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

package/src/server/lovable/hubspot-connect/index.ts

@@ -0,0 +1,28 @@
+import { secureStart } from '../../deno/start.ts';
+import { assertHubSpotConnectCimdClientMetadata } from '../../hono/hubspot-connect-routes/cimd-client-metadata-types.ts';
+import type { HubSpotConnectCimdClientMetadata } from '../../hono/hubspot-connect-routes/cimd-client-metadata-types.ts';
+import { runHubSpotConnectLovableServer } from './run-hubspot-connect-lovable-server.ts';
+
+export type { HubSpotConnectCimdClientMetadata } from '../../hono/hubspot-connect-routes/cimd-client-metadata-types.ts';
+
+export interface StartHubSpotConnectFunctionOptions {
+  client: HubSpotConnectCimdClientMetadata;
+}
+
+/**
+ * Lovable-style entry point for the hubspot-connect Deno function.
+ * Loads `HUBSPOT_APP_PRIVATE_KEY` via `secureStart`, then serves OAuth
+ * and CIMD routes under `/functions/v1/hubspot-connect`.
+ */
+export async function startHubSpotConnectFunction(
+  options: StartHubSpotConnectFunctionOptions
+): Promise<void> {
+  assertHubSpotConnectCimdClientMetadata(options.client);
+  await secureStart(async () => ({
+    start: (context) =>
+      runHubSpotConnectLovableServer({
+        ...context,
+        cimdClientMetadata: options.client,
+      }),
+  }));
+}

package/src/server/lovable/hubspot-connect/run-hubspot-connect-lovable-server.ts

@@ -0,0 +1,40 @@
+import { Hono } from 'hono';
+
+import type { SecureStartContext } from '../../deno/start.ts';
+import type { HubSpotConnectCimdClientMetadata } from '../../hono/hubspot-connect-routes/cimd-client-metadata-types.ts';
+import {
+  loadHubSpotConnectRoutesEnv,
+  registerHubSpotConnectRoutes,
+} from '../../hono/index.ts';
+
+const PORT = Deno.env.get('PORT');
+const serveOptions =
+  typeof PORT === 'string' ? { port: parseInt(PORT, 10) } : {};
+const HUBSPOT_CONNECT_BASE_PATH = '/functions/v1/hubspot-connect';
+
+export interface RunHubSpotConnectLovableServerOptions extends SecureStartContext {
+  cimdClientMetadata: HubSpotConnectCimdClientMetadata;
+}
+
+export function runHubSpotConnectLovableServer(
+  options: RunHubSpotConnectLovableServerOptions
+): Promise<void> {
+  const { appKeys, cimdClientMetadata } = options;
+  const hubspotConnectEnv = loadHubSpotConnectRoutesEnv();
+  const result = Deno.serve(serveOptions, (request) => {
+    const app = new Hono();
+
+    registerHubSpotConnectRoutes({
+      app: app.basePath(HUBSPOT_CONNECT_BASE_PATH),
+      appKeys,
+      basePath: HUBSPOT_CONNECT_BASE_PATH,
+      hubspotConnectEnv,
+      cimdClientMetadata,
+    });
+
+    return app.fetch(request);
+  });
+
+  console.log(`[hubspot-connect] Listening on ${result.addr.port}`);
+  return Promise.resolve();
+}

package/src/server/lovable/index.ts

@@ -0,0 +1,16 @@
+export {
+  secureStart,
+  type SecureStartContext,
+  type SecureStartLoader,
+} from '../deno/start.ts';
+export {
+  startHubSpotConnectFunction,
+  type HubSpotConnectCimdClientMetadata,
+  type StartHubSpotConnectFunctionOptions,
+} from './hubspot-connect/index.ts';
+export {
+  createAppFunctionStart,
+  type CreateAppFunctionStartOptions,
+  type RegisterAppFunctionRoutesFunction,
+  type AppFunctionStart,
+} from './create-app-function-start.ts';

package/src/server/node/index.ts

@@ -0,0 +1 @@
+export * from './start.ts';

package/src/server/node/start.ts

