@revealui/auth 0.5.0 → 0.5.2

package/dist/server/sso/__tests__/helpers/mock-saml-idp.js

@@ -0,0 +1,150 @@
+/**
+ * Minimal mock SAML IdP for GAP-464 integration tests.
+ * Self-signed X509 + xml-crypto enveloped signatures on Response + Assertion.
+ */
+import { randomBytes } from 'node:crypto';
+import selfsigned from 'selfsigned';
+import { SignedXml } from 'xml-crypto';
+function stripPemHeaders(pem) {
+    const lines = pem.split('\n');
+    const body = [];
+    for (const line of lines) {
+        const t = line.trim();
+        if (!t || t.startsWith('-----'))
+            continue;
+        body.push(t);
+    }
+    return body.join('');
+}
+function escapeXml(value) {
+    return value
+        .replaceAll('&', '&')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;')
+        .replaceAll("'", '&apos;');
+}
+export function createMockSamlIdp(options) {
+    const entityId = options?.entityId ?? 'https://saml-idp.example.com';
+    const ssoUrl = `${entityId}/sso`;
+    const attrs = [{ name: 'commonName', value: 'mock-saml-idp' }];
+    const pems = selfsigned.generate(attrs, {
+        keySize: 2048,
+        days: 1,
+        algorithm: 'sha256',
+    });
+    const idpPrivateKeyPem = pems.private;
+    const certPem = pems.cert;
+    const certBody = stripPemHeaders(certPem);
+    const metadataXml = `<?xml version="1.0"?>
+<EntityDescriptor entityID="${escapeXml(entityId)}" xmlns="urn:oasis:names:tc:SAML:2.0:metadata">
+  <IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
+    <KeyDescriptor use="signing">
+      <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
+        <X509Data>
+          <X509Certificate>${certBody}</X509Certificate>
+        </X509Data>
+      </KeyInfo>
+    </KeyDescriptor>
+    <SingleSignOnService
+      Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
+      Location="${escapeXml(ssoUrl)}" />
+  </IDPSSODescriptor>
+</EntityDescriptor>`;
+    function buildUnsignedAssertion(input) {
+        const groupAttrs = input.groups
+            .map((g) => `<saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">${escapeXml(g)}</saml:AttributeValue>`)
+            .join('');
+        return `<saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" Version="2.0" ID="${input.assertionId}" IssueInstant="${input.issueInstant}">
+  <saml:Issuer>${escapeXml(entityId)}</saml:Issuer>
+  <saml:Subject>
+    <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">${escapeXml(input.nameId)}</saml:NameID>
+    <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
+      <saml:SubjectConfirmationData NotOnOrAfter="${input.notOnOrAfter}" Recipient="${escapeXml(input.acsUrl)}" />
+    </saml:SubjectConfirmation>
+  </saml:Subject>
+  <saml:Conditions NotBefore="${input.issueInstant}" NotOnOrAfter="${input.notOnOrAfter}">
+    <saml:AudienceRestriction>
+      <saml:Audience>${escapeXml(input.spEntityId)}</saml:Audience>
+    </saml:AudienceRestriction>
+  </saml:Conditions>
+  <saml:AuthnStatement AuthnInstant="${input.issueInstant}" SessionIndex="_session1">
+    <saml:AuthnContext>
+      <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml:AuthnContextClassRef>
+    </saml:AuthnContext>
+  </saml:AuthnStatement>
+  <saml:AttributeStatement>
+    <saml:Attribute Name="email">
+      <saml:AttributeValue>${escapeXml(input.nameId)}</saml:AttributeValue>
+    </saml:Attribute>
+    <saml:Attribute Name="groups">${groupAttrs}</saml:Attribute>
+  </saml:AttributeStatement>
+</saml:Assertion>`;
+    }
+    function signXmlEnveloped(xml, idAttr) {
+        // Place Signature immediately after Issuer (valid for both Assertion and Response)
+        const issuerPath = "/*[local-name()='Assertion' or local-name()='Response']/*[local-name()='Issuer']";
+        const refPath = `//*[@ID='${idAttr}']`;
+        const sig = new SignedXml({
+            privateKey: idpPrivateKeyPem,
+            publicCert: certPem,
+        });
+        sig.addReference({
+            xpath: refPath,
+            transforms: [
+                'http://www.w3.org/2000/09/xmldsig#enveloped-signature',
+                'http://www.w3.org/2001/10/xml-exc-c14n#',
+            ],
+            digestAlgorithm: 'http://www.w3.org/2001/04/xmlenc#sha256',
+        });
+        sig.signatureAlgorithm = 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256';
+        sig.canonicalizationAlgorithm = 'http://www.w3.org/2001/10/xml-exc-c14n#';
+        sig.computeSignature(xml, {
+            location: { reference: issuerPath, action: 'after' },
+            prefix: 'ds',
+        });
+        return sig.getSignedXml();
+    }
+    function buildPostResponse(input) {
+        const shouldSign = input.sign !== false;
+        const now = new Date();
+        const issueInstant = now.toISOString().replace(/\.\d{3}Z$/, 'Z');
+        const notOnOrAfter = new Date(now.getTime() + (input.notOnOrAfterOffsetMs ?? 5 * 60 * 1000))
+            .toISOString()
+            .replace(/\.\d{3}Z$/, 'Z');
+        const responseId = `_resp_${randomBytes(8).toString('hex')}`;
+        const assertionId = `_assert_${randomBytes(8).toString('hex')}`;
+        const groups = input.groups ?? ['Engineering'];
+        let assertion = buildUnsignedAssertion({
+            spEntityId: input.spEntityId,
+            acsUrl: input.acsUrl,
+            nameId: input.nameId,
+            groups,
+            issueInstant,
+            notOnOrAfter,
+            assertionId,
+        });
+        if (shouldSign) {
+            assertion = signXmlEnveloped(assertion, assertionId);
+        }
+        let response = `<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" Version="2.0" ID="${responseId}" IssueInstant="${issueInstant}" Destination="${escapeXml(input.acsUrl)}">
+  <saml:Issuer>${escapeXml(entityId)}</saml:Issuer>
+  <samlp:Status>
+    <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
+  </samlp:Status>
+  ${assertion}
+</samlp:Response>`;
+        if (shouldSign) {
+            response = signXmlEnveloped(response, responseId);
+        }
+        return Buffer.from(response, 'utf8').toString('base64');
+    }
+    return {
+        entityId,
+        ssoUrl,
+        certPem,
+        privateKeyPem: idpPrivateKeyPem,
+        metadataXml,
+        buildPostResponse,
+    };
+}

