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

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

@@ -0,0 +1,198 @@
+import type { Context } from 'hono';
+
+import { EXPIRES_AT_URL_PARAM } from '../../../shared/constants.ts';
+import {
+  HUBSPOT_ACCESS_TOKEN_COOKIE_NAME,
+  HUBSPOT_REFRESH_COOKIE_PREFIX,
+  TEMP_COOKIE_OAUTH_STATE,
+  TEMP_COOKIE_PKCE_VERIFIER,
+} from '../../constants.ts';
+import { base64urlDecode } from '../../utils/base64-utils.ts';
+import { parseCookies } from '../../utils/cookie-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,
+  buildOAuthRedirectUriFromRequest,
+  clearTempCookie,
+  isPositiveFiniteNumber,
+  isSafeReturnPath,
+} from './utils.ts';
+
+interface OAuthStatePayload {
+  return_path?: string;
+  sid?: string;
+}
+
+export async function handleAuthCallback(
+  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 code = c.req.query('code');
+  const state = c.req.query('state');
+
+  if (!code || !state) {
+    return c.text('Missing code or state', 400);
+  }
+
+  if (hubspotConnectEnv.isAppPrivateKeyRequired && !appKeys) {
+    return c.text(
+      'Server misconfiguration: HUBSPOT_APP_PRIVATE_KEY is required when CIMD or DPoP is enabled',
+      500
+    );
+  }
+
+  const cookies = parseCookies(c.req.header('Cookie'));
+  const expectedState = cookies[TEMP_COOKIE_OAUTH_STATE];
+  const codeVerifier = cookies[TEMP_COOKIE_PKCE_VERIFIER];
+
+  if (!expectedState || state !== decodeURIComponent(expectedState)) {
+    return c.text('State mismatch', 403);
+  }
+  if (!codeVerifier) {
+    return c.text('Missing PKCE verifier', 400);
+  }
+
+  let statePayload: OAuthStatePayload;
+  try {
+    statePayload = JSON.parse(
+      new TextDecoder().decode(base64urlDecode(decodeURIComponent(state)))
+    ) as OAuthStatePayload;
+  } catch {
+    return c.text('Malformed state value', 400);
+  }
+  const returnPath = statePayload.return_path;
+  if (!returnPath || !isSafeReturnPath(returnPath)) {
+    return c.text('Invalid return path in state', 400);
+  }
+
+  const sessionId = statePayload.sid;
+  if (!sessionId) {
+    return c.text('Missing app session cookie', 400);
+  }
+
+  const decodedCodeVerifier = decodeURIComponent(codeVerifier);
+
+  const clientId = hubspotConnectEnv.isCimdEnabled
+    ? buildCimdClientIdUrlFromRequest({
+        requestUrl: c.req.url,
+        basePath,
+        xForwardedProto,
+        xForwardedHost,
+        requestHostHeader,
+      })
+    : hubspotConnectEnv.hubspotClientId;
+
+  const redirectUri = buildOAuthRedirectUriFromRequest({
+    requestUrl: c.req.url,
+    basePath,
+    xForwardedProto,
+    xForwardedHost,
+    requestHostHeader,
+  });
+
+  const tokenEndpointUrl = new URL(
+    '/oauth/v1/token',
+    hubspotConnectEnv.hubspotOAuthApiOrigin
+  ).href;
+
+  let dpopProof: string | undefined;
+  if (hubspotConnectEnv.isDpopEnabled) {
+    dpopProof = await buildTokenEndpointDpopProof({
+      appKeys: appKeys!,
+      tokenEndpointUrl,
+      sessionIdHash: sessionId,
+    });
+  }
+
+  let formParams: Record<string, string>;
+  if (hubspotConnectEnv.isCimdEnabled) {
+    const clientAssertion = await buildClientAssertion({
+      appKeys: appKeys!,
+      clientId,
+      audience: tokenEndpointUrl,
+    });
+    formParams = {
+      grant_type: 'authorization_code',
+      code,
+      code_verifier: decodedCodeVerifier,
+      redirect_uri: redirectUri,
+      ...buildClientAssertionFormParams({ clientId, clientAssertion }),
+    };
+  } else {
+    formParams = {
+      grant_type: 'authorization_code',
+      code,
+      code_verifier: decodedCodeVerifier,
+      redirect_uri: redirectUri,
+      ...buildClientSecretFormParams({
+        clientId,
+        clientSecret: hubspotConnectEnv.hubspotClientSecret,
+      }),
+    };
+  }
+
+  const tokenResult = await requestOAuthToken({
+    tokenEndpointUrl,
+    isDpopEnabled: hubspotConnectEnv.isDpopEnabled,
+    ...(dpopProof !== undefined ? { dpopProof } : {}),
+    formParams,
+  });
+  if (!tokenResult.ok) {
+    return c.text(`Token exchange failed: ${tokenResult.errorText}`, 502);
+  }
+
+  const {
+    access_token: accessToken,
+    refresh_token: refreshToken,
+    expires_in,
+  } = tokenResult.body;
+  if (!refreshToken) {
+    return c.text('Token response missing refresh_token', 502);
+  }
+  if (!isPositiveFiniteNumber(expires_in)) {
+    return c.text('Token response missing or invalid expires_in', 502);
+  }
+
+  const expiresAt = Date.now() + expires_in * 1000;
+  const refreshCookieName = `${HUBSPOT_REFRESH_COOKIE_PREFIX}${sessionId}`;
+
+  setResponseCookie({
+    c,
+    value: serializeCookie({
+      name: HUBSPOT_ACCESS_TOKEN_COOKIE_NAME,
+      value: accessToken,
+      path: '/',
+      maxAge: expires_in,
+    }),
+  });
+  setResponseCookie({
+    c,
+    value: serializeCookie({
+      name: refreshCookieName,
+      value: refreshToken,
+      path: refreshCookiePath,
+      maxAge: REFRESH_COOKIE_MAX_AGE_SEC,
+    }),
+  });
+  setResponseCookie({ c, value: clearTempCookie(TEMP_COOKIE_PKCE_VERIFIER) });
+  setResponseCookie({ c, value: clearTempCookie(TEMP_COOKIE_OAUTH_STATE) });
+
+  const separator = returnPath.includes('?') ? '&' : '?';
+  return c.redirect(
+    `${returnPath}${separator}${EXPIRES_AT_URL_PARAM}=${expiresAt}`,
+    302
+  );
+}

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

