@svadmin/sso 0.9.0 → 0.11.0

package/dist/errors.js

@@ -0,0 +1,86 @@
+const RETRYABLE_STATUS_CODES = new Set([0, 408, 429, 500, 502, 503, 504]);
+const TERMINAL_OAUTH_CODES = new Set([
+    'invalid_grant',
+    'invalid_token',
+    'session_not_found',
+    'refresh_token_not_found',
+    'refresh_token_already_used',
+    'refresh_token_reuse_detected',
+    'invalid_refresh_token',
+    'session_expired',
+    'session_persistence_failed',
+    'auth_retry_exhausted',
+    'session_refresh_failed',
+]);
+export class SSOAuthError extends Error {
+    statusCode;
+    code;
+    details;
+    body;
+    retryable;
+    cause;
+    constructor(message, statusCode, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = 'SSOAuthError';
+        this.statusCode = statusCode;
+        this.code = options.code;
+        this.details = options.details;
+        this.body = options.body;
+        this.retryable = options.retryable ?? RETRYABLE_STATUS_CODES.has(statusCode);
+        this.cause = options.cause;
+    }
+}
+function asRecord(value) {
+    return typeof value === 'object' && value !== null
+        ? value
+        : null;
+}
+function firstString(...values) {
+    return values.find((value) => typeof value === 'string');
+}
+async function readResponseBody(response) {
+    const text = await response.text();
+    if (!text)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+export async function createSSOAuthResponseError(response, fallbackMessage) {
+    const body = await readResponseBody(response);
+    const record = asRecord(body);
+    const nestedError = asRecord(record?.error);
+    const code = firstString(record?.code, record?.error_code, nestedError?.code, nestedError?.error_code, record?.error);
+    const description = firstString(record?.error_description, nestedError?.error_description);
+    const responseMessage = firstString(record?.message, nestedError?.message);
+    const textMessage = typeof body === 'string' ? body : undefined;
+    const statusMessage = response.statusText || `HTTP ${response.status}`;
+    return new SSOAuthError(description ?? responseMessage ?? textMessage ?? `${fallbackMessage}: ${statusMessage}`, response.status, {
+        code,
+        details: record?.details ?? nestedError?.details,
+        body,
+    });
+}
+export function createSSOAuthNetworkError(error, fallbackMessage) {
+    if (error instanceof SSOAuthError)
+        return error;
+    const isAbort = (typeof DOMException !== 'undefined'
+        && error instanceof DOMException
+        && error.name === 'AbortError') || (typeof error === 'object'
+        && error !== null
+        && 'name' in error
+        && error.name === 'AbortError');
+    return new SSOAuthError(error instanceof Error ? error.message : fallbackMessage, 0, {
+        code: isAbort ? 'request_aborted' : 'network_error',
+        retryable: !isAbort,
+        cause: error,
+    });
+}
+export function isTerminalSessionError(error) {
+    const record = asRecord(error);
+    const code = firstString(record?.code, record?.error_code, asRecord(record?.error)?.code, asRecord(record?.error)?.error_code);
+    return code !== undefined && TERMINAL_OAUTH_CODES.has(code);
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @svadmin/sso — OIDC/OAuth2 SSO AuthProvider plugin
+ *
+ * Usage:
+ * ```ts
+ * import { createSSOAuthProvider, createGoogleAuth } from '@svadmin/sso';
+ * ```
+ */
+export { createSSOAuthProvider } from './auth-provider.js';
+export type { AuthStateChangeCallback, AuthStateChangeEvent, GetAccessTokenOptions, RefreshLock, SSOAuthProvider, SSOConfig, SSOSession, TokenStorage, } from './auth-provider.js';
+export { SSOAuthError } from './errors.js';
+export { createGoogleAuth, createMicrosoftAuth, createGitHubAuth, createGitLabAuth, createKeycloakAuth, createAuth0Auth, createSupauthAuth, } from './presets.js';
+export type { PresetOptions } from './presets.js';
+export { generateState, generateVerifier, generateChallenge, isValidReturnTo, getForwardedOrigin, resolveAuthorizeUrl, resolveTokenUrl, } from './auth-helpers.js';

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * @svadmin/sso — OIDC/OAuth2 SSO AuthProvider plugin
+ *
+ * Usage:
+ * ```ts
+ * import { createSSOAuthProvider, createGoogleAuth } from '@svadmin/sso';
+ * ```
+ */
+export { createSSOAuthProvider } from './auth-provider.js';
+export { SSOAuthError } from './errors.js';
+// Social login presets
+export { createGoogleAuth, createMicrosoftAuth, createGitHubAuth, createGitLabAuth, createKeycloakAuth, createAuth0Auth, createSupauthAuth, } from './presets.js';
+// Auth helpers (PKCE, OIDC discovery, redirect validation)
+export { generateState, generateVerifier, generateChallenge, isValidReturnTo, getForwardedOrigin, resolveAuthorizeUrl, resolveTokenUrl, } from './auth-helpers.js';

package/dist/presets.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Social login presets — pre-configured SSO providers for common identity platforms.
+ *
+ * Each factory function returns an AuthProvider via `createSSOAuthProvider()`
+ * with the correct issuer and default scopes for that platform.
+ *
+ * @example
+ * ```ts
+ * import { createGoogleAuth } from '@svadmin/sso';
+ * import { setAuthProvider } from '@svadmin/core';
+ *
+ * setAuthProvider(createGoogleAuth('your-client-id'));
+ * ```
+ */
+import { type SSOConfig } from './auth-provider.js';
+type PresetOptions = Omit<SSOConfig, 'issuer' | 'clientId'>;
+/**
+ * Google Sign-In via OIDC (OpenID Connect).
+ *
+ * Prerequisites:
+ * 1. Create OAuth2 credentials at https://console.cloud.google.com/apis/credentials
+ * 2. Add authorized redirect URIs (e.g., `http://localhost:5173/callback`)
+ *
+ * @param clientId - Google OAuth2 Client ID
+ */
+export declare function createGoogleAuth(clientId: string, opts?: PresetOptions): import("./auth-provider.js").SSOAuthProvider;
+/**
+ * Microsoft / Azure AD Sign-In via OIDC.
+ *
+ * @param clientId - Azure App Registration Client ID
+ * @param tenantId - Azure tenant ID. Default: 'common' (multi-tenant)
+ */
+export declare function createMicrosoftAuth(clientId: string, tenantId?: string, opts?: PresetOptions): import("./auth-provider.js").SSOAuthProvider;
+/**
+ * GitHub Sign-In via OAuth2.
+ *
+ * Note: GitHub does NOT support OIDC discovery, so we manually specify endpoints.
+ * The `issuer` field is used for identification only.
+ *
+ * Prerequisites:
+ * 1. Create an OAuth App at https://github.com/settings/developers
+ * 2. Set the callback URL to your redirect URI
+ *
+ * @param clientId - GitHub OAuth App Client ID
+ */
+export declare function createGitHubAuth(clientId: string, opts?: PresetOptions): import("./auth-provider.js").SSOAuthProvider;
+/**
+ * GitLab Sign-In via OIDC.
+ *
+ * @param clientId - GitLab Application ID
+ * @param instanceUrl - GitLab instance URL. Default: 'https://gitlab.com'
+ */
+export declare function createGitLabAuth(clientId: string, instanceUrl?: string, opts?: PresetOptions): import("./auth-provider.js").SSOAuthProvider;
+/**
+ * Keycloak Sign-In via OIDC.
+ *
+ * @param baseUrl - Keycloak base URL (e.g., 'https://keycloak.example.com')
+ * @param realm - Keycloak realm name
+ * @param clientId - Keycloak Client ID
+ */
+export declare function createKeycloakAuth(baseUrl: string, realm: string, clientId: string, opts?: PresetOptions): import("./auth-provider.js").SSOAuthProvider;
+/**
+ * Auth0 Sign-In via OIDC.
+ *
+ * @param domain - Auth0 domain (e.g., 'your-tenant.auth0.com')
+ * @param clientId - Auth0 Client ID
+ */
+export declare function createAuth0Auth(domain: string, clientId: string, opts?: PresetOptions): import("./auth-provider.js").SSOAuthProvider;
+export type { PresetOptions };
+/**
+ * Supauth OIDC Sign-In (GoTrue-compatible identity provider).
+ *
+ * Compatible with SupaCloud, SupaOAuth, and any GoTrue-based auth backend.
+ * Uses standard OIDC Authorization Code Flow with PKCE.
+ *
+ * @param issuer - Supauth issuer URL (e.g., 'https://auth.example.com')
+ * @param clientId - OAuth2 Client ID
+ */
+export declare function createSupauthAuth(clientId: string, opts?: PresetOptions & {
+    issuer?: string;
+}): import("./auth-provider.js").SSOAuthProvider;

package/dist/presets.js

@@ -0,0 +1,165 @@
+/**
+ * Social login presets — pre-configured SSO providers for common identity platforms.
+ *
+ * Each factory function returns an AuthProvider via `createSSOAuthProvider()`
+ * with the correct issuer and default scopes for that platform.
+ *
+ * @example
+ * ```ts
+ * import { createGoogleAuth } from '@svadmin/sso';
+ * import { setAuthProvider } from '@svadmin/core';
+ *
+ * setAuthProvider(createGoogleAuth('your-client-id'));
+ * ```
+ */
+import { createSSOAuthProvider } from './auth-provider.js';
+function resolveRedirectUri(opts) {
+    return opts?.redirectUri ?? (typeof window !== 'undefined' ? `${window.location.origin}/callback` : '/callback');
+}
+// ─── Google ──────────────────────────────────────────────────
+/**
+ * Google Sign-In via OIDC (OpenID Connect).
+ *
+ * Prerequisites:
+ * 1. Create OAuth2 credentials at https://console.cloud.google.com/apis/credentials
+ * 2. Add authorized redirect URIs (e.g., `http://localhost:5173/callback`)
+ *
+ * @param clientId - Google OAuth2 Client ID
+ */
+export function createGoogleAuth(clientId, opts) {
+    const issuer = 'https://accounts.google.com';
+    return createSSOAuthProvider({
+        issuer,
+        clientId,
+        scopes: ['openid', 'profile', 'email'],
+        redirectUri: resolveRedirectUri(opts),
+        ...opts,
+    });
+}
+// ─── Microsoft / Azure AD (Entra ID) ────────────────────────
+/**
+ * Microsoft / Azure AD Sign-In via OIDC.
+ *
+ * @param clientId - Azure App Registration Client ID
+ * @param tenantId - Azure tenant ID. Default: 'common' (multi-tenant)
+ */
+export function createMicrosoftAuth(clientId, tenantId = 'common', opts) {
+    const issuer = `https://login.microsoftonline.com/${tenantId}/v2.0`;
+    return createSSOAuthProvider({
+        issuer,
+        clientId,
+        scopes: ['openid', 'profile', 'email'],
+        redirectUri: resolveRedirectUri(opts),
+        ...opts,
+    });
+}
+// ─── GitHub ──────────────────────────────────────────────────
+/**
+ * GitHub Sign-In via OAuth2.
+ *
+ * Note: GitHub does NOT support OIDC discovery, so we manually specify endpoints.
+ * The `issuer` field is used for identification only.
+ *
+ * Prerequisites:
+ * 1. Create an OAuth App at https://github.com/settings/developers
+ * 2. Set the callback URL to your redirect URI
+ *
+ * @param clientId - GitHub OAuth App Client ID
+ */
+export function createGitHubAuth(clientId, opts) {
+    // GitHub uses standard OAuth2, not OIDC — requires manual endpoint config.
+    // We leverage the SSO provider but override the discovery with manual endpoints.
+    const redirectUri = resolveRedirectUri(opts);
+    const issuer = 'https://github.com';
+    return createSSOAuthProvider({
+        issuer,
+        clientId,
+        scopes: ['read:user', 'user:email'],
+        redirectUri,
+        // GitHub doesn't support OIDC discovery, provide manual endpoints
+        manualEndpoints: {
+            authorization_endpoint: 'https://github.com/login/oauth/authorize',
+            token_endpoint: 'https://github.com/login/oauth/access_token',
+            userinfo_endpoint: 'https://api.github.com/user',
+        },
+        mapIdentity: (userinfo) => ({
+            id: String(userinfo.id ?? ''),
+            name: userinfo.name ?? userinfo.login ?? '',
+            avatar: userinfo.avatar_url ?? undefined,
+            email: userinfo.email ?? undefined,
+        }),
+        ...opts,
+    });
+}
+// ─── GitLab ──────────────────────────────────────────────────
+/**
+ * GitLab Sign-In via OIDC.
+ *
+ * @param clientId - GitLab Application ID
+ * @param instanceUrl - GitLab instance URL. Default: 'https://gitlab.com'
+ */
+export function createGitLabAuth(clientId, instanceUrl = 'https://gitlab.com', opts) {
+    const issuer = instanceUrl;
+    return createSSOAuthProvider({
+        issuer,
+        clientId,
+        scopes: ['openid', 'profile', 'email'],
+        redirectUri: resolveRedirectUri(opts),
+        ...opts,
+    });
+}
+// ─── Keycloak ────────────────────────────────────────────────
+/**
+ * Keycloak Sign-In via OIDC.
+ *
+ * @param baseUrl - Keycloak base URL (e.g., 'https://keycloak.example.com')
+ * @param realm - Keycloak realm name
+ * @param clientId - Keycloak Client ID
+ */
+export function createKeycloakAuth(baseUrl, realm, clientId, opts) {
+    const issuer = `${baseUrl.replace(/\/$/, '')}/realms/${realm}`;
+    return createSSOAuthProvider({
+        issuer,
+        clientId,
+        scopes: ['openid', 'profile', 'email'],
+        redirectUri: resolveRedirectUri(opts),
+        ...opts,
+    });
+}
+// ─── Auth0 ───────────────────────────────────────────────────
+/**
+ * Auth0 Sign-In via OIDC.
+ *
+ * @param domain - Auth0 domain (e.g., 'your-tenant.auth0.com')
+ * @param clientId - Auth0 Client ID
+ */
+export function createAuth0Auth(domain, clientId, opts) {
+    const issuer = `https://${domain.replace(/^https?:\/\//, '').replace(/\/$/, '')}`;
+    return createSSOAuthProvider({
+        issuer,
+        clientId,
+        scopes: ['openid', 'profile', 'email'],
+        redirectUri: resolveRedirectUri(opts),
+        ...opts,
+    });
+}
+// ─── Supauth / GoTrue ────────────────────────────────────────
+/**
+ * Supauth OIDC Sign-In (GoTrue-compatible identity provider).
+ *
+ * Compatible with SupaCloud, SupaOAuth, and any GoTrue-based auth backend.
+ * Uses standard OIDC Authorization Code Flow with PKCE.
+ *
+ * @param issuer - Supauth issuer URL (e.g., 'https://auth.example.com')
+ * @param clientId - OAuth2 Client ID
+ */
+export function createSupauthAuth(clientId, opts) {
+    const issuer = opts?.issuer ?? '';
+    return createSSOAuthProvider({
+        issuer,
+        clientId,
+        scopes: ['openid', 'profile', 'email'],
+        redirectUri: resolveRedirectUri(opts),
+        ...opts,
+    });
+}

package/dist/session-manager.d.ts

@@ -0,0 +1,50 @@
+export interface SSOSession {
+    access_token: string;
+    id_token?: string;
+    refresh_token?: string;
+    expires_at?: number;
+    token_type: string;
+}
+export interface GetAccessTokenOptions {
+    minValiditySeconds?: number;
+    forceRefresh?: boolean;
+}
+export type AuthStateChangeEvent = 'TOKEN_REFRESHED' | 'SIGNED_OUT';
+export type AuthStateChangeCallback = (event: AuthStateChangeEvent, session: SSOSession | null) => void | Promise<void>;
+export interface RefreshLock {
+    /** Serialize every context that shares the same token storage. */
+    request<T>(name: string, operation: () => Promise<T>): Promise<T>;
+}
+interface SessionManagerOptions {
+    storage: TokenStorageLike;
+    storageKey: string;
+    autoRefresh: boolean;
+    refreshBuffer: number;
+    refreshLock?: RefreshLock;
+    refresh: (session: SSOSession) => Promise<SSOSession>;
+    legacyStorageKey?: string;
+}
+export interface TokenStorageLike {
+    getItem: (key: string) => string | null;
+    setItem: (key: string, value: string) => void;
+    removeItem: (key: string) => void;
+}
+export interface SessionManager {
+    getSession: () => SSOSession | null;
+    getAuthGeneration: () => number;
+    saveSession: (session: SSOSession, event?: AuthStateChangeEvent) => void;
+    clearSession: () => void;
+    beginAuthAttempt: () => void;
+    beginSignOut: () => void;
+    setLoginState: (verifier: string, state: string) => void;
+    getPKCEVerifier: () => string | null;
+    getLoginState: () => string | null;
+    clearLoginState: (expectedState?: string) => void;
+    runAuthMutation: <T>(operation: () => Promise<T>) => Promise<T>;
+    refreshSession: () => Promise<SSOSession | null>;
+    getAccessToken: (options?: GetAccessTokenOptions) => Promise<string | null>;
+    onAuthStateChange: (callback: AuthStateChangeCallback) => () => void;
+    destroy: () => void;
+}
+export declare function createSessionManager(options: SessionManagerOptions): SessionManager;
+export {};