@i4ctime/q-ring 0.15.0 → 0.16.0

package/README.md

@@ -500,6 +500,41 @@ qring approve PROD_DB_URL --revoke
 
 When an agent is blocked on an approval-protected key, q-ring raises a desktop notification (Linux `notify-send`, macOS `osascript`) naming the key and the exact `qring approve` command — throttled per key, disabled with `QRING_NOTIFY=off`.
 
+### Canary Honeytokens
+
+Plant fake credentials that look and read exactly like real ones. Anything that touches one — a compromised MCP server, an over-curious agent, exfiltrated tooling sweeping the ring — gets the fake value back with no tell, while q-ring fires a desktop alert and writes a `canary` event into the tamper-evident audit chain.
+
+```bash
+# Plant a canary shaped like a real AWS access key
+qring canary plant AWS_SECRET_ACCESS_KEY --format aws
+
+# Other shapes: github, openai, anthropic, stripe, generic
+qring canary plant GHP_BACKUP_TOKEN --format github
+
+# See what's been tripped
+qring canary list
+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.
+
+### 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.
+
+```json
+{
+  "mcpServers": {
+    "some-server": {
+      "command": "qring",
+      "args": ["mcp", "wrap", "--", "npx", "-y", "some-mcp-server"]
+    }
+  }
+}
+```
+
+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.
+
 ### Just-In-Time (JIT) Provisioning
 
 Instead of storing static credentials, configure `q-ring` to dynamically generate short-lived tokens on the fly when requested (e.g. AWS STS, generic HTTP endpoints).
@@ -648,7 +683,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.
+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.
 
 ```bash
 # Verify the entire audit chain

package/dist/{chunk-MLBJCPX2.js → chunk-5LFKBZ3Q.js}

@@ -40,7 +40,9 @@ var SecretMetadataSchema = z.object({
   validationUrl: z.string().optional(),
   requiresApproval: z.boolean().optional(),
   jitProvider: z.string().optional(),
-  jitExpiresAt: z.string().optional()
+  jitExpiresAt: z.string().optional(),
+  canary: z.boolean().optional(),
+  canaryFormat: z.string().optional()
 });
 var QuantumEnvelopeSchema = z.object({
   v: z.literal(1),
@@ -73,7 +75,9 @@ function createEnvelope(value, opts) {
       rotationPrefix: opts?.rotationPrefix,
       provider: opts?.provider,
       requiresApproval: opts?.requiresApproval,
-      jitProvider: opts?.jitProvider
+      jitProvider: opts?.jitProvider,
+      canary: opts?.canary,
+      canaryFormat: opts?.canaryFormat
     }
   };
 }
@@ -561,6 +565,18 @@ function writeStoredAnchor(hash) {
   } catch {
   }
 }
