@hubspot/ui-extensions-dev-server 1.1.6 → 1.1.7

package/dist/lib/app-functions/services/AppProxyService.js

@@ -0,0 +1,196 @@
+import express from 'express';
+import cors from 'cors';
+import axios, { isAxiosError } from 'axios';
+import crypto from 'node:crypto';
+import { axiosErrorMappings, defaultServerError, localProxyErrorMappings, } from "../constants.js";
+import { getSignatureHeaders } from "../signing.js";
+import { reportError } from "../errorReporter.js";
+export const mapToLocalUrl = (localDevUrlMapping, requestUri, allowedUrls, logger) => {
+    const url = new URL(requestUri);
+    if (allowedUrls && !allowedUrls.includes(url.origin)) {
+        logger.warn(`'${url.origin}' is not in the 'allowedUrls' list in the application configuration file. Uploading the project in it's current state may result in request failures.`);
+    }
+    const localMapping = localDevUrlMapping[url.origin] || localDevUrlMapping[`${url.origin}/`];
+    if (!localMapping) {
+        return requestUri;
+    }
+    const parsedLocalMapping = new URL(localMapping);
+    url.host = parsedLocalMapping.host;
+    url.protocol = parsedLocalMapping.protocol;
+    // The local mapping pathname is just slash, there is no need to merge
+    if (parsedLocalMapping.pathname !== '/') {
+        // If the local pathname ends with '/', remove it to avoid '//' in the path
+        const localPathname = parsedLocalMapping.pathname.endsWith('/')
+            ? parsedLocalMapping.pathname.slice(0, 1)
+            : parsedLocalMapping.pathname;
+        url.pathname = `${localPathname}${url.pathname}`;
+    }
+    const result = url.toString();
+    // If the result ends with a '/' and the user didn't add it, remove it
+    if (result.endsWith('/') && !localMapping.endsWith('/')) {
+        return result.slice(0, -1);
+    }
+    return result;
+};
+export const extractErrorData = (e) => {
+    // If the error is not an AxiosError, it was an error with the local proxy
+    // Note: reporting is handled by the caller to provide full context
+    if (!isAxiosError(e)) {
+        return defaultServerError;
+    }
+    // Check if we have a mapping, otherwise fallback to the the default error
+    let errorData = axiosErrorMappings[e.code || ''] || defaultServerError;
+    if (e.response) {
+        const { status, data } = e.response;
+        errorData = { ...errorData, status, data };
+    }
+    return errorData;
+};
+export const AppProxyService = ({ localDevUrlMapping, logger, accountId, allowedUrls, }) => {
+    const app = express();
+    app.use(cors());
+    app.use(express.json());
+    app.post('/proxy', async (req, res) => {
+        const correlationId = crypto.randomUUID();
+        const { requestUri, method, requestTimeoutMillis, requestBody, requestHeaders, } = 
+        /* eslint-disable-next-line no-unsafe-optional-chaining */
+        req?.body;
+        try {
+            logger.info(`Request to ${requestUri} started, method=${method}, correlationId=${correlationId}`);
+            const url = mapToLocalUrl(localDevUrlMapping, requestUri, allowedUrls, logger);
+            logger.info(url === requestUri
+                ? `No local mapping found, using ${requestUri}, correlationId=${correlationId}`
+                : `Mapping ${requestUri} -> ${url}, correlationId=${correlationId}`);
+            const headerKeys = Object.keys(requestHeaders || {});
+            const tooManyHeaders = headerKeys.length > 1;
+            /**
+             * Mirroring what the backend is doing
+             * https://git.hubteam.com/HubSpot/CRMExtensibility/blob/082c4468415dfa8492766e8eec59c072aed9a652/CRMExtensibilityExecutionService/src/main/java/com/hubspot/crm/extensibility/service/util/proxy/ProxyError.java#L23
+             */
+            if (tooManyHeaders) {
+                const status = 400;
+                const message = "Only 'Authorization' header is allowed";
+                logger.warn(message);
+                res.status(status).send({
+                    category: 'VALIDATION_ERROR',
+                    status: 'error',
+                    message,
+                    context: {
+                        correlationId: [correlationId],
+                        httpMethod: [method],
+                        portalId: [`${accountId}`],
+                        requestUri: [requestUri],
+                    },
+                });
+                return;
+            }
+            const nonAuthHeader = headerKeys.some((header) => 'authorization' !== header.toLowerCase());
+            /**
+             * Mirroring what the backend is doing
+             * https://git.hubteam.com/HubSpot/CRMExtensibility/blob/082c4468415dfa8492766e8eec59c072aed9a652/CRMExtensibilityExecutionService/src/main/java/com/hubspot/crm/extensibility/service/util/proxy/ProxyError.java#L15
+             */
+            if (nonAuthHeader) {
+                const status = 400;
+                const message = "Invalid Request Headers provided. Only 'Authorization' header is allowed from hubspot.fetch()";
+                logger.warn(message);
+                res.status(status).send({
+                    category: 'VALIDATION_ERROR',
+                    status: 'error',
+                    message,
+                    context: {
+                        correlationId: [correlationId],
+                        httpMethod: [method],
+                        portalId: [`${accountId}`],
+                        requestUri: [requestUri],
+                    },
+                });
+                return;
+            }
+            const methodsWithBody = ['POST', 'PUT', 'PATCH', 'DELETE'];
+            const shouldIncludeBody = methodsWithBody.includes(method.toUpperCase()) &&
+                requestBody !== undefined &&
+                requestBody !== null;
+            const { status, data: responseBody } = await axios.request({
+                url,
+                method,
+                timeout: requestTimeoutMillis,
+                ...(shouldIncludeBody && { data: JSON.stringify(requestBody) }),
+                headers: {
+                    ...requestHeaders,
+                    ...getSignatureHeaders({
+                        method,
+                        url,
+                        ...(shouldIncludeBody && { requestBody }),
+                    }),
+                    ...(shouldIncludeBody && { 'content-type': 'application/json' }),
+                },
+                maxRedirects: 0,
+            });
+            res.status(status).send({
+                status: 'success',
+                responseBody,
+                context: {
+                    correlationId: [correlationId],
+                    httpMethod: [method],
+                    appServerStatusCode: [`${status}`],
+                    portalId: [`${accountId}`],
+                    requestUri: [requestUri],
+                },
+            });
+        }
+        catch (e) {
+            const { status, message, category, data: responseBody, } = extractErrorData(e);
+            // Report non-Axios errors (dev server bugs)
+            if (!isAxiosError(e)) {
+                reportError(e, {
+                    errorType: 'local_proxy_error',
+                    accountId,
+                    requestUri,
+                    method,
+                    correlationId,
+                });
+            }
+            // This is mirroring current backend proxy behavior
+            if (status >= 300 && status <= 599) {
+                const { status: proxyStatus, message: proxyMessage, category: proxyCategory, } = localProxyErrorMappings.BAD_GATEWAY;
+                res.status(proxyStatus).send({
+                    status: 'error',
+                    context: {
+                        portalId: [`${accountId}`],
+                        httpMethod: [method],
+                        requestUri: [requestUri],
+                        correlationId: [correlationId],
+                        appServerStatusCode: [`${status}`],
+                    },
+                    message: proxyMessage,
+                    responseBody,
+                    errors: [
+                        {
+                            message: `Unacceptable HTTP status ${status} calling ${requestUri}`,
+                        },
+                    ],
+                    category: proxyCategory,
+                });
+                return;
+            }
+            res.status(status).send({
+                status: 'error',
+                message,
+                category,
+                context: {
+                    correlationId: [correlationId],
+                    httpMethod: [method],
+                    appServerStatusCode: [`${status}`],
+                    portalId: [`${accountId}`],
+                    requestUri: [requestUri],
+                },
+                responseBody,
+                errors: responseBody ? [responseBody] : undefined,
+            });
+        }
+        finally {
+            logger.info(`Request completed, correlationId=${correlationId}`);
+        }
+    });
+    return app;
+};

