Auth Governance Platform Documentation

This is the single, unified documentation for governance and authorization across the platform.

Purpose

Describe how access governance is implemented end-to-end, including identity, hierarchy, policy evaluation, contract boundaries, gateway exposure, auditability, and release controls.

Platform scope

• IAM identity and internal verification surface.
• Hierarchy/DAG context used for node-scoped authorization.
• Access-policy decisioning (RBAC + ABAC) and policy administration.
• Config-resolver orchestration of governance dependencies.
• Kong internal/public route exposure for governance-related APIs.
• Decision trace and break-glass governance evidence.
• Session facility context: IAM/BFF SHOULD expose a stable hierarchy nodeId (e.g. contextNodeId) for Config Resolver callers; see IAM SPEC §7 and config-resolver SPEC §8.
• Tenant branding vs resolver tokens: Precedence when both apply is defined in config-resolver SPEC §8 and Tenant SPEC (TenantConfiguration note).

Core architecture

Services and responsibilities

• apps/services/iam: user identity, verification, internal lookup APIs.
• apps/services/hierarchy: DAG nodes, ancestry, membership context.
• apps/services/access-policy: access evaluation, context, roles, permissions, policies.
• apps/services/config-resolver: effective config and governance dependency integration.
• apps/services/config-resolver: effective config and governance dependency integration. It orchestrates licensing, flags, role expansion, and UI/tokens, and calls Access Policy’s POST /internal/access/evaluate for ABAC. It does not replace Access Policy as the system of record for authorization decisions (see config-resolver AS_BUILT_AND_ROADMAP §2).
• apps/services/platform-admin: feature flags and bootstrap controls.
• apps/services/terminology: terminology contracts used by governed clinical flows.

Governance contract principles

• Internal contracts are explicit and versioned through shared types.
• Access evaluation requires explicit actor and tenancy context.
• No compatibility facade layer for core governance contracts.
• Contract changes require synchronized producer/consumer updates and tests.

Access governance flows

Authentication and service trust

• Identity is established via JWT and validated in service guards.
• Internal routes are network-restricted at Kong policy level.
• Service-to-service calls rely on explicit internal contract paths.

Authorization lifecycle

1. Caller submits access intent with tenancy and subject context.
2. Access-policy evaluates action/resource with role and policy context.
3. Response includes decision metadata (decisionTraceId, evaluatedAt).
4. Downstream handler proceeds only on allow.
5. Audit and governance evidence is emitted/persisted for governed operations.

End-to-end data flow

Break-glass governance

• Break-glass request context is accepted in evaluate inputs.
• Governance evidence (reason, TTL, step-up metadata, trace linkage) is persisted.
• Schema-backed storage is implemented via break_glass_events.

Contract and route alignment status

Access Policy: licensing vs orchestration

• When LICENSING_INTERNAL_URL (or LICENSING_URL) is set, the Access Policy service performs a node-scoped module entitlement check inside evaluate() (via GET /internal/licenses/check) before RBAC and ABAC policy rules. Resource types map to module keys in apps/services/access-policy/src/resource-module-map.ts.
• When licensing is not configured (common in local dev), evaluate() relies on DENY/ALLOW policies + RBAC only. Config Resolver still orchestrates licensing, flags, and POST /internal/access/evaluate in full platform flows; any direct caller of Access Policy must enforce licensing at the boundary if this service runs without a licensing URL.
• Hierarchy: role assignments match the resource node or any ancestor (GET /internal/hierarchy/nodes/:nodeId/ancestors), implemented by HierarchyClient in access-policy.

Governance-related contract backlog is closed.

• Q1 foundational contract alignments are completed.
• Q2 implementation items (break-glass persistence, bootstrap endpoint drift, allergies internal mapping) are completed.
• Q3 closure items (terminology internal contract path, facade removal, gateway policy checks) are completed.

Gateway policy model (Kong)

• Required governance internal surfaces are mapped and tested in both:
  • infra/kong/kong.yml
  • infra/kong/kong.dev.yml
• Deprecated/stale governance paths are explicitly blocked by declarative checks.
• Dev/prod policy deltas are explicitly asserted and controlled.

Personas and access posture

Persona	Typical Role Keys	Access Characteristics	Governance Controls
Platform Operator	SUPER_ADMIN, platform admin roles	Cross-tenant configuration and oversight operations	Explicit high-privilege permissions, audited admin actions
Tenant Admin	TENANT_ADMIN	Tenant-scoped governance and user/role administration	Tenant boundary enforcement, audited role/policy changes
Clinical Provider	PHYSICIAN, NURSE, clinical roles	Patient-care actions in assigned node/facility scope	License gate, role grants, ABAC evaluate, minimum-necessary
Compliance/Auditor	AUDITOR	Read-focused oversight and evidence review	Read-only policy, audit export controls, no write privileges
Emergency Override Actor	Assigned clinical role + approved break-glass path	Temporary elevation for urgent care scenarios	Reason taxonomy, TTL, step-up metadata, persisted evidence

Access evaluation matrix (practical)

Check Stage	Input Signals	Decision Rule	Outcome on Fail
Identity validation	JWT subject, tenant, signature	Token must be valid and service-trusted	Deny request
Module entitlement	moduleKey, nodeId	Module must be active for node scope/inheritance	Deny request
Feature flag	featureKey, tenantId	Feature must evaluate enabled	Deny request
Role/permission baseline	user roles + role grants	Required action/resource permission must exist	Preliminary deny
Policy evaluate (/internal/access/evaluate)	userId, tenantId, action, resourceType, nodeId, governance fields	ABAC/RBAC policy result is authoritative for governed action	Deny with trace
Explicit override layer	user-node override records	Valid explicit allow/deny may override baseline within scope	Apply override result
Break-glass governance	reason, TTL, step-up metadata	If enabled, evidence must be captured with trace linkage	Reject or deny based on policy/validation
Audit evidence	decision trace + action metadata	Governed action must emit traceable evidence	Release gate failure / control violation

Break-glass lifecycle flow

Verification and release controls

• Governance contract assertions are enforced by declarative Kong tests.
• Targeted client/provider tests exist for high-risk governance contracts.
• Release gates require contract integrity and decision-trace consistency for governed actions.

Canonical references outside this document

• Baseline architecture: specs/architecture/baseline/ARCHITECTURE_BASELINE.md
• Security/compliance: specs/architecture/platform/COMPLIANCE_SECURITY.md
• Module-level specs: specs/modules/

Current status

Auth governance alignment is complete at the architecture/documentation level in this repository.

For module-specific resolver behavior and concrete examples, see specs/modules/config-resolver/CONFIG_MODEL.md.