primitive-admin 1.0.61 → 1.0.62

package/dist/src/commands/webhooks.js

@@ -1,7 +1,19 @@
+import { readFileSync, statSync } from "fs";
 import { ApiClient } from "../lib/api-client.js";
 import { resolveAppId } from "../lib/config.js";
-import { success, error, info, keyValue, result as printResult, formatTable, formatId, formatDate, formatStatus, json, divider, } from "../lib/output.js";
+import { success, error, info, keyValue, result as printResult, formatTable, formatId, formatDate, formatStatus, json, divider, dim, warn, } from "../lib/output.js";
+import { assertSupportedFlags, buildWebhookEnvelope, } from "../lib/log-inspection.js";
 import { confirmPrompt } from "../lib/confirm-prompt.js";
+import { parseStatusFilter } from "../lib/object-status-filter.js";
+import { signingSecretStatusWarning, signingSecretHealthWarning, previousSigningSecretWarning, formatGracePeriodMs, } from "../lib/signing-secret-status.js";
+import { fetchAll } from "./sync.js";
+/**
+ * Platform ceiling on a webhook body (`MAX_WEBHOOK_BODY_BYTES_LIMIT`, 25 MiB).
+ * A per-webhook cap can be lower — that one is the server's call and comes back
+ * as a `body_too_large` verdict. This bound only stops the CLI from reading and
+ * encoding a file no webhook could ever accept.
+ */
+const MAX_VERIFY_BODY_BYTES = 25 * 1024 * 1024;
 export function registerWebhooksCommands(program) {
     const webhooks = program
         .command("webhooks")
@@ -9,11 +21,23 @@ export function registerWebhooksCommands(program) {
         .addHelpText("after", `
 Examples:
   $ primitive webhooks list
-  $ primitive webhooks create --key stripe-events --name "Stripe Events" --workflow-key process-stripe --scheme hmac-sha256
+  $ primitive secrets set STRIPE_WEBHOOK_SECRET --value whsec_...
+  $ primitive config create webhook stripe-events   # then edit webhooks/stripe-events.toml and: primitive config push
   $ primitive webhooks get 01HXY...
-  $ primitive webhooks rotate-secret 01HXY... --secret newsecret123
+  $ primitive webhooks rotate-secret 01HXY... --secret "{{secrets.STRIPE_WEBHOOK_SECRET_NEXT}}"
   $ primitive webhooks events 01HXY...
+  $ primitive webhooks archive 01HXY...   # retire it (soft delete)
   $ primitive webhooks test 01HXY... --payload '{"event":"test"}'
+  $ primitive webhooks verify 01HXY... --header 'Stripe-Signature: t=...,v1=...' --body-file captured.json
+`);
+    // Server-side configuration is authored in TOML and applied with `config push`
+    // (issue #2645) — this group no longer carries config-setting flags.
+    webhooks.addHelpText("after", `
+Configuration lives in webhooks/<key>.toml:
+  $ primitive config fields webhook        # the file's keys, types and defaults
+  $ primitive config create webhook <key>  # scaffold one locally
+  $ primitive config set webhook/<key> <path>=<value>
+  $ primitive config push --only webhook/<key>
 `);
     // List webhooks
     webhooks
@@ -21,15 +45,27 @@ Examples:
         .description("List webhooks")
         .argument("[app-id]", "App ID (uses current app if not specified)")
         .option("--app <app-id>", "App ID")
-        .option("--status <status>", "Filter by status: active, paused, archived")
+        .option("--status <status>", "Filter by status: active, inactive, archived")
         .option("--json", "Output as JSON")
         .action(async (appId, options) => {
         const resolvedAppId = resolveAppId(appId, options);
         const client = new ApiClient();
         try {
-            const { items } = await client.listWebhooks(resolvedAppId, {
-                status: options.status,
-            });
+            // #2803 — `paused` is gone; refuse it by name rather than returning the
+            // empty list a canonical filter would produce.
+            const status = parseStatusFilter("webhooks", options.status, [
+                "active",
+                "inactive",
+                "archived",
+            ]);
+            // Drain every page (#2232). The admin list endpoint pages at 25 by
+            // default, so an app anywhere near the per-app webhook cap of 50 was
+            // silently truncated here — and this is the command an operator uses to
+            // find a webhook to hard-delete when a create is refused at the cap.
+            const items = await fetchAll((params) => client.listWebhooks(resolvedAppId, {
+                ...params,
+                status,
+            }));
             if (options.json) {
                 json(items);
                 return;
@@ -52,81 +88,6 @@ Examples:
             process.exit(1);
         }
     });
-    // Create webhook
-    webhooks
-        .command("create")
-        .description("Create a new webhook")
-        .argument("[app-id]", "App ID (uses current app if not specified)")
-        .option("--app <app-id>", "App ID")
-        .option("--key <key>", "Webhook key (unique identifier)")
-        .option("--name <name>", "Display name")
-        .option("--workflow-key <wfKey>", "Workflow key to trigger")
-        .option("--scheme <scheme>", "Verification scheme (e.g., hmac-sha256, none)")
-        .option("--secret <secret>", "Signing secret")
-        .option("--status <status>", "Status: active, paused (default: active)")
-        .option("--description <desc>", "Description")
-        .option("--tolerance-seconds <n>", "Timestamp tolerance in seconds")
-        .option("--no-dedup", "Disable deduplication")
-        .option("--dedup-window-ms <n>", "Deduplication window in milliseconds")
-        .option("--allowed-ips <cidrs...>", "Allowed IP CIDRs")
-        .option("--input-mapping <json>", "Input mapping as JSON")
-        .option("--json", "Output as JSON")
-        .action(async (appId, options) => {
-        const resolvedAppId = resolveAppId(appId, options);
-        const client = new ApiClient();
-        if (!options.key || !options.name || !options.workflowKey || !options.scheme) {
-            error("Required: --key, --name, --workflow-key, --scheme");
-            process.exit(1);
-        }
-        const payload = {
-            webhookKey: options.key,
-            displayName: options.name,
-            workflowKey: options.workflowKey,
-            verificationScheme: options.scheme,
-            // Default new webhooks to active so they accept inbound deliveries
-            // immediately. The server also defaults to active, but sending an
-            // explicit status keeps create self-describing.
-            status: options.status || "active",
-        };
-        if (options.secret)
-            payload.signingSecret = options.secret;
-        if (options.description)
-            payload.description = options.description;
-        if (options.toleranceSeconds)
-            payload.toleranceSeconds = parseInt(options.toleranceSeconds);
-        if (options.dedup === false)
-            payload.deduplicationEnabled = false;
-        if (options.dedupWindowMs)
-            payload.deduplicationWindowMs = parseInt(options.dedupWindowMs);
-        if (options.allowedIps)
-            payload.allowedIpCidrs = options.allowedIps;
-        if (options.inputMapping) {
-            try {
-                payload.inputMapping = JSON.parse(options.inputMapping);
-            }
-            catch {
-                error("Invalid JSON in --input-mapping");
-                process.exit(1);
-            }
-        }
-        try {
-            const result = await client.createWebhook(resolvedAppId, payload);
-            if (options.json) {
-                json(result);
-                return;
-            }
-            success(`Webhook created: ${result.displayName}`);
-            keyValue("Webhook ID", result.webhookId);
-            keyValue("Key", result.webhookKey);
-            keyValue("Workflow", result.workflowKey);
-            keyValue("Scheme", result.verificationScheme);
-        }
-        catch (err) {
-            error(err.message);
-            process.exit(1);
-        }
-    });
-    // Get webhook
     webhooks
         .command("get")
         .description("Get webhook details")
@@ -149,13 +110,44 @@ Examples:
             printResult("Status", formatStatus(result.status));
             printResult("Workflow Key", result.workflowKey);
             printResult("Verification Scheme", result.verificationScheme);
-            printResult("Signing Secret", result.signingSecretMasked || "-");
+            printResult("Signing Secret", result.signingSecret || "-");
+            printResult("Previous Signing Secret", result.previousSigningSecret || "-");
+            // The grace slot's own status, so an operator can tell "no previous
+            // key" from "a raw value is still live there" — both print the previous
+            // secret as `-`, because a withheld value is never echoed (#2383).
+            printResult("Previous Signing Secret Status", result.previousSigningSecretStatus || "-");
+            // A stored value that is not a reference is never echoed, so say what
+            // it is here rather than showing an empty field: a legacy literal from
+            // before reference-only still verifies deliveries, a malformed
+            // reference does not (#2332). Same wording as `config pull`.
+            const signingSecretWarning = signingSecretStatusWarning(result.signingSecretStatus, {
+                subject: "Signing secret",
+                blocks: "this webhook cannot be updated or rotated",
+            });
+            if (signingSecretWarning)
+                warn(signingSecretWarning);
+            // The grace slot gets its own line: a raw value there keeps verifying
+            // deliveries even though the row's current slot reads as migrated
+            // (#2383). The lever is the grace period, not a migration.
+            const previousWarning = previousSigningSecretWarning(result.previousSigningSecretStatus, { subject: "Previous signing secret" });
+            if (previousWarning)
+                warn(previousWarning);
+            // The health axis, per slot — anything that is not `ok`.
+            const healthWarning = signingSecretHealthWarning(result.signingSecretHealth, { subject: "Signing secret" });
+            if (healthWarning)
+                warn(healthWarning);
+            const previousHealthWarning = signingSecretHealthWarning(result.previousSigningSecretHealth, { subject: "Previous signing secret" });
+            if (previousHealthWarning)
+                warn(previousHealthWarning);
             divider();
             info("Configuration:");
             printResult("  Tolerance Seconds", String(result.toleranceSeconds ?? "-"));
             printResult("  Deduplication", result.deduplicationEnabled ? "enabled" : "disabled");
             printResult("  Dedup Window", result.deduplicationWindowMs ? `${result.deduplicationWindowMs}ms` : "-");
-            printResult("  Grace Period", result.secretGracePeriodMs ? `${result.secretGracePeriodMs}ms` : "-");
+            printResult("  Max Body Bytes", result.maxBodyBytes ? `${result.maxBodyBytes}` : "default (5 MiB)");
+            // Not a truthiness test: a stored `0` means immediate cutover, which is
+            // the opposite of the unset case's 24 h default (#2383).
+            printResult("  Grace Period", formatGracePeriodMs(result.secretGracePeriodMs));
             printResult("  Allowed IPs", result.allowedIpCidrs || "-");
             printResult("  Input Mapping", result.inputMapping || "-");
             divider();
@@ -168,113 +160,121 @@ Examples:
             process.exit(1);
         }
     });
