@friggframework/core 2.0.0-next.8 → 2.0.0-next.81

package/modules/requester/oauth-2.js

@@ -0,0 +1,396 @@
+const { Requester } = require('./requester');
+const { get } = require('../../assertions');
+const { ModuleConstants } = require('../ModuleConstants');
+
+/**
+ * OAuth 2.0 Requester - Base class for API modules using OAuth 2.0 authentication.
+ *
+ * Supports multiple OAuth 2.0 grant types:
+ * - `authorization_code` (default): Standard OAuth flow with user consent
+ * - `client_credentials`: Server-to-server authentication without user
+ * - `password`: Resource Owner Password Credentials grant
+ *
+ * @extends Requester
+ *
+ * @example
+ * // Authorization Code flow (default)
+ * const api = new MyApi({ grant_type: 'authorization_code' });
+ * const authUrl = api.getAuthorizationUri();
+ * // After user authorizes...
+ * await api.getTokenFromCode(code);
+ *
+ * @example
+ * // Client Credentials flow
+ * const api = new MyApi({
+ *     grant_type: 'client_credentials',
+ *     client_id: process.env.CLIENT_ID,
+ *     client_secret: process.env.CLIENT_SECRET,
+ *     audience: 'https://api.example.com',
+ * });
+ * await api.getTokenFromClientCredentials();
+ */
+class OAuth2Requester extends Requester {
+    static requesterType = ModuleConstants.authType.oauth2;
+
+    /**
+     * Creates an OAuth2Requester instance.
+     *
+     * @param {Object} params - Configuration parameters
+     * @param {string} [params.grant_type='authorization_code'] - OAuth grant type:
+     *   'authorization_code', 'client_credentials', or 'password'
+     * @param {string} [params.client_id] - OAuth client ID
+     * @param {string} [params.client_secret] - OAuth client secret
+     * @param {string} [params.redirect_uri] - OAuth redirect URI for authorization code flow
+     * @param {string} [params.scope] - OAuth scopes (space-separated)
+     * @param {string} [params.authorizationUri] - Authorization endpoint URL
+     * @param {string} [params.tokenUri] - Token endpoint URL for exchanging codes/credentials
+     * @param {string} [params.baseURL] - Base URL for API requests
+     * @param {string} [params.access_token] - Existing access token
+     * @param {string} [params.refresh_token] - Existing refresh token
+     * @param {Date} [params.accessTokenExpire] - Access token expiration date
+     * @param {Date} [params.refreshTokenExpire] - Refresh token expiration date
+     * @param {string} [params.audience] - Token audience (for client_credentials)
+     * @param {string} [params.username] - Username (for password grant)
+     * @param {string} [params.password] - Password (for password grant)
+     * @param {string} [params.state] - OAuth state parameter for CSRF protection
+     */
+    constructor(params) {
+        super(params);
+        /** @type {string} Delegate type for token update notifications */
+        this.DLGT_TOKEN_UPDATE = 'TOKEN_UPDATE';
+        /** @type {string} Delegate type for token deauthorization notifications */
+        this.DLGT_TOKEN_DEAUTHORIZED = 'TOKEN_DEAUTHORIZED';
+
+        this.delegateTypes.push(this.DLGT_TOKEN_UPDATE);
+        this.delegateTypes.push(this.DLGT_TOKEN_DEAUTHORIZED);
+
+        /** @type {string} OAuth grant type */
+        this.grant_type = get(params, 'grant_type', 'authorization_code');
+        /** @type {string|null} OAuth client ID */
+        this.client_id = get(params, 'client_id', null);
+        /** @type {string|null} OAuth client secret */
+        this.client_secret = get(params, 'client_secret', null);
+        /** @type {string|null} OAuth redirect URI */
+        this.redirect_uri = get(params, 'redirect_uri', null);
+        /** @type {string|null} OAuth scopes */
+        this.scope = get(params, 'scope', null);
+        /** @type {string|null} Authorization endpoint URL */
+        this.authorizationUri = get(params, 'authorizationUri', null);
+        /** @type {string|null} Token endpoint URL */
+        this.tokenUri = get(params, 'tokenUri', null);
+        /** @type {string|null} Base URL for API requests */
+        this.baseURL = get(params, 'baseURL', null);
+        /** @type {string|null} Current access token */
+        this.access_token = get(params, 'access_token', null);
+        /** @type {string|null} Current refresh token */
+        this.refresh_token = get(params, 'refresh_token', null);
+        /** @type {Date|null} Access token expiration */
+        this.accessTokenExpire = get(params, 'accessTokenExpire', null);
+        /** @type {Date|null} Refresh token expiration */
+        this.refreshTokenExpire = get(params, 'refreshTokenExpire', null);
+        /** @type {string|null} Token audience */
+        this.audience = get(params, 'audience', null);
+        /** @type {string|null} Username for password grant */
+        this.username = get(params, 'username', null);
+        /** @type {string|null} Password for password grant */
+        this.password = get(params, 'password', null);
+        /** @type {string|null} OAuth state for CSRF protection */
+        this.state = get(params, 'state', null);
+
+        /** @type {boolean} Whether this requester supports token refresh */
+        this.isRefreshable = true;
+    }
+
+    /**
+     * Sets OAuth tokens and calculates expiration times.
+     * Notifies delegates of token update via DLGT_TOKEN_UPDATE.
+     *
+     * @param {Object} params - Token response from OAuth server
+     * @param {string} params.access_token - The access token
+     * @param {string} [params.refresh_token] - The refresh token (if provided)
+     * @param {number} [params.expires_in] - Access token lifetime in seconds
+     * @param {number} [params.x_refresh_token_expires_in] - Refresh token lifetime in seconds
+     * @returns {Promise<void>}
+     */
+    async setTokens(params) {
+        this.access_token = get(params, 'access_token');
+        const newRefreshToken = get(params, 'refresh_token', null);
+        if (newRefreshToken !== null) {
+            this.refresh_token = newRefreshToken;
+        } else {
+            if (this.refresh_token) {
+                console.log(
+                    '[Frigg] No refresh_token in response, preserving existing'
+                );
+            } else {
+                console.log(
+                    '[Frigg] Current refresh_token is null and no new refresh_token in response'
+                );
+            }
+        }
+        const accessExpiresIn = get(params, 'expires_in', null);
+        const refreshExpiresIn = get(
+            params,
+            'x_refresh_token_expires_in',
+            null
+        );
+
+        this.accessTokenExpire = new Date(Date.now() + accessExpiresIn * 1000);
+        if (refreshExpiresIn !== null) {
+            this.refreshTokenExpire = new Date(
+                Date.now() + refreshExpiresIn * 1000
+            );
+        }
+
+        await this.notify(this.DLGT_TOKEN_UPDATE);
+    }
+
+    /**
+     * Gets the OAuth authorization URL for initiating the authorization code flow.
+     *
+     * @returns {string|null} The authorization URL
+     */
+    getAuthorizationUri() {
+        return this.authorizationUri;
+    }
+
+    /**
+     * Returns authorization requirements for this OAuth flow.
+     *
+     * @returns {{url: string|null, type: string}} Authorization requirements
+     */
+    getAuthorizationRequirements() {
+        return {
+            url: this.getAuthorizationUri(),
+            type: 'oauth2',
+        };
+    }
+
+    /**
+     * Exchanges an authorization code for access and refresh tokens.
+     * Requires client_id, client_secret, redirect_uri, and tokenUri to be set.
+     *
+     * @param {string} code - The authorization code from the OAuth callback
+     * @returns {Promise<Object>} Token response containing access_token, refresh_token, etc.
+     */
+    async getTokenFromCode(code) {
+        const params = new URLSearchParams();
+        params.append('grant_type', 'authorization_code');
+        params.append('client_id', this.client_id);
+        params.append('client_secret', this.client_secret);
+        params.append('redirect_uri', this.redirect_uri);
+        params.append('scope', this.scope);
+        params.append('code', code);
+        const options = {
+            body: params,
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded',
+            },
+            url: this.tokenUri,
+        };
+        const response = await this._post(options, false);
+        await this.setTokens(response);
+        return response;
+    }
+
+    /**
+     * Exchanges an authorization code for tokens using Basic Auth header.
+     * Alternative to getTokenFromCode() for OAuth servers requiring Basic Auth.
+     * Override getTokenFromCode() in child class to use this instead.
+     *
+     * @param {string} code - The authorization code from the OAuth callback
+     * @returns {Promise<Object>} Token response containing access_token, refresh_token, etc.
+     */
+    async getTokenFromCodeBasicAuthHeader(code) {
+        const params = new URLSearchParams();
+        params.append('grant_type', 'authorization_code');
+        params.append('client_id', this.client_id);
+        params.append('redirect_uri', this.redirect_uri);
+        params.append('code', code);
+
+        const options = {
+            body: params,
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded',
+                Authorization: `Basic ${Buffer.from(
+                    `${this.client_id}:${this.client_secret}`
+                ).toString('base64')}`,
+            },
+            url: this.tokenUri,
+        };
+
+        const response = await this._post(options, false);
+        await this.setTokens(response);
+        return response;
+    }
+
+    /**
+     * Refreshes the access token using the refresh token.
+     * Used for authorization_code and password grant types.
+     *
+     * @param {Object} refreshTokenObject - Object containing refresh_token
+     * @param {string} refreshTokenObject.refresh_token - The refresh token
+     * @returns {Promise<Object>} New token response
+     */
+    async refreshAccessToken(refreshTokenObject) {
+        this.access_token = undefined;
+        const params = new URLSearchParams();
+        params.append('grant_type', 'refresh_token');
+        params.append('client_id', this.client_id);
+        params.append('client_secret', this.client_secret);
+        params.append('refresh_token', refreshTokenObject.refresh_token);
+        params.append('redirect_uri', this.redirect_uri);
+
+        const options = {
+            body: params,
+            url: this.tokenUri,
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded',
+            },
+        };
+        console.log('[Frigg] Refreshing access token with options');
+        const response = await this._post(options, false);
+        await this.setTokens(response);
+        return response;
+    }
+
+    /**
+     * Adds OAuth Bearer token to request headers.
+     * Clears any existing Authorization header first to prevent stale tokens
+     * from being reused after failed refresh attempts.
+     *
+     * @param {Object} headers - Headers object to modify
+     * @returns {Promise<Object>} Headers with Authorization added
+     */
+    async addAuthHeaders(headers) {
+        delete headers.Authorization;
+        if (this.access_token) {
+            headers.Authorization = `Bearer ${this.access_token}`;
+        }
+
+        return headers;
+    }
+
+    /**
+     * Checks if the requester has valid authentication.
+     *
+     * @returns {boolean} True if authenticated with valid tokens
+     */
+    isAuthenticated() {
+        return !!(
+            this.access_token !== null &&
+            this.refresh_token !== null &&
+            this.accessTokenExpire &&
+            this.refreshTokenExpire
+        );
+    }
+
+    /**
+     * Refreshes authentication based on the configured grant type.
+     * - For authorization_code/password: Uses refreshAccessToken() with refresh_token
+     * - For client_credentials: Uses getTokenFromClientCredentials() to get new token
+     *
+     * On failure, notifies delegates via DLGT_INVALID_AUTH.
+     *
+     * @returns {Promise<boolean>} True if refresh succeeded, false if failed
+     */
+    async refreshAuth() {
+        try {
+            console.log('[Frigg] Starting token refresh', {
+                grant_type: this.grant_type,
+                has_refresh_token: !!this.refresh_token,
+                has_client_id: !!this.client_id,
+                has_client_secret: !!this.client_secret,
+                has_token_uri: !!this.tokenUri,
+                tokenUri: this.tokenUri,
+            });
+
+            if (this.grant_type !== 'client_credentials') {
+                await this.refreshAccessToken({
+                    refresh_token: this.refresh_token,
+                });
+            } else {
+                await this.getTokenFromClientCredentials();
+            }
+            console.log('[Frigg] Token refresh succeeded');
+            return true;
+        } catch (error) {
+            console.error('[Frigg] Token refresh failed', {
+                error_message: error?.message,
+                error_name: error?.name,
+                response_status: error?.response?.status,
+                response_data: error?.response?.data,
+            });
+            await this.notify(this.DLGT_INVALID_AUTH);
+            return false;
+        }
+    }
+
+    /**
+     * Obtains tokens using the Resource Owner Password Credentials grant.
+     * Requires username and password to be set.
+     *
+     * @returns {Promise<Object|undefined>} Token response or undefined on error
+     */
+    async getTokenFromUsernamePassword() {
+        try {
+            const url = this.tokenUri;
+
+            const body = {
+                username: this.username,
+                password: this.password,
+                grant_type: 'password',
+            };
+            const headers = {
+                'Content-Type': 'application/json',
+            };
+
+            const tokenRes = await this._post({
+                url,
+                body,
+                headers,
+            });
+
+            await this.setTokens(tokenRes);
+            return tokenRes;
+        } catch {
+            await this.notify(this.DLGT_INVALID_AUTH);
+        }
+    }
+
+    /**
+     * Obtains tokens using the Client Credentials grant.
+     * Used for server-to-server authentication without a user context.
+     * Requires client_id, client_secret, and optionally audience to be set.
+     *
+     * @returns {Promise<Object|undefined>} Token response or undefined on error
+     */
+    async getTokenFromClientCredentials() {
+        try {
+            const url = this.tokenUri;
+
+            const body = {
+                audience: this.audience,
+                client_id: this.client_id,
+                client_secret: this.client_secret,
+                grant_type: 'client_credentials',
+            };
+            const headers = {
+                'Content-Type': 'application/json',
+            };
+
+            const tokenRes = await this._post({
+                url,
+                body,
+                headers,
+            });
+
+            await this.setTokens(tokenRes);
+            return tokenRes;
+        } catch {
+            await this.notify(this.DLGT_INVALID_AUTH);
+        }
+    }
+}
+
+module.exports = { OAuth2Requester };