package/dist/lib/app-functions/services/PrivateAppUserTokenManager.d.ts

@@ -0,0 +1,22 @@
+import type { ServiceConfiguration, PrivateAppUserToken } from '../types.ts';
+export interface GetPrivateAppUserTokenOptions {
+    scopeGroups?: string[];
+    privateAppToken?: string;
+}
+export declare class PrivateAppUserTokenManager {
+    accountId: number;
+    private tokenMap;
+    private enabled;
+    private logger;
+    constructor(accountId: number, logger: ServiceConfiguration['logger']);
+    init(): Promise<void>;
+    isEnabled(): boolean;
+    cleanup(): void;
+    getPrivateAppUserToken(appId: number, { scopeGroups, privateAppToken }?: GetPrivateAppUserTokenOptions): Promise<PrivateAppUserToken | undefined>;
+    private cacheToken;
+    private validateToken;
+    private createNewToken;
+    private updateToken;
+    private getExistingToken;
+    static doesUserTokenContainAppTokenScopes(privateAppUserToken: PrivateAppUserToken): boolean;
+}

package/dist/lib/app-functions/services/PrivateAppUserTokenManager.js

@@ -0,0 +1,185 @@
+import { scopesOnAccessToken } from '@hubspot/local-dev-lib/personalAccessKey';
+import { isHubSpotHttpError } from '@hubspot/local-dev-lib/errors/index';
+import { fetchPrivateAppUserToken, createPrivateAppUserToken, updatePrivateAppUserToken, } from "../api/privateAppUserToken.js";
+import { USER_TOKEN_READ, USER_TOKEN_WRITE, TOKEN_TIME_TO_LIVE, TOKEN_REFRESH_THRESHOLD, } from "./constants.js";
+import { generateCahedTokeMessage, generateMissingScopesMessage, generateTokensEnableMessage, generateTokensNotEnabledMessage, generateTokenCachedMessage, generateTokenOpErrorMessage, generateCreateTokenMessage, generateTokenRefreshMessage, generateMissingScopesMoreContextMessage, } from "./messages.js";
+import { reportError } from "../errorReporter.js";
+const MINUTES_TO_MS = 60000;
+function getTokenExpirationDate() {
+    return new Date(Date.now() + TOKEN_TIME_TO_LIVE * MINUTES_TO_MS).toISOString();
+}
+function getExpDateWithThreshold(expiresAt) {
+    /*
+     * Subtracting the threshold from the expiration date to ensure
+     * that the token is still valid when it's used. If we waint until
+     * the expiration date, we could fire a request with an expired token.
+     */
+    return new Date(new Date(expiresAt).getTime() - TOKEN_REFRESH_THRESHOLD * MINUTES_TO_MS);
+}
+export class PrivateAppUserTokenManager {
+    accountId;
+    tokenMap;
+    enabled;
+    logger;
+    constructor(accountId, logger) {
+        this.accountId = accountId;
+        this.tokenMap = new Map();
+        this.enabled = false;
+        this.logger = logger;
+    }
+    async init() {
+        const scopeGroups = new Set(await scopesOnAccessToken(this.accountId));
+        if (scopeGroups.has(USER_TOKEN_READ) && scopeGroups.has(USER_TOKEN_WRITE)) {
+            this.logger.info(generateTokensEnableMessage(this.accountId));
+            this.enabled = true;
+            return;
+        }
+        this.logger.info(generateMissingScopesMessage(this.accountId));
+        this.logger.debug(generateMissingScopesMoreContextMessage(this.accountId));
+    }
+    isEnabled() {
+        return this.enabled;
+    }
+    cleanup() {
+        this.tokenMap.clear();
+    }
+    async getPrivateAppUserToken(appId, { scopeGroups = [], privateAppToken } = {}) {
+        if (!this.isEnabled()) {
+            this.logger.debug(generateTokensNotEnabledMessage(this.accountId, appId));
+            return;
+        }
+        try {
+            const tokenInCache = this.tokenMap.get(appId);
+            // we have a token in cache and it's valid
+            if (tokenInCache && this.validateToken(tokenInCache.token, scopeGroups)) {
+                this.logger.debug(generateCahedTokeMessage(appId));
+                return tokenInCache.token;
+            }
+            let token = await this.getExistingToken(appId);
+            // token exists but it's not valid. Refresh it
+            if (token && !this.validateToken(token, scopeGroups)) {
+                token = await this.updateToken({
+                    appId,
+                    scopeGroups,
+                    privateAppToken,
+                    userTokenKey: token.userTokenKey,
+                });
+            }
+            // token doesn't exist. Create a new one.
+            else if (token === null) {
+                token = await this.createNewToken(appId, scopeGroups, privateAppToken);
+            }
+            this.cacheToken(appId, token, scopeGroups);
+            return token;
+        }
+        catch (err) {
+            reportError(err, {
+                operation: 'get_private_app_user_token',
+                appId,
+                accountId: this.accountId,
+                errorType: 'token_manager_error',
+            });
+            let messageDetail = 'Unknown error';
+            if (err instanceof Error) {
+                messageDetail = err.message;
+            }
+            throw new Error(generateTokenOpErrorMessage({
+                operation: 'get',
+                appId,
+                accountId: this.accountId,
+                messageDetail,
+            }), { cause: err });
+        }
+    }
+    cacheToken(appId, token, requestedScopeGroups) {
+        if (!token) {
+            throw new Error(generateTokenOpErrorMessage({
+                appId,
+                accountId: this.accountId,
+                operation: 'refresh',
+            }));
+        }
+        const cachedValue = {
+            token,
+            requestedScopeGroups,
+        };
+        this.tokenMap.set(appId, cachedValue);
+        this.logger.debug(generateTokenCachedMessage(appId, token.expiresAt));
+    }
+    validateToken(token, scopeGroups) {
+        if (!token) {
+            return false;
+        }
+        const isTokenActive = new Date() < getExpDateWithThreshold(token.expiresAt);
+        const hasAllScopes = Array.isArray(scopeGroups) &&
+            scopeGroups.every((scopeGroup) => token.scopeGroups.includes(scopeGroup));
+        return isTokenActive && hasAllScopes;
+    }
+    async createNewToken(appId, scopeGroups, privateAppToken) {
+        this.logger.debug(generateCreateTokenMessage(appId));
+        const response = await createPrivateAppUserToken({
+            appId,
+            scopeGroups,
+            privateAppToken,
+            accountId: this.accountId,
+            expiresAt: getTokenExpirationDate(),
+        });
+        if (response.status === 200) {
+            return response.data;
+        }
+        throw new Error(generateTokenOpErrorMessage({
+            appId,
+            operation: 'create',
+            accountId: this.accountId,
+        }));
+    }
+    async updateToken({ appId, userTokenKey, scopeGroups, privateAppToken, }) {
+        this.logger.debug(generateTokenRefreshMessage(appId));
+        const response = await updatePrivateAppUserToken({
+            appId,
+            userTokenKey,
+            scopeGroups,
+            privateAppToken,
+            accountId: this.accountId,
+            expiresAt: getTokenExpirationDate(),
+        });
+        if (response.status === 200) {
+            return response.data;
+        }
+        throw new Error(generateTokenOpErrorMessage({
+            appId,
+            accountId: this.accountId,
+            operation: 'refresh',
+        }));
+    }
+    async getExistingToken(appId) {
+        try {
+            const response = await fetchPrivateAppUserToken({
+                accountId: this.accountId,
+                appId,
+            });
+            if (response.status === 200) {
+                return response.data;
+            }
+            return null;
+        }
+        catch (err) {
+            if (isHubSpotHttpError(err) && err?.status === 404) {
+                return null;
+            }
+            throw err;
+        }
+    }
+    static doesUserTokenContainAppTokenScopes(privateAppUserToken) {
+        const privateAppToken = privateAppUserToken.privateAppTokenInfo;
+        // if the private app token is not present, we can't compare the scopes
+        if (!privateAppToken)
+            return false;
+        const privateAppTokenScopes = privateAppToken.scopeGroups ?? [];
+        const privateAppUserTokenScopes = privateAppUserToken.scopeGroups ?? [];
+        const areBothEmpty = privateAppUserTokenScopes.length === 0 &&
+            privateAppTokenScopes.length === 0;
+        return (areBothEmpty ||
+            privateAppTokenScopes.every((scope) => privateAppUserTokenScopes.includes(scope)));
+    }
+}

