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

package/dist/server/sha256-B7y8GBFB.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sha256-B7y8GBFB.js","names":[],"sources":["../../src/shared/encoding/base64.ts","../../src/server/utils/jwk-utils.ts","../../src/server/utils/jwt-utils.ts","../../src/server/utils/dpop-utils.ts","../../src/shared/encoding/sha256.ts"],"sourcesContent":["/**\n * Base64url encoding and decoding helpers shared by the browser and\n * server halves of `@hubspot/app-connect-sdk`.\n *\n * Base64url (RFC 4648 §5) replaces `+`/`/` with `-`/`_` and drops `=`\n * padding. JWT, DPoP, and JWK thumbprints all use this variant.\n */\n\n/**\n * Encodes a binary buffer as a base64url string (RFC 4648 §5).\n */\nexport function base64url(input: ArrayBuffer | Uint8Array): string {\n  const bytes = input instanceof Uint8Array ? input : new Uint8Array(input);\n  let binary = '';\n  for (const byte of bytes) {\n    binary += String.fromCharCode(byte);\n  }\n  return btoa(binary).replace(/\\+/g, '-').replace(/\\//g, '_').replace(/=/g, '');\n}\n\n/**\n * Decodes a base64url string into a `Uint8Array`. Tolerates missing\n * padding by re-adding it before delegating to `atob`.\n */\nexport function base64urlDecode(encoded: string): Uint8Array<ArrayBuffer> {\n  const padLen = (4 - (encoded.length % 4)) % 4;\n  const padded =\n    encoded.replace(/-/g, '+').replace(/_/g, '/') + '='.repeat(padLen);\n  const binary = atob(padded);\n  const out = new Uint8Array(new ArrayBuffer(binary.length));\n  for (let i = 0; i < binary.length; i++) {\n    out[i] = binary.charCodeAt(i) ?? 0;\n  }\n  return out;\n}\n\n/**\n * Decodes a *standard* base64 string (with `+`/`/` and required `=`\n * padding) into an `ArrayBuffer`. Used for PKCS8-encoded private keys\n * stored in environment variables.\n */\nexport function base64StandardToArrayBuffer(b64: string): ArrayBuffer {\n  const bin = atob(b64);\n  const buf = new ArrayBuffer(bin.length);\n  const view = new Uint8Array(buf);\n  for (let i = 0; i < bin.length; i++) {\n    view[i] = bin.charCodeAt(i) ?? 0;\n  }\n  return buf;\n}\n","import { base64url } from './base64-utils.ts';\n\nexport interface GetJwkThumbprintOptions {\n  /** EC P-256 public JWK whose thumbprint to compute. */\n  publicKeyJwk: JsonWebKey;\n}\n\n/**\n * Computes the RFC 7638 JWK thumbprint of an EC P-256 public JWK.\n * Per §3.2 the canonical form contains only `crv`, `kty`, `x`, `y`,\n * sorted lexicographically — no whitespace, no other members. The\n * SHA-256 of this canonical UTF-8 JSON, base64url-encoded, is the\n * stable identifier (`jkt`) DPoP uses to bind tokens to public keys.\n */\nexport async function getJwkThumbprint(\n  options: GetJwkThumbprintOptions\n): Promise<string> {\n  const { publicKeyJwk } = options;\n  const canonical = JSON.stringify({\n    crv: publicKeyJwk.crv,\n    kty: publicKeyJwk.kty,\n    x: publicKeyJwk.x,\n    y: publicKeyJwk.y,\n  });\n  const digest = await crypto.subtle.digest(\n    'SHA-256',\n    new TextEncoder().encode(canonical)\n  );\n  return base64url(new Uint8Array(digest));\n}\n","import { base64url, base64urlDecode } from './base64-utils.ts';\n\ninterface EncodeAndSignJwtOptions {\n  header: Record<string, unknown>;\n  payload: Record<string, unknown>;\n  privateKey: CryptoKey;\n}\n\n/**\n * Low-level helper that encodes a JWS Compact Serialization JWT\n * (RFC 7519) and signs it with the supplied `privateKey` using\n * ES256 (P-256 + SHA-256). Returns the three-segment compact form.\n */\nexport async function encodeAndSignJwt(\n  options: EncodeAndSignJwtOptions\n): Promise<string> {\n  const { header, payload, privateKey } = options;\n\n  const encodedHeader = base64url(\n    new TextEncoder().encode(JSON.stringify(header))\n  );\n  const encodedPayload = base64url(\n    new TextEncoder().encode(JSON.stringify(payload))\n  );\n  const signingInput = `${encodedHeader}.${encodedPayload}`;\n  const signatureBuffer = await crypto.subtle.sign(\n    { name: 'ECDSA', hash: 'SHA-256' },\n    privateKey,\n    new TextEncoder().encode(signingInput)\n  );\n  return `${signingInput}.${base64url(new Uint8Array(signatureBuffer))}`;\n}\n\nasync function importPublicKey(jwk: JsonWebKey): Promise<CryptoKey> {\n  return crypto.subtle.importKey(\n    'jwk',\n    jwk,\n    { name: 'ECDSA', namedCurve: 'P-256' },\n    false,\n    ['verify']\n  );\n}\n\ninterface DecodeAndVerifyJwtOptions {\n  token: string;\n  publicKeyJwk: JsonWebKey;\n}\n\n/**\n * Verifies the ES256 signature on `token` against `publicKeyJwk` and\n * returns the decoded payload. Does not check `exp` — use\n * {@link verifyJwt} when expiry enforcement is desired.\n *\n * @throws {Error} When the token isn't three segments, when the\n *   signature fails verification, or when the payload isn't valid\n *   JSON.\n */\nexport async function decodeAndVerifyJwt(\n  options: DecodeAndVerifyJwtOptions\n): Promise<Record<string, unknown>> {\n  const { token, publicKeyJwk } = options;\n  const parts = token.split('.');\n  if (parts.length !== 3) throw new Error('Invalid JWT format');\n  const [encodedHeader, encodedPayload, encodedSignature] = parts as [\n    string,\n    string,\n    string,\n  ];\n  const publicKey = await importPublicKey(publicKeyJwk);\n  const valid = await crypto.subtle.verify(\n    { name: 'ECDSA', hash: 'SHA-256' },\n    publicKey,\n    base64urlDecode(encodedSignature),\n    new TextEncoder().encode(`${encodedHeader}.${encodedPayload}`)\n  );\n  if (!valid) throw new Error('JWT signature verification failed');\n  return JSON.parse(\n    new TextDecoder().decode(base64urlDecode(encodedPayload))\n  ) as Record<string, unknown>;\n}\n\nexport interface VerifyJwtOptions {\n  /** Compact-serialized JWT to verify. */\n  token: string;\n  /** Public key in JWK form. Caller is responsible for trusting it. */\n  publicKeyJwk: JsonWebKey;\n}\n\n/**\n * Verifies signature and (if present) `exp` (RFC 7519 §4.1.4) on a\n * JWT and returns its payload.\n *\n * @throws {Error} When the signature fails or when `exp` has passed.\n */\nexport async function verifyJwt(\n  options: VerifyJwtOptions\n): Promise<Record<string, unknown>> {\n  const { token, publicKeyJwk } = options;\n  const payload = await decodeAndVerifyJwt({ token, publicKeyJwk });\n  const now = Math.floor(Date.now() / 1000);\n  if (typeof payload['exp'] === 'number' && payload['exp'] < now) {\n    throw new Error('JWT expired');\n  }\n  return payload;\n}\n\nexport interface SignJwtOptions {\n  /** ES256 private key as a non-extractable WebCrypto key. */\n  privateKey: CryptoKey;\n  /**\n   * Custom claims merged onto an `iat` claim (and `exp` when\n   * `ttlSeconds` is supplied). Caller-provided keys override the\n   * standard ones.\n   */\n  payload: Record<string, unknown>;\n  /**\n   * Lifetime of the token in seconds. When set, the JWT's `exp` claim\n   * is computed as `iat + ttlSeconds`. When omitted, no `exp` is added\n   * (the caller is responsible for one if needed).\n   */\n  ttlSeconds?: number;\n}\n\n/**\n * Signs a JWT (RFC 7519) with `alg=ES256, typ=JWT` and returns the\n * compact serialization. Always sets `iat` to the current second; the\n * caller controls every other claim via `payload`.\n */\nexport async function signJwt(options: SignJwtOptions): Promise<string> {\n  const { privateKey, payload, ttlSeconds } = options;\n  const now = Math.floor(Date.now() / 1000);\n  const payloadWithStandardClaims =\n    ttlSeconds !== undefined\n      ? { iat: now, exp: now + ttlSeconds, ...payload }\n      : { iat: now, ...payload };\n  return encodeAndSignJwt({\n    header: { alg: 'ES256', typ: 'JWT' },\n    payload: payloadWithStandardClaims,\n    privateKey,\n  });\n}\n","import { type AppKeys } from '../types.ts';\nimport { base64urlDecode } from './base64-utils.ts';\nimport { getJwkThumbprint } from './jwk-utils.ts';\nimport { decodeAndVerifyJwt, encodeAndSignJwt } from './jwt-utils.ts';\n\n/**\n * Claims that go into a DPoP proof JWT (RFC 9449 §4.2). Extra\n * properties pass through to the encoder unchanged so callers can\n * include implementation-specific claims.\n */\nexport interface DpopClaims {\n  /** HTTP method of the protected request, uppercase. */\n  htm: string;\n  /** Target URI of the protected request, fully-qualified. */\n  htu: string;\n  /** Unique proof identifier (RFC 9449 §4.2, recommended UUID). */\n  jti: string;\n  /** Issuance time, Unix epoch seconds. */\n  iat: number;\n  /**\n   * Hash of the access token presented alongside this proof, if any\n   * (RFC 9449 §4.2). Required for resource-server DPoP.\n   */\n  ath?: string;\n  /**\n   * App session ID hash. Custom HubSpot extension that lets the auth\n   * server bind tokens to the browser session that minted them.\n   */\n  sid?: string;\n  [key: string]: unknown;\n}\n\nfunction ecPublicJwkForDpopHeader(jwk: JsonWebKey): JsonWebKey {\n  if (\n    jwk.kty !== 'EC' ||\n    jwk.crv !== 'P-256' ||\n    typeof jwk.x !== 'string' ||\n    typeof jwk.y !== 'string'\n  ) {\n    throw new Error('Expected P-256 EC public JWK');\n  }\n  return {\n    kty: 'EC',\n    crv: 'P-256',\n    x: jwk.x,\n    y: jwk.y,\n  };\n}\n\nexport interface SignDpopProofOptions {\n  /** App key material produced by `secureStart`. */\n  appKeys: AppKeys;\n  /** Claims to include in the DPoP proof. */\n  claims: DpopClaims;\n}\n\n/**\n * Mints a DPoP proof JWT (RFC 9449) signed with the app's private\n * key. The header is set to `typ=dpop+jwt`, `alg=ES256`, and embeds\n * the public JWK so the receiver can verify the signature without\n * out-of-band key distribution.\n */\nexport async function signDpopProof(\n  options: SignDpopProofOptions\n): Promise<string> {\n  const { appKeys, claims } = options;\n  const publicJwk = ecPublicJwkForDpopHeader(appKeys.appPublicKeyJwk);\n  return encodeAndSignJwt({\n    header: { alg: 'ES256', typ: 'dpop+jwt', jwk: publicJwk },\n    payload: claims,\n    privateKey: appKeys.appPrivateKey,\n  });\n}\n\n/**\n * Result of a successful {@link verifyDpopProof} call.\n */\nexport interface VerifiedDpopProof {\n  /** Public JWK extracted from the proof's header. */\n  publicKeyJwk: JsonWebKey;\n  /** RFC 7638 JWK thumbprint of `publicKeyJwk`. */\n  jkt: string;\n  /** Decoded claims from the proof's payload. */\n  claims: DpopClaims;\n}\n\nexport interface VerifyDpopProofOptions {\n  /** The compact-serialized DPoP proof. */\n  proof: string;\n  /** Expected HTTP method (RFC 9449 `htm` claim). */\n  htm: string;\n  /** Expected request URI (RFC 9449 `htu` claim). */\n  htu: string;\n  /** Expected access-token hash (RFC 9449 `ath` claim). */\n  ath?: string;\n  /** Expected app-session-ID hash (`sid` claim). */\n  sid?: string;\n}\n\ninterface DpopProofHeader {\n  typ?: string;\n  alg?: string;\n  jwk?: JsonWebKey;\n}\n\n/**\n * Verifies a DPoP proof JWT and returns the embedded public JWK,\n * its thumbprint, and the decoded claims.\n *\n * Enforces RFC 9449's required checks:\n *\n * - `typ=dpop+jwt`, `alg=ES256`, and a JWK in the header.\n * - Signature is valid against the embedded JWK.\n * - `htm`, `htu`, and (when supplied) `ath`/`sid` match.\n * - `iat` is within ±5 minutes of \"now\".\n *\n * @throws {Error} If any of the above checks fail.\n */\nexport async function verifyDpopProof(\n  options: VerifyDpopProofOptions\n): Promise<VerifiedDpopProof> {\n  const { proof, htm, htu, ath, sid } = options;\n  const parts = proof.split('.');\n  if (parts.length !== 3) throw new Error('Invalid DPoP proof format');\n\n  const encodedHeader = parts[0];\n  if (!encodedHeader) throw new Error('Missing DPoP header');\n\n  const header = JSON.parse(\n    new TextDecoder().decode(base64urlDecode(encodedHeader))\n  ) as DpopProofHeader;\n\n  if (header.typ !== 'dpop+jwt') throw new Error('Invalid DPoP typ header');\n  if (header.alg !== 'ES256') throw new Error('Unsupported DPoP algorithm');\n  const publicKeyJwk = header.jwk;\n  if (!publicKeyJwk) throw new Error('Missing jwk in DPoP header');\n\n  const payload = await decodeAndVerifyJwt({ token: proof, publicKeyJwk });\n  const claims = payload as unknown as DpopClaims;\n\n  if (claims.htm !== htm) {\n    throw new Error(`DPoP htm mismatch: expected ${htm}, got ${claims.htm}`);\n  }\n  if (claims.htu !== htu) {\n    throw new Error(`DPoP htu mismatch: expected ${htu}, got ${claims.htu}`);\n  }\n  if (ath !== undefined && claims.ath !== ath) {\n    throw new Error('DPoP ath mismatch');\n  }\n  if (sid !== undefined && claims.sid !== sid) {\n    throw new Error('DPoP sid mismatch');\n  }\n\n  const now = Math.floor(Date.now() / 1000);\n  if (Math.abs(now - claims.iat) > 300) {\n    throw new Error('DPoP proof expired or too far in future');\n  }\n\n  const jkt = await getJwkThumbprint({ publicKeyJwk });\n  return { publicKeyJwk, jkt, claims };\n}\n","import { base64url } from './base64.ts';\n\n/**\n * Hashes a UTF-8 string with SHA-256 and encodes the digest as\n * base64url. Used to compute DPoP `ath`/`sid` claims, JWK thumbprints\n * (RFC 7638), and PKCE code challenges.\n */\nexport async function sha256base64url(input: string): Promise<string> {\n  const digest = await crypto.subtle.digest(\n    'SHA-256',\n    new TextEncoder().encode(input)\n  );\n  return base64url(new Uint8Array(digest));\n}\n"],"mappings":"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"}

package/dist/server/{types.d.ts → types-5gfN91Fq.d.ts}

@@ -52,5 +52,5 @@ interface JwkSet {
   keys: JsonWebKey[];
 }
 //#endregion
-export { AppKeys, HubSpotProxy, JwkSet };
-//# sourceMappingURL=types.d.ts.map
+export { HubSpotProxy as n, JwkSet as r, AppKeys as t };
+//# sourceMappingURL=types-5gfN91Fq.d.ts.map

package/dist/server/{api-client-core/types.d.ts → types-DEOUH4wE.d.ts}

@@ -131,5 +131,5 @@ interface CreateHubSpotClientOptions {
   plugins: Plugin[];
 }
 //#endregion
-export { ApiResponse, CreateHubSpotClientOptions, HubSpotApiResponse, HubSpotClient, Middleware, MiddlewareContext, Next, Operation, PaginatedItem, PaginatedResponse, Plugin, PluginAPI, SyntheticOperation, SyntheticOperationContext, SyntheticStreamingOperation };
-//# sourceMappingURL=types.d.ts.map
+export { Middleware as a, Operation as c, Plugin as d, PluginAPI as f, SyntheticStreamingOperation as h, HubSpotClient as i, PaginatedItem as l, SyntheticOperationContext as m, CreateHubSpotClientOptions as n, MiddlewareContext as o, SyntheticOperation as p, HubSpotApiResponse as r, Next as s, ApiResponse as t, PaginatedResponse as u };
+//# sourceMappingURL=types-DEOUH4wE.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hubspot/app-connect-sdk",
-  "version": "1.0.0-alpha.2",
+  "version": "1.0.0-alpha.4",
   "description": "HubSpot App Connect SDK (alpha release). Documentation and integration guidance forthcoming.",
   "type": "module",
   "exports": {
@@ -23,16 +23,11 @@
   },
   "prettier": "@private/prettier-config",
   "peerDependencies": {
-    "hono": "^4.0.0",
     "react": "^18.0.0 || ^19.0.0"
   },
-  "peerDependenciesMeta": {
-    "hono": {
-      "optional": true
-    }
-  },
   "dependencies": {
-    "@base-ui/react": "^1.4.1"
+    "@base-ui/react": "^1.4.1",
+    "hono": "^4.7.11"
   },
   "engines": {
     "node": ">=24.0.0"
@@ -44,14 +39,13 @@
     "@vanilla-extract/css": "^1.20.1",
     "@vanilla-extract/rollup-plugin": "^1.5.3",
     "eslint": "10.0.3",
-    "hono": "^4.7.11",
     "prettier": "3.8.1",
     "react": "^19.1.0",
     "tsdown": "0.22.0-beta.3",
     "typescript": "6.0.3",
     "vitest": "4.0.18",
-    "@private/tsconfig": "0.1.0",
     "@private/eslint-config": "0.1.0",
+    "@private/tsconfig": "0.1.0",
     "@private/prettier-config": "0.1.0"
   },
   "scripts": {

package/src/browser/app-connect-controller/connect-start.ts

@@ -41,5 +41,6 @@ export async function startHubSpotConnection(
 
   await delay(ARTIFICIAL_CONNECT_REDIRECT_DELAY_MS);
 
-  window.location.href = authorizationUrl;
+  console.log('authorizationUrl', authorizationUrl);
+  // window.location.href = authorizationUrl;
 }

package/src/browser/app-connect-controller/init.test.ts

@@ -0,0 +1,167 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { HUBSPOT_FRONTEND_CALLBACK_PATH } from '../../shared/constants.ts';
+import { noopLogger } from '../../shared/logger.ts';
+import { EXPIRES_AT_KEY } from './constants.ts';
+import { initAppConnect } from './init.ts';
+import type {
+  AppConnectContext,
+  AppConnectInternalState,
+  SessionStorage,
+} from './types.ts';
+import { createStore } from './utils/store-utils.ts';
+
+const HUBSPOT_CONNECT_BASE_URL =
+  'https://edge.example.com/functions/v1/hubspot-connect';
+
+function createInMemorySessionStorage(): SessionStorage {
+  const map = new Map<string, string>();
+  return {
+    getItem: (key) => map.get(key) ?? null,
+    setItem: (key, value) => {
+      map.set(key, value);
+    },
+    removeItem: (key) => {
+      map.delete(key);
+    },
+  };
+}
+
+function createTestContext(): AppConnectContext {
+  const initialState: AppConnectInternalState = {
+    isInitComplete: false,
+    isConnectInFlight: false,
+    isSessionConnected: false,
+    isDisconnectInFlight: false,
+    error: null,
+    expiresAt: null,
+  };
+  return {
+    config: { hubSpotConnectBaseUrl: HUBSPOT_CONNECT_BASE_URL },
+    logger: noopLogger,
+    sessionStorage: createInMemorySessionStorage(),
+    store: createStore<AppConnectInternalState>(initialState),
+  };
+}
+
+interface FakeWindowOptions {
+  href: string;
+}
+
+interface FakeWindow {
+  history: { calls: Array<[unknown, string, string]> };
+  windowProxy: {
+    location: Pick<Location, 'pathname' | 'search' | 'origin'>;
+  };
+}
+
+function installFakeWindow(options: FakeWindowOptions): FakeWindow {
+  const url = new URL(options.href);
+  const calls: Array<[unknown, string, string]> = [];
+  const fakeWindow = {
+    location: {
+      pathname: url.pathname,
+      search: url.search,
+      origin: url.origin,
+    },
+  };
+  const fakeHistory = {
+    replaceState: (state: unknown, title: string, newUrl: string) => {
+      calls.push([state, title, newUrl]);
+      const replaced = new URL(newUrl, url.origin);
+      fakeWindow.location.pathname = replaced.pathname;
+      fakeWindow.location.search = replaced.search;
+    },
+  };
+  vi.stubGlobal('window', fakeWindow);
+  vi.stubGlobal('history', fakeHistory);
+  return { history: { calls }, windowProxy: fakeWindow };
+}
+
+describe('initAppConnect', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date(1_700_000_000_000));
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+    vi.useRealTimers();
+  });
+
+  it('is a no-op on a normal page (no callback path, no expires_at param)', async () => {
+    installFakeWindow({ href: 'https://app.example.com/dashboard' });
+    const fetchSpy = vi.spyOn(globalThis, 'fetch');
+    const context = createTestContext();
+
+    await initAppConnect(context);
+
+    expect(fetchSpy).not.toHaveBeenCalled();
+    expect(context.store.getSnapshot().expiresAt).toBeNull();
+  });
+
+  it('POSTs to /auth/complete on the OAuth callback path and persists expires_at + return_path', async () => {
+    const expiresAt = Date.now() + 1800 * 1000;
+    installFakeWindow({
+      href: `https://app.example.com${HUBSPOT_FRONTEND_CALLBACK_PATH}?code=auth-code&state=auth-state`,
+    });
+    const fetchSpy = vi
+      .spyOn(globalThis, 'fetch')
+      .mockResolvedValue(
+        new Response(
+          JSON.stringify({ expires_at: expiresAt, return_path: '/dashboard' }),
+          { status: 200 }
+        )
+      );
+    const context = createTestContext();
+
+    await initAppConnect(context);
+
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    const [calledUrl, calledInit] = fetchSpy.mock.calls[0]!;
+    const url = new URL(calledUrl as string);
+    expect(url.origin + url.pathname).toBe(
+      `${HUBSPOT_CONNECT_BASE_URL}/auth/complete`
+    );
+    expect(url.searchParams.get('code')).toBe('auth-code');
+    expect(url.searchParams.get('state')).toBe('auth-state');
+    expect((calledInit as RequestInit).method).toBe('POST');
+    expect((calledInit as RequestInit).credentials).toBe('include');
+
+    expect(context.store.getSnapshot().expiresAt).toBe(expiresAt);
+    expect(context.sessionStorage.getItem(EXPIRES_AT_KEY)).toBe(
+      String(expiresAt)
+    );
+    expect(window.location.pathname).toBe('/dashboard');
+  });
+
+  it('throws and clears session storage when /auth/complete returns a non-OK response', async () => {
+    installFakeWindow({
+      href: `https://app.example.com${HUBSPOT_FRONTEND_CALLBACK_PATH}?code=auth-code&state=bad-state`,
+    });
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+      new Response('{"error":"State mismatch"}', {
+        status: 403,
+        statusText: 'Forbidden',
+      })
+    );
+    const context = createTestContext();
+    context.sessionStorage.setItem(EXPIRES_AT_KEY, '999');
+
+    await expect(initAppConnect(context)).rejects.toThrow(/Failed to complete/);
+    expect(context.sessionStorage.getItem(EXPIRES_AT_KEY)).toBeNull();
+  });
+
+  it('skips the callback step on the callback path when code or state are missing', async () => {
+    installFakeWindow({
+      href: `https://app.example.com${HUBSPOT_FRONTEND_CALLBACK_PATH}`,
+    });
+    const fetchSpy = vi.spyOn(globalThis, 'fetch');
+    const context = createTestContext();
+
+    await initAppConnect(context);
+
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+});

