@i4ctime/q-ring 0.3.2 → 0.4.0

package/README.md

@@ -138,6 +138,9 @@ qring entangle API_KEY API_KEY_BACKUP
 
 # Now updating API_KEY also updates API_KEY_BACKUP
 qring set API_KEY "new-value"
+
+# Unlink entangled secrets
+qring disentangle API_KEY API_KEY_BACKUP
 ```
 
 ### Tunneling — Ephemeral Secrets
@@ -170,6 +173,158 @@ cat bundle.txt | qring teleport unpack
 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.
+
+```bash
+# Import all secrets from a .env file
+qring import .env
+
+# Import to project scope, skipping existing keys
+qring import .env --project --skip-existing
+
+# Preview what would be imported
+qring import .env --dry-run
+```
+
+### Selective Export
+
+Export only the secrets you need using key names or tag filters.
+
+```bash
+# Export specific keys
+qring export --keys "API_KEY,DB_PASS,REDIS_URL"
+
+# Export by tag
+qring export --tags "backend"
+
+# Combine with format
+qring export --keys "API_KEY,DB_PASS" --format json
+```
+
+### Secret Search and Filtering
+
+Filter `qring list` output by tag, expiry state, or key pattern.
+
+```bash
+# Filter by tag
+qring list --tag backend
+
+# Show only expired secrets
+qring list --expired
+
+# Show only stale secrets (75%+ decay)
+qring list --stale
+
+# Glob pattern on key name
+qring list --filter "API_*"
+```
+
+### Project Secret Manifest
+
+Declare required secrets in `.q-ring.json` and validate project readiness with a single command.
+
+```bash
+# Validate project secrets against the manifest
+qring check
+
+# See which secrets are present, missing, expired, or stale
+qring check --project-path /path/to/project
+```
+
+### Env File Sync
+
+Generate a `.env` file from the project manifest, resolving each key from q-ring with environment-aware superposition collapse.
+
+```bash
+# Generate to stdout
+qring env:generate
+
+# Write to a file
+qring env:generate --output .env
+
+# Force a specific environment
+qring env:generate --env staging --output .env.staging
+```
+
+### 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.
+
+```bash
+# Validate a single secret
+qring validate OPENAI_API_KEY
+
+# Force a specific provider
+qring validate SOME_KEY --provider stripe
+
+# Validate all secrets with detectable providers
+qring validate --all
+
+# Only validate manifest-declared secrets
+qring validate --all --manifest
+
+# List available providers
+qring validate --list-providers
+```
+
+**Built-in providers:** OpenAI, Stripe, GitHub, AWS (format check), Generic HTTP.
+
+Output:
+
+```
+  ✓ OPENAI_API_KEY   valid    (openai, 342ms)
+  ✗ STRIPE_KEY       invalid  (stripe, 128ms) — API key has been revoked
+  ⚠ AWS_ACCESS_KEY   error    (aws, 10002ms) — network timeout
+  ○ DATABASE_URL     unknown  — no provider detected
+```
+
+### Hooks — Callbacks on Secret Change
+
+Register webhooks, shell commands, or process signals that fire when secrets are created, updated, or deleted. Supports key matching, glob patterns, tag filtering, and scope constraints.
+
+```bash
+# Run a shell command when a secret changes
+qring hook add --key DB_PASS --exec "docker restart app"
+
+# POST to a webhook on any write/delete
+qring hook add --key API_KEY --url "https://hooks.example.com/rotate"
+
+# Trigger on all secrets tagged "backend"
+qring hook add --tag backend --exec "pm2 restart all"
+
+# Signal a process when DB secrets change
+qring hook add --key-pattern "DB_*" --signal-target "node"
+
+# List all hooks
+qring hook list
+
+# Remove a hook
+qring hook remove <id>
+
+# Enable/disable
+qring hook enable <id>
+qring hook disable <id>
+
+# Dry-run test a hook
+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`.
+
+### Configurable Rotation
+
+Set a rotation format per secret so the agent auto-rotates with the correct value shape.
+
+```bash
+# Store a secret with rotation format metadata
+qring set STRIPE_KEY "sk-..." --rotation-format api-key --rotation-prefix "sk-"
+
+# Store a password with password rotation format
+qring set DB_PASS "..." --rotation-format password
+```
+
 ### Agent Mode — Autonomous Monitoring
 
 A background daemon that continuously monitors secret health, detects anomalies, and optionally auto-rotates expired secrets.
@@ -204,17 +359,21 @@ qring status --no-open
 
 ## MCP Server
 
-q-ring includes a full MCP server with 20 tools for AI agent integration.
+q-ring includes a full MCP server with 31 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 |
+| `list_secrets` | List keys with quantum metadata, filterable by tag/expiry/pattern |
+| `set_secret` | Store with optional TTL, env state, tags, rotation format |
 | `delete_secret` | Remove a secret |
 | `has_secret` | Boolean check (respects decay) |
+| `export_secrets` | Export as .env/JSON with optional key and tag filters |
+| `import_dotenv` | Parse and import secrets from .env content |
+| `check_project` | Validate project secrets against `.q-ring.json` manifest |
+| `env_generate` | Generate .env content from the project manifest |
 
 ### Quantum Tools
 
@@ -224,6 +383,7 @@ q-ring includes a full MCP server with 20 tools for AI agent integration.
 | `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 |
