@codespar/cli 0.14.0 → 0.16.0

package/templates/bills-agent/packages/agent-runtime/src/channels/whatsapp/cloud-api.ts

@@ -0,0 +1,358 @@
+/**
+ * The official backend: Meta's WhatsApp Cloud API, behind the same interface
+ * the simulator implements. An ADAPTER and nothing more — the rules, the
+ * session window and the conversation record are the channel's, above this.
+ *
+ * Three things about it are deliberate.
+ *
+ * The credentials are ABSENT by default and this backend refuses to open
+ * without them, by name. No fallback, no "development mode" that quietly
+ * talks to nobody: a channel that pretends to send is worse than one that
+ * says it cannot.
+ *
+ * Nothing here is called from a test or from the CI, ever. What the tests
+ * exercise are the four pure functions — the signature check, the webhook
+ * parse, the verification handshake and the request builder — which is
+ * exactly the part where a mistake is silent. The send itself is one `fetch`
+ * over a request those functions built.
+ *
+ * And the shapes are written against Meta's published documentation, not
+ * against a call we made: nobody on this repo has a Business account, so the
+ * first live run belongs to the developer who has one. The README says that
+ * in those words, and `docs/OPEN_QUESTIONS.md` names what a live run would
+ * settle.
+ */
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { createServer, type Server } from "node:http";
+import type { ChannelBackend, InboundMessage, OutboundBody, SentMessage } from "../types.js";
+
+export interface CloudApiConfig {
+  /**
+   * Where the Graph API lives. Meta's own by default, and the local emulator's
+   * when the run is against the local emulator — which is the whole point of
+   * having it be a field: the two backends are THE SAME CODE with a different
+   * base URL, so the simulator exercises the adapter instead of standing in
+   * for it. A mock of our own would only ever agree with us.
+   */
+  baseUrl: string;
+  /** The number the business sends from, as Meta's dashboard names it. */
+  phoneNumberId: string;
+  accessToken: string;
+  /** Echoed back on the `GET` handshake when Meta registers the webhook. */
+  verifyToken: string;
+  /** The app secret that signs deliveries. Without it no delivery is trusted. */
+  appSecret: string;
+  apiVersion: string;
+  webhookPort: number;
+}
+
+/** Meta's own Graph host. Anything else is a stand-in, and the channel treats it as one. */
+export const META_GRAPH_HOST = "graph.facebook.com";
+
+/**
+ * Whether this base URL is Meta. It decides one thing that matters beyond
+ * logging: `live`, which is what the consent-evidence builder refuses on. An
+ * act observed by an emulator was observed by nobody.
+ */
+export function isMetaBaseUrl(baseUrl: string): boolean {
+  try {
+    return new URL(baseUrl).hostname === META_GRAPH_HOST;
+  } catch {
+    return false;
+  }
+}
+
+export const CLOUD_API_ENV = {
+  phoneNumberId: "WHATSAPP_PHONE_NUMBER_ID",
+  accessToken: "WHATSAPP_ACCESS_TOKEN",
+  verifyToken: "WHATSAPP_VERIFY_TOKEN",
+  appSecret: "WHATSAPP_APP_SECRET",
+  apiVersion: "WHATSAPP_API_VERSION",
+  webhookPort: "WHATSAPP_WEBHOOK_PORT",
+  baseUrl: "WHATSAPP_GRAPH_URL",
+} as const;
+
+export interface ConfigResult {
+  config?: CloudApiConfig;
+  /** The variables that are not set. A refusal names them rather than saying "misconfigured". */
+  missing: string[];
+}
+
+export function loadCloudApiConfig(env: NodeJS.ProcessEnv): ConfigResult {
+  const read = (name: string) => {
+    const v = env[name]?.trim();
+    return v ? v : undefined;
+  };
+  const phoneNumberId = read(CLOUD_API_ENV.phoneNumberId);
+  const accessToken = read(CLOUD_API_ENV.accessToken);
+  const verifyToken = read(CLOUD_API_ENV.verifyToken);
+  const appSecret = read(CLOUD_API_ENV.appSecret);
+  const missing = [
+    ...(phoneNumberId ? [] : [CLOUD_API_ENV.phoneNumberId]),
+    ...(accessToken ? [] : [CLOUD_API_ENV.accessToken]),
+    ...(verifyToken ? [] : [CLOUD_API_ENV.verifyToken]),
+    ...(appSecret ? [] : [CLOUD_API_ENV.appSecret]),
+  ];
+  if (!phoneNumberId || !accessToken || !verifyToken || !appSecret) return { missing };
+  return {
+    missing,
+    config: {
+      baseUrl: read(CLOUD_API_ENV.baseUrl) ?? `https://${META_GRAPH_HOST}`,
+      phoneNumberId,
+      accessToken,
+      verifyToken,
+      appSecret,
+      apiVersion: read(CLOUD_API_ENV.apiVersion) ?? "v21.0",
+      webhookPort: Number(read(CLOUD_API_ENV.webhookPort) ?? 3111),
+    },
+  };
+}
+
+/* ── the pure half: what the tests drive ─────────────────────── */
+
+/**
+ * `X-Hub-Signature-256: sha256=<hex>`, HMAC-SHA256 of the RAW body under the
+ * app secret. Raw and not re-serialized: a body that round-tripped through
+ * `JSON.parse` is a different string, and the signature is over bytes.
+ */
+export function verifyWebhookSignature(appSecret: string, header: string | undefined, rawBody: string): { ok: true } | { ok: false; reason: string } {
+  if (!header) return { ok: false, reason: "missing X-Hub-Signature-256" };
+  const [algorithm, signature] = header.split("=");
+  if (algorithm !== "sha256" || !signature) return { ok: false, reason: "malformed signature header" };
+  const expected = createHmac("sha256", appSecret).update(rawBody, "utf8").digest("hex");
+  if (expected.length !== signature.length) return { ok: false, reason: "signature mismatch" };
+  if (!timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(signature, "hex"))) return { ok: false, reason: "signature mismatch" };
+  return { ok: true };
+}
+
+/** The `GET` handshake Meta makes once, when the webhook URL is registered. */
+export function verifyChallenge(config: CloudApiConfig, query: Record<string, string | undefined>): { status: number; body: string } {
+  if (query["hub.mode"] !== "subscribe") return { status: 400, body: "bad mode" };
+  if (query["hub.verify_token"] !== config.verifyToken) return { status: 403, body: "bad verify token" };
+  return { status: 200, body: query["hub.challenge"] ?? "" };
+}
+
+interface CloudApiEnvelope {
+  object?: string;
+  entry?: Array<{
+    changes?: Array<{
+      field?: string;
+      value?: {
+        messaging_product?: string;
+        metadata?: { phone_number_id?: string };
+        messages?: Array<{ id?: string; from?: string; timestamp?: string; type?: string; text?: { body?: string } }>;
+        statuses?: Array<{ id?: string; status?: string }>;
+      };
+    }>;
+  }>;
+}
+
+/**
+ * The text messages inside one delivery. A delivery carries several entries,
+ * each with several changes, each with several messages — and also status
+ * updates, which are not messages. Anything that is not a `text` is dropped
+ * with its id named: this channel reads words, and an image or a location the
+ * agent cannot read must not be silently treated as an empty message.
+ */
+export function parseInbound(payload: unknown): { messages: InboundMessage[]; ignored: Array<{ id: string; type: string }> } {
+  const envelope = payload as CloudApiEnvelope;
+  const messages: InboundMessage[] = [];
+  const ignored: Array<{ id: string; type: string }> = [];
+  for (const entry of envelope.entry ?? []) {
+    for (const change of entry.changes ?? []) {
+      for (const message of change.value?.messages ?? []) {
+        const id = message.id;
+        const from = message.from;
+        if (!id || !from) continue;
+        if (message.type !== "text" || !message.text?.body) {
+          ignored.push({ id, type: message.type ?? "unknown" });
+          continue;
+        }
+        messages.push({ id, from: from.startsWith("+") ? from : `+${from}`, text: message.text.body, timestamp: Number(message.timestamp ?? 0) });
+      }
+    }
+  }
+  return { messages, ignored };
+}
+
+export interface SendRequest {
+  url: string;
+  method: "POST";
+  headers: Record<string, string>;
+  body: string;
+}
+
+/**
+ * The `/messages` call, as Meta documents it. `to` loses its `+`: the Cloud
+ * API wants the number in international format without the plus.
+ *
+ * `media` has no branch here and that is the honest answer, not an omission.
+ * Sending an image means uploading it first (`POST /{version}/{phone-number-id}/media`,
+ * multipart) or handing Meta a public URL, and this repo hosts nothing and
+ * renders no PNG — `qrcode-terminal` draws characters. The channel therefore
+ * sends the copy-and-paste as its own message, which is the string that
+ * actually pays, and the QR is the simulator's. Named in the README and in
+ * `docs/OPEN_QUESTIONS.md`.
+ */
+export function buildSendRequest(config: CloudApiConfig, to: string, body: OutboundBody): SendRequest | { unsupported: string } {
+  const base = {
+    url: `${config.baseUrl.replace(/\/$/, "")}/${config.apiVersion}/${config.phoneNumberId}/messages`,
+    method: "POST" as const,
+    headers: { authorization: `Bearer ${config.accessToken}`, "content-type": "application/json" },
+  };
+  // `to` loses its `+`: the Cloud API documents the number in international
+  // format without one, and the emulator keys its conversation on the literal
+  // string, so a `+` here and none on the inbound side splits one person into
+  // two conversations (measured; docs/OPEN_QUESTIONS.md §46c).
+  const recipient = { messaging_product: "whatsapp", recipient_type: "individual", to: toGraphNumber(to) };
+  switch (body.kind) {
+    case "text":
+      return { ...base, body: JSON.stringify({ ...recipient, type: "text", text: { preview_url: false, body: body.text } }) };
+    case "instrument":
+      return { ...base, body: JSON.stringify({ ...recipient, type: "text", text: { preview_url: false, body: body.value } }) };
+    case "template":
+      return {
+        ...base,
+        body: JSON.stringify({
+          ...recipient,
+          type: "template",
+          template: {
+            name: body.template,
+            language: { code: body.language },
+            ...(body.variables.length ? { components: [{ type: "body", parameters: body.variables.map((text) => ({ type: "text", text })) }] } : {}),
+          },
+        }),
+      };
+    case "media":
+      return { unsupported: "media_upload_unimplemented" };
+  }
+}
+
+/* ── the impure half: one fetch over a request the above built ── */
+
+/** `+5511987654321` -> `5511987654321`, the only form the Graph API takes. */
+export function toGraphNumber(contact: string): string {
+  return contact.replace(/^\+/, "");
+}
+
+export interface CloudApiOptions {
+  config: CloudApiConfig;
+  conversation: { contact: string };
+  say: (line: string) => void;
+  /** Injected so a test can drive `deliver` without a network. The default is the platform's. */
+  fetchImpl?: typeof fetch;
+}
+
+export class WhatsAppCloudApi implements ChannelBackend {
+  readonly name: string;
+  /** True only against Meta. The emulator is a stand-in and says so. */
+  readonly live: boolean;
+  private server: Server | undefined;
+  private readonly queue: InboundMessage[] = [];
+  private waiting: ((m: InboundMessage | undefined) => void) | undefined;
+  private closed = false;
+
+  constructor(private readonly options: CloudApiOptions) {
+    this.live = isMetaBaseUrl(options.config.baseUrl);
+    this.name = this.live ? "cloud-api" : "emulator";
+  }
+
+  /** The port the receiver is listening on, which the emulator has to be told about. */
+  get webhookPort(): number {
+    return this.options.config.webhookPort;
+  }
+
+  async open(): Promise<void> {
+    const { config, say } = this.options;
+    this.server = createServer((req, res) => {
+      const url = new URL(req.url ?? "/", `http://127.0.0.1:${config.webhookPort}`);
+      if (req.method === "GET") {
+        const query = Object.fromEntries(url.searchParams.entries());
+        const answer = verifyChallenge(config, query);
+        res.writeHead(answer.status, { "content-type": "text/plain" }).end(answer.body);
+        return;
+      }
+      if (req.method !== "POST") {
+        res.writeHead(405).end();
+        return;
+      }
+      const chunks: Buffer[] = [];
+      req.on("data", (c: Buffer) => chunks.push(c));
+      req.on("end", () => {
+        const raw = Buffer.concat(chunks).toString("utf8");
+        const header = req.headers["x-hub-signature-256"];
+        const check = verifyWebhookSignature(config.appSecret, Array.isArray(header) ? header[0] : header, raw);
+        if (!check.ok) {
+          say(`[whatsapp] delivery refused: ${check.reason}`);
+          res.writeHead(401, { "content-type": "application/json" }).end(JSON.stringify({ error: "bad_signature" }));
+          return;
+        }
+        let parsed: { messages: InboundMessage[]; ignored: Array<{ id: string; type: string }> };
+        try {
+          parsed = parseInbound(JSON.parse(raw));
+        } catch {
+          res.writeHead(400, { "content-type": "application/json" }).end(JSON.stringify({ error: "invalid_json" }));
+          return;
+        }
+        for (const ignored of parsed.ignored) say(`[whatsapp] ignored ${ignored.type} message ${ignored.id}: this channel reads text`);
+        for (const message of parsed.messages) this.push(message);
+        // Always 200 once read: Meta retries on anything else, and a duplicate is not an error.
+        res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify({ received: parsed.messages.length }));
+      });
+    });
+    await new Promise<void>((resolve) => this.server!.listen(config.webhookPort, resolve));
+    say(
+      this.live
+        ? `[whatsapp] cloud API backend: webhook on http://127.0.0.1:${config.webhookPort}/ — expose it and register it with Meta; deliveries are verified against ${CLOUD_API_ENV.appSecret}`
+        : `[whatsapp] emulator backend: sending to ${config.baseUrl}/${config.apiVersion}, receiving signed deliveries on http://127.0.0.1:${config.webhookPort}/`,
+    );
+  }
+
+  private push(message: InboundMessage): void {
+    if (this.waiting) {
+      const resolve = this.waiting;
+      this.waiting = undefined;
+      resolve(message);
+      return;
+    }
+    this.queue.push(message);
+  }
+
+  async next(): Promise<InboundMessage | undefined> {
+    if (this.closed) return undefined;
+    const queued = this.queue.shift();
+    if (queued) return queued;
+    return new Promise<InboundMessage | undefined>((resolve) => {
+      this.waiting = resolve;
+    });
+  }
+
+  async deliver(to: string, body: OutboundBody): Promise<SentMessage> {
+    const request = buildSendRequest(this.options.config, to, body);
+    if ("unsupported" in request) {
+      return { id: "", state: "failed", refused: { rule: request.unsupported, detail: "this backend cannot upload media: the copy-and-paste text is what pays, and the QR image is the simulator's" } };
+    }
+    const doFetch = this.options.fetchImpl ?? fetch;
+    const response = await doFetch(request.url, { method: request.method, headers: request.headers, body: request.body });
+    const text = await response.text();
+    if (!response.ok) {
+      return { id: "", state: "failed", refused: { rule: "provider_refused", detail: `${response.status} from the Cloud API` } };
+    }
+    let id = "";
+    try {
+      id = String((JSON.parse(text) as { messages?: Array<{ id?: string }> }).messages?.[0]?.id ?? "");
+    } catch {
+      /* a 2xx with an unreadable body: the message went, the id did not come back */
+    }
+    return { id, state: "sent" };
+  }
+
+  async close(): Promise<void> {
+    this.closed = true;
+    if (this.waiting) {
+      this.waiting(undefined);
+      this.waiting = undefined;
+    }
+    await new Promise<void>((resolve) => (this.server ? this.server.close(() => resolve()) : resolve()));
+  }
+}

