@tpsdev-ai/flair 0.4.15 → 0.5.0

package/dist/resources/OAuth.js

@@ -0,0 +1,381 @@
+import { Resource, databases } from "@harperfast/harper";
+import { createHash, randomBytes } from "node:crypto";
+import { handleJwtBearerGrant } from "./XAA.js";
+/**
+ * OAuth 2.1 Authorization Server for Flair.
+ *
+ * Endpoints (all mapped via Harper's resource routing):
+ *   GET  /OAuthMetadata           → /.well-known/oauth-authorization-server
+ *   POST /OAuthRegister           → /oauth/register (DCR)
+ *   GET  /OAuthAuthorize          → /oauth/authorize (consent screen)
+ *   POST /OAuthToken              → /oauth/token (token exchange)
+ *   POST /OAuthRevoke             → /oauth/revoke
+ *
+ * 1.0 constraints (per FLAIR-PRINCIPALS § 2):
+ *   - Only https://claude.com/api/mcp/auth_callback permitted as redirect URI
+ *   - PKCE required (S256 only)
+ *   - Access tokens: max 1 hour
+ *   - Refresh token rotation on each use
+ *   - No "remember this decision" — each authorize is explicit
+ */
+const ALLOWED_REDIRECT_URI = "https://claude.com/api/mcp/auth_callback";
+const ACCESS_TOKEN_TTL_MS = 3600_000; // 1 hour
+const REFRESH_TOKEN_TTL_MS = 7 * 86400_000; // 7 days
+const AUTH_CODE_TTL_MS = 600_000; // 10 minutes
+function sha256(input) {
+    return createHash("sha256").update(input).digest("hex");
+}
+function randomToken(prefix) {
+    return `${prefix}${randomBytes(32).toString("base64url")}`;
+}
+function nowISO() {
+    return new Date().toISOString();
+}
+function futureISO(ms) {
+    return new Date(Date.now() + ms).toISOString();
+}
+// ─── Discovery metadata ──────────────────────────────────────────────────────
+export class OAuthMetadata extends Resource {
+    async get() {
+        const baseUrl = process.env.FLAIR_PUBLIC_URL || `http://127.0.0.1:${process.env.HTTP_PORT || 19926}`;
+        return {
+            issuer: baseUrl,
+            authorization_endpoint: `${baseUrl}/OAuthAuthorize`,
+            token_endpoint: `${baseUrl}/OAuthToken`,
+            registration_endpoint: `${baseUrl}/OAuthRegister`,
+            revocation_endpoint: `${baseUrl}/OAuthRevoke`,
+            response_types_supported: ["code"],
+            grant_types_supported: [
+                "authorization_code",
+                "refresh_token",
+                "urn:ietf:params:oauth:grant-type:jwt-bearer",
+            ],
+            token_endpoint_auth_methods_supported: ["none", "client_secret_basic"],
+            code_challenge_methods_supported: ["S256"],
+            scopes_supported: [
+                "memory:read", "memory:write", "memory:admin",
+                "principal:read", "principal:admin",
+                "connector:read", "connector:admin",
+            ],
+            extensions_supported: [
+                "io.modelcontextprotocol/enterprise-managed-authorization",
+            ],
+        };
+    }
+}
+// ─── Dynamic Client Registration (RFC 7591) ──────────────────────────────────
+export class OAuthRegister extends Resource {
+    async post(data) {
+        const redirectUris = data?.redirect_uris ?? [];
+        const clientName = data?.client_name ?? "Unknown Client";
+        // 1.0: only claude.com redirect URI permitted
+        for (const uri of redirectUris) {
+            if (uri !== ALLOWED_REDIRECT_URI) {
+                return new Response(JSON.stringify({
+                    error: "invalid_redirect_uri",
+                    error_description: `Only ${ALLOWED_REDIRECT_URI} is permitted in 1.0`,
+                }), { status: 400, headers: { "content-type": "application/json" } });
+            }
+        }
+        if (redirectUris.length === 0) {
+            redirectUris.push(ALLOWED_REDIRECT_URI);
+        }
+        const clientId = `flair_cl_${randomBytes(16).toString("base64url")}`;
+        const now = nowISO();
+        await databases.flair.OAuthClient.put({
+            id: clientId,
+            name: clientName,
+            redirectUris,
+            grantTypes: ["authorization_code", "refresh_token"],
+            scope: data?.scope ?? "memory:read memory:write",
+            registeredBy: "dcr",
+            createdAt: now,
+            updatedAt: now,
+        });
+        return {
+            client_id: clientId,
+            client_name: clientName,
+            redirect_uris: redirectUris,
+            grant_types: ["authorization_code", "refresh_token"],
+            token_endpoint_auth_method: "none",
+        };
+    }
+}
+// ─── Authorization endpoint ──────────────────────────────────────────────────
+export class OAuthAuthorize extends Resource {
+    async get() {
+        // In 1.0, this returns a simple HTML consent page.
+        // The user (Nathan) approves or denies, which POSTs back.
+        const request = this.request;
+        const url = new URL(request?.url ?? "http://localhost", "http://localhost");
+        const clientId = url.searchParams.get("client_id") ?? "";
+        const redirectUri = url.searchParams.get("redirect_uri") ?? "";
+        const responseType = url.searchParams.get("response_type") ?? "";
+        const scope = url.searchParams.get("scope") ?? "memory:read";
+        const state = url.searchParams.get("state") ?? "";
+        const codeChallenge = url.searchParams.get("code_challenge") ?? "";
+        const codeChallengeMethod = url.searchParams.get("code_challenge_method") ?? "";
+        if (responseType !== "code") {
+            return new Response(JSON.stringify({ error: "unsupported_response_type" }), {
+                status: 400, headers: { "content-type": "application/json" },
+            });
+        }
+        if (redirectUri && redirectUri !== ALLOWED_REDIRECT_URI) {
+            return new Response(JSON.stringify({ error: "invalid_redirect_uri" }), {
+                status: 400, headers: { "content-type": "application/json" },
+            });
+        }
+        // Verify client exists
+        const client = await databases.flair.OAuthClient.get(clientId);
+        if (!client) {
+            return new Response(JSON.stringify({ error: "invalid_client" }), {
+                status: 400, headers: { "content-type": "application/json" },
+            });
+        }
+        // Server-rendered consent page (minimal HTML, no JS frameworks)
+        const html = `<!DOCTYPE html>
+<html><head><title>Flair — Authorize</title>
+<style>body{font-family:system-ui;max-width:480px;margin:60px auto;padding:0 20px}
+h1{font-size:1.4em}button{padding:10px 24px;font-size:1em;border:none;border-radius:6px;cursor:pointer;margin-right:8px}
+.approve{background:#2563eb;color:#fff}.deny{background:#e5e7eb;color:#333}
+.scope{background:#f3f4f6;padding:8px 12px;border-radius:4px;margin:4px 0;font-family:monospace}</style></head>
+<body>
+<h1>Authorize ${client.name || clientId}</h1>
+<p>This application wants to access your Flair memories:</p>
+${scope.split(" ").map((s) => `<div class="scope">${s}</div>`).join("")}
+<form method="POST" action="/OAuthAuthorize" style="margin-top:24px">
+<input type="hidden" name="client_id" value="${clientId}">
+<input type="hidden" name="redirect_uri" value="${redirectUri || ALLOWED_REDIRECT_URI}">
+<input type="hidden" name="scope" value="${scope}">
+<input type="hidden" name="state" value="${state}">
+<input type="hidden" name="code_challenge" value="${codeChallenge}">
+<input type="hidden" name="code_challenge_method" value="${codeChallengeMethod}">
+<button type="submit" name="action" value="approve" class="approve">Approve</button>
+<button type="submit" name="action" value="deny" class="deny">Deny</button>
+</form></body></html>`;
+        return new Response(html, {
+            status: 200,
+            headers: { "content-type": "text/html; charset=utf-8" },
+        });
+    }
+    async post(data) {
+        const action = data?.action;
+        const clientId = data?.client_id ?? "";
+        const redirectUri = data?.redirect_uri || ALLOWED_REDIRECT_URI;
+        const scope = data?.scope ?? "memory:read";
+        const state = data?.state ?? "";
+        const codeChallenge = data?.code_challenge ?? "";
+        const codeChallengeMethod = data?.code_challenge_method ?? "S256";
+        // Sherlock 2026-04-11: validate redirect_uri in POST handler too.
+        // Without this, an attacker can CSRF the approval form with an arbitrary
+        // redirect_uri, stealing the authorization code via open redirect.
+        if (redirectUri !== ALLOWED_REDIRECT_URI) {
+            return new Response(JSON.stringify({ error: "invalid_redirect_uri" }), {
+                status: 400, headers: { "content-type": "application/json" },
+            });
+        }
+        if (action === "deny") {
+            const params = new URLSearchParams({ error: "access_denied", state });
+            return Response.redirect(`${redirectUri}?${params}`, 302);
+        }
+        // Determine authenticated principal
+        const request = this.request;
+        const principalId = request?.tpsAgent ?? "admin";
+        // Generate authorization code
+        const code = randomBytes(32).toString("base64url");
+        const now = nowISO();
+        await databases.flair.OAuthAuthCode.put({
+            id: code,
+            clientId,
+            principalId,
+            redirectUri,
+            scope,
+            codeChallenge,
+            codeChallengeMethod,
+            expiresAt: futureISO(AUTH_CODE_TTL_MS),
+            used: false,
+            createdAt: now,
+        });
+        const params = new URLSearchParams({ code, state });
+        return Response.redirect(`${redirectUri}?${params}`, 302);
+    }
+}
+// ─── Token endpoint ──────────────────────────────────────────────────────────
+export class OAuthToken extends Resource {
+    async post(data) {
+        const grantType = data?.grant_type;
+        if (grantType === "authorization_code") {
+            return this.handleAuthorizationCode(data);
+        }
+        else if (grantType === "refresh_token") {
+            return this.handleRefreshToken(data);
+        }
+        else if (grantType === "urn:ietf:params:oauth:grant-type:jwt-bearer") {
+            return handleJwtBearerGrant(data);
+        }
+        return new Response(JSON.stringify({ error: "unsupported_grant_type" }), {
+            status: 400, headers: { "content-type": "application/json" },
+        });
+    }
+    async handleAuthorizationCode(data) {
+        const code = data?.code;
+        const clientId = data?.client_id;
+        const redirectUri = data?.redirect_uri;
+        const codeVerifier = data?.code_verifier;
+        if (!code || !clientId) {
+            return new Response(JSON.stringify({ error: "invalid_request" }), {
+                status: 400, headers: { "content-type": "application/json" },
+            });
+        }
+        // Look up auth code
+        const authCode = await databases.flair.OAuthAuthCode.get(code);
+        if (!authCode) {
+            return new Response(JSON.stringify({ error: "invalid_grant" }), {
+                status: 400, headers: { "content-type": "application/json" },
+            });
+        }
+        // Validate
+        if (authCode.used) {
+            return new Response(JSON.stringify({ error: "invalid_grant", error_description: "code already used" }), {
+                status: 400, headers: { "content-type": "application/json" },
+            });
+        }
+        if (authCode.clientId !== clientId) {
+            return new Response(JSON.stringify({ error: "invalid_grant" }), {
+                status: 400, headers: { "content-type": "application/json" },
+            });
+        }
+        if (new Date(authCode.expiresAt) < new Date()) {
+            return new Response(JSON.stringify({ error: "invalid_grant", error_description: "code expired" }), {
+                status: 400, headers: { "content-type": "application/json" },
+            });
+        }
+        if (redirectUri && authCode.redirectUri !== redirectUri) {
+            return new Response(JSON.stringify({ error: "invalid_grant" }), {
+                status: 400, headers: { "content-type": "application/json" },
+            });
+        }
+        // PKCE verification
+        if (authCode.codeChallenge) {
+            if (!codeVerifier) {
+                return new Response(JSON.stringify({ error: "invalid_grant", error_description: "code_verifier required" }), {
+                    status: 400, headers: { "content-type": "application/json" },
+                });
+            }
+            const expectedChallenge = createHash("sha256").update(codeVerifier).digest("base64url");
+            if (expectedChallenge !== authCode.codeChallenge) {
+                return new Response(JSON.stringify({ error: "invalid_grant", error_description: "PKCE verification failed" }), {
+                    status: 400, headers: { "content-type": "application/json" },
+                });
+            }
+        }
+        // Mark code as used
+        await databases.flair.OAuthAuthCode.put({ ...authCode, used: true });
+        // Issue tokens
+        return this.issueTokenPair(authCode.clientId, authCode.principalId, authCode.scope);
+    }
+    async handleRefreshToken(data) {
+        const refreshTokenRaw = data?.refresh_token;
+        const clientId = data?.client_id;
+        if (!refreshTokenRaw) {
+            return new Response(JSON.stringify({ error: "invalid_request" }), {
+                status: 400, headers: { "content-type": "application/json" },
+            });
+        }
+        const tokenHash = sha256(refreshTokenRaw);
+        // Find refresh token by hash
+        let refreshRecord = null;
+        for await (const t of databases.flair.OAuthToken.search({
+            conditions: [
+                { attribute: "tokenHash", comparator: "equals", value: tokenHash },
+                { attribute: "tokenType", comparator: "equals", value: "refresh" },
+            ],
+        })) {
+            refreshRecord = t;
+            break;
+        }
+        if (!refreshRecord) {
+            return new Response(JSON.stringify({ error: "invalid_grant" }), {
+                status: 400, headers: { "content-type": "application/json" },
+            });
+        }
+        if (refreshRecord.revokedAt) {
+            return new Response(JSON.stringify({ error: "invalid_grant", error_description: "token revoked" }), {
+                status: 400, headers: { "content-type": "application/json" },
+            });
+        }
+        if (new Date(refreshRecord.expiresAt) < new Date()) {
+            return new Response(JSON.stringify({ error: "invalid_grant", error_description: "refresh token expired" }), {
+                status: 400, headers: { "content-type": "application/json" },
+            });
+        }
+        if (clientId && refreshRecord.clientId !== clientId) {
+            return new Response(JSON.stringify({ error: "invalid_grant" }), {
+                status: 400, headers: { "content-type": "application/json" },
+            });
+        }
+        // Rotate: revoke old refresh token, issue new pair
+        await databases.flair.OAuthToken.put({
+            ...refreshRecord,
+            revokedAt: nowISO(),
+        });
+        return this.issueTokenPair(refreshRecord.clientId, refreshRecord.principalId, refreshRecord.scope);
+    }
+    async issueTokenPair(clientId, principalId, scope) {
+        const now = nowISO();
+        const accessTokenRaw = randomToken("flair_at_");
+        const refreshTokenRaw = randomToken("flair_rt_");
+        const accessId = `at_${randomBytes(8).toString("hex")}`;
+        const refreshId = `rt_${randomBytes(8).toString("hex")}`;
+        await databases.flair.OAuthToken.put({
+            id: accessId,
+            tokenHash: sha256(accessTokenRaw),
+            tokenType: "access",
+            clientId,
+            principalId,
+            scope,
+            expiresAt: futureISO(ACCESS_TOKEN_TTL_MS),
+            createdAt: now,
+        });
+        await databases.flair.OAuthToken.put({
+            id: refreshId,
+            tokenHash: sha256(refreshTokenRaw),
+            tokenType: "refresh",
+            clientId,
+            principalId,
+            scope,
+            expiresAt: futureISO(REFRESH_TOKEN_TTL_MS),
+            parentTokenId: accessId,
+            createdAt: now,
+        });
+        return {
+            access_token: accessTokenRaw,
+            token_type: "Bearer",
+            expires_in: Math.floor(ACCESS_TOKEN_TTL_MS / 1000),
+            refresh_token: refreshTokenRaw,
+            scope,
+        };
+    }
+}
+// ─── Revocation endpoint ─────────────────────────────────────────────────────
+export class OAuthRevoke extends Resource {
+    async post(data) {
+        const token = data?.token;
+        if (!token) {
+            return new Response(JSON.stringify({ error: "invalid_request" }), {
+                status: 400, headers: { "content-type": "application/json" },
+            });
+        }
+        const tokenHash = sha256(token);
+        for await (const t of databases.flair.OAuthToken.search({
+            conditions: [{ attribute: "tokenHash", comparator: "equals", value: tokenHash }],
+        })) {
+            await databases.flair.OAuthToken.put({
+                ...t,
+                revokedAt: nowISO(),
+            });
+        }
+        // RFC 7009: always return 200 regardless of whether token was found
+        return {};
+    }
+}

