@i4ctime/q-ring 0.16.0 → 0.16.2

package/README.md

@@ -518,6 +518,8 @@ qring audit --action canary
 
 Values are CSPRNG noise in the provider's real token shape (an `aws` canary matches `AKIA[A-Z0-9]{16}`) — plausible enough to be taken, never valid. Alerts are throttled to one per key per 30 seconds; the audit trail records every read.
 
+Canaries are built to stay covert: they carry no identifying description (add an innocuous cover story with `--description` if you like), their flag never appears in MCP tool responses, and trip records are visible only from the operator's terminal — never to agents via MCP audit tools. Bulk `export` and `delete` trip them just like reads, so sweeping the ring or removing the tripwire both ring the bell. Done with one? `qring canary disarm <key>` turns it back into an ordinary secret (`qring set` over a canary warns you first — the flag deliberately survives overwrites so an agent can't launder it away).
+
 ### MCP Airlock
 
 Run a third-party MCP server behind q-ring. The airlock sits between your agent host and the wrapped server, spawns it with a **stripped environment** (no inherited API keys — opt back in with `--inherit-env`), and records every tool call that crosses it as a `wrap` event in the audit chain, grouped per session and labeled with the calling client's identity. Tool arguments are never logged — they may contain secrets.
@@ -533,7 +535,9 @@ Run a third-party MCP server behind q-ring. The airlock sits between your agent
 }
 ```
 
-Tools-only proxy today: `tools/list` and `tools/call` pass through verbatim, so the wrapped server behaves identically — it just can't read your environment, and everything it's asked to do is on the record.
+Tools-only proxy today: `tools/list` and `tools/call` pass through verbatim (pagination, progress notifications, cancellation, and `tools/list_changed` included; long-running tools are governed by the host's own timeout, with a generous airlock ceiling configurable via `QRING_WRAP_TIMEOUT_MS`). A wrapped server's *resources and prompts* are not proxied yet — a resources-heavy server will look tools-only behind the airlock.
+
+Be clear about what the airlock is: env stripping plus a tamper-evident record of every tool call. It is **not a sandbox** — the wrapped process still runs as your user with normal filesystem, network, and OS-keychain access, and tool descriptions/results pass through uninspected. See `docs/threat-model.md` for the honest boundary picture.
 
 ### Just-In-Time (JIT) Provisioning
 
@@ -683,7 +687,7 @@ qring exec -- echo "hello"
 
 ### Tamper-Evident Audit
 
-Every audit event includes a SHA-256 hash of the previous event, creating a tamper-evident chain. Since v0.14 the chain is also anchored with a keyed HMAC stored in the OS keyring, so `qring audit:verify` detects truncation and whole-file rewrites — not just in-place edits. Verify integrity and export logs in multiple formats. Events from MCP sessions are additionally stamped with the connecting client's self-reported identity (`clientInfo` name@version) — an audit label for "which agent did this", never an authorization boundary, since clients choose what to report.
+Every audit event includes a SHA-256 hash of the previous event, creating a tamper-evident chain. Since v0.14 the chain is also anchored with a keyed HMAC stored in the OS keyring, so `qring audit:verify` detects truncation and whole-file rewrites — not just in-place edits. Verify integrity and export logs in multiple formats. Events from MCP sessions are additionally stamped with the connecting client's self-reported identity (`clientInfo` name@version) — shown in `qring audit` output and filterable with `qring audit --agent <label>`. It's an audit label for "which agent did this", never an authorization boundary, since clients choose what to report.
 
 ```bash
 # Verify the entire audit chain
@@ -951,6 +955,22 @@ Add to `~/.claude/claude_desktop_config.json`:
 }
 ```
 
+### VS Code Configuration
+
+VS Code speaks MCP natively — add to `.vscode/mcp.json` (note the `servers` key, not `mcpServers`):
+
+```json
+{
+  "servers": {
+    "q-ring": {
+      "command": "qring-mcp"
+    }
+  }
+}
+```
+
+`qring setup` does not write this file yet — VS Code is config-only (no first-party plugin bundle).
+
 ## Editor Plugins
 
 The q-ring repo ships three first-party editor packs — each one adds rules/steering, agents, commands, skills, hooks, and the MCP connector to its host editor.

package/dist/{chunk-NCM5GHNW.js → chunk-KFILBHOY.js}

@@ -335,7 +335,8 @@ function isProcessAlive(pid) {
   }
 }
 function withFileLock(name, fn, opts = {}) {
-  const lockDir = join3(homedir(), ".config", "q-ring", opts.dir ?? "locks");
+  const baseDir = process.env.QRING_LOCK_DIR ?? (process.env.QRING_AUDIT_DIR ? join3(process.env.QRING_AUDIT_DIR, ".locks") : join3(homedir(), ".config", "q-ring"));
+  const lockDir = join3(baseDir, opts.dir ?? "locks");
   mkdirSync(lockDir, { recursive: true, mode: 448 });
   const safe = Buffer.from(name, "utf8").toString("base64url");
   const lockPath = join3(lockDir, `${safe}.lock`);
@@ -577,6 +578,13 @@ function setAuditAgentLabel(label) {
 function getAuditAgentLabel() {
   return auditAgentLabel;
 }
+function sanitizeAuditText(value, max) {
+  const cleaned = Array.from(value).filter((ch) => {
+    const cp = ch.codePointAt(0) ?? 0;
+    return cp >= 32 && cp !== 127;
+  }).join("");
+  return cleaned.length > max ? `${cleaned.slice(0, max)}\u2026` : cleaned;
+}
 function getAuditDir() {
   if (process.env.QRING_AUDIT_DIR) {
     if (!existsSync2(process.env.QRING_AUDIT_DIR)) {
@@ -631,6 +639,10 @@ function logAudit(event) {
         if (full.agent === void 0 && auditAgentLabel) {
           full.agent = auditAgentLabel;
         }
+        if (full.key !== void 0) full.key = sanitizeAuditText(full.key, 256);
+        if (full.detail !== void 0) full.detail = sanitizeAuditText(full.detail, 600);
+        if (full.scope !== void 0) full.scope = sanitizeAuditText(full.scope, 128);
+        if (full.env !== void 0) full.env = sanitizeAuditText(full.env, 128);
         const line = JSON.stringify(full);
         const path = getAuditPath();
         appendFileSync(path, line + "\n", { mode: 384 });
@@ -643,7 +655,12 @@ function logAudit(event) {
       },
       { timeoutMs: 5e3 }
     );
-  } catch {
+  } catch (err) {
+    if (process.env.QRING_DEBUG) {
+      console.error(
+        `q-ring: audit event dropped (${event.action}${event.key ? ` ${event.key}` : ""}): ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
   }
 }
 var MAX_AUDIT_BYTES = 12 * 1024 * 1024;
