@tpsdev-ai/flair 0.6.2 → 0.8.0

package/dist/resources/content-safety.js

@@ -47,6 +47,27 @@ export function scanContent(text) {
     }
     return { safe: flags.length === 0, flags };
 }
+/**
+ * Scan multiple string fields on a record, returning a merged SafetyResult.
+ * Non-string / empty fields are skipped. Flags are de-duplicated across fields.
+ */
+export function scanFields(record, fields) {
+    const flags = [];
+    const seen = new Set();
+    for (const field of fields) {
+        const value = record[field];
+        if (typeof value !== "string" || value.length === 0)
+            continue;
+        const result = scanContent(value);
+        for (const flag of result.flags) {
+            if (!seen.has(flag)) {
+                flags.push(flag);
+                seen.add(flag);
+            }
+        }
+    }
+    return { safe: flags.length === 0, flags };
+}
 /**
  * Check if strict mode is enabled (rejects flagged writes).
  */

package/dist/resources/federation-cleanup.js

@@ -0,0 +1,161 @@
+const CLEANUP_INTERVAL_MS = 300_000; // 5 minutes
+let cleanupTimer = null;
+/**
+ * Initialise the federation cleanup sweep.
+ *
+ * Only active on hub instances — reads the Instance table to determine
+ * role. On spokes this is a no-op.
+ *
+ * On hubs: ensures a 5-minute setInterval that sweeps PairingToken records
+ * for consumed or expired tokens, drops the corresponding bootstrap users,
+ * and performs housekeeping on expired/unconsumed token records.
+ *
+ * In test environments, callers pass mock serverOp/db via `opts` so this
+ * module never imports @harperfast/harper at the top level (which would
+ * crash when STORAGE_PATH isn't set).
+ */
+export async function initFederationCleanup(opts) {
+    const immediate = opts?.immediateTick ?? true;
+    // Resolve server / databases: use caller-supplied mocks when available,
+    // otherwise lazy-import @harperfast/harper at call time.
+    let svr;
+    let db;
+    if (opts?.serverOp && opts?.db) {
+        svr = opts.serverOp;
+        db = opts.db;
+    }
+    else {
+        try {
+            const harper = await import("@harperfast/harper");
+            svr = opts?.serverOp ?? harper.server.operation;
+            db = opts?.db ?? harper.databases;
+        }
+        catch (err) {
+            console.error("[federation-cleanup] failed to load @harperfast/harper:", err?.message ?? err);
+            return;
+        }
+    }
+    const role = opts?.instanceRole !== undefined
+        ? opts.instanceRole
+        : await getInstanceRole(db);
+    if (role !== "hub") {
+        console.log("[federation-cleanup] not a hub instance — cleanup disabled");
+        return;
+    }
+    console.log("[federation-cleanup] starting cleanup sweep (5-min cadence)");
+    if (cleanupTimer)
+        clearInterval(cleanupTimer);
+    cleanupTimer = setInterval(() => {
+        runCleanupTick({ serverOp: svr, db }).catch((err) => {
+            console.error("[federation-cleanup] tick error:", err?.message ?? err);
+        });
+    }, CLEANUP_INTERVAL_MS);
+    if (immediate) {
+        // Run an immediate first tick after role detection
+        runCleanupTick({ serverOp: svr, db }).catch((err) => {
+            console.error("[federation-cleanup] initial tick error:", err?.message ?? err);
+        });
+    }
+}
+/**
+ * Look up the instance role from the Instance table.
+ * Returns null if the table doesn't exist or no record is present.
+ */
+async function getInstanceRole(db) {
+    try {
+        for await (const inst of db.flair.Instance.search()) {
+            return inst.role ?? null;
+        }
+    }
+    catch {
+        /* table may not exist yet */
+    }
+    return null;
+}
+/**
+ * Core cleanup logic — exposed for unit testing.
+ *
+ * - Finds PairingToken records that are:
+ *   - consumedBy is non-null (pair succeeded, bootstrap user no longer needed)
+ *   - OR expiresAt < now (token expired without successful pair)
+ * - Drops the bootstrap user via the Harper ops API (idempotent: 404 is
+ *   swallowed).
+ * - Deletes the PairingToken record if expired AND not consumed
+ *   (housekeeping). Consumed records are kept for audit.
+ *
+ * Logging emits token-id prefix only (NEVER the full username, NEVER a
+ * password).
+ */
+export async function runCleanupTick(opts = {}) {
+    let svr;
+    let db;
+    if (opts.serverOp && opts.db) {
+        svr = opts.serverOp;
+        db = opts.db;
+    }
+    else {
+        const harper = await import("@harperfast/harper");
+        svr = opts.serverOp ?? harper.server.operation;
+        db = opts.db ?? harper.databases;
+    }
+    const now = opts.now ?? new Date();
+    // ── Query candidates ──────────────────────────────────────────────────
+    const candidates = [];
+    try {
+        for await (const token of db.flair.PairingToken.search()) {
+            const consumed = !!token.consumedBy;
+            const expired = token.expiresAt && new Date(token.expiresAt) < now;
+            if (consumed || expired) {
+                candidates.push(token);
+            }
+        }
+    }
+    catch (err) {
+        console.error("[federation-cleanup] failed to query PairingToken records:", err?.message ?? err);
+        return;
+    }
+    // ── Process each candidate ────────────────────────────────────────────
+    for (const token of candidates) {
+        const tokenId = token.id;
+        const consumed = !!token.consumedBy;
+        const expired = token.expiresAt && new Date(token.expiresAt) < now;
+        const bootstrapUsername = `pair-bootstrap-${tokenId.slice(0, 8)}`;
+        // Drop the bootstrap user
+        try {
+            await svr({ operation: "drop_user", username: bootstrapUsername }, { user: null }, false);
+            console.log("[federation-cleanup] dropped user", { tid: tokenId.slice(0, 8) });
+        }
+        catch (err) {
+            const msg = err?.message ?? "";
+            const isNotFound = err?.statusCode === 404 ||
+                msg.toLowerCase().includes("not exist") ||
+                msg.toLowerCase().includes("not found");
+            if (isNotFound) {
+                // Idempotent — user already gone, no action needed
+            }
+            else {
+                console.error("[federation-cleanup] drop_user error", { tid: tokenId.slice(0, 8), err: String(err?.message ?? err) });
+            }
+        }
+        // ── Housekeeping ────────────────────────────────────────────────────
+        if (expired && !consumed) {
+            // Delete the expired, unconsumed token record itself
+            try {
+                await svr({
+                    operation: "delete",
+                    database: "flair",
+                    table: "PairingToken",
+                    hash_value: tokenId,
+                }, { user: null }, false);
+                console.log("[federation-cleanup] deleted expired token", { tid: tokenId.slice(0, 8) });
+            }
+            catch (err) {
+                console.error("[federation-cleanup] delete token error", { tid: tokenId.slice(0, 8), err: String(err?.message ?? err) });
+            }
+        }
+        // Consumed tokens: keep record for audit trail
+        if (consumed) {
+            console.log("[federation-cleanup] keeping audit record", { tid: tokenId.slice(0, 8), consumedBy: token.consumedBy });
+        }
+    }
+}

