[Product Gap] Add production OIDC/JWT identity federation with tenant-scoped authorization #314

Buyer-visible outcome

Allow Clearfolio to run as a production standalone service or modular MSA component behind a standards-based identity boundary without relying on a deployment-specific shared tenant-claims HMAC secret as the only production authentication mechanism. Enterprises must be able to bind authenticated issuer/subject/audience claims to Clearfolio tenant and least-privilege permissions while preserving same-tenant concealment, signed artifact delivery, audit pseudonymization, and host independence.

Current protected-main boundary

Protected main currently supports signed tenant-claim headers validated with HmacSHA256 when clearfolio.tenant-claims.hmac-secret is configured. ProductionAuthReadinessConfig requires the production profile to configure that secret, and Draft #313 is independently hardening its minimum key length.

That shared-secret gateway mode remains useful as a bounded deployment adapter, but it is not a complete provider-neutral enterprise federation story. Current documentation already marks production identity integration as incomplete. This issue owns the production identity/federation contract; it must not duplicate #313's HMAC key-length guard, #270/#268's tenant/object authorization, or artifact-token authority.

Standards baseline

Use stable final standards as normative authority and drafts only as watch items:

• OpenID Connect Core 1.0 Final: authenticate users and validate signed identity claims including iss, sub, aud, expiry and nonce where applicable.
• RFC 8725, JSON Web Token Best Current Practices: explicitly constrain accepted algorithms; validate issuer/audience and application-specific token rules; never accept algorithm confusion or token-type substitution.
• RFC 9700, OAuth 2.0 Security Best Current Practice: use audience-restricted tokens and current OAuth security guidance; authorization-code clients use PKCE according to the applicable client profile.
• RFC 9068 may be supported when the deployment chooses JWT access tokens, but Clearfolio must not assume every OAuth access token is a JWT.

A host-provided opaque token adapter may remain possible if it produces the same verified internal identity contract and preserves the trust boundary.

Provider-neutral identity architecture

Introduce an explicit versioned identity_verifier port that resolves untrusted bearer/session input into an immutable internal tenant_context. Keep provider-specific discovery/JWK/token/introspection behavior behind adapters.

Suggested logical components:

• identity_verifier
• oidc_identity_adapter
• jwt_access_token_adapter
• optional opaque_token_adapter
• issuer_trust_policy
• tenant_role_mapping
• identity_key_snapshot
• authorization_audit_event

Database objects, if introduced, use descriptive two-or-more-word snake_case. Do not create a database solely for this feature; static/config-backed mappings are acceptable where operationally sufficient and testable.

Verification contract

For signed JWT/OIDC tokens, fail closed unless all configured requirements pass:

• exact trusted issuer;
• exact intended audience/resource server;
• explicit allowed signature algorithms; never derive the allowed set from the token itself;
• signature against current trusted key material;
• exp, nbf and bounded clock-skew handling;
• stable subject identity;
• token/type/profile-specific required claims;
• tenant mapping and permission/role mapping through server-owned policy;
• issuer/key rotation with bounded cache lifetime and deterministic recovery;
• no acceptance of unsigned alg=none, algorithm confusion, unexpected symmetric/asymmetric substitution, unknown issuer, wrong audience, stale/revoked key, malformed claim types or duplicate/ambiguous critical claims.

OIDC login/session flows additionally require the flow-specific state/nonce/PKCE and redirect-URI protections owned by the host/client role. If Clearfolio acts only as a resource server for a deployment, do not implement browser login flows unnecessarily.

Tenant and authorization invariants

• token identity never directly supplies arbitrary Clearfolio permissions without a server-owned mapping policy;
• one external identity may map to multiple tenant memberships only through explicit server configuration/data;
• a tenant/role mapping change is auditable and cannot retroactively mutate immutable historical audit identity;
• same-tenant object checks remain in Clearfolio after authentication;
• cross-tenant and missing-object concealment remains unchanged;
• signed artifact-token integrity/expiry/revocation/checksum/read-audit authority remains separate from identity authentication;
• service-to-service identities and human-user identities may use different trusted issuer/policy profiles but converge on the same tenant_context contract.

Key/discovery/introspection security

• discovery and JWK endpoints are explicit trusted issuer configuration, not arbitrary URLs derived from untrusted tokens;
• outbound identity-provider traffic uses the repository/host's reviewed egress security boundary and bounded response/time/cache limits;
• reject TLS/destination/issuer mismatches and unbounded redirects;
• key rotation must not silently accept a token signed by an evicted/untrusted key;
• remote provider failure produces controlled authentication unavailability, not unsigned fallback;
• secrets/client credentials are stored in approved secret-management/KMS boundaries and never in logs/model prompts/public error payloads.

Migration / compatibility

Preserve the current signed-HMAC gateway mode as a versioned adapter while deployments migrate. Do not silently reinterpret existing headers as OIDC/JWT authority.

Migration must define:

1. configure trusted issuer/audience/policy;
2. run dual-mode compatibility tests without accepting the same request through a weaker fallback;
3. migrate clients/gateway;
4. observe authentication/authorization failure rates and tenant mappings;
5. disable legacy shared-secret mode for deployments that choose federation;
6. rollback only if it does not reopen a known authorization weakness.

Test-first acceptance

Create RED regressions before implementation for at least:

• valid issuer/audience/signature/expiry success;
• wrong issuer;
• wrong/missing/multi-audience handling according to policy;
• disallowed/none/algorithm-confusion cases;
• expired, future nbf, malformed time claims and bounded skew;
• unknown/stale/rotated key;
• discovery/JWK outage, malformed JWK and oversized responses;
• tenant membership absent, wrong tenant and permission mapping denial;
• service/user issuer-profile separation;
• cross-tenant object concealment after successful authentication;
• artifact-token authority still independently enforced;
• concurrent JWK refresh and key-rotation races;
• restart/cache recovery;
• migration from current HMAC gateway adapter without weak fallback;
• exact 100% owned production line/statement and branch coverage and complete public Javadocs/docstrings.

Run exact-head CI, Security Scan, SAST, fuzz/property tests where applicable, dependency/SBOM/provenance validation, independent review and repository protection before integration.

Observability and privacy

Expose privacy-safe low-cardinality evidence such as verifier profile, controlled failure category, key-refresh outcome and issuer-profile health. Do not put raw issuer token, subject, tenant, email, claims JSON, bearer token, JWK content or arbitrary provider error text into metrics/logs.

Pseudonymous audit identity remains personal data and follows the repository's purpose/key-separation and retention policy.

Documentation / acquisition updates

Update the canonical PRD/TRD/Architecture, ADRs, UML, DATA_MODEL, API contract, Security/Threat Model, Test Strategy, Operability, Migration/Rollback, Traceability, Acquisition Diligence and CHANGELOG with truthful maturity.

This issue is a production identity integration gap, not a certification claim. Deployment-specific IdP configuration, customer identity governance and legal/privacy assessment remain external evidence where applicable.

Dependency order

Do not create a conflicting source branch while #270/#268 or #313 actively owns overlapping authentication/configuration paths. Re-evaluate the stable protected baseline first, then implement the smallest provider-neutral identity verifier slice.