@hubspot/app-connect-sdk 1.0.0-alpha.1

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

@@ -0,0 +1,21 @@
+//#region src/server/utils/cookie-utils.ts
+/**
+* Parses an HTTP `Cookie` request header into a `name -> value` map.
+* Tolerates leading/trailing whitespace, missing `=` (treats the
+* cookie value as empty), and duplicate names (last write wins).
+*
+* Returns an empty object when `cookieHeader` is `null`/`undefined`
+* /empty so callers don't have to null-check the input.
+*/
+function parseCookies(cookieHeader) {
+	if (!cookieHeader) return {};
+	return Object.fromEntries(cookieHeader.split(";").map((pair) => {
+		const eqIdx = pair.indexOf("=");
+		if (eqIdx === -1) return [pair.trim(), ""];
+		return [pair.slice(0, eqIdx).trim(), pair.slice(eqIdx + 1).trim()];
+	}).filter(([name]) => name.length > 0));
+}
+//#endregion
+export { parseCookies };
+
+//# sourceMappingURL=cookie-utils.js.map

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

@@ -0,0 +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"}

package/dist/server/utils/dpop-utils.d.ts

@@ -0,0 +1,67 @@
+//#region src/server/utils/dpop-utils.d.ts
+/**
+ * Claims that go into a DPoP proof JWT (RFC 9449 §4.2). Extra
+ * properties pass through to the encoder unchanged so callers can
+ * include implementation-specific claims.
+ */
+interface DpopClaims {
+  /** HTTP method of the protected request, uppercase. */
+  htm: string;
+  /** Target URI of the protected request, fully-qualified. */
+  htu: string;
+  /** Unique proof identifier (RFC 9449 §4.2, recommended UUID). */
+  jti: string;
+  /** Issuance time, Unix epoch seconds. */
+  iat: number;
+  /**
+   * Hash of the access token presented alongside this proof, if any
+   * (RFC 9449 §4.2). Required for resource-server DPoP.
+   */
+  ath?: string;
+  /**
+   * App session ID hash. Custom HubSpot extension that lets the auth
+   * server bind tokens to the browser session that minted them.
+   */
+  sid?: string;
+  [key: string]: unknown;
+}
+/**
+ * Result of a successful {@link verifyDpopProof} call.
+ */
+interface VerifiedDpopProof {
+  /** Public JWK extracted from the proof's header. */
+  publicKeyJwk: JsonWebKey;
+  /** RFC 7638 JWK thumbprint of `publicKeyJwk`. */
+  jkt: string;
+  /** Decoded claims from the proof's payload. */
+  claims: DpopClaims;
+}
+interface VerifyDpopProofOptions {
+  /** The compact-serialized DPoP proof. */
+  proof: string;
+  /** Expected HTTP method (RFC 9449 `htm` claim). */
+  htm: string;
+  /** Expected request URI (RFC 9449 `htu` claim). */
+  htu: string;
+  /** Expected access-token hash (RFC 9449 `ath` claim). */
+  ath?: string;
+  /** Expected app-session-ID hash (`sid` claim). */
+  sid?: string;
+}
+/**
+ * Verifies a DPoP proof JWT and returns the embedded public JWK,
+ * its thumbprint, and the decoded claims.
+ *
+ * Enforces RFC 9449's required checks:
+ *
+ * - `typ=dpop+jwt`, `alg=ES256`, and a JWK in the header.
+ * - Signature is valid against the embedded JWK.
+ * - `htm`, `htu`, and (when supplied) `ath`/`sid` match.
+ * - `iat` is within ±5 minutes of "now".
+ *
+ * @throws {Error} If any of the above checks fail.
+ */
+declare function verifyDpopProof(options: VerifyDpopProofOptions): Promise<VerifiedDpopProof>;
+//#endregion
+export { verifyDpopProof };
+//# sourceMappingURL=dpop-utils.d.ts.map

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

