@fluid-app/droplet-sdk 0.2.0

package/dist/next/callbacks.mjs

@@ -0,0 +1,120 @@
+import { tokenDigest, verifySignature } from "../signatures.mjs";
+import { consoleLogger, describeError } from "../redact.mjs";
+//#region src/next/callbacks.ts
+const HEADER_TIMESTAMP = "x-fluid-timestamp";
+const HEADER_SIGNATURE = "x-fluid-signature";
+const HEADER_CALLBACK_TOKEN = "x-fluid-callback-token";
+const denyAuth = () => Response.json({ error: "unauthorized" }, { status: 401 });
+const denyBody = () => Response.json({ error: "invalid request" }, { status: 400 });
+const denyHandler = () => Response.json({ error: "internal error" }, { status: 500 });
+function withFluidCallback(config, handler) {
+	const { definitions, store, resolvePrincipal, logger = consoleLogger, name = definitions[0] ?? "callback", onAuthFailure = denyAuth, onInvalidBody = denyBody, onHandlerError = denyHandler } = config;
+	if (definitions.length === 0) throw new Error("withFluidCallback requires at least one definition");
+	return async function POST(request) {
+		const log = (level, message, context = {}) => logger[level](`[fluid-callback:${name}] ${message}`, context);
+		let bodyBytes;
+		try {
+			bodyBytes = new Uint8Array(await request.arrayBuffer());
+		} catch (error) {
+			log("error", "could not read request body", describeError(error));
+			return onInvalidBody({
+				stage: "body",
+				reason: "unreadable"
+			});
+		}
+		const rawBody = new TextDecoder().decode(bodyBytes);
+		const presentedToken = request.headers.get(HEADER_CALLBACK_TOKEN);
+		let registration = null;
+		let authFailure = null;
+		if (!presentedToken) authFailure = "missing_callback_token";
+		else {
+			try {
+				registration = await store.findByTokenDigest(tokenDigest(presentedToken));
+			} catch (error) {
+				log("error", "token store lookup failed", describeError(error));
+				return onAuthFailure({
+					stage: "auth",
+					reason: "store_unavailable"
+				});
+			}
+			if (!registration) authFailure = "unknown_registration";
+			else if (!definitions.includes(registration.definitionName)) authFailure = "definition_mismatch";
+			else {
+				const result = verifySignature({
+					rawBody: bodyBytes,
+					signature: request.headers.get(HEADER_SIGNATURE),
+					timestamp: request.headers.get(HEADER_TIMESTAMP),
+					secret: presentedToken
+				});
+				if (!result.valid) authFailure = result.reason;
+			}
+		}
+		if (authFailure) {
+			log("warn", "rejected", { reason: authFailure });
+			return onAuthFailure({
+				stage: "auth",
+				reason: authFailure
+			});
+		}
+		if (!registration) {
+			log("error", "no registration after verification passed");
+			return onAuthFailure({
+				stage: "auth",
+				reason: "unknown_registration"
+			});
+		}
+		let payload;
+		try {
+			payload = JSON.parse(rawBody);
+		} catch {
+			log("warn", "body was not valid JSON");
+			return onInvalidBody({
+				stage: "body",
+				reason: "malformed_json"
+			});
+		}
+		let principal = null;
+		try {
+			principal = await resolvePrincipal({
+				registration,
+				payload,
+				headers: request.headers
+			});
+		} catch (error) {
+			log("error", "principal resolution threw", describeError(error));
+			return onHandlerError({
+				stage: "handler",
+				reason: "resolve_threw",
+				error
+			});
+		}
+		if (principal === null) {
+			log("warn", "rejected", { reason: "unresolved_principal" });
+			return onAuthFailure({
+				stage: "auth",
+				reason: "unresolved_principal"
+			});
+		}
+		try {
+			const result = await handler({
+				payload,
+				definition: registration.definitionName,
+				principal,
+				registration,
+				headers: request.headers,
+				signal: request.signal,
+				rawBody
+			});
+			return result instanceof Response ? result : Response.json(result);
+		} catch (error) {
+			log("error", "handler threw", describeError(error));
+			return onHandlerError({
+				stage: "handler",
+				reason: "handler_threw",
+				error
+			});
+		}
+	};
+}
+//#endregion
+export { withFluidCallback };

