@volter/twin-twilio 0.1.0

package/src/twilio-connector.ts

@@ -0,0 +1,162 @@
+// Twilio CONNECTOR — the live-vendor pull path that gives the Twilio twin the "git for SaaS"
+// pull lifecycle over an INJECTED client (the auth boundary).
+//
+// PULL (real -> twin) is LIST-DRIVEN for Messages (grounded — the real Twilio REST API has a
+// genuine `GET .../Messages.json` list endpoint, unlike fal's handle-only queue surface), so
+// `syncTwilioFromReal` calls `client.messages.list()` directly, with no caller-supplied handles.
+//
+// VERIFICATIONS ARE NOT PULLED YET (`twilio.connector.pull_verifications`, todo — see
+// pull-audit.json's grounded gap citation). This is a genuine, disclosed scope decision, not an
+// oversight: Twilio's real Verify v2 API has NO bulk "list every verification across a service"
+// endpoint (grounded — the fetched twilio_verify_v2.json OpenAPI document exposes only
+// POST .../Verifications (create), GET/POST .../Verifications/{Sid} (fetch/update), and
+// POST .../VerificationCheck — never a `GET .../Verifications` collection route), so a connector
+// would need caller-supplied handles (mirroring fal's `pullFalRequests`) to pull verifications at
+// all. `mapVerification` (a PURE mapper, below) is written now so that future handle-driven pull
+// entry point has a ready shape-mapper, but nothing calls it yet — kept honest as `todo` rather
+// than silently wired into a `sync*` entrypoint the real vendor doesn't support today.
+//
+// The vendor I/O is an INJECTED client interface (`TwilioLikeClient`): a fake in tests, the real
+// `twilio` SDK's own `messages` namespace in prod (`client.messages.list()` on a real
+// `twilio(accountSid, authToken)` instance is structurally assignable). The pack imports NO SDK
+// and holds NO key.
+import { syncPull } from '@volter/world-core';
+import type { SyncResource } from '@volter/world-core';
+//
+// ── The client-side RATE BUDGET is not optional here ────────────────────────────────────────
+// Twilio documents the CONCEPT of REST API concurrency (a Twilio-Concurrent-Requests header, error
+// 20429) without ever publishing the number, and GET /Messages has no documented rate at all — a
+// vendor that 429s without a published figure is exactly the case a client-side ceiling exists for.
+// Every entrypoint below GUARDS the injected client before touching it (`guardTwilioClient`, which is
+// idempotent — a caller who already wrapped is not double-charged, a caller who forgot is protected
+// anyway); there is deliberately no option that turns the budget off. See twilio-budget.ts.
+import { twilioBudgetOf, guardTwilioClient, type TwilioBudgetedOptions } from './twilio-budget.ts';
+
+const SERVICE = 'twilio';
+
+export type { TwilioBudgetedOptions };
+
+export type TwilioRealMessage = {
+  sid: string;
+  to: string;
+  from: string;
+  body: string;
+  status: string;
+  direction?: string;
+  numSegments?: string;
+  numMedia?: string;
+  dateCreated?: string | null;
+  dateSent?: string | null;
+  errorCode?: number | null;
+  errorMessage?: string | null;
+  accountSid?: string | null;
+};
+
+export type TwilioRealVerification = {
+  sid: string;
+  serviceSid: string;
+  to: string;
+  channel: string;
+  status: string;
+  valid: boolean;
+  dateCreated?: string | null;
+  dateUpdated?: string | null;
+};
+
+// The injected client exposes the minimal subset the connector calls; a real `twilio` client
+// instance's own `.messages.list()` method is structurally assignable (same `{sid,to,from,body,
+// status,direction,...}` instance shape the real SDK's `MessageInstance` returns).
+export interface TwilioLikeClient {
+  messages?: {
+    list: (opts?: { limit?: number }) => Promise<TwilioRealMessage[]>;
+  };
+}
+
+function kid(type: string, id: string): string {
+  return `${type}:${id}`;
+}
+
+/** Pure mapper (real Message -> SyncResource) — never touches a client, so the mutation-test
+ *  connector-seam sweep (which sabotages every export matching the sync-or-push-or-pull-or-
+ *  fullSync naming convention) leaves this real, per the pack convention (replicate-connector.ts's
+ *  `mapModel` / fal-connector.ts's `mapQueueRequest`). */
+export function mapMessage(m: TwilioRealMessage): SyncResource {
+  return {
+    type: 'message',
+    id: kid('message', m.sid),
+    fields: {
+      account_sid: m.accountSid ?? null,
+      api_version: '2010-04-01',
+      body: m.body,
+      to: m.to,
+      from: m.from,
+      direction: m.direction ?? 'outbound-api',
+      status: m.status,
+      num_segments: m.numSegments ?? '1',
+      num_media: m.numMedia ?? '0',
+      messaging_service_sid: null,
+      date_created: m.dateCreated ?? null,
+      date_updated: m.dateCreated ?? null,
+      date_sent: m.dateSent ?? null,
+      error_code: m.errorCode ?? null,
+      error_message: m.errorMessage ?? null,
+      price: null,
+      price_unit: null,
+      poll_count: 0,
+    },
+  };
+}
+
+/** Pure mapper (real Verification -> SyncResource). Not wired into `syncTwilioFromReal` today —
+ *  see header (`twilio.connector.pull_verifications` is `todo`; Verify v2 has no list-all
+ *  endpoint to pull from without caller-supplied handles). */
+export function mapVerification(v: TwilioRealVerification): SyncResource {
+  return {
+    type: 'verification',
+    id: kid('verification', v.sid),
+    fields: {
+      service_sid: v.serviceSid,
+      account_sid: null,
+      to: v.to,
+      channel: v.channel,
+      status: v.status,
+      valid: v.valid,
+      lookup: {},
+      amount: null,
+      payee: null,
+      send_code_attempts: [],
+      sna: null,
+      date_created: v.dateCreated ?? null,
+      date_updated: v.dateUpdated ?? null,
+      _lookup_key: `${v.serviceSid}::${v.to}`,
+      _expected_code: null, // a pulled (real) verification has no twin-derivable expected code
+    },
+  };
+}
+
+/** Pull real Messages via the injected client's `messages.list()` (list-driven — a genuine
+ *  Twilio REST list endpoint, unlike fal's handle-only queue). An absent `client.messages`
+ *  observes nothing. */
+export async function pullTwilioMessages(rawClient: TwilioLikeClient, opts: TwilioBudgetedOptions = {}): Promise<SyncResource[]> {
+  const client = guardTwilioClient(rawClient, opts);
+  if (!client.messages) return [];
+  const list = await client.messages.list();
+  return list.map(mapMessage);
+}
+
+/**
+ * D7 entry point: pull the CURRENT real Messages list and fold it into the twin via ONE
+ * `syncPull` (shadow-diff dedup). Returns `{observed, deltasAppended}` — a re-pull of identical
+ * state appends ZERO deltas.
+ */
+export async function syncTwilioFromReal(
+  rawClient: TwilioLikeClient,
+  opts: { root?: string; occurredAt?: string } & TwilioBudgetedOptions = {},
+): Promise<{ observed: number; deltasAppended: number }> {
+  // Guard ONCE here and hand the guarded client down, so the list pull cannot run unbudgeted.
+  const client = guardTwilioClient(rawClient, twilioBudgetOf(opts));
+  const occurredAt = opts.occurredAt ?? new Date().toISOString();
+  const resources = await pullTwilioMessages(client);
+  const result = syncPull({ service: SERVICE, resources, occurredAt, ...(opts.root !== undefined ? { root: opts.root } : {}) });
+  return { observed: result.observed, deltasAppended: result.deltasAppended };
+}

