@tpsdev-ai/flair 0.8.2 → 0.9.0

package/dist/resources/AdminInstance.js

@@ -1,15 +1,61 @@
 import { Resource } from "@harperfast/harper";
 import { layout, htmlResponse } from "./admin-layout.js";
-import { join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
 import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+/**
+ * Resolve the public URL operators reach this Flair on.
+ *
+ * Production deployments (Fabric, VPS-hosted, behind any reverse proxy)
+ * should set `FLAIR_PUBLIC_URL` in their launchd / systemd unit. The
+ * admin pane then shows the URL operators actually type — not the
+ * 127.0.0.1 binding address Harper sees internally — so the Endpoints
+ * table is copy-pasteable.
+ *
+ * Fall back to `http://127.0.0.1:${HTTP_PORT}` for local-only installs.
+ */
+function resolvePublicUrl() {
+    // Explicit override wins. Production deployments (Fabric, VPS-hosted)
+    // should set FLAIR_PUBLIC_URL in their launchd / systemd unit so the
+    // admin pane shows the URL operators actually type, not the binding
+    // address Harper sees internally. Auto-detecting from request headers
+    // is brittle across reverse-proxy configurations.
+    if (process.env.FLAIR_PUBLIC_URL) {
+        return process.env.FLAIR_PUBLIC_URL.replace(/\/$/, "");
+    }
+    return `http://127.0.0.1:${process.env.HTTP_PORT ?? "19926"}`;
+}
+/**
+ * Read the runtime package version from the bundled package.json so the
+ * Instance pane shows the real version (e.g. 0.8.3) rather than "dev" —
+ * `process.env.npm_package_version` is only populated inside `npm run`.
+ */
+function resolveVersion() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const candidates = [
+            join(here, "..", "..", "package.json"),
+            join(here, "..", "package.json"),
+        ];
+        for (const p of candidates) {
+            if (existsSync(p)) {
+                const pkg = JSON.parse(readFileSync(p, "utf-8"));
+                if (pkg.version)
+                    return pkg.version;
+            }
+        }
+    }
+    catch { /* fall through */ }
+    return process.env.npm_package_version ?? "dev";
+}
 /**
  * GET /AdminInstance — instance info, public key, version.
  */
 export class AdminInstance extends Resource {
     async get() {
-        const version = process.env.npm_package_version ?? "dev";
-        const httpPort = process.env.HTTP_PORT ?? "19926";
-        const publicUrl = process.env.FLAIR_PUBLIC_URL ?? `http://127.0.0.1:${httpPort}`;
+        const version = resolveVersion();
+        const publicUrl = resolvePublicUrl();
         // Try to read instance public key
         let publicKey = "—";
         const keyDir = join(homedir(), ".flair", "keys");

package/dist/resources/AdminMemory.js

@@ -41,10 +41,16 @@ export class AdminMemory extends Resource {
             if (subject) {
                 conditions.push({ attribute: "subject", comparator: "equals", value: subject.toLowerCase() });
             }
-            conditions.push({ attribute: "archived", comparator: "not_equal", value: true });
+            // Note: Harper's `not_equal true` predicate doesn't match rows where
+            // `archived` is `false` *or* unset — boolean comparators behave
+            // unevenly across boolean / undefined / null storage states. We skip
+            // archived rows in the JS-side filter loop below instead, so the list
+            // view actually returns non-archived memories rather than zero.
             const searchQuery = conditions.length > 0 ? { conditions } : {};
             let count = 0;
             for await (const m of databases.flair.Memory.search(searchQuery)) {
+                if (m.archived === true)
+                    continue;
                 if (m.expiresAt && Date.parse(m.expiresAt) < Date.now())
                     continue;
                 if (query && !String(m.content || "").toLowerCase().includes(query.toLowerCase()))

package/dist/resources/MemoryMaintenance.js

@@ -1,34 +1,56 @@
 /**
  * MemoryMaintenance.ts — Maintenance worker for memory hygiene.
  *
- * POST /MemoryMaintenance/ — runs cleanup tasks:
+ * POST /MemoryMaintenance — runs cleanup tasks:
  *   1. Delete expired ephemeral memories (expiresAt < now)
  *   2. Archive old session memories (> 30 days, standard durability)
  *   3. Report stats
  *
- * Designed to run periodically (daily cron or heartbeat).
- * Requires admin auth.
+ * Designed to run periodically (daily cron, scheduler, or REM nightly cycle).
+ * Authenticated via Ed25519 (agent acts on own memories) or admin (system-wide).
+ *
+ * History: prior to slice-2 PR-3, this class used a static-ROUTE pattern
+ * (`export default class MemoryMaintenance` with `static ROUTE`/`METHOD`)
+ * that Harper 5.x does not auto-register. Both `flair rem light` and the
+ * REM nightly runner were returning "Not found" against the endpoint.
+ * Migrated to the standard `extends Resource` shape with `allowCreate()`
+ * to gate auth correctly.
  */
-export default class MemoryMaintenance {
-    static ROUTE = "MemoryMaintenance";
-    static METHOD = "POST";
+import { Resource, databases } from "@harperfast/harper";
+import { isAdmin } from "./auth-middleware.js";
+export class MemoryMaintenance extends Resource {
+    /** POST requires auth — either an agent acting on its own memories, or admin. */
+    allowCreate() {
+        const ctx = this.getContext?.();
+        const request = ctx?.request ?? ctx;
+        return !!(request?.tpsAgent || request?.tpsAgentIsAdmin);
+    }
     async post(data) {
-        const { databases } = this;
-        const request = this.request;
-        const { dryRun = false, agentId } = data || {};
-        // Scope to authenticated agent. Admin can pass agentId for system-wide
-        // maintenance; non-admin always scoped to their own agent.
-        const authAgent = request?.headers?.get?.("x-tps-agent");
-        const isAdmin = request?.tpsAgentIsAdmin === true;
-        const targetAgent = isAdmin && agentId ? agentId : authAgent;
-        if (!targetAgent && !isAdmin) {
-            return { error: "agentId required" };
+        const { dryRun = false, agentId: bodyAgentId } = data || {};
+        const ctx = this.getContext?.();
+        const request = ctx?.request ?? ctx;
+        const actorId = request?.tpsAgent;
+        const callerIsAdmin = request?.tpsAgentIsAdmin === true
+            || (actorId ? await isAdmin(actorId) : false);
+        // Scope rules:
+        //   - Admin can pass agentId to maintain a specific agent (or omit it
+        //     for fleet-wide maintenance).
+        //   - Non-admin agents are scoped to their own memories — bodyAgentId
+        //     either matches the authenticated agent or is ignored.
+        const targetAgent = callerIsAdmin
+            ? bodyAgentId
+            : actorId;
+        if (!targetAgent && !callerIsAdmin) {
+            return new Response(JSON.stringify({ error: "agentId required" }), {
+                status: 400,
+                headers: { "content-type": "application/json" },
+            });
         }
         const now = new Date();
         const stats = { expired: 0, archived: 0, total: 0, errors: 0, agent: targetAgent || "all" };
         try {
             for await (const record of databases.flair.Memory.search()) {
-                // Skip records not belonging to target agent (unless admin running system-wide)
+                // Skip records not belonging to target agent (unless admin running fleet-wide).
                 if (targetAgent && record.agentId !== targetAgent)
                     continue;
                 stats.total++;
@@ -48,9 +70,9 @@ export default class MemoryMaintenance {
                     }
                     continue;
                 }
-                // 2. Archive old standard session memories (> 30 days)
-                // These are low-value session notes that weren't promoted to persistent.
-                // Archiving removes them from search results but keeps the data.
+                // 2. Archive old standard session memories (> 30 days). These are
+                // low-value session notes that weren't promoted to persistent.
+                // Soft-archive removes them from search results but keeps the data.
                 if (record.durability === "standard" &&
                     record.type === "session" &&
                     !record.archived &&
@@ -60,7 +82,6 @@ export default class MemoryMaintenance {
                     if (ageDays > 30) {
                         if (!dryRun) {
                             try {
-                                // Soft archive — set archived flag, keep data
                                 await databases.flair.Memory.update(record.id, {
                                     ...record,
                                     archived: true,
@@ -80,11 +101,18 @@ export default class MemoryMaintenance {
             }
         }
         catch (err) {
-            return { error: err.message, stats };
+            return new Response(JSON.stringify({ error: err.message, stats }), { status: 500, headers: { "content-type": "application/json" } });
         }
+        // Flatten the historical { stats } wrapper into the top level so callers
+        // can read `.expired` / `.archived` directly. The wrapper shape is kept
+        // for backward compatibility with `flair rem light`.
         return {
             message: dryRun ? "Dry run complete" : "Maintenance complete",
             stats,
+            expired: stats.expired,
+            archived: stats.archived,
+            total: stats.total,
+            errors: stats.errors,
         };
     }
 }

package/dist/resources/OAuth.js

@@ -36,6 +36,12 @@ function futureISO(ms) {
 }
 // ─── Discovery metadata ──────────────────────────────────────────────────────
 export class OAuthMetadata extends Resource {
+    // OAuth discovery metadata is intentionally public — RFC 8414 § 3 requires
+    // it be accessible without authentication so clients can bootstrap their
+    // flow. `allowRead() { return true }` opens Harper's role gate so remote
+    // operators (e.g. Fabric-hosted Flair) get the metadata document instead
+    // of a 401 from Harper's intrinsic auth layer. Same pattern as Health (#386).
+    allowRead() { return true; }
     async get() {
         const baseUrl = process.env.FLAIR_PUBLIC_URL || `http://127.0.0.1:${process.env.HTTP_PORT || 19926}`;
         return {
@@ -65,6 +71,10 @@ export class OAuthMetadata extends Resource {
 }
 // ─── Dynamic Client Registration (RFC 7591) ──────────────────────────────────
 export class OAuthRegister extends Resource {
+    // Dynamic Client Registration (RFC 7591) — clients must be able to register
+    // anonymously to bootstrap. Validation (redirect_uri allow-list, etc.)
+    // happens in post(). Pattern matches FederationPair.allowCreate (#299).
+    allowCreate() { return true; }
     async post(data) {
         const redirectUris = data?.redirect_uris ?? [];
         const clientName = data?.client_name ?? "Unknown Client";
@@ -103,6 +113,11 @@ export class OAuthRegister extends Resource {
 }
 // ─── Authorization endpoint ──────────────────────────────────────────────────
 export class OAuthAuthorize extends Resource {
+    // OAuth authorize endpoint must accept anonymous GET/POST — the whole
+    // point of authorize is to start an unauthenticated user's flow. PKCE
+    // and state-parameter validation in the handler enforce real auth.
+    allowRead() { return true; }
+    allowCreate() { return true; }
     async get() {
         // In 1.0, this returns a simple HTML consent page.
         // The user (Nathan) approves or denies, which POSTs back.
@@ -202,6 +217,10 @@ ${scope.split(" ").map((s) => `<div class="scope">${s}</div>`).join("")}
 }
 // ─── Token endpoint ──────────────────────────────────────────────────────────
 export class OAuthToken extends Resource {
+    // OAuth token exchange — client must hit this without prior Harper auth
+    // since they're trading code/refresh for a token. Authentication is in
+    // the post() handler via PKCE verifier + client_secret_basic.
+    allowCreate() { return true; }
     async post(data) {
         const grantType = data?.grant_type;
         if (grantType === "authorization_code") {
@@ -359,6 +378,9 @@ export class OAuthToken extends Resource {
 }
 // ─── Revocation endpoint ─────────────────────────────────────────────────────
 export class OAuthRevoke extends Resource {
+    // RFC 7009 — token revocation accepts the token itself as proof; clients
+    // may not have a separate auth credential. Handler validates the token.
+    allowCreate() { return true; }
     async post(data) {
         const token = data?.token;
         if (!token) {

package/dist/resources/ObservationCenter.js

@@ -10,6 +10,10 @@ const HTML = readFileSync(HTML_PATH, "utf8");
  * The HTML handles its own Basic-auth prompt and polls authenticated JSON endpoints.
  */
 export class ObservationCenter extends Resource {
+    // The dashboard shell is just HTML + inline JS; the JS prompts the user
+    // for admin-pass and authenticates each API call. The shell itself is
+    // intentionally public so it can render before auth happens.
+    allowRead() { return true; }
     async get() {
         return new Response(HTML, {
             status: 200,

package/dist/resources/SkillScan.js

@@ -1,101 +1,44 @@
 import { Resource } from "@harperfast/harper";
-const SHELL_PATTERNS = [
-    { regex: /\bexec\s*\(/, type: "shell_command" },
-    { regex: /\bspawn\s*\(/, type: "shell_command" },
-    { regex: /\bsystem\s*\(/, type: "shell_command" },
-    { regex: /`[^`]*`/, type: "shell_backtick" },
-    { regex: /\bchild_process\b/, type: "shell_command" },
-];
-const NETWORK_PATTERNS = [
-    { regex: /\bfetch\s*\(/, type: "network_call" },
-    { regex: /\bcurl\b/, type: "network_call" },
-    { regex: /https?:\/\//, type: "url_reference" },
-    { regex: /\bXMLHttpRequest\b/, type: "network_call" },
-    { regex: /\baxios\b/, type: "network_call" },
-];
-const FS_PATTERNS = [
-    { regex: /\bfs\.write/, type: "fs_write" },
-    { regex: /\bwriteFile/, type: "fs_write" },
-    { regex: />[>]?\s*[\/~]/, type: "fs_redirect" },
-];
-const ENV_PATTERNS = [
-    { regex: /\bprocess\.env\b/, type: "env_access" },
-    { regex: /\$ENV\b/, type: "env_access" },
-    { regex: /\$\{?\w+\}?/, type: "env_variable" },
-];
-const ENCODING_PATTERNS = [
-    { regex: /\batob\s*\(/, type: "base64_decode" },
-    { regex: /\bbtoa\s*\(/, type: "base64_encode" },
-    { regex: /Buffer\.from\s*\([^)]*,\s*['"]base64['"]/, type: "base64_decode" },
-    { regex: /Buffer\.from\s*\([^)]*,\s*['"]hex['"]/, type: "hex_decode" },
-    { regex: /\\x[0-9a-fA-F]{2}/, type: "hex_escape" },
-    { regex: /\\u200[b-f]|\\u2060|\\ufeff/, type: "zero_width_char" },
-];
-// Unicode zero-width and homoglyph detection (raw chars)
-const UNICODE_PATTERNS = [
-    { regex: /[\u200B-\u200F\u2060\uFEFF]/, type: "zero_width_char" },
-    { regex: /[\u0410-\u044F]/, type: "cyrillic_homoglyph" }, // Cyrillic chars that look like Latin
-];
-const ALL_PATTERNS = [
-    ...SHELL_PATTERNS,
-    ...NETWORK_PATTERNS,
-    ...FS_PATTERNS,
-    ...ENV_PATTERNS,
-    ...ENCODING_PATTERNS,
-    ...UNICODE_PATTERNS,
-];
-function assessRisk(violations) {
-    if (violations.length === 0)
-        return "low";
-    const types = new Set(violations.map((v) => v.type));
-    const hasShell = types.has("shell_command") || types.has("shell_backtick");
-    const hasNetwork = types.has("network_call");
-    const hasFs = types.has("fs_write") || types.has("fs_redirect");
-    const hasZeroWidth = types.has("zero_width_char");
-    const hasHomoglyph = types.has("cyrillic_homoglyph");
-    // Critical: shell + encoding, or zero-width/homoglyph obfuscation
-    if ((hasShell && (types.has("base64_decode") || types.has("hex_decode"))) ||
-        hasZeroWidth || hasHomoglyph) {
-        return "critical";
-    }
-    // High: direct shell commands or fs writes
-    if (hasShell || hasFs)
-        return "high";
-    // Medium: network calls or encoding without shell
-    if (hasNetwork || types.has("base64_decode") || types.has("hex_decode"))
-        return "medium";
-    return "low";
-}
+import { scanSkillContent } from "./scan/skill-scanner.js";
+/**
+ * POST /SkillScan/
+ *
+ * Static analysis of skill content for security violations.
+ * Scans for shell commands, network calls, fs writes, env access,
+ * encoded payloads, zero-width chars, and homoglyphs.
+ *
+ * Request:  { content: string }
+ * Response: { safe, violations, riskLevel }
+ *
+ * Auth: any authenticated agent (read-only analysis).
+ * Size limit: 8KB (8192 bytes).
+ *
+ * Scanner logic lives in `./scan/skill-scanner.ts` (pure module, no Harper
+ * runtime deps) so unit tests can exercise it without instantiating the
+ * Harper database.
+ *
+ * Markdown awareness:
+ *  - Inline `single-token` backticks (markdown identifier convention) are NOT
+ *    flagged. Only inline backticks whose content actually looks shell-ish
+ *    (whitespace, pipe, semicolon, env-var, $(), &&, ||) fire shell_backtick.
+ *  - Fenced ```code blocks``` with no language hint or a shell-family
+ *    language (sh|bash|shell|zsh) are scanned for shell patterns. Non-shell
+ *    language hints (json, yaml, ts, py, graphql, etc.) skip the shell
+ *    patterns but keep network/fs/encoding/unicode detection active — those
+ *    are language-agnostic attack surfaces.
+ *  - This prevents the documentation-as-skill false-positive class without
+ *    weakening detection on actual shell content.
+ */
 export class SkillScan extends Resource {
-    async post(data, context) {
+    async post(data, _context) {
         const { content } = data || {};
         if (!content || typeof content !== "string") {
             return new Response(JSON.stringify({ error: "content (string) required" }), { status: 400, headers: { "Content-Type": "application/json" } });
         }
-        // 8KB size limit
         const byteLength = new TextEncoder().encode(content).length;
         if (byteLength > 8192) {
             return new Response(JSON.stringify({ error: `Content exceeds 8KB limit (${byteLength} bytes)` }), { status: 413, headers: { "Content-Type": "application/json" } });
         }
-        const lines = content.split("\n");
-        const violations = [];
-        for (let i = 0; i < lines.length; i++) {
-            const line = lines[i];
-            for (const pattern of ALL_PATTERNS) {
-                if (pattern.regex.test(line)) {
-                    violations.push({
-                        type: pattern.type,
-                        line: i + 1,
-                        content: line.trim().slice(0, 200),
-                    });
-                }
-            }
-        }
-        const riskLevel = assessRisk(violations);
-        return {
-            safe: violations.length === 0,
-            violations,
-            riskLevel,
-        };
+        return scanSkillContent(content);
     }
 }

package/dist/resources/admin-layout.js

@@ -2,7 +2,31 @@
  * Shared HTML layout for the Flair web admin.
  * Server-rendered, no JS framework. Minimal CSS for Nathan-grade UX.
  */
-const VERSION = process.env.npm_package_version ?? "dev";
+import { existsSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+// Resolve the runtime package version from package.json — process.env.npm_package_version
+// is only populated inside `npm run`, so it returned "dev" in production and rendered
+// "vdev" in the admin sidebar footer for anyone running the published binary.
+function resolveVersion() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const candidates = [
+            join(here, "..", "..", "package.json"),
+            join(here, "..", "package.json"),
+        ];
+        for (const p of candidates) {
+            if (existsSync(p)) {
+                const pkg = JSON.parse(readFileSync(p, "utf-8"));
+                if (pkg.version)
+                    return pkg.version;
+            }
+        }
+    }
+    catch { /* fall through */ }
+    return process.env.npm_package_version ?? "dev";
+}
+const VERSION = resolveVersion();
 /** Escape HTML special characters to prevent stored XSS. */
 export function esc(str) {
     if (!str)

package/dist/resources/auth-middleware.js

@@ -220,6 +220,20 @@ server.http(async (request, nextLayer) => {
     // ── Ed25519 agent auth ────────────────────────────────────────────────────
     const m = header.match(/^TPS-Ed25519\s+([^:]+):(\d+):([^:]+):(.+)$/);
     if (!m) {
+        // For browser-accessible admin pages, emit `WWW-Authenticate: Basic` so
+        // the browser shows a native auth dialog instead of a bare 401 page.
+        // JSON API endpoints don't get this — they should keep the structured
+        // 401 body so the client can parse the error.
+        const isAdminPage = url.pathname === "/Admin" || url.pathname.startsWith("/Admin");
+        if (isAdminPage) {
+            return new Response("Authentication required.", {
+                status: 401,
+                headers: {
+                    "WWW-Authenticate": 'Basic realm="Flair Admin"',
+                    "content-type": "text/plain; charset=utf-8",
+                },
+            });
+        }
         return new Response(JSON.stringify({ error: "missing_or_invalid_authorization" }), { status: 401 });
     }
     const [, agentId, tsRaw, nonce, signatureB64] = m;

package/dist/resources/health.js

@@ -17,13 +17,32 @@ const exists = async (path) => {
     }
 };
 /**
- * Health endpoint — unauthenticated, returns only { ok: true }.
+ * Health endpoint — truly public, returns only { ok: true }.
+ *
+ * `allowRead() { return true }` opens Harper's role gate for anonymous GETs,
+ * which is what makes /Health work for callers outside `authorizeLocal`'s
+ * localhost-bypass. Without this, Harper's intrinsic Basic-auth gate fires
+ * BEFORE our HTTP middleware can apply the /Health bypass list in
+ * auth-middleware.ts, so remote callers (e.g., from rockit hitting a Fabric-
+ * hosted Flair) get a 401 even though the Resource handler is intentionally
+ * unauthenticated. Symptom matched: Fabric returned 401 + WWW-Authenticate:
+ * Basic on /Health while rockit-localhost returned 200 — the difference was
+ * Harper's localhost-auto-auth, not anything in our code.
+ *
+ * Same pattern as `FederationPair.allowCreate(){ return true }` (PR #299):
+ * declare the Resource anonymously-accessible at the Harper layer; let the
+ * handler itself enforce whatever it needs (in this case, nothing — /Health
+ * is intentionally and always public).
  *
  * 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 {
+    // Anyone can call /Health — no auth, no role check. Truly public.
+    allowRead(_user) {
+        return true;
+    }
     async get() {
         return { ok: true };
     }