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

package/dist/server/hono/utils/cookie-utils.js

@@ -14,13 +14,14 @@ function setResponseCookie(options) {
 * cookies share the same policy.
 */
 function serializeCookie(options) {
-	const { name, value, path, sameSite = "Strict", maxAge, secure = true, httpOnly = true } = options;
+	const { name, value, path, sameSite = "Strict", maxAge, secure = true, httpOnly = true, partitioned = false } = options;
 	const parts = [`${name}=${value}`];
 	if (httpOnly) parts.push("HttpOnly");
 	if (secure) parts.push("Secure");
 	parts.push(`SameSite=${sameSite}`);
 	parts.push(`Path=${path}`);
 	parts.push(`Max-Age=${maxAge}`);
+	if (partitioned) parts.push("Partitioned");
 	return parts.join("; ");
 }
 //#endregion

package/dist/server/hono/utils/cookie-utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"cookie-utils.js","names":[],"sources":["../../../../src/server/hono/utils/cookie-utils.ts"],"sourcesContent":["import type { Context } from 'hono';\n\nexport interface SetResponseCookieOptions {\n  c: Context;\n  value: string;\n}\n\n/**\n * Appends a `Set-Cookie` header to the response. Hono replaces single\n * headers by default, so this uses `{ append: true }` to emit multiple\n * cookies on the same response.\n */\nexport function setResponseCookie(options: SetResponseCookieOptions): void {\n  const { c, value } = options;\n  c.header('Set-Cookie', value, { append: true });\n}\n\nexport interface SerializeCookieOptions {\n  name: string;\n  value: string;\n  /** `__Host-` prefix requires `Path=/` and is recommended for session cookies. */\n  path: string;\n  /** Defaults to `Strict`. Use `Lax` for short-lived OAuth temp cookies. */\n  sameSite?: 'Strict' | 'Lax';\n  /** Lifetime in seconds. `0` deletes the cookie. */\n  maxAge: number;\n  /** Defaults to `true`; only set `false` for tests or non-HTTPS dev hosts. */\n  secure?: boolean;\n  /** Defaults to `true`. */\n  httpOnly?: boolean;\n}\n\n/**\n * Builds a `Set-Cookie` header value with HubSpot's default attributes\n * (HttpOnly, Secure, SameSite). Centralizes the serialization so all\n * cookies share the same policy.\n */\nexport function serializeCookie(options: SerializeCookieOptions): string {\n  const {\n    name,\n    value,\n    path,\n    sameSite = 'Strict',\n    maxAge,\n    secure = true,\n    httpOnly = true,\n  } = options;\n  const parts: string[] = [`${name}=${value}`];\n  if (httpOnly) parts.push('HttpOnly');\n  if (secure) parts.push('Secure');\n  parts.push(`SameSite=${sameSite}`);\n  parts.push(`Path=${path}`);\n  parts.push(`Max-Age=${maxAge}`);\n  return parts.join('; ');\n}\n"],"mappings":";;;;;;AAYA,SAAgB,kBAAkB,SAAyC;CACzE,MAAM,EAAE,GAAG,UAAU;CACrB,EAAE,OAAO,cAAc,OAAO,EAAE,QAAQ,MAAM,CAAC;;;;;;;AAuBjD,SAAgB,gBAAgB,SAAyC;CACvE,MAAM,EACJ,MACA,OACA,MACA,WAAW,UACX,QACA,SAAS,MACT,WAAW,SACT;CACJ,MAAM,QAAkB,CAAC,GAAG,KAAK,GAAG,QAAQ;CAC5C,IAAI,UAAU,MAAM,KAAK,WAAW;CACpC,IAAI,QAAQ,MAAM,KAAK,SAAS;CAChC,MAAM,KAAK,YAAY,WAAW;CAClC,MAAM,KAAK,QAAQ,OAAO;CAC1B,MAAM,KAAK,WAAW,SAAS;CAC/B,OAAO,MAAM,KAAK,KAAK"}
+{"version":3,"file":"cookie-utils.js","names":[],"sources":["../../../../src/server/hono/utils/cookie-utils.ts"],"sourcesContent":["import type { Context } from 'hono';\n\nexport interface SetResponseCookieOptions {\n  c: Context;\n  value: string;\n}\n\n/**\n * Appends a `Set-Cookie` header to the response. Hono replaces single\n * headers by default, so this uses `{ append: true }` to emit multiple\n * cookies on the same response.\n */\nexport function setResponseCookie(options: SetResponseCookieOptions): void {\n  const { c, value } = options;\n  c.header('Set-Cookie', value, { append: true });\n}\n\nexport interface SerializeCookieOptions {\n  name: string;\n  value: string;\n  /** `__Host-` prefix requires `Path=/` and is recommended for session cookies. */\n  path: string;\n  /**\n   * Defaults to `Strict`.\n   *\n   * - `Strict`: only sent on same-site requests. Default for self-hosted\n   *   same-origin deployments.\n   * - `Lax`: also sent on top-level cross-site GET navigations. Use for\n   *   short-lived OAuth temp cookies that need to survive a redirect.\n   * - `None`: sent on all cross-site requests; **requires `Secure=true`\n   *   and is typically combined with `Partitioned=true`** for the\n   *   cross-origin Lovable / Supabase deployment shape.\n   */\n  sameSite?: 'Strict' | 'Lax' | 'None';\n  /** Lifetime in seconds. `0` deletes the cookie. */\n  maxAge: number;\n  /** Defaults to `true`; only set `false` for tests or non-HTTPS dev hosts. */\n  secure?: boolean;\n  /** Defaults to `true`. */\n  httpOnly?: boolean;\n  /**\n   * When `true`, appends the `Partitioned` attribute (CHIPS — Cookies\n   * Having Independent Partitioned State). The browser then keys the\n   * cookie by `(top-level site, cookie host)` instead of by cookie\n   * host alone, which is required for the cross-origin SDK shape\n   * where the React app and the SDK's edge functions live on\n   * different sites and third-party cookies are blocked.\n   *\n   * Defaults to `false`. Browsers ignore `Partitioned` on cookies\n   * without `Secure=true` and reject it on cookies without\n   * `SameSite=None`.\n   */\n  partitioned?: boolean;\n}\n\n/**\n * Builds a `Set-Cookie` header value with HubSpot's default attributes\n * (HttpOnly, Secure, SameSite). Centralizes the serialization so all\n * cookies share the same policy.\n */\nexport function serializeCookie(options: SerializeCookieOptions): string {\n  const {\n    name,\n    value,\n    path,\n    sameSite = 'Strict',\n    maxAge,\n    secure = true,\n    httpOnly = true,\n    partitioned = false,\n  } = options;\n  const parts: string[] = [`${name}=${value}`];\n  if (httpOnly) parts.push('HttpOnly');\n  if (secure) parts.push('Secure');\n  parts.push(`SameSite=${sameSite}`);\n  parts.push(`Path=${path}`);\n  parts.push(`Max-Age=${maxAge}`);\n  if (partitioned) parts.push('Partitioned');\n  return parts.join('; ');\n}\n"],"mappings":";;;;;;AAYA,SAAgB,kBAAkB,SAAyC;CACzE,MAAM,EAAE,GAAG,UAAU;CACrB,EAAE,OAAO,cAAc,OAAO,EAAE,QAAQ,MAAM,CAAC;;;;;;;AA8CjD,SAAgB,gBAAgB,SAAyC;CACvE,MAAM,EACJ,MACA,OACA,MACA,WAAW,UACX,QACA,SAAS,MACT,WAAW,MACX,cAAc,UACZ;CACJ,MAAM,QAAkB,CAAC,GAAG,KAAK,GAAG,QAAQ;CAC5C,IAAI,UAAU,MAAM,KAAK,WAAW;CACpC,IAAI,QAAQ,MAAM,KAAK,SAAS;CAChC,MAAM,KAAK,YAAY,WAAW;CAClC,MAAM,KAAK,QAAQ,OAAO;CAC1B,MAAM,KAAK,WAAW,SAAS;CAC/B,IAAI,aAAa,MAAM,KAAK,cAAc;CAC1C,OAAO,MAAM,KAAK,KAAK"}

