@classytic/arc 2.23.0 → 2.25.0

package/skills/arc/references/api-reference.md

@@ -115,8 +115,10 @@ import {
   healthPlugin, gracefulShutdownPlugin, ssePlugin,
   metricsPlugin, versioningPlugin,
   schedulesPlugin,   // 2.21: interval jobs, optional LockAdapter leader lease, no Redis
-  type ScheduleLockLike, type ScheduleDefinition,
+  type ScheduleDefinition,
 } from '@classytic/arc/plugins';
+// Lock contract (schedules.lock / MigrationRunner.lock) — one ecosystem standard:
+// import type { LockAdapter } from '@classytic/repo-core/lock';
 import { tracingPlugin } from '@classytic/arc/plugins/tracing';
 import { auditPlugin } from '@classytic/arc/audit';
 import { idempotencyPlugin } from '@classytic/arc/idempotency';

package/skills/arc/references/integrations.md

@@ -335,7 +335,8 @@ Events published via `fastify.events.publish()` auto-deliver to matching webhook
 ```typescript
 await app.events.publish('order.created', { orderId: '123' });
 // → POST https://customer.com/webhook
-//   Headers: x-webhook-signature, x-webhook-id, x-webhook-event
+//   Headers: x-arc-webhook-signature (v1=<hmac>), x-arc-webhook-timestamp,
+//            x-arc-webhook-delivery (= event meta.id, stable across retries)
 //   Body: { type, payload, meta }
 ```
 
@@ -343,23 +344,31 @@ Deliveries run with bounded concurrency (default: 5) — one slow endpoint won't
 
 ### HMAC Signing & Verification
 
-**Outbound** — every delivery is signed with the subscription's secret:
+**Outbound** — every delivery is signed with the subscription's secret using the v1 contract (timestamp + delivery id are INSIDE the signed string — replay-bounded, dedup on an authenticated id):
 
 ```
-x-webhook-signature: sha256=a1b2c3...
+x-arc-webhook-signature: v1=a1b2c3...
+x-arc-webhook-timestamp: 1784640000000
+x-arc-webhook-delivery:  evt_...
 ```
 
-**Inbound** — verify with `verifySignature()` (timing-safe, never throws):
+**Inbound from arc** — verify with `verifyWebhook()` (signature + tolerance window, typed failure reasons):
 
 ```typescript
-import { verifySignature } from '@classytic/arc/integrations/webhooks';
-
-fastify.post('/webhooks/incoming', 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' });
+import { verifyWebhook } from '@classytic/arc/integrations/webhooks';
+
+fastify.post('/webhooks/incoming', { config: { rawBody: true } }, async (req, reply) => {
+  const result = verifyWebhook({
+    body: req.rawBody as string,
+    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 });
   }
-  // handle event via req.headers['x-webhook-event']
+  // dedup on result.deliveryId, then handle the event
 });
 ```
 

package/dist/QueryCache-Z1B38koh.d.mts

@@ -1,40 +0,0 @@
-import { r as CacheStore } from "./interface-C1_WLTMK.mjs";
-//#region src/cache/QueryCache.d.ts
-/** Metadata wrapper stored in CacheStore */
-interface CacheEnvelope<T = unknown> {
-  data: T;
-  createdAt: number;
-  staleAfter: number;
-  expiresAt: number;
-  tags: string[];
-}
-interface QueryCacheConfig {
-  /** Seconds data is "fresh" (no revalidation). Default: 0 */
-  staleTime?: number;
-  /** Seconds stale data stays cached (SWR window). Default: 60 */
-  gcTime?: number;
-  /** Tags for group invalidation */
-  tags?: string[];
-}
-type CacheStatus = "fresh" | "stale" | "miss";
-interface CacheResult<T> {
-  data: T;
-  status: CacheStatus;
-}
-declare class QueryCache {
-  private readonly store;
-  constructor(store: CacheStore);
-  get<T>(key: string): Promise<CacheResult<T>>;
-  set<T>(key: string, data: T, config: QueryCacheConfig): Promise<void>;
-  invalidate(key: string): Promise<void>;
-  /** Get current version for a resource (defaults to 0 if not set) */
-  getResourceVersion(resource: string): Promise<number>;
-  /** Bump resource version — orphans all cached queries for this resource */
-  bumpResourceVersion(resource: string): Promise<void>;
-  /** Get current version for a tag */
-  getTagVersion(tag: string): Promise<number>;
-  /** Bump tag version — orphans all cached queries tagged with this tag */
-  bumpTagVersion(tag: string): Promise<void>;
-}
-//#endregion
-export { QueryCacheConfig as a, QueryCache as i, CacheResult as n, CacheStatus as r, CacheEnvelope as t };