package/dist/lib/app-functions/services/constants.d.ts

@@ -0,0 +1,4 @@
+export declare const USER_TOKEN_READ = "developer.private_app.temporary_token.read";
+export declare const USER_TOKEN_WRITE = "developer.private_app.temporary_token.write";
+export declare const TOKEN_TIME_TO_LIVE = 15;
+export declare const TOKEN_REFRESH_THRESHOLD = 5;

package/dist/lib/app-functions/services/constants.js

@@ -0,0 +1,4 @@
+export const USER_TOKEN_READ = 'developer.private_app.temporary_token.read';
+export const USER_TOKEN_WRITE = 'developer.private_app.temporary_token.write';
+export const TOKEN_TIME_TO_LIVE = 15; // minutes
+export const TOKEN_REFRESH_THRESHOLD = 5; // minutes

package/dist/lib/app-functions/services/index.d.ts

@@ -0,0 +1,3 @@
+import { AppFunctionExecutionService } from './AppFunctionExecutionService.ts';
+import { AppProxyService } from './AppProxyService.ts';
+export { AppFunctionExecutionService, AppProxyService };

package/dist/lib/app-functions/services/index.js

@@ -0,0 +1,3 @@
+import { AppFunctionExecutionService } from "./AppFunctionExecutionService.js";
+import { AppProxyService } from "./AppProxyService.js";
+export { AppFunctionExecutionService, AppProxyService };

