openclaw-credential-vault 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenClaw Contributors
+
+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,95 @@
+# OpenClaw Credential Vault
+
+Encrypted credential management for [OpenClaw](https://openclaw.ai). Keeps API keys, tokens, and passwords out of the AI agent's context window — where they could be exfiltrated, leaked into transcripts, or exposed through tool output.
+
+## Install
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/karanuppal/openclaw-credential-vault/main/install.sh | bash
+```
+
+This installs the plugin, creates a dedicated system user for credential isolation, and configures everything. You'll be prompted for sudo.
+
+**Can't use sudo?** Run `openclaw vault init` for inline-only mode — credentials are still encrypted at rest, just without OS-level user separation.
+
+## Quick Start
+
+```bash
+# Add a credential (auto-detects format)
+openclaw vault add github --key "ghp_your_token_here"
+
+# Verify it works
+openclaw vault test github
+
+# Add more
+openclaw vault add stripe --key "sk_live_..."
+openclaw vault add amazon --type browser-password --domain .amazon.com --key "p@ssw0rd"
+```
+
+That's it. The agent can now use `gh`, call Stripe APIs, and log into Amazon — without ever seeing the credentials.
+
+## How It Works
+
+```
+Agent runs "gh pr list"
+    ↓
+before_tool_call hook matches "gh" → decrypts credential → injects GH_TOKEN into subprocess
+    ↓
+gh runs with the token, returns PR listings
+    ↓
+Subprocess exits — credential dies with it
+    ↓
+Output scrubbed for credential patterns (3 layers: regex + literal + env-var)
+    ↓
+Agent sees clean PR listings — no credential anywhere in context
+```
+
+**Encryption:** AES-256-GCM with Argon2id key derivation (64 MiB memory, 3 iterations). Each credential is a separate `.enc` file.
+
+**Isolation:** The Rust resolver binary runs as a dedicated `openclaw-vault` system user via setuid. The agent process can't read the credential files — it gets "Permission denied." The plugin and resolver use protocol versioning to detect mismatches after updates — if `npm update` delivers a new version, the plugin surfaces actionable fix instructions (`sudo bash vault-setup.sh`) until the installed binary is updated.
+
+**Scrubbing:** Three redundant layers catch credentials in tool output, file writes, outbound messages, and session transcripts. Patterns for GitHub, Stripe, Gumroad, OpenAI, and Anthropic tokens ship built-in.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `vault init` | Initialize vault (creates directory, shows setup instructions) |
+| `vault add <tool> --key <cred>` | Add a credential (auto-detects format) |
+| `vault add <tool> --type browser-password --domain <d> --key <p>` | Add a domain-pinned browser password |
+| `vault add <tool> --type browser-cookie --domain <d>` | Add browser cookies (paste JSON or Netscape format) |
+| `vault list` | Show all stored credentials and status |
+| `vault show <tool>` | Show credential details and config |
+| `vault test <tool>` | Verify injection and scrubbing work |
+| `vault rotate <tool> --key <new>` | Rotate a credential |
+| `vault rotate --check` | Show overdue rotations |
+| `vault rotate --all` | Emergency mass rotation walkthrough |
+| `vault remove <tool>` | Remove credential (keeps scrub patterns) |
+| `vault remove <tool> --purge` | Fully remove credential + config |
+| `vault audit` | Security audit (permissions, rotation, config) |
+| `vault logs` | View audit log (credential access + scrubbing) |
+| `vault logs --stats` | Aggregate access/scrub statistics |
+| `vault logs --tool <name> --last <duration>` | Filter by tool and time |
+| `vault logs --json` | Raw JSONL output |
+
+## Platform Support
+
+| Platform | Status |
+|----------|--------|
+| Linux x64 | Full support (inline + resolver) |
+| Linux arm64 | Inline mode only (resolver binary coming soon) |
+| macOS | Inline mode only |
+
+**Sandbox mode:** Not yet tested with OpenClaw's Docker sandbox. The vault hooks run in the gateway process (not inside the sandbox container), so they should work in theory, but no end-to-end verification has been done. See [Specification](docs/SPEC.md#sandbox-compatibility) for details.
+
+## Learn More
+
+- **[Architecture](docs/ARCHITECTURE.md)** — Component map, Mermaid diagrams, hook pipeline, Rust resolver deep dive
+- **[Threat Model](docs/THREAT-MODEL.md)** — What we defend against, what we don't, and design trade-offs
+- **[Specification](docs/SPEC.md)** — Encryption scheme, hook behavior, CLI reference, config schemas
+- **[Testing](docs/TESTING.md)** — 576 tests across 29 files: unit, integration, adversarial, performance, resolver versioning
+- **[Security Audit](docs/SECURITY-AUDIT.md)** — Validation methodology, results, bugs found and fixed
+
+## License
+
+MIT

package/bin/vault-setup.sh

@@ -0,0 +1,163 @@
+#!/usr/bin/env bash
+#
+# OpenClaw Credential Vault — OS-Level Isolation Setup
+#
+# This script sets up the Rust resolver binary with setuid permissions
+# for OS-level credential isolation. Must be run as root.
+#
+# Usage:
+#   sudo bash /path/to/vault-setup.sh
+#
+# What it does:
+#   1. Creates 'openclaw-vault' system user (no login, no home directory)
+#   2. Installs the resolver binary to /usr/local/bin/ with setuid
+#   3. Creates /var/lib/openclaw-vault/ with restricted permissions
+#   4. Migrates credential files from user vault to system vault
+#   5. Updates vault config to use binary resolver mode
+#
+set -euo pipefail
+
+# ── Require root ──
+if [ "$(id -u)" -ne 0 ]; then
+  echo "Error: This script must be run as root."
+  echo "Usage: sudo bash $0"
+  exit 1
+fi
+
+# ── Resolve paths ──
+# OPENCLAW_VAULT_DIR can be overridden; defaults to ~user/.openclaw/vault
+# OPENCLAW_USER is the non-root user who owns the vault
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# Auto-detect the calling user (the one who ran sudo)
+if [ -n "${SUDO_USER:-}" ]; then
+  OPENCLAW_USER="$SUDO_USER"
+elif [ -n "${OPENCLAW_USER:-}" ]; then
+  OPENCLAW_USER="$OPENCLAW_USER"
+else
+  echo "Error: Cannot determine the OpenClaw user."
+  echo "Run with sudo (which sets SUDO_USER) or set OPENCLAW_USER."
+  exit 1
+fi
+
+USER_HOME=$(eval echo "~${OPENCLAW_USER}")
+VAULT_DIR="${OPENCLAW_VAULT_DIR:-${USER_HOME}/.openclaw/vault}"
+SYSTEM_VAULT_DIR="/var/lib/openclaw-vault"
+DEST_BINARY="/usr/local/bin/openclaw-vault-resolver"
+
+# ── Find the resolver binary ──
+# Search order: bin/<platform>-<arch>/ in package, then dev build paths
+ARCH="$(uname -m)"
+case "$ARCH" in
+  x86_64)  ARCH_DIR="linux-x64" ;;
+  aarch64) ARCH_DIR="linux-arm64" ;;
+  *)       ARCH_DIR="linux-${ARCH}" ;;
+esac
+
+SOURCE_BINARY=""
+SEARCH_PATHS=(
+  "${SCRIPT_DIR}/${ARCH_DIR}/openclaw-vault-resolver"
+  "${SCRIPT_DIR}/../resolver/target/release/openclaw-vault-resolver"
+  "${SCRIPT_DIR}/../resolver/target/x86_64-unknown-linux-musl/release/openclaw-vault-resolver"
+)
+
+for p in "${SEARCH_PATHS[@]}"; do
+  if [ -f "$p" ]; then
+    SOURCE_BINARY="$p"
+    break
+  fi
+done
+
+if [ -z "$SOURCE_BINARY" ]; then
+  echo "Error: Resolver binary not found for ${ARCH_DIR}."
+  echo "Searched:"
+  for p in "${SEARCH_PATHS[@]}"; do
+    echo "  $p"
+  done
+  exit 1
+fi
+
+echo "OpenClaw Credential Vault — OS-Level Isolation Setup"
+echo "===================================================="
+echo ""
+echo "  User:          ${OPENCLAW_USER}"
+echo "  Vault dir:     ${VAULT_DIR}"
+echo "  System dir:    ${SYSTEM_VAULT_DIR}"
+echo "  Binary:        ${SOURCE_BINARY}"
+echo ""
+
+# ── Step 1: Create system user ──
+if id openclaw-vault &>/dev/null; then
+  echo "✓ System user 'openclaw-vault' already exists"
+else
+  useradd --system --no-create-home --shell /usr/sbin/nologin openclaw-vault
+  echo "✓ Created system user 'openclaw-vault'"
+fi
+
+# ── Step 2: Install resolver binary ──
+cp "$SOURCE_BINARY" "$DEST_BINARY"
+chown openclaw-vault:openclaw-vault "$DEST_BINARY"
+chmod u+s,a+rx "$DEST_BINARY"
+echo "✓ Resolver binary installed: ${DEST_BINARY} (setuid openclaw-vault)"
+
+# ── Step 3: Create system vault directory ──
+mkdir -p "$SYSTEM_VAULT_DIR"
+chown openclaw-vault:openclaw-vault "$SYSTEM_VAULT_DIR"
+chmod 700 "$SYSTEM_VAULT_DIR"
+echo "✓ System vault directory: ${SYSTEM_VAULT_DIR}"
+
+# ── Step 4: Migrate credential files ──
+MIGRATED=0
+if [ -d "$VAULT_DIR" ]; then
+  for f in "$VAULT_DIR"/*.enc "$VAULT_DIR"/.vault-meta.json; do
+    [ -f "$f" ] || continue
+    BASENAME="$(basename "$f")"
+    cp "$f" "${SYSTEM_VAULT_DIR}/${BASENAME}"
+    chown openclaw-vault:openclaw-vault "${SYSTEM_VAULT_DIR}/${BASENAME}"
+    chmod 600 "${SYSTEM_VAULT_DIR}/${BASENAME}"
+    MIGRATED=$((MIGRATED + 1))
+  done
+fi
+
+if [ "$MIGRATED" -gt 0 ]; then
+  echo "✓ Migrated ${MIGRATED} file(s) to ${SYSTEM_VAULT_DIR}"
+else
+  echo "ℹ No credential files to migrate"
+fi
+
+# ── Step 5: Initialize vault if not already done ──
+TOOLS_YAML="${VAULT_DIR}/tools.yaml"
+if [ ! -f "$TOOLS_YAML" ]; then
+  echo "Initializing vault..."
+  mkdir -p "$VAULT_DIR"
+  cat > "$TOOLS_YAML" <<EOF
+version: 1
+masterKeyMode: machine
+resolverMode: binary
+tools: {}
+EOF
+  # Create .vault-meta.json
+  cat > "${VAULT_DIR}/.vault-meta.json" <<EOF
+{
+  "createdAt": "$(date -u +%Y-%m-%dT%H:%M:%S.000Z)",
+  "installTimestamp": "$(date -u +%Y-%m-%dT%H:%M:%S.000Z)",
+  "masterKeyMode": "machine"
+}
+EOF
+  chmod 600 "$TOOLS_YAML" "${VAULT_DIR}/.vault-meta.json"
+  chown "${OPENCLAW_USER}:${OPENCLAW_USER}" "$VAULT_DIR" "$TOOLS_YAML" "${VAULT_DIR}/.vault-meta.json"
+  echo "✓ Vault initialized at ${VAULT_DIR}"
+else
+  # Update resolverMode to binary
+  if grep -q "resolverMode:" "$TOOLS_YAML"; then
+    sed -i 's/resolverMode:.*/resolverMode: binary/' "$TOOLS_YAML"
+  else
+    echo "resolverMode: binary" >> "$TOOLS_YAML"
+  fi
+  chown "${OPENCLAW_USER}:${OPENCLAW_USER}" "$TOOLS_YAML"
+  echo '✓ Config updated: resolverMode = "binary"'
+fi
+
+echo ""
+echo "✓ Setup complete — credentials are now isolated behind OS-user separation."
+echo "  Run 'openclaw doctor fix' to restart the gateway with the new configuration."

package/dist/audit.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Audit logging: append-only JSONL audit log for credential access and scrubbing events.
+ *
+ * Storage: ~/.openclaw/vault/audit.log (JSONL, one event per line)
+ * Permissions: 0600 (Phase 1), owned by openclaw-vault (Phase 2)
+ */
+import { AuditEvent } from "./types.js";
+/**
+ * Get the audit log file path.
+ */
+export declare function getAuditLogPath(vaultDir?: string): string;
+export declare function writeAuditEvent(event: AuditEvent, vaultDir?: string): void;
+/**
+ * Log a credential access event.
+ */
+export declare function logCredentialAccess(params: {
+    tool: string;
+    credential: string;
+    injectionType: string;
+    command: string;
+    sessionKey?: string;
+    durationMs: number;
+    success: boolean;
+}, vaultDir?: string): void;
+/**
+ * Log a scrubbing event.
+ */
+export declare function logScrubEvent(params: {
+    hook: string;
+    credential: string;
+    pattern: string;
+    replacements: number;
+    sessionKey?: string;
+}, vaultDir?: string): void;
+/**
+ * Log a compaction event.
+ */
+export declare function logCompactionEvent(params: {
+    sessionKey?: string;
+    scrubbingActive: boolean;
+}, vaultDir?: string): void;
+/** Filter options for reading audit log */
+export interface AuditLogFilter {
+    tool?: string;
+    type?: string;
+    last?: string;
+    limit?: number;
+}
+/**
+ * Parse a duration string like "24h", "7d", "30m" into milliseconds.
+ */
+export declare function parseDuration(duration: string): number;
+/**
+ * Read audit log events with optional filters.
+ */
+export declare function readAuditLog(filter?: AuditLogFilter, vaultDir?: string): AuditEvent[];
+/** Aggregate stats from the audit log */
+export interface AuditStats {
+    totalEvents: number;
+    credentialAccesses: number;
+    scrubEvents: number;
+    compactionEvents: number;
+    byTool: Record<string, {
+        accesses: number;
+        scrubs: number;
+        lastAccess?: string;
+    }>;
+    byHook: Record<string, number>;
+}
+/**
+ * Compute aggregate stats from the audit log.
+ */
+export declare function computeAuditStats(vaultDir?: string): AuditStats;
+//# sourceMappingURL=audit.d.ts.map

package/dist/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAGxC;;GAEG;AACH,wBAAgB,eAAe,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAGzD;AAQD,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAuB1E;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;CAClB,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAY1B;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAU1B;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,OAAO,CAAC;CAC1B,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAO1B;AAED,2CAA2C;AAC3C,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAatD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,GAAE,cAAmB,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,UAAU,EAAE,CA+CzF;AAED,yCAAyC;AACzC,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClF,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,UAAU,CA4C/D"}

package/dist/audit.js

@@ -0,0 +1,238 @@
+"use strict";
+/**
+ * Audit logging: append-only JSONL audit log for credential access and scrubbing events.
+ *
+ * Storage: ~/.openclaw/vault/audit.log (JSONL, one event per line)
+ * Permissions: 0600 (Phase 1), owned by openclaw-vault (Phase 2)
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAuditLogPath = getAuditLogPath;
+exports.writeAuditEvent = writeAuditEvent;
+exports.logCredentialAccess = logCredentialAccess;
+exports.logScrubEvent = logScrubEvent;
+exports.logCompactionEvent = logCompactionEvent;
+exports.parseDuration = parseDuration;
+exports.readAuditLog = readAuditLog;
+exports.computeAuditStats = computeAuditStats;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const config_js_1 = require("./config.js");
+/**
+ * Get the audit log file path.
+ */
+function getAuditLogPath(vaultDir) {
+    const dir = vaultDir ?? (0, config_js_1.getVaultDir)();
+    return path.join(dir, "audit.log");
+}
+/**
+ * Append an audit event to the log file (JSONL, append-only).
+ */
+/** Max audit log size before rotation: 5 MB */
+const MAX_AUDIT_LOG_BYTES = 5 * 1024 * 1024;
+function writeAuditEvent(event, vaultDir) {
+    const logPath = getAuditLogPath(vaultDir);
+    const dir = path.dirname(logPath);
+    // Ensure directory exists
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    // Rotate if log exceeds max size (keep one backup)
+    try {
+        if (fs.existsSync(logPath)) {
+            const stat = fs.statSync(logPath);
+            if (stat.size > MAX_AUDIT_LOG_BYTES) {
+                const backupPath = logPath + ".1";
+                try {
+                    fs.unlinkSync(backupPath);
+                }
+                catch { /* no old backup */ }
+                fs.renameSync(logPath, backupPath);
+            }
+        }
+    }
+    catch { /* non-fatal: continue writing to current log */ }
+    const line = JSON.stringify(event) + "\n";
+    fs.appendFileSync(logPath, line, { mode: 0o600 });
+}
+/**
+ * Log a credential access event.
+ */
+function logCredentialAccess(params, vaultDir) {
+    writeAuditEvent({
+        type: "credential_access",
+        timestamp: new Date().toISOString(),
+        tool: params.tool,
+        credential: params.credential,
+        injectionType: params.injectionType,
+        command: params.command,
+        sessionKey: params.sessionKey ?? "unknown",
+        durationMs: params.durationMs,
+        success: params.success,
+    }, vaultDir);
+}
+/**
+ * Log a scrubbing event.
+ */
+function logScrubEvent(params, vaultDir) {
+    writeAuditEvent({
+        type: "scrub",
+        timestamp: new Date().toISOString(),
+        hook: params.hook,
+        credential: params.credential,
+        pattern: params.pattern,
+        replacements: params.replacements,
+        sessionKey: params.sessionKey ?? "unknown",
+    }, vaultDir);
+}
+/**
+ * Log a compaction event.
+ */
+function logCompactionEvent(params, vaultDir) {
+    writeAuditEvent({
+        type: "compaction",
+        timestamp: new Date().toISOString(),
+        sessionKey: params.sessionKey ?? "unknown",
+        scrubbingActive: params.scrubbingActive,
+    }, vaultDir);
+}
+/**
+ * Parse a duration string like "24h", "7d", "30m" into milliseconds.
+ */
+function parseDuration(duration) {
+    const match = duration.match(/^(\d+)(m|h|d)$/);
+    if (!match)
+        throw new Error(`Invalid duration format: ${duration} (use e.g., 24h, 7d, 30m)`);
+    const value = parseInt(match[1], 10);
+    const unit = match[2];
+    switch (unit) {
+        case "m": return value * 60 * 1000;
+        case "h": return value * 60 * 60 * 1000;
+        case "d": return value * 24 * 60 * 60 * 1000;
+        default: throw new Error(`Unknown duration unit: ${unit}`);
+    }
+}
+/**
+ * Read audit log events with optional filters.
+ */
+function readAuditLog(filter = {}, vaultDir) {
+    const logPath = getAuditLogPath(vaultDir);
+    if (!fs.existsSync(logPath)) {
+        return [];
+    }
+    const content = fs.readFileSync(logPath, "utf8");
+    const lines = content.trim().split("\n").filter(Boolean);
+    let events = [];
+    for (const line of lines) {
+        try {
+            events.push(JSON.parse(line));
+        }
+        catch {
+            // Skip malformed lines
+        }
+    }
+    // Apply type filter
+    if (filter.type) {
+        events = events.filter((e) => e.type === filter.type);
+    }
+    // Apply tool filter
+    if (filter.tool) {
+        events = events.filter((e) => {
+            if (e.type === "credential_access")
+                return e.tool === filter.tool || e.credential === filter.tool;
+            if (e.type === "scrub")
+                return e.credential === filter.tool;
+            return false;
+        });
+    }
+    // Apply time filter
+    if (filter.last) {
+        const ms = parseDuration(filter.last);
+        const cutoff = Date.now() - ms;
+        events = events.filter((e) => new Date(e.timestamp).getTime() >= cutoff);
+    }
+    // Apply limit (take last N)
+    const limit = filter.limit ?? 50;
+    if (events.length > limit) {
+        events = events.slice(-limit);
+    }
+    return events;
+}
+/**
+ * Compute aggregate stats from the audit log.
+ */
+function computeAuditStats(vaultDir) {
+    const events = readAuditLog({ limit: Infinity }, vaultDir);
+    const stats = {
+        totalEvents: events.length,
+        credentialAccesses: 0,
+        scrubEvents: 0,
+        compactionEvents: 0,
+        byTool: {},
+        byHook: {},
+    };
+    for (const event of events) {
+        switch (event.type) {
+            case "credential_access": {
+                stats.credentialAccesses++;
+                const tool = event.credential;
+                if (!stats.byTool[tool]) {
+                    stats.byTool[tool] = { accesses: 0, scrubs: 0 };
+                }
+                stats.byTool[tool].accesses++;
+                stats.byTool[tool].lastAccess = event.timestamp;
+                break;
+            }
+            case "scrub": {
+                stats.scrubEvents++;
+                const tool = event.credential;
+                if (!stats.byTool[tool]) {
+                    stats.byTool[tool] = { accesses: 0, scrubs: 0 };
+                }
+                stats.byTool[tool].scrubs++;
+                if (!stats.byHook[event.hook]) {
+                    stats.byHook[event.hook] = 0;
+                }
+                stats.byHook[event.hook]++;
+                break;
+            }
+            case "compaction":
+                stats.compactionEvents++;
+                break;
+        }
+    }
+    return stats;
+}
+//# sourceMappingURL=audit.js.map

package/dist/audit.js.map

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