DcsvIo.D2.Auth.Abstractions 0.1.1

DcsvIo.D2.Auth.Abstractions

Identity / authorization vocabulary AND consumer-side runtime contracts — the value types, string constants, and read-only interfaces every consumer references when reasoning about auth. Domain layers, request-context, handler/abstractions, host-supplied JWT runtime, and issuer-side code all reference this slice; impls live in host-supplied runtime libs.

The runtime piece (AddD2Auth, JWT validation, JWKS HTTP fetcher, session liveness tracker impl) is host-supplied — those impls satisfy the IJwksProvider and ISessionLivenessTracker contracts defined here. HTTP-transport binding (middleware + ProblemDetails) and gRPC-transport binding (server-side interceptor + RpcException trailers) are likewise host-supplied. Domain code never references any of the runtime libs — only this abstractions slice.

Install

dotnet add package DcsvIo.D2.Auth.Abstractions

Types (source map)

The Generated/ directory is tracked in git and contains the SourceGen-emitted output — committed for inspection, IDE navigation, and PR diff review. Files are re-emitted on every dotnet build from the spec contracts; never hand-edit. The *.g.cs glob is marked linguist-generated=true in .gitattributes so GitHub PR UI collapses these diffs by default.

Public API surface

ActorKind + ImpersonationKind — RFC 8693 / RFC 6749 §4.4 token taxonomy

ActorKind.Service           // act entry is a service identity (RFC 6749 §4.4 client_credentials)
ActorKind.Impersonation     // act entry is a user impersonating another user

ImpersonationKind.Consent   // OTP-authorized impersonation (staff + admin orgs)
ImpersonationKind.Force     // silent impersonation (admin orgs only, dev/support fallback)

Token shape (derived from act chain):

OrgType / Role enums

Used as typed properties on IAuthContext (auth/context-abstractions). Wire format: lowercase string in JWT claims (d2_org_type, d2_org_role). The codegen-emitted MutableRequestContext.FromClaims(...) handles parse / format.

The JWT carries a single org context — during impersonation, the JWT's org claim is the impersonated user's org. The agent's own org is recorded inside the act chain for audit and for authz rules that key on the agent's home org.

ActorEntry record

public sealed record ActorEntry(
    ActorKind Kind,
    string Subject,                            // act.sub — user id (Impersonation) or service client_id (Service)
    string? ClientId = null,                   // when Service: OAuth client_id (often == Subject)
    ImpersonationKind? ImpersonationKind = null,  // when Impersonation: Consent or Force
    Guid? SessionId = null,                    // when Impersonation: act.d2_session_id (the impersonation session, distinct from the user's own session)
    Guid? OrgId = null,                        // when Impersonation: act.d2_org_id — the agent's own org
    string? OrgName = null,                    // when Impersonation: act.d2_org_name
    OrgType? OrgType = null,                   // when Impersonation: act.d2_org_type
    Role? OrgRole = null,                      // when Impersonation: act.d2_org_role — agent's role in their own org
    ActorEntry? Act = null);                   // RFC 8693 §2.1 nested chain

IAuthContext.ActorChain exposes this as IReadOnlyList<ActorEntry> for ergonomic enumeration. Each entry's Act field walks the nested chain when delegation-of-delegation occurs (e.g. Edge → Notifications → Files all carrying user identity).

The four Org* fields on Impersonation entries carry the agent's own organizational context — useful for audit ("Alice from Customer Support impersonated Bob") and for authz rules that key on the agent's home org. IAuthContext exposes these as derived top-level convenience properties (ImpersonatorOrgId, ImpersonatorOrgName, ImpersonatorOrgType, ImpersonatorOrgRole) — null when not impersonating.

Constant classes

JwtClaimTypes.SUB                          // "sub"
JwtClaimTypes.SCOPE                        // "scope"
JwtClaimTypes.ACT                          // "act"
JwtClaimTypes.CLIENT_ID                    // "client_id"      (RFC 8693 §4.3 / RFC 9068 §2.2)
JwtClaimTypes.SESSION_ID                   // "d2_session_id"
JwtClaimTypes.ORG_ID                       // "d2_org_id"
JwtClaimTypes.ORG_ROLE                     // "d2_org_role"
JwtClaimTypes.ACT_KIND                     // "d2_kind"        (lookup path: act.d2_kind)
JwtClaimTypes.ACT_SESSION_ID               // "d2_session_id"  (lookup path: act.d2_session_id)
// ... plus more

// Wire-protocol header constants live in the per-transport catalogs
// (DcsvIo.D2.Headers.{Common,Http,Amqp,Grpc}). See ../README.md § Libraries
// for the full per-transport enumeration.

