@coderifts/capability-express 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CodeRifts
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,95 @@
+# @coderifts/capability-express
+
+Express middleware that verifies `cr.exec.v1` execution grants **offline**, against a public key you
+pin. No network call on the request path.
+
+Zero runtime dependencies — Node builtins only. Express is a peer of your app, not of this package.
+
+## Install
+
+```bash
+npm install @coderifts/capability-express
+```
+
+## Quickstart
+
+```js
+const express = require('express');
+const { requireExecutionGrant, captureRawBody } = require('@coderifts/capability-express');
+
+const app = express();
+
+const guard = requireExecutionGrant({
+  // One of these two. keysFile is a registry document: { keys: [{ kid, public_key_pem, status }] }
+  keysFile: '/etc/coderifts/keys/executor-keys.json',
+  // publicKeyPem: fs.readFileSync('executor-public.pem', 'utf8'),
+
+  // Which operation each route represents. A route that is not in this map is REFUSED:
+  // an unmapped mutation is not an authorized mutation.
+  operationMap: {
+    'POST /articles': 'publish',
+    'DELETE /articles/:id': 'deploy',
+  },
+});
+
+// captureRawBody must run BEFORE the guard: the raw request body IS the after-payload the
+// grant is bound to, and a re-serialized body is different bytes.
+app.post('/articles', captureRawBody(), guard, (req, res) => {
+  res.status(201).json({ created: true, jti: req.coderifts.payload.jti });
+});
+```
+
+A request without a valid grant gets `403` and never reaches your handler.
+
+## What a refusal looks like
+
+```json
+{
+  "error": "execution_grant_required",
+  "status": "MALFORMED",
+  "reason": "missing_grant_header",
+  "remedy": {
+    "error": "CODERIFTS_GRANT_REQUIRED",
+    "target": "POST /articles",
+    "fingerprint": "sha256:…",
+    "action_required": { "tool": "preflight_change_set", "mode": "authorize", "args_shape": { } },
+    "does_not_promise": "a grant does not guarantee execution (CAS may still fail)"
+  }
+}
+```
+
+`remedy` is present only when the refusal maps to one of three grant error classes
+(`CODERIFTS_GRANT_REQUIRED` / `_INVALID` / `_MISMATCH`). A refusal outside them — an unmapped route,
+for instance — carries no remedy, because no grant the caller could obtain would change the answer.
+
+## Options
+
+| option | required | meaning |
+|---|---|---|
+| `keysFile` | one of | Path to a registry document `{ keys: [{ kid, public_key_pem, status }] }` |
+| `publicKeyPem` | one of | A single PEM, for the air-gapped case |
+| `kid` | no | Select a specific key from `keysFile` |
+| `operationMap` | yes | `'<METHOD> <route path>' -> operation`. Unmapped routes are refused |
+| `audience` | no | Grants must be bound to this audience when set |
+| `targetId` | no | `(req) => string` — what the grant is bound to. Defaults to `req.params.id` |
+| `header` | no | Grant header name. Default `coderifts-execution-grant` |
+| `now` | no | Clock injection, for tests |
+
+Key material is resolved **once at construction**. There is no request-time key I/O.
+
+## Exports
+
+`requireExecutionGrant`, `captureRawBody`, `verifyExecutionGrant`, `computeScopeHash`,
+`DEFAULT_HEADER`.
+
+## What this does and does not prove
+
+It proves that a request carried a grant that verifies against the key you pinned, is bound to this
+operation and target, and covers these exact after-payload bytes.
+
+It does not prove the write happened, that it happened atomically, or that anything downstream
+honoured the decision. A grant is permission to attempt, not evidence of a result.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@coderifts/capability-express",
+  "version": "1.0.0",
+  "description": "Express middleware that verifies cr.exec.v1 execution grants OFFLINE against a pinned Ed25519 public key.",
+  "license": "MIT",
+  "main": "src/index.js",
+  "type": "commonjs",
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.js\"",
+    "prepublishOnly": "npm test"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/coderifts/capability-demo.git",
+    "directory": "packages/middleware"
+  },
+  "homepage": "https://github.com/coderifts/capability-demo/tree/main/packages/middleware",
+  "bugs": {
+    "url": "https://github.com/coderifts/capability-demo/issues"
+  },
+  "keywords": [
+    "express",
+    "middleware",
+    "ed25519",
+    "authorization",
+    "offline-verification"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/attest.js

@@ -0,0 +1,292 @@
+'use strict';
+
+/**
+ * cr.exec.attest.v1 — the executor's signed commit statement.
+ *
+ * Issuance AND offline verification. Mirrors the reference kernel
+ * (coderifts-app src/verdict-core/execution-attestation.js) and the algorithm in
+ * docs/cr-exec-attest-v1.md. Statuses and reason strings are IDENTICAL to that family —
+ * this file adds none of its own.
+ *
+ * The executor key is CUSTOMER-HELD. CodeRifts never receives it. Verification reads a
+ * customer-pinned registry document (same JSON shape as .well-known/coderifts-keys.json),
+ * passed in as opts.registry — never fetched.
+ *
+ * Honesty: a valid attestation proves *a holder of the executor key asserts this commit*.
+ * It does not prove the executor's code is unmodified (deploy attestation is out of scope),
+ * that a human saw anything, or that the grant is still currently authorized.
+ */
+
+const crypto = require('node:crypto');
+
+const ATTEST_VERSION = 'cr.exec.attest.v1';
+const ENVELOPE_TAG = 'cr.exec.attest.v1';
+const SIGNING_PREFIX = 'crexecattest.v1';
+const CLOCK_SKEW_LEEWAY_MS = 30_000;
+
+const REQUIRED_FIELDS = Object.freeze([
+  'executor_kid', 'grant_jti', 'receipt_digest', 'scope_hash', 'committed_at',
+]);
+const OPTIONAL_STRINGS = Object.freeze(['state_nonce', 'result_digest']);
+const ALLOWED_KEYS = new Set(['v', ...REQUIRED_FIELDS, ...OPTIONAL_STRINGS, 'meta']);
+
+const STATUSES = Object.freeze({
+  ATTEST_VALID: 'ATTEST_VALID',
+  ATTEST_INVALID_SIGNATURE: 'ATTEST_INVALID_SIGNATURE',
+  ATTEST_UNKNOWN_KEY: 'ATTEST_UNKNOWN_KEY',
+  ATTEST_RETIRED_KEY_VALID_AT_ISSUE: 'ATTEST_RETIRED_KEY_VALID_AT_ISSUE',
+  ATTEST_MALFORMED: 'ATTEST_MALFORMED',
+  ATTEST_UNBOUND: 'ATTEST_UNBOUND',
+});
+
+const scalar = (v) => (v == null ? '' : String(v));
+const b64url = (b) => Buffer.from(b).toString('base64url');
+const sha256hex = (s) => crypto.createHash('sha256').update(String(s), 'utf8').digest('hex');
+
+/** JSON.stringify with keys sorted — appended to the signing input only when meta is present. */
+function canonicalMeta(meta) {
+  const out = {};
+  for (const k of Object.keys(meta).sort()) out[k] = meta[k];
+  return JSON.stringify(out);
+}
+
+/** meta is advisory and bounded: <=8 keys, key <=64 chars, string values <=256 chars. */
+function metaOk(meta) {
+  if (meta == null) return true;
+  if (typeof meta !== 'object' || Array.isArray(meta)) return false;
+  const keys = Object.keys(meta);
+  if (keys.length > 8) return false;
+  for (const k of keys) {
+    if (k.length > 64) return false;
+    const v = meta[k];
+    const t = typeof v;
+    if (t !== 'string' && t !== 'number' && t !== 'boolean') return false;
+    if (t === 'string' && v.length > 256) return false;
+  }
+  return true;
+}
+
+/**
+ * Signing input (pipe-delimited, NOT JCS):
+ *   crexecattest.v1|kid|grant_jti|receipt_digest|scope_hash|state_nonce|committed_at|result_digest[|meta]
+ * state_nonce and result_digest are FIXED SLOTS — empty strings when absent.
+ */
+function signingInput(body) {
+  const parts = [
+    SIGNING_PREFIX,
+    scalar(body.executor_kid),
+    scalar(body.grant_jti),
+    scalar(body.receipt_digest),
+    scalar(body.scope_hash),
+    body.state_nonce != null && String(body.state_nonce).length > 0 ? String(body.state_nonce) : '',
+    scalar(body.committed_at),
+    body.result_digest != null && String(body.result_digest).length > 0 ? String(body.result_digest) : '',
+  ];
+  if (body.meta && typeof body.meta === 'object') parts.push(canonicalMeta(body.meta));
+  return parts.join('|');
+}
+
+function fieldHasDelimiter(body) {
+  for (const k of Object.keys(body)) {
+    if (k.includes('|')) return true;
+    const v = body[k];
+    if (typeof v === 'string' && v.includes('|')) return true;
+    if (k === 'meta' && v && typeof v === 'object') {
+      for (const mk of Object.keys(v)) {
+        if (mk.includes('|')) return true;
+        if (typeof v[mk] === 'string' && v[mk].includes('|')) return true;
+      }
+    }
+  }
+  return false;
+}
+
+const fail = (status, reason, payload) => ({ valid: false, status, reason, payload });
+const okStatus = (status, payload) => ({ valid: true, status, reason: null, payload });
+
+function toUtcSeconds(d) { return d.toISOString().replace(/\.\d{3}Z$/, 'Z'); }
+
+/**
+ * Sign an attestation with a CALLER-SUPPLIED executor private key.
+ * Never touches any CodeRifts signer.
+ *
+ * @param {object} a
+ * @param {import('node:crypto').KeyObject|string} a.privateKey  executor key (customer-held)
+ * @param {string} a.executor_kid
+ * @param {string} a.grant_jti
+ * @param {string} a.receipt_digest
+ * @param {string} a.scope_hash
+ * @param {string} [a.state_nonce]     copied from the grant iff it carried one (ATOMIC)
+ * @param {string} [a.result_digest]   executor-defined bytes; NOT a CodeRifts fingerprint
+ * @param {object} [a.meta]
+ * @param {Date|number} [a.now]
+ * @returns {string} cr.exec.attest.v1|kid|payload_b64|sig_b64
+ */
+function issueExecutionAttestation(a) {
+  const key = typeof a.privateKey === 'string' ? crypto.createPrivateKey(a.privateKey) : a.privateKey;
+  const now = a.now != null ? new Date(a.now) : new Date();
+  const payload = { v: ATTEST_VERSION, executor_kid: String(a.executor_kid) };
+  payload.grant_jti = String(a.grant_jti);
+  payload.receipt_digest = String(a.receipt_digest);
+  payload.scope_hash = String(a.scope_hash);
+  if (a.state_nonce != null && String(a.state_nonce).length > 0) payload.state_nonce = String(a.state_nonce);
+  payload.committed_at = toUtcSeconds(now);
+  if (a.result_digest != null && String(a.result_digest).length > 0) payload.result_digest = String(a.result_digest);
+  if (a.meta && typeof a.meta === 'object') payload.meta = a.meta;
+
+  if (fieldHasDelimiter(payload)) throw new Error('issueExecutionAttestation: | in a signed field');
+  if (!metaOk(payload.meta)) throw new Error('issueExecutionAttestation: meta exceeds bounds');
+
+  const sig = crypto.sign(null, Buffer.from(signingInput(payload), 'utf8'), key);
+  return [ENVELOPE_TAG, payload.executor_kid, b64url(Buffer.from(JSON.stringify(payload), 'utf8')), b64url(sig)].join('|');
+}
+
+/** Steps 1-2. Envelope is 4 pipe segments; kid lives in the prefix so a registry can be consulted first. */
+function parseAttestToken(token) {
+  if (typeof token !== 'string' || token.length === 0) {
+    return { ok: false, status: STATUSES.ATTEST_MALFORMED, reason: 'malformed_structure' };
+  }
+  const seg = token.split('|');
+  if (seg.length !== 4 || seg.some((x) => !x) || seg[0] !== ENVELOPE_TAG) {
+    return { ok: false, status: STATUSES.ATTEST_MALFORMED, reason: 'malformed_structure' };
+  }
+  let payload;
+  try {
+    payload = JSON.parse(Buffer.from(seg[2], 'base64url').toString('utf8'));
+  } catch (_) {
+    return { ok: false, status: STATUSES.ATTEST_MALFORMED, reason: 'bad_json' };
+  }
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    return { ok: false, status: STATUSES.ATTEST_MALFORMED, reason: 'bad_json' };
+  }
+  if (payload.v !== ATTEST_VERSION) {
+    return { ok: false, status: STATUSES.ATTEST_MALFORMED, reason: 'unsupported_version', payload };
+  }
+  for (const k of REQUIRED_FIELDS) {
+    if (typeof payload[k] !== 'string' || payload[k].length === 0) {
+      return { ok: false, status: STATUSES.ATTEST_MALFORMED, reason: 'missing_field', payload };
+    }
+  }
+  for (const k of OPTIONAL_STRINGS) {
+    if (payload[k] !== undefined && typeof payload[k] !== 'string') {
+      return { ok: false, status: STATUSES.ATTEST_MALFORMED, reason: 'bad_optional', payload };
+    }
+  }
+  if (payload.executor_kid !== seg[1]) {
+    return { ok: false, status: STATUSES.ATTEST_MALFORMED, reason: 'kid_mismatch', payload };
+  }
+  for (const k of Object.keys(payload)) {
+    if (!ALLOWED_KEYS.has(k)) {
+      return { ok: false, status: STATUSES.ATTEST_MALFORMED, reason: 'unknown_field', payload };
+    }
+  }
+  if (!metaOk(payload.meta)) {
+    return { ok: false, status: STATUSES.ATTEST_MALFORMED, reason: 'meta_bounds', payload };
+  }
+  if (payload.result_digest !== undefined && !/^sha256:[0-9a-f]{64}$/.test(payload.result_digest)) {
+    return { ok: false, status: STATUSES.ATTEST_MALFORMED, reason: 'bad_result_digest', payload };
+  }
+  if (!/^sha256:[0-9a-f]{64}$/.test(payload.receipt_digest)) {
+    return { ok: false, status: STATUSES.ATTEST_MALFORMED, reason: 'bad_receipt_digest', payload };
+  }
+  return { ok: true, payload, sig: seg[3] };
+}
+
+function resolveExecutorKey(registry, kid) {
+  const keys = registry && Array.isArray(registry.keys) ? registry.keys : null;
+  if (!keys) return null;
+  const e = keys.find((k) => k && k.kid === kid);
+  if (!e || !e.public_key_pem) return null;
+  return {
+    publicKey: crypto.createPublicKey(e.public_key_pem),
+    status: e.status || 'active',
+    valid_from: e.valid_from || null,
+    retired_at: e.retired_at || null,
+  };
+}
+
+const nonceOf = (o) => (o && o.state_nonce != null && String(o.state_nonce).length > 0 ? String(o.state_nonce) : '');
+
+/**
+ * Offline verification, spec steps 1-8.
+ * @param {string} token
+ * @param {{registry: object, intended?: {grant?: object, receipt_digest?: string}, now?: number}} opts
+ */
+function verifyExecutionAttestation(token, opts = {}) {
+  const parsed = parseAttestToken(token);
+  if (!parsed.ok) return fail(parsed.status, parsed.reason, parsed.payload);
+  const payload = parsed.payload;
+
+  if (fieldHasDelimiter(payload)) {
+    return fail(STATUSES.ATTEST_INVALID_SIGNATURE, 'delimiter_in_field', payload);
+  }
+
+  const entry = resolveExecutorKey(opts.registry, payload.executor_kid);
+  if (!entry) return fail(STATUSES.ATTEST_UNKNOWN_KEY, 'unknown_kid', payload);
+
+  let ok = false;
+  try {
+    ok = crypto.verify(null, Buffer.from(signingInput(payload), 'utf8'), entry.publicKey,
+      Buffer.from(parsed.sig, 'base64url'));
+  } catch (_) {
+    return fail(STATUSES.ATTEST_INVALID_SIGNATURE, 'signature_error', payload);
+  }
+  if (!ok) return fail(STATUSES.ATTEST_INVALID_SIGNATURE, 'signature_mismatch', payload);
+
+  const now = Number.isFinite(opts.now) ? opts.now : Date.now();
+  const committedMs = Date.parse(payload.committed_at);
+  if (!Number.isFinite(committedMs)) return fail(STATUSES.ATTEST_MALFORMED, 'bad_timestamp', payload);
+  if (committedMs > now + CLOCK_SKEW_LEEWAY_MS) {
+    return fail(STATUSES.ATTEST_MALFORMED, 'committed_at_in_future', payload);
+  }
+
+  // Step 6 — HISTORICAL retired-key rule. Unlike a GRANT (live permission, where a retired
+  // kid is always UNKNOWN_KEY), an attestation is a statement about a PAST commit, so a
+  // retired key still proves it if committed_at fell inside [valid_from, retired_at).
+  let retiredHistorical = false;
+  if (entry.status === 'retired') {
+    const from = entry.valid_from ? Date.parse(entry.valid_from) : null;
+    const until = entry.retired_at ? Date.parse(entry.retired_at) : null;
+    const inWindow = Number.isFinite(until) && committedMs < until
+      && (!Number.isFinite(from) || committedMs >= from);
+    if (!inWindow) return fail(STATUSES.ATTEST_UNKNOWN_KEY, 'retired_key_outside_window', payload);
+    retiredHistorical = true;
+  }
+
+  // Step 7 — cross-checks only when the caller holds the grant. Field equality is the bind;
+  // GRANT_CURRENT is deliberately NOT required (a grant may expire after the commit).
+  const intended = opts.intended && typeof opts.intended === 'object' ? opts.intended : null;
+  if (intended) {
+    const g = intended.grant;
+    if (g !== undefined) {
+      if (!g || typeof g !== 'object') return fail(STATUSES.ATTEST_UNBOUND, 'grant_unparseable', payload);
+      if (String(g.jti || '') !== payload.grant_jti) {
+        return fail(STATUSES.ATTEST_UNBOUND, 'grant_jti_mismatch', payload);
+      }
+      if (String(g.scope_hash || '') !== payload.scope_hash) {
+        return fail(STATUSES.ATTEST_UNBOUND, 'scope_hash_mismatch', payload);
+      }
+      if (nonceOf(g) !== nonceOf(payload)) {
+        return fail(STATUSES.ATTEST_UNBOUND, 'state_nonce_mismatch', payload);
+      }
+      if (g.receipt_digest && String(g.receipt_digest) !== payload.receipt_digest) {
+        return fail(STATUSES.ATTEST_UNBOUND, 'receipt_digest_mismatch', payload);
+      }
+    }
+    if (intended.receipt_digest != null && String(intended.receipt_digest).length > 0
+        && String(intended.receipt_digest) !== payload.receipt_digest) {
+      return fail(STATUSES.ATTEST_UNBOUND, 'receipt_digest_mismatch', payload);
+    }
+  }
+
+  return retiredHistorical
+    ? okStatus(STATUSES.ATTEST_RETIRED_KEY_VALID_AT_ISSUE, payload)
+    : okStatus(STATUSES.ATTEST_VALID, payload);
+}
+
+module.exports = {
+  ATTEST_VERSION, ENVELOPE_TAG, SIGNING_PREFIX, STATUSES, CLOCK_SKEW_LEEWAY_MS,
+  REQUIRED_FIELDS, OPTIONAL_STRINGS,
+  signingInput, canonicalMeta, metaOk, sha256hex,
+  issueExecutionAttestation, parseAttestToken, verifyExecutionAttestation, resolveExecutorKey,
+};

