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

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

@@ -0,0 +1,181 @@
+import type { AppKeys } from '../../types.ts';
+import { signDpopProof } from '../../utils/dpop-utils.ts';
+import { signJwt } from '../../utils/jwt-utils.ts';
+
+/**
+ * Lifetime of the OAuth `client_assertion` JWT in seconds. Short by
+ * design — RFC 7521 recommends short-lived assertions, and HubSpot's
+ * authorization server rejects assertions older than ~5 minutes.
+ */
+const CLIENT_ASSERTION_TTL_SEC = 60;
+
+/**
+ * The `client_assertion_type` value mandated by RFC 7523 §2.2 for
+ * JWT-bearer client authentication.
+ */
+const JWT_BEARER_ASSERTION_TYPE =
+  'urn:ietf:params:oauth:client-assertion-type:jwt-bearer';
+
+/**
+ * Wire shape of a HubSpot OAuth token-endpoint success response.
+ */
+export interface OAuthTokenResponse {
+  /** New DPoP-bound access token (sender-constrained). */
+  access_token: string;
+  /** New refresh token, opaque to the client. */
+  refresh_token: string;
+  /** Lifetime of `access_token` in seconds. */
+  expires_in: number;
+}
+
+export interface BuildClientAssertionOptions {
+  appKeys: AppKeys;
+  /** Client ID URL — used as both `iss` and `sub`. */
+  clientId: string;
+  /** Token-endpoint URL — used as `aud`. */
+  audience: string;
+}
+
+/**
+ * Mints a short-lived ES256 JWT used as the `client_assertion`
+ * parameter when calling HubSpot's token endpoint, per RFC 7523.
+ */
+export async function buildClientAssertion(
+  options: BuildClientAssertionOptions
+): Promise<string> {
+  const { appKeys, clientId, audience } = options;
+  return signJwt({
+    privateKey: appKeys.appPrivateKey,
+    payload: {
+      iss: clientId,
+      sub: clientId,
+      aud: audience,
+      jti: crypto.randomUUID(),
+    },
+    ttlSeconds: CLIENT_ASSERTION_TTL_SEC,
+  });
+}
+
+export interface BuildTokenEndpointDpopProofOptions {
+  appKeys: AppKeys;
+  /** Token-endpoint URL — used as the DPoP `htu` claim. */
+  tokenEndpointUrl: string;
+  /** Hash of the app session ID — used as the DPoP `sid` claim. */
+  sessionIdHash: string;
+}
+
+/**
+ * Signs a DPoP proof for a `POST` to HubSpot's token endpoint. RFC 9449
+ * binds the resulting access token to the proving public key so that
+ * later API calls must come from the same key holder.
+ */
+export async function buildTokenEndpointDpopProof(
+  options: BuildTokenEndpointDpopProofOptions
+): Promise<string> {
+  const { appKeys, tokenEndpointUrl, sessionIdHash } = options;
+  return signDpopProof({
+    appKeys,
+    claims: {
+      htm: 'POST',
+      htu: tokenEndpointUrl,
+      jti: crypto.randomUUID(),
+      iat: Math.floor(Date.now() / 1000),
+      sid: sessionIdHash,
+    },
+  });
+}
+
+export interface RequestOAuthTokenOptions {
+  tokenEndpointUrl: string;
+  /** Body parameters; serialized to `application/x-www-form-urlencoded`. */
+  formParams: Record<string, string>;
+  /**
+   * When true, a `DPoP` header is required and `dpopProof` must be set.
+   */
+  isDpopEnabled: boolean;
+  /**
+   * DPoP proof for this request; required when `isDpopEnabled` is true.
+   */
+  dpopProof?: string;
+}
+
+export interface RequestOAuthTokenSuccess {
+  ok: true;
+  body: OAuthTokenResponse;
+}
+
+export interface RequestOAuthTokenFailure {
+  ok: false;
+  /** HTTP status returned by the upstream endpoint. */
+  status: number;
+  /** Error body as text — used to compose the SDK's error response. */
+  errorText: string;
+}
+
+export type RequestOAuthTokenResult =
+  | RequestOAuthTokenSuccess
+  | RequestOAuthTokenFailure;
+
+/**
+ * POSTs an `application/x-www-form-urlencoded` body to a HubSpot token
+ * endpoint. Attaches a `DPoP` header when `isDpopEnabled` is true and
+ * `dpopProof` is provided. Reads the response once — either
+ * as JSON on success or as text on failure — so callers never have to
+ * consume the body twice.
+ */
+export async function requestOAuthToken(
+  options: RequestOAuthTokenOptions
+): Promise<RequestOAuthTokenResult> {
+  const { tokenEndpointUrl, formParams, dpopProof, isDpopEnabled } = options;
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/x-www-form-urlencoded',
+  };
+  if (isDpopEnabled) {
+    if (!dpopProof) {
+      throw new Error('DPoP proof is required when DPoP is enabled');
+    }
+    headers.DPoP = dpopProof;
+  }
+  const tokenResponse = await fetch(tokenEndpointUrl, {
+    method: 'POST',
+    headers,
+    body: new URLSearchParams(formParams),
+  });
+  if (!tokenResponse.ok) {
+    const errorText = await tokenResponse.text();
+    return { ok: false, status: tokenResponse.status, errorText };
+  }
+  const body = (await tokenResponse.json()) as OAuthTokenResponse;
+  return { ok: true, body };
+}
+
+/**
+ * Form parameters always present on the OAuth `client_assertion` flow.
+ * Spread into the call site's `formParams`.
+ */
+export function buildClientAssertionFormParams(input: {
+  clientId: string;
+  clientAssertion: string;
+}): Record<string, string> {
+  const { clientId, clientAssertion } = input;
+  return {
+    client_id: clientId,
+    client_assertion_type: JWT_BEARER_ASSERTION_TYPE,
+    client_assertion: clientAssertion,
+  };
+}
+
+export interface BuildClientSecretFormParamsOptions {
+  clientId: string;
+  clientSecret: string;
+}
+
+export function buildClientSecretFormParams(
+  options: BuildClientSecretFormParamsOptions
+): Record<string, string> {
+  const { clientId, clientSecret } = options;
+  return {
+    client_id: clientId,
+    client_secret: clientSecret,
+  };
+}

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

