@nifrajs/core 1.9.0 → 1.10.0

package/src/classification.ts

@@ -0,0 +1,44 @@
+/**
+ * Response data-classification tags. A route can declare the highest sensitivity its response body
+ * carries (`schema.classification`). This is a declarative, compile-time + introspection fact — never
+ * read on the request hot path and never enforced at runtime here. Downstream consumers use it: a
+ * partner-API surface refuses to expose a route whose response is `pii`/`secret`, privacy tooling
+ * learns which routes emit regulated data, and the capability lockfile records it so a route that
+ * *starts* returning PII flips the lockfile and forces a review.
+ */
+
+/** Sensitivity of the data a response carries. Ordered `public` < `pii` < `secret`. */
+export type DataClassification = "public" | "pii" | "secret"
+
+/** Total order over classifications; higher = more sensitive. */
+export const DATA_CLASSIFICATION_RANK: Readonly<Record<DataClassification, number>> = Object.freeze(
+  {
+    public: 0,
+    pii: 1,
+    secret: 2,
+  },
+)
+
+const CLASSIFICATIONS = Object.keys(DATA_CLASSIFICATION_RANK) as readonly DataClassification[]
+
+/** Whether `value` is a known classification token. */
+export function isDataClassification(value: unknown): value is DataClassification {
+  return typeof value === "string" && (CLASSIFICATIONS as readonly string[]).includes(value)
+}
+
+/** The most sensitive classification among the inputs; `"public"` when none are given. */
+export function maxClassification(values: Iterable<DataClassification>): DataClassification {
+  let max: DataClassification = "public"
+  for (const value of values) {
+    if (DATA_CLASSIFICATION_RANK[value] > DATA_CLASSIFICATION_RANK[max]) max = value
+  }
+  return max
+}
+
+/** True when `value` is at least as sensitive as `floor` (e.g. `classificationAtLeast(x, "pii")`). */
+export function classificationAtLeast(
+  value: DataClassification,
+  floor: DataClassification,
+): boolean {
+  return DATA_CLASSIFICATION_RANK[value] >= DATA_CLASSIFICATION_RANK[floor]
+}

package/src/errors.ts

@@ -24,6 +24,7 @@ export type RouteConfigErrorCode =
   | "INVALID_PARAM_NAME"
   | "WILDCARD_NOT_LAST"
   | "INVALID_METHOD"
