@i4ctime/q-ring 0.11.7 → 0.13.0

package/README.md

@@ -44,6 +44,19 @@ yarn global add @i4ctime/q-ring
 brew install i4ctime/tap/qring
 ```
 
+### Docker (MCP server)
+
+The repo ships a `Dockerfile` that builds the MCP server and exposes it through [`mcp-proxy`](https://github.com/punkpeye/mcp-proxy) — useful for hosted MCP deployments (e.g. Glama) or keeping the server off the host entirely:
+
+```bash
+git clone https://github.com/I4cTime/quantum_ring.git
+cd quantum_ring
+docker build -t qring-mcp .
+docker run --rm -p 8080:8080 qring-mcp
+```
+
+> Note: inside a container there is no OS keychain (GNOME Keyring / macOS Keychain), so this path is for the MCP protocol surface, ephemeral use, and CI experiments — not for durable local secret storage. For day-to-day use install the CLI natively via one of the package managers above.
+
 ## ⚡ Quick Start
 
 ```bash
@@ -61,6 +74,12 @@ qring generate --format api-key --prefix "sk-" --save MY_KEY
 
 # 5️⃣ Run a full health scan
 qring health
+
+# Something not working? Diagnose the install (keyring, audit, MCP wiring)
+qring doctor
+
+# Tab completion for your shell
+qring completion zsh > ~/.zsh/completions/_qring   # also: bash, fish
 ```
 
 ## Quantum Features
@@ -182,7 +201,7 @@ qring tunnel list
 
 ### Teleportation — Encrypted Sharing
 
-Pack secrets into AES-256-GCM encrypted bundles for secure transfer between machines.
+Pack secrets into AES-256-GCM encrypted bundles for secure transfer between machines. Keys are derived with PBKDF2-HMAC-SHA512 (210 000 iterations) from your passphrase; each bundle records its iteration count, so bundles produced by older versions still unpack.
 
 ```bash
 # Pack secrets (prompts for passphrase)
@@ -197,7 +216,7 @@ qring teleport unpack <bundle> --dry-run
 
 ### Import — Bulk Secret Ingestion
 
-Import secrets from `.env` files directly into q-ring. Supports standard dotenv syntax including comments, quoted values, and escape sequences.
+Import secrets from `.env` files directly into q-ring. Supports standard dotenv syntax including comments, quoted values, and escape sequences. The CLI accepts either a file path or raw content; the `import_dotenv` MCP tool only accepts raw content (it never reads files from disk) so an agent can't coerce it into reading arbitrary local files.
 
 ```bash
 # Import all secrets from a .env file
@@ -241,6 +260,9 @@ qring list --stale
 
 # Glob pattern on key name
 qring list --filter "API_*"
+
+# Script-friendly existence check (exit 0 if present, 1 if not; decay-aware)
+qring has OPENAI_API_KEY --quiet && echo "configured"
 ```
 
 ### Project Secret Manifest
@@ -335,7 +357,7 @@ qring hook test <id>
 
 Hooks are fire-and-forget: a failing hook never blocks secret operations. The hook registry is stored at `~/.config/q-ring/hooks.json`.
 
-**SSRF protection:** HTTP hook URLs targeting private/loopback IP ranges (`127.0.0.0/8`, `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `169.254.0.0/16`, `::1`, `fc00::/7`) are blocked by default. DNS resolution is checked before the request is sent. To allow hooks targeting local services (e.g. during development), set the environment variable `Q_RING_ALLOW_PRIVATE_HOOKS=1`.
+**SSRF protection:** HTTP hook URLs targeting private/loopback IP ranges (`127.0.0.0/8`, `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `169.254.0.0/16`, `::1`, `fc00::/7`) are blocked by default. DNS is checked up front *and* re-validated at connect time, so a hostname can't pass the check then rebind to a private address before the socket opens. To allow hooks targeting local services (e.g. during development), set the environment variable `Q_RING_ALLOW_PRIVATE_HOOKS=1`.
 
 ### Configurable Rotation
 
@@ -397,7 +419,7 @@ qring get DB_URL
 
 ### User Approvals (Zero-Trust Agent)
 
