@cat-factory/server 0.223.0 → 0.224.0

package/dist/auth/oidc/OidcClient.d.ts

@@ -0,0 +1,86 @@
+import type { Logger, SsoDiscoveryDocument } from '@cat-factory/kernel';
+import type { JWTPayload } from 'jose';
+import type { SsoConfig } from '../../config/types.js';
+import type { OidcProviderDirectory } from './discovery.js';
+/** A failed exchange or verification, carrying the reason the SPA renders copy for. */
+export declare class OidcFlowError extends Error {
+    readonly reason: 'exchange_failed' | 'token_invalid';
+    constructor(reason: 'exchange_failed' | 'token_invalid', message: string);
+}
+/** The PKCE pair a login leg mints: the secret stays in a cookie, the challenge goes to the IdP. */
+export interface PkcePair {
+    verifier: string;
+    challenge: string;
+}
+export interface OidcClientDependencies {
+    config: SsoConfig;
+    directory: OidcProviderDirectory;
+    logger?: Logger;
+    fetchImpl?: typeof fetch;
+}
+export declare class OidcClient {
+    private readonly deps;
+    private readonly log;
+    constructor(deps: OidcClientDependencies);
+    /** The provider, from the discovery cache. */
+    provider(): Promise<SsoDiscoveryDocument>;
+    /** Where to send the browser to authenticate. */
+    authorizeUrl(params: {
+        redirectUri: string;
+        state: string;
+        nonce: string;
+        codeChallenge: string;
+        /** Pre-fills the IdP's account picker when the SPA knows who is signing in. Rarely set. */
+        loginHint?: string;
+    }): Promise<string>;
+    /**
+     * Exchange the callback `code` for tokens. Authenticates as a confidential client
+     * (`client_secret_post`, the method every enterprise IdP accepts) AND sends the PKCE verifier,
+     * so neither the code alone nor the secret alone is enough.
+     */
+    exchangeCode(params: {
+        code: string;
+        redirectUri: string;
+        codeVerifier: string;
+    }): Promise<{
+        idToken: string;
+        accessToken: string | null;
+    }>;
+    /**
+     * Verify an ID token and return its claims.
+     *
+     * On a `kid` the cached key set does not hold, refetches the provider ONCE (the rate-limited
+     * key-rotation path) and retries — because a provider rotating its signing keys must cost one
+     * fetch, not every login until the cache TTL lapses.
+     *
+     * Every exit is a payload or an `OidcFlowError`. The unknown-key signal is jose's OWN error and
+     * it is useful only INSIDE this method: once the one refetch is spent (or refused by its rate
+     * limit) the token is simply unverifiable, and letting the raw error out made the callback leg's
+     * `instanceof OidcFlowError` catch miss, which rendered a 500 JSON envelope at a browser
+     * mid-redirect instead of the reason the flow promises.
+     */
+    verifyIdToken(idToken: string, expected: {
+        nonce: string;
+    }): Promise<JWTPayload>;
+    private verifyAgainst;
+    /**
+     * Read the userinfo endpoint, or null when the provider exposes none / the call failed.
+     *
+     * Best-effort BY DESIGN: it supplements the ID token's claims, and a provider that answers
+     * slowly must not turn a valid authentication into a failed login. When the missing claim is
+     * one admission depends on, the ADMISSION rule refuses (with `email_required` /
+     * `group_required`) — so a userinfo outage never silently widens who gets in.
+     */
+    fetchUserInfo(accessToken: string): Promise<Record<string, unknown> | null>;
+}
+/**
+ * Mint a PKCE pair: 32 random bytes as the verifier, its SHA-256 as the S256 challenge.
+ *
+ * Exported (rather than a private method) because the login leg needs the verifier to put in the
+ * cookie and the challenge to put in the redirect, and the callback leg needs neither — keeping
+ * it a free function is what stops the secret from being reachable off the client instance.
+ */
+export declare function createPkcePair(): Promise<PkcePair>;
+/** Throw the shared 503 when a caller reached an SSO route on a deployment with none wired. */
+export declare function ssoNotConfigured(): never;
+//# sourceMappingURL=OidcClient.d.ts.map

