@nelsonlongxiang/dsh-open-a2a-net 0.6.30 → 0.6.32

package/lib/node-tasks.js

@@ -0,0 +1,342 @@
+/**
+ * Node task pointers (docs/design/node-identity.md §2 "任务指针", §5 task context, §6; slice N6).
+ *
+ * - A pointer is `owner/repo#n` plus a CACHED state — GitHub is the truth
+ *   (`open` / `merged` / `closed` / `declined`; `unknown` until a check
+ *   answers). Each records the node's `core_version` and `mutable_version`
+ *   when it was tracked (§6 归因).
+ * - Kept in `node-tasks.json` under the a2a home, beside the roster rather
+ *   than inside it: a cache that changes on every check must not rewrite
+ *   the identity roster. The newest 64 per node stay — finished pointers are
+ *   evicted before open ones — and evicted ones are appended to
+ *   `node-tasks-archive.jsonl`.
+ * - Checks: once when a pointer is tracked, a full pass right after the
+ *   plugin loads, and a full pass every 12 hours. Finished pointers are not
+ *   re-checked (a re-opened issue keeps reading finished — the cost of not
+ *   polling finished work). One check per ref at a time; a finished state
+ *   is never walked back to open by a late answer. A probe that cannot
+ *   answer marks the check `unknown` and keeps the last known state.
+ * - Reminder (§6 主触发): a pointer that finished AFTER it was tracked —
+ *   it was `open` here, or GitHub's merged_at / closed_at is later than
+ *   `since` — calls `onSettled` once. A pointer that finished before it
+ *   was tracked, or whose finish time cannot be told, does not remind; an
+ *   unknown state never does. A reminder that reached no session (a cold
+ *   host boot: the load-time pass runs before any session is live) is kept
+ *   as `remind_pending` and handed out the next time the node mounts on a
+ *   session (`takePending`), so a merge during downtime is not swallowed.
+ *   The finish-time comparison trusts the host clock; skew of a few minutes
+ *   can add or drop a reminder for a pointer whose first check failed.
+ * - After the plugin unloads (`dispose`), a check still in flight neither
+ *   writes nor reminds: a newer instance owns the file by then.
+ * - A file that does not parse is left in place and the table is read-only;
+ *   malformed rows are backed up before the next write drops them (as the
+ *   roster and the bindings table do).
+ * @module @nelsonlongxiang/dsh-open-a2a-net/node-tasks
+ */
+import { appendFileSync, copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { TASK_REF } from "./node-github.js";
+export const TASK_KEEP = 64;
+/** §5: the task context is generated, so it is truncated (not refused) at this many characters. */
+export const TASKS_CONTEXT_MAX = 1500;
+/** §6 / §8-8: the full check runs twice a day. */
+export const TASKS_CHECK_MS = 12 * 60 * 60 * 1000;
+/** The §6 reminder for a pointer that finished. */
+export function settledReminder(p) {
+    const verb = p.state === 'merged' ? '合并' : p.state === 'declined' ? '被拒' : '关闭';
+    return `[节点复盘] ${p.ref} 已${verb}。这件事告一段落：按需更新节点自记（当前状态、执行要点、已知陷阱、当前重点）。`;
+}
+const FINISHED = new Set(['merged', 'closed', 'declined']);
+const STATES = new Set(['open', 'merged', 'closed', 'declined', 'unknown']);
+/** ISO-8601 instants only: a hand-edited `since` must not carry text into the task context. */
+const ISO = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/;
+const chars = (text) => [...text].length;
+const fail = (code, error) => ({ ok: false, code, error });
+function pointerOf(raw) {
+    const r = raw;
+    if (r === null || typeof r !== 'object' || typeof r.ref !== 'string' || !TASK_REF.test(r.ref) || typeof r.state !== 'string' || !STATES.has(r.state))
+        return undefined;
+    if (typeof r.since !== 'string' || !ISO.test(r.since))
+        return undefined;
+    const n = (v) => typeof v === 'number' && Number.isSafeInteger(v) && v >= 0 ? v : 0;
+    return {
+        ref: r.ref, state: r.state, check: r.check === 'ok' || r.check === 'unknown' ? r.check : 'pending',
+        since: r.since, checked_at: typeof r.checked_at === 'string' && ISO.test(r.checked_at) ? r.checked_at : '',
+        core_version: n(r.core_version), mutable_version: n(r.mutable_version), by: typeof r.by === 'string' ? r.by.slice(0, 80) : '',
+        ...(r.remind_pending === true && FINISHED.has(r.state) ? { remind_pending: true } : {}),
+    };
+}
+/** Whether a fresh answer means the pointer finished after it was tracked (see the module note). */
+function finishedSinceTracked(before, fact) {
+    if (!FINISHED.has(fact.state) || FINISHED.has(before.state))
+        return false;
+    if (before.state === 'open')
+        return true;
+    const at = fact.finishedAt === undefined ? Number.NaN : Date.parse(fact.finishedAt);
+    const since = Date.parse(before.since);
+    return Number.isFinite(at) && Number.isFinite(since) && at >= since;
+}
+export class NodeTasks {
+    root;
+    d;
+    table = {};
+    readOnlyReason = '';
+    running;
+    inflight = new Map();
+    /** Owed reminders already handed out by this process: a clear that could not be written must not repeat at every mount. */
+    handedOut = new Set();
+    disposed = false;
+    now;
+    /** @param root - the `<home>/a2a` directory; '' keeps the table in memory (tests). */
+    constructor(root, d) {
+        this.root = root;
+        this.d = d;
+        this.now = d.now ?? (() => new Date().toISOString());
+        this.restore();
+    }
+    get file() { return join(this.root, 'node-tasks.json'); }
+    stamp() { return this.now().replace(/[:.]/g, '-'); }
+    restore() {
+        if (this.root === '' || !existsSync(this.file))
+            return;
+        let raw;
+        try {
+            raw = JSON.parse(readFileSync(this.file, 'utf8'));
+        }
+        catch {
+            raw = undefined;
+        }
+        const tasks = raw?.tasks;
+        if (raw === null || typeof raw !== 'object' || tasks === null || typeof tasks !== 'object' || Array.isArray(tasks)) {
+            const aside = `${this.file}.corrupt-${this.stamp()}`;
+            try {
+                copyFileSync(this.file, aside);
+            }
+            catch { /* the original stays in place either way */ }
+            this.readOnlyReason = `node-tasks.json is unreadable (copy kept at ${aside}); repair it, then restart`;
+            return;
+        }
+        let dropped = 0;
+        for (const [node, list] of Object.entries(tasks)) {
+            if (!Array.isArray(list)) {
+                dropped++;
+                continue;
+            }
+            const kept = [];
+            for (const raw of list) {
+                const p = pointerOf(raw);
+                if (p === undefined || kept.some(k => k.ref === p.ref))
+                    dropped++;
+                else
+                    kept.push(p);
+            }
+            this.table[node] = kept;
+        }
+        // The next commit rewrites the table without the dropped rows: keep the original first.
+        if (dropped > 0) {
+            try {
+                copyFileSync(this.file, `${this.file}.dropped-${this.stamp()}`);
+            }
+            catch { /* best effort; the rows were unusable either way */ }
+        }
+    }
+    commit(next, archived = []) {
+        if (this.disposed)
+            return fail('unavailable', 'node tasks were unloaded');
+        if (this.readOnlyReason !== '')
+            return fail('unavailable', `node tasks are read-only: ${this.readOnlyReason}`);
+        if (this.root !== '') {
+            try {
+                mkdirSync(this.root, { recursive: true });
+                const tmp = `${this.file}.${String(process.pid)}.tmp`;
+                writeFileSync(tmp, JSON.stringify({ tasks: next }), { mode: 0o600 });
+                // The archive is appended after the new table is staged and before it replaces the old one: a failed
+                // staging write leaves no archive rows; a crash (or a failed rename) after the append leaves the pointer
+                // in BOTH files — a duplicate, never a loss.
+                for (const a of archived)
+                    appendFileSync(join(this.root, 'node-tasks-archive.jsonl'), `${JSON.stringify({ node: a.node, ...a.pointer, archived_at: this.now() })}\n`, { mode: 0o600 });
+                renameSync(tmp, this.file);
+            }
+            catch (error) {
+                return fail('unavailable', `could not persist node-tasks.json: ${String(error)}`);
+            }
+        }
+        this.table = next;
+        return { ok: true, value: true };
+    }
+    get readOnly() { return this.readOnlyReason; }
+    list(node) { return this.table[node] ?? []; }
+    /**
+     * Run the checks on the plugin's context: one full pass right after load (a restart within 12 hours
+     * would otherwise never check), one every 12 hours, and stop writing once the plugin unloads.
+     */
+    schedule(ctx) {
+        ctx.effect(() => () => { this.disposed = true; }, 'a2a: node tasks');
+        ctx.timer.timeout(() => { void this.checkAll(); }, 0);
+        ctx.timer.interval(() => { void this.checkAll(); }, TASKS_CHECK_MS);
+    }
+    /** Track a pointer at the node's current versions; checks it once in the background. Re-tracking is a no-op. */
+    track(node, ref, versions, by) {
+        if (typeof ref !== 'string' || !TASK_REF.test(ref))
+            return fail('bad-request', 'ref must be owner/repo#number');
+        const list = this.list(node);
+        const existing = list.find(p => p.ref === ref);
+        if (existing !== undefined)
+            return { ok: true, value: existing };
+        const pointer = { ref, state: 'unknown', check: 'pending', since: this.now(), checked_at: '', core_version: versions.core, mutable_version: versions.mutable, by };
+        // Over the cap: finished pointers go first (oldest first), then the oldest open ones, and a pointer that
+        // still owes a reminder goes last — evicting it would drop the reminder with it.
+        const all = [pointer, ...list];
+        const evict = new Set();
+        const pass = (pick) => {
+            for (const p of [...all].reverse()) {
+                if (all.length - evict.size <= TASK_KEEP)
+                    return;
+                if (p !== pointer && !evict.has(p.ref) && pick(p))
+                    evict.add(p.ref);
+            }
+        };
+        pass(p => FINISHED.has(p.state) && p.remind_pending !== true);
+        pass(p => p.remind_pending !== true);
+        pass(() => true);
+        const done = this.commit({ ...this.table, [node]: all.filter(p => !evict.has(p.ref)) }, all.filter(p => evict.has(p.ref)).map(p => ({ node, pointer: p })));
+        if (!done.ok)
+            return done;
+        void this.check(node, ref);
+        return { ok: true, value: pointer };
+    }
+    untrack(node, ref) {
+        const list = this.list(node);
+        if (typeof ref !== 'string' || !list.some(p => p.ref === ref))
+            return fail('not-found', `${node} does not track ${String(ref)}`);
+        return this.commit({ ...this.table, [node]: list.filter(p => p.ref !== ref) });
+    }
+    /** An archived node's pointers move to the archive file. */
+    dropNode(node) {
+        const list = this.list(node);
+        if (list.length === 0)
+            return;
+        const next = { ...this.table };
+        delete next[node];
+        const done = this.commit(next, list.map(pointer => ({ node, pointer })));
+        if (!done.ok)
+            this.d.logger.warn('a2a nodes: could not archive the task pointers of %s: %s', node, done.error);
+    }
+    /** Check one pointer now; joins a check of the same pointer already in flight. Never throws. */
+    check(node, ref) {
+        const key = `${node}\u0000${ref}`;
+        const running = this.inflight.get(key);
+        if (running !== undefined)
+            return running;
+        const run = this.checkOnce(node, ref).finally(() => { this.inflight.delete(key); });
+        this.inflight.set(key, run);
+        return run;
+    }
+    async checkOnce(node, ref) {
+        let fact;
+        try {
+            fact = await this.d.probe(ref);
+        }
+        catch {
+            fact = undefined;
+        }
+        if (this.disposed)
+            return;
+        // Re-read after the await: the pointer may have been untracked, or the node archived, meanwhile.
+        const list = this.list(node);
+        const before = list.find(p => p.ref === ref);
+        if (before === undefined)
+            return;
+        const after = fact === undefined
+            ? { ...before, check: 'unknown', checked_at: this.now() }
+            // A finished state is final here: a late answer never walks it back.
+            : { ...before, state: FINISHED.has(before.state) ? before.state : fact.state, check: 'ok', checked_at: this.now() };
+        const done = this.commit({ ...this.table, [node]: list.map(p => p.ref === ref ? after : p) });
+        if (!done.ok) {
+            this.d.logger.warn('a2a nodes: checked %s for %s but could not record it: %s', ref, node, done.error);
+            return;
+        }
+        if (fact !== undefined && finishedSinceTracked(before, fact)) {
+            let reached = 0;
+            try {
+                reached = this.d.onSettled(node, after);
+            }
+            catch (error) {
+                this.d.logger.warn('a2a nodes: reminder for %s failed: %s', ref, String(error));
+            }
+            // Nobody carried the node right now (e.g. a cold boot): owe it to the next session that mounts it.
+            if (reached === 0) {
+                this.handedOut.delete(`${node}\u0000${ref}`);
+                this.setPending(node, ref, true);
+            }
+        }
+    }
+    setPending(node, ref, pending) {
+        const list = this.list(node);
+        if (!list.some(p => p.ref === ref))
+            return;
+        const done = this.commit({ ...this.table, [node]: list.map(p => {
+                if (p.ref !== ref)
+                    return p;
+                const { remind_pending: _drop, ...rest } = p;
+                return pending ? { ...rest, remind_pending: true } : rest;
+            }) });
+        if (!done.ok)
+            this.d.logger.warn('a2a nodes: could not record the owed reminder for %s: %s', ref, done.error);
+    }
+    /**
+     * The reminders owed to `node`, cleared as they are handed out (one session gets each). A clear that
+     * cannot be written still hands them out, once per process — a reminder may then repeat after a restart,
+     * never vanish.
+     */
+    takePending(node) {
+        const owed = this.list(node).filter(p => p.remind_pending === true && !this.handedOut.has(`${node}\u0000${p.ref}`));
+        for (const p of owed) {
+            this.handedOut.add(`${node}\u0000${p.ref}`);
+            this.setPending(node, p.ref, false);
+        }
+        return owed;
+    }
+    /** The full pass: every pointer not yet finished, one at a time. A pass already running is joined. */
+    checkAll() {
+        this.running ??= (async () => {
+            try {
+                for (const [node, list] of Object.entries(this.table)) {
+                    for (const p of list) {
+                        if (this.disposed)
+                            return;
+                        if (!FINISHED.has(p.state))
+                            await this.check(node, p.ref);
+                    }
+                }
+            }
+            finally {
+                this.running = undefined;
+            }
+        })();
+        return this.running;
+    }
+    /** §5 task context: open first, then newest; truncated (never refused) at {@link TASKS_CONTEXT_MAX}. '' when none. */
+    render(node) {
+        const list = [...this.list(node)].sort((a, b) => Number(b.state === 'open') - Number(a.state === 'open') || (a.since < b.since ? 1 : a.since > b.since ? -1 : 0));
+        if (list.length === 0)
+            return '';
+        const head = '## 节点任务（a2a:node:tasks）\n\n以 GitHub 为准，这里是缓存：「未知」表示这次没能核对（没有凭证或离线）。';
+        const label = (p) => p.state === 'unknown' ? '未知' : p.check === 'unknown' ? `${p.state}（未能核对）` : p.state;
+        const lines = list.map(p => `- ${label(p)}　${p.ref}（自 ${p.since.slice(0, 10)}，契约 v${String(p.core_version)} / 自记 v${String(p.mutable_version)}）`);
+        const out = [head, ''];
+        let used = chars(head) + 2;
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            const rest = lines.length - i - 1;
+            const tail = rest > 0 ? chars(`\n另有 ${String(rest)} 条，见 GitHub。`) : 0;
+            if (used + chars(line) + 1 + tail > TASKS_CONTEXT_MAX) {
+                out.push(`另有 ${String(lines.length - i)} 条，见 GitHub。`);
+                break;
+            }
+            out.push(line);
+            used += chars(line) + 1;
+        }
+        return out.join('\n');
+    }
+}