package/src/twilio-credentials.ts

@@ -0,0 +1,171 @@
+// The Twilio twin's ACCOUNT CREDENTIAL — the `AccountSid` / `AuthToken` pair this world answers
+// for — as twin STATE, never a function of the world's filesystem path.
+//
+// WHY THIS FILE EXISTS. The pair used to be `deriveTwilioAuthToken(root)` /
+// `deriveTwilioAccountSid(root)` — `sha256('twilio-twin-auth-token:' + root)` and
+// `'AC' + sha256('twilio-twin-account-sid:' + root).slice(0,32)`: the world's DIRECTORY was the
+// credential. Two byte-identical worlds in different directories then signed webhooks with
+// different keys and served different `auth_token`s from `GET Accounts/{Sid}.json`; a world COPIED
+// to another directory silently rotated its AuthToken out from under every signature a consumer
+// had already verified (R4 says snapshot/fork IS a copy of the root); an addressed namespace (R7b)
+// has no local directory at all; and anyone who knew where a world sat could compute its AuthToken
+// — the one value Twilio's whole webhook-signature scheme rests on. That is environment
+// masquerading as state. The path now never enters the AuthToken, the AccountSid, a signature, a
+// served byte or a stored byte.
+//
+// THE MODEL (the behavioral contract (docs/contributing/adding-a-twin.md, "Keep the three kinds of credential apart"), in substance: "FAKE vendor creds an app presents are twin STATE
+// — validated against the namespace, seeded via the wire or import"). A root's pair is established
+// EXACTLY ONCE and persisted as the pack's declared `signing_key` resource — the declaration that
+// was previously a name with nothing behind it, and Twilio's AuthToken *is* literally the webhook
+// signing key, so the type is the honest one. It is folded through the kernel action log, so it
+// rides snapshots/hydrate/flush like every other fact this twin holds, no `node:fs` touches the
+// serve path, and two serves on one root agree across a process restart. Two ways in:
+//   • SEEDED VIA THE WIRE — the first request to reach a virgin world carries Twilio's own
+//     `Authorization: Basic base64(AccountSid:AuthToken)`, and that pair becomes the world's. An
+//     app already configured with a SID/token therefore finds a twin that agrees with it, and
+//     `GET Accounts/{Sid}.json` hands back the app's own AuthToken rather than a stranger's.
+//   • MINTED WITH REAL ENTROPY — `twilioCredentials(root)` on a virgin world (what the account
+//     read, a test or a fixture does when nothing was presented) generates a vendor-shaped pair
+//     from `randomBytes`, so two fresh worlds are distinct BY CONSTRUCTION rather than by hashing
+//     where they sit. The pack's "different roots never share a secret" doctrine holds the same
+//     way it always did — by construction, now from entropy instead of from a path.
+// A pair that is not vendor-shaped is never adopted, so a caller's typo cannot become a world's
+// permanent credential.
+//
+// This twin does NOT refuse a request whose Basic pair does not match — it never has, and adding a
+// 401 the pack has never modeled or claimed is a separate capability with its own verify, not a
+// side effect of moving where the secret comes from. What this file changes is the ORIGIN of the
+// secret, not the enforcement around it.
+//
+// This is the runtime contract's ONE NAMED EXCEPTION to R9 (keying material generated once per
+// root and persisted, exactly like googleoauth's RSA pair, fal's ed25519 seed and sendblue's
+// api-key pair): same-root byte-identical, cross-root divergent by construction. The two reads
+// that CAN carry it — `GET Accounts/{Sid}.json`'s `auth_token`, and a verification row's
+// `account_sid` — are named on the gate: the account read joins the replay because the sequence
+// SEEDS the pair on its first step, and no verification read is replayed.
+//
+// `node:crypto` is required LAZILY (server-only), the same convention twilio-signature.ts takes,
+// so this module stays browser-bundle safe.
+import { applyTwinWriteAtomic, projectResources, nodeBuiltin } from '@volter/world-core';
+
+type NodeCrypto = typeof import('node:crypto');
+function nodeCrypto(): NodeCrypto {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  return nodeBuiltin('node:crypto') as NodeCrypto;
+}
+
+const SERVICE = 'twilio';
+/** The kernel resource type the pair is stored as — already declared in `pack.resources`. */
+export const TWILIO_SIGNING_KEY_TYPE = 'signing_key';
+const SIGNING_KEY_SUBJECT = 'signing_key:account';
+
+export type TwilioCredentials = {
+  /** `AC` + 32 hex — the real vendor's own SID shape. */
+  accountSid: string;
+  /** The HMAC-SHA1 key `X-Twilio-Signature` is computed with. */
+  authToken: string;
+};
+
+/** A pair a caller PRESENTED over the wire — the seed for a virgin world. */
+export type PresentedTwilioCredentials = { accountSid?: string | undefined; authToken?: string | undefined };
+
+/** Twilio account SIDs are `AC` + 32 hex, everywhere in the product and in its own OpenAPI. */
+export function isWellFormedTwilioAccountSid(sid: string | undefined): boolean {
+  return typeof sid === 'string' && /^AC[0-9a-fA-F]{32}$/.test(sid);
+}
+/** Real AuthTokens are 32 hex characters; the bar is a SHAPE bar and nothing more (a longer hex
+ *  token — the 64-hex string this pack used to derive — is still recognisably one). */
+export function isWellFormedTwilioAuthToken(token: string | undefined): boolean {
+  return typeof token === 'string' && /^[0-9a-fA-F]{32,}$/.test(token);
+}
+
+/**
+ * The `AccountSid:AuthToken` pair on a request's `Authorization: Basic …` header — how the real
+ * Twilio SDK authenticates every call, so an app wired at this twin presents it without being
+ * asked to do anything special. Returns undefined unless BOTH halves are vendor-shaped.
+ */
+export function presentedTwilioCredentials(headers?: Record<string, string>): PresentedTwilioCredentials | undefined {
+  let raw: string | undefined;
+  for (const [k, v] of Object.entries(headers ?? {})) if (k.toLowerCase() === 'authorization') raw = v;
+  const m = /^Basic\s+([A-Za-z0-9+/=]+)$/i.exec(raw ?? '');
+  if (!m) return undefined;
+  let decoded: string;
+  try {
+    decoded = Buffer.from(m[1]!, 'base64').toString('utf8');
+  } catch {
+    return undefined;
+  }
+  const sep = decoded.indexOf(':');
+  if (sep < 0) return undefined;
+  const accountSid = decoded.slice(0, sep);
+  const authToken = decoded.slice(sep + 1);
+  if (!isWellFormedTwilioAccountSid(accountSid) || !isWellFormedTwilioAuthToken(authToken)) return undefined;
+  return { accountSid, authToken };
+}
+
+function readStored(resources: readonly { type: string; id: string }[]): TwilioCredentials | undefined {
+  const row = resources.find((r) => r.type === TWILIO_SIGNING_KEY_TYPE && r.id === SIGNING_KEY_SUBJECT) as Record<string, unknown> | undefined;
+  const accountSid = row?.['_account_sid'];
+  const authToken = row?.['_auth_token'];
+  if (typeof accountSid !== 'string' || typeof authToken !== 'string') return undefined;
+  if (!accountSid || !authToken) return undefined;
+  return { accountSid, authToken };
+}
+
+/** The root's established pair, or undefined on a world that has never been seeded.
+ *  Pure read — never writes, so a read-only serve can ask. */
+export function storedTwilioCredentials(root?: string): TwilioCredentials | undefined {
+  return readStored(projectResources(SERVICE, root));
+}
+
+/** A freshly minted, vendor-shaped pair drawn from real entropy. */
+export function mintTwilioCredentials(presented?: PresentedTwilioCredentials): TwilioCredentials {
+  const hex = (bytes: number) => nodeCrypto().randomBytes(bytes).toString('hex');
+  return {
+    accountSid: isWellFormedTwilioAccountSid(presented?.accountSid) ? presented!.accountSid! : `AC${hex(16)}`,
+    authToken: isWellFormedTwilioAuthToken(presented?.authToken) ? presented!.authToken! : hex(16),
+  };
+}
+
+/**
+ * The root's `AccountSid`/`AuthToken`, establishing them on first use. `presented` (the Basic pair
+ * on the incoming request) seeds a virgin world; absent it, the twin mints one from real entropy.
+ * Stable forever after — across calls AND across processes.
+ *
+ * The decide-and-append runs inside the kernel's own action lock (`applyTwinWriteAtomic`), so two
+ * processes racing a first use agree on ONE pair rather than each signing with a key the other's
+ * state does not hold.
+ */
+export async function twilioCredentials(root?: string, presented?: PresentedTwilioCredentials): Promise<TwilioCredentials> {
+  const fast = storedTwilioCredentials(root);
+  if (fast) return fast;
+  const { value } = await applyTwinWriteAtomic<TwilioCredentials>(SERVICE, (resources) => {
+    const existing = readStored(resources);
+    if (existing) return { kind: 'skip', value: existing };
+    const minted = mintTwilioCredentials(presented);
+    return {
+      kind: 'write',
+      value: minted,
+      write: {
+        operation: 'signing_key.create',
+        subjectType: TWILIO_SIGNING_KEY_TYPE,
+        subjectId: SIGNING_KEY_SUBJECT,
+        // `_`-prefixed fields are twin-internal: `view()` strips them and no route projects this
+        // type, so the pair only ever leaves through `GET Accounts/{Sid}.json`, which is the
+        // vendor's own endpoint for exactly that.
+        fields: { _account_sid: minted.accountSid, _auth_token: minted.authToken },
+        actor: { kind: 'system' },
+      },
+    };
+  }, root);
+  return value;
+}
+
+/** The root's `AuthToken` — the key `X-Twilio-Signature` is HMAC-SHA1'd with. */
+export async function twilioAuthToken(root?: string): Promise<string> {
+  return (await twilioCredentials(root)).authToken;
+}
+/** The root's `AccountSid`. */
+export async function twilioAccountSid(root?: string): Promise<string> {
+  return (await twilioCredentials(root)).accountSid;
+}