package/dist/server/sso/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Enterprise SSO pure layer (GAP-464).
+ *
+ * OIDC discovery + id_token validation, code exchange, SAML SP helpers,
+ * signed SSO state, group→role mapping, JIT user upsert. HTTP routes +
+ * account entitlement gate live in apps/server.
+ */
+export { normalizeSsoUserRole, type UpsertSsoUserInput, upsertSsoUser, } from './jit.js';
+export { type BuildOidcAuthorizationUrlInput, buildOidcAuthorizationUrl, createOidcRemoteJwkSet, type ExchangeOidcCodeFailureReason, type ExchangeOidcCodeInput, type ExchangeOidcCodeResult, type ExchangeOidcCodeSuccess, exchangeOidcCode, type FetchOidcDiscoveryOptions, type FetchOidcDiscoveryResult, fetchOidcDiscovery, type JWTPayload, type JWTVerifyGetKey, type KeyLike, type OidcDiscoveryDocument, type OidcDiscoveryFailureReason, type ValidatedIdTokenClaims, type ValidateIdTokenFailureReason, type ValidateIdTokenResult, type ValidateOidcIdTokenOptions, validateOidcIdToken, } from './oidc.js';
+export { extractGroupsFromClaim, type MapSsoGroupsFailureReason, type MapSsoGroupsInput, type MapSsoGroupsResult, mapSsoGroupsToRole, } from './roles.js';
+export { type BuildSamlAuthorizeUrlFailureReason, type BuildSamlAuthorizeUrlResult, buildSamlAuthorizeUrl, buildSamlSpMetadata, fetchIdpMetadata, normalizeIdpCertPem, type ParseIdpMetadataFailureReason, type ParseIdpMetadataResult, parseIdpMetadataXml, type SamlSpConfig, type ValidatedSamlAssertion, type ValidateSamlResponseFailureReason, type ValidateSamlResponseResult, validateSamlPostResponse, } from './saml.js';
+export { type GenerateSsoStateInput, type GenerateSsoStateResult, generateSsoState, type SsoStatePayload, type VerifiedSsoState, verifySsoState, } from './state.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/server/sso/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/sso/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,oBAAoB,EACpB,KAAK,kBAAkB,EACvB,aAAa,GACd,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,KAAK,8BAA8B,EACnC,yBAAyB,EACzB,sBAAsB,EACtB,KAAK,6BAA6B,EAClC,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAC5B,gBAAgB,EAChB,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,kBAAkB,EAClB,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,OAAO,EACZ,KAAK,qBAAqB,EAC1B,KAAK,0BAA0B,EAC/B,KAAK,sBAAsB,EAC3B,KAAK,4BAA4B,EACjC,KAAK,qBAAqB,EAC1B,KAAK,0BAA0B,EAC/B,mBAAmB,GACpB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,sBAAsB,EACtB,KAAK,yBAAyB,EAC9B,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,kBAAkB,GACnB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,KAAK,kCAAkC,EACvC,KAAK,2BAA2B,EAChC,qBAAqB,EACrB,mBAAmB,EACnB,gBAAgB,EAChB,mBAAmB,EACnB,KAAK,6BAA6B,EAClC,KAAK,sBAAsB,EAC3B,mBAAmB,EACnB,KAAK,YAAY,EACjB,KAAK,sBAAsB,EAC3B,KAAK,iCAAiC,EACtC,KAAK,0BAA0B,EAC/B,wBAAwB,GACzB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,gBAAgB,EAChB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,cAAc,GACf,MAAM,YAAY,CAAC"}

