@cachly-dev/mcp-server 0.10.70 → 0.10.71

package/dist/src/auth.d.ts

@@ -1,3 +1,29 @@
 export declare function jwtExpiryMs(token: string): number | null;
+/** Long-lived API keys cannot expire silently; raw access tokens can. */
+export declare const API_KEY_PREFIX = "cky_";
+export type AuthState = 'healthy' | 'no_jwt' | 'expired' | 'near_expiry' | 'long_lived';
+export interface AuthDiagnosis {
+    state: AuthState;
+    /** Safe to make API calls right now? (healthy, near_expiry and long_lived all are.) */
+    usable: boolean;
+    /** ms until expiry, or null for tokens with no exp claim (long-lived keys). */
+    expiresInMs: number | null;
+    /** Human-facing message with the single fix, when action is needed. */
+    message: string;
+}
+/** A long-lived API key (cky_live_… / cky_…) has no exp and never expires silently. */
+export declare function isLongLivedApiKey(token: string): boolean;
+export declare const NEAR_EXPIRY_MS: number;
+/**
+ * Diagnose the current credential without making any network call. Pure +
+ * deterministic (pass `now` in tests).
+ */
+export declare function diagnoseAuth(jwt: string, now?: number): AuthDiagnosis;
+export type AuthHealAction = 'none' | 'refresh' | 'reauth';
+/**
+ * Decide what self-healing step (if any) to take for a diagnosis. Pure so the
+ * decision is unit-testable independently of the network-bound executor.
+ */
+export declare function planAuthHeal(d: AuthDiagnosis): AuthHealAction;
 export declare function checkJwt(jwt: string): void;
 export declare function handleApiError(status: number, detail: string): never;

package/dist/src/auth.js

@@ -11,18 +11,90 @@ export function jwtExpiryMs(token) {
         return null;
     }
 }
