@circuit-llm/bundle 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Circuit LLM
+
+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,25 @@
+# @circuit-llm/bundle
+
+> Build, sign, verify, and unpack **content-addressed (sha256) signed agent bundles** — the canonical codec shared by the Circuit agent cloud and the `circuit` CLI. **Zero runtime dependencies.**
+
+Part of the **[Circuit SDK](https://github.com/Circuit-LLM/circuit-sdk)**. [Packages →](https://github.com/Circuit-LLM/circuit-sdk/blob/main/docs/packages.md)
+
+## Install
+
+```bash
+npm install @circuit-llm/bundle
+```
+
+## Usage
+
+```ts
+import { packDir, createBundle, verifyBundle, unpackTo, fromSeed } from '@circuit-llm/bundle';
+
+const resources = await packDir('./my-agent');                        // read + hash a folder
+const bundle = createBundle(resources, { entry: 'index.js' }, fromSeed(seed));   // signed manifest
+
+verifyBundle(bundle);                                                 // checks hashes + signature
+await unpackTo(bundle, './out');
+```
+
+Every file is content-addressed and the manifest is signed, so a bundle can't be silently altered between author and host. `isSafeEntry` blocks path traversal.

package/dist/index.d.ts

@@ -0,0 +1,77 @@
+import crypto from 'node:crypto';
+
+declare function base58(buf: Uint8Array | Buffer): string;
+declare function base58decode(str: string): Buffer;
+interface Keypair {
+    seed: Buffer;
+    priv: crypto.KeyObject;
+    pubkey: Buffer;
+    address: string;
+}
+/** Deterministic keypair from a 32-byte seed. */
+declare function fromSeed(seed: Uint8Array | Buffer): Keypair;
+/** 64-byte Ed25519 signature over `msg`. `priv` is a node KeyObject (see fromSeed). */
+declare function sign(priv: crypto.KeyObject, msg: Uint8Array | Buffer): Buffer;
+/** Verify a signature against a 32-byte raw Ed25519 public key. */
+declare function verify(pubkey: Uint8Array | Buffer, msg: Uint8Array | Buffer, sig: Uint8Array | Buffer): boolean;
+declare const sha256hex: (s: crypto.BinaryLike) => string;
+
+declare const BUNDLE_SCHEMA = 1;
+type BundleRuntime = 'node' | 'oci';
+interface BundleResources {
+    maxCpu?: number | null;
+    maxMemoryMb?: number | null;
+}
+interface BundleManifest {
+    schema: number;
+    agentId: string;
+    runtime: BundleRuntime;
+    entry: string;
+    sdk: string | null;
+    egress: string[];
+    resources: BundleResources | null;
+    sha256: string;
+    publisherPubkey: string;
+    sig?: string;
+}
+interface VerifyBundleResult {
+    ok: boolean;
+    code?: 'sha256-mismatch' | 'bad-manifest-sig' | 'publisher-not-owner' | 'agent-id-mismatch' | 'bad-entry';
+}
+declare function canonResources(r: BundleResources | null | undefined): BundleResources | null;
+declare function manifestSigningBytes(m: BundleManifest): Buffer;
+declare function signManifest(m: BundleManifest, priv: crypto.KeyObject): string;
+declare function verifyManifest(m: BundleManifest): boolean;
+interface PackResult {
+    bytes: Buffer;
+    sha256: string;
+    files: string[];
+    excludedSecrets: string[];
+}
+declare function packDir(dir: string): PackResult;
+declare function unpackTo(bytes: Buffer | Uint8Array, destDir: string): string;
+declare function isSafeEntry(entry: unknown): entry is string;
+interface CreateBundleOptions {
+    dir: string;
+    agentId: string;
+    runtime?: BundleRuntime;
+    entry?: string;
+    sdk?: string | null;
+    egress?: string[];
+    resources?: BundleResources | null;
+    priv: crypto.KeyObject;
+    publisherPubkey: string;
+}
+declare function createBundle({ dir, agentId, runtime, entry, sdk, egress, resources, priv, publisherPubkey, }: CreateBundleOptions): {
+    bytes: Buffer;
+    sha256: string;
+    manifest: BundleManifest;
+    files: string[];
+    excludedSecrets: string[];
+};
+declare function verifyBundle(bytes: Buffer | Uint8Array, manifest: BundleManifest, { expectedOwner, expectedAgentId }?: {
+    expectedOwner?: string;
+    expectedAgentId?: string;
+}): VerifyBundleResult;
+
+export { BUNDLE_SCHEMA, type BundleManifest, type BundleResources, type BundleRuntime, type CreateBundleOptions, type Keypair, type PackResult, type VerifyBundleResult, base58, base58decode, canonResources, createBundle, fromSeed, isSafeEntry, manifestSigningBytes, packDir, sha256hex, sign, signManifest, unpackTo, verify, verifyBundle, verifyManifest };

package/dist/index.js

@@ -0,0 +1,312 @@
+// src/crypto.ts
+import crypto from "crypto";
+var PKCS8_PREFIX = Buffer.from("302e020100300506032b657004220420", "hex");
+var SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+var B58 = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+var B58_MAP = Object.fromEntries([...B58].map((ch, i) => [ch, i]));
+function base58(buf) {
+  const bytes = Uint8Array.from(buf);
+  let zeros = 0;
+  while (zeros < bytes.length && bytes[zeros] === 0) zeros++;
+  const digits = [];
+  for (let i = zeros; i < bytes.length; i++) {
+    let carry = bytes[i];
+    for (let j = 0; j < digits.length; j++) {
+      carry += digits[j] << 8;
+      digits[j] = carry % 58;
+      carry = carry / 58 | 0;
+    }
+    while (carry) {
+      digits.push(carry % 58);
+      carry = carry / 58 | 0;
+    }
+  }
+  let out = "1".repeat(zeros);
+  for (let k = digits.length - 1; k >= 0; k--) out += B58[digits[k]];
+  return out;
+}
+function base58decode(str) {
+  let zeros = 0;
+  while (zeros < str.length && str[zeros] === "1") zeros++;
+  const bytes = [];
+  for (let i = zeros; i < str.length; i++) {
+    let carry = B58_MAP[str[i]];
+    if (carry === void 0) throw new Error(`invalid base58 char '${str[i]}'`);
+    for (let j = 0; j < bytes.length; j++) {
+      carry += bytes[j] * 58;
+      bytes[j] = carry & 255;
+      carry >>= 8;
+    }
+    while (carry) {
+      bytes.push(carry & 255);
+      carry >>= 8;
+    }
+  }
+  const out = Buffer.alloc(zeros + bytes.length);
+  for (let i = 0; i < bytes.length; i++) out[zeros + bytes.length - 1 - i] = bytes[i];
+  return out;
+}
+function fromSeed(seed) {
+  if (seed.length !== 32) throw new Error("seed must be 32 bytes");
+  const priv = crypto.createPrivateKey({
+    key: Buffer.concat([PKCS8_PREFIX, Buffer.from(seed)]),
+    format: "der",
+    type: "pkcs8"
+  });
+  const spki = crypto.createPublicKey(priv).export({ format: "der", type: "spki" });
+  const pubkey = Buffer.from(spki.subarray(spki.length - 32));
+  return { seed: Buffer.from(seed), priv, pubkey, address: base58(pubkey) };
+}
+function sign(priv, msg) {
+  return crypto.sign(null, Buffer.from(msg), priv);
+}
+function verify(pubkey, msg, sig) {
+  const pub = crypto.createPublicKey({
+    key: Buffer.concat([SPKI_PREFIX, Buffer.from(pubkey)]),
+    format: "der",
+    type: "spki"
+  });
+  return crypto.verify(null, Buffer.from(msg), pub, Buffer.from(sig));
+}
+var sha256hex = (s) => crypto.createHash("sha256").update(s).digest("hex");
+
+// src/bundle.ts
+import crypto2 from "crypto";
+import fs from "fs";
+import path from "path";
+import os from "os";
+import zlib from "zlib";
+import { execFileSync } from "child_process";
+var BUNDLE_SCHEMA = 1;
+function canonResources(r) {
+  return r ? { maxCpu: r.maxCpu ?? null, maxMemoryMb: r.maxMemoryMb ?? null } : null;
+}
+function manifestSigningBytes(m) {
+  const canon = {
+    agentId: m.agentId,
+    egress: Array.isArray(m.egress) ? [...m.egress].sort() : [],
+    entry: m.entry,
+    resources: canonResources(m.resources),
+    runtime: m.runtime,
+    schema: BUNDLE_SCHEMA,
+    sdk: m.sdk ?? null,
+    sha256: m.sha256
+  };
+  return Buffer.from(JSON.stringify(canon));
+}
+function signManifest(m, priv) {
+  return base58(sign(priv, manifestSigningBytes(m)));
+}
+function verifyManifest(m) {
+  if (!m || !m.sig || !m.publisherPubkey) return false;
+  try {
+    return verify(base58decode(m.publisherPubkey), manifestSigningBytes(m), base58decode(m.sig));
+  } catch {
+    return false;
+  }
+}
+var ALWAYS_IGNORE = [".git/", "node_modules/", ".hg/", ".svn/", ".DS_Store", "Thumbs.db", "*.log"];
+var SECRET_IGNORE = [
+  ".env",
+  ".env.*",
+  "*.env",
+  "*.pem",
+  "*.key",
+  "*.p12",
+  "*.pfx",
+  "id.json",
+  "id_*.json",
+  "*keypair*.json",
+  "*keypair*",
+  "wallet.json",
+  "*.wallet",
+  ".npmrc",
+  ".netrc",
+  "secrets.json",
+  "secrets.*",
+  ".secrets/",
+  ".ssh/",
+  ".aws/",
+  ".gnupg/",
+  ".circuit/"
+];
+var _reCache = /* @__PURE__ */ new Map();
+function globRe(glob) {
+  const cached = _reCache.get(glob);
+  if (cached) return cached;
+  let body = "";
+  for (const ch of glob) {
+    if (ch === "*") body += "[^/]*";
+    else if (ch === "?") body += "[^/]";
+    else body += ch.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  }
+  const re = new RegExp(`^${body}$`);
+  _reCache.set(glob, re);
+  return re;
+}
+function matchAny(rel, name, patterns) {
+  for (const raw of patterns) {
+    let p = (raw || "").trim();
+    if (!p || p.startsWith("#") || p.startsWith("!")) continue;
+    if (p.endsWith("/")) p = p.slice(0, -1);
+    if (p.startsWith("/")) p = p.slice(1);
+    if (!p) continue;
+    if (p.includes("/")) {
+      if (globRe(p).test(rel) || rel === p || rel.startsWith(`${p}/`)) return true;
+    } else if (globRe(p).test(name)) {
+      return true;
+    }
+  }
+  return false;
+}
+function readIgnore(dir, file) {
+  try {
+    return fs.readFileSync(path.join(dir, file), "utf8").split("\n");
+  } catch {
+    return [];
+  }
+}
+function listIncluded(dir) {
+  const userIgnore = [...readIgnore(dir, ".gitignore"), ...readIgnore(dir, ".circuitignore")];
+  const files = [];
+  const excludedSecrets = [];
+  const rec = (cur, rel) => {
+    let names;
+    try {
+      names = fs.readdirSync(cur).sort();
+    } catch {
+      return;
+    }
+    for (const name of names) {
+      const r = rel ? `${rel}/${name}` : name;
+      let st;
+      try {
+        st = fs.lstatSync(path.join(cur, name));
+      } catch {
+        continue;
+      }
+      if (st.isSymbolicLink()) continue;
+      if (matchAny(r, name, SECRET_IGNORE)) {
+        excludedSecrets.push(r + (st.isDirectory() ? "/" : ""));
+        continue;
+      }
+      if (matchAny(r, name, ALWAYS_IGNORE)) continue;
+      if (matchAny(r, name, userIgnore)) continue;
+      if (st.isDirectory()) rec(path.join(cur, name), r);
+      else if (st.isFile()) files.push(r);
+    }
+  };
+  rec(dir, "");
+  return { files: files.sort(), excludedSecrets };
+}
+function ustarHeader(name, size, mode = 420) {
+  const buf = Buffer.alloc(512);
+  let nm = name;
+  let prefix = "";
+  if (Buffer.byteLength(nm) > 100) {
+    let split = -1;
+    for (let p = nm.indexOf("/"); p !== -1; p = nm.indexOf("/", p + 1)) {
+      if (Buffer.byteLength(nm.slice(p + 1)) <= 100 && Buffer.byteLength(nm.slice(0, p)) <= 155) {
+        split = p;
+        break;
+      }
+    }
+    if (split === -1) throw new Error(`path too long to bundle (USTAR limit): ${name}`);
+    prefix = nm.slice(0, split);
+    nm = nm.slice(split + 1);
+  }
+  buf.write(nm, 0, 100, "utf8");
+  buf.write((mode & 4095).toString(8).padStart(7, "0") + "\0", 100, 8, "ascii");
+  buf.write("0000000\0", 108, 8, "ascii");
+  buf.write("0000000\0", 116, 8, "ascii");
+  buf.write(size.toString(8).padStart(11, "0") + "\0", 124, 12, "ascii");
+  buf.write("00000000000\0", 136, 12, "ascii");
+  buf.write("        ", 148, 8, "ascii");
+  buf.write("0", 156, 1, "ascii");
+  buf.write("ustar\0", 257, 6, "ascii");
+  buf.write("00", 263, 2, "ascii");
+  if (prefix) buf.write(prefix, 345, 155, "utf8");
+  let sum = 0;
+  for (let i = 0; i < 512; i++) sum += buf[i];
+  buf.write((sum & 262143).toString(8).padStart(6, "0") + "\0 ", 148, 8, "ascii");
+  return buf;
+}
+function tarGzip(dir, files) {
+  const blocks = [];
+  for (const rel of files) {
+    const data = fs.readFileSync(path.join(dir, rel));
+    blocks.push(ustarHeader(rel, data.length), data);
+    const pad = (512 - data.length % 512) % 512;
+    if (pad) blocks.push(Buffer.alloc(pad));
+  }
+  blocks.push(Buffer.alloc(1024));
+  const gz = zlib.gzipSync(Buffer.concat(blocks), { level: 9 });
+  gz.writeUInt32LE(0, 4);
+  gz[9] = 255;
+  return gz;
+}
+function packDir(dir) {
+  const { files, excludedSecrets } = listIncluded(dir);
+  if (!files.length) throw new Error("nothing to bundle \u2014 every file was excluded by ignore rules");
+  const bytes = tarGzip(dir, files);
+  return { bytes, sha256: sha256hex(bytes), files, excludedSecrets };
+}
+function unpackTo(bytes, destDir) {
+  fs.mkdirSync(destDir, { recursive: true });
+  const tmp = path.join(os.tmpdir(), `cbundle-${crypto2.randomBytes(6).toString("hex")}.tgz`);
+  try {
+    fs.writeFileSync(tmp, bytes);
+    execFileSync("tar", ["--no-same-owner", "-xzf", tmp, "-C", destDir], { stdio: "pipe" });
+  } finally {
+    fs.rmSync(tmp, { force: true });
+  }
+  return destDir;
+}
+function isSafeEntry(entry) {
+  return typeof entry === "string" && /^[\w][\w.-]*$/.test(entry) && entry !== "." && entry !== ".." && !entry.includes("/");
+}
+function createBundle({
+  dir,
+  agentId,
+  runtime = "node",
+  entry = "agent.js",
+  sdk = null,
+  egress = [],
+  resources = null,
+  priv,
+  publisherPubkey
+}) {
+  if (runtime !== "node" && runtime !== "oci") throw new Error(`unknown runtime '${runtime}'`);
+  if (!isSafeEntry(entry)) throw new Error(`unsafe entry '${entry}'`);
+  if (!fs.existsSync(path.join(dir, entry))) throw new Error(`entry '${entry}' not found in ${dir}`);
+  const { bytes, sha256, files, excludedSecrets } = packDir(dir);
+  const manifest = { schema: BUNDLE_SCHEMA, agentId, runtime, entry, sdk, egress, resources, sha256, publisherPubkey };
+  manifest.sig = signManifest(manifest, priv);
+  return { bytes, sha256, manifest, files, excludedSecrets };
+}
+function verifyBundle(bytes, manifest, { expectedOwner, expectedAgentId } = {}) {
+  if (sha256hex(bytes) !== manifest.sha256) return { ok: false, code: "sha256-mismatch" };
+  if (!verifyManifest(manifest)) return { ok: false, code: "bad-manifest-sig" };
+  if (expectedOwner && manifest.publisherPubkey !== expectedOwner) return { ok: false, code: "publisher-not-owner" };
+  if (expectedAgentId && manifest.agentId !== expectedAgentId) return { ok: false, code: "agent-id-mismatch" };
+  if (!isSafeEntry(manifest.entry)) return { ok: false, code: "bad-entry" };
+  return { ok: true };
+}
+export {
+  BUNDLE_SCHEMA,
+  base58,
+  base58decode,
+  canonResources,
+  createBundle,
+  fromSeed,
+  isSafeEntry,
+  manifestSigningBytes,
+  packDir,
+  sha256hex,
+  sign,
+  signManifest,
+  unpackTo,
+  verify,
+  verifyBundle,
+  verifyManifest
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@circuit-llm/bundle",
+  "version": "0.2.1",
+  "description": "Circuit SDK agent bundles — build, sign, verify, and unpack content-addressed (sha256) signed agent bundles. The canonical codec shared by the Circuit agent cloud and the circuit CLI.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "test": "node --experimental-strip-types --conditions=development --test test/*.test.ts",
+    "typecheck": "tsc -p tsconfig.json",
+    "build": "tsup src/index.ts --format esm --dts --clean --out-dir dist",
+    "prepack": "tsup src/index.ts --format esm --dts --clean --out-dir dist"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Circuit-LLM/circuit-sdk.git",
+    "directory": "packages/bundle"
+  },
+  "homepage": "https://github.com/Circuit-LLM/circuit-sdk/tree/main/packages/bundle#readme",
+  "bugs": {
+    "url": "https://github.com/Circuit-LLM/circuit-sdk/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}