@tpsdev-ai/flair 0.6.1 → 0.7.0

package/dist/install/clients.js

@@ -0,0 +1,225 @@
+// ─── Client Detection & Wiring ──────────────────────────────────────────────────────
+//
+// Detects locally installed MCP clients and wires them to Flair.
+// Each client has:
+//   - detect(): boolean - returns true if client is installed
+//   - wire(options: { agentId: string; flairUrl: string }): { ok: boolean; message: string }
+//
+// ---- Detection helpers ----------------------------------------------------------
+import { spawnSync } from "node:child_process";
+import { accessSync, constants } from "node:fs";
+/**
+ * Check if a command exists in PATH (cross-platform alternative to `which`).
+ * Does not spawn a child process — pure filesystem check.
+ */
+function binInPath(name) {
+    try {
+        const sep = process.platform === "win32" ? ";" : ":";
+        const dirs = (process.env.PATH || "").split(sep);
+        const exts = process.platform === "win32" ? [".exe", ".cmd", ".bat", ".ps1"] : [];
+        for (const dir of dirs) {
+            if (!dir)
+                continue;
+            const base = `${dir}/${name}`;
+            try {
+                accessSync(base, constants.X_OK);
+                return true;
+            }
+            catch { /* not here */ }
+            for (const ext of exts) {
+                try {
+                    accessSync(`${base}${ext}`, constants.X_OK);
+                    return true;
+                }
+                catch { /* not here */ }
+            }
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+function claudeCodeDetect() {
+    try {
+        const result = spawnSync("npm", ["list", "-g", "@anthropic-ai/claude-code"], {
+            stdio: ["ignore", "ignore", "ignore"],
+        });
+        return result.status === 0;
+    }
+    catch (_e) {
+        return false;
+    }
+}
+function codexDetect() {
+    try {
+        if (binInPath("codex"))
+            return true;
+        const npmResult = spawnSync("npm", ["list", "-g", "@openai/codex"], {
+            stdio: ["ignore", "ignore", "ignore"],
+        });
+        return npmResult.status === 0;
+    }
+    catch (_e) {
+        return false;
+    }
+}
+function geminiDetect() {
+    try {
+        if (binInPath("gemini"))
+            return true;
+        const npmResult = spawnSync("npm", ["list", "-g", "@google/generative-ai"], {
+            stdio: ["ignore", "ignore", "ignore"],
+        });
+        return npmResult.status === 0;
+    }
+    catch (_e) {
+        return false;
+    }
+}
+function cursorDetect() {
+    try {
+        return binInPath("cursor");
+    }
+    catch (_e) {
+        return false;
+    }
+}
+// ---- Internal wiring functions --------------------------------------------------
+function _wireClaudeCode(env) {
+    return {
+        ok: false,
+        message: `Manual wiring required for Claude Code:\n` +
+            `1. Locate Claude Code's settings file (usually ~/Library/Application Support/Claude/settings.json on macOS or %APPDATA%/Claude/settings.json on Windows)\n` +
+            `2. Add or update the "mcpServers" section:\n` +
+            `   {\n` +
+            `     "mcpServers": {\n` +
+            `       "flair": {\n` +
+            `         "command": "npx",\n` +
+            `         "args": ["-y", "@tpsdev-ai/flair-mcp"],\n` +
+            `         "env": {\n` +
+            `           "FLAIR_AGENT_ID": "${env.FLAIR_AGENT_ID}",\n` +
+            `           "FLAIR_URL": "${env.FLAIR_URL}"\n` +
+            `         }\n` +
+            `       }\n` +
+            `     }\n` +
+            `   }\n` +
+            `3. Restart Claude Code\n` +
+            `Note: This is a manual step - the Flair CLI cannot automatically modify Claude Code's settings due to security restrictions.`,
+    };
+}
+function _wireCodex(env) {
+    return {
+        ok: false,
+        message: `Manual wiring required for Codex:\n` +
+            `1. Locate Codex's configuration (check ~/.codex/config or similar)\n` +
+            `2. Add the Flair MCP server configuration:\n` +
+            `   {\n` +
+            `     "mcpServers": {\n` +
+            `       "flair": {\n` +
+            `         "command": "npx",\n` +
+            `         "args": ["-y", "@tpsdev-ai/flair-mcp"],\n` +
+            `         "env": {\n` +
+            `           "FLAIR_AGENT_ID": "${env.FLAIR_AGENT_ID}",\n` +
+            `           "FLAIR_URL": "${env.FLAIR_URL}"\n` +
+            `         }\n` +
+            `       }\n` +
+            `     }\n` +
+            `   }\n` +
+            `3. Restart Codex\n` +
+            `Note: This is a manual step - the Flair CLI cannot automatically modify Codex's configuration due to security restrictions.`,
+    };
+}
+function _wireGemini(env) {
+    return {
+        ok: false,
+        message: `Manual wiring required for Gemini:\n` +
+            `1. Locate Gemini's configuration (check ~/.gemini/config or similar)\n` +
+            `2. Add the Flair MCP server configuration:\n` +
+            `   {\n` +
+            `     "mcpServers": {\n` +
+            `       "flair": {\n` +
+            `         "command": "npx",\n` +
+            `         "args": ["-y", "@tpsdev-ai/flair-mcp"],\n` +
+            `         "env": {\n` +
+            `           "FLAIR_AGENT_ID": "${env.FLAIR_AGENT_ID}",\n` +
+            `           "FLAIR_URL": "${env.FLAIR_URL}"\n` +
+            `         }\n` +
+            `       }\n` +
+            `     }\n` +
+            `   }\n` +
+            `3. Restart Gemini\n` +
+            `Note: This is a manual step - the Flair CLI cannot automatically modify Gemini's configuration due to security restrictions.`,
+    };
+}
+function _wireCursor(env) {
+    return {
+        ok: false,
+        message: `Manual wiring required for Cursor:\n` +
+            `1. Locate Cursor's settings file (usually ~/.cursor/settings.json)\n` +
+            `2. Add or update the "mcpServers" section:\n` +
+            `   {\n` +
+            `     "mcpServers": {\n` +
+            `       "flair": {\n` +
+            `         "command": "npx",\n` +
+            `         "args": ["-y", "@tpsdev-ai/flair-mcp"],\n` +
+            `         "env": {\n` +
+            `           "FLAIR_AGENT_ID": "${env.FLAIR_AGENT_ID}",\n` +
+            `           "FLAIR_URL": "${env.FLAIR_URL}"\n` +
+            `         }\n` +
+            `       }\n` +
+            `     }\n` +
+            `   }\n` +
+            `3. Restart Cursor\n` +
+            `Note: This is a manual step - the Flair CLI cannot automatically modify Cursor's settings due to security restrictions.`,
+    };
+}
+// ---- Exported detection & wiring array ------------------------------------------
+export const ALL_CLIENTS = [
+    {
+        id: "claude-code",
+        label: "Claude Code",
+        wire: _wireClaudeCode,
+    },
+    {
+        id: "codex",
+        label: "Codex",
+        wire: _wireCodex,
+    },
+    {
+        id: "gemini",
+        label: "Gemini",
+        wire: _wireGemini,
+    },
+    {
+        id: "cursor",
+        label: "Cursor",
+        wire: _wireCursor,
+    },
+];
+export function detectClients() {
+    return ALL_CLIENTS.map((client) => ({
+        ...client,
+        detected: client.id === "claude-code"
+            ? claudeCodeDetect()
+            : client.id === "codex"
+                ? codexDetect()
+                : client.id === "gemini"
+                    ? geminiDetect()
+                    : client.id === "cursor"
+                        ? cursorDetect()
+                        : false,
+    }));
+}
+export function wireClaudeCode(env) {
+    return _wireClaudeCode(env);
+}
+export function wireCodex(env) {
+    return _wireCodex(env);
+}
+export function wireGemini(env) {
+    return _wireGemini(env);
+}
+export function wireCursor(env) {
+    return _wireCursor(env);
+}

package/dist/resources/Federation.js

@@ -82,6 +82,14 @@ export class FederationInstance extends Resource {
  * Requires a one-time pairing token generated by `flair federation token`.
  */
 export class FederationPair extends Resource {
+    // Pairing is a public endpoint by design — spokes have no Harper credentials
+    // on the hub yet. The handler self-validates via PairingToken + Ed25519
+    // body-signature. Bypassing Harper's role gate is required because Harper's
+    // auth layer (security/auth.js) claims any "Bearer X" header for itself,
+    // so we route the token through the body instead.
+    allowCreate(_user, _record, _context) {
+        return true;
+    }
     async post(data) {
         const { instanceId, publicKey, role, endpoint, signature, pairingToken } = data || {};
         if (!instanceId || !publicKey) {
@@ -119,36 +127,34 @@ export class FederationPair extends Resource {
             });
         }
         else {
-            // New peer — require a valid pairing token
+            // New peer — require a valid pairing token in the request body.
+            // The handler self-validates because the endpoint is public at the
+            // Harper-auth and middleware layers (Bearer is not usable on Harper —
+            // its auth layer claims unknown Bearer values and 401s).
             if (!pairingToken) {
                 return new Response(JSON.stringify({
-                    error: "pairingToken required — generate one with 'flair federation token'",
+                    error: "pairingToken required in body for first-time pair",
                 }), { status: 401, headers: { "content-type": "application/json" } });
             }
-            // Validate and consume the token
-            let token = null;
+            // Fetch the token record for consumption
+            let tokenRecord = null;
             try {
-                token = await databases.flair.PairingToken.get(pairingToken);
+                tokenRecord = await databases.flair.PairingToken.get(pairingToken);
             }
             catch { /* table may not exist */ }
-            if (!token) {
-                return new Response(JSON.stringify({ error: "invalid pairing token" }), {
-                    status: 401, headers: { "content-type": "application/json" },
-                });
-            }
-            if (token.consumedBy) {
-                return new Response(JSON.stringify({ error: "pairing token already used" }), {
+            if (!tokenRecord || tokenRecord.consumedBy) {
+                return new Response(JSON.stringify({ error: "invalid_or_expired_pairing_token" }), {
                     status: 401, headers: { "content-type": "application/json" },
                 });
             }
-            if (token.expiresAt && new Date(token.expiresAt) < new Date()) {
-                return new Response(JSON.stringify({ error: "pairing token expired" }), {
+            if (tokenRecord.expiresAt && new Date(tokenRecord.expiresAt) < new Date()) {
+                return new Response(JSON.stringify({ error: "invalid_or_expired_pairing_token" }), {
                     status: 401, headers: { "content-type": "application/json" },
                 });
             }
             // Consume the token
             await databases.flair.PairingToken.put({
-                ...token,
+                ...tokenRecord,
                 consumedBy: instanceId,
                 consumedAt: new Date().toISOString(),
             });

package/dist/resources/auth-middleware.js

@@ -117,28 +117,49 @@ server.http(async (request, nextLayer) => {
         url.pathname === "/AgentCard" ||
         url.pathname.startsWith("/A2AAdapter/") ||
         url.pathname.startsWith("/AgentCard/") ||
-        // Federation endpoints handle their own auth via Ed25519 body signatures
-        url.pathname === "/FederationPair" ||
+        // FederationSync uses Ed25519 body-signature auth (handled by the resource)
         url.pathname === "/FederationSync" ||
+        // FederationPair uses one-time PairingToken in the request body, validated
+        // by the resource itself (allowCreate=true on the Resource lets anonymous
+        // POST through Harper's role gate). Bearer can't be used here because
+        // Harper's auth layer claims any "Bearer X" Authorization header for itself.
+        url.pathname === "/FederationPair" ||
         // OAuth 2.1 public endpoints (spec requires no pre-auth)
         url.pathname === "/OAuthRegister" ||
         url.pathname === "/OAuthAuthorize" ||
         url.pathname === "/OAuthToken" ||
         url.pathname === "/OAuthRevoke" ||
         url.pathname === "/.well-known/oauth-authorization-server" ||
-        url.pathname === "/OAuthMetadata")
+        url.pathname === "/OAuthMetadata" ||
+        // ObservationCenter HTML shell is public — the page itself is just markup
+        // and inline JS, with no embedded data. The JS prompts for admin-pass and
+        // auths every API call (/Agent, /SemanticSearch, /FederationPeers, etc).
+        // Without this allow-list entry, the HTML is 401-blocked on hosted Flair
+        // instances (rockit-local works only because authorizeLocal=true).
+        url.pathname === "/ObservationCenter")
+        return nextLayer(request);
+    // If Harper has already authorized this request (e.g. authorizeLocal=true on localhost),
+    // trust Harper's auth decision and pass through without requiring additional headers.
+    if (request.user?.role?.permission?.super_user === true) {
         return nextLayer(request);
+    }
     // Skip re-entry: if we already swapped auth to Basic, pass through
     if (request._tpsAuthVerified)
         return nextLayer(request);
     const header = request.headers.get("authorization") || request.headers?.asObject?.authorization || "";
-    // ── Basic admin auth ──────────────────────────────────────────────────────
-    // Allow Basic auth with the admin password for CLI operations (backup, etc.)
-    // This is checked BEFORE Ed25519 so admin tools can use simple auth.
+    // ── Basic admin / super_user auth ──────────────────────────────────────────
+    // Allow Basic auth for CLI operations (backup, etc.). Two paths:
+    // 1. HDB_ADMIN_PASSWORD env-var fast-path (user must be "admin" with exact pass)
+    // 2. Harper super_user check — any user with super_user:true permission accepted
+    // Checked BEFORE Ed25519 so admin tools can use simple auth.
     if (header.startsWith("Basic ")) {
         try {
             const decoded = Buffer.from(header.slice(6), "base64").toString("utf-8");
-            const [user, pass] = decoded.split(":");
+            const colonIdx = decoded.indexOf(":");
+            const user = colonIdx >= 0 ? decoded.slice(0, colonIdx) : decoded;
+            const pass = colonIdx >= 0 ? decoded.slice(colonIdx + 1) : "";
+            // Path 1: Env-var fast-path (back-compat). Only matches user==="admin"
+            // with exact HDB_ADMIN_PASSWORD. Non-match falls through to Path 2.
             const adminPass = getAdminPass();
             if (adminPass !== null && user === "admin" && pass === adminPass) {
                 // Mark as verified and set Harper user directly
@@ -150,14 +171,26 @@ server.http(async (request, nextLayer) => {
                 request.headers.set("x-tps-agent", "admin");
                 if (request.headers.asObject)
                     request.headers.asObject["x-tps-agent"] = "admin";
-                // Basic admin auth IS admin — resource-level checks (SemanticSearch,
-                // MemoryBootstrap, MemoryReflect, MemoryConsolidate) gate cross-agent
-                // access on this flag. Prior to 0.5.5 the check was a no-op so this
-                // was never needed; now it must be set.
                 request.tpsAgent = "admin";
                 request.tpsAgentIsAdmin = true;
                 return nextLayer(request);
             }
+            // Path 2: Harper super_user check — any user with super_user:true
+            let harperUser = null;
+            try {
+                harperUser = await server.getUser(user, pass, request);
+            }
+            catch { /* fall through — invalid creds, non-existent user, etc. */ }
+            if (harperUser?.role?.permission?.super_user === true) {
+                request._tpsAuthVerified = true;
+                request.user = harperUser;
+                request.headers.set("x-tps-agent", user);
+                if (request.headers.asObject)
+                    request.headers.asObject["x-tps-agent"] = user;
+                request.tpsAgent = user;
+                request.tpsAgentIsAdmin = true;
+                return nextLayer(request);
+            }
         }
         catch { /* fall through to Ed25519 check */ }
         return new Response(JSON.stringify({ error: "invalid_admin_credentials" }), { status: 401 });

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,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.6.1",
+  "version": "0.7.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",
@@ -59,11 +59,13 @@
     "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"
   },