-export function checkJwt(jwt) {
+// ── Self-healing auth ─────────────────────────────────────────────────────────
+// The silent-failure mode we guard against: a token that is missing, expired, or
+// about to expire degrades the brain into "0 recalls" without the user ever being
+// told why. Instead of failing silently (or only at the moment a network call
+// finally 401s), we diagnose the credential up front and either heal it
+// automatically (mint a fresh long-lived key while the current one is still valid)
+// or surface a single, actionable instruction.
+/** Long-lived API keys cannot expire silently; raw access tokens can. */
+export const API_KEY_PREFIX = 'cky_';
+/** A long-lived API key (cky_live_… / cky_…) has no exp and never expires silently. */
+export function isLongLivedApiKey(token) {
+    return token.startsWith(API_KEY_PREFIX);
+}
+// Refresh a token this close to expiry (or already expired) the moment we touch it.
+export const NEAR_EXPIRY_MS = 10 * 60 * 1000; // 10 minutes
+const SETUP_URL = 'https://cachly.dev/setup-ai';
+/**
+ * Diagnose the current credential without making any network call. Pure +
+ * deterministic (pass `now` in tests).
+ */
+export function diagnoseAuth(jwt, now = Date.now()) {
     if (!jwt) {
-        throw new McpError(ErrorCode.InvalidRequest, 'CACHLY_JWT env var not set.\n\nGet your token at https://cachly.dev/setup-ai and add it to your MCP config:\n  CACHLY_JWT=<your-token>');
+        return {
+            state: 'no_jwt',
+            usable: false,
+            expiresInMs: null,
+            message: `No CACHLY_JWT set — the brain can't persist or recall anything (you'd silently get 0 recalls).\n\nGet your token at ${SETUP_URL} and add it to your MCP config, or just call any tool to start the one-time device-flow sign-in.`,
+        };
     }
     const expMs = jwtExpiryMs(jwt);
-    if (expMs !== null && expMs < Date.now()) {
-        throw new McpError(ErrorCode.InvalidRequest, `CACHLY_JWT expired at ${new Date(expMs).toISOString()}.\n\nGet a fresh token at https://cachly.dev/setup-ai and update CACHLY_JWT in your MCP config.`);
+    // No exp claim → long-lived API key. These are the healthy steady state.
+    if (expMs === null) {
+        return {
+            state: isLongLivedApiKey(jwt) ? 'long_lived' : 'healthy',
+            usable: true,
+            expiresInMs: null,
+            message: '',
+        };
+    }
+    const remaining = expMs - now;
+    if (remaining <= 0) {
+        return {
+            state: 'expired',
+            usable: false,
+            expiresInMs: remaining,
+            message: `CACHLY_JWT expired at ${new Date(expMs).toISOString()} — recalls will silently return nothing until you re-authenticate.\n\nGet a fresh token at ${SETUP_URL}, or call any tool to re-run the device-flow sign-in.`,
+        };
+    }
+    if (remaining <= NEAR_EXPIRY_MS) {
+        const mins = Math.max(1, Math.round(remaining / 60_000));
+        return {
+            state: 'near_expiry',
+            usable: true,
+            expiresInMs: remaining,
+            message: `CACHLY_JWT expires in ~${mins} min. cachly will refresh it automatically into a long-lived key while it's still valid.`,
+        };
+    }
+    return { state: 'healthy', usable: true, expiresInMs: remaining, message: '' };
+}
+/**
+ * Decide what self-healing step (if any) to take for a diagnosis. Pure so the
+ * decision is unit-testable independently of the network-bound executor.
+ */
+export function planAuthHeal(d) {
+    switch (d.state) {
+        case 'no_jwt':
+        case 'expired':
+            return 'reauth';
+        case 'near_expiry':
+            return 'refresh';
+        case 'healthy':
+        case 'long_lived':
+            return 'none';
+    }
+}
+export function checkJwt(jwt) {
+    const d = diagnoseAuth(jwt);
+    if (!d.usable) {
+        throw new McpError(ErrorCode.InvalidRequest, d.message);
     }
 }
 export function handleApiError(status, detail) {
     if (status === 401) {
-        throw new McpError(ErrorCode.InvalidRequest, `Authentication failed (401): ${detail}\n\nYour CACHLY_JWT may be expired or invalid. Get a fresh token at https://cachly.dev/setup-ai`);
+        throw new McpError(ErrorCode.InvalidRequest, `Authentication failed (401): ${detail}\n\nYour CACHLY_JWT may be expired or invalid. Get a fresh token at ${SETUP_URL}`);
     }
     if (status === 403) {
         throw new McpError(ErrorCode.InvalidRequest, `Access denied (403): ${detail}\n\nCheck that your CACHLY_JWT belongs to an account with access to this resource.`);

package/dist/src/auth.js.map

@@ -1 +1 @@
-{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,oCAAoC,CAAC;AAEzE,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QACpC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CACxB,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CACjC,CAAC;QACtB,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IACjD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,GAAW;IAClC,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,QAAQ,CAChB,SAAS,CAAC,cAAc,EACxB,wIAAwI,CACzI,CAAC;IACJ,CAAC;IACD,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;IAC/B,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;QACzC,MAAM,IAAI,QAAQ,CAChB,SAAS,CAAC,cAAc,EACxB,yBAAyB,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,iGAAiG,CACxJ,CAAC;IACJ,CAAC;AACH,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,MAAc,EAAE,MAAc;IAC3D,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;QACnB,MAAM,IAAI,QAAQ,CAChB,SAAS,CAAC,cAAc,EACxB,gCAAgC,MAAM,iGAAiG,CACxI,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;QACnB,MAAM,IAAI,QAAQ,CAChB,SAAS,CAAC,cAAc,EACxB,wBAAwB,MAAM,oFAAoF,CACnH,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,QAAQ,CAAC,SAAS,CAAC,aAAa,EAAE,oBAAoB,MAAM,KAAK,MAAM,EAAE,CAAC,CAAC;AACvF,CAAC"}
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/auth.ts"],"names":[],"mappings":"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"}

package/dist/src/handlers/brain.js

@@ -6,8 +6,14 @@ import { keywordSearch, tokenize, splitMultiQuery, levenshtein, indexVocab as _i
 import { rerankByQuality } from '../rerank.js';
 import { computeEmbedding, hasEmbedProvider } from '../embeddings.js';
 // ── Changelog (shown once per version in session_start) ──────────────────────
-const MCP_VERSION = '0.10.70';
+const MCP_VERSION = '0.10.71';
 const WHATS_NEW = {
+    '0.10.71': [
+        `🛡️ **Self-healing auth** — no more silent "0 recalls because the token quietly died"`,
+        `  ♻️ Near-expiry tokens auto-refresh into a long-lived key while still valid (zero interaction)`,
+        `  🔁 A rejected (401) call self-heals once and retries before surfacing an error`,
+        `  📣 If the credential is truly dead, session_start + get_api_status say so plainly + how to fix`,
+    ],
     '0.10.70': [
         `🛰️ **Service/System nodes in the graph (Phase 3)** — the brain now models running systems`,
         `  🆕 \`brain_service_map(service="prometheus")\` — who owns it + every failure/fix known`,