@youzan-cloud/zan-saas-cli 0.1.0-beta.4 → 0.1.0-beta.8

package/src/execution/error-details.js

@@ -3,6 +3,7 @@
 const { executionFor } = require('./request-state');
 const { issueReasons } = require('./error-model');
 const { ParserError } = require('./parser-error');
+const { gatewayGuidance } = require('./gateway-guidance');
 const contexts = new WeakMap();
 const reasons = new Set(issueReasons);
 const constraintKeys = ['type', 'enum', 'const', 'minimum', 'maximum', 'exclusiveMinimum',
@@ -203,7 +204,8 @@ function localContextReason(error, details, execution) {
     execution.observedAttempts === 0 ? error.diagnosticReason : undefined;
 }
 
-function describeRecovery(details, execution, missingAuthentication = false, contextReason, responseReason) {
+function describeRecovery(details, execution, missingAuthentication = false, contextReason, responseReason,
+  gateway = gatewayGuidance(details, undefined, execution)) {
   if (contextReason) return { action: 'stop_and_inspect', nextStep:
     ['context_missing', 'target_missing'].includes(contextReason)
       ? '未登录先执行 zan-saas auth login；登录后用 zan-saas shop list 和 zan-saas shop use <kdtId> 选店。缺少上下文时仅可显式指定店铺做 --dry-run，不自动切店或重放。'
@@ -221,14 +223,13 @@ function describeRecovery(details, execution, missingAuthentication = false, con
   if (details.category === 'provider_unavailable' && details.command === 'privacy.field.decrypt') {
     return { action: 'stop_and_inspect', nextStep: '当前仅支持离线预览，请加 --dry-run；真实解密服务尚未接入。' };
   }
+  if (responseReason) return { action: 'stop_and_inspect',
+    nextStep: `${responseReason.nextStep} 不自动重放、切店或换身份。` };
+  if (gateway) return { action: gateway.action, nextStep: gateway.nextStep };
   if (missingAuthentication || details.category === 'authentication') {
     return { action: 'complete_authentication',
       nextStep: '检查 zan-saas auth status --format json，按公共认证流程完成登录；不在聊天中提供凭证，不自动重放原调用。' };
   }
-  if (gatewayAccessDenied(details)) {
-    return { action: 'request_access_review',
-      nextStep: '请检查当前账号是否有该店铺权限，以及店铺应用是否已获该接口的开放能力授权；可提供接口和 trace_id 给管理员排查，不自动重放。' };
-  }
   if (details.category === 'permission') {
     return { action: 'request_access_review',
       nextStep: '核对原账号、目标店铺与服务端授权，可提供脱敏接口及 trace_id 给管理员；不切店、换身份或自动重放。' };
@@ -237,8 +238,6 @@ function describeRecovery(details, execution, missingAuthentication = false, con
     return { action: 'stop_and_inspect',
       nextStep: '店铺核验失败，后续业务请求尚未发送；本次已有核验请求记录，核对原店铺和凭证后停止，不自动切店或重放。' };
   }
-  if (responseReason) return { action: 'stop_and_inspect',
-    nextStep: `${responseReason.nextStep} 不自动重放、切店或换身份。` };
   if (details.requestState === 'sent' && details.category === 'business_rejected') {
     return { action: 'stop_and_inspect',
       nextStep: '接口已拒绝本次查询；将诊断中的 api、businessCode 或 gatewayCode、trace_id 提供给管理员核查服务端原因。错误码本身不能证明是权限或数据问题，不自动重放、切店或换身份。' };
@@ -275,19 +274,14 @@ function businessRejectionMessage(details) {
   return `接口拒绝了本次查询${code ? `（${code}）` : ''}，已停止处理。`;
 }
 
-function gatewayAccessDenied(details) {
-  return details?.requestState === 'sent' &&
-    ['business_rejected', 'permission'].includes(details.category) &&
-    [4204, '4204'].includes(details.gatewayCode);
-}
-
 function finalizeError(error, registeredContext) {
   if (error instanceof ParserError) return structuredClone(error.result);
   const context = contexts.get(error) || registeredContext;
   if (context?.schema.errors?.diagnosticsVersion !== 2) {
-    if (gatewayAccessDenied(error.cliDetails)) {
-      error.message = '网关拒绝访问：没有操作权限。';
-      error.cliDetails.nextStep = '请检查当前账号是否有该店铺权限，以及店铺应用是否已获该接口的开放能力授权；可提供接口和 trace_id 给管理员排查。';
+    const gateway = gatewayGuidance(error.cliDetails, context);
+    if (gateway) {
+      error.message = gateway.message;
+      error.cliDetails.nextStep = gateway.nextStep;
     }
     return { success: false, code: -10001, message: error.message,
       ...(error.cliDetails ? { details: error.cliDetails } : {}) };
@@ -372,7 +366,8 @@ function diagnosticError(error, context, execution) {
   if (error.issuesTruncated) details.issuesTruncated = true;
   const contextReason = localContextReason(error, details, execution);
   const responseReason = declaredResponseReason(error, context, details, execution);
-  const recovery = describeRecovery(details, execution, error.diagnosticReason === 'missing_authentication', contextReason, responseReason);
+  const gateway = !inputError && !contextReason && !responseReason ? gatewayGuidance(details, context, execution) : undefined;
+  const recovery = describeRecovery(details, execution, error.diagnosticReason === 'missing_authentication', contextReason, responseReason, gateway);
   const groupConflict = inputError && context.path === 'item.group.list' &&
     issues.some(issue => issue.path === '/parentGroupId' && issue.reason === 'constraint' && issue.relatedPaths?.includes('/title'))
     ? context.schema.errors.parentTitleConflict : undefined;
@@ -382,9 +377,9 @@ function diagnosticError(error, context, execution) {
   const result = { success: false, code: -10001,
     message: inputError ? (groupConflict?.message || issueMessage(issues)) :
       contextReason ? localContextMessages[contextReason] :
-      gatewayAccessDenied(details) ? '网关拒绝访问：没有操作权限。' :
       details.category === 'provider_unavailable' && context.path === 'privacy.field.decrypt' ? '当前仅支持离线预览，真实解密服务尚未接入' :
       responseReason ? responseReason.message :
+      gateway ? gateway.message :
       details.category === 'business_rejected' && details.requestState === 'sent' ? businessRejectionMessage(details) :
       issues.some(issue => issue.source === 'output') ?
         `返回数据字段 ${issues.find(issue => issue.source === 'output').path} 不符合要求，已停止查询` :

package/src/execution/gateway-guidance.js

@@ -0,0 +1,43 @@
+'use strict';
+
+const authenticationStep = '先区分当前凭证来源与目标店铺、应用授权范围；个人登录使用 zan-saas auth login 重新登录授权，显式环境身份由凭证提供方更新或补齐配置。zan-saas auth status 仅查看本地保存状态，不能证明环境 token 有效；不在聊天中提供凭证，不自动切换来源或刷新，不自动重放。';
+const supportStep = '先按同版 help/schema 核对参数契约；参数符合且持续失败时，将诊断中实际保留的 api、gatewayCode 和追踪号提供给支持人员排查，不提供凭证、客户标识或请求 body，不自动重放。';
+const guidance = new Map([
+  [4101, { message: '网关限制了本次请求：调用过于频繁或受限。', action: 'stop_and_inspect',
+    nextStep: '停止本轮后续请求，检查调用频率、并发与可用配额；降低频率后由调用方重新决定是否发起。持续受限时提供诊断中实际保留的 api、gatewayCode 和追踪号排查，不保证固定恢复时间，不自动等待或重试，不自动重放。' }],
+  [4201, { message: '网关拒绝了本次请求：请求凭证无效。', action: 'complete_authentication',
+    nextStep: `核查凭证值以及店铺与应用授权；不能仅凭此码确定密码、员工权限或某一项授权失效。${authenticationStep}` }],
+  [4202, { message: '网关拒绝了本次请求：请求凭证已过期。', action: 'complete_authentication',
+    nextStep: authenticationStep }],
+  [4203, { message: '网关拒绝了本次请求：请求凭证不存在。', action: 'complete_authentication',
+    nextStep: authenticationStep }],
+  [4204, { message: '网关拒绝访问：没有操作权限。', action: 'request_access_review',
+    nextStep: '请检查当前账号是否有该店铺权限，以及店铺应用是否已获该接口的开放能力授权；不能仅凭此码确定根因，持续拒绝时提供诊断中实际保留的 api、gatewayCode 和追踪号给管理员核查服务端限制，不自动申请授权、切店或换身份，不自动重放。' }],
+  [4009, { message: '网关无法解析本次请求的客户标识 open_id。', action: 'stop_and_inspect',
+    nextStep: '按同版契约核对客户标识、标识类型与目标店铺；这不是登录凭证问题，也不能据此认定客户在所有店铺均不存在，不自动登录或切店，不自动重放。' }],
+  [5001, { message: '本次请求失败：网关报告上游系统异常。', action: 'stop_and_inspect', nextStep: supportStep }],
+  [5002, { message: '本次请求失败：网关报告上游业务异常。', action: 'stop_and_inspect', nextStep: supportStep }]
+]);
+
+function gatewayGuidance(details, context, execution) {
+  if (details?.requestState !== 'sent' ||
+      (execution && (execution.requestState !== 'sent' || execution.coverage !== 'complete')) ||
+      details.issues?.length) return undefined;
+  const raw = details.gatewayCode;
+  if (typeof raw !== 'number' && !(typeof raw === 'string' && /^[1-9]\d{3}$/.test(raw))) return undefined;
+  const code = Number(raw);
+  const selected = guidance.get(code);
+  if (!selected) return undefined;
+  const compatible = details.category === 'business_rejected' ||
+    (details.category === 'authentication' && [4201, 4202, 4203].includes(code)) ||
+    (details.category === 'permission' && code === 4204) ||
+    (details.category === 'http' && ((details.httpStatus === 429 && code === 4101) ||
+      (details.httpStatus >= 500 && [5001, 5002].includes(code))));
+  if (!compatible) return undefined;
+  const customerOption = code === 4009 && context?.command?.options.some(option => option.long === '--yz-open-id');
+  const bindingStep = details.stage === 'shop-binding' ? '店铺核验失败，后续业务请求尚未发送。' : '';
+  const customerStep = customerOption ? '核对本命令 --yz-open-id 的客户标识。' : '';
+  return { ...selected, nextStep: `${bindingStep}${customerStep}${selected.nextStep}` };
+}
+
+module.exports = { gatewayGuidance };

package/src/execution/shop-query.js

@@ -12,20 +12,23 @@ function failure(command, category, stage, scope = {}, requestState = 'not_sent'
   return new QueryError(category, stage, scope, facts, requestState, command, nextStep);
 }
 
-async function createBoundShopQuery(target, command, bindingStage = 'shop-binding', { onResponse, transportOptions } = {}) {
+async function createBoundShopQuery(target, command, bindingStage = 'shop-binding', {
+  onResponse, transportOptions, environment, beforeRequest
+} = {}) {
   const scope = Object.freeze({ kdtId: target.kdtId });
   if (!Number.isSafeInteger(scope.kdtId) || scope.kdtId < 1) {
     throw failure(command, 'validation', 'scope');
   }
   let env;
   try {
-    env = await snapshotApiEnvironment(undefined, scope.kdtId);
+    env = await snapshotApiEnvironment(environment, scope.kdtId);
   } catch (error) {
     const rejected = failure(command, 'configuration', 'configuration', scope);
     rejected.diagnosticReason = error.diagnosticReason;
     throw rejected;
   }
   async function read(path, body, stage, successCodes = [200]) {
+    if (beforeRequest) beforeRequest(path, stage);
     const { result, facts, rawBody, responseBytes } = await readApiEnvelope(path, body,
       (category, details, state, at) => failure(command, category,
         at === 'configuration' || category === transportOptions?.limitCategory ? at : stage,
@@ -43,7 +46,7 @@ async function createBoundShopQuery(target, command, bindingStage = 'shop-bindin
   if (data.sid !== scope.kdtId) {
     throw failure(command, 'scope_unresolved', bindingStage, scope, 'sent', facts);
   }
-  return { read, binding };
+  return { read, binding, environment: env };
 }
 
 async function createShopQuery(target, command, options = {}) {

package/src/identity/context-store.js

@@ -1,7 +1,8 @@
 'use strict';
 
 const { oauthConfig } = require('../auth/config');
-const { readStore, storePath, writeStore } = require('../auth/credential-store');
+const { storePath } = require('../auth/credential-store');
+const { readFileStore, updateFileStore } = require('./file-store');
 const { createContext, readContext } = require('./context');
 
 const fileName = 'context.json';
@@ -12,7 +13,7 @@ function contextPath(env = process.env) {
 
 // The selected shop is kept per oauth origin, like the credential it was chosen with.
 function readSavedContext(env = process.env) {
-  const entry = readStore(fileName, env)[oauthConfig(env).server];
+  const entry = readFileStore(contextPath(env))[oauthConfig(env).server];
   const state = readContext(entry?.context);
   if (state.status !== 'ready') return null;
   return Object.freeze({
@@ -25,24 +26,27 @@ function readSavedContext(env = process.env) {
 function saveContext(input, { shopName } = {}, env = process.env) {
   const context = createContext(input);
   const { server } = oauthConfig(env);
-  const data = readStore(fileName, env);
-  data[server] = { context, ...(shopName ? { shopName } : {}), savedAt: new Date().toISOString() };
-  writeStore(fileName, data, env);
+  updateFileStore(contextPath(env), data => {
+    data[server] = { context, ...(shopName ? { shopName } : {}), savedAt: new Date().toISOString() };
+  });
   return context;
 }
 
 function deleteContext(env = process.env) {
   const { server } = oauthConfig(env);
-  const data = readStore(fileName, env);
-  if (!Object.hasOwn(data, server)) return false;
-  delete data[server];
-  writeStore(fileName, data, env);
-  return true;
+  return updateFileStore(contextPath(env), data => {
+    if (!Object.hasOwn(data, server)) return false;
+    delete data[server];
+    return true;
+  });
 }
 
 // ZAN_SAAS_CONTEXT wins, even when invalid; otherwise the shop chosen with `shop use`.
 function contextInput(env = process.env) {
   if (env.ZAN_SAAS_CONTEXT) return env.ZAN_SAAS_CONTEXT;
+  if (env.ZAN_SAAS_SESSION_ID !== undefined) {
+    return require('./session-store').sessionContext(env);
+  }
   try {
     return readSavedContext(env)?.context;
   } catch {

package/src/identity/file-store.js

@@ -0,0 +1,147 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { createHash, randomUUID } = require('node:crypto');
+
+const pause = new Int32Array(new SharedArrayBuffer(4));
+const digest = text => createHash('sha256').update(text).digest('hex');
+
+function reclaim(lock, previous) {
+  const guard = `${lock}.reclaim`;
+  let fd;
+  try { fd = fs.openSync(guard, 'wx', 0o600); }
+  catch (error) {
+    if (error.code === 'EEXIST') return false;
+    throw storageError();
+  }
+  try {
+    if (readText(lock) !== previous) return false;
+    fs.unlinkSync(lock);
+    return true;
+  } finally {
+    fs.closeSync(fd);
+    fs.unlinkSync(guard);
+  }
+}
+
+function storageError(reason = 'context_store_invalid') {
+  const error = new Error(reason === 'context_lock_timeout'
+    ? '选店记录正在被其他调用更新，请稍后核对当前位置。'
+    : '选店记录损坏或无法读取，请核对本机上下文文件；未回退到其他店铺。');
+  error.diagnosticReason = reason;
+  return error;
+}
+
+function readText(filename) {
+  try {
+    const fd = fs.openSync(filename, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
+    try {
+      if (!fs.fstatSync(fd).isFile()) throw storageError();
+      return fs.readFileSync(fd, 'utf8');
+    } finally { fs.closeSync(fd); }
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw storageError();
+  }
+}
+
+function withLock(filename, action) {
+  const lock = `${filename}.lock`;
+  const started = Date.now();
+  const owner = JSON.stringify({ pid: process.pid, nonce: randomUUID() });
+  let fd;
+  for (;;) {
+    try {
+      fd = fs.openSync(lock, 'wx', 0o600);
+      fs.writeFileSync(fd, owner);
+      break;
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw storageError();
+      const previous = readText(lock);
+      try {
+        const { pid } = JSON.parse(previous);
+        if (Number.isSafeInteger(pid) && pid > 0) {
+          try { process.kill(pid, 0); }
+          catch (dead) {
+            if (dead.code === 'ESRCH' && readText(lock) === previous) {
+              if (reclaim(lock, previous)) continue;
+            }
+          }
+        }
+      } catch { /* An incomplete lock is never stolen from a live writer. */ }
+      if (Date.now() - started >= 5000) throw storageError('context_lock_timeout');
+      Atomics.wait(pause, 0, 0, 10);
+    }
+  }
+  try { return action(); }
+  finally {
+    fs.closeSync(fd);
+    if (readText(lock) === owner) fs.unlinkSync(lock);
+  }
+}
+
+function parse(text) {
+  try {
+    const value = JSON.parse(text);
+    if (!value || typeof value !== 'object' || Array.isArray(value)) throw storageError();
+    return value;
+  } catch { throw storageError(); }
+}
+
+function readUnlocked(filename) {
+  const pending = readText(`${filename}.journal`);
+  if (pending?.endsWith('\n')) {
+    const record = parse(pending);
+    if (typeof record.payload !== 'string' || digest(record.payload) !== record.sha256) {
+      throw storageError();
+    }
+    return parse(record.payload);
+  }
+  const text = readText(filename);
+  return text === null ? {} : parse(text);
+}
+
+// Keep the existing inode: permissions granted to a file remain attached to that file.
+function rewrite(filename, text) {
+  let fd;
+  try {
+    fd = fs.openSync(filename, fs.constants.O_RDWR | fs.constants.O_CREAT |
+      (fs.constants.O_NOFOLLOW || 0), 0o600);
+    if (!fs.fstatSync(fd).isFile()) throw storageError();
+    const bytes = Buffer.from(text);
+    let offset = 0;
+    while (offset < bytes.length) {
+      offset += fs.writeSync(fd, bytes, offset, bytes.length - offset, offset);
+    }
+    fs.ftruncateSync(fd, bytes.length);
+    fs.fsyncSync(fd);
+    fs.fchmodSync(fd, 0o600);
+  } finally { if (fd !== undefined) fs.closeSync(fd); }
+}
+
+function readFileStore(filename) {
+  if (!fs.existsSync(path.dirname(filename))) return {};
+  return withLock(filename, () => readUnlocked(filename));
+}
+
+function updateFileStore(filename, update) {
+  fs.mkdirSync(path.dirname(filename), { recursive: true, mode: 0o700 });
+  return withLock(filename, () => {
+    const data = readUnlocked(filename);
+    const result = update(data);
+    const payload = `${JSON.stringify(data, null, 2)}\n`;
+    // Finish a previously committed rewrite before reusing its journal.
+    if (readText(`${filename}.journal`)?.endsWith('\n')) {
+      rewrite(filename, `${JSON.stringify(readUnlocked(filename), null, 2)}\n`);
+    }
+    rewrite(`${filename}.journal`, '');
+    // A durable redo record is the commit point. Readers can use it after an interrupted rewrite.
+    rewrite(`${filename}.journal`, `${JSON.stringify({ payload, sha256: digest(payload) })}\n`);
+    rewrite(filename, payload);
+    rewrite(`${filename}.journal`, '');
+    return result;
+  });
+}
+
+module.exports = { digest, readFileStore, updateFileStore, storageError };

package/src/identity/session-store.js

@@ -0,0 +1,261 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { oauthConfig, configDir, defaultAccountApiBaseUrl, defaultApiBaseUrl } = require('../auth/config');
+const { createContext } = require('./context');
+const { digest, readFileStore, updateFileStore, storageError } = require('./file-store');
+const { readCredential, credentialPresence } = require('../auth/credential-store');
+const { authSource, credentialChoice } = require('../auth/credential-source');
+
+function fail(reason, message) {
+  const error = new Error(message);
+  error.diagnosticReason = reason;
+  return error;
+}
+
+function sessionId(env = process.env) {
+  const value = env.ZAN_SAAS_SESSION_ID;
+  if (value === undefined) return null;
+  if (typeof value !== 'string' || !value.trim() || /[\u0000-\u001f\u007f]/.test(value) ||
+      Buffer.byteLength(value) > 256) {
+    throw fail('session_missing', 'ZAN_SAAS_SESSION_ID 必须是宿主提供的非空会话标识，最长256字节。');
+  }
+  return digest(value);
+}
+
+function environmentKey(env) {
+  const server = oauthConfig(env).server;
+  const bases = [env.ZAN_SAAS_ACCOUNT_API_BASE_URL || defaultAccountApiBaseUrl,
+    env.ZAN_SAAS_API_BASE_URL || defaultApiBaseUrl].map(value => {
+    const url = new URL(value);
+    if (url.username || url.password || url.search || url.hash ||
+        !['https:', 'http:'].includes(url.protocol)) throw storageError();
+    return url.toString().replace(/\/$/, '');
+  });
+  return { server, key: digest(JSON.stringify([server, ...bases])) };
+}
+
+function statePath(env = process.env) {
+  return path.join(configDir(env), 'contexts-v2', `${environmentKey(env).key}.json`);
+}
+
+function exact(value, fields) {
+  return value && typeof value === 'object' && !Array.isArray(value) &&
+    Object.keys(value).length === fields.length && fields.every(key => Object.hasOwn(value, key));
+}
+const dictionary = value => value && typeof value === 'object' && !Array.isArray(value) &&
+  Object.keys(value).every(key => /^[a-f0-9]{64}$/.test(key));
+const time = value => value === null || typeof value === 'string' &&
+  /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/.test(value) && Number.isFinite(Date.parse(value));
+const nullableName = value => value === null || typeof value === 'string' && Boolean(value.trim());
+
+function validLocation(value, userId) {
+  if (!exact(value, ['context', 'selection'])) return false;
+  const { context, selection } = value;
+  try { createContext(context); } catch { return false; }
+  return context.userId === userId && exact(selection, [
+    'tenantRootKdtId', 'tenantName', 'currentUnitKdtId', 'unitName', 'position', 'role'
+  ]) && selection.tenantRootKdtId === context.hq && selection.currentUnitKdtId === context.shopId &&
+    selection.position === context.orgType && nullableName(selection.tenantName) &&
+    nullableName(selection.unitName) && (selection.role === null ||
+      Number.isSafeInteger(selection.role) && selection.role >= 0);
+}
+
+function validate(data, env) {
+  if (!Object.keys(data).length) return {
+    schemaVersion: 2, server: environmentKey(env).server, identity: null, identities: {}, accounts: {}
+  };
+  if (!exact(data, ['schemaVersion', 'server', 'identity', 'identities', 'accounts']) ||
+      data.schemaVersion !== 2 || data.server !== environmentKey(env).server ||
+      !dictionary(data.accounts) || !dictionary(data.identities)) throw storageError();
+  for (const identity of [...Object.values(data.identities), ...(data.identity ? [data.identity] : [])]) {
+    if (!exact(identity, ['userId', 'credentialRef']) ||
+        !(identity.userId === null || typeof identity.userId === 'string' && identity.userId.trim()) ||
+        typeof identity.credentialRef !== 'string') throw storageError();
+  }
+  if (data.identity !== null && (!data.identity || typeof data.identity !== 'object')) throw storageError();
+  for (const [key, identity] of Object.entries(data.identities)) {
+    if (key !== digest(identity.credentialRef) || !identity.credentialRef.startsWith('env:') ||
+        identity.userId === null) throw storageError();
+  }
+  for (const [key, account] of Object.entries(data.accounts)) {
+    if (!exact(account, ['userId', 'recent', 'sessions', 'legacyChecked']) || typeof account.userId !== 'string' ||
+        !account.userId.trim() || digest(account.userId) !== key || !dictionary(account.sessions) ||
+        typeof account.legacyChecked !== 'boolean' ||
+        account.recent !== null && !validLocation(account.recent, account.userId)) throw storageError();
+    for (const binding of Object.values(account.sessions)) {
+      if (!exact(binding, ['state', 'revision', 'origin', 'initializedAt', 'selectedAt', 'location']) ||
+          !['needs_selection', 'ready', 'cleared'].includes(binding.state) ||
+          !Number.isSafeInteger(binding.revision) || binding.revision < 1 ||
+          !['explicit', 'inherited', 'legacy_import', 'none'].includes(binding.origin) ||
+          !time(binding.initializedAt) || !time(binding.selectedAt) ||
+          (binding.state === 'ready' ? !validLocation(binding.location, account.userId)
+            : binding.location !== null)) throw storageError();
+    }
+  }
+  return data;
+}
+
+const read = env => validate(readFileStore(statePath(env)), env);
+function update(env, action) {
+  return updateFileStore(statePath(env), raw => {
+    const data = validate(raw, env);
+    const result = action(data);
+    Object.assign(raw, data);
+    validate(raw, env);
+    return result;
+  });
+}
+
+function credentialRef(env, credential) {
+  return credentialChoice(env, credential).credentialRef;
+}
+
+function activeIdentity(data, env) {
+  const mode = authSource(env);
+  if (mode !== 'env') {
+    const personal = credentialPresence(oauthConfig(env).server, env);
+    if (personal.present) {
+      return data.identity?.credentialRef === personal.credentialRef
+        ? data.identity : { userId: null, credentialRef: personal.credentialRef };
+    }
+  }
+  const ref = credentialRef(env);
+  return mode !== 'personal' && ref ? data.identities[digest(ref)] || null : null;
+}
+
+function assertCredential(identity, env) {
+  const credential = authSource(env) === 'env' ? null : readCredential(oauthConfig(env).server, env);
+  if (identity.credentialRef !== credentialRef(env, credential)) {
+    throw fail('context_conflict', '登录代次在执行期间改变，未提交旧身份的位置。');
+  }
+}
+
+function accountOf(data, env) {
+  const identity = activeIdentity(data, env);
+  return identity?.userId ? data.accounts[digest(identity.userId)] : null;
+}
+
+function snapshot(env = process.env, verifiedIdentity) {
+  const id = sessionId(env);
+  if (!id) throw fail('session_missing', '请由宿主逐次传入 ZAN_SAAS_SESSION_ID。');
+  const data = read(env);
+  const identity = verifiedIdentity || activeIdentity(data, env);
+  const account = identity?.userId ? data.accounts[digest(identity.userId)] : null;
+  const binding = account?.sessions[id] || null;
+  return { identity, binding, id, recent: account?.recent ?? null, legacyChecked: account?.legacyChecked ?? false };
+}
+
+function publicBinding(snapshotValue) {
+  const { binding, id, identity } = snapshotValue;
+  return {
+    mode: 'session', sessionRef: id.slice(0, 16),
+    state: binding?.state || (identity?.userId ? 'uninitialized' : 'identity_pending'),
+    revision: binding?.revision ?? null, origin: binding?.origin || 'none',
+    initializedAt: binding?.initializedAt ?? null, selectedAt: binding?.selectedAt ?? null
+  };
+}
+
+function initialize({ resume = false, legacy = null, verifiedIdentity } = {}, env = process.env) {
+  const id = sessionId(env);
+  if (!id) throw fail('session_missing', '会话初始化需要 ZAN_SAAS_SESSION_ID。');
+  return update(env, data => {
+    const identity = verifiedIdentity || activeIdentity(data, env);
+    if (!identity?.userId) throw fail('identity_pending', '请先核实当前登录账号，再初始化会话。');
+    assertCredential(identity, env);
+    const key = digest(identity.userId);
+    const account = data.accounts[key] || {
+      userId: identity.userId, recent: null, sessions: {}, legacyChecked: false
+    };
+    if (resume && !account.sessions[id]) {
+      throw fail('session_not_found', '原会话选店记录不存在，请明确重新选择店铺。');
+    }
+    if (identity.credentialRef.startsWith('env:')) data.identities[digest(identity.credentialRef)] = identity;
+    else data.identity = identity;
+    data.accounts[key] = account;
+    if (account.sessions[id]) return false;
+    const imported = legacy && validLocation(legacy, account.userId) ? legacy : null;
+    const location = account.recent || (!account.legacyChecked ? imported : null);
+    const now = new Date().toISOString();
+    account.sessions[id] = {
+      state: location ? 'ready' : 'needs_selection', revision: 1,
+      origin: account.recent ? 'inherited' : location ? 'legacy_import' : 'none',
+      initializedAt: now, selectedAt: location ? now : null, location
+    };
+    if (!account.recent && location) account.recent = location;
+    account.legacyChecked = true;
+    return true;
+  });
+}
+
+function commit(location, expected, { sessionOnly = false } = {}, env = process.env) {
+  const id = sessionId(env);
+  return update(env, data => {
+    const identity = activeIdentity(data, env);
+    const account = accountOf(data, env);
+    const previous = account?.sessions[id];
+    if (!previous) throw fail('session_uninitialized', '请先执行 zan-saas shop session init。');
+    assertCredential(identity, env);
+    if (identity.userId !== expected.identity?.userId ||
+        identity.credentialRef !== expected.identity?.credentialRef ||
+        previous.revision !== expected.binding?.revision) {
+      throw fail('context_conflict', '会话位置或登录身份已改变，请重新查看当前位置。');
+    }
+    if (!validLocation(location, account.userId)) throw storageError();
+    const currentChanged = JSON.stringify(previous.location) !== JSON.stringify(location);
+    const recentChanged = !sessionOnly && JSON.stringify(account.recent) !== JSON.stringify(location);
+    if (currentChanged) account.sessions[id] = {
+      ...previous, state: 'ready', revision: previous.revision + 1, origin: 'explicit',
+      selectedAt: new Date().toISOString(), location
+    };
+    if (!sessionOnly) account.recent = location;
+    return { currentChanged, recentChanged };
+  });
+}
+
+function clear({ recent = false } = {}, env = process.env) {
+  const id = sessionId(env);
+  return update(env, data => {
+    const account = accountOf(data, env);
+    const binding = account?.sessions[id];
+    if (!binding) throw fail('session_uninitialized', '请先执行 zan-saas shop session init。');
+    const currentChanged = binding.state !== 'cleared';
+    const recentChanged = recent && account.recent !== null;
+    if (currentChanged) account.sessions[id] = {
+      ...binding, state: 'cleared', location: null, origin: 'none',
+      revision: binding.revision + 1, selectedAt: null
+    };
+    if (recent) account.recent = null;
+    return { cleared: binding.state === 'ready', currentChanged, recentChanged };
+  });
+}
+
+function sessionContext(env) {
+  return snapshot(env).binding?.location?.context;
+}
+
+function resetIdentity(env, { logout = false, pendingCredentialRef = null } = {}) {
+  const directory = path.join(configDir(env), 'contexts-v2');
+  if (!fs.existsSync(directory)) return;
+  const server = oauthConfig(env).server;
+  for (const filename of fs.readdirSync(directory).filter(name => /^[a-f0-9]{64}\.json$/.test(name))) {
+    const target = path.join(directory, filename);
+    updateFileStore(target, data => {
+      if (data.server !== server) return;
+      if (logout) {
+        const protectedUsers = new Set(Object.values(data.identities || {}).map(item => item.userId));
+        if (data.identity?.userId) delete data.accounts[digest(data.identity.userId)];
+        else for (const [key, account] of Object.entries(data.accounts || {})) {
+          if (!protectedUsers.has(account.userId)) delete data.accounts[key];
+        }
+      }
+      data.identity = pendingCredentialRef ? { userId: null, credentialRef: pendingCredentialRef } : null;
+    });
+  }
+}
+
+module.exports = {
+  sessionId, environmentKey, statePath, credentialRef, snapshot, publicBinding,
+  initialize, commit, clear, sessionContext, resetIdentity, fail
+};