@lifeaitools/clauth 1.30.13 → 1.30.14

package/.clauth-skill/SKILL.md

@@ -11,23 +11,47 @@ Hardware-bound credential vault for the LIFEAI stack. Your machine is the second
 
 ## How Claude Interfaces with clauth
 
-> **CRITICAL:** Never pipe input to clauth or use interactive prompts. The CLI uses `inquirer` which produces ANSI garbage when stdin is piped. Always use one of the two methods below.
+> **CRITICAL:** Agents should use the local daemon for credential discovery and
+> exact secret retrieval. Do not ask the user for the vault password just to get
+> a key, do not use interactive prompts, and do not walk every service.
 
-### Method 1 — CLI with `--pw` flag (simplest)
+### Method 1 — Local daemon (preferred for agents)
 
-All clauth commands accept `-p` / `--pw <password>` to skip the interactive password prompt:
+Discover services without reading secrets:
+
+```bash
+curl -s http://127.0.0.1:52437/ping
+curl -s http://127.0.0.1:52437/knowledge
+curl -s http://127.0.0.1:52437/list-services
+```
+
+Retrieve exactly one credential only when the next command needs it:
+
+```bash
+curl -s http://127.0.0.1:52437/v/<service>
+```
+
+`/knowledge` is safe to cache for a session: it returns service metadata and
+`has_key`, but no raw secrets and no Vault secret names. `/status` uses the same
+short metadata cache and can be forced with `?refresh=1`.
+
+### Method 2 — CLI with `--pw` flag (admin/setup only)
+
+All clauth commands accept `-p` / `--pw <password>` to skip the interactive
+password prompt. Use this for local admin/setup tasks, not routine agent secret
+retrieval:
 
 ```bash
 clauth status -p "YourPassword"
-clauth get github -p "YourPassword"
 clauth test -p "YourPassword"
 clauth enable github -p "YourPassword"
 clauth write key github -p "YourPassword"   # still prompts for the key value
 ```
 
-### Method 2 — Direct API calls (full control, no CLI needed)
+### Method 3 — Direct API calls (implementation/debugging only)
 
-Call the auth-vault Edge Function directly. This is the most reliable method for Claude.
+Call the auth-vault Edge Function directly only when debugging clauth internals.
+Normal agents should not bypass the daemon metadata cache.
 
 **Base URL:** `https://<project-ref>.supabase.co/functions/v1/auth-vault`
 **Auth header:** `Authorization: Bearer <supabase-anon-key>`
@@ -75,10 +99,10 @@ All auth routes require: `machine_hash`, `token`, `timestamp`, `password`.
 
 ### Password Handling
 
-- Ask the user for their clauth password **once per session**
-- Store it in working memory for the duration of the conversation
+- Do not ask the user for their clauth password for routine credential lookup
+- Use the unlocked local daemon whenever possible
 - Never log or echo the password
-- If the user says "use clauth" or "get my github key", ask for the password if you don't have it yet
+- If the daemon is locked, ask the user to unlock `http://127.0.0.1:52437`
 
 ---
 
@@ -144,7 +168,9 @@ clauth setup [--admin-token T] [-p P]  Register this machine
 clauth status [-p P]                   All services + state
 clauth test [-p P]                     Verify HMAC connection
 clauth list [-p P]                     Service names
-clauth search <query> [-p P]           Search names, metadata, and redacted server addresses
+clauth search <query> [-p P]           Search names and metadata
+clauth search <query> --addresses [-p P]
+                                      Also search redacted address hints (may read multiple secrets)
 
 clauth write key <service> [-p P]      Store a credential
 clauth write pw [-p P]                 Change password
@@ -175,32 +201,64 @@ Service type `fileserver` — mount configuration for fs tools (UI-only config).
 
 ---
 
-## MCP Server (v1.5.38+)
+## Daemon Metadata Cache
+
+When discovering service names, do not retrieve secrets. Use the daemon metadata
+cache:
+
+```bash
+curl -s http://127.0.0.1:52437/knowledge
+curl -s http://127.0.0.1:52437/list-services
+```
 
-clauth runs as an MCP server with 3 namespaces and 27 tools:
+`/knowledge` is agent-safe: it returns service metadata and `has_key`, but no
+raw secrets and no Vault secret names. Fetch `GET /v/<service>` only for the one
+exact credential needed by the next command. Never walk every service and never
+bulk-fetch all secrets.
+
+## MCP Server (v1.16.9+)
+
+clauth runs as an MCP server with five namespaced paths and safe
+credential-discovery tools:
 
 | Path | Namespace | Tools |
 |------|-----------|-------|
