Onboarding guide

8. Authentication & Authorization

What this group covers. This is the security spine of the framework: how a caller proves who they are (authentication), how the system decides what they may do (authorization), and how both survive the jump from a single-process monolith to a fleet of extracted services. Almost every type here serves one of the clusters below: minting and validating JWTs (TokenService / ITokenService, RsaJwksProvider / IJwksProvider, and the settings that select the algorithm and the key material: JwtSettings, JwtSigningAlgorithm, JwksSettings); the shared login / register / refresh workflow (AuthenticationServiceBase<TUser>, IAuthenticationService, AuthenticationValidators); multi-device refresh sessions (RefreshSession, IRefreshSessionStore, RefreshSessionSettings, RefreshSessionSummaryResponse, and the issuer that owns every session decision, AuthSessionIssuer / IAuthSessionIssuer, with its two private helpers IssuedSession and SessionStampingTokenService); the contracts an app's User aggregate exposes to those shared workflows (IAuthUser, IPasswordChangeableUser, IUserPreferences, IErasableUser); password material (PasswordHasher / IPasswordHasher, and the one complexity rule both server and client read, PasswordComplexity); brute-force and rate-limit protection (LoginProtectionService / ILoginProtectionService, LoginProtectionSettings); the forgot-password token lifecycle (PasswordResetTokenService / IPasswordResetTokenService, PasswordResetEntry, PasswordResetSettings); reading the current caller's identity from claims (CurrentUserService / ICurrentUserService, ClaimsPrincipalExtensions, ClaimBasedUserIdProvider, AuthClaimTypes); the authorization model (permissions and resource ownership under AuthorizationExtensions, PermissionAuthorizationHandler, and OwnerOrAdminFilter); and the HttpOnly session-cookie machinery (SessionCookieEndpoints, SessionCookieAuthenticationHandler, CookieSessionRefresher) that keeps server-side-rendered Blazor pages authenticated across a cold navigation. Five further clusters are opt-in identity completions: a second factor (ITwoFactorService / TotpTwoFactorService, ITwoFactorAuthenticator, ITwoFactorStore, ITwoFactorUserState); email confirmation (IEmailConfirmationTokenService / EmailConfirmationTokenService, IEmailConfirmableUser); operator-editable permission grants (PermissionGrant, IPermissionGrantStore, LayeredPermissionRegistry); a user and role administration API (IUserAdministrationService<TUserDto>, IRoleAdministrationService, StoredPermissionRoleAdministrationService); and Terms of Service acceptance (LegalAcceptancePolicy, ILegalAcceptanceService, ILegalAcceptingUser). Each of those five is a set of contracts plus an abstract or concrete base behind its own Add* call, never a framework feature with a framework table, so a host that does not opt in pays nothing.

The governing decisions are ADR-004 (dual-fetch login and cross-service token validation via JWKS, with RS256 as the default because it survives extraction), ADR-097 (hashed, rotating, per-device refresh sessions, which supersedes the storage model of ADR-050 while keeping its rotation and reuse-detection policy), ADR-029 (brute-force protection), ADR-102 (PBKDF2-only password hashing, superseding ADR-032), ADR-091 (the cache-backed forgot-password token), ADR-020 (permission-based authorization), ADR-033 (resource-ownership authorization), ADR-022 (the browser session-cookie scheme), ADR-051 (how each render head holds and reacquires a token), and ADR-047 (runtime revocation for a soft-deleted account), and ADR-116 (the second factor, email confirmation, operator-editable permission grants, and the administration API, all shipped as contracts and bases behind their own Add* calls rather than as framework features). Two neighbouring records also reach into this chapter by dependency grouping: ADR-115 owns the MMCA.Common.Shared.Identifiers wrapper-struct capability, and ADR-031 owns the [FeatureFlag] lifecycle metadata in MMCA.Common.Shared.FeatureFlags. The rubric lenses are dominated by [Rubric §11, Security], with supporting [Rubric §7, Microservices Readiness] and [Rubric §12, Performance & Scalability]. Auth surfaces all of its expected failures (bad password, lockout, expired session, rejected reset token) as Result failures, never exceptions, so reading the Result pattern first pays off here.

Tokens: one signing switch, two validation worlds

The framework mints two credentials on every successful sign-in: a short-lived access token (a JWT, 15 minutes by default, MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Auth/JwtSettings.cs:61) and an opaque, random refresh token (64 bytes of RandomNumberGenerator output, Base64-encoded, valid 7 days by default, TokenService.cs:155-158, JwtSettings.cs:64), both produced by TokenService (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Auth/TokenService.cs:26). The access token carries a fixed claim spine: sub, jti, iat, plus name, email, and role (TokenService.cs:113-122), and the app adds its own claims (for example speaker_id or customer_id) through the additionalClaims parameter (TokenService.cs:124-127). sub is the single carrier of the user identifier: the duplicate custom claim that used to ride alongside it is gone, because two values that can disagree is two claim names every reader has to know (TokenService.cs:110-112). The port ITokenService (MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/Infrastructure/Auth/ITokenService.cs:8) publishes both lifetimes as default interface members pinned to the same 15-minute / 7-day baseline (ITokenService.cs:33, ITokenService.cs:40), so a hand-written test double reports the same expiry the production settings would, while the concrete service derives them from the bound settings (TokenService.cs:162, TokenService.cs:165).

The load-bearing design choice is a single configuration switch, JwtSettings.SigningAlgorithm (TokenService.cs:87). It defaults to JwtSigningAlgorithm.RS256 (JwtSettings.cs:30): the Identity service signs with an RSA private key and every other service validates against the matching public key, which it fetches over JWKS. A single-host monolith opts into HS256 explicitly, where one symmetric Base64 secret both signs and validates because issuer and validator are the same process (TokenService.cs:87-98, TokenService.cs:226-238). Asymmetric is the default precisely because it is the shape that survives extraction: a compromised non-Identity service can verify tokens but cannot forge them. An issuer with no explicit public key configured derives one from its own private-key parameters so it can still self-validate during refresh (TokenService.cs:262-276), and the key id from JwksSettings travels into every RS256 token's kid header so a validator reading the published document selects the right key by name rather than trying each in turn (TokenService.cs:255-259). Key material is materialized once in the constructor and the owned RSA handles are disposed with the service (TokenService.cs:39-40, TokenService.cs:220-224), so token operations never re-parse a PEM. The settings class enforces the pairing rather than trusting the host: it implements IValidatableObject and rejects an HS256 secret shorter than 32 characters or an RS256 configuration with no private key (JwtSettings.cs:70-85).

The public half is served by RsaJwksProvider (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Auth/RsaJwksProvider.cs:14), which lazily builds a JsonWebKeySet from a PEM key (inline or read from a path) configured through JwksSettings (RsaJwksProvider.cs:27-55, RsaJwksProvider.cs:57-73), behind the IJwksProvider port (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Auth/IJwksProvider.cs:11). Publishing is off by default, and when disabled or unconfigured the provider returns an empty key set (RsaJwksProvider.cs:29-32, RsaJwksProvider.cs:35-38) so the endpoint stays queryable but a non-issuer host advertises nothing. The cache is a Lazy<JsonWebKeySet> in PublicationOnly mode rather than the default ExecutionAndPublication (RsaJwksProvider.cs:16-22): the default caches a factory exception forever, so a single transient IO failure reading the PEM would brick the endpoint (and with it cross-service auth) until the process restarted. The endpoint itself, /.well-known/jwks.json, is mapped in the API layer by JwksEndpointExtensions (path constant at MMCA.Common/Source/Presentation/MMCA.Common.API/Startup/Endpoints/JwksEndpointExtensions.cs:20, mapped anonymously at JwksEndpointExtensions.cs:33-39), paired with the OIDC discovery document from OidcDiscoveryEndpointExtensions (MMCA.Common/Source/Presentation/MMCA.Common.API/Startup/Endpoints/OidcDiscoveryEndpointExtensions.cs:27); OpenIdConnectMetadataWarmupTask pre-fetches that document as a startup warm-up task (MMCA.Common/Source/Hosting/MMCA.Common.Aspire/Warmup/OpenIdConnectMetadataWarmupTask.cs:23) so the first authenticated request on a cold replica does not pay the discovery round trip. Validation pins the expected algorithm so an attacker cannot force an algorithm swap: GetPrincipalFromExpiredToken sets ValidAlgorithms to the single configured value (TokenService.cs:187) and then re-checks the token header after ValidateToken returns (TokenService.cs:196-200). Only the lifetime check is skipped there (TokenService.cs:182), because the method exists to read claims out of an already-expired token during refresh.

The shared authentication workflow

Login, registration, refresh, revocation, and device listing are not re-implemented per app. They live once in AuthenticationServiceBase<TUser> (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/AuthenticationServiceBase.cs:64), an abstract base each app's Identity module seals over its concrete User aggregate. The base owns the sequence; the sealed subclass supplies the genuinely app-specific pieces through abstract and virtual hooks: FindUntrackedByEmailAsync and EmailExistsAsync (written against the concrete User so EF translation is unchanged, AuthenticationServiceBase.cs:464, AuthenticationServiceBase.cs:470), CreateUser (AuthenticationServiceBase.cs:473), CreateAccessToken (AuthenticationServiceBase.cs:476), the two optional candidate gates (AuthenticationServiceBase.cs:581-586), the post-commit OnUserRegisteredAsync (AuthenticationServiceBase.cs:592), and the overridable "refresh user vanished" error (AuthenticationServiceBase.cs:600, 401 by default because a token for a deleted user is indistinguishable from an invalid one). What the base does not own is the session: it decides who is signed in and hands everything about what they are given to IAuthSessionIssuer, a constructor dependency (AuthenticationServiceBase.cs:41-44, AuthenticationServiceBase.cs:69), so the workflow never touches a session row. Even the token service a subclass mints through is the issuer's (AuthenticationServiceBase.cs:99), which is how the sid and mfa claims reach an app's token without the app's claim code knowing they exist (see the refresh-session section below).

LoginAsync (AuthenticationServiceBase.cs:123) shows the shape. It validates the request first, then runs the ADR-029 lockout check (AuthenticationServiceBase.cs:135-140), then does the dual-fetch: an untracked, no-change-tracking query to verify the password cheaply (AuthenticationServiceBase.cs:148, AuthenticationServiceBase.cs:161), and only on success a second tracked re-fetch of the instance the app's CreateAccessToken hook mints from, which is also what turns a race that deleted the account between the two steps into a clean 404 (AuthenticationServiceBase.cs:195-204). The email is normalized through the Email value object before the query so the EF predicate compares same-typed converted values (AuthenticationServiceBase.cs:144). Soft-deleted accounts fall out through EF global query filters and return the same generic 401 as a wrong password (AuthenticationServiceBase.cs:146-166), and so does an account with no stored credential at all (the external-OAuth shape), which also pays one throwaway key derivation so its 401 does not come back measurably faster than a real check (AuthenticationServiceBase.cs:150-159, AuthenticationServiceBase.cs:615-625): the API never reveals whether an email exists. The app's candidate gate, the email-confirmation gate and the second-factor challenge all run after the password check (AuthenticationServiceBase.cs:168-193), and a successful login clears the attempt counters (AuthenticationServiceBase.cs:207) before handing off to the shared token-issue path (AuthenticationServiceBase.cs:212).

RegisterAsync (AuthenticationServiceBase.cs:221) first refuses a request that did not accept the Terms of Service when the host configures a current terms version (AuthenticationServiceBase.cs:236-239, covered in the Terms of Service section below), then rate-limits by source IP, rejects a duplicate email as a conflict, hashes the password, saves, and only then runs the app's post-commit hook, counts the registration, and opens the session (AuthenticationServiceBase.cs:241-305). The up-front email check is a check-then-act, so two concurrent registrations for the same address both pass it and the loser only fails on the insert. The save is therefore wrapped in a deliberately broad catch that re-checks the address and, if it now exists, returns the same conflict the serialized path would have produced, rethrowing anything else (AuthenticationServiceBase.cs:266-294); the shared failure factory keeps the two paths indistinguishable to the caller (AuthenticationServiceBase.cs:632). The catch is broad because the Application layer has no EF Core dependency by layer rule and cannot name DbUpdateException; the re-check is what narrows it, and it deliberately runs on CancellationToken.None so a cancelled save can still be classified (AuthenticationServiceBase.cs:288). The password rule a registration is validated against is defined exactly once, in PasswordComplexity (MMCA.Common/Source/Core/MMCA.Common.Shared/Auth/PasswordComplexity.cs:18): 8 to 128 UTF-16 code units (PasswordComplexity.cs:21, PasswordComplexity.cs:24) with an uppercase letter, a lowercase letter, a digit and a special character, each a Unicode-aware generated regex with a one-second match timeout, so an accented or CJK letter counts as a letter and never as the special character (PasswordComplexity.cs:12-16, PasswordComplexity.cs:27-43), combined in Evaluate (PasswordComplexity.cs:52-57). It lives in Shared because both sides read it: the server's StrongPasswordRules matches the same four patterns and the same ceiling (MMCA.Common/Source/Core/MMCA.Common.Application/Validation/CommonValidationRules.cs:197-201), and the client form attribute calls Evaluate (MMCA.Common/Source/Presentation/MMCA.Common.UI/Pages/Auth/PasswordComplexityAttribute.cs:24), so the two cannot give different verdicts for one input, which is the validation-parity point of rubric §24 the type's own remarks cite (PasswordComplexity.cs:5-10).

RefreshTokenAsync (AuthenticationServiceBase.cs:309) extracts claims from the expired access token (signature still verified, only lifetime skipped, AuthenticationServiceBase.cs:321-323), reads the identifier off sub through ClaimsPrincipalExtensions (AuthenticationServiceBase.cs:333), carries the mfa claim the user already earned across the rotation so a signed-in session is not quietly demoted every fifteen minutes (AuthenticationServiceBase.cs:353-358), and then hands the presented refresh token to the issuer's RotateAsync (AuthenticationServiceBase.cs:363-369). Every failure path returns a Result rather than throwing, matching the framework-wide Result pattern (see primer §2).

The request and response DTOs for these flows (LoginRequest, RegisterRequest, RefreshTokenRequest, AuthenticationResponse, ChangePasswordRequest, OAuthCodeExchangeRequest, and the device-aware AuthenticationRequest used by MAUI clients) are compact readonly record structs in MMCA.Common.Shared. Several of them mark boundaries worth noting: password change is dispatched straight through its command handler at the controller layer rather than brokered by IAuthenticationService (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/IAuthenticationService.cs:12), the same is true of the forgot/reset pair below (ForgotPasswordRequest, ResetPasswordRequest), and ExternalLoginAsync has a default interface implementation that rejects the call (IAuthenticationService.cs:131-139) because OAuth account linking stays coupled to the app's own User factory. OAuthCodeExchangeRequest carries only an opaque single-use code (MMCA.Common/Source/Core/MMCA.Common.Shared/Auth/Requests/OAuthCodeExchangeRequest.cs:11) precisely so the token pair never appears in the address bar, browser history, a Referer header, or an access log. The FluentValidation rules that guard the requests are bundled into one parameter object, AuthenticationValidators (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/AuthenticationValidators.cs:24), which keeps the app's AuthenticationService constructor below the arity ceiling; the framework ships LoginRequestValidator and RefreshTokenRequestValidator, both deliberately minimal presence-and-shape checks so a rejection never reveals which field was wrong (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/Validation/LoginRequestValidator.cs:11, MMCA.Common/Source/Core/MMCA.Common.Application/Auth/Validation/RefreshTokenRequestValidator.cs:10), while the IValidator<RegisterRequest> the bundle requires is supplied by each app (AuthenticationValidators.cs:16-19).

Refresh sessions: one row per device

A refresh token is no longer a column on the user row. Every issue opens its own RefreshSession (MMCA.Common/Source/Core/MMCA.Common.Domain/Auth/RefreshSession.cs:35), so signing in on a phone leaves a laptop signed in, and the store holds only the token's digest: Create hashes on the way in so the plaintext never reaches a property (RefreshSession.cs:129-162), and HashToken is an unsalted, deterministic SHA-256 rendered as 64 upper-case hex characters precisely because lookups are by hash (RefreshSession.cs:177-181, width constant at RefreshSession.cs:46). The encoding is part of the contract, not an implementation detail: the type's own remarks give the byte-for-byte SQL Server equivalent a consumer's data migration has to reproduce (RefreshSession.cs:168-174). The row is deliberately not an aggregate: no audit stamps, no soft-delete flag, no concurrency token, like OutboxMessage and AuditTrailEntry, because rows are only ever inserted or revoked and no global query filter may hide a revoked row from the reuse check (RefreshSession.cs:26-35). Revoke is idempotent by refusal, so the first reason and instant recorded are the ones kept (RefreshSession.cs:191-206), and the four reason constants (Rotated, SignedOut, ReuseDetected, SessionCapExceeded, RefreshSession.cs:58-67) are what an operator reads afterwards.

Rotation leaves a chain, and the chain is the security mechanism. Using a session revokes it and records the successor in ReplacedByTokenHash (RefreshSession.cs:91), so presenting an already-rotated token lands on a revoked row rather than on nothing: that is the ADR-050 reuse signal, and AuthSessionIssuer answers it by revoking every live session the user holds (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/Sessions/AuthSessionIssuer.cs:335-339, AuthSessionIssuer.cs:489-501). The three rejections behind the single generic error are deliberately different in what they do (AuthSessionIssuer.cs:284-345): an unknown hash, or one belonging to another account, is failed alone, since revoking the family on it would let anyone holding one of this user's expired access tokens sign them out everywhere by posting a random string (AuthSessionIssuer.cs:313-316); a revoked row splits by why it was revoked, so one rotated away (or already flagged as reuse) is the reuse signal and revokes the family, while one signed out or evicted by the session cap only lost its session and fails alone (AuthSessionIssuer.cs:318-326, classified by IsReuseSignal at AuthSessionIssuer.cs:462-470, which treats a missing or unrecognized reason as reuse); an expired row is an ordinary end of life, so that device re-authenticates while the others keep working (AuthSessionIssuer.cs:342-344). One window softens the reuse answer: a row revoked as Rotated less than RefreshSessionSettings.ReuseGraceSeconds ago (AuthSessionIssuer.cs:479-487) is a sibling race (a second tab, or one browser served by two replicas), answered 409 Conflict with the code Auth.RefreshSuperseded and nothing revoked (AuthSessionIssuer.cs:328-333, AuthSessionIssuer.cs:278-280). Two requests presenting the same still-live token go through the same classification: rotation is claimed atomically through IRefreshSessionStore.TryRotateAsync (AuthSessionIssuer.cs:417-419), the request that loses the claim re-reads the row as the database holds it now (AuthSessionIssuer.cs:427-429), and then a sign-out or cap eviction fails it alone, a rotation inside the grace is a 409, and anything else is answered exactly like a replay (AuthSessionIssuer.cs:430-450).

IRefreshSessionStore (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/IRefreshSessionStore.cs:22) is the narrow persistence port: add, find by hash (revoked and expired rows included, which is load-bearing for reuse detection, IRefreshSessionStore.cs:29-38), list a user's un-revoked sessions (IRefreshSessionStore.cs:46), find one of a user's sessions by id with the owner inside the query so another account's id is indistinguishable from a nonexistent one (IRefreshSessionStore.cs:50-63), re-read one session by id untracked for the rotation loser above (IRefreshSessionStore.cs:66-81, whose default body returns null), save, and TryRotateAsync (IRefreshSessionStore.cs:116). Implementations must return tracked instances from every lookup except that read-only re-read, because revocation is a mutation on an instance the store handed out and a no-tracking read would drop it at save time (IRefreshSessionStore.cs:16-21). The default TryRotateAsync body (revoke in memory, add, save) is atomic only per instance, which is all an in-memory or test store can offer; the shipped EF implementation EFRefreshSessionStore overrides it with a conditional ExecuteUpdateAsync the database arbitrates (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Auth/EFRefreshSessionStore.cs:121-146). That is the [Rubric §8, Data Architecture] half of the story, and the store is registered scoped alongside the unit of work it shares a DbContext with, so a login and its session insert commit together (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:166-172).

The workflow around the port lives in AuthSessionIssuer (AuthSessionIssuer.cs:41), not in the authentication base, and is small and worth reading end to end. IssueTokensAsync (AuthenticationServiceBase.cs:443) hands the user's id and a minting callback to the issuer's IssueAsync (AuthSessionIssuer.cs:64), which opens the session before it mints the access token, because the token carries the session's id and a session only has an id once it has been created (AuthSessionIssuer.cs:75-88). OpenSessionAsync (AuthSessionIssuer.cs:352) mints the refresh token, builds the row, and, before staging the insert, enforces the per-user cap by revoking the oldest live sessions (AuthSessionIssuer.cs:374, AuthSessionIssuer.cs:503-525), so one account cannot grow the table without bound while a legitimate sign-in never fails. OpenSessionAsync and its rotation twin RotateSessionAsync (AuthSessionIssuer.cs:394) both return IssuedSession (AuthSessionIssuer.cs:532), the private pair of "the plaintext token, which exists nowhere else" and "the row id". The id reaches the client as the standard sid claim, stamped by SessionStampingTokenService (AuthSessionIssuer.cs:544), a private pass-through ITokenService that the issuer exposes as its TokenService (AuthSessionIssuer.cs:52-55) and arms through MintForSession for the duration of the app's CreateAccessToken call (AuthSessionIssuer.cs:132-147, reached from AuthenticationServiceBase.cs:495-496). Doing it with a wrapper rather than by changing the hook's signature is what makes the claim additive: every existing subclass keeps compiling and starts emitting sid with no edit. GetSessionsAsync (AuthenticationServiceBase.cs:412) delegates to the issuer's ListActiveAsync (AuthSessionIssuer.cs:193), which projects the user's live sessions into RefreshSessionSummaryResponse (MMCA.Common/Source/Core/MMCA.Common.Shared/Auth/Responses/RefreshSessionSummaryResponse.cs:23), newest first, flagging the caller's own device by comparing against the session id the caller passes from the token's sid (AuthSessionIssuer.cs:201-214); the response deliberately omits the token hash and the rotation link, since nothing a client does with a session needs anything but its id (RefreshSessionSummaryResponse.cs:6-11). RevokeSessionByIdAsync (AuthenticationServiceBase.cs:428, delegating to AuthSessionIssuer.cs:231) signs one device out and treats an already-revoked row as a success that writes nothing, because a device list clicked twice is the most ordinary duplicate in the feature (AuthSessionIssuer.cs:246-253), while RevokeTokenAsync (AuthenticationServiceBase.cs:378, delegating to AuthSessionIssuer.cs:150) degrades to signing every device out when the presented token does not identify a live session of this user's (AuthSessionIssuer.cs:160-174). Those methods surface on IAuthenticationService (IAuthenticationService.cs:67, IAuthenticationService.cs:96, IAuthenticationService.cs:115) and are exposed by AuthControllerBase as revoke, my-sessions, and a per-session route (MMCA.Common/Source/Presentation/MMCA.Common.API/Controllers/AuthControllerBase.cs:152, AuthControllerBase.cs:183, AuthControllerBase.cs:231).

RefreshSessionSettings (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/RefreshSessionSettings.cs:9) is where a host tunes the model: MaxActiveSessionsPerUser (default 10, range 1 to 1000, RefreshSessionSettings.cs:34-35), RetentionDays (default 30, RefreshSessionSettings.cs:71-72), CleanupIntervalHours (default 6, RefreshSessionSettings.cs:79-80), the DataSourceName that says which database carries the table (RefreshSessionSettings.cs:51-52), and Enabled (RefreshSessionSettings.cs:25), which gates the model, not the workflow: the service that owns identity sets it, every other service in a modular host leaves it alone, and that is what keeps the table, its migrations, and its sweep in exactly one database. Retention is not decoration: the settings' own remarks state that the sweep bounds reuse detection, because once a revoked row is swept, a replay of its token reads as an unknown token and fails alone (RefreshSessionSettings.cs:59-66). ReuseGraceSeconds (default 10, range 0 to 300, RefreshSessionSettings.cs:97-98) is the rotation-race window described above, matched to the cookie refresher's rotation grace, and its remarks state the trade-off plainly: a stolen-token replay arriving inside the window of a legitimate rotation is answered 409 instead of revoking the family, and 0 treats every returning rotated token as reuse (RefreshSessionSettings.cs:82-95). The hosted sweep RefreshSessionCleanupService (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Auth/RefreshSessionCleanupService.cs:48) is registered only when the flag is set, so a service with no RefreshSessions table never starts a sweep over a table it does not have (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:178-186), and the mapping itself is opt-in through RefreshSessionModelBuilderExtensions.ApplyRefreshSessionConfiguration (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Auth/RefreshSessionModelBuilderExtensions.cs:34). This whole cluster is [Rubric §7, Microservices Readiness] as much as [Rubric §11, Security]: the credential store is one service's table, not a column every service's user model has to carry.

What the app's User aggregate must expose

The shared workflows never see an app's User class. They see four small Domain-layer contracts, each sized to one workflow, which is the [Rubric §1, SOLID] interface-segregation story in miniature. IAuthUser (MMCA.Common/Source/Core/MMCA.Common.Domain/Auth/IAuthUser.cs:16) is now the password surface and nothing else: the hash and the salt whose length once selected an algorithm (IAuthUser.cs:19-23). Refresh tokens are deliberately absent, and the interface says why: they used to live here as a single plaintext column, which capped every account at one signed-in device and put a usable credential in the users table (IAuthUser.cs:9-14). Profile fields, roles, and linked aggregates stay app-specific and are reached only through the per-app hooks. IPasswordChangeableUser (MMCA.Common/Source/Core/MMCA.Common.Domain/Auth/IPasswordChangeableUser.cs:11) extends it with ChangePassword (IPasswordChangeableUser.cs:19), because both the rotation workflow and the reset workflow have to write a new credential through the aggregate rather than around it. IUserPreferences (MMCA.Common/Source/Core/MMCA.Common.Domain/Auth/IUserPreferences.cs:10) carries the stored culture and theme plus a single UpdatePreferences mutator that always replaces both fields (IUserPreferences.cs:13-25); the shared workflow is what preserves the other preference, passing the stored value for any field the request left null (MMCA.Common/Source/Core/MMCA.Common.Application/Users/UseCases/ChangePreferences/ChangePreferencesHandlerBase.cs:53-55), which is the null-means-unchanged contract stated on ChangePreferencesRequest and mirrored by UserPreferencesResponse (MMCA.Common/Source/Core/MMCA.Common.Shared/Auth/Requests/ChangePreferencesRequest.cs:10, MMCA.Common/Source/Core/MMCA.Common.Shared/Auth/Responses/UserPreferencesResponse.cs:9).

IErasableUser (MMCA.Common/Source/Core/MMCA.Common.Domain/Auth/IErasableUser.cs:30) is the subtlest of the four. It extends IAnonymizable and redeclares Delete() (IErasableUser.cs:37) rather than inheriting it from AuditableBaseEntity<TId>, because an app User commonly hides the base method (public new Result Delete()) to add account-specific behavior. A hidden method is not an override, so a shared workflow calling through the class constraint would silently run the base implementation and skip that behavior; routing the call through this interface makes the interface map resolve to the most derived Delete() (IErasableUser.cs:11-24). The base entity deliberately does not implement the interface, so a consumer that forgets to add it fails the generic constraint at compile time instead of losing behavior at run time (IErasableUser.cs:25-28). These four contracts are consumed by the shared handler bases in group 14: ChangePasswordHandlerBase<TUser, TCommand> (MMCA.Common/Source/Core/MMCA.Common.Application/Users/UseCases/ChangePassword/ChangePasswordHandlerBase.cs:34), ChangePreferencesHandlerBase<TUser, TCommand> (MMCA.Common/Source/Core/MMCA.Common.Application/Users/UseCases/ChangePreferences/ChangePreferencesHandlerBase.cs:23), GetUserPreferencesHandlerBase<TUser> (MMCA.Common/Source/Core/MMCA.Common.Application/Users/UseCases/GetPreferences/GetUserPreferencesHandlerBase.cs:21), ResetPasswordHandlerBase<TUser, TCommand> (MMCA.Common/Source/Core/MMCA.Common.Application/Users/UseCases/ResetPassword/ResetPasswordHandlerBase.cs:41), and DeleteUserHandlerBase<TUser, TCommand> (MMCA.Common/Source/Core/MMCA.Common.Application/Users/UseCases/DeleteUser/DeleteUserHandlerBase.cs:58), each of which constrains TUser to the matching contract.

Passwords and brute-force protection

Password material is handled by PasswordHasher (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Auth/PasswordHasher.cs:12), which hashes with PBKDF2-HMAC-SHA512 at 600,000 iterations (OWASP 2023 guidance, PasswordHasher.cs:24) over a 32-byte random salt (PasswordHasher.cs:15, PasswordHasher.cs:31) into a 64-byte output (PasswordHasher.cs:18), and verifies in constant time via CryptographicOperations.FixedTimeEquals (PasswordHasher.cs:64) to close the timing side channel. PBKDF2 is now the only path: the legacy single-round HMAC branch, and with it the algorithm selection keyed on stored salt length, is gone (ADR-102), so one algorithm derives and verifies every stored credential (PasswordHasher.cs:7-10, PasswordHasher.cs:68-74). That is a compact [Rubric §11, Security] story: a modern KDF and a constant-time compare in one small type, all behind the IPasswordHasher port (MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/Infrastructure/Auth/IPasswordHasher.cs:6) so the algorithm can be strengthened without touching an Application handler.

LoginProtectionService (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Auth/LoginProtectionService.cs:28) adds the ADR-029 gates on top, backed by ICacheService rather than a database so the counters are cheap and self-expiring. Counter keys are built from an Email-normalized identity (LoginProtectionService.cs:45-47), so User@x.com, user@x.com, and a padded variant collapse onto one lockout instead of handing an attacker three independent budgets. The normalization itself lives once, in the internal EmailIdentity helper (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Auth/EmailIdentity.cs:12), which every cache-keyed auth service calls: a valid address becomes the Email value object's normalized value, and a malformed one (which never matches a user but can still mint a key) falls back to the same trim-and-lowercase shape so its attempts land on one key too (EmailIdentity.cs:22-30). After LoginProtectionSettings.MaxFailedAttempts consecutive failures (default 5, MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Auth/LoginProtectionSettings.cs:18) it applies an exponential-backoff lockout capped at MaxLockoutSeconds (default 300, LoginProtectionSettings.cs:24), with a deliberately clamped shift exponent so a persistent attacker cannot wrap the TTL back to something small (LoginProtectionService.cs:102), and it rate-limits registrations per source IP (default 10 per 60-minute window, LoginProtectionSettings.cs:37-43, LoginProtectionService.cs:127-181). Every setting carries a [Range] attribute, which is what makes the clamp argument airtight: MaxLockoutSeconds cannot exceed 3600 (LoginProtectionSettings.cs:23), and 1 << 30 already dwarfs that. The ILoginProtectionService port (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/ILoginProtectionService.cs:10) is what the workflow depends on, and it calls the gates at exactly the right points (increment on failed login, reset on success), so the protection is centralized rather than sprinkled through each app's controller. One documented trade-off is stated in source: the attempt increment is a read-modify-write rather than an atomic counter, because the native Redis INCR path wrote a key shape IDistributedCache could not read back (LoginProtectionService.cs:78-86). Sequential guessing, which is what a credential-stuffing run looks like, still trips the lockout.

