@o3co/auth-provider-foundation 0.14.0 → 0.16.0

package/README.md

@@ -1,85 +1,334 @@
 # @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.
+Last updated: 2026-09-26
 
-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.
+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, and answers the
+identity lookup federation grants ask for. `registerBuiltinAdapters` registers
+it as the `"http"` user adapter.
+
+## Responsibility
+
+**Role.** An adapter for one core port,
+[`UserRepository`](../core/src/repositories/UserRepository.mts) (see
+[`core/src/repositories`](../core/src/repositories/README.md)). 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 —
+`repositories.user.type = "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.
+
+**Does not own:** the port and the `User` shape (core); 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
+nothing but core (the global `fetch`, no other dependency).
 
 ## 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`. The package has no dependencies
+of its own.
 
-Registers the `"http"` adapter type into the provided `userFactory`.
+## Usage
 
 ```typescript
-function registerBuiltinAdapters(factories: {
-  userFactory: AdapterFactory<UserRepository>;
-}): void;
-```
+import { createRepositoryFactories } from "@o3co/auth-provider-core";
+import { registerBuiltinAdapters } from "@o3co/auth-provider-foundation";
+
+const { userFactory } = createRepositoryFactories();
 
-For Redis-backed code storage, register the builder from `@o3co/auth-provider-redis` directly:
+registerBuiltinAdapters({ userFactory });
 
-```typescript
-import { redisCodeRepositoryBuilder } from "@o3co/auth-provider-redis";
-codeFactory.register("redis", redisCodeRepositoryBuilder);
+// 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,
+});
 ```
 