package/modules/requester/requester.js

@@ -0,0 +1,275 @@
+const fetch = require('node-fetch');
+const { Delegate } = require('../../core');
+const { FetchError } = require('../../errors');
+const { get } = require('../../assertions');
+
+const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
+
+class Requester extends Delegate {
+    constructor(params) {
+        super(params);
+        this.backOff = get(params, 'backOff', [1, 3, 10, 30, 60, 180]);
+        this.isRefreshable = false;
+        this.refreshCount = 0;
+        this.DLGT_INVALID_AUTH = 'INVALID_AUTH';
+        this.delegateTypes.push(this.DLGT_INVALID_AUTH);
+        this.agent = get(params, 'agent', null);
+
+        // Per-attempt HTTP timeout. Without this the framework called fetch()
+        // with no AbortController and no timeout — a silently-hung TCP
+        // connection (server accepts but never responds) blocked the calling
+        // promise forever, cascading into stalled batches, stalled syncs,
+        // and worker-lambda timeouts.
+        //
+        // Configuration precedence:
+        //   1. Instance param:   new Requester({ requestTimeoutMs: 30_000 })
+        //   2. Class static:     static requestTimeoutMs = 30_000
+        //   3. Default:          DEFAULT_REQUEST_TIMEOUT_MS (60s)
+        //
+        // Pass 0 (or null) to disable the timeout entirely — reserved for
+        // test doubles and documented long-running endpoints.
+        // Intentionally NOT using `get(params, ...)` here — the Frigg
+        // `get` helper throws RequiredPropertyError if the key is missing
+        // and no default is provided, which would collide with the fall-
+        // through to the class-level static override.
+        const instanceTimeout = params?.requestTimeoutMs;
+        this.requestTimeoutMs =
+            instanceTimeout !== undefined && instanceTimeout !== null
+                ? instanceTimeout
+                : this.constructor.requestTimeoutMs ??
+                  DEFAULT_REQUEST_TIMEOUT_MS;
+
+        // Allow passing in the fetch function
+        // Instance methods can use this.fetch without differentiating
+        this.fetch = get(params, 'fetch', fetch);
+    }
+
+    parsedBody = async (resp) => {
+        const contentType = resp.headers.get('Content-Type') || '';
+
+        if (
+            contentType.match(/^application\/json/) ||
+            contentType.match(/^application\/vnd.api\+json/) ||
+            contentType.match(/^application\/hal\+json/)
+        ) {
+            return resp.json();
+        }
+
+        return resp.text();
+    };
+
+    async _request(url, options, i = 0) {
+        let encodedUrl = encodeURI(url);
+        if (options.query) {
+            let queryBuild = '?';
+            for (const key in options.query) {
+                queryBuild += `${encodeURIComponent(key)}=${encodeURIComponent(
+                    options.query[key]
+                )}&`;
+            }
+            encodedUrl += queryBuild.slice(0, -1);
+        }
+
+        options.headers = await this.addAuthHeaders(options.headers);
+
+        if (this.agent) options.agent = this.agent;
+
+        // Per-attempt timeout — fresh AbortController per call so the retry
+        // recursion (with its own backoff sleeps) always gets a clean
+        // signal. Timer is cleared in the finally block regardless of
+        // outcome.
+        const timeoutMs = this.requestTimeoutMs;
+        const controller = timeoutMs > 0 ? new AbortController() : null;
+        const timeoutHandle = controller
+            ? setTimeout(() => controller.abort(), timeoutMs)
+            : null;
+        const fetchOptions = controller
+            ? { ...options, signal: controller.signal }
+            : options;
+
+        // Timer must stay active through body consumption. node-fetch v2
+        // resolves the fetch() promise when headers arrive, not when the
+        // body is fully read — so a server that sends headers and then
+        // stalls the body would still hang parsedBody() or
+        // FetchError.create()'s response.text() call. We clear the timer
+        // only after the body is fully consumed (success path) or
+        // deliberately before each recursive retry so the new attempt
+        // starts with its own fresh timer.
+        let timerCleared = false;
+        const clearRequestTimer = () => {
+            if (!timerCleared && timeoutHandle) {
+                clearTimeout(timeoutHandle);
+                timerCleared = true;
+            }
+        };
+
+        try {
+            let response;
+            try {
+                response = await this.fetch(encodedUrl, fetchOptions);
+            } catch (e) {
+                // AbortController fires AbortError (name) / ETIMEDOUT-shaped
+                // errors (type on node-fetch) when we hit the timeout. No
+                // retry on timeout: a slow endpoint is a downstream problem,
+                // and each retry would wait another `timeoutMs` before giving
+                // up — amplifying the hang into a per-record multi-minute
+                // stall at batch scale.
+                const isTimeout =
+                    e?.name === 'AbortError' || e?.type === 'aborted';
+                if (e?.code === 'ECONNRESET' && i < this.backOff.length) {
+                    clearRequestTimer();
+                    const delay = this.backOff[i] * 1000;
+                    await new Promise((resolve) =>
+                        setTimeout(resolve, delay)
+                    );
+                    return this._request(url, options, i + 1);
+                }
+                const fetchError = await FetchError.create({
+                    resource: encodedUrl,
+                    init: options,
+                    responseBody: isTimeout
+                        ? `Request timed out after ${timeoutMs}ms`
+                        : e,
+                });
+                if (isTimeout) {
+                    // Flag + machine-readable fields so callers can
+                    // distinguish a timeout from a generic network error
+                    // without parsing the message (which FetchError
+                    // sanitizes outside of STAGE=dev).
+                    fetchError.isTimeout = true;
+                    fetchError.timeoutMs = timeoutMs;
+                }
+                throw fetchError;
+            }
+
+            const { status } = response;
+
+            // If the status is retriable and there are back off requests left, retry the request
+            if ((status === 429 || status >= 500) && i < this.backOff.length) {
+                clearRequestTimer();
+                const delay = this.backOff[i] * 1000;
+                await new Promise((resolve) => setTimeout(resolve, delay));
+                return this._request(url, options, i + 1);
+            } else if (status === 401) {
+                if (!this.isRefreshable || this.refreshCount > 0) {
+                    await this.notify(this.DLGT_INVALID_AUTH);
+                } else {
+                    this.refreshCount++;
+                    const refreshSucceeded = await this.refreshAuth();
+                    if (refreshSucceeded) {
+                        clearRequestTimer();
+                        return this._request(url, options, i + 1);
+                    }
+                }
+            }
+
+            // If the error wasn't retried, throw. FetchError.create reads
+            // the response body (response.text()) — timer must still be
+            // alive to catch a stalled body stream.
+            if (status >= 400) {
+                const fetchError = await FetchError.create({
+                    resource: encodedUrl,
+                    init: options,
+                    response,
+                });
+                throw this._maybeFlagTimeoutDuringBodyRead(
+                    fetchError,
+                    timeoutMs
+                );
+            }
+
+            // parsedBody consumes the response body stream. If the server
+            // stalls mid-stream the timer (still armed) aborts it.
+            return options.returnFullRes
+                ? response
+                : await this.parsedBody(response);
+        } catch (e) {
+            // If the abort fired during body consumption, node-fetch emits
+            // the error as an AbortError on the body stream. Surface the
+            // same isTimeout flag callers use for header-phase timeouts.
+            throw this._maybeFlagTimeoutDuringBodyRead(e, timeoutMs);
+        } finally {
+            clearRequestTimer();
+        }
+    }
+
+    _maybeFlagTimeoutDuringBodyRead(err, timeoutMs) {
+        if (!err || typeof err !== 'object') return err;
+        if (err.isTimeout) return err;
+        const isAbort =
+            err.name === 'AbortError' || err.type === 'aborted';
+        if (!isAbort) return err;
+        err.isTimeout = true;
+        err.timeoutMs = timeoutMs;
+        return err;
+    }
+
+    async _get(options) {
+        const fetchOptions = {
+            method: 'GET',
+            credentials: 'include',
+            headers: options.headers || {},
+            query: options.query || {},
+            returnFullRes: options.returnFullRes || false,
+        };
+
+        const res = await this._request(options.url, fetchOptions);
+        return res;
+    }
+
+    async _post(options, stringify = true) {
+        const fetchOptions = {
+            method: 'POST',
+            credentials: 'include',
+            headers: options.headers || {},
+            query: options.query || {},
+            body: stringify ? JSON.stringify(options.body) : options.body,
+            returnFullRes: options.returnFullRes || false,
+        };
+        const res = await this._request(options.url, fetchOptions);
+        return res;
+    }
+
+    async _patch(options, stringify = true) {
+        const fetchOptions = {
+            method: 'PATCH',
+            credentials: 'include',
+            headers: options.headers || {},
+            query: options.query || {},
+            body: stringify ? JSON.stringify(options.body) : options.body,
+            returnFullRes: options.returnFullRes || false,
+        };
+        const res = await this._request(options.url, fetchOptions);
+        return res;
+    }
+
+    async _put(options, stringify = true) {
+        const fetchOptions = {
+            method: 'PUT',
+            credentials: 'include',
+            headers: options.headers || {},
+            query: options.query || {},
+            body: stringify ? JSON.stringify(options.body) : options.body,
+            returnFullRes: options.returnFullRes || false,
+        };
+        const res = await this._request(options.url, fetchOptions);
+        return res;
+    }
+
+    async _delete(options) {
+        const fetchOptions = {
+            method: 'DELETE',
+            credentials: 'include',
+            headers: options.headers || {},
+            query: options.query || {},
+            returnFullRes: options.returnFullRes || true,
+        };
+        return this._request(options.url, fetchOptions);
+    }
+
+    async refreshAuth() {
+        throw new Error('refreshAuth not yet defined in child of Requester');
+    }
+}
+
+module.exports = { Requester };

package/{module-plugin → modules}/test/mock-api/api.js

@@ -1,5 +1,5 @@
-const { get } = require('../../assertions');
-const { OAuth2Requester } = require('../../module-plugin');
+const { get } = require('../../../assertions');
+const { OAuth2Requester } = require('../..');
 
 class Api extends OAuth2Requester {
     constructor(params) {
@@ -23,7 +23,12 @@ class Api extends OAuth2Requester {
         return this.authorizationUri;
     }
 
-
+    getAuthorizationRequirements() {
+        return {
+            url: this.getAuthUri(),
+            type: 'oauth2',
+        };
+    }
 }
 
 module.exports = { Api };