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

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

@@ -0,0 +1,141 @@
+import { base64url, base64urlDecode } from './base64-utils.ts';
+
+interface EncodeAndSignJwtOptions {
+  header: Record<string, unknown>;
+  payload: Record<string, unknown>;
+  privateKey: CryptoKey;
+}
+
+/**
+ * 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.
+ */
+export async function encodeAndSignJwt(
+  options: EncodeAndSignJwtOptions
+): Promise<string> {
+  const { header, payload, privateKey } = options;
+
+  const encodedHeader = base64url(
+    new TextEncoder().encode(JSON.stringify(header))
+  );
+  const encodedPayload = base64url(
+    new TextEncoder().encode(JSON.stringify(payload))
+  );
+  const signingInput = `${encodedHeader}.${encodedPayload}`;
+  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: JsonWebKey): Promise<CryptoKey> {
+  return crypto.subtle.importKey(
+    'jwk',
+    jwk,
+    { name: 'ECDSA', namedCurve: 'P-256' },
+    false,
+    ['verify']
+  );
+}
+
+interface DecodeAndVerifyJwtOptions {
+  token: string;
+  publicKeyJwk: JsonWebKey;
+}
+
+/**
+ * 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.
+ */
+export async function decodeAndVerifyJwt(
+  options: DecodeAndVerifyJwtOptions
+): Promise<Record<string, unknown>> {
+  const { token, publicKeyJwk } = options;
+  const parts = token.split('.');
+  if (parts.length !== 3) throw new Error('Invalid JWT format');
+  const [encodedHeader, encodedPayload, encodedSignature] = parts as [
+    string,
+    string,
+    string,
+  ];
+  const publicKey = await importPublicKey(publicKeyJwk);
+  const valid = await crypto.subtle.verify(
+    { name: 'ECDSA', hash: 'SHA-256' },
+    publicKey,
+    base64urlDecode(encodedSignature),
+    new TextEncoder().encode(`${encodedHeader}.${encodedPayload}`)
+  );
+  if (!valid) throw new Error('JWT signature verification failed');
+  return JSON.parse(
+    new TextDecoder().decode(base64urlDecode(encodedPayload))
+  ) as Record<string, unknown>;
+}
+
+export 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.
+ */
+export async function verifyJwt(
+  options: VerifyJwtOptions
+): Promise<Record<string, unknown>> {
+  const { token, publicKeyJwk } = options;
+  const payload = await decodeAndVerifyJwt({ token, publicKeyJwk });
+  const now = Math.floor(Date.now() / 1000);
+  if (typeof payload['exp'] === 'number' && payload['exp'] < now) {
+    throw new Error('JWT expired');
+  }
+  return payload;
+}
+
+export 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`.
+ */
+export async function signJwt(options: SignJwtOptions): Promise<string> {
+  const { privateKey, payload, ttlSeconds } = options;
+  const now = Math.floor(Date.now() / 1000);
+  const payloadWithStandardClaims =
+    ttlSeconds !== undefined
+      ? { iat: now, exp: now + ttlSeconds, ...payload }
+      : { iat: now, ...payload };
+  return encodeAndSignJwt({
+    header: { alg: 'ES256', typ: 'JWT' },
+    payload: payloadWithStandardClaims,
+    privateKey,
+  });
+}

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

@@ -0,0 +1,32 @@
+import type { AppKeys } from '../types.ts';
+
+/**
+ * Generates a fresh ES256 key pair and packages it as `AppKeys`.
+ * Used by tests so they don't need access to the production private
+ * key. Each call produces a new pair.
+ */
+export async function createTestAppKeys(): Promise<AppKeys> {
+  const keyPair = (await crypto.subtle.generateKey(
+    { name: 'ECDSA', namedCurve: 'P-256' },
+    true,
+    ['sign', 'verify']
+  )) as CryptoKeyPair;
+  const publicJwk = await crypto.subtle.exportKey('jwk', keyPair.publicKey);
+  if (
+    typeof publicJwk.kty !== 'string' ||
+    typeof publicJwk.crv !== 'string' ||
+    typeof publicJwk.x !== 'string' ||
+    typeof publicJwk.y !== 'string'
+  ) {
+    throw new Error('Generated key is not a valid EC public JWK');
+  }
+  return {
+    appPrivateKey: keyPair.privateKey,
+    appPublicKeyJwk: {
+      kty: publicJwk.kty,
+      crv: publicJwk.crv,
+      x: publicJwk.x,
+      y: publicJwk.y,
+    },
+  };
+}

package/src/shared/constants.ts

@@ -0,0 +1,13 @@
+/**
+ * Constants whose values are part of the contract between the browser
+ * controller and the server-side hubspot-connect routes. Both halves
+ * import from this module so the wire format stays in sync.
+ */
+
+/**
+ * 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`.
+ */
+export const EXPIRES_AT_URL_PARAM = '__hs_expires_at';

