@o3co/auth-provider-foundation 0.15.0 → 0.17.0-rc.1

package/README.md

@@ -1,97 +1,237 @@
 # @o3co/auth-provider-foundation
 
-Production HTTP user-authentication adapter for auth.provider. Registers the `"http"` adapter type into a `UserRepository` factory, which delegates `authenticate` / `authenticateByToken` to an upstream HTTP service.
-
-This package's scope is **production non-database / external-service adapters** for the v0.5.0 module system. As of v0.5.0 it ships exactly one such adapter (`HttpUserRepository`); the previous Redis `CodeRepository` adapter was relocated to [`@o3co/auth-provider-redis`](../redis/README.md) in Phase 10.
+Last updated: 2026-10-03
+
+The HTTP client of "the Store" — the deployment's own user service — for
+auth.provider. `HttpUserRepository` implements core's `UserRepository` port over
+HTTPS: it authenticates users, links federated identities, answers the
+identity lookup federation grants ask for, and writes the MFA enrollment
+witness. `registerBuiltinAdapters` registers
+it as the `"http"` user adapter. The package also fixes the contract of the
+Store's MFA endpoints — where a Store keeps a subject's second factors and the
+enrollment witness — with the configuration section that names them and what
+their failures throw; `HttpMfaFactorStore` implements core's `MfaFactorStore`
+over the factor endpoints, and `foundationMfaFactorStoreModule` installs it.
+
+## Responsibility
+
+**Role.** An adapter for two core ports:
+[`UserRepository`](../core/src/repositories/UserRepository.mts) (see
+[`core/src/repositories`](../core/src/repositories/README.md)), and, where
+the Store keeps a deployment's MFA factors,
+[`MfaFactorStore`](../core/src/mfa/factorStore.mts). Despite the
+package name it is not a base layer: no other package imports it at runtime
+(`federation-grants` uses it in a test). A composition root selects it —
+`adapters.userRepository = "http"` in the standalone template.
+
+**Owns:**
+
+- the wire contract a Store implements: the requests `HttpUserRepository` sends
+  and what each answer means (below);
+- the transport rules on the Store's URLs — `https`, or `http` to a loopback
+  host only ([`src/endpointUrl.mts`](src/endpointUrl.mts)) — and that no
+  request follows a redirect away from them;
+- the credential it presents to the Store (`bearerToken`), the floor that
+  credential is held to, and how the Store's refusal of it reads;
+- that nothing a transport reports — which may quote the request — is thrown;
+- the request deadline and the response-size cap;
+- the coverage declaration the identity lookup is judged by at boot;
+- the contract of the Store's MFA endpoints: what each is sent, what each
+  answer means, and that nothing the Store sends reaches a client when a call
+  fails ([below](#the-stores-mfa-endpoints)); the `foundation-mfa-factor-store`
+  section that names the factor endpoints; and `MfaStoreError`, what their
+  failures throw;
+- `HttpMfaFactorStore`, the Store-backed `MfaFactorStore`, and the
+  `foundation-mfa-factor-store` module that installs it
+  ([below](#the-store-backed-factor-store)).
+
+**Does not own:** the port and the `User` shape (core); the MFA ports and the
+JSON bodies of the MFA endpoints (core's
+[`mfa/storeWire.mts`](../core/src/mfa/storeWire.mts), which a Store's own
+implementation and the test kit's fake Store read too); when a user is
+authenticated, an identity linked or an owner looked up — the session routes
+([`@o3co/auth-provider-session`](../session/README.md)), `oauth`'s jwt-bearer
+grant ([`@o3co/auth-provider-oauth`](../oauth/README.md)) and federation grants
+([`@o3co/auth-provider-federation-grants`](../federation-grants/README.md)); the
+Store itself; core's development user adapters (`yaml` / `static`); Redis-backed
+stores ([`@o3co/auth-provider-redis`](../redis/README.md), which also holds the
+Redis authorization-code store).
+
+**Why a separate package.** Core ships only development user adapters, read from
+a file; a production deployment keeps its users in a service of its own, and
+this is the client for one. It is the replaceable piece — a deployment with its
+own `UserRepository` implementation does not install it — and it depends on
+core alone among the packages, with the global `fetch` and `zod` for its
+section's schema.
 
 ## Install
 
 ```sh
-npm install @o3co/auth-provider-foundation
-# Peer dependency (required):
-npm install @o3co/auth-provider-core
+npm install @o3co/auth-provider-foundation @o3co/auth-provider-core
 ```
 
-## Public API
-
-### `registerBuiltinAdapters`
+Peer dependency: `@o3co/auth-provider-core`. Its one dependency of its own is
+`zod`, for the schema of its configuration section.
 
-Registers the `"http"` adapter type into the provided `userFactory`.
+## Usage
 
 ```typescript
-function registerBuiltinAdapters(factories: {
-  userFactory: AdapterFactory<UserRepository>;
-}): void;
-```
-
-For Redis-backed code storage, register the builder from `@o3co/auth-provider-redis` directly:
-
-```typescript
-import { redisCodeRepositoryBuilder } from "@o3co/auth-provider-redis";
-codeFactory.register("redis", redisCodeRepositoryBuilder);
-```
+import { createRepositoryFactories } from "@o3co/auth-provider-core";
+import { registerBuiltinAdapters } from "@o3co/auth-provider-foundation";
 
-### `HttpUserRepository`
+const { userFactory } = createRepositoryFactories();
 
-A `UserRepository` implementation that delegates authentication to an upstream HTTP service.
+registerBuiltinAdapters({ userFactory });
 
-```typescript
-class HttpUserRepository implements UserRepository {
-  constructor(options: {
-    authenticateUrl: string;        // POST endpoint for username/password auth
-    authenticateByTokenUrl: string; // POST endpoint for token-based auth
-    linkFederatedIdentityUrl?: string; // POST endpoint that links a federated identity (#482)
-    findSubjectByFederatedIdentityUrl?: string; // POST endpoint that says who holds an upstream identity (#613)
-    federatedIdentityLookupCoverage?: FederatedIdentityLookupCoverage[]; // what that lookup covers (#613)
-    timeout: number;                // request timeout in milliseconds
-    maxResponseBytes?: number;      // response body cap, default 1 MiB
-  });
-
-  // POST authenticateUrl with body: { email, password }
-  authenticate(username: string, password: string): Promise<User | null>;
-
-  // POST authenticateByTokenUrl with body: { token }
-  authenticateByToken(token: string): Promise<User | null>;
-
-  // POST linkFederatedIdentityUrl with body: { userId, provider, sub, token, claims }
-  // — present only when the URL is configured (#482)
-  linkFederatedIdentity?(userId: string, identity: FederatedIdentityLink): Promise<LinkFederatedIdentityResult>;
-
-  // From the coverage declaration alone; the Store is not asked (#613).
-  // Present together with the lookup, only when its URL is configured.
-  supportsFederatedIdentityLookup?(registration: { provider, issuer, clientId }, identityClaims: string[]): boolean;
-
-  // POST findSubjectByFederatedIdentityUrl with body: { provider, issuer, clientId, sub, claims }
-  findSubjectByFederatedIdentity?(identity: FederatedIdentityLookup): Promise<FederatedIdentityLookupResult>;
-}
+// Create an HTTP user repository via the factory
+const userRepo = await userFactory.create({
+  type: "http",
+  authenticateUrl: "https://users.example.com/authenticate",
+  authenticateByTokenUrl: "https://users.example.com/authenticate-by-token",
+  timeout: 5000,
+});
 ```
 
-For `authenticate` and `authenticateByToken`:
-
-- Returns `null` on HTTP 401 or 403.
-- Throws an error on any other non-OK HTTP status.
-- Throws when the upstream returns 2xx with a body that is not a JSON `User`
-  (`{ id: string, username: string, … }`) — an upstream failure, not a
-  "user not found".
-- `linkFederatedIdentity` (#482): a `2xx` `User` is `{ ok: true, user }`;
-  `401` / `403` is `{ ok: false, reason: "refused" }`; `409` is
-  `{ ok: false, reason: "conflict" }`; anything else throws. The method is
-  absent when `linkFederatedIdentityUrl` is not configured, which is how the
-  federation routes know to refuse `?link=1` up front. What a Store checks
-  before answering `2xx` — never on an unverified or relay address, never by
-  e-mail alone — is in the
-  [session package README](../session/README.md#account-linking-across-federations-482).
+`registerBuiltinAdapters` ([`src/index.mts`](src/index.mts)) registers the
+`"http"` type on a `UserRepository` factory; the builder reads the keys below,
+defaults `timeout` to 5000 ms and `maxResponseBytes` to
+`DEFAULT_MAX_RESPONSE_BYTES` (1 MiB) when absent, and accepts numbers given as
+strings (an environment override). `HttpUserRepository`
+([`src/repositories/HttpUserRepository.mts`](src/repositories/HttpUserRepository.mts))
+can also be constructed directly with the same options; there `timeout` is
+required, since the 5000 ms default is the builder's.
+
+### Configuration
+
+Under `repositories.user.http`, the standalone template's `repositories`
+section, read when `adapters.userRepository = "http"` (`ADAPTERS_USER_REPOSITORY`);
+defaults are in [the template's `reference.conf`](../../templates/standalone/config/reference.conf):
+
+| Key | Env | |
+| --- | --- | --- |
+| `authenticateUrl` | `REPOSITORIES_USER_HTTP_AUTHENTICATE_URL` | Required. Password login. |
+| `authenticateByTokenUrl` | `REPOSITORIES_USER_HTTP_AUTHENTICATE_BY_TOKEN_URL` | Required. Resolves an opaque handle: federated login, the jwt-bearer grant. |
+| `linkFederatedIdentityUrl` | `REPOSITORIES_USER_HTTP_LINK_FEDERATED_IDENTITY_URL` | Optional. Enables account linking. |
+| `findSubjectByFederatedIdentityUrl` | `REPOSITORIES_USER_HTTP_FIND_SUBJECT_BY_FEDERATED_IDENTITY_URL` | Optional. The identity lookup. |
+| `federatedIdentityLookupCoverage` | — (a list; HOCON only) | What the lookup covers. Default `[]`. |
+| `markMfaEnrolledUrl` | `REPOSITORIES_USER_HTTP_MARK_MFA_ENROLLED_URL` | Optional. Writes the MFA enrollment witness ([below](#the-witness-written-through-the-user-repository)). No default. |
+| `bearerToken` | `REPOSITORIES_USER_HTTP_BEARER_TOKEN` | Optional. Sent on every request as `Authorization: Bearer <token>`; at least 32 bytes of key material. Unset, no `Authorization` header is sent. See [who may call the Store](#what-the-store-must-enforce-itself). |
+| `timeout` | `REPOSITORIES_USER_HTTP_TIMEOUT` | Milliseconds. Default 5000. |
+| `maxResponseBytes` | `REPOSITORIES_USER_HTTP_MAX_RESPONSE_BYTES` | Default 1048576. |
+
+## The wire contract
+
+Every request is a `POST` with a JSON body, and — when `bearerToken` is
+configured — an `Authorization: Bearer <token>` header. The user a Store
+answers with is core's [`User`](../core/src/repositories/types.mts).
+
+**`authenticate`** posts `{ email, password }` to `authenticateUrl` (the
+username arrives as `email`); **`authenticateByToken`** posts `{ token }` to
+`authenticateByTokenUrl`, where `token` is an opaque handle the Store resolves
+to a user — `<provider>:<sub>` from the federation callback, the verified
+assertion's subject handle from `oauth`'s jwt-bearer grant. For both:
+
+- a `2xx` whose body is a JSON `User` (`{ id: string, username: string, … }`,
+  both non-empty) is the user;
+- `401` or `403` is `null` — no such user, or wrong credentials;
+- a `2xx` with a body that is not a `User` throws — an upstream failure, not a
+  "user not found". An empty `id` or `username` is not a `User`: an empty `id`
+  names nobody, and OpenID Connect Core §2 requires the `sub` it becomes to be
+  a locally unique identifier. For a user without a username, the Store sends
+  a stable label as `username`, such as the e-mail address. The session routes
+  and the jwt-bearer grant answer the throw `503 temporarily_unavailable`, as
+  they answer any Store failure (the table under
+  [What the Store must enforce itself](#what-the-store-must-enforce-itself)
+  names each line they log);
+- any other status throws.
+
+**The MFA enrollment witness on both reads.** A Store that keeps the witness
+(the MFA ADR's D12) MUST answer `User.mfaEnrolled` on `authenticate` and on
+`authenticateByToken` alike: a boolean, left out until the subject is first
+marked. A federated login records the witness from `authenticateByToken`'s
+`User`, so a Store that answers it on `authenticate` alone leaves federated
+sessions without the defence the witness gives. The adapter hands
+`mfaEnrolled` through as the Store answered it, and core reads it
+(`readMfaEnrollmentWitness`): any value other than `true`, `false` or absent
+is malformed, which the MFA package answers `503` and never a first binding.
+The test kit's witness suite holds a Store to both reads.
+
+The body of a non-`2xx` answer is discarded unread, for these and for linking.
+No request follows a redirect, including the identity lookup: a `3xx` is one
+more status that throws, and its `Location` is never contacted.
+
+**A `401` or `403` with a `Bearer` challenge is a refused credential.** When
+`bearerToken` is configured, a `401` or `403` carrying
+`WWW-Authenticate: Bearer …` (RFC 6750 §3 — `invalid_token`,
+`insufficient_scope`) from any endpoint it posts to throws a
+`StoreCredentialRefusedError`, `HttpUserRepository: the Store at <url> refused
+this deployment's credential (HTTP <status> with a Bearer challenge) — …`,
+instead of the reading this section otherwise gives that status: not "no such
+user", not a refused link, not the lookup's `answered HTTP <status>`. What each
+caller then answers and logs is in
+[What the Store must enforce itself](#what-the-store-must-enforce-itself). The
+challenge is found in any case, among other challenges or on a header line of
+its own, and never inside a quoted string; a quoted string left unterminated
+runs to the end of the value and hides whatever follows it, which then reads
+as no challenge. Nothing the Store wrote after the scheme is repeated. A `401`
+or `403` without a `Bearer` challenge, and any `401` or `403` when no token is
+configured, keeps the meaning this section gives it, so a Store that does not
+check the token is unaffected.
+
+**A transport failure carries nothing of the exchange.** When a request cannot
+be made or its answer cannot be read, the error is a `StoreTransportError`
+whose `reason` and message say which:
+
+| `reason` | When | Message (the lookup: `identity lookup at <url> …`) |
+| --- | --- | --- |
+| `unreachable` | no connection to exchange on: a refused connection, DNS, TLS, a route or host the network cannot reach — the network path, or TLS | `HttpUserRepository: request to <url> could not be reached` |
+| `connection_closed` | a connection closed or reset before a complete response arrived: before any byte, after an interim `1xx`, mid-head, or a pooled keep-alive connection the Store, a proxy or an idle timeout closed between two requests — the transport cannot tell which | `HttpUserRepository: the connection to <url> closed before a complete response arrived` (the lookup: `identity lookup at <url>: the connection closed …`) |
+| `malformed_response` | the Store sent a response head the transport cannot take: the parser refused the status line or a header, or the head outgrew the size limit — the Store's answer, or a proxy's | `HttpUserRepository: the Store at <url> answered with a malformed HTTP response` |
+| `unreadable` | an HTTP answer whose body broke mid-read | `HttpUserRepository: response from <url> could not be read` |
+
+Each carries at most a transport code an operator can act on, in the message
+and as `code`: `ECONNREFUSED`, `ENOTFOUND`, `ECONNRESET`, `EPROTO`, an
+`UND_ERR_*` (`UND_ERR_HEADERS_OVERFLOW`, `UND_ERR_SOCKET`, …), an `HPE_*` where
+the runtime sets one (Node 26's undici sets no code on its parser errors), an
+`ERR_SSL_*` (`ERR_SSL_WRONG_VERSION_NUMBER` is an https URL on a port that
+speaks plain HTTP; `ERR_SSL_SSL/TLS_ALERT_HANDSHAKE_FAILURE` is a TLS 1.2
+handshake the Store refused — mutual TLS it expects a client certificate for,
+or no shared cipher), a certificate code. It never
+carries the transport's own error or a `cause`: undici's parser errors quote
+the bytes they rejected, and a peer that reflects the request — a broken
+proxy, a debugging echo — puts the `Authorization` header, or a password,
+among them. A request that outlives the deadline is a `TimeoutError` instead
+(see Constructor validation).
+
+**`linkFederatedIdentity`** posts `{ userId, provider, sub, token, claims }` to
+`linkFederatedIdentityUrl`: a `2xx` `User` is `{ ok: true, user }`; `401` / `403`
+is `{ ok: false, reason: "refused" }`; `409` is
+`{ ok: false, reason: "conflict" }`; anything else throws. A `2xx` whose body
+is not a `User` throws too, although the Store has already made the link: the
+caller answers `503` and audits no link, so the Store reconciles that link on
+its side. Because the body of a
+refusal is not read, a refusal carries no description from the Store. The
+method is absent when `linkFederatedIdentityUrl` is not configured, which is
+how the federation
+routes know to refuse `?link=1` up front. What a Store checks before answering
+`2xx` — never on an unverified or relay address, never by e-mail alone — is in
+the
+[session package README](../session/README.md#account-linking-across-federations-482).
 
 #### The identity lookup (#613)
 
 What a federation-grant deployment (`@o3co/auth-provider-federation-grants`,
-D7 check 5) asks of the Store: who holds an upstream identity, so that a
+the connect callback's check 5 in the ADR's
+[D7](../core/docs/adr/2026-09-17-federation-grants-offline-delegation.md#d7--the-connect-flow-binds-its-callback-and-refuses-on-any-mismatch))
+asks of the Store: who holds an upstream identity, so that a
 delegation is refused when the account belongs to another local user. The
 Store answers about ownership across **every** registration of the IdP, not
 only the one the identity came through — a login links under the federation
 the user signed in through, and an IdP whose `sub` is pairwise per app
 registration (Entra's is) gives the same person another `sub` under each. For
-D19's separate grants registration, that means: to answer `unlinked`
+a separate registration for grants (the ADR's
+[D19](../core/docs/adr/2026-09-17-federation-grants-offline-delegation.md#d19--entra-on-behalf-of-is-not-implemented-and-consent-accumulates)),
+that means: to answer `unlinked`
 honestly, your Store must resolve the verified `(tid, oid)` against an
 authoritative directory complete for the relevant tenant and all local
 ownership links across registrations; no match in a partial directory or an
@@ -109,7 +249,10 @@ The request is `POST findSubjectByFederatedIdentityUrl` with
 
 — the registration exactly as the connection is configured, the verified
 `sub`, and every claim the connection's `identityClaims` named (verified,
-from the id_token; `{}` when it named none). The lookup must change nothing:
+from the id_token; `{}` when it named none). The Store must not log, persist
+or echo those claims — core's
+[`FederatedIdentityLookup`](../core/src/repositories/UserRepository.mts) marks
+them transient. The lookup must change nothing:
 no login stamped, no link made, no user provisioned. The answer is a `2xx`
 JSON body, one of
 
@@ -137,25 +280,451 @@ exactly (no trimming, no case folding, no trailing-slash tolerance), and
 `requiredClaims` the claim names the strategy needs — `[]` for one on the
 registration and `sub` alone. `supportsFederatedIdentityLookup(registration,
 identityClaims)` is `true` when an entry equals the registration and every
-`requiredClaims` name is among `identityClaims`; the grants module refuses at
-boot every connection it is `false` for. A registration nobody declared is
+`requiredClaims` name is among `identityClaims`. When federation grants are enabled and have at
+least one connection and `federation-grants.identityLookup` is `"required"` (the
+default), the grants module refuses at boot every connection it is `false` for;
+under `"unsupported"`, or with no connection, it asks nothing. A registration nobody declared is
 answered `registration_not_covered` locally, and a declared one arriving
 without a required claim `identity_not_resolvable`, with no request either
 way. The declaration is snapshotted at construction; a duplicate registration,
 a malformed entry, or coverage without the URL is a construction error. It has
-no environment-variable form (a list is HOCON's), as `federationGrants.connections`
-has none.
+no environment-variable form (a list is HOCON's), as `federation-grants.connections`
+has none. `supportsFederatedIdentityLookup` and `findSubjectByFederatedIdentity`
+are absent when `findSubjectByFederatedIdentityUrl` is not configured, and a
+deployment that then has a connection under `"required"` is refused at boot.
+
+## The Store's MFA endpoints
+
+A Store can keep a subject's second factors (the MFA ADR's D7) and the
+enrollment witness (D12). The provider decides and the Store persists; the
+Store never decodes, logs or derives anything from a factor's `data`, which
+the provider seals first. This package holds the contract, the section that
+names the factor endpoints and what their failures throw; `HttpUserRepository`
+sends the witness's request when `markMfaEnrolledUrl` is configured
+([below](#the-witness-written-through-the-user-repository)), and
+`HttpMfaFactorStore` the four factor endpoints'
+([below](#the-store-backed-factor-store)). The JSON bodies are core's
+[`mfa/storeWire.mts`](../core/src/mfa/storeWire.mts) (`MfaStoreFactor`,
+`MfaStoreUpdateRequest`, …), with the codec both sides use.
+
+**Every request** is a `POST` of JSON to the configured URL as it is — no path
+segment or query is added, so no subject or factor id appears in a request
+line or a Store's access log — under the user repository's rules: the same
+`bearerToken`, deadline and response cap, `https` or loopback `http`, no
+redirect followed, and a `401` or `403` with a `Bearer` challenge a refused
+credential ([the wire contract](#the-wire-contract)).
+
+**A factor record** is `{ id, subject, kind, label?, binding?, createdAtMs,
+lastUsedAtMs?, version, data }`. Times are epoch milliseconds, as numbers,
+named `…Ms`. An optional field with no value is left out: `null` is never
+"unset", and a record carrying it for any field is one the provider cannot
+read. `id` is 22 base64url characters (16 random bytes); `kind` a hint token
+(`^[a-z][a-z0-9_-]{0,63}$`); `label` 1 to 64 characters, well formed, none of
+them one that breaks or reorders a line; `binding` is `password`,
+`email_proof`, `federated` or `mfa`; `version` a safe non-negative integer; `data` a
+string kept byte for byte. A record outside that shape is one the provider
+cannot read (core's `isMfaFactorId`, `isMfaFactorKind`, `isMfaFactorLabel`).
+
+| Endpoint | Request | Answers |
+| --- | --- | --- |
+| list (`listUrl`) | `{ subject }` | `200 { factors: [record…], generation }`: every record held for the subject and the set's generation, from one snapshot; `{ factors: [], generation: null }` for an absent set. Any other status throws. |
+| create (`createUrl`), conditional | `{ factor: record, expectedGeneration, deadlineMs }` | `200 { outcome: "created", generation }`: created, the set at its new generation. `409 { outcome: "conflict" }`: nothing written. Any other status throws, a `404` included. |
+| update (`updateUrl`) | `{ subject, id, expectedVersion, changes: { data, label?, lastUsedAtMs? } }` | `200 { factor: record }`, the record as written at `expectedVersion + 1`. `409`: the version moved; `404`: the record is gone — each the port's `null`. Any other status throws. |
+| delete (`deleteUrl`), conditional | `{ subject, id, expectedGeneration, deadlineMs }` | `200 { outcome: "removed", generation }`: removed, the set at its new generation. `404 { outcome: "missing" }` and `409 { outcome: "conflict" }`: nothing written. Any other status throws. |
+| delete, the set's reset | `{ subject, all: true }` | `2xx` (`204`), or `404` when nothing was held: both done. Any other status throws. |
+| markMfaEnrolled (`markMfaEnrolledUrl`) | `{ subject, enrolled }` | `204`, the value held already included. `404`: the Store holds no such subject — an error, since the subject has just authenticated. Any other status throws. |
+
+- **An update writes its changes and nothing else.** It names the record by
+  `subject` and `id` and carries the expected version and, as its changes,
+  only `data`, `label` and `lastUsedAtMs`; one left out is cleared. `id`, `subject`, `kind`, `binding` and `createdAtMs` are
+  never sent as changes, and the Store must not change them; it refuses
+  changes carrying any other field (`400`). The Store compares and sets
+  atomically on `expectedVersion` and writes `version` one higher: two
+  updates at one version never both succeed.
+- **Every record, always.** A list answers every record the Store holds for
+  the subject, one it or the provider cannot read included, and only that
+  subject's. The provider holds a record it cannot read — a field missing, of
+  the wrong type, out of range or out of shape, or `null` — a record naming
+  another subject, and a second record with an id already listed, as present
+  and unusable: the subject's list is refused whole (core's
+  `readMfaStoreListAnswer`), never read as fewer records, so such a record
+  never lets the subject count as having none and never opens a first
+  binding. A transport failure is an outage, never an empty list.
+- **A version other than `expectedVersion + 1`** in an update's answer is an
+  outage, never a success, and one error line naming the subject and the
+  factor id.
+- **The witness** is answered back on `authenticate` and on
+  `authenticateByToken` as `User.mfaEnrolled` ([both reads](#the-wire-contract)):
+  a boolean, left out until the subject is first marked, read only through
+  core's `readMfaEnrollmentWitness`.
+- **The factors' integrity and freshness are the Store's.** A record's
+  version never goes back, and a write the Store acknowledged is never lost —
+  across a restore or a failover included. A list answers the latest write,
+  every record the subject has and no record removed. The provider cannot
+  check any of it ([what the Store must enforce itself](#what-the-store-must-enforce-itself)).
+
+**The factor set's generation.** A subject's records are one set, and the
+Store keeps one generation for its membership, under core's
+conditional-write convention for a set
+([`docs/adapter-surface.md`, "Conditional writes"](../../docs/adapter-surface.md#conditional-writes)),
+whose HTTP wire the table follows. Core's codec carries it on both sides
+(`readMfaStoreVersionedListAnswer`, `toMfaStoreCreateIfRequest`,
+`readMfaStoreCreateIfAnswer`, `toMfaStoreRemoveIfRequest`,
+`readMfaStoreRemoveIfAnswer`).
+
+- **A generation** is 1 to 128 visible ASCII characters, none of them `"`
+  (core's `isStoreGeneration`), compared only whole. The Store mints it at
+  random, a v4 UUID for one, and never issues it again for the subject: not
+  after the set is emptied and written again, a byte-identical rewrite, a
+  tombstone's expiry, or a restore or a failover that loses writes. A digest,
+  a timestamp or a counter is not one.
+- **Every membership write mints a fresh one**: a create, a removal that
+  removed, and a reset. An update keeps it.
+- **A conditional write is one atomic step**, its check and its write: in
+  SQL, one transaction that locks the set's row first, then its records'. An
+  in-process lock does not count. A reset is one atomic step too,
+  serialised with the conditional writes.
+- **A create and a removal of one record always carry `expectedGeneration`.**
+  The provider never sends either without it, and a Store may refuse one
+  that comes without it with `400`, as the convention does. `null`, on a
+  create only, means "only while the set is absent". A value that is no
+  generation, and `null` on a removal, are `400`.
+- **`conflict` and `missing` write nothing.** A create answers `conflict`
+  when the set is at another generation, absent while `expectedGeneration`
+  names one, present while it is `null`, or holding the `(subject, id)`
+  already; never `missing`. A removal answers `missing` for an absent set;
+  for a present one it checks the generation first, `conflict` at another,
+  then the record, `missing` when it is not held.
+- **An emptied set stays, as its tombstone.** A removal of the last record,
+  or a reset, leaves the set present and empty at a new generation, and a
+  reset creates it for a subject never written. A tombstone reads absent only
+  once `BUNDLED_STORE_WRITE_LIFETIME_MS` (24 hours) has passed since the
+  set's last membership write, and each emptying write, a reset of an empty
+  set included, starts that again. A set holding a record never expires.
+  Account deletion is the same reset.
+- **A set held without a generation**, written before the Store kept one,
+  is given a fresh one, atomically, by its first list, its records kept. A
+  conditional write against it answers `conflict` and mints nothing.
+- **No list is served from a cache.** A list answers the records and the
+  generation from one snapshot that reflects every write the Store
+  acknowledged before the list began: never a cached answer, from the Store,
+  an HTTP cache in front of it or a lagging replica. A stale list answers a
+  factor already removed as present, and a generation already moved.
+- **A rollback must not bring a generation back.** A restore or a failover
+  that returns a set to a state from before a write the Store acknowledged
+  would answer that state's generation again, which a writer may still hold.
+  The Store mints a fresh generation for every set it restores before it
+  answers one, or runs so that acknowledged writes are never rolled back, and
+  states which.
+- **A conditional write states its deadline.** A conditional create or delete carries `deadlineMs`: the instant, in epoch milliseconds on the provider's clock, after which it must not be applied. The adapter sets it to the moment it sends plus its request timeout, and gives up at that moment itself. The Store checks `deadlineMs` against its own clock in the same atomic step as the conditional write; at or after it, the write is not applied and the answer is `408`.
+  The adapter's write lifetime W is its request timeout plus the clock skew assumed between the provider and the Store.
+  The provider's and the Store's clocks agree within that skew.
+  This adapter takes `deadlineMs` just before it sends the request, and its
+  timer starts after that, so the deadline is at or before the moment it gives
+  up: a write past it is never applied after the adapter stopped waiting.
+  A `deadlineMs` absent or not a whole instant above 0 within the `Date`
+  range is `400`.
+- **No retry.** The adapter never retries a conditional write; it gives up at
+  its deadline, and a timeout or an unexpected status leaves the outcome
+  unknown. The Store, and anything in front of it, answers `421` only for a
+  request it did not apply, because the HTTP client may send it again: Node's
+  `fetch` sends a `POST` once more on a `421`.
+
+**When a call fails, nothing the Store sent reaches a client**: no status, no
+error text, no header, no record, and not whether a record was unreadable.
+Every failure of these endpoints is answered with the provider's answer for an
+outage, `503 temporarily_unavailable`. What went wrong reaches the operator's
+log line and audit event only, through what the adapter throws: a
+`MfaStoreError` ([`src/mfa/storeFailure.mts`](src/mfa/storeFailure.mts)) built
+from the operation, the endpoint by origin and path, the status as a number
+and — for a skipped version — the subject and the factor id, leading the
+message so a log line's cut keeps both, each through core's `auditErrorText`
+and at most 64 characters; never from a body, a status text or a header, with
+the body released unread; and with no `status`, `statusCode` or `cause` an
+HTTP layer would answer with or print. A transport failure, the deadline and
+a refused credential throw the user repository's errors.
+
+A readable record's `id`, `kind` and `label` do reach a client, by design: the
+MFA ADR's pages show them (the account page's list of factors, F4; a first
+binding's enrollable kinds, F3). They reach it only in the shape the reader
+holds them to, so nothing else the Store writes in them does.
+
+| `reason` | When |
+| --- | --- |
+| `unexpected_status` | A status the table does not give the endpoint; `storeStatus` holds it |
+| `unknown_subject` | `markMfaEnrolledUrl` answered `404` |
+| `malformed_answer` | A `2xx` whose body is not the table's, or a conditional write's `404` or `409` without its outcome body; from `listVersioned`, a list holding a record the provider cannot read too |
+| `unreadable_record` | From `list`, a list holding a record the provider cannot read. One fault, two reasons: the same list makes `listVersioned` throw `malformed_answer`, since core's codec reads it as an answer outside the contract |
+| `version_skipped` | An update answered a version other than `expectedVersion + 1` |
+
+### Where the factor endpoints are configured
+
+The four factor endpoints are the section of the module that keeps a subject's
+factors in the Store, `foundation-mfa-factor-store`, named after it
+([`src/mfa/section.mts`](src/mfa/section.mts)); the package's
+[`config/reference.conf`](config/reference.conf), exported as
+`@o3co/auth-provider-foundation/reference.conf`, binds each key to the
+variable named after its path, with no default:
+
+| Key | Env |
+| --- | --- |
+| `listUrl` | `FOUNDATION_MFA_FACTOR_STORE_LIST_URL` |
+| `createUrl` | `FOUNDATION_MFA_FACTOR_STORE_CREATE_URL` |
+| `updateUrl` | `FOUNDATION_MFA_FACTOR_STORE_UPDATE_URL` |
+| `deleteUrl` | `FOUNDATION_MFA_FACTOR_STORE_DELETE_URL` |
+
+A key the section does not know, and a URL that is not `https` or loopback
+`http`, refuse the boot at config validation, naming the key in printable
+characters and quoting no value. Each URL is required: the module reading the
+section, `foundationMfaFactorStoreModule`, provides its store eagerly
+(`foundationMfaFactorStoreLifecycle`) and calls
+`readFoundationMfaFactorStoreUrls` first, so a composition that installs it
+with any of the four unset refuses the boot, naming each missing key and its
+variable, whether or not anything requires the store.
+
+`markMfaEnrolledUrl` is not in this section. The witness is written through
+the user repository whatever keeps the factors — Redis factors with the
+Store's witness among them — so its URL is a key of the user repository's
+settings: `repositories.user.http.markMfaEnrolledUrl`
+(`REPOSITORIES_USER_HTTP_MARK_MFA_ENROLLED_URL`), with no default. With the
+URL, the user repository writes the witness (`markMfaEnrolled`); without it,
+the repository has no `markMfaEnrolled` — the capability is absent, never a
+refused boot, since the witness is optional (the MFA ADR's D12) — and a
+composition with MFA on whose user repository cannot write the witness is
+warned at boot (`mfa_enrollment_witness_unwritable`), whatever keeps the
+factors: the witness is what keeps a lost factor store from opening a first
+binding. A value set that is not a string, a URL that is not `https` or
+loopback `http`, and one carrying `user:password@` refuse the boot when the
+repository is built, naming `markMfaEnrolledUrl` and quoting no value.
+
+### The Store-backed factor store
+
+[`HttpMfaFactorStore`](src/mfa/HttpMfaFactorStore.mts) is `MfaFactorStore`
+(`kind` `"store"`) over the four factor endpoints, and
+[`foundationMfaFactorStoreModule`](src/mfa/module.mts) installs it:
+
+```typescript
+import { foundationMfaFactorStoreModule } from "@o3co/auth-provider-foundation";
+
+const modules = [
+  // The Store transport settings: the user repository's HTTP settings, handed
+  // over as the composition root hands them to the user repository's builder.
+  foundationMfaFactorStoreModule({ storeTransport: config.repositories.user.http }),
+  // ...the MFA package's modules, a transaction store
+];
+```
 
-### Constructor validation
+- The module provides `mfaFactorStore`, built at boot whether or not
+  anything requires it, from the section's four URLs, read first.
+- It requires no slot and reads no configuration beyond its own section.
+- `storeTransport` is required: the Store's credential, deadline and response
+  cap are the user repository's, so the composition root hands it the user
+  repository's HTTP settings (`repositories.user.http`). Their `bearerToken`,
+  `timeout` and `maxResponseBytes` are read as the `"http"` builder reads
+  them, text as numbers, so one token goes to every Store endpoint. `{}`
+  states that there are none: no credential is sent, and the deadline and the
+  cap are 5000 ms and 1 MiB. Settings left out, or that are not a section of
+  keys, refuse the boot rather than send no credential. A setting the
+  transport refuses — the rules of
+  [constructor validation](#constructor-validation) — refuses the boot too
+  (`provides-factory-failed`), naming `HttpMfaFactorStore`.
+- It declares no replica-unsafe state: the factors are the Store's.
+
+It writes the factor set's membership through `createIf`, `removeIf` and
+the reset. It answers the port as the
+[contract](#the-stores-mfa-endpoints) gives each answer, and throws on
+anything else:
+
+| Operation | The Store answers | The port gets |
+| --- | --- | --- |
+| `list` | `200 { factors }` | Every record, read whole. A record it cannot read, one of another subject or a second record with one id throws `unreadable_record`. |
+| `list` | Any other status, a redirect included | Throws `unexpected_status`: never "no factors". |
+| `update` | `200 { factor }` | The record, when it is the one named, holding the changes sent, at `expectedVersion + 1`; otherwise throws `malformed_answer` or `version_skipped`. Its `kind`, `binding` and `createdAtMs` are the Store's word: the port hands the adapter no earlier record to compare them with. `kind` is bound into the seal, so data answered under another kind does not open. |
+| `update` | `409` or `404` / any other | `null` / throws `unexpected_status`. |
+| `removeAllForSubject` | `2xx` or `404` / any other | Done / throws `unexpected_status`. |
+| `listVersioned` | `200 { factors, generation }` | The records and the set's generation, read whole by `readMfaStoreVersionedListAnswer`; `{ items: [], generation: null }` for an absent set. An answer the codec refuses — no `generation`, as a Store from before it answers, a generation out of shape, a record it cannot read, of another subject or twice — throws `malformed_answer`. |
+| `listVersioned` | Any other status | Throws `unexpected_status`. |
+| `createIf` | `200` / `409`, each with its outcome body | `created` with the set's new generation / `conflict`. Without its body, or with another status's outcome, throws `malformed_answer`. |
+| `createIf` | Any other status, a `404`, a late write's `408` and a `204` from a Store that ignores `expectedGeneration` included | Throws `unexpected_status`. |
+| `removeIf` | `200` / `404` / `409`, each with its outcome body | `removed` with the set's new generation / `missing` / `conflict`. Without its body, or with another status's outcome, throws `malformed_answer`. |
+| `removeIf` | Any other status, a late write's `408` included | Throws `unexpected_status`. |
+
+The set's members read the status first: one the operation is not given
+throws `unexpected_status`, its body released unread. The body of a status
+it is given is parsed once and read by core's codec alone, and what the codec
+refuses throws `malformed_answer`, carrying none of the codec's words. A
+conditional write that rejects after it was sent — its deadline, a lost
+connection, a `408`, a refused answer — is unknown, never `missing` or
+`conflict`: it may have committed. A Store that ignores `expectedGeneration` may have
+written unfenced before its answer is refused; only the contract suite, run
+in the Store's own CI, shows that it does not.
+
+Before any request, a record or an update the wire codec would not read back
+— an id that is not 22 base64url characters, a label out of shape, an update
+at `Number.MAX_SAFE_INTEGER`, an expected generation that is no generation —
+is a `RangeError`, and nothing is sent. The
+`data` it is handed is sent as it is: the MFA package sealed it, and nothing
+here opens it.
+
+**The Store is trusted with the factors.** The adapter reads each answer
+strictly, but it cannot tell an old record from a current one, a list with a
+record left out from a complete one, or a factor removed and answered again
+from one never removed: the Store is responsible for the factors' integrity
+and freshness ([what the Store must enforce itself](#what-the-store-must-enforce-itself)).
+
+### The witness written through the user repository
+
+With `markMfaEnrolledUrl`, `HttpUserRepository.markMfaEnrolled(subject,
+enrolled)` posts `{ subject, enrolled }` to it
+([`src/mfa/markEnrolled.mts`](src/mfa/markEnrolled.mts)), with the user
+repository's credential and deadline; it reads no body, so the response cap
+does not apply. `204` is done; `404` throws an
+`MfaStoreError` `unknown_subject`, and any other status — a `200` and a
+redirect included — `unexpected_status`, the body released unread. A
+transport failure, the deadline and a refused credential throw the user
+repository's errors. A subject that is not a non-empty string, or a value
+that is not a boolean, is a `RangeError`, and nothing is sent.
+
+The MFA package marks a subject `true` once its first counting factor is
+written — a first binding at a login or in a signed-in session — and again
+whenever a counting factor is verified where the login's `User` does not say
+the subject enrolled, a step-up included, so a mark that failed is written at
+the subject's next such verification; a mark that fails is one warning
+(`mfa_enrollment_witness_unwritten`) and the login completes. A Store that
+takes the marks but never answers `mfaEnrolled` back is therefore marked once
+per counting verification.
+The witness then stops a lost factor store from opening a first binding: a
+login whose `User` says the subject enrolled, beside no factor that counts,
+is `503` (`mfa.enrollment_state_inconsistent`), never a password-only login
+or a first binding.
+
+Without the URL nothing is written, and the provider reads back whatever
+`mfaEnrolled` the Store answers. Then nothing but the Store keeps a
+subject's factor list whole: a Store that drops a subject's records lets a
+password-only login through under `mfa.mode = "optional"`, and opens a first
+binding to whoever holds the password under `required`.
+
+**Turning it on.** A subject that enrolled before
+`REPOSITORIES_USER_HTTP_MARK_MFA_ENROLLED_URL` was set has no witness until
+its next counting verification, and until then a lost factor store reads it
+as never enrolled. When you set the URL, backfill `mfaEnrolled = true` in the
+Store for every subject that holds a counting factor.
+
+### Testing against the contract
+
+[`@o3co/auth-provider-test-kit`](../test-kit/README.md) holds the enrollment
+witness's contract suite, `MfaFactorStore`'s (`mfaFactorStoreContract`), the
+factor set's (`mfaFactorStoreConditionalContract`), and a fake Store that
+answers these endpoints as the table says, the set's generation and its
+tombstone included — and, told to, as a broken Store would. This package's
+tests run both factor store suites against `HttpMfaFactorStore` over the fake
+Store, a second adapter on the same Store racing the first, and the
+witness's suite
+against `HttpUserRepository` with `markMfaEnrolledUrl` over it, reading the
+witness back through `authenticate` and `authenticateByToken`. The
+section's test builder, `foundationMfaFactorStoreConfig`, is on
+`@o3co/auth-provider-foundation/testing`.
+
+## What the Store must enforce itself
+
+- **Who may call it.** What `authenticateByToken` and linking carry is not a
+  secret — the federation callback's `<provider>:<sub>` is an identifier — so a
+  Store that answers any caller lets anyone who can reach
+  `authenticateByTokenUrl` resolve a known identity to its user, and anyone who
+  can reach an open `linkFederatedIdentityUrl` bind any identity to any
+  `userId`. The MFA endpoints are no less: anyone who can reach an open
+  `deleteUrl` or `markMfaEnrolledUrl` can remove a subject's factors and clear
+  its witness, and the subject's next password login then opens a first
+  binding to whoever holds the password. Configure `bearerToken`
+  (`REPOSITORIES_USER_HTTP_BEARER_TOKEN`, from `openssl rand -hex 32`) and have the Store
+  refuse every request on every endpoint it serves auth.provider — the user
+  repository's four and the MFA endpoints alike — whose `Authorization` is not
+  exactly `Bearer <that token>`, compared in constant time, and never log the
+  header. One token goes to every one of those URLs, so they must be one trust
+  domain: whoever runs any of those endpoints holds a credential the others
+  accept. Refuse with `401` and
+  `WWW-Authenticate: Bearer error="invalid_token"` (RFC 6750 §3), or `403` and
+  `error="insufficient_scope"` for a token that is valid but not enough. With
+  that challenge, a token the Store does not accept — a typo, a half-finished
+  rotation — is an outage on every call, which each caller reports as the
+  table below shows. Without the challenge the `401` or `403` keeps its wire
+  meaning, "no such user" or a refused link, and a mismatch shows only as
+  every login failing. For the same reason, never send a `Bearer` challenge
+  with a user's wrong password, an unknown identity or a link your policy
+  refuses: that answer would read as the Store refusing auth.provider, and the
+  user's failed login or link as an outage. To rotate, have the Store accept the old token and the new, move
+  auth.provider to the new, then retire the old.
+  Without `bearerToken` no request carries an `Authorization` header, and the
+  Store must admit only auth.provider some other way — a network policy or a
+  private network, or mutual TLS provided by the platform in front of the
+  Store (a sidecar on a loopback address, which the `http` carve-out admits).
+  This adapter offers no client certificate of its own: Node's `fetch` takes
+  one only through an `undici` dispatcher, a dependency this package does not
+  carry. A URL carrying `user:password@` is refused.
+- **No secret in the URL.** A query-string token would not stay secret: it
+  travels in every request line, to the Store's own access logs and to any
+  proxy in between. The errors this adapter throws — which the session routes
+  log — name an endpoint by its origin and path only, never its query or
+  fragment, so the query at least does not reach this deployment's log. The
+  caller's credential belongs in `bearerToken`, which nothing this adapter
+  throws carries.
+- **Answer without redirecting.** No request follows a redirect, so a
+  password, a token, a link request or an identity goes only to the configured
+  URL — the one the `https` rule below checks — and no answer from anywhere
+  else is taken as the user, the link or the lookup's answer. A `3xx` from any
+  endpoint throws like any other unexpected status (the session
+  routes and the jwt-bearer grant answer `503 temporarily_unavailable`, the
+  grants callback `temporarily_unavailable`), so a Store behind a URL that
+  redirects — a host alias redirecting to the canonical host, an added
+  trailing slash, a moved path — fails every call. Configure each URL as the
+  endpoint that answers, not one that redirects.
+- **Keep the MFA factors whole and fresh.** A Store that keeps MFA factors
+  is responsible for their integrity and freshness: it never rolls a factor
+  back, hides one from a list, answers one it acknowledged removing, or lets
+  two updates at one version both succeed. A version never goes back, and an
+  acknowledged write is never lost across a restore or a failover; a list
+  answers the latest write, never a cache's or a lagging replica's. The provider cannot tell when this breaks: an
+  older record's sealed data opens as it did then — the seal binds the
+  subject, the factor id and the kind, not the version — so a TOTP step
+  already used is accepted again within its window, a spent recovery code
+  works again, and a removed factor is back. A Store that drops a subject's
+  records lets a password-only login through under `mfa.mode = "optional"`,
+  and opens a first binding to whoever holds the password under `required`;
+  the enrollment witness, kept outside the factor store, is what stops that
+  (the MFA ADR's D12). The MFA ADR's O6 recommends the factors in Redis and the witness in the Store; keeping
+  both in one Store loses that protection, since what drops or rolls back
+  the one can do the same to the other. The runbook, "Keeping MFA factors in
+  the Store", has the failover and restore procedures.
+
+**What a refused token looks like, per caller.** Each caller answers a
+`StoreCredentialRefusedError` as it answers any Store failure — a
+`StoreTransportError` or a `TimeoutError` too; what differs is what it logs:
+
+| Caller | Answers | Logs |
+| --- | --- | --- |
+| Password login, `POST /session/login` ([`@o3co/auth-provider-session`](../session/README.md)) | `503 temporarily_unavailable` | `login_store_unavailable` (error, `store: "user_repository"`), with `err` |
+| Federation login and `?link=1` callbacks (session) | `503 temporarily_unavailable` | `federation_callback_store_unavailable` or `federation_link_store_unavailable` (error, `store: "user_repository"`), with `err` |
+| The jwt-bearer grant ([`@o3co/auth-provider-oauth`](../oauth/README.md)) | `503 temporarily_unavailable` | `jwt_bearer_user_repository_unavailable` (error), with `err` |
+| The federation-grants connect callback — the identity lookup ([`@o3co/auth-provider-federation-grants`](../federation-grants/README.md)) | redirect with `error=temporarily_unavailable` | `federation_grant_callback_unavailable` (error), `store: "user_directory"`, with `err` |
+
+Where `err` is logged, a `StoreCredentialRefusedError`'s message names the
+Store endpoint (its origin and path), the status and
+`REPOSITORIES_USER_HTTP_BEARER_TOKEN` — never the token; a `StoreTransportError`'s names
+the endpoint the same way, what failed and at most a transport code. No
+message this adapter throws quotes a URL's query string or fragment.
+
+## Constructor validation
 
 Every option is validated in the **constructor**, so a misconfigured deployment
 fails at boot rather than at the first login attempt.
 
-**Every URL must use `https://`** (the link and lookup endpoints included). They carry plaintext user credentials — a
+**Every URL must use `https://`** (the link, lookup and witness endpoints included). They carry plaintext user credentials — a
 password on `authenticateUrl`, a token on `authenticateByTokenUrl`, a verified
 upstream identity on `findSubjectByFederatedIdentityUrl` — so an
 `http://` URL does not merely weaken the connection, it publishes the credential
-to every hop on the path.
+to every hop on the path. The URL checked here is the only place a request goes
+and the only one whose answer is taken: no request follows a redirect, so a
+`307` or `308` cannot re-send the body to, and no `301`, `302` or `303` can fetch an answer from, a `Location` this rule never saw.
 
 **The one carve-out is loopback:** `http://` is accepted when the host is
 `localhost`, an address in `127.0.0.0/8`, or `[::1]`. That traffic never leaves
@@ -170,44 +739,122 @@ This is the same rule `oauth.jwt.issuer` applies in
 [`@o3co/auth-provider-core`](../core/README.md), with the carve-out widened from
 the single address `127.0.0.1` to the whole `127.0.0.0/8` block, and query
 strings allowed (an issuer may not carry one; a POST endpoint legitimately may).
+A query is sent, and never quoted: every error names the endpoint by origin
+and path.
+
+`HttpMfaFactorStore` holds its four URLs, `timeout`, `maxResponseBytes` and
+`bearerToken` to the same rules below, each refusal naming
+`HttpMfaFactorStore`.
 
 **`timeout` must be a positive integer** no greater than `2147483647`
 milliseconds. `0`, a negative number, and `NaN` all clamp to "fire immediately"
 in `setTimeout` — which would abort every request — and a value above Node's
 timer range clamps to 1ms, turning "be patient" into the most impatient setting
-available. The deadline covers the whole exchange, **body included**: the body
-read is raced against it rather than relying on the abort signal, because
-aborting a request does not reliably interrupt a read already in flight. That is
-the slow-loris shape — headers arrive promptly, then the body dribbles or stops
-— and without the race it hangs forever. A request that outlives the deadline
-rejects with a `timed out after <n>ms` error naming the endpoint.
+available. A blank environment override is a boot failure, not the default. The
+deadline covers the whole exchange, **body included**: the body read is raced
+against it rather than relying on the abort signal, because aborting a request
+does not reliably interrupt a read already in flight. That is the slow-loris
+shape — headers arrive promptly, then the body dribbles or stops — and without
+the race it hangs forever. A request that outlives the deadline rejects with a
+`timed out after <n>ms` error naming the endpoint, named `TimeoutError` on
+every request, so a reporter that classifies by name reads it as a timeout.
 
 **`maxResponseBytes` must be a positive integer**, defaulting to
 `DEFAULT_MAX_RESPONSE_BYTES` (1 MiB). The cap is enforced against
 `Content-Length` *and* while streaming, so a Store that omits the header — or
 lies in it — is still cut off rather than allowed to exhaust memory.
 
-## Usage Example
-
-```typescript
-import { createRepositoryFactories } from "@o3co/auth-provider-core";
-import { registerBuiltinAdapters } from "@o3co/auth-provider-foundation";
-
-const { userFactory } = createRepositoryFactories();
-
-registerBuiltinAdapters({ userFactory });
+**`bearerToken`, when set, must be a bare RFC 6750 token of at least 32 bytes
+of key material.** Unset (absent) sends no `Authorization` header. Set, it is
+refused unless it is a string, not blank (a blank environment override is a
+boot failure, not "no token"), made only of letters, digits, `-._~+/` and
+trailing `=` padding — no whitespace, no line break, and no `Bearer ` prefix,
+which the adapter adds — and it clears core's shared-secret floor
+(`MIN_SECRET_ENTROPY_BYTES`, the one `SESSION_STORE_SECRET` and `KEY_STORE_LOCAL_SECRET`
+clear), measured on the decoded length of a hex or base64 value, so
+`openssl rand -hex 16` is 16 bytes however long it looks. Whoever holds the
+token speaks to the Store as auth.provider. The shape is checked here because
+a header value `fetch` refuses is one it quotes in the error it throws. No
+refusal quotes the value, no error from a request carries it — a transport
+failure is thrown without the transport's error (see the wire contract) — and
+it is held in an ECMAScript private field, so it is absent from `inspect()`
+and `JSON.stringify` of the repository. These checks run when the repository
+is built, which a deployment does under `adapters.userRepository = "http"`
+(the standalone template's default); under core's `reference.conf` default,
+`yaml`, the `http` block — and a token in it — is not read at all.
 
-// Create an HTTP user repository via the factory
-const userRepo = await userFactory.create({
-  type: "http",
-  authenticateUrl: "https://users.example.com/authenticate",
-  authenticateByTokenUrl: "https://users.example.com/authenticate-by-token",
-  timeout: 5000,
-});
-```
-
-## See Also
+## Public API
 
-- [`@o3co/auth-provider-core`](../core/README.md) — Core interfaces (`UserRepository`, `CodeRepository`, `AdapterFactory`, `createAdapterFactory`, `BuilderContext`, `PathResolver`)
-- [`@o3co/auth-provider-redis`](../redis/README.md) — Redis-backed adapters (challenges, replay-seen-set, refresh-token-family, user-sessions, federation-tokens, **code-repository**, rate-limiter)
-- [auth.provider](../../README.md) — Top-level repository documentation
+Exported from [`src/index.mts`](src/index.mts):
+
+- `registerBuiltinAdapters({ userFactory })` — registers the `"http"` type.
+- `HttpUserRepository` — the repository
+  ([`src/repositories/HttpUserRepository.mts`](src/repositories/HttpUserRepository.mts)).
+- `StoreCredentialRefusedError` — what a refused credential throws; its
+  `name` and `storeStatus` (`401` or `403`) are part of the contract. Not
+  `status`: Express, http-errors and the standalone's terminal handler read
+  that as the status to answer with.
+- `StoreTransportError`, `StoreTransportFailure` — what a transport failure
+  throws; its `name`, `reason` and `code` are part of the contract, and it has
+  no `status` either
+  ([`src/repositories/storeErrors.mts`](src/repositories/storeErrors.mts)).
+- `DEFAULT_MAX_RESPONSE_BYTES` — the default response cap.
+- `FederatedIdentityLookupCoverage` — the type of one coverage entry.
+- `HttpMfaFactorStore`, `HttpMfaFactorStoreOptions` — the Store-backed
+  `MfaFactorStore` ([`src/mfa/HttpMfaFactorStore.mts`](src/mfa/HttpMfaFactorStore.mts)).
+- `foundationMfaFactorStoreModule`, `FoundationMfaFactorStoreModuleOptions` —
+  its module ([`src/mfa/module.mts`](src/mfa/module.mts)).
+- `MfaStoreError`, `MfaStoreFailure`, `MfaStoreOperation` — what the MFA
+  endpoints' failures throw; its `name`, `reason`, `operation` and
+  `storeStatus` are part of the contract, and it has no `status`
+  ([`src/mfa/storeFailure.mts`](src/mfa/storeFailure.mts)). The builders the
+  adapter throws through, and the `foundation-mfa-factor-store` section's
+  schema and reader ([`src/mfa/section.mts`](src/mfa/section.mts)), are the
+  package's own.
+
+Exported from [`src/testing/index.mts`](src/testing/index.mts) as
+`@o3co/auth-provider-foundation/testing`, for test code only:
+`foundationMfaFactorStoreConfig(urls, extra?)`, the
+`foundation-mfa-factor-store` section as a configuration fragment to lay over
+a test's configuration, holding the four URLs `urls` holds — a fake Store's
+`urls` included, its other endpoints left behind — and `extra` as given; and
+`foundationUserRepositoryHttpConfig(urls, extra?)`, the user repository's
+`http` block, holding the Store URLs the `"http"` builder reads that `urls`
+holds — its MFA factor endpoints left behind — and `extra` as given, which a
+composition places with core's `withUserRepositoryHttp`.
+
+## Tests
+
+| Test file | Pins |
+| --- | --- |
+| [`HttpUserRepository.test.mts`](src/repositories/__tests__/HttpUserRepository.test.mts) | authentication and its answers, `mfaEnrolled` handed through as the Store answered it, the `User` shape check, the https rule, the timeout and the response cap, linking, and the identity lookup's presence, probe and wire |
+| [`HttpUserRepository.transport.test.mts`](src/repositories/__tests__/HttpUserRepository.transport.test.mts) | against real HTTP servers: the identity lookup releasing a refused answer's connection, and a redirect refused on each of the four requests — to another origin, to the same origin, or with no `Location` — with nothing sent to a redirect target |
+| [`HttpUserRepository.credential.test.mts`](src/repositories/__tests__/HttpUserRepository.credential.test.mts) | against real HTTP servers: `Authorization: Bearer <token>` on each of the four requests when `bearerToken` is set and no `Authorization` header when it is not, by hand and through the `"http"` builder; a weak, malformed, blank or non-string token refused at construction; the token in no failure and no inspection of the repository; a transport failure a `StoreTransportError` that says what failed — a refused connection and an https URL on a plain-HTTP port (not reached), a peer that reflects the token into a status line or header, a head over the size limit (malformed response), a close after a `1xx`, mid-head, before any byte, or of a pooled keep-alive connection between two requests (connection closed), a chunked body (not read), a TLS 1.2 server that refuses the handshake (not reached, `ERR_SSL_SSL/TLS_ALERT_HANDSHAKE_FAILURE`) — with its code and no cause; a timeout a `TimeoutError` whether the headers or the body stall; with a token sent, a `401` or `403` with a `Bearer` challenge a `StoreCredentialRefusedError` (`storeStatus`, no `status`) on each of the four, and one without — or with no token sent — read as before |
+| [`storeErrors.test.mts`](src/repositories/__tests__/storeErrors.test.mts) | which transport codes are kept, and the two named errors' shape — no `status`, no cause |
+| [`wwwAuthenticate.test.mts`](src/repositories/__tests__/wwwAuthenticate.test.mts) | which `WWW-Authenticate` values carry a `Bearer` challenge, and a hostile 64 KiB value read in one pass |
+| [`registerBuiltinAdapters.test.mts`](src/repositories/__tests__/registerBuiltinAdapters.test.mts) | the `"http"` builder, its defaults and string coercion, the optional URLs it forwards, and configuration refused at build time |
+| [`endpointUrl.test.mts`](src/__tests__/endpointUrl.test.mts) | the https-or-loopback rule |
+| [`storeFailure.test.mts`](src/mfa/__tests__/storeFailure.test.mts) | what the MFA endpoints' failures throw: nothing the Store wrote in any form the error leaves in, the body released unread, no status to answer with; a skipped version's log line naming the subject and the factor id, each sanitised and bounded, however long they are |
+| [`section.test.mts`](src/mfa/__tests__/section.test.mts) | the `foundation-mfa-factor-store` section: its schema, its reader, and through `createApp` with the package's module the boot refused for a missing, malformed or unknown key, the module installed alone included |
+| [`module.test.mts`](src/mfa/__tests__/module.test.mts) | `foundationMfaFactorStoreModule` through `createApp`: the Store-backed store provided over the section's URLs with nothing else installed; the Store transport settings required, the user repository's bearer token, deadline and cap read from them (text read as numbers), the boot refused for settings absent or not a section of keys and for a value the user repository refuses too |
+| [`HttpMfaFactorStore.contract.test.mts`](src/mfa/__tests__/HttpMfaFactorStore.contract.test.mts) | the test kit's `MfaFactorStore` suite and the factor set's conditional-write binding against `HttpMfaFactorStore` over the fake Store, with a second adapter on the same Store, one whose Store has closed, and the Store's tombstone clock moved past the write-lifetime bound |
+| [`HttpMfaFactorStore.test.mts`](src/mfa/__tests__/HttpMfaFactorStore.test.mts) | what it sends — each URL as configured, the bearer token, the sealed data byte for byte and nothing it was sealed from, nothing the codec refuses; each operation's answers, and a Store that breaks the contract: `404`, `5xx`, a redirect, a malformed answer, an unreadable record, a foreign subject, a repeated id, a skipped version, an answer that did not write the changes; the set's members: what they send, each status with its outcome body, a `404` or `409` without one malformed, any other status unexpected, a list without its generation malformed, a conditional write given up at its deadline, its `deadlineMs` the send time plus the timeout, a late one refused `408` and not applied, one within its deadline applied; nothing the Store sent in anything thrown; the credential refused (naming this store), a deadline over the head or the body, the cap, an unreachable Store; construction, no unconditional `create` or `remove`, and neither the token nor the endpoints shown when the store is inspected |
+| [`foundationMfaFactorStoreConfig.test.mts`](src/testing/__tests__/foundationMfaFactorStoreConfig.test.mts) | the testing entry's section builder |
+| [`foundationUserRepositoryHttpConfig.test.mts`](src/testing/__tests__/foundationUserRepositoryHttpConfig.test.mts) | the testing entry's builder of the user repository's `http` block, which the `"http"` builder takes |
+| [`storeRequestMessages.test.mts`](src/mfa/__tests__/storeRequestMessages.test.mts) | one wording for a transport failure at the MFA endpoints, whichever client sends to them |
+| [`referenceConf.test.mts`](src/mfa/__tests__/referenceConf.test.mts) | the package's `reference.conf`: only that section, each URL bound to the variable named after its path, no default |
+| [`enrollmentWitness.contract.test.mts`](src/mfa/__tests__/enrollmentWitness.contract.test.mts) | the test kit's witness suite against `HttpUserRepository` over its fake Store, written through `markMfaEnrolled` and read back through `authenticate` and `authenticateByToken`; the capability present with `markMfaEnrolledUrl` alone |
+| [`markEnrolled.test.mts`](src/mfa/__tests__/markEnrolled.test.mts) | `markMfaEnrolled`: what it sends — the URL as configured, `{ subject, enrolled }`, the bearer token, nothing for a subject or a value out of shape; `204` done, `404` `unknown_subject`, any other status `unexpected_status` with no `Location` contacted; a refused credential, a deadline and an unreachable Store; nothing the Store sent, nor the query or the subject, in anything thrown; the URL held to the https rule |
+
+## See also
+
+- [`@o3co/auth-provider-core`](../core/README.md) — the `UserRepository` port,
+  `createRepositoryFactories` and the development user adapters, the MFA
+  ports and the MFA endpoints' wire format
+- [`@o3co/auth-provider-test-kit`](../test-kit/README.md) — the enrollment
+  witness's and the factor store's contract suites, and the fake Store
+- [`@o3co/auth-provider-session`](../session/README.md) — the routes that call
+  `authenticate`, `authenticateByToken` and `linkFederatedIdentity`
+- [`@o3co/auth-provider-federation-grants`](../federation-grants/README.md) — the
+  caller of the identity lookup
+- [auth.provider](../../README.md) — top-level repository documentation