@tpsdev-ai/flair 0.13.0 → 0.15.0

package/dist/resources/WorkspaceState.js

@@ -50,8 +50,18 @@ export class WorkspaceState extends databases.flair.WorkspaceState {
         // there was no authenticated agent, so anonymous could write any record).
         if (auth.kind === "anonymous")
             return UNAUTH();
-        if (auth.kind === "agent" && !auth.isAdmin && content.agentId !== auth.agentId) {
-            return FORBIDDEN("forbidden: cannot write workspace state for another agent");
+        // No-forge: a non-admin agent's workspace record is ALWAYS attributed to the
+        // authenticated identity (from the Ed25519 signature), never the body. We do
+        // NOT trust `content.agentId` — overwriting it (rather than 403'ing a
+        // mismatch) mirrors Presence.post(): "agentId from signature, NOT from body".
+        // An admin may write on behalf of another agent (content.agentId honored if
+        // present, else defaults to the admin's own id). Internal in-process callers
+        // keep whatever agentId they pass.
+        if (auth.kind === "agent" && !auth.isAdmin) {
+            content.agentId = auth.agentId;
+        }
+        else if (auth.kind === "agent" && auth.isAdmin) {
+            content.agentId ||= auth.agentId;
         }
         content.createdAt = new Date().toISOString();
         content.timestamp ||= content.createdAt;

package/dist/resources/a2a-url.js

@@ -0,0 +1,53 @@
+// URL resolution for the A2A adapter — flair#507.
+//
+// A default local Flair install listens on DEFAULT_HTTP_PORT (19926, the
+// CLI's `DEFAULT_PORT` in src/cli.ts), NOT on 9926 (the legacy early-install
+// port). The A2A agent-card `url` and the streaming catch-up self-fetch must
+// reflect the REAL listening port, or a remote A2A peer that follows discovery
+// hits a dead port.
+//
+// Kept free of any @harperfast/harper import so the resolution logic is
+// unit-testable without spinning up Harper (mirrors agentcard-fields.ts —
+// avoids the simulator-pattern drift that let the AdminInstance predicate be
+// reproduced-not-imported).
+// The CLI's DEFAULT_HTTP_PORT (src/cli.ts `DEFAULT_PORT`). Keep in sync.
+export const DEFAULT_HTTP_PORT = 19926;
+// Loopback base URL for in-process self-calls (e.g. the streaming catch-up
+// fetch). Points at the port Flair is ACTUALLY listening on, which Harper
+// exposes via HTTP_PORT in the runtime env — never the public/proxy URL.
+// Falls back to DEFAULT_HTTP_PORT for a default local install.
+export function localBaseUrl(env = process.env) {
+    return `http://127.0.0.1:${env.HTTP_PORT || DEFAULT_HTTP_PORT}`;
+}
+// Public base URL advertised in the A2A agent card so remote peers can reach
+// this Flair. Mirrors AdminInstance.resolvePublicUrl (flair#404):
+//   1. FLAIR_PUBLIC_URL (explicit override, always wins)
+//   2. Request headers (X-Forwarded-Proto/Host or Host) — how the caller
+//      actually reached us
+//   3. http://127.0.0.1:${HTTP_PORT} — local-only fallback on the REAL port
+export function resolvePublicBaseUrl(request, env = process.env) {
+    if (env.FLAIR_PUBLIC_URL) {
+        return env.FLAIR_PUBLIC_URL.replace(/\/$/, "");
+    }
+    const getHeader = (name) => {
+        const h = request?.headers;
+        if (!h)
+            return undefined;
+        if (typeof h.get === "function")
+            return h.get(name) ?? h.get(name.toLowerCase()) ?? undefined;
+        if (typeof h === "object") {
+            const obj = h.asObject ?? h;
+            return obj[name] ?? obj[name.toLowerCase()] ?? undefined;
+        }
+        return undefined;
+    };
+    const fwdProto = getHeader("X-Forwarded-Proto");
+    const fwdHost = getHeader("X-Forwarded-Host");
+    const host = fwdHost ?? getHeader("Host");
+    if (host && /^[\w.\-:]+$/.test(host)) {
+        const scheme = fwdProto && (fwdProto === "http" || fwdProto === "https") ? fwdProto : "https";
+        const effectiveScheme = fwdProto ? scheme : (host.includes(":") ? "http" : scheme);
+        return `${effectiveScheme}://${host}`;
+    }
+    return localBaseUrl(env);
+}

package/dist/resources/agent-auth.js

@@ -16,6 +16,7 @@
  * 30s timestamp window + a per-(agent,nonce) seen-set pruned to that window.
  */
 import { databases } from "@harperfast/harper";
+import { b64ToArrayBuffer } from "./b64.js";
 const WINDOW_MS = Number(process.env.FLAIR_AGENT_AUTH_WINDOW_MS) || 30_000;
 /**
  * Shared Harper user that verified Ed25519 agents resolve to (least-privilege
@@ -27,16 +28,8 @@ export const FLAIR_AGENT_USERNAME = "flair-agent";
 // Replay protection: remember recently-seen (agent:nonce), pruned by the window.
 const nonceSeen = new Map();
 // ─── Crypto helpers ───────────────────────────────────────────────────────────
-function b64ToArrayBuffer(b64) {
-    // Handle both standard and URL-safe base64.
-    const std = b64.replace(/-/g, "+").replace(/_/g, "/");
-    const bin = atob(std);
-    const buf = new ArrayBuffer(bin.length);
-    const view = new Uint8Array(buf);
-    for (let i = 0; i < bin.length; i++)
-        view[i] = bin.charCodeAt(i);
-    return buf;
-}
+// b64ToArrayBuffer lives in ./b64.ts (shared with auth-middleware.ts + Presence.ts
+// so the base64/base64url decoder can't drift across the three auth call sites).
 const keyCache = new Map();
 async function importEd25519Key(publicKeyStr) {
     const cached = keyCache.get(publicKeyStr);

package/dist/resources/auth-middleware.js

@@ -2,6 +2,7 @@ import { patchRecord } from "./table-helpers.js";
 import { server, databases } from "@harperfast/harper";
 import { getEmbedding } from "./embeddings-provider.js";
 import { isAdmin, FLAIR_AGENT_USERNAME } from "./agent-auth.js";
+import { b64ToArrayBuffer } from "./b64.js";
 // --- Admin credentials ---
 // Admin auth is sourced exclusively from Harper's own environment variables
 // (HDB_ADMIN_PASSWORD / FLAIR_ADMIN_PASSWORD). No filesystem token file.
@@ -37,16 +38,8 @@ const nonceSeen = new Map();
 // auth reshape this gate and the per-resource allow* helpers must agree on who's
 // an admin — one implementation guarantees they can't diverge.
 // ─── Crypto helpers ───────────────────────────────────────────────────────────
-function b64ToArrayBuffer(b64) {
-    // Handle both standard and URL-safe base64
-    const std = b64.replace(/-/g, '+').replace(/_/g, '/');
-    const bin = atob(std);
-    const buf = new ArrayBuffer(bin.length);
-    const view = new Uint8Array(buf);
-    for (let i = 0; i < bin.length; i++)
-        view[i] = bin.charCodeAt(i);
-    return buf;
-}
+// b64ToArrayBuffer lives in ./b64.ts (shared with agent-auth.ts + Presence.ts so
+// the base64/base64url decoder can't drift across the three auth call sites).
 const keyCache = new Map();
 async function importEd25519Key(publicKeyStr) {
     if (keyCache.has(publicKeyStr))

package/dist/resources/b64.js

@@ -0,0 +1,40 @@
+/**
+ * b64 — single shared base64 / base64url decoder for Ed25519 auth.
+ *
+ * This was previously copy-pasted into three files (auth-middleware.ts,
+ * agent-auth.ts, Presence.ts) and they drifted: some copies fed url-safe input
+ * straight to `atob`, which rejects `-`/`_` ("Invalid character") and 401s any
+ * agent whose public key (or signature) is base64url-encoded. Found in the
+ * Rivet × krais cross-org dogfood: an Agent registered with a base64url pubkey
+ * containing `-`/`_` failed signature verification. One shared decoder so the
+ * three call sites can't diverge again (same lesson as HarperFast/harper#1466).
+ *
+ * Accepts BOTH standard base64 (`+` `/`, with optional `=` padding) AND
+ * base64url (`-` `_`, padded or unpadded). Standard input is unchanged.
+ */
+/**
+ * Decode a base64 OR base64url string to an ArrayBuffer.
+ *
+ * Normalizes url-safe alphabet (`-`→`+`, `_`→`/`) and right-pads with `=` to a
+ * length that is a multiple of 4 before calling `atob`, so unpadded base64url
+ * (the common JWK / Buffer.toString('base64url') form — e.g. a 32-byte key is
+ * 43 chars, a 64-byte signature is 86 chars) decodes correctly regardless of
+ * how lenient the host runtime's `atob` is about missing padding.
+ */
+export function b64ToArrayBuffer(b64) {
+    // Normalize base64url → standard base64 alphabet.
+    let std = b64.replace(/-/g, "+").replace(/_/g, "/");
+    // Right-pad to a multiple of 4 so atob accepts unpadded base64url input.
+    const remainder = std.length % 4;
+    if (remainder === 2)
+        std += "==";
+    else if (remainder === 3)
+        std += "=";
+    // remainder === 1 is not a valid base64 length; let atob throw as before.
+    const bin = atob(std);
+    const buf = new ArrayBuffer(bin.length);
+    const view = new Uint8Array(buf);
+    for (let i = 0; i < bin.length; i++)
+        view[i] = bin.charCodeAt(i);
+    return buf;
+}

package/dist/resources/bm25-filter.js

@@ -0,0 +1,84 @@
+// ─── BM25 candidate SECURITY filter (the hard cross-agent trust boundary) ────
+// Per spec FLAIR-BM25-HYBRID-RETRIEVAL §26 + Sherlock's gate (§45-46):
+//
+//   "apply the SAME conditions[] filter (agent scoping, archived exclusion,
+//    tag/subject) to the BM25 candidates BEFORE fusion. BM25-scoring other
+//    agents' private memories and filtering only after fusion would leak
+//    term-frequency / content metadata across agent boundaries. The conditions
+//    filter MUST precede the union/fusion."
+//
+// The HNSW path gets this filter FOR FREE — Harper applies conditions[] inside
+// Memory.search(). The BM25 pass runs in-process over the corpus, so it MUST
+// re-apply the IDENTICAL predicate itself, BEFORE any scoring is fused or even
+// returned. This module is the single source of that predicate.
+//
+// Harper-free + pure so the security test exercises the SHIPPED predicate
+// directly (test/unit/bm25-security.test.ts).
+//
+// The condition shapes mirror EXACTLY what SemanticSearch.ts builds:
+//   - leaf:  { attribute, comparator, value }
+//   - group: { operator: "or", conditions: [...] }
+// supported comparators: "equals", "not_equal" (the only ones SemanticSearch
+// emits into conditions[]). An unknown comparator/shape is treated as NON-matching
+// (fail closed — never leak on an unrecognized condition).
+function isGroup(c) {
+    return c.operator !== undefined && Array.isArray(c.conditions);
+}
+// Evaluate a single leaf condition against a record. `tags` is array-valued in
+// Harper; "equals" on an array attribute is membership (matches Harper's
+// array-attribute equals semantics used by the tag filter).
+function matchLeaf(cond, record) {
+    const actual = record?.[cond.attribute];
+    switch (cond.comparator) {
+        case "equals":
+            if (Array.isArray(actual))
+                return actual.includes(cond.value);
+            return actual === cond.value;
+        case "not_equal":
+            // Harper "not_equal" semantics used for `archived not_equal true`: a record
+            // WITHOUT the field (undefined) is included — it is "not equal" to true.
+            if (Array.isArray(actual))
+                return !actual.includes(cond.value);
+            return actual !== cond.value;
+        default:
+            // Unknown comparator → fail closed (do NOT pass a record on a condition we
+            // can't evaluate; that could leak across the agent boundary).
+            return false;
+    }
+}
+function matchCondition(cond, record) {
+    if (isGroup(cond)) {
+        const results = cond.conditions.map((c) => matchCondition(c, record));
+        return cond.operator === "or" ? results.some(Boolean) : results.every(Boolean);
+    }
+    return matchLeaf(cond, record);
+}
+// AND across the top-level conditions[] (Harper's default for a conditions array
+// — same as SemanticSearch passing them as the implicit-AND query.conditions).
+export function matchesConditions(conditions, record) {
+    for (const c of conditions) {
+        if (!matchCondition(c, record))
+            return false;
+    }
+    return true;
+}
+export function passesRecordFilters(record, f = {}) {
+    const now = f.now ?? Date.now();
+    if (record?.expiresAt && Date.parse(record.expiresAt) < now)
+        return false;
+    if (f.sinceDate && record?.createdAt && new Date(record.createdAt) < f.sinceDate)
+        return false;
+    if (f.asOf && record?.validFrom && record.validFrom > f.asOf)
+        return false;
+    if (f.asOf && record?.validTo && record.validTo <= f.asOf)
+        return false;
+    return true;
+}
+// The full BM25-candidate security filter: a record is a valid BM25 candidate
+// ONLY if it passes BOTH the agent-scoping/archived/tag/subject conditions[] AND
+// the per-record temporal filters — IDENTICAL to the HNSW candidate gate. Apply
+// this to the corpus BEFORE building/scoring the union (defense at the boundary,
+// not after fusion).
+export function isAllowedBm25Candidate(record, conditions, timeFilters = {}) {
+    return matchesConditions(conditions, record) && passesRecordFilters(record, timeFilters);
+}

package/dist/resources/bm25.js

@@ -0,0 +1,130 @@
+// ─── BM25 + union-RRF hybrid retrieval (Harper-free, unit-testable) ──────────
+// Per spec FLAIR-BM25-HYBRID-RETRIEVAL (Kern-approved, ops-i39b). This module is
+// deliberately Harper-free — same rationale as ./scoring.ts — so the BM25
+// scoring, the candidate-union RRF fusion, and the security conditions-filter
+// can be unit-tested directly against the SHIPPED code without a live Harper.
+//
+// Ported from the pilot ops/tools/agent-fabric/bm25-rrf-pilot.mjs (commit
+// 5552320), which validated: BM25 alone recovers 5/6 severe misses into top-3;
+// candidate-UNION RRF (NOT naive whole-corpus RRF) recovers 4/6 into top-10 with
+// no regression on the within-cluster gate (p@3 holds 0.88).
+// ─── Feature flag: BM25 + union-RRF hybrid retrieval ────────────────────────
+// Flag OFF (default) → SemanticSearch behavior is byte-identical to the
+// pre-hybrid path (HNSW + the +0.05 exact-substring keyword bump). Flag ON → the
+// hybrid path. Toggle with FLAIR_HYBRID_RETRIEVAL=true (also "1" / "on"). Read
+// per-call so it can be flipped without a rebuild and set per-case in tests.
+// Lives here (Harper-free) so it's unit-testable.
+export function hybridEnabled() {
+    const v = (process.env.FLAIR_HYBRID_RETRIEVAL ?? "").toLowerCase();
+    return v === "true" || v === "1" || v === "on";
+}
+// BM25 parameters (Kern-approved): k1≈1.2, b≈0.75; standard IDF + BM25.
+export const BM25_K1 = 1.2;
+export const BM25_B = 0.75;
+// RRF constant (Cormack et al. 2009 default). A doc absent from a list
+// contributes 0 from that list (rank = ∞).
+export const RRF_K = 60;
+// BM25 candidate window — top-N by BM25 score fused into the union (spec §35:
+// "BM25 uses a fixed SEM_LIMIT=50"). Independent of CANDIDATE_MULTIPLIER (the
+// HNSW fetch size, which is left untouched).
+export const SEM_LIMIT = 50;
+// Tokenize: lowercase, split on non-alphanumeric, drop trivial stopwords and
+// 1-char tokens. Standard, language-agnostic enough for the corpus.
+const STOP = new Set(("a an the and or but of to in on at for with from by as is are was were be been being " +
+    "this that these those it its do does did so if then than when how what why who whom which while " +
+    "i you he she we they them his her our your their not no yes can will would should could may might " +
+    "have has had get got into out over under again about up down off all any each").split(" "));
+export function tokenize(text) {
+    return ((text || "").toLowerCase().match(/[a-z0-9]+/g) || []).filter((t) => t.length > 1 && !STOP.has(t));
+}
+// Build a BM25 index over docs[].content. Standard Robertson/Sparck-Jones BM25
+// with the +1 IDF variant (always non-negative — the common Lucene/Elasticsearch
+// form).
+export function buildBM25(docs) {
+    const N = docs.length;
+    const docTokens = docs.map((d) => tokenize(d.content || ""));
+    const docLen = docTokens.map((t) => t.length);
+    const avgdl = docLen.reduce((s, x) => s + x, 0) / (N || 1);
+    const tfPerDoc = docTokens.map((toks) => {
+        const tf = new Map();
+        for (const t of toks)
+            tf.set(t, (tf.get(t) || 0) + 1);
+        return tf;
+    });
+    const df = new Map();
+    for (const tf of tfPerDoc)
+        for (const term of tf.keys())
+            df.set(term, (df.get(term) || 0) + 1);
+    const idf = new Map();
+    for (const [term, n] of df)
+        idf.set(term, Math.log(1 + (N - n + 0.5) / (n + 0.5)));
+    function rank(query) {
+        const qToks = [...new Set(tokenize(query))];
+        const scored = docs.map((d, i) => {
+            const tf = tfPerDoc[i];
+            const dl = docLen[i];
+            let s = 0;
+            for (const term of qToks) {
+                const f = tf.get(term);
+                if (!f)
+                    continue;
+                const numer = f * (BM25_K1 + 1);
+                const denom = f + BM25_K1 * (1 - BM25_B + BM25_B * (dl / (avgdl || 1)));
+                s += (idf.get(term) || 0) * (numer / denom);
+            }
+            return { id: d.id, score: s };
+        });
+        scored.sort((a, b) => b.score - a.score);
+        return scored;
+    }
+    return { rank, get N() { return N; }, get avgdl() { return avgdl; } };
+}
+// ─── Reciprocal Rank Fusion over a candidate UNION ──────────────────────────
+// rankings: array of ordered id-lists (best-first). A doc absent from a list
+// contributes 0 from that list. `universe` = the id set fused over — for the
+// production hybrid this is the candidate UNION (semantic ∪ bm25), NOT the whole
+// corpus (naive whole-corpus RRF FAILS — the broken semantic list floods the
+// fusion and buries BM25's rank-1 hits; pilot confirmed 0/6).
+//
+// Returns a Map id → raw RRF score. Caller normalizes + sorts.
+export function rrfScores(rankings, universe) {
+    const score = new Map();
+    for (const id of universe)
+        score.set(id, 0);
+    for (const list of rankings) {
+        list.forEach((id, idx) => {
+            if (!score.has(id))
+                return; // doc not in this universe (union mode)
+            score.set(id, (score.get(id) || 0) + 1 / (RRF_K + idx + 1)); // idx+1 = 1-based rank
+        });
+    }
+    return score;
+}
+// Fuse semantic + BM25 candidate id-lists via candidate-union RRF and return a
+// per-id score normalized to [0,1] (rrf / max_rrf_in_union). This normalized
+// value is the rawScore fed to compositeScore so durability/recency/rBoost and
+// the RBOOST_RELEVANCE_FLOOR / minScore thresholds still apply unchanged.
+//
+//   semIds  — semantic candidate ids, best-first (from the HNSW pass).
+//   bm25Ids — BM25 candidate ids, best-first, already sliced to SEM_LIMIT and
+//             already SECURITY-FILTERED (see filterBm25Candidates) BEFORE this call.
+//
+// The union dedupes ids across both lists. Absent-from-a-list = 0 contribution.
+export function fuseRrfNormalized(semIds, bm25Ids) {
+    const union = new Set([...semIds, ...bm25Ids]);
+    const raw = rrfScores([semIds, bm25Ids], union);
+    let maxRrf = 0;
+    for (const v of raw.values())
+        if (v > maxRrf)
+            maxRrf = v;
+    const norm = new Map();
+    if (maxRrf <= 0) {
+        // Degenerate (empty union) — nothing to normalize.
+        for (const [id] of raw)
+            norm.set(id, 0);
+        return norm;
+    }
+    for (const [id, v] of raw)
+        norm.set(id, v / maxRrf);
+    return norm;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Identity, memory, and soul for AI agents. Cryptographic identity (Ed25519), semantic memory with local embeddings, and persistent personality — all in a single process.",
   "type": "module",
   "license": "Apache-2.0",
@@ -25,7 +25,7 @@
     "openclaw"
   ],
   "bin": {
-    "flair": "dist/cli.js"
+    "flair": "dist/cli-shim.cjs"
   },
   "files": [
     "dist/",
@@ -46,7 +46,7 @@
     "test": "bun test",
     "test:e2e": "playwright test",
     "release": "./scripts/release.sh",
-    "postinstall": "node -e \"try{const{chmodSync,statSync}=require('fs');const p='dist/cli.js';if(statSync(p).isFile()){chmodSync(p,0o755);console.error('@tpsdev-ai/flair: chmod +x ' + p + ' OK')}}catch(e){if(e.code!=='ENOENT')console.error('postinstall warn:',e.message)}\""
+    "postinstall": "node -e \"try{const{chmodSync,statSync}=require('fs');for(const p of ['dist/cli-shim.cjs','dist/cli.js']){try{if(statSync(p).isFile()){chmodSync(p,0o755);console.error('@tpsdev-ai/flair: chmod +x ' + p + ' OK')}}catch(e){if(e.code!=='ENOENT')console.error('postinstall warn:',e.message)}}}catch(e){console.error('postinstall warn:',e.message)}\""
   },
   "publishConfig": {
     "access": "public"