frameio 3.2.3 → 4.1.1

package/dist/cjs/oauth/http.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Internal HTTP helper for Adobe IMS token endpoint calls.
+ *
+ * Supports configurable timeouts, retries with exponential backoff,
+ * rate-limit handling (429), and response validation.
+ *
+ * Allows configurable IMS base URL for staging/alternative environments,
+ * and optional fetch injection for proxy, TLS, and custom HTTP handling.
+ */
+import type { Logger } from "./logger";
+import type { TokenResponse } from "./TokenManager";
+export declare const DEFAULT_IMS_BASE_URL = "https://ims-na1.adobelogin.com";
+/**
+ * Build authorize, token, and revoke URLs from an IMS base URL.
+ *
+ * @throws {Error} if the base URL does not use HTTPS.
+ */
+export declare function buildImsUrls(imsBaseUrl: string): {
+    authorizeUrl: string;
+    tokenUrl: string;
+    revokeUrl: string;
+};
+export declare const AUTHORIZE_URL: string;
+export declare const TOKEN_URL: string;
+export declare const REVOKE_URL: string;
+export declare const DEFAULT_SCOPES = "openid email profile offline_access additional_info.roles";
+export declare const S2S_SCOPES = "openid AdobeID frame.s2s.all";
+export declare const DEFAULT_TIMEOUT = 30000;
+export declare const DEFAULT_MAX_RETRIES = 2;
+/** Options for token requests. */
+export interface TokenRequestOptions {
+    timeout?: number;
+    maxRetries?: number;
+    logger?: Logger;
+    /** Token endpoint URL (for alternative IMS environments). */
+    tokenUrl?: string;
+    /** Custom fetch implementation (for proxy, TLS, etc.). */
+    fetch?: typeof fetch;
+}
+/**
+ * Send a POST to the Adobe IMS token endpoint.
+ *
+ * Rate-limit retries (429) are tracked separately from error retries
+ * (5xx / network failures), so a 429 does not consume the error retry
+ * budget and vice versa.
+ *
+ * @param data - Form-encoded body parameters.
+ * @param options - Timeout, retry, and logger options.
+ * @returns Parsed token response.
+ */
+export declare function tokenRequest(data: Record<string, string>, options?: TokenRequestOptions): Promise<TokenResponse>;
+/** Options for revoke requests. */
+export interface RevokeRequestOptions {
+    timeout?: number;
+    logger?: Logger;
+    /** Revoke endpoint URL (for alternative IMS environments). */
+    revokeUrl?: string;
+    /** Custom fetch implementation (for proxy, TLS, etc.). */
+    fetch?: typeof fetch;
+}
+/**
+ * Revoke an access or refresh token.
+ *
+ * For confidential clients (with client_secret), credentials are sent via
+ * HTTP Basic Auth per RFC 7009. For public clients, the client_id is sent
+ * as a query parameter.
+ *
+ * This is best-effort — errors are logged but not thrown.
+ */
+export declare function revokeRequest(token: string, clientId: string, clientSecret?: string, options?: RevokeRequestOptions): Promise<void>;

package/dist/cjs/oauth/http.js

