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

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

@@ -1 +1 @@
-{"version":3,"file":"logger.js","names":[],"sources":["../../../src/shared/logger.ts"],"sourcesContent":["/**\n * Pluggable logger contract used by the SDK on both the browser and\n * server. Consumers can pass `console`-like loggers, structured\n * loggers (pino / winston / etc.) or no-op stubs in tests.\n */\nexport interface Logger {\n  debug: (message: string, ...args: unknown[]) => void;\n  info: (message: string, ...args: unknown[]) => void;\n  warn: (message: string, ...args: unknown[]) => void;\n  error: (message: string, ...args: unknown[]) => void;\n}\n\nfunction formatPrefix(name: string): string {\n  return `[${name}]`;\n}\n\n/**\n * Creates a console-backed logger that prefixes every line with the\n * supplied `name`. Used as the default when no custom logger is\n * provided.\n */\nexport function createLogger(name: string): Logger {\n  const prefix = formatPrefix(name);\n  return {\n    debug: (message, ...args) => {\n      console.debug(prefix, message, ...args);\n    },\n    info: (message, ...args) => {\n      console.info(prefix, message, ...args);\n    },\n    warn: (message, ...args) => {\n      console.warn(prefix, message, ...args);\n    },\n    error: (message, ...args) => {\n      console.error(prefix, message, ...args);\n    },\n  };\n}\n\n/**\n * Logger that swallows every message. Convenient for tests and for\n * the SDK's server-side handlers when no logger is provided by the\n * host application.\n */\nexport const noopLogger: Logger = {\n  debug: () => {},\n  info: () => {},\n  warn: () => {},\n  error: () => {},\n};\n"],"mappings":";;;;;;AA4CA,MAAa,aAAqB;CAChC,aAAa;CACb,YAAY;CACZ,YAAY;CACZ,aAAa;CACd"}
+{"version":3,"file":"logger.js","names":[],"sources":["../../../src/shared/logger.ts"],"sourcesContent":["/**\n * Pluggable logger contract used by the SDK on both the browser and\n * server. Consumers can pass `console`-like loggers, structured\n * loggers (pino / winston / etc.) or no-op stubs in tests.\n */\nexport interface Logger {\n  debug: (message: string, ...args: unknown[]) => void;\n  info: (message: string, ...args: unknown[]) => void;\n  warn: (message: string, ...args: unknown[]) => void;\n  error: (message: string, ...args: unknown[]) => void;\n}\n\nfunction formatPrefix(name: string): string {\n  return `[${name}]`;\n}\n\n/**\n * Creates a console-backed logger that prefixes every line with the\n * supplied `name`. Used as the default when no custom logger is\n * provided.\n */\nexport function createLogger(name: string): Logger {\n  const prefix = formatPrefix(name);\n  return {\n    debug: (message, ...args) => {\n      console.debug(prefix, message, ...args);\n    },\n    info: (message, ...args) => {\n      console.info(prefix, message, ...args);\n    },\n    warn: (message, ...args) => {\n      console.warn(prefix, message, ...args);\n    },\n    error: (message, ...args) => {\n      console.error(prefix, message, ...args);\n    },\n  };\n}\n\n/**\n * Logger that swallows every message. Convenient for tests and for\n * the SDK's server-side handlers when no logger is provided by the\n * host application.\n */\nexport const noopLogger: Logger = {\n  debug: () => {},\n  info: () => {},\n  warn: () => {},\n  error: () => {},\n};\n"],"mappings":";;;;;;AA4CA,MAAa,aAAqB;CAChC,aAAa,CAAC;CACd,YAAY,CAAC;CACb,YAAY,CAAC;CACb,aAAa,CAAC;AAChB"}

package/dist/server/types.d.ts

@@ -10,40 +10,6 @@ interface AppKeys {
   /** Public key in JWK form. Used to derive the JWK thumbprint and `cnf`. */
   appPublicKeyJwk: JsonWebKey;
 }
-/**
- * Request shape accepted by `HubSpotProxy.fetch`. Only the `path`
- * is required; everything else mirrors the equivalent fetch fields.
- */
-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.
- */
-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.
@@ -52,5 +18,5 @@ interface JwkSet {
   keys: JsonWebKey[];
 }
 //#endregion
-export { AppKeys, HubSpotProxy, JwkSet };
+export { AppKeys, JwkSet };
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"cookie-utils.js","names":[],"sources":["../../../src/server/utils/cookie-utils.ts"],"sourcesContent":["/**\n * Parses an HTTP `Cookie` request header into a `name -> value` map.\n * Tolerates leading/trailing whitespace, missing `=` (treats the\n * cookie value as empty), and duplicate names (last write wins).\n *\n * Returns an empty object when `cookieHeader` is `null`/`undefined`\n * /empty so callers don't have to null-check the input.\n */\nexport function parseCookies(\n  cookieHeader: string | null | undefined\n): Record<string, string> {\n  if (!cookieHeader) return {};\n  return Object.fromEntries(\n    cookieHeader\n      .split(';')\n      .map((pair) => {\n        const eqIdx = pair.indexOf('=');\n        if (eqIdx === -1) return [pair.trim(), ''] as [string, string];\n        return [pair.slice(0, eqIdx).trim(), pair.slice(eqIdx + 1).trim()] as [\n          string,\n          string,\n        ];\n      })\n      .filter(([name]) => name.length > 0)\n  );\n}\n"],"mappings":";;;;;;;;;AAQA,SAAgB,aACd,cACwB;CACxB,IAAI,CAAC,cAAc,OAAO,EAAE;CAC5B,OAAO,OAAO,YACZ,aACG,MAAM,IAAI,CACV,KAAK,SAAS;EACb,MAAM,QAAQ,KAAK,QAAQ,IAAI;EAC/B,IAAI,UAAU,IAAI,OAAO,CAAC,KAAK,MAAM,EAAE,GAAG;EAC1C,OAAO,CAAC,KAAK,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,MAAM,QAAQ,EAAE,CAAC,MAAM,CAAC;GAIlE,CACD,QAAQ,CAAC,UAAU,KAAK,SAAS,EAAE,CACvC"}
+{"version":3,"file":"cookie-utils.js","names":[],"sources":["../../../src/server/utils/cookie-utils.ts"],"sourcesContent":["/**\n * Parses an HTTP `Cookie` request header into a `name -> value` map.\n * Tolerates leading/trailing whitespace, missing `=` (treats the\n * cookie value as empty), and duplicate names (last write wins).\n *\n * Returns an empty object when `cookieHeader` is `null`/`undefined`\n * /empty so callers don't have to null-check the input.\n */\nexport function parseCookies(\n  cookieHeader: string | null | undefined\n): Record<string, string> {\n  if (!cookieHeader) return {};\n  return Object.fromEntries(\n    cookieHeader\n      .split(';')\n      .map((pair) => {\n        const eqIdx = pair.indexOf('=');\n        if (eqIdx === -1) return [pair.trim(), ''] as [string, string];\n        return [pair.slice(0, eqIdx).trim(), pair.slice(eqIdx + 1).trim()] as [\n          string,\n          string,\n        ];\n      })\n      .filter(([name]) => name.length > 0)\n  );\n}\n"],"mappings":";;;;;;;;;AAQA,SAAgB,aACd,cACwB;CACxB,IAAI,CAAC,cAAc,OAAO,CAAC;CAC3B,OAAO,OAAO,YACZ,aACG,MAAM,GAAG,EACT,KAAK,SAAS;EACb,MAAM,QAAQ,KAAK,QAAQ,GAAG;EAC9B,IAAI,UAAU,IAAI,OAAO,CAAC,KAAK,KAAK,GAAG,EAAE;EACzC,OAAO,CAAC,KAAK,MAAM,GAAG,KAAK,EAAE,KAAK,GAAG,KAAK,MAAM,QAAQ,CAAC,EAAE,KAAK,CAAC;CAInE,CAAC,EACA,QAAQ,CAAC,UAAU,KAAK,SAAS,CAAC,CACvC;AACF"}

