@i4ctime/q-ring 0.14.0 → 0.15.0

package/README.md

@@ -1,16 +1,24 @@
 <div align="center">
-  <img src="https://unpkg.com/@i4ctime/q-ring@latest/assets/social-card-optimized.jpg" alt="q-ring logo" width="100%" />
+  <img src="https://raw.githubusercontent.com/I4cTime/q-ring/main/assets/social-card-optimized.jpg" alt="q-ring — never paste an API key into .env again" width="100%" />
 </div>
 
 # q-ring
 
-**The first quantum-inspired keyring built specifically for AI coding agents.**
+**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:
 
@@ -383,7 +445,7 @@ qring exec -- npm run deploy
 # Inject only specific tags
 qring exec --tags backend -- node server.js
 
-# Run with a restricted profile (blocks curl/wget/ssh, 30s timeout)
+# Run with a restricted profile (blocks network tools and interpreters/shells, 30s timeout)
 qring exec --profile restricted -- npm test
 ```
 
@@ -436,6 +498,8 @@ 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`.
+
 ### 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).
@@ -533,6 +597,8 @@ Define project-level governance rules in `.q-ring.json` to control which MCP too
 
 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.
 
+Policy files are schema-validated and **fail closed**: an invalid `policy` object (say, a typo like `denytools`) raises a `PolicyConfigError` instead of being silently ignored, so a malformed rule can never widen access.
+
 ```bash
 # View the active policy
 qring policy
@@ -568,7 +634,7 @@ Example policy in `.q-ring.json`:
 Restrict command execution with named profiles that control allowed commands, network access, timeouts, and environment sanitization.
 
 ```bash
-# Run with the "restricted" profile (blocks curl, wget, ssh; 30s timeout)
+# Run with the "restricted" profile (blocks network tools and interpreters/shells; 30s timeout)
 qring exec --profile restricted -- npm test
 
 # Run with the "ci" profile (5min timeout, allows network)
@@ -578,11 +644,11 @@ qring exec --profile ci -- npm run deploy
 qring exec -- echo "hello"
 ```
 
-**Built-in profiles:** `unrestricted`, `restricted` (no network tools, 30s limit), `ci` (5min limit, blocks destructive commands).
+**Built-in profiles:** `unrestricted`, `restricted` (denies network tools *and* interpreters/shells — `python -c`, `node -e`, `bash` and friends can't exfiltrate injected secrets; 30s limit), `ci` (5min limit, blocks destructive commands).
 
 ### Tamper-Evident Audit
 
-Every audit event includes a SHA-256 hash of the previous event, creating a tamper-evident chain. 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.
 
 ```bash
 # Verify the entire audit chain
@@ -595,6 +661,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).
@@ -987,6 +1065,13 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide (dev environment, conv
   - **Claude Code:** `pnpm run plugin:sync:claude` copies `claude-code-plugin/` into the current directory (or pass a project path; add `--user` to install at `~/.claude/`).
 - See also [docs/cli-mcp-parity.md](docs/cli-mcp-parity.md).
 
+## 🔒 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).
+
 ## 📜 License
 
 [AGPL-3.0](LICENSE) - Free to use, modify, and share. Any derivative work or hosted service must release its source code under the same license.