The second factor: one optional step in the same sign-in

Two-factor authentication ships as contracts plus a stateless implementation, never as a feature that turns itself on: the account row belongs to the app, and making a second factor mandatory would be a behavior change in a deployed system (ADR-116). The cryptography lives in ITwoFactorService (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/TwoFactor/ITwoFactorService.cs:16) and its implementation TotpTwoFactorService (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Auth/TwoFactor/TotpTwoFactorService.cs:35): mint a Base32 shared secret (TotpTwoFactorService.cs:40-41), render the otpauth://totp/... provisioning URI an authenticator app is keyed from (TotpTwoFactorService.cs:44, TotpTwoFactorService.cs:54), verify a code inside the configured skew window (TotpTwoFactorService.cs:58), and generate and match single-use recovery codes (TotpTwoFactorService.cs:91, TotpTwoFactorService.cs:120). It is deliberately stateless and persistence-free, so a data migration enrolling existing accounts can call it directly and every method is testable against a fixed clock (ITwoFactorService.cs:10-15). Recovery codes travel as a RecoveryCodeSet (ITwoFactorService.cs:97), plaintext and hashes paired positionally so a caller cannot store one set and display another, and the plaintext exists only in the returned value. Matching compares in fixed time through CryptographicOperations.FixedTimeEquals with no early exit (TotpTwoFactorService.cs:142), and the codes are Base32 rather than Base64 because that alphabet has no case ambiguity for a user reading one off paper (TotpTwoFactorService.cs:98-100).

TwoFactorSettings (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/TwoFactor/TwoFactorSettings.cs:15) binds from Authentication:TwoFactor (TwoFactorSettings.cs:18) and defaults to the RFC 6238 values every authenticator app assumes: six digits (TwoFactorSettings.cs:30), a thirty-second step (TwoFactorSettings.cs:34), one step of tolerated skew on each side, which widens the accepted window to roughly ninety seconds (TwoFactorSettings.cs:46), a twenty-byte secret (TwoFactorSettings.cs:61), and ten recovery codes of ten random bytes each (TwoFactorSettings.cs:50, TwoFactorSettings.cs:57). They are configurable so a host can match an existing enrollment base, not because moving them is a good idea: an app keyed against one period cannot read codes minted with another (TwoFactorSettings.cs:9-14).

State is the app's, so it is reached through two contracts rather than a framework table. ITwoFactorUserState (MMCA.Common/Source/Core/MMCA.Common.Domain/Auth/ITwoFactorUserState.cs:27) is what the app's User exposes: the enabled flag, the Base32 secret, and the unspent recovery-code hashes (ITwoFactorUserState.cs:30, ITwoFactorUserState.cs:36, ITwoFactorUserState.cs:42). The load-bearing invariant is stated on the interface itself: a stored secret is not an enabled second factor, because starting an enrollment writes the secret while the flag stays false, so an enrollment the user abandons half way can never gate a later sign-in (ITwoFactorUserState.cs:22-25). ITwoFactorStore (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/TwoFactor/ITwoFactorStore.cs:24) is the matching persistence port, split along that invariant: StartEnrollmentAsync stores the secret without activating anything (ITwoFactorStore.cs:44), CompleteEnrollmentAsync activates it and stores the first recovery hashes only after a code minted from that secret has verified (ITwoFactorStore.cs:54), DisableAsync clears both so a later enrollment starts from a fresh secret rather than reviving an old one (ITwoFactorStore.cs:66), and the recovery set is replaced wholesale or spent one code at a time (ITwoFactorStore.cs:76, ITwoFactorStore.cs:93). Every mutating member returns a Result so an aggregate that refuses can say so without an exception crossing the layer, and implementations save their own work, because a workflow treats one call's result as final (ITwoFactorStore.cs:13-22). The framework ships no EF implementation here the way it does for refresh sessions, because the secret and the hashes belong to the app's user row (ITwoFactorStore.cs:6-10).

The sign-in hook is a third contract, ITwoFactorAuthenticator (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/TwoFactor/ITwoFactorAuthenticator.cs:24), and it is a separate collaborator on purpose: AuthenticationServiceBase<TUser> takes it as an optional constructor dependency, so an app that has not adopted the second factor passes nothing and its sign-in does not even pay a query (ITwoFactorAuthenticator.cs:13-16). The challenge runs after the password check, for the same reason the account-state gate does: reaching it proves the caller owns the credential, so answering "this account needs a second factor" tells the owner something rather than telling an address sweeper which accounts are protected (ITwoFactorAuthenticator.cs:19-21). The shipped TwoFactorAuthenticator (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Auth/TwoFactor/TwoFactorAuthenticator.cs:36) reads the state and returns TwoFactorOutcome.NotEnrolled when there is no active factor, so an unenrolled account's sign-in is unchanged (TwoFactorAuthenticator.cs:114, ITwoFactorAuthenticator.cs:47); otherwise it verifies a TOTP code (TwoFactorAuthenticator.cs:114), falls back to matching and spending a recovery code (TwoFactorAuthenticator.cs:70, TwoFactorAuthenticator.cs:85), and fails with one of the two TwoFactorErrors codes: Authentication.TwoFactorRequired when a code was needed and none arrived, Authentication.TwoFactorInvalid when one arrived and did not verify (TwoFactorAuthenticator.cs:61, TwoFactorAuthenticator.cs:74, MMCA.Common/Source/Core/MMCA.Common.Application/Auth/TwoFactor/TwoFactorErrors.cs:18, TwoFactorErrors.cs:21). Which method satisfied the challenge is what the issued token records: AuthClaimTypes names the mfa claim and its two values, otp and recovery (MMCA.Common/Source/Core/MMCA.Common.Shared/Auth/AuthClaimTypes.cs:62, AuthClaimTypes.cs:65, AuthClaimTypes.cs:68), read back through ClaimsPrincipalExtensions.HasMultiFactor and FindMultiFactorMethod (ClaimsPrincipalExtensions.cs:127, ClaimsPrincipalExtensions.cs:137), which is how a presence check stays out of ICurrentUserService. The wire shapes are TwoFactorCodeRequest with its TwoFactorCodeRequestValidator, TwoFactorSetupResponse and TwoFactorRecoveryCodesResponse.

Forgot password: a cache-backed single-use token

A user who has lost the password cannot present one, so this flow is anonymous by necessity, which makes every one of its responses a potential account-enumeration oracle. It is also built without a schema change: the token lives in the cache, hashed, and expires by TTL rather than being reaped by a sweeper (ADR-091). The port is IPasswordResetTokenService (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/IPasswordResetTokenService.cs:10), two methods wide: IssueAsync mints a token for an address (IPasswordResetTokenService.cs:23) and ValidateAndConsumeAsync redeems it exactly once (IPasswordResetTokenService.cs:36). The implementation, PasswordResetTokenService (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Auth/PasswordResetTokenService.cs:33), rides on ICacheService and buys four properties in a few lines each:

• One active token per email. Issuing writes the same per-address key (PasswordResetTokenService.cs:53, PasswordResetTokenService.cs:90), so requesting a new link retires the previous one.
• Hashed at rest. Only the Base64 of the token's SHA-256 is stored (PasswordResetTokenService.cs:57-58, PasswordResetTokenService.cs:84-90), so a cache dump hands out no working reset links, and the comparison on redemption is constant time through CryptographicOperations.FixedTimeEquals (PasswordResetTokenService.cs:146).
• An attempt cap. A wrong token increments a counter on the record, and the record is discarded at MaxValidationAttempts (PasswordResetTokenService.cs:160-181, default 5, MMCA.Common/Source/Core/MMCA.Common.Application/Auth/PasswordResetSettings.cs:36). The rewrite after a wrong guess uses the record's remaining lifetime rather than a fresh one (PasswordResetTokenService.cs:174-180), so guessing cannot extend the redeemable window.
• A per-email request throttle. A counter carrying the window's TTL caps how often one address can trigger an email (PasswordResetTokenService.cs:68-79, default 3 per 60 minutes, PasswordResetSettings.cs:40, PasswordResetSettings.cs:44), and a successful redemption deletes the token and that counter (PasswordResetTokenService.cs:154-155) so a legitimate reset does not leave the user throttled out of a later one.

Keys are built from an Email-normalized identity, through the same EmailIdentity helper and for the same reason LoginProtectionService does it (PasswordResetTokenService.cs:47-55). The cached record, PasswordResetEntry (PasswordResetTokenService.cs:199), is deliberately all JSON primitives: cache values round-trip through System.Text.Json, so a value object or a byte[] member would not survive a distributed backing store (PasswordResetTokenService.cs:190-194). Token material is 32 random bytes, Base64Url encoded (PasswordResetTokenService.cs:39, PasswordResetTokenService.cs:81), redeemable for TokenLifetimeMinutes (default 30, PasswordResetSettings.cs:29), and every rejection (unknown, expired, mismatched, attempt-capped) collapses into one generic failure (PasswordResetTokenService.cs:183-187). The settings bind from the PasswordReset configuration section and the service is registered scoped in Infrastructure DI (PasswordResetSettings.cs:13, MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:160-164).

The workflow around the port lives in the group-14 handler bases, and it is where the anti-enumeration rule is enforced. ForgotPasswordHandlerBase<TUser, TCommand> (MMCA.Common/Source/Core/MMCA.Common.Application/Users/UseCases/ForgotPassword/ForgotPasswordHandlerBase.cs:36) resolves the account through its one abstract lookup, issues a token, and mails it through IEmailSender (ForgotPasswordHandlerBase.cs:84-89), but a malformed address, an address with no account, a throttled request, and a failed send all log and return success alike (ForgotPasswordHandlerBase.cs:60-63, ForgotPasswordHandlerBase.cs:68-71, ForgotPasswordHandlerBase.cs:75-78, ForgotPasswordHandlerBase.cs:91-97). The only 400 comes from ForgotPasswordRequestValidator (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/Validation/ForgotPasswordRequestValidator.cs:11), which inspects the shape of the address and nothing else. The email carries both a prefilled link (composed from PasswordResetSettings.ResetUrl, deliberately not required so a host that has not configured a UI base still boots, PasswordResetSettings.cs:25, ForgotPasswordHandlerBase.cs:145-148) and the raw token, because a client without deep linking (the MAUI head) needs it typed into the reset page by hand (ForgotPasswordHandlerBase.cs:124). ResetPasswordHandlerBase<TUser, TCommand> (MMCA.Common/Source/Core/MMCA.Common.Application/Users/UseCases/ResetPassword/ResetPasswordHandlerBase.cs:41) consumes the token before the save on a stated trade-off (leaving it live until the write succeeds opens a replay window; a token burned by a later invariant failure costs the user one more reset request, ResetPasswordHandlerBase.cs:73-83), hashes through IPasswordHasher and writes the credential through the aggregate's ChangePassword (ResetPasswordHandlerBase.cs:94-95), then clears the login-protection counters so a user who reset because of a lockout is not left locked out (ResetPasswordHandlerBase.cs:110). ResetPasswordRequestValidator (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/Validation/ResetPasswordRequestValidator.cs:12) includes the same StrongPasswordRules<T> that registration and change-password use (ResetPasswordRequestValidator.cs:23), so a reset is not a way around the complexity policy. The endpoints are PasswordResetAuthControllerBase<TForgotPasswordCommand, TResetPasswordCommand> (MMCA.Common/Source/Presentation/MMCA.Common.API/Controllers/PasswordResetAuthControllerBase.cs:43): both actions are [AllowAnonymous] and rate-limited per IP exactly as login and register are (PasswordResetAuthControllerBase.cs:77-78, PasswordResetAuthControllerBase.cs:101-102), forgot-password answers 202 for any well-formed request (PasswordResetAuthControllerBase.cs:79, PasswordResetAuthControllerBase.cs:92), and reset-password collapses every rejection into a single 401 (PasswordResetAuthControllerBase.cs:105).

Email confirmation: the same token shape, a different prefix

Confirming an address is the forgot-password flow's twin, and it is built that way on purpose: member for member, IEmailConfirmationTokenService (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/EmailConfirmation/IEmailConfirmationTokenService.cs:15) mirrors the reset port, with IssueAsync minting a token for an address and account (IEmailConfirmationTokenService.cs:28) and ValidateAndConsumeAsync redeeming it exactly once and returning the confirmed account's identifier (IEmailConfirmationTokenService.cs:41). The implementation EmailConfirmationTokenService (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Auth/EmailConfirmationTokenService.cs:36) rides on ICacheService under its own key prefix and buys the same four properties: 32 random bytes Base64Url encoded (EmailConfirmationTokenService.cs:41, EmailConfirmationTokenService.cs:66), only the token's SHA-256 stored (EmailConfirmationTokenService.cs:135), a constant-time comparison on redemption (EmailConfirmationTokenService.cs:108), and every rejection collapsed into one generic failure (EmailConfirmationTokenService.cs:160-162). Its token and request-counter keys go through the same EmailIdentity normalization as the reset keys (EmailConfirmationTokenService.cs:130, EmailConfirmationTokenService.cs:132). The cached record is EmailConfirmationEntry (EmailConfirmationTokenService.cs:174), JSON primitives only for the same round-trip reason PasswordResetEntry is.

EmailConfirmationSettings (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/EmailConfirmation/EmailConfirmationSettings.cs:10) binds from Authentication:EmailConfirmation (EmailConfirmationSettings.cs:13) and differs from the reset settings where the use case does: the token is redeemable for a day rather than half an hour (TokenLifetimeMinutes default 1440, EmailConfirmationSettings.cs:29), because a confirmation mail is commonly opened much later, while the attempt cap (5, EmailConfirmationSettings.cs:36) and the per-address request throttle (3 per 60 minutes, EmailConfirmationSettings.cs:40, EmailConfirmationSettings.cs:44) match. The gate is RequireConfirmedEmail (EmailConfirmationSettings.cs:55), off unless a host sets it and the app's user implements IEmailConfirmableUser (MMCA.Common/Source/Core/MMCA.Common.Domain/Auth/IEmailConfirmableUser.cs:22), a two-member contract: the IsEmailConfirmed flag and a Result-returning ConfirmEmail() that writes it through the aggregate (IEmailConfirmableUser.cs:25, IEmailConfirmableUser.cs:33). A user type that does not implement the interface is never asked about confirmation (IEmailConfirmableUser.cs:12), which is what keeps the feature inert for the apps that have not adopted it. The two failures are named in EmailConfirmationErrors (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/EmailConfirmation/EmailConfirmationErrors.cs:9): Authentication.EmailNotConfirmed for a sign-in blocked by the gate and Authentication.InvalidConfirmationToken for every rejected redemption (EmailConfirmationErrors.cs:12, EmailConfirmationErrors.cs:15, EmailConfirmationErrors.cs:25, EmailConfirmationErrors.cs:33). The requests are SendEmailConfirmationRequest and ConfirmEmailRequest, guarded by SendEmailConfirmationRequestValidator and ConfirmEmailRequestValidator. A sibling constant class, AuthErrorCodes (MMCA.Common/Source/Core/MMCA.Common.Shared/Auth/AuthErrorCodes.cs:12), names the authentication outcomes a client has to branch on rather than merely display: Auth.EmailAlreadyExists (AuthErrorCodes.cs:19), returned identically by the registration pre-check and by the unique-index race recovery so the two paths stay indistinguishable, and Auth.TermsNotAccepted (AuthErrorCodes.cs:25), returned only when a current terms version is configured (next section).

Terms of Service acceptance: one version string, one rule set

Recording consent to a host's Terms of Service is opt-in the same way, and unset is the off switch. LegalAcceptanceOptions (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/Legal/LegalAcceptanceOptions.cs:12) binds from the Legal section (LegalAcceptanceOptions.cs:15) through AddLegalAcceptance(configuration) (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.Auth.cs:104-110) and carries a single value, CurrentTermsVersion (LegalAcceptanceOptions.cs:21). With no version configured, registration does not ask, the read endpoint reports every user as current, and the accept endpoint has nothing to accept (LegalAcceptanceOptions.cs:7-11); changing the version asks every signed-in user to accept again (LegalAcceptanceOptions.cs:17-20).

The rules live once, in LegalAcceptancePolicy (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/Legal/LegalAcceptancePolicy.cs:10), so the registration flow and the API controller base cannot apply them differently. ResolveCurrentVersion trims the configured value and treats null or whitespace as "none" (LegalAcceptancePolicy.cs:18-22). EnsureAcceptsCurrentVersion accepts only an ordinal match against a configured version (LegalAcceptancePolicy.cs:33-36), so a dialog left open across a version bump cannot record consent to text the user never saw (the client echoes the version it showed in AcceptLegalTermsRequest, MMCA.Common/Source/Core/MMCA.Common.Shared/Legal/AcceptLegalTermsRequest.cs:6-12). Normalize re-derives the standing from the accepted version and instant alone, so the answer never depends on a consumer filling the computed fields correctly (LegalAcceptancePolicy.cs:47-52). The standing is LegalAcceptanceDTO (MMCA.Common/Source/Core/MMCA.Common.Shared/Legal/LegalAcceptanceDTO.cs:18): current version, accepted version, accepted instant and IsCurrent (LegalAcceptanceDTO.cs:21, LegalAcceptanceDTO.cs:24, LegalAcceptanceDTO.cs:27, LegalAcceptanceDTO.cs:33), built through Evaluate, where an unconfigured version always yields IsCurrent = true so a client never blocks a user on a host that has not opted in (LegalAcceptanceDTO.cs:42-53, LegalAcceptanceDTO.cs:9-11).

Registration reads the version without a new constructor dependency: AuthenticationValidators takes the options as an optional parameter and exposes CurrentTermsVersion (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/AuthenticationValidators.cs:28, AuthenticationValidators.cs:43), which AuthenticationServiceBase<TUser> surfaces to its subclasses (AuthenticationServiceBase.cs:120). When a version is configured and the plain AcceptedTerms flag on RegisterRequest (MMCA.Common/Source/Core/MMCA.Common.Shared/Auth/Requests/RegisterRequest.cs:26) is false, RegisterAsync fails before the rate limit with LegalAcceptanceErrors.TermsNotAccepted (AuthenticationServiceBase.cs:236-239, MMCA.Common/Source/Core/MMCA.Common.Application/Auth/Legal/LegalAcceptanceErrors.cs:22-25); it is a flag rather than a version because the anonymous register page cannot read the version (AuthenticationServiceBase.cs:233-235). The app's CreateUser override then stamps the configured version on a user that implements ILegalAcceptingUser (AuthenticationServiceBase.cs:112-115), a Domain contract of two read-only properties and a Result-returning AcceptTerms that should treat the version already on record as an ordinary repeat (MMCA.Common/Source/Core/MMCA.Common.Domain/Auth/ILegalAcceptingUser.cs:21, ILegalAcceptingUser.cs:24, ILegalAcceptingUser.cs:27, ILegalAcceptingUser.cs:29-37). A user created outside RegisterAsync (the external-login path) is left unstamped and asked by the UI's acceptance gate on first sign-in (AuthenticationServiceBase.cs:116-117).

After registration the standing is read and recorded through ILegalAcceptanceService (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/Legal/ILegalAcceptanceService.cs:21), which each app implements over its own User (GetForCurrentUserAsync and AcceptForCurrentUserAsync, ILegalAcceptanceService.cs:28, ILegalAcceptanceService.cs:41). The version rules are explicitly not the implementation's job (ILegalAcceptanceService.cs:11-20): LegalAcceptanceControllerBase resolves the version, refuses an acceptance of any other version before the service is called, and normalizes every answer on the way out (MMCA.Common/Source/Presentation/MMCA.Common.API/Controllers/Legal/LegalAcceptanceControllerBase.cs:54, LegalAcceptanceControllerBase.cs:110, LegalAcceptanceControllerBase.cs:83, LegalAcceptanceControllerBase.cs:125). LegalAcceptanceRoutes (MMCA.Common/Source/Core/MMCA.Common.Shared/Legal/LegalAcceptanceRoutes.cs:7) declares the action template me/legal-acceptance and the full Users/me/legal-acceptance path the UI client calls, so the controller base and the client cannot drift (LegalAcceptanceRoutes.cs:13, LegalAcceptanceRoutes.cs:16). The two failure codes live where their callers can reach them: Auth.TermsNotAccepted on AuthErrorCodes because it is a registration outcome, and Legal.VersionNotCurrent on LegalAcceptanceErrorCodes (MMCA.Common/Source/Core/MMCA.Common.Shared/Legal/LegalAcceptanceErrorCodes.cs:7, LegalAcceptanceErrorCodes.cs:13), with LegalAcceptanceErrors aliasing both and building each as a validation error (LegalAcceptanceErrors.cs:14, LegalAcceptanceErrors.cs:17, LegalAcceptanceErrors.cs:33-36). Versioned, dated consent that a host can re-ask on a terms change is the [Rubric §30, Compliance/Privacy/Data Governance] reading of this cluster.

Reading identity from claims

Once a request is authenticated, downstream code needs the caller's identity without re-parsing the JWT, and it needs one answer no matter which pipeline produced the principal. That is the job of ClaimsPrincipalExtensions (MMCA.Common/Source/Core/MMCA.Common.Shared/Auth/ClaimsPrincipalExtensions.cs:18): FindUserIdValue reads the raw sub claim and falls back to the ClaimTypes.NameIdentifier form the JWT bearer handler maps it onto (ClaimsPrincipalExtensions.cs:26-28), GetUserId parses that value through IParsable<T> in the invariant culture so the solution-wide identifier alias can change shape without editing any reader (ClaimsPrincipalExtensions.cs:40-44), and FindSessionId reads the sid claim, treating absence as an ordinary "the caller's own device is unknown" rather than an error (ClaimsPrincipalExtensions.cs:109-113). AuthClaimTypes (MMCA.Common/Source/Core/MMCA.Common.Shared/Auth/AuthClaimTypes.cs:9) names the three claim types this group cares about: the framework-custom "permission" (AuthClaimTypes.cs:24) used by the authorization model below, plus the standard sub (AuthClaimTypes.cs:34) and sid (AuthClaimTypes.cs:47), each documented with the pipeline caveat that motivates reading it through the extensions.

CurrentUserService (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Context/CurrentUserService.cs:17) is the scoped adapter over IHttpContextAccessor: it exposes the ClaimsPrincipal, the parsed user id, and the first role claim, caching the parsed values behind a per-request Lazy<T> (CurrentUserService.cs:19-23) and reading the identifier through the shared extensions (CurrentUserService.cs:20). Its generic GetClaimValue<T> (CurrentUserService.cs:35) is what the ownership filter uses to read app-specific owner claims, and it parses in the invariant culture because claims are machine-written and the ambient request culture must not decide how a separator reads (CurrentUserService.cs:39-41). The interface itself, ICurrentUserService (MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/Infrastructure/Auth/ICurrentUserService.cs:9), carries the multi-role logic as default interface members: Roles reads every role claim across the three claim-type spellings the JWT middleware may produce and falls back to the single Role property when a hand-written double populates only that (ICurrentUserService.cs:45-64), and IsInRole does a case-insensitive membership check over that set (ICurrentUserService.cs:88-89). A sibling adapter, ClaimBasedUserIdProvider (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Context/ClaimBasedUserIdProvider.cs:11), plugs the same identifier into SignalR's IUserIdProvider so Clients.User(userId) routes hub messages to the right connections (ClaimBasedUserIdProvider.cs:14-15).

Authorization: permissions and ownership

There is one authorization model here, and it is capabilities, not role names. The single AddAuthorizationPolicies() extension in AuthorizationExtensions (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/AuthorizationExtensions.cs:14, AuthorizationExtensions.cs:62) wires the whole mechanism: the permission handler and the on-demand policy provider (AuthorizationExtensions.cs:71-73), the shared registry, built once and exposed under both IPermissionRegistry and IPermissionCatalog (AuthorizationExtensions.cs:128-129, AuthorizationExtensions.cs:135-136), and the fallback policy described at the end of this section. Role names still exist as data, but the framework ships no constant class naming them: roles get a value-object base, RoleValue (MMCA.Common/Source/Core/MMCA.Common.Shared/Auth/RoleValue.cs:26), so each app can fix its own role set with case-insensitive, type-guarded equality (RoleValue.cs:91-97), a frozen interned lookup (RoleValue.cs:76-85), and Result-returning validation (RoleValue.cs:43) while staying dependency-free enough to use from Blazor WASM. What no longer exists is a shipped policy per role: an endpoint states the capability it needs and the registry maps roles to capabilities (ADR-020).

HasPermissionAttribute (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/HasPermissionAttribute.cs:13) marks a controller or action with a permission such as "sessions:manage"; under the hood it is an AuthorizeAttribute whose policy name is perm:sessions:manage (PermissionPolicy.NameFor, MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/PermissionPolicy.cs:12, PermissionPolicy.cs:17, applied at HasPermissionAttribute.cs:17-18). Rather than pre-registering a named policy per permission, PermissionPolicyProvider (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/PermissionPolicyProvider.cs:13) materializes those policies on demand for any perm: name and falls through to the default provider for everything else (PermissionPolicyProvider.cs:31-47). The requirement it attaches, PermissionRequirement (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/PermissionRequirement.cs:10), is evaluated by PermissionAuthorizationHandler (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/PermissionAuthorizationHandler.cs:13), which grants access when the principal holds the permission directly (a permission claim) or derives it from one of its roles via IPermissionRegistry (PermissionAuthorizationHandler.cs:30-32, MMCA.Common/Source/Core/MMCA.Common.Shared/Auth/Permissions/IPermissionRegistry.cs:14), reading the caller's roles through ClaimsPrincipalExtensions.GetRoleValues (PermissionAuthorizationHandler.cs:30, MMCA.Common/Source/Core/MMCA.Common.Shared/Auth/ClaimsPrincipalExtensions.cs:59), which is the one place the three claim-type spellings the JWT middleware may produce are reconciled. The registry itself (PermissionRegistry, MMCA.Common/Source/Core/MMCA.Common.Shared/Auth/Permissions/PermissionRegistry.cs:16) is an immutable, frozen role-to-permission map with case-insensitive role keys and ordinal permission values (PermissionRegistry.cs:33-36) built by PermissionRegistryBuilder (MMCA.Common/Source/Core/MMCA.Common.Shared/Auth/Permissions/PermissionRegistryBuilder.cs:8); each module contributes only its own grants through AddPermissions(...) (AuthorizationExtensions.cs:105), duplicate grants union rather than collide (PermissionRegistryBuilder.cs:34), and the shared registry is built lazily on first resolve, after every module has registered (AuthorizationExtensions.cs:129, PermissionRegistryBuilder.cs:46). The same instance answers as IPermissionCatalog (PermissionRegistry.cs:16, PermissionRegistry.cs:55, PermissionRegistry.cs:58), explicitly implemented because a catalog's flat list of permission names and the registry's per-role lookup are different questions that would otherwise share a member name. That module-local contribution is the [Rubric §7, Microservices Readiness] touch: an extracted service carries only its own permission grants.

The same capabilities reach inside the CQRS pipeline, not just the HTTP boundary: a command or query that implements IRequiresPermission is checked by AuthorizationCommandDecorator<TCommand, TResult> and AuthorizationQueryDecorator<TQuery, TResult> against the same registry. Because those decorators are registered unconditionally, a host with no Identity module and no grants would fail to activate every handler in the pipeline, which is what UnconfiguredPermissionRegistry (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/UnconfiguredPermissionRegistry.cs:20) exists to prevent: it is registered with TryAdd, so a host that called AddAuthorizationPolicies() keeps its own registry and never constructs this one (MMCA.Common/Source/Core/MMCA.Common.Application/DependencyInjection.cs:123). It grants nothing, so a permission-gated request is denied rather than allowed (UnconfiguredPermissionRegistry.cs:37, UnconfiguredPermissionRegistry.cs:44), and it says so exactly once, through an interlocked one-shot flag, in a log message naming the call that would fix it (UnconfiguredPermissionRegistry.cs:25, UnconfiguredPermissionRegistry.cs:60, UnconfiguredPermissionRegistry.cs:68). The warning is deferred to the first real check rather than raised at startup, because a host with no permission-gated request is correctly configured: it simply never needs a registry (UnconfiguredPermissionRegistry.cs:13-19). Fail-closed plus a diagnosable message is the [Rubric §11, Security] and [Rubric §13, Observability & Operability] reading of that type.

The second style is resource ownership. OwnerOrAdminFilter (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnerOrAdminFilter.cs:31) is an action filter for endpoints that mix admin and owner access (carts, orders, bookmarks). It lets a bypass role through (OwnerOrAdminFilter.cs:43), then compares the caller's owner claim against the resource id taken from either the route or a bound argument (OwnerOrAdminFilter.cs:49, OwnerOrAdminFilter.cs:93-111), returning 403 otherwise. The important property is that it denies by default: when the owner claim is missing (OwnerOrAdminFilter.cs:51-55) or the owner parameter cannot be resolved at all, the request is rejected rather than waved through (OwnerOrAdminFilter.cs:57-71), because "nothing to compare" must not read as "nothing to enforce". An action that legitimately has no owner parameter opts out explicitly with AllowMissingOwnerAttribute (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/AllowMissingOwnerAttribute.cs:21), honored from either the action or its declaring controller via endpoint metadata (OwnerOrAdminFilter.cs:82-85, AllowMissingOwnerAttribute.cs:20), and the attribute's own remarks require the application site to name the guard that replaces the check (AllowMissingOwnerAttribute.cs:15-19). The filter's vocabulary (claim type, bypass role, route parameter) is configurable through OwnerOrAdminFilterOptions (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnerOrAdminFilterOptions.cs:13) whose defaults preserve the original customer_id / Admin / id behavior (OwnerOrAdminFilterOptions.cs:16-31, ADR-033), with OwnershipHelper (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnershipHelper.cs:11) supplying both the bypass-role check (OwnershipHelper.cs:18) and the query-scoping specification factory that controllers use to narrow collection endpoints to the caller's own rows (OwnershipHelper.cs:35-68).

