@graphorin/server 0.5.0

package/dist/middleware/cors.js

@@ -0,0 +1,45 @@
+//#region src/middleware/cors.ts
+/**
+* @stable
+*/
+function createCorsMiddleware(config) {
+	const allowSet = new Set(config.allowOrigins);
+	const allowAny = allowSet.has("*");
+	const allowMethods = config.allowMethods.join(", ");
+	const allowHeaders = config.allowHeaders.join(", ");
+	const maxAge = config.maxAgeSeconds.toString();
+	return async (c, next) => {
+		const origin = c.req.header("origin");
+		const isPreflight = c.req.method === "OPTIONS" && c.req.header("access-control-request-method") !== void 0;
+		if (origin === void 0) {
+			if (isPreflight) return c.body(null, 204);
+			await next();
+			return;
+		}
+		if (!(allowAny || allowSet.has(origin))) {
+			if (isPreflight) return c.body(null, 204);
+			await next();
+			return;
+		}
+		if (allowAny && config.allowCredentials) {
+			c.header("Access-Control-Allow-Origin", origin);
+			c.header("Vary", "Origin");
+		} else if (allowAny) c.header("Access-Control-Allow-Origin", "*");
+		else {
+			c.header("Access-Control-Allow-Origin", origin);
+			c.header("Vary", "Origin");
+		}
+		if (config.allowCredentials) c.header("Access-Control-Allow-Credentials", "true");
+		if (isPreflight) {
+			c.header("Access-Control-Allow-Methods", allowMethods);
+			c.header("Access-Control-Allow-Headers", allowHeaders);
+			c.header("Access-Control-Max-Age", maxAge);
+			return c.body(null, 204);
+		}
+		await next();
+	};
+}
+
+//#endregion
+export { createCorsMiddleware };
+//# sourceMappingURL=cors.js.map

