npm - @voltro/plugin-webhooks - Versions diffs - 0.33.0 → 0.34.0 - Mend

@voltro/plugin-webhooks 0.33.0 → 0.34.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/CHANGELOG.md +1801 -0
package/dist/index.d.ts +355 -37
package/dist/index.js +398 -344
package/dist/mixin.d.ts +2 -2
package/dist/mixin.js +2 -0
package/dist/providers/index.d.ts +39 -6
package/dist/providers/index.js +16 -18
package/dist/signing-DeHObNv6.js +234 -0
package/package.json +7 -7
package/dist/signing-DUG4JWwk.js +0 -117

package/dist/index.d.ts CHANGED Viewed

@@ -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,
@@ -168,6 +182,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 +307,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 +447,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 +492,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 +536,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 +600,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 +651,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 +724,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 +805,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;
+/** 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;
-/** 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;
+/** 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 +1116,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 +1146,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 +1171,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 +1229,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 +1460,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 +1572,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 +1882,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. */