@hubspot/app-connect-sdk 1.0.0-alpha.2 → 1.0.0-alpha.4

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

@@ -0,0 +1,285 @@
+import { Hono } from 'hono';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { HUBSPOT_FRONTEND_CALLBACK_PATH } from '../../../shared/constants.ts';
+import {
+  HUBSPOT_ACCESS_TOKEN_COOKIE_NAME,
+  HUBSPOT_APP_ORIGIN_COOKIE_NAME,
+  HUBSPOT_REFRESH_COOKIE_PREFIX,
+  TEMP_COOKIE_OAUTH_STATE,
+  TEMP_COOKIE_PKCE_VERIFIER,
+} from '../../constants.ts';
+import { handleAuthComplete } from './auth-complete.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';
+const APP_ORIGIN = 'https://app.example.com';
+
+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'] } },
+  };
+}
+
+function base64urlEncode(input: string): string {
+  let binary = '';
+  const bytes = new TextEncoder().encode(input);
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
+}
+
+interface CompleteFixture {
+  stateValue: string;
+  cookieHeader: string;
+}
+
+function buildCompleteFixture(options?: {
+  returnPath?: string;
+  sid?: string;
+  appOrigin?: string | null;
+}): CompleteFixture {
+  const returnPath = options?.returnPath ?? '/dashboard';
+  const sid = options?.sid ?? 'test-session-id-hash';
+  const appOrigin =
+    options?.appOrigin === null ? null : (options?.appOrigin ?? APP_ORIGIN);
+  const stateValue = base64urlEncode(
+    JSON.stringify({ return_path: returnPath, sid })
+  );
+  const cookieParts = [
+    `${TEMP_COOKIE_OAUTH_STATE}=${encodeURIComponent(stateValue)}`,
+    `${TEMP_COOKIE_PKCE_VERIFIER}=${encodeURIComponent('test-pkce-verifier')}`,
+  ];
+  if (appOrigin !== null) {
+    cookieParts.push(`${HUBSPOT_APP_ORIGIN_COOKIE_NAME}=${appOrigin}`);
+  }
+  return { stateValue, cookieHeader: cookieParts.join('; ') };
+}
+
+function buildCompleteUrl(stateValue: string, code = 'test-auth-code'): string {
+  const url = new URL(`http://localhost${BASE_PATH}/auth/complete`);
+  url.searchParams.set('code', code);
+  url.searchParams.set('state', stateValue);
+  return url.toString();
+}
+
+describe('handleAuthComplete', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('returns 400 when code is missing', async () => {
+    const app = new Hono();
+    app.post('/auth/complete', (c) =>
+      handleAuthComplete(c, buildOAuthRouteOptions())
+    );
+    const res = await app.request('http://localhost/auth/complete?state=abc', {
+      method: 'POST',
+    });
+    expect(res.status).toBe(400);
+    expect(await res.json()).toMatchObject({ error: 'Missing code or state' });
+  });
+
+  it('returns 400 when state is missing', async () => {
+    const app = new Hono();
+    app.post('/auth/complete', (c) =>
+      handleAuthComplete(c, buildOAuthRouteOptions())
+    );
+    const res = await app.request('http://localhost/auth/complete?code=abc', {
+      method: 'POST',
+    });
+    expect(res.status).toBe(400);
+    expect(await res.json()).toMatchObject({ error: 'Missing code or state' });
+  });
+
+  it('returns 403 when state cookie is missing', async () => {
+    const app = new Hono();
+    app.post(`${BASE_PATH}/auth/complete`, (c) =>
+      handleAuthComplete(c, buildOAuthRouteOptions())
+    );
+    const { stateValue } = buildCompleteFixture();
+    const res = await app.request(buildCompleteUrl(stateValue), {
+      method: 'POST',
+    });
+    expect(res.status).toBe(403);
+    expect(await res.json()).toMatchObject({ error: 'State mismatch' });
+  });
+
+  it('returns 403 when state does not match cookie', async () => {
+    const app = new Hono();
+    app.post(`${BASE_PATH}/auth/complete`, (c) =>
+      handleAuthComplete(c, buildOAuthRouteOptions())
+    );
+    const { cookieHeader } = buildCompleteFixture();
+    const res = await app.request(buildCompleteUrl('wrong-state-value'), {
+      method: 'POST',
+      headers: { Cookie: cookieHeader },
+    });
+    expect(res.status).toBe(403);
+  });
+
+  it('returns 400 when state payload has invalid return_path', async () => {
+    const app = new Hono();
+    app.post(`${BASE_PATH}/auth/complete`, (c) =>
+      handleAuthComplete(c, buildOAuthRouteOptions())
+    );
+    const { stateValue, cookieHeader } = buildCompleteFixture({
+      returnPath: '//evil.example.com',
+    });
+    const res = await app.request(buildCompleteUrl(stateValue), {
+      method: 'POST',
+      headers: { Cookie: cookieHeader },
+    });
+    expect(res.status).toBe(400);
+    expect(await res.json()).toMatchObject({
+      error: expect.stringContaining('Invalid return path'),
+    });
+  });
+
+  it('returns 400 when the pinned app-origin cookie is absent', async () => {
+    const app = new Hono();
+    app.post(`${BASE_PATH}/auth/complete`, (c) =>
+      handleAuthComplete(c, buildOAuthRouteOptions())
+    );
+    const { stateValue, cookieHeader } = buildCompleteFixture({
+      appOrigin: null,
+    });
+    const res = await app.request(buildCompleteUrl(stateValue), {
+      method: 'POST',
+      headers: { Cookie: cookieHeader },
+    });
+    expect(res.status).toBe(400);
+    expect(await res.json()).toMatchObject({
+      error: expect.stringContaining('app origin'),
+    });
+  });
+
+  it('returns 502 when upstream token exchange fails', async () => {
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+      new Response('{"error":"invalid_grant"}', {
+        status: 400,
+        statusText: 'Bad Request',
+      })
+    );
+    const app = new Hono();
+    app.post(`${BASE_PATH}/auth/complete`, (c) =>
+      handleAuthComplete(c, buildOAuthRouteOptions())
+    );
+    const { stateValue, cookieHeader } = buildCompleteFixture();
+    const res = await app.request(buildCompleteUrl(stateValue), {
+      method: 'POST',
+      headers: { Cookie: cookieHeader },
+    });
+    expect(res.status).toBe(502);
+    expect(await res.json()).toMatchObject({
+      error: expect.stringContaining('Token exchange failed'),
+    });
+  });
+
+  it('sends the OAuth token endpoint the same redirect_uri it advertised in init-session', async () => {
+    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+      new Response(
+        JSON.stringify({
+          access_token: 'at',
+          refresh_token: 'rt',
+          expires_in: 1800,
+        }),
+        { status: 200 }
+      )
+    );
+    const app = new Hono();
+    app.post(`${BASE_PATH}/auth/complete`, (c) =>
+      handleAuthComplete(c, buildOAuthRouteOptions())
+    );
+    const { stateValue, cookieHeader } = buildCompleteFixture();
+    await app.request(buildCompleteUrl(stateValue), {
+      method: 'POST',
+      headers: { Cookie: cookieHeader },
+    });
+
+    const [, init] = fetchSpy.mock.calls[0]!;
+    const body = (init as RequestInit).body as URLSearchParams | string;
+    const formParams = new URLSearchParams(body as string);
+    expect(formParams.get('redirect_uri')).toBe(
+      `${APP_ORIGIN}${HUBSPOT_FRONTEND_CALLBACK_PATH}`
+    );
+    expect(formParams.get('grant_type')).toBe('authorization_code');
+  });
+
+  it('returns 200 with expires_at + return_path and sets durable cookies on success', async () => {
+    const beforeMs = Date.now();
+    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(`${BASE_PATH}/auth/complete`, (c) =>
+      handleAuthComplete(c, buildOAuthRouteOptions())
+    );
+    const { stateValue, cookieHeader } = buildCompleteFixture({
+      returnPath: '/dashboard',
+      sid: 'abc123sid',
+    });
+    const res = await app.request(buildCompleteUrl(stateValue), {
+      method: 'POST',
+      headers: { Cookie: cookieHeader },
+    });
+
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      expires_at: number;
+      return_path: string;
+    };
+    expect(body.return_path).toBe('/dashboard');
+    expect(body.expires_at).toBeGreaterThanOrEqual(beforeMs + 1800 * 1000 - 50);
+
+    const setCookies = res.headers.getSetCookie();
+
+    const accessCookie = setCookies.find((h) =>
+      h.startsWith(`${HUBSPOT_ACCESS_TOKEN_COOKIE_NAME}=`)
+    );
+    expect(accessCookie).toBeDefined();
+    expect(accessCookie).toContain('new-access-token');
+    expect(accessCookie).toContain('SameSite=None');
+    expect(accessCookie).toContain('Partitioned');
+
+    const refreshCookie = setCookies.find((h) =>
+      h.startsWith(`${HUBSPOT_REFRESH_COOKIE_PREFIX}`)
+    );
+    expect(refreshCookie).toBeDefined();
+    expect(refreshCookie).toContain('new-refresh-token');
+    expect(refreshCookie).toContain('SameSite=None');
+    expect(refreshCookie).toContain('Partitioned');
+
+    const pkceCleared = setCookies.find((h) =>
+      h.startsWith(`${TEMP_COOKIE_PKCE_VERIFIER}=`)
+    );
+    expect(pkceCleared).toContain('Max-Age=0');
+
+    const stateCleared = setCookies.find((h) =>
+      h.startsWith(`${TEMP_COOKIE_OAUTH_STATE}=`)
+    );
+    expect(stateCleared).toContain('Max-Age=0');
+  });
+});

