@tpsdev-ai/flair 0.2.0

package/resources/AgentCard.ts

@@ -0,0 +1,65 @@
+import { Resource, databases } from "@harperfast/harper";
+
+type SoulLike = {
+  key?: string;
+  value?: string;
+  kind?: string;
+  content?: string;
+};
+
+function readSoulKind(entry: SoulLike): string {
+  return String(entry.kind ?? entry.key ?? "").trim().toLowerCase();
+}
+
+function readSoulContent(entry: SoulLike): string {
+  return String(entry.content ?? entry.value ?? "").trim();
+}
+
+export class AgentCard extends Resource {
+  async get(pathInfo?: any) {
+    const agentId =
+      (typeof pathInfo === "string" ? pathInfo : null) ??
+      (this as any).getId?.() ??
+      null;
+
+    if (!agentId) {
+      return new Response(
+        JSON.stringify({ error: "agentId required in path: GET /AgentCard/{agentId}" }),
+        { status: 400, headers: { "Content-Type": "application/json" } },
+      );
+    }
+
+    const agent = await (databases as any).flair.Agent.get(agentId).catch(() => null);
+    if (!agent) {
+      return new Response(JSON.stringify({ error: "agent_not_found", agentId }), {
+        status: 404,
+        headers: { "Content-Type": "application/json" },
+      });
+    }
+
+    const souls: SoulLike[] = [];
+    for await (const row of (databases as any).flair.Soul.search()) {
+      if (row?.agentId === agentId) souls.push(row);
+    }
+
+    const descriptionEntry =
+      souls.find((s) => readSoulKind(s) === "description" && readSoulContent(s)) ??
+      souls.find((s) => readSoulContent(s));
+
+    const skills = souls
+      .filter((s) => readSoulKind(s) === "capability")
+      .map((s) => readSoulContent(s))
+      .filter(Boolean);
+
+    return {
+      name: String(agent.name ?? agent.id ?? agentId),
+      description: descriptionEntry ? readSoulContent(descriptionEntry) : "",
+      url: String(agent.url ?? ""),
+      version: String(agent.version ?? "1.0.0"),
+      capabilities: agent.capabilities && typeof agent.capabilities === "object" ? agent.capabilities : {},
+      skills,
+      defaultInputModes: ["text"],
+      defaultOutputModes: ["text"],
+    };
+  }
+}

package/resources/AgentSeed.ts

