@svadmin/sso 0.10.0 → 0.11.0

package/dist/auth-helpers.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 浏览器端 OIDC/OAuth2 认证辅助函数。
+ *
+ * 提供 PKCE 生成、OIDC Discovery 端点解析、重定向校验、
+ * 反向代理 origin 恢复等通用工具。
+ */
+/** 生成随机的 OAuth state 值 */
+export declare function generateState(): string;
+/** 生成 PKCE code verifier */
+export declare function generateVerifier(): string;
+/** 基于 code verifier 算得 code challenge (S256) */
+export declare function generateChallenge(verifier: string): Promise<string>;
+/**
+ * 校验 returnTo 重定向地址，防止开放重定向漏洞。
+ * 只允许同源相对路径（必须以 / 开头且非 // 开头）。
+ */
+export declare function isValidReturnTo(url: string): boolean;
+/** 从反向代理头恢复公网 origin */
+export declare function getForwardedOrigin(req: Request, fallbackUrl: URL): string;
+/** 通过 OIDC Discovery 解析授权端点 URL */
+export declare function resolveAuthorizeUrl(issuer: string, overrideUrl?: string, fetcher?: typeof fetch): Promise<string>;
+/** 通过 OIDC Discovery 解析 token 端点 URL */
+export declare function resolveTokenUrl(issuer: string, overrideUrlOrFetcher?: string | typeof fetch, fetcherOverride?: typeof fetch): Promise<string>;

package/dist/auth-helpers.js