@@ -0,0 +1,280 @@
+"use strict";
+/**
+ * Internal HTTP helper for Adobe IMS token endpoint calls.
+ *
+ * Supports configurable timeouts, retries with exponential backoff,
+ * rate-limit handling (429), and response validation.
+ *
+ * Allows configurable IMS base URL for staging/alternative environments,
+ * and optional fetch injection for proxy, TLS, and custom HTTP handling.
+ */
+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.DEFAULT_MAX_RETRIES = exports.DEFAULT_TIMEOUT = exports.S2S_SCOPES = exports.DEFAULT_SCOPES = exports.REVOKE_URL = exports.TOKEN_URL = exports.AUTHORIZE_URL = exports.DEFAULT_IMS_BASE_URL = void 0;
+exports.buildImsUrls = buildImsUrls;
+exports.tokenRequest = tokenRequest;
+exports.revokeRequest = revokeRequest;
+const errors_1 = require("./errors");
+const logger_1 = require("./logger");
+// Default Adobe IMS base URL (production). Override via imsBaseUrl for staging.
+exports.DEFAULT_IMS_BASE_URL = "https://ims-na1.adobelogin.com";
+/**
+ * Build authorize, token, and revoke URLs from an IMS base URL.
+ *
+ * @throws {Error} if the base URL does not use HTTPS.
+ */
+function buildImsUrls(imsBaseUrl) {
+    if (!imsBaseUrl.toLowerCase().startsWith("https://")) {
+        throw new errors_1.ConfigurationError(`imsBaseUrl must use HTTPS, got: ${imsBaseUrl}`);
+    }
+    const base = imsBaseUrl.replace(/\/$/, "");
+    return {
+        authorizeUrl: `${base}/ims/authorize/v2`,
+        tokenUrl: `${base}/ims/token/v3`,
+        revokeUrl: `${base}/ims/revoke`,
+    };
+}
+const DEFAULT_URLS = buildImsUrls(exports.DEFAULT_IMS_BASE_URL);
+exports.AUTHORIZE_URL = DEFAULT_URLS.authorizeUrl;
+exports.TOKEN_URL = DEFAULT_URLS.tokenUrl;
+exports.REVOKE_URL = DEFAULT_URLS.revokeUrl;
+// OAuth 2.0 RFC 6749 specifies space-separated scopes
+exports.DEFAULT_SCOPES = "openid email profile offline_access additional_info.roles";
+exports.S2S_SCOPES = "openid AdobeID frame.s2s.all";
+// Defaults
+exports.DEFAULT_TIMEOUT = 30000; // milliseconds
+exports.DEFAULT_MAX_RETRIES = 2;
+const RETRY_BACKOFF_SCHEDULE = [1000, 2000, 5000, 10000]; // ms
+const MAX_RETRY_AFTER_MS = 60000; // cap Retry-After to 60 s, matching Python
+const RETRYABLE_STATUS_CODES = new Set([500, 502, 503, 504]);
+/**
+ * Parse a Retry-After header value (seconds or HTTP-date).
+ * Returns milliseconds to wait, or undefined.
+ */
+function parseRetryAfter(header) {
+    if (!header)
+        return undefined;
+    const seconds = Number(header);
+    if (!isNaN(seconds))
+        return seconds * 1000;
+    const date = new Date(header);
+    if (isNaN(date.getTime()))
+        return undefined;
+    return Math.max(date.getTime() - Date.now(), 0);
+}
+/**
+ * Validate that a token response has the required fields.
+ */
+function validateTokenResponse(data, log) {
+    if (typeof data !== "object" || data === null) {
+        throw new errors_1.AuthenticationError("invalid_response", "Token endpoint returned non-object response.");
+    }
+    const obj = data;
+    if (!("access_token" in obj) || typeof obj.access_token !== "string" || !obj.access_token) {
+        throw new errors_1.AuthenticationError("invalid_response", "Token response missing or empty 'access_token'.");
+    }
+    const tokenType = obj.token_type;
+    if (tokenType == null) {
+        log.debug("Token response missing 'token_type' field.");
+    }
+    else if (typeof tokenType === "string" && tokenType.toLowerCase() !== "bearer") {
+        log.warn(`Unexpected token_type: ${tokenType} (expected 'bearer').`);
+    }
+    if (obj.expires_in !== undefined && obj.expires_in !== null) {
+        if (typeof obj.expires_in !== "number" || obj.expires_in <= 0) {
+            log.warn(`Invalid expires_in value (${obj.expires_in}), using default.`);
+            delete obj.expires_in;
+        }
+    }
+    return obj;
+}
+/** Sleep for a given number of milliseconds. */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Send a POST to the Adobe IMS token endpoint.
+ *
+ * Rate-limit retries (429) are tracked separately from error retries
+ * (5xx / network failures), so a 429 does not consume the error retry
+ * budget and vice versa.
+ *
+ * @param data - Form-encoded body parameters.
+ * @param options - Timeout, retry, and logger options.
+ * @returns Parsed token response.
+ */
+function tokenRequest(data_1) {
+    return __awaiter(this, arguments, void 0, function* (data, options = {}) {
+        var _a, _b, _c, _d, _e, _f;
+        const timeout = (_a = options.timeout) !== null && _a !== void 0 ? _a : exports.DEFAULT_TIMEOUT;
+        const maxRetries = (_b = options.maxRetries) !== null && _b !== void 0 ? _b : exports.DEFAULT_MAX_RETRIES;
+        const log = (_c = options.logger) !== null && _c !== void 0 ? _c : logger_1.noopLogger;
+        const tokenUrl = (_d = options.tokenUrl) !== null && _d !== void 0 ? _d : exports.TOKEN_URL;
+        const fetchFn = (_e = options.fetch) !== null && _e !== void 0 ? _e : (typeof globalThis.fetch !== "undefined" ? globalThis.fetch.bind(globalThis) : undefined);
+        if (fetchFn === undefined) {
+            throw new errors_1.NetworkError("no fetch implementation available; please provide options.fetch or polyfill global fetch");
+        }
+        const body = new URLSearchParams(data).toString();
+        const maxErrorAttempts = maxRetries + 1;
+        const maxRateLimitAttempts = maxRetries + 1;
+        const maxTotal = maxErrorAttempts + maxRateLimitAttempts;
+        let errorAttempts = 0;
+        let rateLimitAttempts = 0;
+        for (let i = 0; i < maxTotal; i++) {
+            let response;
+            try {
+                log.debug(`Token request (errors=${errorAttempts}/${maxErrorAttempts}, rate_limits=${rateLimitAttempts}/${maxRateLimitAttempts})`);
+                const controller = new AbortController();
+                const timer = setTimeout(() => controller.abort(), timeout);
+                try {
+                    response = yield fetchFn(tokenUrl, {
+                        method: "POST",
+                        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+                        body,
+                        signal: controller.signal,
+                    });
+                }
+                finally {
+                    clearTimeout(timer);
+                }
+            }
+            catch (err) {
+                errorAttempts++;
+                log.warn(`Network error on attempt ${errorAttempts}: ${err}`);
+                if (errorAttempts < maxErrorAttempts) {
+                    const backoff = RETRY_BACKOFF_SCHEDULE[Math.min(errorAttempts - 1, RETRY_BACKOFF_SCHEDULE.length - 1)];
+                    log.debug(`Retrying in ${backoff}ms...`);
+                    yield sleep(backoff);
+                    continue;
+                }
+                if (err instanceof Error && (err.name === "AbortError" || err.name === "TimeoutError")) {
+                    throw new errors_1.NetworkError(`Token request timed out after ${timeout}ms (${maxErrorAttempts} attempts).`);
+                }
+                throw new errors_1.NetworkError(`Token request failed after ${maxErrorAttempts} attempts: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            // Rate limit handling — separate budget from error retries
+            if (response.status === 429) {
+                rateLimitAttempts++;
+                const retryAfterMs = parseRetryAfter(response.headers.get("retry-after"));
+                const retryAfterSec = retryAfterMs !== undefined ? retryAfterMs / 1000 : undefined;
+                log.warn(`Rate limited (429), attempt ${rateLimitAttempts}/${maxRateLimitAttempts}. Retry-After: ${retryAfterSec}s`);
+                if (rateLimitAttempts < maxRateLimitAttempts) {
+                    const waitMs = Math.min(retryAfterMs !== null && retryAfterMs !== void 0 ? retryAfterMs : RETRY_BACKOFF_SCHEDULE[Math.min(rateLimitAttempts - 1, RETRY_BACKOFF_SCHEDULE.length - 1)], MAX_RETRY_AFTER_MS);
+                    yield sleep(waitMs);
+                    continue;
+                }
+                throw new errors_1.RateLimitError(retryAfterSec);
+            }
+            // Retryable server errors
+            if (RETRYABLE_STATUS_CODES.has(response.status)) {
+                errorAttempts++;
+                log.warn(`Server error ${response.status}, attempt ${errorAttempts}/${maxErrorAttempts}`);
+                if (errorAttempts < maxErrorAttempts) {
+                    const backoff = RETRY_BACKOFF_SCHEDULE[Math.min(errorAttempts - 1, RETRY_BACKOFF_SCHEDULE.length - 1)];
+                    yield sleep(backoff);
+                    continue;
+                }
+                // Fall through to error handling below
+            }
+            if (!response.ok) {
+                let errorCode = `http_${response.status}`;
+                let errorDesc;
+                try {
+                    const errBody = (yield response.json());
+                    errorCode = (_f = errBody.error) !== null && _f !== void 0 ? _f : errorCode;
+                    errorDesc = errBody.error_description;
+                }
+                catch (_g) {
+                    // ignore parse errors
+                }
+                // Detect expired refresh token
+                if ((errorCode === "invalid_grant" || errorCode === "invalid_token") &&
+                    errorDesc &&
+                    errorDesc.toLowerCase().includes("expired")) {
+                    log.error(`Token expired: ${errorCode}`);
+                    throw new errors_1.TokenExpiredError(`${errorCode} — ${errorDesc}`);
+                }
+                log.error(`Authentication error: ${errorCode}`);
+                throw new errors_1.AuthenticationError(errorCode, errorDesc);
+            }
+            // Success
+            let responseBody;
+            try {
+                responseBody = yield response.json();
+            }
+            catch (_h) {
+                throw new errors_1.AuthenticationError("invalid_response", "Token endpoint returned non-JSON body");
+            }
+            const result = validateTokenResponse(responseBody, log);
+            log.info(`Token acquired (length=${result.access_token.length})`);
+            return result;
+        }
+        // Should not reach here, but just in case
+        throw new errors_1.NetworkError("Token request failed after all retries.");
+    });
+}
+/**
+ * Revoke an access or refresh token.
+ *
+ * For confidential clients (with client_secret), credentials are sent via
+ * HTTP Basic Auth per RFC 7009. For public clients, the client_id is sent
+ * as a query parameter.
+ *
+ * This is best-effort — errors are logged but not thrown.
+ */
+function revokeRequest(token_1, clientId_1, clientSecret_1) {
+    return __awaiter(this, arguments, void 0, function* (token, clientId, clientSecret, options = {}) {
+        var _a, _b, _c, _d;
+        const timeout = (_a = options.timeout) !== null && _a !== void 0 ? _a : exports.DEFAULT_TIMEOUT;
+        const log = (_b = options.logger) !== null && _b !== void 0 ? _b : logger_1.noopLogger;
+        const revokeUrl = (_c = options.revokeUrl) !== null && _c !== void 0 ? _c : exports.REVOKE_URL;
+        const fetchFn = (_d = options.fetch) !== null && _d !== void 0 ? _d : (typeof globalThis.fetch !== "undefined" ? globalThis.fetch.bind(globalThis) : undefined);
+        if (fetchFn === undefined) {
+            log.warn("Token revocation skipped: no fetch implementation available");
+            return;
+        }
+        const headers = {
+            "Content-Type": "application/x-www-form-urlencoded",
+        };
+        const data = { token };
+        let url = revokeUrl;
+        if (clientSecret) {
+            // Confidential client: use HTTP Basic Auth (RFC 7009 §2.1)
+            const credentials = btoa(`${clientId}:${clientSecret}`);
+            headers["Authorization"] = `Basic ${credentials}`;
+        }
+        else {
+            // Public client: send client_id as query parameter
+            url = `${revokeUrl}?${new URLSearchParams({ client_id: clientId }).toString()}`;
+        }
+        try {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), timeout);
+            try {
+                const response = yield fetchFn(url, {
+                    method: "POST",
+                    headers,
+                    body: new URLSearchParams(data).toString(),
+                    signal: controller.signal,
+                });
+                if (!response.ok) {
+                    log.warn(`Token revocation returned status ${response.status}`);
+                }
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        }
+        catch (err) {
+            log.warn(`Token revocation failed: ${err}`);
+        }
+    });
+}

package/dist/cjs/oauth/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * frameio OAuth 2.0 authentication for the Frame.io V4 SDK.
+ *
+ * Provides four authentication flows:
+ *
+ * - {@link ServerToServerAuth} — client_credentials grant (backend services)
+ * - {@link WebAppAuth} — authorization_code grant (server-side apps)
+ * - {@link SPAAuth} — authorization_code + PKCE (browser apps)
+ * - {@link NativeAppAuth} — authorization_code + PKCE (desktop / mobile)
+ *
+ * @example
+ * ```ts
+ * import { FrameioClient, ServerToServerAuth } from 'frameio';
+ *
+ * const auth = new ServerToServerAuth({ clientId: '...', clientSecret: '...' });
+ * const client = new FrameioClient({ token: () => auth.getToken() });
+ * ```
+ *
+ * @packageDocumentation
+ */
+export type { BaseAuthOptions } from "./BaseAuth";
+export { ServerToServerAuth } from "./ServerToServerAuth";
+export type { ServerToServerAuthOptions } from "./ServerToServerAuth";
+export { WebAppAuth } from "./WebAppAuth";
+export type { WebAppAuthOptions } from "./WebAppAuth";
+export { SPAAuth } from "./SPAAuth";
+export type { SPAAuthOptions, AuthorizationUrlResult } from "./SPAAuth";
+export { NativeAppAuth } from "./NativeAppAuth";
+export type { NativeAppAuthOptions } from "./NativeAppAuth";
+export { FrameioAuthError, AuthenticationError, TokenExpiredError, NetworkError, RateLimitError, PKCEError, ConfigurationError, } from "./errors";
+export type { Logger } from "./logger";
+export { noopLogger } from "./logger";
+export { DEFAULT_IMS_BASE_URL, buildImsUrls } from "./http";
+export type { TokenResponse, ExportedTokens, OnTokenRefreshed } from "./TokenManager";

package/dist/cjs/oauth/index.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * frameio OAuth 2.0 authentication for the Frame.io V4 SDK.
+ *
+ * Provides four authentication flows:
+ *
+ * - {@link ServerToServerAuth} — client_credentials grant (backend services)
+ * - {@link WebAppAuth} — authorization_code grant (server-side apps)
+ * - {@link SPAAuth} — authorization_code + PKCE (browser apps)
+ * - {@link NativeAppAuth} — authorization_code + PKCE (desktop / mobile)
+ *
+ * @example
+ * ```ts
+ * import { FrameioClient, ServerToServerAuth } from 'frameio';
+ *
+ * const auth = new ServerToServerAuth({ clientId: '...', clientSecret: '...' });
+ * const client = new FrameioClient({ token: () => auth.getToken() });
+ * ```
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildImsUrls = exports.DEFAULT_IMS_BASE_URL = exports.noopLogger = exports.ConfigurationError = exports.PKCEError = exports.RateLimitError = exports.NetworkError = exports.TokenExpiredError = exports.AuthenticationError = exports.FrameioAuthError = exports.NativeAppAuth = exports.SPAAuth = exports.WebAppAuth = exports.ServerToServerAuth = void 0;
+// Auth flows
+var ServerToServerAuth_1 = require("./ServerToServerAuth");
+Object.defineProperty(exports, "ServerToServerAuth", { enumerable: true, get: function () { return ServerToServerAuth_1.ServerToServerAuth; } });
+var WebAppAuth_1 = require("./WebAppAuth");
+Object.defineProperty(exports, "WebAppAuth", { enumerable: true, get: function () { return WebAppAuth_1.WebAppAuth; } });
+var SPAAuth_1 = require("./SPAAuth");
+Object.defineProperty(exports, "SPAAuth", { enumerable: true, get: function () { return SPAAuth_1.SPAAuth; } });
+var NativeAppAuth_1 = require("./NativeAppAuth");
+Object.defineProperty(exports, "NativeAppAuth", { enumerable: true, get: function () { return NativeAppAuth_1.NativeAppAuth; } });
+// Errors
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "FrameioAuthError", { enumerable: true, get: function () { return errors_1.FrameioAuthError; } });
+Object.defineProperty(exports, "AuthenticationError", { enumerable: true, get: function () { return errors_1.AuthenticationError; } });
+Object.defineProperty(exports, "TokenExpiredError", { enumerable: true, get: function () { return errors_1.TokenExpiredError; } });
+Object.defineProperty(exports, "NetworkError", { enumerable: true, get: function () { return errors_1.NetworkError; } });
+Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return errors_1.RateLimitError; } });
+Object.defineProperty(exports, "PKCEError", { enumerable: true, get: function () { return errors_1.PKCEError; } });
+Object.defineProperty(exports, "ConfigurationError", { enumerable: true, get: function () { return errors_1.ConfigurationError; } });
+var logger_1 = require("./logger");
+Object.defineProperty(exports, "noopLogger", { enumerable: true, get: function () { return logger_1.noopLogger; } });
+// Config
+var http_1 = require("./http");
+Object.defineProperty(exports, "DEFAULT_IMS_BASE_URL", { enumerable: true, get: function () { return http_1.DEFAULT_IMS_BASE_URL; } });
+Object.defineProperty(exports, "buildImsUrls", { enumerable: true, get: function () { return http_1.buildImsUrls; } });

package/dist/cjs/oauth/logger.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Pluggable logger interface for frameio-auth-sdk.
+ *
+ * Consumers can supply any object matching this interface (e.g. `console`,
+ * `winston`, `pino`) via the `logger` option on auth class constructors.
+ *
+ * The default is a no-op logger (silent).
+ */
+/** Logger interface accepted by all frameio-auth-sdk classes. */
+export interface Logger {
+    debug(msg: string): void;
+    info(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string): void;
+}
+/** Silent no-op logger — the default when no logger is provided. */
+export declare const noopLogger: Logger;

package/dist/cjs/oauth/logger.js

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * Pluggable logger interface for frameio-auth-sdk.
+ *
+ * Consumers can supply any object matching this interface (e.g. `console`,
+ * `winston`, `pino`) via the `logger` option on auth class constructors.
+ *
+ * The default is a no-op logger (silent).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.noopLogger = void 0;
+/** Silent no-op logger — the default when no logger is provided. */
+exports.noopLogger = {
+    debug() { },
+    info() { },
+    warn() { },
+    error() { },
+};

package/dist/cjs/oauth/pkce.d.ts

@@ -0,0 +1,30 @@
+/**
+ * PKCE (Proof Key for Code Exchange) utilities.
+ *
+ * Implements code_verifier generation and S256 code_challenge derivation
+ * per RFC 7636.
+ *
+ * Uses the Web Crypto API (`globalThis.crypto`) so it works in both
+ * Node.js (>=18) and browsers.
+ */
+/**
+ * Generate a cryptographically random code verifier.
+ *
+ * Uses `globalThis.crypto.getRandomValues` which is available in
+ * browsers and Node.js >= 18.
+ *
+ * @param length - Length of the verifier (43–128 inclusive). Defaults to 128.
+ * @returns A random string of unreserved URI characters.
+ */
+export declare function generateCodeVerifier(length?: number): string;
+/**
+ * Derive the S256 code challenge from a code verifier.
+ *
+ * `code_challenge = BASE64URL(SHA256(code_verifier))`
+ *
+ * Uses `crypto.subtle.digest` which is available in browsers and Node.js >= 18.
+ *
+ * @param verifier - The code verifier string.
+ * @returns Base64url-encoded (no padding) SHA-256 hash.
+ */
+export declare function generateCodeChallenge(verifier: string): Promise<string>;

package/dist/cjs/oauth/pkce.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * PKCE (Proof Key for Code Exchange) utilities.
+ *
+ * Implements code_verifier generation and S256 code_challenge derivation
+ * per RFC 7636.
+ *
+ * Uses the Web Crypto API (`globalThis.crypto`) so it works in both
+ * Node.js (>=18) and browsers.
+ */
+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.generateCodeChallenge = generateCodeChallenge;
+/** Unreserved URI characters allowed in a code verifier (RFC 7636 §4.1). */
+const VERIFIER_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~";
+const MIN_VERIFIER_LENGTH = 43;
+const MAX_VERIFIER_LENGTH = 128;
+const DEFAULT_VERIFIER_LENGTH = 128;
+/**
+ * Generate a cryptographically random code verifier.
+ *
+ * Uses `globalThis.crypto.getRandomValues` which is available in
+ * browsers and Node.js >= 18.
+ *
+ * @param length - Length of the verifier (43–128 inclusive). Defaults to 128.
+ * @returns A random string of unreserved URI characters.
+ */
+function generateCodeVerifier(length = DEFAULT_VERIFIER_LENGTH) {
+    if (length < MIN_VERIFIER_LENGTH || length > MAX_VERIFIER_LENGTH) {
+        throw new RangeError(`code_verifier length must be between ${MIN_VERIFIER_LENGTH} and ${MAX_VERIFIER_LENGTH}, got ${length}`);
+    }
+    // Rejection sampling: discard random bytes that would introduce modulo bias.
+    // Only accept values below the largest multiple of the charset length that
+    // fits in a byte (256), so every character has equal probability.
+    const charsetLen = VERIFIER_CHARS.length; // 66
+    const limit = 256 - (256 % charsetLen); // 252
+    const chars = new Array(length);
+    // Batch random bytes; refill when exhausted. Oversize slightly to absorb the
+    // ~1.6% rejection rate without a second refill in the common case.
+    let buf = new Uint8Array(Math.ceil(length * 1.1));
+    globalThis.crypto.getRandomValues(buf);
+    let bufPos = 0;
+    for (let i = 0; i < length;) {
+        if (bufPos >= buf.length) {
+            buf = new Uint8Array(length);
+            globalThis.crypto.getRandomValues(buf);
+            bufPos = 0;
+        }
+        const b = buf[bufPos++];
+        if (b < limit) {
+            chars[i] = VERIFIER_CHARS[b % charsetLen];
+            i++;
+        }
+        // else: discard and advance to next byte
+    }
+    return chars.join("");
+}
+/**
+ * Derive the S256 code challenge from a code verifier.
+ *
+ * `code_challenge = BASE64URL(SHA256(code_verifier))`
+ *
+ * Uses `crypto.subtle.digest` which is available in browsers and Node.js >= 18.
+ *
+ * @param verifier - The code verifier string.
+ * @returns Base64url-encoded (no padding) SHA-256 hash.
+ */
+function generateCodeChallenge(verifier) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const data = new TextEncoder().encode(verifier);
+        const hashBuffer = yield globalThis.crypto.subtle.digest("SHA-256", data);
+        const hashArray = new Uint8Array(hashBuffer);
+        // Base64url encode (no padding)
+        let base64 = "";
+        const len = hashArray.length;
+        for (let i = 0; i < len; i += 3) {
+            const a = hashArray[i];
+            const b = i + 1 < len ? hashArray[i + 1] : 0;
+            const c = i + 2 < len ? hashArray[i + 2] : 0;
+            base64 += toBase64Url((a >> 2) & 0x3f);
+            base64 += toBase64Url(((a & 0x03) << 4) | ((b >> 4) & 0x0f));
+            if (i + 1 < len)
+                base64 += toBase64Url(((b & 0x0f) << 2) | ((c >> 6) & 0x03));
+            if (i + 2 < len)
+                base64 += toBase64Url(c & 0x3f);
+        }
+        return base64;
+    });
+}
+const BASE64URL_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+function toBase64Url(index) {
+    return BASE64URL_CHARS[index];
+}

package/dist/cjs/oauth/validation.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Input validation helpers for frameio-auth-sdk.
+ */
+import type { ExportedTokens } from "./TokenManager";
+/**
+ * Validate that a redirect URI uses HTTPS, except for loopback addresses
+ * where HTTP is allowed for local development.
+ *
+ * @throws {ConfigurationError} if the URI uses http:// with a non-loopback host.
+ */
+export declare function validateRedirectUriScheme(uri: string): void;
+/**
+ * Validate the structure of an exported token object before importing.
+ *
+ * @throws {ConfigurationError} if any field has an unexpected type.
+ */
+export declare function validateTokenImport(data: unknown): asserts data is ExportedTokens;