@@ -0,0 +1,75 @@
+import { base64urlDecode } from "../shared/encoding/base64.js";
+import { getJwkThumbprint } from "./jwk-utils.js";
+import { decodeAndVerifyJwt, encodeAndSignJwt } from "./jwt-utils.js";
+//#region src/server/utils/dpop-utils.ts
+function ecPublicJwkForDpopHeader(jwk) {
+	if (jwk.kty !== "EC" || jwk.crv !== "P-256" || typeof jwk.x !== "string" || typeof jwk.y !== "string") throw new Error("Expected P-256 EC public JWK");
+	return {
+		kty: "EC",
+		crv: "P-256",
+		x: jwk.x,
+		y: jwk.y
+	};
+}
+/**
+* Mints a DPoP proof JWT (RFC 9449) signed with the app's private
+* key. The header is set to `typ=dpop+jwt`, `alg=ES256`, and embeds
+* the public JWK so the receiver can verify the signature without
+* out-of-band key distribution.
+*/
+async function signDpopProof(options) {
+	const { appKeys, claims } = options;
+	return encodeAndSignJwt({
+		header: {
+			alg: "ES256",
+			typ: "dpop+jwt",
+			jwk: ecPublicJwkForDpopHeader(appKeys.appPublicKeyJwk)
+		},
+		payload: claims,
+		privateKey: appKeys.appPrivateKey
+	});
+}
+/**
+* Verifies a DPoP proof JWT and returns the embedded public JWK,
+* its thumbprint, and the decoded claims.
+*
+* Enforces RFC 9449's required checks:
+*
+* - `typ=dpop+jwt`, `alg=ES256`, and a JWK in the header.
+* - Signature is valid against the embedded JWK.
+* - `htm`, `htu`, and (when supplied) `ath`/`sid` match.
+* - `iat` is within ±5 minutes of "now".
+*
+* @throws {Error} If any of the above checks fail.
+*/
+async function verifyDpopProof(options) {
+	const { proof, htm, htu, ath, sid } = options;
+	const parts = proof.split(".");
+	if (parts.length !== 3) throw new Error("Invalid DPoP proof format");
+	const encodedHeader = parts[0];
+	if (!encodedHeader) throw new Error("Missing DPoP header");
+	const header = JSON.parse(new TextDecoder().decode(base64urlDecode(encodedHeader)));
+	if (header.typ !== "dpop+jwt") throw new Error("Invalid DPoP typ header");
+	if (header.alg !== "ES256") throw new Error("Unsupported DPoP algorithm");
+	const publicKeyJwk = header.jwk;
+	if (!publicKeyJwk) throw new Error("Missing jwk in DPoP header");
+	const claims = await decodeAndVerifyJwt({
+		token: proof,
+		publicKeyJwk
+	});
+	if (claims.htm !== htm) throw new Error(`DPoP htm mismatch: expected ${htm}, got ${claims.htm}`);
+	if (claims.htu !== htu) throw new Error(`DPoP htu mismatch: expected ${htu}, got ${claims.htu}`);
+	if (ath !== void 0 && claims.ath !== ath) throw new Error("DPoP ath mismatch");
+	if (sid !== void 0 && claims.sid !== sid) throw new Error("DPoP sid mismatch");
+	const now = Math.floor(Date.now() / 1e3);
+	if (Math.abs(now - claims.iat) > 300) throw new Error("DPoP proof expired or too far in future");
+	return {
+		publicKeyJwk,
+		jkt: await getJwkThumbprint({ publicKeyJwk }),
+		claims
+	};
+}
+//#endregion
+export { signDpopProof, verifyDpopProof };
+
+//# sourceMappingURL=dpop-utils.js.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,54 @@
+//#region src/server/utils/env-utils.ts
+/**
+* Reads an environment variable in a way that works under both Node
+* (`process.env`) and Deno (`Deno.env.get`). Returns `undefined` when
+* the variable is unset or when neither runtime is available.
+*/
+function getEnv(key) {
+	const g = globalThis;
+	const proc = g.process;
+	if (proc?.env) return proc.env[key];
+	const deno = g.Deno;
+	if (deno !== void 0) return deno.env.get(key);
+}
+/**
+* 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).
+*
+* @throws {Error} When the environment variable is unset or an empty
+*   string.
+*/
+function requireEnv(key) {
+	const value = getEnv(key);
+	if (!value) throw new Error(`Missing required environment variable: ${key}`);
+	return value;
+}
+/**
+* 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).
+*/
+function isHubspotDpopEnabled() {
+	return getEnv("HUBSPOT_DPOP_ENABLED") !== "false";
+}
+/**
+* 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).
+*/
+function isHubspotCimdEnabled() {
+	return getEnv("HUBSPOT_CIMD_ENABLED") !== "false";
+}
+/**
+* Whether `HUBSPOT_APP_PRIVATE_KEY` must be set for `secureStart`. False
+* when both CIMD and DPoP are disabled — the SDK then uses
+* `client_secret` for OAuth and Bearer tokens only for API calls.
+*/
+function isHubspotAppPrivateKeyRequired() {
+	return isHubspotCimdEnabled() || isHubspotDpopEnabled();
+}
+//#endregion
+export { isHubspotAppPrivateKeyRequired, isHubspotCimdEnabled, isHubspotDpopEnabled, requireEnv };
+
+//# sourceMappingURL=env-utils.js.map

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

