@facilis.dev/auth 0.0.0-stage → 0.1.1

package/dist/sso/identity.js

@@ -0,0 +1,162 @@
+import { and, eq, sql } from "drizzle-orm";
+import { SsoError } from "./errors.js";
+import { authIdentities } from "./tables.js";
+import { normalizeEmail } from "../email.js";
+import { users, userRoles } from "../tables.js";
+/**
+ * Account linking and JIT provisioning (D-120).
+ *
+ * The identity key is `(provider, subject)`: a changed email never breaks an existing link.
+ * Without a link, the asserted email must be verified before it can match a user, and a user is
+ * only created when the provider's `autoProvision` allows it. Every read/write happens inside the
+ * caller's audited `ctx.system` elevation — never on a raw client (D-099).
+ *
+ * Races are handled with the unique keys the schema already has: `(provider, subject)` for the
+ * identity and `users.email` for the user, both `ON CONFLICT DO NOTHING` followed by a re-read.
+ */
+export const IDENTITY_TABLES = ["auth_identities", "users", "user_roles"];
+const IDENTITY_ELEVATION = {
+    actor: "system:auth:sso",
+    operation: "auth:sso:identity:resolve",
+    reason: "Linking or provisioning the user happens before the SSO session exists.",
+    tables: IDENTITY_TABLES,
+};
+function roleFor(provider, options) {
+    return provider.defaultRole ?? options.defaultRole;
+}
+async function findIdentityUserId(db, provider, subject) {
+    const rows = await db
+        .select({ userId: authIdentities.userId })
+        .from(authIdentities)
+        .where(and(eq(authIdentities.provider, provider), eq(authIdentities.subject, subject)))
+        .limit(1);
+    return rows[0]?.userId ?? null;
+}
+async function findUserByEmail(db, email) {
+    const rows = await db
+        .select({
+        id: users.id,
+        passwordHash: users.passwordHash,
+        emailVerifiedAt: users.emailVerifiedAt,
+    })
+        .from(users)
+        .where(sql `lower(${users.email}) = ${normalizeEmail(email)}`)
+        .limit(1);
+    return rows[0] ?? null;
+}
+/**
+ * A service account exists only to back an API client: it must never complete an interactive
+ * login. The generic `sso_account_not_found` is deliberate — the flow must not become a probe
+ * for which addresses belong to a service identity.
+ */
+async function assertLoginable(db, userId) {
+    const rows = await db
+        .select({ isService: users.isService })
+        .from(users)
+        .where(eq(users.id, userId))
+        .limit(1);
+    if (rows[0]?.isService === true)
+        throw new SsoError("sso_account_not_found");
+}
+async function touchIdentity(db, claims, now) {
+    await db
+        .update(authIdentities)
+        .set({ email: normalizeEmail(claims.email), lastLoginAt: now })
+        .where(and(eq(authIdentities.provider, claims.provider), eq(authIdentities.subject, claims.subject)));
+}
+/**
+ * Resolves the Facilis user for a verified identity.
+ *
+ * Throws `sso_email_unverified` for an unverified email that has no existing link and
+ * `sso_account_not_found` when provisioning is disabled; both are safe to redirect.
+ */
+export async function resolveIdentity(system, claims, provider, options, now = new Date()) {
+    return system(IDENTITY_ELEVATION, async (db) => {
+        const linked = await findIdentityUserId(db, claims.provider, claims.subject);
+        if (linked !== null) {
+            await assertLoginable(db, linked);
+            await touchIdentity(db, claims, now);
+            return { userId: linked, outcome: "existing" };
+        }
+        // An unverified email must never link to (or provision) an account: that is account takeover.
+        if (!claims.emailVerified)
+            throw new SsoError("sso_email_unverified");
+        const existingUser = await findUserByEmail(db, claims.email);
+        if (existingUser !== null) {
+            await assertLoginable(db, existingUser.id);
+            // Account pre-hijacking (SEC-02): a pending password account was registered by someone
+            // who never proved they own the address, and with email verification enabled it cannot
+            // even log in. The verified IdP email IS that proof now, so the identity claims the
+            // account and the placeholder password is removed before linking (D-156): whoever
+            // registered the address first loses it, the mailbox owner keeps it. A verified password
+            // account belongs to the same proven mailbox and links without clearing anything.
+            const claimed = existingUser.passwordHash !== null && existingUser.emailVerifiedAt === null;
+            if (claimed) {
+                // With verification disabled the account was never meant to prove its mailbox: refuse
+                // rather than silently reset a password its owner may still use (D-156).
+                if (!options.claimUnverifiedPasswordAccount)
+                    throw new SsoError("sso_email_conflict");
+                await db
+                    .update(users)
+                    .set({ passwordHash: null, emailVerifiedAt: now })
+                    .where(eq(users.id, existingUser.id));
+            }
+            const inserted = await db
+                .insert(authIdentities)
+                .values({
+                provider: claims.provider,
+                subject: claims.subject,
+                userId: existingUser.id,
+                email: normalizeEmail(claims.email),
+            })
+                .onConflictDoNothing()
+                .returning({ userId: authIdentities.userId });
+            const raced = inserted[0]?.userId ?? (await findIdentityUserId(db, claims.provider, claims.subject));
+            if (raced === null)
+                throw new SsoError("sso_internal_error", "identity link race");
+            await touchIdentity(db, claims, now);
+            options.audit({
+                operation: "auth:sso:link",
+                outcome: "succeeded",
+                tables: claimed ? ["auth_identities", "users"] : ["auth_identities"],
+                details: {
+                    provider: claims.provider,
+                    ...(claimed ? { claimed: "unverified_password" } : {}),
+                },
+            });
+            return { userId: raced, outcome: "linked" };
+        }
+        if (!provider.autoProvision)
+            throw new SsoError("sso_account_not_found");
+        const role = roleFor(provider, options);
+        const created = await db
+            .insert(users)
+            .values({ email: normalizeEmail(claims.email), passwordHash: null })
+            .onConflictDoNothing()
+            .returning({ id: users.id });
+        const userId = created[0]?.id ?? (await findUserByEmail(db, claims.email))?.id ?? null;
+        if (userId === null)
+            throw new SsoError("sso_internal_error", "user provision race");
+        await db.insert(userRoles).values({ userId, role }).onConflictDoNothing();
+        const identity = await db
+            .insert(authIdentities)
+            .values({
+            provider: claims.provider,
+            subject: claims.subject,
+            userId,
+            email: normalizeEmail(claims.email),
+        })
+            .onConflictDoNothing()
+            .returning({ userId: authIdentities.userId });
+        const resolved = identity[0]?.userId ?? (await findIdentityUserId(db, claims.provider, claims.subject));
+        if (resolved === null)
+            throw new SsoError("sso_internal_error", "identity provision race");
+        options.audit({
+            operation: "auth:sso:provision",
+            outcome: "succeeded",
+            tables: ["users", "user_roles", "auth_identities"],
+            details: { provider: claims.provider, role },
+        });
+        return { userId: resolved, outcome: "provisioned" };
+    });
+}

