@jini-ai/mcp 0.3.4 → 0.4.1

package/dist/core/config.js

@@ -1,3 +1,4 @@
+import { isLoopbackHostname } from '@jini-ai/platform/net';
 /**
  * @module @jini-ai/mcp/core/config
  * Config schema + on-disk store for the external MCP servers the daemon connects
@@ -22,8 +23,37 @@
 import { readFile } from 'node:fs/promises';
 import { realpathSync } from 'node:fs';
 import path from 'node:path';
-import { pathContains } from '@jini-ai/platform';
-import { writeSecretFileAtomic } from './secure-write.js';
+import { pathContains } from '@jini-ai/core/primitives';
+import { writeFileAtomicAsync } from '@jini-ai/platform/fs';
+/** Shared atomic secret persistence (CR-006 / SEC-RB-002).
+ * The previous pattern in each of those stores wrote the temp file with
+ * default permissions and either never restricted it (config, OAuth client
+ * cache) or `chmod(0600)`'d it *after* the atomic rename and silently
+ * continued when the chmod failed (tokens) — both leave a window where the
+ * file exists world/group-readable, and the latter makes the "protection"
+ * advisory rather than enforced. The platform writer instead:
+ *
+ *   1. Creates the temp file *exclusively* (`wx`) with mode 0600 supplied to
+ *      the same `open()`/`writeFile()` call that creates it — POSIX applies
+ *      the requested mode atomically at creation time, so there is no
+ *      window where the file exists with a broader mode. Creation-mode enforcement
+ *      follows the existing prompt-file precedent; the shared writer also reapplies
+ *      0600 before checking the mode and flushing the file, never after rename.
+ *   2. On POSIX platforms, verifies the on-disk mode actually landed as
+ *      owner-only before renaming into place, and fails closed — removing
+ *      the temp file and throwing — if it did not (e.g. an unusual umask or
+ *      a filesystem that doesn't honor `mode`).
+ *   3. Skips that verification on `win32`: Windows has no POSIX permission-
+ *      bit model (`mode` there only toggles the read-only attribute), so
+ *      there is nothing meaningful to enforce or fail closed on.
+ *   4. Flushes file content before rename and the parent directory after it. A directory
+ *      flush can fail after replacement; it is reported rather than silently ignored.
+ *
+ */
+const defaultFilesystem = {
+    readText: ({ filePath }) => readFile(filePath, 'utf8'),
+    writeSecretText: ({ filePath, contents }) => writeFileAtomicAsync({ filePath, content: contents }, { mode: 0o600, verifyOwnerOnly: true, createParent: true }),
+};
 const VALID_TRANSPORTS = new Set([
     'stdio',
     'sse',
@@ -69,21 +99,8 @@ function sanitizeStringArray(raw) {
     const out = raw.filter((v) => typeof v === 'string');
     return out.length > 0 ? out : undefined;
 }
-function normalizeHost(hostname) {
-    return hostname
-        .replace(/^\[|\]$/g, '')
-        .toLowerCase()
-        .replace(/\.+$/g, '');
-}
-function isLoopbackHost(hostname) {
-    const host = normalizeHost(hostname);
-    if (host === 'localhost' || host === '::1')
-        return true;
-    // Note: IPv4-mapped IPv6 loopback (`::ffff:127.0.0.1`) is not special-cased —
-    // the WHATWG URL parser compresses it to `::ffff:7f00:1` before it reaches
-    // here, so a dotted-quad match is unreachable through `inferMcpAuthModeForUrl`.
-    return /^127(?:\.\d{1,3}){3}$/.test(host);
-}
+// The shared classifier receives the URL parser's canonical hostname; IPv4-mapped
+// IPv6 is deliberately not a loopback exception for default authentication.
 /**
  * Infer the appropriate `McpAuthMode` for a given server URL.
  * Returns `'none'` for loopback targets (localhost, 127.x.x.x, ::1)
@@ -91,11 +108,11 @@ function isLoopbackHost(hostname) {
  * @param rawUrl The server URL string to inspect, if any.
  * @returns The inferred `McpAuthMode`.
  */
-export function inferMcpAuthModeForUrl(rawUrl) {
+export function inferMcpAuthModeForUrl({ rawUrl }) {
     if (!rawUrl)
         return 'oauth';
     try {
-        return isLoopbackHost(new URL(rawUrl).hostname) ? 'none' : 'oauth';
+        return isLoopbackHostname({ hostname: new URL(rawUrl).hostname }) ? 'none' : 'oauth';
     }
     catch {
         return 'oauth';
@@ -110,22 +127,28 @@ function sanitizeMcpAuthMode(raw) {
 // there is no stdio short-circuit here — the token merge just needs the
 // effective auth mode for a remote server.
 function effectiveMcpAuthMode(server) {
-    return server.authMode ?? inferMcpAuthModeForUrl(server.url);
+    return server.authMode ?? inferMcpAuthModeForUrl({ rawUrl: server.url });
 }
 /**
  * Validate a single user-supplied entry. Drops invalid fields so a typo in
  * one server doesn't tank the whole config. Returns null when the entry is
  * unsalvageable (no id, or no transport-required fields).
  */
-export function sanitizeMcpServer(raw) {
+export function sanitizeMcpServer({ raw }) {
     if (!isPlainObject(raw))
         return null;
     const id = typeof raw.id === 'string' ? raw.id.trim() : '';
     if (!SERVER_ID_PATTERN.test(id))
         return null;
-    const transport = typeof raw.transport === 'string' ? raw.transport : 'stdio';
+    // Absence preserves the legacy stdio default; a supplied invalid discriminator must not
+    // silently select a different transport or authentication policy.
+    if (raw.transport !== undefined && typeof raw.transport !== 'string')
+        return null;
+    const transport = raw.transport === undefined ? 'stdio' : raw.transport;
     if (!VALID_TRANSPORTS.has(transport))
         return null;
+    if (raw.authMode !== undefined && sanitizeMcpAuthMode(raw.authMode) === undefined)
+        return null;
     const next = {
         id,
         transport,
@@ -160,7 +183,7 @@ export function sanitizeMcpServer(raw) {
         if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
             return null;
         next.url = parsed.toString();
-        next.authMode = sanitizeMcpAuthMode(raw.authMode) ?? inferMcpAuthModeForUrl(next.url);
+        next.authMode = sanitizeMcpAuthMode(raw.authMode) ?? inferMcpAuthModeForUrl({ rawUrl: next.url });
         const headers = sanitizeStringMap(raw.headers);
         if (headers)
             next.headers = headers;
@@ -174,14 +197,14 @@ export function sanitizeMcpServer(raw) {
  * @param raw The raw parsed JSON to sanitize.
  * @returns A clean `McpConfig` guaranteed to have only valid, unique server entries.
  */
-export function sanitizeMcpConfig(raw) {
+export function sanitizeMcpConfig({ raw }) {
     if (!isPlainObject(raw))
         return { servers: [] };
     const list = Array.isArray(raw.servers) ? raw.servers : [];
     const seen = new Set();
     const out = [];
     for (const entry of list) {
-        const ok = sanitizeMcpServer(entry);
+        const ok = sanitizeMcpServer({ raw: entry });
         if (!ok)
             continue;
         if (seen.has(ok.id))
@@ -197,11 +220,11 @@ export function sanitizeMcpConfig(raw) {
  * @param dataDir The resolved runtime data directory.
  * @returns The sanitized `McpConfig`, never rejects on missing-file or corrupt-JSON.
  */
-export async function readMcpConfig(dataDir) {
+export async function readMcpConfig({ dataDir }, { filesystem = defaultFilesystem } = {}) {
     try {
-        const raw = await readFile(configFile(dataDir), 'utf8');
+        const raw = await filesystem.readText({ filePath: configFile(dataDir) });
         const parsed = JSON.parse(raw);
-        return sanitizeMcpConfig(parsed);
+        return sanitizeMcpConfig({ raw: parsed });
     }
     catch (err) {
         const e = err;
@@ -222,15 +245,15 @@ const writeLocks = new Map();
  * being written. This file may carry environment variables and
  * `Authorization` header values (API keys, bearer tokens — see
  * `McpServerConfig.env`/`.headers`), so it is written with owner-only
- * (0600) permissions from the very first byte via `writeSecretFileAtomic`
+ * (0600) permissions from the very first byte via `writeFileAtomicAsync`
  * rather than a post-rename chmod (CR-006 / SEC-RB-002).
  * @param dataDir The resolved runtime data directory.
  * @param body The raw config body to sanitize and persist.
  * @returns The sanitized `McpConfig` that was written to disk.
  */
-export async function writeMcpConfig(dataDir, body) {
+export async function writeMcpConfig({ dataDir, body }, { filesystem = defaultFilesystem } = {}) {
     const prev = writeLocks.get(dataDir) ?? Promise.resolve();
-    const task = prev.catch(() => { }).then(() => doWrite(dataDir, body));
+    const task = prev.catch(() => { }).then(() => doWrite(dataDir, body, filesystem));
     writeLocks.set(dataDir, task);
     try {
         return await task;
@@ -240,9 +263,9 @@ export async function writeMcpConfig(dataDir, body) {
             writeLocks.delete(dataDir);
     }
 }
-async function doWrite(dataDir, body) {
-    const next = sanitizeMcpConfig(body);
-    await writeSecretFileAtomic(configFile(dataDir), JSON.stringify(next, null, 2));
+async function doWrite(dataDir, body, filesystem) {
+    const next = sanitizeMcpConfig({ raw: body });
+    await filesystem.writeSecretText({ filePath: configFile(dataDir), contents: JSON.stringify(next, null, 2) });
     return next;
 }
 // ───────────────────────────────────────────────────────────────────────
@@ -253,7 +276,7 @@ async function doWrite(dataDir, body) {
  * falls back to lexical `path.resolve` (still normalizing `..`/`.`
  * segments) when it does not exist yet, or the platform can't resolve it.
  */
-function resolveRealOrLexical(p) {
+function resolveRealOrLexical({ filePath: p }) {
     try {
         return realpathSync.native(p);
     }
@@ -271,20 +294,20 @@ function resolveRealOrLexical(p) {
  * Both `cwd` and `projectsDir` are realpath-resolved before the containment
  * check (falling back to lexical `path.resolve` normalization for a path
  * that doesn't exist on disk yet), and containment is decided with
- * `@jini-ai/platform`'s separator-aware `pathContains` rather than a raw
+ * `@jini-ai/core/primitives`' separator-aware `pathContains` rather than a raw
  * string-prefix check — a `..`-containing path or a symlinked descendant
  * can defeat a plain `startsWith` (CR-006 / SEC-RB-011).
  */
-export function isManagedProjectCwd(cwd, projectsDir) {
+export function isManagedProjectCwd({ cwd, projectsDir }, { resolvePath = resolveRealOrLexical } = {}) {
     if (!cwd || typeof cwd !== 'string')
         return false;
     if (typeof projectsDir !== 'string' || projectsDir.length === 0)
         return false;
-    const resolvedProjectsDir = resolveRealOrLexical(projectsDir);
-    const resolvedCwd = resolveRealOrLexical(cwd);
+    const resolvedProjectsDir = resolvePath({ filePath: projectsDir });
+    const resolvedCwd = resolvePath({ filePath: cwd });
     if (resolvedCwd === resolvedProjectsDir)
         return false; // projects root, not a project
-    return pathContains(resolvedProjectsDir, resolvedCwd);
+    return pathContains({ root: resolvedProjectsDir, target: resolvedCwd }, { caseSensitive: path.sep !== '\\', separator: path.sep === '\\' ? '\\' : '/' });
 }
 /**
  * Project-cwd `.mcp.json` shape that Claude Code auto-loads on spawn (the
@@ -300,7 +323,7 @@ export function isManagedProjectCwd(cwd, projectsDir) {
  * pre-authenticated credentials. User-supplied headers always win on
  * conflict so they can pin a specific token if they really want to.
  */
-export function buildClaudeMcpJson(servers, tokens = {}) {
+export function buildClaudeMcpJson({ servers }, { tokens = {} } = {}) {
     const enabled = servers.filter((s) => s.enabled);
     if (enabled.length === 0)
         return null;
@@ -361,7 +384,7 @@ function mergeAuthHeader(existing, bearer) {
  * @param servers The full server list from `McpConfig`.
  * @returns ACP-shaped server entries for all enabled stdio servers.
  */
-export function buildAcpMcpServers(servers) {
+export function buildAcpMcpServers({ servers }) {
     const enabled = servers.filter((s) => s.enabled && s.transport === 'stdio');
     const out = [];
     for (const s of enabled) {
@@ -383,7 +406,12 @@ export function buildAcpMcpServers(servers) {
     }
     return out;
 }
-export function buildOpenCodeMcpConfigContent(servers, tokens = {}, options = {}) {
+export function buildOpenCodeMcpConfigContent({ servers }, options = {}) {
+    const tokens = options.tokens ?? {};
+    const resolvePath = options.resolvePath ?? (({ filePath }) => realpathSync.native(filePath));
+    return buildOpenCodeContent(servers, tokens, options, resolvePath);
+}
+function buildOpenCodeContent(servers, tokens, options, resolvePath) {
     const enabled = servers.filter((s) => s.enabled);
     const mcp = {};
     for (const s of enabled) {
@@ -416,7 +444,7 @@ export function buildOpenCodeMcpConfigContent(servers, tokens = {}, options = {}
             mcp[s.id] = entry;
         }
     }
-    const externalDirectory = buildOpenCodeExternalDirectoryAllowlist(options.allowedDirectories);
+    const externalDirectory = buildOpenCodeExternalDirectoryAllowlist(options.allowedDirectories, resolvePath);
     const extraConfig = options.extraConfig ?? {};
     if (Object.keys(mcp).length === 0 &&
         !externalDirectory &&
@@ -436,11 +464,11 @@ export function buildOpenCodeMcpConfigContent(servers, tokens = {}, options = {}
     }
     return JSON.stringify(config);
 }
-function buildOpenCodeExternalDirectoryAllowlist(directories) {
+function buildOpenCodeExternalDirectoryAllowlist(directories, resolvePath) {
     const normalized = Array.from(new Set((directories ?? [])
         .filter((dir) => typeof dir === 'string' && dir.trim().length > 0)
         .filter((dir) => path.isAbsolute(dir))
-        .flatMap((dir) => normalizeAllowedDirectoryVariants(dir))));
+        .flatMap((dir) => normalizeAllowedDirectoryVariants(dir, resolvePath))));
     if (normalized.length === 0)
         return null;
     const allowlist = {};
@@ -458,11 +486,11 @@ function normalizeAllowedDirectory(dir) {
         return root;
     return resolved.replace(/[\\/]+$/, '');
 }
-function normalizeAllowedDirectoryVariants(dir) {
+function normalizeAllowedDirectoryVariants(dir, resolvePath) {
     const normalized = normalizeAllowedDirectory(dir);
     let real = null;
     try {
-        real = normalizeAllowedDirectory(realpathSync.native(dir));
+        real = normalizeAllowedDirectory(resolvePath({ filePath: dir }));
     }
     catch {
         real = null;

package/dist/core/index.d.ts

@@ -1,14 +1,13 @@
 /**
  * @module @jini-ai/mcp/core
  * Foundation kernel for the MCP domain: the shared config schema and IO
- * (`config`), the OAuth 2.1 / PKCE client-credential flow (`oauth`), the
+ * (`config`), the
  * per-server token store (`tokens`), and the install-payload builder
  * (`install-info`). These are the pure, dependency-light primitives every other
  * MCP concern (client, agent-install) and the daemon's routes and runtime build
  * on. `core` imports no sibling subdirectory.
  */
 export * from './config.js';
-export * from './oauth.js';
 export * from './tokens.js';
 export * from './install-info.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/index.js

@@ -1,14 +1,13 @@
 /**
  * @module @jini-ai/mcp/core
  * Foundation kernel for the MCP domain: the shared config schema and IO
- * (`config`), the OAuth 2.1 / PKCE client-credential flow (`oauth`), the
+ * (`config`), the
  * per-server token store (`tokens`), and the install-payload builder
  * (`install-info`). These are the pure, dependency-light primitives every other
  * MCP concern (client, agent-install) and the daemon's routes and runtime build
  * on. `core` imports no sibling subdirectory.
  */
 export * from './config.js';
-export * from './oauth.js';
 export * from './tokens.js';
 export * from './install-info.js';
 //# sourceMappingURL=index.js.map

package/dist/core/install-info.d.ts

@@ -32,6 +32,9 @@ export interface BuildMcpInstallPayloadInputs {
      *  propagated into the snippet. The caller decides what's worth
      *  propagating; this builder just merges. */
     sidecarEnv: Record<string, string>;
+}
+/** Optional launch settings, separated from required runtime facts. */
+export interface BuildMcpInstallPayloadOptions {
     /** Browser-facing base URL (e.g. `http://127.0.0.1:65321`). Used by MCP
      *  clients to build deep links so the outer agent can suggest a URL. Null
      *  when the daemon was launched without a known web port (headless). */
@@ -65,5 +68,5 @@ export interface McpInstallPayload {
  * @param inputs Runtime facts collected by the production route or test fixture.
  * @returns The install payload; `buildHint` is non-null when prerequisites are missing.
  */
-export declare function buildMcpInstallPayload(inputs: BuildMcpInstallPayloadInputs): McpInstallPayload;
+export declare function buildMcpInstallPayload(inputs: BuildMcpInstallPayloadInputs, options?: BuildMcpInstallPayloadOptions): McpInstallPayload;
 //# sourceMappingURL=install-info.d.ts.map

package/dist/core/install-info.js

@@ -25,8 +25,8 @@
  * @param inputs Runtime facts collected by the production route or test fixture.
  * @returns The install payload; `buildHint` is non-null when prerequisites are missing.
  */
-export function buildMcpInstallPayload(inputs) {
-    const subcommand = inputs.subcommand ?? 'mcp';
+export function buildMcpInstallPayload(inputs, options = {}) {
+    const subcommand = options.subcommand ?? 'mcp';
     const hints = [];
     if (!inputs.cliExists) {
         hints.push(`CLI entry is missing at ${inputs.cliPath}. Rebuild the daemon or packaged app and refresh.`);
@@ -41,8 +41,8 @@ export function buildMcpInstallPayload(inputs) {
     // per-cwd data dir which for packaged installs can be a read-only app
     // bundle that trips EPERM.
     const env = {
-        [inputs.dataDirEnvVar]: inputs.dataDir,
         ...inputs.sidecarEnv,
+        [inputs.dataDirEnvVar]: inputs.dataDir,
     };
     if (inputs.electronAsNode) {
         env.ELECTRON_RUN_AS_NODE = '1';
@@ -64,8 +64,8 @@ export function buildMcpInstallPayload(inputs) {
         args,
         env,
         daemonUrl: `http://127.0.0.1:${inputs.port}`,
-        webBaseUrl: typeof inputs.webBaseUrl === 'string' && inputs.webBaseUrl.length > 0
-            ? inputs.webBaseUrl
+        webBaseUrl: typeof options.webBaseUrl === 'string' && options.webBaseUrl.length > 0
+            ? options.webBaseUrl
             : null,
         // Surface platform so the install panel can localize path hints
         // (~/.cursor vs %USERPROFILE%\.cursor) and keyboard shortcuts

package/dist/core/tokens.d.ts

@@ -1,9 +1,5 @@
-/**
- * @module @jini-ai/mcp/core/tokens
- * Persistent, 0600-guarded OAuth-token store for remote MCP servers, keyed by
- * server id, with expiry checks. The durable counterpart to `oauth`'s live flow.
- * Part of the MCP `core` kernel; depends on no sibling subdirectory.
- */
+import { type Clock } from "@jini-ai/core/primitives";
+import type { McpConfigFilesystemPort } from './config.js';
 /**
  * Stored OAuth token for a single MCP server. Mirrors the relevant subset
  * of an OAuth 2.0 token-endpoint response (RFC 6749 §5.1), plus the OAuth
@@ -44,29 +40,59 @@ export interface McpTokensFile {
     /** keyed by McpServerConfig.id */
     servers: Record<string, StoredMcpToken>;
 }
+/** Optional clock used when imported tokens have no saved timestamp. */
+export interface McpTokenClockOptions {
+    clock?: Clock;
+}
+/** Injectable store boundaries; defaults use the Node filesystem and wall clock. */
+export interface McpTokenStoreOptions extends McpTokenClockOptions {
+    filesystem?: McpConfigFilesystemPort;
+}
 /** Coerce a freeform JSON blob into the typed shape, dropping anything that
  * doesn't deserialize cleanly. Used both at read time and as a defensive
  * pass when third-party tooling has hand-edited the file. */
-export declare function sanitizeTokensFile(raw: unknown): McpTokensFile;
+export declare function sanitizeTokensFile({ raw }: {
+    raw: unknown;
+}, { clock }?: McpTokenClockOptions): McpTokensFile;
 /**
  * Read and sanitize the MCP token store from `<dataDir>/mcp-tokens.json`.
  * Returns an empty store when the file does not exist or contains invalid JSON.
  * @param dataDir The resolved runtime data directory.
  * @returns The sanitized token file, never rejects on missing-file or corrupt-JSON.
  */
-export declare function readTokensFile(dataDir: string): Promise<McpTokensFile>;
+export declare function readTokensFile({ dataDir }: {
+    dataDir: string;
+}, options?: McpTokenStoreOptions): Promise<McpTokensFile>;
 /** Get the current token for a given server, or null when none is stored
  * (or the persisted entry is malformed). */
-export declare function getToken(dataDir: string, serverId: string): Promise<StoredMcpToken | null>;
+export declare function getToken({ dataDir, serverId }: {
+    dataDir: string;
+    serverId: string;
+}, options?: McpTokenStoreOptions): Promise<StoredMcpToken | null>;
 /** Atomically merge a new token for `serverId` into the tokens file. */
-export declare function setToken(dataDir: string, serverId: string, token: StoredMcpToken): Promise<void>;
+export declare function setToken({ dataDir, serverId, token }: {
+    dataDir: string;
+    serverId: string;
+    token: StoredMcpToken;
+}, options?: McpTokenStoreOptions): Promise<void>;
 /** Atomically delete the stored token for `serverId`. No-op when absent. */
-export declare function clearToken(dataDir: string, serverId: string): Promise<void>;
+export declare function clearToken({ dataDir, serverId }: {
+    dataDir: string;
+    serverId: string;
+}, options?: McpTokenStoreOptions): Promise<void>;
 /** Bulk read used by the spawn pipeline so we make one disk hit per spawn,
  * not one per server. */
-export declare function readAllTokens(dataDir: string): Promise<Record<string, StoredMcpToken>>;
+export declare function readAllTokens({ dataDir }: {
+    dataDir: string;
+}, options?: McpTokenStoreOptions): Promise<Record<string, StoredMcpToken>>;
 /** True when the stored token is past its `expiresAt` (or within `skew`
  * milliseconds of expiring). Returns false when no `expiresAt` is recorded
  * — many providers issue non-expiring tokens. */
-export declare function isTokenExpired(token: StoredMcpToken, now?: number, skew?: number): boolean;
+export declare function isTokenExpired({ token }: {
+    token: StoredMcpToken;
+}, { clock, now, skew }?: {
+    clock?: Clock;
+    now?: number;
+    skew?: number;
+}): boolean;
 //# sourceMappingURL=tokens.d.ts.map

package/dist/core/tokens.js

@@ -1,3 +1,4 @@
+import { createSystemClock } from "@jini-ai/core/primitives";
 /**
  * @module @jini-ai/mcp/core/tokens
  * Persistent, 0600-guarded OAuth-token store for remote MCP servers, keyed by
@@ -13,18 +14,47 @@
 // atomic write + per-dataDir mutex pattern the rest of the runtime uses.
 //
 // File mode: owner-only (0600) from the very first byte, via
-// `writeSecretFileAtomic` (CR-006 / SEC-RB-002) — NOT a post-rename chmod.
+// `writeFileAtomicAsync` (CR-006 / SEC-RB-002) — NOT a post-rename chmod.
 // The previous chmod-after-rename approach left a window where the file
 // briefly existed with default (potentially world/group-readable)
 // permissions, and silently continued persisting the token when chmod
 // failed for any reason other than ENOTSUP/EPERM, which is not a
-// fail-closed guarantee. `writeSecretFileAtomic` creates the file with mode
+// fail-closed guarantee. `writeFileAtomicAsync` creates the file with mode
 // 0600 atomically at creation and fails closed (removing the temp file and
 // throwing) if a POSIX platform did not honor that mode; it skips
 // verification on `win32`, which has no POSIX permission-bit model.
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
-import { writeSecretFileAtomic } from './secure-write.js';
+import { writeFileAtomicAsync } from '@jini-ai/platform/fs';
+/** Shared atomic secret persistence (CR-006 / SEC-RB-002).
+ * The previous pattern in each of those stores wrote the temp file with
+ * default permissions and either never restricted it (config, OAuth client
+ * cache) or `chmod(0600)`'d it *after* the atomic rename and silently
+ * continued when the chmod failed (tokens) — both leave a window where the
+ * file exists world/group-readable, and the latter makes the "protection"
+ * advisory rather than enforced. The platform writer instead:
+ *
+ *   1. Creates the temp file *exclusively* (`wx`) with mode 0600 supplied to
+ *      the same `open()`/`writeFile()` call that creates it — POSIX applies
+ *      the requested mode atomically at creation time, so there is no
+ *      window where the file exists with a broader mode. Creation-mode enforcement
+ *      follows the existing prompt-file precedent; the shared writer also reapplies
+ *      0600 before checking the mode and flushing the file, never after rename.
+ *   2. On POSIX platforms, verifies the on-disk mode actually landed as
+ *      owner-only before renaming into place, and fails closed — removing
+ *      the temp file and throwing — if it did not (e.g. an unusual umask or
+ *      a filesystem that doesn't honor `mode`).
+ *   3. Skips that verification on `win32`: Windows has no POSIX permission-
+ *      bit model (`mode` there only toggles the read-only attribute), so
+ *      there is nothing meaningful to enforce or fail closed on.
+ *   4. Flushes file content before rename and the parent directory after it. A directory
+ *      flush can fail after replacement; it is reported rather than silently ignored.
+ *
+ */
+const defaultFilesystem = {
+    readText: ({ filePath }) => readFile(filePath, 'utf8'),
+    writeSecretText: ({ filePath, contents }) => writeFileAtomicAsync({ filePath, content: contents }, { mode: 0o600, verifyOwnerOnly: true, createParent: true }),
+};
 const EMPTY = { servers: {} };
 function tokensFile(dataDir) {
     return path.join(dataDir, 'mcp-tokens.json');
@@ -35,7 +65,7 @@ function isPlainObject(v) {
 /** Coerce a freeform JSON blob into the typed shape, dropping anything that
  * doesn't deserialize cleanly. Used both at read time and as a defensive
  * pass when third-party tooling has hand-edited the file. */
-export function sanitizeTokensFile(raw) {
+export function sanitizeTokensFile({ raw }, { clock = createSystemClock() } = {}) {
     if (!isPlainObject(raw))
         return { servers: {} };
     const servers = raw.servers;
@@ -45,14 +75,14 @@ export function sanitizeTokensFile(raw) {
     for (const [id, value] of Object.entries(servers)) {
         if (id === '__proto__' || id === 'constructor')
             continue;
-        const tok = sanitizeToken(value);
+        const tok = sanitizeToken(value, clock);
         if (!tok)
             continue;
         out[id] = tok;
     }
     return { servers: out };
 }
-function sanitizeToken(raw) {
+function sanitizeToken(raw, clock) {
     if (!isPlainObject(raw))
         return null;
     const accessToken = typeof raw.accessToken === 'string' ? raw.accessToken.trim() : '';
@@ -72,7 +102,7 @@ function sanitizeToken(raw) {
         : undefined;
     const savedAt = typeof raw.savedAt === 'number' && Number.isFinite(raw.savedAt)
         ? raw.savedAt
-        : Date.now();
+        : clock.nowMs();
     const tokenEndpoint = typeof raw.tokenEndpoint === 'string' && raw.tokenEndpoint.trim()
         ? raw.tokenEndpoint.trim()
         : undefined;
@@ -118,10 +148,10 @@ function sanitizeToken(raw) {
  * @param dataDir The resolved runtime data directory.
  * @returns The sanitized token file, never rejects on missing-file or corrupt-JSON.
  */
-export async function readTokensFile(dataDir) {
+export async function readTokensFile({ dataDir }, options = {}) {
     try {
-        const raw = await readFile(tokensFile(dataDir), 'utf8');
-        return sanitizeTokensFile(JSON.parse(raw));
+        const raw = await (options.filesystem ?? defaultFilesystem).readText({ filePath: tokensFile(dataDir) });
+        return sanitizeTokensFile({ raw: JSON.parse(raw) }, options);
     }
     catch (err) {
         const e = err;
@@ -147,49 +177,49 @@ async function withLock(dataDir, fn) {
             writeLocks.delete(dataDir);
     }
 }
-async function writeTokensFile(dataDir, next) {
+async function writeTokensFile(dataDir, next, options) {
     const file = tokensFile(dataDir);
     // Bearer tokens can hand someone posting-as-you against the upstream MCP,
     // so the file is created with owner-only (0600) permissions from the
     // first byte and the write fails closed if that can't be guaranteed on a
-    // POSIX platform — see `writeSecretFileAtomic`.
-    await writeSecretFileAtomic(file, JSON.stringify(next, null, 2));
+    // POSIX platform — see `writeFileAtomicAsync`.
+    await (options.filesystem ?? defaultFilesystem).writeSecretText({ filePath: file, contents: JSON.stringify(next, null, 2) });
     return next;
 }
 /** Get the current token for a given server, or null when none is stored
  * (or the persisted entry is malformed). */
-export async function getToken(dataDir, serverId) {
-    const file = await readTokensFile(dataDir);
+export async function getToken({ dataDir, serverId }, options = {}) {
+    const file = await readTokensFile({ dataDir }, options);
     return file.servers[serverId] ?? null;
 }
 /** Atomically merge a new token for `serverId` into the tokens file. */
-export async function setToken(dataDir, serverId, token) {
+export async function setToken({ dataDir, serverId, token }, options = {}) {
     await withLock(dataDir, async () => {
-        const file = await readTokensFile(dataDir);
+        const file = await readTokensFile({ dataDir }, options);
         file.servers[serverId] = token;
-        await writeTokensFile(dataDir, file);
+        await writeTokensFile(dataDir, file, options);
     });
 }
 /** Atomically delete the stored token for `serverId`. No-op when absent. */
-export async function clearToken(dataDir, serverId) {
+export async function clearToken({ dataDir, serverId }, options = {}) {
     await withLock(dataDir, async () => {
-        const file = await readTokensFile(dataDir);
+        const file = await readTokensFile({ dataDir }, options);
         if (!(serverId in file.servers))
             return;
         delete file.servers[serverId];
-        await writeTokensFile(dataDir, file);
+        await writeTokensFile(dataDir, file, options);
     });
 }
 /** Bulk read used by the spawn pipeline so we make one disk hit per spawn,
  * not one per server. */
-export async function readAllTokens(dataDir) {
-    const file = await readTokensFile(dataDir);
+export async function readAllTokens({ dataDir }, options = {}) {
+    const file = await readTokensFile({ dataDir }, options);
     return file.servers;
 }
 /** True when the stored token is past its `expiresAt` (or within `skew`
  * milliseconds of expiring). Returns false when no `expiresAt` is recorded
  * — many providers issue non-expiring tokens. */
-export function isTokenExpired(token, now = Date.now(), skew = 30_000) {
+export function isTokenExpired({ token }, { clock = createSystemClock(), now = clock.nowMs(), skew = 30_000 } = {}) {
     if (typeof token.expiresAt !== 'number')
         return false;
     return token.expiresAt - skew <= now;