@nelsonlongxiang/dsh-open-a2a-net 0.5.13

package/README.md

@@ -0,0 +1,115 @@
+# @nelsonlongxiang/dsh-open-a2a-net
+
+Open A2A network plugin for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH): turns a DSH
+deployment into one node of a decentralized agent network — no central server, no registry.
+
+Each node publishes a **signed, expiring agent card** at `/.well-known/agent-card.json`, discovers peers through
+**seed URLs and referrals** (each card lists the peers it knows), resolves names through **zone delegations**
+(GNUnet GNS-style: a card may delegate a name to another zone), and routes **directly** to a peer's team with
+failover across the reachable half of candidates. Every main session can additionally be exposed as a **session
+node** other hosts can discover and join from the web sidebar.
+
+| The sidebar network panel | Context message display |
+| --- | --- |
+| ![Sidebar network panel](images/image-01.png) | ![Context message display](images/image-02.png) |
+
+## Install
+
+```sh
+npx -p @deepseek-ai/dsh dsh plugin --profile <name> add @nelsonlongxiang/dsh-open-a2a-net
+```
+
+(As a package specifier, a local path, or a Git URL; the package runs `pnpm build` in `prepare`, so a source
+install builds on install. Note: a standalone Git install currently fails to build outside a DSH profile —
+the official `@deepseek-ai/*` npm packages lag the harness source this plugin compiles against, so install
+from the registry or inside a profile whose harness provides current `@deepseek-ai` peers.) Then restart the
+profile. The plugin composes beside the stock
+webserver row: it registers its card, state, and control routes on the shared listener and its model tools on the
+shared tool runtime.
+
+## What you get
+
+- **Model tools** — `a2a_teams` lists the teams this node can see (own, peers', joined sessions'); `a2a_route`
+  sends one message to a team, reuses `context_id` to continue a remote conversation, and fails over across
+  candidates when a peer is unreachable.
+- **Sidebar control** — a footer action in the web sidebar listing this host's sessions as joinable network
+  nodes: title, recent-activity excerpt, and team per row, join/leave in place, and a wake action for cold rows
+  (persisted join intent whose session is not loaded yet — opening the session remounts the node). Session teams
+  are `<team>/<id8>`; web sessions use their id's first 8 chars, imported sessions (`import-<uuid>`) keep the
+  `import-` prefix plus the uuid's first 8 hex chars so imported ids cannot collapse into a handful of teams.
+- **Archive leaves the network** — archiving a session (workspace registry state) prunes its join
+  intent and unmounts its node: at boot settlement before any wake, on every state read (a mid-session
+  archive disappears within one panel poll), and as a route-time guard that never wakes an archived
+  target.
+- **Honest waits** — a synchronous route whose target never answers releases the caller at a 180s
+  reply-wait deadline with the delivered shape and the receipt contract (the target answers on its own
+  cadence); `async: true` skips the wait entirely. The network panel dims an in-flight row past 120s as
+  a stale wait instead of implying live progress, and its title carries the package version badge.
+- **Announce** — `announce: true` publishes this node's card (team, capabilities, referrals, joined session
+  teams) so peers find it without any directory.
+
+## Configuration
+
+Row config overlays in the profile's patch layers; every key has a schema default.
+
+| Key | Default | Purpose |
+| --- | --- | --- |
+| `announce` | `false` | Publish this node's agent card for peer discovery. |
+| `peers` | `[]` | Seed base URLs; referred peers are learned from their cards. |
+| `delegates` | `[]` | Zone delegations: `{ name, url, publicKey }` published on the card. |
+| `team` | `'dsh'` | Team name this node exposes for direct routing. |
+| `session` | `''` | Caller label; `''` derives a stable `dsh-host-<8hex>` per home. |
+| `agentName` | `'DeepSeek Harness A2A node'` | Human-facing name on the card. |
+| `apiKey` | `''` | `X-API-Key` sent on peer requests; non-empty also gates the control routes. |
+| `sessionNodes` | `true` | Expose main sessions as joinable network nodes. |
+| `wakeJoinedOnBoot` | `false` | Materialize every cold joined session's agent on mount (needs the api gateway; wake-on-route and the sidebar wake button stay available without it). |
+| `cardTtlMs` / `flushTimeoutMs` / `routeTimeoutMs` | see schema | Card lifetime and route timing budgets. |
+
+Example — one announcing node with a seed:
+
+```yaml
+- id: a2a
+  name: '@nelsonlongxiang/dsh-open-a2a-net'
+  config:
+    announce: true
+    peers: ['http://127.0.0.1:41243']
+```
+
+## Trust model
+
+Cards are Ed25519-signed and expire; `peers` referrals and `sessionTeams` listings on a card are unsigned and
+read fresh. The `/__dsh_a2a/join` and `/__dsh_a2a/leave` control routes require the configured `apiKey`
+(constant-time compare) when one is set; with an empty key they trust only same-origin browsers and loopback
+callers. Set an `apiKey` before exposing the listener beyond loopback.
+
+## Collaboration SOP (network practice, v0.1)
+
+Distilled from the 0.1.x–0.5.x delivery cycles by the network's research node; adopted by the maintainer.
+
+- **Roles** — one session, one office, no crossing workspace boundaries: a research node (protocol/design
+  review, verdict criteria, source-line references with must-fix/recommend labels), a maintainer node
+  (version rulings, releases, adoption receipts), a test node (the single execution point for all live-host
+  verification; production hosts are never used for ad-hoc testing), and an install/ops node (production
+  profile deployment, single-owner, waits for the maintenance window).
+- **Dispatch discipline** — test tasks go to the test node with version + commit + decidable criteria +
+  receipt target; review tasks go to the research node with source pointers, not paraphrases.
+- **Receipt contract** — tasks longer than minutes route with `async: true` (wait:false); receipts read
+  `[A2A receipt] task <task_id> <outcome summary>`; the task id is caller-born, request-carried,
+  peer-echoed, and steered-header-transmitted — four-way agreement before a receipt correlates.
+- **Upgrade chain** — test node green → maintainer receipt → ops node requests the window → production
+  upgrade → maintainer's browser-face final check → network-wide notice.
+- **Reuse red lines** — shared pure logic extracts to a library; shared runtime capability extracts to a
+  Service; plugins never value-import each other; production hosts carry no verification duty (no
+  dev-who-self-tests).
+
+## Verify
+
+```sh
+pnpm install   # auto-install-peers pulls the DSH peer train from npm
+pnpm verify    # typecheck, build, source tests, and built-artifact layout guard
+pnpm build     # host lib (including lib/a2a-client.js), client types, and browser bundle (lib/client.js)
+```
+
+## License
+
+MIT