package/dist/server/utils/dpop-utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"dpop-utils.js","names":[],"sources":["../../../src/server/utils/dpop-utils.ts"],"sourcesContent":["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"],"mappings":";;;;AAgCA,SAAS,yBAAyB,KAA6B;CAC7D,IACE,IAAI,QAAQ,QACZ,IAAI,QAAQ,WACZ,OAAO,IAAI,MAAM,YACjB,OAAO,IAAI,MAAM,UAEjB,MAAM,IAAI,MAAM,+BAA+B;CAEjD,OAAO;EACL,KAAK;EACL,KAAK;EACL,GAAG,IAAI;EACP,GAAG,IAAI;EACR;;;;;;;;AAgBH,eAAsB,cACpB,SACiB;CACjB,MAAM,EAAE,SAAS,WAAW;CAE5B,OAAO,iBAAiB;EACtB,QAAQ;GAAE,KAAK;GAAS,KAAK;GAAY,KAFzB,yBAAyB,QAAQ,gBAEM;GAAE;EACzD,SAAS;EACT,YAAY,QAAQ;EACrB,CAAC;;;;;;;;;;;;;;;AA+CJ,eAAsB,gBACpB,SAC4B;CAC5B,MAAM,EAAE,OAAO,KAAK,KAAK,KAAK,QAAQ;CACtC,MAAM,QAAQ,MAAM,MAAM,IAAI;CAC9B,IAAI,MAAM,WAAW,GAAG,MAAM,IAAI,MAAM,4BAA4B;CAEpE,MAAM,gBAAgB,MAAM;CAC5B,IAAI,CAAC,eAAe,MAAM,IAAI,MAAM,sBAAsB;CAE1D,MAAM,SAAS,KAAK,MAClB,IAAI,aAAa,CAAC,OAAO,gBAAgB,cAAc,CAAC,CACzD;CAED,IAAI,OAAO,QAAQ,YAAY,MAAM,IAAI,MAAM,0BAA0B;CACzE,IAAI,OAAO,QAAQ,SAAS,MAAM,IAAI,MAAM,6BAA6B;CACzE,MAAM,eAAe,OAAO;CAC5B,IAAI,CAAC,cAAc,MAAM,IAAI,MAAM,6BAA6B;CAGhE,MAAM,SAAS,MADO,mBAAmB;EAAE,OAAO;EAAO;EAAc,CAAC;CAGxE,IAAI,OAAO,QAAQ,KACjB,MAAM,IAAI,MAAM,+BAA+B,IAAI,QAAQ,OAAO,MAAM;CAE1E,IAAI,OAAO,QAAQ,KACjB,MAAM,IAAI,MAAM,+BAA+B,IAAI,QAAQ,OAAO,MAAM;CAE1E,IAAI,QAAQ,KAAA,KAAa,OAAO,QAAQ,KACtC,MAAM,IAAI,MAAM,oBAAoB;CAEtC,IAAI,QAAQ,KAAA,KAAa,OAAO,QAAQ,KACtC,MAAM,IAAI,MAAM,oBAAoB;CAGtC,MAAM,MAAM,KAAK,MAAM,KAAK,KAAK,GAAG,IAAK;CACzC,IAAI,KAAK,IAAI,MAAM,OAAO,IAAI,GAAG,KAC/B,MAAM,IAAI,MAAM,0CAA0C;CAI5D,OAAO;EAAE;EAAc,KAAA,MADL,iBAAiB,EAAE,cAAc,CAAC;EACxB;EAAQ"}
+{"version":3,"file":"dpop-utils.js","names":[],"sources":["../../../src/server/utils/dpop-utils.ts"],"sourcesContent":["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"],"mappings":";;;;AAgCA,SAAS,yBAAyB,KAA6B;CAC7D,IACE,IAAI,QAAQ,QACZ,IAAI,QAAQ,WACZ,OAAO,IAAI,MAAM,YACjB,OAAO,IAAI,MAAM,UAEjB,MAAM,IAAI,MAAM,8BAA8B;CAEhD,OAAO;EACL,KAAK;EACL,KAAK;EACL,GAAG,IAAI;EACP,GAAG,IAAI;CACT;AACF;;;;;;;AAeA,eAAsB,cACpB,SACiB;CACjB,MAAM,EAAE,SAAS,WAAW;CAE5B,OAAO,iBAAiB;EACtB,QAAQ;GAAE,KAAK;GAAS,KAAK;GAAY,KAFzB,yBAAyB,QAAQ,eAEK;EAAE;EACxD,SAAS;EACT,YAAY,QAAQ;CACtB,CAAC;AACH;;;;;;;;;;;;;;AA8CA,eAAsB,gBACpB,SAC4B;CAC5B,MAAM,EAAE,OAAO,KAAK,KAAK,KAAK,QAAQ;CACtC,MAAM,QAAQ,MAAM,MAAM,GAAG;CAC7B,IAAI,MAAM,WAAW,GAAG,MAAM,IAAI,MAAM,2BAA2B;CAEnE,MAAM,gBAAgB,MAAM;CAC5B,IAAI,CAAC,eAAe,MAAM,IAAI,MAAM,qBAAqB;CAEzD,MAAM,SAAS,KAAK,MAClB,IAAI,YAAY,EAAE,OAAO,gBAAgB,aAAa,CAAC,CACzD;CAEA,IAAI,OAAO,QAAQ,YAAY,MAAM,IAAI,MAAM,yBAAyB;CACxE,IAAI,OAAO,QAAQ,SAAS,MAAM,IAAI,MAAM,4BAA4B;CACxE,MAAM,eAAe,OAAO;CAC5B,IAAI,CAAC,cAAc,MAAM,IAAI,MAAM,4BAA4B;CAG/D,MAAM,SAAS,MADO,mBAAmB;EAAE,OAAO;EAAO;CAAa,CAAC;CAGvE,IAAI,OAAO,QAAQ,KACjB,MAAM,IAAI,MAAM,+BAA+B,IAAI,QAAQ,OAAO,KAAK;CAEzE,IAAI,OAAO,QAAQ,KACjB,MAAM,IAAI,MAAM,+BAA+B,IAAI,QAAQ,OAAO,KAAK;CAEzE,IAAI,QAAQ,KAAA,KAAa,OAAO,QAAQ,KACtC,MAAM,IAAI,MAAM,mBAAmB;CAErC,IAAI,QAAQ,KAAA,KAAa,OAAO,QAAQ,KACtC,MAAM,IAAI,MAAM,mBAAmB;CAGrC,MAAM,MAAM,KAAK,MAAM,KAAK,IAAI,IAAI,GAAI;CACxC,IAAI,KAAK,IAAI,MAAM,OAAO,GAAG,IAAI,KAC/B,MAAM,IAAI,MAAM,yCAAyC;CAI3D,OAAO;EAAE;EAAc,KAAA,MADL,iBAAiB,EAAE,aAAa,CAAC;EACvB;CAAO;AACrC"}

