dsh-d365-kit 0.34.1 → 0.34.4

package/index.js

@@ -1,142 +1,142 @@
-/**
- * `dsh-d365-kit` — D365 CE / Dataverse toolkit for DSH.
- *
- * Tools, one data path:
- *   d365_envs       which environments exist and whether they authenticate
- *   d365_metadata   the generic metadata query over a fixed resource catalogue
- *   d365_layers     the solution-layer stack behind any component
- *   d365_sync       snapshot an environment's metadata to local files
- *   d365_diff       compare two snapshots
- *   d365_configure  read/write the environment list (same storage as the UI)
- *   d365_write      prepare a metadata change, then confirm and apply it
- *   d365_migrate    assess what happens if a solution is imported into another environment
- *   d365_code_check what a merge request's changed scripts break in a target environment
- *   d365_refs       who references a field, script or plugin assembly
- *   d365_data       count / group / sample business records (needs `data.read`)
- *   d365_data_write create or patch one business record (needs `data.write`)
- *   d365_data_sync  move business records between environments (plan, then confirm)
- *   d365_invoke     call one action or function and return status + body (needs `message.invoke`)
+/**
+ * `dsh-d365-kit` — D365 CE / Dataverse toolkit for DSH.
+ *
+ * Tools, one data path:
+ *   d365_envs       which environments exist and whether they authenticate
+ *   d365_metadata   the generic metadata query over a fixed resource catalogue
+ *   d365_layers     the solution-layer stack behind any component
+ *   d365_sync       snapshot an environment's metadata to local files
+ *   d365_diff       compare two snapshots
+ *   d365_configure  read/write the environment list (same storage as the UI)
+ *   d365_write      prepare a metadata change, then confirm and apply it
+ *   d365_migrate    assess what happens if a solution is imported into another environment
+ *   d365_code_check what a merge request's changed scripts break in a target environment
+ *   d365_refs       who references a field, script or plugin assembly
+ *   d365_data       count / group / sample business records (needs `data.read`)
+ *   d365_data_write create or patch one business record (needs `data.write`)
+ *   d365_data_sync  move business records between environments (plan, then confirm)
+ *   d365_invoke     call one action or function and return status + body (needs `message.invoke`)
  *   d365_trace      read plug-in trace logs to explain a failure (needs `data.read`)
- *   d365_flows      Power Automate cloud flows: list, one flow's skeleton, who touches a table
- *   d365_contract   compare plugin registration / option values across environments
- *   d365_health     stuck jobs, running imports, recently installed solutions
- *   d365_reports    what this plugin wrote to disk, and how much space it takes
- *
- * Reads go through `lib/client.js`, which sends GET only and splits reads in
- * two: metadata (always allowed) and business records (needs `data.read` for
- * that environment, resolved by `lib/data-policy.js`). The single metadata
- * write path lives in `lib/write-actions.js` and always runs behind a plan that
- * a human approves; business record writes live in `lib/tool-data-write.js`,
- * are gated by `data.write`, and always ask for confirmation first.
- *
- * The Web UI half contributes a settings page ("D365 工具箱") that saves through
- * the same `lib/settings-store.js` functions as `d365_configure`, and reaches
- * the Host through the routes in `lib/settings-http.js`.
- */
-import { register as registerEnvironments } from './lib/tool-environments.js'
-import { register as registerMetadata } from './lib/tool-metadata.js'
-import { register as registerLayers } from './lib/tool-layers.js'
-import { register as registerSync } from './lib/tool-sync.js'
-import { register as registerDiff } from './lib/tool-diff.js'
-import { register as registerConfigure } from './lib/tool-configure.js'
-import { register as registerWrite } from './lib/tool-write.js'
-import { register as registerMigrate } from './lib/tool-migrate.js'
-import { register as registerCodeCheck } from './lib/tool-code-check.js'
-import { register as registerRefs } from './lib/tool-refs.js'
-import { register as registerData } from './lib/tool-data.js'
-import { register as registerDataWrite } from './lib/tool-data-write.js'
-import { register as registerContract } from './lib/tool-contract.js'
-import { register as registerHealth } from './lib/tool-health.js'
-import { register as registerReports } from './lib/tool-reports.js'
-import { register as registerDataSync } from './lib/tool-data-sync.js'
-import { register as registerInvoke } from './lib/tool-invoke.js'
+ *   d365_flows      Power Automate cloud flows: list, one flow's skeleton, who touches a table
+ *   d365_contract   compare plugin registration / option values across environments
+ *   d365_health     stuck jobs, running imports, recently installed solutions
+ *   d365_reports    what this plugin wrote to disk, and how much space it takes
+ *
+ * Reads go through `lib/client.js`, which sends GET only and splits reads in
+ * two: metadata (always allowed) and business records (needs `data.read` for
+ * that environment, resolved by `lib/data-policy.js`). The single metadata
+ * write path lives in `lib/write-actions.js` and always runs behind a plan that
+ * a human approves; business record writes live in `lib/tool-data-write.js`,
+ * are gated by `data.write`, and always ask for confirmation first.
+ *
+ * The Web UI half contributes a settings page ("D365 工具箱") that saves through
+ * the same `lib/settings-store.js` functions as `d365_configure`, and reaches
+ * the Host through the routes in `lib/settings-http.js`.
+ */
+import { register as registerEnvironments } from './lib/tool-environments.js'
+import { register as registerMetadata } from './lib/tool-metadata.js'
+import { register as registerLayers } from './lib/tool-layers.js'
+import { register as registerSync } from './lib/tool-sync.js'
+import { register as registerDiff } from './lib/tool-diff.js'
+import { register as registerConfigure } from './lib/tool-configure.js'
+import { register as registerWrite } from './lib/tool-write.js'
+import { register as registerMigrate } from './lib/tool-migrate.js'
+import { register as registerCodeCheck } from './lib/tool-code-check.js'
+import { register as registerRefs } from './lib/tool-refs.js'
+import { register as registerData } from './lib/tool-data.js'
+import { register as registerDataWrite } from './lib/tool-data-write.js'
+import { register as registerContract } from './lib/tool-contract.js'
+import { register as registerHealth } from './lib/tool-health.js'
+import { register as registerReports } from './lib/tool-reports.js'
+import { register as registerDataSync } from './lib/tool-data-sync.js'
+import { register as registerInvoke } from './lib/tool-invoke.js'
 import { register as registerTrace } from './lib/tool-trace.js'
