@lorekit/cli 1.29.0 → 1.29.2

package/README.md

@@ -110,6 +110,14 @@ command is still refreshed. Pass `--hooks <mode>` to choose explicitly.
 wiring new ones. `lorekit doctor` reports which events are wired, and in which
 scope.
 
+**Replacing a token.** A plain re-run reuses the token already in your config.
+An interactive `lorekit install --force` instead asks what to do with it —
+**keep**, **replace** (paste a new one), or **remove** — so a revoked token can
+be swapped without hand-editing `.mcp.json` / `~/.claude.json`. The stored token
+is only ever shown masked (`lk_rw_…ijkl`). Non-interactive runs (`--yes`, or no
+TTY) never prompt and keep reusing the stored token; pass `--token` to replace
+it in a script.
+
 > The hook command uses a global `lorekit` when one is on your `PATH` (fast),
 > otherwise `npx -y @lorekit/cli`. Installing the CLI globally
 > (`npm i -g @lorekit/cli`) is recommended so hooks fire without an npx
@@ -127,7 +135,9 @@ Verifies the setup and prints a status report:
   gitignored
 - for `remote`: `.mcp.json` has a `lorekit` server, the endpoint is real (not
   the `<project-ref>` placeholder), the token and its permission tier
-  (`lk_rw_*` / `lk_ro_*` / `lk_wo_*`), and that the endpoint is reachable
+  (`lk_rw_*` / `lk_ro_*` / `lk_wo_*`), that the endpoint is reachable, and —
+  the `authentication` check — that the token is **still accepted by the
+  server**
 - for `off`: a note that memory is disabled
 - the git-derived read/write scopes for the current directory
 
@@ -138,6 +148,22 @@ lorekit doctor --deep     # also does a write → read → delete round-trip (ne
 
 Exit code is non-zero if any check fails, so it fits CI gates.
 
+**`connectivity` and `authentication` are different questions.** `connectivity`
+probes the public `/health` function: it proves the network path and says
+nothing about your credential. `authentication` makes one authenticated,
+side-effect-free request and reports what the server said about the token
+itself:
+
+| Result | Meaning |
+| --- | --- |
+| `PASS — token accepted` | the token is live (read access confirmed) |
+| `PASS — no read permission` | accepted, but it is a write-only `lk_wo_*` token |
+| `FAIL — token REJECTED (HTTP 401)` | revoked, deleted, or never valid — every remote read and write is broken |
+| `WARN` | rate limited, unreachable, or an inconclusive answer — never reported as "revoked" |
+
+A revoked token is a **failure**, not a warning: fix it by creating a new token
+and running `lorekit install --force`, which offers to replace the stored one.
+
 ### `lorekit list` (alias `ls`)
 
 Shows the lessons that apply to **where you are** — the scopes `deriveScope`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lorekit/cli",
