@classytic/arc 2.21.0 → 2.23.0

package/dist/{init-0YhHkXGk.mjs → init-CjO4p_q1.mjs}

@@ -1,3 +1,4 @@
+import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.mjs";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { dirname, join } from "node:path";
@@ -76,6 +77,60 @@ export function createAdapter${ts ? "<TDoc = unknown>" : ""}(
 `;
 }
 //#endregion
+//#region src/cli/commands/init/templates/agents.ts
+function agentsGuideTemplate(config) {
+	return `# CLAUDE.md — agent guide for this app
+
+> This file doubles as AGENTS.md — copy or symlink if your tool reads that name.
+
+**This is an \`@classytic/arc\` application.** Resources are DECLARED, not hand-rolled:
+one \`defineResource()\` = REST + validation + auth + permissions + events + caching +
+OpenAPI + MCP tools. Data layer: ${config.adapter === "mongokit" ? "@classytic/mongokit (Mongoose)" : "a custom DataAdapter kit"}.
+
+## The one rule
+
+**Hand-rolling is a bug.** Before writing ANY route, validation, pagination, auth check,
+cron, counter, or audit code by hand, prove arc lacks it — check the table below, then
+\`node_modules/@classytic/arc/skills/arc/SKILL.md\` (full framework guide + references).
+
+## About to write X? Arc already has Y
+
+| If you're about to write… | Use instead |
+|---|---|
+| \`fastify.get/post/...\` CRUD routes for an entity | \`defineResource({ name, adapter, permissions })\` |
+| \`if (req.user.role !== 'admin') return 403\` | \`permissions: { update: requireRoles(['admin']) }\` |
+| Reading \`req.user._id\` / org id directly | \`getUserId(scope)\` / \`requireOrgId(scope)\` from \`@classytic/arc/scope\` |
+| Hand-written \`schema: { body }\` / JSON Schema | \`schemaOptions.fieldRules\` (or \`customSchemas\` for wire≠model) |
+| toJSON transforms hiding \`password\`/internals | \`fieldRules: { password: { hidden: true } }\` |
+| Manual \`req.query\` filter/sort/pagination parsing | the resource's \`queryParser\` (allow-listed fields) |
+| Soft delete / slug lookup / tree / bulk / file upload | \`presets: ['softDelete', 'slugLookup', ...]\` |
+| \`setInterval\` sweeps + hand-rolled leader lock | \`schedulesPlugin\` (\`@classytic/arc/plugins\`) |
+| A background/queue worker entrypoint | \`createWorker(sameOptions)\` (\`@classytic/arc/factory\`) |
+| Usage counters / quotas / plan rate limits | \`usagePlugin\` + \`requireQuota\` + \`rateLimit.plan\` |
+| Audit log rows / "who changed what" endpoints | \`audit: true\` + \`history: true\` on the resource |
+| Manual idempotency keys / dedupe | \`idempotencyPlugin\` |
+| Event emitters / webhooks plumbing | \`eventPlugin\` + resource \`events:\` (+ outbox for guarantees) |
+| Custom MCP/AI tool handlers | generated automatically from every resource |
+
+## Load-bearing conventions
+
+- \`request.user\` is \`undefined\` on public routes — always guard.
+- Never read \`scope.organizationId\` directly — use \`@classytic/arc/scope\` accessors.
+- The DB connection belongs in \`createApp({ beforeBoot })\` — not before \`createApp\`.
+- Custom endpoints: \`routes:\`/\`actions:\` on the resource (they inherit auth/permissions/
+  OpenAPI/MCP) — a bare \`fastify.get()\` gets none of that.
+
+## Commands
+
+\`\`\`bash
+npm run dev        # watch mode
+npm test           # vitest
+npx arc generate resource <name>   # scaffold a resource (model/repo/resource files)
+npx arc describe   # list registered resources + routes
+\`\`\`
+`;
+}
+//#endregion
 //#region src/cli/commands/init/templates/app.ts
 function indexTemplate(config) {
 	const ts = config.typescript;
@@ -442,8 +497,8 @@ function betterAuthSetupTemplate(config) {
 import { mongodbAdapter } from '@better-auth/mongo-adapter';` : "";
 	const stubsImport = useStubs ? `import { registerBetterAuthStubs } from '@classytic/mongokit/better-auth';` : "";
 	const pluginImports = [
-		useOrg ? `import { organization } from 'better-auth/plugins';` : "",
-		useBearer ? `import { bearer } from 'better-auth/plugins';` : "",
+		useOrg ? `import { organization } from 'better-auth/plugins/organization';` : "",
+		useBearer ? `import { bearer } from 'better-auth/plugins/bearer';` : "",
 		useApiKey ? `import { apiKey } from '@better-auth/api-key';` : ""
 	].filter(Boolean).join("\n");
 	const dbAdapter = useMongo ? config.typescript ? `database: mongodbAdapter(mongoose.connection.getClient().db() as unknown as never),` : `database: mongodbAdapter(mongoose.connection.getClient().db()),` : `// Configure your database adapter here
@@ -985,6 +1040,11 @@ ${config.adapter === "mongokit" ? `    await mongoose.connection.collection('use
 * `installDependencies` (runs the package manager's `install` against
 * the declared ranges). One source — no drift.
 */
+var dependency_plan_exports = /* @__PURE__ */ __exportAll({
+	SCAFFOLD_DEP_VERSIONS: () => SCAFFOLD_DEP_VERSIONS,
+	primeLatestScaffoldVersions: () => primeLatestScaffoldVersions,
+	resolveScaffoldDependencies: () => resolveScaffoldDependencies
+});
 const SCAFFOLD_DEP_VERSIONS = {
 	core: {
 		"@classytic/arc": "^2.20.0",
@@ -1014,10 +1074,10 @@ const SCAFFOLD_DEP_VERSIONS = {
 	},
 	devCommon: {
 		"@biomejs/biome": "^2.4.15",
-		"mongodb-memory-server": "^11.1.0",
 		"pino-pretty": "^13.1.3",
 		vitest: "^4.1.7"
 	},
+	devMongokit: { "mongodb-memory-server": "^11.1.0" },
 	devTypescript: {
 		"@types/node": "^22.10.0",
 		tsx: "^4.22.3",
@@ -1069,6 +1129,51 @@ function floorLessThan(a, b) {
 *     floor>` when the static pin's floor is BELOW the declared peer floor
 *     (never lowered — static pins may legitimately be ahead of the floor).
 */
+const latestCache = /* @__PURE__ */ new Map();
+function allScaffoldPackageNames() {
+	const names = /* @__PURE__ */ new Set();
+	for (const group of Object.values(SCAFFOLD_DEP_VERSIONS)) for (const name of Object.keys(group)) names.add(name);
+	return [...names];
+}
+async function primeLatestScaffoldVersions(options) {
+	const timeoutMs = options?.timeoutMs ?? 3500;
+	const registry = (options?.registry ?? process.env.npm_config_registry ?? "https://registry.npmjs.org").replace(/\/$/, "");
+	const names = allScaffoldPackageNames();
+	const results = await Promise.allSettled(names.map(async (name) => {
+		const res = await fetch(`${registry}/${name}/latest`, {
+			signal: AbortSignal.timeout(timeoutMs),
+			headers: { accept: "application/json" }
+		});
+		if (!res.ok) throw new Error(String(res.status));
+		const body = await res.json();
+		if (typeof body.version === "string" && /^\d+\.\d+\.\d+$/.test(body.version)) latestCache.set(name, body.version);
+	}));
+	return {
+		resolved: latestCache.size,
+		total: results.length
+	};
+}
+function parseBareVersion(v) {
+	const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(v);
+	return m ? [
+		Number(m[1]),
+		Number(m[2]),
+		Number(m[3])
+	] : void 0;
+}
+function applyLatestOverlay(dependencies) {
+	if (latestCache.size === 0) return;
+	for (const [name, currentRange] of Object.entries(dependencies)) {
+		const latest = latestCache.get(name);
+		if (!latest || latest.includes("-")) continue;
+		const latestV = parseBareVersion(latest);
+		const currentFloor = parseFloor(currentRange);
+		if (!latestV || !currentFloor) continue;
+		if (!floorLessThan(currentFloor, latestV)) continue;
+		if (latestV[0] !== currentFloor[0] && !name.startsWith("@classytic/")) continue;
+		dependencies[name] = `^${latest}`;
+	}
+}
 function overlayLiveArcVersions(dependencies) {
 	const own = readOwnPackageJson();
 	if (!own) return;
@@ -1100,8 +1205,13 @@ function resolveScaffoldDependencies(config) {
 		Object.assign(dependencies, SCAFFOLD_DEP_VERSIONS.authJwt);
 		if (config.typescript) Object.assign(devDependencies, SCAFFOLD_DEP_VERSIONS.typesJwt);
 	}
-	if (config.adapter === "mongokit") Object.assign(dependencies, SCAFFOLD_DEP_VERSIONS.adapterMongokit);
+	if (config.adapter === "mongokit") {
+		Object.assign(dependencies, SCAFFOLD_DEP_VERSIONS.adapterMongokit);
+		Object.assign(devDependencies, SCAFFOLD_DEP_VERSIONS.devMongokit);
+	}
 	if (config.typescript) Object.assign(devDependencies, SCAFFOLD_DEP_VERSIONS.devTypescript);
+	applyLatestOverlay(dependencies);
+	applyLatestOverlay(devDependencies);
 	overlayLiveArcVersions(dependencies);
 	return {
 		dependencies: sortByKey(dependencies),
@@ -3030,6 +3140,7 @@ async function createProjectStructure(projectPath, config) {
 		files["docker-compose.yml"] = dockerComposeTemplate(config);
 	}
 	if (config.edge) files["wrangler.toml"] = wranglerTemplate(config);
+	files["CLAUDE.md"] = agentsGuideTemplate(config);
 	files[".arcrc"] = `${JSON.stringify({
 		adapter: config.adapter,
 		auth: config.auth,
@@ -3329,6 +3440,14 @@ async function init(options = {}) {
 	}
 	const packageManager = detectPackageManager();
 	console.log(`Using package manager: ${packageManager}\n`);
+	if (!process.env.VITEST && process.env.ARC_INIT_OFFLINE !== "1") {
+		const { primeLatestScaffoldVersions } = await Promise.resolve().then(() => dependency_plan_exports);
+		const { resolved, total } = await primeLatestScaffoldVersions().catch(() => ({
+			resolved: 0,
+			total: 0
+		}));
+		console.log(resolved > 0 ? `Resolved ${resolved}/${total} dependency versions from npm (latest stable)\n` : "Registry unreachable — using pinned fallback versions\n");
+	}
 	await createProjectStructure(projectPath, config);
 	if (!options.skipInstall) {
 		console.log("\n📥 Installing dependencies...\n");

package/dist/integrations/event-gateway.mjs

@@ -4,7 +4,7 @@ const eventGatewayPluginImpl = async (fastify, opts = {}) => {
 	const { auth = true, orgScoped = false, roomPolicy, maxMessageBytes, maxSubscriptionsPerClient, authenticate } = opts;
 	if (auth && !authenticate && !fastify.hasDecorator("authenticate")) throw new Error("[arc-event-gateway] auth is true but fastify.authenticate is not registered. Register an auth plugin first, provide a custom authenticate function, or set auth: false.");
 	if (opts.sse !== false) {
-		const { default: ssePlugin } = await import("../sse-CfUjwjDk.mjs").then((n) => n.r);
+		const { default: ssePlugin } = await import("../sse-0u4P4-OI.mjs").then((n) => n.r);
 		await fastify.register(ssePlugin, {
 			path: opts.sse?.path ?? "/events/stream",
 			requireAuth: auth,

package/dist/integrations/index.d.mts

@@ -1,7 +1,7 @@
 import { c as WebSocketClient, l as WebSocketMessage, u as WebSocketPluginOptions } from "../websocket-uuWqM6UY.mjs";
 import { EventGatewayOptions } from "./event-gateway.mjs";
 import { JobDefinition, JobDispatchOptions, JobDispatcher, JobMeta, JobsPluginOptions, QueueStats } from "./jobs.mjs";
-import { c as McpAuthResult, d as PromptDefinition, g as ToolDefinition, h as ToolContext, l as McpPluginOptions, m as ToolAnnotations, n as CallToolResult, o as CrudOperation, r as CreateMcpServerConfig, t as BetterAuthHandler, u as McpResourceConfig } from "../types-DRj-Ut4n.mjs";
+import { _ as ToolDefinition, c as McpAuthResult, d as McpResourceConfig, f as PromptDefinition, g as ToolContext, h as ToolAnnotations, n as CallToolResult, o as CrudOperation, r as CreateMcpServerConfig, t as BetterAuthHandler, u as McpPluginOptions } from "../types-5OuqeTDX.mjs";
 import { StreamlinePluginOptions, WorkflowLike, WorkflowRunLike } from "./streamline.mjs";
 import { WebhookDeliveryRecord, WebhookManager, WebhookPluginOptions, WebhookStore, WebhookSubscription } from "./webhooks.mjs";
 export type { BetterAuthHandler, CallToolResult, CreateMcpServerConfig, CrudOperation, EventGatewayOptions, JobDefinition, JobDispatchOptions, JobDispatcher, JobMeta, JobsPluginOptions, McpAuthResult, McpPluginOptions, McpResourceConfig, PromptDefinition, QueueStats, StreamlinePluginOptions, ToolAnnotations, ToolContext, ToolDefinition, WebSocketClient, WebSocketMessage, WebSocketPluginOptions, WebhookDeliveryRecord, WebhookManager, WebhookPluginOptions, WebhookStore, WebhookSubscription, WorkflowLike, WorkflowRunLike };

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

@@ -1,7 +1,8 @@
-import { V as ResourceDefinition, bt as IControllerResponse, xt as IRequestContext } from "../../index-Dtrj6XZk.mjs";
+import { Rt as IControllerResponse, V as ResourceDefinition, Vt as ServerAccessor, zt as IRequestContext } from "../../index-BBsvQt7U.mjs";
 import { i as RequestScope } from "../../types-DH0GupI7.mjs";
-import { c as PermissionCheck } from "../../fields-BGqrAa_u.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-DRj-Ut4n.mjs";
+import { t as PermissionCheck } from "../../types-Csxga7d3.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-5OuqeTDX.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-B9XjjNVG.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-BtzIL_kM.mjs";
 //#region src/integrations/mcp/defineTool.ts
 /**
 * Define a type-safe MCP tool.

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

@@ -1,4 +1,4 @@
-import { c as McpAuthResult, l as McpPluginOptions } from "../../types-DRj-Ut4n.mjs";
+import { c as McpAuthResult, u as McpPluginOptions } from "../../types-5OuqeTDX.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-B9XjjNVG.mjs";
+import { m as createMcpServer, r as resourceToTools, t as filterResourcesForMcp } from "../../mcpPlugin-BtzIL_kM.mjs";
 //#region src/integrations/mcp/testing.ts
 /**
 * @classytic/arc/mcp/testing — MCP Test Utilities

package/dist/integrations/webhooks.d.mts

@@ -36,13 +36,51 @@ 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;
+  /**
+   * 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" {
@@ -53,9 +91,91 @@ declare module "fastify" {
 /**
  * Sign a payload with HMAC-SHA256 for outbound webhook delivery.
  *
+ * @deprecated LEGACY (pre-2.23) format — signs the BODY ONLY, so a captured
+ * request can be replayed indefinitely and the event-id header is not
+ * cryptographically bound to the body. Still emitted on the legacy
+ * `x-webhook-signature` header for existing receivers; new receivers should
+ * verify the v1 contract (`x-arc-webhook-signature`) via {@link verifyWebhook}.
+ * Legacy emission is scheduled for removal in v3.
+ *
  * @returns `sha256=<hex>` — the format written to `x-webhook-signature`
  */
 declare function signPayload(payload: string, secret: string): string;
+/**
+ * Signed-string layout for the v1 webhook contract:
+ *
+ *     v1.<timestampMs>.<deliveryId>.<body>
+ *
+ * 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 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 {
   /**
@@ -77,8 +197,9 @@ interface VerifySignatureOptions {
  *
  * ⚠ 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
- * the original signature. Register `@fastify/raw-body` or use `preParsing`
- * to capture `req.rawBody`, then pass that here.
+ * the original signature. Register `fastify-raw-body` (arc's createApp does
+ * this automatically with `global: false`) and opt the route in via
+ * `config: { rawBody: true }`, then pass `req.rawBody` here.
  *
  * @param body      - Raw request body (string or Buffer — must be the exact bytes the sender signed)
  * @param secret    - Shared secret between sender and receiver
@@ -90,8 +211,11 @@ interface VerifySignatureOptions {
  * ```typescript
  * import { verifySignature } from '@classytic/arc/integrations/webhooks';
  *
- * // Arc-to-Arc (default headers + format)
- * fastify.post('/webhooks/incoming', async (req, reply) => {
+ * // 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;
  *   if (!verifySignature(req.rawBody, secret, sig)) {
  *     return reply.status(401).send({ error: 'Invalid signature' });
@@ -114,4 +238,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, signPayload, signWebhook, verifySignature, verifyWebhook, webhookPlugin };