@nelsonlongxiang/dsh-open-a2a-net 0.6.25 → 0.6.27

package/lib/cli-deposit.js

@@ -0,0 +1,141 @@
+/**
+ * CLI 户口登记处 (gh#45, owner rulings 2026-10-24):
+ *   ① handle = <agent-name>/<uuid·8B (16 hex)> — the name is custom, the
+ *      suffix is forced 16-hex by shape gate;
+ *   ② one key, multiple registrations — v1: the local home host;
+ *   ③ deposit TTL: default AND max 4h — expiry auto-deregisters (the CLI
+ *      vanishes from the card face and the directory; re-publish returns).
+ *
+ * The deposit is the CLI's "household registration": the home host serves
+ * the CLI's SIGNED card at /a2a/cli/<handle>/.well-known/agent-card.json
+ * (an OriginClaim fetch of the CLI envelope lands exactly there), lists
+ * the handle in its own card's sessionTeams (so the whole fleet sees the
+ * CLI as a member card — draggable into canvas teams = the operator link),
+ * and holds a mailbox for inbound deliveries (receipts land here; the CLI
+ * polls while alive).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { verifyCard } from "./card.js";
+/** Owner ruling ③: the default AND maximum online window. */
+export const CLI_DEPOSIT_TTL_MS = 4 * 60 * 60 * 1000;
+/** Owner ruling ①: <agent-name>/<uuid·8B>. The name is [a-z0-9-]{1,32}. */
+export const CLI_HANDLE_RE = /^([a-z0-9-]{1,32})\/([0-9a-f]{16})$/;
+const MAILBOX_CAP = 64;
+export class CliDepositStore {
+    path;
+    deposits = new Map();
+    mailbox = new Map();
+    now;
+    constructor(path, options) {
+        this.path = path;
+        this.now = options?.now ?? (() => Date.now());
+        this.restore();
+    }
+    /** Deposit (or refresh) one CLI card. TTL is clamped to the 4h ruling. */
+    deposit(cardJson) {
+        let parsed;
+        try {
+            parsed = JSON.parse(cardJson);
+        }
+        catch {
+            return { ok: false, error: 'card is not JSON' };
+        }
+        const verdict = verifyCard(parsed, this.now());
+        if (!verdict.ok)
+            return { ok: false, error: `card verification failed (${verdict.reason})` };
+        if (typeof verdict.card.team !== 'string' || !CLI_HANDLE_RE.test(verdict.card.team)) {
+            return { ok: false, error: `card.team must be the CLI handle <agent-name>/<uuid16hex>, got "${String(verdict.card.team)}"` };
+        }
+        const handle = verdict.card.team;
+        const name = CLI_HANDLE_RE.exec(handle)[1];
+        if (verdict.card.team !== `${name}/${CLI_HANDLE_RE.exec(handle)[2]}`)
+            return { ok: false, error: 'handle mismatch' };
+        const ttl = Math.min(CLI_DEPOSIT_TTL_MS, CLI_DEPOSIT_TTL_MS);
+        const at = this.now();
+        const row = { handle, name, cardJson, depositedAt: at, expiresAt: at + ttl };
+        this.deposits.set(handle, row);
+        this.persist();
+        return { ok: true, handle, expiresAt: row.expiresAt };
+    }
+    revoke(handle) {
+        const had = this.deposits.delete(handle);
+        if (had)
+            this.persist();
+        return had;
+    }
+    /** Active deposits (sweeping expired ones — ruling ③ auto-deregister). */
+    list() {
+        this.sweep();
+        return [...this.deposits.values()];
+    }
+    get(handle) {
+        const row = this.deposits.get(handle);
+        if (row === undefined)
+            return undefined;
+        if (row.expiresAt <= this.now()) {
+            this.deposits.delete(handle);
+            this.persist();
+            return undefined;
+        }
+        return row;
+    }
+    /** Card-serve rows: the handle + display name, marked cli (no wake). */
+    cardRows() {
+        return this.list().map(row => ({ team: row.handle, name: row.name, description: 'cli — deposited identity (no wake; mailbox)' }));
+    }
+    mail(handle, from, text) {
+        const list = this.mailbox.get(handle) ?? [];
+        list.unshift({ at: this.now(), from, text: text.slice(0, 4000) });
+        this.mailbox.set(handle, list.slice(0, MAILBOX_CAP));
+        this.persist();
+    }
+    readMail(handle) {
+        return [...(this.mailbox.get(handle) ?? [])];
+    }
+    sweep() {
+        const now = this.now();
+        let changed = false;
+        for (const [handle, row] of this.deposits) {
+            if (row.expiresAt <= now) {
+                this.deposits.delete(handle);
+                changed = true;
+            }
+        }
+        if (changed)
+            this.persist();
+    }
+    persist() {
+        const mailbox = {};
+        for (const [handle, list] of this.mailbox)
+            mailbox[handle] = [...list];
+        const snapshot = { deposits: [...this.deposits.values()], mailbox };
+        try {
+            mkdirSync(join(this.path, '..'), { recursive: true });
+            writeFileSync(this.path, JSON.stringify(snapshot), 'utf8');
+        }
+        catch {
+            // persistence best-effort; the deposit re-publishes self-heal
+        }
+    }
+    restore() {
+        if (this.path === '' || !existsSync(this.path))
+            return;
+        try {
+            const snapshot = JSON.parse(readFileSync(this.path, 'utf8'));
+            for (const row of snapshot.deposits ?? []) {
+                if (typeof row?.handle === 'string' && typeof row.cardJson === 'string' && typeof row.expiresAt === 'number') {
+                    this.deposits.set(row.handle, row);
+                }
+            }
+            for (const [handle, list] of Object.entries(snapshot.mailbox ?? {})) {
+                if (Array.isArray(list))
+                    this.mailbox.set(handle, list.filter(m => m !== null && typeof m === 'object'));
+            }
+            this.sweep();
+        }
+        catch {
+            // corrupt file: start empty (re-publish heals)
+        }
+    }
+}