package/dist/sso/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * SSO (D-120): OIDC, generic OAuth2 and SAML as framework auth.
+ *
+ * Root re-exports only; the implementation is split by concern under this directory.
+ */
+export { authIdentities, authSsoStates } from "./tables.js";
+export type { AuthIdentityRow, AuthSsoStateRow, NewAuthIdentityRow, NewAuthSsoStateRow, } from "./tables.js";
+export { SSO_ERROR_CODES, failureRedirectPath, isSsoError, SsoError, ssoErrorCode, } from "./errors.js";
+export type { SsoErrorCode } from "./errors.js";
+export { isProviderConfigured, missingCredentialEnv, publicProviderList, resolveProvider, SSO_NAMESPACE, } from "./providers.js";
+export type { Oauth2Mapping, Oauth2ProviderConfig, OidcProviderConfig, PublicSsoProvider, ResolvedSsoProvider, SamlProviderConfig, SsoConfigLike, SsoProviderBase, SsoProviderConfig, SsoProviderKind, SsoTokenAuth, } from "./providers.js";
+export { consumeSsoState, createSsoState, MAX_REDIRECT_TO, normalizeRedirectTo } from "./state.js";
+export type { CreateSsoStateInput } from "./state.js";
+export { buildOidcAuthorizeUrl, clearOidcDiscoveryCache, discoverOidc, exchangeOidcCode, OIDC_DISCOVERY_TTL_MS, resolveOidcIdentity, verifyOidcIdToken, } from "./oidc.js";
+export { createPkcePair } from "./pkce.js";
+export type { OidcAuthorizeInput, OidcClaims, OidcDeps, OidcDiscovery, OidcTokenInput, } from "./oidc.js";
+export type { PkcePair } from "./pkce.js";
+export { buildOauth2AuthorizeUrl, exchangeOauth2Code, readDottedPath, readVerifiedClaim, requestToken, resolveOauth2Identity, resolveOauth2IdentityFromCode, } from "./oauth2.js";
+export type { Oauth2Identity, Oauth2TokenInput, RequestTokenInput, TokenClientConfig, TokenPayload, } from "./oauth2.js";
+export { buildAuthnRequestXml, buildSamlRedirect, validateSamlResponse } from "./saml.js";
+export type { BuiltSamlRequest, SamlProfileLike, SamlValidator, SamlValidatorFactory, ValidateSamlInput, } from "./saml.js";
+export { IDENTITY_TABLES, resolveIdentity } from "./identity.js";
+export type { IdentityOutcome, IdentityProviderPolicy, IdentityResolution, ResolveIdentityOptions, } from "./identity.js";
+export { completeLogin, startLogin } from "./login.js";
+export { DEFAULT_POST_LOGIN_PATH, postLoginPath, ssoCallbackUrl } from "./paths.js";
+export type { CompleteLoginInput, CompleteLoginResult, SsoFlowDeps } from "./login.js";
+export type { FetchInit, FetchLike, FetchResponse, IdentityClaims, SsoAudit, SsoAuditInput, SystemElevationOptions, SystemRunner, } from "./contracts.js";

