@nelsonlongxiang/dsh-open-a2a-net 0.6.31 → 0.6.33

package/lib/a2a-client.js

@@ -29,7 +29,7 @@ export class A2aClient {
     constructor(options) {
         this.options = options;
     }
-    headers(json) {
+    headers(json, url, method) {
         const headers = {};
         if (json)
             headers['Content-Type'] = 'application/json';
@@ -43,7 +43,7 @@ export class A2aClient {
         // peer request when the signer is wired (full-card reads and delivery
         // verification both ride it).
         if (this.options.originClaim !== undefined) {
-            for (const [key, value] of Object.entries(this.options.originClaim()))
+            for (const [key, value] of Object.entries(this.options.originClaim({ url, method })))
                 headers[key] = value;
         }
         return headers;
@@ -62,9 +62,10 @@ export class A2aClient {
         };
         init.signal?.addEventListener('abort', abort, { once: true });
         try {
-            const response = await this.options.fetch(`${baseUrl}${path}`, {
+            const url = `${baseUrl}${path}`;
+            const response = await this.options.fetch(url, {
                 method: init.method,
-                headers: this.headers(init.body !== undefined),
+                headers: this.headers(init.body !== undefined, url, init.method),
                 ...(init.body !== undefined ? { body: init.body } : {}),
                 signal: controller.signal,
             });
@@ -256,6 +257,8 @@ export class A2aClient {
         // the receipt contract back to the caller's team instead. A bridged
         // native round carries the peer's `bridge` marker and promises NO
         // receipt: the text must not claim one the slice will never send.
+        // gh#141: the peer's enforce verdict on a receipt this message carried (#139).
+        const settlementRefused = raw.settlement?.status === 'refused';
         if (raw.routed === true && raw.delivered === true) {
             const taskId = wireText(raw.task_id) !== '' ? wireText(raw.task_id) : taskIdFromCaller ?? '';
             const bridge = wireBridge(raw.bridge);
@@ -276,6 +279,7 @@ export class A2aClient {
                 task_status: wireText(raw.task_status) === '' ? 'TASK_STATE_DELIVERED' : wireText(raw.task_status),
                 ...(consumed !== undefined ? { consumed } : {}),
                 ...(bridge !== undefined ? { bridge } : {}),
+                ...(settlementRefused ? { settlementRefused: true } : {}),
             };
         }
         const reply = this.replyText(raw.result, '');
@@ -290,6 +294,7 @@ export class A2aClient {
             context_id: wireText(raw.context_id),
             task_status: wireText(raw.task_status),
             ...(bridge !== undefined ? { bridge } : {}),
+            ...(settlementRefused ? { settlementRefused: true } : {}),
         };
     }
     /**

package/lib/auth-observer.js

@@ -0,0 +1,254 @@
+/**
+ * Allowlist change observer (gh#114 S6, design docs/design/114-task-authorization.md §5).
+ *
+ * When the records admission reads change — joins, canvas membership, roster
+ * declarations, CLI deposits, peer seeds — the allowlist version (§2.3)
+ * moves. This module keeps the version history and, on every move, re-judges
+ * the unsettled tasks that carry an authorization record against the CURRENT
+ * records, producing an "affected tasks" list.
+ *
+ * OBSERVE MODE ONLY. Nothing here cancels a task, changes a row's state,
+ * nudges a session or blocks a receipt: the judgement is a pure read and its
+ * output is a record. Enforcing it (revalidate before resume, design §5 last
+ * paragraph) needs its own owner ruling.
+ *
+ * Persistence at `<dsh-home>/a2a/auth-versions.json`, two rings of
+ * {@link AUTH_HISTORY_CAP}: the version history `{version, at, cause, inputs}`
+ * and the affected-task entries. A corrupt file is dropped whole; malformed
+ * entries are dropped one by one. No timers: the host calls {@link observe}
+ * lazily and at its known change points.
+ * @module @nelsonlongxiang/dsh-open-a2a-net/auth-observer
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+/** Ring size of both the version history and the affected-task entries. */
+export const AUTH_HISTORY_CAP = 32;
+/** Longest refusal text kept on an affected task (the faces' texts fit; a longer one is cut, flagged by `…`). */
+export const AFFECTED_REASON_CAP = 400;
+/**
+ * Re-judge rows against today's records — pure: `judge` must be a read-only
+ * admission decision (task-auth.ts callerAdmission over the live records).
+ * A row is judged when it carries a record and either was born under another
+ * version than `version` or `cacheResting(row)` says its admission rests on
+ * the peer-card cache (`peer-org`, which the version does not hash; by
+ * default: the birth record's `via`).
+ * @returns the affected rows, in ledger order; unaffected rows are omitted.
+ */
+export function judgeAffected(rows, version, judge, cacheResting = bornOnCache) {
+    const affected = [];
+    for (const row of rows) {
+        const outcome = judgeRow(row, version, judge, cacheResting);
+        if (outcome?.task !== undefined)
+            affected.push(outcome.task);
+    }
+    return affected;
+}
+const bornOnCache = (row) => row.auth?.via === 'peer-org';
+/** One row's re-judgement: undefined when the row is not judged; `task` only when it is affected. */
+function judgeRow(row, version, judge, cacheResting) {
+    const auth = row.auth;
+    if (auth === undefined)
+        return undefined;
+    if (auth.allowlist_version === version && !cacheResting(row))
+        return undefined;
+    // #142 review P2: a record is re-judged by the rule of the face that admitted it.
+    const verdict = judge(auth.caller, auth.target, auth.ingress);
+    const base = { taskId: row.taskId, direction: row.direction ?? 'inbound', caller: auth.caller, target: auth.target };
+    if (!verdict.ok) {
+        const reason = verdict.refusal.length <= AFFECTED_REASON_CAP ? verdict.refusal : `${verdict.refusal.slice(0, AFFECTED_REASON_CAP - 1)}…`;
+        return { admission: verdict, task: { ...base, verdict: 'would-revoke', reason } };
+    }
+    if (basisHolds(auth.basis, auth.admission_rule, verdict))
+        return { admission: verdict };
+    return { admission: verdict, task: { ...base, verdict: 'basis-changed', reason: `admitted by ${verdict.rule} on [${verdict.basis.join(', ')}], was ${auth.admission_rule} on [${auth.basis.join(', ')}]` } };
+}
+/**
+ * The dedupe key of a report: `would-revoke` is one state whatever the
+ * refusal text (one /leave writes three stores, each worded differently);
+ * `basis-changed` is keyed by the new rule and basis its reason names.
+ */
+const reportKey = (task) => (task.verdict === 'would-revoke' ? 'would-revoke' : `basis-changed\n${task.reason}`);
+/**
+ * Whether today's admission still rests on the record's basis: the shared
+ * teams overlap, or — for basis-less rules (host-face, node-fact,
+ * cli-deposit, scope-off) — the same rule admits again.
+ */
+function basisHolds(was, wasRule, now) {
+    if (was.length === 0 && now.basis.length === 0)
+        return now.rule === wasRule;
+    return was.some(team => now.basis.includes(team));
+}
+/**
+ * The persisted observer. One instance per host; every entry point is
+ * total and never throws (an unwritable home degrades to memory-only).
+ */
+export class AuthObserver {
+    path;
+    now;
+    versions = [];
+    affected = [];
+    /**
+     * The last report per task ({@link reportKey}), so a task still affected
+     * the same way is not listed again — on a peer-org recheck poll, nor on a
+     * later unrelated version move. A task judged unaffected is forgotten, so
+     * a relapse reports again; a task gone from the rows is pruned.
+     * Boot-local by design: after a restart the next version change reports
+     * afresh.
+     */
+    reported = new Map();
+    /**
+     * The rule of each task's latest passing judgement. Whether a row rests on
+     * the peer-card cache is read from here first, the birth record second: a
+     * row born remote-ref-samezone that today passes only through `peer-org`
+     * is rechecked like one born there (and stops being once a firm rule
+     * admits it again).
+     */
+    lastRule = new Map();
+    constructor(path, now = Date.now) {
+        this.path = path;
+        this.now = now;
+        this.restore();
+    }
+    /** The version history, newest first. */
+    history() {
+        return [...this.versions];
+    }
+    /** The affected-task entries, newest first. */
+    entries() {
+        return [...this.affected];
+    }
+    /**
+     * Record the current version when it moved, and re-judge.
+     * - Version moved: append it to the history; judge every row born under
+     *   another version and every cache-resting row.
+     * - Version unchanged: only cache-resting rows are re-judged.
+     * - Cause `boot`: cache-resting rows are not judged at all — the peer-card
+     *   cache is empty at boot, so every one of them would read as refused.
+     *   The first read after boot (`lazy`) rechecks them.
+     * Either way a task is reported only when its report differs from the
+     * last one for it ({@link reportKey}).
+     * @returns the new affected entry, or undefined when nothing was affected.
+     */
+    observe(input) {
+        try {
+            const last = this.versions[0]?.version ?? null;
+            const moved = last !== input.version;
+            if (moved) {
+                this.versions = [{ version: input.version, at: this.now(), cause: input.cause, inputs: input.inputs() }, ...this.versions].slice(0, AUTH_HISTORY_CAP);
+            }
+            const all = input.rows();
+            this.prune(all);
+            const cacheResting = (row) => {
+                const rule = this.lastRule.get(row.taskId);
+                return rule !== undefined ? rule === 'peer-org' : bornOnCache(row);
+            };
+            const coldCache = input.cause === 'boot';
+            const rows = all.filter(row => (coldCache ? !cacheResting(row) : moved || cacheResting(row)));
+            const tasks = [];
+            for (const row of rows) {
+                const outcome = judgeRow(row, input.version, input.judge, cacheResting);
+                if (outcome === undefined)
+                    continue;
+                if (outcome.admission.ok)
+                    this.lastRule.set(row.taskId, outcome.admission.rule);
+                if (outcome.task === undefined) {
+                    this.reported.delete(row.taskId);
+                    continue;
+                }
+                const key = reportKey(outcome.task);
+                if (this.reported.get(row.taskId) === key)
+                    continue;
+                this.reported.set(row.taskId, key);
+                tasks.push(outcome.task);
+            }
+            if (tasks.length === 0) {
+                if (moved)
+                    this.persist();
+                return undefined;
+            }
+            const entry = { at: this.now(), from_version: moved ? last : input.version, to_version: input.version, cause: moved ? input.cause : 'peer-org-recheck', tasks };
+            this.affected = [entry, ...this.affected].slice(0, AUTH_HISTORY_CAP);
+            this.persist();
+            return entry;
+        }
+        catch {
+            // Observation is bookkeeping: a failure here must never reach routing.
+            return undefined;
+        }
+    }
+    /** Forget the per-task memory of tasks no longer among the unsettled rows. */
+    prune(rows) {
+        const live = new Set(rows.map(row => row.taskId));
+        for (const map of [this.reported, this.lastRule]) {
+            for (const taskId of map.keys())
+                if (!live.has(taskId))
+                    map.delete(taskId);
+        }
+    }
+    restore() {
+        if (this.path === '' || !existsSync(this.path))
+            return;
+        try {
+            const snapshot = JSON.parse(readFileSync(this.path, 'utf8'));
+            const versions = Array.isArray(snapshot?.versions) ? snapshot.versions : [];
+            const affected = Array.isArray(snapshot?.affected) ? snapshot.affected : [];
+            this.versions = versions.map(parseVersion).filter((entry) => entry !== undefined).slice(0, AUTH_HISTORY_CAP);
+            this.affected = affected.map(parseAffected).filter((entry) => entry !== undefined).slice(0, AUTH_HISTORY_CAP);
+        }
+        catch {
+            // A corrupt file is dropped whole: the next observation starts a fresh history.
+            this.versions = [];
+            this.affected = [];
+        }
+    }
+    persist() {
+        if (this.path === '')
+            return;
+        try {
+            mkdirSync(dirname(this.path), { recursive: true });
+            // tmp + rename: a crash mid-write leaves the previous file, never a torn one.
+            const tmp = `${this.path}.${String(process.pid)}.tmp`;
+            writeFileSync(tmp, JSON.stringify({ versions: this.versions, affected: this.affected }), { mode: 0o600 });
+            renameSync(tmp, this.path);
+        }
+        catch {
+            // An unwritable home must not break routing; the history degrades to memory-only.
+        }
+    }
+}
+const VERSION_SHAPE = /^al1:[0-9a-f]{16}$/;
+const isRecord = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const finiteTime = (v) => typeof v === 'number' && Number.isFinite(v);
+const shortString = (v, cap = 256) => typeof v === 'string' && v !== '' && v.length <= cap;
+function parseVersion(raw) {
+    if (!isRecord(raw))
+        return undefined;
+    if (typeof raw.version !== 'string' || !VERSION_SHAPE.test(raw.version) || !finiteTime(raw.at) || !shortString(raw.cause, 64))
+        return undefined;
+    return { version: raw.version, at: raw.at, cause: raw.cause, inputs: raw.inputs ?? null };
+}
+function parseAffected(raw) {
+    if (!isRecord(raw) || !finiteTime(raw.at) || !shortString(raw.cause, 64))
+        return undefined;
+    if (typeof raw.to_version !== 'string' || !VERSION_SHAPE.test(raw.to_version))
+        return undefined;
+    if (raw.from_version !== null && (typeof raw.from_version !== 'string' || !VERSION_SHAPE.test(raw.from_version)))
+        return undefined;
+    if (!Array.isArray(raw.tasks))
+        return undefined;
+    const tasks = [];
+    for (const task of raw.tasks) {
+        if (!isRecord(task))
+            return undefined;
+        if (!shortString(task.taskId) || !shortString(task.caller) || !shortString(task.target))
+            return undefined;
+        if (task.direction !== 'inbound' && task.direction !== 'outbound')
+            return undefined;
+        if (task.verdict !== 'basis-changed' && task.verdict !== 'would-revoke')
+            return undefined;
+        if (!shortString(task.reason, AFFECTED_REASON_CAP + 200))
+            return undefined;
+        tasks.push({ taskId: task.taskId, direction: task.direction, caller: task.caller, target: task.target, verdict: task.verdict, reason: task.reason });
+    }
+    return { at: raw.at, from_version: raw.from_version, to_version: raw.to_version, cause: raw.cause, tasks };
+}

package/lib/blob-store.js

@@ -0,0 +1,210 @@
+/**
+ * #91 file channel, slice F1 (docs/design/file-channel.md §3.1–§3.2, §5): the sender host's
+ * content-addressed blob store and its grants. A file never rides a session message: the sender
+ * stages it here (by sha256), a grant names who may pull it and until when, and the session
+ * message carries only a reference line ({@link formatFileRef}). This module is pure storage —
+ * the wire face (admission, OriginClaim) and the tools sit on top of it.
+ *
+ * - Blobs live at `<root>/blobs/<sha256>`, written tmp + rename; identical bytes are stored once.
+ * - Grants live in `<root>/blob-grants.json`, one per (sha256, to): re-sending the same blob to
+ *   the same target only extends its expiry.
+ * - Capacity: one file ≤ {@link BLOB_FILE_MAX}; the store ≤ {@link BLOB_TOTAL_MAX} bytes and
+ *   ≤ {@link BLOB_COUNT_MAX} blobs. A full store first drops expired grants and the blobs no
+ *   live grant names, then refuses visibly — a live grant is never pushed out.
+ * - A grants file that does not parse is set aside and read as EMPTY (fail-closed: references
+ *   already sent stop resolving, nothing is served by mistake).
+ * @module @nelsonlongxiang/dsh-open-a2a-net/blob-store
+ */
+import { createHash } from 'node:crypto';
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** One file's ceiling, in bytes (64 MiB; design §8). */
+export const BLOB_FILE_MAX = 64 * 1024 * 1024;
+/** The store's ceiling, in bytes (1 GiB). */
+export const BLOB_TOTAL_MAX = 1024 * 1024 * 1024;
+/** The store's ceiling, in blobs. */
+export const BLOB_COUNT_MAX = 256;
+/** How long a grant lets its target pull (24h). */
+export const BLOB_GRANT_TTL_MS = 24 * 60 * 60 * 1000;
+/** A sanitized file name's length cap. */
+export const BLOB_NAME_MAX = 120;
+const SHA256_RE = /^[0-9a-f]{64}$/;
+/** A file name that can only land inside the inbox: no path, no `..`, no control characters, bounded. */
+export function sanitizeBlobName(name) {
+    const base = (name.split(/[\\/]/).pop() ?? '')
+        // eslint-disable-next-line no-control-regex
+        .replace(/[\u0000-\u001f\u007f]/g, '')
+        .replace(/\.\.+/g, '.')
+        .replace(/^[.\s]+/, '')
+        .trim();
+    const capped = base.slice(0, BLOB_NAME_MAX);
+    return capped === '' ? 'file' : capped;
+}
+/** The one-line reference a session message carries (design §3.1). */
+export function formatFileRef(ref) {
+    return `[A2A file] v1 sha256=${ref.sha256} size=${String(ref.size)} name=${encodeURIComponent(sanitizeBlobName(ref.name))} from=${ref.from}`;
+}
+/** Parse a reference line (anywhere in a message); undefined when it is not a well-formed v1 reference. */
+export function parseFileRef(text) {
+    const m = /\[A2A file\] v1 sha256=([0-9a-f]{64}) size=(\d{1,12}) name=(\S{1,512}) from=(https?:\/\/\S{1,2048})/.exec(text);
+    if (m === null)
+        return undefined;
+    const size = Number(m[2]);
+    if (!Number.isSafeInteger(size) || size > BLOB_FILE_MAX)
+        return undefined;
+    let name;
+    try {
+        name = decodeURIComponent(m[3]);
+    }
+    catch {
+        return undefined;
+    }
+    let from;
+    try {
+        from = new URL(m[4]);
+    }
+    catch {
+        return undefined;
+    }
+    // Only the origin is a pull target: a path, query or credentials on the URL are refused.
+    if (from.username !== '' || from.password !== '' || (from.pathname !== '/' && from.pathname !== '') || from.search !== '' || from.hash !== '')
+        return undefined;
+    return { sha256: m[1], size, name: sanitizeBlobName(name), from: from.origin };
+}
+export class BlobStore {
+    root;
+    now;
+    grants = [];
+    /**
+     * @param root - the store's directory (`<home>/a2a`); '' = in-memory grants and no blob files (tests of the grant logic only).
+     * @param now - clock (tests).
+     */
+    constructor(root, now = () => Date.now()) {
+        this.root = root;
+        this.now = now;
+        this.restore();
+    }
+    get grantsFile() { return join(this.root, 'blob-grants.json'); }
+    blobPath(sha256) { return join(this.root, 'blobs', sha256); }
+    /** Stage bytes for `to`; a repeat of the same (sha256, to) only extends the grant. */
+    stage(bytes, meta) {
+        if (typeof meta.to !== 'string' || meta.to === '' || typeof meta.by !== 'string' || meta.by === '')
+            return { ok: false, code: 'bad-request', error: 'to and by are required' };
+        if (bytes.byteLength > BLOB_FILE_MAX)
+            return { ok: false, code: 'too-large', error: `file is ${String(bytes.byteLength)} bytes; the file channel takes at most ${String(BLOB_FILE_MAX)}` };
+        const sha256 = createHash('sha256').update(bytes).digest('hex');
+        const name = sanitizeBlobName(meta.name);
+        const at = this.now();
+        const expiresAt = at + BLOB_GRANT_TTL_MS;
+        const stored = this.hasBlob(sha256);
+        if (!stored) {
+            this.sweep();
+            const blobs = this.liveBlobs();
+            const total = blobs.reduce((sum, b) => sum + b.size, 0);
+            if (blobs.length + 1 > BLOB_COUNT_MAX || total + bytes.byteLength > BLOB_TOTAL_MAX) {
+                return { ok: false, code: 'full', error: `the file store is full (${String(blobs.length)} files, ${String(total)} bytes held by live grants); retry after some expire` };
+            }
+            if (this.root !== '') {
+                mkdirSync(join(this.root, 'blobs'), { recursive: true });
+                const tmp = `${this.blobPath(sha256)}.tmp-${String(process.pid)}`;
+                writeFileSync(tmp, bytes, { mode: 0o600 });
+                renameSync(tmp, this.blobPath(sha256));
+            }
+        }
+        const grant = { sha256, size: bytes.byteLength, name, to: meta.to, by: meta.by, grantedAt: at, expiresAt };
+        this.grants = [grant, ...this.grants.filter(g => !(g.sha256 === sha256 && g.to === meta.to))];
+        this.persist();
+        return { ok: true, sha256, size: bytes.byteLength, name, expiresAt };
+    }
+    /**
+     * The live grant that lets one of `callerTeams` pull `sha256`, if any. `callerTeams` are the
+     * teams the WIRE FACE proved for the caller (OriginClaim + membership) — never self-described.
+     */
+    grantFor(sha256, callerTeams) {
+        if (!SHA256_RE.test(sha256))
+            return undefined;
+        const at = this.now();
+        return this.grants.find(g => g.sha256 === sha256 && g.expiresAt > at && callerTeams.includes(g.to));
+    }
+    /** The bytes of a granted blob (undefined when the file is gone or does not hash back). */
+    read(grant) {
+        if (this.root === '' || !this.hasBlob(grant.sha256))
+            return undefined;
+        const bytes = readFileSync(this.blobPath(grant.sha256));
+        if (bytes.byteLength !== grant.size || createHash('sha256').update(bytes).digest('hex') !== grant.sha256)
+            return undefined;
+        return bytes;
+    }
+    /** Live grants (for the state face). */
+    list() {
+        const at = this.now();
+        return this.grants.filter(g => g.expiresAt > at);
+    }
+    hasBlob(sha256) {
+        if (this.root === '')
+            return this.grants.some(g => g.sha256 === sha256);
+        return existsSync(this.blobPath(sha256));
+    }
+    /** Blobs some live grant still names, with their sizes. */
+    liveBlobs() {
+        const at = this.now();
+        const seen = new Map();
+        for (const g of this.grants)
+            if (g.expiresAt > at)
+                seen.set(g.sha256, g.size);
+        return [...seen].map(([sha256, size]) => ({ sha256, size }));
+    }
+    /** Drop expired grants and every blob file no live grant names. */
+    sweep() {
+        const at = this.now();
+        const before = this.grants.length;
+        this.grants = this.grants.filter(g => g.expiresAt > at);
+        if (this.root !== '' && existsSync(join(this.root, 'blobs'))) {
+            const keep = new Set(this.grants.map(g => g.sha256));
+            for (const file of readdirSync(join(this.root, 'blobs'))) {
+                if (keep.has(file) && statSync(join(this.root, 'blobs', file)).isFile())
+                    continue;
+                rmSync(join(this.root, 'blobs', file), { force: true, recursive: true });
+            }
+        }
+        if (this.grants.length !== before)
+            this.persist();
+    }
+    persist() {
+        if (this.root === '')
+            return;
+        mkdirSync(this.root, { recursive: true });
+        const tmp = `${this.grantsFile}.tmp-${String(process.pid)}`;
+        writeFileSync(tmp, JSON.stringify({ grants: this.grants }), { mode: 0o600 });
+        renameSync(tmp, this.grantsFile);
+    }
+    restore() {
+        if (this.root === '' || !existsSync(this.grantsFile))
+            return;
+        let raw;
+        try {
+            raw = JSON.parse(readFileSync(this.grantsFile, 'utf8'));
+        }
+        catch {
+            raw = undefined;
+        }
+        const list = raw?.grants;
+        const valid = (g) => {
+            const r = g;
+            return r !== null && typeof r === 'object' && typeof r.sha256 === 'string' && SHA256_RE.test(r.sha256)
+                && Number.isSafeInteger(r.size) && r.size >= 0 && r.size <= BLOB_FILE_MAX
+                && typeof r.name === 'string' && typeof r.to === 'string' && r.to !== '' && typeof r.by === 'string'
+                && Number.isSafeInteger(r.grantedAt) && Number.isSafeInteger(r.expiresAt);
+        };
+        if (!Array.isArray(list) || !list.every(valid)) {
+            // Fail-closed: set the file aside and serve nothing from it.
+            try {
+                copyFileSync(this.grantsFile, `${this.grantsFile}.corrupt-${String(this.now())}`);
+            }
+            catch { /* the original stays in place */ }
+            this.grants = [];
+            return;
+        }
+        this.grants = list;
+    }
+}

package/lib/canvas-store.js

@@ -240,3 +240,9 @@ export class CanvasStore {
             this.persist();
     }
 }
+/** One policy predicate for local and signed-remote canvas creation. */
+export function canvasNameReserved(raw, zone, allowlist, roster) {
+    const name = raw.trim();
+    const team = `${zone}/${name}`;
+    return name.startsWith('roster:') || allowlist.includes(team) || roster.membersOf(team).length > 0;
+}

package/lib/card.js

@@ -82,6 +82,8 @@ function referrals(wire) {
  * 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.
+ * A missing description is the D2 `exposureExcerpt: off` form, not a
+ * malformed node: retain its handle and normalize its excerpt to empty.
  * @param wire - the shape-checked card candidate.
  * @returns the session-team entries, or `undefined` when absent or malformed.
  */
@@ -93,12 +95,12 @@ function sessionTeams(wire) {
         const team = entry;
         if (typeof team?.team !== 'string' || team.team === '')
             continue;
-        if (typeof team.name !== 'string' || typeof team.description !== 'string')
+        if (typeof team.name !== 'string' || (team.description !== undefined && typeof team.description !== 'string'))
             continue;
         entries.push({
             team: team.team,
             name: team.name,
-            description: team.description,
+            description: team.description ?? '',
             ...(typeof team.workspace === 'string' && team.workspace !== '' ? { workspace: team.workspace } : {}),
         });
     }