package/dist/lib/app-functions/services/messages.d.ts

@@ -0,0 +1,14 @@
+export declare function generateMissingScopesMessage(accountId: number): string;
+export declare function generateTokensEnableMessage(accountId: number): string;
+export declare function generateMissingScopesMoreContextMessage(accountId: number): string;
+export declare function generateTokensNotEnabledMessage(accountId: number, appId: number): string;
+export declare function generateCahedTokeMessage(appId: number): string;
+export declare function generateTokenCachedMessage(appId: number, expiresAt: string): string;
+export declare function generateCreateTokenMessage(appId: number): string;
+export declare function generateTokenOpErrorMessage({ appId, accountId, messageDetail, operation, }: {
+    appId: number;
+    accountId: number;
+    messageDetail?: string;
+    operation?: 'create' | 'get' | 'refresh';
+}): string;
+export declare function generateTokenRefreshMessage(appId: number): string;

package/dist/lib/app-functions/services/messages.js

@@ -0,0 +1,36 @@
+export function generateMissingScopesMessage(accountId) {
+    return `Your account is missing the "App functions" scope, so some new features won’t work. To fix this, regenerate the Personal Access Key for account: ${accountId}`;
+}
+export function generateTokensEnableMessage(accountId) {
+    return `Private app user tokens are enabled for accountId: ${accountId}`;
+}
+export function generateMissingScopesMoreContextMessage(accountId) {
+    return `
+    Heads up! Private app user tokens are now supported for serverless functions, but it looks like the account (ID: ${accountId}) is missing the required "App functions" scope.
+
+    To fix this:
+    1. Deactivate the existing Personal Access Key for this account.
+    2. Generate a new Personal Access Key with the "App functions" scope enabled.
+    3. Run "hs auth" and reauthenticate the account (ID: ${accountId}).
+
+    Once updated, you won't need a "PRIVATE_APP_ACCESS_TOKEN" for local development.
+  `;
+}
+export function generateTokensNotEnabledMessage(accountId, appId) {
+    return `Private app user tokens are not enabled for accountId ${accountId}, skipping call to fetch for appId ${appId}`;
+}
+export function generateCahedTokeMessage(appId) {
+    return `Using cached private app user token for appId ${appId}`;
+}
+export function generateTokenCachedMessage(appId, expiresAt) {
+    return `Token for appId ${appId} expiring at ${expiresAt} is in cache.`;
+}
+export function generateCreateTokenMessage(appId) {
+    return `Creating new private app user token for appId ${appId}`;
+}
+export function generateTokenOpErrorMessage({ appId, accountId, messageDetail = '', operation = 'create', }) {
+    return `Unable to ${operation} private app user token for appId ${appId} on accountId ${accountId}. ${messageDetail}`;
+}
+export function generateTokenRefreshMessage(appId) {
+    return `Refreshing private app user token for appId ${appId}`;
+}

