@tpsdev-ai/flair 0.4.15 → 0.5.0

package/dist/keystore.js

@@ -0,0 +1,116 @@
+/**
+ * Keystore — encrypted file-based storage for Ed25519 private key seeds.
+ *
+ * Primary: AES-256-GCM encrypted files at ~/.flair/keys/<instanceId>.key
+ * Fallback: HarperDB (migration path from pre-keystore installs)
+ *
+ * Encryption key derived via HKDF from FLAIR_KEY_PASSPHRASE env var,
+ * or an auto-generated random passphrase stored at ~/.flair/keys/.passphrase
+ * (mode 0600). Never falls back to guessable data.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { randomBytes, createCipheriv, createDecipheriv, hkdfSync, } from "node:crypto";
+// ─── Helpers ────────────────────────────────────────────────────────────────
+function keysDir() {
+    return join(homedir(), ".flair", "keys");
+}
+function keyPath(instanceId) {
+    // Sanitize instanceId to prevent directory traversal
+    const safe = instanceId.replace(/[^a-zA-Z0-9_-]/g, "_");
+    return join(keysDir(), `${safe}.key`);
+}
+/**
+ * Path to the auto-generated passphrase file.
+ * Created on first keystore use if FLAIR_KEY_PASSPHRASE env var is not set.
+ */
+function passphrasePath() {
+    return join(keysDir(), ".passphrase");
+}
+/**
+ * Get or create the keystore passphrase.
+ * Priority: FLAIR_KEY_PASSPHRASE env var > auto-generated file.
+ * Never falls back to guessable data (hostname, username, etc.).
+ */
+function getPassphrase() {
+    // Explicit env var takes priority
+    if (process.env.FLAIR_KEY_PASSPHRASE) {
+        return process.env.FLAIR_KEY_PASSPHRASE;
+    }
+    const pp = passphrasePath();
+    // Read existing auto-generated passphrase
+    if (existsSync(pp)) {
+        return readFileSync(pp, "utf-8").trim();
+    }
+    // Generate a cryptographically random passphrase and persist it
+    const dir = keysDir();
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    const generated = randomBytes(32).toString("base64url");
+    writeFileSync(pp, generated, { mode: 0o600 });
+    return generated;
+}
+/**
+ * Derive a 256-bit encryption key using HKDF.
+ * Input keying material: FLAIR_KEY_PASSPHRASE env var, or auto-generated random passphrase.
+ */
+function deriveKey() {
+    const passphrase = getPassphrase();
+    return Buffer.from(hkdfSync("sha256", passphrase, "flair-keystore-salt", "flair-key-encryption", 32));
+}
+// ─── File-based encrypted keystore ──────────────────────────────────────────
+/**
+ * Encrypt a seed with AES-256-GCM.
+ * File format: 12-byte IV | 16-byte auth tag | ciphertext
+ */
+function encryptSeed(seed) {
+    const key = deriveKey();
+    const iv = randomBytes(12);
+    const cipher = createCipheriv("aes-256-gcm", key, iv);
+    const encrypted = Buffer.concat([cipher.update(seed), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return Buffer.concat([iv, tag, encrypted]);
+}
+/**
+ * Decrypt a seed from the file format.
+ */
+function decryptSeed(data) {
+    const key = deriveKey();
+    const iv = data.subarray(0, 12);
+    const tag = data.subarray(12, 28);
+    const ciphertext = data.subarray(28);
+    const decipher = createDecipheriv("aes-256-gcm", key, iv, { authTagLength: 16 });
+    decipher.setAuthTag(tag);
+    const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+    return new Uint8Array(decrypted);
+}
+// ─── KeyStore implementation ────────────────────────────────────────────────
+class FileKeyStore {
+    getPrivateKeySeed(instanceId) {
+        const p = keyPath(instanceId);
+        if (!existsSync(p))
+            return null;
+        try {
+            const data = readFileSync(p);
+            return decryptSeed(data);
+        }
+        catch {
+            return null;
+        }
+    }
+    setPrivateKeySeed(instanceId, seed) {
+        const dir = keysDir();
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true, mode: 0o700 });
+        }
+        const p = keyPath(instanceId);
+        const encrypted = encryptSeed(seed);
+        writeFileSync(p, encrypted, { mode: 0o600 });
+    }
+}
+/** Singleton keystore instance. */
+export const keystore = new FileKeyStore();
+// Export helpers for testing
+export { encryptSeed, decryptSeed, deriveKey, keyPath, keysDir };

package/dist/resources/AdminConnectors.js