package/lib/origin-claim.js

@@ -0,0 +1,246 @@
+/**
+ * OriginClaim envelope (gh#9+gh#10, docs/protocol/delivery-origin-auth.md):
+ * the signer every outbound peer request stamps and the verifier every peer
+ * face (card, /a2a/direct, /a2a/log, /a2a/canvas-op, /a2a/canvas-changed)
+ * runs.
+ *
+ * Two canonical forms ride the same four base headers
+ * (X-A2A-Caller / -Url / -Ts):
+ *   · bound (v2, §2.1): JSON.stringify([tag, caller, callerUrl, ts,
+ *     audience, METHOD, path]) in X-A2A-Caller-Sig2, the audience origin in
+ *     X-A2A-Caller-Aud. The verifier requires the audience to be one of its
+ *     own origins and signs-over its own method and path, so an envelope is
+ *     good at exactly the host and route it was made for.
+ *   · unbound (v1, legacy): JSON.stringify([caller, callerUrl, ts]) in
+ *     X-A2A-Caller-Sig. Emitted and accepted only while the unbound window
+ *     is open (originClaimUnboundWindow); accepted ones are counted.
+ * Once the window closes a present Sig2 is the only thing verified. While
+ * it is open, a Sig2 that misses (audience or signature) falls back to the
+ * Sig the envelope also carries — no more than stripping Sig2 would give —
+ * and the miss is counted, so a peer dialled by an unlisted name keeps
+ * working through the rollout and shows on the gauge.
+ */
+import { createPublicKey, sign as edSign, verify as edVerify } from 'node:crypto';
+import { verifyCard } from "./card.js";
+/** ts skew tolerance (protocol constant, §7). */
+export const ORIGIN_CLAIM_SKEW_MS = 5 * 60_000;
+/** Domain tag of the bound form: a v1 signature can never verify as v2. */
+export const ORIGIN_CLAIM_BOUND_TAG = 'a2a-origin-claim/2';
+/** Only the canonical origin root can claim that origin's identity. */
+export function isRootOriginUrl(value) {
+    try {
+        const url = new URL(value);
+        return (url.protocol === 'http:' || url.protocol === 'https:') && url.username === '' && url.password === '' && url.pathname === '/' && url.search === '' && url.hash === '';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * #189 follow-up: whether a path-prefixed claim URL is EXACTLY a peer URL the operator seeded (a
+ * mounted card endpoint, delivery-origin-auth §"挂载卡片端点"): same origin and same path (trailing
+ * slashes ignored), neither carrying userinfo, query or fragment. A different path under the same
+ * origin is a different publisher and never matches.
+ */
+export function sameMountedUrl(seeded, claimUrl) {
+    try {
+        const a = new URL(seeded);
+        const b = new URL(claimUrl);
+        const clean = (u) => (u.protocol === 'http:' || u.protocol === 'https:') && u.username === '' && u.password === '' && u.search === '' && u.hash === '';
+        const path = (u) => u.pathname.replace(/\/+$/, '');
+        return clean(a) && clean(b) && a.origin === b.origin && path(a) !== '' && path(a) === path(b);
+    }
+    catch {
+        return false;
+    }
+}
+/** The unbound (v1) canonical form. */
+export function unboundCanonical(caller, callerUrl, ts) {
+    return JSON.stringify([caller, callerUrl, ts]);
+}
+/** The bound (v2) canonical form; method upper-cased, path without query. */
+export function boundCanonical(caller, callerUrl, ts, audience, method, path) {
+    return JSON.stringify([ORIGIN_CLAIM_BOUND_TAG, caller, callerUrl, ts, audience, method.toUpperCase(), path]);
+}
+/** An origin in URL's normal form, or '' when the text is not an http(s) URL. */
+export function originOf(url) {
+    try {
+        const parsed = new URL(url);
+        return parsed.protocol === 'http:' || parsed.protocol === 'https:' ? parsed.origin : '';
+    }
+    catch {
+        return '';
+    }
+}
+/** The path a request names, without its query (the bound form signs this). */
+export function pathOf(url) {
+    try {
+        return new URL(url, 'http://x').pathname;
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Sign one envelope for `target`. The bound form is always present; the
+ * unbound one only while `unbound` (the window) is open, so an upgraded
+ * host stops signing the unbound form the moment it closes.
+ */
+export function signOriginClaim(target, signer) {
+    const { caller, callerUrl, privateKey, now: ts } = signer;
+    const sign = (text) => edSign(undefined, Buffer.from(text, 'utf8'), privateKey).toString('base64');
+    const headers = {
+        'X-A2A-Caller': caller,
+        'X-A2A-Caller-Url': callerUrl,
+        'X-A2A-Caller-Ts': String(ts),
+    };
+    const audience = originOf(target.url);
+    if (audience !== '') {
+        headers['X-A2A-Caller-Aud'] = audience;
+        headers['X-A2A-Caller-Sig2'] = sign(boundCanonical(caller, callerUrl, ts, audience, target.method, pathOf(target.url)));
+    }
+    if (signer.unbound)
+        headers['X-A2A-Caller-Sig'] = sign(unboundCanonical(caller, callerUrl, ts));
+    return headers;
+}
+/** IPv4-mapped and bare IPv6 socket addresses in URL host form. */
+function hostForm(address) {
+    const plain = address.startsWith('::ffff:') ? address.slice(7) : address;
+    return plain.includes(':') ? `[${plain}]` : plain;
+}
+/**
+ * The origins this host answers to for one request: the configured ones
+ * (own card URL, operator aliases) plus the address the request actually
+ * arrived on — the socket's LOCAL end, which a sender cannot choose (unlike
+ * the Host header). A loopback arrival answers to all its loopback
+ * spellings — unless `loopbackArrival` is off (originClaimUrl declares a
+ * tunnel or proxy, whose requests all arrive on loopback), and then only
+ * when a configured origin is loopback at that port.
+ */
+export function requestAudiences(req, configured, loopbackArrival = true) {
+    const out = new Set();
+    for (const url of configured) {
+        const origin = originOf(url);
+        if (origin !== '')
+            out.add(origin);
+    }
+    const socket = req.socket;
+    const local = socket?.localAddress;
+    const port = socket?.localPort;
+    if (local !== undefined && port !== undefined) {
+        const scheme = socket?.encrypted === true ? 'https' : 'http';
+        const host = hostForm(local);
+        const loopback = host === '[::1]' || /^127\./.test(host);
+        const spellings = [host, '127.0.0.1', 'localhost', '[::1]'].map(name => originOf(`${scheme}://${name}:${String(port)}`));
+        const names = loopback ? (loopbackArrival || spellings.some(origin => out.has(origin)) ? spellings : []) : [spellings[0]];
+        for (const origin of names)
+            if (origin !== '')
+                out.add(origin);
+    }
+    return out;
+}
+const originClaimCallerShape = /^[a-z0-9-]+$/i;
+/**
+ * Verify one request's envelope. Cheap refusals (shape, ts, audience,
+ * closed window) answer before any card fetch; the card is then read from
+ * the shared cache or fetched PLAIN from the caller's well-known URL.
+ */
+export async function verifyOriginClaim(req, d) {
+    const header = (name) => String(req.headers[name] ?? '');
+    const caller = header('x-a2a-caller');
+    const callerUrl = header('x-a2a-caller-url');
+    const ts = Number(header('x-a2a-caller-ts'));
+    const unboundSig = header('x-a2a-caller-sig');
+    const boundSig = header('x-a2a-caller-sig2');
+    const audience = header('x-a2a-caller-aud');
+    if (caller === '' || callerUrl === '' || !Number.isFinite(ts) || ts <= 0 || (unboundSig === '' && boundSig === ''))
+        return { ok: false, reason: 'absent' };
+    if (!originClaimCallerShape.test(caller))
+        return { ok: false, reason: 'bad-caller-shape' };
+    if (Math.abs(d.now - ts) > ORIGIN_CLAIM_SKEW_MS)
+        return { ok: false, reason: 'bad-ts' };
+    const hasBound = boundSig !== '';
+    const audienceOk = hasBound && requestAudiences(req, d.audiences, d.loopbackArrival ?? true).has(originOf(audience));
+    const fallback = d.unboundOpen && unboundSig !== '';
+    if (hasBound && !audienceOk && !fallback)
+        return { ok: false, reason: 'wrong-audience' };
+    if (!hasBound && !d.unboundOpen)
+        return { ok: false, reason: 'unbound-closed' };
+    const verifies = (card, canonical, signature) => {
+        try {
+            const publicKey = createPublicKey({ key: Buffer.from(card.publicKey, 'base64'), format: 'der', type: 'spki' });
+            return edVerify(undefined, Buffer.from(canonical, 'utf8'), publicKey, Buffer.from(signature, 'base64'));
+        }
+        catch {
+            return false;
+        }
+    };
+    // Only a successful bound signature is origin proof. A v1/fallback
+    // signature is accepted for migration compatibility but remains unbound.
+    let bound = false;
+    const signedBy = (card) => {
+        bound = audienceOk && verifies(card, boundCanonical(caller, callerUrl, ts, audience, req.method ?? '', pathOf(req.url ?? '')), boundSig);
+        return bound || (fallback && verifies(card, unboundCanonical(caller, callerUrl, ts), unboundSig));
+    };
+    const accepted = () => {
+        if (bound)
+            return;
+        d.onUnbound();
+        if (hasBound)
+            d.onBoundMiss?.();
+    };
+    // gh#133: a CLI identity deposited HERE, decided from the deposit table
+    // before any fetch (the CLI may reach its home through a proxy the host
+    // cannot dial back). Same forms, audience and window as a zone claim.
+    const cli = d.cliDeposit?.(callerUrl);
+    if (cli !== undefined) {
+        if (cli.card === undefined)
+            return { ok: false, reason: 'no-card' };
+        if (!signedBy(cli.card))
+            return { ok: false, reason: 'bad-sig' };
+        if (cli.name !== caller)
+            return { ok: false, reason: 'not-derivable' };
+        accepted();
+        return { ok: true, caller: cli.handle, callerUrl, card: cli.card, bound, cli: true };
+    }
+    // Fetch the caller's card PLAIN (REVIEW M2 third-round ruling: the
+    // envelope names a BARE ZONE, and derivation is the exact match
+    // card.team === caller below — both ride the minimal card's signed core,
+    // so a single envelope-less fetch suffices and never recurses). A warm
+    // cache entry short-circuits the fetch.
+    let card = d.cardCache.get(callerUrl)?.card;
+    if (card === undefined) {
+        try {
+            // callerUrl is the caller's BASE URL — the card lives under it.
+            const cardBase = new URL(callerUrl);
+            cardBase.username = '';
+            cardBase.password = '';
+            cardBase.pathname = `${cardBase.pathname.replace(/\/+$/, '')}/.well-known/agent-card.json`;
+            cardBase.search = '';
+            cardBase.hash = '';
+            const cardUrl = cardBase.toString();
+            const response = await d.fetch(cardUrl, { method: 'GET', headers: {}, redirect: 'manual' });
+            if (response.status >= 300 && response.status < 400)
+                return { ok: false, reason: 'not-derivable' };
+            const verdict = verifyCard(JSON.parse(await response.text()), Date.now());
+            if (verdict.ok)
+                card = verdict.card;
+        }
+        catch {
+            card = undefined;
+        }
+    }
+    if (card === undefined)
+        return { ok: false, reason: 'no-card' };
+    if (!signedBy(card))
+        return { ok: false, reason: 'bad-sig' };
+    // Derivation (REVIEW M2, third-round ruling): card.team === caller EXACT.
+    // A zone/id8 envelope is bad-caller-shape at the gate — session identity
+    // rides the body's caller_session, judged by N3/S3 against the PUBLISHED
+    // roster (the prefix variant let a same-zone foreign host sign a target's
+    // session handle with its own key).
+    if (card.team !== caller)
+        return { ok: false, reason: 'not-derivable' };
+    accepted();
+    return { ok: true, caller, callerUrl, card, bound };
+}