package/dist/auth/oidc/OidcClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OidcClient.d.ts","sourceRoot":"","sources":["../../../src/auth/oidc/OidcClient.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAGvE,OAAO,KAAK,EAAiB,UAAU,EAAE,MAAM,MAAM,CAAA;AAErD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AACtD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAA;AAgD3D,uFAAuF;AACvF,qBAAa,aAAc,SAAQ,KAAK;IAEpC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,GAAG,eAAe;IADtD,YACW,MAAM,EAAE,iBAAiB,GAAG,eAAe,EACpD,OAAO,EAAE,MAAM,EAIhB;CACF;AAED,oGAAoG;AACpG,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,SAAS,CAAA;IACjB,SAAS,EAAE,qBAAqB,CAAA;IAChC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;CACzB;AAED,qBAAa,UAAU;IAGT,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFjC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAQ;IAE5B,YAA6B,IAAI,EAAE,sBAAsB,EAExD;IAED,8CAA8C;IAC9C,QAAQ,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAExC;IAED,iDAAiD;IAC3C,YAAY,CAAC,MAAM,EAAE;QACzB,WAAW,EAAE,MAAM,CAAA;QACnB,KAAK,EAAE,MAAM,CAAA;QACb,KAAK,EAAE,MAAM,CAAA;QACb,aAAa,EAAE,MAAM,CAAA;QACrB,2FAA2F;QAC3F,SAAS,CAAC,EAAE,MAAM,CAAA;KACnB,GAAG,OAAO,CAAC,MAAM,CAAC,CAalB;IAED;;;;OAIG;IACG,YAAY,CAAC,MAAM,EAAE;QACzB,IAAI,EAAE,MAAM,CAAA;QACZ,WAAW,EAAE,MAAM,CAAA;QACnB,YAAY,EAAE,MAAM,CAAA;KACrB,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAsD3D;IAED;;;;;;;;;;;;OAYG;IACG,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAmBrF;YAEa,aAAa;IAsC3B;;;;;;;OAOG;IACG,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAmBhF;CACF;AAmCD;;;;;;GAMG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,QAAQ,CAAC,CAKxD;AAED,+FAA+F;AAC/F,wBAAgB,gBAAgB,IAAI,KAAK,CAKxC"}

package/dist/auth/oidc/OidcClient.js