package/dist/betterAuthOpenApi-CV1lxpRX.mjs

@@ -1,2 +0,0 @@
-import { extractBetterAuthOpenApi } from "./auth/index.mjs";
-export { extractBetterAuthOpenApi };

package/dist/health-ScyjIVo5.mjs

@@ -1,202 +0,0 @@
-import fp from "fastify-plugin";
-//#region src/plugins/health.ts
-function createHttpMetrics() {
-	return {
-		requestsTotal: {},
-		requestDurations: [],
-		_ringIndex: 0,
-		startTime: Date.now()
-	};
-}
-const healthPlugin = async (fastify, opts = {}) => {
-	const { prefix = "/_health", checks = [], metrics = false, metricsCollector, version, collectHttpMetrics = metrics } = opts;
-	const httpMetrics = createHttpMetrics();
-	fastify.get(prefix, { schema: {
-		tags: ["Health"],
-		summary: "Liveness probe (alias for /live)",
-		description: "Returns 200 if the process is alive",
-		response: { 200: {
-			type: "object",
-			properties: {
-				status: {
-					type: "string",
-					enum: ["ok"]
-				},
-				timestamp: { type: "string" },
-				version: { type: "string" }
-			}
-		} }
-	} }, async () => ({
-		status: "ok",
-		timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-		...version ? { version } : {}
-	}));
-	fastify.get(`${prefix}/live`, { schema: {
-		tags: ["Health"],
-		summary: "Liveness probe",
-		description: "Returns 200 if the process is alive",
-		response: { 200: {
-			type: "object",
-			properties: {
-				status: {
-					type: "string",
-					enum: ["ok"]
-				},
-				timestamp: { type: "string" },
-				version: { type: "string" }
-			}
-		} }
-	} }, async () => {
-		return {
-			status: "ok",
-			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-			...version ? { version } : {}
-		};
-	});
-	fastify.get(`${prefix}/ready`, { schema: {
-		tags: ["Health"],
-		summary: "Readiness probe",
-		description: "Returns 200 if all dependencies are healthy",
-		response: {
-			200: {
-				type: "object",
-				properties: {
-					status: {
-						type: "string",
-						enum: ["ready", "not_ready"]
-					},
-					timestamp: { type: "string" },
-					checks: {
-						type: "array",
-						items: {
-							type: "object",
-							properties: {
-								name: { type: "string" },
-								healthy: { type: "boolean" },
-								duration: { type: "number" },
-								error: { type: "string" }
-							}
-						}
-					}
-				}
-			},
-			503: {
-				type: "object",
-				properties: {
-					status: {
-						type: "string",
-						enum: ["not_ready"]
-					},
-					timestamp: { type: "string" },
-					checks: { type: "array" }
-				}
-			}
-		}
-	} }, async (_, reply) => {
-		const results = await runChecks(checks);
-		const criticalFailed = results.some((r) => !r.healthy && (checks.find((c) => c.name === r.name)?.critical ?? true));
-		const response = {
-			status: criticalFailed ? "not_ready" : "ready",
-			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-			checks: results
-		};
-		if (criticalFailed) reply.code(503);
-		return response;
-	});
-	if (metrics) fastify.get(`${prefix}/metrics`, async (_, reply) => {
-		reply.type("text/plain; charset=utf-8");
-		if (metricsCollector) return await metricsCollector();
-		const uptime = process.uptime();
-		const memory = process.memoryUsage();
-		const cpu = process.cpuUsage();
-		const lines = [
-			"# HELP process_uptime_seconds Process uptime in seconds",
-			"# TYPE process_uptime_seconds gauge",
-			`process_uptime_seconds ${uptime.toFixed(2)}`,
-			"",
-			"# HELP process_memory_heap_bytes Heap memory usage in bytes",
-			"# TYPE process_memory_heap_bytes gauge",
-			`process_memory_heap_bytes{type="used"} ${memory.heapUsed}`,
-			`process_memory_heap_bytes{type="total"} ${memory.heapTotal}`,
-			"",
-			"# HELP process_memory_rss_bytes RSS memory in bytes",
-			"# TYPE process_memory_rss_bytes gauge",
-			`process_memory_rss_bytes ${memory.rss}`,
-			"",
-			"# HELP process_memory_external_bytes External memory in bytes",
-			"# TYPE process_memory_external_bytes gauge",
-			`process_memory_external_bytes ${memory.external}`,
-			"",
-			"# HELP process_cpu_user_microseconds User CPU time in microseconds",
-			"# TYPE process_cpu_user_microseconds counter",
-			`process_cpu_user_microseconds ${cpu.user}`,
-			"",
-			"# HELP process_cpu_system_microseconds System CPU time in microseconds",
-			"# TYPE process_cpu_system_microseconds counter",
-			`process_cpu_system_microseconds ${cpu.system}`,
-			""
-		];
-		if (collectHttpMetrics && Object.keys(httpMetrics.requestsTotal).length > 0) {
-			lines.push("# HELP http_requests_total Total HTTP requests by status code", "# TYPE http_requests_total counter");
-			for (const [status, count] of Object.entries(httpMetrics.requestsTotal)) lines.push(`http_requests_total{status="${status}"} ${count}`);
-			lines.push("");
-			if (httpMetrics.requestDurations.length > 0) {
-				const sorted = [...httpMetrics.requestDurations].sort((a, b) => a - b);
-				const p50 = sorted[Math.floor(sorted.length * .5)] || 0;
-				const p95 = sorted[Math.floor(sorted.length * .95)] || 0;
-				const p99 = sorted[Math.floor(sorted.length * .99)] || 0;
-				const sum = sorted.reduce((a, b) => a + b, 0);
-				lines.push("# HELP http_request_duration_milliseconds HTTP request duration", "# TYPE http_request_duration_milliseconds summary", `http_request_duration_milliseconds{quantile="0.5"} ${p50.toFixed(2)}`, `http_request_duration_milliseconds{quantile="0.95"} ${p95.toFixed(2)}`, `http_request_duration_milliseconds{quantile="0.99"} ${p99.toFixed(2)}`, `http_request_duration_milliseconds_sum ${sum.toFixed(2)}`, `http_request_duration_milliseconds_count ${sorted.length}`, "");
-			}
-		}
-		return lines.join("\n");
-	});
-	if (collectHttpMetrics) fastify.addHook("onResponse", async (_request, reply) => {
-		const duration = reply.elapsedTime;
-		const statusBucket = `${Math.floor(reply.statusCode / 100)}xx`;
-		httpMetrics.requestsTotal[statusBucket] = (httpMetrics.requestsTotal[statusBucket] || 0) + 1;
-		if (httpMetrics.requestDurations.length < 1e4) httpMetrics.requestDurations.push(duration);
-		else httpMetrics.requestDurations[httpMetrics._ringIndex % 1e4] = duration;
-		httpMetrics._ringIndex = httpMetrics._ringIndex + 1;
-	});
-	fastify.log?.debug?.(`Health plugin registered at ${prefix} (alias), ${prefix}/live, ${prefix}/ready${metrics ? `, ${prefix}/metrics` : ""}`);
-};
-/**
-* Run all health checks with timeout
-*/
-async function runChecks(checks) {
-	const results = [];
-	for (const check of checks) {
-		const start = Date.now();
-		const timeout = check.timeout ?? 5e3;
-		let timer;
-		try {
-			const checkPromise = Promise.resolve(check.check());
-			const timeoutPromise = new Promise((_, reject) => {
-				timer = setTimeout(() => reject(/* @__PURE__ */ new Error("Health check timeout")), timeout);
-			});
-			const healthy = await Promise.race([checkPromise, timeoutPromise]);
-			results.push({
-				name: check.name,
-				healthy: Boolean(healthy),
-				duration: Date.now() - start
-			});
-		} catch (err) {
-			results.push({
-				name: check.name,
-				healthy: false,
-				duration: Date.now() - start,
-				error: err.message
-			});
-		} finally {
-			if (timer) clearTimeout(timer);
-		}
-	}
-	return results;
-}
-var health_default = fp(healthPlugin, {
-	name: "arc-health",
-	fastify: "5.x"
-});
-//#endregion
-export { health_default as n, healthPlugin as t };