@@ -0,0 +1,36 @@
+import type { Logger } from '../../../shared/logger.ts';
+import type { AppKeys } from '../../types.ts';
+import type { HubSpotConnectCimdClientMetadata } from './cimd-client-metadata-types.ts';
+import type { HubSpotConnectRoutesEnv } from './load-hubspot-connect-routes-env.ts';
+
+/**
+ * Configuration shared by every OAuth route handler in this module.
+ */
+export interface HubSpotConnectOAuthRouteOptions {
+  /**
+   * Imported app keys from `secureStart`, or `null` when CIMD and DPoP
+   * are both disabled.
+   */
+  appKeys: AppKeys | null;
+  /**
+   * Cookie `Path=` attribute applied to refresh-token cookies. The
+   * caller is responsible for picking a path that scopes the cookie
+   * to the OAuth refresh endpoint and nothing else.
+   */
+  refreshCookiePath: string;
+  /** Logger forwarded from `registerHubSpotConnectRoutes`. */
+  logger: Logger;
+  /**
+   * Mount path for hubspot-connect (e.g. `/functions/v1/hubspot-connect`),
+   * used to build OAuth `redirect_uri`.
+   */
+  basePath: string;
+  /** OAuth and client-mode settings from {@link loadHubSpotConnectRoutesEnv}. */
+  hubspotConnectEnv: HubSpotConnectRoutesEnv;
+  /**
+   * Scope configuration for `client.json` and for `/auth/init-session`
+   * authorize `scope` / `optional_scope` when CIMD is off (in-memory; no
+   * HTTP fetch). Required for all hubspot-connect registrations.
+   */
+  cimdClientMetadata: HubSpotConnectCimdClientMetadata;
+}

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

