@revealui/auth 0.4.10 → 0.5.1

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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"}

package/dist/server/sso/oidc.js

@@ -0,0 +1,345 @@
+/**
+ * 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 { createRemoteJWKSet, jwtVerify, } from 'jose';
+/** Asymmetric algorithms used by enterprise IdPs; `none` is never allowed. */
+const ID_TOKEN_ALGORITHMS = [
+    'RS256',
+    'RS384',
+    'RS512',
+    'ES256',
+    'ES384',
+    'ES512',
+    'PS256',
+    'PS384',
+    'PS512',
+    'EdDSA',
+];
+const DISCOVERY_REQUIRED = [
+    'issuer',
+    'authorization_endpoint',
+    'token_endpoint',
+    'jwks_uri',
+];
+/** Strip trailing `/` without regex (CodeQL: avoid poly ReDoS on uncontrolled issuer). */
+function normalizeIssuer(issuer) {
+    let end = issuer.length;
+    while (end > 0 && issuer.charCodeAt(end - 1) === 47 /* '/' */) {
+        end -= 1;
+    }
+    return end === issuer.length ? issuer : issuer.slice(0, end);
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+/**
+ * Fetch and parse an OIDC discovery document (openid-configuration).
+ */
+export async function fetchOidcDiscovery(discoveryUrl, options = {}) {
+    if (!isNonEmptyString(discoveryUrl)) {
+        return {
+            ok: false,
+            reason: 'missing_required_fields',
+            message: 'discoveryUrl is required',
+        };
+    }
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let response;
+    try {
+        response = await fetchImpl(discoveryUrl, {
+            method: 'GET',
+            headers: { Accept: 'application/json' },
+            signal: controller.signal,
+            redirect: 'follow',
+        });
+    }
+    catch (err) {
+        clearTimeout(timer);
+        const message = err instanceof Error ? err.message : 'discovery fetch failed';
+        return { ok: false, reason: 'fetch_failed', message };
+    }
+    clearTimeout(timer);
+    if (!response.ok) {
+        return {
+            ok: false,
+            reason: 'fetch_failed',
+            message: `discovery HTTP ${response.status}`,
+        };
+    }
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch {
+        return { ok: false, reason: 'invalid_json', message: 'discovery response is not JSON' };
+    }
+    if (!body || typeof body !== 'object') {
+        return { ok: false, reason: 'invalid_json', message: 'discovery response is not an object' };
+    }
+    const record = body;
+    for (const key of DISCOVERY_REQUIRED) {
+        if (!isNonEmptyString(record[key])) {
+            return {
+                ok: false,
+                reason: 'missing_required_fields',
+                message: `discovery document missing ${key}`,
+            };
+        }
+    }
+    const document = {
+        issuer: record.issuer,
+        authorization_endpoint: record.authorization_endpoint,
+        token_endpoint: record.token_endpoint,
+        jwks_uri: record.jwks_uri,
+    };
+    if (isNonEmptyString(record.userinfo_endpoint)) {
+        document.userinfo_endpoint = record.userinfo_endpoint;
+    }
+    if (isNonEmptyString(record.end_session_endpoint)) {
+        document.end_session_endpoint = record.end_session_endpoint;
+    }
+    if (Array.isArray(record.scopes_supported)) {
+        document.scopes_supported = record.scopes_supported.filter((s) => typeof s === 'string');
+    }
+    if (Array.isArray(record.response_types_supported)) {
+        document.response_types_supported = record.response_types_supported.filter((s) => typeof s === 'string');
+    }
+    if (Array.isArray(record.code_challenge_methods_supported)) {
+        document.code_challenge_methods_supported = record.code_challenge_methods_supported.filter((s) => typeof s === 'string');
+    }
+    if (options.expectedIssuer) {
+        if (normalizeIssuer(document.issuer) !== normalizeIssuer(options.expectedIssuer)) {
+            return {
+                ok: false,
+                reason: 'issuer_mismatch',
+                message: `discovery issuer "${document.issuer}" does not match expected "${options.expectedIssuer}"`,
+            };
+        }
+    }
+    return { ok: true, document };
+}
+/**
+ * Build the OIDC authorization redirect URL (code + PKCE S256).
+ */
+export function buildOidcAuthorizationUrl(input) {
+    const url = new URL(input.authorizationEndpoint);
+    url.searchParams.set('response_type', 'code');
+    url.searchParams.set('client_id', input.clientId);
+    url.searchParams.set('redirect_uri', input.redirectUri);
+    url.searchParams.set('scope', input.scope ?? 'openid email profile');
+    url.searchParams.set('state', input.state);
+    url.searchParams.set('code_challenge', input.codeChallenge);
+    url.searchParams.set('code_challenge_method', 'S256');
+    if (input.nonce) {
+        url.searchParams.set('nonce', input.nonce);
+    }
+    return url.toString();
+}
+function mapJoseError(err) {
+    const message = err instanceof Error ? err.message : 'id_token validation failed';
+    const code = err &&
+        typeof err === 'object' &&
+        'code' in err &&
+        typeof err.code === 'string'
+        ? err.code
+        : '';
+    const claim = err &&
+        typeof err === 'object' &&
+        'claim' in err &&
+        typeof err.claim === 'string'
+        ? err.claim
+        : '';
+    // Prefer jose error codes / claim names over message regex (avoids "exp" matching "expected")
+    if (code === 'ERR_JWT_EXPIRED' || claim === 'exp') {
+        return { reason: 'expired', message };
+    }
+    if (code === 'ERR_JWT_CLAIM_VALIDATION_FAILED' || claim) {
+        if (claim === 'iss' || /"iss"/i.test(message)) {
+            return { reason: 'invalid_issuer', message };
+        }
+        if (claim === 'aud' || /"aud"/i.test(message)) {
+            return { reason: 'invalid_audience', message };
+        }
+        if (claim === 'nbf' || /"nbf"/i.test(message)) {
+            return { reason: 'not_yet_valid', message };
+        }
+    }
+    if (code === 'ERR_JWS_SIGNATURE_VERIFICATION_FAILED' ||
+        code === 'ERR_JWS_INVALID' ||
+        /signature verification failed|jws signature/i.test(message)) {
+        return { reason: 'invalid_signature', message };
+    }
+    if (code === 'ERR_JWT_INVALID' || /compact jws|invalid token/i.test(message)) {
+        return { reason: 'malformed', message };
+    }
+    return { reason: 'invalid_signature', message };
+}
+/**
+ * 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 async function validateOidcIdToken(options) {
+    const { idToken, issuer, clientId, jwks, clockToleranceSeconds = 30 } = options;
+    if (!isNonEmptyString(idToken)) {
+        return { ok: false, reason: 'missing_token', message: 'id_token is required' };
+    }
+    if (jwks == null) {
+        return {
+            ok: false,
+            reason: 'missing_key',
+            message: 'JWKS / verification key is required; unsigned id_tokens are rejected',
+        };
+    }
+    if (!isNonEmptyString(issuer)) {
+        return { ok: false, reason: 'invalid_issuer', message: 'expected issuer is required' };
+    }
+    if (!isNonEmptyString(clientId)) {
+        return { ok: false, reason: 'invalid_audience', message: 'clientId (audience) is required' };
+    }
+    // Prefer asymmetric algorithms used by enterprise IdPs; reject `none`
+    const verifyOptions = {
+        issuer: normalizeIssuer(issuer),
+        audience: clientId,
+        clockTolerance: clockToleranceSeconds,
+        algorithms: ID_TOKEN_ALGORITHMS,
+    };
+    let payload;
+    try {
+        // jose types KeyLike and JWTVerifyGetKey as separate overloads — narrow first
+        let verified;
+        if (typeof jwks === 'function') {
+            verified = await jwtVerify(idToken, jwks, verifyOptions);
+        }
+        else {
+            verified = await jwtVerify(idToken, jwks, verifyOptions);
+        }
+        payload = verified.payload;
+    }
+    catch (err) {
+        return { ok: false, ...mapJoseError(err) };
+    }
+    if (!isNonEmptyString(payload.sub)) {
+        return { ok: false, reason: 'missing_sub', message: 'id_token missing sub claim' };
+    }
+    const claims = {
+        sub: payload.sub,
+        payload,
+    };
+    if (typeof payload.email === 'string' && payload.email.length > 0) {
+        claims.email = payload.email;
+    }
+    if (typeof payload.email_verified === 'boolean') {
+        claims.emailVerified = payload.email_verified;
+    }
+    else if (payload.email_verified === 'true') {
+        claims.emailVerified = true;
+    }
+    else if (payload.email_verified === 'false') {
+        claims.emailVerified = false;
+    }
+    if (typeof payload.name === 'string' && payload.name.length > 0) {
+        claims.name = payload.name;
+    }
+    if (typeof payload.preferred_username === 'string' && payload.preferred_username.length > 0) {
+        claims.preferredUsername = payload.preferred_username;
+    }
+    return { ok: true, claims };
+}
+/**
+ * Create a remote JWKS key resolver from a discovery `jwks_uri`.
+ * Thin wrapper so route code does not import jose directly.
+ */
+export function createOidcRemoteJwkSet(jwksUri) {
+    if (!isNonEmptyString(jwksUri)) {
+        throw new Error('jwksUri is required');
+    }
+    return createRemoteJWKSet(new URL(jwksUri));
+}
+/**
+ * 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 async function exchangeOidcCode(input) {
+    const { tokenEndpoint, clientId, clientSecret, code, redirectUri, codeVerifier, fetchImpl = fetch, timeoutMs = 10_000, } = input;
+    if (!(isNonEmptyString(tokenEndpoint) &&
+        isNonEmptyString(clientId) &&
+        isNonEmptyString(clientSecret) &&
+        isNonEmptyString(code) &&
+        isNonEmptyString(redirectUri) &&
+        isNonEmptyString(codeVerifier))) {
+        return {
+            ok: false,
+            reason: 'missing_params',
+            message: 'tokenEndpoint, clientId, clientSecret, code, redirectUri, and codeVerifier are required',
+        };
+    }
+    const body = new URLSearchParams({
+        grant_type: 'authorization_code',
+        code,
+        redirect_uri: redirectUri,
+        client_id: clientId,
+        client_secret: clientSecret,
+        code_verifier: codeVerifier,
+    });
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let response;
+    try {
+        response = await fetchImpl(tokenEndpoint, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded',
+                Accept: 'application/json',
+            },
+            body,
+            signal: controller.signal,
+            redirect: 'error',
+        });
+    }
+    catch (err) {
+        clearTimeout(timer);
+        const message = err instanceof Error ? err.message : 'token exchange fetch failed';
+        return { ok: false, reason: 'fetch_failed', message };
+    }
+    clearTimeout(timer);
+    if (!response.ok) {
+        return {
+            ok: false,
+            reason: 'fetch_failed',
+            message: `token endpoint HTTP ${response.status}`,
+        };
+    }
+    let parsed;
+    try {
+        parsed = await response.json();
+    }
+    catch {
+        return { ok: false, reason: 'invalid_json', message: 'token response is not JSON' };
+    }
+    if (!parsed || typeof parsed !== 'object') {
+        return { ok: false, reason: 'invalid_json', message: 'token response is not an object' };
+    }
+    const record = parsed;
+    if (!isNonEmptyString(record.id_token)) {
+        return {
+            ok: false,
+            reason: 'missing_id_token',
+            message: 'token response missing id_token',
+        };
+    }
+    const tokens = { id_token: record.id_token };
+    if (isNonEmptyString(record.access_token)) {
+        tokens.access_token = record.access_token;
+    }
+    return { ok: true, tokens };
+}

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

@@ -0,0 +1,48 @@
+/**
+ * SSO group → role mapping (GAP-464).
+ *
+ * Security hardlines:
+ * - Map only via explicit group_role_map hits.
+ * - Empty mapped set + require_group_match → reject.
+ * - Never grant `admin` from an unmapped group (unmapped groups are ignored).
+ * - When no map hits and require_group_match is false → default_role.
+ */
+export interface MapSsoGroupsInput {
+    /** Raw IdP claims (id_token payload or SAML attribute bag) */
+    claims: Record<string, unknown>;
+    /** Claim key that holds group membership (default on providers: `groups`) */
+    groupClaim: string;
+    /** IdP group name → RevealUI role */
+    groupRoleMap: Record<string, string>;
+    /** Used when no groups map and requireGroupMatch is false */
+    defaultRole: string;
+    /** When true, login fails unless at least one group maps to a role */
+    requireGroupMatch: boolean;
+}
+export type MapSsoGroupsFailureReason = 'require_group_match' | 'invalid_default_role';
+export type MapSsoGroupsResult = {
+    ok: true;
+    role: string;
+    /** Groups present on the token that hit group_role_map */
+    matchedGroups: string[];
+    /** All groups extracted from the claim (mapped + unmapped) */
+    groups: string[];
+} | {
+    ok: false;
+    reason: MapSsoGroupsFailureReason;
+    message: string;
+    groups: string[];
+};
+/**
+ * Extract a string array of groups from a claim value.
+ * Accepts string[], a single string, or a space/comma-separated string.
+ */
+export declare function extractGroupsFromClaim(claims: Record<string, unknown>, groupClaim: string): string[];
+/**
+ * Resolve a single RevealUI role from IdP groups + provider mapping config.
+ *
+ * Unmapped groups never contribute a role (including never implying admin).
+ * Only explicit map values and the configured default_role assign roles.
+ */
+export declare function mapSsoGroupsToRole(input: MapSsoGroupsInput): MapSsoGroupsResult;
+//# sourceMappingURL=roles.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"roles.d.ts","sourceRoot":"","sources":["../../../src/server/sso/roles.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,iBAAiB;IAChC,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,6EAA6E;IAC7E,UAAU,EAAE,MAAM,CAAC;IACnB,qCAAqC;IACrC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,iBAAiB,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,MAAM,yBAAyB,GAAG,qBAAqB,GAAG,sBAAsB,CAAC;AAEvF,MAAM,MAAM,kBAAkB,GAC1B;IACE,EAAE,EAAE,IAAI,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,8DAA8D;IAC9D,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,GACD;IACE,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,yBAAyB,CAAC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAAC;AAWN;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,UAAU,EAAE,MAAM,GACjB,MAAM,EAAE,CAyBV;AAgBD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,iBAAiB,GAAG,kBAAkB,CAiD/E"}