@dorigjo/besa 0.1.0-alpha.1 → 0.1.0-beta.4

package/dist/index.js

@@ -1,34 +1,149 @@
 #!/usr/bin/env node
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { generateKeyPair } from "./crypto.js";
+import { chmodSync, existsSync, lstatSync, mkdirSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { generateKeyPair, publicKeyId, validateKeyPair, } 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 { createReceipt, hashRequest, signManifest, validateReceipt, validateSignedManifest, verifyReceiptDetailed, verifySignedManifest, } from "./signing.js";
+import { admit, admitAndConsume, getCount, loadMeter, meterKey, } from "./admit.js";
 import { checkGrant, loadGrants } from "./grant.js";
+import { addTrustAnchor, applyKeyRotation, checkTrustedKey, createKeyRotation, emptyTrustStore, revokeTrustAnchor, validateTrustStore, verifyKeyRotation, verifyTrustedSignedManifest, } from "./trust.js";
+import { readJsonFile, writeJsonAtomic, writeJsonExclusive, } from "./io.js";
+import { isStoredKeyPair, openKeyPair, sealKeyPair, } from "./keystore.js";
 const BESA_DIR = ".besa";
 const KEY_PATH = join(BESA_DIR, "key.json");
+const KEYS_DIR = join(BESA_DIR, "keys");
 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");
+const ROTATIONS_DIR = join(BESA_DIR, "rotations");
+const TRUST_PATH = join(BESA_DIR, "trust.json");
+const FLAGS_WITH_VALUES = new Set([
+    "--agent",
+    "--grants",
+    "--request",
+    "--trust",
+]);
+const COMMAND_FLAGS = {
+    keys: new Set(["--trust"]),
+    trust: new Set(["--trust"]),
+    load: new Set(),
+    sign: new Set(["--trust"]),
+    verify: new Set(["--trust"]),
+    admit: new Set(["--trust", "--agent", "--grants"]),
+    receipt: new Set([
+        "--trust",
+        "--request",
+        "--agent",
+        "--grants",
+    ]),
+    "verify-receipt": new Set(["--trust"]),
+};
 function readJson(path) {
-    return JSON.parse(readFileSync(path, "utf8"));
+    return readJsonFile(path);
 }
-function writeJson(path, value) {
-    writeFileSync(path, JSON.stringify(value, null, 2) + "\n", "utf8");
+function writeJson(path, value, mode) {
+    writeJsonAtomic(path, value, mode ?? 0o600);
 }
 function ensureBesaDir() {
-    mkdirSync(BESA_DIR, { recursive: true });
+    mkdirSync(BESA_DIR, { recursive: true, mode: 0o700 });
+    const stats = lstatSync(BESA_DIR);
+    if (!stats.isDirectory() || stats.isSymbolicLink()) {
+        throw new Error(`${BESA_DIR} must be a real private directory, not a link`);
+    }
+    if (process.platform !== "win32")
+        chmodSync(BESA_DIR, 0o700);
+}
+function protectKeyFile(path = KEY_PATH) {
+    if (lstatSync(path).isSymbolicLink()) {
+        throw new Error(`refusing to use symbolic-link key file at ${path}`);
+    }
+    if (process.platform !== "win32")
+        chmodSync(path, 0o600);
+}
+function keyPassphrase() {
+    const passphrase = process.env.BESA_KEY_PASSPHRASE;
+    if (!passphrase) {
+        throw new Error("BESA_KEY_PASSPHRASE is required and must contain at least 16 UTF-8 bytes");
+    }
+    return passphrase;
+}
+function loadExistingKeyPair() {
+    if (!existsSync(KEY_PATH)) {
+        throw new Error(`no signing key found at ${KEY_PATH}; run besa keys first`);
+    }
+    ensureBesaDir();
+    protectKeyFile();
+    const stored = readJson(KEY_PATH);
+    const passphrase = keyPassphrase();
+    if (isStoredKeyPair(stored)) {
+        return openKeyPair(stored, passphrase);
+    }
+    if (!validateKeyPair(stored)) {
+        throw new Error(`invalid or mismatched Ed25519 key pair at ${KEY_PATH}`);
+    }
+    writeJson(KEY_PATH, sealKeyPair(stored, passphrase), 0o600);
+    return stored;
 }
 function loadOrCreateKeyPair() {
     ensureBesaDir();
     if (existsSync(KEY_PATH)) {
-        return readJson(KEY_PATH);
+        return loadExistingKeyPair();
     }
     const keypair = generateKeyPair();
-    writeJson(KEY_PATH, keypair);
+    try {
+        writeJsonExclusive(KEY_PATH, sealKeyPair(keypair, keyPassphrase()), 0o600);
+    }
+    catch (error) {
+        if (error.code === "EEXIST") {
+            return loadExistingKeyPair();
+        }
+        throw error;
+    }
+    protectKeyFile();
     return keypair;
 }
+function terminalText(value) {
+    return value.replace(/[\u0000-\u001f\u007f-\u009f]/g, "?");
+}
+function selectedTrustPath() {
+    const path = flagValue("--trust") ?? TRUST_PATH;
+    if (!path.endsWith(".json")) {
+        throw new Error(`trust store path must end in .json: ${terminalText(path)}`);
+    }
+    return path;
+}
+function loadTrustStore(path = selectedTrustPath()) {
+    if (!existsSync(path)) {
+        throw new Error(`no trust store found at ${path}; run besa trust add <signed-manifest> first`);
+    }
+    if (lstatSync(path).isSymbolicLink()) {
+        throw new Error(`refusing to use symbolic-link trust store at ${path}`);
+    }
+    const validation = validateTrustStore(readJson(path));
+    if (!validation.ok || !validation.trustStore) {
+        throw new Error(`invalid trust store at ${path}:\n  - ${validation.errors.join("\n  - ")}`);
+    }
+    return validation.trustStore;
+}
+function loadOrCreateTrustStore(path = selectedTrustPath()) {
+    return existsSync(path) ? loadTrustStore(path) : emptyTrustStore();
+}
+function saveTrustStore(store, path = selectedTrustPath()) {
+    if (existsSync(path) && lstatSync(path).isSymbolicLink()) {
+        throw new Error(`refusing to write to symbolic-link trust store at ${path}`);
+    }
+    const validation = validateTrustStore(store);
+    if (!validation.ok) {
+        throw new Error(`refusing to save invalid trust store: ${validation.errors.join("; ")}`);
+    }
+    writeJson(path, store, 0o600);
+}
+function trustSignedManifestKey(signed) {
+    const path = selectedTrustPath();
+    const store = addTrustAnchor(loadOrCreateTrustStore(path), signed.publicKey);
+    saveTrustStore(store, path);
+}
 function printJson(label, value) {
     console.log("");
     console.log(label + ":");
@@ -48,14 +163,35 @@ function signedOutPath(manifestPath) {
 }
 function flagValue(name) {
     const index = process.argv.indexOf(name);
-    return index >= 0 ? process.argv[index + 1] : undefined;
+    if (index < 0) {
+        return undefined;
+    }
+    const value = process.argv[index + 1];
+    if (!value || value.startsWith("--")) {
+        throw new Error(`${name} requires a value`);
+    }
+    return value;
 }
-function positionals(args) {
+function positionals(args, allowedFlags) {
     const values = [];
-    const flagsWithValues = new Set(["--agent", "--grants"]);
+    const seenFlags = new Set();
     for (let index = 0; index < args.length; index += 1) {
         const value = args[index];
-        if (value && flagsWithValues.has(value)) {
+        if (value?.startsWith("-")) {
+            if (!FLAGS_WITH_VALUES.has(value)) {
+                throw new Error(`unknown flag '${value}'`);
+            }
+            if (!allowedFlags.has(value)) {
+                throw new Error(`flag '${value}' is not supported by this command`);
+            }
+            if (seenFlags.has(value)) {
+                throw new Error(`duplicate flag '${value}'`);
+            }
+            const flagArgument = args[index + 1];
+            if (!flagArgument || flagArgument.startsWith("--")) {
+                throw new Error(`${value} requires a value`);
+            }
+            seenFlags.add(value);
             index += 1;
             continue;
         }
@@ -65,7 +201,52 @@ function positionals(args) {
     }
     return values;
 }
-function cmdKeys() {
+function requireSignedManifest(value) {
+    const validation = validateSignedManifest(value);
+    if (!validation.ok || !validation.signedManifest) {
+        throw new Error(`invalid signed manifest:\n  - ${validation.errors.join("\n  - ")}`);
+    }
+    return validation.signedManifest;
+}
+function cmdRotateKeys() {
+    const previous = loadExistingKeyPair();
+    const next = generateKeyPair();
+    const rotation = createKeyRotation(previous, next);
+    const previousId = rotation.previousPublicKeyId;
+    const archivePath = join(KEYS_DIR, `${previousId}.json`);
+    const rotationPath = join(ROTATIONS_DIR, `${previousId}-to-${rotation.newPublicKeyId}.json`);
+    const path = selectedTrustPath();
+    const anchored = addTrustAnchor(loadOrCreateTrustStore(path), previous.publicKeyDer);
+    const rotatedStore = applyKeyRotation(anchored, rotation);
+    const passphrase = keyPassphrase();
+    // Pre-compute all crypto before touching the filesystem.
+    // If scrypt or key derivation throws, no files are written.
+    const sealedPrevious = sealKeyPair(previous, passphrase);
+    const sealedNext = sealKeyPair(next, passphrase);
+    writeJson(archivePath, sealedPrevious, 0o600);
+    protectKeyFile(archivePath);
+    writeJson(rotationPath, rotation);
+    writeJson(KEY_PATH, sealedNext, 0o600);
+    protectKeyFile();
+    saveTrustStore(rotatedStore, path);
+    printJson("keyRotation", rotation);
+    console.log("");
+    console.log(`OK: active key rotated to ${rotation.newPublicKeyId}`);
+    console.log(`OK: previous private key archived at ${terminalText(archivePath)}`);
+    console.log(`OK: rotation proof written to ${terminalText(rotationPath)}`);
+    console.log("NEXT: re-sign active manifests with the new key");
+}
+function cmdKeys(action) {
+    if (action === "rotate") {
+        cmdRotateKeys();
+        return;
+    }
+    if (action) {
+        throw new Error(`unknown keys action '${action}'`);
+    }
+    if (flagValue("--trust")) {
+        throw new Error("--trust is only supported by keys rotate");
+    }
     const keypair = loadOrCreateKeyPair();
     printJson("keypair", {
         publicKeyDer: keypair.publicKeyDer,
@@ -74,11 +255,77 @@ function cmdKeys() {
     console.log("");
     console.log("OK: keypair ready at " + KEY_PATH);
 }
+function cmdTrustAdd(file) {
+    const raw = readJson(file);
+    const verification = verifySignedManifest(raw);
+    if (!verification.valid) {
+        throw new Error(`${verification.reasonCode}: ${verification.detail}`);
+    }
+    const signed = requireSignedManifest(raw);
+    const path = selectedTrustPath();
+    const store = addTrustAnchor(loadOrCreateTrustStore(path), signed.publicKey);
+    saveTrustStore(store, path);
+    console.log(`OK: trusted public key ${signed.publicKeyId} in ${terminalText(path)}`);
+}
+function cmdTrustApply(file) {
+    const rotation = readJson(file);
+    const verification = verifyKeyRotation(rotation);
+    if (!verification.valid) {
+        throw new Error(`${verification.reasonCode}: ${verification.detail}`);
+    }
+    const path = selectedTrustPath();
+    const store = applyKeyRotation(loadTrustStore(path), rotation);
+    saveTrustStore(store, path);
+    console.log(`OK: retired ${rotation.previousPublicKeyId} and trusted ${rotation.newPublicKeyId}`);
+}
+function cmdTrustRevoke(keyId) {
+    const path = selectedTrustPath();
+    const store = revokeTrustAnchor(loadTrustStore(path), keyId);
+    saveTrustStore(store, path);
+    console.log(`OK: revoked public key ${keyId} in ${terminalText(path)}`);
+}
+function cmdTrustList() {
+    const path = selectedTrustPath();
+    const store = loadTrustStore(path);
+    printJson("trustStore", store);
+    console.log("");
+    console.log(`OK: loaded ${String(store.keys.length)} trust anchor(s) from ${terminalText(path)}`);
+}
+function cmdTrust(action, value) {
+    switch (action) {
+        case "add":
+            if (!value) {
+                throw new Error("trust add requires a signed manifest path");
+            }
+            cmdTrustAdd(value);
+            break;
+        case "apply":
+            if (!value) {
+                throw new Error("trust apply requires a key rotation path");
+            }
+            cmdTrustApply(value);
+            break;
+        case "revoke":
+            if (!value) {
+                throw new Error("trust revoke requires a public key id");
+            }
+            cmdTrustRevoke(value);
+            break;
+        case "list":
+            if (value) {
+                throw new Error("trust list does not accept a positional value");
+            }
+            cmdTrustList();
+            break;
+        default:
+            throw new Error(`unknown trust action '${action}'`);
+    }
+}
 function cmdLoad(file) {
     const manifest = loadManifest(file);
     printJson("manifest", manifest);
     console.log("");
-    console.log("OK: loaded " + String(manifest.tools.length) + " tool(s) from " + file);
+    console.log("OK: loaded " + String(manifest.tools.length) + " tool(s) from " + terminalText(file));
 }
 function cmdSign(file) {
     const manifest = loadManifest(file);
@@ -88,13 +335,15 @@ function cmdSign(file) {
     writeJson(out, signed);
     ensureBesaDir();
     writeJson(ACTIVE_MANIFEST_PATH, signed);
+    trustSignedManifestKey(signed);
     printJson("signedManifest", signed);
     console.log("");
-    console.log("OK: signed -> " + out + " with publicKeyId " + signed.publicKeyId);
+    console.log("OK: signed -> " + terminalText(out) + " with publicKeyId " + signed.publicKeyId);
+    console.log("OK: public key anchored in " + terminalText(selectedTrustPath()));
 }
 function cmdVerify(file) {
     const signed = readJson(file);
-    const result = verifySignedManifest(signed);
+    const result = verifyTrustedSignedManifest(signed, loadTrustStore());
     printJson("verify", result);
     if (!result.valid) {
         process.exitCode = 1;
@@ -115,11 +364,14 @@ function denyFromVerification(toolName, reasonCode, detail) {
 }
 export function grantGate(toolName) {
     const grantsPath = flagValue("--grants");
+    const agentId = flagValue("--agent");
+    if (Boolean(grantsPath) !== Boolean(agentId)) {
+        throw new Error("--agent and --grants must be provided together");
+    }
     if (!grantsPath) {
         return undefined;
     }
-    const agentId = flagValue("--agent") ?? "";
-    const grant = checkGrant(loadGrants(grantsPath), agentId, toolName);
+    const grant = checkGrant(loadGrants(grantsPath), agentId ?? "", toolName);
     return {
         decision: grant.granted ? "allow" : "deny",
         reasonCode: grant.reasonCode,
@@ -129,14 +381,15 @@ export function grantGate(toolName) {
     };
 }
 function cmdAdmit(file, toolName) {
-    const signed = readJson(file);
-    const verified = verifySignedManifest(signed);
+    const raw = readJson(file);
+    const verified = verifyTrustedSignedManifest(raw, loadTrustStore(), "admit");
     if (!verified.valid) {
         const denied = denyFromVerification(toolName, verified.reasonCode, verified.detail);
         printJson("admission", denied);
         process.exitCode = 1;
         return;
     }
+    const signed = requireSignedManifest(raw);
     const grantDecision = grantGate(toolName);
     if (grantDecision && grantDecision.decision === "deny") {
         printJson("admission", grantDecision);
@@ -144,24 +397,37 @@ function cmdAdmit(file, toolName) {
         return;
     }
     const meter = loadMeter(METER_PATH);
-    const count = getCount(meter, toolName);
-    const decision = admit(signed.manifest, toolName, count);
+    const key = meterKey(signed.manifestHash, toolName);
+    const decision = admit(signed.manifest, toolName, getCount(meter, key));
     if (grantDecision?.agentId) {
         decision.agentId = grantDecision.agentId;
     }
     printJson("admission", decision);
+    console.log("");
+    console.log("[dry-run: budget not consumed — use 'besa receipt' to enforce and record]");
     if (decision.decision === "deny") {
         process.exitCode = 1;
     }
 }
+function readRequest(toolName) {
+    const requestPath = flagValue("--request");
+    return requestPath ? readJson(requestPath) : { toolName };
+}
 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");
+        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);
+    const signed = requireSignedManifest(readJson(signedPath));
+    const keypair = loadExistingKeyPair();
+    const request = readRequest(toolName);
+    void hashRequest(request);
+    if (publicKeyId(keypair.publicKeyDer) !== signed.publicKeyId) {
+        throw new Error("local receipt key does not match the signed manifest publicKeyId");
+    }
+    const verified = verifyTrustedSignedManifest(signed, loadTrustStore(), "admit");
     let decision;
     let grantReasonCode;
     if (!verified.valid) {
@@ -174,14 +440,10 @@ function cmdReceipt(toolName, file) {
             decision = grantDecision;
         }
         else {
-            const meter = loadMeter(METER_PATH);
-            decision = admit(signed.manifest, toolName, getCount(meter, toolName));
+            decision = admitAndConsume(METER_PATH, signed.manifestHash, signed.manifest, toolName);
             if (grantDecision?.agentId) {
                 decision.agentId = grantDecision.agentId;
             }
-            if (decision.decision === "allow") {
-                saveMeter(METER_PATH, increment(meter, toolName));
-            }
         }
     }
     const receipt = createReceipt({
@@ -189,10 +451,7 @@ function cmdReceipt(toolName, file) {
         toolName,
         decision: decision.decision,
         reasonCode: decision.reasonCode,
-        request: {
-            toolName,
-            signedManifest: signedPath,
-        },
+        request,
         agentId: decision.agentId,
         grantReasonCode,
     }, keypair);
@@ -201,47 +460,140 @@ function cmdReceipt(toolName, file) {
     writeJson(receiptPath, receipt);
     printJson("receipt", receipt);
     console.log("");
-    console.log(decision.decision.toUpperCase() + ": " + decision.reasonCode + " -> " + receiptPath);
+    console.log(decision.decision.toUpperCase() +
+        ": " +
+        decision.reasonCode +
+        " -> " +
+        receiptPath);
     if (decision.decision === "deny") {
         process.exitCode = 1;
     }
 }
+function cmdVerifyReceipt(receiptFile, manifestFile) {
+    const signedPath = manifestFile ?? ACTIVE_MANIFEST_PATH;
+    if (!existsSync(signedPath)) {
+        throw new Error("no signed manifest found at " +
+            signedPath +
+            "; provide one or run besa sign <manifest> first");
+    }
+    const signedRaw = readJson(signedPath);
+    const trustStore = loadTrustStore();
+    const manifestVerification = verifyTrustedSignedManifest(signedRaw, trustStore);
+    if (!manifestVerification.valid) {
+        printJson("verifyReceipt", manifestVerification);
+        process.exitCode = 1;
+        return;
+    }
+    const signed = requireSignedManifest(signedRaw);
+    const receiptRaw = readJson(receiptFile);
+    const receiptValidation = validateReceipt(receiptRaw);
+    if (!receiptValidation.ok || !receiptValidation.receipt) {
+        const result = {
+            valid: false,
+            reasonCode: "E_RECEIPT_INVALID",
+            detail: receiptValidation.errors.join("; "),
+        };
+        printJson("verifyReceipt", result);
+        process.exitCode = 1;
+        return;
+    }
+    const receipt = receiptValidation.receipt;
+    if (receipt.manifestHash !== signed.manifestHash) {
+        const result = {
+            valid: false,
+            reasonCode: "E_RECEIPT_MANIFEST_MISMATCH",
+            detail: "receipt manifestHash does not match the signed manifest",
+        };
+        printJson("verifyReceipt", result);
+        process.exitCode = 1;
+        return;
+    }
+    const signatureResult = verifyReceiptDetailed(receipt, signed.publicKey);
+    const result = signatureResult.valid
+        ? checkTrustedKey(trustStore, signed.publicKey, receipt.timestamp)
+        : signatureResult;
+    printJson("verifyReceipt", result);
+    if (!result.valid) {
+        process.exitCode = 1;
+        return;
+    }
+    console.log("");
+    console.log("OK: receipt and signed manifest form a valid trust chain");
+}
+function readVersion() {
+    try {
+        const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+        const pkg = readJsonFile(join(packageRoot, "package.json"));
+        return typeof pkg.version === "string" ? pkg.version : "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
 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>]",
+        "  besa <command> [arguments] [options]",
+        "  besa --help | --version",
+        "",
+        "Commands:",
+        "  keys                 Show the local signing key, generating one if absent",
+        "  keys rotate          Rotate the signing key and emit a signed rotation proof",
+        "  trust add            Anchor a signed manifest's public key in a trust store",
+        "  trust apply          Apply a signed rotation proof to a trust store",
+        "  trust revoke         Revoke a public key in a trust store",
+        "  trust list           List trusted, retired, and revoked keys",
+        "  load                 Load and validate a manifest (YAML or JSON)",
+        "  sign                 Sign a manifest and anchor the publisher key",
+        "  verify               Verify a signed manifest against a trust store",
+        "  admit                Check whether a tool call is allowed (dry-run)",
+        "  receipt              Enforce budget and issue a signed execution receipt",
+        "  verify-receipt       Verify a receipt and its manifest trust chain",
+        "",
+        "Options:",
+        "  --trust <file>       Trust store path (default: .besa/trust.json)",
+        "  --agent <id>         Scope admission to a named agent (admit, receipt)",
+        "  --grants <file>      Grant set for agent-scoped admission (admit, receipt)",
+        "  --request <file>     Request payload hashed into the receipt (receipt)",
         "",
         "Examples:",
         "  besa keys",
-        "  besa load examples/manifest.yaml",
         "  besa sign examples/manifest.yaml",
+        "  besa trust add examples/manifest.signed.json --trust consumer-trust.json",
         "  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",
+        "  besa receipt crm.lookup examples/manifest.signed.json --request examples/request.json",
+        "  besa verify-receipt .besa/receipts/<receipt-id>.json examples/manifest.signed.json",
+        "",
+        "Security:",
+        "  Local developer beta. Private keys are encrypted at rest (AES-256-GCM + scrypt).",
+        "  Never commit the .besa/ directory. Not hardened for production use yet.",
     ].join("\n"));
 }
-function requireArgs(args, expected, command) {
-    if (args.length < expected) {
-        throw new Error(command + " requires " + String(expected) + " argument(s)");
+function requireArgs(args, minimum, command, maximum = minimum) {
+    if (args.length < minimum || args.length > maximum) {
+        const expected = minimum === maximum
+            ? String(minimum)
+            : `${String(minimum)}-${String(maximum)}`;
+        throw new Error(`${command} requires ${expected} argument(s), received ${String(args.length)}`);
     }
 }
 function main(argv) {
     const command = argv[0] ?? "";
-    const args = positionals(argv.slice(1));
     try {
+        const allowedFlags = COMMAND_FLAGS[command] ?? new Set();
+        const args = positionals(argv.slice(1), allowedFlags);
         switch (command) {
             case "keys":
-                cmdKeys();
+                requireArgs(args, 0, command, 1);
+                cmdKeys(args[0]);
+                break;
+            case "trust":
+                requireArgs(args, 1, command, 2);
+                cmdTrust(args[0] ?? "", args[1]);
                 break;
             case "load":
                 requireArgs(args, 1, command);
@@ -260,9 +612,18 @@ function main(argv) {
                 cmdAdmit(args[0] ?? "", args[1] ?? "");
                 break;
             case "receipt":
-                requireArgs(args, 1, command);
+                requireArgs(args, 1, command, 2);
                 cmdReceipt(args[0] ?? "", args[1]);
                 break;
+            case "verify-receipt":
+                requireArgs(args, 1, command, 2);
+                cmdVerifyReceipt(args[0] ?? "", args[1]);
+                break;
+            case "version":
+            case "--version":
+            case "-v":
+                console.log("besa " + readVersion());
+                break;
             case "":
             case "help":
             case "--help":
@@ -270,7 +631,7 @@ function main(argv) {
                 usage();
                 break;
             default:
-                console.error("Unknown command: " + command);
+                console.error("Unknown command: " + terminalText(command));
                 usage();
                 process.exitCode = 1;
                 break;
@@ -278,7 +639,7 @@ function main(argv) {
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        console.error("Error: " + message);
+        console.error("Error: " + terminalText(message));
         process.exitCode = 1;
     }
 }

package/dist/io.d.ts

@@ -0,0 +1,5 @@
+export declare const MAX_ARTIFACT_BYTES = 1048576;
+export declare function readUtf8File(path: string, maximumBytes?: number): string;
+export declare function readJsonFile(path: string): unknown;
+export declare function writeJsonAtomic(path: string, value: unknown, mode?: number): void;
+export declare function writeJsonExclusive(path: string, value: unknown, mode?: number): void;