@o3co/auth-provider-foundation 0.14.0 → 0.16.0

package/dist/repositories/HttpUserRepository.mjs

@@ -13,7 +13,10 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { assertSecureEndpoint } from "../endpointUrl.mjs";
+import { describeWeakSecret, MIN_SECRET_ENTROPY_BYTES, measureSecretEntropyBytes, } from "@o3co/auth-provider-core";
+import { assertSecureEndpoint, endpointForMessage } from "../endpointUrl.mjs";
+import { readFailure, requestFailure, StoreCredentialRefusedError } from "./storeErrors.mjs";
+import { hasBearerChallenge } from "./wwwAuthenticate.mjs";
 /** The Store answered 409 to a link request: the identity is already someone else's (#482). */
 const CONFLICT = Symbol("conflict");
 /**
@@ -51,6 +54,154 @@ function isUser(v) {
     const o = v;
     return typeof o.id === "string" && typeof o.username === "string";
 }
+const COVERAGE_FIELD = "federatedIdentityLookupCoverage";
+const COVERAGE_KEYS = new Set([
+    "provider",
+    "issuer",
+    "clientId",
+    "requiredClaims",
+]);
+/** A claim name: printable ASCII, no spaces (the shape the connection side accepts). */
+const CLAIM_NAME = /^[\x21-\x7E]{1,256}$/;
+const FORBIDDEN_CLAIM_NAMES = new Set([
+    "__proto__",
+    "constructor",
+    "prototype",
+]);
+/** A registration field: a non-empty string carrying no surrounding whitespace, compared exactly. */
+const exactString = (value) => typeof value === "string" && value.length > 0 && value.trim() === value;
+const coverageError = (at, problem) => new Error(`HttpUserRepository: "${at}" ${problem}`);
+/**
+ * The declaration, checked field by field and frozen — the list, each entry
+ * and each claim list — so that neither a later mutation of the caller's list
+ * nor anything in-process holding the repository can widen what the boot
+ * probe accepts. Diagnostics name the option, the entry and the field (a
+ * field NAME an operator wrote wrongly is quoted) — never a value: a
+ * registration's client id is configuration an operator may not want in a
+ * log line.
+ */
+function validateCoverage(value) {
+    if (value === undefined)
+        return Object.freeze([]);
+    if (!Array.isArray(value)) {
+        throw coverageError(COVERAGE_FIELD, "must be a list of registrations");
+    }
+    const seen = new Set();
+    const entries = value.map((entry, index) => {
+        const at = `${COVERAGE_FIELD}[${index}]`;
+        if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+            throw coverageError(at, "must be an object with provider, issuer, clientId and requiredClaims");
+        }
+        for (const key of Object.keys(entry)) {
+            if (!COVERAGE_KEYS.has(key))
+                throw coverageError(at, `has a field it may not have: "${key}"`);
+        }
+        // Own properties only: a field that lives on the entry's prototype is
+        // not one the operator wrote.
+        const own = (field) => Object.hasOwn(entry, field) ? entry[field] : undefined;
+        const provider = own("provider");
+        const issuer = own("issuer");
+        const clientId = own("clientId");
+        const requiredClaims = own("requiredClaims");
+        for (const [field, candidate] of [
+            ["provider", provider],
+            ["issuer", issuer],
+            ["clientId", clientId],
+        ]) {
+            if (!exactString(candidate)) {
+                throw coverageError(`${at}.${field}`, "must be a non-empty string without surrounding whitespace");
+            }
+        }
+        if (!Array.isArray(requiredClaims)) {
+            throw coverageError(`${at}.requiredClaims`, "must be a list of claim names (empty for none)");
+        }
+        const names = new Set();
+        for (const name of requiredClaims) {
+            if (typeof name !== "string" || !CLAIM_NAME.test(name) || FORBIDDEN_CLAIM_NAMES.has(name)) {
+                throw coverageError(`${at}.requiredClaims`, "holds a name that is not a claim name");
+            }
+            if (names.has(name))
+                throw coverageError(`${at}.requiredClaims`, "lists a claim twice");
+            names.add(name);
+        }
+        const key = JSON.stringify([provider, issuer, clientId]);
+        if (seen.has(key))
+            throw coverageError(at, "declares a registration an earlier entry already declares");
+        seen.add(key);
+        return Object.freeze({
+            provider: provider,
+            issuer: issuer,
+            clientId: clientId,
+            requiredClaims: Object.freeze([...names]),
+        });
+    });
+    return Object.freeze(entries);
+}
+/** A lookup answer if it is one the port defines — a fresh object of the contract's fields, nothing else. */
+function lookupAnswer(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return undefined;
+    const answer = value;
+    switch (answer.kind) {
+        case "linked":
+            return typeof answer.subject === "string" && answer.subject.length > 0
+                ? { kind: "linked", subject: answer.subject }
+                : undefined;
+        case "unlinked":
+            return { kind: "unlinked" };
+        case "indeterminate":
+            return answer.reason === "registration_not_covered" ||
+                answer.reason === "identity_not_resolvable"
+                ? { kind: "indeterminate", reason: answer.reason }
+                : undefined;
+        default:
+            return undefined;
+    }
+}
+/**
+ * RFC 6750 §2.1 `b64token` — the characters a bearer credential may carry.
+ * Nothing in it is whitespace or a control character, so a token that
+ * matches cannot break the header it rides in.
+ */
+const B64TOKEN = /^[A-Za-z0-9\-._~+/]+=*$/;
+const BEARER_TOKEN_FIELD = "bearerToken";
+/**
+ * The credential presented to the Store, checked (#285's rule: at
+ * construction, so a deployment that would send an unusable one fails at
+ * boot) and turned into the `Authorization` value; `undefined` when none is
+ * configured, which sends no `Authorization` header at all.
+ *
+ * The shape is refused here and not left to `fetch`: a header value `fetch`
+ * refuses is one it QUOTES in the `TypeError` it throws, on the request path,
+ * where the session routes log what is thrown. The strength is core's
+ * shared-secret floor (`MIN_SECRET_ENTROPY_BYTES`, measured on the decoded
+ * length as `SESSION_SECRET` is): whoever holds this token speaks to the Store
+ * as auth.provider — resolves an identity to its user, links one to any user.
+ * No message quotes the value.
+ */
+function bearerAuthorization(value) {
+    if (value === undefined)
+        return undefined;
+    const refuse = (problem) => new Error(`HttpUserRepository: "${BEARER_TOKEN_FIELD}" ${problem}`);
+    if (typeof value !== "string")
+        throw refuse("must be a string");
+    if (value === "") {
+        throw refuse('must not be empty — HOCON substitutes an exported-but-empty variable as ""; ' +
+            "leave it unset to send no Authorization header");
+    }
+    if (!B64TOKEN.test(value)) {
+        throw refuse("must be a bare RFC 6750 token: letters, digits and - . _ ~ + /, then optional = padding — " +
+            'no whitespace, no line break, and no "Bearer " prefix (the scheme is added)');
+    }
+    const actualBytes = measureSecretEntropyBytes(value);
+    if (actualBytes < MIN_SECRET_ENTROPY_BYTES) {
+        throw new Error(`HttpUserRepository: ${describeWeakSecret(actualBytes, {
+            configKey: "repositories.user.http.bearerToken",
+            envVar: "CLIENT_USER_BEARER_TOKEN",
+        })}`);
+    }
+    return `Bearer ${value}`;
+}
 /** Whether `value` is a positive integer that fits `bound`. */
 function isPositiveIntegerWithin(value, bound) {
     return typeof value === "number" && Number.isInteger(value) && value > 0 && value <= bound;
@@ -81,12 +232,17 @@ function discardBody(res) {
  * before a byte of it is read, but the streaming count is the load-bearing
  * half: a hostile Store simply omits the header (or lies), and chunked transfer
  * encoding has none to omit.
+ *
+ * Everything it throws is the adapter's own: the cap, the deadline's
+ * rejection, or — for a stream that broke mid-read — what `unreadable` makes
+ * of the transport's error, which is never passed on as it is. `endpoint` is
+ * how its messages name the Store: origin and path (`endpointForMessage`).
  */
-async function readBodyCapped(res, limit, url, deadline) {
+async function readBodyCapped(res, limit, endpoint, deadline, unreadable) {
     const declared = Number(res.headers.get("content-length"));
     if (Number.isFinite(declared) && declared > limit) {
         discardBody(res);
-        throw new Error(`HttpUserRepository: upstream ${url} response exceeds the ${limit}-byte cap ` +
+        throw new Error(`HttpUserRepository: upstream ${endpoint} response exceeds the ${limit}-byte cap ` +
             `(Content-Length: ${declared})`);
     }
     if (res.body === null)
@@ -102,12 +258,17 @@ async function readBodyCapped(res, limit, url, deadline) {
             // in flight, which is exactly the slow-loris shape — headers arrive
             // promptly, then the body dribbles or stops. One absolute deadline
             // for the whole exchange, not a fresh one per chunk.
-            const { done, value } = await Promise.race([reader.read(), deadline]);
+            const { done, value } = await Promise.race([
+                reader.read().catch((err) => {
+                    throw unreadable(err);
+                }),
+                deadline,
+            ]);
             if (done)
                 break;
             read += value.byteLength;
             if (read > limit) {
-                throw new Error(`HttpUserRepository: upstream ${url} response exceeds the ${limit}-byte cap`);
+                throw new Error(`HttpUserRepository: upstream ${endpoint} response exceeds the ${limit}-byte cap`);
             }
             text += decoder.decode(value, { stream: true });
         }
@@ -127,8 +288,9 @@ async function readBodyCapped(res, limit, url, deadline) {
  * A deliberately shallow check. An aborted `fetch` rejects with the
  * `AbortError` directly; the wrapping that `fetch` does apply is for network
  * failures, which are not aborts. If some runtime did wrap one, the request
- * still fails — it would simply surface the runtime's message instead of ours,
- * which is a cosmetic difference and not worth an untestable `cause` walk.
+ * still fails — as a `StoreTransportError` ("could not be reached") instead of
+ * a `TimeoutError`, a misnamed failure rather than a missed one, and not worth
+ * an untestable `cause` walk.
  * A stalled *body* is not covered here at all: that is the deadline race in
  * `readBodyCapped`, which does not depend on abort semantics.
  */
@@ -143,31 +305,93 @@ function isAbortError(err) {
  * `UserRepository` backed by "the Store" — the upstream user service defined
  * on core's `User` doc (`@o3co/auth-provider-core`, `src/repositories/types.mts`).
  *
- * Both endpoints receive plaintext user credentials, so both are validated at
- * **construction**: a deployment configured with an `http://` Store URL fails
- * at boot rather than leaking the first user's password (#285). `http://` is
- * accepted for loopback hosts only — see `src/endpointUrl.mts` for the
- * carve-out and its rationale.
+ * Every endpoint receives a plaintext credential or a verified identity, so
+ * each is validated at **construction**: a deployment configured with an
+ * `http://` Store URL fails at boot rather than leaking the first user's
+ * password (#285). `http://` is accepted for loopback hosts only — see
+ * `src/endpointUrl.mts` for the carve-out and its rationale.
+ *
+ * No request follows a redirect, so a URL that passed that check is the only
+ * place its body is ever sent and the only one whose answer is taken: a `3xx`
+ * from the Store is an upstream failure, thrown like any other unexpected
+ * status, and its `Location` is never contacted.
+ *
+ * With `bearerToken` configured, every request — authentication, linking and
+ * the identity lookup alike — carries `Authorization: Bearer <token>`, so the
+ * Store can refuse a caller that is not this deployment; without it, no
+ * request carries an `Authorization` header. The Store says it refused THIS
+ * deployment by answering `401` or `403` with a `Bearer` challenge (RFC 6750
+ * §3), and that answer, while a token was sent, throws a
+ * {@link StoreCredentialRefusedError} on every request — never "no such user"
+ * or a refused link, which is what either status without the challenge still
+ * means.
+ *
+ * A transport's own error is never thrown: undici's parser errors quote the
+ * bytes they rejected, and a peer that reflects the request puts the
+ * `Authorization` header — or a password — there. A request that cannot be
+ * made, or an answer that cannot be read, throws a `StoreTransportError`
+ * (`src/repositories/storeErrors.mts`): a fixed message naming the endpoint
+ * and what failed, at most an allowlisted transport code, no cause.
+ *
+ * Every message names an endpoint by its origin and path alone
+ * (`endpointForMessage`, `src/endpointUrl.mts`): a Store URL may carry a
+ * query string, and a query may carry a credential, while every caller logs
+ * what this throws.
  */
 export class HttpUserRepository {
+    /**
+     * `Bearer <token>`, or `undefined` for none. An ECMAScript private field
+     * rather than a TypeScript `private` one: `inspect()` and `JSON.stringify`
+     * see every other field of a repository handed to a logger, and not this.
+     */
+    #authorization;
     authenticateUrl;
     authenticateByTokenUrl;
     timeout;
     maxResponseBytes;
     linkFederatedIdentityUrl;
+    findSubjectByFederatedIdentityUrl;
+    coverage;
     /**
      * #482 — see {@link UserRepository.linkFederatedIdentity}. Present only when
      * `linkFederatedIdentityUrl` is configured, which is how the federation routes
      * know to refuse `?link=1` up front instead of at the callback.
      */
     linkFederatedIdentity;
-    constructor({ authenticateUrl, authenticateByTokenUrl, linkFederatedIdentityUrl, timeout, maxResponseBytes = DEFAULT_MAX_RESPONSE_BYTES, }) {
+    /**
+     * #613 — see {@link UserRepository.supportsFederatedIdentityLookup}. Present
+     * together with the lookup, only when `findSubjectByFederatedIdentityUrl` is
+     * configured: absent, a deployment that requires the lookup is refused at
+     * boot by the method's name, which is the message that says what to set.
+     * Answers from the declaration alone — the Store is not asked at boot.
+     */
+    supportsFederatedIdentityLookup;
+    /** #613 — see {@link UserRepository.findSubjectByFederatedIdentity}. Present with the probe. */
+    findSubjectByFederatedIdentity;
+    constructor({ authenticateUrl, authenticateByTokenUrl, linkFederatedIdentityUrl, findSubjectByFederatedIdentityUrl, federatedIdentityLookupCoverage, bearerToken, timeout, maxResponseBytes = DEFAULT_MAX_RESPONSE_BYTES, }) {
         this.authenticateUrl = assertSecureEndpoint(authenticateUrl, "authenticateUrl");
         this.authenticateByTokenUrl = assertSecureEndpoint(authenticateByTokenUrl, "authenticateByTokenUrl");
+        this.#authorization = bearerAuthorization(bearerToken);
         if (linkFederatedIdentityUrl !== undefined) {
             this.linkFederatedIdentityUrl = assertSecureEndpoint(linkFederatedIdentityUrl, "linkFederatedIdentityUrl");
             this.linkFederatedIdentity = (userId, identity) => this.linkViaHttp(userId, identity);
         }
+        this.coverage = validateCoverage(federatedIdentityLookupCoverage);
+        if (findSubjectByFederatedIdentityUrl !== undefined) {
+            this.findSubjectByFederatedIdentityUrl = assertSecureEndpoint(findSubjectByFederatedIdentityUrl, "findSubjectByFederatedIdentityUrl");
+            this.supportsFederatedIdentityLookup = (registration, identityClaims) => 
+            // A list, as the port types it: `includes` on a string would match
+            // a substring, and a caller that is not the boot probe may hand
+            // over anything.
+            Array.isArray(identityClaims) &&
+                (this.declared(registration)?.requiredClaims.every((name) => identityClaims.includes(name)) ??
+                    false);
+            this.findSubjectByFederatedIdentity = (identity) => this.lookupViaHttp(identity);
+        }
+        else if (this.coverage.length > 0) {
+            throw new Error(`HttpUserRepository: "${COVERAGE_FIELD}" declares what the Store's lookup covers, and no ` +
+                '"findSubjectByFederatedIdentityUrl" names that lookup — set the URL, or remove the declaration');
+        }
         if (!isPositiveIntegerWithin(timeout, MAX_TIMEOUT_MS)) {
             throw new Error(`HttpUserRepository: "timeout" must be a positive integer no greater than ` +
                 `${MAX_TIMEOUT_MS} milliseconds`);
@@ -178,6 +402,29 @@ export class HttpUserRepository {
         }
         this.maxResponseBytes = maxResponseBytes;
     }
+    /** What every request carries: the body's type and, when configured, the credential. */
+    headers() {
+        return this.#authorization === undefined
+            ? { "Content-Type": "application/json" }
+            : { "Content-Type": "application/json", Authorization: this.#authorization };
+    }
+    /**
+     * Throws {@link StoreCredentialRefusedError} when a non-`2xx` answer is the
+     * Store refusing this deployment's credential: a `401` or `403` with a
+     * `Bearer` challenge, to a request that carried the token. Read before any
+     * other reading of the status — without it a token the Store does not
+     * accept is every login "no such user" and every link "refused", with
+     * nothing logged. Without a token sent, a challenge is not about one, and a
+     * Store whose stack challenges every refusal keeps the wire meaning it has
+     * always had.
+     */
+    assertCredentialAccepted(res, endpoint) {
+        if (this.#authorization !== undefined &&
+            (res.status === 401 || res.status === 403) &&
+            hasBearerChallenge(res.headers.get("www-authenticate"))) {
+            throw new StoreCredentialRefusedError(endpoint, res.status);
+        }
+    }
     async authenticate(username, password) {
         // Without `acceptConflict` the sentinel is never produced — a 409 throws.
         return this.post(this.authenticateUrl, { email: username, password });
@@ -200,7 +447,129 @@ export class HttpUserRepository {
             return { ok: false, reason: "refused" };
         return { ok: true, user: answer };
     }
+    /** The declaration for a registration, if the operator made one. Exact on all three. */
+    declared(registration) {
+        return this.coverage.find((entry) => entry.provider === registration.provider &&
+            entry.issuer === registration.issuer &&
+            entry.clientId === registration.clientId);
+    }
+    /**
+     * POST `{ provider, issuer, clientId, sub, claims }` to the Store's lookup
+     * (#613) and read one of the port's three answers. Answered locally, with
+     * no request, where the declaration already decides: a registration nobody
+     * declared is `registration_not_covered`, and a declared one arriving
+     * without a claim its strategy needs is `identity_not_resolvable`. Every
+     * claim the connection supplied is sent, not only the required ones: what
+     * the Store matches on is the Store's business.
+     */
+    async lookupViaHttp(identity) {
+        const entry = this.declared(identity);
+        if (entry === undefined)
+            return { kind: "indeterminate", reason: "registration_not_covered" };
+        for (const name of entry.requiredClaims) {
+            const value = Object.hasOwn(identity.claims, name) ? identity.claims[name] : undefined;
+            if (typeof value !== "string" || value.length === 0) {
+                return { kind: "indeterminate", reason: "identity_not_resolvable" };
+            }
+        }
+        return this.postLookup(this.findSubjectByFederatedIdentityUrl, {
+            provider: identity.provider,
+            issuer: identity.issuer,
+            clientId: identity.clientId,
+            sub: identity.sub,
+            claims: { ...identity.claims },
+        });
+    }
+    /**
+     * The lookup's transport: the same deadline, cap and abort as {@link post},
+     * and like it never follows a redirect — the body carries a verified
+     * identity, and a `Location` is not a configured endpoint. None of
+     * {@link post}'s readings, though. A `401`/`403` is not "nobody", a `409` is
+     * not a conflict, a `404` is not an absence: only a `2xx` carrying one of the
+     * three answers is an answer, and everything else throws — as an outage,
+     * which is what a lookup that could not be made is — a `401` or `403` with a
+     * `Bearer` challenge, to a request that carried the token, as the refused
+     * credential it is. What is thrown names the endpoint by origin and path — and, for an answer
+     * with a status, the status; for a transport failure, at most its code — and
+     * never the body, the identity, a status text or an underlying cause.
+     */
+    async postLookup(url, body) {
+        // What every message names: origin and path, never the query.
+        const endpoint = endpointForMessage(url);
+        const controller = new AbortController();
+        let timedOut = false;
+        const timeoutError = () => {
+            const error = new Error(`HttpUserRepository: request to ${endpoint} timed out after ${this.timeout}ms`);
+            error.name = "TimeoutError";
+            return error;
+        };
+        let fireDeadline = () => { };
+        const deadline = new Promise((_resolve, reject) => {
+            fireDeadline = () => reject(timeoutError());
+        });
+        deadline.catch(() => { });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+            fireDeadline();
+        }, this.timeout);
+        try {
+            let res;
+            try {
+                res = await fetch(url, {
+                    method: "POST",
+                    headers: this.headers(),
+                    body: JSON.stringify(body),
+                    signal: controller.signal,
+                    redirect: "manual",
+                });
+            }
+            catch (err) {
+                if (timedOut && isAbortError(err))
+                    throw timeoutError();
+                // A fixed message, without the cause: what a transport reports may
+                // quote what it was sending.
+                throw requestFailure(err, {
+                    unreachable: `HttpUserRepository: identity lookup at ${endpoint} could not be reached`,
+                    closed: `HttpUserRepository: identity lookup at ${endpoint}: the connection closed before a complete response arrived`,
+                    malformed: `HttpUserRepository: identity lookup at ${endpoint} answered with a malformed HTTP response`,
+                });
+            }
+            if (!res.ok) {
+                discardBody(res);
+                this.assertCredentialAccepted(res, endpoint);
+                throw new Error(`HttpUserRepository: identity lookup at ${endpoint} answered HTTP ${res.status}`);
+            }
+            let raw;
+            try {
+                raw = await readBodyCapped(res, this.maxResponseBytes, endpoint, deadline, (err) => readFailure(err, `HttpUserRepository: identity lookup at ${endpoint} could not be read`));
+            }
+            catch (err) {
+                if (timedOut)
+                    throw timeoutError();
+                throw err;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                throw new Error(`HttpUserRepository: upstream ${endpoint} returned a non-JSON body`);
+            }
+            const answer = lookupAnswer(parsed);
+            if (answer === undefined) {
+                throw new Error(`HttpUserRepository: identity lookup at ${endpoint} answered a body that is not one of the ` +
+                    "port's answers (linked / unlinked / indeterminate)");
+            }
+            return answer;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
     async post(url, body, options = {}) {
+        // What every message names: origin and path, never the query.
+        const endpoint = endpointForMessage(url);
         const controller = new AbortController();
         let timedOut = false;
         // One absolute deadline for the whole exchange, expressed twice: as the
@@ -208,9 +577,17 @@ export class HttpUserRepository {
         // raced against. `.catch` is attached up front so an exchange that
         // finishes first — the overwhelmingly common case, where the timer is
         // cleared and this never rejects — cannot leave an unhandled rejection.
+        // Named as the lookup's is: a reporter that classifies by `name` —
+        // federation-grants' reads `TimeoutError` as `timeout` — sees one kind
+        // of timeout whichever request it came from.
+        const timeoutError = () => {
+            const error = new Error(`HttpUserRepository: request to ${endpoint} timed out after ${this.timeout}ms`);
+            error.name = "TimeoutError";
+            return error;
+        };
         let fireDeadline = () => { };
         const deadline = new Promise((_resolve, reject) => {
-            fireDeadline = () => reject(new Error(`HttpUserRepository: request to ${url} timed out after ${this.timeout}ms`));
+            fireDeadline = () => reject(timeoutError());
         });
         deadline.catch(() => { });
         const timer = setTimeout(() => {
@@ -219,14 +596,46 @@ export class HttpUserRepository {
             fireDeadline();
         }, this.timeout);
         try {
-            const res = await fetch(url, {
-                method: "POST",
-                headers: { "Content-Type": "application/json" },
-                body: JSON.stringify(body),
-                signal: controller.signal,
-            });
+            let res;
+            try {
+                res = await fetch(url, {
+                    method: "POST",
+                    headers: this.headers(),
+                    body: JSON.stringify(body),
+                    signal: controller.signal,
+                    // Never followed: a 307 or 308 would re-send the body — a
+                    // password, a token, a link request — to a `Location` the https
+                    // rule never checked, and after any redirect the answer from
+                    // there would be taken as the user. Node's fetch hands the 3xx
+                    // back as it is (a browser-spec runtime would hand back an opaque
+                    // redirect, status 0); either way it is not a 2xx, 401, 403 or
+                    // 409, so it throws below as an unexpected status.
+                    redirect: "manual",
+                });
+            }
+            catch (err) {
+                if (timedOut && isAbortError(err))
+                    throw timeoutError();
+                // Never the transport's own error: it may quote what it was
+                // sending — the credential, the password — or what came back.
+                throw requestFailure(err, {
+                    unreachable: `HttpUserRepository: request to ${endpoint} could not be reached`,
+                    closed: `HttpUserRepository: the connection to ${endpoint} closed before a complete response arrived`,
+                    malformed: `HttpUserRepository: the Store at ${endpoint} answered with a malformed HTTP response`,
+                });
+            }
             if (res.ok) {
-                const raw = await readBodyCapped(res, this.maxResponseBytes, url, deadline);
+                let raw;
+                try {
+                    raw = await readBodyCapped(res, this.maxResponseBytes, endpoint, deadline, (err) => readFailure(err, `HttpUserRepository: response from ${endpoint} could not be read`));
+                }
+                catch (err) {
+                    // Whatever the deadline interrupted is a timeout; everything
+                    // else readBodyCapped throws is already the adapter's own.
+                    if (timedOut)
+                        throw timeoutError();
+                    throw err;
+                }
                 let parsed;
                 try {
                     parsed = JSON.parse(raw);
@@ -235,31 +644,26 @@ export class HttpUserRepository {
                     // Same class of failure as the shape check below: the Store is
                     // broken, not the credential. Reported as ours rather than as a
                     // bare SyntaxError with no indication of where it came from.
-                    throw new Error(`HttpUserRepository: upstream ${url} returned a non-JSON body`);
+                    throw new Error(`HttpUserRepository: upstream ${endpoint} returned a non-JSON body`);
                 }
                 if (!isUser(parsed)) {
                     // Upstream returned 2xx with an unexpected shape — this is an
                     // "upstream is broken" case, not a "user not found" case, so
                     // throw rather than return null. The thrown error propagates
                     // as a 500 to the client (correct: upstream-service failure).
-                    throw new Error(`HttpUserRepository: upstream ${url} returned an invalid User shape`);
+                    throw new Error(`HttpUserRepository: upstream ${endpoint} returned an invalid User shape`);
                 }
                 return parsed;
             }
             discardBody(res);
+            this.assertCredentialAccepted(res, endpoint);
             if (options.acceptConflict && res.status === 409) {
                 return CONFLICT;
             }
             if (res.status === 401 || res.status === 403) {
                 return null;
             }
-            throw new Error(`Unexpected HTTP status ${res.status} from ${url}`);
-        }
-        catch (err) {
-            if (timedOut && isAbortError(err)) {
-                throw new Error(`HttpUserRepository: request to ${url} timed out after ${this.timeout}ms`);
-            }
-            throw err;
+            throw new Error(`Unexpected HTTP status ${res.status} from ${endpoint}`);
         }
         finally {
             clearTimeout(timer);

package/dist/repositories/storeErrors.d.mts

@@ -0,0 +1,81 @@
+/**
+ * The Store refused the credential this deployment presented: a `401` or a
+ * `403` carrying a `Bearer` challenge (RFC 6750 §3 — `invalid_token`,
+ * `insufficient_scope`) to a request that sent `bearerToken`. An outage, not
+ * an answer about the user: thrown, so every caller answers it as it answers
+ * any Store failure.
+ *
+ * `name` is part of the contract. A caller that does not depend on this
+ * package recognises the refusal by it — an operator reading the
+ * federation-grants callback's `federation_grant_callback_unavailable` line
+ * finds it as the projected error's `name`. The message names the endpoint —
+ * its origin and path, never a query or fragment, however it is handed one —
+ * the status and the option to check; never the token, and nothing the Store
+ * wrote.
+ *
+ * The Store's status is `storeStatus`, never `status` or `statusCode`: those
+ * are what Express's finalhandler, http-errors and the standalone's terminal
+ * handler read as the status to ANSWER with, and a 4xx there is taken for a
+ * client error — the Store's 401 would reach the browser as its own, and go
+ * unlogged.
+ */
+export declare class StoreCredentialRefusedError extends Error {
+    readonly storeStatus: 401 | 403;
+    constructor(url: string, status: 401 | 403);
+}
+/** What went wrong with the exchange, when it was not the Store's answer. */
+export type StoreTransportFailure = 
+/**
+ * No connection to exchange on: refused, DNS, TLS, a route or host the
+ * network cannot reach. The network path, or TLS to the Store.
+ */
+"unreachable"
+/**
+ * A connection that closed — or was 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, so this says no
+ * more than that; it is not the network path, and not a malformed answer.
+ */
+ | "connection_closed"
+/**
+ * The Store (or whatever answers at the URL) 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.
+ */
+ | "malformed_response"
+/** An HTTP answer arrived, and its body broke before it was read. */
+ | "unreadable";
+/**
+ * The Store could not be reached, or what it answered could not be read — a
+ * transport failure rather than an answer. Thrown so every caller answers it
+ * as it answers any Store failure; `name` is part of the contract (the
+ * federation-grants callback's outage line carries it as the projected
+ * error's `name`), as are `reason` and `code`.
+ *
+ * Built only from what an operator can act on: a fixed message naming the
+ * endpoint and the failure, and `code` — a transport code from the allowlist
+ * below, when there is one. Never a `cause`: the transport's own error may
+ * quote what was sent or received. And no `status` (see
+ * {@link StoreCredentialRefusedError}).
+ */
+export declare class StoreTransportError extends Error {
+    readonly reason: StoreTransportFailure;
+    readonly code: string | undefined;
+    constructor(message: string, reason: StoreTransportFailure, code?: string);
+}
+/** The first allowlisted `code` on `err` or its causes. */
+export declare function transportCode(err: unknown): string | undefined;
+/**
+ * A request that failed before a response could be taken, as its reason's
+ * message — `unreachable`, `closed` or `malformed` — with the code, when
+ * there is one. Only `unreachable` points an operator at the network.
+ */
+export declare function requestFailure(err: unknown, messages: {
+    readonly unreachable: string;
+    readonly closed: string;
+    readonly malformed: string;
+}): StoreTransportError;
+/** An answer whose body broke before it was read. */
+export declare function readFailure(err: unknown, message: string): StoreTransportError;
+//# sourceMappingURL=storeErrors.d.mts.map

package/dist/repositories/storeErrors.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storeErrors.d.mts","sourceRoot":"","sources":["../../src/repositories/storeErrors.mts"],"names":[],"mappings":"AA0BA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;IACrD,QAAQ,CAAC,WAAW,EAAE,GAAG,GAAG,GAAG,CAAC;gBAEpB,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,GAAG,GAAG;CAS1C;AAED,6EAA6E;AAC7E,MAAM,MAAM,qBAAqB;AAChC;;;GAGG;AACD,aAAa;AACf;;;;;;GAMG;GACD,mBAAmB;AACrB;;;;GAIG;GACD,oBAAoB;AACtB,qEAAqE;GACnE,YAAY,CAAC;AAEhB;;;;;;;;;;;;GAYG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;gBAEtB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,qBAAqB,EAAE,IAAI,CAAC,EAAE,MAAM;CAMzE;AA4DD,2DAA2D;AAC3D,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAW9D;AAwCD;;;;GAIG;AACH,wBAAgB,cAAc,CAC7B,GAAG,EAAE,OAAO,EACZ,QAAQ,EAAE;IACT,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC3B,GACC,mBAAmB,CAUrB;AAED,qDAAqD;AACrD,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,mBAAmB,CAG9E"}