@hubspot/app-connect-sdk 1.0.0-alpha.1

package/src/server/hono/hubspot-connect-routes/auth-logout.ts

@@ -0,0 +1,140 @@
+import type { Context } from 'hono';
+
+import type { Logger } from '../../../shared/logger.ts';
+import {
+  HUBSPOT_ACCESS_TOKEN_COOKIE_NAME,
+  HUBSPOT_APP_SID_COOKIE_NAME,
+  HUBSPOT_REFRESH_COOKIE_PREFIX,
+} from '../../constants.ts';
+import { parseCookies } from '../../utils/cookie-utils.ts';
+import { serializeCookie, setResponseCookie } from '../utils/cookie-utils.ts';
+import { buildClientAssertion } from './oauth-client.ts';
+import type { HubSpotConnectOAuthRouteOptions } from './types.ts';
+import { buildCimdClientIdUrlFromRequest } from './utils.ts';
+
+async function revokeToken(options: {
+  revokeEndpointUrl: string;
+  body: URLSearchParams;
+  logger: Logger;
+}): Promise<void> {
+  const { revokeEndpointUrl, body, logger } = options;
+  try {
+    const response = await fetch(revokeEndpointUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body,
+    });
+    if (!response.ok) {
+      logger.warn(
+        `HubSpot token revoke returned HTTP ${response.status} ${response.statusText}`
+      );
+    }
+  } catch (error) {
+    logger.warn('HubSpot token revoke request failed', error);
+  }
+}
+
+export async function handleAuthLogout(
+  c: Context,
+  options: HubSpotConnectOAuthRouteOptions
+) {
+  const { appKeys, refreshCookiePath, basePath, hubspotConnectEnv, logger } =
+    options;
+  const xForwardedProto = c.req.header('x-forwarded-proto') ?? undefined;
+  const xForwardedHost = c.req.header('x-forwarded-host') ?? undefined;
+  const requestHostHeader = c.req.header('host') ?? undefined;
+  const cookies = parseCookies(c.req.header('Cookie'));
+  const accessToken = cookies[HUBSPOT_ACCESS_TOKEN_COOKIE_NAME];
+
+  const clientId = hubspotConnectEnv.isCimdEnabled
+    ? buildCimdClientIdUrlFromRequest({
+        requestUrl: c.req.url,
+        basePath,
+        xForwardedProto,
+        xForwardedHost,
+        requestHostHeader,
+      })
+    : hubspotConnectEnv.hubspotClientId;
+
+  const revokeEndpointUrl = new URL(
+    '/oauth/v1/revoke',
+    hubspotConnectEnv.hubspotOAuthApiOrigin
+  ).href;
+
+  if (accessToken) {
+    if (hubspotConnectEnv.isCimdEnabled) {
+      if (!appKeys) {
+        return c.json(
+          {
+            error:
+              'Server misconfiguration: HUBSPOT_APP_PRIVATE_KEY is required when CIMD is enabled',
+          },
+          500
+        );
+      }
+      const clientAssertion = await buildClientAssertion({
+        appKeys,
+        clientId,
+        audience: revokeEndpointUrl,
+      });
+      await revokeToken({
+        revokeEndpointUrl,
+        body: new URLSearchParams({
+          token: accessToken,
+          token_type_hint: 'access_token',
+          client_id: clientId,
+          client_assertion_type:
+            'urn:ietf:params:oauth:client-assertion-type:jwt-bearer',
+          client_assertion: clientAssertion,
+        }),
+        logger,
+      });
+    } else {
+      await revokeToken({
+        revokeEndpointUrl,
+        body: new URLSearchParams({
+          token: accessToken,
+          token_type_hint: 'access_token',
+          client_id: clientId,
+          client_secret: hubspotConnectEnv.hubspotClientSecret,
+        }),
+        logger,
+      });
+    }
+  }
+
+  setResponseCookie({
+    c,
+    value: serializeCookie({
+      name: HUBSPOT_ACCESS_TOKEN_COOKIE_NAME,
+      value: '',
+      path: '/',
+      maxAge: 0,
+    }),
+  });
+  setResponseCookie({
+    c,
+    value: serializeCookie({
+      name: HUBSPOT_APP_SID_COOKIE_NAME,
+      value: '',
+      path: '/',
+      maxAge: 0,
+    }),
+  });
+
+  Object.keys(cookies).forEach((cookieName) => {
+    if (cookieName.startsWith(HUBSPOT_REFRESH_COOKIE_PREFIX)) {
+      setResponseCookie({
+        c,
+        value: serializeCookie({
+          name: cookieName,
+          value: '',
+          path: refreshCookiePath,
+          maxAge: 0,
+        }),
+      });
+    }
+  });
+
+  return c.json({ redirect_to: '/' });
+}

