@i4ctime/q-ring 0.14.1 → 0.16.0

package/README.md

@@ -6,11 +6,19 @@
 
 **OS keychain secrets for AI coding agents, over MCP.**
 
+[![CI](https://img.shields.io/github/actions/workflow/status/I4cTime/q-ring/ci.yml?style=flat-square&label=CI)](https://github.com/I4cTime/q-ring/actions/workflows/ci.yml)
 [![NPM Version](https://img.shields.io/npm/v/@i4ctime/q-ring?style=flat-square&color=0ea5e9)](https://www.npmjs.com/package/@i4ctime/q-ring)
+[![NPM Downloads](https://img.shields.io/npm/dm/@i4ctime/q-ring?style=flat-square&color=0ea5e9&label=downloads)](https://www.npmjs.com/package/@i4ctime/q-ring)
 [![Docs](https://img.shields.io/badge/docs-website-0ea5e9?style=flat-square)](https://qring.i4c.studio/docs)
 [![MCP Tools](https://img.shields.io/badge/MCP_tools-44-0ea5e9?style=flat-square)](https://glama.ai/mcp/servers/I4cTime/q-ring)
+[![Smithery](https://img.shields.io/badge/smithery-i4ctime%2Fq--ring-0ea5e9?style=flat-square)](https://smithery.ai/servers/i4ctime/q-ring)
+[![Cursor Directory](https://img.shields.io/badge/cursor_directory-q--ring-0ea5e9?style=flat-square)](https://cursor.directory/plugins/q-ring)
+[![PulseMCP](https://img.shields.io/badge/pulsemcp-q--ring-0ea5e9?style=flat-square)](https://www.pulsemcp.com/servers/i4ctime-q-ring)
+[![mcpservers.org](https://img.shields.io/badge/mcpservers.org-q--ring-0ea5e9?style=flat-square)](https://mcpservers.org/servers/i4ctime/q-ring)
 [![License](https://img.shields.io/npm/l/@i4ctime/q-ring?style=flat-square&color=0ea5e9)](https://github.com/I4cTime/q-ring/blob/main/LICENSE)
 [![Discord](https://img.shields.io/badge/discord-join%20the%20studio-5865F2?style=flat-square&logo=discord&logoColor=white)](https://discord.gg/5uEApw5uEz)
+[![YouTube](https://img.shields.io/badge/youtube-%40qring__dev-FF0000?style=flat-square&logo=youtube&logoColor=white)](https://www.youtube.com/@qring_dev)
+[![X](https://img.shields.io/badge/follow-%40i4c__studio-000000?style=flat-square&logo=x&logoColor=white)](https://x.com/i4c_studio)
 
 <a href="https://glama.ai/mcp/servers/I4cTime/q-ring">
   <img src="https://glama.ai/mcp/servers/I4cTime/q-ring/badges/card.svg" alt="q-ring MCP server" width="400" />
@@ -293,6 +301,60 @@ qring env:generate --output .env
 qring env:generate --env staging --output .env.staging
 ```
 
+### Secret References & Least-Privilege Run
+
+A `qring://` reference is a committable pointer to a secret — it goes in your `.env` file instead of the value. `qring run` resolves references and manifest keys at spawn time, injecting **only what the project declares** (unlike `exec`, which injects the whole scope). Output is auto-redacted.
+
+```bash
+# .env — safe to commit: these are references, not values
+DATABASE_URL=qring://project/DATABASE_URL
+OPENAI_API_KEY=qring://global/OPENAI_API_KEY
+STRIPE_KEY=qring:///STRIPE_KEY            # auto scope: project, then global
+SESSION_TTL=3600                          # plain values pass through
+
+# Run with declared secrets injected (manifest + .env refs)
+qring run -- pnpm dev
+
+# Preview what would be injected, without running
+qring run --dry-run -- pnpm dev
+
+# Pin an environment, use a specific env file, or skip the manifest
+qring run --env prod --env-file .env.prod --no-manifest -- ./deploy.sh
+```
+
+The key lives in the **path**, never the host (`qring://project/KEY`, not `qring://KEY`) — URL hosts are case-insensitive, and env-var keys are not. Malformed references fail loudly instead of leaking a literal `qring://…` string into the child. A reference pinned to an environment: `qring://project/DATABASE_URL?env=prod`.
+
+### Editor Setup
+
+Wire the q-ring MCP server into an editor's MCP config with one command. Merges non-destructively — other servers are preserved, and an existing q-ring entry is only replaced with `--force`.
+
+```bash
+qring setup cursor          # .cursor/mcp.json (project) or --global for ~/.cursor
+qring setup kiro            # .kiro/settings/mcp.json, with read-only autoApprove list
+qring setup claude          # .mcp.json (project scope)
+
+# Preview without writing
+qring setup cursor --dry-run
+```
+
+### Push to Deployment Platforms
+
+Push manifest secrets to GitHub Actions, Vercel, or Cloudflare Workers through each platform's **own authenticated CLI** (`gh` / `vercel` / `wrangler`) — q-ring never holds platform tokens, and values travel over stdin, never argv. Every push is recorded in the audit chain.
+
+```bash
+# Push the .q-ring.json manifest keys to GitHub Actions secrets
+qring push github --repo you/your-app
+
+# Push to Vercel environments
+qring push vercel --vercel-env production,preview
+
+# Push to Cloudflare Workers secrets
+qring push cloudflare
+
+# Explicit keys, preview first
+qring push github --keys DATABASE_URL,API_KEY --dry-run
+```
+
 ### Secret Liveness Validation
 
 Test if a secret is actually valid with its target service. q-ring auto-detects the provider from key prefixes (`sk-` → OpenAI, `ghp_` → GitHub, etc.) or accepts an explicit provider name.
@@ -314,7 +376,7 @@ qring validate --all --manifest
 qring validate --list-providers
 ```
 
-**Built-in providers:** OpenAI, Stripe, GitHub, AWS (format check), Generic HTTP.
+**Built-in providers:** OpenAI, Anthropic, OpenRouter, Google AI (Gemini), Groq, Hugging Face, ElevenLabs*, Vercel*, Stripe, GitHub, AWS (format check), Generic HTTP. Keys are only ever sent in headers, never URLs. (*no safe public prefix — select explicitly with `--provider` or the manifest `provider` field.)
 
 Output:
 
@@ -436,6 +498,43 @@ qring approvals
 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).
@@ -584,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
@@ -597,6 +696,18 @@ qring audit:export --format json --since 2026-03-01
 qring audit:export --format csv --output audit-report.csv
 ```
 
+### Encrypted File Backend (Headless / CI)
+
+Hosts with no OS keyring at all (headless Linux, containers, CI) can opt into an encrypted file store. Everything — secrets, the audit anchor, the agent-memory key — routes through it.
+
+```bash
+export QRING_BACKEND=file
+export QRING_FILE_PASSPHRASE="a strong passphrase"   # required — no passphrase, no access
+qring set CI_TOKEN
+```
+
+The store is AES-256-GCM at `~/.config/q-ring/file-backend.enc` (mode `0600`, path override via `QRING_FILE_BACKEND_PATH`), keyed by PBKDF2 from the passphrase. It is **explicit-only**: a missing OS keyring never falls back to it silently, and without the passphrase every operation fails closed — q-ring never encrypts under a machine-derivable key.
+
 ### Team & Org Scopes
 
 Extend beyond `global` and `project` scopes with `team` and `org` scopes for shared secrets across groups. Resolution order: project → team → org → global (most specific wins).
@@ -992,6 +1103,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide (dev environment, conv
 ## 🔒 Security
 
 - **Local-first.** Core storage is your OS keychain — there is no q-ring cloud and no account. The MCP surface, audit log, and agent memory live on your machine (audit and memory files are written owner-only, `0600`).
+- **Written-down threat model.** What q-ring protects, what it doesn't, and where the residual risk lives — including an honest answer to the agent-exfiltration question — in [docs/threat-model.md](docs/threat-model.md).
 - **Hardened by adversarial review.** v0.14.0 shipped the results of an internal adversarial audit — policy-bypass, approval-scoping, and exec-profile findings all fixed, each with regression tests. Details are in the [CHANGELOG](CHANGELOG.md) `Security` sections (house style since 0.12.0: fix first, then disclose there).
 - **Reporting a vulnerability.** Use [GitHub private vulnerability reporting](https://github.com/I4cTime/q-ring/security/advisories/new) — see [SECURITY.md](SECURITY.md) for the supported-versions table and response commitments (48-hour acknowledgement, 7-day assessment).