package/dist/server/utils/env-utils.js

@@ -1,4 +1,9 @@
 //#region src/server/utils/env-utils.ts
+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`. */
+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
@@ -12,6 +17,15 @@ function getEnv(key) {
 	if (deno !== void 0) return deno.env.get(key);
 }
 /**
+* Reads an environment variable, returning `defaultValue` when it is
+* unset or an empty string.
+*/
+function getEnvWithDefault(key, defaultValue) {
+	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
 * URLs).
@@ -25,20 +39,59 @@ function requireEnv(key) {
 	return value;
 }
 /**
+* HubSpot API origin used by the HubSpot API client transport. Defaults to
+* `https://api.hubapi.com` when `HUBSPOT_API_ORIGIN` is unset.
+*/
+function getHubSpotApiOrigin() {
+	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.
+*/
+function getHubSpotAuthorizationEndpoint() {
+	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.
+*/
+function getHubSpotOAuthApiOrigin() {
+	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.
+*/
+function requireHubSpotClientId() {
+	return requireEnv("HUBSPOT_CLIENT_ID");
+}
+/**
+* Static OAuth client secret. Required when CIMD is disabled.
+*
+* @throws {Error} When `HUBSPOT_CLIENT_SECRET` is unset or empty.
+*/
+function requireHubSpotClientSecret() {
+	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).
 */
 function isHubspotDpopEnabled() {
-	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).
 */
 function isHubspotCimdEnabled() {
-	return getEnv("HUBSPOT_CIMD_ENABLED") !== "false";
+	return getEnv("HUBSPOT_CIMD_ENABLED") === "true";
 }
 /**
 * Whether `HUBSPOT_APP_PRIVATE_KEY` must be set for `secureStart`. False
@@ -49,6 +102,6 @@ function isHubspotAppPrivateKeyRequired() {
 	return isHubspotCimdEnabled() || isHubspotDpopEnabled();
 }
 //#endregion
-export { isHubspotAppPrivateKeyRequired, isHubspotCimdEnabled, isHubspotDpopEnabled, requireEnv };
+export { HUBSPOT_APP_PRIVATE_KEY_ENV, getHubSpotApiOrigin, getHubSpotAuthorizationEndpoint, getHubSpotOAuthApiOrigin, isHubspotAppPrivateKeyRequired, isHubspotCimdEnabled, isHubspotDpopEnabled, requireHubSpotClientId, requireHubSpotClientSecret };
 
 //# sourceMappingURL=env-utils.js.map

package/dist/server/utils/env-utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"env-utils.js","names":[],"sources":["../../../src/server/utils/env-utils.ts"],"sourcesContent":["interface GlobalWithOptionalEnv {\n  process?: { env?: Record<string, string | undefined> };\n  Deno?: { env: { get(name: string): string | undefined } };\n}\n\n/**\n * Reads an environment variable in a way that works under both Node\n * (`process.env`) and Deno (`Deno.env.get`). Returns `undefined` when\n * the variable is unset or when neither runtime is available.\n */\nexport function getEnv(key: string): string | undefined {\n  const g = globalThis as GlobalWithOptionalEnv;\n  const proc = g.process;\n  if (proc?.env) {\n    return proc.env[key];\n  }\n  const deno = g.Deno;\n  if (deno !== undefined) {\n    return deno.env.get(key);\n  }\n  return undefined;\n}\n\n/**\n * Reads an environment variable and throws when it is missing or empty.\n * Use for values the SDK cannot fall back on (e.g. upstream service\n * URLs).\n *\n * @throws {Error} When the environment variable is unset or an empty\n *   string.\n */\nexport function requireEnv(key: string): string {\n  const value = getEnv(key);\n  if (!value) {\n    throw new Error(`Missing required environment variable: ${key}`);\n  }\n  return value;\n}\n\n/**\n * Whether outbound HubSpot OAuth and API calls should attach DPoP on\n * the wire. Disabled only when `HUBSPOT_DPOP_ENABLED` is exactly the\n * string `\"false\"` (unset or any other value keeps DPoP enabled).\n */\nexport function isHubspotDpopEnabled(): boolean {\n  return getEnv('HUBSPOT_DPOP_ENABLED') !== 'false';\n}\n\n/**\n * Whether the SDK should use CIMD-style OAuth (client ID URL + JWT client\n * assertion). Disabled only when `HUBSPOT_CIMD_ENABLED` is exactly the\n * string `\"false\"` (unset or any other value keeps CIMD enabled).\n */\nexport function isHubspotCimdEnabled(): boolean {\n  return getEnv('HUBSPOT_CIMD_ENABLED') !== 'false';\n}\n\n/**\n * Whether `HUBSPOT_APP_PRIVATE_KEY` must be set for `secureStart`. False\n * when both CIMD and DPoP are disabled — the SDK then uses\n * `client_secret` for OAuth and Bearer tokens only for API calls.\n */\nexport function isHubspotAppPrivateKeyRequired(): boolean {\n  return isHubspotCimdEnabled() || isHubspotDpopEnabled();\n}\n"],"mappings":";;;;;;AAUA,SAAgB,OAAO,KAAiC;CACtD,MAAM,IAAI;CACV,MAAM,OAAO,EAAE;CACf,IAAI,MAAM,KACR,OAAO,KAAK,IAAI;CAElB,MAAM,OAAO,EAAE;CACf,IAAI,SAAS,KAAA,GACX,OAAO,KAAK,IAAI,IAAI,IAAI;;;;;;;;;;AAa5B,SAAgB,WAAW,KAAqB;CAC9C,MAAM,QAAQ,OAAO,IAAI;CACzB,IAAI,CAAC,OACH,MAAM,IAAI,MAAM,0CAA0C,MAAM;CAElE,OAAO;;;;;;;AAQT,SAAgB,uBAAgC;CAC9C,OAAO,OAAO,uBAAuB,KAAK;;;;;;;AAQ5C,SAAgB,uBAAgC;CAC9C,OAAO,OAAO,uBAAuB,KAAK;;;;;;;AAQ5C,SAAgB,iCAA0C;CACxD,OAAO,sBAAsB,IAAI,sBAAsB"}
+{"version":3,"file":"env-utils.js","names":[],"sources":["../../../src/server/utils/env-utils.ts"],"sourcesContent":["interface GlobalWithOptionalEnv {\n  process?: { env?: Record<string, string | undefined> };\n  Deno?: { env: { get(name: string): string | undefined } };\n}\n\nconst HUBSPOT_API_ORIGIN_DEFAULT = 'https://api.hubapi.com';\n\nconst HUBSPOT_OAUTH_API_ORIGIN_DEFAULT = 'https://api.hubapi.com';\n\nconst HUBSPOT_AUTHORIZATION_ENDPOINT_DEFAULT =\n  'https://app.hubspot.com/oauth/authorize';\n\n/** Environment variable name for the app private key loaded by `secureStart`. */\nexport const HUBSPOT_APP_PRIVATE_KEY_ENV = 'HUBSPOT_APP_PRIVATE_KEY';\n\n/**\n * Reads an environment variable in a way that works under both Node\n * (`process.env`) and Deno (`Deno.env.get`). Returns `undefined` when\n * the variable is unset or when neither runtime is available.\n */\nexport function getEnv(key: string): string | undefined {\n  const g = globalThis as GlobalWithOptionalEnv;\n  const proc = g.process;\n  if (proc?.env) {\n    return proc.env[key];\n  }\n  const deno = g.Deno;\n  if (deno !== undefined) {\n    return deno.env.get(key);\n  }\n  return undefined;\n}\n\n/**\n * Reads an environment variable, returning `defaultValue` when it is\n * unset or an empty string.\n */\nexport function getEnvWithDefault(key: string, defaultValue: string): string {\n  const value = getEnv(key);\n  if (!value) {\n    return defaultValue;\n  }\n  return value;\n}\n\n/**\n * Reads an environment variable and throws when it is missing or empty.\n * Use for values the SDK cannot fall back on (e.g. upstream service\n * URLs).\n *\n * @throws {Error} When the environment variable is unset or an empty\n *   string.\n */\nexport function requireEnv(key: string): string {\n  const value = getEnv(key);\n  if (!value) {\n    throw new Error(`Missing required environment variable: ${key}`);\n  }\n  return value;\n}\n\n/**\n * HubSpot API origin used by the HubSpot API client transport. Defaults to\n * `https://api.hubapi.com` when `HUBSPOT_API_ORIGIN` is unset.\n */\nexport function getHubSpotApiOrigin(): string {\n  return getEnvWithDefault('HUBSPOT_API_ORIGIN', HUBSPOT_API_ORIGIN_DEFAULT);\n}\n\n/**\n * Full OAuth authorize URL for hubspot-connect routes. Defaults to\n * `https://app.hubspot.com/oauth/authorize` when\n * `HUBSPOT_AUTHORIZATION_ENDPOINT` is unset.\n */\nexport function getHubSpotAuthorizationEndpoint(): string {\n  return getEnvWithDefault(\n    'HUBSPOT_AUTHORIZATION_ENDPOINT',\n    HUBSPOT_AUTHORIZATION_ENDPOINT_DEFAULT\n  );\n}\n\n/**\n * HubSpot OAuth API origin (token, revoke, JWKS). Normalized to a URL\n * origin. Defaults to `https://api.hubapi.com` when\n * `HUBSPOT_OAUTH_API_ORIGIN` is unset.\n */\nexport function getHubSpotOAuthApiOrigin(): string {\n  return new URL(\n    getEnvWithDefault(\n      'HUBSPOT_OAUTH_API_ORIGIN',\n      HUBSPOT_OAUTH_API_ORIGIN_DEFAULT\n    )\n  ).origin;\n}\n\n/**\n * Static OAuth client ID. Required when CIMD is disabled.\n *\n * @throws {Error} When `HUBSPOT_CLIENT_ID` is unset or empty.\n */\nexport function requireHubSpotClientId(): string {\n  return requireEnv('HUBSPOT_CLIENT_ID');\n}\n\n/**\n * Static OAuth client secret. Required when CIMD is disabled.\n *\n * @throws {Error} When `HUBSPOT_CLIENT_SECRET` is unset or empty.\n */\nexport function requireHubSpotClientSecret(): string {\n  return requireEnv('HUBSPOT_CLIENT_SECRET');\n}\n\n/**\n * Whether outbound HubSpot OAuth and API calls should attach DPoP on\n * the wire. Enabled only when `HUBSPOT_DPOP_ENABLED` is exactly the\n * string `\"true\"` (unset or any other value keeps DPoP disabled).\n */\nexport function isHubspotDpopEnabled(): boolean {\n  return getEnv('HUBSPOT_DPOP_ENABLED') === 'true';\n}\n\n/**\n * Whether the SDK should use CIMD-style OAuth (client ID URL + JWT client\n * assertion). Enabled only when `HUBSPOT_CIMD_ENABLED` is exactly the\n * string `\"true\"` (unset or any other value keeps CIMD disabled).\n */\nexport function isHubspotCimdEnabled(): boolean {\n  return getEnv('HUBSPOT_CIMD_ENABLED') === 'true';\n}\n\n/**\n * Whether `HUBSPOT_APP_PRIVATE_KEY` must be set for `secureStart`. False\n * when both CIMD and DPoP are disabled — the SDK then uses\n * `client_secret` for OAuth and Bearer tokens only for API calls.\n */\nexport function isHubspotAppPrivateKeyRequired(): boolean {\n  return isHubspotCimdEnabled() || isHubspotDpopEnabled();\n}\n"],"mappings":";AAKA,MAAM,6BAA6B;AAEnC,MAAM,mCAAmC;AAEzC,MAAM,yCACJ;;AAGF,MAAa,8BAA8B;;;;;;AAO3C,SAAgB,OAAO,KAAiC;CACtD,MAAM,IAAI;CACV,MAAM,OAAO,EAAE;CACf,IAAI,MAAM,KACR,OAAO,KAAK,IAAI;CAElB,MAAM,OAAO,EAAE;CACf,IAAI,SAAS,KAAA,GACX,OAAO,KAAK,IAAI,IAAI,GAAG;AAG3B;;;;;AAMA,SAAgB,kBAAkB,KAAa,cAA8B;CAC3E,MAAM,QAAQ,OAAO,GAAG;CACxB,IAAI,CAAC,OACH,OAAO;CAET,OAAO;AACT;;;;;;;;;AAUA,SAAgB,WAAW,KAAqB;CAC9C,MAAM,QAAQ,OAAO,GAAG;CACxB,IAAI,CAAC,OACH,MAAM,IAAI,MAAM,0CAA0C,KAAK;CAEjE,OAAO;AACT;;;;;AAMA,SAAgB,sBAA8B;CAC5C,OAAO,kBAAkB,sBAAsB,0BAA0B;AAC3E;;;;;;AAOA,SAAgB,kCAA0C;CACxD,OAAO,kBACL,kCACA,sCACF;AACF;;;;;;AAOA,SAAgB,2BAAmC;CACjD,OAAO,IAAI,IACT,kBACE,4BACA,gCACF,CACF,EAAE;AACJ;;;;;;AAOA,SAAgB,yBAAiC;CAC/C,OAAO,WAAW,mBAAmB;AACvC;;;;;;AAOA,SAAgB,6BAAqC;CACnD,OAAO,WAAW,uBAAuB;AAC3C;;;;;;AAOA,SAAgB,uBAAgC;CAC9C,OAAO,OAAO,sBAAsB,MAAM;AAC5C;;;;;;AAOA,SAAgB,uBAAgC;CAC9C,OAAO,OAAO,sBAAsB,MAAM;AAC5C;;;;;;AAOA,SAAgB,iCAA0C;CACxD,OAAO,qBAAqB,KAAK,qBAAqB;AACxD"}

package/dist/server/utils/hubspot-dpop-auth-headers.js

@@ -0,0 +1,38 @@
+import { signDpopProof } from "./dpop-utils.js";
+import { sha256base64url } from "../shared/encoding/sha256.js";
+//#region src/server/utils/hubspot-dpop-auth-headers.ts
+function getDpopHtuFromTargetUrl(targetUrl) {
+	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.
+*/
+async function buildHubSpotDpopAuthHeaders(options) {
+	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() / 1e3),
+			ath,
+			sid
+		}
+	});
+	return {
+		Authorization: `DPoP ${accessToken}`,
+		DPoP: dpopProof
+	};
+}
+//#endregion
+export { buildHubSpotDpopAuthHeaders };
+
+//# sourceMappingURL=hubspot-dpop-auth-headers.js.map