-import { register as registerFlows } from './lib/tool-flows.js'
-import { registerRoutes } from './lib/settings-http.js'
-import { registerSkills } from './lib/skill.js'
-import { setCapabilityResolver, setDataReadResolver, setDataWriteResolver, setMetadataReadResolver } from './lib/client.js'
-import { makeAnyCapabilityResolver, makeDataReadResolver, makeDataWriteResolver, makeMetadataReadResolver } from './lib/data-policy.js'
-
-export const name = 'dsh-d365-kit'
-
-/** Tools are required; the HTTP carrier is looked up optionally via `ctx.get`. */
-export const inject = ['tools']
-
-/** Guards the route registration against the two attach paths colliding. */
-let routesAttached = false
-
-/**
- * Install the tools and, when a web server is present, the settings routes.
- * @param ctx - host context.
- * @param config - the `config` block from cordis.patch.yml.
- */
-export function apply(ctx, config = {}) {
-  const state = { rawConfig: config ?? {} }
-
-  // Every request consults the policy file: metadata reads, business-record
-  // reads and writes are separate capabilities granted per environment.
-  setMetadataReadResolver(makeMetadataReadResolver(() => state.rawConfig))
-  setDataReadResolver(makeDataReadResolver(() => state.rawConfig))
-  setDataWriteResolver(makeDataWriteResolver(() => state.rawConfig))
-  setCapabilityResolver(makeAnyCapabilityResolver(() => state.rawConfig))
-
-  const disposers = [
-    registerEnvironments(ctx, state),
-    registerMetadata(ctx, state),
-    registerLayers(ctx, state),
-    registerSync(ctx, state),
-    registerDiff(ctx, state),
-    registerConfigure(ctx, state),
-    registerWrite(ctx, state),
-    registerMigrate(ctx, state),
-    registerCodeCheck(ctx, state),
-    registerRefs(ctx, state),
-    registerData(ctx, state),
-    registerDataWrite(ctx, state),
-    registerDataSync(ctx, state),
-    registerInvoke(ctx, state),
+import { register as registerFlows } from './lib/tool-flows.js'
+import { registerRoutes } from './lib/settings-http.js'
+import { registerSkills } from './lib/skill.js'
+import { setCapabilityResolver, setDataReadResolver, setDataWriteResolver, setMetadataReadResolver } from './lib/client.js'
+import { makeAnyCapabilityResolver, makeDataReadResolver, makeDataWriteResolver, makeMetadataReadResolver } from './lib/data-policy.js'
+
+export const name = 'dsh-d365-kit'
+
+/** Tools are required; the HTTP carrier is looked up optionally via `ctx.get`. */
+export const inject = ['tools']
+
+/** Guards the route registration against the two attach paths colliding. */
+let routesAttached = false
+
+/**
+ * Install the tools and, when a web server is present, the settings routes.
+ * @param ctx - host context.
+ * @param config - the `config` block from cordis.patch.yml.
+ */
+export function apply(ctx, config = {}) {
+  const state = { rawConfig: config ?? {} }
+
+  // Every request consults the policy file: metadata reads, business-record
+  // reads and writes are separate capabilities granted per environment.
+  setMetadataReadResolver(makeMetadataReadResolver(() => state.rawConfig))
+  setDataReadResolver(makeDataReadResolver(() => state.rawConfig))
+  setDataWriteResolver(makeDataWriteResolver(() => state.rawConfig))
+  setCapabilityResolver(makeAnyCapabilityResolver(() => state.rawConfig))
+
+  const disposers = [
+    registerEnvironments(ctx, state),
+    registerMetadata(ctx, state),
+    registerLayers(ctx, state),
+    registerSync(ctx, state),
+    registerDiff(ctx, state),
+    registerConfigure(ctx, state),
+    registerWrite(ctx, state),
+    registerMigrate(ctx, state),
+    registerCodeCheck(ctx, state),
+    registerRefs(ctx, state),
+    registerData(ctx, state),
+    registerDataWrite(ctx, state),
+    registerDataSync(ctx, state),
+    registerInvoke(ctx, state),
     registerTrace(ctx, state),
-    registerFlows(ctx, state),
-    registerContract(ctx, state),
-    registerHealth(ctx, state),
-    registerReports(ctx, state),
-  ]
-
-  ctx.effect(() => () => {
-    for (const dispose of disposers) {
-      try {
-        dispose?.()
-      } catch {
-        // A failed unregister must not block the remaining ones.
-      }
-    }
-  })
-
-  // The troubleshooting skill travels with the package: registering it here is
-  // what makes installing the bundle enough, with no file to copy by hand.
-  registerSkills(ctx)
-
-  // Looked up rather than declared: a headless profile has no HTTP carrier and
-  // must not keep the plugin inactive. The settings routes live on the
-  // authenticated `/api` channel that `ctx.connection` owns.
-  const attachRoutes = (host) => {
-    if (routesAttached) return
-    const connection = typeof host.get === 'function' ? host.get('connection') : undefined
-    if (!connection) return
-    // The write routes compare the browser Origin against this origin; without
-    // it they refuse, which is the intended failure mode.
-    let origin
-    try {
-      origin = typeof host.get === 'function' ? host.get('webServer')?.getOrigin?.() : undefined
-    } catch {
-      origin = undefined
-    }
-    routesAttached = true
-    host.effect(() => {
-      routesAttached = false
-      return registerRoutes({ connection, origin }, state)
-    })
-  }
-  if (typeof ctx.inject === 'function') ctx.inject(['connection'], attachRoutes)
-  attachRoutes(ctx)
-}
+    registerFlows(ctx, state),
+    registerContract(ctx, state),
+    registerHealth(ctx, state),
+    registerReports(ctx, state),
+  ]
+
+  ctx.effect(() => () => {
+    for (const dispose of disposers) {
+      try {
+        dispose?.()
+      } catch {
+        // A failed unregister must not block the remaining ones.
+      }
+    }
+  })
+
+  // The troubleshooting skill travels with the package: registering it here is
+  // what makes installing the bundle enough, with no file to copy by hand.
+  registerSkills(ctx)
+
+  // Looked up rather than declared: a headless profile has no HTTP carrier and
+  // must not keep the plugin inactive. The settings routes live on the
+  // authenticated `/api` channel that `ctx.connection` owns.
+  const attachRoutes = (host) => {
+    if (routesAttached) return
+    const connection = typeof host.get === 'function' ? host.get('connection') : undefined
+    if (!connection) return
+    // The write routes compare the browser Origin against this origin; without
+    // it they refuse, which is the intended failure mode.
+    let origin
+    try {
+      origin = typeof host.get === 'function' ? host.get('webServer')?.getOrigin?.() : undefined
+    } catch {
+      origin = undefined
+    }
+    routesAttached = true
+    host.effect(() => {
+      routesAttached = false
+      return registerRoutes({ connection, origin }, state)
+    })
+  }
+  if (typeof ctx.inject === 'function') ctx.inject(['connection'], attachRoutes)
+  attachRoutes(ctx)
+}