@@ -0,0 +1,271 @@
+import { UnavailableError, describeError, noopLogger, redactSecrets } from '@cat-factory/kernel';
+import { createLocalJWKSet, jwtVerify } from 'jose';
+import { base64url } from '../../crypto/encoding.js';
+// ---------------------------------------------------------------------------
+// The OpenID Connect Authorization Code + PKCE client — one adapter for every enterprise IdP.
+//
+// Deliberate choices, each of which is the difference between a login flow and a vulnerability:
+//
+//  - **Authorization Code, never implicit.** No token ever crosses the browser's URL bar.
+//  - **PKCE (S256) always.** The `code_verifier` lives only in an httpOnly cookie, so an
+//    authorization code intercepted from the redirect cannot be exchanged. Sent even to
+//    providers whose metadata omits `code_challenge_methods_supported`: an unaware provider
+//    ignores the parameters, whereas refusing on the advertisement locks out providers that
+//    implement the RFC without announcing it.
+//  - **ID token verified against the provider's JWKS, with an ASYMMETRIC algorithm allow-list.**
+//    Signature verification is delegated to `jose` rather than hand-rolled: it is Web-Crypto
+//    native (so it runs unchanged in a Workers isolate and on Node) and it is the wrong thing to
+//    reimplement. The allow-list is what closes the classic JWT holes — `alg: none` and an
+//    `HS256` token forged with the deployment's own client secret as the HMAC key.
+//  - **Keys are supplied LOCALLY** (`createLocalJWKSet` over the key set our own cache holds)
+//    rather than through jose's remote JWKS helper, which keeps its own module-level cache. One
+//    cache for the document, and it is the evictable app-cache seam.
+//  - **`nonce` is checked here**, bound to the httpOnly cookie the login leg set, so a replayed
+//    or injected ID token from another session is refused.
+// ---------------------------------------------------------------------------
+/**
+ * The signature algorithms an ID token may use. Asymmetric only, so a token can be verified
+ * ONLY with a key the provider published — never with a secret this deployment also holds.
+ */
+const ALLOWED_ID_TOKEN_ALGS = [
+    'RS256',
+    'RS384',
+    'RS512',
+    'PS256',
+    'PS384',
+    'PS512',
+    'ES256',
+    'ES384',
+    'ES512',
+    'EdDSA',
+];
+/** Clock skew tolerated on `exp`/`iat`/`nbf`. IdP and app clocks routinely differ by seconds. */
+const CLOCK_TOLERANCE = '60s';
+/** The token/userinfo calls sit on a user's critical path — bound them. */
+const FETCH_TIMEOUT_MS = 10_000;
+/** A failed exchange or verification, carrying the reason the SPA renders copy for. */
+export class OidcFlowError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = 'OidcFlowError';
+    }
+}
+export class OidcClient {
+    deps;
+    log;
+    constructor(deps) {
+        this.deps = deps;
+        this.log = deps.logger ?? noopLogger;
+    }
+    /** The provider, from the discovery cache. */
+    provider() {
+        return this.deps.directory.resolve(this.deps.config.issuerUrl);
+    }
+    /** Where to send the browser to authenticate. */
+    async authorizeUrl(params) {
+        const { metadata } = await this.provider();
+        const url = new URL(metadata.authorizationEndpoint);
+        url.searchParams.set('client_id', this.deps.config.clientId);
+        url.searchParams.set('redirect_uri', params.redirectUri);
+        url.searchParams.set('response_type', 'code');
+        url.searchParams.set('scope', this.deps.config.scopes);
+        url.searchParams.set('state', params.state);
+        url.searchParams.set('nonce', params.nonce);
+        url.searchParams.set('code_challenge', params.codeChallenge);
+        url.searchParams.set('code_challenge_method', 'S256');
+        if (params.loginHint)
+            url.searchParams.set('login_hint', params.loginHint);
+        return url.toString();
+    }
+    /**
+     * Exchange the callback `code` for tokens. Authenticates as a confidential client
+     * (`client_secret_post`, the method every enterprise IdP accepts) AND sends the PKCE verifier,
+     * so neither the code alone nor the secret alone is enough.
+     */
+    async exchangeCode(params) {
+        const { metadata } = await this.provider();
+        const doFetch = this.deps.fetchImpl ?? fetch;
+        let res;
+        try {
+            res = await doFetch(metadata.tokenEndpoint, {
+                method: 'POST',
+                headers: {
+                    accept: 'application/json',
+                    'content-type': 'application/x-www-form-urlencoded',
+                },
+                body: new URLSearchParams({
+                    grant_type: 'authorization_code',
+                    code: params.code,
+                    redirect_uri: params.redirectUri,
+                    client_id: this.deps.config.clientId,
+                    client_secret: this.deps.config.clientSecret,
+                    code_verifier: params.codeVerifier,
+                }),
+                signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+            });
+        }
+        catch (error) {
+            throw new OidcFlowError('exchange_failed', `The token endpoint could not be reached: ${causeText(error)}`);
+        }
+        const body = (await res.json().catch(() => ({})));
+        if (!res.ok) {
+            // The provider's own `error`/`error_description` is the diagnostic an operator needs
+            // ("invalid_client" ⇒ wrong secret, "invalid_grant" ⇒ redirect_uri mismatch), and it is
+            // scrubbed because a token-endpoint error routinely echoes the request back.
+            const detail = [body.error, body.error_description].filter(Boolean).join(': ');
+            throw new OidcFlowError('exchange_failed', `The identity provider refused the authorization code (HTTP ${res.status})` +
+                (detail ? `: ${redactSecrets(String(detail)) ?? ''}` : '.'));
+        }
+        if (typeof body.id_token !== 'string' || body.id_token === '') {
+            throw new OidcFlowError('token_invalid', 'The identity provider returned no ID token. Make sure the `openid` scope is granted to this client.');
+        }
+        return {
+            idToken: body.id_token,
+            accessToken: typeof body.access_token === 'string' ? body.access_token : null,
+        };
+    }
+    /**
+     * Verify an ID token and return its claims.
+     *
+     * On a `kid` the cached key set does not hold, refetches the provider ONCE (the rate-limited
+     * key-rotation path) and retries — because a provider rotating its signing keys must cost one
+     * fetch, not every login until the cache TTL lapses.
+     *
+     * Every exit is a payload or an `OidcFlowError`. The unknown-key signal is jose's OWN error and
+     * it is useful only INSIDE this method: once the one refetch is spent (or refused by its rate
+     * limit) the token is simply unverifiable, and letting the raw error out made the callback leg's
+     * `instanceof OidcFlowError` catch miss, which rendered a 500 JSON envelope at a browser
+     * mid-redirect instead of the reason the flow promises.
+     */
+    async verifyIdToken(idToken, expected) {
+        const document = await this.provider();
+        try {
+            return await this.verifyAgainst(document, idToken, expected);
+        }
+        catch (error) {
+            if (!isUnknownKeyError(error))
+                throw error;
+            const refreshed = await this.deps.directory.refreshForUnknownKey(this.deps.config.issuerUrl, document);
+            // Unchanged means the refetch was rate-limited: nothing new to try against.
+            if (refreshed === document)
+                throw keyNotPublished(error);
+            try {
+                return await this.verifyAgainst(refreshed, idToken, expected);
+            }
+            catch (retryError) {
+                if (!isUnknownKeyError(retryError))
+                    throw retryError;
+                throw keyNotPublished(retryError);
+            }
+        }
+    }
+    async verifyAgainst(document, idToken, expected) {
+        const keys = createLocalJWKSet(document.jwks);
+        let payload;
+        try {
+            const verified = await jwtVerify(idToken, keys, {
+                // The DISCOVERED issuer, never the configured URL: the provider's own spelling is what
+                // it signs, and it is what the identity subject is built from.
+                issuer: document.metadata.issuer,
+                audience: this.deps.config.clientId,
+                algorithms: ALLOWED_ID_TOKEN_ALGS,
+                clockTolerance: CLOCK_TOLERANCE,
+                requiredClaims: ['sub', 'iat', 'exp'],
+            });
+            payload = verified.payload;
+        }
+        catch (error) {
+            if (isUnknownKeyError(error))
+                throw error;
+            throw new OidcFlowError('token_invalid', `The ID token did not verify: ${causeText(error)}`);
+        }
+        // `nonce` is not a claim jose checks — it is OIDC's own replay binding, and it is the reason
+        // an ID token captured from one user's round-trip cannot be injected into another's.
+        if (payload.nonce !== expected.nonce) {
+            throw new OidcFlowError('token_invalid', "The ID token's nonce does not match this sign-in attempt.");
+        }
+        // `azp` identifies which client the token was issued FOR when the audience is multi-valued.
+        // Only meaningful when present; when it is, it must be us.
+        if (typeof payload.azp === 'string' && payload.azp !== this.deps.config.clientId) {
+            throw new OidcFlowError('token_invalid', 'The ID token was issued for a different client.');
+        }
+        return payload;
+    }
+    /**
+     * Read the userinfo endpoint, or null when the provider exposes none / the call failed.
+     *
+     * Best-effort BY DESIGN: it supplements the ID token's claims, and a provider that answers
+     * slowly must not turn a valid authentication into a failed login. When the missing claim is
+     * one admission depends on, the ADMISSION rule refuses (with `email_required` /
+     * `group_required`) — so a userinfo outage never silently widens who gets in.
+     */
+    async fetchUserInfo(accessToken) {
+        const { metadata } = await this.provider();
+        if (!metadata.userinfoEndpoint)
+            return null;
+        const doFetch = this.deps.fetchImpl ?? fetch;
+        try {
+            const res = await doFetch(metadata.userinfoEndpoint, {
+                headers: { accept: 'application/json', authorization: `Bearer ${accessToken}` },
+                signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+            });
+            if (!res.ok) {
+                this.log.warn('sso.userinfo.failed', { status: res.status });
+                return null;
+            }
+            const body = await res.json();
+            return body && typeof body === 'object' ? body : null;
+        }
+        catch (error) {
+            this.log.warn('sso.userinfo.failed', describeError(error));
+            return null;
+        }
+    }
+}
+/** The scrubbed message of a thrown value, as a string safe to interpolate. */
+function causeText(error) {
+    return String(describeError(error).err ?? '');
+}
+/**
+ * The refusal for a token whose signing key the provider does not publish, once the single
+ * rate-limited refetch has been spent. Reported as `token_invalid` because that is what it is
+ * from the caller's side: a token this deployment cannot verify. The message names the key so an
+ * operator reading the log can tell a mid-rotation race (retry succeeds) from a provider signing
+ * with a key it never published (it does not).
+ */
+function keyNotPublished(error) {
+    return new OidcFlowError('token_invalid', 'The ID token is signed with a key the identity provider does not publish in its key set, ' +
+        `and refetching the key set did not produce it: ${causeText(error)}`);
+}
+/**
+ * Whether a verification failure is "no key with that `kid`" — the key-rotation signal — rather
+ * than a bad signature.
+ *
+ * Matched on jose's stable error `code` rather than its message, so a wording change upstream
+ * cannot silently turn a rotation into a hard login failure. `ERR_JWKS_MULTIPLE_MATCHING_KEYS`
+ * counts too: an ambiguous match resolves once the stale key is gone.
+ */
+function isUnknownKeyError(error) {
+    const code = error?.code;
+    return code === 'ERR_JWKS_NO_MATCHING_KEY' || code === 'ERR_JWKS_MULTIPLE_MATCHING_KEYS';
+}
+/**
+ * Mint a PKCE pair: 32 random bytes as the verifier, its SHA-256 as the S256 challenge.
+ *
+ * Exported (rather than a private method) because the login leg needs the verifier to put in the
+ * cookie and the challenge to put in the redirect, and the callback leg needs neither — keeping
+ * it a free function is what stops the secret from being reachable off the client instance.
+ */
+export async function createPkcePair() {
+    const bytes = crypto.getRandomValues(new Uint8Array(32));
+    const verifier = base64url(bytes);
+    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier));
+    return { verifier, challenge: base64url(digest) };
+}
+/** Throw the shared 503 when a caller reached an SSO route on a deployment with none wired. */
+export function ssoNotConfigured() {
+    throw new UnavailableError('Single sign-on is not configured on this deployment.', 'sso_not_configured');
+}
+//# sourceMappingURL=OidcClient.js.map

