@graphorin/server 0.5.0

package/dist/metrics/registry.js

@@ -0,0 +1,222 @@
+//#region src/metrics/registry.ts
+const SUMMARY_SAMPLE_CAP = 1024;
+const SUMMARY_QUANTILES = Object.freeze([.5, .95]);
+/**
+* Lightweight Prometheus registry. Each instance owns its metric
+* catalogue + per-label samples; `render()` emits the canonical text
+* exposition block.
+*
+* @stable
+*/
+var MetricRegistry = class {
+	#definitions = /* @__PURE__ */ new Map();
+	#counters = /* @__PURE__ */ new Map();
+	#gauges = /* @__PURE__ */ new Map();
+	#summaries = /* @__PURE__ */ new Map();
+	registerCounter(name, help, labelNames = []) {
+		this.#register(name, help, "counter", labelNames);
+		if (!this.#counters.has(name)) this.#counters.set(name, /* @__PURE__ */ new Map());
+	}
+	registerGauge(name, help, labelNames = []) {
+		this.#register(name, help, "gauge", labelNames);
+		if (!this.#gauges.has(name)) this.#gauges.set(name, /* @__PURE__ */ new Map());
+	}
+	registerSummary(name, help, labelNames = []) {
+		this.#register(name, help, "summary", labelNames);
+		if (!this.#summaries.has(name)) this.#summaries.set(name, /* @__PURE__ */ new Map());
+	}
+	inc(name, labels = {}, by = 1) {
+		this.#assertKind(name, "counter");
+		assertLabelNames(labels);
+		const bucket = this.#counters.get(name);
+		if (bucket === void 0) throw new Error(`MetricRegistry.inc: counter '${name}' is not registered`);
+		const key = serializeLabelKey(labels);
+		const entry = bucket.get(key) ?? {
+			labels: { ...labels },
+			value: 0
+		};
+		if (!Number.isFinite(by)) throw new Error(`MetricRegistry.inc(${name}): by must be finite`);
+		if (by < 0) throw new Error(`MetricRegistry.inc(${name}): counters never decrement`);
+		entry.value += by;
+		bucket.set(key, entry);
+	}
+	set(name, value, labels = {}) {
+		this.#assertKind(name, "gauge");
+		assertLabelNames(labels);
+		const bucket = this.#gauges.get(name);
+		if (bucket === void 0) throw new Error(`MetricRegistry.set: gauge '${name}' is not registered`);
+		const key = serializeLabelKey(labels);
+		bucket.set(key, {
+			labels: { ...labels },
+			value
+		});
+	}
+	observe(name, value, labels = {}) {
+		this.#assertKind(name, "summary");
+		assertLabelNames(labels);
+		const bucket = this.#summaries.get(name);
+		if (bucket === void 0) throw new Error(`MetricRegistry.observe: summary '${name}' is not registered`);
+		const key = serializeLabelKey(labels);
+		const entry = bucket.get(key) ?? {
+			labels: { ...labels },
+			count: 0,
+			sum: 0,
+			samples: []
+		};
+		entry.count += 1;
+		entry.sum += value;
+		entry.samples.push(value);
+		if (entry.samples.length > SUMMARY_SAMPLE_CAP) entry.samples.shift();
+		bucket.set(key, entry);
+	}
+	reset() {
+		this.#counters.clear();
+		this.#gauges.clear();
+		this.#summaries.clear();
+		for (const [name, def] of this.#definitions) switch (def.kind) {
+			case "counter":
+				this.#counters.set(name, /* @__PURE__ */ new Map());
+				break;
+			case "gauge":
+				this.#gauges.set(name, /* @__PURE__ */ new Map());
+				break;
+			case "summary":
+				this.#summaries.set(name, /* @__PURE__ */ new Map());
+				break;
+		}
+	}
+	/**
+	* Render the current snapshot in Prometheus text exposition
+	* format (v0.0.4). Never throws — incomplete sample buckets are
+	* skipped instead of failing the scrape.
+	*/
+	render() {
+		const lines = [];
+		for (const def of this.#definitions.values()) {
+			lines.push(`# HELP ${def.name} ${escapeHelp(def.help)}`);
+			lines.push(`# TYPE ${def.name} ${def.kind}`);
+			switch (def.kind) {
+				case "counter": {
+					const bucket = this.#counters.get(def.name);
+					if (bucket !== void 0) for (const entry of bucket.values()) lines.push(formatSample(def.name, entry.labels, entry.value));
+					break;
+				}
+				case "gauge": {
+					const bucket = this.#gauges.get(def.name);
+					if (bucket !== void 0) for (const entry of bucket.values()) lines.push(formatSample(def.name, entry.labels, entry.value));
+					break;
+				}
+				case "summary": {
+					const bucket = this.#summaries.get(def.name);
+					if (bucket !== void 0) for (const entry of bucket.values()) {
+						for (const q of SUMMARY_QUANTILES) {
+							const value = computeQuantile(entry.samples, q);
+							if (value === void 0) continue;
+							lines.push(formatSample(def.name, {
+								...entry.labels,
+								quantile: q.toString()
+							}, value));
+						}
+						lines.push(formatSample(`${def.name}_sum`, entry.labels, entry.sum));
+						lines.push(formatSample(`${def.name}_count`, entry.labels, entry.count));
+					}
+					break;
+				}
+			}
+		}
+		return `${lines.join("\n")}\n`;
+	}
+	contentType() {
+		return "text/plain; version=0.0.4; charset=utf-8";
+	}
+	/** Snapshot for tests / assertions. */
+	snapshot() {
+		const counters = {};
+		for (const [name, bucket] of this.#counters) counters[name] = [...bucket.values()].map((entry) => ({
+			labels: entry.labels,
+			value: entry.value
+		}));
+		const gauges = {};
+		for (const [name, bucket] of this.#gauges) gauges[name] = [...bucket.values()].map((entry) => ({
+			labels: entry.labels,
+			value: entry.value
+		}));
+		const summaries = {};
+		for (const [name, bucket] of this.#summaries) summaries[name] = [...bucket.values()].map((entry) => ({
+			labels: entry.labels,
+			count: entry.count,
+			sum: entry.sum,
+			samples: [...entry.samples]
+		}));
+		return {
+			counters,
+			gauges,
+			summaries
+		};
+	}
+	#register(name, help, kind, labelNames) {
+		if (!METRIC_NAME_RE.test(name)) throw new Error(`MetricRegistry: invalid metric name '${name}'`);
+		const existing = this.#definitions.get(name);
+		if (existing !== void 0) {
+			if (existing.kind !== kind) throw new Error(`MetricRegistry: metric '${name}' already registered as '${existing.kind}', cannot redefine as '${kind}'`);
+			return;
+		}
+		this.#definitions.set(name, {
+			name,
+			help,
+			kind,
+			labelNames: Object.freeze([...labelNames])
+		});
+	}
+	#assertKind(name, kind) {
+		const def = this.#definitions.get(name);
+		if (def === void 0) throw new Error(`MetricRegistry: unknown metric '${name}'`);
+		if (def.kind !== kind) throw new Error(`MetricRegistry: metric '${name}' is a ${def.kind}, not a ${kind}`);
+	}
+};
+const METRIC_NAME_RE = /^[a-zA-Z_:][a-zA-Z0-9_:]*$/;
+const LABEL_NAME_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+function assertLabelNames(labels) {
+	for (const key of Object.keys(labels)) if (!LABEL_NAME_RE.test(key)) throw new Error(`MetricRegistry: invalid label name '${key}'`);
+}
+function serializeLabelKey(labels) {
+	const keys = Object.keys(labels).sort();
+	if (keys.length === 0) return "";
+	const parts = [];
+	for (const k of keys) parts.push(`${k}=${String(labels[k])}`);
+	return parts.join("|");
+}
+function formatSample(name, labels, value) {
+	return `${name}${formatLabels(labels)} ${formatNumber(value)}`;
+}
+function formatLabels(labels) {
+	const keys = Object.keys(labels).sort();
+	if (keys.length === 0) return "";
+	const parts = [];
+	for (const k of keys) {
+		if (!LABEL_NAME_RE.test(k)) throw new Error(`MetricRegistry: invalid label name '${k}'`);
+		parts.push(`${k}="${escapeLabelValue(String(labels[k]))}"`);
+	}
+	return `{${parts.join(",")}}`;
+}
+function escapeLabelValue(value) {
+	return value.replace(/\\/g, "\\\\").replace(/\n/g, "\\n").replace(/"/g, "\\\"");
+}
+function escapeHelp(help) {
+	return help.replace(/\\/g, "\\\\").replace(/\n/g, "\\n");
+}
+function formatNumber(value) {
+	if (Number.isNaN(value)) return "NaN";
+	if (!Number.isFinite(value)) return value > 0 ? "+Inf" : "-Inf";
+	if (Number.isInteger(value)) return String(value);
+	return value.toString();
+}
+function computeQuantile(samples, q) {
+	if (samples.length === 0) return void 0;
+	const sorted = [...samples].sort((a, b) => a - b);
+	return sorted[Math.min(sorted.length - 1, Math.max(0, Math.ceil(q * sorted.length) - 1))];
+}
+
+//#endregion
+export { MetricRegistry };
+//# sourceMappingURL=registry.js.map

