Authority DPoP + mTLS Rollout Plan (Sprint 100)

Last updated: 2026-05-30 (reconciled against src/Authority implementation)

This is the rollout plan and reference for sender-constrained tokens in the Stella Ops Authority service: DPoP proof-of-possession and mutual-TLS (mTLS) binding. It is written for Authority and Security Guild engineers driving the rollout, and for operators wiring the config, telemetry, and alerts. The phase checklists below track delivery state; the Verification Matrix, Telemetry, and config tables double as the operational reference once a phase ships.

See also: authority-scopes.md, authority-threat-model.md, and the Authority module docs under docs/modules/authority/.

Objectives

Enforce DPoP sender constraints (AUTH-DPOP-11-001).
Bind high-assurance clients/audiences to mTLS tokens (AUTH-MTLS-11-002).
Provide telemetry + runbooks so plugins (SEC2/SEC3/SEC5) can validate enforcement without regressions.

Implementation note: sender-constraint enforcement is per-client and per-audience, not per-tenant. A client opts into DPoP/mTLS via its senderConstraint property (see etc/authority.yaml), and DPoP/mTLS can additionally be forced for configured audiences (security.senderConstraints.dpop.nonce.requiredAudiences and security.senderConstraints.mtls.enforceForAudiences, defaults signer/attestor and signer).

Phase 1 · Config & Telemetry

[x] Extend etc/authority.yaml with the security.senderConstraints.dpop section. Bound options are enabled, allowTemporaryBypass, proofLifetime (default 2m), allowedClockSkew (default 30s), replayWindow (default 5m), allowedAlgorithms (default ES256, ES384), and a nested nonce block (enabled, ttl default 10m, maxIssuancePerMinute default 120, store, redisConnectionString, requiredAudiences default signer/attestor). Source: StellaOps.Configuration.AuthorityDpopOptions / AuthorityDpopNonceOptions. The .NET binding path is Authority:Security:SenderConstraints:Dpop.
[x] Emit DPoP audit events through IAuthEventSink. The event types are authority.dpop.proof.valid, authority.dpop.proof.challenge, authority.dpop.proof.bypass, authority.dpop.proof.disabled, and authority.dpop.proof.error (see ValidateDpopProofHandler). Each carries sender.constraint=dpop plus, when available, dpop.jkt (key thumbprint), dpop.jti, dpop.issued_at, dpop.audience, dpop.reason_code, and (sensitive) dpop.nonce.presented / dpop.nonce.issued. There is no single authority.dpop.request log line; reconcile dashboards to the per-outcome event types above.
[x] Add the IDpopNonceStore abstraction. Implementations: InMemoryDpopNonceStore (Testing / local harness), MessagingDpopNonceStore (Valkey-backed, production durable path wired by AddAuthorityDpopRuntime), RedisDpopNonceStore (legacy alias), and DisabledDpopNonceStore (DPoP off). Outside Testing, when DPoP is enabled AddAuthorityDpopRuntime requires Authority:Security:SenderConstraints:Dpop:Nonce:Store=valkey (or the redis legacy alias) and a non-empty RedisConnectionString, otherwise startup throws.
[x] Integration tests live in StellaOps.Authority.Tests/OpenIddict/ClientCredentialsAndTokenHandlersTests.cs. Relevant cases include ValidateDpopProof_AllowsSenderConstrainedClient, ValidateDpopProof_RequiresSenderConstraint_WhenAudienceMatchesConfiguration, ValidateDpopProof_IssuesNonceChallenge_WhenNonceMissing, and ValidateDpopProof_AllowsBypass_WhenEnabled. (The previously-cited AuthorityTokenTests.DPoPNonceRequired / AuthorityTokenTests.DPoPMustMatchCnF classes do not exist.)

Phase 2 · Enforcement & Fallback

[x] Reject /token requests lacking a DPoP proof when the client’s senderConstraint is dpop or the requested audience matches nonce.requiredAudiences. ValidateDpopProofHandler rejects with OpenIddict error invalid_client and emits a WWW-Authenticate: DPoP error="invalid_dpop_proof" (or error="use_dpop_nonce" for a nonce challenge) header; nonce challenges also set the DPoP-Nonce response header.
[x] Persist cnf.jkt (DPoP) / cnf["x5t#S256"] (mTLS) on issuance and re-attach the cnf claim during token and introspection validation so downstream services validate the sender. The DPoP key thumbprint is stored in AuthorityTokenDocument.SenderKeyThumbprint; the cnf claim is applied by AuthoritySenderConstraintHelper / EnsureSenderConstraintClaims (TokenValidationHandlers).
[x] Add emergency bypass flag (security.senderConstraints.dpop.allowTemporaryBypass) for sealed recap drills; default disabled. AddAuthorityDpopRuntime restricts this flag to Development/Testing local harnesses — enabling it in any other environment throws at startup.
- When enabled, Authority emits the authority.dpop.proof.bypass audit event (outcome Success, dpop.reason_code=bypass), sets the authority.dpop_result=bypass and authority.sender_constraint=dpop_bypass request tags, and issues tokens without a sender constraint (the SenderConstraintProperty is left unset, so no cnf is attached) so downstream services know sender constraints were relaxed. Reset immediately after the drill.