package/src/deny-remedy.js

@@ -0,0 +1,131 @@
+/**
+ * deny-remedy.v1 — the machine-readable next step attached to a refusal.
+ *
+ * CANONICAL SCHEMA: capability-demo/docs/deny-remedy.v1.json
+ *   sha256 3f51c5afd1708a9185075a4f19f6386ea7d63ad39b0104e31f0e4e887b6e167f
+ *
+ * This builder is copied byte-for-byte into every repo that emits a deny, and
+ * must stay equivalent to that schema. It is a copy rather than a shared
+ * package on purpose: these repos are installed independently and a shared
+ * dependency would make one of them unable to refuse a request because another
+ * failed to resolve.
+ *
+ * WHERE IT SITS IN THE FLOW. The remedy is attached AFTER a verdict is reached,
+ * never inside verification. Nothing here reads a key, checks a signature, or
+ * can change allow into deny. A surface that emits a remedy has already refused.
+ *
+ * WHAT IT REFUSES TO EMIT. Three error classes exist and no more. A refusal
+ * whose reason does not map to one of them gets NO remedy — an unmapped reason
+ * is a refusal we cannot yet describe as a next step, and inventing a fourth
+ * class, or defaulting to the nearest one, would send a caller to a step that
+ * does not address why they were refused.
+ */
+'use strict';
+
+/** The closed set from the schema. */
+const DENY_ERROR = Object.freeze({
+  GRANT_REQUIRED: 'CODERIFTS_GRANT_REQUIRED',
+  GRANT_INVALID: 'CODERIFTS_GRANT_INVALID',
+  GRANT_MISMATCH: 'CODERIFTS_GRANT_MISMATCH',
+});
+
+/** Carried verbatim from the schema so it cannot be softened in rendering. */
+const DOES_NOT_PROMISE = 'a grant does not guarantee execution (CAS may still fail)';
+
+const ARGS_SHAPE = Object.freeze({
+  artifacts: 'Array<{ id, type, before, after }> — the change set being authorized',
+  context: '{ operation, environment?, repository?, branch?, pull_request? } — operation is required for authorize',
+});
+
+const FINGERPRINT_RE = /^sha256:[0-9a-f]{64}$/;
+
+/**
+ * Build the remedy object, or return null when this refusal has no remedy.
+ *
+ * @param {string}  o.error        one of DENY_ERROR; anything else returns null
+ * @param {string}  [o.target]     the surface's own addressing for what was refused
+ * @param {string}  [o.fingerprint] the change-set fingerprint the deny was evaluated
+ *                                 against, when the surface has one
+ * @param {object}  [o.observed]   free-form, for an operator reading a log
+ * @returns {object|null}
+ */
+function buildDenyRemedy({ error, target = null, fingerprint = null, observed = null } = {}) {
+  if (!Object.values(DENY_ERROR).includes(error)) return null;
+
+  const remedy = {
+    error,
+    // Null, never a wildcard: a surface that cannot name what it refused must
+    // not emit a value a reader could take for "everything".
+    target: typeof target === 'string' && target.length > 0 ? target : null,
+    // Only a well-formed fingerprint. A malformed one is dropped rather than
+    // passed through, because a caller comparing it would get a false mismatch.
+    fingerprint: typeof fingerprint === 'string' && FINGERPRINT_RE.test(fingerprint)
+      ? fingerprint
+      : null,
+    action_required: {
+      tool: 'preflight_change_set',
+      mode: 'authorize',
+      args_shape: { ...ARGS_SHAPE },
+    },
+    does_not_promise: DOES_NOT_PROMISE,
+  };
+  if (observed && typeof observed === 'object') remedy.observed = observed;
+  return remedy;
+}
+
+/**
+ * Map a surface's own refusal reason to an error class.
+ *
+ * The mapping is explicit and closed. An unlisted reason returns null, which
+ * means no remedy — see the note at the top of this file.
+ */
+function denyErrorForReason(reason) {
+  switch (String(reason || '').toLowerCase()) {
+    // Nothing was presented.
+    case 'receipt_missing':
+    case 'missing_receipt':
+    case 'missing_grant_header':
+    case 'decision_missing':
+    case 'missing_decision_result':
+    case 'no_preflight_response':
+    case 'grant_not_supplied':
+      return DENY_ERROR.GRANT_REQUIRED;
+
+    // Something was presented and did not hold up.
+    case 'receipt_invalid':
+    case 'receipt_unverified':
+    case 'invalid_signature':
+    case 'unknown_key':
+    case 'unknown_kid':
+    case 'dsse_malformed':
+    case 'dsse_unsupported':
+    case 'dsse_predicate_mismatch':
+    case 'malformed':
+    case 'grant_malformed':
+    case 'grant_unverified':
+    case 'grant_expired':
+      return DENY_ERROR.GRANT_INVALID;
+
+    // It held up, but it is not about this request.
+    case 'scope_mismatch':
+    case 'target_mismatch':
+    case 'operation_mismatch':
+    case 'grant_scope_mismatch':
+    case 'mode_mismatch':
+    case 'repo_mismatch':
+    case 'base_mismatch':
+    case 'head_mismatch':
+    case 'grant_does_not_cover_path':
+    case 'grant_bound_elsewhere':
+    case 'receipt_envelope_mismatch':
+    case 'artifact_mismatch':
+    case 'grant_unbound':
+    case 'grant_wrong_audience':
+      return DENY_ERROR.GRANT_MISMATCH;
+
+    default:
+      return null;
+  }
+}
+
+module.exports = { buildDenyRemedy, denyErrorForReason, DENY_ERROR, DOES_NOT_PROMISE, ARGS_SHAPE };

