@tpsdev-ai/flair 0.20.1 → 0.22.0

package/dist/resources/federation-nonce-store.js

@@ -0,0 +1,195 @@
+/**
+ * federation-nonce-store.ts — persistent backing for the federation
+ * anti-replay NonceStore (federation-edge-hardening slice 4).
+ *
+ * The gap: `federationNonceStore` in Federation.ts was a bare in-memory Map
+ * (`createNonceStore()` in federation-crypto.ts). On process restart it's
+ * wiped, so a signed federation request captured within its ±30s freshness
+ * window (verifyBodySignatureFresh) could be replayed once, post-restart.
+ * This module closes that window by backing the SAME `NonceStore` interface
+ * with the `Nonce` Harper table, while keeping every method synchronous —
+ * `verifyBodySignatureFresh` and its 2 call sites in Federation.ts are
+ * UNCHANGED (they still call `.has()` / `.set()` / `.evict()` with no
+ * `await`), so the entire existing federation-crypto-replay test suite
+ * (all synchronous assertions) keeps working unmodified.
+ *
+ * How the sync interface stays sync against an inherently-async DB API:
+ *   - `has()` / `evict()` read/mutate an in-memory Map (via the existing
+ *     `createNonceStore()`), exactly as before — no DB round trip.
+ *   - `set()` updates that same in-memory Map synchronously (so replay
+ *     detection within THIS process's lifetime is unchanged), and fires an
+ *     async `Nonce.put()` in the background (not awaited) to persist the
+ *     nonce for the NEXT restart. A failed/slow persist never blocks or
+ *     fails request handling — see the perf/durability tradeoff note below.
+ *   - `hydrate()` is the new piece: an explicit async step that loads
+ *     not-yet-expired rows from the `Nonce` table into the in-memory Map.
+ *     Call it once, on startup, BEFORE the store starts guarding live
+ *     traffic — that's what makes a nonce recorded by the PREVIOUS process
+ *     visible to a FRESH store instance after a restart (the whole point).
+ *
+ * Known tradeoff (flagged, not fixed here — would require making NonceStore
+ * async, which ripples into ~40 synchronous call sites across
+ * federation-crypto-replay.test.ts + federation-sync-e2e.test.ts):
+ * `set()`'s persistence is fire-and-forget. A crash in the narrow gap
+ * between "response sent" and "async put() resolved" can still lose that
+ * one nonce — narrowing the replay window to that gap, not eliminating it
+ * outright. Defense-in-depth: the ±30s freshness check + signature
+ * verification are still the primary guards; this closes the common case
+ * (graceful restart / redeploy), not the crash-mid-request edge case.
+ */
+import { createNonceStore } from "./federation-crypto.js";
+/** 2x the standard 30s freshness window — matches the in-memory `evict()` cutoff already used by verifyBodySignatureFresh. */
+export const DEFAULT_RETENTION_MS = 60_000;
+async function resolveDb(opts, cache) {
+    if (opts.db)
+        return opts.db;
+    if (!cache.db) {
+        cache.db = import("@harperfast/harper").then((h) => h.databases);
+    }
+    return cache.db;
+}
+/**
+ * Create a `NonceStore` backed by the `Nonce` Harper table.
+ *
+ * Wraps the existing in-memory `createNonceStore()` (unchanged behavior for
+ * `has()`/`set()`/`evict()` within this process) and adds:
+ *   - background persistence of newly-set nonces (`set()`)
+ *   - an explicit `hydrate()` to reload previously-persisted nonces (used
+ *     at startup, and by tests simulating a restart with a fresh instance)
+ */
+export function createPersistentNonceStore(opts = {}) {
+    const memory = createNonceStore();
+    const dbCache = {};
+    return {
+        has(key) {
+            return memory.has(key);
+        },
+        evict(olderThan) {
+            memory.evict(olderThan);
+        },
+        set(key, value) {
+            memory.set(key, value);
+            // Fire-and-forget persistence — see module header for the tradeoff.
+            void (async () => {
+                try {
+                    const db = await resolveDb(opts, dbCache);
+                    await db.flair.Nonce.put({ id: key, seenAt: value });
+                }
+                catch (err) {
+                    console.error("[federation-nonce-store] failed to persist nonce (in-memory record already made — this process's replay guard is unaffected):", err?.message ?? err);
+                }
+            })();
+        },
+        async hydrate(hydrateOpts) {
+            const retentionMs = hydrateOpts?.retentionMs ?? DEFAULT_RETENTION_MS;
+            const now = hydrateOpts?.now ?? Date.now();
+            const cutoff = now - retentionMs;
+            try {
+                const db = await resolveDb(opts, dbCache);
+                for await (const row of db.flair.Nonce.search()) {
+                    if (row?.id != null && typeof row.seenAt === "number" && row.seenAt >= cutoff) {
+                        memory.set(String(row.id), row.seenAt);
+                    }
+                }
+            }
+            catch (err) {
+                console.error("[federation-nonce-store] failed to hydrate from Nonce table (starting with an empty replay guard):", err?.message ?? err);
+            }
+        },
+    };
+}
+// ─── Eviction sweep — periodic Nonce table hygiene ─────────────────────────
+//
+// Mirrors federation-cleanup.ts's 5-min setInterval hub-pattern. Decoupled
+// from the in-memory `evict()` above (which runs per-request and only trims
+// the local Map): this sweep deletes rows from the `Nonce` TABLE itself so
+// it doesn't grow unbounded across restarts. No native TTL in this repo —
+// same app-managed-sweep idiom as PairingToken cleanup.
+//
+// Runs on every instance (hub AND spoke) — unlike PairingToken cleanup
+// (hub-only, since only hubs issue pairing tokens), both FederationPair and
+// FederationSync can be the RECEIVING side of a signed request on either
+// role, so both roles accumulate rows in the Nonce table and both need the
+// sweep.
+const NONCE_CLEANUP_INTERVAL_MS = 300_000; // 5 minutes
+let nonceCleanupTimer = null;
+/**
+ * Core sweep logic — exposed for unit testing. Deletes `Nonce` rows with
+ * `seenAt` older than `retentionMs` (default: 2x the 30s freshness window).
+ */
+export async function runNonceCleanupTick(opts = {}) {
+    let db;
+    if (opts.db) {
+        db = opts.db;
+    }
+    else {
+        const harper = await import("@harperfast/harper");
+        db = harper.databases;
+    }
+    const retentionMs = opts.retentionMs ?? DEFAULT_RETENTION_MS;
+    const now = opts.now ?? Date.now();
+    const cutoff = now - retentionMs;
+    const toDelete = [];
+    let scanned = 0;
+    try {
+        for await (const row of db.flair.Nonce.search()) {
+            scanned++;
+            if (typeof row?.seenAt === "number" && row.seenAt < cutoff) {
+                toDelete.push(row.id);
+            }
+        }
+    }
+    catch (err) {
+        console.error("[federation-nonce-store] failed to query Nonce records:", err?.message ?? err);
+        return { deleted: 0, scanned: 0 };
+    }
+    let deleted = 0;
+    for (const id of toDelete) {
+        try {
+            await db.flair.Nonce.delete(id);
+            deleted++;
+        }
+        catch (err) {
+            console.error("[federation-nonce-store] failed to delete expired nonce:", err?.message ?? err);
+        }
+    }
+    return { deleted, scanned };
+}
+/**
+ * Initialise the periodic Nonce-table eviction sweep (5-min cadence).
+ *
+ * In test environments, callers pass a mock `db` via `opts` so this module
+ * never imports @harperfast/harper at the top level (mirrors
+ * federation-cleanup.ts's `initFederationCleanup`).
+ */
+export async function initNonceStoreCleanup(opts) {
+    const immediate = opts?.immediateTick ?? true;
+    let db;
+    if (opts?.db) {
+        db = opts.db;
+    }
+    else {
+        try {
+            const harper = await import("@harperfast/harper");
+            db = harper.databases;
+        }
+        catch (err) {
+            console.error("[federation-nonce-store] failed to load @harperfast/harper:", err?.message ?? err);
+            return;
+        }
+    }
+    const retentionMs = opts?.retentionMs ?? DEFAULT_RETENTION_MS;
+    console.log("[federation-nonce-store] starting nonce eviction sweep (5-min cadence)");
+    if (nonceCleanupTimer)
+        clearInterval(nonceCleanupTimer);
+    nonceCleanupTimer = setInterval(() => {
+        runNonceCleanupTick({ db, retentionMs }).catch((err) => {
+            console.error("[federation-nonce-store] cleanup tick error:", err?.message ?? err);
+        });
+    }, NONCE_CLEANUP_INTERVAL_MS);
+    if (immediate) {
+        runNonceCleanupTick({ db, retentionMs }).catch((err) => {
+            console.error("[federation-nonce-store] initial cleanup tick error:", err?.message ?? err);
+        });
+    }
+}