package/src/twilio-server.ts

@@ -0,0 +1,49 @@
+// Twilio twin HTTP server — serve the full Twilio API twin handler over HTTP so the real
+// `twilio` npm SDK (via its injectable `httpClient` constructor option — see
+// twilio-sdk.integration.test.ts) works unmodified against it. Requests are form-urlencoded (POST/
+// PUT) or query-string (GET); responses are plain JSON.
+//
+// UNLIKE fal-server.ts (which must read an `x-fal-target-url` proxy header to recover the real
+// host, because the real `@fal-ai/client` has no injectable host and instead proxies via a
+// `requestMiddleware` URL rewrite), this server needs NO such proxy header: the real `twilio`
+// SDK's injectable `httpClient` receives the FULL absolute vendor URL per call (`opts.uri`, e.g.
+// `https://api.twilio.com/2010-04-01/Accounts/...`) and a caller-supplied httpClient can extract
+// its path+query directly — Twilio's THREE real hosts (api/verify/lookups.twilio.com) have
+// NON-OVERLAPPING path namespaces (`/2010-04-01/...` vs `/v2/Services/...` vs
+// `/v2/PhoneNumbers/...`, grounded live against the installed SDK's own generated `_uri`
+// construction), so `routeTwilioSurface`'s PATH-SHAPE fallback alone disambiguates every real
+// call once a caller's own httpClient forwards it here. The incoming HTTP `Host` header is
+// forwarded too (in the header map), so a direct (non-SDK) caller that sets it explicitly to a
+// real vendor hostname is also honored, per `routeTwilioSurface`'s explicit-host-wins precedence.
+// Writable by default; pass readOnly to reject writes with 405 (D3). State is the kernel
+// projection (no side-store) — see twilio-twin.ts.
+//
+// FETCH-FIRST (runtime contract R12b): the serve path is the plain fetch below, built from the
+// kernel's ONE adaptation (`createTwinFetchFromHandler`); this file contributes only VALUES. The
+// vendor's 204s return `{ status: 204, body: null }`, which the adapter's null-body rule serves as
+// a genuinely empty response. The server is one line of Bun.serve around that same closure.
+import { serveHttp } from '@volter/world-core';
+import { handleTwilioTwinRequest } from './twilio-twin.ts';
+import { createTwinFetchFromHandler, statefulTwinManifest } from '@volter/world-core';
+
+/** Options every Twilio-twin HTTP surface needs, independent of who owns the socket. */
+export interface TwilioTwinFetchOptions {
+  root?: string;
+  readOnly?: boolean;
+}
+
+export function createTwilioTwinFetch(options: TwilioTwinFetchOptions = {}): (request: Request) => Promise<Response> {
+  return createTwinFetchFromHandler(handleTwilioTwinRequest, {
+    ...options,
+    manifest: statefulTwinManifest({ vendor: 'twilio', twinOf: 'the Twilio messaging API', stores: 'sent messages progressing queued→sending→sent→delivered, with signed status callbacks' }),
+  });
+}
+
+export async function createTwilioTwinServer(options: { root?: string; port?: number; readOnly?: boolean } = {}): Promise<{ port: number; stop: () => void }> {
+  const server = await serveHttp({
+    port: options.port ?? 0,
+    idleTimeout: 60,
+    fetch: createTwilioTwinFetch(options),
+  });
+  return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}