package/dist/middleware/cors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cors.js","names":[],"sources":["../../src/middleware/cors.ts"],"sourcesContent":["/**\n * Deny-by-default CORS middleware. The framework refuses to echo back\n * arbitrary origins; allowlist semantics match the threat-model\n * checklist in the runtime architecture.\n *\n * @packageDocumentation\n */\n\nimport type { MiddlewareHandler } from 'hono';\n\nimport type { ServerConfigSpec } from '../config.js';\nimport type { ServerVariables } from '../internal/context.js';\n\n/**\n * @stable\n */\nexport function createCorsMiddleware(\n  config: ServerConfigSpec['server']['cors'],\n): MiddlewareHandler<{ Variables: ServerVariables }> {\n  const allowSet = new Set(config.allowOrigins);\n  const allowAny = allowSet.has('*');\n  const allowMethods = config.allowMethods.join(', ');\n  const allowHeaders = config.allowHeaders.join(', ');\n  const maxAge = config.maxAgeSeconds.toString();\n\n  return async (c, next) => {\n    const origin = c.req.header('origin');\n    const isPreflight =\n      c.req.method === 'OPTIONS' && c.req.header('access-control-request-method') !== undefined;\n    if (origin === undefined) {\n      // Same-origin request — proceed without CORS headers.\n      if (isPreflight) {\n        return c.body(null, 204);\n      }\n      await next();\n      return;\n    }\n    const allowed = allowAny || allowSet.has(origin);\n    if (!allowed) {\n      if (isPreflight) {\n        return c.body(null, 204);\n      }\n      // Pass the request through but withhold the CORS allow header so\n      // the browser blocks it; do NOT short-circuit the request — the\n      // server-to-server flow must still receive a normal response.\n      await next();\n      return;\n    }\n\n    if (allowAny && config.allowCredentials) {\n      // Specs forbid `Access-Control-Allow-Origin: *` with credentials;\n      // mirror the request origin instead.\n      c.header('Access-Control-Allow-Origin', origin);\n      c.header('Vary', 'Origin');\n    } else if (allowAny) {\n      c.header('Access-Control-Allow-Origin', '*');\n    } else {\n      c.header('Access-Control-Allow-Origin', origin);\n      c.header('Vary', 'Origin');\n    }\n    if (config.allowCredentials) {\n      c.header('Access-Control-Allow-Credentials', 'true');\n    }\n    if (isPreflight) {\n      c.header('Access-Control-Allow-Methods', allowMethods);\n      c.header('Access-Control-Allow-Headers', allowHeaders);\n      c.header('Access-Control-Max-Age', maxAge);\n      return c.body(null, 204);\n    }\n    await next();\n  };\n}\n"],"mappings":";;;;AAgBA,SAAgB,qBACd,QACmD;CACnD,MAAM,WAAW,IAAI,IAAI,OAAO,aAAa;CAC7C,MAAM,WAAW,SAAS,IAAI,IAAI;CAClC,MAAM,eAAe,OAAO,aAAa,KAAK,KAAK;CACnD,MAAM,eAAe,OAAO,aAAa,KAAK,KAAK;CACnD,MAAM,SAAS,OAAO,cAAc,UAAU;AAE9C,QAAO,OAAO,GAAG,SAAS;EACxB,MAAM,SAAS,EAAE,IAAI,OAAO,SAAS;EACrC,MAAM,cACJ,EAAE,IAAI,WAAW,aAAa,EAAE,IAAI,OAAO,gCAAgC,KAAK;AAClF,MAAI,WAAW,QAAW;AAExB,OAAI,YACF,QAAO,EAAE,KAAK,MAAM,IAAI;AAE1B,SAAM,MAAM;AACZ;;AAGF,MAAI,EADY,YAAY,SAAS,IAAI,OAAO,GAClC;AACZ,OAAI,YACF,QAAO,EAAE,KAAK,MAAM,IAAI;AAK1B,SAAM,MAAM;AACZ;;AAGF,MAAI,YAAY,OAAO,kBAAkB;AAGvC,KAAE,OAAO,+BAA+B,OAAO;AAC/C,KAAE,OAAO,QAAQ,SAAS;aACjB,SACT,GAAE,OAAO,+BAA+B,IAAI;OACvC;AACL,KAAE,OAAO,+BAA+B,OAAO;AAC/C,KAAE,OAAO,QAAQ,SAAS;;AAE5B,MAAI,OAAO,iBACT,GAAE,OAAO,oCAAoC,OAAO;AAEtD,MAAI,aAAa;AACf,KAAE,OAAO,gCAAgC,aAAa;AACtD,KAAE,OAAO,gCAAgC,aAAa;AACtD,KAAE,OAAO,0BAA0B,OAAO;AAC1C,UAAO,EAAE,KAAK,MAAM,IAAI;;AAE1B,QAAM,MAAM"}

package/dist/middleware/csrf.d.ts

@@ -0,0 +1,15 @@
+import { ServerConfigSpec } from "../config.js";
+import { ServerVariables } from "../internal/context.js";
+import { MiddlewareHandler } from "hono";
+
+//#region src/middleware/csrf.d.ts
+
+/**
+ * @stable
+ */
+declare function createCsrfMiddleware(config: ServerConfigSpec['server']['csrf']): MiddlewareHandler<{
+  Variables: ServerVariables;
+}>;
+//#endregion
+export { createCsrfMiddleware };
+//# sourceMappingURL=csrf.d.ts.map

package/dist/middleware/csrf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"csrf.d.ts","names":[],"sources":["../../src/middleware/csrf.ts"],"sourcesContent":[],"mappings":";;;;;;;;;iBAsBgB,oBAAA,SACN,qCACP;aAA+B"}

package/dist/middleware/csrf.js

@@ -0,0 +1,77 @@
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { Buffer } from "node:buffer";
+
+//#region src/middleware/csrf.ts
+/**
+* Double-submit CSRF middleware. Targets browser flows: when a
+* request carries a session-cookie style credential we require the
+* client to echo the value of the `graphorin_csrf` cookie back in
+* the `X-CSRF-Token` header. Bearer-token (Authorization header)
+* requests are exempt because they are not vulnerable to the
+* confused-deputy attack the cookie pattern guards against.
+*
+* @packageDocumentation
+*/
+/**
+* @stable
+*/
+function createCsrfMiddleware(config) {
+	if (!config.enabled) return async (_, next) => {
+		await next();
+	};
+	const safeMethods = new Set(config.safeMethods.map((m) => m.toUpperCase()));
+	return async (c, next) => {
+		const method = c.req.method.toUpperCase();
+		const cookieValue = parseCookies(c.req.header("cookie")).get(config.cookieName);
+		const authHeader = c.req.header("authorization");
+		const isBearer = authHeader !== void 0 && /^bearer\s+/i.test(authHeader);
+		if (safeMethods.has(method) || isBearer) {
+			if (!isBearer && cookieValue === void 0) {
+				const token = randomBytes(24).toString("base64url");
+				c.header("Set-Cookie", `${config.cookieName}=${token}; Path=/; SameSite=Strict; Secure`);
+			}
+			await next();
+			return;
+		}
+		if (cookieValue === void 0) return c.json({
+			error: "csrf-denied",
+			message: "CSRF cookie missing on state-changing request."
+		}, 403);
+		const headerValue = c.req.header(config.headerName);
+		if (headerValue === void 0) return c.json({
+			error: "csrf-denied",
+			message: `CSRF header '${config.headerName}' missing.`
+		}, 403);
+		if (!constantTimeEqual(cookieValue, headerValue)) return c.json({
+			error: "csrf-denied",
+			message: "CSRF token mismatch."
+		}, 403);
+		await next();
+	};
+}
+function parseCookies(header) {
+	const out = /* @__PURE__ */ new Map();
+	if (header === void 0) return out;
+	const parts = header.split(";");
+	for (const part of parts) {
+		const trimmed = part.trim();
+		if (trimmed.length === 0) continue;
+		const eq = trimmed.indexOf("=");
+		if (eq < 0) continue;
+		const name = trimmed.slice(0, eq).trim();
+		const value = trimmed.slice(eq + 1).trim();
+		out.set(name, value);
+	}
+	return out;
+}
+function constantTimeEqual(a, b) {
+	if (a.length !== b.length) return false;
+	const aBuf = Buffer.from(a, "utf8");
+	const bBuf = Buffer.from(b, "utf8");
+	if (aBuf.length !== bBuf.length) return false;
+	return timingSafeEqual(aBuf, bBuf);
+}
+
+//#endregion
+export { createCsrfMiddleware };
+//# sourceMappingURL=csrf.js.map

package/dist/middleware/csrf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"csrf.js","names":[],"sources":["../../src/middleware/csrf.ts"],"sourcesContent":["/**\n * Double-submit CSRF middleware. Targets browser flows: when a\n * request carries a session-cookie style credential we require the\n * client to echo the value of the `graphorin_csrf` cookie back in\n * the `X-CSRF-Token` header. Bearer-token (Authorization header)\n * requests are exempt because they are not vulnerable to the\n * confused-deputy attack the cookie pattern guards against.\n *\n * @packageDocumentation\n */\n\nimport { Buffer } from 'node:buffer';\nimport { randomBytes, timingSafeEqual } from 'node:crypto';\n\nimport type { MiddlewareHandler } from 'hono';\n\nimport type { ServerConfigSpec } from '../config.js';\nimport type { ServerVariables } from '../internal/context.js';\n\n/**\n * @stable\n */\nexport function createCsrfMiddleware(\n  config: ServerConfigSpec['server']['csrf'],\n): MiddlewareHandler<{ Variables: ServerVariables }> {\n  if (!config.enabled) {\n    return async (_, next) => {\n      await next();\n    };\n  }\n  const safeMethods = new Set(config.safeMethods.map((m) => m.toUpperCase()));\n\n  return async (c, next) => {\n    const method = c.req.method.toUpperCase();\n    const cookieHeader = c.req.header('cookie');\n    const cookies = parseCookies(cookieHeader);\n    const cookieValue = cookies.get(config.cookieName);\n    const authHeader = c.req.header('authorization');\n    const isBearer = authHeader !== undefined && /^bearer\\s+/i.test(authHeader);\n\n    if (safeMethods.has(method) || isBearer) {\n      // Always issue a fresh CSRF cookie on browser flows so SPAs\n      // can read it on first load. Skip the cookie issuance for\n      // bearer-only callers — they don't need it.\n      if (!isBearer && cookieValue === undefined) {\n        const token = randomBytes(24).toString('base64url');\n        // IP-12: the CSRF token must be readable by the SPA for the\n        // double-submit echo, so the cookie carries NO HttpOnly attribute —\n        // RFC 6265 enables HttpOnly on its mere presence, even `HttpOnly=false`.\n        c.header('Set-Cookie', `${config.cookieName}=${token}; Path=/; SameSite=Strict; Secure`);\n      }\n      await next();\n      return;\n    }\n\n    if (cookieValue === undefined) {\n      return c.json(\n        { error: 'csrf-denied', message: 'CSRF cookie missing on state-changing request.' },\n        403,\n      );\n    }\n    const headerValue = c.req.header(config.headerName);\n    if (headerValue === undefined) {\n      return c.json(\n        { error: 'csrf-denied', message: `CSRF header '${config.headerName}' missing.` },\n        403,\n      );\n    }\n    if (!constantTimeEqual(cookieValue, headerValue)) {\n      return c.json({ error: 'csrf-denied', message: 'CSRF token mismatch.' }, 403);\n    }\n    await next();\n  };\n}\n\nfunction parseCookies(header: string | undefined): Map<string, string> {\n  const out = new Map<string, string>();\n  if (header === undefined) return out;\n  const parts = header.split(';');\n  for (const part of parts) {\n    const trimmed = part.trim();\n    if (trimmed.length === 0) continue;\n    const eq = trimmed.indexOf('=');\n    if (eq < 0) continue;\n    const name = trimmed.slice(0, eq).trim();\n    const value = trimmed.slice(eq + 1).trim();\n    out.set(name, value);\n  }\n  return out;\n}\n\nfunction constantTimeEqual(a: string, b: string): boolean {\n  if (a.length !== b.length) return false;\n  const aBuf = Buffer.from(a, 'utf8');\n  const bBuf = Buffer.from(b, 'utf8');\n  if (aBuf.length !== bBuf.length) return false;\n  return timingSafeEqual(aBuf, bBuf);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAsBA,SAAgB,qBACd,QACmD;AACnD,KAAI,CAAC,OAAO,QACV,QAAO,OAAO,GAAG,SAAS;AACxB,QAAM,MAAM;;CAGhB,MAAM,cAAc,IAAI,IAAI,OAAO,YAAY,KAAK,MAAM,EAAE,aAAa,CAAC,CAAC;AAE3E,QAAO,OAAO,GAAG,SAAS;EACxB,MAAM,SAAS,EAAE,IAAI,OAAO,aAAa;EAGzC,MAAM,cADU,aADK,EAAE,IAAI,OAAO,SAAS,CACD,CACd,IAAI,OAAO,WAAW;EAClD,MAAM,aAAa,EAAE,IAAI,OAAO,gBAAgB;EAChD,MAAM,WAAW,eAAe,UAAa,cAAc,KAAK,WAAW;AAE3E,MAAI,YAAY,IAAI,OAAO,IAAI,UAAU;AAIvC,OAAI,CAAC,YAAY,gBAAgB,QAAW;IAC1C,MAAM,QAAQ,YAAY,GAAG,CAAC,SAAS,YAAY;AAInD,MAAE,OAAO,cAAc,GAAG,OAAO,WAAW,GAAG,MAAM,mCAAmC;;AAE1F,SAAM,MAAM;AACZ;;AAGF,MAAI,gBAAgB,OAClB,QAAO,EAAE,KACP;GAAE,OAAO;GAAe,SAAS;GAAkD,EACnF,IACD;EAEH,MAAM,cAAc,EAAE,IAAI,OAAO,OAAO,WAAW;AACnD,MAAI,gBAAgB,OAClB,QAAO,EAAE,KACP;GAAE,OAAO;GAAe,SAAS,gBAAgB,OAAO,WAAW;GAAa,EAChF,IACD;AAEH,MAAI,CAAC,kBAAkB,aAAa,YAAY,CAC9C,QAAO,EAAE,KAAK;GAAE,OAAO;GAAe,SAAS;GAAwB,EAAE,IAAI;AAE/E,QAAM,MAAM;;;AAIhB,SAAS,aAAa,QAAiD;CACrE,MAAM,sBAAM,IAAI,KAAqB;AACrC,KAAI,WAAW,OAAW,QAAO;CACjC,MAAM,QAAQ,OAAO,MAAM,IAAI;AAC/B,MAAK,MAAM,QAAQ,OAAO;EACxB,MAAM,UAAU,KAAK,MAAM;AAC3B,MAAI,QAAQ,WAAW,EAAG;EAC1B,MAAM,KAAK,QAAQ,QAAQ,IAAI;AAC/B,MAAI,KAAK,EAAG;EACZ,MAAM,OAAO,QAAQ,MAAM,GAAG,GAAG,CAAC,MAAM;EACxC,MAAM,QAAQ,QAAQ,MAAM,KAAK,EAAE,CAAC,MAAM;AAC1C,MAAI,IAAI,MAAM,MAAM;;AAEtB,QAAO;;AAGT,SAAS,kBAAkB,GAAW,GAAoB;AACxD,KAAI,EAAE,WAAW,EAAE,OAAQ,QAAO;CAClC,MAAM,OAAO,OAAO,KAAK,GAAG,OAAO;CACnC,MAAM,OAAO,OAAO,KAAK,GAAG,OAAO;AACnC,KAAI,KAAK,WAAW,KAAK,OAAQ,QAAO;AACxC,QAAO,gBAAgB,MAAM,KAAK"}

package/dist/middleware/idempotency.d.ts

@@ -0,0 +1,41 @@
+import { ServerConfigSpec } from "../config.js";
+import { ServerVariables } from "../internal/context.js";
+import { MetricRegistry } from "../metrics/registry.js";
+import { IdempotencyStore } from "@graphorin/store-sqlite";
+import { MiddlewareHandler } from "hono";
+
+//#region src/middleware/idempotency.d.ts
+
+/**
+ * Options accepted by {@link createIdempotencyMiddleware}.
+ *
+ * @stable
+ */
+interface IdempotencyMiddlewareOptions {
+  /**
+   * Paths whose responses are NEVER cached or replayed (IP-6) — the
+   * middleware passes straight through. Used for secret-bearing
+   * endpoints (`POST /v1/tokens` returns a raw token; caching it would
+   * persist the secret plaintext in durable SQLite for the TTL).
+   */
+  readonly excludeResponseCachePaths?: ReadonlyArray<string>;
+  readonly store: IdempotencyStore;
+  readonly config: ServerConfigSpec['server']['idempotency'];
+  /** Wall-clock provider; tests inject a deterministic generator. */
+  readonly now?: () => number;
+  /**
+   * IP-15: when supplied, the middleware publishes a live
+   * `graphorin_idempotency_cache_hit_ratio` gauge (replays / replays+executes)
+   * instead of leaving the registered metric a permanently-empty series.
+   */
+  readonly metricRegistry?: MetricRegistry;
+}
+/**
+ * @stable
+ */
+declare function createIdempotencyMiddleware(options: IdempotencyMiddlewareOptions): MiddlewareHandler<{
+  Variables: ServerVariables;
+}>;
+//#endregion
+export { IdempotencyMiddlewareOptions, createIdempotencyMiddleware };
+//# sourceMappingURL=idempotency.d.ts.map

package/dist/middleware/idempotency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.d.ts","names":[],"sources":["../../src/middleware/idempotency.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;UA2CiB,4BAAA;;;;;;;uCAOsB;kBACrB;mBACC;;;;;;;;4BAQS;;;;;iBAWZ,2BAAA,UACL,+BACR;aAA+B"}

package/dist/middleware/idempotency.js

@@ -0,0 +1,198 @@
+import { SERVER_METRIC_NAMES } from "../metrics/catalog.js";
+import { fingerprintRequest } from "../internal/json.js";
+
+//#region src/middleware/idempotency.ts
+const HEADER_NAME = "idempotency-key";
+const SAFE_METHODS = new Set([
+	"GET",
+	"HEAD",
+	"OPTIONS",
+	"TRACE"
+]);
+const NON_CACHEABLE_STATUS = new Set([
+	408,
+	425,
+	429,
+	500,
+	502,
+	503,
+	504
+]);
+const KEY_RE = /^[A-Za-z0-9_\-:]{8,255}$/;
+/**
+* @stable
+*/
+function createIdempotencyMiddleware(options) {
+	const { store, config } = options;
+	if (!config.enabled) return async (_, next) => {
+		await next();
+	};
+	const now = options.now ?? Date.now;
+	const lru = new SimpleLru(config.lruCacheSize);
+	const excluded = new Set(options.excludeResponseCachePaths ?? []);
+	const registry = options.metricRegistry;
+	let hits = 0;
+	let lookups = 0;
+	const recordCacheOutcome = (hit) => {
+		if (registry === void 0) return;
+		lookups += 1;
+		if (hit) hits += 1;
+		registry.set(SERVER_METRIC_NAMES.idempotencyCacheHitRatio, hits / lookups);
+	};
+	return async (c, next) => {
+		if (SAFE_METHODS.has(c.req.method.toUpperCase())) {
+			await next();
+			return;
+		}
+		if (excluded.has(c.req.path)) {
+			await next();
+			return;
+		}
+		const key = c.req.header(HEADER_NAME)?.trim();
+		if (key === void 0 || key.length === 0) {
+			if (config.requireKey === "enforce") return c.json({
+				error: "idempotency-key-required",
+				message: "Idempotency-Key header is required for this endpoint.",
+				hint: "Set 'Idempotency-Key: <uuid>' on the request."
+			}, 400);
+			if (config.requireKey === "warn") c.header("Idempotency-Status", "header-missing");
+			await next();
+			return;
+		}
+		if (!KEY_RE.test(key)) return c.json({
+			error: "idempotency-key-required",
+			message: "Idempotency-Key must be 8-255 chars of [A-Za-z0-9_:-]."
+		}, 400);
+		c.set("state", {
+			...c.get("state"),
+			idempotencyKey: key
+		});
+		const fingerprint = await computeFingerprint(c);
+		const cached = lru.get(key);
+		let record;
+		if (cached !== void 0 && now() - cached.cachedAt < 300 * 1e3) record = cached.record;
+		else {
+			record = await store.get(key);
+			if (record !== null) lru.set(key, {
+				record,
+				cachedAt: now()
+			});
+		}
+		const auth = c.get("state").auth;
+		const principal = auth.kind === "token" ? auth.token.tokenId : "anonymous";
+		if (record !== null) {
+			if (record.scope !== void 0 && record.scope !== principal) return c.json({
+				error: "idempotency-conflict",
+				message: `Idempotency-Key '${key}' is bound to a different principal.`
+			}, 409);
+			if (config.checkBodyFingerprint && record.requestHash !== fingerprint) return c.json({
+				error: "idempotency-conflict",
+				message: `Idempotency-Key '${key}' was previously used with a different request body.`
+			}, 409);
+			if (record.expiresAt > now()) {
+				c.set("state", {
+					...c.get("state"),
+					idempotencyReplay: true
+				});
+				const headers = record.responseHeaders ?? {};
+				for (const [name, value] of Object.entries(headers)) c.header(name, value);
+				c.header("Idempotency-Replayed", "true");
+				recordCacheOutcome(true);
+				return new Response(JSON.stringify(record.response), {
+					status: record.statusCode,
+					headers: {
+						...headers,
+						"Content-Type": "application/json",
+						"Idempotency-Replayed": "true"
+					}
+				});
+			}
+			lru.delete(key);
+			await store.delete(key);
+		}
+		recordCacheOutcome(false);
+		await next();
+		const status = c.res.status;
+		if (NON_CACHEABLE_STATUS.has(status)) return;
+		const responseBody = await captureJsonResponse(c);
+		if (responseBody === null) return;
+		const responseHeaders = collectResponseHeaders(c);
+		const record_ = {
+			key,
+			requestHash: fingerprint,
+			statusCode: status,
+			response: responseBody,
+			...responseHeaders !== void 0 ? { responseHeaders } : {},
+			scope: principal,
+			createdAt: now(),
+			expiresAt: now() + config.ttlSeconds * 1e3
+		};
+		try {
+			await store.put(record_);
+			lru.set(key, {
+				record: record_,
+				cachedAt: now()
+			});
+		} catch {}
+	};
+}
+async function computeFingerprint(c) {
+	let body = null;
+	if (c.req.header("content-type")?.toLowerCase().includes("application/json")) try {
+		body = await c.req.json();
+	} catch {
+		body = await c.req.text();
+	}
+	else body = await c.req.text();
+	return fingerprintRequest(c.req.method, c.req.path, body);
+}
+async function captureJsonResponse(c) {
+	if (c.res === void 0) return null;
+	if (!(c.res.headers.get("content-type") ?? "").toLowerCase().includes("application/json")) return null;
+	try {
+		const text = await c.res.clone().text();
+		if (text.length === 0) return null;
+		return JSON.parse(text);
+	} catch {
+		return null;
+	}
+}
+function collectResponseHeaders(c) {
+	if (c.res === void 0) return void 0;
+	const out = {};
+	c.res.headers.forEach((value, name) => {
+		if (name.toLowerCase() === "content-length") return;
+		out[name] = value;
+	});
+	return Object.keys(out).length === 0 ? void 0 : Object.freeze(out);
+}
+var SimpleLru = class {
+	#capacity;
+	#map = /* @__PURE__ */ new Map();
+	constructor(capacity) {
+		this.#capacity = Math.max(1, capacity);
+	}
+	get(key) {
+		const value = this.#map.get(key);
+		if (value === void 0) return void 0;
+		this.#map.delete(key);
+		this.#map.set(key, value);
+		return value;
+	}
+	set(key, value) {
+		if (this.#map.has(key)) this.#map.delete(key);
+		this.#map.set(key, value);
+		while (this.#map.size > this.#capacity) {
+			const oldestKey = this.#map.keys().next().value;
+			if (oldestKey === void 0) break;
+			this.#map.delete(oldestKey);
+		}
+	}
+	delete(key) {
+		return this.#map.delete(key);
+	}
+};
+
+//#endregion
+export { createIdempotencyMiddleware };
+//# sourceMappingURL=idempotency.js.map

package/dist/middleware/idempotency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.js","names":["record: IdempotencyRecord | null","record_: IdempotencyRecord","body: unknown","out: Record<string, string>","#capacity","#map"],"sources":["../../src/middleware/idempotency.ts"],"sourcesContent":["/**\n * REST `Idempotency-Key` middleware per IETF\n * draft-ietf-httpapi-idempotency-key-header-07. Layers an LRU\n * read-cache over a durable {@link IdempotencyStore} so:\n *\n * - Replays of a successful request return the cached response body\n *   AND the original status code, with a synthetic\n *   `Idempotency-Replayed: true` header so clients can distinguish\n *   the cached path.\n * - Replays of a key with a different request body return `409\n *   Conflict` and a typed error body (per ADR-036 / DEC-142).\n * - 5xx + 408 + 429 + 503 responses are NOT cached so transient\n *   errors do not pin the operator into a non-recoverable state.\n *\n * Streaming endpoints (`/v1/agents/:id/stream`,\n * `/v1/workflows/:id/execute` when invoked with the `stream=true`\n * query) cache only the initial 202 + `runId` envelope; the actual\n * event stream is replayed via the WebSocket layer (Phase 14b).\n *\n * @packageDocumentation\n */\n\nimport type { IdempotencyRecord, IdempotencyStore } from '@graphorin/store-sqlite';\nimport type { Context, MiddlewareHandler } from 'hono';\n\nimport type { ServerConfigSpec } from '../config.js';\nimport type { ServerVariables } from '../internal/context.js';\nimport { fingerprintRequest } from '../internal/json.js';\nimport { SERVER_METRIC_NAMES } from '../metrics/catalog.js';\nimport type { MetricRegistry } from '../metrics/registry.js';\n\nconst HEADER_NAME = 'idempotency-key';\nconst SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS', 'TRACE']);\n// Status codes the IETF draft + Stripe convention exclude from\n// idempotent caching (always retry-eligible).\nconst NON_CACHEABLE_STATUS = new Set([408, 425, 429, 500, 502, 503, 504]);\nconst KEY_RE = /^[A-Za-z0-9_\\-:]{8,255}$/;\n\n/**\n * Options accepted by {@link createIdempotencyMiddleware}.\n *\n * @stable\n */\nexport interface IdempotencyMiddlewareOptions {\n  /**\n   * Paths whose responses are NEVER cached or replayed (IP-6) — the\n   * middleware passes straight through. Used for secret-bearing\n   * endpoints (`POST /v1/tokens` returns a raw token; caching it would\n   * persist the secret plaintext in durable SQLite for the TTL).\n   */\n  readonly excludeResponseCachePaths?: ReadonlyArray<string>;\n  readonly store: IdempotencyStore;\n  readonly config: ServerConfigSpec['server']['idempotency'];\n  /** Wall-clock provider; tests inject a deterministic generator. */\n  readonly now?: () => number;\n  /**\n   * IP-15: when supplied, the middleware publishes a live\n   * `graphorin_idempotency_cache_hit_ratio` gauge (replays / replays+executes)\n   * instead of leaving the registered metric a permanently-empty series.\n   */\n  readonly metricRegistry?: MetricRegistry;\n}\n\ninterface CacheEntry {\n  readonly record: IdempotencyRecord;\n  readonly cachedAt: number;\n}\n\n/**\n * @stable\n */\nexport function createIdempotencyMiddleware(\n  options: IdempotencyMiddlewareOptions,\n): MiddlewareHandler<{ Variables: ServerVariables }> {\n  const { store, config } = options;\n  if (!config.enabled) {\n    return async (_, next) => {\n      await next();\n    };\n  }\n  const now = options.now ?? Date.now;\n  const lru = new SimpleLru<string, CacheEntry>(config.lruCacheSize);\n\n  const excluded = new Set(options.excludeResponseCachePaths ?? []);\n\n  // IP-15: publish the cache hit ratio as a live gauge. A \"hit\" is a replay\n  // served from a stored record; a \"miss\" is a keyed request that executed\n  // fresh. Conflicts (409) are abnormal and excluded from the ratio.\n  const registry = options.metricRegistry;\n  let hits = 0;\n  let lookups = 0;\n  const recordCacheOutcome = (hit: boolean): void => {\n    if (registry === undefined) return;\n    lookups += 1;\n    if (hit) hits += 1;\n    registry.set(SERVER_METRIC_NAMES.idempotencyCacheHitRatio, hits / lookups);\n  };\n\n  return async (c, next) => {\n    if (SAFE_METHODS.has(c.req.method.toUpperCase())) {\n      await next();\n      return;\n    }\n    // IP-6: secret-bearing endpoints opt out of response caching\n    // entirely — repeats re-execute and no body is ever persisted.\n    if (excluded.has(c.req.path)) {\n      await next();\n      return;\n    }\n    const key = c.req.header(HEADER_NAME)?.trim();\n    if (key === undefined || key.length === 0) {\n      if (config.requireKey === 'enforce') {\n        return c.json(\n          {\n            error: 'idempotency-key-required',\n            message: 'Idempotency-Key header is required for this endpoint.',\n            hint: \"Set 'Idempotency-Key: <uuid>' on the request.\",\n          },\n          400,\n        );\n      }\n      // 'warn' / 'off' — pass-through with a hint header.\n      if (config.requireKey === 'warn') {\n        c.header('Idempotency-Status', 'header-missing');\n      }\n      await next();\n      return;\n    }\n    if (!KEY_RE.test(key)) {\n      return c.json(\n        {\n          error: 'idempotency-key-required',\n          message: 'Idempotency-Key must be 8-255 chars of [A-Za-z0-9_:-].',\n        },\n        400,\n      );\n    }\n    c.set('state', { ...c.get('state'), idempotencyKey: key });\n    const fingerprint = await computeFingerprint(c);\n    const cached = lru.get(key);\n    let record: IdempotencyRecord | null;\n    if (cached !== undefined && now() - cached.cachedAt < 5 * 60 * 1000) {\n      record = cached.record;\n    } else {\n      record = await store.get(key);\n      if (record !== null) {\n        lru.set(key, { record, cachedAt: now() });\n      }\n    }\n    // IP-6: the verified principal the record is bound to. Replays are\n    // served only to the SAME principal that originally executed the\n    // request (who passed the route's scope checks at execute time) —\n    // a different token cannot fetch someone else's cached response,\n    // closing the scope-bypass the pre-router mount opened.\n    const auth = c.get('state').auth;\n    const principal = auth.kind === 'token' ? auth.token.tokenId : 'anonymous';\n    if (record !== null) {\n      if (record.scope !== undefined && record.scope !== principal) {\n        return c.json(\n          {\n            error: 'idempotency-conflict',\n            message: `Idempotency-Key '${key}' is bound to a different principal.`,\n          },\n          409,\n        );\n      }\n      if (config.checkBodyFingerprint && record.requestHash !== fingerprint) {\n        return c.json(\n          {\n            error: 'idempotency-conflict',\n            message: `Idempotency-Key '${key}' was previously used with a different request body.`,\n          },\n          409,\n        );\n      }\n      if (record.expiresAt > now()) {\n        c.set('state', { ...c.get('state'), idempotencyReplay: true });\n        const headers = record.responseHeaders ?? {};\n        for (const [name, value] of Object.entries(headers)) {\n          c.header(name, value);\n        }\n        c.header('Idempotency-Replayed', 'true');\n        recordCacheOutcome(true);\n        return new Response(JSON.stringify(record.response), {\n          status: record.statusCode,\n          headers: {\n            ...headers,\n            'Content-Type': 'application/json',\n            'Idempotency-Replayed': 'true',\n          },\n        });\n      }\n      // Expired — fall through to re-execute.\n      lru.delete(key);\n      await store.delete(key);\n    }\n\n    // A keyed request that reaches execution is a cache miss.\n    recordCacheOutcome(false);\n    await next();\n\n    const status = c.res.status;\n    if (NON_CACHEABLE_STATUS.has(status)) {\n      // Retry-eligible — leave nothing in the cache.\n      return;\n    }\n    const responseBody = await captureJsonResponse(c);\n    if (responseBody === null) {\n      // Non-JSON or empty body — skip caching to keep the schema\n      // simple; clients that need response replay can use bodied\n      // POSTs.\n      return;\n    }\n    const responseHeaders = collectResponseHeaders(c);\n    const record_: IdempotencyRecord = {\n      key,\n      requestHash: fingerprint,\n      statusCode: status,\n      response: responseBody,\n      ...(responseHeaders !== undefined ? { responseHeaders } : {}),\n      // IP-6: bind the record to the executing principal.\n      scope: principal,\n      createdAt: now(),\n      expiresAt: now() + config.ttlSeconds * 1000,\n    };\n    try {\n      await store.put(record_);\n      lru.set(key, { record: record_, cachedAt: now() });\n    } catch {\n      // Best-effort cache. Persistence failures must not break the\n      // hot path — operators see them via the audit log + logger.\n    }\n  };\n}\n\nasync function computeFingerprint(c: Context<{ Variables: ServerVariables }>): Promise<string> {\n  let body: unknown = null;\n  const ct = c.req.header('content-type');\n  if (ct?.toLowerCase().includes('application/json')) {\n    try {\n      body = await c.req.json();\n    } catch {\n      body = await c.req.text();\n    }\n  } else {\n    body = await c.req.text();\n  }\n  return fingerprintRequest(c.req.method, c.req.path, body);\n}\n\nasync function captureJsonResponse(\n  c: Context<{ Variables: ServerVariables }>,\n): Promise<unknown | null> {\n  if (c.res === undefined) return null;\n  const contentType = c.res.headers.get('content-type') ?? '';\n  if (!contentType.toLowerCase().includes('application/json')) return null;\n  try {\n    const cloned = c.res.clone();\n    const text = await cloned.text();\n    if (text.length === 0) return null;\n    return JSON.parse(text);\n  } catch {\n    return null;\n  }\n}\n\nfunction collectResponseHeaders(\n  c: Context<{ Variables: ServerVariables }>,\n): Readonly<Record<string, string>> | undefined {\n  if (c.res === undefined) return undefined;\n  const out: Record<string, string> = {};\n  c.res.headers.forEach((value, name) => {\n    if (name.toLowerCase() === 'content-length') return;\n    out[name] = value;\n  });\n  return Object.keys(out).length === 0 ? undefined : Object.freeze(out);\n}\n\nclass SimpleLru<K, V> {\n  readonly #capacity: number;\n  readonly #map: Map<K, V> = new Map();\n\n  constructor(capacity: number) {\n    this.#capacity = Math.max(1, capacity);\n  }\n\n  get(key: K): V | undefined {\n    const value = this.#map.get(key);\n    if (value === undefined) return undefined;\n    this.#map.delete(key);\n    this.#map.set(key, value);\n    return value;\n  }\n\n  set(key: K, value: V): void {\n    if (this.#map.has(key)) this.#map.delete(key);\n    this.#map.set(key, value);\n    while (this.#map.size > this.#capacity) {\n      const oldestKey = this.#map.keys().next().value as K | undefined;\n      if (oldestKey === undefined) break;\n      this.#map.delete(oldestKey);\n    }\n  }\n\n  delete(key: K): boolean {\n    return this.#map.delete(key);\n  }\n}\n"],"mappings":"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"}

package/dist/middleware/index.d.ts

@@ -0,0 +1,9 @@
+import { AuditErrorSink, AuditMiddlewareOptions, HTTP_REQUEST_AUDIT_ACTION, createAuditMiddleware } from "./audit.js";
+import { AuthMiddlewareOptions, createAnonymousAuthMiddleware, createAuthMiddleware } from "./auth.js";
+import { createCorsMiddleware } from "./cors.js";
+import { createCsrfMiddleware } from "./csrf.js";
+import { IdempotencyMiddlewareOptions, createIdempotencyMiddleware } from "./idempotency.js";
+import { createRateLimitMiddleware } from "./rate-limit.js";
+import { RequestStateMiddlewareOptions, createRequestStateMiddleware } from "./request-state.js";
+import { ScopeRequirement, createScopeMiddleware } from "./scope.js";
+export { type AuditErrorSink, type AuditMiddlewareOptions, type AuthMiddlewareOptions, HTTP_REQUEST_AUDIT_ACTION, type IdempotencyMiddlewareOptions, type RequestStateMiddlewareOptions, type ScopeRequirement, createAnonymousAuthMiddleware, createAuditMiddleware, createAuthMiddleware, createCorsMiddleware, createCsrfMiddleware, createIdempotencyMiddleware, createRateLimitMiddleware, createRequestStateMiddleware, createScopeMiddleware };

package/dist/middleware/index.js

@@ -0,0 +1,10 @@
+import { createScopeMiddleware } from "./scope.js";
+import { HTTP_REQUEST_AUDIT_ACTION, createAuditMiddleware } from "./audit.js";
+import { createAnonymousAuthMiddleware, createAuthMiddleware } from "./auth.js";
+import { createCorsMiddleware } from "./cors.js";
+import { createCsrfMiddleware } from "./csrf.js";
+import { createIdempotencyMiddleware } from "./idempotency.js";
+import { createRateLimitMiddleware } from "./rate-limit.js";
+import { createRequestStateMiddleware } from "./request-state.js";
+
+export { HTTP_REQUEST_AUDIT_ACTION, createAnonymousAuthMiddleware, createAuditMiddleware, createAuthMiddleware, createCorsMiddleware, createCsrfMiddleware, createIdempotencyMiddleware, createRateLimitMiddleware, createRequestStateMiddleware, createScopeMiddleware };

package/dist/middleware/rate-limit.d.ts

@@ -0,0 +1,17 @@
+import { ServerConfigSpec } from "../config.js";
+import { ServerVariables } from "../internal/context.js";
+import { MiddlewareHandler } from "hono";
+
+//#region src/middleware/rate-limit.d.ts
+
+/**
+ * @stable
+ */
+declare function createRateLimitMiddleware(config: ServerConfigSpec['server']['rateLimit'], options?: {
+  readonly now?: () => number;
+}): MiddlewareHandler<{
+  Variables: ServerVariables;
+}>;
+//#endregion
+export { createRateLimitMiddleware };
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/middleware/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","names":[],"sources":["../../src/middleware/rate-limit.ts"],"sourcesContent":[],"mappings":";;;;;;;;;iBAsBgB,yBAAA,SACN;;IAEP;aAA+B"}

package/dist/middleware/rate-limit.js

@@ -0,0 +1,47 @@
+//#region src/middleware/rate-limit.ts
+/**
+* @stable
+*/
+function createRateLimitMiddleware(config, options = {}) {
+	if (!config.enabled) return async (_, next) => {
+		await next();
+	};
+	const windows = /* @__PURE__ */ new Map();
+	const now = options.now ?? Date.now;
+	const SWEEP_THRESHOLD = 1e4;
+	const sweep = (ts) => {
+		if (windows.size < SWEEP_THRESHOLD) return;
+		for (const [key, win] of windows) if (ts - win.start >= config.windowMs) windows.delete(key);
+	};
+	return async (c, next) => {
+		const ip = c.get("state").clientIp ?? "anonymous";
+		const ts = now();
+		sweep(ts);
+		const window = windows.get(ip) ?? {
+			count: 0,
+			start: ts
+		};
+		if (ts - window.start >= config.windowMs) {
+			window.start = ts;
+			window.count = 0;
+		}
+		window.count += 1;
+		windows.set(ip, window);
+		const remaining = Math.max(0, config.perIpRequests - window.count);
+		c.header("X-RateLimit-Limit", config.perIpRequests.toString());
+		c.header("X-RateLimit-Remaining", remaining.toString());
+		c.header("X-RateLimit-Reset", Math.max(0, Math.ceil((window.start + config.windowMs - ts) / 1e3)).toString());
+		if (window.count > config.perIpRequests) {
+			const retryAfter = Math.max(0, Math.ceil((window.start + config.windowMs - ts) / 1e3));
+			return c.json({
+				error: "rate-limit-exceeded",
+				message: "Too many requests."
+			}, 429, { "Retry-After": retryAfter.toString() });
+		}
+		await next();
+	};
+}
+
+//#endregion
+export { createRateLimitMiddleware };
+//# sourceMappingURL=rate-limit.js.map

package/dist/middleware/rate-limit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.js","names":[],"sources":["../../src/middleware/rate-limit.ts"],"sourcesContent":["/**\n * Per-IP sliding-window rate limit. Defends against brute-force\n * authentication probes and naive DoS scenarios. The limit is\n * deliberately conservative — operators with multi-tenant traffic\n * should layer a dedicated reverse proxy on top.\n *\n * @packageDocumentation\n */\n\nimport type { MiddlewareHandler } from 'hono';\n\nimport type { ServerConfigSpec } from '../config.js';\nimport type { ServerVariables } from '../internal/context.js';\n\ninterface Window {\n  count: number;\n  start: number;\n}\n\n/**\n * @stable\n */\nexport function createRateLimitMiddleware(\n  config: ServerConfigSpec['server']['rateLimit'],\n  options: { readonly now?: () => number } = {},\n): MiddlewareHandler<{ Variables: ServerVariables }> {\n  if (!config.enabled) {\n    return async (_, next) => {\n      await next();\n    };\n  }\n  const windows = new Map<string, Window>();\n  const now = options.now ?? Date.now;\n  // IP-10: bound the window map — expired entries are swept once the\n  // map crosses the cap so an attacker rotating spoofed XFF values\n  // (trustProxy=true deployments) cannot grow it without bound.\n  const SWEEP_THRESHOLD = 10_000;\n  const sweep = (ts: number): void => {\n    if (windows.size < SWEEP_THRESHOLD) return;\n    for (const [key, win] of windows) {\n      if (ts - win.start >= config.windowMs) windows.delete(key);\n    }\n  };\n\n  return async (c, next) => {\n    const ip = c.get('state').clientIp ?? 'anonymous';\n    const ts = now();\n    sweep(ts);\n    const window = windows.get(ip) ?? { count: 0, start: ts };\n    if (ts - window.start >= config.windowMs) {\n      window.start = ts;\n      window.count = 0;\n    }\n    window.count += 1;\n    windows.set(ip, window);\n    const remaining = Math.max(0, config.perIpRequests - window.count);\n    c.header('X-RateLimit-Limit', config.perIpRequests.toString());\n    c.header('X-RateLimit-Remaining', remaining.toString());\n    c.header(\n      'X-RateLimit-Reset',\n      Math.max(0, Math.ceil((window.start + config.windowMs - ts) / 1000)).toString(),\n    );\n    if (window.count > config.perIpRequests) {\n      const retryAfter = Math.max(0, Math.ceil((window.start + config.windowMs - ts) / 1000));\n      return c.json({ error: 'rate-limit-exceeded', message: 'Too many requests.' }, 429, {\n        'Retry-After': retryAfter.toString(),\n      });\n    }\n    await next();\n  };\n}\n"],"mappings":";;;;AAsBA,SAAgB,0BACd,QACA,UAA2C,EAAE,EACM;AACnD,KAAI,CAAC,OAAO,QACV,QAAO,OAAO,GAAG,SAAS;AACxB,QAAM,MAAM;;CAGhB,MAAM,0BAAU,IAAI,KAAqB;CACzC,MAAM,MAAM,QAAQ,OAAO,KAAK;CAIhC,MAAM,kBAAkB;CACxB,MAAM,SAAS,OAAqB;AAClC,MAAI,QAAQ,OAAO,gBAAiB;AACpC,OAAK,MAAM,CAAC,KAAK,QAAQ,QACvB,KAAI,KAAK,IAAI,SAAS,OAAO,SAAU,SAAQ,OAAO,IAAI;;AAI9D,QAAO,OAAO,GAAG,SAAS;EACxB,MAAM,KAAK,EAAE,IAAI,QAAQ,CAAC,YAAY;EACtC,MAAM,KAAK,KAAK;AAChB,QAAM,GAAG;EACT,MAAM,SAAS,QAAQ,IAAI,GAAG,IAAI;GAAE,OAAO;GAAG,OAAO;GAAI;AACzD,MAAI,KAAK,OAAO,SAAS,OAAO,UAAU;AACxC,UAAO,QAAQ;AACf,UAAO,QAAQ;;AAEjB,SAAO,SAAS;AAChB,UAAQ,IAAI,IAAI,OAAO;EACvB,MAAM,YAAY,KAAK,IAAI,GAAG,OAAO,gBAAgB,OAAO,MAAM;AAClE,IAAE,OAAO,qBAAqB,OAAO,cAAc,UAAU,CAAC;AAC9D,IAAE,OAAO,yBAAyB,UAAU,UAAU,CAAC;AACvD,IAAE,OACA,qBACA,KAAK,IAAI,GAAG,KAAK,MAAM,OAAO,QAAQ,OAAO,WAAW,MAAM,IAAK,CAAC,CAAC,UAAU,CAChF;AACD,MAAI,OAAO,QAAQ,OAAO,eAAe;GACvC,MAAM,aAAa,KAAK,IAAI,GAAG,KAAK,MAAM,OAAO,QAAQ,OAAO,WAAW,MAAM,IAAK,CAAC;AACvF,UAAO,EAAE,KAAK;IAAE,OAAO;IAAuB,SAAS;IAAsB,EAAE,KAAK,EAClF,eAAe,WAAW,UAAU,EACrC,CAAC;;AAEJ,QAAM,MAAM"}

package/dist/middleware/request-state.d.ts

@@ -0,0 +1,27 @@
+import { ServerVariables } from "../internal/context.js";
+import { MiddlewareHandler } from "hono";
+
+//#region src/middleware/request-state.d.ts
+
+/**
+ * @stable
+ */
+interface RequestStateMiddlewareOptions {
+  /** Override the wall clock; tests inject a fixed value. */
+  readonly now?: () => number;
+  /** Override the request id generator. */
+  readonly newRequestId?: () => string;
+  /** Trust `X-Forwarded-For`/`X-Real-IP` for the client IP. Default false. */
+  readonly trustProxy?: boolean;
+  /** Echo the request id back to the client. Default `'X-Request-Id'`. */
+  readonly responseHeader?: string | false;
+}
+/**
+ * @stable
+ */
+declare function createRequestStateMiddleware(options?: RequestStateMiddlewareOptions): MiddlewareHandler<{
+  Variables: ServerVariables;
+}>;
+//#endregion
+export { RequestStateMiddlewareOptions, createRequestStateMiddleware };
+//# sourceMappingURL=request-state.d.ts.map

package/dist/middleware/request-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-state.d.ts","names":[],"sources":["../../src/middleware/request-state.ts"],"sourcesContent":[],"mappings":";;;;;;;;UAgBiB,6BAAA;;;;;;;;;;;;;iBA8BD,4BAAA,WACL,gCACR;aAA+B"}

package/dist/middleware/request-state.js

@@ -0,0 +1,42 @@
+import { newRequestId } from "../internal/ids.js";
+
+//#region src/middleware/request-state.ts
+function clientIp(headerLookup, trustProxy) {
+	if (trustProxy) {
+		const xff = headerLookup("x-forwarded-for");
+		if (xff !== void 0 && xff.length > 0) {
+			const [first] = xff.split(",");
+			if (first !== void 0) return first.trim();
+		}
+		const xri = headerLookup("x-real-ip");
+		if (xri !== void 0 && xri.length > 0) return xri.trim();
+	}
+}
+/**
+* @stable
+*/
+function createRequestStateMiddleware(options = {}) {
+	const now = options.now ?? Date.now;
+	const idFactory = options.newRequestId ?? newRequestId;
+	const trustProxy = options.trustProxy ?? false;
+	const responseHeader = options.responseHeader === void 0 ? "X-Request-Id" : options.responseHeader;
+	return async (c, next) => {
+		const headerLookup = (name) => c.req.header(name);
+		const requestId = headerLookup("x-request-id")?.trim() || idFactory();
+		const socketAddress = c.env?.incoming?.socket?.remoteAddress;
+		const ip = clientIp(headerLookup, trustProxy) ?? socketAddress;
+		const state = {
+			requestId,
+			receivedAt: now(),
+			clientIp: ip,
+			auth: { kind: "unauthenticated" }
+		};
+		c.set("state", state);
+		if (responseHeader !== false) c.header(responseHeader, requestId);
+		await next();
+	};
+}
+
+//#endregion
+export { createRequestStateMiddleware };
+//# sourceMappingURL=request-state.js.map

package/dist/middleware/request-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-state.js","names":["state: ServerRequestState"],"sources":["../../src/middleware/request-state.ts"],"sourcesContent":["/**\n * Bootstraps the per-request `c.var.state` slot. Every server-owned\n * middleware downstream reads from this object; defaults are kept on\n * a single line per field so the structure is auditable at a glance.\n *\n * @packageDocumentation\n */\n\nimport type { MiddlewareHandler } from 'hono';\n\nimport type { ServerRequestState, ServerVariables } from '../internal/context.js';\nimport { newRequestId } from '../internal/ids.js';\n\n/**\n * @stable\n */\nexport interface RequestStateMiddlewareOptions {\n  /** Override the wall clock; tests inject a fixed value. */\n  readonly now?: () => number;\n  /** Override the request id generator. */\n  readonly newRequestId?: () => string;\n  /** Trust `X-Forwarded-For`/`X-Real-IP` for the client IP. Default false. */\n  readonly trustProxy?: boolean;\n  /** Echo the request id back to the client. Default `'X-Request-Id'`. */\n  readonly responseHeader?: string | false;\n}\n\nfunction clientIp(\n  headerLookup: (name: string) => string | undefined,\n  trustProxy: boolean,\n): string | undefined {\n  if (trustProxy) {\n    const xff = headerLookup('x-forwarded-for');\n    if (xff !== undefined && xff.length > 0) {\n      const [first] = xff.split(',');\n      if (first !== undefined) return first.trim();\n    }\n    const xri = headerLookup('x-real-ip');\n    if (xri !== undefined && xri.length > 0) return xri.trim();\n  }\n  return undefined;\n}\n\n/**\n * @stable\n */\nexport function createRequestStateMiddleware(\n  options: RequestStateMiddlewareOptions = {},\n): MiddlewareHandler<{ Variables: ServerVariables }> {\n  const now = options.now ?? Date.now;\n  const idFactory = options.newRequestId ?? newRequestId;\n  const trustProxy = options.trustProxy ?? false;\n  const responseHeader =\n    options.responseHeader === undefined ? 'X-Request-Id' : options.responseHeader;\n\n  return async (c, next) => {\n    const headerLookup = (name: string): string | undefined => c.req.header(name);\n    const requestId = headerLookup('x-request-id')?.trim() || idFactory();\n    // IP-10: with the default trustProxy=false the proxy headers are\n    // ignored — the client IP comes from the SOCKET, so per-IP rate\n    // limits and lockouts actually key per client instead of dumping\n    // every request into one shared 'anonymous' bucket.\n    const socketAddress = (\n      c.env as { incoming?: { socket?: { remoteAddress?: string } } } | undefined\n    )?.incoming?.socket?.remoteAddress;\n    const ip = clientIp(headerLookup, trustProxy) ?? socketAddress;\n    const state: ServerRequestState = {\n      requestId,\n      receivedAt: now(),\n      clientIp: ip,\n      auth: { kind: 'unauthenticated' },\n    };\n    c.set('state', state);\n    if (responseHeader !== false) {\n      c.header(responseHeader, requestId);\n    }\n    await next();\n  };\n}\n"],"mappings":";;;AA2BA,SAAS,SACP,cACA,YACoB;AACpB,KAAI,YAAY;EACd,MAAM,MAAM,aAAa,kBAAkB;AAC3C,MAAI,QAAQ,UAAa,IAAI,SAAS,GAAG;GACvC,MAAM,CAAC,SAAS,IAAI,MAAM,IAAI;AAC9B,OAAI,UAAU,OAAW,QAAO,MAAM,MAAM;;EAE9C,MAAM,MAAM,aAAa,YAAY;AACrC,MAAI,QAAQ,UAAa,IAAI,SAAS,EAAG,QAAO,IAAI,MAAM;;;;;;AAQ9D,SAAgB,6BACd,UAAyC,EAAE,EACQ;CACnD,MAAM,MAAM,QAAQ,OAAO,KAAK;CAChC,MAAM,YAAY,QAAQ,gBAAgB;CAC1C,MAAM,aAAa,QAAQ,cAAc;CACzC,MAAM,iBACJ,QAAQ,mBAAmB,SAAY,iBAAiB,QAAQ;AAElE,QAAO,OAAO,GAAG,SAAS;EACxB,MAAM,gBAAgB,SAAqC,EAAE,IAAI,OAAO,KAAK;EAC7E,MAAM,YAAY,aAAa,eAAe,EAAE,MAAM,IAAI,WAAW;EAKrE,MAAM,gBACJ,EAAE,KACD,UAAU,QAAQ;EACrB,MAAM,KAAK,SAAS,cAAc,WAAW,IAAI;EACjD,MAAMA,QAA4B;GAChC;GACA,YAAY,KAAK;GACjB,UAAU;GACV,MAAM,EAAE,MAAM,mBAAmB;GAClC;AACD,IAAE,IAAI,SAAS,MAAM;AACrB,MAAI,mBAAmB,MACrB,GAAE,OAAO,gBAAgB,UAAU;AAErC,QAAM,MAAM"}