@ainra/middleware 0.4.0

package/README.md

@@ -0,0 +1,90 @@
+<!-- SPDX-License-Identifier: Apache-2.0 OR MIT -->
+# @ainra/middleware
+
+A fail-closed gate for requests made by AI agents. Five lines in front of your handler, and a request gets through
+only if it carried a valid [AINRA](https://ainra.vercel.app/) passport.
+
+**Offline. Fail-closed. Zero telemetry.** The check is local — no account with us, no per-request call, nothing that
+can be down. A request with no passport, a revoked one, or one whose status cannot be freshly confirmed is refused
+with a machine-readable reason.
+
+```sh
+npm install @ainra/middleware
+```
+
+## Connect / Express
+
+```js
+import express from "express";
+import { Verifier, ainraGate } from "@ainra/middleware";
+
+const verifier = Verifier.fromDirectoryB64(directory, roots.root_ed25519, roots.root_slh);
+
+const app = express();
+app.use("/agent", ainraGate(verifier));      // every /agent request must carry a valid passport
+
+app.post("/agent/order", (req, res) => {
+  req.ainra;   // the GateResult: { allow, reason?, verdict, event }
+});
+```
+
+The passport arrives in the `x-ainra-passport` header (raw JSON or base64url of it), or in `body.ainra_passport`.
+On refusal the gate answers **403** with `{ error, reason }`. Every response — allowed or refused — carries
+`x-ainra-verdict`, the canonical verdict event.
+
+Options: `header` (default `x-ainra-passport`), `now` (your clock, for tests and fixed demo windows), and `onDeny`
+for logging. It never receives secrets and never throws.
+
+## Any other framework
+
+`checkRequest` is the same decision without the Connect shape — hand it the bundle, get a result:
+
+```js
+import { checkRequest } from "@ainra/middleware";
+
+const result = checkRequest(verifier, req.headers.get("x-ainra-passport"));
+if (!result.allow) return new Response(result.reason, { status: 403 });
+```
+
+It accepts a decoded object or the base64url-of-JSON string a header carries, and returns
+`{ allow, reason?, verdict, event }`. Anything that is not a bundle verifying `valid` — including a parse failure —
+comes back `allow: false`.
+
+## What "fail-closed" costs you
+
+Nothing on the happy path, and it is the whole point on the unhappy one. When status freshness cannot be
+established this gate refuses, rather than admitting the request and logging a warning. That is the behaviour you
+want on the day a key is stolen, and it is the behaviour that becomes impossible to add later, once something
+depends on the lenient path.
+
+## Underneath
+
+Verification is [`@ainra/sdk`](https://www.npmjs.com/package/@ainra/sdk) — one of the three implementations that
+agree on all 1153 conformance vectors, on verdict and reason. This package adds only the request plumbing: header decoding, the 403, the
+verdict event, and `req.ainra`.
+
+Licensed Apache-2.0 OR MIT.
+
+## Gating a running copy (ADR-019)
+
+The gate accepts an instance credential wherever it accepts a passport — build the `Verifier` with your audience
+and nothing else changes:
+
+```js
+const verifier = Verifier.fromDirectoryB64(directory, roots.root_ed25519, roots.root_slh, "F2", false,
+  "https://api.example");           // ← YOUR audience; a presenter can never supply it
+app.use("/agent", ainraGate(verifier));
+```
+
+Refusals arrive with their own reason, so a 403 tells the caller what to fix:
+
+| reason | what the caller should do |
+|---|---|
+| `instance_expired` | mint a fresh credential — the passport is fine |
+| `instance_scope_exceeds` | the copy asked for more than its passport holds |
+| `instance_sig_invalid` | not minted by that passport's control key, or bound to another passport |
+| `instance_pop_invalid` | wrong audience, stale timestamp, or no proof of possession |
+| `revoked` | the **passport** is revoked — every live copy under it is dead |
+
+The verdict event gains `instance_iid` and `instance_exp` (both `null` for a plain passport), so an operator
+watching the log sees short expiries and can spot a long one. Proven by `make instance-gate`.

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+import { Verifier, type Verdict, type VerdictEvent } from "@ainra/sdk";
+export interface GateOptions {
+    /** Verifier's clock, unix seconds. Default: `Date.now()/1000`. Pass a fixed value for a demo/test window. */
+    now?: () => number;
+    /** Header the presentation bundle (JSON, or base64url-of-JSON) arrives in. Default `x-ainra-passport`. */
+    header?: string;
+    /** Called on deny (before the 403 is sent) — for logging. Never receives secrets. */
+    onDeny?: (reason: string) => void;
+}
+export interface GateResult {
+    allow: boolean;
+    reason?: string;
+    verdict: Verdict;
+    /** The canonical verdict event (docs/PRESENTATION.md) — identical shape across CLI, MCP, and this middleware. */
+    event: VerdictEvent;
+}
+/** Verify one presentation bundle. FAIL CLOSED: anything that isn't a bundle that verifies VALID → `allow:false`.
+ * Never throws. `bundle` may be a decoded object or a base64url-of-JSON string (what a header carries). */
+export declare function checkRequest(verifier: Verifier, bundle: unknown, opts?: GateOptions): GateResult;
+interface ReqLike {
+    headers: Record<string, string | string[] | undefined>;
+    body?: unknown;
+    ainra?: GateResult;
+}
+interface ResLike {
+    status(code: number): ResLike;
+    json(body: unknown): unknown;
+    setHeader(name: string, value: string): void;
+}
+type Next = () => void;
+/**
+ * Connect/Express middleware. Reads the presentation from the configured header (or `req.body.ainra_passport`),
+ * verifies it, and either calls `next()` (attaching `req.ainra`) or responds **403 fail-closed** with the reason.
+ *
+ * ```ts
+ * const verifier = Verifier.fromDirectoryB64(directory, roots.root_ed25519, roots.root_slh)!;
+ * app.use("/agent", ainraGate(verifier));   // every /agent request must carry a valid passport
+ * ```
+ */
+export declare function ainraGate(verifier: Verifier, opts?: GateOptions): (req: ReqLike, res: ResLike, next: Next) => void;
+export { Verifier, verdictEvent, serializeVerdictEvent, type VerdictEvent } from "@ainra/sdk";

package/dist/index.js

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: Apache-2.0 OR MIT
+//! `@ainra/middleware` — the verifier wedge: a fail-closed gate that checks an AINRA passport presented on a
+//! request and allows or denies it, in ~5 lines of integration. Pure over `@ainra/sdk`'s `Verifier`: no network,
+//! no state, no telemetry — a request either carries a presentation bundle that verifies against the trusted
+//! directory, or it is denied with a machine-readable reason.
+//!
+//! Two surfaces:
+//!   * `ainraGate(verifier, opts)` → Connect/Express `(req, res, next)` middleware.
+//!   * `checkRequest(verifier, bundle, opts)` → framework-agnostic `{ allow, reason?, verdict }` (edge/fetch).
+import { verdictEvent, serializeVerdictEvent } from "@ainra/sdk";
+const DENY_SCHEMA = { verdict: "invalid", reason: "schema_violation" };
+/** Verify one presentation bundle. FAIL CLOSED: anything that isn't a bundle that verifies VALID → `allow:false`.
+ * Never throws. `bundle` may be a decoded object or a base64url-of-JSON string (what a header carries). */
+export function checkRequest(verifier, bundle, opts = {}) {
+    const now = (opts.now ?? (() => Math.floor(Date.now() / 1000)))();
+    let parsed;
+    try {
+        if (typeof bundle === "string") {
+            // Accept raw JSON or base64url(JSON) — a header is easiest as the latter.
+            const text = bundle.trim().startsWith("{") ? bundle : Buffer.from(bundle, "base64url").toString("utf8");
+            parsed = JSON.parse(text);
+        }
+        else if (bundle && typeof bundle === "object") {
+            parsed = bundle;
+        }
+        else {
+            return { allow: false, reason: "schema_violation", verdict: DENY_SCHEMA, event: verdictEvent({}, DENY_SCHEMA, now) };
+        }
+    }
+    catch {
+        return { allow: false, reason: "schema_violation", verdict: DENY_SCHEMA, event: verdictEvent({}, DENY_SCHEMA, now) };
+    }
+    const verdict = verifier.verify(parsed, now); // never throws; invalid on any failure
+    const allow = verdict.verdict === "valid";
+    return { allow, reason: allow ? undefined : verdict.reason, verdict, event: verdictEvent(parsed, verdict, now) };
+}
+/**
+ * Connect/Express middleware. Reads the presentation from the configured header (or `req.body.ainra_passport`),
+ * verifies it, and either calls `next()` (attaching `req.ainra`) or responds **403 fail-closed** with the reason.
+ *
+ * ```ts
+ * const verifier = Verifier.fromDirectoryB64(directory, roots.root_ed25519, roots.root_slh)!;
+ * app.use("/agent", ainraGate(verifier));   // every /agent request must carry a valid passport
+ * ```
+ */
+export function ainraGate(verifier, opts = {}) {
+    const header = (opts.header ?? "x-ainra-passport").toLowerCase();
+    return (req, res, next) => {
+        const raw = req.headers[header] ?? req.body?.ainra_passport;
+        const result = raw === undefined
+            ? { allow: false, reason: "schema_violation", verdict: DENY_SCHEMA, event: verdictEvent({}, DENY_SCHEMA, (opts.now ?? (() => Math.floor(Date.now() / 1000)))()) }
+            : checkRequest(verifier, Array.isArray(raw) ? raw[0] : raw, opts);
+        req.ainra = result;
+        // Emit the canonical verdict event on every request (allow or deny) — one event shape everywhere (PRESENTATION.md).
+        res.setHeader("x-ainra-verdict", serializeVerdictEvent(result.event));
+        if (result.allow) {
+            next();
+            return;
+        }
+        if (opts.onDeny)
+            opts.onDeny(result.reason ?? "schema_violation");
+        res.setHeader("x-ainra-reason", result.reason ?? "schema_violation");
+        res.status(403).json({ error: "ainra: passport not valid", reason: result.reason });
+    };
+}
+export { Verifier, verdictEvent, serializeVerdictEvent } from "@ainra/sdk";

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@ainra/middleware",
+  "version": "0.4.0",
+  "description": "AINRA verifier middleware — a fail-closed gate (Connect/Express + framework-agnostic) that verifies an AINRA passport on a request, over @ainra/sdk. The verification wedge: local, offline, ~5-line integration.",
+  "license": "Apache-2.0 OR MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test"
+  },
+  "dependencies": {
+    "@ainra/sdk": "^0.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "typescript": "^5.6.0"
+  },
+  "homepage": "https://ainra.vercel.app/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JacobJandon/ainra.git"
+  }
+}