@@ -0,0 +1,132 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  buildCimdClientIdUrlFromRequest,
+  buildHubSpotAppJwksUrlFromRequest,
+  buildOAuthRedirectUriFromRequest,
+  getRequestHostForHubspotConnect,
+} from './utils.ts';
+
+describe('buildCimdClientIdUrlFromRequest', () => {
+  it('builds client id URL under base path', () => {
+    expect(
+      buildCimdClientIdUrlFromRequest({
+        requestUrl:
+          'https://third-party-app.test:5173/functions/v1/hubspot-connect/auth/init-session',
+        basePath: '/functions/v1/hubspot-connect',
+      })
+    ).toBe(
+      'https://third-party-app.test:5173/functions/v1/hubspot-connect/client.json'
+    );
+  });
+
+  it('uses X-Forwarded-Proto and X-Forwarded-Host when present', () => {
+    expect(
+      buildCimdClientIdUrlFromRequest({
+        requestUrl:
+          'http://127.0.0.1:5175/functions/v1/hubspot-connect/auth/init-session',
+        basePath: '/functions/v1/hubspot-connect',
+        xForwardedProto: 'https',
+        xForwardedHost: 'third-party-app.test:5173',
+      })
+    ).toBe(
+      'https://third-party-app.test:5173/functions/v1/hubspot-connect/client.json'
+    );
+  });
+});
+
+describe('buildHubSpotAppJwksUrlFromRequest', () => {
+  it('builds app JWKS URL under base path', () => {
+    expect(
+      buildHubSpotAppJwksUrlFromRequest({
+        requestUrl:
+          'https://third-party-app.test:5173/functions/v1/hubspot-connect/auth/init-session',
+        basePath: '/functions/v1/hubspot-connect',
+      })
+    ).toBe(
+      'https://third-party-app.test:5173/functions/v1/hubspot-connect/jwks.json'
+    );
+  });
+});
+
+describe('buildOAuthRedirectUriFromRequest', () => {
+  it('builds callback URL from origin and base path', () => {
+    expect(
+      buildOAuthRedirectUriFromRequest({
+        requestUrl:
+          'https://third-party-app.test:5173/functions/v1/hubspot-connect/auth/init-session',
+        basePath: '/functions/v1/hubspot-connect',
+      })
+    ).toBe(
+      'https://third-party-app.test:5173/functions/v1/hubspot-connect/auth/callback'
+    );
+  });
+
+  it('strips a trailing slash from basePath', () => {
+    expect(
+      buildOAuthRedirectUriFromRequest({
+        requestUrl: 'https://example.com/x',
+        basePath: '/functions/v1/hubspot-connect/',
+      })
+    ).toBe('https://example.com/functions/v1/hubspot-connect/auth/callback');
+  });
+
+  it('uses X-Forwarded-Proto and X-Forwarded-Host when present', () => {
+    expect(
+      buildOAuthRedirectUriFromRequest({
+        requestUrl:
+          'http://127.0.0.1:5175/functions/v1/hubspot-connect/auth/init-session',
+        basePath: '/functions/v1/hubspot-connect',
+        xForwardedProto: 'https',
+        xForwardedHost: 'third-party-app.test:5173',
+      })
+    ).toBe(
+      'https://third-party-app.test:5173/functions/v1/hubspot-connect/auth/callback'
+    );
+  });
+
+  it('uses X-Forwarded-Proto with Host header when X-Forwarded-Host is absent', () => {
+    expect(
+      buildOAuthRedirectUriFromRequest({
+        requestUrl:
+          'http://127.0.0.1:5175/functions/v1/hubspot-connect/auth/init-session',
+        basePath: '/functions/v1/hubspot-connect',
+        xForwardedProto: 'https',
+        requestHostHeader: 'third-party-app.test:5173',
+      })
+    ).toBe(
+      'https://third-party-app.test:5173/functions/v1/hubspot-connect/auth/callback'
+    );
+  });
+
+  it('uses X-Forwarded-Proto with request URL host when forwarded host and Host are absent', () => {
+    expect(
+      buildOAuthRedirectUriFromRequest({
+        requestUrl:
+          'http://127.0.0.1:5175/functions/v1/hubspot-connect/auth/init-session',
+        basePath: '/functions/v1/hubspot-connect',
+        xForwardedProto: 'https',
+      })
+    ).toBe('https://127.0.0.1:5175/functions/v1/hubspot-connect/auth/callback');
+  });
+});
+
+describe('getRequestHostForHubspotConnect', () => {
+  it('prefers X-Forwarded-Host', () => {
+    expect(
+      getRequestHostForHubspotConnect({
+        requestUrl: 'http://127.0.0.1:5175/x',
+        xForwardedHost: 'third-party-app.test:5173',
+      })
+    ).toBe('third-party-app.test:5173');
+  });
+
+  it('uses Host header when X-Forwarded-Host is absent', () => {
+    expect(
+      getRequestHostForHubspotConnect({
+        requestUrl: 'http://127.0.0.1:5175/x',
+        requestHostHeader: 'third-party-app.test:5173',
+      })
+    ).toBe('third-party-app.test:5173');
+  });
+});

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

