@volter/twin-hubspot 0.1.0

package/src/hubspot-mirror-ui.ts

@@ -0,0 +1,166 @@
+// HubSpot MIRROR UI — a HubSpot-CRM-like view served as a React/TSX app (bundled by Bun).
+//
+// WHY THIS PACK MIRRORS AT ALL (docs/contributing/adding-a-twin.md, "Does this vendor get a mirror?"): the
+// question is not "does HubSpot have a UI" but "when someone does this vendor's core job, do
+// they open a browser or write code?" A sales rep works a deal by DRAGGING IT ACROSS THE
+// PIPELINE BOARD and a support agent works a ticket in the ticket view — the CRM screen IS the
+// product, the way a board is Jira's product. So: mirror.
+//
+// ARCHETYPE A (API passthrough), the recipe's default and the strongest parity claim available:
+// non-asset requests fall through to the pack's OWN fetch adapter, and the browser client fetches
+// HubSpot's REAL API paths (`/crm/v3/objects/contacts`, …). There is exactly ONE code path, so
+// API↔UI parity cannot drift — it is not "kept in sync", it is structurally the same read.
+// PURE FRONTEND (R3): the mirror imports no handler and no twin internals — it MOUNTS the pack's
+// fetch adapter as its API backend and reads every byte of state back over the wire.
+import { readFile } from 'node:fs/promises';
+import { bundleClient, fileResponse } from '@volter/world-core';
+import { serveHttp } from '@volter/world-core';
+import { createHubspotTwinFetch } from './hubspot-server.ts';
+
+const CLIENT_ENTRY = () => new URL('../client/hubspot-mirror.tsx', import.meta.url).pathname;  // lazy: workerd rejects top-level relative URL from import.meta.url (bundled via pack index)
+const CLIENT_CSS = () => new URL('../client/hubspot-mirror.css', import.meta.url).pathname;  // lazy: workerd rejects top-level relative URL from import.meta.url (bundled via pack index)
+
+// ---------------------------------------------------------------------------
+// Pure, dependency-free render/format helpers (importable by the React client; Bun
+// tree-shakes the server-only exports out of the browser bundle). Keep free of any
+// @volter/world-core / Bun / handler usage.
+// ---------------------------------------------------------------------------
+
+/** One rendered CRM record, as the vendor's own API returns it (SimplePublicObject). */
+export type HubspotRow = { id: string; properties: Record<string, string | null>; createdAt?: string; updatedAt?: string; archived?: boolean };
+
+/** The four record sections the mirror shows, keyed by HubSpot's own object-type path segment. */
+export const MIRROR_SECTIONS = [
+  { key: 'contacts', label: 'Contacts', path: '/crm/v3/objects/contacts?limit=100&properties=email,firstname,lastname,phone,lifecyclestage' },
+  { key: 'companies', label: 'Companies', path: '/crm/v3/objects/companies?limit=100&properties=name,domain,city,industry' },
+  { key: 'deals', label: 'Deals', path: '/crm/v3/objects/deals?limit=100&properties=dealname,amount,dealstage,pipeline,closedate' },
+  { key: 'tickets', label: 'Tickets', path: '/crm/v3/objects/tickets?limit=100&properties=subject,content,hs_pipeline_stage,hs_ticket_priority' },
+] as const;
+export type MirrorSectionKey = (typeof MIRROR_SECTIONS)[number]['key'];
+
+/** The columns each section's table shows — HubSpot property names, in display order. */
+export const SECTION_COLUMNS: Record<MirrorSectionKey, { prop: string; label: string }[]> = {
+  contacts: [
+    { prop: 'firstname', label: 'First name' }, { prop: 'lastname', label: 'Last name' },
+    { prop: 'email', label: 'Email' }, { prop: 'phone', label: 'Phone' }, { prop: 'lifecyclestage', label: 'Lifecycle stage' },
+  ],
+  companies: [
+    { prop: 'name', label: 'Name' }, { prop: 'domain', label: 'Domain' },
+    { prop: 'city', label: 'City' }, { prop: 'industry', label: 'Industry' },
+  ],
+  deals: [
+    { prop: 'dealname', label: 'Deal name' }, { prop: 'amount', label: 'Amount' },
+    { prop: 'dealstage', label: 'Stage' }, { prop: 'closedate', label: 'Close date' },
+  ],
+  tickets: [
+    { prop: 'subject', label: 'Ticket name' }, { prop: 'hs_ticket_priority', label: 'Priority' },
+    { prop: 'hs_pipeline_stage', label: 'Status' },
+  ],
+};
+
+/** The property whose value titles a record in the list — HubSpot's own primary display property. */
+export const TITLE_PROPERTY: Record<MirrorSectionKey, string[]> = {
+  contacts: ['firstname', 'lastname', 'email'],
+  companies: ['name', 'domain'],
+  deals: ['dealname'],
+  tickets: ['subject'],
+};
+
+/** The label a row shows for a record — the vendor's primary display properties, joined. */
+export function recordTitle(section: MirrorSectionKey, properties: Record<string, string | null> | undefined): string {
+  const props = properties ?? {};
+  const parts = TITLE_PROPERTY[section].map((p) => props[p]).filter((v): v is string => typeof v === 'string' && v !== '');
+  return parts.length ? parts.join(' ') : '(no name)';
+}
+
+/** Status pill tone for a deal stage. Closed-won reads good, closed-lost bad, anything open warn. */
+export type PillTone = 'ok' | 'warn' | 'bad' | '';
+export function stageTone(dealstage: unknown): PillTone {
+  const s = String(dealstage ?? '').toLowerCase();
+  if (s === '') return '';
+  if (s === 'closedwon') return 'ok';
+  if (s === 'closedlost') return 'bad';
+  return 'warn';
+}
+
+/** Format a deal amount the way a CRM list does: `$1,250` / `—` when unset. */
+export function formatAmount(amount: unknown): string {
+  const n = Number(amount);
+  if (amount === null || amount === undefined || amount === '' || !Number.isFinite(n)) return '—';
+  return `$${n.toLocaleString('en-US', { maximumFractionDigits: 2 })}`;
+}
+
+/** Group deal rows by their `dealstage` property — the pipeline board's own projection. */
+export function groupByStage(rows: HubspotRow[]): { stage: string; rows: HubspotRow[] }[] {
+  const buckets = new Map<string, HubspotRow[]>();
+  for (const r of rows) {
+    const stage = String(r.properties?.dealstage ?? '') || 'unstaged';
+    const list = buckets.get(stage);
+    if (list) list.push(r); else buckets.set(stage, [r]);
+  }
+  return [...buckets.entries()].sort((a, b) => a[0].localeCompare(b[0])).map(([stage, list]) => ({ stage, rows: list }));
+}
+
+const APP_SHELL = `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<base href="/"><title>HubSpot CRM mirror (twin)</title><link rel="stylesheet" href="assets/styles.css"></head>
+<body><div id="root"></div><script type="module" src="assets/app.js"></script></body></html>`;
+
+let clientBundle: Promise<string> | null = null;
+/** Build the React/TSX CRM client to browser JS (Bun bundles TSX); cached at module scope, so a
+ *  pack running on its own does exactly ONE build. */
+export function buildHubspotMirrorClient(): Promise<string> {
+  if (!clientBundle) {
+    clientBundle = bundleClient(CLIENT_ENTRY())
+      .catch((error) => { clientBundle = null; throw error; });
+  }
+  return clientBundle;
+}
+
+/** Serve the HubSpot CRM mirror UI (React app) + its backing CRM REST API. */
+export async function createHubspotMirrorServer(options: { root?: string; port?: number }): Promise<{ port: number; url: string; stop: () => void }> {
+  const twin = createHubspotTwinFetch(options);
+  const server = await serveHttp({
+    // LOOPBACK-SPECIFIC bind: with the default wildcard hostname, `port: 0` can be handed a port
+    // some long-running app already LISTENS on at 127.0.0.1 (SO_REUSEADDR allows the overlapping
+    // non-identical bind), and the more specific loopback listener then shadows this server for
+    // every 127.0.0.1 fetch — the verify would talk to a STRANGER. Binding 127.0.0.1 makes the
+    // kernel allocate a port that is actually free on loopback.
+    hostname: '127.0.0.1',
+    port: options.port ?? 0,
+    idleTimeout: 60,
+    async fetch(request) {
+      const url = new URL(request.url);
+      if (request.method === 'GET' && url.pathname === '/assets/app.js') {
+        try { return new Response(await buildHubspotMirrorClient(), { headers: { 'content-type': 'text/javascript; charset=utf-8' } }); }
+        catch (error) { return new Response(String(error), { status: 500 }); }
+      }
+      if (request.method === 'GET' && url.pathname === '/assets/styles.css') {
+        return fileResponse(CLIENT_CSS(), { headers: { 'content-type': 'text/css; charset=utf-8' } });
+      }
+      if (request.method === 'GET' && (url.pathname === '/' || url.pathname === '')) {
+        return new Response(APP_SHELL, { headers: { 'content-type': 'text/html; charset=utf-8' } });
+      }
+      // Everything else → the twin's OWN FETCH ADAPTER (composition, R2/R3): the React client
+      // fetches HubSpot's real endpoints, and the adapter is the same closure
+      // `createHubspotTwinServer` serves, so there is exactly ONE serving code path — the world
+      // instant on every write (the kernel dedupes an action by content + millisecond, so a
+      // pinned stamp would swallow an A→B→A revert as `replayed`), the rate-limit response
+      // headers, an honorable `readOnly` and contained handler throws all come from it, and the
+      // mirror port cannot drift from the API port.
+      return twin(request);
+    },
+  });
+  const port = server.port ?? options.port ?? 0;
+  return { port, url: `http://127.0.0.1:${port}`, stop: () => server.stop(true) };
+}
+
+/** The app-shell HTML (pure, for tests). The CRM itself is the React client. */
+export function hubspotMirrorHtml(): string {
+  return APP_SHELL;
+}
+
+/** The mirror's stylesheet, for a host serving the shell's `assets/styles.css` itself (the hosted mirror mount). */
+export function hubspotMirrorStyles(): Promise<string> {
+  return readFile(CLIENT_CSS(), 'utf8');
+}

