@objectstack/plugin-webhooks 17.0.0 → 17.2.0

package/dist/index.d.cts

@@ -32,7 +32,15 @@ type HttpEnqueueFn = (input: EnqueueHttpInput) => Promise<string>;
  */
 interface OptionalLogger {
     info?(msg: string, meta?: unknown): void;
-    warn?(msg: string, meta?: unknown): void;
+    /**
+     * The GUARANTEED fallback channel (#9754). `error` stays optional — hosts do
+     * inject reduced sinks — so `warn` is where a durability report lands when
+     * `error` is absent, and a fallback that may itself be missing is not a
+     * fallback. Call sites keep the `logger?.warn?.(…)` spelling as the backstop
+     * for hosts the TYPE cannot reach; `SweepLogger` in plugin-email's
+     * `outbox-sweep.ts` carries the full reasoning and the measurement.
+     */
+    warn(msg: string, meta?: unknown): void;
     debug?(msg: string, meta?: unknown): void;
     error?(msg: string, err?: unknown, meta?: unknown): void;
 }
@@ -129,7 +137,22 @@ declare class AutoEnqueuer {
     private readonly subscriptions;
     private readonly subscriptionsObject;
     private readonly refreshIntervalMs;
-    private readonly logger;
+    /**
+     * Optional, and deliberately NOT defaulted to `{}` (#10556).
+     *
+     * `OptionalLogger` guarantees a `warn` channel under #9754, so `{}` stopped being a
+     * legal value of the type — which is the gate working: an empty object is a
+     * sink that declares it can report and then discards everything. The repair
+     * is to say what is TRUE — there may be no logger at all — rather than to
+     * mint a sink that lies. Runtime behaviour is unchanged in both directions:
+     * absent logger and `{}` both printed nothing before, and print nothing now.
+     *
+     * ⛔ What this deliberately does NOT decide: whether an absent host sink should
+     * instead default to a `console`-backed one. That is the open design call the
+     * #9754 ledger records against `plugin-security`'s `= {}` field, and it is a
+     * maintainer decision — not something to settle here to make a checker green.
+     */
+    private readonly logger?;
     private subId;
     private subIdSelfHeal;
     private refreshTimer;
@@ -404,6 +427,28 @@ declare class WebhookOutboxPlugin implements Plugin {
     private boundEngine;
     constructor(options?: WebhookOutboxPluginOptions);
     init(ctx: PluginContext): Promise<void>;
+    /**
+     * Teardown — the kernel's ONLY teardown hook.
+     *
+     * [#10772] This body used to be spelled `dispose()`. `Plugin`
+     * (`@objectstack/core`'s `types.ts`) declares `init()`, `start?(ctx)` and
+     * `destroy?()` and no `dispose()`, and `ObjectKernel.performShutdown()` /
+     * `LiteKernel.destroy()` walk the plugins in reverse calling
+     * `plugin.destroy()` — so after `await kernel.shutdown()` had RESOLVED the
+     * auto-enqueuer was still running and both engine hooks were still bound.
+     * Measured on the same revision: `dispose()` had ZERO callers anywhere in
+     * the repo, so this teardown had never run in any process at all.
+     *
+     * Idempotent: `boundEngine` is cleared as it is unbound, so a second
+     * teardown is a no-op rather than a second unbind.
+     */
+    destroy(): Promise<void>;
+    /**
+     * Retained alias for {@link destroy}. Kept because it is public API of an
+     * exported class: an embedder may have learned to call it directly
+     * precisely BECAUSE the kernel never did, and deleting it would break them.
+     * Same signature, same return type — a direct caller sees no change.
+     */
     dispose(): Promise<void>;
     private getMessaging;
     /**
@@ -436,11 +481,35 @@ declare class WebhookOutboxPlugin implements Plugin {
     private tryGetService;
     /**
      * Mount POST /api/v1/webhooks/redeliver on the host Hono app, if one is
-     * available. Delegates to `messaging.redeliverHttp(deliveryId)`. Auth is the
-     * better-auth session cookie — every authenticated user counts.
+     * available. Delegates to `messaging.redeliverHttp(deliveryId, …)`. Auth is
+     * the better-auth session cookie — every authenticated user counts.
+     *
+     * [#10740] Which is precisely why the caller's ACTIVE ORGANIZATION is
+     * resolved here and threaded into the call. `sys_http_delivery` is
+     * tenant-scoped, and this is the one door on it a request can reach: an
+     * unscoped replay from here is an authenticated user reaching another
+     * organization's delivery row on a walled deployment. With the tenant
+     * threaded, a row outside the caller's organization is simply not found.
+     *
+     * ⚠️ A session with no active organization threads `undefined`, and the
+     * driver's tenant-audit line then fires for that write. That is deliberate:
+     * the deployment could not tell us who is asking, and reporting the gap is
+     * the correct outcome. ⛔ It is never repaired with `bypassTenantAudit`,
+     * which would silence the report without closing anything.
      */
     private registerAdminRoutes;
-    private resolveSessionUserId;
+    /**
+     * [#10740] The better-auth session envelope (`{ user, session }`) for this
+     * request, or `undefined`.
+     *
+     * Widened from the previous `resolveSessionUserId` because the route now
+     * needs two facts from ONE lookup: who is asking (`user.id`, the
+     * authentication gate) and which organization they are asking as
+     * (`session.activeOrganizationId`, the tenant threaded into the write).
+     * Resolving them separately would mean two `getSession` calls that can
+     * disagree.
+     */
+    private resolveSession;
 }
 
 /**
@@ -572,6 +641,71 @@ declare const WEBHOOK_SECRET_FIELD = "signing_secret";
 /** Column on `sys_webhook` holding the encrypted custom-header map. */
 declare const WEBHOOK_HEADERS_FIELD = "headers_secret";
 
+/**
+ * ADR-0112 envelope for this refusal. `VALIDATION_ERROR`/400 is the standard
+ * catalog member for "the payload is not acceptable" — the SAME pair #8559's
+ * `EmptyCredentialWriteError` carries at the same door for the same class of
+ * verdict, so a client branching on `code`/`status` handles both malformed
+ * credential writes identically. A standard-catalog code needs no ledger entry.
+ */
+declare const WEBHOOK_HEADERS_SHAPE_REFUSAL_CODE = "VALIDATION_ERROR";
+declare const WEBHOOK_HEADERS_SHAPE_REFUSAL_STATUS = 400;
+/**
+ * [#8566] Refusal to persist a `headers_secret` plaintext that is not a flat
+ * JSON object of string values.
+ *
+ * Carries the ADR-0112 pair plus the LOCATION (`object`/`field`) as fields, so
+ * a consumer branches on `code`/`status` rather than on message text — the same
+ * discipline {@link WebhookHeadersUnresolvableError} follows on the read side
+ * of this seam, and `EmptyCredentialWriteError` follows on the write side.
+ */
+declare class WebhookHeadersShapeError extends Error {
+    readonly code = "VALIDATION_ERROR";
+    readonly status = 400;
+    readonly object: string;
+    readonly field: string;
+    constructor(object: string, field: string, diagnosis: string);
+}
+/**
+ * The verdict, as a pure function of the write payload — exported so the gate
+ * can be reasoned about and tested without booting an engine, and so any future
+ * caller uses the same one rule rather than restating it.
+ *
+ * Mutates nothing and returns nothing: it either passes or throws
+ * {@link WebhookHeadersShapeError}.
+ */
+declare function assertWritableWebhookHeaders(data: Record<string, unknown> | null | undefined, object?: string, field?: string): void;
+/** Minimal engine surface this binding needs — mirrors `webhook-provenance.ts`. */
+interface MinimalEngine {
+    registerHook(event: string, handler: (ctx: any) => any, options?: Record<string, any>): void;
+    unregisterHooksByPackage(packageId: string): number;
+}
+interface MinimalLogger {
+    info?: (msg: string, meta?: Record<string, any>) => void;
+}
+/**
+ * Bind the shape gate to both write events on `sys_webhook`.
+ *
+ * ## Deliberately NOT exempt for `isSystem`
+ * The provenance stamp next door skips system writes because it is detecting an
+ * ADMIN edit; this is a validity verdict on a payload, and a malformed header
+ * map is exactly as unusable when a seeder writes it. Ruling item 2 says the
+ * plugin's own write paths inherit this validation through the hook, which is
+ * only true if system writes are covered. They pass by construction —
+ * `bootstrapDeclaredWebhooks` and the migration sweep both write
+ * `serializeHeaders(...)` of an already `isHeaderMap`-filtered map — so
+ * covering them costs nothing and closes the door for a future write path that
+ * is less careful.
+ *
+ * Registered in CODE rather than from metadata, which also means
+ * `session.skipAutomations` (an import run with automations unchecked) cannot
+ * suppress it: the engine only skips metadata-bound entries. A validation door
+ * that an import could switch off would not be a door.
+ */
+declare function bindWebhookHeadersShapeGate(engine: MinimalEngine, logger?: MinimalLogger): void;
+/** Remove the gate — mirrors `unbindWebhookProvenanceStamp`, for `dispose()`. */
+declare function unbindWebhookHeadersShapeGate(engine: MinimalEngine): void;
+
 /**
  * [#7799] One-shot boot sweep that moves already-persisted cleartext signing
  * secrets out of `sys_webhook.definition_json` and into the encrypted
@@ -625,4 +759,4 @@ interface MigrateWebhookSecretsResult {
  */
 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 };