package/dist/resources/Relationship.js

@@ -0,0 +1,96 @@
+import { databases } from "@harperfast/harper";
+import { checkRateLimit, rateLimitResponse } from "./rate-limiter.js";
+/**
+ * Relationship resource — entity-to-entity relationships with temporal validity.
+ *
+ * Enables knowledge graph queries like:
+ *   - "Who manages project X?" (active relationships)
+ *   - "Who was team lead in Q1?" (historical, validFrom/validTo bounded)
+ *   - "What changed about Nathan's role?" (all relationships for a subject, ordered by time)
+ *
+ * Relationships are scoped by agentId for multi-agent isolation.
+ * Admin agents can query across all agents.
+ */
+export class Relationship extends databases.flair.Relationship {
+    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 relationships
+        const agentCondition = { attribute: "agentId", comparator: "equals", value: authAgent };
+        if (!query?.conditions) {
+            return super.search({ conditions: [agentCondition], ...(query || {}) });
+        }
+        return super.search({
+            ...query,
+            conditions: [agentCondition, { conditions: query.conditions, operator: query.operator || "and" }],
+            operator: "and",
+        });
+    }
+    async put(content) {
+        const ctx = this.getContext?.();
+        const request = ctx?.request ?? ctx;
+        const authAgent = request?.tpsAgent;
+        if (!authAgent) {
+            return new Response(JSON.stringify({ error: "authentication required" }), {
+                status: 401, headers: { "content-type": "application/json" },
+            });
+        }
+        const rl = checkRateLimit(authAgent);
+        if (!rl.allowed)
+            return rateLimitResponse(rl.retryAfterMs, "relationship");
+        // Validate required fields
+        if (!content.subject || typeof content.subject !== "string") {
+            return new Response(JSON.stringify({ error: "subject is required (string)" }), {
+                status: 400, headers: { "content-type": "application/json" },
+            });
+        }
+        if (!content.predicate || typeof content.predicate !== "string") {
+            return new Response(JSON.stringify({ error: "predicate is required (string)" }), {
+                status: 400, headers: { "content-type": "application/json" },
+            });
+        }
+        if (!content.object || typeof content.object !== "string") {
+            return new Response(JSON.stringify({ error: "object is required (string)" }), {
+                status: 400, headers: { "content-type": "application/json" },
+            });
+        }
+        // Normalize
+        const now = new Date().toISOString();
+        content.agentId = authAgent;
+        content.subject = content.subject.toLowerCase();
+        content.predicate = content.predicate.toLowerCase();
+        content.object = content.object.toLowerCase();
+        content.createdAt = content.createdAt || now;
+        content.updatedAt = now;
+        content.validFrom = content.validFrom || now;
+        // validTo left as null/undefined for active relationships
+        content.confidence = content.confidence ?? 1.0;
+        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" },
+            });
+        }
+        // Non-admin: verify ownership before delete
+        if (!isAdminAgent) {
+            const existing = await super.get();
+            if (existing?.agentId && existing.agentId !== authAgent) {
+                return new Response(JSON.stringify({ error: "cannot delete another agent's relationship" }), {
+                    status: 403, headers: { "content-type": "application/json" },
+                });
+            }
+        }
+        return super.delete(_);
+    }
+}

