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

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

@@ -1,7 +1,9 @@
 import { Hono } from 'hono';
 import { describe, expect, it, vi } from 'vitest';
 
+import { HUBSPOT_FRONTEND_CALLBACK_PATH } from '../../../shared/constants.ts';
 import {
+  HUBSPOT_APP_ORIGIN_COOKIE_NAME,
   HUBSPOT_APP_SID_COOKIE_NAME,
   TEMP_COOKIE_OAUTH_STATE,
   TEMP_COOKIE_PKCE_VERIFIER,
@@ -21,6 +23,7 @@ const hubspotConnectEnv = {
 } satisfies HubSpotConnectRoutesEnvClientSecret;
 
 const BASE_PATH = '/functions/v1/hubspot-connect';
+const APP_ORIGIN = 'https://app.example.com';
 
 function buildOAuthRouteOptions(): HubSpotConnectOAuthRouteOptions {
   return {
@@ -38,60 +41,109 @@ function buildOAuthRouteOptions(): HubSpotConnectOAuthRouteOptions {
   };
 }
 
+function buildInitSessionRequest(options: {
+  returnPath?: string;
+  origin?: string | null;
+}): Request {
+  const url = new URL('http://localhost/auth/init-session');
+  if (options.returnPath !== undefined) {
+    url.searchParams.set('return_path', options.returnPath);
+  }
+  const headers = new Headers();
+  if (options.origin !== null && options.origin !== undefined) {
+    headers.set('Origin', options.origin);
+  }
+  return new Request(url.toString(), { method: 'GET', headers });
+}
+
 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' }
+    const res = await app.fetch(
+      buildInitSessionRequest({
+        returnPath: '//evil.example.com',
+        origin: APP_ORIGIN,
+      })
     );
     expect(res.status).toBe(400);
     expect(await res.text()).toContain('Invalid return_path');
   });
 