-  "version": "1.29.0",
+  "version": "1.29.2",
   "description": "Install the LoreKit shared-memory skill and run health checks for the LoreKit MCP server.",
   "license": "MIT",
   "repository": {

package/src/doctor.mjs

@@ -268,8 +268,11 @@ async function checkRemote(control, root, args, record) {
     if (res.networkError) {
       record('fail', 'connectivity', res.networkError);
     } else if (res.ok) {
-      const tools = res.result && Array.isArray(res.result.tools) ? res.result.tools.length : null;
-      record('pass', 'connectivity', tools !== null ? `reachable, ${tools} tools` : 'reachable');
+      // Say what the probe actually proved. `ping()` hits the PUBLIC `/health`
+      // function and returns only `{ ok, httpStatus }` — never a tool list — so
+      // "reachable" is a statement about the network path alone. The token itself
+      // is judged by the `authentication` check below.
+      record('pass', 'connectivity', 'reachable (public health probe — token not checked)');
     } else if (res.error && AUTH_CODES.has(res.error.code)) {
       record('fail', 'connectivity', `auth rejected (${res.error.code}) — check your token`);
     } else if (res.error) {
@@ -278,10 +281,64 @@ async function checkRemote(control, root, args, record) {
       record('warn', 'connectivity', `unexpected response (HTTP ${res.httpStatus})`);
     }
 
+    await checkRemoteAuth(store, record);
+
     if (args.deep) await deepCheckRemote(store, root, record);
   } else {
     record('warn', 'connectivity', 'skipped — need a valid endpoint and token');
+    record('warn', 'authentication', 'skipped — need a valid endpoint and token');
+  }
+}
+
+/**
+ * Does the configured token STILL work?
+ *
+ * The `token` check above only reads the PREFIX (`lk_rw_`/`lk_ro_`/`lk_wo_`)
+ * and `connectivity` probes the PUBLIC `/health` function, so both stay green
+ * for a token that has been revoked in the dashboard — which is precisely the
+ * state a user runs doctor in. This check makes one authenticated,
+ * side-effect-free request and reports what the server said about the
+ * credential itself.
+ *
+ * A revoked token is a FAIL (doctor exits non-zero): every remote read and
+ * write is broken, which is not a warning-level condition. A token that is
+ * accepted but lacks read permission is a PASS — that is the healthy state of a
+ * write-only token, and the `token` check already describes the tradeoff.
+ */
+async function checkRemoteAuth(store, record) {
+  const res = await store.verifyAuth();
+
+  if (res.networkError) {
+    record('warn', 'authentication', `could not verify — ${res.networkError}`);
+    return;
+  }
+  if (res.unusable) {
+    record('warn', 'authentication', 'skipped — need a valid endpoint and token');
+    return;
+  }
+  if (res.authenticated === false) {
+    record(
+      'fail',
+      'authentication',
+      'token REJECTED by the server (HTTP 401) — it has been revoked, deleted, or was never valid. ' +
+        'Create a new one at https://lorekit.io/settings, then run `lorekit install --force` to replace it.',
+    );
+    return;
+  }
+  if (res.rateLimited) {
+    record('warn', 'authentication', 'could not verify — the request was rate limited (HTTP 429) before it reached the route; retry shortly');
+    return;
+  }
+  if (res.authenticated === true) {
+    record(
+      'pass',
+      'authentication',
+      res.permitted ? 'token accepted — read access confirmed' : 'token accepted — no read permission (write-only token)',
+    );
+    return;
   }
+  const detail = res.error ? res.error.message || res.error.code : `HTTP ${res.httpStatus}`;
+  record('warn', 'authentication', `inconclusive — server said: ${detail}`);
 }
 
 async function deepCheckRemote(store, root, record) {

package/src/install.mjs

@@ -33,6 +33,46 @@ function ask(question) {
   return new Promise((resolve) => rl.question(question, (a) => { rl.close(); resolve(a.trim()); }));
 }
 
+// Show enough of a token to recognise it, never enough to use it: the
+// permission prefix plus the last four characters.
+export function maskToken(token) {
+  if (!token) return 'none';
+  const s = String(token);
+  const m = /^(lk_(?:rw|ro|wo)_)/.exec(s);
+  const prefix = m ? m[1] : '';
+  const tail = s.slice(-4);
+  return s.length <= prefix.length + 4 ? `${prefix}…` : `${prefix}…${tail}`;
+}
+
+/**
+ * How `install` should arrive at the token it writes — the pure decision, so
+ * the rule is testable without a pseudo-TTY.
+ *
+ *   'flag'   → an explicit --token / LOREKIT_TOKEN wins outright.
+ *   'choose' → a token is already configured AND this is an interactive
+ *              `--force`: ask whether to keep / replace / remove it.
+ *   'reuse'  → a token is already configured: reuse it silently.
+ *   'prompt' → nothing configured and someone is there to ask.
+ *   'none'   → nothing configured and nobody to ask.
+ *
+ * WHY 'choose' exists: `--force` is what a user runs precisely BECAUSE the
+ * current setup is wrong, and the most common way for it to be wrong is a
+ * revoked token — which doctor's `authentication` check now names, telling them
+ * to come here. Reusing the stored token silently made `--force` incapable of
+ * fixing the one thing it was reached for, and no other command could either.
+ * It stays interactive-only: a non-interactive run has nobody to answer, so it
+ * keeps the old reuse behaviour and `--token` remains the way to replace a
+ * token in a script.
+ */
+export function tokenPlan({ flagToken, existingToken, force, nonInteractive } = {}) {
+  if (flagToken) return { action: 'flag', token: flagToken };
+  if (existingToken) {
+    if (force && !nonInteractive) return { action: 'choose', token: existingToken };
+    return { action: 'reuse', token: existingToken };
+  }
+  return nonInteractive ? { action: 'none', token: null } : { action: 'prompt', token: null };
+}
+
 // Detect whether lorekit is already installed for a given scope. Returns an
 // object describing what is present so the caller can give precise feedback.
 function detectInstalled(root, scope) {
@@ -256,16 +296,44 @@ export async function install(args) {
   const endpoint = fromArgs.endpoint || LOREKIT_MCP_ENDPOINT;
 
   // Token resolution order: --token flag → env → existing config → prompt.
-  let token = fromArgs.token;
-  if (!token && currentState.existingToken) {
-    // Reuse the token that's already in the config — don't make the user repeat
-    // it just because they're running install again.
-    token = currentState.existingToken;
+  const plan = tokenPlan({
+    flagToken: fromArgs.token,
+    existingToken: currentState.existingToken,
+    force,
+    nonInteractive,
+  });
+
+  let token = null;
+  if (plan.action === 'flag') {
+    token = plan.token;
+  } else if (plan.action === 'reuse') {
+    token = plan.token;
     log(`  ${c.dim('Token: reusing existing token from config.')}`);
-  }
-  if (!token && !nonInteractive) {
-    token = await ask('  LoreKit token (lk_rw_… to allow writes, blank to skip): ');
-    token = token || null;
+  } else if (plan.action === 'choose') {
+    const choice = await select(
+      `A token is already configured (${maskToken(currentState.existingToken)}). What should this reinstall do?`,
+      [
+        { label: 'Keep the existing token', value: 'keep', hint: 'reuse what is in the config' },
+        { label: 'Replace it with a new token', value: 'replace', hint: 'paste a fresh lk_… token (e.g. after revoking one)' },
+        { label: 'Remove the token', value: 'remove', hint: 'leave the server unauthenticated' },
+      ],
+    );
+    if (choice === 'replace') {
+      const entered = await ask('  New LoreKit token (lk_rw_… to allow writes, blank to keep the existing one): ');
+      token = entered || currentState.existingToken;
+      log(`  ${c.dim(entered ? 'Token: replaced with the token you entered.' : 'Token: nothing entered — keeping the existing token.')}`);
+    } else if (choice === 'remove') {
+      // Deliberately NOT followed by the fresh-install prompt below: someone who
+      // just chose "remove" must not be immediately asked for a token again.
+      token = null;
+      log(`  ${c.yellow('Token: removed — reads/writes will fail until a token is set.')}`);
+    } else {
+      token = currentState.existingToken;
+      log(`  ${c.dim('Token: reusing existing token from config.')}`);
+    }
+  } else if (plan.action === 'prompt') {
+    const entered = await ask('  LoreKit token (lk_rw_… to allow writes, blank to skip): ');
+    token = entered || null;
   }
 
   // 4. Install the skill files — every skill the CLI ships.

package/src/store/remote.mjs

@@ -197,8 +197,62 @@ class RemoteStore {
     return { ok: true, scopes: scopes.map((s) => ({ scope: s.scope, count: Number(s.count) || 0 })) };
   }
 
+  // Authentication probe for doctor — does the configured token STILL work?
+  //
+  // `ping()` deliberately hits the PUBLIC `/health` function, so it stays green
+  // for a revoked, deleted or mistyped token: it proves the network path, and
+  // nothing about the credential. This probe is the missing half. It makes one
+  // authenticated, side-effect-free request (`GET /memories?limit=1`) and
+  // classifies the answer:
+  //
+  //   200 → the token was accepted AND may read.
+  //   401 → the token was REJECTED (revoked, deleted, or never valid). This is
+  //         `resolveRestAuth` finding no `api_tokens` row for the hash
+  //         (supabase/functions/_shared/api/auth.ts).
+  //   403 → the token was ACCEPTED, but lacks read permission — the normal,
+  //         healthy answer for a write-only `lk_wo_*` token, so it must never
+  //         be reported as an auth failure.
+  //   429 → rate limited, and it says NOTHING about the credential. The only
+  //         `tooManyRequests()` call sites on the whole REST surface are
+  //         `memories/handlers/create.ts` and `purge.ts` — both write paths.
+  //         `GET /memories` (`handleList`) has no rate-limit check at all, so a
+  //         429 here is emitted by the platform edge AHEAD of the function,
+  //         before `resolveRestAuth` ever runs. `rateLimited` is still reported
+  //         so the caller can say "retry shortly" instead of "inconclusive".
+  //
+  // Returns { ok, authenticated, permitted, rateLimited, httpStatus, error,
+  // networkError, unusable }. `authenticated` is null when the answer does not
+  // settle the question — the caller must not turn "don't know" into "broken".
+  async verifyAuth() {
+    if (!this.usable()) return { ok: false, unusable: true, authenticated: null };
+    if (!this.restBase) {
+      return { ok: false, authenticated: null, error: { message: `Endpoint is not a valid URL: ${this.endpoint}` } };
+    }
+    // limit=1 keeps the probe cheap; the rows themselves are never read.
+    const res = await this._rest('/memories?limit=1');
+    if (res.networkError) return { ok: false, authenticated: null, networkError: res.networkError };
+    if (res.ok) return { ok: true, authenticated: true, permitted: true, httpStatus: res.httpStatus };
+
+    const httpStatus = res.httpStatus ?? null;
+    if (httpStatus === 401) {
+      return { ok: false, authenticated: false, permitted: false, httpStatus, error: res.error };
+    }
+    if (httpStatus === 403) {
+      return { ok: true, authenticated: true, permitted: false, httpStatus, error: res.error };
+    }
+    if (httpStatus === 429) {
+      return { ok: true, authenticated: null, permitted: null, rateLimited: true, httpStatus, error: res.error };
+    }
+    return { ok: false, authenticated: null, httpStatus, error: res.error };
+  }
+
   // Connectivity probe for doctor — a transport check, not a memory op.
   //
+  // NOTE: this is deliberately UNAUTHENTICATED (the `/health` function is
+  // public), so a green result says the endpoint is reachable and says NOTHING
+  // about the token. `verifyAuth()` above is what answers that; doctor runs
+  // both and reports them as separate checks.
+  //
   // There is no MCP fallback: a `restBase` we could not derive means the
   // configured endpoint is not a URL, and a JSON-RPC POST to that same
   // unparseable string could only fail in a less legible way. Report the