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

package/dist/admit.js

@@ -1,18 +1,46 @@
+import { randomUUID } from "node:crypto";
 import { dirname } from "node:path";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { validateManifest } from "./manifest.js";
+import { readJsonFile, writeJsonAtomic } from "./io.js";
 export const REASON = {
     ALLOWED: "ALLOWED",
     TOOL_NOT_FOUND: "TOOL_NOT_FOUND",
     RISK_BLOCKED: "RISK_BLOCKED",
-    BUDGET_EXCEEDED: "BUDGET_EXCEEDED"
+    BUDGET_EXCEEDED: "BUDGET_EXCEEDED",
+    INVALID_MANIFEST: "INVALID_MANIFEST",
+    INVALID_TOOL_NAME: "INVALID_TOOL_NAME",
+    INVALID_CALL_COUNT: "INVALID_CALL_COUNT",
+    INVALID_POLICY: "INVALID_POLICY",
 };
+const SHA256_HEX = /^[a-f0-9]{64}$/;
+const TOOL_NAME_RE = /^[a-zA-Z0-9._-]{1,256}$/;
+function isValidToolName(name) {
+    return typeof name === "string" && TOOL_NAME_RE.test(name);
+}
 export const DEFAULT_POLICY = {
-    denyDestructiveHighRisk: true
+    denyDestructiveHighRisk: true,
 };
 export function findTool(manifest, toolName) {
     return manifest.tools.find((tool) => tool.name === toolName);
 }
 export function admit(manifest, toolName, callCount, policy = DEFAULT_POLICY) {
+    if (!isValidToolName(toolName)) {
+        return deny("", REASON.INVALID_TOOL_NAME, "tool name is invalid");
+    }
+    if (!Number.isSafeInteger(callCount) || callCount < 0) {
+        return deny(toolName, REASON.INVALID_CALL_COUNT, "call count must be a safe non-negative integer");
+    }
+    if (!policy ||
+        typeof policy !== "object" ||
+        policy.denyDestructiveHighRisk !== true &&
+            policy.denyDestructiveHighRisk !== false) {
+        return deny(toolName, REASON.INVALID_POLICY, "admission policy is invalid");
+    }
+    const manifestValidation = validateManifest(manifest);
+    if (!manifestValidation.ok) {
+        return deny(toolName, REASON.INVALID_MANIFEST, "manifest failed runtime validation");
+    }
     const tool = findTool(manifest, toolName);
     if (!tool) {
         return deny(toolName, REASON.TOOL_NOT_FOUND, `tool '${toolName}' is not declared in the manifest`);
@@ -29,7 +57,7 @@ export function admit(manifest, toolName, callCount, policy = DEFAULT_POLICY) {
         decision: "allow",
         reasonCode: REASON.ALLOWED,
         toolName,
-        detail: "tool call admitted"
+        detail: "tool call admitted",
     };
 }
 function deny(toolName, reasonCode, detail) {
@@ -37,40 +65,172 @@ function deny(toolName, reasonCode, detail) {
         decision: "deny",
         reasonCode,
         toolName,
-        detail
+        detail,
     };
 }
+export function meterKey(manifestHash, toolName) {
+    if (!SHA256_HEX.test(manifestHash)) {
+        throw new Error("manifestHash must be a lowercase SHA-256 hex digest");
+    }
+    if (!isValidToolName(toolName)) {
+        throw new Error("toolName is invalid");
+    }
+    return `${manifestHash}:${toolName}`;
+}
 export function loadMeter(path) {
     if (!existsSync(path)) {
         return {};
     }
+    let raw;
     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;
+        raw = readJsonFile(path);
     }
-    catch {
-        return {};
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`invalid meter state at ${path}: ${message}`);
+    }
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error(`invalid meter state at ${path}: expected a JSON object`);
+    }
+    const state = Object.create(null);
+    for (const [key, value] of Object.entries(raw)) {
+        if (typeof value !== "number" ||
+            !Number.isSafeInteger(value) ||
+            value < 0) {
+            throw new Error(`invalid meter state at ${path}: '${key}' must be a safe non-negative integer`);
+        }
+        state[key] = value;
     }
