@downcity/plugins 1.0.4

package/src/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 "@/contact/types/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/contact/runtime/LinkApproval.ts

@@ -0,0 +1,387 @@
+/**
+ * contact link approve 状态机。
+ *
+ * 关键点（中文）
+ * - 远端 approve 只有一个入口：校验 link -> 保存 contact -> 消费 link。
+ * - 同一个 agent 在 link 有效期内可重试，用于恢复“远端已保存、本地保存失败”的半建联。
+ * - contact token 由协议自动交换，不依赖用户手动配置环境变量。
+ */
+
+import type { ContactApproveLinkResponse } from "@/contact/types/ContactLink.js";
+import type {
+  ApproveContactLinkRequestInput,
+  ConfirmContactLinkRequestInput,
+  ContactConfirmResponse,
+} from "@/contact/types/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",
+  };
+}

package/src/contact/runtime/LinkCode.ts

@@ -0,0 +1,70 @@
+/**
+ * contact link code 编码。
+ *
+ * 关键点（中文）
+ * - link code 是 `dc-link-v1.<base64url-json>`。
+ * - 这里只负责编码/解析，不负责落盘状态校验。
+ */
+
+import type { ContactLinkCodePayload } from "@/contact/types/ContactLink.js";
+
+const CONTACT_LINK_PREFIX = "dc-link-v1.";
+
+function encodeJson(input: ContactLinkCodePayload): string {
+  return Buffer.from(JSON.stringify(input), "utf-8").toString("base64url");
+}
+
+function decodeJson(input: string): ContactLinkCodePayload {
+  const text = Buffer.from(input, "base64url").toString("utf-8");
+  const parsed = JSON.parse(text) as Partial<ContactLinkCodePayload>;
+  if (parsed.version !== 1) throw new Error("Unsupported contact link version");
+  const linkId = String(parsed.linkId || "").trim();
+  const agentName = String(parsed.agentName || "").trim();
+  const endpoint = String(parsed.endpoint || "").trim();
+  const secret = String(parsed.secret || "").trim();
+  const createdAt = Number(parsed.createdAt);
+  const expiresAt = Number(parsed.expiresAt);
+  if (!linkId || !agentName || !endpoint || !secret) {
+    throw new Error("Invalid contact link code");
+  }
+  if (!Number.isFinite(createdAt) || !Number.isFinite(expiresAt)) {
+    throw new Error("Invalid contact link timestamps");
+  }
+  return {
+    version: 1,
+    linkId,
+    agentName,
+    endpoint,
+    secret,
+    createdAt,
+    expiresAt,
+  };
+}
+
+/**
+ * 创建 contact link code。
+ */
+export function createContactLinkCode(payload: ContactLinkCodePayload): string {
+  return `${CONTACT_LINK_PREFIX}${encodeJson(payload)}`;
+}
+
+/**
+ * 解析 contact link code。
+ */
+export function parseContactLinkCode(code: string): ContactLinkCodePayload {
+  const value = String(code || "").trim();
+  if (!value.startsWith(CONTACT_LINK_PREFIX)) {
+    throw new Error("Invalid contact link code prefix");
+  }
+  return decodeJson(value.slice(CONTACT_LINK_PREFIX.length));
+}
+
+/**
+ * 判断 link code 是否过期。
+ */
+export function isContactLinkExpired(
+  payload: Pick<ContactLinkCodePayload, "expiresAt">,
+  nowMs: number = Date.now(),
+): boolean {
+  return Number(payload.expiresAt) <= nowMs;
+}

package/src/contact/runtime/LinkStore.ts

@@ -0,0 +1,50 @@
+/**
+ * contact link 本地状态存储。
+ *
+ * 关键点（中文）
+ * - link code 明文只展示给用户；本地落盘只保存 secret hash。
+ * - approve 成功后写入 usedAt 和恢复元数据，确保一次性语义并支持同一 agent 幂等重试。
+ */
+
+import fs from "fs-extra";
+import type { ContactLinkRecord } from "@/contact/types/ContactLink.js";
+import { getContactLinkPath, getContactLinksRootPath } from "./Paths.js";
+
+function isLinkRecord(input: unknown): input is ContactLinkRecord {
+  const item = input as Partial<ContactLinkRecord> | null;
+  return Boolean(
+    item &&
+      typeof item.id === "string" &&
+      typeof item.agentName === "string" &&
+      typeof item.endpoint === "string" &&
+      typeof item.secretHash === "string" &&
+      typeof item.createdAt === "number" &&
+      typeof item.expiresAt === "number",
+  );
+}
+
+/**
+ * 保存 link 记录。
+ */
+export async function saveContactLinkRecord(
+  projectRoot: string,
+  record: ContactLinkRecord,
+): Promise<void> {
+  await fs.ensureDir(getContactLinksRootPath(projectRoot));
+  await fs.writeJson(getContactLinkPath(projectRoot, record.id), record, {
+    spaces: 2,
+  });
+}
+
+/**
+ * 读取 link 记录。
+ */
+export async function readContactLinkRecord(
+  projectRoot: string,
+  linkId: string,
+): Promise<ContactLinkRecord | null> {
+  const filePath = getContactLinkPath(projectRoot, linkId);
+  if (!(await fs.pathExists(filePath))) return null;
+  const raw = await fs.readJson(filePath).catch(() => null);
+  return isLinkRecord(raw) ? raw : null;
+}