@tpsdev-ai/flair 0.8.3 → 0.10.0

package/dist/resources/auth-middleware.js

@@ -110,12 +110,18 @@ async function backfillEmbedding(memoryId) {
 // ─── HTTP middleware ──────────────────────────────────────────────────────────
 server.http(async (request, nextLayer) => {
     const url = new URL(request.url, "http://" + (request.headers.get("host") || "localhost"));
+    // A2A discovery endpoints: GET returns public agent-card metadata (per
+    // A2A spec, cards are intentionally public). POST invokes JSON-RPC
+    // actions (message/send writes OrgEvents on behalf of agents,
+    // tasks/list reads Beads issues, message/stream subscribes to
+    // OrgEvents) — those must be authenticated. Narrowing to GET-only
+    // closes the P0 where any caller could forge OrgEvents as any agent
+    // and read all internal Beads issues unauthenticated.
+    const isA2APath = url.pathname === "/a2a" || url.pathname === "/A2AAdapter" || url.pathname.startsWith("/A2AAdapter/");
     if (url.pathname === "/health" ||
         url.pathname === "/Health" ||
-        url.pathname === "/a2a" ||
-        url.pathname === "/A2AAdapter" ||
+        (request.method === "GET" && isA2APath) ||
         url.pathname === "/AgentCard" ||
-        url.pathname.startsWith("/A2AAdapter/") ||
         url.pathname.startsWith("/AgentCard/") ||
         // FederationSync uses Ed25519 body-signature auth with anti-replay, validated
         // by the resource handler (allowCreate=true, same pattern as FederationPair).
@@ -220,6 +226,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/federation-classify.js

@@ -0,0 +1,29 @@
+/**
+ * Pure classifier for federation sync records — no Harper imports.
+ *
+ * Extracted from Federation.ts so the decision can be unit-tested without
+ * spinning up Harper's database module. The same SkipReason names are used
+ * in SyncLog.skippedReasons so operators can grep for them.
+ */
+export function classifyRecord(record, peerRole, receiverInstanceId, local, knownTables, now = new Date()) {
+    if (!knownTables.has(record.table)) {
+        return { action: "skip", reason: "unknown_table" };
+    }
+    const originator = record.originatorInstanceId ?? receiverInstanceId;
+    if (originator !== receiverInstanceId && peerRole !== "hub") {
+        return { action: "skip", reason: "non_originator" };
+    }
+    const fiveMinFromNow = new Date(now.getTime() + 5 * 60 * 1000).toISOString();
+    if (record.updatedAt > fiveMinFromNow) {
+        return { action: "skip", reason: "future_timestamp" };
+    }
+    const remoteContentHash = record.data?.contentHash;
+    if (local &&
+        local.contentHash &&
+        remoteContentHash &&
+        local.contentHash === remoteContentHash &&
+        record.updatedAt <= (local.updatedAt ?? "")) {
+        return { action: "skip", reason: "no_op_same_hash" };
+    }
+    return { action: "merge", originator };
+}

package/dist/resources/health.js

@@ -201,13 +201,18 @@ export class HealthDetail extends Resource {
             for await (const s of db.flair.Soul.search({}))
                 souls.push(s);
             stats.soulEntries = souls.length;
-            const byPriority = { critical: 0, high: 0, standard: 0, low: 0 };
+            // Soul entries have no severity dimension — they are keyed identity facts
+            // (role / project / standards / …). A per-priority breakdown was dead
+            // telemetry: nothing writes Soul.priority to anything but "standard", and
+            // the `?? "standard"` fallback also mislabelled *unset* as *standard*, so
+            // it always read 100% standard regardless of the data. Report the honest
+            // dimension instead — a count per key.
+            const byKey = {};
             for (const s of souls) {
-                const p = (s.priority ?? "standard");
-                if (p in byPriority)
-                    byPriority[p]++;
+                const k = (s.key ?? "(unkeyed)");
+                byKey[k] = (byKey[k] ?? 0) + 1;
             }
-            stats.soul = { total: souls.length, byPriority };
+            stats.soul = { total: souls.length, byKey };
         }
         catch {
             stats.soulEntries = null;

package/dist/resources/scan/skill-scanner.js

@@ -0,0 +1,166 @@
+/**
+ * Skill content static analyzer — pure, no Harper runtime deps.
+ *
+ * Imported by `resources/SkillScan.ts` (the HTTP Resource) and by unit
+ * tests in `test/unit/SkillScan.test.ts`. Keeping the scanner logic in a
+ * separate module lets the tests run without instantiating the Harper
+ * runtime.
+ *
+ * See SkillScan.ts for the design rationale on markdown awareness and the
+ * language-agnostic vs shell-only pattern split.
+ */
+const SHELL_PATTERNS = [
+    { regex: /\bexec\s*\(/, type: "shell_command" },
+    { regex: /\bspawn\s*\(/, type: "shell_command" },
+    { regex: /\bsystem\s*\(/, type: "shell_command" },
+    { 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" },
+];
+const UNICODE_PATTERNS = [
+    { regex: /[​-‏⁠]/, type: "zero_width_char" },
+    { regex: /[А-я]/, type: "cyrillic_homoglyph" },
+];
+const LANG_AGNOSTIC_PATTERNS = [
+    ...NETWORK_PATTERNS,
+    ...FS_PATTERNS,
+    ...ENV_PATTERNS,
+    ...ENCODING_PATTERNS,
+    ...UNICODE_PATTERNS,
+];
+const SHELL_FENCE_LANGS = new Set(["", "sh", "bash", "shell", "zsh"]);
+const MARKDOWN_IDENTIFIER_RE = /^[\w@./-]+$/;
+const SHELL_BACKTICK_INDICATORS = [
+    /\s/,
+    /[|;&]/,
+    /\$\(/,
+    /\$\{/,
+    /^\$\w/,
+    />/,
+    /<\(/,
+];
+function lineHasShellishBacktick(line) {
+    const matches = line.match(/`([^`\n]+)`/g);
+    if (!matches)
+        return false;
+    for (const raw of matches) {
+        const inner = raw.slice(1, -1);
+        if (MARKDOWN_IDENTIFIER_RE.test(inner))
+            continue;
+        for (const indicator of SHELL_BACKTICK_INDICATORS) {
+            if (indicator.test(inner))
+                return true;
+        }
+    }
+    return false;
+}
+function assessRisk(violations) {
+    if (violations.length === 0)
+        return "low";
+    const types = new Set(violations.map((v) => v.type));
+    // Programmatic shell call patterns: exec/spawn/system/child_process. These
+    // are definite payloads when they appear in a skill.
+    const hasShellCommand = types.has("shell_command");
+    // Backticked shell-ish content in markdown prose. Could be `npm run deploy`
+    // in documentation (medium), or could combine with other smells (high).
+    const hasShellBacktick = types.has("shell_backtick");
+    const hasFs = types.has("fs_write") || types.has("fs_redirect");
+    const hasEncoding = types.has("base64_decode") || types.has("hex_decode");
+    const hasZeroWidth = types.has("zero_width_char");
+    const hasHomoglyph = types.has("cyrillic_homoglyph");
+    // Critical: any shell combined with encoded payloads, OR obfuscation chars.
+    if (((hasShellCommand || hasShellBacktick) && hasEncoding) ||
+        hasZeroWidth ||
+        hasHomoglyph) {
+        return "critical";
+    }
+    // High: programmatic shell, fs writes, or shell-backtick + other smells
+    // (env access, network call). A skill that quotes a command AND reads env
+    // AND fetches a URL is doing something, not just documenting.
+    const hasOtherSmells = types.has("env_access") ||
+        types.has("env_variable") ||
+        types.has("network_call") ||
+        types.has("url_reference");
+    if (hasShellCommand || hasFs || (hasShellBacktick && hasOtherSmells)) {
+        return "high";
+    }
+    // Medium: shell_backtick alone (doc reference), or network/encoding
+    // without shell. Reviewable but not blocked.
+    if (hasShellBacktick || hasOtherSmells || hasEncoding) {
+        return "medium";
+    }
+    return "low";
+}
+function detectFenceTransition(line, state) {
+    const m = line.match(/^[ \t]*```([\w.-]*)\s*$/);
+    if (!m)
+        return false;
+    if (state.inFence) {
+        state.inFence = false;
+        state.lang = "";
+    }
+    else {
+        state.inFence = true;
+        state.lang = (m[1] || "").toLowerCase();
+    }
+    return true;
+}
+export function scanSkillContent(content) {
+    const lines = content.split("\n");
+    const violations = [];
+    const fence = { inFence: false, lang: "" };
+    const recordIfMatch = (lineIndex, line, patterns) => {
+        for (const pattern of patterns) {
+            if (pattern.regex.test(line)) {
+                violations.push({
+                    type: pattern.type,
+                    line: lineIndex + 1,
+                    content: line.trim().slice(0, 200),
+                });
+            }
+        }
+    };
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? "";
+        if (detectFenceTransition(line, fence))
+            continue;
+        const insideShellFence = fence.inFence && SHELL_FENCE_LANGS.has(fence.lang);
+        const insideNonShellFence = fence.inFence && !insideShellFence;
+        if (!fence.inFence && lineHasShellishBacktick(line)) {
+            violations.push({
+                type: "shell_backtick",
+                line: i + 1,
+                content: line.trim().slice(0, 200),
+            });
+        }
+        if (!insideNonShellFence) {
+            recordIfMatch(i, line, SHELL_PATTERNS);
+        }
+        recordIfMatch(i, line, LANG_AGNOSTIC_PATTERNS);
+    }
+    const riskLevel = assessRisk(violations);
+    return { safe: violations.length === 0, violations, riskLevel };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.8.3",
+  "version": "0.10.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",
@@ -30,6 +30,7 @@
   "files": [
     "dist/",
     "schemas/",
+    "templates/",
     "ui/",
     "config.yaml",
     "LICENSE",

package/schemas/federation.graphql

@@ -30,7 +30,8 @@ type Peer @table(database: "flair") @export {
   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
+  lastSyncAt: String               # last contact with this peer (liveness signal)
+  lastMergeAt: String              # last sync where merged > 0 (data-progress signal)
   lastSyncCursor: String           # Lamport clock or ISO timestamp for incremental sync
   relayOnly: Boolean               # true for spoke-to-spoke peers announced by hub
   pairedAt: String
@@ -43,9 +44,11 @@ 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
+  recordCount: Int                 # how many records merged in this batch
+  skippedCount: Int                # how many records skipped (sum of skippedReasons)
+  skippedReasons: String           # JSON: { unknown_table: N, non_originator: N, future_timestamp: N, no_op_same_hash: N, merge_error: N }
   status: String @indexed          # "success" | "partial" | "failed"
-  error: String                    # error message if failed
+  error: String                    # human-readable summary if partial/failed (includes per-record error messages, capped)
   durationMs: Int                  # how long the sync took
   createdAt: String! @indexed
 }

package/templates/bin/flair-rem-nightly.sh.tmpl

@@ -0,0 +1,9 @@
+#!/bin/sh
+# Flair REM nightly runner shim.
+# Deployed by `flair rem nightly enable` to {{SHIM_PATH}}.
+# Invoked by launchd (macOS) or systemd (Linux) on the configured schedule.
+#
+# Single line that invokes the CLI's run-once subcommand — the runner module
+# does all the work. Logs land in {{HOME}}/.flair/logs/.
+set -e
+exec {{FLAIR_BIN}} rem nightly run-once

package/templates/launchd/dev.flair.rem.nightly.plist.tmpl

@@ -0,0 +1,46 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>dev.flair.rem.nightly</string>
+
+  <key>ProgramArguments</key>
+  <array>
+    <string>{{SHIM_PATH}}</string>
+  </array>
+
+  <key>StartCalendarInterval</key>
+  <dict>
+    <key>Hour</key>
+    <integer>{{HOUR}}</integer>
+    <key>Minute</key>
+    <integer>{{MINUTE}}</integer>
+  </dict>
+
+  <key>RunAtLoad</key>
+  <false/>
+
+  <key>StandardOutPath</key>
+  <string>{{HOME}}/.flair/logs/rem-nightly.stdout.log</string>
+
+  <key>StandardErrorPath</key>
+  <string>{{HOME}}/.flair/logs/rem-nightly.stderr.log</string>
+
+  <key>WorkingDirectory</key>
+  <string>{{HOME}}</string>
+
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>HOME</key>
+    <string>{{HOME}}</string>
+    <key>PATH</key>
+    <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
+    <key>FLAIR_AGENT_ID</key>
+    <string>{{AGENT_ID}}</string>
+    <key>FLAIR_URL</key>
+    <string>{{FLAIR_URL}}</string>
+  </dict>
+</dict>
+</plist>

package/templates/systemd/flair-rem-nightly.service.tmpl

@@ -0,0 +1,14 @@
+[Unit]
+Description=Flair REM nightly cycle ({{AGENT_ID}})
+After=network.target
+
+[Service]
+Type=oneshot
+ExecStart={{SHIM_PATH}}
+Environment=FLAIR_AGENT_ID={{AGENT_ID}}
+Environment=FLAIR_URL={{FLAIR_URL}}
+StandardOutput=append:{{HOME}}/.flair/logs/rem-nightly.stdout.log
+StandardError=append:{{HOME}}/.flair/logs/rem-nightly.stderr.log
+
+[Install]
+WantedBy=default.target

package/templates/systemd/flair-rem-nightly.timer.tmpl

@@ -0,0 +1,10 @@
+[Unit]
+Description=Flair REM nightly timer ({{AGENT_ID}})
+
+[Timer]
+OnCalendar=*-*-* {{HOUR_PAD}}:{{MINUTE_PAD}}:00
+Persistent=true
+Unit=flair-rem-nightly.service
+
+[Install]
+WantedBy=timers.target