-| `/clauth` | `clauth_*` | 13 credential vault tools |
+| `/clauth` | `clauth_*` + runtime helpers | 23 default live tools, including `clauth_knowledge` |
 | `/gws` | `gws_*` | 6 Google Workspace tools |
-| `/fs` | `fs_*` | 8 filesystem tools (read, write, grep, glob, list, delete, mkdir, mounts) |
-| `/mcp` | all | 27 tools combined |
+| `/fs` | `fs_*` | 20 filesystem and git-safe file tools |
+| `/chitchat` | `chitchat_*` | 7 collaboration relay tools |
+| `/codevelop` | `codevelop_*` | 7 peer development tools |
+| `/mcp` | all | 63 tools combined |
+
+The default live `/clauth` surface includes credential tools plus
+`call_agent`, `monkey_dispatch`, `handoff_start`, `terminal_*`, and `channel_*`.
+Admin write tools are gated by write-mode.
 
 ### claude.ai Connector URLs (noauth mode)
 - `https://clauth.regendevcorp.com/clauth` — credential tools
 - `https://clauth.regendevcorp.com/gws` — Google Workspace
+- `https://clauth.regendevcorp.com/chitchat` — collaboration relay tools
+- `https://clauth.regendevcorp.com/codevelop` — peer development tools
 - `https://fs.regendevcorp.com/fs` — filesystem tools
 
 Noauth mode: fresh domains that return 404 on OAuth endpoints. claude.ai connects directly (Anthropic OAuth proxy bug workaround).
 
+Use `clauth_knowledge` or `clauth_status` for discovery. Use `clauth_get` only
+for one exact secret. `clauth_search` is metadata-only by default; pass
+`addresses: true` only when redacted address hints are intentionally needed.
+`clauth_inject` is guarded against accidental bulk vault sweeps.
+
 ### FS Tools
-`fs_read` `fs_write` `fs_list` `fs_grep` `fs_glob` `fs_delete` `fs_mkdir` `fs_mounts`
+`fs_read` `fs_write` `fs_stat` `fs_append` `fs_write_chunk` `fs_ingest_url`
+`fs_import_git_files` `fs_list` `fs_grep` `fs_glob` `fs_delete` `fs_mkdir`
+`fs_edit` `fs_move` `fs_copy` `fs_mounts` `fs_repo_status` `fs_use_branch`
+`fs_commit` `fs_diff`
 
 Path-jail security: all paths resolved against mount root. Permission flags (r/w/d) per mount. Uses `@vscode/ripgrep` for grep, `fast-glob` for glob.
 
 ### Testing
 ```bash
-node test-tools.mjs    # 25 tool execution tests across all 3 namespaces
+node test-tools.mjs    # MCP tool execution smoke tests
 ```
 
 ---

package/README.md

@@ -92,7 +92,9 @@ clauth install              Provision Supabase + install Claude skill
 clauth setup                Register this machine with the vault
 clauth enroll               Create one-time code to add another computer
 clauth status               All services + state
-clauth search <query>       Find services by name, project, description, or redacted address
+clauth search <query>       Find services by name, project, description, or type
+clauth search <query> --addresses
+                            Also search redacted address hints (may read multiple secrets)
 clauth test                 Verify connection
 
 clauth write key <service>  Store a credential
@@ -136,7 +138,7 @@ Nothing stored locally. Password never persisted. Machine hash is one-way only.
 clauth runs as an HTTP daemon on `http://127.0.0.1:52437`. The daemon provides:
 
 - **Web UI** — unlock vault, manage services, configure mounts
-- **REST API** — `GET /get/<service>`, `GET /ping`, `POST /restart`, `GET /shutdown`
+- **REST API** — `GET /knowledge`, `GET /status`, `GET /v/<service>`, `GET /ping`, `POST /restart`, `GET /shutdown`
 - **MCP server** — Model Context Protocol for Claude Code and claude.ai
 - **Cloudflare Tunnel** — exposes MCP endpoints publicly for claude.ai connectors
 
@@ -144,32 +146,88 @@ Start: `clauth serve start` (starts locked, auto-opens browser for unlock).
 
 Full daemon operations reference: see `regen-root/.claude/rules/clauth.md`.
 