@@ -0,0 +1,97 @@
+/**
+ * 浏览器端 OIDC/OAuth2 认证辅助函数。
+ *
+ * 提供 PKCE 生成、OIDC Discovery 端点解析、重定向校验、
+ * 反向代理 origin 恢复等通用工具。
+ */
+/** 将 Uint8Array 编码为 base64url 格式 (纯 Web API) */
+function base64url(array) {
+    let binary = "";
+    for (const byte of array)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+/** 生成随机的 OAuth state 值 */
+export function generateState() {
+    const array = new Uint8Array(16);
+    crypto.getRandomValues(array);
+    return base64url(array);
+}
+/** 生成 PKCE code verifier */
+export function generateVerifier() {
+    const array = new Uint8Array(32);
+    crypto.getRandomValues(array);
+    return base64url(array);
+}
+/** 基于 code verifier 算得 code challenge (S256) */
+export async function generateChallenge(verifier) {
+    const encoder = new TextEncoder();
+    const data = encoder.encode(verifier);
+    const hash = await crypto.subtle.digest("SHA-256", data);
+    return base64url(new Uint8Array(hash));
+}
+/**
+ * 校验 returnTo 重定向地址，防止开放重定向漏洞。
+ * 只允许同源相对路径（必须以 / 开头且非 // 开头）。
+ */
+export function isValidReturnTo(url) {
+    if (!url)
+        return false;
+    if (url.includes("\\"))
+        return false;
+    return /^\/[^/].*/.test(url) || url === "/";
+}
+/** 从反向代理头恢复公网 origin */
+export function getForwardedOrigin(req, fallbackUrl) {
+    const forwardedProto = req.headers.get("x-forwarded-proto")?.split(",")[0]?.trim();
+    const forwardedHost = req.headers.get("x-forwarded-host")?.split(",")[0]?.trim();
+    const host = forwardedHost || req.headers.get("host") || fallbackUrl.host;
+    const protocol = (forwardedProto || fallbackUrl.protocol.replace(/:$/, "")).replace(/:$/, "");
+    return `${protocol}://${host}`;
+}
+/** 通过 OIDC Discovery 解析授权端点 URL */
+export async function resolveAuthorizeUrl(issuer, overrideUrl = "", fetcher = fetch) {
+    const normalizedIssuer = issuer.replace(/\/$/, "");
+    const normalizedOverride = overrideUrl.trim();
+    if (normalizedOverride)
+        return normalizedOverride;
+    if (normalizedIssuer) {
+        try {
+            const response = await fetcher(`${normalizedIssuer}/.well-known/openid-configuration`);
+            if (response.ok) {
+                const discovery = await response.json();
+                if (discovery.authorization_endpoint)
+                    return discovery.authorization_endpoint;
+            }
+        }
+        catch {
+            // 忽略 discovery 失败，走 fallback
+        }
+    }
+    if (normalizedIssuer)
+        return `${normalizedIssuer}/oauth/authorize`;
+    return "";
+}
+/** 通过 OIDC Discovery 解析 token 端点 URL */
+export async function resolveTokenUrl(issuer, overrideUrlOrFetcher = "", fetcherOverride = fetch) {
+    const normalizedIssuer = issuer.replace(/\/$/, "");
+    const fetcher = typeof overrideUrlOrFetcher === "function" ? overrideUrlOrFetcher : fetcherOverride;
+    const overrideUrl = typeof overrideUrlOrFetcher === "string" ? overrideUrlOrFetcher : "";
+    const normalizedOverride = overrideUrl.trim();
+    if (normalizedOverride)
+        return normalizedOverride;
+    if (!normalizedIssuer)
+        return "";
+    try {
+        const response = await fetcher(`${normalizedIssuer}/.well-known/openid-configuration`);
+        if (response.ok) {
+            const discovery = await response.json();
+            if (discovery.token_endpoint)
+                return discovery.token_endpoint;
+        }
+    }
+    catch {
+        // 忽略 discovery 失败
+    }
+    return `${normalizedIssuer}/oauth/token`;
+}

package/dist/auth-provider.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @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 type { AuthProvider, Identity } from '@svadmin/core';
+import { type AuthStateChangeCallback, type GetAccessTokenOptions, type RefreshLock, type SSOSession } from './session-manager.js';
+export interface SSOConfig {
+    /** OIDC Issuer URL (e.g., 'https://your-tenant.okta.com') */
+    issuer: string;
+    /** OAuth2 Client ID */
+    clientId: string;
+    /** Redirect URI after login (e.g., '/callback') */
+    redirectUri: string;
+    /** OAuth2 scopes. Default: ['openid', 'profile', 'email'] */
+    scopes?: string[];
+    /** Where to redirect after logout */
+    postLogoutRedirectUri?: string;
+    /** Token storage backend. Default: 'local' (localStorage) */
+    storage?: 'local' | 'session' | TokenStorage;
+    /** Storage namespace. Defaults to an issuer/client-specific key. */
+    storageKey?: string;
+    /** Explicit legacy namespace to migrate after confirming it belongs to this provider. */
+    legacyStorageKey?: string;
+    /** Custom identity mapper — transform OIDC userinfo to svadmin Identity */
+    mapIdentity?: (userinfo: Record<string, unknown>) => Identity;
+    /** Auto-refresh tokens before expiry. Default: true */
+    autoRefresh?: boolean;
+    /** Seconds before expiry to trigger refresh. Default: 60 */
+    refreshBuffer?: number;
+    /** Additional authorization request parameters, e.g. audience or prompt. */
+    authorizationParams?: Record<string, string>;
+    /**
+     * Atomic authentication coordination lock override. Browsers use Web Locks
+     * by default and fail closed when unavailable; non-browser runtimes
+     * serialize within the process.
+     */
+    refreshLock?: RefreshLock;
+    /** Injectable fetch implementation for testing and SSR runtimes. */
+    fetcher?: typeof fetch;
+    /**
+     * Manual OAuth2 endpoints for providers that don't support OIDC discovery
+     * (e.g., GitHub). When provided, OIDC auto-discovery is skipped.
+     */
+    manualEndpoints?: {
+        authorization_endpoint: string;
+        token_endpoint: string;
+        userinfo_endpoint: string;
+        end_session_endpoint?: string;
+    };
+}
+export interface TokenStorage {
+    getItem: (key: string) => string | null;
+    setItem: (key: string, value: string) => void;
+    removeItem: (key: string) => void;
+}
+export interface SSOAuthProvider extends AuthProvider {
+    getSession: () => Promise<SSOSession | null>;
+    refreshSession: () => Promise<SSOSession | null>;
+    getAccessToken: (options?: GetAccessTokenOptions) => Promise<string | null>;
+    onAuthStateChange: (callback: AuthStateChangeCallback) => () => void;
+    createAuthenticatedFetch: (fetcher?: typeof fetch) => typeof fetch;
+    destroy: () => void;
+}
+/** Create an OIDC/OAuth2 SSO AuthProvider. */
+export declare function createSSOAuthProvider(config: SSOConfig): SSOAuthProvider;
+export type { AuthStateChangeCallback, AuthStateChangeEvent, GetAccessTokenOptions, RefreshLock, SSOSession, } from './session-manager.js';