@crimson-education/sdk 0.2.0

package/dist/core/auth/oauth-adapter.js

@@ -0,0 +1,341 @@
+"use strict";
+/**
+ * OAuth Adapter
+ * Main entry point for OAuth 2.0 authentication with PKCE
+ */
+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.OAuthAdapter = void 0;
+exports.createCrimsonOAuthAdapter = createCrimsonOAuthAdapter;
+const pkce_1 = require("./pkce");
+const token_manager_1 = require("./token-manager");
+const token_storage_1 = require("./token-storage");
+const PKCE_STATE_KEY = "crimson_oauth_pkce_state";
+class OAuthAdapter {
+    constructor(config) {
+        var _a, _b;
+        this.initialized = false;
+        this.config = config;
+        this.storage = (_a = config.storage) !== null && _a !== void 0 ? _a : (0, token_storage_1.createDefaultTokenStorage)();
+        this.tokenManager = new token_manager_1.TokenManager({
+            storage: this.storage,
+            onRefreshNeeded: this.refreshTokenWithApi.bind(this),
+            autoRefresh: (_b = config.autoRefresh) !== null && _b !== void 0 ? _b : true,
+        });
+    }
+    /**
+     * Initialize the OAuth adapter
+     * Loads existing tokens and sets up auto-refresh
+     */
+    initialize() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.initialized) {
+                return;
+            }
+            yield this.tokenManager.initialize();
+            this.initialized = true;
+        });
+    }
+    /**
+     * Get the authorization URL for OAuth flow
+     */
+    getAuthorizeUrl(options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c;
+            const codeVerifier = (0, pkce_1.generateCodeVerifier)();
+            const codeChallenge = yield (0, pkce_1.generateCodeChallenge)(codeVerifier);
+            const state = (0, pkce_1.generateState)();
+            // Store PKCE state for callback verification
+            const pkceState = {
+                codeVerifier,
+                state,
+                createdAt: Date.now(),
+            };
+            this.storePkceState(pkceState);
+            // Build authorization URL
+            const params = new URLSearchParams({
+                response_type: "code",
+                client_id: this.config.clientId,
+                redirect_uri: (_a = options === null || options === void 0 ? void 0 : options.redirectUri) !== null && _a !== void 0 ? _a : this.config.redirectUri,
+                scope: ((_c = (_b = options === null || options === void 0 ? void 0 : options.scope) !== null && _b !== void 0 ? _b : this.config.scope) !== null && _c !== void 0 ? _c : ["profile"]).join(" "),
+                state,
+                code_challenge: codeChallenge,
+                code_challenge_method: "S256",
+            });
+            return `${this.config.authorizationEndpoint}?${params.toString()}`;
+        });
+    }
+    /**
+     * Start the OAuth authorization flow
+     * Redirects the user to the authorization page
+     */
+    authorize(options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const url = yield this.getAuthorizeUrl(options);
+            if (typeof window !== "undefined") {
+                window.location.href = url;
+            }
+            else {
+                throw new Error("authorize() can only be called in a browser environment");
+            }
+        });
+    }
+    /**
+     * Handle the OAuth callback
+     * Exchanges the authorization code for tokens
+     */
+    handleCallback(params) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // Check for error response
+            if (params.error) {
+                const error = {
+                    error: params.error,
+                    errorDescription: params.errorDescription,
+                };
+                throw error;
+            }
+            // Validate required parameters
+            if (!params.code) {
+                throw {
+                    error: "invalid_request",
+                    errorDescription: "Missing authorization code",
+                };
+            }
+            if (!params.state) {
+                throw {
+                    error: "invalid_request",
+                    errorDescription: "Missing state parameter",
+                };
+            }
+            // Retrieve and validate PKCE state
+            const pkceState = this.getPkceState();
+            if (!pkceState) {
+                throw {
+                    error: "invalid_request",
+                    errorDescription: "No PKCE state found",
+                };
+            }
+            // Validate state matches
+            if (pkceState.state !== params.state) {
+                throw {
+                    error: "invalid_request",
+                    errorDescription: "State mismatch - possible CSRF attack",
+                };
+            }
+            // Check if PKCE state is expired (10 minutes)
+            if (Date.now() - pkceState.createdAt > 10 * 60 * 1000) {
+                this.clearPkceState();
+                throw {
+                    error: "invalid_request",
+                    errorDescription: "Authorization request expired",
+                };
+            }
+            // Exchange code for tokens
+            try {
+                const tokens = yield this.exchangeCode(params.code, pkceState.codeVerifier, params.redirectUri);
+                // Clear PKCE state after successful exchange
+                this.clearPkceState();
+                // Store tokens
+                yield this.tokenManager.setTokens(tokens);
+                return tokens;
+            }
+            catch (error) {
+                this.clearPkceState();
+                throw error;
+            }
+        });
+    }
+    /**
+     * Manually refresh the access token
+     */
+    refreshToken() {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.tokenManager.refreshToken();
+        });
+    }
+    /**
+     * Logout - revoke tokens and clear storage
+     */
+    logout() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const state = this.tokenManager.getState();
+            const tokens = state.tokens;
+            // Try to revoke tokens on the server
+            if (tokens === null || tokens === void 0 ? void 0 : tokens.accessToken) {
+                try {
+                    yield this.revokeToken(tokens.accessToken, "access_token");
+                }
+                catch (_a) {
+                    // Ignore revocation errors - we're logging out anyway
+                }
+            }
+            // Clear local tokens
+            yield this.tokenManager.clearTokens();
+        });
+    }
+    /**
+     * Get current access token if valid
+     */
+    getAccessToken() {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.tokenManager.getAccessToken();
+        });
+    }
+    /**
+     * Get current authentication state
+     */
+    getAuthState() {
+        return this.tokenManager.getState();
+    }
+    /**
+     * Subscribe to authentication state changes
+     */
+    subscribe(listener) {
+        return this.tokenManager.subscribe(listener);
+    }
+    /**
+     * Check if user is authenticated
+     */
+    isAuthenticated() {
+        return this.tokenManager.getState().isAuthenticated;
+    }
+    /**
+     * Clean up resources
+     */
+    destroy() {
+        this.tokenManager.destroy();
+    }
+    // Private methods
+    exchangeCode(code, codeVerifier, redirectUri) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            const body = new URLSearchParams({
+                grant_type: "authorization_code",
+                code,
+                redirect_uri: redirectUri !== null && redirectUri !== void 0 ? redirectUri : this.config.redirectUri,
+                client_id: this.config.clientId,
+                code_verifier: codeVerifier,
+            });
+            const response = yield fetch(this.config.tokenEndpoint, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/x-www-form-urlencoded",
+                },
+                body: body.toString(),
+            });
+            if (!response.ok) {
+                const error = yield response.json().catch(() => ({}));
+                throw {
+                    error: (_a = error.error) !== null && _a !== void 0 ? _a : "token_error",
+                    errorDescription: (_b = error.error_description) !== null && _b !== void 0 ? _b : "Failed to exchange authorization code",
+                };
+            }
+            const data = yield response.json();
+            return this.parseTokenResponse(data);
+        });
+    }
+    refreshTokenWithApi(refreshToken) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const body = new URLSearchParams({
+                grant_type: "refresh_token",
+                refresh_token: refreshToken,
+                client_id: this.config.clientId,
+            });
+            const response = yield fetch(this.config.tokenEndpoint, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/x-www-form-urlencoded",
+                },
+                body: body.toString(),
+            });
+            if (!response.ok) {
+                const error = yield response.json().catch(() => ({}));
+                throw new Error((_a = error.error) !== null && _a !== void 0 ? _a : "refresh_failed");
+            }
+            const data = yield response.json();
+            return this.parseTokenResponse(data);
+        });
+    }
+    revokeToken(token, tokenTypeHint) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.config.revocationEndpoint) {
+                return;
+            }
+            const body = new URLSearchParams({
+                token,
+                client_id: this.config.clientId,
+            });
+            if (tokenTypeHint) {
+                body.set("token_type_hint", tokenTypeHint);
+            }
+            yield fetch(this.config.revocationEndpoint, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/x-www-form-urlencoded",
+                },
+                body: body.toString(),
+            });
+            // RFC 7009: revocation endpoint returns 200 even on error
+            // We don't need to check the response
+        });
+    }
+    parseTokenResponse(data) {
+        var _a, _b;
+        const accessToken = data.access_token;
+        const expiresIn = (_a = data.expires_in) !== null && _a !== void 0 ? _a : 3600;
+        const refreshToken = data.refresh_token;
+        const scope = data.scope;
+        const tokenType = (_b = data.token_type) !== null && _b !== void 0 ? _b : "Bearer";
+        if (!accessToken) {
+            throw {
+                error: "invalid_response",
+                errorDescription: "Missing access_token in response",
+            };
+        }
+        return {
+            accessToken,
+            refreshToken,
+            expiresAt: Date.now() + expiresIn * 1000,
+            scope: scope === null || scope === void 0 ? void 0 : scope.split(" "),
+            tokenType,
+        };
+    }
+    storePkceState(state) {
+        if (typeof window !== "undefined" && window.sessionStorage) {
+            sessionStorage.setItem(PKCE_STATE_KEY, JSON.stringify(state));
+        }
+    }
+    getPkceState() {
+        if (typeof window === "undefined" || !window.sessionStorage) {
+            return null;
+        }
+        try {
+            const stored = sessionStorage.getItem(PKCE_STATE_KEY);
+            return stored ? JSON.parse(stored) : null;
+        }
+        catch (_a) {
+            return null;
+        }
+    }
+    clearPkceState() {
+        if (typeof window !== "undefined" && window.sessionStorage) {
+            sessionStorage.removeItem(PKCE_STATE_KEY);
+        }
+    }
+}
+exports.OAuthAdapter = OAuthAdapter;
+/**
+ * Create an OAuth adapter with default configuration for Crimson API
+ */
+function createCrimsonOAuthAdapter(config) {
+    return new OAuthAdapter(Object.assign(Object.assign({}, config), { authorizationEndpoint: `${config.apiUrl}/oauth/authorize`, tokenEndpoint: `${config.apiUrl}/oauth/token`, revocationEndpoint: `${config.apiUrl}/oauth/revoke` }));
+}

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

