@tpsdev-ai/flair 0.4.15 → 0.5.0

package/dist/resources/health.js

@@ -1,6 +1,72 @@
-import { Resource } from "@harperfast/harper";
+import { Resource, databases } from "@harperfast/harper";
+const db = databases;
+/**
+ * Health endpoint — unauthenticated, returns only { ok: true }.
+ *
+ * Rich stats (memory counts, agent names, etc.) are behind /HealthDetail
+ * which requires authentication. This prevents information leakage on
+ * publicly exposed instances.
+ */
 export class Health extends Resource {
     async get() {
         return { ok: true };
     }
 }
+/**
+ * Authenticated health detail — returns memory/agent/soul stats + process info.
+ * Requires Ed25519 agent auth or admin basic auth.
+ */
+export class HealthDetail extends Resource {
+    async get() {
+        const stats = { ok: true };
+        // ── Memory stats ──
+        try {
+            const list = [];
+            for await (const m of db.flair.Memory.search({})) {
+                list.push(m);
+            }
+            stats.memories = {
+                total: list.length,
+                withEmbeddings: list.filter((m) => m.embeddingModel && m.embeddingModel !== "hash-512d").length,
+                hashFallback: list.filter((m) => !m.embeddingModel || m.embeddingModel === "hash-512d").length,
+            };
+            if (list.length > 0) {
+                const sorted = list.filter((m) => m.createdAt).sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
+                if (sorted[0])
+                    stats.lastWrite = sorted[0].createdAt;
+            }
+        }
+        catch {
+            stats.memories = null;
+        }
+        // ── Agent stats ──
+        try {
+            const agents = [];
+            for await (const a of db.flair.Agent.search({})) {
+                agents.push(a);
+            }
+            stats.agents = {
+                count: agents.length,
+                names: agents.map((a) => a.id).filter(Boolean),
+            };
+        }
+        catch {
+            stats.agents = null;
+        }
+        // ── Soul stats ──
+        try {
+            let count = 0;
+            for await (const _ of db.flair.Soul.search({})) {
+                count++;
+            }
+            stats.soulEntries = count;
+        }
+        catch {
+            stats.soulEntries = null;
+        }
+        // ── Process info ──
+        stats.pid = process.pid;
+        stats.uptimeSeconds = Math.floor(process.uptime());
+        return stats;
+    }
+}

package/dist/src/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.4.15",
+  "version": "0.5.0",
   "description": "Identity, memory, and soul for AI agents. Cryptographic identity (Ed25519), semantic memory with local embeddings, and persistent personality — all in a single process.",
   "type": "module",
   "license": "Apache-2.0",
@@ -39,7 +39,8 @@
     "build": "tsc -p tsconfig.json --noCheck",
     "build:cli": "tsc -p tsconfig.cli.json --noCheck",
     "prepublishOnly": "npm run build && npm run build:cli",