package/templates/bills-agent/packages/agent-runtime/src/channels/whatsapp/emulator.ts

@@ -0,0 +1,206 @@
+/**
+ * The house simulator, which is not ours: `dyvit-wa-sim`, the local Cloud API
+ * emulator from https://github.com/fabianocruz/whatsapp-simulator (MIT).
+ *
+ * WHY A SEPARATE PROCESS INSTEAD OF A FAKE IN THIS REPO. A mock we wrote would
+ * agree with us by construction — it would accept the payloads we send because
+ * we wrote both sides, and the day Meta refused one we would find out in
+ * production. The emulator answers `POST /v{version}/{phone-number-id}/messages`
+ * with the Cloud API's own response shape and posts back the same signed
+ * `x-hub-signature-256` webhooks, so the `simulator` backend is THE SAME CODE
+ * as the official one with a different base URL. That is the thing being
+ * proved, and it is not something a mock can prove.
+ *
+ * It also has a clock we can move (`POST /_sim/clock`), which a replay
+ * finishing in seconds cannot otherwise have: a collection runs over days, and
+ * without moving the clock the 24-hour window never closes, so the one rule
+ * that decides whether a message may be sent at all is never exercised.
+ *
+ * WHAT THIS FILE IS: the `_sim/*` side only — the routes that belong to the
+ * emulator and have no counterpart at Meta. The sending and receiving are
+ * `WhatsAppCloudApi`, unchanged.
+ *
+ * The emulator is a separate process and is not a dependency of this workspace:
+ * it is a development tool nothing here imports. `scripts/whatsapp-emulator.mjs`
+ * fetches `@dyvit/whatsapp-simulator-cli` at a pinned version and runs it;
+ * `npm run whatsapp:emulator` is the command.
+ */
+import type { ConversationScript } from "@codespar/agent-core";
+import type { ChannelBackend, InboundMessage, OutboundBody, SentMessage } from "../types.js";
+import { toGraphNumber, WhatsAppCloudApi, type CloudApiOptions } from "./cloud-api.js";
+
+export const EMULATOR_ENV = {
+  url: "WHATSAPP_SIM_URL",
+  appSecret: "WHATSAPP_SIM_APP_SECRET",
+  webhookPort: "WHATSAPP_SIM_WEBHOOK_PORT",
+  phoneNumberId: "WHATSAPP_SIM_PHONE_NUMBER_ID",
+} as const;
+
+export const EMULATOR_DEFAULTS = {
+  url: "http://127.0.0.1:4290",
+  /** Matches `--app-secret` in `npm run whatsapp:emulator`. A local development value, not a credential. */
+  appSecret: "dev",
+  webhookPort: 4399,
+  phoneNumberId: "900000000001",
+  apiVersion: "v22.0",
+} as const;
+
+export class EmulatorUnreachableError extends Error {
+  constructor(url: string, detail: string) {
+    super(
+      `the WhatsApp emulator is not answering at ${url} (${detail}).\n` +
+        `  Start it in another terminal:  npm run whatsapp:emulator\n` +
+        `  It is dyvit-wa-sim, from https://github.com/fabianocruz/whatsapp-simulator — MIT, run from npm at a pinned version, no Meta account and no credential.`,
+    );
+    this.name = "EmulatorUnreachableError";
+  }
+}
+
+/** The `_sim/*` routes: what the emulator has and Meta does not. */
+export class EmulatorDriver {
+  constructor(
+    private readonly url: string,
+    private readonly fetchImpl: typeof fetch = fetch,
+  ) {}
+
+  private async call(path: string, init?: RequestInit): Promise<unknown> {
+    let response: Response;
+    try {
+      response = await this.fetchImpl(`${this.url}${path}`, { ...init, signal: AbortSignal.timeout(5000) });
+    } catch (err) {
+      throw new EmulatorUnreachableError(this.url, err instanceof Error ? err.message : String(err));
+    }
+    const text = await response.text();
+    if (!response.ok) throw new Error(`emulator answered ${response.status} to ${path}: ${text.slice(0, 200)}`);
+    return text ? JSON.parse(text) : {};
+  }
+
+  private post(path: string, body: unknown): Promise<unknown> {
+    return this.call(path, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) });
+  }
+
+  health(): Promise<unknown> {
+    return this.call("/health");
+  }
+
+  /** Pins the conversation clock, so a scripted run reads the same at 03:00 as at 15:00. */
+  pin(at: Date): Promise<unknown> {
+    return this.post("/_sim/clock", { now: at.toISOString() });
+  }
+
+  /** Moves the conversation clock forward. The only way to reach the far side of the 24-hour window. */
+  advanceHours(hours: number): Promise<unknown> {
+    return this.post("/_sim/clock", { advance_hours: hours });
+  }
+
+  /** The person writes. The emulator answers with a signed inbound webhook to our receiver. */
+  inbound(options: { phoneNumberId: string; from: string; text: string; sentAt?: Date }): Promise<unknown> {
+    return this.post("/_sim/inbound", {
+      phone_number_id: options.phoneNumberId,
+      // Without the `+`, matching what `deliver` sends as `to`: the emulator keys
+      // its conversation on the literal string, so the two forms are two people.
+      from: toGraphNumber(options.from),
+      text: options.text,
+      ...(options.sentAt ? { sent_at: options.sentAt.toISOString() } : {}),
+    });
+  }
+
+  /** The priced timeline, which is the emulator's own reason for existing. Read for the console, never asserted on. */
+  state(key: string): Promise<{ priced?: { total?: number; currency?: string } } | undefined> {
+    return this.call(`/_sim/state?key=${encodeURIComponent(key)}`).then(
+      (v) => v as { priced?: { total?: number; currency?: string } },
+      () => undefined,
+    );
+  }
+}
+
+export interface EmulatorBackendOptions extends CloudApiOptions {
+  driver: EmulatorDriver;
+  /** The person's turns. Absent means they are at the keyboard. */
+  script?: ConversationScript | undefined;
+  /** The instant the emulator's conversation clock is pinned to. */
+  pinAt?: Date | undefined;
+  /** Interactive only: reads the person's next line. */
+  ask?: ((question: string) => Promise<string>) | undefined;
+  /** Where the console draws the conversation as it goes. */
+  render: (line: string) => void;
+}
+
+/**
+ * The `simulator` backend: `WhatsAppCloudApi` pointed at the emulator, plus the
+ * one thing the Cloud API has no equivalent for — making the person write.
+ *
+ * Every outbound message goes through the same `deliver` the Meta backend uses,
+ * and every inbound one arrives as a signed webhook at the same receiver, so
+ * nothing here is a shortcut around the adapter.
+ */
+export class WhatsAppEmulator implements ChannelBackend {
+  readonly name = "emulator";
+  readonly live = false;
+  private readonly api: WhatsAppCloudApi;
+  private turn = 0;
+  private closed = false;
+
+  constructor(private readonly options: EmulatorBackendOptions) {
+    const { driver: _driver, script: _script, pinAt: _pinAt, ask: _ask, render: _render, ...api } = options;
+    this.api = new WhatsAppCloudApi(api);
+  }
+
+  async open(): Promise<void> {
+    await this.api.open();
+    await this.options.driver.health();
+    if (this.options.pinAt) await this.options.driver.pin(this.options.pinAt);
+    this.options.render("");
+    this.options.render(`  ┌─ WhatsApp (dyvit-wa-sim, emulador local da Cloud API — sem rede externa, sem conta Meta)`);
+  }
+
+  async next(): Promise<InboundMessage | undefined> {
+    if (this.closed) return undefined;
+    const text = await this.nextText();
+    if (text === undefined) return undefined;
+    // The person writes THROUGH the emulator: it mints the message id and posts
+    // the signed webhook our receiver verifies, so a scripted turn takes the
+    // same path a real one would.
+    await this.options.driver.inbound({
+      phoneNumberId: this.options.config.phoneNumberId,
+      from: this.options.conversation.contact,
+      text,
+    });
+    return this.api.next();
+  }
+
+  private async nextText(): Promise<string | undefined> {
+    const script = this.options.script;
+    if (script) {
+      const turn = script.turns[this.turn];
+      if (!turn) return undefined;
+      this.turn += 1;
+      // The person's own pause, on the emulator's clock. A conversation that
+      // happens over days is what closes the 24-hour window.
+      if (turn.after_seconds > 0) await this.options.driver.advanceHours(turn.after_seconds / 3600);
+      return turn.text;
+    }
+    if (!this.options.ask) return undefined;
+    let answer: string;
+    try {
+      answer = await this.options.ask("  │ voce> ");
+    } catch {
+      return undefined;
+    }
+    const text = answer.trim();
+    if (!text) return this.nextText();
+    if (["sair", "exit", "quit"].includes(text.toLowerCase())) return undefined;
+    return text;
+  }
+
+  deliver(to: string, body: OutboundBody): Promise<SentMessage> {
+    return this.api.deliver(to, body);
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+    await this.api.close();
+    this.options.render("  └─ fim da conversa");
+  }
+}

