@o3co/auth-provider-foundation 0.15.0 → 0.16.0

package/dist/repositories/HttpUserRepository.d.mts

@@ -1,4 +1,4 @@
-import type { FederatedIdentityLink, FederatedIdentityLookup, FederatedIdentityLookupResult, FederatedIdentityRegistration, LinkFederatedIdentityResult, User, UserRepository } from "@o3co/auth-provider-core";
+import { type FederatedIdentityLink, type FederatedIdentityLookup, type FederatedIdentityLookupResult, type FederatedIdentityRegistration, type LinkFederatedIdentityResult, type User, type UserRepository } from "@o3co/auth-provider-core";
 /**
  * Default ceiling on an upstream response body, in bytes.
  *
@@ -26,13 +26,41 @@ export interface FederatedIdentityLookupCoverage {
  * `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 declare class HttpUserRepository implements UserRepository {
+    #private;
     private authenticateUrl;
     private authenticateByTokenUrl;
     private timeout;
@@ -56,7 +84,7 @@ export declare class HttpUserRepository implements UserRepository {
     readonly supportsFederatedIdentityLookup?: (registration: FederatedIdentityRegistration, identityClaims: readonly string[]) => boolean;
     /** #613 — see {@link UserRepository.findSubjectByFederatedIdentity}. Present with the probe. */
     readonly findSubjectByFederatedIdentity?: (identity: FederatedIdentityLookup) => Promise<FederatedIdentityLookupResult>;