package/dist/sso/index.js

@@ -0,0 +1,16 @@
+/**
+ * SSO (D-120): OIDC, generic OAuth2 and SAML as framework auth.
+ *
+ * Root re-exports only; the implementation is split by concern under this directory.
+ */
+export { authIdentities, authSsoStates } from "./tables.js";
+export { SSO_ERROR_CODES, failureRedirectPath, isSsoError, SsoError, ssoErrorCode, } from "./errors.js";
+export { isProviderConfigured, missingCredentialEnv, publicProviderList, resolveProvider, SSO_NAMESPACE, } from "./providers.js";
+export { consumeSsoState, createSsoState, MAX_REDIRECT_TO, normalizeRedirectTo } from "./state.js";
+export { buildOidcAuthorizeUrl, clearOidcDiscoveryCache, discoverOidc, exchangeOidcCode, OIDC_DISCOVERY_TTL_MS, resolveOidcIdentity, verifyOidcIdToken, } from "./oidc.js";
+export { createPkcePair } from "./pkce.js";
+export { buildOauth2AuthorizeUrl, exchangeOauth2Code, readDottedPath, readVerifiedClaim, requestToken, resolveOauth2Identity, resolveOauth2IdentityFromCode, } from "./oauth2.js";
+export { buildAuthnRequestXml, buildSamlRedirect, validateSamlResponse } from "./saml.js";
+export { IDENTITY_TABLES, resolveIdentity } from "./identity.js";
+export { completeLogin, startLogin } from "./login.js";
+export { DEFAULT_POST_LOGIN_PATH, postLoginPath, ssoCallbackUrl } from "./paths.js";

package/dist/sso/login.d.ts

