@tpsdev-ai/flair 0.23.0 → 0.24.0

package/dist/resources/Memory.js

@@ -291,8 +291,26 @@ async function hasWriteGrant(granteeId, ownerId) {
  * requires a "write" MemoryGrant from the target's owner (reuses the existing
  * agent-auth/grant machinery — no parallel auth logic). Returns a Response to
  * short-circuit with (400/403), or null to continue.
+ *
+ * flair#704: an explicit `supersedes: null` — the shape most JSON writers
+ * produce for an unset optional field (`JSON.stringify({supersedes: undefined})`
+ * drops the key, but plenty of writers instead do `{supersedes: x ?? null}`)
+ * — must be treated identically to the key being OMITTED, per the
+ * additive-schema convention (flair#695: an explicit null on an
+ * optional/nullable field reads as absent, not as a distinct value). Fixed by
+ * deleting the key BEFORE the type check below, so (a) the check never
+ * rejects it, and (b) `super.put()`/`super.post()` — Harper full-record
+ * replacement, see table-helpers.ts's header comment — never persists a
+ * literal `null` where "absent" was intended: the stored row ends up
+ * byte-for-byte identical to the omitted-key case, so every downstream
+ * `!content.supersedes` / `content.supersedes &&` check below (and in
+ * closeSupersededIfNeeded) already treats it as unset with no further
+ * changes needed.
  */
 async function validateAndAuthorizeSupersedes(content, auth) {
+    if (content.supersedes === null) {
+        delete content.supersedes;
+    }
     if (content.supersedes !== undefined && typeof content.supersedes !== "string") {
         return new Response(JSON.stringify({ error: "supersedes must be a string (memory ID)" }), {
             status: 400, headers: { "Content-Type": "application/json" },

package/dist/resources/Presence.js

@@ -32,7 +32,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
 import { resolveAgentAuth, verifyAgentRequest } from "./agent-auth.js";
-import { WINDOW_MS, isNonceReplay, recordNonce, importEd25519Key, b64ToArrayBuffer } from "./ed25519-auth.js";
+import { WINDOW_MS, isNonceReplay, recordNonce, importEd25519Key, b64ToArrayBuffer, parseTpsEd25519Header } from "./ed25519-auth.js";
 // ─── Constants ────────────────────────────────────────────────────────────────
 const CURRENT_TASK_MAX_LENGTH = 200;
 const VALID_ACTIVITIES = new Set(["coding", "reviewing", "planning", "debugging", "idle"]);
@@ -409,11 +409,11 @@ export class Presence extends databases.flair.Presence {
             agentId = middlewareAgent;
         }
         else {
-            const m = authHeader.match(/^TPS-Ed25519\s+([^:]+):(\d+):([^:]+):(.+)$/);
-            if (!m) {
+            const parsed = parseTpsEd25519Header(authHeader);
+            if (!parsed) {
                 return new Response(JSON.stringify({ error: "Ed25519 agent auth required for heartbeat" }), { status: 401, headers: { "Content-Type": "application/json" } });
             }
-            const [, headerAgentId, tsRaw, nonce, sigB64] = m;
+            const { agentId: headerAgentId, tsRaw, nonce, signatureB64: sigB64 } = parsed;
             const ts = Number(tsRaw);
             const now = Date.now();
             if (!Number.isFinite(ts) || Math.abs(now - ts) > WINDOW_MS) {

package/dist/resources/agent-auth.js

@@ -16,7 +16,7 @@
  * 30s timestamp window + a per-(agent,nonce) seen-set pruned to that window.
  */
 import { databases } from "@harperfast/harper";
-import { WINDOW_MS, isNonceReplay, recordNonce, importEd25519Key, b64ToArrayBuffer } from "./ed25519-auth.js";
+import { WINDOW_MS, isNonceReplay, recordNonce, importEd25519Key, b64ToArrayBuffer, parseTpsEd25519Header } from "./ed25519-auth.js";
 /**
  * Shared Harper user that verified Ed25519 agents resolve to (least-privilege
  * `flair_agent` role), replacing the old admin super_user elevation. Single
@@ -56,15 +56,14 @@ async function getAdminAgents() {
 export async function isAdmin(agentId) {
     return (await getAdminAgents()).has(agentId);
 }
-const HEADER_RE = /^TPS-Ed25519\s+([^:]+):(\d+):([^:]+):(.+)$/;
 async function doVerify(request) {
     const header = request?.headers?.get?.("authorization") ??
         request?.headers?.asObject?.authorization ??
         "";
-    const m = HEADER_RE.exec(header);
-    if (!m)
+    const parsed = parseTpsEd25519Header(header);
+    if (!parsed)
         return null;
-    const [, agentId, tsRaw, nonce, signatureB64] = m;
+    const { agentId, tsRaw, nonce, signatureB64 } = parsed;
     const ts = Number(tsRaw);
     const now = Date.now();
     if (!Number.isFinite(ts) || Math.abs(now - ts) > WINDOW_MS)

package/dist/resources/auth-middleware.js

@@ -2,7 +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 { WINDOW_MS, isNonceReplay, recordNonce, importEd25519Key, b64ToArrayBuffer } from "./ed25519-auth.js";
+import { WINDOW_MS, isNonceReplay, recordNonce, importEd25519Key, b64ToArrayBuffer, parseTpsEd25519Header } from "./ed25519-auth.js";
 import { resolveReadScope } from "./memory-read-scope.js";
 // --- Admin credentials ---
 // Admin auth is sourced exclusively from Harper's own environment variables
@@ -230,8 +230,8 @@ server.http(async (request, nextLayer) => {
         return nextLayer(request);
     }
     // ── Ed25519 agent auth ────────────────────────────────────────────────────
-    const m = header.match(/^TPS-Ed25519\s+([^:]+):(\d+):([^:]+):(.+)$/);
-    if (!m) {
+    const parsed = parseTpsEd25519Header(header);
+    if (!parsed) {
         // For browser-accessible admin pages, emit `WWW-Authenticate: Basic` so
         // the browser shows a native auth dialog instead of a bare 401 page.
         // JSON API endpoints don't get this — they should keep the structured
@@ -260,7 +260,7 @@ server.http(async (request, nextLayer) => {
         catch { /* frozen headers — annotation on the request object still applies */ }
         return nextLayer(request);
     }
-    const [, agentId, tsRaw, nonce, signatureB64] = m;
+    const { agentId, tsRaw, nonce, signatureB64 } = parsed;
     const ts = Number(tsRaw);
     const now = Date.now();
     if (!Number.isFinite(ts) || Math.abs(now - ts) > WINDOW_MS)

package/dist/resources/ed25519-auth.js

@@ -42,6 +42,43 @@ export { b64ToArrayBuffer };
  * stated "plugin-shaped, config via env" design intent.
  */
 export const WINDOW_MS = Number(process.env.FLAIR_AGENT_AUTH_WINDOW_MS) || 30_000;
+// ─── Auth header parsing (single shared implementation) ────────────────────
+//
+// One parser for the `Authorization: TPS-Ed25519 <id>:<ts>:<nonce>:<sig>`
+// header, used by all 3 call sites (auth-middleware.ts, agent-auth.ts,
+// Presence.ts) so the grammar and its input bounds can't drift.
+/**
+ * Upper bound on the accepted Authorization header length. A well-formed
+ * TPS-Ed25519 header (`TPS-Ed25519 <id>:<ts>:<nonce>:<sig>`) is a few hundred
+ * chars at most; anything materially larger is malformed. The header is
+ * untrusted client input, so we cap its length before running the regex,
+ * keeping parse cost bounded regardless of the input's shape.
+ */
+export const MAX_AUTH_HEADER_LEN = 4096;
+/**
+ * TPS-Ed25519 auth header grammar.
+ *
+ * The two colon-delimited text captures use `[^:\s]+` (not `[^:]+`) so they are
+ * disjoint from the preceding `\s+`: with no character shared between the two
+ * adjacent quantifiers there is exactly one way to split any input, so matching
+ * is linear-time on every input (including long, degenerate ones). A real
+ * agentId / nonce / signature never contains whitespace, so excluding it is
+ * behavior-preserving for well-formed headers.
+ */
+export const TPS_ED25519_HEADER_RE = /^TPS-Ed25519\s+([^:\s]+):(\d+):([^:\s]+):(.+)$/;
+/**
+ * Parse a TPS-Ed25519 `Authorization` header value into its fields, or return
+ * null if it is over `MAX_AUTH_HEADER_LEN` or doesn't match the grammar.
+ * Callers treat null exactly as a header that carries no valid agent auth.
+ */
+export function parseTpsEd25519Header(header) {
+    if (!header || header.length > MAX_AUTH_HEADER_LEN)
+        return null;
+    const m = TPS_ED25519_HEADER_RE.exec(header);
+    if (!m)
+        return null;
+    return { agentId: m[1], tsRaw: m[2], nonce: m[3], signatureB64: m[4] };
+}
 // ─── Replay guard (single shared instance) ─────────────────────────────────
 //
 // nonceSeen is the ONE module-level singleton — the whole point of this

package/dist/resources/embeddings-boot.js

@@ -87,6 +87,41 @@
 import { resolveModelsDir } from "./embeddings-provider.js";
 const LOGICAL_NAME = "default";
 const MODEL_NAME = "nomic-embed-text";
+/**
+ * Pooling declaration (HFE 0.5.0+, harper-fabric-embeddings' `init()`
+ * `pooling` option). Verification, not override: the native addon has no
+ * pooling knob of its own — llama.cpp always pools by whatever the GGUF's
+ * own `<arch>.pooling_type` metadata says. Declaring the expectation makes
+ * HFE assert it at init and fail loudly on absent/mismatched metadata,
+ * instead of a metadata-less or mismatched conversion silently pooling the
+ * wrong way (see node_modules/harper-fabric-embeddings/README.md's `init()`
+ * 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
+ * `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".
+ *
+ * Applies to the bench-only `modelPath` override too (`benchModelPathOverride()`
+ * below): `FLAIR_RECALL_HARNESS_MODEL_PATH` lets an operator point this
+ * registration at an arbitrary GGUF for a Q4/Q8 bakeoff, and this constant
+ * assumes whatever file lands there is still nomic-family (mean-pooling) —
+ * true for every bakeoff run to date (same base model, different quant).
+ * HFE 0.5.0's verification is exactly the safety net that turns "someone
+ * points --model-file at a non-nomic, non-mean-pooling GGUF" into a loud
+ * boot-time failure instead of a silently-wrong pooling pass.
+ */
+const EMBEDDING_POOLING = "mean";
 /**
  * BENCH-ONLY escape hatch — NOT a production feature flag, never documented
  * as an operator setting, and never read anywhere else in this codebase.
@@ -131,7 +166,9 @@ export async function registerEmbeddingsBackend() {
         await register({
             logicalName: LOGICAL_NAME,
             kind: "embedding",
-            config: modelPath ? { modelPath } : { modelName: MODEL_NAME, modelsDir: resolveModelsDir() },
+            config: modelPath
+                ? { modelPath, pooling: EMBEDDING_POOLING }
+                : { modelName: MODEL_NAME, modelsDir: resolveModelsDir(), pooling: EMBEDDING_POOLING },
         });
     }
     catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.23.0",
+  "version": "0.24.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",
@@ -55,10 +55,10 @@
   },
   "dependencies": {
     "@harperfast/harper": "5.1.17",
-    "@harperfast/oauth": "2.2.0",
+    "@harperfast/oauth": "2.4.0",
     "@types/js-yaml": "4.0.9",
     "commander": "14.0.3",
-    "harper-fabric-embeddings": "^0.4.0",
+    "harper-fabric-embeddings": "^0.5.0",
     "jose": "6.2.2",
     "js-yaml": "4.1.1",
     "node-llama-cpp": "3.18.1",