package/src/server/hono/hubspot-connect-routes/{auth-callback.ts → auth-complete.ts}

@@ -1,8 +1,12 @@
 import type { Context } from 'hono';
 
-import { EXPIRES_AT_URL_PARAM } from '../../../shared/constants.ts';
+import {
+  AUTH_COMPLETE_CODE_PARAM,
+  AUTH_COMPLETE_STATE_PARAM,
+} from '../../../shared/constants.ts';
 import {
   HUBSPOT_ACCESS_TOKEN_COOKIE_NAME,
+  HUBSPOT_APP_ORIGIN_COOKIE_NAME,
   HUBSPOT_REFRESH_COOKIE_PREFIX,
   TEMP_COOKIE_OAUTH_STATE,
   TEMP_COOKIE_PKCE_VERIFIER,
@@ -21,10 +25,11 @@ import {
 import type { HubSpotConnectOAuthRouteOptions } from './types.ts';
 import {
   buildCimdClientIdUrlFromRequest,
-  buildOAuthRedirectUriFromRequest,
+  buildFrontendOAuthRedirectUri,
   clearTempCookie,
   isPositiveFiniteNumber,
   isSafeReturnPath,
+  parseAppOriginHeader,
 } from './utils.ts';
 
 interface OAuthStatePayload {
@@ -32,24 +37,53 @@ interface OAuthStatePayload {
   sid?: string;
 }
 
-export async function handleAuthCallback(
+/**
+ * Cross-origin OAuth completion endpoint.
+ *
+ * Called from the React app on the frontend OAuth callback path
+ * (`HUBSPOT_FRONTEND_CALLBACK_PATH`) once HubSpot has redirected the
+ * browser back with `?code` + `?state`. The browser POSTs both
+ * values here as a credentialed cross-site fetch — same partition as
+ * `init-session`, so the temp PKCE/state cookies are visible — and
+ * the SDK:
+ *
+ * 1. Validates `state` against the temp `__hs_oauth_state` cookie.
+ * 2. Pulls the PKCE verifier from `__hs_pkce_verifier`.
+ * 3. Rebuilds the same `redirect_uri` it sent to HubSpot during
+ *    `init-session` (frontend origin + the fixed callback path);
+ *    the OAuth token endpoint requires the two values to match.
+ * 4. Exchanges `code` for an access + refresh token (with DPoP /
+ *    CIMD client-assertion when enabled).
+ * 5. Sets the durable session cookies (access token, refresh) with
+ *    `SameSite=None; Secure; Partitioned` so they live in the
+ *    `(frontend, edge)` partition where subsequent API fetches will
+ *    read them.
+ * 6. Clears the temp cookies.
+ * 7. Returns `{ expires_at, return_path }` so the controller can
+ *    update its session-storage expiry tracking and navigate back to
+ *    the page the user started the connect flow from.
+ */
+export async function handleAuthComplete(
   c: Context,
   options: HubSpotConnectOAuthRouteOptions
 ) {
-  const { appKeys, refreshCookiePath, basePath, hubspotConnectEnv } = options;
+  const { appKeys, refreshCookiePath, 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');
+  const code = c.req.query(AUTH_COMPLETE_CODE_PARAM);
+  const state = c.req.query(AUTH_COMPLETE_STATE_PARAM);
 
   if (!code || !state) {
-    return c.text('Missing code or state', 400);
+    return c.json({ error: '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',
+    return c.json(
+      {
+        error:
+          'Server misconfiguration: HUBSPOT_APP_PRIVATE_KEY is required when CIMD or DPoP is enabled',
+      },
       500
     );
   }
@@ -57,12 +91,21 @@ export async function handleAuthCallback(
   const cookies = parseCookies(c.req.header('Cookie'));
   const expectedState = cookies[TEMP_COOKIE_OAUTH_STATE];
   const codeVerifier = cookies[TEMP_COOKIE_PKCE_VERIFIER];
+  const appOriginCookie = cookies[HUBSPOT_APP_ORIGIN_COOKIE_NAME];
 
   if (!expectedState || state !== decodeURIComponent(expectedState)) {
-    return c.text('State mismatch', 403);
+    return c.json({ error: 'State mismatch' }, 403);
   }
   if (!codeVerifier) {
-    return c.text('Missing PKCE verifier', 400);
+    return c.json({ error: 'Missing PKCE verifier' }, 400);
+  }
+  // The redirect_uri the OAuth token endpoint validates must equal
+  // the one we sent during init-session. We rebuild it from the
+  // pinned origin cookie so that value is anchored server-side, not
+  // taken from the (caller-controlled) request `Origin` on this call.
+  const appOrigin = parseAppOriginHeader(appOriginCookie);
+  if (!appOrigin) {
+    return c.json({ error: 'Missing app origin cookie' }, 400);
   }
 
   let statePayload: OAuthStatePayload;
@@ -71,16 +114,16 @@ export async function handleAuthCallback(
       new TextDecoder().decode(base64urlDecode(decodeURIComponent(state)))
     ) as OAuthStatePayload;
   } catch {
-    return c.text('Malformed state value', 400);
+    return c.json({ error: 'Malformed state value' }, 400);
   }
   const returnPath = statePayload.return_path;
   if (!returnPath || !isSafeReturnPath(returnPath)) {
-    return c.text('Invalid return path in state', 400);
+    return c.json({ error: 'Invalid return path in state' }, 400);
   }
 
   const sessionId = statePayload.sid;
   if (!sessionId) {
-    return c.text('Missing app session cookie', 400);
+    return c.json({ error: 'Missing app session cookie' }, 400);
   }
 
   const decodedCodeVerifier = decodeURIComponent(codeVerifier);
@@ -88,20 +131,14 @@ export async function handleAuthCallback(
   const clientId = hubspotConnectEnv.isCimdEnabled
     ? buildCimdClientIdUrlFromRequest({
         requestUrl: c.req.url,
-        basePath,
+        basePath: options.basePath,
         xForwardedProto,
         xForwardedHost,
         requestHostHeader,
       })
     : hubspotConnectEnv.hubspotClientId;
 
-  const redirectUri = buildOAuthRedirectUriFromRequest({
-    requestUrl: c.req.url,
-    basePath,
-    xForwardedProto,
-    xForwardedHost,
-    requestHostHeader,
-  });
+  const redirectUri = buildFrontendOAuthRedirectUri(appOrigin);
 
   const tokenEndpointUrl = new URL(
     '/oauth/v1/token',
@@ -151,7 +188,10 @@ export async function handleAuthCallback(
     formParams,
   });
   if (!tokenResult.ok) {
-    return c.text(`Token exchange failed: ${tokenResult.errorText}`, 502);
+    return c.json(
+      { error: `Token exchange failed: ${tokenResult.errorText}` },
+      502
+    );
   }
 
   const {
@@ -160,10 +200,13 @@ export async function handleAuthCallback(
     expires_in,
   } = tokenResult.body;
   if (!refreshToken) {
-    return c.text('Token response missing refresh_token', 502);
+    return c.json({ error: 'Token response missing refresh_token' }, 502);
   }
   if (!isPositiveFiniteNumber(expires_in)) {
-    return c.text('Token response missing or invalid expires_in', 502);
+    return c.json(
+      { error: 'Token response missing or invalid expires_in' },
+      502
+    );
   }
 
   const expiresAt = Date.now() + expires_in * 1000;
@@ -175,6 +218,8 @@ export async function handleAuthCallback(
       name: HUBSPOT_ACCESS_TOKEN_COOKIE_NAME,
       value: accessToken,
       path: '/',
+      sameSite: 'None',
+      partitioned: true,
       maxAge: expires_in,
     }),
   });
@@ -184,15 +229,13 @@ export async function handleAuthCallback(
       name: refreshCookieName,
       value: refreshToken,
       path: refreshCookiePath,
+      sameSite: 'None',
+      partitioned: true,
       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
-  );
+  return c.json({ expires_at: expiresAt, return_path: returnPath });
 }