package/dist/metrics/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","names":["#definitions","#counters","#gauges","#summaries","#register","#assertKind","lines: string[]","counters: Record<string, ReadonlyArray<{ labels: LabelSet; value: number }>>","gauges: Record<string, ReadonlyArray<{ labels: LabelSet; value: number }>>","summaries: Record<\n      string,\n      ReadonlyArray<{\n        labels: LabelSet;\n        count: number;\n        sum: number;\n        samples: ReadonlyArray<number>;\n      }>\n    >","parts: string[]"],"sources":["../../src/metrics/registry.ts"],"sourcesContent":["/**\n * Tiny Prometheus exposition layer. The framework intentionally does\n * not pull in `prom-client` so the bundle stays lean and so the\n * exposition is byte-stable across processes (`prom-client` adds\n * default counters that drift between Node releases).\n *\n * The supported metric kinds are the three the runtime spec calls\n * out: `counter`, `gauge`, and `summary` (with hard-coded p50/p95\n * quantiles). Sample rendering follows Prometheus text exposition\n * format v0.0.4 — every metric block is preceded by `# HELP` + `# TYPE`\n * and labels are quoted-escaped per the spec.\n *\n * @packageDocumentation\n */\n\n/** @stable */\nexport type MetricKind = 'counter' | 'gauge' | 'summary';\n\n/** @stable */\nexport type LabelSet = Readonly<Record<string, string | number | boolean>>;\n\ninterface MetricDefinition {\n  readonly name: string;\n  readonly help: string;\n  readonly kind: MetricKind;\n  readonly labelNames: ReadonlyArray<string>;\n}\n\ninterface CounterEntry {\n  readonly labels: LabelSet;\n  value: number;\n}\n\ninterface GaugeEntry {\n  readonly labels: LabelSet;\n  value: number;\n}\n\ninterface SummaryEntry {\n  readonly labels: LabelSet;\n  count: number;\n  sum: number;\n  /** Recent samples (capped) used to compute quantiles. */\n  samples: number[];\n}\n\nconst SUMMARY_SAMPLE_CAP = 1024;\nconst SUMMARY_QUANTILES = Object.freeze([0.5, 0.95]);\n\n/**\n * Lightweight Prometheus registry. Each instance owns its metric\n * catalogue + per-label samples; `render()` emits the canonical text\n * exposition block.\n *\n * @stable\n */\nexport class MetricRegistry {\n  readonly #definitions = new Map<string, MetricDefinition>();\n  readonly #counters = new Map<string, Map<string, CounterEntry>>();\n  readonly #gauges = new Map<string, Map<string, GaugeEntry>>();\n  readonly #summaries = new Map<string, Map<string, SummaryEntry>>();\n\n  registerCounter(name: string, help: string, labelNames: ReadonlyArray<string> = []): void {\n    this.#register(name, help, 'counter', labelNames);\n    if (!this.#counters.has(name)) this.#counters.set(name, new Map());\n  }\n\n  registerGauge(name: string, help: string, labelNames: ReadonlyArray<string> = []): void {\n    this.#register(name, help, 'gauge', labelNames);\n    if (!this.#gauges.has(name)) this.#gauges.set(name, new Map());\n  }\n\n  registerSummary(name: string, help: string, labelNames: ReadonlyArray<string> = []): void {\n    this.#register(name, help, 'summary', labelNames);\n    if (!this.#summaries.has(name)) this.#summaries.set(name, new Map());\n  }\n\n  inc(name: string, labels: LabelSet = {}, by = 1): void {\n    this.#assertKind(name, 'counter');\n    assertLabelNames(labels);\n    const bucket = this.#counters.get(name);\n    if (bucket === undefined) {\n      throw new Error(`MetricRegistry.inc: counter '${name}' is not registered`);\n    }\n    const key = serializeLabelKey(labels);\n    const entry = bucket.get(key) ?? { labels: { ...labels }, value: 0 };\n    if (!Number.isFinite(by)) {\n      throw new Error(`MetricRegistry.inc(${name}): by must be finite`);\n    }\n    if (by < 0) {\n      throw new Error(`MetricRegistry.inc(${name}): counters never decrement`);\n    }\n    entry.value += by;\n    bucket.set(key, entry);\n  }\n\n  set(name: string, value: number, labels: LabelSet = {}): void {\n    this.#assertKind(name, 'gauge');\n    assertLabelNames(labels);\n    const bucket = this.#gauges.get(name);\n    if (bucket === undefined) {\n      throw new Error(`MetricRegistry.set: gauge '${name}' is not registered`);\n    }\n    const key = serializeLabelKey(labels);\n    bucket.set(key, { labels: { ...labels }, value });\n  }\n\n  observe(name: string, value: number, labels: LabelSet = {}): void {\n    this.#assertKind(name, 'summary');\n    assertLabelNames(labels);\n    const bucket = this.#summaries.get(name);\n    if (bucket === undefined) {\n      throw new Error(`MetricRegistry.observe: summary '${name}' is not registered`);\n    }\n    const key = serializeLabelKey(labels);\n    const entry = bucket.get(key) ?? { labels: { ...labels }, count: 0, sum: 0, samples: [] };\n    entry.count += 1;\n    entry.sum += value;\n    entry.samples.push(value);\n    if (entry.samples.length > SUMMARY_SAMPLE_CAP) {\n      entry.samples.shift();\n    }\n    bucket.set(key, entry);\n  }\n\n  reset(): void {\n    this.#counters.clear();\n    this.#gauges.clear();\n    this.#summaries.clear();\n    for (const [name, def] of this.#definitions) {\n      switch (def.kind) {\n        case 'counter':\n          this.#counters.set(name, new Map());\n          break;\n        case 'gauge':\n          this.#gauges.set(name, new Map());\n          break;\n        case 'summary':\n          this.#summaries.set(name, new Map());\n          break;\n      }\n    }\n  }\n\n  /**\n   * Render the current snapshot in Prometheus text exposition\n   * format (v0.0.4). Never throws — incomplete sample buckets are\n   * skipped instead of failing the scrape.\n   */\n  render(): string {\n    const lines: string[] = [];\n    for (const def of this.#definitions.values()) {\n      lines.push(`# HELP ${def.name} ${escapeHelp(def.help)}`);\n      lines.push(`# TYPE ${def.name} ${def.kind}`);\n      switch (def.kind) {\n        case 'counter': {\n          const bucket = this.#counters.get(def.name);\n          if (bucket !== undefined) {\n            for (const entry of bucket.values()) {\n              lines.push(formatSample(def.name, entry.labels, entry.value));\n            }\n          }\n          break;\n        }\n        case 'gauge': {\n          const bucket = this.#gauges.get(def.name);\n          if (bucket !== undefined) {\n            for (const entry of bucket.values()) {\n              lines.push(formatSample(def.name, entry.labels, entry.value));\n            }\n          }\n          break;\n        }\n        case 'summary': {\n          const bucket = this.#summaries.get(def.name);\n          if (bucket !== undefined) {\n            for (const entry of bucket.values()) {\n              for (const q of SUMMARY_QUANTILES) {\n                const value = computeQuantile(entry.samples, q);\n                if (value === undefined) continue;\n                lines.push(\n                  formatSample(def.name, { ...entry.labels, quantile: q.toString() }, value),\n                );\n              }\n              lines.push(formatSample(`${def.name}_sum`, entry.labels, entry.sum));\n              lines.push(formatSample(`${def.name}_count`, entry.labels, entry.count));\n            }\n          }\n          break;\n        }\n      }\n    }\n    return `${lines.join('\\n')}\\n`;\n  }\n\n  contentType(): string {\n    return 'text/plain; version=0.0.4; charset=utf-8';\n  }\n\n  /** Snapshot for tests / assertions. */\n  snapshot(): {\n    counters: Record<string, ReadonlyArray<{ labels: LabelSet; value: number }>>;\n    gauges: Record<string, ReadonlyArray<{ labels: LabelSet; value: number }>>;\n    summaries: Record<\n      string,\n      ReadonlyArray<{\n        labels: LabelSet;\n        count: number;\n        sum: number;\n        samples: ReadonlyArray<number>;\n      }>\n    >;\n  } {\n    const counters: Record<string, ReadonlyArray<{ labels: LabelSet; value: number }>> = {};\n    for (const [name, bucket] of this.#counters) {\n      counters[name] = [...bucket.values()].map((entry) => ({\n        labels: entry.labels,\n        value: entry.value,\n      }));\n    }\n    const gauges: Record<string, ReadonlyArray<{ labels: LabelSet; value: number }>> = {};\n    for (const [name, bucket] of this.#gauges) {\n      gauges[name] = [...bucket.values()].map((entry) => ({\n        labels: entry.labels,\n        value: entry.value,\n      }));\n    }\n    const summaries: Record<\n      string,\n      ReadonlyArray<{\n        labels: LabelSet;\n        count: number;\n        sum: number;\n        samples: ReadonlyArray<number>;\n      }>\n    > = {};\n    for (const [name, bucket] of this.#summaries) {\n      summaries[name] = [...bucket.values()].map((entry) => ({\n        labels: entry.labels,\n        count: entry.count,\n        sum: entry.sum,\n        samples: [...entry.samples],\n      }));\n    }\n    return { counters, gauges, summaries };\n  }\n\n  #register(name: string, help: string, kind: MetricKind, labelNames: ReadonlyArray<string>): void {\n    if (!METRIC_NAME_RE.test(name)) {\n      throw new Error(`MetricRegistry: invalid metric name '${name}'`);\n    }\n    const existing = this.#definitions.get(name);\n    if (existing !== undefined) {\n      if (existing.kind !== kind) {\n        throw new Error(\n          `MetricRegistry: metric '${name}' already registered as '${existing.kind}', cannot redefine as '${kind}'`,\n        );\n      }\n      return;\n    }\n    this.#definitions.set(name, {\n      name,\n      help,\n      kind,\n      labelNames: Object.freeze([...labelNames]),\n    });\n  }\n\n  #assertKind(name: string, kind: MetricKind): void {\n    const def = this.#definitions.get(name);\n    if (def === undefined) {\n      throw new Error(`MetricRegistry: unknown metric '${name}'`);\n    }\n    if (def.kind !== kind) {\n      throw new Error(`MetricRegistry: metric '${name}' is a ${def.kind}, not a ${kind}`);\n    }\n  }\n}\n\nconst METRIC_NAME_RE = /^[a-zA-Z_:][a-zA-Z0-9_:]*$/;\nconst LABEL_NAME_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;\n\nfunction assertLabelNames(labels: LabelSet): void {\n  for (const key of Object.keys(labels)) {\n    if (!LABEL_NAME_RE.test(key)) {\n      throw new Error(`MetricRegistry: invalid label name '${key}'`);\n    }\n  }\n}\n\nfunction serializeLabelKey(labels: LabelSet): string {\n  const keys = Object.keys(labels).sort();\n  if (keys.length === 0) return '';\n  const parts: string[] = [];\n  for (const k of keys) parts.push(`${k}=${String(labels[k])}`);\n  return parts.join('|');\n}\n\nfunction formatSample(name: string, labels: LabelSet, value: number): string {\n  const labelStr = formatLabels(labels);\n  return `${name}${labelStr} ${formatNumber(value)}`;\n}\n\nfunction formatLabels(labels: LabelSet): string {\n  const keys = Object.keys(labels).sort();\n  if (keys.length === 0) return '';\n  const parts: string[] = [];\n  for (const k of keys) {\n    if (!LABEL_NAME_RE.test(k)) {\n      throw new Error(`MetricRegistry: invalid label name '${k}'`);\n    }\n    parts.push(`${k}=\"${escapeLabelValue(String(labels[k]))}\"`);\n  }\n  return `{${parts.join(',')}}`;\n}\n\nfunction escapeLabelValue(value: string): string {\n  return value.replace(/\\\\/g, '\\\\\\\\').replace(/\\n/g, '\\\\n').replace(/\"/g, '\\\\\"');\n}\n\nfunction escapeHelp(help: string): string {\n  return help.replace(/\\\\/g, '\\\\\\\\').replace(/\\n/g, '\\\\n');\n}\n\nfunction formatNumber(value: number): string {\n  if (Number.isNaN(value)) return 'NaN';\n  if (!Number.isFinite(value)) return value > 0 ? '+Inf' : '-Inf';\n  if (Number.isInteger(value)) return String(value);\n  return value.toString();\n}\n\nfunction computeQuantile(samples: ReadonlyArray<number>, q: number): number | undefined {\n  if (samples.length === 0) return undefined;\n  const sorted = [...samples].sort((a, b) => a - b);\n  const idx = Math.min(sorted.length - 1, Math.max(0, Math.ceil(q * sorted.length) - 1));\n  return sorted[idx];\n}\n"],"mappings":"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"}

