@voltro/plugin-webhooks 0.33.0 → 0.35.0

package/dist/index.d.ts

@@ -8,8 +8,10 @@ import { EventDescriptor } from '@voltro/protocol';
 import { EventWebhookSpec } from '@voltro/protocol';
 import { FieldDefinitions } from '@voltro/database';
 import { OutboxHandlerDefinition } from '@voltro/runtime';
+import { PluginPermission } from '@voltro/protocol';
 import { Schema } from 'effect';
 import { Table } from '@voltro/database';
+import { VoltroPlugin } from '@voltro/protocol';
 import { Workflow } from '@effect/workflow';
 import { WorkflowEngine } from '@effect/workflow/WorkflowEngine';
 import { WorkflowInstance } from '@effect/workflow/WorkflowEngine';
@@ -93,7 +95,10 @@ export declare interface CustomSignatureScheme {
     readonly _tag: 'custom';
     readonly header: string;
     readonly sign: (rawBody: Uint8Array, secret: string) => string;
-    readonly verify: (rawBody: Uint8Array, secret: string, signatureHeader: string) => boolean;
+    /** Verify against the request's FULL header map (lowercased keys) — a scheme
+     *  whose timestamp lives in a second header can read it here instead of
+     *  relying on a caller to splice the two values together. */
+    readonly verify: (rawBody: Uint8Array, secret: string, headers: Readonly<Record<string, string>>) => boolean;
 }
 
 /** The structural slice of a `defineEvent` descriptor this plugin needs.
@@ -117,8 +122,17 @@ export declare interface DeclaredEventLike {
  *  register routes. */
 export declare const defaultIncomingPath: (webhookId: string) => `/${string}`;
 
-/** Generic HMAC-SHA-256 — sensible default for new outgoing webhooks. */
-export declare const defaultOutgoingSignature: () => HmacSignatureScheme;
+/**
+ * The DEFAULT for a new outgoing subscription: Standard Webhooks v1.0.0.
+ *
+ * An interoperable spec beats a house format for the one signature shape a
+ * third party has to implement against. Every Standard-Webhooks consumer
+ * library — and the package `voltro webhooks consumer` generates — verifies
+ * these deliveries with no per-vendor code. That is the whole argument for a
+ * spec, and it only pays if the spec is what we send by DEFAULT rather than
+ * what you can opt into.
+ */
+export declare const defaultOutgoingSignature: () => StandardWebhooksSignatureScheme;
 
 /** Sensible default for new outgoing subscriptions: exponential, 8
  *  attempts, 5s → 1h. Roughly: 5s, 10s, 20s, 40s, 80s, 160s, 320s,
@@ -154,7 +168,16 @@ declare interface DeliverInput {
     readonly attemptEpoch?: number;
 }
 
-export declare const deliverWebhookWorkflow: Workflow.Workflow<"voltro.deliverWebhook", Workflow.AnyStructSchema | Schema.Struct<Schema.Struct.Fields>, Schema.Struct<{
+export declare const deliverWebhookWorkflow: Workflow.Workflow<"voltro.deliverWebhook", Schema.Struct<{
+    deliveryId: typeof Schema.String;
+    targetId: typeof Schema.String;
+    event: typeof Schema.String;
+    eventId: typeof Schema.String;
+    payloadJson: typeof Schema.String;
+    attemptEpoch: Schema.optionalWith<typeof Schema.Number, {
+        default: () => number;
+    }>;
+}>, Schema.Struct<{
     finalStatus: Schema.Literal<["succeeded", "failed", "deferred"]>;
     attempts: typeof Schema.Number;
 }>, typeof Schema.Never>;
@@ -168,6 +191,17 @@ declare interface DeliverWorkflowOptions {
     /** The fixed window backing "per minute" — injectable for tests
      *  (production uses the 60s default). */
     readonly rateWindowMs?: number;