package/dist/server/sso/index.js

@@ -0,0 +1,12 @@
+/**
+ * Enterprise SSO pure layer (GAP-464).
+ *
+ * OIDC discovery + id_token validation, code exchange, SAML SP helpers,
+ * signed SSO state, group→role mapping, JIT user upsert. HTTP routes +
+ * account entitlement gate live in apps/server.
+ */
+export { normalizeSsoUserRole, upsertSsoUser, } from './jit.js';
+export { buildOidcAuthorizationUrl, createOidcRemoteJwkSet, exchangeOidcCode, fetchOidcDiscovery, validateOidcIdToken, } from './oidc.js';
+export { extractGroupsFromClaim, mapSsoGroupsToRole, } from './roles.js';
+export { buildSamlAuthorizeUrl, buildSamlSpMetadata, fetchIdpMetadata, normalizeIdpCertPem, parseIdpMetadataXml, validateSamlPostResponse, } from './saml.js';
+export { generateSsoState, verifySsoState, } from './state.js';

package/dist/server/sso/jit.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Enterprise SSO JIT user upsert (GAP-464).
+ *
+ * Flow:
+ * 1. Lookup sso_identities by (providerId, subject) → existing user
+ * 2. Else if verified email: find users by email → link identity
+ *    (enterprise SSO intentionally links by verified email from id_token;
+ *    email is used only when emailVerified === true)
+ * 3. Else create user with password null and a sanitized role
+ * 4. Insert sso_identities; ensure account_memberships row as 'member'
+ *
+ * Never defaults new users to admin. Membership role is always 'member'
+ * (account ACL); mapped SSO role is stored on users.role after allowlist.
+ */
+import type { User } from '../../types.js';
+export interface UpsertSsoUserInput {
+    providerId: string;
+    /** Provider's account_id — membership is attached here */
+    accountId: string;
+    /** IdP subject (`sub`) */
+    subject: string;
+    email?: string;
+    /** Only link/create with email when IdP asserts email_verified */
+    emailVerified?: boolean;
+    name?: string;
+    /** Role from mapSsoGroupsToRole (already forbid unmapped admin) */
+    role: string;
+}
+/**
+ * Map SSO/group roles onto the users table allowlist.
+ * `member` (membership vocabulary) → `viewer` on the user row.
+ * Unknown roles fail closed to `viewer` (never admin).
+ */
+export declare function normalizeSsoUserRole(role: string): string;
+/**
+ * Upsert a user from a validated SSO identity and ensure account membership.
+ */
+export declare function upsertSsoUser(input: UpsertSsoUserInput): Promise<User>;
+//# sourceMappingURL=jit.d.ts.map