@@ -0,0 +1,144 @@
+import { Hono } from 'hono';
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  HUBSPOT_APP_SID_COOKIE_NAME,
+  TEMP_COOKIE_OAUTH_STATE,
+  TEMP_COOKIE_PKCE_VERIFIER,
+} from '../../constants.ts';
+import { handleAuthInitSession } from './auth-init-session.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'],
+        optional: ['crm.objects.deals.read'],
+      },
+    },
+  };
+}
+
+describe('handleAuthInitSession', () => {
+  it('returns 400 for an unsafe return_path (open redirect)', async () => {
+    const app = new Hono();
+    app.get('/auth/init-session', (c) =>
+      handleAuthInitSession(c, buildOAuthRouteOptions())
+    );
+    const res = await app.request(
+      'http://localhost/auth/init-session?return_path=//evil.example.com',
+      { method: 'GET' }
+    );
+    expect(res.status).toBe(400);
+    expect(await res.text()).toContain('Invalid return_path');
+  });
+
+  it('returns JSON with authorization_url on success', async () => {
+    const app = new Hono();
+    app.get('/auth/init-session', (c) =>
+      handleAuthInitSession(c, buildOAuthRouteOptions())
+    );
+    const res = await app.request(
+      'http://localhost/auth/init-session?return_path=/dashboard',
+      { method: 'GET' }
+    );
+
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { authorization_url: string };
+    expect(body.authorization_url).toBeDefined();
+
+    const authUrl = new URL(body.authorization_url);
+    expect(authUrl.origin).toBe('https://auth.example.test');
+    expect(authUrl.searchParams.get('response_type')).toBe('code');
+    expect(authUrl.searchParams.get('client_id')).toBe('test-client-id');
+    expect(authUrl.searchParams.get('code_challenge_method')).toBe('S256');
+    expect(authUrl.searchParams.get('code_challenge')).toBeTruthy();
+    expect(authUrl.searchParams.get('state')).toBeTruthy();
+    expect(authUrl.searchParams.get('scope')).toContain(
+      'crm.objects.contacts.read'
+    );
+    expect(authUrl.searchParams.get('optional_scope')).toContain(
+      'crm.objects.deals.read'
+    );
+  });
+
+  it('sets session, PKCE verifier, and state cookies', async () => {
+    const app = new Hono();
+    app.get('/auth/init-session', (c) =>
+      handleAuthInitSession(c, buildOAuthRouteOptions())
+    );
+    const res = await app.request(
+      'http://localhost/auth/init-session?return_path=/dashboard',
+      { method: 'GET' }
+    );
+
+    expect(res.status).toBe(200);
+    const setCookies = res.headers.getSetCookie();
+
+    const sidCookie = setCookies.find((h) =>
+      h.startsWith(`${HUBSPOT_APP_SID_COOKIE_NAME}=`)
+    );
+    expect(sidCookie).toBeDefined();
+    expect(sidCookie).toContain('HttpOnly');
+
+    const pkceCookie = setCookies.find((h) =>
+      h.startsWith(`${TEMP_COOKIE_PKCE_VERIFIER}=`)
+    );
+    expect(pkceCookie).toBeDefined();
+    expect(pkceCookie).toContain('SameSite=Lax');
+
+    const stateCookie = setCookies.find((h) =>
+      h.startsWith(`${TEMP_COOKIE_OAUTH_STATE}=`)
+    );
+    expect(stateCookie).toBeDefined();
+    expect(stateCookie).toContain('SameSite=Lax');
+  });
+
+  it('defaults return_path to / when param is absent', async () => {
+    const app = new Hono();
+    app.get('/auth/init-session', (c) =>
+      handleAuthInitSession(c, buildOAuthRouteOptions())
+    );
+    const res = await app.request('http://localhost/auth/init-session', {
+      method: 'GET',
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { authorization_url: string };
+    const state =
+      new URL(body.authorization_url).searchParams.get('state') ?? '';
+    const decoded = JSON.parse(
+      new TextDecoder().decode(
+        (() => {
+          const padLen = (4 - (state.length % 4)) % 4;
+          const padded =
+            state.replace(/-/g, '+').replace(/_/g, '/') + '='.repeat(padLen);
+          const binary = atob(padded);
+          const out = new Uint8Array(binary.length);
+          for (let i = 0; i < binary.length; i++)
+            out[i] = binary.charCodeAt(i) ?? 0;
+          return out;
+        })()
+      )
+    ) as { return_path: string };
+    expect(decoded.return_path).toBe('/');
+  });
+});

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

@@ -0,0 +1,126 @@
+import type { Context } from 'hono';
+
+import {
+  HUBSPOT_APP_SID_COOKIE_NAME,
+  TEMP_COOKIE_OAUTH_STATE,
+  TEMP_COOKIE_PKCE_VERIFIER,
+} from '../../constants.ts';
+import { base64url } from '../../utils/base64-utils.ts';
+import { sha256base64url } from '../../utils/crypto-utils.ts';
+import { serializeCookie, setResponseCookie } from '../utils/cookie-utils.ts';
+import { OAUTH_TEMP_MAX_AGE_SEC, SESSION_MAX_AGE_SEC } from './constants.ts';
+import { deriveHubSpotAuthorizeScopesFromClientMetadata } from './fetch-hubspot-client-metadata.ts';
+import type { HubSpotConnectOAuthRouteOptions } from './types.ts';
+import {
+  buildCimdClientIdUrlFromRequest,
+  buildOAuthRedirectUriFromRequest,
+  isSafeReturnPath,
+} from './utils.ts';
+
+export async function handleAuthInitSession(
+  c: Context,
+  options: HubSpotConnectOAuthRouteOptions
+) {
+  const { hubspotConnectEnv, cimdClientMetadata } = 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 url = new URL(c.req.url);
+  const returnPath = url.searchParams.get('return_path') ?? '/';
+  if (!isSafeReturnPath(returnPath)) {
+    return c.text('Invalid return_path', 400);
+  }
+
+  const sessionIdBytes = new Uint8Array(32);
+  crypto.getRandomValues(sessionIdBytes);
+  const sessionId = base64url(sessionIdBytes);
+  const sessionIdHash = await sha256base64url(sessionId);
+
+  const codeVerifierBytes = new Uint8Array(32);
+  crypto.getRandomValues(codeVerifierBytes);
+  const codeVerifier = base64url(codeVerifierBytes);
+  const codeChallenge = await sha256base64url(codeVerifier);
+
+  const stateValue = base64url(
+    new TextEncoder().encode(
+      JSON.stringify({
+        return_path: returnPath,
+        sid: sessionIdHash,
+      })
+    )
+  );
+
+  const clientId = hubspotConnectEnv.isCimdEnabled
+    ? buildCimdClientIdUrlFromRequest({
+        requestUrl: c.req.url,
+        basePath: options.basePath,
+        xForwardedProto,
+        xForwardedHost,
+        requestHostHeader,
+      })
+    : hubspotConnectEnv.hubspotClientId;
+
+  const redirectUri = buildOAuthRedirectUriFromRequest({
+    requestUrl: c.req.url,
+    basePath: options.basePath,
+    xForwardedProto,
+    xForwardedHost,
+    requestHostHeader,
+  });
+
+  const authorizeUrl = new URL(hubspotConnectEnv.hubspotAuthorizationEndpoint);
+  authorizeUrl.searchParams.set('response_type', 'code');
+  authorizeUrl.searchParams.set('client_id', clientId);
+  authorizeUrl.searchParams.set('redirect_uri', redirectUri);
+  authorizeUrl.searchParams.set('code_challenge', codeChallenge);
+  authorizeUrl.searchParams.set('code_challenge_method', 'S256');
+  authorizeUrl.searchParams.set('state', stateValue);
+  authorizeUrl.searchParams.set('sid', sessionIdHash);
+
+  if (!hubspotConnectEnv.isCimdEnabled) {
+    const scopesResult =
+      deriveHubSpotAuthorizeScopesFromClientMetadata(cimdClientMetadata);
+    if (!scopesResult.ok) {
+      return c.text(scopesResult.message, scopesResult.status as 500 | 502);
+    }
+    authorizeUrl.searchParams.set('scope', scopesResult.scope);
+    if (scopesResult.optionalScope !== undefined) {
+      authorizeUrl.searchParams.set(
+        'optional_scope',
+        scopesResult.optionalScope
+      );
+    }
+  }
+
+  setResponseCookie({
+    c,
+    value: serializeCookie({
+      name: HUBSPOT_APP_SID_COOKIE_NAME,
+      value: sessionId,
+      path: '/',
+      maxAge: SESSION_MAX_AGE_SEC,
+    }),
+  });
+  setResponseCookie({
+    c,
+    value: serializeCookie({
+      name: TEMP_COOKIE_PKCE_VERIFIER,
+      value: encodeURIComponent(codeVerifier),
+      path: '/',
+      sameSite: 'Lax',
+      maxAge: OAUTH_TEMP_MAX_AGE_SEC,
+    }),
+  });
+  setResponseCookie({
+    c,
+    value: serializeCookie({
+      name: TEMP_COOKIE_OAUTH_STATE,
+      value: encodeURIComponent(stateValue),
+      path: '/',
+      sameSite: 'Lax',
+      maxAge: OAUTH_TEMP_MAX_AGE_SEC,
+    }),
+  });
+
+  return c.json({ authorization_url: authorizeUrl.toString() });
+}

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

@@ -0,0 +1,124 @@
+import { Hono } from 'hono';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import type { Logger } from '../../../shared/logger.ts';
+import {
+  HUBSPOT_ACCESS_TOKEN_COOKIE_NAME,
+  HUBSPOT_APP_SID_COOKIE_NAME,
+} from '../../constants.ts';
+import { handleAuthLogout } from './auth-logout.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;
+
+function buildOAuthRouteOptions(
+  logger: Logger
+): HubSpotConnectOAuthRouteOptions {
+  const basePath = '/functions/v1/hubspot-connect';
+  return {
+    appKeys: null,
+    refreshCookiePath: `${basePath}/auth`,
+    logger,
+    basePath,
+    hubspotConnectEnv,
+    cimdClientMetadata: {
+      scope: { required: ['crm.objects.contacts.read'] },
+    },
+  };
+}
+
+describe('handleAuthLogout', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('clears cookies and logs a warning when revoke fetch throws', async () => {
+    const warnSpy = vi.fn();
+    const logger: Logger = {
+      debug: vi.fn(),
+      info: vi.fn(),
+      warn: warnSpy,
+      error: vi.fn(),
+    };
+    const app = new Hono();
+    app.post('/auth/logout', (c) =>
+      handleAuthLogout(c, buildOAuthRouteOptions(logger))
+    );
+
+    vi.spyOn(globalThis, 'fetch').mockRejectedValue(new Error('network down'));
+
+    const res = await app.request('http://localhost/auth/logout', {
+      method: 'POST',
+      headers: {
+        Cookie: `${HUBSPOT_ACCESS_TOKEN_COOKIE_NAME}=access-token-value`,
+      },
+    });
+
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ redirect_to: '/' });
+    expect(warnSpy).toHaveBeenCalledWith(
+      'HubSpot token revoke request failed',
+      expect.any(Error)
+    );
+
+    const setCookies = res.headers.getSetCookie();
+    const accessCookie = setCookies.find((header) =>
+      header.startsWith(`${HUBSPOT_ACCESS_TOKEN_COOKIE_NAME}=`)
+    );
+    expect(accessCookie).toBeDefined();
+    expect(accessCookie).toContain('Max-Age=0');
+
+    const sidCookie = setCookies.find((header) =>
+      header.startsWith(`${HUBSPOT_APP_SID_COOKIE_NAME}=`)
+    );
+    expect(sidCookie).toBeDefined();
+    expect(sidCookie).toContain('Max-Age=0');
+  });
+
+  it('clears cookies and logs a warning when revoke returns non-OK HTTP', async () => {
+    const warnSpy = vi.fn();
+    const logger: Logger = {
+      debug: vi.fn(),
+      info: vi.fn(),
+      warn: warnSpy,
+      error: vi.fn(),
+    };
+    const app = new Hono();
+    app.post('/auth/logout', (c) =>
+      handleAuthLogout(c, buildOAuthRouteOptions(logger))
+    );
+
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+      new Response(null, { status: 502, statusText: 'Bad Gateway' })
+    );
+
+    const res = await app.request('http://localhost/auth/logout', {
+      method: 'POST',
+      headers: {
+        Cookie: `${HUBSPOT_ACCESS_TOKEN_COOKIE_NAME}=access-token-value`,
+      },
+    });
+
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ redirect_to: '/' });
+    expect(warnSpy).toHaveBeenCalledWith(
+      'HubSpot token revoke returned HTTP 502 Bad Gateway'
+    );
+
+    const setCookies = res.headers.getSetCookie();
+    expect(
+      setCookies.some((header) =>
+        header.startsWith(`${HUBSPOT_ACCESS_TOKEN_COOKIE_NAME}=`)
+      )
+    ).toBe(true);
+  });
+});