-Protect sensitive production secrets from being read autonomously by the MCP server without explicit user approval. Each approval token is HMAC-verified, scoped, reasoned, and time-limited.
+Protect sensitive production secrets from being read autonomously by the MCP server without explicit user approval. Each approval token is HMAC-verified, scoped, reasoned, and time-limited. The gate applies to bulk reads too — `export_secrets` and `teleport_pack` over MCP skip approval-protected keys that lack a valid grant.
 
 ```bash
 # Mark a secret as requiring approval
@@ -508,6 +530,8 @@ qring wizard myservice --hook-exec "pm2 restart app"
 
 Define project-level governance rules in `.q-ring.json` to control which MCP tools can be used, which keys are accessible, and which commands can be executed. Policy is enforced at both the MCP server and keyring level.
 
+Over MCP, policy is resolved from the directory the server was **launched** in — not from the `projectPath` a caller passes — so an agent can't sidestep restrictions by pointing at a directory with no policy. Launch the MCP server from your project root (where `.q-ring.json` lives). Edits to `.q-ring.json` are picked up automatically (the policy cache invalidates on file change), so you don't need to restart the server.
+
 ```bash
 # View the active policy
 qring policy
@@ -626,7 +650,7 @@ qring agent --once
 
 ### Quantum Status Dashboard — Live Monitoring
 
-Launch a real-time dashboard in your browser that turns the entire quantum subsystem into one glanceable page. The dashboard is a single self-contained HTML page served locally — no dependencies, no cloud, no config — and streams updates every 5 seconds via Server-Sent Events while preserving search input and scroll position across ticks.
+Launch a real-time dashboard in your browser that turns the entire quantum subsystem into one glanceable page. It's a single self-contained HTML page served locally — no cloud, no config, fully offline — built as a Preact + htm app (runtime bundled and inlined). It streams updates every 5 seconds via Server-Sent Events and diffs the DOM in place, so data refreshes without re-running entrance animations and your search input, caret, and scroll position are preserved across ticks.
 
 What you get:
 
@@ -644,14 +668,16 @@ What you get:
 
 Top-bar controls let you **pause** SSE updates (handy while reading the audit feed), **refresh** on demand, or jump to the raw JSON snapshot at `/api/status`. Keyboard shortcuts: `/` focus secrets search · `P` pause · `R` refresh.
 
+The dashboard binds to `127.0.0.1` only and **never** exposes secret values, but it does surface key names, the audit log, and approval grants — so every route is gated by a random, per-launch token. `qring status` prints (and opens) the full URL including `?token=…`; requests without the token get a `403`. Stop the server to invalidate the token.
+
 ```bash
-# Open the dashboard (auto-launches your browser)
+# Open the dashboard (auto-launches your browser at http://127.0.0.1:9876/?token=…)
 qring status
 
 # Specify a custom port
 qring status --port 4200
 
-# Don't auto-open the browser
+# Don't auto-open the browser (copy the printed tokenized URL yourself)
 qring status --no-open
 ```
 
@@ -668,8 +694,8 @@ q-ring includes a full MCP server with 44 tools for AI agent integration.
 | `set_secret` | Create or overwrite a single secret with optional TTL, per-env state, tags, rotation format |
 | `delete_secret` | Permanently remove a secret value (not undoable from q-ring) |
 | `has_secret` | Boolean existence check that respects decay (no audit read) |
-| `export_secrets` | Render multiple secrets as `.env` or JSON for one-off export |
-| `import_dotenv` | Parse `.env` text and bulk-store every key/value pair |
+| `export_secrets` | Render multiple secrets as `.env` or JSON for one-off export (skips approval-protected keys without a grant) |
+| `import_dotenv` | Parse `.env` text and bulk-store every key/value pair (accepts raw content only — never reads files) |
 | `check_project` | Compare `.q-ring.json` manifest against the keyring for missing/expired/stale keys |
 | `env_generate` | Render a complete `.env` body from the project manifest, with warnings for gaps |
 
