@fargowealth/fargo-ai-cli 1.5.0 → 1.5.1

package/src/yida-auth.mjs

@@ -1,309 +0,0 @@
-// YiDA protocol adapted from OpenYida (MIT). See THIRD_PARTY_NOTICES.md.
-import { createHash, randomBytes } from "node:crypto";
-import { readdir } from "node:fs/promises";
-import { homedir } from "node:os";
-import { join } from "node:path";
-import { authenticatedRequest } from "./api-client.mjs";
-import { openBrowser } from "./auth.mjs";
-import { createCredentialStore } from "./credential-store.mjs";
-import { createLoopbackReceiver } from "./loopback-receiver.mjs";
-import { CLI_VERSION, DEFAULT_AUTH_URL, DEFAULT_MCP_URL } from "./constants.mjs";
-
-const CLIENT_ID = "suite9xvlxxerybljwheo";
-const AUTH_PATH = "/openapi/cli/v1/auth";
-const PROFILE_ID = /^[a-f0-9]{64}$/;
-
-export function yidaOrigin(value) {
-  let url;
-  try { url = new URL(value); } catch { throw new Error("YIDA_INVALID_ORIGIN: expected an HTTPS YiDA origin"); }
-  const host = url.hostname;
-  if (url.protocol !== "https:" || url.username || url.password || url.port || url.search || url.hash ||
-      (url.pathname !== "/" && url.pathname !== "") ||
-      !(host === "aliwork.com" || host.endsWith(".aliwork.com") || host === "yidaapps.com" || host.endsWith(".yidaapps.com"))) {
-    throw new Error("YIDA_INVALID_ORIGIN: only HTTPS aliwork.com or yidaapps.com origins are supported");
-  }
-  return url.origin;
-}
-
-export async function resolveYidaOwner(fargoStore, options = {}) {
-  if (options.resolveYidaOwner) return validateOwner(await options.resolveYidaOwner());
-  const response = await authenticatedRequest(fargoStore,
-    options.mcpUrl ?? process.env.FARGO_MCP_URL ?? DEFAULT_MCP_URL, {
-      method: "POST",
-      headers: { Accept: "application/json", "Content-Type": "application/json", "MCP-Protocol-Version": "2025-11-25" },
-      body: JSON.stringify({ jsonrpc: "2.0", id: randomBytes(12).toString("hex"), method: "tools/call", params: { name: "ping_who_am_i", arguments: {} } })
-    }, options);
-  if (!response.ok) throw new Error(`YIDA_FARGO_IDENTITY_REQUIRED: Fargo identity check failed (HTTP ${response.status})`);
-  const rpc = await response.json();
-  let identity = rpc.result?.structuredContent;
-  if (!identity) {
-    const block = rpc.result?.content?.find(item => item.type === "text");
-    try { identity = JSON.parse(block?.text ?? "null"); } catch { /* Fail closed below. */ }
-  }
-  if (rpc.error || rpc.result?.isError || identity?.authenticated !== true) throw new Error("YIDA_FARGO_IDENTITY_REQUIRED: Fargo identity could not be verified");
-  const credential = await fargoStore.load();
-  return validateOwner({
-    issuer: credential?.auth_url ?? options.authUrl ?? process.env.FARGO_AUTH_URL ?? DEFAULT_AUTH_URL,
-    accountId: identity.account?.id,
-    organizationId: identity.account?.organizationId
-  });
-}
-
-function validateOwner(owner) {
-  if (!owner || [owner.issuer, owner.accountId, owner.organizationId].some(value => typeof value !== "string" || !value || value.length > 512)) {
-    throw new Error("YIDA_FARGO_IDENTITY_REQUIRED: Fargo account and organization are required");
-  }
-  return { issuer: owner.issuer, accountId: owner.accountId, organizationId: owner.organizationId };
-}
-
-const digest = value => createHash("sha256").update(JSON.stringify(value)).digest("hex");
-function profileDirectory(owner, options) {
-  const home = options.yidaHome ?? homedir();
-  const root = options.yidaDirectory ?? (process.platform === "win32" ? join(process.env.APPDATA || home, "Fargo AI", "yida") : join(home, ".fargo", "yida"));
-  return join(root, digest(owner));
-}
-
-function profileStore(owner, profile, options) {
-  if (!PROFILE_ID.test(profile)) throw new Error("YIDA_PROFILE_INVALID: expected an exact profile ID");
-  const directory = profileDirectory(owner, options);
-  return createCredentialStore({
-    env: { FARGO_CREDENTIAL_STORE: "file", FARGO_CREDENTIAL_PATH: join(directory, `${profile}.json`), FARGO_REFRESH_LOCK_PATH: join(directory, `${profile}.lock`) }
-  });
-}
-
-function checkSession(session, owner, profile) {
-  if (!session || digest(session.owner) !== digest(owner) || session.profile !== profile || !session.corp_id || !session.user_id) {
-    throw new Error("YIDA_PROFILE_INVALID: the saved authorization does not belong to this Fargo account");
-  }
-  yidaOrigin(session.base_url);
-  yidaOrigin(session.auth_origin);
-  return session;
-}
-
-function profileSummary(session) {
-  return {
-    profile: session.profile, corpId: session.corp_id, userId: session.user_id,
-    baseUrl: session.base_url, expiresAt: session.expires_at ?? null, refreshable: Boolean(session.refresh_token)
-  };
-}
-
-async function profilesForOwner(owner, options) {
-  const entries = await readdir(profileDirectory(owner, options), { withFileTypes: true }).catch(error => {
-    if (error.code === "ENOENT") return [];
-    throw error;
-  });
-  const profiles = [];
-  for (const entry of entries) {
-    const profile = entry.name.replace(/\.json$/, "");
-    if (!entry.name.endsWith(".json") || !PROFILE_ID.test(profile)) continue;
-    const session = await profileStore(owner, profile, options).load();
-    if (session) profiles.push(profileSummary(checkSession(session, owner, profile)));
-  }
-  return profiles.sort((a, b) => a.profile.localeCompare(b.profile));
-}
-
-export async function yidaStatus(fargoStore, options = {}) {
-  const owner = await resolveYidaOwner(fargoStore, options);
-  const profiles = await profilesForOwner(owner, options);
-  return { connected: profiles.length > 0, validation: "local_metadata_only", profiles };
-}
-
-async function selectSession(fargoStore, options) {
-  const owner = await resolveYidaOwner(fargoStore, options);
-  let profile = options.profile;
-  if (!profile) {
-    const profiles = await profilesForOwner(owner, options);
-    if (profiles.length !== 1) throw new Error(profiles.length ? "YIDA_PROFILE_REQUIRED: multiple authorizations exist; select --profile" : "YIDA_BINDING_REQUIRED: run 'fargo yida auth login' first");
-    profile = profiles[0].profile;
-  }
-  const store = profileStore(owner, profile, options);
-  const session = await store.load();
-  if (!session) throw new Error("YIDA_BINDING_REQUIRED: authorization not found for the current Fargo account");
-  return { owner, store, session: checkSession(session, owner, profile) };
-}
-
-async function jsonRequest(origin, path, body, options = {}, accessToken, encoding = "json") {
-  const response = await (options.yidaFetchImpl ?? options.fetchImpl ?? fetch)(new URL(path, yidaOrigin(origin)), {
-    method: body === undefined ? "GET" : "POST",
-    redirect: "error",
-    signal: AbortSignal.timeout(options.yidaTimeoutMs ?? 30_000),
-    headers: {
-      Accept: "application/json", "User-Agent": `fargo-cli/${CLI_VERSION}`,
-      ...(body === undefined || encoding === "form" ? { Origin: yidaOrigin(origin), Referer: `${yidaOrigin(origin)}/`, "X-Requested-With": "XMLHttpRequest" } : {}),
-      ...(body === undefined ? {} : { "Content-Type": encoding === "form" ? "application/x-www-form-urlencoded" : "application/json" }),
-      ...(accessToken ? { Authorization: `Bearer ${accessToken}` } : {})
-    },
-    ...(body === undefined ? {} : { body: encoding === "form" ? new URLSearchParams(body).toString() : JSON.stringify(body) })
-  });
-  const payload = await response.json().catch(() => null);
-  if (!payload && response.ok) throw new Error("YIDA_UNEXPECTED_RESPONSE: the endpoint returned no JSON schema; verify environment and personal-token support");
-  // Do not echo upstream bodies: error messages can contain credentials or URLs.
-  const code = payload?.code ?? payload?.errorCode ?? payload?.error;
-  const authRequired = response.status === 401 || payload?.__needLogin === true || ["invalid_access_token", "expired_access_token", "access_token_expired", "missing_access_token"].includes(code);
-  if (!response.ok || !payload || payload.success === false || payload.ok === false || authRequired) {
-    const forbidden = response.status === 403 || (typeof code === "string" && code.startsWith("noPermission."));
-    const error = new Error(forbidden ? "YIDA_UPSTREAM_FORBIDDEN: current user cannot access this resource" : `YIDA_UPSTREAM_ERROR: request failed (HTTP ${response.status})`);
-    error.status = response.status;
-    error.authRequired = authRequired;
-    if (typeof code === "string" && /^[A-Za-z0-9_.-]{1,120}$/.test(code)) error.upstreamCode = code;
-    throw error;
-  }
-  return payload;
-}
-
-function normalizedToken(payload, context, previous = {}) {
-  const value = payload.data ?? payload.content ?? payload;
-  const accessToken = value.access_token ?? value.accessToken;
-  const corpId = value.corp_id ?? value.corpId ?? previous.corp_id;
-  const userId = value.user_id ?? value.userId ?? previous.user_id;
-  const refreshToken = value.refresh_token ?? value.refreshToken ?? previous.refresh_token ?? "";
-  if (typeof accessToken !== "string" || !/^[\x21-\x7e]{1,16384}$/.test(accessToken) || typeof refreshToken !== "string" || refreshToken.length > 16384 || typeof corpId !== "string" || !corpId || typeof userId !== "string" || !userId) {
-    throw new Error("YIDA_TOKEN_RESPONSE_INVALID: the service did not return a token and enterprise member identity");
-  }
-  if ((previous.corp_id && previous.corp_id !== corpId) || (previous.user_id && previous.user_id !== userId)) {
-    throw new Error("YIDA_IDENTITY_CHANGED: reauthorize the intended enterprise account");
-  }
-  const expires = value.expires_at ?? value.expiresAt;
-  const parsedExpiry = typeof expires === "string" && !/^\d+$/.test(expires) ? Date.parse(expires) : Number(expires);
-  const expiresIn = Number(value.expires_in ?? value.expiresIn);
-  return {
-    ...context, access_token: accessToken,
-    refresh_token: refreshToken,
-    corp_id: corpId, user_id: userId,
-    base_url: yidaOrigin(value.base_url ?? value.baseUrl ?? previous.base_url ?? context.auth_origin),
-    expires_at: Number.isFinite(parsedExpiry) && parsedExpiry > 0 ? (parsedExpiry < 1e12 ? parsedExpiry * 1000 : parsedExpiry) : (expiresIn > 0 ? Date.now() + expiresIn * 1000 : null)
-  };
-}
-
-export async function yidaLogin(fargoStore, options = {}) {
-  const owner = await resolveYidaOwner(fargoStore, options);
-  const authOrigin = yidaOrigin(options.endpoint ?? "https://www.aliwork.com");
-  const clientId = options.yidaClientId ?? CLIENT_ID;
-  const state = randomBytes(32).toString("base64url");
-  const receiver = await (options.yidaLoopbackFactory ?? createLoopbackReceiver)({ expectedState: state, callbackPath: "/oauth/callback", timeoutMs: options.authorizationTimeoutMs });
-  const callbackPromise = receiver.waitForCallback();
-  void callbackPromise.catch(() => {});
-  try {
-    const url = new URL("/oauth2/auth", authOrigin.endsWith("yidaapps.com") ? "https://login.dingtalk.io" : "https://login.dingtalk.com");
-    url.search = new URLSearchParams({ client_id: clientId, redirect_uri: receiver.redirectUri, response_type: "code", scope: "openid corpid", state, prompt: "consent" }).toString();
-    await options.onYidaAuthorization?.({ authorizationUrl: url.toString() });
-    if (options.openBrowser !== false) await (options.browserOpener ?? openBrowser)(url.toString());
-    const callback = await callbackPromise;
-    if (callback.searchParams.get("state") !== state || callback.searchParams.has("error")) throw new Error("YIDA_OAUTH_FAILED: authorization callback could not be verified");
-    const code = callback.searchParams.get("code") || callback.searchParams.get("authCode") || callback.searchParams.get("auth_code");
-    if (!code) throw new Error("YIDA_OAUTH_FAILED: authorization code is missing");
-    const payload = await jsonRequest(authOrigin, `${AUTH_PATH}/dingtalk/token`, { code, authCode: callback.searchParams.get("authCode") || code, redirectUri: receiver.redirectUri, state, clientId }, options);
-    const session = normalizedToken(payload, { owner, auth_origin: authOrigin, client_id: clientId });
-    if (options.corpId && options.corpId !== session.corp_id) throw new Error("YIDA_ENTERPRISE_MISMATCH: the authorized account belongs to a different enterprise");
-    if (digest(await resolveYidaOwner(fargoStore, options)) !== digest(owner)) throw new Error("YIDA_FARGO_ACCOUNT_CHANGED: restart authorization for the current Fargo account");
-    session.profile = digest([owner, session.auth_origin, session.client_id, session.corp_id, session.user_id]);
-    const store = profileStore(owner, session.profile, options);
-    await store.withRefreshLock(() => store.save(session));
-    return { connected: true, ...profileSummary(session) };
-  } finally { await receiver.close(); }
-}
-
-async function refreshSession(selected, options) {
-  return selected.store.withRefreshLock(async () => {
-    const latest = await selected.store.load();
-    if (!latest) throw new Error("YIDA_BINDING_REVOKED: authorization was removed locally");
-    checkSession(latest, selected.owner, selected.session.profile);
-    if (latest.access_token !== selected.session.access_token || latest.refresh_token !== selected.session.refresh_token) return latest;
-    if (!latest.refresh_token) throw new Error("YIDA_REAUTH_REQUIRED: authorization cannot be refreshed; run 'fargo yida auth login'");
-    const payload = await jsonRequest(latest.auth_origin, `${AUTH_PATH}/refresh`, { refreshToken: latest.refresh_token, clientId: latest.client_id }, options);
-    const next = normalizedToken(payload, { owner: selected.owner, auth_origin: latest.auth_origin, client_id: latest.client_id, profile: latest.profile }, latest);
-    await selected.store.save(next);
-    return next;
-  });
-}
-
-export async function yidaRead(fargoStore, requestPath, options = {}) {
-  const dataRead = /^\/dingtalk\/web\/APP_[A-Za-z0-9_-]+\/v1\/(?:process\/(?:getInstances|getInstanceById)|form\/(?:searchFormDatas|getFormDataById))\.json\?/.test(requestPath ?? "");
-  const uploadSign = /^\/ossSign\?/.test(requestPath ?? "");
-  const formBinding = /^\/APP_[A-Za-z0-9_-]+\/query\/formProcBinding\/getBindingByFormUuid\.json\?/.test(requestPath ?? "");
-  const formNavigation = /^\/dingtalk\/web\/APP_[A-Za-z0-9_-]+\/query\/formnav\/getFormNavigationListByOrder\.json\?/.test(requestPath ?? "");
-  if (typeof requestPath !== "string" || (!requestPath.startsWith("/alibaba/web/") && !dataRead && !uploadSign && !formBinding && !formNavigation) || requestPath.includes("\\") || requestPath.includes("..") || requestPath.startsWith("//")) throw new Error("YIDA_REQUEST_INVALID");
-  const selected = await selectSession(fargoStore, options);
-  try { return await jsonRequest(selected.session.base_url, requestPath, undefined, options, selected.session.access_token); }
-  catch (error) {
-    if (!error.authRequired) throw error;
-    const refreshed = await refreshSession(selected, options);
-    return jsonRequest(refreshed.base_url, requestPath, undefined, options, refreshed.access_token);
-  }
-}
-
-// YiDA's page runtime uses POST for read-only lookup expressions. Admit only
-// the lookup DSL, never general formulas (which can contain write functions).
-export async function yidaLookupExpression(fargoStore, appType, formUuid, expression, options = {}) {
-  if (!/^APP_[A-Za-z0-9_-]{1,200}$/.test(appType ?? "") || !/^FORM-[A-Za-z0-9_-]{1,200}$/.test(formUuid ?? "") ||
-      typeof expression !== "string" || expression.length > 16000 || !expression.startsWith(`{${appType}}@FETCHDISTINCTDATA(`)) throw new Error("YIDA_LOOKUP_INVALID");
-  let source = expression.slice(appType.length + 3);
-  source = source.replace(/"(?:\\.|[^"\\])*"/g, value => { JSON.parse(value); return "0"; });
-  const allowed = new Set(["FETCHDISTINCTDATA", "QUERYAND", "QUERYOR", "QUERYEQ", "QUERYNE", "QUERYLIKECI", "QUERYLIKE", "QUERYGT", "QUERYGE", "QUERYLT", "QUERYLE", "QUERYIN"]);
-  const names = [...source.matchAll(/([A-Za-z_][A-Za-z0-9_]*)\s*\(/g)].map(match => match[1]);
-  if (!names.length || names.some(name => !allowed.has(name)) || /[^\d\s(),.\-]/.test(source.replace(/[A-Z_]+\s*\(/g, "(").replace(/\b(?:true|false|null)\b/g, "0"))) throw new Error("YIDA_LOOKUP_INVALID");
-  let depth = 0;
-  for (const char of source) { if (char === "(") depth++; if (char === ")" && --depth < 0) throw new Error("YIDA_LOOKUP_INVALID"); }
-  if (depth) throw new Error("YIDA_LOOKUP_INVALID");
-  const selected = await selectSession(fargoStore, options);
-  const path = `/${appType}/query/expression/evaluate.json`;
-  const fields = { formUuid, expression, _api: "nattyFetch", _mock: "false" };
-  try { return await jsonRequest(selected.session.base_url, path, fields, options, selected.session.access_token, "form"); }
-  catch (error) {
-    if (!error.authRequired) throw error;
-    const refreshed = await refreshSession(selected, options);
-    return jsonRequest(refreshed.base_url, path, fields, options, refreshed.access_token, "form");
-  }
-}
-
-// Reviewed read-only adapters for the two connectors used by this business.
-// HR queries are always bound to the token's member, never a supplied user ID.
-export async function yidaApplicantConnector(fargoStore, connector, operation, departmentId, options = {}) {
-  const hr = operation === "self_hr" && connector?.connectorId === "Http_5c72b42d47f14a1983767932f6c1d4f1" && connector.actionId === "getUserMessage" && connector.connection === 15597;
-  const dept = operation === "department" && connector?.connectorId === "Http_75b8f8aef03c4b40815462052ba21a13" && connector.actionId === "operation-1" && connector.connection === 15624 && /^\d{1,20}$/.test(departmentId ?? "");
-  if (!hr && !dept) throw new Error("YIDA_CONNECTOR_ADAPTER_UNSUPPORTED");
-  const selected = await selectSession(fargoStore, options);
-  const inputs = hr ? { "Content-Type": "application/json", Query: { agentid: "3195124669", userid_list: selected.session.user_id } } :
-    { "Content-Type": "application/json", Body: { dept_id: departmentId } };
-  const fields = { inputs: JSON.stringify(inputs), serviceInfo: JSON.stringify({ connectorInfo: {
-    connectorId: connector.connectorId, actionId: connector.actionId, connection: connector.connection, type: "httpConnector"
-  } }) };
-  // Both operations are reads, but do not automatically replay connector calls.
-  return jsonRequest(selected.session.base_url, "/query/publicService/invokeService.json", fields, options, selected.session.access_token, "form");
-}
-
-// Internal transport for explicitly prepared requests. Never replay a mutation,
-// even after a token rejection. Refresh through a read before calling this function.
-// The MCP bridge does not expose arbitrary paths or raw write arguments.
-export async function yidaPostFormOnce(fargoStore, requestPath, fields, options = {}) {
-  let selected;
-  try {
-    if (typeof requestPath !== "string" || !(/^\/dingtalk\/web\/APP_[A-Za-z0-9_-]+\/v1\/process\/(?:startInstance|terminateInstance)\.json$/.test(requestPath) || requestPath === "/query/attach/uploadCallBack.json")) throw new Error("YIDA_REQUEST_INVALID");
-    if (!fields || typeof fields !== "object" || Array.isArray(fields) || Object.values(fields).some(value => typeof value !== "string") || JSON.stringify(fields).length > 2_000_000) throw new Error("YIDA_WRITE_INVALID: expected bounded form-encoded string values");
-    const expected = options.expectedYidaPrincipal;
-    if (!expected || !options.profile || [expected.corpId, expected.userId, expected.baseUrl].some(value => typeof value !== "string" || !value)) throw new Error("YIDA_WRITE_PRINCIPAL_REQUIRED: bind the prepared request to its exact local profile and enterprise/member");
-    await options.revalidateYidaTaskOwner?.();
-    selected = await selectSession(fargoStore, options);
-    if (options.expectedFargoOwner && digest(options.expectedFargoOwner) !== digest(selected.owner)) throw new Error("YIDA_FARGO_ACCOUNT_CHANGED");
-    if (selected.session.corp_id !== expected.corpId || selected.session.user_id !== expected.userId || selected.session.base_url !== expected.baseUrl) throw new Error("YIDA_WRITE_PRINCIPAL_MISMATCH: the prepared request belongs to a different identity");
-    if (digest(await resolveYidaOwner(fargoStore, options)) !== digest(selected.owner)) throw new Error("YIDA_FARGO_ACCOUNT_CHANGED");
-  } catch (error) {
-    error.yidaRequestSent = false;
-    error.yidaMutationNotApplied = true;
-    throw error;
-  }
-  return jsonRequest(selected.session.base_url, requestPath, fields, options, selected.session.access_token, "form");
-}
-
-export async function yidaLogout(fargoStore, options = {}) {
-  const selected = await selectSession(fargoStore, options);
-  return selected.store.withRefreshLock(async () => {
-    const current = await selected.store.load();
-    let remoteRevoked = false;
-    if (current?.refresh_token) {
-      try { await jsonRequest(current.auth_origin, `${AUTH_PATH}/logout`, { refreshToken: current.refresh_token }, options, current.access_token); remoteRevoked = true; } catch { /* Local removal is still effective. */ }
-    }
-    await selected.store.clear();
-    return { disconnected: true, profile: selected.session.profile, remoteRevoked };
-  });
-}

package/src/yida-bundle-format.mjs

@@ -1,77 +0,0 @@
-// Shared by the local connector and the LEGO business-package publisher.
-export const YIDA_BUNDLE_FORMAT = "fargo.yida-business/v1";
-export const YIDA_CONNECTOR_APP_ID = "app_5c7114fa1a53";
-export const BUSINESS_ID = /^[a-z][a-z0-9_]{0,79}$/;
-export const HASH = /^sha256:[a-f0-9]{64}$/;
-export const MAX_BUNDLE_BYTES = 2_000_000;
-
-function fail(message) { throw new Error(`YIDA_BUNDLE_INVALID: ${message}`); }
-export function canonicalJson(value) {
-  if (value === null || typeof value === "boolean" || typeof value === "string") return JSON.stringify(value);
-  if (typeof value === "number" && Number.isFinite(value)) return JSON.stringify(value);
-  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
-  if (value && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype) {
-    return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(",")}}`;
-  }
-  fail("expected JSON values");
-}
-export async function bundleHash(value) {
-  const { bundleHash: ignored, ...body } = value;
-  const bytes = new TextEncoder().encode(canonicalJson(body));
-  if (bytes.length > MAX_BUNDLE_BYTES) fail("package too large");
-  const digest = await crypto.subtle.digest("SHA-256", bytes);
-  return `sha256:${Array.from(new Uint8Array(digest), byte => byte.toString(16).padStart(2, "0")).join("")}`;
-}
-
-function versionParts(value) {
-  if (typeof value !== "string" || !/^\d{1,6}\.\d{1,6}\.\d{1,6}$/.test(value)) fail("expected a release version x.y.z");
-  return value.split(".").map(Number);
-}
-export function versionAtLeast(actual, required) {
-  const a = versionParts(actual);
-  const b = versionParts(required);
-  for (let i = 0; i < 3; i++) if (a[i] !== b[i]) return a[i] > b[i];
-  return true;
-}
-
-export async function validateBusinessBundle(value, { cliVersion } = {}) {
-  if (!value || value.format !== YIDA_BUNDLE_FORMAT || !BUSINESS_ID.test(value.businessId ?? "") ||
-      !Number.isSafeInteger(value.revision) || value.revision < 1 || !HASH.test(value.bundleHash ?? "")) fail("identity, revision or hash");
-  versionParts(value.version);
-  versionParts(value.minCliVersion);
-  if (cliVersion && !versionAtLeast(cliVersion, value.minCliVersion)) throw new Error("YIDA_CLI_UPGRADE_REQUIRED: this business package requires a newer Fargo CLI");
-  if (typeof value.corpId !== "string" || !/^ding[A-Za-z0-9_-]{1,200}$/.test(value.corpId)) fail("enterprise identity");
-  let origin;
-  try { origin = new URL(value.yidaOrigin); } catch { fail("YiDA origin"); }
-  if (origin.origin !== value.yidaOrigin || origin.protocol !== "https:" || origin.port ||
-      !/^(?:[a-z0-9-]+\.)*(?:aliwork\.com|yidaapps\.com)$/.test(origin.hostname)) fail("YiDA origin");
-  const schema = value.schema;
-  if (!schema || schema.kind !== "yida_business_form" || schema.businessId !== value.businessId ||
-      !/^APP_[A-Za-z0-9_-]{1,200}$/.test(schema.appType ?? "") || !/^FORM-[A-Za-z0-9_-]{1,200}$/.test(schema.formUuid ?? "") ||
-      !HASH.test(schema.schemaHash ?? "") || !Array.isArray(schema.fields) || schema.fieldCount !== schema.fields.length ||
-      ![1, 2].includes(schema.modelVersion) || typeof schema.truncated !== "boolean") fail("business schema");
-  if (schema.modelVersion === 2 && (!schema.runtime || !Array.isArray(schema.runtime.rules) || schema.runtime.ruleCount !== schema.runtime.rules.length ||
-      !Array.isArray(schema.runtime.connectors) || !Array.isArray(schema.runtime.scripts) || schema.runtime.formulasExecuted !== false)) fail("runtime rule metadata");
-  // Generic submission stays disabled; workflow cancellation is a separate,
-  // explicitly declared local capability and never grants upstream permission.
-  if (schema.constraints?.submitEnabled !== false) fail("submission is not enabled by this connector release");
-  const cancellation = schema.capabilities?.cancellation;
-  if (cancellation?.enabled === true && (schema.formType !== "process" || cancellation.mode !== "terminate" ||
-      cancellation.ownRequestsOnly !== true || cancellation.localTool !== "yida_cancel_request" ||
-      JSON.stringify(cancellation.allowedStates) !== '["RUNNING"]' || JSON.stringify(cancellation.terminalStates) !== '["TERMINATED","CANCELED"]' ||
-      !/^TPROC-[A-Za-z0-9_-]{1,200}$/.test(schema.entry?.processCode ?? ""))) fail("workflow cancellation declaration");
-  if (typeof value.handbook !== "string" || !value.handbook.trim() || new TextEncoder().encode(value.handbook).length > 128_000) fail("handbook");
-  if (await bundleHash(value) !== value.bundleHash) throw new Error("YIDA_BUNDLE_HASH_MISMATCH: schema and handbook package integrity check failed");
-  return value;
-}
-
-export function businessBundleSummary(bundle) {
-  return {
-    businessId: bundle.businessId, name: bundle.schema.businessName ?? bundle.businessId,
-    revision: bundle.revision, version: bundle.version, minCliVersion: bundle.minCliVersion,
-    bundleHash: bundle.bundleHash, schemaHash: bundle.schema.schemaHash,
-    corpId: bundle.corpId, yidaOrigin: bundle.yidaOrigin,
-    appType: bundle.schema.appType, formUuid: bundle.schema.formUuid,
-    submitEnabled: false, cancellationEnabled: bundle.schema.capabilities?.cancellation?.enabled === true
-  };
-}

package/src/yida-business.mjs

@@ -1,128 +0,0 @@
-import { createHash, randomUUID } from "node:crypto";
-import { lstat, mkdir, open, readFile, rename, rm } from "node:fs/promises";
-import { homedir } from "node:os";
-import { dirname, join } from "node:path";
-import { createCredentialStore } from "./credential-store.mjs";
-import { CLI_VERSION } from "./constants.mjs";
-import { resolveYidaOwner, yidaStatus } from "./yida-auth.mjs";
-import { describeYidaForm } from "./yida-schema.mjs";
-import { BUSINESS_ID, HASH, MAX_BUNDLE_BYTES, YIDA_CONNECTOR_APP_ID, businessBundleSummary, validateBusinessBundle } from "./yida-bundle-format.mjs";
-
-const digest = value => createHash("sha256").update(JSON.stringify(value)).digest("hex");
-function validateBusinessId(id) {
-  if (typeof id !== "string" || !BUSINESS_ID.test(id)) throw new Error("YIDA_BUSINESS_INVALID: expected a business ID");
-}
-async function context(store, options) {
-  const owner = await resolveYidaOwner(store, options);
-  const status = await yidaStatus(store, { ...options, resolveYidaOwner: async () => owner });
-  if (options.profile !== undefined && !/^[a-f0-9]{64}$/.test(options.profile)) throw new Error("YIDA_PROFILE_INVALID: expected an exact profile ID");
-  if (!options.profile && status.profiles.length > 1) throw new Error("YIDA_PROFILE_REQUIRED: select an authorization profile");
-  const profile = options.profile ? status.profiles.find(item => item.profile === options.profile) : status.profiles[0];
-  if (!profile) throw new Error("YIDA_BINDING_REQUIRED: run 'fargo yida auth login' first");
-  const appId = options.yidaConnectorAppId ?? YIDA_CONNECTOR_APP_ID;
-  if (!/^app_[a-zA-Z0-9_-]{1,150}$/.test(appId)) throw new Error("YIDA_CONNECTOR_INVALID: expected a LEGO App ID");
-  const root = options.yidaBundleDirectory ?? (process.platform === "win32" ? join(process.env.APPDATA || homedir(), "Fargo AI", "yida-business") : join(options.yidaHome ?? homedir(), ".fargo", "yida-business"));
-  return { owner, profile, appId, directory: join(root, digest({ owner, appId, profile: profile.profile })) };
-}
-async function remote(store, ctx, toolName, args, options) {
-  // Import lazily: the MCP client also imports the local YiDA dispatch table.
-  const { callMcpTool } = await import("./mcp-client.mjs");
-  const result = await callMcpTool(store, "app_mcp_tool_call", { appId: ctx.appId, toolName, arguments: args }, options);
-  if (result.isError) throw new Error("YIDA_BUSINESS_FETCH_FAILED: the business publisher denied or failed this request");
-  let value = result.structuredContent;
-  if (!value) {
-    try { value = JSON.parse(result.content?.find(item => item.type === "text")?.text ?? "null"); } catch { /* Checked below. */ }
-  }
-  if (!value || typeof value !== "object" || value.error) throw new Error("YIDA_BUSINESS_FETCH_FAILED: invalid business publisher response");
-  return value;
-}
-function checkEnterprise(bundle, ctx) {
-  if (bundle.corpId !== ctx.profile.corpId || bundle.yidaOrigin !== ctx.profile.baseUrl) throw new Error("YIDA_BUSINESS_ENTERPRISE_MISMATCH: this package belongs to another YiDA enterprise");
-}
-async function checkOwner(store, ctx, options) {
-  if (digest(await resolveYidaOwner(store, options)) !== digest(ctx.owner)) throw new Error("YIDA_FARGO_ACCOUNT_CHANGED: Fargo account changed during package retrieval");
-}
-async function regular(path, directory = false) {
-  const details = await lstat(path);
-  if (details.isSymbolicLink() || !(directory ? details.isDirectory() : details.isFile()) ||
-      (typeof process.getuid === "function" && details.uid !== process.getuid())) throw new Error("YIDA_BUNDLE_CACHE_INVALID: cache must be owned by the current user and cannot be a symlink");
-  return details;
-}
-async function load(path) {
-  try {
-    await regular(dirname(path), true);
-    if ((await regular(path)).size > MAX_BUNDLE_BYTES + 4096) throw new Error("YIDA_BUNDLE_CACHE_INVALID: cache too large");
-    return JSON.parse(await readFile(path, "utf8"));
-  } catch (error) { if (error.code === "ENOENT") return undefined; throw error; }
-}
-async function save(path, value) {
-  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
-  await regular(dirname(path), true);
-  const temporary = `${path}.${randomUUID()}.tmp`;
-  let handle;
-  try {
-    handle = await open(temporary, "wx", 0o600);
-    await handle.writeFile(JSON.stringify(value));
-    await handle.sync();
-    await handle.close();
-    handle = undefined;
-    await rename(temporary, path);
-  } finally { await handle?.close(); await rm(temporary, { force: true }); }
-}
-function cacheLock(ctx, businessId, callback) {
-  return createCredentialStore({ env: { FARGO_REFRESH_LOCK_PATH: join(ctx.directory, `${businessId}.lock`) } }).withRefreshLock(callback);
-}
-
-export async function listYidaBusinesses(store, options = {}) {
-  const ctx = await context(store, options);
-  const result = await remote(store, ctx, "list_businesses", {}, options);
-  if (!Array.isArray(result.businesses)) throw new Error("YIDA_BUSINESS_FETCH_FAILED: expected a business catalog");
-  await checkOwner(store, ctx, options);
-  return { appId: ctx.appId, profile: ctx.profile.profile, businesses: result.businesses.filter(item => item.corpId === ctx.profile.corpId && item.yidaOrigin === ctx.profile.baseUrl) };
-}
-
-export async function getYidaBusinessBundle(store, businessId, options = {}) {
-  validateBusinessId(businessId);
-  if (options.revision !== undefined && (!Number.isSafeInteger(options.revision) || options.revision < 1)) throw new Error("YIDA_BUSINESS_INVALID: revision must be a positive integer");
-  if (options.bundleHash !== undefined && (typeof options.bundleHash !== "string" || !HASH.test(options.bundleHash))) throw new Error("YIDA_BUSINESS_INVALID: invalid pinned bundle hash");
-  const ctx = await context(store, options);
-  const headPath = join(ctx.directory, `${businessId}.json`);
-  const initial = await load(headPath);
-  if (initial) await validateBusinessBundle(initial, { cliVersion: CLI_VERSION });
-  const cached = options.revision && initial?.revision !== options.revision ? await load(join(ctx.directory, `${businessId}.${options.revision}.json`)) : initial;
-  if (cached) await validateBusinessBundle(cached, { cliVersion: CLI_VERSION });
-  // Every access checks the App's admission and current published version, even on a cache hit.
-  const response = await remote(store, ctx, "get_business_bundle", {
-    businessId, ...(options.revision ? { revision: options.revision } : {}), ...(cached ? { knownHash: cached.bundleHash } : {})
-  }, options);
-  const bundle = response.unchanged === true ? cached : response.bundle;
-  if (!bundle || (response.unchanged && response.bundleHash !== cached?.bundleHash)) throw new Error("YIDA_BUSINESS_FETCH_FAILED: invalid unchanged response");
-  await validateBusinessBundle(bundle, { cliVersion: CLI_VERSION });
-  if (bundle.businessId !== businessId || (options.revision && bundle.revision !== options.revision)) throw new Error("YIDA_BUNDLE_IDENTITY_MISMATCH: unexpected business or revision");
-  checkEnterprise(bundle, ctx);
-  if (options.bundleHash && bundle.bundleHash !== options.bundleHash) throw new Error("YIDA_BUNDLE_PIN_MISMATCH: the workflow's pinned package has changed");
-  await checkOwner(store, ctx, options);
-  await cacheLock(ctx, businessId, async () => {
-    const head = await load(headPath);
-    if (head) await validateBusinessBundle(head, { cliVersion: CLI_VERSION });
-    const revisionPath = join(ctx.directory, `${businessId}.${bundle.revision}.json`);
-    const existing = await load(revisionPath);
-    if ((existing && existing.bundleHash !== bundle.bundleHash) || (head?.revision === bundle.revision && head.bundleHash !== bundle.bundleHash)) throw new Error("YIDA_BUNDLE_REVISION_CONFLICT: a published revision is immutable");
-    if (!options.revision && head && bundle.revision < head.revision) throw new Error("YIDA_BUNDLE_DOWNGRADE: publish a new revision to roll back business content");
-    // Both documents are stored in one file; a partial download never replaces the active version.
-    await save(revisionPath, bundle);
-    if (!options.revision) await save(headPath, bundle);
-  });
-  const live = await describeYidaForm(store, bundle.schema.appType, bundle.schema.formUuid, { ...options, profile: ctx.profile.profile });
-  await checkOwner(store, ctx, options);
-  const matches = !live.truncated && !bundle.schema.truncated && live.schemaHash === bundle.schema.schemaHash;
-  return {
-    appId: ctx.appId, profile: ctx.profile.profile,
-    status: matches ? "current" : "schema_changed",
-    pin: { businessId, revision: bundle.revision, bundleHash: bundle.bundleHash },
-    definition: businessBundleSummary(bundle), bundle,
-    liveSchema: { schemaHash: live.schemaHash, fieldCount: live.fieldCount, truncated: live.truncated, matches },
-    usableForSubmission: false,
-    ...(matches ? {} : { actionRequired: "Re-read the YiDA definition and review the matching handbook before publishing a new business revision. Do not prepare or submit with this package." })
-  };
-}

package/src/yida-cancellation.mjs

@@ -1,121 +0,0 @@
-import { createHash } from "node:crypto";
-import { homedir } from "node:os";
-import { join } from "node:path";
-import { getYidaBusinessBundle } from "./yida-business.mjs";
-import { resolveYidaOwner, yidaStatus, yidaRead, yidaPostFormOnce } from "./yida-auth.mjs";
-import { BUSINESS_ID, HASH, canonicalJson } from "./yida-bundle-format.mjs";
-import { runRecordedYidaMutation } from "./yida-operation.mjs";
-
-const digest = value => createHash("sha256").update(canonicalJson(value)).digest("hex");
-const terminal = new Set(["TERMINATED", "CANCELED"]);
-
-export async function cancelYidaRequest(store, businessId, processInstanceId, options = {}) {
-  if (typeof businessId !== "string" || !BUSINESS_ID.test(businessId) || typeof processInstanceId !== "string" || !/^[A-Za-z0-9_-]{1,200}$/.test(processInstanceId) ||
-      options.dryRun !== undefined && typeof options.dryRun !== "boolean") throw new Error("YIDA_CANCELLATION_INVALID");
-  const execute = options.dryRun === false;
-  if (execute && (!HASH.test(options.previewHash ?? "") || !Number.isSafeInteger(options.revision) || options.revision < 1 || !HASH.test(options.bundleHash ?? ""))) {
-    throw new Error("YIDA_CANCELLATION_PREVIEW_REQUIRED: preview this exact request and reuse its hash and business pin");
-  }
-  const owner = await resolveYidaOwner(store, options);
-  const loaded = await getYidaBusinessBundle(store, businessId, options);
-  if (loaded.status !== "current") throw new Error("YIDA_SCHEMA_CHANGED: cancellation is blocked until the business definition is reviewed");
-  const schema = loaded.bundle.schema;
-  const capability = schema.capabilities?.cancellation;
-  if (schema.formType !== "process" || capability?.enabled !== true || capability.mode !== "terminate" ||
-      capability.ownRequestsOnly !== true || capability.localTool !== "yida_cancel_request" ||
-      typeof schema.entry?.processCode !== "string" || !/^TPROC-[A-Za-z0-9_-]{1,200}$/.test(schema.entry.processCode)) {
-    throw new Error("YIDA_CANCELLATION_UNSUPPORTED: business must declare a process termination capability");
-  }
-  const status = await yidaStatus(store, options);
-  const principal = status.profiles.find(profile => profile.profile === loaded.profile);
-  if (!principal || principal.corpId !== loaded.bundle.corpId || principal.baseUrl !== loaded.bundle.yidaOrigin) throw new Error("YIDA_CANCELLATION_PRINCIPAL_MISMATCH");
-  const local = { ...options, profile: principal.profile };
-  async function checkOwner() {
-    if (digest(owner) !== digest(await resolveYidaOwner(store, options))) throw new Error("YIDA_FARGO_ACCOUNT_CHANGED");
-  }
-  async function checkBinding() {
-    const binding = await yidaRead(store, `/${schema.appType}/query/formProcBinding/getBindingByFormUuid.json?${new URLSearchParams({ formUuid: schema.formUuid })}`, local);
-    if (binding.content?.appType !== schema.appType || binding.content?.procCode !== schema.entry.processCode) throw new Error("YIDA_CANCELLATION_PROCESS_MISMATCH");
-  }
-  await checkBinding();
-  const path = `/dingtalk/web/${schema.appType}/v1/process/getInstanceById.json?${new URLSearchParams({ processInstanceId })}`;
-  async function read() {
-    await checkOwner();
-    const result = await yidaRead(store, path, local);
-    const record = result.content ?? result.result;
-    if (record?.processInstanceId !== processInstanceId || record?.formUuid !== schema.formUuid || record?.processCode !== schema.entry.processCode ||
-        record.originatorCorpId !== undefined && record.originatorCorpId !== principal.corpId) throw new Error("YIDA_CANCELLATION_TARGET_MISMATCH");
-    if (record.originator?.userId !== principal.userId) throw new Error("YIDA_CANCELLATION_NOT_ORIGINATOR: only the member's own requests can be cancelled");
-    await checkOwner();
-    return record;
-  }
-  const record = await read();
-  const fingerprint = value => `sha256:${digest({ pin: loaded.pin, profile: principal.profile, userId: principal.userId, processInstanceId,
-    formUuid: value.formUuid, state: value.instanceStatus, approvedResult: value.approvedResult ?? null, data: value.data ?? null,
-    version: value.version ?? null, modified: value.gmtModified ?? null, actioners: value.actioners ?? null })}`;
-  const previewHash = fingerprint(record);
-  const state = record.instanceStatus;
-  const summary = {
-    businessId, businessName: schema.businessName, processInstanceId, formUuid: schema.formUuid, originatorId: principal.userId,
-    title: String(record.title ?? "").slice(0, 500), instanceStatus: state
-  };
-  const base = { operation: "terminate", pin: loaded.pin, previewHash, summary, verified: true, verification: "api_readback" };
-  if (terminal.has(state)) return { ...base, status: "already_cancelled", requestSent: false };
-  if (state !== "RUNNING" || record.approvedResult) return { ...base, status: "not_cancellable", requestSent: false, reason: "instance_not_running_or_already_decided" };
-  // Whether this token is allowed to terminate remains authoritative at YiDA.
-  if (!execute) return { ...base, status: "preview", requestSent: false, permission: "upstream_authorization_required_on_execute" };
-  if (previewHash !== options.previewHash) throw new Error("YIDA_CANCELLATION_PREVIEW_CHANGED: request changed; inspect a fresh preview before cancelling");
-
-  // Stable per identity + instance, independent of caller-generated request IDs.
-  // A new call cannot bypass an uncertain result by choosing another request ID.
-  const identity = { owner, profile: principal.profile, appType: schema.appType, formUuid: schema.formUuid, processInstanceId, action: "terminate" };
-  const operationId = `cancel-${digest(identity)}`;
-  const operationRoot = options.yidaOperationDirectory ?? (process.platform === "win32" ? join(process.env.APPDATA || homedir(), "Fargo AI", "yida-operations") : join(options.yidaHome ?? homedir(), ".fargo", "yida-operations"));
-  const directory = join(operationRoot, digest({ owner, profile: principal.profile }));
-  let attemptedHere = false;
-  try {
-    await runRecordedYidaMutation({ directory, requestId: operationId, payloadHash: `sha256:${digest(identity)}`, allowSafeRetry: true,
-      send: async () => {
-        // Re-read inside the per-instance lock; a parallel caller may have finished.
-        try {
-          await checkBinding();
-          const current = await read();
-          if (terminal.has(current.instanceStatus)) return { processInstanceId, requestSent: false };
-          if (fingerprint(current) !== options.previewHash) throw new Error("YIDA_CANCELLATION_PREVIEW_CHANGED");
-          await checkOwner();
-        } catch (error) { error.yidaMutationNotApplied = true; throw error; }
-        attemptedHere = true;
-        let response;
-        try {
-          response = await yidaPostFormOnce(store, `/dingtalk/web/${schema.appType}/v1/process/terminateInstance.json`,
-            { processInstanceId, _api: "nattyFetch", _mock: "false" }, { ...local, expectedYidaPrincipal: principal, expectedFargoOwner: owner });
-        } catch (error) {
-          if (error.status === 401 || error.status === 403 || error.authRequired || error.upstreamCode?.startsWith("noPermission.")) error.yidaMutationNotApplied = true;
-          throw error;
-        }
-        if (response.success !== true) throw new Error("YIDA_CANCELLATION_UNVERIFIED");
-        return { processInstanceId, requestSent: true };
-      } });
-  } catch (error) {
-    if (error.yidaRequestSent === false) attemptedHere = false;
-    if (["YIDA_CANCELLATION_PREVIEW_CHANGED", "YIDA_FARGO_ACCOUNT_CHANGED", "YIDA_CANCELLATION_NOT_ORIGINATOR", "YIDA_CANCELLATION_TARGET_MISMATCH", "YIDA_CANCELLATION_PROCESS_MISMATCH"].some(code => error.message.startsWith(code))) throw error;
-    if (error.yidaMutationNotApplied === true) return { ...base,
-      status: error.authRequired ? "authorization_required" : error.status === 403 || error.upstreamCode?.startsWith("noPermission.") ? "permission_denied" : "not_sent",
-      verified: false, operationId, requestSent: attemptedHere, upstreamCode: error.upstreamCode ?? null,
-      actionRequired: "Resolve the authorization or preflight failure, then inspect a fresh preview. No automatic retry was attempted." };
-    // Read-only reconciliation, never retry a mutation (including a 401/timeout).
-    try {
-      const latest = await read();
-      if (terminal.has(latest.instanceStatus)) return { ...base, status: "cancelled", summary: { ...summary, instanceStatus: latest.instanceStatus }, operationId,
-        requestSent: attemptedHere, outcome: "terminal_state_observed_during_reconciliation" };
-    } catch { /* Remain uncertain; do not expose upstream bodies. */ }
-    return { ...base, status: "result_unknown", verified: false, operationId, requestSent: attemptedHere,
-      upstreamCode: error.upstreamCode ?? null, actionRequired: "Read the instance state before any further action. Automatic retry is disabled." };
-  }
-  try {
-    const latest = await read();
-    if (terminal.has(latest.instanceStatus)) return { ...base, status: "cancelled", summary: { ...summary, instanceStatus: latest.instanceStatus }, operationId, requestSent: attemptedHere };
-  } catch { /* An accepted request is not proof of the final state. */ }
-  return { ...base, status: "verification_pending", verified: false, operationId, requestSent: attemptedHere,
-    actionRequired: "Read the instance state to confirm termination. Do not resend." };
-}