package/dist/next/webhooks.d.mts

@@ -0,0 +1,119 @@
+import { Logger } from "../redact.mjs";
+
+//#region src/next/webhooks.d.ts
+/**
+* The event that arrives before any per-company secret exists, and so the
+* default — and only sensible — member of `bootstrapEvents`.
+*/
+declare const INSTALL_EVENT = "droplet.installed";
+interface WebhookRoutingHints {
+  /** Parsed but *unverified*. Used only to locate a candidate secret. */
+  payload: unknown;
+  headers: Headers;
+  dri?: string;
+  fluidShop?: string;
+  companyId?: string | number;
+}
+interface ResolvedWebhookPrincipal<Principal> {
+  secret: string;
+  principal: Principal;
+}
+interface WebhookContext<Principal> {
+  event: string;
+  payload: unknown;
+  /**
+  * The verified tenant.
+  *
+  * Non-null means the request verified — but NOT necessarily against this
+  * company's own secret. An event listed in `bootstrapEvents` verifies against
+  * the shared bootstrap secret and ONLY that, so a reinstall is bootstrap-
+  * verified while `resolve` still finds the existing company: the handler sees
+  * that company on a request no company token could have signed.
+  *
+  * Null means the bootstrap secret verified and no company was found — a first
+  * install, which the handler is expected to create. It is never null for an
+  * unverified request: those are refused before the handler runs.
+  */
+  principal: Principal | null;
+  headers: Headers;
+  signal: AbortSignal;
+  rawBody: string;
+}
+interface WithFluidWebhookConfig<Principal> {
+  /**
+  * Locates the per-company secret and tenant from unverified routing hints.
+  *
+  * Unlike callbacks, webhook secrets are per-company, so the tenant must be
+  * guessed from untrusted input *before* verification. That is inherent to the
+  * scheme: resolve a candidate, verify against it, and only then trust it.
+  *
+  * The two failure modes are NOT the same and must not be conflated:
+  *
+  *   return null — "there is no such tenant". A settled answer. The request is
+  *     refused with `onAuthFailure`, and Fluid will not retry it.
+  *   throw       — "I could not find out". The lookup itself failed: the
+  *     database was unreachable, a query timed out. The request is answered
+  *     with `onResolveError` (503 by default) so Fluid retries the delivery.
+  *
+  * Throw for "unknown", and an outage becomes a permanently rejected webhook.
+  */
+  resolve: (hints: WebhookRoutingHints) => Promise<ResolvedWebhookPrincipal<Principal> | null>;
+  /**
+  * Shared token accepted only for the events in `bootstrapEvents`, which
+  * defaults to `droplet.installed` alone.
+  *
+  * A first install has no per-company secret yet, so something has to
+  * authenticate it. Every other event requires a signature: a shared value
+  * accepted generally is a bypass, because one leaked copy authenticates
+  * anything.
+  *
+  * The exclusivity runs BOTH ways. For an event in `bootstrapEvents` this is
+  * the only accepted signer and a per-company secret is refused, because Fluid
+  * signs those events with the droplet's own secret and never with a
+  * company's. Omitting it while listing lifecycle events means those events
+  * cannot verify at all (`no_bootstrap_secret`), which is a loud failure by
+  * design.
+  */
+  bootstrapSecret?: string;
+  /**
+  * The complete set of events permitted to use the bootstrap secret.
+  *
+  * REPLACES the default rather than adding to it, so a list that omits
+  * `droplet.installed` stops installs verifying. Include it explicitly unless
+  * that is what you intend. Defaults to `["droplet.installed"]`.
+  *
+  * Replacement rather than addition is deliberate for a security control: the
+  * list is exactly what the caller sees when reading their own code, with no
+  * inherited entry to overlook.
+  */
+  bootstrapEvents?: string[];
+  logger?: Logger;
+  name?: string;
+  onAuthFailure?: (reason: string) => Response;
+  onInvalidBody?: (reason: string) => Response;
+  /**
+  * Answers a `resolve` that threw. Defaults to 503.
+  *
+  * Must stay a 5xx: Fluid retries 5xx and 429, and treats every other 4xx as
+  * a permanent rejection that is never delivered again.
+  */
+  onResolveError?: (error: unknown) => Response;
+  onHandlerError?: (error: unknown) => Response;
+}
+type WebhookHandler<Principal> = (context: WebhookContext<Principal>) => Promise<Response | unknown>;
+/**
+* The object the event was actually derived FROM.
+*
+* `eventOf` accepts several shapes; everything downstream — tenant hints,
+* handler payload — has to look at the same object it chose, or the three
+* disagree. They did: hints were read from the outer envelope, so an enveloped
+* per-company webhook (`{name, payload: {company: {...}}}`) offered no tenant,
+* produced no candidate secret, and failed closed with 401 on every delivery.
+*
+* Precedence mirrors `eventOf` exactly, in the same order.
+*/
+declare const effectivePayload: (body: unknown) => unknown;
+/** Wraps a Fluid webhook route with HMAC verification. */
+declare function withFluidWebhook<Principal>(config: WithFluidWebhookConfig<Principal>, handler: WebhookHandler<Principal>): (request: Request) => Promise<Response>;
+//#endregion
+export { INSTALL_EVENT, ResolvedWebhookPrincipal, WebhookContext, WebhookHandler, WebhookRoutingHints, WithFluidWebhookConfig, effectivePayload, withFluidWebhook };