@@ -0,0 +1,54 @@
+import { Resource, databases } from "@harperfast/harper";
+import { layout, htmlResponse, esc } from "./admin-layout.js";
+/**
+ * GET /AdminConnectors — OAuth clients and active sessions.
+ */
+export class AdminConnectors extends Resource {
+    async get() {
+        const clients = [];
+        try {
+            for await (const c of databases.flair.OAuthClient.search()) {
+                clients.push(c);
+            }
+        }
+        catch { /* table may not exist */ }
+        clients.sort((a, b) => (b.createdAt || "").localeCompare(a.createdAt || ""));
+        let tableRows = "";
+        if (clients.length === 0) {
+            tableRows = `<tr><td colspan="4" class="empty">No OAuth clients registered. Clients are created via Dynamic Client Registration when Claude connects.</td></tr>`;
+        }
+        else {
+            for (const c of clients) {
+                const created = c.createdAt?.slice(0, 10) ?? "—";
+                const source = c.registeredBy === "dcr" ? "DCR" : c.registeredBy ?? "—";
+                const redirects = (c.redirectUris ?? []).join(", ");
+                tableRows += `
+          <tr>
+            <td><strong>${esc(c.name || "Unnamed")}</strong><br><small>${esc(c.id)}</small></td>
+            <td>${esc(redirects || "—")}</td>
+            <td><span class="badge badge-gray">${esc(source)}</span></td>
+            <td>${created}</td>
+          </tr>`;
+            }
+        }
+        const content = `
+      <h1>Connectors</h1>
+      <p class="subtitle">OAuth clients that can access this Flair instance</p>
+
+      <table>
+        <thead>
+          <tr>
+            <th>Client</th>
+            <th>Redirect URIs</th>
+            <th>Source</th>
+            <th>Created</th>
+          </tr>
+        </thead>
+        <tbody>
+          ${tableRows}
+        </tbody>
+      </table>
+    `;
+        return htmlResponse(layout("Connectors", content, "connectors"));
+    }
+}

package/dist/resources/AdminDashboard.js

@@ -0,0 +1,68 @@
+import { Resource, databases } from "@harperfast/harper";
+import { layout, htmlResponse } from "./admin-layout.js";
+/**
+ * GET /AdminDashboard — admin home page with system overview.
+ */
+export class AdminDashboard extends Resource {
+    async get() {
+        let principalCount = 0;
+        let memoryCount = 0;
+        let humanCount = 0;
+        let agentCount = 0;
+        try {
+            for await (const p of databases.flair.Agent.search()) {
+                principalCount++;
+                if (p.kind === "human")
+                    humanCount++;
+                else
+                    agentCount++;
+            }
+        }
+        catch { /* table may not exist */ }
+        try {
+            for await (const _ of databases.flair.Memory.search()) {
+                memoryCount++;
+            }
+        }
+        catch { /* table may not exist */ }
+        let idpCount = 0;
+        try {
+            for await (const _ of databases.flair.IdpConfig.search()) {
+                idpCount++;
+            }
+        }
+        catch { /* table may not exist */ }
+        let relationshipCount = 0;
+        try {
+            for await (const _ of databases.flair.Relationship.search()) {
+                relationshipCount++;
+            }
+        }
+        catch { /* table may not exist */ }
+        const content = `
+      <h1>Dashboard</h1>
+      <p class="subtitle">Flair instance overview</p>
+
+      <div class="stats">
+        <div class="card">
+          <h3>Principals</h3>
+          <div class="value">${principalCount}</div>
+          <div>${humanCount} human, ${agentCount} agent</div>
+        </div>
+        <div class="card">
+          <h3>Memories</h3>
+          <div class="value">${memoryCount}</div>
+        </div>
+        <div class="card">
+          <h3>Relationships</h3>
+          <div class="value">${relationshipCount}</div>
+        </div>
+        <div class="card">
+          <h3>IdP Configs</h3>
+          <div class="value">${idpCount}</div>
+        </div>
+      </div>
+    `;
+        return htmlResponse(layout("Dashboard", content, "home"));
+    }
+}

package/dist/resources/AdminIdp.js