package/dist/server/utils/hubspot-dpop-auth-headers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hubspot-dpop-auth-headers.js","names":[],"sources":["../../../src/server/utils/hubspot-dpop-auth-headers.ts"],"sourcesContent":["import { type AppKeys } from '../types.ts';\nimport { sha256base64url } from './crypto-utils.ts';\nimport { signDpopProof } from './dpop-utils.ts';\n\nexport interface BuildHubSpotDpopAuthHeadersOptions {\n  accessToken: string;\n  sessionId: string;\n  appKeys: AppKeys;\n  method: string;\n  targetUrl: string;\n}\n\nfunction getDpopHtuFromTargetUrl(targetUrl: string): string {\n  const url = new URL(targetUrl);\n  url.search = '';\n  url.hash = '';\n  return url.toString();\n}\n\n/**\n * Builds `Authorization` and `DPoP` headers for an authenticated\n * HubSpot API request when DPoP is enabled.\n */\nexport async function buildHubSpotDpopAuthHeaders(\n  options: BuildHubSpotDpopAuthHeadersOptions\n): Promise<Record<string, string>> {\n  const { accessToken, sessionId, appKeys, method, targetUrl } = options;\n  const htu = getDpopHtuFromTargetUrl(targetUrl);\n\n  const ath = await sha256base64url(accessToken);\n  const sid = await sha256base64url(sessionId);\n  const dpopProof = await signDpopProof({\n    appKeys,\n    claims: {\n      htm: method,\n      htu,\n      jti: crypto.randomUUID(),\n      iat: Math.floor(Date.now() / 1000),\n      ath,\n      sid,\n    },\n  });\n\n  return {\n    Authorization: `DPoP ${accessToken}`,\n    DPoP: dpopProof,\n  };\n}\n"],"mappings":";;;AAYA,SAAS,wBAAwB,WAA2B;CAC1D,MAAM,MAAM,IAAI,IAAI,SAAS;CAC7B,IAAI,SAAS;CACb,IAAI,OAAO;CACX,OAAO,IAAI,SAAS;AACtB;;;;;AAMA,eAAsB,4BACpB,SACiC;CACjC,MAAM,EAAE,aAAa,WAAW,SAAS,QAAQ,cAAc;CAC/D,MAAM,MAAM,wBAAwB,SAAS;CAE7C,MAAM,MAAM,MAAM,gBAAgB,WAAW;CAC7C,MAAM,MAAM,MAAM,gBAAgB,SAAS;CAC3C,MAAM,YAAY,MAAM,cAAc;EACpC;EACA,QAAQ;GACN,KAAK;GACL;GACA,KAAK,OAAO,WAAW;GACvB,KAAK,KAAK,MAAM,KAAK,IAAI,IAAI,GAAI;GACjC;GACA;EACF;CACF,CAAC;CAED,OAAO;EACL,eAAe,QAAQ;EACvB,MAAM;CACR;AACF"}