@@ -741,7 +767,7 @@ q-ring includes a full MCP server with 44 tools for AI agent integration.
 | `verify_audit_chain` | Recompute the audit hash chain and report the first break point if tampered |
 | `export_audit` | Export audit events as jsonl, json, or csv for archival/SIEM |
 | `health_check` | Read-only scope sweep: decay/stale/expired counts plus current anomalies |
-| `status_dashboard` | Start a local SSE dashboard with live KPIs, secrets, hooks, and audit feed |
+| `status_dashboard` | Start a local SSE dashboard with live KPIs, secrets, hooks, and audit feed (returns a token-gated `127.0.0.1` URL) |
 | `agent_scan` | Multi-project health pass with optional `autoRotate` for expired secrets |
 
 ### Governance & Policy Tools
@@ -940,8 +966,17 @@ Optional per-project configuration:
 - **`validationUrl`** configures the generic HTTP provider's endpoint for custom validation
 - **`policy`** defines governance rules for MCP tool gating, key access restrictions, exec allowlists, and secret lifecycle requirements
 
+## 📚 Docs
+
+- [Quickstart: Claude Code](docs/quickstart-claude-code.md) · [Cursor](docs/quickstart-cursor.md) · [Kiro](docs/quickstart-kiro.md)
+- [Troubleshooting](docs/troubleshooting.md) — keyring backends, MCP connection, approval gate, policy pinning
+- [CLI ↔ MCP parity](docs/cli-mcp-parity.md) — every command mapped to its MCP tool
+- [Releasing](docs/releasing.md) — tag-driven release flow
+
 ## Contributing
 
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide (dev environment, conventions, files to keep in sync). The short version:
+
 - Run **`pnpm run lint`**, **`pnpm run typecheck`**, and **`pnpm run test:ci`** before opening a PR.
 - Tests or sandboxes can point the audit log elsewhere with **`QRING_AUDIT_DIR`** (directory is created if missing); default is `~/.config/q-ring/audit.jsonl`.
 - Optional local pre-commit: **`qring hook:install`** (uses this package’s `precommit` hook when `qring` is on your `PATH`).

package/dist/{chunk-MQM4DLPI.js → chunk-CWV3WTPF.js}

