@tpsdev-ai/flair 0.4.16 → 0.5.0

package/dist/resources/Credential.js

@@ -0,0 +1,105 @@
+import { databases } from "@harperfast/harper";
+import { checkRateLimit, rateLimitResponse } from "./rate-limiter.js";
+/**
+ * Credential resource — authentication surfaces for Principals.
+ *
+ * A Principal can have multiple credentials: passkeys, bearer tokens,
+ * Ed25519 signing keys, and IdP links. This resource manages the
+ * credential lifecycle: creation, revocation, and lookup.
+ *
+ * Only admin principals can create/revoke credentials for other principals.
+ * Non-admin principals can only view their own credentials (token hashes
+ * are never returned in responses).
+ */
+export class Credential extends databases.flair.Credential {
+    async search(query) {
+        const ctx = this.getContext?.();
+        const request = ctx?.request ?? ctx;
+        const authAgent = request?.tpsAgent;
+        const isAdminAgent = request?.tpsAgentIsAdmin ?? false;
+        if (!authAgent || isAdminAgent) {
+            return super.search(query);
+        }
+        // Non-admin: scope to own credentials
+        const condition = { attribute: "principalId", comparator: "equals", value: authAgent };
+        if (!query?.conditions) {
+            return super.search({ conditions: [condition], ...(query || {}) });
+        }
+        return super.search({
+            ...query,
+            conditions: [condition, { conditions: query.conditions, operator: query.operator || "and" }],
+            operator: "and",
+        });
+    }
+    async get() {
+        const result = await super.get();
+        if (!result)
+            return result;
+        const ctx = this.getContext?.();
+        const request = ctx?.request ?? ctx;
+        const authAgent = request?.tpsAgent;
+        const isAdminAgent = request?.tpsAgentIsAdmin ?? false;
+        // Non-admin can only see their own credentials
+        if (authAgent && !isAdminAgent && result.principalId !== authAgent) {
+            return new Response(JSON.stringify({ error: "forbidden" }), {
+                status: 403, headers: { "content-type": "application/json" },
+            });
+        }
+        // Never return token hashes
+        const { tokenHash, ...safe } = result;
+        return safe;
+    }
+    async put(content) {
+        const ctx = this.getContext?.();
+        const request = ctx?.request ?? ctx;
+        const authAgent = request?.tpsAgent;
+        const isAdminAgent = request?.tpsAgentIsAdmin ?? false;
+        if (!authAgent) {
+            return new Response(JSON.stringify({ error: "authentication required" }), {
+                status: 401, headers: { "content-type": "application/json" },
+            });
+        }
+        // Only admins can create credentials for other principals
+        if (!isAdminAgent && content.principalId && content.principalId !== authAgent) {
+            return new Response(JSON.stringify({ error: "only admin principals can manage other principals' credentials" }), {
+                status: 403, headers: { "content-type": "application/json" },
+            });
+        }
+        const rl = checkRateLimit(authAgent);
+        if (!rl.allowed)
+            return rateLimitResponse(rl.retryAfterMs, "credential");
+        // Validate kind
+        const validKinds = ["webauthn", "bearer-token", "ed25519", "idp"];
+        if (!content.kind || !validKinds.includes(content.kind)) {
+            return new Response(JSON.stringify({ error: `kind must be one of: ${validKinds.join(", ")}` }), {
+                status: 400, headers: { "content-type": "application/json" },
+            });
+        }
+        const now = new Date().toISOString();
+        content.principalId = content.principalId || authAgent;
+        content.status = content.status || "active";
+        content.createdAt = content.createdAt || now;
+        content.updatedAt = now;
+        return super.put(content);
+    }
+    async delete(_) {
+        const ctx = this.getContext?.();
+        const request = ctx?.request ?? ctx;
+        const authAgent = request?.tpsAgent;
+        const isAdminAgent = request?.tpsAgentIsAdmin ?? false;
+        if (!authAgent) {
+            return new Response(JSON.stringify({ error: "authentication required" }), {
+                status: 401, headers: { "content-type": "application/json" },
+            });
+        }
+        if (!isAdminAgent) {
+            const existing = await super.get();
+            if (existing?.principalId && existing.principalId !== authAgent) {
+                return new Response(JSON.stringify({ error: "only admin principals can revoke other principals' credentials" }), {
+                    status: 403, headers: { "content-type": "application/json" },
+                });
+            }
+        }
+        return super.delete(_);
+    }
+}