package/dist/server/utils/jwk-utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"jwk-utils.js","names":[],"sources":["../../../src/server/utils/jwk-utils.ts"],"sourcesContent":["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"],"mappings":";;;;;;;;;AAcA,eAAsB,iBACpB,SACiB;CACjB,MAAM,EAAE,iBAAiB;CACzB,MAAM,YAAY,KAAK,UAAU;EAC/B,KAAK,aAAa;EAClB,KAAK,aAAa;EAClB,GAAG,aAAa;EAChB,GAAG,aAAa;EACjB,CAAC;CACF,MAAM,SAAS,MAAM,OAAO,OAAO,OACjC,WACA,IAAI,aAAa,CAAC,OAAO,UAAU,CACpC;CACD,OAAO,UAAU,IAAI,WAAW,OAAO,CAAC"}
+{"version":3,"file":"jwk-utils.js","names":[],"sources":["../../../src/server/utils/jwk-utils.ts"],"sourcesContent":["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"],"mappings":";;;;;;;;;AAcA,eAAsB,iBACpB,SACiB;CACjB,MAAM,EAAE,iBAAiB;CACzB,MAAM,YAAY,KAAK,UAAU;EAC/B,KAAK,aAAa;EAClB,KAAK,aAAa;EAClB,GAAG,aAAa;EAChB,GAAG,aAAa;CAClB,CAAC;CACD,MAAM,SAAS,MAAM,OAAO,OAAO,OACjC,WACA,IAAI,YAAY,EAAE,OAAO,SAAS,CACpC;CACA,OAAO,UAAU,IAAI,WAAW,MAAM,CAAC;AACzC"}

