@voltro/cli 0.33.0 → 0.35.0

package/dist/webhookDiscovery-CrGAfhIG.js

@@ -0,0 +1,2 @@
+import { i as e, r as t, t as n } from "./webhookDiscovery-D7VaeMlz.js";
+export { n as WEBHOOK_PATTERN, t as loadWebhookFiles, e as outgoingFromEvents };

package/dist/webhookDiscovery-D7VaeMlz.js

@@ -0,0 +1,51 @@
+import { n as e } from "./appModuleLoader-C9r9mxZt.js";
+import { asOutgoingEvent as t, isWebhookDescriptor as n } from "@voltro/plugin-webhooks";
+//#region src/webhookDiscovery.ts
+var r = /\.webhook\.tsx?$/, i = async (t, r) => {
+	let i = [], a = [], o = [];
+	for (let i of t) {
+		let t;
+		try {
+			t = await e(i);
+		} catch (e) {
+			r.warn("webhook: failed to import", { file: i }, e);
+			continue;
+		}
+		let s = (t.default && n(t.default) ? t.default : void 0) ?? Object.values(t).find(n);
+		if (!s) {
+			r.warn("webhook: no descriptor default-exported", { file: i });
+			continue;
+		}
+		switch (s._tag) {
+			case "incomingWebhook":
+				a.push({
+					file: i,
+					descriptor: s
+				});
+				break;
+			case "webhookProvider":
+				o.push({
+					file: i,
+					descriptor: s
+				});
+				break;
+		}
+	}
+	return {
+		outgoing: i,
+		incoming: a,
+		providers: o
+	};
+}, a = (e) => {
+	let n = [];
+	for (let { file: r, descriptor: i } of e) {
+		let e = t(i);
+		e !== void 0 && n.push({
+			file: r,
+			descriptor: e
+		});
+	}
+	return n;
+}, o = (e, t) => e > 0 || a(t).length > 0;
+//#endregion
+export { a as i, o as n, i as r, r as t };

package/dist/webhooksCommand-DlAgS2Iw.js