package/dist/middleware/audit.d.ts

@@ -0,0 +1,47 @@
+import { ServerVariables } from "../internal/context.js";
+import { AuditDb, AuditEntryInput } from "@graphorin/security/audit";
+import { MiddlewareHandler } from "hono";
+
+//#region src/middleware/audit.d.ts
+
+/**
+ * Canonical action discriminator emitted on every authenticated REST
+ * request per the Phase 14a spec (`§ Audit middleware`). Exposed as
+ * a constant so consumers (downstream filters, dashboards) can grep
+ * for it without restating the literal everywhere.
+ *
+ * @stable
+ */
+declare const HTTP_REQUEST_AUDIT_ACTION: "http:request";
+/**
+ * Optional telemetry sink. The default ignores errors; production
+ * deployments wire this into their structured logger.
+ *
+ * @stable
+ */
+type AuditErrorSink = (err: unknown, entry: Omit<AuditEntryInput, 'ts'>) => void;
+/**
+ * @stable
+ */
+interface AuditMiddlewareOptions {
+  readonly auditDb: AuditDb;
+  /** Optional override for the time source. */
+  readonly now?: () => number;
+  /** Optional error sink. Defaults to swallow. */
+  readonly onError?: AuditErrorSink;
+  /**
+   * When `true` (the default), include the path + method + status on
+   * the audit entry's metadata. Disable for compliance-strict
+   * deployments that already log the request envelope elsewhere.
+   */
+  readonly recordMetadata?: boolean;
+}
+/**
+ * @stable
+ */
+declare function createAuditMiddleware(options: AuditMiddlewareOptions): MiddlewareHandler<{
+  Variables: ServerVariables;
+}>;
+//#endregion
+export { AuditErrorSink, AuditMiddlewareOptions, HTTP_REQUEST_AUDIT_ACTION, createAuditMiddleware };
+//# sourceMappingURL=audit.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","names":[],"sources":["../../src/middleware/audit.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;cA4Ba;;;;;;;KAQD,cAAA,yBAAuC,KAAK;;;;UAKvC,sBAAA;oBACG;;;;qBAIC;;;;;;;;;;;iBAmBL,qBAAA,UACL,yBACR;aAA+B"}

