@tpsdev-ai/flair 0.21.0 → 0.22.0

package/dist/resources/AttentionQuery.js

@@ -0,0 +1,356 @@
+/**
+ * AttentionQuery.ts — entity-scoped attention query (flair#677).
+ *
+ * POST /AttentionQuery — "what touches entity E in the last N days?", grouped
+ * by source across the five surfaces the attention plane spans: Memory,
+ * Relationship, WorkspaceState, Presence, OrgEvent. Spec:
+ * FLAIR-ATTENTION-PLANE.md ("Phase 1 — the query" + the K&S verdict's
+ * refinements). Builds on the entity vocabulary + `entities[]` fields shipped
+ * in flair#675/#676 (resources/entity-vocab.ts, schemas/*.graphql).
+ *
+ * Deliberately NOT built here (separate follow-up, FLAIR-ATTENTION-PLANE.md
+ * Phase 2): collision surfacing (joining a CALLER's own current task/
+ * WorkspaceState against teammates' for overlap), semantic/embedding
+ * matching, or a Relationship write path. This is read-only, exact-match,
+ * index-pushdown across the five sources — nothing more.
+ *
+ * ─── Per-source read-scoping (binding, per the K&S verdict) ──────────────────
+ *
+ * - Memory: through resolveReadScope() (resources/memory-read-scope.ts) — the
+ *   SAME centralized open-within-org-minus-private rule Memory.search()/
+ *   SemanticSearch.ts/MemoryBootstrap.ts use. No new scoping logic.
+ * - Relationship: mirrors Relationship.ts's OWN search() scoping (own agentId
+ *   for non-admin, unfiltered for admin/internal) — the entity condition is
+ *   ANDed with that same rule, never replacing it. Relationship carries no
+ *   visibility field yet (unlike Memory's open-within-org reframe), so the
+ *   conservative, least-surprising choice is "the same rows a direct
+ *   `POST /Relationship` search from this caller would already return."
+ * - WorkspaceState: Sherlock's Option 1 (K&S verdict, binding). WorkspaceState
+ *   is normally strictly per-agent-scoped (403 cross-agent via the exported
+ *   `WorkspaceState` resource class — see resources/WorkspaceState.ts). This
+ *   query needs teammates' WorkspaceState, so it reads the RAW generated table
+ *   object directly (`(databases as any).flair.WorkspaceState`), the same
+ *   "internal path" idiom already used elsewhere in this codebase (e.g.
+ *   OrgEvent.post()/put() call `(databases as any).flair.OrgEvent.put(...)`
+ *   directly rather than through the exported subclass) — NEVER through the
+ *   exported `WorkspaceState` class, which would just re-apply the per-agent
+ *   403 for the caller's own identity. This does NOT broaden WorkspaceState's
+ *   general read model (a plain `GET /WorkspaceState` from a non-admin agent
+ *   still 403s cross-agent, unchanged) — it is a narrow, server-computed join
+ *   scoped to one caller-supplied, validated entity string + a bounded day
+ *   window, returning only rows that matched. The exposed field set mirrors
+ *   exactly what FLAIR-ATTENTION-PLANE.md's Phase 2 write-up already names as
+ *   the intended surfaced shape (`summary`, `taskId`, `filesChanged`,
+ *   `entities`) plus bare identifiers (`id`, `agentId`, `ref`, `phase`,
+ *   `timestamp`) — never `metadata` (an undocumented free-form JSON blob with
+ *   no spec-blessed exposure here).
+ * - Presence: via the exported `Presence` resource's get() (preserves its
+ *   verified-agent currentTask content gate, #592) — never the raw table.
+ *   Presence.get()'s gate keys off a fresh TPS-Ed25519 SIGNATURE
+ *   (verifyAgentRequest), not an annotation, specifically to close the
+ *   authorizeLocal-forged-identity vector (flair#610) — so this resource
+ *   cannot just re-run resolveAgentAuth's verdict through it. Instead it
+ *   pre-seeds verifyAgentRequest's OWN per-request memoization cache
+ *   (`request._flairAgentAuth` — see resources/agent-auth.ts's
+ *   verifyAgentRequest doc: "memoized... including null... we verify once and
+ *   cache the result on the request") with the verdict THIS request already
+ *   established via resolveAgentAuth. This is not a forgery: by the time this
+ *   helper runs, `auth.kind` is already constrained to "agent" (a real
+ *   Ed25519 signature verified upstream by auth-middleware.ts/agent-auth.ts)
+ *   or "internal" (a trusted in-process call, unauthenticated-HTTP calls
+ *   never reach this point — see the top-level anonymous gate below) — it
+ *   relays an already-established fact instead of re-running a doomed second
+ *   signature check (the original request's nonce was already consumed by
+ *   auth-middleware.ts, so re-verifying the SAME raw request would collide
+ *   with the shared nonce store and spuriously read as a replay).
+ * - OrgEvent: OrgEvent's own read model has no per-agent scoping override at
+ *   all (resources/OrgEvent.ts only gates allowRead() to allowVerified() —
+ *   any verified agent/admin already reads every OrgEvent org-wide). The raw
+ *   table is queried directly purely to avoid instantiating an unneeded
+ *   Resource subclass; the effective access is identical either way.
+ *
+ * No source here EVER receives a global/unscoped entity scan: every query
+ * carries EITHER the source's own read-scope condition (Memory,
+ * Relationship, OrgEvent's already-org-open model) OR a narrowly-targeted,
+ * validated single-entity + bounded-window condition (WorkspaceState), OR
+ * goes through the source's own content-gated resource (Presence).
+ */
+import { Resource, databases } from "@harperfast/harper";
+import { resolveAgentAuth, allowVerified } from "./agent-auth.js";
+import { isValidEntity } from "./entity-vocab.js";
+import { resolveReadScope } from "./memory-read-scope.js";
+import { withDetachedTxn } from "./table-helpers.js";
+import { checkRateLimit, rateLimitResponse } from "./rate-limiter.js";
+import { wrapUntrusted } from "./content-safety.js";
+import { getPresenceRoster } from "./presence-internal.js";
+// ─── Tunables ─────────────────────────────────────────────────────────────────
+export const DEFAULT_WINDOW_DAYS = 7;
+const MAX_WINDOW_DAYS = 365;
+// Per-source result cap. The attention view is meant to surface "what's
+// touching this entity right now", not paginate a full history — a hot
+// entity (e.g. a widely-referenced repo) is capped rather than returning an
+// unbounded payload. Each source is independently capped (not a shared total).
+const MAX_RESULTS_PER_SOURCE = 25;
+const JSON_HEADERS = { "Content-Type": "application/json" };
+function badRequest(error, detail) {
+    return new Response(JSON.stringify({ error, ...(detail ? { detail } : {}) }), {
+        status: 400,
+        headers: JSON_HEADERS,
+    });
+}
+const UNAUTH = () => new Response(JSON.stringify({ error: "authentication required" }), { status: 401, headers: JSON_HEADERS });
+function parseQueryInput(data) {
+    const entity = data?.entity;
+    if (typeof entity !== "string" || entity.length === 0) {
+        return badRequest("invalid_entity", "entity is required (a vocabulary string, e.g. 'repo:owner/name')");
+    }
+    // Exact match on the full type:value string — the SAME validator every
+    // write path (Memory/WorkspaceState/OrgEvent) gates `entities` writes
+    // through (resources/entity-vocab.ts). Rejects anything not drawn from the
+    // closed, documented type set / grammar — never a prefix/regex match, so
+    // this stays a plain indexed equality lookup, never a scan.
+    if (!isValidEntity(entity)) {
+        return badRequest("invalid_entity", `'${entity}' is not a well-formed vocabulary string (type:value, closed type set)`);
+    }
+    let days = DEFAULT_WINDOW_DAYS;
+    if (data?.days !== undefined && data?.days !== null) {
+        const n = Number(data.days);
+        if (!Number.isFinite(n) || !Number.isInteger(n) || n <= 0) {
+            return badRequest("invalid_days", "days must be a positive integer");
+        }
+        days = Math.min(n, MAX_WINDOW_DAYS);
+    }
+    const sinceIso = new Date(Date.now() - days * 24 * 3600_000).toISOString();
+    return { entity, days, sinceIso };
+}
+async function queryMemory(ctx, entity, auth) {
+    const conditions = [
+        { attribute: "entities", comparator: "equals", value: entity },
+        { attribute: "archived", comparator: "not_equal", value: true },
+    ];
+    // Same centralized scope every other cross-agent Memory read path uses
+    // (Memory.search()/SemanticSearch.ts/MemoryBootstrap.ts) — own records (any
+    // visibility) + any other agent's non-private record, org-open. Admin/
+    // internal callers are unfiltered, matching those same call sites.
+    if (auth.kind === "agent" && !auth.isAdmin) {
+        const scope = await resolveReadScope(auth.agentId);
+        conditions.unshift(scope.condition);
+    }
+    const query = {
+        conditions,
+        select: [
+            "id", "agentId", "content", "summary", "subject", "tags", "durability",
+            "visibility", "createdAt", "updatedAt", "entities", "_safetyFlags",
+        ],
+    };
+    const rows = withDetachedTxn(ctx, () => databases.flair.Memory.search(query));
+    const callerAgent = auth.kind === "agent" ? auth.agentId : undefined;
+    const hits = [];
+    for await (const r of rows) {
+        const isFlagged = Array.isArray(r._safetyFlags) && r._safetyFlags.length > 0;
+        const fromOther = callerAgent !== undefined && r.agentId !== callerAgent;
+        hits.push({
+            id: r.id,
+            agentId: r.agentId,
+            content: isFlagged ? wrapUntrusted(r.content, fromOther ? r.agentId : undefined) : r.content,
+            summary: r.summary ?? null,
+            subject: r.subject ?? null,
+            tags: Array.isArray(r.tags) ? r.tags : null,
+            durability: r.durability ?? null,
+            visibility: r.visibility ?? null,
+            createdAt: r.createdAt,
+            updatedAt: r.updatedAt ?? null,
+            entities: Array.isArray(r.entities) ? r.entities : null,
+        });
+    }
+    hits.sort((a, b) => (b.createdAt || "").localeCompare(a.createdAt || ""));
+    return hits.slice(0, MAX_RESULTS_PER_SOURCE);
+}
+async function queryRelationship(ctx, entity, auth) {
+    const entityCondition = {
+        operator: "or",
+        conditions: [
+            { attribute: "subject", comparator: "equals", value: entity },
+            { attribute: "object", comparator: "equals", value: entity },
+        ],
+    };
+    const conditions = [entityCondition];
+    // Mirror Relationship.ts's search(): non-admin agents are scoped to their
+    // own agentId; admin/internal calls are unfiltered. Never broader than what
+    // a direct POST /Relationship search from this same caller would return.
+    if (auth.kind === "agent" && !auth.isAdmin) {
+        conditions.unshift({ attribute: "agentId", comparator: "equals", value: auth.agentId });
+    }
+    const rows = withDetachedTxn(ctx, () => databases.flair.Relationship.search({ conditions }));
+    const hits = [];
+    for await (const r of rows) {
+        hits.push({
+            id: r.id,
+            agentId: r.agentId,
+            subject: r.subject,
+            predicate: r.predicate,
+            object: r.object,
+            confidence: typeof r.confidence === "number" ? r.confidence : null,
+            validFrom: r.validFrom ?? null,
+            validTo: r.validTo ?? null,
+            createdAt: r.createdAt,
+            updatedAt: r.updatedAt ?? null,
+        });
+    }
+    hits.sort((a, b) => (b.updatedAt || b.createdAt || "").localeCompare(a.updatedAt || a.createdAt || ""));
+    return hits.slice(0, MAX_RESULTS_PER_SOURCE);
+}
+async function queryWorkspaceState(ctx, entity, sinceIso) {
+    const conditions = [
+        { attribute: "entities", comparator: "equals", value: entity },
+        { attribute: "timestamp", comparator: "greater_than_equal", value: sinceIso },
+    ];
+    // INTERNAL server-side path (Sherlock Option 1, binding): the RAW generated
+    // table object, never the exported `WorkspaceState` resource class — that
+    // class's search() re-applies strict per-agent scoping keyed off THIS
+    // caller's own identity, which would just filter every teammate's row back
+    // out. See this file's module doc for the full rationale + why this is not
+    // a broadening of WorkspaceState's general (still per-agent, still 403)
+    // read model.
+    const query = {
+        conditions,
+        select: ["id", "agentId", "ref", "phase", "taskId", "summary", "filesChanged", "timestamp", "entities"],
+    };
+    const rows = withDetachedTxn(ctx, () => databases.flair.WorkspaceState.search(query));
+    const hits = [];
+    for await (const r of rows) {
+        hits.push({
+            id: r.id,
+            agentId: r.agentId,
+            ref: r.ref,
+            phase: r.phase ?? null,
+            taskId: r.taskId ?? null,
+            summary: r.summary ?? null,
+            filesChanged: Array.isArray(r.filesChanged) ? r.filesChanged : null,
+            timestamp: r.timestamp,
+            entities: Array.isArray(r.entities) ? r.entities : null,
+        });
+    }
+    hits.sort((a, b) => (b.timestamp || "").localeCompare(a.timestamp || ""));
+    return hits.slice(0, MAX_RESULTS_PER_SOURCE);
+}
+// Presence roster fetch (the synthetic delegation-context trick) now lives in
+// resources/presence-internal.ts, shared with MemoryBootstrap.ts's collision
+// surfacing (flair#681) — see that file's module doc for the full security
+// rationale (why this isn't a forgery, why a fresh signature re-verify isn't
+// possible). This file's own "Presence" doc section above still applies; it
+// just no longer duplicates the code.
+async function queryPresence(auth, entity) {
+    const roster = await getPresenceRoster(auth); // fail-open (empty) — never fail the whole attention query
+    // Bounded scan: Presence carries exactly one row per agent (org-wide agent
+    // count is small), so a free-text substring match here is the pushdown-free
+    // exception the K&S verdict explicitly blesses ("Presence is a bounded
+    // scan, one row/agent, tiny") — unlike the other four sources, currentTask
+    // is unstructured prose with no indexed entities field to push down on.
+    const hits = [];
+    for (const row of roster) {
+        if (typeof row?.currentTask !== "string" || row.currentTask.length === 0)
+            continue;
+        if (!row.currentTask.includes(entity))
+            continue;
+        hits.push({
+            agentId: row.id,
+            displayName: row.displayName,
+            activity: row.activity,
+            currentTask: row.currentTask,
+            presenceStatus: row.presenceStatus,
+            lastHeartbeatAt: row.lastHeartbeatAt,
+        });
+    }
+    hits.sort((a, b) => {
+        const av = typeof a.lastHeartbeatAt === "number" ? a.lastHeartbeatAt : 0;
+        const bv = typeof b.lastHeartbeatAt === "number" ? b.lastHeartbeatAt : 0;
+        return bv - av;
+    });
+    return hits.slice(0, MAX_RESULTS_PER_SOURCE);
+}
+async function queryOrgEvent(ctx, entity, sinceIso) {
+    const conditions = [
+        { attribute: "entities", comparator: "equals", value: entity },
+        { attribute: "createdAt", comparator: "greater_than_equal", value: sinceIso },
+    ];
+    const query = {
+        conditions,
+        select: ["id", "authorId", "kind", "scope", "summary", "detail", "targetIds", "createdAt", "expiresAt", "entities"],
+    };
+    const rows = withDetachedTxn(ctx, () => databases.flair.OrgEvent.search(query));
+    const now = Date.now();
+    const hits = [];
+    for await (const r of rows) {
+        // Skip expired events (mirrors OrgEventCatchup.ts's in-process expiry filter).
+        if (r.expiresAt && new Date(r.expiresAt).getTime() < now)
+            continue;
+        hits.push({
+            id: r.id,
+            authorId: r.authorId,
+            kind: r.kind,
+            scope: r.scope ?? null,
+            summary: r.summary,
+            detail: r.detail ?? null,
+            targetIds: Array.isArray(r.targetIds) ? r.targetIds : null,
+            createdAt: r.createdAt,
+            entities: Array.isArray(r.entities) ? r.entities : null,
+        });
+    }
+    hits.sort((a, b) => (b.createdAt || "").localeCompare(a.createdAt || ""));
+    return hits.slice(0, MAX_RESULTS_PER_SOURCE);
+}
+// ─── Resource ─────────────────────────────────────────────────────────────────
+export class AttentionQuery extends Resource {
+    // Self-authorize (allowVerified: any verified agent/admin/internal call;
+    // anonymous denied). Per-source scoping is applied inside post() — see the
+    // module doc above for each source's rule.
+    async allowCreate() {
+        return allowVerified(this.getContext?.());
+    }
+    async post(data) {
+        const ctx = this.getContext?.();
+        const auth = await resolveAgentAuth(ctx);
+        if (auth.kind === "anonymous")
+            return UNAUTH();
+        if (auth.kind === "agent") {
+            const rl = checkRateLimit(auth.agentId, "general");
+            if (!rl.allowed)
+                return rateLimitResponse(rl.retryAfterMs, "attention");
+        }
+        const parsed = parseQueryInput(data);
+        if (parsed instanceof Response)
+            return parsed;
+        const { entity, days, sinceIso } = parsed;
+        // Sequential, not Promise.all: each helper wraps its table read in
+        // withDetachedTxn (save/clear/call/restore ctx.transaction around a
+        // SYNCHRONOUS search() call — see table-helpers.ts's doc). Running five
+        // of these concurrently over the SAME shared `ctx` would risk one call's
+        // save/restore interleaving with another's in-flight generator iteration
+        // in ways Harper's transaction chaining isn't documented to tolerate.
+        // Every other multi-table resource in this codebase (Memory.ts,
+        // SemanticSearch.ts, MemoryBootstrap.ts) sequences its cross-table reads
+        // for the same reason — this query is an internal/coordination read, not
+        // a latency-critical hot path, so the small sequential cost is the safe
+        // trade.
+        const memory = await queryMemory(ctx, entity, auth);
+        const relationship = await queryRelationship(ctx, entity, auth);
+        const workspaceState = await queryWorkspaceState(ctx, entity, sinceIso);
+        const presence = await queryPresence(auth, entity);
+        const orgEvent = await queryOrgEvent(ctx, entity, sinceIso);
+        return {
+            entity,
+            windowDays: days,
+            since: sinceIso,
+            groups: { memory, relationship, workspaceState, presence, orgEvent },
+            counts: {
+                memory: memory.length,
+                relationship: relationship.length,
+                workspaceState: workspaceState.length,
+                presence: presence.length,
+                orgEvent: orgEvent.length,
+                total: memory.length + relationship.length + workspaceState.length + presence.length + orgEvent.length,
+            },
+        };
+    }
+}