-  it('returns JSON with authorization_url on success', async () => {
+  it('returns 400 when the Origin header is missing', async () => {
+    const app = new Hono();
+    app.get('/auth/init-session', (c) =>
+      handleAuthInitSession(c, buildOAuthRouteOptions())
+    );
+    const res = await app.fetch(
+      buildInitSessionRequest({ returnPath: '/dashboard', origin: null })
+    );
+    expect(res.status).toBe(400);
+    expect(await res.text()).toContain('Origin');
+  });
+
+  it('returns 400 when the Origin header is not an https:// or localhost origin', 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' }
+    const res = await app.fetch(
+      buildInitSessionRequest({
+        returnPath: '/dashboard',
+        origin: 'http://evil.example.com',
+      })
+    );
+    expect(res.status).toBe(400);
+  });
+
+  it('builds the OAuth redirect_uri from the request Origin and the frontend callback path', async () => {
+    const app = new Hono();
+    app.get('/auth/init-session', (c) =>
+      handleAuthInitSession(c, buildOAuthRouteOptions())
+    );
+    const res = await app.fetch(
+      buildInitSessionRequest({ returnPath: '/dashboard', origin: APP_ORIGIN })
     );
 
     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'
+    expect(authUrl.searchParams.get('redirect_uri')).toBe(
+      `${APP_ORIGIN}${HUBSPOT_FRONTEND_CALLBACK_PATH}`
     );
   });
 
-  it('sets session, PKCE verifier, and state cookies', async () => {
+  it('pins the request Origin in `__Host-hs_app_origin` with SameSite=None; Partitioned', 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' }
+    const res = await app.fetch(
+      buildInitSessionRequest({ returnPath: '/dashboard', origin: APP_ORIGIN })
+    );
+    const setCookies = res.headers.getSetCookie();
+    const originCookie = setCookies.find((h) =>
+      h.startsWith(`${HUBSPOT_APP_ORIGIN_COOKIE_NAME}=`)
+    );
+    expect(originCookie).toBeDefined();
+    expect(originCookie).toContain(
+      `${HUBSPOT_APP_ORIGIN_COOKIE_NAME}=${APP_ORIGIN}`
     );
+    expect(originCookie).toContain('SameSite=None');
+    expect(originCookie).toContain('Secure');
+    expect(originCookie).toContain('Partitioned');
+  });
 
-    expect(res.status).toBe(200);
+  it('sets all session cookies with SameSite=None; Partitioned', async () => {
+    const app = new Hono();
+    app.get('/auth/init-session', (c) =>
+      handleAuthInitSession(c, buildOAuthRouteOptions())
+    );
+    const res = await app.fetch(
+      buildInitSessionRequest({ returnPath: '/dashboard', origin: APP_ORIGIN })
+    );
     const setCookies = res.headers.getSetCookie();
 
     const sidCookie = setCookies.find((h) =>
@@ -99,18 +151,50 @@ describe('handleAuthInitSession', () => {
     );
     expect(sidCookie).toBeDefined();
     expect(sidCookie).toContain('HttpOnly');
+    expect(sidCookie).toContain('SameSite=None');
+    expect(sidCookie).toContain('Partitioned');
 
     const pkceCookie = setCookies.find((h) =>
       h.startsWith(`${TEMP_COOKIE_PKCE_VERIFIER}=`)
     );
     expect(pkceCookie).toBeDefined();
-    expect(pkceCookie).toContain('SameSite=Lax');
+    expect(pkceCookie).toContain('SameSite=None');
+    expect(pkceCookie).toContain('Partitioned');
 
     const stateCookie = setCookies.find((h) =>
       h.startsWith(`${TEMP_COOKIE_OAUTH_STATE}=`)
     );
     expect(stateCookie).toBeDefined();
-    expect(stateCookie).toContain('SameSite=Lax');
+    expect(stateCookie).toContain('SameSite=None');
+    expect(stateCookie).toContain('Partitioned');
+  });
+
+  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.fetch(
+      buildInitSessionRequest({ returnPath: '/dashboard', origin: APP_ORIGIN })
+    );
+
+    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('defaults return_path to / when param is absent', async () => {
@@ -118,9 +202,9 @@ describe('handleAuthInitSession', () => {
     app.get('/auth/init-session', (c) =>
       handleAuthInitSession(c, buildOAuthRouteOptions())
     );
-    const res = await app.request('http://localhost/auth/init-session', {
-      method: 'GET',
-    });
+    const res = await app.fetch(
+      buildInitSessionRequest({ origin: APP_ORIGIN })
+    );
     expect(res.status).toBe(200);
     const body = (await res.json()) as { authorization_url: string };
     const state =

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

@@ -1,6 +1,7 @@
 import type { Context } from 'hono';
 
 import {
+  HUBSPOT_APP_ORIGIN_COOKIE_NAME,
   HUBSPOT_APP_SID_COOKIE_NAME,
   TEMP_COOKIE_OAUTH_STATE,
   TEMP_COOKIE_PKCE_VERIFIER,
@@ -13,8 +14,9 @@ import { deriveHubSpotAuthorizeScopesFromClientMetadata } from './fetch-hubspot-
 import type { HubSpotConnectOAuthRouteOptions } from './types.ts';
 import {
   buildCimdClientIdUrlFromRequest,
-  buildOAuthRedirectUriFromRequest,
+  buildFrontendOAuthRedirectUri,
   isSafeReturnPath,
+  parseAppOriginHeader,
 } from './utils.ts';
 
 export async function handleAuthInitSession(
@@ -31,6 +33,18 @@ export async function handleAuthInitSession(
     return c.text('Invalid return_path', 400);
   }
 
+  // The app origin pins the OAuth `redirect_uri` (which lands on the
+  // frontend, not on this edge function) and, via the persisted
+  // `__Host-hs_app_origin` cookie, drives credentialed
+  // `Access-Control-Allow-Origin` on every subsequent SDK response.
+  const appOrigin = parseAppOriginHeader(c.req.header('Origin'));
+  if (!appOrigin) {
+    return c.text(
+      'Missing or invalid Origin header; init-session must be called from a browser',
+      400
+    );
+  }
+
   const sessionIdBytes = new Uint8Array(32);
   crypto.getRandomValues(sessionIdBytes);
   const sessionId = base64url(sessionIdBytes);
@@ -60,13 +74,7 @@ export async function handleAuthInitSession(
       })
     : hubspotConnectEnv.hubspotClientId;
 
-  const redirectUri = buildOAuthRedirectUriFromRequest({
-    requestUrl: c.req.url,
-    basePath: options.basePath,
-    xForwardedProto,
-    xForwardedHost,
-    requestHostHeader,
-  });
+  const redirectUri = buildFrontendOAuthRedirectUri(appOrigin);
 
   const authorizeUrl = new URL(hubspotConnectEnv.hubspotAuthorizationEndpoint);
   authorizeUrl.searchParams.set('response_type', 'code');
@@ -92,12 +100,25 @@ export async function handleAuthInitSession(
     }
   }
 
+  setResponseCookie({
+    c,
+    value: serializeCookie({
+      name: HUBSPOT_APP_ORIGIN_COOKIE_NAME,
+      value: appOrigin,
+      path: '/',
+      sameSite: 'None',
+      partitioned: true,
+      maxAge: SESSION_MAX_AGE_SEC,
+    }),
+  });
   setResponseCookie({
     c,
     value: serializeCookie({
       name: HUBSPOT_APP_SID_COOKIE_NAME,
       value: sessionId,
       path: '/',
+      sameSite: 'None',
+      partitioned: true,
       maxAge: SESSION_MAX_AGE_SEC,
     }),
   });
@@ -107,7 +128,8 @@ export async function handleAuthInitSession(
       name: TEMP_COOKIE_PKCE_VERIFIER,
       value: encodeURIComponent(codeVerifier),
       path: '/',
-      sameSite: 'Lax',
+      sameSite: 'None',
+      partitioned: true,
       maxAge: OAUTH_TEMP_MAX_AGE_SEC,
     }),
   });
@@ -117,7 +139,8 @@ export async function handleAuthInitSession(
       name: TEMP_COOKIE_OAUTH_STATE,
       value: encodeURIComponent(stateValue),
       path: '/',
-      sameSite: 'Lax',
+      sameSite: 'None',
+      partitioned: true,
       maxAge: OAUTH_TEMP_MAX_AGE_SEC,
     }),
   });

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

@@ -4,6 +4,7 @@ import { afterEach, describe, expect, it, vi } from 'vitest';
 import type { Logger } from '../../../shared/logger.ts';
 import {
   HUBSPOT_ACCESS_TOKEN_COOKIE_NAME,
+  HUBSPOT_APP_ORIGIN_COOKIE_NAME,
   HUBSPOT_APP_SID_COOKIE_NAME,
 } from '../../constants.ts';
 import { handleAuthLogout } from './auth-logout.ts';
@@ -76,12 +77,24 @@ describe('handleAuthLogout', () => {
     );
     expect(accessCookie).toBeDefined();
     expect(accessCookie).toContain('Max-Age=0');
+    expect(accessCookie).toContain('SameSite=None');
+    expect(accessCookie).toContain('Partitioned');
 
     const sidCookie = setCookies.find((header) =>
       header.startsWith(`${HUBSPOT_APP_SID_COOKIE_NAME}=`)
     );
     expect(sidCookie).toBeDefined();
     expect(sidCookie).toContain('Max-Age=0');
+    expect(sidCookie).toContain('SameSite=None');
+    expect(sidCookie).toContain('Partitioned');
+
+    const originCookie = setCookies.find((header) =>
+      header.startsWith(`${HUBSPOT_APP_ORIGIN_COOKIE_NAME}=`)
+    );
+    expect(originCookie).toBeDefined();
+    expect(originCookie).toContain('Max-Age=0');
+    expect(originCookie).toContain('SameSite=None');
+    expect(originCookie).toContain('Partitioned');
   });
 
   it('clears cookies and logs a warning when revoke returns non-OK HTTP', async () => {

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

@@ -3,6 +3,7 @@ import type { Context } from 'hono';
 import type { Logger } from '../../../shared/logger.ts';
 import {
   HUBSPOT_ACCESS_TOKEN_COOKIE_NAME,
+  HUBSPOT_APP_ORIGIN_COOKIE_NAME,
   HUBSPOT_APP_SID_COOKIE_NAME,
   HUBSPOT_REFRESH_COOKIE_PREFIX,
 } from '../../constants.ts';
@@ -109,6 +110,8 @@ export async function handleAuthLogout(
       name: HUBSPOT_ACCESS_TOKEN_COOKIE_NAME,
       value: '',
       path: '/',
+      sameSite: 'None',
+      partitioned: true,
       maxAge: 0,
     }),
   });