package/dist/next/webhooks.mjs

@@ -0,0 +1,150 @@
+import { verifySignature } from "../signatures.mjs";
+import { consoleLogger, describeError } from "../redact.mjs";
+//#region src/next/webhooks.ts
+const HEADER_TIMESTAMP = "x-fluid-timestamp";
+const HEADER_SIGNATURE = "x-fluid-signature";
+const INSTALL_EVENT = "droplet.installed";
+const eventOf = (payload) => {
+	if (!payload || typeof payload !== "object") return "unknown";
+	const record = payload;
+	const name = record["name"];
+	if (typeof name === "string" && name.length > 0) return name.includes(".") ? name : name.replace("_", ".");
+	const nested = record["payload"] ?? {};
+	const resource = record["resource"] ?? nested["resource"];
+	const event = record["event"] ?? nested["event"];
+	if (typeof resource === "string" && typeof event === "string") return `${resource}.${event}`;
+	if (typeof event === "string") return event;
+	return "unknown";
+};
+const effectivePayload = (body) => {
+	if (!body || typeof body !== "object" || Array.isArray(body)) return body;
+	const record = body;
+	const nested = record["payload"];
+	const nestedIsObject = typeof nested === "object" && nested !== null && !Array.isArray(nested);
+	const name = record["name"];
+	if (typeof name === "string" && name.length > 0) return nestedIsObject ? nested : record;
+	if (typeof record["resource"] === "string" && typeof record["event"] === "string") return record;
+	if (nestedIsObject) {
+		const inner = nested;
+		if (typeof inner["resource"] === "string" || typeof inner["event"] === "string") return nested;
+	}
+	return record;
+};
+const readHints = (body) => {
+	const payload = effectivePayload(body);
+	if (!payload || typeof payload !== "object") return {};
+	const record = payload;
+	const company = record["company"] ?? {};
+	const context = record["context"] ?? {};
+	const dri = company["droplet_installation_uuid"];
+	const shop = company["fluid_shop"];
+	const companyId = company["id"] ?? company["fluid_company_id"] ?? context["company_id"];
+	return {
+		dri: typeof dri === "string" ? dri : void 0,
+		fluidShop: typeof shop === "string" ? shop : void 0,
+		companyId: typeof companyId === "string" || typeof companyId === "number" ? companyId : void 0
+	};
+};
+function withFluidWebhook(config, handler) {
+	const { resolve, bootstrapSecret, bootstrapEvents = [INSTALL_EVENT], logger = consoleLogger, name = "webhook", onAuthFailure = () => Response.json({ error: "unauthorized" }, { status: 401 }), onInvalidBody = () => Response.json({ error: "invalid request" }, { status: 400 }), onResolveError = () => Response.json({ error: "resolver unavailable" }, { status: 503 }), onHandlerError = () => Response.json({ error: "internal error" }, { status: 500 }) } = config;
+	return async function POST(request) {
+		const log = (level, message, context = {}) => logger[level](`[fluid-webhook:${name}] ${message}`, context);
+		let rawBody;
+		try {
+			rawBody = await request.text();
+		} catch (error) {
+			log("error", "could not read request body", describeError(error));
+			return onInvalidBody("unreadable");
+		}
+		let payload;
+		try {
+			payload = JSON.parse(rawBody);
+		} catch {
+			log("warn", "body was not valid JSON");
+			return onInvalidBody("malformed_json");
+		}
+		const event = eventOf(payload);
+		const signature = request.headers.get(HEADER_SIGNATURE);
+		const timestamp = request.headers.get(HEADER_TIMESTAMP);
+		let principal = null;
+		let authFailure = null;
+		let resolveThrew = false;
+		let resolveError;
+		const resolved = await resolve({
+			payload,
+			headers: request.headers,
+			...readHints(payload),
+			fluidShop: request.headers.get("x-fluid-shop") ?? readHints(payload).fluidShop
+		}).catch((error) => {
+			resolveThrew = true;
+			resolveError = error;
+			log("error", "resolve threw", describeError(error));
+			return null;
+		});
+		if (resolveThrew) {
+			log("warn", "unavailable", {
+				reason: "resolve_failed",
+				event
+			});
+			return onResolveError(resolveError);
+		}
+		const candidates = [];
+		const isBootstrapEvent = bootstrapEvents.includes(event);
+		if (isBootstrapEvent) {
+			if (bootstrapSecret) candidates.push({
+				label: "bootstrap",
+				secret: bootstrapSecret
+			});
+		} else if (resolved?.secret) candidates.push({
+			label: "company",
+			secret: resolved.secret
+		});
+		if (candidates.length === 0) authFailure = isBootstrapEvent ? "no_bootstrap_secret" : resolved ? "blank_secret" : "unresolved_company";
+		else {
+			let matched = null;
+			let lastReason = "mismatch";
+			for (const candidate of candidates) {
+				const result = verifySignature({
+					rawBody,
+					signature,
+					timestamp,
+					secret: candidate.secret
+				});
+				if (result.valid) {
+					matched = candidate.label;
+					break;
+				}
+				lastReason = result.reason;
+			}
+			if (matched === "company" && resolved) principal = resolved.principal;
+			else if (matched === "bootstrap") principal = resolved?.principal ?? null;
+			else authFailure = lastReason;
+		}
+		if (authFailure) {
+			log("warn", "rejected", {
+				reason: authFailure,
+				event
+			});
+			return onAuthFailure(authFailure);
+		}
+		try {
+			const result = await handler({
+				event,
+				payload,
+				principal,
+				headers: request.headers,
+				signal: request.signal,
+				rawBody
+			});
+			return result instanceof Response ? result : Response.json(result);
+		} catch (error) {
+			log("error", "handler threw", {
+				event,
+				...describeError(error)
+			});
+			return onHandlerError(error);
+		}
+	};
+}
+//#endregion
+export { INSTALL_EVENT, effectivePayload, withFluidWebhook };

