Skip to main content

Architecture

Documentation Map​

Architecture

Repository Boundary​

jhf-heddle is an IdP and OIDC infrastructure repository.

Allowed responsibilities:

  • run and configure Keycloak
  • define technical clients, scopes, and protocol mappers
  • expose health and drift surfaces
  • document session, revocation, and logout semantics
  • provide reproducible bootstrap and operations guidance

Explicitly out of scope:

  • business identity ownership
  • business role authoring
  • direct runtime user provisioning for downstream tools
  • policy evaluation
  • launcher or application-specific authorization logic

Identity Types​

The system model keeps these identity types separate:

  • human_user
  • service_identity
  • ai_agent
  • human_team
  • human_department
  • breakglass
  • bootstrap

Rules:

  • machine or agent identities are never modeled as normal users
  • delegated execution must preserve acting_agent
  • on_behalf_of appears only for delegated chains outside this repository's token issuance profile
  • technical existence in the IdP does not imply business authorization

Modes​

identity_mode=standalone​

  • downstream tools may use reduced local auth
  • no central SSO guarantee
  • no implicit cross-tool trust
  • useful for local development and break-glass situations only

identity_mode=federated​

  • central IdP is mandatory
  • downstream tools become OIDC consumers
  • audience and scope checks are strict
  • policy and audit decisions happen outside the IdP layer

Token and Session Rules​

  • access token target TTL: 5 minutes
  • refresh/session target TTL: 8 hours
  • mutating actions must include revocation-aware checks downstream
  • wrong aud: immediate deny
  • empty or missing required scope: immediate deny
  • stale or ambiguous tenant binding: immediate deny
  • breakglass sessions are explicitly time-bounded and fail-closed on expiry without privileged carryover
  • bootstrap sessions are explicitly temporary and fail-closed on deactivation without privileged carryover
  • breakglass claims for downstream consumers require explicit projection allowance and must fail-closed on stale, blocked, or widened scope attempts
  • post-expiry revocation and session kill must be deterministic; residual sessions after expiry are incident-class and fail-closed
  • disable/delete transitions are terminal and stackwide fail-closed: no lingering active sessions and no local reactivation bypass

Technical Mapping Flow​

The architecture assumes this chain:

Business role in spindle -> technical group/role in Keycloak -> policy decision in fabric

jhf-heddle owns only the middle technical translation surface.

For Plane-facing human access the chain is stricter:

Spindle human eligibility/governance facts -> Pattern workspace/project/membership facts -> Fabric plane-unified-access projection -> jhf-heddle technical client and session posture

jhf-heddle must not read Spindle or Pattern directly for Plane login posture. Plane-facing technical markers and login gates must come only from Fabric's unified projection.

For agent identities the chain is stricter:

Spindle agent registry -> Warp runtime/delegation posture -> Fabric agent federation projection -> jhf-heddle technical reconcile

jhf-heddle must consume the Fabric projection read-only and must not invent a second agent catalog or delegation truth family.

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