package/dist/server/utils/jwt-utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"jwt-utils.js","names":[],"sources":["../../../src/server/utils/jwt-utils.ts"],"sourcesContent":["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"],"mappings":";;;;;;;AAaA,eAAsB,iBACpB,SACiB;CACjB,MAAM,EAAE,QAAQ,SAAS,eAAe;CAQxC,MAAM,eAAe,GANC,UACpB,IAAI,aAAa,CAAC,OAAO,KAAK,UAAU,OAAO,CAAC,CAKb,CAAC,GAHf,UACrB,IAAI,aAAa,CAAC,OAAO,KAAK,UAAU,QAAQ,CAAC,CAEI;CACvD,MAAM,kBAAkB,MAAM,OAAO,OAAO,KAC1C;EAAE,MAAM;EAAS,MAAM;EAAW,EAClC,YACA,IAAI,aAAa,CAAC,OAAO,aAAa,CACvC;CACD,OAAO,GAAG,aAAa,GAAG,UAAU,IAAI,WAAW,gBAAgB,CAAC;;AAGtE,eAAe,gBAAgB,KAAqC;CAClE,OAAO,OAAO,OAAO,UACnB,OACA,KACA;EAAE,MAAM;EAAS,YAAY;EAAS,EACtC,OACA,CAAC,SAAS,CACX;;;;;;;;;;;AAiBH,eAAsB,mBACpB,SACkC;CAClC,MAAM,EAAE,OAAO,iBAAiB;CAChC,MAAM,QAAQ,MAAM,MAAM,IAAI;CAC9B,IAAI,MAAM,WAAW,GAAG,MAAM,IAAI,MAAM,qBAAqB;CAC7D,MAAM,CAAC,eAAe,gBAAgB,oBAAoB;CAK1D,MAAM,YAAY,MAAM,gBAAgB,aAAa;CAOrD,IAAI,CAAC,MANe,OAAO,OAAO,OAChC;EAAE,MAAM;EAAS,MAAM;EAAW,EAClC,WACA,gBAAgB,iBAAiB,EACjC,IAAI,aAAa,CAAC,OAAO,GAAG,cAAc,GAAG,iBAAiB,CAC/D,EACW,MAAM,IAAI,MAAM,oCAAoC;CAChE,OAAO,KAAK,MACV,IAAI,aAAa,CAAC,OAAO,gBAAgB,eAAe,CAAC,CAC1D;;;;;;;;AAgBH,eAAsB,UACpB,SACkC;CAClC,MAAM,EAAE,OAAO,iBAAiB;CAChC,MAAM,UAAU,MAAM,mBAAmB;EAAE;EAAO;EAAc,CAAC;CACjE,MAAM,MAAM,KAAK,MAAM,KAAK,KAAK,GAAG,IAAK;CACzC,IAAI,OAAO,QAAQ,WAAW,YAAY,QAAQ,SAAS,KACzD,MAAM,IAAI,MAAM,cAAc;CAEhC,OAAO;;;;;;;AAyBT,eAAsB,QAAQ,SAA0C;CACtE,MAAM,EAAE,YAAY,SAAS,eAAe;CAC5C,MAAM,MAAM,KAAK,MAAM,KAAK,KAAK,GAAG,IAAK;CAKzC,OAAO,iBAAiB;EACtB,QAAQ;GAAE,KAAK;GAAS,KAAK;GAAO;EACpC,SALA,eAAe,KAAA,IACX;GAAE,KAAK;GAAK,KAAK,MAAM;GAAY,GAAG;GAAS,GAC/C;GAAE,KAAK;GAAK,GAAG;GAAS;EAI5B;EACD,CAAC"}
+{"version":3,"file":"jwt-utils.js","names":[],"sources":["../../../src/server/utils/jwt-utils.ts"],"sourcesContent":["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"],"mappings":";;;;;;;AAaA,eAAsB,iBACpB,SACiB;CACjB,MAAM,EAAE,QAAQ,SAAS,eAAe;CAQxC,MAAM,eAAe,GANC,UACpB,IAAI,YAAY,EAAE,OAAO,KAAK,UAAU,MAAM,CAAC,CAKb,EAAE,GAHf,UACrB,IAAI,YAAY,EAAE,OAAO,KAAK,UAAU,OAAO,CAAC,CAEI;CACtD,MAAM,kBAAkB,MAAM,OAAO,OAAO,KAC1C;EAAE,MAAM;EAAS,MAAM;CAAU,GACjC,YACA,IAAI,YAAY,EAAE,OAAO,YAAY,CACvC;CACA,OAAO,GAAG,aAAa,GAAG,UAAU,IAAI,WAAW,eAAe,CAAC;AACrE;AAEA,eAAe,gBAAgB,KAAqC;CAClE,OAAO,OAAO,OAAO,UACnB,OACA,KACA;EAAE,MAAM;EAAS,YAAY;CAAQ,GACrC,OACA,CAAC,QAAQ,CACX;AACF;;;;;;;;;;AAgBA,eAAsB,mBACpB,SACkC;CAClC,MAAM,EAAE,OAAO,iBAAiB;CAChC,MAAM,QAAQ,MAAM,MAAM,GAAG;CAC7B,IAAI,MAAM,WAAW,GAAG,MAAM,IAAI,MAAM,oBAAoB;CAC5D,MAAM,CAAC,eAAe,gBAAgB,oBAAoB;CAK1D,MAAM,YAAY,MAAM,gBAAgB,YAAY;CAOpD,IAAI,CAAC,MANe,OAAO,OAAO,OAChC;EAAE,MAAM;EAAS,MAAM;CAAU,GACjC,WACA,gBAAgB,gBAAgB,GAChC,IAAI,YAAY,EAAE,OAAO,GAAG,cAAc,GAAG,gBAAgB,CAC/D,GACY,MAAM,IAAI,MAAM,mCAAmC;CAC/D,OAAO,KAAK,MACV,IAAI,YAAY,EAAE,OAAO,gBAAgB,cAAc,CAAC,CAC1D;AACF;;;;;;;AAeA,eAAsB,UACpB,SACkC;CAClC,MAAM,EAAE,OAAO,iBAAiB;CAChC,MAAM,UAAU,MAAM,mBAAmB;EAAE;EAAO;CAAa,CAAC;CAChE,MAAM,MAAM,KAAK,MAAM,KAAK,IAAI,IAAI,GAAI;CACxC,IAAI,OAAO,QAAQ,WAAW,YAAY,QAAQ,SAAS,KACzD,MAAM,IAAI,MAAM,aAAa;CAE/B,OAAO;AACT;;;;;;AAwBA,eAAsB,QAAQ,SAA0C;CACtE,MAAM,EAAE,YAAY,SAAS,eAAe;CAC5C,MAAM,MAAM,KAAK,MAAM,KAAK,IAAI,IAAI,GAAI;CAKxC,OAAO,iBAAiB;EACtB,QAAQ;GAAE,KAAK;GAAS,KAAK;EAAM;EACnC,SALA,eAAe,KAAA,IACX;GAAE,KAAK;GAAK,KAAK,MAAM;GAAY,GAAG;EAAQ,IAC9C;GAAE,KAAK;GAAK,GAAG;EAAQ;EAI3B;CACF,CAAC;AACH"}

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@hubspot/app-connect-sdk",
-  "version": "1.0.0-alpha.2",
+  "version": "1.0.0-alpha.20",
   "description": "HubSpot App Connect SDK (alpha release). Documentation and integration guidance forthcoming.",
   "type": "module",
   "exports": {
     "./browser": "./dist/browser/index.js",
     "./react": "./dist/browser/react.js",
     "./react/lovable": "./dist/browser/react/lovable.js",
-    "./server/api-client": "./dist/server/api-client-core.js",
+    "./server/api-client": "./dist/server/api-client.js",
     "./server/lovable": "./dist/server/lovable.js",
     "./server/oauth": "./dist/server/oauth.js"
   },