+    return state;
 }
 export function saveMeter(path, state) {
+    writeJsonAtomic(path, state, 0o600);
+}
+export function getCount(state, key) {
+    return state[key] ?? 0;
+}
+export function increment(state, key) {
+    const count = getCount(state, key);
+    if (!Number.isSafeInteger(count) || count < 0 || count === Number.MAX_SAFE_INTEGER) {
+        throw new Error(`meter count for '${key}' cannot be incremented safely`);
+    }
+    return Object.assign(Object.create(null), state, {
+        [key]: count + 1,
+    });
+}
+function sleep(milliseconds) {
+    const signal = new Int32Array(new SharedArrayBuffer(4));
+    Atomics.wait(signal, 0, 0, milliseconds);
+}
+function acquireMeterLock(path, options) {
+    const lockPath = `${path}.lock`;
+    const timeoutMs = options.timeoutMs ?? 5_000;
+    const staleMs = options.staleMs ?? 30_000;
+    const retryMs = options.retryMs ?? 10;
+    const startedAt = Date.now();
+    if (!Number.isFinite(timeoutMs) ||
+        !Number.isFinite(staleMs) ||
+        !Number.isFinite(retryMs) ||
+        timeoutMs < 0 ||
+        staleMs <= 0 ||
+        retryMs <= 0) {
+        throw new Error("meter lock timings must be positive");
+    }
     mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, JSON.stringify(state, null, 2) + "\n", "utf8");
+    while (true) {
+        try {
+            const descriptor = openSync(lockPath, "wx", 0o600);
+            const token = randomUUID();
+            try {
+                writeFileSync(descriptor, JSON.stringify({
+                    pid: process.pid,
+                    token,
+                    createdAt: new Date().toISOString(),
+                }) + "\n", "utf8");
+                fsyncSync(descriptor);
+            }
+            catch (error) {
+                closeSync(descriptor);
+                unlinkSync(lockPath);
+                throw error;
+            }
+            return () => {
+                closeSync(descriptor);
+                try {
+                    const lock = readJsonFile(lockPath);
+                    if (lock.token === token) {
+                        unlinkSync(lockPath);
+                    }
+                }
+                catch (error) {
+                    if (error.code !== "ENOENT") {
+                        throw error;
+                    }
+                }
+            };
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== "EEXIST") {
+                throw error;
+            }
+            try {
+                if (Date.now() - statSync(lockPath).mtimeMs > staleMs &&
+                    !lockOwnerIsAlive(lockPath)) {
+                    const stalePath = `${lockPath}.${String(process.pid)}.${randomUUID()}.stale`;
+                    renameSync(lockPath, stalePath);
+                    unlinkSync(stalePath);
+                    continue;
+                }
+            }
+            catch (statError) {
+                if (statError.code === "ENOENT") {
+                    continue;
+                }
+                throw statError;
+            }
+            if (Date.now() - startedAt >= timeoutMs) {
+                throw new Error(`timed out waiting for meter lock at ${lockPath}`);
+            }
+            sleep(retryMs);
+        }
+    }
 }
