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

package/src/server/hono/hubspot-connect-routes/load-hubspot-connect-routes-env.test.ts

@@ -1,5 +1,9 @@
 import { afterEach, describe, expect, it, vi } from 'vitest';
 
+import {
+  getHubSpotAuthorizationEndpoint,
+  getHubSpotOAuthApiOrigin,
+} from '../../utils/env-utils.ts';
 import { loadHubSpotConnectRoutesEnv } from './load-hubspot-connect-routes-env.ts';
 
 const HUBSPOT_AUTHORIZATION_ENDPOINT_EXAMPLE =
@@ -19,29 +23,16 @@ describe('loadHubSpotConnectRoutesEnv', () => {
     vi.unstubAllEnvs();
   });
 
-  it('throws when HUBSPOT_AUTHORIZATION_ENDPOINT is missing', () => {
-    vi.stubEnv('HUBSPOT_OAUTH_API_ORIGIN', HUBSPOT_OAUTH_API_ORIGIN_EXAMPLE);
+  it('uses production URL defaults when OAuth endpoint vars are unset', () => {
     vi.stubEnv('HUBSPOT_CIMD_ENABLED', 'false');
     vi.stubEnv('HUBSPOT_DPOP_ENABLED', 'false');
-    vi.stubEnv('HUBSPOT_CLIENT_ID', 'cid');
-    vi.stubEnv('HUBSPOT_CLIENT_SECRET', 'sec');
-    expect(() => loadHubSpotConnectRoutesEnv()).toThrow(
-      'Missing required environment variable: HUBSPOT_AUTHORIZATION_ENDPOINT'
-    );
-  });
-
-  it('throws when HUBSPOT_OAUTH_API_ORIGIN is missing', () => {
-    vi.stubEnv(
-      'HUBSPOT_AUTHORIZATION_ENDPOINT',
-      HUBSPOT_AUTHORIZATION_ENDPOINT_EXAMPLE
-    );
-    vi.stubEnv('HUBSPOT_CIMD_ENABLED', 'false');
-    vi.stubEnv('HUBSPOT_DPOP_ENABLED', 'false');
-    vi.stubEnv('HUBSPOT_CLIENT_ID', 'cid');
-    vi.stubEnv('HUBSPOT_CLIENT_SECRET', 'sec');
-    expect(() => loadHubSpotConnectRoutesEnv()).toThrow(
-      'Missing required environment variable: HUBSPOT_OAUTH_API_ORIGIN'
+    vi.stubEnv('HUBSPOT_CLIENT_ID', 'my-id');
+    vi.stubEnv('HUBSPOT_CLIENT_SECRET', 'my-secret');
+    const env = loadHubSpotConnectRoutesEnv();
+    expect(env.hubspotAuthorizationEndpoint).toBe(
+      getHubSpotAuthorizationEndpoint()
     );
+    expect(env.hubspotOAuthApiOrigin).toBe(getHubSpotOAuthApiOrigin());
   });
 
   it('throws when CIMD is disabled and HUBSPOT_CLIENT_ID is missing', () => {
@@ -120,12 +111,14 @@ describe('loadHubSpotConnectRoutesEnv', () => {
     expect(loadHubSpotConnectRoutesEnv().isAppPrivateKeyRequired).toBe(true);
   });
 
-  it('sets isAppPrivateKeyRequired true when both are enabled by default', () => {
+  it('sets CIMD and DPoP disabled when both flags are unset', () => {
     stubHubSpotOAuthEndpoints();
+    vi.stubEnv('HUBSPOT_CLIENT_ID', 'id');
+    vi.stubEnv('HUBSPOT_CLIENT_SECRET', 'sec');
     const env = loadHubSpotConnectRoutesEnv();
-    expect(env.isCimdEnabled).toBe(true);
-    expect(env.isDpopEnabled).toBe(true);
-    expect(env.isAppPrivateKeyRequired).toBe(true);
+    expect(env.isCimdEnabled).toBe(false);
+    expect(env.isDpopEnabled).toBe(false);
+    expect(env.isAppPrivateKeyRequired).toBe(false);
   });
 
   it('normalizes HUBSPOT_OAUTH_API_ORIGIN to an origin URL', () => {

package/src/server/hono/hubspot-connect-routes/load-hubspot-connect-routes-env.ts

@@ -1,7 +1,10 @@
 import {
+  getHubSpotAuthorizationEndpoint,
+  getHubSpotOAuthApiOrigin,
   isHubspotCimdEnabled,
   isHubspotDpopEnabled,
-  requireEnv,
+  requireHubSpotClientId,
+  requireHubSpotClientSecret,
 } from '../../utils/env-utils.ts';
 
 /**
@@ -36,11 +39,8 @@ export interface HubSpotConnectRoutesEnvClientSecret {
  * {@link registerHubSpotConnectRoutes}.
  */
 export function loadHubSpotConnectRoutesEnv(): HubSpotConnectRoutesEnv {
-  const hubspotAuthorizationEndpoint = requireEnv(
-    'HUBSPOT_AUTHORIZATION_ENDPOINT'
-  );
-  const hubspotOAuthApiOrigin = new URL(requireEnv('HUBSPOT_OAUTH_API_ORIGIN'))
-    .origin;
+  const hubspotAuthorizationEndpoint = getHubSpotAuthorizationEndpoint();
+  const hubspotOAuthApiOrigin = getHubSpotOAuthApiOrigin();
   const isCimdEnabled = isHubspotCimdEnabled();
   const isDpopEnabled = isHubspotDpopEnabled();
   const isAppPrivateKeyRequired = isCimdEnabled || isDpopEnabled;
@@ -61,7 +61,7 @@ export function loadHubSpotConnectRoutesEnv(): HubSpotConnectRoutesEnv {
     isCimdEnabled: false,
     isDpopEnabled,
     isAppPrivateKeyRequired,
-    hubspotClientId: requireEnv('HUBSPOT_CLIENT_ID'),
-    hubspotClientSecret: requireEnv('HUBSPOT_CLIENT_SECRET'),
+    hubspotClientId: requireHubSpotClientId(),
+    hubspotClientSecret: requireHubSpotClientSecret(),
   };
 }

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

@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'vitest';
 
+import { OAUTH_CALLBACK_PATH } from '../../../shared/constants.ts';
 import {
   buildCimdClientIdUrlFromRequest,
   buildHubSpotAppJwksUrlFromRequest,
@@ -7,6 +8,9 @@ import {
   getRequestHostForHubspotConnect,
 } from './utils.ts';
 
+const APP_ORIGIN = 'https://third-party-app.test:5173';
+const APP_ORIGIN_QUERY = `app_origin=${encodeURIComponent(APP_ORIGIN)}`;
+
 describe('buildCimdClientIdUrlFromRequest', () => {
   it('builds client id URL under base path', () => {
     expect(
@@ -14,9 +18,10 @@ describe('buildCimdClientIdUrlFromRequest', () => {
         requestUrl:
           'https://third-party-app.test:5173/functions/v1/hubspot-connect/auth/init-session',
         basePath: '/functions/v1/hubspot-connect',
+        appOrigin: APP_ORIGIN,
       })
     ).toBe(
-      'https://third-party-app.test:5173/functions/v1/hubspot-connect/client.json'
+      `https://third-party-app.test:5173/functions/v1/hubspot-connect/client.json?${APP_ORIGIN_QUERY}`
     );
   });
 
@@ -28,9 +33,10 @@ describe('buildCimdClientIdUrlFromRequest', () => {
         basePath: '/functions/v1/hubspot-connect',
         xForwardedProto: 'https',
         xForwardedHost: 'third-party-app.test:5173',
+        appOrigin: APP_ORIGIN,
       })
     ).toBe(
-      'https://third-party-app.test:5173/functions/v1/hubspot-connect/client.json'
+      `https://third-party-app.test:5173/functions/v1/hubspot-connect/client.json?${APP_ORIGIN_QUERY}`
     );
   });
 });
@@ -42,6 +48,7 @@ describe('buildHubSpotAppJwksUrlFromRequest', () => {
         requestUrl:
           'https://third-party-app.test:5173/functions/v1/hubspot-connect/auth/init-session',
         basePath: '/functions/v1/hubspot-connect',
+        appOrigin: APP_ORIGIN,
       })
     ).toBe(
       'https://third-party-app.test:5173/functions/v1/hubspot-connect/jwks.json'
@@ -50,64 +57,27 @@ describe('buildHubSpotAppJwksUrlFromRequest', () => {
 });
 
 describe('buildOAuthRedirectUriFromRequest', () => {
-  it('builds callback URL from origin and base path', () => {
+  it('builds callback URL from app origin and frontend callback path', () => {
     expect(
       buildOAuthRedirectUriFromRequest({
         requestUrl:
           'https://third-party-app.test:5173/functions/v1/hubspot-connect/auth/init-session',
         basePath: '/functions/v1/hubspot-connect',
+        appOrigin: APP_ORIGIN,
       })
-    ).toBe(
-      'https://third-party-app.test:5173/functions/v1/hubspot-connect/auth/callback'
-    );
+    ).toBe(`${APP_ORIGIN}${OAUTH_CALLBACK_PATH}`);
   });
 
-  it('strips a trailing slash from basePath', () => {
+  it('ignores basePath and forwarded headers for redirect URI', () => {
     expect(
       buildOAuthRedirectUriFromRequest({
         requestUrl: 'https://example.com/x',
         basePath: '/functions/v1/hubspot-connect/',
-      })
-    ).toBe('https://example.com/functions/v1/hubspot-connect/auth/callback');
-  });
-
-  it('uses X-Forwarded-Proto and X-Forwarded-Host when present', () => {
-    expect(
-      buildOAuthRedirectUriFromRequest({
-        requestUrl:
-          'http://127.0.0.1:5175/functions/v1/hubspot-connect/auth/init-session',
-        basePath: '/functions/v1/hubspot-connect',
-        xForwardedProto: 'https',
-        xForwardedHost: 'third-party-app.test:5173',
-      })
-    ).toBe(
-      'https://third-party-app.test:5173/functions/v1/hubspot-connect/auth/callback'
-    );
-  });
-
-  it('uses X-Forwarded-Proto with Host header when X-Forwarded-Host is absent', () => {
-    expect(
-      buildOAuthRedirectUriFromRequest({
-        requestUrl:
-          'http://127.0.0.1:5175/functions/v1/hubspot-connect/auth/init-session',
-        basePath: '/functions/v1/hubspot-connect',
-        xForwardedProto: 'https',
-        requestHostHeader: 'third-party-app.test:5173',
-      })
-    ).toBe(
-      'https://third-party-app.test:5173/functions/v1/hubspot-connect/auth/callback'
-    );
-  });
-
-  it('uses X-Forwarded-Proto with request URL host when forwarded host and Host are absent', () => {
-    expect(
-      buildOAuthRedirectUriFromRequest({
-        requestUrl:
-          'http://127.0.0.1:5175/functions/v1/hubspot-connect/auth/init-session',
-        basePath: '/functions/v1/hubspot-connect',
         xForwardedProto: 'https',
+        xForwardedHost: 'other.example.com',
+        appOrigin: APP_ORIGIN,
       })
-    ).toBe('https://127.0.0.1:5175/functions/v1/hubspot-connect/auth/callback');
+    ).toBe(`${APP_ORIGIN}${OAUTH_CALLBACK_PATH}`);
   });
 });
 

package/src/server/hono/hubspot-connect-routes/utils.ts

@@ -1,3 +1,4 @@
+import { OAUTH_CALLBACK_PATH } from '../../../shared/constants.ts';
 import { serializeCookie } from '../utils/cookie-utils.ts';
 
 export function clearTempCookie(name: string): string {
@@ -5,11 +6,66 @@ export function clearTempCookie(name: string): string {
     name,
     value: '',
     path: '/',
-    sameSite: 'Lax',
+    sameSite: 'None',
     maxAge: 0,
+    partitioned: true,
   });
 }
 
+/**
+ * Parses the request `Origin` header into the canonical origin
+ * string (`URL.origin`) or returns `null` when the header is
+ * missing, malformed, or carries a scheme/host the SDK does not
+ * accept.
+ *
+ * Accepted shapes:
+ *
+ * - `https://<host>` for production deployments.
+ * - `http://localhost[:<port>]` and `http://127.0.0.1[:<port>]`
+ *   for local development; browsers exempt these from the `Secure`
+ *   cookie restriction.
+ *
+ * Rejects values with a path/query/hash component (the request
+ * `Origin` header is by spec a bare origin, so anything else
+ * indicates a malformed or hostile request).
+ */
+export function parseAppOriginHeader(
+  originHeader: string | undefined
+): string | null {
+  if (!originHeader) return null;
+  let parsed: URL;
+  try {
+    parsed = new URL(originHeader);
+  } catch {
+    return null;
+  }
+  if (parsed.pathname !== '/' && parsed.pathname !== '') return null;
+  if (parsed.search !== '' || parsed.hash !== '') return null;
+  if (parsed.protocol === 'https:') return parsed.origin;
+  if (
+    parsed.protocol === 'http:' &&
+    (parsed.hostname === 'localhost' || parsed.hostname === '127.0.0.1')
+  ) {
+    return parsed.origin;
+  }
+  return null;
+}
+
+/**
+ * OAuth `redirect_uri` for the cross-origin app shape: the OAuth
+ * callback lands on the **frontend** origin (not the SDK's edge
+ * function host), so all cookies set by `init-session` and read by
+ * `auth/complete` live in the same `(frontend, edge)` CHIPS
+ * partition.
+ *
+ * Used by `auth/init-session` (when building `authorization_url`)
+ * and `auth/complete` (which must rebuild the same value to satisfy
+ * the OAuth token endpoint's `redirect_uri` check).
+ */
+export function buildFrontendOAuthRedirectUri(appOrigin: string): string {
+  return `${appOrigin}${OAUTH_CALLBACK_PATH}`;
+}
+
 export function isSafeReturnPath(rawPath: string): boolean {
   if (!rawPath.startsWith('/')) return false;
   if (rawPath.includes('\0')) return false;
@@ -70,6 +126,7 @@ export interface BuildOAuthRedirectUriFromRequestOptions {
   xForwardedHost?: string | undefined;
   /** `Host` when `X-Forwarded-Host` is absent but `X-Forwarded-Proto` is set. */
   requestHostHeader?: string | undefined;
+  appOrigin: string;
 }
 
 function normalizeHubSpotConnectBasePath(basePath: string): string {
@@ -106,9 +163,8 @@ export function buildHubSpotConnectRequestOrigin(
 export function buildOAuthRedirectUriFromRequest(
   options: BuildOAuthRedirectUriFromRequestOptions
 ): string {
-  const trimmed = normalizeHubSpotConnectBasePath(options.basePath);
-  const origin = buildHubSpotConnectRequestOrigin(options);
-  return `${origin}${trimmed}/auth/callback`;
+  const { appOrigin } = options;
+  return `${appOrigin}${OAUTH_CALLBACK_PATH}`;
 }
 
 /**
@@ -119,7 +175,7 @@ export function buildCimdClientIdUrlFromRequest(
 ): string {
   const trimmed = normalizeHubSpotConnectBasePath(options.basePath);
   const origin = buildHubSpotConnectRequestOrigin(options);
-  return `${origin}${trimmed}/client.json`;
+  return `${origin}${trimmed}/client.json?app_origin=${encodeURIComponent(options.appOrigin)}`;
 }
 
 /**

package/src/server/hono/hubspot-connect-routes/whoami.ts

@@ -0,0 +1,74 @@
+import type { AuthCompleteWhoami } from '../../../shared/wire-types.ts';
+import {
+  account,
+  authOauth,
+  createHubSpotClient,
+  settingsUsers,
+} from '../../api-client-core/index.ts';
+import { fetchTransportPlugin } from '../../api-client-core/plugins/fetch-transport.ts';
+import { getHubSpotApiOrigin } from '../../utils/env-utils.ts';
+import type { HubSpotConnectRoutesEnv } from './load-hubspot-connect-routes-env.ts';
+
+export async function fetchWhoami(
+  accessToken: string,
+  hubspotConnectEnv: HubSpotConnectRoutesEnv
+): Promise<AuthCompleteWhoami> {
+  const apiClient = createHubSpotClient({
+    plugins: [
+      fetchTransportPlugin({
+        getEndpoint: getHubSpotApiOrigin,
+        getAccessToken: () => accessToken,
+      }),
+    ],
+  });
+
+  const introspectInput = hubspotConnectEnv.isCimdEnabled
+    ? { token: accessToken }
+    : {
+        client_id: hubspotConnectEnv.hubspotClientId,
+        client_secret: hubspotConnectEnv.hubspotClientSecret,
+        token: accessToken,
+      };
+
+  // Introspect and account.get are independent — run in parallel.
+  // settingsUsers.get requires user_id from introspect, so it runs after.
+  const [introspectResult, hubResult] = await Promise.allSettled([
+    apiClient.send(authOauth.introspectToken(introspectInput)),
+    apiClient.send(account.get()),
+  ]);
+
+  const whoami: AuthCompleteWhoami = {
+    hub: {},
+    user: {},
+  };
+
+  if (hubResult.status === 'fulfilled') {
+    const portal = hubResult.value;
+    whoami.hub.id = portal.portalId;
+    whoami.hub.uiDomain = portal.uiDomain;
+  }
+
+  if (
+    introspectResult.status === 'fulfilled' &&
+    introspectResult.value.token_use === 'access_token'
+  ) {
+    whoami.hub.domain = introspectResult.value.hub_domain;
+
+    const userId = String(introspectResult.value.user_id);
+    const userResult = await apiClient
+      .send(settingsUsers.get({ userId, idProperty: 'USER_ID' }))
+      .then(
+        (u) => ({ ok: true as const, value: u }),
+        () => ({ ok: false as const })
+      );
+    if (userResult.ok) {
+      const u = userResult.value;
+      whoami.user.id = u.id;
+      whoami.user.email = u.email;
+      whoami.user.firstName = u.firstName;
+      whoami.user.lastName = u.lastName;
+    }
+  }
+
+  return whoami;
+}

package/src/server/hono/types.ts

@@ -1,24 +1,25 @@
 import type { HubSpotClient } from '../api-client-core/types.ts';
-import type { HubSpotProxy } from '../types.ts';
 
-export interface AppConnectHonoBindings {
+export interface AppConnectRequestContext {
   /**
-   * Authenticated proxy that issues DPoP-bound calls to HubSpot's
-   * API on behalf of the browser session that made the inbound
-   * request. `authenticated: false` when the session cookies are
-   * absent or invalid.
+   * HubSpot API client.
    */
-  hubSpotProxy: HubSpotProxy;
+  client: HubSpotClient;
+
   /**
-   * Authenticated HubSpot API client.
+   * Whether the browser session is authenticated.
    */
-  hubSpotClient: HubSpotClient;
+  authenticated: boolean;
+}
+
+export interface AppConnectHonoBindings {
+  hubSpot: AppConnectRequestContext;
 }
 
 /**
  * Hono environment shape used by handlers running inside a hubspot-
  * connect request handler. Exposes the per-request
- * {@link HubSpotProxy} as `c.env.hubSpotProxy`.
+ * {@link AppConnectRequestContext} as `c.env.hubSpot`.
  */
 export interface AppConnectHonoEnv {
   Bindings: AppConnectHonoBindings;

package/src/server/hono/utils/cookie-utils.ts

@@ -20,14 +20,37 @@ export interface SerializeCookieOptions {
   value: string;
   /** `__Host-` prefix requires `Path=/` and is recommended for session cookies. */
   path: string;
-  /** Defaults to `Strict`. Use `Lax` for short-lived OAuth temp cookies. */
-  sameSite?: 'Strict' | 'Lax';
+  /**
+   * Defaults to `Strict`.
+   *
+   * - `Strict`: only sent on same-site requests. Default for self-hosted
+   *   same-origin deployments.
+   * - `Lax`: also sent on top-level cross-site GET navigations. Use for
+   *   short-lived OAuth temp cookies that need to survive a redirect.
+   * - `None`: sent on all cross-site requests; **requires `Secure=true`
+   *   and is typically combined with `Partitioned=true`** for the
+   *   cross-origin Lovable / Supabase deployment shape.
+   */
+  sameSite?: 'Strict' | 'Lax' | 'None';
   /** Lifetime in seconds. `0` deletes the cookie. */
   maxAge: number;
   /** Defaults to `true`; only set `false` for tests or non-HTTPS dev hosts. */
   secure?: boolean;
   /** Defaults to `true`. */
   httpOnly?: boolean;
+  /**
+   * When `true`, appends the `Partitioned` attribute (CHIPS — Cookies
+   * Having Independent Partitioned State). The browser then keys the
+   * cookie by `(top-level site, cookie host)` instead of by cookie
+   * host alone, which is required for the cross-origin SDK shape
+   * where the React app and the SDK's edge functions live on
+   * different sites and third-party cookies are blocked.
+   *
+   * Defaults to `false`. Browsers ignore `Partitioned` on cookies
+   * without `Secure=true` and reject it on cookies without
+   * `SameSite=None`.
+   */
+  partitioned?: boolean;
 }
 
 /**
@@ -44,6 +67,7 @@ export function serializeCookie(options: SerializeCookieOptions): string {
     maxAge,
     secure = true,
     httpOnly = true,
+    partitioned = false,
   } = options;
   const parts: string[] = [`${name}=${value}`];
   if (httpOnly) parts.push('HttpOnly');
@@ -51,5 +75,6 @@ export function serializeCookie(options: SerializeCookieOptions): string {
   parts.push(`SameSite=${sameSite}`);
   parts.push(`Path=${path}`);
   parts.push(`Max-Age=${maxAge}`);
+  if (partitioned) parts.push('Partitioned');
   return parts.join('; ');
 }

package/src/server/hono/utils/cors-middleware.test.ts

@@ -0,0 +1,80 @@
+import { Hono } from 'hono';
+import { describe, expect, it } from 'vitest';
+
+import { HUBSPOT_APP_ORIGIN_COOKIE_NAME } from '../../constants.ts';
+import { corsMiddleware } from './cors-middleware.ts';
+
+const APP_ORIGIN = 'https://app.example.com';
+const PINNED_ORIGIN = 'https://pinned.example.com';
+
+function buildApp(): Hono {
+  const app = new Hono();
+  app.use('*', corsMiddleware());
+  app.get('/echo', (c) => c.json({ ok: true }));
+  app.post('/echo', (c) => c.json({ ok: true }));
+  return app;
+}
+
+describe('corsMiddleware', () => {
+  it('answers OPTIONS preflight with 204 + credentialed CORS headers', async () => {
+    const app = buildApp();
+    const res = await app.request('http://localhost/echo', {
+      method: 'OPTIONS',
+      headers: { Origin: APP_ORIGIN },
+    });
+
+    expect(res.status).toBe(204);
+    expect(res.headers.get('Access-Control-Allow-Origin')).toBe(APP_ORIGIN);
+    expect(res.headers.get('Access-Control-Allow-Credentials')).toBe('true');
+    expect(res.headers.get('Access-Control-Allow-Methods')).toContain('GET');
+    expect(res.headers.get('Access-Control-Allow-Methods')).toContain('POST');
+    expect(res.headers.get('Access-Control-Allow-Methods')).toContain('DELETE');
+    expect(res.headers.get('Access-Control-Allow-Methods')).toContain(
+      'OPTIONS'
+    );
+    expect(res.headers.get('Access-Control-Allow-Headers')).toContain(
+      'authorization'
+    );
+    expect(res.headers.get('Access-Control-Allow-Headers')).toContain('apikey');
+    expect(res.headers.get('Access-Control-Max-Age')).toBe('600');
+    expect(res.headers.get('Vary')).toContain('Origin');
+  });
+
+  it('echoes the request Origin when no pinned origin cookie is present', async () => {
+    const app = buildApp();
+    const res = await app.request('http://localhost/echo', {
+      method: 'GET',
+      headers: { Origin: APP_ORIGIN },
+    });
+
+    expect(res.status).toBe(200);
+    expect(res.headers.get('Access-Control-Allow-Origin')).toBe(APP_ORIGIN);
+    expect(res.headers.get('Access-Control-Allow-Credentials')).toBe('true');
+    expect(res.headers.get('Vary')).toContain('Origin');
+    expect(res.headers.get('Vary')).toContain('Cookie');
+  });
+
+  it('prefers the pinned `__Host-hs_app_origin` cookie over the Origin header', async () => {
+    const app = buildApp();
+    const res = await app.request('http://localhost/echo', {
+      method: 'GET',
+      headers: {
+        Origin: APP_ORIGIN,
+        Cookie: `${HUBSPOT_APP_ORIGIN_COOKIE_NAME}=${PINNED_ORIGIN}`,
+      },
+    });
+
+    expect(res.status).toBe(200);
+    expect(res.headers.get('Access-Control-Allow-Origin')).toBe(PINNED_ORIGIN);
+    expect(res.headers.get('Access-Control-Allow-Credentials')).toBe('true');
+  });
+
+  it('omits CORS headers when the request has no Origin (server-to-server / curl)', async () => {
+    const app = buildApp();
+    const res = await app.request('http://localhost/echo', { method: 'GET' });
+
+    expect(res.status).toBe(200);
+    expect(res.headers.get('Access-Control-Allow-Origin')).toBeNull();
+    expect(res.headers.get('Access-Control-Allow-Credentials')).toBeNull();
+  });
+});

package/src/server/hono/utils/cors-middleware.ts

@@ -0,0 +1,95 @@
+import type { Context, MiddlewareHandler } from 'hono';
+
+import { HUBSPOT_APP_ORIGIN_COOKIE_NAME } from '../../constants.ts';
+import { parseCookies } from '../../utils/cookie-utils.ts';
+
+/**
+ * Comma-separated list of request headers the SDK accepts on
+ * cross-site fetches. Mirrors the Supabase Edge Functions defaults
+ * the Lovable AI agent emits today, plus `content-type` for the
+ * `auth/complete` POST body and `accept` so JSON content negotiation
+ * works.
+ */
+const ALLOWED_HEADERS = [
+  'authorization',
+  'x-client-info',
+  'apikey',
+  'content-type',
+  'accept',
+  'x-supabase-client-platform',
+  'x-supabase-client-platform-version',
+  'x-supabase-client-runtime',
+  'x-supabase-client-runtime-version',
+].join(', ');
+
+const ALLOWED_METHODS = 'GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS';
+
+const PREFLIGHT_MAX_AGE_SECONDS = '600';
+
+/**
+ * Reads the persisted app-origin cookie from the request, falling
+ * back to the literal `Origin` request header. The cookie is the
+ * authoritative pin once `auth/init-session` has run; on the very
+ * first init-session call (no cookie yet) we just echo whatever
+ * `Origin` the caller sent — the actual access decision is enforced
+ * by cookie-based authentication on every other route, not by CORS.
+ */
+function resolveAllowedOrigin(c: Context): string | null {
+  const cookies = parseCookies(c.req.header('Cookie'));
+  const pinned = cookies[HUBSPOT_APP_ORIGIN_COOKIE_NAME];
+  if (pinned) return pinned;
+  return c.req.header('Origin') ?? null;
+}
+
+function setSharedCorsHeaders(c: Context, allowOrigin: string): void {
+  c.res.headers.set('Access-Control-Allow-Origin', allowOrigin);
+  c.res.headers.set('Access-Control-Allow-Credentials', 'true');
+  // `Origin` so caches differentiate per-caller responses; `Cookie`
+  // because the allowed origin is derived from the persisted
+  // `__Host-hs_app_origin` cookie.
+  c.res.headers.set('Vary', 'Origin, Cookie');
+}
+
+/**
+ * Hono middleware that emits credentialed CORS response headers for
+ * the cross-origin Lovable / Supabase deployment shape.
+ *
+ * - On `OPTIONS` preflight: short-circuits with a 204 carrying
+ *   `Access-Control-Allow-*` headers. The browser will then send the
+ *   real request with cookies attached.
+ * - On every other method: echoes the pinned `__Host-hs_app_origin`
+ *   cookie value (or, before init-session has run, the request
+ *   `Origin` header) as `Access-Control-Allow-Origin`, with
+ *   `Access-Control-Allow-Credentials: true`. The wildcard `*` is
+ *   forbidden by browsers when credentials are included, so the
+ *   middleware always echoes a concrete origin.
+ *
+ * Skips header emission entirely when the request has no `Origin`
+ * (server-to-server calls, curl, etc.) so non-browser callers are
+ * left untouched.
+ */
+export function corsMiddleware(): MiddlewareHandler {
+  return async (c, next) => {
+    const allowOrigin = resolveAllowedOrigin(c);
+
+    if (c.req.method === 'OPTIONS') {
+      const headers = new Headers();
+      if (allowOrigin) {
+        headers.set('Access-Control-Allow-Origin', allowOrigin);
+        headers.set('Access-Control-Allow-Credentials', 'true');
+        headers.set('Vary', 'Origin, Cookie');
+      }
+      headers.set('Access-Control-Allow-Methods', ALLOWED_METHODS);
+      headers.set('Access-Control-Allow-Headers', ALLOWED_HEADERS);
+      headers.set('Access-Control-Max-Age', PREFLIGHT_MAX_AGE_SECONDS);
+      return new Response(null, { status: 204, headers });
+    }
+
+    await next();
+
+    if (allowOrigin) {
+      setSharedCorsHeaders(c, allowOrigin);
+    }
+    return;
+  };
+}