@tpsdev-ai/flair 0.20.1 → 0.22.0

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" },
+        });
+    }
+}

package/dist/resources/Memory.js

@@ -1,11 +1,14 @@
 import { databases } from "@harperfast/harper";
 import { patchRecord, withDetachedTxn } from "./table-helpers.js";
 import { isAdmin, resolveAgentAuth, allowVerified } from "./agent-auth.js";
+import { localInstanceId } from "./instance-identity.js";
 import { getEmbedding, getModelId } from "./embeddings-provider.js";
 import { scanFields, isStrictMode } from "./content-safety.js";
+import { invalidEntitiesResponse } from "./entity-vocab.js";
 import { checkRateLimit, rateLimitResponse } from "./rate-limiter.js";
 import { resolveReadScope } from "./memory-read-scope.js";
 import { DEDUP_COSINE_THRESHOLD_DEFAULT, DEDUP_LEXICAL_THRESHOLD_DEFAULT, DEDUP_MIN_CONTENT_LENGTH, computeMatchConfidence, cosineSimilarity, isConservativeMatch, } from "./dedup.js";
+import { buildProvenance } from "./provenance.js";
 const FORBIDDEN = (msg) => new Response(JSON.stringify({ error: msg }), { status: 403, headers: { "Content-Type": "application/json" } });
 const UNAUTH = () => new Response(JSON.stringify({ error: "authentication required" }), { status: 401, headers: { "Content-Type": "application/json" } });
 const NOT_FOUND = () => new Response(JSON.stringify({ error: "not found" }), { status: 404, headers: { "Content-Type": "application/json" } });