@@ -0,0 +1,25 @@
+import {
+  runSecureStart,
+  type SecureStartAdapter,
+  type SecureStartContext,
+  type SecureStartLoader,
+} from '../secure-start-core.ts';
+
+export type { SecureStartContext, SecureStartLoader };
+
+const nodeAdapter: SecureStartAdapter = {
+  readEnv: (key) => process.env[key],
+  deleteEnv: (key) => {
+    delete process.env[key];
+  },
+  exit: (code) => process.exit(code),
+};
+
+/**
+ * Node entrypoint helper. Reads `HUBSPOT_APP_PRIVATE_KEY` from
+ * `process.env` when CIMD or DPoP is enabled, imports the supplied
+ * loader, and invokes `start` with `AppKeys` or `null`.
+ */
+export function secureStart(loader: SecureStartLoader): Promise<void> {
+  return runSecureStart(loader, nodeAdapter);
+}

package/src/server/oauth.ts

@@ -0,0 +1,6 @@
+export { getJwkThumbprint } from './utils/jwk-utils.ts';
+export { verifyDpopProof } from './utils/dpop-utils.ts';
+export { verifyJwt } from './utils/jwt-utils.ts';
+export { type JwkSet } from './types.ts';
+export { sha256base64url } from './utils/crypto-utils.ts';
+export { signJwt } from './utils/jwt-utils.ts';

package/src/server/proxy.test.ts