+export { AutoEnqueuer, type AutoEnqueuerOptions, type HttpEnqueueFn, type MigrateWebhookSecretsResult, WEBHOOK_HEADERS_FIELD, WEBHOOK_HEADERS_SHAPE_REFUSAL_CODE, WEBHOOK_HEADERS_SHAPE_REFUSAL_STATUS, WEBHOOK_SECRET_FIELD, WebhookHeadersShapeError, WebhookOutboxPlugin, type WebhookOutboxPluginOptions, assertWritableWebhookHeaders, bindWebhookHeadersShapeGate, migrateLegacyWebhookSecrets, unbindWebhookHeadersShapeGate };

package/dist/index.d.ts

@@ -32,7 +32,15 @@ type HttpEnqueueFn = (input: EnqueueHttpInput) => Promise<string>;
  */
 interface OptionalLogger {
     info?(msg: string, meta?: unknown): void;
-    warn?(msg: string, meta?: unknown): void;
+    /**
+     * The GUARANTEED fallback channel (#9754). `error` stays optional — hosts do
+     * inject reduced sinks — so `warn` is where a durability report lands when
+     * `error` is absent, and a fallback that may itself be missing is not a
+     * fallback. Call sites keep the `logger?.warn?.(…)` spelling as the backstop
+     * for hosts the TYPE cannot reach; `SweepLogger` in plugin-email's
+     * `outbox-sweep.ts` carries the full reasoning and the measurement.
+     */
+    warn(msg: string, meta?: unknown): void;
     debug?(msg: string, meta?: unknown): void;
     error?(msg: string, err?: unknown, meta?: unknown): void;
 }