package/dist/next.d.mts

@@ -0,0 +1,3 @@
+import { CallbackContext, CallbackFailure, CallbackHandler, WithFluidCallbackConfig, withFluidCallback } from "./next/callbacks.mjs";
+import { INSTALL_EVENT, ResolvedWebhookPrincipal, WebhookContext, WebhookHandler, WebhookRoutingHints, WithFluidWebhookConfig, effectivePayload, withFluidWebhook } from "./next/webhooks.mjs";
+export { type CallbackContext, type CallbackFailure, type CallbackHandler, INSTALL_EVENT, type ResolvedWebhookPrincipal, type WebhookContext, type WebhookHandler, type WebhookRoutingHints, type WithFluidCallbackConfig, type WithFluidWebhookConfig, effectivePayload, withFluidCallback, withFluidWebhook };

package/dist/next.mjs

@@ -0,0 +1,3 @@
+import { withFluidCallback } from "./next/callbacks.mjs";
+import { INSTALL_EVENT, effectivePayload, withFluidWebhook } from "./next/webhooks.mjs";
+export { INSTALL_EVENT, effectivePayload, withFluidCallback, withFluidWebhook };

package/dist/prisma.d.mts

@@ -0,0 +1,2 @@
+import { PrismaCallbackDelegate, createPrismaCallbackStore } from "./store/prisma.mjs";
+export { type PrismaCallbackDelegate, createPrismaCallbackStore };

