@tpsdev-ai/flair 0.20.0 → 0.21.0

package/dist/version-check.js

@@ -0,0 +1,167 @@
+/**
+ * version-check.ts — offline-tolerant, cached check of whether the installed
+ * @tpsdev-ai/flair is behind the latest published npm release.
+ *
+ * Motivation (flair#587): a laptop install sat on 0.16.1 through v0.17.0 and
+ * v0.19.0 (P0 security fixes) and v0.18.0 (memory-integrity fix) — `flair
+ * status` reported "✓ all checks passing" the whole time. Nothing anywhere
+ * in the CLI told the operator they were behind. `flair status` and `flair
+ * doctor` both wire this in.
+ *
+ * Non-negotiable design constraints — this must never make status/doctor
+ * WORSE:
+ *   - Offline-tolerant: a failed/timed-out registry fetch falls back to a
+ *     stale cache, or is skipped entirely. NEVER throws, NEVER hangs (short
+ *     fetch timeout).
+ *   - Cached with a TTL so a healthy network doesn't cost a registry round
+ *     trip on every single `flair status`/`flair doctor` invocation.
+ *   - No advisory data — we don't know which release fixed which CVE, so the
+ *     severity heuristic is purely the version GAP (major/minor count), not
+ *     "did this release carry a security fix". See classifyGap().
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { parseSemverCore } from "./fabric-upgrade.js";
+export const FLAIR_PKG_NAME = "@tpsdev-ai/flair";
+export const DEFAULT_CACHE_PATH = join(homedir(), ".flair", ".version-check-cache.json");
+/** How long a cached "latest" answer is trusted before we re-hit the registry. */
+export const DEFAULT_TTL_MS = 12 * 60 * 60 * 1000; // 12h
+/** Registry fetch timeout — this runs on every status/doctor call, so it must stay short. */
+export const DEFAULT_TIMEOUT_MS = 3000;
+function readCacheFile(path) {
+    try {
+        if (!existsSync(path))
+            return null;
+        const raw = JSON.parse(readFileSync(path, "utf-8"));
+        if (typeof raw?.latest === "string" && typeof raw?.checkedAt === "number") {
+            return { latest: raw.latest, checkedAt: raw.checkedAt };
+        }
+        return null;
+    }
+    catch {
+        // Corrupt/unreadable cache — treat as absent, never throw.
+        return null;
+    }
+}
+function writeCacheFile(path, entry) {
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, JSON.stringify(entry), "utf-8");
+    }
+    catch {
+        // Best-effort — a cache-write failure must never surface as a
+        // status/doctor error (e.g. read-only $HOME).
+    }
+}
+async function defaultFetchLatest(timeoutMs) {
+    try {
+        const res = await fetch(`https://registry.npmjs.org/${FLAIR_PKG_NAME}/latest`, {
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!res.ok)
+            return null;
+        const data = (await res.json());
+        return typeof data?.version === "string" ? data.version : null;
+    }
+    catch {
+        // Offline, DNS failure, timeout, registry 5xx, bad JSON — all the same:
+        // we couldn't determine "latest" over the network this time.
+        return null;
+    }
+}
+export function defaultVersionCheckDeps() {
+    return {
+        fetchLatest: defaultFetchLatest,
+        cachePath: DEFAULT_CACHE_PATH,
+        ttlMs: DEFAULT_TTL_MS,
+        timeoutMs: DEFAULT_TIMEOUT_MS,
+        now: () => Date.now(),
+        readCache: readCacheFile,
+        writeCache: writeCacheFile,
+    };
+}
+/**
+ * Resolve the latest published @tpsdev-ai/flair version, preferring a fresh
+ * cache hit over a network round trip, and falling back to a stale cache (or
+ * giving up quietly) when the registry is unreachable. NEVER throws.
+ */
+export async function checkVersion(installed, injected = {}) {
+    const deps = { ...defaultVersionCheckDeps(), ...injected };
+    const nowMs = deps.now();
+    const cached = deps.readCache(deps.cachePath);
+    if (cached && nowMs - cached.checkedAt < deps.ttlMs) {
+        return { installed, latest: cached.latest, source: "cache" };
+    }
+    // Defense-in-depth: the default fetchLatest already catches everything
+    // internally (network error, timeout, non-2xx, bad JSON) and resolves
+    // null rather than rejecting. This try/catch guards the contract even if
+    // a caller-injected fetchLatest misbehaves and throws/rejects instead —
+    // status/doctor must never crash or hang on a version check either way.
+    let fetched = null;
+    try {
+        fetched = await deps.fetchLatest(deps.timeoutMs);
+    }
+    catch {
+        fetched = null;
+    }
+    if (fetched) {
+        deps.writeCache(deps.cachePath, { latest: fetched, checkedAt: nowMs });
+        return { installed, latest: fetched, source: "network" };
+    }
+    // Registry unreachable/timed out — fall back to a stale cache rather than
+    // reporting nothing, but never block or throw trying to get a fresh one.
+    if (cached) {
+        return { installed, latest: cached.latest, source: "cache" };
+    }
+    return { installed, latest: null, source: "unavailable" };
+}
+const NO_GAP = { severity: "none", majorBehind: false, releasesBehind: 0 };
+/**
+ * Classify how far `installed` is behind `latest` using major.minor.patch
+ * math only — we don't have advisory data, so:
+ *   - any major version behind, or ≥2 minor versions behind → "red" (loud;
+ *     heuristic for "you've likely missed a security fix")
+ *   - a single minor version behind, or a patch-only gap → "yellow"
+ *   - equal, ahead, or unparseable → "none"
+ */
+export function classifyGap(installed, latest) {
+    const a = parseSemverCore(installed);
+    const b = parseSemverCore(latest);
+    if (!a || !b)
+        return NO_GAP;
+    const [aMaj, aMin, aPatch] = a;
+    const [bMaj, bMin, bPatch] = b;
+    if (bMaj > aMaj)
+        return { severity: "red", majorBehind: true, releasesBehind: 0 };
+    if (bMaj < aMaj)
+        return NO_GAP; // installed is ahead (e.g. local/pre-release build)
+    if (bMin > aMin) {
+        const releasesBehind = bMin - aMin;
+        return { severity: releasesBehind >= 2 ? "red" : "yellow", majorBehind: false, releasesBehind };
+    }
+    if (bMin < aMin)
+        return NO_GAP; // ahead on minor
+    if (bPatch > aPatch)
+        return { severity: "yellow", majorBehind: false, releasesBehind: bPatch - aPatch };
+    return NO_GAP; // equal, or ahead on patch
+}
+/**
+ * Build the human-readable nudge line for `flair status`/`flair doctor`, or
+ * null when there's nothing worth printing — current, ahead (local/dev
+ * build), or we couldn't determine latest at all (offline with no cache).
+ * Callers own icon/color; this returns plain text plus a severity to color by.
+ */
+export function formatVersionNudge(result) {
+    if (!result.latest)
+        return null;
+    const gap = classifyGap(result.installed, result.latest);
+    if (gap.severity === "none")
+        return null;
+    const countHint = gap.majorBehind
+        ? "major version"
+        : `${gap.releasesBehind} release${gap.releasesBehind === 1 ? "" : "s"}`;
+    const message = `flair ${result.installed} is behind — latest is ${result.latest} (${countHint} behind). ` +
+        `Upgrade: npm i -g ${FLAIR_PKG_NAME}@latest`;
+    return { severity: gap.severity, message };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.20.0",
+  "version": "0.21.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,7 +55,7 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@harperfast/harper": "5.1.14",
+    "@harperfast/harper": "5.1.15",
     "@harperfast/oauth": "2.1.0",
     "@types/js-yaml": "4.0.9",
     "commander": "14.0.3",

package/schemas/agent.graphql

@@ -22,6 +22,13 @@ type Agent @table(database: "flair") @export {
 
   createdAt: String!
   updatedAt: String
+  originatorInstanceId: String @indexed  # federation-edge-hardening slice 1 — write-time instance identity,
+                                   # stamped server-side in resources/Agent.ts's post()/put() from
+                                   # resources/instance-identity.ts's localInstanceId(). Nullable (existing rows
+                                   # read null = clean upgrade); preserved (never re-stamped) as the record flows
+                                   # through federation sync merges. See schemas/memory.graphql's Memory.
+                                   # originatorInstanceId for the full contract — same field, same idiom, this is
+                                   # one of the 4 synced tables (Memory/Soul/Agent/Relationship).
 }
 
 # Credential table — auth surfaces for Principals.

package/schemas/federation.graphql

@@ -39,6 +39,18 @@ type Peer @table(database: "flair") @export {
   updatedAt: String
 }
 
+# Anti-replay nonce store (federation-edge-hardening slice 4).
+# Persists nonces recorded by verifyBodySignatureFresh (federation-crypto.ts)
+# so an instance restart doesn't wipe recently-seen nonces — closes the
+# ±30s freshness-window replay gap a restart would otherwise reopen. Nonces
+# are already globally unique (128-bit random, generated per request by
+# signBodyFresh), so the nonce string itself is the primary key — no scope
+# prefix needed. Internal bookkeeping only: never served, never replicated.
+type Nonce @table(database: "flair") {
+  id: ID @primaryKey               # the nonce string (base64url, 128-bit random)
+  seenAt: Int! @indexed            # ms-epoch when first recorded — eviction cutoff
+}
+
 # Sync log — audit trail for federation operations.
 type SyncLog @table(database: "flair") {
   id: ID @primaryKey

package/schemas/memory.graphql

@@ -31,6 +31,16 @@ type Memory @table(database: "flair") {
   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()
+  provenance: String           # JSON blob (memory-provenance slice 1): { v, verified: { agentId, timestamp }, claimed?: { model } }
+                               # Nullable by design — existing rows read back provenance = null, unchanged behavior (clean-upgrade-path gate).
+                               # Same idiom as Soul.metadata below. Stamped server-side in resources/Memory.ts; never client-writable.
+  originatorInstanceId: String @indexed  # federation-edge-hardening slice 1: WRITE-TIME instance identity, stamped server-side in
+                               # resources/Memory.ts from resources/instance-identity.ts's localInstanceId() — never client-writable.
+                               # Nullable (existing rows read null = clean upgrade). Distinct from the legacy _originatorInstanceId
+                               # (Federation.ts's mergeRecord — stamped by the RECEIVER at merge time, forgeable/lossy); this field is
+                               # stamped by the ORIGINATING instance itself and preserved (never re-stamped) as the record flows through
+                               # sync merges. @indexed for the later sync push-query filter (per-record signature verification and the
+                               # classifier org-gate are separate, later slices — not built here).
 }
 
 # Explicit entity-to-entity relationships with temporal validity.
@@ -48,6 +58,9 @@ type Relationship @table(database: "flair") {
   source: String                   # where this was learned (memory ID, conversation, etc.)
   createdAt: String! @indexed
   updatedAt: String
+  originatorInstanceId: String @indexed  # federation-edge-hardening slice 1 — see Memory.originatorInstanceId's doc above
+                                    # for the full contract (write-time stamp, nullable, preserved across sync merges).
+                                    # Stamped server-side in resources/Relationship.ts's put().
 }
 
 type Soul @table(database: "flair") {
@@ -60,6 +73,9 @@ type Soul @table(database: "flair") {
   durability: String @indexed
   createdAt: String!
   updatedAt: String
+  originatorInstanceId: String @indexed  # federation-edge-hardening slice 1 — see Memory.originatorInstanceId's doc above
+                                    # for the full contract (write-time stamp, nullable, preserved across sync merges).
+                                    # Stamped server-side in resources/Soul.ts's post()/put().
 }
 
 type MemoryGrant @table(database: "flair") @export {