@crimson-education/sdk 0.2.0

package/dist/core/auth/token-manager.js

@@ -0,0 +1,294 @@
+"use strict";
+/**
+ * Token Manager
+ * Handles token lifecycle, automatic refresh, and state management
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TokenManager = void 0;
+/** Buffer time before expiration to trigger refresh (5 minutes) */
+const REFRESH_BUFFER_MS = 5 * 60 * 1000;
+/** Minimum time between refresh attempts (30 seconds) */
+const MIN_REFRESH_INTERVAL_MS = 30 * 1000;
+class TokenManager {
+    constructor(config) {
+        var _a, _b;
+        this.listeners = new Set();
+        this.refreshPromise = null;
+        this.refreshTimer = null;
+        this.lastRefreshAttempt = 0;
+        this.currentState = {
+            isAuthenticated: false,
+            isLoading: true,
+            tokens: null,
+            error: null,
+        };
+        this.storage = config.storage;
+        this.onRefreshNeeded = config.onRefreshNeeded;
+        this.refreshBufferMs = (_a = config.refreshBufferMs) !== null && _a !== void 0 ? _a : REFRESH_BUFFER_MS;
+        this.autoRefresh = (_b = config.autoRefresh) !== null && _b !== void 0 ? _b : true;
+    }
+    /**
+     * Initialize the token manager
+     * Loads tokens from storage and sets up auto-refresh if enabled
+     */
+    initialize() {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const tokens = yield this.storage.getTokens();
+                if (tokens) {
+                    if (this.isTokenExpired(tokens)) {
+                        // Token expired, try to refresh
+                        if (tokens.refreshToken) {
+                            yield this.refreshToken();
+                        }
+                        else {
+                            // No refresh token, clear and set unauthenticated
+                            yield this.storage.clearTokens();
+                            this.updateState({
+                                isAuthenticated: false,
+                                isLoading: false,
+                                tokens: null,
+                                error: null,
+                            });
+                        }
+                    }
+                    else {
+                        // Token still valid
+                        this.updateState({
+                            isAuthenticated: true,
+                            isLoading: false,
+                            tokens,
+                            error: null,
+                        });
+                        this.scheduleRefresh(tokens);
+                    }
+                }
+                else {
+                    this.updateState({
+                        isAuthenticated: false,
+                        isLoading: false,
+                        tokens: null,
+                        error: null,
+                    });
+                }
+            }
+            catch (error) {
+                this.updateState({
+                    isAuthenticated: false,
+                    isLoading: false,
+                    tokens: null,
+                    error: error instanceof Error ? error : new Error(String(error)),
+                });
+            }
+        });
+    }
+    /**
+     * Get current authentication state
+     */
+    getState() {
+        return this.currentState;
+    }
+    /**
+     * Get current access token if valid
+     * Automatically refreshes if needed and possible
+     */
+    getAccessToken() {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const tokens = yield this.storage.getTokens();
+            if (!tokens) {
+                return null;
+            }
+            // Check if token needs refresh
+            if (this.shouldRefresh(tokens)) {
+                const refreshed = yield this.refreshToken();
+                return (_a = refreshed === null || refreshed === void 0 ? void 0 : refreshed.accessToken) !== null && _a !== void 0 ? _a : null;
+            }
+            return tokens.accessToken;
+        });
+    }
+    /**
+     * Set new tokens (after successful authorization)
+     */
+    setTokens(tokens) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.storage.setTokens(tokens);
+            this.updateState({
+                isAuthenticated: true,
+                isLoading: false,
+                tokens,
+                error: null,
+            });
+            this.scheduleRefresh(tokens);
+        });
+    }
+    /**
+     * Refresh the access token
+     * Uses a lock to prevent concurrent refresh attempts
+     */
+    refreshToken() {
+        return __awaiter(this, void 0, void 0, function* () {
+            // Check minimum refresh interval
+            const now = Date.now();
+            if (now - this.lastRefreshAttempt < MIN_REFRESH_INTERVAL_MS) {
+                // Wait for existing refresh or return current tokens
+                if (this.refreshPromise) {
+                    return this.refreshPromise;
+                }
+                return this.currentState.tokens;
+            }
+            // If refresh already in progress, wait for it
+            if (this.refreshPromise) {
+                return this.refreshPromise;
+            }
+            this.lastRefreshAttempt = now;
+            // Start refresh with lock
+            this.refreshPromise = this.doRefresh();
+            try {
+                return yield this.refreshPromise;
+            }
+            finally {
+                this.refreshPromise = null;
+            }
+        });
+    }
+    doRefresh() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const currentTokens = yield this.storage.getTokens();
+            if (!(currentTokens === null || currentTokens === void 0 ? void 0 : currentTokens.refreshToken)) {
+                this.updateState({
+                    isAuthenticated: false,
+                    isLoading: false,
+                    tokens: null,
+                    error: new Error("No refresh token available"),
+                });
+                return null;
+            }
+            try {
+                const newTokens = yield this.onRefreshNeeded(currentTokens.refreshToken);
+                if (newTokens) {
+                    yield this.storage.setTokens(newTokens);
+                    this.updateState({
+                        isAuthenticated: true,
+                        isLoading: false,
+                        tokens: newTokens,
+                        error: null,
+                    });
+                    this.scheduleRefresh(newTokens);
+                    return newTokens;
+                }
+                else {
+                    // Refresh failed, clear tokens
+                    yield this.storage.clearTokens();
+                    this.updateState({
+                        isAuthenticated: false,
+                        isLoading: false,
+                        tokens: null,
+                        error: new Error("Token refresh failed"),
+                    });
+                    return null;
+                }
+            }
+            catch (error) {
+                // Check if this is a revocation/invalid token error
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                const isRevoked = errorMessage.includes("invalid_grant") ||
+                    errorMessage.includes("revoked") ||
+                    errorMessage.includes("reuse");
+                if (isRevoked) {
+                    // Token was revoked or reused, clear everything
+                    yield this.storage.clearTokens();
+                }
+                this.updateState({
+                    isAuthenticated: false,
+                    isLoading: false,
+                    tokens: isRevoked ? null : this.currentState.tokens,
+                    error: error instanceof Error ? error : new Error(String(error)),
+                });
+                return null;
+            }
+        });
+    }
+    /**
+     * Clear tokens (logout)
+     */
+    clearTokens() {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.cancelScheduledRefresh();
+            yield this.storage.clearTokens();
+            this.updateState({
+                isAuthenticated: false,
+                isLoading: false,
+                tokens: null,
+                error: null,
+            });
+        });
+    }
+    /**
+     * Subscribe to auth state changes
+     */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        // Immediately call with current state
+        listener(this.currentState);
+        // Return unsubscribe function
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /**
+     * Clean up resources
+     */
+    destroy() {
+        this.cancelScheduledRefresh();
+        this.listeners.clear();
+    }
+    updateState(newState) {
+        this.currentState = newState;
+        this.listeners.forEach((listener) => {
+            try {
+                listener(newState);
+            }
+            catch (_a) {
+                // Ignore listener errors
+            }
+        });
+    }
+    isTokenExpired(tokens) {
+        return Date.now() >= tokens.expiresAt;
+    }
+    shouldRefresh(tokens) {
+        // Refresh if within buffer time of expiration
+        return Date.now() >= tokens.expiresAt - this.refreshBufferMs;
+    }
+    scheduleRefresh(tokens) {
+        if (!this.autoRefresh || !tokens.refreshToken) {
+            return;
+        }
+        this.cancelScheduledRefresh();
+        // Calculate time until refresh is needed
+        const refreshAt = tokens.expiresAt - this.refreshBufferMs;
+        const delay = Math.max(refreshAt - Date.now(), 0);
+        this.refreshTimer = setTimeout(() => {
+            this.refreshToken().catch(() => {
+                // Refresh error handled in doRefresh
+            });
+        }, delay);
+    }
+    cancelScheduledRefresh() {
+        if (this.refreshTimer) {
+            clearTimeout(this.refreshTimer);
+            this.refreshTimer = null;
+        }
+    }
+}
+exports.TokenManager = TokenManager;