-    // Update webhook
+    // #2645 criterion 9 / #2803 — the operational verbs. They are the only
+    // writers of `status`, which is server-owned and no longer a `[webhook]`
+    // TOML key: `config push` can neither set nor clear it, so pushing a file
+    // pulled before a pause no longer puts the endpoint back in service.
     webhooks
-        .command("update")
-        .description("Update a webhook")
+        .command("disable")
+        .description("Take a webhook out of service now. Inbound deliveries are refused with a 410; the committed configuration is unchanged.")
         .argument("<webhook-id>", "Webhook ID")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
-        .option("--name <name>", "Display name")
-        .option("--description <desc>", "Description")
-        .option("--status <status>", "Status: active, paused")
-        .option("--scheme <scheme>", "Verification scheme")
-        .option("--workflow-key <wfKey>", "Workflow key to trigger")
-        .option("--tolerance-seconds <n>", "Timestamp tolerance in seconds")
-        .option("--no-dedup", "Disable deduplication")
-        .option("--dedup-window-ms <n>", "Deduplication window in milliseconds")
-        .option("--allowed-ips <cidrs...>", "Allowed IP CIDRs")
-        .option("--grace-period-ms <n>", "Secret grace period in milliseconds")
-        .option("--input-mapping <json>", "Input mapping as JSON")
         .option("--json", "Output as JSON")
         .action(async (webhookId, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
-        const payload = {};
-        if (options.name)
-            payload.displayName = options.name;
-        if (options.description)
-            payload.description = options.description;
-        if (options.status)
-            payload.status = options.status;
-        if (options.scheme)
-            payload.verificationScheme = options.scheme;
-        if (options.workflowKey)
-            payload.workflowKey = options.workflowKey;
-        if (options.toleranceSeconds)
-            payload.toleranceSeconds = parseInt(options.toleranceSeconds);
-        if (options.dedup === false)
-            payload.deduplicationEnabled = false;
-        if (options.dedupWindowMs)
-            payload.deduplicationWindowMs = parseInt(options.dedupWindowMs);
-        if (options.allowedIps)
-            payload.allowedIpCidrs = options.allowedIps;
-        if (options.gracePeriodMs)
-            payload.secretGracePeriodMs = parseInt(options.gracePeriodMs);
-        if (options.inputMapping) {
-            try {
-                payload.inputMapping = JSON.parse(options.inputMapping);
-            }
-            catch {
-                error("Invalid JSON in --input-mapping");
-                process.exit(1);
+        const client = new ApiClient();
+        try {
+            const result = await client.setWebhookAvailability(resolvedAppId, webhookId, "disable");
+            if (options.json) {
+                json(result);
+                return;
             }
+            success(`Webhook disabled: ${result.webhookKey || webhookId}`);
+            info("Deliveries are refused with a 410 — `primitive webhooks enable` puts it back.");
         }
-        if (Object.keys(payload).length === 0) {
-            error("No update options specified.");
+        catch (err) {
+            error(err.message);
             process.exit(1);
         }
+    });
+    webhooks
+        .command("enable")
+        .description("Put a webhook back in service.")
+        .argument("<webhook-id>", "Webhook ID")
+        .option("--app <app-id>", "App ID (uses current app if not specified)")
+        .option("--json", "Output as JSON")
+        .action(async (webhookId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
         const client = new ApiClient();
         try {
-            const result = await client.updateWebhook(resolvedAppId, webhookId, payload);
+            const result = await client.setWebhookAvailability(resolvedAppId, webhookId, "enable");
             if (options.json) {
                 json(result);
                 return;
             }
-            success("Webhook updated.");
+            success(`Webhook enabled: ${result.webhookKey || webhookId}`);
         }
         catch (err) {
             error(err.message);
             process.exit(1);
         }
     });
-    // Delete webhook
+    // #2907 — the delete flow's CLI spelling. Not a second writer of `status`:
+    // this is the plain `DELETE` the server has always answered by writing the
+    // tombstone, which until now only the admin API and the console could reach.
+    // Named `archive`, not `delete`, because a configuration noun gets no
+    // `delete` verb (docs/cli-design.md) and prune-by-push stays the only CLI
+    // hard-delete path.
     webhooks
-        .command("delete")
-        .description("Delete a webhook")
+        .command("archive")
+        .description("Retire a webhook (soft delete). Delete-lifecycle, not `disable`: the row is kept, keeps its key and its capped slot, and there is no un-archive.")
         .argument("<webhook-id>", "Webhook ID")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
         .option("-y, --yes", "Skip confirmation prompt")
+        .option("--json", "Output as JSON")
+        .addHelpText("after", `
+What archiving a webhook costs:
+  Inbound deliveries are refused, as they are for a disabled webhook.
+  The archived row still holds its webhookKey AND its slot under the per-app
+  webhook cap (50) — archiving frees neither, which is why an archived row a
+  delivery still reaches is not free.
+  \`primitive webhooks enable\` refuses an archived webhook; there is no
+  un-archive.
+
+Reclaiming the key and the slot means hard-deleting the row:
+  $ rm webhooks/<key>.toml
+  $ primitive config push --prune     # confirmed; hard-deletes the row
+  # or hard-delete it in the console, then re-add the file and push.
+`)
         .action(async (webhookId, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         if (!options.yes) {
-            let confirm;
+            let confirmed;
             try {
-                confirm = await confirmPrompt(`Are you sure you want to delete webhook ${webhookId}?`);
+                confirmed = await confirmPrompt(`Archive webhook ${webhookId}? Deliveries stop, the row keeps its key ` +
+                    `and its capped slot, and there is no un-archive.`);
             }
             catch (err) {
                 error(err.message);
                 process.exit(1);
             }
-            if (!confirm) {
+            if (!confirmed) {
                 info("Cancelled.");
                 return;
             }
         }
         const client = new ApiClient();
         try {
-            await client.deleteWebhook(resolvedAppId, webhookId);
-            success("Webhook deleted.");
+            // The soft delete: no `hard`, so the server writes the tombstone. The
+            // `--hard` path stays out of the CLI surface — prune-by-push owns it.
+            const result = await client.deleteWebhook(resolvedAppId, webhookId);
+            if (options.json) {
+                json(result);
+                return;
+            }
+            success(`Webhook archived: ${webhookId}`);
+            info("Deliveries are refused. The row still holds its key and its capped slot — reclaim both by removing its file and running a confirmed `primitive config push --prune`.");
         }
         catch (err) {
             error(err.message);
             process.exit(1);
         }
     });
-    // Rotate secret
     webhooks
         .command("rotate-secret")
         .description("Rotate the signing secret for a webhook")
         .argument("<webhook-id>", "Webhook ID")
-        .requiredOption("--secret <new-secret>", "New signing secret")
+        .requiredOption("--secret <ref>", "New signing secret, as a {{secrets.KEY}} reference to an app secret")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
         .option("--json", "Output as JSON")
         .action(async (webhookId, options) => {
@@ -288,9 +288,15 @@ Examples:
                 json(result);
                 return;
             }
+            // Rotation now returns the serialized webhook on both surfaces, and
+            // both references are plain text (the secret values live only in the
+            // secret store), so print them rather than a masked value.
             success("Signing secret rotated.");
-            if (result.signingSecretMasked) {
-                keyValue("Secret (masked)", result.signingSecretMasked);
+            if (result.signingSecret) {
+                keyValue("Signing Secret", result.signingSecret);
+            }
+            if (result.previousSigningSecret) {
+                keyValue("Previous Signing Secret", result.previousSigningSecret);
             }
         }
         catch (err) {
@@ -305,24 +311,41 @@ Examples:
         .argument("<webhook-id>", "Webhook ID")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
         .option("--limit <n>", "Number of events to show", "20")
+        .option("--cursor <cursor>", "Pagination cursor from a previous page")
+        // Declared so they can be rejected with a clear message instead of being
+        // silently ignored — status/time filtering on webhook events is deferred to
+        // Phase B (issue #1967). See assertSupportedFlags below.
+        .option("--status <status>", "(not supported yet — deferred to Phase B)")
+        .option("--from <iso>", "(not supported yet — deferred to Phase B)")
+        .option("--to <iso>", "(not supported yet — deferred to Phase B)")
         .option("--json", "Output as JSON")
         .action(async (webhookId, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         const client = new ApiClient();
         try {
-            const result = await client.listWebhookEvents(resolvedAppId, webhookId, {
+            // The webhook-events route serves limit + cursor only; reject the
+            // Phase B filters cleanly rather than dropping them silently.
+            assertSupportedFlags("webhook events", { status: options.status, from: options.from, to: options.to }, ["limit", "cursor"]);
+            const page = await client.listWebhookEvents(resolvedAppId, webhookId, {
                 limit: parseInt(options.limit),
+                ...(options.cursor && { cursor: options.cursor }),
             });
-            const events = result?.items ?? result ?? [];
             if (options.json) {
-                json(events);
+                json(buildWebhookEnvelope(page.items, page));
                 return;
             }
-            if (!events || events.length === 0) {
+            const printCursorHint = () => {
+                if (!page.nextCursor)
+                    return;
+                console.log();
+                dim(`More events. Use --cursor ${page.nextCursor} for the next page.`);
+            };
+            if (!page.items || page.items.length === 0) {
                 info("No events found.");
+                printCursorHint();
                 return;
             }
-            console.log(formatTable(events, [
+            console.log(formatTable(page.items, [
                 { header: "EVENT ID", key: "eventId", format: formatId },
                 { header: "EXTERNAL ID", key: "externalEventId" },
                 { header: "STATUS", key: "status", format: formatStatus },
@@ -330,6 +353,7 @@ Examples:
                 { header: "REASON", key: "rejectionReason" },
                 { header: "CREATED", key: "createdAt", format: formatDate },
             ]));
+            printCursorHint();
         }
         catch (err) {
             error(err.message);
@@ -339,18 +363,23 @@ Examples:
     // Test webhook
     webhooks
         .command("test")
-        .description("Send a test payload to a webhook")
+        .description("Sign a test payload for a webhook (returns body + headers)")
         .argument("<webhook-id>", "Webhook ID")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
-        .option("--payload <json>", "Test payload as JSON, delivered and signed verbatim. Pass the event " +
+        .option("--payload <json>", "Test payload as JSON, signed verbatim. Pass the event " +
         "object directly (e.g. '{\"type\":\"event\",\"data\":{…}}'); it is used " +
-        "as-is. Omit it to send a canned webhook.test ping.")
+        "as-is. Omit it to sign a canned webhook.test ping.")
         .option("--json", "Output as JSON")
         .addHelpText("after", `
-The value of --payload is delivered and signed exactly as given (WYSIWYG). A
-JSON object is used as the test body verbatim, so a wrapped payload such as
-'{"payload":{…}}' now delivers the literal wrapper — do not wrap the event.
-Omitting --payload (or passing a non-object such as an array) sends the canned
+This command signs a payload and prints the signature headers and the signed
+body. It does NOT post them to the webhook's receive endpoint, so no workflow
+runs and no delivery is recorded — send the returned body with the returned
+headers to POST /app/{appId}/webhook/{webhookKey} yourself to do that.
+
+The value of --payload is signed exactly as given (WYSIWYG). A JSON object is
+used as the test body verbatim, so a wrapped payload such as '{"payload":{…}}'
+signs the literal wrapper — do not wrap the event. Omitting --payload (or
+passing a non-object such as an array) signs the canned
 {"type":"webhook.test", …} ping.
 `)
         .action(async (webhookId, options) => {
@@ -373,7 +402,9 @@ Omitting --payload (or passing a non-object such as an array) sends the canned
                 return;
             }
             if (result.success) {
-                success("Test webhook delivered successfully.");
+                success("Test payload signed. Nothing was delivered — post the signed body " +
+                    "(--json shows the exact rawBody) with these headers to the " +
+                    "receive endpoint to trigger the workflow.");
                 if (result.signatureHeaders) {
                     divider();
                     info("Generated Signature Headers:");
@@ -392,7 +423,138 @@ Omitting --payload (or passing a non-object such as an array) sends the canned
             }
         }
         catch (err) {
-            error(err.message);
+            // The server refuses a preview it cannot sign with a coded 400 — the
+            // scheme holds only public key material, the row still stores a raw
+            // secret, the signing secret is unset or unresolvable (#2445). Print
+            // the machine-readable code alongside the message, the established
+            // convention here: the prose explains, the code is what an operator
+            // searches for or reports.
+            error(err?.code ? `${err.message} (${err.code})` : err.message);
+            process.exit(1);
+        }
+    });
+    // Verify a captured delivery's signature
+    webhooks
+        .command("verify")
+        .description("Check whether signature headers you captured verify against a webhook")
+        .argument("<webhook-id>", "Webhook ID")
+        .option("--app <app-id>", "App ID (uses current app if not specified)")
+        .option("--header <name: value>", "A header from the captured delivery. Repeatable.", (value, previous) => [...(previous || []), value], [])
+        .option("--body <text>", "The captured delivery body, as text")
+        .option("--body-file <path>", "Read the captured delivery body from a file")
+        .option("--json", "Output as JSON")
+        .addHelpText("after", `
+Runs the webhook's configured verifier over the body and headers you supply and
+reports whether that signature checks out — the useful question when a real
+delivery was rejected 401, and the only way to check a scheme the platform holds
+only public key material for (discord, jwt, plaid), which \`webhooks test\`
+cannot preview.
+
+Nothing is delivered: no workflow runs, and no delivery is recorded (this check
+never appears in \`primitive webhooks events\`).
+
+It answers SIGNATURE verification only. A real delivery is also subject to the
+webhook's status and IP allowlist before verification, and to handshake rules
+and deduplication after it.
+
+Exits 0 when the signature verifies and non-zero otherwise, so it composes in a
+script.
+
+  $ primitive webhooks verify 01HXY... \\
+      --header 'Stripe-Signature: t=1754...,v1=abc...' \\
+      --body-file captured-delivery.json
+`)
+        .action(async (webhookId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        if (options.body !== undefined && options.bodyFile !== undefined) {
+            error("Pass --body or --body-file, not both.");
+            process.exit(1);
+        }
+        let rawBody;
+        let bodyBase64;
+        if (options.bodyFile !== undefined) {
+            let bytes;
+            try {
+                // Size first: a mistakenly-passed large file should be a clear CLI
+                // error rather than a buffer the command tries to base64 and ship.
+                const { size } = statSync(options.bodyFile);
+                if (size > MAX_VERIFY_BODY_BYTES) {
+                    error(`--body-file is ${size} bytes, over the ${MAX_VERIFY_BODY_BYTES}-byte platform maximum for a webhook body. A delivery that large is refused before its signature is checked.`);
+                    process.exit(1);
+                    return;
+                }
+                bytes = readFileSync(options.bodyFile);
+            }
+            catch (err) {
+                error(`Could not read --body-file: ${err.message}`);
+                process.exit(1);
+                return;
+            }
+            // A signature is over BYTES. Decoding a capture that is not valid
+            // UTF-8 replaces each bad byte with U+FFFD, so sending it as `rawBody`
+            // would check the signature against bytes the provider never sent and
+            // report a confident `sig_invalid` — the wrong answer in exactly the
+            // case this command exists for. `bodyBase64` carries those bytes
+            // intact, so only a body that round-trips losslessly goes as text.
+            const asText = bytes.toString("utf-8");
+            if (Buffer.from(asText, "utf-8").equals(bytes)) {
+                rawBody = asText;
+            }
+            else {
+                bodyBase64 = bytes.toString("base64");
+            }
+        }
+        else {
+            // An empty body is a legitimate delivery, so an omitted --body means
+            // "the delivery carried no body" rather than "no body was supplied".
+            rawBody = options.body ?? "";
+        }
+        // Ordered pairs, not an object: a real capture can carry the same field
+        // name on more than one line, which an object cannot represent.
+        const headers = [];
+        for (const entry of (options.header || [])) {
+            const separator = entry.indexOf(":");
+            if (separator <= 0) {
+                error(`Invalid --header '${entry}'. Use 'Name: value'.`);
+                process.exit(1);
+            }
+            headers.push([
+                entry.slice(0, separator).trim(),
+                entry.slice(separator + 1).trim(),
+            ]);
+        }
+        const client = new ApiClient();
+        try {
+            const result = await client.verifyWebhook(resolvedAppId, webhookId, {
+                headers,
+                // Exactly one body form — the server refuses a request naming both.
+                ...(bodyBase64 !== undefined ? { bodyBase64 } : { rawBody }),
+            });
+            if (options.json) {
+                json(result);
+            }
+            else if (result.verified) {
+                success("Signature verified.");
+                keyValue("  Scheme", String(result.verificationScheme));
+                if (result.dedupKey)
+                    keyValue("  Dedup key", String(result.dedupKey));
+                if (result.externalEventId) {
+                    keyValue("  Event ID", String(result.externalEventId));
+                }
+            }
+            else {
+                error("Signature did NOT verify.");
+                keyValue("  Scheme", String(result.verificationScheme));
+                keyValue("  Reason", String(result.rejectionReason || "unknown"));
+            }
+            if (result.webhookStatus && result.webhookStatus !== "active") {
+                warn(`This webhook is ${result.webhookStatus} — a live delivery would be refused before its signature was checked.`);
+            }
+            if (!result.verified)
+                process.exit(1);
+        }
+        catch (err) {
+            error(err?.code ? `${err.message} (${err.code})` : err.message);
             process.exit(1);
         }
     });