@@ -0,0 +1,119 @@
+/**
+ * POST /AgentSeed
+ *
+ * Auto-seeds a new agent with soul entries and starter memories.
+ * Called by `tps agent create` after local key generation.
+ *
+ * Request:
+ *   agentId          string   — agent identifier
+ *   displayName      string?  — human-readable name (defaults to agentId)
+ *   role             string?  — "admin" | "agent" (default: "agent")
+ *   soulTemplate     object?  — key:value pairs for Soul table (merged with defaults)
+ *   starterMemories  array?   — [{content, tags?, durability?}] (defaults if omitted)
+ *
+ * Response:
+ *   { agent, soulEntries, memories }
+ *
+ * Auth: admin only.
+ */
+
+import { Resource, databases } from "@harperfast/harper";
+import { isAdmin } from "./auth-middleware.js";
+
+const DEFAULT_SOUL_KEYS = (agentId: string, displayName: string, role: string, now: string) => ({
+  name: displayName,
+  role,
+  created: now,
+  status: "active",
+});
+
+const DEFAULT_MEMORIES = (agentId: string, now: string) => [
+  {
+    content: `Agent ${agentId} initialized. No prior context.`,
+    tags: ["onboarding", "system"],
+    durability: "persistent",
+  },
+];
+
+export class AgentSeed extends Resource {
+  async post(data: any) {
+    const actorId = (this as any).request?.tpsAgent;
+    if (!actorId || !(await isAdmin(actorId))) {
+      return new Response(JSON.stringify({ error: "forbidden: admin only" }), { status: 403 });
+    }
+
+    const { agentId, displayName, role = "agent", soulTemplate, starterMemories } = data || {};
+    if (!agentId) return new Response(JSON.stringify({ error: "agentId required" }), { status: 400 });
+    if (!/^[a-zA-Z0-9_-]{1,64}$/.test(agentId)) {
+      return new Response(JSON.stringify({ error: "invalid agentId" }), { status: 400 });
+    }
+
+    const now = new Date().toISOString();
+    const name = displayName || agentId;
+
+    // ── Agent record ──────────────────────────────────────────────────────────
+    const existingAgent = await (databases as any).flair.Agent.get(agentId).catch(() => null);
+    let agent = existingAgent;
+    if (!existingAgent) {
+      agent = { id: agentId, name, role, publicKey: "pending", createdAt: now, updatedAt: now };
+      await (databases as any).flair.Agent.put(agent);
+    }
+
+    // ── Soul entries ──────────────────────────────────────────────────────────
+    const defaults = DEFAULT_SOUL_KEYS(agentId, name, role, now);
+    const merged = { ...defaults, ...(soulTemplate || {}) };
+    const soulEntries: any[] = [];
+
+    for (const [key, value] of Object.entries(merged)) {
+      const id = `${agentId}:${key}`;
+      const existing = await (databases as any).flair.Soul.get(id);
+      if (existing) {
+        soulEntries.push(existing); // skip — don't overwrite existing soul entries
+        continue;
+      }
+      const entry = { id, agentId, key, value: String(value), durability: "permanent", createdAt: now, updatedAt: now };
+      await (databases as any).flair.Soul.put(entry);
+      soulEntries.push(entry);
+    }
+
+    // ── Starter memories ──────────────────────────────────────────────────────
+    const memDefs = starterMemories && starterMemories.length > 0
+      ? starterMemories
+      : DEFAULT_MEMORIES(agentId, now);
+
+    const memories: any[] = [];
+    // Only seed memories if this is a first-time seed (none tagged onboarding yet)
+    const hasOnboardingMemory = await (async () => {
+      for await (const m of (databases as any).flair.Memory.search()) {
+        if (m.agentId === agentId && (m.tags ?? []).includes("onboarding")) return true;
+      }
+      return false;
+    })();
+    if (hasOnboardingMemory) {
+      // Re-seed: return existing onboarding memories without writing new ones
+      for await (const m of (databases as any).flair.Memory.search()) {
+        if (m.agentId === agentId && (m.tags ?? []).includes("onboarding")) memories.push(m);
+      }
+    } else {
+      for (let i = 0; i < memDefs.length; i++) {
+        const def = memDefs[i];
+        const id = `seed-${agentId}-${i}-${Date.now()}`;
+        const record = {
+          id,
+          agentId,
+          content: def.content,
+          durability: def.durability ?? "persistent",
+          tags: def.tags ?? ["onboarding"],
+          source: "seed",
+          createdAt: now,
+          updatedAt: now,
+          archived: false,
+        };
+        await (databases as any).flair.Memory.put(record);
+        memories.push(record);
+      }
+    } // end !hasOnboardingMemory
+
+    return { agent, soulEntries, memories };
+  }
+}

package/resources/IngestEvents.ts

