frameio 3.2.2 → 4.1.1

package/dist/esm/oauth/ServerToServerAuth.d.mts

@@ -0,0 +1,17 @@
+/**
+ * Server-to-Server authentication (client_credentials grant).
+ *
+ * Use for backend services and scripts with no user interaction.
+ */
+import { BaseAuth, type BaseAuthOptions } from "./BaseAuth";
+import type { TokenResponse } from "./TokenManager";
+export interface ServerToServerAuthOptions extends BaseAuthOptions {
+    clientSecret: string;
+}
+export declare class ServerToServerAuth extends BaseAuth {
+    private readonly _scopes;
+    constructor(options: ServerToServerAuthOptions);
+    /** Explicitly fetch a new access token. */
+    authenticate(): Promise<TokenResponse>;
+    protected _refresh(): Promise<TokenResponse>;
+}

package/dist/esm/oauth/ServerToServerAuth.mjs

@@ -0,0 +1,45 @@
+/**
+ * Server-to-Server authentication (client_credentials grant).
+ *
+ * Use for backend services and scripts with no user interaction.
+ */
+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());
+    });
+};
+import { BaseAuth } from "./BaseAuth";
+import { ConfigurationError } from "./errors";
+import { S2S_SCOPES } from "./http";
+export class ServerToServerAuth extends BaseAuth {
+    constructor(options) {
+        var _a;
+        if (!options.clientSecret) {
+            throw new ConfigurationError("clientSecret is required");
+        }
+        super(options, options.clientSecret);
+        this._scopes = (_a = options.scopes) !== null && _a !== void 0 ? _a : S2S_SCOPES;
+    }
+    /** Explicitly fetch a new access token. */
+    authenticate() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const result = yield this._refresh();
+            this._storeTokens(result);
+            return result;
+        });
+    }
+    _refresh() {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this._tokenRequest({
+                grant_type: "client_credentials",
+                client_id: this._clientId,
+                client_secret: this._clientSecret,
+                scope: this._scopes,
+            });
+        });
+    }
+}

package/dist/esm/oauth/TokenManager.d.mts

@@ -0,0 +1,83 @@
+/**
+ * Token lifecycle manager — the core of frameio-auth-sdk.
+ *
+ * Stores access/refresh tokens, checks expiry with a configurable buffer,
+ * and coordinates async-safe automatic refresh.
+ */
+import type { Logger } from "./logger";
+/** Shape returned by refresh functions and token endpoints. */
+export interface TokenResponse {
+    access_token: string;
+    expires_in: number;
+    refresh_token?: string;
+    token_type?: string;
+    scope?: string;
+}
+/** Serialised token state for persistence. */
+export interface ExportedTokens {
+    access_token: string | null;
+    refresh_token: string | null;
+    expires_at: number;
+}
+/** A function that performs the actual token refresh / fetch. */
+export type RefreshFunction = () => Promise<TokenResponse>;
+/** Optional callback fired after every successful token refresh. */
+export type OnTokenRefreshed = (tokens: ExportedTokens) => void;
+export interface TokenManagerOptions {
+    refreshFunc: RefreshFunction;
+    /** Seconds before actual expiry to trigger proactive refresh. Default: 60. */
+    refreshBuffer?: number;
+    /** Called after every successful refresh. */
+    onTokenRefreshed?: OnTokenRefreshed;
+    /** Logger instance for diagnostic output. */
+    logger?: Logger;
+}
+/**
+ * Manages token storage, expiry detection, and auto-refresh.
+ *
+ * Pass `manager.getToken` (bound) to the Frame.io SDK:
+ * ```ts
+ * const client = new FrameioClient({ token: () => auth.getToken() });
+ * ```
+ */
+export declare class TokenManager {
+    private _refreshFunc;
+    private _refreshBuffer;
+    private _onTokenRefreshed?;
+    private _logger;
+    private _accessToken;
+    private _refreshToken;
+    private _expiresAt;
+    /** In-flight refresh promise for deduplication. */
+    private _refreshPromise;
+    /** Set by clear() to prevent an in-flight refresh from restoring tokens. */
+    private _revoked;
+    constructor(options: TokenManagerOptions);
+    /**
+     * Return a valid access token, refreshing if necessary.
+     *
+     * Safe to call concurrently — only one refresh request will fire.
+     */
+    getToken(): Promise<string>;
+    get accessToken(): string | null;
+    get refreshTokenValue(): string | null;
+    get expiresAt(): number;
+    get isExpired(): boolean;
+    /**
+     * Manually set token data (e.g. after initial code exchange).
+     */
+    setTokens(accessToken: string, expiresIn: number, refreshToken?: string): void;
+    /** Export current token state for persistence. */
+    exportTokens(): ExportedTokens;
+    /** Restore token state from a previously exported object. */
+    importTokens(data: ExportedTokens): void;
+    /** Clear all stored tokens and cancel any in-flight refresh. */
+    clear(): void;
+    private _isTokenValid;
+    /**
+     * Async-safe refresh: if a refresh is already in flight, await the
+     * existing promise instead of firing a second request.
+     */
+    private _doRefresh;
+    private _executeRefresh;
+}