package/src/server/hono/hubspot-connect-routes/auth-refresh.test.ts

@@ -0,0 +1,224 @@
+import { Hono } from 'hono';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  HUBSPOT_ACCESS_TOKEN_COOKIE_NAME,
+  HUBSPOT_APP_SID_COOKIE_NAME,
+  HUBSPOT_REFRESH_COOKIE_PREFIX,
+} from '../../constants.ts';
+import { handleAuthRefresh } from './auth-refresh.ts';
+import type { HubSpotConnectRoutesEnvClientSecret } from './load-hubspot-connect-routes-env.ts';
+import type { HubSpotConnectOAuthRouteOptions } from './types.ts';
+
+const hubspotConnectEnv = {
+  hubspotAuthorizationEndpoint: 'https://auth.example.test/oauth/authorize',
+  hubspotOAuthApiOrigin: 'https://auth.example.test',
+  isCimdEnabled: false,
+  isDpopEnabled: false,
+  isAppPrivateKeyRequired: false,
+  hubspotClientId: 'test-client-id',
+  hubspotClientSecret: 'test-client-secret',
+} satisfies HubSpotConnectRoutesEnvClientSecret;
+
+const BASE_PATH = '/functions/v1/hubspot-connect';
+
+function buildOAuthRouteOptions(): HubSpotConnectOAuthRouteOptions {
+  return {
+    appKeys: null,
+    refreshCookiePath: `${BASE_PATH}/auth`,
+    logger: { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+    basePath: BASE_PATH,
+    hubspotConnectEnv,
+    cimdClientMetadata: { scope: { required: ['crm.objects.contacts.read'] } },
+  };
+}
+
+async function sha256base64url(input: string): Promise<string> {
+  const digest = await crypto.subtle.digest(
+    'SHA-256',
+    new TextEncoder().encode(input)
+  );
+  let binary = '';
+  new Uint8Array(digest).forEach((b) => (binary += String.fromCharCode(b)));
+  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
+}
+
+describe('handleAuthRefresh', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('returns 401 when session cookie is missing', async () => {
+    const app = new Hono();
+    app.post('/auth/refresh', (c) =>
+      handleAuthRefresh(c, buildOAuthRouteOptions())
+    );
+    const res = await app.request('http://localhost/auth/refresh', {
+      method: 'POST',
+    });
+    expect(res.status).toBe(401);
+    expect(await res.json()).toEqual({ error: 'Missing session cookie' });
+  });
+
+  it('returns 401 when refresh token cookie is missing', async () => {
+    const app = new Hono();
+    app.post('/auth/refresh', (c) =>
+      handleAuthRefresh(c, buildOAuthRouteOptions())
+    );
+    const res = await app.request('http://localhost/auth/refresh', {
+      method: 'POST',
+      headers: { Cookie: `${HUBSPOT_APP_SID_COOKIE_NAME}=my-session` },
+    });
+    expect(res.status).toBe(401);
+    expect(await res.json()).toMatchObject({ error: 'Missing refresh token' });
+  });
+
+  it('returns 502 when upstream token endpoint fails', async () => {
+    const sessionId = 'test-session-id';
+    const sidHash = await sha256base64url(sessionId);
+    const refreshCookieName = `${HUBSPOT_REFRESH_COOKIE_PREFIX}${sidHash}`;
+
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+      new Response('{"error":"invalid_grant"}', {
+        status: 400,
+        statusText: 'Bad Request',
+      })
+    );
+
+    const app = new Hono();
+    app.post('/auth/refresh', (c) =>
+      handleAuthRefresh(c, buildOAuthRouteOptions())
+    );
+    const res = await app.request('http://localhost/auth/refresh', {
+      method: 'POST',
+      headers: {
+        Cookie: [
+          `${HUBSPOT_APP_SID_COOKIE_NAME}=${sessionId}`,
+          `${refreshCookieName}=old-refresh-token`,
+        ].join('; '),
+      },
+    });
+
+    expect(res.status).toBe(502);
+    expect(await res.json()).toMatchObject({
+      error: expect.stringContaining('Token refresh failed'),
+    });
+  });
+
+  it('returns 502 when token response is missing refresh_token', async () => {
+    const sessionId = 'test-session-id';
+    const sidHash = await sha256base64url(sessionId);
+    const refreshCookieName = `${HUBSPOT_REFRESH_COOKIE_PREFIX}${sidHash}`;
+
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+      new Response(
+        JSON.stringify({ access_token: 'new-at', expires_in: 1800 }),
+        { status: 200 }
+      )
+    );
+
+    const app = new Hono();
+    app.post('/auth/refresh', (c) =>
+      handleAuthRefresh(c, buildOAuthRouteOptions())
+    );
+    const res = await app.request('http://localhost/auth/refresh', {
+      method: 'POST',
+      headers: {
+        Cookie: [
+          `${HUBSPOT_APP_SID_COOKIE_NAME}=${sessionId}`,
+          `${refreshCookieName}=old-refresh-token`,
+        ].join('; '),
+      },
+    });
+
+    expect(res.status).toBe(502);
+    expect(await res.json()).toMatchObject({
+      error: expect.stringContaining('refresh_token'),
+    });
+  });
+
+  it('returns 200 and sets new cookies on success', async () => {
+    const sessionId = 'test-session-id';
+    const sidHash = await sha256base64url(sessionId);
+    const refreshCookieName = `${HUBSPOT_REFRESH_COOKIE_PREFIX}${sidHash}`;
+
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+      new Response(
+        JSON.stringify({
+          access_token: 'new-access-token',
+          refresh_token: 'new-refresh-token',
+          expires_in: 1800,
+        }),
+        { status: 200 }
+      )
+    );
+
+    const app = new Hono();
+    app.post('/auth/refresh', (c) =>
+      handleAuthRefresh(c, buildOAuthRouteOptions())
+    );
+    const res = await app.request('http://localhost/auth/refresh', {
+      method: 'POST',
+      headers: {
+        Cookie: [
+          `${HUBSPOT_APP_SID_COOKIE_NAME}=${sessionId}`,
+          `${refreshCookieName}=old-refresh-token`,
+        ].join('; '),
+      },
+    });
+
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ expires_in: 1800 });
+
+    const setCookies = res.headers.getSetCookie();
+    const accessCookie = setCookies.find((h) =>
+      h.startsWith(`${HUBSPOT_ACCESS_TOKEN_COOKIE_NAME}=`)
+    );
+    expect(accessCookie).toContain('new-access-token');
+
+    const refreshCookie = setCookies.find((h) =>
+      h.startsWith(`${refreshCookieName}=`)
+    );
+    expect(refreshCookie).toContain('new-refresh-token');
+  });
+
+  it('clears stale refresh cookies on success', async () => {
+    const sessionId = 'test-session-id';
+    const sidHash = await sha256base64url(sessionId);
+    const refreshCookieName = `${HUBSPOT_REFRESH_COOKIE_PREFIX}${sidHash}`;
+    const staleCookieName = `${HUBSPOT_REFRESH_COOKIE_PREFIX}stale-hash`;
+
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+      new Response(
+        JSON.stringify({
+          access_token: 'new-at',
+          refresh_token: 'new-rt',
+          expires_in: 1800,
+        }),
+        { status: 200 }
+      )
+    );
+
+    const app = new Hono();
+    app.post('/auth/refresh', (c) =>
+      handleAuthRefresh(c, buildOAuthRouteOptions())
+    );
+    const res = await app.request('http://localhost/auth/refresh', {
+      method: 'POST',
+      headers: {
+        Cookie: [
+          `${HUBSPOT_APP_SID_COOKIE_NAME}=${sessionId}`,
+          `${refreshCookieName}=current-rt`,
+          `${staleCookieName}=old-rt`,
+        ].join('; '),
+      },
+    });
+
+    expect(res.status).toBe(200);
+    const setCookies = res.headers.getSetCookie();
+    const staleCleared = setCookies.find((h) =>
+      h.startsWith(`${staleCookieName}=`)
+    );
+    expect(staleCleared).toContain('Max-Age=0');
+  });
+});