package/dist/core/auth/token-storage.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Token Storage Implementations
+ * Provides different storage strategies for OAuth tokens
+ */
+import { OAuthTokens, TokenStorage } from "./types";
+/**
+ * LocalStorage-based token storage
+ * Persists tokens across browser sessions
+ * Suitable for web applications where persistence is desired
+ */
+export declare class LocalStorageTokenStorage implements TokenStorage {
+    private readonly storageKey;
+    constructor(storageKey?: string);
+    getTokens(): Promise<OAuthTokens | null>;
+    setTokens(tokens: OAuthTokens): Promise<void>;
+    clearTokens(): Promise<void>;
+}
+/**
+ * SessionStorage-based token storage
+ * Tokens are cleared when the browser tab is closed
+ * More secure than localStorage for sensitive applications
+ */
+export declare class SessionStorageTokenStorage implements TokenStorage {
+    private readonly storageKey;
+    constructor(storageKey?: string);
+    getTokens(): Promise<OAuthTokens | null>;
+    setTokens(tokens: OAuthTokens): Promise<void>;
+    clearTokens(): Promise<void>;
+}
+/**
+ * In-memory token storage
+ * Tokens are lost on page refresh - most secure option
+ * Suitable for high-security applications or server-side usage
+ */
+export declare class MemoryTokenStorage implements TokenStorage {
+    private tokens;
+    getTokens(): Promise<OAuthTokens | null>;
+    setTokens(tokens: OAuthTokens): Promise<void>;
+    clearTokens(): Promise<void>;
+}
+/**
+ * Create a default token storage based on the environment
+ * - Browser: LocalStorageTokenStorage
+ * - Server/Node.js: MemoryTokenStorage
+ */
+export declare function createDefaultTokenStorage(): TokenStorage;