package/dist/requestId-5BhTVzBv.mjs

@@ -1,113 +0,0 @@
-import { randomUUID } from "node:crypto";
-import fp from "fastify-plugin";
-//#region src/plugins/requestId.ts
-/**
-* Request ID Plugin
-*
-* Propagates request IDs for distributed tracing.
-* - Accepts incoming x-request-id header (sanitized)
-* - Generates UUID if not provided
-* - Echoes the id on the response header + W3C trace-context propagation
-*
-* ID RESOLUTION LIVES AT THE SERVER LEVEL, NOT HERE. Fastify binds
-* `request.log = logger.child({ reqId: request.id })` at request
-* construction — before any hook runs — so an id assigned inside a hook
-* never reaches the logs. `createApp` therefore wires
-* {@link createRequestIdGenerator} into Fastify's `genReqId` option, and
-* this plugin simply adopts `request.id`. Standalone registration on a
-* bare Fastify instance falls back to the legacy in-hook resolution
-* (header echo / UUID), with the documented limitation that
-* `request.log`'s `reqId` binding predates the overwrite — pass
-* `genReqId: createRequestIdGenerator()` to `Fastify()` to fix that.
-*
-* @example
-* import { requestIdPlugin, createRequestIdGenerator } from '@classytic/arc';
-*
-* const fastify = Fastify({ genReqId: createRequestIdGenerator() });
-* await fastify.register(requestIdPlugin);
-*
-* fastify.get('/', async (request) => {
-*   request.log.info('traced');   // carries the same reqId as the header
-*   return { id: request.id };
-* });
-*/
-/**
-* Sanitize an incoming request-id header value: max 128 chars, alphanumeric
-* plus dashes/underscores/dots/colons only. Returns `undefined` for anything
-* else (crafted values could pollute logs or response headers). Array values
-* (repeated headers) are rejected outright — a client sending multiple
-* request-id headers is not tracing in good faith.
-*/
-function sanitizeRequestId(value) {
-	if (typeof value !== "string") return void 0;
-	const trimmed = value.trim();
-	return trimmed.length > 0 && trimmed.length <= 128 && /^[\w.:-]+$/.test(trimmed) ? trimmed : void 0;
-}
-/**
-* Build a Fastify `genReqId` function: adopt a sanitized incoming request-id
-* header, or generate one. Wire this into the `Fastify()` constructor so
-* `request.id`, `request.log`'s `reqId` binding, and the echoed response
-* header all agree — `createApp` does this automatically.
-*/
-function createRequestIdGenerator(opts = {}) {
-	const { header = "x-request-id", generator = randomUUID } = opts;
-	const headerName = header.toLowerCase();
-	return (req) => sanitizeRequestId(req.headers[headerName]) ?? generator();
-}
-/** Fastify's default request ids are `req-<base36 counter>`. */
-const FASTIFY_DEFAULT_ID = /^req-[0-9a-z]+$/;
-/** W3C traceparent format: `version-traceid-parentid-flags` */
-const TRACEPARENT_RE = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/i;
-/** W3C spec: version ff is reserved and invalid; trace/parent IDs must not be all zeros */
-const TRACEID_ZEROS = "0".repeat(32);
-const PARENTID_ZEROS = "0".repeat(16);
-/** tracestate: printable ASCII, <= 512 bytes */
-const TRACESTATE_MAX = 512;
-function isValidTraceparent(tp) {
-	const m = TRACEPARENT_RE.exec(tp);
-	if (!m) return false;
-	const version = m[1] ?? "";
-	const traceId = m[2] ?? "";
-	const parentId = m[3] ?? "";
-	if (version.toLowerCase() === "ff") return false;
-	if (traceId.toLowerCase() === TRACEID_ZEROS) return false;
-	if (parentId.toLowerCase() === PARENTID_ZEROS) return false;
-	return true;
-}
-const requestIdPlugin = async (fastify, opts = {}) => {
-	const { header = "x-request-id", generator = randomUUID, setResponseHeader = true, propagateTraceContext = true } = opts;
-	if (!fastify.hasRequestDecorator("requestId")) fastify.decorateRequest("requestId", "");
-	if (!fastify.hasRequestDecorator("traceContext")) fastify.decorateRequest("traceContext", void 0);
-	fastify.addHook("onRequest", async (request, reply) => {
-		const incoming = sanitizeRequestId(request.headers[header]);
-		let requestId = String(request.id);
-		if (incoming && incoming !== requestId) requestId = incoming;
-		else if (!incoming && FASTIFY_DEFAULT_ID.test(requestId)) requestId = generator();
-		if (requestId !== request.id) request.id = requestId;
-		request.requestId = requestId;
-		if (setResponseHeader) reply.header(header, requestId);
-		if (propagateTraceContext) {
-			const rawTraceparent = request.headers["traceparent"];
-			const rawTracestate = request.headers["tracestate"];
-			if (typeof rawTraceparent === "string") {
-				const tp = rawTraceparent.trim();
-				if (isValidTraceparent(tp)) {
-					const ts = typeof rawTracestate === "string" && rawTracestate.length > 0 && rawTracestate.length <= TRACESTATE_MAX ? rawTracestate : void 0;
-					request.traceContext = {
-						traceparent: tp,
-						...ts ? { tracestate: ts } : {}
-					};
-					reply.header("traceparent", tp);
-					if (ts) reply.header("tracestate", ts);
-				}
-			}
-		}
-	});
-	fastify.log?.debug?.("Request ID plugin registered");
-};
-var requestId_default = fp(requestIdPlugin, {
-	name: "arc-request-id",
-	fastify: "5.x"
-});
-//#endregion
-export { sanitizeRequestId as i, requestIdPlugin as n, requestId_default as r, createRequestIdGenerator as t };

package/dist/types-XTApa8b6.mjs

@@ -1,24 +0,0 @@
-//#region src/permissions/types.ts
-/**
-* Extract normalized roles from a user object.
-*
-* Reads `user.role` which can be:
-* - A comma-separated string: `"superadmin,user"` (Better Auth admin plugin)
-* - A string array: `["admin", "user"]` (JWT / custom auth)
-* - A single string: `"admin"`
-*/
-/**
-* Normalize a raw role value (string, comma-separated string, or array) into a string[].
-* Shared low-level helper used by both getUserRoles() and the Better Auth adapter.
-*/
-function normalizeRoles(value) {
-	if (Array.isArray(value)) return value.map((r) => String(r).trim()).filter(Boolean);
-	if (typeof value === "string" && value.length > 0) return value.split(",").map((r) => r.trim()).filter(Boolean);
-	return [];
-}
-function getUserRoles(user) {
-	if (!user) return [];
-	return normalizeRoles(user.role);
-}
-//#endregion
-export { normalizeRoles as n, getUserRoles as t };