@@ -0,0 +1,189 @@
+/**
+ * IngestEvents.ts — Observatory ingestion endpoint.
+ *
+ * POST /IngestEvents
+ * Auth: TPS-Ed25519 signed by the office's private key (verified against
+ *       ObsOffice.publicKey stored at registration time).
+ *
+ * Body: {
+ *   officeId: string;
+ *   events:   OrgEventRecord[];
+ *   agents:   AgentStatus[];
+ *   syncedAt: string;
+ * }
+ *
+ * Actions:
+ *   1. Verify Ed25519 signature against stored office public key
+ *   2. Upsert ObsAgentSnapshot for each agent
+ *   3. Insert ObsEventFeed for each new event (30-day TTL)
+ *   4. Update ObsOffice.lastSeen + agentCount
+ *
+ * Rate limit: 1 call / 10s per office (enforced by createdAt delta check)
+ * Batch limit: 100 events per call
+ */
+
+import { Resource, databases } from "@harperfast/harper";
+import { createPublicKey, verify } from "node:crypto";
+
+const BATCH_LIMIT = 100;
+const RATE_LIMIT_MS = 10_000;
+const EVENT_TTL_DAYS = 30;
+
+interface OrgEventRecord {
+  id: string;
+  kind: string;
+  authorId: string;
+  summary: string;
+  refId?: string;
+  scope?: string;
+  targetIds?: string[];
+  createdAt: string;
+}
+
+interface AgentStatus {
+  agentId: string;
+  name?: string;
+  role?: string;
+  status?: string;
+  model?: string;
+  lastSeen?: string;
+}
+
+interface IngestPayload {
+  officeId: string;
+  events: OrgEventRecord[];
+  agents: AgentStatus[];
+  syncedAt: string;
+}
+
+function verifyEd25519Signature(
+  publicKeyHex: string,
+  authHeader: string,
+  officeId: string,
+): boolean {
+  try {
+    // Header format: TPS-Ed25519 officeId:ts:nonce:sig
+    const prefix = "TPS-Ed25519 ";
+    if (!authHeader.startsWith(prefix)) return false;
+    const parts = authHeader.slice(prefix.length).split(":");
+    if (parts.length < 4) return false;
+    const [id, ts, nonce, ...sigParts] = parts;
+    const sig = sigParts.join(":");
+    if (id !== officeId) return false;
+
+    // Replay protection: reject signatures older than 5 minutes
+    const age = Date.now() - Number(ts);
+    if (age > 5 * 60 * 1000 || age < -30_000) return false;
+
+    const pubKeyBytes = Buffer.from(publicKeyHex.replace(/=\s*/g, ""), "hex");
+    const spkiHeader = Buffer.from("302a300506032b6570032100", "hex");
+    const pubKey = createPublicKey({ key: Buffer.concat([spkiHeader, pubKeyBytes]), format: "der", type: "spki" });
+
+    const payload = Buffer.from(`${id}:${ts}:${nonce}:POST:/IngestEvents`);
+    const sigBuf = Buffer.from(sig, "base64");
+    return verify(null, payload, pubKey, sigBuf);
+  } catch {
+    return false;
+  }
+}
+
+export class IngestEvents extends Resource {
+  async post(body: unknown, context?: unknown) {
+    const request = (this as any).request;
+    const authHeader: string | undefined = request?.headers?.get?.("authorization") ?? request?.headers?.authorization;
+
+    // Parse and validate body
+    let payload: IngestPayload;
+    try {
+      payload = (typeof body === "string" ? JSON.parse(body) : body) as IngestPayload;
+    } catch {
+      return new Response(JSON.stringify({ error: "invalid JSON" }), { status: 400, headers: { "Content-Type": "application/json" } });
+    }
+
+    const { officeId, events = [], agents = [], syncedAt } = payload;
+    if (!officeId) {
+      return new Response(JSON.stringify({ error: "officeId required" }), { status: 400, headers: { "Content-Type": "application/json" } });
+    }
+
+    // Look up the office
+    const office = await (databases as any).flair.ObsOffice.get(officeId).catch(() => null);
+    if (!office) {
+      return new Response(JSON.stringify({ error: "office not registered — POST /ObsOffice first" }), { status: 403, headers: { "Content-Type": "application/json" } });
+    }
+
+    // Verify Ed25519 signature
+    if (!authHeader || !verifyEd25519Signature(String(office.publicKey), authHeader, officeId)) {
+      return new Response(JSON.stringify({ error: "invalid signature" }), { status: 401, headers: { "Content-Type": "application/json" } });
+    }
+
+    // Rate limit check
+    if (office.lastSeen) {
+      const msSinceLastSync = Date.now() - new Date(office.lastSeen).getTime();
+      if (msSinceLastSync < RATE_LIMIT_MS) {
+        return new Response(JSON.stringify({ error: "rate limit: 1 call per 10s" }), { status: 429, headers: { "Content-Type": "application/json" } });
+      }
+    }
+
+    // Batch limit
+    if (events.length > BATCH_LIMIT) {
+      return new Response(JSON.stringify({ error: `batch limit: max ${BATCH_LIMIT} events` }), { status: 400, headers: { "Content-Type": "application/json" } });
+    }
+
+    const now = new Date().toISOString();
+    const expiresAt = new Date(Date.now() + EVENT_TTL_DAYS * 24 * 60 * 60 * 1000).toISOString();
+
+    // Upsert agent snapshots
+    for (const agent of agents) {
+      if (!agent.agentId) continue;
+      const snapshotId = `${officeId}:${agent.agentId}`;
+      await (databases as any).flair.ObsAgentSnapshot.put({
+        id: snapshotId,
+        officeId,
+        agentId: agent.agentId,
+        name: agent.name ?? agent.agentId,
+        role: agent.role,
+        status: agent.status ?? "unknown",
+        model: agent.model,
+        lastActivity: agent.lastSeen ?? now,
+        lastHeartbeat: now,
+        updatedAt: now,
+      }).catch((e: Error) => console.warn(`[IngestEvents] snapshot upsert failed for ${snapshotId}: ${e.message}`));
+    }
+
+    // Insert event feed entries (skip duplicates)
+    let inserted = 0;
+    for (const ev of events) {
+      if (!ev.id || !ev.kind) continue;
+      const feedId = `${officeId}:${ev.id}`;
+      const existing = await (databases as any).flair.ObsEventFeed.get(feedId).catch(() => null);
+      if (existing) continue;
+      await (databases as any).flair.ObsEventFeed.put({
+        id: feedId,
+        officeId,
+        kind: ev.kind,
+        authorId: ev.authorId,
+        summary: ev.summary,
+        refId: ev.refId,
+        scope: ev.scope,
+        createdAt: ev.createdAt,
+        receivedAt: now,
+        expiresAt,
+      }).catch((e: Error) => console.warn(`[IngestEvents] event insert failed for ${feedId}: ${e.message}`));
+      inserted++;
+    }
+
+    // Update office lastSeen + agentCount
+    await (databases as any).flair.ObsOffice.put({
+      ...office,
+      status: "online",
+      lastSeen: now,
+      agentCount: agents.length,
+      updatedAt: now,
+    }).catch(() => {});
+
+    return new Response(JSON.stringify({ ok: true, events: inserted, agents: agents.length }), {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    });
+  }
+}