package/dist/resources/SemanticSearch.js

@@ -2,6 +2,7 @@ import { Resource, databases } from "@harperfast/harper";
 import { getEmbedding, getMode } from "./embeddings-provider.js";
 import { patchRecord } from "./table-helpers.js";
 import { checkRateLimit, rateLimitResponse } from "./rate-limiter.js";
+import { wrapUntrusted } from "./content-safety.js";
 // ─── Temporal Decay + Relevance Scoring ─────────────────────────────────────
 const DURABILITY_WEIGHTS = {
     permanent: 1.0,
@@ -45,7 +46,7 @@ function distanceToSimilarity(distance) {
 const CANDIDATE_MULTIPLIER = 5;
 export class SemanticSearch extends Resource {
     async post(data) {
-        const { agentId, q, queryEmbedding, tag, subject, subjects, limit = 10, includeSuperseded = false, scoring = "composite", minScore = 0, since } = data || {};
+        const { agentId, q, queryEmbedding, tag, subject, subjects, limit = 10, includeSuperseded = false, scoring = "composite", minScore = 0, since, asOf } = data || {};
         // Rate limiting — use authenticated agent ID from request context, not client-supplied body
         const rateLimitAgent = this.request?.headers?.get?.("x-tps-agent")
             ?? this.request?.tpsAgent;
@@ -171,7 +172,7 @@ export class SemanticSearch extends Resource {
                     "source", "createdAt", "updatedAt", "expiresAt", "retrievalCount", "lastRetrieved",
                     "promotionStatus", "promotedAt", "promotedBy", "archived", "archivedAt", "archivedBy",
                     "parentId", "derivedFrom", "sessionId", "lastReflected", "supersedes", "subject",
-                    "$distance"],
+                    "validFrom", "validTo", "_safetyFlags", "$distance"],
                 limit: candidateLimit,
             };
             if (conditions.length > 0) {
@@ -182,6 +183,11 @@ export class SemanticSearch extends Resource {
                     continue;
                 if (sinceDate && record.createdAt && new Date(record.createdAt) < sinceDate)
                     continue;
+                // Temporal validity: if asOf is specified, only include memories valid at that point
+                if (asOf && record.validFrom && record.validFrom > asOf)
+                    continue;
+                if (asOf && record.validTo && record.validTo <= asOf)
+                    continue;
                 const semanticScore = distanceToSimilarity(record.$distance ?? 1);
                 let keywordHit = false;
                 if (q && String(record.content || "").toLowerCase().includes(String(q).toLowerCase())) {
@@ -192,11 +198,14 @@ export class SemanticSearch extends Resource {
                 if (temporalBoost > 1.0)
                     finalScore *= temporalBoost;
                 const { $distance, ...rest } = record;
+                const isFlagged = rest._safetyFlags && Array.isArray(rest._safetyFlags) && rest._safetyFlags.length > 0;
+                const source = record.agentId !== agentId ? record.agentId : undefined;
                 results.push({
                     ...rest,
+                    content: isFlagged ? wrapUntrusted(rest.content, source) : rest.content,
                     _score: Math.round(finalScore * 1000) / 1000,
                     _rawScore: scoring !== "raw" ? Math.round(rawScore * 1000) / 1000 : undefined,
-                    _source: record.agentId !== agentId ? record.agentId : undefined,
+                    _source: source,
                 });
             }
         }
@@ -210,6 +219,10 @@ export class SemanticSearch extends Resource {
                     continue;
                 if (sinceDate && record.createdAt && new Date(record.createdAt) < sinceDate)
                     continue;
+                if (asOf && record.validFrom && record.validFrom > asOf)
+                    continue;
+                if (asOf && record.validTo && record.validTo <= asOf)
+                    continue;
                 let keywordHit = false;
                 if (q && String(record.content || "").toLowerCase().includes(String(q).toLowerCase())) {
                     keywordHit = true;
@@ -221,11 +234,14 @@ export class SemanticSearch extends Resource {
                 let finalScore = scoring === "raw" ? rawScore : compositeScore(rawScore, rest);
                 if (temporalBoost > 1.0)
                     finalScore *= temporalBoost;
+                const isFlagged = rest._safetyFlags && Array.isArray(rest._safetyFlags) && rest._safetyFlags.length > 0;
+                const source = record.agentId !== agentId ? record.agentId : undefined;
                 results.push({
                     ...rest,
+                    content: isFlagged ? wrapUntrusted(rest.content, source) : rest.content,
                     _score: Math.round(finalScore * 1000) / 1000,
                     _rawScore: scoring !== "raw" ? Math.round(rawScore * 1000) / 1000 : undefined,
-                    _source: record.agentId !== agentId ? record.agentId : undefined,
+                    _source: source,
                 });
             }
         }