+### Safe Metadata Cache
+
+Agents and scripts must discover services through metadata endpoints, not by
+walking every secret endpoint. The daemon caches service metadata for 30 seconds:
+
+```bash
+curl -s http://127.0.0.1:52437/knowledge      # sanitized, agent-safe metadata
+curl -s http://127.0.0.1:52437/list-services  # names only
+curl -s http://127.0.0.1:52437/status         # full daemon metadata, cached
+```
+
+`/knowledge` returns service names, labels, key types, enabled state, project,
+description, timestamps, and `has_key`. It never returns raw secrets or Vault
+secret names. Use `GET /v/<service>` only for the one exact secret needed by the
+next command. Do not bulk-fetch every service.
+
 ---
 
-## MCP Server — 3 Namespaces, 32 Tools
+## MCP Server — 5 Namespaces, 63 Tools
 
 clauth is the single MCP interface for all local tools. One process, namespaced paths:
 
 | Path | Namespace | Tools | Description |
 |------|-----------|-------|-------------|
-| `/clauth` | `clauth_*` | 13 | Credential vault operations |
+| `/clauth` | `clauth_*` + runtime helpers | 23 | Credential vault operations, safe metadata cache, and agent runtime helpers |
 | `/gws` | `gws_*` | 6 | Google Workspace (Gmail, Calendar, Drive) |
-| `/fs` | `fs_*` | 13 | Filesystem (read, write, append, chunked write, URL ingest, Git import, stat, grep, glob, delete, mkdir, mounts) |
-| `/mcp` | all | 32 | All namespaces combined (Claude Code) |
+| `/fs` | `fs_*` | 20 | Filesystem plus guarded git/local-branch tools |
+| `/chitchat` | `chitchat_*` | 7 | Collaboration relay sessions |
+| `/codevelop` | `codevelop_*` | 7 | Peer development sessions |
+| `/mcp` | all | 63 | All namespaces combined (Claude Code) |
+
+The default live `/clauth` surface includes 13 credential tools plus
+`call_agent`, `monkey_dispatch`, `handoff_start`, `terminal_*`, and `channel_*`
+runtime helpers. Admin write tools such as enable/disable/project/token actions
+are gated by write-mode.
+
+### TinTin Agent Setup
+
+clauth owns the local TinTin settings and isolated agent setup contract used by
+app sidebars and the standalone TinTin console.
+
+| Method | Route | Purpose |
+| --- | --- | --- |
+| `GET` | `/tintin/settings` | Read persisted TinTin app/agent/sidebar/dispatch/co-develop settings. |
+| `PUT` | `/tintin/settings` | Save TinTin app/agent/sidebar/dispatch/co-develop settings. |
+| `GET` | `/tintin/settings/ui` | Browser settings page for operators, with sections for Agent Setup, Agent Defaults, Sidebar Apps, Blackboard Dispatch, Co-develop Relay, and stored agent sessions. |
+| `POST` | `/tintin/agent-sessions` | Create or reuse an isolated agent cwd, normally a git worktree. |
+
+The agent-session response includes the requested agent/runtime/model, repo
+root, isolated `cwd`, worktree path, branch, launch mode, and launch command.
+This route prepares the proper Codex/Claude isolation path; separate supervisor
+code is still responsible for long-running process parking and wake/resume.
+
+### clauth MCP Usage
+
+Use `clauth_knowledge` or `clauth_status` for discovery. They use cached
+metadata and never retrieve raw secrets. `clauth_search` is metadata-only by
+default; pass `addresses: true` only when you intentionally need redacted address
+hints from connstrings/fileserver/oauth secrets. `clauth_get` is for one exact
+secret. `clauth_inject` refuses more than five services unless `allow_many: true`
+is explicitly supplied, to prevent accidental rate-limit lockouts from bulk
+secret sweeps.
 
 ### FS Tools
 