package/resources/Integration.ts

@@ -0,0 +1,14 @@
+import { databases } from "@harperfast/harper";
+
+export class Integration extends (databases as any).flair.Integration {
+  async post(content: any, context?: any) {
+    // S31-A: API never accepts plaintext credentials.
+    if (typeof content?.credential === "string" || typeof content?.token === "string") {
+      return new Response(JSON.stringify({ error: "plaintext_credentials_forbidden" }), {
+        status: 400,
+        headers: { "Content-Type": "application/json" },
+      });
+    }
+    return super.post(content, context);
+  }
+}

package/resources/IssueTokens.ts

@@ -0,0 +1,29 @@
+import { Resource, databases } from "@harperfast/harper";
+
+export class IssueTokens extends Resource {
+  static loadAsInstance = false;
+
+  async get(_target: unknown) {
+    const { refresh_token: refreshToken, operation_token: jwt } =
+      await (databases as any).system.hdb_user.operation(
+        { operation: "create_authentication_tokens" },
+        this.getContext(),
+      );
+    return { refreshToken, jwt };
+  }
+
+  async post(_target: unknown, data: any) {
+    if (!data?.username || !data?.password) {
+      throw new Error("username and password are required");
+    }
+
+    const { refresh_token: refreshToken, operation_token: jwt } =
+      await (databases as any).system.hdb_user.operation({
+        operation: "create_authentication_tokens",
+        username: data.username,
+        password: data.password,
+      });
+
+    return { refreshToken, jwt };
+  }
+}

package/resources/Memory.ts