@@ -0,0 +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"}

package/dist/server/utils/jwk-utils.d.ts

@@ -0,0 +1,16 @@
+//#region src/server/utils/jwk-utils.d.ts
+interface GetJwkThumbprintOptions {
+  /** EC P-256 public JWK whose thumbprint to compute. */
+  publicKeyJwk: JsonWebKey;
+}
+/**
+ * Computes the RFC 7638 JWK thumbprint of an EC P-256 public JWK.
+ * Per §3.2 the canonical form contains only `crv`, `kty`, `x`, `y`,
+ * sorted lexicographically — no whitespace, no other members. The
+ * SHA-256 of this canonical UTF-8 JSON, base64url-encoded, is the
+ * stable identifier (`jkt`) DPoP uses to bind tokens to public keys.
+ */
+declare function getJwkThumbprint(options: GetJwkThumbprintOptions): Promise<string>;
+//#endregion
+export { getJwkThumbprint };
+//# sourceMappingURL=jwk-utils.d.ts.map

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

@@ -0,0 +1,24 @@
+import { base64url } from "../shared/encoding/base64.js";
+//#region src/server/utils/jwk-utils.ts
+/**
+* Computes the RFC 7638 JWK thumbprint of an EC P-256 public JWK.
+* Per §3.2 the canonical form contains only `crv`, `kty`, `x`, `y`,
+* sorted lexicographically — no whitespace, no other members. The
+* SHA-256 of this canonical UTF-8 JSON, base64url-encoded, is the
+* stable identifier (`jkt`) DPoP uses to bind tokens to public keys.
+*/
+async function getJwkThumbprint(options) {
+	const { publicKeyJwk } = options;
+	const canonical = JSON.stringify({
+		crv: publicKeyJwk.crv,
+		kty: publicKeyJwk.kty,
+		x: publicKeyJwk.x,
+		y: publicKeyJwk.y
+	});
+	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(canonical));
+	return base64url(new Uint8Array(digest));
+}
+//#endregion
+export { getJwkThumbprint };
+
+//# sourceMappingURL=jwk-utils.js.map

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

@@ -0,0 +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"}

package/dist/server/utils/jwt-utils.d.ts

@@ -0,0 +1,39 @@
+//#region src/server/utils/jwt-utils.d.ts
+interface VerifyJwtOptions {
+  /** Compact-serialized JWT to verify. */
+  token: string;
+  /** Public key in JWK form. Caller is responsible for trusting it. */
+  publicKeyJwk: JsonWebKey;
+}
+/**
+ * Verifies signature and (if present) `exp` (RFC 7519 §4.1.4) on a
+ * JWT and returns its payload.
+ *
+ * @throws {Error} When the signature fails or when `exp` has passed.
+ */
+declare function verifyJwt(options: VerifyJwtOptions): Promise<Record<string, unknown>>;
+interface SignJwtOptions {
+  /** ES256 private key as a non-extractable WebCrypto key. */
+  privateKey: CryptoKey;
+  /**
+   * Custom claims merged onto an `iat` claim (and `exp` when
+   * `ttlSeconds` is supplied). Caller-provided keys override the
+   * standard ones.
+   */
+  payload: Record<string, unknown>;
+  /**
+   * Lifetime of the token in seconds. When set, the JWT's `exp` claim
+   * is computed as `iat + ttlSeconds`. When omitted, no `exp` is added
+   * (the caller is responsible for one if needed).
+   */
+  ttlSeconds?: number;
+}
+/**
+ * Signs a JWT (RFC 7519) with `alg=ES256, typ=JWT` and returns the
+ * compact serialization. Always sets `iat` to the current second; the
+ * caller controls every other claim via `payload`.
+ */
+declare function signJwt(options: SignJwtOptions): Promise<string>;
+//#endregion
+export { signJwt, verifyJwt };
+//# sourceMappingURL=jwt-utils.d.ts.map

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