Compiled grants are the baseline, not the ceiling. A host that needs an operator to move a capability between roles without a redeploy calls AddStoredPermissionGrants(configuration) (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.Auth.cs:139), which binds PermissionGrantSettings (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/Permissions/PermissionGrantSettings.cs:12, bound at DependencyInjection.Auth.cs:141-144), registers the EF-backed IPermissionGrantStore (DependencyInjection.Auth.cs:149), and decorates the compiled registry with LayeredPermissionRegistry (DependencyInjection.Auth.cs:170-181). The layering rule is a union with no deny row: a role holds a permission when either the compiled registry or the stored grants say so (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/Permissions/LayeredPermissionRegistry.cs:30, LayeredPermissionRegistry.cs:55-65), so a bad edit can add a capability but can never take away one an endpoint's own module declared. Because HasPermission is synchronous, the stored half cannot be read from the database on the hot path: IPermissionGrantCache (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/Permissions/IPermissionGrantCache.cs:21) is the boundary over an in-memory snapshot, refreshed on demand (IPermissionGrantCache.cs:37, IPermissionGrantCache.cs:11-19), and IPermissionGrantCacheInvalidator (IPermissionGrantCache.cs:53, IPermissionGrantCache.cs:61) is what an edit calls. The consequence a host accepts is that a grant edit reaches other replicas within CacheSeconds (default 300, PermissionGrantSettings.cs:25), with DataSourceName naming the one database that carries the rows (PermissionGrantSettings.cs:33), exactly as RefreshSessionSettings does. The row itself, PermissionGrant (MMCA.Common/Source/Core/MMCA.Common.Domain/Auth/PermissionGrant.cs:24), is a two-column identity (PermissionGrant.cs:39, PermissionGrant.cs:45) trimmed and length-validated in a Result-returning factory (PermissionGrant.cs:64, widths at PermissionGrant.cs:27 and PermissionGrant.cs:30), and its table is mapped only for the host that opted in, through a model gate whose mere registration is the opt-in the context reads (DependencyInjection.Auth.cs:147).

The administration API sits on top of the same grants. IRoleAdministrationService (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/Administration/IRoleAdministrationService.cs:29) lists roles, reads one role, returns the catalog of role and permission names, and replaces a role's stored grants (IRoleAdministrationService.cs:37, IRoleAdministrationService.cs:45, IRoleAdministrationService.cs:58, IRoleAdministrationService.cs:72); it ships filled in as StoredPermissionRoleAdministrationService (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Auth/Administration/StoredPermissionRoleAdministrationService.cs:45, its four methods at :54, :80, :93, :114) because both halves of that surface are framework-owned. The user half cannot be: IUserAdministrationService<TUserDto> (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/Administration/IUserAdministrationService.cs:24) is generic in the app's own DTO, constrained by the marker IUserAdminDTO (MMCA.Common/Source/Core/MMCA.Common.Shared/Auth/Administration/IUserAdminDTO.cs:15), and each app implements listing, reading, locking and role assignment over its own User (IUserAdministrationService.cs:32, IUserAdministrationService.cs:42, IUserAdministrationService.cs:57, IUserAdministrationService.cs:66), with UserAdministrationQuery (IUserAdministrationService.cs:79) carrying the paging and filter arguments. The two capabilities that gate the whole surface are named once in AdministrationPermissions (MMCA.Common/Source/Core/MMCA.Common.Shared/Auth/Permissions/AdministrationPermissions.cs:15): users:manage and roles:manage (AdministrationPermissions.cs:18, AdministrationPermissions.cs:21). The wire shapes are SetUserRolesRequest, SetRolePermissionsRequest, RolePermissionsResponse and PermissionCatalogResponse, each guarded by its own FluentValidation rule (SetUserRolesRequestValidator, SetRolePermissionsRequestValidator).