-### `HttpUserRepository`
+`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.
 
-A `UserRepository` implementation that delegates authentication to an upstream HTTP service.
+### Configuration
 
-```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)
-    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>;
-}
+Under `repositories.user` (`type = "http"`, `CLIENT_USER_TYPE`), in its `http`
+block; defaults are in [`reference.conf`](../core/config/reference.conf):
+
+| Key | Env | |
+| --- | --- | --- |
+| `authenticateUrl` | `CLIENT_USER_AUTHENTICATE_URL` | Required. Password login. |
+| `authenticateByTokenUrl` | `CLIENT_USER_AUTHENTICATE_BY_TOKEN_URL` | Required. Resolves an opaque handle: federated login, the jwt-bearer grant. |
+| `linkFederatedIdentityUrl` | `CLIENT_USER_LINK_FEDERATED_IDENTITY_URL` | Optional. Enables account linking. |
+| `findSubjectByFederatedIdentityUrl` | `CLIENT_USER_FIND_SUBJECT_BY_FEDERATED_IDENTITY_URL` | Optional. The identity lookup. |
+| `federatedIdentityLookupCoverage` | — (a list; HOCON only) | What the lookup covers. Default `[]`. |
+| `bearerToken` | `CLIENT_USER_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` | `CLIENT_USER_TIMEOUT` | Milliseconds. Default 5000. |
+| `maxResponseBytes` | `CLIENT_USER_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, … }`) 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";
+- any other status throws.
+
+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 of the four endpoints 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. 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`,
+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
+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
+unfamiliar identity is `identity_not_resolvable`, and multiple distinct local
+owners are a server error. Declaring coverage attests to that strategy; boot
+neither discovers nor proves the remote directory's completeness.
+
+The request is `POST findSubjectByFederatedIdentityUrl` with
+
+```json
+{ "provider": "entra-files", "issuer": "https://login.microsoftonline.com/<tenant>/v2.0",
+  "clientId": "<the grants app registration>", "sub": "<verified sub>",
+  "claims": { "tid": "<verified>", "oid": "<verified>" } }
 ```
 
-- 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).
-
-### Constructor validation
+— 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 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
+
+| Body | Meaning |
+|---|---|
+| `{ "kind": "linked", "subject": "<local User.id>" }` | exactly one local user holds it. `subject` is that user's `id` **byte for byte** — the callback compares it with the signed-in user's `sub` exactly, so a padded or otherwise normalised id reads as another user's |
+| `{ "kind": "unlinked" }` | a **complete** resolution found nobody |
+| `{ "kind": "indeterminate", "reason": "registration_not_covered" }` | no strategy for this registration |
+| `{ "kind": "indeterminate", "reason": "identity_not_resolvable" }` | a strategy, and this identity is not in it |
+
+Fields beyond those are ignored. **Everything else is an outage, never
+"nobody"**: any status but a `2xx` — `404`, `401`, `403`, `409`, `5xx` — a
+`2xx` whose body is empty or not one of the four, a redirect (never followed:
+the body carries a verified identity), a timeout, or a body over the cap all
+throw, and the callback answers `temporarily_unavailable`. More than one
+distinct local owner is a `500` from the Store. What is thrown names the
+endpoint — and, for an answer with a status, the status — never the body,
+the identity, a status text or an underlying cause.
+
+**Coverage.** The probe the grants module asks at boot is synchronous and
+cannot reach the Store, so `federatedIdentityLookupCoverage` relays what the
+Store's lookup covers: one entry per registration,
+`{ provider, issuer, clientId, requiredClaims }`, all four fields, compared
+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`. When federation grants are enabled and have at
+least one connection and `federationGrants.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. `supportsFederatedIdentityLookup` and `findSubjectByFederatedIdentity`
+are absent when `findSubjectByFederatedIdentityUrl` is not configured, and a
+deployment that then has a connection under `"required"` is refused at boot.
+
+## 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`. Configure `bearerToken` (`CLIENT_USER_BEARER_TOKEN`, from
+  `openssl rand -hex 32`) and have the Store refuse every request on all four
+  endpoints whose `Authorization` is not exactly `Bearer <that token>`,
+  compared in constant time, and never log the header. One token goes to all
+  four 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
+  of the four endpoints 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.
+
+**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
+`CLIENT_USER_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 endpoint included). They carry plaintext user credentials — a
-password on `authenticateUrl`, a token on `authenticateByTokenUrl` — so an
+**Every URL must use `https://`** (the link and lookup 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
@@ -94,44 +343,82 @@ 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.
 
 **`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 all
+four requests, 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
+**`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_SECRET` and `OAUTH_JWT_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 `repositories.user.type = "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.
 
-```typescript
-import { createRepositoryFactories } from "@o3co/auth-provider-core";
-import { registerBuiltinAdapters } from "@o3co/auth-provider-foundation";
+## Public API
 
-const { userFactory } = createRepositoryFactories();
+Exported from [`src/index.mts`](src/index.mts):
 
-registerBuiltinAdapters({ userFactory });
+- `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.
 
-// 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,
-});
-```
+## Tests
+
+| Test file | Pins |
+| --- | --- |
+| [`HttpUserRepository.test.mts`](src/repositories/__tests__/HttpUserRepository.test.mts) | authentication and its answers, 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, and configuration refused at build time |
+| [`endpointUrl.test.mts`](src/__tests__/endpointUrl.test.mts) | the https-or-loopback rule |
 
-## See Also
+## See also
 
