Skip to main content

jhf-heddle Overview

Documentation Map​

jhf-heddle Overview

jhf-heddle is the technical identity infrastructure layer for the Helpifyr SSO program.

It owns:

  • Keycloak runtime and realm configuration
  • OIDC/OAuth2 client registration patterns
  • technical token and session surfaces
  • canonical identity-claim language and SSO posture
  • service-account and agent-identity technical setup
  • health, drift, backup, restore, and rotation contracts

It does not own:

  • business identities and business role truth
  • final authorization policy decisions
  • work ownership claims and leases
  • a second user/role system outside the identity architecture

Cross-repo role separation:

  • jhf-spindle: business identity and account binding source of truth
  • jhf-heddle: IdP and technical auth infrastructure
  • helpifyr-fabric: policy decision, deny-on-conflict, audit correlation
  • jhf-keystore: read-only consumer of the canonical claim language, never a local identity-truth owner
  • jhf-pattern: project and workspace business truth that must flow to consumers through Fabric rather than direct runtime reads

Implemented repository baseline:

  • runtime bootstrap via compose.yaml
  • environment contract via .env.example
  • realm bootstrap via config/keycloak/realms/helpifyr-template.json
  • downstream client template via config/clients/client-template.yaml
  • Plane OSS client bootstrap via config/clients/plane-openclaw-client-template.yaml
  • versioned claim contract via config/identity/claim-vocabulary.v2.yaml
  • technical sync consumer template via config/sync/technical-sync-consumer-template.yaml
  • Fabric Plane unified-access consumer template via config/fabric/plane-unified-access-consumer.yaml
  • runbooks for bootstrap, backup/restore, and secret rotation

Verification surfaces:

  • scripts/verify-realm-export.ps1 validates the repo-owned realm export baseline
  • scripts/validate-technical-sync-surface.py validates that the consumer/client templates stay import-only and deny-oriented
  • scripts/validate-identity-claim-vocabulary.py validates the canonical claim language, its spindle binding, and live Fabric identity contract posture
  • scripts/verify-runtime-guardrails-v1.py and scripts/verify-runtime-materialization-drift.py are the canonical live execution paths against <internal-runtime-redacted>

Base docs family for the v1.6 docs platform rollout:

License: AGPLv3
Project: https://helpifyr.com