package/dist/resources/Credential.js

@@ -1,5 +1,5 @@
 import { databases } from "@harperfast/harper";
-import { resolveAgentAuth } from "./agent-auth.js";
+import { resolveAgentAuth, allowVerified } from "./agent-auth.js";
 import { checkRateLimit, rateLimitResponse } from "./rate-limiter.js";
 /**
  * Credential resource — authentication surfaces for Principals.
@@ -13,6 +13,16 @@ import { checkRateLimit, rateLimitResponse } from "./rate-limiter.js";
  * are never returned in responses).
  */
 export class Credential extends databases.flair.Credential {
+    /**
+     * Self-authorize (mirrors Soul.ts/Relationship.ts/WorkspaceState.ts). Harper
+     * routes some request shapes (e.g. collection-describe `GET /Credential`)
+     * OUTSIDE get()/search() entirely, so those in-method checks alone don't
+     * cover every path — Credential was the one sibling in this sensitive class
+     * missing this gate (#556/#557 swept the others). Deny anonymous/unverified
+     * here; get()/search() below still enforce per-agent ownership scoping on
+     * top of this for the paths they do see.
+     */
+    allowRead() { return allowVerified(this.getContext?.()); }
     async search(query) {
         const auth = await resolveAgentAuth(this.getContext?.());
         // Anonymous HTTP must NOT read credentials. (Previously `!authAgent` was

package/dist/resources/Federation.js

@@ -1,6 +1,7 @@
 import { Resource, databases, server } from "@harperfast/harper";
 import { randomBytes } from "node:crypto";
 import nacl from "tweetnacl";
+import { allowAdmin } from "./agent-auth.js";
 import { canonicalize, signBody, verifyBodySignature, signBodyFresh, verifyBodySignatureFresh, generateNonce, } from "./federation-crypto.js";
 import { initFederationCleanup } from "./federation-cleanup.js";
 import { createPersistentNonceStore, initNonceStoreCleanup } from "./federation-nonce-store.js";
@@ -61,8 +62,21 @@ function mergeRecord(local, remote) {
 /**
  * GET /FederationInstance — return this instance's identity.
  * Used by peers during pairing and by the admin UI.
+ *
+ * allowRead()=allowAdmin (defense-in-depth, authorizeLocal-escalation-class
+ * follow-up to #601/#604/#609/#612 — flair#614's backstop found this one had
+ * NO allow* at all, so Harper's own default — `user?.role.permission.
+ * super_user`, satisfiable only by a genuine admin OR authorizeLocal's forged
+ * loopback super_user — was silently standing in). Same idiom as
+ * AdminInstance.ts/AdminDashboard.ts: this is an admin-view endpoint (peers
+ * never call it during pairing — FederationPair.post() reads the Instance
+ * table directly server-side to hand a peer our identity; this HTTP GET is
+ * CLI tooling only).
  */
 export class FederationInstance extends Resource {
+    async allowRead() {
+        return allowAdmin(this.getContext?.());
+    }
     async get() {
         // Find or create instance identity
         let instance = null;
@@ -452,8 +466,17 @@ export class FederationSync extends Resource {
 }
 /**
  * GET /FederationPeers — list known peers (admin view).
+ *
+ * allowRead()=allowAdmin (defense-in-depth, authorizeLocal-escalation-class
+ * follow-up to #601/#604/#609/#612 — flair#614's backstop found this one had
+ * NO allow* at all). The docstring already called this "(admin view)" — this
+ * closes the gap between the documented/intended access model and what was
+ * actually enforced (nothing).
  */
 export class FederationPeers extends Resource {
+    async allowRead() {
+        return allowAdmin(this.getContext?.());
+    }
     async get() {
         const peers = [];
         try {

package/dist/resources/MCPClientMetadata.js

@@ -0,0 +1,88 @@
+import { Resource, databases } from "@harperfast/harper";
+import { mcpIssuer } from "./mcp-oauth-flag.js";
+import { agentPublicKeyToJwk, buildCimdDocument } from "./mcp-client-metadata-fields.js";
+/**
+ * MCPClientMetadata — serves a Client ID Metadata Document (CIMD) for a
+ * Flair agent at `GET /MCPClientMetadata/{agentId}`.
+ *
+ * This is the "publish" half of RFC 7523 private_key_jwt / client_credentials
+ * agent-auth (see docs/notes/mcp-agent-auth-consumer.md and
+ * HarperFast/oauth#159, whose full chain is now shipped in the published
+ * @harperfast/oauth@2.2.0: assertion verification #160/PR #165, CIMD-first
+ * client resolution #161/#167, token-endpoint grant + issuance rate
+ * limiting #162/#163 via PRs #170/#171). An authorization server that
+ * treats an agent's `client_id` as this URL fetches this document to learn
+ * the agent's JWKS (its EXISTING Ed25519 identity key) instead of doing a
+ * DCR registration — no registration state to replicate across Fabric
+ * nodes, matching Flair's stateless posture.
+ *
+ * Public, unauthenticated — mirrors AgentCard.ts. CIMD documents are meant
+ * to be fetched by an AS with no prior trust relationship (same posture as
+ * an A2A agent card / OIDC client metadata); this document exposes ONLY the
+ * agent's already-public identity key (the same value a verified caller
+ * already reads via `GET /Agent/{id}`), never anything secret.
+ *
+ * The document served here is proven against the REAL published plugin:
+ * test/unit/mcp-client-credentials-live-package.test.ts feeds it through
+ * 2.2.0's actual `resolveCimdClient` fetch+validate pipeline, and
+ * test/integration/mcp-client-credentials-e2e.test.ts serves it from a live
+ * spawned Harper. Note the plugin's CIMD fetch enforces an UNCONDITIONAL
+ * SSRF gate (https only, no private/loopback/link-local DNS answers, no
+ * override knob) — so an AS can only ever consume this document when it is
+ * served from a genuinely public HTTPS host. See the doc note's
+ * "SSRF/loopback boundary" section.
+ *
+ * Deployment coordination: the AS's `clientIdMetadataDocuments.allowedHosts`
+ * config MUST include this route's host (derived from `FLAIR_MCP_ISSUER` /
+ * `FLAIR_PUBLIC_URL`, same env vars as `mcpIssuer()` below) — merely being
+ * reachable is not enough; the allowlist gate is AS-side config and
+ * fail-closed. See docs/notes/mcp-agent-auth-consumer.md.
+ */
+export class MCPClientMetadata extends Resource {
+    allowRead() {
+        return true;
+    }
+    async get(pathInfo) {
+        const agentId = (typeof pathInfo === "string" ? pathInfo : null) ??
+            this.getId?.() ??
+            null;
+        if (!agentId) {
+            return new Response(JSON.stringify({ error: "agentId required in path: GET /MCPClientMetadata/{agentId}" }), { status: 400, headers: { "Content-Type": "application/json" } });
+        }
+        const issuer = mcpIssuer();
+        if (!issuer) {
+            // Fail closed rather than guess a client_id URL — CIMD requires the
+            // document's client_id to equal the URL it was fetched from, byte for
+            // byte, so a floating/unpinned origin would produce a document that
+            // never validates.
+            return new Response(JSON.stringify({
+                error: "mcp_issuer_not_configured",
+                message: "FLAIR_MCP_ISSUER (or FLAIR_PUBLIC_URL) must be set to publish a stable client_id URL.",
+            }), { status: 501, headers: { "Content-Type": "application/json" } });
+        }
+        const agent = await databases.flair.Agent.get(agentId).catch(() => null);
+        if (!agent?.publicKey) {
+            return new Response(JSON.stringify({ error: "agent_not_found_or_no_key", agentId }), {
+                status: 404,
+                headers: { "Content-Type": "application/json" },
+            });
+        }
+        let jwk;
+        try {
+            jwk = agentPublicKeyToJwk(String(agent.publicKey), agentId);
+        }
+        catch (err) {
+            return new Response(JSON.stringify({ error: "invalid_agent_key", message: err?.message ?? String(err) }), { status: 500, headers: { "Content-Type": "application/json" } });
+        }
+        const clientId = `${issuer.replace(/\/+$/, "")}/MCPClientMetadata/${agentId}`;
+        const doc = buildCimdDocument({
+            clientId,
+            clientName: String(agent.name ?? agent.displayName ?? agentId),
+            jwk,
+        });
+        return new Response(JSON.stringify(doc), {
+            status: 200,
+            headers: { "Content-Type": "application/json" },
+        });
+    }
+}