@passioncode-ai/fabric-agent-adapter 0.10.0 → 0.11.1

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## 0.11.1 - 2026-10-12
+
+0.11.0 plus one fix. The `v0.11.0` tag was refused by the release's own validation and never published: on Node 22,
+the CI version, the Node kit accepted a forged delegation token signed "under" a small-order key. Node 26's
+`crypto.verify` refuses such keys, but Node 20 and 22 accept them with the same OpenSSL.
+
+### Security
+
+- **The Node kit refuses small-order Ed25519 keys itself** (`isSmallOrderKey`: libsodium's list, including the
+  non-canonical encodings, compared with the sign bit cleared), so `verifyDelegation` and `verifyApproval` no longer
+  depend on the Node version. Checked on Node 20, 22 and 26. The contract's own verifier uses `crypto.verify` the
+  same way and has the same exposure on Node before 26; the contract repository was told.
+
+## 0.11.0 - 2026-10-12 (tagged, never published; see 0.11.1)
+
+Contract DEC-0039, second part (FAA-20): a service built with the kit checks a delegation token and an operator's
+approval offline, in Python and in Node, with the same answers as the contract's own verifier at the pin
+(`8e49fbd`, unchanged).
+
+### Added
+
+- **`scripts/fabric_delegation.py` and `scripts/fabric-delegation.mjs`**: `verify_delegation` / `verifyDelegation`
+  (the eleven DL-13 checks in their order), `verify_approval` / `verifyApproval` (DL-18, the jti consumed last),
+  `read_delegation_token` / `readDelegationToken` (`Fabric-Delegation` first, then a delegation-typ Bearer),
+  `jcs` and `action_digest` / `actionDigest` (RFC 8785), the jti stores (`MemoryJtiStore` / `createMemoryJtiStore`,
+  `FileJtiStore`, `UNSAFE_NO_JTI_STORE`), `JwksCache` (DL-15: at most 10 minutes, an unknown `kid` re-read at most
+  once a minute, 10 s between failed reads, no redirects), `delegation_gate` / `delegationGate`, and the DL-19
+  refusal shapes `refusal_tool_result` / `refusalToolResult` and `refusal_http` / `refusalHttp`.
+- **The Python kit verifies Ed25519 itself** (standard library only): RFC 8032, cofactorless, and as strict as
+  OpenSSL. `S` must be below the group order, points must be canonical, and small-order keys are refused.
+- **`McpToolServer(authorize=)`**: the gate runs before every tool; `ctx.delegation` carries the principal, caller
+  and chain. A job records who started it, and `fabric.job.get` / `fabric.job.cancel` answer only that principal
+  and caller, with a token that still covers the job's capability.
+- **Shared vectors** `test/fixtures/delegation/vectors.json` (66 delegation, 15 approval, 8 header, 5 JCS, 2 digest
+  and 330 Ed25519 cases), produced by `make_vectors.mjs`. Every expected answer comes from the contract's verifier
+  or from OpenSSL. Both kits' tests run over them.
+- `references/delegation.md`; `surfaces-and-auth.md` and `protocol.md` no longer say the kits do not verify. Scenario
+  evals `mcp-auth-delegation` (updated) and `approval-before-an-external-effect` came first.
+
+### Security
+
+- An independent review of the port found, before release:
+  - The Python Ed25519 verifier accepted forged signatures under a small-order key.
+  - A nested token with a duplicate member crashed the gate on Python 3.9–3.11.
+  - An unreadable jti file allowed approvals to be replayed.
+  - The key-set fetch followed redirects.
+  - The job tools were ungated.
+
+  All are fixed, and each has a test that failed first. The small-order forgery is now in the shared vectors.
+
 ## 0.10.0 - 2026-10-11
 
 Contract DEC-0039, first part (FAA-20, issue #52): the operator's dashboard session now lives no longer than

package/README.md

@@ -229,8 +229,8 @@ FABRIC_CONTRACT_OLD=/path/to/legacy-contract FABRIC_CONTRACT_NEW=/path/to/curren
 ```
 
 Without both environment variables, those tests explicitly skip as `NOT_RUN`.
-This source checkout is 0.10.0. 0.9.0 is the latest published GitHub/npm release (2026-10-11; 0.7.0 was never
-released); 0.10.0 is published by its `v0.10.0` tag. Source delivery does not update installed skills or live sessions.
+This source checkout is 0.11.1. 0.10.0 is the latest published GitHub/npm release (2026-10-11; 0.7.0 and 0.11.0
+were never released); 0.11.1 is published by its `v0.11.1` tag. Source delivery does not update installed skills or live sessions.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@passioncode-ai/fabric-agent-adapter",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "description": "Create Fabric-compatible agents, run them as always-alive local services with dashboards (fabric-service/0.1), and adapt existing projects to the Fabric Agent Contract. This package is the installer CLI.",
   "scripts": {
     "test": "python3 test/validate.py && python3 -m unittest discover -s test -q && node --test 'test/*.test.mjs'"

package/plugins/fabric-agent-adapter/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "fabric-agent-adapter",
   "displayName": "Fabric Agent Adapter",
   "description": "Create new Fabric-compatible agents, build them as always-alive local services with dashboards (fabric-service/0.1), and adapt existing projects to the Fabric Agent Contract through evidence-backed MCP, A2A, or local-runner provider bundles.",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "author": {
     "name": "PassionCode.ai",
     "url": "https://passioncode.ai/"

package/plugins/fabric-agent-adapter/skills/adapting-projects-to-fabric/SKILL.md

@@ -5,7 +5,7 @@ license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 compatibility: Requires filesystem access and Python 3.9+. Exact schema checks additionally need git, Node.js, pnpm, and the pinned fabric-agent-contract checkout (a public repository). Works without those tools in an explicitly degraded structural-check mode.
 metadata:
   author: PassionCode.ai
-  version: "0.10.0"
+  version: "0.11.1"
   contract-version: "0.1.0"
   contract-commit: "8e49fbd5fbbf230e32c1969cd24ac3c22422f0a5"
 ---

package/plugins/fabric-agent-adapter/skills/building-fabric-services/SKILL.md

@@ -16,7 +16,7 @@ license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 compatibility: Python 3.9+ or Node.js 20+ for the kits; the probe needs Python 3.9+. launchd steps are macOS-only (Linux services use lifecycle manager none until a systemd adapter exists). Dashboard handoff optionally uses Fabric Dashboards MCP link/host_status/open; without it, report unresolved host capability. The contract checkout is optional.
 metadata:
   author: PassionCode.ai
-  version: "0.10.0"
+  version: "0.11.1"
   contract-version: "0.1.0"
   extension: "fabric-service/0.1"
   extension-commit: "8e49fbd5fbbf230e32c1969cd24ac3c22422f0a5"
@@ -80,7 +80,10 @@ each manifest capability is the tool of its name, long work is a job with a stab
 a question for a person is an elicitation, and every call carries one trace. Read
 [the interop reference](references/interop.md) before writing an MCP tool; the helpers
 are in [`scripts/fabric_interop.py`](scripts/fabric_interop.py) and
-[`scripts/fabric-interop.mjs`](scripts/fabric-interop.mjs).
+[`scripts/fabric-interop.mjs`](scripts/fabric-interop.mjs). When the callers are agents of the estate, the
+service checks each call's delegation token (DEC-0039): read [the delegation reference](references/delegation.md);
+the verifier is [`scripts/fabric_delegation.py`](scripts/fabric_delegation.py) /
+[`scripts/fabric-delegation.mjs`](scripts/fabric-delegation.mjs).
 
 ## Step 2 — the non-negotiables
 

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/delegation.md

@@ -0,0 +1,84 @@
+# Delegation — checking who acts for whom (DEC-0039)
+
+A service that other agents of the estate call checks each call offline with the kit's verifier: the estate hub
+signs a delegation token naming the person (`sub`), the actor chain (`act`), this service (`aud`), the
+capabilities (`scope`) and the effect ceiling (`effect`); the service checks the signature against the estate's
+published keys and answers `ok` or one refusal code. Contract: `docs/specification/delegation.md` (DL-1…DL-19)
+at the pin. Python: [`scripts/fabric_delegation.py`](../scripts/fabric_delegation.py); Node:
+[`scripts/fabric-delegation.mjs`](../scripts/fabric-delegation.mjs). Both answer the shared vectors exactly as the
+contract's own verifier does.
+
+## Contents
+
+- Declaring it
+- Wiring the gate
+- Approvals
+- What a refusal looks like
+- Keys and the cache
+- What the kit does not do
+
+## Declaring it
+
+In the well-known document: `surfaces.mcp.auth: "delegation"` (only delegation tokens) and
+`auth.delegation: {issuer, jwks}` — the `iss` you trust (`urn:fabric:estate:<id>`) and where the key set is read.
+The descriptor's token stays the host's: it is never a caller's credential on `/mcp` (DL-12). The probe checks
+the declaration (`auth.delegation-declared`) and that `/mcp` refuses the descriptor token.
+
+## Wiring the gate
+
+```python
+import fabric_delegation as fd, fabric_interop as fi
+keys = fd.JwksCache(well_known["auth"]["delegation"]["jwks"])          # https, loopback http, or a file
+gate = fd.delegation_gate(audience="example-agent", jwks=keys, issuer=well_known["auth"]["delegation"]["issuer"],
+                          effects={"example.write": "draft", "example.publish": "publish"})   # each tool's manifest effect
+server = fi.McpToolServer("example-agent", VERSION, authorize=gate)    # pass the request headers to handle()
+# in a handler: ctx.delegation["principal"], ["caller"], ["chain"] — record the chain with the work
+```
+
+```js
+import { JwksCache, delegationGate, refusalToolResult } from './fabric-delegation.mjs';
+const gate = delegationGate({ audience: 'example-agent', jwks: new JwksCache(wk.auth.delegation.jwks), issuer: wk.auth.delegation.issuer,
+  effects: { 'example.write': 'draft' } });
+const verdict = await gate(params.name, req.headers);
+if (!verdict.ok) return refusalToolResult(verdict);
+```
+
+The token is read from `Fabric-Delegation` first (a forwarded call; present but empty is refused, never skipped),
+then from `Authorization: Bearer` when the bearer is a delegation JWT (DL-9, DL-10). A tool with no declared
+effect is refused (`unknown-state`), never guessed. The checks run in the DL-13 order; nothing about a token is
+believed before its signature. The built-in job tools (`fabric.job.get`, `fabric.job.cancel`) are gated too: by the
+job's own capability and effect, and only for the principal and caller that started the job (another caller is
+`scope-not-granted`); `on_input` gets the checked delegation on its context. Start jobs with `ctx.start_job()` so the
+job records who started it.
+
+## Approvals
+
+An action with an external effect may need the operator's approval (DL-17, DL-18). The order is fixed: the token,
+then the grant check where there is one, then `verify_approval` / `verifyApproval`, which consumes the approval's
+`jti` last, then the action. Without an approval, answer `approval-required` with
+`action_digest(action)` / `actionDigest(action)` — the SHA-256 of the action's RFC 8785 form (`jcs`) — so the caller
+can ask the hub. Keep consumed ids in `FileJtiStore` (0600, survives a restart); `MemoryJtiStore` is for tests
+and `UNSAFE_NO_JTI_STORE` exists only by name. No store at all, or a store file that cannot be read, is
+`unknown-state` — never a pass.
+
+## What a refusal looks like
+
+DL-19: an MCP tool answers `refusal_tool_result(r)` / `refusalToolResult(r)` — `isError: true` and
+`structuredContent: {error: {code, message, data: {detail}}}`; an HTTP route answers `refusal_http(r)` /
+`refusalHttp(r)` with the code's status (401 for `unauthenticated`, `token-expired`, `principal-unproven`, with
+`WWW-Authenticate: Bearer error="invalid_token"`; 503 for `issuer-unavailable` and `unknown-state`; 403 for the
+rest). `detail` is a short machine word; the token, the approval and the keys never appear in a result or a log.
+
+## Keys and the cache
+
+`JwksCache` holds the estate's key set at most 10 minutes and, on a `kid` it does not hold, re-reads at most once
+a minute (DL-15), and waits 10 s after a failed read before trying again; after 10 minutes without a successful read it answers nothing, and the verifier says
+`issuer-unavailable`. It reads https, http on loopback only, or a file; a URL with credentials is refused. The
+Python kit verifies Ed25519 itself (RFC 8032, standard library only, strict as OpenSSL: `S` below the group order,
+canonical points, no small-order key); it follows no redirect when it reads the key set; the Node kit uses `node:crypto` and refuses small-order keys
+itself (`isSmallOrderKey`), because Node before 26 lets OpenSSL accept a signature under one.
+
+## What the kit does not do
+
+It does not mint tokens, check attenuation against a parent (the issuer's rule, DL-5), check a grant or a spend
+window (the meter's, DL-21), or decide which actions need an approval — the service decides that.

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/protocol.md

@@ -72,7 +72,7 @@ No auth; the Host/Origin guard applies; answered from memory in under 100 ms.
   the MCP surface takes only the estate's delegation tokens, and the top-level
   `auth.delegation {issuer, jwks}` is then required. With `own` or `delegation` the descriptor's
   token is not an MCP credential: a host and the probe never call `/mcp` with it as a caller.
-  The kits do not verify delegation tokens yet (a later FAA-20 release).
+  The kits verify them with `fabric_delegation` / `fabric-delegation.mjs` ([delegation](delegation.md)).
 
 ## Events page — `GET /fabric/v1/events?after=<cursor>&limit=<n>`
 

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/surfaces-and-auth.md

@@ -15,8 +15,8 @@
 - **Delegation (DEC-0039, DL-16).** `surfaces.mcp.auth: "delegation"` means `/mcp` takes only
   the estate's delegation tokens; declare `auth.delegation {issuer, jwks}` in the well-known
   document. The probe treats it like `own` and checks the declaration
-  (`auth.delegation-declared`). The kits do not verify the tokens yet; until they do, name what
-  checks them.
+  (`auth.delegation-declared`). The kits verify the tokens: put `delegation_gate` /
+  `delegationGate` in front of the tools — see [the delegation reference](delegation.md).
 - Register it into a client config with the service's own command
   (`<tool> mcp-register`), which writes `{"type":"http","url":"http://127.0.0.1:<port>/mcp","headers":{...}}`
   atomically, aborts if the file changed meanwhile, and keeps one 0600 backup. The token