@@ -0,0 +1,20 @@
+/**
+ * PKCE (Proof Key for Code Exchange) Utilities
+ * Client-side implementation for OAuth 2.0 with PKCE
+ */
+/**
+ * Generate a code verifier for PKCE
+ * @returns A 64-character random string
+ */
+export declare function generateCodeVerifier(): string;
+/**
+ * Generate a state parameter for CSRF protection
+ * @returns A 32-character random string
+ */
+export declare function generateState(): string;
+/**
+ * Generate a code challenge from a code verifier using SHA256 (S256 method)
+ * @param codeVerifier The code verifier
+ * @returns Base64URL-encoded SHA256 hash
+ */
+export declare function generateCodeChallenge(codeVerifier: string): Promise<string>;

package/dist/core/auth/pkce.js

@@ -0,0 +1,112 @@
+"use strict";
+/**
+ * PKCE (Proof Key for Code Exchange) Utilities
+ * Client-side implementation for OAuth 2.0 with PKCE
+ */
+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.generateCodeVerifier = generateCodeVerifier;
+exports.generateState = generateState;
+exports.generateCodeChallenge = generateCodeChallenge;
+/**
+ * Generate a cryptographically secure random string
+ */
+function generateRandomString(length) {
+    const charset = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~";
+    const randomValues = new Uint8Array(length);
+    if (typeof window !== "undefined" && window.crypto) {
+        window.crypto.getRandomValues(randomValues);
+    }
+    else if (typeof globalThis !== "undefined" && globalThis.crypto) {
+        globalThis.crypto.getRandomValues(randomValues);
+    }
+    else {
+        // Fallback for Node.js environments
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const nodeCrypto = require("crypto");
+        const buffer = nodeCrypto.randomBytes(length);
+        for (let i = 0; i < length; i++) {
+            randomValues[i] = buffer[i];
+        }
+    }
+    let result = "";
+    for (let i = 0; i < length; i++) {
+        result += charset[randomValues[i] % charset.length];
+    }
+    return result;
+}
+/**
+ * Generate a code verifier for PKCE
+ * @returns A 64-character random string
+ */
+function generateCodeVerifier() {
+    return generateRandomString(64);
+}
+/**
+ * Generate a state parameter for CSRF protection
+ * @returns A 32-character random string
+ */
+function generateState() {
+    return generateRandomString(32);
+}
+/**
+ * Generate a code challenge from a code verifier using SHA256 (S256 method)
+ * @param codeVerifier The code verifier
+ * @returns Base64URL-encoded SHA256 hash
+ */
+function generateCodeChallenge(codeVerifier) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        // Convert string to Uint8Array
+        const encoder = new TextEncoder();
+        const data = encoder.encode(codeVerifier);
+        // Hash with SHA-256
+        let hashBuffer;
+        if (typeof window !== "undefined" && ((_a = window.crypto) === null || _a === void 0 ? void 0 : _a.subtle)) {
+            hashBuffer = yield window.crypto.subtle.digest("SHA-256", data);
+        }
+        else if (typeof globalThis !== "undefined" && ((_b = globalThis.crypto) === null || _b === void 0 ? void 0 : _b.subtle)) {
+            hashBuffer = yield globalThis.crypto.subtle.digest("SHA-256", data);
+        }
+        else {
+            // Fallback for Node.js environments
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const nodeCrypto = require("crypto");
+            const hash = nodeCrypto.createHash("sha256").update(codeVerifier).digest();
+            hashBuffer = hash.buffer.slice(hash.byteOffset, hash.byteOffset + hash.byteLength);
+        }
+        // Convert to base64url encoding
+        return base64UrlEncode(new Uint8Array(hashBuffer));
+    });
+}
+/**
+ * Base64URL encode a buffer
+ * @param buffer The buffer to encode
+ * @returns Base64URL-encoded string (no padding)
+ */
+function base64UrlEncode(buffer) {
+    // Convert to base64
+    let base64 = "";
+    const bytes = new Uint8Array(buffer);
+    for (let i = 0; i < bytes.byteLength; i++) {
+        base64 += String.fromCharCode(bytes[i]);
+    }
+    // Use btoa if available (browser), otherwise Buffer (Node.js)
+    let encoded;
+    if (typeof btoa !== "undefined") {
+        encoded = btoa(base64);
+    }
+    else {
+        encoded = Buffer.from(base64, "binary").toString("base64");
+    }
+    // Convert to base64url (no padding)
+    return encoded.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}

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