package/src/hubspot-oauth.tsx

@@ -0,0 +1,296 @@
+// HUBSPOT OAUTH — the install an app's "Connect HubSpot" starts (docs/contributing/architecture.md, "Screens": a hosted
+// flow). From HubSpot's OAuth guide (developers.hubspot.com/docs/api/oauth-quickstart-guide):
+//   - the app sends a person to https://app.hubspot.com/oauth/authorize with `client_id`, `scope` (space-separated),
+//     `redirect_uri`, and optionally `optional_scope` and `state`; its consent shows "the name of your app and a short
+//     description of the HubSpot API services it's requesting permission to access", and on approval HubSpot redirects
+//     to the redirect_uri "with a `code` query parameter";
+//   - the app exchanges the code at POST https://api.hubapi.com/oauth/v1/token with `grant_type=authorization_code`,
+//     client_id, client_secret, redirect_uri and code, and later refreshes with `grant_type=refresh_token`;
+//   - both answer `token_type`, `refresh_token`, `hub_id`, `scopes`, `access_token` and `expires_in` (1800) (HubSpot's
+//     changelog, "Additional details returned when generating OAuth access tokens");
+//   - GET /oauth/v1/access-tokens/{token} answers the token's metadata (token, user, hub_domain, scopes, hub_id,
+//     app_id, expires_in, user_id, token_type "access"), and a bad refresh token is `invalid_grant` with status
+//     BAD_REFRESH_TOKEN (the v1 OAuth tokens guide).
+// The consent is authored from @volter/world-ui's piece under HubSpot's skin; nothing of HubSpot's page is copied.
+//
+// AN APP AN ACCOUNT BUILT (screens/developer.tsx) is installed as HubSpot's install page describes
+// (https://developers.hubspot.com/docs/apps/developer-platform/build-apps/manage-apps-in-hubspot, "Install an OAuth
+// marketplace app"): the person is signed in (screens/session.tsx), the redirect URL is one the app registered, an
+// OAuth marketplace app installs outside test accounts only once its AUP is signed and at most 25 times before it is
+// listed, the person selects the account to install it in, reviews the scopes and clicks **Connect app**, and for an
+// app HubSpot has not verified confirms in a dialog ("type **I accept the risk**, and click **Connect**"). The code is
+// the account's; its exchange checks the app's client secret, installs the app in the account (the page's
+// "TOKEN_EXCHANGE: … At this point, the app is installed in the user's account"), and answers the account's `hub_id`;
+// every token it issues acts in that account (portal.ts) until it expires, the install is uninstalled or the account
+// is closed (tokenPortal).
+//
+// Where the documentation stops and the twin decides, for an app no account of the World built: the portal is the
+// World's own (hub 2953265, user twin@hubspot.local), so a World pointing an app at the twin with a client_id of its own
+// keeps working: any redirect_uri may start an install and the client_secret is not checked; the consent lists each scope by its name (the twin has no table of HubSpot's scope
+// descriptions); a code is redeemed once, within ten minutes, by the app it was issued to at the redirect it
+// named, and a bad code is `invalid_grant` with status BAD_AUTH_CODE; each refresh mints a new refresh token and the
+// earlier ones stay valid; another grant type, and the metadata of an unknown or expired token (401 in the API's error
+// envelope), are worded by the twin; a denial redirects with `error=access_denied` (RFC 6749 §4.1.2.1); the consent is
+// served only on HubSpot's app hosts (*.hubspot.com), the token endpoints on the API host; the rest of the API accepts
+// any bearer, as it did before (hubspot-server.ts), so a minted token is not required there.
+import { createHash } from 'node:crypto';
+import { applyTwinWrite, projectResources } from '@volter/world-core';
+import { Consent, CONSENT_CSS, flowPage, Portal, PORTAL_CSS } from '@volter/world-ui';
+import { accountOf, appByClientId, installOf, keep, signedIn, stored, type Row as AccountRow } from './accounts.ts';
+import { TWIN_HUB_ID, type PortalScope } from './portal.ts';
+
+export { TWIN_HUB_ID };
+const SERVICE = 'hubspot';
+const TWIN_USER = { id: 1, email: 'twin@hubspot.local', domain: 'twin.hubspot.local' };
+const CODE_TTL_MS = 10 * 60_000;
+const EXPIRES_IN = 1800;
+const INSTALL_CAP = 25;
+const ACCEPT_RISK = 'I accept the risk';
+
+const SKIN = `
+body { background: #ffffff; color: #33475b; font-family: "Lexend Deca", Helvetica, Arial, sans-serif; }
+.consent-badge { background: #f5f8fa; border: 1px solid #cbd6e2; color: #33475b; }
+.consent-vendor { background: #ff7a59; }
+.consent-link, .consent-box, .consent-actions { border-color: #cbd6e2; }
+.consent-who small, .consent-permission summary small, .consent-note { color: #516f90; }
+.consent-deny { background: #ffffff; border-color: #cbd6e2; color: #33475b; }
+.consent-allow, .portal-primary { background: #ff7a59; border-color: #ff7a59; color: #ffffff; }
+.portal-side { background: #f5f8fa; border-right: 1px solid #cbd6e2; }
+.portal-notice { background: #fef8f0; border: 1px solid #f5c26b; }
+`;
+
+type Row = Record<string, unknown>;
+const hex = (s: string): string => createHash('sha256').update(s).digest('hex');
+const rows = (type: string, root?: string): Row[] => (projectResources(SERVICE, root) as unknown as Row[]).filter((r) => r.type === type);
+async function write(type: string, id: string, fields: Row, root: string | undefined, at: string, actor = TWIN_USER.email): Promise<void> {
+  await applyTwinWrite(SERVICE, { operation: `oauth.${type}`, subjectType: type, subjectId: id, fields, occurredAt: at, actor: { kind: 'human', id: actor } }, root);
+}
+
+async function fieldsOf(request: Request): Promise<Record<string, string>> {
+  const out: Record<string, string> = Object.fromEntries(new URL(request.url).searchParams);
+  if (request.method !== 'POST') return out;
+  const text = await request.text();
+  if ((request.headers.get('content-type') ?? '').includes('json')) {
+    try { for (const [k, v] of Object.entries(JSON.parse(text) as Row)) if (v != null) out[k] = String(v); return out; } catch { /* read as a form */ }
+  }
+  return { ...out, ...Object.fromEntries(new URLSearchParams(text)) };
+}
+
+const scopesOf = (raw: string | undefined): string[] => [...new Set((raw ?? '').split(/[\s,+]+/).filter(Boolean))];
+const parses = (u: string | undefined): u is string => { try { return !!u && !!new URL(u); } catch { return false; } };
+const errorPage = (status: number, message: string): Response =>
+  flowPage({ title: 'HubSpot', status, css: [CONSENT_CSS, SKIN], body: <main className="consent"><h1 className="consent-heading">{message}</h1></main> });
+function redirect(to: string, params: Record<string, string | undefined>): Response {
+  const url = new URL(to);
+  for (const [k, v] of Object.entries(params)) if (v !== undefined) url.searchParams.set(k, v);
+  return new Response(null, { status: 302, headers: { location: url.toString() } });
+}
+const tokenError = (status: string, message: string): Response =>
+  Response.json({ error: 'invalid_grant', error_description: message, status, message }, { status: 400 });
+
+/** The fields the consent carries from the install URL to its answer. */
+function carried(p: Record<string, string>): Record<string, string> {
+  return { client_id: p.client_id!, redirect_uri: p.redirect_uri!, scope: scopesOf(p.scope).join(' '), ...(p.optional_scope ? { optional_scope: p.optional_scope } : {}), ...(p.state !== undefined ? { state: p.state } : {}) };
+}
+
+// ── an app no account of the World built: the World's own portal ────────────────────────────
+async function consent(request: Request): Promise<Response> {
+  const p = await fieldsOf(request);
+  if (!p.client_id) return errorPage(400, 'Missing client_id');
+  if (!parses(p.redirect_uri)) return errorPage(400, 'Missing or invalid redirect_uri');
+  const scopes = [...scopesOf(p.scope), ...scopesOf(p.optional_scope)];
+  if (!scopes.length) return errorPage(400, 'Missing scope');
+  return flowPage({
+    title: `Connect ${p.client_id} to HubSpot | HubSpot`,
+    css: [CONSENT_CSS, SKIN],
+    body: (
+      <Consent
+        heading={`Connect ${p.client_id} to your HubSpot account`}
+        app={{ name: p.client_id }}
+        request={`${TWIN_USER.domain} · Hub ID ${TWIN_HUB_ID}`}
+        permissions={scopes.map((s) => ({ title: s, detail: 'Requested scope' }))}
+        action="/oauth/authorize"
+        fields={carried(p)}
+        deny={{ name: 'answer', value: 'cancel', label: 'Cancel' }}
+        allow={{ name: 'answer', value: 'allow', label: 'Connect app' }}
+        note={`You will be sent to ${new URL(p.redirect_uri).origin}`}
+      />
+    ),
+  });
+}
+
+async function answer(request: Request, root: string | undefined, at: string): Promise<Response> {
+  const p = await fieldsOf(request);
+  if (!p.client_id || !parses(p.redirect_uri)) return errorPage(400, 'Missing client_id or redirect_uri');
+  if (p.answer !== 'allow') return redirect(p.redirect_uri, { error: 'access_denied', state: p.state });
+  const scopes = [...scopesOf(p.scope), ...scopesOf(p.optional_scope)];
+  const code = await mintCode(p.client_id, p.redirect_uri, scopes, { hubId: TWIN_HUB_ID }, root, at);
+  return redirect(p.redirect_uri, { code, state: p.state });
+}
+
+async function mintCode(clientId: string, redirectUri: string, scopes: string[], extra: Row, root: string | undefined, at: string, actor?: string): Promise<string> {
+  const n = rows('oauth_code', root).length + 1;
+  const code = `na1-${hex(`hubspotcode:${clientId}:${at}:${n}`).slice(0, 32)}`;
+  await write('oauth_code', code, { code, client_id: clientId, redirect_uri: redirectUri, scopes, created_at: at, used: false, ...extra }, root, at, actor);
+  return code;
+}
+
+// ── an app an account of the World built ───────────────────────────────────────────────────
+/** Why the app cannot be installed from this URL, or undefined. */
+function refusalFor(app: AccountRow, p: Record<string, string>, root?: string): string | undefined {
+  if (!(app.redirectUrls as string[]).includes(p.redirect_uri ?? '')) return 'The redirect URL is not one this app allows.';
+  const scopes = scopesOf(p.scope);
+  const missing = (app.requiredScopes as string[]).filter((s) => !scopes.includes(s));
+  if (missing.length) return `The install URL is missing required scopes: ${missing.join(', ')}.`;
+  if (app.distribution === 'marketplace' && !app.aup_signed_at) return 'This app can only be installed in developer test accounts.';
+  if (app.distribution === 'marketplace' && stored('_install', root).filter((i) => i.appId === app.appId && !i.uninstalled_at).length >= INSTALL_CAP) return 'This app has reached its install limit.';
+  return undefined;
+}
+
+function appConsent(app: AccountRow, person: AccountRow, p: Record<string, string>, root?: string): Response {
+  const account = accountOf(Number(person.hubId), root)!;
+  return flowPage({
+    title: `Connect ${String(app.name)} | HubSpot`,
+    css: [CONSENT_CSS, SKIN],
+    body: (
+      <Consent
+        heading={`Connect ${String(app.name)} to HubSpot`}
+        app={{ name: String(app.name) }}
+        request={`${String(person.email)} · This app has not been verified by HubSpot`}
+        permissions={['oauth', ...(app.requiredScopes as string[])].filter((s, i, all) => all.indexOf(s) === i).map((s) => ({ title: s, detail: 'Required' }))}
+        action="/oauth/authorize"
+        fields={carried(p)}
+        choices={[{ id: 'account', label: 'Select an account', value: String(account.hubId), options: [{ value: String(account.hubId), label: `${String(account.name)} (${String(account.hubId)})` }] }]}
+        deny={{ name: 'answer', value: 'cancel', label: 'Cancel' }}
+        allow={{ name: 'answer', value: 'allow', label: 'Connect app' }}
+        note={`You will be sent to ${new URL(p.redirect_uri!).origin}`}
+      />
+    ),
+  });
+}
+
+/** The dialog an unverified app's install asks a person to confirm in. */
+function acceptRisk(app: AccountRow, p: Record<string, string>, notice?: string): Response {
+  const fields = { ...carried(p), account: p.account ?? '', answer: 'allow' };
+  return flowPage({
+    title: `Connect ${String(app.name)} | HubSpot`,
+    css: [PORTAL_CSS, SKIN],
+    body: (
+      <Portal merchant={`Connect ${String(app.name)}`} notice={notice ?? 'This app has not been verified by HubSpot. Double-check all details of the app to confirm that it matches what you expect.'}
+        sections={[{ heading: 'App details', items: [{ title: String(app.name), detail: String(app.description ?? ''), note: `Requests: ${['oauth', ...(app.requiredScopes as string[])].join(', ')}` }] }]}
+        forms={[{ heading: 'Connect unverified app', action: '/oauth/authorize', fields: [
+          ...Object.entries(fields).map(([id, value]) => ({ id, label: '', type: 'hidden', value })),
+          { id: 'confirm', label: `Type ${ACCEPT_RISK}` },
+        ], submit: { label: 'Connect' } }]} />
+    ),
+  });
+}
+
+async function appAnswer(app: AccountRow, request: Request, p: Record<string, string>, root: string | undefined, at: string): Promise<Response> {
+  if (p.answer !== 'allow') return redirect(p.redirect_uri!, { error: 'access_denied', state: p.state });
+  const person = signedIn(request, root);
+  if (!person) return errorPage(401, 'Log in to HubSpot to connect this app.');
+  const hubId = Number(p.account);
+  if (hubId !== Number(person.hubId) || accountOf(hubId, root)?.closed_at) return errorPage(403, "You don't have access to this account.");
+  if (p.confirm === undefined) return acceptRisk(app, p);
+  if (p.confirm !== ACCEPT_RISK) return acceptRisk(app, p, `Type ${ACCEPT_RISK} to connect this app.`);
+  const code = await mintCode(String(app.client_id), p.redirect_uri!, ['oauth', ...(app.requiredScopes as string[])].filter((s, i, all) => all.indexOf(s) === i), { hubId, appId: app.appId, person: person.email }, root, at, String(person.email));
+  return redirect(p.redirect_uri!, { code, state: p.state });
+}
+
+async function authorize(request: Request, root: string | undefined, at: string): Promise<Response> {
+  const p = await fieldsOf(request);
+  const app = p.client_id ? appByClientId(p.client_id, root) : undefined;
+  if (!app) return request.method === 'GET' ? consent(new Request(request.url)) : answer(new Request(request.url, { method: 'POST', headers: { 'content-type': 'application/x-www-form-urlencoded' }, body: new URLSearchParams(p).toString() }), root, at);
+  if (!parses(p.redirect_uri)) return errorPage(400, 'Missing or invalid redirect_uri');
+  const refused = refusalFor(app, p, root);
+  if (refused) return errorPage(400, refused);
+  if (request.method === 'POST') return appAnswer(app, request, p, root, at);
+  const person = signedIn(request, root);
+  const url = new URL(request.url);
+  if (!person) return new Response(null, { status: 302, headers: { location: `/login?loginRedirectUrl=${encodeURIComponent(url.pathname + url.search)}` } });
+  return appConsent(app, person, p, root);
+}
+
+// ── the token endpoints ────────────────────────────────────────────────────────────────────
+async function issue(clientId: string, scopes: string[], seed: string, extra: Row, root: string | undefined, at: string): Promise<Response> {
+  const access = `CN${hex(`hubspotaccess:${seed}`).slice(0, 48)}`;
+  const refresh = `na1-${hex(`hubspotrefresh:${seed}`).slice(0, 8)}-${hex(`hubspotrefresh2:${seed}`).slice(0, 28)}`;
+  const hubId = Number(extra.hubId ?? TWIN_HUB_ID);
+  await write('oauth_token', access, { access_token: access, refresh_token: refresh, client_id: clientId, scopes, issued_at: at, ...extra }, root, at);
+  return Response.json({ token_type: 'bearer', refresh_token: refresh, hub_id: hubId, scopes, access_token: access, expires_in: EXPIRES_IN });
+}
+
+async function token(request: Request, root: string | undefined, at: string): Promise<Response> {
+  const p = await fieldsOf(request);
+  const app = p.client_id ? appByClientId(p.client_id, root) : undefined;
+  // a built app's client secret is checked; where the documentation stops, HubSpot's words for a wrong one are the twin's
+  if (app && p.client_secret !== app.client_secret) return Response.json({ error: 'invalid_client', error_description: 'client_id or client_secret is invalid', status: 'BAD_CLIENT_ID', message: 'client_id or client_secret is invalid' }, { status: 400 });
+  if (p.grant_type === 'authorization_code') {
+    const code = rows('oauth_code', root).find((r) => r.code === p.code);
+    if (!code || code.used === true || code.client_id !== p.client_id || code.redirect_uri !== p.redirect_uri || Date.parse(at) - Date.parse(String(code.created_at)) > CODE_TTL_MS) {
+      return tokenError('BAD_AUTH_CODE', 'auth code is invalid, expired or already used');
+    }
+    await write('oauth_code', String(code.code), { used: true }, root, at);
+    const extra: Row = { hubId: code.hubId ?? TWIN_HUB_ID, ...(app ? { appId: app.appId } : {}) };
+    if (app) {
+      const hubId = Number(code.hubId);
+      const live = installOf(Number(app.appId), hubId, root);
+      if (!live) await keep('_install', `install:${String(app.appId)}:${hubId}:${at}`, { appId: app.appId, hubId, installed_by: code.person, scopes: code.scopes, installed_at: at, uninstalled_at: null }, root, at, String(code.person));
+    }
+    return issue(String(p.client_id), (code.scopes as string[]) ?? [], `${code.code}`, extra, root, at);
+  }
+  if (p.grant_type === 'refresh_token') {
+    const held = rows('oauth_token', root).filter((r) => r.refresh_token === p.refresh_token && r.client_id === p.client_id);
+    const first = held[0];
+    if (!first || (app && !installOf(Number(app.appId), Number(first.hubId), root))) return tokenError('BAD_REFRESH_TOKEN', 'refresh token is invalid, expired or revoked');
+    return issue(String(p.client_id), (first.scopes as string[]) ?? [], `${p.refresh_token}:${at}:${held.length}`, { hubId: first.hubId ?? TWIN_HUB_ID, ...(app ? { appId: app.appId } : {}) }, root, at);
+  }
+  return Response.json({ error: 'unsupported_grant_type', error_description: 'grant_type must be authorization_code or refresh_token', status: 'BAD_GRANT_TYPE', message: 'grant_type must be authorization_code or refresh_token' }, { status: 400 });
+}
+
+function tokenInfo(access: string, root: string | undefined, at: string): Response {
+  const t = rows('oauth_token', root).find((r) => r.access_token === access);
+  const expiresIn = t ? EXPIRES_IN - Math.floor((Date.parse(at) - Date.parse(String(t.issued_at))) / 1000) : -1;
+  if (!t || expiresIn <= 0) return Response.json({ status: 'error', message: 'The OAuth token used to make this call expired', category: 'EXPIRED_AUTHENTICATION' }, { status: 401 });
+  const hubId = Number(t.hubId ?? TWIN_HUB_ID);
+  return Response.json({ token: access, user: TWIN_USER.email, hub_domain: TWIN_USER.domain, scopes: t.scopes, hub_id: hubId, app_id: t.appId ?? Number.parseInt(hex(String(t.client_id)).slice(0, 6), 16), expires_in: expiresIn, user_id: TWIN_USER.id, token_type: 'access' });
+}
+
+/** The account a CRM request's bearer acts in: an access token the install issued (refused once expired, its app
+ *  uninstalled or its account closed), a static app's token, or, for a credential the twin never issued, undefined (the
+ *  World's own account). Where the documentation stops: HubSpot's refusal words for a revoked token are the twin's. */
+export function tokenPortal(authorization: string | null, root: string | undefined, at: string): PortalScope | Response | undefined {
+  const bearer = /^Bearer\s+(.+)$/i.exec(authorization ?? '')?.[1]?.trim();
+  if (!bearer) return undefined;
+  const refuse = (category: string, message: string): Response => Response.json({ status: 'error', message, correlationId: hex(`${category}:${bearer}:${at}`).replace(/^(.{8})(.{4})(.{4})(.{4})(.{12}).*$/, '$1-$2-$3-$4-$5'), category }, { status: 401 });
+  const staticInstall = stored('_install', root).find((i) => i.static_token === bearer);
+  if (staticInstall) {
+    if (staticInstall.uninstalled_at || accountOf(Number(staticInstall.hubId), root)?.closed_at) return refuse('INVALID_AUTHENTICATION', 'Authentication credentials not found. This API supports OAuth 2.0 authentication.');
+    return { hub: Number(staticInstall.hubId), source: 'INTEGRATION', sourceId: String(staticInstall.appId) };
+  }
+  const t = rows('oauth_token', root).find((r) => r.access_token === bearer);
+  if (!t || t.appId === undefined) return undefined;
+  const hubId = Number(t.hubId);
+  const ago = Math.floor((Date.parse(at) - Date.parse(String(t.issued_at))) / 1000) - EXPIRES_IN;
+  if (ago >= 0) return refuse('EXPIRED_AUTHENTICATION', `The OAuth token used to make this call expired ${ago} second(s) ago.`);
+  if (!installOf(Number(t.appId), hubId, root) || accountOf(hubId, root)?.closed_at) return refuse('INVALID_AUTHENTICATION', 'Authentication credentials not found. This API supports OAuth 2.0 authentication.');
+  return { hub: hubId, source: 'INTEGRATION', sourceId: String(t.appId) };
+}
+
+/** app.hubspot.com's consent and api.hubapi.com's OAuth v1 endpoints, or undefined for any other request. */
+export async function hubspotOAuth(request: Request, root: string | undefined, now: () => string): Promise<Response | undefined> {
+  const url = new URL(request.url);
+  const path = url.pathname.replace(/\/+$/, '');
+  // the vendor host a redirected request names (the injector, a hosted World), else its Host, else the URL's
+  const host = (request.headers.get('x-volter-twin-original-host') ?? request.headers.get('host') ?? url.host).split(':')[0]!.toLowerCase();
+  const appHost = host === 'hubspot.com' || host.endsWith('.hubspot.com') || url.hostname.endsWith('.hubspot.com');
+  if (path === '/oauth/authorize' && appHost) {
+    if (request.method === 'GET' || request.method === 'POST') return authorize(request, root, now());
+    return undefined;
+  }
+  if (path === '/oauth/v1/token' && request.method === 'POST') return token(request, root, now());
+  const info = /^\/oauth\/v1\/access-tokens\/([^/]+)$/.exec(path);
+  if (info && request.method === 'GET') return tokenInfo(decodeURIComponent(info[1]!), root, now());
+  return undefined;
+}