@@ -0,0 +1,57 @@
+import { Resource, databases } from "@harperfast/harper";
+import { layout, htmlResponse, esc } from "./admin-layout.js";
+/**
+ * GET /AdminIdp — enterprise IdP configuration management.
+ */
+export class AdminIdp extends Resource {
+    async get() {
+        const idps = [];
+        try {
+            for await (const cfg of databases.flair.IdpConfig.search()) {
+                idps.push(cfg);
+            }
+        }
+        catch { /* table may not exist */ }
+        let tableRows = "";
+        if (idps.length === 0) {
+            tableRows = `<tr><td colspan="5" class="empty">No IdPs configured. Use <code>flair idp add</code> to register an enterprise IdP.</td></tr>`;
+        }
+        else {
+            for (const cfg of idps) {
+                const status = cfg.enabled
+                    ? `<span class="badge badge-green">enabled</span>`
+                    : `<span class="badge badge-gray">disabled</span>`;
+                const jit = cfg.jitProvision ? "yes" : "no";
+                const domain = cfg.requiredDomain ?? "—";
+                tableRows += `
+          <tr>
+            <td><strong>${esc(cfg.name)}</strong><br><small>${esc(cfg.id)}</small></td>
+            <td>${esc(cfg.issuer)}</td>
+            <td>${esc(domain)}</td>
+            <td>${jit}</td>
+            <td>${status}</td>
+          </tr>`;
+            }
+        }
+        const content = `
+      <h1>Enterprise IdP</h1>
+      <p class="subtitle">Identity providers for XAA (Enterprise-Managed Authorization)</p>
+
+      <table>
+        <thead>
+          <tr>
+            <th>Name</th>
+            <th>Issuer</th>
+            <th>Domain</th>
+            <th>JIT</th>
+            <th>Status</th>
+          </tr>
+        </thead>
+        <tbody>
+          ${tableRows}
+        </tbody>
+      </table>
+    `;
+        return htmlResponse(layout("IdP", content, "idp"));
+    }
+}

package/dist/resources/AdminInstance.js

@@ -0,0 +1,64 @@
+import { Resource } from "@harperfast/harper";
+import { layout, htmlResponse } from "./admin-layout.js";
+import { join } from "node:path";
+import { homedir } from "node:os";
+/**
+ * GET /AdminInstance — instance info, public key, version.
+ */
+export class AdminInstance extends Resource {
+    async get() {
+        const version = process.env.npm_package_version ?? "dev";
+        const httpPort = process.env.HTTP_PORT ?? "19926";
+        const publicUrl = process.env.FLAIR_PUBLIC_URL ?? `http://127.0.0.1:${httpPort}`;
+        // Try to read instance public key
+        let publicKey = "—";
+        const keyDir = join(homedir(), ".flair", "keys");
+        try {
+            // Look for any .pub file
+            const { readdirSync } = await import("node:fs");
+            const files = readdirSync(keyDir).filter((f) => f.endsWith(".pub") || f.endsWith(".key"));
+            if (files.length > 0) {
+                publicKey = `${files.length} key(s) in ${keyDir}`;
+            }
+        }
+        catch {
+            publicKey = "Key directory not found";
+        }
+        const content = `
+      <h1>Instance</h1>
+      <p class="subtitle">Flair instance configuration and identity</p>
+
+      <div class="stats">
+        <div class="card">
+          <h3>Version</h3>
+          <div class="value" style="font-size:1.4em">${version}</div>
+        </div>
+        <div class="card">
+          <h3>Public URL</h3>
+          <div style="font-family:monospace;font-size:0.9em;word-break:break-all">${publicUrl}</div>
+        </div>
+      </div>
+
+      <div class="card">
+        <h3>Keys</h3>
+        <p>${publicKey}</p>
+        <p style="margin-top:8px;color:#666;font-size:0.9em">
+          Ed25519 keys are stored in <code>${keyDir}</code>. Each principal has its own keypair.
+        </p>
+      </div>
+
+      <div class="card">
+        <h3>Endpoints</h3>
+        <table style="box-shadow:none">
+          <tr><td>API</td><td><code>${publicUrl}/</code></td></tr>
+          <tr><td>MCP</td><td><code>${publicUrl}/mcp</code></td></tr>
+          <tr><td>OAuth Discovery</td><td><code>${publicUrl}/OAuthMetadata</code></td></tr>
+          <tr><td>OAuth Authorize</td><td><code>${publicUrl}/OAuthAuthorize</code></td></tr>
+          <tr><td>OAuth Token</td><td><code>${publicUrl}/OAuthToken</code></td></tr>
+          <tr><td>Admin</td><td><code>${publicUrl}/AdminDashboard</code></td></tr>
+        </table>
+      </div>
+    `;
+        return htmlResponse(layout("Instance", content, "instance"));
+    }
+}

package/dist/resources/AdminMemory.js

