Audit #67 remediation: milestones 1–5 (#68–#82)

CLAUDE.md

@@ -230,6 +230,7 @@ until it was dissolved on 2026-09-04.
 | [`docs/work/mvp/2026-09-04-open-items-dissolution.md`](docs/work/mvp/2026-09-04-open-items-dissolution.md) | **Archive of record, not a register.** The dissolved open-items register, moved here whole on 2026-09-04 with every open question in it decided. Nothing is appended to it; its item IDs stay reserved and still resolve, because they are cited from source. | no — archive |
 | `docs/first-release.md` | **Live.** Release-readiness: what the release path already does, and the blockers that must clear before a first publish. Was the `NFR-16` row of the dissolved deferral register. | yes |
 | `docs/deviations.md` | **Register.** The as-built audit of §10, and where a deviation found outside a phase lands. | yes |
+| `docs/audit-67-decisions.md` | **Ledger.** Decisions taken during the audit #67 remediation run, and the release-machinery work it deferred. | yes |
 | `docs/assets/` | Vendored wordmark SVGs the root `README.md` renders. | yes |
 
 **Frozen means a maintenance tool refuses to write there**, not merely that you should not. The

docs/README.md

@@ -16,6 +16,7 @@ is the index; the rule is that nothing in `docs/` is unowned, and nothing is wri
 | [the dissolved open-items register](./work/mvp/2026-09-04-open-items-dissolution.md) | **Archive of record.** Everything the register held when it was dissolved on 2026-09-04, with every open question in it decided. Item IDs stay reserved and still resolve | — | No — nothing is appended |
 | [`first-release.md`](./first-release.md) | Release readiness: what the release path already does, the confirmed mechanics, and the blockers that must clear before a first publish. Was the `NFR-16` row of `deferred-items.md`, which was dissolved on 2026-09-04 — its five still-live rows are archived under *Live deferrals* in [`work/mvp/2026-09-04-register-retirement-purge.md`](./work/mvp/2026-09-04-register-retirement-purge.md) | The maintainer | Yes — edited as blockers clear |
 | [`deviations.md`](./deviations.md) | The as-built audit of §10, and the landing point for a deviation found outside a phase | An audit or review | Yes — appends |
+| [`audit-67-decisions.md`](./audit-67-decisions.md) | Decision ledger for the audit #67 remediation run: cross-task decisions, rejected alternatives, and the release-machinery work deferred from it | The remediation supervisor | Yes — appends |
 | [`assets/`](./assets/) | Vendored wordmark SVGs the root `README.md` renders | Copied from `dexpace/morphic` | Yes |
 
 ## Frozen means frozen

docs/sdk-documentation/auth.md