package/dist/esm/oauth/TokenManager.mjs

@@ -0,0 +1,170 @@
+/**
+ * Token lifecycle manager — the core of frameio-auth-sdk.
+ *
+ * Stores access/refresh tokens, checks expiry with a configurable buffer,
+ * and coordinates async-safe automatic refresh.
+ */
+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());
+    });
+};
+import { AuthenticationError, NetworkError, RateLimitError, sanitizeMessage, TokenExpiredError } from "./errors";
+import { noopLogger } from "./logger";
+import { validateTokenImport } from "./validation";
+/**
+ * Manages token storage, expiry detection, and auto-refresh.
+ *
+ * Pass `manager.getToken` (bound) to the Frame.io SDK:
+ * ```ts
+ * const client = new FrameioClient({ token: () => auth.getToken() });
+ * ```
+ */
+export class TokenManager {
+    constructor(options) {
+        var _a, _b;
+        this._accessToken = null;
+        this._refreshToken = null;
+        this._expiresAt = 0;
+        /** In-flight refresh promise for deduplication. */
+        this._refreshPromise = null;
+        /** Set by clear() to prevent an in-flight refresh from restoring tokens. */
+        this._revoked = false;
+        this._refreshFunc = options.refreshFunc;
+        this._refreshBuffer = (_a = options.refreshBuffer) !== null && _a !== void 0 ? _a : 60;
+        this._onTokenRefreshed = options.onTokenRefreshed;
+        this._logger = (_b = options.logger) !== null && _b !== void 0 ? _b : noopLogger;
+    }
+    // ------------------------------------------------------------------
+    // Public API
+    // ------------------------------------------------------------------
+    /**
+     * Return a valid access token, refreshing if necessary.
+     *
+     * Safe to call concurrently — only one refresh request will fire.
+     */
+    getToken() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this._isTokenValid()) {
+                return this._accessToken;
+            }
+            return this._doRefresh();
+        });
+    }
+    get accessToken() {
+        return this._accessToken;
+    }
+    get refreshTokenValue() {
+        return this._refreshToken;
+    }
+    get expiresAt() {
+        return this._expiresAt;
+    }
+    get isExpired() {
+        return !this._isTokenValid();
+    }
+    /**
+     * Manually set token data (e.g. after initial code exchange).
+     */
+    setTokens(accessToken, expiresIn, refreshToken) {
+        this._revoked = false;
+        this._accessToken = accessToken;
+        this._expiresAt = Date.now() / 1000 + expiresIn;
+        if (refreshToken !== undefined) {
+            this._refreshToken = refreshToken;
+        }
+    }
+    /** Export current token state for persistence. */
+    exportTokens() {
+        return {
+            access_token: this._accessToken,
+            refresh_token: this._refreshToken,
+            expires_at: this._expiresAt,
+        };
+    }
+    /** Restore token state from a previously exported object. */
+    importTokens(data) {
+        var _a;
+        validateTokenImport(data);
+        this._revoked = false;
+        this._accessToken = data.access_token;
+        this._refreshToken = data.refresh_token;
+        this._expiresAt = (_a = data.expires_at) !== null && _a !== void 0 ? _a : 0;
+    }
+    /** Clear all stored tokens and cancel any in-flight refresh. */
+    clear() {
+        this._accessToken = null;
+        this._refreshToken = null;
+        this._expiresAt = 0;
+        this._refreshPromise = null;
+        this._revoked = true;
+    }
+    // ------------------------------------------------------------------
+    // Internals
+    // ------------------------------------------------------------------
+    _isTokenValid() {
+        return this._accessToken !== null && Date.now() / 1000 < this._expiresAt - this._refreshBuffer;
+    }
+    /**
+     * Async-safe refresh: if a refresh is already in flight, await the
+     * existing promise instead of firing a second request.
+     */
+    _doRefresh() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this._refreshPromise) {
+                return this._refreshPromise;
+            }
+            this._refreshPromise = this._executeRefresh();
+            try {
+                return yield this._refreshPromise;
+            }
+            finally {
+                this._refreshPromise = null;
+            }
+        });
+    }
+    _executeRefresh() {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            let result;
+            this._logger.debug("Token refresh triggered.");
+            try {
+                result = yield this._refreshFunc();
+            }
+            catch (err) {
+                if (err instanceof AuthenticationError ||
+                    err instanceof TokenExpiredError ||
+                    err instanceof NetworkError ||
+                    err instanceof RateLimitError) {
+                    throw err;
+                }
+                throw new AuthenticationError("refresh_failed", sanitizeMessage(`Token refresh failed: ${err instanceof Error ? err.message : String(err)}`));
+            }
+            // If clear() was called while the refresh was in flight (e.g. via
+            // revoke()), do not overwrite the cleared state with new tokens.
+            if (this._revoked) {
+                throw new AuthenticationError("revoked", "Tokens were revoked during refresh.");
+            }
+            const token = result.access_token;
+            this._accessToken = token;
+            this._expiresAt = Date.now() / 1000 + ((_a = result.expires_in) !== null && _a !== void 0 ? _a : 86400);
+            if (result.refresh_token) {
+                this._refreshToken = result.refresh_token;
+            }
+            this._logger.info(`Token refreshed (length=${token.length}).`);
+            if (this._onTokenRefreshed) {
+                try {
+                    this._onTokenRefreshed(this.exportTokens());
+                }
+                catch (err) {
+                    this._logger.warn(`onTokenRefreshed callback raised: ${err}`);
+                }
+            }
+            return token;
+        });
+    }
+}