@@ -23,36 +23,30 @@
   },
   "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.12.19"
   },
   "engines": {
     "node": ">=24.0.0"
   },
   "devDependencies": {
-    "@types/deno": "^2.5.0",
-    "@types/node": "25.6.0",
-    "@types/react": "^19.1.0",
-    "@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",
+    "@types/deno": "2.7.0",
+    "@types/node": "25.9.0",
+    "@types/react": "19.2.14",
+    "@vanilla-extract/css": "1.20.1",
+    "@vanilla-extract/rollup-plugin": "1.5.3",
+    "eslint": "10.4.0",
+    "prettier": "3.8.3",
+    "react": "19.2.6",
+    "tsdown": "0.22.0",
     "typescript": "6.0.3",
-    "vitest": "4.0.18",
-    "@private/tsconfig": "0.1.0",
+    "vitest": "4.1.6",
     "@private/eslint-config": "0.1.0",
-    "@private/prettier-config": "0.1.0"
+    "@private/prettier-config": "0.1.0",
+    "@private/tsconfig": "0.1.0"
   },
   "scripts": {
     "clean": "rm -rf dist build *.tsbuildinfo node_modules .turbo",

package/src/browser/app-connect-controller/README.md

@@ -57,8 +57,11 @@ flowchart TD
 ## Module map
 
 - [create.ts](./create.ts) — factory; the only file [`../index.ts`](../index.ts) imports from. Wires the context, defines `connectToHubSpot` / `disconnectFromHubSpot`, and applies `memoizeLast` to `getSnapshot`.
-- [init.ts](./init.ts) — runs once on `start()`. Reads `?__hs_expires_at=…` from `window.location`, persists it via [`utils/session-utils.ts`](./utils/session-utils.ts), and scrubs the parameter from the address bar with `history.replaceState`.
-- [connect-start.ts](./connect-start.ts) — `GET`s the SDK's `/auth/init-session` route, then full-page redirects to HubSpot's `authorize` URL. The `return_path` is the current path + query so the user lands back where they started.
+- [init.ts](./init.ts) — runs once on `start()`. Redirect flow: POSTs `code` + `state` to `/auth/complete`, persists `expires_at`, `history.replaceState`s to `return_path`. Popup flow (`window.opener`): relays `code` + `state` to the opener and closes (no `auth/complete` in the popup).
+- [connect-start.ts](./connect-start.ts) — `GET`s `/auth/init-session`, then redirects or opens a popup per `config.oauthConnectMode` (`auto` uses a popup when embedded in an iframe). See [oauth-popup.ts](./oauth-popup.ts).
+- [oauth-popup.ts](./oauth-popup.ts) — opener waits for popup `postMessage` with `code` + `state`, then POSTs `/auth/complete`.
+- [oauth-complete.ts](./oauth-complete.ts) — shared credentialed `POST /auth/complete` used by redirect init and the opener popup handler.
+- [utils/resolve-oauth-connect-mode.ts](./utils/resolve-oauth-connect-mode.ts) / [utils/iframe-utils.ts](./utils/iframe-utils.ts) — map `oauthConnectMode` + iframe detection to redirect vs popup.
 - [disconnect.ts](./disconnect.ts) — `POST`s `/auth/logout`, clears local session storage, and redirects to the server-supplied `redirect_to`. Errors are caught and surfaced via `state.error`.
 - [refresh.ts](./refresh.ts) — subscribes to the store and (re)schedules a `/auth/refresh` call whenever `expiresAt` changes. Exposes `RefreshSchedulerHandle.stop()` for teardown.
 - [view-state.ts](./view-state.ts) — `getDerivedStatus` and `SERVER_VIEW` (the SSR snapshot returned by `getServerSnapshot`).

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

@@ -0,0 +1,156 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { noopLogger } from '../../shared/logger.ts';
+import { startHubSpotConnection } from './connect-start.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(
+  oauthConnectMode?: AppConnectContext['config']['oauthConnectMode']
+): AppConnectContext {
+  const initialState: AppConnectInternalState = {
+    isInitComplete: true,
+    isConnectInFlight: true,
+    isSessionConnected: false,
+    isDisconnectInFlight: false,
+    error: null,
+    expiresAt: null,
+  };
+  return {
+    config: {
+      hubSpotConnectBaseUrl: HUBSPOT_CONNECT_BASE_URL,
+      ...(oauthConnectMode !== undefined ? { oauthConnectMode } : {}),
+    },
+    logger: noopLogger,
+    sessionStorage: createInMemorySessionStorage(),
+    store: createStore<AppConnectInternalState>(initialState),
+  };
+}
+
+describe('startHubSpotConnection', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+    vi.useRealTimers();
+  });
+
+  it('redirects the browser when oauthConnectMode is redirect', async () => {
+    const top = {};
+    const location = {
+      origin: 'https://app.example.com',
+      pathname: '/dashboard',
+      search: '?tab=1',
+      href: '',
+    };
+    vi.stubGlobal('window', {
+      self: top,
+      top,
+      location,
+      open: vi.fn(),
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+    });
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+      new Response(
+        JSON.stringify({
+          authorization_url: 'https://auth.example/authorize',
+        }),
+        { status: 200 }
+      )
+    );
+
+    const context = createTestContext('redirect');
+    const connectPromise = startHubSpotConnection(context);
+    await vi.advanceTimersByTimeAsync(500);
+    await connectPromise;
+
+    expect(location.href).toBe('https://auth.example/authorize');
+    expect(window.open).not.toHaveBeenCalled();
+  });
+
+  it('opens a popup when oauthConnectMode is popup', async () => {
+    const top = {};
+    const popup = { closed: false, close: vi.fn() };
+    const messageListeners: Array<(event: MessageEvent) => void> = [];
+
+    vi.stubGlobal('window', {
+      self: top,
+      top,
+      location: {
+        origin: 'https://app.example.com',
+        pathname: '/dashboard',
+        search: '',
+      },
+      open: vi.fn(() => popup),
+      addEventListener: (
+        type: string,
+        listener: (event: MessageEvent) => void
+      ) => {
+        if (type === 'message') messageListeners.push(listener);
+      },
+      removeEventListener: vi.fn(),
+    });
+    const expiresAt = Date.now() + 1800 * 1000;
+    vi.spyOn(globalThis, 'fetch')
+      .mockResolvedValueOnce(
+        new Response(
+          JSON.stringify({
+            authorization_url: 'https://auth.example/authorize',
+          }),
+          { status: 200 }
+        )
+      )
+      .mockResolvedValueOnce(
+        new Response(
+          JSON.stringify({ expires_at: expiresAt, return_path: '/dashboard' }),
+          { status: 200 }
+        )
+      );
+
+    const context = createTestContext('popup');
+    const connectPromise = startHubSpotConnection(context);
+    await vi.advanceTimersByTimeAsync(500);
+
+    expect(window.open).toHaveBeenCalledWith(
+      'https://auth.example/authorize',
+      expect.any(String),
+      expect.stringContaining('popup=yes')
+    );
+
+    messageListeners[0]!({
+      origin: 'https://app.example.com',
+      data: {
+        type: 'hubspot-app-connect:oauth-callback',
+        code: 'auth-code',
+        state: 'auth-state',
+      },
+    } as MessageEvent);
+
+    await connectPromise;
+    expect(context.store.getSnapshot().expiresAt).toBe(expiresAt);
+  });
+});

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

