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

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

@@ -0,0 +1,102 @@
+import { describe, expect, it } from 'vitest';
+
+import { signDpopProof, verifyDpopProof } from './dpop-utils.ts';
+import { createTestAppKeys } from './test-fixtures.ts';
+
+const HTM = 'POST';
+const HTU = 'https://example.test/oauth/v1/token';
+
+function makeClaims(overrides: Record<string, unknown> = {}) {
+  return {
+    htm: HTM,
+    htu: HTU,
+    jti: '11111111-1111-1111-1111-111111111111',
+    iat: Math.floor(Date.now() / 1000),
+    ...overrides,
+  };
+}
+
+describe('signDpopProof + verifyDpopProof', () => {
+  it('round-trips matching claims', async () => {
+    const appKeys = await createTestAppKeys();
+    const proof = await signDpopProof({
+      appKeys,
+      claims: makeClaims({ ath: 'token-hash', sid: 'session-hash' }),
+    });
+
+    const verified = await verifyDpopProof({
+      proof,
+      htm: HTM,
+      htu: HTU,
+      ath: 'token-hash',
+      sid: 'session-hash',
+    });
+
+    expect(verified.claims.htm).toBe(HTM);
+    expect(verified.claims.htu).toBe(HTU);
+    expect(verified.publicKeyJwk.kty).toBe('EC');
+    expect(verified.publicKeyJwk.crv).toBe('P-256');
+    expect(typeof verified.jkt).toBe('string');
+    expect(verified.jkt.length).toBeGreaterThan(0);
+  });
+
+  it('throws on htm mismatch', async () => {
+    const appKeys = await createTestAppKeys();
+    const proof = await signDpopProof({ appKeys, claims: makeClaims() });
+    await expect(
+      verifyDpopProof({ proof, htm: 'GET', htu: HTU })
+    ).rejects.toThrow(/htm mismatch/);
+  });
+
+  it('throws on htu mismatch', async () => {
+    const appKeys = await createTestAppKeys();
+    const proof = await signDpopProof({ appKeys, claims: makeClaims() });
+    await expect(
+      verifyDpopProof({
+        proof,
+        htm: HTM,
+        htu: 'https://other.test/oauth/v1/token',
+      })
+    ).rejects.toThrow(/htu mismatch/);
+  });
+
+  it('throws on ath mismatch when expected', async () => {
+    const appKeys = await createTestAppKeys();
+    const proof = await signDpopProof({
+      appKeys,
+      claims: makeClaims({ ath: 'one' }),
+    });
+    await expect(
+      verifyDpopProof({ proof, htm: HTM, htu: HTU, ath: 'two' })
+    ).rejects.toThrow(/ath mismatch/);
+  });
+
+  it('throws on sid mismatch when expected', async () => {
+    const appKeys = await createTestAppKeys();
+    const proof = await signDpopProof({
+      appKeys,
+      claims: makeClaims({ sid: 'one' }),
+    });
+    await expect(
+      verifyDpopProof({ proof, htm: HTM, htu: HTU, sid: 'two' })
+    ).rejects.toThrow(/sid mismatch/);
+  });
+
+  it('rejects iat skewed beyond ±5 minutes', async () => {
+    const appKeys = await createTestAppKeys();
+    const longAgo = Math.floor(Date.now() / 1000) - 60 * 60;
+    const proof = await signDpopProof({
+      appKeys,
+      claims: makeClaims({ iat: longAgo }),
+    });
+    await expect(
+      verifyDpopProof({ proof, htm: HTM, htu: HTU })
+    ).rejects.toThrow(/expired or too far in future/);
+  });
+
+  it('rejects malformed proofs', async () => {
+    await expect(
+      verifyDpopProof({ proof: 'a.b', htm: HTM, htu: HTU })
+    ).rejects.toThrow(/Invalid DPoP proof format/);
+  });
+});

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