package/dist/core/auth/token-storage.js

@@ -0,0 +1,155 @@
+"use strict";
+/**
+ * Token Storage Implementations
+ * Provides different storage strategies for OAuth tokens
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryTokenStorage = exports.SessionStorageTokenStorage = exports.LocalStorageTokenStorage = void 0;
+exports.createDefaultTokenStorage = createDefaultTokenStorage;
+const STORAGE_KEY = "crimson_oauth_tokens";
+/**
+ * LocalStorage-based token storage
+ * Persists tokens across browser sessions
+ * Suitable for web applications where persistence is desired
+ */
+class LocalStorageTokenStorage {
+    constructor(storageKey = STORAGE_KEY) {
+        this.storageKey = storageKey;
+    }
+    getTokens() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (typeof window === "undefined" || !window.localStorage) {
+                return null;
+            }
+            try {
+                const stored = localStorage.getItem(this.storageKey);
+                if (!stored) {
+                    return null;
+                }
+                const tokens = JSON.parse(stored);
+                // Validate token structure
+                if (!tokens.accessToken || !tokens.expiresAt) {
+                    return null;
+                }
+                return tokens;
+            }
+            catch (_a) {
+                // Invalid JSON or other error
+                return null;
+            }
+        });
+    }
+    setTokens(tokens) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (typeof window === "undefined" || !window.localStorage) {
+                throw new Error("localStorage is not available");
+            }
+            localStorage.setItem(this.storageKey, JSON.stringify(tokens));
+        });
+    }
+    clearTokens() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (typeof window === "undefined" || !window.localStorage) {
+                return;
+            }
+            localStorage.removeItem(this.storageKey);
+        });
+    }
+}
+exports.LocalStorageTokenStorage = LocalStorageTokenStorage;
+/**
+ * SessionStorage-based token storage
+ * Tokens are cleared when the browser tab is closed
+ * More secure than localStorage for sensitive applications
+ */
+class SessionStorageTokenStorage {
+    constructor(storageKey = STORAGE_KEY) {
+        this.storageKey = storageKey;
+    }
+    getTokens() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (typeof window === "undefined" || !window.sessionStorage) {
+                return null;
+            }
+            try {
+                const stored = sessionStorage.getItem(this.storageKey);
+                if (!stored) {
+                    return null;
+                }
+                const tokens = JSON.parse(stored);
+                // Validate token structure
+                if (!tokens.accessToken || !tokens.expiresAt) {
+                    return null;
+                }
+                return tokens;
+            }
+            catch (_a) {
+                // Invalid JSON or other error
+                return null;
+            }
+        });
+    }
+    setTokens(tokens) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (typeof window === "undefined" || !window.sessionStorage) {
+                throw new Error("sessionStorage is not available");
+            }
+            sessionStorage.setItem(this.storageKey, JSON.stringify(tokens));
+        });
+    }
+    clearTokens() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (typeof window === "undefined" || !window.sessionStorage) {
+                return;
+            }
+            sessionStorage.removeItem(this.storageKey);
+        });
+    }
+}
+exports.SessionStorageTokenStorage = SessionStorageTokenStorage;
+/**
+ * In-memory token storage
+ * Tokens are lost on page refresh - most secure option
+ * Suitable for high-security applications or server-side usage
+ */
+class MemoryTokenStorage {
+    constructor() {
+        this.tokens = null;
+    }
+    getTokens() {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.tokens;
+        });
+    }
+    setTokens(tokens) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.tokens = tokens;
+        });
+    }
+    clearTokens() {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.tokens = null;
+        });
+    }
+}
+exports.MemoryTokenStorage = MemoryTokenStorage;
+/**
+ * Create a default token storage based on the environment
+ * - Browser: LocalStorageTokenStorage
+ * - Server/Node.js: MemoryTokenStorage
+ */
+function createDefaultTokenStorage() {
+    if (typeof window !== "undefined" && window.localStorage) {
+        return new LocalStorageTokenStorage();
+    }
+    return new MemoryTokenStorage();
+}