package/src/shared/encoding/base64.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  base64StandardToArrayBuffer,
+  base64url,
+  base64urlDecode,
+} from './base64.ts';
+
+describe('base64', () => {
+  describe('base64url', () => {
+    it('encodes empty input as empty string', () => {
+      expect(base64url(new Uint8Array([]))).toBe('');
+    });
+
+    it('uses url-safe alphabet (no +/=)', () => {
+      const encoded = base64url(new Uint8Array([0xff, 0xff, 0xff]));
+      expect(encoded).not.toMatch(/[+/=]/);
+    });
+
+    it('round-trips arbitrary bytes', () => {
+      const original = new Uint8Array(256);
+      for (let i = 0; i < 256; i++) original[i] = i;
+
+      const encoded = base64url(original);
+      const decoded = base64urlDecode(encoded);
+
+      expect(decoded.length).toBe(original.length);
+      expect(Array.from(decoded)).toEqual(Array.from(original));
+    });
+
+    it('accepts ArrayBuffer input', () => {
+      const buffer = new ArrayBuffer(3);
+      new Uint8Array(buffer).set([1, 2, 3]);
+      expect(base64url(buffer)).toBe('AQID');
+    });
+  });
+
+  describe('base64urlDecode', () => {
+    it('tolerates missing padding', () => {
+      expect(Array.from(base64urlDecode('AQID'))).toEqual([1, 2, 3]);
+      expect(Array.from(base64urlDecode('AQIDBA'))).toEqual([1, 2, 3, 4]);
+    });
+
+    it('handles url-safe characters', () => {
+      const encoded = base64url(new Uint8Array([0xfb, 0xff]));
+      const decoded = base64urlDecode(encoded);
+      expect(Array.from(decoded)).toEqual([0xfb, 0xff]);
+    });
+  });
+
+  describe('base64StandardToArrayBuffer', () => {
+    it('decodes a padded base64 string into an ArrayBuffer', () => {
+      const buffer = base64StandardToArrayBuffer('AQID');
+      expect(new Uint8Array(buffer)).toEqual(new Uint8Array([1, 2, 3]));
+    });
+  });
+});

package/src/shared/encoding/base64.ts

@@ -0,0 +1,50 @@
+/**
+ * Base64url encoding and decoding helpers shared by the browser and
+ * server halves of `@hubspot/app-connect-sdk`.
+ *
+ * Base64url (RFC 4648 §5) replaces `+`/`/` with `-`/`_` and drops `=`
+ * padding. JWT, DPoP, and JWK thumbprints all use this variant.
+ */
+
+/**
+ * Encodes a binary buffer as a base64url string (RFC 4648 §5).
+ */
+export function base64url(input: ArrayBuffer | Uint8Array): string {
+  const bytes = input instanceof Uint8Array ? input : new Uint8Array(input);
+  let binary = '';
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
+}
+
+/**
+ * Decodes a base64url string into a `Uint8Array`. Tolerates missing
+ * padding by re-adding it before delegating to `atob`.
+ */
+export function base64urlDecode(encoded: string): Uint8Array<ArrayBuffer> {
+  const padLen = (4 - (encoded.length % 4)) % 4;
+  const padded =
+    encoded.replace(/-/g, '+').replace(/_/g, '/') + '='.repeat(padLen);
+  const binary = atob(padded);
+  const out = new Uint8Array(new ArrayBuffer(binary.length));
+  for (let i = 0; i < binary.length; i++) {
+    out[i] = binary.charCodeAt(i) ?? 0;
+  }
+  return out;
+}
+
+/**
+ * Decodes a *standard* base64 string (with `+`/`/` and required `=`
+ * padding) into an `ArrayBuffer`. Used for PKCS8-encoded private keys
+ * stored in environment variables.
+ */
+export function base64StandardToArrayBuffer(b64: string): ArrayBuffer {
+  const bin = atob(b64);
+  const buf = new ArrayBuffer(bin.length);
+  const view = new Uint8Array(buf);
+  for (let i = 0; i < bin.length; i++) {
+    view[i] = bin.charCodeAt(i) ?? 0;
+  }
+  return buf;
+}

package/src/shared/encoding/sha256.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest';
+
+import { sha256base64url } from './sha256.ts';
+
+describe('sha256base64url', () => {
+  it('matches the known SHA-256 of the empty string', () => {
+    // SHA-256("") = e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
+    // base64url: 47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU
+    return sha256base64url('').then((hash) => {
+      expect(hash).toBe('47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU');
+    });
+  });
+
+  it('produces deterministic output', async () => {
+    const a = await sha256base64url('hello');
+    const b = await sha256base64url('hello');
+    expect(a).toBe(b);
+  });
+
+  it('produces different output for different input', async () => {
+    const a = await sha256base64url('hello');
+    const b = await sha256base64url('world');
+    expect(a).not.toBe(b);
+  });
+});

package/src/shared/encoding/sha256.ts

@@ -0,0 +1,14 @@
+import { base64url } from './base64.ts';
+
+/**
+ * Hashes a UTF-8 string with SHA-256 and encodes the digest as
+ * base64url. Used to compute DPoP `ath`/`sid` claims, JWK thumbprints
+ * (RFC 7638), and PKCE code challenges.
+ */
+export async function sha256base64url(input: string): Promise<string> {
+  const digest = await crypto.subtle.digest(
+    'SHA-256',
+    new TextEncoder().encode(input)
+  );
+  return base64url(new Uint8Array(digest));
+}