-13 filesystem tools with path-jail security:
-- `fs_read`, `fs_write`, `fs_stat`, `fs_append`, `fs_write_chunk`, `fs_ingest_url`, `fs_import_git_files`, `fs_list`, `fs_grep`, `fs_glob`, `fs_delete`, `fs_mkdir`, `fs_mounts`
+20 filesystem tools with path-jail security:
+- `fs_read`, `fs_write`, `fs_stat`, `fs_append`, `fs_write_chunk`, `fs_ingest_url`, `fs_import_git_files`, `fs_list`, `fs_grep`, `fs_glob`, `fs_delete`, `fs_mkdir`, `fs_edit`, `fs_move`, `fs_copy`, `fs_mounts`, `fs_repo_status`, `fs_use_branch`, `fs_commit`, `fs_diff`
 - Uses `node:fs/promises` (async), `@vscode/ripgrep` (shipped binary), `fast-glob`
 - Permission flags per mount: `r` (read), `w` (write), `d` (delete)
 - Mount config stored as "fileserver" service type in vault — only configurable through web UI
 - Large writes should use `fs_write_chunk`; cloud-to-local transfer should use `fs_ingest_url`; guarded appends should pass `expected_sha256` from `fs_stat`
 - Durable new files authored by Claude.ai in GitHub should use `fs_import_git_files` so the local dirty monorepo fetches and restores only named paths without `git pull`
 
+### Collaboration Tools
+
+Chitchat tools: `chitchat_start`, `chitchat_list`, `chitchat_send`, `chitchat_recv`, `chitchat_reply`, `chitchat_poll`, `chitchat_stop`
+
+Codevelop tools: `codevelop_start`, `codevelop_join`, `codevelop_send`, `codevelop_poll`, `codevelop_status`, `codevelop_stream`, `codevelop_stop`
+
 ### GWS Tools
 
-6 Google Workspace tools: `gws_gmail_list`, `gws_gmail_read`, `gws_gmail_send`, `gws_gmail_draft`, `gws_calendar_list`, `gws_calendar_create`
+6 Google Workspace tools: `gws_run`, `gws_gmail_list`, `gws_gmail_read`, `gws_gmail_send`, `gws_calendar_list`, `gws_drive_list`
 - Calls `gws` CLI via `execSync` with `shell: 'bash'` (fixes Windows cmd.exe JSON quoting)
 
 ---
@@ -196,6 +254,8 @@ Full OAuth 2.1 protocol implementation is present for future use when Anthropic
 |-----------|-----|
 | clauth | `https://clauth.regendevcorp.com/clauth` |
 | gws | `https://clauth.regendevcorp.com/gws` |
+| chitchat | `https://clauth.regendevcorp.com/chitchat` |
+| codevelop | `https://clauth.regendevcorp.com/codevelop` |
 | fs | `https://fs.regendevcorp.com/fs` |
 
 ---
@@ -210,7 +270,7 @@ Full OAuth 2.1 protocol implementation is present for future use when Anthropic
 ## Testing
 
 ```bash
-node test-tools.mjs    # 25 tool execution tests across all 3 namespaces
+node test-tools.mjs    # MCP tool execution smoke tests
 ```
 
 Tests actual MCP tool calls (not just OAuth + listing).

package/cli/api.classify.test.js

