npm - @dorigjo/besa - Versions diffs - 0.1.0-alpha.2 → 0.1.0-beta.5 - Mend

@dorigjo/besa 0.1.0-alpha.2 → 0.1.0-beta.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (22) hide show

package/README.md CHANGED Viewed

@@ -1,345 +1,312 @@
-# Besa
-Signed trust infrastructure for AI-agent tools.
-> **Alpha / developer preview — not production-ready.**
->
-> Besa is currently an early alpha (`0.1.0-alpha.0`). APIs, file formats, receipt formats, and behavior may change without notice.
->
-> Do not use Besa to protect production systems, production secrets, customer data, or real signing keys yet.
->
-> The key under `.besa/` is a local demo key.
-Besa signs MCP-style tool manifests, verifies them before use, admits or denies tool calls against policy, and issues signed tamper-evident receipts.
-Besa is the trust layer for AI-agent tools.
-## What it does
-* Signs tool manifests with Ed25519.
-* Verifies signed manifests before runtime use.
-* Allows or denies tool calls with reason codes.
-* Blocks destructive high-risk tools by default.
-* Tracks local per-tool usage with a mini ActionMeter.
-* Creates signed receipts for admission decisions.
-Flow:
-```text
-manifest.yaml -> sign -> verify -> admit -> receipt
-```
-## Why it matters
-AI agents increasingly call external tools, APIs, MCP servers, and internal systems.
-The important question is not only whether an agent can call a tool.
-The important questions are:
-* Which tool is the agent allowed to call?
-* Who signed the declared capability?
-* Has the manifest changed?
-* Was the call allowed or denied?
-* Is there a receipt proving the decision?
-Besa turns those answers into signed artifacts.
-## Quickstart
-Install dependencies:
-```bash
-npm install
-```
-Build:
-```bash
-npm run build
-```
-Run tests:
-```bash
-npm test
-```
-Run the smoke test:
-```bash
-npm run smoke
-```
-The smoke test runs the full CLI flow: build, load, sign, verify, admit allow, admit deny, and receipt creation.
-## CLI commands
-Load a manifest:
-```bash
-node dist/index.js load examples/manifest.yaml
-```
-Sign a manifest:
-```bash
-node dist/index.js sign examples/manifest.yaml
-```
-Verify a signed manifest:
-```bash
-node dist/index.js verify examples/manifest.signed.json
-```
-Admit a safe tool:
-```bash
-node dist/index.js admit examples/manifest.signed.json crm.lookup
-```
-Deny a dangerous tool:
-```bash
-node dist/index.js admit examples/manifest.signed.json crm.delete
-```
-Create a signed receipt:
-```bash
-node dist/index.js receipt crm.lookup
-```
-Expected behavior:
-* `crm.lookup` -> allow / `ALLOWED`
-* `crm.delete` -> deny / `RISK_BLOCKED`
-### Grant-aware admission (optional)
-Besa can scope a tool call to a specific agent. Add a `grants.yaml` listing which `agentId` may use which tools:
+<p align="center">
+  <img src="site/logo.svg" alt="" width="44" height="40" />
+</p>
+<h1 align="center">Besa</h1>
+<p align="center"><strong>Agent Action Receipts</strong></p>
+<p align="center">
+  The signed-receipt layer for AI-agent tool calls.
+</p>
+<p align="center">
+  <a href="https://github.com/dorigjo/besa/actions/workflows/ci.yml"><img src="https://github.com/dorigjo/besa/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <a href="https://www.npmjs.com/package/@dorigjo/besa"><img src="https://img.shields.io/npm/v/@dorigjo/besa" alt="npm" /></a>
+</p>
+---
+Besa creates cryptographic execution evidence for AI-agent tool calls. Every
+admission decision is signed. Every signed receipt is tamper-evident and
+independently verifiable.
+> **Beta.** `0.1.0-beta.5` is a public developer beta. Not yet production-ready.
+> Feedback and issues: [github.com/dorigjo/besa/issues](https://github.com/dorigjo/besa/issues).
+---
+## Trust flow
 ```
-grants:
-  - agentId: agent-alpha
-    tools:
-      - crm.lookup
+manifest.yaml
+  → besa sign              # sign the declared tools, capabilities, risks, scopes
+  → manifest.signed.json   # Ed25519-signed artifact
+  → besa trust add         # pin the publisher's public key
+  → besa verify            # verify signature against pinned trust anchor
+  → besa admit <tool>      # dry-run: check policy, capabilities, budget
+  → besa receipt <tool>    # enforce budget, issue signed receipt
+  → besa verify-receipt    # verify the receipt chain end-to-end
 ```
-Then pass `--agent` and `--grants` to `admit` or `receipt`:
+Every step produces a durable, verifiable artifact. The signed manifest, public
+key ID, manifest hash, admission decision, request hash, and signed receipt are
+all tamper-evident. Changing any field causes verification to fail.
+---
+## What works today
+- YAML + JSON manifest loading with strict schema validation
+- Ed25519 key generation; AES-256-GCM encrypted key storage with scrypt KDF
+- Whole-envelope Ed25519 signatures covering manifest, hash, key, algorithm, and timestamp
+- Explicit public-key trust anchors (active / retired / revoked)
+- Signed key-rotation proofs preserving forward trust continuity
+- Allow / deny decisions with machine-readable reason codes
+- Destructive high-risk tool blocking by default policy
+- ASCII-validated tool names (prevents Unicode homograph attacks)
+- Manifest-scoped call budgets with cross-process atomic file locking
+- Optional per-agent grant scoping
+- Signed, tamper-evident Agent Action Receipts
+- Receipt trust-chain verification
+- TypeScript SDK exports
+---
+## Install
+```bash
+npm install @dorigjo/besa
+```
+Pin the beta channel explicitly:
+```bash
+npm install @dorigjo/besa@beta
 ```
-node dist/index.js admit examples/manifest.signed.json crm.lookup --agent agent-alpha --grants examples/grants.yaml
+Set the key passphrase before any signing operation:
+```bash
+export BESA_KEY_PASSPHRASE="your-passphrase-at-least-16-bytes"
+```
+### Build from source
+```bash
+git clone https://github.com/dorigjo/besa
+cd besa
+npm ci
+npm run build
+```
+---
+## Quickstart
+```bash
+# Show available commands
+npx besa --help
+# Generate or load the local signing key
+npx besa keys
+# Validate the manifest (dry-run, no signing)
+npx besa load examples/manifest.yaml
+# Sign the manifest
+npx besa sign examples/manifest.yaml
+# Verify the signature
+npx besa verify examples/manifest.signed.json
+# Admission dry-run (does not consume budget)
+npx besa admit examples/manifest.signed.json crm.lookup   # → allow
+npx besa admit examples/manifest.signed.json crm.delete   # → deny RISK_BLOCKED
+# Issue a signed receipt (consumes budget)
+npx besa receipt crm.lookup examples/manifest.signed.json \
+  --request examples/request.json
+# Verify the receipt chain
+npx besa verify-receipt .besa/receipts/<id>.json \
+  examples/manifest.signed.json
+```
+### PowerShell
+```powershell
+$env:BESA_KEY_PASSPHRASE = "your-passphrase-at-least-16-bytes"
+npx besa keys
+npx besa sign examples/manifest.yaml
+npx besa verify examples/manifest.signed.json
+npx besa admit examples/manifest.signed.json crm.lookup
+npx besa receipt crm.lookup examples/manifest.signed.json `
+  --request examples/request.json
+$receipt = Get-ChildItem .\.besa\receipts\*.json |
+  Sort-Object LastWriteTime -Descending | Select-Object -First 1
+npx besa verify-receipt $receipt.FullName examples/manifest.signed.json
+```
+### Consumer trust (separate system)
+```bash
+# Pin the publisher's public key
+npx besa trust add examples/manifest.signed.json \
+  --trust consumer-trust.json
+# Verify against a pinned trust anchor (fails without it)
+npx besa verify examples/manifest.signed.json \
+  --trust consumer-trust.json
 ```
-- `--agent <id>`: the id of the calling agent.
-- `--grants <file>`: the grants file to check against.
-- If the agent is not granted the tool, admission is denied (`TOOL_NOT_GRANTED`, or `AGENT_NOT_FOUND` for an unknown agent), and the receipt records `agentId` and `grantReasonCode`.
-Grants are **optional and backward-compatible**: without `--grants`, admission behaves exactly as before.
-## Core concepts
-### Tool Manifest
-A YAML or JSON file that declares a tool server and its tools.
-Each tool has:
-* name
-* description
-* capability
-* risk
-* scopes
-* budgetLimit
-* inputSchema
-Capabilities:
-* read
-* write
-* destructive
-Risk levels:
-* low
-* medium
-* high
-### Signed Manifest
-A manifest signed with Ed25519.
-The signed manifest includes:
-* manifest
-* manifestHash
-* algorithm
-* publicKey
-* publicKeyId
-* signature
-* signedAt
-### Admission Decision
-Besa evaluates whether a tool call should be allowed or denied.
-Reason codes include:
-* `ALLOWED`
-* `TOOL_NOT_FOUND`
-* `RISK_BLOCKED`
-* `BUDGET_EXCEEDED`
-### Mini ActionMeter
-Besa tracks local call counts per tool.
-This allows simple budget enforcement through `budgetLimit`.
-### Signed Receipt
-A receipt proves what decision was made.
-A receipt includes:
-* receiptId
-* manifestHash
-* toolName
-* decision
-* reasonCode
-* timestamp
-* requestHash
-* publicKeyId
-* algorithm
-* signature
-## SDK usage
-Import Besa from the SDK:
-```ts
-import {
-  loadManifest,
-  generateKeyPair,
-  signManifest,
-  verifySignedManifest,
-  admit,
-  createReceipt,
-  verifyReceipt,
-} from "besa";
-```
-Basic flow:
-```ts
-const manifest = loadManifest("examples/manifest.yaml");
-const keypair = generateKeyPair();
-const signed = signManifest(manifest, keypair);
-const verified = verifySignedManifest(signed);
-if (!verified.valid) {
-  throw new Error(verified.reasonCode);
-}
-const decision = admit(signed, "crm.lookup");
-const receipt = createReceipt(signed, decision, keypair);
-const receiptResult = verifyReceipt(receipt);
-if (!receiptResult.valid) {
-  throw new Error(receiptResult.reasonCode);
-}
-```
-## Security
-Never commit `.besa/`.
-The `.besa/` folder contains local trust artifacts, including the Ed25519 private key.
-Ignored local artifacts:
-* `.besa/`
-* `.besa/key.json`
-* `.besa/meter.json`
-* `.besa/receipts/`
-* `examples/manifest.signed.json`
-The local key generated by this MVP is a demo key. Rotate keys before real usage.
-See:
-* [SECURITY.md](SECURITY.md)
-* [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md)
-## MVP limitations
-This is an MVP and alpha developer preview.
-Current limitations:
-* local key storage only
-* local JSON meter only
-* no hosted registry
-* no SaaS backend
-* no dashboard
-* no remote verifier API
-* no hosted receipts API
-* no distributed replay protection
-* no key rotation
-* no key revocation
-* one default policy
-Default policy:
-* destructive + high risk = denied
-## What Besa is not
-Besa is currently an alpha trust layer for AI-agent tool control and evidence.
-It is not:
-* a hosted SaaS
-* a dashboard or UI
-* a full MCP gateway
-* production key management
-* a compliance certification product
-* a replacement for identity, authorization, audit storage, or security monitoring
-* ready for production secrets or production systems
-## Release docs
-* [SECURITY.md](SECURITY.md) — security policy, key handling, and vulnerability reporting
-* [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md) — assets, threats, mitigations, and current MVP limitations
-* [docs/RELEASE_CHECKLIST.md](docs/RELEASE_CHECKLIST.md) — pre-release gates before tagging or publishing
-* [CHANGELOG.md](CHANGELOG.md) — notable changes by version
-## Roadmap
-Planned next layers:
-* hosted key management
-* remote verifier API
-* policy packs
-* MCP gateway integration
-* enterprise audit export
-* receipts API
-* usage-based ActionMeter
-* organization-level trust registry
-## Positioning
-Besa is signed trust infrastructure for AI-agent tools.
-It is not another chatbot.
-It is not another dashboard.
-It is a trust layer for agentic execution.
+### Key rotation
+```bash
+npx besa keys rotate
+npx besa trust apply .besa/rotations/<rotation>.json \
+  --trust consumer-trust.json
+npx besa sign examples/manifest.yaml   # re-sign under the new key
+```
+The previous key becomes `retired`: artifacts signed before rotation remain
+verifiable, but new admissions under that key are denied. `trust revoke`
+invalidates a key for all artifacts, current and historical.
+---
+## Commands
+| Command | Description |
+|---|---|
+| `besa keys` | Generate or display the local signing key |
+| `besa keys rotate` | Rotate to a new key, archive the previous |
+| `besa trust add <manifest>` | Pin the manifest's public key as a trust anchor |
+| `besa trust apply <rotation>` | Apply a signed rotation proof |
+| `besa trust revoke <key-id>` | Revoke a trust anchor |
+| `besa trust list` | List all trust anchors and their status |
+| `besa load <manifest>` | Validate a manifest without signing |
+| `besa sign <manifest>` | Sign a manifest |
+| `besa verify <manifest>` | Verify a signed manifest against the trust store |
+| `besa admit <manifest> <tool>` | Dry-run: check policy + budget |
+| `besa receipt <tool> <manifest>` | Enforce budget and issue a signed receipt |
+| `besa verify-receipt <receipt> <manifest>` | Verify the receipt trust chain |
+All commands accept `--trust <trust.json>` to use a consumer-side trust store.
+`admit` and `receipt` also accept `--agent <id> --grants <grants.yaml>`.
+---
+## Receipt artifact
+```json
+{
+  "receiptId": "rcpt_2d7942c7-8f70-4984-9c3f-24876acfd860",
+  "manifestHash": "ea7e9ca22d199f40281cdf9e5d6145440c6c7d6bfbe94157c4b1da5527054410",
+  "toolName": "crm.lookup",
+  "decision": "allow",
+  "reasonCode": "ALLOWED",
+  "timestamp": "2026-06-19T10:00:00.000Z",
+  "requestHash": "b27b80d1227c167a6fca199778645daa77d20a8087782fc48802d11d6281c920",
+  "publicKeyId": "f68668614543c4896cf8cee418492f1a4df1f1acdba8850f94728b8a94cf90fe",
+  "algorithm": "ed25519",
+  "signature": "<base64-ed25519-signature>"
+}
+```
+`publicKeyId` is the full SHA-256 fingerprint of the Ed25519 public key DER bytes.
+Changing any field causes `verify-receipt` to fail closed.
+---
+## Reason codes
+| Code | Meaning |
+|---|---|
+| `ALLOWED` | Tool call admitted |
+| `TOOL_NOT_FOUND` | Tool not declared in the signed manifest |
+| `RISK_BLOCKED` | Destructive high-risk tool blocked by policy |
+| `BUDGET_EXCEEDED` | Call count reached the manifest budget limit |
+| `TOOL_NOT_GRANTED` | Agent not granted access to this tool |
+| `AGENT_NOT_FOUND` | Agent ID not listed in the grant set |
+| `E_KEY_UNTRUSTED` | Signing key not in the trust store |
+| `E_KEY_RETIRED` | Key retired; new admissions under it are denied |
+| `E_KEY_REVOKED` | Key revoked; all operations denied |
+---
+## SDK
+```typescript
+import {
+  admit,
+  addTrustAnchor,
+  applyKeyRotation,
+  canonicalize,
+  checkTrustedKey,
+  createKeyRotation,
+  createReceipt,
+  generateKeyPair,
+  hashRequest,
+  loadManifest,
+  signManifest,
+  validateManifest,
+  validateReceipt,
+  verifyReceiptDetailed,
+  verifySignedManifest,
+  verifyTrustedSignedManifest,
+} from "@dorigjo/besa";
+```
+---
+## Security model
+Besa provides **tamper-evidence**, not secrecy.
+A signed manifest proves that the declared tool capabilities, scopes, risks, and
+metadata have not changed since signing. A signed receipt creates a
+tamper-evident record that a specific admission decision was made at a specific
+time under a specific key.
+**Cryptography:**
+- Ed25519 signatures (256-bit security) on the complete artifact envelope
+- AES-256-GCM key encryption at rest with scrypt KDF (N=32768, r=8, p=1)
+- SHA-256 manifest hashing and full 256-bit (64-hex-character) SHA-256 public key fingerprints
+- Domain-separated signature messages (`besa:<domain>:v1\0<canonical-json>`)
+- Timing-safe public key comparison via `crypto.timingSafeEqual`
+**Fail-closed behavior:**
+- Verification fails on any signature, hash, or key mismatch
+- Admission fails closed on invalid policy, manifest, or call count
+- Trust store rejects symlinks, unknown fields, and duplicate key IDs
+- Trust store paths must end in `.json`
+- Tool names are restricted to ASCII printable characters
+See [SECURITY.md](SECURITY.md) and [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md).
+---
+## Release gates
+```bash
+npm ci
+npm run build
+npm test          # 56 tests
+npm run smoke     # end-to-end trust flow
+npm run test:package
+npm pack --dry-run
+```
+---
+## Beta limitations
+- Local key storage only; no hosted key management or HSM integration
+- File-based meter and trust state; intended for single-host use
+- No distributed replay protection across machines or environments
+- No external trusted timestamp authority
+- No hosted verifier, receipt retention, or SIEM export
+- No production identity or multi-user authorization
+- No formal compliance certification (SOC 2, ISO 27001, EU AI Act)
+---
+## License
+[MIT](LICENSE)

package/dist/admit.d.ts CHANGED Viewed

@@ -4,15 +4,26 @@ export declare const REASON: {
     readonly TOOL_NOT_FOUND: "TOOL_NOT_FOUND";
     readonly RISK_BLOCKED: "RISK_BLOCKED";
     readonly BUDGET_EXCEEDED: "BUDGET_EXCEEDED";
+    readonly INVALID_MANIFEST: "INVALID_MANIFEST";
+    readonly INVALID_TOOL_NAME: "INVALID_TOOL_NAME";
+    readonly INVALID_CALL_COUNT: "INVALID_CALL_COUNT";
+    readonly INVALID_POLICY: "INVALID_POLICY";
 };
 export interface AdmissionPolicy {
     denyDestructiveHighRisk: boolean;
 }
 export declare const DEFAULT_POLICY: AdmissionPolicy;
 export type MeterState = Record<string, number>;
+export interface MeterLockOptions {
+    timeoutMs?: number;
+    staleMs?: number;
+    retryMs?: number;
+}
 export declare function findTool(manifest: Manifest, toolName: string): ToolDefinition | undefined;
 export declare function admit(manifest: Manifest, toolName: string, callCount: number, policy?: AdmissionPolicy): AdmissionDecision;
+export declare function meterKey(manifestHash: string, toolName: string): string;
 export declare function loadMeter(path: string): MeterState;
 export declare function saveMeter(path: string, state: MeterState): void;
-export declare function getCount(state: MeterState, toolName: string): number;
-export declare function increment(state: MeterState, toolName: string): MeterState;
+export declare function getCount(state: MeterState, key: string): number;
+export declare function increment(state: MeterState, key: string): MeterState;
+export declare function admitAndConsume(path: string, manifestHash: string, manifest: Manifest, toolName: string, policy?: AdmissionPolicy, lockOptions?: MeterLockOptions): AdmissionDecision;