@@ -118,6 +121,19 @@ export async function handleAuthLogout(
       name: HUBSPOT_APP_SID_COOKIE_NAME,
       value: '',
       path: '/',
+      sameSite: 'None',
+      partitioned: true,
+      maxAge: 0,
+    }),
+  });
+  setResponseCookie({
+    c,
+    value: serializeCookie({
+      name: HUBSPOT_APP_ORIGIN_COOKIE_NAME,
+      value: '',
+      path: '/',
+      sameSite: 'None',
+      partitioned: true,
       maxAge: 0,
     }),
   });
@@ -130,6 +146,8 @@ export async function handleAuthLogout(
           name: cookieName,
           value: '',
           path: refreshCookiePath,
+          sameSite: 'None',
+          partitioned: true,
           maxAge: 0,
         }),
       });

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

@@ -175,11 +175,15 @@ describe('handleAuthRefresh', () => {
       h.startsWith(`${HUBSPOT_ACCESS_TOKEN_COOKIE_NAME}=`)
     );
     expect(accessCookie).toContain('new-access-token');
+    expect(accessCookie).toContain('SameSite=None');
+    expect(accessCookie).toContain('Partitioned');
 
     const refreshCookie = setCookies.find((h) =>
       h.startsWith(`${refreshCookieName}=`)
     );
     expect(refreshCookie).toContain('new-refresh-token');
+    expect(refreshCookie).toContain('SameSite=None');
+    expect(refreshCookie).toContain('Partitioned');
   });
 
   it('clears stale refresh cookies on success', async () => {
@@ -220,5 +224,7 @@ describe('handleAuthRefresh', () => {
       h.startsWith(`${staleCookieName}=`)
     );
     expect(staleCleared).toContain('Max-Age=0');
+    expect(staleCleared).toContain('SameSite=None');
+    expect(staleCleared).toContain('Partitioned');
   });
 });

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