package/src/twilio-signature.ts

@@ -0,0 +1,132 @@
+import { nodeBuiltin } from '@volter/world-core';
+// Twilio X-Twilio-Signature webhook signing — REAL HMAC-SHA1 sign/verify, written FRESH for
+// this pack (build spec §1 divergence 1: do NOT port fal-webhooks.ts, ed25519/asymmetric; do NOT
+// port replicate-webhooks.ts/inngest-signing.ts, HMAC-SHA256 base64). NEVER imports twilio-
+// twin.ts's handler — this module is pure local crypto, so its capabilities are legitimately
+// mutation-test ALLOW-listed (build spec §13.8).
+//
+// GROUNDED (2026-07-09, read-only) against the ACTUALLY-INSTALLED `twilio@6.0.2` npm package's
+// own compiled source (`node_modules/twilio/lib/webhooks/webhooks.js`, fetched via `npm pack`,
+// not just docs — same discipline algolia/inngest/fal used for their own SDK-source grounding):
+//   getExpectedTwilioSignature(authToken, url, params) computes, VERBATIM:
+//     data = Object.keys(params).sort().reduce((acc,key) => acc + key + String(params[key]), url)
+//     signature = base64(HMAC-SHA1(authToken, data))
+//   — i.e. the signed string is the URL (INCLUDING query string) followed by every POST
+//   parameter's key immediately concatenated with its value (NO separator between key/value or
+//   between successive pairs), for keys in ASCII-sorted order. This is the exact algorithm this
+//   module implements (`toFormUrlEncodedParam`/`computeTwilioSignature` below are line-for-line
+//   equivalent to the real SDK's `toFormUrlEncodedParam`/`getExpectedTwilioSignature`).
+//
+// NO CREDENTIAL LIVES HERE. This module is PURE CRYPTO: every function takes the AuthToken (and,
+// where a payload carries it, the AccountSid) as an argument. It used to derive them from the
+// world's DIRECTORY PATH — `sha256('twilio-twin-auth-token:' + root)` — which made the filesystem
+// the owner of the one secret Twilio's whole signature scheme rests on. The pair is now twin STATE
+// (twilio-credentials.ts: established once per root, persisted, entropy-born or seeded from the
+// Basic pair a caller presents); a caller reads it with `twilioAuthToken(root)` /
+// `twilioAccountSid(root)` and hands it in. That keeps this module synchronous, state-free and
+// legitimately mutation-test ALLOW-listed, and it means no path can ever reach a signature.
+//
+// `node:crypto` is required LAZILY (server-only), same convention as fal-webhooks.ts/replicate-
+// webhooks.ts, so this module stays browser-bundle safe.
+type NodeCrypto = typeof import('node:crypto');
+function nodeCrypto(): NodeCrypto {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  return nodeBuiltin('node:crypto') as NodeCrypto;
+}
+
+export class TwilioSignatureVerificationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'TwilioSignatureVerificationError';
+  }
+}
+
+/** VERBATIM port of the real SDK's `toFormUrlEncodedParam` for a scalar param (arrays are not
+ *  used by any signed payload this pack builds — status callbacks and inbound messages are all
+ *  flat string params). */
+function toFormUrlEncodedParam(key: string, value: string): string {
+  return key + value;
+}
+
+/** VERBATIM port of the real SDK's `getExpectedTwilioSignature`: base64(HMAC-SHA1(authToken,
+ *  url + sorted-key-concatenated params)). */
+export function computeTwilioSignature(authToken: string, url: string, params: Record<string, string>): string {
+  const data = Object.keys(params)
+    .sort()
+    .reduce((acc, key) => acc + toFormUrlEncodedParam(key, params[key] ?? ''), url);
+  return nodeCrypto().createHmac('sha1', authToken).update(Buffer.from(data, 'utf-8')).digest('base64');
+}
+
+/** Constant-time-ish comparison (length-checked first, then a real `crypto.timingSafeEqual`) —
+ *  avoids a naive `===` timing side-channel on the signature string. */
+function signaturesEqual(a: string, b: string): boolean {
+  const bufA = Buffer.from(a, 'utf-8');
+  const bufB = Buffer.from(b, 'utf-8');
+  if (bufA.length !== bufB.length) return false;
+  return nodeCrypto().timingSafeEqual(bufA, bufB);
+}
+
+/** Verify a received X-Twilio-Signature header against an AuthToken the caller supplies (the
+ *  world's own comes from `twilioAuthToken(root)`). Pure local crypto — never touches the twin
+ *  handler and never reads state. Throws on mismatch. */
+export function verifyTwilioSignature(url: string, params: Record<string, string>, signature: string, authToken: string): void {
+  const expected = computeTwilioSignature(authToken, url, params);
+  if (!signaturesEqual(expected, signature)) {
+    throw new TwilioSignatureVerificationError('X-Twilio-Signature verification failed.');
+  }
+}
+
+/** Build a signed request envelope (headers + form params) for ANY Twilio-shaped webhook POST
+ *  (status callbacks, inbound messages) against a supplied AuthToken. Pure builder — never calls
+ *  the twin handler and never reads state. */
+export function buildSignedTwilioRequest(args: { url: string; params: Record<string, string>; authToken: string }): { headers: Record<string, string>; params: Record<string, string> } {
+  const signature = computeTwilioSignature(args.authToken, args.url, args.params);
+  return { headers: { 'x-twilio-signature': signature }, params: args.params };
+}
+
+/** Build a signed Message status-callback delivery (the shape Twilio POSTs to a message's
+ *  `StatusCallback` URL): {MessageSid, MessageStatus, To, From, AccountSid, ...}. */
+export function buildSignedStatusCallback(args: {
+  url: string;
+  messageSid: string;
+  messageStatus: 'queued' | 'sending' | 'sent' | 'delivered' | 'undelivered' | 'failed';
+  to: string;
+  from: string;
+  accountSid: string;
+  authToken: string;
+  errorCode?: string;
+}): { headers: Record<string, string>; params: Record<string, string> } {
+  const params: Record<string, string> = {
+    MessageSid: args.messageSid,
+    SmsSid: args.messageSid,
+    MessageStatus: args.messageStatus,
+    To: args.to,
+    From: args.from,
+    AccountSid: args.accountSid,
+    ...(args.errorCode ? { ErrorCode: args.errorCode } : {}),
+  };
+  return buildSignedTwilioRequest({ url: args.url, params, authToken: args.authToken });
+}
+
+/** Build a signed INBOUND message webhook (the shape Twilio POSTs to a phone number's
+ *  `SmsUrl`/`smsUrl` when a real SMS arrives): {MessageSid, From, To, Body, ...}. Pure builder —
+ *  never calls the twin handler (build spec §3 webhooks.inbound_message_shape — ALLOW builder). */
+export function buildSignedInboundMessage(args: {
+  url: string;
+  messageSid?: string;
+  from: string;
+  to: string;
+  body: string;
+  accountSid: string;
+  authToken: string;
+}): { headers: Record<string, string>; params: Record<string, string> } {
+  const params: Record<string, string> = {
+    MessageSid: args.messageSid ?? `SM${nodeCrypto().createHash('sha256').update(`${args.from}:${args.to}:${args.body}`).digest('hex').slice(0, 32)}`,
+    From: args.from,
+    To: args.to,
+    Body: args.body,
+    AccountSid: args.accountSid,
+    NumMedia: '0',
+  };
+  return buildSignedTwilioRequest({ url: args.url, params, authToken: args.authToken });
+}