@@ -0,0 +1,161 @@
+import { type AppKeys } from '../types.ts';
+import { base64urlDecode } from './base64-utils.ts';
+import { getJwkThumbprint } from './jwk-utils.ts';
+import { decodeAndVerifyJwt, encodeAndSignJwt } from './jwt-utils.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.
+ */
+export 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;
+}
+
+function ecPublicJwkForDpopHeader(jwk: JsonWebKey): JsonWebKey {
+  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,
+  };
+}
+
+export interface SignDpopProofOptions {
+  /** App key material produced by `secureStart`. */
+  appKeys: AppKeys;
+  /** Claims to include in the DPoP proof. */
+  claims: DpopClaims;
+}
+
+/**
+ * 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.
+ */
+export async function signDpopProof(
+  options: SignDpopProofOptions
+): Promise<string> {
+  const { appKeys, claims } = options;
+  const publicJwk = ecPublicJwkForDpopHeader(appKeys.appPublicKeyJwk);
+  return encodeAndSignJwt({
+    header: { alg: 'ES256', typ: 'dpop+jwt', jwk: publicJwk },
+    payload: claims,
+    privateKey: appKeys.appPrivateKey,
+  });
+}
+
+/**
+ * Result of a successful {@link verifyDpopProof} call.
+ */
+export 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;
+}
+
+export 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;
+}
+
+interface DpopProofHeader {
+  typ?: string;
+  alg?: string;
+  jwk?: JsonWebKey;
+}
+
+/**
+ * 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.
+ */
+export async function verifyDpopProof(
+  options: VerifyDpopProofOptions
+): Promise<VerifiedDpopProof> {
+  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))
+  ) as DpopProofHeader;
+
+  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 payload = await decodeAndVerifyJwt({ token: proof, publicKeyJwk });
+  const claims = payload as unknown as DpopClaims;
+
+  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 !== undefined && claims.ath !== ath) {
+    throw new Error('DPoP ath mismatch');
+  }
+  if (sid !== undefined && claims.sid !== sid) {
+    throw new Error('DPoP sid mismatch');
+  }
+
+  const now = Math.floor(Date.now() / 1000);
+  if (Math.abs(now - claims.iat) > 300) {
+    throw new Error('DPoP proof expired or too far in future');
+  }
+
+  const jkt = await getJwkThumbprint({ publicKeyJwk });
+  return { publicKeyJwk, jkt, claims };
+}

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