@@ -0,0 +1,60 @@
+import type { FetchLike, SsoAudit, SystemRunner } from "./contracts.js";
+import { type IdentityResolution } from "./identity.js";
+import { type OidcDeps } from "./oidc.js";
+import { type SsoConfigLike } from "./providers.js";
+import { type SamlValidatorFactory } from "./saml.js";
+/**
+ * The two ends of an SSO login (D-120): start builds the IdP redirect and stores the single-use
+ * attempt; complete consumes that attempt, resolves the identity and returns the user.
+ *
+ * The route owns the HTTP envelope (302, cookie, failure redirect); this module owns the protocol
+ * and never exposes an internal message. Every failure is an {@link SsoError} whose code is safe
+ * to append to `failureRedirect`.
+ */
+export interface SsoFlowDeps {
+    /** `config.auth.sso` after defaults. */
+    readonly sso: SsoConfigLike;
+    /** `config.auth.defaultRole`: the role a provisioned user gets without a provider override. */
+    readonly defaultRole: string;
+    /** `config.auth.verification.enabled`: allows the SSO identity to claim a pending account. */
+    readonly verificationEnabled: boolean;
+    /** Deployment origin (`FACILIS_PUBLIC_ORIGIN` or the request origin), no trailing slash. */
+    readonly publicOrigin: string;
+    readonly system: SystemRunner;
+    readonly audit: SsoAudit;
+    readonly fetch?: FetchLike;
+    readonly now?: () => number;
+    readonly environment?: Readonly<Record<string, string | undefined>>;
+    /** Diagnostic line for an unusable provider; must never receive a secret value. */
+    readonly warn?: (message: string, data: Record<string, unknown>) => void;
+    /** Test seam for discovery/JWKS; defaults to the flow's fetch/now. */
+    readonly oidc?: OidcDeps;
+    /** Test seam for the lazily imported SAML validator. */
+    readonly samlValidatorFactory?: SamlValidatorFactory;
+}
+/** Starts a login and returns the IdP URL; the attempt is stored as one single-use row. */
+export declare function startLogin(deps: SsoFlowDeps, input: {
+    readonly providerId: string;
+    readonly redirectTo: string | null;
+}): Promise<{
+    readonly redirectUrl: string;
+}>;
+export type CompleteLoginInput = {
+    readonly method: "GET";
+    readonly code: string;
+    readonly state: string;
+} | {
+    readonly method: "POST";
+    readonly samlResponse: string;
+    readonly relayState: string;
+};
+export interface CompleteLoginResult {
+    readonly userId: string;
+    readonly redirectTo: string;
+    readonly resolution: IdentityResolution;
+}
+/**
+ * Completes a login: consumes the single-use state, exchanges the code/assertion and resolves the
+ * identity. A failure is rethrown as the safe code the route turns into a redirect.
+ */
+export declare function completeLogin(deps: SsoFlowDeps, providerId: string, input: CompleteLoginInput): Promise<CompleteLoginResult>;

package/dist/sso/login.js