@@ -0,0 +1,80 @@
+import {
+  afterEach,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+} from 'vitest';
+
+import { createTestAppKeys } from './utils/test-fixtures.ts';
+
+describe('createHubSpotProxy', () => {
+  let createHubSpotProxy: typeof import('./proxy.ts').createHubSpotProxy;
+
+  beforeAll(async () => {
+    vi.stubEnv('HUBSPOT_API_ORIGIN', 'https://api.example.test');
+    ({ createHubSpotProxy } = await import('./proxy.ts'));
+  });
+
+  beforeEach(() => {
+    vi.stubEnv('HUBSPOT_API_ORIGIN', 'https://api.example.test');
+    vi.stubEnv('HUBSPOT_DPOP_ENABLED', 'false');
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it('throws when DPoP is enabled and appKeys is null', () => {
+    vi.stubEnv('HUBSPOT_DPOP_ENABLED', 'true');
+    expect(() =>
+      createHubSpotProxy({
+        userCredentials: { accessToken: 't', sessionId: 's' },
+        appKeys: null,
+      })
+    ).toThrow(
+      'createHubSpotProxy: appKeys is required when HUBSPOT_DPOP_ENABLED is not false'
+    );
+  });
+
+  it('uses Bearer when DPoP is disabled and appKeys is null', async () => {
+    const fetchSpy = vi
+      .spyOn(globalThis, 'fetch')
+      .mockResolvedValue(new Response('{}'));
+    const proxy = createHubSpotProxy({
+      userCredentials: { accessToken: 'tok', sessionId: 'sid' },
+      appKeys: null,
+    });
+    expect(proxy.authenticated).toBe(true);
+    await proxy.fetch({ path: '/crm/v3/objects/contacts' });
+    expect(fetchSpy).toHaveBeenCalledWith(
+      'https://api.example.test/crm/v3/objects/contacts',
+      expect.objectContaining({
+        headers: expect.objectContaining({
+          Authorization: 'Bearer tok',
+        }),
+      })
+    );
+    fetchSpy.mockRestore();
+  });
+
+  it('sends DPoP when enabled and appKeys are provided', async () => {
+    vi.stubEnv('HUBSPOT_DPOP_ENABLED', 'true');
+    const fetchSpy = vi
+      .spyOn(globalThis, 'fetch')
+      .mockResolvedValue(new Response('{}'));
+    const appKeys = await createTestAppKeys();
+    const proxy = createHubSpotProxy({
+      userCredentials: { accessToken: 'tok', sessionId: 'sid' },
+      appKeys,
+    });
+    await proxy.fetch({ path: '/x' });
+    const init = fetchSpy.mock.calls[0]?.[1] as RequestInit;
+    const headers = init.headers as Record<string, string>;
+    expect(headers.Authorization).toMatch(/^DPoP /);
+    expect(headers.DPoP).toBeDefined();
+    fetchSpy.mockRestore();
+  });
+});

package/src/server/proxy.ts

@@ -0,0 +1,116 @@
+import { noopLogger, type Logger } from '../shared/logger.ts';
+import {
+  type AppKeys,
+  type HubSpotProxy,
+  type HubSpotProxyRequest,
+  type UserCredentials,
+} from './types.ts';
+import { sha256base64url } from './utils/crypto-utils.ts';
+import { signDpopProof } from './utils/dpop-utils.ts';
+import { isHubspotDpopEnabled, requireEnv } from './utils/env-utils.ts';
+
+const HUBSPOT_API_ORIGIN = requireEnv('HUBSPOT_API_ORIGIN');
+
+/**
+ * Options accepted by {@link createHubSpotProxy}.
+ */
+export interface CreateHubSpotProxyOptions {
+  /**
+   * User session context from the incoming browser request.
+   */
+  userCredentials: UserCredentials;
+
+  /**
+   * Imported app keys from `secureStart`, or `null` when CIMD and DPoP
+   * are both disabled.
+   */
+  appKeys: AppKeys | null;
+  /** Optional logger. Defaults to a no-op logger. */
+  logger?: Logger;
+}
+
+const notAuthenticated: HubSpotProxy = {
+  authenticated: false,
+  fetch: async (): Promise<Response> => {
+    return new Response(null, {
+      status: 401,
+      statusText: 'Unauthorized',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+    });
+  },
+};
+
+const EMPTY_HEADERS = {};
+
+export function createHubSpotProxy(
+  options: CreateHubSpotProxyOptions
+): HubSpotProxy {
+  const { userCredentials, appKeys, logger = noopLogger } = options;
+
+  if (isHubspotDpopEnabled() && appKeys === null) {
+    throw new Error(
+      'createHubSpotProxy: appKeys is required when HUBSPOT_DPOP_ENABLED is not false'
+    );
+  }
+
+  const { accessToken, sessionId } = userCredentials;
+
+  if (!accessToken || !sessionId) {
+    logger.debug(
+      'createHubSpotProxy: returning unauthenticated proxy (missing cookies)'
+    );
+    return notAuthenticated;
+  }
+
+  async function proxyFetch(request: HubSpotProxyRequest): Promise<Response> {
+    const { path, method = 'GET', headers = EMPTY_HEADERS, body } = request;
+
+    const targetUrl = `${HUBSPOT_API_ORIGIN}${path}`;
+    const useDpop = isHubspotDpopEnabled();
+
+    let authorizationHeaders: Record<string, string>;
+    if (useDpop) {
+      const ath = await sha256base64url(accessToken!);
+      const sid = await sha256base64url(sessionId!);
+      const dpopProof = await signDpopProof({
+        appKeys: appKeys!,
+        claims: {
+          htm: method,
+          htu: targetUrl,
+          jti: crypto.randomUUID(),
+          iat: Math.floor(Date.now() / 1000),
+          ath,
+          sid,
+        },
+      });
+      authorizationHeaders = {
+        Authorization: `DPoP ${accessToken}`,
+        DPoP: dpopProof,
+      };
+    } else {
+      authorizationHeaders = {
+        Authorization: `Bearer ${accessToken}`,
+      };
+    }
+
+    const finalHeaders = { ...headers, ...authorizationHeaders };
+
+    const requestInit: RequestInit = {
+      headers: finalHeaders,
+      method,
+    };
+
+    if (body != null) {
+      requestInit.body = body;
+    }
+
+    return fetch(targetUrl, requestInit);
+  }
+
+  return {
+    authenticated: true,
+    fetch: proxyFetch,
+  };
+}

package/src/server/sanitize-request.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  HUBSPOT_ACCESS_TOKEN_COOKIE_NAME,
+  HUBSPOT_APP_SID_COOKIE_NAME,
+  HUBSPOT_REFRESH_COOKIE_PREFIX,
+} from './constants.ts';
+import { sanitizeRequest } from './sanitize-request.ts';
+
+function buildRequest(cookieHeader: string | null): Request {
+  const headers = new Headers();
+  if (cookieHeader !== null) headers.set('Cookie', cookieHeader);
+  return new Request('https://example.test/api/foo', {
+    method: 'GET',
+    headers,
+  });
+}
+
+describe('sanitizeRequest', () => {
+  it('removes the access-token cookie', () => {
+    const request = buildRequest(
+      `${HUBSPOT_ACCESS_TOKEN_COOKIE_NAME}=secret; user_pref=light`
+    );
+    const sanitized = sanitizeRequest(request);
+    expect(sanitized.headers.get('cookie')).toBe('user_pref=light');
+  });
+
+  it('removes the app-session-id cookie', () => {
+    const request = buildRequest(
+      `${HUBSPOT_APP_SID_COOKIE_NAME}=abc; user_pref=light`
+    );
+    const sanitized = sanitizeRequest(request);
+    expect(sanitized.headers.get('cookie')).toBe('user_pref=light');
+  });
+
+  it('removes any cookie with the refresh prefix', () => {
+    const request = buildRequest(
+      `${HUBSPOT_REFRESH_COOKIE_PREFIX}abc=opaque; user_pref=light`
+    );
+    const sanitized = sanitizeRequest(request);
+    expect(sanitized.headers.get('cookie')).toBe('user_pref=light');
+  });
+
+  it('drops the Cookie header entirely when nothing survives', () => {
+    const request = buildRequest(`${HUBSPOT_ACCESS_TOKEN_COOKIE_NAME}=x`);
+    const sanitized = sanitizeRequest(request);
+    expect(sanitized.headers.get('cookie')).toBeNull();
+  });
+
+  it('keeps non-managed cookies untouched', () => {
+    const request = buildRequest('a=1; b=2; c=3');
+    const sanitized = sanitizeRequest(request);
+    expect(sanitized.headers.get('cookie')).toBe('a=1; b=2; c=3');
+  });
+
+  it('preserves method and url', () => {
+    const original = new Request('https://example.test/api/foo', {
+      method: 'POST',
+      headers: { Cookie: `${HUBSPOT_ACCESS_TOKEN_COOKIE_NAME}=x; foo=bar` },
+    });
+    const sanitized = sanitizeRequest(original);
+    expect(sanitized.method).toBe('POST');
+    expect(sanitized.url).toBe('https://example.test/api/foo');
+  });
+});

package/src/server/sanitize-request.ts

@@ -0,0 +1,52 @@
+import { isProtectedCookieName } from './constants.ts';
+import { parseCookies } from './utils/cookie-utils.ts';
+
+function serializeCookies(cookies: Map<string, string>): string {
+  const parts: string[] = [];
+  for (const [name, value] of cookies) {
+    parts.push(`${name}=${value}`);
+  }
+  return parts.join('; ');
+}
+
+/**
+ * Returns a clone of `original` whose `Cookie` header has every
+ * protected cookie removed (see
+ * {@link isProtectedCookieName}). When no other cookies
+ * remain, the header is dropped entirely.
+ *
+ * Used by `createAppConnectRequestHandler` so the user's route
+ * handlers never see — and therefore cannot leak — the access token,
+ * session ID, or refresh-token cookies.
+ */
+export function sanitizeRequest(original: Request): Request {
+  const cookies = parseCookies(original.headers.get('Cookie'));
+
+  const surviving = new Map<string, string>();
+  for (const [name, value] of Object.entries(cookies)) {
+    if (!isProtectedCookieName(name)) {
+      surviving.set(name, value);
+    }
+  }
+
+  const headers = new Headers(original.headers);
+  if (surviving.size === 0) {
+    headers.delete('cookie');
+  } else {
+    headers.set('cookie', serializeCookies(surviving));
+  }
+
+  const init: RequestInit = {
+    method: original.method,
+    headers,
+    redirect: original.redirect,
+    signal: original.signal,
+  };
+
+  if (original.body !== null) {
+    init.body = original.body;
+    (init as RequestInit & { duplex: 'half' }).duplex = 'half';
+  }
+
+  return new Request(original.url, init);
+}

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

@@ -0,0 +1,67 @@
+import { importAppKeys } from './import-app-keys.ts';
+import type { AppKeys } from './types.ts';
+import { isHubspotAppPrivateKeyRequired } from './utils/env-utils.ts';
+
+/**
+ * Context passed to a function-style entrypoint loaded by `runSecureStart`.
+ * Contains imported `AppKeys` when CIMD or DPoP is enabled; otherwise
+ * `null` (traditional OAuth with `client_secret` and Bearer API calls).
+ */
+export interface SecureStartContext {
+  appKeys: AppKeys | null;
+}
+
+interface SecureEntryPointExports {
+  start: (context: SecureStartContext) => Promise<void>;
+}
+
+/**
+ * Loader returned to `runSecureStart` that produces the entrypoint
+ * module. Always pass an `() => import('...')` arrow so the bundler
+ * preserves dynamic-import semantics.
+ */
+export type SecureStartLoader = () => Promise<SecureEntryPointExports>;
+
+/**
+ * Platform adapters injected by the runtime-specific shim
+ * (`node/start.ts` or `deno/start.ts`). Keeping the env/exit/delete
+ * functions out of the core lets the shared logic stay platform-free.
+ */
+export interface SecureStartAdapter {
+  /** Reads the named env var, or returns `undefined` when unset. */
+  readEnv: (key: string) => string | undefined;
+  /** Removes the named env var so child processes cannot read it. */
+  deleteEnv: (key: string) => void;
+  /** Terminates the process with the given exit code. */
+  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
+ * entrypoint module via `loader`, and invokes `start` with `AppKeys` or
+ * `null` when both features are off. On failure, logs the error and
+ * exits with code 1.
+ */
+export async function runSecureStart(
+  loader: SecureStartLoader,
+  adapter: SecureStartAdapter
+): Promise<void> {
+  let appKeys: AppKeys | null = null;
+  if (isHubspotAppPrivateKeyRequired()) {
+    const envKey = adapter.readEnv(APP_PRIVATE_KEY_ENV)?.trim();
+    if (!envKey) {
+      throw new Error(`${APP_PRIVATE_KEY_ENV} is not set`);
+    }
+    appKeys = await importAppKeys(envKey);
+    adapter.deleteEnv(APP_PRIVATE_KEY_ENV);
+  }
+
+  const exports = await loader();
+  return exports.start({ appKeys }).catch((error) => {
+    console.error(error);
+    return adapter.exit(1);
+  });
+}

package/src/server/types.ts

@@ -0,0 +1,62 @@
+/**
+ * Imported app key material used to sign client assertions and DPoP
+ * proofs. Produced by `secureStart`/`importAppKeys`; never store this
+ * shape on disk.
+ */
+export interface AppKeys {
+  /** ES256 private key as a non-extractable WebCrypto `CryptoKey`. */
+  appPrivateKey: CryptoKey;
+  /** 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.
+ */
+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.
+ */
+export interface JwkSet {
+  keys: JsonWebKey[];
+}
+
+export interface UserCredentials {
+  /** Access token. */
+  accessToken: string;
+  /** Session ID. */
+  sessionId: string;
+}

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

@@ -0,0 +1,5 @@
+export {
+  base64url,
+  base64urlDecode,
+  base64StandardToArrayBuffer,
+} from '../../shared/encoding/base64.ts';

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

@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest';
+
+import { parseCookies } from './cookie-utils.ts';
+
+describe('parseCookies', () => {
+  it('returns empty object for null/undefined/empty input', () => {
+    expect(parseCookies(null)).toEqual({});
+    expect(parseCookies(undefined)).toEqual({});
+    expect(parseCookies('')).toEqual({});
+  });
+
+  it('parses a single cookie', () => {
+    expect(parseCookies('foo=bar')).toEqual({ foo: 'bar' });
+  });
+
+  it('parses multiple cookies separated by `;`', () => {
+    expect(parseCookies('a=1; b=2; c=3')).toEqual({ a: '1', b: '2', c: '3' });
+  });
+
+  it('trims surrounding whitespace from names and values', () => {
+    expect(parseCookies('  foo  =  bar  ;  baz  =  qux  ')).toEqual({
+      foo: 'bar',
+      baz: 'qux',
+    });
+  });
+
+  it('handles cookies whose value contains `=`', () => {
+    expect(parseCookies('token=eyJhbGciPSJIUzI=; sid=abc')).toEqual({
+      token: 'eyJhbGciPSJIUzI=',
+      sid: 'abc',
+    });
+  });
+
+  it('treats cookies without `=` as empty values', () => {
+    expect(parseCookies('foo; bar=baz')).toEqual({ foo: '', bar: 'baz' });
+  });
+
+  it('lets later cookies overwrite earlier duplicates', () => {
+    expect(parseCookies('foo=1; foo=2')).toEqual({ foo: '2' });
+  });
+
+  it('skips empty segments produced by trailing `;`', () => {
+    expect(parseCookies('foo=bar; ; baz=qux;')).toEqual({
+      foo: 'bar',
+      baz: 'qux',
+    });
+  });
+});

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

@@ -0,0 +1,26 @@
+/**
+ * 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.
+ */
+export function parseCookies(
+  cookieHeader: string | null | undefined
+): Record<string, string> {
+  if (!cookieHeader) return {};
+  return Object.fromEntries(
+    cookieHeader
+      .split(';')
+      .map((pair) => {
+        const eqIdx = pair.indexOf('=');
+        if (eqIdx === -1) return [pair.trim(), ''] as [string, string];
+        return [pair.slice(0, eqIdx).trim(), pair.slice(eqIdx + 1).trim()] as [
+          string,
+          string,
+        ];
+      })
+      .filter(([name]) => name.length > 0)
+  );
+}

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

@@ -0,0 +1 @@
+export { sha256base64url } from '../../shared/encoding/sha256.ts';