package/dist/esm/oauth/WebAppAuth.d.mts

@@ -0,0 +1,29 @@
+/**
+ * Web App authentication (authorization_code grant).
+ *
+ * Use for server-side applications that can securely store a client secret.
+ */
+import { BaseAuth, type BaseAuthOptions } from "./BaseAuth";
+import type { TokenResponse } from "./TokenManager";
+export interface WebAppAuthOptions extends BaseAuthOptions {
+    clientSecret: string;
+    redirectUri: string;
+}
+export declare class WebAppAuth extends BaseAuth {
+    private readonly _redirectUri;
+    private readonly _scopes;
+    constructor(options: WebAppAuthOptions);
+    /**
+     * Build the Adobe IMS authorization URL.
+     *
+     * @param options.state - An opaque CSRF/state value.
+     */
+    getAuthorizationUrl(options: {
+        state: string;
+    }): string;
+    /** Exchange an authorization code for access and refresh tokens. */
+    exchangeCode(code: string): Promise<TokenResponse>;
+    /** Manually trigger a token refresh. */
+    refresh(): Promise<TokenResponse>;
+    protected _refresh(): Promise<TokenResponse>;
+}

package/dist/esm/oauth/WebAppAuth.mjs

@@ -0,0 +1,84 @@
+/**
+ * Web App authentication (authorization_code grant).
+ *
+ * Use for server-side applications that can securely store a client secret.
+ */
+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());
+    });
+};
+import { BaseAuth } from "./BaseAuth";
+import { ConfigurationError } from "./errors";
+import { DEFAULT_SCOPES } from "./http";
+import { validateRedirectUriScheme } from "./validation";
+export class WebAppAuth extends BaseAuth {
+    constructor(options) {
+        var _a;
+        if (!options.clientSecret) {
+            throw new ConfigurationError("clientSecret is required");
+        }
+        if (!options.redirectUri) {
+            throw new ConfigurationError("redirectUri is required");
+        }
+        validateRedirectUriScheme(options.redirectUri);
+        super(options, options.clientSecret);
+        this._redirectUri = options.redirectUri;
+        this._scopes = (_a = options.scopes) !== null && _a !== void 0 ? _a : DEFAULT_SCOPES;
+    }
+    /**
+     * Build the Adobe IMS authorization URL.
+     *
+     * @param options.state - An opaque CSRF/state value.
+     */
+    getAuthorizationUrl(options) {
+        const params = new URLSearchParams({
+            client_id: this._clientId,
+            redirect_uri: this._redirectUri,
+            scope: this._scopes,
+            response_type: "code",
+            state: options.state,
+        });
+        return `${this._authorizeUrl}?${params.toString()}`;
+    }
+    /** Exchange an authorization code for access and refresh tokens. */
+    exchangeCode(code) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const result = yield this._tokenRequest({
+                grant_type: "authorization_code",
+                client_id: this._clientId,
+                client_secret: this._clientSecret,
+                code,
+                redirect_uri: this._redirectUri,
+            });
+            this._storeTokens(result);
+            return result;
+        });
+    }
+    /** Manually trigger a token refresh. */
+    refresh() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const result = yield this._refresh();
+            this._storeTokens(result);
+            return result;
+        });
+    }
+    _refresh() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const refreshTok = this._tokenManager.refreshTokenValue;
+            if (!refreshTok) {
+                throw new ConfigurationError("No refresh token available. Call exchangeCode() first.");
+            }
+            return this._tokenRequest({
+                grant_type: "refresh_token",
+                client_id: this._clientId,
+                client_secret: this._clientSecret,
+                refresh_token: refreshTok,
+            });
+        });
+    }
+}