package/dist/server/hono/utils/cors-middleware.js

@@ -0,0 +1,85 @@
+import { HUBSPOT_APP_ORIGIN_COOKIE_NAME } from "../../constants.js";
+import { parseCookies } from "../../utils/cookie-utils.js";
+//#region src/server/hono/utils/cors-middleware.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, 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) {
+	const pinned = parseCookies(c.req.header("Cookie"))[HUBSPOT_APP_ORIGIN_COOKIE_NAME];
+	if (pinned) return pinned;
+	return c.req.header("Origin") ?? null;
+}
+function setSharedCorsHeaders(c, allowOrigin) {
+	c.res.headers.set("Access-Control-Allow-Origin", allowOrigin);
+	c.res.headers.set("Access-Control-Allow-Credentials", "true");
+	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.
+*/
+function corsMiddleware() {
+	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);
+	};
+}
+//#endregion
+export { corsMiddleware };
+
+//# sourceMappingURL=cors-middleware.js.map

package/dist/server/hono/utils/cors-middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cors-middleware.js","names":[],"sources":["../../../../src/server/hono/utils/cors-middleware.ts"],"sourcesContent":["import type { Context, MiddlewareHandler } from 'hono';\n\nimport { HUBSPOT_APP_ORIGIN_COOKIE_NAME } from '../../constants.ts';\nimport { parseCookies } from '../../utils/cookie-utils.ts';\n\n/**\n * Comma-separated list of request headers the SDK accepts on\n * cross-site fetches. Mirrors the Supabase Edge Functions defaults\n * the Lovable AI agent emits today, plus `content-type` for the\n * `auth/complete` POST body and `accept` so JSON content negotiation\n * works.\n */\nconst ALLOWED_HEADERS = [\n  'authorization',\n  'x-client-info',\n  'apikey',\n  'content-type',\n  'accept',\n  'x-supabase-client-platform',\n  'x-supabase-client-platform-version',\n  'x-supabase-client-runtime',\n  'x-supabase-client-runtime-version',\n].join(', ');\n\nconst ALLOWED_METHODS = 'GET, POST, OPTIONS';\n\nconst PREFLIGHT_MAX_AGE_SECONDS = '600';\n\n/**\n * Reads the persisted app-origin cookie from the request, falling\n * back to the literal `Origin` request header. The cookie is the\n * authoritative pin once `auth/init-session` has run; on the very\n * first init-session call (no cookie yet) we just echo whatever\n * `Origin` the caller sent — the actual access decision is enforced\n * by cookie-based authentication on every other route, not by CORS.\n */\nfunction resolveAllowedOrigin(c: Context): string | null {\n  const cookies = parseCookies(c.req.header('Cookie'));\n  const pinned = cookies[HUBSPOT_APP_ORIGIN_COOKIE_NAME];\n  if (pinned) return pinned;\n  return c.req.header('Origin') ?? null;\n}\n\nfunction setSharedCorsHeaders(c: Context, allowOrigin: string): void {\n  c.res.headers.set('Access-Control-Allow-Origin', allowOrigin);\n  c.res.headers.set('Access-Control-Allow-Credentials', 'true');\n  // `Origin` so caches differentiate per-caller responses; `Cookie`\n  // because the allowed origin is derived from the persisted\n  // `__Host-hs_app_origin` cookie.\n  c.res.headers.set('Vary', 'Origin, Cookie');\n}\n\n/**\n * Hono middleware that emits credentialed CORS response headers for\n * the cross-origin Lovable / Supabase deployment shape.\n *\n * - On `OPTIONS` preflight: short-circuits with a 204 carrying\n *   `Access-Control-Allow-*` headers. The browser will then send the\n *   real request with cookies attached.\n * - On every other method: echoes the pinned `__Host-hs_app_origin`\n *   cookie value (or, before init-session has run, the request\n *   `Origin` header) as `Access-Control-Allow-Origin`, with\n *   `Access-Control-Allow-Credentials: true`. The wildcard `*` is\n *   forbidden by browsers when credentials are included, so the\n *   middleware always echoes a concrete origin.\n *\n * Skips header emission entirely when the request has no `Origin`\n * (server-to-server calls, curl, etc.) so non-browser callers are\n * left untouched.\n */\nexport function corsMiddleware(): MiddlewareHandler {\n  return async (c, next) => {\n    const allowOrigin = resolveAllowedOrigin(c);\n\n    if (c.req.method === 'OPTIONS') {\n      const headers = new Headers();\n      if (allowOrigin) {\n        headers.set('Access-Control-Allow-Origin', allowOrigin);\n        headers.set('Access-Control-Allow-Credentials', 'true');\n        headers.set('Vary', 'Origin, Cookie');\n      }\n      headers.set('Access-Control-Allow-Methods', ALLOWED_METHODS);\n      headers.set('Access-Control-Allow-Headers', ALLOWED_HEADERS);\n      headers.set('Access-Control-Max-Age', PREFLIGHT_MAX_AGE_SECONDS);\n      return new Response(null, { status: 204, headers });\n    }\n\n    await next();\n\n    if (allowOrigin) {\n      setSharedCorsHeaders(c, allowOrigin);\n    }\n    return;\n  };\n}\n"],"mappings":";;;;;;;;;;AAYA,MAAM,kBAAkB;CACtB;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD,CAAC,KAAK,KAAK;AAEZ,MAAM,kBAAkB;AAExB,MAAM,4BAA4B;;;;;;;;;AAUlC,SAAS,qBAAqB,GAA2B;CAEvD,MAAM,SADU,aAAa,EAAE,IAAI,OAAO,SAAS,CAC7B,CAAC;CACvB,IAAI,QAAQ,OAAO;CACnB,OAAO,EAAE,IAAI,OAAO,SAAS,IAAI;;AAGnC,SAAS,qBAAqB,GAAY,aAA2B;CACnE,EAAE,IAAI,QAAQ,IAAI,+BAA+B,YAAY;CAC7D,EAAE,IAAI,QAAQ,IAAI,oCAAoC,OAAO;CAI7D,EAAE,IAAI,QAAQ,IAAI,QAAQ,iBAAiB;;;;;;;;;;;;;;;;;;;;AAqB7C,SAAgB,iBAAoC;CAClD,OAAO,OAAO,GAAG,SAAS;EACxB,MAAM,cAAc,qBAAqB,EAAE;EAE3C,IAAI,EAAE,IAAI,WAAW,WAAW;GAC9B,MAAM,UAAU,IAAI,SAAS;GAC7B,IAAI,aAAa;IACf,QAAQ,IAAI,+BAA+B,YAAY;IACvD,QAAQ,IAAI,oCAAoC,OAAO;IACvD,QAAQ,IAAI,QAAQ,iBAAiB;;GAEvC,QAAQ,IAAI,gCAAgC,gBAAgB;GAC5D,QAAQ,IAAI,gCAAgC,gBAAgB;GAC5D,QAAQ,IAAI,0BAA0B,0BAA0B;GAChE,OAAO,IAAI,SAAS,MAAM;IAAE,QAAQ;IAAK;IAAS,CAAC;;EAGrD,MAAM,MAAM;EAEZ,IAAI,aACF,qBAAqB,GAAG,YAAY"}

package/dist/server/sanitize-request.js

@@ -7,22 +7,36 @@ function serializeCookies(cookies) {
 	return parts.join("; ");
 }
 /**
-* 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.
+* 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.
 *
-* Used by `createAppConnectRequestHandler` so the user's route
-* handlers never see — and therefore cannot leak — the access token,
-* session ID, or refresh-token cookies.
+* Used by the SDK's auth middleware after it has read the access
+* token / session ID, so user route handlers never see — and
+* therefore cannot leak — those cookies, while CORS / auth
+* middleware that ran first still got the raw values.
 */
-function sanitizeRequest(original) {
-	const cookies = parseCookies(original.headers.get("Cookie"));
+function stripProtectedCookies(headers) {
+	const cookies = parseCookies(headers.get("Cookie"));
 	const surviving = /* @__PURE__ */ new Map();
 	for (const [name, value] of Object.entries(cookies)) if (!isProtectedCookieName(name)) surviving.set(name, value);
-	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.
+*
+* Standalone helper retained for callers that want a new Request
+* (e.g. tests). Inside the SDK's per-request handler, the auth
+* middleware uses {@link stripProtectedCookies} directly on
+* `c.req.raw.headers` so the auth check itself can still read the
+* protected cookies before they are stripped.
+*/
+function sanitizeRequest(original) {
+	const headers = new Headers(original.headers);
+	stripProtectedCookies(headers);
 	const init = {
 		method: original.method,
 		headers,

package/dist/server/sanitize-request.js.map

@@ -1 +1 @@
-{"version":3,"file":"sanitize-request.js","names":[],"sources":["../../src/server/sanitize-request.ts"],"sourcesContent":["import { isProtectedCookieName } from './constants.ts';\nimport { parseCookies } from './utils/cookie-utils.ts';\n\nfunction serializeCookies(cookies: Map<string, string>): string {\n  const parts: string[] = [];\n  for (const [name, value] of cookies) {\n    parts.push(`${name}=${value}`);\n  }\n  return parts.join('; ');\n}\n\n/**\n * Returns a clone of `original` whose `Cookie` header has every\n * protected cookie removed (see\n * {@link isProtectedCookieName}). When no other cookies\n * remain, the header is dropped entirely.\n *\n * Used by `createAppConnectRequestHandler` so the user's route\n * handlers never see — and therefore cannot leak — the access token,\n * session ID, or refresh-token cookies.\n */\nexport function sanitizeRequest(original: Request): Request {\n  const cookies = parseCookies(original.headers.get('Cookie'));\n\n  const surviving = new Map<string, string>();\n  for (const [name, value] of Object.entries(cookies)) {\n    if (!isProtectedCookieName(name)) {\n      surviving.set(name, value);\n    }\n  }\n\n  const headers = new Headers(original.headers);\n  if (surviving.size === 0) {\n    headers.delete('cookie');\n  } else {\n    headers.set('cookie', serializeCookies(surviving));\n  }\n\n  const init: RequestInit = {\n    method: original.method,\n    headers,\n    redirect: original.redirect,\n    signal: original.signal,\n  };\n\n  if (original.body !== null) {\n    init.body = original.body;\n    (init as RequestInit & { duplex: 'half' }).duplex = 'half';\n  }\n\n  return new Request(original.url, init);\n}\n"],"mappings":";;;AAGA,SAAS,iBAAiB,SAAsC;CAC9D,MAAM,QAAkB,EAAE;CAC1B,KAAK,MAAM,CAAC,MAAM,UAAU,SAC1B,MAAM,KAAK,GAAG,KAAK,GAAG,QAAQ;CAEhC,OAAO,MAAM,KAAK,KAAK;;;;;;;;;;;;AAazB,SAAgB,gBAAgB,UAA4B;CAC1D,MAAM,UAAU,aAAa,SAAS,QAAQ,IAAI,SAAS,CAAC;CAE5D,MAAM,4BAAY,IAAI,KAAqB;CAC3C,KAAK,MAAM,CAAC,MAAM,UAAU,OAAO,QAAQ,QAAQ,EACjD,IAAI,CAAC,sBAAsB,KAAK,EAC9B,UAAU,IAAI,MAAM,MAAM;CAI9B,MAAM,UAAU,IAAI,QAAQ,SAAS,QAAQ;CAC7C,IAAI,UAAU,SAAS,GACrB,QAAQ,OAAO,SAAS;MAExB,QAAQ,IAAI,UAAU,iBAAiB,UAAU,CAAC;CAGpD,MAAM,OAAoB;EACxB,QAAQ,SAAS;EACjB;EACA,UAAU,SAAS;EACnB,QAAQ,SAAS;EAClB;CAED,IAAI,SAAS,SAAS,MAAM;EAC1B,KAAK,OAAO,SAAS;EACrB,KAA2C,SAAS;;CAGtD,OAAO,IAAI,QAAQ,SAAS,KAAK,KAAK"}
+{"version":3,"file":"sanitize-request.js","names":[],"sources":["../../src/server/sanitize-request.ts"],"sourcesContent":["import { isProtectedCookieName } from './constants.ts';\nimport { parseCookies } from './utils/cookie-utils.ts';\n\nfunction serializeCookies(cookies: Map<string, string>): string {\n  const parts: string[] = [];\n  for (const [name, value] of cookies) {\n    parts.push(`${name}=${value}`);\n  }\n  return parts.join('; ');\n}\n\n/**\n * Mutates `headers` in place: parses the `Cookie` header, drops every\n * protected cookie (see {@link isProtectedCookieName}), and rewrites\n * the header. Deletes the header entirely when nothing survives.\n *\n * Used by the SDK's auth middleware after it has read the access\n * token / session ID, so user route handlers never see — and\n * therefore cannot leak — those cookies, while CORS / auth\n * middleware that ran first still got the raw values.\n */\nexport function stripProtectedCookies(headers: Headers): void {\n  const cookies = parseCookies(headers.get('Cookie'));\n  const surviving = new Map<string, string>();\n  for (const [name, value] of Object.entries(cookies)) {\n    if (!isProtectedCookieName(name)) {\n      surviving.set(name, value);\n    }\n  }\n\n  if (surviving.size === 0) {\n    headers.delete('cookie');\n  } else {\n    headers.set('cookie', serializeCookies(surviving));\n  }\n}\n\n/**\n * Returns a clone of `original` whose `Cookie` header has every\n * protected cookie removed (see {@link isProtectedCookieName}). When\n * no other cookies remain, the header is dropped entirely.\n *\n * Standalone helper retained for callers that want a new Request\n * (e.g. tests). Inside the SDK's per-request handler, the auth\n * middleware uses {@link stripProtectedCookies} directly on\n * `c.req.raw.headers` so the auth check itself can still read the\n * protected cookies before they are stripped.\n */\nexport function sanitizeRequest(original: Request): Request {\n  const headers = new Headers(original.headers);\n  stripProtectedCookies(headers);\n\n  const init: RequestInit = {\n    method: original.method,\n    headers,\n    redirect: original.redirect,\n    signal: original.signal,\n  };\n\n  if (original.body !== null) {\n    init.body = original.body;\n    (init as RequestInit & { duplex: 'half' }).duplex = 'half';\n  }\n\n  return new Request(original.url, init);\n}\n"],"mappings":";;;AAGA,SAAS,iBAAiB,SAAsC;CAC9D,MAAM,QAAkB,EAAE;CAC1B,KAAK,MAAM,CAAC,MAAM,UAAU,SAC1B,MAAM,KAAK,GAAG,KAAK,GAAG,QAAQ;CAEhC,OAAO,MAAM,KAAK,KAAK;;;;;;;;;;;;AAazB,SAAgB,sBAAsB,SAAwB;CAC5D,MAAM,UAAU,aAAa,QAAQ,IAAI,SAAS,CAAC;CACnD,MAAM,4BAAY,IAAI,KAAqB;CAC3C,KAAK,MAAM,CAAC,MAAM,UAAU,OAAO,QAAQ,QAAQ,EACjD,IAAI,CAAC,sBAAsB,KAAK,EAC9B,UAAU,IAAI,MAAM,MAAM;CAI9B,IAAI,UAAU,SAAS,GACrB,QAAQ,OAAO,SAAS;MAExB,QAAQ,IAAI,UAAU,iBAAiB,UAAU,CAAC;;;;;;;;;;;;;AAetD,SAAgB,gBAAgB,UAA4B;CAC1D,MAAM,UAAU,IAAI,QAAQ,SAAS,QAAQ;CAC7C,sBAAsB,QAAQ;CAE9B,MAAM,OAAoB;EACxB,QAAQ,SAAS;EACjB;EACA,UAAU,SAAS;EACnB,QAAQ,SAAS;EAClB;CAED,IAAI,SAAS,SAAS,MAAM;EAC1B,KAAK,OAAO,SAAS;EACrB,KAA2C,SAAS;;CAGtD,OAAO,IAAI,QAAQ,SAAS,KAAK,KAAK"}

package/dist/server/shared/constants.js

@@ -1,17 +1,30 @@
 //#region src/shared/constants.ts
 /**
-* Constants whose values are part of the contract between the browser
-* controller and the server-side hubspot-connect routes. Both halves
-* import from this module so the wire format stays in sync.
+* 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.
 */
+const HUBSPOT_FRONTEND_CALLBACK_PATH = "/__hubspot_oauth_callback";
 /**
-* 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`.
+* Query parameter on the `auth/complete` POST request carrying the
+* authorization `code` HubSpot returned to the frontend callback.
 */
-const EXPIRES_AT_URL_PARAM = "__hs_expires_at";
+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.
+*/
+const AUTH_COMPLETE_STATE_PARAM = "state";
 //#endregion
-export { EXPIRES_AT_URL_PARAM };
+export { AUTH_COMPLETE_CODE_PARAM, AUTH_COMPLETE_STATE_PARAM, HUBSPOT_FRONTEND_CALLBACK_PATH };
 
 //# sourceMappingURL=constants.js.map

package/dist/server/shared/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","names":[],"sources":["../../../src/shared/constants.ts"],"sourcesContent":["/**\n * Constants whose values are part of the contract between the browser\n * controller and the server-side hubspot-connect routes. Both halves\n * import from this module so the wire format stays in sync.\n */\n\n/**\n * Query parameter on the OAuth return URL that carries the new access\n * token's expiry (Unix epoch milliseconds). The server emits this on\n * the `auth/callback` redirect; the browser parses it during `initSdk`\n * and then strips it from the URL via `history.replaceState`.\n */\nexport const EXPIRES_AT_URL_PARAM = '__hs_expires_at';\n"],"mappings":";;;;;;;;;;;;AAYA,MAAa,uBAAuB"}
+{"version":3,"file":"constants.js","names":[],"sources":["../../../src/shared/constants.ts"],"sourcesContent":["/**\n * Constants whose values are part of the contract between the browser\n * controller and the server-side hubspot-connect routes. Both halves\n * import from this module so the wire format stays in sync.\n */\n\n/**\n * Query parameter on the OAuth return URL that carries the new access\n * token's expiry (Unix epoch milliseconds). The browser controller\n * sets this in the URL after a successful `auth/complete` call and\n * then strips it during `initAppConnect` via `history.replaceState`.\n */\nexport const EXPIRES_AT_URL_PARAM = '__hs_expires_at';\n\n/**\n * Path the browser visits after HubSpot's authorize endpoint\n * redirects back to the app. Mounted on the **frontend** origin (not\n * the SDK's edge function host) so all OAuth-related cookies live in\n * the `(frontend, edge)` CHIPS partition.\n *\n * The SDK's `auth/init-session` builds the OAuth `redirect_uri` as\n * `${requestOrigin}${HUBSPOT_FRONTEND_CALLBACK_PATH}`. The browser\n * controller, on `start()`, recognizes this path on `window.location`\n * and forwards `?code` + `?state` to the SDK's `auth/complete`\n * endpoint via a credentialed cross-site fetch. The host app must\n * register `${app_origin}${HUBSPOT_FRONTEND_CALLBACK_PATH}` as a\n * redirect URI in its HubSpot app settings.\n */\nexport const HUBSPOT_FRONTEND_CALLBACK_PATH = '/__hubspot_oauth_callback';\n\n/**\n * Query parameter on the `auth/complete` POST request carrying the\n * authorization `code` HubSpot returned to the frontend callback.\n */\nexport const AUTH_COMPLETE_CODE_PARAM = 'code';\n\n/**\n * Query parameter on the `auth/complete` POST request carrying the\n * OAuth `state` HubSpot echoed back to the frontend callback.\n */\nexport const AUTH_COMPLETE_STATE_PARAM = 'state';\n"],"mappings":";;;;;;;;;;;;;;;AA4BA,MAAa,iCAAiC;;;;;AAM9C,MAAa,2BAA2B;;;;;AAMxC,MAAa,4BAA4B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hubspot/app-connect-sdk",
-  "version": "1.0.0-alpha.2",
+  "version": "1.0.0-alpha.3",
   "description": "HubSpot App Connect SDK (alpha release). Documentation and integration guidance forthcoming.",
   "type": "module",
   "exports": {
@@ -50,9 +50,9 @@
     "tsdown": "0.22.0-beta.3",
     "typescript": "6.0.3",
     "vitest": "4.0.18",
+    "@private/prettier-config": "0.1.0",
     "@private/tsconfig": "0.1.0",
-    "@private/eslint-config": "0.1.0",
-    "@private/prettier-config": "0.1.0"
+    "@private/eslint-config": "0.1.0"
   },
   "scripts": {
     "clean": "rm -rf dist build *.tsbuildinfo node_modules .turbo",

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';