package/dist/server/sso/jit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jit.d.ts","sourceRoot":"","sources":["../../../src/server/sso/jit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAK3C,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB,0BAA0B;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIzD;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAsG5E"}

package/dist/server/sso/jit.js

@@ -0,0 +1,141 @@
+/**
+ * Enterprise SSO JIT user upsert (GAP-464).
+ *
+ * Flow:
+ * 1. Lookup sso_identities by (providerId, subject) → existing user
+ * 2. Else if verified email: find users by email → link identity
+ *    (enterprise SSO intentionally links by verified email from id_token;
+ *    email is used only when emailVerified === true)
+ * 3. Else create user with password null and a sanitized role
+ * 4. Insert sso_identities; ensure account_memberships row as 'member'
+ *
+ * Never defaults new users to admin. Membership role is always 'member'
+ * (account ACL); mapped SSO role is stored on users.role after allowlist.
+ */
+import { logger } from '@revealui/core/observability/logger';
+import { getClient } from '@revealui/db/client';
+import { accountMemberships, ssoIdentities, users } from '@revealui/db/schema';
+import { and, eq, isNull } from 'drizzle-orm';
+/** Roles allowed on users.role for SSO-provisioned humans. */
+const ALLOWED_USER_ROLES = new Set(['viewer', 'editor', 'contributor', 'admin', 'owner']);
+/**
+ * Map SSO/group roles onto the users table allowlist.
+ * `member` (membership vocabulary) → `viewer` on the user row.
+ * Unknown roles fail closed to `viewer` (never admin).
+ */
+export function normalizeSsoUserRole(role) {
+    if (role === 'member')
+        return 'viewer';
+    if (ALLOWED_USER_ROLES.has(role))
+        return role;
+    return 'viewer';
+}
+/**
+ * Upsert a user from a validated SSO identity and ensure account membership.
+ */
+export async function upsertSsoUser(input) {
+    const { providerId, accountId, subject, email, emailVerified, name, role } = input;
+    if (!(providerId && accountId && subject)) {
+        throw new Error('providerId, accountId, and subject are required for SSO JIT');
+    }
+    const db = getClient();
+    const userRole = normalizeSsoUserRole(role);
+    const displayName = typeof name === 'string' && name.trim().length > 0 ? name.trim() : (email ?? 'SSO User');
+    // 1. Existing federated identity
+    const [existingIdentity] = await db
+        .select()
+        .from(ssoIdentities)
+        .where(and(eq(ssoIdentities.providerId, providerId), eq(ssoIdentities.subject, subject)))
+        .limit(1);
+    if (existingIdentity) {
+        const [user] = await db
+            .select()
+            .from(users)
+            .where(and(eq(users.id, existingIdentity.userId), isNull(users.deletedAt)))
+            .limit(1);
+        if (!user) {
+            logger.error('sso_identities row references missing user', {
+                identityId: existingIdentity.id,
+                userId: existingIdentity.userId,
+            });
+            throw new Error('SSO identity references a deleted user');
+        }
+        // Refresh email on identity if we have a verified one
+        if (email && emailVerified === true && existingIdentity.email !== email) {
+            await db
+                .update(ssoIdentities)
+                .set({ email, updatedAt: new Date() })
+                .where(eq(ssoIdentities.id, existingIdentity.id));
+        }
+        await ensureAccountMembership(db, accountId, user.id);
+        return user;
+    }
+    // 2. Link by verified email (enterprise SSO intentional JIT)
+    let userId;
+    let isNewUser = false;
+    if (email && emailVerified === true) {
+        const [existingUser] = await db
+            .select()
+            .from(users)
+            .where(and(eq(users.email, email), isNull(users.deletedAt)))
+            .limit(1);
+        if (existingUser) {
+            userId = existingUser.id;
+            logger.info('Linking SSO identity to existing user by verified email', {
+                userId,
+                providerId,
+            });
+        }
+        else {
+            isNewUser = true;
+            userId = crypto.randomUUID();
+        }
+    }
+    else {
+        isNewUser = true;
+        userId = crypto.randomUUID();
+    }
+    // 3. Create user (password null — federated only)
+    if (isNewUser) {
+        await db.insert(users).values({
+            id: userId,
+            name: displayName,
+            email: email && emailVerified === true ? email : (email ?? null),
+            password: null,
+            role: userRole,
+            status: 'active',
+            emailVerified: emailVerified === true,
+            emailVerifiedAt: emailVerified === true ? new Date() : null,
+        });
+    }
+    // 4. Insert identity link
+    await db.insert(ssoIdentities).values({
+        id: crypto.randomUUID(),
+        userId,
+        providerId,
+        subject,
+        email: email ?? null,
+    });
+    await ensureAccountMembership(db, accountId, userId);
+    const [user] = await db.select().from(users).where(eq(users.id, userId)).limit(1);
+    if (!user) {
+        throw new Error('Failed to fetch upserted SSO user');
+    }
+    return user;
+}
+async function ensureAccountMembership(db, accountId, userId) {
+    const [existing] = await db
+        .select({ id: accountMemberships.id })
+        .from(accountMemberships)
+        .where(and(eq(accountMemberships.accountId, accountId), eq(accountMemberships.userId, userId)))
+        .limit(1);
+    if (existing)
+        return;
+    await db.insert(accountMemberships).values({
+        id: crypto.randomUUID(),
+        accountId,
+        userId,
+        role: 'member',
+        status: 'active',
+    });
+}

