@svadmin/sso 0.9.0 → 0.11.0

package/dist/auth-provider.js

@@ -0,0 +1,555 @@
+/**
+ * @svadmin/sso — OIDC/OAuth2 SSO AuthProvider for svadmin.
+ *
+ * Uses the Authorization Code Flow with PKCE and supports rotation-safe
+ * refresh-token handling for browser applications.
+ */
+import { createAuthenticatedFetch as buildAuthenticatedFetch } from './authenticated-fetch.js';
+import { createSSOAuthNetworkError, createSSOAuthResponseError, isTerminalSessionError, SSOAuthError, } from './errors.js';
+import { createSessionManager, } from './session-manager.js';
+const DEFAULT_STORAGE_KEY = 'svadmin_sso';
+function decodeJwtPayload(token) {
+    if (!token)
+        return null;
+    const parts = token.split('.');
+    if (parts.length < 2)
+        return null;
+    const payloadStr = parts[1];
+    const padded = payloadStr + '='.repeat((4 - (payloadStr.length % 4)) % 4);
+    const binString = atob(padded.replace(/-/g, '+').replace(/_/g, '/'));
+    const bytes = Uint8Array.from(binString, (value) => value.codePointAt(0) ?? 0);
+    return JSON.parse(new TextDecoder().decode(bytes));
+}
+function getAccessTokenExpiry(data, accessToken) {
+    if (typeof data.expires_in === 'number' && Number.isFinite(data.expires_in)) {
+        return Math.floor(Date.now() / 1000) + data.expires_in;
+    }
+    try {
+        const payload = decodeJwtPayload(accessToken);
+        return typeof payload?.exp === 'number' ? payload.exp : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function createInvalidTokenResponseError(fallbackMessage, field, body) {
+    return new SSOAuthError(`${fallbackMessage}: invalid ${field}`, 502, {
+        code: 'invalid_token_response',
+        body,
+        retryable: true,
+    });
+}
+function readTokenResponse(body, fallbackMessage) {
+    if (typeof body === 'object' && body !== null && !Array.isArray(body)) {
+        return body;
+    }
+    throw createInvalidTokenResponseError(fallbackMessage, 'response body', body);
+}
+function requireTokenString(response, field, fallbackMessage) {
+    const token = response[field];
+    if (typeof token === 'string' && token.length > 0)
+        return token;
+    throw createInvalidTokenResponseError(fallbackMessage, field, response);
+}
+function readOptionalTokenString(response, field, fallback, fallbackMessage) {
+    return response[field] === undefined
+        ? fallback
+        : requireTokenString(response, field, fallbackMessage);
+}
+function normalizeTokenResponse(body, defaults, fallbackMessage) {
+    const response = readTokenResponse(body, fallbackMessage);
+    const accessToken = requireTokenString(response, 'access_token', fallbackMessage);
+    return {
+        access_token: accessToken,
+        id_token: typeof response.id_token === 'string' ? response.id_token : defaults.idToken,
+        refresh_token: readOptionalTokenString(response, 'refresh_token', defaults.refreshToken, fallbackMessage),
+        expires_at: getAccessTokenExpiry(response, accessToken),
+        token_type: readOptionalTokenString(response, 'token_type', defaults.tokenType, fallbackMessage) ?? defaults.tokenType,
+    };
+}
+function generateRandomString(length) {
+    const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~';
+    const values = crypto.getRandomValues(new Uint8Array(length));
+    return Array.from(values, (value) => chars[value % chars.length]).join('');
+}
+async function createPKCEChallenge() {
+    const verifier = generateRandomString(64);
+    const hashed = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier));
+    const bytes = new Uint8Array(hashed);
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    const challenge = btoa(binary)
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_')
+        .replace(/=+$/, '');
+    return { verifier, challenge };
+}
+function createMemoryStorage() {
+    const values = new Map();
+    return {
+        getItem: (key) => values.get(key) ?? null,
+        setItem: (key, value) => { values.set(key, value); },
+        removeItem: (key) => { values.delete(key); },
+    };
+}
+function storageProbe(storage) {
+    const probeKey = `svadmin_sso_probe_${Math.random().toString(36).slice(2)}`;
+    try {
+        storage.setItem(probeKey, '1');
+        storage.removeItem(probeKey);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function unavailableStorage() {
+    return {
+        getItem: () => null,
+        setItem: () => {
+            throw new SSOAuthError('Browser storage is unavailable', 0, {
+                code: 'storage_unavailable',
+                retryable: false,
+            });
+        },
+        removeItem: () => undefined,
+    };
+}
+function safeBrowserStorage(readStorage) {
+    try {
+        const storage = readStorage();
+        return storageProbe(storage) ? storage : null;
+    }
+    catch {
+        return null;
+    }
+}
+function getStorage(config) {
+    if (config.storage && typeof config.storage === 'object')
+        return config.storage;
+    if (typeof window === 'undefined')
+        return createMemoryStorage();
+    const requestedStorage = config.storage === 'session'
+        ? safeBrowserStorage(() => window.sessionStorage)
+        : safeBrowserStorage(() => window.localStorage)
+            ?? safeBrowserStorage(() => window.sessionStorage);
+    if (!requestedStorage)
+        return unavailableStorage();
+    return {
+        getItem: (key) => requestedStorage.getItem(key),
+        setItem: (key, value) => { requestedStorage.setItem(key, value); },
+        removeItem: (key) => { requestedStorage.removeItem(key); },
+    };
+}
+function getErrorResult(error) {
+    if (error instanceof SSOAuthError) {
+        return { message: error.message, name: error.code ?? error.name };
+    }
+    if (error instanceof Error)
+        return { message: error.message, name: error.name };
+    return { message: String(error) };
+}
+function getErrorStatus(error) {
+    if (typeof error !== 'object' || error === null)
+        return undefined;
+    if ('statusCode' in error && typeof error.statusCode === 'number')
+        return error.statusCode;
+    if ('status' in error && typeof error.status === 'number')
+        return error.status;
+    return undefined;
+}
+/** Create an OIDC/OAuth2 SSO AuthProvider. */
+export function createSSOAuthProvider(config) {
+    const scopes = config.scopes ?? ['openid', 'profile', 'email'];
+    const refreshBuffer = Math.max(0, config.refreshBuffer ?? 60);
+    const storage = getStorage(config);
+    const storageKey = config.storageKey
+        ?? `${DEFAULT_STORAGE_KEY}:${encodeURIComponent(config.issuer)}:${encodeURIComponent(config.clientId)}`;
+    let oidcConfig = null;
+    function getFetcher() {
+        const fetcher = config.fetcher ?? globalThis.fetch;
+        if (typeof fetcher !== 'function') {
+            throw new SSOAuthError('No fetch implementation found', 0, {
+                code: 'fetch_unavailable',
+                retryable: false,
+            });
+        }
+        return fetcher.bind(globalThis);
+    }
+    async function discover() {
+        if (oidcConfig)
+            return oidcConfig;
+        if (config.manualEndpoints) {
+            oidcConfig = config.manualEndpoints;
+            return oidcConfig;
+        }
+        const url = `${config.issuer.replace(/\/$/, '')}/.well-known/openid-configuration`;
+        let response;
+        try {
+            response = await getFetcher()(url);
+        }
+        catch (error) {
+            throw createSSOAuthNetworkError(error, 'OIDC discovery failed');
+        }
+        if (!response.ok)
+            throw await createSSOAuthResponseError(response, 'OIDC discovery failed');
+        let discovered;
+        try {
+            discovered = await response.json();
+        }
+        catch (error) {
+            throw new SSOAuthError('OIDC discovery returned invalid JSON', 502, {
+                code: 'invalid_discovery_document',
+                retryable: true,
+                cause: error,
+            });
+        }
+        if (typeof discovered.authorization_endpoint !== 'string'
+            || typeof discovered.token_endpoint !== 'string'
+            || typeof discovered.userinfo_endpoint !== 'string') {
+            throw new SSOAuthError('OIDC discovery returned incomplete endpoints', 502, {
+                code: 'invalid_discovery_document',
+                body: discovered,
+            });
+        }
+        oidcConfig = discovered;
+        return oidcConfig;
+    }
+    async function requestToken(endpoint, body, fallbackMessage) {
+        let response;
+        try {
+            response = await getFetcher()(endpoint, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+                body,
+            });
+        }
+        catch (error) {
+            throw createSSOAuthNetworkError(error, fallbackMessage);
+        }
+        if (!response.ok)
+            throw await createSSOAuthResponseError(response, fallbackMessage);
+        try {
+            return await response.json();
+        }
+        catch (error) {
+            throw new SSOAuthError(`${fallbackMessage}: invalid JSON response`, 502, {
+                code: 'invalid_token_response',
+                retryable: true,
+                cause: error,
+            });
+        }
+    }
+    async function performRefresh(current) {
+        if (!current.refresh_token) {
+            throw new SSOAuthError('Refresh token is unavailable', 401, {
+                code: 'session_not_found',
+            });
+        }
+        const endpoints = await discover();
+        const response = await requestToken(endpoints.token_endpoint, new URLSearchParams({
+            grant_type: 'refresh_token',
+            client_id: config.clientId,
+            refresh_token: current.refresh_token,
+        }), 'Token refresh failed');
+        return normalizeTokenResponse(response, {
+            idToken: current.id_token,
+            refreshToken: current.refresh_token,
+            tokenType: current.token_type,
+        }, 'Token refresh failed');
+    }
+    const sessions = createSessionManager({
+        storage,
+        storageKey,
+        autoRefresh: config.autoRefresh ?? true,
+        refreshBuffer,
+        refreshLock: config.refreshLock,
+        refresh: performRefresh,
+        legacyStorageKey: config.legacyStorageKey,
+    });
+    function assertAuthorizationExchangeCurrent(authGeneration, expectedState) {
+        if (sessions.getAuthGeneration() === authGeneration
+            && sessions.getLoginState() === expectedState)
+            return;
+        throw new SSOAuthError('Authorization exchange was cancelled by a newer session action', 409, {
+            code: 'authorization_exchange_cancelled',
+            retryable: false,
+        });
+    }
+    async function clearOwnedLoginState(expectedState) {
+        try {
+            await sessions.runAuthMutation(async () => {
+                sessions.clearLoginState(expectedState);
+            });
+        }
+        catch (error) {
+            if (!(error instanceof SSOAuthError) || error.code !== 'auth_lock_failed')
+                throw error;
+            sessions.clearLoginState(expectedState);
+        }
+    }
+    async function exchangeCode(code, expectedState) {
+        const authGeneration = sessions.getAuthGeneration();
+        const verifier = sessions.getPKCEVerifier();
+        const endpoints = await discover();
+        assertAuthorizationExchangeCurrent(authGeneration, expectedState);
+        const body = new URLSearchParams({
+            grant_type: 'authorization_code',
+            client_id: config.clientId,
+            code,
+            redirect_uri: config.redirectUri,
+            ...(verifier ? { code_verifier: verifier } : {}),
+        });
+        const response = await requestToken(endpoints.token_endpoint, body, 'Token exchange failed');
+        const session = normalizeTokenResponse(response, { tokenType: 'Bearer' }, 'Token exchange failed');
+        assertAuthorizationExchangeCurrent(authGeneration, expectedState);
+        return sessions.runAuthMutation(async () => {
+            assertAuthorizationExchangeCurrent(authGeneration, expectedState);
+            sessions.saveSession(session);
+            sessions.clearLoginState(expectedState);
+            return session;
+        });
+    }
+    const mapIdentity = config.mapIdentity ?? ((userinfo) => ({
+        id: userinfo.sub ?? '',
+        name: userinfo.name ?? userinfo.preferred_username ?? '',
+        avatar: userinfo.picture ?? undefined,
+        email: userinfo.email ?? undefined,
+    }));
+    const authorizationSource = {
+        getAuthorizationHeader: async (options) => {
+            const accessToken = await sessions.getAccessToken(options);
+            const session = sessions.getSession();
+            return accessToken && session?.access_token === accessToken
+                ? `${session.token_type} ${accessToken}`
+                : null;
+        },
+    };
+    const provider = {
+        async login() {
+            if (typeof window === 'undefined') {
+                return { success: false, error: { message: 'SSO login requires a browser environment' } };
+            }
+            const state = generateRandomString(32);
+            try {
+                await sessions.runAuthMutation(async () => {
+                    sessions.beginAuthAttempt();
+                    sessions.setLoginState('', state);
+                });
+                const endpoints = await discover();
+                const { verifier, challenge } = await createPKCEChallenge();
+                await sessions.runAuthMutation(async () => {
+                    if (sessions.getLoginState() !== state) {
+                        throw new SSOAuthError('Login attempt was superseded', 409, {
+                            code: 'authorization_exchange_cancelled',
+                            retryable: false,
+                        });
+                    }
+                    sessions.setLoginState(verifier, state);
+                });
+                const params = new URLSearchParams({
+                    response_type: 'code',
+                    client_id: config.clientId,
+                    redirect_uri: config.redirectUri,
+                    scope: scopes.join(' '),
+                    state,
+                    code_challenge: challenge,
+                    code_challenge_method: 'S256',
+                    ...config.authorizationParams,
+                });
+                window.location.href = `${endpoints.authorization_endpoint}?${params}`;
+                return { success: true };
+            }
+            catch (error) {
+                try {
+                    await clearOwnedLoginState(state);
+                }
+                catch {
+                    // 保留触发失败的原始认证错误；清理失败不能掩盖根因。
+                }
+                return { success: false, error: getErrorResult(error) };
+            }
+        },
+        async logout() {
+            const session = sessions.getSession();
+            sessions.beginSignOut();
+            try {
+                await sessions.runAuthMutation(async () => {
+                    sessions.clearSession();
+                });
+            }
+            catch (error) {
+                if (!(error instanceof SSOAuthError) || error.code !== 'auth_lock_failed')
+                    throw error;
+                // 无跨上下文锁时 callback commit 同样会失败；本地登出仍应清理会话。
+                sessions.clearSession();
+            }
+            try {
+                const endpoints = await discover();
+                if (typeof window !== 'undefined' && endpoints.end_session_endpoint && session?.id_token) {
+                    const params = new URLSearchParams({
+                        id_token_hint: session.id_token,
+                        ...(config.postLogoutRedirectUri
+                            ? { post_logout_redirect_uri: config.postLogoutRedirectUri }
+                            : {}),
+                    });
+                    window.location.href = `${endpoints.end_session_endpoint}?${params}`;
+                    return { success: true };
+                }
+            }
+            catch {
+                // 本地会话已清理，发现或跳转失败不能恢复为登录态。
+            }
+            return {
+                success: true,
+                redirectTo: config.postLogoutRedirectUri ?? '/',
+            };
+        },
+        async check() {
+            const existingSession = sessions.getSession();
+            if (typeof window === 'undefined') {
+                const now = Math.floor(Date.now() / 1000);
+                return existingSession && (existingSession.expires_at === undefined || existingSession.expires_at > now)
+                    ? { authenticated: true }
+                    : { authenticated: false, logout: true };
+            }
+            const url = new URL(window.location.href);
+            const callbackError = url.searchParams.get('error');
+            if (callbackError) {
+                const callbackState = url.searchParams.get('state');
+                const savedState = sessions.getLoginState();
+                if (callbackState && savedState && callbackState === savedState) {
+                    try {
+                        await clearOwnedLoginState(savedState);
+                    }
+                    catch {
+                        // 错误回调仍返回 IdP 的原始错误；清理失败不掩盖它。
+                    }
+                }
+                return {
+                    authenticated: false,
+                    error: {
+                        message: url.searchParams.get('error_description') ?? callbackError,
+                        name: callbackError,
+                    },
+                };
+            }
+            const code = url.searchParams.get('code');
+            const state = url.searchParams.get('state');
+            if (code) {
+                const savedState = sessions.getLoginState();
+                if (!state || !savedState || state !== savedState) {
+                    return { authenticated: false, error: { message: 'State mismatch' } };
+                }
+                try {
+                    await exchangeCode(code, savedState);
+                    url.searchParams.delete('code');
+                    url.searchParams.delete('state');
+                    window.history.replaceState({}, '', `${url.pathname}${url.search}${url.hash}`);
+                    return { authenticated: true };
+                }
+                catch (error) {
+                    try {
+                        await clearOwnedLoginState(savedState);
+                    }
+                    catch {
+                        // 保留 token exchange 的原始错误。
+                    }
+                    return { authenticated: false, error: getErrorResult(error) };
+                }
+            }
+            const session = sessions.getSession();
+            if (!session)
+                return { authenticated: false, logout: true };
+            const now = Math.floor(Date.now() / 1000);
+            if (session.expires_at !== undefined && session.expires_at <= now) {
+                if (!session.refresh_token) {
+                    try {
+                        if (await sessions.getAccessToken())
+                            return { authenticated: true };
+                        return sessions.getLoginState()
+                            ? { authenticated: false }
+                            : { authenticated: false, logout: true };
+                    }
+                    catch (error) {
+                        return { authenticated: false, error: getErrorResult(error) };
+                    }
+                }
+                try {
+                    return await sessions.refreshSession()
+                        ? { authenticated: true }
+                        : { authenticated: false, logout: true };
+                }
+                catch (error) {
+                    return {
+                        authenticated: false,
+                        error: getErrorResult(error),
+                        ...(isTerminalSessionError(error) ? { logout: true } : {}),
+                    };
+                }
+            }
+            return { authenticated: true };
+        },
+        async getIdentity() {
+            if (!sessions.getSession())
+                return null;
+            const authGeneration = sessions.getAuthGeneration();
+            try {
+                const endpoints = await discover();
+                const response = await buildAuthenticatedFetch(authorizationSource, getFetcher(), { requireAuthorization: true })(endpoints.userinfo_endpoint);
+                if (!response.ok)
+                    return null;
+                const userinfo = await response.json();
+                if (sessions.getAuthGeneration() !== authGeneration
+                    || !sessions.getSession())
+                    return null;
+                return mapIdentity(userinfo);
+            }
+            catch {
+                return null;
+            }
+        },
+        async getPermissions() {
+            const idToken = sessions.getSession()?.id_token;
+            if (!idToken)
+                return null;
+            try {
+                const payload = decodeJwtPayload(idToken);
+                return payload?.roles ?? payload?.groups ?? payload?.permissions ?? null;
+            }
+            catch {
+                return null;
+            }
+        },
+        getSession: async () => sessions.getSession(),
+        refreshSession: () => sessions.refreshSession(),
+        getAccessToken: (options) => sessions.getAccessToken(options),
+        onAuthStateChange: (callback) => sessions.onAuthStateChange(callback),
+        createAuthenticatedFetch: (fetcher) => buildAuthenticatedFetch(authorizationSource, fetcher ?? getFetcher()),
+        destroy: () => sessions.destroy(),
+        async onError(error) {
+            const status = getErrorStatus(error);
+            if (status === 403)
+                return {};
+            if (isTerminalSessionError(error))
+                return { logout: true, redirectTo: '/login' };
+            if (status !== 401)
+                return {};
+            const session = sessions.getSession();
+            if (!session?.refresh_token)
+                return { logout: true, redirectTo: '/login' };
+            try {
+                return await sessions.getAccessToken({ forceRefresh: true })
+                    ? {}
+                    : { logout: true, redirectTo: '/login' };
+            }
+            catch (refreshError) {
+                return isTerminalSessionError(refreshError)
+                    ? { logout: true, redirectTo: '/login' }
+                    : {};
+            }
+        },
+    };
+    return provider;
+}

package/dist/authenticated-fetch.d.ts

@@ -0,0 +1,9 @@
+import type { GetAccessTokenOptions } from './session-manager.js';
+interface AccessTokenSource {
+    getAuthorizationHeader: (options?: GetAccessTokenOptions) => Promise<string | null>;
+}
+interface AuthenticatedFetchOptions {
+    requireAuthorization?: boolean;
+}
+export declare function createAuthenticatedFetch(source: AccessTokenSource, fetcher: typeof fetch, options?: AuthenticatedFetchOptions): typeof fetch;
+export {};

package/dist/authenticated-fetch.js

@@ -0,0 +1,71 @@
+import { SSOAuthError } from './errors.js';
+function cloneReplayableRequest(request) {
+    try {
+        return request.clone();
+    }
+    catch (error) {
+        throw new SSOAuthError('Authenticated request body cannot be safely replayed', 0, {
+            code: 'request_not_replayable',
+            retryable: false,
+            cause: error,
+        });
+    }
+}
+function withAuthorization(request, authorization) {
+    if (!authorization)
+        return request;
+    const headers = new Headers(request.headers);
+    headers.set('Authorization', authorization);
+    return new Request(request, { headers });
+}
+function markRetryExhausted(response) {
+    const headers = new Headers(response.headers);
+    headers.set('X-Svadmin-Auth-Retry', 'exhausted');
+    return new Response(response.body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers,
+    });
+}
+export function createAuthenticatedFetch(source, fetcher, options = {}) {
+    return (async (input, init) => {
+        if (input instanceof Request && input.bodyUsed) {
+            throw new SSOAuthError('Authenticated request body cannot be safely replayed', 0, {
+                code: 'request_not_replayable',
+                retryable: false,
+            });
+        }
+        let request;
+        try {
+            request = new Request(input, init);
+        }
+        catch (error) {
+            throw new SSOAuthError('Authenticated request could not be constructed', 0, {
+                code: 'request_not_replayable',
+                retryable: false,
+                cause: error,
+            });
+        }
+        // 两份副本都在首次发送前创建，避免流式 body 被消费后静默丢失。
+        const firstAttempt = cloneReplayableRequest(request);
+        const retryAttempt = cloneReplayableRequest(request);
+        const authorization = await source.getAuthorizationHeader();
+        if (options.requireAuthorization && !authorization) {
+            throw new SSOAuthError('Authenticated request requires an active session', 401, {
+                code: 'session_not_found',
+                retryable: false,
+            });
+        }
+        const response = await fetcher(withAuthorization(firstAttempt, authorization));
+        if (response.status !== 401)
+            return response;
+        const currentAuthorization = await source.getAuthorizationHeader();
+        const refreshedAuthorization = currentAuthorization && currentAuthorization !== authorization
+            ? currentAuthorization
+            : await source.getAuthorizationHeader({ forceRefresh: true });
+        if (!refreshedAuthorization)
+            return response;
+        const retryResponse = await fetcher(withAuthorization(retryAttempt, refreshedAuthorization));
+        return retryResponse.status === 401 ? markRetryExhausted(retryResponse) : retryResponse;
+    });
+}

package/dist/errors.d.ts

@@ -0,0 +1,19 @@
+export interface SSOAuthErrorOptions {
+    code?: string;
+    details?: unknown;
+    body?: unknown;
+    retryable?: boolean;
+    cause?: unknown;
+}
+export declare class SSOAuthError extends Error {
+    readonly statusCode: number;
+    readonly code?: string;
+    readonly details?: unknown;
+    readonly body?: unknown;
+    readonly retryable: boolean;
+    readonly cause?: unknown;
+    constructor(message: string, statusCode: number, options?: SSOAuthErrorOptions);
+}
+export declare function createSSOAuthResponseError(response: Response, fallbackMessage: string): Promise<SSOAuthError>;
+export declare function createSSOAuthNetworkError(error: unknown, fallbackMessage: string): SSOAuthError;
+export declare function isTerminalSessionError(error: unknown): boolean;