@@ -15,7 +18,7 @@ const NOT_FOUND = () => new Response(JSON.stringify({ error: "not found" }), { s
  * live in ./memory-read-scope.ts — the ONE centralized helper every
  * cross-agent Memory read path (search()/get() here, SemanticSearch.ts,
  * MemoryBootstrap.ts, auth-middleware.ts's by-id guard) resolves its scope
- * through, so the scoping rule cannot drift per-path again (ops-nzxa: a
+ * through, so the scoping rule cannot drift per-path again (a
  * SemanticSearch inline `visibility === "office"` OR-clause leaked office
  * memories to any authenticated agent because the rule had scattered). See
  * that module's doc for the migration invariant (no-visibility-field reads
@@ -86,7 +89,7 @@ async function findConservativeDedupMatch(ctx, agentId, contentText, embedding,
         }
         if (!top)
             return null;
-        // ─── ops-ume4: Harper's cosine-sort query omits $distance for a SINGLETON
+        // ─── Harper's cosine-sort query omits $distance for a SINGLETON
         // result set ─────────────────────────────────────────────────────────────
         // Initial working theory was a per-agentId HNSW "cold-start" (first-ever
         // query cold, second query warm) and the initially-recommended fix was a
@@ -133,7 +136,7 @@ async function findConservativeDedupMatch(ctx, agentId, contentText, embedding,
             cosine = 1 - top.$distance;
         }
         else {
-            console.error("Memory.findConservativeDedupMatch: $distance undefined on a singleton cosine result (ops-ume4) — " +
+            console.error("Memory.findConservativeDedupMatch: $distance undefined on a singleton cosine result — " +
                 "falling back to a manual cosine computation from the candidate's stored embedding", { agentId, candidateId: top.id });
             const fullCandidate = await withDetachedTxn(ctx, () => databases.flair.Memory.get(top.id));
             const candidateEmbedding = Array.isArray(fullCandidate?.embedding) ? fullCandidate.embedding : [];
@@ -170,10 +173,29 @@ async function runDedupGate(ctx, content) {
     if (typeof content.content !== "string" || content.content.length < DEDUP_MIN_CONTENT_LENGTH) {
         return null;
     }
+    // flair#504 Phase 2: 'document' — this embedding IS the stored vector (the
+    // "generate embedding if missing" step in post()/put() below reuses
+    // whatever this computes), so it MUST use the same inputType as every
+    // other document-write site or dedup's cosine compare would cross prefixed
+    // and unprefixed spaces. All three Memory doc sites (here, post(), put())
+    // move together in one commit for exactly that reason — see
+    // embeddings-provider.ts's file header for why the VALUE must be the
+    // literal 'document', never the prefix string.
+    //
+    // Dedup-during-transition transient (documented per Kern's review, not a
+    // bug to fix here): mid stage-2 re-embed, a NEW write embeds 'document'
+    // (prefixed) but may compare against an OLDER stored vector that hasn't
+    // been re-embedded yet (unprefixed) — cross-space cosine, so dedup can
+    // miss a near-duplicate during that window. Bounded (the re-embed pass is
+    // batched and finishes in minutes), self-healing once the pass completes,
+    // and a missed dedup is a duplicate row, not data loss — quality, not
+    // correctness. Stage 1 (this PR) doesn't trigger this at all: no re-embed
+    // runs, so there's no mixed-space window until stage 2's separate,
+    // deliberate ops step.
     let embedding = Array.isArray(content.embedding) ? content.embedding : null;
     if (!embedding) {
         try {
-            embedding = await getEmbedding(content.content);
+            embedding = await getEmbedding(content.content, "document");
         }
         catch {
             embedding = null;
@@ -209,7 +231,7 @@ function buildWriteResponse(content, result, dedupMatch) {
  * detachment discipline as findConservativeDedupMatch (each discrete Harper
  * call individually wrapped — see withDetachedTxn's doc for why a single
  * wrap around a multi-await async function would not protect the later
- * call). Does NOT swallow failures (ops-a4t5 fix) — throws so the caller can
+ * call). Does NOT swallow failures — throws so the caller can
  * log it. Never called before the new record is already written.
  */
 async function closeSupersededRecord(ctx, oldId, patch) {
@@ -273,7 +295,7 @@ async function validateAndAuthorizeSupersedes(content, auth) {
 }
 /**
  * Close the superseded record — called AFTER the new record has already been
- * written (write-new-BEFORE-close-old, ops-a4t5 fix). Safe failure state is
+ * written (write-new-BEFORE-close-old). Safe failure state is
  * two active records (recoverable), never a tombstoned-old-with-lost-new.
  * Failure is logged (observable), never silently swallowed. No-op if
  * `content.supersedes` is not set.
@@ -293,11 +315,11 @@ async function closeSupersededIfNeeded(ctx, content, methodLabel) {
         // `err` arg) would let an id containing %s/%o consume/hide the real error
         // (semgrep unsafe-formatstring). Keep all dynamic values in the data object.
         console.error("Memory.closeSuperseded: failed to close superseded record after writing new record " +
-            "(ops-a4t5 — observable, not silent; new record is safely written, old record remains active until retried)", { method: methodLabel, supersededId: content.supersedes, newRecordId: content.id, err });
+            "(observable, not silent; new record is safely written, old record remains active until retried)", { method: methodLabel, supersededId: content.supersedes, newRecordId: content.id, err });
     }
 }
 /**
- * ─── Durability-keyed default visibility (ops-2dm3 Layer 1, part A) ─────────
+ * ─── Durability-keyed default visibility (Layer 1, part A) ─────────────────
  *
  * Writer intent: an explicit `visibility` on the write ALWAYS overrides this
  * (callers check `content.visibility == null` before calling this). When
@@ -310,6 +332,51 @@ async function closeSupersededIfNeeded(ctx, content, methodLabel) {
 function defaultVisibilityForDurability(durability) {
     return durability === "permanent" || durability === "persistent" ? "shared" : "private";
 }
+/**
+ * ─── Write-time provenance stamp (memory-provenance slice 1) ────────────────
+ *
+ * `buildProvenance` itself now lives in ./provenance.ts (imported above) —
+ * extracted so resources/Relationship.ts's write path can reuse the EXACT
+ * same `{v, verified, claimed?}` shape (the relationship-write-path spec's
+ * "reuse buildProvenance as-is" contract) instead of a hand-copied format
+ * that could drift. See that module for the full field-by-field rationale
+ * (verified.agentId from the auth verdict never the body, verified.timestamp
+ * = the server-computed createdAt, optional unverified claimed.model
+ * passthrough). Deliberately NOT implemented in this slice: a
+ * context-fingerprint field — bootstrap doesn't return the IDs a fingerprint
+ * would need, so it requires client cooperation that's out of scope here.
+ */
+/**
+ * ─── Write-time originatorInstanceId stamp (federation-edge-hardening slice 1) ──
+ *
+ * Stamps this instance's own federation identity (resources/instance-
+ * identity.ts's localInstanceId(), cached — never a DB read per write) onto
+ * every LOCAL write. Deliberately a no-op when `content.originatorInstanceId`
+ * already carries a non-null value: this is the anti-clobber rule that keeps
+ * a federation-synced record's true origin intact.
+ *
+ * Why this can never clobber a synced record: FederationSync.post()
+ * (resources/Federation.ts) merges incoming records via the RAW table object
+ * (`(databases as any).flair.Memory.put(mergedData)`) — Harper's static
+ * table-level put, not this Resource subclass's instance put() below. The
+ * merge path never runs this function at all, so a record arriving from
+ * instance B keeps whatever `originatorInstanceId` it already carried in
+ * `mergedData` (that instance's own write-time stamp, carried through in the
+ * synced row) with no risk of this instance overwriting it with its own id.
+ * The `content.originatorInstanceId == null` guard below is still applied —
+ * defense-in-depth for any future path that might route a synced payload
+ * through this class's post()/put() — so the invariant holds even if that
+ * assumption ever changes.
+ *
+ * `localInstanceId()` resolves to null on an instance that has never been
+ * federation-bootstrapped (no Instance row yet) — the field is nullable by
+ * design, so this stamps null rather than inventing an id.
+ */
+async function stampOriginatorInstanceId(content) {
+    if (content.originatorInstanceId == null) {
+        content.originatorInstanceId = await localInstanceId();
+    }
+}
 export class Memory extends databases.flair.Memory {
     /**
      * Self-authorize now that the global gate is non-rejecting. Closes the P0
@@ -360,8 +427,8 @@ export class Memory extends databases.flair.Memory {
             return super.get(target);
         }
         // Non-admin agent: only its own memories (any visibility), or a granted
-        // owner's SHARED memories — never that owner's private ones (ops-2dm3
-        // Layer 1 private-exclusion). Centralized in resolveReadScope() so this
+        // owner's SHARED memories — never that owner's private ones (Layer 1
+        // private-exclusion). Centralized in resolveReadScope() so this
         // and search() below cannot drift.
         const record = await super.get(target);
         if (!record)
@@ -397,7 +464,7 @@ export class Memory extends databases.flair.Memory {
             return super.search(query);
         }
         // Non-admin agent: scope to own (any visibility) + granted owners' SHARED
-        // memories only (ops-2dm3 Layer 1 private-exclusion). Centralized in
+        // memories only (Layer 1 private-exclusion). Centralized in
         // resolveReadScope() so get() above and search() here cannot drift.
         const authAgent = auth.agentId;
         const scope = await resolveReadScope(authAgent);
@@ -450,7 +517,7 @@ export class Memory extends databases.flair.Memory {
         content.createdAt = new Date().toISOString();
         content.updatedAt = content.createdAt;
         content.archived = content.archived ?? false;
-        // ─── Default visibility (durability-keyed) — ops-2dm3 Layer 1, part A ────
+        // ─── Default visibility (durability-keyed) — Layer 1, part A ────────────
         // post() only ever creates a NEW record — patchRecord/supersede-close/
         // retrievalCount bumps all route through put() instead (see put()'s
         // pre-existing-record guard below), so there is no "don't overwrite an
@@ -483,12 +550,19 @@ export class Memory extends databases.flair.Memory {
         if (!content.validFrom) {
             content.validFrom = content.createdAt;
         }
+        // attention-plane vocabulary gate (flair#675): `entities`, if present,
+        // must be well-formed vocabulary strings — see resources/entity-vocab.ts.
+        // Field is additive/optional (v1 schema-only; no auto-derivation here —
+        // that producer is a follow-up); absent entities is not an error.
+        const entitiesError = invalidEntitiesResponse(content.entities);
+        if (entitiesError)
+            return entitiesError;
         if (content.durability === "ephemeral" && !content.expiresAt) {
             const ttlHours = Number(process.env.FLAIR_EPHEMERAL_TTL_HOURS || 24);
             content.expiresAt = new Date(Date.now() + ttlHours * 3600_000).toISOString();
         }
         // Content safety scan — covers content + summary (defense-in-depth for
-        // agent-set summaries, ops-i2jb).
+        // agent-set summaries).
         if (content.content || content.summary) {
             const safety = scanFields(content, ["content", "summary"]);
             if (!safety.safe) {
@@ -517,17 +591,27 @@ export class Memory extends databases.flair.Memory {
             delete content.lexicalThreshold;
         }
         // Generate embedding from content text (no-op if the dedup gate above
-        // already computed one for this content).
+        // already computed one for this content). flair#504 Phase 2: 'document'
+        // — see runDedupGate's comment above for why all three Memory doc sites
+        // must move together.
         if (content.content && !content.embedding) {
-            const vec = await getEmbedding(content.content);
+            const vec = await getEmbedding(content.content, "document");
             if (vec) {
                 content.embedding = vec;
                 content.embeddingModel = getModelId();
             }
         }
+        // Write-time provenance stamp (memory-provenance slice 1) — see
+        // buildProvenance's doc above. Stamped last, right before persist, so it
+        // reflects the final resolved `content.createdAt`.
+        content.provenance = buildProvenance(auth, content.createdAt, content);
+        // Write-time originatorInstanceId stamp (federation-edge-hardening slice
+        // 1) — see stampOriginatorInstanceId's doc above. No-op if already set
+        // (never fires for a genuine local write — no client sets this field).
+        await stampOriginatorInstanceId(content);
         // ── Write the new record FIRST ──────────────────────────────────────────
         const result = await super.post(content);
-        // ── THEN close the superseded record (ops-a4t5 fix) ─────────────────────
+        // ── THEN close the superseded record ────────────────────────────────────
         // Write-new-BEFORE-close-old: the previous order (close-old via a fire-
         // and-forget `.catch(()=>{})` BEFORE the new write) could tombstone the
         // old record and then lose the new one if the write failed afterward.
@@ -582,7 +666,7 @@ export class Memory extends databases.flair.Memory {
         // visibility stamped) or an update/patch (dedup-bypassed, visibility left
         // untouched). See the dedup-gate block further down for why an existing
         // id skips the gate; the SAME "does a record already exist" check gates
-        // the visibility default (ops-2dm3 Layer 1 part A): patchRecord/supersede-
+        // the visibility default (Layer 1 part A): patchRecord/supersede-
         // close/retrievalCount bumps all route through put() with a MERGED
         // `{...existing, ...patch}` payload, and must never have their stored
         // visibility overwritten by a default recomputed from that merged content
@@ -590,7 +674,7 @@ export class Memory extends databases.flair.Memory {
         const preExisting = content.id
             ? await databases.flair.Memory.get(content.id).catch(() => null)
             : null;
-        // ─── Default visibility (durability-keyed) — ops-2dm3 Layer 1, part A ────
+        // ─── Default visibility (durability-keyed) — Layer 1, part A ────────────
         // Explicit visibility on the write ALWAYS overrides; only stamp the
         // default when the caller left it unset AND this is a fresh record.
         // permanent|persistent → shared; standard|ephemeral|absent → private.
@@ -607,7 +691,11 @@ export class Memory extends databases.flair.Memory {
         if (content.supersedes && !content.validFrom) {
             content.validFrom = content.createdAt;
         }
-        // Content safety scan on updated content + summary (ops-i2jb).
+        // attention-plane vocabulary gate (flair#675) — see post()'s comment above.
+        const entitiesError = invalidEntitiesResponse(content.entities);
+        if (entitiesError)
+            return entitiesError;
+        // Content safety scan on updated content + summary.
         if (content.content || content.summary) {
             const safety = scanFields(content, ["content", "summary"]);
             if (!safety.safe) {
@@ -653,9 +741,12 @@ export class Memory extends databases.flair.Memory {
             dedupMatch = await runDedupGate(ctx, content);
         }
         // Re-generate embedding if content changed (no-op if the dedup gate above
-        // already computed one for this content).
+        // already computed one for this content). flair#504 Phase 2: 'document'
+        // — this is also the regen branch `flair reembed` triggers (clears
+        // embedding/embeddingModel then hits this put()), so it's what actually
+        // re-embeds a stale row WITH the prefix once stage 2 runs.
         if (content.content && !content.embedding) {
-            const vec = await getEmbedding(content.content);
+            const vec = await getEmbedding(content.content, "document");
             if (vec) {
                 content.embedding = vec;
                 content.embeddingModel = getModelId();
@@ -674,9 +765,23 @@ export class Memory extends databases.flair.Memory {
         if (content.promotionStatus === "approved") {
             content.durability = "permanent";
         }
+        // Write-time provenance stamp (memory-provenance slice 1) — see
+        // buildProvenance's doc above post(). Applies to every put() (fresh
+        // create AND update/patch) — never gated on preExisting, so an update
+        // always gets a freshly-stamped provenance reflecting the CURRENT
+        // authenticated actor performing this write.
+        content.provenance = buildProvenance(auth, content.createdAt, content);
+        // Write-time originatorInstanceId stamp (federation-edge-hardening slice
+        // 1) — see stampOriginatorInstanceId's doc above post(). No-op if
+        // already set: an update/patch of an existing local record carries its
+        // own already-stamped originatorInstanceId forward unchanged (the
+        // `{...existing, ...patch}` merge pattern every put() caller uses), and a
+        // federation-synced record never reaches this method at all (see that
+        // function's doc for why the merge path can't clobber it here either).
+        await stampOriginatorInstanceId(content);
         // ── Write the new/updated record FIRST ──────────────────────────────────
         const result = await super.put(content);
-        // ── THEN close the superseded record (ops-a4t5 fix; see post()) ────────
+        // ── THEN close the superseded record (see post()) ───────────────────────
         await closeSupersededIfNeeded(ctx, content, "put");
         return buildWriteResponse(content, result, dedupMatch);
     }