@nelsonlongxiang/dsh-open-a2a-net 0.6.40 → 0.6.41

package/README.md

@@ -171,6 +171,7 @@ Row config overlays in the profile's patch layers; every key has a schema defaul
 | `originClaimUrl` | `''` | Override for the envelope's `callerUrl` (pocket-tunneled hosts); `''` derives it. |
 | `originClaimUnboundWindow` | `true` | OriginClaim audience-binding window: also sign and accept the legacy envelope that names no audience (accepted ones counted as `unboundInbound`; those whose bound form missed here also as `boundMissInbound`); `false` signs and accepts the audience-bound form only. |
 | `originClaimAudiences` | `[]` | Extra origins this host answers to as an envelope audience, for port-mapped or proxied hosts whose dialed URL is neither the card URL nor the arrival address. |
+| `linkKeys` | `{}` | Link keys (#317): `{ "<peer origin>": "<key>" }`. Requests to that peer carry this key instead of `apiKey`; this host's peer faces (`/a2a/direct`, `/a2a/log`, `/a2a/blob`) accept it only from a caller whose OriginClaim verifies and names that origin (a POST must be Sig3 body-bound); the control routes never accept it. Lets a public node link to the fleet without holding the fleet apiKey; both ends configure the same link key. |
 | `gateAgentLessCalls` | `'audit'` | Host-side (agent-less) routing calls: audit them, or `refuse`. |
 | `settlementAuth` | `'observe'` | Settlement authorization (#114): `off`, `observe` (record what would be refused, settle as before), or `enforce`. |
 | `asyncNudgeDelayMs` | `120000` | Delay before a delivered-but-unconsumed async route re-wakes its target with a one-line nudge; `0` disables. |

package/README_zh.md

@@ -129,6 +129,7 @@ a2a-net inbox --new                                      # 未读来信；--wait
 | `originClaimUrl` | `''` | 信封 `callerUrl` 的覆盖值（pocket 隧道宿主用）；`''` 自动推导。 |
 | `originClaimUnboundWindow` | `true` | OriginClaim 受众绑定过渡窗口：同时签发并接受不带受众的旧信封（接受数计入 `unboundInbound`；其中绑定形式在本机未命中的另计 `boundMissInbound`）；`false` 只签发、只接受绑定受众的信封。 |
 | `originClaimAudiences` | `[]` | 本宿主额外认作信封受众的 origin，用于端口映射或反向代理宿主（对端拨号的 URL 既不是卡片 URL 也不是到达地址）。 |
+| `linkKeys` | `{}` | 链路 key（#317）：`{ "<对端 origin>": "<key>" }`。发往该对端的请求改带这把 key；本机对端面（`/a2a/direct`、`/a2a/log`、`/a2a/blob`）只在调用方 OriginClaim 验签通过、且签名者正是该 origin 时接受它（POST 须 Sig3 绑定请求体）；控制路由不接受。用于公网节点与舰队互联而不持有舰队 apiKey，两端配同一把链路 key。 |
 | `gateAgentLessCalls` | `'audit'` | 宿主侧（无 agent）路由调用：审计，或 `refuse` 拒绝。 |
 | `settlementAuth` | `'observe'` | 结算授权（#114）：`off`、`observe`（记下本会拒绝的，照旧结算）或 `enforce`。 |
 | `asyncNudgeDelayMs` | `120000` | 已投递但未被消费的异步路由，在此延迟后用一行催办重新唤醒目标；`0` 关闭。 |

package/lib/a2a-client.js

@@ -33,8 +33,9 @@ export class A2aClient {
         const headers = {};
         if (json)
             headers['Content-Type'] = 'application/json';
-        if (this.options.apiKey !== '')
-            headers['X-API-Key'] = this.options.apiKey;
+        const apiKey = this.options.apiKeyFor?.(url) ?? this.options.apiKey;
+        if (apiKey !== '')
+            headers['X-API-Key'] = apiKey;
         // GETs are card fetches: name ourselves so the peer serves the full
         // card (gh#7 G1). POSTs carry caller_session in the body already.
         if (!json && this.options.cardCaller !== '')

package/lib/config.js

@@ -102,6 +102,7 @@ export const Config = s.object({
     originClaimUnboundWindow: s.boolean().default(true),
     /** Extra OriginClaim audience origins (port-mapped/proxied hosts). */
     originClaimAudiences: s.array(s.string()).default([]),
+    linkKeys: s.dict(s.string()).default({}),
     /** OriginClaim callerUrl override for pocket-tunneled hosts; '' = auto. */
     originClaimUrl: s.string().default(''),
     /**

package/lib/faces/files.js

@@ -33,7 +33,7 @@ export function grantAdmits(to, caller, signer, zone, localCanvasMembers, cli =
  * @param d - the captures listed on {@link FileFaceDeps}.
  */
 export function registerFileFaces(webServer, d) {
-    const { ctx, config, blobStore, canvasStore, verifyOriginClaim, secretEqual, controlRoute, recordActivity } = d;
+    const { ctx, config, blobStore, canvasStore, verifyOriginClaim, peerKeyAdmits, controlRoute, recordActivity } = d;
     const now = d.now ?? (() => Date.now());
     const pulls = new Map();
     const json = (res, status, body) => {
@@ -63,7 +63,7 @@ export function registerFileFaces(webServer, d) {
                 json(res, 405, { ok: false, error: 'GET is the only method on this face' });
                 return;
             }
-            if (config.apiKey !== '' && !secretEqual(String(req.headers['x-api-key'] ?? ''), config.apiKey)) {
+            if (!await peerKeyAdmits(req)) {
                 json(res, 401, { ok: false, error: 'unauthorized: X-API-Key required (apiKey is configured)' });
                 return;
             }

package/lib/faces/session-log.js

@@ -4,7 +4,7 @@ import { TRANSCRIPT_DEFAULT_LIMIT, TRANSCRIPT_MAX_LIMIT } from "../session-trans
  * @param d - the captures listed on {@link SessionLogFaceDeps}.
  */
 export function registerSessionLogFaces(webServer, d) {
-    const { ctx, config, controlRoute, scanSessionLogList, readSessionLogTail, peerStore, peerFetch, directoryPeerCandidates, memoizedCardFetch } = d;
+    const { ctx, config, controlRoute, scanSessionLogList, readSessionLogTail, peerStore, peerFetch, peerRequestHeaders, directoryPeerCandidates, memoizedCardFetch } = d;
     // Session transcript reader (0.6.11): the workbench inspector shows the
     // tail of a LOCAL node's own conversation log inline — owner ruling
     // 2026-10-20 banned navigation, and reading is the need jumps used to
@@ -116,7 +116,7 @@ export function registerSessionLogFaces(webServer, d) {
                     const listUrl = new URL('/a2a/log', base);
                     listUrl.searchParams.set('caller_session', config.team);
                     try {
-                        const listResponse = await peerFetch(listUrl, { signal: AbortSignal.timeout(5000), headers: { accept: 'application/json' } });
+                        const listResponse = await peerFetch(listUrl, { signal: AbortSignal.timeout(5000), headers: { accept: 'application/json', ...peerRequestHeaders(new URL('/a2a/log', base).toString(), 'GET') } });
                         const listBody = await listResponse.json().catch(() => ({ ok: false, error: `peer answered HTTP ${listResponse.status}` }));
                         if (listResponse.ok && listBody.ok === true && Array.isArray(listBody.sessions)) {
                             const picked = suffix !== '' ? listBody.sessions.find(row => row.id.includes(suffix)) : listBody.sessions[0];
@@ -144,7 +144,7 @@ export function registerSessionLogFaces(webServer, d) {
                     target.searchParams.set('id', resolvedId);
                 target.searchParams.set('limit', String(limit));
                 try {
-                    const response = await peerFetch(target, { signal: AbortSignal.timeout(5000), headers: { accept: 'application/json' } });
+                    const response = await peerFetch(target, { signal: AbortSignal.timeout(5000), headers: { accept: 'application/json', ...peerRequestHeaders(new URL('/a2a/log', base).toString(), 'GET') } });
                     const body = await response.json().catch(() => ({ ok: false, error: `peer answered HTTP ${response.status}` }));
                     if (response.ok && body.ok === true) {
                         finish({ ...body, via: base });

package/lib/faces/wire.js

@@ -92,7 +92,7 @@ export class SyncAnswered {
     }
 }
 export function registerWireFaces(webServer, d) {
-    const { ctx, logger, config, cliDeposits, canvasStore, canvasNameReserved, sessionNodes, joinedSessions, idempotencyStore, verifyOriginClaim, remoteCliProof, callerLinkedToThisHost, recordActivity, secretEqual, a2aCallerRefusal, a2aCallerAdmission, allowlistVersionNow, observeAuthorization, scanSessionLogList, readSessionLogTail, taskLedger, refuseIfFlooded, refuseIfQueueFull, settleAndAnnounce, waitForForwardBirth, session, resolveAgentForTeam, parseCanvasTeamName, canvasLiveAgent, wakeColdTeam, probeConsumption, sessionTeamOf, localSessionOfHandle, steerRelay, fromClause, sanitizeFromClause, armReceiptAutosend, eventCountOf, receiptExpectationOf, armAsyncNudge, liveAgent, callerIsAgent, selfRouteText, noWakeFaceText, archivedColdMatchText, noColdMatchText, nativeTeamsPrepare, nativeTeamsRound, routeIntoAgent, } = d;
+    const { ctx, logger, config, cliDeposits, canvasStore, canvasNameReserved, sessionNodes, joinedSessions, idempotencyStore, verifyOriginClaim, remoteCliProof, callerLinkedToThisHost, recordActivity, peerKeyAdmits, a2aCallerRefusal, a2aCallerAdmission, allowlistVersionNow, observeAuthorization, scanSessionLogList, readSessionLogTail, taskLedger, refuseIfFlooded, refuseIfQueueFull, settleAndAnnounce, waitForForwardBirth, session, resolveAgentForTeam, parseCanvasTeamName, canvasLiveAgent, wakeColdTeam, probeConsumption, sessionTeamOf, localSessionOfHandle, steerRelay, fromClause, sanitizeFromClause, armReceiptAutosend, eventCountOf, receiptExpectationOf, armAsyncNudge, liveAgent, callerIsAgent, selfRouteText, noWakeFaceText, archivedColdMatchText, noColdMatchText, nativeTeamsPrepare, nativeTeamsRound, routeIntoAgent, } = d;
     const syncAnswered = new SyncAnswered();
     // gh#45 CLI 户口卡面 (peer face, unsigned card serve): the deposited
     // CLI's SIGNED card is served verbatim under its own base URL — an
@@ -257,13 +257,10 @@ export function registerWireFaces(webServer, d) {
                 return;
             }
             // V2 (gh#7, S1): the read-only log face rides the same apiKey gate
-            // as delivery — a configured key must be presented here too.
-            if (config.apiKey !== '') {
-                const presented = String(req.headers['x-api-key'] ?? '');
-                if (!secretEqual(presented, config.apiKey)) {
-                    send(401, { ok: false, error: 'unauthorized: X-API-Key required (apiKey is configured)', code: -32000 });
-                    return;
-                }
+            // as delivery — a configured key (or #317 link key) must be presented here too.
+            if (!await peerKeyAdmits(req)) {
+                send(401, { ok: false, error: 'unauthorized: X-API-Key required (apiKey is configured)', code: -32000 });
+                return;
             }
             const url = new URL(req.url ?? '/', 'http://x');
             const caller = url.searchParams.get('caller_session') ?? '';
@@ -465,14 +462,12 @@ export function registerWireFaces(webServer, d) {
                 // used to let anyone reachable steer sessions while the control
                 // routes demanded the key, making it decorative for delivery.
                 // Empty-key deployments keep the documented open posture.
-                if (config.apiKey !== '') {
-                    const presented = String(req.headers['x-api-key'] ?? '');
-                    if (!secretEqual(presented, config.apiKey)) {
-                        const payload = JSON.stringify({ error: 'unauthorized: X-API-Key required on the delivery face (apiKey is configured)', code: -32000 });
-                        res.writeHead(401, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) });
-                        res.end(payload);
-                        return;
-                    }
+                // #317: a link key admits only its own verified, body-bound peer.
+                if (!await peerKeyAdmits(req, rawBody)) {
+                    const payload = JSON.stringify({ error: 'unauthorized: X-API-Key required on the delivery face (apiKey is configured)', code: -32000 });
+                    res.writeHead(401, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) });
+                    res.end(payload);
+                    return;
                 }
                 // #282 S2: our own `<canvas>@<fp8>` is our canvas; a foreign suffix stays for the forward walk.
                 const ownerQualified = splitCanvasOwner(typeof body.team === 'string' ? body.team : '');

package/lib/index.js

@@ -9,6 +9,7 @@ import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, ran
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { networkInterfaces } from 'node:os';
 import { selectLanIPv4 } from "./lan-ip.js";
+import { isLinkKey, normalizeLinkKeys, originOf, outboundKeyFor } from "./link-keys.js";
 import { dirname, join } from 'node:path';
 import { resolveDshHome } from '@deepseek-ai/dsh-home-paths';
 // The package own version, read from package.json at load time so the
@@ -199,7 +200,9 @@ export function apply(ctx, config) {
         }
     };
     // gh#193: the one door to peers — while isolated nothing leaves this host.
-    const peerFetch = (url, init) => config.isolated ? Promise.reject(new Error('isolated: outbound peer traffic is off on this host')) : globalThis.fetch(url, init);
+    // Review of #318 R4: never follow a peer's redirect — X-API-Key and the OriginClaim headers are not stripped on
+    // a cross-origin hop, so a 3xx would hand them to whoever the Location names. A redirect is an HTTP failure.
+    const peerFetch = (url, init) => config.isolated ? Promise.reject(new Error('isolated: outbound peer traffic is off on this host')) : globalThis.fetch(url, { ...init, redirect: 'manual' });
     const fetchImpl = (url, init) => peerFetch(url, init);
     /** Constant-time secret comparison: hash both sides to equal-length digests. */
     function secretEqual(a, b) {
@@ -207,6 +210,39 @@ export function apply(ctx, config) {
         const digestB = createHash('sha256').update(b).digest();
         return timingSafeEqual(digestA, digestB);
     }
+    // #317 link keys (src/link-keys.ts): a per-peer X-API-Key on the peer faces, never on the control routes.
+    const linkKeyMap = normalizeLinkKeys(config.linkKeys);
+    /**
+     * The peer-face key gate (/a2a/direct, /a2a/log, /a2a/blob): this host's apiKey as before; a link key only
+     * from a host whose OriginClaim verifies here BOUND to this very request (audience-bound v2 — never a v1
+     * envelope replayed onto another path; a POST also body-bound, Sig3), and only the key configured for that
+     * signer's own origin (review of #318 R1, R3). A leaked link key cannot act without that peer's node key.
+     * An empty apiKey keeps the open posture.
+     * @param req - the inbound peer request.
+     * @param rawBody - the request body, for a POST.
+     */
+    async function peerKeyAdmits(req, rawBody) {
+        if (config.apiKey === '')
+            return true;
+        const presented = String(req.headers['x-api-key'] ?? '');
+        if (secretEqual(presented, config.apiKey))
+            return true;
+        if (!isLinkKey(presented, linkKeyMap, secretEqual))
+            return false;
+        const claim = await verifyOriginClaim(req, rawBody !== undefined ? { rawBody } : undefined);
+        if (!claim.ok || claim.cli === true || !claim.bound || (rawBody !== undefined && claim.bodyBound !== true))
+            return false;
+        const expected = linkKeyMap.get(originOf(claim.callerUrl));
+        return expected !== undefined && secretEqual(presented, expected);
+    }
+    /**
+     * The headers of one signed peer read (the remote session-log proxy): the OriginClaim for `url` (origin and
+     * path, no query) and the key for that target — its link key, else this host's apiKey (review of #318 R2).
+     */
+    function peerRequestHeaders(url, method) {
+        const key = outboundKeyFor(url, linkKeyMap, config.apiKey);
+        return { ...originClaimHeaders({ url, method }), ...(key !== '' ? { 'X-API-Key': key } : {}) };
+    }
     /**
      * No-key trust for the control routes (gh#7 N1, V1): ONLY a loopback
      * socket — header-only trust (Sec-Fetch-Site, Origin) admitted any
@@ -471,6 +507,7 @@ export function apply(ctx, config) {
     }
     const client = new A2aClient({
         apiKey: config.apiKey,
+        apiKeyFor: url => outboundKeyFor(url, linkKeyMap, config.apiKey),
         sessionId: session,
         cardCaller: config.team,
         // gh#9+gh#10 OriginClaim (docs/protocol/delivery-origin-auth.md): every
@@ -2073,21 +2110,20 @@ export function apply(ctx, config) {
      */
     function routeIntoAgentFor(agent, team, message, caller, taskId, proofClause, buildHeader, localFrom, onSteered) {
         return new Promise((resolve) => {
+            // #306: synchronous replies use the same reading-turn attribution as automatic receipts.
+            // Registering and steering are synchronous, so this is the exact pre-steer floor.
             const floorAtRegistration = sessionEventsOf(agent).length;
             const waiter = registerFinalWaiter(agent, (text, placeholder) => {
-                // #298 (review of #305 F4): the sync wait may close on a busy target's OTHER turn. `ownTurn` states,
-                // from this session's own events, that the steer carrying this task was read and that the reply is the
-                // reading turn's own last text — the only reply a peer may declare final (`reply_final`).
+                // Preserve #305's reply_final contract: only this task's own completed reading turn qualifies.
                 let ownTurn = false;
                 if (placeholder !== true && taskId !== undefined && taskId !== '') {
                     const events = sessionEventsOf(agent);
                     const read = consumptionIndex(events, taskId, floorAtRegistration);
-                    // The receipt's own window (review of #305 F5): a back-to-back next turn's text is not this turn's.
                     const window = read === undefined ? undefined : readingTurnReply(events, read);
                     ownTurn = window !== undefined && window.completed && window.reply !== '' && window.reply === text;
                 }
                 resolve({ ok: true, reply: text, ...(placeholder === true ? { placeholder: true } : {}), ...(ownTurn ? { ownTurn: true } : {}) });
-            });
+            }, taskId !== undefined && taskId !== '' ? { taskId, steerFloor: floorAtRegistration } : undefined);
             // The header names the sender first: `caller` is the routing node's
             // own label (the session that issued the route), while `team` is this
             // request's target — showing the target as "remote team" hid the
@@ -2488,6 +2524,7 @@ export function apply(ctx, config) {
             joinedSessions,
             idempotencyStore,
             verifyOriginClaim,
+            peerKeyAdmits,
             remoteCliProof,
             forwardReceiptBasis: (taskId, caller, cliHandle, claim) => forwardReceiptBasis(taskLedger.find(taskId), caller, cliHandle, claim),
             forwardDirect: request => forwardDirect(request), ownCanvasFingerprint,
@@ -2495,7 +2532,6 @@ export function apply(ctx, config) {
             callerLinkedToThisHost, get ownCardUrl() { return ownCardUrl; },
             recordActivity,
             bumpLegacyInbound: () => { legacyInboundCount += 1; },
-            secretEqual,
             a2aCallerRefusal,
             a2aCallerAdmission,
             allowlistVersionNow,
@@ -2647,8 +2683,8 @@ export function apply(ctx, config) {
             }),
         }), 'a2a: quick-dispatch route');
         // gh#77: the session-log faces (local transcript reader + remote-log proxy) live in src/faces/session-log.ts.
-        registerSessionLogFaces(webServer, { ctx, config, controlRoute, scanSessionLogList, readSessionLogTail, peerStore, peerFetch, directoryPeerCandidates, memoizedCardFetch });
-        registerFileFaces(webServer, { ctx, config, blobStore, canvasStore, verifyOriginClaim, secretEqual, controlRoute, recordActivity });
+        registerSessionLogFaces(webServer, { ctx, config, controlRoute, scanSessionLogList, readSessionLogTail, peerStore, peerFetch, peerRequestHeaders, directoryPeerCandidates, memoizedCardFetch });
+        registerFileFaces(webServer, { ctx, config, blobStore, canvasStore, verifyOriginClaim, peerKeyAdmits, controlRoute, recordActivity });
     });
     /**
      * Settle one card-fetch outcome into the peer store and the plain card:

package/lib/link-keys.js

@@ -0,0 +1,29 @@
+/**
+ * #317 link keys: a per-peer `X-API-Key` so a public node never holds the fleet key. Outbound requests to a
+ * linked origin carry that link's key; inbound, a link key is accepted on the peer faces only when the
+ * caller's verified OriginClaim names exactly that origin. The control routes never accept a link key.
+ */
+import { originOf } from "./origin-claim.js";
+export { originOf };
+/** The configured link keys keyed by normalized origin; blank keys and unparsable origins are dropped. */
+export function normalizeLinkKeys(linkKeys) {
+    const out = new Map();
+    for (const [peer, key] of Object.entries(linkKeys ?? {})) {
+        const origin = originOf(peer);
+        if (origin !== '' && typeof key === 'string' && key !== '')
+            out.set(origin, key);
+    }
+    return out;
+}
+/** The `X-API-Key` to send to `url`: its link key, else this host's apiKey ('' omits the header). */
+export function outboundKeyFor(url, linkKeys, apiKey) {
+    return linkKeys.get(originOf(url)) ?? apiKey;
+}
+/** Whether `presented` is one of the link keys (every key is compared, in constant time each). */
+export function isLinkKey(presented, linkKeys, secretEqual) {
+    let matched = false;
+    for (const key of linkKeys.values())
+        if (secretEqual(presented, key))
+            matched = true;
+    return matched;
+}

package/lib/skill/references/setup.md

@@ -65,7 +65,11 @@ Do section 1 on both hosts first. Then the **owner**, on BOTH hosts:
    key is set, and a host sends ITS OWN `apiKey` on every peer request. So
    keyed hosts that talk to each other must carry the SAME key (or both
    none, loopback-only). A mismatch shows up as HTTP 401
-   `X-API-Key required on the delivery face`.
+   `X-API-Key required on the delivery face`. To link a host that must NOT
+   hold the fleet key (a public node), give that one link its own key instead:
+   `linkKeys: { '<other host origin>': '<link key>' }` on BOTH ends (#317).
+   A link key is accepted only on the peer faces, only from the verified
+   peer it names, and never on the control routes.
 3. **Announce and seed each other.** Seeding BOTH ways is what makes the
    hosts linked: each side then reads the other's full card. One-sided
    seeding does not link.

package/lib/tools/files.js

@@ -20,6 +20,7 @@ import { BLOB_FILE_MAX, formatFileRef, parseFileRef, sanitizeBlobName } from "..
 import { grantAdmits } from "../faces/files.js";
 import { LOCAL_ROUTE } from "../node-self.js";
 import { originOf } from "../origin-claim.js";
+import { normalizeLinkKeys, outboundKeyFor } from "../link-keys.js";
 /** Files one send may carry (one message; the FloodGuard per-transfer figure). */
 export const FILE_SEND_MAX = 16;
 /** The inbox directory under a session's workspace. */
@@ -127,10 +128,11 @@ export function createFileTools(d) {
                 }
                 else {
                     const target = `${ref.from}/a2a/blob`;
+                    const key = outboundKeyFor(target, normalizeLinkKeys(config.linkKeys), config.apiKey); // #317 link key
                     let response;
                     try {
                         response = await d.peerFetch(`${target}?sha256=${ref.sha256}&caller_session=${encodeURIComponent(caller)}`, {
-                            headers: { ...d.originClaimHeaders({ url: target, method: 'GET' }), ...(config.apiKey !== '' ? { 'X-API-Key': config.apiKey } : {}) },
+                            headers: { ...d.originClaimHeaders({ url: target, method: 'GET' }), ...(key !== '' ? { 'X-API-Key': key } : {}) },
                             redirect: 'manual',
                             signal: AbortSignal.any([exec.signal, AbortSignal.timeout(120_000)]),
                         });

package/lib/types/a2a-client.d.ts

@@ -13,7 +13,7 @@ export type A2aSchedule = (callback: () => void, delayMs: number) => () => void;
 export type A2aFetch = (url: string, init: {
     readonly method: 'GET' | 'POST';
     readonly headers: Record<string, string>;
-    /** Optional fetch redirect policy; origin verification sets manual. */
+    /** Unused by the client itself: the host's peerFetch already refuses every redirect (review of #318 R4). */
     readonly redirect?: 'follow' | 'error' | 'manual';
     readonly body?: string;
     readonly signal?: AbortSignal;
@@ -26,6 +26,8 @@ export type A2aFetch = (url: string, init: {
 export interface A2aClientOptions {
     /** `X-API-Key` value sent on peer requests; empty omits the header. */
     readonly apiKey: string;
+    /** #317: the key for one target URL (a link key), when it differs from `apiKey`. */
+    readonly apiKeyFor?: (url: string) => string;
     /** This node's caller label stamped on outbound routes. */
     readonly sessionId: string;
     /**

package/lib/types/config.d.ts

@@ -83,6 +83,12 @@ export interface Config {
      * proxied hosts name the URL peers dial).
      */
     readonly originClaimAudiences: string[];
+    /**
+     * #317: per-peer `X-API-Key`, keyed by the peer's origin. Sent instead of `apiKey` on requests to that peer,
+     * and accepted on this host's peer faces only from a caller whose verified OriginClaim names that origin.
+     * Never accepted on the control routes. Lets a public node link without holding the fleet key.
+     */
+    readonly linkKeys: Record<string, string>;
     /**
      * #19 D2: card-face sessionTeams excerpt exposure — 'full' | 'masked'
      * | 'off' (owner-level; default full). See the schema comment.

package/lib/types/faces/files.d.ts

@@ -30,7 +30,8 @@ export interface FileFaceDeps {
     readonly verifyOriginClaim: (req: IncomingMessage, options?: {
         readonly cli?: boolean;
     }) => Promise<OriginClaimResult>;
-    readonly secretEqual: (a: string, b: string) => boolean;
+    /** #317: the peer-face key gate — this host's apiKey, or a link key from the verified peer it belongs to. */
+    readonly peerKeyAdmits: (req: IncomingMessage, rawBody?: Uint8Array) => Promise<boolean>;
     readonly controlRoute: (handler: (req: IncomingMessage, res: ServerResponse) => void) => (req: IncomingMessage, res: ServerResponse) => void;
     readonly recordActivity: (dir: 'in' | 'out', team: string, peer: string, ok: boolean) => void;
     readonly now?: () => number;

package/lib/types/faces/session-log.d.ts

@@ -34,6 +34,8 @@ export interface SessionLogFaceDeps {
     };
     readonly peerStore: Pick<PeerStore, 'list'>;
     readonly peerFetch: typeof globalThis.fetch;
+    /** #317 review R2: the signed, keyed headers of one peer read (OriginClaim + the target's key). */
+    readonly peerRequestHeaders: (url: string, method: string) => Record<string, string>;
     readonly directoryPeerCandidates: (fetch: (url: string) => Promise<A2aPeerCard | undefined>, team: string, failures: string[]) => Promise<string[]>;
     readonly memoizedCardFetch: () => (url: string) => Promise<A2aPeerCard | undefined>;
 }

package/lib/types/faces/wire.d.ts

@@ -148,7 +148,8 @@ export interface WireDeps {
     readonly ownCardUrl: string;
     readonly recordActivity: (dir: 'in' | 'out', team: string, peer: string, ok: boolean) => void;
     readonly bumpLegacyInbound: () => void;
-    readonly secretEqual: (a: string, b: string) => boolean;
+    /** #317: the peer-face key gate — this host's apiKey, or a link key from the verified peer it belongs to. */
+    readonly peerKeyAdmits: (req: IncomingMessage, rawBody?: Uint8Array) => Promise<boolean>;
     readonly a2aCallerRefusal: (caller: string, targetTeam?: string) => string | undefined;
     /** #114 S2: the same decision with the rule and basis that admitted the caller. */
     readonly a2aCallerAdmission: (caller: string, targetTeam?: string, cliProof?: RemoteCliProof) => Admission;

package/lib/types/link-keys.d.ts

@@ -0,0 +1,13 @@
+/**
+ * #317 link keys: a per-peer `X-API-Key` so a public node never holds the fleet key. Outbound requests to a
+ * linked origin carry that link's key; inbound, a link key is accepted on the peer faces only when the
+ * caller's verified OriginClaim names exactly that origin. The control routes never accept a link key.
+ */
+import { originOf } from './origin-claim.ts';
+export { originOf };
+/** The configured link keys keyed by normalized origin; blank keys and unparsable origins are dropped. */
+export declare function normalizeLinkKeys(linkKeys: Readonly<Record<string, unknown>> | undefined): ReadonlyMap<string, string>;
+/** The `X-API-Key` to send to `url`: its link key, else this host's apiKey ('' omits the header). */
+export declare function outboundKeyFor(url: string, linkKeys: ReadonlyMap<string, string>, apiKey: string): string;
+/** Whether `presented` is one of the link keys (every key is compared, in constant time each). */
+export declare function isLinkKey(presented: string, linkKeys: ReadonlyMap<string, string>, secretEqual: (a: string, b: string) => boolean): boolean;

package/lib/types/tools/files.d.ts

@@ -12,7 +12,7 @@ export declare const FILE_SEND_MAX = 16;
 export declare const FILE_INBOX_DIR = "a2a-inbox";
 export interface FileToolsDeps {
     readonly ctx: Context;
-    readonly config: Pick<Config, 'apiKey' | 'team'>;
+    readonly config: Pick<Config, 'apiKey' | 'team' | 'linkKeys'>;
     readonly blobStore: BlobStore;
     readonly canvasMembersOf: (name: string) => readonly string[];
     /** This host's own card URL (live: it is known only once the web server settled). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nelsonlongxiang/dsh-open-a2a-net",
-  "version": "0.6.40",
+  "version": "0.6.41",
   "description": "Open A2A network plugin for DeepSeek Harness: signed agent cards, decentralized peer/zone discovery, direct routing model tools, and joinable session nodes with a sidebar control",
   "type": "module",
   "main": "lib/index.js",