package/dist/resources/Federation.js

@@ -0,0 +1,315 @@
+import { Resource, databases } from "@harperfast/harper";
+import { randomBytes } from "node:crypto";
+import nacl from "tweetnacl";
+import { canonicalize, signBody, verifyBodySignature } from "./federation-crypto.js";
+// Re-export for consumers that import from Federation.ts
+export { canonicalize, signBody, verifyBodySignature };
+// ─── Conflict resolution ─────────────────────────────────────────────────────
+/**
+ * Field-level Last-Write-Wins merge.
+ * For each field, the value with the later `updatedAt` wins.
+ * Records with no local counterpart are accepted directly.
+ */
+function mergeRecord(local, remote) {
+    if (!local)
+        return remote.data;
+    const merged = { ...local };
+    const localUpdated = local.updatedAt ?? "";
+    const remoteUpdated = remote.updatedAt ?? "";
+    // Simple LWW at record level for 1.0
+    // Field-level LWW is the spec target but record-level is sufficient
+    // for the initial implementation and avoids per-field clock tracking.
+    if (remoteUpdated > localUpdated) {
+        Object.assign(merged, remote.data);
+        merged.updatedAt = remoteUpdated;
+    }
+    return merged;
+}
+// ─── Instance identity ───────────────────────────────────────────────────────
+/**
+ * GET /FederationInstance — return this instance's identity.
+ * Used by peers during pairing and by the admin UI.
+ */
+export class FederationInstance extends Resource {
+    async get() {
+        // Find or create instance identity
+        let instance = null;
+        try {
+            for await (const i of databases.flair.Instance.search()) {
+                instance = i;
+                break;
+            }
+        }
+        catch { /* table may not exist */ }
+        if (!instance) {
+            // First boot — generate instance identity
+            const kp = nacl.sign.keyPair();
+            const id = `flair_${randomBytes(4).toString("hex")}`;
+            const publicKey = Buffer.from(kp.publicKey).toString("base64url");
+            instance = {
+                id,
+                publicKey,
+                role: "spoke", // default; hub is set during `flair init --remote`
+                status: "active",
+                createdAt: new Date().toISOString(),
+                updatedAt: new Date().toISOString(),
+            };
+            await databases.flair.Instance.put(instance);
+            // Store private key seed in encrypted keystore (not in DB)
+            try {
+                const { keystore } = await import("../src/keystore.js");
+                const seed = kp.secretKey.slice(0, 32);
+                keystore.setPrivateKeySeed(id, seed);
+            }
+            catch (err) {
+                // Fail closed — never store plaintext keys in the database
+                console.error("[federation] FATAL: Could not store key seed in keystore. Federation identity not created.", err);
+                throw new Error("Keystore unavailable — cannot create federation identity without secure key storage");
+            }
+        }
+        return {
+            id: instance.id,
+            publicKey: instance.publicKey,
+            role: instance.role,
+            status: instance.status,
+        };
+    }
+}
+// ─── Peer management ─────────────────────────────────────────────────────────
+/**
+ * POST /FederationPair — one-shot pairing handshake.
+ * A spoke sends its instance identity; the hub records it as a peer.
+ * Requires a one-time pairing token generated by `flair federation token`.
+ */
+export class FederationPair extends Resource {
+    async post(data) {
+        const { instanceId, publicKey, role, endpoint, signature, pairingToken } = data || {};
+        if (!instanceId || !publicKey) {
+            return new Response(JSON.stringify({ error: "instanceId and publicKey required" }), {
+                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).
+        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" }), {
+                status: 401, headers: { "content-type": "application/json" },
+            });
+        }
+        // Check if already paired (re-pairing doesn't need a token)
+        const existing = await databases.flair.Peer.get(instanceId);
+        if (existing) {
+            // Re-pairing: verify public key matches (prevents impersonation)
+            if (existing.publicKey !== publicKey) {
+                return new Response(JSON.stringify({
+                    error: "public key mismatch — peer already paired with different key",
+                }), { status: 409, headers: { "content-type": "application/json" } });
+            }
+            // Update endpoint and status
+            await databases.flair.Peer.put({
+                ...existing,
+                endpoint: endpoint ?? existing.endpoint,
+                status: "paired",
+                updatedAt: new Date().toISOString(),
+            });
+        }
+        else {
+            // New peer — require a valid pairing token
+            if (!pairingToken) {
+                return new Response(JSON.stringify({
+                    error: "pairingToken required — generate one with 'flair federation token'",
+                }), { status: 401, headers: { "content-type": "application/json" } });
+            }
+            // Validate and consume the token
+            let token = null;
+            try {
+                token = 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" }), {
+                    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" },
+                });
+            }
+            // Consume the token
+            await databases.flair.PairingToken.put({
+                ...token,
+                consumedBy: instanceId,
+                consumedAt: new Date().toISOString(),
+            });
+            await databases.flair.Peer.put({
+                id: instanceId,
+                publicKey,
+                role: role ?? "spoke",
+                endpoint: endpoint ?? null,
+                status: "paired",
+                relayOnly: false,
+                pairedAt: new Date().toISOString(),
+                createdAt: new Date().toISOString(),
+                updatedAt: new Date().toISOString(),
+            });
+        }
+        // Return our own identity for the peer to record
+        let ourInstance = null;
+        try {
+            for await (const i of databases.flair.Instance.search()) {
+                ourInstance = i;
+                break;
+            }
+        }
+        catch { }
+        return {
+            paired: true,
+            instance: ourInstance ? {
+                id: ourInstance.id,
+                publicKey: ourInstance.publicKey,
+                role: ourInstance.role,
+            } : null,
+        };
+    }
+}
+// ─── Sync endpoint ───────────────────────────────────────────────────────────
+/**
+ * POST /FederationSync — push sync records from a peer.
+ * In 1.0, this is a simple HTTP push (not WebSocket).
+ * The calling peer sends a batch of SyncRecords; we merge them.
+ */
+export class FederationSync extends Resource {
+    async post(data) {
+        const { instanceId, records, lamportClock, signature } = data || {};
+        if (!instanceId || !Array.isArray(records)) {
+            return new Response(JSON.stringify({ error: "instanceId and records[] required" }), {
+                status: 400, headers: { "content-type": "application/json" },
+            });
+        }
+        // Verify peer is known
+        const peer = await databases.flair.Peer.get(instanceId);
+        if (!peer || peer.status === "revoked") {
+            return new Response(JSON.stringify({ error: "unknown or revoked peer" }), {
+                status: 403, headers: { "content-type": "application/json" },
+            });
+        }
+        // Verify request signature against peer's pinned public key
+        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" }), {
+                status: 401, headers: { "content-type": "application/json" },
+            });
+        }
+        const startTime = Date.now();
+        let merged = 0;
+        let skipped = 0;
+        // Table name → Harper database table mapping
+        const tableMap = {
+            Memory: databases.flair.Memory,
+            Soul: databases.flair.Soul,
+            Agent: databases.flair.Agent,
+            Relationship: databases.flair.Relationship,
+        };
+        for (const record of records) {
+            const table = tableMap[record.table];
+            if (!table) {
+                skipped++;
+                continue;
+            }
+            // Originator enforcement: peers can only push records they originated.
+            // The hub can relay records from other peers (role === "hub"),
+            // but spokes can only push their own records.
+            const originator = record.originatorInstanceId ?? instanceId;
+            if (originator !== instanceId && peer.role !== "hub") {
+                skipped++;
+                continue;
+            }
+            try {
+                const local = await table.get(record.id);
+                // Timestamp ceiling: reject records with updatedAt more than 5 minutes in the future.
+                // Prevents attackers from using far-future timestamps to permanently win LWW.
+                const fiveMinFromNow = new Date(Date.now() + 5 * 60 * 1000).toISOString();
+                if (record.updatedAt > fiveMinFromNow) {
+                    skipped++;
+                    continue;
+                }
+                const mergedData = mergeRecord(local, record);
+                // Preserve originator for provenance
+                mergedData._originatorInstanceId = originator;
+                mergedData._syncedFrom = instanceId;
+                mergedData._syncedAt = new Date().toISOString();
+                await table.put(mergedData);
+                merged++;
+            }
+            catch {
+                skipped++;
+            }
+        }
+        // Update peer sync cursor
+        await databases.flair.Peer.put({
+            ...peer,
+            lastSyncAt: new Date().toISOString(),
+            lastSyncCursor: lamportClock?.toString() ?? new Date().toISOString(),
+            status: "connected",
+            updatedAt: new Date().toISOString(),
+        });
+        // Log sync operation
+        try {
+            await databases.flair.SyncLog.put({
+                id: `sync_${Date.now()}_${randomBytes(4).toString("hex")}`,
+                peerId: instanceId,
+                direction: "pull",
+                recordCount: merged,
+                status: skipped > 0 ? "partial" : "success",
+                error: skipped > 0 ? `${skipped} records skipped` : undefined,
+                durationMs: Date.now() - startTime,
+                createdAt: new Date().toISOString(),
+            });
+        }
+        catch { /* non-fatal */ }
+        return {
+            merged,
+            skipped,
+            total: records.length,
+            durationMs: Date.now() - startTime,
+        };
+    }
+}
+/**
+ * GET /FederationPeers — list known peers (admin view).
+ */
+export class FederationPeers extends Resource {
+    async get() {
+        const peers = [];
+        try {
+            for await (const p of databases.flair.Peer.search()) {
+                peers.push({
+                    id: p.id,
+                    role: p.role,
+                    status: p.status,
+                    endpoint: p.endpoint,
+                    lastSyncAt: p.lastSyncAt,
+                    relayOnly: p.relayOnly,
+                    pairedAt: p.pairedAt,
+                });
+            }
+        }
+        catch { }
+        return { peers };
+    }
+}