@@ -1,5 +1,7 @@
 import type { InitSessionResponse } from '../../shared/wire-types.ts';
+import { waitForHubSpotOAuthPopup } from './oauth-popup.ts';
 import type { AppConnectContext } from './types.ts';
+import { resolveOAuthConnectMode } from './utils/resolve-oauth-connect-mode.ts';
 import { delay } from './utils/timeout-utils.ts';
 
 /** Extra wait before redirect so the connect progress UI is visible; set to `0` to disable. */
@@ -10,12 +12,14 @@ const ARTIFICIAL_CONNECT_REDIRECT_DELAY_MS = 500;
  *
  * 1. Calls the SDK's `auth/init-session` route to mint a fresh PKCE
  *    verifier + state and obtain HubSpot's `authorize` URL.
- * 2. Navigates the browser to that URL (full-page redirect).
+ * 2. Navigates to that URL via full-page redirect, or opens it in a
+ *    popup when embedded in an iframe or when `oauthConnectMode` is
+ *    `'popup'`.
  *
  * The `return_path` is the current path + query so the user lands
- * back where they started after authorizing.
+ * back where they started after authorizing (redirect mode only).
  *
- * Throws when the init call fails. Does not return after the redirect
+ * Throws when the init call fails. Does not return after a redirect
  * begins because the page is unloaded.
  */
 export async function startHubSpotConnection(
@@ -41,5 +45,16 @@ export async function startHubSpotConnection(
 
   await delay(ARTIFICIAL_CONNECT_REDIRECT_DELAY_MS);
 
+  const connectMode = resolveOAuthConnectMode(
+    config.oauthConnectMode !== undefined
+      ? { oauthConnectMode: config.oauthConnectMode }
+      : {}
+  );
+
+  if (connectMode === 'popup') {
+    await waitForHubSpotOAuthPopup({ context, authorizationUrl });
+    return;
+  }
+
   window.location.href = authorizationUrl;
 }

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

@@ -1,4 +1,3 @@
-import type { LogoutResponse } from '../../shared/wire-types.ts';
 import type { AppConnectContext } from './types.ts';
 import { clearSessionStorage } from './utils/session-utils.ts';
 
@@ -8,8 +7,8 @@ import { clearSessionStorage } from './utils/session-utils.ts';
  * 1. Calls the SDK's `auth/logout` route to revoke the upstream token
  *    and clear the refresh-token cookie.
  * 2. Clears the local session-storage `expiresAt` entry.
- * 3. Updates the controller state to `disconnected` and navigates the
- *    browser to the URL the server returned in `redirect_to`.
+ * 3. Updates the controller state to `disconnected` so the UI re-renders
+ *    without a page reload.
  *
  * Errors are caught, logged, and surfaced via the controller's
  * `error` field so the UI can show a retry state.
@@ -32,8 +31,7 @@ export async function disconnectFromHubSpot(
     if (!response.ok) {
       throw new Error(`Logout failed: ${response.status}`);
     }
-    const { redirect_to: redirectTo } =
-      (await response.json()) as LogoutResponse;
+    await response.body?.cancel();
 
     store.setState({
       expiresAt: null,
@@ -41,8 +39,7 @@ export async function disconnectFromHubSpot(
       isDisconnectInFlight: false,
     });
 
-    window.location.href = redirectTo;
-    logger.info('disconnectFromHubSpot: redirecting');
+    logger.info('disconnectFromHubSpot: complete');
   } catch (err) {
     const message = err instanceof Error ? err.message : 'Disconnect failed';
     logger.error('disconnectFromHubSpot: failed', err);