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

package/src/server/lovable/create-app-function-start.ts

@@ -27,7 +27,7 @@ export type AppFunctionStart = (context: SecureStartContext) => Promise<void>;
 /**
  * Builds a Deno-style `start({ appKeys })` entry point that boots a
  * Hono app under `basePath`, wires the SDK's per-request HubSpot
- * proxy via `createAppConnectRequestHandler`, and serves it with
+ * client via `createAppConnectRequestHandler`, and serves it with
  * `Deno.serve` on `PORT`.
  */
 export function createAppFunctionStart(
@@ -35,8 +35,8 @@ export function createAppFunctionStart(
 ): AppFunctionStart {
   const { basePath, registerRoutes, logger } = options;
 
-  return ({ appKeys }) => {
-    Deno.serve(
+  return async ({ appKeys }) => {
+    const server = Deno.serve(
       serveOptions,
       createAppConnectRequestHandler({
         appKeys,
@@ -47,9 +47,6 @@ export function createAppFunctionStart(
       })
     );
 
-    console.log(
-      `[app-function ${basePath}] Listening on http://localhost:${PORT}`
-    );
-    return Promise.resolve();
+    await server.finished;
   };
 }

package/src/server/lovable/hubspot-connect/run-hubspot-connect-lovable-server.ts

@@ -8,33 +8,38 @@ import {
 } from '../../hono/index.ts';
 
 const PORT = Deno.env.get('PORT');
-const serveOptions =
-  typeof PORT === 'string' ? { port: parseInt(PORT, 10) } : {};
-const HUBSPOT_CONNECT_BASE_PATH = '/functions/v1/hubspot-connect';
+const port = typeof PORT === 'string' ? parseInt(PORT!, 10) : undefined;
+
+const PUBLIC_HUBSPOT_CONNECT_BASE_PATH = '/functions/v1/hubspot-connect';
 
 export interface RunHubSpotConnectLovableServerOptions extends SecureStartContext {
   cimdClientMetadata: HubSpotConnectCimdClientMetadata;
 }
 
-export function runHubSpotConnectLovableServer(
+export async function runHubSpotConnectLovableServer(
   options: RunHubSpotConnectLovableServerOptions
 ): Promise<void> {
   const { appKeys, cimdClientMetadata } = options;
   const hubspotConnectEnv = loadHubSpotConnectRoutesEnv();
-  const result = Deno.serve(serveOptions, (request) => {
-    const app = new Hono();
 
-    registerHubSpotConnectRoutes({
-      app: app.basePath(HUBSPOT_CONNECT_BASE_PATH),
-      appKeys,
-      basePath: HUBSPOT_CONNECT_BASE_PATH,
-      hubspotConnectEnv,
-      cimdClientMetadata,
-    });
+  const app = new Hono().basePath('/hubspot-connect');
 
-    return app.fetch(request);
+  registerHubSpotConnectRoutes({
+    app,
+    appKeys,
+    basePath: PUBLIC_HUBSPOT_CONNECT_BASE_PATH,
+    hubspotConnectEnv,
+    cimdClientMetadata,
   });
 
-  console.log(`[hubspot-connect] Listening on ${result.addr.port}`);
-  return Promise.resolve();
+  const serveHandler = (request: Request): Response | Promise<Response> => {
+    return app.fetch(request);
+  };
+
+  const server =
+    port !== undefined
+      ? Deno.serve({ port }, serveHandler)
+      : Deno.serve(serveHandler);
+
+  await server.finished;
 }

package/src/server/sanitize-request.ts

@@ -10,18 +10,12 @@ function serializeCookies(cookies: Map<string, string>): string {
 }
 
 /**
- * Returns a clone of `original` whose `Cookie` header has every
- * protected cookie removed (see
- * {@link isProtectedCookieName}). When no other cookies
- * remain, the header is dropped entirely.
- *
- * Used by `createAppConnectRequestHandler` so the user's route
- * handlers never see — and therefore cannot leak — the access token,
- * session ID, or refresh-token cookies.
+ * Mutates `headers` in place: parses the `Cookie` header, drops every
+ * protected cookie (see {@link isProtectedCookieName}), and rewrites
+ * the header. Deletes the header entirely when nothing survives.
  */
-export function sanitizeRequest(original: Request): Request {
-  const cookies = parseCookies(original.headers.get('Cookie'));
-
+function stripProtectedCookies(headers: Headers): void {
+  const cookies = parseCookies(headers.get('Cookie'));
   const surviving = new Map<string, string>();
   for (const [name, value] of Object.entries(cookies)) {
     if (!isProtectedCookieName(name)) {
@@ -29,12 +23,21 @@ export function sanitizeRequest(original: Request): Request {
     }
   }
 
-  const headers = new Headers(original.headers);
   if (surviving.size === 0) {
     headers.delete('cookie');
   } else {
     headers.set('cookie', serializeCookies(surviving));
   }
+}
+
+/**
+ * Returns a clone of `original` whose `Cookie` header has every
+ * protected cookie removed (see {@link isProtectedCookieName}). When
+ * no other cookies remain, the header is dropped entirely.
+ */
+export function sanitizeRequest(original: Request): Request {
+  const headers = new Headers(original.headers);
+  stripProtectedCookies(headers);
 
   const init: RequestInit = {
     method: original.method,

package/src/server/secure-start-core.ts

@@ -1,6 +1,9 @@
 import { importAppKeys } from './import-app-keys.ts';
 import type { AppKeys } from './types.ts';
-import { isHubspotAppPrivateKeyRequired } from './utils/env-utils.ts';
+import {
+  HUBSPOT_APP_PRIVATE_KEY_ENV,
+  isHubspotAppPrivateKeyRequired,
+} from './utils/env-utils.ts';
 
 /**
  * Context passed to a function-style entrypoint loaded by `runSecureStart`.
@@ -36,8 +39,6 @@ export interface SecureStartAdapter {
   exit: (code: number) => never;
 }
 
-const APP_PRIVATE_KEY_ENV = 'HUBSPOT_APP_PRIVATE_KEY';
-
 /**
  * Loads `HUBSPOT_APP_PRIVATE_KEY` when CIMD or DPoP is enabled, deletes
  * it from the environment so later code cannot re-read it, imports the
@@ -51,12 +52,12 @@ export async function runSecureStart(
 ): Promise<void> {
   let appKeys: AppKeys | null = null;
   if (isHubspotAppPrivateKeyRequired()) {
-    const envKey = adapter.readEnv(APP_PRIVATE_KEY_ENV)?.trim();
+    const envKey = adapter.readEnv(HUBSPOT_APP_PRIVATE_KEY_ENV)?.trim();
     if (!envKey) {
-      throw new Error(`${APP_PRIVATE_KEY_ENV} is not set`);
+      throw new Error(`${HUBSPOT_APP_PRIVATE_KEY_ENV} is not set`);
     }
     appKeys = await importAppKeys(envKey);
-    adapter.deleteEnv(APP_PRIVATE_KEY_ENV);
+    adapter.deleteEnv(HUBSPOT_APP_PRIVATE_KEY_ENV);
   }
 
   const exports = await loader();

package/src/server/types.ts

@@ -10,42 +10,6 @@ export interface AppKeys {
   appPublicKeyJwk: JsonWebKey;
 }
 
-/**
- * Request shape accepted by `HubSpotProxy.fetch`. Only the `path`
- * is required; everything else mirrors the equivalent fetch fields.
- */
-export interface HubSpotProxyRequest {
-  /** Path component of the upstream URL, including leading slash. */
-  path: string;
-  /** HTTP method. Defaults to `GET`. */
-  method?: string;
-  /**
-   * Extra request headers. The proxy adds `Authorization` itself
-   * (`DPoP` access token plus `DPoP` proof when `HUBSPOT_DPOP_ENABLED` is
-   * not `"false"` and `appKeys` is non-null; otherwise `Bearer` only).
-   */
-  headers?: Record<string, string>;
-  /** Optional request body. Pass `null`/`undefined` for empty bodies. */
-  body?: string | null | undefined;
-}
-
-/**
- * Authenticated proxy returned by `createHubSpotProxy`. Use it
- * inside Hono handlers (via `c.env.hubSpotProxy`) to call
- * HubSpot's API on behalf of the browser session that issued the
- * incoming request.
- */
-export interface HubSpotProxy {
-  /**
-   * `true` when the session cookies present on the inbound request
-   * yielded a usable access token. When `false`, every `fetch()` call
-   * returns a 401 without contacting the upstream.
-   */
-  authenticated: boolean;
-  /** Performs an authenticated upstream request. */
-  fetch: (request: HubSpotProxyRequest) => Promise<Response>;
-}
-
 /**
  * RFC 7517 JWK Set. Returned by HubSpot's `/oauth/v1/jwks` endpoint
  * and used to verify access tokens on the resource server.
@@ -56,7 +20,7 @@ export interface JwkSet {
 
 export interface UserCredentials {
   /** Access token. */
-  accessToken: string;
+  accessToken: string | undefined;
   /** Session ID. */
-  sessionId: string;
+  sessionId: string | undefined;
 }

package/src/server/utils/env-utils.test.ts

@@ -1,19 +1,143 @@
 import { afterEach, describe, expect, it, vi } from 'vitest';
 
 import {
+  getEnvWithDefault,
+  getHubSpotApiOrigin,
+  getHubSpotAuthorizationEndpoint,
+  getHubSpotOAuthApiOrigin,
   isHubspotAppPrivateKeyRequired,
   isHubspotCimdEnabled,
   isHubspotDpopEnabled,
+  requireHubSpotClientId,
+  requireHubSpotClientSecret,
 } from './env-utils.ts';
 
+describe('getEnvWithDefault', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it('returns defaultValue when the variable is unset', () => {
+    expect(getEnvWithDefault('CUSTOM_VAR', 'default')).toBe('default');
+  });
+
+  it('returns defaultValue when the variable is an empty string', () => {
+    vi.stubEnv('CUSTOM_VAR', '');
+    expect(getEnvWithDefault('CUSTOM_VAR', 'default')).toBe('default');
+  });
+
+  it('returns the explicit value when set', () => {
+    vi.stubEnv('CUSTOM_VAR', 'explicit');
+    expect(getEnvWithDefault('CUSTOM_VAR', 'default')).toBe('explicit');
+  });
+});
+
+describe('getHubSpotApiOrigin', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it('returns production default when unset', () => {
+    expect(getHubSpotApiOrigin()).toBe('https://api.hubapi.com');
+  });
+
+  it('returns production default when empty string', () => {
+    vi.stubEnv('HUBSPOT_API_ORIGIN', '');
+    expect(getHubSpotApiOrigin()).toBe('https://api.hubapi.com');
+  });
+
+  it('returns the explicit value when set', () => {
+    vi.stubEnv('HUBSPOT_API_ORIGIN', 'https://custom.example.test');
+    expect(getHubSpotApiOrigin()).toBe('https://custom.example.test');
+  });
+});
+
+describe('getHubSpotAuthorizationEndpoint', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it('returns production default when unset', () => {
+    expect(getHubSpotAuthorizationEndpoint()).toBe(
+      'https://app.hubspot.com/oauth/authorize'
+    );
+  });
+
+  it('returns the explicit value when set', () => {
+    vi.stubEnv(
+      'HUBSPOT_AUTHORIZATION_ENDPOINT',
+      'https://auth.example.test/oauth/authorize'
+    );
+    expect(getHubSpotAuthorizationEndpoint()).toBe(
+      'https://auth.example.test/oauth/authorize'
+    );
+  });
+});
+
+describe('getHubSpotOAuthApiOrigin', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it('returns production default when unset', () => {
+    expect(getHubSpotOAuthApiOrigin()).toBe('https://api.hubapi.com');
+  });
+
+  it('normalizes a URL with path segments to an origin', () => {
+    vi.stubEnv(
+      'HUBSPOT_OAUTH_API_ORIGIN',
+      'https://api.hubapi.com/extra/path/'
+    );
+    expect(getHubSpotOAuthApiOrigin()).toBe('https://api.hubapi.com');
+  });
+});
+
+describe('requireHubSpotClientId', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it('throws when HUBSPOT_CLIENT_ID is missing', () => {
+    expect(() => requireHubSpotClientId()).toThrow(
+      'Missing required environment variable: HUBSPOT_CLIENT_ID'
+    );
+  });
+
+  it('returns the value when set', () => {
+    vi.stubEnv('HUBSPOT_CLIENT_ID', 'my-id');
+    expect(requireHubSpotClientId()).toBe('my-id');
+  });
+});
+
+describe('requireHubSpotClientSecret', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it('throws when HUBSPOT_CLIENT_SECRET is missing', () => {
+    expect(() => requireHubSpotClientSecret()).toThrow(
+      'Missing required environment variable: HUBSPOT_CLIENT_SECRET'
+    );
+  });
+
+  it('returns the value when set', () => {
+    vi.stubEnv('HUBSPOT_CLIENT_SECRET', 'my-secret');
+    expect(requireHubSpotClientSecret()).toBe('my-secret');
+  });
+});
+
 describe('isHubspotCimdEnabled', () => {
   afterEach(() => {
     vi.unstubAllEnvs();
   });
 
-  it('returns true when HUBSPOT_CIMD_ENABLED is empty string', () => {
+  it('returns false when HUBSPOT_CIMD_ENABLED is unset', () => {
+    expect(isHubspotCimdEnabled()).toBe(false);
+  });
+
+  it('returns false when HUBSPOT_CIMD_ENABLED is empty string', () => {
     vi.stubEnv('HUBSPOT_CIMD_ENABLED', '');
-    expect(isHubspotCimdEnabled()).toBe(true);
+    expect(isHubspotCimdEnabled()).toBe(false);
   });
 
   it('returns false when HUBSPOT_CIMD_ENABLED is exactly false', () => {
@@ -26,9 +150,9 @@ describe('isHubspotCimdEnabled', () => {
     expect(isHubspotCimdEnabled()).toBe(true);
   });
 
-  it('returns true for other non-false strings', () => {
+  it('returns false for other non-true strings', () => {
     vi.stubEnv('HUBSPOT_CIMD_ENABLED', '0');
-    expect(isHubspotCimdEnabled()).toBe(true);
+    expect(isHubspotCimdEnabled()).toBe(false);
   });
 });
 
@@ -55,8 +179,8 @@ describe('isHubspotAppPrivateKeyRequired', () => {
     expect(isHubspotAppPrivateKeyRequired()).toBe(true);
   });
 
-  it('returns true when both are enabled by default (unset)', () => {
-    expect(isHubspotAppPrivateKeyRequired()).toBe(true);
+  it('returns false when both are disabled by default (unset)', () => {
+    expect(isHubspotAppPrivateKeyRequired()).toBe(false);
   });
 });
 
@@ -65,9 +189,13 @@ describe('isHubspotDpopEnabled', () => {
     vi.unstubAllEnvs();
   });
 
-  it('returns true when HUBSPOT_DPOP_ENABLED is empty string', () => {
+  it('returns false when HUBSPOT_DPOP_ENABLED is unset', () => {
+    expect(isHubspotDpopEnabled()).toBe(false);
+  });
+
+  it('returns false when HUBSPOT_DPOP_ENABLED is empty string', () => {
     vi.stubEnv('HUBSPOT_DPOP_ENABLED', '');
-    expect(isHubspotDpopEnabled()).toBe(true);
+    expect(isHubspotDpopEnabled()).toBe(false);
   });
 
   it('returns false when HUBSPOT_DPOP_ENABLED is exactly false', () => {
@@ -80,13 +208,13 @@ describe('isHubspotDpopEnabled', () => {
     expect(isHubspotDpopEnabled()).toBe(true);
   });
 
-  it('returns true for other non-false strings', () => {
+  it('returns false for other non-true strings', () => {
     vi.stubEnv('HUBSPOT_DPOP_ENABLED', '0');
-    expect(isHubspotDpopEnabled()).toBe(true);
+    expect(isHubspotDpopEnabled()).toBe(false);
   });
 
-  it('returns true for False with different casing', () => {
+  it('returns false for False with different casing', () => {
     vi.stubEnv('HUBSPOT_DPOP_ENABLED', 'False');
-    expect(isHubspotDpopEnabled()).toBe(true);
+    expect(isHubspotDpopEnabled()).toBe(false);
   });
 });

package/src/server/utils/env-utils.ts

@@ -3,6 +3,16 @@ interface GlobalWithOptionalEnv {
   Deno?: { env: { get(name: string): string | undefined } };
 }
 
+const HUBSPOT_API_ORIGIN_DEFAULT = 'https://api.hubapi.com';
+
+const HUBSPOT_OAUTH_API_ORIGIN_DEFAULT = 'https://api.hubapi.com';
+
+const HUBSPOT_AUTHORIZATION_ENDPOINT_DEFAULT =
+  'https://app.hubspot.com/oauth/authorize';
+
+/** Environment variable name for the app private key loaded by `secureStart`. */
+export const HUBSPOT_APP_PRIVATE_KEY_ENV = 'HUBSPOT_APP_PRIVATE_KEY';
+
 /**
  * Reads an environment variable in a way that works under both Node
  * (`process.env`) and Deno (`Deno.env.get`). Returns `undefined` when
@@ -21,6 +31,18 @@ export function getEnv(key: string): string | undefined {
   return undefined;
 }
 
+/**
+ * Reads an environment variable, returning `defaultValue` when it is
+ * unset or an empty string.
+ */
+export function getEnvWithDefault(key: string, defaultValue: string): string {
+  const value = getEnv(key);
+  if (!value) {
+    return defaultValue;
+  }
+  return value;
+}
+
 /**
  * Reads an environment variable and throws when it is missing or empty.
  * Use for values the SDK cannot fall back on (e.g. upstream service
@@ -37,22 +59,74 @@ export function requireEnv(key: string): string {
   return value;
 }
 
+/**
+ * HubSpot API origin used by the HubSpot API client transport. Defaults to
+ * `https://api.hubapi.com` when `HUBSPOT_API_ORIGIN` is unset.
+ */
+export function getHubSpotApiOrigin(): string {
+  return getEnvWithDefault('HUBSPOT_API_ORIGIN', HUBSPOT_API_ORIGIN_DEFAULT);
+}
+
+/**
+ * Full OAuth authorize URL for hubspot-connect routes. Defaults to
+ * `https://app.hubspot.com/oauth/authorize` when
+ * `HUBSPOT_AUTHORIZATION_ENDPOINT` is unset.
+ */
+export function getHubSpotAuthorizationEndpoint(): string {
+  return getEnvWithDefault(
+    'HUBSPOT_AUTHORIZATION_ENDPOINT',
+    HUBSPOT_AUTHORIZATION_ENDPOINT_DEFAULT
+  );
+}
+
+/**
+ * HubSpot OAuth API origin (token, revoke, JWKS). Normalized to a URL
+ * origin. Defaults to `https://api.hubapi.com` when
+ * `HUBSPOT_OAUTH_API_ORIGIN` is unset.
+ */
+export function getHubSpotOAuthApiOrigin(): string {
+  return new URL(
+    getEnvWithDefault(
+      'HUBSPOT_OAUTH_API_ORIGIN',
+      HUBSPOT_OAUTH_API_ORIGIN_DEFAULT
+    )
+  ).origin;
+}
+
+/**
+ * Static OAuth client ID. Required when CIMD is disabled.
+ *
+ * @throws {Error} When `HUBSPOT_CLIENT_ID` is unset or empty.
+ */
+export function requireHubSpotClientId(): string {
+  return requireEnv('HUBSPOT_CLIENT_ID');
+}
+
+/**
+ * Static OAuth client secret. Required when CIMD is disabled.
+ *
+ * @throws {Error} When `HUBSPOT_CLIENT_SECRET` is unset or empty.
+ */
+export function requireHubSpotClientSecret(): string {
+  return requireEnv('HUBSPOT_CLIENT_SECRET');
+}
+
 /**
  * Whether outbound HubSpot OAuth and API calls should attach DPoP on
- * the wire. Disabled only when `HUBSPOT_DPOP_ENABLED` is exactly the
- * string `"false"` (unset or any other value keeps DPoP enabled).
+ * the wire. Enabled only when `HUBSPOT_DPOP_ENABLED` is exactly the
+ * string `"true"` (unset or any other value keeps DPoP disabled).
  */
 export function isHubspotDpopEnabled(): boolean {
-  return getEnv('HUBSPOT_DPOP_ENABLED') !== 'false';
+  return getEnv('HUBSPOT_DPOP_ENABLED') === 'true';
 }
 
 /**
  * Whether the SDK should use CIMD-style OAuth (client ID URL + JWT client
- * assertion). Disabled only when `HUBSPOT_CIMD_ENABLED` is exactly the
- * string `"false"` (unset or any other value keeps CIMD enabled).
+ * assertion). Enabled only when `HUBSPOT_CIMD_ENABLED` is exactly the
+ * string `"true"` (unset or any other value keeps CIMD disabled).
  */
 export function isHubspotCimdEnabled(): boolean {
-  return getEnv('HUBSPOT_CIMD_ENABLED') !== 'false';
+  return getEnv('HUBSPOT_CIMD_ENABLED') === 'true';
 }
 
 /**

package/src/server/utils/hubspot-dpop-auth-headers.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+
+import { sha256base64url } from './crypto-utils.ts';
+import { verifyDpopProof } from './dpop-utils.ts';
+import { buildHubSpotDpopAuthHeaders } from './hubspot-dpop-auth-headers.ts';
+import { createTestAppKeys } from './test-fixtures.ts';
+
+describe('buildHubSpotDpopAuthHeaders', () => {
+  it('returns DPoP authorization headers with a signed proof', async () => {
+    const appKeys = await createTestAppKeys();
+    const headers = await buildHubSpotDpopAuthHeaders({
+      accessToken: 'tok',
+      sessionId: 'sid',
+      appKeys,
+      method: 'GET',
+      targetUrl: 'https://api.example.test/x',
+    });
+
+    expect(headers.Authorization).toBe('DPoP tok');
+    expect(headers.DPoP).toBeDefined();
+  });
+
+  it('strips query string parameters from the htu claim', async () => {
+    const appKeys = await createTestAppKeys();
+    const headers = await buildHubSpotDpopAuthHeaders({
+      accessToken: 'tok',
+      sessionId: 'sid',
+      appKeys,
+      method: 'GET',
+      targetUrl: 'https://api.example.test/x?limit=10&properties=email',
+    });
+
+    await expect(
+      verifyDpopProof({
+        proof: headers.DPoP!,
+        htm: 'GET',
+        htu: 'https://api.example.test/x',
+        ath: await sha256base64url('tok'),
+        sid: await sha256base64url('sid'),
+      })
+    ).resolves.toBeDefined();
+  });
+});

package/src/server/utils/hubspot-dpop-auth-headers.ts

@@ -0,0 +1,48 @@
+import { type AppKeys } from '../types.ts';
+import { sha256base64url } from './crypto-utils.ts';
+import { signDpopProof } from './dpop-utils.ts';
+
+export interface BuildHubSpotDpopAuthHeadersOptions {
+  accessToken: string;
+  sessionId: string;
+  appKeys: AppKeys;
+  method: string;
+  targetUrl: string;
+}
+
+function getDpopHtuFromTargetUrl(targetUrl: string): string {
+  const url = new URL(targetUrl);
+  url.search = '';
+  url.hash = '';
+  return url.toString();
+}
+
+/**
+ * Builds `Authorization` and `DPoP` headers for an authenticated
+ * HubSpot API request when DPoP is enabled.
+ */
+export async function buildHubSpotDpopAuthHeaders(
+  options: BuildHubSpotDpopAuthHeadersOptions
+): Promise<Record<string, string>> {
+  const { accessToken, sessionId, appKeys, method, targetUrl } = options;
+  const htu = getDpopHtuFromTargetUrl(targetUrl);
+
+  const ath = await sha256base64url(accessToken);
+  const sid = await sha256base64url(sessionId);
+  const dpopProof = await signDpopProof({
+    appKeys,
+    claims: {
+      htm: method,
+      htu,
+      jti: crypto.randomUUID(),
+      iat: Math.floor(Date.now() / 1000),
+      ath,
+      sid,
+    },
+  });
+
+  return {
+    Authorization: `DPoP ${accessToken}`,
+    DPoP: dpopProof,
+  };
+}

package/src/shared/constants.ts

@@ -6,8 +6,45 @@
 
 /**
  * Query parameter on the OAuth return URL that carries the new access
- * token's expiry (Unix epoch milliseconds). The server emits this on
- * the `auth/callback` redirect; the browser parses it during `initSdk`
- * and then strips it from the URL via `history.replaceState`.
+ * token's expiry (Unix epoch milliseconds). The browser controller
+ * sets this in the URL after a successful `auth/complete` call and
+ * then strips it during `initAppConnect` via `history.replaceState`.
  */
 export const EXPIRES_AT_URL_PARAM = '__hs_expires_at';
+
+/**
+ * Path the browser visits after HubSpot's authorize endpoint
+ * redirects back to the app. Mounted on the **frontend** origin (not
+ * the SDK's edge function host) so all OAuth-related cookies live in
+ * the `(frontend, edge)` CHIPS partition.
+ *
+ * The SDK's `auth/init-session` builds the OAuth `redirect_uri` as
+ * `${requestOrigin}${HUBSPOT_FRONTEND_CALLBACK_PATH}`. The browser
+ * controller, on `start()`, recognizes this path on `window.location`
+ * and forwards `?code` + `?state` to the SDK's `auth/complete`
+ * endpoint via a credentialed cross-site fetch. The host app must
+ * register `${app_origin}${HUBSPOT_FRONTEND_CALLBACK_PATH}` as a
+ * redirect URI in its HubSpot app settings.
+ */
+export const OAUTH_CALLBACK_PATH = '/__hubspot_oauth_callback';
+
+/**
+ * Query parameter on the `auth/complete` POST request carrying the
+ * authorization `code` HubSpot returned to the frontend callback.
+ */
+export const AUTH_COMPLETE_CODE_PARAM = 'code';
+
+/**
+ * Query parameter on the `auth/complete` POST request carrying the
+ * OAuth `state` HubSpot echoed back to the frontend callback.
+ */
+export const AUTH_COMPLETE_STATE_PARAM = 'state';
+
+/**
+ * `postMessage` `data.type` value the OAuth popup sends to its opener
+ * with the authorization `code` and `state` from the callback URL. The
+ * opener POSTs them to `auth/complete` so credentialed cookies stay in
+ * the same CHIPS partition as `auth/init-session`.
+ */
+export const OAUTH_POPUP_CALLBACK_MESSAGE_TYPE =
+  'hubspot-app-connect:oauth-callback';