package/README_zh.md

@@ -0,0 +1,80 @@
+# @nelsonlongxiang/dsh-open-a2a-net
+
+[English](README.md) | 中文
+
+面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）的开放 A2A 网络插件：把一个 DSH 部署变成去中心化 agent 网络中的一个节点——没有中心服务器，没有注册中心。
+
+每个节点在 `/.well-known/agent-card.json` 发布**带签名、会过期**的 agent 卡片，通过**种子 URL 与相互引荐**发现 peers（每张卡片列出它认识的节点），通过**区域委托**解析名字（GNUnet GNS 风格：卡片可把一个名字委托给另一个 zone），并**直连**路由到 peer 的团队、在可达半数候选间故障切换。每个主会话还可以作为**会话节点**暴露，供其他宿主从 Web 侧栏发现并加入。
+
+| 侧栏网络面板 | 上下文消息展示 |
+| --- | --- |
+| ![侧栏网络面板](images/image-01.png) | ![上下文消息展示](images/image-02.png) |
+
+## 安装
+
+```sh
+npx -p @deepseek-ai/dsh dsh plugin --profile <name> add @nelsonlongxiang/dsh-open-a2a-net
+```
+
+（支持包名、本地路径或 Git URL；包内 `prepare` 会在安装时执行 `pnpm build`。注意：脱离 DSH profile 的独立 Git 安装目前无法构建——官方 `@deepseek-ai/*` npm 快照落后于本插件编译所对照的 harness 源码，请从 registry 安装，或在由 harness 提供当前 `@deepseek-ai` peers 的 profile 内安装。）然后重启 profile。插件组合在标准 webserver 行旁边：在共享监听器上注册卡片、状态与控制路由，在共享工具运行时上注册模型工具。
+
+## 你能得到什么
+
+- **模型工具** —— `a2a_teams` 列出本节点可见的团队（自有、peers 的、已加入会话的）；`a2a_route` 向一个团队发送消息，用 `context_id` 继续远端会话，peer 不可达时在候选间故障切换。
+- **侧栏控制** —— Web 侧栏底部的操作入口，把本宿主的会话列为可加入的网络节点：标题、近期活动摘录、每行所属团队，就地加入/退出，冷行（已持久化加入意图但会话未加载）可唤醒——打开会话即重挂节点。会话团队名为 `<team>/<id8>`；Web 会话取 id 前 8 位，导入会话（`import-<uuid>`）保留 `import-` 前缀加 uuid 前 8 位十六进制，避免导入 id 塌缩成少数几个团队。
+- **归档即离网** —— 归档会话（workspace 注册表状态）会剪除其加入意图并卸载其节点：唤醒前的启动结算、每次状态读取（会话中归档在一个面板轮询周期内消失）、以及永不唤醒已归档目标的路由时守卫。
+- **诚实的等待** —— 目标始终不应答的同步路由，在 180s 回复等待期限后以已投递形态与回执契约释放调用方（目标按自己的节奏作答）；`async: true` 完全跳过等待。网络面板对超过 120s 的在途行降亮度标记为过期等待而非暗示活跃进度，标题带包版本徽标。
+- **通告** —— `announce: true` 发布本节点卡片（团队、能力、引荐、已加入会话团队），peers 无需任何目录即可发现它。
+
+## 配置
+
+行配置叠加在 profile 的 patch 层；每个键都有 schema 默认值。
+
+| 键 | 默认值 | 用途 |
+| --- | --- | --- |
+| `announce` | `false` | 发布本节点 agent 卡片供 peer 发现。 |
+| `peers` | `[]` | 种子 base URL；被引荐的 peers 从其卡片学习。 |
+| `delegates` | `[]` | 区域委托：`{ name, url, publicKey }` 发布在卡片上。 |
+| `team` | `'dsh'` | 本节点暴露给直连路由的团队名。 |
+| `session` | `''` | 调用方标签；`''` 为每个 home 派生稳定的 `dsh-host-<8hex>`。 |
+| `agentName` | `'DeepSeek Harness A2A node'` | 卡片上的人类可读名称。 |
+| `apiKey` | `''` | peer 请求携带的 `X-API-Key`；非空时同时门禁控制路由。 |
+| `sessionNodes` | `true` | 把主会话暴露为可加入的网络节点。 |
+| `wakeJoinedOnBoot` | `false` | 挂载时物化所有冷加入会话的 agent（需要 api gateway；无它时路由唤醒与侧栏唤醒按钮仍可用）。 |
+| `cardTtlMs` / `flushTimeoutMs` / `routeTimeoutMs` | 见 schema | 卡片生命周期与路由时序预算。 |
+
+示例——一个带种子的通告节点：
+
+```yaml
+- id: a2a
+  name: '@nelsonlongxiang/dsh-open-a2a-net'
+  config:
+    announce: true
+    peers: ['http://127.0.0.1:41243']
+```
+
+## 信任模型
+
+卡片经 Ed25519 签名且会过期；卡片上的 `peers` 引荐与 `sessionTeams` 列表未签名、每次现读。`/__dsh_a2a/join` 与 `/__dsh_a2a/leave` 控制路由在配置了 `apiKey` 时要求之（常数时间比较）；密钥为空时仅信任同源浏览器与 loopback 调用方。把监听器暴露到 loopback 之外前请先设置 `apiKey`。
+
+## 协作 SOP（网络实践，v0.1）
+
+由网络研究节点从 0.1.x–0.5.x 交付周期蒸馏；维护者采纳。
+
+- **角色** —— 一个会话一个职能，不越工作区边界：研究节点（协议/设计评审、裁决标准、带 must-fix/recommend 标签的源码行引用）、维护者节点（版本裁决、发布、采纳回执）、测试节点（所有活体验证的唯一执行点；生产宿主绝不用于临时测试）、安装/运维节点（生产 profile 部署、单一 owner、等待维护窗口）。
+- **派发纪律** —— 测试任务发测试节点，带版本 + 提交 + 可判定标准 + 回执目标；评审任务发研究节点，带源码指针而非转述。
+- **回执契约** —— 超过分钟级的任务用 `async: true`（wait:false）路由；回执读作 `[A2A receipt] task <task_id> <outcome summary>`；task id 由调用方出生、请求携带、peer 回显、steering 头传输——四方一致才关联回执。
+- **升级链** —— 测试节点绿 → 维护者回执 → 运维节点申请窗口 → 生产升级 → 维护者浏览器面终检 → 全网通告。
+- **复用红线** —— 共享纯逻辑提取库；共享运行时能力提取 Service；插件之间禁止值 import；生产宿主不承担验证职责（禁止开发者自测）。
+
+## 验证
+
+```sh
+pnpm install   # auto-install-peers 从 npm 拉取 DSH peer 线
+pnpm verify    # typecheck、构建、源码测试与构建产物布局守卫
+pnpm build     # host lib（含 lib/a2a-client.js）、client 类型与浏览器 bundle（lib/client.js）
+```
+
+## 许可证
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,21 @@
+# Bundle patch for @nelsonlongxiang/dsh-open-a2a-net: mounts the a2a row into
+# the host composition of a dsh profile. The plugin registers its
+# /.well-known/agent-card.json announce route, its /__dsh_a2a/* state and
+# control routes, and the a2a_teams / a2a_route model tools on the shared web
+# server and tool runtime — it owns no listener of its own, so compose it
+# beside a webserver row (the stock web profile already has one).
+#
+# Install: `dsh plugin --profile <name> add @nelsonlongxiang/dsh-open-a2a-net`
+# (npm, a local path, or Git). The `dsh plugin` command pnpm-installs the
+# package into the profile and reconciles it into the profile's
+# `dsh.profile.bundles` layer list.
+#
+# All config keys carry schema defaults: session nodes are on (the sidebar
+# join control works out of the box), announce is opt-in. Peers, zone
+# delegates, and an API key are set per deployment through row config
+# overlays, never here.
+- insert:
+    - id: a2a
+      # Node-resolvable package name — must stay in sync with package.json
+      # `name`. Quoted because `@` is a reserved YAML indicator.
+      name: '@nelsonlongxiang/dsh-open-a2a-net'