package/src/index.js

@@ -0,0 +1,216 @@
+'use strict';
+
+/**
+ * @coderifts/capability-express — requireExecutionGrant()
+ *
+ * An Express middleware that refuses a mutation unless the request carries a
+ * cr.exec.v1 execution grant that verifies OFFLINE against a PINNED Ed25519
+ * public key AND whose signed scope covers exactly this request.
+ *
+ * OFFLINE IS THE POINT. This middleware performs no network I/O at request time:
+ * no key fetch, no CodeRifts call, no registry lookup. Unplugging the network does
+ * not change a single verdict. The key is supplied once at construction, from a PEM
+ * string or a keys file read at startup.
+ *
+ * HEADER NAME. docs/cr-exec-v1.md specifies the token format and the verification
+ * algorithm but is SILENT on HTTP transport. This middleware defines
+ *   CodeRifts-Execution-Grant: <token>
+ * as the REFERENCE CONVENTION for cr.exec.v1 over HTTP. It is established here,
+ * not measured from the spec. Override with the `header` option.
+ *
+ * BINDING RULE (this middleware's contract; see README § Binding rule):
+ *   after_payload := the RAW request body bytes, exactly as received
+ * The request body IS the after-payload. Byte-for-byte: a 1-byte change to the body
+ * produces a different scope_hash and a 403 GRANT_SCOPE_MISMATCH. Reordering JSON
+ * keys is a byte change and therefore also fails — the grant binds bytes, not meaning.
+ *
+ * SCOPE. Enforcement is per-adapter. Mounting this on a route proves something about
+ * that route only. It makes no claim about any other path into the same data.
+ */
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const { verifyExecutionGrant, computeScopeHash } = require('./verify-grant');
+const { buildDenyRemedy, denyErrorForReason } = require('./deny-remedy.js');
+
+/** Reference convention established by this package (spec is silent on transport). */
+const DEFAULT_HEADER = 'coderifts-execution-grant';
+
+/**
+ * Express body parser that ALSO retains the raw bytes.
+ *
+ * The binding rule hashes what arrived on the wire, so the raw buffer must be kept
+ * before any JSON round-trip. `express.json({ verify })` would also work; this keeps
+ * the demo dependency-light and makes the captured bytes explicit.
+ *
+ * Sets `req.rawBody` (Buffer) and, for JSON content, `req.body`.
+ * @param {{ limit?: number }} [opts]
+ */
+function captureRawBody(opts = {}) {
+  const limit = Number.isFinite(opts.limit) ? opts.limit : 1_048_576;
+  return function rawBodyMiddleware(req, res, next) {
+    const chunks = [];
+    let size = 0;
+    let done = false;
+    const finish = (err) => {
+      if (done) return;
+      done = true;
+      if (err) return next(err);
+      req.rawBody = Buffer.concat(chunks);
+      const ct = String(req.headers['content-type'] || '');
+      if (req.rawBody.length && ct.includes('application/json')) {
+        try { req.body = JSON.parse(req.rawBody.toString('utf8')); } catch (_) { req.body = undefined; }
+      } else if (!req.rawBody.length) {
+        req.body = undefined;
+      }
+      next();
+    };
+    req.on('data', (c) => {
+      size += c.length;
+      if (size > limit) {
+        res.status(413).json({ error: 'payload_too_large', status: 'MALFORMED', reason: 'body_limit' });
+        done = true;
+        req.destroy();
+        return;
+      }
+      chunks.push(c);
+    });
+    req.on('end', () => finish());
+    req.on('error', finish);
+  };
+}
+
+function loadPublicKey({ publicKeyPem, keysFile, kid }) {
+  if (publicKeyPem) {
+    return { publicKey: crypto.createPublicKey(publicKeyPem), kid: kid || null, status: 'active' };
+  }
+  if (keysFile) {
+    // Same registry SHAPE as .well-known/coderifts-keys.json, read from disk at
+    // STARTUP. A URL is intentionally not accepted: request-time fetching would
+    // break the offline guarantee this middleware exists to demonstrate.
+    const doc = JSON.parse(fs.readFileSync(keysFile, 'utf8'));
+    const keys = doc && Array.isArray(doc.keys) ? doc.keys : null;
+    if (!keys || keys.length === 0) throw new Error(`requireExecutionGrant: no keys[] in ${keysFile}`);
+    const entry = kid ? keys.find((k) => k.kid === kid) : keys.find((k) => (k.status || 'active') === 'active');
+    if (!entry) throw new Error(`requireExecutionGrant: no usable key in ${keysFile}${kid ? ` for kid ${kid}` : ''}`);
+    if (!entry.public_key_pem) throw new Error(`requireExecutionGrant: entry ${entry.kid} has no public_key_pem`);
+    return {
+      publicKey: crypto.createPublicKey(entry.public_key_pem),
+      kid: entry.kid || null,
+      status: entry.status || 'active',
+    };
+  }
+  throw new Error('requireExecutionGrant: publicKeyPem or keysFile is required');
+}
+
+/**
+ * Build the guard.
+ *
+ * @param {object} options
+ * @param {string} [options.publicKeyPem]  pinned Ed25519 SPKI PEM (this or keysFile)
+ * @param {string} [options.keysFile]      path to a coderifts-keys.json-shaped file (read at startup)
+ * @param {string} [options.kid]           require this exact kid
+ * @param {string} [options.audience]      required audience; '' / omitted = unbound (not checked)
+ * @param {Record<string,string>} [options.operationMap]
+ *        'METHOD /route/path' -> operation, e.g. { 'POST /articles': 'publish' }.
+ *        Keys use the Express route pattern (req.route.path), not the concrete URL.
+ *        A request with no mapping is REFUSED (fail-closed), never allowed through.
+ * @param {(req: import('express').Request) => string} [options.targetId]
+ *        Resolve target_id. Default: req.params.id ?? '' — configure for other shapes.
+ * @param {string} [options.header]        header name; default CodeRifts-Execution-Grant
+ * @param {() => number} [options.now]     clock injection (tests)
+ * @returns {import('express').RequestHandler}
+ */
+function requireExecutionGrant(options = {}) {
+  const {
+    publicKeyPem, keysFile, kid, audience,
+    operationMap = {},
+    targetId = (req) => (req.params && req.params.id != null ? String(req.params.id) : ''),
+    header = DEFAULT_HEADER,
+    now,
+  } = options;
+
+  // Resolved ONCE at construction. No request-time key I/O, ever.
+  const pinned = loadPublicKey({ publicKeyPem, keysFile, kid });
+  const headerName = String(header).toLowerCase();
+
+  // The 403 body, plus the next step when the caller can act on one.
+  //
+  // `error`, `status` and `reason` are byte-identical to what this returned
+  // before the remedy existed; the remedy is an additive key. The error class is
+  // decided by the CALLER of deny, not derived here, because one refusal on this
+  // surface — an unmapped route — is not something a grant can fix, and mapping
+  // it by its status would send the caller to mint a grant that still gets 403.
+  const deny = (res, status, reason, remedy = null) => res.status(403).json({
+    error: 'execution_grant_required', status, reason, ...(remedy ? { remedy } : {}),
+  });
+
+  // The request line is this surface's own addressing for what it refused.
+  const targetOf = (req, routePath) => `${req.method} ${routePath}`;
+
+  return function executionGrantGuard(req, res, next) {
+    const routePath = (req.route && req.route.path) || req.path;
+    const operation = operationMap[`${req.method} ${routePath}`];
+    if (!operation) {
+      // Fail closed: an unmapped mutation is not an authorized mutation.
+      // NO remedy: this route has no operation to authorize, so no grant the
+      // caller could obtain would change this answer. An unactionable refusal is
+      // reported as unactionable.
+      return deny(res, 'GRANT_SCOPE_MISMATCH', 'unmapped_operation');
+    }
+
+    // The binding rule: the raw request body IS the after-payload.
+    const afterPayload = req.rawBody != null ? req.rawBody.toString('utf8') : '';
+    // The scope hash of the request being refused — the same value a grant for
+    // this request would have to carry, so the caller can match it.
+    const scope = computeScopeHash({ operation, target_id: targetId(req), after_payload: afterPayload });
+
+    const token = req.headers[headerName];
+    if (!token || typeof token !== 'string') {
+      return deny(res, 'MALFORMED', 'missing_grant_header', buildDenyRemedy({
+        error: denyErrorForReason('missing_grant_header'),
+        target: targetOf(req, routePath),
+        fingerprint: scope,
+        observed: { status: 'MALFORMED', reason: 'missing_grant_header' },
+      }));
+    }
+
+    const result = verifyExecutionGrant(token, {
+      publicKey: pinned.publicKey,
+      keyKid: pinned.kid,
+      keyStatus: pinned.status,
+      now: typeof now === 'function' ? now() : undefined,
+      intended: {
+        audience: audience || '',
+        operation,
+        target_id: targetId(req),
+        after_payload: afterPayload,
+      },
+    });
+
+    if (!result.valid) {
+      // The specific reason first; its status is the fallback, so a new reason
+      // string still lands in the right class rather than silently losing its
+      // remedy. A reason and a status that both fall outside the three classes
+      // produce no remedy at all.
+      const error = denyErrorForReason(result.reason) || denyErrorForReason(result.status);
+      return deny(res, result.status, result.reason, buildDenyRemedy({
+        error,
+        target: targetOf(req, routePath),
+        fingerprint: scope,
+        observed: { status: result.status, reason: result.reason },
+      }));
+    }
+
+    req.coderifts = { payload: result.payload };
+    return next();
+  };
+}
+
+module.exports = {
+  requireExecutionGrant,
+  captureRawBody,
+  computeScopeHash,
+  verifyExecutionGrant,
+  DEFAULT_HEADER,
+};

