attenu-guard 0.1.0

package/dist/esm/wire.js

@@ -0,0 +1,159 @@
+/**
+ * wire.ts — the signing and verification backends.
+ *
+ * Anchors and delegation tokens are signed over canonical JSON bytes. Two
+ * backends ship, matching the Python library's `attenu_guard.wire`:
+ *
+ *   `HS256TestSigner`  stdlib HMAC-SHA256, for tests, examples and local dev;
+ *   `Ed25519Signer`    the production signer the Internet-Draft requires, with
+ *                      `Ed25519Verifier` for anyone holding only the public half.
+ *
+ * Everything here is built on Node's own `node:crypto`, so the package keeps
+ * zero runtime dependencies. Ed25519 keys are wrapped in the fixed DER prefixes
+ * below rather than pulled from a library.
+ */
+import { createHmac, createPrivateKey, createPublicKey, generateKeyPairSync, sign as cryptoSign, timingSafeEqual, verify as cryptoVerify, } from "node:crypto";
+/**
+ * stdlib HMAC-SHA256 signer — the default for tests, examples and local dev,
+ * because it needs no key management at all.
+ *
+ * NOT FOR PRODUCTION. HMAC is symmetric: `sign` and `verify` use the identical
+ * secret, so anyone able to verify a bundle is also able to forge one. That
+ * precludes the property the draft is built around — public offline
+ * verification at an untrusted enforcement point — because every verifier would
+ * have to hold the minting secret. Use `Ed25519Signer` in production; this
+ * class exists so the wire format and the interop fixtures can be exercised
+ * with no key distribution.
+ */
+export class HS256TestSigner {
+    secret;
+    alg = "HS256";
+    kid;
+    constructor(secret, kid = "test") {
+        this.secret = secret;
+        this.kid = kid;
+    }
+    sign(signingInput) {
+        return createHmac("sha256", this.secret).update(signingInput).digest();
+    }
+    verify(signingInput, sig, _keyId) {
+        // `keyId` is accepted for parity with multi-key signers but not used for
+        // key selection: this signer holds exactly one secret. The comparison is
+        // constant-time to avoid a signature-forgery timing oracle.
+        const expected = this.sign(signingInput);
+        return expected.length === sig.length && timingSafeEqual(expected, sig);
+    }
+}
+// Fixed DER wrappers for raw Ed25519 keys (RFC 8410). A raw 32-byte public key
+// becomes a SubjectPublicKeyInfo by prefixing the first; a raw 32-byte private
+// key becomes a PKCS#8 PrivateKeyInfo by prefixing the second.
+const ED25519_SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+const ED25519_PKCS8_PREFIX = Buffer.from("302e020100300506032b657004220420", "hex");
+function publicKeyFromRaw(raw) {
+    if (raw.length !== 32) {
+        throw new Error(`an Ed25519 public key is 32 bytes, got ${raw.length}`);
+    }
+    return createPublicKey({
+        key: Buffer.concat([ED25519_SPKI_PREFIX, raw]),
+        format: "der",
+        type: "spki",
+    });
+}
+function privateKeyFromRaw(raw) {
+    if (raw.length !== 32) {
+        throw new Error(`an Ed25519 private key is 32 bytes, got ${raw.length}`);
+    }
+    return createPrivateKey({
+        key: Buffer.concat([ED25519_PKCS8_PREFIX, raw]),
+        format: "der",
+        type: "pkcs8",
+    });
+}
+function rawPublicBytes(key) {
+    const der = key.export({ format: "der", type: "spki" });
+    return Buffer.from(der.subarray(der.length - 32));
+}
+function rawPrivateBytes(key) {
+    const der = key.export({ format: "der", type: "pkcs8" });
+    return Buffer.from(der.subarray(der.length - 32));
+}
+/**
+ * The production signer the draft requires ("Implementations MUST support
+ * Ed25519"); JOSE alg "EdDSA". Public-key, so — unlike `HS256TestSigner` — a
+ * verifier never needs the signing secret, which is exactly what offline
+ * verification at an untrusted edge depends on.
+ */
+export class Ed25519Signer {
+    alg = "EdDSA";
+    kid;
+    privateKey;
+    publicKey;
+    constructor(privateKey, kid = "ed25519-1") {
+        if (privateKey === undefined) {
+            const pair = generateKeyPairSync("ed25519");
+            this.privateKey = pair.privateKey;
+            this.publicKey = pair.publicKey;
+        }
+        else {
+            this.privateKey = privateKey;
+            this.publicKey = createPublicKey(privateKey);
+        }
+        this.kid = kid;
+    }
+    /** A signer wrapping a freshly generated keypair. */
+    static generate(kid = "ed25519-1") {
+        return new Ed25519Signer(undefined, kid);
+    }
+    /** Rebuild a signer from the 32 raw bytes `privateBytesRaw` produced. */
+    static fromPrivateBytes(raw, kid = "ed25519-1") {
+        return new Ed25519Signer(privateKeyFromRaw(raw), kid);
+    }
+    sign(signingInput) {
+        return cryptoSign(null, signingInput, this.privateKey);
+    }
+    verify(signingInput, sig, _keyId) {
+        try {
+            return cryptoVerify(null, signingInput, this.publicKey, sig);
+        }
+        catch {
+            return false;
+        }
+    }
+    /** The 32-byte raw public key — a trust anchor to distribute out of band. */
+    publicBytesRaw() {
+        return rawPublicBytes(this.publicKey);
+    }
+    /** The 32-byte raw private key — what a key FILE stores, never a repo. */
+    privateBytesRaw() {
+        return rawPrivateBytes(this.privateKey);
+    }
+}
+/**
+ * The public-key-only counterpart of `Ed25519Signer` — what a console, an
+ * auditor or an ingest server holds. It verifies anchors signed by the matching
+ * private key and can never sign: `sign` throws.
+ */
+export class Ed25519Verifier {
+    alg = "EdDSA";
+    kid;
+    publicKey;
+    constructor(publicBytesRaw, kid = "ed25519-1") {
+        this.publicKey = publicKeyFromRaw(publicBytesRaw);
+        this.kid = kid;
+    }
+    sign(_signingInput) {
+        throw new Error("Ed25519Verifier holds no private key and cannot sign");
+    }
+    verify(signingInput, sig, _keyId) {
+        try {
+            return cryptoVerify(null, signingInput, this.publicKey, sig);
+        }
+        catch {
+            return false;
+        }
+    }
+    publicBytesRaw() {
+        return rawPublicBytes(this.publicKey);
+    }
+}
+//# sourceMappingURL=wire.js.map