package/src/browser/app-connect-controller/init.ts

@@ -1,35 +1,86 @@
-import { EXPIRES_AT_KEY, EXPIRES_AT_URL_PARAM } from './constants.ts';
+import {
+  AUTH_COMPLETE_CODE_PARAM,
+  AUTH_COMPLETE_STATE_PARAM,
+  HUBSPOT_FRONTEND_CALLBACK_PATH,
+} from '../../shared/constants.ts';
+import type { AuthCompleteResponse } from '../../shared/wire-types.ts';
+import { EXPIRES_AT_KEY } from './constants.ts';
 import type { AppConnectContext } from './types.ts';
+import { clearSessionStorage } from './utils/session-utils.ts';
 
 /**
- * Picks up the `__hs_expires_at` parameter the OAuth callback adds to
- * the redirect URL, persists it to the controller, and strips it from
- * the address bar so it's not logged or bookmarked.
+ * On `controller.start()`:
  *
- * Called once by `controller.start()`. A no-op when the parameter
- * isn't present (e.g. on every page load other than the OAuth return
- * trip).
+ * 1. If the browser has been redirected back to the SDK's frontend
+ *    OAuth callback path (`HUBSPOT_FRONTEND_CALLBACK_PATH`) with
+ *    `?code` + `?state`, POST those values to the SDK's
+ *    `auth/complete` endpoint to finish the token exchange. The
+ *    server sets the durable session cookies on the response (in the
+ *    same `(frontend, edge)` CHIPS partition the SDK reads them from
+ *    on subsequent API fetches) and returns `{ expires_at,
+ *    return_path }`. Replace the URL with `${return_path}?
+ *    ${EXPIRES_AT_URL_PARAM}=${expires_at}` so the rest of init
+ *    runs against the page the user actually started the connect
+ *    flow from.
+ * 2. Pick up `?__hs_expires_at` from `window.location` (placed there
+ *    by step 1, or by an in-progress refresh hop), persist it to the
+ *    controller's store + sessionStorage, and strip it from the
+ *    address bar so it isn't logged or bookmarked.
+ *
+ * A no-op when neither set of parameters is present (every page
+ * load other than the OAuth return trip).
  */
 export async function initAppConnect(
   context: AppConnectContext
 ): Promise<void> {
+  await consumeOAuthCallback(context);
+}
+
+async function consumeOAuthCallback(context: AppConnectContext): Promise<void> {
+  if (window.location.pathname !== HUBSPOT_FRONTEND_CALLBACK_PATH) return;
+
   const params = new URLSearchParams(window.location.search);
-  const expiresAtStr = params.get(EXPIRES_AT_URL_PARAM);
-  if (!expiresAtStr) return;
+  const code = params.get(AUTH_COMPLETE_CODE_PARAM);
+  const state = params.get(AUTH_COMPLETE_STATE_PARAM);
+  if (!code || !state) return;
+
+  const completeUrl = new URL(
+    `${context.config.hubSpotConnectBaseUrl}/auth/complete`,
+    window.location.origin
+  );
+  completeUrl.searchParams.set(AUTH_COMPLETE_CODE_PARAM, code);
+  completeUrl.searchParams.set(AUTH_COMPLETE_STATE_PARAM, state);
+
+  let response: Response;
+  try {
+    response = await fetch(completeUrl.toString(), {
+      method: 'POST',
+      credentials: 'include',
+    });
+  } catch (err) {
+    clearSessionStorage(context);
+    throw new Error(
+      `Failed to complete HubSpot OAuth: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
 
-  const expiresAt = parseInt(expiresAtStr, 10);
-  if (isNaN(expiresAt)) return;
+  if (!response.ok) {
+    clearSessionStorage(context);
+    throw new Error(
+      `Failed to complete HubSpot OAuth: ${response.status} ${response.statusText}`
+    );
+  }
 
-  params.delete(EXPIRES_AT_URL_PARAM);
-  const cleanSearch = params.toString();
+  const body = (await response.json()) as AuthCompleteResponse;
+
+  const { expires_at: expiresAt, return_path: returnPath } = body;
+  context.store.setState({ expiresAt });
+  context.sessionStorage.setItem(EXPIRES_AT_KEY, String(expiresAt));
+
+  const targetUrl = new URL(returnPath, window.location.origin);
   history.replaceState(
     null,
     '',
-    cleanSearch
-      ? `${window.location.pathname}?${cleanSearch}`
-      : window.location.pathname
+    `${targetUrl.pathname}${targetUrl.search}${targetUrl.hash}`
   );
-
-  context.store.setState({ expiresAt });
-  context.sessionStorage.setItem(EXPIRES_AT_KEY, String(expiresAt));
 }

package/src/browser/react/components/AppConnectHeader/AppConnectHeader.tsx

@@ -37,6 +37,8 @@ interface AppConnectHeaderProps {
 
 export function AppConnectHeader({ title }: AppConnectHeaderProps) {
   const { status } = useHubSpotAppConnect();
+  const connectButton =
+    status === 'initializing' ? null : <ConnectButton variant="secondary" />;
   return (
     <header className={styles.header}>
       <div className={styles.titleRow}>
@@ -48,11 +50,7 @@ export function AppConnectHeader({ title }: AppConnectHeaderProps) {
           {status === 'connected' ? <ViewingHubSpotContextRow /> : null}
         </div>
       </div>
-      {status === 'connected' ? (
-        <UserMenu />
-      ) : (
-        <ConnectButton variant="secondary" />
-      )}
+      {status === 'connected' ? <UserMenu /> : connectButton}
     </header>
   );
 }

package/src/browser/react/components/ConnectButton/ConnectButton.tsx

@@ -20,7 +20,8 @@ export function ConnectButton({
   className,
 }: ConnectButtonProps) {
   const { status, connectToHubSpot } = useHubSpotAppConnect();
-  const isConnecting = status === 'connecting';
+  console.log('status', status);
+  const isConnecting = status === 'connecting' || status === 'initializing';
   const composedClassName = [root, className].filter(Boolean).join(' ');
   const labelClassName = isConnecting ? `${label} ${labelMuted}` : label;
   return (

package/src/server/api-client-core/plugins/fetch-transport.ts

@@ -101,11 +101,15 @@ export function fetchTransportPlugin(
           }
         }
         const response = await fetch(url, init);
+        const responseHeaders: Record<string, string> = Object.create(null);
+        response.headers.forEach((value, key) => {
+          responseHeaders[key] = value;
+        });
 
         return {
           status: response.status,
           statusText: response.statusText,
-          headers: Object.fromEntries(response.headers.entries()),
+          headers: responseHeaders,
           // 204 No Content responses have no body to parse
           bodyJson: response.status === 204 ? undefined : await response.json(),
         };

package/src/server/constants.ts

@@ -12,6 +12,25 @@ export const HUBSPOT_ACCESS_TOKEN_COOKIE_NAME = '__Host-hs_access_token';
  */
 export const HUBSPOT_APP_SID_COOKIE_NAME = '__Host-hs_app_sid';
 
+/**
+ * Cookie pinning the browser-facing app origin (e.g.
+ * `https://app.example.com`) for the lifetime of an app session.
+ * Set by `auth/init-session` from the request's `Origin` header and
+ * read by:
+ *
+ * - The CORS middleware to emit a credentialed
+ *   `Access-Control-Allow-Origin` value (`*` is forbidden when
+ *   `Access-Control-Allow-Credentials: true`).
+ * - `auth/complete` to rebuild the OAuth `redirect_uri` it sent to
+ *   HubSpot during `init-session` (the token endpoint validates that
+ *   the two values match).
+ *
+ * `__Host-` prefixed (Path=/, Secure, no Domain), so the same
+ * function host can serve both `hubspot-connect` and `api` routes
+ * and read the cookie from either.
+ */
+export const HUBSPOT_APP_ORIGIN_COOKIE_NAME = '__Host-hs_app_origin';
+
 /**
  * Prefix used for refresh-token cookies. Each session gets its own
  * cookie name (`hs_refresh_<sidHash>`) so multiple devices/tabs can
@@ -22,6 +41,7 @@ export const HUBSPOT_REFRESH_COOKIE_PREFIX = 'hs_refresh_';
 const PROTECTED_COOKIE_NAMES = new Set([
   HUBSPOT_ACCESS_TOKEN_COOKIE_NAME,
   HUBSPOT_APP_SID_COOKIE_NAME,
+  HUBSPOT_APP_ORIGIN_COOKIE_NAME,
 ]);
 
 /**
@@ -40,14 +60,19 @@ export function isProtectedCookieName(cookieName: string): boolean {
 
 /**
  * Cookie carrying the PKCE code verifier between `init-session` and
- * `callback`. `Lax` SameSite so it accompanies the redirect back from
- * HubSpot.
+ * `auth/complete`. Set with `SameSite=None; Secure; Partitioned` so the
+ * frontend's credentialed cross-site `POST /auth/complete` (made from
+ * the OAuth callback page on the app origin to the SDK's edge function
+ * origin) carries it through. `Lax` would silently drop it on that
+ * fetch, breaking every successful HubSpot redirect.
  */
 export const TEMP_COOKIE_PKCE_VERIFIER = '__hs_pkce_verifier';
 
 /**
  * Cookie carrying the OAuth `state` value between `init-session` and
- * `callback`. Compared against the `state` query parameter as the
- * primary CSRF defense.
+ * `auth/complete`. Compared against the `state` query parameter as the
+ * primary CSRF defense. Same `SameSite=None; Secure; Partitioned`
+ * attributes as `TEMP_COOKIE_PKCE_VERIFIER` for the same cross-site
+ * `POST /auth/complete` reason.
  */
 export const TEMP_COOKIE_OAUTH_STATE = '__hs_oauth_state';

package/src/server/hono/hono-request-handler.ts

@@ -12,6 +12,7 @@ import { sanitizeRequest } from '../sanitize-request.ts';
 import type { AppKeys, UserCredentials } from '../types.ts';
 import { parseCookies } from '../utils/cookie-utils.ts';
 import type { AppConnectHonoBindings, AppConnectHonoEnv } from './types.ts';
+import { corsMiddleware } from './utils/cors-middleware.ts';
 
 /**
  * Web-standard fetch handler signature returned by
@@ -62,6 +63,29 @@ export function createAppConnectRequestHandler(
 ): AppConnectFetchHandler {
   const { registerRoutes, appKeys, logger = noopLogger } = options;
   const app = new Hono<AppConnectHonoEnv>();
+  // Credentialed CORS first: preflights short-circuit with 204
+  // before the auth check runs, and 401 responses still carry
+  // `Access-Control-Allow-*` headers (the browser drops responses
+  // without them on credentialed cross-site fetches).
+  app.use('*', corsMiddleware());
+
+  // Auth gate: every non-OPTIONS request must arrive with the
+  // SDK-managed access-token + session-id cookies. The CORS
+  // middleware above short-circuits OPTIONS, so this only runs on
+  // real requests; missing cookies now surface as a normal 401 with
+  // CORS headers attached on the way back out (the previous
+  // implementation threw on a missing `Cookie` header before any
+  // middleware ran, which broke browser preflights).
+  app.use('*', async (c, next) => {
+    const { authenticated } = c.env.hubSpot;
+    if (!authenticated) {
+      return c.json({ error: 'Unauthorized' }, 401);
+    }
+
+    await next();
+    return;
+  });
+
   registerRoutes(app);
 
   return (request: Request) => {
@@ -72,33 +96,36 @@ export function createAppConnectRequestHandler(
     const cookies = parseCookies(cookie);
     const accessToken = cookies[HUBSPOT_ACCESS_TOKEN_COOKIE_NAME];
     const sessionId = cookies[HUBSPOT_APP_SID_COOKIE_NAME];
-    if (!accessToken || !sessionId) {
-      // Return 401 Unauthorized
-      return new Response(null, {
-        status: 401,
-        statusText: 'Unauthorized',
-        headers: {
-          'Content-Type': 'application/json',
-        },
-      });
-    }
+
     const userCredentials: UserCredentials = { accessToken, sessionId };
 
-    const hubSpotProxy = createHubSpotProxy({
+    const proxy = createHubSpotProxy({
       userCredentials,
       appKeys,
       logger,
     });
 
-    const hubSpotClient = createHubSpotClient({
-      plugins: [fetchTransportPlugin({ getAccessToken: () => accessToken })],
+    const client = createHubSpotClient({
+      plugins: [
+        fetchTransportPlugin({
+          getAccessToken: () => {
+            if (!accessToken) {
+              throw new Error('Missing access token');
+            }
+            return accessToken;
+          },
+        }),
+      ],
     });
 
     const sanitizedRequest = sanitizeRequest(request);
 
     const honoBindings: AppConnectHonoBindings = {
-      hubSpotProxy,
-      hubSpotClient,
+      hubSpot: {
+        proxy,
+        client,
+        authenticated: proxy.authenticated,
+      },
     };
 
     return app.fetch(sanitizedRequest, honoBindings);