package/dist/resources/health.js

@@ -1,8 +1,11 @@
 import { Resource, databases } from "@harperfast/harper";
-import { promises as fsp } from "node:fs";
+import { promises as fsp, existsSync, readFileSync } from "node:fs";
 import { homedir, platform } from "node:os";
-import { join } from "node:path";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 import { getRerankStatus } from "./rerank-provider.js";
+import { allowVerified, resolveAgentAuth } from "./agent-auth.js";
+import { getMigrationStatusSnapshot } from "./migrations/status.js";
 const db = databases;
 const redactHome = (p) => {
     const home = homedir();
@@ -17,6 +20,35 @@ const exists = async (path) => {
         return false;
     }
 };
+/**
+ * Resolve the runtime package version from package.json (duplicated from
+ * admin-layout.ts / AdminInstance.ts — same "keep in sync" idiom as the
+ * federation-crypto helpers in src/cli.ts; see those two files' comments for
+ * why it's inlined rather than imported). `process.env.npm_package_version`
+ * is only populated inside `npm run`, so reading package.json relative to
+ * THIS running module is the only way to report the version of the code
+ * that's actually executing — which is exactly what `flair upgrade`'s
+ * post-restart verification (flair#635) needs: proof the NEW package is
+ * what's serving, not just what landed on disk before a restart.
+ */
+function resolveVersion() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const candidates = [
+            join(here, "..", "..", "package.json"),
+            join(here, "..", "package.json"),
+        ];
+        for (const p of candidates) {
+            if (existsSync(p)) {
+                const pkg = JSON.parse(readFileSync(p, "utf-8"));
+                if (pkg.version)
+                    return pkg.version;
+            }
+        }
+    }
+    catch { /* fall through */ }
+    return process.env.npm_package_version ?? "dev";
+}
 /**
  * Health endpoint — truly public, returns only { ok: true }.
  *
@@ -45,25 +77,57 @@ export class Health extends Resource {
         return true;
     }
     async get() {
-        return { ok: true };
+        // `version` (flair#695, the CLI↔server handshake — src/version-handshake.ts):
+        // exposed on the PUBLIC endpoint deliberately, so the check works even
+        // before an agent identity/key exists (fresh install, pre-`flair init`).
+        // Sherlock verdict: fine while locally bound; if /Health is ever fronted
+        // PUBLICLY over Fabric, the public surface must omit this field (the
+        // richer, auth-gated /HealthDetail already carried version pre-existing —
+        // this only adds it to the anonymous endpoint too).
+        return { ok: true, version: resolveVersion() };
     }
 }
 /**
  * Authenticated health detail — returns memory/agent/soul stats + process info.
  * Requires Ed25519 agent auth or admin basic auth.
  *
+ * allowRead()=allowVerified (authorizeLocal-escalation-class follow-up to
+ * #601/#604/#609/#612 — flair#614's backstop found this resource had NO
+ * allow* at all, despite this docstring's stated intent). 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 instead. Any verified agent may read — get() below still
+ * filters sensitive fields (peer/OAuth-client lists, absolute paths, full
+ * agent roster) down to admin-only.
+ *
  * Every optional-subsystem lookup is wrapped so a missing table or absent
  * schema downgrades to "not configured" rather than failing the whole call.
  */
 export class HealthDetail extends Resource {
+    async allowRead() {
+        return allowVerified(this.getContext?.());
+    }
     async get() {
         const stats = { ok: true };
         const nowMs = Date.now();
         const warnings = [];
         const ctx = this.getContext?.();
-        const request = ctx?.request ?? ctx;
-        const callerAgent = request?.tpsAgent;
-        const isAdmin = request?.tpsAgentIsAdmin === true || !callerAgent;
+        // #614 fix: resolve identity via the shared three-way verdict
+        // (internal/agent/anonymous — agent-auth.ts) instead of reading
+        // tpsAgent/tpsAgentIsAdmin off the raw request directly. The OLD
+        // computation was `request?.tpsAgentIsAdmin === true || !callerAgent` —
+        // the `|| !callerAgent` half meant an UNRESOLVED caller (no tpsAgent at
+        // all — i.e. anonymous) defaulted to isAdmin=TRUE, backwards from every
+        // other resource in this codebase and the opposite of fail-safe.
+        // allowRead() above already denies a genuine anonymous HTTP caller
+        // before get() ever runs; this fixes the internal computation to match
+        // (defense-in-depth, and correct semantics if get() is ever reached
+        // another way). Only a true "internal" verdict (no HTTP request at all —
+        // a programmatic/in-process call) or a verified admin agent is isAdmin;
+        // an unresolved/anonymous HTTP caller is never treated as admin.
+        const auth = await resolveAgentAuth(ctx);
+        const callerAgent = auth.kind === "agent" ? auth.agentId : undefined;
+        const isAdmin = auth.kind === "internal" || (auth.kind === "agent" && auth.isAdmin);
         stats.caller = { agentId: callerAgent ?? null, isAdmin };
         let memoriesList = [];
         // ── Memory stats ──
@@ -435,6 +499,29 @@ export class HealthDetail extends Resource {
         catch {
             stats.rem = null;
         }
+        // ── Migrations (flair#695: zero-touch boot-keyed auto-migration) ──
+        // `{ id, rowsDone, rowsRemaining, state }` per registered migration, per
+        // flair#695 §A. `cyclePhase: "pre-hash"` is the
+        // "pre-flight integrity check in progress" state the K&S verdict calls
+        // for; a halted migration surfaces here (with `reason`) AND as a
+        // warning below so it's visible without a separate lookup.
+        try {
+            const migrationsDataDir = process.env.HDB_ROOT ?? join(homedir(), ".flair", "data");
+            const snapshot = getMigrationStatusSnapshot(migrationsDataDir);
+            stats.migrations = {
+                cyclePhase: snapshot.cyclePhase,
+                lastCycleAt: snapshot.lastCycleAt ?? null,
+                migrations: snapshot.migrations,
+            };
+            for (const m of snapshot.migrations) {
+                if (m.state === "halted" || m.state === "failed") {
+                    warnings.push({ level: "warn", message: `migration '${m.id}' ${m.state}${m.reason ? `: ${m.reason}` : ""} — see \`flair doctor\`` });
+                }
+            }
+        }
+        catch {
+            stats.migrations = null;
+        }
         // ── Disk ──
         try {
             const dataDir = process.env.HDB_ROOT ?? join(homedir(), ".flair", "data");
@@ -535,6 +622,10 @@ export class HealthDetail extends Resource {
         // ── Warnings ──
         stats.warnings = warnings;
         // ── Process info ──
+        // version: the RUNNING process's own package.json — used by `flair
+        // upgrade`'s post-restart verification (flair#635) to prove the new
+        // code is actually serving, not just installed on disk.
+        stats.version = resolveVersion();
         stats.pid = process.pid;
         stats.uptimeSeconds = Math.floor(process.uptime());
         return stats;

package/dist/resources/instance-identity.js

@@ -0,0 +1,53 @@
+import { databases } from "@harperfast/harper";
+/**
+ * ─── Local instance identity (federation-edge-hardening slice 1) ────────────
+ *
+ * The write-time `originatorInstanceId` stamp (Memory.ts/Soul.ts/Agent.ts/
+ * Relationship.ts post()/put()) needs to know THIS instance's own federation
+ * identity — the same `id` FederationInstance.get() (resources/Federation.ts)
+ * finds-or-creates on first boot and persists in the `Instance` table
+ * (schemas/federation.graphql). Exactly one row is expected in a given
+ * instance's own Instance table — that row IS this instance; other instances
+ * it has paired with live in the separate `Peer` table, never here.
+ *
+ * Deliberately READ-ONLY: this module never creates an Instance row — that
+ * first-boot bootstrap (keypair generation + keystore write) stays
+ * FederationInstance.get()'s job (resources/Federation.ts). If no Instance
+ * row exists yet (a fresh, never-federated instance, or a unit-test
+ * environment with no Instance table at all), localInstanceId() resolves to
+ * null and callers stamp nothing — originatorInstanceId is nullable by
+ * design (schemas/memory.graphql), and a null tag reads as "pre-tag /
+ * local-origin by default" per the federation-edge-hardening design.
+ *
+ * Cached at module scope after the FIRST successful resolution — a write
+ * must not pay a DB lookup every call. An unresolved (null) result is NOT
+ * cached, since that state can legitimately change later (federation gets
+ * bootstrapped after this process already started serving writes) and the
+ * cost of re-checking only applies to instances that have never federated.
+ */
+let cachedInstanceId = null;
+export async function localInstanceId() {
+    if (cachedInstanceId)
+        return cachedInstanceId;
+    try {
+        for await (const row of databases.flair.Instance.search()) {
+            if (row?.id) {
+                cachedInstanceId = row.id;
+            }
+            break; // exactly one row expected — this instance's own identity
+        }
+    }
+    catch {
+        // Instance table not present (test env / not yet migrated) — no local id.
+    }
+    return cachedInstanceId;
+}
+/**
+ * Test-only: force re-resolution on the next localInstanceId() call. The
+ * module-level cache otherwise persists across test files that share the
+ * same `bun test` process (same collision class documented in
+ * memory-integrity.test.ts re: the Memory class singleton).
+ */
+export function _resetLocalInstanceIdCacheForTests() {
+    cachedInstanceId = null;
+}

package/dist/resources/mcp-client-metadata-fields.js

@@ -0,0 +1,112 @@
+/**
+ * Client ID Metadata Document (CIMD) field logic for Flair agent identities.
+ *
+ * Produces the JSON metadata document an OAuth authorization server fetches
+ * when a client_id is an HTTPS URL — draft-ietf-oauth-client-id-metadata-
+ * document-00, adopted by the MCP draft authorization spec IN PLACE OF DCR
+ * (no registration row to create or replicate across nodes; the served
+ * document IS the registration).
+ *
+ * Shape is pinned to HarperFast/oauth **issue #161** ("client_credentials
+ * (2/4): CIMD-first client resolution for private_key_jwt agents") — the
+ * FORMAL shape spec for this document, shipped in @harperfast/oauth@2.2.0
+ * via PR #170 (with #167's CIMD resolution layer). #161 requires:
+ *
+ *   - `grant_types: ["client_credentials"]`;
+ *     `token_endpoint_auth_method: "private_key_jwt"`.
+ *   - `jwks` = JWK Set of PUBLIC OKP/Ed25519 keys ONLY — reject any key
+ *     carrying a private `d`, reject empty sets, reject non-OKP/non-Ed25519
+ *     keys.
+ *   - client_credentials-only clients carry NEITHER `redirect_uris` NOR
+ *     `response_types` — #161 explicitly blesses this as a documented
+ *     deviation from the CIMD draft's general required-fields list (which
+ *     includes `redirect_uris` for interactive/DCR-style clients).
+ *   - `client_credentials` combined with `refresh_token` is rejected.
+ *   - Security gate (AS-side, enforced by the plugin, documented here for
+ *     deployment coordination): `clientIdMetadataDocuments.allowedHosts`
+ *     MUST be configured and this document's `client_id` host MUST be on
+ *     it — merely hosting a reachable document must never be sufficient to
+ *     mint tokens. Replaces the old DCR `initialAccessToken` gate.
+ *
+ * The AS-side machinery consuming this document (fetch/validate/cache —
+ * #167's CIMD resolution layer, extended by #170 for client_credentials +
+ * private_key_jwt) is SHIPPED in the published @harperfast/oauth@2.2.0.
+ * This module's output is proven against that real published code — not a
+ * mirror — in test/unit/mcp-client-credentials-live-package.test.ts, which
+ * drives 2.2.0's actual `resolveCimdClient` pipeline (via its exported
+ * `_setDnsLookup`/`_setFetch` test hooks) and confirms the document
+ * resolves and validates end-to-end, plus the fail-closed negatives (no
+ * `allowedHosts` configured → rejected; leaked private `d` in a JWK →
+ * rejected by the plugin even if our own build-time guard were bypassed).
+ *
+ * Kept free of any @harperfast/harper import (mirrors agentcard-fields.ts)
+ * so the document shape is unit-testable without spinning up Harper.
+ */
+/** The grant this agent's CIMD document targets — formalized by oauth#161, accepted by the published 2.2.0 validator. See module header. */
+export const CIMD_TARGET_GRANT_TYPES = ["client_credentials"];
+/** The auth method this agent's CIMD document targets — formalized by oauth#161, accepted by the published 2.2.0 validator. See module header. */
+export const CIMD_TARGET_AUTH_METHOD = "private_key_jwt";
+/** Build a Client ID Metadata Document for a headless Flair agent. */
+export function buildCimdDocument(params) {
+    const { clientId, clientName, jwk } = params;
+    if (!clientId)
+        throw new Error("clientId is required");
+    if (!clientName)
+        throw new Error("clientName is required");
+    if (!jwk || jwk.kty !== "OKP" || jwk.crv !== "Ed25519" || typeof jwk.x !== "string" || !jwk.x) {
+        throw new Error("jwk must be a public Ed25519 JWK ({kty:'OKP', crv:'Ed25519', x:'...'})");
+    }
+    // Belt-and-suspenders (oauth#161: "reject any key carrying private `d`").
+    // Ed25519Jwk's TS type has no `d` field, so a well-typed caller can't
+    // construct one — but this function's argument still crosses a runtime
+    // boundary (a JWK read from disk/network, or a caller using `as any`), so
+    // check for it explicitly rather than trust the type alone. A CIMD
+    // document is fetched by an unauthenticated AS over the public internet;
+    // there is no scenario where leaking `d` here is acceptable.
+    if (typeof jwk.d !== "undefined") {
+        throw new Error("jwk must be a PUBLIC key — refusing to build a CIMD document from a JWK carrying a private 'd' component");
+    }
+    return {
+        client_id: clientId,
+        client_name: clientName,
+        // Exactly one key, always non-empty and always OKP/Ed25519 — both are
+        // structurally guaranteed by the validation above (oauth#161 also
+        // requires rejecting an EMPTY jwks set and non-OKP/non-Ed25519 keys;
+        // this function's single-already-validated-jwk API makes both
+        // impossible to violate from here).
+        jwks: { keys: [jwk] },
+        // pending oauth#161 — rejected by today's open-draft #167 validator; see module header.
+        token_endpoint_auth_method: CIMD_TARGET_AUTH_METHOD,
+        grant_types: [...CIMD_TARGET_GRANT_TYPES],
+        // redirect_uris AND response_types are both deliberately omitted — #161
+        // blesses this explicitly for client_credentials-only CIMD clients (no
+        // redirect-based flow is ever possible for a headless agent). Neither
+        // field is declared on CimdDocument, so neither can slip back in via
+        // this object literal.
+    };
+}
+/**
+ * Normalize a Flair `Agent.publicKey` value into a JWK OKP `x`. Accepts both
+ * encodings `Agent.publicKey` is written in across this repo (hex 64-char,
+ * or base64/base64url 44-char raw 32-byte key) — the same two forms
+ * resources/ed25519-auth.ts's `importEd25519Key` accepts, so a document
+ * built from this always matches what the verified-request path already
+ * treats as the agent's key.
+ */
+export function agentPublicKeyToJwk(publicKeyStr, kid) {
+    const trimmed = (publicKeyStr ?? "").trim();
+    let raw;
+    if (/^[0-9a-f]{64}$/i.test(trimmed)) {
+        raw = Buffer.from(trimmed, "hex");
+    }
+    else {
+        raw = Buffer.from(trimmed.replace(/-/g, "+").replace(/_/g, "/"), "base64");
+    }
+    if (raw.length !== 32) {
+        throw new Error(`agent public key must decode to 32 bytes (got ${raw.length})`);
+    }
+    const jwk = { kty: "OKP", crv: "Ed25519", x: raw.toString("base64url") };
+    if (kid)
+        jwk.kid = kid;
+    return jwk;
+}

package/dist/resources/mcp-handler.js

@@ -1,7 +1,7 @@
 /**
  * mcp-handler.ts — the Model-2 custom MCP protocol handler.
  *
- * A minimal in-process MCP (JSON-RPC 2.0) handler serving the 9 curated flair
+ * A minimal in-process MCP (JSON-RPC 2.0) handler serving the 12 curated flair
  * tools over Streamable HTTP. It is wrapped by `@harperfast/oauth`'s
  * `withMCPAuth` (see mcp-oauth.ts), which fails closed on any missing/invalid
  * Bearer token BEFORE this handler runs and, on success, sets