@@ -0,0 +1,138 @@
+import { serializeCookie } from '../utils/cookie-utils.ts';
+
+export function clearTempCookie(name: string): string {
+  return serializeCookie({
+    name,
+    value: '',
+    path: '/',
+    sameSite: 'Lax',
+    maxAge: 0,
+  });
+}
+
+export function isSafeReturnPath(rawPath: string): boolean {
+  if (!rawPath.startsWith('/')) return false;
+  if (rawPath.includes('\0')) return false;
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(rawPath);
+  } catch {
+    return false;
+  }
+  if (!decoded.startsWith('/')) return false;
+  const second = decoded.charAt(1);
+  if (second === '/' || second === '\\') return false;
+  return true;
+}
+
+export function getRequestHost(requestUrl: string): string {
+  return new URL(requestUrl).host;
+}
+
+export interface GetRequestHostForHubspotConnectOptions {
+  requestUrl: string;
+  xForwardedHost?: string | undefined;
+  /** `Host` when `X-Forwarded-Host` is absent (some proxies only set `X-Forwarded-Proto`). */
+  requestHostHeader?: string | undefined;
+}
+
+/**
+ * Host for CIMD `client_id` URLs when hubspot-connect sits behind a reverse
+ * proxy (e.g. Vite → Deno): prefers `X-Forwarded-Host`, then `Host`, then the
+ * request URL host.
+ */
+export function getRequestHostForHubspotConnect(
+  options: GetRequestHostForHubspotConnectOptions
+): string {
+  const rawForwarded = options.xForwardedHost?.split(',')[0]?.trim();
+  if (rawForwarded) {
+    try {
+      return new URL(`https://${rawForwarded}`).host;
+    } catch {
+      /* invalid forwarded host */
+    }
+  }
+  const rawHost = options.requestHostHeader?.split(',')[0]?.trim();
+  if (rawHost) {
+    try {
+      return new URL(`https://${rawHost}`).host;
+    } catch {
+      /* invalid host header */
+    }
+  }
+  return getRequestHost(options.requestUrl);
+}
+
+export interface BuildOAuthRedirectUriFromRequestOptions {
+  requestUrl: string;
+  basePath: string;
+  xForwardedProto?: string | undefined;
+  xForwardedHost?: string | undefined;
+  /** `Host` when `X-Forwarded-Host` is absent but `X-Forwarded-Proto` is set. */
+  requestHostHeader?: string | undefined;
+}
+
+function normalizeHubSpotConnectBasePath(basePath: string): string {
+  return basePath.endsWith('/') && basePath.length > 1
+    ? basePath.slice(0, -1)
+    : basePath;
+}
+
+/**
+ * Public origin for hubspot-connect URLs (`redirect_uri`, CIMD `client_id`,
+ * `jwks_uri`). Matches the host/proto rules used for the OAuth callback.
+ */
+export function buildHubSpotConnectRequestOrigin(
+  options: BuildOAuthRedirectUriFromRequestOptions
+): string {
+  const { requestUrl, xForwardedProto, xForwardedHost, requestHostHeader } =
+    options;
+  const proto = xForwardedProto?.split(',')[0]?.trim();
+  if (proto && (proto === 'http' || proto === 'https')) {
+    const forwardedHost = xForwardedHost?.split(',')[0]?.trim();
+    const hostHeader = requestHostHeader?.split(',')[0]?.trim();
+    const hostPart = forwardedHost || hostHeader || new URL(requestUrl).host;
+    return `${proto}://${hostPart}`;
+  }
+  return new URL(requestUrl).origin;
+}
+
+/**
+ * OAuth `redirect_uri` for the hubspot-connect callback. Uses
+ * `X-Forwarded-Proto` with `X-Forwarded-Host`, then `Host`, then the request URL
+ * host when the proto is forwarded (reverse proxy); otherwise the request URL
+ * origin.
+ */
+export function buildOAuthRedirectUriFromRequest(
+  options: BuildOAuthRedirectUriFromRequestOptions
+): string {
+  const trimmed = normalizeHubSpotConnectBasePath(options.basePath);
+  const origin = buildHubSpotConnectRequestOrigin(options);
+  return `${origin}${trimmed}/auth/callback`;
+}
+
+/**
+ * CIMD `client_id` URL: `{origin}{basePath}/client.json`.
+ */
+export function buildCimdClientIdUrlFromRequest(
+  options: BuildOAuthRedirectUriFromRequestOptions
+): string {
+  const trimmed = normalizeHubSpotConnectBasePath(options.basePath);
+  const origin = buildHubSpotConnectRequestOrigin(options);
+  return `${origin}${trimmed}/client.json`;
+}
+
+/**
+ * App JWKS URL published in CIMD: `{origin}{basePath}/jwks.json`.
+ */
+export function buildHubSpotAppJwksUrlFromRequest(
+  options: BuildOAuthRedirectUriFromRequestOptions
+): string {
+  const trimmed = normalizeHubSpotConnectBasePath(options.basePath);
+  const origin = buildHubSpotConnectRequestOrigin(options);
+  return `${origin}${trimmed}/jwks.json`;
+}
+
+export function isPositiveFiniteNumber(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0;
+}