@@ -0,0 +1,75 @@
+// cli/api.classify.test.js
+// Regression tests for backend/external-resource error classification.
+//
+// WHY THIS EXISTS: on 2026-06-19 a saturated Postgres database made every
+// auth-vault verify call time out. clauth counted each timeout as an
+// authentication failure ([AUTH FAIL n/10]), hit the strike ceiling, and
+// hard-locked the vault — turning a transient DB blip into a full lockout that
+// blocked Claude/Codex from starting. A database timeout, a 5xx, a network
+// drop, or a rate-limit is NOT a wrong password and must never take a strike.
+// These tests pin that classification so the regression can't return.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  VaultBackendError,
+  classifyBackendError,
+  classifyServerReason,
+} from "./api.js";
+
+test("VaultBackendError marks failures as non-strike + retriable", () => {
+  const e = new VaultBackendError("timeout", "no response", { status: 504, detail: "abort" });
+  assert.equal(e.kind, "timeout");
+  assert.equal(e.isBackend, true);
+  assert.equal(e.retriable, true);
+  assert.equal(e.status, 504);
+  assert.ok(e instanceof Error);
+});
+
+test("classifyBackendError: AbortSignal.timeout shapes => 'timeout'", () => {
+  // This is the exact error that slipped through the old substring check.
+  assert.equal(classifyBackendError({ name: "TimeoutError", message: "The operation was aborted due to timeout" }), "timeout");
+  assert.equal(classifyBackendError({ name: "AbortError", message: "This operation was aborted" }), "timeout");
+  assert.equal(classifyBackendError(new Error("request timed out")), "timeout");
+});
+
+test("classifyBackendError: network/transport shapes => 'network'", () => {
+  assert.equal(classifyBackendError(new Error("fetch failed")), "network");
+  assert.equal(classifyBackendError(new Error("connect ECONNREFUSED 127.0.0.1:443")), "network");
+  assert.equal(classifyBackendError(new Error("getaddrinfo ENOTFOUND db.supabase.co")), "network");
+  assert.equal(classifyBackendError(new Error("read ECONNRESET")), "network");
+});
+
+test("classifyBackendError: a typed VaultBackendError passes its kind through", () => {
+  assert.equal(classifyBackendError(new VaultBackendError("rate_limited", "slow down")), "rate_limited");
+  assert.equal(classifyBackendError(new VaultBackendError("db_error", "pool exhausted")), "db_error");
+});
+
+test("classifyBackendError: a genuine credential error is NOT a backend error", () => {
+  assert.equal(classifyBackendError(new Error("Wrong password")), null);
+  assert.equal(classifyBackendError(new Error("invalid_token")), null);
+  assert.equal(classifyBackendError(null), null);
+  assert.equal(classifyBackendError(undefined), null);
+});
+
+test("classifyServerReason: rate-limit reasons => 'rate_limited'", () => {
+  assert.equal(classifyServerReason("rate_limited"), "rate_limited");
+  assert.equal(classifyServerReason("Rate limit: 38/30 per 60s"), "rate_limited");
+});
+
+test("classifyServerReason: database/backend reasons => 'db_error'", () => {
+  assert.equal(classifyServerReason("canceling statement due to statement timeout"), "db_error");
+  assert.equal(classifyServerReason("database connection pool exhausted"), "db_error");
+  assert.equal(classifyServerReason("internal server error"), "db_error");
+  assert.equal(classifyServerReason("service unavailable"), "db_error");
+});
+
+test("classifyServerReason: genuine auth verdicts are NOT backend errors (they strike)", () => {
+  assert.equal(classifyServerReason("invalid_token (3/5)"), null);
+  assert.equal(classifyServerReason("machine_locked"), null);
+  assert.equal(classifyServerReason("machine_disabled"), null);
+  assert.equal(classifyServerReason("machine_not_found"), null);
+  assert.equal(classifyServerReason("wrong_password"), null);
+  assert.equal(classifyServerReason(null), null);
+  assert.equal(classifyServerReason(""), null);
+});

package/cli/api.js