@@ -0,0 +1,267 @@
+import { i as e, n as t } from "./cliArgs-D4p8n7EE.js";
+import { t as n } from "./cliRuntime-Dh7UDinH.js";
+import { i as r, n as i, r as a } from "./schemaIr-UJybUUZW.js";
+import { isAbsolute as o, join as s, resolve as c } from "node:path";
+import { promises as l } from "node:fs";
+import { createLogger as u } from "@voltro/logger";
+import { Effect as d, JSONSchema as f } from "effect";
+//#region src/webhookConsumer.ts
+var p = (e) => {
+	switch (e.kind) {
+		case "string": return "string";
+		case "integer":
+		case "number": return "number";
+		case "boolean": return "boolean";
+		case "unknown": return "unknown";
+		case "array": return `ReadonlyArray<${p(e.element)}>`;
+		case "optional": return `${p(e.inner)} | undefined`;
+		case "ref": return e.name;
+	}
+}, m = (e) => `export type ${e.name} =\n${e.values.map((e) => `  | ${JSON.stringify(e)}`).join("\n")}`, h = (e) => {
+	let t = e.fields.map((e) => {
+		let t = e.type.kind === "optional", n = p(t ? e.type.inner : e.type);
+		return `  readonly ${/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(e.jsonName) ? e.jsonName : JSON.stringify(e.jsonName)}${t ? "?" : ""}: ${n}`;
+	});
+	return `export interface ${e.name} {\n${t.join("\n")}\n}`;
+}, g = (e) => a(e.replace(/[^A-Za-z0-9]+/g, " ").trim()) || "Event", _ = "// Generated by `voltro webhooks consumer`. Do not edit.\n//\n// Standard Webhooks v1.0.0 verification. Zero dependencies; `node:crypto` only.\n\nimport { createHmac, timingSafeEqual } from 'node:crypto'\n\nconst PREFIX = 'whsec_'\nconst DEFAULT_TOLERANCE_SECONDS = 300\n\nexport class WebhookVerificationError extends Error {\n  constructor(reason) {\n    super(`webhook verification failed: ${reason}`)\n    this.name = 'WebhookVerificationError'\n    this.reason = reason\n  }\n}\n\nconst keyBytes = (secret) => {\n  if (typeof secret !== 'string' || !secret.startsWith(PREFIX)) {\n    throw new WebhookVerificationError(\n      'the signing secret must be the \"whsec_\" + base64 form the producer issued',\n    )\n  }\n  return Buffer.from(secret.slice(PREFIX.length), 'base64')\n}\n\nconst constantTimeEq = (a, b) => {\n  const ba = Buffer.from(a, 'utf8')\n  const bb = Buffer.from(b, 'utf8')\n  if (ba.length !== bb.length) {\n    timingSafeEqual(ba, Buffer.alloc(ba.length))\n    return false\n  }\n  return timingSafeEqual(ba, bb)\n}\n\n// Accepts a Headers instance, a Node `req.headers`, or a plain object.\nconst headerValue = (headers, name) => {\n  if (headers && typeof headers.get === 'function') return headers.get(name) ?? undefined\n  if (!headers || typeof headers !== 'object') return undefined\n  for (const [k, v] of Object.entries(headers)) {\n    if (k.toLowerCase() !== name) continue\n    return Array.isArray(v) ? v[0] : v == null ? undefined : String(v)\n  }\n  return undefined\n}\n\n/**\n * Verify one delivery.\n *\n * `body` MUST be the RAW request bytes — the exact string or Buffer that\n * arrived. Re-serialising a parsed JSON object changes key order and whitespace\n * and the signature will not match. This is the single most common integration\n * failure; see the README for the per-framework raw-body recipe.\n */\nexport const createVerifier = (options) => {\n  const secrets = (Array.isArray(options?.secret) ? options.secret : [options?.secret]).filter(Boolean)\n  if (secrets.length === 0) throw new WebhookVerificationError('at least one secret is required')\n  const tolerance = options?.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS\n\n  const verify = (body, headers, now) => {\n    const id = headerValue(headers, 'webhook-id')\n    const timestampRaw = headerValue(headers, 'webhook-timestamp')\n    const signatureHeader = headerValue(headers, 'webhook-signature')\n    if (!id) throw new WebhookVerificationError('missing webhook-id')\n    if (!timestampRaw) throw new WebhookVerificationError('missing webhook-timestamp')\n    if (!signatureHeader) throw new WebhookVerificationError('missing webhook-signature')\n    if (id.includes('.')) throw new WebhookVerificationError('webhook-id contains the \".\" field delimiter')\n\n    const timestamp = Number(timestampRaw)\n    if (!Number.isInteger(timestamp)) throw new WebhookVerificationError('webhook-timestamp is not an integer')\n    const nowSeconds = now ?? Math.floor(Date.now() / 1000)\n    const skew = Math.abs(nowSeconds - timestamp)\n    if (skew > tolerance) {\n      throw new WebhookVerificationError(`timestamp outside the ${tolerance}s tolerance (off by ${skew}s)`)\n    }\n\n    const raw = Buffer.isBuffer(body) ? body : Buffer.from(String(body), 'utf8')\n    const signed = Buffer.concat([Buffer.from(`${id}.${timestamp}.`, 'utf8'), raw])\n    const offered = signatureHeader.split(' ').map((t) => t.trim()).filter(Boolean)\n\n    let matched = false\n    for (const secret of secrets) {\n      const mac = createHmac('sha256', keyBytes(secret))\n      mac.update(signed)\n      const expected = `v1,${mac.digest('base64')}`\n      for (const token of offered) {\n        if (!token.startsWith('v1,')) continue\n        if (constantTimeEq(expected, token)) { matched = true; break }\n      }\n      if (matched) break\n    }\n    if (!matched) throw new WebhookVerificationError('signature mismatch')\n\n    let payload\n    try {\n      payload = JSON.parse(raw.toString('utf8'))\n    } catch (err) {\n      throw new WebhookVerificationError(`body is not valid JSON: ${err.message}`)\n    }\n\n    return {\n      id,\n      timestamp,\n      event: headerValue(headers, 'x-voltro-event') ?? null,\n      payload,\n    }\n  }\n\n  return { verify }\n}\n", v = (e, t, n) => {
+	let r = [...n.map(m), ...t.map(h)], i = [], a = [];
+	for (let t of e) {
+		let e = `${g(t.name)}Payload`;
+		a.push(`  | { readonly event: '${t.name}'; readonly payload: ${e} }`), t.description !== void 0 && i.push(`/** ${t.description} */`);
+	}
+	return `// Generated by \`voltro webhooks consumer\`. Do not edit.
+//
+// TYPES ONLY — no decoder ships with this package. The types describe what the
+// producer sends; the SIGNATURE is what proves a delivery came from them. If
+// you want runtime validation on top, use your own validator against these
+// shapes.
+
+${r.join("\n\n")}
+
+/** Every event this producer can deliver, discriminated on \`event\`. */
+export type WebhookEvent =
+${a.length > 0 ? a.join("\n") : "  never"}
+
+export declare class WebhookVerificationError extends Error {
+  readonly reason: string
+}
+
+export interface VerifiedWebhook {
+  /** \`webhook-id\` — the producer's message id. USE THIS AS YOUR IDEMPOTENCY
+   *  KEY: retries of the same delivery repeat it, and a redelivery is expected
+   *  rather than exceptional. */
+  readonly id: string
+  /** \`webhook-timestamp\`, unix seconds. */
+  readonly timestamp: number
+  /** The event name, from \`x-voltro-event\`. \`null\` if the header is absent. */
+  readonly event: string | null
+  /** The decoded body. */
+  readonly payload: unknown
+}
+
+export interface VerifierOptions {
+  /** The endpoint's signing secret (\`whsec_…\`). Pass an ARRAY during a secret
+   *  rotation — each is tried, so both old and new deliveries verify. */
+  readonly secret: string | ReadonlyArray<string>
+  /** Replay tolerance in seconds. Default 300. */
+  readonly toleranceSeconds?: number
+}
+
+export interface Verifier {
+  /**
+   * Verify a delivery. Throws \`WebhookVerificationError\` on any failure.
+   *
+   * \`body\` MUST be the RAW bytes. Re-serialising a parsed object changes key
+   * order and whitespace, and the signature will not match.
+   */
+  verify(body: string | Uint8Array, headers: unknown, nowSeconds?: number): VerifiedWebhook
+}
+
+export declare const createVerifier: (options: VerifierOptions) => Verifier
+`;
+}, y = (e, t) => {
+	let n = e.appName ?? "the producer", r = t.length > 0 ? t.map((e) => `| \`${e.name}\` | ${e.description ?? "—"} | v${e.version ?? 1} |`).join("\n") : "| _(no outbound events declared)_ | | |";
+	return `# ${e.packageName}
+
+Webhook verification for **${n}**, generated from its own event schema by
+\`voltro webhooks consumer\`.
+
+- **Zero runtime dependencies.** \`node:crypto\` only.
+- **Standard Webhooks v1.0.0** — the same spec every conformant producer signs
+  to, so this is not a vendor-specific verifier.
+- **Node 18+** (or any runtime that provides \`node:crypto\`). Deliberately NOT
+  Web Crypto: its HMAC is async, which would make \`verify()\` return a Promise
+  and force every handler using it to be async too.
+
+## Install
+
+Copy this directory into your service, or publish it to your private registry.
+
+## Verify
+
+\`\`\`js
+import { createVerifier, WebhookVerificationError } from '${e.packageName}'
+
+const verifier = createVerifier({ secret: process.env.WEBHOOK_SECRET })
+
+app.post('/webhooks/${n.toLowerCase().replace(/[^a-z0-9]+/g, "-")}', (req, res) => {
+  let delivery
+  try {
+    delivery = verifier.verify(req.rawBody, req.headers)   // ← RAW bytes
+  } catch (err) {
+    if (err instanceof WebhookVerificationError) return res.status(401).send(err.reason)
+    throw err
+  }
+
+  // \`delivery.id\` is your idempotency key — retries repeat it.
+  if (alreadyProcessed(delivery.id)) return res.sendStatus(200)
+
+  switch (delivery.event) {
+${t.slice(0, 3).map((e) => `    case '${e.name}': /* delivery.payload */ break`).join("\n") || "    default: break"}
+  }
+  res.sendStatus(200)
+})
+\`\`\`
+
+### The raw body is the whole trap
+
+The signature covers **the exact bytes that arrived**. A JSON body-parser
+re-serialises, changing key order and whitespace, and the signature then never
+matches. Every framework has a way to keep the raw bytes:
+
+| framework | how |
+|---|---|
+| Express | \`express.json({ verify: (req, _res, buf) => { req.rawBody = buf } })\` |
+| Fastify | \`fastify.addContentTypeParser('application/json', { parseAs: 'buffer' }, (_req, body, done) => done(null, body))\` |
+| Next.js (app router) | \`await req.text()\` |
+| Hono | \`await c.req.text()\` |
+
+## What the producer sends
+
+| header | meaning |
+|---|---|
+| \`webhook-id\` | unique message id — **your idempotency key** |
+| \`webhook-timestamp\` | unix seconds; rejected outside the tolerance (default 300s) |
+| \`webhook-signature\` | \`v1,<base64>\`, space-delimited during a secret rotation |
+| \`x-voltro-event\` | the event name |
+| \`x-voltro-attempt\` | 1-based attempt counter |
+
+Answer **2xx** to accept. Anything else is a failure and will be retried; a
+\`410 Gone\` tells the producer to disable your endpoint permanently.
+
+## Events
+
+| event | description | payload version |
+|---|---|---|
+${r}
+
+Payload types are in \`index.d.ts\`. They are **types only** — no decoder ships
+here. The types describe what the producer sends; the signature is what proves
+it came from them.
+
+## Rotating the secret
+
+Pass both keys while the rotation is in flight:
+
+\`\`\`js
+createVerifier({ secret: [process.env.WEBHOOK_SECRET, process.env.WEBHOOK_SECRET_PREVIOUS] })
+\`\`\`
+`;
+}, b = (e, t) => {
+	let n = i();
+	for (let t of e) r(t.payload, `${g(t.name)}Payload`, n);
+	let a = [...n.models.values()], o = [...n.enums.values()];
+	return [
+		{
+			path: "package.json",
+			content: `${JSON.stringify({
+				name: t.packageName,
+				version: "0.0.0",
+				description: `Webhook verification for ${t.appName ?? "a Voltro app"} — generated, zero-dependency.`,
+				type: "module",
+				main: "./index.js",
+				types: "./index.d.ts",
+				exports: { ".": {
+					types: "./index.d.ts",
+					import: "./index.js",
+					default: "./index.js"
+				} },
+				files: [
+					"index.js",
+					"index.d.ts",
+					"README.md"
+				],
+				engines: { node: ">=18" },
+				private: !0
+			}, null, 2)}\n`
+		},
+		{
+			path: "index.js",
+			content: _
+		},
+		{
+			path: "index.d.ts",
+			content: v(e, a, o)
+		},
+		{
+			path: "README.md",
+			content: y(t, e)
+		}
+	];
+}, x = (e) => {
+	let t;
+	try {
+		t = f.make(e.payload);
+	} catch {
+		t = void 0;
+	}
+	return {
+		name: e.id,
+		...e.description === void 0 ? {} : { description: e.description },
+		...e.version === void 0 ? {} : { version: e.version },
+		...t === void 0 ? {} : { payload: t }
+	};
+}, S = u({ scope: "voltro:webhooks" }), C = ["--out", "--name"], w = async (e) => {
+	let { walk: t, loadDiscovered: n } = await import("./dev-D2BikO7a.js"), { outgoingFromEvents: r } = await import("./webhookDiscovery-CrGAfhIG.js");
+	return r((await n(await t(e))).events.map((e) => ({
+		file: e.file,
+		descriptor: e.descriptor
+	}))).map((e) => x(e.descriptor));
+}, T = (t, n) => {
+	let r = e(t, [...C]).find((e) => e !== "consumer" && e !== "events");
+	return r ? o(r) ? r : s(n, r) : n;
+}, E = async (e, n) => {
+	let r = T(e, n), i = await w(r);
+	if (i.length === 0) return console.error("voltro webhooks consumer: this app declares no outbound events, so there is nothing for a\n  subscriber to verify. Add a `webhook:` block to a defineEvent(), e.g.\n\n    export const orderPaid = defineEvent({\n      name: 'orders.paid',\n      key: Schema.Struct({ orderId: Schema.String }),\n      payload: Schema.Struct({ total: Schema.Number }),\n      webhook: { description: 'An order was paid' },\n    })\n"), 1;
+	let a = await O(r), o = t(e, "--name") ?? `${(a ?? "voltro-app").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "")}-webhooks`, u = c(r, t(e, "--out") ?? "webhook-consumer"), d = b(i, {
+		packageName: o,
+		...a === void 0 ? {} : { appName: a }
+	});
+	await l.mkdir(u, { recursive: !0 });
+	for (let e of d) await l.writeFile(s(u, e.path), e.content, "utf8");
+	return S.info("generated the consumer verification package", {
+		outDir: u,
+		packageName: o,
+		events: i.length,
+		dependencies: 0
+	}), console.log(`\nHand ${u} to whoever receives your webhooks.\n  ${i.length} event(s) · zero runtime dependencies · Standard Webhooks v1.0.0\n`), 0;
+}, D = async (e, t) => {
+	let n = await w(T(e, t));
+	if (e.includes("--json")) return console.log(JSON.stringify({ events: n }, null, 2)), 0;
+	if (n.length === 0) return console.log("No outbound events declared (a defineEvent() with a `webhook:` block)."), 0;
+	console.log(`\n${n.length} outbound event(s):\n`);
+	for (let e of n) console.log(`  ${e.name}  (v${e.version ?? 1})${e.description ? ` — ${e.description}` : ""}`);
+	return console.log(""), 0;
+}, O = async (e) => {
+	try {
+		let t = await l.readFile(s(e, "package.json"), "utf8"), n = JSON.parse(t).name;
+		return typeof n == "string" ? n : void 0;
+	} catch {
+		return;
+	}
+}, k = async (e, t = process.cwd()) => {
+	let r = e[0];
+	return r === "consumer" ? n(d.promise(() => E(e.slice(1), t))) : r === "events" ? n(d.promise(() => D(e.slice(1), t))) : (console.error("usage: voltro webhooks <consumer|events> [path] [--out <dir>] [--name <pkg>]\n  consumer  generate the zero-dependency verification package a subscriber installs\n  events    list the outbound events a subscriber can register for"), 1);
+};
+//#endregion
+export { k as runWebhooksCommand };