package/dist/server/sso/oidc.d.ts

@@ -0,0 +1,137 @@
+/**
+ * OIDC discovery + id_token validation (GAP-464 Phase 2).
+ *
+ * Security hardlines:
+ * - Never accept id_token without cryptographic signature validation (JWKS / key).
+ * - Validate issuer, audience (client_id), and exp on every token.
+ */
+import { type JWTPayload, type JWTVerifyGetKey, type KeyLike } from 'jose';
+export interface OidcDiscoveryDocument {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    jwks_uri: string;
+    userinfo_endpoint?: string;
+    end_session_endpoint?: string;
+    scopes_supported?: string[];
+    response_types_supported?: string[];
+    code_challenge_methods_supported?: string[];
+}
+export type OidcDiscoveryFailureReason = 'fetch_failed' | 'invalid_json' | 'missing_required_fields' | 'issuer_mismatch';
+export type FetchOidcDiscoveryResult = {
+    ok: true;
+    document: OidcDiscoveryDocument;
+} | {
+    ok: false;
+    reason: OidcDiscoveryFailureReason;
+    message: string;
+};
+export interface FetchOidcDiscoveryOptions {
+    /**
+     * Optional expected issuer. When set, the document's `issuer` must match
+     * (after trailing-slash normalization).
+     */
+    expectedIssuer?: string;
+    /** Injectable fetch for tests (defaults to global fetch) */
+    fetchImpl?: typeof fetch;
+    /** Request timeout ms (default 10_000) */
+    timeoutMs?: number;
+}
+/**
+ * Fetch and parse an OIDC discovery document (openid-configuration).
+ */
+export declare function fetchOidcDiscovery(discoveryUrl: string, options?: FetchOidcDiscoveryOptions): Promise<FetchOidcDiscoveryResult>;
+export interface BuildOidcAuthorizationUrlInput {
+    authorizationEndpoint: string;
+    clientId: string;
+    redirectUri: string;
+    state: string;
+    codeChallenge: string;
+    /** Default: openid email profile */
+    scope?: string;
+    /** Optional OIDC nonce (distinct from SSO state nonce) */
+    nonce?: string;
+}
+/**
+ * Build the OIDC authorization redirect URL (code + PKCE S256).
+ */
+export declare function buildOidcAuthorizationUrl(input: BuildOidcAuthorizationUrlInput): string;
+export type ValidateIdTokenFailureReason = 'missing_token' | 'missing_key' | 'invalid_signature' | 'invalid_issuer' | 'invalid_audience' | 'expired' | 'not_yet_valid' | 'missing_sub' | 'malformed';
+export interface ValidatedIdTokenClaims {
+    sub: string;
+    email?: string;
+    emailVerified?: boolean;
+    name?: string;
+    preferredUsername?: string;
+    /** Full verified JWT payload (includes groups, custom claims, etc.) */
+    payload: JWTPayload;
+}
+export type ValidateIdTokenResult = {
+    ok: true;
+    claims: ValidatedIdTokenClaims;
+} | {
+    ok: false;
+    reason: ValidateIdTokenFailureReason;
+    message: string;
+};
+export interface ValidateOidcIdTokenOptions {
+    idToken: string;
+    /** Expected `iss` (must match provider.issuer) */
+    issuer: string;
+    /** Expected `aud` (OIDC client_id) */
+    clientId: string;
+    /**
+     * Key material for signature verification.
+     * Pass a remote JWKS getter (`createRemoteJWKSet(new URL(jwks_uri))`),
+     * a local JWK set, or a single KeyLike from tests.
+     * REQUIRED — unsigned tokens are never accepted.
+     */
+    jwks: JWTVerifyGetKey | KeyLike | Uint8Array;
+    /** Clock skew tolerance in seconds (default 30) */
+    clockToleranceSeconds?: number;
+}
+/**
+ * Validate an OIDC id_token: signature (JWKS), issuer, audience, exp.
+ *
+ * Hardline: `jwks` is required. Callers must not pass a no-op key or skip verify.
+ */
+export declare function validateOidcIdToken(options: ValidateOidcIdTokenOptions): Promise<ValidateIdTokenResult>;
+/**
+ * Create a remote JWKS key resolver from a discovery `jwks_uri`.
+ * Thin wrapper so route code does not import jose directly.
+ */
+export declare function createOidcRemoteJwkSet(jwksUri: string): JWTVerifyGetKey;
+export type ExchangeOidcCodeFailureReason = 'missing_params' | 'fetch_failed' | 'invalid_json' | 'missing_id_token';
+export interface ExchangeOidcCodeInput {
+    tokenEndpoint: string;
+    clientId: string;
+    clientSecret: string;
+    code: string;
+    redirectUri: string;
+    codeVerifier: string;
+    /** Injectable fetch for tests (defaults to global fetch) */
+    fetchImpl?: typeof fetch;
+    /** Request timeout ms (default 10_000) */
+    timeoutMs?: number;
+}
+export interface ExchangeOidcCodeSuccess {
+    id_token: string;
+    access_token?: string;
+}
+export type ExchangeOidcCodeResult = {
+    ok: true;
+    tokens: ExchangeOidcCodeSuccess;
+} | {
+    ok: false;
+    reason: ExchangeOidcCodeFailureReason;
+    message: string;
+};
+/**
+ * Exchange an OIDC authorization code for tokens (PKCE + client_secret).
+ *
+ * POSTs `application/x-www-form-urlencoded`. Rejects responses without `id_token`.
+ * Never logs client_secret or tokens.
+ */
+export declare function exchangeOidcCode(input: ExchangeOidcCodeInput): Promise<ExchangeOidcCodeResult>;
+export type { JWTPayload, JWTVerifyGetKey, KeyLike };
+//# sourceMappingURL=oidc.d.ts.map

package/dist/server/sso/oidc.d.ts.map

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