package/src/shared/logger.ts

@@ -0,0 +1,50 @@
+/**
+ * Pluggable logger contract used by the SDK on both the browser and
+ * server. Consumers can pass `console`-like loggers, structured
+ * loggers (pino / winston / etc.) or no-op stubs in tests.
+ */
+export interface Logger {
+  debug: (message: string, ...args: unknown[]) => void;
+  info: (message: string, ...args: unknown[]) => void;
+  warn: (message: string, ...args: unknown[]) => void;
+  error: (message: string, ...args: unknown[]) => void;
+}
+
+function formatPrefix(name: string): string {
+  return `[${name}]`;
+}
+
+/**
+ * Creates a console-backed logger that prefixes every line with the
+ * supplied `name`. Used as the default when no custom logger is
+ * provided.
+ */
+export function createLogger(name: string): Logger {
+  const prefix = formatPrefix(name);
+  return {
+    debug: (message, ...args) => {
+      console.debug(prefix, message, ...args);
+    },
+    info: (message, ...args) => {
+      console.info(prefix, message, ...args);
+    },
+    warn: (message, ...args) => {
+      console.warn(prefix, message, ...args);
+    },
+    error: (message, ...args) => {
+      console.error(prefix, message, ...args);
+    },
+  };
+}
+
+/**
+ * Logger that swallows every message. Convenient for tests and for
+ * the SDK's server-side handlers when no logger is provided by the
+ * host application.
+ */
+export const noopLogger: Logger = {
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+};

package/src/shared/wire-types.ts

@@ -0,0 +1,40 @@
+/**
+ * Wire-format types for HTTP responses exchanged between the browser
+ * controller and the server-side hubspot-connect routes in this same
+ * package. Both halves import from this module so the response shapes
+ * stay in sync.
+ */
+
+/**
+ * Body returned by `POST /auth/init-session`. The browser uses
+ * `authorization_url` as the redirect target that begins the HubSpot
+ * authorization code flow.
+ */
+export interface InitSessionResponse {
+  /** Fully-qualified URL the browser should navigate to. */
+  authorization_url: string;
+}
+
+/**
+ * Body returned by `POST /auth/refresh` after a successful access-token
+ * refresh.
+ */
+export interface RefreshTokenResponse {
+  /**
+   * Lifetime of the new access token in seconds, as reported by the
+   * upstream OAuth provider.
+   */
+  expires_in: number;
+}
+
+/**
+ * Body returned by `POST /auth/logout` once the upstream revoke call
+ * has completed.
+ */
+export interface LogoutResponse {
+  /**
+   * Path or URL the browser should navigate to after the session has
+   * been cleared (e.g. the app home page).
+   */
+  redirect_to: string;
+}

package/tsconfig.browser.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "@private/tsconfig/tsconfig.dom.json",
+  "compilerOptions": {
+    "composite": true,
+    "rootDir": "src",
+    "tsBuildInfoFile": "build/tsconfig.browser.tsbuildinfo"
+  },
+  "include": ["src/browser/**/*", "src/shared/**/*"]
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.browser.json" },
+    { "path": "./tsconfig.server.json" }
+  ]
+}

package/tsconfig.server.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "@private/tsconfig/tsconfig.deno.json",
+  "compilerOptions": {
+    "composite": true,
+    "declaration": true,
+    "lib": ["ES2024", "DOM"],
+    "rootDir": "src",
+    "tsBuildInfoFile": "build/tsconfig.server.tsbuildinfo"
+  },
+  "include": ["src/server/**/*", "src/shared/**/*"]
+}

package/tsdown.config.ts

@@ -0,0 +1,38 @@
+import { vanillaExtractPlugin } from '@vanilla-extract/rollup-plugin';
+import { defineConfig } from 'tsdown';
+
+export default defineConfig([
+  {
+    entry: {
+      index: 'src/browser/index.ts',
+      react: 'src/browser/react/index.ts',
+      'react/lovable': 'src/browser/react/lovable/index.ts',
+    },
+    outDir: 'dist/browser',
+    platform: 'browser',
+    format: 'esm',
+    tsconfig: 'tsconfig.browser.json',
+    dts: true,
+    sourcemap: true,
+    clean: true,
+    exports: false,
+    unbundle: false,
+    plugins: [vanillaExtractPlugin()],
+  },
+  {
+    entry: {
+      'api-client': 'src/server/api-client-core/index.ts',
+      oauth: 'src/server/oauth.ts',
+      lovable: 'src/server/lovable/index.ts',
+    },
+    outDir: 'dist/server',
+    platform: 'neutral',
+    format: 'esm',
+    tsconfig: 'tsconfig.server.json',
+    dts: true,
+    sourcemap: true,
+    clean: true,
+    exports: false,
+    unbundle: true,
+  },
+]);

package/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['src/**/*.test.ts'],
+    passWithNoTests: true,
+  },
+});