package/dist/auth/oidc/OidcClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OidcClient.js","sourceRoot":"","sources":["../../../src/auth/oidc/OidcClient.ts"],"names":[],"mappings":"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"}

package/dist/auth/oidc/claims.d.ts

@@ -0,0 +1,97 @@
+import type { SsoErrorReason } from '@cat-factory/contracts';
+import type { SsoConfig } from '../../config/types.js';
+/** The identity an SSO round-trip resolved, normalised across providers. */
+export interface SsoIdentity {
+    /** The provider's `sub` — the stable identity, never the email. */
+    sub: string;
+    email: string | null;
+    /**
+     * Whether the email may be trusted to LINK this login onto an existing same-email user.
+     *
+     * `email_verified` is absent from a great many enterprise ID tokens even though the address is
+     * authoritative — it comes from the corporate directory, which is the whole trust model an
+     * operator adopted this IdP for. So absence is treated as verified and only an EXPLICIT
+     * `email_verified: false` is honoured as unverified. The alternative (requiring the claim)
+     * silently creates a second user for anyone who also signed in with GitHub, and — because
+     * `users.email` is unique and an unverified email is dropped — leaves the SSO account with no
+     * email at all, which breaks invitations and every roster display. The residual risk is
+     * bounded by the IdP: a directory that lets a user self-assert another person's corporate
+     * address has already lost, with or without this claim.
+     */
+    emailVerified: boolean;
+    name: string | null;
+    avatarUrl: string | null;
+    /** A display handle: `preferred_username`, else the email, else the `sub`. */
+    login: string;
+    /** Group memberships read from the configured claim, lowercased. Empty when none released. */
+    groups: string[];
+}
+/** Whether a sign-in is admitted, and if not, which rule refused it. */
+export type SsoAdmission = {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: SsoErrorReason;
+};
+/**
+ * Read a group-membership claim, tolerating every shape providers ship it in: an array of
+ * strings, a single string, a space-separated string (some SAML-to-OIDC bridges), or an array of
+ * `{ value }` / `{ name }` objects. Anything unrecognised contributes nothing rather than
+ * throwing: one odd entry must not discard the rest of a user's groups.
+ *
+ * Whether a value is SPLIT on whitespace turns on whether something else already delimited it,
+ * and getting that backwards is the silent lockout this whole file warns about. An ARRAY entry is
+ * taken WHOLE: Okta, Entra ID and every AD-backed directory permit spaces in a group's name
+ * ("Domain Admins" is the canonical one), `AUTH_SSO_REQUIRED_GROUPS` splits on COMMAS so such a
+ * name is perfectly addressable, and shredding it into `domain` + `admins` matches nothing an
+ * operator can write. Only a BARE STRING is genuinely ambiguous, and there the space-separated
+ * spelling is the shape a whole-value read would get wrong.
+ */
+export declare function readGroupClaim(claims: Record<string, unknown>, claimName: string): string[];
+/**
+ * Whether a userinfo response describes the SAME subject the verified ID token did.
+ *
+ * OIDC Core 5.3.2 makes this a MUST, and it is not tidiness: overlaying the ID token's claims
+ * LAST already stops `sub` itself from being taken from userinfo, but `email` and `groups` ride
+ * the same response and BOTH decide admission. A response for another subject would hand this
+ * user that subject's directory groups, which is the one way a `requiredGroups` gate can be
+ * satisfied by somebody else's membership. A response with no `sub` at all fails this too: the
+ * claim is REQUIRED there, and a merge that cannot be checked is not one to trust.
+ */
+export declare function userinfoMatchesSubject(userinfo: Record<string, unknown>, claims: Record<string, unknown>): boolean;
+/**
+ * Build the identity from the merged claim bag (ID token, with any userinfo claims overlaid).
+ *
+ * Returns null when there is no `sub`: without it there is no stable key, and inventing one from
+ * the email would key a user's account on a value orgs reassign.
+ */
+export declare function readSsoIdentity(claims: Record<string, unknown>, cfg: Pick<SsoConfig, 'groupsClaim'>): SsoIdentity | null;
+/**
+ * Whether this identity may sign in.
+ *
+ * The default is ADMIT, and that is the feature rather than an oversight: with SSO configured,
+ * the identity provider's own app assignment IS the allowlist, which is precisely the capability
+ * an org adopts SSO to get (onboarding and — the one that matters — offboarding happen in the
+ * directory, not in a list here). Contrast the GitHub login path, which fails closed with both
+ * its lists empty: there, nothing else expresses who is allowed.
+ *
+ * The two optional narrowings are for orgs whose IdP serves more than the population that should
+ * reach this deployment, and they are checked in the order whose refusal is most actionable:
+ *
+ *  1. `requiredGroups` — the user is in none of the named directory groups.
+ *  2. `allowedEmailDomains` — their email's domain is not listed. A configured domain gate with
+ *     NO email released is refused (`email_required`) rather than admitted: admitting would void
+ *     a rule the operator wrote, and the fix (release the `email` claim) belongs to them.
+ */
+export declare function judgeSsoAdmission(identity: SsoIdentity, cfg: Pick<SsoConfig, 'allowedEmailDomains' | 'requiredGroups'>): SsoAdmission;
+/**
+ * Whether the ID token's claims are enough to decide admission and populate a profile, or
+ * whether the userinfo endpoint has to be called too.
+ *
+ * Asked so the extra round-trip happens only when it can change the outcome. Most enterprise
+ * providers put `email` in the ID token but release `groups` only from userinfo (Entra ID
+ * notably), and one unconditional userinfo call per login is a latency cost paid by every
+ * deployment to serve the ones that need it.
+ */
+export declare function needsUserinfo(claims: Record<string, unknown>, cfg: Pick<SsoConfig, 'groupsClaim' | 'requiredGroups' | 'allowedEmailDomains'>): boolean;
+//# sourceMappingURL=claims.d.ts.map

