@i4ctime/q-ring 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) 2026 I4cTime
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to use,
+copy, modify, and merge the Software for their own use only, subject to the
+following conditions:
+
+You may not publish, distribute, sublicense, or sell copies of the Software
+or any derivative work, in source or binary form, without explicit written
+permission from the copyright holder.
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,286 @@
+<div align="center">
+  <img src="./assets/logo.png" alt="q-ring logo" width="100%" />
+</div>
+
+# q-ring
+
+Quantum keyring for AI coding tools — Cursor, Kiro, Claude Code, and more.
+
+Secrets are stored in your OS native keyring (macOS Keychain, GNOME/KDE Keyring, Windows Credential Manager). q-ring layers quantum mechanics concepts on top to create a secret management system that's actually novel: superposition, entanglement, decay, tunneling, teleportation, and an autonomous agent.
+
+## Install
+
+```bash
+npm install -g q-ring
+```
+
+## Quick Start
+
+```bash
+# Store a secret
+qring set OPENAI_API_KEY sk-...
+
+# Retrieve it
+qring get OPENAI_API_KEY
+
+# List all keys (values are never shown)
+qring list
+
+# Generate a cryptographic secret
+qring generate --format api-key --prefix "sk-" --save MY_KEY
+
+# Check health of all secrets
+qring health
+```
+
+## Quantum Features
+
+### Superposition — One Key, Multiple Environments
+
+A single secret can hold different values for dev, staging, and prod simultaneously. The correct value resolves based on your current context.
+
+```bash
+# Set environment-specific values
+qring set API_KEY "sk-dev-123" --env dev
+qring set API_KEY "sk-stg-456" --env staging
+qring set API_KEY "sk-prod-789" --env prod
+
+# Value resolves based on context
+QRING_ENV=prod qring get API_KEY   # → sk-prod-789
+QRING_ENV=dev  qring get API_KEY   # → sk-dev-123
+
+# Inspect the quantum state
+qring inspect API_KEY
+```
+
+### Wavefunction Collapse — Smart Environment Detection
+
+q-ring auto-detects your environment without explicit flags. Resolution order:
+
+1. `--env` flag
+2. `QRING_ENV` environment variable
+3. `NODE_ENV` environment variable
+4. Git branch heuristics (`main`/`master` → prod, `develop` → dev)
+5. `.q-ring.json` project config
+6. Default environment from the secret
+
+```bash
+# See what environment q-ring detects
+qring env
+
+# Project config (.q-ring.json)
+echo '{"env": "staging", "branchMap": {"release/*": "staging"}}' > .q-ring.json
+```
+
+### Quantum Decay — Secrets with TTL
+
+Secrets can have a time-to-live. Expired secrets are blocked from reads. Stale secrets (75%+ lifetime) trigger warnings.
+
+```bash
+# Set a secret that expires in 1 hour
+qring set SESSION_TOKEN "tok-..." --ttl 3600
+
+# Set with explicit expiry
+qring set CERT_KEY "..." --expires "2026-06-01T00:00:00Z"
+
+# Health check shows decay status
+qring health
+```
+
+### Observer Effect — Audit Everything
+
+Every secret read, write, and delete is logged. Access patterns are tracked for anomaly detection.
+
+```bash
+# View audit log
+qring audit
+qring audit --key OPENAI_KEY --limit 50
+
+# Detect anomalies (burst access, unusual hours)
+qring audit --anomalies
+```
+
+### Quantum Noise — Secret Generation
+
+Generate cryptographically strong secrets in common formats.
+
+```bash
+qring generate                          # API key (default)
+qring generate --format password -l 32  # Strong password
+qring generate --format uuid            # UUID v4
+qring generate --format token           # Base64url token
+qring generate --format hex -l 64       # 64-byte hex
+qring generate --format api-key --prefix "sk-live-" --save STRIPE_KEY
+```
+
+### Entanglement — Linked Secrets
+
+Link secrets across projects. When you rotate one, all entangled copies update automatically.
+
+```bash
+# Entangle two secrets
+qring entangle API_KEY API_KEY_BACKUP
+
+# Now updating API_KEY also updates API_KEY_BACKUP
+qring set API_KEY "new-value"
+```
+
+### Tunneling — Ephemeral Secrets
+
+Create secrets that exist only in memory. They never touch disk. Optional TTL and max-read self-destruction.
+
+```bash
+# Create an ephemeral secret (returns tunnel ID)
+qring tunnel create "temporary-token-xyz" --ttl 300 --max-reads 1
+
+# Read it (self-destructs after this read)
+qring tunnel read tun_abc123
+
+# List active tunnels
+qring tunnel list
+```
+
+### Teleportation — Encrypted Sharing
+
+Pack secrets into AES-256-GCM encrypted bundles for secure transfer between machines.
+
+```bash
+# Pack secrets (prompts for passphrase)
+qring teleport pack --keys "API_KEY,DB_PASS" > bundle.txt
+
+# On another machine: unpack (prompts for passphrase)
+cat bundle.txt | qring teleport unpack
+
+# Preview without importing
+qring teleport unpack <bundle> --dry-run
+```
+
+### Agent Mode — Autonomous Monitoring
+
+A background daemon that continuously monitors secret health, detects anomalies, and optionally auto-rotates expired secrets.
+
+```bash
+# Start the agent
+qring agent --interval 60 --verbose
+
+# With auto-rotation of expired secrets
+qring agent --auto-rotate
+
+# Single scan (for CI/cron)
+qring agent --once
+```
+
+## MCP Server
+
+q-ring includes a full MCP server with 20 tools for AI agent integration.
+
+### Core Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_secret` | Retrieve with superposition collapse + observer logging |
+| `list_secrets` | List keys with quantum metadata (never exposes values) |
+| `set_secret` | Store with optional TTL, env state, tags |
+| `delete_secret` | Remove a secret |
+| `has_secret` | Boolean check (respects decay) |
+
+### Quantum Tools
+
+| Tool | Description |
+|------|-------------|
+| `inspect_secret` | Full quantum state (states, decay, entanglement, access count) |
+| `detect_environment` | Wavefunction collapse — detect current env context |
+| `generate_secret` | Quantum noise — generate and optionally save secrets |
+| `entangle_secrets` | Link two secrets for synchronized rotation |
+
+### Tunneling Tools
+
+| Tool | Description |
+|------|-------------|
+| `tunnel_create` | Create ephemeral in-memory secret |
+| `tunnel_read` | Read (may self-destruct) |
+| `tunnel_list` | List active tunnels |
+| `tunnel_destroy` | Immediately destroy |
+
+### Teleportation Tools
+
+| Tool | Description |
+|------|-------------|
+| `teleport_pack` | Encrypt secrets into a portable bundle |
+| `teleport_unpack` | Decrypt and import a bundle |
+
+### Observer & Health Tools
+
+| Tool | Description |
+|------|-------------|
+| `audit_log` | Query access history |
+| `detect_anomalies` | Scan for unusual access patterns |
+| `health_check` | Full health report |
+| `agent_scan` | Run autonomous agent scan |
+
+### Cursor / Kiro Configuration
+
+Add to `.cursor/mcp.json` or `.kiro/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "q-ring": {
+      "command": "node",
+      "args": ["/path/to/quantum_ring/dist/mcp.js"]
+    }
+  }
+}
+```
+
+### Claude Code Configuration
+
+Add to `~/.claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "q-ring": {
+      "command": "node",
+      "args": ["/path/to/quantum_ring/dist/mcp.js"]
+    }
+  }
+}
+```
+
+## Architecture
+
+```
+qring CLI ─────┐
+               ├──▶ Core Engine ──▶ @napi-rs/keyring ──▶ OS Keyring
+MCP Server ────┘       │
+                       ├── Envelope (quantum metadata)
+                       ├── Scope Resolver (global / project)
+                       ├── Collapse (env detection)
+                       ├── Observer (audit log)
+                       ├── Noise (secret generation)
+                       ├── Entanglement (cross-secret linking)
+                       ├── Tunnel (ephemeral in-memory)
+                       ├── Teleport (encrypted sharing)
+                       └── Agent (autonomous monitor)
+```
+
+## Project Config (`.q-ring.json`)
+
+Optional per-project configuration:
+
+```json
+{
+  "env": "dev",
+  "defaultEnv": "dev",
+  "branchMap": {
+    "main": "prod",
+    "develop": "dev",
+    "staging": "staging"
+  }
+}
+```
+
+## License
+
+MIT