-    "test": "bun test"
+    "test": "bun test",
+    "release": "./scripts/release.sh"
   },
   "publishConfig": {
     "access": "public"
@@ -48,9 +49,10 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@harperfast/harper": "5.0.0-beta.8",
+    "@harperfast/harper": "5.0.0",
     "commander": "14.0.3",
     "harper-fabric-embeddings": "0.2.2",
+    "jose": "^6.2.2",
     "tweetnacl": "1.0.3"
   },
   "devDependencies": {

package/schemas/agent.graphql

@@ -1,13 +1,62 @@
+# Agent table — backward compatible with 0.x, extended for 1.0 Principals.
+# The Agent table IS the Principal table. We keep the name "Agent" for backward
+# compatibility with existing code, queries, and exports. The `kind` field
+# distinguishes humans from agents. Pre-1.0 records without `kind` are treated
+# as agents.
 type Agent @table(database: "flair") @export {
   id: ID @primaryKey
   name: String!
   role: String
-  type: String @indexed
-  publicKey: String!
+  type: String @indexed           # legacy (0.x): "agent", "tool", etc.
+
+  # 1.0 Principal fields
+  kind: String @indexed           # "human" | "agent" (default: "agent" for 0.x compat)
+  displayName: String             # human-friendly name
+  status: String @indexed         # "active" | "deactivated" (default: "active")
+  publicKey: String!              # Ed25519 public key
+  defaultTrustTier: String @indexed  # "endorsed" | "corroborated" | "unverified"
+  admin: Boolean @indexed         # admin principals can manage other principals
+  runtime: String                 # "openclaw" | "claude-code" | "headless" | "external" | null
+  runtimeEndpoint: String         # how to reach this principal programmatically
+  subjects: [String]              # soul-level subject interests
+
+  createdAt: String!
+  updatedAt: String
+}
+
+# Credential table — auth surfaces for Principals.
+# A Principal can have multiple credentials (passkey + bearer token + Ed25519).
+# Credentials are NOT the Ed25519 signing keypair — they're authentication methods.
+type Credential @table(database: "flair") @export {
+  id: ID @primaryKey
+  principalId: String! @indexed   # FK to Agent.id
+  kind: String! @indexed          # "webauthn" | "bearer-token" | "ed25519" | "idp"
+  label: String                   # "iPhone 16 Pro", "OpenClaw plugin", "Harper Corporate"
+  status: String @indexed         # "active" | "revoked"
+
+  # Bearer token (kind: "bearer-token")
+  tokenHash: String               # bcrypt/sha256 hash — never store raw token
+  tokenPrefix: String             # first 8 chars for identification ("flair_at_")
+
+  # WebAuthn (kind: "webauthn")
+  webauthnCredentialId: String     # base64url credential ID
+  webauthnPublicKey: String        # COSE public key
+  webauthnAaguid: String           # authenticator identifier
+  webauthnTransports: [String]     # ["internal", "hybrid", "usb"]
+  webauthnCounter: Int             # signature counter for replay detection
+
+  # IdP (kind: "idp") — for XAA enterprise auth
+  idpProvider: String              # IdP config ID
+  idpSubject: String @indexed      # stable user identifier from IdP
+  idpEmail: String                 # email from IdP claims
+
   createdAt: String!
+  lastUsedAt: String
   updatedAt: String
 }
 
+# Integration table — kept for backward compat with 0.x platform connections.
+# New code should use Credential instead.
 type Integration @table(database: "flair") @export {
   id: ID @primaryKey
   agentId: String! @indexed

package/schemas/federation.graphql

@@ -0,0 +1,51 @@
+# Federation tables — hub-and-spoke sync per FLAIR-FEDERATION spec.
+
+# Instance identity — one record per Flair instance.
+type Instance @table(database: "flair") @export {
+  id: ID @primaryKey               # "flair_h82kx9" — generated on first boot
+  publicKey: String!               # Ed25519 instance key (base64url)
+  role: String @indexed            # "hub" | "spoke"
+  fabricEndpoint: String           # wss:// URL if hub
+  status: String @indexed          # "active" | "paused" | "decommissioned"
+  lastSeen: String
+  createdAt: String! @indexed
+  updatedAt: String
+}
+
+# One-time pairing tokens — generated by hub admin, consumed during peer pairing.
+type PairingToken @table(database: "flair") @export {
+  id: ID @primaryKey               # the token value (crypto random)
+  createdBy: String                # admin who generated it
+  consumedBy: String               # peer instanceId that used it
+  consumedAt: String               # when it was consumed
+  expiresAt: String! @indexed      # token TTL (default 1 hour)
+  createdAt: String! @indexed
+}
+
+# Peer records — known federation peers.
+# Hub has one entry per spoke. Spokes have one entry for the hub.
+type Peer @table(database: "flair") @export {
+  id: ID @primaryKey               # peer's instance ID
+  publicKey: String!               # peer's Ed25519 public key (pinned on first pair)
+  role: String @indexed            # "hub" | "spoke"
+  endpoint: String                 # wss:// URL for the peer
+  status: String @indexed          # "paired" | "connected" | "disconnected" | "revoked"
+  lastSyncAt: String               # last successful sync timestamp
+  lastSyncCursor: String           # Lamport clock or ISO timestamp for incremental sync
+  relayOnly: Boolean               # true for spoke-to-spoke peers announced by hub
+  pairedAt: String
+  createdAt: String! @indexed
+  updatedAt: String
+}
+
+# Sync log — audit trail for federation operations.
+type SyncLog @table(database: "flair") {
+  id: ID @primaryKey
+  peerId: String! @indexed         # which peer this sync was with
+  direction: String! @indexed      # "push" | "pull"
+  recordCount: Int                 # how many records in this sync batch
+  status: String @indexed          # "success" | "partial" | "failed"
+  error: String                    # error message if failed
+  durationMs: Int                  # how long the sync took
+  createdAt: String! @indexed
+}

package/schemas/memory.graphql

@@ -26,6 +26,26 @@ type Memory @table(database: "flair") {
   lastReflected: String     # ISO timestamp of last reflection pass
   supersedes: String @indexed  # ID of memory this one replaces (version chain)
   subject: String @indexed     # entity this memory is about (person, service, project)
+  validFrom: String @indexed   # ISO timestamp — when this fact became true
+  validTo: String @indexed     # ISO timestamp — when this fact stopped being true (null = still valid)
+  _safetyFlags: [String]       # content safety flags from scanContent()
+}
+
+# Explicit entity-to-entity relationships with temporal validity.
+# Enables queries like "who was team lead in Q1?" or "what changed about X on date Y?"
+# Inspired by knowledge graph triples with time-bounded validity windows.
+type Relationship @table(database: "flair") {
+  id: ID @primaryKey
+  agentId: String! @indexed        # who created this relationship
+  subject: String! @indexed        # source entity (person, project, service)
+  predicate: String! @indexed      # relationship type (manages, owns, depends_on, etc.)
+  object: String! @indexed         # target entity
+  validFrom: String @indexed       # when this relationship became true
+  validTo: String @indexed         # when it ended (null = still active)
+  confidence: Float                # 0.0–1.0, how certain (1.0 = explicitly stated)
+  source: String                   # where this was learned (memory ID, conversation, etc.)
+  createdAt: String! @indexed
+  updatedAt: String
 }
 
 type Soul @table(database: "flair") {

package/schemas/oauth.graphql

@@ -0,0 +1,72 @@
+# OAuth 2.1 Authorization Server tables.
+# Implements: RFC 6749 (OAuth 2.0), RFC 7591 (DCR), RFC 7636 (PKCE),
+# with 1.0 constraints from FLAIR-PRINCIPALS § 2.
+
+# Registered OAuth clients (via DCR or admin).
+# 1.0: only claude.com redirect URI permitted for DCR clients.
+type OAuthClient @table(database: "flair") @export {
+  id: ID @primaryKey                # client_id
+  clientSecret: String              # hashed — only for confidential clients
+  name: String!
+  redirectUris: [String]!           # 1.0: only ["https://claude.com/api/mcp/auth_callback"]
+  grantTypes: [String]              # ["authorization_code", "refresh_token"]
+  scope: String                     # space-separated default scopes
+  registeredBy: String @indexed     # principal ID who registered, or "dcr"
+  createdAt: String! @indexed
+  updatedAt: String
+}
+
+# Authorization codes — short-lived, single-use.
+type OAuthAuthCode @table(database: "flair") {
+  id: ID @primaryKey                # the authorization code itself (random, URL-safe)
+  clientId: String! @indexed
+  principalId: String! @indexed     # who authorized
+  redirectUri: String!
+  scope: String                     # granted scopes
+  codeChallenge: String             # PKCE S256
+  codeChallengeMethod: String       # "S256"
+  expiresAt: String! @indexed       # short TTL (10 min max)
+  used: Boolean @indexed            # single-use enforcement
+  createdAt: String!
+}
+
+# IdP configuration for XAA (Enterprise-Managed Authorization).
+# Stores trusted enterprise IdP endpoints for ID-JAG validation.
+type IdpConfig @table(database: "flair") @export {
+  id: ID @primaryKey                # stable UUID
+  name: String!                     # display name ("Harper Corporate")
+  issuer: String! @indexed          # must match ID-JAG `iss` (e.g., "https://accounts.google.com")
+  jwksUri: String!                  # JWKS endpoint for signature verification
+  clientId: String!                 # Flair's client_id at this IdP
+  requiredDomain: String            # domain boundary: `hd` (Google), `tid` (Azure), issuer-scoped (Okta)
+  jitProvision: Boolean             # auto-create principals on first login
+  defaultTrustTier: String          # "unverified" | "corroborated" for JIT principals
+  allowedScopes: [String]           # restrict which scopes this IdP can grant
+  enabled: Boolean @indexed
+  jwksCachedAt: String              # when JWKS was last fetched
+  createdAt: String! @indexed
+  updatedAt: String
+}
+
+# ID-JAG replay prevention — tracks used `jti` claims.
+type IdJagReplay @table(database: "flair") {
+  id: ID @primaryKey                # the jti value
+  expiresAt: String! @indexed       # TTL for cleanup
+  createdAt: String!
+}
+
+# Access + refresh tokens.
+type OAuthToken @table(database: "flair") {
+  id: ID @primaryKey                # token ID (internal reference)
+  tokenHash: String! @indexed       # SHA-256 of actual token — never store raw
+  tokenType: String! @indexed       # "access" | "refresh"
+  clientId: String! @indexed
+  principalId: String! @indexed
+  scope: String                     # space-separated granted scopes
+  expiresAt: String! @indexed
+  revokedAt: String                 # null = active
+  parentTokenId: String             # refresh token that generated this access token
+  idpIssuer: String                 # if token was issued via XAA, the IdP issuer
+  idpSubject: String                # if token was issued via XAA, the IdP subject
+  createdAt: String! @indexed
+}