package/dist/auth/oidc/claims.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claims.d.ts","sourceRoot":"","sources":["../../../src/auth/oidc/claims.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AAiBtD,4EAA4E;AAC5E,MAAM,WAAW,WAAW;IAC1B,mEAAmE;IACnE,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB;;;;;;;;;;;;OAYG;IACH,aAAa,EAAE,OAAO,CAAA;IACtB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,8EAA8E;IAC9E,KAAK,EAAE,MAAM,CAAA;IACb,8FAA8F;IAC9F,MAAM,EAAE,MAAM,EAAE,CAAA;CACjB;AAED,wEAAwE;AACxE,MAAM,MAAM,YAAY,GAAG;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,cAAc,CAAA;CAAE,CAAA;AAMzF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAyB3F;AAcD;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,OAAO,CAGT;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,GAAG,EAAE,IAAI,CAAC,SAAS,EAAE,aAAa,CAAC,GAClC,WAAW,GAAG,IAAI,CAcpB;AAUD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,WAAW,EACrB,GAAG,EAAE,IAAI,CAAC,SAAS,EAAE,qBAAqB,GAAG,gBAAgB,CAAC,GAC7D,YAAY,CAgBd;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,GAAG,EAAE,IAAI,CAAC,SAAS,EAAE,aAAa,GAAG,gBAAgB,GAAG,qBAAqB,CAAC,GAC7E,OAAO,CAMT"}