package/src/server/hono/index.ts

@@ -0,0 +1,6 @@
+export * from './hono-request-handler.ts';
+export * from './hubspot-connect-routes/cimd-client-metadata-types.ts';
+export * from './hubspot-connect-routes/hubspot-connect-routes.ts';
+export * from './hubspot-connect-routes/load-hubspot-connect-routes-env.ts';
+export * from './types.ts';
+export * from '../types.ts';

package/src/server/hono/types.ts

@@ -0,0 +1,25 @@
+import type { HubSpotClient } from '../api-client-core/types.ts';
+import type { HubSpotProxy } from '../types.ts';
+
+export interface AppConnectHonoBindings {
+  /**
+   * Authenticated proxy that issues DPoP-bound calls to HubSpot's
+   * API on behalf of the browser session that made the inbound
+   * request. `authenticated: false` when the session cookies are
+   * absent or invalid.
+   */
+  hubSpotProxy: HubSpotProxy;
+  /**
+   * Authenticated HubSpot API client.
+   */
+  hubSpotClient: HubSpotClient;
+}
+
+/**
+ * Hono environment shape used by handlers running inside a hubspot-
+ * connect request handler. Exposes the per-request
+ * {@link HubSpotProxy} as `c.env.hubSpotProxy`.
+ */
+export interface AppConnectHonoEnv {
+  Bindings: AppConnectHonoBindings;
+}

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

@@ -0,0 +1,55 @@
+import type { Context } from 'hono';
+
+export interface SetResponseCookieOptions {
+  c: Context;
+  value: string;
+}
+
+/**
+ * Appends a `Set-Cookie` header to the response. Hono replaces single
+ * headers by default, so this uses `{ append: true }` to emit multiple
+ * cookies on the same response.
+ */
+export function setResponseCookie(options: SetResponseCookieOptions): void {
+  const { c, value } = options;
+  c.header('Set-Cookie', value, { append: true });
+}
+
+export interface SerializeCookieOptions {
+  name: string;
+  value: string;
+  /** `__Host-` prefix requires `Path=/` and is recommended for session cookies. */
+  path: string;
+  /** Defaults to `Strict`. Use `Lax` for short-lived OAuth temp cookies. */
+  sameSite?: 'Strict' | 'Lax';
+  /** Lifetime in seconds. `0` deletes the cookie. */
+  maxAge: number;
+  /** Defaults to `true`; only set `false` for tests or non-HTTPS dev hosts. */
+  secure?: boolean;
+  /** Defaults to `true`. */
+  httpOnly?: boolean;
+}
+
+/**
+ * Builds a `Set-Cookie` header value with HubSpot's default attributes
+ * (HttpOnly, Secure, SameSite). Centralizes the serialization so all
+ * cookies share the same policy.
+ */
+export function serializeCookie(options: SerializeCookieOptions): string {
+  const {
+    name,
+    value,
+    path,
+    sameSite = 'Strict',
+    maxAge,
+    secure = true,
+    httpOnly = true,
+  } = options;
+  const parts: string[] = [`${name}=${value}`];
+  if (httpOnly) parts.push('HttpOnly');
+  if (secure) parts.push('Secure');
+  parts.push(`SameSite=${sameSite}`);
+  parts.push(`Path=${path}`);
+  parts.push(`Max-Age=${maxAge}`);
+  return parts.join('; ');
+}