package/dist/middleware/audit.js

@@ -0,0 +1,71 @@
+import { appendAudit } from "@graphorin/security/audit";
+
+//#region src/middleware/audit.ts
+/**
+* Audit middleware. Forwards every authenticated request through
+* `appendAudit` (`@graphorin/security/audit`) so the operator gets a
+* tamper-evident chain of every state-changing call. Append failures
+* never break the request hot path; they are recorded on a best-
+* effort error sink.
+*
+* @packageDocumentation
+*/
+/**
+* Canonical action discriminator emitted on every authenticated REST
+* request per the Phase 14a spec (`§ Audit middleware`). Exposed as
+* a constant so consumers (downstream filters, dashboards) can grep
+* for it without restating the literal everywhere.
+*
+* @stable
+*/
+const HTTP_REQUEST_AUDIT_ACTION = "http:request";
+function decisionForStatus(status) {
+	if (status >= 500) return "error";
+	if (status === 404) return "not-found";
+	if (status >= 400) return "denied";
+	return "success";
+}
+/**
+* @stable
+*/
+function createAuditMiddleware(options) {
+	const now = options.now ?? Date.now;
+	const onError = options.onError ?? (() => {});
+	const recordMetadata = options.recordMetadata ?? true;
+	return async (c, next) => {
+		const start = now();
+		await next();
+		const status = c.res?.status ?? 0;
+		const auth = c.get("state").auth;
+		if (auth.kind !== "token") return;
+		const token = auth.token;
+		const entry = {
+			ts: now(),
+			actor: {
+				kind: "token",
+				id: token.tokenId,
+				...token.label !== void 0 ? { label: token.label } : {}
+			},
+			action: HTTP_REQUEST_AUDIT_ACTION,
+			target: c.req.path,
+			decision: decisionForStatus(status),
+			...recordMetadata ? { metadata: {
+				method: c.req.method,
+				status,
+				durationMs: now() - start,
+				requestId: c.get("state").requestId,
+				...c.get("state").idempotencyKey !== void 0 ? { idempotencyKey: c.get("state").idempotencyKey } : {},
+				...c.get("state").idempotencyReplay === true ? { idempotencyReplayed: true } : {}
+			} } : {}
+		};
+		try {
+			await appendAudit(options.auditDb, entry);
+		} catch (err) {
+			onError(err, entry);
+		}
+	};
+}
+
+//#endregion
+export { HTTP_REQUEST_AUDIT_ACTION, createAuditMiddleware };
+//# sourceMappingURL=audit.js.map

