@classytic/arc 2.21.0 → 2.23.0

package/dist/integrations/webhooks.mjs

@@ -33,6 +33,13 @@ import fp from "fastify-plugin";
 /**
 * 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`
 */
 function signPayload(payload, secret) {
@@ -41,6 +48,120 @@ function signPayload(payload, secret) {
 	return `sha256=${hmac.digest("hex")}`;
 }
 /**
+* 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)
+*/
+function signWebhook(body, secret, meta) {
+	const hmac = createHmac("sha256", secret);
+	hmac.update(`v1.${meta.timestamp}.${meta.deliveryId}.${body}`);
+	return `v1=${hmac.digest("hex")}`;
+}
+/**
+* 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
+* });
+* ```
+*/
+function verifyWebhook(input) {
+	const { body, secret, signature, deliveryId, toleranceMs = 3e5, now = Date.now } = input;
+	if (typeof body !== "string" && !Buffer.isBuffer(body)) throw new TypeError("verifyWebhook: body must be a string or Buffer (the exact bytes the sender signed). Add `config: { rawBody: true }` to the route and pass req.rawBody — not req.body.");
+	if (!signature || !deliveryId || input.timestamp === void 0 || input.timestamp === "") return {
+		valid: false,
+		reason: "missing_headers"
+	};
+	const timestamp = Number(input.timestamp);
+	if (!Number.isFinite(timestamp)) return {
+		valid: false,
+		reason: "bad_timestamp"
+	};
+	if (Math.abs(now() - timestamp) > toleranceMs) return {
+		valid: false,
+		reason: "expired"
+	};
+	const expected = signWebhook(typeof body === "string" ? body : body.toString("utf8"), secret, {
+		timestamp,
+		deliveryId
+	});
+	const a = Buffer.from(signature);
+	const b = Buffer.from(expected);
+	if (a.length !== b.length || !timingSafeEqual(a, b)) return {
+		valid: false,
+		reason: "bad_signature"
+	};
+	return {
+		valid: true,
+		deliveryId,
+		timestamp
+	};
+}
+/**
+* Opt-in URL policy for tenant-registered webhooks: requires HTTPS and
+* rejects loopback, link-local, private-network, and cloud-metadata
+* destinations. Pass as `validateUrl: defaultWebhookUrlPolicy`.
+*
+* Scope note: this validates the URL LITERAL at registration time. It does
+* not resolve DNS — rebinding/level-2 SSRF protection belongs at the actual
+* outbound network boundary (egress proxy, network policy), where the real
+* connection target is known. Internal deployments that legitimately POST
+* to private services should write their own narrower policy instead.
+*/
+const BLOCKED_V4 = /^(?:127\.|10\.|192\.168\.|172\.(?:1[6-9]|2\d|3[01])\.|169\.254\.|0\.)/;
+function defaultWebhookUrlPolicy(url) {
+	if (url.protocol !== "https:") throw new Error(`Webhook URL must use https (got ${url.protocol}//)`);
+	let host = url.hostname.toLowerCase();
+	if (host.startsWith("[") && host.endsWith("]")) host = host.slice(1, -1);
+	const blockedName = host === "localhost" || host.endsWith(".localhost") || host === "metadata.google.internal";
+	const isV6 = host.includes(":");
+	const mappedV4 = isV6 ? decodeMappedV4(host) : void 0;
+	const blockedV6 = isV6 && (host === "::1" || host === "::" || /^f[cd]/.test(host) || /^fe[89ab]/.test(host) || mappedV4 !== void 0 && BLOCKED_V4.test(mappedV4));
+	const blockedV4 = !isV6 && BLOCKED_V4.test(host);
+	if (blockedName || blockedV4 || blockedV6) throw new Error(`Webhook URL host '${host}' is not allowed (loopback/private/metadata)`);
+}
+/**
+* Decode an IPv4-mapped IPv6 literal to its dotted-quad form. Accepts both
+* the textual spelling (`::ffff:1.2.3.4`) and the hex-group canonical form
+* WHATWG URL produces (`::ffff:102:304`). Returns undefined for anything else.
+*/
+function decodeMappedV4(host) {
+	const dotted = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/.exec(host)?.[1];
+	if (dotted) return dotted;
+	const hex = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(host);
+	if (!hex?.[1] || !hex[2]) return void 0;
+	const hi = Number.parseInt(hex[1], 16);
+	const lo = Number.parseInt(hex[2], 16);
+	return `${hi >> 8}.${hi & 255}.${lo >> 8}.${lo & 255}`;
+}
+/**
 * Verify an inbound webhook signature using timing-safe comparison.
 *
 * Works with Arc's own `signPayload` format by default (`sha256=<hex>`),
@@ -48,8 +169,9 @@ function signPayload(payload, secret) {
 *
 * ⚠ 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
@@ -61,8 +183,11 @@ function signPayload(payload, secret) {
 * ```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' });
@@ -82,7 +207,7 @@ function signPayload(payload, secret) {
 * ```
 */
 function verifySignature(body, secret, signature, options) {
-	if (typeof body !== "string" && !Buffer.isBuffer(body)) throw new TypeError("verifySignature: body must be a string or Buffer (the exact bytes the sender signed). Register @fastify/raw-body and pass req.rawBody — not req.body.");
+	if (typeof body !== "string" && !Buffer.isBuffer(body)) throw new TypeError("verifySignature: body must be a string or Buffer (the exact bytes the sender signed). Add `config: { rawBody: true }` to the route (arc registers fastify-raw-body with global: false) and pass req.rawBody — not req.body.");
 	if (!signature) return false;
 	const prefix = options?.prefix ?? "sha256=";
 	const algorithm = options?.algorithm ?? "sha256";
@@ -129,9 +254,24 @@ const webhookPlugin = async (fastify, opts = {}) => {
 	const timeout = opts.timeout ?? 1e4;
 	const maxLogEntries = opts.maxLogEntries ?? 1e3;
 	const concurrency = opts.concurrency ?? 5;
+	if (!Number.isInteger(concurrency) || concurrency < 1) throw new Error(`webhookPlugin: concurrency must be an integer >= 1 (got ${String(opts.concurrency)})`);
 	let subscriptions = [];
 	const log = [];
 	subscriptions = await store.getAll();
+	if (opts.validateUrl) {
+		const admitted = [];
+		for (const sub of subscriptions) try {
+			await opts.validateUrl(new URL(sub.url), sub);
+			admitted.push(sub);
+		} catch (err) {
+			fastify.log.warn({
+				subscriptionId: sub.id,
+				url: sub.url,
+				err
+			}, "webhookPlugin: persisted subscription failed the URL policy — excluded from dispatch. Fix the URL or unregister the subscription.");
+		}
+		subscriptions = admitted;
+	}
 	async function dispatchEvent(event) {
 		const matching = subscriptions.filter((s) => matchesPattern(s.events, event.type));
 		if (matching.length === 0) return;
@@ -148,7 +288,12 @@ const webhookPlugin = async (fastify, opts = {}) => {
 				timestamp: /* @__PURE__ */ new Date()
 			};
 			try {
-				const signature = signPayload(body, sub.secret);
+				const timestamp = Date.now();
+				const v1Signature = signWebhook(body, sub.secret, {
+					timestamp,
+					deliveryId: event.meta.id
+				});
+				const legacySignature = signPayload(body, sub.secret);
 				const ac = new AbortController();
 				const timer = setTimeout(() => ac.abort(), timeout);
 				try {
@@ -156,12 +301,16 @@ const webhookPlugin = async (fastify, opts = {}) => {
 						method: "POST",
 						headers: {
 							"content-type": "application/json",
-							"x-webhook-signature": signature,
+							"x-arc-webhook-signature": v1Signature,
+							"x-arc-webhook-timestamp": String(timestamp),
+							"x-arc-webhook-delivery": event.meta.id,
+							"x-webhook-signature": legacySignature,
 							"x-webhook-id": event.meta.id,
 							"x-webhook-event": event.type
 						},
 						body,
-						signal: ac.signal
+						signal: ac.signal,
+						...opts.validateUrl ? { redirect: "manual" } : {}
 					});
 					record.success = response.ok;
 					record.status = response.status;
@@ -184,6 +333,13 @@ const webhookPlugin = async (fastify, opts = {}) => {
 	if (fastify.events) unsubscribe = await fastify.events.subscribe("*", dispatchEvent);
 	fastify.decorate("webhooks", {
 		async register(sub) {
+			let parsed;
+			try {
+				parsed = new URL(sub.url);
+			} catch {
+				throw new Error(`webhookPlugin: invalid webhook URL '${sub.url}'`);
+			}
+			if (opts.validateUrl) await opts.validateUrl(parsed, sub);
 			await store.save(sub);
 			subscriptions = subscriptions.filter((s) => s.id !== sub.id);
 			subscriptions.push(sub);
@@ -193,7 +349,10 @@ const webhookPlugin = async (fastify, opts = {}) => {
 			subscriptions = subscriptions.filter((s) => s.id !== id);
 		},
 		list() {
-			return [...subscriptions];
+			return subscriptions.map(({ secret: _secret, ...pub }) => pub);
+		},
+		getSecret(id) {
+			return subscriptions.find((s) => s.id === id)?.secret;
 		},
 		deliveryLog(limit) {
 			if (limit) return log.slice(-limit);
@@ -213,4 +372,4 @@ var webhooks_default = fp(webhookPlugin, {
 	dependencies: ["arc-events"]
 });
 //#endregion
-export { webhooks_default as default, signPayload, verifySignature, webhookPlugin };
+export { webhooks_default as default, defaultWebhookUrlPolicy, signPayload, signWebhook, verifySignature, verifyWebhook, webhookPlugin };

package/dist/interface-n5hpKg1d.mjs

@@ -0,0 +1,16 @@
+//#region src/idempotency/stores/interface.ts
+/**
+* Helper to create a result object
+*/
+function createIdempotencyResult(statusCode, body, headers, ttlMs) {
+	const now = /* @__PURE__ */ new Date();
+	return {
+		statusCode,
+		headers,
+		body,
+		createdAt: now,
+		expiresAt: new Date(now.getTime() + ttlMs)
+	};
+}
+//#endregion
+export { createIdempotencyResult as t };

package/dist/jsonBody-BlzAoGCe.mjs

@@ -0,0 +1,43 @@
+import { t as ArcError } from "./errors-DkO8Nk6-.mjs";
+import sjson from "secure-json-parse";
+//#region src/utils/jsonBody.ts
+/**
+* Shared JSON request-body parsing for every arc content-type parser
+* (`application/json`, `application/scim+json`, decrypted `application/jose`).
+*
+* One primitive, one contract:
+*   - empty body → `undefined` (DELETE/GET with `Content-Type: application/json`
+*     must not crash — the original reason arc replaces Fastify's parser)
+*   - prototype-poisoning payloads (`__proto__`, `constructor.prototype`)
+*     rejected via `secure-json-parse`, same protection Fastify's stock
+*     parser has
+*   - ANY parse failure → `ArcError` with `statusCode: 400` /
+*     `code: 'arc.bad_request'`. Client-sent bytes can never produce a 500:
+*     Fastify forwards parser errors to the error handler as-is, so an
+*     undecorated `SyntaxError` would fall through to the
+*     `arc.internal_error` fallback. The raw parser message stays on
+*     `cause` (logged, never on the wire).
+*/
+/**
+* Parse a JSON request body with prototype-poisoning protection and the
+* arc 400 error contract.
+*
+* @param raw     - Body text (string or Buffer). Empty/absent → `undefined`.
+* @param message - Wire-safe error message for parse failures
+*                  (default: `"Invalid JSON payload"`).
+*/
+function parseJsonBody(raw, message = "Invalid JSON payload") {
+	const text = typeof raw === "string" ? raw : raw ? raw.toString("utf8") : "";
+	if (text.length === 0) return void 0;
+	try {
+		return sjson.parse(text);
+	} catch (cause) {
+		throw new ArcError(message, {
+			code: "arc.bad_request",
+			statusCode: 400,
+			cause
+		});
+	}
+}
+//#endregion
+export { parseJsonBody as t };

package/dist/{loadResourcesFromEntry-OMCvIEE7.mjs → loadResourcesFromEntry-kvGT6EcO.mjs}

@@ -1,4 +1,4 @@
-import { t as ResourceRegistry } from "./ResourceRegistry-7RnrEWNP.mjs";
+import { t as ResourceRegistry } from "./ResourceRegistry-y9Hnypus.mjs";
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 //#region src/cli/utils/loadResourcesFromEntry.ts

package/dist/logger/index.d.mts

@@ -77,5 +77,30 @@ declare function configureArcLogger(options: ArcLoggerOptions): void;
  * ```
  */
 declare function arcLog(module: string): ArcLogger;
+/**
+ * Minimal structural slice of a pino-style logger (`fastify.log`). Each
+ * level accepts `(msg)` or `(mergeObject, msg)` — the pino calling
+ * convention, which differs from console's variadic `(...args)`.
+ */
+interface PinoLike {
+  debug: (obj: unknown, msg?: string) => void;
+  info: (obj: unknown, msg?: string) => void;
+  warn: (obj: unknown, msg?: string) => void;
+  error: (obj: unknown, msg?: string) => void;
+}
+/**
+ * Bridge an `ArcLogWriter` onto a pino-style logger (`fastify.log`).
+ *
+ * arcLog call sites use the console convention — positional args like
+ * `log.warn("message", { userId })` — which pino would silently drop
+ * (extra args are printf interpolation values there). The bridge folds
+ * string args into the message, merges object args into the pino merge
+ * object, and maps `Error` instances to `{ err }` so pino's error
+ * serializer applies.
+ *
+ * `createApp` installs this automatically so arc-internal warnings flow
+ * through the host's transports, level, and redaction config.
+ */
+declare function createPinoWriter(logger: PinoLike): ArcLogWriter;
 //#endregion
-export { ArcLogWriter, ArcLogger, ArcLoggerOptions, arcLog, configureArcLogger };
+export { ArcLogWriter, ArcLogger, ArcLoggerOptions, PinoLike, arcLog, configureArcLogger, createPinoWriter };

package/dist/logger/index.mjs

@@ -44,6 +44,44 @@ function arcLog(module) {
 		}
 	};
 }
+/**
+* Bridge an `ArcLogWriter` onto a pino-style logger (`fastify.log`).
+*
+* arcLog call sites use the console convention — positional args like
+* `log.warn("message", { userId })` — which pino would silently drop
+* (extra args are printf interpolation values there). The bridge folds
+* string args into the message, merges object args into the pino merge
+* object, and maps `Error` instances to `{ err }` so pino's error
+* serializer applies.
+*
+* `createApp` installs this automatically so arc-internal warnings flow
+* through the host's transports, level, and redaction config.
+*/
+function createPinoWriter(logger) {
+	const emit = (level) => (...args) => {
+		const parts = [];
+		let merge;
+		for (const arg of args) if (typeof arg === "string") parts.push(arg);
+		else if (arg instanceof Error) merge = {
+			...merge ?? {},
+			err: arg
+		};
+		else if (arg !== null && typeof arg === "object") merge = {
+			...merge ?? {},
+			...arg
+		};
+		else parts.push(String(arg));
+		const msg = parts.join(" ");
+		if (merge) logger[level](merge, msg);
+		else logger[level](msg);
+	};
+	return {
+		debug: emit("debug"),
+		info: emit("info"),
+		warn: emit("warn"),
+		error: emit("error")
+	};
+}
 function getWriter() {
 	return globalOptions.writer ?? console;
 }
@@ -68,4 +106,4 @@ function isSuppressed() {
 	return env === "1" || env === "true";
 }
 //#endregion
-export { arcLog, configureArcLogger };
+export { arcLog, configureArcLogger, createPinoWriter };