package/dist/auth/oidc/claims.js

@@ -0,0 +1,149 @@
+function str(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value.trim() : null;
+}
+/**
+ * Read a group-membership claim, tolerating every shape providers ship it in: an array of
+ * strings, a single string, a space-separated string (some SAML-to-OIDC bridges), or an array of
+ * `{ value }` / `{ name }` objects. Anything unrecognised contributes nothing rather than
+ * throwing: one odd entry must not discard the rest of a user's groups.
+ *
+ * Whether a value is SPLIT on whitespace turns on whether something else already delimited it,
+ * and getting that backwards is the silent lockout this whole file warns about. An ARRAY entry is
+ * taken WHOLE: Okta, Entra ID and every AD-backed directory permit spaces in a group's name
+ * ("Domain Admins" is the canonical one), `AUTH_SSO_REQUIRED_GROUPS` splits on COMMAS so such a
+ * name is perfectly addressable, and shredding it into `domain` + `admins` matches nothing an
+ * operator can write. Only a BARE STRING is genuinely ambiguous, and there the space-separated
+ * spelling is the shape a whole-value read would get wrong.
+ */
+export function readGroupClaim(claims, claimName) {
+    if (!claimName)
+        return [];
+    const raw = claims[claimName];
+    if (typeof raw === 'string') {
+        return raw
+            .split(/\s+/)
+            .filter(Boolean)
+            .map((part) => part.toLowerCase());
+    }
+    const values = Array.isArray(raw) ? raw : raw === undefined || raw === null ? [] : [raw];
+    const out = [];
+    for (const entry of values) {
+        if (typeof entry === 'string') {
+            const value = str(entry);
+            if (value)
+                out.push(value.toLowerCase());
+            continue;
+        }
+        if (entry && typeof entry === 'object') {
+            const nested = str(entry.value ?? entry.name);
+            if (nested)
+                out.push(nested.toLowerCase());
+        }
+    }
+    return out;
+}
+/**
+ * Whether a claim states a NEGATIVE explicitly.
+ *
+ * `email_verified` is specified as a boolean and its ABSENCE is read as verified (the decision
+ * documented on {@link SsoIdentity.emailVerified}), so the only thing this has to catch is a
+ * provider that says "no". Some ship JSON booleans as strings, and `"false"` is the one spelling
+ * where absence-means-verified would invert the provider's own answer rather than fill a gap.
+ */
+function statesFalse(value) {
+    return value === false || value === 'false';
+}
+/**
+ * Whether a userinfo response describes the SAME subject the verified ID token did.
+ *
+ * OIDC Core 5.3.2 makes this a MUST, and it is not tidiness: overlaying the ID token's claims
+ * LAST already stops `sub` itself from being taken from userinfo, but `email` and `groups` ride
+ * the same response and BOTH decide admission. A response for another subject would hand this
+ * user that subject's directory groups, which is the one way a `requiredGroups` gate can be
+ * satisfied by somebody else's membership. A response with no `sub` at all fails this too: the
+ * claim is REQUIRED there, and a merge that cannot be checked is not one to trust.
+ */
+export function userinfoMatchesSubject(userinfo, claims) {
+    const fromUserinfo = str(userinfo.sub);
+    return fromUserinfo !== null && fromUserinfo === str(claims.sub);
+}
+/**
+ * Build the identity from the merged claim bag (ID token, with any userinfo claims overlaid).
+ *
+ * Returns null when there is no `sub`: without it there is no stable key, and inventing one from
+ * the email would key a user's account on a value orgs reassign.
+ */
+export function readSsoIdentity(claims, cfg) {
+    const sub = str(claims.sub);
+    if (!sub)
+        return null;
+    const email = str(claims.email)?.toLowerCase() ?? null;
+    const preferred = str(claims.preferred_username);
+    return {
+        sub,
+        email,
+        emailVerified: email !== null && !statesFalse(claims.email_verified),
+        name: str(claims.name) ?? joinName(claims),
+        avatarUrl: str(claims.picture),
+        login: preferred ?? email ?? sub,
+        groups: readGroupClaim(claims, cfg.groupsClaim),
+    };
+}
+/** `given_name` + `family_name`, for providers that release no composed `name`. */
+function joinName(claims) {
+    const parts = [str(claims.given_name), str(claims.family_name)].filter((part) => part !== null);
+    return parts.length > 0 ? parts.join(' ') : null;
+}
+/**
+ * Whether this identity may sign in.
+ *
+ * The default is ADMIT, and that is the feature rather than an oversight: with SSO configured,
+ * the identity provider's own app assignment IS the allowlist, which is precisely the capability
+ * an org adopts SSO to get (onboarding and — the one that matters — offboarding happen in the
+ * directory, not in a list here). Contrast the GitHub login path, which fails closed with both
+ * its lists empty: there, nothing else expresses who is allowed.
+ *
+ * The two optional narrowings are for orgs whose IdP serves more than the population that should
+ * reach this deployment, and they are checked in the order whose refusal is most actionable:
+ *
+ *  1. `requiredGroups` — the user is in none of the named directory groups.
+ *  2. `allowedEmailDomains` — their email's domain is not listed. A configured domain gate with
+ *     NO email released is refused (`email_required`) rather than admitted: admitting would void
+ *     a rule the operator wrote, and the fix (release the `email` claim) belongs to them.
+ */
+export function judgeSsoAdmission(identity, cfg) {
+    if (cfg.requiredGroups.length > 0) {
+        const member = identity.groups.some((group) => cfg.requiredGroups.includes(group));
+        if (!member)
+            return { allowed: false, reason: 'group_required' };
+    }
+    if (cfg.allowedEmailDomains.length > 0) {
+        if (!identity.email || !identity.emailVerified) {
+            return { allowed: false, reason: 'email_required' };
+        }
+        const at = identity.email.lastIndexOf('@');
+        const domain = at < 0 ? '' : identity.email.slice(at + 1);
+        if (!cfg.allowedEmailDomains.includes(domain)) {
+            return { allowed: false, reason: 'domain_not_allowed' };
+        }
+    }
+    return { allowed: true };
+}
+/**
+ * Whether the ID token's claims are enough to decide admission and populate a profile, or
+ * whether the userinfo endpoint has to be called too.
+ *
+ * Asked so the extra round-trip happens only when it can change the outcome. Most enterprise
+ * providers put `email` in the ID token but release `groups` only from userinfo (Entra ID
+ * notably), and one unconditional userinfo call per login is a latency cost paid by every
+ * deployment to serve the ones that need it.
+ */
+export function needsUserinfo(claims, cfg) {
+    if (!str(claims.email))
+        return true;
+    if (cfg.requiredGroups.length > 0 && readGroupClaim(claims, cfg.groupsClaim).length === 0) {
+        return true;
+    }
+    return false;
+}
+//# sourceMappingURL=claims.js.map