package/dist/prisma.mjs

@@ -0,0 +1,2 @@
+import { createPrismaCallbackStore } from "./store/prisma.mjs";
+export { createPrismaCallbackStore };

package/dist/readiness.d.mts

@@ -0,0 +1,32 @@
+//#region src/readiness.d.ts
+/**
+* Boot-time check that this droplet can verify callbacks.
+*
+* Reports whether any registration tokens are stored yet. Until they are, a
+* wrapped route cannot verify anything it receives.
+*
+* Never throws and never prevents boot.
+*
+* CALLING CONTRACT: do not await this from `instrumentation.register()`. It
+* retries for minutes rather than seconds before giving up, so awaiting it
+* would hold a cold start open for that whole span.
+*/
+type CallbackVerificationReadiness = "ready" | "no-registrations" | "unavailable";
+type Logger = Pick<Console, "error" | "info">;
+declare function reportCallbackVerificationReadiness({
+  countRegistrations,
+  backfillCommand,
+  logger
+}: {
+  countRegistrations: () => Promise<number>;
+  /**
+  * The exact command an operator should run to fix an empty table, e.g.
+  * `pnpm --filter <droplet> backfill:callbacks`. Named rather than derived,
+  * because the alert is read by someone who does not already know which
+  * droplet is broken.
+  */
+  backfillCommand: string;
+  logger?: Logger;
+}): Promise<CallbackVerificationReadiness>;
+//#endregion
+export { CallbackVerificationReadiness, reportCallbackVerificationReadiness };

package/dist/readiness.mjs

@@ -0,0 +1,53 @@
+//#region src/readiness.ts
+const MARKER = "[fluid-callback:readiness]";
+const TIMEOUT_MS = 2e4;
+const RETRY_DELAYS_MS = [
+	3e4,
+	6e4,
+	12e4
+];
+async function withTimeout(work, ms) {
+	let timer;
+	try {
+		return await Promise.race([work, new Promise((_, reject) => {
+			timer = setTimeout(() => reject(new Error(`timed out after ${ms}ms`)), ms);
+		})]);
+	} finally {
+		if (timer) clearTimeout(timer);
+	}
+}
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function reportCallbackVerificationReadiness({ countRegistrations, backfillCommand, logger = console }) {
+	const attempts = RETRY_DELAYS_MS.length + 1;
+	let lastError = "";
+	for (let attempt = 0; attempt < attempts; attempt++) {
+		if (attempt > 0) await sleep(RETRY_DELAYS_MS[attempt - 1]);
+		let count;
+		try {
+			count = await withTimeout(countRegistrations(), TIMEOUT_MS);
+		} catch (error) {
+			lastError = error instanceof Error ? error.message : String(error);
+			logger.info(`${MARKER} could not read stored callback registrations yet; retrying`, {
+				attempt: attempt + 1,
+				of: attempts,
+				error: lastError
+			});
+			continue;
+		}
+		if (count === 0) {
+			logger.error(`${MARKER} NO callback registrations are stored, but callback verification is enabled. Every callback Fluid sends will be refused, and refusals answer 200 so nothing else will report this. Run \`${backfillCommand}\` against this database.`);
+			return "no-registrations";
+		}
+		logger.info(`${MARKER} verifying callbacks against stored registrations`, {
+			registrations: count,
+			...attempt > 0 ? { afterAttempts: attempt + 1 } : {}
+		});
+		return "ready";
+	}
+	logger.error(`${MARKER} could not check stored callback registrations after ${attempts} attempts; cannot tell whether verification will accept anything`, { error: lastError });
+	return "unavailable";
+}
+//#endregion
+export { reportCallbackVerificationReadiness };

