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

package/src/server/hono/hubspot-connect-routes/cimd-public-routes.test.ts

@@ -0,0 +1,128 @@
+import { Hono } from 'hono';
+import { describe, expect, it, vi } from 'vitest';
+
+import { createTestAppKeys } from '../../utils/test-fixtures.ts';
+import {
+  handleCimdAppJwks,
+  handleCimdClientJson,
+} from './cimd-public-routes.ts';
+import type {
+  HubSpotConnectRoutesEnvCimd,
+  HubSpotConnectRoutesEnvClientSecret,
+} from './load-hubspot-connect-routes-env.ts';
+import type { HubSpotConnectOAuthRouteOptions } from './types.ts';
+
+const BASE_PATH = '/functions/v1/hubspot-connect';
+
+function buildOptions(
+  hubspotConnectEnv: HubSpotConnectOAuthRouteOptions['hubspotConnectEnv'],
+  appKeys: HubSpotConnectOAuthRouteOptions['appKeys'] = null
+): HubSpotConnectOAuthRouteOptions {
+  return {
+    appKeys,
+    refreshCookiePath: `${BASE_PATH}/auth`,
+    logger: { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+    basePath: BASE_PATH,
+    hubspotConnectEnv,
+    cimdClientMetadata: {
+      scope: {
+        required: ['crm.objects.contacts.read'],
+        optional: ['crm.objects.deals.read'],
+      },
+    },
+  };
+}
+
+const clientSecretEnv = {
+  hubspotAuthorizationEndpoint: 'https://auth.example.test/oauth/authorize',
+  hubspotOAuthApiOrigin: 'https://auth.example.test',
+  isCimdEnabled: false,
+  isDpopEnabled: false,
+  isAppPrivateKeyRequired: false,
+  hubspotClientId: 'test-client-id',
+  hubspotClientSecret: 'test-client-secret',
+} satisfies HubSpotConnectRoutesEnvClientSecret;
+
+const cimdEnv = {
+  hubspotAuthorizationEndpoint: 'https://auth.example.test/oauth/authorize',
+  hubspotOAuthApiOrigin: 'https://auth.example.test',
+  isCimdEnabled: true,
+  isDpopEnabled: false,
+  isAppPrivateKeyRequired: true,
+} satisfies HubSpotConnectRoutesEnvCimd;
+
+describe('handleCimdClientJson', () => {
+  it('returns client.json with redirect_uri, jwks_uri, and scope', async () => {
+    const app = new Hono();
+    app.get(`${BASE_PATH}/client.json`, (c) =>
+      handleCimdClientJson(c, buildOptions(clientSecretEnv))
+    );
+    const res = await app.request(
+      `http://app.example.test${BASE_PATH}/client.json`,
+      { method: 'GET' }
+    );
+
+    expect(res.status).toBe(200);
+    expect(res.headers.get('Content-Type')).toContain('application/json');
+
+    const body = (await res.json()) as {
+      redirect_uri: string;
+      jwks_uri: string;
+      scope: { required: string[]; optional?: string[] };
+    };
+
+    expect(body.redirect_uri).toBe(
+      `http://app.example.test${BASE_PATH}/auth/callback`
+    );
+    expect(body.jwks_uri).toBe(`http://app.example.test${BASE_PATH}/jwks.json`);
+    expect(body.scope.required).toContain('crm.objects.contacts.read');
+    expect(body.scope.optional).toContain('crm.objects.deals.read');
+  });
+});
+
+describe('handleCimdAppJwks', () => {
+  it('returns 404 when CIMD is not enabled', async () => {
+    const app = new Hono();
+    app.get('/jwks.json', (c) =>
+      handleCimdAppJwks(c, buildOptions(clientSecretEnv))
+    );
+    const res = await app.request('http://localhost/jwks.json', {
+      method: 'GET',
+    });
+    expect(res.status).toBe(404);
+  });
+
+  it('returns 503 when CIMD is enabled but appKeys are missing', async () => {
+    const app = new Hono();
+    app.get('/jwks.json', (c) =>
+      handleCimdAppJwks(c, buildOptions(cimdEnv, null))
+    );
+    const res = await app.request('http://localhost/jwks.json', {
+      method: 'GET',
+    });
+    expect(res.status).toBe(503);
+  });
+
+  it('returns JWKS with public key when CIMD is enabled and keys are present', async () => {
+    const appKeys = await createTestAppKeys();
+    const app = new Hono();
+    app.get('/jwks.json', (c) =>
+      handleCimdAppJwks(c, buildOptions(cimdEnv, appKeys))
+    );
+    const res = await app.request('http://localhost/jwks.json', {
+      method: 'GET',
+    });
+
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { keys: unknown[] };
+    expect(body.keys).toHaveLength(1);
+
+    const jwk = body.keys[0] as Record<string, unknown>;
+    expect(jwk.kty).toBe('EC');
+    expect(jwk.crv).toBe('P-256');
+    expect(jwk.alg).toBe('ES256');
+    expect(jwk.use).toBe('sig');
+    expect(jwk.kid).toBeDefined();
+    expect(jwk.d).toBeUndefined();
+  });
+});

package/src/server/hono/hubspot-connect-routes/cimd-public-routes.ts

@@ -0,0 +1,72 @@
+import type { Context } from 'hono';
+
+import type { JwkSet } from '../../types.ts';
+import { getJwkThumbprint } from '../../utils/jwk-utils.ts';
+import type { HubSpotConnectCimdClientDocument } from './cimd-client-metadata-types.ts';
+import type { HubSpotConnectOAuthRouteOptions } from './types.ts';
+import {
+  buildHubSpotAppJwksUrlFromRequest,
+  buildOAuthRedirectUriFromRequest,
+  type BuildOAuthRedirectUriFromRequestOptions,
+} from './utils.ts';
+
+export async function handleCimdClientJson(
+  c: Context,
+  options: HubSpotConnectOAuthRouteOptions
+): Promise<Response> {
+  const { cimdClientMetadata, basePath } = options;
+  if (!cimdClientMetadata) {
+    return c.text('CIMD client metadata is not configured', 500);
+  }
+
+  const xForwardedProto = c.req.header('x-forwarded-proto') ?? undefined;
+  const xForwardedHost = c.req.header('x-forwarded-host') ?? undefined;
+  const requestHostHeader = c.req.header('host') ?? undefined;
+
+  const forwarded: BuildOAuthRedirectUriFromRequestOptions = {
+    requestUrl: c.req.url,
+    basePath,
+    xForwardedProto,
+    xForwardedHost,
+    requestHostHeader,
+  };
+
+  const body: HubSpotConnectCimdClientDocument = {
+    redirect_uri: buildOAuthRedirectUriFromRequest(forwarded),
+    jwks_uri: buildHubSpotAppJwksUrlFromRequest(forwarded),
+    scope: cimdClientMetadata.scope,
+  };
+
+  return c.text(JSON.stringify(body, null, 2), 200, {
+    'Content-Type': 'application/json; charset=utf-8',
+  });
+}
+
+export async function handleCimdAppJwks(
+  c: Context,
+  options: HubSpotConnectOAuthRouteOptions
+): Promise<Response> {
+  const { appKeys, hubspotConnectEnv } = options;
+  if (!hubspotConnectEnv.isCimdEnabled) {
+    return c.text('Not found', 404);
+  }
+  if (!appKeys) {
+    return c.text('Missing app keys', 503);
+  }
+
+  const kid = await getJwkThumbprint({
+    publicKeyJwk: appKeys.appPublicKeyJwk,
+  });
+
+  const jwk = {
+    ...appKeys.appPublicKeyJwk,
+    kid,
+    use: 'sig',
+    alg: 'ES256',
+    key_ops: ['verify'],
+    ext: true,
+  } as JsonWebKey;
+
+  const jwks: JwkSet = { keys: [jwk] };
+  return c.json(jwks);
+}

package/src/server/hono/hubspot-connect-routes/constants.ts

@@ -0,0 +1,3 @@
+export const SESSION_MAX_AGE_SEC = 2592000;
+export const OAUTH_TEMP_MAX_AGE_SEC = 3600;
+export const REFRESH_COOKIE_MAX_AGE_SEC = 2592000;

package/src/server/hono/hubspot-connect-routes/fetch-hubspot-client-metadata.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from 'vitest';
+
+import type { HubSpotConnectCimdClientScope } from './cimd-client-metadata-types.ts';
+import { deriveHubSpotAuthorizeScopesFromClientMetadata } from './fetch-hubspot-client-metadata.ts';
+
+describe('deriveHubSpotAuthorizeScopesFromClientMetadata', () => {
+  it('returns scope and optionalScope when optional scopes are present', () => {
+    const result = deriveHubSpotAuthorizeScopesFromClientMetadata({
+      scope: {
+        required: ['crm.objects.contacts.read', 'settings.users.read'],
+        optional: ['crm.objects.deals.read'],
+      },
+    });
+
+    expect(result).toEqual({
+      ok: true,
+      scope: 'crm.objects.contacts.read settings.users.read',
+      optionalScope: 'crm.objects.deals.read',
+    });
+  });
+
+  it('returns scope only when optional is absent', () => {
+    const result = deriveHubSpotAuthorizeScopesFromClientMetadata({
+      scope: {
+        required: ['crm.objects.contacts.read'],
+      },
+    });
+
+    expect(result).toEqual({
+      ok: true,
+      scope: 'crm.objects.contacts.read',
+    });
+  });
+
+  it('returns scope only when optional is an empty array', () => {
+    const result = deriveHubSpotAuthorizeScopesFromClientMetadata({
+      scope: {
+        required: ['crm.objects.contacts.read'],
+        optional: [],
+      },
+    });
+
+    expect(result).toEqual({
+      ok: true,
+      scope: 'crm.objects.contacts.read',
+    });
+  });
+
+  it('fails when scope.required is missing or empty', () => {
+    const result = deriveHubSpotAuthorizeScopesFromClientMetadata({
+      scope: {} as unknown as HubSpotConnectCimdClientScope,
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.status).toBe(500);
+      expect(result.message).toContain('scope.required');
+    }
+  });
+
+  it('fails when optional is present but not an array', () => {
+    const result = deriveHubSpotAuthorizeScopesFromClientMetadata({
+      scope: {
+        required: ['a'],
+        optional: 'not-array' as unknown as string[],
+      },
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.status).toBe(500);
+      expect(result.message).toBe('Invalid scope.optional in client metadata');
+    }
+  });
+});

package/src/server/hono/hubspot-connect-routes/fetch-hubspot-client-metadata.ts

@@ -0,0 +1,73 @@
+import type { HubSpotConnectCimdClientMetadata } from './cimd-client-metadata-types.ts';
+
+export interface DeriveHubSpotAuthorizeScopesFromClientMetadataSuccess {
+  ok: true;
+  scope: string;
+  optionalScope?: string;
+}
+
+export interface DeriveHubSpotAuthorizeScopesFromClientMetadataFailure {
+  ok: false;
+  status: number;
+  message: string;
+}
+
+export type DeriveHubSpotAuthorizeScopesFromClientMetadataResult =
+  | DeriveHubSpotAuthorizeScopesFromClientMetadataSuccess
+  | DeriveHubSpotAuthorizeScopesFromClientMetadataFailure;
+
+/**
+ * Builds `scope` and `optional_scope` query values for HubSpot
+ * `/oauth/authorize` from in-memory client metadata (same shape as
+ * `HubSpotConnectCimdClientMetadata` / `startHubSpotConnectFunction({ client })`).
+ */
+export function deriveHubSpotAuthorizeScopesFromClientMetadata(
+  metadata: HubSpotConnectCimdClientMetadata
+): DeriveHubSpotAuthorizeScopesFromClientMetadataResult {
+  const required = metadata.scope?.required;
+  const requiredOk =
+    Array.isArray(required) &&
+    required.length > 0 &&
+    required.every((s) => typeof s === 'string' && s.length > 0);
+
+  if (!requiredOk) {
+    return {
+      ok: false,
+      status: 500,
+      message: 'Invalid or empty scope.required in client metadata',
+    };
+  }
+
+  const scope = required.join(' ');
+
+  const optionalRaw = metadata.scope.optional;
+  if (optionalRaw == null) {
+    return { ok: true, scope };
+  }
+
+  if (!Array.isArray(optionalRaw)) {
+    return {
+      ok: false,
+      status: 500,
+      message: 'Invalid scope.optional in client metadata',
+    };
+  }
+
+  if (optionalRaw.length === 0) {
+    return { ok: true, scope };
+  }
+
+  if (!optionalRaw.every((s) => typeof s === 'string' && s.length > 0)) {
+    return {
+      ok: false,
+      status: 500,
+      message: 'Invalid scope.optional in client metadata',
+    };
+  }
+
+  return {
+    ok: true,
+    scope,
+    optionalScope: optionalRaw.join(' '),
+  };
+}

package/src/server/hono/hubspot-connect-routes/hubspot-connect-routes.ts

@@ -0,0 +1,95 @@
+import type { Hono } from 'hono';
+
+import { noopLogger, type Logger } from '../../../shared/logger.ts';
+import type { AppKeys } from '../../types.ts';
+import { handleAuthCallback } from './auth-callback.ts';
+import { handleAuthInitSession } from './auth-init-session.ts';
+import { handleAuthLogout } from './auth-logout.ts';
+import { handleAuthRefresh } from './auth-refresh.ts';
+import { assertHubSpotConnectCimdClientMetadata } from './cimd-client-metadata-types.ts';
+import type { HubSpotConnectCimdClientMetadata } from './cimd-client-metadata-types.ts';
+import {
+  handleCimdAppJwks,
+  handleCimdClientJson,
+} from './cimd-public-routes.ts';
+import type { HubSpotConnectRoutesEnv } from './load-hubspot-connect-routes-env.ts';
+
+/**
+ * Options accepted by {@link registerHubSpotConnectRoutes}.
+ */
+export interface RegisterHubSpotConnectRoutesOptions {
+  /** The Hono app to mount the OAuth routes on. */
+  app: Hono;
+  /**
+   * Imported app keys from `secureStart`, or `null` when CIMD and DPoP
+   * are both disabled.
+   */
+  appKeys: AppKeys | null;
+  /**
+   * Path the routes are mounted under (no trailing slash). Used to
+   * scope refresh-token cookies via `Path=${basePath}/auth`.
+   */
+  basePath: string;
+  /**
+   * OAuth and client-mode settings, typically from
+   * {@link loadHubSpotConnectRoutesEnv}.
+   */
+  hubspotConnectEnv: HubSpotConnectRoutesEnv;
+  /**
+   * Scope configuration for `GET /client.json` and for authorize URL
+   * scopes when CIMD is off. Always required.
+   */
+  cimdClientMetadata: HubSpotConnectCimdClientMetadata;
+  /**
+   * Optional logger. When omitted the SDK uses a no-op logger so
+   * server-side state never leaks into the host application's
+   * console.
+   */
+  logger?: Logger;
+}
+
+/**
+ * Mounts hubspot-connect routes: OAuth (`/auth/...`); `GET /client.json`
+ * from `cimdClientMetadata`; `GET /jwks.json` when CIMD is enabled.
+ */
+export function registerHubSpotConnectRoutes(
+  options: RegisterHubSpotConnectRoutesOptions
+): void {
+  const {
+    app,
+    appKeys,
+    basePath,
+    hubspotConnectEnv,
+    cimdClientMetadata,
+    logger = noopLogger,
+  } = options;
+
+  if (!cimdClientMetadata) {
+    throw new Error(
+      'registerHubSpotConnectRoutes: cimdClientMetadata is required'
+    );
+  }
+  assertHubSpotConnectCimdClientMetadata(cimdClientMetadata);
+
+  const refreshCookiePath = `${basePath}/auth`;
+  const oauthRouteOptions = {
+    appKeys,
+    refreshCookiePath,
+    logger,
+    basePath,
+    hubspotConnectEnv,
+    cimdClientMetadata,
+  };
+
+  app.get('/client.json', (c) => handleCimdClientJson(c, oauthRouteOptions));
+  if (hubspotConnectEnv.isCimdEnabled) {
+    app.get('/jwks.json', (c) => handleCimdAppJwks(c, oauthRouteOptions));
+  }
+
+  app.get('/auth/init-session', (c) =>
+    handleAuthInitSession(c, oauthRouteOptions)
+  );
+  app.get('/auth/callback', (c) => handleAuthCallback(c, oauthRouteOptions));
+  app.post('/auth/refresh', (c) => handleAuthRefresh(c, oauthRouteOptions));
+  app.post('/auth/logout', (c) => handleAuthLogout(c, oauthRouteOptions));
+}

package/src/server/hono/hubspot-connect-routes/load-hubspot-connect-routes-env.test.ts

@@ -0,0 +1,145 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { loadHubSpotConnectRoutesEnv } from './load-hubspot-connect-routes-env.ts';
+
+const HUBSPOT_AUTHORIZATION_ENDPOINT_EXAMPLE =
+  'https://auth.hubspot.com/oauth/authorize';
+const HUBSPOT_OAUTH_API_ORIGIN_EXAMPLE = 'https://auth.hubspot.com';
+
+function stubHubSpotOAuthEndpoints(): void {
+  vi.stubEnv(
+    'HUBSPOT_AUTHORIZATION_ENDPOINT',
+    HUBSPOT_AUTHORIZATION_ENDPOINT_EXAMPLE
+  );
+  vi.stubEnv('HUBSPOT_OAUTH_API_ORIGIN', HUBSPOT_OAUTH_API_ORIGIN_EXAMPLE);
+}
+
+describe('loadHubSpotConnectRoutesEnv', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it('throws when HUBSPOT_AUTHORIZATION_ENDPOINT is missing', () => {
+    vi.stubEnv('HUBSPOT_OAUTH_API_ORIGIN', HUBSPOT_OAUTH_API_ORIGIN_EXAMPLE);
+    vi.stubEnv('HUBSPOT_CIMD_ENABLED', 'false');
+    vi.stubEnv('HUBSPOT_DPOP_ENABLED', 'false');
+    vi.stubEnv('HUBSPOT_CLIENT_ID', 'cid');
+    vi.stubEnv('HUBSPOT_CLIENT_SECRET', 'sec');
+    expect(() => loadHubSpotConnectRoutesEnv()).toThrow(
+      'Missing required environment variable: HUBSPOT_AUTHORIZATION_ENDPOINT'
+    );
+  });
+
+  it('throws when HUBSPOT_OAUTH_API_ORIGIN is missing', () => {
+    vi.stubEnv(
+      'HUBSPOT_AUTHORIZATION_ENDPOINT',
+      HUBSPOT_AUTHORIZATION_ENDPOINT_EXAMPLE
+    );
+    vi.stubEnv('HUBSPOT_CIMD_ENABLED', 'false');
+    vi.stubEnv('HUBSPOT_DPOP_ENABLED', 'false');
+    vi.stubEnv('HUBSPOT_CLIENT_ID', 'cid');
+    vi.stubEnv('HUBSPOT_CLIENT_SECRET', 'sec');
+    expect(() => loadHubSpotConnectRoutesEnv()).toThrow(
+      'Missing required environment variable: HUBSPOT_OAUTH_API_ORIGIN'
+    );
+  });
+
+  it('throws when CIMD is disabled and HUBSPOT_CLIENT_ID is missing', () => {
+    stubHubSpotOAuthEndpoints();
+    vi.stubEnv('HUBSPOT_CIMD_ENABLED', 'false');
+    vi.stubEnv('HUBSPOT_DPOP_ENABLED', 'false');
+    vi.stubEnv('HUBSPOT_CLIENT_SECRET', 'sec');
+    expect(() => loadHubSpotConnectRoutesEnv()).toThrow(
+      'Missing required environment variable: HUBSPOT_CLIENT_ID'
+    );
+  });
+
+  it('throws when CIMD is disabled and HUBSPOT_CLIENT_SECRET is missing', () => {
+    stubHubSpotOAuthEndpoints();
+    vi.stubEnv('HUBSPOT_CIMD_ENABLED', 'false');
+    vi.stubEnv('HUBSPOT_DPOP_ENABLED', 'false');
+    vi.stubEnv('HUBSPOT_CLIENT_ID', 'cid');
+    expect(() => loadHubSpotConnectRoutesEnv()).toThrow(
+      'Missing required environment variable: HUBSPOT_CLIENT_SECRET'
+    );
+  });
+
+  it('does not require client id or secret when CIMD is enabled', () => {
+    stubHubSpotOAuthEndpoints();
+    vi.stubEnv('HUBSPOT_CIMD_ENABLED', 'true');
+    vi.stubEnv('HUBSPOT_DPOP_ENABLED', 'false');
+    const env = loadHubSpotConnectRoutesEnv();
+    expect(env.isCimdEnabled).toBe(true);
+    expect(env.hubspotAuthorizationEndpoint).toBe(
+      HUBSPOT_AUTHORIZATION_ENDPOINT_EXAMPLE
+    );
+    expect(env.hubspotOAuthApiOrigin).toBe(HUBSPOT_OAUTH_API_ORIGIN_EXAMPLE);
+    expect(env.isDpopEnabled).toBe(false);
+    expect(env.isAppPrivateKeyRequired).toBe(true);
+  });
+
+  it('returns client credentials when CIMD is disabled', () => {
+    stubHubSpotOAuthEndpoints();
+    vi.stubEnv('HUBSPOT_CIMD_ENABLED', 'false');
+    vi.stubEnv('HUBSPOT_DPOP_ENABLED', 'false');
+    vi.stubEnv('HUBSPOT_CLIENT_ID', 'my-id');
+    vi.stubEnv('HUBSPOT_CLIENT_SECRET', 'my-secret');
+    const env = loadHubSpotConnectRoutesEnv();
+    expect(env.isCimdEnabled).toBe(false);
+    if (!env.isCimdEnabled) {
+      expect(env.hubspotClientId).toBe('my-id');
+      expect(env.hubspotClientSecret).toBe('my-secret');
+    }
+    expect(env.isAppPrivateKeyRequired).toBe(false);
+    expect(env.isDpopEnabled).toBe(false);
+  });
+
+  it('sets isAppPrivateKeyRequired false when both CIMD and DPoP are false', () => {
+    stubHubSpotOAuthEndpoints();
+    vi.stubEnv('HUBSPOT_CIMD_ENABLED', 'false');
+    vi.stubEnv('HUBSPOT_DPOP_ENABLED', 'false');
+    vi.stubEnv('HUBSPOT_CLIENT_ID', 'id');
+    vi.stubEnv('HUBSPOT_CLIENT_SECRET', 'sec');
+    expect(loadHubSpotConnectRoutesEnv().isAppPrivateKeyRequired).toBe(false);
+  });
+
+  it('sets isAppPrivateKeyRequired true when CIMD is enabled and DPoP is false', () => {
+    stubHubSpotOAuthEndpoints();
+    vi.stubEnv('HUBSPOT_CIMD_ENABLED', 'true');
+    vi.stubEnv('HUBSPOT_DPOP_ENABLED', 'false');
+    const env = loadHubSpotConnectRoutesEnv();
+    expect(env.isAppPrivateKeyRequired).toBe(true);
+  });
+
+  it('sets isAppPrivateKeyRequired true when CIMD is false and DPoP is enabled', () => {
+    stubHubSpotOAuthEndpoints();
+    vi.stubEnv('HUBSPOT_CIMD_ENABLED', 'false');
+    vi.stubEnv('HUBSPOT_DPOP_ENABLED', 'true');
+    vi.stubEnv('HUBSPOT_CLIENT_ID', 'id');
+    vi.stubEnv('HUBSPOT_CLIENT_SECRET', 'sec');
+    expect(loadHubSpotConnectRoutesEnv().isAppPrivateKeyRequired).toBe(true);
+  });
+
+  it('sets isAppPrivateKeyRequired true when both are enabled by default', () => {
+    stubHubSpotOAuthEndpoints();
+    const env = loadHubSpotConnectRoutesEnv();
+    expect(env.isCimdEnabled).toBe(true);
+    expect(env.isDpopEnabled).toBe(true);
+    expect(env.isAppPrivateKeyRequired).toBe(true);
+  });
+
+  it('normalizes HUBSPOT_OAUTH_API_ORIGIN to an origin URL', () => {
+    vi.stubEnv(
+      'HUBSPOT_AUTHORIZATION_ENDPOINT',
+      HUBSPOT_AUTHORIZATION_ENDPOINT_EXAMPLE
+    );
+    vi.stubEnv(
+      'HUBSPOT_OAUTH_API_ORIGIN',
+      'https://api.hubapi.com/extra/path/'
+    );
+    vi.stubEnv('HUBSPOT_CIMD_ENABLED', 'true');
+    vi.stubEnv('HUBSPOT_DPOP_ENABLED', 'false');
+    const env = loadHubSpotConnectRoutesEnv();
+    expect(env.hubspotOAuthApiOrigin).toBe('https://api.hubapi.com');
+  });
+});

