@downcity/agent 1.1.1

package/src/services/contact/runtime/EndpointResolver.ts

@@ -0,0 +1,146 @@
+/**
+ * contact 自身 endpoint 解析。
+ *
+ * 关键点（中文）
+ * - endpoint 是 contact 协议内部字段，不暴露成普通用户命令参数。
+ * - 优先使用明确配置的公开地址，避免服务器 / 反向代理 / tunnel 场景被误判。
+ * - 监听 `0.0.0.0` 时只做本机网卡最佳努力探测，不访问外部网络。
+ */
+
+import os from "node:os";
+
+export interface ResolveContactSelfEndpointInput {
+  /**
+   * 运行时监听 host。
+   */
+  host?: string;
+  /**
+   * 运行时监听 port。
+   */
+  port?: number;
+  /**
+   * 环境变量读取来源，测试可注入。
+   */
+  env?: NodeJS.ProcessEnv | Record<string, string | undefined>;
+  /**
+   * 网卡信息读取来源，测试可注入。
+   */
+  interfaces?: NodeJS.Dict<os.NetworkInterfaceInfo[]>;
+  /**
+   * 公网 IPv4 解析器，测试可注入。
+   */
+  resolvePublicIpv4?: () => Promise<string | null> | string | null;
+}
+
+function normalizeUrl(value: string, fallbackPort: number): string {
+  const raw = String(value || "").trim();
+  if (!raw) return formatUrl("127.0.0.1", fallbackPort);
+  if (/^https?:\/\//i.test(raw)) return raw.replace(/\/$/, "");
+  return formatUrl(raw, fallbackPort);
+}
+
+function formatUrl(host: string, port: number): string {
+  const normalizedHost = String(host || "").trim() || "127.0.0.1";
+  if (normalizedHost.startsWith("[")) return `http://${normalizedHost}:${String(port)}`;
+  if (normalizedHost.includes(":") && !normalizedHost.includes(".")) {
+    return `http://[${normalizedHost}]:${String(port)}`;
+  }
+  return `http://${normalizedHost}:${String(port)}`;
+}
+
+function isWildcardHost(host: string): boolean {
+  const value = String(host || "").trim().toLowerCase();
+  return !value || value === "0.0.0.0" || value === "::";
+}
+
+function isLoopbackHost(host: string): boolean {
+  const value = String(host || "").trim().toLowerCase();
+  return value === "127.0.0.1" || value === "::1" || value === "localhost";
+}
+
+function detectLanIpv4FromInterfaces(
+  interfaces: NodeJS.Dict<os.NetworkInterfaceInfo[]> = os.networkInterfaces(),
+): string | null {
+  for (const entries of Object.values(interfaces)) {
+    const items = (entries || []) as Array<{
+      address?: string;
+      family?: string | number;
+      internal?: boolean;
+    }>;
+    for (const rawItem of items) {
+      const family =
+        typeof rawItem.family === "string"
+          ? rawItem.family
+          : rawItem.family === 4
+            ? "IPv4"
+            : "unknown";
+      if (family !== "IPv4") continue;
+      if (rawItem.internal) continue;
+      const address = String(rawItem.address || "").trim();
+      if (address) return address;
+    }
+  }
+  return null;
+}
+
+function isIpv4Address(value: string): boolean {
+  const parts = String(value || "").trim().split(".");
+  if (parts.length !== 4) return false;
+  return parts.every((part) => {
+    if (!/^\d+$/.test(part)) return false;
+    const value = Number.parseInt(part, 10);
+    return value >= 0 && value <= 255;
+  });
+}
+
+async function resolvePublicIpv4FromNetwork(): Promise<string | null> {
+  if (typeof fetch !== "function") return null;
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 800);
+  try {
+    const response = await fetch("https://api.ipify.org?format=json", {
+      signal: controller.signal,
+    });
+    if (!response.ok) return null;
+    const data = (await response.json().catch(() => null)) as {
+      ip?: unknown;
+    } | null;
+    const ip = String(data?.ip || "").trim();
+    return isIpv4Address(ip) ? ip : null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+/**
+ * 解析 contact link code 中写入的自身 endpoint。
+ */
+export async function resolveContactSelfEndpoint(
+  input: ResolveContactSelfEndpointInput,
+): Promise<string> {
+  const env = input.env || process.env;
+  const port = Number(input.port || env.DC_SERVER_PORT || 5314);
+
+  // 关键点（中文）：公开 URL 是最可靠来源，适配域名、反向代理和 tunnel。
+  const publicUrl = String(env.DOWNCITY_PUBLIC_URL || "").trim();
+  if (publicUrl) return normalizeUrl(publicUrl, port);
+
+  const publicHost = String(env.DOWNCITY_PUBLIC_HOST || "").trim();
+  if (publicHost) return formatUrl(publicHost, port);
+
+  const host = String(input.host || env.DC_SERVER_HOST || "127.0.0.1").trim();
+  if (!isWildcardHost(host) && !isLoopbackHost(host)) return formatUrl(host, port);
+
+  const lanIp = detectLanIpv4FromInterfaces(input.interfaces);
+  if (lanIp) return formatUrl(lanIp, port);
+
+  // 关键点（中文）：云服务器公网 IP 可能不在网卡上，最后再做短超时公网探测。
+  const publicIp = String(
+    (await (input.resolvePublicIpv4 || resolvePublicIpv4FromNetwork)()) || "",
+  ).trim();
+  if (isIpv4Address(publicIp)) return formatUrl(publicIp, port);
+
+  return formatUrl("127.0.0.1", port);
+}

package/src/services/contact/runtime/InboxStore.ts

@@ -0,0 +1,178 @@
+/**
+ * contact inbox 存储。
+ *
+ * 关键点（中文）
+ * - 每条 share 都是独立目录，避免大内容堆进单个 JSON。
+ * - `inbox` 列表只读取 `meta.json`，保持轻量。
+ */
+
+import fs from "fs-extra";
+import path from "node:path";
+import type {
+  ContactInboxShareMeta,
+  ContactInboxSharePayload,
+  SaveContactInboxShareInput,
+} from "@/types/contact/ContactShare.js";
+import {
+  getContactInboxRootPath,
+  getContactInboxShareFilesPath,
+  getContactInboxShareMetaPath,
+  getContactInboxSharePath,
+  getContactInboxSharePayloadPath,
+  getContactReceivedSharePath,
+} from "./Paths.js";
+
+function assertSafeRelativePath(relativePath: string): string {
+  const value = String(relativePath || "").trim();
+  if (!value) throw new Error("relativePath is required");
+  if (path.isAbsolute(value)) throw new Error(`Absolute path is not allowed: ${value}`);
+  const normalized = path.normalize(value);
+  if (
+    normalized === "." ||
+    normalized.startsWith("..") ||
+    normalized.includes(`${path.sep}..${path.sep}`) ||
+    normalized.endsWith(`${path.sep}..`)
+  ) {
+    throw new Error(`Unsafe relative path: ${value}`);
+  }
+  return normalized;
+}
+
+function isMeta(input: unknown): input is ContactInboxShareMeta {
+  const item = input as Partial<ContactInboxShareMeta> | null;
+  return Boolean(
+    item &&
+      typeof item.id === "string" &&
+      typeof item.fromAgentName === "string" &&
+      (item.status === "pending" || item.status === "received"),
+  );
+}
+
+/**
+ * 保存 inbox share。
+ */
+export async function saveContactInboxShare(
+  projectRoot: string,
+  input: SaveContactInboxShareInput,
+): Promise<ContactInboxShareMeta> {
+  const inboxRoot = getContactInboxRootPath(projectRoot);
+  const sharePath = getContactInboxSharePath(projectRoot, input.meta.id);
+  const tempRoot = path.join(path.dirname(inboxRoot), ".inbox-tmp");
+  const tempPath = path.join(
+    tempRoot,
+    `${path.basename(sharePath)}.${process.pid}.${Date.now()}`,
+  );
+
+  await fs.ensureDir(inboxRoot);
+  await fs.remove(tempPath);
+  try {
+    await fs.ensureDir(tempPath);
+    await fs.writeJson(path.join(tempPath, "payload.json"), input.payload, {
+      spaces: 2,
+    });
+
+    const filesRoot = path.join(tempPath, "files");
+    for (const file of input.files) {
+      const relativePath = assertSafeRelativePath(file.relativePath);
+      const outputPath = path.join(filesRoot, relativePath);
+      const encoding = file.encoding === "base64" ? "base64" : "utf8";
+      const content =
+        encoding === "base64"
+          ? Buffer.from(file.content, "base64")
+          : Buffer.from(file.content, "utf-8");
+      await fs.ensureDir(path.dirname(outputPath));
+      await fs.writeFile(outputPath, content);
+    }
+
+    // meta 最后写入，正式目录只在整条 share 完整后出现，避免 inbox 暴露半成品。
+    await fs.writeJson(path.join(tempPath, "meta.json"), input.meta, {
+      spaces: 2,
+    });
+    await fs.move(tempPath, sharePath, {
+      overwrite: false,
+    });
+  } catch (error) {
+    await fs.remove(tempPath).catch(() => undefined);
+    throw error;
+  }
+
+  return input.meta;
+}
+
+/**
+ * 读取 inbox share meta。
+ */
+export async function readContactInboxShareMeta(
+  projectRoot: string,
+  shareId: string,
+): Promise<ContactInboxShareMeta | null> {
+  const filePath = getContactInboxShareMetaPath(projectRoot, shareId);
+  if (!(await fs.pathExists(filePath))) return null;
+  const raw = await fs.readJson(filePath).catch(() => null);
+  return isMeta(raw) ? raw : null;
+}
+
+/**
+ * 读取 inbox share payload。
+ */
+export async function readContactInboxSharePayload(
+  projectRoot: string,
+  shareId: string,
+): Promise<ContactInboxSharePayload | null> {
+  const filePath = getContactInboxSharePayloadPath(projectRoot, shareId);
+  if (!(await fs.pathExists(filePath))) return null;
+  const raw = await fs.readJson(filePath).catch(() => null);
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const payload = raw as ContactInboxSharePayload;
+  return payload.kind === "share" ? payload : null;
+}
+
+/**
+ * 列出 inbox share。
+ */
+export async function listContactInboxShares(
+  projectRoot: string,
+): Promise<ContactInboxShareMeta[]> {
+  const root = getContactInboxRootPath(projectRoot);
+  if (!(await fs.pathExists(root))) return [];
+  const entries = await fs.readdir(root, { withFileTypes: true });
+  const shares: ContactInboxShareMeta[] = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const meta = await readContactInboxShareMeta(projectRoot, entry.name);
+    if (meta) shares.push(meta);
+  }
+  return shares.sort((a, b) => b.receivedAt - a.receivedAt);
+}
+
+/**
+ * 标记 share 已接收，并复制轻量状态到 received。
+ */
+export async function markContactInboxShareReceived(
+  projectRoot: string,
+  shareId: string,
+): Promise<ContactInboxShareMeta> {
+  const meta = await readContactInboxShareMeta(projectRoot, shareId);
+  if (!meta) throw new Error(`Share not found: ${shareId}`);
+  const next: ContactInboxShareMeta = {
+    ...meta,
+    status: "received",
+  };
+  const receivedPath = getContactReceivedSharePath(projectRoot, shareId);
+  await fs.ensureDir(receivedPath);
+  await fs.writeJson(path.join(receivedPath, "meta.json"), next, {
+    spaces: 2,
+  });
+  // received 区先完整写入，最后再更新 inbox meta，避免列表状态提前变成 received。
+  await fs.writeJson(getContactInboxShareMetaPath(projectRoot, shareId), next, {
+    spaces: 2,
+  });
+  return next;
+}
+
+/**
+ * 读取 share 文件根目录。
+ */
+export function getInboxShareFilesRoot(projectRoot: string, shareId: string): string {
+  return getContactInboxShareFilesPath(projectRoot, shareId);
+}

package/src/services/contact/runtime/LinkApproval.ts

@@ -0,0 +1,387 @@
+/**
+ * contact link approve 状态机。
+ *
+ * 关键点（中文）
+ * - 远端 approve 只有一个入口：校验 link -> 保存 contact -> 消费 link。
+ * - 同一个 agent 在 link 有效期内可重试，用于恢复“远端已保存、本地保存失败”的半建联。
+ * - contact token 由协议自动交换，不依赖用户手动配置环境变量。
+ */
+
+import type { ContactApproveLinkResponse } from "@/types/contact/ContactLink.js";
+import type {
+  ApproveContactLinkRequestInput,
+  ConfirmContactLinkRequestInput,
+  ContactConfirmResponse,
+} from "@/types/contact/ContactApproval.js";
+import {
+  createStableContactId,
+  listContacts,
+  normalizeContactEndpoint,
+  readContact,
+  saveContact,
+} from "./ContactStore.js";
+import {
+  readContactLinkRecord,
+  saveContactLinkRecord,
+} from "./LinkStore.js";
+import {
+  createContactToken,
+  hashContactToken,
+} from "./Token.js";
+
+export const CONTACT_LINK_NOT_FOUND_ERROR =
+  "Contact link not found. This runtime does not have that link record. This usually means the approve request reached the wrong endpoint or port, the link was generated by another agent/project, or the local link store was cleared. If the code is expired, the remote agent returns Contact link expired instead.";
+
+function failure(params: {
+  ownerAgentName: string;
+  endpoint: string;
+  error: string;
+}): ContactApproveLinkResponse {
+  return {
+    success: false,
+    agentName: params.ownerAgentName,
+    endpoint: params.endpoint,
+    tokenForOwner: "",
+    error: params.error,
+  };
+}
+
+function confirmFailure(params: {
+  ownerAgentName: string;
+  error: string;
+}): ContactConfirmResponse {
+  return {
+    success: false,
+    agentName: params.ownerAgentName,
+    confirmed: false,
+    reachability: "inbound",
+    error: params.error,
+  };
+}
+
+function readCallbackCandidate(
+  request: {
+    callbackOffered?: boolean;
+    endpoint?: string;
+    tokenForRequester?: string;
+  },
+): {
+  endpoint: string | null;
+  token: string | null;
+  error?: string;
+} {
+  if (request.callbackOffered !== true) {
+    return {
+      endpoint: null,
+      token: null,
+    };
+  }
+  const token = String(request.tokenForRequester || "").trim();
+  if (!request.endpoint || !token) {
+    return {
+      endpoint: null,
+      token: null,
+      error: "Contact approve request is missing the peer callback token",
+    };
+  }
+  try {
+    return {
+      endpoint: normalizeContactEndpoint(request.endpoint),
+      token,
+    };
+  } catch {
+    return {
+      endpoint: null,
+      token: null,
+      error: "Contact approve request has an invalid peer callback endpoint",
+    };
+  }
+}
+
+async function findApprovedContact(params: {
+  projectRoot: string;
+  agentName: string;
+}) {
+  const stable = await readContact(
+    params.projectRoot,
+    createStableContactId(params.agentName),
+  );
+  if (stable) return stable;
+  const contacts = await listContacts(params.projectRoot);
+  const lower = params.agentName.trim().toLowerCase();
+  return contacts.find((item) => item.name.toLowerCase() === lower) || null;
+}
+
+async function saveApprovedInboundContact(params: {
+  projectRoot: string;
+  agentName: string;
+  tokenForOwner: string;
+  nowMs: number;
+}) {
+  const existing = await findApprovedContact({
+    projectRoot: params.projectRoot,
+    agentName: params.agentName,
+  });
+  const hasOutboundSide = Boolean(existing?.endpoint && existing?.outboundToken);
+  await saveContact(params.projectRoot, {
+    id: existing?.id || createStableContactId(params.agentName),
+    name: existing?.name || params.agentName,
+    endpoint: existing?.endpoint || null,
+    reachability: hasOutboundSide ? "bidirectional" : "inbound",
+    status: "trusted",
+    outboundToken: existing?.outboundToken || null,
+    inboundTokenHash: hashContactToken(params.tokenForOwner),
+    createdAt: existing?.createdAt || params.nowMs,
+    lastSeenAt: params.nowMs,
+  });
+}
+
+/**
+ * 执行远端 link approve 状态转换。
+ */
+export async function approveContactLinkRequest(
+  input: ApproveContactLinkRequestInput,
+): Promise<ContactApproveLinkResponse> {
+  const nowMs = input.nowMs ?? Date.now();
+  const link = await readContactLinkRecord(input.projectRoot, input.request.linkId);
+  if (!link) {
+    return failure({
+      ownerAgentName: input.ownerAgentName,
+      endpoint: input.ownerEndpoint,
+      error: CONTACT_LINK_NOT_FOUND_ERROR,
+    });
+  }
+  if (link.expiresAt <= nowMs) {
+    return failure({
+      ownerAgentName: input.ownerAgentName,
+      endpoint: link.endpoint,
+      error: "Contact link expired",
+    });
+  }
+  if (hashContactToken(input.request.secret) !== link.secretHash) {
+    return failure({
+      ownerAgentName: input.ownerAgentName,
+      endpoint: link.endpoint,
+      error: "Invalid contact link secret",
+    });
+  }
+  const callbackCandidate = readCallbackCandidate(input.request);
+
+  if (link.usedAt) {
+    if (
+      link.approvedAgentName === input.request.agentName &&
+      link.tokenForOwner
+    ) {
+      let nextLink = link;
+      if (
+        !link.confirmedAt &&
+        !callbackCandidate.error &&
+        callbackCandidate.endpoint &&
+        callbackCandidate.token
+      ) {
+        nextLink = {
+          ...link,
+          approvedEndpoint: callbackCandidate.endpoint,
+          tokenForRequester: callbackCandidate.token,
+          callbackReason: input.request.callbackReason || link.callbackReason || null,
+        };
+        await saveContactLinkRecord(input.projectRoot, nextLink);
+      }
+      await saveApprovedInboundContact({
+        projectRoot: input.projectRoot,
+        agentName: input.request.agentName,
+        tokenForOwner: link.tokenForOwner,
+        nowMs,
+      });
+      return {
+        success: true,
+        agentName: input.ownerAgentName,
+        endpoint: link.endpoint,
+        tokenForOwner: link.tokenForOwner,
+      };
+    }
+    return failure({
+      ownerAgentName: input.ownerAgentName,
+      endpoint: link.endpoint,
+      error: "Contact link already used",
+    });
+  }
+
+  const tokenForOwner = createContactToken();
+  const approvedLink = {
+    ...link,
+    usedAt: nowMs,
+    approvedAgentName: input.request.agentName,
+    approvedEndpoint: callbackCandidate.endpoint,
+    tokenForOwner,
+    tokenForRequester: callbackCandidate.token,
+    callbackReason: callbackCandidate.error ? null : input.request.callbackReason || null,
+  };
+
+  // 先消费 link，再派生 contact；重试时以 link 记录为来源修复 contact，避免孤儿 trusted contact。
+  await saveContactLinkRecord(input.projectRoot, approvedLink);
+  await saveApprovedInboundContact({
+    projectRoot: input.projectRoot,
+    agentName: input.request.agentName,
+    tokenForOwner,
+    nowMs,
+  });
+
+  return {
+    success: true,
+    agentName: input.ownerAgentName,
+    endpoint: link.endpoint,
+    tokenForOwner,
+  };
+}
+
+/**
+ * 执行远端 confirm 状态转换。
+ */
+export async function confirmContactLinkRequest(
+  input: ConfirmContactLinkRequestInput,
+): Promise<ContactConfirmResponse> {
+  const nowMs = input.nowMs ?? Date.now();
+  const link = await readContactLinkRecord(input.projectRoot, input.request.linkId);
+  if (!link) {
+    return confirmFailure({
+      ownerAgentName: input.ownerAgentName,
+      error: CONTACT_LINK_NOT_FOUND_ERROR,
+    });
+  }
+  if (!link.usedAt && link.expiresAt <= nowMs) {
+    return confirmFailure({
+      ownerAgentName: input.ownerAgentName,
+      error: "Contact link expired",
+    });
+  }
+  if (hashContactToken(input.request.secret) !== link.secretHash) {
+    return confirmFailure({
+      ownerAgentName: input.ownerAgentName,
+      error: "Invalid contact link secret",
+    });
+  }
+  if (!link.usedAt || link.approvedAgentName !== input.request.agentName) {
+    return confirmFailure({
+      ownerAgentName: input.ownerAgentName,
+      error: "Contact link is not approved by this agent",
+    });
+  }
+
+  let endpoint: string;
+  try {
+    endpoint = normalizeContactEndpoint(input.request.endpoint);
+  } catch {
+    return confirmFailure({
+      ownerAgentName: input.ownerAgentName,
+      error: "Contact confirm request has an invalid peer callback endpoint",
+    });
+  }
+  const token = String(input.request.tokenForRequester || "").trim();
+  if (!token) {
+    return confirmFailure({
+      ownerAgentName: input.ownerAgentName,
+      error: "Contact confirm request is missing the peer callback token",
+    });
+  }
+  if (!link.tokenForRequester) {
+    return confirmFailure({
+      ownerAgentName: input.ownerAgentName,
+      error: "Contact link has no callback token to confirm",
+    });
+  }
+  if (link.tokenForRequester !== token) {
+    return confirmFailure({
+      ownerAgentName: input.ownerAgentName,
+      error: "Contact confirm callback token does not match the approved token",
+    });
+  }
+  if (!link.approvedEndpoint) {
+    return confirmFailure({
+      ownerAgentName: input.ownerAgentName,
+      error: "Contact link has no callback endpoint to confirm",
+    });
+  }
+  if (normalizeContactEndpoint(link.approvedEndpoint) !== endpoint) {
+    return confirmFailure({
+      ownerAgentName: input.ownerAgentName,
+      error: "Contact confirm callback endpoint does not match the approved endpoint",
+    });
+  }
+  const contact = await findApprovedContact({
+    projectRoot: input.projectRoot,
+    agentName: input.request.agentName,
+  });
+  if (!contact || contact.status !== "trusted") {
+    return confirmFailure({
+      ownerAgentName: input.ownerAgentName,
+      error: "Contact not found for approved link",
+    });
+  }
+  if (!link.tokenForOwner || contact.inboundTokenHash !== hashContactToken(link.tokenForOwner)) {
+    return confirmFailure({
+      ownerAgentName: input.ownerAgentName,
+      error: "Contact token state does not match the approved link",
+    });
+  }
+
+  if (
+    contact.reachability === "bidirectional" &&
+    contact.endpoint === endpoint &&
+    contact.outboundToken === token
+  ) {
+    if (!link.confirmedAt) {
+      // contact 已经完成双向升级时，重试 confirm 需要补齐 link 状态，避免最终状态分裂。
+      await saveContactLinkRecord(input.projectRoot, {
+        ...link,
+        approvedEndpoint: endpoint,
+        tokenForRequester: token,
+        confirmedAt: nowMs,
+      });
+    }
+    return {
+      success: true,
+      agentName: input.ownerAgentName,
+      confirmed: true,
+      reachability: "bidirectional",
+    };
+  }
+
+  let callbackOk = false;
+  try {
+    callbackOk = await input.verifyCallback({ endpoint, token });
+  } catch {
+    callbackOk = false;
+  }
+  if (!callbackOk) {
+    return {
+      success: true,
+      agentName: input.ownerAgentName,
+      confirmed: false,
+      reachability: "inbound",
+      error: "Contact callback ping failed",
+    };
+  }
+
+  await saveContact(input.projectRoot, {
+    ...contact,
+    endpoint,
+    reachability: "bidirectional",
+    outboundToken: token,
+    inboundTokenHash: contact.inboundTokenHash,
+    lastSeenAt: nowMs,
+  });
+  await saveContactLinkRecord(input.projectRoot, {
+    ...link,
+    approvedEndpoint: endpoint,
+    tokenForRequester: token,
+    confirmedAt: nowMs,
+  });
+
+  return {
+    success: true,
+    agentName: input.ownerAgentName,
+    confirmed: true,
+    reachability: "bidirectional",
+  };
+}