package/src/server/import-app-keys.ts

@@ -0,0 +1,55 @@
+import type { AppKeys } from './types.ts';
+import { base64StandardToArrayBuffer } from './utils/base64-utils.ts';
+
+/**
+ * Imports a base64-encoded PKCS8 ES256 private key into the
+ * `AppKeys` shape used throughout the SDK.
+ *
+ * The function imports the key twice: once as **extractable** to
+ * derive the public JWK (via `crypto.subtle.exportKey`), and once
+ * as **non-extractable** so the long-lived `appPrivateKey` can never
+ * be exfiltrated.
+ *
+ * @throws {Error} When `envKey` is empty/undefined or when the key
+ *   isn't an EC P-256 keypair.
+ */
+export async function importAppKeys(
+  envKey: string | undefined
+): Promise<AppKeys> {
+  const b64 = envKey?.trim() ?? '';
+  if (!b64) {
+    throw new Error('HUBSPOT_APP_PRIVATE_KEY is not set');
+  }
+
+  const pkcs8 = base64StandardToArrayBuffer(b64);
+  const tempPrivateKey = await crypto.subtle.importKey(
+    'pkcs8',
+    pkcs8,
+    { name: 'ECDSA', namedCurve: 'P-256' },
+    true,
+    ['sign']
+  );
+  const privateJwk = await crypto.subtle.exportKey('jwk', tempPrivateKey);
+  if (
+    privateJwk.kty !== 'EC' ||
+    privateJwk.crv !== 'P-256' ||
+    typeof privateJwk.x !== 'string' ||
+    typeof privateJwk.y !== 'string'
+  ) {
+    throw new Error('Expected P-256 EC private key JWK with x and y');
+  }
+  const appPublicKeyJwk: JsonWebKey = {
+    kty: 'EC',
+    crv: 'P-256',
+    x: privateJwk.x,
+    y: privateJwk.y,
+  };
+  const appPrivateKey = await crypto.subtle.importKey(
+    'pkcs8',
+    pkcs8,
+    { name: 'ECDSA', namedCurve: 'P-256' },
+    false,
+    ['sign']
+  );
+  return { appPrivateKey, appPublicKeyJwk };
+}

package/src/server/lovable/create-app-function-start.ts

@@ -0,0 +1,55 @@
+import type { Hono } from 'hono';
+
+import type { Logger } from '../../shared/logger.ts';
+import { createAppConnectRequestHandler } from '../hono/hono-request-handler.ts';
+import type { AppConnectHonoEnv } from '../hono/types.ts';
+import type { SecureStartContext } from '../secure-start-core.ts';
+
+const PORT = Deno.env.get('PORT');
+const serveOptions =
+  typeof PORT === 'string' ? { port: parseInt(PORT, 10) } : {};
+
+export type RegisterAppFunctionRoutesFunction = (
+  app: Hono<AppConnectHonoEnv>
+) => void;
+
+export interface CreateAppFunctionStartOptions {
+  /** Base path the user's routes are mounted under (e.g. `/functions/v1/api`). */
+  basePath: string;
+  /** Attach app routes to the SDK-owned Hono instance. */
+  registerRoutes: RegisterAppFunctionRoutesFunction;
+  /** Optional logger forwarded to `createAppConnectRequestHandler`. */
+  logger?: Logger;
+}
+
+export type AppFunctionStart = (context: SecureStartContext) => Promise<void>;
+
+/**
+ * Builds a Deno-style `start({ appKeys })` entry point that boots a
+ * Hono app under `basePath`, wires the SDK's per-request HubSpot
+ * proxy via `createAppConnectRequestHandler`, and serves it with
+ * `Deno.serve` on `PORT`.
+ */
+export function createAppFunctionStart(
+  options: CreateAppFunctionStartOptions
+): AppFunctionStart {
+  const { basePath, registerRoutes, logger } = options;
+
+  return ({ appKeys }) => {
+    Deno.serve(
+      serveOptions,
+      createAppConnectRequestHandler({
+        appKeys,
+        ...(logger !== undefined ? { logger } : {}),
+        registerRoutes: (app) => {
+          registerRoutes(app.basePath(basePath));
+        },
+      })
+    );
+
+    console.log(
+      `[app-function ${basePath}] Listening on http://localhost:${PORT}`
+    );
+    return Promise.resolve();
+  };
+}