@@ -0,0 +1,87 @@
+import { base64url, base64urlDecode } from "../shared/encoding/base64.js";
+//#region src/server/utils/jwt-utils.ts
+/**
+* Low-level helper that encodes a JWS Compact Serialization JWT
+* (RFC 7519) and signs it with the supplied `privateKey` using
+* ES256 (P-256 + SHA-256). Returns the three-segment compact form.
+*/
+async function encodeAndSignJwt(options) {
+	const { header, payload, privateKey } = options;
+	const signingInput = `${base64url(new TextEncoder().encode(JSON.stringify(header)))}.${base64url(new TextEncoder().encode(JSON.stringify(payload)))}`;
+	const signatureBuffer = await crypto.subtle.sign({
+		name: "ECDSA",
+		hash: "SHA-256"
+	}, privateKey, new TextEncoder().encode(signingInput));
+	return `${signingInput}.${base64url(new Uint8Array(signatureBuffer))}`;
+}
+async function importPublicKey(jwk) {
+	return crypto.subtle.importKey("jwk", jwk, {
+		name: "ECDSA",
+		namedCurve: "P-256"
+	}, false, ["verify"]);
+}
+/**
+* Verifies the ES256 signature on `token` against `publicKeyJwk` and
+* returns the decoded payload. Does not check `exp` — use
+* {@link verifyJwt} when expiry enforcement is desired.
+*
+* @throws {Error} When the token isn't three segments, when the
+*   signature fails verification, or when the payload isn't valid
+*   JSON.
+*/
+async function decodeAndVerifyJwt(options) {
+	const { token, publicKeyJwk } = options;
+	const parts = token.split(".");
+	if (parts.length !== 3) throw new Error("Invalid JWT format");
+	const [encodedHeader, encodedPayload, encodedSignature] = parts;
+	const publicKey = await importPublicKey(publicKeyJwk);
+	if (!await crypto.subtle.verify({
+		name: "ECDSA",
+		hash: "SHA-256"
+	}, publicKey, base64urlDecode(encodedSignature), new TextEncoder().encode(`${encodedHeader}.${encodedPayload}`))) throw new Error("JWT signature verification failed");
+	return JSON.parse(new TextDecoder().decode(base64urlDecode(encodedPayload)));
+}
+/**
+* Verifies signature and (if present) `exp` (RFC 7519 §4.1.4) on a
+* JWT and returns its payload.
+*
+* @throws {Error} When the signature fails or when `exp` has passed.
+*/
+async function verifyJwt(options) {
+	const { token, publicKeyJwk } = options;
+	const payload = await decodeAndVerifyJwt({
+		token,
+		publicKeyJwk
+	});
+	const now = Math.floor(Date.now() / 1e3);
+	if (typeof payload["exp"] === "number" && payload["exp"] < now) throw new Error("JWT expired");
+	return payload;
+}
+/**
+* Signs a JWT (RFC 7519) with `alg=ES256, typ=JWT` and returns the
+* compact serialization. Always sets `iat` to the current second; the
+* caller controls every other claim via `payload`.
+*/
+async function signJwt(options) {
+	const { privateKey, payload, ttlSeconds } = options;
+	const now = Math.floor(Date.now() / 1e3);
+	return encodeAndSignJwt({
+		header: {
+			alg: "ES256",
+			typ: "JWT"
+		},
+		payload: ttlSeconds !== void 0 ? {
+			iat: now,
+			exp: now + ttlSeconds,
+			...payload
+		} : {
+			iat: now,
+			...payload
+		},
+		privateKey
+	});
+}
+//#endregion
+export { decodeAndVerifyJwt, encodeAndSignJwt, signJwt, verifyJwt };
+
+//# sourceMappingURL=jwt-utils.js.map

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

@@ -0,0 +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"}

package/eslint.config.js

