@facilis.dev/auth 0.0.0-stage → 0.1.0

package/dist/sso/oauth2.js

@@ -0,0 +1,180 @@
+import { runtimeFetch } from "./contracts.js";
+import { SsoError } from "./errors.js";
+/**
+ * Generic OAuth2 authorization-code provider (D-120).
+ *
+ * Unlike OIDC there is no discovery or ID token, so the identity comes from the userinfo endpoint
+ * plus a dotted-path mapping declared in facilis.config.ts. Email verification is claim-driven:
+ * a provider that never reports the claim must opt in with `assumeEmailVerified`.
+ */
+const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+$/;
+function requireFetch(fetch) {
+    return fetch ?? runtimeFetch();
+}
+function basicAuthorization(clientId, clientSecret) {
+    const bytes = new TextEncoder().encode(`${clientId}:${clientSecret}`);
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return `Basic ${btoa(binary)}`;
+}
+/**
+ * POSTs an authorization-code grant to the token endpoint with the configured client auth mode.
+ *
+ * The response is parsed for `access_token`/`id_token` only; a provider error body is never
+ * surfaced (it can echo the code), just the safe `sso_exchange_failed` code.
+ */
+export async function requestToken(input) {
+    const form = new URLSearchParams(input.form);
+    form.set("client_id", input.client.clientId);
+    const headers = {
+        "content-type": "application/x-www-form-urlencoded",
+        accept: "application/json",
+    };
+    if (input.client.tokenAuth === "client_secret_basic") {
+        if (input.client.clientSecret === undefined)
+            throw new SsoError("sso_provider_unavailable");
+        headers["authorization"] = basicAuthorization(input.client.clientId, input.client.clientSecret);
+    }
+    else if (input.client.tokenAuth === "client_secret_post") {
+        if (input.client.clientSecret === undefined)
+            throw new SsoError("sso_provider_unavailable");
+        form.set("client_secret", input.client.clientSecret);
+    }
+    let response;
+    try {
+        response = await requireFetch(input.fetch)(input.endpoint, {
+            method: "POST",
+            headers,
+            body: form.toString(),
+        });
+    }
+    catch (error) {
+        throw new SsoError("sso_exchange_failed", "token request failed", { cause: error });
+    }
+    if (!response.ok)
+        throw new SsoError("sso_exchange_failed", `token endpoint ${response.status}`);
+    let payload;
+    try {
+        payload = await response.json();
+    }
+    catch (error) {
+        throw new SsoError("sso_exchange_failed", "token response is not JSON", { cause: error });
+    }
+    if (typeof payload !== "object" || payload === null) {
+        throw new SsoError("sso_exchange_failed", "token response shape");
+    }
+    const record = payload;
+    const accessToken = readString(record, "access_token");
+    if (accessToken === undefined)
+        throw new SsoError("sso_exchange_failed", "no access_token");
+    const idToken = readString(record, "id_token");
+    return idToken === undefined ? { accessToken } : { accessToken, idToken };
+}
+/** Reads a dotted path (`data.user.email`) out of parsed userinfo JSON. */
+export function readDottedPath(value, path) {
+    let current = value;
+    for (const segment of path.split(".")) {
+        if (typeof current !== "object" || current === null)
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+}
+function readString(record, key) {
+    const value = record[key];
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+/** Truthiness of a verification claim: boolean true or the string "true" only. */
+export function readVerifiedClaim(value) {
+    if (value === true || value === "true")
+        return true;
+    if (value === false || value === "false")
+        return false;
+    return undefined;
+}
+function requireString(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+/** Subjects are often numeric in OAuth2 userinfo (e.g. a GitHub `id`). */
+function requireScalar(value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return String(value);
+    return requireString(value);
+}
+/**
+ * The authorization URL: response_type=code, the configured scopes, state, PKCE S256 and the
+ * redirect URI. PKCE is sent unconditionally (RFC 6749 lets a provider ignore it) so a public
+ * `tokenAuth: "none"` client is protected exactly like the OIDC flow (D-120).
+ */
+export function buildOauth2AuthorizeUrl(provider, redirectUri, state, codeChallenge) {
+    const url = new URL(provider.authorizationEndpoint);
+    url.searchParams.set("response_type", "code");
+    url.searchParams.set("client_id", provider.clientId);
+    url.searchParams.set("redirect_uri", redirectUri);
+    url.searchParams.set("state", state);
+    url.searchParams.set("code_challenge", codeChallenge);
+    url.searchParams.set("code_challenge_method", "S256");
+    if (provider.scopes.length > 0)
+        url.searchParams.set("scope", provider.scopes.join(" "));
+    return url.toString();
+}
+export function exchangeOauth2Code(client, provider, input) {
+    return requestToken({
+        endpoint: provider.tokenEndpoint,
+        client,
+        form: {
+            grant_type: "authorization_code",
+            code: input.code,
+            redirect_uri: input.redirectUri,
+            code_verifier: input.codeVerifier,
+        },
+        ...(input.fetch === undefined ? {} : { fetch: input.fetch }),
+    });
+}
+async function fetchUserinfo(provider, accessToken, fetch) {
+    let response;
+    try {
+        response = await fetch(provider.userinfoEndpoint, {
+            method: "GET",
+            headers: { authorization: `Bearer ${accessToken}`, accept: "application/json" },
+        });
+    }
+    catch (error) {
+        throw new SsoError("sso_exchange_failed", "userinfo request failed", { cause: error });
+    }
+    if (!response.ok)
+        throw new SsoError("sso_exchange_failed", `userinfo ${response.status}`);
+    let payload;
+    try {
+        payload = await response.json();
+    }
+    catch (error) {
+        throw new SsoError("sso_exchange_failed", "userinfo is not JSON", { cause: error });
+    }
+    if (typeof payload !== "object" || payload === null) {
+        throw new SsoError("sso_exchange_failed", "userinfo shape");
+    }
+    return payload;
+}
+/** Maps the userinfo JSON onto the identity key via the configured dotted paths. */
+export function resolveOauth2Identity(provider, userinfo) {
+    const subject = requireScalar(readDottedPath(userinfo, provider.mapping.subject));
+    if (subject === undefined)
+        throw new SsoError("sso_identity_invalid", "no subject mapping");
+    const rawEmail = requireString(readDottedPath(userinfo, provider.mapping.email));
+    if (rawEmail === undefined || !EMAIL_PATTERN.test(rawEmail)) {
+        throw new SsoError("sso_identity_invalid", "no email mapping");
+    }
+    const claim = provider.mapping.emailVerified === undefined
+        ? undefined
+        : readVerifiedClaim(readDottedPath(userinfo, provider.mapping.emailVerified));
+    const emailVerified = claim ?? provider.assumeEmailVerified;
+    return { subject, email: rawEmail, emailVerified };
+}
+/** Token exchange + userinfo + mapping, the complete generic-OAuth2 identity resolution. */
+export async function resolveOauth2IdentityFromCode(client, provider, input) {
+    const token = await exchangeOauth2Code(client, provider, input);
+    const userinfo = await fetchUserinfo(provider, token.accessToken, input.fetch ?? runtimeFetch());
+    return resolveOauth2Identity(provider, userinfo);
+}

package/dist/sso/oidc.d.ts

@@ -0,0 +1,60 @@
+import { type JWTVerifyGetKey } from "jose";
+import { type FetchLike, type IdentityClaims } from "./contracts.js";
+import { type TokenPayload } from "./oauth2.js";
+import type { OidcProviderConfig } from "./providers.js";
+/**
+ * OpenID Connect authorization code flow with PKCE and nonce (D-120).
+ *
+ * Discovery is fetched once per provider and cached with a TTL; the ID token is verified with
+ * `jose` against the provider JWKS, the issuer, the client id and the nonce. Tests inject the
+ * fetch (discovery) and the JWKS resolver (`createLocalJWKSet`), so the suite needs no network.
+ */
+export declare const OIDC_DISCOVERY_TTL_MS: number;
+export interface OidcDiscovery {
+    readonly issuer: string;
+    readonly authorizationEndpoint: string;
+    readonly tokenEndpoint: string;
+    readonly userinfoEndpoint?: string;
+    readonly jwksUri: string;
+}
+export interface OidcDeps {
+    readonly fetch?: FetchLike;
+    readonly now?: () => number;
+    readonly jwksResolver?: (jwksUri: string) => JWTVerifyGetKey;
+    readonly discoveryTtlMs?: number;
+}
+/** Clears the per-provider discovery cache (tests, and a deliberate provider reconfiguration). */
+export declare function clearOidcDiscoveryCache(): void;
+/** Fetches and caches `<issuer>/.well-known/openid-configuration` for one provider. */
+export declare function discoverOidc(provider: OidcProviderConfig, deps?: OidcDeps): Promise<OidcDiscovery>;
+export interface OidcAuthorizeInput {
+    readonly redirectUri: string;
+    readonly state: string;
+    readonly nonce: string;
+    readonly codeChallenge: string;
+}
+/** The authorization URL: response_type=code, scopes, state, nonce and PKCE S256. */
+export declare function buildOidcAuthorizeUrl(provider: OidcProviderConfig, discovery: OidcDiscovery, input: OidcAuthorizeInput): string;
+export interface OidcTokenInput {
+    readonly code: string;
+    readonly redirectUri: string;
+    readonly codeVerifier: string;
+    readonly fetch?: FetchLike;
+}
+export declare function exchangeOidcCode(client: {
+    clientId: string;
+    clientSecret?: string;
+    tokenAuth: OidcProviderConfig["tokenAuth"];
+}, discovery: OidcDiscovery, input: OidcTokenInput): Promise<TokenPayload>;
+export interface OidcClaims {
+    readonly subject: string;
+    readonly email?: string;
+    readonly emailVerified: boolean;
+}
+/** Verifies an ID token: signature (JWKS), issuer, audience, expiry (jose) and the nonce. */
+export declare function verifyOidcIdToken(provider: OidcProviderConfig, discovery: OidcDiscovery, idToken: string, nonce: string, deps?: OidcDeps): Promise<OidcClaims>;
+/**
+ * Resolves the OIDC identity: ID-token claims, with a userinfo fallback only when the email
+ * claim is absent. The userinfo `sub` must agree with the verified ID-token subject.
+ */
+export declare function resolveOidcIdentity(provider: OidcProviderConfig, discovery: OidcDiscovery, token: TokenPayload, nonce: string, deps?: OidcDeps): Promise<IdentityClaims>;

package/dist/sso/oidc.js

@@ -0,0 +1,201 @@
+import { createRemoteJWKSet, jwtVerify } from "jose";
+import { runtimeFetch, } from "./contracts.js";
+import { SsoError } from "./errors.js";
+import { requestToken, readVerifiedClaim } from "./oauth2.js";
+/**
+ * OpenID Connect authorization code flow with PKCE and nonce (D-120).
+ *
+ * Discovery is fetched once per provider and cached with a TTL; the ID token is verified with
+ * `jose` against the provider JWKS, the issuer, the client id and the nonce. Tests inject the
+ * fetch (discovery) and the JWKS resolver (`createLocalJWKSet`), so the suite needs no network.
+ */
+export const OIDC_DISCOVERY_TTL_MS = 5 * 60 * 1000;
+const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+$/;
+const discoveryCache = new Map();
+/** Clears the per-provider discovery cache (tests, and a deliberate provider reconfiguration). */
+export function clearOidcDiscoveryCache() {
+    discoveryCache.clear();
+}
+function readRecord(value) {
+    return typeof value === "object" && value !== null ? value : null;
+}
+function readUrl(record, key) {
+    const value = record[key];
+    if (typeof value !== "string")
+        return undefined;
+    try {
+        const url = new URL(value);
+        return url.protocol === "https:" || url.protocol === "http:" ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function discoveryUrl(issuer) {
+    return `${issuer.replace(/\/+$/, "")}/.well-known/openid-configuration`;
+}
+function parseDiscovery(value) {
+    const record = readRecord(value);
+    if (record === null)
+        throw new SsoError("sso_provider_unavailable", "discovery shape");
+    const authorizationEndpoint = readUrl(record, "authorization_endpoint");
+    const tokenEndpoint = readUrl(record, "token_endpoint");
+    const jwksUri = readUrl(record, "jwks_uri");
+    const issuer = typeof record["issuer"] === "string" ? record["issuer"] : "";
+    if (authorizationEndpoint === undefined || tokenEndpoint === undefined || jwksUri === undefined) {
+        throw new SsoError("sso_provider_unavailable", "discovery is missing an endpoint");
+    }
+    const userinfoEndpoint = readUrl(record, "userinfo_endpoint");
+    return {
+        issuer,
+        authorizationEndpoint,
+        tokenEndpoint,
+        jwksUri,
+        ...(userinfoEndpoint === undefined ? {} : { userinfoEndpoint }),
+    };
+}
+/** Fetches and caches `<issuer>/.well-known/openid-configuration` for one provider. */
+export async function discoverOidc(provider, deps = {}) {
+    const now = deps.now?.() ?? Date.now();
+    const ttl = deps.discoveryTtlMs ?? OIDC_DISCOVERY_TTL_MS;
+    const key = `${provider.id}\u0000${provider.issuer}`;
+    const cached = discoveryCache.get(key);
+    if (cached !== undefined && now - cached.fetchedAt < ttl)
+        return cached.value;
+    const fetch = deps.fetch ?? runtimeFetch();
+    let response;
+    try {
+        response = await fetch(discoveryUrl(provider.issuer), {
+            method: "GET",
+            headers: { accept: "application/json" },
+        });
+    }
+    catch (error) {
+        throw new SsoError("sso_provider_unavailable", "discovery request failed", { cause: error });
+    }
+    if (!response.ok) {
+        throw new SsoError("sso_provider_unavailable", `discovery ${response.status}`);
+    }
+    let payload;
+    try {
+        payload = await response.json();
+    }
+    catch (error) {
+        throw new SsoError("sso_provider_unavailable", "discovery is not JSON", { cause: error });
+    }
+    const discovery = parseDiscovery(payload);
+    discoveryCache.set(key, { value: discovery, fetchedAt: now });
+    return discovery;
+}
+/** The authorization URL: response_type=code, scopes, state, nonce and PKCE S256. */
+export function buildOidcAuthorizeUrl(provider, discovery, input) {
+    const url = new URL(discovery.authorizationEndpoint);
+    url.searchParams.set("response_type", "code");
+    url.searchParams.set("client_id", provider.clientId);
+    url.searchParams.set("redirect_uri", input.redirectUri);
+    url.searchParams.set("scope", provider.scopes.join(" "));
+    url.searchParams.set("state", input.state);
+    url.searchParams.set("nonce", input.nonce);
+    url.searchParams.set("code_challenge", input.codeChallenge);
+    url.searchParams.set("code_challenge_method", "S256");
+    return url.toString();
+}
+export function exchangeOidcCode(client, discovery, input) {
+    return requestToken({
+        endpoint: discovery.tokenEndpoint,
+        client,
+        form: {
+            grant_type: "authorization_code",
+            code: input.code,
+            redirect_uri: input.redirectUri,
+            code_verifier: input.codeVerifier,
+        },
+        ...(input.fetch === undefined ? {} : { fetch: input.fetch }),
+    });
+}
+function readString(record, key) {
+    const value = record[key];
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+/** Verifies an ID token: signature (JWKS), issuer, audience, expiry (jose) and the nonce. */
+export async function verifyOidcIdToken(provider, discovery, idToken, nonce, deps = {}) {
+    try {
+        const resolver = deps.jwksResolver?.(discovery.jwksUri) ?? createRemoteJWKSet(new URL(discovery.jwksUri));
+        const { payload } = await jwtVerify(idToken, resolver, {
+            issuer: provider.issuer,
+            audience: provider.clientId,
+        });
+        const tokenNonce = payload["nonce"];
+        if (typeof tokenNonce !== "string" || tokenNonce !== nonce) {
+            throw new SsoError("sso_identity_invalid", "id_token nonce mismatch");
+        }
+        const subject = payload.sub;
+        if (typeof subject !== "string" || subject.length === 0) {
+            throw new SsoError("sso_identity_invalid", "id_token has no subject");
+        }
+        const email = typeof payload["email"] === "string" ? payload["email"] : undefined;
+        const claim = readVerifiedClaim(payload["email_verified"]);
+        return {
+            subject,
+            ...(email === undefined ? {} : { email }),
+            emailVerified: claim ?? provider.assumeEmailVerified,
+        };
+    }
+    catch (error) {
+        if (error instanceof SsoError)
+            throw error;
+        throw new SsoError("sso_identity_invalid", "id_token verification failed", { cause: error });
+    }
+}
+async function fetchUserinfo(discovery, accessToken, fetch) {
+    if (discovery.userinfoEndpoint === undefined) {
+        throw new SsoError("sso_identity_invalid", "no userinfo endpoint");
+    }
+    let response;
+    try {
+        response = await fetch(discovery.userinfoEndpoint, {
+            method: "GET",
+            headers: { authorization: `Bearer ${accessToken}`, accept: "application/json" },
+        });
+    }
+    catch (error) {
+        throw new SsoError("sso_exchange_failed", "userinfo request failed", { cause: error });
+    }
+    if (!response.ok)
+        throw new SsoError("sso_exchange_failed", `userinfo ${response.status}`);
+    let payload;
+    try {
+        payload = await response.json();
+    }
+    catch (error) {
+        throw new SsoError("sso_exchange_failed", "userinfo is not JSON", { cause: error });
+    }
+    const record = readRecord(payload);
+    if (record === null)
+        throw new SsoError("sso_exchange_failed", "userinfo shape");
+    return record;
+}
+/**
+ * Resolves the OIDC identity: ID-token claims, with a userinfo fallback only when the email
+ * claim is absent. The userinfo `sub` must agree with the verified ID-token subject.
+ */
+export async function resolveOidcIdentity(provider, discovery, token, nonce, deps = {}) {
+    if (token.idToken === undefined)
+        throw new SsoError("sso_identity_invalid", "no id_token");
+    const claims = await verifyOidcIdToken(provider, discovery, token.idToken, nonce, deps);
+    let email = claims.email;
+    let emailVerified = claims.emailVerified;
+    if (email === undefined) {
+        const userinfo = await fetchUserinfo(discovery, token.accessToken, deps.fetch ?? runtimeFetch());
+        const userinfoSubject = readString(userinfo, "sub");
+        if (userinfoSubject !== undefined && userinfoSubject !== claims.subject) {
+            throw new SsoError("sso_identity_invalid", "userinfo subject mismatch");
+        }
+        email = readString(userinfo, "email");
+        emailVerified = readVerifiedClaim(userinfo["email_verified"]) ?? provider.assumeEmailVerified;
+    }
+    if (email === undefined || !EMAIL_PATTERN.test(email)) {
+        throw new SsoError("sso_identity_invalid", "no email claim");
+    }
+    return { provider: provider.id, subject: claims.subject, email, emailVerified };
+}

package/dist/sso/paths.d.ts

@@ -0,0 +1,14 @@
+/**
+ * URL helpers for the SSO flow (D-120), shared by the login orchestration and its tests.
+ *
+ * Kept out of login.ts so the orchestration stays under the 300-line limit; nothing here needs
+ * the flow dependencies, only the public origin and the single-use state row.
+ */
+/** Fallback after a login when the attempt carried no valid same-origin path. */
+export declare const DEFAULT_POST_LOGIN_PATH = "/";
+/** The callback URL registered at the IdP for one provider. */
+export declare function ssoCallbackUrl(publicOrigin: string, providerId: string): string;
+/** The post-login path for a state row; an absent or invalid value falls back to the app root. */
+export declare function postLoginPath(state: {
+    readonly redirectTo: string | null;
+}): string;

package/dist/sso/paths.js

@@ -0,0 +1,17 @@
+import { normalizeRedirectTo } from "./state.js";
+/**
+ * URL helpers for the SSO flow (D-120), shared by the login orchestration and its tests.
+ *
+ * Kept out of login.ts so the orchestration stays under the 300-line limit; nothing here needs
+ * the flow dependencies, only the public origin and the single-use state row.
+ */
+/** Fallback after a login when the attempt carried no valid same-origin path. */
+export const DEFAULT_POST_LOGIN_PATH = "/";
+/** The callback URL registered at the IdP for one provider. */
+export function ssoCallbackUrl(publicOrigin, providerId) {
+    return `${publicOrigin.replace(/\/+$/, "")}/api/auth/sso/${encodeURIComponent(providerId)}/callback`;
+}
+/** The post-login path for a state row; an absent or invalid value falls back to the app root. */
+export function postLoginPath(state) {
+    return normalizeRedirectTo(state.redirectTo) ?? DEFAULT_POST_LOGIN_PATH;
+}

package/dist/sso/pkce.d.ts

@@ -0,0 +1,6 @@
+export interface PkcePair {
+    readonly verifier: string;
+    readonly challenge: string;
+}
+/** PKCE S256 pair: a 43-character base64url verifier and its SHA-256 challenge. */
+export declare function createPkcePair(): Promise<PkcePair>;

package/dist/sso/pkce.js

@@ -0,0 +1,21 @@
+import { encodeBase64, randomToken, webcrypto } from "../crypto.js";
+/**
+ * PKCE (RFC 7636) for the authorization-code flows (D-120).
+ *
+ * Both OIDC and generic OAuth2 use S256 unconditionally: a provider that does not implement PKCE
+ * ignores the unknown parameters (RFC 6749), while a public `tokenAuth: "none"` client is
+ * protected against authorization-code interception. Kept in its own module so the OIDC flow
+ * and the login orchestration stay under the 300-line limit.
+ */
+function toBase64Url(bytes) {
+    return encodeBase64(bytes).replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");
+}
+async function s256(verifier) {
+    const digest = await webcrypto().subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+    return toBase64Url(new Uint8Array(digest));
+}
+/** PKCE S256 pair: a 43-character base64url verifier and its SHA-256 challenge. */
+export async function createPkcePair() {
+    const verifier = randomToken(32);
+    return { verifier, challenge: await s256(verifier) };
+}

package/dist/sso/providers.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Provider resolution against the environment (D-120).
+ *
+ * The config commits the ENV VAR NAMES that hold secrets; the values never appear in the project.
+ * A provider whose secret (or SAML certificate) is missing is unusable: it is hidden from the
+ * public list and a start attempt answers `sso_provider_unavailable`. The value itself is never
+ * read for logging, compared or echoed.
+ *
+ * The types here mirror the `auth.sso` section of facilis.config.ts structurally. @facilis.dev/core
+ * already validates that config and depends on @facilis.dev/auth, so auth cannot import the core
+ * types without a package cycle; a parsed core provider is assignable to these shapes.
+ */
+export type SsoProviderKind = "oidc" | "oauth2" | "saml";
+export type SsoTokenAuth = "client_secret_post" | "client_secret_basic" | "none";
+export interface SsoProviderBase {
+    readonly id: string;
+    readonly label?: string;
+    readonly autoProvision: boolean;
+    readonly defaultRole?: string;
+}
+export interface OidcProviderConfig extends SsoProviderBase {
+    readonly kind: "oidc";
+    readonly issuer: string;
+    readonly clientId: string;
+    readonly clientSecretEnv?: string;
+    readonly scopes: readonly string[];
+    readonly tokenAuth: SsoTokenAuth;
+    readonly assumeEmailVerified: boolean;
+}
+export interface Oauth2Mapping {
+    readonly subject: string;
+    readonly email: string;
+    readonly emailVerified?: string;
+}
+export interface Oauth2ProviderConfig extends SsoProviderBase {
+    readonly kind: "oauth2";
+    readonly authorizationEndpoint: string;
+    readonly tokenEndpoint: string;
+    readonly userinfoEndpoint: string;
+    readonly clientId: string;
+    readonly clientSecretEnv?: string;
+    readonly scopes: readonly string[];
+    readonly tokenAuth: SsoTokenAuth;
+    readonly mapping: Oauth2Mapping;
+    readonly assumeEmailVerified: boolean;
+}
+export interface SamlProviderConfig extends SsoProviderBase {
+    readonly kind: "saml";
+    readonly entryPoint: string;
+    /** SP entity id declared to the IdP, and the expected assertion audience. */
+    readonly issuer: string;
+    readonly certificateEnv: string;
+    readonly emailAttribute: string;
+    readonly wantAssertionsSigned: boolean;
+    readonly wantResponseSigned: boolean;
+}
+export type SsoProviderConfig = OidcProviderConfig | Oauth2ProviderConfig | SamlProviderConfig;
+/**
+ * The identity-policy projection of a provider: exactly the fields identity resolution needs,
+ * so the flow never hands the whole config (and its secrets) to the linking code.
+ */
+export declare function identityPolicy(config: SsoProviderConfig): {
+    readonly id: string;
+    readonly autoProvision: boolean;
+    readonly defaultRole?: string;
+};
+/** Structural shape of `config.auth.sso` after defineConfig applied its defaults. */
+export interface SsoConfigLike {
+    readonly providers: readonly SsoProviderConfig[];
+    readonly failureRedirect: string;
+    readonly stateTtlMs: number;
+}
+/** What the login page may see: no secret, no endpoint beyond the framework start URL. */
+export interface PublicSsoProvider {
+    readonly id: string;
+    readonly label: string;
+    readonly kind: SsoProviderKind;
+    /** Framework-owned start URL, always relative to the application origin. */
+    readonly startUrl: string;
+}
+/** A provider plus the environment values the flow needs; never serialised. */
+export interface ResolvedSsoProvider {
+    readonly config: SsoProviderConfig;
+    readonly clientSecret?: string;
+    readonly idpCertificate?: string;
+}
+export declare const SSO_NAMESPACE = "/api/auth/sso";
+/** The environment variable whose absence makes a provider unusable, if any. */
+export declare function missingCredentialEnv(provider: SsoProviderConfig): string | undefined;
+/** True when every environment value this provider needs is present. */
+export declare function isProviderConfigured(provider: SsoProviderConfig, environment?: Readonly<Record<string, string | undefined>>): boolean;
+/** The public list rendered by the login page; unconfigured providers are omitted. */
+export declare function publicProviderList(config: SsoConfigLike, environment?: Readonly<Record<string, string | undefined>>): PublicSsoProvider[];
+/**
+ * Finds a configured provider and reads its environment secret(s).
+ *
+ * Unknown provider => `sso_provider_unknown`; a known provider missing its env value =>
+ * `sso_provider_unavailable` (the caller logs a warning with the ENV VAR NAME only).
+ */
+export declare function resolveProvider(config: SsoConfigLike, id: string, environment?: Readonly<Record<string, string | undefined>>): ResolvedSsoProvider;

package/dist/sso/providers.js

@@ -0,0 +1,70 @@
+import { SsoError } from "./errors.js";
+/**
+ * The identity-policy projection of a provider: exactly the fields identity resolution needs,
+ * so the flow never hands the whole config (and its secrets) to the linking code.
+ */
+export function identityPolicy(config) {
+    return {
+        id: config.id,
+        autoProvision: config.autoProvision,
+        ...(config.defaultRole === undefined ? {} : { defaultRole: config.defaultRole }),
+    };
+}
+export const SSO_NAMESPACE = "/api/auth/sso";
+/** The environment variable whose absence makes a provider unusable, if any. */
+export function missingCredentialEnv(provider) {
+    if (provider.kind === "saml")
+        return provider.certificateEnv;
+    if (provider.tokenAuth === "none")
+        return undefined;
+    return provider.clientSecretEnv;
+}
+function readEnv(name, environment) {
+    if (name === undefined)
+        return undefined;
+    const value = environment[name];
+    return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+/** True when every environment value this provider needs is present. */
+export function isProviderConfigured(provider, environment = process.env) {
+    if (provider.kind === "saml") {
+        return readEnv(provider.certificateEnv, environment) !== undefined;
+    }
+    if (provider.tokenAuth === "none")
+        return true;
+    return readEnv(provider.clientSecretEnv, environment) !== undefined;
+}
+/** The public list rendered by the login page; unconfigured providers are omitted. */
+export function publicProviderList(config, environment = process.env) {
+    return config.providers
+        .filter((provider) => isProviderConfigured(provider, environment))
+        .map((provider) => ({
+        id: provider.id,
+        label: provider.label ?? provider.id,
+        kind: provider.kind,
+        startUrl: `${SSO_NAMESPACE}/${encodeURIComponent(provider.id)}/start`,
+    }));
+}
+/**
+ * Finds a configured provider and reads its environment secret(s).
+ *
+ * Unknown provider => `sso_provider_unknown`; a known provider missing its env value =>
+ * `sso_provider_unavailable` (the caller logs a warning with the ENV VAR NAME only).
+ */
+export function resolveProvider(config, id, environment = process.env) {
+    const provider = config.providers.find((candidate) => candidate.id === id);
+    if (provider === undefined)
+        throw new SsoError("sso_provider_unknown");
+    if (provider.kind === "saml") {
+        const idpCertificate = readEnv(provider.certificateEnv, environment);
+        if (idpCertificate === undefined)
+            throw new SsoError("sso_provider_unavailable");
+        return { config: provider, idpCertificate };
+    }
+    if (provider.tokenAuth === "none")
+        return { config: provider };
+    const clientSecret = readEnv(provider.clientSecretEnv, environment);
+    if (clientSecret === undefined)
+        throw new SsoError("sso_provider_unavailable");
+    return { config: provider, clientSecret };
+}