-export function getCount(state, toolName) {
-    return state[toolName] ?? 0;
+function lockOwnerIsAlive(lockPath) {
+    try {
+        const value = readJsonFile(lockPath);
+        if (!value || typeof value !== "object" || Array.isArray(value)) {
+            return false;
+        }
+        const pid = value.pid;
+        if (!Number.isSafeInteger(pid) || pid <= 0) {
+            return false;
+        }
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch (error) {
+            const code = error.code;
+            return code !== "ESRCH";
+        }
+    }
+    catch {
+        return false;
+    }
 }
-export function increment(state, toolName) {
-    return {
-        ...state,
-        [toolName]: getCount(state, toolName) + 1
-    };
+export function admitAndConsume(path, manifestHash, manifest, toolName, policy = DEFAULT_POLICY, lockOptions = {}) {
+    const release = acquireMeterLock(path, lockOptions);
+    try {
+        const state = loadMeter(path);
+        const key = meterKey(manifestHash, toolName);
+        const decision = admit(manifest, toolName, getCount(state, key), policy);
+        if (decision.decision === "allow") {
+            saveMeter(path, increment(state, key));
+        }
+        return decision;
+    }
+    finally {
+        release();
+    }
 }

package/dist/crypto.d.ts

@@ -4,9 +4,12 @@ export interface KeyPair {
     privateKeyDer: string;
 }
 export declare function canonicalize(value: unknown): string;
-export declare function sha256Hex(data: string): string;
+export declare function sha256Hex(data: string | Uint8Array): 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;
+export declare function isCanonicalBase64(value: unknown): value is string;
+export declare function signatureMessage(domain: string, value: unknown): Buffer;
+export declare function validateKeyPair(value: unknown): value is KeyPair;

package/dist/crypto.js

@@ -1,23 +1,74 @@
-import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync } from "node:crypto";
-function sortValue(value) {
-    if (Array.isArray(value)) {
-        return value.map(sortValue);
+import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, timingSafeEqual, } from "node:crypto";
+const MAX_CANONICAL_DEPTH = 64;
+const MAX_CANONICAL_NODES = 100_000;
+const MAX_CANONICAL_BYTES = 1_048_576;
+function sortValue(value, path, depth, state) {
+    state.nodes += 1;
+    if (state.nodes > MAX_CANONICAL_NODES) {
+        throw new TypeError("value exceeds the canonical JSON node limit");
     }
-    if (value !== null && typeof value === "object") {
+    if (depth > MAX_CANONICAL_DEPTH) {
+        throw new TypeError(`${path} exceeds the canonical JSON depth limit`);
+    }
+    if (value === null ||
+        typeof value === "string" ||
+        typeof value === "boolean") {
+        return value;
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new TypeError(`${path} must be a finite JSON number`);
+        }
+        return value;
+    }
+    if (typeof value !== "object") {
+        throw new TypeError(`${path} contains a non-JSON value`);
+    }
+    if (state.seen.has(value)) {
+        throw new TypeError(`${path} contains a circular reference`);
+    }
+    state.seen.add(value);
+    try {
+        if (Array.isArray(value)) {
+            return value.map((item, index) => sortValue(item, `${path}[${String(index)}]`, depth + 1, state));
+        }
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new TypeError(`${path} must contain only plain JSON objects`);
+        }
         const input = value;
-        const output = {};
+        const output = Object.create(null);
         for (const key of Object.keys(input).sort()) {
-            output[key] = sortValue(input[key]);
+            const descriptor = Object.getOwnPropertyDescriptor(input, key);
+            if (!descriptor || !("value" in descriptor)) {
+                throw new TypeError(`${path}.${key} must be a JSON data property`);
+            }
+            output[key] = sortValue(descriptor.value, `${path}.${key.slice(0, 64)}`, depth + 1, state);
         }
         return output;
     }
-    return value;
+    finally {
+        state.seen.delete(value);
+    }
 }
 export function canonicalize(value) {
-    return JSON.stringify(sortValue(value));
+    const canonical = JSON.stringify(sortValue(value, "$", 0, {
+        nodes: 0,
+        seen: new WeakSet(),
+    }));
+    if (canonical === undefined) {
+        throw new TypeError("value cannot be canonicalized");
+    }
+    if (Buffer.byteLength(canonical, "utf8") > MAX_CANONICAL_BYTES) {
+        throw new TypeError("value exceeds the canonical JSON byte limit");
+    }
+    return canonical;
 }
 export function sha256Hex(data) {
-    return createHash("sha256").update(data, "utf8").digest("hex");
+    const hash = createHash("sha256");
+    return typeof data === "string"
+        ? hash.update(data, "utf8").digest("hex")
+        : hash.update(data).digest("hex");
 }
 export function hashObject(value) {
     return sha256Hex(canonicalize(value));
@@ -25,24 +76,81 @@ export function hashObject(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")
+        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"),
+    const key = createPublicKey({
+        key: decodeCanonicalBase64(publicKeyDer, "public key"),
         type: "spki",
-        format: "der"
+        format: "der",
     });
+    if (key.asymmetricKeyType !== "ed25519") {
+        throw new TypeError("public key must be Ed25519");
+    }
+    return key;
 }
 export function privateKeyFromDer(privateKeyDer) {
-    return createPrivateKey({
-        key: Buffer.from(privateKeyDer, "base64"),
+    const key = createPrivateKey({
+        key: decodeCanonicalBase64(privateKeyDer, "private key"),
         type: "pkcs8",
-        format: "der"
+        format: "der",
     });
+    if (key.asymmetricKeyType !== "ed25519") {
+        throw new TypeError("private key must be Ed25519");
+    }
+    return key;
 }
 export function publicKeyId(publicKeyDer) {
-    return sha256Hex(publicKeyDer).slice(0, 16);
+    return sha256Hex(decodeCanonicalBase64(publicKeyDer, "public key"));
+}
+export function isCanonicalBase64(value) {
+    if (typeof value !== "string" || value.length === 0) {
+        return false;
+    }
+    try {
+        return Buffer.from(value, "base64").toString("base64") === value;
+    }
+    catch {
+        return false;
+    }
+}
+function decodeCanonicalBase64(value, label) {
+    if (!isCanonicalBase64(value)) {
+        throw new TypeError(`${label} must be canonical base64`);
+    }
+    return Buffer.from(value, "base64");
+}
+export function signatureMessage(domain, value) {
+    if (!/^[a-z][a-z0-9-]{0,63}$/.test(domain)) {
+        throw new TypeError("signature domain is invalid");
+    }
+    return Buffer.from(`besa:${domain}:v1\0${canonicalize(value)}`, "utf8");
+}
+export function validateKeyPair(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const candidate = value;
+    if (typeof candidate.publicKeyDer !== "string" ||
+        typeof candidate.privateKeyDer !== "string") {
+        return false;
+    }
+    try {
+        const privateKey = privateKeyFromDer(candidate.privateKeyDer);
+        const derivedPublicKeyDer = createPublicKey(privateKey)
+            .export({ type: "spki", format: "der" });
+        publicKeyFromDer(candidate.publicKeyDer);
+        const storedPublicKeyDer = Buffer.from(candidate.publicKeyDer, "base64");
+        return (derivedPublicKeyDer.length === storedPublicKeyDer.length &&
+            timingSafeEqual(derivedPublicKeyDer, storedPublicKeyDer));
+    }
+    catch {
+        return false;
+    }
 }

package/dist/grant.js

@@ -1,16 +1,23 @@
-import { readFileSync } from "node:fs";
 import { extname } from "node:path";
 import { parse as parseYaml } from "yaml";
+import { canonicalize } from "./crypto.js";
+import { readUtf8File } from "./io.js";
 export const GRANT_REASON = {
     GRANTED: "GRANT_OK",
     AGENT_NOT_FOUND: "AGENT_NOT_FOUND",
     TOOL_NOT_GRANTED: "TOOL_NOT_GRANTED",
 };
+const MAX_GRANTS = 256;
+const MAX_TOOLS_PER_GRANT = 256;
 function isObject(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 function isNonEmptyString(value) {
-    return typeof value === "string" && value.trim().length > 0;
+    return (typeof value === "string" &&
+        value.length <= 256 &&
+        value.trim().length > 0 &&
+        value.trim() === value &&
+        !/[\u0000-\u001f\u007f]/.test(value));
 }
 export function validateGrantSet(raw) {
     const errors = [];
@@ -20,9 +27,17 @@ export function validateGrantSet(raw) {
             errors: ["grant set must be an object"],
         };
     }
+    for (const field of Object.keys(raw)) {
+        if (field !== "grants") {
+            errors.push(`unexpected grant set field '${field}'`);
+        }
+    }
     if (!Array.isArray(raw.grants) || raw.grants.length === 0) {
         errors.push("grants must be a non-empty array");
     }
+    else if (raw.grants.length > MAX_GRANTS) {
+        errors.push(`grants must contain at most ${String(MAX_GRANTS)} entries`);
+    }
     else {
         const seenAgents = new Set();
         raw.grants.forEach((grant, index) => {
@@ -31,6 +46,11 @@ export function validateGrantSet(raw) {
                 errors.push(`${path} must be an object`);
                 return;
             }
+            for (const field of Object.keys(grant)) {
+                if (field !== "agentId" && field !== "tools") {
+                    errors.push(`unexpected ${path} field '${field}'`);
+                }
+            }
             if (!isNonEmptyString(grant.agentId)) {
                 errors.push(`${path}.agentId must be a non-empty string`);
             }
@@ -42,11 +62,22 @@ export function validateGrantSet(raw) {
             }
             if (!Array.isArray(grant.tools) ||
                 grant.tools.length === 0 ||
+                grant.tools.length > MAX_TOOLS_PER_GRANT ||
                 !grant.tools.every((tool) => isNonEmptyString(tool))) {
-                errors.push(`${path}.tools must be a non-empty array of non-empty strings`);
+                errors.push(`${path}.tools must contain 1-${String(MAX_TOOLS_PER_GRANT)} valid tool names`);
+            }
+            else if (new Set(grant.tools).size !== grant.tools.length) {
+                errors.push(`${path}.tools must not contain duplicate tool names`);
             }
         });
     }
+    try {
+        canonicalize(raw);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        errors.push(`grant set must contain only bounded JSON values: ${message}`);
+    }
     if (errors.length > 0) {
         return {
             ok: false,
@@ -60,8 +91,22 @@ export function validateGrantSet(raw) {
     };
 }
 export function loadGrants(path) {
-    const source = readFileSync(path, "utf8");
-    const raw = extname(path).toLowerCase() === ".json" ? JSON.parse(source) : parseYaml(source);
+    const source = readUtf8File(path);
+    const extension = extname(path).toLowerCase();
+    let raw;
+    if (extension === ".json") {
+        raw = JSON.parse(source);
+    }
+    else if (extension === ".yaml" || extension === ".yml") {
+        raw = parseYaml(source, {
+            maxAliasCount: 50,
+            strict: true,
+            uniqueKeys: true,
+        });
+    }
+    else {
+        throw new Error("grant path must end in .json, .yaml, or .yml");
+    }
     const result = validateGrantSet(raw);
     if (!result.ok || !result.grantSet) {
         throw new Error(`Invalid grant set:\n  - ${result.errors.join("\n  - ")}`);