@@ -0,0 +1,5 @@
+export default [
+  {
+    ignores: ['dist/**', 'dist-*/**', 'build/**'],
+  },
+];

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@hubspot/app-connect-sdk",
+  "version": "1.0.0-alpha.1",
+  "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/lovable": "./dist/server/lovable.js",
+    "./server/oauth": "./dist/server/oauth.js"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org",
+    "tag": "v1-alpha",
+    "files": [
+      "dist",
+      "README.md",
+      "src"
+    ]
+  },
+  "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"
+  },
+  "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",
+    "typescript": "6.0.3",
+    "vitest": "4.0.18",
+    "@private/eslint-config": "0.1.0",
+    "@private/tsconfig": "0.1.0",
+    "@private/prettier-config": "0.1.0"
+  },
+  "scripts": {
+    "clean": "rm -rf dist build *.tsbuildinfo node_modules .turbo",
+    "dev": "tsdown --watch",
+    "format": "prettier --write . --ignore-path ../../.prettierignore",
+    "format:check": "prettier --check . --ignore-path ../../.prettierignore",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "tsdown": "tsdown",
+    "tsc": "tsc --build"
+  }
+}

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

@@ -0,0 +1,92 @@
+# `app-connect-controller` (internal)
+
+This folder owns the browser-side OAuth lifecycle for the SDK: starting a connect flow, picking up the OAuth callback, refreshing the access token in the background, and disconnecting. It is **internal** — only `createAppConnectController` (and its `CreateAppConnectControllerOptions` type) leak out via [../index.ts](../index.ts). Everything else in this folder is implementation detail and may change without notice.
+
+For consumer-facing usage (browser bootstrap, `<HubSpotAppConnect>`, server route shapes) see the package [README](../../../README.md). This document is for SDK maintainers reading the source for the first time.
+
+## Public surface
+
+- [`createAppConnectController`](./create.ts) — factory that returns an `AppConnectController`.
+- The returned `AppConnectController` shape (`subscribe` / `getSnapshot` / `getServerSnapshot` / `start`) lives in [../types.ts](../types.ts) so it plugs directly into React's `useSyncExternalStore`.
+
+The controller is inert until `start()` is called. Calling `createAppConnectController` does not read session storage, schedule a refresh timer, or issue any fetches.
+
+## Architecture overview
+
+The controller is composed from three small, generic building blocks under [`utils/`](./utils):
+
+- [`Store<TState>`](./utils/store-utils.ts) — a tiny external store with shallow-equal change detection. Listeners only fire when at least one field actually changed.
+- [`SessionStorage`](./types.ts) adapter (default impl in [`default-session-storage.ts`](./default-session-storage.ts)) — narrow interface so tests can plug in an in-memory implementation without a DOM.
+- [`memoizeLast`](./utils/memoize-utils.ts) — single-slot memoization that keeps `getSnapshot()` referentially stable for React.
+
+These dependencies are bundled into an `AppConnectContext` ([types.ts](./types.ts)) — `{ config, logger, sessionStorage, store }` — which is the single argument every per-flow helper accepts. That keeps call sites flat and avoids drift between functions on positional argument order.
+
+The view-state derivation in [view-state.ts](./view-state.ts) reduces the boolean lifecycle flags in `AppConnectInternalState` into the public `AppConnectStatus` enum. The order of checks (disconnect-in-flight beats connect-in-flight, etc.) is documented inline next to `getDerivedStatus`.
+
+## Lifecycle
+
+```mermaid
+flowchart TD
+    factory["createAppConnectController(options)"] --> inert["inert controller"]
+    inert -->|"start()"| started["controller started"]
+    started --> sched["startRefreshScheduler(context)"]
+    started --> initFlow["initAppConnect(context)"]
+    initFlow -->|"reads ?__hs_expires_at"| store[("Store&lt;AppConnectInternalState&gt;")]
+
+    subgraph flows [Per-flow helpers]
+        connect["startHubSpotConnection (connect-start.ts)"]
+        disconnect["disconnectFromHubSpot (disconnect.ts)"]
+        refresh["refreshAccessToken (refresh.ts)"]
+    end
+
+    connect -->|"setState"| store
+    disconnect -->|"setState"| store
+    refresh -->|"setState"| store
+    sched -->|"on store change"| refresh
+
+    store -->|"subscribe"| react["React useSyncExternalStore"]
+    store -->|"getSnapshot + memoizeLast"| view["AppConnectState (view-state.ts)"]
+    view --> react
+```
+
+1. `createAppConnectController` builds the `Store`, the default `SessionStorage`, and the `AppConnectContext`, then hydrates `expiresAt` from session storage if present.
+2. `controller.start()` is idempotent. On the first call it starts the refresh scheduler and runs `initAppConnect` to consume the `?__hs_expires_at=…` parameter the OAuth callback adds to the redirect URL.
+3. `connectToHubSpot()` and `disconnectFromHubSpot()` are exposed on the public `AppConnectState`. Both wrap their respective flow helpers and funnel errors into `state.error`.
+4. The refresh scheduler is store-driven: it re-evaluates whenever the store changes and (re)schedules a single `setTimeout` against `expiresAt - REFRESH_BUFFER_MS`.
+
+## 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.
+- [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`).
+- [default-session-storage.ts](./default-session-storage.ts) — adapter around the global `sessionStorage`.
+- [constants.ts](./constants.ts) — `EXPIRES_AT_KEY`, `REFRESH_BUFFER_MS`; re-exports the shared `EXPIRES_AT_URL_PARAM`.
+- [types.ts](./types.ts) — internal types: `AppConnectInternalState`, `AppConnectContext`, `AppConnectStore`, `SessionStorage`.
+- [utils/session-utils.ts](./utils/session-utils.ts) — read/write `expiresAt` to session storage, `isClientSessionActive`, `clearSessionStorage`.
+- [utils/store-utils.ts](./utils/store-utils.ts) — the generic `Store<TState>`.
+- [utils/memoize-utils.ts](./utils/memoize-utils.ts) — single-slot memoization for view state.
+- [utils/timeout-utils.ts](./utils/timeout-utils.ts) — `delay` helper used by `connect-start.ts`.
+- [utils/crypto-utils.ts](./utils/crypto-utils.ts) / [utils/encode-utils.ts](./utils/encode-utils.ts) — thin re-exports of `shared/encoding/*` shared with the server.
+- [view-state.test.ts](./view-state.test.ts), [utils/\*.test.ts](./utils) — Vitest specs.
+
+## Internal state model
+
+`AppConnectInternalState` ([types.ts](./types.ts)) is the single source of truth. Each field is flipped by exactly the flows that own it:
+
+- `isInitComplete` — set to `true` in the `finally` block of the async init step in `create.ts`. Stays `true` for the lifetime of the controller.
+- `isConnectInFlight` — toggled by the `connectToHubSpot` wrapper in `create.ts` around `startHubSpotConnection`. Cleared in `finally` even though the page is usually about to unload.
+- `isSessionConnected` — set after init completes (mirrors `isClientSessionActive`) and cleared by `disconnectFromHubSpot` and by refresh failures in `refresh.ts`.
+- `isDisconnectInFlight` — toggled by `disconnectFromHubSpot` in `disconnect.ts`.
+- `error` — most recent error from any flow. Intentionally last-write-wins so the UI shows the most actionable failure; flows clear it at their start (`error: null`).
+- `expiresAt` — the access-token expiry in Unix epoch milliseconds, or `null`. Persisted to session storage so it survives full-page navigations within the tab. Always go through [`utils/session-utils.ts`](./utils/session-utils.ts) — do not read or write this field directly elsewhere.
+
+## Maintainer notes
+
+- Every flow helper takes a single `AppConnectContext` argument, matching the repo's "single options object" rule from [AGENTS.md](../../../../../AGENTS.md). When a new flow needs another dependency, add it to `AppConnectContext` rather than threading new positional arguments through.
+- The `Store` is the only place mutable state lives. Anything that should be observable to React must flow through `store.setState`; otherwise `getSnapshot()` will skip the change because `memoizeLast` keys on the store snapshot reference.
+- Keep `getDerivedStatus` allocation-free. Allocating inside it (e.g. building a new object literal that's then returned alongside actions) defeats the `memoizeLast` cache and triggers re-renders on every unrelated store update.
+- `getServerSnapshot()` returns the frozen module-level `SERVER_VIEW` constant. Keep it referentially stable for SSR — React reuses it across renders.
+- Adding a new flow: define the helper in its own file under this folder, accept `AppConnectContext`, mutate state only via `store.setState`, and expose it on the public `AppConnectState` from `create.ts` if the UI needs to call it.