@@ -0,0 +1,92 @@
+import { Resource, databases } from "@harperfast/harper";
+import { layout, htmlResponse, esc } from "./admin-layout.js";
+/**
+ * GET /AdminMemory — browse and search memories.
+ */
+export class AdminMemory extends Resource {
+    async get() {
+        const request = this.request;
+        const url = new URL(request?.url ?? "http://localhost", "http://localhost");
+        const query = url.searchParams.get("q") ?? "";
+        const subject = url.searchParams.get("subject") ?? "";
+        const limit = Math.min(Number(url.searchParams.get("limit") ?? 50), 200);
+        const memories = [];
+        try {
+            const conditions = [];
+            if (subject) {
+                conditions.push({ attribute: "subject", comparator: "equals", value: subject.toLowerCase() });
+            }
+            conditions.push({ attribute: "archived", comparator: "not_equal", value: true });
+            const searchQuery = conditions.length > 0 ? { conditions } : {};
+            let count = 0;
+            for await (const m of databases.flair.Memory.search(searchQuery)) {
+                if (m.expiresAt && Date.parse(m.expiresAt) < Date.now())
+                    continue;
+                if (query && !String(m.content || "").toLowerCase().includes(query.toLowerCase()))
+                    continue;
+                memories.push(m);
+                count++;
+                if (count >= limit)
+                    break;
+            }
+        }
+        catch { /* table may not exist */ }
+        memories.sort((a, b) => (b.createdAt || "").localeCompare(a.createdAt || ""));
+        let tableRows = "";
+        if (memories.length === 0) {
+            tableRows = `<tr><td colspan="5" class="empty">No memories found${query ? ` matching "${query}"` : ""}.</td></tr>`;
+        }
+        else {
+            for (const m of memories) {
+                const preview = (m.content || "").slice(0, 120) + ((m.content || "").length > 120 ? "…" : "");
+                const durability = m.durability ?? "standard";
+                const durBadge = durability === "permanent"
+                    ? `<span class="badge badge-green">${durability}</span>`
+                    : durability === "persistent"
+                        ? `<span class="badge badge-blue">${durability}</span>`
+                        : `<span class="badge badge-gray">${durability}</span>`;
+                const subjectStr = m.subject ?? "—";
+                const created = m.createdAt?.slice(0, 10) ?? "—";
+                const validity = m.validTo ? `<small>expired ${m.validTo.slice(0, 10)}</small>` : "";
+                tableRows += `
+          <tr>
+            <td style="max-width:400px">${esc(preview)}</td>
+            <td>${durBadge}</td>
+            <td>${esc(subjectStr)}</td>
+            <td>${esc(m.agentId ?? "—")}</td>
+            <td>${created} ${validity}</td>
+          </tr>`;
+            }
+        }
+        const content = `
+      <h1>Memory</h1>
+      <p class="subtitle">${memories.length} memor${memories.length !== 1 ? "ies" : "y"} shown</p>
+
+      <div style="margin-bottom: 20px">
+        <form method="GET" action="/AdminMemory" style="display:flex;gap:8px">
+          <input type="text" name="q" value="${esc(query)}" placeholder="Search memories..."
+            style="flex:1;padding:8px 12px;border:1px solid #ddd;border-radius:6px;font-size:0.95em">
+          <input type="text" name="subject" value="${esc(subject)}" placeholder="Subject filter"
+            style="width:150px;padding:8px 12px;border:1px solid #ddd;border-radius:6px;font-size:0.95em">
+          <button type="submit" class="btn btn-primary">Search</button>
+        </form>
+      </div>
+
+      <table>
+        <thead>
+          <tr>
+            <th>Content</th>
+            <th>Durability</th>
+            <th>Subject</th>
+            <th>Agent</th>
+            <th>Created</th>
+          </tr>
+        </thead>
+        <tbody>
+          ${tableRows}
+        </tbody>
+      </table>
+    `;
+        return htmlResponse(layout("Memory", content, "memory"));
+    }
+}

package/dist/resources/AdminPrincipals.js