@@ -147,7 +147,7 @@ function checkDecay(envelope) {
   const remaining = expires - now;
   const lifetimePercent = totalLifetime > 0 ? Math.round(elapsed / totalLifetime * 100) : 100;
   const secondsRemaining = Math.floor(remaining / 1e3);
-  let timeRemaining = null;
+  let timeRemaining = "expired";
   if (remaining > 0) {
     const days = Math.floor(remaining / 864e5);
     const hours = Math.floor(remaining % 864e5 / 36e5);
@@ -155,8 +155,6 @@ function checkDecay(envelope) {
     if (days > 0) timeRemaining = `${days}d ${hours}h`;
     else if (hours > 0) timeRemaining = `${hours}h ${minutes}m`;
     else timeRemaining = `${minutes}m`;
-  } else {
-    timeRemaining = "expired";
   }
   return {
     isExpired: remaining <= 0,
@@ -555,87 +553,11 @@ import { randomUUID } from "crypto";
 // src/utils/http-request.ts
 import { request as httpsRequest } from "https";
 import { request as httpRequestPlain } from "http";
-var DEFAULT_TIMEOUT_MS = 1e4;
-var DEFAULT_MAX_RESPONSE_BYTES = 65536;
-function httpRequest(opts) {
-  const {
-    url,
-    method = "GET",
-    headers = {},
-    body,
-    timeoutMs = DEFAULT_TIMEOUT_MS,
-    maxResponseBytes = DEFAULT_MAX_RESPONSE_BYTES
-  } = opts;
-  return new Promise((resolve, reject) => {
-    const parsed = new URL(url);
-    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-      reject(new Error(`Unsupported URL protocol: ${parsed.protocol}`));
-      return;
-    }
-    const reqFn = parsed.protocol === "https:" ? httpsRequest : httpRequestPlain;
-    const reqHeaders = { ...headers };
-    if (body && !reqHeaders["Content-Length"]) {
-      reqHeaders["Content-Length"] = Buffer.byteLength(body);
-    }
-    const req = reqFn(
-      url,
-      { method, headers: reqHeaders, timeout: timeoutMs },
-      (res) => {
-        const chunks = [];
-        let totalBytes = 0;
-        let truncated = false;
-        res.on("data", (chunk) => {
-          totalBytes += chunk.length;
-          if (totalBytes > maxResponseBytes) {
-            truncated = true;
-            res.destroy();
-            return;
-          }
-          chunks.push(chunk);
-        });
-        let settled = false;
-        const settle = (result) => {
-          if (!settled) {
-            settled = true;
-            resolve(result);
-          }
-        };
-        const fail = (err) => {
-          if (!settled) {
-            settled = true;
-            reject(err);
-          }
-        };
-        res.on("error", (err) => fail(new Error(`Response error: ${err.message}`)));
-        res.on("end", () => {
-          settle({
-            statusCode: res.statusCode ?? 0,
-            body: Buffer.concat(chunks).toString("utf8"),
-            truncated
-          });
-        });
-        res.on("close", () => {
-          settle({
-            statusCode: res.statusCode ?? 0,
-            body: Buffer.concat(chunks).toString("utf8"),
-            truncated
-          });
-        });
-      }
-    );
-    req.on("error", (err) => reject(new Error(`Network error: ${err.message}`)));
-    req.on("timeout", () => {
-      req.destroy();
-      reject(new Error("Request timed out"));
-    });
-    if (body) req.write(body);
-    req.end();
-  });
-}
 
 // src/core/ssrf.ts
 import { lookup } from "dns/promises";
 import * as dns from "dns";
+import { lookup as dnsLookup } from "dns";
 import { isIPv4, isIPv6 } from "net";
 function lookupAddressesSync(hostname2) {
   const lookupSync2 = dns.lookupSync;
@@ -682,6 +604,36 @@ async function checkSSRF(url) {
   }
   return null;
 }
+function guardedLookup(hostname2, options, callback) {
+  if (process.env.Q_RING_ALLOW_PRIVATE_HOOKS === "1") {
+    dnsLookup(
+      hostname2,
+      options,
+      callback
+    );
+    return;
+  }
+  dnsLookup(
+    hostname2,
+    options,
+    (err, address, family) => {
+      if (err) return callback(err, address, family);
+      const list = Array.isArray(address) ? address : [{ address, family: family ?? 0 }];
+      for (const a of list) {
+        if (isPrivateIP(a.address)) {
+          const blocked = Object.assign(
+            new Error(
+              `Blocked: "${hostname2}" resolved to private address ${a.address} at connect time.`
+            ),
+            { code: "EQRINGSSRF" }
+          );
+          return callback(blocked, address, family);
+        }
+      }
+      callback(null, address, family);
+    }
+  );
+}
 function checkJitHttpProvisionUrl(url) {
   if (process.env.Q_RING_ALLOW_PRIVATE_HOOKS === "1") return null;
   try {
@@ -719,6 +671,91 @@ function checkJitHttpProvisionUrl(url) {
   return null;
 }
 
+// src/utils/http-request.ts
+var DEFAULT_TIMEOUT_MS = 1e4;
+var DEFAULT_MAX_RESPONSE_BYTES = 65536;
+function httpRequest(opts) {
+  const {
+    url,
+    method = "GET",
+    headers = {},
+    body,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    maxResponseBytes = DEFAULT_MAX_RESPONSE_BYTES
+  } = opts;
+  return new Promise((resolve, reject) => {
+    const parsed = new URL(url);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+      reject(new Error(`Unsupported URL protocol: ${parsed.protocol}`));
+      return;
+    }
+    const reqFn = parsed.protocol === "https:" ? httpsRequest : httpRequestPlain;
+    const reqHeaders = { ...headers };
+    if (body && !reqHeaders["Content-Length"]) {
+      reqHeaders["Content-Length"] = Buffer.byteLength(body);
+    }
+    const req = reqFn(
+      url,
+      {
+        method,
+        headers: reqHeaders,
+        timeout: timeoutMs,
+        // Re-validate the resolved IP at connect time (DNS-rebinding guard).
+        lookup: guardedLookup
+      },
+      (res) => {
+        const chunks = [];
+        let totalBytes = 0;
+        let truncated = false;
+        res.on("data", (chunk) => {
+          totalBytes += chunk.length;
+          if (totalBytes > maxResponseBytes) {
+            truncated = true;
+            res.destroy();
+            return;
+          }
+          chunks.push(chunk);
+        });
+        let settled = false;
+        const settle = (result) => {
+          if (!settled) {
+            settled = true;
+            resolve(result);
+          }
+        };
+        const fail = (err) => {
+          if (!settled) {
+            settled = true;
+            reject(err);
+          }
+        };
+        res.on("error", (err) => fail(new Error(`Response error: ${err.message}`)));
+        res.on("end", () => {
+          settle({
+            statusCode: res.statusCode ?? 0,
+            body: Buffer.concat(chunks).toString("utf8"),
+            truncated
+          });
+        });
+        res.on("close", () => {
+          settle({
+            statusCode: res.statusCode ?? 0,
+            body: Buffer.concat(chunks).toString("utf8"),
+            truncated
+          });
+        });
+      }
+    );
+    req.on("error", (err) => reject(new Error(`Network error: ${err.message}`)));
+    req.on("timeout", () => {
+      req.destroy();
+      reject(new Error("Request timed out"));
+    });
+    if (body) req.write(body);
+    req.end();
+  });
+}
+
 // src/core/hooks.ts
 function getRegistryPath2() {
   const dir = join5(homedir3(), ".config", "q-ring");
@@ -1065,15 +1102,33 @@ function listApprovals() {
 }
 
 // src/core/policy.ts
+import { statSync as statSync2 } from "fs";
+import { join as join7 } from "path";
 var cachedPolicy = null;
+var policyRoot = null;
+function setPolicyRoot(root) {
+  policyRoot = root;
+  cachedPolicy = null;
+}
+function resolvePolicyPath(projectPath) {
+  return policyRoot ?? projectPath ?? process.cwd();
+}
+function configMtime(pp) {
+  try {
+    return statSync2(join7(pp, ".q-ring.json")).mtimeMs;
+  } catch {
+    return 0;
+  }
+}
 function loadPolicy(projectPath) {
-  const pp = projectPath ?? process.cwd();
-  if (cachedPolicy && cachedPolicy.path === pp) {
+  const pp = resolvePolicyPath(projectPath);
+  const mtimeMs = configMtime(pp);
+  if (cachedPolicy && cachedPolicy.path === pp && cachedPolicy.mtimeMs === mtimeMs) {
     return cachedPolicy.policy;
   }
   const config = readProjectConfig(pp);
   const policy = config?.policy ?? {};
-  cachedPolicy = { path: pp, policy };
+  cachedPolicy = { path: pp, mtimeMs, policy };
   return policy;
 }
 function checkToolPolicy(toolName, projectPath) {
@@ -1161,7 +1216,13 @@ function checkExecPolicy(command, projectPath) {
   const policy = loadPolicy(projectPath);
   if (!policy.exec) return { allowed: true, policySource: "no-policy" };
   if (policy.exec.denyCommands) {
-    const denied = policy.exec.denyCommands.find((d) => command.includes(d));
+    const denied = policy.exec.denyCommands.find((d) => {
+      const pattern = new RegExp(
+        `(^|[\\s/])${d.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(\\s|$)`,
+        "i"
+      );
+      return pattern.test(command);
+    });
     if (denied) {
       return {
         allowed: false,
@@ -1171,7 +1232,8 @@ function checkExecPolicy(command, projectPath) {
     }
   }
   if (policy.exec.allowCommands) {
-    const allowed = policy.exec.allowCommands.some((a) => command.startsWith(a));
+    const normalized = command.trimStart();
+    const allowed = policy.exec.allowCommands.some((a) => normalized.startsWith(a));
     if (!allowed) {
       return {
         allowed: false,
@@ -1198,7 +1260,7 @@ function getPolicySummary(projectPath) {
 // src/core/keyring.ts
 import { mkdirSync as mkdirSync5, writeFileSync as writeFileSync4, unlinkSync } from "fs";
 import { homedir as homedir5 } from "os";
-import { join as join7 } from "path";
+import { join as join8 } from "path";
 import { Entry, findCredentials } from "@napi-rs/keyring";
 
 // src/utils/hash.ts
@@ -1324,7 +1386,7 @@ var awsStsProvider = {
         expiresAt: creds.Expiration
       };
     } catch (err) {
-      throw new Error(`AWS STS provision failed: ${err instanceof Error ? err.message : String(err)}`);
+      throw new Error(`AWS STS provision failed: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
     }
   }
 };
@@ -1392,7 +1454,7 @@ req.end();
         expiresAt: new Date(Date.now() + expiresInSeconds * 1e3).toISOString()
       };
     } catch (err) {
-      throw new Error(`HTTP provision failed: ${err instanceof Error ? err.message : String(err)}`);
+      throw new Error(`HTTP provision failed: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
     }
   }
 };
@@ -1402,10 +1464,10 @@ registry.register(httpProvider);
 
 // src/core/keyring.ts
 function withJitEnvelopeLock(service, key, fn) {
-  const dir = join7(homedir5(), ".config", "q-ring", "jit-locks");
+  const dir = join8(homedir5(), ".config", "q-ring", "jit-locks");
   mkdirSync5(dir, { recursive: true });
   const safe = Buffer.from(`${service}\0${key}`, "utf8").toString("base64url");
-  const lockPath = join7(dir, `${safe}.lock`);
+  const lockPath = join8(dir, `${safe}.lock`);
   const deadline = Date.now() + 8e3;
   while (Date.now() < deadline) {
     try {
@@ -1789,6 +1851,16 @@ function exportSecrets(opts = {}) {
     if (entry.envelope) {
       const decay = checkDecay(entry.envelope);
       if (decay.isExpired) continue;
+      if (source === "mcp" && entry.envelope.meta.requiresApproval && !hasApproval(entry.key, entry.scope)) {
+        logAudit({
+          action: "read",
+          key: entry.key,
+          scope: entry.scope,
+          source,
+          detail: "blocked: requires user approval (export)"
+        });
+        continue;
+      }
       const value = collapseValue(entry.envelope, env);
       if (value !== null) {
         rawValues.set(entry.key, value);
@@ -1920,7 +1992,7 @@ function tunnelList() {
 
 // src/core/memory.ts
 import { existsSync as existsSync6, readFileSync as readFileSync7, writeFileSync as writeFileSync5, mkdirSync as mkdirSync6 } from "fs";
-import { join as join8 } from "path";
+import { join as join9 } from "path";
 import { homedir as homedir6, hostname, userInfo } from "os";
 import { createCipheriv, createDecipheriv, createHash as createHash3, randomBytes as randomBytes3 } from "crypto";
 import { Entry as Entry2 } from "@napi-rs/keyring";
@@ -1928,14 +2000,14 @@ var MEMORY_FILE = "agent-memory.enc";
 var KEYRING_SERVICE = "qring-memory-key";
 var KEYRING_ACCOUNT = "encryption-key";
 function getMemoryDir() {
-  const dir = join8(homedir6(), ".config", "q-ring");
+  const dir = join9(homedir6(), ".config", "q-ring");
   if (!existsSync6(dir)) {
     mkdirSync6(dir, { recursive: true });
   }
   return dir;
 }
 function getMemoryPath() {
-  return join8(getMemoryDir(), MEMORY_FILE);
+  return join9(getMemoryDir(), MEMORY_FILE);
 }
 function deriveLegacyKey() {
   const fingerprint = `qring-memory:${hostname()}:${userInfo().username}`;
@@ -2043,14 +2115,15 @@ export {
   exportAudit,
   detectAnomalies,
   listEntanglements,
-  httpRequest,
   checkSSRF,
+  httpRequest,
   registerHook,
   removeHook,
   listHooks,
   fireHooks,
   listApprovals,
   registry,
+  setPolicyRoot,
   checkToolPolicy,
   checkKeyReadPolicy,
   checkExecPolicy,
@@ -2074,4 +2147,4 @@ export {
   listMemory,
   forget
 };
-//# sourceMappingURL=chunk-MQM4DLPI.js.map
+//# sourceMappingURL=chunk-CWV3WTPF.js.map