-    constructor({ authenticateUrl, authenticateByTokenUrl, linkFederatedIdentityUrl, findSubjectByFederatedIdentityUrl, federatedIdentityLookupCoverage, timeout, maxResponseBytes, }: {
+    constructor({ authenticateUrl, authenticateByTokenUrl, linkFederatedIdentityUrl, findSubjectByFederatedIdentityUrl, federatedIdentityLookupCoverage, bearerToken, timeout, maxResponseBytes, }: {
         authenticateUrl: string;
         authenticateByTokenUrl: string;
         /** #482: optional; the Store's link endpoint. Same https rule as the other two. */
@@ -65,9 +93,28 @@ export declare class HttpUserRepository implements UserRepository {
         findSubjectByFederatedIdentityUrl?: string;
         /** #613: which registrations the Store's lookup covers. Needs the URL; `[]` covers none. */
         federatedIdentityLookupCoverage?: readonly FederatedIdentityLookupCoverage[];
+        /**
+         * Optional; sent to the Store on every request as `Authorization: Bearer
+         * <token>`. A bare RFC 6750 token (no scheme) of at least
+         * `MIN_SECRET_ENTROPY_BYTES` of key material — `openssl rand -hex 32`.
+         */
+        bearerToken?: string;
         timeout: number;
         maxResponseBytes?: number;
     });
+    /** What every request carries: the body's type and, when configured, the credential. */
+    private headers;
+    /**
+     * 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.
+     */
+    private assertCredentialAccepted;
     authenticate(username: string, password: string): Promise<User | null>;
     authenticateByToken(token: string): Promise<User | null>;
     /**
@@ -91,14 +138,16 @@ export declare class HttpUserRepository implements UserRepository {
     private lookupViaHttp;
     /**
      * The lookup's transport: the same deadline, cap and abort as {@link post},
-     * and none of its readings. 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
+     * 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. Redirects are never
-     * followed: the body carries a verified identity, and a `Location` is not a
-     * configured endpoint. What is thrown names the endpoint — and, for an
-     * answer with a status, the status — and never the body, the identity, a
-     * status text or an underlying cause.
+     * 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.
      */
     private postLookup;
     private post;

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

@@ -1 +1 @@
-{"version":3,"file":"HttpUserRepository.d.mts","sourceRoot":"","sources":["../../src/repositories/HttpUserRepository.mts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EACX,qBAAqB,EACrB,uBAAuB,EACvB,6BAA6B,EAC7B,6BAA6B,EAC7B,2BAA2B,EAC3B,IAAI,EACJ,cAAc,EACd,MAAM,0BAA0B,CAAC;AAMlC;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,QAAc,CAAC;AA8BtD;;;;;;;;GAQG;AACH,MAAM,WAAW,+BAA+B;IAC/C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3C;AA4ND;;;;;;;;;GASG;AACH,qBAAa,kBAAmB,YAAW,cAAc;IACxD,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,sBAAsB,CAAS;IACvC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,wBAAwB,CAAC,CAAS;IAC1C,OAAO,CAAC,iCAAiC,CAAC,CAAS;IACnD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6C;IACtE;;;;OAIG;IACH,QAAQ,CAAC,qBAAqB,CAAC,EAAE,CAChC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,qBAAqB,KAC3B,OAAO,CAAC,2BAA2B,CAAC,CAAC;IAC1C;;;;;;OAMG;IACH,QAAQ,CAAC,+BAA+B,CAAC,EAAE,CAC1C,YAAY,EAAE,6BAA6B,EAC3C,cAAc,EAAE,SAAS,MAAM,EAAE,KAC7B,OAAO,CAAC;IACb,gGAAgG;IAChG,QAAQ,CAAC,8BAA8B,CAAC,EAAE,CACzC,QAAQ,EAAE,uBAAuB,KAC7B,OAAO,CAAC,6BAA6B,CAAC,CAAC;gBAEhC,EACX,eAAe,EACf,sBAAsB,EACtB,wBAAwB,EACxB,iCAAiC,EACjC,+BAA+B,EAC/B,OAAO,EACP,gBAA6C,GAC7C,EAAE;QACF,eAAe,EAAE,MAAM,CAAC;QACxB,sBAAsB,EAAE,MAAM,CAAC;QAC/B,mFAAmF;QACnF,wBAAwB,CAAC,EAAE,MAAM,CAAC;QAClC,iGAAiG;QACjG,iCAAiC,CAAC,EAAE,MAAM,CAAC;QAC3C,4FAA4F;QAC5F,+BAA+B,CAAC,EAAE,SAAS,+BAA+B,EAAE,CAAC;QAC7E,OAAO,EAAE,MAAM,CAAC;QAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;KAC1B;IAkDK,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IAKtE,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IAI9D;;;;;OAKG;YACW,WAAW;IAWzB,wFAAwF;IACxF,OAAO,CAAC,QAAQ;IAWhB;;;;;;;;OAQG;YACW,aAAa;IAoB3B;;;;;;;;;;OAUG;YACW,UAAU;YAsEV,IAAI;CA4ElB"}
+{"version":3,"file":"HttpUserRepository.d.mts","sourceRoot":"","sources":["../../src/repositories/HttpUserRepository.mts"],"names":[],"mappings":"AAgBA,OAAO,EAEN,KAAK,qBAAqB,EAC1B,KAAK,uBAAuB,EAC5B,KAAK,6BAA6B,EAClC,KAAK,6BAA6B,EAClC,KAAK,2BAA2B,EAGhC,KAAK,IAAI,EACT,KAAK,cAAc,EACnB,MAAM,0BAA0B,CAAC;AAQlC;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,QAAc,CAAC;AA8BtD;;;;;;;;GAQG;AACH,MAAM,WAAW,+BAA+B;IAC/C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3C;AA4RD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,qBAAa,kBAAmB,YAAW,cAAc;;IAOxD,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,sBAAsB,CAAS;IACvC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,wBAAwB,CAAC,CAAS;IAC1C,OAAO,CAAC,iCAAiC,CAAC,CAAS;IACnD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6C;IACtE;;;;OAIG;IACH,QAAQ,CAAC,qBAAqB,CAAC,EAAE,CAChC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,qBAAqB,KAC3B,OAAO,CAAC,2BAA2B,CAAC,CAAC;IAC1C;;;;;;OAMG;IACH,QAAQ,CAAC,+BAA+B,CAAC,EAAE,CAC1C,YAAY,EAAE,6BAA6B,EAC3C,cAAc,EAAE,SAAS,MAAM,EAAE,KAC7B,OAAO,CAAC;IACb,gGAAgG;IAChG,QAAQ,CAAC,8BAA8B,CAAC,EAAE,CACzC,QAAQ,EAAE,uBAAuB,KAC7B,OAAO,CAAC,6BAA6B,CAAC,CAAC;gBAEhC,EACX,eAAe,EACf,sBAAsB,EACtB,wBAAwB,EACxB,iCAAiC,EACjC,+BAA+B,EAC/B,WAAW,EACX,OAAO,EACP,gBAA6C,GAC7C,EAAE;QACF,eAAe,EAAE,MAAM,CAAC;QACxB,sBAAsB,EAAE,MAAM,CAAC;QAC/B,mFAAmF;QACnF,wBAAwB,CAAC,EAAE,MAAM,CAAC;QAClC,iGAAiG;QACjG,iCAAiC,CAAC,EAAE,MAAM,CAAC;QAC3C,4FAA4F;QAC5F,+BAA+B,CAAC,EAAE,SAAS,+BAA+B,EAAE,CAAC;QAC7E;;;;WAIG;QACH,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,OAAO,EAAE,MAAM,CAAC;QAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;KAC1B;IAmDD,wFAAwF;IACxF,OAAO,CAAC,OAAO;IAMf;;;;;;;;;OASG;IACH,OAAO,CAAC,wBAAwB;IAU1B,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IAKtE,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IAI9D;;;;;OAKG;YACW,WAAW;IAWzB,wFAAwF;IACxF,OAAO,CAAC,QAAQ;IAWhB;;;;;;;;OAQG;YACW,aAAa;IAoB3B;;;;;;;;;;;;OAYG;YACW,UAAU;YA8EV,IAAI;CAiHlB"}

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");
 /**
@@ -155,6 +158,50 @@ function lookupAnswer(value) {
             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;
@@ -185,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)
@@ -206,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 });
         }
@@ -231,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.
  */
@@ -247,13 +305,46 @@ 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;
@@ -277,9 +368,10 @@ export class HttpUserRepository {
     supportsFederatedIdentityLookup;
     /** #613 — see {@link UserRepository.findSubjectByFederatedIdentity}. Present with the probe. */
     findSubjectByFederatedIdentity;
-    constructor({ authenticateUrl, authenticateByTokenUrl, linkFederatedIdentityUrl, findSubjectByFederatedIdentityUrl, federatedIdentityLookupCoverage, timeout, maxResponseBytes = DEFAULT_MAX_RESPONSE_BYTES, }) {
+    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);
@@ -310,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 });
@@ -367,20 +482,24 @@ export class HttpUserRepository {
     }
     /**
      * The lookup's transport: the same deadline, cap and abort as {@link post},
-     * and none of its readings. 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
+     * 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. Redirects are never
-     * followed: the body carries a verified identity, and a `Location` is not a
-     * configured endpoint. What is thrown names the endpoint — and, for an
-     * answer with a status, the status — and never the body, the identity, a
-     * status text or an underlying cause.
+     * 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 ${url} timed out after ${this.timeout}ms`);
+            const error = new Error(`HttpUserRepository: request to ${endpoint} timed out after ${this.timeout}ms`);
             error.name = "TimeoutError";
             return error;
         };
@@ -399,7 +518,7 @@ export class HttpUserRepository {
             try {
                 res = await fetch(url, {
                     method: "POST",
-                    headers: { "Content-Type": "application/json" },
+                    headers: this.headers(),
                     body: JSON.stringify(body),
                     signal: controller.signal,
                     redirect: "manual",
@@ -410,33 +529,36 @@ export class HttpUserRepository {
                     throw timeoutError();
                 // A fixed message, without the cause: what a transport reports may
                 // quote what it was sending.
-                throw new Error(`HttpUserRepository: identity lookup at ${url} could not be reached`);
+                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);
-                throw new Error(`HttpUserRepository: identity lookup at ${url} answered HTTP ${res.status}`);
+                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, url, deadline);
+                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();
-                if (err instanceof Error && err.message.startsWith("HttpUserRepository:"))
-                    throw err;
-                throw new Error(`HttpUserRepository: identity lookup at ${url} could not be read`);
+                throw err;
             }
             let parsed;
             try {
                 parsed = JSON.parse(raw);
             }
             catch {
-                throw new Error(`HttpUserRepository: upstream ${url} returned a non-JSON body`);
+                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 ${url} answered a body that is not one of the ` +
+                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;
@@ -446,6 +568,8 @@ export class HttpUserRepository {
         }
     }
     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
@@ -453,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(() => {
@@ -464,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);
@@ -480,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"}