package/dist/esm/oauth/errors.d.mts

@@ -0,0 +1,41 @@
+/**
+ * Custom error types for frameio-auth-sdk.
+ */
+/**
+ * Strip JWT-like tokens from error messages to prevent token leakage.
+ *
+ * Redacts strings matching the JWT prefix pattern (eyJ followed by 10+
+ * base64url characters). This covers Adobe IMS access and refresh tokens.
+ */
+export declare function sanitizeMessage(msg: string): string;
+/** Base error for all frameio-auth-sdk errors. */
+export declare class FrameioAuthError extends Error {
+    constructor(message: string);
+}
+/** Raised when token exchange or refresh fails. */
+export declare class AuthenticationError extends FrameioAuthError {
+    readonly errorCode: string;
+    readonly errorDescription?: string;
+    constructor(errorCode: string, errorDescription?: string);
+}
+/** Raised when the refresh token is expired and re-authentication is required. */
+export declare class TokenExpiredError extends FrameioAuthError {
+    constructor(message?: string);
+}
+/** Raised when a network request fails (timeout, connection error, etc.). */
+export declare class NetworkError extends FrameioAuthError {
+    constructor(message?: string);
+}
+/** Raised when the API returns 429 Too Many Requests and retries are exhausted. */
+export declare class RateLimitError extends FrameioAuthError {
+    readonly retryAfter: number | undefined;
+    constructor(retryAfter?: number);
+}
+/** Raised when PKCE verification fails. */
+export declare class PKCEError extends FrameioAuthError {
+    constructor(message?: string);
+}
+/** Raised when required configuration is missing or invalid. */
+export declare class ConfigurationError extends FrameioAuthError {
+    constructor(message: string);
+}

package/dist/esm/oauth/errors.mjs

@@ -0,0 +1,72 @@
+/**
+ * Custom error types for frameio-auth-sdk.
+ */
+/** Pattern to detect JWT-like tokens (eyJ...) in error messages. */
+const JWT_PATTERN = /eyJ[A-Za-z0-9_-]{10,}/g;
+/**
+ * Strip JWT-like tokens from error messages to prevent token leakage.
+ *
+ * Redacts strings matching the JWT prefix pattern (eyJ followed by 10+
+ * base64url characters). This covers Adobe IMS access and refresh tokens.
+ */
+export function sanitizeMessage(msg) {
+    return msg.replace(JWT_PATTERN, "[REDACTED]");
+}
+/** Base error for all frameio-auth-sdk errors. */
+export class FrameioAuthError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "FrameioAuthError";
+    }
+}
+/** Raised when token exchange or refresh fails. */
+export class AuthenticationError extends FrameioAuthError {
+    constructor(errorCode, errorDescription) {
+        const desc = errorDescription ? sanitizeMessage(errorDescription) : undefined;
+        const msg = desc ? `${errorCode} — ${desc}` : errorCode;
+        super(msg);
+        this.name = "AuthenticationError";
+        this.errorCode = errorCode;
+        this.errorDescription = desc;
+    }
+}
+/** Raised when the refresh token is expired and re-authentication is required. */
+export class TokenExpiredError extends FrameioAuthError {
+    constructor(message = "Refresh token expired. Re-authentication required.") {
+        super(sanitizeMessage(message));
+        this.name = "TokenExpiredError";
+    }
+}
+/** Raised when a network request fails (timeout, connection error, etc.). */
+export class NetworkError extends FrameioAuthError {
+    constructor(message = "Network request failed.") {
+        super(message);
+        this.name = "NetworkError";
+    }
+}
+/** Raised when the API returns 429 Too Many Requests and retries are exhausted. */
+export class RateLimitError extends FrameioAuthError {
+    constructor(retryAfter) {
+        let msg = "Rate limited by Adobe IMS.";
+        if (retryAfter !== undefined) {
+            msg += ` Retry after ${Math.round(retryAfter)}s.`;
+        }
+        super(msg);
+        this.name = "RateLimitError";
+        this.retryAfter = retryAfter;
+    }
+}
+/** Raised when PKCE verification fails. */
+export class PKCEError extends FrameioAuthError {
+    constructor(message = "PKCE verification failed.") {
+        super(message);
+        this.name = "PKCEError";
+    }
+}
+/** Raised when required configuration is missing or invalid. */
+export class ConfigurationError extends FrameioAuthError {
+    constructor(message) {
+        super(message);
+        this.name = "ConfigurationError";
+    }
+}

package/dist/esm/oauth/http.d.mts

@@ -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>;