package/src/verify-grant.js

@@ -0,0 +1,267 @@
+'use strict';
+
+/**
+ * cr.exec.v1 OFFLINE grant verifier.
+ *
+ * Logic shape mirrors the reference implementation
+ * (coderifts-app src/verdict-core/execution-grant.js) and the 10-step algorithm in
+ * coderifts-app docs/cr-exec-v1.md § "Verification algorithm". Statuses and reason
+ * strings are IDENTICAL to that family — this file adds no status of its own.
+ *
+ * Differences from the reference, all deliberate for a standalone enforcement point:
+ *   - keys come from a PINNED public key (PEM string or a keys file), never from a
+ *     network lookup. There is no resolveVerifyKey() and no registry fetch: the
+ *     middleware must behave identically with the network unplugged.
+ *   - a pinned key with status 'retired' is refused (UNKNOWN_KEY / retired_kid),
+ *     matching spec step 4: a grant is live execution permission, so retired keys
+ *     never yield GRANT_CURRENT.
+ *
+ * Dependency-free: node:crypto only.
+ */
+
+const crypto = require('node:crypto');
+
+const GRANT_VERSION = 'cr.exec.v1';
+const SIGNING_PREFIX = 'crexec.v1';
+
+/**
+ * Field separator in the scope_hash preimage.
+ * docs/cr-exec-v1.md § Derivation specifies \x1f (the reference calls the constant
+ * NUL, but the byte it uses is 0x1F — Unit Separator; the byte, not the name, is
+ * normative and is what we reproduce).
+ */
+const US = '\x1f';
+
+/** ID104 verification leeway. `exp + leeway < now` → expired. Same 30s as receipts. */
+const CLOCK_SKEW_LEEWAY_MS = 30_000;
+
+const SIGNED_FIELDS = Object.freeze([
+  'kid', 'receipt_digest', 'scope_hash', 'audience', 'operation', 'target_id', 'jti', 'iat', 'exp',
+]);
+
+/**
+ * ATOMIC-profile field (docs/cr-exec-v1.md § Profiles). Optional and additive:
+ * present  → ATOMIC (one-use consumption is the EXECUTOR's job — see demo/src/db.js)
+ * absent   → BEARER (today's grant, unchanged)
+ * It is a SEPARATE signed field and is deliberately NOT folded into scope_hash:
+ * after-payload binding and state binding are independent facts, so rotating a nonce
+ * must not look like a different after-shape.
+ */
+const OPTIONAL_SIGNED_FIELDS = Object.freeze(['state_nonce', 'deployment_id']);
+
+function sha256hex(str) {
+  return crypto.createHash('sha256').update(String(str), 'utf8').digest('hex');
+}
+
+function scalar(v) {
+  return v == null ? '' : String(v);
+}
+
+/**
+ * scope_hash preimage: operation \x1f target_id \x1f after_payload.
+ * @returns {string} 'sha256:'+hex
+ */
+function computeScopeHash({ operation, target_id, after_payload }) {
+  const preimage = [scalar(operation), scalar(target_id), scalar(after_payload)].join(US);
+  return `sha256:${sha256hex(preimage)}`;
+}
+
+/** sha256 of the receipt TOKEN STRING (not of any decoded body). */
+function receiptDigest(token) {
+  return `sha256:${sha256hex(String(token))}`;
+}
+
+function signingInput(body) {
+  const parts = [
+    SIGNING_PREFIX,
+    scalar(body.kid), scalar(body.receipt_digest), scalar(body.scope_hash),
+    scalar(body.audience), scalar(body.operation), scalar(body.target_id),
+    scalar(body.jti), scalar(body.iat), scalar(body.exp),
+  ];
+  // The |{state_nonce} slot is appended ONLY when non-empty, so a BEARER grant's
+  // signing input stays byte-identical to pre-ATOMIC issuances.
+  if (body.state_nonce != null && String(body.state_nonce).length > 0) {
+    parts.push(String(body.state_nonce));
+  }
+  // deployment_id is optional-additive (STEP 4). Appended only when present so
+  // grants issued before this field stay byte-identical.
+  if (body.deployment_id != null && String(body.deployment_id).length > 0) {
+    parts.push(String(body.deployment_id));
+  }
+  return parts.join('|');
+}
+
+/** ATOMIC iff a non-empty state_nonce is carried. */
+function grantProfile(payload) {
+  return payload && payload.state_nonce != null && String(payload.state_nonce).length > 0
+    ? 'ATOMIC' : 'BEARER';
+}
+
+function fieldHasDelimiter(body) {
+  for (const k of [...SIGNED_FIELDS, ...OPTIONAL_SIGNED_FIELDS]) {
+    if (typeof body[k] === 'string' && body[k].includes('|')) return true;
+  }
+  return false;
+}
+
+/** Steps 1-3 (structure / JSON / field presence / unknown keys). */
+function parseGrantToken(token) {
+  if (typeof token !== 'string' || token.length === 0) {
+    return { ok: false, status: 'MALFORMED', reason: 'malformed_structure' };
+  }
+  const segments = token.split('.');
+  if (segments.length !== 2 || segments.some((s) => !s)) {
+    return { ok: false, status: 'MALFORMED', reason: 'malformed_structure' };
+  }
+  let payload;
+  try {
+    payload = JSON.parse(Buffer.from(segments[0], 'base64url').toString('utf8'));
+  } catch (_) {
+    return { ok: false, status: 'MALFORMED', reason: 'bad_json' };
+  }
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    return { ok: false, status: 'MALFORMED', reason: 'bad_json' };
+  }
+  if (payload.v !== GRANT_VERSION) {
+    return { ok: false, status: 'MALFORMED', reason: 'unsupported_version', payload };
+  }
+  for (const k of SIGNED_FIELDS) {
+    if (typeof payload[k] !== 'string') {
+      return { ok: false, status: 'MALFORMED', reason: 'missing_field', payload };
+    }
+  }
+  for (const k of OPTIONAL_SIGNED_FIELDS) {
+    if (payload[k] !== undefined && typeof payload[k] !== 'string') {
+      return { ok: false, status: 'MALFORMED', reason: 'bad_optional', payload };
+    }
+  }
+  // Reserved keys (cnf, nbf, max_uses, …) are NOT accepted in this phase.
+  const allowed = new Set(['v', ...SIGNED_FIELDS, ...OPTIONAL_SIGNED_FIELDS]);
+  for (const k of Object.keys(payload)) {
+    if (!allowed.has(k)) {
+      return { ok: false, status: 'MALFORMED', reason: 'unknown_field', payload };
+    }
+  }
+  return { ok: true, payload, sig: segments[1] };
+}
+
+/**
+ * Offline verification, spec steps 1-10.
+ *
+ * @param {string} token
+ * @param {object} opts
+ * @param {import('node:crypto').KeyObject} opts.publicKey  PINNED key (required)
+ * @param {string} [opts.keyStatus]  'active' | 'retired' — retired refuses (step 4)
+ * @param {string} [opts.keyKid]     when set, payload.kid must equal it (step 4)
+ * @param {object} [opts.intended]   { operation, target_id, audience, after_payload, scope_hash, receipt_token }
+ * @param {number} [opts.now]        epoch ms
+ * @returns {{ valid: boolean, status: string, reason: string|null, payload?: object }}
+ */
+function verifyExecutionGrant(token, opts = {}) {
+  // 1-3
+  const parsed = parseGrantToken(token);
+  if (!parsed.ok) {
+    return { valid: false, status: parsed.status, reason: parsed.reason, payload: parsed.payload };
+  }
+  const payload = parsed.payload;
+  if (fieldHasDelimiter(payload)) {
+    return { valid: false, status: 'INVALID_SIGNATURE', reason: 'delimiter_in_field', payload };
+  }
+
+  // 4 — pinned key. No registry, no fetch: unknown kid / retired key never verifies.
+  if (!opts.publicKey) {
+    return { valid: false, status: 'UNKNOWN_KEY', reason: 'unknown_kid', payload };
+  }
+  if (opts.keyKid != null && opts.keyKid !== '' && payload.kid !== String(opts.keyKid)) {
+    return { valid: false, status: 'UNKNOWN_KEY', reason: 'unknown_kid', payload };
+  }
+  if (opts.keyStatus === 'retired') {
+    return { valid: false, status: 'UNKNOWN_KEY', reason: 'retired_kid', payload };
+  }
+
+  // 5
+  let ok = false;
+  try {
+    ok = crypto.verify(
+      null,
+      Buffer.from(signingInput(payload), 'utf8'),
+      opts.publicKey,
+      Buffer.from(parsed.sig, 'base64url'),
+    );
+  } catch (_) {
+    return { valid: false, status: 'INVALID_SIGNATURE', reason: 'signature_error', payload };
+  }
+  if (!ok) {
+    return { valid: false, status: 'INVALID_SIGNATURE', reason: 'signature_mismatch', payload };
+  }
+
+  // 6 — expiry with the same 30s leeway as receipt verification.
+  const now = Number.isFinite(opts.now) ? opts.now : Date.now();
+  const expMs = Date.parse(payload.exp);
+  const iatMs = Date.parse(payload.iat);
+  if (!Number.isFinite(expMs) || !Number.isFinite(iatMs)) {
+    return { valid: false, status: 'MALFORMED', reason: 'bad_timestamp', payload };
+  }
+  if (expMs + CLOCK_SKEW_LEEWAY_MS < now) {
+    return { valid: false, status: 'GRANT_EXPIRED', reason: 'expired', payload };
+  }
+  if (iatMs > now + CLOCK_SKEW_LEEWAY_MS) {
+    return { valid: false, status: 'GRANT_EXPIRED', reason: 'iat_in_future', payload };
+  }
+
+  // 7 — receipt binding.
+  if (!payload.receipt_digest || !payload.receipt_digest.startsWith('sha256:')) {
+    return { valid: false, status: 'GRANT_UNBOUND', reason: 'missing_receipt_digest', payload };
+  }
+  const intended = opts.intended && typeof opts.intended === 'object' ? opts.intended : {};
+  if (intended.receipt_token != null && String(intended.receipt_token).length > 0) {
+    if (receiptDigest(intended.receipt_token) !== payload.receipt_digest) {
+      return { valid: false, status: 'GRANT_UNBOUND', reason: 'receipt_digest_mismatch', payload };
+    }
+  }
+
+  // 8 — audience / operation / target.
+  if (intended.audience != null && intended.audience !== '' && payload.audience !== String(intended.audience)) {
+    return { valid: false, status: 'GRANT_WRONG_AUDIENCE', reason: 'audience_mismatch', payload };
+  }
+  if (intended.operation != null && intended.operation !== '' && payload.operation !== String(intended.operation)) {
+    return { valid: false, status: 'GRANT_SCOPE_MISMATCH', reason: 'operation_mismatch', payload };
+  }
+  if (intended.target_id != null && intended.target_id !== '' && payload.target_id !== String(intended.target_id)) {
+    return { valid: false, status: 'GRANT_SCOPE_MISMATCH', reason: 'target_mismatch', payload };
+  }
+
+  // 9 — recompute scope_hash from the after-payload about to be applied.
+  let expectedScope = null;
+  if (intended.scope_hash != null && String(intended.scope_hash).length > 0) {
+    expectedScope = String(intended.scope_hash);
+  } else if (intended.after_payload != null) {
+    expectedScope = computeScopeHash({
+      operation: intended.operation != null ? intended.operation : payload.operation,
+      target_id: intended.target_id != null ? intended.target_id : payload.target_id,
+      after_payload: intended.after_payload,
+    });
+  }
+  if (expectedScope != null && expectedScope !== payload.scope_hash) {
+    return { valid: false, status: 'GRANT_SCOPE_MISMATCH', reason: 'scope_hash_mismatch', payload };
+  }
+
+  // 10
+  return { valid: true, status: 'GRANT_CURRENT', reason: null, payload };
+}
+
+module.exports = {
+  GRANT_VERSION,
+  grantProfile,
+  OPTIONAL_SIGNED_FIELDS,
+  SIGNING_PREFIX,
+  CLOCK_SKEW_LEEWAY_MS,
+  SIGNED_FIELDS,
+  US,
+  sha256hex,
+  computeScopeHash,
+  receiptDigest,
+  signingInput,
+  parseGrantToken,
+  verifyExecutionGrant,
+};