@@ -0,0 +1,68 @@
+/**
+ * Token Manager
+ * Handles token lifecycle, automatic refresh, and state management
+ */
+import { OAuthTokens, TokenStorage, OAuthAuthState, OAuthAuthStateListener, TokenRefreshFunction } from "./types";
+export interface TokenManagerConfig {
+    /** Token storage implementation */
+    storage: TokenStorage;
+    /** Function to call when tokens need refreshing */
+    onRefreshNeeded: TokenRefreshFunction;
+    /** Buffer time before expiration to trigger refresh (default: 5 minutes) */
+    refreshBufferMs?: number;
+    /** Enable automatic background refresh (default: true) */
+    autoRefresh?: boolean;
+}
+export declare class TokenManager {
+    private storage;
+    private onRefreshNeeded;
+    private refreshBufferMs;
+    private autoRefresh;
+    private listeners;
+    private refreshPromise;
+    private refreshTimer;
+    private lastRefreshAttempt;
+    private currentState;
+    constructor(config: TokenManagerConfig);
+    /**
+     * Initialize the token manager
+     * Loads tokens from storage and sets up auto-refresh if enabled
+     */
+    initialize(): Promise<void>;
+    /**
+     * Get current authentication state
+     */
+    getState(): OAuthAuthState;
+    /**
+     * Get current access token if valid
+     * Automatically refreshes if needed and possible
+     */
+    getAccessToken(): Promise<string | null>;
+    /**
+     * Set new tokens (after successful authorization)
+     */
+    setTokens(tokens: OAuthTokens): Promise<void>;
+    /**
+     * Refresh the access token
+     * Uses a lock to prevent concurrent refresh attempts
+     */
+    refreshToken(): Promise<OAuthTokens | null>;
+    private doRefresh;
+    /**
+     * Clear tokens (logout)
+     */
+    clearTokens(): Promise<void>;
+    /**
+     * Subscribe to auth state changes
+     */
+    subscribe(listener: OAuthAuthStateListener): () => void;
+    /**
+     * Clean up resources
+     */
+    destroy(): void;
+    private updateState;
+    private isTokenExpired;
+    private shouldRefresh;
+    private scheduleRefresh;
+    private cancelScheduledRefresh;
+}