oathbound 0.1.0

package/README.md

@@ -0,0 +1,83 @@
+# oathbound
+
+Install and verify Claude Code skills from the [Oath Bound](https://oathbound.ai) registry.
+
+Skills are downloaded as tarballs from the registry and verified using SHA-256 content hashing. Every session start and every tool invocation can be checked against the registry to detect tampering.
+
+## Installation
+
+Requires the [Bun](https://bun.sh) runtime.
+
+```sh
+bun add -g oathbound
+```
+
+Or via npm:
+
+```sh
+npm install -g oathbound
+```
+
+## Usage
+
+### Install a skill
+
+```sh
+oathbound pull <namespace/skill-name>
+oathbound install <namespace/skill-name>
+```
+
+Downloads the latest version of a skill from the registry, verifies the tarball hash, and extracts it into your `.claude/skills/` directory.
+
+### Verify all installed skills (SessionStart hook)
+
+```sh
+oathbound verify
+```
+
+Reads session context from stdin, hashes every skill directory under `.claude/skills/`, and compares each hash against the registry. Writes a session state file so subsequent checks are fast. Exits non-zero if any skill fails verification.
+
+### Check a skill before tool execution (PreToolUse hook)
+
+```sh
+oathbound verify --check
+```
+
+Reads tool invocation context from stdin, re-hashes the relevant skill directory, and compares it against the hash recorded at session start. If the skill was modified after verification, the hook denies execution.
+
+## Hook integration
+
+oathbound is designed to run as [Claude Code hooks](https://docs.anthropic.com/en/docs/claude-code/hooks). Add it to your `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "type": "command",
+        "command": "oathbound verify"
+      }
+    ],
+    "PreToolUse": [
+      {
+        "type": "command",
+        "command": "oathbound verify --check"
+      }
+    ]
+  }
+}
+```
+
+## How it works
+
+1. **Pull**: Downloads a skill tarball from Supabase storage, verifies the SHA-256 hash of the tarball against the registry, and extracts the skill into `.claude/skills/`.
+
+2. **SessionStart verification**: Walks each subdirectory in `.claude/skills/`, collects all files (excluding `node_modules`, lockfiles, and `.DS_Store`), sorts them by path, hashes each file with SHA-256, then hashes the combined manifest. The resulting content hash is compared against the registry. Verified hashes are written to a temporary session state file.
+
+3. **PreToolUse verification**: Re-hashes the skill directory on disk and compares it against the hash saved at session start. If the content has changed since verification, the tool invocation is denied. This detects mid-session tampering.
+
+The content hash algorithm is deterministic: files are sorted lexicographically by relative path, each file is individually hashed, and the concatenated `path\0hash` lines are hashed together. The same algorithm runs on both the registry (frontend) and the CLI to guarantee parity.
+
+## License
+
+Apache 2.0

package/bin/cli.cjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+// Thin wrapper that spawns the platform binary downloaded by postinstall.
+
+const { execFileSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+const ext = process.platform === "win32" ? ".exe" : "";
+const binary = path.join(__dirname, `oathbound${ext}`);
+
+if (!fs.existsSync(binary)) {
+  console.error(
+    "oathbound binary not found. Run `npm rebuild oathbound` or reinstall the package."
+  );
+  process.exit(1);
+}
+
+try {
+  execFileSync(binary, process.argv.slice(2), { stdio: "inherit" });
+} catch (err) {
+  process.exit(err.status ?? 1);
+}

package/cli.ts

@@ -0,0 +1,438 @@
+#!/usr/bin/env bun
+
+import { createClient } from '@supabase/supabase-js';
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { writeFileSync, readFileSync, unlinkSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { tmpdir } from 'node:os';
+
+const VERSION = '0.1.0';
+
+// --- Supabase ---
+const SUPABASE_URL = 'https://mjnfqagwuewhgwbtrdgs.supabase.co';
+const SUPABASE_ANON_KEY = 'sb_publishable_T-rk0azNRqAMLLGCyadyhQ_ulk9685n';
+
+// --- ANSI ---
+const TEAL = '\x1b[38;2;63;168;164m'; // brand teal #3fa8a4
+const GREEN = '\x1b[32m';
+const RED = '\x1b[31m';
+const DIM = '\x1b[2m';
+const BOLD = '\x1b[1m';
+const RESET = '\x1b[0m';
+
+// --- Types ---
+interface SkillRow {
+  name: string;
+  namespace: string;
+  version: number;
+  tar_hash: string;
+  storage_path: string;
+}
+
+// --- Helpers ---
+function usage(exitCode = 1): never {
+  console.log(`
+${BOLD}oathbound${RESET} — install and verify skills
+
+${DIM}Usage:${RESET}
+  oathbound pull <namespace/skill-name>
+  oathbound install <namespace/skill-name>
+  oathbound verify              ${DIM}SessionStart hook — verify all skills${RESET}
+  oathbound verify --check      ${DIM}PreToolUse hook — check skill integrity${RESET}
+
+${DIM}Options:${RESET}
+  --help, -h      Show this help message
+  --version, -v   Show version
+`);
+  process.exit(exitCode);
+}
+
+function fail(message: string, detail?: string): never {
+  console.log(`\n${BOLD}${RED} ✗ ${message}${RESET}`);
+  if (detail) {
+    console.log(`${RED}   ${detail}${RESET}`);
+  }
+  process.exit(1);
+}
+
+function spinner(text: string): { stop: () => void } {
+  const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+  let i = 0;
+  process.stdout.write(`${TEAL} ${frames[0]} ${text}${RESET}`);
+  const interval = setInterval(() => {
+    i = (i + 1) % frames.length;
+    process.stdout.write(`\r${TEAL} ${frames[i]} ${text}${RESET}`);
+  }, 80);
+  return {
+    stop() {
+      clearInterval(interval);
+      process.stdout.write('\r\x1b[2K');
+    },
+  };
+}
+
+function findSkillsDir(): string {
+  const cwd = process.cwd();
+  const normalized = cwd.replace(/\/+$/, '');
+
+  // Already inside .claude/skills
+  if (normalized.endsWith('.claude/skills')) return cwd;
+
+  // Inside .claude — check for skills/ subdir
+  if (normalized.endsWith('.claude')) {
+    const skills = join(cwd, 'skills');
+    if (existsSync(skills)) return skills;
+  }
+
+  // Check cwd/.claude/skills directly
+  const direct = join(cwd, '.claude', 'skills');
+  if (existsSync(direct)) return direct;
+
+  // Recurse downward (skip noise, limited depth)
+  const SKIP = new Set(['node_modules', '.git', 'dist', 'build', '.next']);
+  function search(dir: string, depth: number): string | null {
+    if (depth <= 0) return null;
+    try {
+      const entries = readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory() || SKIP.has(entry.name)) continue;
+        if (entry.name === '.claude') {
+          const skills = join(dir, '.claude', 'skills');
+          if (existsSync(skills)) return skills;
+        }
+      }
+      for (const entry of entries) {
+        if (!entry.isDirectory() || SKIP.has(entry.name) || entry.name.startsWith('.')) continue;
+        const result = search(join(dir, entry.name), depth - 1);
+        if (result) return result;
+      }
+    } catch {
+      // permission denied, etc.
+    }
+    return null;
+  }
+
+  return search(cwd, 5) ?? cwd;
+}
+
+function parseSkillArg(arg: string): { namespace: string; name: string } | null {
+  const slash = arg.indexOf('/');
+  if (slash < 1 || slash === arg.length - 1) return null;
+  return { namespace: arg.slice(0, slash), name: arg.slice(slash + 1) };
+}
+
+// --- Content hashing (must match frontend/lib/content-hash.ts) ---
+const HASH_EXCLUDED = new Set([
+  'node_modules',
+  'bun.lock',
+  'package-lock.json',
+  'yarn.lock',
+  '.DS_Store',
+]);
+
+function collectFiles(dir: string, base: string = dir): { path: string; content: Buffer }[] {
+  const results: { path: string; content: Buffer }[] = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (HASH_EXCLUDED.has(entry.name)) continue;
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...collectFiles(full, base));
+    } else if (entry.isFile()) {
+      results.push({ path: relative(base, full), content: readFileSync(full) });
+    }
+  }
+  return results;
+}
+
+function contentHash(files: { path: string; content: Buffer }[]): string {
+  const sorted = files.toSorted((a, b) => a.path.localeCompare(b.path));
+  const lines = sorted.map((f) => {
+    const h = createHash('sha256').update(f.content).digest('hex');
+    return `${f.path}\0${h}`;
+  });
+  return createHash('sha256').update(lines.join('\n')).digest('hex');
+}
+
+function hashSkillDir(skillDir: string): string {
+  const files = collectFiles(skillDir);
+  return contentHash(files);
+}
+
+// --- Session state file ---
+interface SessionState {
+  verified: Record<string, string>; // skill name → content_hash
+  rejected: { name: string; reason: string }[];
+  ok: boolean;
+}
+
+function sessionStatePath(sessionId: string): string {
+  return join(tmpdir(), `oathbound-${sessionId}.json`);
+}
+
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of Bun.stdin.stream()) {
+    chunks.push(Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString('utf-8');
+}
+
+// --- Verify (SessionStart hook) ---
+async function verify(): Promise<void> {
+  const input = JSON.parse(await readStdin());
+  const sessionId: string = input.session_id;
+  if (!sessionId) {
+    process.stderr.write('oathbound verify: no session_id in stdin\n');
+    process.exit(1);
+  }
+
+  const skillsDir = findSkillsDir();
+
+  // Guard: findSkillsDir() falls back to cwd if no .claude/skills found.
+  // In verify mode, we must NOT hash the entire project — only .claude/skills.
+  if (!skillsDir.endsWith('.claude/skills') && !skillsDir.includes('.claude/skills')) {
+    const state: SessionState = { verified: {}, rejected: [], ok: true };
+    writeFileSync(sessionStatePath(sessionId), JSON.stringify(state));
+    console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: 'Oathbound: no .claude/skills/ directory found — nothing to verify.' } }));
+    process.exit(0);
+  }
+
+  // List skill subdirectories
+  const entries = readdirSync(skillsDir, { withFileTypes: true });
+  const skillDirs = entries.filter((e) => e.isDirectory() && !e.name.startsWith('.'));
+
+  if (skillDirs.length === 0) {
+    const state: SessionState = { verified: {}, rejected: [], ok: true };
+    writeFileSync(sessionStatePath(sessionId), JSON.stringify(state));
+    console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: 'Oathbound: no skills installed — nothing to verify.' } }));
+    process.exit(0);
+  }
+
+  // Hash each local skill
+  const localHashes: Record<string, string> = {};
+  for (const dir of skillDirs) {
+    const fullPath = join(skillsDir, dir.name);
+    localHashes[dir.name] = hashSkillDir(fullPath);
+  }
+
+  // Fetch registry hashes from Supabase (latest version per skill name)
+  const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY);
+  const { data: skills, error } = await supabase
+    .from('skills')
+    .select('name, namespace, content_hash, version')
+    .order('version', { ascending: false });
+
+  if (error) {
+    process.stderr.write(`oathbound verify: failed to query registry: ${error.message}\n`);
+    process.exit(1);
+  }
+
+  // Build lookup: skill name → latest content_hash (dedupe by taking first per name)
+  const registryHashes = new Map<string, string>();
+  for (const skill of skills ?? []) {
+    if (!skill.content_hash) continue;
+    if (!registryHashes.has(skill.name)) {
+      registryHashes.set(skill.name, skill.content_hash);
+    }
+  }
+
+  const verified: Record<string, string> = {};
+  const rejected: { name: string; reason: string }[] = [];
+
+  for (const [name, localHash] of Object.entries(localHashes)) {
+    const registryHash = registryHashes.get(name);
+    if (!registryHash) {
+      rejected.push({ name, reason: 'not in registry' });
+    } else if (localHash !== registryHash) {
+      rejected.push({ name, reason: `content hash mismatch (local: ${localHash.slice(0, 8)}…, registry: ${registryHash.slice(0, 8)}…)` });
+    } else {
+      verified[name] = localHash;
+    }
+  }
+
+  const ok = rejected.length === 0;
+  const state: SessionState = { verified, rejected, ok };
+  writeFileSync(sessionStatePath(sessionId), JSON.stringify(state));
+
+  if (ok) {
+    const names = Object.keys(verified).join(', ');
+    console.log(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'SessionStart',
+        additionalContext: `Oathbound: all ${Object.keys(verified).length} skill(s) verified against registry [${names}]. Skills are safe to use.`,
+      },
+    }));
+    process.exit(0);
+  } else {
+    const lines = rejected.map((r) => `  - ${r.name}: ${r.reason}`);
+    process.stderr.write(`Oathbound: skill verification failed!\n${lines.join('\n')}\nDo NOT use unverified skills.\n`);
+    process.exit(2);
+  }
+}
+
+// --- Verify --check (PreToolUse hook) ---
+async function verifyCheck(): Promise<void> {
+  const input = JSON.parse(await readStdin());
+  const sessionId: string = input.session_id;
+  const skillName: string | undefined = input.tool_input?.skill;
+
+  if (!sessionId || !skillName) {
+    // Can't verify — allow through (non-skill invocation or missing context)
+    process.exit(0);
+  }
+
+  const stateFile = sessionStatePath(sessionId);
+  if (!existsSync(stateFile)) {
+    // No session state — session start hook didn't run or no skills installed
+    process.exit(0);
+  }
+
+  const state: SessionState = JSON.parse(readFileSync(stateFile, 'utf-8'));
+
+  // Extract just the skill name (strip namespace/ prefix if present)
+  const baseName = skillName.includes(':') ? skillName.split(':').pop()! : skillName;
+
+  // Find the skill directory and re-hash
+  const skillsDir = findSkillsDir();
+  const skillDir = join(skillsDir, baseName);
+
+  if (!existsSync(skillDir) || !statSync(skillDir).isDirectory()) {
+    console.log(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: `Oathbound: skill directory not found for "${baseName}"`,
+      },
+    }));
+    process.exit(0);
+  }
+
+  const currentHash = hashSkillDir(skillDir);
+  const sessionHash = state.verified[baseName];
+
+  if (!sessionHash) {
+    console.log(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: `Oathbound: skill "${baseName}" was not verified at session start`,
+      },
+    }));
+    process.exit(0);
+  }
+
+  if (currentHash !== sessionHash) {
+    console.log(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: `Oathbound: skill "${baseName}" was modified since session start (tampering detected)`,
+      },
+    }));
+    process.exit(0);
+  }
+
+  // Hash matches — allow
+  process.exit(0);
+}
+
+// --- Main ---
+async function pull(skillArg: string): Promise<void> {
+  const parsed = parseSkillArg(skillArg);
+  if (!parsed) usage();
+  const { namespace, name } = parsed;
+  const fullName = `${namespace}/${name}`;
+
+  console.log(`\n${TEAL} ↓ Pulling ${fullName}...${RESET}`);
+
+  const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY);
+
+  // 1. Query for the skill
+  const { data: skill, error } = await supabase
+    .from('skills')
+    .select('name, namespace, version, tar_hash, storage_path')
+    .eq('namespace', namespace)
+    .eq('name', name)
+    .order('version', { ascending: false })
+    .limit(1)
+    .single<SkillRow>();
+
+  if (error || !skill) {
+    fail(`Skill not found: ${fullName}`);
+  }
+
+  // 2. Download the tar from storage
+  const { data: blob, error: downloadError } = await supabase
+    .storage
+    .from('skills')
+    .download(skill.storage_path);
+
+  if (downloadError || !blob) {
+    fail('Download failed', downloadError?.message ?? 'Unknown storage error');
+  }
+
+  const buffer = Buffer.from(await blob.arrayBuffer());
+  const tarFile = `${name}.tar.gz`;
+
+  // 3. Hash and verify
+  const verify = spinner('Verifying...');
+  const hash = createHash('sha256').update(buffer).digest('hex');
+  verify.stop();
+
+  if (hash !== skill.tar_hash) {
+    fail('Verification failed', `Downloaded file does not match expected hash for ${fullName}`);
+  }
+
+  // 4. Find target directory and extract
+  const skillsDir = findSkillsDir();
+  writeFileSync(tarFile, buffer);
+  try {
+    execFileSync('tar', ['-xf', tarFile, '-C', skillsDir], { stdio: 'pipe' });
+  } catch (e: unknown) {
+    unlinkSync(tarFile);
+    const msg = e instanceof Error ? e.message : 'Unknown error';
+    fail('Extraction failed', msg);
+  }
+  unlinkSync(tarFile);
+
+  // 5. Success
+  console.log(`${BOLD}${GREEN} ✓ Skill verified${RESET}`);
+  console.log(`${DIM}   ${fullName} v${skill.version}${RESET}`);
+  console.log(`${DIM}   → ${join(skillsDir, name)}${RESET}`);
+}
+
+// --- Entry ---
+const args = Bun.argv.slice(2);
+const subcommand = args[0];
+
+if (subcommand === '--help' || subcommand === '-h') {
+  usage(0);
+}
+
+if (subcommand === '--version' || subcommand === '-v') {
+  console.log(`oathbound ${VERSION}`);
+  process.exit(0);
+}
+
+if (subcommand === 'verify') {
+  const isCheck = args.includes('--check');
+  const run = isCheck ? verifyCheck : verify;
+  run().catch((err: unknown) => {
+    const msg = err instanceof Error ? err.message : 'Unknown error';
+    process.stderr.write(`oathbound verify: ${msg}\n`);
+    process.exit(1);
+  });
+} else {
+  const PULL_ALIASES = new Set(['pull', 'i', 'install']);
+  const skillArg = args[1];
+
+  if (!subcommand || !PULL_ALIASES.has(subcommand) || !skillArg) {
+    usage();
+  }
+
+  pull(skillArg).catch((err: unknown) => {
+    const msg = err instanceof Error ? err.message : 'Unknown error';
+    fail('Unexpected error', msg);
+  });
+}

package/install.cjs

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+
+// Postinstall script: downloads the correct platform binary from GitHub Releases.
+// Skips download in CI (binaries don't exist yet during the build job).
+
+if (process.env.CI) {
+  console.log("oathbound: skipping binary download in CI");
+  process.exit(0);
+}
+
+const https = require("https");
+const fs = require("fs");
+const path = require("path");
+
+const pkg = require("./package.json");
+const VERSION = pkg.version;
+const REPO = "Joshuatanderson/oath-bound";
+
+const PLATFORM_MAP = {
+  darwin: "darwin",
+  linux: "linux",
+  win32: "windows",
+};
+
+const ARCH_MAP = {
+  arm64: "arm64",
+  x64: "x64",
+};
+
+function getBinaryName() {
+  const platform = PLATFORM_MAP[process.platform];
+  const arch = ARCH_MAP[process.arch];
+  if (!platform || !arch) {
+    throw new Error(
+      `Unsupported platform: ${process.platform}-${process.arch}`
+    );
+  }
+  const ext = process.platform === "win32" ? ".exe" : "";
+  return `oathbound-${platform}-${arch}${ext}`;
+}
+
+function download(url) {
+  return new Promise((resolve, reject) => {
+    https
+      .get(url, (res) => {
+        // Follow redirects (GitHub sends 302 to S3)
+        if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+          return download(res.headers.location).then(resolve, reject);
+        }
+        if (res.statusCode !== 200) {
+          return reject(new Error(`Download failed: HTTP ${res.statusCode} for ${url}`));
+        }
+        const chunks = [];
+        res.on("data", (chunk) => chunks.push(chunk));
+        res.on("end", () => resolve(Buffer.concat(chunks)));
+        res.on("error", reject);
+      })
+      .on("error", reject);
+  });
+}
+
+async function main() {
+  const binaryName = getBinaryName();
+  const url = `https://github.com/${REPO}/releases/download/v${VERSION}/${binaryName}`;
+  const destDir = path.join(__dirname, "bin");
+  const ext = process.platform === "win32" ? ".exe" : "";
+  const dest = path.join(destDir, `oathbound${ext}`);
+
+  console.log(`oathbound: downloading ${binaryName} from v${VERSION} release...`);
+
+  fs.mkdirSync(destDir, { recursive: true });
+
+  const data = await download(url);
+  fs.writeFileSync(dest, data);
+  fs.chmodSync(dest, 0o755);
+
+  console.log(`oathbound: installed to ${dest}`);
+}
+
+main().catch((err) => {
+  console.error(`oathbound install failed: ${err.message}`);
+  console.error("You can download the binary manually from:");
+  console.error(`  https://github.com/${REPO}/releases/tag/v${VERSION}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "oathbound",
+  "version": "0.1.0",
+  "description": "Install verified Claude Code skills from the Oath Bound registry",
+  "license": "Apache-2.0",
+  "author": "Josh Anderson",
+  "homepage": "https://oathbound.ai",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Joshuatanderson/oath-bound"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "skills",
+    "verification",
+    "integrity",
+    "security",
+    "ai-tools"
+  ],
+  "type": "module",
+  "bin": {
+    "oathbound": "./bin/cli.cjs"
+  },
+  "files": [
+    "cli.ts",
+    "bin/cli.cjs",
+    "install.cjs"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "bun build ./cli.ts --compile --outfile dist/oathbound",
+    "build:macos-arm64": "bun build ./cli.ts --compile --target=bun-darwin-arm64 --outfile dist/oathbound-macos-arm64",
+    "build:macos-x64": "bun build ./cli.ts --compile --target=bun-darwin-x64 --outfile dist/oathbound-macos-x64",
+    "build:linux-x64": "bun build ./cli.ts --compile --target=bun-linux-x64 --outfile dist/oathbound-linux-x64",
+    "build:linux-arm64": "bun build ./cli.ts --compile --target=bun-linux-arm64 --outfile dist/oathbound-linux-arm64",
+    "build:windows-x64": "bun build ./cli.ts --compile --target=bun-windows-x64 --outfile dist/oathbound-windows-x64",
+    "build:windows-arm64": "bun build ./cli.ts --compile --target=bun-windows-arm64 --outfile dist/oathbound-windows-arm64",
+    "build:all": "bun run build:macos-arm64 && bun run build:macos-x64 && bun run build:linux-x64 && bun run build:linux-arm64 && bun run build:windows-x64 && bun run build:windows-arm64",
+    "test": "bun test",
+    "postinstall": "node install.cjs"
+  },
+  "dependencies": {
+    "@supabase/supabase-js": "^2"
+  }
+}