package/dist/redact.d.mts

@@ -0,0 +1,31 @@
+//#region src/redact.d.ts
+/**
+* Recursively replaces credential-shaped values.
+*
+* Deny-by-name rather than deny-by-value: matching on the key is stable, while
+* matching on the value is how redaction helpers silently stop working (a
+* helper testing values for the substring "password" never fires on a license
+* key).
+*/
+declare function redactValue(input: unknown, depth?: number): unknown;
+/**
+* Renders an error for logging without leaking a body through its message.
+*
+* Truncation alone is not enough: upstream clients routinely embed whole
+* response bodies in error messages, and the first 300 characters of a cart
+* payload is still a cart payload. Anything resembling a JSON object or a
+* credential is stripped before truncating.
+*/
+declare function describeError(error: unknown): {
+  name: string;
+  message: string;
+};
+interface Logger {
+  info(message: string, context?: Record<string, unknown>): void;
+  warn(message: string, context?: Record<string, unknown>): void;
+  error(message: string, context?: Record<string, unknown>): void;
+}
+/** Injectable so droplets can route into Sentry or a structured logger later. */
+declare const consoleLogger: Logger;
+//#endregion
+export { Logger, consoleLogger, describeError, redactValue };

package/dist/redact.mjs

@@ -0,0 +1,35 @@
+//#region src/redact.ts
+const SENSITIVE_KEY_PATTERN = /(token|secret|password|credential|api[_-]?key|authorization|signature)/i;
+const REDACTED = "[REDACTED]";
+const MAX_DEPTH = 6;
+function redactValue(input, depth = 0) {
+	if (depth > MAX_DEPTH) return "[TRUNCATED]";
+	if (input === null || input === void 0) return input;
+	if (Array.isArray(input)) return input.map((entry) => redactValue(entry, depth + 1));
+	if (typeof input === "object") {
+		const output = {};
+		for (const [key, value] of Object.entries(input)) output[key] = SENSITIVE_KEY_PATTERN.test(key) ? REDACTED : redactValue(value, depth + 1);
+		return output;
+	}
+	return input;
+}
+function describeError(error) {
+	const raw = error instanceof Error ? error.message : String(error);
+	return {
+		name: error instanceof Error ? error.name : "UnknownError",
+		message: truncate(scrubMessage(raw), 300)
+	};
+}
+function scrubMessage(message) {
+	return message.replace(/[{[][\s\S]*[}\]]/g, "[STRUCTURED_CONTENT_REMOVED]").replace(/\b(?:cvt|wvt|dit|dri|drp|cbr)_[A-Za-z0-9._-]+/g, "[REDACTED]").replace(/\b(token|secret|password|credential|api[_-]?key|authorization|signature)\b\s*[:=]\s*\S+/gi, "$1=[REDACTED]");
+}
+function truncate(value, max) {
+	return value.length <= max ? value : `${value.slice(0, max)}…[truncated]`;
+}
+const consoleLogger = {
+	info: (message, context) => console.log(message, context ?? {}),
+	warn: (message, context) => console.warn(message, context ?? {}),
+	error: (message, context) => console.error(message, context ?? {})
+};
+//#endregion
+export { consoleLogger, describeError, redactValue };

package/dist/signatures.d.mts

