ckforensics 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 phong28zk
+
+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,126 @@
+# ckforensics
+
+**Forensic CLI for Claude Code sessions — audit, redact, export your transcripts.**
+
+[![CI](https://github.com/phong28zk/ckforensics/actions/workflows/ci.yml/badge.svg)](https://github.com/phong28zk/ckforensics/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/ckforensics)](https://www.npmjs.com/package/ckforensics)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Bun](https://img.shields.io/badge/runtime-Bun-f472b6)](https://bun.sh)
+
+---
+
+## Why ckforensics
+
+**Pain:**
+- Claude Code transcripts stored as raw JSONL — no way to summarize or audit them
+- Sensitive keys / tokens leak into `.jsonl` files that get committed or shared
+- No visibility into token usage, tool calls, or subagent orchestration patterns
+
+**Solution:**
+- Ingest all sessions into a local SQLite DB — queryable, indexed, stays on disk
+- Redact 9 secret patterns (API keys, AWS creds, JWTs, PEM blocks) before any export
+- CLI commands for summary, audit, session diff, and export — no cloud, no telemetry
+
+---
+
+## Install
+
+```bash
+npm i -g ckforensics
+```
+
+Or download a prebuilt binary from [Releases](https://github.com/phong28zk/ckforensics/releases):
+
+```bash
+# Linux x64
+curl -L https://github.com/phong28zk/ckforensics/releases/latest/download/ckforensics-linux-x64 \
+  -o /usr/local/bin/ckforensics && chmod +x /usr/local/bin/ckforensics
+```
+
+Platforms: `linux-x64`, `linux-arm64`, `macos-x64`, `macos-arm64`, `windows-x64`
+
+---
+
+## Quick Start
+
+```bash
+# 1. Ingest all sessions from default Claude Code path
+ckforensics ingest
+
+# 2. Summarize recent sessions
+ckforensics summary --last 7d
+
+# 3. Audit a session for leaked secrets
+ckforensics audit --session <session-id>
+
+# 4. Redact and export a session as Markdown
+ckforensics export --session <session-id> --format markdown --redact
+
+# 5. Health check (verify DB integrity + schema version)
+ckforensics doctor
+```
+
+> Sessions are stored in `~/.ckforensics/db.sqlite` (mode `0600`). Nothing leaves your machine.
+
+---
+
+## Screenshots
+
+```
+[ terminal recording placeholder — see docs/demo.gif once available ]
+```
+
+---
+
+## Feature Matrix
+
+| Feature | ckforensics | ccusage | Native CC |
+|---------|:-----------:|:-------:|:---------:|
+| Local SQLite storage | ✅ | ✅ | ❌ |
+| Token usage analytics | ✅ | ✅ | ❌ |
+| Secret redaction (9 rules) | ✅ | ❌ | ❌ |
+| Session audit trail | ✅ | ❌ | ❌ |
+| Subagent tracking | ✅ | ❌ | ❌ |
+| Markdown / JSON export | ✅ | ❌ | ❌ |
+| Diff between sessions | ✅ | ❌ | ❌ |
+| Offline / no telemetry | ✅ | ✅ | ✅ |
+| Cross-platform binaries | ✅ | ❌ | ✅ |
+
+---
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `ingest` | Parse JSONL files → SQLite |
+| `summary` | Token + cost summary for a time range |
+| `audit` | Detect secrets / anomalies in a session |
+| `export` | Output session as Markdown or JSON |
+| `redact` | Strip secrets from JSONL in-place |
+| `sessions` | List sessions with metadata |
+| `path` | Show DB path and stats |
+| `doctor` | Verify DB integrity and schema version |
+
+---
+
+## Architecture
+
+See [docs/architecture.md](docs/architecture.md) — module overview and data-flow diagram.
+
+## Threat Model
+
+See [docs/threat-model.md](docs/threat-model.md) — privacy stance, redaction guarantees, and known gaps.
+
+## Schema
+
+See [docs/jsonl-schema-v1.md](docs/jsonl-schema-v1.md) — reverse-engineered Claude Code JSONL event types.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) — dev setup, PR checklist, fixture contribution flow.
+
+---
+
+## License
+
+MIT — [LICENSE](LICENSE) — Copyright (c) 2026 phong28zk

package/bin/ckforensics.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+/**
+ * bin/ckforensics.js — npm wrapper shim for ckforensics.
+ *
+ * This file is the npm `bin` entry point. It detects the current platform/arch,
+ * locates the matching prebuilt binary inside node_modules/ckforensics/binaries/,
+ * and delegates execution via spawnSync (stdio: inherit + exit code propagation).
+ *
+ * Written as ESM because package.json sets "type": "module".
+ *
+ * Requirements:
+ *   - Node 18+ (uses only built-in modules: path, child_process, fs, url)
+ *   - Binary must have been placed by scripts/postinstall.js (runs on npm install)
+ *
+ * Error behaviour:
+ *   - Binary missing → clear message pointing to postinstall, exits 1
+ *   - spawnSync error  → prints OS error, exits 1
+ */
+
+import { spawnSync } from "child_process";
+import { existsSync } from "fs";
+import { createRequire } from "module";
+import { fileURLToPath } from "url";
+import path from "path";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname  = path.dirname(__filename);
+
+// ── Platform → binary name mapping ───────────────────────────────────────────
+
+// darwin-x64 (Intel Mac) intentionally omitted — see release.yml comment.
+// Intel Mac users: build from source via `bun build --compile --target=bun-darwin-x64`.
+const PLATFORM_MAP = {
+  "linux-x64":    "ckforensics-linux-x64",
+  "linux-arm64":  "ckforensics-linux-arm64",
+  "darwin-arm64": "ckforensics-darwin-arm64",
+  "win32-x64":    "ckforensics-win-x64.exe",
+};
+
+// ── Resolve binary path ───────────────────────────────────────────────────────
+
+const platform = process.platform;  // "linux" | "darwin" | "win32"
+const arch     = process.arch;      // "x64" | "arm64"
+const key      = `${platform}-${arch}`;
+const binName  = PLATFORM_MAP[key];
+
+if (!binName) {
+  process.stderr.write(
+    `[ckforensics] Unsupported platform: ${platform}-${arch}\n` +
+    `Supported: ${Object.keys(PLATFORM_MAP).join(", ")}\n`
+  );
+  process.exit(1);
+}
+
+// Binaries live next to this shim's package root: <pkg>/binaries/<name>
+// __dirname is <pkg>/bin/, so go up one level.
+const pkgRoot    = path.resolve(__dirname, "..");
+const binaryDir  = path.join(pkgRoot, "binaries");
+const binaryPath = path.join(binaryDir, binName);
+
+if (!existsSync(binaryPath)) {
+  process.stderr.write(
+    `[ckforensics] Binary not found: ${binaryPath}\n` +
+    `This usually means the postinstall script did not run.\n` +
+    `Try: npm install  (or re-run: node ${path.join(pkgRoot, "scripts", "postinstall.js")})\n`
+  );
+  process.exit(1);
+}
+
+// ── Execute binary ────────────────────────────────────────────────────────────
+
+const result = spawnSync(binaryPath, process.argv.slice(2), {
+  stdio: "inherit",
+  // Pass through the full environment so the binary inherits PATH, HOME, etc.
+  env: process.env,
+});
+
+if (result.error) {
+  process.stderr.write(
+    `[ckforensics] Failed to launch binary: ${result.error.message}\n`
+  );
+  process.exit(1);
+}
+
+process.exit(result.status ?? 0);

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "ckforensics",
+  "version": "0.1.0",
+  "module": "index.ts",
+  "type": "module",
+  "bin": {
+    "ckforensics": "./bin/ckforensics.js"
+  },
+  "scripts": {
+    "cli": "bun run src/cli/index.ts",
+    "build:all": "./scripts/build-all.sh",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "postinstall": "node ./scripts/postinstall.js || true"
+  },
+  "files": [
+    "bin/",
+    "scripts/postinstall.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "dependencies": {
+    "commander": "^14.0.3"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "description": "Forensic CLI for Claude Code sessions — audit, redact, export your transcripts.",
+  "homepage": "https://github.com/phong28zk/ckforensics#readme",
+  "bugs": {
+    "url": "https://github.com/phong28zk/ckforensics/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/phong28zk/ckforensics.git"
+  },
+  "author": "phong28zk",
+  "license": "MIT",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "anthropic",
+    "cli",
+    "audit",
+    "forensics",
+    "sqlite",
+    "bun"
+  ]
+}

package/scripts/postinstall.js

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+/**
+ * scripts/postinstall.js — npm postinstall binary downloader.
+ *
+ * Runs automatically on `npm install` (triggered via package.json postinstall).
+ * Downloads the correct platform binary from the GitHub Release matching the
+ * package version, verifies SHA256 checksum, makes it executable, and saves
+ * it to <pkg>/binaries/ where bin/ckforensics.js will find it.
+ *
+ * Written as ESM because package.json sets "type": "module".
+ *
+ * Design constraints:
+ *   - Node 18+ only (uses built-in https, fs, crypto, path, url — NO npm deps)
+ *   - Skip silently when running inside the source repo (detected via .git)
+ *   - Skip when CKFORENSICS_SKIP_DOWNLOAD=1 env var is set (CI compile step)
+ *   - Fail loudly with actionable message if download or checksum fails
+ *
+ * GitHub Release asset naming (must match scripts/build-all.sh):
+ *   ckforensics-linux-x64
+ *   ckforensics-linux-arm64
+ *   ckforensics-darwin-x64
+ *   ckforensics-darwin-arm64
+ *   ckforensics-win-x64.exe
+ *   checksums.txt
+ */
+
+import https   from "https";
+import fs      from "fs";
+import path    from "path";
+import crypto  from "crypto";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname  = path.dirname(__filename);
+
+// ── Configuration ─────────────────────────────────────────────────────────────
+
+const GITHUB_REPO  = "phong28zk/ckforensics";
+const PKG_ROOT     = path.resolve(__dirname, "..");
+const PKG_JSON     = path.join(PKG_ROOT, "package.json");
+const BINARIES_DIR = path.join(PKG_ROOT, "binaries");
+
+// ── Early exit conditions ─────────────────────────────────────────────────────
+
+// 1. Respect explicit opt-out (useful in CI compile jobs).
+if (process.env.CKFORENSICS_SKIP_DOWNLOAD === "1") {
+  console.log("[ckforensics] CKFORENSICS_SKIP_DOWNLOAD=1 — skipping binary download.");
+  process.exit(0);
+}
+
+// 2. Skip when running in the source repo (developer workflow).
+//    Presence of a .git directory at pkg root means we are in a git checkout.
+if (fs.existsSync(path.join(PKG_ROOT, ".git"))) {
+  console.log("[ckforensics] Source repo detected (.git present) — skipping binary download.");
+  process.exit(0);
+}
+
+// ── Platform → binary name mapping ───────────────────────────────────────────
+
+// darwin-x64 (Intel Mac) intentionally omitted from prebuilt releases.
+// Intel Mac users: build from source — see README "Build from source".
+const PLATFORM_MAP = {
+  "linux-x64":    "ckforensics-linux-x64",
+  "linux-arm64":  "ckforensics-linux-arm64",
+  "darwin-arm64": "ckforensics-darwin-arm64",
+  "win32-x64":    "ckforensics-win-x64.exe",
+};
+
+const platform = process.platform; // "linux" | "darwin" | "win32"
+const arch     = process.arch;     // "x64" | "arm64"
+const key      = `${platform}-${arch}`;
+const binName  = PLATFORM_MAP[key];
+
+if (!binName) {
+  console.warn(
+    `[ckforensics] Unsupported platform ${platform}-${arch} — no binary available.\n` +
+    `Supported: ${Object.keys(PLATFORM_MAP).join(", ")}\n` +
+    `You can build from source: bun build --compile src/cli/index.ts`
+  );
+  // Non-fatal: user can still build from source.
+  process.exit(0);
+}
+
+// ── Resolve package version ───────────────────────────────────────────────────
+
+let version;
+try {
+  const pkg = JSON.parse(fs.readFileSync(PKG_JSON, "utf8"));
+  version = pkg.version;
+  if (!version) throw new Error("version field missing");
+} catch (e) {
+  fatal(`Cannot read package version from ${PKG_JSON}: ${e.message}`);
+}
+
+const tagName        = `v${version}`;
+const releaseBaseUrl = `https://github.com/${GITHUB_REPO}/releases/download/${tagName}`;
+const binaryUrl      = `${releaseBaseUrl}/${binName}`;
+const checksumUrl    = `${releaseBaseUrl}/checksums.txt`;
+
+// ── Utilities ─────────────────────────────────────────────────────────────────
+
+/** Exit with a human-readable error. */
+function fatal(msg) {
+  process.stderr.write(`[ckforensics] ERROR: ${msg}\n`);
+  process.exit(1);
+}
+
+/**
+ * Follow HTTP redirects and return the final response.
+ * Supports up to 10 hops (GitHub Releases redirects to S3).
+ *
+ * @param {string} url
+ * @param {number} hops
+ * @returns {Promise<import("http").IncomingMessage>}
+ */
+function httpsGet(url, hops = 0) {
+  return new Promise((resolve, reject) => {
+    if (hops > 10) return reject(new Error(`Too many redirects for ${url}`));
+
+    https
+      .get(url, { headers: { "User-Agent": "ckforensics-postinstall/1.0" } }, (res) => {
+        if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+          res.resume(); // discard body
+          return resolve(httpsGet(res.headers.location, hops + 1));
+        }
+        resolve(res);
+      })
+      .on("error", reject);
+  });
+}
+
+/**
+ * Download a URL and buffer the full body.
+ *
+ * @param {string} url
+ * @returns {Promise<{ status: number, buffer: Buffer }>}
+ */
+async function download(url) {
+  const res = await httpsGet(url);
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    res.on("data", (c) => chunks.push(c));
+    res.on("end",  () => resolve({ status: res.statusCode, buffer: Buffer.concat(chunks) }));
+    res.on("error", reject);
+  });
+}
+
+/** Compute SHA256 hex of a Buffer. */
+function sha256hex(buf) {
+  return crypto.createHash("sha256").update(buf).digest("hex");
+}
+
+/**
+ * Parse checksums.txt (sha256sum format: "<hash>  <filename>\n").
+ *
+ * @param {string} text
+ * @returns {Map<string, string>}  filename → lowercase hex hash
+ */
+function parseChecksums(text) {
+  const map = new Map();
+  for (const line of text.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    // Two-space separator (sha256sum convention) or single space (shasum)
+    const match = trimmed.match(/^([0-9a-f]{64})\s{1,2}(.+)$/i);
+    if (match) map.set(match[2].trim(), match[1].toLowerCase());
+  }
+  return map;
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+
+async function main() {
+  console.log(`[ckforensics] Downloading binary for ${platform}-${arch} (${tagName})...`);
+
+  // 1. Fetch checksums first (fail fast if release doesn't exist).
+  console.log(`[ckforensics] Fetching checksums from: ${checksumUrl}`);
+  const cksumResult = await download(checksumUrl).catch((e) =>
+    fatal(`Failed to fetch checksums: ${e.message}`)
+  );
+
+  if (cksumResult.status !== 200) {
+    fatal(
+      `Checksums not found (HTTP ${cksumResult.status}). ` +
+      `Release ${tagName} may not exist yet at https://github.com/${GITHUB_REPO}/releases`
+    );
+  }
+
+  const checksums    = parseChecksums(cksumResult.buffer.toString("utf8"));
+  const expectedHash = checksums.get(binName);
+
+  if (!expectedHash) {
+    fatal(
+      `No checksum entry for "${binName}" in checksums.txt. ` +
+      `Available entries: ${[...checksums.keys()].join(", ")}`
+    );
+  }
+
+  // 2. Download binary.
+  console.log(`[ckforensics] Downloading binary from: ${binaryUrl}`);
+  const binResult = await download(binaryUrl).catch((e) =>
+    fatal(`Failed to download binary: ${e.message}`)
+  );
+
+  if (binResult.status !== 200) {
+    fatal(`Binary download failed (HTTP ${binResult.status}). URL: ${binaryUrl}`);
+  }
+
+  // 3. Verify checksum.
+  const actualHash = sha256hex(binResult.buffer);
+  if (actualHash !== expectedHash) {
+    fatal(
+      `SHA256 mismatch for ${binName}!\n` +
+      `  Expected: ${expectedHash}\n` +
+      `  Got:      ${actualHash}\n` +
+      `The download may be corrupt or tampered — aborting for safety.`
+    );
+  }
+  console.log(`[ckforensics] Checksum verified OK (${actualHash.slice(0, 16)}...)`);
+
+  // 4. Write binary to disk.
+  fs.mkdirSync(BINARIES_DIR, { recursive: true });
+  const destPath = path.join(BINARIES_DIR, binName);
+  fs.writeFileSync(destPath, binResult.buffer);
+
+  // 5. chmod +x on Unix.
+  if (platform !== "win32") {
+    fs.chmodSync(destPath, 0o755);
+    console.log(`[ckforensics] Set executable bit on ${destPath}`);
+  }
+
+  const sizeMB = (binResult.buffer.length / 1024 / 1024).toFixed(1);
+  console.log(`[ckforensics] Installed ${binName} (${sizeMB} MB) → ${destPath}`);
+  console.log(`[ckforensics] Run: ckforensics --help`);
+}
+
+main().catch((e) => fatal(String(e)));