@o3co/auth-provider-foundation 0.14.0 → 0.15.0

package/README.md

@@ -41,6 +41,8 @@ class HttpUserRepository implements UserRepository {
     authenticateUrl: string;        // POST endpoint for username/password auth
     authenticateByTokenUrl: string; // POST endpoint for token-based auth
     linkFederatedIdentityUrl?: string; // POST endpoint that links a federated identity (#482)
+    findSubjectByFederatedIdentityUrl?: string; // POST endpoint that says who holds an upstream identity (#613)
+    federatedIdentityLookupCoverage?: FederatedIdentityLookupCoverage[]; // what that lookup covers (#613)
     timeout: number;                // request timeout in milliseconds
     maxResponseBytes?: number;      // response body cap, default 1 MiB
   });
@@ -54,9 +56,18 @@ class HttpUserRepository implements UserRepository {
   // POST linkFederatedIdentityUrl with body: { userId, provider, sub, token, claims }
   // — present only when the URL is configured (#482)
   linkFederatedIdentity?(userId: string, identity: FederatedIdentityLink): Promise<LinkFederatedIdentityResult>;
+
+  // From the coverage declaration alone; the Store is not asked (#613).
+  // Present together with the lookup, only when its URL is configured.
+  supportsFederatedIdentityLookup?(registration: { provider, issuer, clientId }, identityClaims: string[]): boolean;
+
+  // POST findSubjectByFederatedIdentityUrl with body: { provider, issuer, clientId, sub, claims }
+  findSubjectByFederatedIdentity?(identity: FederatedIdentityLookup): Promise<FederatedIdentityLookupResult>;
 }
 ```
 
+For `authenticate` and `authenticateByToken`:
+
 - Returns `null` on HTTP 401 or 403.
 - Throws an error on any other non-OK HTTP status.
 - Throws when the upstream returns 2xx with a body that is not a JSON `User`
@@ -71,13 +82,78 @@ class HttpUserRepository implements UserRepository {
   e-mail alone — is in the
   [session package README](../session/README.md#account-linking-across-federations-482).
 
+#### The identity lookup (#613)
+
+What a federation-grant deployment (`@o3co/auth-provider-federation-grants`,
+D7 check 5) asks of the Store: who holds an upstream identity, so that a
+delegation is refused when the account belongs to another local user. The
+Store answers about ownership across **every** registration of the IdP, not
+only the one the identity came through — a login links under the federation
+the user signed in through, and an IdP whose `sub` is pairwise per app
+registration (Entra's is) gives the same person another `sub` under each. For
+D19's separate grants registration, that means: to answer `unlinked`
+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>" } }
+```
+
+— the registration exactly as the connection is configured, the verified
+`sub`, and every claim the connection's `identityClaims` named (verified,
+from the id_token; `{}` when it named none). The lookup must change nothing:
+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`; the grants module refuses at
+boot every connection it is `false` for. 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.
+
 ### 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.
 

package/dist/index.d.mts

@@ -2,5 +2,5 @@ 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";
 //# 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,IAqCH,CAAC;AAEF,OAAO,EACN,0BAA0B,EAC1B,KAAK,+BAA+B,EACpC,kBAAkB,GAClB,MAAM,uCAAuC,CAAC"}

package/dist/index.mjs

@@ -56,6 +56,20 @@ 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,
+                }
+                : {}),
             timeout: toNumber(config.timeout, DEFAULT_TIMEOUT_MS),
             maxResponseBytes: toNumber(config.maxResponseBytes, DEFAULT_MAX_RESPONSE_BYTES),
         });

package/dist/repositories/HttpUserRepository.d.mts

@@ -1,4 +1,4 @@
-import type { FederatedIdentityLink, LinkFederatedIdentityResult, User, UserRepository } from "@o3co/auth-provider-core";
+import type { FederatedIdentityLink, FederatedIdentityLookup, FederatedIdentityLookupResult, FederatedIdentityRegistration, LinkFederatedIdentityResult, User, UserRepository } from "@o3co/auth-provider-core";
 /**
  * Default ceiling on an upstream response body, in bytes.
  *
@@ -7,6 +7,21 @@ 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`).
@@ -23,17 +38,33 @@ export declare class HttpUserRepository implements UserRepository {
     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, 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[];
         timeout: number;
         maxResponseBytes?: number;
     });
@@ -46,6 +77,30 @@ 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 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
+     * 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.
+     */
+    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,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"}

package/dist/repositories/HttpUserRepository.mjs

@@ -51,6 +51,110 @@ 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;
+    }
+}
 /** Whether `value` is a positive integer that fits `bound`. */
 function isPositiveIntegerWithin(value, bound) {
     return typeof value === "number" && Number.isInteger(value) && value > 0 && value <= bound;
@@ -155,19 +259,47 @@ export class HttpUserRepository {
     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, timeout, maxResponseBytes = DEFAULT_MAX_RESPONSE_BYTES, }) {
         this.authenticateUrl = assertSecureEndpoint(authenticateUrl, "authenticateUrl");
         this.authenticateByTokenUrl = assertSecureEndpoint(authenticateByTokenUrl, "authenticateByTokenUrl");
         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`);
@@ -200,6 +332,119 @@ 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 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
+     * 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.
+     */
+    async postLookup(url, body) {
+        const controller = new AbortController();
+        let timedOut = false;
+        const timeoutError = () => {
+            const error = new Error(`HttpUserRepository: request to ${url} 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: { "Content-Type": "application/json" },
+                    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 new Error(`HttpUserRepository: identity lookup at ${url} could not be reached`);
+            }
+            if (!res.ok) {
+                discardBody(res);
+                throw new Error(`HttpUserRepository: identity lookup at ${url} answered HTTP ${res.status}`);
+            }
+            let raw;
+            try {
+                raw = await readBodyCapped(res, this.maxResponseBytes, url, deadline);
+            }
+            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`);
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                throw new Error(`HttpUserRepository: upstream ${url} 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 ` +
+                    "port's answers (linked / unlinked / indeterminate)");
+            }
+            return answer;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
     async post(url, body, options = {}) {
         const controller = new AbortController();
         let timedOut = false;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@o3co/auth-provider-foundation",
   "description": "Production HTTP user-authentication adapter for auth.provider",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "license": "Apache-2.0",
   "engines": {
     "node": ">=22.0.0"
@@ -32,7 +32,7 @@
     }
   },
   "peerDependencies": {
-    "@o3co/auth-provider-core": "^0.14.0"
+    "@o3co/auth-provider-core": "^0.15.0"
   },
   "devDependencies": {
     "@types/node": "^26.5.1",
@@ -40,7 +40,7 @@
     "pino": "^10.3.1",
     "vitest": "^5.0.0",
     "@vitest/coverage-v8": "^5.0.0",
-    "@o3co/auth-provider-core": "0.14.0"
+    "@o3co/auth-provider-core": "0.15.0"
   },
   "scripts": {
     "prebuild": "rimraf dist",