@tpsdev-ai/flair 0.6.2 → 0.8.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

@@ -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.
@@ -82,6 +87,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) {
@@ -89,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" },
             });
         }
@@ -119,36 +138,46 @@ 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" }), {
+            if (!tokenRecord || tokenRecord.consumedBy) {
+                return new Response(JSON.stringify({ error: "invalid_or_expired_pairing_token" }), {
                     status: 401, headers: { "content-type": "application/json" },
                 });
             }
-            if (token.consumedBy) {
-                return new Response(JSON.stringify({ error: "pairing token already used" }), {
+            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" },
                 });
             }
-            if (token.expiresAt && new Date(token.expiresAt) < new Date()) {
-                return new Response(JSON.stringify({ error: "pairing token expired" }), {
-                    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({
-                ...token,
+                ...tokenRecord,
                 consumedBy: instanceId,
                 consumedAt: new Date().toISOString(),
             });
@@ -163,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;
@@ -190,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)) {
@@ -204,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" },
             });
         }
@@ -313,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,28 +117,50 @@ 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 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
+        // 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 +172,47 @@ 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);
+            }
+            // 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 });