+  | "INVALID_ASSURANCE"
 
 /**
  * Thrown at route registration when a route is misconfigured. This is the

package/src/idempotency.ts

@@ -0,0 +1,205 @@
+/**
+ * Idempotency primitive. A mutating route can declare `schema.idempotency`; the server then dedupes
+ * on an `Idempotency-Key` header: the first request runs and its response is stored, and a retry with
+ * the same key replays the stored response byte-for-byte without re-running the handler. A retry that
+ * reuses a key with a *different* request body is rejected (409) — a key binds to one request.
+ *
+ * This module is the runtime-neutral core: the store interface, an in-memory store, the request
+ * fingerprint, and response (de)serialization. The server owns the request-path lane that reads the
+ * body, consults the store, and captures the response. All logic here is pure/injectable so it is
+ * unit-tested without a server. A durable store (cross-restart) implements the same interface.
+ */
+
+/** Whether a route's idempotency is satisfied by an in-process store or a durable (cross-restart) one. */
+export type IdempotencyScope = "request" | "durable"
+
+/** Default retention for a stored idempotent response: 24 hours. */
+export const DEFAULT_IDEMPOTENCY_TTL_MS = 86_400_000
+
+/** Canonical request header carrying the client-chosen idempotency key. */
+export const DEFAULT_IDEMPOTENCY_HEADER = "idempotency-key"
+
+/** Header stamped on a replayed response so clients/proxies can tell a replay from a fresh run. */
+export const IDEMPOTENT_REPLAY_HEADER = "x-nifra-idempotent-replay"
+
+const KEY_MAX_LENGTH = 255
+
+/** A serialized response held by a store. `body` is base64 so binary payloads round-trip intact. */
+export interface StoredResponse {
+  readonly status: number
+  readonly headers: readonly (readonly [string, string])[]
+  /** Base64-encoded response body; `""` when the response had no body. */
+  readonly body: string
+}
+
+/**
+ * Outcome of reserving a key. `new` → the caller runs the handler and later calls {@link
+ * IdempotencyStore.complete}. `replay` → return the stored response, handler never runs. `mismatch`
+ * → same key, different request fingerprint (client bug) → 409. `in-flight` → the key is reserved but
+ * not yet completed (a concurrent duplicate) → 409 + Retry-After.
+ */
+export type IdempotencyBeginResult =
+  | { readonly state: "new" }
+  | { readonly state: "replay"; readonly response: StoredResponse }
+  | { readonly state: "mismatch" }
+  | { readonly state: "in-flight" }
+
+/**
+ * Storage seam for idempotent responses. `begin` MUST be atomic: for one key, exactly one concurrent
+ * caller sees `new`; the rest see `in-flight` (or `replay` once completed). The in-memory store gets
+ * this free from the single-threaded event loop; a durable store uses an atomic insert.
+ */
+export interface IdempotencyStore {
+  /** Reserve `key` for `fingerprint`, retaining any stored response for `ttlMs`. */
+  begin(
+    key: string,
+    fingerprint: string,
+    ttlMs: number,
+  ): IdempotencyBeginResult | Promise<IdempotencyBeginResult>
+  /** Persist the final response for a reserved key so later retries replay it. */
+  complete(key: string, response: StoredResponse): void | Promise<void>
+  /** Release a reservation that produced no cacheable response, so the client may retry. */
+  abandon(key: string): void | Promise<void>
+}
+
+/** A key must be a non-empty, bounded, control-char-free token. Fail closed on anything else. */
+export function validIdempotencyKey(key: string): boolean {
+  if (typeof key !== "string" || key.length === 0 || key.length > KEY_MAX_LENGTH) return false
+  for (let i = 0; i < key.length; i++) {
+    const code = key.charCodeAt(i)
+    if (code <= 31 || code === 127) return false
+  }
+  return true
+}
+
+const encoder = new TextEncoder()
+
+/**
+ * SHA-256 fingerprint binding a key to one request: method, path (+ query), and the raw body bytes.
+ * A collision-resistant hash matters — a weak hash would let a crafted body replay another's response.
+ */
+export async function computeIdempotencyFingerprint(
+  method: string,
+  path: string,
+  body: Uint8Array,
+): Promise<string> {
+  const head = encoder.encode(`${method.toUpperCase()}\n${path}\n`)
+  const material = new Uint8Array(head.length + body.length)
+  material.set(head, 0)
+  material.set(body, head.length)
+  const digest = await crypto.subtle.digest("SHA-256", material)
+  const bytes = new Uint8Array(digest)
+  let hex = ""
+  for (let i = 0; i < bytes.length; i++) hex += (bytes[i] as number).toString(16).padStart(2, "0")
+  return hex
+}
+
+const BASE64_CHUNK = 0x8000
+
+function bytesToBase64(bytes: Uint8Array): string {
+  let binary = ""
+  for (let i = 0; i < bytes.length; i += BASE64_CHUNK) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + BASE64_CHUNK))
+  }
+  return btoa(binary)
+}
+
+function base64ToBytes(value: string): Uint8Array {
+  const binary = atob(value)
+  const bytes = new Uint8Array(binary.length)
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i)
+  return bytes
+}
+
+/** Buffer a response into a storable form. Clones first so the live response body stays intact. */
+export async function serializeResponse(response: Response): Promise<StoredResponse> {
+  const bytes = new Uint8Array(await response.clone().arrayBuffer())
+  return {
+    status: response.status,
+    headers: [...response.headers] as readonly (readonly [string, string])[],
+    body: bytes.length > 0 ? bytesToBase64(bytes) : "",
+  }
+}
+
+/** Rebuild a live response from storage, stamping the replay marker header. */
+export function responseFromStored(stored: StoredResponse): Response {
+  const headers = new Headers(stored.headers as [string, string][])
+  headers.set(IDEMPOTENT_REPLAY_HEADER, "1")
+  // Reference the Response body type structurally: `BodyInit` isn't a named type under every lib config,
+  // but a fresh `Uint8Array` is a valid body — the cast bridges the `ArrayBufferLike` generic variance.
+  const body = (stored.body === "" ? null : base64ToBytes(stored.body)) as ConstructorParameters<
+    typeof Response
+  >[0]
+  return new Response(body, { status: stored.status, headers })
+}
+
+interface MemoryEntry {
+  readonly fingerprint: string
+  readonly expiresAt: number
+  response: StoredResponse | undefined
+}
+
+export interface MemoryIdempotencyStoreOptions {
+  /** Injectable clock (epoch ms) for deterministic TTL tests. Default `Date.now`. */
+  readonly now?: () => number
+}
+
+/**
+ * In-process idempotency store. Reservation is atomic by construction — `begin` never awaits, so the
+ * single-threaded event loop serializes concurrent callers for one key. Expired entries are treated
+ * as absent (lazy eviction on access); a periodic {@link MemoryIdempotencyStore.sweep} bounds memory.
+ */
+export class MemoryIdempotencyStore implements IdempotencyStore {
+  private readonly entries = new Map<string, MemoryEntry>()
+  private readonly now: () => number
+
+  constructor(options: MemoryIdempotencyStoreOptions = {}) {
+    this.now = options.now ?? Date.now
+  }
+
+  begin(key: string, fingerprint: string, ttlMs: number): IdempotencyBeginResult {
+    const existing = this.entries.get(key)
+    if (existing !== undefined && existing.expiresAt > this.now()) {
+      if (existing.fingerprint !== fingerprint) return { state: "mismatch" }
+      if (existing.response !== undefined) return { state: "replay", response: existing.response }
+      return { state: "in-flight" }
+    }
+    this.entries.set(key, {
+      fingerprint,
+      expiresAt: this.now() + ttlMs,
+      response: undefined,
+    })
+    return { state: "new" }
+  }
+
+  complete(key: string, response: StoredResponse): void {
+    const entry = this.entries.get(key)
+    if (entry !== undefined) entry.response = response
+  }
+
+  abandon(key: string): void {
+    const entry = this.entries.get(key)
+    // Only drop a still-pending reservation; never evict a completed (replayable) response.
+    if (entry !== undefined && entry.response === undefined) this.entries.delete(key)
+  }
+
+  /** Evict expired entries. Callers may run this on an interval; access-time eviction covers the rest. */
+  sweep(): void {
+    const now = this.now()
+    for (const [key, entry] of this.entries) {
+      if (entry.expiresAt <= now) this.entries.delete(key)
+    }
+  }
+
+  /** Live entry count (post-sweep semantics are the caller's; this is a raw size for tests/metrics). */
+  get size(): number {
+    return this.entries.size
+  }
+}
+
+/** Convenience factory mirroring the other core primitives' `create*` style. */
+export function createMemoryIdempotencyStore(
+  options?: MemoryIdempotencyStoreOptions,
+): MemoryIdempotencyStore {
+  return new MemoryIdempotencyStore(options)
+}