package/src/server/hono/hubspot-connect-routes/load-hubspot-connect-routes-env.ts

@@ -0,0 +1,67 @@
+import {
+  isHubspotCimdEnabled,
+  isHubspotDpopEnabled,
+  requireEnv,
+} from '../../utils/env-utils.ts';
+
+/**
+ * HubSpot OAuth and client-mode settings read once for hubspot-connect
+ * routes. Built by {@link loadHubSpotConnectRoutesEnv}.
+ */
+export type HubSpotConnectRoutesEnv =
+  | HubSpotConnectRoutesEnvCimd
+  | HubSpotConnectRoutesEnvClientSecret;
+
+export interface HubSpotConnectRoutesEnvCimd {
+  hubspotAuthorizationEndpoint: string;
+  hubspotOAuthApiOrigin: string;
+  isCimdEnabled: true;
+  isDpopEnabled: boolean;
+  isAppPrivateKeyRequired: boolean;
+}
+
+export interface HubSpotConnectRoutesEnvClientSecret {
+  hubspotAuthorizationEndpoint: string;
+  hubspotOAuthApiOrigin: string;
+  isCimdEnabled: false;
+  isDpopEnabled: boolean;
+  isAppPrivateKeyRequired: boolean;
+  hubspotClientId: string;
+  hubspotClientSecret: string;
+}
+
+/**
+ * Reads hubspot-connect environment variables from `process.env` or
+ * `Deno.env` and returns a typed object for
+ * {@link registerHubSpotConnectRoutes}.
+ */
+export function loadHubSpotConnectRoutesEnv(): HubSpotConnectRoutesEnv {
+  const hubspotAuthorizationEndpoint = requireEnv(
+    'HUBSPOT_AUTHORIZATION_ENDPOINT'
+  );
+  const hubspotOAuthApiOrigin = new URL(requireEnv('HUBSPOT_OAUTH_API_ORIGIN'))
+    .origin;
+  const isCimdEnabled = isHubspotCimdEnabled();
+  const isDpopEnabled = isHubspotDpopEnabled();
+  const isAppPrivateKeyRequired = isCimdEnabled || isDpopEnabled;
+
+  if (isCimdEnabled) {
+    return {
+      hubspotAuthorizationEndpoint,
+      hubspotOAuthApiOrigin,
+      isCimdEnabled: true,
+      isDpopEnabled,
+      isAppPrivateKeyRequired,
+    };
+  }
+
+  return {
+    hubspotAuthorizationEndpoint,
+    hubspotOAuthApiOrigin,
+    isCimdEnabled: false,
+    isDpopEnabled,
+    isAppPrivateKeyRequired,
+    hubspotClientId: requireEnv('HUBSPOT_CLIENT_ID'),
+    hubspotClientSecret: requireEnv('HUBSPOT_CLIENT_SECRET'),
+  };
+}