@@ -135,6 +135,8 @@ export async function handleAuthRefresh(
       name: HUBSPOT_ACCESS_TOKEN_COOKIE_NAME,
       value: newAccessToken,
       path: '/',
+      sameSite: 'None',
+      partitioned: true,
       maxAge: expires_in,
     }),
   });
@@ -144,6 +146,8 @@ export async function handleAuthRefresh(
       name: refreshCookieName,
       value: newRefreshToken,
       path: refreshCookiePath,
+      sameSite: 'None',
+      partitioned: true,
       maxAge: REFRESH_COOKIE_MAX_AGE_SEC,
     }),
   });
@@ -161,6 +165,8 @@ export async function handleAuthRefresh(
           name: cookieName,
           value: '',
           path: refreshCookiePath,
+          sameSite: 'None',
+          partitioned: true,
           maxAge: 0,
         }),
       });

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

@@ -2,7 +2,8 @@ import type { Hono } from 'hono';
 
 import { noopLogger, type Logger } from '../../../shared/logger.ts';
 import type { AppKeys } from '../../types.ts';
-import { handleAuthCallback } from './auth-callback.ts';
+import { corsMiddleware } from '../utils/cors-middleware.ts';
+import { handleAuthComplete } from './auth-complete.ts';
 import { handleAuthInitSession } from './auth-init-session.ts';
 import { handleAuthLogout } from './auth-logout.ts';
 import { handleAuthRefresh } from './auth-refresh.ts';
@@ -81,6 +82,12 @@ export function registerHubSpotConnectRoutes(
     cimdClientMetadata,
   };
 
+  // Credentialed CORS for the cross-origin Lovable / Supabase shape.
+  // Echoes the request `Origin` (or the pinned `__Host-hs_app_origin`
+  // cookie value once init-session has run) and short-circuits OPTIONS
+  // preflights with a 204 before any route handler runs.
+  app.use('*', corsMiddleware());
+
   app.get('/client.json', (c) => handleCimdClientJson(c, oauthRouteOptions));
   if (hubspotConnectEnv.isCimdEnabled) {
     app.get('/jwks.json', (c) => handleCimdAppJwks(c, oauthRouteOptions));
@@ -89,7 +96,7 @@ export function registerHubSpotConnectRoutes(
   app.get('/auth/init-session', (c) =>
     handleAuthInitSession(c, oauthRouteOptions)
   );
-  app.get('/auth/callback', (c) => handleAuthCallback(c, oauthRouteOptions));
+  app.post('/auth/complete', (c) => handleAuthComplete(c, oauthRouteOptions));
   app.post('/auth/refresh', (c) => handleAuthRefresh(c, oauthRouteOptions));
   app.post('/auth/logout', (c) => handleAuthLogout(c, oauthRouteOptions));
 }

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

@@ -1,3 +1,4 @@
+import { HUBSPOT_FRONTEND_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}${HUBSPOT_FRONTEND_CALLBACK_PATH}`;
+}
+
 export function isSafeReturnPath(rawPath: string): boolean {
   if (!rawPath.startsWith('/')) return false;
   if (rawPath.includes('\0')) return false;

package/src/server/hono/types.ts

@@ -1,24 +1,30 @@
 import type { HubSpotClient } from '../api-client-core/types.ts';
 import type { HubSpotProxy } from '../types.ts';
 
-export interface AppConnectHonoBindings {
+export interface AppConnectRequestContext {
+  /**
+   * HubSpot API proxy.
+   */
+  proxy: HubSpotProxy;
   /**
-   * 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('; ');
 }