@o3co/auth-provider-foundation 0.14.0 → 0.16.0

package/dist/repositories/HttpUserRepository.d.mts

@@ -1,4 +1,4 @@
-import type { FederatedIdentityLink, 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.
  *
@@ -7,36 +7,114 @@ import type { FederatedIdentityLink, LinkFederatedIdentityResult, User, UserRepo
  * process out of memory one login at a time (#285).
  */
 export declare const DEFAULT_MAX_RESPONSE_BYTES: number;
+/**
+ * What the Store declares it can place (#613): identities issued under one
+ * registration — the federation's name, the issuer and the client, exactly as
+ * a federation-grant connection is configured — given at least these claims
+ * from the verified id_token. The synchronous probe D7 check 5 asks at boot
+ * cannot reach the Store, so the operator relays the Store's own claim here;
+ * boot then holds every connection to it. `requiredClaims = []` is a strategy
+ * on the registration and the `sub` alone.
+ */
+export interface FederatedIdentityLookupCoverage {
+    readonly provider: string;
+    readonly issuer: string;
+    readonly clientId: string;
+    readonly requiredClaims: readonly string[];
+}
 /**
  * `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;
     private maxResponseBytes;
     private linkFederatedIdentityUrl?;
+    private findSubjectByFederatedIdentityUrl?;
+    private readonly 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.
      */
     readonly linkFederatedIdentity?: (userId: string, identity: FederatedIdentityLink) => Promise<LinkFederatedIdentityResult>;
-    constructor({ authenticateUrl, authenticateByTokenUrl, linkFederatedIdentityUrl, timeout, maxResponseBytes, }: {
+    /**
+     * #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.
+     */
+    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, bearerToken, timeout, maxResponseBytes, }: {
         authenticateUrl: string;
         authenticateByTokenUrl: string;
         /** #482: optional; the Store's link endpoint. Same https rule as the other two. */
         linkFederatedIdentityUrl?: string;
+        /** #613: optional; the Store's identity lookup. Same https rule; carries a verified identity. */
+        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>;
     /**
@@ -46,6 +124,32 @@ export declare class HttpUserRepository implements UserRepository {
      * provider, …); `409` says the identity is already someone else's.
      */
     private linkViaHttp;
+    /** The declaration for a registration, if the operator made one. Exact on all three. */
+    private declared;
+    /**
+     * 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.
+     */
+    private lookupViaHttp;
+    /**
+     * 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.
+     */
+    private postLookup;
     private post;
 }
 //# sourceMappingURL=HttpUserRepository.d.mts.map

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,2BAA2B,EAC3B,IAAI,EACJ,cAAc,EACd,MAAM,0BAA0B,CAAC;AAMlC;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,QAAc,CAAC;AAkItD;;;;;;;;;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;;;;OAIG;IACH,QAAQ,CAAC,qBAAqB,CAAC,EAAE,CAChC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,qBAAqB,KAC3B,OAAO,CAAC,2BAA2B,CAAC,CAAC;gBAE9B,EACX,eAAe,EACf,sBAAsB,EACtB,wBAAwB,EACxB,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,OAAO,EAAE,MAAM,CAAC;QAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;KAC1B;IA4BK,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;YAWX,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"}