package/dist/resources/Memory.js

@@ -88,6 +88,17 @@ export class Memory extends databases.flair.Memory {
                 status: 400, headers: { "Content-Type": "application/json" },
             });
         }
+        // Temporal validity: validFrom defaults to now, validTo left null for active facts.
+        // When a memory supersedes another, close the superseded memory's validity window.
+        if (!content.validFrom) {
+            content.validFrom = content.createdAt;
+        }
+        if (content.supersedes) {
+            patchRecord(databases.flair.Memory, content.supersedes, {
+                validTo: content.validFrom,
+                updatedAt: content.createdAt,
+            }).catch(() => { });
+        }
         if (content.durability === "ephemeral" && !content.expiresAt) {
             const ttlHours = Number(process.env.FLAIR_EPHEMERAL_TTL_HOURS || 24);
             content.expiresAt = new Date(Date.now() + ttlHours * 3600_000).toISOString();

package/dist/resources/MemoryBootstrap.js

@@ -4,15 +4,22 @@ import { wrapUntrusted } from "./content-safety.js";
 /**
  * POST /MemoryBootstrap
  *
- * One-call context builder for agent cold starts.
+ * Predictive context builder for agent session starts.
  * Returns prioritized, token-budgeted context with:
  *   1. Soul records (identity, role, preferences)
  *   2. Permanent memories (safety rules, core principles)
- *   3. Recent memories (last 24-48h standard/persistent)
+ *   3. Recent memories (adaptive window)
  *   4. Task-relevant memories (semantic search if currentTask provided)
+ *   5. Relationship context (active relationships for mentioned entities)
+ *   6. Predicted context (based on channel/surface/subject hints)
+ *
+ * Prediction: when context signals (channel, surface, subjects) are provided,
+ * the bootstrap loads more aggressively — Flair is fast enough that the
+ * bottleneck is prediction quality, not load time.
  *
  * Request:
- *   { agentId, currentTask?, maxTokens?, includeSoul?, since? }
+ *   { agentId, currentTask?, maxTokens?, includeSoul?, since?,
+ *     channel?, surface?, subjects? }
  *
  * Response:
  *   { context, sections, tokenEstimate, memoriesIncluded, memoriesAvailable }
@@ -34,7 +41,10 @@ function formatMemory(m, supersedes) {
 }
 export class BootstrapMemories extends Resource {
     async post(data, _context) {
-        const { agentId, currentTask, maxTokens = 4000, includeSoul = true, since, } = data || {};
+        const { agentId, currentTask, maxTokens = 4000, includeSoul = true, since, channel, // e.g., "discord", "tps-mail", "claude-code"
+        surface, // e.g., "tps-build", "tps-review", "cli-session"
+        subjects, // e.g., ["flair", "auth"] — entities to preload context for
+         } = data || {};
         if (!agentId) {
             return new Response(JSON.stringify({ error: "agentId required" }), {
                 status: 400,
@@ -54,6 +64,8 @@ export class BootstrapMemories extends Resource {
             skills: [],
             permanent: [],
             recent: [],
+            predicted: [],
+            relationships: [],
             relevant: [],
             events: [],
         };
@@ -202,6 +214,73 @@ export class BootstrapMemories extends Resource {
             tokenBudget -= cost;
             memoriesIncluded++;
         }
+        // --- 3b. Subject-predicted context ---
+        // When subjects are provided (e.g., ["flair", "auth"]), load memories
+        // tagged with those subjects that aren't already included. This is the
+        // "predictive" part — the caller knows what topics are likely relevant
+        // based on channel/surface/recent-activity.
+        const predictedSubjects = Array.isArray(subjects)
+            ? subjects.map((s) => s.toLowerCase())
+            : [];
+        if (predictedSubjects.length > 0 && tokenBudget > 200) {
+            const includedIds = new Set([
+                ...permanent.map((m) => m.id),
+                ...recent.filter((_, i) => i < sections.recent.length).map((m) => m.id),
+            ]);
+            const subjectMemories = activeMemories
+                .filter((m) => !includedIds.has(m.id) &&
+                m.subject &&
+                predictedSubjects.includes(m.subject.toLowerCase()) &&
+                m.durability !== "permanent" // already loaded
+            )
+                .sort((a, b) => (b.createdAt || "").localeCompare(a.createdAt || ""));
+            const predictedBudget = Math.floor(tokenBudget * 0.3);
+            let predictedSpent = 0;
+            for (const m of subjectMemories) {
+                const line = formatMemory(m);
+                const cost = estimateTokens(line);
+                if (predictedSpent + cost > predictedBudget)
+                    continue;
+                sections.predicted.push(line);
+                predictedSpent += cost;
+                tokenBudget -= cost;
+                memoriesIncluded++;
+                includedIds.add(m.id);
+            }
+        }
+        // --- 3c. Active relationships for predicted subjects ---
+        if (predictedSubjects.length > 0 && tokenBudget > 100) {
+            try {
+                for (const subj of predictedSubjects) {
+                    for await (const rel of databases.flair.Relationship.search({
+                        conditions: [
+                            { attribute: "agentId", comparator: "equals", value: agentId },
+                            {
+                                operator: "or",
+                                conditions: [
+                                    { attribute: "subject", comparator: "equals", value: subj },
+                                    { attribute: "object", comparator: "equals", value: subj },
+                                ],
+                            },
+                        ],
+                        operator: "and",
+                    })) {
+                        // Only include active relationships (no validTo or validTo in future)
+                        if (rel.validTo && rel.validTo < new Date().toISOString())
+                            continue;
+                        const line = `- ${rel.subject} → ${rel.predicate} → ${rel.object}${rel.confidence < 1.0 ? ` (${Math.round(rel.confidence * 100)}%)` : ""}`;
+                        const cost = estimateTokens(line);
+                        if (cost > tokenBudget)
+                            break;
+                        sections.relationships.push(line);
+                        tokenBudget -= cost;
+                    }
+                }
+            }
+            catch {
+                // Relationship table may not exist yet
+            }
+        }
         // --- 4. Task-relevant memories (semantic search) ---
         if (currentTask && tokenBudget > 200) {
             let queryEmbedding = null;
@@ -280,6 +359,12 @@ export class BootstrapMemories extends Resource {
         if (sections.recent.length > 0) {
             parts.push("## Recent Context\n" + sections.recent.join("\n"));
         }
+        if (sections.predicted.length > 0) {
+            parts.push("## Predicted Context\n" + sections.predicted.join("\n"));
+        }
+        if (sections.relationships.length > 0) {
+            parts.push("## Active Relationships\n" + sections.relationships.join("\n"));
+        }
         if (sections.relevant.length > 0) {
             parts.push("## Relevant Knowledge\n" + sections.relevant.join("\n"));
         }
@@ -296,6 +381,8 @@ export class BootstrapMemories extends Resource {
                 skills: sections.skills.length,
                 permanent: sections.permanent.length,
                 recent: sections.recent.length,
+                predicted: sections.predicted.length,
+                relationships: sections.relationships.length,
                 relevant: sections.relevant.length,
                 events: sections.events.length,
             },