Phase 3 · mTLS Binding

[x] Validate the presented client certificate on /token (client_credentials and refresh grants) when the client’s senderConstraint is mtls or the audience matches mtls.enforceForAudiences, then store the SHA-256 hex thumbprint in AuthorityTokenDocument.SenderCertificateHex (persisted as the sender_cert_hex token property in PostgresTokenStore). The certificate is checked against the client’s registered CertificateBindings (thumbprint, subject, serial, issuer, SANs, validity window with rotationGrace) plus optional CA allow-list, subject patterns, and SAN-type rules (AuthorityClientCertificateValidator).
[x] Re-validate the certificate hash on the /token and /introspect endpoints: EnsureMtlsBinding (TokenValidationHandlers) compares the presented cert hash against SenderCertificateHex and rejects with invalid_token on mismatch, incrementing authority_mtls_mismatch_total.
[ ] Document bootstrap/rotation in docs/modules/authority/AUTHORITY.md+ docs/security/dpop-mtls-rollout.md (this file).

NOT VERIFIED IN CODE: this plan previously claimed cert-hash validation on a /fresh-auth endpoint. Authority’s MtlsValidationHandler only runs for the Token and Introspection endpoints (OpenIddictServerEndpointType.Token/Introspection in TokenValidationHandlers); there is no Authority /fresh-auth token endpoint that performs sender-certificate validation. “Fresh auth” in Authority is a Console concept (the stellaops:fresh_auth claim + a 300s window enforced by StellaOpsScopeAuthorizationHandler for obs:incident and pack-approval scopes), unrelated to mTLS binding. Drop the /fresh-auth reference or confirm a planned endpoint before re-asserting it.

Verification Matrix

Scenario	Test/Command	Expected
DPoP required, proof missing	`ValidateDpopProof_IssuesNonceChallenge_WhenNonceMissing` (in `ClientCredentialsAndTokenHandlersTests`)	Rejected with `invalid_client`; `WWW-Authenticate: DPoP error="use_dpop_nonce"` and a `DPoP-Nonce` header; `authority_dpop_nonce_miss_total` increments.
Nonce missing/expired/invalid	`ValidateDpopProof_RequiresSenderConstraint_WhenAudienceMatchesConfiguration` + nonce-consume paths	Nonce challenge reissued (`nonce_missing` / `nonce_expired` / `nonce_invalid` reason codes); audit event `authority.dpop.proof.challenge`.
mTLS cert missing	`ValidateAccessTokenHandler_Rejects_WhenMtlsCertificateMissing`	`invalid_token`; `authority_mtls_mismatch_total{reason="missing_certificate"}` increment.
mTLS cert mismatch	`ValidateAccessTokenHandler_Rejects_WhenMtlsCertificateMismatch`	`invalid_token`; `authority_mtls_mismatch_total{reason="thumbprint_mismatch"}` increment.
Bypass enabled	`ValidateDpopProof_AllowsBypass_WhenEnabled`	Not rejected; no `cnf`; `authority.dpop.proof.bypass` audit event.

The --filter-style invocation above does not run with this repo’s test host; MTP ignores --filter. Run targeted cases via the test .exe runner against StellaOps.Authority.Tests rather than dotnet test --filter.

Telemetry & Alerting

Metrics: authority_dpop_nonce_miss_total and authority_mtls_mismatch_total. Both carry a reason tag. The mTLS mismatch reasons emitted by RecordMtlsMismatch are context_missing, missing_certificate, and thumbprint_mismatch (underscores, not hyphens). The DPoP nonce-miss reasons include missing_proof, invalid_proof, invalid_key, nonce_missing, nonce_expired, and nonce_invalid.
Audit events (via IAuthEventSink, not a single log line): authority.dpop.proof.valid / .challenge / .bypass / .disabled / .error. Per-request OpenTelemetry tags include authority.sender_constraint and authority.dpop_result. (The previously-cited authority.security.senderConstraint structured log does not exist.)
Alerts: Page DevOps when nonce miss > 5% or mTLS mismatches > 0 over 10 min.

Dependencies

Authority Core & Security Guild owners.
DevOps to provide sealed-mode CI coverage (DEVOPS-AIRGAP-57-002).
Plugin Standard Guild to consume new telemetry once rolled out.

Communication

Daily async update in #guild-authority thread referencing this plan.
Link this document from docs-archive/implplan/SPRINT_0100_0001_0001_identity_signing.md notes once Phase 1 merges.