Scopes.Self.Read                           // "self.read"   (codegen-emitted)
Scopes.Auth.Password.Change                // "auth.password.change"
// (full catalog lives in contracts/auth-scopes/scopes.spec.json)

WellKnownAudiences.D2_INTERNAL_AUDIENCE    // "d2.internal" (hand-declared, NOT spec-derived —
                                           //  the universal internal receive audience every hop validates)

RequestOrigin + CallPath — local establishment facts vs propagated telemetry

What kind of trust boundary produced the current request hop's context, and what sequence of hops the request has traversed so far, are two structurally distinct kinds of fact:

RequestOrigin.Unestablished    // no boundary has positively established this yet — fail-closed
RequestOrigin.EdgeInbound      // the external HTTP boundary; starts the call-path
RequestOrigin.CrossProcessHop  // a gRPC hop authenticated by a validated mTLS client certificate
RequestOrigin.InProcessModule  // an in-host module call through the generated I<Module>Api leaf
RequestOrigin.System           // an in-host background worker with no inbound user request

CallPathKind.Edge          // external HTTP / API-gateway inbound boundary (public enum member name)
CallPathKind.WorkloadHop   // a cross-process mTLS-authenticated hop
CallPathKind.ModuleHop     // an in-process module hop
CallPathKind.System        // an in-host system worker

