Phase 6c: authentication — the authentication layer

[Wahbeh-Mohammad]

Part of #24. First PR of phase 6c's three-PR stack — the code. Its tests are the next PR up and the phase record the one after. Cut from main at f1fe848 (phase 5 complete); phase 6a (#22, PRs #72–#74) was built in parallel off the same base — whichever merges second gets the rebase-and-reprove pass (this one, by the maintainer's order: 6a first).

What lands

The authentication layer in dexpace-core — 59 files, +3,266 / −15 — AUTH-1–AUTH-38, all 38 implemented, no ⏳ row: the only sub-phase of phase 6 with none.

• Dexpace::Auth::Scheme (closed at five, .new and .[] private, #with refusing, Scheme::ALL), Requirement (scopes owned — a caller's scopes[0] << ":write" cannot reach the stored value), Descriptor, and the pure Resolver over the three tiers with Dexpace::AuthResolutionError (flat, error/).
• Four credential types with variant-specific equality and redaction — #to_s, #inspect and #pretty_print (pp walks a Data's members and never calls #inspect; P6-72, a new corpus note); PasswordCredential redacts the username too (P6-73); key credentials compare by identity.
• Challenges.parse — an RFC 7235 StringScanner state machine, no regexp over the grammar, eight timeout-compiled frozen patterns; the top-level comma and token68 padding handled; recovery from an unterminated quote and a stray comma; an invalidly encoded value scanned as BINARY (P6-74).
• BasicHandler — ["u:p"].pack("m0") over the UTF-8-transcoded pair, never Base64; a colon in the username refused (P6-75). DigestHandler — MD5 / MD5-sess / SHA-256 / SHA-256-sess with the expectations derived from RFC 2617 §3.5's and RFC 7616 §3.9.1's inputs (the RFC's printed SHA-256 response is 63 hex characters and cannot be one); the per-nonce counter in the handler's own BoundedMap (bare name from the full-nesting body; DEFAULT_CAP 1024; nc wrapping at 32 bits, restarting per nonce, counted after the raising step); cnonce from ::SecureRandom; a non-ASCII username sent as RFC 7616 §3.4 username* because HTTP-18's outbound grammar refuses the raw form (P6-76); AUTH-21's ISO-8859-1 branch a typed UnencodableCredentialError naming the field and the encoding, raised cause: nil so no rendering names a byte of the secret (P6-84/85).
• ChallengeHandlerChain, KeyStamper (the header value grammar-checked at construction), BearerProvider (.fetch_async, .conforms?, P6-81), BearerStamper (lock-free hot path by publication, the fetch under the credential's mutex — XCUT-12's one sanctioned lock across a fetch — single-flight, AUTH-35's rejections raising ProviderError and caching nothing, exact-match eviction), AsyncBearerStamper (AUTH-37's three zones from one clock reading, a background refresh through Future#on_settle never awaited, each waiter settled from the single-flight slot through its own Completer so one caller's cancel detaches that waiter alone — P6-86; a failed refresh logged as Events::AUTH_REFRESH, P6-77).
• Auth::Step at Stages::AUTH — .build(stamper:, challenge_hook: NO_REPLACEMENT, logger: Logger::NULL), .new private, frozen, no redactor: (P6-71): the cross-origin marker read from cursor.state(Stages::REDIRECT) first (AUTH-29 — the reader half of the contract 6b writes; the shared frozen empty hash is the same-origin case), the HTTPS guard second (HTTPSRequiredError before any fetch), a fork for every drive, the 401 re-challenge replayed exactly once through a fresh fork with the superseded 401 closed before the replay, AUTH-31's gate a private Step#replayable? (P6-80), AUTH-36's evict-if-matches-then-re-stamp. AsyncStep < Step — the same keywords, one Completer frame, a hook that may answer a Future (P6-78), every inner future observed with cancellation forwarded both ways (P6-79), a provider error a failed future never a raise (AUTH-38).
• BoundedMap#update(key) { |old| new } — the one earlier-phase widening 4a anticipated, read-yield-write under the map's own mutex; Events::AUTH_REFRESH — the ninth event in 5b's vocabulary.
• The round-4 repair (P6-87): a fetched token whose Bearer <token> wire form the outbound header grammar refuses is AUTH-35's fourth rejection on both stampers — nothing cached, the waiter fails with a ProviderError that never names the token, the next call refetches — so a token read from a file with its newline can no longer poison every later request until expiry.
• sig/ mirrors lib/ one file per file (auth/validation.rb's with hooks.rbs's comment; _BearerProvider/_AsyncBearerProvider declared; no Digest/SecureRandom type in any signature — NFR-11); the manifest regenerated once from 956 to 1060 rows. Three earlier-phase test pins the code invalidated ride this branch: dexpace_test.rb's layer table, seam_surface_test.rb's plain-require list (digest joins), 5b's keys_test.rb event count.

Decisions taken in the open, against the plan's text

Ledger rows P6-71–P6-87 and the checklist's "Deviations from the plan" (35 items). The plan was written against phase 4/5 designs and one interpreter; the load-bearing corrections: Dexpace::Error is a module, Headers#[] returns a list, Request::Builder#header appends (stampers set), a root Cursor.build cannot fork (every drive test through a real pipeline), no redactor: keyword (P5-95), Future#then exists, the three Auth:: errors under lib/dexpace/auth/, bounded_map.rb given a true test mirror.

Layering

Each tip of the stack is green under every gate on its own tree. This branch is green on the SimpleCov floor too — 92.43% on 4.0.6 (92.36% on 3.2.11; 2,051 runs, 0 failures). The tests PR takes the same tree to 99.98%.

Verification

• Independent review, five rounds by five fresh reviewers with a fix round between each: round 0 0 blocking / 1 should-fix / 4 nits; round 1 0 / 3 / 2; round 2 0 / 3 / 2; round 3 0 / 1 / 1 (the four-review cap — the open should-fix was the poisoned-cache defect, so one targeted fix round followed by the maintainer's decision); round 4 0 / 1 / 0. No round found a red gate or a layering fault.
• All seventeen gates individually at this tip on 4.0.6; the matrix set on 3.2.11; honest RuboCop (--ignore-parent-exclusion) 426 files clean.
• Mutations: 58, 58, 46, 43 and 37 applied by the five reviewers on both interpreters; every one caught at the final tip except R4-1's three (below).
• By experiment, both interpreters: Basic and the four Digest algorithms against the derived vectors; the parser on the fixtures and a 100 KB value; the nonce store's cap, per-nonce restart and sixteen-thread determinism; the step against 4c's ForkingProbe at REDIRECT with the marker set, unset and absent, the HTTPS guard before any fetch, the 401 replay through one fresh fork with the close ordered before it; the bearer hot path lock-free under a raising mutex, sixteen threads coalescing on one fetch, the three zones on a FakeClock, a cancelled waiter detaching alone; every credential's renderings and every error's #cause/full_message free of the secret; the round-3 poisoned-cache reproduction now refetching at the stamper and through an AsyncStep pipeline.

Known follow-ups from the final review (not blocking a gate)

• R4-1 (should-fix, tests) — bearer_stamper_test.rb:95: the sync BearerStamper's AUTH-35 rejections are pinned from a cold cache only; a rejection on the refresh path (a warm cache inside the margin) is exercised by no suite, so a validate-skipped-on-refresh mutation survives. A warm-cache rejection case on the tests PR closes it; the code is correct as built.
• R3-2 (nit) — two 73-character body lines in the round-2 docs commit (a12c758).
• Findings routed: three spellings of the body-replayability predicate after phase 6 (6a's Resend.eligible?, 6b's Resend.replayable_body?, this private Step#replayable?) → phase 10's inbound list; SequencedTransport beside 6a's ScriptedTransport → reconciled after both lanes land; the end-to-end cross-origin test (test/dexpace/auth/cross_origin_convergence_test.rb, guarded) → 6b un-guards it.