package/dist/auth/oidc/claims.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claims.js","sourceRoot":"","sources":["../../../src/auth/oidc/claims.ts"],"names":[],"mappings":"AAgDA,SAAS,GAAG,CAAC,KAAc;IACzB,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAA;AAC/E,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,cAAc,CAAC,MAA+B,EAAE,SAAiB;IAC/E,IAAI,CAAC,SAAS;QAAE,OAAO,EAAE,CAAA;IACzB,MAAM,GAAG,GAAG,MAAM,CAAC,SAAS,CAAC,CAAA;IAC7B,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5B,OAAO,GAAG;aACP,KAAK,CAAC,KAAK,CAAC;aACZ,MAAM,CAAC,OAAO,CAAC;aACf,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAA;IACtC,CAAC;IACD,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;IACxF,MAAM,GAAG,GAAa,EAAE,CAAA;IACxB,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,CAAA;YACxB,IAAI,KAAK;gBAAE,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAA;YACxC,SAAQ;QACV,CAAC;QACD,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YACvC,MAAM,MAAM,GAAG,GAAG,CACf,KAAiC,CAAC,KAAK,IAAK,KAAiC,CAAC,IAAI,CACpF,CAAA;YACD,IAAI,MAAM;gBAAE,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,CAAA;QAC5C,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,WAAW,CAAC,KAAc;IACjC,OAAO,KAAK,KAAK,KAAK,IAAI,KAAK,KAAK,OAAO,CAAA;AAC7C,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,sBAAsB,CACpC,QAAiC,EACjC,MAA+B;IAE/B,MAAM,YAAY,GAAG,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAA;IACtC,OAAO,YAAY,KAAK,IAAI,IAAI,YAAY,KAAK,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;AAClE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAC7B,MAA+B,EAC/B,GAAmC;IAEnC,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;IAC3B,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAA;IACrB,MAAM,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,WAAW,EAAE,IAAI,IAAI,CAAA;IACtD,MAAM,SAAS,GAAG,GAAG,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAA;IAChD,OAAO;QACL,GAAG;QACH,KAAK;QACL,aAAa,EAAE,KAAK,KAAK,IAAI,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,cAAc,CAAC;QACpE,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,QAAQ,CAAC,MAAM,CAAC;QAC1C,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC;QAC9B,KAAK,EAAE,SAAS,IAAI,KAAK,IAAI,GAAG;QAChC,MAAM,EAAE,cAAc,CAAC,MAAM,EAAE,GAAG,CAAC,WAAW,CAAC;KAChD,CAAA;AACH,CAAC;AAED,mFAAmF;AACnF,SAAS,QAAQ,CAAC,MAA+B;IAC/C,MAAM,KAAK,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,CACpE,CAAC,IAAI,EAAkB,EAAE,CAAC,IAAI,KAAK,IAAI,CACxC,CAAA;IACD,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;AAClD,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,iBAAiB,CAC/B,QAAqB,EACrB,GAA8D;IAE9D,IAAI,GAAG,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClC,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,CAAC,cAAc,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAA;QAClF,IAAI,CAAC,MAAM;YAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAA;IAClE,CAAC;IACD,IAAI,GAAG,CAAC,mBAAmB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvC,IAAI,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC,QAAQ,CAAC,aAAa,EAAE,CAAC;YAC/C,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAA;QACrD,CAAC;QACD,MAAM,EAAE,GAAG,QAAQ,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAA;QAC1C,MAAM,MAAM,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAA;QACzD,IAAI,CAAC,GAAG,CAAC,mBAAmB,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YAC9C,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,oBAAoB,EAAE,CAAA;QACzD,CAAC;IACH,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA;AAC1B,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAC3B,MAA+B,EAC/B,GAA8E;IAE9E,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IACnC,IAAI,GAAG,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC,IAAI,cAAc,CAAC,MAAM,EAAE,GAAG,CAAC,WAAW,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1F,OAAO,IAAI,CAAA;IACb,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC"}