@@ -0,0 +1,209 @@
+import { randomToken } from "../crypto.js";
+import { isSsoError, SsoError, ssoErrorCode } from "./errors.js";
+import { resolveIdentity } from "./identity.js";
+import { buildOidcAuthorizeUrl, discoverOidc, exchangeOidcCode, resolveOidcIdentity, } from "./oidc.js";
+import { buildOauth2AuthorizeUrl, resolveOauth2IdentityFromCode } from "./oauth2.js";
+import { createPkcePair } from "./pkce.js";
+import { postLoginPath, ssoCallbackUrl } from "./paths.js";
+import { identityPolicy, missingCredentialEnv, resolveProvider, } from "./providers.js";
+import { buildSamlRedirect, validateSamlResponse } from "./saml.js";
+import { consumeSsoState, createSsoState, normalizeRedirectTo } from "./state.js";
+function oidcDeps(deps) {
+    if (deps.oidc !== undefined)
+        return deps.oidc;
+    return {
+        ...(deps.fetch === undefined ? {} : { fetch: deps.fetch }),
+        ...(deps.now === undefined ? {} : { now: deps.now }),
+    };
+}
+function resolve(deps, providerId) {
+    try {
+        return resolveProvider(deps.sso, providerId, deps.environment ?? process.env);
+    }
+    catch (error) {
+        if (isSsoError(error) && error.code === "sso_provider_unavailable") {
+            const provider = deps.sso.providers.find((candidate) => candidate.id === providerId);
+            const envName = provider === undefined ? undefined : missingCredentialEnv(provider);
+            // The warning names the provider and the ENV VAR, never its value (D-120).
+            deps.warn?.("sso provider is not configured", {
+                provider: providerId,
+                ...(envName === undefined ? {} : { env: envName }),
+            });
+        }
+        throw error;
+    }
+}
+function nowOf(deps) {
+    return deps.now?.() ?? Date.now();
+}
+function tokenClient(config, secret) {
+    if (config.kind === "saml")
+        throw new SsoError("sso_state_invalid");
+    return {
+        clientId: config.clientId,
+        tokenAuth: config.tokenAuth,
+        ...(secret === undefined ? {} : { clientSecret: secret }),
+    };
+}
+async function startRedirect(deps, input, provider) {
+    const config = provider.config;
+    const redirectTo = normalizeRedirectTo(input.redirectTo);
+    const now = nowOf(deps);
+    const redirectUri = ssoCallbackUrl(deps.publicOrigin, config.id);
+    if (config.kind === "saml") {
+        const state = randomToken(32);
+        const built = await buildSamlRedirect(config, redirectUri, state, now);
+        await createSsoState(deps.system, {
+            provider: config.id,
+            ttlMs: deps.sso.stateTtlMs,
+            redirectTo,
+            requestId: built.requestId,
+            state,
+        }, now);
+        return built.redirectUrl;
+    }
+    if (config.kind === "oidc") {
+        const discovery = await discoverOidc(config, oidcDeps(deps));
+        const pkce = await createPkcePair();
+        const nonce = randomToken(32);
+        const state = await createSsoState(deps.system, {
+            provider: config.id,
+            ttlMs: deps.sso.stateTtlMs,
+            redirectTo,
+            nonce,
+            codeVerifier: pkce.verifier,
+        }, now);
+        return buildOidcAuthorizeUrl(config, discovery, {
+            redirectUri,
+            state: state.state,
+            nonce,
+            codeChallenge: pkce.challenge,
+        });
+    }
+    const pkce = await createPkcePair();
+    const state = await createSsoState(deps.system, {
+        provider: config.id,
+        ttlMs: deps.sso.stateTtlMs,
+        redirectTo,
+        codeVerifier: pkce.verifier,
+    }, now);
+    return buildOauth2AuthorizeUrl(config, redirectUri, state.state, pkce.challenge);
+}
+/** Starts a login and returns the IdP URL; the attempt is stored as one single-use row. */
+export async function startLogin(deps, input) {
+    try {
+        const provider = resolve(deps, input.providerId);
+        const redirectUrl = await startRedirect(deps, input, provider);
+        deps.audit({
+            operation: "auth:sso:start",
+            outcome: "succeeded",
+            details: { provider: input.providerId },
+        });
+        return { redirectUrl };
+    }
+    catch (error) {
+        deps.audit({
+            operation: "auth:sso:start",
+            outcome: "failed",
+            errorCode: ssoErrorCode(error),
+            details: { provider: input.providerId },
+        });
+        throw error;
+    }
+}
+async function claimsFromCode(deps, provider, code, state) {
+    const config = provider.config;
+    if (state.provider !== config.id)
+        throw new SsoError("sso_state_invalid");
+    if (config.kind === "oidc") {
+        if (state.nonce === null || state.codeVerifier === null)
+            throw new SsoError("sso_state_invalid");
+        const discovery = await discoverOidc(config, oidcDeps(deps));
+        const token = await exchangeOidcCode(tokenClient(config, provider.clientSecret), discovery, {
+            code,
+            redirectUri: ssoCallbackUrl(deps.publicOrigin, config.id),
+            codeVerifier: state.codeVerifier,
+            ...(deps.fetch === undefined ? {} : { fetch: deps.fetch }),
+        });
+        return resolveOidcIdentity(config, discovery, token, state.nonce, oidcDeps(deps));
+    }
+    if (config.kind === "oauth2") {
+        if (state.codeVerifier === null)
+            throw new SsoError("sso_state_invalid");
+        const identity = await resolveOauth2IdentityFromCode(tokenClient(config, provider.clientSecret), config, {
+            code,
+            redirectUri: ssoCallbackUrl(deps.publicOrigin, config.id),
+            codeVerifier: state.codeVerifier,
+            ...(deps.fetch === undefined ? {} : { fetch: deps.fetch }),
+        });
+        return { provider: config.id, ...identity };
+    }
+    throw new SsoError("sso_state_invalid");
+}
+async function completeGet(deps, provider, input) {
+    const state = await consumeSsoState(deps.system, input.state, nowOf(deps));
+    const claims = await claimsFromCode(deps, provider, input.code, state);
+    const resolution = await resolveIdentity(deps.system, claims, identityPolicy(provider.config), {
+        defaultRole: deps.defaultRole,
+        claimUnverifiedPasswordAccount: deps.verificationEnabled,
+        audit: deps.audit,
+    });
+    return { userId: resolution.userId, redirectTo: postLoginPath(state), resolution };
+}
+async function completePost(deps, provider, input) {
+    const config = provider.config;
+    if (config.kind !== "saml")
+        throw new SsoError("sso_state_invalid");
+    const state = await consumeSsoState(deps.system, input.relayState, nowOf(deps));
+    if (state.provider !== config.id)
+        throw new SsoError("sso_state_invalid");
+    const claims = await validateSamlResponse({
+        provider: config,
+        certificate: provider.idpCertificate ?? "",
+        callbackUrl: ssoCallbackUrl(deps.publicOrigin, config.id),
+        samlResponse: input.samlResponse,
+        requestId: state.requestId,
+        ...(deps.samlValidatorFactory === undefined
+            ? {}
+            : { validatorFactory: deps.samlValidatorFactory }),
+    });
+    const resolution = await resolveIdentity(deps.system, claims, identityPolicy(config), {
+        defaultRole: deps.defaultRole,
+        claimUnverifiedPasswordAccount: deps.verificationEnabled,
+        audit: deps.audit,
+    });
+    return { userId: resolution.userId, redirectTo: postLoginPath(state), resolution };
+}
+/**
+ * Completes a login: consumes the single-use state, exchanges the code/assertion and resolves the
+ * identity. A failure is rethrown as the safe code the route turns into a redirect.
+ */
+export async function completeLogin(deps, providerId, input) {
+    try {
+        const provider = resolve(deps, providerId);
+        if (input.method === "POST" && provider.config.kind !== "saml") {
+            throw new SsoError("sso_state_invalid");
+        }
+        if (input.method === "GET" && provider.config.kind === "saml") {
+            throw new SsoError("sso_state_invalid");
+        }
+        const result = input.method === "POST"
+            ? await completePost(deps, provider, input)
+            : await completeGet(deps, provider, input);
+        deps.audit({
+            operation: "auth:sso:login",
+            outcome: "succeeded",
+            details: { provider: providerId },
+        });
+        return result;
+    }
+    catch (error) {
+        deps.audit({
+            operation: "auth:sso:login",
+            outcome: "failed",
+            errorCode: ssoErrorCode(error),
+            details: { provider: providerId },
+        });
+        throw error;
+    }
+}