package/src/server/hono/hubspot-connect-routes/auth-refresh.ts

@@ -0,0 +1,171 @@
+import type { Context } from 'hono';
+
+import {
+  HUBSPOT_ACCESS_TOKEN_COOKIE_NAME,
+  HUBSPOT_APP_SID_COOKIE_NAME,
+  HUBSPOT_REFRESH_COOKIE_PREFIX,
+} from '../../constants.ts';
+import { parseCookies } from '../../utils/cookie-utils.ts';
+import { sha256base64url } from '../../utils/crypto-utils.ts';
+import { serializeCookie, setResponseCookie } from '../utils/cookie-utils.ts';
+import { REFRESH_COOKIE_MAX_AGE_SEC } from './constants.ts';
+import {
+  buildClientAssertion,
+  buildClientAssertionFormParams,
+  buildClientSecretFormParams,
+  buildTokenEndpointDpopProof,
+  requestOAuthToken,
+} from './oauth-client.ts';
+import type { HubSpotConnectOAuthRouteOptions } from './types.ts';
+import {
+  buildCimdClientIdUrlFromRequest,
+  isPositiveFiniteNumber,
+} from './utils.ts';
+
+export async function handleAuthRefresh(
+  c: Context,
+  options: HubSpotConnectOAuthRouteOptions
+) {
+  const { appKeys, refreshCookiePath, basePath, hubspotConnectEnv } = options;
+  const xForwardedProto = c.req.header('x-forwarded-proto') ?? undefined;
+  const xForwardedHost = c.req.header('x-forwarded-host') ?? undefined;
+  const requestHostHeader = c.req.header('host') ?? undefined;
+  const cookies = parseCookies(c.req.header('Cookie'));
+  const sessionId = cookies[HUBSPOT_APP_SID_COOKIE_NAME];
+  if (!sessionId) {
+    return c.json({ error: 'Missing session cookie' }, 401);
+  }
+
+  if (hubspotConnectEnv.isAppPrivateKeyRequired && !appKeys) {
+    return c.json(
+      {
+        error:
+          'Server misconfiguration: HUBSPOT_APP_PRIVATE_KEY is required when CIMD or DPoP is enabled',
+      },
+      500
+    );
+  }
+
+  const sidHash = await sha256base64url(sessionId);
+  const refreshCookieName = `${HUBSPOT_REFRESH_COOKIE_PREFIX}${sidHash}`;
+  const refreshToken = cookies[refreshCookieName];
+  if (!refreshToken) {
+    return c.json({ error: 'Missing refresh token' }, 401);
+  }
+
+  const clientId = hubspotConnectEnv.isCimdEnabled
+    ? buildCimdClientIdUrlFromRequest({
+        requestUrl: c.req.url,
+        basePath,
+        xForwardedProto,
+        xForwardedHost,
+        requestHostHeader,
+      })
+    : hubspotConnectEnv.hubspotClientId;
+
+  const tokenEndpointUrl = new URL(
+    '/oauth/v1/token',
+    hubspotConnectEnv.hubspotOAuthApiOrigin
+  ).href;
+
+  let dpopProof: string | undefined;
+  if (hubspotConnectEnv.isDpopEnabled) {
+    dpopProof = await buildTokenEndpointDpopProof({
+      appKeys: appKeys!,
+      tokenEndpointUrl,
+      sessionIdHash: sidHash,
+    });
+  }
+
+  let formParams: Record<string, string>;
+  if (hubspotConnectEnv.isCimdEnabled) {
+    const clientAssertion = await buildClientAssertion({
+      appKeys: appKeys!,
+      clientId,
+      audience: tokenEndpointUrl,
+    });
+    formParams = {
+      grant_type: 'refresh_token',
+      refresh_token: refreshToken,
+      ...buildClientAssertionFormParams({ clientId, clientAssertion }),
+    };
+  } else {
+    formParams = {
+      grant_type: 'refresh_token',
+      refresh_token: refreshToken,
+      ...buildClientSecretFormParams({
+        clientId,
+        clientSecret: hubspotConnectEnv.hubspotClientSecret,
+      }),
+    };
+  }
+
+  const tokenResult = await requestOAuthToken({
+    tokenEndpointUrl,
+    isDpopEnabled: hubspotConnectEnv.isDpopEnabled,
+    ...(dpopProof !== undefined ? { dpopProof } : {}),
+    formParams,
+  });
+  if (!tokenResult.ok) {
+    return c.json(
+      { error: `Token refresh failed: ${tokenResult.errorText}` },
+      502
+    );
+  }
+
+  const {
+    access_token: newAccessToken,
+    refresh_token: newRefreshToken,
+    expires_in,
+  } = tokenResult.body;
+
+  if (!newRefreshToken) {
+    return c.json({ error: 'Token response missing refresh_token' }, 502);
+  }
+  if (!isPositiveFiniteNumber(expires_in)) {
+    return c.json(
+      { error: 'Token response missing or invalid expires_in' },
+      502
+    );
+  }
+
+  setResponseCookie({
+    c,
+    value: serializeCookie({
+      name: HUBSPOT_ACCESS_TOKEN_COOKIE_NAME,
+      value: newAccessToken,
+      path: '/',
+      maxAge: expires_in,
+    }),
+  });
+  setResponseCookie({
+    c,
+    value: serializeCookie({
+      name: refreshCookieName,
+      value: newRefreshToken,
+      path: refreshCookiePath,
+      maxAge: REFRESH_COOKIE_MAX_AGE_SEC,
+    }),
+  });
+
+  // Cookies prefixed with HUBSPOT_REFRESH_COOKIE_PREFIX that don't match the
+  // new refresh cookie name are stale and need to be cleared.
+  Object.keys(cookies).forEach((cookieName) => {
+    if (
+      cookieName.startsWith(HUBSPOT_REFRESH_COOKIE_PREFIX) &&
+      cookieName !== refreshCookieName
+    ) {
+      setResponseCookie({
+        c,
+        value: serializeCookie({
+          name: cookieName,
+          value: '',
+          path: refreshCookiePath,
+          maxAge: 0,
+        }),
+      });
+    }
+  });
+
+  return c.json({ expires_in });
+}

