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

package/dist/io.js

@@ -0,0 +1,97 @@
+import { randomUUID } from "node:crypto";
+import { chmodSync, closeSync, existsSync, fstatSync, fsyncSync, mkdirSync, openSync, readSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { dirname } from "node:path";
+export const MAX_ARTIFACT_BYTES = 1_048_576;
+export function readUtf8File(path, maximumBytes = MAX_ARTIFACT_BYTES) {
+    if (!Number.isSafeInteger(maximumBytes) || maximumBytes <= 0) {
+        throw new TypeError("maximumBytes must be a positive safe integer");
+    }
+    const descriptor = openSync(path, "r");
+    try {
+        if (!fstatSync(descriptor).isFile()) {
+            throw new Error(`refusing to read non-regular file at ${path}`);
+        }
+        const buffer = Buffer.allocUnsafe(maximumBytes + 1);
+        let total = 0;
+        while (total <= maximumBytes) {
+            const count = readSync(descriptor, buffer, total, maximumBytes + 1 - total, null);
+            if (count === 0)
+                break;
+            total += count;
+        }
+        if (total > maximumBytes) {
+            throw new Error(`file at ${path} exceeds the ${String(maximumBytes)} byte limit`);
+        }
+        return new TextDecoder("utf-8", { fatal: true }).decode(buffer.subarray(0, total));
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}
+export function readJsonFile(path) {
+    try {
+        return JSON.parse(readUtf8File(path));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`invalid JSON at ${path}: ${message}`);
+    }
+}
+export function writeJsonAtomic(path, value, mode = 0o600) {
+    const contents = JSON.stringify(value, null, 2) + "\n";
+    if (Buffer.byteLength(contents, "utf8") > MAX_ARTIFACT_BYTES) {
+        throw new Error(`refusing to write oversized JSON artifact at ${path}`);
+    }
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const temporaryPath = `${path}.${String(process.pid)}.${randomUUID()}.tmp`;
+    let descriptor;
+    try {
+        descriptor = openSync(temporaryPath, "wx", mode);
+        writeFileSync(descriptor, contents, "utf8");
+        fsyncSync(descriptor);
+        closeSync(descriptor);
+        descriptor = undefined;
+        renameSync(temporaryPath, path);
+        try {
+            chmodSync(path, mode);
+        }
+        catch {
+            // Windows does not apply POSIX modes; ACL custody remains operator-owned.
+        }
+    }
+    finally {
+        if (descriptor !== undefined) {
+            closeSync(descriptor);
+        }
+        if (existsSync(temporaryPath)) {
+            unlinkSync(temporaryPath);
+        }
+    }
+}
+export function writeJsonExclusive(path, value, mode = 0o600) {
+    const contents = JSON.stringify(value, null, 2) + "\n";
+    if (Buffer.byteLength(contents, "utf8") > MAX_ARTIFACT_BYTES) {
+        throw new Error(`refusing to write oversized JSON artifact at ${path}`);
+    }
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const descriptor = openSync(path, "wx", mode);
+    let complete = false;
+    try {
+        writeFileSync(descriptor, contents, "utf8");
+        fsyncSync(descriptor);
+        complete = true;
+    }
+    finally {
+        closeSync(descriptor);
+        if (!complete && existsSync(path)) {
+            unlinkSync(path);
+        }
+    }
+    try {
+        chmodSync(path, mode);
+    }
+    catch {
+        if (process.platform !== "win32")
+            throw new Error(`cannot protect ${path}`);
+    }
+}

package/dist/keystore.d.ts

@@ -0,0 +1,16 @@
+import { type KeyPair } from "./crypto.js";
+export interface StoredKeyPair {
+    version: 1;
+    publicKeyDer: string;
+    protection: {
+        kdf: "scrypt";
+        cipher: "aes-256-gcm";
+        salt: string;
+        iv: string;
+        authTag: string;
+        ciphertext: string;
+    };
+}
+export declare function sealKeyPair(keypair: KeyPair, passphrase: string): StoredKeyPair;
+export declare function isStoredKeyPair(value: unknown): value is StoredKeyPair;
+export declare function openKeyPair(stored: unknown, passphrase: string): KeyPair;

package/dist/keystore.js

@@ -0,0 +1,117 @@
+import { createCipheriv, createDecipheriv, randomBytes, scryptSync, } from "node:crypto";
+import { canonicalize, isCanonicalBase64, validateKeyPair } from "./crypto.js";
+const SCRYPT_N = 32_768;
+const SCRYPT_R = 8;
+const SCRYPT_P = 1;
+const SCRYPT_MAX_MEMORY = 64 * 1024 * 1024;
+function assertPassphrase(passphrase) {
+    const length = Buffer.byteLength(passphrase, "utf8");
+    if (length < 16 || length > 1_024) {
+        throw new Error("key passphrase must contain 16-1024 UTF-8 bytes");
+    }
+}
+function deriveKey(passphrase, salt) {
+    return scryptSync(passphrase, salt, 32, {
+        N: SCRYPT_N,
+        r: SCRYPT_R,
+        p: SCRYPT_P,
+        maxmem: SCRYPT_MAX_MEMORY,
+    });
+}
+function additionalData(publicKeyDer) {
+    return Buffer.from(canonicalize({
+        version: 1,
+        publicKeyDer,
+        kdf: "scrypt",
+        cipher: "aes-256-gcm",
+        parameters: { N: SCRYPT_N, r: SCRYPT_R, p: SCRYPT_P },
+    }), "utf8");
+}
+export function sealKeyPair(keypair, passphrase) {
+    if (!validateKeyPair(keypair)) {
+        throw new Error("cannot seal an invalid Ed25519 key pair");
+    }
+    assertPassphrase(passphrase);
+    const salt = randomBytes(16);
+    const iv = randomBytes(12);
+    const cipher = createCipheriv("aes-256-gcm", deriveKey(passphrase, salt), iv, { authTagLength: 16 });
+    cipher.setAAD(additionalData(keypair.publicKeyDer));
+    const ciphertext = Buffer.concat([
+        cipher.update(keypair.privateKeyDer, "utf8"),
+        cipher.final(),
+    ]);
+    return {
+        version: 1,
+        publicKeyDer: keypair.publicKeyDer,
+        protection: {
+            kdf: "scrypt",
+            cipher: "aes-256-gcm",
+            salt: salt.toString("base64"),
+            iv: iv.toString("base64"),
+            authTag: cipher.getAuthTag().toString("base64"),
+            ciphertext: ciphertext.toString("base64"),
+        },
+    };
+}
+export function isStoredKeyPair(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const candidate = value;
+    if (candidate.version !== 1 ||
+        typeof candidate.publicKeyDer !== "string" ||
+        !candidate.protection ||
+        typeof candidate.protection !== "object" ||
+        Array.isArray(candidate.protection)) {
+        return false;
+    }
+    if (Object.keys(candidate).some((field) => field !== "version" && field !== "publicKeyDer" && field !== "protection")) {
+        return false;
+    }
+    const protection = candidate.protection;
+    const allowed = new Set([
+        "kdf",
+        "cipher",
+        "salt",
+        "iv",
+        "authTag",
+        "ciphertext",
+    ]);
+    return (Object.keys(protection).every((field) => allowed.has(field)) &&
+        protection.kdf === "scrypt" &&
+        protection.cipher === "aes-256-gcm" &&
+        typeof protection.salt === "string" &&
+        protection.salt.length === 24 &&
+        isCanonicalBase64(protection.salt) &&
+        typeof protection.iv === "string" &&
+        protection.iv.length === 16 &&
+        isCanonicalBase64(protection.iv) &&
+        typeof protection.authTag === "string" &&
+        protection.authTag.length === 24 &&
+        isCanonicalBase64(protection.authTag) &&
+        typeof protection.ciphertext === "string" &&
+        protection.ciphertext.length <= 16_384 &&
+        isCanonicalBase64(protection.ciphertext));
+}
+export function openKeyPair(stored, passphrase) {
+    assertPassphrase(passphrase);
+    if (!isStoredKeyPair(stored)) {
+        throw new Error("encrypted key file is malformed or unsupported");
+    }
+    try {
+        const protection = stored.protection;
+        const decipher = createDecipheriv("aes-256-gcm", deriveKey(passphrase, Buffer.from(protection.salt, "base64")), Buffer.from(protection.iv, "base64"), { authTagLength: 16 });
+        decipher.setAAD(additionalData(stored.publicKeyDer));
+        decipher.setAuthTag(Buffer.from(protection.authTag, "base64"));
+        const privateKeyDer = Buffer.concat([
+            decipher.update(Buffer.from(protection.ciphertext, "base64")),
+            decipher.final(),
+        ]).toString("utf8");
+        const keypair = { publicKeyDer: stored.publicKeyDer, privateKeyDer };
+        if (!validateKeyPair(keypair))
+            throw new Error("key pair mismatch");
+        return keypair;
+    }
+    catch {
+        throw new Error("key file authentication failed");
+    }
+}

package/dist/manifest.js

@@ -1,21 +1,52 @@
-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";
 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})$/;
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
+const MANIFEST_FIELDS = new Set([
+    "serverName",
+    "serverVersion",
+    "serverUrl",
+    "createdAt",
+    "tools",
+]);
+const TOOL_FIELDS = new Set([
+    "name",
+    "description",
+    "capability",
+    "risk",
+    "scopes",
+    "budgetLimit",
+    "inputSchema",
+]);
+const MAX_TOOLS = 256;
+const MAX_SCOPES = 64;
+const TOOL_NAME_RE = /^[a-zA-Z0-9._-]{1,256}$/;
 function isObject(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
-function isNonEmptyString(value) {
-    return typeof value === "string" && value.trim().length > 0;
+function isNonEmptyString(value, maximumLength) {
+    return (typeof value === "string" &&
+        value.length <= maximumLength &&
+        value.trim().length > 0 &&
+        value.trim() === value &&
+        !/[\u0000-\u001f\u007f]/.test(value));
 }
 function isHttpUrl(value) {
     if (typeof value !== "string")
         return false;
     try {
         const url = new URL(value);
-        return url.protocol === "http:" || url.protocol === "https:";
+        const isLoopback = url.hostname === "localhost" ||
+            url.hostname === "127.0.0.1" ||
+            url.hostname === "[::1]";
+        return (value.length <= 2_048 &&
+            (url.protocol === "https:" || (url.protocol === "http:" && isLoopback)) &&
+            url.username === "" &&
+            url.password === "" &&
+            url.hash === "");
     }
     catch {
         return false;
@@ -31,11 +62,16 @@ export function validateManifest(raw) {
     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");
+    for (const field of Object.keys(raw)) {
+        if (!MANIFEST_FIELDS.has(field)) {
+            errors.push(`unexpected manifest field '${field}'`);
+        }
+    }
+    if (!isNonEmptyString(raw.serverName, 128)) {
+        errors.push("serverName must be a non-empty string of at most 128 characters");
     }
-    if (!isNonEmptyString(raw.serverVersion)) {
-        errors.push("serverVersion must be a non-empty string");
+    if (!isNonEmptyString(raw.serverVersion, 64)) {
+        errors.push("serverVersion must be a non-empty string of at most 64 characters");
     }
     if (!isHttpUrl(raw.serverUrl)) {
         errors.push("serverUrl must be a valid http(s) URL");
@@ -46,6 +82,9 @@ export function validateManifest(raw) {
     if (!Array.isArray(raw.tools) || raw.tools.length === 0) {
         errors.push("tools must be a non-empty array");
     }
+    else if (raw.tools.length > MAX_TOOLS) {
+        errors.push(`tools must contain at most ${String(MAX_TOOLS)} entries`);
+    }
     else {
         const seen = new Set();
         raw.tools.forEach((tool, index) => {
@@ -58,6 +97,13 @@ export function validateManifest(raw) {
             }
         });
     }
+    try {
+        canonicalize(raw);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        errors.push(`manifest must contain only JSON values: ${message}`);
+    }
     if (errors.length > 0) {
         return { ok: false, errors };
     }
@@ -69,11 +115,16 @@ function validateTool(tool, index, errors) {
         errors.push(`${path} must be an object`);
         return;
     }
-    if (!isNonEmptyString(tool.name)) {
-        errors.push(`${path}.name must be a non-empty string`);
+    for (const field of Object.keys(tool)) {
+        if (!TOOL_FIELDS.has(field)) {
+            errors.push(`unexpected ${path} field '${field}'`);
+        }
     }
-    if (typeof tool.description !== "string") {
-        errors.push(`${path}.description must be a string`);
+    if (typeof tool.name !== "string" || !TOOL_NAME_RE.test(tool.name)) {
+        errors.push(`${path}.name must contain only ASCII letters, digits, dots, underscores, and hyphens (1-256 characters)`);
+    }
+    if (typeof tool.description !== "string" || tool.description.length > 4_096) {
+        errors.push(`${path}.description must be a string of at most 4096 characters`);
     }
     if (!CAPABILITIES.includes(tool.capability)) {
         errors.push(`${path}.capability must be one of ${CAPABILITIES.join(", ")}`);
@@ -83,8 +134,9 @@ function validateTool(tool, index, errors) {
     }
     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`);
+        tool.scopes.length > MAX_SCOPES ||
+        !tool.scopes.every((scope) => isNonEmptyString(scope, 256))) {
+        errors.push(`${path}.scopes must contain 1-${String(MAX_SCOPES)} non-empty strings of at most 256 characters`);
     }
     if (typeof tool.budgetLimit !== "number" ||
         !Number.isSafeInteger(tool.budgetLimit) ||
@@ -96,8 +148,22 @@ function validateTool(tool, index, errors) {
     }
 }
 export function loadManifest(path) {
-    const source = readFileSync(path, "utf8");
-    const raw = extname(path) === ".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("manifest path must end in .json, .yaml, or .yml");
+    }
     const result = validateManifest(raw);
     if (!result.ok || !result.manifest) {
         throw new Error(`Invalid manifest:\n  - ${result.errors.join("\n  - ")}`);

package/dist/sdk.d.ts

@@ -4,3 +4,5 @@ export * from "./manifest.js";
 export * from "./signing.js";
 export * from "./admit.js";
 export * from "./grant.js";
+export * from "./trust.js";
+export * from "./keystore.js";

package/dist/sdk.js

@@ -4,3 +4,5 @@ export * from "./manifest.js";
 export * from "./signing.js";
 export * from "./admit.js";
 export * from "./grant.js";
+export * from "./trust.js";
+export * from "./keystore.js";

package/dist/signing.d.ts

@@ -5,6 +5,16 @@ export interface VerifyResult {
     reasonCode: string;
     detail: string;
 }
+export interface SignedManifestValidationResult {
+    ok: boolean;
+    signedManifest?: SignedManifest;
+    errors: string[];
+}
+export interface ReceiptValidationResult {
+    ok: boolean;
+    receipt?: Receipt;
+    errors: string[];
+}
 export interface ReceiptInput {
     manifestHash: string;
     toolName: string;
@@ -14,8 +24,12 @@ export interface ReceiptInput {
     agentId?: string;
     grantReasonCode?: string;
 }
+export declare function validateSignedManifest(value: unknown): SignedManifestValidationResult;
+export declare function validateReceipt(value: unknown): ReceiptValidationResult;
 export declare function hashManifest(manifest: Manifest): string;
+export declare function hashRequest(request: unknown): string;
 export declare function signManifest(manifest: Manifest, keypair: KeyPair): SignedManifest;
-export declare function verifySignedManifest(signed: SignedManifest): VerifyResult;
+export declare function verifySignedManifest(value: unknown): VerifyResult;
 export declare function createReceipt(input: ReceiptInput, keypair: KeyPair): Receipt;
-export declare function verifyReceipt(receipt: Receipt, publicKeyDer: string): boolean;
+export declare function verifyReceiptDetailed(value: unknown, publicKeyDer: string): VerifyResult;
+export declare function verifyReceipt(receipt: unknown, publicKeyDer: string): boolean;