package/dist/core/auth/types.d.ts

@@ -0,0 +1,148 @@
+/**
+ * OAuth Authentication Types
+ */
+/**
+ * OAuth configuration for the adapter
+ */
+export interface OAuthConfig {
+    /**
+     * OAuth client ID
+     */
+    clientId: string;
+    /**
+     * OAuth client secret (for confidential clients only)
+     */
+    clientSecret?: string;
+    /**
+     * Redirect URI for OAuth callback
+     */
+    redirectUri: string;
+    /**
+     * Authorization endpoint URL
+     */
+    authorizationEndpoint: string;
+    /**
+     * Token endpoint URL
+     */
+    tokenEndpoint: string;
+    /**
+     * Token revocation endpoint URL (optional)
+     */
+    revocationEndpoint?: string;
+    /**
+     * Requested scopes
+     */
+    scope?: string[];
+}
+/**
+ * OAuth token response
+ */
+export interface OAuthTokens {
+    /** Access token */
+    accessToken: string;
+    /** Refresh token (if granted) */
+    refreshToken?: string;
+    /** Token type (always Bearer) */
+    tokenType: string;
+    /** Expiration timestamp in milliseconds */
+    expiresAt: number;
+    /** Granted scopes */
+    scope?: string[];
+}
+/**
+ * OAuth authorization options
+ */
+export interface AuthorizeOptions {
+    /**
+     * Override redirect URI
+     */
+    redirectUri?: string;
+    /**
+     * Override requested scopes
+     */
+    scope?: string[];
+    /**
+     * Force user to re-authenticate
+     */
+    prompt?: "login" | "consent" | "none";
+    /**
+     * Pre-fill login with this email
+     */
+    loginHint?: string;
+}
+/**
+ * OAuth callback parameters (from URL query string)
+ */
+export interface CallbackParams {
+    /** Authorization code */
+    code?: string;
+    /** State parameter for CSRF protection */
+    state?: string;
+    /** OAuth error code (if authorization failed) */
+    error?: string;
+    /** OAuth error description */
+    errorDescription?: string;
+    /** Override redirect URI for code exchange */
+    redirectUri?: string;
+}
+/**
+ * OAuth error
+ */
+export interface OAuthError {
+    error: string;
+    errorDescription?: string;
+    errorUri?: string;
+}
+/**
+ * OAuth Authentication state
+ */
+export interface OAuthAuthState {
+    /** Whether the user is authenticated */
+    isAuthenticated: boolean;
+    /** Whether authentication is in progress */
+    isLoading: boolean;
+    /** Current tokens (if authenticated) */
+    tokens: OAuthTokens | null;
+    /** Last error (if any) */
+    error: Error | OAuthError | null;
+}
+/**
+ * OAuth auth state change listener
+ */
+export type OAuthAuthStateListener = (state: OAuthAuthState) => void;
+/**
+ * Token refresh function signature
+ */
+export type TokenRefreshFunction = (refreshToken: string) => Promise<OAuthTokens | null>;
+/**
+ * Token storage interface
+ * All methods are async to support various storage backends
+ */
+export interface TokenStorage {
+    /** Get stored tokens */
+    getTokens(): Promise<OAuthTokens | null>;
+    /** Store tokens */
+    setTokens(tokens: OAuthTokens): Promise<void>;
+    /** Clear stored tokens */
+    clearTokens(): Promise<void>;
+}
+/**
+ * PKCE state stored during authorization
+ */
+export interface PkceState {
+    /** Code verifier (kept secret) */
+    codeVerifier: string;
+    /** State parameter for CSRF protection */
+    state: string;
+    /** Timestamp when PKCE state was created */
+    createdAt: number;
+}
+/**
+ * OAuth endpoints paths
+ */
+export declare const OAUTH_ENDPOINTS: {
+    readonly AUTHORIZE: "/oauth/authorize";
+    readonly TOKEN: "/oauth/token";
+    readonly REVOKE: "/oauth/revoke";
+    readonly USERINFO: "/oauth/userinfo";
+};

package/dist/core/auth/types.js

@@ -0,0 +1,15 @@
+"use strict";
+/**
+ * OAuth Authentication Types
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OAUTH_ENDPOINTS = void 0;
+/**
+ * OAuth endpoints paths
+ */
+exports.OAUTH_ENDPOINTS = {
+    AUTHORIZE: "/oauth/authorize",
+    TOKEN: "/oauth/token",
+    REVOKE: "/oauth/revoke",
+    USERINFO: "/oauth/userinfo",
+};