@xiashe/sdk 0.1.36 → 0.1.38

package/http.mjs

@@ -0,0 +1,37 @@
+const MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
+export function requestUrl(value) {
+  const url = new URL(value);
+  const loopback = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+  if ((url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback)) || url.username || url.password || url.hash) throw Error('HTTP_TARGET_INVALID');
+  return url;
+}
+export async function boundedJsonRequest(url, body, { timeoutMs = 20000, headers = {}, maxResponseBytes = MAX_RESPONSE_BYTES, method = 'POST' } = {}) {
+  requestUrl(url);
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || !Number.isSafeInteger(maxResponseBytes) || maxResponseBytes <= 0) throw Error('HTTP_LIMIT_INVALID');
+  const controller = new AbortController();
+  let timer;
+  const deadline = new Promise((_, reject) => { timer = setTimeout(() => { controller.abort(); reject(Error('REQUEST_TIMEOUT')); }, timeoutMs); });
+  const request = async () => {
+    const response = await fetch(url, { method, redirect: 'error', signal: controller.signal,
+      headers: { 'content-type': 'application/json', ...headers }, ...(method === 'GET' ? {} : { body: JSON.stringify(body ?? {}) }) });
+    if (response.status >= 300 && response.status < 400) throw Error('HTTP_REDIRECT_REFUSED');
+    if (Number(response.headers.get('content-length')) > maxResponseBytes) { controller.abort(); throw Error('HTTP_RESPONSE_TOO_LARGE'); }
+    const reader = response.body?.getReader();
+    const chunks = []; let total = 0;
+    try {
+      if (reader) while (true) {
+        const { done, value } = await reader.read(); if (done) break;
+        total += value.byteLength;
+        if (total > maxResponseBytes) { controller.abort(); throw Error('HTTP_RESPONSE_TOO_LARGE'); }
+        chunks.push(Buffer.from(value));
+      }
+    } finally { reader?.releaseLock(); }
+    let payload;
+    try { const text = Buffer.concat(chunks).toString('utf8'); payload = text ? JSON.parse(text) : {}; }
+    catch { throw Error('HTTP_BAD_JSON'); }
+    return { response, payload };
+  };
+  try { return await Promise.race([request(), deadline]); }
+  catch (error) { if (controller.signal.aborted && error.message !== 'HTTP_RESPONSE_TOO_LARGE') throw Error('REQUEST_TIMEOUT'); throw error; }
+  finally { clearTimeout(timer); }
+}

package/index.mjs

@@ -1,3 +1,5 @@
+import { privateDirectory, checkPrivateFile, withPrivateLock, atomicPrivateJson } from './privateState.mjs';
+import { boundedJsonRequest } from './http.mjs';
 import { createHash, randomUUID } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import { mkdir, readFile, writeFile, stat } from 'node:fs/promises';
@@ -5,7 +7,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { ConvexHttpClient } from 'convex/browser';
 import { anyApi as api } from 'convex/server';
-export { installRuntimePackage, runtimePrincipal, writeRuntimeRecord } from './runtime.mjs';
+export { verifyDirectory as verifyRuntimePackageDirectory, inspectRuntimeArchive, installRuntimePackage, runtimePrincipal, writeRuntimeRecord } from './runtime.mjs';
 export { reportRuntimeResult, retryRuntimeResults } from './runtimeOutbox.mjs';
 export { runRuntimeScript } from './runtimeScript.mjs';
 export { serveRuntimeScriptHost, retryRuntimeHostResults } from './runtimeHost.mjs';
@@ -13,7 +15,9 @@ export { createRuntimeAgentHost } from './runtimeAgentHost.mjs';
 export { createRuntimeAgentSession } from './runtimeAgent.mjs';
 export { serveRuntimeMcp } from './runtimeMcp.mjs';
 
