@lifeaitools/clauth 1.16.9 → 1.18.0

package/cli/api.js

@@ -37,22 +37,109 @@ const VAULT_FETCH_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),
-    signal: AbortSignal.timeout(VAULT_FETCH_TIMEOUT_MS)
-  });
+  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;
 }
 
@@ -146,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
 };

package/cli/assets/codevelop/launcher-active.cmd.template

@@ -1,20 +1,20 @@
-@echo off
-setlocal
-set "CODEVELOP_SESSION=${SESSION_ID}"
-set "CODEVELOP_PEER=${PEER}"
-set "CODEVELOP_TARGET=${TARGET_PEER}"
-set "CODEVELOP_BASE_URL=${BASE_URL}"
-set "CODEVELOP_MANIFEST=${MANIFEST}"
-set "CODEVELOP_CONTEXT=${CONTEXT_FILE}"
-set "CELL_ROLE=codevelop-${PEER}"
-cd /d "${CWD}"
-if /i "%~1"=="--print-only" (
-  echo command: ${PRINT_COMMAND}
-  exit /b 0
-)
-echo Co-develop ${PEER} ready. Session ${SESSION_ID}. Listening for collaboration.
-echo Context: ${CONTEXT_FILE}
-node "${CLAUTH_CLI}" codevelop check-partner --repo "${REPO}" --peer ${PEER}
-${COMMAND}
-set EXITCODE=%ERRORLEVEL%
-endlocal & exit /b %EXITCODE%
+@echo off
+setlocal
+set "CODEVELOP_SESSION=${SESSION_ID}"
+set "CODEVELOP_PEER=${PEER}"
+set "CODEVELOP_TARGET=${TARGET_PEER}"
+set "CODEVELOP_BASE_URL=${BASE_URL}"
+set "CODEVELOP_MANIFEST=${MANIFEST}"
+set "CODEVELOP_CONTEXT=${CONTEXT_FILE}"
+set "CELL_ROLE=codevelop-${PEER}"
+cd /d "${CWD}"
+if /i "%~1"=="--print-only" (
+  echo command: ${PRINT_COMMAND}
+  exit /b 0
+)
+echo Co-develop ${PEER} ready. Session ${SESSION_ID}. Listening for collaboration.
+echo Context: ${CONTEXT_FILE}
+node "${CLAUTH_CLI}" codevelop check-partner --repo "${REPO}" --peer ${PEER}
+${COMMAND}
+set EXITCODE=%ERRORLEVEL%
+endlocal & exit /b %EXITCODE%

package/cli/assets/codevelop/launcher-static.cmd.template

@@ -1,7 +1,7 @@
-@echo off
-if not exist "${ACTIVE_LAUNCHER}" (
-  echo No active co-develop launcher has been written.
-  echo Run: clauth codevelop start --repo "${REPO}" --port ${PORT} --start-isolated-clauth
-  exit /b 1
-)
-call "${ACTIVE_LAUNCHER}" %*
+@echo off
+if not exist "${ACTIVE_LAUNCHER}" (
+  echo No active co-develop launcher has been written.
+  echo Run: clauth codevelop start --repo "${REPO}" --port ${PORT} --start-isolated-clauth
+  exit /b 1
+)
+call "${ACTIVE_LAUNCHER}" %*

package/cli/assets/codevelop/windows-terminal.profiles.json

@@ -1,48 +1,48 @@
-{
-  "profiles": [
-    {
-      "name": "Co Develop Claude",
-      "guid": "{a2f8548f-82e6-44b4-bdbb-d934e8881f01}",
-      "commandline": "cmd.exe /k \"${CLAUTH_APPDATA}\\codevelop-claude.cmd\"",
-      "startingDirectory": "${REPO}",
-      "environment": {
-        "CELL_ROLE": "codevelop-claude"
-      },
-      "icon": "🔴",
-      "tabColor": "#B91C1C",
-      "colorScheme": "Dimidium"
-    },
-    {
-      "name": "Co Develop Codex",
-      "guid": "{31a52b07-6efd-4b3d-96dd-ded73488140a}",
-      "commandline": "cmd.exe /k \"${CLAUTH_APPDATA}\\codevelop-codex.cmd\"",
-      "startingDirectory": "${REPO}",
-      "environment": {
-        "CELL_ROLE": "codevelop-codex"
-      },
-      "icon": "🧬",
-      "tabColor": "#0F766E",
-      "colorScheme": "Dimidium"
-    }
-  ],
-  "layout": {
-    "wtArgs": [
-      "-w",
-      "new",
-      "new-tab",
-      "--profile",
-      "Co Develop Claude",
-      "--title",
-      "Co Develop Claude",
-      ";",
-      "split-pane",
-      "-V",
-      "--size",
-      "0.50",
-      "--profile",
-      "Co Develop Codex",
-      "--title",
-      "Co Develop Codex"
-    ]
-  }
-}
+{
+  "profiles": [
+    {
+      "name": "Co Develop Claude",
+      "guid": "{a2f8548f-82e6-44b4-bdbb-d934e8881f01}",
+      "commandline": "cmd.exe /k \"${CLAUTH_APPDATA}\\codevelop-claude.cmd\"",
+      "startingDirectory": "${REPO}",
+      "environment": {
+        "CELL_ROLE": "codevelop-claude"
+      },
+      "icon": "🔴",
+      "tabColor": "#B91C1C",
+      "colorScheme": "Dimidium"
+    },
+    {
+      "name": "Co Develop Codex",
+      "guid": "{31a52b07-6efd-4b3d-96dd-ded73488140a}",
+      "commandline": "cmd.exe /k \"${CLAUTH_APPDATA}\\codevelop-codex.cmd\"",
+      "startingDirectory": "${REPO}",
+      "environment": {
+        "CELL_ROLE": "codevelop-codex"
+      },
+      "icon": "🧬",
+      "tabColor": "#0F766E",
+      "colorScheme": "Dimidium"
+    }
+  ],
+  "layout": {
+    "wtArgs": [
+      "-w",
+      "new",
+      "new-tab",
+      "--profile",
+      "Co Develop Claude",
+      "--title",
+      "Co Develop Claude",
+      ";",
+      "split-pane",
+      "-V",
+      "--size",
+      "0.50",
+      "--profile",
+      "Co Develop Codex",
+      "--title",
+      "Co Develop Codex"
+    ]
+  }
+}