package/dist/esm/wire.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire.js","sourceRoot":"","sources":["../../src/wire.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "attenu-guard",
+  "version": "0.1.0",
+  "description": "Attenu Guard for TypeScript: enforces per-agent permissions on every tool call and sub-agent handoff — a sub-agent never holds more than its parent — and writes a hash-chained audit log you verify offline. Same bundle format as the Python library.",
+  "license": "Apache-2.0",
+  "author": "Attenu",
+  "homepage": "https://attenu.io",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/attenu-io/attenu-guard-ts.git"
+  },
+  "bugs": {
+    "url": "https://github.com/attenu-io/attenu-guard-ts/issues"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "security",
+    "authorization",
+    "least-privilege",
+    "delegation",
+    "sub-agents",
+    "audit-log",
+    "mcp",
+    "a2a",
+    "owasp",
+    "langgraph",
+    "langchain",
+    "langgraphjs",
+    "typescript"
+  ],
+  "type": "commonjs",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/cjs/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./adapters/langgraph": {
+      "import": {
+        "types": "./dist/esm/adapters/langgraph.d.ts",
+        "default": "./dist/esm/adapters/langgraph.js"
+      },
+      "require": {
+        "types": "./dist/cjs/adapters/langgraph.d.ts",
+        "default": "./dist/cjs/adapters/langgraph.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "attenu-guard": "bin/attenu-guard.js"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "SECURITY.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true});require('node:fs').rmSync('build',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc -p tsconfig.cjs.json && tsc -p tsconfig.esm.json && node scripts/write-module-markers.js",
+    "build:tests": "tsc -p tsconfig.test.json",
+    "pretest": "npm run build && npm run build:tests",
+    "test": "node --test build/test/*.test.js",
+    "fixtures": "python3 tools/gen_fixtures.py"
+  },
+  "devDependencies": {
+    "@langchain/core": "^1.2.9",
+    "@langchain/langgraph": "^1.4.13",
+    "@types/node": "^22.20.1",
+    "typescript": "^5.9.3",
+    "zod": "^4.4.3"
+  }
+}