package/src/hubspot-server.ts

@@ -0,0 +1,115 @@
+// HubSpot twin HTTP server — the pack's wire as the derived dispatch over HubSpot's nine published documents
+// (docs/contributing/architecture.md, "Protocol 3"), so an application calling HubSpot with raw fetch (Dub) or an
+// UNMODIFIED `@hubspot/api-client` (pointed here with its own `basePath` option, or routed by the world injector's
+// api.hubapi.com interception) works against it. Writable by default; pass readOnly to reject writes (R4). The CRM API
+// accepts any bearer: a token the install minted is not required there.
+//
+// FETCH-FIRST (runtime contract R12b): the serve path is the plain fetch below, the server one line of Bun.serve around
+// the same closure. The 204-with-no-body case is the kernel adapter's own null-body rule — `handleHubspotTwinRequest`
+// returns `{ status: 204, body: null, headers }`, served as a genuinely empty response carrying those headers.
+import { createDerivedFetch, createTwinFetchFromHandler, serveHttp, statefulTwinManifest, worldNow, type DerivedFetch, type DerivedSurface } from '@volter/world-core';
+import surface from './generated/surface.gen.json' with { type: 'json' };
+import { hubspotHandlers } from './semantics/crm.ts';
+import { handleHubspotTwinRequest, hubspotUnknownRequest, specObjectPath } from './hubspot-twin.ts';
+import { hubspotOAuth, tokenPortal } from './hubspot-oauth.tsx';
+import { signUpDoor } from './accounts.ts';
+import { inPortal } from './portal.ts';
+import { deliveriesDoor } from './webhooks.ts';
+import { accountPages } from './screens/account.tsx';
+import { crmPages } from './screens/crm.tsx';
+import { developerPages, uploadDoor } from './screens/developer.tsx';
+import { FORMS_HOST, formPages, formSubmission } from './screens/forms.tsx';
+import { signIn } from './screens/session.tsx';
+
+/** Options every HubSpot-twin HTTP surface needs, independent of who owns the socket. */
+export interface HubspotTwinFetchOptions {
+  root?: string;
+  readOnly?: boolean;
+}
+
+/**
+ * The pack's wire: the twin's discovery door (`GET /twin`) and HubSpot's OAuth consent (app.hubspot.com's
+ * /oauth/authorize, a hosted flow: hubspot-oauth.tsx) in front, then the derived dispatch over the nine documents'
+ * union. A /crm/v3/objects/ path naming its object type in the spelling the spec's paths do not use (`deals` for the
+ * Deals document's `0-3`, `0-1` for `contacts`) is dispatched as the spelling they use (`specObjectPath`). The
+ * operations the twin serves go to their handlers (semantics/crm.ts); every other one, and a path no document has,
+ * is the gap.
+ */
+export function createHubspotTwinFetch(options: HubspotTwinFetchOptions): DerivedFetch {
+  const answer = createTwinFetchFromHandler(handleHubspotTwinRequest, {
+    ...options,
+    manifest: statefulTwinManifest({
+      vendor: 'hubspot',
+      twinOf: 'the HubSpot CRM v3/v4 API and its OAuth v1 token endpoints',
+      stores: 'CRM records (contacts, companies, deals, tickets), their properties and property groups, pipelines and stages, owners, and associations; OAuth codes and tokens',
+    }),
+  });
+  // a read-only twin installs nothing: its token endpoints answer as the request handler answers any write
+  const oauth = async (request: Request): Promise<Response> =>
+    (options.readOnly ? undefined : await hubspotOAuth(request, options.root, worldNow)) ?? answer(request);
+  const derived = createDerivedFetch({
+    surface: surface as DerivedSurface,
+    handlers: hubspotHandlers(answer, oauth),
+    gap: (request) => {
+      const url = new URL(request.url);
+      const refused = hubspotUnknownRequest(request.method, url.pathname);
+      return Response.json(refused.body, { status: refused.status, headers: refused.headers });
+    },
+  });
+  return Object.assign(async function hubspotTwinFetch(request: Request): Promise<Response> {
+    try {
+      const url = new URL(request.url);
+      const bare = url.pathname.replace(/\/+$/, '') || '/';
+      if (request.method === 'GET' && bare === '/twin') return await answer(request);
+      const root = options.root;
+      const at = worldNow();
+      // the World's doors, on every host (accounts.ts, screens/developer.tsx, webhooks.ts)
+      if (request.method === 'GET' && bare === '/_twin/deliveries') return deliveriesDoor(request, root);
+      if (!options.readOnly && request.method === 'POST') {
+        const user = /^\/_twin\/users\/([^/]+)\/password$/.exec(bare);
+        if (user) return await signUpDoor(decodeURIComponent(user[1]!).toLowerCase(), request, root, at);
+        const project = /^\/_twin\/accounts\/(\d+)\/projects$/.exec(bare);
+        if (project) return await uploadDoor(Number(project[1]), request, root, at);
+      }
+      // the vendor host a redirected request names (the injector, a hosted World), else its own
+      const host = (request.headers.get('x-volter-twin-original-host') ?? url.host).split(':')[0]!.toLowerCase();
+      if (host === FORMS_HOST) return (await formSubmission(request, root, at)) ?? notFoundPage();
+      if (host === 'app.hubspot.com') {
+        if (options.readOnly && request.method !== 'GET') return notFoundPage();
+        if (bare === '/login') return await signIn(request, root, at);
+        if (bare === '/oauth/authorize') return (await hubspotOAuth(request, root, worldNow)) ?? notFoundPage();
+        return (await accountPages(request, root, at)) ?? (await developerPages(request, root, at)) ?? (await crmPages(request, root, at)) ?? (await formPages(request, root, at)) ?? notFoundPage();
+      }
+      // the consent on another hubspot.com host a World routes here (hubspotOAuth answers only on HubSpot's app hosts)
+      if (!options.readOnly && bare === '/oauth/authorize') {
+        const consent = await hubspotOAuth(request, root, worldNow);
+        if (consent) return consent;
+      }
+      const path = specObjectPath(url.pathname);
+      const routed = path === url.pathname ? request : new Request(Object.assign(url, { pathname: path }), request);
+      // the account the bearer acts in (portal.ts): refused if the twin issued it and it no longer works
+      const scope = tokenPortal(request.headers.get('authorization'), root, at);
+      if (scope instanceof Response) return scope;
+      return scope ? await inPortal(scope, () => derived(routed)) : await derived(routed);
+    } catch (error) {
+      // Never let an exception escape the fetch callback (§8): answer with a vendor-shaped 500
+      // so an in-process fidelity test sees a response, not a hang.
+      return new Response(JSON.stringify({ status: 'error', message: `internal twin error: ${String(error)}`, category: 'INTERNAL_ERROR', correlationId: '00000000-0000-0000-0000-000000000000' }), {
+        status: 500, headers: { 'content-type': 'application/json' },
+      });
+    }
+  }, { owners: () => derived.owners() });
+}
+
+const notFoundPage = (): Response => new Response('Not Found', { status: 404, headers: { 'content-type': 'text/plain' } });
+
+export async function createHubspotTwinServer(options: { root?: string; port?: number; readOnly?: boolean }): Promise<{ port: number; url: string; stop: () => void }> {
+  const server = await serveHttp({
+    hostname: '127.0.0.1',
+    port: options.port ?? 0,
+    idleTimeout: 60,
+    fetch: createHubspotTwinFetch(options),
+  });
+  const port = server.port ?? options.port ?? 0;
+  return { port, url: `http://127.0.0.1:${port}`, stop: () => server.stop(true) };
+}