package/dist/resources/federation-crypto.js

@@ -22,10 +22,106 @@ function sortKeys(val) {
     }
     return sorted;
 }
-// ─── Signing ────────────────────────────────────────────────────────────────
+// ─── Nonce generation ───────────────────────────────────────────────────────
+/**
+ * Generate a random nonce for anti-replay protection.
+ * 16 random bytes → base64url (22 chars, no padding). 128 bits of entropy
+ * is sufficient for collision-resistance over the signing window.
+ */
+export function generateNonce() {
+    return Buffer.from(nacl.randomBytes(16)).toString("base64url");
+}
+/**
+ * Default in-memory nonce store backed by a Map.
+ * Safe for module-level singleton use (e.g. federationNonceStore).
+ */
+export function createNonceStore() {
+    const store = new Map();
+    return {
+        has(key) { return store.has(key); },
+        set(key, value) { store.set(key, value); },
+        evict(olderThan) {
+            for (const [k, ts] of store.entries()) {
+                if (ts < olderThan)
+                    store.delete(k);
+            }
+        },
+    };
+}
+/**
+ * Sign a request body with embedded timestamp and nonce for anti-replay.
+ *
+ * Adds `_ts` and `_nonce` fields to the body, then signs the canonical form
+ * (including those fields) using the existing `signBody`. Returns the body
+ * with `_ts`, `_nonce`, and `signature` fields set.
+ *
+ * The caller sends the returned body as the JSON payload. The receiver
+ * uses `verifyBodySignatureFresh` to validate it.
+ */
+export function signBodyFresh(body, secretKey, opts) {
+    const tsBody = {
+        ...body,
+        _ts: opts?.ts ?? Date.now(),
+        _nonce: opts?.nonce ?? generateNonce(),
+    };
+    const sig = signBody(tsBody, secretKey);
+    return { ...tsBody, signature: sig };
+}
+/**
+ * Verify a signed request body with anti-replay protection.
+ *
+ * 1. Validates the Ed25519 signature over the canonical form (including
+ *    `_ts`, `_nonce`, and all other fields EXCEPT `signature`).
+ * 2. Checks that the embedded `_ts` is within `opts.windowMs` of now.
+ * 3. Checks that the embedded `_nonce` has not been seen before (replay).
+ * 4. Records the nonce on success.
+ *
+ * Returns `{ ok: true }` on success, or `{ ok: false, reason: "..." }`.
+ */
+export function verifyBodySignatureFresh(body, publicKeyB64url, opts = {}) {
+    const windowMs = opts.windowMs ?? 30_000;
+    const nonceStore = opts.nonceStore;
+    const { signature, _ts, _nonce, ...rest } = body;
+    // ── Field presence ───────────────────────────────────────────────────
+    if (!signature)
+        return { ok: false, reason: "invalid_signature" };
+    if (_ts == null || !Number.isFinite(_ts))
+        return { ok: false, reason: "invalid_signature" };
+    if (!_nonce || typeof _nonce !== "string")
+        return { ok: false, reason: "invalid_signature" };
+    // ── Timestamp check ──────────────────────────────────────────────────
+    const now = Date.now();
+    const delta = now - _ts;
+    if (delta > windowMs)
+        return { ok: false, reason: "stale" };
+    if (delta < -windowMs)
+        return { ok: false, reason: "future" };
+    // ── Nonce replay check ───────────────────────────────────────────────
+    if (nonceStore) {
+        // Evict entries older than 2x window — keeps the store bounded
+        nonceStore.evict(now - 2 * windowMs);
+        if (nonceStore.has(_nonce))
+            return { ok: false, reason: "replay" };
+    }
+    // ── Signature verification — canonical form includes _ts, _nonce ─────
+    const verificationBody = { _ts, _nonce, ...rest, signature };
+    if (!verifyBodySignature(verificationBody, publicKeyB64url)) {
+        return { ok: false, reason: "invalid_signature" };
+    }
+    // ── Record nonce ─────────────────────────────────────────────────────
+    if (nonceStore) {
+        nonceStore.set(_nonce, now);
+    }
+    return { ok: true };
+}
+// ─── Legacy signing (without anti-replay) ────────────────────────────────────
+// Kept as implementation detail for signBodyFresh / verifyBodySignatureFresh.
+// Callers should use the fresh variants for replay-safe federation operations.
 /**
  * Create a detached Ed25519 signature over the canonical form of a body.
  * Returns base64url-encoded signature.
+ *
+ * NOTE: Prefer `signBodyFresh()` which includes anti-replay metadata (_ts, _nonce).
  */
 export function signBody(body, secretKey) {
     const message = new TextEncoder().encode(canonicalize(body));
@@ -35,6 +131,9 @@ export function signBody(body, secretKey) {
 /**
  * Verify a signature field on a request body.
  * The canonical form is the body WITHOUT the `signature` field.
+ *
+ * NOTE: Prefer `verifyBodySignatureFresh()` which adds timestamp and nonce
+ * replay protection. This function performs ONLY signature validation.
  */
 export function verifyBodySignature(body, publicKeyB64url) {
     const { signature, ...rest } = body;

package/dist/resources/health.js

@@ -150,7 +150,7 @@ export class HealthDetail extends Resource {
             const perAgentFull = Array.from(perAgentMap.values()).sort((a, b) => b.memoryCount - a.memoryCount);
             const perAgent = isAdmin
                 ? perAgentFull
-                : perAgentFull.filter((r) => r.id === callerAgent);
+                : perAgentFull.filter((r) => r.id === callerAgent || r.memoryCount > 0);
             stats.agents = {
                 count: agents.length,
                 names: isAdmin ? agents.map((a) => a.id).filter(Boolean) : undefined,

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.6.2",
+  "version": "0.8.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",
   "repository": {
     "type": "git",
-    "url": "https://github.com/tpsdev-ai/flair.git"
+    "url": "git+https://github.com/tpsdev-ai/flair.git"
   },
   "homepage": "https://github.com/tpsdev-ai/flair",
   "bugs": {
@@ -44,7 +44,8 @@
     "prepublishOnly": "npm run build && npm run build:cli",
     "test": "bun test",
     "test:e2e": "playwright test",
-    "release": "./scripts/release.sh"
+    "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)}\""
   },
   "publishConfig": {
     "access": "public"
@@ -53,17 +54,19 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@harperfast/harper": "5.0.1",
+    "@harperfast/harper": "5.0.9",
     "@types/js-yaml": "^4.0.9",
     "commander": "14.0.3",
     "harper-fabric-embeddings": "0.2.3",
     "jose": "^6.2.2",
     "js-yaml": "^4.1.1",
+    "tar": "^7.5.13",
     "tweetnacl": "1.0.3"
   },
   "devDependencies": {
     "@playwright/test": "^1.59.1",
     "@types/node": "24.11.0",
+    "@types/tar": "^7.0.87",
     "bun-types": "1.3.11",
     "typescript": "5.9.3"
   },
@@ -71,7 +74,6 @@
     "harper-fabric-embeddings"
   ],
   "workspaces": [
-    "packages/*",
-    "plugins/*"
+    "packages/*"
   ]
 }

package/schemas/memory.graphql

@@ -26,6 +26,8 @@ type Memory @table(database: "flair") {
   lastReflected: String     # ISO timestamp of last reflection pass
   supersedes: String @indexed  # ID of memory this one replaces (version chain)
   subject: String @indexed     # entity this memory is about (person, service, project)
+  summary: String              # agent-set multi-sentence dense compression (optional; ops-wkoh)
+                               # 3-tier compression chain: subject (one-line) → summary (paragraph) → content (full)
   validFrom: String @indexed   # ISO timestamp — when this fact became true
   validTo: String @indexed     # ISO timestamp — when this fact stopped being true (null = still valid)
   _safetyFlags: [String]       # content safety flags from scanContent()
@@ -68,3 +70,29 @@ type MemoryGrant @table(database: "flair") @export {
   filter: String
   createdAt: String
 }
+
+# MemoryCandidate — staged distillations from the FLAIR-NIGHTLY-REM cycle.
+# Per specs/FLAIR-NIGHTLY-REM.md § 7. Slice 1 of ops-2qq adds the schema +
+# `flair rem candidates` listing command. Future slices wire the nightly
+# cycle that populates this table and the promote/reject endpoints.
+#
+# Inviolable contract: candidates are NEVER auto-promoted. Promotion is a
+# separate, deliberate action (`flair rem promote <id> --rationale "<why>"`)
+# that requires both --rationale and --to (soul|memory). Rejected candidates
+# retain their decision history so recurring false-positives become visible
+# via the `supersedes` chain.
+type MemoryCandidate @table(database: "flair") {
+  id: ID @primaryKey
+  agentId: String! @indexed
+  claim: String!                   # distilled lesson text
+  sourceMemoryIds: [String]        # episodic memories feeding the distillation
+  rationalePrompt: String          # the prompt given to the distillation LLM
+  generatedBy: String              # model identifier (e.g. "claude-opus-4-7")
+  generatedAt: String! @indexed
+  status: String! @indexed         # pending | promoted | rejected
+  target: String                   # soul | memory (set on promote)
+  reviewerId: String               # who decided (agentId or human admin)
+  reviewRationale: String          # required on promote/reject (no rubber-stamp)
+  decidedAt: String
+  supersedes: String @indexed      # previous rejected candidate this replaces
+}