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

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
+};

package/src/identity/shop-location.js

@@ -0,0 +1,153 @@
+'use strict';
+
+const account = require('../transport/account-api');
+const { oauthConfig } = require('../auth/config');
+const { readCredential } = require('../auth/credential-store');
+const { authSource } = require('../auth/credential-source');
+const { requestApi, snapshotApiIdentity, snapshotApiEnvironment } = require('../transport/api');
+const sessions = require('./session-store');
+const { readSavedContext } = require('./context-store');
+const { createContext } = require('./context');
+
+function id(value) {
+  if (typeof value !== 'string' || !/^[1-9]\d*$/.test(value) || !Number.isSafeInteger(Number(value))) {
+    throw sessions.fail('invalid_target', 'kdtId 必须是正整数店铺 ID。');
+  }
+  return value;
+}
+
+function selection(context, { tenantName = null, unitName = null, role = null } = {}) {
+  return {
+    tenantRootKdtId: context.hq, tenantName, currentUnitKdtId: context.shopId,
+    unitName, position: context.orgType, role
+  };
+}
+
+async function identify(env) {
+  const { environment: pinned, source, credentialRef: ref } = await snapshotApiIdentity(env);
+  const user = await account.whoami(pinned);
+  const actor = { user, pinned, ref, source };
+  assertIdentity(actor, env);
+  return actor;
+}
+
+function assertIdentity(actor, env) {
+  const credential = authSource(env) === 'env' ? null : readCredential(oauthConfig(env).server, env);
+  if (actor.ref !== sessions.credentialRef(env, credential)) {
+    throw sessions.fail('context_conflict', '登录状态在核实账号期间发生变化，请重新查看当前身份。');
+  }
+}
+
+function rejectOverride(env, explicitContext) {
+  if (env.ZAN_SAAS_CONTEXT || explicitContext !== undefined) {
+    throw sessions.fail('context_override_conflict',
+      '本次上下文由显式输入覆盖，请使用会话调用环境切店后核对 shop current。');
+  }
+}
+
+async function rootLocation(kdtId, actor) {
+  id(kdtId);
+  const page = await account.listShops({ includeKdtIds: [kdtId], pageNum: 1, pageSize: 1 }, actor.pinned);
+  const shop = page.items.find(item => item.kdtId === kdtId);
+  if (!shop) throw new Error(`当前账号下没有可选店铺 ${kdtId}。执行 zan-saas shop list 查看可选店铺。`);
+  if (!shop.orgType) throw new Error(`店铺 ${kdtId} 不是本版支持的总部或单店入口。`);
+  const status = await account.staffStatus(kdtId, actor.pinned);
+  if (status === account.staffStatuses.disabled) throw new Error(`你在店铺 ${kdtId} 的员工账号已停用，不能选择。`);
+  const context = createContext({
+    userId: actor.user.userId, hq: kdtId, shopId: kdtId, orgType: shop.orgType
+  });
+  return { context, selection: selection(context, {
+    tenantName: shop.shopName, unitName: shop.shopName, role: shop.shopRole
+  }) };
+}
+
+async function unitLocation(kdtId, root, actor) {
+  id(kdtId);
+  if (kdtId === root.context.hq) return root;
+  if (root.context.orgType !== 'hq') {
+    throw sessions.fail('unit_scope_unresolved', '当前店铺没有已核实的连锁总部，不能进入下级组织。');
+  }
+  const response = await requestApi({ path: 'youzan.shop.basic.get/3.0.0', body: {} },
+    await snapshotApiEnvironment(actor.pinned, kdtId),
+    { shopApp: false, identityCheck: false, maxResponseBytes: () => 256 * 1024 });
+  let envelope;
+  try { envelope = JSON.parse(response.body); } catch { /* Report a bounded protocol error below. */ }
+  const data = envelope?.data;
+  if (!response.ok || envelope?.success !== true || envelope.code !== 200 ||
+      !data || data.sid !== Number(kdtId) || data.root_kdt_id !== Number(root.context.hq)) {
+    throw sessions.fail('unit_scope_unresolved', '未能核实目标组织及所属连锁，未改变当前位置。');
+  }
+  if (![2001, 2002].includes(data.role)) {
+    throw sessions.fail('unit_not_supported', '本版仅支持已核实的连锁门店或网店位置。');
+  }
+  const context = createContext({ ...root.context, shopId: kdtId, orgType: 'shop' });
+  return { context, selection: selection(context, {
+    tenantName: root.selection.tenantName,
+    unitName: typeof data.name === 'string' && data.name.trim() ? data.name : null, role: data.role
+  }) };
+}
+
+function displayName(location) {
+  const { tenantName, unitName, currentUnitKdtId, tenantRootKdtId } = location.selection;
+  if (currentUnitKdtId === tenantRootKdtId) return tenantName || unitName;
+  return tenantName && unitName ? `${tenantName} / ${unitName}` : unitName || tenantName;
+}
+
+function result(action, effect, env) {
+  const state = sessions.snapshot(env);
+  const location = state.binding?.location;
+  return { context: location?.context ?? null, selection: location?.selection ?? null,
+    binding: sessions.publicBinding(state), effect: { action, ...effect } };
+}
+
+async function initialize(options = {}, env = process.env) {
+  if (!sessions.sessionId(env)) throw sessions.fail('session_missing', '会话初始化需要 ZAN_SAAS_SESSION_ID。');
+  rejectOverride(env);
+  const actor = await identify(env);
+  let legacy = null;
+  const existing = sessions.snapshot(env, { userId: actor.user.userId, credentialRef: actor.ref });
+  if (!options.resume && !existing.binding && !existing.recent && !existing.legacyChecked &&
+      !env.ZAN_SAAS_ACCOUNT_API_BASE_URL && !env.ZAN_SAAS_API_BASE_URL) {
+    const saved = readSavedContext(env);
+    if (saved?.context.userId === actor.user.userId && saved.context.hq === saved.context.shopId) {
+      const root = await rootLocation(saved.context.hq, actor);
+      if (JSON.stringify(root.context) === JSON.stringify(saved.context)) legacy = root;
+    }
+  }
+  const currentChanged = sessions.initialize({ ...options, legacy,
+    verifiedIdentity: { userId: actor.user.userId, credentialRef: actor.ref } }, env);
+  return result('init', { currentChanged, recentChanged: false }, env);
+}
+
+async function select(kdtId, options = {}, env = process.env, explicitContext) {
+  id(kdtId);
+  if (!sessions.sessionId(env)) throw sessions.fail('session_missing', '会话切换需要 ZAN_SAAS_SESSION_ID。');
+  rejectOverride(env, explicitContext);
+  if (env.ZAN_SAAS_KDT_ID && env.ZAN_SAAS_KDT_ID !== kdtId) {
+    throw sessions.fail('context_override_conflict', '请求店铺头覆盖与切换目标不同，未改变当前位置。');
+  }
+  const expected = sessions.snapshot(env);
+  if (!expected.binding) throw sessions.fail('session_uninitialized', '请先执行 zan-saas shop session init。');
+  const actor = await identify(env);
+  if (actor.user.userId !== expected.identity?.userId || actor.ref !== expected.identity?.credentialRef) {
+    throw sessions.fail('context_conflict', '登录身份已改变，请重新初始化本会话。');
+  }
+  const rootId = options.unit ? expected.binding.location?.context.hq : kdtId;
+  if (!rootId) throw sessions.fail('unit_scope_unresolved', '请先选择当前连锁。');
+  const root = await rootLocation(rootId, actor);
+  const location = options.unit ? await unitLocation(kdtId, root, actor) : root;
+  const effect = sessions.commit(location, expected, options, env);
+  return result(options.unit ? 'use_unit' : 'use_root', effect, env);
+}
+
+async function resolve(kdtId, options = {}, env = process.env) {
+  id(kdtId);
+  const rootId = options.rootKdtId === undefined ? kdtId : id(options.rootKdtId);
+  const actor = await identify(env);
+  const root = await rootLocation(rootId, actor);
+  const location = await unitLocation(kdtId, root, actor);
+  return { ...location, effect: { action: 'resolve', currentChanged: false, recentChanged: false },
+    revision: null };
+}
+
+module.exports = { selection, identify, assertIdentity, initialize, select, resolve, displayName, rejectOverride };