package/cli/assets/watchdog.ps1

@@ -1,42 +1,42 @@
-# clauth-watchdog.ps1
-# Monitors clauth daemon on port 52437. Restarts it if not responding.
-# Installed by: npm install -g @lifeaitools/clauth
-# Managed by:   clauth watchdog [install|uninstall|status]
-
-$clauth   = "$env:APPDATA\npm\clauth.cmd"
-$logFile  = "$env:APPDATA\clauth\watchdog.log"
-$pingUrl  = "http://127.0.0.1:52437/ping"
-$interval = 15
-
-function Write-Log($msg) {
-    $ts   = (Get-Date).ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ssZ")
-    $line = "[$ts] $msg"
-    Add-Content -Path $logFile -Value $line -ErrorAction SilentlyContinue
-}
-
-Write-Log "Watchdog started (PID $PID, clauth=$clauth)"
-
-while ($true) {
-    $alive = $false
-    try {
-        $r = Invoke-WebRequest -Uri $pingUrl -TimeoutSec 3 -UseBasicParsing -ErrorAction Stop
-        if ($r.StatusCode -eq 200) { $alive = $true }
-    } catch { }
-
-    if (-not $alive) {
-        Write-Log "Daemon not responding — restarting..."
-        Start-Process -FilePath "cmd.exe" `
-            -ArgumentList "/c `"$clauth`" serve start" `
-            -WindowStyle Hidden
-        Start-Sleep -Seconds 5
-        try {
-            $r = Invoke-WebRequest -Uri $pingUrl -TimeoutSec 5 -UseBasicParsing -ErrorAction Stop
-            if ($r.StatusCode -eq 200) { Write-Log "Daemon restarted OK." }
-            else { Write-Log "WARNING: Daemon still not responding." }
-        } catch {
-            Write-Log "WARNING: Daemon still not responding after restart."
-        }
-    }
-
-    Start-Sleep -Seconds $interval
-}
+# clauth-watchdog.ps1
+# Monitors clauth daemon on port 52437. Restarts it if not responding.
+# Installed by: npm install -g @lifeaitools/clauth
+# Managed by:   clauth watchdog [install|uninstall|status]
+
+$clauth   = "$env:APPDATA\npm\clauth.cmd"
+$logFile  = "$env:APPDATA\clauth\watchdog.log"
+$pingUrl  = "http://127.0.0.1:52437/ping"
+$interval = 15
+
+function Write-Log($msg) {
+    $ts   = (Get-Date).ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ssZ")
+    $line = "[$ts] $msg"
+    Add-Content -Path $logFile -Value $line -ErrorAction SilentlyContinue
+}
+
+Write-Log "Watchdog started (PID $PID, clauth=$clauth)"
+
+while ($true) {
+    $alive = $false
+    try {
+        $r = Invoke-WebRequest -Uri $pingUrl -TimeoutSec 3 -UseBasicParsing -ErrorAction Stop
+        if ($r.StatusCode -eq 200) { $alive = $true }
+    } catch { }
+
+    if (-not $alive) {
+        Write-Log "Daemon not responding — restarting..."
+        Start-Process -FilePath "cmd.exe" `
+            -ArgumentList "/c `"$clauth`" serve start" `
+            -WindowStyle Hidden
+        Start-Sleep -Seconds 5
+        try {
+            $r = Invoke-WebRequest -Uri $pingUrl -TimeoutSec 5 -UseBasicParsing -ErrorAction Stop
+            if ($r.StatusCode -eq 200) { Write-Log "Daemon restarted OK." }
+            else { Write-Log "WARNING: Daemon still not responding." }
+        } catch {
+            Write-Log "WARNING: Daemon still not responding after restart."
+        }
+    }
+
+    Start-Sleep -Seconds $interval
+}