package/src/index.ts

@@ -12,13 +12,16 @@
  * (it shipped at "0.0.0" through 1.0.0 before those guards existed). Kept narrow (`as const`) so
  * consumers can pin it at the type level — see `test/version.test-d.ts`.
  */
-export const VERSION = "1.9.0" as const
+export const VERSION = "1.10.0" as const
 
 export type Version = typeof VERSION
 
 export * from "./assurance.ts"
+export * from "./capabilities.ts"
+export * from "./classification.ts"
 export * from "./diff.ts"
 export { FrameworkError, RouteConfigError, type RouteConfigErrorCode } from "./errors.ts"
+export * from "./idempotency.ts"
 export { FRAMEWORK_NAME, type FrameworkName } from "./internal/brand.ts"
 export * from "./reflection.ts"
 export { METHODS, type Method, Router, type RouterMatch } from "./router/router.ts"
@@ -78,6 +81,8 @@ export {
 } from "./server/logger.ts"
 export type { Registry, RouteInfo } from "./server/registry.ts"
 export {
+  type AdmissionController,
+  type AdmissionDecision,
   type AnyServer,
   type DurableObjectNamespaceLike,
   defineIdentityPlugin,

package/src/internal/capability-runtime.ts

@@ -0,0 +1,49 @@
+export const CAPABILITY_GUARD = Symbol("nifra.capability.guard")
+const CAPABILITY_ID = /^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/
+
+export function validCapabilityId(value: string): boolean {
+  return CAPABILITY_ID.test(value)
+}
+
+export interface CapabilityUseEvent {
+  readonly capability: string
+  readonly method: string
+  readonly path: string
+}
+
+export interface CapabilityGuard {
+  readonly allowed: readonly string[]
+  readonly method: string
+  readonly path: string
+  readonly onUse?: (event: CapabilityUseEvent) => void
+}
+
+export function normalizeRouteCapabilities(
+  values: readonly string[] | undefined,
+): readonly string[] {
+  if (values === undefined) return Object.freeze([])
+  if (!Array.isArray(values)) throw new TypeError("route capabilities must be an array")
+  const out: string[] = []
+  const seen = new Set<string>()
+  for (const value of values) {
+    if (typeof value !== "string" || !validCapabilityId(value)) {
+      throw new Error(
+        `route capabilities: invalid capability id ${JSON.stringify(value)} (use lowercase dot/dash segments)`,
+      )
+    }
+    if (!seen.has(value)) {
+      seen.add(value)
+      out.push(value)
+    }
+  }
+  return Object.freeze(out)
+}
+
+export function createCapabilityGuard(
+  allowed: readonly string[],
+  method: string,
+  path: string,
+  onUse: ((event: CapabilityUseEvent) => void) | undefined,
+): CapabilityGuard {
+  return Object.freeze({ allowed, method, path, ...(onUse !== undefined ? { onUse } : {}) })
+}

package/src/internal/route-assurance.ts

@@ -26,6 +26,7 @@ export const NIFRA_ASSURANCE_IDS = Object.freeze({
   AUTHENTICATED: "nifra.authenticated",
   BODY_BOUNDED: "nifra.body-bounded",
   CSRF: "nifra.csrf",
+  DURABLE_COMMAND: "nifra.durable-command",
   IDEMPOTENCY_KEY: "nifra.idempotency-key",
   IP_RESTRICTED: "nifra.ip-restricted",
   RATE_LIMITED: "nifra.rate-limited",

package/src/reflection.ts

@@ -7,6 +7,8 @@
  * recognizes Nifra/TypeBox carriers and raw JSON Schema without depending on a validator package.
  */
 
+import { type DataClassification, isDataClassification } from "./classification.ts"
+import { normalizeRouteCapabilities } from "./internal/capability-runtime.ts"
 import { type AssuranceEvidence, validEvidence } from "./internal/route-assurance.ts"
 import type { StandardSchemaV1 } from "./schema/standard.ts"
 import type { ToolAnnotations } from "./server/server.ts"
@@ -45,6 +47,9 @@ export interface ReflectedRoute {
   readonly path: string
   readonly schema?: ReflectedRouteSchema
   readonly assurance?: readonly AssuranceEvidence[]
+  readonly capabilities?: readonly string[]
+  /** Highest data-sensitivity the response carries, when declared. */
+  readonly classification?: DataClassification
   readonly tool?: {
     readonly name: string
     readonly description: string
@@ -196,11 +201,20 @@ export function reflectRoutes(source: unknown): readonly ReflectedRoute[] {
     const schema = reflectedRouteSchema(route.schema)
     const tool = reflectedTool(route.tool)
     const assurance = reflectedAssurance(route.assurance)
+    const capabilities = normalizeRouteCapabilities(
+      Array.isArray(route.capabilities) ? (route.capabilities as readonly string[]) : undefined,
+    )
+    const rawClassification = recordOf(route.schema)?.classification
+    const classification: DataClassification | undefined = isDataClassification(rawClassification)
+      ? rawClassification
+      : undefined
     reflected.push({
       method: route.method.toUpperCase(),
       path: route.path,
       ...(schema !== undefined ? { schema } : {}),
       ...(assurance !== undefined ? { assurance } : {}),
+      ...(capabilities.length > 0 ? { capabilities } : {}),
+      ...(classification !== undefined ? { classification } : {}),
       ...(tool !== undefined ? { tool } : {}),
     })
   }

package/src/server/context.ts

@@ -1,7 +1,25 @@
-import type { RequestBudget } from "@nifrajs/budget"
+import type { RequestBudget } from "../budget.ts"
+import type { DataClassification } from "../classification.ts"
+import type { IdempotencyScope, IdempotencyStore } from "../idempotency.ts"
 import type { InferOutput, StandardIssue, StandardSchemaV1 } from "../schema/standard.ts"
 import type { CookieOptions } from "./cookies.ts"
 
+/**
+ * Declares a mutating route as idempotent: the server dedupes retries on an `Idempotency-Key` header
+ * (see {@link RouteSchema.idempotency}). Satisfies the capability-assurance idempotency requirement
+ * for a `write` capability — `scope: "durable"` additionally clears the durable-command requirement.
+ */
+export interface IdempotencyConfig {
+  /** `request` = in-process dedupe; `durable` = cross-restart, backed by a durable store. */
+  readonly scope: IdempotencyScope
+  /** Retention for the stored response. Default 24h. */
+  readonly ttlMs?: number
+  /** Store override. Defaults to the server's shared in-memory store; inject a durable store here. */
+  readonly store?: IdempotencyStore
+  /** Header carrying the key. Default `idempotency-key`. */
+  readonly headerName?: string
+}
+
 /** Flattens an intersection into a single object type for readable hovers. */
 export type Prettify<T> = { [K in keyof T]: T[K] } & {}
 
@@ -25,6 +43,22 @@ export type Params<Path extends string> = Prettify<RawParams<Path>>
 
 /** Per-route input schemas. Each is any Standard Schema (zod/valibot/arktype/…). */
 export interface RouteSchema {
+  /** Declared effect tokens. Reflected for assurance; never read by validation or serialization. */
+  readonly capabilities?: readonly string[]
+  /**
+   * Dedupe retries of this (mutating) route on an `Idempotency-Key` header. The first request runs and
+   * its response is stored; a retry with the same key replays that response without re-running the
+   * handler, and a key reused with a different body is rejected (409). A missing key on an
+   * idempotency-required route fails closed (400). Off the hot path — routes without it are unchanged.
+   */
+  readonly idempotency?: IdempotencyConfig
+  /**
+   * Highest data-sensitivity this route's response body carries (`public` | `pii` | `secret`). A
+   * declarative, compile-time + introspection fact — never validated at runtime. Reflected for tooling,
+   * recorded in the capability lockfile (so a route that starts returning PII is a reviewable change),
+   * and read by downstream policy (e.g. a partner-API surface refusing to expose `pii`/`secret`).
+   */
+  readonly classification?: DataClassification
   readonly body?: StandardSchemaV1
   readonly query?: StandardSchemaV1
   /** Optional **response contract**. When declared: the handler's return is type-checked against it

package/src/server/contract.ts

@@ -1,7 +1,9 @@
+import type { DataClassification } from "../classification.ts"
 import { RouteConfigError } from "../errors.ts"
+import { normalizeRouteCapabilities } from "../internal/capability-runtime.ts"
 import { METHODS, type Method } from "../router/router.ts"
 import type { InferOutput, StandardSchemaV1 } from "../schema/standard.ts"
-import type { Context, Params, RouteSchema } from "./context.ts"
+import type { Context, IdempotencyConfig, Params, RouteSchema } from "./context.ts"
 import type { OutputOf } from "./registry.ts"
 import { Server } from "./server.ts"
 
@@ -27,6 +29,12 @@ export interface OperationDef {
   readonly body?: StandardSchemaV1
   readonly query?: StandardSchemaV1
   readonly response?: StandardSchemaV1
+  /** Declared effect tokens, carried into route reflection and capability assurance. */
+  readonly capabilities?: readonly string[]
+  /** Dedupe retries of this operation on an `Idempotency-Key` header (see {@link RouteSchema.idempotency}). */
+  readonly idempotency?: IdempotencyConfig
+  /** Highest data-sensitivity the response carries (see {@link RouteSchema.classification}). */
+  readonly classification?: DataClassification
   /** Short summary (OpenAPI `summary`). */
   readonly summary?: string
   /** Longer description (OpenAPI `description`, CommonMark). */
@@ -167,6 +175,7 @@ export function defineContract<const C extends ContractShape>(contract: C): C {
     if (seen.has(key)) {
       throw new RouteConfigError("DUPLICATE_ROUTE", `duplicate operation route: ${key}`)
     }
+    normalizeRouteCapabilities(op.capabilities)
     seen.add(key)
   }
   return contract
@@ -219,11 +228,19 @@ export function implement<const C extends ContractShape, H extends HandlersFor<C
     // once here at bind time, not per request — it just carries a reference to the op's existing schema.
     // A response-less op still yields `undefined`, byte-identical to before.
     const schema: RouteSchema | undefined =
-      op.body !== undefined || op.query !== undefined || op.response !== undefined
+      op.body !== undefined ||
+      op.query !== undefined ||
+      op.response !== undefined ||
+      op.capabilities !== undefined ||
+      op.idempotency !== undefined ||
+      op.classification !== undefined
         ? {
             ...(op.body !== undefined ? { body: op.body } : {}),
             ...(op.query !== undefined ? { query: op.query } : {}),
             ...(op.response !== undefined ? { response: op.response } : {}),
+            ...(op.capabilities !== undefined ? { capabilities: op.capabilities } : {}),
+            ...(op.idempotency !== undefined ? { idempotency: op.idempotency } : {}),
+            ...(op.classification !== undefined ? { classification: op.classification } : {}),
           }
         : undefined
     app.register(