@tpsdev-ai/flair 0.7.0 → 0.8.0

package/dist/resources/Federation.js

@@ -1,9 +1,14 @@
-import { Resource, databases } from "@harperfast/harper";
+import { Resource, databases, server } from "@harperfast/harper";
 import { randomBytes } from "node:crypto";
 import nacl from "tweetnacl";
-import { canonicalize, signBody, verifyBodySignature } from "./federation-crypto.js";
+import { canonicalize, signBody, verifyBodySignature, signBodyFresh, verifyBodySignatureFresh, createNonceStore, generateNonce, } from "./federation-crypto.js";
+import { initFederationCleanup } from "./federation-cleanup.js";
+// Module-level nonce store for federation anti-replay.
+// Shared across FederationPair + FederationSync — nonces are globally unique
+// (generated by signBodyFresh per request with 128-bit random nonces).
+const federationNonceStore = createNonceStore();
 // Re-export for consumers that import from Federation.ts
-export { canonicalize, signBody, verifyBodySignature };
+export { canonicalize, signBody, verifyBodySignature, signBodyFresh, verifyBodySignatureFresh, generateNonce };
 // ─── Conflict resolution ─────────────────────────────────────────────────────
 /**
  * Field-level Last-Write-Wins merge.
@@ -97,15 +102,21 @@ export class FederationPair extends Resource {
                 status: 400, headers: { "content-type": "application/json" },
             });
         }
-        // Verify signature — the pairing body must be signed with the private key
-        // corresponding to the publicKey in the body (proves key ownership).
+        // Verify request signature against the public key (proves key ownership).
+        // Uses fresh verification with anti-replay — even though pair has implicit
+        // replay protection via single-use pairingToken, explicit anti-replay is
+        // defense-in-depth and keeps signature semantics consistent across endpoints.
         if (!signature) {
             return new Response(JSON.stringify({ error: "signature required — request must be signed" }), {
                 status: 401, headers: { "content-type": "application/json" },
             });
         }
-        if (!verifyBodySignature(data, publicKey)) {
-            return new Response(JSON.stringify({ error: "invalid signature — key ownership proof failed" }), {
+        const verifyResult = verifyBodySignatureFresh(data, publicKey, {
+            windowMs: 30_000,
+            nonceStore: federationNonceStore,
+        });
+        if (!verifyResult.ok) {
+            return new Response(JSON.stringify({ error: `invalid signature — ${verifyResult.reason}` }), {
                 status: 401, headers: { "content-type": "application/json" },
             });
         }
@@ -152,6 +163,18 @@ export class FederationPair extends Resource {
                     status: 401, headers: { "content-type": "application/json" },
                 });
             }
+            // PR-4: bind authenticated bootstrap user to specific pairing token
+            const ctx = this.getContext?.() ?? {};
+            const authedUser = ctx.request?.tpsAgent;
+            const isAdmin = ctx.request?.tpsAgentIsAdmin === true;
+            if (!isAdmin && authedUser) {
+                const expectedBootstrap = `pair-bootstrap-${pairingToken.slice(0, 8)}`;
+                if (authedUser !== expectedBootstrap) {
+                    return new Response(JSON.stringify({
+                        error: "bootstrap_user_token_mismatch",
+                    }), { status: 401, headers: { "content-type": "application/json" } });
+                }
+            }
             // Consume the token
             await databases.flair.PairingToken.put({
                 ...tokenRecord,
@@ -169,6 +192,15 @@ export class FederationPair extends Resource {
                 createdAt: new Date().toISOString(),
                 updatedAt: new Date().toISOString(),
             });
+            // Drop the bootstrap user that was created alongside this pairing token.
+            // Failure here is non-fatal: the cleanup sweep (PR-5) will catch stragglers.
+            try {
+                const bootstrapUsername = `pair-bootstrap-${pairingToken.slice(0, 8)}`;
+                await server.operation({ operation: "drop_user", username: bootstrapUsername }, ctx, false);
+            }
+            catch (err) {
+                console.warn(`[federation] drop_user failed: ${err?.message} — cleanup sweep will retry`);
+            }
         }
         // Return our own identity for the peer to record
         let ourInstance = null;
@@ -196,6 +228,12 @@ export class FederationPair extends Resource {
  * The calling peer sends a batch of SyncRecords; we merge them.
  */
 export class FederationSync extends Resource {
+    // Public endpoint by design: spokes have no Harper credentials. Body signature
+    // (with timestamp + nonce, via verifyBodySignatureFresh) is the auth boundary.
+    // Same pattern as FederationPair.
+    allowCreate(_user, _record, _context) {
+        return true;
+    }
     async post(data) {
         const { instanceId, records, lamportClock, signature } = data || {};
         if (!instanceId || !Array.isArray(records)) {
@@ -210,14 +248,20 @@ export class FederationSync extends Resource {
                 status: 403, headers: { "content-type": "application/json" },
             });
         }
-        // Verify request signature against peer's pinned public key
+        // Verify request signature against peer's pinned public key.
+        // Fresh verification with anti-replay — prevents captured signatures from
+        // being replayed across the timestamp window.
         if (!signature) {
             return new Response(JSON.stringify({ error: "signature required — sync requests must be signed" }), {
                 status: 401, headers: { "content-type": "application/json" },
             });
         }
-        if (!verifyBodySignature(data, peer.publicKey)) {
-            return new Response(JSON.stringify({ error: "invalid signature — request not from claimed peer" }), {
+        const verifyResult = verifyBodySignatureFresh(data, peer.publicKey, {
+            windowMs: 30_000,
+            nonceStore: federationNonceStore,
+        });
+        if (!verifyResult.ok) {
+            return new Response(JSON.stringify({ error: `invalid signature — ${verifyResult.reason}` }), {
                 status: 401, headers: { "content-type": "application/json" },
             });
         }
@@ -319,3 +363,16 @@ export class FederationPeers extends Resource {
         return { peers };
     }
 }
+// ── Module initialisation ────────────────────────────────────────────────────
+// Deferred: the cleanup sweep (PR-5) starts after the module graph resolves.
+// In unit test environments (no Harper runtime), setTimeout never fires
+// synchronously and import is safe. In the live Harper process, the sweep
+// will start on the next event loop tick and runs only on hub instances.
+if (typeof setTimeout !== "undefined") {
+    setTimeout(() => {
+        initFederationCleanup().catch((err) => {
+            // Swallow — in test/resource-env the Harper databases may not be bound.
+            // In production, initFederationCleanup handles its own error paths.
+        });
+    }, 0);
+}

package/dist/resources/Memory.js

@@ -2,7 +2,7 @@ import { databases } from "@harperfast/harper";
 import { patchRecord, withDetachedTxn } from "./table-helpers.js";
 import { isAdmin } from "./auth-middleware.js";
 import { getEmbedding, getModelId } from "./embeddings-provider.js";
-import { scanContent, isStrictMode } from "./content-safety.js";
+import { scanFields, isStrictMode } from "./content-safety.js";
 import { checkRateLimit, rateLimitResponse } from "./rate-limiter.js";
 export class Memory extends databases.flair.Memory {
     /**
@@ -41,25 +41,17 @@ export class Memory extends databases.flair.Memory {
         const agentIdCondition = allowedOwners.length === 1
             ? { attribute: "agentId", comparator: "equals", value: allowedOwners[0] }
             : { conditions: allowedOwners.map(id => ({ attribute: "agentId", comparator: "equals", value: id })), operator: "or" };
-        // Harper passes `query` as a RequestTarget (extends URLSearchParams). Table.search()
-        // reads `target.conditions`; when that is unset, it iterates URLSearchParams entries
-        // as conditions instead. We inject our scope condition into `.conditions`, which
-        // means URL params (except agentId, which we always enforce) must also be translated
-        // to conditions or they'll be silently dropped.
+        // Harper passes `query` as a RequestTarget (extends URLSearchParams) or a
+        // conditions array. For URL-based GET /Memory?... calls, URL params are no
+        // longer translated to conditions here — callers should use
+        // POST /Memory/search_by_conditions with an explicit conditions array.
+        // For programmatic calls with a conditions array, we wrap with the agentId scope.
         if (query && typeof query === "object" && !Array.isArray(query)) {
-            const existing = [];
             if (Array.isArray(query.conditions) && query.conditions.length > 0) {
-                existing.push(...query.conditions);
+                query.conditions = [agentIdCondition, ...query.conditions];
+                return withDetachedTxn(ctx, () => super.search(query));
             }
-            else if (typeof query.entries === "function") {
-                for (const [k, v] of query.entries()) {
-                    if (k === "agentId")
-                        continue;
-                    existing.push({ attribute: k, comparator: "equals", value: v });
-                }
-            }
-            query.conditions = [agentIdCondition, ...existing];
-            return withDetachedTxn(ctx, () => super.search(query));
+            // Fallback: no conditions array present — just scope and pass through
         }
         // Fallback: plain array or no query (internal calls)
         const conditions = Array.isArray(query) && query.length > 0
@@ -114,9 +106,10 @@ export class Memory extends databases.flair.Memory {
             const ttlHours = Number(process.env.FLAIR_EPHEMERAL_TTL_HOURS || 24);
             content.expiresAt = new Date(Date.now() + ttlHours * 3600_000).toISOString();
         }
-        // Content safety scan
-        if (content.content) {
-            const safety = scanContent(content.content);
+        // Content safety scan — covers content + summary (defense-in-depth for
+        // agent-set summaries, ops-i2jb).
+        if (content.content || content.summary) {
+            const safety = scanFields(content, ["content", "summary"]);
             if (!safety.safe) {
                 if (isStrictMode()) {
                     return new Response(JSON.stringify({
@@ -163,9 +156,9 @@ export class Memory extends databases.flair.Memory {
         // Set defaults that post() sets — put() is also used for new records via CLI
         content.archived = content.archived ?? false;
         content.createdAt = content.createdAt ?? now;
-        // Content safety scan on updated content
-        if (content.content) {
-            const safety = scanContent(content.content);
+        // Content safety scan on updated content + summary (ops-i2jb).
+        if (content.content || content.summary) {
+            const safety = scanFields(content, ["content", "summary"]);
             if (!safety.safe) {
                 if (isStrictMode()) {
                     return new Response(JSON.stringify({
@@ -177,7 +170,7 @@ export class Memory extends databases.flair.Memory {
                 content._safetyFlags = safety.flags;
             }
             else {
-                // Clear previous flags if content is now clean
+                // Clear previous flags if both fields are now clean
                 content._safetyFlags = null;
             }
         }

package/dist/resources/MemoryBootstrap.js

@@ -82,6 +82,7 @@ export class BootstrapMemories extends Resource {
         let tokenBudget = maxTokens;
         let memoriesIncluded = 0;
         let memoriesAvailable = 0;
+        let memoriesTruncated = 0;
         // --- 1. Soul records (budgeted — prioritized by key importance) ---
         // Soul is who you are, but we still need to respect token budgets.
         // Workspace files (SOUL.md, AGENTS.md) can be massive — they're already
@@ -189,6 +190,9 @@ export class BootstrapMemories extends Resource {
                 tokenBudget -= cost;
                 memoriesIncluded++;
             }
+            else {
+                memoriesTruncated++;
+            }
         }
         // --- 3. Recent memories (adaptive window) ---
         // Start with 48h. If nothing found, widen to 7d, then 30d.
@@ -217,8 +221,10 @@ export class BootstrapMemories extends Resource {
         for (const m of recent) {
             const line = formatMemory(m);
             const cost = estimateTokens(line);
-            if (recentSpent + cost > recentBudget)
+            if (recentSpent + cost > recentBudget) {
+                memoriesTruncated++;
                 continue;
+            }
             sections.recent.push(line);
             recentSpent += cost;
             tokenBudget -= cost;
@@ -249,8 +255,10 @@ export class BootstrapMemories extends Resource {
             for (const m of subjectMemories) {
                 const line = formatMemory(m);
                 const cost = estimateTokens(line);
-                if (predictedSpent + cost > predictedBudget)
+                if (predictedSpent + cost > predictedBudget) {
+                    memoriesTruncated++;
                     continue;
+                }
                 sections.predicted.push(line);
                 predictedSpent += cost;
                 tokenBudget -= cost;
@@ -401,6 +409,7 @@ export class BootstrapMemories extends Resource {
             memoryTokens,
             memoriesIncluded,
             memoriesAvailable,
+            memoriesTruncated,
         };
     }
 }

package/dist/resources/auth-middleware.js

@@ -117,7 +117,8 @@ server.http(async (request, nextLayer) => {
         url.pathname === "/AgentCard" ||
         url.pathname.startsWith("/A2AAdapter/") ||
         url.pathname.startsWith("/AgentCard/") ||
-        // FederationSync uses Ed25519 body-signature auth (handled by the resource)
+        // FederationSync uses Ed25519 body-signature auth with anti-replay, validated
+        // by the resource handler (allowCreate=true, same pattern as FederationPair).
         url.pathname === "/FederationSync" ||
         // FederationPair uses one-time PairingToken in the request body, validated
         // by the resource itself (allowCreate=true on the Resource lets anonymous
@@ -191,6 +192,27 @@ server.http(async (request, nextLayer) => {
                 request.tpsAgentIsAdmin = true;
                 return nextLayer(request);
             }
+            // Path 3: flair_pair_initiator — restricted to /FederationPair only.
+            // Bootstrap credentials (pair-bootstrap-<id>) may only be used on this
+            // one endpoint. Any other path must fall through to 401.
+            if (url.pathname === "/FederationPair" && user.startsWith("pair-bootstrap-")) {
+                let pairUser = null;
+                try {
+                    pairUser = await server.getUser(user, pass, request);
+                }
+                catch { /* fall through */ }
+                if (pairUser?.role?.role === "flair_pair_initiator" &&
+                    pairUser?.active === true) {
+                    request._tpsAuthVerified = true;
+                    request.user = pairUser;
+                    request.headers.set("x-tps-agent", user);
+                    if (request.headers.asObject)
+                        request.headers.asObject["x-tps-agent"] = user;
+                    request.tpsAgent = user;
+                    request.tpsAgentIsAdmin = false;
+                    return nextLayer(request);
+                }
+            }
         }
         catch { /* fall through to Ed25519 check */ }
         return new Response(JSON.stringify({ error: "invalid_admin_credentials" }), { status: 401 });

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/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.7.0",
+  "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,7 +54,7 @@
     "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",
@@ -73,7 +74,6 @@
     "harper-fabric-embeddings"
   ],
   "workspaces": [
-    "packages/*",
-    "plugins/*"
+    "packages/*"
   ]
 }