+    /**
+     * Per-attempt wire timeout, milliseconds. Default 30 000.
+     *
+     * There was no timeout at all before this, so one receiver that accepted the
+     * connection and never answered held a durable workflow — and its rate-limit
+     * slot — indefinitely. Standard Webhooks recommends "somewhere between 15 and
+     * 30s"; the top of that band is the default because a slow-but-alive receiver
+     * being cut off produces a retry storm, which is the worse of the two
+     * failures. Also settable per deployment with `VOLTRO_WEBHOOK_TIMEOUT_MS`.
+     */
+    readonly timeoutMs?: number;
 }
 
 /** `getDelivery` adds the two heavy columns `listDeliveries` omits. */
@@ -282,6 +316,26 @@ export declare const fastRetryPolicy: () => RetryPolicy;
 
 export declare const generateSecret: () => string;
 
+/**
+ * Mint a spec-shaped signing secret: `whsec_` + base64 of 32 random bytes.
+ *
+ * 32 bytes sits inside the spec's 24..64 band and matches the SHA-256 block
+ * this key feeds. Per the spec, keys "should be unique per endpoint" — which is
+ * already how `subscribe` mints them.
+ */
+export declare const generateStandardWebhooksSecret: () => string;
+
+/**
+ * The house HMAC shape: `X-Webhook-Signature: t=NNN,v1=hex` over
+ * `<timestamp>.<body>`.
+ *
+ * Kept as a named CHOICE, not as a default and not as a fallback: a receiver
+ * that already implemented this exact format should not have to change to keep
+ * receiving. It is a peer of `stripeSignature()` / `githubSignature()` — a
+ * specific counterparty's format — rather than a second general-purpose path.
+ */
+export declare const genericHmacSignature: () => HmacSignatureScheme;
+
 export declare const getIdempotencyCache: () => IdempotencyCache;
 
 /** GitHub-style: `X-Hub-Signature-256: sha256=hex` (no timestamp). */