@@ -0,0 +1,59 @@
+//#region src/signatures.d.ts
+/**
+* Maximum age of a signature, in seconds.
+*
+* Note this bounds *freshness*, not replay: the same request can be presented
+* repeatedly inside the window. There is no nonce or seen-signature cache.
+*/
+declare const MAX_SIGNATURE_AGE_SECONDS = 300;
+type SignatureFailureReason = "missing_signature" | "missing_timestamp" | "malformed_timestamp" | "stale_timestamp" | "malformed_signature" | "no_secret" | "mismatch";
+type SignatureResult = {
+  valid: true;
+} | {
+  valid: false;
+  reason: SignatureFailureReason;
+  detail: string;
+};
+interface VerifySignatureInput {
+  /**
+  * The exact bytes that were signed. Never a re-serialised object.
+  *
+  * Prefer the byte form. A string has already been through a UTF-8 decode,
+  * which is not a round trip: `Request.text()` strips a leading BOM and turns
+  * malformed sequences into U+FFFD, so re-encoding it here would not reproduce
+  * what Fluid actually hashed.
+  */
+  rawBody: string | Uint8Array;
+  signature: string | null;
+  timestamp: string | null;
+  /** The HMAC key. For callbacks this is the presented token; for webhooks the stored per-company token. */
+  secret: string;
+  maxAgeSeconds?: number;
+  /** Injectable for tests. Seconds since epoch. */
+  now?: () => number;
+}
+/**
+* Verifies an HMAC-SHA256 signature over `{timestamp}.{rawBody}`.
+*
+* This is the same computation Fluid performs for both webhooks
+* (`WebhookCaller`) and callbacks (`Callback::Client#generate_signed_headers`).
+* The two paths differ only in where the secret comes from.
+*/
+declare function verifySignature({
+  rawBody,
+  signature,
+  timestamp,
+  secret,
+  maxAgeSeconds,
+  now
+}: VerifySignatureInput): SignatureResult;
+/**
+* Hashes a callback verification token for storage.
+*
+* Tokens are stored as digests so that a dump of a droplet's database does not
+* hand over working callback credentials. Fluid presents the plaintext token on
+* every request, so the digest is sufficient to locate the registration.
+*/
+declare function tokenDigest(token: string): string;
+//#endregion
+export { MAX_SIGNATURE_AGE_SECONDS, SignatureFailureReason, SignatureResult, VerifySignatureInput, tokenDigest, verifySignature };

package/dist/signatures.mjs

@@ -0,0 +1,60 @@
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+//#region src/signatures.ts
+const MAX_SIGNATURE_AGE_SECONDS = 300;
+function verifySignature({ rawBody, signature, timestamp, secret, maxAgeSeconds = 300, now = () => Math.floor(Date.now() / 1e3) }) {
+	if (!signature) return {
+		valid: false,
+		reason: "missing_signature",
+		detail: "Missing X-Fluid-Signature header"
+	};
+	if (!timestamp) return {
+		valid: false,
+		reason: "missing_timestamp",
+		detail: "Missing X-Fluid-Timestamp header"
+	};
+	const timestampSeconds = timestamp.trim() === "" ? NaN : Number(timestamp);
+	if (!Number.isInteger(timestampSeconds)) return {
+		valid: false,
+		reason: "malformed_timestamp",
+		detail: "X-Fluid-Timestamp is not an integer"
+	};
+	const age = Math.abs(now() - timestampSeconds);
+	if (age > maxAgeSeconds) return {
+		valid: false,
+		reason: "stale_timestamp",
+		detail: `Signature age ${age}s exceeds ${maxAgeSeconds}s`
+	};
+	if (!secret) return {
+		valid: false,
+		reason: "no_secret",
+		detail: "No secret available to verify against"
+	};
+	const bodyBytes = typeof rawBody === "string" ? Buffer.from(rawBody, "utf8") : rawBody;
+	const expected = createHmac("sha256", secret).update(Buffer.from(`${timestamp}.`, "utf8")).update(bodyBytes).digest("hex");
+	if (!isHexOfLength(signature, expected.length)) return {
+		valid: false,
+		reason: "malformed_signature",
+		detail: "Signature is not hex of the expected length"
+	};
+	const presented = Buffer.from(signature, "hex");
+	const computed = Buffer.from(expected, "hex");
+	if (presented.length !== computed.length || presented.length === 0) return {
+		valid: false,
+		reason: "mismatch",
+		detail: "Signature mismatch"
+	};
+	if (!timingSafeEqual(presented, computed)) return {
+		valid: false,
+		reason: "mismatch",
+		detail: "Signature mismatch"
+	};
+	return { valid: true };
+}
+function isHexOfLength(value, length) {
+	return value.length === length && /^[0-9a-fA-F]+$/.test(value);
+}
+function tokenDigest(token) {
+	return createHash("sha256").update(token).digest("hex");
+}
+//#endregion
+export { MAX_SIGNATURE_AGE_SECONDS, tokenDigest, verifySignature };