@tpsdev-ai/flair 0.16.1 → 0.18.0

package/dist/resources/SemanticSearch.js

@@ -4,6 +4,7 @@ import { getEmbedding, getMode } from "./embeddings-provider.js";
 import { patchRecord, withDetachedTxn } from "./table-helpers.js";
 import { checkRateLimit, rateLimitResponse } from "./rate-limiter.js";
 import { wrapUntrusted } from "./content-safety.js";
+import { isRerankEnabled, getRerankTopN, getRerankBudgetMs, getRerankMinCandidates, rerankCandidates, } from "./rerank-provider.js";
 // Temporal decay + relevance scoring (incl. the OPS-AYGD retrievalBoost cap +
 // relevance floor) lives in ./scoring.ts — a Harper-free module so it can be
 // unit-tested directly (see test/unit/temporal-scoring.test.ts).
@@ -170,6 +171,16 @@ export class SemanticSearch extends Resource {
         }
         const results = [];
         const hybrid = hybridEnabled();
+        // When the reranker is on, widen the legacy HNSW fetch so it has a deeper
+        // pool to re-score (retrieve topN → rerank → slice to limit). Decoupled
+        // from CANDIDATE_MULTIPLIER so composite re-ranking keeps its existing
+        // headroom. Scoped to the legacy (non-hybrid) vector path below — the
+        // hybrid path's candidate pool is already governed by CANDIDATE_MULTIPLIER
+        // (semantic leg) + SEM_LIMIT (BM25 leg) via RRF union (ops-i39b); the
+        // reranker still applies to its output further down regardless of which
+        // path produced `filteredResults`.
+        const rerankOn = isRerankEnabled();
+        const rerankTopN = getRerankTopN();
         if (hybrid) {
             // ─── BM25 + union-RRF hybrid path (ops-i39b) ─────────────────────────
             // 1. Semantic candidates via HNSW (unchanged fetch). 2. BM25 lexical pass
@@ -284,8 +295,10 @@ export class SemanticSearch extends Resource {
             }
         }
         else if (qEmb) {
-            // ─── HNSW vector search path ───────────────────────────────────────────
-            const candidateLimit = limit * CANDIDATE_MULTIPLIER;
+            // ─── HNSW vector search path (legacy, hybrid flag OFF) ────────────────
+            const candidateLimit = rerankOn
+                ? Math.max(limit * CANDIDATE_MULTIPLIER, rerankTopN)
+                : limit * CANDIDATE_MULTIPLIER;
             const query = {
                 sort: { attribute: "embedding", target: qEmb, distance: "cosine" },
                 select: ["id", "agentId", "content", "contentHash", "visibility", "tags", "durability",
@@ -387,7 +400,32 @@ export class SemanticSearch extends Resource {
         if (minScore > 0) {
             filteredResults = filteredResults.filter((r) => r._score >= minScore);
         }
-        filteredResults.sort((a, b) => b._score - a._score);
+        // ─── Cross-encoder rerank (best-effort, fail-open to vector order) ───────
+        // Re-scores query+candidate TOGETHER (cross-attention the pooled embedding
+        // can't do) and reorders before the final slice. Reorders whatever
+        // `filteredResults` the retrieval stage above produced — legacy HNSW-only
+        // OR the BM25+union-RRF hybrid path (ops-i39b) — since both converge into
+        // the same `results`/`filteredResults` shape before this point; hybrid
+        // retrieves+fuses, the reranker only reorders the fused set. Still gated
+        // on `qEmb` (an embedding was actually generated); the pure keyword-only
+        // fallback (no qEmb at all) is untouched either way. The reranker
+        // overwrites `_score` with the rerank score (so margin measurement reads it)
+        // and preserves the semantic score as `_semScore`; `_rawScore` is left as-is
+        // so recall-bench's scoring:"raw" path stays reproducible. On init failure,
+        // timeout, or any throw, rerankCandidates returns the input UNCHANGED and we
+        // fall through to the existing vector-order sort — recall is never blocked.
+        if (rerankOn && qEmb && q && filteredResults.length >= getRerankMinCandidates()) {
+            // Pre-sort by vector order so the topN fed to the reranker is the most
+            // semantically-promising slice (filteredResults isn't sorted yet here).
+            filteredResults.sort((a, b) => b._score - a._score);
+            filteredResults = await rerankCandidates(String(q), filteredResults, {
+                topN: rerankTopN,
+                budgetMs: getRerankBudgetMs(),
+            });
+        }
+        else {
+            filteredResults.sort((a, b) => b._score - a._score);
+        }
         const topResults = filteredResults.slice(0, limit);
         // Async hit tracking — don't block the response
         const now = new Date().toISOString();

package/dist/resources/WorkspaceLatest.js

@@ -5,7 +5,7 @@
  * Auth: requesting agent must match agentId in path (or be admin).
  */
 import { Resource, databases } from "@harperfast/harper";
-import { allowVerified } from "./agent-auth.js";
+import { allowVerified, resolveAgentAuth } from "./agent-auth.js";
 export class WorkspaceLatest extends Resource {
     // Self-authorize via the Ed25519 agent verify (auth reshape removes the gate's
     // admin elevation). Any verified agent may read; the path-vs-agent ownership
@@ -14,9 +14,13 @@ export class WorkspaceLatest extends Resource {
         return allowVerified(this.getContext?.());
     }
     async get(pathInfo) {
-        const request = this.context?.request ?? this.request;
-        const callerAgent = request?.tpsAgent;
-        const callerIsAdmin = request?.tpsAgentIsAdmin === true;
+        // Harper v5 does not populate this.context / this.request on Resource
+        // subclasses — getContext() is the only reliable path to the gate's
+        // tpsAgent/tpsAgentIsAdmin annotations (ops-sal4: the previous
+        // `(this as any).context?.request ?? (this as any).request` read was always
+        // undefined, so the ownership check below never ran — fail-open cross-agent
+        // read).
+        const auth = await resolveAgentAuth(this.getContext?.());
         // Extract agentId from path: /WorkspaceLatest/{agentId}
         const agentId = (typeof pathInfo === "string" ? pathInfo : null) ??
             this.getId?.() ??
@@ -24,8 +28,13 @@ export class WorkspaceLatest extends Resource {
         if (!agentId) {
             return new Response(JSON.stringify({ error: "agentId required in path: GET /WorkspaceLatest/{agentId}" }), { status: 400, headers: { "Content-Type": "application/json" } });
         }
-        // Auth: requesting agent must match path agentId (or admin)
-        if (callerAgent && !callerIsAdmin && callerAgent !== agentId) {
+        // Auth: internal calls and admins pass unfiltered; a verified agent may only
+        // read its own workspace state; anonymous is denied. allowRead() already
+        // blocks anonymous HTTP, but this handler must fail closed on its own too.
+        if (auth.kind === "anonymous") {
+            return new Response(JSON.stringify({ error: "forbidden: cannot read workspace state for another agent" }), { status: 403, headers: { "Content-Type": "application/json" } });
+        }
+        if (auth.kind === "agent" && !auth.isAdmin && auth.agentId !== agentId) {
             return new Response(JSON.stringify({ error: "forbidden: cannot read workspace state for another agent" }), { status: 403, headers: { "Content-Type": "application/json" } });
         }
         // Query WorkspaceState table for this agent, sorted by timestamp desc

package/dist/resources/dedup.js

@@ -0,0 +1,62 @@
+// ─── Conservative near-duplicate detection primitives (Harper-free) ─────────
+// Memory-integrity fix (#526/#548 field regressions). This module is
+// deliberately Harper-free — same rationale as ./bm25.ts and ./scoring.ts —
+// so the cosine+Jaccard co-gate math is unit-testable directly against the
+// SHIPPED code without a live Harper. The DB-touching top-1-cosine lookup
+// (needs `databases`) lives in ./Memory.ts, built on top of these primitives.
+//
+// ── THE INVARIANT ────────────────────────────────────────────────────────────
+// This module NEVER decides whether to write. It only scores a candidate
+// match. Callers (Memory.post / Memory.put) always write the new record; a
+// "conservative match" is surfaced to the caller as a SIGNAL on the response
+// (deduplicated/matchedId/matchConfidence), never as a reason to skip the
+// write. That was the #526 bug: two topically-close but DISTINCT findings —
+// one about replication route-directionality, one about DDL/schema
+// replication — and the second was silently dropped because raw cosine alone
+// flagged it as a "duplicate" of the first. Requiring BOTH cosine AND lexical
+// (Jaccard token-overlap) to clear their thresholds against the SAME single
+// top-cosine candidate catches true near-dups while sparing topic collisions
+// (high cosine, low lexical) — and even then, only ever as a non-suppressing
+// signal.
+import { tokenize } from "./bm25.js";
+/** Default raw-cosine similarity threshold for a candidate to even be considered. */
+export const DEDUP_COSINE_THRESHOLD_DEFAULT = 0.95;
+/** Default Jaccard token-overlap threshold (of the top cosine candidate). */
+export const DEDUP_LEXICAL_THRESHOLD_DEFAULT = 0.5;
+/** Below this content length, similarity scoring is unreliable ("ok" would
+ *  match "ok" trivially) — the dedup gate is bypassed entirely. */
+export const DEDUP_MIN_CONTENT_LENGTH = 20;
+/** Jaccard similarity of two token sets: |A∩B| / |A∪B|. An empty side yields 0
+ *  (no signal — never treated as "fully similar" by vacuous set equality). */
+export function jaccardSimilarity(tokensA, tokensB) {
+    const a = new Set(tokensA);
+    const b = new Set(tokensB);
+    if (a.size === 0 || b.size === 0)
+        return 0;
+    let intersection = 0;
+    for (const t of a)
+        if (b.has(t))
+            intersection++;
+    const union = a.size + b.size - intersection;
+    return union === 0 ? 0 : intersection / union;
+}
+/**
+ * Conservative match = cosine AND lexical BOTH clear their thresholds.
+ * Both gates are required — a topic collision (high cosine, low lexical: two
+ * DIFFERENT findings that merely share a topic/vocabulary) must NOT be
+ * flagged as a duplicate. Only a true near-duplicate (high cosine AND high
+ * lexical overlap) is flagged.
+ */
+export function isConservativeMatch(cosine, lexical, cosineThreshold = DEDUP_COSINE_THRESHOLD_DEFAULT, lexicalThreshold = DEDUP_LEXICAL_THRESHOLD_DEFAULT) {
+    return cosine >= cosineThreshold && lexical >= lexicalThreshold;
+}
+/** Compute the {cosine, lexical} confidence pair for a candidate against the
+ *  new content's text, using the shared bm25 tokenizer. Rounded to 3dp to
+ *  match the existing _score rounding convention (SemanticSearch.ts). */
+export function computeMatchConfidence(newContent, candidateContent, cosine) {
+    const lexical = jaccardSimilarity(tokenize(newContent), tokenize(candidateContent || ""));
+    return {
+        cosine: Math.round(cosine * 1000) / 1000,
+        lexical: Math.round(lexical * 1000) / 1000,
+    };
+}

package/dist/resources/health.js

@@ -2,6 +2,7 @@ import { Resource, databases } from "@harperfast/harper";
 import { promises as fsp } from "node:fs";
 import { homedir, platform } from "node:os";
 import { join } from "node:path";
+import { getRerankStatus } from "./rerank-provider.js";
 const db = databases;
 const redactHome = (p) => {
     const home = homedir();
@@ -515,6 +516,22 @@ export class HealthDetail extends Resource {
         catch {
             stats.bridges = null;
         }
+        // ── Reranker ──
+        // Cross-encoder rerank stage. Reports flag/model/mode + live counters so we
+        // can see if it's silently degrading (fallbackCount climbing) in prod.
+        try {
+            const rr = getRerankStatus();
+            stats.rerank = rr;
+            if (rr.enabled && rr.state === "failed") {
+                warnings.push({ level: "warn", message: `reranker enabled but unavailable: ${rr.error ?? "init failed"} — recall falling back to vector order` });
+            }
+            if (rr.enabled && rr.rerankCount > 0 && rr.fallbackCount > rr.rerankCount) {
+                warnings.push({ level: "warn", message: `reranker falling back more than reranking (${rr.fallbackCount} fallbacks / ${rr.rerankCount} reranks) — check latency budget / topN` });
+            }
+        }
+        catch {
+            stats.rerank = null;
+        }
         // ── Warnings ──
         stats.warnings = warnings;
         // ── Process info ──

package/dist/resources/mcp-handler.js

@@ -0,0 +1,248 @@
+/**
+ * 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
+ * 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
+ * `request.mcp = { sub, client_id, aud, scope }` (verified RS256 JWT claims).
+ *
+ * ── This handler's job ──────────────────────────────────────────────────────
+ *   1. Parse the JSON-RPC request (initialize / tools/list / tools/call / ping).
+ *   2. For tools/call: resolve `request.mcp.sub` → a flair `Agent` id via the
+ *      `Credential(kind:"idp", idpSubject=sub)` lookup, JIT-provisioning a
+ *      Principal+Credential the first time IF the trust anchor allows it.
+ *   3. Establish the flair scoping context and invoke the tool, which delegates
+ *      to the existing resource handler (per-agent scoping enforced there).
+ *
+ * /mcp is its OWN dispatch chain (urlPath subroute) — flair's default
+ * auth-middleware does NOT run here, so this handler is solely responsible for
+ * turning the verified token into a scoped flair identity.
+ *
+ * ── Return shape ────────────────────────────────────────────────────────────
+ * Harper HTTP listeners return `{ status, body, headers? }`. MCP messages are
+ * JSON-RPC 2.0, so we serialize the JSON-RPC response object as the body.
+ */
+import { databases } from "@harperfast/harper";
+import { randomBytes } from "node:crypto";
+import { TOOLS, listToolDefs } from "./mcp-tools.js";
+// The MCP protocol revision we implement (initialize handshake).
+const PROTOCOL_VERSION = "2025-06-18";
+const JSON_HEADERS = { "content-type": "application/json" };
+// ─── JSON-RPC helpers ────────────────────────────────────────────────────────
+function rpcResult(id, result) {
+    return { status: 200, headers: JSON_HEADERS, body: JSON.stringify({ jsonrpc: "2.0", id, result }) };
+}
+function rpcError(id, code, message, httpStatus = 200) {
+    return {
+        status: httpStatus,
+        headers: JSON_HEADERS,
+        body: JSON.stringify({ jsonrpc: "2.0", id: id ?? null, error: { code, message } }),
+    };
+}
+// ─── sub → Agent resolution ─────────────────────────────────────────────────
+/**
+ * Should an unknown IdP subject be JIT-provisioned into a new Principal+
+ * Credential? Gated by an explicit, auditable trust anchor — an OPEN JIT-provision
+ * means anyone who can obtain a token (which requires passing the AS's own login
+ * + DCR gate) auto-materializes a flair agent. That is the Sherlock req-4 boundary
+ * on the resolution side: provisioning is a deliberate decision, not a default.
+ *
+ * `FLAIR_MCP_JIT_PROVISION` — truthy ("1"/"true"/"yes"/"on") enables it. Default
+ * OFF: an unknown subject is denied (the operator must pre-provision the
+ * Agent+Credential, or explicitly opt into JIT). This composes with the AS-side
+ * DCR gate (initialAccessToken) — both must be deliberately opened.
+ */
+function jitProvisionEnabled() {
+    const raw = (process.env.FLAIR_MCP_JIT_PROVISION ?? "").trim().toLowerCase();
+    return raw === "1" || raw === "true" || raw === "yes" || raw === "on";
+}
+/**
+ * Resolve the OAuth token `sub` to a flair `Agent` (Principal) id.
+ *
+ * Lookup: `Credential` where `kind === "idp"` AND `idpSubject === sub`. The
+ * Credential's `principalId` is the Agent id. This is the SAME credential surface
+ * XAA's ID-JAG path uses (resources/XAA.ts resolveOrCreatePrincipal) — one
+ * identity model, keyed on the IdP subject.
+ *
+ * Returns:
+ *   - `{ agentId, isAdmin }` when a Credential maps the sub to an Agent.
+ *   - null when no Credential maps the sub AND JIT-provisioning is disabled or
+ *     failed → the handler denies the tool call (sub is unresolvable).
+ */
+export async function resolveAgentFromSub(sub) {
+    if (!sub)
+        return null;
+    // 1. Existing IdP credential → its principalId is the Agent id.
+    try {
+        for await (const cred of databases.flair.Credential.search({
+            conditions: [
+                { attribute: "kind", comparator: "equals", value: "idp" },
+                { attribute: "idpSubject", comparator: "equals", value: sub },
+            ],
+        })) {
+            if (cred?.principalId && cred.status !== "revoked") {
+                // Touch lastUsedAt (best-effort; a failure here must not deny a valid call).
+                try {
+                    await databases.flair.Credential.put({ ...cred, lastUsedAt: new Date().toISOString() });
+                }
+                catch { /* non-fatal */ }
+                return { agentId: String(cred.principalId), isAdmin: await isAgentAdmin(cred.principalId) };
+            }
+        }
+    }
+    catch { /* Credential table empty / search error → fall through to JIT/deny */ }
+    // 2. No mapping. JIT-provision only behind the explicit trust anchor.
+    if (!jitProvisionEnabled())
+        return null;
+    try {
+        const principalId = await jitProvisionPrincipal(sub);
+        // A JIT-provisioned principal is a fresh, non-admin agent by construction.
+        return { agentId: principalId, isAdmin: false };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * JIT-provision a Principal (Agent record) + an IdP Credential from a verified
+ * token subject. Mirrors XAA.resolveOrCreatePrincipal's provisioning shape (the
+ * `Credential.kind:"idp"` + `idpSubject` surface) but keyed on the MCP token sub.
+ * The created agent is non-admin, `kind:"agent"`, unverified trust tier.
+ */
+async function jitProvisionPrincipal(sub) {
+    const now = new Date().toISOString();
+    const principalId = `agt_mcp_${sub.replace(/[^a-zA-Z0-9]/g, "_").slice(0, 24)}_${randomBytes(4).toString("hex")}`;
+    await databases.flair.Agent.put({
+        id: principalId,
+        name: principalId,
+        displayName: principalId,
+        kind: "agent",
+        type: "agent",
+        status: "active",
+        // Placeholder public key — an MCP-OAuth agent authenticates via bearer token,
+        // not an Ed25519 signing key. Marks provenance without forging a real key.
+        publicKey: `mcp-oauth:${sub}`,
+        defaultTrustTier: "unverified",
+        admin: false,
+        createdAt: now,
+        updatedAt: now,
+    });
+    await databases.flair.Credential.put({
+        id: `cred_mcp_${randomBytes(8).toString("hex")}`,
+        principalId,
+        kind: "idp",
+        label: "MCP OAuth (native /mcp)",
+        status: "active",
+        idpProvider: "mcp-oauth",
+        idpSubject: sub,
+        createdAt: now,
+        lastUsedAt: now,
+    });
+    return principalId;
+}
+/**
+ * Is this Principal a flair admin? Reads the Agent record's `admin`/`role`
+ * fields. A MCP-OAuth agent is NON-admin unless an operator has explicitly
+ * marked its Agent record admin — the MCP surface never elevates on its own.
+ */
+async function isAgentAdmin(principalId) {
+    try {
+        const agent = await databases.flair.Agent.get(principalId);
+        return agent?.admin === true || agent?.role === "admin";
+    }
+    catch {
+        return false;
+    }
+}
+// ─── MCP protocol dispatch ───────────────────────────────────────────────────
+/**
+ * The custom /mcp handler. `withMCPAuth` guarantees `request.mcp` is present here
+ * (it fails closed before us on a missing/invalid token), so we read the verified
+ * `sub` directly. Handles a single JSON-RPC request per POST (the minimal
+ * Streamable-HTTP shape the curated surface needs; batching is not used by the
+ * MCP clients we target).
+ */
+export async function mcpHandler(request) {
+    // MCP is a POST-only JSON-RPC surface. A GET (e.g. an SSE stream open) is not
+    // part of the curated request/response tool flow — reject cleanly.
+    const method = String(request?.method ?? "POST").toUpperCase();
+    if (method !== "POST") {
+        return rpcError(null, -32600, "method not allowed: /mcp accepts JSON-RPC POST only", 405);
+    }
+    // Parse the JSON-RPC body. Harper's Request wraps a Node stream — read text.
+    let msg;
+    try {
+        const text = typeof request.text === "function" ? await request.text() : request.body;
+        msg = typeof text === "string" ? JSON.parse(text) : text;
+    }
+    catch {
+        return rpcError(null, -32700, "parse error: invalid JSON");
+    }
+    if (!msg || typeof msg !== "object" || msg.jsonrpc !== "2.0" || typeof msg.method !== "string") {
+        return rpcError(msg?.id ?? null, -32600, "invalid request: expected JSON-RPC 2.0");
+    }
+    const { id, method: rpcMethod, params } = msg;
+    switch (rpcMethod) {
+        case "initialize":
+            return rpcResult(id, {
+                protocolVersion: PROTOCOL_VERSION,
+                capabilities: { tools: {} },
+                serverInfo: { name: "flair", version: "0.1.0" },
+            });
+        // Notifications (no id) — acknowledge with 202-ish empty 200; MCP clients send
+        // `notifications/initialized` after initialize.
+        case "notifications/initialized":
+            return { status: 200, headers: JSON_HEADERS, body: "" };
+        case "ping":
+            return rpcResult(id, {});
+        case "tools/list":
+            return rpcResult(id, { tools: listToolDefs() });
+        case "tools/call":
+            return handleToolCall(request, id, params);
+        default:
+            return rpcError(id, -32601, `method not found: ${rpcMethod}`);
+    }
+}
+/**
+ * tools/call: resolve the token sub → flair Agent, then dispatch to the curated
+ * tool. An unresolvable sub is DENIED (not silently run as anonymous or admin).
+ */
+async function handleToolCall(request, id, params) {
+    const toolName = params?.name;
+    const args = params?.arguments ?? {};
+    const entry = toolName ? TOOLS[toolName] : undefined;
+    if (!entry) {
+        return rpcError(id, -32602, `unknown tool: ${toolName ?? "(none)"}`);
+    }
+    // withMCPAuth guarantees request.mcp on success. Defense-in-depth: if it's
+    // somehow absent, deny (never run a tool without a verified sub).
+    const sub = request?.mcp?.sub;
+    if (!sub) {
+        return rpcError(id, -32001, "unauthorized: no verified token subject");
+    }
+    const agent = await resolveAgentFromSub(String(sub));
+    if (!agent) {
+        // Sub verified by the AS but not mapped to a flair Agent (and JIT disabled /
+        // failed). Deny — do NOT fall back to anonymous or admin.
+        return rpcError(id, -32001, "forbidden: token subject is not a provisioned flair agent");
+    }
+    try {
+        const result = await entry.impl(agent, args);
+        // MCP tools/call result: content blocks. Surface the handler's JSON payload
+        // as a text block (structuredContent carries the raw object for programmatic
+        // clients). A handler-level error object (from unwrap of a Response) is
+        // reported as an MCP tool error (isError) rather than a JSON-RPC error, so
+        // the client sees the structured message.
+        const text = typeof result === "string" ? result : JSON.stringify(result);
+        const isError = !!(result && typeof result === "object" && "error" in result && "status" in result);
+        return rpcResult(id, {
+            content: [{ type: "text", text }],
+            structuredContent: typeof result === "object" ? result : { value: result },
+            isError,
+        });
+    }
+    catch (err) {
+        return rpcError(id, -32000, `tool execution failed: ${err?.message ?? String(err)}`);
+    }
+}

package/dist/resources/mcp-oauth-flag.js

@@ -0,0 +1,84 @@
+/**
+ * mcp-oauth-flag.ts — the feature flag + AS config for the native-MCP OAuth
+ * surface (FLAIR-NATIVE-MCP-OAUTH, Model 2).
+ *
+ * Model 2 = a CUSTOM in-process `/mcp` JSON-RPC handler wrapped with
+ * `@harperfast/oauth`'s `withMCPAuth` (a fail-closed Bearer-token guard). It is
+ * DISTINCT from the native-application-MCP surface (design A / the
+ * `native-mcp-surface` branch's `static mcpTools`) — Model 2 does not use
+ * Harper's native MCP transport at all, so it is not blocked by the Harper
+ * native-MCP timing/worker gating gaps. The curated 9 tools are curated
+ * BY CONSTRUCTION (the handler only implements those 9).
+ *
+ * ── Default-OFF ─────────────────────────────────────────────────────────────
+ * The whole surface is gated behind `FLAIR_MCP_OAUTH`, default-OFF. When off:
+ *   - NO `/mcp` route is registered (mcpOAuthResource() early-returns).
+ *   - The `@harperfast/oauth` authorization-server config is NOT injected.
+ *   - flair's default auth chain is byte-identical to today.
+ * There is zero prod-behavior change until an operator explicitly opts in AND
+ * Sherlock signs off on live enablement.
+ *
+ * NOTE — separate flag from the native-MCP surface: `FLAIR_MCP_ENABLED` gates the
+ * design-A native surface (other branch); `FLAIR_MCP_OAUTH` gates THIS Model-2
+ * OAuth-guarded custom handler. They are independent flags for independent
+ * mechanisms; neither implies the other.
+ */
+/**
+ * Is the Model-2 OAuth-guarded /mcp surface enabled? Default-OFF.
+ *
+ * Read from `FLAIR_MCP_OAUTH` — truthy values: "1", "true", "yes", "on"
+ * (case-insensitive). Anything else (incl. unset / empty) → OFF.
+ */
+export function mcpOAuthEnabled() {
+    const raw = (process.env.FLAIR_MCP_OAUTH ?? "").trim().toLowerCase();
+    return raw === "1" || raw === "true" || raw === "yes" || raw === "on";
+}
+/**
+ * The public origin the authorization server pins `iss` (and, via it, `aud`) to.
+ * REQUIRED when the surface is enabled — the @harperfast/oauth plugin refuses to
+ * start without `mcp.issuer`, and pinning it (rather than letting it float with
+ * the client-controlled Host header) is the audience-confusion defense called
+ * out in the plugin's production checklist.
+ *
+ * Configurable via `FLAIR_MCP_ISSUER` (fall back to `FLAIR_PUBLIC_URL`, which the
+ * XAA token path already uses as the canonical public base). No hardcoded
+ * default — an operator turning the flag on MUST set the public origin.
+ */
+export function mcpIssuer() {
+    const raw = (process.env.FLAIR_MCP_ISSUER ?? process.env.FLAIR_PUBLIC_URL ?? "").trim();
+    return raw || undefined;
+}
+/**
+ * The RFC-8707 resource identifier tokens are audience-bound to. This is the
+ * public URL of the `/mcp` endpoint itself: `<issuer>/mcp`. `withMCPAuth`
+ * verifies the `aud` claim equals this, so the token minted for flair's `/mcp`
+ * cannot be replayed against a different resource server.
+ */
+export function mcpResource() {
+    const iss = mcpIssuer();
+    if (!iss)
+        return undefined;
+    return `${iss.replace(/\/+$/, "")}/mcp`;
+}
+/**
+ * `getConfig` payload injected into `withMCPAuth` so it verifies against the
+ * exact issuer/resource the authorization-server component mints tokens with —
+ * required because flair's `/mcp` handler and the @harperfast/oauth plugin may
+ * resolve different `node_modules` copies (docs/mcp-oauth.md §"Using withMCPAuth
+ * from a different component"), in which case the wrapper's live-config lookup
+ * reads `undefined` and fails closed. Pinning it here makes the iss/aud checks
+ * match the minted tokens.
+ *
+ * Returns undefined when the surface is off or the issuer is unset (the wrapper
+ * then denies — never serves a guarded route unconfigured, which is the safe
+ * failure mode).
+ */
+export function mcpAuthConfig() {
+    if (!mcpOAuthEnabled())
+        return undefined;
+    const issuer = mcpIssuer();
+    const resource = mcpResource();
+    if (!issuer || !resource)
+        return undefined;
+    return { enabled: true, issuer, resource };
+}

package/dist/resources/mcp-oauth.js

@@ -0,0 +1,84 @@
+/**
+ * mcp-oauth.ts — registers the Model-2 OAuth-guarded /mcp surface.
+ *
+ * Wraps the custom `mcpHandler` (mcp-handler.ts) with `@harperfast/oauth`'s
+ * `withMCPAuth` (a fail-closed Bearer-token guard) and mounts it on the `/mcp`
+ * urlPath subroute — its OWN dispatch chain, so flair's default auth-middleware
+ * never runs for /mcp and can't clobber the Bearer challenge.
+ *
+ * ── Default-OFF (byte-identical when off) ───────────────────────────────────
+ * The route is registered ONLY when `FLAIR_MCP_OAUTH` is truthy. When off, this
+ * module does NOTHING at load — no `server.http` call, no `@harperfast/oauth`
+ * import, no config injection. flair's default auth chain and prod behavior are
+ * unchanged. This is the no-op contract the flag guarantees.
+ *
+ * The `@harperfast/oauth` authorization-server config itself (providers, mcp.*,
+ * DCR gating) lives in `config.yaml` under the `@harperfast/oauth` key, but is
+ * only meaningful when an operator has set the issuer + enabled the flag (see
+ * docs). The plugin serves DCR / authorize / token / JWKS / discovery.
+ */
+import * as harper from "@harperfast/harper";
+import { mcpOAuthEnabled, mcpAuthConfig } from "./mcp-oauth-flag.js";
+import { mcpHandler } from "./mcp-handler.js";
+async function defaultLoadWithMCPAuth() {
+    // Dynamic import so the dep is only required when the surface is enabled.
+    const mod = (await import("@harperfast/oauth"));
+    return mod.withMCPAuth;
+}
+export async function registerMcpOAuthRoute(deps = {}) {
+    if (!mcpOAuthEnabled())
+        return false; // OFF → no route, no import, no side effects.
+    const config = mcpAuthConfig();
+    if (!config) {
+        // Flag on but issuer unset → we cannot safely pin iss/aud. Do NOT mount an
+        // unconfigured guard (withMCPAuth would fail closed anyway, but not mounting
+        // is the clearer signal). Log and bail — the operator must set FLAIR_MCP_ISSUER.
+        console.error("[mcp-oauth] FLAIR_MCP_OAUTH is on but no issuer configured " +
+            "(set FLAIR_MCP_ISSUER or FLAIR_PUBLIC_URL) — /mcp NOT mounted.");
+        return false;
+    }
+    let withMCPAuth;
+    try {
+        withMCPAuth = await (deps.loadWithMCPAuth ?? defaultLoadWithMCPAuth)();
+    }
+    catch (err) {
+        console.error("[mcp-oauth] @harperfast/oauth not available — /mcp NOT mounted: " + (err?.message ?? err));
+        return false;
+    }
+    if (typeof withMCPAuth !== "function") {
+        console.error("[mcp-oauth] @harperfast/oauth has no withMCPAuth export — /mcp NOT mounted.");
+        return false;
+    }
+    // Read `server` lazily off the namespace (it's a runtime global on the Harper
+    // module, not a static named export) so this module links cleanly even where a
+    // stub build of @harperfast/harper lacks the export.
+    const srv = deps.server ?? (harper.server);
+    // Primary registration: urlPath subroute → own chain (flair's auth-middleware
+    // does not run here). `getConfig` pins iss/resource to the AS's values so the
+    // wrapper's iss/aud checks match the minted tokens even if this component
+    // resolves a different node_modules copy of the plugin (docs/mcp-oauth.md
+    // §"Using withMCPAuth from a different component").
+    srv.http(withMCPAuth(mcpHandler, {
+        getConfig: () => mcpAuthConfig(),
+    }), { urlPath: "/mcp" });
+    console.error(`[mcp-oauth] /mcp mounted (OAuth-guarded); issuer=${config.issuer}`);
+    return true;
+}
+// Fire-and-forget at module load. Any failure is contained inside
+// registerMcpOAuthRoute (it logs and returns) so it can never crash flair boot.
+// When the flag is off it returns immediately without importing the plugin or
+// touching `server` — the byte-identical no-op contract.
+//
+// Skipped ONLY when a test explicitly opts out via FLAIR_MCP_NO_AUTOSTART, so
+// importing this module in a unit test doesn't trigger the real plugin/handler
+// import chain under a partial harper mock (registration is exercised directly
+// via the exported fn). Production never sets this, so boot behavior is
+// unchanged — and when the flag is off, registerMcpOAuthRoute() is a no-op
+// regardless. (bun test runs under Node's runtime here via the harper toolchain;
+// we don't gate on the runtime to avoid disabling the feature in a bun-hosted
+// deployment.)
+if (process.env.FLAIR_MCP_NO_AUTOSTART == null) {
+    void registerMcpOAuthRoute().catch((err) => {
+        console.error("[mcp-oauth] route registration failed (surface not mounted): " + (err?.message ?? err));
+    });
+}