package/lib/a2a-client.js

@@ -0,0 +1,166 @@
+/**
+ * In-process decentralized A2A client: the outbound peer surface — verified
+ * agent-card fetches (discovery) and direct routes to a peer's
+ * `/a2a/direct` endpoint. Timing and fetch seams are constructor-injected so
+ * tests drive them without a network.
+ * @module @nelsonlongxiang/dsh-open-a2a-net/a2a-client
+ */
+import { verifyCard } from "./card.js";
+/** Direct-route HTTP budget. */
+const HTTP_TIMEOUT_MS = 15_000;
+/** Wire strings are absent-or-string; anything else degrades to ''. */
+function wireText(value) {
+    return typeof value === 'string' ? value : '';
+}
+/**
+ * The A2A peer client. One instance serves the whole fiber's outbound
+ * card fetches and direct routes; it owns no connection state.
+ */
+export class A2aClient {
+    options;
+    /** @param options - resolved caller facts and injected seams. */
+    constructor(options) {
+        this.options = options;
+    }
+    headers(json) {
+        const headers = {};
+        if (json)
+            headers['Content-Type'] = 'application/json';
+        if (this.options.apiKey !== '')
+            headers['X-API-Key'] = this.options.apiKey;
+        return headers;
+    }
+    async http(path, init, baseUrl) {
+        if (init.signal?.aborted)
+            throw new Error('A2A request aborted before dispatch');
+        const controller = new AbortController();
+        const timer = this.options.schedule(() => {
+            controller.abort();
+        }, HTTP_TIMEOUT_MS);
+        const abort = () => {
+            controller.abort();
+        };
+        init.signal?.addEventListener('abort', abort, { once: true });
+        try {
+            const response = await this.options.fetch(`${baseUrl}${path}`, {
+                method: init.method,
+                headers: this.headers(init.body !== undefined),
+                ...(init.body !== undefined ? { body: init.body } : {}),
+                signal: controller.signal,
+            });
+            const text = await response.text();
+            if (!response.ok)
+                throw new Error(`A2A HTTP ${String(response.status)}: ${text.slice(0, 200)}`);
+            return JSON.parse(text);
+        }
+        finally {
+            timer();
+            init.signal?.removeEventListener('abort', abort);
+        }
+    }
+    /**
+     * Fetch one peer's agent card (discovery): team, session, capabilities.
+     * The card is verified at parse — unsigned, badly signed, or expired cards
+     * are rejected here, so a stale peer disappears from discovery without any
+     * background cleanup.
+     * @param baseUrl - the peer's base URL.
+     * @returns the verified card, or `undefined` when unreachable, malformed, or rejected.
+     */
+    async fetchCard(baseUrl) {
+        try {
+            const candidate = await this.http('/.well-known/agent-card.json', { method: 'GET' }, baseUrl);
+            const verified = verifyCard(candidate, Date.now());
+            if (!verified.ok)
+                return undefined;
+            return verified.card;
+        }
+        catch {
+            // An unreachable or malformed peer leaves discovery to the other peers.
+            return undefined;
+        }
+    }
+    /**
+     * Extract the reply text from a route result member: the wire carries a
+     * plain string, a `{text}` object, or anything else JSON-encoded.
+     * @param inner - the raw `result` member of a route response.
+     * @param fallback - what a nullish member encodes as.
+     * @returns the reply text.
+     */
+    replyText(inner, fallback) {
+        if (typeof inner === 'string')
+            return inner;
+        if (inner !== null && typeof inner === 'object' && typeof inner.text === 'string') {
+            return inner.text;
+        }
+        return JSON.stringify(inner ?? fallback);
+    }
+    /**
+     * Route directly to a peer node's `/a2a/direct` endpoint. The peer steers
+     * the message into its live agent (or the named session team's agent) and
+     * answers within its own final-reply budget.
+     * @param baseUrl - the peer's base URL.
+     * @param team - target team name (the peer's own or a session team).
+     * @param message - request text.
+     * @param contextId - context id from a prior reply, for multi-turn.
+     * @param signal - caller cancellation.
+     * @param callerSession - caller label overriding the node's label (the calling session's node label).
+     * @returns the canonical route result (success or explicit failure).
+     */
+    async routeDirect(baseUrl, team, message, contextId, signal, callerSession, asyncMode = false, taskIdFromCaller) {
+        const args = { team, message, caller_session: callerSession ?? this.options.sessionId };
+        if (contextId !== undefined)
+            args.context_id = contextId;
+        // wait:false asks the peer to steer and answer delivered immediately —
+        // the async half of the receipt contract for cross-host long tasks.
+        if (asyncMode)
+            args.wait = false;
+        // The caller-born task id rides the request (idempotency key): a peer
+        // that echoes it keeps the receipt header correlated with this route's
+        // own result; the fallback below stamps it when the peer generated its
+        // own (pre-0.5.3 peers).
+        if (taskIdFromCaller !== undefined)
+            args.task_id = taskIdFromCaller;
+        let raw;
+        try {
+            raw = await this.http('/a2a/direct', {
+                method: 'POST',
+                body: JSON.stringify(args),
+                ...(signal !== undefined ? { signal } : {}),
+            }, baseUrl);
+        }
+        catch (error) {
+            return { ok: false, error: `direct route to peer failed: ${String(error)}`, code: -32000 };
+        }
+        if (raw.error !== undefined && raw.error !== null) {
+            const failure = {
+                ok: false,
+                error: typeof raw.error === 'string' ? raw.error : JSON.stringify(raw.error),
+            };
+            if (typeof raw.code === 'number')
+                failure.code = raw.code;
+            return failure;
+        }
+        // The delivered shape (wait:false): no result member — the reply rides
+        // the receipt contract back to the caller's team instead.
+        if (raw.routed === true && raw.delivered === true) {
+            const taskId = wireText(raw.task_id) !== '' ? wireText(raw.task_id) : taskIdFromCaller ?? '';
+            return {
+                ok: true,
+                team,
+                reply: `Delivered to ${team} (async). The target routes a receipt — a message starting "[A2A receipt] task ${taskId} <outcome summary>" — back to your team when done; watch a2a_status activity or follow up with the context id.`,
+                task_id: taskId,
+                context_id: wireText(raw.context_id),
+                task_status: wireText(raw.task_status) === '' ? 'TASK_STATE_DELIVERED' : wireText(raw.task_status),
+            };
+        }
+        const reply = this.replyText(raw.result, '');
+        return {
+            ok: true,
+            team,
+            reply,
+            task_id: wireText(raw.task_id) !== '' ? wireText(raw.task_id) : taskIdFromCaller ?? wireText(raw.task_id),
+            context_id: wireText(raw.context_id),
+            task_status: wireText(raw.task_status),
+        };
+    }
+}