+var auditAgentLabel = null;
+function setAuditAgentLabel(label) {
+  if (label === null) {
+    auditAgentLabel = null;
+    return;
+  }
+  const cleaned = label.replace(/[^\x20-\x7e]/g, "").trim().slice(0, 128);
+  auditAgentLabel = cleaned.length > 0 ? cleaned : null;
+}
+function getAuditAgentLabel() {
+  return auditAgentLabel;
+}
 function getAuditDir() {
   if (process.env.QRING_AUDIT_DIR) {
     if (!existsSync2(process.env.QRING_AUDIT_DIR)) {
@@ -612,6 +628,9 @@ function logAudit(event) {
           pid: process.pid,
           prevHash
         };
+        if (full.agent === void 0 && auditAgentLabel) {
+          full.agent = auditAgentLabel;
+        }
         const line = JSON.stringify(full);
         const path = getAuditPath();
         appendFileSync(path, line + "\n", { mode: 384 });
@@ -656,6 +675,7 @@ function queryAudit(query = {}) {
     if (query.action) events = events.filter((e) => e.action === query.action);
     if (query.source) events = events.filter((e) => e.source === query.source);
     if (query.correlationId) events = events.filter((e) => e.correlationId === query.correlationId);
+    if (query.agent) events = events.filter((e) => e.agent === query.agent);
     if (query.since) {
       const since = new Date(query.since).getTime();
       events = events.filter((e) => new Date(e.timestamp).getTime() >= since);
@@ -746,9 +766,9 @@ function exportAudit(opts = {}) {
     return JSON.stringify(events, null, 2);
   }
   if (opts.format === "csv") {
-    const header = "timestamp,action,key,scope,env,source,pid,correlationId,detail";
+    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.pid},${e.correlationId ?? ""},${(e.detail ?? "").replace(/,/g, ";")}`
+      (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, ";")}`
     );
     return [header, ...rows].join("\n");
   }
@@ -1771,6 +1791,31 @@ function notifyApprovalRequested(key, source) {
   );
 }
 
+// src/core/canary-alert.ts
+var TRIP_THROTTLE_MS = 30 * 1e3;
+var lastAlerted = /* @__PURE__ */ new Map();
+function recordCanaryTrip(trip) {
+  const agent = getAuditAgentLabel();
+  logAudit({
+    action: "canary",
+    key: trip.key,
+    scope: trip.scope,
+    env: trip.env,
+    source: trip.source,
+    detail: `CANARY TRIPPED: honeytoken read via ${trip.source}`
+  });
+  if (!notificationsEnabled()) return;
+  const now = Date.now();
+  const last = lastAlerted.get(trip.key);
+  if (last !== void 0 && now - last < TRIP_THROTTLE_MS) return;
+  lastAlerted.set(trip.key, now);
+  const who = agent ? `${trip.source} (${agent})` : trip.source;
+  notifyUser(
+    "q-ring: CANARY TRIPPED",
+    `Honeytoken "${trip.key}" was read by ${who}. This credential is fake \u2014 but something reached for it. Investigate: qring audit --action canary`
+  );
+}
+
 // src/core/provision.ts
 import { execFileSync, spawnSync } from "child_process";
 import { z as z3 } from "zod";
@@ -2052,6 +2097,9 @@ function getSecret(key, opts = {}) {
       const latest = readEnvelope(service, key) ?? envelope;
       writeEnvelope(service, key, recordAccess(latest));
       logAudit({ action: "read", key, scope, env, source });
+      if (envelope.meta.canary) {
+        recordCanaryTrip({ key, scope, env, source });
+      }
     }
     return value;
   }
@@ -2084,6 +2132,8 @@ function setSecret(key, value, opts = {}) {
   const prov = opts.provider ?? existing?.meta.provider;
   const reqApp = opts.requiresApproval ?? existing?.meta.requiresApproval;
   const jitProv = opts.jitProvider ?? existing?.meta.jitProvider;
+  const canaryFlag = opts.canary ?? existing?.meta.canary;
+  const canaryFmt = opts.canaryFormat ?? existing?.meta.canaryFormat;
   const mergedTags = opts.tags ?? existing?.meta.tags;
   const ttlForPolicy = opts.ttlSeconds ?? existing?.meta.ttlSeconds;
   const life = checkSecretLifecyclePolicy(
@@ -2111,7 +2161,9 @@ function setSecret(key, value, opts = {}) {
       rotationPrefix: rotPfx,
       provider: prov,
       requiresApproval: reqApp,
-      jitProvider: jitProv
+      jitProvider: jitProv,
+      canary: canaryFlag,
+      canaryFormat: canaryFmt
     });
   } else {
     envelope = createEnvelope(value, {
@@ -2124,7 +2176,9 @@ function setSecret(key, value, opts = {}) {
       rotationPrefix: rotPfx,
       provider: prov,
       requiresApproval: reqApp,
-      jitProvider: jitProv
+      jitProvider: jitProv,
+      canary: canaryFlag,
+      canaryFormat: canaryFmt
     });
   }
   if (existing) {
@@ -2620,6 +2674,7 @@ export {
   checkDecay,
   readProjectConfig,
   collapseEnvironment,
+  setAuditAgentLabel,
   logAudit,
   queryAudit,
   verifyAuditChain,
@@ -2661,4 +2716,4 @@ export {
   forget,
   clearMemory
 };
-//# sourceMappingURL=chunk-MLBJCPX2.js.map
+//# sourceMappingURL=chunk-5LFKBZ3Q.js.map