package/src/server/hono/hubspot-connect-routes/cimd-client-metadata-types.ts

@@ -0,0 +1,54 @@
+/**
+ * Caller-supplied scope configuration for the CIMD document served at
+ * `{basePath}/client.json`. `redirect_uri` and `jwks_uri` are derived at
+ * request time by the hubspot-connect routes.
+ */
+export interface HubSpotConnectCimdClientMetadata {
+  scope: HubSpotConnectCimdClientScope;
+}
+
+export interface HubSpotConnectCimdClientScope {
+  required: string[];
+  optional?: string[];
+}
+
+/**
+ * JSON body returned by `GET {basePath}/client.json` (HubSpot CIMD).
+ */
+export interface HubSpotConnectCimdClientDocument {
+  redirect_uri: string;
+  jwks_uri: string;
+  scope: HubSpotConnectCimdClientScope;
+}
+
+export function assertHubSpotConnectCimdClientMetadata(
+  value: HubSpotConnectCimdClientMetadata
+): void {
+  const required = value.scope?.required;
+  const requiredOk =
+    Array.isArray(required) &&
+    required.length > 0 &&
+    required.every((s) => typeof s === 'string' && s.length > 0);
+  if (!requiredOk) {
+    throw new Error(
+      'HubSpotConnectCimdClientMetadata.scope.required must be a non-empty array of non-empty strings'
+    );
+  }
+  const optional = value.scope.optional;
+  if (optional === undefined) {
+    return;
+  }
+  if (!Array.isArray(optional)) {
+    throw new Error(
+      'HubSpotConnectCimdClientMetadata.scope.optional must be an array when set'
+    );
+  }
+  if (
+    optional.length > 0 &&
+    !optional.every((s) => typeof s === 'string' && s.length > 0)
+  ) {
+    throw new Error(
+      'HubSpotConnectCimdClientMetadata.scope.optional entries must be non-empty strings'
+    );
+  }
+}