package/lib/card.js

@@ -0,0 +1,159 @@
+/**
+ * Expiring signed agent cards (GNUnet HELLO semantics): the card carries its
+ * own expiry and an Ed25519 signature over identity, team, capabilities, and
+ * expiry, so only the key holder can extend a card's life. Expiry and the
+ * signature are enforced wherever a card is parsed — no background cleanup.
+ * Design basis: .agents/notes/proposed/feature/2026-08-16-gnunet-prior-art-for-a2a-topology.md (slice 1).
+ * @module @nelsonlongxiang/dsh-open-a2a-net/card
+ */
+import { createPublicKey, sign as edSign, verify as edVerify } from 'node:crypto';
+/** Card validity budget. GNUnet HELLO default (2 days). */
+export const CARD_TTL_MS = 172_800_000;
+/** Announce re-sign cadence: four publication opportunities per TTL. */
+export const CARD_REFRESH_MS = CARD_TTL_MS / 4;
+/** Deterministic signing payload: field order is fixed by JSON.stringify of this literal shape. */
+function canonicalPayload(core) {
+    return JSON.stringify({
+        capabilities: core.capabilities,
+        expiresAt: core.expiresAt,
+        name: core.name,
+        ...(core.records !== undefined ? { records: core.records } : {}),
+        session: core.session,
+        team: core.team,
+    });
+}
+/**
+ * Encode a public key as the base64 SPKI DER the card carries.
+ * @param publicKey - the signing node's Ed25519 public key.
+ * @returns the base64 SPKI DER string.
+ */
+export function encodePublicKey(publicKey) {
+    return publicKey.export({ format: 'der', type: 'spki' }).toString('base64');
+}
+/**
+ * Sign one card core with the node's Ed25519 private key.
+ * @param core - the card's lifecycle-relevant fields, expiry included.
+ * @param privateKey - the signing node's Ed25519 private key.
+ * @returns the wire card: the core plus the public key and signature.
+ */
+export function signCard(core, privateKey) {
+    const signature = edSign(undefined, Buffer.from(canonicalPayload(core), 'utf8'), privateKey).toString('base64');
+    return { ...core, publicKey: encodePublicKey(createPublicKey(privateKey)), signature };
+}
+/**
+ * Validate the signed records member: absent stays absent; any other shape
+ * rejects the card. Records are authority claims, so a malformed list is a
+ * malformed card — unlike the unsigned referral hints, which only drop.
+ * @param wire - the shape-checked card candidate.
+ * @returns the validated records, `undefined` when the card carries none, or
+ * `null` when the member is malformed (the caller rejects the card).
+ */
+function zoneRecords(wire) {
+    if (wire.records === undefined)
+        return undefined;
+    if (!Array.isArray(wire.records))
+        return null;
+    for (const entry of wire.records) {
+        const record = entry;
+        if (record?.type !== 'delegate')
+            return null;
+        if (typeof record.name !== 'string' || record.name === '')
+            return null;
+        if (typeof record.url !== 'string' || record.url === '')
+            return null;
+        if (record.publicKey !== undefined && typeof record.publicKey !== 'string')
+            return null;
+    }
+    return wire.records;
+}
+/**
+ * The unsigned `peers` referral list passes through only as an array of
+ * strings; any other shape drops the field instead of rejecting the card,
+ * because cards from nodes without gossip carry none.
+ * @param wire - the shape-checked card candidate.
+ * @returns the verified referral list, or `undefined` when absent or malformed.
+ */
+function referrals(wire) {
+    if (!Array.isArray(wire.peers) || !wire.peers.every(url => typeof url === 'string'))
+        return undefined;
+    return wire.peers;
+}
+/**
+ * The unsigned `sessionTeams` listing passes through only as an array of
+ * well-formed entries; any other shape drops the field instead of rejecting
+ * the card, because cards from nodes without joined sessions carry none.
+ * @param wire - the shape-checked card candidate.
+ * @returns the session-team entries, or `undefined` when absent or malformed.
+ */
+function sessionTeams(wire) {
+    if (!Array.isArray(wire.sessionTeams))
+        return undefined;
+    const entries = [];
+    for (const entry of wire.sessionTeams) {
+        const team = entry;
+        if (typeof team?.team !== 'string' || team.team === '')
+            continue;
+        if (typeof team.name !== 'string' || typeof team.description !== 'string')
+            continue;
+        entries.push({
+            team: team.team,
+            name: team.name,
+            description: team.description,
+            ...(typeof team.workspace === 'string' && team.workspace !== '' ? { workspace: team.workspace } : {}),
+        });
+    }
+    return entries;
+}
+/**
+ * Verify a parsed card: shape, signature, and expiry, in that order.
+ * @param candidate - the JSON value fetched from a peer's agent-card URL.
+ * @param now - evaluation time (epoch ms); injected for tests.
+ * @returns the verified card, or the first rejection reason.
+ */
+export function verifyCard(candidate, now) {
+    if (typeof candidate !== 'object' || candidate === null)
+        return { ok: false, reason: 'malformed' };
+    const wire = candidate;
+    if (typeof wire.name !== 'string' || typeof wire.session !== 'string' || typeof wire.team !== 'string') {
+        return { ok: false, reason: 'malformed' };
+    }
+    if (typeof wire.expiresAt !== 'number' || typeof wire.publicKey !== 'string' || typeof wire.signature !== 'string') {
+        return { ok: false, reason: 'unsigned' };
+    }
+    const records = zoneRecords(wire);
+    if (records === null)
+        return { ok: false, reason: 'malformed' };
+    if (wire.expiresAt <= now)
+        return { ok: false, reason: 'expired' };
+    const core = {
+        name: wire.name,
+        session: wire.session,
+        team: wire.team,
+        capabilities: wire.capabilities,
+        expiresAt: wire.expiresAt,
+        ...(records !== undefined ? { records } : {}),
+    };
+    try {
+        const publicKey = createPublicKey({ key: Buffer.from(wire.publicKey, 'base64'), format: 'der', type: 'spki' });
+        const valid = edVerify(undefined, Buffer.from(canonicalPayload(core), 'utf8'), publicKey, Buffer.from(wire.signature, 'base64'));
+        if (!valid)
+            return { ok: false, reason: 'bad-signature' };
+    }
+    catch {
+        return { ok: false, reason: 'malformed' };
+    }
+    const peers = referrals(wire);
+    const teams = sessionTeams(wire);
+    return {
+        ok: true,
+        card: {
+            ...core,
+            expiresAt: wire.expiresAt,
+            ...(peers !== undefined ? { peers } : {}),
+            ...(teams !== undefined && teams.length > 0 ? { sessionTeams: teams } : {}),
+            ...(typeof wire.lanIp === 'string' && wire.lanIp !== '' ? { lanIp: wire.lanIp } : {}),
+            publicKey: wire.publicKey,
+            signature: wire.signature,
+        },
+    };
+}