The last piece of the authorization wiring is defensive rather than declarative. AddAuthorizationPolicies() installs a fallback policy, so an endpoint carrying no authorization metadata at all is denied rather than served. The requirement is its own type, FallbackAuthorizationRequirement (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/Fallback/FallbackAuthorizationRequirement.cs:16), and FallbackAuthorizationHandler (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/Fallback/FallbackAuthorizationHandler.cs:32) grants it to an authenticated caller, to a request whose path matches one of the exempt prefixes, to a request that matched no endpoint and names no web-root file (so the host's not-found page renders a 404 instead of a sign-in redirect), and to a request routed to an API-versioning rejection endpoint (so the caller gets the 400 version error rather than a 401 challenge) (FallbackAuthorizationHandler.cs:46-51, rationale at FallbackAuthorizationHandler.cs:16-28). A bare RequireAuthenticatedUser() would not do, because a Blazor host maps endpoint-routed static and framework surfaces that carry no metadata of their own and would be gated along with everything else (FallbackAuthorizationRequirement.cs:11-15), which is why the requirement is path-aware. FallbackAuthorizationOptions (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/Fallback/FallbackAuthorizationOptions.cs:14) carries the Enabled switch (on by default, FallbackAuthorizationOptions.cs:52) and the editable exempt-prefix list seeded from the framework defaults (FallbackAuthorizationOptions.cs:64); the handler is registered with TryAddEnumerable and the policy attached only while the switch is set (AuthorizationExtensions.cs:82-83, AuthorizationExtensions.cs:88-91).

Session cookies: keeping SSR authenticated

The final cluster solves a Blazor-specific problem: an interactive Blazor app keeps its access token in browser memory, but a cold server-side render (a new tab, an F5, an external deep link) has no memory to read, so an [Authorize] page would bounce to /login before the interactive phase starts. The fix is a pair of HttpOnly cookies (mmca_auth_access, mmca_auth_refresh, MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/SessionCookieEndpoints.cs:18-19) seeded and cleared from JS through SessionCookieEndpoints (SessionCookieEndpoints.cs:16, SessionCookieEndpoints.cs:35-45, request body SessionCookieRequest at SessionCookieEndpoints.cs:95), written with one shared set of attributes by SessionCookieJar (MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/SessionCookieJar.cs:14: HttpOnly, Secure outside Development, Path=/, SameSite from SessionCookieSettings, Lax by default and Strict on the same-origin API proxy, MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/SessionCookieSettings.cs:19, and a max age resolved from SessionCookieSettings.Lifetime, else the configured refresh-token lifetime, else 7 days, because a cookie must not outlive the credential it carries, SessionCookieJar.cs:30-48, SessionCookieJar.cs:61-67, SessionCookieSettings.cs:38), and read during prerender by CookieTokenReader (MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/CookieTokenReader.cs:10). SessionCookieAuthenticationHandler (MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/SessionCookieAuthenticationHandler.cs:24) is a custom authentication scheme that reads the cookie JWT, checks only its expiry against the handler's injectable TimeProvider (SessionCookieAuthenticationHandler.cs:55) because the API still performs full validation on every API call (SessionCookieAuthenticationHandler.cs:18-23), and populates HttpContext.User so SSR authorization passes (SessionCookieAuthenticationHandler.cs:60-63); a challenge redirects to /login with a returnUrl (SessionCookieAuthenticationHandler.cs:72-77). It is registered through SessionCookieAuthenticationExtensions (SessionCookieAuthenticationHandler.cs:90).

When the access cookie has expired but the refresh cookie is still valid, CookieSessionRefreshMiddleware (MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/CookieSessionRefreshMiddleware.cs:13, registered by CookieSessionRefreshMiddlewareExtensions at CookieSessionRefreshMiddleware.cs:35) runs before UseAuthentication on qualifying navigations (GET plus an Accept header containing text/html, CookieSessionRefreshMiddleware.cs:28-31) and delegates to CookieSessionRefresher (MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/CookieSessionRefresher.cs:75) through the ICookieSessionRefresher port (CookieSessionRefresher.cs:32). The refresher first tries to read a still-valid expiry out of the access cookie with a 30-second skew allowance (CookieSessionRefresher.cs:85, CookieSessionRefresher.cs:243-272); failing that it exchanges the refresh cookie at the API's auth/refresh endpoint server-to-server (CookieSessionRefresher.cs:186-192), so the refresh token never reaches browser JS. That call carries the browser's user-agent and IP, captured from the triggering request by the private BrowserOrigin before the lock is taken, so the rotated session records the real device instead of this host's empty user-agent and loopback address (CookieSessionRefresher.cs:136, CookieSessionRefresher.cs:190, CookieSessionRefresher.cs:283-297). It then writes the rotated pair back as cookies and stashes the fresh access token on HttpContext.Items (CookieSessionRefresher.cs:143-147) so the current request's authentication reads the new token: CookieTokenReader checks that item before falling back to the request cookie (CookieTokenReader.cs:17, CookieTokenReader.cs:27-33). Concurrent refreshes are collapsed into a single flight by a KeyedSemaphoreStripe keyed on the refresh token plus a 10-second rotation-grace IMemoryCache entry keyed by the old refresh token (CookieSessionRefresher.cs:86, CookieSessionRefresher.cs:88, CookieSessionRefresher.cs:151-168, CookieSessionRefresher.cs:208), so a queued herd of requests cannot double-rotate. Striping rather than one process-wide lock is deliberate and stated in source: the lock is held across an outbound HTTP call, so a single semaphore serialized every unrelated user's cold navigation behind whichever refresh was in flight (CookieSessionRefresher.cs:68-73); two unrelated tokens sharing a stripe is harmless because the grace cache is re-checked per token after acquiring (CookieSessionRefresher.cs:161-165). Failures are kept apart as a SessionRefreshOutcome carrying a SessionRefreshStatus: only a 400, 401 or 403 from the identity endpoint is Rejected (the session is over), while anything else, including the 409 Auth.RefreshSuperseded answer to a rotation race, is Unavailable, so a caller that clears cookies on failure does so only for a session that is really dead (CookieSessionRefresher.cs:114-126, CookieSessionRefresher.cs:41-49). A transport failure, including the resilience pipeline's own refusals, is not cached and renders the request anonymously rather than throwing a 500 out of SSR (CookieSessionRefresher.cs:175-181, CookieSessionRefresher.cs:211-219). The same refresher backs the same-origin POST /auth/session/token endpoint the browser polls to hydrate its in-memory token (SessionCookieEndpoints.cs:60-82), guarded by the cookies' configured SameSite plus a Sec-Fetch-Site cross-site rejection (SessionCookieEndpoints.cs:63-66, SessionCookieEndpoints.cs:88-93); a host that sets ClaimsOnlyBrowserTokens hands the browser an unsigned copy of the claims built by SessionClaimsToken rather than the credential (SessionCookieEndpoints.cs:74-77, SessionCookieSettings.cs:29). The endpoint returns SessionTokenResponse (CookieSessionRefresher.cs:23), the browser-safe projection of the internal SessionTokenResult (CookieSessionRefresher.cs:17) that deliberately omits the refresh token. This whole cluster is ADR-022's server half; the client half across Blazor Server, WASM, and MAUI is ADR-051.

Privacy: the data-subject export package

Three members of this group belong to the privacy surface that sits beside erasure. UserDataExportDTO (MMCA.Common/Source/Core/MMCA.Common.Shared/Privacy/UserDataExportDTO.cs:15) is the portable GDPR/CCPA export envelope: a document FormatVersion consumers read before parsing (UserDataExportDTO.cs:22), the generation instant, the subject id, an app-owned Subject snapshot typed as object so each app decides which of its own fields are portable (UserDataExportDTO.cs:40), and an ordered list of UserDataExportSectionDTO envelopes (UserDataExportDTO.cs:48, UserDataExportDTO.cs:61). Each section reports Available explicitly (UserDataExportDTO.cs:72) so a reader can tell "this subject has no data here" apart from "this contributor could not be reached", and an unavailable section carries only a caller-safe reason string, never an exception message or a connection string (UserDataExportDTO.cs:88). One failing contributor therefore degrades one section instead of denying the subject their whole export, which is the [Rubric §30, Compliance/Privacy/Data Governance] point of the shape. PrivacyFeatures (MMCA.Common/Source/Core/MMCA.Common.Shared/Privacy/PrivacyFeatures.cs:8) holds the single flag name Privacy.DataExport (PrivacyFeatures.cs:12) that keeps the whole surface off until a host turns it on, applied as a [FeatureGate] on DataExportControllerBase<TQuery>. The composing workflow (ExportUserDataHandlerBase<TUser, TQuery> and the IUserDataExportSection contributors) lives in group 14 (ADR-076).

Shared primitives and adjacent members

Several group members are general-purpose primitives that landed in this chapter because of how the dependency grouping fell, though one of them is now load-bearing for auth. KeyedSemaphoreStripe (MMCA.Common/Source/Core/MMCA.Common.Shared/Concurrency/KeyedSemaphoreStripe.cs:22) and its Releaser handle (KeyedSemaphoreStripe.cs:78) serialize work per logical key across a fixed set of semaphores (256 by default, KeyedSemaphoreStripe.cs:25, with an explicit-width constructor at KeyedSemaphoreStripe.cs:37; acquisition maps the key onto one stripe at KeyedSemaphoreStripe.cs:60-75). That is the bounded alternative to a semaphore-per-key dictionary, which forces a choice between two defects: removing the entry on release opens a window where one caller waits on a semaphore no longer in the table while another creates a fresh one, and never removing it lets caller-supplied keys grow the table without bound (KeyedSemaphoreStripe.cs:7-16). Its consumers today are CookieSessionRefresher (above, CookieSessionRefresher.cs:88), the IdempotencyFilter (MMCA.Common/Source/Presentation/MMCA.Common.API/Idempotency/IdempotencyFilter.cs:91), CachingQueryDecorator<TQuery, TResult> (MMCA.Common/Source/Core/MMCA.Common.Application/UseCases/Decorators/CachingQueryDecorator.cs:250), MemoryCacheService (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Caching/MemoryCacheService.cs:45), and the default GetOrCreateAsync lock table on ICacheService (MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/ICacheService.cs:199). InProcessDistributedLock is the deliberate exception: it keys on the exact key in a ConcurrentDictionary instead, because its contract has a bounded wait, and stripe false-sharing would turn that into a spurious "held elsewhere" answer for a key nobody holds (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Concurrency/InProcessDistributedLock.cs:19-24).

Three HTTP and convention helpers sit in MMCA.Common.Shared for the same structural reason: both ends of an exchange need them and the two packages do not reference each other. IdempotencyHeaders (MMCA.Common/Source/Core/MMCA.Common.Shared/Http/IdempotencyHeaders.cs:13) is a two-constant class holding Idempotency-Key and X-Idempotent-Replay, read by the API filter and written by the UI service bases (IdempotencyHeaders.cs:19, IdempotencyHeaders.cs:25). ConcurrencyETag (MMCA.Common/Source/Core/MMCA.Common.Shared/Http/ConcurrencyETag.cs:24) translates between the EF Core rowversion token and the HTTP entity tag that represents it: Format renders the base64 of the raw token as a weak tag (ConcurrencyETag.cs:40-45), weak on purpose because the same row version renders differently under a fields= projection and a strong tag would be promising byte-for-byte equality it cannot deliver (ConcurrencyETag.cs:12-18), and the parse side tolerates the weak prefix and the quotes while treating a blank value, the * wildcard, and a non-base64 payload alike as "no concrete token" for the caller to classify (ConcurrencyETag.cs:27-33, ConcurrencyETag.cs:52-60). ProblemDetailsResultReader (MMCA.Common/Source/Core/MMCA.Common.Shared/Http/ProblemDetailsResultReader.cs:58) is the client-side inverse of the API's error contract: it turns a response body back into Error values, synthesizing a status-derived code (Http.404 and friends, ProblemDetailsResultReader.cs:65) when the payload carries no machine-readable code, and it is explicit that the reverse mapping is lossy for 400, where Validation, Invariant and Failure all collapse onto one status (ProblemDetailsResultReader.cs:50-56). ModuleNameConventions (MMCA.Common/Source/Core/MMCA.Common.Shared/Conventions/ModuleNameConventions.cs:10) derives a type's owning module from its namespace under the MMCA.{App}.{Module}.{Layer} convention (ModuleNameConventions.cs:38-45); it lives in Shared because both persistence (schema and data-source names) and the Application-layer CQRS logging decorators need it, and Application may not reference Infrastructure (ModuleNameConventions.cs:6-8). Its layer list deliberately omits Shared (ModuleNameConventions.cs:17) so a framework namespace never resolves to a phantom module. IcsEvent and IcsCalendarBuilder (MMCA.Common/Source/Core/MMCA.Common.Shared/Calendars/IcsEvent.cs:15, MMCA.Common/Source/Core/MMCA.Common.Shared/Calendars/IcsCalendarBuilder.cs:12) build RFC 5545 calendar (.ics) exports from UTC-normalized event times, with 75-octet line folding and CRLF endings (IcsCalendarBuilder.cs:14 for the MaxLineOctets budget; the folding and the \r\n writes both live in AppendLine, IcsCalendarBuilder.cs:83-104).

Two further Shared clusters land here the same way. The feature-flag lifecycle metadata closes the flag-debt trade-off of ADR-031: FeatureFlagAttribute (MMCA.Common/Source/Core/MMCA.Common.Shared/FeatureFlags/FeatureFlagAttribute.cs:32) is applied to the public const string fields of a *Features class (FeatureFlagAttribute.cs:9, FeatureFlagAttribute.cs:31) and carries a FeatureFlagLifetime (MMCA.Common/Source/Core/MMCA.Common.Shared/FeatureFlags/FeatureFlagLifetime.cs:9), an optional RemoveBy date in a fixed yyyy-MM-dd format, and an owner (FeatureFlagAttribute.cs:35, FeatureFlagAttribute.cs:38, FeatureFlagAttribute.cs:46, FeatureFlagAttribute.cs:52). The distinction is the whole point: a Permanent flag is a capability a host chooses to run with or without and must not carry a removal date, while a Temporary one exists only until a migration or experiment finishes, must carry one, and fails the build once that date has passed (FeatureFlagLifetime.cs:11-20). FeatureFlagRegistry (MMCA.Common/Source/Core/MMCA.Common.Shared/FeatureFlags/FeatureFlagRegistry.cs:35) is the runtime half, reflecting over assemblies to project every declared flag into a FeatureFlagDescriptor (FeatureFlagRegistry.cs:17, FeatureFlagRegistry.cs:46, FeatureFlagRegistry.cs:64) with the two recognizers the fitness rules also use (FeatureFlagRegistry.cs:77, FeatureFlagRegistry.cs:91). PrivacyFeatures above is one of the framework's own annotated flags.

The strongly typed identifier capability is the opt-in wrapper struct of ADR-115, shipped complete and adopted by nothing, with the ADR-048 primitive aliases left as the default. IStronglyTypedId<TSelf, TValue> (MMCA.Common/Source/Core/MMCA.Common.Shared/Identifiers/IStronglyTypedId.cs:60) is two members, a Value getter and a static abstract From (IStronglyTypedId.cs:65, IStronglyTypedId.cs:72), so a wrapper is a positional readonly record struct plus one factory line; IParsable<TSelf> arrives as explicit default implementations, which is the only form an inherited static abstract member allows, so OrderId.Parse(...) does not compile and every framework boundary parses through the interface (IStronglyTypedId.cs:25-36). The static helper StronglyTypedId (MMCA.Common/Source/Core/MMCA.Common.Shared/Identifiers/StronglyTypedId.cs:19) is what those boundaries call: Parse/TryParse (StronglyTypedId.cs:40, StronglyTypedId.cs:63), the CanParseValues and GetValueType/IsStronglyTypedId reflection probes (StronglyTypedId.cs:85, StronglyTypedId.cs:97, StronglyTypedId.cs:108), and TryDescribe (StronglyTypedId.cs:118), with the per-primitive delegate cache StronglyTypedIdValueParser<TValue> and its StronglyTypedIdValueParserDelegate<TValue> (StronglyTypedId.cs:173, StronglyTypedId.cs:161) keeping the reflection off the hot path. Each boundary then gets one adapter: JSON through StronglyTypedIdJsonConverterFactory and its private StronglyTypedIdConverter<TSelf, TValue> (MMCA.Common/Source/Core/MMCA.Common.Shared/Identifiers/StronglyTypedIdJsonConverterFactory.cs:22, StronglyTypedIdJsonConverterFactory.cs:25, StronglyTypedIdJsonConverterFactory.cs:38), MVC route and query binding through StronglyTypedIdTypeConverter<TSelf, TValue> and the StronglyTypedIdTypeConverters registrar (MMCA.Common/Source/Core/MMCA.Common.Shared/Identifiers/StronglyTypedIdTypeConverter.cs:21, StronglyTypedIdTypeConverter.cs:82, StronglyTypedIdTypeConverter.cs:89, StronglyTypedIdTypeConverter.cs:119), object mapping through StronglyTypedIdMappings<TSelf, TValue>, whose four static methods are the contract because Mapperly discovers them by signature on a closed generic type (MMCA.Common/Source/Core/MMCA.Common.Shared/Identifiers/StronglyTypedIdMappings.cs:31, StronglyTypedIdMappings.cs:38-53), and discovery through StronglyTypedIdRegistry (MMCA.Common/Source/Core/MMCA.Common.Shared/Identifiers/StronglyTypedIdRegistry.cs:22), which scans assemblies up front and hands out the type list (StronglyTypedIdRegistry.cs:28, StronglyTypedIdRegistry.cs:66, StronglyTypedIdRegistry.cs:73) because EF needs it before any entity exists. One more Shared constant class rounds the group out: MessageHeaders (MMCA.Common/Source/Core/MMCA.Common.Shared/Messaging/MessageHeaders.cs:22) names the four MMCA--prefixed transport headers a message carries across a boundary (tenant, user, roles, and correlation id, MessageHeaders.cs:25-34), so a publisher and a consumer in different services spell them identically.

Two genuine auth members sit at the edge of the group. ISoftDeletedUserValidator (MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/Infrastructure/Auth/ISoftDeletedUserValidator.cs:7) is the small contract the API's SoftDeletedUserMiddleware uses to reject an otherwise-valid token whose backing account has since been soft-deleted (BR-133, ADR-047), implemented by each Identity module so Common never takes a cross-module domain reference. Its fast path is SoftDeletedUserCache (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/SoftDeletedUserCache.cs:17), which owns both the key shape and the 15-minute marker lifetime (SoftDeletedUserCache.cs:32, SoftDeletedUserCache.cs:45) so the module that deletes an account writes exactly the key the middleware reads. The marker has to outlive every access token issued before the delete, because a host that does not run Identity registers no validator query and the marker is the only thing that rejects a deleted user's still-valid token there; it therefore matches the default access-token lifetime, and a host that raises that lifetime writes its own marker with a matching duration (SoftDeletedUserCache.cs:22-31). The key is formatted invariantly on purpose, because a culture-sensitive identifier would be written under one request's culture and missed under another (SoftDeletedUserCache.cs:39-46). The controller surface that drives everything above (AuthControllerBase, OAuthControllerBase, UserAccountAuthControllerBase<TChangePasswordCommand, TChangePreferencesCommand>, PasswordResetAuthControllerBase<TForgotPasswordCommand, TResetPasswordCommand>, ExternalAuthExtensions) and the gRPC token forwarding (JwtForwardingClientInterceptor) live in later groups; this chapter is the engine those endpoints call into.

AllowMissingOwnerAttribute

MMCA.Common.API · MMCA.Common.API.Authorization · MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/AllowMissingOwnerAttribute.cs:21 · Level 0 · class (sealed attribute, marker)

• What it is: a marker attribute placed on an action or a whole controller to declare that the action legitimately has no owner parameter, exempting it from OwnerOrAdminFilter's requirement that the request carry a resolvable owner identifier.
• Depends on: nothing first-party; System.Attribute and AttributeUsageAttribute (BCL). It is read (never constructed) by OwnerOrAdminFilter.
• Concept introduced, the explicit opt-out that makes deny-by-default safe. [Rubric §11, Security] (assesses whether a guard fails closed rather than open) and [Rubric §34, Architecture Governance & Documentation] (assesses whether a deliberate exemption is written down where it applies, so it can be audited later). The filter this attribute exempts from denies the request when it cannot resolve an owner parameter, because "no owner to compare" must not read as "no restriction" (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/AllowMissingOwnerAttribute.cs:6-13). Deny-by-default only works if the genuinely parameter-less actions have a way to say so, and that is the entire job of this type. The doc comment names the two shapes that qualify: a collection endpoint whose rows are already narrowed to the caller by an ownership specification, and an action restricted to administrators by its own authorization policy (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/AllowMissingOwnerAttribute.cs:9-12).
• Walkthrough: the whole type is its [AttributeUsage] declaration plus an empty body (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/AllowMissingOwnerAttribute.cs:20-23). AttributeTargets.Class | AttributeTargets.Method allows both controller-wide and per-action application; AllowMultiple = false because a second copy would mean nothing; Inherited = true so a controller base class can carry it. It holds no data: presence in the endpoint metadata is the entire signal, which is exactly what OwnerOrAdminFilter.HasAllowMissingOwner looks for (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnerOrAdminFilter.cs:84-85).
• Why it's built this way: an empty marker keeps the opt-out cheap to apply and impossible to mis-configure, but the <remarks> block (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/AllowMissingOwnerAttribute.cs:15-19) is the load-bearing half of the design: applying it is an assertion that the action is guarded elsewhere, so every application site is expected to name the replacement guard in a comment. That turns a silent hole into a reviewable claim (ADR-033 records the audit that produced the current application sites).
• Where it's used: honored by OwnerOrAdminFilter through endpoint metadata. In MMCA.Store it marks four actions on MMCA.Store/Source/Modules/Sales/MMCA.Store.Sales.API/Controllers/ShoppingCartsController.cs:92,107,136,172 and six on MMCA.Store/Source/Modules/Identity/MMCA.Store.Identity.API/Controllers/CustomersController.cs:53,65,82,114,135,150, both controllers naming the replacing guard in an inline comment next to the attribute (ShoppingCartsController.cs:87-92, CustomersController.cs:51-53).
• Caveats / not-in-source: nothing enforces the assertion. No analyzer or compile-time rule checks that an action carrying this attribute really is guarded another way; the guarantee is a review convention. Store closes the specific gap it opens with a hand-written RequireResolvableOwner() gate on the collection reads (ShoppingCartsController.cs:79-84), but that gate is per-controller code, not something the attribute demands.

FallbackAuthorizationOptions

MMCA.Common.API · MMCA.Common.API.Authorization.Fallback · MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/Fallback/FallbackAuthorizationOptions.cs:14 · Level 0 · class (options)

• What it is: a host-configurable options object controlling the framework's fallback authorization policy, whether it runs at all and which request path prefixes it never gates.
• Depends on: nothing first-party.
• Concept introduced, deny-by-default as the ASP.NET Core FallbackPolicy. [Rubric §11, Security] (assesses whether an endpoint with no authorization metadata fails closed rather than publishing itself anonymously) and [Rubric §17, DevOps & Deployment] (assesses whether the rule ships with a documented, code-level opt-out rather than forcing every host to fork it). An endpoint that declares neither [Authorize] nor [AllowAnonymous] used to be anonymous by omission; this options type is what a host tunes before flipping that default.
• Walkthrough: DefaultExemptPathPrefixes (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/Fallback/FallbackAuthorizationOptions.cs:21-44) is a static, read-only seed list of framework and static surfaces that are endpoint-routed but carry no authorization metadata of their own: Blazor's framework files and circuit (/_framework, /_blazor, /_content, /_vs), health probes (/health, /alive), well-known documents (/.well-known, /robots.txt, /sitemap.xml, /manifest.json, /site.webmanifest, /service-worker.js, /apple-app-site-association), and static asset roots (/css, /js, /lib, /images, /img, /fonts, /media, /favicon.ico). Enabled (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/Fallback/FallbackAuthorizationOptions.cs:52) defaults to true; the doc comment states the opt-out is deliberate (AddAuthorizationPolicies(options => options.Enabled = false)) rather than by omission (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/Fallback/FallbackAuthorizationOptions.cs:47-49). ExemptPathPrefixes (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/Fallback/FallbackAuthorizationOptions.cs:64) is a mutable IList<string> seeded with [.. DefaultExemptPathPrefixes], so a host appends its own static roots without losing the framework defaults; the doc comment is explicit that application endpoints belong on [AllowAnonymous], not in this list, because that is what the anonymous-endpoint fitness gate reads (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/Fallback/FallbackAuthorizationOptions.cs:58-59).
• Why it's built this way: matching is segment-based and case-insensitive against these prefixes (per the ExemptPathPrefixes doc comment), so a coarse prefix like /_framework covers everything beneath it without enumerating individual asset paths.
• Caveats / not-in-source: the exemption is purely path-based. An undecorated controller routed under one of these prefixes would pass ungated, and the doc comment names AnonymousEndpointTestsBase.Endpoints_DeclareAnAuthorizationDecision as the gate that keeps such a controller from landing (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/Fallback/FallbackAuthorizationOptions.cs:59-62). That test is off by default, so a repo only gets this protection once it opts into the stricter gate (MMCA.Common/Source/Hosting/MMCA.Common.Testing.Architecture/Bases/Api/AnonymousEndpointTestsBase.cs:55-56,118).
• Where it's used: bound via services.AddOptions<FallbackAuthorizationOptions>() and read by FallbackAuthorizationHandler inside AuthorizationExtensions.AddAuthorizationPolicies.

FallbackAuthorizationRequirement

MMCA.Common.API · MMCA.Common.API.Authorization.Fallback · MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/Fallback/FallbackAuthorizationRequirement.cs:16 · Level 0 · class (sealed)

• What it is: the marker IAuthorizationRequirement attached to the framework's fallback authorization policy.
• Depends on: Microsoft.AspNetCore.Authorization.IAuthorizationRequirement (framework).
• Concept introduced, the requirement half of the fallback requirement/handler pair. [Rubric §11, Security] and [Rubric §2, Design Patterns] (assesses whether the ASP.NET Core requirement/handler split is used as designed even for a policy with no data of its own). Unlike PermissionRequirement, this requirement carries no permission string: the whole type is a one-line marker, public sealed class FallbackAuthorizationRequirement : IAuthorizationRequirement; (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/Fallback/FallbackAuthorizationRequirement.cs:16).
• Walkthrough: no members; presence in a policy's requirement list is the entire signal FallbackAuthorizationHandler reacts to.
• Why it's built this way: a data-free requirement is enough here because the decision (is the caller authenticated, or is the path exempt) needs no configuration carried on the requirement itself; the configuration instead lives on FallbackAuthorizationOptions, injected into the handler.
• Where it's used: attached to the built-in AuthorizationPolicy set as ASP.NET Core's AuthorizationOptions.FallbackPolicy by AuthorizationExtensions.AddAuthorizationPolicies when FallbackAuthorizationOptions.Enabled is true, and evaluated by FallbackAuthorizationHandler.

OwnerOrAdminFilterOptions

MMCA.Common.API · MMCA.Common.API.Authorization · MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnerOrAdminFilterOptions.cs:13 · Level 0 · class (options)

• What it is: a host-configurable options object that supplies the three vocabulary values OwnerOrAdminFilter needs: which claim carries the caller's owner id, which role bypasses the ownership check, and which route or argument parameter names the resource owner.
• Depends on: nothing first-party; System.ComponentModel.DataAnnotations for [Required].
• Concept introduced, externalizing a filter's vocabulary through the options pattern. [Rubric §11, Security] (assesses whether the ownership rule is enforced consistently; here the rule is fixed in code while its identifiers are configuration, and the bypass role is required rather than defaulted) and [Rubric §15, Best Practices & Code Quality] (assesses whether a second host can reuse a component without forking it). The class doc comment (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnerOrAdminFilterOptions.cs:5-12) states the current shape: the claim and route parameter keep the framework's conventional names (customer_id and id), but the bypass role has no default because the framework knows no role names, so a host that applies the filter configures its own role through services.Configure<OwnerOrAdminFilterOptions>(o => o.BypassRole = MyRoleNames.Admin), and a host that never applies the filter configures nothing.
• Walkthrough: three mutable auto-properties. OwnerClaimType still defaults to "customer_id" (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnerOrAdminFilterOptions.cs:16). BypassRole now carries [Required] and defaults to string.Empty, not "Admin" (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnerOrAdminFilterOptions.cs:23-24); its doc comment states the options are validated against their data annotations on first resolve, so a host that applies the filter without naming a role fails loudly instead of silently bypassing for nobody (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnerOrAdminFilterOptions.cs:19-22). OwnerParameterName still defaults to "id" (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnerOrAdminFilterOptions.cs:31); its doc comment (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnerOrAdminFilterOptions.cs:26-30) spells out that the parameter is looked up as a route value first and a model-bound query or body argument second, which is exactly the two-step lookup the filter performs.
• Why it's built this way: get; set; (not init) is the shape the ASP.NET Core options binder expects, so the values can arrive from appsettings or a Configure callback; requiring BypassRole rather than defaulting it to "Admin" means a host cannot silently ship a filter that bypasses for a role it never granted to anyone.
• Where it's used: injected as IOptions<OwnerOrAdminFilterOptions> into OwnerOrAdminFilter (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnerOrAdminFilter.cs:33). MMCA.ADC's Engagement module is the host that configures it rather than taking the defaults, pointing the shared filter at ClaimTypes.NameIdentifier, the Organizer bypass role, and a userId parameter (MMCA.ADC/Source/Modules/Engagement/MMCA.ADC.Engagement.API/DependencyInjection.cs:45,53-55); the comment above those assignments explains why NameIdentifier and not the raw sub claim is the type the principal actually carries by the time the filter runs (MMCA.ADC/Source/Modules/Engagement/MMCA.ADC.Engagement.API/DependencyInjection.cs:47-52).

PermissionPolicy

MMCA.Common.API · MMCA.Common.API.Authorization · MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/PermissionPolicy.cs:9 · Level 0 · class (static)

• What it is: the naming convention that turns a permission string such as "sessions:manage" into the ASP.NET Core policy name "perm:sessions:manage", and back.
• Depends on: nothing first-party.
• Concept introduced, permission policies as prefixed policy names. [Rubric §11, Security] (assesses whether authorization is expressed as capabilities rather than hard-coded role checks) and [Rubric §2, Design Patterns] (assesses deliberate use of a known pattern; here a reserved-prefix naming convention is what lets an on-demand provider recognize its own policies). Rather than pre-register one named policy per permission, the codebase encodes the permission inside the policy name behind a reserved prefix; PermissionPolicyProvider then materializes any policy whose name starts with that prefix on demand (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/PermissionPolicy.cs:3-8). This class owns both ends of that encoding.
• Walkthrough: Prefix = "perm:" (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/PermissionPolicy.cs:12), the reserved marker; and NameFor(string permission) (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/PermissionPolicy.cs:17), an expression-bodied Prefix + permission that builds the policy name. HasPermissionAttribute calls NameFor to build the [Authorize] policy string, and PermissionPolicyProvider strips Prefix back off to recover the permission.
• Why it's built this way: a single shared prefix constant means the attribute that writes the policy name and the provider that reads it cannot disagree; both reference PermissionPolicy.Prefix.
• Where it's used: by HasPermissionAttribute (encode) and PermissionPolicyProvider (decode).

PermissionRequirement

MMCA.Common.API · MMCA.Common.API.Authorization · MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/PermissionRequirement.cs:10 · Level 0 · class (sealed)

• What it is: an ASP.NET Core IAuthorizationRequirement carrying the single permission a principal must hold for a given policy to succeed.
• Depends on: Microsoft.AspNetCore.Authorization.IAuthorizationRequirement (framework).
• Concept introduced, the requirement/handler pair. [Rubric §11, Security] and [Rubric §2, Design Patterns] (assesses whether the ASP.NET Core authorization model is used as designed: it splits what is required from how it is checked). A requirement is a passive data object; a matching AuthorizationHandler<T> decides whether it is satisfied. This type is the passive half; PermissionAuthorizationHandler is the active half, as the doc comment states (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/PermissionRequirement.cs:5-9).
• Walkthrough: a sealed class implementing IAuthorizationRequirement (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/PermissionRequirement.cs:10). Its constructor (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/PermissionRequirement.cs:14-18) guards with ArgumentException.ThrowIfNullOrWhiteSpace(permission) (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/PermissionRequirement.cs:16) and stores the value into the get-only Permission property (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/PermissionRequirement.cs:21), so a requirement can never carry an empty permission.
• Why it's built this way: keeping Permission immutable and non-empty means the handler can trust it without re-validating; the requirement is a value carrier with no behavior of its own.
• Where it's used: attached to a policy by PermissionPolicyProvider (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/PermissionPolicyProvider.cs:43) and evaluated by PermissionAuthorizationHandler.

FallbackAuthorizationHandler

MMCA.Common.API · MMCA.Common.API.Authorization.Fallback · MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/Fallback/FallbackAuthorizationHandler.cs:32 · Level 1 · class (sealed)

• What it is: the AuthorizationHandler<FallbackAuthorizationRequirement> that decides whether an endpoint carrying no authorization metadata of its own should be allowed through: it succeeds for an authenticated caller, an exempt path, a request that matched no endpoint and names no web-root file, or an API-versioning rejection endpoint, and otherwise leaves the requirement unsatisfied.
• Depends on: FallbackAuthorizationRequirement, FallbackAuthorizationOptions (the exempt path prefixes, taken as IOptions<FallbackAuthorizationOptions> on the primary constructor, MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/Fallback/FallbackAuthorizationHandler.cs:32); Microsoft.AspNetCore.Http, Microsoft.AspNetCore.Authorization.
• Concept introduced, path-based exemption over endpoint routing's ambient resource. [Rubric §11, Security] (assesses whether the fail-closed default still lets framework and static surfaces through without requiring [AllowAnonymous] on infrastructure that was never meant to declare authorization metadata) and [Rubric §7, Microservices Readiness] (assesses whether the handler works without extra DI plumbing; it needs no IHttpContextAccessor).
• Walkthrough: HandleRequirementAsync (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/Fallback/FallbackAuthorizationHandler.cs:39-55) null-guards both arguments and succeeds the requirement when any of context.User.Identity?.IsAuthenticated == true, IsExemptPath(context.Resource), IsUnmatchedRequest(context.Resource) or IsApiVersioningRejection(context.Resource) holds (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/Fallback/FallbackAuthorizationHandler.cs:46-49); otherwise it returns without calling context.Succeed, leaving the requirement unmet. IsUnmatchedRequest (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/Fallback/FallbackAuthorizationHandler.cs:76-93) returns false for a non-HTTP resource or any request that matched an endpoint (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/Fallback/FallbackAuthorizationHandler.cs:78-81); for an unmatched request it consults the IWebHostEnvironment.WebRootFileProvider and passes only when neither a file nor a directory exists at the path (or no web root is available) (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/Fallback/FallbackAuthorizationHandler.cs:85-92). Nothing sits behind such a request, and challenging it would turn an unknown URL into a sign-in redirect instead of letting the host's not-found re-execute render the 404; a request for an existing web-root file keeps the gate because UseStaticFiles would still serve it. IsApiVersioningRejection (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/Fallback/FallbackAuthorizationHandler.cs:64-71) recognizes Asp.Versioning's client-error endpoints (no metadata, request delegate declared in the Asp.Versioning.Routing namespace, constant at MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/Fallback/FallbackAuthorizationHandler.cs:36), so an anonymous caller with a bad api-version gets the 400 version error rather than a 401 (rationale comment at MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/Fallback/FallbackAuthorizationHandler.cs:57-63). IsExemptPath (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/Fallback/FallbackAuthorizationHandler.cs:95-107) pattern-matches context.Resource to HttpContext and returns false for anything else (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/Fallback/FallbackAuthorizationHandler.cs:97-100), then checks the request path against options.Value.ExemptPathPrefixes with StartsWithSegments(prefix, StringComparison.OrdinalIgnoreCase) (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/Fallback/FallbackAuthorizationHandler.cs:104-106). The comment above IsUnmatchedRequest (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/Fallback/FallbackAuthorizationHandler.cs:73-75) explains why no IHttpContextAccessor is needed: under endpoint routing the authorization resource IS the HttpContext, and a non-HTTP resource (a SignalR hub invocation) simply has no exempt path and falls through to the authenticated-user rule.
• Why it's built this way: reading the resource directly off AuthorizationHandlerContext instead of injecting IHttpContextAccessor keeps the handler stateless and singleton-safe; never calling context.Fail() follows the same ASP.NET Core convention as PermissionAuthorizationHandler, abstaining rather than vetoing.
• Where it's used: registered as an IAuthorizationHandler singleton and wired as ASP.NET Core's AuthorizationOptions.FallbackPolicy handler by AuthorizationExtensions.AddAuthorizationPolicies whenever FallbackAuthorizationOptions.Enabled is true.

HasPermissionAttribute

MMCA.Common.API · MMCA.Common.API.Authorization · MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/HasPermissionAttribute.cs:13 · Level 1 · class (sealed attribute)

• What it is: an [Authorize]-derived attribute that requires the authenticated principal to hold a named permission, applied to a controller or an action.
• Depends on: PermissionPolicy (to build the policy name); Microsoft.AspNetCore.Authorization.AuthorizeAttribute (framework base).
• Concept introduced, capability-based endpoint authorization. [Rubric §11, Security] (assesses whether endpoints depend on capabilities rather than hard-coded role names) and [Rubric §7, Microservices Readiness] (assesses whether a module can be lifted out on its own; permissions travel as claims or through a per-module registry, so an extracted service authorizes without embedding the issuer's role taxonomy). The doc comment (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/HasPermissionAttribute.cs:5-11) states the intent directly: prefer [HasPermission("sessions:manage")] over role-based [Authorize(Policy = ...)] so an endpoint declares the capability it needs, with the mapping from roles to that capability living in one registry (IPermissionRegistry).
• Walkthrough: sealed class HasPermissionAttribute : AuthorizeAttribute (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/HasPermissionAttribute.cs:13) with [AttributeUsage(... AllowMultiple = true, Inherited = true)] (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/HasPermissionAttribute.cs:12) so several permission requirements can stack on one target and subclasses inherit them. The constructor (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/HasPermissionAttribute.cs:17-18) chains to the base with PermissionPolicy.NameFor(permission): setting the inherited Policy to "perm:<permission>" is what routes the check through PermissionPolicyProvider. It also stores the bare permission on the get-only Permission property (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/HasPermissionAttribute.cs:21).
• Why it's built this way: deriving from AuthorizeAttribute (rather than inventing a filter) means the standard MVC authorization pipeline picks it up for free, and encoding the permission into the inherited Policy string is what removes the per-permission registration step.
• Where it's used: on controllers and actions across both apps; its policy name is resolved by PermissionPolicyProvider and satisfied by PermissionAuthorizationHandler against the grants each module declares through AuthorizationExtensions.AddPermissions.

PermissionAuthorizationHandler

MMCA.Common.API · MMCA.Common.API.Authorization · MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/PermissionAuthorizationHandler.cs:13 · Level 1 · class (sealed)

• What it is: the AuthorizationHandler<PermissionRequirement> that decides whether the current principal satisfies a PermissionRequirement, either because it carries the permission as an explicit claim or because one of its roles grants it.
• Depends on: PermissionRequirement, IPermissionRegistry (the role-to-permission map, taken as a primary constructor parameter at MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/PermissionAuthorizationHandler.cs:13), and the shared ClaimsPrincipal extension methods HasPermissionClaim / GetRoleValues (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/PermissionAuthorizationHandler.cs:30-31).
• Concept introduced, resolving a permission through claim-or-role. [Rubric §11, Security] (assesses correctness of the grant decision; there are two independent grant paths, a direct permission claim and a role-derived one) and [Rubric §7, Microservices Readiness] (assesses whether a service stands alone; the role lookup used by GetRoleValues() reads out of the token regardless of how the JWT middleware mapped the role claim type, so it survives inbound-claim mapping being on or off).
• Walkthrough: HandleRequirementAsync (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/PermissionAuthorizationHandler.cs:17) null-guards both arguments (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/PermissionAuthorizationHandler.cs:21-22), then short-circuits to a completed task when the principal is not authenticated (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/PermissionAuthorizationHandler.cs:24-27), so an anonymous request never succeeds. It then succeeds the requirement if either context.User.HasPermissionClaim(requirement.Permission) (a directly granted permission) or permissionRegistry.HasPermission(context.User.GetRoleValues(), requirement.Permission) (a role-derived grant) holds (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/PermissionAuthorizationHandler.cs:30-31). The handler no longer carries its own role-gathering helper: the three-claim-type role lookup (the standard ClaimTypes.Role URI plus the raw "role"/"roles" claims) that used to live as a private GetRoles method here now lives once, on the shared ClaimsPrincipalExtensions.GetRoleValues() used by both this handler and ICurrentUserService.Roles, so the two call sites cannot restate the predicate and drift.
• Why it's built this way: never calling context.Fail() (only context.Succeed) is the ASP.NET Core convention that lets multiple handlers vote independently: this handler abstains rather than vetoes when it cannot grant. Moving the role-claim-type lookup into a shared extension (rather than a private method restated per call site) is what removed the duplication the prior version flagged in a comment.
• Where it's used: registered as an IAuthorizationHandler singleton by AuthorizationExtensions.AddAuthorizationPolicies (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/AuthorizationExtensions.cs:70-71); invoked by the authorization middleware for every policy that carries a PermissionRequirement.

PermissionPolicyProvider

MMCA.Common.API · MMCA.Common.API.Authorization · MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/PermissionPolicyProvider.cs:13 · Level 1 · class (sealed)

• What it is: an IAuthorizationPolicyProvider that lazily builds an AuthorizationPolicy for any policy name starting with the PermissionPolicy prefix, attaching a PermissionRequirement for the encoded permission, and delegates every other policy name to the default provider.
• Depends on: PermissionPolicy (the prefix), PermissionRequirement; Microsoft.AspNetCore.Authorization, Microsoft.Extensions.Options.
• Concept introduced, on-demand policy materialization. [Rubric §11, Security] and [Rubric §15, Best Practices & Code Quality] (assesses whether the design scales without repetitive registration; a system with an open-ended set of permissions cannot pre-register a named policy for each, so the policy is built from its own name at resolution time). The doc comment (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/PermissionPolicyProvider.cs:6-12) explains the design: "perm:*" names are materialized here, and every other name falls through to the default provider, so a policy the application registers itself is still resolved the usual way.
• Walkthrough: the constructor (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/PermissionPolicyProvider.cs:19-20) wraps a DefaultAuthorizationPolicyProvider built from the ambient AuthorizationOptions and keeps it in _fallbackPolicyProvider (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/PermissionPolicyProvider.cs:15). GetDefaultPolicyAsync and GetFallbackPolicyAsync (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/PermissionPolicyProvider.cs:23-28) delegate straight to that fallback. GetPolicyAsync (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/PermissionPolicyProvider.cs:31) is the interesting one: it rejects a null or blank name outright (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/PermissionPolicyProvider.cs:33), and if the name does not start with PermissionPolicy.Prefix it defers to the fallback (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/PermissionPolicyProvider.cs:35-38); otherwise it slices the prefix off with the range expression policyName[PermissionPolicy.Prefix.Length..] (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/PermissionPolicyProvider.cs:40) and builds a policy that requires an authenticated user plus a fresh PermissionRequirement(permission) (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/PermissionPolicyProvider.cs:41-44). Note the RequireAuthenticatedUser() at MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/PermissionPolicyProvider.cs:42: it makes anonymous requests fail with a challenge before the handler ever runs, which is why the handler can treat "not authenticated" as a plain abstain.
• Why it's built this way: composing over DefaultAuthorizationPolicyProvider rather than reimplementing it means all pre-registered policies survive; only the perm: namespace is intercepted. That is what lets HasPermissionAttribute work for any permission string without a registration step.
• Where it's used: installed (via Replace) as the single IAuthorizationPolicyProvider by AuthorizationExtensions.AddAuthorizationPolicies (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/AuthorizationExtensions.cs:72-73).
• Caveats / not-in-source: a policy object is built on every GetPolicyAsync call for a perm: name; no cache is present in this type, and whether ASP.NET Core caches the result upstream is not determinable from this source file.

AuthorizationExtensions

MMCA.Common.API · MMCA.Common.API.Authorization · MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/AuthorizationExtensions.cs:14 · Level 3 · class (static, extension block)

• What it is: the DI wiring for the whole authorization model: one overload set that turns on ASP.NET Core authorization, installs the permission mechanism (handler, on-demand provider, registry) and the framework's fallback policy, and one method each module uses to declare its role-to-permission grants.
• Depends on: PermissionAuthorizationHandler, PermissionPolicyProvider, IPermissionRegistry, IPermissionCatalog, PermissionRegistryBuilder, FallbackAuthorizationOptions and FallbackAuthorizationHandler; Microsoft.Extensions.DependencyInjection plus its Extensions namespace for TryAddEnumerable.
• Concept introduced, extension(T) DI members and lazy registry accumulation. [Rubric §6, CQRS & Event-Driven Design] (assesses whether a concern is configured once for every host rather than re-wired per application) and [Rubric §7, Microservices Readiness] (assesses per-module self-sufficiency: each module contributes only the permissions it owns, so an extracted module carries its own grants). The extension(IServiceCollection services) block (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/AuthorizationExtensions.cs:16) is the C# extension(T) DI idiom taught in the primer: it adds AddAuthorizationPolicies and AddPermissions directly onto IServiceCollection. The doc comment on the no-argument overload (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/AuthorizationExtensions.cs:18-23) states the permission model plainly: an endpoint states the capability it needs and the registry maps roles to capabilities, so no policy name has to be pre-registered per role. The parameterized overload's doc comment (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/AuthorizationExtensions.cs:28-61) states the fallback half: an endpoint declaring NO authorization metadata now requires an authenticated caller instead of publishing anonymously by omission, exempt paths are seeded from FallbackAuthorizationOptions.DefaultExemptPathPrefixes, the opt-out is AddAuthorizationPolicies(options => options.Enabled = false), and two surfaces need a decision before adopting it in an existing host: a YARP gateway's proxied routes need "AuthorizationPolicy": "anonymous" per public route (or the opt-out), and a routable Blazor page is gated by AuthorizeRouteView, which reads attributes and ignores this policy entirely, so a page still declares [Authorize]/[AllowAnonymous] for itself. The same comment also notes that a request matching no endpoint and naming no web-root file is not gated, so it reaches the 404 (and a host's not-found re-execute) instead of a sign-in challenge (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/AuthorizationExtensions.cs:40-41).
• Walkthrough
  • AddAuthorizationPolicies() (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/AuthorizationExtensions.cs:25-26): a one-line forward to AddAuthorizationPolicies(configureFallback: null), so the fallback policy is enabled with its default exempt list unless a host opts out.
  • AddAuthorizationPolicies(Action<FallbackAuthorizationOptions>? configureFallback) (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/AuthorizationExtensions.cs:62): calls services.AddAuthorization() (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/AuthorizationExtensions.cs:64) to bring in the framework's authorization services, then wires the permission mechanism: TryAddEnumerable adds PermissionAuthorizationHandler as a singleton IAuthorizationHandler (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/AuthorizationExtensions.cs:70-71), Replace installs PermissionPolicyProvider as the transient IAuthorizationPolicyProvider (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/AuthorizationExtensions.cs:72-73), and EnsurePermissionRegistry(services) guarantees a registry exists (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/AuthorizationExtensions.cs:74). It then binds FallbackAuthorizationOptions, applies configureFallback when supplied, registers FallbackAuthorizationHandler as a singleton IAuthorizationHandler, and configures AuthorizationOptions.FallbackPolicy through the options pipeline (Configure<IOptions<FallbackAuthorizationOptions>>) rather than inline, so the Enabled flag is read after every AddAuthorizationPolicies/Configure call the host makes (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/AuthorizationExtensions.cs:76-93): a FallbackAuthorizationRequirement-carrying policy when Enabled is true, null (no fallback policy) when it is false.
  • AddPermissions(Action<PermissionRegistryBuilder> configure) (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/AuthorizationExtensions.cs:105): the per-module entry point for declaring grants. It guards the callback (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/AuthorizationExtensions.cs:107), fetches the shared builder via EnsurePermissionRegistry, and invokes configure(builder) so the module's grants accumulate (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/AuthorizationExtensions.cs:109-110). The doc comment (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/AuthorizationExtensions.cs:98-104) notes it is safe to call once per module because grants union into a single registry; the union itself happens in PermissionRegistryBuilder.Grant (MMCA.Common/Source/Core/MMCA.Common.Shared/Auth/Permissions/PermissionRegistryBuilder.cs:32-39).
  • EnsurePermissionRegistry(IServiceCollection) (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/AuthorizationExtensions.cs:119): the idempotent core. If a PermissionRegistryBuilder is already registered as a singleton instance it returns that existing one (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/AuthorizationExtensions.cs:121-125); otherwise it creates one, registers it, and registers the built PermissionRegistry as a singleton factory (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/AuthorizationExtensions.cs:127-129). Both IPermissionRegistry and IPermissionCatalog are then registered as singleton factories that resolve that same concrete PermissionRegistry (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/AuthorizationExtensions.cs:135-136); the inline comment (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/AuthorizationExtensions.cs:131-134) states why: both contracts must forward to the ONE built instance so what an administration screen enumerates and what an authorization check answers from can never disagree, and calling builder.Build() a second time to satisfy the second contract would build two. Because the registry is built on first resolve, every module's AddPermissions call has already contributed by the time any request evaluates a permission, which is the point the comment at MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/AuthorizationExtensions.cs:116-118 makes.
• Why it's built this way: TryAddEnumerable lets the permission handler (and, separately, the fallback handler) coexist with any other authorization handlers a host registers; Replace guarantees exactly one policy provider (the permission-aware one); and the lazy builder.Build() factory is what makes module registration order irrelevant, since all grants are collected before the first Build(). Resolving IPermissionRegistry and IPermissionCatalog from the same singleton factory output (rather than each calling builder.Build()) is what keeps the read side and the enforcement side of the permission model looking at one object.
• Where it's used: AddAuthorizationPolicies() is called at the end of both framework authentication-wiring helpers, so a host that wires authentication through either gets the authorization model without an explicit call: AddForwardedJwtBearerCore (MMCA.Common/Source/Presentation/MMCA.Common.API/Startup/WebApplicationBuilderExtensions.Authentication.cs:77, the call at WebApplicationBuilderExtensions.Authentication.cs:116) and AddCommonAuthentication (WebApplicationBuilderExtensions.Authentication.cs:133, the call at WebApplicationBuilderExtensions.Authentication.cs:155). AddPermissions(...) is called by each module that owns permissions: in MMCA.ADC by Conference (MMCA.ADC/Source/Modules/Conference/MMCA.ADC.Conference.API/DependencyInjection.cs:41), Engagement (MMCA.ADC/Source/Modules/Engagement/MMCA.ADC.Engagement.API/DependencyInjection.cs:58), Identity (MMCA.ADC/Source/Modules/Identity/MMCA.ADC.Identity.API/DependencyInjection.cs:44) and Notification (MMCA.ADC/Source/Modules/Notification/MMCA.ADC.Notification.API/DependencyInjection.cs:38), and in MMCA.Store by Catalog (MMCA.Store/Source/Modules/Catalog/MMCA.Store.Catalog.API/DependencyInjection.cs:41), Sales (MMCA.Store/Source/Modules/Sales/MMCA.Store.Sales.API/DependencyInjection.cs:40) and Identity (MMCA.Store/Source/Modules/Identity/MMCA.Store.Identity.API/DependencyInjection.cs:42).
• Caveats / not-in-source: a host that never calls either method has no IPermissionRegistry registered at all. That case is covered elsewhere in this group by UnconfiguredPermissionRegistry, whose diagnostic message names these two methods as the fix (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/UnconfiguredPermissionRegistry.cs:68).

OwnershipHelper

MMCA.Common.API · MMCA.Common.API.Authorization · MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnershipHelper.cs:11 · Level 9 · class (static)

• What it is: static helpers a controller calls to enforce ownership: to scope a query to the current user's own data (a specification that filters by owner id, or null when the caller holds the privileged bypass role), to refuse a scoped read whose owner claim cannot be resolved, and to check that the caller owns one specific record.
• Depends on: ICurrentUserService (Application layer, imported at MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnershipHelper.cs:1), plus Result and Error for the two gate methods. The specification it hands back is typically a Specification<TEntity, TIdentifierType>, though the helper itself never says so (see caveats).
• Concept introduced, ownership scoping at the query level, as distinct from the filter's gate. [Rubric §11, Security] (assesses row-level data isolation: a non-admin caller can only read their own rows) and [Rubric §1, SOLID] (assesses separation of responsibility: the helper produces a specification, the repository applies it). Where OwnerOrAdminFilter blocks a request that names someone else's id, this helper narrows the result set so a list endpoint returns only the caller's rows without them passing any id at all. ADR-033 calls these the two enforcement points of one ownership axis: reject-one for single-resource routes, filter-many for collection routes.
• Walkthrough
  • IsAdmin(ICurrentUserService, string bypassRole) (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnershipHelper.cs:18): a case-insensitive compare of the current user's Role against the bypass role (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnershipHelper.cs:21). bypassRole has no default argument: every caller supplies its own, normally sourced from OwnerOrAdminFilterOptions.BypassRole, so the framework itself declares no role names (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnershipHelper.cs:14-17). OwnerOrAdminFilter reuses this same method so the gate and the scoping agree on who bypasses.
  • GetOwnershipSpecification<TSpec, TId>(...) (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnershipHelper.cs:35): the general form. It returns null for a bypass-role caller (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnershipHelper.cs:46-49, no scoping needed); otherwise it reads the owner id from the named claim via currentUserService.GetClaimValue<TId>(claimType) and, when present, calls the supplied specFactory(id.Value) to build the scoping specification (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnershipHelper.cs:51-52). Like IsAdmin, bypassRole is a required parameter with no default (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnershipHelper.cs:39). The where TId : struct, IParsable<TId> constraint (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnershipHelper.cs:41) is what lets the claim string be parsed into a strongly-typed id.
  • GetOwnershipSpecification<TSpec>(...) (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnershipHelper.cs:65): the convenience overload that fixes TId to int and the claim to "customer_id", but still takes bypassRole as a required parameter and forwards it (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnershipHelper.cs:68).
  • RequireResolvableOwner<TId>(currentUserService, claimType, bypassRole, source, target) (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnershipHelper.cs:91): the fail-closed gate to call before a read scoped through GetOwnershipSpecification. It returns Result.Success() when the caller passes IsAdmin or carries a parsable owner claim, and otherwise a Forbidden failure (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnershipHelper.cs:101-103). The doc comment frames a missing claim as an authorization answer (403), never an unscoped read and never a 500 (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnershipHelper.cs:73-78).
  • ValidateOwnershipAsync<TId>(..., isOwnedBy, source, target, cancellationToken) (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnershipHelper.cs:133): the single-record gate. A bypass-role caller passes without a lookup (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnershipHelper.cs:146-149); an unresolvable owner claim is refused with the same Forbidden failure and the lookup never runs (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnershipHelper.cs:151-154); otherwise the private CheckOwnershipAsync (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnershipHelper.cs:159) awaits the caller-supplied isOwnedBy(ownerId, cancellationToken) predicate (typically an ExistsAsync query) and answers Error.NotFound with the given source and target when it is false.
  • AccessDenied(source, target) (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnershipHelper.cs:174): the one private factory both gates share, Error.Forbidden("Error.Forbidden", "Access denied.", source, target).
• Why it's built this way: returning null for bypass-role callers (rather than a "match everything" specification) lets the caller skip filtering entirely on the privileged path; producing a specification rather than running the query keeps the helper in the API layer while the actual filtering runs in the query pipeline. Every method takes bypassRole as a required parameter and checks it through the same IsAdmin, so the scope and both gates agree on who is privileged, and, like OwnerOrAdminFilterOptions.BypassRole, the framework names no default role anywhere in the ownership axis. ValidateOwnershipAsync answers a non-owner with 404 rather than 403 so the existence of another owner's record cannot be probed for (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnershipHelper.cs:113-114).
• Where it's used: MMCA.Store's ShoppingCartsController wraps GetOwnershipSpecification and RequireResolvableOwner in private helpers (MMCA.Store/Source/Modules/Sales/MMCA.Store.Sales.API/Controllers/ShoppingCartsController.cs:65-67,79-84), and OrdersController does the same (MMCA.Store/Source/Modules/Sales/MMCA.Store.Sales.API/Controllers/OrdersController.cs:66-68,80-85), also routing its mutating endpoints through ValidateOwnershipAsync (MMCA.Store/Source/Modules/Sales/MMCA.Store.Sales.API/Controllers/OrdersController.cs:386-390). In MMCA.ADC, EventQuestionAnswersController and SessionQuestionAnswersController scope by user id with GetOwnershipSpecification and gate with RequireResolvableOwner (MMCA.ADC/Source/Modules/Conference/MMCA.ADC.Conference.API/Controllers/Events/EventQuestionAnswersController.cs:110,138, MMCA.ADC/Source/Modules/Conference/MMCA.ADC.Conference.API/Controllers/Sessions/SessionQuestionAnswersController.cs:110,138). IsAdmin also decides the export override AllowUnscopedExport on all four controllers (for example MMCA.Store/Source/Modules/Sales/MMCA.Store.Sales.API/Controllers/OrdersController.cs:249) and is the bypass check inside OwnerOrAdminFilter (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnerOrAdminFilter.cs:43).
• Caveats / not-in-source: two gaps are worth knowing. TSpec is an open generic with only a class constraint (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnershipHelper.cs:40), so the helper does not itself require the returned type to be a specification: that contract is the caller's. And GetOwnershipSpecification also returns null for a non-admin caller whose claim is missing or unparseable (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnershipHelper.cs:52), which means no scoping. It does not distinguish that case from the bypass role; RequireResolvableOwner does, but only if the caller invokes it before the read, which nothing in the helper enforces.

OwnerOrAdminFilter

MMCA.Common.API · MMCA.Common.API.Authorization · MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnerOrAdminFilter.cs:31 · Level 10 · class (sealed action filter)

• What it is: an MVC async action filter that lets a request proceed only if the caller holds the bypass role or owns the resource named by the request, returning 403 Forbidden otherwise.

• Depends on: OwnershipHelper (for the IsAdmin check), OwnerOrAdminFilterOptions (the vocabulary), AllowMissingOwnerAttribute (the opt-out it honors), ICurrentUserService (claims); Microsoft.AspNetCore.Mvc.Filters, Microsoft.Extensions.Options, System.Globalization.

• Concept introduced, per-request ownership enforcement as a filter, and deny-by-default. [Rubric §11, Security] (assesses whether a resource-level access gate runs before the action body and whether it fails closed) and [Rubric §17, DevOps & Deployment] (assesses whether the rule is expressed once and attached, rather than re-coded in each action). This is the gate counterpart to OwnershipHelper's query scoping: the helper narrows a list, this filter blocks an attempt to read or mutate a specific id the caller does not own (ADR-033, cited at MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnerOrAdminFilter.cs:15). The deny-by-default half is the more important lesson, and the class doc comment spells it out (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnerOrAdminFilter.cs:16-23): a gate that treats "nothing to compare" as "nothing to enforce" silently stops guarding every action whose parameter is optional, non-integer, or carried inside a bound model.

• Walkthrough: OnActionExecutionAsync (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnerOrAdminFilter.cs:36) null-guards its arguments and reads the current settings = options.Value (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnerOrAdminFilter.cs:38-41), then walks four decisions in order:

  1. Bypass role: if OwnershipHelper.IsAdmin(currentUserService, settings.BypassRole) it calls next() and returns (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnerOrAdminFilter.cs:43-47).
  2. Missing owner claim: it reads the caller's owner id with currentUserService.GetClaimValue<int>(settings.OwnerClaimType) (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnerOrAdminFilter.cs:49) and short-circuits to ForbidResult when the claim is absent (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnerOrAdminFilter.cs:51-55).
  3. Unresolvable owner parameter: if TryGetOwnerParameter cannot produce an int, the request is denied unless the endpoint carries AllowMissingOwnerAttribute, in which case it falls through to next() (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnerOrAdminFilter.cs:57-71). Note the ordering: the opt-out excuses only a missing parameter, and it is checked after the claim check, so an [AllowMissingOwner] action still requires a valid owner claim.
  4. Mismatch: a resolved parameter that does not equal the claim value yields ForbidResult (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnerOrAdminFilter.cs:73-77); only an exact match reaches await next() (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnerOrAdminFilter.cs:79).

  Two private helpers back that flow. HasAllowMissingOwner (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnerOrAdminFilter.cs:84-85) reads context.ActionDescriptor.EndpointMetadata.OfType<AllowMissingOwnerAttribute>(), which is how one lookup covers the attribute whether it sits on the action or on its declaring controller: MVC has already composed both into the metadata (comment at OwnerOrAdminFilter.cs:82-83). TryGetOwnerParameter (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnerOrAdminFilter.cs:93-111) resolves the id from the route values first (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnerOrAdminFilter.cs:95-100) and, failing that, from the model-bound action arguments (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnerOrAdminFilter.cs:102-107), reporting failure by setting value = 0 and returning false (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnerOrAdminFilter.cs:109-110). Both parses pass NumberStyles.Integer and CultureInfo.InvariantCulture explicitly (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnerOrAdminFilter.cs:97,104); the comment above the method states the convention (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnerOrAdminFilter.cs:90-92): an owner id off the wire is not a number the request's ambient culture formatted, so the host's CurrentCulture must not decide which strings are ids.

• Why it's built this way: denying on an unresolvable parameter, with an explicit attribute as the only escape, converts a silent failure mode into a visible one: the action either compares an owner id or documents the guard that replaces the comparison (ADR-033's deny-by-default decision and the audit table that came with it). Reading the vocabulary from injected options keeps a single filter reusable across hosts, and checking the route before the bound arguments means a conventional /{id} route costs one dictionary lookup.

• Where it's used: registered scoped by AddAPI (MMCA.Common/Source/Presentation/MMCA.Common.API/DependencyInjection.cs:85, next to IdempotencyFilter at DependencyInjection.cs:84, because both depend on scoped services) and applied as [ServiceFilter(typeof(OwnerOrAdminFilter))], per the remarks at MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnerOrAdminFilter.cs:25-30. MMCA.Store applies it at controller level on ShoppingCartsController (MMCA.Store/Source/Modules/Sales/MMCA.Store.Sales.API/Controllers/ShoppingCartsController.cs:49) and CustomersController (MMCA.Store/Source/Modules/Identity/MMCA.Store.Identity.API/Controllers/CustomersController.cs:34), which covers every action on those controllers, so adoption there was an audit of the whole controller and the actions with no owner parameter carry AllowMissingOwnerAttribute. MMCA.ADC instead applies it per action, on two BookmarksController endpoints (MMCA.ADC/Source/Modules/Engagement/MMCA.ADC.Engagement.API/Controllers/BookmarksController.cs:85,106), against the Engagement vocabulary configured at MMCA.ADC/Source/Modules/Engagement/MMCA.ADC.Engagement.API/DependencyInjection.cs:45-56.

• Caveats / not-in-source: the owner id is parsed as int only (MMCA.Common/Source/Presentation/MMCA.Common.API/Authorization/OwnerOrAdminFilter.cs:97,104), and the claim is read as GetClaimValue<int> (OwnerOrAdminFilter.cs:49), so a host whose owner id is a Guid or a string cannot use this filter as-is. It also assumes the owner parameter is the owning id, which holds for a cart or a customer profile but not for a resource with its own id and a foreign-key owner (ADR-033 lists orders as that case, handled with a specification or an explicit per-id check instead).

BrowserOrigin

MMCA.Common.API · MMCA.Common.API.SessionCookies · MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/CookieSessionRefresher.cs:289 · Level 0 · record struct

• What it is: a private nested value type inside CookieSessionRefresher that captures the browser's user-agent and remote IP from the triggering request, so the refresher's server-to-server auth/refresh call can pass them on.
• Depends on: HttpContext and HttpRequestMessage (ASP.NET Core / BCL) only. It is private readonly record struct, so nothing outside the refresher can name it.
• Concept introduced, carry the real device through a server-side hop. [Rubric §11, Security] assesses whether session records describe the true client. The type comment (MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/CookieSessionRefresher.cs:283-288) explains that the origin is captured before the lock is taken, so the rotated session records the real device and IP instead of this host's own (empty user-agent, loopback address), and that the identity endpoint trusts X-Forwarded-For through CommonForwardedHeaders.
• Walkthrough: From(HttpContext) (:291-297) reads the User-Agent header, storing null when it is blank, and Connection.RemoteIpAddress as a string (possibly null). ApplyTo(HttpRequestMessage) (:299-312) copies each non-null value onto the outgoing request: User-Agent and X-Forwarded-For, both through TryAddWithoutValidation (:305, :310) because a real browser user-agent does not always parse as a strict product token list and the value is informational only (comment :303-304).
• Why it's built this way: the doc comment says the origin is captured from the triggering request before the lock is taken, and a readonly record struct gives value equality and no per-refresh heap allocation for two strings' worth of state.
• Where it's used: created by the refresher's GetOrRefreshAsync path (MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/CookieSessionRefresher.cs:136), passed through RefreshAsync (:152) and CallRefreshAsync (:171), and applied to the auth/refresh request at :190. No ADR names it and no usage exists outside the defining file.

ISessionCookieStore

MMCA.Common.API · MMCA.Common.API.SessionCookies · MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/ISessionCookieStore.cs:14 · Level 0 · interface

• What it is: the public port for writing and clearing the two HttpOnly session cookies from server code that obtained the tokens itself, so it can store them without a browser round trip.
• Depends on: HttpContext (ASP.NET Core) only. Its one implementation is SessionCookieStore, a thin adapter over the internal SessionCookieJar that applies SessionCookieSettings.
• Concept introduced, a public door onto an internal cookie writer. [Rubric §11, Security] assesses whether cookie hardening has one definition. The jar is internal, so before this interface only MMCA.Common.API itself could set the session cookies. The doc comment (MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/ISessionCookieStore.cs:7-13) names the new caller: the same-origin API proxy in MMCA.Common.UI.Web, which receives tokens from the identity endpoint and must persist them with exactly the options (HttpOnly, Secure outside Development, the configured SameSite, 7-day lifetime) that the session-cookie endpoints and the server-side refresher already use. Exposing two methods instead of making the jar public keeps the option-building in one place.
• Walkthrough: void Write(HttpContext context, string accessToken, string refreshToken) (:19) appends both cookies; void Clear(HttpContext context) (:23) expires both. Neither returns anything: the cookies are a side effect on context.Response.
• Why it's built this way: the proxy keeps every credential server-side (ADR-131), so it is the one writer of the cookies on a proxied host and needs a supported way to write them that cannot drift from the endpoints' own writes.
• Where it's used: registered as a singleton by AddServerAuthSessionCookie (MMCA.Common/Source/Presentation/MMCA.Common.API/DependencyInjection.cs:191); injected into SameOriginApiProxyEndpoint (MMCA.Common/Source/Presentation/MMCA.Common.UI.Web/SameOriginProxy/SameOriginApiProxyEndpoint.cs:33), SameOriginProxyTransformer (MMCA.Common/Source/Presentation/MMCA.Common.UI.Web/SameOriginProxy/SameOriginProxyTransformer.cs:39) and the handoff route of SessionHandoffEndpoints (MMCA.Common/Source/Presentation/MMCA.Common.UI.Web/SameOriginProxy/SessionHandoffEndpoints.cs:42).

SessionClaimsToken

MMCA.Common.API · MMCA.Common.API.SessionCookies · MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/SessionClaimsToken.cs:14 · Level 0 · class

• What it is: a static helper that turns a signed access token into a claims-only copy: the same payload under an unsecured header with an empty signature, readable by the browser but useless as a credential.
• Depends on: BCL and NuGet only: Base64Url (System.Buffers.Text), Encoding, and JwtSecurityTokenHandler (System.IdentityModel.Tokens.Jwt). Switched on by SessionCookieSettings.ClaimsOnlyBrowserTokens.
• Concept introduced, the claims-only browser token. [Rubric §11, Security] and [Rubric §26, Front-End Security] both assess what an XSS payload could steal. The doc comment (MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/SessionClaimsToken.cs:7-13) states the trade: the client can still read the user's claims and the expiry to render its authentication state, but the token authorizes nothing, because every API validates signatures and rejects an unsigned token. Script on the page therefore holds nothing worth exfiltrating, while the UI keeps working off the same claims it always read.
• Walkthrough: UnsecuredHeader (:17) is computed once as the base64url (no padding) encoding of {"alg":"none","typ":"JWT"}, as the comment at :16 records. Create(string? accessToken) (:25) returns null for a blank value or anything JwtSecurityTokenHandler.CanReadToken refuses (:27-30), then splits on . and, for a three-segment compact JWT, returns {UnsecuredHeader}.{payload}. (:32-33); any other shape is also null. The trailing dot keeps the three-segment compact form with an empty signature.
• Why it's built this way: copying the payload segment verbatim (rather than re-serializing claims) guarantees the browser sees exactly the claims and exp the API issued (ADR-131).
• Where it's used: the /auth/session/token route of SessionCookieEndpoints under claims-only mode (MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/SessionCookieEndpoints.cs:75-77), the proxy's response rewrite (MMCA.Common/Source/Presentation/MMCA.Common.UI.Web/SameOriginProxy/SameOriginProxyTransformer.cs:142) and its refresh answer (MMCA.Common/Source/Presentation/MMCA.Common.UI.Web/SameOriginProxy/SameOriginApiProxyEndpoint.cs:369). Pinned by MMCA.Common/Tests/Presentation/MMCA.Common.API.Tests/SessionCookies/SessionClaimsTokenTests.cs: claims and expiry kept but signature dropped (:20), the result rejected by a signature-validating API (:37), and null for non-JWT input (:56).
• Caveats / not-in-source: "authorizes nothing" is a property of each API's JWT bearer validation (signature required), not of this type; the test at :37 checks it against one validating handler.

SessionCookieRequest

MMCA.Common.API · MMCA.Common.API.SessionCookies · MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/SessionCookieEndpoints.cs:95 · Level 0 · record

• What it is: the inbound body for POST /auth/session-cookie: the access and refresh token strings the browser hands back to the server so they can be re-issued as HttpOnly cookies.
• Depends on: nothing first-party. It is a two-string public sealed record nested inside SessionCookieEndpoints.
• Concept introduced, the browser cannot set an HttpOnly cookie from JS. [Rubric §11, Security] and [Rubric §26, Front-End Security] both assess XSS-resistant token storage. After the SPA logs in against the API it holds the token pair in memory; to persist that pair as HttpOnly cookies (unreadable by script, so an injected payload cannot exfiltrate them) it POSTs the tokens once to this same-origin endpoint, which writes the cookies server-side. This is the seeding half of ADR-022's browser session-cookie scheme.
• Walkthrough: the whole type is one line, public sealed record SessionCookieRequest(string AccessToken, string RefreshToken) (MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/SessionCookieEndpoints.cs:95). It is nested in the endpoint class it serves, so the contract sits next to its only route.
• Where it's used: bound by the POST handler at SessionCookieEndpoints.cs:35, which passes both strings straight to SessionCookieJar (:31).

SessionCookieSettings

MMCA.Common.API · MMCA.Common.API.SessionCookies · MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/SessionCookieSettings.cs:11 · Level 0 · class

• What it is: the options object for both session cookies: which SameSite mode they carry, whether the browser is ever handed a real access token, and how long the cookies live.
• Depends on: SameSiteMode (ASP.NET Core) only. Read through IOptions<SessionCookieSettings> by SessionCookieEndpoints, SessionCookieStore and CookieSessionRefresher; its claims-only switch selects SessionClaimsToken.
• Concept introduced, one options object for every cookie write. [Rubric §11, Security] assesses cookie hardening and credential exposure. A cookie delete only matches when it repeats the write's attributes, so the seed, refresh, store and clear paths all read SameSite from this one object instead of each choosing a value.
• Walkthrough: SameSite (:19) defaults to SameSiteMode.Lax; the doc comment (:13-18) explains the same-origin API proxy raises it to Strict because the cookie then authenticates data calls, not only server-side rendering. ClaimsOnlyBrowserTokens (:29) defaults to false; when true (doc :21-28), POST /auth/session/token answers with a claims-only token instead of the real access token, and POST /auth/session-cookie ignores posted tokens and answers 204 without writing, because the server is then the only writer of the cookies. Lifetime (:38, a TimeSpan?, doc :31-37) is the Max-Age of both cookies: null (the default) derives it from Jwt:RefreshTokenExpirationDays when that section is bound in the host, otherwise 7 days, so a cookie neither outlives nor undershoots the refresh token it carries. A UI host that does not bind Jwt and runs a non-default refresh lifetime sets it here. The resolution itself lives in SessionCookieJar.ResolveLifetime.
• Why it's built this way: the defaults are the long-standing cookie behavior (the comment at DependencyInjection.cs:188-189 says so), so a host that never opts in keeps Lax cookies and real browser tokens; the proxy tightens both settings in one place (ADR-131).
• Where it's used: registered with defaults by AddServerAuthSessionCookie (MMCA.Common/Source/Presentation/MMCA.Common.API/DependencyInjection.cs:190, comment at :188-189). The proxy's registration in SameOriginApiProxyServiceExtensions configures it (MMCA.Common/Source/Presentation/MMCA.Common.UI.Web/SameOriginProxy/SameOriginApiProxyServiceExtensions.cs:69-74), copying SameSite from SameOriginApiProxySettings.SessionCookieSameSite (default Strict, MMCA.Common/Source/Presentation/MMCA.Common.UI.Web/SameOriginProxy/SameOriginApiProxySettings.cs:74) and setting ClaimsOnlyBrowserTokens = true. Claims-only behavior is pinned by MMCA.Common/Tests/Presentation/MMCA.Common.API.Tests/SessionCookies/ClaimsOnlySessionCookieEndpointsTests.cs (:27, :47, :62).

SessionRefreshStatus

MMCA.Common.API · MMCA.Common.API.SessionCookies · MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/SessionRefreshOutcome.cs:4 · Level 0 · enum

• What it is: the three ways a validate-or-refresh attempt can end: Refreshed = 0 (:10), Rejected = 1 (:16) and Unavailable = 2 (:23).
• Depends on: nothing. Carried by SessionRefreshOutcome.
• Concept introduced, a dead session is not the same as an unreachable identity endpoint. [Rubric §29, Resilience, Reliability & Business Continuity] assesses whether a transient fault is treated as a permanent one. The doc comments draw the line: Refreshed means a usable access token is available (still-valid cookie, or a rotated pair written back, :6-9); Rejected means no refresh cookie or the identity endpoint refused it with 400, 401 or 403, so clearing the cookies is correct (:12-15); Unavailable covers a 5xx, 429 or other non-refusal status, a timeout, a network failure or an unreadable body, where the cookies may still hold a live session and must be kept for a retry (:18-22). A caller that clears cookies on any failure would sign a user out over a gateway blip.
• Where it's used: produced by CookieSessionRefresher (its ClassifyFailure, CookieSessionRefresher.cs:123-126) and branched on by the proxy's FailRefreshAsync (MMCA.Common/Source/Presentation/MMCA.Common.UI.Web/SameOriginProxy/SameOriginApiProxyEndpoint.cs:276).

SessionTokenResponse

MMCA.Common.API · MMCA.Common.API.SessionCookies · MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/CookieSessionRefresher.cs:23 · Level 0 · record

• What it is: the JSON body returned by POST /auth/session/token: the access token and its UTC expiry, and nothing else.
• Depends on: BCL only. Produced by SessionCookieEndpoints from a SessionTokenResult.
• Concept introduced, the refresh token never crosses the wire to the browser. [Rubric §9, API & Contract Design] assesses whether a response exposes only what its client needs. This record carries the access token, which the SPA holds in memory for its Bearer calls, and deliberately omits the refresh token, which stays exclusively in the HttpOnly cookie. The doc comment states the rule outright (MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/CookieSessionRefresher.cs:19-22).
• Walkthrough: public sealed record SessionTokenResponse(string AccessToken, DateTime AccessTokenExpiry) (:20). It is the serialized projection of the internal SessionTokenResult, which is why the two types carry the same two members and different visibility of intent.
• Where it's used: constructed and returned by the /auth/session/token handler (MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/SessionCookieEndpoints.cs:63).

SessionTokenResult

MMCA.Common.API · MMCA.Common.API.SessionCookies · MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/CookieSessionRefresher.cs:17 · Level 0 · record struct

• What it is: the internal carrier for a validated access token plus its UTC expiry, returned by the refresher. A readonly record struct, so the validate path allocates nothing to report success.
• Depends on: BCL only. Returned by ICookieSessionRefresher and projected onto the wire-facing SessionTokenResponse.
• Concept: the value-type twin of SessionTokenResponse. Same two members, but this one stays server-side and is used as SessionTokenResult? at every call site, so "no valid session" is expressed by the absence of a value rather than by a sentinel string or a thrown exception. [Rubric §12, Performance & Scalability] assesses avoidable allocation; a readonly record struct is the light choice for a result produced on every qualifying navigation.
• Walkthrough: public readonly record struct SessionTokenResult(string AccessToken, DateTime AccessTokenExpiry) (MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/CookieSessionRefresher.cs:17), with the one-line summary at :13 naming its provenance ("acquired from the session cookies").
• Where it's used: the return type of ICookieSessionRefresher.GetOrRefreshAsync (:36); constructed by CookieSessionRefresher at :71 (cookie still valid) and :92 (after a rotation); unwrapped by SessionCookieEndpoints at SessionCookieEndpoints.cs:63.

SessionRefreshOutcome

MMCA.Common.API · MMCA.Common.API.SessionCookies · MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/SessionRefreshOutcome.cs:32 · Level 9 · class

• What it is: the result of ICookieSessionRefresher.ValidateOrRefreshAsync and .RefreshAsync: a SessionRefreshStatus, the token when the status is Refreshed, and the upstream's Retry-After hint when it is Unavailable (doc comment, MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/SessionRefreshOutcome.cs:26-31).
• Depends on: SessionRefreshStatus and SessionTokenResult; TimeSpan from the BCL.
• Concept: a closed result type built only through named factories, so a caller cannot assemble an inconsistent combination (a Rejected outcome carrying a token, say). It is the richer sibling of the nullable SessionTokenResult? that GetOrRefreshAsync still returns: that shape cannot tell a dead session from a transient failure, this one can. [Rubric §29, Resilience, Reliability & Business Continuity] is the lens, as introduced at SessionRefreshStatus.
• Walkthrough: the constructor is private (:36-41). Status (:44), Session (:47, set only for Refreshed) and RetryAfter (:53, set only for Unavailable when the identity endpoint sent one) are get-only. The factories are Refreshed(SessionTokenResult session) (:58-59), Rejected() (:63), which returns one cached RejectedOutcome instance (:34) since it carries no data, and Unavailable(TimeSpan? retryAfter = null) (:68-69).
• Where it's used: built throughout CookieSessionRefresher and consumed by the proxy's FailRefreshAsync (MMCA.Common/Source/Presentation/MMCA.Common.UI.Web/SameOriginProxy/SameOriginApiProxyEndpoint.cs:274-286): Rejected ends the session, while Unavailable keeps the cookies and answers 503 with a Retry-After taken from outcome.RetryAfter or a short default (ADR-131).

ICookieSessionRefresher

MMCA.Common.API · MMCA.Common.API.SessionCookies · MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/CookieSessionRefresher.cs:32 · Level 10 · interface

• What it is: the "validate-or-refresh over the HttpOnly session cookies" port. It returns a currently-valid access token for the request, rotating from the refresh cookie when the access cookie has expired, in two shapes (a nullable token, or a SessionRefreshOutcome that separates a dead session from a transient failure), plus a forced rotation for when an API rejected a still-valid-looking access token.
• Depends on: HttpContext (ASP.NET Core), SessionTokenResult, SessionRefreshOutcome and SessionRefreshStatus. Its only implementation is CookieSessionRefresher.
• Concept introduced, server-side refresh that browser script never sees. [Rubric §11, Security] assesses where the long-lived credential lives. The type comment (MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/CookieSessionRefresher.cs:25-31) is the contract in prose: if the access cookie's JWT is still valid it is returned as-is; otherwise the refresh cookie is exchanged at the API's auth/refresh endpoint server-to-server, so the refresh token never reaches browser JS; the rotated pair is written back as HttpOnly cookies; and the fresh access token is stashed on HttpContext.Items so the current request's SSR authentication can read it before the Set-Cookie takes effect on the next request.
• Walkthrough: three members. Task<SessionTokenResult?> GetOrRefreshAsync(HttpContext context, CancellationToken cancellationToken = default) (:39) keeps the simple vocabulary: a value means "here is a good access token", null means "no session, treat this caller as anonymous"; its doc comment (:34-38) flags that setting fresh cookies is a side effect. Task<SessionRefreshOutcome> ValidateOrRefreshAsync(...) (:49) is the same operation with the failure kept apart: Rejected when there is no refresh cookie or the identity endpoint refused it, Unavailable for any other outcome (5xx, 429, 408, a misrouted 404, a 409 Auth.RefreshSuperseded, a timeout or a network failure), "so a caller that clears cookies on failure does so only for a session that is really dead" (:41-48). Task<SessionRefreshOutcome> RefreshAsync(...) (:60) exchanges the refresh cookie even when the access cookie still looks valid (the API rejected it: revoked, or signed with a rotated key), and is single-flighted exactly like GetOrRefreshAsync, so concurrent callers holding the same refresh cookie share one rotation (:51-59).
• Why it's built this way: one interface lets the SSR middleware, the /auth/session/token endpoint and the same-origin proxy share a single refresh path, so exactly one type decides validity and exactly one type rotates (ADR-022, ADR-131). Callers that render anonymously on any failure keep the nullable method; callers that clear cookies use the outcome methods. It is also what makes every caller testable against a mock.
• Where it's used: GetOrRefreshAsync by CookieSessionRefreshMiddleware (which runs before authentication on navigations), by the /auth/session/token handler (MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/SessionCookieEndpoints.cs:68) and by SessionHandoffEndpoints (MMCA.Common/Source/Presentation/MMCA.Common.UI.Web/SameOriginProxy/SessionHandoffEndpoints.cs:31); ValidateOrRefreshAsync and RefreshAsync by SameOriginApiProxyEndpoint (MMCA.Common/Source/Presentation/MMCA.Common.UI.Web/SameOriginProxy/SameOriginApiProxyEndpoint.cs:88, :321, :358). Registered as a singleton at MMCA.Common/Source/Presentation/MMCA.Common.API/DependencyInjection.cs:186.

CookieSessionRefreshMiddleware

MMCA.Common.API · MMCA.Common.API.SessionCookies · MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/CookieSessionRefreshMiddleware.cs:13 · Level 2 · class

• What it is: an ASP.NET Core middleware that runs before UseAuthentication on full-page navigations and, when the access cookie's JWT has expired but the refresh cookie is still good, refreshes server-side so SSR [Authorize] survives instead of bouncing to /login.
• Depends on: RequestDelegate and ICookieSessionRefresher, both primary-constructor parameters (MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/CookieSessionRefreshMiddleware.cs:13). Registered through CookieSessionRefreshMiddlewareExtensions.
• Concept introduced, refresh before authenticate for prerender. [Rubric §11, Security] and [Rubric §18, UI Architecture] meet here. A Blazor Web App prerenders [Authorize] pages on a cold GET (new tab, F5, external deep link), and authentication reads the cookie before any interactive code runs. If the access cookie has just expired, plain authentication fails and the user is redirected even though a perfectly good refresh token is sitting in the next cookie over. This middleware inserts a refresh attempt first, so the token the refresher stashes on HttpContext.Items is what authentication then reads.
• Walkthrough: InvokeAsync (:16-26) null-checks the context (:18), asks ShouldAttempt (:20), and on a match awaits refresher.GetOrRefreshAsync(context, context.RequestAborted) (:22) before invoking the rest of the pipeline (:25). The refresh is a side effect only: the return value is discarded and the pipeline always continues, leaving the actual authentication decision to the downstream scheme. ShouldAttempt (:28-31) gates strictly to GET requests whose Accept header contains text/html, so it never fires on static assets, API calls, or XHR.
• Why it's built this way: the narrow gate keeps a cookie read and a possible outbound HTTP call off every static-asset request, and delegating single-flight to the refresher means the middleware itself cannot double-rotate a token (ADR-022).
• Where it's used: registered on both Blazor Server hosts immediately before UseAuthentication(), MMCA.ADC/Source/Hosts/UI/MMCA.ADC.UI.Web/Program.cs:252 (with UseAuthentication() on the very next statement at :140) and MMCA.Store/Source/Hosts/UI/MMCA.Store.UI.Web/Program.cs:178 (:180). Its gating rules are pinned one test per branch in MMCA.Common/Tests/Presentation/MMCA.Common.API.Tests/SessionCookies/CookieSessionRefreshMiddlewareTests.cs: an HTML navigation refreshes (:19), a browser-style multi-value Accept list still matches (:31), a non-HTML Accept (:45), a missing Accept (:60) and a POST (:74) all skip, and a null refresh result still calls next (:90).
• Caveats / not-in-source: the ordering rule (before UseAuthentication) is enforced by the host that calls the extension, not by this class. Getting it wrong silently disables the SSR refresh rather than failing loudly.

SessionCookieEndpoints

MMCA.Common.API · MMCA.Common.API.SessionCookies · MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/SessionCookieEndpoints.cs:16 · Level 11 · class

• What it is: the minimal-API mapper for the three session-cookie routes: POST and DELETE /auth/session-cookie (seed and clear the HttpOnly cookies at login and logout) and POST /auth/session/token (the same-origin validate-or-refresh the browser calls to hydrate its in-memory access token). It also owns the two cookie-name constants and the cross-site guard.
• Depends on: SessionCookieJar, ICookieSessionRefresher, SessionCookieSettings (via IOptions<T>), SessionClaimsToken, SessionCookieRequest, SessionTokenResponse, and ASP.NET Core routing plus Results. The cookies it writes are read back by CookieTokenReader.
• Concept introduced, the cookie names are the shared contract. AccessTokenCookieName = "mmca_auth_access" and RefreshTokenCookieName = "mmca_auth_refresh" (MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/SessionCookieEndpoints.cs:18-19) are public const, and every other type in this feature (the jar, the reader, the refresher) references them instead of a string literal, so the names have exactly one definition. [Rubric §9, API & Contract Design] is the other lens: three tightly-scoped routes, all excluded from OpenAPI (ExcludeFromDescription at :33 and :80) because they are browser plumbing, not public API surface.
• Walkthrough: the mapping method lives inside an extension(IEndpointRouteBuilder endpoints) block (:21), the C# extension-member syntax this codebase uses for fluent registration (primer §2), so hosts call app.MapSessionCookieEndpoints(). Inside MapSessionCookieEndpoints (:23-85): a route group for /auth/session-cookie is created, excluded from description, and explicitly marked AllowAnonymous() (:32-34); the comment above it (:27-31) spells out why the anonymity has to be declared rather than left implicit: the POST seeds the cookie jar at login (except on a claims-only host, where it writes nothing and answers 204) and the DELETE clears it at logout, so both run before or after a session exists, and the default fallback authorization policy (SEC-Common-16) requires an authenticated caller on any endpoint that does not declare otherwise, which would make sign-in impossible on a Blazor host. The POST (:36-47) binds a SessionCookieRequest plus IOptions<SessionCookieSettings> and, unless ClaimsOnlyBrowserTokens is set (:41), calls SessionCookieJar.Append with the configured SameSite (:43); either way it returns 204 (:46). The comment at :38-40 explains the claims-only branch: on a proxied host the server is the only writer of the cookies and the browser holds nothing worth posting, and answering 204 rather than an error keeps a client written for the default mode signing in. The DELETE (:49-53) calls SessionCookieJar.Delete with the same configured SameSite (:51) and returns 204; both DisableAntiforgery() because there is no antiforgery token cookie to validate on these calls. The /auth/session/token POST (:60-82) first rejects an obvious cross-site request with 403 (:63-66), then awaits refresher.GetOrRefreshAsync (:68); a null result becomes a 401 JSON body { error = "no_session" } (:71). Otherwise the browser token is the real access token, or, on a claims-only host, SessionClaimsToken.Create(...) ?? string.Empty (:75-77, comment at :74), and a SessionTokenResponse is serialized (:78). That route is AllowAnonymous() (:81) because it authenticates via the cookies themselves. The private IsCrossSite (:91-93) inspects the Sec-Fetch-Site request header and treats a missing header as allowed, which the comment at :88-90 attributes to older browsers.
• Why it's built this way: CSRF is defended in depth rather than by antiforgery tokens. The comments at :58-59 and :88-90 spell it out: POST-only, the cookies' configured SameSite (which already blocks cross-site cookie attachment on a POST; the comments name Lax as the default and Strict on the same-origin proxy, both set through SessionCookieSettings), and the Sec-Fetch-Site check together stop a cross-site page from driving these endpoints, which is what makes disabling antiforgery safe here (ADR-022). [Rubric §11, Security]. The group-level AllowAnonymous() is the same defense-in-depth posture applied to authentication instead of CSRF: it is a deliberate, commented opt-out of the fallback policy (SEC-Common-16) rather than an oversight. The claims-only branches are what let the same three routes serve a proxied host without ever handing the browser a credential (ADR-131).
• Where it's used: mapped by both Blazor Server hosts, MMCA.ADC/Source/Hosts/UI/MMCA.ADC.UI.Web/Program.cs:283 and MMCA.Store/Source/Hosts/UI/MMCA.Store.UI.Web/Program.cs:261. The routes are exercised end to end by MMCA.Common/Tests/Presentation/MMCA.Common.API.Tests/SessionCookies/SessionCookieEndpointsTests.cs:125, whose CreateHostAsync builds a real pipeline around the mapper; the cases that matter most are the cross-site 403 (:60), the no-session 401 (:91), and the assertion that a valid session returns the access token but never the refresh token (:104). The claims-only branches are covered by MMCA.Common/Tests/Presentation/MMCA.Common.API.Tests/SessionCookies/ClaimsOnlySessionCookieEndpointsTests.cs: an unsigned claims copy instead of the credential (:27), script-supplied tokens ignored (:47), and the delete using the configured SameSite (:62).

SessionCookieJar

MMCA.Common.API · MMCA.Common.API.SessionCookies · MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/SessionCookieJar.cs:14 · Level 11 · class

• What it is: the one internal static helper that writes and clears the two HttpOnly auth cookies, so the endpoints, the server-side refresher, and the public cookie store all emit identical cookie options.
• Depends on: CookieOptions, HttpContext, IWebHostEnvironment and SameSiteMode (ASP.NET Core) plus the cookie-name constants on SessionCookieEndpoints. The SameSite value its callers pass comes from SessionCookieSettings.
• Concept introduced, one place to build cookie options. [Rubric §11, Security] assesses cookie hardening. Centralizing BuildOptions (MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/SessionCookieJar.cs:61-68) means every write is HttpOnly = true (:63), Secure outside Development (:64, !environment.IsDevelopment(), so http://localhost dev still works while every deployed environment forces HTTPS), SameSite set to the caller's mode (:65), and Path = "/" (:66). Drift between the seed, refresh, store and clear paths is structurally impossible because all of them call this method. The conditional Secure is the one thing an analyzer objects to, and the suppression carries its justification inline (:60 and :69 bracket a scoped #pragma warning disable S2092), which is the house style for an accepted deviation.
• Walkthrough: DefaultLifetime = TimeSpan.FromDays(7) (:18) is the refresh-token lifetime's default (JwtSettings.RefreshTokenExpirationDays, MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Auth/JwtSettings.cs:64), used when the host configures neither the cookie lifetime nor the Jwt section (comment :16-17). Append has two overloads: the four-argument form (:20-21) forwards with SameSiteMode.Lax, and the five-argument form (:23-28) builds options once with the given SameSite and the resolved lifetime, and writes both cookies with it as MaxAge. ResolveLifetime(HttpContext) (:35-48, doc :30-34) picks that lifetime in order: SessionCookieSettings.Lifetime when the host set it (:40-43), else JwtSettings.RefreshTokenExpirationDays when the Jwt section is bound and positive (:45-47), else DefaultLifetime. It reads both through context.RequestServices with GetService, null-tolerant because the property is null on a bare DefaultHttpContext (comment :37-38). Delete mirrors Append: the three-argument form (:50-51) forwards with Lax, and the four-argument form (:53-58) rebuilds the options with TimeSpan.Zero, which :67 turns into a null MaxAge, and calls Cookies.Delete for both names.
• Why it's built this way: a delete must send back the same Path, SameSite and Secure attributes as the original write or the browser will not match the cookie and will not clear it. Sharing BuildOptions between Append and Delete, and having every caller pass the same configured SameSite, guarantees that (ADR-022). The Lax-defaulting overloads keep the long-standing call shape for callers with no settings in hand.
• Where it's used: SessionCookieEndpoints (seed at SessionCookieEndpoints.cs:43, clear at :51), CookieSessionRefresher (rewrite after rotation, CookieSessionRefresher.cs:143) and SessionCookieStore (ISessionCookieStore.cs:33 and :36), all passing SessionCookieSettings.SameSite. Its BuildOptions is also named as the precedent for the culture cookie's conditional Secure suppression (MMCA.Common/Source/Presentation/MMCA.Common.API/Startup/WebApplicationExtensions.cs:124). The attributes it emits are asserted directly by MMCA.Common/Tests/Presentation/MMCA.Common.API.Tests/SessionCookies/SessionCookieJarTests.cs.

CookieSessionRefreshMiddlewareExtensions

MMCA.Common.API · MMCA.Common.API.SessionCookies · MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/CookieSessionRefreshMiddleware.cs:35 · Level 3 · class

• What it is: a one-method registration helper (UseCookieSessionRefresh) that adds CookieSessionRefreshMiddleware to the request pipeline.
• Depends on: IApplicationBuilder (ASP.NET Core) and CookieSessionRefreshMiddleware.
• Concept: the standard UseXxx() middleware-registration idiom, written with the codebase's extension(IApplicationBuilder app) member syntax (MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/CookieSessionRefreshMiddleware.cs:37); see primer §2. Nothing new beyond putting a name and a doc comment on UseMiddleware<T>.
• Walkthrough: UseCookieSessionRefresh() (:43-47) null-guards the builder (:45) and returns app.UseMiddleware<CookieSessionRefreshMiddleware>() (:46). The XML comment (:39-42) states the load-bearing rule in bold: register it immediately before UseAuthentication() on the Blazor Server (UI.Web) host.
• Where it's used: the two Blazor Server hosts (MMCA.ADC/Source/Hosts/UI/MMCA.ADC.UI.Web/Program.cs:252, MMCA.Store/Source/Hosts/UI/MMCA.Store.UI.Web/Program.cs:178). Both the null guard and the pipeline wiring are covered directly at MMCA.Common/Tests/Presentation/MMCA.Common.API.Tests/SessionCookies/CookieSessionRefreshMiddlewareTests.cs:115 and :123.

CookieTokenReader

MMCA.Common.API · MMCA.Common.API.SessionCookies · MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/CookieTokenReader.cs:10 · Level 3 · class

• What it is: the read side of the cookie feature. It pulls the access JWT and the refresh token out of the request cookies (or out of the freshly-refreshed token stashed on HttpContext.Items) for server-side token storage during SSR prerender, when JS interop and therefore localStorage are unreachable.
• Depends on: IHttpContextAccessor (primary constructor, MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/CookieTokenReader.cs:10) and the cookie-name constants on SessionCookieEndpoints. Consumed by SessionCookieAuthenticationHandler and by ServerTokenStorageService.
• Concept introduced, the fresh-token handoff. [Rubric §29, Resilience, Reliability & Business Continuity] covers request-scoped state. The internal const string FreshAccessTokenItemKey = "mmca.fresh-access-token" (:17) is the agreed HttpContext.Items key under which CookieSessionRefresher parks a just-rotated access token, as the comment at :12-16 explains. ReadAccessToken checks that key first, so on the very request that triggered a refresh, SSR authentication uses the new token instead of the still-expired one sitting in the request cookie; the Set-Cookie from the rotation only affects the next request.
• Walkthrough: ReadAccessToken (:19-34) returns null when there is no HttpContext (:22-25), then prefers a non-empty string under FreshAccessTokenItemKey (:27-31), and otherwise falls back to the access cookie (:33). The fresh is string freshToken pattern plus the whitespace check mean a wrong-typed or blank item silently falls through to the cookie rather than poisoning the request. ReadRefreshToken (:36-37) reads the refresh cookie directly with a null-conditional accessor and has no fresh-item fallback, because only the access token is ever swapped mid-request.
• Why it's built this way: the Items-first precedence is exactly what makes the middleware's server-side refresh take effect on the request that triggered it instead of only on the next one (ADR-022).
• Where it's used: injected into SessionCookieAuthenticationHandler (SessionCookieAuthenticationHandler.cs:28) and into the UI host's server-side token store (MMCA.Common/Source/Presentation/MMCA.Common.UI.Web/Services/ServerTokenStorageService.cs:32). Registered scoped by AddServerAuthSessionCookie (MMCA.Common/Source/Presentation/MMCA.Common.API/DependencyInjection.cs:180), and covered by MMCA.Common/Tests/Presentation/MMCA.Common.API.Tests/SessionCookies/CookieTokenReaderTests.cs.

SessionCookieStore

MMCA.Common.API · MMCA.Common.API.SessionCookies · MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/ISessionCookieStore.cs:28 · Level 12 · class

• What it is: the internal implementation of ISessionCookieStore: a two-line adapter that forwards to SessionCookieJar with the configured SameSite.
• Depends on: IWebHostEnvironment and IOptions<SessionCookieSettings> (primary constructor, MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/ISessionCookieStore.cs:28-30), SessionCookieSettings and SessionCookieJar.
• Concept: the adapter half of the public-port-over-internal-helper split introduced at ISessionCookieStore. It adds no behavior of its own, which is the point: every cookie option still comes from the jar's single BuildOptions.
• Walkthrough: Write (:32-33) calls SessionCookieJar.Append(context, accessToken, refreshToken, environment, settings.Value.SameSite); Clear (:35-36) calls SessionCookieJar.Delete(context, environment, settings.Value.SameSite). Reading settings.Value on each call means writes and deletes always agree on SameSite.
• Why it's built this way: internal sealed, so consumers outside MMCA.Common.API depend on the interface and the jar stays hidden; the one-line summary at :27 names it "the ISessionCookieStore over SessionCookieJar".
• Where it's used: registered as the singleton ISessionCookieStore by AddServerAuthSessionCookie (MMCA.Common/Source/Presentation/MMCA.Common.API/DependencyInjection.cs:191); see ISessionCookieStore for the proxy types that consume it.

SessionCookieAuthenticationHandler

MMCA.Common.API · MMCA.Common.API.SessionCookies · MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/SessionCookieAuthenticationHandler.cs:24 · Level 4 · class

• What it is: an ASP.NET Core AuthenticationHandler that reads the JWT out of the session cookie, parses its claims, and populates HttpContext.User during SSR prerender, so both Blazor's internal SSR authorization and endpoint-level [Authorize] pass on a fresh GET before the interactive phase starts.
• Depends on: AuthenticationHandler<AuthenticationSchemeOptions> and its three framework constructor arguments (IOptionsMonitor, ILoggerFactory, UrlEncoder) plus CookieTokenReader (MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/SessionCookieAuthenticationHandler.cs:24-29), and System.IdentityModel.Tokens.Jwt. Registered by SessionCookieAuthenticationExtensions.
• Concept introduced, a deliberately non-validating scheme. [Rubric §11, Security] assesses where the trust decision is actually made. The <remarks> block (:18-23) is load-bearing: this handler does not validate the JWT signature. The cookie was minted by the UI host in response to a successful login against the API, and every real API call still performs full JWT validation, so the handler exists only to extract claims for ASP.NET Core's auth system during prerender. That is what lets a deep-linked [Authorize] page render instead of flashing a redirect. Read it next to ADR-004: the API remains the single validation authority via JWKS, and the UI host deliberately does not duplicate it.
• Walkthrough: SchemeName = "SessionCookie" (:32) is the canonical scheme name, exposed as a public const so registration never repeats a literal. HandleAuthenticateAsync (:35-69) reads the token through CookieTokenReader (:37) and returns AuthenticateResult.NoResult() when there is none (:38-41), which lets other schemes have their turn rather than hard-failing the request. It then rejects anything that is not a readable JWT (:46-49), and fails when jwt.ValidTo is in the past according to the base handler's injectable TimeProvider (:55-58, with the rationale at :53-54). On success it builds a ClaimsIdentity from the JWT claims with ClaimTypes.NameIdentifier and ClaimTypes.Role as the name and role claim types (:60), wraps it in a ClaimsPrincipal and an AuthenticationTicket stamped with the scheme name (:61-63), and returns Success. Malformed-token exceptions are narrowed to ArgumentException and FormatException and returned as Fail (:65-68). HandleChallengeAsync (:72-77) redirects to /login?returnUrl=... with the original path and query URL-escaped (:74-75), and HandleForbiddenAsync (:80-84) sets a bare 403.
• Why it's built this way: validating the signature here would duplicate the API's JWKS validation and couple the UI host to the signing key. Extracting claims only, while the API stays the single authority, keeps the trust boundary in one place (ADR-004 and ADR-022). Reading the clock through the base handler's TimeProvider rather than DateTime.UtcNow keeps the expiry check on the same injectable clock as the rest of the auth stack and its tests. [Rubric §14, Testability].
• Where it's used: registered as the SessionCookie scheme on both Blazor Server hosts, MMCA.ADC/Source/Hosts/UI/MMCA.ADC.UI.Web/Program.cs:107-108 and MMCA.Store/Source/Hosts/UI/MMCA.Store.UI.Web/Program.cs:111-112. Covered directly by MMCA.Common/Tests/Presentation/MMCA.Common.API.Tests/SessionCookies/SessionCookieAuthenticationHandlerTests.cs, including the fresh-token-from-Items path (:95, which stashes the token under CookieTokenReader.FreshAccessTokenItemKey at :102 and asserts it wins over an expired cookie) and the proof that expiry is judged by the handler's TimeProvider rather than the system clock (:112).

CookieSessionRefresher

MMCA.Common.API · MMCA.Common.API.SessionCookies · MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/CookieSessionRefresher.cs:75 · Level 13 · class

• What it is: the singleton implementation of ICookieSessionRefresher. It validates the access cookie's JWT locally and, when that fails (or when a caller forces it), exchanges the refresh cookie at the API's auth/refresh endpoint server-to-server, writes the rotated pair back as cookies, single-flights concurrent refreshes so a burst of requests rotates the token only once, forwards the browser's own user-agent and IP to the identity endpoint, and classifies every failure as a dead session or a transient one.
• Depends on: IHttpClientFactory, IMemoryCache, IWebHostEnvironment, ILogger<CookieSessionRefresher>, TimeProvider and IOptions<SessionCookieSettings> (primary constructor, MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/CookieSessionRefresher.cs:75-81); KeyedSemaphoreStripe (:88); SessionCookieJar; SessionCookieSettings for the cookie SameSite; SessionRefreshOutcome and SessionRefreshStatus; CookieTokenReader for the Items key; SessionCookieEndpoints for the cookie names; and the AuthenticationResponse / RefreshTokenRequest contracts from MMCA.Common.Shared.Auth. It reads token expiry with System.IdentityModel.Tokens.Jwt and names Polly.ExecutionRejectedException in its catch filter.
• Concept introduced, single-flight refresh under a thundering herd. [Rubric §12, Performance & Scalability] assesses behavior under concurrent load. When an access token expires, many queued navigations can arrive at once; rotating for each would burn the refresh token repeatedly and log the user out. The type comment (:63-74) states the design: the lock is a striped KeyedSemaphoreStripe keyed by refresh token rather than one process-wide semaphore, because the lock is held across an outbound HTTP call and a single semaphore would serialize every unrelated user's cold navigation behind whichever refresh happened to be in flight. Two unrelated tokens can still land on the same one of the stripe's 256 lanes (MMCA.Common/Source/Core/MMCA.Common.Shared/Concurrency/KeyedSemaphoreStripe.cs:25), which the comment calls out as harmless precisely because the rotation-grace cache is re-checked per token after acquiring. Alongside the lock, a 10-second RotationGrace (:86) caches the rotated pair keyed by the OLD refresh token (:208), so a slightly-late sibling carrying the same expired pair gets the same result instead of rotating again.
• Walkthrough: GetOrRefreshAsync (:90-91) is a projection: it awaits ValidateOrRefreshAsync and returns its .Session, so every failure becomes null. ValidateOrRefreshAsync (:93-104) reads the access cookie (:97) and, if TryReadValidExpiry passes, returns a Refreshed outcome around it untouched (:98-101); otherwise it delegates to RefreshFromCookiesAsync (:103). The public RefreshAsync (:106-112) skips the validity check and goes straight to RefreshFromCookiesAsync (:111), which is the forced rotation the interface promises. RefreshFromCookiesAsync (:128-149) returns Rejected when there is no refresh cookie (:131-134), captures the browser's identity with BrowserOrigin.From(context) (:136), calls the private RefreshAsync (:137) and passes its failure through (:138-141), writes the rotated pair with SessionCookieJar.Append and the configured SameSite (:143), stashes the fresh access token on context.Items[CookieTokenReader.FreshAccessTokenItemKey] (:147, with the reason at :145-146), and returns a Refreshed outcome around the new SessionTokenResult (:148). The private RefreshAsync (:151-168) is textbook double-checked locking: a cache hit returns immediately (:154-157), otherwise it acquires the stripe for this token (:159) and re-checks the cache before doing any work (:162-165). CallRefreshAsync (:170-220) creates the named client (:173), builds an HttpRequestMessage POST to the relative auth/refresh URI carrying a RefreshTokenRequest as JSON content (:186-190), lets the captured origin stamp its headers (:191), and sends it with CancellationToken.None (:192) so that once the lock is held the rotation completes and writes its cookies even if the triggering request was aborted (the reason is at :184-185). A non-success status goes through ClassifyFailure (:194-199): Rejected, or Unavailable carrying the parsed Retry-After. An empty access token is Unavailable (:202-205). Success caches the AuthenticationResponse under the old refresh token for RotationGrace (:208). ClassifyFailure (:123-126) is internal static: 400, 401 and 403 are the identity endpoint refusing the token, so Rejected; anything else (5xx, 429, 408, a 404 from a misrouted gateway, and a 409) says nothing about the token, so Unavailable (doc :114-122). The 409 case is Auth.RefreshSuperseded: another request (a second tab, or the same browser served by another replica) rotated this token a moment ago, inside RefreshSessions:ReuseGraceSeconds, and the browser picks up the winner's cookie on its next request, so the session is kept (ADR-097). ReadRetryAfter (:222-241) accepts either form of the header, a delta (:229-232) or a date measured against the injected TimeProvider (:234-238), and clamps a negative result to zero. TryReadValidExpiry (:243-272) rejects a blank token, refuses anything JwtSecurityTokenHandler cannot read (:252-255), treats the token as expired when jwt.ValidTo <= timeProvider.GetUtcNow().UtcDateTime + ClockSkew (:260, with ClockSkew a 30-second margin at :85), and swallows only ArgumentException/FormatException (:268-271); it is an instance method because it reads the injected clock. CacheKey (:278) builds the mmca:session-refresh:{refreshToken} string that is both the cache key and the striping key; the comment at :274-277 explains it is internal rather than private so a concurrency test can pick two refresh tokens that do not collide on a stripe, which is a nice example of a testability affordance that costs nothing at runtime. [Rubric §14, Testability]: the injected TimeProvider is the same kind of affordance, letting tests move the clock instead of minting tokens around the wall clock.
• Concept, forwarding the browser's identity on a server-to-server hop. [Rubric §11, Security] and [Rubric §13, Observability & Operability] apply to what the identity endpoint records. Because this host, not the browser, calls auth/refresh, a bare call would stamp the rotated session with the host's own empty user-agent and loopback address. The private BrowserOrigin record struct (:283-313) is captured from the triggering request before the lock is taken (:136, doc :283-288): From reads the User-Agent header, treating blank as null, and the connection's remote IP (:291-297). ApplyTo (:299-312) adds User-Agent and X-Forwarded-For to the outbound request with TryAddWithoutValidation (:305, :310), because a real browser user-agent does not always parse as a strict product-token list and the value is informational only. The identity endpoint trusts X-Forwarded-For through CommonForwardedHeaders. Capturing it before RefreshAsync matters because the work that follows runs under the lock and cache, where the triggering HttpContext is no longer the thing being read.
• Concept, an SSR-safe failure mode that does not sign users out. [Rubric §29, Resilience, Reliability & Business Continuity] and [Rubric §13, Observability & Operability] apply to the outbound call. CallRefreshAsync wraps the POST in a try whose filter narrows to HttpRequestException, OperationCanceledException, JsonException, NotSupportedException and Polly.ExecutionRejectedException (:214-215); the comment at :211-213 explains the last one: the resilience pipeline's own refusals (a timed-out attempt, an open circuit, a rate-limited call) throw it, for example TimeoutRejectedException with the gateway down, which is neither transport exception. The catch logs one warning through the source-generated LogRefreshCallFailed (:217, declared with [LoggerMessage] at :280-281, which is why the class is partial at :75) and returns Unavailable (:218). The comment at :175-181 gives the reasoning: this code runs during SSR, so an escaping exception would turn a signed-in user's navigation into a 500 instead of an anonymous render; it is Unavailable, not Rejected, because nothing said the refresh token is dead, so a caller that clears cookies must keep them. The failure is deliberately not cached (only a successful rotation reaches cache.Set at :208), so the next navigation retries, and a missing BaseAddress raises InvalidOperationException and is left to propagate because that is a host misconfiguration rather than a runtime condition.
• Why it's built this way: keying the grace cache by the OLD token is what lets a slightly-late sibling find the already-rotated pair, and striping the lock keeps one user's slow refresh from blocking everyone else's cold navigation. The server-to-server call is what keeps the refresh token off browser JS (ADR-022). [Rubric §11, Security]. Separating Rejected from Unavailable is what lets the same-origin proxy clear cookies only for a session that is really over and answer a transient identity-endpoint fault with 503 plus Retry-After (ADR-131).
• Where it's used: resolved as ICookieSessionRefresher by CookieSessionRefreshMiddleware, by the /auth/session/token endpoint, and by the same-origin proxy (SameOriginApiProxyEndpoint, SessionHandoffEndpoints). Its named HttpClient, RefreshClientName = "SessionCookieRefreshClient" (:83), is configured with the API base address in AddServerAuthSessionCookie (MMCA.Common/Source/Presentation/MMCA.Common.API/DependencyInjection.cs:182-183), which also registers the refresher as a singleton (:186) with an inline note (:185) that a shared instance across requests is what makes single-flight work at all, and registers TimeProvider.System with TryAdd (:196) because a Blazor Web host calling only this method has no other clock registration (comment :193-195). The validate, rotate, grace-cache and failure paths are covered by MMCA.Common/Tests/Presentation/MMCA.Common.API.Tests/SessionCookies/CookieSessionRefresherTests.cs, including refusal as Rejected (:362, :377), undecidable statuses as Unavailable with no cookies written (:389), the rotation-race 409 as Unavailable that keeps the cookies (:419, :446), resilience-pipeline rejections (:465), both Retry-After forms (:489, :505), the forwarded user-agent and IP (:80, :97) and expiry judged against the injected clock (:61).

SessionCookieAuthenticationExtensions

MMCA.Common.API · MMCA.Common.API.SessionCookies · MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/SessionCookieAuthenticationHandler.cs:90 · Level 5 · class

• What it is: the registration helper for SessionCookieAuthenticationHandler: a single AddSessionCookieAuthentication() that wires the scheme into an AuthenticationBuilder.
• Depends on: AuthenticationBuilder (ASP.NET Core) and SessionCookieAuthenticationHandler.
• Concept: the same extension(T) DI-registration idiom introduced by the other extension helpers in this group. The method is declared inside an extension(AuthenticationBuilder builder) block (MMCA.Common/Source/Presentation/MMCA.Common.API/SessionCookies/SessionCookieAuthenticationHandler.cs:92) and reads at the call site as an instance method on the builder; see primer §2.
• Walkthrough: AddSessionCookieAuthentication() (:98-100) is a single expression: builder.AddScheme<AuthenticationSchemeOptions, SessionCookieAuthenticationHandler>( SessionCookieAuthenticationHandler.SchemeName, displayName: null, configureOptions: null). The scheme name comes from the handler's own constant rather than a duplicated literal, and the two explicit null arguments are named, so the call site says what it is skipping. The doc comment (:94-97) directs callers to use it after AddAuthentication(SessionCookieAuthenticationHandler.SchemeName).
• Where it's used: MMCA.ADC/Source/Hosts/UI/MMCA.ADC.UI.Web/Program.cs:108 and MMCA.Store/Source/Hosts/UI/MMCA.Store.UI.Web/Program.cs:112, chained onto the host's AddAuthentication(SessionCookieAuthenticationHandler.SchemeName) call on the preceding line.

PasswordResetSettings

MMCA.Common.Application · MMCA.Common.Application.Auth · MMCA.Common/Source/Core/MMCA.Common.Application/Auth/PasswordResetSettings.cs:10 · Level 0 · class (sealed)

• What it is: the bound options object for the forgot-password workflow: where the reset page lives, how long a token stays redeemable, how many wrong guesses a token tolerates, and how often one address may ask for a reset (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/PasswordResetSettings.cs:6-9).
• Depends on: System.ComponentModel.DataAnnotations for the range attributes and System.Diagnostics.CodeAnalysis for one scoped suppression (BCL, :1-2). Nothing first-party. Read by the implementation behind IPasswordResetTokenService and by the shared ForgotPasswordHandlerBase<TUser, TCommand>.
• Concept: validated options whose defaults keep an unconfigured host bootable. [Rubric §17, DevOps & Deployment] assesses whether policy knobs are configuration rather than constants buried in a handler, and [Rubric §11, Security] assesses whether the security-relevant knobs (token lifetime, attempt cap, request throttle) are bounded rather than free-form. Every numeric member carries a [Range] attribute, and the host binds the section with ValidateDataAnnotations().ValidateOnStart() (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:160-163), so a typo such as TokenLifetimeMinutes: 0 fails the host at startup instead of silently issuing tokens that are already expired.
• Walkthrough: const string SectionName = "PasswordReset" (:13) names the configuration section the host binds. ResetUrl (:25) defaults to string.Empty and is deliberately not [Required]: the doc comment (:15-20) records that a host which has not configured a UI base must still boot, and an empty value degrades to a token-only email the user pastes into the reset page by hand. That degradation is visible in the caller, which emits the bare token when the URL is blank and otherwise appends the escaped address and token as a URL fragment, #email=...&token=... (MMCA.Common/Source/Core/MMCA.Common.Application/Users/UseCases/ForgotPassword/ForgotPasswordHandlerBase.cs:153-155). A fragment is never sent to the server in the HTTP request, which is the reason the doc comment gives (:16-17): the live token never reaches a server or proxy access log the way a query string would. The property carries a scoped CA1056 suppression (:21-24) explaining why it is a string and not a System.Uri: it is bound from PasswordReset__ResetUrl, concatenated with a URL fragment, and the empty default is not a valid Uri. The four numeric knobs follow: TokenLifetimeMinutes (:29, [Range(1, 1440)], default 30), MaxValidationAttempts (:36, [Range(1, 100)], default 5), MaxRequestsPerEmail (:40, [Range(1, 100)], default 3), and RequestWindowMinutes (:44, [Range(1, 1440)], default 60). All five members are init-only, so the bound instance is immutable afterwards.
• Why it's built this way: the defaults are a working policy on their own, so adopting the feature costs a registration call and no configuration at all, while the [Range] bounds plus ValidateOnStart make the one genuinely dangerous class of misconfiguration (a zero or negative lifetime, an unbounded attempt cap) unreachable. The decision to keep the whole reset credential in configuration and cache rather than in schema is ADR-091.
• Where it's used: bound in the framework's Infrastructure registration (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:160-163, immediately before the token service that reads it is registered at :164); consumed by PasswordResetTokenService as a snapshot field (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Auth/PasswordResetTokenService.cs:45) for the request window, the throttle ceiling, the token lifetime, and the attempt cap; and exposed to the shared forgot-password handler as a protected Settings property (ForgotPasswordHandlerBase.cs:49) that states the expiry in the email body (:126) and renders the fragment link (:153-155).

RefreshSessionSettings

MMCA.Common.Application · MMCA.Common.Application.Auth · MMCA.Common/Source/Core/MMCA.Common.Application/Auth/RefreshSessionSettings.cs:9 · Level 0 · class (sealed)

• What it is: the bound options object for multi-device refresh sessions: whether this host owns the RefreshSessions table, which database carries it, how many live sessions one user may hold, and how long dead session rows are retained before a sweep deletes them (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/RefreshSessionSettings.cs:5-8). A host that omits the section gets the defaults.
• Depends on: System.ComponentModel.DataAnnotations (BCL, :1). Nothing first-party. Read by AuthSessionIssuer, by EFRefreshSessionStore, by ApplicationDbContext, and by RefreshSessionCleanupService.
• Concept introduced: a flag that places a table rather than switching a feature. [Rubric §8, Data Architecture] assesses whether each table has exactly one owning database, and [Rubric §7, Microservices Readiness] assesses whether that ownership survives splitting a modular host into services. The doc comment on Enabled states the distinction precisely (:20-23): the flag "gates the model, not the workflow". The workflow always issues, rotates and revokes sessions; Enabled decides which host maps the table, runs its migrations, and sweeps it. In a modular host the service that owns identity sets it to true and every other service leaves it false, which is what keeps one table in one database instead of one per service. The Scheduler:Enabled precedent is named in the same comment as the pattern being followed.
• Walkthrough: seven members, all init-only.
  • const string SectionName = "RefreshSessions" (:12) names the configuration section.
  • Enabled (:25) defaults to false. Two places read it: the model gate in ApplicationDbContext, which enables the table only when the flag is set and the context instance's physical source name equals DataSourceName (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/ApplicationDbContext.cs:336-339), and the hosted-service registration, which starts the retention sweep only when the flag is set (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:182-186, whose comment explains that registering it unconditionally would start a sweep in every service of a modular host, all but one of which has no table to sweep).
  • MaxActiveSessionsPerUser (:35, [Range(1, 1000)], default 10) caps live sessions per user. The comment (:28-33) records the deliberate behavior at the ceiling: signing in on device number cap + 1 revokes the oldest live session rather than refusing the login, so the table is bounded without a legitimate sign-in ever failing.
  • DataSourceName (:52, [MinLength(1)], default "Default") names the logical data source whose database holds the table. The comment (:37-49) is worth reading in full: the value answers two questions that must agree, which context maps the table and which context the shipped IRefreshSessionStore reads and writes through, and naming a source that does not exist fails loudly on the first session query rather than reading the wrong database. It is ignored for routing when the consumer ships its own entity configuration for the session entity.
  • RetentionDays (:72, [Range(0, 3650)], default 30) is measured from the instant a session died (its revocation, or its expiry when never revoked), so a live session is never a sweep candidate. The comment (:59-66) states the constraint that makes the number security-relevant: retention bounds reuse detection, because BR-206 catches a replayed refresh token by landing on its revoked row, and a swept row turns that replay into an unknown token that fails alone instead of revoking the family. Thirty days sits well past the seven-day refresh-token lifetime for exactly that reason. 0 keeps every row forever (:67-69).
  • CleanupIntervalHours (:80, [Range(1, 168)], default 6) is how often the sweep runs, ignored when RetentionDays is 0, and matches the outbox sweep cadence because the deadline is measured in days (:74-77).
  • ReuseGraceSeconds (:98, [Range(0, 300)], default 10) is how long after a session was rotated a second presentation of its token counts as a rotation race rather than reuse (:82-96). Two tabs, or one browser served by two replicas, can present the same refresh token a moment apart; the later request is answered 409 Conflict (Auth.RefreshSuperseded) with nothing revoked, and the client retries with the winner's token. The default matches the cookie refresher's rotation grace. The comment is explicit that this is a security trade-off: a stolen-token replay arriving inside the window gets a 409 instead of the BR-206 family revocation. Only a row revoked as Rotated qualifies, so a row already flagged as reuse still revokes the family however recent, and 0 treats every rotated token that comes back as reuse.
• Why it's built this way: the same AddOptions(...).Bind(...).ValidateDataAnnotations().ValidateOnStart() treatment as every other settings class in the framework (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:168-171) means an out-of-range cap or a negative retention window fails the host at startup, not at the first login. Defaulting Enabled to false is the safe direction for a multi-service host: a service that never opts in never grows a table it does not own.
• Where it's used: bound at MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:168-171; injected as IOptions<RefreshSessionSettings> into AuthSessionIssuer (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/Sessions/AuthSessionIssuer.cs:44, read for the reuse grace at :481 and the cap at :514), into EFRefreshSessionStore (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Auth/EFRefreshSessionStore.cs:35), and into RefreshSessionCleanupService (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Auth/RefreshSessionCleanupService.cs:51, snapshotted at :55). The design-time context helper supplies an instance so dotnet ef can build a model that includes the table (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/Design/DesignTimeDbContextHelper.cs:173-174). The app Identity services no longer take it: the issuer owns it, so ADC's AuthenticationService has no reference to it.

UserAdministrationQuery

MMCA.Common.Application · MMCA.Common.Application.Auth.Administration · MMCA.Common/Source/Core/MMCA.Common.Application/Auth/Administration/IUserAdministrationService.cs:79 · Level 0 · record struct

• What it is: the paging and filter parameters for IUserAdministrationService<TUserDto>'s ListAsync: a page number, a page size, an optional free-text search term, and an optional role filter (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/Administration/IUserAdministrationService.cs:79-83).
• Depends on: nothing beyond the BCL (string, int). It exists purely as the input shape to IUserAdministrationService<TUserDto>.ListAsync.
• Concept introduced: a query parameter object at an admin list boundary. [Rubric §9, API & Contract Design] assesses whether a list endpoint's inputs are a named, typed shape rather than several loose parameters strung along a signature. A readonly record struct gives value equality for free and keeps the four knobs, paging plus the two optional filters, together at the controller, the service, and any test double.
• Walkthrough: a four-member positional declaration: PageNumber and PageSize (required), SearchTerm and Role (both string?, default null, meaning "no filter").
• Why it's built this way: a record struct rather than a class avoids a heap allocation for a value that is built once, passed to one call, and discarded, and the two optional filters default to null so a caller that wants an unfiltered page supplies only the paging pair.
• Where it's used: built by UsersAdminControllerBase (MMCA.Common/Source/Presentation/MMCA.Common.API/Controllers/Administration/UsersAdminControllerBase.cs) from the incoming query string and passed to IUserAdministrationService<TUserDto>.ListAsync; consumed by each app's UserAdministrationService, for example MMCA.ADC/Source/Modules/Identity/MMCA.ADC.Identity.Application/Users/Administration/UserAdministrationService.cs.

UnconfiguredPermissionRegistry

MMCA.Common.Application · MMCA.Common.Application.Auth · MMCA.Common/Source/Core/MMCA.Common.Application/Auth/UnconfiguredPermissionRegistry.cs:20 · Level 1 · class (internal sealed partial)

• What it is: the fallback IPermissionRegistry (and, since it also implements IPermissionCatalog, the fallback catalog) for a host that wired the CQRS pipeline without declaring any role-to-permission grants. It grants nothing, so a permission-gated command or query is denied rather than allowed, and it logs one warning naming the call that would fix it (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/UnconfiguredPermissionRegistry.cs:6-11).
• Depends on: IPermissionRegistry and IPermissionCatalog (:20), IRequiresPermission by reference in the doc comment (:9), and Microsoft.Extensions.Logging for the source-generated log message (:1).
• Concept introduced: failing closed, and only where it costs nothing. [Rubric §11, Security] assesses the direction a misconfiguration fails in: a registry that answered "no permission model, therefore allow" would silently open every gated request, so this one denies, and now that it doubles as the fallback IPermissionCatalog it renders an empty catalog rather than throwing, so a role-administration screen on an unconfigured host reads as "this host grants nothing yet" instead of failing (:225-228). [Rubric §13, Observability & Operability] assesses whether an operator can tell why: the log message spells out the remedy verbatim (:264-267, naming AddAuthorizationPolicies() / AddPermissions(...) and the required ordering before AddApplicationDecorators()). The second half of the doc comment (:12-17) is the more interesting teaching point and is an availability story rather than a security one: the two authorization decorators are registered unconditionally and take an IPermissionRegistry constructor dependency, so without any registration the whole pipeline fails to activate and a small app with no Identity module answers 500 on every read, not only the gated ones. This type turns a total activation failure into a correct, noisy denial on the subset of requests that actually declare a permission.
• Walkthrough: two fields, two catalog properties, and three methods.
  • private static readonly HashSet<string> None = [] (:221) is the single empty grant set every permission call returns, and private int _warned (:223) is the one-time-warning latch.
  • IReadOnlyList<string> Roles => [] (:229) and IReadOnlyList<string> Permissions => [] (:232) are the IPermissionCatalog members: both always empty, so an unconfigured host's role editor renders no roles and no permissions to pick from rather than erroring.
  • GetPermissions(string role) (:235-239) warns then returns None.
  • HasPermission(IEnumerable<string> roles, string permission) (:242-249) argument-guards both parameters (:244-245) before warning and returning false, so a caller bug still surfaces as an ArgumentException rather than being swallowed by the stub.
  • WarnOnce() (:256-262) uses Interlocked.Exchange(ref _warned, 1) == 0 (:258) so concurrent requests produce exactly one log line. The comment (:251-255) explains why the warning is deferred to the first permission check instead of emitted at startup: a host with no permission-gated request is correctly configured and simply never needs a registry, so warning at boot would cry wolf. Reading the catalog properties never triggers the warning, only GetPermissions/HasPermission do.
  • LogNoPermissionsConfigured (:264-267) is a [LoggerMessage] source-generated Warning, which is why the class is partial.
• Why it's built this way: it is registered with TryAddSingleton from inside AddApplicationDecorators() (MMCA.Common/Source/Core/MMCA.Common.Application/DependencyInjection.cs:123), and the surrounding comment (:119-123) states both halves of the rule: TryAdd so a host that already declared its grants (via AddAuthorizationPolicies() or AddPermissions(...), both of which run before this call) keeps its own registry and never constructs this type, and here rather than in AddApplication() so the registration lands exactly where the decorators that need it are wired. Adding IPermissionCatalog to the same fallback type, rather than a second stub class, means the one TryAddSingleton call keeps both ports covered from the same no-op instance.
• Where it's used: reached through the IPermissionRegistry dependency of the authorization command and query decorators in the CQRS pipeline (see group 05), and through the IPermissionCatalog dependency of IRoleAdministrationService's GetCatalogAsync on a host that never configured a registry.
• Caveats / not-in-source: internal, so it is not part of the framework's public API and cannot be referenced or asserted against from a consumer's code.

ILoginProtectionService

MMCA.Common.Application · MMCA.Common.Application.Auth · MMCA.Common/Source/Core/MMCA.Common.Application/Auth/ILoginProtectionService.cs:10 · Level 3 · interface

• What it is: the application-layer contract for brute-force and rate-limit protection on authentication endpoints: lockout checks, failed-attempt increments, successful-login resets, and registration rate-limiting per IP address.

• Depends on: Result from MMCA.Common.Shared.Abstractions (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/ILoginProtectionService.cs:1).

• Concept introduced: rate limiting as a first-class application concern. [Rubric §11, Security] assesses brute-force protection on auth flows, and [Rubric §12, Performance & Scalability] assesses whether such a policy is extracted to a port so the application layer can reason about it without coupling to a specific store (the doc comment at :7-8 names both a distributed and an in-memory cache as valid backers). Returning Result from CheckLockoutAsync (:18) and CheckRegistrationRateLimitAsync (:42) makes "account is locked out" a normal control-flow branch rather than a thrown exception.

• Walkthrough: five async methods in two scopes.

  • Email-scoped (failed-login lockout): CheckLockoutAsync (:18) returns a failure result when the email is currently locked; IncrementFailedAttemptsAsync (:26) records a failure and, per the doc comment (:20-22), applies exponential-backoff lockout once the maximum is exceeded; ResetFailedAttemptsAsync (:33) clears the counter after a successful login.
  • IP-scoped (registration flood): CheckRegistrationRateLimitAsync (:42) and IncrementRegistrationCountAsync (:49) throttle account creation per client IP. Both accept a nullable ipAddress and skip the check when it is null, so a host that cannot resolve the caller IP degrades to no limit rather than blocking everyone; CheckRegistrationRateLimitAsync returns Result.Success() in that case (doc comment, :36-37).

  All five take a CancellationToken with a default argument, per convention.

• Why it's built this way: keeping the protection policy behind an interface lets the shared authentication workflow compose it in while the concrete cache mechanics stay in the implementation; the null-IP skip keeps the limiter from becoming an availability hazard (ADR-029).

• Where it's used: injected into AuthenticationServiceBase<TUser> (constructor parameter at MMCA.Common/Source/Core/MMCA.Common.Application/Auth/AuthenticationServiceBase.cs:67), which calls all five across its login and registration flows: CheckLockoutAsync (:131), IncrementFailedAttemptsAsync on both the unknown-email and wrong-password branches (:146, :161), ResetFailedAttemptsAsync on success (:178), CheckRegistrationRateLimitAsync (:197) and IncrementRegistrationCountAsync (:256). The concrete, cache-backed LoginProtectionService (tuned by LoginProtectionSettings, bound at MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:154-157) implements it, and the framework registers that pairing at :135.

IPasswordResetTokenService

MMCA.Common.Application · MMCA.Common.Application.Auth · MMCA.Common/Source/Core/MMCA.Common.Application/Auth/IPasswordResetTokenService.cs:10 · Level 3 · interface

• What it is: the two-method port behind the forgot-password workflow: issue a single-use reset token for an email address, and validate-then-consume a token presented back by the user. Implementations keep the token material outside the database, hashed at rest, and enforce both the per-email request throttle and the per-token validation-attempt cap (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/IPasswordResetTokenService.cs:5-9).

• Depends on: Result and its generic form from MMCA.Common.Shared.Abstractions (:1), plus the UserIdentifierType alias. Its Infrastructure adapter is PasswordResetTokenService, backed by ICacheService and tuned by PasswordResetSettings.

• Concept introduced: a single-use credential without a schema change. [Rubric §11, Security] assesses how a secondary credential is minted, stored, and retired; [Rubric §8, Data Architecture] assesses whether short-lived state earns a place in the durable store. A reset token is not durable data: it is valid for minutes and must stop working the instant it is redeemed. Putting it in columns on the user row costs a migration in every consumer and needs a sweeper to reap expired rows, because expiry is not something a table enforces; a self-contained signed payload needs no store but then cannot be single-use, since a signed token that has not expired stays valid however many times it is presented. This port takes the third path and hides the choice: the handlers see two Result-returning methods, and the cache substrate is entirely the implementation's business (ADR-091).

  The second teaching point is in the return shapes. ValidateAndConsumeAsync is documented to collapse unknown, expired, mismatched, and attempt-capped into one generic failure (:32-35), so the redeem endpoint cannot be used to distinguish a wrong token from an expired one from an address that was never issued a token. The issue path is throttled rather than refused loudly, for the same anti-enumeration reason the forgot-password handler answers success to every input.

• Walkthrough: two members.

  • Task<Result<string>> IssueAsync(string email, UserIdentifierType userId, CancellationToken cancellationToken = default) (:23) returns the raw token to email, or a failure when the per-email request throttle has been exceeded. The doc comment (:12-15) states the replace semantics: issuing overwrites any token already outstanding for that address, so requesting a new link immediately stops the older one from working. The userId parameter is what the token resolves back to at redeem time, which is why the redeem call never has to trust an identifier supplied by the caller.
  • Task<Result<UserIdentifierType>> ValidateAndConsumeAsync(string email, string token, CancellationToken cancellationToken = default) (:36) validates the presented token against the outstanding record and consumes it on success, so a token never redeems twice (:25-28), returning the account the token belongs to.

• Why it's built this way: taking email on both methods, rather than treating the token as self-describing, is what lets the implementation key its records by address and enforce the per-address throttle and the one-active-token rule at the same key. Returning Result<UserIdentifierType> rather than a boolean means the redeem handler gets the account identity from the token store itself. See PasswordResetTokenService for the mechanics the port hides: a 32-byte random token (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Auth/PasswordResetTokenService.cs:39), only its digest stored, an attempt counter, and an address normalized through Email before it becomes a cache key (:34-45) so User@x.com and user@x.com cannot hold independent tokens for one account.

• Where it's used: injected into the shared ForgotPasswordHandlerBase<TUser, TCommand> (constructor parameter at MMCA.Common/Source/Core/MMCA.Common.Application/Users/UseCases/ForgotPassword/ForgotPasswordHandlerBase.cs:38, called at :72, where a throttled issue is logged and still answered as success) and into ResetPasswordHandlerBase<TUser, TCommand> (MMCA.Common/Source/Core/MMCA.Common.Application/Users/UseCases/ResetPassword/ResetPasswordHandlerBase.cs:44, redeemed at :61-62). Both apps' sealed subclasses take the same dependency, for example ADC's ForgotPasswordHandler and ResetPasswordHandler. The framework registers the concrete as scoped at MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:164.

IRoleAdministrationService

MMCA.Common.Application · MMCA.Common.Application.Auth.Administration · MMCA.Common/Source/Core/MMCA.Common.Application/Auth/Administration/IRoleAdministrationService.cs:29 · Level 3 · interface

• What it is: the application-layer contract for a role-permission administration screen: list every role with its compiled and stored permissions, read one role, read the closed catalog of roles and permissions an editor may pick from, and replace one role's stored permissions (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/Administration/IRoleAdministrationService.cs:29-77).
• Depends on: RolePermissionsResponse and PermissionCatalogResponse (both in MMCA.Common.Application.Auth.Administration), and Result and its generic form.
• Concept introduced: an editor's writable set is a strict subset of its readable catalog. [Rubric §11, Security] assesses whether an administrative surface can grant more than it should. The remarks on GetCatalogAsync (:311-315) state that the permission list it returns is the compiled catalog, so an editor built from that response can never submit anything SetStoredPermissionsAsync would refuse as unknown, and the parameter doc on SetStoredPermissionsAsync (:324-328) adds the one hard exclusion: no submitted list may include AdministrationPermissions.ManageRoles, so a role editor can never grant a role the permission to edit roles.
• Walkthrough: four methods.
  • ListRolesAsync(CancellationToken cancellationToken = default) (:297) returns one RolePermissionsResponse per known role, ordered by role name.
  • GetRoleAsync(string role, CancellationToken cancellationToken = default) (:305) reads one role's compiled and stored permissions, matched case-insensitively, or a not-found failure.
  • GetCatalogAsync(CancellationToken cancellationToken = default) (:318) returns the two closed sets, roles and permissions, an editor renders from, both sorted ordinally.
  • SetStoredPermissionsAsync(string role, IReadOnlyList<string> permissions, string? changedBy = null, CancellationToken cancellationToken = default) (:332-336) replaces a role's stored permissions and invalidates the cached snapshot, recording an optional changedBy principal name on the rows it creates.
• Why it's built this way: separating the compiled catalog (GetCatalogAsync) from the writable operation (SetStoredPermissionsAsync), and stating the ManageRoles exclusion as a contract obligation rather than leaving it to each implementation, keeps every host's role editor equally safe against granting itself the permission that edits roles.
• Where it's used: implemented by StoredPermissionRoleAdministrationService (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Auth/Administration/StoredPermissionRoleAdministrationService.cs); consumed by RolesAdminControllerBase (MMCA.Common/Source/Presentation/MMCA.Common.API/Controllers/Administration/RolesAdminControllerBase.cs) and, through it, by each app's admin roles controller, for example MMCA.ADC/Source/Modules/Identity/MMCA.ADC.Identity.API/Controllers/AdminRolesController.cs; registered through MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs.

IUserAdministrationService<TUserDto>

MMCA.Common.Application · MMCA.Common.Application.Auth.Administration · MMCA.Common/Source/Core/MMCA.Common.Application/Auth/Administration/IUserAdministrationService.cs:24 · Level 3 · interface

• What it is: the application-layer contract for an account administration screen: list accounts paged and filtered, read one account, lock or unlock an account, and replace an account's roles (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/Administration/IUserAdministrationService.cs:24-70).
• Depends on: UserAdministrationQuery (the list filter), PagedCollectionResult<TUserDto>, the UserIdentifierType alias, and Result and its generic form. Generic over TUserDto, the app's shape for one row of the admin account list.
• Concept introduced: locking an account is a workflow, not a flag flip. [Rubric §11, Security] assesses whether an administrative action actually removes access rather than merely marking it removed. The remarks on SetLockedAsync (:380-384) state the obligation directly: an implementation that locks an account should also revoke its live refresh sessions, or the lock only takes effect once the current access token expires, and name IRefreshSessionStore and RefreshSessionRevocation's RevokeAllAsync as what the framework's own credential-rotation paths use for exactly that.
• Walkthrough: four methods.
  • ListAsync(UserAdministrationQuery query, CancellationToken cancellationToken = default) (:365-367) returns one page of TUserDto, with pagination metadata.
  • GetAsync(UserIdentifierType userId, CancellationToken cancellationToken = default) (:375) reads one account, or a not-found failure.
  • SetLockedAsync(UserIdentifierType userId, bool locked, CancellationToken cancellationToken = default) (:390) locks or unlocks an account.
  • SetRolesAsync(UserIdentifierType userId, IReadOnlyList<string> roles, CancellationToken cancellationToken = default) (:399-402) replaces the complete set of roles an account holds.
• Why it's built this way: generic over TUserDto so each app's admin list can carry app-specific columns without the framework knowing about them, while the lock/unlock contract's remarks pin the one security-relevant behavior (session revocation on lock) as a documented obligation rather than leaving it to whichever app implements the interface first.
• Where it's used: consumed by UsersAdminControllerBase (MMCA.Common/Source/Presentation/MMCA.Common.API/Controllers/Administration/UsersAdminControllerBase.cs); implemented by each app's UserAdministrationService, for example MMCA.ADC/Source/Modules/Identity/MMCA.ADC.Identity.Application/Users/Administration/UserAdministrationService.cs, and registered through MMCA.ADC/Source/Modules/Identity/MMCA.ADC.Identity.Application/DependencyInjection.cs.

SoftDeletedUserCache

MMCA.Common.Application · MMCA.Common.Application.Auth · MMCA.Common/Source/Core/MMCA.Common.Application/Auth/SoftDeletedUserCache.cs:17 · Level 4 · class (static)

• What it is: the shared cache contract for the soft-deleted user marker (BR-133): the key shape, the marker lifetime, and a one-call helper that writes it. The API middleware reads the marker on every authenticated request; the module that soft-deletes a user writes it (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/SoftDeletedUserCache.cs:6-9).

• Depends on: ICacheService from MMCA.Common.Application.Interfaces (:2), the UserIdentifierType alias, and System.Globalization.CultureInfo (BCL, :1).

• Concept introduced: revoking a stateless credential without a per-request lookup. [Rubric §11, Security] assesses whether a revoked principal actually loses access, and [Rubric §12, Performance & Scalability] assesses whether such a concern is factored so both ends share one definition. A JWT is a bearer credential: signature validation never asks "is this account still active?", so soft-deleting a user leaves an already-issued access token passing validation until it expires (ADR-047). The textbook fixes (a deny-list, or an account-status query on every request) reintroduce exactly the per-request state that stateless JWT was chosen to avoid. This type is the middle path: a short-lived cache marker written at deletion time and read cheaply on the hot path.

  The remarks (:11-16) explain why the constants live in the Application layer rather than next to the middleware that reads them: a downstream application deleting an account has to write the exact same key the middleware reads, and a private constant in the presentation layer is unreachable from an application-layer command handler. Same reasoning as IdempotencyHeaders, applied one layer up.

• Walkthrough: three static members, no state.

  • MarkerDuration => TimeSpan.FromMinutes(15) (:32). The remarks (:22-31) justify the number rather than leaving it magic: the marker must outlive every access token issued before the delete. A host that does not run Identity registers no validator query, so the marker is the only thing rejecting a deleted user's still-valid token there; if it expired first, that token would be served again until it lapsed. It therefore lasts as long as the default 15-minute access-token lifetime (the BR-205 default on ITokenService). It is a constant rather than a read of the JWT settings because the marker is written through this static helper, where those settings are not reachable, so a host that raises the access-token lifetime should write its own marker with a matching duration. Only positive markers are written (:30).
  • KeyFor(UserIdentifierType userId) (:45-46) builds user:deleted:{userId} through string.Create(CultureInfo.InvariantCulture, ...). The remarks (:39-44) name the bug this prevents: an identifier renders differently under some cultures (digit shapes, group separators), so a culture-sensitive key would be written under one request's culture and missed under another, silently letting a deleted user keep making requests. This is a case where the analyzer rule about culture-invariant formatting is guarding a security property, not just a formatting nicety.
  • MarkDeletedAsync(ICacheService cache, UserIdentifierType userId, CancellationToken cancellationToken = default) (:56-64) null-guards the cache (:61) and writes true under KeyFor(userId) for MarkerDuration (:63). It returns the task without awaiting, so there is no extra async state machine for a one-call passthrough.

• Why it's built this way: publishing the key shape and the TTL as framework API is what keeps the writer and the reader honest, and it is a precondition for the module boundary in ADR-047: Identity owns the delete, every service hosts the middleware, and the only thing they share is a cache entry rather than a database. [Rubric §7, Microservices Readiness] applies directly: an extracted service can enforce the revocation without a reference to the Identity database.

• Where it's used: read by SoftDeletedUserMiddleware, which builds the key (MMCA.Common/Source/Presentation/MMCA.Common.API/Middleware/SoftDeletedUserMiddleware.cs:82), reads it from the shared store rather than the replica's local copy (:88-93), short-circuits with 401 when the marker is true on every host, Identity-hosting or not (:105-112), and on a miss falls back to the validator query when one is registered (:114-122, :139-141). Only a deleted answer is cached, for MarkerDuration (:152-161): a live answer is never cached (:133-135), because every replica keeps its own local copy and a cached live answer would outlive a delete made on another. Written by the shared delete workflow itself, ahead of either app's post-commit tail: DeleteUserHandlerBase.HandleAsync calls SoftDeletedUserCache.MarkDeletedAsync right after the erasure commits (MMCA.Common/Source/Core/MMCA.Common.Application/Users/UseCases/DeleteUser/DeleteUserHandlerBase.cs:146-148) and swallows a cache fault (:150-153) so a failed marker cannot turn a successful erasure into an error the caller would retry.

• Caveats / not-in-source: the marker is best effort on both ends by design. The middleware fails open on a cache outage, falling through to the validator query (:95-103) and proceeding if that is also unavailable (:143-149), and the writer logs and continues on a cache fault. The exposure that leaves is bounded by the access-token lifetime, which is the trade-off ADR-047 accepts explicitly. Both ADC's and Store's DeleteUserHandler derive from DeleteUserHandlerBase<User, DeleteUserCommand> (MMCA.ADC/Source/Modules/Identity/MMCA.ADC.Identity.Application/Users/UseCases/DeleteUser/DeleteUserHandler.cs:35, MMCA.Store/Source/Modules/Identity/MMCA.Store.Identity.Application/Users/UseCases/DeleteUser/DeleteUserHandler.cs:29), so both write the marker through the base.

IRefreshSessionStore

MMCA.Common.Application · MMCA.Common.Application.Auth · MMCA.Common/Source/Core/MMCA.Common.Application/Auth/IRefreshSessionStore.cs:22 · Level 5 · interface

• What it is: persistence for RefreshSession rows, the multi-device replacement for the single plaintext refresh-token column a user aggregate used to carry (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/IRefreshSessionStore.cs:5-7). Sessions are added, looked up by token hash or by id, listed per user, rotated, and saved.

• Depends on: RefreshSession from MMCA.Common.Domain.Auth (:1) and the UserIdentifierType alias. The shipped implementation is EFRefreshSessionStore; the test double is InMemoryRefreshSessionStore (MMCA.Common/Source/Hosting/MMCA.Common.Testing/Support/InMemoryRefreshSessionStore.cs:27).

• Concept introduced: a repository whose contract is deliberately missing an Update. [Rubric §1, SOLID] assesses interface segregation, and [Rubric §8, Data Architecture] assesses whether the persistence contract expresses the aggregate's rules. The doc comment (:8-15) explains the shape: sessions are mutated only through RefreshSession.Revoke on instances this store returned, so an implementation that tracks its entities persists a revocation with no update method at all. The requirement that makes that safe is stated as a contract obligation, not left implicit: implementations must return tracked instances from every lookup except FindByIdUntrackedAsync, which is untracked by design and for reading only, because a no-tracking read anywhere else would accept revocations and rotations and drop them silently at save time (:16-20). This is the same trap called out for composed EF queries elsewhere in the framework, promoted here to interface documentation.

  The second concept is lookup by hash, never by token (:37). The store never sees plaintext: callers hash first with RefreshSession.HashToken and search on the digest, which is what lets the table hold only digests. [Rubric §11, Security] applies directly.

• Walkthrough: seven members.

  • AddAsync(RefreshSession session, ...) (:27) stages an insert.
  • FindByTokenHashAsync(string tokenHash, ...) (:38) finds by digest including revoked and expired rows, and the comment (:29-34) marks that as load-bearing: a rotated token that comes back is found on its revoked row, which is the BR-206 reuse signal, so a store that filtered revoked rows out would report a replay as "unknown token" and never revoke the family.
  • GetUnrevokedByUserAsync(UserIdentifierType userId, ...) (:46-48) returns the user's un-revoked sessions oldest first, expired ones included since they still occupy a row, which is what makes both family revocation and cap eviction deterministic (:40-43).
  • FindByIdAsync(Guid id, UserIdentifierType userId, ...) (:60-63) takes the owner as part of the query rather than as a check the caller performs afterwards. The comment (:50-54) gives the reason: a session id is a value a client hands back, so scoping the query to the owner is what makes another account's id indistinguishable from a nonexistent one. That is an authorization decision encoded in a signature.
  • FindByIdUntrackedAsync(Guid id, ...) (:80-81) re-reads a session as the database holds it now, bypassing any tracked copy, revoked and expired rows included (:65-79). The rotation loser needs it: its tracked instance was read before the winner's conditional update and still shows the row live, so only a fresh read can say when and why the row was revoked. The instance is for reading only, so a mutation on it is never persisted. The default returns null, which the caller treats as "cannot tell" and answers with the conservative BR-206 family revocation; the shipped EF store overrides it with a no-tracking query (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Auth/EFRefreshSessionStore.cs:93-95).
  • SaveChangesAsync(...) (:86) persists staged inserts and revocations.
  • TryRotateAsync(RefreshSession presented, RefreshSession successor, DateTime revokedAt, ...) (:116) is the one exception to the no-update rule, and it ships a default interface implementation. It argument-guards both sessions (:122-123), revokes the presented session as RefreshSession.ReasonRotated linked to the successor's hash (:125), then stages and saves the successor (:130-131). The bool return is the whole point (:93-99): two requests presenting the same still-live token both read an un-revoked row, so a check-then-act rotation would mint two successors from one token and the presented row could never fire reuse detection again. Returning false tells the caller it lost the claim. The caller then re-reads the row through FindByIdUntrackedAsync to tell a sibling rotation inside the reuse grace (a 409 with nothing revoked) or a sign-out or cap eviction (that request fails alone) from a genuine replay (the family is revoked). The default body is atomic only per instance, which is all an in-memory or test store can offer; the shipped EF store replaces it with a conditional ExecuteUpdateAsync the database arbitrates (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Auth/EFRefreshSessionStore.cs:121 and :139).

• Why it's built this way: hashed-at-rest, per-device session rows are what turn refresh-token rotation into something a user can inspect and revoke per device, and what let reuse detection revoke a whole family (ADR-050, BR-205/206). Keeping the contract in Application means the workflow that uses it is independent of EF, so an extracted Identity service can bring its own store. Making rotation a claim rather than a mutation is the difference between a race that mints two live tokens and a race one side of which is answered as a replay.

• Where it's used: registered as scoped against the EF implementation at MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:172, scoped, like the unit of work it shares a DbContext with, so a login and its session insert commit together. Consumed by AuthSessionIssuer, not by AuthenticationServiceBase (injected at MMCA.Common/Source/Core/MMCA.Common.Application/Auth/Sessions/AuthSessionIssuer.cs:43) for the owner-scoped lookup behind targeted revocation (:236), the unrevoked-session reads behind family revocation and listing (:199, :496), cap eviction (:515) and the insert of a new session (:375).

AuthenticationValidators

MMCA.Common.Application · MMCA.Common.Application.Auth · MMCA.Common/Source/Core/MMCA.Common.Application/Auth/AuthenticationValidators.cs:24 · Level 5 · class (sealed)

• What it is: a tiny parameter object that bundles the three FluentValidation validators the authentication workflow needs (login, registration, refresh), plus the optional Terms of Service version registration requires, into one injectable dependency.
• Depends on: FluentValidation's IValidator<T> (NuGet, :1) over the request DTOs LoginRequest, RegisterRequest, and RefreshTokenRequest (all in MMCA.Common.Shared.Auth, :4), and, for the terms check, IOptions<LegalAcceptanceOptions> and LegalAcceptancePolicy from MMCA.Common.Application.Auth.Legal (:2-3).
• Concept introduced: the parameter object as a constructor-arity guardrail. [Rubric §1, SOLID] assesses whether a class stays a single, cohesive responsibility rather than sprawling into a god class, and [Rubric §15, Best Practices & Code Quality] assesses whether cross-cutting dependencies are grouped so a class can grow without exploding its constructor. The doc comment (:6-11) states the exact motive: collapsing three closely-related dependencies into one keeps the app's AuthenticationService below the application-service constructor-arity ceiling (a god-class analyzer guardrail) without giving up per-request validation. Because the request DTOs already live in MMCA.Common.Shared.Auth, the bundle is app-agnostic, which is why it could be hoisted out of the apps into the framework. The pressure is real rather than theoretical: even with the bundle, ADC's subclass constructor takes ten parameters (MMCA.ADC/Source/Modules/Identity/MMCA.ADC.Identity.Application/Users/AuthenticationService.cs:51-57).
• Walkthrough: a primary constructor takes the three IValidator<T> instances plus an optional IOptions<LegalAcceptanceOptions>? legalAcceptance = null (:24-28), and three get-only properties surface the validators by name: Login (:31), Register (:34), and Refresh (:37), each assigned from its matching constructor parameter. The fourth member, CurrentTermsVersion (:43), returns LegalAcceptancePolicy.ResolveCurrentVersion(legalAcceptance?.Value): the Terms of Service version registration requires, or null when acceptance is not configured. The doc comment (:18-22) gives the motive: the terms check is a registration rule, so carrying the options here keeps the opt-in from adding a constructor dependency to AuthenticationServiceBase or to the app's subclass. Beyond that one resolver call the type has no logic.
• Why it's built this way: a sealed grouping type with get-only properties is the cheapest way to fold three cohesive dependencies into one constructor slot, so the workflow base can validate each request shape without pushing its constructor over the arity limit; DI resolves the three underlying validators and composes them into this one object. Two of the three (LoginRequestValidator, RefreshTokenRequestValidator) come from the framework assembly, while IValidator<RegisterRequest> is satisfied by the app's own RegisterRequestValidator, so the bundle is the point where framework and app validation meet.
• Where it's used: injected into AuthenticationServiceBase<TUser> (constructor parameter at MMCA.Common/Source/Core/MMCA.Common.Application/Auth/AuthenticationServiceBase.cs:68), whose LoginAsync, RegisterAsync, and RefreshTokenAsync call validators.Login (:129), validators.Register (:227), and validators.Refresh (:315) respectively before doing any work, and which re-exposes CurrentTermsVersion as a protected property (:120) that RegisterAsync tests (:236). It is registered by each app's Identity module rather than by the framework, since one of its dependencies is app-owned: MMCA.ADC/Source/Modules/Identity/MMCA.ADC.Identity.Application/DependencyInjection.cs:37 and MMCA.Store/Source/Modules/Identity/MMCA.Store.Identity.Application/DependencyInjection.cs:46, both TryAddScoped<AuthenticationValidators>(). The options themselves are bound by the opt-in AddLegalAcceptance(configuration) (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.Auth.cs:104-110).

IAuthenticationService

MMCA.Common.Application · MMCA.Common.Application.Auth · MMCA.Common/Source/Core/MMCA.Common.Application/Auth/IAuthenticationService.cs:12 · Level 5 · interface

• What it is: the application-layer contract for the Identity module's authentication workflows: login, registration, token refresh, per-device and global session revocation, session listing, and external (OAuth) login.

• Depends on: LoginRequest, RefreshTokenRequest, RegisterRequest, AuthenticationResponse, RefreshSessionSummaryResponse, Result, Error, and the UserIdentifierType alias (:1-2).

• Concept introduced: default interface methods for optional capabilities. [Rubric §1, SOLID] (interface segregation and dependency inversion): ExternalLoginAsync (:131-139) ships a default implementation in the interface itself that returns a not-supported Error ("Auth.ExternalLoginNotSupported", :139). An implementation that does not offer OAuth (a stub host, or a deployment with social login disabled) inherits that failure for free and need not override anything, so the interface stays one piece while the capability is opt-in (ADR-036). [Rubric §11, Security]: login, registration, and refresh all return Result<AuthenticationResponse>, so auth outcomes flow as values and no exception leaks credential detail to the caller.

  The second concept the signatures teach is that a session is a device, not a user. LoginAsync, RegisterAsync and RefreshTokenAsync all take optional ipAddress and userAgent (:24-25, :32-33, :47-48) recorded on the session row, and the doc comments state the invariant each time: signing in opens a session for the calling device and leaves the user's other devices signed in (:14-15), and refreshing rotates the presenting device's session only (:43-44).

• Walkthrough: eight methods, all async, all ending in a CancellationToken.

  • LoginAsync(LoginRequest, string? ipAddress = null, string? userAgent = null, ...) returns Result<AuthenticationResponse> (:23-27).
  • RegisterAsync(RegisterRequest, string? ipAddress = null, string? userAgent = null, ...) (:37-41); the ipAddress does double duty, feeding ILoginProtectionService's registration rate limit and the new session row (:32).
  • RefreshTokenAsync(RefreshTokenRequest, ...) (:52-56) exchanges an expired access token plus a valid refresh token for a rotated pair.
  • RevokeTokenAsync(UserIdentifierType userId, string? refreshToken = null, ...) (:67-70) signs one device out. The documented fallback is the interesting part (:58-60): passing no token, or one that does not belong to this user, revokes every session the user holds, which the comment calls the safe reading of "log me out" from a caller that cannot produce its refresh token.
  • RevokeAllSessionsAsync(UserIdentifierType userId, ...) (:79-81) signs every device out: a password change, an admin lockout, or an explicit "sign out everywhere".
  • GetSessionsAsync(UserIdentifierType userId, Guid? currentSessionId = null, ...) (:96-99) lists live sessions newest first with the caller's own device marked. currentSessionId is the caller token's sid claim and is used only to set RefreshSessionSummaryResponse.IsCurrent; passing null marks no row (:88-91).
  • RevokeSessionByIdAsync(UserIdentifierType userId, Guid sessionId, ...) (:115-118) revokes one named device. The remarks (:104-110) fix two behaviors as contract: an unknown id and another account's id both return NotFound and are indistinguishable, so a caller cannot probe for another user's sessions; and revoking an already-revoked session changes nothing and also returns NotFound with the code Auth.SessionAlreadyRevoked (:107-109), so a device list can tell the user the device was already signed out instead of claiming this request signed it out.
  • ExternalLoginAsync(loginProvider, providerKey, email, firstName, lastName, ...) (:131-139), the default-implemented OAuth path.

  The doc comment (:6-9) also records a scope decision: password change is not on this interface. It is dispatched directly through its own command handler at the controller layer.

• Why it's built this way: concentrating the token-issuing and session-management workflows behind one port keeps the Identity controllers thin and lets the protection and rate-limit policy (ILoginProtectionService) compose in; the default OAuth method keeps the contract stable across hosts that do and do not enable social login. Encoding the anti-probing and idempotent-revoke rules in remarks rather than leaving them to an implementation makes them testable expectations of every implementer.

• Where it's used: implemented by AuthenticationServiceBase<TUser> (which realises every member except the default ExternalLoginAsync) and, through it, by each app's sealed AuthenticationService; consumed by the Identity API controllers.

RefreshSessionRevocation

MMCA.Common.Application · MMCA.Common.Application.Auth · MMCA.Common/Source/Core/MMCA.Common.Application/Auth/RefreshSessionRevocation.cs:17 · Level 5 · class (internal static)

• What it is: a single shared helper, RevokeAllAsync, that revokes every un-revoked refresh session a user holds. Used wherever a credential-rotation path needs to make sure a stale token cannot keep authenticating after the event that should have invalidated it.
• Depends on: IRefreshSessionStore (nullable: a host that never registered one, because refresh sessions are opt-in, is a no-op), RefreshSession (.Revoke, RefreshSession.ReasonSignedOut), and the BCL TimeProvider.
• Concept introduced: a credential-rotation event is a call site, not a feature flag. [Rubric §11, Security] assesses whether changing a credential actually invalidates the sessions issued under the old one. Because refresh sessions are opt-in (RefreshSessionSettings.Enabled), a change-password or reset-password handler cannot assume a store exists; the doc comment states this directly (:426-428), and refreshSessions is null (:439-442) is checked first so the call degrades to a no-op rather than throwing, meaning the same handler code runs unchanged on a host that never enabled the feature.
• Walkthrough: one static method, RevokeAllAsync(IRefreshSessionStore? refreshSessions, TimeProvider? timeProvider, UserIdentifierType userId, CancellationToken cancellationToken) (:433-437). It returns immediately on a null store (:439-442) or an empty session list (:446-449), otherwise stamps now from the supplied timeProvider or TimeProvider.System (:444), calls session.Revoke(now, RefreshSession.ReasonSignedOut) on every un-revoked session in a loop (:451-454), and saves once (:456).
• Why it's built this way: internal static with no instance state keeps the helper a one-line call from any handler that needs it, and centralizing the null-store check here means every caller gets the same opt-in-safe behavior instead of re-deriving it.
• Where it's used: the documented mechanism behind IUserAdministrationService<TUserDto>'s SetLockedAsync obligation (see that type); also ChangePasswordHandlerBase (MMCA.Common/Source/Core/MMCA.Common.Application/Users/UseCases/ChangePassword/ChangePasswordHandlerBase.cs) and ResetPasswordHandlerBase (MMCA.Common/Source/Core/MMCA.Common.Application/Users/UseCases/ResetPassword/ResetPasswordHandlerBase.cs).

AuthenticationServiceBase<TUser>

MMCA.Common.Application · MMCA.Common.Application.Auth · MMCA.Common/Source/Core/MMCA.Common.Application/Auth/AuthenticationServiceBase.cs:64 · Level 8 · class (abstract)

• What it is: the shared authentication workflow (login, registration, refresh-token rotation, per-device and global revocation, session listing) hoisted once into the framework, generic over the app's User aggregate. It realises IAuthenticationService and leaves the genuinely app-specific decisions to a small set of abstract and virtual hooks a sealed subclass overrides.

• Depends on: IUnitOfWork and IRepository<TEntity, TIdentifierType> (persistence, G07), IPasswordHasher, ILoginProtectionService, AuthenticationValidators and IAuthSessionIssuer (the five required constructor parameters, :64-68), and two optional ones: an ITwoFactorAuthenticator? and IOptions<EmailConfirmationSettings>? (:69-70, both default null so a subclass that adopts neither passes nothing), the IAuthUser credential contract plus AuditableAggregateRootEntity<TIdentifierType> as the TUser constraint (:71) and, where a host adopts confirmation, IEmailConfirmableUser (matched in CheckEmailConfirmed), ITokenService (reached only through the issuer's TokenService property, MMCA.Common/Source/Core/MMCA.Common.Application/Auth/Sessions/IAuthSessionIssuer.cs:34), TwoFactorOutcome, TwoFactorErrors and AuthClaimTypes (the mfa claim values), Email (normalizing the login and register address), ClaimsPrincipalExtensions (principal.GetUserId() and principal.FindMultiFactorMethod()), Result and Error, and the request and response DTOs. The base itself takes no session store, no session settings and no clock (:63-70): those belong to the issuer.

• Concept introduced: the Template Method that de-duplicates a whole vertical slice. [Rubric §2, Design Patterns] assesses idiomatic pattern use: this is a textbook Template Method, the invariant sequence of an operation living in the base while the variable steps are deferred to subclass hooks. [Rubric §15, Best Practices & Code Quality] (DRY across services) and [Rubric §1, SOLID] also apply: the doc comment (:19-23) records that the app Identity modules previously duplicated this workflow at roughly 70 to 95 percent line-identity, so a fix to the lockout order or the rotation logic is written once. [Rubric §11, Security]: the base encodes the security posture directly, validate first, an ILoginProtectionService lockout and rate-limit gate (ADR-029), an untracked-then-tracked dual fetch (ADR-004), and, through IAuthSessionIssuer, refresh-token rotation with reuse detection (ADR-050, BR-205/206). [Rubric §7, Microservices Readiness]: the workflow depends only on ports, so it runs unchanged whether the Identity module is in-monolith or its own service.

  The division of labour is the other concept to absorb before reading the code (:39-44): this class decides who is signed in, and IAuthSessionIssuer decides what they are handed. Once a caller is proved, the multi-device refresh sessions (hashed at rest), BR-205 rotation with BR-206 reuse detection, the per-user session cap, and the sid and mfa claims on the minted access token are the issuer's job, so this workflow never touches a RefreshSession row. Every session-shaped member below is a single delegation to the issuer; the reuse, replay, expiry and cap rules are taught on AuthSessionIssuer.

• Walkthrough (members in teaching order):

  • Constructor and protected accessors (:64-71): a primary constructor takes the five required collaborators plus the two optional ones. A protected CurrentTermsVersion (:120) forwards validators.CurrentTermsVersion, so adopting Terms of Service acceptance adds no constructor dependency here or in the app's subclass; when it is non-null, RegisterAsync has already refused a request whose AcceptedTerms is false (:236, returning LegalAcceptanceErrors.TermsNotAccepted) before CreateUser runs, so a CreateUser override stamps that version on the new user (doc comment :105-119). An external-login path that creates users outside RegisterAsync leaves them unstamped, and the UI's acceptance gate asks them on first sign-in. A private _multiFactorMethod field (:83) is the base's own arming state for the second-factor claim, a plain field because the service is scoped and one request issues one token pair (remarks, :79-82); it is handed to the issuer at mint time. Protected read-only properties re-expose UnitOfWork (:86), TokenService (:98), which returns sessionIssuer.TokenService, the issuer's stamping instance, so minting through it is what puts sid on the token (remarks, :88-97), and a Repository resolved lazily as unitOfWork.GetRepository<TUser, UserIdentifierType>() (:101-102). Token lifetimes and the session cap are not members of this class: they are configuration read by the issuer.

  • LoginAsync (:105-200): validate the request, check lockout (ADR-029 and BR-212), normalize the raw email into an Email value object so the EF predicate compares same-typed converted values (an invalid address yields a null value object that simply matches no user, which is the invalid-credentials answer anyway). Step 1 is an untracked fetch via the FindUntrackedByEmailAsync hook to verify credentials without change-tracker overhead. The null check now also calls HasStoredCredential(untracked) (:135, private helper at :581-582): an account with no stored password material, the shape an external-OAuth account carries (ADR-036), can never be reached by password login, and both branches answer the identical generic 401 with the identical BurnPasswordVerificationCost(request.Password) call (:137, private helper at :589-599) so the two cases cost the same time and are indistinguishable to a timing observer, before IncrementFailedAttemptsAsync. passwordHasher.VerifyPassword runs next and fails the same way on a wrong password. Only after the password check does the app gate (ValidateLoginCandidateAsync) run, deliberately reordered: reaching it now proves the caller owns the account, so its distinct status message (for example a deactivated-account rejection) is told to the account's owner rather than to anyone sweeping addresses, and running it before the password check (the old order) made account state readable with no credential at all. Two more gates follow the same rule, for the same reason: CheckEmailConfirmed(untracked) (:164, hook at :480-490), off unless the host both supplied EmailConfirmationSettings.RequireConfirmedEmail and the app's User implements IEmailConfirmableUser, and ChallengeSecondFactorCountingFailuresAsync(untracked.Id, request, cancellationToken) (:170-171, private helper at :522-535). That helper runs the overridable ChallengeSecondFactorAsync hook (:504-510), which with no ITwoFactorAuthenticator registered answers TwoFactorOutcome.NotEnrolled outright at no extra cost, and counts a TwoFactorErrors.TwoFactorInvalidCode failure against the account through IncrementFailedAttemptsAsync exactly like a wrong password, so the lockout at the top of the method throttles code guessing per account. A missing code is the ordinary first leg of the challenge and is not counted (:512-517). Step 2 is a tracked re-fetch by id, purely about the instance the app's CreateAccessToken hook mints from, and the second lookup is what turns a race that deleted the account between the two steps into a clean 404. Then ResetFailedAttemptsAsync, and _multiFactorMethod = MultiFactorMethodFor(secondFactor.Value) (:191, private helper at :543-552, mapping a verified TOTP or recovery code to the mfa claim value and any unrecognized outcome to null) arms the field in a try/finally around IssueTokensAsync so the claim lands only on this response and disarms whether or not the call throws.

  • RegisterAsync (:203-280): validate, IP rate-limit (ADR-029 and BR-213), reject a duplicate email through the EmailExistsAsync hook, hash the password, build the user through the CreateUser hook, AddAsync and SaveChangesAsync, run the OnUserRegisteredAsync post-commit hook to pick up the instance the first access token is minted from, increment the IP registration count, and open the session last: the session row carries the user id, which a store-generated key only has once the insert has run.

    The save is wrapped in a deliberately broad catch (Exception) whose comment is the teaching material. The email lookup above is a check-then-act: two concurrent registrations for the same address both pass it, and the loser only fails on the insert, against the unique index every consumer puts on Email (ADC unfiltered, Store filtered on IsDeleted). Without the catch, that race surfaces as a generic 500 instead of the 409 a serialized pair would have produced. The catch cannot name DbUpdateException, because Application has no EF Core dependency by layer rule, so the re-check is what narrows it: if the address exists now, the concurrent registration is the cause and the caller gets the same conflict the serial path returns through the shared EmailAlreadyExistsFailure() helper; anything else rethrows untouched and still reaches the exception middleware. The re-check passes CancellationToken.None on purpose: it has to run even when the caller's token is what aborted the save, or a cancelled save could never be classified.

  • RefreshTokenAsync (:283-349): validate, pull claims from the expired JWT via TokenService.GetPrincipalFromExpiredToken (:297, the issuer's instance; signature still checked, only lifetime skipped), read the identifier with principal.GetUserId() (rides the standard sub claim, also accepts the NameIdentifier form the bearer handler maps it to, and parses through IParsable so the identifier alias can change shape without editing this file), load the tracked user, run the refresh app gate, and hand the presented refresh token to sessionIssuer.RotateAsync (:337-343) together with a mint callback over CreateAccessTokenForSession. The issuer resolves the session behind the token (reuse detection included), rotates it, and answers with a token pair whose access token carries the successor's sid, a client's current-device marker following the rotation instead of pointing at the session the rotation just revoked. The step-up the user already performed is carried across the rotation too: _multiFactorMethod = principal.FindMultiFactorMethod() (:332) reads the mfa claim off the presented access token, whose signature was already validated, and arms it in a try/finally around the successor mint, the same disarm pattern as LoginAsync. Dropping it would quietly demote a signed-in session every access-token lifetime and make an IRequiresMfa use case unreachable without a fresh sign-in.

  • RevokeTokenAsync (:352-366): load the user (a NotFound when absent), then delegate to sessionIssuer.SignOutAsync(userId, refreshToken, ...) (:363). Only a live session belonging to this user identifies the device to sign out; when the token is absent or identifies no live session of this user, the issuer revokes every live session instead (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/Sessions/IAuthSessionIssuer.cs:88-97), rather than reporting success for a revocation that reached nothing.

  • RevokeAllSessionsAsync (:369-382): the unconditional form of the same thing, through sessionIssuer.SignOutEverywhereAsync (:379).

  • GetSessionsAsync (:386-394): no user lookup, so a list is one call to sessionIssuer.ListActiveAsync(userId, currentSessionId, ...) (:391) wrapped in a success. The issuer lists live sessions newest first and leaves expired-but-unrevoked rows out, since a device list must not offer a device that can no longer authenticate (IAuthSessionIssuer.cs:105-116).

  • RevokeSessionByIdAsync (:402-406): an expression-bodied delegation to sessionIssuer.RevokeSessionAsync. Ownership is checked by the issuer's store query, so another account's id and a nonexistent id produce the same NotFound; an already-revoked session writes nothing and returns NotFound with Auth.SessionAlreadyRevoked, matching the interface contract (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/IAuthenticationService.cs:107-109).

  • IssueTokensAsync (:417-431): the shared open-and-respond used by login and registration, and reusable by an app-level external-login flow. It null-guards the user and delegates to sessionIssuer.IssueAsync(user.Id, sessionId => CreateAccessTokenForSession(user, sessionId), ...) (:425-430): the access token is a callback because it carries the session's id, which exists only once the issuer has opened the session.

  • The private mechanics are login-side only. ChallengeSecondFactorCountingFailuresAsync (:522-535) is the counting wrapper described under LoginAsync. MultiFactorMethodFor (:543-552) maps an unrecognized outcome to null, so an enum that grew cannot silently mint an mfa claim. HasStoredCredential (:581-582) requires both a non-empty hash and a non-empty salt. BurnPasswordVerificationCost (:589-599) runs one throwaway VerifyPassword against a zeroed 64-byte hash and 32-byte salt, skipping a blank password, so a branch that never reaches the real check still pays the key-derivation cost. EmailAlreadyExistsFailure() (:606-608) is the 409 shared by the up-front check and the race recovery so the two paths are indistinguishable to a caller. Session resolution, rotation, family revocation and the cap are private to AuthSessionIssuer.

  • The hooks: four are abstract, so a subclass must supply them. FindUntrackedByEmailAsync (:438) and EmailExistsAsync (:444) are deliberately written against the app's concrete User so EF translates the predicate byte-for-byte as before, and the second explicitly leaves the app to decide whether soft-deleted accounts count (ignoreQueryFilters: true blocks re-registration of an erased address); CreateUser (:447) runs the app's domain factory; CreateAccessToken (:450) mints the app's claim set (for example speaker_id versus customer_id). Seven virtual members can be overridden: CreateAccessTokenForSession (:469-470) calls sessionIssuer.MintForSession(sessionId, _multiFactorMethod, () => CreateAccessToken(user)), so the issuer arms its stamping token service for the duration of the app hook and sid (plus mfa when this request verified a second factor) is appended to whatever claim set the app passes, which is what keeps the claims additive with no change to CreateAccessToken's signature (remarks, :456-465); CheckEmailConfirmed (:480-490) is the email-confirmation sign-in gate, off unless the host supplied EmailConfirmationSettings.RequireConfirmedEmail and the app's User implements IEmailConfirmableUser; ChallengeSecondFactorAsync (:504-510) runs the second-factor challenge and, with no ITwoFactorAuthenticator injected, answers TwoFactorOutcome.NotEnrolled with no extra query, which is what keeps the feature free for an app that has not adopted it; ValidateLoginCandidateAsync (:555) and ValidateRefreshCandidateAsync (:559) add extra gates such as a deactivated-account check; OnUserRegisteredAsync (:566) runs the post-commit side-effect; and CreateRefreshUserMissingError (:574) defaults the vanished-user case to 401 (a token for a missing user is indistinguishable from an invalid one) while letting an app return 404 where its public contract already promises it.

• Why it's built this way: the untracked-then-tracked dual fetch keeps the common credential-verification path off the change tracker (cheaper, and soft-deleted accounts fall out via EF query filters returning the generic 401) while still giving a tracked instance to mint from (ADR-004). Per-device session rows with hashed tokens, rotation, family revocation on reuse, and a per-user cap are the BR-205/206 model (ADR-050), and keeping them behind IAuthSessionIssuer gives the sign-in decision and the session mechanics one owner each (:39-44). Password material flows through IAuthUser's PasswordHash and PasswordSalt (ADR-032), and the whole workflow depends only on abstractions, so it is identical whether the module runs in-process or as an extracted service.

• Where it's used: subclassed by each app's sealed AuthenticationService, for example MMCA.ADC/Source/Modules/Identity/MMCA.ADC.Identity.Application/Users/AuthenticationService.cs:50, which binds TUser = User, adds the Attendee default role (BR-45) and the speaker_id claim (BR-209, built at :381-384), passes the injected IAuthSessionIssuer through to the base (:56, :63), and re-lists IAuthenticationService (:66) so it can re-implement RegisterAsync and ExternalLoginAsync outright: ADC raises its registration side-effects inside one transactional unit rather than through the OnUserRegisteredAsync hook, because the identity column means the id does not exist until the first save (AuthenticationService.cs:30-42). MMCA.Store supplies its own subclass with a customer_id claim. Consumed by the Identity API controllers via the IAuthenticationService port.

• Caveats / not-in-source: ExternalLoginAsync is intentionally not overridden here: the base inherits the interface's default not-supported failure, and OAuth account linking stays in the app subclass because it is coupled to the app's User factory surface (doc comment, :37-38).

IssuedSession

MMCA.Common.Application · MMCA.Common.Application.Auth.Sessions · MMCA.Common/Source/Core/MMCA.Common.Application/Auth/Sessions/AuthSessionIssuer.cs:532 · Level 0 · record (private sealed, nested)

• What it is: the two-field result of opening or rotating a refresh session: the plaintext refresh token the client is handed, and the id of the session row it belongs to. It is a private sealed record nested inside AuthSessionIssuer (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/Sessions/AuthSessionIssuer.cs:532), not part of the framework's public surface.
• Depends on: nothing beyond the BCL (string, Guid). It is produced and consumed entirely inside its declaring class.
• Concept introduced: the plaintext token exists in exactly one place, and it is a return value. [Rubric §11, Security] assesses how a bearer credential is stored. RefreshSession rows keep only a digest (RefreshSession.HashToken, used at AuthSessionIssuer.cs:157 and :285 to look up by hash), so once a session is persisted the raw token cannot be recovered from the store at all. The type comment says exactly this (AuthSessionIssuer.cs:527-531): the plaintext "exists nowhere else, since the store keeps only its hash". Modelling the hand-off as a small record rather than an out-parameter or a tuple is what keeps that fact readable: both methods that can produce a token return Result<IssuedSession>, so the compiler shows you the complete list of places raw token material is in flight. [Rubric §15, Best Practices & Code Quality] also applies: a positional record gives value equality and immutability for free, and Guid SessionId names what would otherwise be an anonymous second tuple element.
• Walkthrough: one positional declaration, IssuedSession(string RefreshToken, Guid SessionId) (AuthSessionIssuer.cs:532). RefreshToken is what goes back to the caller in the AuthenticationResponse; SessionId is what the access token's sid claim carries, which is why the session must be opened before the token is minted (the comment at AuthSessionIssuer.cs:75-76).
• Why it's built this way: the pairing is load-bearing rather than incidental. A caller that received only the token could not stamp sid, and a caller that received only the id could not answer the client. Returning both together removes the ordering mistake where a token is minted for a session that does not exist yet.
• Where it's used: returned by OpenSessionAsync (AuthSessionIssuer.cs:352, constructed at :337) and RotateSessionAsync (:350, constructed at :390); unwrapped by IssueAsync (:84-85) and by RotateAsync (:120-121), each of which passes SessionId to the caller's mintAccessToken callback and puts RefreshToken into the response.

EmailConfirmationSettings

MMCA.Common.Application · MMCA.Common.Application.Auth.EmailConfirmation · MMCA.Common/Source/Core/MMCA.Common.Application/Auth/EmailConfirmation/EmailConfirmationSettings.cs:10 · Level 0 · class

• What it is: the options class bound to the Authentication:EmailConfirmation configuration section (EmailConfirmationSettings.cs:28), controlling token lifetime, throttling, and whether an unconfirmed address blocks sign-in.
• Depends on: nothing first-party; System.ComponentModel.DataAnnotations ([Range]) and System.Diagnostics.CodeAnalysis ([SuppressMessage]) validate the bound values.
• Concept introduced: the config-bound settings-class shape (a SectionName constant plus init-only, range-validated properties with sane defaults) is the same one the sibling PasswordResetSettings uses elsewhere in this group; see it there for the general pattern rather than re-teaching it here. [Rubric §11, Security] (assesses whether authentication-adjacent behavior is safely configurable): every numeric knob here is range-constrained (EmailConfirmationSettings.cs:43,50,54,58), so a bad value in configuration fails validation instead of silently disabling throttling.
• Walkthrough: ConfirmationUrl (EmailConfirmationSettings.cs:40) defaults to empty rather than being [Required], deliberately, per its own doc comment (EmailConfirmationSettings.cs:30-34): an unconfigured host still boots and degrades to a token-only, paste-in-by-hand flow. TokenLifetimeMinutes (line 44) defaults to 1440 (one day). MaxValidationAttempts (line 51) caps wrong-token guesses at 5 before the record is discarded. MaxRequestsPerEmail (line 55) and RequestWindowMinutes (line 59) throttle re-issuance per address. RequireConfirmedEmail (line 70) defaults to false.
• Why it's built this way: the RequireConfirmedEmail default is called out as load-bearing in its own remarks (EmailConfirmationSettings.cs:49-54): turning it on locks out every account whose address was never confirmed, so a host backfills existing rows as confirmed before flipping it, and with it off the whole feature is additive. This is the opt-in shape recorded in ADR-116.
• Where it's used: read by AuthenticationServiceBase and EmailConfirmationTokenService (MMCA.Common/Source/Core/MMCA.Common.Application/Auth/AuthenticationServiceBase.cs, MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Auth/EmailConfirmationTokenService.cs) and registered in MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs; ADC binds it via MMCA.ADC.Identity.Application/Users/AuthenticationServiceSettings.cs and consumes it in SendEmailConfirmationHandler.

IPermissionGrantCache

MMCA.Common.Application · MMCA.Common.Application.Auth.Permissions · MMCA.Common/Source/Core/MMCA.Common.Application/Auth/Permissions/IPermissionGrantCache.cs:21 · Level 0 · interface