@tpsdev-ai/flair 0.30.0 → 0.31.1

package/dist/resources/agent-auth.js

@@ -17,6 +17,7 @@
  */
 import { databases } from "harper";
 import { WINDOW_MS, isNonceReplay, recordNonce, importEd25519Key, b64ToArrayBuffer, parseTpsEd25519Header } from "./ed25519-auth.js";
+import { ADMIN_ROLE, agentRecordIsAdmin } from "./agent-admin.js";
 /**
  * Shared Harper user that verified Ed25519 agents resolve to (least-privilege
  * `flair_agent` role), replacing the old admin super_user elevation. Single
@@ -32,8 +33,14 @@ export const FLAIR_AGENT_USERNAME = "flair-agent";
 // visible to the other two, and the crypto/decoder logic can't drift.
 // ─── Admin resolution ─────────────────────────────────────────────────────────
 // Admin agents come from FLAIR_ADMIN_AGENTS (comma-separated) OR Agent records
-// with role === "admin". OR-combined, cached 60s. Distinct from Harper's
-// super_user — admin here gates flair-policy decisions (promotions, raw ops).
+// whose `role` is the admin sentinel. OR-combined, cached 60s. Distinct from
+// Harper's super_user — admin here gates flair-policy decisions (promotions,
+// raw ops).
+//
+// The record half of that union is the ONE place the Agent table is consulted
+// for an authorization decision, and it resolves through
+// resources/agent-admin.ts's shared predicate so it cannot drift from the
+// reporters or from the MCP surface (flair#941 — they had drifted).
 let adminCacheExpiry = 0;
 let adminCache = new Set();
 async function getAdminAgents() {
@@ -43,9 +50,9 @@ async function getAdminAgents() {
     const fromEnv = (process.env.FLAIR_ADMIN_AGENTS ?? "").split(",").map((s) => s.trim()).filter(Boolean);
     const fromDb = [];
     try {
-        const results = await databases.flair.Agent.search([{ attribute: "role", value: "admin", condition: "equals" }]);
+        const results = await databases.flair.Agent.search([{ attribute: "role", value: ADMIN_ROLE, condition: "equals" }]);
         for await (const row of results)
-            if (row?.id)
+            if (row?.id && agentRecordIsAdmin(row))
                 fromDb.push(row.id);
     }
     catch { /* Agent table may be empty */ }
@@ -53,6 +60,28 @@ async function getAdminAgents() {
     adminCacheExpiry = now + 60_000;
     return adminCache;
 }
+/**
+ * Drop the memoised admin set so the NEXT isAdmin() re-reads the Agent table.
+ *
+ * The 60s TTL is a load optimisation, but on its own it makes a privilege
+ * change take up to a minute to appear — which reads as "the change didn't
+ * work", and is exactly the confusion flair#941 is about: an operator grants
+ * admin, tests it, sees a denial, and starts changing other things. The write
+ * path knows precisely when a principal's admin status changed, so it says so
+ * and the grant is effective on the caller's very next request.
+ *
+ * Deliberately NOT a distributed invalidation: Harper runs N worker threads,
+ * each with its own module instance and its own cache, so a promotion applied
+ * on thread A still takes up to the TTL to be seen by thread B. Making that
+ * exact would mean a shared invalidation channel, which is a much larger change
+ * than the confusion warrants — the bound stays 60s, unchanged, and the common
+ * single-threaded/dev case becomes immediate. Called by resources/Agent.ts's
+ * write paths.
+ */
+export function invalidateAdminCache() {
+    adminCacheExpiry = 0;
+    adminCache = new Set();
+}
 export async function isAdmin(agentId) {
     return (await getAdminAgents()).has(agentId);
 }
@@ -195,10 +224,73 @@ export async function allowAdmin(context) {
     const a = await resolveAgentAuth(context);
     return a.kind === "internal" || (a.kind === "agent" && a.isAdmin);
 }