package/dist/middleware/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","names":["entry: AuditEntryInput"],"sources":["../../src/middleware/audit.ts"],"sourcesContent":["/**\n * Audit middleware. Forwards every authenticated request through\n * `appendAudit` (`@graphorin/security/audit`) so the operator gets a\n * tamper-evident chain of every state-changing call. Append failures\n * never break the request hot path; they are recorded on a best-\n * effort error sink.\n *\n * @packageDocumentation\n */\n\nimport {\n  type AuditDb,\n  type AuditDecision,\n  type AuditEntryInput,\n  appendAudit,\n} from '@graphorin/security/audit';\nimport type { MiddlewareHandler } from 'hono';\n\nimport type { ServerVariables } from '../internal/context.js';\n\n/**\n * Canonical action discriminator emitted on every authenticated REST\n * request per the Phase 14a spec (`§ Audit middleware`). Exposed as\n * a constant so consumers (downstream filters, dashboards) can grep\n * for it without restating the literal everywhere.\n *\n * @stable\n */\nexport const HTTP_REQUEST_AUDIT_ACTION = 'http:request' as const;\n\n/**\n * Optional telemetry sink. The default ignores errors; production\n * deployments wire this into their structured logger.\n *\n * @stable\n */\nexport type AuditErrorSink = (err: unknown, entry: Omit<AuditEntryInput, 'ts'>) => void;\n\n/**\n * @stable\n */\nexport interface AuditMiddlewareOptions {\n  readonly auditDb: AuditDb;\n  /** Optional override for the time source. */\n  readonly now?: () => number;\n  /** Optional error sink. Defaults to swallow. */\n  readonly onError?: AuditErrorSink;\n  /**\n   * When `true` (the default), include the path + method + status on\n   * the audit entry's metadata. Disable for compliance-strict\n   * deployments that already log the request envelope elsewhere.\n   */\n  readonly recordMetadata?: boolean;\n}\n\nfunction decisionForStatus(status: number): AuditDecision {\n  if (status >= 500) return 'error';\n  if (status === 404) return 'not-found';\n  if (status >= 400) return 'denied';\n  return 'success';\n}\n\n/**\n * @stable\n */\nexport function createAuditMiddleware(\n  options: AuditMiddlewareOptions,\n): MiddlewareHandler<{ Variables: ServerVariables }> {\n  const now = options.now ?? Date.now;\n  const onError = options.onError ?? (() => {});\n  const recordMetadata = options.recordMetadata ?? true;\n\n  return async (c, next) => {\n    const start = now();\n    await next();\n    const status = c.res?.status ?? 0;\n    const auth = c.get('state').auth;\n    if (auth.kind !== 'token') {\n      // Anonymous calls (health, etc.) are not audited.\n      return;\n    }\n    const token = auth.token;\n    const entry: AuditEntryInput = {\n      ts: now(),\n      actor: {\n        kind: 'token',\n        id: token.tokenId,\n        ...(token.label !== undefined ? { label: token.label } : {}),\n      },\n      action: HTTP_REQUEST_AUDIT_ACTION,\n      target: c.req.path,\n      decision: decisionForStatus(status),\n      ...(recordMetadata\n        ? {\n            metadata: {\n              method: c.req.method,\n              status,\n              durationMs: now() - start,\n              requestId: c.get('state').requestId,\n              ...(c.get('state').idempotencyKey !== undefined\n                ? { idempotencyKey: c.get('state').idempotencyKey }\n                : {}),\n              ...(c.get('state').idempotencyReplay === true ? { idempotencyReplayed: true } : {}),\n            },\n          }\n        : {}),\n    };\n    try {\n      await appendAudit(options.auditDb, entry);\n    } catch (err) {\n      onError(err, entry);\n    }\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AA4BA,MAAa,4BAA4B;AA2BzC,SAAS,kBAAkB,QAA+B;AACxD,KAAI,UAAU,IAAK,QAAO;AAC1B,KAAI,WAAW,IAAK,QAAO;AAC3B,KAAI,UAAU,IAAK,QAAO;AAC1B,QAAO;;;;;AAMT,SAAgB,sBACd,SACmD;CACnD,MAAM,MAAM,QAAQ,OAAO,KAAK;CAChC,MAAM,UAAU,QAAQ,kBAAkB;CAC1C,MAAM,iBAAiB,QAAQ,kBAAkB;AAEjD,QAAO,OAAO,GAAG,SAAS;EACxB,MAAM,QAAQ,KAAK;AACnB,QAAM,MAAM;EACZ,MAAM,SAAS,EAAE,KAAK,UAAU;EAChC,MAAM,OAAO,EAAE,IAAI,QAAQ,CAAC;AAC5B,MAAI,KAAK,SAAS,QAEhB;EAEF,MAAM,QAAQ,KAAK;EACnB,MAAMA,QAAyB;GAC7B,IAAI,KAAK;GACT,OAAO;IACL,MAAM;IACN,IAAI,MAAM;IACV,GAAI,MAAM,UAAU,SAAY,EAAE,OAAO,MAAM,OAAO,GAAG,EAAE;IAC5D;GACD,QAAQ;GACR,QAAQ,EAAE,IAAI;GACd,UAAU,kBAAkB,OAAO;GACnC,GAAI,iBACA,EACE,UAAU;IACR,QAAQ,EAAE,IAAI;IACd;IACA,YAAY,KAAK,GAAG;IACpB,WAAW,EAAE,IAAI,QAAQ,CAAC;IAC1B,GAAI,EAAE,IAAI,QAAQ,CAAC,mBAAmB,SAClC,EAAE,gBAAgB,EAAE,IAAI,QAAQ,CAAC,gBAAgB,GACjD,EAAE;IACN,GAAI,EAAE,IAAI,QAAQ,CAAC,sBAAsB,OAAO,EAAE,qBAAqB,MAAM,GAAG,EAAE;IACnF,EACF,GACD,EAAE;GACP;AACD,MAAI;AACF,SAAM,YAAY,QAAQ,SAAS,MAAM;WAClC,KAAK;AACZ,WAAQ,KAAK,MAAM"}

package/dist/middleware/auth.d.ts

@@ -0,0 +1,50 @@
+import { ServerVariables } from "../internal/context.js";
+import { MiddlewareHandler } from "hono";
+import { TokenVerifier } from "@graphorin/security/auth";
+
+//#region src/middleware/auth.d.ts
+
+/**
+ * Build the no-auth middleware mounted when `auth.kind = 'none'`. It stamps
+ * `state.auth = { kind: 'anonymous', grantedScopes: [admin:*] }` so the
+ * scope middleware, SSE handler and replay routes all treat the request as a
+ * fully-authorized principal. This is the documented trusted-loopback /
+ * single-operator mode — never mount it on a non-loopback deployment without
+ * understanding that every endpoint becomes open.
+ *
+ * @stable
+ */
+declare function createAnonymousAuthMiddleware(): MiddlewareHandler<{
+  Variables: ServerVariables;
+}>;
+/**
+ * Options accepted by {@link createAuthMiddleware}. Tests inject a
+ * stub verifier; production wiring uses the verifier built during the
+ * server's pre-bind step.
+ *
+ * @stable
+ */
+interface AuthMiddlewareOptions {
+  readonly verifier: TokenVerifier;
+  /**
+   * Whether to allow unauthenticated requests through. Used by
+   * `health` and (when explicitly opted-in) by the public read
+   * endpoints. When `false` (the default), missing / malformed /
+   * invalid tokens short-circuit the request with `401`.
+   */
+  readonly allowAnonymous?: boolean;
+}
+/**
+ * Build the bearer-token middleware. The middleware always sets
+ * `c.var.state.auth`, even on the unauthenticated branch, so
+ * downstream code can pattern-match the discriminated union without
+ * a separate "is anonymous?" check.
+ *
+ * @stable
+ */
+declare function createAuthMiddleware(options: AuthMiddlewareOptions): MiddlewareHandler<{
+  Variables: ServerVariables;
+}>;
+//#endregion
+export { AuthMiddlewareOptions, createAnonymousAuthMiddleware, createAuthMiddleware };
+//# sourceMappingURL=auth.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","names":[],"sources":["../../src/middleware/auth.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;;iBAqCgB,6BAAA,CAAA,GAAiC;aACpC;;;;;;;;;UAkBI,qBAAA;qBACI;;;;;;;;;;;;;;;;;iBAwEL,oBAAA,UACL,wBACR;aAA+B"}

package/dist/middleware/auth.js

@@ -0,0 +1,164 @@
+import { parseScope } from "@graphorin/security/auth";
+
+//#region src/middleware/auth.ts
+/**
+* Bearer-token authentication middleware. Wraps the
+* `@graphorin/security` token verifier so handlers see
+* a stable {@link import('../internal/context.js').AuthState}
+* structure on `c.var.state.auth`.
+*
+* @packageDocumentation
+*/
+/**
+* IP-13: the scope set granted to every request when `auth.kind = 'none'`.
+* `admin:*` matches every required scope (see `@graphorin/security/auth`
+* `scopeMatches`), so the trusted-loopback operator is uniformly authorized
+* without special-casing each route.
+*/
+const ANONYMOUS_GRANTED_SCOPES = Object.freeze([parseScope("admin:*")]);
+/**
+* Build the no-auth middleware mounted when `auth.kind = 'none'`. It stamps
+* `state.auth = { kind: 'anonymous', grantedScopes: [admin:*] }` so the
+* scope middleware, SSE handler and replay routes all treat the request as a
+* fully-authorized principal. This is the documented trusted-loopback /
+* single-operator mode — never mount it on a non-loopback deployment without
+* understanding that every endpoint becomes open.
+*
+* @stable
+*/
+function createAnonymousAuthMiddleware() {
+	return async (c, next) => {
+		c.set("state", {
+			...c.get("state"),
+			auth: {
+				kind: "anonymous",
+				grantedScopes: ANONYMOUS_GRANTED_SCOPES
+			}
+		});
+		await next();
+	};
+}
+const HEADER_NAME = "authorization";
+const BEARER_PREFIX = "bearer ";
+function extractBearer(c) {
+	const raw = c.req.header(HEADER_NAME);
+	if (raw === void 0 || raw === null) return void 0;
+	const trimmed = raw.trim();
+	if (trimmed.length < 7) return void 0;
+	if (trimmed.slice(0, 7).toLowerCase() !== BEARER_PREFIX) return void 0;
+	return trimmed.slice(7).trim();
+}
+function reasonToStatus(reason) {
+	switch (reason) {
+		case "malformed": return {
+			status: 401,
+			body: {
+				error: "auth-invalid",
+				message: "Malformed bearer token."
+			}
+		};
+		case "unknown-token": return {
+			status: 401,
+			body: {
+				error: "auth-invalid",
+				message: "Unknown bearer token."
+			}
+		};
+		case "revoked": return {
+			status: 401,
+			body: {
+				error: "auth-revoked",
+				message: "Bearer token has been revoked."
+			}
+		};
+		case "expired": return {
+			status: 401,
+			body: {
+				error: "auth-expired",
+				message: "Bearer token has expired."
+			}
+		};
+		case "ip-locked-out": return {
+			status: 429,
+			body: {
+				error: "auth-locked-out",
+				message: "Too many failed authentications from this address.",
+				hint: "Wait for the lockout window to elapse before retrying."
+			}
+		};
+		case "token-locked-out": return {
+			status: 429,
+			body: {
+				error: "auth-locked-out",
+				message: "Bearer token is locked out after repeated failures.",
+				hint: "Operator must rotate the token."
+			}
+		};
+		default: return {
+			status: 401,
+			body: {
+				error: "auth-invalid",
+				message: `Authentication failed: ${reason}.`
+			}
+		};
+	}
+}
+/**
+* Build the bearer-token middleware. The middleware always sets
+* `c.var.state.auth`, even on the unauthenticated branch, so
+* downstream code can pattern-match the discriminated union without
+* a separate "is anonymous?" check.
+*
+* @stable
+*/
+function createAuthMiddleware(options) {
+	const allowAnonymous = options.allowAnonymous ?? false;
+	return async (c, next) => {
+		const token = extractBearer(c);
+		const ip = c.get("state").clientIp;
+		if (token === void 0) {
+			if (allowAnonymous) {
+				c.set("state", {
+					...c.get("state"),
+					auth: { kind: "unauthenticated" }
+				});
+				await next();
+				return;
+			}
+			return c.json({
+				error: "auth-required",
+				message: "Bearer token required.",
+				hint: "Set 'Authorization: Bearer <token>'."
+			}, 401);
+		}
+		const result = await options.verifier.verify(token, ip !== void 0 ? { ip } : {});
+		if (!result.ok) {
+			const mapped = reasonToStatus(result.reason);
+			const headers = {};
+			if (result.retryAfterMs !== void 0) headers["Retry-After"] = Math.ceil(result.retryAfterMs / 1e3).toString();
+			return c.json(mapped.body, mapped.status, headers);
+		}
+		const grantedScopes = [];
+		for (const scope of result.token.scopes) grantedScopes.push(scope);
+		c.set("state", {
+			...c.get("state"),
+			auth: {
+				kind: "token",
+				token: result.token,
+				grantedScopes: Object.freeze(grantedScopes)
+			}
+		});
+		c.set("token", {
+			id: result.token.tokenId,
+			label: result.token.label,
+			scopes: Object.freeze(grantedScopes.slice()),
+			env: result.token.env,
+			expiresAt: result.token.expiresAt
+		});
+		await next();
+	};
+}
+
+//#endregion
+export { createAnonymousAuthMiddleware, createAuthMiddleware };
+//# sourceMappingURL=auth.js.map

package/dist/middleware/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","names":["ANONYMOUS_GRANTED_SCOPES: ReadonlyArray<ParsedScope>","headers: Record<string, string>","grantedScopes: ParsedScope[]"],"sources":["../../src/middleware/auth.ts"],"sourcesContent":["/**\n * Bearer-token authentication middleware. Wraps the\n * `@graphorin/security` token verifier so handlers see\n * a stable {@link import('../internal/context.js').AuthState}\n * structure on `c.var.state.auth`.\n *\n * @packageDocumentation\n */\n\nimport {\n  type ParsedScope,\n  parseScope,\n  type TokenVerifier,\n  tryParseScope,\n} from '@graphorin/security/auth';\nimport type { Context, MiddlewareHandler, Next } from 'hono';\n\nimport type { ServerVariables } from '../internal/context.js';\n\n/**\n * IP-13: the scope set granted to every request when `auth.kind = 'none'`.\n * `admin:*` matches every required scope (see `@graphorin/security/auth`\n * `scopeMatches`), so the trusted-loopback operator is uniformly authorized\n * without special-casing each route.\n */\nconst ANONYMOUS_GRANTED_SCOPES: ReadonlyArray<ParsedScope> = Object.freeze([parseScope('admin:*')]);\n\n/**\n * Build the no-auth middleware mounted when `auth.kind = 'none'`. It stamps\n * `state.auth = { kind: 'anonymous', grantedScopes: [admin:*] }` so the\n * scope middleware, SSE handler and replay routes all treat the request as a\n * fully-authorized principal. This is the documented trusted-loopback /\n * single-operator mode — never mount it on a non-loopback deployment without\n * understanding that every endpoint becomes open.\n *\n * @stable\n */\nexport function createAnonymousAuthMiddleware(): MiddlewareHandler<{\n  Variables: ServerVariables;\n}> {\n  return async (c, next: Next) => {\n    c.set('state', {\n      ...c.get('state'),\n      auth: { kind: 'anonymous' as const, grantedScopes: ANONYMOUS_GRANTED_SCOPES },\n    });\n    await next();\n  };\n}\n\n/**\n * Options accepted by {@link createAuthMiddleware}. Tests inject a\n * stub verifier; production wiring uses the verifier built during the\n * server's pre-bind step.\n *\n * @stable\n */\nexport interface AuthMiddlewareOptions {\n  readonly verifier: TokenVerifier;\n  /**\n   * Whether to allow unauthenticated requests through. Used by\n   * `health` and (when explicitly opted-in) by the public read\n   * endpoints. When `false` (the default), missing / malformed /\n   * invalid tokens short-circuit the request with `401`.\n   */\n  readonly allowAnonymous?: boolean;\n}\n\nconst HEADER_NAME = 'authorization';\nconst BEARER_PREFIX = 'bearer ';\n\nfunction extractBearer(c: Context): string | undefined {\n  const raw = c.req.header(HEADER_NAME);\n  if (raw === undefined || raw === null) return undefined;\n  const trimmed = raw.trim();\n  if (trimmed.length < BEARER_PREFIX.length) return undefined;\n  if (trimmed.slice(0, BEARER_PREFIX.length).toLowerCase() !== BEARER_PREFIX) return undefined;\n  return trimmed.slice(BEARER_PREFIX.length).trim();\n}\n\nfunction reasonToStatus(reason: string): {\n  status: number;\n  body: { error: string; message: string; hint?: string };\n} {\n  switch (reason) {\n    case 'malformed':\n      return { status: 401, body: { error: 'auth-invalid', message: 'Malformed bearer token.' } };\n    case 'unknown-token':\n      return { status: 401, body: { error: 'auth-invalid', message: 'Unknown bearer token.' } };\n    case 'revoked':\n      return {\n        status: 401,\n        body: { error: 'auth-revoked', message: 'Bearer token has been revoked.' },\n      };\n    case 'expired':\n      return { status: 401, body: { error: 'auth-expired', message: 'Bearer token has expired.' } };\n    case 'ip-locked-out':\n      return {\n        status: 429,\n        body: {\n          error: 'auth-locked-out',\n          message: 'Too many failed authentications from this address.',\n          hint: 'Wait for the lockout window to elapse before retrying.',\n        },\n      };\n    case 'token-locked-out':\n      return {\n        status: 429,\n        body: {\n          error: 'auth-locked-out',\n          message: 'Bearer token is locked out after repeated failures.',\n          hint: 'Operator must rotate the token.',\n        },\n      };\n    default:\n      return {\n        status: 401,\n        body: { error: 'auth-invalid', message: `Authentication failed: ${reason}.` },\n      };\n  }\n}\n\n/**\n * Build the bearer-token middleware. The middleware always sets\n * `c.var.state.auth`, even on the unauthenticated branch, so\n * downstream code can pattern-match the discriminated union without\n * a separate \"is anonymous?\" check.\n *\n * @stable\n */\nexport function createAuthMiddleware(\n  options: AuthMiddlewareOptions,\n): MiddlewareHandler<{ Variables: ServerVariables }> {\n  const allowAnonymous = options.allowAnonymous ?? false;\n  return async (c, next: Next) => {\n    const token = extractBearer(c);\n    // IP-11: the request-state middleware is the ONLY IP authority —\n    // it resolves the client IP per the configured trustProxy policy\n    // (proxy headers when trusted, else the socket address). The old\n    // fallback read attacker-controlled X-Real-IP unconditionally,\n    // letting header rotation evade per-IP lockout and a spoofed\n    // victim IP trigger a lockout against them.\n    const ip = c.get('state').clientIp;\n    if (token === undefined) {\n      if (allowAnonymous) {\n        c.set('state', { ...c.get('state'), auth: { kind: 'unauthenticated' as const } });\n        await next();\n        return;\n      }\n      return c.json(\n        {\n          error: 'auth-required',\n          message: 'Bearer token required.',\n          hint: \"Set 'Authorization: Bearer <token>'.\",\n        },\n        401,\n      );\n    }\n    const result = await options.verifier.verify(token, ip !== undefined ? { ip } : {});\n    if (!result.ok) {\n      const mapped = reasonToStatus(result.reason);\n      const headers: Record<string, string> = {};\n      if (result.retryAfterMs !== undefined) {\n        headers['Retry-After'] = Math.ceil(result.retryAfterMs / 1000).toString();\n      }\n      return c.json(mapped.body, mapped.status as 401 | 429, headers);\n    }\n    const grantedScopes: ParsedScope[] = [];\n    for (const scope of result.token.scopes) {\n      grantedScopes.push(scope);\n    }\n    // Defensive: any string scopes coming from the store also parse here\n    // even though the verifier itself parses them — see scope.ts.\n    void tryParseScope;\n    c.set('state', {\n      ...c.get('state'),\n      auth: {\n        kind: 'token' as const,\n        token: result.token,\n        grantedScopes: Object.freeze(grantedScopes),\n      },\n    });\n    // Mirror the verified token onto the documented `c.var.token`\n    // slot so route handlers can read it without unwrapping the auth\n    // discriminator. The shape is the one called out in the Phase\n    // 14a spec: { id, label, scopes, env, expiresAt? }.\n    c.set('token', {\n      id: result.token.tokenId,\n      label: result.token.label,\n      scopes: Object.freeze(grantedScopes.slice()),\n      env: result.token.env,\n      expiresAt: result.token.expiresAt,\n    });\n    await next();\n  };\n}\n"],"mappings":"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"}

package/dist/middleware/cors.d.ts

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

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

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