@@ -402,11 +456,24 @@ export declare interface IncomingWebhookDescriptor<Body> {
      *  integrations (`/integrations/stripe/v1`). */
     readonly path?: `/${string}`;
     /** Signature scheme used to authenticate inbound requests. Reject
-     *  on mismatch with a 401. `undefined` (the default) means NO
-     *  verification — only acceptable when behind a separate trust
-     *  boundary (gateway + IP allow-list). The dashboard surfaces a
-     *  warning for unsigned incoming webhooks. */
+     *  on mismatch with a 401. Usually filled in by `provider`. */
     readonly signature?: SignatureScheme;
+    /**
+     * How this endpoint authenticates its caller. An incoming webhook is a
+     * PUBLIC POST that runs your application code, so the framework will not
+     * mount one that has made no decision here: `mountIncomingWebhook` throws
+     * at boot when there is no effective `signature` (from this descriptor or
+     * from `provider`) AND no explicit value below.
+     *
+     *  - omitted → derived. `signature` / `provider` present → `'signature'`;
+     *    nothing present → boot refuses.
+     *  - `'provider'` → the handler verifies with the provider's own SDK
+     *    (Stripe's `constructEvent`, etc.). The framework's generic HMAC layer
+     *    is not the authority and does not require a framework-side secret.
+     *  - `'none'` → deliberately unverified, because a gateway + IP allow-list
+     *    owns the trust boundary. Logged as a warning at every boot, on purpose.
+     */
+    readonly verification?: 'signature' | 'provider' | 'none';
     /** Idempotency key extraction. Default `'Idempotency-Key'` header.
      *  Provider-templates override this to match the provider's wire
      *  format. */
@@ -434,6 +501,26 @@ export declare interface IncomingWebhookDescriptor<Body> {
     readonly handler: (context: IncomingWebhookContext<Body>) => Promise<void> | void;
 }
 
+/** How a mounted incoming webhook authenticates its caller. Mirrors
+ *  `@voltro/runtime`'s `WebhookVerification` STRUCTURALLY — this package must
+ *  not depend on the runtime (it is imported by browser-safe descriptor files),
+ *  and the runtime reads the stamped value back by shape. */
+export declare type IncomingWebhookVerification = 'signature' | 'provider' | 'none';
+
+/**
+ * The verification decision for a descriptor, WITHOUT mounting it.
+ *
+ * One function, two readers: `mountIncomingWebhook` (which turns `null` into a
+ * boot refusal) and `voltro doctor` (which reports it as a preflight, before a
+ * deploy discovers it). A doctor that re-derived this could disagree with the
+ * boot it is supposed to predict — the failure shape a preflight must not have.
+ *
+ * `null` = nothing authenticates the caller. Declaring nothing, and declaring
+ * `'signature'` with no scheme to verify AGAINST, are the same open endpoint,
+ * so both answer `null`.
+ */
+export declare const incomingWebhookVerification: <Body>(descriptor: IncomingWebhookDescriptor<Body>) => IncomingWebhookVerification | null;
+
 export declare interface IncomingWorkflowFacade {
     start<Payload = unknown>(workflowName: string, payload: Payload): Promise<WorkflowRunHandle>;
     signal(target: {
@@ -458,6 +545,9 @@ export declare interface IncomingWorkflowFacade {
     }>;
 }
 
+/** Is this a spec-shaped secret? Used to decide whether a target needs one minted. */
+export declare const isStandardWebhooksSecret: (secret: string) => boolean;
+
 /** Type guard for file-walker discovery — every `*.webhook.tsx`
  *  must default-export one of these. */
 export declare const isWebhookDescriptor: (value: unknown) => value is WebhookDescriptor;
@@ -519,16 +609,24 @@ emitter: () => Pick<WebhooksServiceShape, "emit"> | undefined) => OutboxHandlerD
  */
 export declare const matchesFilter: (filter: WebhookFilter | Readonly<Record<string, unknown>> | null, payload: unknown) => boolean;
 
+/** A mounted handler, carrying its verification declaration. */
+export declare type MountedIncomingWebhook = ((request: IncomingRequest) => Promise<IncomingResponse>) & {
+    readonly [WEBHOOK_VERIFICATION_PROPERTY]: IncomingWebhookVerification;
+};
+
 /**
  * Build a request handler for a specific `IncomingWebhookDescriptor`.
  * The returned function is what stage 4 mounts on the HTTP layer.
+ *
+ * @throws {UnverifiedIncomingWebhook} at mount time when the descriptor has no
+ * effective signature scheme and no explicit `verification`.
  */
-export declare const mountIncomingWebhook: <Body>(descriptor: IncomingWebhookDescriptor<Body>, options: MountOptions) => (request: IncomingRequest) => Promise<IncomingResponse>;
+export declare const mountIncomingWebhook: <Body>(descriptor: IncomingWebhookDescriptor<Body>, options: MountOptions) => MountedIncomingWebhook;
 
 export declare interface MountOptions {
-    /** Resolves the per-webhook signing secret. Return `null` to
-     *  skip signature verification (a warning logs to the framework
-     *  logger; the user has explicitly opted out). */
+    /** Resolves the per-webhook signing secret. Returning `null` for a
+     *  webhook whose verification is `'signature'` makes every delivery
+     *  answer 503 — it does NOT skip verification. */
     readonly resolveSecret: (webhookId: string) => Promise<string | null>;
     /** Optional idempotency cache override. Defaults to the
      *  process-singleton LRU. Pass a custom cache for tests or for a
@@ -562,9 +660,16 @@ export declare interface OutgoingEventDescriptor<Payload> {
      *  (pass the descriptor itself to `emit(descriptor, payload)` to
      *  type the payload; either way `emit` DECODES the payload against
      *  this schema and rejects a mismatch with `WebhookPayloadInvalid`
-     *  before any delivery is created). Recipients receive
-     *  `{ event, eventId, occurredAt, payload }` with `payload`
-     *  matching this schema. */
+     *  before any delivery is created).
+     *
+     *  The BODY on the wire is this payload and nothing else — no envelope. It
+     *  used to say recipients receive `{ event, eventId, occurredAt, payload }`,
+     *  which was never true of the code: `emit` posts `JSON.stringify(payload)`
+     *  verbatim (asserted in `deliverWorkflow.integration.test.ts`). The event
+     *  name, ids and attempt count ride in HEADERS (`x-voltro-event`,
+     *  `webhook-id`, `x-voltro-attempt`), which is also where Standard Webhooks
+     *  puts the delivery metadata — so the generated consumer package reads them
+     *  from there. */
     readonly payload: Schema.Schema<Payload>;
     /** Schema version. Increment when the payload shape changes in a
      *  way subscribers must adapt to. The dashboard surfaces version
@@ -628,7 +733,17 @@ export declare interface RateScope {
  * target when the auto-disable fires. Returns the post-write streak +
  * whether THIS call auto-disabled.
  */
-export declare const recordDeliveryOutcome: (store: DataStore, targetId: string, succeeded: boolean, reason: string, now?: Date) => Promise<AutoDisableOutcome>;
+export declare const recordDeliveryOutcome: (store: DataStore, targetId: string, succeeded: boolean, reason: string, now?: Date, 
+/**
+ * Disable the target on THIS failure, whatever the streak says.
+ *
+ * Standard Webhooks is explicit that `410 Gone` means "disable the endpoint",
+ * and that is a different signal from a streak: the receiver has TOLD us the
+ * endpoint is gone, so waiting for `autoDisableAfter` more failures is us
+ * ignoring an answer we asked for. It also fires when `autoDisableAfter` is
+ * unset — the streak feature being off does not make a 410 ambiguous.
+ */
+disableNow?: boolean) => Promise<AutoDisableOutcome>;
 
 /** Refund a slot claimed by `consumeRateSlot` — used when a later scope
  *  in the same acquisition denies, so a deferred delivery doesn't burn
@@ -699,26 +814,160 @@ export declare interface RetryPolicy {
 
 export declare type RetryStrategy = 'fixed' | 'linear' | 'exponential';
 
-export declare type SignatureScheme = HmacSignatureScheme | CustomSignatureScheme;
+export declare type SignatureScheme = HmacSignatureScheme | CustomSignatureScheme | StandardWebhooksSignatureScheme;
 
-export declare interface SignedPayload {
-    /** Header value to set on the outbound request. */
-    readonly headerValue: string;
-    /** Header name from the scheme. */
-    readonly headerName: string;
-    /** Timestamp embedded in the header (when `includeTimestamp`).
-     *  Surfaced so callers can log it alongside delivery records. */
+export declare interface SignedRequest {
+    /** Every header the scheme contributes, lowercased. */
+    readonly headers: Readonly<Record<string, string>>;
+    /** The instant embedded in the signature, when the scheme embeds one.
+     *  Surfaced so callers can log it beside the delivery record. */
     readonly timestamp?: number;
 }
 
-/** Produce the signature header value for an outbound request. */
-export declare const signPayload: (scheme: SignatureScheme, rawBody: Uint8Array, secret: string) => SignedPayload;
+/**
+ * Render the signature headers for an outbound request.
+ *
+ * ONE function for every scheme: a caller that has to know which scheme it is
+ * holding in order to assemble the right headers is a caller that will get a
+ * new scheme wrong.
+ */
+export declare const signRequest: (scheme: SignatureScheme, input: SignRequestInput) => SignedRequest;
 
-/** Slack-style: `X-Slack-Signature: v0=hex` with `X-Slack-Request-Timestamp` separate.
- *  Slack's actual header layout is non-standard — the timestamp lives
- *  in a SECOND header rather than embedded in the signature header.
- *  We model it via a custom scheme that reads both headers in `verify`. */
-export declare const slackSignature: () => CustomSignatureScheme;
+/** Everything a scheme may need to render its headers. */
+export declare interface SignRequestInput {
+    /** The exact bytes on the wire — the signature covers these, never the
+     *  pre-encoded JSON. */
+    readonly rawBody: Uint8Array;
+    /** The signing secret for this target. */
+    readonly secret: string;
+    /**
+     * The unique message identifier. Standard Webhooks signs OVER it and sends it
+     * as `webhook-id`; the other schemes ignore it.
+     *
+     * Required rather than optional, and the reason is worth keeping: it is also
+     * the consumer's idempotency key, so a delivery without one cannot be
+     * de-duplicated by the receiver at all. Making it optional would let a call
+     * site omit it and produce a spec-shaped message that is missing the one
+     * field the spec tells consumers to rely on.
+     */
+    readonly messageId: string;
+    /** Unix seconds. Defaults to now — a test pins it. */
+    readonly timestampSeconds?: number;
+}
+
+/**
+ * Slack-style: `X-Slack-Signature: v0=hex`, with the timestamp in the SEPARATE
+ * `X-Slack-Request-Timestamp` header and a signed content of
+ * `v0:<timestamp>:<body>`.
+ *
+ * This used to be a stub whose `verify` returned `false` unconditionally, with a
+ * comment explaining that the route adapter spliced the two header values into
+ * one string before calling it. It did — so `slackSignature()` was an exported,
+ * documented API that rejected every request when used as written, and the only
+ * thing that made Slack work was a special case in `incoming.ts` keyed on
+ * `_tag === 'custom'`. A verifier that receives the whole header map does not
+ * need either.
+ */
+export declare const slackSignature: (options?: {
+    readonly replayWindowSeconds?: number;
+}) => CustomSignatureScheme;
+
+/** Default replay tolerance. The spec requires A tolerance and names no number,
+ *  so this is ours: 5 minutes, matching the window every other scheme here uses. */
+export declare const STANDARD_WEBHOOKS_DEFAULT_TOLERANCE_SECONDS = 300;
+
+/** The three headers, exactly as the spec names them (lowercase). */
+export declare const STANDARD_WEBHOOKS_ID_HEADER = "webhook-id";
+
+export declare const STANDARD_WEBHOOKS_MAX_KEY_BYTES = 64;
+
+/** Spec: "Between 24 bytes (192 bits) and 64 bytes (512 bits)". */
+export declare const STANDARD_WEBHOOKS_MIN_KEY_BYTES = 24;
+
+/** Secret serialization prefix. */
+export declare const STANDARD_WEBHOOKS_SECRET_PREFIX = "whsec_";
+
+export declare const STANDARD_WEBHOOKS_SIGNATURE_HEADER = "webhook-signature";
+
+export declare const STANDARD_WEBHOOKS_TIMESTAMP_HEADER = "webhook-timestamp";
+
+/** The symmetric signature identifier. `v1a` is the asymmetric one — see the
+ *  header for why it is refused rather than ignored. */
+export declare const STANDARD_WEBHOOKS_VERSION = "v1";
+
+/**
+ * The three outbound headers for one delivery.
+ *
+ * `secrets` may carry more than one: during a rotation the spec has the producer
+ * sign "with both the current and old keys" and space-delimit the tokens, so a
+ * consumer holding either key still verifies. Order is producer-chosen; a
+ * consumer tries each.
+ */
+export declare const standardWebhooksHeaders: (input: {
+    readonly secrets: ReadonlyArray<string>;
+    readonly messageId: string;
+    readonly timestampSeconds: number;
+    readonly rawBody: Uint8Array;
+}) => Readonly<Record<string, string>>;
+
+/**
+ * The raw HMAC key behind a `whsec_…` secret.
+ *
+ * The prefix is REQUIRED, and that strictness is deliberate. A hex secret (what
+ * this plugin's generic schemes mint) is also valid base64, so a lenient
+ * "decode if it looks like base64" rule would silently HMAC 48 bytes of garbage
+ * — self-consistently, so our own round-trip would pass while every conformant
+ * consumer library rejected the delivery. Refusing loudly at signing time is the
+ * only version of this that cannot ship a broken endpoint.
+ */
+export declare const standardWebhooksKey: (secret: string) => Buffer;
+
+/**
+ * Standard Webhooks v1.0.0 — the interoperable scheme.
+ *
+ * Use it on an INCOMING webhook whose sender signs to the spec, and read it as
+ * the OUTGOING default via `defaultOutgoingSignature()`.
+ *
+ * Symmetric (HMAC-SHA256, `v1`) only. The spec's asymmetric half (ed25519,
+ * `v1a`, `whsk_`/`whpk_`) is not implemented, and `verifyRequest` says so
+ * explicitly rather than reporting a generic mismatch.
+ */
+export declare const standardWebhooksSignature: (options?: {
+    readonly toleranceSeconds?: number;
+    readonly previousSecret?: string;
+}) => StandardWebhooksSignatureScheme;
+
+/**
+ * The Standard Webhooks (v1.0.0) scheme — three `webhook-*` headers, a
+ * `msg_id.timestamp.payload` signed content, base64 `v1,` signatures, a
+ * `whsec_`-prefixed base64 key. Implemented in `./standardWebhooks`, which
+ * carries the spec quotations and the interop vector it is verified against.
+ */
+export declare interface StandardWebhooksSignatureScheme {
+    readonly _tag: 'standardWebhooks';
+    /** Replay tolerance. The spec REQUIRES a tolerance and names no number; 300s
+     *  is ours. */
+    readonly toleranceSeconds?: number;
+    /** A second key accepted on verify AND signed alongside on send — the spec's
+     *  zero-downtime rotation, which is what the space-delimited signature list
+     *  exists for. */
+    readonly previousSecret?: string;
+}
+
+/** One `v1,<base64>` token. */
+export declare const standardWebhooksSignatureToken: (secret: string, messageId: string, timestampSeconds: number, rawBody: Uint8Array) => string;
+
+/** The exact bytes the spec signs: `msg_id.timestamp.payload`. */
+export declare const standardWebhooksSignedContent: (messageId: string, timestampSeconds: number, rawBody: Uint8Array) => Buffer;
+
+export declare type StandardWebhooksVerifyResult = {
+    readonly ok: true;
+    readonly messageId: string;
+    readonly timestampSeconds: number;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
 
 /** Stripe-style: `Stripe-Signature: t=NNN,v1=hex`, 5-min replay window. */
 export declare const stripeSignature: (header?: string) => HmacSignatureScheme;
@@ -876,6 +1125,15 @@ export declare interface TargetSummary {
 
 declare const TTL_MS: Record<string, number>;
 
+/** Thrown at mount (i.e. at boot) for a webhook that verifies nothing and never
+ *  said so. The message is the deliverable — it names the endpoint and every
+ *  way out of the failure. */
+export declare class UnverifiedIncomingWebhook extends Error {
+    readonly webhookId: string;
+    readonly name = "UnverifiedIncomingWebhook";
+    constructor(webhookId: string);
+}
+
 /**
  * Convenience accessor for handlers. The framework's `AppContext`
  * types the `webhooks` slot as `unknown` to avoid a circular dep
@@ -897,6 +1155,24 @@ export declare const useWebhooksEffect: Effect.Effect<WebhooksServiceShape, neve
 
 export declare const validateSubscribe: (input: SubscribeInput) => void;
 
+/**
+ * Constant-time verification of an incoming request.
+ *
+ * Returns the structured reason so a caller can attach it to a 401 (helpful in
+ * dev, fine to elide in prod).
+ */
+export declare const verifyRequest: (scheme: SignatureScheme, input: VerifyRequestInput) => VerifyResult;
+
+export declare interface VerifyRequestInput {
+    readonly rawBody: Uint8Array;
+    readonly secret: string;
+    /** The request's headers, LOWERCASED keys. A scheme reads whichever of them
+     *  it needs (Slack needs two; Standard Webhooks needs three). */
+    readonly headers: Readonly<Record<string, string>>;
+    /** Overridable clock for the replay window — tests pin it. */
+    readonly nowSeconds?: number;
+}
+
 export declare type VerifyResult = {
     readonly ok: true;
 } | {
@@ -904,11 +1180,20 @@ export declare type VerifyResult = {
     readonly reason: string;
 };
 
-/** Constant-time signature verification for an incoming request.
- *  Returns the structured result so callers can attach the
- *  specific reason to a 401 response (helpful in dev, OK to elide
- *  in prod). */
-export declare const verifySignature: (scheme: SignatureScheme, rawBody: Uint8Array, secret: string, receivedHeaderValue: string | undefined) => VerifyResult;
+/**
+ * Verify an inbound Standard-Webhooks request.
+ *
+ * Order matters and follows the spec's own reasoning: shape → timestamp
+ * tolerance (a replay is rejected before any HMAC work) → constant-time compare
+ * against every accepted key × every offered token.
+ */
+export declare const verifyStandardWebhooks: (input: {
+    readonly secrets: ReadonlyArray<string>;
+    readonly rawBody: Uint8Array;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly toleranceSeconds?: number;
+    readonly nowSeconds?: number;
+}) => StandardWebhooksVerifyResult;
 
 /** Compare a target's pinned `payloadVersion` against the event's
  *  current `version`. Three states:
@@ -953,7 +1238,7 @@ export declare const _voltroWebhookDeliveriesTable: Table<"_voltro_webhook_deliv
     readonly eventId: ColumnBuilder<string | null, "text", boolean>;
     /** Attempt counter (1-indexed). */
     readonly attempt: ColumnBuilder<number, "integer", boolean>;
-    readonly status: ColumnBuilder<"failed" | "succeeded" | "inFlight" | "pending" | "retryScheduled", "text", boolean>;
+    readonly status: ColumnBuilder<"failed" | "pending" | "succeeded" | "inFlight" | "retryScheduled", "text", boolean>;
     /** Payload as sent over the wire. Stored verbatim — re-rendering
      *  from a referenced event row would lose the snapshot if the
      *  source event was deleted. */
@@ -1184,6 +1469,9 @@ export declare const _voltroWebhookTargetsTable: Table<"_voltro_webhook_targets"
  *  duplicate-effect check is what enforces that. */
 export declare const WEBHOOK_EMIT_EFFECT = "voltro.webhook.emit";
 
+/** The property name the runtime's boot gate reads off a mounted handler. */
+export declare const WEBHOOK_VERIFICATION_PROPERTY: "voltroWebhookVerification";
+
 /**
  * Thrown by `WebhooksService.replay` when no delivery row exists for the
  * given `deliveryId` — the row can't be re-triggered because the
@@ -1293,6 +1581,45 @@ export declare interface WebhookProviderDescriptor {
     readonly eventTypeFrom?: (body: unknown) => string | undefined;
 }
 
+/**
+ * The permissions webhook delivery declares.
+ *
+ * `network:outbound:*` and nothing else, deliberately: this entry contributes
+ * no interceptors, no inspect endpoints, no `extendSchema` tables (the webhook
+ * tables ride the framework's feature-mix assembly the moment a `*.webhook.tsx`
+ * file exists — see `cli/src/frameworkTableAssembly.ts`), so no other hook
+ * permission would be truthful either.
+ */
+export declare const WEBHOOKS_PLUGIN_PERMISSIONS: ReadonlyArray<PluginPermission>;
+
+/**
+ * Register webhook delivery with the plugin system.
+ *
+ * ```ts
+ * // app.config.ts
+ * import { webhooksPlugin } from '@voltro/plugin-webhooks'
+ *
+ * export default {
+ *   plugins: [webhooksPlugin()],
+ * }
+ * ```
+ *
+ * Adding it changes no behavior — `*.webhook.tsx` discovery, delivery and the
+ * incoming routes work exactly as before. What it changes is the boot audit:
+ * webhooks now appears in the plugin permission report and the plugin manifest
+ * with its outbound declaration, instead of being invisible to both.
+ */
+export declare const webhooksPlugin: (options?: WebhooksPluginOptions) => VoltroPlugin;
+
+export declare interface WebhooksPluginOptions {
+    /**
+     * Distinguishing suffix when an app registers the entry more than once
+     * (matching the `@voltro/plugin-mail#<name>` convention). Plugin names must
+     * be unique in one app's plugin list.
+     */
+    readonly name?: string;
+}
+
 export declare class WebhooksService extends WebhooksService_base {
 }
 
@@ -1564,7 +1891,7 @@ export declare const webhookTables: () => readonly [ Table<"_voltro_webhook_targ
     readonly eventId: ColumnBuilder<string | null, "text", boolean>;
     /** Attempt counter (1-indexed). */
     readonly attempt: ColumnBuilder<number, "integer", boolean>;
-    readonly status: ColumnBuilder<"failed" | "succeeded" | "inFlight" | "pending" | "retryScheduled", "text", boolean>;
+    readonly status: ColumnBuilder<"failed" | "pending" | "succeeded" | "inFlight" | "retryScheduled", "text", boolean>;
     /** Payload as sent over the wire. Stored verbatim — re-rendering
      *  from a referenced event row would lose the snapshot if the
      *  source event was deleted. */