@classytic/arc 2.22.0 → 2.25.0

package/dist/integrations/{jobs.mjs → jobs/index.mjs}

@@ -1,45 +1,53 @@
 import fp from "fastify-plugin";
-//#region src/integrations/jobs.ts
-/**
-* Define a background job with typed data and configuration.
-*
-* @example
-* const processImage = defineJob({
-*   name: 'process-image',
-*   handler: async (data: { url: string; width: number }) => {
-*     return await sharp(data.url).resize(data.width).toBuffer();
-*   },
-*   retries: 3,
-*   timeout: 60000,
-* });
-*/
-function defineJob(definition) {
-	return definition;
-}
-var Semaphore = class {
-	available;
-	waiters = [];
-	constructor(permits) {
-		this.available = permits;
-	}
-	get isFull() {
-		return this.available === 0;
-	}
-	acquire() {
-		if (this.available > 0) {
-			this.available--;
-			return Promise.resolve();
-		}
-		return new Promise((resolve) => {
-			this.waiters.push(resolve);
-		});
-	}
-	release() {
-		const next = this.waiters.shift();
-		if (next) next();
-		else this.available++;
+//#region src/integrations/jobs/execution.ts
+async function executeTimedHandler(options) {
+	const { run, label, jobId, timeoutMs, cancelGraceMs = 3e4, logger } = options;
+	let released = false;
+	const releaseSlot = () => {
+		if (released) return;
+		released = true;
+		options.releaseSlot?.();
+	};
+	const abort = new AbortController();
+	const handlerPromise = (async () => run(abort.signal))();
+	handlerPromise.then(releaseSlot, releaseSlot);
+	if (!timeoutMs) return handlerPromise;
+	let timer;
+	const timeoutPromise = new Promise((_, reject) => {
+		timer = setTimeout(() => {
+			const err = /* @__PURE__ */ new Error(`Job '${label}' timed out after ${timeoutMs}ms`);
+			abort.abort(err);
+			const timedOutAt = Date.now();
+			const graceTimer = setTimeout(() => {
+				logger?.warn({
+					job: label,
+					jobId,
+					graceMs: cancelGraceMs
+				}, "timed-out job handler still running after grace period — force-releasing its maxConcurrent slot (bulkhead may now be exceeded); make the handler honor its AbortSignal");
+				releaseSlot();
+			}, cancelGraceMs);
+			graceTimer.unref?.();
+			handlerPromise.then(() => logger?.warn({
+				job: label,
+				jobId,
+				afterMs: Date.now() - timedOutAt
+			}, "timed-out job handler eventually completed (result discarded)"), (handlerErr) => logger?.warn({
+				job: label,
+				jobId,
+				afterMs: Date.now() - timedOutAt,
+				err: handlerErr
+			}, "timed-out job handler eventually failed")).finally(() => clearTimeout(graceTimer));
+			reject(err);
+		}, timeoutMs);
+	});
+	try {
+		return await Promise.race([handlerPromise, timeoutPromise]);
+	} finally {
+		clearTimeout(timer);
 	}
-};
+}
+//#endregion
+//#region src/integrations/jobs/repeat.ts
 /**
 * Whether an existing schedule matches the currently configured repeat spec.
 *
@@ -60,11 +68,6 @@ function repeatSpecMatches(record, spec) {
 * Remove repeatable schedules left behind by a previous deploy whose repeat
 * spec no longer matches the current `JobDefinition.repeat`.
 *
-* BullMQ keys repeatable schedules by a hash of their repeat options, so
-* re-adding a job with a CHANGED pattern/every/tz/endDate creates a NEW
-* schedule while the old one keeps firing — the job double-fires after every
-* repeat-config change. This reconciles at plugin registration:
-*
 *   - Only schedulers whose `name` equals the registered job's name are
 *     candidates — foreign/unknown schedulers are never touched.
 *   - A scheduler matching the current spec is kept (the subsequent
@@ -102,6 +105,32 @@ async function removeStaleRepeatSchedulers(queue, jobName, spec, log) {
 		}, `[arc/jobs] Failed to reconcile repeatable schedules for '${jobName}' — continuing (boot-time hygiene only)`);
 	}
 }
+//#endregion
+//#region src/integrations/jobs/plugin.ts
+var Semaphore = class {
+	available;
+	waiters = [];
+	constructor(permits) {
+		this.available = permits;
+	}
+	get isFull() {
+		return this.available === 0;
+	}
+	acquire() {
+		if (this.available > 0) {
+			this.available--;
+			return Promise.resolve();
+		}
+		return new Promise((resolve) => {
+			this.waiters.push(resolve);
+		});
+	}
+	release() {
+		const next = this.waiters.shift();
+		if (next) next();
+		else this.available++;
+	}
+};
 const jobsPluginImpl = async (fastify, options) => {
 	const { connection, jobs, prefix = "/jobs", bridgeEvents = true, defaults = {} } = options;
 	let Queue;
@@ -158,11 +187,6 @@ const jobsPluginImpl = async (fastify, options) => {
 		const throttledSet = /* @__PURE__ */ new Set();
 		throttledJobs.set(queueName, throttledSet);
 		const worker = new Worker(queueName, async (bullJob) => {
-			const meta = {
-				jobId: bullJob.id ?? "",
-				attemptsMade: bullJob.attemptsMade ?? 0,
-				timestamp: Date.now()
-			};
 			if (semaphore) {
 				if (semaphore.isFull) throttledSet.add(bullJob.id ?? "");
 				try {
@@ -171,22 +195,23 @@ const jobsPluginImpl = async (fastify, options) => {
 					throttledSet.delete(bullJob.id ?? "");
 				}
 			}
-			let result;
-			try {
-				if (jobTimeout) {
-					let timer;
-					const timeoutPromise = new Promise((_, reject) => {
-						timer = setTimeout(() => reject(/* @__PURE__ */ new Error(`Job '${queueName}' timed out after ${jobTimeout}ms`)), jobTimeout);
-					});
-					try {
-						result = await Promise.race([job.handler(bullJob.data, meta), timeoutPromise]);
-					} finally {
-						clearTimeout(timer);
-					}
-				} else result = await job.handler(bullJob.data, meta);
-			} finally {
-				semaphore?.release();
-			}
+			const result = await executeTimedHandler({
+				label: queueName,
+				...bullJob.id !== void 0 ? { jobId: bullJob.id } : {},
+				...jobTimeout !== void 0 ? { timeoutMs: jobTimeout } : {},
+				...job.cancelGraceMs !== void 0 ? { cancelGraceMs: job.cancelGraceMs } : {},
+				...semaphore ? { releaseSlot: () => semaphore.release() } : {},
+				logger: fastify.log,
+				run: (signal) => {
+					const meta = {
+						jobId: bullJob.id ?? "",
+						attemptsMade: bullJob.attemptsMade ?? 0,
+						timestamp: Date.now(),
+						signal
+					};
+					return job.handler(bullJob.data, meta);
+				}
+			});
 			if (bridgeEvents && fastify.events?.publish) try {
 				await fastify.events.publish(`job.${queueName}.completed`, {
 					jobId: bullJob.id,
@@ -366,4 +391,22 @@ const jobsPlugin = fp(jobsPluginImpl, {
 	fastify: "5.x"
 });
 //#endregion
-export { defineJob, jobsPlugin };
+//#region src/integrations/jobs/types.ts
+/**
+* Define a background job with typed data and configuration.
+*
+* @example
+* const processImage = defineJob({
+*   name: 'process-image',
+*   handler: async (data: { url: string; width: number }) => {
+*     return await sharp(data.url).resize(data.width).toBuffer();
+*   },
+*   retries: 3,
+*   timeout: 60000,
+* });
+*/
+function defineJob(definition) {
+	return definition;
+}
+//#endregion
+export { defineJob, executeTimedHandler, jobsPlugin };

package/dist/integrations/mcp/index.d.mts

@@ -1,7 +1,8 @@
-import { Rt as IControllerResponse, V as ResourceDefinition, zt as IRequestContext } from "../../index-DbtgCOCj.mjs";
-import { i as RequestScope } from "../../types-DH0GupI7.mjs";
-import { t as PermissionCheck } from "../../types-Csxga7d3.mjs";
-import { a as CrudDescriptionOverride, c as McpAuthResult, d as PromptDefinition, f as PromptResult, g as ToolDefinition, h as ToolContext, i as CrudDescriptionMeta, l as McpPluginOptions, m as ToolAnnotations, n as CallToolResult, o as CrudOperation, p as SessionEntry, r as CreateMcpServerConfig, s as McpAuthResolver, t as BetterAuthHandler, u as McpResourceConfig } from "../../types-Bc42CUyk.mjs";
+import { Rt as IControllerResponse, V as ResourceDefinition, Vt as ServerAccessor, zt as IRequestContext } from "../../index-DPRH0Cme.mjs";
+import { i as RequestScope } from "../../types-DjC-KUCz.mjs";
+import { t as PermissionCheck } from "../../types-Dmw-6Qeo.mjs";
+import { n as FieldPermissionMap } from "../../fields-D3lhgzhD.mjs";
+import { _ as ToolDefinition, a as CrudDescriptionOverride, c as McpAuthResult, d as McpResourceConfig, f as PromptDefinition, g as ToolContext, h as ToolAnnotations, i as CrudDescriptionMeta, l as McpExecutionWiring, m as SessionEntry, n as CallToolResult, o as CrudOperation, p as PromptResult, r as CreateMcpServerConfig, s as McpAuthResolver, t as BetterAuthHandler, u as McpPluginOptions } from "../../types-QFGc3Cjv.mjs";
 import { ErrorContract } from "@classytic/repo-core/errors";
 import { FastifyPluginAsync } from "fastify";
 import { z } from "zod";
@@ -299,6 +300,34 @@ declare function customGuard(check: (ctx: ToolContext) => boolean | Promise<bool
 //#endregion
 //#region src/integrations/mcp/buildRequestContext.d.ts
 type McpOperation = "list" | "get" | "create" | "update" | "delete" | "action";
+/**
+ * Optional context extras — the pieces of `IRequestContext` that HTTP's
+ * `createRequestContext` assembles from Fastify decorators and the MCP
+ * synthetic path historically DROPPED. Without them, controller code that
+ * reads `metadata.arc.hooks` (the whole hook system — including the
+ * arcCorePlugin after-hook that publishes `<resource>.<op>d` events) or
+ * `ctx.server.events` silently no-ops on MCP calls: agents could mutate
+ * records without hooks firing, events publishing, realtime feeds updating,
+ * or webhooks dispatching. Thread these through `invokeController` /
+ * `resourceToTools({ wiring })` to restore full HTTP ↔ MCP parity.
+ */
+interface McpContextExtras {
+  /**
+   * Resource wiring — becomes `metadata.arc`, the same frozen shape
+   * `buildArcDecorator` stamps on HTTP requests (`ArcRouteMeta`).
+   */
+  arc?: {
+    readonly resourceName: string;
+    readonly schemaOptions?: unknown;
+    readonly permissions?: unknown;
+    readonly hooks?: unknown;
+    readonly events?: unknown;
+    readonly fields?: unknown;
+    readonly idField?: string;
+  };
+  /** Server accessor — `ctx.server.events/audit/log`, mirroring HTTP. */
+  server?: ServerAccessor;
+}
 /**
  * Build an IRequestContext from MCP tool input and session auth.
  *
@@ -317,7 +346,7 @@ type McpOperation = "list" | "get" | "create" | "update" | "delete" | "action";
  * the session-derived scope is `public` (i.e. MCP called with `auth: false`).
  * An authenticated session scope is never overwritten.
  */
-declare function buildRequestContext(input: Record<string, unknown>, auth: McpAuthResult | null, operation: McpOperation, policyFilters?: Record<string, unknown>, scopeOverride?: RequestScope): IRequestContext;
+declare function buildRequestContext(input: Record<string, unknown>, auth: McpAuthResult | null, operation: McpOperation, policyFilters?: Record<string, unknown>, scopeOverride?: RequestScope, extras?: McpContextExtras): IRequestContext;
 //#endregion
 //#region src/integrations/mcp/invokeController.d.ts
 /**
@@ -349,6 +378,33 @@ interface InvokeControllerOptions {
    * action handler reached through a `string` route handler).
    */
   readonly methodName?: string;
+  /**
+   * Resource field-permission map (`ResourceConfig.fields`). When present,
+   * field-level READ permissions are applied to the response payload before
+   * serialization — the same masking the HTTP wire and realtime frames get.
+   * Omit only for tools whose output carries no resource documents.
+   */
+  readonly fields?: FieldPermissionMap;
+  /**
+   * App-level execution wiring (hooks system, event bus, audit, logger,
+   * idempotency store). When present, the synthetic request context carries
+   * `metadata.arc` + `server` exactly like HTTP's `createRequestContext` —
+   * so resource hooks run, CRUD events publish, and `ctx.server.*` works.
+   * `mcpPlugin` supplies this automatically; omit for dispatch-only calls.
+   */
+  readonly wiring?: McpExecutionWiring;
+  /** Resource `schemaOptions` — rides on `metadata.arc` like HTTP. */
+  readonly schemaOptions?: unknown;
+  /** Resource `idField` — rides on `metadata.arc` for `getEntityIdField()`. */
+  readonly idField?: string;
+  /**
+   * Caller-supplied idempotency key (mutations only). Requires
+   * `wiring.idempotencyStore`; the executor then runs the same
+   * check → lock → execute → record → replay protocol the HTTP
+   * idempotency plugin runs, keyed by tool + input + caller identity.
+   * A concurrent call with the same key gets a 409 `arc.idempotency_conflict`.
+   */
+  readonly idempotencyKey?: string;
 }
 /**
  * Invoke a controller method through the MCP synthetic-context path.
@@ -549,6 +605,13 @@ interface ResourceToToolsConfig extends McpResourceConfig {
   toolNamePrefix?: string;
   /** Per-operation tool name overrides: `{ get: 'get_job_by_id' }` */
   names?: Partial<Record<CrudOperation, string>>;
+  /**
+   * App-level execution wiring (hooks, events, audit, log, idempotency
+   * store). `mcpPlugin` supplies this automatically from its Fastify
+   * instance; standalone callers pass their own or omit it for
+   * dispatch-only tools (no hooks/events/idempotency).
+   */
+  wiring?: McpExecutionWiring;
 }
 /**
  * Convert a ResourceDefinition into MCP ToolDefinitions.

package/dist/integrations/mcp/index.mjs

@@ -1,4 +1,4 @@
-import { a as defaultCrudDescription, c as mcpHandlerAdapter, d as toCallToolResult, f as toCallToolSuccess, h as resolveToolCollisions, i as fieldRulesToZod, l as permissionDeniedResult, m as createMcpServer, n as mcpPlugin, o as resolveCrudDescription, p as buildRequestContext, r as resourceToTools, s as invokeController, t as filterResourcesForMcp, u as toCallToolError } from "../../mcpPlugin-ByA2tf6D.mjs";
+import { a as defaultCrudDescription, c as mcpHandlerAdapter, d as toCallToolResult, f as toCallToolSuccess, h as resolveToolCollisions, i as fieldRulesToZod, l as permissionDeniedResult, m as createMcpServer, n as mcpPlugin, o as resolveCrudDescription, p as buildRequestContext, r as resourceToTools, s as invokeController, t as filterResourcesForMcp, u as toCallToolError } from "../../mcpPlugin-Cb7olw0j.mjs";
 //#region src/integrations/mcp/defineTool.ts
 /**
 * Define a type-safe MCP tool.
@@ -206,7 +206,7 @@ function createMcpAuthFromBetterAuthApiKey(auth, options = {}) {
 			...userId ? { userId } : {},
 			...organizationId ? { organizationId } : {},
 			...clientId ? { clientId } : {},
-			...scopes && scopes.length ? { scopes } : {}
+			...scopes?.length ? { scopes } : {}
 		};
 	};
 }

package/dist/integrations/mcp/testing.d.mts

@@ -1,4 +1,4 @@
-import { c as McpAuthResult, l as McpPluginOptions } from "../../types-Bc42CUyk.mjs";
+import { c as McpAuthResult, u as McpPluginOptions } from "../../types-QFGc3Cjv.mjs";
 //#region src/integrations/mcp/testing.d.ts
 interface TestMcpClientOptions {
   /** MCP plugin options (resources, overrides, etc.) — same as mcpPlugin config */

package/dist/integrations/mcp/testing.mjs

@@ -1,4 +1,4 @@
-import { m as createMcpServer, r as resourceToTools, t as filterResourcesForMcp } from "../../mcpPlugin-ByA2tf6D.mjs";
+import { m as createMcpServer, r as resourceToTools, t as filterResourcesForMcp } from "../../mcpPlugin-Cb7olw0j.mjs";
 //#region src/integrations/mcp/testing.ts
 /**
 * @classytic/arc/mcp/testing — MCP Test Utilities

package/dist/integrations/webhooks.d.mts

@@ -19,6 +19,8 @@ interface WebhookDeliveryRecord {
   status?: number;
   error?: string;
   timestamp: Date;
+  /** Delivery attempts made (present when `retry` is configured). */
+  attempts?: number;
 }
 /** Pluggable persistence — memory for dev, bring your own DB for prod */
 interface WebhookStore {
@@ -36,13 +38,70 @@ interface WebhookPluginOptions {
   timeout?: number;
   /** Max delivery log entries kept in memory (default: 1000) */
   maxLogEntries?: number;
-  /** Max concurrent deliveries per event (default: 5). Set to 1 for sequential. */
+  /**
+   * Max concurrent deliveries per event (default: 5). Set to 1 for
+   * sequential. Must be >= 1 — the plugin throws at registration otherwise
+   * (a zero would make the delivery loop spin forever without progress).
+   */
   concurrency?: number;
+  /**
+   * In-process retry for failed deliveries. Default: single attempt.
+   * Retries fire on network errors, timeouts, 429 and 5xx — NOT on other
+   * 4xx (the receiver rejected the payload; repeating it can't succeed).
+   * Each attempt is re-signed with a fresh timestamp so the receiver's
+   * replay-tolerance window applies per attempt; `x-arc-webhook-delivery`
+   * stays constant, which is exactly what receiver-side dedup keys on.
+   *
+   * This is BEST-EFFORT: attempts live in this process, so a crash or
+   * deploy drops the remaining ones. Guaranteed delivery is a durable-job
+   * concern (queue keyed by subscription + delivery id) — pair the events
+   * outbox with a worker if you need it.
+   */
+  retry?: {
+    /** Total attempts including the first. Must be an integer >= 1. */
+    attempts: number;
+    /** Backoff before retry N, as `backoffMs * 2^(N-1)` ms (default: 1000). */
+    backoffMs?: number;
+  };
+  /**
+   * URL policy hook — the SSRF seam for tenant-registered URLs. Throw to
+   * reject. Pass {@link defaultWebhookUrlPolicy} to require HTTPS and block
+   * localhost / link-local / private-network / cloud-metadata destinations,
+   * or supply your own (allowlists, per-tenant rules).
+   *
+   * Enforcement points when set:
+   *  - `register()` — new subscriptions are validated BEFORE saving.
+   *  - Plugin init — every PERSISTED subscription is re-validated; failures
+   *    are excluded from dispatch and logged (they stay in the store for
+   *    the host to fix), so pre-policy rows and out-of-band store writes
+   *    can't bypass the policy.
+   *  - Delivery — `fetch` runs with `redirect: "manual"`, so an allowed
+   *    public URL can't 302 into a blocked private/metadata target; a 3xx
+   *    records as a failed delivery.
+   *
+   * Arc deliberately ships no DEFAULT policy — deployments differ (internal
+   * webhooks to private services are legitimate), and DNS-rebinding
+   * protection belongs at the actual outbound network boundary, not in the
+   * framework.
+   */
+  validateUrl?: (url: URL, subscription: WebhookSubscription) => void | Promise<void>;
 }
+/** `WebhookSubscription` as returned by `list()` — secret withheld. */
+type WebhookSubscriptionPublic = Omit<WebhookSubscription, "secret">;
 interface WebhookManager {
   register(sub: WebhookSubscription): Promise<void> | void;
   unregister(id: string): Promise<void> | void;
-  list(): WebhookSubscription[];
+  /**
+   * Enumerate subscriptions WITHOUT their secrets — safe to surface in
+   * admin UIs / API responses. Use {@link WebhookManager.getSecret} for
+   * the privileged retrieval path.
+   */
+  list(): WebhookSubscriptionPublic[];
+  /**
+   * Privileged secret retrieval — separate from `list()` so enumerating
+   * subscriptions never leaks signing material into logs or UIs.
+   */
+  getSecret(id: string): string | undefined;
   deliveryLog(limit?: number): WebhookDeliveryRecord[];
 }
 declare module "fastify" {
@@ -51,11 +110,80 @@ declare module "fastify" {
   }
 }
 /**
- * Sign a payload with HMAC-SHA256 for outbound webhook delivery.
+ * Signed-string layout for the v1 webhook contract:
+ *
+ *     v1.<timestampMs>.<deliveryId>.<body>
  *
- * @returns `sha256=<hex>` — the format written to `x-webhook-signature`
+ * Binding the timestamp bounds replay to the verifier's tolerance window,
+ * and binding the delivery id lets receivers deduplicate redeliveries on an
+ * AUTHENTICATED value (the legacy `x-webhook-id` header was unsigned — an
+ * attacker replaying a captured request could change it and defeat dedup).
+ *
+ * Wire headers:
+ *   - `x-arc-webhook-signature: v1=<hex hmac-sha256>`
+ *   - `x-arc-webhook-timestamp: <unix epoch ms>`
+ *   - `x-arc-webhook-delivery:  <delivery id>` (arc sends the event's
+ *     `meta.id` — STABLE across retries of the same event, so dedup on it
+ *     collapses redeliveries)
  */
-declare function signPayload(payload: string, secret: string): string;
+declare function signWebhook(body: string, secret: string, meta: {
+  timestamp: number;
+  deliveryId: string;
+}): string;
+interface VerifyWebhookInput {
+  /** Raw request body — the exact bytes the sender signed (`req.rawBody`). */
+  body: string | Buffer;
+  /** Shared secret. */
+  secret: string;
+  /** `x-arc-webhook-signature` header value (`v1=<hex>`). */
+  signature: string | undefined;
+  /** `x-arc-webhook-timestamp` header value (unix epoch ms). */
+  timestamp: string | number | undefined;
+  /** `x-arc-webhook-delivery` header value. */
+  deliveryId: string | undefined;
+  /**
+   * Max allowed clock skew between sender timestamp and now, in ms.
+   * @default 300_000 (5 minutes)
+   */
+  toleranceMs?: number;
+  /** Injectable clock for tests. @default Date.now */
+  now?: () => number;
+}
+type VerifyWebhookResult = {
+  valid: true;
+  /** The AUTHENTICATED delivery id — dedup redeliveries on this. */
+  deliveryId: string;
+  /** Sender timestamp (unix epoch ms), authenticated. */
+  timestamp: number;
+} | {
+  valid: false;
+  reason: "missing_headers" | "bad_timestamp" | "expired" | "bad_signature";
+};
+/**
+ * Verify an inbound v1 arc webhook: signature + timestamp tolerance, and
+ * return the authenticated delivery id for receiver-side deduplication.
+ *
+ * ⚠ Pass `req.rawBody` (route opted in via `config: { rawBody: true }`),
+ * never the parsed `req.body` — re-serialised JSON won't match the HMAC.
+ *
+ * @example
+ * ```typescript
+ * fastify.post('/hooks/arc', { config: { rawBody: true } }, async (req, reply) => {
+ *   const result = verifyWebhook({
+ *     body: req.rawBody,
+ *     secret: process.env.WEBHOOK_SECRET,
+ *     signature: req.headers['x-arc-webhook-signature'] as string,
+ *     timestamp: req.headers['x-arc-webhook-timestamp'] as string,
+ *     deliveryId: req.headers['x-arc-webhook-delivery'] as string,
+ *   });
+ *   if (!result.valid) return reply.status(401).send({ error: result.reason });
+ *   if (await seen(result.deliveryId)) return reply.send({ ok: true }); // dedup
+ *   // ... handle, then mark result.deliveryId seen
+ * });
+ * ```
+ */
+declare function verifyWebhook(input: VerifyWebhookInput): VerifyWebhookResult;
+declare function defaultWebhookUrlPolicy(url: URL): void;
 /** Options for `verifySignature` — customize for non-Arc webhook senders */
 interface VerifySignatureOptions {
   /**
@@ -65,15 +193,18 @@ interface VerifySignatureOptions {
   prefix?: string;
   /**
    * HMAC algorithm (default: `'sha256'`).
-   * Must match what the sender uses — Arc's `signPayload` always uses sha256.
+   * Must match what the sender uses.
    */
   algorithm?: string;
 }
 /**
- * Verify an inbound webhook signature using timing-safe comparison.
+ * Verify an INBOUND third-party webhook signature using timing-safe
+ * comparison — for webhooks arc RECEIVES (GitHub, Stripe, ...), not for
+ * arc-to-arc delivery. Arc's own outbound contract is v1
+ * (`x-arc-webhook-*`) — receivers of arc webhooks use {@link verifyWebhook}.
  *
- * Works with Arc's own `signPayload` format by default (`sha256=<hex>`),
- * but configurable for any HMAC scheme via options.
+ * Defaults to the common `sha256=<hex>` format; configurable for any HMAC
+ * scheme via options.
  *
  * ⚠ The `body` argument must be the exact bytes the sender signed. Fastify
  * parses JSON bodies by default and the re-serialised object will NOT match
@@ -91,21 +222,17 @@ interface VerifySignatureOptions {
  * ```typescript
  * import { verifySignature } from '@classytic/arc/integrations/webhooks';
  *
- * // Arc-to-Arc (default headers + format). `config: { rawBody: true }` is
- * // REQUIRED — arc registers fastify-raw-body with `global: false`, so
- * // routes opt in per-route; without it `req.rawBody` is undefined and
- * // verifySignature throws a TypeError.
- * fastify.post('/webhooks/incoming', { config: { rawBody: true } }, async (req, reply) => {
- *   const sig = req.headers['x-webhook-signature'] as string;
+ * // `config: { rawBody: true }` is REQUIRED — arc registers
+ * // fastify-raw-body with `global: false`, so routes opt in per-route;
+ * // without it `req.rawBody` is undefined and verifySignature throws a
+ * // TypeError.
+ *
+ * // GitHub-style sender (sha256=<hex>)
+ * fastify.post('/webhooks/github', { config: { rawBody: true } }, async (req, reply) => {
+ *   const sig = req.headers['x-hub-signature-256'] as string;
  *   if (!verifySignature(req.rawBody, secret, sig)) {
  *     return reply.status(401).send({ error: 'Invalid signature' });
  *   }
- *   // handle event via req.headers['x-webhook-event']
- * });
- *
- * // Third-party sender with custom header + bare hex
- * const valid = verifySignature(body, secret, req.headers['x-hub-signature'], {
- *   prefix: 'sha256=',  // GitHub format
  * });
  *
  * // Stripe-style (bare hex, different header)
@@ -118,4 +245,4 @@ declare function verifySignature(body: string | Buffer, secret: string, signatur
 declare const webhookPlugin: FastifyPluginAsync<WebhookPluginOptions>;
 declare const _default: FastifyPluginAsync<WebhookPluginOptions>;
 //#endregion
-export { VerifySignatureOptions, WebhookDeliveryRecord, WebhookManager, WebhookPluginOptions, WebhookStore, WebhookSubscription, _default as default, signPayload, verifySignature, webhookPlugin };
+export { VerifySignatureOptions, VerifyWebhookInput, VerifyWebhookResult, WebhookDeliveryRecord, WebhookManager, WebhookPluginOptions, WebhookStore, WebhookSubscription, WebhookSubscriptionPublic, _default as default, defaultWebhookUrlPolicy, signWebhook, verifySignature, verifyWebhook, webhookPlugin };