Skip to main content

Overview

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

Bootstrap-specific identity seam:

  • jhf-spindle owns who a person is, whether the person is eligible, and which business role/profile is authoritative
  • jhf-heddle owns how that upstream truth becomes technical claims, sessions, revocation posture, admitted OIDC client posture, and JML/access-projection hooks
  • helpifyr-fabric owns policy admission, projection correlation, and deny-on-conflict posture
  • downstream repos may consume Heddle contracts and readbacks, but must not mint local replacement identity truth

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 the owner-supplied runtime host

Release-eligibility posture:

  • bounded public release surfaces are tracked in contracts/admission/release_surface_inventory_v1.json
  • repository history admission remains pending in contracts/admission/repository_publication_history_posture_v1.json
  • the non-destructive owner decision is documented in docs/FILTERED_PUBLICATION_DECISION.md
  • active owner blocker: JaddaHelpifyr/jhf-heddle#329
  • operator-only host/runbook details remain explicit but excluded from the current public release-candidate set
  • repo-owned history evidence now runs through python scripts/verify_repository_history_posture.py and currently proves filtered_publication_required
  • the selected owner-side remediation is filtered publication from exact main, not canonical history rewrite

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

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