package/dist/lib/app-functions/signing.d.ts

@@ -0,0 +1,29 @@
+interface SignV2Params {
+    method: string;
+    url: string;
+    requestBody: string;
+    clientSecret: string;
+    signature: '';
+}
+interface SignV3Params extends SignV2Params {
+    timestamp: number;
+}
+interface Sign {
+    v2: (options: SignV2Params) => string;
+    v3: (options: SignV3Params) => string;
+}
+export declare const sign: Sign;
+interface SignatureHeaders {
+    'X-HubSpot-Signature': string;
+    'X-HubSpot-Signature-Version': 'v2';
+    'X-HubSpot-Request-Timestamp': number;
+    'X-HubSpot-Signature-v3': string;
+}
+type GetSignatureHeaders = (params: {
+    method: string;
+    url: string;
+    requestBody?: unknown;
+}) => SignatureHeaders | undefined;
+export declare const formatForSigning: (body: unknown) => string;
+export declare const getSignatureHeaders: GetSignatureHeaders;
+export {};

package/dist/lib/app-functions/signing.js

@@ -0,0 +1,51 @@
+import { Signature } from '@hubspot/api-client';
+// Only exported for testing
+export const sign = {
+    v2: ({ method, ...options }) => Signature.getSignature(method, 'v2', options),
+    v3: ({ method, ...options }) => Signature.getSignature(method, 'v3', options),
+};
+export const formatForSigning = (body) => {
+    if (body === null) {
+        return '';
+    }
+    if (typeof body === 'number' &&
+        (!Number.isFinite(body) || Number.isNaN(body))) {
+        return '';
+    }
+    // Anything that stringifies to undefined will be an empty string
+    return JSON.stringify(body) || '';
+};
+// This is only used for signing local dev proxy requests
+export const getSignatureHeaders = ({ method, url, requestBody, }) => {
+    const clientSecret = process.env.CLIENT_SECRET;
+    if (!clientSecret) {
+        return;
+    }
+    const timestamp = new Date().getTime();
+    const signingProps = {
+        method,
+        url,
+        requestBody: formatForSigning(requestBody),
+        clientSecret,
+        /**
+         * I'm not sure why the signing function requires this
+         *
+         * https://github.com/HubSpot/hubspot-api-nodejs/blob/bfaa106af7199adbce5f766b1eb35a73f3c72499/src/utils/ISignatureOptions.ts
+         *
+         * But it doesn't use it for signing
+         *
+         * https://github.com/HubSpot/hubspot-api-nodejs/blob/bfaa106af7199adbce5f766b1eb35a73f3c72499/src/utils/signature.ts#L19-L32
+         *
+         */
+        signature: '',
+    };
+    return {
+        'X-HubSpot-Signature': sign.v2(signingProps),
+        'X-HubSpot-Signature-Version': 'v2',
+        'X-HubSpot-Request-Timestamp': timestamp,
+        'X-HubSpot-Signature-v3': sign.v3({
+            ...signingProps,
+            timestamp,
+        }),
+    };
+};