@remnic/core 9.3.767 → 9.3.769

package/src/access-http.ts

@@ -11,7 +11,7 @@ import { abortError, isAbortError } from "./abort-error.js";
 import { EngramAccessInputError, type EngramAccessService, type EngramAccessMemoryResponse, type EngramAccessWriteResponse } from "./access-service.js";
 import { CorrectionContractError } from "./correction/correction-contract.js";
 import { WearablesInputError } from "./wearables/errors.js";
-import { EngramMcpServer } from "./access-mcp.js";
+import { EngramMcpServer, MCP_SUPPORTED_PROTOCOL_VERSIONS } from "./access-mcp.js";
 import { validateRequest, type SchemaName, type SchemaTypeFor } from "./access-schema.js";
 import {
   OFFLINE_SYNC_APPLY_MAX_BODY_BYTES,
@@ -54,6 +54,21 @@ export interface EngramAccessHttpServerOptions {
   authTokens?: string[];
   /** Dynamic token loader — called on each auth check so new/revoked tokens take effect without restart. */
   authTokensGetter?: () => string[];
+  /**
+   * Dynamic token-ENTRY loader ({token, connector} pairs from one coherent
+   * snapshot). Preferred over `authTokensGetter` when a `tokenPathPolicy`
+   * is set: the connector used for the policy decision comes from the SAME
+   * entry that validated, so identity can never lag validation.
+   */
+  authTokenEntriesGetter?: () => ReadonlyArray<{ token: string; connector?: string }>;
+  /**
+   * Optional per-request scope policy for tokens sourced from
+   * `authTokenEntriesGetter`. Return false to deny the (validated) token
+   * for this pathname. Static `authToken`/`authTokens` (operator-supplied)
+   * bypass the policy. Entries whose connector is missing FAIL CLOSED when
+   * a policy is configured.
+   */
+  tokenPathPolicy?: (connector: string, pathname: string | undefined) => boolean;
   principal?: string;
   maxBodyBytes?: number;
   adminConsoleEnabled?: boolean;
@@ -78,6 +93,28 @@ export interface EngramAccessHttpServerOptions {
    * existing health behavior.
    */
   readiness?: () => AccessHttpReadinessState;
+  /**
+   * When set, every 401 response includes
+   * `WWW-Authenticate: Bearer resource_metadata="<value>"` so MCP clients
+   * can discover the OAuth 2.0 protected-resource metadata document
+   * (RFC 9728). Must be an absolute http(s) URL; constructor throws on
+   * anything else. Unset → bare `Bearer`.
+   */
+  resourceMetadataUrl?: string;
+  /**
+   * Optional pre-auth request handler (e.g. OAuth facade mounted by
+   * `@remnic/server`). Runs after the admin-console handler and BEFORE
+   * bearer authorization. Return true if the request was fully handled
+   * (response ended). `ctx.authorized` reports whether the request
+   * carries a valid operator bearer token, so the handler can gate
+   * operator-only endpoints without owning token validation.
+   * Errors thrown by the handler flow into the existing error handling.
+   */
+  externalRequestHandler?: (
+    req: IncomingMessage,
+    res: ServerResponse,
+    ctx: { authorized: boolean },
+  ) => Promise<boolean>;
 }
 
 export interface EngramAccessHttpServerStatus {
@@ -183,6 +220,23 @@ function parseHttpServerPort(port: number | undefined): number {
   }
   return port;
 }
+function assertResourceMetadataUrl(value: string | undefined): string | undefined {
+  if (value === undefined) return undefined;
+  let parsed: URL;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new Error(
+      `access HTTP resourceMetadataUrl must be an absolute http(s) URL, got: ${value}`,
+    );
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error(
+      `access HTTP resourceMetadataUrl must use http or https, got: ${parsed.protocol}`,
+    );
+  }
+  return value;
+}
 
 function parseTrustZoneKindFilter(raw: string | null): TrustZoneRecordKind | undefined {
   if (raw === null) return undefined;
@@ -283,6 +337,8 @@ export class EngramAccessHttpServer {
   private readonly authToken?: string;
   private readonly authTokens: string[];
   private readonly authTokensGetter?: () => string[];
+  private readonly authTokenEntriesGetter?: () => ReadonlyArray<{ token: string; connector?: string }>;
+  private readonly tokenPathPolicy?: (connector: string, pathname: string | undefined) => boolean;
   private readonly authenticatedPrincipal?: string;
   private readonly maxBodyBytes: number;
   private readonly adminConsoleEnabled: boolean;
@@ -292,6 +348,12 @@ export class EngramAccessHttpServer {
   private readonly trustPrincipalHeader: boolean;
   private readonly adapterRegistry: AdapterRegistry | null;
   private readonly readiness: () => AccessHttpReadinessState;
+  private readonly resourceMetadataUrl?: string;
+  private readonly externalRequestHandler?: (
+    req: IncomingMessage,
+    res: ServerResponse,
+    ctx: { authorized: boolean },
+  ) => Promise<boolean>;
   private readonly writeRequestTimestamps: number[] = [];
   private readonly mcpServer: EngramMcpServer;
   private server: Server | null = null;
@@ -323,6 +385,8 @@ export class EngramAccessHttpServer {
     this.authToken = options.authToken?.trim() || undefined;
     this.authTokens = (options.authTokens ?? []).map((t) => t.trim()).filter(Boolean);
     this.authTokensGetter = options.authTokensGetter;
+    this.authTokenEntriesGetter = options.authTokenEntriesGetter;
+    this.tokenPathPolicy = options.tokenPathPolicy;
     this.authenticatedPrincipal = options.principal?.trim() || undefined;
     this.maxBodyBytes = Number.isFinite(options.maxBodyBytes)
       ? Math.max(1, Math.floor(options.maxBodyBytes ?? 131072))
@@ -333,6 +397,8 @@ export class EngramAccessHttpServer {
     this.adminControls = options.adminControls;
     this.trustPrincipalHeader = options.trustPrincipalHeader === true;
     this.readiness = options.readiness ?? (() => ({ ready: true, warmupAttempts: 0 }));
+    this.resourceMetadataUrl = assertResourceMetadataUrl(options.resourceMetadataUrl);
+    this.externalRequestHandler = options.externalRequestHandler;
     this.adapterRegistry = options.enableAdapters !== false
       ? (options.adapterRegistry ?? new AdapterRegistry())
       : null;
@@ -351,7 +417,7 @@ export class EngramAccessHttpServer {
   }
 
   async start(): Promise<EngramAccessHttpServerStatus> {
-    if (!this.authToken && this.authTokens.length === 0 && !this.authTokensGetter) {
+    if (!this.authToken && this.authTokens.length === 0 && !this.authTokensGetter && !this.authTokenEntriesGetter) {
       throw new Error("engram access HTTP requires authToken or authTokens");
     }
     if (this.server) return this.status();
@@ -642,11 +708,40 @@ export class EngramAccessHttpServer {
 
     }
 
+    // Run any host-supplied pre-auth request handler. It runs AFTER the
+    // admin-console branch (admin assets are public) and BEFORE the
+    // operator bearer gate. The handler decides whether it has fully
+    // owned the response (return true) or wants the request to fall
+    // through to the normal pipeline. `ctx.authorized` is computed
+    // here so the handler can implement operator-only endpoints
+    // (e.g. /oauth/pending) without owning token validation.
+    if (this.externalRequestHandler) {
+      const authorized = this.isAuthorized(req, pathname);
+      if (await this.externalRequestHandler(req, res, { authorized })) {
+        return;
+      }
+    }
+
     if (!this.isAuthorized(req, pathname)) {
       const body = JSON.stringify({ error: "unauthorized", code: "unauthorized" });
       res.writeHead(401, {
         "content-type": "application/json; charset=utf-8",
-        "www-authenticate": "Bearer",
+        "www-authenticate": this.bearerChallenge(),
+        "x-request-id": correlationId,
+      });
+      res.end(body);
+      return;
+    }
+
+    // Method-conformance for the streamable-HTTP MCP endpoint:
+    // GET/DELETE on /mcp must return 405 + Allow: POST instead of
+    // silently falling through to the generic 404. POST continues
+    // to the normal handler below.
+    if (pathname === "/mcp" && (req.method === "GET" || req.method === "DELETE")) {
+      const body = JSON.stringify({ error: "method_not_allowed", code: "method_not_allowed" });
+      res.writeHead(405, {
+        "content-type": "application/json; charset=utf-8",
+        allow: "POST",
         "x-request-id": correlationId,
       });
       res.end(body);
@@ -2682,7 +2777,28 @@ export class EngramAccessHttpServer {
   }
 
   private async handleMcpRequest(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    // Reject requests that advertise an unknown MCP protocol version in
+    // the streamable-HTTP `MCP-Protocol-Version` header. Absent or
+    // valid → proceed. Unknown → 400 with a JSON-RPC-shaped error so
+    // the client surfaces a clear message. The supported set is
+    // exported by @remnic/core's access-mcp module to keep the
+    // version policy in a single place.
+    const headerVersion = req.headers["mcp-protocol-version"];
+    if (typeof headerVersion === "string" && headerVersion.length > 0) {
+      if (!(MCP_SUPPORTED_PROTOCOL_VERSIONS as readonly string[]).includes(headerVersion)) {
+        this.respondJson(res, 400, {
+          jsonrpc: "2.0",
+          id: null,
+          error: {
+            code: -32000,
+            message: `unsupported MCP-Protocol-Version: ${headerVersion}; supported: ${MCP_SUPPORTED_PROTOCOL_VERSIONS.join(", ")}`,
+          },
+        });
+        return;
+      }
+    }
     const body = await this.readJsonBody(req);
+
     const request = body as {
       jsonrpc?: string;
       id?: string | number | null;
@@ -3118,8 +3234,29 @@ export class EngramAccessHttpServer {
     return result.data as SchemaTypeFor<S>;
   }
 
-  private isAuthorized(req: IncomingMessage, pathname?: string): boolean {
-    if (!this.authToken && this.authTokens.length === 0 && !this.authTokensGetter) return false;
+  /**
+   * Build the WWW-Authenticate challenge string for 401 responses.
+   * When `resourceMetadataUrl` is configured, includes the RFC 9728
+   * `resource_metadata` parameter so MCP clients (e.g. ChatGPT) can
+   * discover the OAuth 2.0 protected-resource metadata document.
+   * Otherwise the bare `Bearer` challenge is returned (unchanged).
+   */
+  private bearerChallenge(): string {
+    if (this.resourceMetadataUrl) {
+      return `Bearer resource_metadata="${this.resourceMetadataUrl}"`;
+    }
+    return "Bearer";
+  }
+
+   private isAuthorized(req: IncomingMessage, pathname?: string): boolean {
+    if (
+      !this.authToken &&
+      this.authTokens.length === 0 &&
+      !this.authTokensGetter &&
+      !this.authTokenEntriesGetter
+    ) {
+      return false;
+    }
     // Primary path: Authorization: Bearer <token> header.
     const raw = req.headers.authorization;
     let candidate: string | null = null;
@@ -3159,7 +3296,24 @@ export class EngramAccessHttpServer {
     for (const valid of this.authTokens) {
       if (this.timingSafeStringEqual(token, valid)) return true;
     }
-    // Check dynamic tokens (reloaded per request for generate/revoke without restart)
+    // Entry-based dynamic tokens are AUTHORITATIVE when configured: the
+    // dynamic-token decision ends here (no fall-through to the string
+    // getter, which carries no identity and would bypass the policy).
+    // Validation and connector identity come from the same snapshot entry,
+    // so a scope policy can never observe a token fresher than the
+    // identity it scopes (mint/revoke coherence).
+    if (this.authTokenEntriesGetter) {
+      for (const entry of this.authTokenEntriesGetter()) {
+        if (!this.timingSafeStringEqual(token, entry.token)) continue;
+        if (!this.tokenPathPolicy) return true;
+        // Fail closed: a policy without a connector identity denies.
+        if (typeof entry.connector !== "string" || entry.connector.length === 0) return false;
+        return this.tokenPathPolicy(entry.connector, pathname);
+      }
+      return false;
+    }
+    // String-token getter (no identity, no policy) — only consulted when
+    // no entry getter is configured.
     if (this.authTokensGetter) {
       for (const valid of this.authTokensGetter()) {
         if (this.timingSafeStringEqual(token, valid)) return true;

package/src/access-mcp.ts

@@ -78,7 +78,79 @@ type McpResource = {
   _meta?: Record<string, unknown>;
 };
 
-const MCP_PROTOCOL_VERSION = "2024-11-05";
+/**
+ * Conservative allowlist of canonical MCP tool suffixes that are
+ * unambiguously read-only. Tools in this set are tagged with
+ * `annotations: { readOnlyHint: true }` so ChatGPT (and other MCP
+ * clients that honor the hint) can skip per-call confirmation.
+ *
+ * The list is suffix-based so it covers both the `remnic.*` and
+ * `engram.*` naming forms. Anything not on it stays unannotated:
+ * uncertainty is resolved as "might mutate".
+ *
+ * Excluded by construction: anything that writes, runs a pipeline,
+ * flushes, applies, records, imports, or destructively deletes.
+ */
+const MCP_READ_ONLY_TOOL_SUFFIXES: Readonly<Record<string, true>> = {
+  recall: true,
+  recall_explain: true,
+  recall_tier_explain: true,
+  recall_xray: true,
+  briefing: true,
+  wearables_status: true,
+  transcript_day: true,
+  transcript_search: true,
+  transcript_memories: true,
+  action_confidence: true,
+  capsule_list: true,
+  procedural_stats: true,
+  memory_get: true,
+  memory_timeline: true,
+  entity_get: true,
+  review_queue_list: true,
+  lcm_search: true,
+  continuity_incident_list: true,
+  identity_anchor_get: true,
+  memory_identity: true,
+  memory_search: true,
+  memory_profile: true,
+  memory_entities_list: true,
+  memory_questions: true,
+  memory_last_recall: true,
+  memory_intent_debug: true,
+  memory_qmd_debug: true,
+  memory_graph_explain: true,
+  graph_snapshot: true,
+  review_list: true,
+  profiling_report: true,
+  peer_list: true,
+  peer_get: true,
+  peer_profile_get: true,
+  console_state: true,
+  dreams_status: true,
+  codegraph_list_projects: true,
+  codegraph_index_status: true,
+  codegraph_search_graph: true,
+  codegraph_trace_path: true,
+  codegraph_detect_changes: true,
+  codegraph_query_graph: true,
+  codegraph_get_schema: true,
+  codegraph_get_snippet: true,
+  codegraph_get_architecture: true,
+  codegraph_search_code: true,
+};
+
+/**
+ * MCP protocol versions this server understands, ordered newest → oldest.
+ * Exported so the HTTP transport can validate the `MCP-Protocol-Version`
+ * header and reject requests advertising an unknown version.
+ */
+export const MCP_SUPPORTED_PROTOCOL_VERSIONS: readonly string[] = [
+  "2025-06-18",
+  "2025-03-26",
+  "2024-11-05",
+];
+const MCP_DEFAULT_PROTOCOL_VERSION: string = MCP_SUPPORTED_PROTOCOL_VERSIONS[0] ?? "2025-06-18";
 const LEGACY_MCP_PREFIX = "engram.";
 const CANONICAL_MCP_PREFIX = "remnic.";
 
@@ -87,13 +159,27 @@ function toCanonicalToolName(name: string): string {
     ? `${CANONICAL_MCP_PREFIX}${name.slice(LEGACY_MCP_PREFIX.length)}`
     : name;
 }
-
 function toLegacyToolName(name: string): string {
   return name.startsWith(CANONICAL_MCP_PREFIX)
     ? `${LEGACY_MCP_PREFIX}${name.slice(CANONICAL_MCP_PREFIX.length)}`
     : name;
 }
 
+/**
+ * Suffix-based allowlist matcher. Returns true for tools whose canonical
+ * suffix (after stripping `remnic.` or `engram.`) is in
+ * {@link MCP_READ_ONLY_TOOL_SUFFIXES}. Unprefixed names are treated as
+ * unannotated.
+ */
+function isReadOnlyToolName(name: string): boolean {
+  for (const prefix of [CANONICAL_MCP_PREFIX, LEGACY_MCP_PREFIX]) {
+    if (name.startsWith(prefix)) {
+      return MCP_READ_ONLY_TOOL_SUFFIXES[name.slice(prefix.length)] === true;
+    }
+  }
+  return false;
+}
+
 function withToolAliases(tool: McpTool, emitLegacyTools = true): McpTool[] {
   const canonicalName = toCanonicalToolName(tool.name);
   const canonicalTool = canonicalName === tool.name ? tool : { ...tool, name: canonicalName };
@@ -2342,6 +2428,17 @@ export class EngramMcpServer {
       );
       this.tools = [...this.tools, ...chatTools];
     }
+    // Apply `readOnlyHint` annotations to the conservative read-only
+    // allowlist. Done as a final pass so every spread (chat, codegraph,
+    // coding_*, correction, etc.) inherits the annotation without
+    // scattering the same logic across every `withToolAliases` call site.
+    // Suffix-based matching covers both the `remnic.*` and `engram.*`
+    // naming forms emitted by `withToolAliases`.
+    this.tools = this.tools.map((tool) =>
+      isReadOnlyToolName(tool.name) && tool.annotations?.readOnlyHint !== true
+        ? { ...tool, annotations: { ...(tool.annotations ?? {}), readOnlyHint: true } }
+        : tool,
+    );
   }
 
   /** Get clientInfo for a specific MCP session. Returns undefined for non-MCP requests. */
@@ -2369,6 +2466,24 @@ export class EngramMcpServer {
     }
     if (method === "initialize") {
       const params = request.params ?? {};
+      // MCP initialize REQUIRES params.protocolVersion (string). Reject a
+      // missing/mistyped field with JSON-RPC invalid params instead of
+      // silently negotiating (repo rule: never reinterpret invalid input).
+      // An unsupported-but-well-formed version gets the spec-mandated
+      // counter-offer below instead: the server answers with the newest
+      // version it supports and the client decides whether to proceed.
+      if (typeof params.protocolVersion !== "string" || params.protocolVersion.length === 0) {
+        return {
+          jsonrpc: "2.0",
+          id,
+          error: {
+            code: -32602,
+            message:
+              "initialize requires params.protocolVersion (string); " +
+              `supported versions: ${MCP_SUPPORTED_PROTOCOL_VERSIONS.join(", ")}`,
+          },
+        };
+      }
       const rawClientInfo = params.clientInfo as { name?: string; version?: string } | undefined;
       // Generate a server-side session ID for this MCP session.
       // The caller should send this back as Mcp-Session-Id on subsequent requests.
@@ -2391,7 +2506,9 @@ export class EngramMcpServer {
         jsonrpc: "2.0",
         id,
         result: {
-          protocolVersion: MCP_PROTOCOL_VERSION,
+          protocolVersion: MCP_SUPPORTED_PROTOCOL_VERSIONS.includes(params.protocolVersion)
+            ? params.protocolVersion
+            : MCP_DEFAULT_PROTOCOL_VERSION,
           capabilities: {
             tools: {},
             resources: {},

package/src/index.ts

@@ -977,11 +977,14 @@ export {
 // ---------------------------------------------------------------------------
 
 export {
+  buildTokenEntry,
+  commitTokenEntry,
   generateToken,
   listTokens,
   revokeToken,
   getAllValidTokens,
   getAllValidTokensCached,
+  getAllValidTokenEntriesCached,
   resolveConnectorFromToken,
   loadTokenStore,
   saveTokenStore,

package/src/tokens.test.ts

@@ -8,6 +8,7 @@ import {
   buildTokenEntry,
   commitTokenEntry,
   generateToken,
+  getAllValidTokenEntriesCached,
   getAllValidTokensCached,
   loadTokenStore,
   revokeToken,
@@ -208,3 +209,60 @@ test("generateToken uses a recognizable prefix for the omp connector", async ()
     await rm(dir, { recursive: true, force: true });
   }
 });
+
+test("generateToken uses a recognizable prefix for the chatgpt connector", async () => {
+  const { dir, tokensPath } = await makeTempTokenPath();
+  try {
+    const entry = generateToken("chatgpt", tokensPath);
+    assert.equal(entry.connector, "chatgpt");
+    assert.ok(
+      entry.token.startsWith("remnic_cg_"),
+      `expected remnic_cg_ prefix, got ${entry.token}`,
+    );
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("commitTokenEntry replaces the prior chatgpt entry so re-linking rotates the token", async () => {
+  const { dir, tokensPath } = await makeTempTokenPath();
+  try {
+    const first = generateToken("chatgpt", tokensPath);
+    commitTokenEntry(first, tokensPath);
+    const second = generateToken("chatgpt", tokensPath);
+    commitTokenEntry(second, tokensPath);
+    assert.notEqual(first.token, second.token, "re-linking must mint a new token");
+    const store = loadTokenStore(tokensPath);
+    const chatgptEntries = store.tokens.filter((t) => t.connector === "chatgpt");
+    assert.equal(chatgptEntries.length, 1, "only one chatgpt entry survives the rotate");
+    assert.equal(chatgptEntries[0]?.token, second.token, "the new token is the surviving one");
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("entries snapshot is coherent with validation: mint and revoke take effect immediately", async () => {
+  const { dir, tokensPath } = await makeTempTokenPath();
+  try {
+    // Warm the cache so a stale snapshot WOULD be observable if mutation
+    // failed to invalidate it.
+    assert.deepEqual([...getAllValidTokenEntriesCached(tokensPath)], []);
+
+    // Mint-then-use: the fresh token resolves with its connector in the
+    // SAME snapshot call that validates it — no window where the token is
+    // valid but its identity is unknown.
+    const minted = generateToken("chatgpt", tokensPath);
+    const afterMint = getAllValidTokenEntriesCached(tokensPath);
+    const found = afterMint.find((entry) => entry.token === minted.token);
+    assert.ok(found, "freshly minted token must appear immediately");
+    assert.equal(found.connector, "chatgpt");
+    assert.deepEqual(getAllValidTokensCached(tokensPath), [minted.token]);
+
+    // Revoke-then-use: the token disappears from the snapshot immediately.
+    assert.equal(revokeToken("chatgpt", tokensPath), true);
+    assert.deepEqual([...getAllValidTokenEntriesCached(tokensPath)], []);
+    assert.deepEqual(getAllValidTokensCached(tokensPath), []);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});

package/src/tokens.ts

@@ -36,6 +36,7 @@ const TOKEN_PREFIXES: Record<string, string> = {
   "windsurf": "remnic_ws_",
   "amp": "remnic_am_",
   "generic-mcp": "remnic_gm_",
+  "chatgpt": "remnic_cg_",
 };
 
 function defaultTokensPath(): string {
@@ -260,26 +261,36 @@ export function getAllValidTokens(tokensPath?: string): string[] {
   return loadTokenStore(tokensPath).tokens.map((t) => t.token);
 }
 
-// Cached token loader to avoid synchronous disk I/O on every HTTP request.
-// Re-reads tokens.json at most once per TTL interval (default 5s).
+// Cached token-entry snapshot to avoid synchronous disk I/O on every HTTP
+// request. Re-reads tokens.json at most once per TTL interval (default 5s).
+// There is deliberately exactly ONE cache: validation (token strings) and
+// identity (connector ids) are derived from the SAME snapshot, so a token
+// can never validate against a fresher snapshot than the one that resolves
+// its connector. saveTokenStore() invalidates on every mutation, so a
+// freshly minted or revoked token is coherent immediately.
 const TOKEN_CACHE_TTL_MS = 5_000;
-let _cachedTokens: string[] = [];
+let _cachedEntries: TokenEntry[] = [];
 let _cachedAt = 0;
 let _cachedPath: string | undefined;
 
 function invalidateTokenCache(): void {
-  _cachedTokens = [];
+  _cachedEntries = [];
   _cachedAt = 0;
   _cachedPath = undefined;
 }
 
-export function getAllValidTokensCached(tokensPath?: string): string[] {
+/** Cached token-entry snapshot ({token, connector} pairs). */
+export function getAllValidTokenEntriesCached(tokensPath?: string): readonly TokenEntry[] {
   const now = Date.now();
-  if (now - _cachedAt < TOKEN_CACHE_TTL_MS && tokensPath === _cachedPath) return _cachedTokens;
-  _cachedTokens = getAllValidTokens(tokensPath);
+  if (now - _cachedAt < TOKEN_CACHE_TTL_MS && tokensPath === _cachedPath) return _cachedEntries;
+  _cachedEntries = loadTokenStore(tokensPath).tokens;
   _cachedAt = now;
   _cachedPath = tokensPath;
-  return _cachedTokens;
+  return _cachedEntries;
+}
+
+export function getAllValidTokensCached(tokensPath?: string): string[] {
+  return getAllValidTokenEntriesCached(tokensPath).map((entry) => entry.token);
 }
 
 export function resolveConnectorFromToken(token: string, tokensPath?: string): string | undefined {