@@ -0,0 +1,71 @@
+import { Resource, databases } from "@harperfast/harper";
+import { layout, htmlResponse, esc } from "./admin-layout.js";
+/**
+ * GET /AdminPrincipals — list all principals with kind, trust, status.
+ */
+export class AdminPrincipals extends Resource {
+    async get() {
+        const principals = [];
+        try {
+            for await (const p of databases.flair.Agent.search()) {
+                principals.push(p);
+            }
+        }
+        catch { /* table may not exist */ }
+        principals.sort((a, b) => (a.createdAt || "").localeCompare(b.createdAt || ""));
+        let tableRows = "";
+        if (principals.length === 0) {
+            tableRows = `<tr><td colspan="6" class="empty">No principals registered yet.</td></tr>`;
+        }
+        else {
+            for (const p of principals) {
+                const kind = p.kind ?? "agent";
+                const kindBadge = kind === "human"
+                    ? `<span class="badge badge-blue">human</span>`
+                    : `<span class="badge badge-gray">agent</span>`;
+                const trust = p.defaultTrustTier ?? "—";
+                const trustBadge = trust === "endorsed"
+                    ? `<span class="badge badge-green">${trust}</span>`
+                    : trust === "corroborated"
+                        ? `<span class="badge badge-blue">${trust}</span>`
+                        : `<span class="badge badge-yellow">${trust}</span>`;
+                const status = p.status ?? "active";
+                const statusBadge = status === "active"
+                    ? `<span class="badge badge-green">${status}</span>`
+                    : `<span class="badge badge-gray">${status}</span>`;
+                const admin = p.admin ? "yes" : "";
+                const created = p.createdAt?.slice(0, 10) ?? "—";
+                tableRows += `
+          <tr>
+            <td><strong>${esc(p.id)}</strong><br><small>${esc(p.displayName || p.name || "")}</small></td>
+            <td>${kindBadge}</td>
+            <td>${trustBadge}</td>
+            <td>${statusBadge}</td>
+            <td>${admin}</td>
+            <td>${created}</td>
+          </tr>`;
+            }
+        }
+        const content = `
+      <h1>Principals</h1>
+      <p class="subtitle">${principals.length} registered principal${principals.length !== 1 ? "s" : ""}</p>
+
+      <table>
+        <thead>
+          <tr>
+            <th>ID / Name</th>
+            <th>Kind</th>
+            <th>Trust</th>
+            <th>Status</th>
+            <th>Admin</th>
+            <th>Created</th>
+          </tr>
+        </thead>
+        <tbody>
+          ${tableRows}
+        </tbody>
+      </table>
+    `;
+        return htmlResponse(layout("Principals", content, "principals"));
+    }
+}

package/dist/resources/Agent.js

@@ -1,9 +1,56 @@
 import { databases } from "@harperfast/harper";
+/**
+ * Agent resource — serves as the Principal table in 1.0.
+ *
+ * The Agent table is extended (not replaced) to serve as the Principal
+ * model. The `kind` field distinguishes humans from agents. Pre-1.0
+ * records without `kind` are treated as agents with default trust tier.
+ *
+ * Principal fields added in 1.0:
+ *   - kind: "human" | "agent"
+ *   - displayName: human-friendly label
+ *   - status: "active" | "deactivated"
+ *   - defaultTrustTier: "endorsed" | "corroborated" | "unverified"
+ *   - admin: boolean
+ *   - runtime: how to reach this principal
+ *   - subjects: soul-level subject interests
+ */
 export class Agent extends databases.flair.Agent {
     async post(content, context) {
+        const now = new Date().toISOString();
+        // Backward compat: set type for legacy code
         content.type ||= "agent";
-        content.createdAt = new Date().toISOString();
-        content.updatedAt = content.createdAt;
+        // 1.0 Principal defaults
+        content.kind ||= "agent";
+        content.status ||= "active";
+        content.displayName ||= content.name;
+        content.admin ??= false;
+        // Trust tier defaults per kind
+        if (!content.defaultTrustTier) {
+            content.defaultTrustTier = content.admin ? "endorsed" : "unverified";
+        }
+        content.createdAt = now;
+        content.updatedAt = now;
         return super.post(content, context);
     }
+    async put(content) {
+        const ctx = this.getContext?.();
+        const request = ctx?.request ?? ctx;
+        const authAgent = request?.tpsAgent;
+        const isAdminAgent = request?.tpsAgentIsAdmin ?? false;
+        // Only admin principals can modify other principals
+        if (authAgent && !isAdminAgent) {
+            const existing = await super.get();
+            if (existing && existing.id !== authAgent) {
+                return new Response(JSON.stringify({ error: "only admin principals can modify other principals" }), {
+                    status: 403, headers: { "content-type": "application/json" },
+                });
+            }
+        }
+        content.updatedAt = new Date().toISOString();
+        // Protect immutable fields
+        delete content.createdAt;
+        delete content.publicKey; // key rotation goes through dedicated endpoint
+        return super.put(content);
+    }
 }