+/**
+ * flair#936 — the `internal` verdict is TRUSTED and UNFILTERED, and it is also
+ * what a caller gets for supplying no context at all. Nothing distinguishes
+ * "I am flair's own maintenance code" from "I am an application developer who
+ * did not know a context was required": both spell it `new Memory()`, both
+ * succeed, and both return plausible data. It surfaces months later as memories
+ * that were never scoped.
+ *
+ * This does not change the verdict — every authorization outcome is byte-
+ * identical — it ends the SILENCE. A deliberate elevated call says so with
+ * `internalContext()` (resources/in-process.ts), whose `__flairInternal` marker
+ * is read here and nowhere else; anything else that lands on `internal` gets one
+ * warning per process, with the stack, so the condition is observable where it
+ * was previously invisible.
+ *
+ * MEASURED, and the reason this is worth having: flair itself has NO in-process
+ * caller that relies on the omission — every maintenance, migration, federation
+ * and boot path goes through the raw `databases.flair.*` table accessor, which
+ * bypasses this resolver entirely rather than defaulting through it. So a
+ * warning from this line is, in practice, always either an embedding
+ * application that forgot a context or a flair call site that should be naming
+ * its intent. Neither is noise.
+ *
+ * The marker is read off `context`, NOT off `c`: `c` is rebound to
+ * `context.request` on the line below, and internalContext() carries the marker
+ * on the outer object.
+ */
+let warnedInternalByOmission = false;
+/**
+ * Was this elevated call DELIBERATE — i.e. did the caller name the authority
+ * with `internalContext()` rather than land on it by leaving a context off?
+ *
+ * Exported because it is the whole decision, and a decision worth testing is
+ * worth testing directly: the warning itself is latched once per process, which
+ * makes any test of the side effect order-dependent (bun shares one module
+ * registry across the whole run, so whichever file resolves a context-less call
+ * first consumes the latch and every later assertion silently passes). Pinning
+ * the predicate instead is deterministic.
+ *
+ * Grants nothing and is never consulted for an authorization decision — the
+ * verdict is identical either way.
+ */
+export function isDeliberateInternalCall(context) {
+    return context?.__flairInternal === true;
+}
+/** The advisory text, exported so its content is pinned without tripping the latch. */
+export const INTERNAL_BY_OMISSION_WARNING = "[flair-auth] a resource was invoked with NO caller context and resolved to the trusted " +
+    "`internal` verdict: reads are UNFILTERED across every agent, writes are unattributed, and " +
+    "the admin-only gate passes. If this is your application's code, pass agentContext(<id>) from " +
+    "@tpsdev-ai/flair's in-process seam so the call is scoped and attributed. If the elevated " +
+    "authority is genuinely intended, say so with internalContext() and this warning will stop. " +
+    "Fires once per process.";
+function noteInternalVerdict(context) {
+    if (warnedInternalByOmission)
+        return;
+    if (isDeliberateInternalCall(context))
+        return; // deliberate, and said so
+    warnedInternalByOmission = true;
+    const stack = (new Error().stack ?? "").split("\n").slice(2, 7).join("\n");
+    console.error(INTERNAL_BY_OMISSION_WARNING + "\n" + stack);
+}
 export async function resolveAgentAuth(context) {
     const c = context?.request ?? context;
-    if (!c)
+    if (!c) {
+        noteInternalVerdict(context);
         return { kind: "internal" };
+    }
     if (c.tpsAnonymous === true)
         return { kind: "anonymous" };
     if (c.tpsAgent) {
@@ -231,5 +323,6 @@ export async function resolveAgentAuth(context) {
             return { kind: "agent", agentId: auth.agentId, isAdmin: auth.isAdmin };
         return { kind: "anonymous" };
     }
+    noteInternalVerdict(context);
     return { kind: "internal" };
 }

package/dist/resources/auth-middleware.js

@@ -4,6 +4,7 @@ import { getEmbedding } from "./embeddings-provider.js";
 import { isAdmin, FLAIR_AGENT_USERNAME } from "./agent-auth.js";
 import { WINDOW_MS, isNonceReplay, recordNonce, importEd25519Key, b64ToArrayBuffer, parseTpsEd25519Header } from "./ed25519-auth.js";
 import { resolveReadScope } from "./memory-read-scope.js";
+import { isForbiddenOwnerMutation, resolveGuardedRecord } from "./record-owner-guard.js";
 // --- Admin credentials ---
 // Admin auth is sourced exclusively from Harper's own environment variables
 // (HDB_ADMIN_PASSWORD / FLAIR_ADMIN_PASSWORD). No filesystem token file.
@@ -350,6 +351,37 @@ server.http(async (request, nextLayer) => {
     // ── Server-side permission guards ──────────────────────────────────────────
     const method = request.method.toUpperCase();
     const isMutation = method === "POST" || method === "PUT" || method === "PATCH" || method === "DELETE";
+    // ── THE record-ownership rule, for every table, on every mutating verb ─────
+    //
+    // One enforcement point rather than one per resource. See
+    // resources/record-owner-guard.ts for why this is not written into each
+    // resource's put(): Harper maps verbs to methods one-to-one, so a rule living
+    // in put() is enforced on PUT alone, and nearly every resource wrote its rules
+    // there. Doing this per-resource would be N chances to get one wrong and would
+    // still leave the next resource broken by default.
+    //
+    // Ownership is read from the STORED record named by the path — never from the
+    // request body, which is the caller's claim about who owns the row and was how
+    // a body that simply omitted the field passed unchecked.
+    //
+    // Deliberately scoped to records that ALREADY EXIST: creation is left to each
+    // resource's own no-forge attribution. That keeps this incapable of breaking a
+    // create, a self-write, or a legitimate cross-agent field like MemoryGrant's
+    // granteeId — it can only narrow mutation of another agent's stored row.
+    if (isMutation && !request.tpsAgentIsAdmin) {
+        const guarded = resolveGuardedRecord(url.pathname);
+        if (guarded) {
+            try {
+                const record = await databases.flair[guarded.table]?.get(guarded.id);
+                if (isForbiddenOwnerMutation(record, guarded.ownerField, agentId)) {
+                    return new Response(JSON.stringify({
+                        error: `forbidden: cannot modify ${guarded.table} owned by another principal`,
+                    }), { status: 403, headers: { "Content-Type": "application/json" } });
+                }
+            }
+            catch { /* unreadable row → fall through to the resource's own rules */ }
+        }
+    }
     if (isMutation) {
         // OrgEvent: authorId must match authenticated agent
         if ((url.pathname === "/OrgEvent" || url.pathname.startsWith("/OrgEvent/")) &&
@@ -419,19 +451,59 @@ server.http(async (request, nextLayer) => {
                 catch { }
             }
         }
-        // Soul PUT: only owner or admin
-        if (url.pathname.startsWith("/Soul") && (method === "PUT" || method === "POST")) {
+        // Soul mutations: only the owner or an admin may write a soul entry.
+        //
+        // This guard had two independent holes, either of which alone let one agent
+        // rewrite another's identity data:
+        //
+        //   1. THE VERB LIST enumerated PUT and POST only. Its three siblings above
+        //      (OrgEvent, WorkspaceState, Memory) all include PATCH, and Memory
+        //      includes DELETE; this one did neither. Harper routes PATCH to a
+        //      resource method that carries no ownership check of its own
+        //      (Soul.ts's enforceWriteAuth covers post()/put()), and DELETE reached
+        //      the table with no per-record check at all. Both were live.
+        //
+        //   2. IT COMPARED THE BODY, not the target. `body.agentId` is the owner
+        //      the CALLER claims, and the check only fired when that field was
+        //      present and mismatched — so a body omitting it, which a partial
+        //      write naturally does, was compared against nothing and passed
+        //      whatever record the URL pointed at. The resource-level check behind
+        //      it is "validate-truthy" attribution, which by design also passes an
+        //      ABSENT owner field, so nothing downstream caught it either. (A PUT
+        //      happened to fail anyway, but on `agentId: String!` schema
+        //      validation — a 400 for the wrong reason, not an authorization
+        //      decision, and not a defence to rely on.)
+        //
+        // Closing one hole leaves the other reachable through the remaining verbs,
+        // so both are closed here: every mutating verb is covered, and ownership is
+        // resolved from the STORED RECORD named by the path. That is the same shape
+        // as the Memory ownership guard below, which is the resource in this file
+        // that already had it right — worth copying rather than reinventing.
+        //
+        // The path test stays `startsWith("/Soul")` so sibling routes keep the
+        // body check they already had; the record lookup is scoped to the real
+        // `/Soul/<id>` collection so it never resolves an unrelated id.
+        if (url.pathname.startsWith("/Soul") &&
+            (method === "POST" || method === "PUT" || method === "PATCH" || method === "DELETE")) {
             if (!request.tpsAgentIsAdmin) {
-                let bodyAgentId = null;
-                try {
-                    const clone = request.clone();
-                    const body = await clone.json();
-                    bodyAgentId = body?.agentId ?? null;
-                }
-                catch { }
-                if (bodyAgentId && bodyAgentId !== agentId) {
-                    return new Response(JSON.stringify({ error: "forbidden: non-admin cannot modify another agent's soul" }), { status: 403 });
+                // (a) A PRESENT, mismatched body agentId is a forged attribution.
+                if (method !== "DELETE") {
+                    let bodyAgentId = null;
+                    try {
+                        const clone = request.clone();
+                        const body = await clone.json();
+                        bodyAgentId = body?.agentId ?? null;
+                    }
+                    catch { }
+                    if (bodyAgentId && bodyAgentId !== agentId) {
+                        return new Response(JSON.stringify({ error: "forbidden: non-admin cannot modify another agent's soul" }), { status: 403 });
+                    }
                 }
+                // (b) The owner of the record actually being written — the half that
+                // catches a body simply leaving agentId out — is now the shared
+                // record-ownership rule at the top of this block, which applies it to
+                // every table on every mutating verb. Deliberately NOT repeated here:
+                // one condition enforced in two places is how the two drift apart.
             }
         }
         // Memory promotion guard: only admin can approve or set durability=permanent
@@ -453,21 +525,22 @@ server.http(async (request, nextLayer) => {
                 catch { }
             }
         }
-        // Memory PUT/DELETE: ownership check (non-admin can only modify their own memories)
+        // Memory DELETE: permanent memories are admin-only to purge.
+        //
+        // The OWNERSHIP half of this guard — which was the model the shared
+        // record-ownership rule above was built from, and the only one in this file
+        // that already covered PATCH — now lives there and covers every table. What
+        // remains here is the part that is NOT about ownership: durability. An agent
+        // owning a permanent memory still may not purge it.
         if (((url.pathname === "/Memory" || url.pathname.startsWith("/Memory/") || url.pathname === "/memory" || url.pathname.startsWith("/memory/"))) &&
-            (method === "PUT" || method === "DELETE" || method === "PATCH")) {
+            method === "DELETE") {
             if (!request.tpsAgentIsAdmin) {
                 try {
                     const pathParts = url.pathname.split("/").filter(Boolean);
                     const memId = pathParts[1] ? decodeURIComponent(pathParts[1]) : null;
                     if (memId) {
                         const record = await databases.flair.Memory.get(memId);
-                        if (record && record.agentId && record.agentId !== agentId) {
-                            return new Response(JSON.stringify({
-                                error: `forbidden: cannot modify memory owned by ${record.agentId}`
-                            }), { status: 403 });
-                        }
-                        if (method === "DELETE" && record?.durability === "permanent") {
+                        if (record?.durability === "permanent") {
                             return new Response(JSON.stringify({
                                 error: "forbidden: only admins can purge permanent memories"
                             }), { status: 403 });

package/dist/resources/embeddings-boot.js

@@ -98,19 +98,17 @@ const MODEL_NAME = "nomic-embed-text";
  * table for the exact contract this PR bumps to).
  *
  * "mean" is nomic-embed-text-v1.5's actual pooling type — NOT assumed from
- * the model's reputation, directly confirmed against the shipped GGUF:
- * `node_modules/.bin/node-llama-cpp inspect gguf
- * ~/.flair/data/models/nomic-embed-text-v1.5.Q4_K_M.gguf` reports
- * `"nomic-bert": { pooling_type: 1 }`, and llama.cpp's
+ * the model's reputation, directly confirmed against the shipped GGUF by
+ * reading its metadata: `"nomic-bert": { pooling_type: 1 }`, and llama.cpp's
  * `enum llama_pooling_type` maps 1 -> `LLAMA_POOLING_TYPE_MEAN` (0 = none,
- * 1 = mean, 2 = cls, 3 = last, 4 = rank). nomic-embed-text is a
- * NomicBertModel architecture, not Qwen3 (last-token) — flair registers no
- * Qwen3-class embedding model today (the Qwen3-Reranker-0.6B in
- * resources/rerank-provider.ts is a SEPARATE code path that calls
- * node-llama-cpp directly for generative yes/no scoring, never goes through
- * HFE's register()/init(), and has no embedding-pooling context at all — see
- * that file's header). If a Qwen3-class (last-token-pooling) embedding model
- * is ever registered here, it must declare `pooling: "last"`, not "mean".
+ * 1 = mean, 2 = cls, 3 = last, 4 = rank). (That reading was originally taken
+ * with `node-llama-cpp inspect gguf`, which flair no longer depends on —
+ * flair#893. Any GGUF inspector reports the same metadata field; install the
+ * CLI ad hoc if the check needs repeating.) nomic-embed-text is a
+ * NomicBertModel architecture, not Qwen3 (last-token), and flair registers no
+ * Qwen3-class embedding model today. If a Qwen3-class (last-token-pooling)
+ * embedding model is ever registered here, it must declare `pooling: "last"`,
+ * not "mean".
  *
  * Applies to the bench-only `modelPath` override too (`benchModelPathOverride()`
  * below): `FLAIR_RECALL_HARNESS_MODEL_PATH` lets an operator point this

package/dist/resources/embeddings-provider.js

@@ -152,7 +152,7 @@ const EMBEDDING_PREFIXES_ENABLED = true; // Phase 2 prefix flip ON — re-baseli
  * embedding call, so this lets it override the ONE thing that matters
  * (whether `models.embed` receives `inputType`, and whether `getModelId()`
  * stamps the suffix) via the env var it already forwards to `startHarper()`
- * (the same mechanism `FLAIR_HYBRID_RETRIEVAL`/`FLAIR_RERANK_ENABLED` use).
+ * (the same mechanism `FLAIR_HYBRID_RETRIEVAL` uses).
  *
  * Bidirectional, not two separate force-on/force-off hatches: THE GATE has
  * flipped direction once already (off→on, this PR) and may again in the
@@ -236,12 +236,15 @@ async function getModelsApi() {
 /**
  * Resolve the directory the embeddings model lives in / downloads into.
  *
- * Implementation moved to `resources/models-dir.ts` (flair#815) so the
- * reranker can share the exact same resolution without importing this module
- * (several unit-isolated tests `mock.module()` this file wholesale — see
- * models-dir.ts's header). Re-exported here so existing consumers keep their
- * import site: `resources/embeddings-boot.ts` (flair#694), which builds the
- * `modelsDir` it passes to harper-fabric-embeddings' `register()`, and
+ * Implementation lives in `resources/models-dir.ts` (extracted in flair#815)
+ * so any model consumer can share the exact same resolution without importing
+ * this module — several unit-isolated tests `mock.module()` this file
+ * wholesale, and an incomplete stub then breaks every file that imports it.
+ * See models-dir.ts's header for why that hazard makes the tiny standalone
+ * module worth keeping even now that embeddings are its only consumer.
+ * Re-exported here so existing consumers keep their import site:
+ * `resources/embeddings-boot.ts` (flair#694), which builds the `modelsDir` it
+ * passes to harper-fabric-embeddings' `register()`, and
  * test/unit/embeddings-models-dir.test.ts, which pins the resolution order.
  */
 export { resolveModelsDir } from "./models-dir.js";

package/dist/resources/health.js

@@ -3,9 +3,9 @@ import { promises as fsp, existsSync, readFileSync } from "node:fs";
 import { homedir, platform } from "node:os";
 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";
+import { resolveMigrationDataDirForRead } from "./migrations/data-dir.js";
 import { REM_DEDUP_STATS_PATH } from "./dedup-cluster.js";
 const db = databases;
 const redactHome = (p) => {
@@ -560,12 +560,21 @@ export class HealthDetail extends Resource {
         // "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.
+        //
+        // flair#812: the dataDir is resolved by the shared, READ-ONLY resolver
+        // (resources/migrations/data-dir.ts) rather than the old
+        // `HDB_ROOT ?? homedir()/.flair/data` expression duplicated here — that
+        // env var is never set by anything, so the left branch was dead and the
+        // path silently disagreed with wherever the boot cycle actually wrote.
+        // `lastCycleError` is surfaced so `flair doctor` can name WHY a cycle
+        // didn't run, not merely that it didn't.
         try {
-            const migrationsDataDir = process.env.HDB_ROOT ?? join(homedir(), ".flair", "data");
+            const migrationsDataDir = resolveMigrationDataDirForRead();
             const snapshot = getMigrationStatusSnapshot(migrationsDataDir);
             stats.migrations = {
                 cyclePhase: snapshot.cyclePhase,
                 lastCycleAt: snapshot.lastCycleAt ?? null,
+                lastCycleError: snapshot.lastCycleError ?? null,
                 migrations: snapshot.migrations,
             };
             for (const m of snapshot.migrations) {
@@ -573,13 +582,25 @@ export class HealthDetail extends Resource {
                     warnings.push({ level: "warn", message: `migration '${m.id}' ${m.state}${m.reason ? `: ${m.reason}` : ""} — see \`flair doctor\`` });
                 }
             }
+            // The boot trigger sets `scheduled` synchronously at module load, so
+            // `idle` here means resources/migration-boot.js never loaded — the
+            // instance is running a build whose migration trigger is absent or
+            // failed to import, and NO migration will ever run on it.
+            if (snapshot.cyclePhase === "idle" && snapshot.migrations.length > 0) {
+                warnings.push({
+                    level: "warn",
+                    message: "migration boot cycle never fired on this instance (cyclePhase=idle) — no migration will run until this is resolved; see `flair doctor`",
+                });
+            }
         }
         catch {
             stats.migrations = null;
         }
         // ── Disk ──
+        // flair#812: same shared read-only resolution as the migrations section
+        // above, so `disk.dataDir` names the directory migrations actually use.
         try {
-            const dataDir = process.env.HDB_ROOT ?? join(homedir(), ".flair", "data");
+            const dataDir = resolveMigrationDataDirForRead();
             const snapshotDir = join(homedir(), ".flair", "snapshots");
             const dirSize = async (root, maxDepth = 6) => {
                 if (!(await exists(root)))
@@ -658,22 +679,6 @@ 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 ──