@@ -762,13 +779,33 @@ function exportAudit(opts = {}) {
     const until = new Date(opts.until).getTime();
     events = events.filter((e) => new Date(e.timestamp).getTime() <= until);
   }
+  if (opts.excludeActions?.length) {
+    const excluded = new Set(opts.excludeActions);
+    events = events.filter((e) => !excluded.has(e.action));
+  }
   if (opts.format === "json") {
     return JSON.stringify(events, null, 2);
   }
   if (opts.format === "csv") {
+    const csvField = (v) => {
+      let s = v === void 0 ? "" : String(v);
+      if (/^[=+\-@\t\r]/.test(s)) s = `'${s}`;
+      return `"${s.replace(/"/g, '""')}"`;
+    };
     const header = "timestamp,action,key,scope,env,source,agent,pid,correlationId,detail";
     const rows = events.map(
-      (e) => `${e.timestamp},${e.action},${e.key ?? ""},${e.scope ?? ""},${e.env ?? ""},${e.source},${(e.agent ?? "").replace(/,/g, ";")},${e.pid},${e.correlationId ?? ""},${(e.detail ?? "").replace(/,/g, ";")}`
+      (e) => [
+        csvField(e.timestamp),
+        csvField(e.action),
+        csvField(e.key),
+        csvField(e.scope),
+        csvField(e.env),
+        csvField(e.source),
+        csvField(e.agent),
+        csvField(e.pid),
+        csvField(e.correlationId),
+        csvField(e.detail)
+      ].join(",")
     );
     return [header, ...rows].join("\n");
   }
@@ -1718,7 +1755,8 @@ function notifyUser(title, body) {
     let args;
     if (process.platform === "linux") {
       command = "notify-send";
-      args = ["--app-name=q-ring", "--urgency=critical", title, body];
+      const pango = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+      args = ["--app-name=q-ring", "--urgency=critical", pango(title), pango(body)];
     } else if (process.platform === "darwin") {
       command = "osascript";
       const clean = (s) => s.replace(/["\\]/g, "");
@@ -1758,7 +1796,7 @@ function recordCanaryTrip(trip) {
     scope: trip.scope,
     env: trip.env,
     source: trip.source,
-    detail: `CANARY TRIPPED: honeytoken read via ${trip.source}`
+    detail: `CANARY TRIPPED: ${trip.detail ?? `honeytoken read via ${trip.source}`}`
   });
   if (!notificationsEnabled()) return;
   const now = Date.now();
@@ -2201,8 +2239,12 @@ function deleteSecret(key, opts = {}) {
   for (const { service, scope } of scopes) {
     const entry = new Entry(service, key);
     try {
+      const existing = readEnvelope(service, key);
       if (entry.deleteCredential()) {
         deleted = true;
+        if (existing?.meta.canary) {
+          recordCanaryTrip({ key, scope, source, detail: "canary deleted" });
+        }
         logAudit({ action: "delete", key, scope, source });
         fireHooks({
           action: "delete",
@@ -2321,6 +2363,9 @@ function exportSecrets(opts = {}) {
       const value = collapseValue(entry.envelope, env);
       if (value !== null) {
         rawValues.set(entry.key, value);
+        if (entry.envelope.meta.canary) {
+          recordCanaryTrip({ key: entry.key, scope: entry.scope, env, source });
+        }
       }
     }
   }
@@ -2333,7 +2378,13 @@ function exportSecrets(opts = {}) {
       console.warn(`Warning: skipped exporting ${key} due to template error: ${err instanceof Error ? err.message : String(err)}`);
     }
   }
-  logAudit({ action: "export", source, detail: `format=${format}` });
+  const exportedKeys = [...merged.keys()];
+  const keyList = exportedKeys.length > 20 ? `${exportedKeys.slice(0, 20).join(",")} +${exportedKeys.length - 20} more` : exportedKeys.join(",");
+  logAudit({
+    action: "export",
+    source,
+    detail: `format=${format} keys=${keyList}`
+  });
   if (format === "json") {
     const obj = {};
     for (const [key, value] of merged) {
@@ -2665,4 +2716,4 @@ export {
   listMemory,
   forget
 };
-//# sourceMappingURL=chunk-NCM5GHNW.js.map
+//# sourceMappingURL=chunk-KFILBHOY.js.map