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

package/src/server/sanitize-request.ts

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

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

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

package/src/server/types.ts

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

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

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

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

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

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

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

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

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

package/src/shared/constants.ts

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

package/src/shared/wire-types.ts

@@ -15,6 +15,25 @@ export interface InitSessionResponse {
   authorization_url: string;
 }
 
+/**
+ * Body returned by `POST /auth/complete` once the SDK has exchanged
+ * the OAuth authorization code for an access + refresh token. The
+ * SDK has set the durable session cookies on the response by this
+ * point; the browser controller uses these fields to update its
+ * client-side expiry tracking and to navigate the user back to the
+ * page they started the connect flow from.
+ */
+export interface AuthCompleteResponse {
+  /** Access-token expiry as Unix epoch milliseconds. */
+  expires_at: number;
+  /**
+   * Path the browser should land on after the connect flow finishes,
+   * carried through the OAuth `state` round-trip. Always begins with
+   * `/` and is restricted to safe internal paths.
+   */
+  return_path: string;
+}
+
 /**
  * Body returned by `POST /auth/refresh` after a successful access-token
  * refresh.