package/dist/sso/oauth2.d.ts

@@ -0,0 +1,52 @@
+import { type FetchLike } from "./contracts.js";
+import type { Oauth2ProviderConfig, SsoTokenAuth } from "./providers.js";
+export interface TokenPayload {
+    readonly accessToken: string;
+    readonly idToken?: string;
+}
+/** The subset of a provider the token endpoint needs; OIDC and OAuth2 share it. */
+export interface TokenClientConfig {
+    readonly clientId: string;
+    readonly clientSecret?: string;
+    readonly tokenAuth: SsoTokenAuth;
+}
+export interface RequestTokenInput {
+    readonly endpoint: string;
+    readonly client: TokenClientConfig;
+    readonly form: Readonly<Record<string, string>>;
+    readonly fetch?: FetchLike;
+}
+/**
+ * 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 declare function requestToken(input: RequestTokenInput): Promise<TokenPayload>;
+/** Reads a dotted path (`data.user.email`) out of parsed userinfo JSON. */
+export declare function readDottedPath(value: unknown, path: string): unknown;
+/** Truthiness of a verification claim: boolean true or the string "true" only. */
+export declare function readVerifiedClaim(value: unknown): boolean | undefined;
+/**
+ * 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 declare function buildOauth2AuthorizeUrl(provider: Oauth2ProviderConfig, redirectUri: string, state: string, codeChallenge: string): string;
+export interface Oauth2TokenInput {
+    readonly code: string;
+    readonly redirectUri: string;
+    /** PKCE verifier stored in the single-use state row; required, like the OIDC flow. */
+    readonly codeVerifier: string;
+    readonly fetch?: FetchLike;
+}
+export declare function exchangeOauth2Code(client: TokenClientConfig, provider: Oauth2ProviderConfig, input: Oauth2TokenInput): Promise<TokenPayload>;
+export interface Oauth2Identity {
+    readonly subject: string;
+    readonly email: string;
+    readonly emailVerified: boolean;
+}
+/** Maps the userinfo JSON onto the identity key via the configured dotted paths. */
+export declare function resolveOauth2Identity(provider: Oauth2ProviderConfig, userinfo: Record<string, unknown>): Oauth2Identity;
+/** Token exchange + userinfo + mapping, the complete generic-OAuth2 identity resolution. */
+export declare function resolveOauth2IdentityFromCode(client: TokenClientConfig, provider: Oauth2ProviderConfig, input: Oauth2TokenInput): Promise<Oauth2Identity>;