@objectstack/plugin-webhooks 17.0.0-rc.6 → 17.0.0

package/dist/index.d.ts

@@ -16,6 +16,15 @@ type WebhookTrigger = WebhookTriggerType;
  * Enqueue callback into the shared `service-messaging` HTTP outbox (ADR-0018 M3).
  * The plugin supplies one bound to `messaging.enqueueHttp(...)`; webhooks no
  * longer own a delivery outbox/dispatcher — they share the generic substrate.
+ *
+ * [#8069] It MUST be `MessagingService.enqueueHttp`, not `IHttpOutbox.enqueue`.
+ * The enqueuer now emits two kinds of input through this one door — an ordinary
+ * delivery, and a PARKED event whose subscription lost its credentials — and
+ * only the messaging seam routes the second to `recordUndeliverable()`. Wired
+ * to the raw outbox instead, the parked input is refused at the delivery door
+ * (correctly — the alternative is a `pending` unsigned row) and the durable
+ * record is lost; {@link AutoEnqueuer} reports that at `error` rather than
+ * letting it pass as an ordinary enqueue failure.
  */
 type HttpEnqueueFn = (input: EnqueueHttpInput) => Promise<string>;
 /**
@@ -42,6 +51,20 @@ interface CachedSubscription {
     headers?: Record<string, string>;
     secret?: string;
     timeoutMs?: number;
+    /**
+     * [#8069] Set when a credential this subscription needs could not be
+     * recovered. The subscription stays CACHED — that is the change — but every
+     * event it matches is written to `sys_http_delivery` as a parked `dead` row
+     * carrying this text, instead of being discarded with nothing to find.
+     *
+     * Before this, `attachCredentials` returning false removed the row from the
+     * cache entirely, so matching events found no subscription and vanished:
+     * fail-closed and correct, but leaving an operator with a log line (#8043)
+     * and no durable trace. A parked subscription is still fail-closed —
+     * {@link secret} and {@link headers} stay unset, so nothing can be sent —
+     * it is merely no longer silent.
+     */
+    parkedReason?: string;
 }
 interface AutoEnqueuerOptions {
     /**
@@ -112,18 +135,191 @@ declare class AutoEnqueuer {
     private refreshTimer;
     private running;
     private refreshing;
+    /** [#8022] Detach for the engine's crypto-registration listener. */
+    private unbindCryptoListener;
+    /**
+     * [#8022] Webhook ids currently dropped for an unresolvable credential —
+     * the signing key (#7799) or, since #7986, the custom header map. ONE set
+     * for both on purpose: a subscription is either armed or dropped, so a
+     * per-credential ledger would let a row already silenced for its key report
+     * loudly again for its headers on the very next refresh.
+     * Held so the loud first report is said ONCE per outage (AGENTS.md
+     * "Degradation log levels": *say it once, at the first degradation*) and
+     * again if the same webhook breaks after recovering — not once per row per
+     * refresh, forever.
+     */
+    private readonly droppedForSecret;
     constructor(engine: IDataEngine, realtime: IRealtimeService, enqueue: HttpEnqueueFn, opts?: AutoEnqueuerOptions);
     /**
      * Load the subscription cache and start listening for events.
      */
     start(): Promise<void>;
     stop(): Promise<void>;
+    /**
+     * [#8022] The engine just gained a CryptoProvider — rebuild the cache so
+     * subscriptions dropped for an unresolvable signing key re-arm now, instead
+     * of at the next periodic refresh up to {@link refreshIntervalMs} away.
+     *
+     * It deliberately does NOT call {@link refresh} directly. `refresh()`
+     * coalesces onto an in-flight build, and the build most likely to be in
+     * flight right now is the one from `start()` — the very build whose rows
+     * were read while there was no provider. Joining it would return "refreshed"
+     * having re-armed nothing, which is this issue with an extra step. So: let
+     * whatever is running finish, then read again.
+     */
+    private rearmAfterCryptoRegistered;
     /**
      * Force-refresh the subscription cache from storage. Concurrent
      * callers share a single in-flight refresh.
      */
     refresh(): Promise<void>;
     private doRefresh;
+    /**
+     * [#7799, #7986] Resolve BOTH encrypted credentials for one cached
+     * subscription. Returns `false` when the subscription must be dropped from
+     * the cache.
+     *
+     * The two halves are deliberately resolved on the SAME build rather than on
+     * separate schedules. #8022's re-arm rebuilds the whole cache when a
+     * CryptoProvider registers; a header map recovered on any other cadence
+     * would let the enqueuer re-arm into a delivery that is correctly signed and
+     * silently missing its `Authorization`, which is the failure mode of both
+     * cards at once.
+     *
+     * The drop ledger is cleared only when BOTH succeed — otherwise a row whose
+     * secret resolves and whose headers do not would clear its own "already
+     * reported" mark on every refresh and shout the same `error` every 60s,
+     * which is precisely the unreadable-error-channel failure #8022's say-once
+     * rule exists to prevent.
+     *
+     * Cost: up to two point reads + two decrypts per credential-bearing row per
+     * refresh (default 60s), off the write path entirely. Deliberately NOT
+     * memoised across refreshes — the only cheap cache key would be
+     * `updated_at`, which nothing guarantees is stamped when a credential is
+     * rotated, and a stale key signs every delivery with a signature the
+     * receiver rejects.
+     */
+    private attachCredentials;
+    /**
+     * [#8069] Mark a subscription parked and strip anything sendable off it.
+     *
+     * Called from the two `attachX` failure paths, which each already reported
+     * the drop at `error` (say-once, #8022). The credentials are cleared rather
+     * than merely "not set": `attachSecret` can succeed and `attachHeaders`
+     * fail, and a parked row must not carry the header map — that map is the
+     * ordinary place an `Authorization: Bearer …` goes (#7986), and copying it
+     * onto a row that will sit in `sys_http_delivery` for the full 30d
+     * retention window without ever being sent is a credential copy bought for
+     * nothing.
+     */
+    /**
+     * [#8069] Report a failed outbox write off the hot path, at the level the
+     * loss actually deserves.
+     *
+     * AGENTS.md decides that with one question — *does the system still look
+     * normal from the outside while something it claims is persisted has not
+     * landed?* For a PARKED subscription the answer is unambiguously yes, and
+     * worse than for an ordinary enqueue failure: the durable record is the
+     * only trace this event ever existed, so losing the write puts us back
+     * exactly where this issue started, silently. So `error` there, and the
+     * pre-existing `warn` for an ordinary enqueue, where the delivery itself is
+     * the thing that did not happen and the subscription is otherwise healthy.
+     *
+     * The realistic cause of the parked branch is a host that wired
+     * {@link HttpEnqueueFn} straight to `IHttpOutbox.enqueue` instead of
+     * `MessagingService.enqueueHttp`: only the messaging seam routes a parked
+     * input to `recordUndeliverable()`, and the raw delivery door refuses the
+     * discriminator rather than minting a `pending` unsigned row from it. The
+     * message names that, because it is not guessable from "enqueue failed".
+     */
+    private reportWriteFailure;
+    private park;
+    /**
+     * [#7799] Resolve `sub.secret`. Returns `false` when the subscription must
+     * be dropped.
+     *
+     * Three sources, in order:
+     *  1. `sys_webhook.signing_secret` — the encrypted column. The read path
+     *     returns a mask, so presence is decidable here but the value is not;
+     *     `resolveWebhookSecret` dereferences it server-side.
+     *  2. `definition_json.secret` — a row not yet swept by
+     *     `migrateLegacyWebhookSecrets` (or hand-edited back in). Still honoured
+     *     so an un-migrated deployment keeps signing, and warned about once per
+     *     refresh so the exposure is visible rather than silently permanent.
+     *  3. Neither — an unsigned webhook, which is a legitimate authored choice
+     *     (`secret` is optional on the envelope).
+     *
+     * A stored-but-unresolvable key DROPS the subscription instead of
+     * delivering unsigned. The signature is the receiver's only proof of
+     * origin (#7722, #7799): a webhook that stops arriving is visible and gets
+     * investigated, while one that keeps arriving unsigned is invisible and
+     * teaches the receiver to accept unauthenticated traffic.
+     *
+     * [#8542] Case 3 means what it says only because the seam was fixed to say
+     * it. `resolveWebhookSecret` used to answer `undefined` for BOTH "no key is
+     * stored" and "a key is stored and did not come back", so this method read
+     * the second as the third and armed the subscription — the invariant above
+     * failing OPEN, silently, on the producer path. Nothing here changed: the
+     * seam now raises for that case, so it lands in the `catch` below exactly
+     * the way a throwing resolver already did, and the drop, the say-once
+     * `error` and the #8069 park all apply to it unchanged.
+     */
+    private attachSecret;
+    /**
+     * [#7986] Resolve `sub.headers` from the encrypted column, with the same
+     * three-source shape as {@link attachSecret} and for the same reasons.
+     *
+     * A stored-but-unresolvable header map DROPS the subscription rather than
+     * delivering without it. That is the identical trade #7799 made for the
+     * signature, and it needs restating because the intuition runs the other
+     * way: a missing `Authorization` looks self-announcing, since the receiver
+     * answers 401 and the attempt lands in `sys_http_delivery` for anyone to
+     * find. But that is only the AUTHENTICATED case. Against an endpoint that
+     * does not require the header — a routing `X-Tenant-Id`, an
+     * `X-Environment: staging` — the delivery SUCCEEDS while quietly deviating
+     * from the configuration the author wrote, and nothing anywhere records
+     * that it went out incomplete. A subscription that stops is visible; a
+     * delivery that arrives subtly wrong is not.
+     *
+     * [#8558] And that is what this method used to do, for the same reason its
+     * signing sibling did (#8542): `resolveWebhookHeaders` answered `undefined`
+     * for BOTH "no headers are stored" and "a map is stored and did not come
+     * back as one", so this method read the second as the first and armed the
+     * subscription — the paragraph above failing OPEN. Measured, the delivery
+     * then went out SUCCESSFULLY and correctly SIGNED with the whole authored
+     * map missing, which is the worst available combination: the signature
+     * tells the receiver the request is genuinely ours. Nothing here changed:
+     * the seam now raises, so it lands in the `catch` below exactly the way a
+     * throwing resolver already did, and the drop, the say-once `error` and the
+     * #8069 park all apply to it unchanged.
+     */
+    private attachHeaders;
+    /**
+     * [#8022] Report a subscription dropped for an unresolvable signing key.
+     *
+     * ## Why `error`, and why only the first time
+     * AGENTS.md decides the level with one question: *after the degradation,
+     * does the system still look normal from the outside while something the
+     * system claims is happening is not?* Here the answer is yes, and it is the
+     * whole defect — `GET /api/v1/data/sys_webhook` keeps reading
+     * `active: true`, Setup keeps showing the webhook armed, and every matching
+     * record change is discarded with no delivery and no `sys_http_delivery`
+     * row to find afterwards. That is a durability degradation wearing a
+     * functional degradation's clothes, so it owes the two things an `error`
+     * owes: the consequence, concretely, and the fix.
+     *
+     * Said ONCE per outage per webhook, per the same section. The cache is
+     * rebuilt every {@link refreshIntervalMs}; an unfixed misconfiguration would
+     * otherwise print this line every 60s forever, which is how an `error`
+     * channel becomes unreadable — the failure mode that made the founding
+     * incident's `warn` invisible. Repeats drop to `debug`; a recovery clears
+     * the id, so a re-break is loud again.
+     *
+     * ADR-0112: `code` + `status` travel in the meta so a consumer branches on
+     * the pair, not on message text. Same pair the seeder's refusal carries for
+     * the same underlying cause.
+     */
+    private reportDrop;
     private parseRow;
     /**
      * Handler for the firehose subscription.
@@ -224,6 +420,19 @@ declare class WebhookOutboxPlugin implements Plugin {
      */
     private bootDeclaredWebhooks;
     private bootAutoEnqueue;
+    /**
+     * [#8069] Register {@link createWebhookRedeliverGuard} with messaging, so
+     * `redeliver()` refuses a webhook row whose signing configuration is no
+     * longer available — for EVERY caller, not just the
+     * `POST /api/v1/webhooks/redeliver` route.
+     *
+     * Absence is loud, and `error` is the right level by AGENTS.md's one
+     * question: with no guard installed the endpoint still answers 200 and the
+     * dispatcher still reports a delivery, while the fail-closed signing
+     * guarantee the system claims (#7799) is not actually being kept. That is a
+     * durability/consistency degradation wearing a functional one's clothes.
+     */
+    private installRedeliverGuard;
     private tryGetService;
     /**
      * Mount POST /api/v1/webhooks/redeliver on the host Hono app, if one is
@@ -234,4 +443,186 @@ declare class WebhookOutboxPlugin implements Plugin {
     private resolveSessionUserId;
 }
 
-export { AutoEnqueuer, type AutoEnqueuerOptions, type HttpEnqueueFn, WebhookOutboxPlugin, type WebhookOutboxPluginOptions };
+/**
+ * [#7799] The persistence seam for a webhook's HMAC signing secret.
+ *
+ * ## The defect
+ * `bootstrapDeclaredWebhooks` used to persist the whole validated `Webhook`
+ * envelope — `secret` included — as `definition_json: JSON.stringify(wh)`, and
+ * `AutoEnqueuer.parseRow` read `defn.secret` straight back out to sign
+ * deliveries. `definition_json` is an ordinary textarea on an admin-authorable
+ * object with no restrictive `enable.apiMethods`, so an ordinary
+ * `GET /api/v1/data/sys_webhook` returned the key to every persona that can read
+ * the object. That key is the receiver's ONLY proof a delivery came from us.
+ *
+ * #7722 removed the same secret's per-attempt copies from `sys_http_delivery`;
+ * this is the remaining cleartext location, and unlike the delivery table it is
+ * not bounded by a retention window.
+ *
+ * ## The seam
+ * Nothing about the AUTHORING envelope changes — authors still write
+ * `secret: '…'` on `defineWebhook()`, and `webhook.zod.ts` is untouched. What
+ * changes is where the value LANDS:
+ *
+ *   authored `secret`  →  `sys_webhook.signing_secret` (`type: 'secret'`)
+ *                      →  engine encrypts → `sys_secret` ciphertext row
+ *                      →  row keeps only an opaque `secret:<id>` ref
+ *                      →  every read path returns the mask
+ *
+ *   `definition_json`  →  the same envelope MINUS `secret`
+ *
+ * and the enqueuer recovers the plaintext server-side, at cache-refresh time,
+ * through `engine.resolveSecretField()` — the privileged, driver-level
+ * dereference added alongside this change, because the encrypted channel masks
+ * its own ref on every supported read path and a server-side consumer
+ * previously had no way to get at it.
+ *
+ * ## Two things this file deliberately does NOT do
+ * - It does not invent a second cipher store. The engine owns the
+ *   `ICryptoProvider` (the host injects it via `setCryptoProvider`, and it is
+ *   not a kernel service), so the plugin cannot encrypt on its own — it writes
+ *   cleartext INTO the `secret`-typed column exactly once and lets the engine's
+ *   own write path do the wrapping. That also inherits the engine's fail-closed
+ *   posture for free: no provider ⇒ the write throws ⇒ we skip the webhook
+ *   loudly, rather than silently re-opening the hole in a new column.
+ * - It does not guess. When a row HAS a stored secret the enqueuer cannot
+ *   resolve, the subscription is dropped rather than delivered unsigned — an
+ *   undelivered webhook is visible and safe, an unsigned one is invisible and
+ *   is precisely the failure this issue is about.
+ */
+
+/** Column on `sys_webhook` holding the encrypted signing key. */
+declare const WEBHOOK_SECRET_FIELD = "signing_secret";
+
+/**
+ * [#7986] The persistence seam for a webhook's custom `headers` map — the
+ * sibling passenger #7799 left behind on the blob it emptied.
+ *
+ * ## The defect
+ * #7799 moved the signing secret out of `sys_webhook.definition_json` into an
+ * encrypted column. It did not move `headers`, and `headers` is the ordinary
+ * place an `Authorization: Bearer …` goes. Same column, same object with no
+ * `enable` block at all (so the FULL default data API), same unbounded
+ * retention — the only thing that differed was which key of the blob the card
+ * happened to name. `GET /api/v1/data/sys_webhook` handed the header map back
+ * to every persona that can read the object.
+ *
+ * That framing is the finding: the COLUMN was the problem and the secret was
+ * only one of its passengers.
+ *
+ * ## Why the WHOLE map moves, and not just the credential-looking entries
+ * A signing secret is one opaque value with one consumer. `headers` is an
+ * open-ended `Record<string, string>` in which only some entries are
+ * credentials — and **the platform cannot tell which**. Three ways to decide
+ * were on the table; this is why the map moves whole:
+ *
+ *  - **Guess from the header NAME** (`authorization`, `x-api-key`, …). Rejected:
+ *    it is fail-OPEN on precisely the names most likely to be a credential in
+ *    practice — `X-Acme-Token`, `X-Vendor-Key` — and a heuristic that silently
+ *    passes the one header that mattered is worse than no heuristic, because it
+ *    reads as coverage. Every other credential decision in this repo fails
+ *    closed; this one would not.
+ *  - **Have the author DECLARE which are sensitive** (`secretHeaders: [...]`).
+ *    That is a change to the authoring envelope (`webhook.zod.ts`), which is
+ *    the spec seat's surface, not this one — and it would still leave the
+ *    `source: 'flow'` half of the same exposure untouched, because a flow
+ *    `http` node's headers are interpolated per run and never parsed through
+ *    `WebhookSchema` at all. Escalated rather than attempted here (#7986).
+ *  - **Move the whole map.** Fail-closed by construction, needs no authoring
+ *    change, and the cost it is accused of — "it encrypts non-sensitive headers
+ *    too" — is measured and small: `definition_json` is a raw JSON textarea
+ *    pending a real builder (see `sys-webhook.object.ts`), so what an admin
+ *    loses is the ability to READ back a `Content-Type` they typed, on a
+ *    surface that was never the intended authoring UI.
+ *
+ * ## The seam
+ * Identical in shape to `webhook-secret.ts`, deliberately — one mechanism, two
+ * passengers, so a reader who has understood #7799 has already understood this:
+ *
+ *   authored `headers`  →  `sys_webhook.headers_secret` (`type: 'secret'`)
+ *                       →  engine encrypts the SERIALIZED map → `sys_secret`
+ *                       →  row keeps only an opaque `secret:<id>` ref
+ *                       →  every read path returns the mask
+ *
+ *   `definition_json`   →  the same envelope MINUS `headers` (and MINUS
+ *                          `secret`, as #7799 already established)
+ *
+ * The map is serialized because the encrypted channel carries a string. That is
+ * an encoding detail and not a second format: {@link parseStoredHeaders} is the
+ * only reader, and it treats anything that is not a flat string map as absent
+ * rather than guessing.
+ *
+ * ## What this file deliberately does NOT do
+ * - It does not invent a second cipher store, for the same layering reason
+ *   `webhook-secret.ts` gives: the engine owns the `ICryptoProvider`, so the
+ *   plugin writes cleartext INTO the `secret`-typed column exactly once and
+ *   lets the engine's write path wrap it. The fail-closed posture comes free.
+ * - It does not deliver partially. A row whose stored headers cannot be
+ *   resolved DROPS the subscription rather than delivering it with the headers
+ *   missing — see {@link resolveWebhookHeaders}.
+ *
+ * [#8558] That last line was a statement of intent this file did not keep. Only
+ * a THROWING resolver reached the caller's `catch`; a resolver that answered
+ * `null` — or handed back a value that was not a flat string map — folded onto
+ * the `undefined` this seam uses for "no headers stored", and the subscription
+ * armed and delivered without them. {@link WebhookHeadersUnresolvableError} is
+ * what makes the sentence true.
+ */
+
+/** Column on `sys_webhook` holding the encrypted custom-header map. */
+declare const WEBHOOK_HEADERS_FIELD = "headers_secret";
+
+/**
+ * [#7799] One-shot boot sweep that moves already-persisted cleartext signing
+ * secrets out of `sys_webhook.definition_json` and into the encrypted
+ * `signing_secret` column.
+ *
+ * ## Why a sweep and not just the seeder
+ * `bootstrapDeclaredWebhooks` re-seeds package-declared rows on every boot, so
+ * those heal themselves the moment the new mapping lands. The rows that do NOT
+ * heal are exactly the ones most likely to hold a real production key:
+ *
+ *  - `managed_by: 'admin'` — authored in Setup, never touched by the seeder;
+ *  - `customized: true` — a package row an admin edited, deliberately frozen
+ *    against re-seeding (seed-not-clobber, #3461 / #2909).
+ *
+ * Leaving those behind would make this a half-migration: the code path that
+ * created the exposure would be fixed while the exposed values stayed in the
+ * table. So the sweep is keyed off the DATA (does this blob contain a secret?),
+ * not off provenance.
+ *
+ * ## What it is careful about
+ *  - **System context.** The provenance hook exempts `isSystem` writes, so
+ *    migrating a package row does not stamp `customized: true` and freeze it
+ *    against future seeding.
+ *  - **Idempotent.** A row whose blob no longer carries a `secret` is skipped,
+ *    so the sweep is free on every boot after the first.
+ *  - **Fail-closed, per row.** With no CryptoProvider the encrypted write throws
+ *    and the row is LEFT AS IT WAS — still exposed, but intact and still
+ *    signing. It is reported with an ADR-0112 `code`/`status` pair so an
+ *    operator can see exactly which rows are still cleartext and why, rather
+ *    than the sweep quietly reporting success.
+ *  - **Never widens the blast radius.** The cleartext is only removed from
+ *    `definition_json` in the SAME update that stores the encrypted copy; a
+ *    failure cannot land the strip without the store.
+ */
+
+interface Logger {
+    info?: (msg: string, meta?: unknown) => void;
+    warn?: (msg: string, meta?: unknown) => void;
+}
+interface MigrateWebhookSecretsResult {
+    /** Rows whose blob carried a cleartext secret. */
+    found: number;
+    /** Rows now holding an encrypted secret and a secret-free blob. */
+    migrated: number;
+    /** Rows still holding cleartext because the encrypted write was refused. */
+    failed: number;
+}
+/**
+ * Move every cleartext `definition_json.secret` into the encrypted column.
+ * Safe to run on every boot; returns counts for the caller to log.
+ */
+declare function migrateLegacyWebhookSecrets(engine: IDataEngine, logger?: Logger, subscriptionsObject?: string): Promise<MigrateWebhookSecretsResult>;
+
+export { AutoEnqueuer, type AutoEnqueuerOptions, type HttpEnqueueFn, type MigrateWebhookSecretsResult, WEBHOOK_HEADERS_FIELD, WEBHOOK_SECRET_FIELD, WebhookOutboxPlugin, type WebhookOutboxPluginOptions, migrateLegacyWebhookSecrets };