@@ -27,21 +27,119 @@ export function getAnonKey() {
 // ============================================================
 // Core POST helper
 // ============================================================
+// Bound every vault round-trip with a wall-clock timeout. Without this, a TCP
+// stall (DNS black-hole, half-open socket — NOT a clean 4xx) hangs the caller
+// forever. Callers that treat persistence as best-effort (e.g. the call_agent
+// scratchpad mirror) rely on this resolving to an error rather than blocking.
+// Override via CLAUTH_VAULT_TIMEOUT_MS; default 8s.
+const VAULT_FETCH_TIMEOUT_MS = (() => {
+  const n = Number(process.env.CLAUTH_VAULT_TIMEOUT_MS);
+  return Number.isFinite(n) && n > 0 ? n : 8000;
+})();
+
+// ============================================================
+// Backend / external-resource error model
+// ============================================================
+// A VaultBackendError means the vault backend (the auth-vault Edge Function or
+// the Postgres database behind it) never rendered an auth verdict — the request
+// timed out, the network failed, the function 5xx'd, the DB was unreachable, or
+// we were rate-limited. These are TRANSIENT and must NEVER be counted as an
+// authentication failure (a wrong password). Treating a database timeout as a
+// bad password is the bug that turned a DB blip into a permanent vault lockout.
+export class VaultBackendError extends Error {
+  constructor(kind, message, { status = null, detail = null, cause = null } = {}) {
+    super(message);
+    this.name = "VaultBackendError";
+    this.kind = kind;              // timeout | network | server_error | rate_limited | db_error | unknown
+    this.isBackend = true;         // marker for callers: do not strike
+    this.retriable = true;         // the verdict was never rendered — safe to retry
+    this.status = status;          // HTTP status if the server responded
+    this.detail = detail;          // human-readable backend detail
+    if (cause) this.cause = cause;
+  }
+}
+
+// Server `reason` strings that are genuine AUTH VERDICTS (the backend evaluated
+// the credential and answered). These DO count — they are not backend errors.
+const AUTH_VERDICT_REASONS = [
+  "invalid_token", "wrong_password", "invalid_password",
+  "machine_locked", "machine_disabled", "machine_not_found",
+];
+
+// Classify a server-supplied `reason` string. Returns a VaultBackendError kind
+// when the reason describes a backend/transient condition, or null when the
+// reason is a real auth verdict (or unknown — caller decides).
+export function classifyServerReason(reason) {
+  if (!reason || typeof reason !== "string") return null;
+  const r = reason.toLowerCase();
+  if (AUTH_VERDICT_REASONS.some((v) => r.includes(v))) return null; // genuine verdict
+  if (/rate[_\s-]?limit/.test(r)) return "rate_limited";
+  if (/(database|\bdb\b|postgres|connection|pool|statement timeout|unavailable|internal|timeout|5\d\d)/.test(r)) return "db_error";
+  return null;
+}
+
+// Classify a thrown error (transport/timeout/network/typed). Returns a kind
+// string when it is a backend/transient failure, or null when it is not.
+export function classifyBackendError(err) {
+  if (!err) return null;
+  if (err instanceof VaultBackendError) return err.kind;
+  const name = err.name || "";
+  const msg = (err.message || "").toString();
+  if (name === "TimeoutError" || name === "AbortError" || /\babort(ed)?\b|\btim(e|ed)?\s*out\b|timeout/i.test(msg)) return "timeout";
+  if (/fetch failed|ECONNREFUSED|ENOTFOUND|ETIMEDOUT|EAI_AGAIN|ECONNRESET|EPIPE|network|socket hang/i.test(msg)) return "network";
+  return null;
+}
+
 async function post(route, body) {
   const url = `${getBaseUrl()}/${route}`;
   const anonKey = getAnonKey();
 
-  const res = await fetch(url, {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      "Authorization": `Bearer ${anonKey}`
-    },
-    body: JSON.stringify(body)
-  });
+  let res;
+  try {
+    res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${anonKey}`
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(VAULT_FETCH_TIMEOUT_MS)
+    });
+  } catch (err) {
+    // Transport-level failure — the backend never answered. Surface a typed,
+    // non-strike error so callers report "backend unreachable", not "bad password".
+    const kind = classifyBackendError(err) || "network";
+    const why = kind === "timeout"
+      ? `vault backend did not respond within ${VAULT_FETCH_TIMEOUT_MS}ms`
+      : `cannot reach vault backend (${err.message || "network error"})`;
+    throw new VaultBackendError(kind, why, { detail: err.message || String(err), cause: err });
+  }
+
+  let data;
+  try {
+    data = await res.json();
+  } catch (err) {
+    // 2xx/5xx with a non-JSON or empty body — the function errored without a
+    // structured verdict. Transient backend condition, not an auth failure.
+    throw new VaultBackendError("server_error", `vault backend returned an unreadable response (HTTP ${res.status})`, { status: res.status, detail: err.message });
+  }
+
+  // HTTP 5xx (or any non-ok with no structured error) = backend problem, never a verdict.
+  if (res.status >= 500 || (!res.ok && !data.error)) {
+    const reasonKind = classifyServerReason(data.reason || data.error) || "server_error";
+    throw new VaultBackendError(reasonKind, `vault backend error (HTTP ${res.status})`, { status: res.status, detail: data.error || data.reason || `HTTP ${res.status}` });
+  }
+
+  // 4xx WITH a structured error: could be a real verdict (invalid_token) or a
+  // transient backend signal surfaced as 4xx (rate_limited). Promote the latter
+  // to a typed backend error; leave genuine verdicts in `data` for the caller.
+  if (data.error) {
+    const reasonKind = classifyServerReason(data.reason || data.error);
+    if (reasonKind) {
+      throw new VaultBackendError(reasonKind, `vault backend ${reasonKind.replace("_", " ")}`, { status: res.status, detail: data.error || data.reason });
+    }
+  }
 
-  const data = await res.json();
-  if (!res.ok && !data.error) throw new Error(`HTTP ${res.status}`);
   return data;
 }
 
@@ -135,5 +233,6 @@ export async function redeemEnrollment(machineHash, seedHash, label, enrollmentC
 
 export default {
   retrieve, write, enable, addService, updateService, removeService, revoke,
-  status, test, createEnrollment, registerMachine, redeemEnrollment, getBaseUrl, getAnonKey
+  status, test, createEnrollment, registerMachine, redeemEnrollment, getBaseUrl, getAnonKey,
+  VaultBackendError, classifyBackendError, classifyServerReason
 };