package/src/transport/api.js

@@ -11,6 +11,8 @@ const { runWithRequestState, beginRequest } = require('../execution/request-stat
 
 const apiPathPattern = /^\/?([a-z][a-z0-9._-]*)\/([0-9]+\.[0-9]+\.[0-9]+)$/;
 const apiSessions = new AsyncLocalStorage();
+const boundTargets = new WeakMap();
+const pinnedCredentials = new WeakMap();
 
 function runWithApiSession(action, environment) {
   return runWithRequestState(() =>
@@ -20,10 +22,22 @@ function runWithApiSession(action, environment) {
 function apiEnvironment() {
   const session = apiSessions.getStore();
   if (!session) return Object.freeze({ ...process.env });
-  session.env ||= Object.freeze({ ...(session.environment || process.env) });
+  session.env ||= Object.freeze({
+    ...(session.environment || process.env),
+    ...(Object.hasOwn(session, 'context') ? { ZAN_SAAS_CONTEXT: session.context } : {})
+  });
   return session.env;
 }
 
+function bindApiContext(context, environment = process.env) {
+  const session = apiSessions.getStore();
+  if (session) {
+    session.environment = environment;
+    session.context = JSON.stringify(context ?? null);
+    session.env = undefined;
+  }
+}
+
 // Business APIs select the shop per request; account APIs serve the user and send no shop.
 const gateways = {
   business: { key: 'ZAN_SAAS_API_BASE_URL', base: defaultApiBaseUrl, label: 'API base URL', shop: true },
@@ -46,14 +60,15 @@ class ApiResponseLimitError extends Error {
   }
 }
 
-async function accessToken(env) {
+async function accessCredential(env) {
   try {
+    if (pinnedCredentials.has(env)) return pinnedCredentials.get(env);
     const session = apiSessions.getStore();
     if (session && env === session.env) {
       session.credential ||= resolveAccessToken(env);
-      return (await session.credential).token;
+      return await session.credential;
     }
-    return (await resolveAccessToken(env)).token;
+    return await resolveAccessToken(env);
   } catch (error) {
     if (error instanceof AuthRequiredError || error instanceof AuthConfigurationError) {
       throw new ApiConfigurationError(error.message,
@@ -63,6 +78,20 @@ async function accessToken(env) {
   }
 }
 
+function pinEnvironment(env, credential, overrides = {}) {
+  const snapshot = Object.freeze({ ...env, ...overrides });
+  pinnedCredentials.set(snapshot, credential);
+  if (boundTargets.has(env)) boundTargets.set(snapshot, boundTargets.get(env));
+  return snapshot;
+}
+
+async function snapshotApiIdentity(env = apiEnvironment()) {
+  requestAddress('youzan.user.info.get/1.0.0', env, gateways.account);
+  const credential = await accessCredential(env);
+  return { environment: pinEnvironment(env, credential), source: credential.source,
+    credentialRef: credential.credentialRef };
+}
+
 // Personal tokens select the shop per request: ZAN_SAAS_KDT_ID, else the shopId of ZAN_SAAS_CONTEXT,
 // else the shop saved by `zan-saas shop use`.
 function shopHeader(env) {
@@ -76,7 +105,7 @@ function shopHeader(env) {
   return state.status === 'ready' ? state.context.shopId : undefined;
 }
 
-async function endpoint(path, env, gateway = gateways.business) {
+function requestAddress(path, env, gateway) {
   const base = env[gateway.key] || gateway.base;
   const match = apiPathPattern.exec(path);
   if (!match) throw new ApiConfigurationError('API path must be <api-name>/<version>');
@@ -88,19 +117,47 @@ async function endpoint(path, env, gateway = gateways.business) {
       url.password || url.search || url.hash || url.origin === 'null') {
     throw new ApiConfigurationError(`${gateway.label} must be an HTTPS URL without credentials, query or fragment`);
   }
-  // Resolve the token last so invalid configuration never triggers a login or refresh.
-  const token = await accessToken(env);
   const requestUrl = new URL(
     `${url.pathname.replace(/\/$/, '')}/${match[1]}/${match[2]}`, url.origin
   );
+  return requestUrl;
+}
+
+async function endpoint(path, env, gateway = gateways.business) {
+  const requestUrl = requestAddress(path, env, gateway);
+  // Resolve the token last so invalid configuration never triggers a login or refresh.
+  const credential = await accessCredential(env);
+  const { token } = credential;
   requestUrl.searchParams.set('access_token', token);
-  return { requestUrl, token };
+  return { requestUrl, token, credential };
 }
 
 async function requestApi({ path, body }, env = apiEnvironment(), options = {}) {
   const target = gateways[options.gateway || 'business'];
   if (!target) throw new ApiConfigurationError(`Unknown API gateway: ${options.gateway}`);
   const kdtId = target.shop ? shopHeader(env) : undefined;
+  if (target.shop && env.ZAN_SAAS_SESSION_ID !== undefined && options.identityCheck !== false) {
+    const state = readContext(contextInput(env));
+    if (state.status !== 'ready') {
+      throw new ApiConfigurationError('会话没有有效上下文，请先初始化并选择店铺。', 'session_uninitialized');
+    }
+    if (env.ZAN_SAAS_KDT_ID && env.ZAN_SAAS_KDT_ID !== state.context.shopId &&
+        boundTargets.get(env) !== env.ZAN_SAAS_KDT_ID) {
+      throw new ApiConfigurationError('请求店铺头与会话位置冲突，业务请求未发送。', 'context_override_conflict');
+    }
+    const { credential } = await endpoint(path, env, target);
+    env = pinEnvironment(env, credential);
+    let user;
+    try { user = await require('./account-api').whoami(env); }
+    catch { throw new ApiConfigurationError('无法核实当前凭证账号，业务请求未发送。', 'context_identity_mismatch'); }
+    if (user.userId !== state.context.userId) {
+      throw new ApiConfigurationError('当前凭证账号与任务上下文不一致或无法核实，业务请求未发送。', 'context_identity_mismatch');
+    }
+  }
+  if (!pinnedCredentials.has(env)) {
+    const { credential } = await endpoint(path, env, target);
+    env = pinEnvironment(env, credential);
+  }
   const send = () => sendApi(path, body, env, target, kdtId, options);
   const response = await send();
   if (!kdtId || env.ZAN_SAAS_SHOP_APP_INIT === '0' || options.shopApp === false) return response;
@@ -189,11 +246,21 @@ async function readResponseBody(response, maxResponseBytes) {
 }
 
 async function snapshotApiEnvironment(env = apiEnvironment(), kdtId) {
-  const { token } = await endpoint('youzan.shop.basic.get/3.0.0', env);
-  return Object.freeze({ ...env, ZAN_SAAS_USER_ACCESS_TOKEN: token, ZAN_SAAS_KDT_ID: String(kdtId) });
+  if (env.ZAN_SAAS_SESSION_ID !== undefined && env.ZAN_SAAS_KDT_ID &&
+      env.ZAN_SAAS_KDT_ID !== String(kdtId)) {
+    throw new ApiConfigurationError('显式请求店铺头与本次命令目标冲突。', 'context_override_conflict');
+  }
+  const context = contextInput(env);
+  const { credential } = await endpoint('youzan.shop.basic.get/3.0.0', env);
+  const snapshot = pinEnvironment(env, credential, {
+    ZAN_SAAS_KDT_ID: String(kdtId),
+    ZAN_SAAS_CONTEXT: typeof context === 'string' ? context : JSON.stringify(context ?? null)
+  });
+  boundTargets.set(snapshot, String(kdtId));
+  return snapshot;
 }
 
 module.exports = {
   requestApi, snapshotApiEnvironment, runWithApiSession, ApiConfigurationError,
-  ApiResponseLimitError, readResponseBody
+  ApiResponseLimitError, readResponseBody, bindApiContext, snapshotApiIdentity
 };

package/src/transport/shop-app.js

@@ -5,6 +5,10 @@ const { callAccountApi, paths } = require('./account-api');
 // The business gateway answers 1106 when the selected shop has no usable app. The request never
 // reached the API, so it is safe to send again once the app is ready.
 const noAppCode = '1106';
+// bifrost-gateway maps the oauth 1106 to its own 4204 and keeps only the message. 4204 also covers
+// other permission failures, so it counts as "no app" only together with this message.
+const noAppGatewayCode = '4204';
+const noAppMessage = '该店铺下没有可用的应用';
 // CloudAppStateEnums: only 2 is ready; 4, 5 and 6 never become ready without a person stepping in.
 const appStates = Object.freeze({ 1: '审核中', 2: '已创建', 3: '初始化中', 4: '初始化失败', 5: '审核驳回', 6: '已删除' });
 const readyState = 2;
@@ -16,7 +20,10 @@ function isNoAppResponse(response) {
   try { json = JSON.parse(response.body); } catch { return false; }
   if (!json || typeof json !== 'object') return false;
   const source = json.gw_err_resp && typeof json.gw_err_resp === 'object' ? json.gw_err_resp : json;
-  return String(source.code ?? source.err_code) === noAppCode;
+  const code = String(source.code ?? source.err_code);
+  if (code === noAppCode) return true;
+  const message = source.err_msg ?? source.message ?? source.msg;
+  return code === noAppGatewayCode && typeof message === 'string' && message.includes(noAppMessage);
 }
 
 const stateText = app => (app ? `应用 ${app.appId} ${appStates[app.appState] || `状态 ${app.appState}`}` : '应用尚未生成');