@@ -0,0 +1,138 @@
+import { databases } from "@harperfast/harper";
+import { patchRecord } from "./table-helpers.js";
+import { isAdmin } from "./auth-middleware.js";
+
+export class Memory extends (databases as any).flair.Memory {
+  /**
+   * Override search() to scope collection GETs by authenticated agent.
+   *
+   * Security Critical: the agentId condition is wrapped as the outermost
+   * `and` block so user-supplied query operators cannot bypass it via
+   * boolean injection (e.g. [..., "or", { wildcard }]).
+   *
+   * Admin agents and unauthenticated internal calls pass through unfiltered.
+   * Non-admin calls also check MemoryGrant to include granted memories.
+   */
+  async search(query?: any) {
+    // Access request context via Harper's Resource instance context
+    const ctx = (this as any).getContext?.();
+    const request = ctx?.request ?? ctx;
+    const authAgent: string | undefined = request?.tpsAgent;
+    const isAdminAgent: boolean = request?.tpsAgentIsAdmin ?? false;
+
+    // No auth context (internal admin call) or admin agent — unfiltered
+    if (!authAgent || isAdminAgent) {
+      return super.search(query);
+    }
+
+    // Collect agentIds this agent may read: own + any granted owners
+    const allowedOwners: string[] = [authAgent];
+    try {
+      for await (const grant of (databases as any).flair.MemoryGrant.search({
+        conditions: [{ attribute: "granteeId", comparator: "equals", value: authAgent }],
+      })) {
+        if (grant.ownerId && (grant.scope === "read" || grant.scope === "search")) {
+          allowedOwners.push(grant.ownerId);
+        }
+      }
+    } catch { /* MemoryGrant table not yet populated — ignore */ }
+
+    // Build the agentId scope condition
+    const agentIdCondition: any = 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) with pathname, id, etc.
+    // Table.search() reads `target.conditions` from it. We inject our scope condition there.
+    if (query && typeof query === "object" && !Array.isArray(query)) {
+      const existing = query.conditions ?? [];
+      query.conditions = Array.isArray(existing)
+        ? [agentIdCondition, ...existing]
+        : [agentIdCondition, existing];
+      return super.search(query);
+    }
+
+    // Fallback: plain array or no query (internal calls)
+    const conditions = Array.isArray(query) && query.length > 0
+      ? [agentIdCondition, ...query]
+      : [agentIdCondition];
+    return super.search(conditions);
+  }
+
+  async post(content: any, context?: any) {
+    content.durability ||= "standard";
+    content.createdAt = new Date().toISOString();
+    content.updatedAt = content.createdAt;
+    content.archived = content.archived ?? false;
+
+    // Validate derivedFrom source IDs exist (best-effort, non-blocking)
+    if (Array.isArray(content.derivedFrom) && content.derivedFrom.length > 0) {
+      const now = content.createdAt;
+      for (const sourceId of content.derivedFrom) {
+        try {
+          const src = await (databases as any).flair.Memory.get(sourceId);
+          if (src) {
+            patchRecord((databases as any).flair.Memory, sourceId, { lastReflected: now }).catch(() => {});
+          }
+        } catch {}
+      }
+    }
+
+    // supersedes: optional reference to the ID of the memory this one replaces
+    if (content.supersedes !== undefined && typeof content.supersedes !== "string") {
+      return new Response(JSON.stringify({ error: "supersedes must be a string (memory ID)" }), {
+        status: 400, headers: { "Content-Type": "application/json" },
+      });
+    }
+
+    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();
+    }
+
+    return super.post(content);
+  }
+
+  async put(content: any) {
+    const now = new Date().toISOString();
+    content.updatedAt = now;
+
+    // If archiving, record who + when
+    if (content.archived === true && !content.archivedAt) {
+      content.archivedAt = now;
+      // archivedBy should be set by the caller (CLI stamps req.tpsAgent via query param)
+    }
+
+    // If approving promotion, record timestamp
+    if (content.promotionStatus === "approved" && !content.promotedAt) {
+      content.promotedAt = now;
+    }
+
+    // Upgrade to permanent when approved
+    if (content.promotionStatus === "approved") {
+      content.durability = "permanent";
+    }
+
+    return super.put(content);
+  }
+
+  async delete(id: any) {
+    const record = await this.get(id);
+    if (!record) return super.delete(id);
+
+    if (record.durability === "permanent") {
+      // Middleware already guards this for non-admins, but belt-and-suspenders
+      const ctx = (this as any).getContext?.();
+      const request = ctx?.request ?? ctx;
+      const actorId = request?.tpsAgent;
+      if (actorId && !(await isAdmin(actorId))) {
+        return new Response(JSON.stringify({ error: "permanent_memory_cannot_be_deleted_by_non_admin" }), {
+          status: 403,
+          headers: { "Content-Type": "application/json" },
+        });
+      }
+    }
+
+    return super.delete(id);
+  }
+}