@@ -16,8 +16,12 @@ interface AuthTiers {
 
 The most specific tier that is set wins (`AUTH-4`). `perCall` comes from
 `RequestOptions.newBuilder().auth(descriptor)`, which is how one call opts out of, or into, something
-different from the client default. Only the *selection* is tiered; whether a selected requirement can
-be satisfied at all is `AUTH-6`, and failing it is an `AuthResolutionError`.
+different from the client default. **`operation` comes from `RequestOptions.operationAuth`**, set with
+`RequestOptions.newBuilder().operationAuth(descriptor)` — both per-call slots ride on the same
+`RequestOptions`, and the AUTH pillar step reads them into the two tiers
+(`packages/core/src/auth/auth-step.ts:252,756`; `packages/core/src/auth/resolve.ts:19` names the mapping). `client` is the
+configured default. Only the *selection* is tiered; whether a selected requirement can be satisfied at
+all is `AUTH-6`, and failing it is an `AuthResolutionError`.
 
 An `AuthDescriptor` is a list of `AuthRequirement`s, each a scheme plus optional scopes and
 parameters. Both are built by factory, never as an object literal:
@@ -39,8 +43,8 @@ The factories validate and freeze (`AUTH-3`). A descriptor containing a `NO_AUTH
 ```typescript
 interface AuthCredentialSet {
   readonly bearer?: {provider: TokenProvider; marginMs?: number};
-  readonly basic?: {username: string; password: string};
-  readonly digest?: {username: string; password: string; algorithmPreference?: DigestAlgorithm[]};
+  readonly basic?: BasicCredential;
+  readonly digest?: DigestCredential;
   readonly apiKey?: {credential: ApiKeyCredential | NameKeyCredential; headerName?: string; prefix?: string};
 }
 ```
@@ -49,18 +53,37 @@ The five schemes are `OAUTH2`, `API_KEY`, `BASIC`, `DIGEST` and `NO_AUTH`. A req
 scheme; the credential set supplies the material for it. A requirement with no matching credential is
 an `AuthResolutionError` at send time, not a silent unauthenticated request.
 
-**`ApiKeyCredential`, `NameKeyCredential` and `BearerToken` are nominal, not structural.** Each carries
-a `#private` field, so no caller-side object literal is assignable to them and the validation in each
-factory cannot be routed around. They also override `toString()` and Node's inspect symbol, so a
-credential cannot leak into a log line or a stack trace by accident.
+**Every credential type is nominal, not structural.** `ApiKeyCredential`, `NameKeyCredential`,
+`BearerToken`, `BasicCredential` and `DigestCredential` each carry a `#private` field, so no
+caller-side object literal is assignable to them and the validation behind each cannot be routed
+around. All five override `toString()` and Node's inspect symbol, so a credential cannot leak into a
+log line or a stack trace by accident.
 
 ```typescript
-import {ApiKeyCredential, createBearerToken} from '@dexpace/core';
+import {
+  ApiKeyCredential,
+  BasicCredential,
+  createBearerToken,
+  DigestCredential,
+} from '@dexpace/core';
+
+const credentials = {
+  basic: new BasicCredential('alice', 'super-secret'),
+  digest: new DigestCredential('bob', 'super-secret', ['SHA-256', 'MD5']),
+  apiKey: {credential: new ApiKeyCredential('super-secret'), headerName: 'X-Api-Key'},
+};
 
 String(new ApiKeyCredential('super-secret')); // 'ApiKeyCredential{key=***}'
 String(createBearerToken('t', 1)); // 'BearerToken{token=***, expiresAt=1}' — the expiry survives
+String(credentials.basic); // 'BasicCredential{username=alice, password=***}'
 ```
 
+There is no `password` property to read back, by design: `BasicCredential` and `DigestCredential`
+shipped as plain `{username, password}` records until 2026-09-04, and a plain property is reachable
+through `credential['password']`, `Object.keys`, `JSON.stringify` and a default `util.inspect` — so
+`util.inspect(credentials)` printed the password in clear beside `ApiKeyCredential{key=***}`. The
+username and the Digest algorithm preference stay visible; `AUTH-8` permits non-secret fields to.
+
 The inspect symbol matters as much as `toString`: `console.log(credential)` and `util.inspect` do not
 route an object argument through `toString`, so both are overridden (`AUTH-8`).
 
@@ -102,6 +125,14 @@ request is dispatched (`AUTH-28`). There is no option to disable it. `NO_AUTH` n
 is why an auth-less `standardResilience()` installs a `NO_AUTH`-only step rather than no step at all —
 the pillar slot stays filled and the behaviour stays uniform.
 
+**Once guarded, always guarded.** A `challengeHook` may return any request it likes, including one
+whose URL has been downgraded to `http://`. When the outbound pass ran the guard, the replay is
+guarded too — unconditionally, without inspecting a single header name, because
+`ApiKeyCredentialConfig.headerName` lets this step stamp a header no fixed list would contain. On a
+`NO_AUTH` hop, which is never guarded outbound, a replacement carrying `Authorization` or
+`Proxy-Authorization` still trips the guard. A genuinely credential-free re-issue over `http://` is
+what `XCUT-16` explicitly permits, and it still proceeds.
+
 ## Challenges
 
 ```typescript
@@ -130,6 +161,23 @@ when the deferral register was dissolved on 2026-09-04).
 **Basic and Digest never stamp preemptively.** They react to a challenge. That is an interpretation of
 `§11` rather than a stated requirement, and it is ledgered as one.
 
+**Every challenge the response offered is considered, not just the first.** A server may send
+`WWW-Authenticate` (or `Proxy-Authenticate`) once with several comma-separated challenges, or once per
+challenge — RFC 9110 §5.3 permits both, and RFC 7616 §3.3 recommends the repeated form for Digest
+algorithm discovery. Which of the two shapes reaches the step is partly the transport's accident:
+`@dexpace/transport-fetch` comma-joins repeated values because WHATWG `Headers` does,
+`@dexpace/transport-undici` keeps them apart. The step reads *every* value and parses each on its own,
+so the offer is the same list either way, and `@dexpace/transport-conformance` carries a row asserting
+that. A challenge the SDK cannot answer — an unsupported algorithm, an `auth-int`-only `qop`, a realm
+this client cannot echo back, an empty `realm` or `nonce` — is declined and the next one is tried; a
+`401` offering nothing answerable surfaces unchanged and unclosed.
+
+**Digest `-sess` sends `cnonce` whether or not `qop` was negotiated.** `MD5-sess` and `SHA-256-sess`
+fold the client nonce into HA1 (RFC 7616 §3.4.2), so a server handed a `-sess` response without one
+cannot verify it. `nc` and `qop` stay conditional on a negotiated `qop`. `AUTH-22`'s literal wording
+says all three are conditional; the departure is a row in
+[`deviations.md`](../deviations.md).
+
 ## Redirects and credentials
 
 Credentials are attached at an origin and must not follow a request to a different one. The redirect

docs/sdk-documentation/errors.md

@@ -112,6 +112,11 @@ export async function call(): Promise<void> {
 the two apart at the point of abort — which is exactly how a transport decides which of the two
 errors to raise.
 
+**Neither narrowing changes when a retry pillar is installed.** What `retryStep` throws once it gives
+up is the final attempt's own error, unwrapped, so the two `instanceof` checks above read the same at
+`maxAttempts: 1` and at `maxAttempts: 3`. The earlier attempts ride beside it and are read with
+`retryAttempts(error)` — see [`pipelines.md`](./pipelines.md#the-four-shipped-pillars).
+
 ## Narrowing helpers
 
 Three predicates exist for the cases where `instanceof` on a union is tedious:
@@ -162,12 +167,30 @@ Eight classes that a `@throws` tag named but no package exported were promoted t
 | `CursorAlreadyAdvancedError` | a step reusing an already-invoked `next()`/`fork()` continuation |
 | `EndOfStreamError` | a `BufferedSource` read that required more bytes than the source delivered |
 
+**The two redirect errors carry redacted messages and raw properties, and the split is deliberate.**
+`SchemeDowngradeError.message` and `NonReplayableBodyError.message` name their URLs in the redacted
+form `OBS-11`/`OBS-12` define — userinfo as `***:***@`, every non-allow-listed query value as `***` —
+because a message is rendered by every logger, every `cause` chain and every consumer `console.error`,
+and `http.redirect.rejected` hands the error straight to `LogEvent.cause()`. The unredacted URLs stay
+on `fromUrl` / `toUrl` / `targetUrl`, which is where program code reads them:
+
+```ts
+try {
+  await client.send(request);
+} catch (error) {
+  if (error instanceof SchemeDowngradeError) {
+    console.error(error.message); // https://***:***@api.example.com/v1?token=***
+    retargetTo(error.toUrl); //     the real URL, for code rather than for a log
+  }
+}
+```
+
 Two more joined them on the same date, both from `XCUT-8`'s "never fabricate a successful exception":
 
 | Error | Raised by |
 |---|---|
 | `HttpStatusValidationError` | `new HttpStatusError(status, …)` when `status` is not an integer in 400–599. The constructor validated nothing before, so a consumer could build an `HttpStatusError` claiming a `200`. `toHttpError` is the total form — it returns `null` instead of throwing |
-| `RetryDiscardedResponseError` | the retry engine's suppressed trail, for a response it discarded whose status is outside 400–599. Reachable only if you widen `RetrySettings.retryableStatuses` to include a non-error code; the trail previously said `HttpStatusError` for it, which claimed an HTTP failure that had not happened |
+| `RetryDiscardedResponseError` | the retry engine's prior-attempt trail (`retryAttempts()`), for a response it discarded whose status is outside 400–599. Reachable only if you widen `RetrySettings.retryableStatuses` to include a non-error code; the trail previously said `HttpStatusError` for it, which claimed an HTTP failure that had not happened |
 
 All of them descend from `DexpaceError`, so the broad catch works too.
 

docs/sdk-documentation/http.md

@@ -110,8 +110,9 @@ const options = RequestOptions.newBuilder()
 `RequestOptions.EMPTY` is the shared no-op instance. A step reads it as `ctx.options`, and a
 transport receives it as `send()`'s second argument. Both range checks are the **full** range, not
 only the lower bound: `maxRetries` rejects anything that is not a non-negative integer, and
-`timeoutMs` rejects zero, negatives, `Infinity` and `NaN` alike (`HTTP-35`). A fractional
-`timeoutMs` is accepted — a timeout is a duration, not a count.
+`timeoutMs` rejects zero, negatives, `Infinity`, `NaN`, a fractional value and anything above
+`2**32 - 1` (`HTTP-35`) — the range is `AbortSignal.timeout()`'s, the only one a transport can
+honor.
 
 `auth` on the builder is the **per-call** auth tier, the highest-precedence one; see
 [`auth.md`](./auth.md).