@i4ctime/q-ring 0.17.6 → 0.18.0

package/README.md

@@ -10,7 +10,7 @@
 [![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)
+[![MCP Tools](https://img.shields.io/badge/MCP_tools-46-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)
@@ -33,7 +33,7 @@ Stop pasting API keys into plain-text `.env` files or wrestling with clunky secr
 - **Entanglement:** Link keys across projects so rotating one automatically updates them all.
 - **Tunneling:** Create ephemeral, in-memory secrets that self-destruct after a set time or read count.
 - **Teleportation:** Securely pack and share AES-256-GCM encrypted secret bundles.
-- **Seamless AI Integration:** 44 built-in MCP tools for native use in **Cursor**, **Kiro**, and **Claude Code**.
+- **Seamless AI Integration:** 46 built-in MCP tools for native use in **Cursor**, **Kiro**, and **Claude Code**.
 
 ## 🚀 Installation
 
@@ -111,6 +111,23 @@ QRING_ENV=dev  qring get API_KEY   # → sk-dev-123
 qring inspect API_KEY
 ```
 
+### Environment Promotion — Diff, Then Promote
+
+Once a secret carries per-environment states, promotion replaces copy-paste: compare two environments key by key (statuses only, never values), then copy a value from one state to another. `diff` exits 1 on drift, so it doubles as a CI gate; `promote` refuses to overwrite a differing target unless you say so.
+
+```bash
+# What differs between staging and prod? (same / different / missing on one side)
+qring diff staging prod
+
+# Make prod match staging for one key (asks before overwriting a different value)
+qring promote DATABASE_URL --from staging --to prod
+
+# Non-interactive, e.g. in a release script
+qring promote DATABASE_URL --from staging --to prod --force --json
+```
+
+MCP agents get the same two operations as `diff_environments` and `promote_secret`.
+
 ### Wavefunction Collapse — Smart Environment Detection
 
 q-ring auto-detects your environment without explicit flags. Resolution order:
@@ -210,16 +227,27 @@ qring tunnel list
 
 ### Teleportation — Encrypted Sharing
 
-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.
+Pack secrets into AES-256-GCM encrypted bundles for secure transfer between machines. Two ways to lock a bundle:
+
+- **Passphrase** (v1): keys derived with PBKDF2-HMAC-SHA512 (210 000 iterations); each bundle records its iteration count, so old bundles still unpack.
+- **Recipients** (v2, 0.18): each teammate runs `qring teleport keygen` once and shares their recipient string (`qring1…`, an X25519 public key; the private half lives in their OS keyring). `pack --to` encrypts a fresh content key to every recipient — HKDF-SHA256 over an ephemeral X25519 agreement, AES-256-GCM throughout, `node:crypto` only — so nothing secret travels beside the bundle and nobody has to whisper a passphrase.
 
 ```bash
-# Pack secrets (prompts for passphrase)
+# Passphrase bundle (prompts)
 qring teleport pack --keys "API_KEY,DB_PASS" > bundle.txt
+cat bundle.txt | qring teleport unpack
+
+# Recipient bundle: teammates publish their recipient once…
+qring teleport keygen            # → qring1a3F…  (share this; keep the keyring)
+qring teleport identity          # print it again later
+
+# …then you address the pack to them (repeatable or comma-separated)
+qring teleport pack --keys "API_KEY,DB_PASS" --to qring1a3F… --to qring1Zz9… > bundle.txt
 
-# On another machine: unpack (prompts for passphrase)
+# They unpack with the identity in their keyring — no passphrase
 cat bundle.txt | qring teleport unpack
 
-# Preview without importing
+# Preview: who it's addressed to, whether that's you, and what's inside
 qring teleport unpack <bundle> --dry-run
 ```
 
@@ -339,7 +367,7 @@ 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.
+Push manifest secrets to GitHub Actions, Vercel, Cloudflare Workers, fly.io, Railway, or Netlify through each platform's **own authenticated CLI** (`gh` / `vercel` / `wrangler` / `flyctl` / `railway` / `netlify`) — q-ring never holds platform tokens, and values travel over stdin (or, for Netlify's import-only CLI, a `0600` temp file that is removed immediately), never argv. Every push is recorded in the audit chain.
 
 ```bash
 # Push the .q-ring.json manifest keys to GitHub Actions secrets
@@ -351,6 +379,11 @@ qring push vercel --vercel-env production,preview
 # Push to Cloudflare Workers secrets
 qring push cloudflare
 
+# fly.io (flyctl secrets import over stdin — note flyctl deploys per import), Railway, Netlify
+qring push fly --app my-app
+qring push railway --service api --railway-env production
+qring push netlify --site 1234-abcd
+
 # Explicit keys, preview first
 qring push github --keys DATABASE_URL,API_KEY --dry-run
 ```
@@ -426,7 +459,7 @@ Hooks are fire-and-forget: a failing hook never blocks secret operations. The ho
 
 ### Configurable Rotation
 
-Set a rotation format per secret so the agent auto-rotates with the correct value shape.
+Set a rotation format per secret so the agent auto-rotates with the correct value shape, and a rotation interval so q-ring reminds you before a credential goes stale. Every secret remembers when its value last changed (`rotatedAt`); with `--rotate-every` it becomes *due soon* inside the last 20% of the interval (or the last 7 days, whichever is shorter) and *overdue* past it — in `qring inspect`, `qring rotate:due`, the dashboard's "Rotate soon" card and the `inspect_secret` tool.
 
 ```bash
 # Store a secret with rotation format metadata
@@ -434,6 +467,13 @@ 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
+
+# Remind me every 90 days
+qring set STRIPE_KEY "sk-..." --rotate-every 90
+
+# What needs rotating? (most overdue first; --all lists every scheduled secret)
+qring rotate:due
+qring rotate:due --json
 ```
 
 ### Secure Execution & Auto-Redaction
@@ -883,7 +923,7 @@ qring status --no-open
 
 ## MCP Server
 
-q-ring includes a full MCP server with 44 tools for AI agent integration.
+q-ring includes a full MCP server with 46 tools for AI agent integration.
 
 ### Core Tools
 
@@ -892,6 +932,8 @@ q-ring includes a full MCP server with 44 tools for AI agent integration.
 | `get_secret` | Read a secret value (collapses superposition, audits the read) |
 | `list_secrets` | List keys + metadata in scope (values never exposed); filter by tag, expiry, glob |
 | `set_secret` | Create or overwrite a single secret with optional TTL, per-env state, tags, rotation format |
+| `promote_secret` | Copy one secret's value from one environment state to another (no-op when equal; `force` to overwrite a differing target) |
+| `diff_environments` | Compare two environments key by key — same / different / only-a / only-b / collapsed; statuses only, never values |
 | `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 (skips approval-protected keys without a grant) |
@@ -1074,7 +1116,7 @@ The **q-ring Cursor Plugin** brings quantum secret management directly into your
 | **2 Agents** | `security-auditor` (proactive monitoring) and `secret-ops` (day-to-day assistant) |
 | **8 Commands** | `/qring:scan-secrets`, `/qring:health-check`, `/qring:rotate-expired`, `/qring:setup-project`, `/qring:teleport-secrets`, `/qring:dashboard`, `/qring:exec-safe`, `/qring:analyze` |
 | **3 Hooks** | `afterFileEdit` (lint scan), `sessionStart` (project context), `beforeShellExecution` (`.env` guard) |
-| **MCP Connector** | Auto-connects to `qring-mcp` via stdio — all 44 tools available |
+| **MCP Connector** | Auto-connects to `qring-mcp` via stdio — all 46 tools available |
 
 Install from the Cursor marketplace or see [`cursor-plugin/README.md`](cursor-plugin/README.md) for manual setup.
 

package/dist/{chunk-VMDD5QTJ.js → chunk-NTCTVLSK.js}

@@ -36,6 +36,10 @@ var SecretMetadataSchema = z.object({
   ephemeral: z.boolean().optional(),
   rotationFormat: z.string().optional(),
   rotationPrefix: z.string().optional(),
+  rotatedAt: z.string().optional(),
+  // `.catch(undefined)`: a bad interval strips the reminder rather than
+  // rejecting the whole envelope (which would surface the JSON as the value).
+  rotateEveryDays: z.number().int().positive().max(3650).optional().catch(void 0),
   provider: z.string().optional(),
   validationUrl: z.string().optional(),
   requiresApproval: z.boolean().optional(),
@@ -73,6 +77,8 @@ function createEnvelope(value, opts) {
       accessCount: 0,
       rotationFormat: opts?.rotationFormat,
       rotationPrefix: opts?.rotationPrefix,
+      rotatedAt: opts?.rotatedAt ?? now,
+      rotateEveryDays: opts?.rotateEveryDays,
       provider: opts?.provider,
       requiresApproval: opts?.requiresApproval,
       jitProvider: opts?.jitProvider,
@@ -302,14 +308,13 @@ import {
   closeSync,
   statSync as statSync3
 } from "fs";
-import { join as join5 } from "path";
-import { homedir as homedir3 } from "os";
+import { join as join6 } from "path";
 import { createHash, createHmac, randomBytes as randomBytes2 } from "crypto";
 
 // src/core/backend.ts
 import { Entry as NapiEntry, findCredentials as napiFindCredentials } from "@napi-rs/keyring";
 import { existsSync, readFileSync as readFileSync4, writeFileSync as writeFileSync2, mkdirSync as mkdirSync2, chmodSync } from "fs";
-import { dirname as dirname2, join as join4 } from "path";
+import { dirname as dirname2, join as join5 } from "path";
 import { homedir as homedir2 } from "os";
 import { createCipheriv, createDecipheriv, randomBytes, pbkdf2Sync } from "crypto";
 
@@ -321,8 +326,19 @@ import {
   readFileSync as readFileSync3,
   statSync as statSync2
 } from "fs";
-import { join as join3 } from "path";
+import { join as join4 } from "path";
+
+// src/utils/config-dir.ts
 import { homedir } from "os";
+import { join as join3 } from "path";
+var CONFIG_DIR_ENV = "QRING_CONFIG_DIR";
+function configDir() {
+  const override = process.env[CONFIG_DIR_ENV];
+  if (override && override.trim()) return override;
+  return join3(homedir(), ".config", "q-ring");
+}
+
+// src/utils/file-lock.ts
 function sleepSync(ms) {
   Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
@@ -335,11 +351,11 @@ function isProcessAlive(pid) {
   }
 }
 function withFileLock(name, fn, opts = {}) {
-  const baseDir = process.env.QRING_LOCK_DIR ?? (process.env.QRING_AUDIT_DIR ? join3(process.env.QRING_AUDIT_DIR, ".locks") : join3(homedir(), ".config", "q-ring"));
-  const lockDir = join3(baseDir, opts.dir ?? "locks");
+  const baseDir = process.env.QRING_LOCK_DIR ?? (process.env.QRING_AUDIT_DIR ? join4(process.env.QRING_AUDIT_DIR, ".locks") : configDir());
+  const lockDir = join4(baseDir, opts.dir ?? "locks");
   mkdirSync(lockDir, { recursive: true, mode: 448 });
   const safe = Buffer.from(name, "utf8").toString("base64url");
-  const lockPath = join3(lockDir, `${safe}.lock`);
+  const lockPath = join4(lockDir, `${safe}.lock`);
   const deadline = Date.now() + (opts.timeoutMs ?? 8e3);
   const staleMs = opts.staleMs ?? 3e4;
   while (Date.now() < deadline) {
@@ -382,6 +398,12 @@ var PATH_ENV = "QRING_FILE_BACKEND_PATH";
 var PBKDF2_ITERATIONS = 21e4;
 var KEY_LENGTH = 32;
 var FILE_PREFIX = "qfile1";
+function keyringFailure(op, err) {
+  const detail = err instanceof Error ? err.message : String(err);
+  return new BackendUnavailableError(
+    `OS keyring ${op} failed \u2014 the credential store is locked or unreachable (${detail}). Unlock your keyring (or set ${BACKEND_ENV}=file with ${PASSPHRASE_ENV} for a headless store) and retry.`
+  );
+}
 var BackendUnavailableError = class extends Error {
   constructor(message) {
     super(message);
@@ -399,7 +421,7 @@ function activeBackend() {
   return "keyring";
 }
 function storePath() {
-  return process.env[PATH_ENV] ?? join4(homedir2(), ".config", "q-ring", "file-backend.enc");
+  return process.env[PATH_ENV] ?? join5(homedir2(), ".config", "q-ring", "file-backend.enc");
 }
 function passphrase() {
   const p = process.env[PASSPHRASE_ENV];
@@ -492,7 +514,11 @@ var Entry = class {
     if (activeBackend() === "file") {
       return loadStore().map[this.storeKey()] ?? null;
     }
-    return this.delegate().getPassword();
+    try {
+      return this.delegate().getPassword();
+    } catch (err) {
+      throw keyringFailure("read", err);
+    }
   }
   setPassword(password) {
     if (activeBackend() === "file") {
@@ -511,7 +537,11 @@ var Entry = class {
         return existed;
       });
     }
-    return this.delegate().deleteCredential();
+    try {
+      return this.delegate().deleteCredential();
+    } catch (err) {
+      throw keyringFailure("delete", err);
+    }
   }
   // @napi-rs/keyring's other delete alias, used by `qring doctor`.
   deletePassword() {
@@ -592,14 +622,14 @@ function getAuditDir() {
     }
     return process.env.QRING_AUDIT_DIR;
   }
-  const dir = join5(homedir3(), ".config", "q-ring");
+  const dir = configDir();
   if (!existsSync2(dir)) {
     mkdirSync3(dir, { recursive: true, mode: 448 });
   }
   return dir;
 }
 function getAuditPath() {
-  return join5(getAuditDir(), "audit.jsonl");
+  return join6(getAuditDir(), "audit.jsonl");
 }
 function getLastLineHash() {
   const path = getAuditPath();
@@ -849,8 +879,7 @@ function detectAnomalies(key) {
 
 // src/core/entanglement.ts
 import { existsSync as existsSync4, writeFileSync as writeFileSync3, mkdirSync as mkdirSync4 } from "fs";
-import { join as join6 } from "path";
-import { homedir as homedir4 } from "os";
+import { join as join7 } from "path";
 
 // src/utils/registry.ts
 import { existsSync as existsSync3, readFileSync as readFileSync6, renameSync } from "fs";
@@ -880,11 +909,11 @@ function loadJsonRegistry(path, empty) {
 // src/core/entanglement.ts
 var REGISTRY_VERSION = 1;
 function getRegistryPath() {
-  const dir = join6(homedir4(), ".config", "q-ring");
+  const dir = configDir();
   if (!existsSync4(dir)) {
     mkdirSync4(dir, { recursive: true, mode: 448 });
   }
-  return join6(dir, "entanglement.json");
+  return join7(dir, "entanglement.json");
 }
 function loadRegistry() {
   return loadJsonRegistry(getRegistryPath(), { pairs: [] });
@@ -926,8 +955,7 @@ function listEntanglements() {
 
 // src/core/hooks.ts
 import { existsSync as existsSync5, writeFileSync as writeFileSync4, mkdirSync as mkdirSync5 } from "fs";
-import { join as join7 } from "path";
-import { homedir as homedir5 } from "os";
+import { join as join8 } from "path";
 import { execFile, spawn } from "child_process";
 import { randomUUID } from "crypto";
 
@@ -1151,11 +1179,11 @@ function httpRequest(opts) {
 
 // src/core/hooks.ts
 function getRegistryPath2() {
-  const dir = join7(homedir5(), ".config", "q-ring");
+  const dir = configDir();
   if (!existsSync5(dir)) {
     mkdirSync5(dir, { recursive: true, mode: 448 });
   }
-  return join7(dir, "hooks.json");
+  return join8(dir, "hooks.json");
 }
 function loadRegistry2() {
   return loadJsonRegistry(getRegistryPath2(), { hooks: [] });
@@ -1409,12 +1437,11 @@ async function fireHooks(payload, tags) {
 
 // src/core/approval.ts
 import { existsSync as existsSync6, readFileSync as readFileSync7, writeFileSync as writeFileSync5, mkdirSync as mkdirSync6 } from "fs";
-import { join as join8 } from "path";
-import { homedir as homedir6 } from "os";
+import { join as join9 } from "path";
 import { createHmac as createHmac2, randomBytes as randomBytes3, timingSafeEqual } from "crypto";
 function getHmacSecret() {
-  const dir = join8(homedir6(), ".config", "q-ring");
-  const secretPath = join8(dir, ".approval-key");
+  const dir = configDir();
+  const secretPath = join9(dir, ".approval-key");
   if (!existsSync6(dir)) mkdirSync6(dir, { recursive: true, mode: 448 });
   if (existsSync6(secretPath)) {
     return readFileSync7(secretPath, "utf8").trim();
@@ -1450,11 +1477,11 @@ function verifyHmac(entry) {
   }
 }
 function getRegistryPath3() {
-  const dir = join8(homedir6(), ".config", "q-ring");
+  const dir = configDir();
   if (!existsSync6(dir)) {
     mkdirSync6(dir, { recursive: true, mode: 448 });
   }
-  return join8(dir, "approvals.json");
+  return join9(dir, "approvals.json");
 }
 function loadRegistry3() {
   return loadJsonRegistry(getRegistryPath3(), { approvals: [] });
@@ -1481,7 +1508,7 @@ function listApprovals() {
 
 // src/core/policy.ts
 import { statSync as statSync4 } from "fs";
-import { join as join9 } from "path";
+import { join as join10 } from "path";
 import { z as z2 } from "zod";
 var stringArray = z2.array(z2.string());
 var mcpPolicySchema = z2.object({
@@ -1540,7 +1567,7 @@ function resolvePolicyPath(projectPath) {
 }
 function configMtime(pp) {
   try {
-    return statSync4(join9(pp, ".q-ring.json")).mtimeMs;
+    return statSync4(join10(pp, ".q-ring.json")).mtimeMs;
   } catch {
     return 0;
   }
@@ -1563,7 +1590,7 @@ function loadPolicy(projectPath) {
   if (!parsed.success) {
     const issues = parsed.error.issues.map((i) => `policy${i.path.length ? "." + i.path.join(".") : ""}: ${i.message}`).join("; ");
     const error = new PolicyConfigError(
-      `Invalid policy in ${join9(pp, ".q-ring.json")} \u2014 refusing to run under an unparseable security policy (fail closed). Fix these and retry: ${issues}`
+      `Invalid policy in ${join10(pp, ".q-ring.json")} \u2014 refusing to run under an unparseable security policy (fail closed). Fix these and retry: ${issues}`
     );
     console.error(`q-ring: ${error.message}`);
     cachedPolicy = { path: pp, mtimeMs, error };
@@ -1801,15 +1828,14 @@ function notifyApprovalRequested(key, source) {
 
 // src/core/canary-webhooks.ts
 import { existsSync as existsSync7, writeFileSync as writeFileSync6, mkdirSync as mkdirSync7 } from "fs";
-import { join as join10 } from "path";
-import { homedir as homedir7 } from "os";
+import { join as join11 } from "path";
 import { randomUUID as randomUUID2 } from "crypto";
 function getRegistryPath4() {
   const override = process.env.QRING_CANARY_ALERTS_PATH;
   if (override) return override;
-  const dir = join10(homedir7(), ".config", "q-ring");
+  const dir = configDir();
   if (!existsSync7(dir)) mkdirSync7(dir, { recursive: true, mode: 448 });
-  return join10(dir, "canary-alerts.json");
+  return join11(dir, "canary-alerts.json");
 }
 function loadRegistry4() {
   return loadJsonRegistry(getRegistryPath4(), { channels: [] });
@@ -2109,6 +2135,10 @@ registry.register(httpProvider);
 function withJitEnvelopeLock(service, key, fn) {
   return withFileLock(`${service}\0${key}`, fn, { dir: "jit-locks" });
 }
+var MAX_ROTATE_EVERY_DAYS = 3650;
+function isValidRotateEveryDays(days) {
+  return Number.isInteger(days) && days >= 1 && days <= MAX_ROTATE_EVERY_DAYS;
+}
 function readEnvelope(service, key) {
   const entry = new Entry(service, key);
   const raw = entry.getPassword();
@@ -2271,6 +2301,14 @@ function setSecret(key, value, opts = {}) {
   let envelope;
   const rotFmt = opts.rotationFormat ?? existing?.meta.rotationFormat;
   const rotPfx = opts.rotationPrefix ?? existing?.meta.rotationPrefix;
+  const rotEvery = opts.rotateEveryDays ?? existing?.meta.rotateEveryDays;
+  if (rotEvery !== void 0 && !isValidRotateEveryDays(rotEvery)) {
+    throw new Error(
+      `rotateEveryDays must be a whole number of days between 1 and ${MAX_ROTATE_EVERY_DAYS}`
+    );
+  }
+  const valueChanged = !existing || (opts.states ? JSON.stringify(existing.states ?? null) !== JSON.stringify(opts.states) : existing.states !== void 0 || existing.value !== value);
+  const rotatedAt = valueChanged ? (/* @__PURE__ */ new Date()).toISOString() : existing?.meta.rotatedAt ?? existing?.meta.updatedAt ?? existing?.meta.createdAt;
   const prov = opts.provider ?? existing?.meta.provider;
   const reqApp = opts.requiresApproval ?? existing?.meta.requiresApproval;
   const jitProv = opts.jitProvider ?? existing?.meta.jitProvider;
@@ -2301,6 +2339,8 @@ function setSecret(key, value, opts = {}) {
       entangled: existing?.meta.entangled,
       rotationFormat: rotFmt,
       rotationPrefix: rotPfx,
+      rotatedAt,
+      rotateEveryDays: rotEvery,
       provider: prov,
       requiresApproval: reqApp,
       jitProvider: jitProv,
@@ -2316,6 +2356,8 @@ function setSecret(key, value, opts = {}) {
       entangled: existing?.meta.entangled,
       rotationFormat: rotFmt,
       rotationPrefix: rotPfx,
+      rotatedAt,
+      rotateEveryDays: rotEvery,
       provider: prov,
       requiresApproval: reqApp,
       jitProvider: jitProv,
@@ -2577,6 +2619,50 @@ function disentangleSecrets(sourceKey, sourceOpts, targetKey, targetOpts) {
   });
 }
 
+// src/core/rotation.ts
+var DAY_MS = 864e5;
+var DUE_SOON_FRACTION = 0.2;
+var DUE_SOON_MAX_DAYS = 7;
+function dueSoonWindowDays(rotateEveryDays) {
+  return Math.min(rotateEveryDays * DUE_SOON_FRACTION, DUE_SOON_MAX_DAYS);
+}
+function parseMs(iso) {
+  if (!iso) return null;
+  const ms = new Date(iso).getTime();
+  return Number.isFinite(ms) ? ms : null;
+}
+function rotationStatus(meta, now = Date.now()) {
+  const nowMs = typeof now === "number" ? now : now.getTime();
+  const lastRotatedAt = meta.rotatedAt ?? meta.updatedAt ?? meta.createdAt;
+  const lastMs = parseMs(lastRotatedAt) ?? nowMs;
+  const ageDays = Math.max(0, Math.floor((nowMs - lastMs) / DAY_MS));
+  const every = meta.rotateEveryDays;
+  if (!every || !Number.isFinite(every) || every <= 0) {
+    return {
+      lastRotatedAt,
+      ageDays,
+      rotateEveryDays: null,
+      dueAt: null,
+      daysUntilDue: null,
+      state: "unscheduled"
+    };
+  }
+  const dueMs = lastMs + every * DAY_MS;
+  const untilMs = dueMs - nowMs;
+  const daysUntilDue = Math.ceil(untilMs / DAY_MS);
+  let state = "ok";
+  if (untilMs <= 0) state = "overdue";
+  else if (untilMs <= dueSoonWindowDays(every) * DAY_MS) state = "due-soon";
+  return {
+    lastRotatedAt,
+    ageDays,
+    rotateEveryDays: every,
+    dueAt: new Date(dueMs).toISOString(),
+    daysUntilDue,
+    state
+  };
+}
+
 // src/core/tunnel.ts
 import { randomBytes as randomBytes4 } from "crypto";
 var tunnelStore = /* @__PURE__ */ new Map();
@@ -2651,8 +2737,8 @@ function tunnelList() {
 
 // src/core/memory.ts
 import { existsSync as existsSync8, readFileSync as readFileSync8, writeFileSync as writeFileSync7, mkdirSync as mkdirSync8, chmodSync as chmodSync3 } from "fs";
-import { join as join11 } from "path";
-import { homedir as homedir8, hostname, userInfo } from "os";
+import { join as join12 } from "path";
+import { hostname, userInfo } from "os";
 import {
   createCipheriv as createCipheriv2,
   createDecipheriv as createDecipheriv2,
@@ -2664,7 +2750,7 @@ var MEMORY_FILE = "agent-memory.enc";
 var KEYRING_SERVICE = "qring-memory-key";
 var KEYRING_ACCOUNT = "encryption-key";
 function getMemoryDir() {
-  const dir = join11(homedir8(), ".config", "q-ring");
+  const dir = configDir();
   if (!existsSync8(dir)) {
     mkdirSync8(dir, { recursive: true, mode: 448 });
   }
@@ -2678,7 +2764,7 @@ function writeMemoryFile(path, data) {
   }
 }
 function getMemoryPath() {
-  return join11(getMemoryDir(), MEMORY_FILE);
+  return join12(getMemoryDir(), MEMORY_FILE);
 }
 var PBKDF2_ITERATIONS2 = 21e4;
 var KEY_LENGTH2 = 32;
@@ -2900,6 +2986,7 @@ function summariseSession(session) {
 
 export {
   PACKAGE_VERSION,
+  Entry,
   checkDecay,
   readProjectConfig,
   collapseEnvironment,
@@ -2933,6 +3020,7 @@ export {
   exportSecrets,
   entangleSecrets,
   disentangleSecrets,
+  rotationStatus,
   tunnelCreate,
   tunnelRead,
   tunnelDestroy,
@@ -2945,4 +3033,4 @@ export {
   listAgentSessionsForAgents,
   summariseSession
 };
-//# sourceMappingURL=chunk-VMDD5QTJ.js.map
+//# sourceMappingURL=chunk-NTCTVLSK.js.map