+| `disentangle_secrets` | Remove entanglement between two secrets |
 
 ### Tunneling Tools
 
@@ -241,6 +401,21 @@ q-ring includes a full MCP server with 20 tools for AI agent integration.
 | `teleport_pack` | Encrypt secrets into a portable bundle |
 | `teleport_unpack` | Decrypt and import a bundle |
 
+### Validation Tools
+
+| Tool | Description |
+|------|-------------|
+| `validate_secret` | Test if a secret is valid with its target service (OpenAI, Stripe, GitHub, etc.) |
+| `list_providers` | List all available validation providers |
+
+### Hook Tools
+
+| Tool | Description |
+|------|-------------|
+| `register_hook` | Register a shell/HTTP/signal callback on secret changes |
+| `list_hooks` | List all registered hooks with match criteria and status |
+| `remove_hook` | Remove a registered hook by ID |
+
 ### Observer & Health Tools
 
 | Tool | Description |
@@ -316,13 +491,16 @@ qring CLI ─────┐
 MCP Server ────┘       │
                        ├── Envelope (quantum metadata)
                        ├── Scope Resolver (global / project)
-                       ├── Collapse (env detection)
+                       ├── Collapse (env detection + branchMap globs)
                        ├── Observer (audit log)
                        ├── Noise (secret generation)
                        ├── Entanglement (cross-secret linking)
+                       ├── Validate (provider-based liveness checks)
+                       ├── Hooks (shell/HTTP/signal callbacks)
+                       ├── Import (.env file ingestion)
                        ├── Tunnel (ephemeral in-memory)
                        ├── Teleport (encrypted sharing)
-                       ├── Agent (autonomous monitor)
+                       ├── Agent (autonomous monitor + rotation)
                        └── Dashboard (live status via SSE)
 ```
 
@@ -337,11 +515,23 @@ Optional per-project configuration:
   "branchMap": {
     "main": "prod",
     "develop": "dev",
-    "staging": "staging"
+    "staging": "staging",
+    "release/*": "staging",
+    "feature/*": "dev"
+  },
+  "secrets": {
+    "OPENAI_API_KEY": { "required": true, "description": "OpenAI API key", "format": "api-key", "prefix": "sk-", "provider": "openai" },
+    "DATABASE_URL": { "required": true, "description": "Postgres connection string", "validationUrl": "https://api.example.com/health" },
+    "SENTRY_DSN": { "required": false, "description": "Sentry error tracking" }
   }
 }
 ```
 
+- **`branchMap`** supports glob patterns with `*` wildcards (e.g., `release/*` matches `release/v1.0`)
+- **`secrets`** declares the project's required secrets — use `qring check` to validate, `qring env:generate` to produce a `.env` file
+- **`provider`** associates a liveness validation provider with a secret (e.g., `"openai"`, `"stripe"`, `"github"`) — use `qring validate` to test
+- **`validationUrl`** configures the generic HTTP provider's endpoint for custom validation
+
 ## 📜 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.

package/dist/{chunk-F4SPZ774.js → chunk-6IQ5SFLI.js}

@@ -20,7 +20,10 @@ function createEnvelope(value, opts) {
       description: opts?.description,
       tags: opts?.tags,
       entangled: opts?.entangled,
-      accessCount: 0
+      accessCount: 0,
+      rotationFormat: opts?.rotationFormat,
+      rotationPrefix: opts?.rotationPrefix,
+      provider: opts?.provider
     }
   };
 }