@@ -0,0 +1,92 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  isHubspotAppPrivateKeyRequired,
+  isHubspotCimdEnabled,
+  isHubspotDpopEnabled,
+} from './env-utils.ts';
+
+describe('isHubspotCimdEnabled', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it('returns true when HUBSPOT_CIMD_ENABLED is empty string', () => {
+    vi.stubEnv('HUBSPOT_CIMD_ENABLED', '');
+    expect(isHubspotCimdEnabled()).toBe(true);
+  });
+
+  it('returns false when HUBSPOT_CIMD_ENABLED is exactly false', () => {
+    vi.stubEnv('HUBSPOT_CIMD_ENABLED', 'false');
+    expect(isHubspotCimdEnabled()).toBe(false);
+  });
+
+  it('returns true when HUBSPOT_CIMD_ENABLED is true', () => {
+    vi.stubEnv('HUBSPOT_CIMD_ENABLED', 'true');
+    expect(isHubspotCimdEnabled()).toBe(true);
+  });
+
+  it('returns true for other non-false strings', () => {
+    vi.stubEnv('HUBSPOT_CIMD_ENABLED', '0');
+    expect(isHubspotCimdEnabled()).toBe(true);
+  });
+});
+
+describe('isHubspotAppPrivateKeyRequired', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it('returns false when both CIMD and DPoP are false', () => {
+    vi.stubEnv('HUBSPOT_CIMD_ENABLED', 'false');
+    vi.stubEnv('HUBSPOT_DPOP_ENABLED', 'false');
+    expect(isHubspotAppPrivateKeyRequired()).toBe(false);
+  });
+
+  it('returns true when CIMD is enabled and DPoP is false', () => {
+    vi.stubEnv('HUBSPOT_CIMD_ENABLED', 'true');
+    vi.stubEnv('HUBSPOT_DPOP_ENABLED', 'false');
+    expect(isHubspotAppPrivateKeyRequired()).toBe(true);
+  });
+
+  it('returns true when CIMD is false and DPoP is enabled', () => {
+    vi.stubEnv('HUBSPOT_CIMD_ENABLED', 'false');
+    vi.stubEnv('HUBSPOT_DPOP_ENABLED', 'true');
+    expect(isHubspotAppPrivateKeyRequired()).toBe(true);
+  });
+
+  it('returns true when both are enabled by default (unset)', () => {
+    expect(isHubspotAppPrivateKeyRequired()).toBe(true);
+  });
+});
+
+describe('isHubspotDpopEnabled', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it('returns true when HUBSPOT_DPOP_ENABLED is empty string', () => {
+    vi.stubEnv('HUBSPOT_DPOP_ENABLED', '');
+    expect(isHubspotDpopEnabled()).toBe(true);
+  });
+
+  it('returns false when HUBSPOT_DPOP_ENABLED is exactly false', () => {
+    vi.stubEnv('HUBSPOT_DPOP_ENABLED', 'false');
+    expect(isHubspotDpopEnabled()).toBe(false);
+  });
+
+  it('returns true when HUBSPOT_DPOP_ENABLED is true', () => {
+    vi.stubEnv('HUBSPOT_DPOP_ENABLED', 'true');
+    expect(isHubspotDpopEnabled()).toBe(true);
+  });
+
+  it('returns true for other non-false strings', () => {
+    vi.stubEnv('HUBSPOT_DPOP_ENABLED', '0');
+    expect(isHubspotDpopEnabled()).toBe(true);
+  });
+
+  it('returns true for False with different casing', () => {
+    vi.stubEnv('HUBSPOT_DPOP_ENABLED', 'False');
+    expect(isHubspotDpopEnabled()).toBe(true);
+  });
+});

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

@@ -0,0 +1,65 @@
+interface GlobalWithOptionalEnv {
+  process?: { env?: Record<string, string | undefined> };
+  Deno?: { env: { get(name: string): string | undefined } };
+}
+
+/**
+ * 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.
+ */
+export function getEnv(key: string): string | undefined {
+  const g = globalThis as GlobalWithOptionalEnv;
+  const proc = g.process;
+  if (proc?.env) {
+    return proc.env[key];
+  }
+  const deno = g.Deno;
+  if (deno !== undefined) {
+    return deno.env.get(key);
+  }
+  return undefined;
+}
+
+/**
+ * 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.
+ */
+export function requireEnv(key: string): string {
+  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).
+ */
+export function isHubspotDpopEnabled(): boolean {
+  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).
+ */
+export function isHubspotCimdEnabled(): boolean {
+  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.
+ */
+export function isHubspotAppPrivateKeyRequired(): boolean {
+  return isHubspotCimdEnabled() || isHubspotDpopEnabled();
+}

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

@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest';
+
+import { getJwkThumbprint } from './jwk-utils.ts';
+import { createTestAppKeys } from './test-fixtures.ts';
+
+describe('getJwkThumbprint', () => {
+  it('produces a deterministic thumbprint per key', async () => {
+    const keys = await createTestAppKeys();
+    const a = await getJwkThumbprint({ publicKeyJwk: keys.appPublicKeyJwk });
+    const b = await getJwkThumbprint({ publicKeyJwk: keys.appPublicKeyJwk });
+    expect(a).toBe(b);
+  });
+
+  it('produces different thumbprints for different keys', async () => {
+    const keysA = await createTestAppKeys();
+    const keysB = await createTestAppKeys();
+    const a = await getJwkThumbprint({ publicKeyJwk: keysA.appPublicKeyJwk });
+    const b = await getJwkThumbprint({ publicKeyJwk: keysB.appPublicKeyJwk });
+    expect(a).not.toBe(b);
+  });
+
+  it('only depends on kty, crv, x, y (RFC 7638 §3.2)', async () => {
+    const keys = await createTestAppKeys();
+    const base = await getJwkThumbprint({ publicKeyJwk: keys.appPublicKeyJwk });
+    const withExtras = await getJwkThumbprint({
+      publicKeyJwk: {
+        ...keys.appPublicKeyJwk,
+        use: 'sig',
+        alg: 'ES256',
+      } as JsonWebKey,
+    });
+    expect(withExtras).toBe(base);
+  });
+});

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

@@ -0,0 +1,30 @@
+import { base64url } from './base64-utils.ts';
+
+export 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.
+ */
+export async function getJwkThumbprint(
+  options: GetJwkThumbprintOptions
+): Promise<string> {
+  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));
+}

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