-export const VERSION = '0.1.36';
+export { safeOutput as redactCredentials } from './outputSafety.mjs';
+
+export const VERSION = '0.1.38';
 export { probeRuntimeGateway, runtimeSetupTemplate } from './runtimeSetup.mjs';
 
 export const DEFAULTS = {
@@ -121,6 +125,8 @@ export async function readConfig() {
   if (!existsSync(CONFIG_PATH)) {
     return freshConfig();
   }
+  await privateDirectory(path.dirname(CONFIG_PATH));
+  await checkPrivateFile(CONFIG_PATH);
   const raw = await readFile(CONFIG_PATH, 'utf8');
   try {
     const parsed = JSON.parse(raw);
@@ -139,14 +145,21 @@ export async function readConfig() {
       profiles
     };
   } catch (error) {
-    throw new XiasheError(`Invalid ${DEFAULT_PRODUCT_NAME} config JSON at ${CONFIG_PATH}`, { code: 'CONFIG_INVALID_JSON', details: error });
+    throw new XiasheError(`Invalid ${DEFAULT_PRODUCT_NAME} config JSON at ${CONFIG_PATH}`, { code: 'CONFIG_INVALID_JSON' });
   }
 }
 
+async function mutateConfig(operation) {
+  await privateDirectory(path.dirname(CONFIG_PATH));
+  return withPrivateLock(CONFIG_PATH, async () => {
+    const config = await readConfig();
+    await operation(config);
+    await atomicPrivateJson(CONFIG_PATH, config);
+    return config;
+  });
+}
 export async function writeConfig(config) {
-  await mkdir(CONFIG_DIR, { recursive: true, mode: 0o700 });
-  await writeFile(CONFIG_PATH, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
-  return config;
+  return mutateConfig(current => { for (const key of Object.keys(current)) delete current[key]; Object.assign(current, config); });
 }
 
 export async function getProfile(name) {
@@ -162,28 +175,40 @@ export async function getProfile(name) {
   };
 }
 
-export async function updateProfile(name, patch) {
-  const config = await readConfig();
-  const profileName = name || config.profile || DEFAULT_PROFILE;
-  config.profiles = config.profiles || {};
-  config.profiles[profileName] = {
-    ...(config.profiles[profileName] || {}),
-    ...patch,
-    name: profileName
+const endpointKeys = ['convexUrl', 'actionsUrl', 'mcpUrl', 'agentClaimUrl', 'relayUrl'];
+function environmentBinding(profile) {
+  const actions = normalizeBaseUrl(profile.actionsUrl);
+  const endpoints = {
+    ...profile,
+    mcpUrl: profile.mcpUrl || (actions ? `${actions}/mcp/xiashe` : ''),
+    agentClaimUrl: profile.agentClaimUrl || (actions ? `${actions}/agent-gateway/claim` : ''),
   };
-  return writeConfig(config);
+  return Object.fromEntries(endpointKeys.map(key => [key, normalizeBaseUrl(endpoints[key])]));
 }
 
+function sameEnvironment(left, right) {
+  const a = environmentBinding(left || {}), b = environmentBinding(right || {});
+  return endpointKeys.every(key => a[key] === b[key]);
+}
+export async function updateProfile(name, patch) {
+  return mutateConfig(config => {
+    const profileName = name || config.profile || DEFAULT_PROFILE;
+    const previous = { ...freshConfig().profiles[DEFAULT_PROFILE], ...(config.profiles[profileName] || {}) };
+    const next = { ...previous, ...patch, name: profileName };
+    if (!sameEnvironment(previous, next)) { delete next.session; delete next.agent; }
+    config.profiles[profileName] = next;
+  });
+}
 export async function useProfile(name) {
-  const config = await readConfig();
-  config.profile = name || DEFAULT_PROFILE;
-  config.profiles = config.profiles || {};
-  config.profiles[config.profile] = config.profiles[config.profile] || { name: config.profile };
-  return writeConfig(config);
+  return mutateConfig(config => {
+    config.profile = name || DEFAULT_PROFILE;
+    config.profiles[config.profile] ||= { name: config.profile };
+  });
 }
 
 export async function useEnvironment(envName, profileName) {
   const normalized = String(envName || '').toLowerCase();
+  if (!['cn', 'global', 'intl'].includes(normalized)) throw Error('ENVIRONMENT_INVALID');
   const defaults = normalized === 'global' || normalized === 'intl' ? DEFAULTS.global : DEFAULTS.cn;
   await updateProfile(profileName, {
     market: defaults.market,
@@ -200,10 +225,11 @@ export async function useEnvironment(envName, profileName) {
 function envProfile(profile) {
   const defaults = DEFAULTS[DEFAULT_ENV];
   const actionsUrl = normalizeBaseUrl(process.env.XIASHE_ACTIONS_URL || process.env.AGENTPIE_ACTIONS_URL || profile.actionsUrl);
-  const mcpUrl = process.env.XIASHE_MCP_URL || process.env.AGENTPIE_MCP_URL || (actionsUrl ? `${actionsUrl}/mcp/xiashe` : profile.mcpUrl);
+  const changedActions = process.env.XIASHE_ACTIONS_URL || process.env.AGENTPIE_ACTIONS_URL;
+  const mcpUrl = process.env.XIASHE_MCP_URL || process.env.AGENTPIE_MCP_URL || (!changedActions && profile.mcpUrl) || (actionsUrl ? `${actionsUrl}/mcp/xiashe` : undefined);
   const agentClaimUrl =
-    process.env.XIASHE_AGENT_CLAIM_URL || process.env.AGENTPIE_AGENT_CLAIM_URL || (actionsUrl ? `${actionsUrl}/agent-gateway/claim` : profile.agentClaimUrl);
-  return {
+    process.env.XIASHE_AGENT_CLAIM_URL || process.env.AGENTPIE_AGENT_CLAIM_URL || (!changedActions && profile.agentClaimUrl) || (actionsUrl ? `${actionsUrl}/agent-gateway/claim` : undefined);
+  const resolved = {
     ...profile,
     convexUrl: process.env.XIASHE_CONVEX_URL || process.env.AGENTPIE_CONVEX_URL || profile.convexUrl,
     actionsUrl,
@@ -212,24 +238,33 @@ function envProfile(profile) {
     relayUrl: process.env.XIASHE_RELAY_URL || process.env.AGENTPIE_RELAY_URL || profile.relayUrl,
     market: process.env.XIASHE_MARKET || process.env.AGENTPIE_MARKET || profile.market || defaults.market,
     locale: process.env.XIASHE_LOCALE || process.env.AGENTPIE_LOCALE || profile.locale || defaults.locale,
-    session: {
-      ...(profile.session || {}),
-      ...(process.env.XIASHE_USER_ID || process.env.XIASHE_SESSION_TOKEN
-        ? {
-            userId: process.env.XIASHE_USER_ID || profile.session?.userId,
-            sessionToken: process.env.XIASHE_SESSION_TOKEN || profile.session?.sessionToken
-          }
-        : {})
-    },
-    agent: {
-      ...(profile.agent || {}),
-      ...(process.env.XIASHE_RUNTIME_TOKEN
-        ? {
-            runtimeToken: process.env.XIASHE_RUNTIME_TOKEN
-          }
-        : {})
-    }
+    session: { ...(profile.session || {}) },
+    agent: { ...(profile.agent || {}) }
   };
+  for (const key of ['session', 'agent']) {
+    const binding = profile[key]?.environmentBinding || environmentBinding(profile);
+    if (!sameEnvironment(binding, resolved)) resolved[key] = {};
+    else if (Object.keys(resolved[key]).length) resolved[key].environmentBinding = binding;
+  }
+  const userId = process.env.XIASHE_USER_ID || process.env.AGENTPIE_USER_ID;
+  const sessionToken = process.env.XIASHE_SESSION_TOKEN || process.env.AGENTPIE_SESSION_TOKEN;
+  const runtimeToken = process.env.XIASHE_RUNTIME_TOKEN || process.env.AGENTPIE_RUNTIME_TOKEN;
+  let injectedBinding;
+  if (userId || sessionToken || runtimeToken) {
+    const issuer = process.env.XIASHE_AUTH_ENVIRONMENT || process.env.AGENTPIE_AUTH_ENVIRONMENT;
+    const rawBinding = process.env.XIASHE_AUTH_BINDING || process.env.AGENTPIE_AUTH_BINDING;
+    try { injectedBinding = rawBinding ? JSON.parse(rawBinding) : DEFAULTS[issuer === 'intl' ? 'global' : issuer]; }
+    catch { throw new XiasheError('Invalid environment credential binding.', { code: 'AUTH_ENVIRONMENT_MISMATCH' }); }
+    if (!injectedBinding || !sameEnvironment(injectedBinding, resolved))
+      throw new XiasheError('Environment credentials require a matching issuer binding. Set AUTH_ENVIRONMENT for this brand or authenticate again.', { code: 'AUTH_ENVIRONMENT_MISMATCH' });
+  }
+  if (userId || sessionToken) {
+    if (!userId || !sessionToken) throw new XiasheError('Environment authentication requires both user ID and session token.', { code: 'AUTH_ENV_INCOMPLETE' });
+    resolved.session = { userId, sessionToken, environmentBinding: environmentBinding(injectedBinding) };
+  }
+  if (runtimeToken) resolved.agent = { runtimeToken, environmentBinding: environmentBinding(injectedBinding) };
+
+  return resolved;
 }
 
 function normalizeConvexError(error) {
@@ -264,6 +299,9 @@ export async function loadProfile(options = {}) {
     profileName,
     profile: envProfile({
       ...profile,
+      // A legacy saved token has no verifiable issuer. Re-authenticate once.
+      session: profile.session?.environmentBinding ? profile.session : {},
+      agent: profile.agent?.environmentBinding ? profile.agent : {},
       ...cleanOptions
     })
   };
@@ -285,35 +323,13 @@ async function withTimeout(promiseFactory, timeoutMs = HTTP_TIMEOUT_MS) {
 }
 
 export async function postJson(url, body, options = {}) {
-  const timeoutMs = options.timeoutMs || HTTP_TIMEOUT_MS;
-  const headers = options.headers || {};
-  const response = await withTimeout(
-    (signal) =>
-      fetch(url, {
-        method: 'POST',
-        headers: {
-          'content-type': 'application/json',
-          ...headers
-        },
-        body: JSON.stringify(body ?? {}),
-        signal
-      }),
-    timeoutMs
-  );
-  const text = await response.text();
-  let payload = {};
-  try {
-    payload = text ? JSON.parse(text) : {};
-  } catch {
-    throw new XiasheError(`Bad JSON response from ${url}`, { code: 'HTTP_BAD_JSON', status: response.status });
-  }
-  if (!response.ok) {
-    throw new XiasheError(payload.error || payload.message || `HTTP ${response.status}`, {
-      code: payload.error || `HTTP_${response.status}`,
-      status: response.status,
-      details: payload
-    });
-  }
+  let result;
+  try { result = await boundedJsonRequest(url, body, options); }
+  catch (error) { throw new XiasheError(error.message, { code: error.message }); }
+  const { response, payload } = result;
+  if (!response.ok) throw new XiasheError(payload?.error || payload?.message || `HTTP ${response.status}`, {
+    code: payload?.error || `HTTP_${response.status}`, status: response.status
+  });
   return payload;
 }
 
@@ -381,6 +397,8 @@ export class XiasheClient {
   }
 
   authArgs(extra = {}) {
+    if (this.profile.session?.environmentBinding && !sameEnvironment(this.profile.session.environmentBinding, this.profile))
+      throw new XiasheError('Environment changed. Sign in again.', { code: 'AUTH_ENVIRONMENT_MISMATCH' });
     const userId = this.profile.session?.userId;
     const sessionToken = this.profile.session?.sessionToken;
     if (!userId || !sessionToken) {
@@ -455,10 +473,11 @@ export class XiasheClient {
   assertNumbersEnvironment() {
     const pairs = new Map([
       ['https://actions.xiashe.chat', 'https://api.xiashe.chat'],
-      ['https://actions.projectphenix.site', 'https://api.projectphenix.site']
+      ['https://actions.projectphenix.site', 'https://api.projectphenix.site'],
+      ['https://agentpie.app', DEFAULTS.global.convexUrl]
     ]);
     const actions = normalizeBaseUrl(this.profile.actionsUrl);
-    if (this.profile.market !== 'cn' || !pairs.has(actions) || pairs.get(actions) !== normalizeBaseUrl(this.profile.convexUrl)) {
+    if (this.profile.market !== (actions === 'https://agentpie.app' ? 'intl' : 'cn') || !pairs.has(actions) || pairs.get(actions) !== normalizeBaseUrl(this.profile.convexUrl)) {
       throw new XiasheError('Skill numbers require matching official XiaShe backend and actions URLs.', { code: 'NUMBER_ENVIRONMENT_INVALID' });
     }
   }
@@ -467,6 +486,10 @@ export class XiasheClient {
     this.assertNumbersEnvironment();
     return this.query(api.skillNumbers.resolve, { number: String(number) });
   }
+  async skillNumberAnalytics(number) {
+    this.assertNumbersEnvironment();
+    return this.query(api.skillNumbers.analytics, this.authArgs({ number: String(number) }));
+  }
   async acquireSkillNumber(number) {
     this.assertNumbersEnvironment();
     return this.mutation(api.skillNumbers.acquire, this.authArgs({ number: String(number) }));
@@ -1477,6 +1500,9 @@ export class XiasheClient {
 
   async agentRest(pathname, body = {}, options = {}) {
     const baseUrl = normalizeBaseUrl(options.restBaseUrl || this.profile.agent?.restBaseUrl || this.profile.actionsUrl);
+    if (!options.runtimeToken && (new URL(baseUrl).origin !== new URL(this.profile.actionsUrl).origin ||
+        (this.profile.agent?.environmentBinding && !sameEnvironment(this.profile.agent.environmentBinding, this.profile))))
+      throw new XiasheError('Environment changed. Reconnect the Agent.', { code: 'AUTH_ENVIRONMENT_MISMATCH' });
     const runtimeToken = options.runtimeToken || this.profile.agent?.runtimeToken;
     if (!runtimeToken) {
       throw new XiasheError('Missing Agent runtime token. Run `xiashe agent connect --token <token>` first.', {
@@ -1554,6 +1580,10 @@ export class XiasheClient {
   }
 
   async mcp(method, params = {}, options = {}) {
+    if (!options.runtimeToken && this.profile.agent?.runtimeToken &&
+        (normalizeBaseUrl(options.mcpUrl || this.profile.mcpUrl) !== normalizeBaseUrl(this.profile.mcpUrl) ||
+        !sameEnvironment(this.profile.agent.environmentBinding || this.profile, this.profile)))
+      throw new XiasheError('Environment changed. Reconnect the Agent.', { code: 'AUTH_ENVIRONMENT_MISMATCH' });
     return mcpCall(
       options.mcpUrl || this.profile.mcpUrl,
       options.runtimeToken || this.profile.agent?.runtimeToken || '',
@@ -1573,7 +1603,7 @@ export class XiasheClient {
   }
 }
 
-export async function saveLoginSession(profileName, authResult) {
+export async function saveLoginSession(profileName, authResult, authenticatedProfile) {
   const session = {
     userId: authResult.userId,
     email: authResult.email,
@@ -1582,11 +1612,13 @@ export async function saveLoginSession(profileName, authResult) {
     sessionExpiresAt: authResult.sessionExpiresAt,
     defaultChatId: authResult.defaultChatId || null
   };
+  const profile = authenticatedProfile || (await loadProfile({ profile: profileName })).profile;
+  session.environmentBinding = environmentBinding(profile);
   await updateProfile(profileName, { session });
   return session;
 }
 
-export async function saveAgentSession(profileName, claimResult) {
+export async function saveAgentSession(profileName, claimResult, authenticatedProfile) {
   const agent = {
     runtimeToken: claimResult.runtimeToken,
     agentConnectionId: claimResult.agentConnectionId,
@@ -1598,6 +1630,10 @@ export async function saveAgentSession(profileName, claimResult) {
     restBaseUrl: claimResult.restBaseUrl,
     expiresAt: claimResult.expiresAt
   };
+  const profile = authenticatedProfile || (await loadProfile({ profile: profileName })).profile;
+  agent.environmentBinding = environmentBinding(profile);
+  if (agent.mcpUrl && new URL(agent.mcpUrl).origin !== new URL(profile.mcpUrl).origin) throw Error('AGENT_ENVIRONMENT_MISMATCH');
+  if (agent.restBaseUrl && new URL(agent.restBaseUrl).origin !== new URL(profile.actionsUrl).origin) throw Error('AGENT_ENVIRONMENT_MISMATCH');
   await updateProfile(profileName, { agent });
   return agent;
 }

package/outputSafety.mjs

@@ -0,0 +1,21 @@
+// Output-only filtering. Never transform source files or generated Skill content.
+const secrets = new Set();
+const credentialKey = key => /(?:token|secret|password|authorization|cookie|apikey|uploadurl|downloadurl)$/i.test(key.replace(/[-_]/g, ''));
+export function rememberSecrets(value) {
+  if (!value || typeof value !== 'object') return value;
+  for (const [key, child] of Object.entries(value)) {
+    if (credentialKey(key) && typeof child === 'string' && child) secrets.add(child);
+    else if (child && typeof child === 'object') rememberSecrets(child);
+  }
+  return value;
+}
+export function safeOutput(value) {
+  rememberSecrets(value);
+  if (typeof value === 'string') {
+    for (const secret of [...secrets].sort((a, b) => b.length - a.length)) value = value.split(secret).join('[REDACTED]');
+    return value;
+  }
+  if (Array.isArray(value)) return value.map(safeOutput);
+  if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, credentialKey(key) && child ? '[REDACTED]' : safeOutput(child)]));
+  return value;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiashe/sdk",
-  "version": "0.1.36",
+  "version": "0.1.38",
   "type": "module",
   "main": "index.mjs",
   "exports": {

package/privateState.mjs

@@ -0,0 +1,61 @@
+import { constants } from 'node:fs';
+import { chmod, lstat, mkdir, open, realpath, rename, rm } from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+const missing = error => { if (error.code !== 'ENOENT') throw error; return null; };
+export async function privateDirectory(directory) {
+  for (let parent = path.resolve(directory); parent !== path.dirname(parent); parent = path.dirname(parent)) {
+    const info = await lstat(parent).catch(missing);
+    // macOS exposes its root-owned temporary filesystem through /var and /tmp.
+    const systemAlias = process.platform === 'darwin' && ['/var', '/tmp'].includes(parent) && info?.uid === 0 &&
+      info.isSymbolicLink() && await realpath(parent) === `/private${parent}`;
+    if (info && !systemAlias && (!info.isDirectory() || info.isSymbolicLink())) throw Error('PRIVATE_STATE_UNSAFE_DIRECTORY');
+  }
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  const info = await lstat(directory);
+  if (!info.isDirectory() || info.isSymbolicLink()) throw Error('PRIVATE_STATE_UNSAFE_DIRECTORY');
+  await chmod(directory, 0o700);
+}
+export async function checkPrivateFile(file) {
+  const info = await lstat(file).catch(missing);
+  if (info && (!info.isFile() || info.isSymbolicLink() || info.nlink !== 1)) throw Error('PRIVATE_STATE_UNSAFE_FILE');
+  if (info) await chmod(file, 0o600);
+  return info;
+}
+// Never steal a lock: a crashed process requires explicit local reconciliation.
+export async function withPrivateLock(file, operation, { timeoutMs = 3000 } = {}) {
+  const lock = `${file}.lock`;
+  const deadline = Date.now() + timeoutMs;
+  let handle;
+  while (!handle) {
+    try { handle = await open(lock, 'wx', 0o600); }
+    catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      if (Date.now() >= deadline) throw Error('PRIVATE_STATE_BUSY: another process or an interrupted operation owns the lock');
+      await new Promise(resolve => setTimeout(resolve, 25));
+    }
+  }
+  try { return await operation(); }
+  finally { await handle.close(); await rm(lock); }
+}
+// Caller holds the lock around the complete read/modify/write transaction.
+export async function atomicPrivateJson(file, value) {
+  const before = await checkPrivateFile(file);
+  const temporary = path.join(path.dirname(file), `.${path.basename(file)}.${randomUUID()}.tmp`);
+  let handle;
+  try {
+    handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW || 0), 0o600);
+    await handle.writeFile(`${JSON.stringify(value, null, 2)}\n`);
+    await handle.sync();
+    await handle.close(); handle = null;
+    const after = await checkPrivateFile(file);
+    if (Boolean(before) !== Boolean(after) || (before && (before.ino !== after.ino || before.dev !== after.dev))) throw Error('PRIVATE_STATE_CHANGED');
+    await rename(temporary, file);
+    // Atomic replacement is complete. Persist directory metadata where supported.
+    if (process.platform !== 'win32') {
+      const directory = await open(path.dirname(file), 'r');
+      try { await directory.sync(); } finally { await directory.close(); }
+    }
+  } finally { if (handle) await handle.close(); await rm(temporary, { force: true }); }
+}

package/runtime.mjs

@@ -72,7 +72,7 @@ export function runtimePrincipal(client) {
   return digest(`${new URL(client.profile.convexUrl).origin}\0${userId}`);
 }
 
-async function verifyDirectory(directory, files) {
+export async function verifyDirectory(directory, files) {
   const expected = new Map(files.map(file => [file.path, file]));
   let count = 0;
   const walk = async (folder, prefix = '') => {