@@ -173,7 +176,7 @@ function collapseEnvironment(ctx = {}) {
   const branch = detectGitBranch(ctx.projectPath);
   if (branch) {
     const branchMap = { ...BRANCH_ENV_MAP, ...config?.branchMap };
-    const mapped = branchMap[branch];
+    const mapped = branchMap[branch] ?? matchGlob(branchMap, branch);
     if (mapped) {
       return { env: mapped, source: "git-branch" };
     }
@@ -183,6 +186,16 @@ function collapseEnvironment(ctx = {}) {
   }
   return null;
 }
+function matchGlob(branchMap, branch) {
+  for (const [pattern, env] of Object.entries(branchMap)) {
+    if (!pattern.includes("*")) continue;
+    const regex = new RegExp(
+      "^" + pattern.replace(/\*/g, ".*") + "$"
+    );
+    if (regex.test(branch)) return env;
+  }
+  return void 0;
+}
 function mapEnvName(raw) {
   const lower = raw.toLowerCase();
   if (lower === "production") return "prod";
@@ -323,6 +336,13 @@ function entangle(source, target) {
     saveRegistry(registry);
   }
 }
+function disentangle(source, target) {
+  const registry = loadRegistry();
+  registry.pairs = registry.pairs.filter(
+    (p) => !(p.source.service === source.service && p.source.key === source.key && p.target.service === target.service && p.target.key === target.key || p.source.service === target.service && p.source.key === target.key && p.target.service === source.service && p.target.key === source.key)
+  );
+  saveRegistry(registry);
+}
 function findEntangled(source) {
   const registry = loadRegistry();
   return registry.pairs.filter(
@@ -373,6 +393,213 @@ function resolveScope(opts) {
   return [{ scope: "global", service: globalService() }];
 }
 
+// src/core/hooks.ts
+import { existsSync as existsSync4, readFileSync as readFileSync4, writeFileSync as writeFileSync2, mkdirSync as mkdirSync3 } from "fs";
+import { join as join4 } from "path";
+import { homedir as homedir3 } from "os";
+import { exec } from "child_process";
+import { request as httpsRequest } from "https";
+import { request as httpRequest } from "http";
+import { randomUUID } from "crypto";
+function getRegistryPath2() {
+  const dir = join4(homedir3(), ".config", "q-ring");
+  if (!existsSync4(dir)) {
+    mkdirSync3(dir, { recursive: true });
+  }
+  return join4(dir, "hooks.json");
+}
+function loadRegistry2() {
+  const path = getRegistryPath2();
+  if (!existsSync4(path)) {
+    return { hooks: [] };
+  }
+  try {
+    return JSON.parse(readFileSync4(path, "utf8"));
+  } catch {
+    return { hooks: [] };
+  }
+}
+function saveRegistry2(registry) {
+  writeFileSync2(getRegistryPath2(), JSON.stringify(registry, null, 2));
+}
+function registerHook(entry) {
+  const registry = loadRegistry2();
+  const hook = {
+    ...entry,
+    id: randomUUID().slice(0, 8),
+    createdAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  registry.hooks.push(hook);
+  saveRegistry2(registry);
+  return hook;
+}
+function removeHook(id) {
+  const registry = loadRegistry2();
+  const before = registry.hooks.length;
+  registry.hooks = registry.hooks.filter((h) => h.id !== id);
+  if (registry.hooks.length < before) {
+    saveRegistry2(registry);
+    return true;
+  }
+  return false;
+}
+function listHooks() {
+  return loadRegistry2().hooks;
+}
+function matchesHook(hook, payload, tags) {
+  if (!hook.enabled) return false;
+  const m = hook.match;
+  if (m.action?.length && !m.action.includes(payload.action)) return false;
+  if (m.key && m.key !== payload.key) return false;
+  if (m.keyPattern) {
+    const regex = new RegExp(
+      "^" + m.keyPattern.replace(/\*/g, ".*") + "$",
+      "i"
+    );
+    if (!regex.test(payload.key)) return false;
+  }
+  if (m.tag && (!tags || !tags.includes(m.tag))) return false;
+  if (m.scope && m.scope !== payload.scope) return false;
+  return true;
+}
+function executeShell(command, payload) {
+  return new Promise((resolve) => {
+    const env = {
+      ...process.env,
+      QRING_HOOK_KEY: payload.key,
+      QRING_HOOK_ACTION: payload.action,
+      QRING_HOOK_SCOPE: payload.scope
+    };
+    exec(command, { timeout: 3e4, env }, (err, stdout, stderr) => {
+      if (err) {
+        resolve({ hookId: "", success: false, message: `Shell error: ${err.message}` });
+      } else {
+        resolve({ hookId: "", success: true, message: stdout.trim() || "OK" });
+      }
+    });
+  });
+}
+function executeHttp(url, payload) {
+  return new Promise((resolve) => {
+    const body = JSON.stringify(payload);
+    const parsedUrl = new URL(url);
+    const reqFn = parsedUrl.protocol === "https:" ? httpsRequest : httpRequest;
+    const req = reqFn(
+      url,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Content-Length": Buffer.byteLength(body),
+          "User-Agent": "q-ring-hooks/1.0"
+        },
+        timeout: 1e4
+      },
+      (res) => {
+        let data = "";
+        res.on("data", (chunk) => data += chunk);
+        res.on("end", () => {
+          resolve({
+            hookId: "",
+            success: (res.statusCode ?? 0) >= 200 && (res.statusCode ?? 0) < 300,
+            message: `HTTP ${res.statusCode}`
+          });
+        });
+      }
+    );
+    req.on("error", (err) => {
+      resolve({ hookId: "", success: false, message: `HTTP error: ${err.message}` });
+    });
+    req.on("timeout", () => {
+      req.destroy();
+      resolve({ hookId: "", success: false, message: "HTTP timeout" });
+    });
+    req.write(body);
+    req.end();
+  });
+}
+function executeSignal(target, signal = "SIGHUP") {
+  return new Promise((resolve) => {
+    const pid = parseInt(target, 10);
+    if (!isNaN(pid)) {
+      try {
+        process.kill(pid, signal);
+        resolve({ hookId: "", success: true, message: `Signal ${signal} sent to PID ${pid}` });
+      } catch (err) {
+        resolve({ hookId: "", success: false, message: `Signal error: ${err instanceof Error ? err.message : String(err)}` });
+      }
+      return;
+    }
+    exec(`pgrep -f "${target}"`, { timeout: 5e3 }, (err, stdout) => {
+      if (err || !stdout.trim()) {
+        resolve({ hookId: "", success: false, message: `Process "${target}" not found` });
+        return;
+      }
+      const pids = stdout.trim().split("\n").map((p) => parseInt(p.trim(), 10)).filter((p) => !isNaN(p));
+      let sent = 0;
+      for (const p of pids) {
+        try {
+          process.kill(p, signal);
+          sent++;
+        } catch {
+        }
+      }
+      resolve({ hookId: "", success: sent > 0, message: `Signal ${signal} sent to ${sent} process(es)` });
+    });
+  });
+}
+async function executeHook(hook, payload) {
+  let result;
+  switch (hook.type) {
+    case "shell":
+      result = hook.command ? await executeShell(hook.command, payload) : { hookId: hook.id, success: false, message: "No command specified" };
+      break;
+    case "http":
+      result = hook.url ? await executeHttp(hook.url, payload) : { hookId: hook.id, success: false, message: "No URL specified" };
+      break;
+    case "signal":
+      result = hook.signal ? await executeSignal(hook.signal.target, hook.signal.signal) : { hookId: hook.id, success: false, message: "No signal target specified" };
+      break;
+    default:
+      result = { hookId: hook.id, success: false, message: `Unknown hook type: ${hook.type}` };
+  }
+  result.hookId = hook.id;
+  return result;
+}
+async function fireHooks(payload, tags) {
+  const hooks = listHooks();
+  const matching = hooks.filter((h) => matchesHook(h, payload, tags));
+  if (matching.length === 0) return [];
+  const results = await Promise.allSettled(
+    matching.map((h) => executeHook(h, payload))
+  );
+  const hookResults = [];
+  for (const r of results) {
+    if (r.status === "fulfilled") {
+      hookResults.push(r.value);
+    } else {
+      hookResults.push({
+        hookId: "unknown",
+        success: false,
+        message: r.reason?.message ?? "Hook execution failed"
+      });
+    }
+  }
+  for (const r of hookResults) {
+    try {
+      logAudit({
+        action: "write",
+        key: payload.key,
+        scope: payload.scope,
+        source: payload.source,
+        detail: `hook:${r.hookId} ${r.success ? "ok" : "fail"} \u2014 ${r.message}`
+      });
+    } catch {
+    }
+  }
+  return hookResults;
+}
+
 // src/core/keyring.ts
 function readEnvelope(service, key) {
   const entry = new Entry(service, key);
@@ -432,6 +659,9 @@ function setSecret(key, value, opts = {}) {
   const source = opts.source ?? "cli";
   const existing = readEnvelope(service, key);
   let envelope;
+  const rotFmt = opts.rotationFormat ?? existing?.meta.rotationFormat;
+  const rotPfx = opts.rotationPrefix ?? existing?.meta.rotationPrefix;
+  const prov = opts.provider ?? existing?.meta.provider;
   if (opts.states) {
     envelope = createEnvelope("", {
       states: opts.states,
@@ -440,7 +670,10 @@ function setSecret(key, value, opts = {}) {
       tags: opts.tags,
       ttlSeconds: opts.ttlSeconds,
       expiresAt: opts.expiresAt,
-      entangled: existing?.meta.entangled
+      entangled: existing?.meta.entangled,
+      rotationFormat: rotFmt,
+      rotationPrefix: rotPfx,
+      provider: prov
     });
   } else {
     envelope = createEnvelope(value, {
@@ -448,7 +681,10 @@ function setSecret(key, value, opts = {}) {
       tags: opts.tags,
       ttlSeconds: opts.ttlSeconds,
       expiresAt: opts.expiresAt,
-      entangled: existing?.meta.entangled
+      entangled: existing?.meta.entangled,
+      rotationFormat: rotFmt,
+      rotationPrefix: rotPfx,
+      provider: prov
     });
   }
   if (existing) {
@@ -480,6 +716,14 @@ function setSecret(key, value, opts = {}) {
     } catch {
     }
   }
+  fireHooks({
+    action: "write",
+    key,
+    scope,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    source
+  }, envelope.meta.tags).catch(() => {
+  });
 }
 function deleteSecret(key, opts = {}) {
   const scopes = resolveScope(opts);
@@ -491,12 +735,31 @@ function deleteSecret(key, opts = {}) {
       if (entry.deleteCredential()) {
         deleted = true;
         logAudit({ action: "delete", key, scope, source });
+        fireHooks({
+          action: "delete",
+          key,
+          scope,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          source
+        }).catch(() => {
+        });
       }
     } catch {
     }
   }
   return deleted;
 }
+function hasSecret(key, opts = {}) {
+  const scopes = resolveScope(opts);
+  for (const { service } of scopes) {
+    const envelope = readEnvelope(service, key);
+    if (envelope) {
+      const decay = checkDecay(envelope);
+      if (!decay.isExpired) return true;
+    }
+  }
+  return false;
+}
 function listSecrets(opts = {}) {
   const source = opts.source ?? "cli";
   const services = [];
@@ -538,8 +801,17 @@ function listSecrets(opts = {}) {
 function exportSecrets(opts = {}) {
   const format = opts.format ?? "env";
   const env = resolveEnv(opts);
-  const entries = listSecrets(opts);
+  let entries = listSecrets(opts);
   const source = opts.source ?? "cli";
+  if (opts.keys?.length) {
+    const keySet = new Set(opts.keys);
+    entries = entries.filter((e) => keySet.has(e.key));
+  }
+  if (opts.tags?.length) {
+    entries = entries.filter(
+      (e) => opts.tags.some((t) => e.envelope?.meta.tags?.includes(t))
+    );
+  }
   const merged = /* @__PURE__ */ new Map();
   const globalEntries = entries.filter((e) => e.scope === "global");
   const projectEntries = entries.filter((e) => e.scope === "project");
@@ -581,6 +853,19 @@ function entangleSecrets(sourceKey, sourceOpts, targetKey, targetOpts) {
     detail: `entangled with ${targetKey}`
   });
 }
+function disentangleSecrets(sourceKey, sourceOpts, targetKey, targetOpts) {
+  const sourceScopes = resolveScope({ ...sourceOpts, scope: sourceOpts.scope ?? "global" });
+  const targetScopes = resolveScope({ ...targetOpts, scope: targetOpts.scope ?? "global" });
+  const source = { service: sourceScopes[0].service, key: sourceKey };
+  const target = { service: targetScopes[0].service, key: targetKey };
+  disentangle(source, target);
+  logAudit({
+    action: "entangle",
+    key: sourceKey,
+    source: sourceOpts.source ?? "cli",
+    detail: `disentangled from ${targetKey}`
+  });
+}
 
 // src/core/tunnel.ts
 var tunnelStore = /* @__PURE__ */ new Map();
@@ -655,21 +940,28 @@ function tunnelList() {
 
 export {
   checkDecay,
+  readProjectConfig,
   collapseEnvironment,
   logAudit,
   queryAudit,
   detectAnomalies,
   listEntanglements,
+  registerHook,
+  removeHook,
+  listHooks,
+  fireHooks,
   getSecret,
   getEnvelope,
   setSecret,
   deleteSecret,
+  hasSecret,
   listSecrets,
   exportSecrets,
   entangleSecrets,
+  disentangleSecrets,
   tunnelCreate,
   tunnelRead,
   tunnelDestroy,
   tunnelList
 };
-//# sourceMappingURL=chunk-F4SPZ774.js.map
+//# sourceMappingURL=chunk-6IQ5SFLI.js.map