@@ -0,0 +1,81 @@
+import { describe, expect, it } from 'vitest';
+
+import { signJwt, verifyJwt } from './jwt-utils.ts';
+import { createTestAppKeys } from './test-fixtures.ts';
+
+describe('signJwt + verifyJwt', () => {
+  it('round-trips arbitrary payloads', async () => {
+    const keys = await createTestAppKeys();
+    const token = await signJwt({
+      privateKey: keys.appPrivateKey,
+      payload: { sub: 'user-1', custom: 'value' },
+    });
+    const payload = await verifyJwt({
+      token,
+      publicKeyJwk: keys.appPublicKeyJwk,
+    });
+    expect(payload['sub']).toBe('user-1');
+    expect(payload['custom']).toBe('value');
+    expect(typeof payload['iat']).toBe('number');
+  });
+
+  it('adds `exp = iat + ttlSeconds` when ttl is supplied', async () => {
+    const keys = await createTestAppKeys();
+    const token = await signJwt({
+      privateKey: keys.appPrivateKey,
+      payload: { sub: 'user-1' },
+      ttlSeconds: 60,
+    });
+    const payload = await verifyJwt({
+      token,
+      publicKeyJwk: keys.appPublicKeyJwk,
+    });
+    expect(payload['exp']).toBe((payload['iat'] as number) + 60);
+  });
+
+  it('omits `exp` when no ttl is supplied', async () => {
+    const keys = await createTestAppKeys();
+    const token = await signJwt({
+      privateKey: keys.appPrivateKey,
+      payload: { sub: 'user-1' },
+    });
+    const payload = await verifyJwt({
+      token,
+      publicKeyJwk: keys.appPublicKeyJwk,
+    });
+    expect(payload['exp']).toBeUndefined();
+  });
+
+  it('rejects expired tokens', async () => {
+    const keys = await createTestAppKeys();
+    const token = await signJwt({
+      privateKey: keys.appPrivateKey,
+      payload: { exp: Math.floor(Date.now() / 1000) - 10 },
+    });
+    await expect(
+      verifyJwt({ token, publicKeyJwk: keys.appPublicKeyJwk })
+    ).rejects.toThrow('JWT expired');
+  });
+
+  it('rejects tokens signed with a different key', async () => {
+    const keysA = await createTestAppKeys();
+    const keysB = await createTestAppKeys();
+    const token = await signJwt({
+      privateKey: keysA.appPrivateKey,
+      payload: { sub: 'user-1' },
+    });
+    await expect(
+      verifyJwt({ token, publicKeyJwk: keysB.appPublicKeyJwk })
+    ).rejects.toThrow('JWT signature verification failed');
+  });
+
+  it('rejects malformed tokens', async () => {
+    const keys = await createTestAppKeys();
+    await expect(
+      verifyJwt({
+        token: 'not-a-jwt',
+        publicKeyJwk: keys.appPublicKeyJwk,
+      })
+    ).rejects.toThrow('Invalid JWT format');
+  });
+});