package/templates/bills-agent/packages/agent-runtime/src/channels/whatsapp/evidence.ts

@@ -0,0 +1,109 @@
+/**
+ * Decision 19a, the part a channel can carry: `attestation.evidence` on
+ * `POST /v1/consents/{token}/submit` (codespar-enterprise ent#1615).
+ *
+ * In the sandbox a mandate is born at the terminal with
+ * `attestation: { method: "in_person" }` — the titular is at the keyboard and
+ * the partner is the process. In production the act happens in a
+ * CONVERSATION, so the method is `partner_session` and the submit may carry
+ * what the partner OBSERVED of it. This builds that object.
+ *
+ * The API's rule, restated here because it is the whole point: a WhatsApp
+ * conversation hands the partner a message and a sender, not a socket. The
+ * channel's allowed keys are therefore `contact`, `message_id`, `session_id`
+ * and `provider_ts`, and an `ip`, a `user_agent`, a `device_id_hash` or a
+ * `geo` on this channel would have been inferred rather than observed. The
+ * API refuses them (400 `attestation_evidence_invalid`), and so does this,
+ * one layer earlier, because a value inferred inside a signed record reads as
+ * observed and is worse than an absent one.
+ *
+ * WHY THE EMULATOR CANNOT PRODUCE ONE. Everything here is a claim about what a
+ * provider observed. A conversation carried by an emulator on the developer's
+ * own machine was observed by nobody: its message id was minted locally, its
+ * timestamp came from a clock we move ourselves, and no phone was involved.
+ * Signing that as evidence would be a false declaration — the same one the
+ * API's own schema warns about for a partner that declares `other` for a
+ * WhatsApp act. So `evidenceFor` returns a REFUSAL for any backend that is not
+ * live, with the reason on it, and the caller either submits without evidence
+ * or does not submit at all. That is not a gap in the seam; it is the seam
+ * working.
+ *
+ * `live` is not a flag anyone sets: it is whether the base URL is Meta's host.
+ * A run cannot claim to be live by being configured to say so.
+ */
+import type { InboundMessage } from "../types.js";
+
+/** The keys the API's `whatsapp` channel accepts. Mirrored from `CONSENT_EVIDENCE_CHANNEL_KEYS`. */
+export const WHATSAPP_EVIDENCE_KEYS = ["contact", "message_id", "session_id", "provider_ts"] as const;
+
+/** Opaque provider ids: a `wamid.` carries `.`, `:`, `=` and `+`, and all four are allowed. */
+const OPAQUE_ID = /^[A-Za-z0-9_.:=+-]{1,120}$/;
+
+/**
+ * The evidence as the PARTNER sends it. The wire carries `contact` in the
+ * clear and the API hashes it into `contact_hash` under the org's own key —
+ * a partner cannot compute that hash, and a partner-computed one would match
+ * nothing.
+ */
+export interface WhatsAppConsentEvidence {
+  channel: "whatsapp";
+  contact?: string;
+  message_id?: string;
+  session_id?: string;
+  /** Unix seconds on the PROVIDER's clock, which is not the partner's. */
+  provider_ts?: number;
+}
+
+export interface ConsentAttestation {
+  method: "partner_session";
+  /** Unix seconds: when the PARTNER says the human authorized. */
+  asserted_at: number;
+  /** The partner's own record id. `^[A-Za-z0-9_-]{1,120}$` — no dots, so a `wamid` goes in `message_id`. */
+  reference?: string;
+  evidence: WhatsAppConsentEvidence;
+}
+
+export type EvidenceResult = { attestable: true; attestation: ConsentAttestation } | { attestable: false; reason: string };
+
+export interface EvidenceInput {
+  /** Whether the backend that carried the message talks to a real provider. */
+  live: boolean;
+  /** The message in which the person said yes. */
+  message: InboundMessage;
+  /** The partner's id for this conversation, when it has one. */
+  sessionId?: string | undefined;
+  /** The partner's clock, for `asserted_at`. */
+  now: () => Date;
+  reference?: string | undefined;
+}
+
+export function evidenceFor(input: EvidenceInput): EvidenceResult {
+  if (!input.live) {
+    return {
+      attestable: false,
+      reason:
+        "this act was observed by an emulator on this machine, and a simulated observation is not evidence: " +
+        "the message id was minted locally, the timestamp came from a clock we move ourselves, and no phone was involved",
+    };
+  }
+  if (!OPAQUE_ID.test(input.message.id)) return { attestable: false, reason: `the provider message id does not fit the API's opaque-id shape: ${input.message.id.slice(0, 24)}` };
+  if (!Number.isInteger(input.message.timestamp) || input.message.timestamp <= 0) return { attestable: false, reason: "the provider gave no usable timestamp for the message" };
+  if (input.sessionId !== undefined && !OPAQUE_ID.test(input.sessionId)) return { attestable: false, reason: "the session id does not fit the API's opaque-id shape" };
+  if (input.reference !== undefined && !/^[A-Za-z0-9_-]{1,120}$/.test(input.reference)) return { attestable: false, reason: "the attestation reference must be [A-Za-z0-9_-]{1,120}" };
+
+  return {
+    attestable: true,
+    attestation: {
+      method: "partner_session",
+      asserted_at: Math.floor(input.now().getTime() / 1000),
+      ...(input.reference !== undefined ? { reference: input.reference } : {}),
+      evidence: {
+        channel: "whatsapp",
+        contact: input.message.from,
+        message_id: input.message.id,
+        ...(input.sessionId !== undefined ? { session_id: input.sessionId } : {}),
+        provider_ts: input.message.timestamp,
+      },
+    },
+  };
+}