@dorigjo/besa 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dorigjo
+
+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,345 @@
+# 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:
+
+```
+grants:
+  - agentId: agent-alpha
+    tools:
+      - crm.lookup
+```
+
+Then pass `--agent` and `--grants` to `admit` or `receipt`:
+
+```
+node dist/index.js admit examples/manifest.signed.json crm.lookup --agent agent-alpha --grants examples/grants.yaml
+```
+
+- `--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.

package/dist/admit.d.ts

@@ -0,0 +1,18 @@
+import type { AdmissionDecision, Manifest, ToolDefinition } from "./types.js";
+export declare const REASON: {
+    readonly ALLOWED: "ALLOWED";
+    readonly TOOL_NOT_FOUND: "TOOL_NOT_FOUND";
+    readonly RISK_BLOCKED: "RISK_BLOCKED";
+    readonly BUDGET_EXCEEDED: "BUDGET_EXCEEDED";
+};
+export interface AdmissionPolicy {
+    denyDestructiveHighRisk: boolean;
+}
+export declare const DEFAULT_POLICY: AdmissionPolicy;
+export type MeterState = Record<string, 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 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;

package/dist/admit.js

@@ -0,0 +1,76 @@
+import { dirname } from "node:path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+export const REASON = {
+    ALLOWED: "ALLOWED",
+    TOOL_NOT_FOUND: "TOOL_NOT_FOUND",
+    RISK_BLOCKED: "RISK_BLOCKED",
+    BUDGET_EXCEEDED: "BUDGET_EXCEEDED"
+};
+export const DEFAULT_POLICY = {
+    denyDestructiveHighRisk: true
+};
+export function findTool(manifest, toolName) {
+    return manifest.tools.find((tool) => tool.name === toolName);
+}
+export function admit(manifest, toolName, callCount, policy = DEFAULT_POLICY) {
+    const tool = findTool(manifest, toolName);
+    if (!tool) {
+        return deny(toolName, REASON.TOOL_NOT_FOUND, `tool '${toolName}' is not declared in the manifest`);
+    }
+    if (policy.denyDestructiveHighRisk &&
+        tool.capability === "destructive" &&
+        tool.risk === "high") {
+        return deny(toolName, REASON.RISK_BLOCKED, "destructive high-risk tool is blocked by policy");
+    }
+    if (callCount >= tool.budgetLimit) {
+        return deny(toolName, REASON.BUDGET_EXCEEDED, `call count ${callCount} has reached budget limit ${tool.budgetLimit}`);
+    }
+    return {
+        decision: "allow",
+        reasonCode: REASON.ALLOWED,
+        toolName,
+        detail: "tool call admitted"
+    };
+}
+function deny(toolName, reasonCode, detail) {
+    return {
+        decision: "deny",
+        reasonCode,
+        toolName,
+        detail
+    };
+}
+export function loadMeter(path) {
+    if (!existsSync(path)) {
+        return {};
+    }
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+            return {};
+        }
+        const state = {};
+        for (const [key, value] of Object.entries(raw)) {
+            if (typeof value === "number" && Number.isInteger(value) && value >= 0) {
+                state[key] = value;
+            }
+        }
+        return state;
+    }
+    catch {
+        return {};
+    }
+}
+export function saveMeter(path, state) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(state, null, 2) + "\n", "utf8");
+}
+export function getCount(state, toolName) {
+    return state[toolName] ?? 0;
+}
+export function increment(state, toolName) {
+    return {
+        ...state,
+        [toolName]: getCount(state, toolName) + 1
+    };
+}

package/dist/crypto.d.ts

@@ -0,0 +1,12 @@
+import { type KeyObject } from "node:crypto";
+export interface KeyPair {
+    publicKeyDer: string;
+    privateKeyDer: string;
+}
+export declare function canonicalize(value: unknown): string;
+export declare function sha256Hex(data: string): string;
+export declare function hashObject(value: unknown): string;
+export declare function generateKeyPair(): KeyPair;
+export declare function publicKeyFromDer(publicKeyDer: string): KeyObject;
+export declare function privateKeyFromDer(privateKeyDer: string): KeyObject;
+export declare function publicKeyId(publicKeyDer: string): string;

package/dist/crypto.js

@@ -0,0 +1,48 @@
+import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync } from "node:crypto";
+function sortValue(value) {
+    if (Array.isArray(value)) {
+        return value.map(sortValue);
+    }
+    if (value !== null && typeof value === "object") {
+        const input = value;
+        const output = {};
+        for (const key of Object.keys(input).sort()) {
+            output[key] = sortValue(input[key]);
+        }
+        return output;
+    }
+    return value;
+}
+export function canonicalize(value) {
+    return JSON.stringify(sortValue(value));
+}
+export function sha256Hex(data) {
+    return createHash("sha256").update(data, "utf8").digest("hex");
+}
+export function hashObject(value) {
+    return sha256Hex(canonicalize(value));
+}
+export function generateKeyPair() {
+    const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+    return {
+        publicKeyDer: publicKey.export({ type: "spki", format: "der" }).toString("base64"),
+        privateKeyDer: privateKey.export({ type: "pkcs8", format: "der" }).toString("base64")
+    };
+}
+export function publicKeyFromDer(publicKeyDer) {
+    return createPublicKey({
+        key: Buffer.from(publicKeyDer, "base64"),
+        type: "spki",
+        format: "der"
+    });
+}
+export function privateKeyFromDer(privateKeyDer) {
+    return createPrivateKey({
+        key: Buffer.from(privateKeyDer, "base64"),
+        type: "pkcs8",
+        format: "der"
+    });
+}
+export function publicKeyId(publicKeyDer) {
+    return sha256Hex(publicKeyDer).slice(0, 16);
+}

package/dist/grant.d.ts

@@ -0,0 +1,15 @@
+import type { Grant, GrantDecision, GrantSet } from "./types.js";
+export declare const GRANT_REASON: {
+    readonly GRANTED: "GRANT_OK";
+    readonly AGENT_NOT_FOUND: "AGENT_NOT_FOUND";
+    readonly TOOL_NOT_GRANTED: "TOOL_NOT_GRANTED";
+};
+export interface GrantValidationResult {
+    ok: boolean;
+    grantSet?: GrantSet;
+    errors: string[];
+}
+export declare function validateGrantSet(raw: unknown): GrantValidationResult;
+export declare function loadGrants(path: string): GrantSet;
+export declare function findGrant(grantSet: GrantSet, agentId: string): Grant | undefined;
+export declare function checkGrant(grantSet: GrantSet, agentId: string, toolName: string): GrantDecision;

package/dist/grant.js

@@ -0,0 +1,101 @@
+import { readFileSync } from "node:fs";
+import { extname } from "node:path";
+import { parse as parseYaml } from "yaml";
+export const GRANT_REASON = {
+    GRANTED: "GRANT_OK",
+    AGENT_NOT_FOUND: "AGENT_NOT_FOUND",
+    TOOL_NOT_GRANTED: "TOOL_NOT_GRANTED",
+};
+function isObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+export function validateGrantSet(raw) {
+    const errors = [];
+    if (!isObject(raw)) {
+        return {
+            ok: false,
+            errors: ["grant set must be an object"],
+        };
+    }
+    if (!Array.isArray(raw.grants) || raw.grants.length === 0) {
+        errors.push("grants must be a non-empty array");
+    }
+    else {
+        const seenAgents = new Set();
+        raw.grants.forEach((grant, index) => {
+            const path = `grants[${index}]`;
+            if (!isObject(grant)) {
+                errors.push(`${path} must be an object`);
+                return;
+            }
+            if (!isNonEmptyString(grant.agentId)) {
+                errors.push(`${path}.agentId must be a non-empty string`);
+            }
+            else if (seenAgents.has(grant.agentId)) {
+                errors.push(`${path}.agentId must be unique`);
+            }
+            else {
+                seenAgents.add(grant.agentId);
+            }
+            if (!Array.isArray(grant.tools) ||
+                grant.tools.length === 0 ||
+                !grant.tools.every((tool) => isNonEmptyString(tool))) {
+                errors.push(`${path}.tools must be a non-empty array of non-empty strings`);
+            }
+        });
+    }
+    if (errors.length > 0) {
+        return {
+            ok: false,
+            errors,
+        };
+    }
+    return {
+        ok: true,
+        grantSet: raw,
+        errors: [],
+    };
+}
+export function loadGrants(path) {
+    const source = readFileSync(path, "utf8");
+    const raw = extname(path).toLowerCase() === ".json" ? JSON.parse(source) : parseYaml(source);
+    const result = validateGrantSet(raw);
+    if (!result.ok || !result.grantSet) {
+        throw new Error(`Invalid grant set:\n  - ${result.errors.join("\n  - ")}`);
+    }
+    return result.grantSet;
+}
+export function findGrant(grantSet, agentId) {
+    return grantSet.grants.find((grant) => grant.agentId === agentId);
+}
+export function checkGrant(grantSet, agentId, toolName) {
+    const grant = findGrant(grantSet, agentId);
+    if (!grant) {
+        return {
+            granted: false,
+            reasonCode: GRANT_REASON.AGENT_NOT_FOUND,
+            agentId,
+            toolName,
+            detail: `no grant found for agent '${agentId}'`,
+        };
+    }
+    if (!grant.tools.includes(toolName)) {
+        return {
+            granted: false,
+            reasonCode: GRANT_REASON.TOOL_NOT_GRANTED,
+            agentId,
+            toolName,
+            detail: `agent '${agentId}' is not granted tool '${toolName}'`,
+        };
+    }
+    return {
+        granted: true,
+        reasonCode: GRANT_REASON.GRANTED,
+        agentId,
+        toolName,
+        detail: `agent '${agentId}' is granted tool '${toolName}'`,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import type { AdmissionDecision } from "./types.js";
+export declare function grantGate(toolName: string): AdmissionDecision | undefined;

package/dist/index.js

@@ -0,0 +1,285 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { generateKeyPair } from "./crypto.js";
+import { loadManifest } from "./manifest.js";
+import { createReceipt, signManifest, verifySignedManifest } from "./signing.js";
+import { admit, getCount, increment, loadMeter, saveMeter } from "./admit.js";
+import { checkGrant, loadGrants } from "./grant.js";
+const BESA_DIR = ".besa";
+const KEY_PATH = join(BESA_DIR, "key.json");
+const METER_PATH = join(BESA_DIR, "meter.json");
+const ACTIVE_MANIFEST_PATH = join(BESA_DIR, "active-manifest.json");
+const RECEIPTS_DIR = join(BESA_DIR, "receipts");
+function readJson(path) {
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+function writeJson(path, value) {
+    writeFileSync(path, JSON.stringify(value, null, 2) + "\n", "utf8");
+}
+function ensureBesaDir() {
+    mkdirSync(BESA_DIR, { recursive: true });
+}
+function loadOrCreateKeyPair() {
+    ensureBesaDir();
+    if (existsSync(KEY_PATH)) {
+        return readJson(KEY_PATH);
+    }
+    const keypair = generateKeyPair();
+    writeJson(KEY_PATH, keypair);
+    return keypair;
+}
+function printJson(label, value) {
+    console.log("");
+    console.log(label + ":");
+    console.log(JSON.stringify(value, null, 2));
+}
+function signedOutPath(manifestPath) {
+    if (manifestPath.endsWith(".yaml")) {
+        return manifestPath.slice(0, -5) + ".signed.json";
+    }
+    if (manifestPath.endsWith(".yml")) {
+        return manifestPath.slice(0, -4) + ".signed.json";
+    }
+    if (manifestPath.endsWith(".json")) {
+        return manifestPath.slice(0, -5) + ".signed.json";
+    }
+    return manifestPath + ".signed.json";
+}
+function flagValue(name) {
+    const index = process.argv.indexOf(name);
+    return index >= 0 ? process.argv[index + 1] : undefined;
+}
+function positionals(args) {
+    const values = [];
+    const flagsWithValues = new Set(["--agent", "--grants"]);
+    for (let index = 0; index < args.length; index += 1) {
+        const value = args[index];
+        if (value && flagsWithValues.has(value)) {
+            index += 1;
+            continue;
+        }
+        if (value) {
+            values.push(value);
+        }
+    }
+    return values;
+}
+function cmdKeys() {
+    const keypair = loadOrCreateKeyPair();
+    printJson("keypair", {
+        publicKeyDer: keypair.publicKeyDer,
+        privateKeyDerPath: KEY_PATH,
+    });
+    console.log("");
+    console.log("OK: keypair ready at " + KEY_PATH);
+}
+function cmdLoad(file) {
+    const manifest = loadManifest(file);
+    printJson("manifest", manifest);
+    console.log("");
+    console.log("OK: loaded " + String(manifest.tools.length) + " tool(s) from " + file);
+}
+function cmdSign(file) {
+    const manifest = loadManifest(file);
+    const keypair = loadOrCreateKeyPair();
+    const signed = signManifest(manifest, keypair);
+    const out = signedOutPath(file);
+    writeJson(out, signed);
+    ensureBesaDir();
+    writeJson(ACTIVE_MANIFEST_PATH, signed);
+    printJson("signedManifest", signed);
+    console.log("");
+    console.log("OK: signed -> " + out + " with publicKeyId " + signed.publicKeyId);
+}
+function cmdVerify(file) {
+    const signed = readJson(file);
+    const result = verifySignedManifest(signed);
+    printJson("verify", result);
+    if (!result.valid) {
+        process.exitCode = 1;
+        console.log("");
+        console.log("DENY: " + result.reasonCode);
+        return;
+    }
+    console.log("");
+    console.log("OK: " + result.detail);
+}
+function denyFromVerification(toolName, reasonCode, detail) {
+    return {
+        decision: "deny",
+        reasonCode,
+        toolName,
+        detail,
+    };
+}
+export function grantGate(toolName) {
+    const grantsPath = flagValue("--grants");
+    if (!grantsPath) {
+        return undefined;
+    }
+    const agentId = flagValue("--agent") ?? "";
+    const grant = checkGrant(loadGrants(grantsPath), agentId, toolName);
+    return {
+        decision: grant.granted ? "allow" : "deny",
+        reasonCode: grant.reasonCode,
+        toolName,
+        detail: grant.detail,
+        agentId,
+    };
+}
+function cmdAdmit(file, toolName) {
+    const signed = readJson(file);
+    const verified = verifySignedManifest(signed);
+    if (!verified.valid) {
+        const denied = denyFromVerification(toolName, verified.reasonCode, verified.detail);
+        printJson("admission", denied);
+        process.exitCode = 1;
+        return;
+    }
+    const grantDecision = grantGate(toolName);
+    if (grantDecision && grantDecision.decision === "deny") {
+        printJson("admission", grantDecision);
+        process.exitCode = 1;
+        return;
+    }
+    const meter = loadMeter(METER_PATH);
+    const count = getCount(meter, toolName);
+    const decision = admit(signed.manifest, toolName, count);
+    if (grantDecision?.agentId) {
+        decision.agentId = grantDecision.agentId;
+    }
+    printJson("admission", decision);
+    if (decision.decision === "deny") {
+        process.exitCode = 1;
+    }
+}
+function cmdReceipt(toolName, file) {
+    const signedPath = file ?? ACTIVE_MANIFEST_PATH;
+    if (!existsSync(signedPath)) {
+        throw new Error("no signed manifest found at " + signedPath + "; run besa sign <manifest> first");
+    }
+    const signed = readJson(signedPath);
+    const keypair = loadOrCreateKeyPair();
+    const verified = verifySignedManifest(signed);
+    let decision;
+    let grantReasonCode;
+    if (!verified.valid) {
+        decision = denyFromVerification(toolName, verified.reasonCode, verified.detail);
+    }
+    else {
+        const grantDecision = grantGate(toolName);
+        grantReasonCode = grantDecision?.reasonCode;
+        if (grantDecision && grantDecision.decision === "deny") {
+            decision = grantDecision;
+        }
+        else {
+            const meter = loadMeter(METER_PATH);
+            decision = admit(signed.manifest, toolName, getCount(meter, toolName));
+            if (grantDecision?.agentId) {
+                decision.agentId = grantDecision.agentId;
+            }
+            if (decision.decision === "allow") {
+                saveMeter(METER_PATH, increment(meter, toolName));
+            }
+        }
+    }
+    const receipt = createReceipt({
+        manifestHash: signed.manifestHash,
+        toolName,
+        decision: decision.decision,
+        reasonCode: decision.reasonCode,
+        request: {
+            toolName,
+            signedManifest: signedPath,
+        },
+        agentId: decision.agentId,
+        grantReasonCode,
+    }, keypair);
+    mkdirSync(RECEIPTS_DIR, { recursive: true });
+    const receiptPath = join(RECEIPTS_DIR, receipt.receiptId + ".json");
+    writeJson(receiptPath, receipt);
+    printJson("receipt", receipt);
+    console.log("");
+    console.log(decision.decision.toUpperCase() + ": " + decision.reasonCode + " -> " + receiptPath);
+    if (decision.decision === "deny") {
+        process.exitCode = 1;
+    }
+}
+function usage() {
+    console.log([
+        "Besa - signed trust infrastructure for AI-agent tools",
+        "",
+        "Usage:",
+        "  besa keys",
+        "  besa load    <manifest.yaml>",
+        "  besa sign    <manifest.yaml>",
+        "  besa verify  <manifest.signed.json>",
+        "  besa admit   <manifest.signed.json> <tool-name> [--agent <agent-id> --grants <grants.yaml>]",
+        "  besa receipt <tool-name> [manifest.signed.json] [--agent <agent-id> --grants <grants.yaml>]",
+        "",
+        "Examples:",
+        "  besa keys",
+        "  besa load examples/manifest.yaml",
+        "  besa sign examples/manifest.yaml",
+        "  besa verify examples/manifest.signed.json",
+        "  besa admit examples/manifest.signed.json crm.lookup",
+        "  besa admit examples/manifest.signed.json crm.lookup --agent agent-alpha --grants examples/grants.yaml",
+        "  besa admit examples/manifest.signed.json crm.delete --agent agent-alpha --grants examples/grants.yaml",
+        "  besa receipt crm.lookup examples/manifest.signed.json",
+        "  besa receipt crm.lookup examples/manifest.signed.json --agent agent-alpha --grants examples/grants.yaml",
+    ].join("\n"));
+}
+function requireArgs(args, expected, command) {
+    if (args.length < expected) {
+        throw new Error(command + " requires " + String(expected) + " argument(s)");
+    }
+}
+function main(argv) {
+    const command = argv[0] ?? "";
+    const args = positionals(argv.slice(1));
+    try {
+        switch (command) {
+            case "keys":
+                cmdKeys();
+                break;
+            case "load":
+                requireArgs(args, 1, command);
+                cmdLoad(args[0] ?? "");
+                break;
+            case "sign":
+                requireArgs(args, 1, command);
+                cmdSign(args[0] ?? "");
+                break;
+            case "verify":
+                requireArgs(args, 1, command);
+                cmdVerify(args[0] ?? "");
+                break;
+            case "admit":
+                requireArgs(args, 2, command);
+                cmdAdmit(args[0] ?? "", args[1] ?? "");
+                break;
+            case "receipt":
+                requireArgs(args, 1, command);
+                cmdReceipt(args[0] ?? "", args[1]);
+                break;
+            case "":
+            case "help":
+            case "--help":
+            case "-h":
+                usage();
+                break;
+            default:
+                console.error("Unknown command: " + command);
+                usage();
+                process.exitCode = 1;
+                break;
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error("Error: " + message);
+        process.exitCode = 1;
+    }
+}
+main(process.argv.slice(2));

package/dist/manifest.d.ts

@@ -0,0 +1,8 @@
+import type { Manifest } from "./types.js";
+export interface ValidationResult {
+    ok: boolean;
+    manifest?: Manifest;
+    errors: string[];
+}
+export declare function validateManifest(raw: unknown): ValidationResult;
+export declare function loadManifest(path: string): Manifest;

package/dist/manifest.js

@@ -0,0 +1,106 @@
+import { readFileSync } from "node:fs";
+import { extname } from "node:path";
+import { parse as parseYaml } from "yaml";
+const CAPABILITIES = ["read", "write", "destructive"];
+const RISKS = ["low", "medium", "high"];
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
+function isObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function isHttpUrl(value) {
+    if (typeof value !== "string")
+        return false;
+    try {
+        const url = new URL(value);
+        return url.protocol === "http:" || url.protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+function isIsoDate(value) {
+    return (typeof value === "string" &&
+        ISO_DATE.test(value) &&
+        !Number.isNaN(Date.parse(value)));
+}
+export function validateManifest(raw) {
+    const errors = [];
+    if (!isObject(raw)) {
+        return { ok: false, errors: ["manifest must be an object"] };
+    }
+    if (!isNonEmptyString(raw.serverName)) {
+        errors.push("serverName must be a non-empty string");
+    }
+    if (!isNonEmptyString(raw.serverVersion)) {
+        errors.push("serverVersion must be a non-empty string");
+    }
+    if (!isHttpUrl(raw.serverUrl)) {
+        errors.push("serverUrl must be a valid http(s) URL");
+    }
+    if (!isIsoDate(raw.createdAt)) {
+        errors.push("createdAt must be a valid ISO-8601 date-time");
+    }
+    if (!Array.isArray(raw.tools) || raw.tools.length === 0) {
+        errors.push("tools must be a non-empty array");
+    }
+    else {
+        const seen = new Set();
+        raw.tools.forEach((tool, index) => {
+            validateTool(tool, index, errors);
+            if (isObject(tool) && typeof tool.name === "string") {
+                if (seen.has(tool.name)) {
+                    errors.push(`tools[${index}].name '${tool.name}' is a duplicate tool name`);
+                }
+                seen.add(tool.name);
+            }
+        });
+    }
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    return { ok: true, manifest: raw, errors: [] };
+}
+function validateTool(tool, index, errors) {
+    const path = `tools[${index}]`;
+    if (!isObject(tool)) {
+        errors.push(`${path} must be an object`);
+        return;
+    }
+    if (!isNonEmptyString(tool.name)) {
+        errors.push(`${path}.name must be a non-empty string`);
+    }
+    if (typeof tool.description !== "string") {
+        errors.push(`${path}.description must be a string`);
+    }
+    if (!CAPABILITIES.includes(tool.capability)) {
+        errors.push(`${path}.capability must be one of ${CAPABILITIES.join(", ")}`);
+    }
+    if (!RISKS.includes(tool.risk)) {
+        errors.push(`${path}.risk must be one of ${RISKS.join(", ")}`);
+    }
+    if (!Array.isArray(tool.scopes) ||
+        tool.scopes.length === 0 ||
+        !tool.scopes.every((scope) => isNonEmptyString(scope))) {
+        errors.push(`${path}.scopes must be a non-empty array of non-empty strings`);
+    }
+    if (typeof tool.budgetLimit !== "number" ||
+        !Number.isSafeInteger(tool.budgetLimit) ||
+        tool.budgetLimit < 0) {
+        errors.push(`${path}.budgetLimit must be a safe non-negative integer`);
+    }
+    if (!isObject(tool.inputSchema)) {
+        errors.push(`${path}.inputSchema must be an object`);
+    }
+}
+export function loadManifest(path) {
+    const source = readFileSync(path, "utf8");
+    const raw = extname(path) === ".json" ? JSON.parse(source) : parseYaml(source);
+    const result = validateManifest(raw);
+    if (!result.ok || !result.manifest) {
+        throw new Error(`Invalid manifest:\n  - ${result.errors.join("\n  - ")}`);
+    }
+    return result.manifest;
+}

package/dist/sdk.d.ts

@@ -0,0 +1,6 @@
+export * from "./types.js";
+export * from "./crypto.js";
+export * from "./manifest.js";
+export * from "./signing.js";
+export * from "./admit.js";
+export * from "./grant.js";

package/dist/sdk.js

@@ -0,0 +1,6 @@
+export * from "./types.js";
+export * from "./crypto.js";
+export * from "./manifest.js";
+export * from "./signing.js";
+export * from "./admit.js";
+export * from "./grant.js";

package/dist/signing.d.ts

@@ -0,0 +1,21 @@
+import type { Decision, Manifest, Receipt, SignedManifest } from "./types.js";
+import { type KeyPair } from "./crypto.js";
+export interface VerifyResult {
+    valid: boolean;
+    reasonCode: string;
+    detail: string;
+}
+export interface ReceiptInput {
+    manifestHash: string;
+    toolName: string;
+    decision: Decision;
+    reasonCode: string;
+    request: unknown;
+    agentId?: string;
+    grantReasonCode?: string;
+}
+export declare function hashManifest(manifest: Manifest): string;
+export declare function signManifest(manifest: Manifest, keypair: KeyPair): SignedManifest;
+export declare function verifySignedManifest(signed: SignedManifest): VerifyResult;
+export declare function createReceipt(input: ReceiptInput, keypair: KeyPair): Receipt;
+export declare function verifyReceipt(receipt: Receipt, publicKeyDer: string): boolean;

package/dist/signing.js

@@ -0,0 +1,100 @@
+import { randomUUID, sign as ed25519Sign, verify as ed25519Verify } from "node:crypto";
+import { canonicalize, hashObject, privateKeyFromDer, publicKeyFromDer, publicKeyId } from "./crypto.js";
+export function hashManifest(manifest) {
+    return hashObject(manifest);
+}
+export function signManifest(manifest, keypair) {
+    const canonical = canonicalize(manifest);
+    const signature = ed25519Sign(null, Buffer.from(canonical, "utf8"), privateKeyFromDer(keypair.privateKeyDer));
+    return {
+        manifest,
+        manifestHash: hashManifest(manifest),
+        algorithm: "ed25519",
+        publicKey: keypair.publicKeyDer,
+        publicKeyId: publicKeyId(keypair.publicKeyDer),
+        signature: signature.toString("base64"),
+        signedAt: new Date().toISOString()
+    };
+}
+export function verifySignedManifest(signed) {
+    if (signed.algorithm !== "ed25519") {
+        return {
+            valid: false,
+            reasonCode: "E_ALGORITHM_UNSUPPORTED",
+            detail: "only ed25519 signed manifests are supported"
+        };
+    }
+    const canonical = canonicalize(signed.manifest);
+    const expectedHash = hashManifest(signed.manifest);
+    if (expectedHash !== signed.manifestHash) {
+        return {
+            valid: false,
+            reasonCode: "E_MANIFEST_HASH_MISMATCH",
+            detail: "manifest content does not match stored hash"
+        };
+    }
+    if (publicKeyId(signed.publicKey) !== signed.publicKeyId) {
+        return {
+            valid: false,
+            reasonCode: "E_PUBLIC_KEY_ID_MISMATCH",
+            detail: "publicKeyId does not match publicKey"
+        };
+    }
+    try {
+        const valid = ed25519Verify(null, Buffer.from(canonical, "utf8"), publicKeyFromDer(signed.publicKey), Buffer.from(signed.signature, "base64"));
+        if (!valid) {
+            return {
+                valid: false,
+                reasonCode: "E_SIGNATURE_INVALID",
+                detail: "signature does not verify against the public key"
+            };
+        }
+        return {
+            valid: true,
+            reasonCode: "OK",
+            detail: "manifest signature is valid"
+        };
+    }
+    catch {
+        return {
+            valid: false,
+            reasonCode: "E_SIGNATURE_CHECK_FAILED",
+            detail: "signature verification failed"
+        };
+    }
+}
+export function createReceipt(input, keypair) {
+    const body = {
+        receiptId: "rcpt_" + randomUUID(),
+        manifestHash: input.manifestHash,
+        toolName: input.toolName,
+        decision: input.decision,
+        reasonCode: input.reasonCode,
+        timestamp: new Date().toISOString(),
+        requestHash: hashObject(input.request ?? {}),
+        agentId: input.agentId,
+        grantReasonCode: input.grantReasonCode,
+        publicKeyId: publicKeyId(keypair.publicKeyDer),
+        algorithm: "ed25519"
+    };
+    const signature = ed25519Sign(null, Buffer.from(canonicalize(body), "utf8"), privateKeyFromDer(keypair.privateKeyDer));
+    return {
+        ...body,
+        signature: signature.toString("base64")
+    };
+}
+export function verifyReceipt(receipt, publicKeyDer) {
+    if (receipt.algorithm !== "ed25519") {
+        return false;
+    }
+    if (publicKeyId(publicKeyDer) !== receipt.publicKeyId) {
+        return false;
+    }
+    const { signature, ...body } = receipt;
+    try {
+        return ed25519Verify(null, Buffer.from(canonicalize(body), "utf8"), publicKeyFromDer(publicKeyDer), Buffer.from(signature, "base64"));
+    }
+    catch {
+        return false;
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,63 @@
+export type CapabilityType = "read" | "write" | "destructive";
+export type RiskLevel = "low" | "medium" | "high";
+export type Decision = "allow" | "deny";
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    capability: CapabilityType;
+    risk: RiskLevel;
+    scopes: string[];
+    budgetLimit: number;
+    inputSchema: Record<string, unknown>;
+}
+export interface Manifest {
+    serverName: string;
+    serverVersion: string;
+    serverUrl: string;
+    createdAt: string;
+    tools: ToolDefinition[];
+}
+export interface SignedManifest {
+    manifest: Manifest;
+    manifestHash: string;
+    algorithm: "ed25519";
+    publicKey: string;
+    publicKeyId: string;
+    signature: string;
+    signedAt: string;
+}
+export interface AdmissionDecision {
+    decision: Decision;
+    reasonCode: string;
+    toolName: string;
+    detail: string;
+    agentId?: string;
+}
+export interface Receipt {
+    receiptId: string;
+    manifestHash: string;
+    toolName: string;
+    decision: Decision;
+    reasonCode: string;
+    timestamp: string;
+    requestHash: string;
+    publicKeyId: string;
+    algorithm: "ed25519";
+    agentId?: string;
+    grantReasonCode?: string;
+    signature: string;
+}
+export interface Grant {
+    agentId: string;
+    tools: string[];
+}
+export interface GrantSet {
+    grants: Grant[];
+}
+export interface GrantDecision {
+    granted: boolean;
+    reasonCode: string;
+    agentId: string;
+    toolName: string;
+    detail: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/examples/grants.yaml

@@ -0,0 +1,4 @@
+grants:
+  - agentId: agent-alpha
+    tools:
+      - crm.lookup

package/examples/manifest.yaml

@@ -0,0 +1,34 @@
+serverName: acme-crm
+serverVersion: 1.0.0
+serverUrl: https://tools.acme.example/mcp
+createdAt: 2026-06-12T00:00:00Z
+tools:
+  - name: crm.lookup
+    description: Look up a customer record by id or email.
+    capability: read
+    risk: low
+    scopes:
+      - crm:read
+    budgetLimit: 100
+    inputSchema:
+      type: object
+      properties:
+        query:
+          type: string
+      required:
+        - query
+  - name: crm.delete
+    description: Permanently delete a customer record.
+    capability: destructive
+    risk: high
+    scopes:
+      - crm:write
+      - crm:admin
+    budgetLimit: 5
+    inputSchema:
+      type: object
+      properties:
+        id:
+          type: string
+      required:
+        - id

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@dorigjo/besa",
+  "version": "0.1.0-alpha.1",
+  "description": "Signed trust infrastructure for AI-agent tools.",
+  "type": "module",
+  "main": "./dist/sdk.js",
+  "types": "./dist/sdk.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/sdk.d.ts",
+      "default": "./dist/sdk.js"
+    }
+  },
+  "bin": {
+    "besa": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run build && node --test dist/tests/*.test.js",
+    "smoke": "node scripts/smoke.mjs"
+  },
+  "keywords": [
+    "mcp",
+    "ai-agents",
+    "trust",
+    "ed25519",
+    "signing",
+    "manifest",
+    "receipt"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dorigjo/besa.git"
+  },
+  "author": "dorigjo",
+  "license": "MIT",
+  "dependencies": {
+    "yaml": "^2.5.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.6.2"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist/*.js",
+    "dist/*.d.ts",
+    "examples/manifest.yaml",
+    "examples/grants.yaml"
+  ],
+  "bugs": {
+    "url": "https://github.com/dorigjo/besa/issues"
+  },
+  "homepage": "https://github.com/dorigjo/besa#readme"
+}