IRequestContext.Origin and its paired ImmediateCaller are never propagated — every establishment boundary (the Edge-inbound HTTP middleware, the cross-process gRPC interceptor, the in-process-module boundary, the System-worker bootstrap — all in DcsvIo.D2.Context.Abstractions

• the transport-binding libs) recomputes both fresh from its own local, unforgeable transport evidence every hop. RequestOrigin.Unestablished (the enum's zero member) is the scoped default, so a context no boundary has touched fails closed by construction — a host capability authority that consumes RequestOrigin denies rather than assume a plane.

CallPath (IReadOnlyList<CallPathEntry>) is the opposite shape on purpose: it DOES propagate on x-d2-context (depth-bounded — see CallPathOps in DcsvIo.D2.Context.Abstractions), accumulating each hop's own CallPathEntry as the request travels. It is operational telemetry only — authority code never takes a CallPath parameter.

Forwarded-JWT credential — ForwardedJwt + IForwardedJwtAccessor

The in-process realization of the forward-unchanged rule — how a hop holds the forwarded transaction-token so it can re-attach it outbound.

// Smart constructor — validates a blank credential away; NO JWT-format re-check
// (the token is already validated at the capture site).
D2Result<ForwardedJwt> result = ForwardedJwt.Create(rawBearer);

// THE sole reveal seam — the only path to the raw bytes (used by the outbound
// forwarding credential). Throws on an empty wrapper.
string raw = forwardedJwt.RevealForForwarding();

// Unloggable by construction — every log/serialization path yields the placeholder.
forwardedJwt.ToString();                   // "[REDACTED: ForwardedJwt]"
// {@x} destructuring → "[REDACTED: SecretInformation]" via the [RedactData] policy.

// Request-scoped holder — populated by the inbound auth surface, read by the
// outbound forwarding credential. Registered by AddD2AuthHttp() + AddD2AuthGrpc().
ForwardedJwt? current = accessor.Current;
accessor.Capture(rawBearer);

Four-layer never-logged guarantee (proven by tests, not asserted): self-redacting (ToString + [RedactData] + private backing field), single reveal seam (RevealForForwarding), enrichment-isolated (held off IRequestContext, so the request-context enricher cannot reach it), and never a [LoggerMessage] parameter.

Dependencies

• DcsvIo.D2.Result — D2Result<T> returns on the consumer-side contracts (IJwksProvider, ISessionLivenessTracker) and ForwardedJwt.Create. Transitively re-exposes ErrorCategory (used by ForwardedJwt.Create's generic ValidationFailed).
• DcsvIo.D2.I18n.Abstractions — TKMessage parameters via D2Result.Messages / InputErrors shape.
• DcsvIo.D2.Utilities — [RedactData] + RedactReason for the ForwardedJwt redacting wrapper, and ToNullIfEmpty() for its smart constructor. A leaf (references only result/i18n), so no cycle.
• Microsoft.IdentityModel.Tokens — SecurityKey type used on JwksKeySetSnapshot.Keys. The de-facto BCL-adjacent abstraction (ASP.NET Core's TokenValidationParameters.IssuerSigningKeys takes it; ConfigurationManager<OpenIdConnectConfiguration> emits it). No deeper abstraction layer adds value here.
• Analyzer-only project references to DcsvIo.D2.Auth.Scopes.SourceGen and DcsvIo.D2.Auth.Audiences.SourceGen for the codegen output.

The package carries the consumer-side runtime contract surface — interfaces + result-shaped types — but no impl logic. Consumer-side runtime libs and Edge's issuer-side code both target these contracts.

Design notes

Why d2_ prefix on custom claims

Custom JWT claims are namespaced with the d2_ prefix to avoid future spec collisions. Standard OAuth / OIDC claims (sub, aud, iat, exp, azp, scope, act) keep their canonical names because they're spec-defined.

Why act chain is recursive

RFC 8693 §2.1 defines the actor claim recursively: { "sub": "...", "act": { "sub": "...", "act": { ... } } }. Each link represents one delegation / impersonation step. Flat-list modeling would lose audit fidelity for multi-hop scenarios (e.g. Edge service forwards an impersonation token through Notifications onto Files).

Per RFC 8693 §4.1: the outermost act claim represents the current actor; the least recent actor is the most deeply nested. The ActorChainParser flattens to an IReadOnlyList<ActorEntry> ordered outermost-first, so chain[0] is the immediate caller and chain[chain.Count - 1] is the originator (the first service that started the call chain).

⚠ Hard requirement on the auth runtime: preserve nested act whenever a token IS exchanged

RFC 8693 §4.1 leaves it to the AS's discretion whether to preserve nested act history when issuing an exchanged token. Many ASes drop nesting and only carry the immediate caller forward.

This requirement is about what happens when a token exchange occurs — not about exchanging on every hop. Under the forward-unchanged service-to-service model, an ordinary internal hop forwards the edge-minted token byte-for-byte and does not exchange, so its act chain is the one set at the boundary mint and is left untouched the whole way down. The chain is established (or extended) only where an exchange genuinely happens: the single boundary mint at the edge, and the deliberate exception cases token exchange is retained for — most relevantly impersonation, which adds an actor entry. (The chain therefore does not grow link-by-link as a request descends the call graph; it is set once at the mint and forwarded.)

Whenever the host-supplied auth runtime DOES mint or exchange a token that carries an actor, it MUST preserve the nested act history. Specifically: when an exchange takes a token with act = { sub: B, act: { sub: Edge } } and adds a new actor A, the resulting token's act must be { sub: A, act: { sub: B, act: { sub: Edge } } } — A is added as the new immediate actor and the prior chain is preserved unchanged. Dropping nesting would make IAuthContext.OriginatingClientId unrecoverable beyond the most recent actor and break audit traceability across multi-actor chains.

The exchange-helper API on the auth runtime accepts an optional prior_actor_chain parameter for the callers that forward an existing chain — used only on the exchange path itself (the boundary mint and the retained exception cases), never on an ordinary forward-unchanged hop. (Async consumers do not propagate identity claims via the wire — identity rebuilds from the JWT each sync hop, and the asynchronous path carries only the encrypted operational subset.)

The depth limit lives in DcsvIo.D2.Context.Abstractions.ActorChainParser.MaxActDepth (currently 20). The auth runtime enforces the same limit at mint time so issued tokens never exceed what consumers can parse — a DoS guard on the chain structure, independent of where the chain is established.

Strict-mode parsing of the act chain

DcsvIo.D2.Context.Abstractions.ActorChainParser rejects malformed actor chains by throwing MalformedActorChainException:

• Any entry missing sub (RFC 8693 §2.1 violation)
• Any impersonation entry missing d2_kind / d2_session_id / d2_org_id / d2_org_type / d2_org_role
• Depth exceeds MaxActDepth (DoS protection)
• Invalid JSON or non-object root

Auth middleware MUST catch and convert to D2Result.Unauthorized (HTTP 401) — a malformed actor chain is a signed-token-with-bad-payload condition that should never reach a handler.

Why every constant catalog is codegen-emitted

The scope catalog, audience catalog, JWT claim names, HTTP header names, and in-process slot keys are ALL codegen-emitted from per-topic specs in contracts/. Each spec is a single source of truth that drives BOTH the .NET catalog AND the corresponding TS catalog (where applicable) — cross-language drift is structurally impossible.

• Scopes.g.cs ← contracts/auth-scopes/scopes.spec.json via DcsvIo.D2.Auth.Scopes.SourceGen
• Audiences.g.cs ← contracts/auth-audiences/audiences.spec.json via DcsvIo.D2.Auth.Audiences.SourceGen
• JwtClaimTypes.g.cs ← contracts/jwt-claims/jwt-claims.spec.json via DcsvIo.D2.Auth.JwtClaims.SourceGen
• Http/D2HttpContextItems.g.cs ← contracts/in-process-keys/keys.spec.json via DcsvIo.D2.InProcessKeys.SourceGen
• HTTP / AMQP / gRPC / cross-transport header catalogs ← contracts/headers/headers.spec.json via DcsvIo.D2.Headers.SourceGen (live in their own per-transport csprojs DcsvIo.D2.Headers.{Http,Amqp,Grpc,Common})

Tests

packages/dotnet/tests/Unit/Auth/:

• ActorKindTests.cs / ImpersonationKindTests.cs / OrgTypeTests.cs / RoleTests.cs / ActionSensitivityTests.cs — enum value stability (rename = breaking change gate).
• ActorEntryTests.cs — record equality including nested Act chains; null-Act default; multi-level chain traversal; ImpersonationKind / SessionId only-meaningful-when-Impersonation discipline.
• JwtClaimTypesTests.cs — per-VALUE pin against the codegen-emitted catalog; D²-prefix validation.
• WellKnownAudiencesTests.cs — value pin on D2_INTERNAL_AUDIENCE; the hand-declared-not-spec-derived guard (the value is absent from every Audiences projection — the codegen boundary); adversarial no-duplicate-constant walk.
• HTTP / AMQP / gRPC / common header per-VALUE pins live in tests/Unit/Headers/HeaderCatalogPinTests.cs.
• SpecsConsistency/JwtClaimsVsIAuthContextConsistencyTests.cs — every claim: annotation in IAuthContext.spec.json references a valid jwt-claims spec entry (forward direction; reverse intentionally not enforced — ACT_KIND / IAT / EXP etc. live outside top-level IAuthContext properties).

packages/dotnet/tests/Unit/Auth/Jwks/:

• JwksKeySetSnapshotTests.cs — defensive-copy guarantee on the Keys init setter, per-property record equality, empty-key-set tolerance.
• IJwksProviderContractTests.cs — reflection-based shape pinning (return type, parameter count, ct default, public + interface, exact method count).

packages/dotnet/tests/Unit/Auth/Sessions/:

• ISessionLivenessTrackerContractTests.cs — same reflection-based shape pinning so accidental method additions / removals fire at the abstractions test layer first.

packages/dotnet/tests/Unit/Auth/Inbound/Forwarding/ — the forwarded-JWT credential:

• ForwardedJwtTests.cs — Create (valid / null / empty / whitespace / oversized / control-chars-verbatim); RevealForForwarding (exact bytes / empty-throws / sole raw accessor / no public raw property); the never-logged proofs (ToString / interpolation / JSON-serialize / [RedactData]-attribute / real-destructuring-policy all yield the placeholder, never the bytes); equality / hashcode / HasValue.
• MutableForwardedJwtAccessorTests.cs — Current / Capture / double-capture (last-write-wins) / blank-input-no-op / no-shared-state.
• ForwardedJwtAccessorResolutionTests.cs — AddD2AuthHttp() + AddD2AuthGrpc() each register a RESOLVABLE scoped holder (resolve, not descriptor-presence); scoped-lifetime + cross-request-bleed + cross-transport parity + dual-transport.
• ForwardedJwtLogDelegateContractTests.cs — scans every auth *Log class; asserts no [LoggerMessage] delegate takes a ForwardedJwt parameter (mirrors MtlsLogDelegateContractTests).
• ForwardedJwtSoleRevealCallerTests.cs — source-text scan over server/; asserts no unexpected production caller of RevealForForwarding (the single controlled reveal seam).

packages/dotnet/tests/Unit/Logging/Internal/ForwardedJwtEnrichmentExclusionTests.cs — structural-isolation pin: no ForwardedJwt-typed / credential-named property on IRequestContext / IAuthContext, and the request-context enricher records no credential field/bytes even with a populated holder in scope.

packages/dotnet/tests/Integration/Logging/ForwardedJwtLogCaptureTests.cs — end-to-end Serilog log-capture across a capture-then-reveal cycle; asserts the raw bytes surface in NO event across both the {@x} and {x} paths.

Run: dotnet test packages/dotnet/tests.

Reference

• DcsvIo.D2.Messaging.RabbitMq — context propagation across AMQP
• RFC 8693 — OAuth 2.0 Token Exchange (act chain semantics): https://datatracker.ietf.org/doc/html/rfc8693
• RFC 6749 §4.4 — Client Credentials grant: https://datatracker.ietf.org/doc/html/rfc6749#section-4.4