-- [`@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
+- [`@o3co/auth-provider-core`](../core/README.md) — the `UserRepository` port,
+  `createRepositoryFactories` and the development user adapters
+- [`@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

package/dist/endpointUrl.d.mts

@@ -27,6 +27,15 @@
  * runs on, though, is shared vocabulary: `isLoopbackHostname` comes from
  * `@o3co/auth-provider-core` (`net/loopback`, #364), the same definition the
  * session redirect policy consumes, so the carve-outs cannot drift apart.
+ *
+ * ## What a message names of an endpoint
+ *
+ * Every failure the repository throws names the endpoint it was talking to,
+ * and every caller logs what it throws. A message names the endpoint by its
+ * origin and path alone ({@link endpointForMessage}): a query string is
+ * accepted in a Store URL, and a deployment may carry a credential there
+ * (`?api_key=…`) despite the README's advice, so the query never reaches a
+ * message — nor does a fragment, which no request sends anyway.
  */
 import { isLoopbackHostname } from "@o3co/auth-provider-core";
 export { isLoopbackHostname };
@@ -56,4 +65,15 @@ export declare function describeEndpointRejection(reason: EndpointRejection): st
  * lands in logs.
  */
 export declare function assertSecureEndpoint(value: unknown, field: string): string;
+/**
+ * `url` as a message names it: its origin and path — `https://store.example
+ * /authenticate`, as the WHATWG URL parser normalises them (a default port
+ * dropped, scheme and host lower-cased, an IPv6 literal in brackets) — and
+ * never its query or fragment, which may carry a credential. Anything that is
+ * not an http or https URL is named by what it is not: its origin would be
+ * `"null"` and its "path" the rest of it (`data:…`, `mailto:…`), and the
+ * constructor refuses such a Store URL anyway — but a caller can hand
+ * `StoreCredentialRefusedError` anything.
+ */
+export declare function endpointForMessage(url: string): string;
 //# sourceMappingURL=endpointUrl.d.mts.map

package/dist/endpointUrl.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"endpointUrl.d.mts","sourceRoot":"","sources":["../src/endpointUrl.mts"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAK9D,OAAO,EAAE,kBAAkB,EAAE,CAAC;AAE9B,4EAA4E;AAC5E,MAAM,MAAM,iBAAiB,GAC1B,cAAc,GACd,OAAO,GACP,kBAAkB,GAClB,oBAAoB,GACpB,iBAAiB,GACjB,iBAAiB,CAAC;AAKrB;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,iBAAiB,GAAG,IAAI,CAyB5E;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAwB3E;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAS1E"}
+{"version":3,"file":"endpointUrl.d.mts","sourceRoot":"","sources":["../src/endpointUrl.mts"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAK9D,OAAO,EAAE,kBAAkB,EAAE,CAAC;AAE9B,4EAA4E;AAC5E,MAAM,MAAM,iBAAiB,GAC1B,cAAc,GACd,OAAO,GACP,kBAAkB,GAClB,oBAAoB,GACpB,iBAAiB,GACjB,iBAAiB,CAAC;AAKrB;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,iBAAiB,GAAG,IAAI,CAyB5E;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAwB3E;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAS1E;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAQtD"}

package/dist/endpointUrl.mjs

@@ -42,6 +42,15 @@
  * runs on, though, is shared vocabulary: `isLoopbackHostname` comes from
  * `@o3co/auth-provider-core` (`net/loopback`, #364), the same definition the
  * session redirect policy consumes, so the carve-outs cannot drift apart.
+ *
+ * ## What a message names of an endpoint
+ *
+ * Every failure the repository throws names the endpoint it was talking to,
+ * and every caller logs what it throws. A message names the endpoint by its
+ * origin and path alone ({@link endpointForMessage}): a query string is
+ * accepted in a Store URL, and a deployment may carry a credential there
+ * (`?api_key=…`) despite the README's advice, so the query never reaches a
+ * message — nor does a fragment, which no request sends anyway.
  */
 import { isLoopbackHostname } from "@o3co/auth-provider-core";
 // Re-exported unchanged: this module's callers (and its tests) read the
@@ -127,3 +136,24 @@ export function assertSecureEndpoint(value, field) {
     }
     return value;
 }
+/**
+ * `url` as a message names it: its origin and path — `https://store.example
+ * /authenticate`, as the WHATWG URL parser normalises them (a default port
+ * dropped, scheme and host lower-cased, an IPv6 literal in brackets) — and
+ * never its query or fragment, which may carry a credential. Anything that is
+ * not an http or https URL is named by what it is not: its origin would be
+ * `"null"` and its "path" the rest of it (`data:…`, `mailto:…`), and the
+ * constructor refuses such a Store URL anyway — but a caller can hand
+ * `StoreCredentialRefusedError` anything.
+ */
+export function endpointForMessage(url) {
+    try {
+        const { protocol, origin, pathname } = new URL(url);
+        if (protocol === "http:" || protocol === "https:")
+            return `${origin}${pathname}`;
+    }
+    catch {
+        // Named below, like any other value that is not an http or https URL.
+    }
+    return "(an endpoint that is not an http or https URL)";
+}

package/dist/index.d.mts

@@ -2,5 +2,6 @@ import type { AdapterFactory, UserRepository } from "@o3co/auth-provider-core";
 export declare const registerBuiltinAdapters: (factories: {
     userFactory: AdapterFactory<UserRepository>;
 }) => void;
-export { DEFAULT_MAX_RESPONSE_BYTES, HttpUserRepository, } from "./repositories/HttpUserRepository.mjs";
+export { DEFAULT_MAX_RESPONSE_BYTES, type FederatedIdentityLookupCoverage, HttpUserRepository, } from "./repositories/HttpUserRepository.mjs";
+export { StoreCredentialRefusedError, StoreTransportError, type StoreTransportFailure, } from "./repositories/storeErrors.mjs";
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../src/index.mts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AA6B/E,eAAO,MAAM,uBAAuB,GAAI,WAAW;IAClD,WAAW,EAAE,cAAc,CAAC,cAAc,CAAC,CAAC;CAC5C,KAAG,IAsBH,CAAC;AAEF,OAAO,EACN,0BAA0B,EAC1B,kBAAkB,GAClB,MAAM,uCAAuC,CAAC"}
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../src/index.mts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AA8B/E,eAAO,MAAM,uBAAuB,GAAI,WAAW;IAClD,WAAW,EAAE,cAAc,CAAC,cAAc,CAAC,CAAC;CAC5C,KAAG,IA0CH,CAAC;AAEF,OAAO,EACN,0BAA0B,EAC1B,KAAK,+BAA+B,EACpC,kBAAkB,GAClB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EACN,2BAA2B,EAC3B,mBAAmB,EACnB,KAAK,qBAAqB,GAC1B,MAAM,gCAAgC,CAAC"}

package/dist/index.mjs

@@ -56,9 +56,29 @@ export const registerBuiltinAdapters = (factories) => {
             ...(typeof config.linkFederatedIdentityUrl === "string"
                 ? { linkFederatedIdentityUrl: config.linkFederatedIdentityUrl }
                 : {}),
+            // #613: optional. Forwarded whenever SET, not only when well-typed —
+            // the link URL above vanishes when misspelt, and for the lookup a value
+            // that vanishes is a deployment that believes itself covered and is
+            // not. The constructor refuses what is not a URL, or not a list.
+            ...(config.findSubjectByFederatedIdentityUrl !== undefined
+                ? {
+                    findSubjectByFederatedIdentityUrl: config.findSubjectByFederatedIdentityUrl,
+                }
+                : {}),
+            ...(config.federatedIdentityLookupCoverage !== undefined
+                ? {
+                    federatedIdentityLookupCoverage: config.federatedIdentityLookupCoverage,
+                }
+                : {}),
+            // Optional, and forwarded whenever SET for the lookup URL's reason: a
+            // token that vanished would be a deployment that believes its Store
+            // calls authenticated and sends them bare. The constructor refuses
+            // what is not a string, and what is blank, malformed or too weak.
+            ...(config.bearerToken !== undefined ? { bearerToken: config.bearerToken } : {}),
             timeout: toNumber(config.timeout, DEFAULT_TIMEOUT_MS),
             maxResponseBytes: toNumber(config.maxResponseBytes, DEFAULT_MAX_RESPONSE_BYTES),
         });
     });
 };
 export { DEFAULT_MAX_RESPONSE_BYTES, HttpUserRepository, } from "./repositories/HttpUserRepository.mjs";
+export { StoreCredentialRefusedError, StoreTransportError, } from "./repositories/storeErrors.mjs";