@@ -129,7 +137,22 @@ declare class AutoEnqueuer {
     private readonly subscriptions;
     private readonly subscriptionsObject;
     private readonly refreshIntervalMs;
-    private readonly logger;
+    /**
+     * Optional, and deliberately NOT defaulted to `{}` (#10556).
+     *
+     * `OptionalLogger` guarantees a `warn` channel under #9754, so `{}` stopped being a
+     * legal value of the type — which is the gate working: an empty object is a
+     * sink that declares it can report and then discards everything. The repair
+     * is to say what is TRUE — there may be no logger at all — rather than to
+     * mint a sink that lies. Runtime behaviour is unchanged in both directions:
+     * absent logger and `{}` both printed nothing before, and print nothing now.
+     *
+     * ⛔ What this deliberately does NOT decide: whether an absent host sink should
+     * instead default to a `console`-backed one. That is the open design call the
+     * #9754 ledger records against `plugin-security`'s `= {}` field, and it is a
+     * maintainer decision — not something to settle here to make a checker green.
+     */
+    private readonly logger?;
     private subId;
     private subIdSelfHeal;
     private refreshTimer;
@@ -404,6 +427,28 @@ declare class WebhookOutboxPlugin implements Plugin {
     private boundEngine;
     constructor(options?: WebhookOutboxPluginOptions);
     init(ctx: PluginContext): Promise<void>;
+    /**
+     * Teardown — the kernel's ONLY teardown hook.
+     *
+     * [#10772] This body used to be spelled `dispose()`. `Plugin`
+     * (`@objectstack/core`'s `types.ts`) declares `init()`, `start?(ctx)` and
+     * `destroy?()` and no `dispose()`, and `ObjectKernel.performShutdown()` /
+     * `LiteKernel.destroy()` walk the plugins in reverse calling
+     * `plugin.destroy()` — so after `await kernel.shutdown()` had RESOLVED the
+     * auto-enqueuer was still running and both engine hooks were still bound.
+     * Measured on the same revision: `dispose()` had ZERO callers anywhere in
+     * the repo, so this teardown had never run in any process at all.
+     *
+     * Idempotent: `boundEngine` is cleared as it is unbound, so a second
+     * teardown is a no-op rather than a second unbind.
+     */
+    destroy(): Promise<void>;
+    /**
+     * Retained alias for {@link destroy}. Kept because it is public API of an
+     * exported class: an embedder may have learned to call it directly
+     * precisely BECAUSE the kernel never did, and deleting it would break them.
+     * Same signature, same return type — a direct caller sees no change.
+     */
     dispose(): Promise<void>;
     private getMessaging;
     /**
@@ -436,11 +481,35 @@ declare class WebhookOutboxPlugin implements Plugin {
     private tryGetService;
     /**
      * Mount POST /api/v1/webhooks/redeliver on the host Hono app, if one is
-     * available. Delegates to `messaging.redeliverHttp(deliveryId)`. Auth is the
-     * better-auth session cookie — every authenticated user counts.
+     * available. Delegates to `messaging.redeliverHttp(deliveryId, …)`. Auth is
+     * the better-auth session cookie — every authenticated user counts.
+     *
+     * [#10740] Which is precisely why the caller's ACTIVE ORGANIZATION is
+     * resolved here and threaded into the call. `sys_http_delivery` is
+     * tenant-scoped, and this is the one door on it a request can reach: an
+     * unscoped replay from here is an authenticated user reaching another
+     * organization's delivery row on a walled deployment. With the tenant
+     * threaded, a row outside the caller's organization is simply not found.
+     *
+     * ⚠️ A session with no active organization threads `undefined`, and the
+     * driver's tenant-audit line then fires for that write. That is deliberate:
+     * the deployment could not tell us who is asking, and reporting the gap is
+     * the correct outcome. ⛔ It is never repaired with `bypassTenantAudit`,
+     * which would silence the report without closing anything.
      */
     private registerAdminRoutes;
-    private resolveSessionUserId;
+    /**
+     * [#10740] The better-auth session envelope (`{ user, session }`) for this
+     * request, or `undefined`.
+     *
+     * Widened from the previous `resolveSessionUserId` because the route now
+     * needs two facts from ONE lookup: who is asking (`user.id`, the
+     * authentication gate) and which organization they are asking as
+     * (`session.activeOrganizationId`, the tenant threaded into the write).
+     * Resolving them separately would mean two `getSession` calls that can
+     * disagree.
+     */
+    private resolveSession;
 }
 
 /**
@@ -572,6 +641,71 @@ declare const WEBHOOK_SECRET_FIELD = "signing_secret";
 /** Column on `sys_webhook` holding the encrypted custom-header map. */
 declare const WEBHOOK_HEADERS_FIELD = "headers_secret";
 
+/**
+ * ADR-0112 envelope for this refusal. `VALIDATION_ERROR`/400 is the standard
+ * catalog member for "the payload is not acceptable" — the SAME pair #8559's
+ * `EmptyCredentialWriteError` carries at the same door for the same class of
+ * verdict, so a client branching on `code`/`status` handles both malformed
+ * credential writes identically. A standard-catalog code needs no ledger entry.
+ */
+declare const WEBHOOK_HEADERS_SHAPE_REFUSAL_CODE = "VALIDATION_ERROR";
+declare const WEBHOOK_HEADERS_SHAPE_REFUSAL_STATUS = 400;
+/**
+ * [#8566] Refusal to persist a `headers_secret` plaintext that is not a flat
+ * JSON object of string values.
+ *
+ * Carries the ADR-0112 pair plus the LOCATION (`object`/`field`) as fields, so
+ * a consumer branches on `code`/`status` rather than on message text — the same
+ * discipline {@link WebhookHeadersUnresolvableError} follows on the read side
+ * of this seam, and `EmptyCredentialWriteError` follows on the write side.
+ */
+declare class WebhookHeadersShapeError extends Error {
+    readonly code = "VALIDATION_ERROR";
+    readonly status = 400;
+    readonly object: string;
+    readonly field: string;
+    constructor(object: string, field: string, diagnosis: string);
+}
+/**
+ * The verdict, as a pure function of the write payload — exported so the gate
+ * can be reasoned about and tested without booting an engine, and so any future
+ * caller uses the same one rule rather than restating it.
+ *
+ * Mutates nothing and returns nothing: it either passes or throws
+ * {@link WebhookHeadersShapeError}.
+ */
+declare function assertWritableWebhookHeaders(data: Record<string, unknown> | null | undefined, object?: string, field?: string): void;
+/** Minimal engine surface this binding needs — mirrors `webhook-provenance.ts`. */
+interface MinimalEngine {
+    registerHook(event: string, handler: (ctx: any) => any, options?: Record<string, any>): void;
+    unregisterHooksByPackage(packageId: string): number;
+}
+interface MinimalLogger {
+    info?: (msg: string, meta?: Record<string, any>) => void;
+}
+/**
+ * Bind the shape gate to both write events on `sys_webhook`.
+ *
+ * ## Deliberately NOT exempt for `isSystem`
+ * The provenance stamp next door skips system writes because it is detecting an
+ * ADMIN edit; this is a validity verdict on a payload, and a malformed header
+ * map is exactly as unusable when a seeder writes it. Ruling item 2 says the
+ * plugin's own write paths inherit this validation through the hook, which is
+ * only true if system writes are covered. They pass by construction —
+ * `bootstrapDeclaredWebhooks` and the migration sweep both write
+ * `serializeHeaders(...)` of an already `isHeaderMap`-filtered map — so
+ * covering them costs nothing and closes the door for a future write path that
+ * is less careful.
+ *
+ * Registered in CODE rather than from metadata, which also means
+ * `session.skipAutomations` (an import run with automations unchecked) cannot
+ * suppress it: the engine only skips metadata-bound entries. A validation door
+ * that an import could switch off would not be a door.
+ */
+declare function bindWebhookHeadersShapeGate(engine: MinimalEngine, logger?: MinimalLogger): void;
+/** Remove the gate — mirrors `unbindWebhookProvenanceStamp`, for `dispose()`. */
+declare function unbindWebhookHeadersShapeGate(engine: MinimalEngine): void;
+
 /**
  * [#7799] One-shot boot sweep that moves already-persisted cleartext signing
  * secrets out of `sys_webhook.definition_json` and into the encrypted
@@ -625,4 +759,4 @@ interface MigrateWebhookSecretsResult {
  */
 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 };
+export { AutoEnqueuer, type AutoEnqueuerOptions, type HttpEnqueueFn, type MigrateWebhookSecretsResult, WEBHOOK_HEADERS_FIELD, WEBHOOK_HEADERS_SHAPE_REFUSAL_CODE, WEBHOOK_HEADERS_SHAPE_REFUSAL_STATUS, WEBHOOK_SECRET_FIELD, WebhookHeadersShapeError, WebhookOutboxPlugin, type WebhookOutboxPluginOptions, assertWritableWebhookHeaders, bindWebhookHeadersShapeGate, migrateLegacyWebhookSecrets, unbindWebhookHeadersShapeGate };