package/lib/auth.js

@@ -1,181 +1,181 @@
-/**
- * OAuth2 client-credentials tokens for Dataverse.
- *
- * One token per environment, cached until shortly before expiry. The token is
- * requested against the environment's own URL, which is what Dataverse
- * requires (a token for another environment is rejected with 401).
- */
-import { createHash } from 'node:crypto'
-import { resolveCredential } from './config.js'
-import { D365Error } from './errors.js'
-
-/** Cloud-specific Entra ID authorities. The resource scope is always the env URL. */
-const AUTHORITY = {
-  public: 'https://login.microsoftonline.com',
-  usgovernment: 'https://login.microsoftonline.us',
-  dod: 'https://login.microsoftonline.us',
-  china: 'https://login.partner.microsoftonline.cn',
-}
-
-export const KNOWN_CLOUDS = Object.keys(AUTHORITY)
-
-/** @type {Map<string, { token: string, expiresAt: number, fingerprint: string }>} */
-const tokenCache = new Map()
-
-/**
- * Token requests that are already in flight, per environment.
- *
- * Without this, N requests issued at the same moment (a business-data sync
- * writes with a concurrency of 4, a multi-environment query fans out per
- * environment) each missed the cache and each POSTed to Entra — six concurrent
- * requests used to mean six token requests. They now await one POST.
- * @type {Map<string, { promise: Promise<string>, fingerprint: string | undefined }>}
- */
-const tokenPending = new Map()
-
-/** Renew this long before `expires_in` runs out, so an in-flight request never races the expiry. */
-const REFRESH_SKEW_MS = 120_000
-
-/**
- * Fingerprint of the values a token was minted from.
- *
- * Changing the application user in the settings page must take effect on the
- * next call, but the token cache outlives a settings save (and a plugin reload
- * reuses the module). Comparing this fingerprint makes a cached token
- * unusable as soon as the url, tenant, client id or secret changes.
- */
-function credentialFingerprint(env) {
-  const parts = ['tenantId', 'clientId', 'clientSecret'].map((kind) => {
-    const resolved = resolveCredential(env, kind)
-    return resolved.ok ? resolved.value : ''
-  })
-  if (parts.some((part) => !part)) return undefined
-  return createHash('sha256').update([env.url, ...parts].join('\u0000')).digest('hex')
-}
-
-/**
- * Drop a cached token so the next call re-authenticates.
- * @param envKey - environment key.
- */
-export function forgetToken(envKey) {
-  tokenCache.delete(envKey)
-}
-
-function requireCredential(env, kind) {
-  const resolved = resolveCredential(env, kind)
-  if (resolved.ok) return resolved.value
-  throw new D365Error(
-    `环境 ${env.key} 缺少 ${kind}（找不到 ${resolved.missing.join(' 或 ')}）`,
-    {
-      code: 'missing-credential',
-      hint: `在配置里写 ${kind}Env: '${resolved.missing[0]}'，并在启动 harness 的环境中设置该变量。`,
-    },
-  )
-}
-
-/**
- * Acquire (or reuse) an access token for one environment.
- *
- * Three layers keep authentication off the per-request path: the cache, the
- * in-flight map (so concurrent callers share one POST), and the 401 handler in
- * the client, which only forces a refresh when the server actually rejected a
- * token.
- * @param env - normalized environment.
- * @param options - `force` bypasses the cache.
- * @returns a bearer token string.
- */
-export async function getAccessToken(env, options = {}) {
-  const fingerprint = credentialFingerprint(env)
-  const cached = tokenCache.get(env.key)
-  if (
-    !options.force
-    && cached
-    && fingerprint
-    && cached.fingerprint === fingerprint
-    && cached.expiresAt - REFRESH_SKEW_MS > Date.now()
-  ) {
-    return cached.token
-  }
-
-  if (!options.force) {
-    const inFlight = tokenPending.get(env.key)
-    if (inFlight && inFlight.fingerprint === fingerprint) return inFlight.promise
-  }
-
-  const promise = requestToken(env, fingerprint)
-  tokenPending.set(env.key, { promise, fingerprint })
-  try {
-    return await promise
-  } finally {
-    // Only the caller that installed this promise may clear it: a forced
-    // refresh can replace it while the first POST is still running.
-    if (tokenPending.get(env.key)?.promise === promise) tokenPending.delete(env.key)
-  }
-}
-
-/** The actual client-credentials POST. Callers go through `getAccessToken`. */
-async function requestToken(env, fingerprint) {
-  const tenant = requireCredential(env, 'tenantId')
-  const clientId = requireCredential(env, 'clientId')
-  const clientSecret = requireCredential(env, 'clientSecret')
-
-  const authority = (env.authorityHost ?? AUTHORITY[env.cloud] ?? AUTHORITY.public).replace(/\/+$/, '')
-  const url = `${authority}/${encodeURIComponent(tenant)}/oauth2/v2.0/token`
-  const body = new URLSearchParams({
-    grant_type: 'client_credentials',
-    client_id: clientId,
-    client_secret: clientSecret,
-    scope: `${env.url}/.default`,
-  })
-
-  const controller = new AbortController()
-  const timer = setTimeout(() => controller.abort(), 30_000)
-  let response
-  try {
-    response = await fetch(url, {
-      method: 'POST',
-      headers: { 'content-type': 'application/x-www-form-urlencoded' },
-      body,
-      signal: controller.signal,
-    })
-  } catch (error) {
-    throw new D365Error(`环境 ${env.key} 获取令牌失败：${error.message}`, {
-      code: 'token-network',
-      hint: `确认能访问 ${authority}；企业代理需要放行登录与 *.dynamics.com。`,
-    })
-  } finally {
-    clearTimeout(timer)
-  }
-
-  const text = await response.text()
-  let payload
-  try {
-    payload = JSON.parse(text)
-  } catch {
-    throw new D365Error(`环境 ${env.key} 获取令牌失败：HTTP ${response.status}，响应不是 JSON`, {
-      code: 'token-http',
-    })
-  }
-
-  if (!response.ok) {
-    const detail = payload?.error_description ?? payload?.error ?? text.slice(0, 400)
-    throw new D365Error(`环境 ${env.key} 获取令牌失败：HTTP ${response.status} — ${detail}`, {
-      code: 'token-http',
-      status: response.status,
-      hint: '常见原因：密钥过期、应用用户未在目标环境启用、或该环境 URL 与租户不匹配。',
-    })
-  }
-
-  const token = payload?.access_token
-  if (!token) {
-    throw new D365Error(`环境 ${env.key} 获取令牌失败：响应中没有 access_token`, { code: 'token-shape' })
-  }
-
-  const lifetimeMs = Number(payload.expires_in) > 0 ? Number(payload.expires_in) * 1000 : 3600_000
-  tokenCache.set(env.key, {
-    token,
-    expiresAt: Date.now() + lifetimeMs,
-    fingerprint: fingerprint ?? '',
-  })
-  return token
-}
+/**
+ * OAuth2 client-credentials tokens for Dataverse.
+ *
+ * One token per environment, cached until shortly before expiry. The token is
+ * requested against the environment's own URL, which is what Dataverse
+ * requires (a token for another environment is rejected with 401).
+ */
+import { createHash } from 'node:crypto'
+import { resolveCredential } from './config.js'
+import { D365Error } from './errors.js'
+
+/** Cloud-specific Entra ID authorities. The resource scope is always the env URL. */
+const AUTHORITY = {
+  public: 'https://login.microsoftonline.com',
+  usgovernment: 'https://login.microsoftonline.us',
+  dod: 'https://login.microsoftonline.us',
+  china: 'https://login.partner.microsoftonline.cn',
+}
+
+export const KNOWN_CLOUDS = Object.keys(AUTHORITY)
+
+/** @type {Map<string, { token: string, expiresAt: number, fingerprint: string }>} */
+const tokenCache = new Map()
+
+/**
+ * Token requests that are already in flight, per environment.
+ *
+ * Without this, N requests issued at the same moment (a business-data sync
+ * writes with a concurrency of 4, a multi-environment query fans out per
+ * environment) each missed the cache and each POSTed to Entra — six concurrent
+ * requests used to mean six token requests. They now await one POST.
+ * @type {Map<string, { promise: Promise<string>, fingerprint: string | undefined }>}
+ */
+const tokenPending = new Map()
+
+/** Renew this long before `expires_in` runs out, so an in-flight request never races the expiry. */
+const REFRESH_SKEW_MS = 120_000
+
+/**
+ * Fingerprint of the values a token was minted from.
+ *
+ * Changing the application user in the settings page must take effect on the
+ * next call, but the token cache outlives a settings save (and a plugin reload
+ * reuses the module). Comparing this fingerprint makes a cached token
+ * unusable as soon as the url, tenant, client id or secret changes.
+ */
+function credentialFingerprint(env) {
+  const parts = ['tenantId', 'clientId', 'clientSecret'].map((kind) => {
+    const resolved = resolveCredential(env, kind)
+    return resolved.ok ? resolved.value : ''
+  })
+  if (parts.some((part) => !part)) return undefined
+  return createHash('sha256').update([env.url, ...parts].join('\u0000')).digest('hex')
+}
+
+/**
+ * Drop a cached token so the next call re-authenticates.
+ * @param envKey - environment key.
+ */
+export function forgetToken(envKey) {
+  tokenCache.delete(envKey)
+}
+
+function requireCredential(env, kind) {
+  const resolved = resolveCredential(env, kind)
+  if (resolved.ok) return resolved.value
+  throw new D365Error(
+    `环境 ${env.key} 缺少 ${kind}（找不到 ${resolved.missing.join(' 或 ')}）`,
+    {
+      code: 'missing-credential',
+      hint: `在配置里写 ${kind}Env: '${resolved.missing[0]}'，并在启动 harness 的环境中设置该变量。`,
+    },
+  )
+}
+
+/**
+ * Acquire (or reuse) an access token for one environment.
+ *
+ * Three layers keep authentication off the per-request path: the cache, the
+ * in-flight map (so concurrent callers share one POST), and the 401 handler in
+ * the client, which only forces a refresh when the server actually rejected a
+ * token.
+ * @param env - normalized environment.
+ * @param options - `force` bypasses the cache.
+ * @returns a bearer token string.
+ */
+export async function getAccessToken(env, options = {}) {
+  const fingerprint = credentialFingerprint(env)
+  const cached = tokenCache.get(env.key)
+  if (
+    !options.force
+    && cached
+    && fingerprint
+    && cached.fingerprint === fingerprint
+    && cached.expiresAt - REFRESH_SKEW_MS > Date.now()
+  ) {
+    return cached.token
+  }
+
+  if (!options.force) {
+    const inFlight = tokenPending.get(env.key)
+    if (inFlight && inFlight.fingerprint === fingerprint) return inFlight.promise
+  }
+
+  const promise = requestToken(env, fingerprint)
+  tokenPending.set(env.key, { promise, fingerprint })
+  try {
+    return await promise
+  } finally {
+    // Only the caller that installed this promise may clear it: a forced
+    // refresh can replace it while the first POST is still running.
+    if (tokenPending.get(env.key)?.promise === promise) tokenPending.delete(env.key)
+  }
+}
+
+/** The actual client-credentials POST. Callers go through `getAccessToken`. */
+async function requestToken(env, fingerprint) {
+  const tenant = requireCredential(env, 'tenantId')
+  const clientId = requireCredential(env, 'clientId')
+  const clientSecret = requireCredential(env, 'clientSecret')
+
+  const authority = (env.authorityHost ?? AUTHORITY[env.cloud] ?? AUTHORITY.public).replace(/\/+$/, '')
+  const url = `${authority}/${encodeURIComponent(tenant)}/oauth2/v2.0/token`
+  const body = new URLSearchParams({
+    grant_type: 'client_credentials',
+    client_id: clientId,
+    client_secret: clientSecret,
+    scope: `${env.url}/.default`,
+  })
+
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), 30_000)
+  let response
+  try {
+    response = await fetch(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded' },
+      body,
+      signal: controller.signal,
+    })
+  } catch (error) {
+    throw new D365Error(`环境 ${env.key} 获取令牌失败：${error.message}`, {
+      code: 'token-network',
+      hint: `确认能访问 ${authority}；企业代理需要放行登录与 *.dynamics.com。`,
+    })
+  } finally {
+    clearTimeout(timer)
+  }
+
+  const text = await response.text()
+  let payload
+  try {
+    payload = JSON.parse(text)
+  } catch {
+    throw new D365Error(`环境 ${env.key} 获取令牌失败：HTTP ${response.status}，响应不是 JSON`, {
+      code: 'token-http',
+    })
+  }
+
+  if (!response.ok) {
+    const detail = payload?.error_description ?? payload?.error ?? text.slice(0, 400)
+    throw new D365Error(`环境 ${env.key} 获取令牌失败：HTTP ${response.status} — ${detail}`, {
+      code: 'token-http',
+      status: response.status,
+      hint: '常见原因：密钥过期、应用用户未在目标环境启用、或该环境 URL 与租户不匹配。',
+    })
+  }
+
+  const token = payload?.access_token
+  if (!token) {
+    throw new D365Error(`环境 ${env.key} 获取令牌失败：响应中没有 access_token`, { code: 'token-shape' })
+  }
+
+  const lifetimeMs = Number(payload.expires_in) > 0 ? Number(payload.expires_in) * 1000 : 3600_000
+  tokenCache.set(env.key, {
+    token,
+    expiresAt: Date.now() + lifetimeMs,
+    fingerprint: fingerprint ?? '',
+  })
+  return token
+}