@tpsdev-ai/flair 0.44.5 → 0.44.7

package/dist/cli.js

@@ -23,7 +23,7 @@ import { detectClients, renderWiringSummary, wireClaudeCode, wireCodex, wireGemi
 import { flairCliVersion, clearFlairCliVersionCache, mcpServerSpec, unpinnedSpecWarning } from "./lib/mcp-spec.js";
 import { resolveAgentKeyPath, loadEd25519PrivateKeyFromFile, signClientAssertion, buildTokenRequestForm, getMcpAccessToken, McpTokenRequestError, defaultMcpClientId, defaultMcpTokenEndpoint, defaultMcpResource, defaultMcpIssuer, MAX_ASSERTION_LIFETIME_SECONDS, } from "./mcp-client-assertion.js";
 import { enableMcp, disableMcp, mcpStatus, checkLocalOriginRefusal, selfVerifyMcpMetadata, } from "./lib/mcp-enable.js";
-import { readClientMcpBlock, checkClaudeMdBootstrap, inspectSessionStartHook, upgradeSessionStartHookCommand, fixClaudeMdBootstrap, fixSessionStartHook, applyOrReportClaudeMdBootstrap, applyOrReportSessionStartHook, resolveWireFlairUrl, planAgentIterations, inferSoleAgentId, fixCommandAgentHint, describeAgentGateFinding, embeddingsSkipRemedy, classifyKeyFile, resolveCollisionSafeName, pruneDateStamp, PRUNED_DIR_NAME, } from "./doctor-client.js";
+import { readClientMcpBlock, checkClaudeMdBootstrap, inspectSessionStartHook, upgradeSessionStartHookCommand, fixClaudeMdBootstrap, fixSessionStartHook, applyOrReportClaudeMdBootstrap, applyOrReportSessionStartHook, resolveWireFlairUrl, planAgentIterations, fixCommandAgentHint, isNodeKeyId, partitionKeyIds, resolveFixAgentId, describeAgentGateFinding, embeddingsSkipRemedy, classifyKeyFile, resolveCollisionSafeName, pruneDateStamp, PRUNED_DIR_NAME, } from "./doctor-client.js";
 import { installHook, uninstallHook, hookStatus, isSupportedHarness, SUPPORTED_HARNESSES, } from "./hook-install.js";
 import { readSecretFileSecure, readAdminPassFileSecure, defaultAdminPassPath, defaultKeysDir, resolveLocalAdminPass, resolveKeyPath, buildEd25519Auth, authFetch, KeyLoadError, isLocalBase, authedRequest, } from "./lib/auth-resolve.js";
 import { resolveSigningIdentity, emitSigningIdentityDebug, } from "./lib/signing-identity.js";
@@ -1503,8 +1503,12 @@ export async function verifySemanticSearch(baseUrl, agentIdOpt, keysDir) {
     if (!agentId) {
         try {
             const keyFiles = readdirSync(keysDir).filter((f) => f.endsWith(".key"));
-            if (keyFiles.length > 0)
-                agentId = keyFiles[0].replace(/\.key$/, "");
+            // Skip node-scoped federation keys (flair#1193): they can't sign, so
+            // picking one here would fail the probe with a decode error that reads
+            // like a semantic-search regression rather than "no agent to sign as".
+            const agentKeyFile = keyFiles.find((f) => !isNodeKeyId(f.replace(/\.key$/, ""), keysDir));
+            if (agentKeyFile)
+                agentId = agentKeyFile.replace(/\.key$/, "");
         }
         catch { /* keysDir missing */ }
     }
@@ -9796,8 +9800,12 @@ program
     await (async () => {
         const agentId = resolveAgentIdOrEnv({}) ?? (() => {
             try {
-                const keyFiles = readdirSync(defaultKeysDir()).filter((f) => f.endsWith(".key"));
-                return keyFiles.length > 0 ? keyFiles[0].replace(/\.key$/, "") : null;
+                const kd = defaultKeysDir();
+                const keyFiles = readdirSync(kd).filter((f) => f.endsWith(".key"));
+                // Node-scoped federation keys aren't agents (flair#1193) — never
+                // pin-refresh a connector as one.
+                const agentKeyFile = keyFiles.find((f) => !isNodeKeyId(f.replace(/\.key$/, ""), kd));
+                return agentKeyFile ? agentKeyFile.replace(/\.key$/, "") : null;
             }
             catch {
                 return null;
@@ -11843,9 +11851,27 @@ program
     const keysDir = defaultKeysDir();
     if (existsSync(keysDir)) {
         const keyFiles = (await import("node:fs")).readdirSync(keysDir).filter((f) => f.endsWith(".key"));
-        if (keyFiles.length > 0) {
-            keyAgentIds = keyFiles.map((f) => f.replace(/\.key$/, ""));
-            console.log(`  ${render.icons.ok} Keys found: ${render.wrap(render.c.bold, String(keyFiles.length))} agent(s) in ${render.wrap(render.c.dim, keysDir)}`);
+        // ~/.flair/keys is shared by agent Ed25519 signing keys and node-scoped
+        // federation keys (flair#1193). Only agent keys are signing identities;
+        // node keys are AES-GCM keystore blobs that must never be parsed as, or
+        // inferred as, an agent. Partition them out here so every downstream
+        // consumer of keyAgentIds (registration checks, --fix inference,
+        // fixCommandAgentHint) is node-free by construction.
+        const { agentKeyIds, nodeKeyIds } = partitionKeyIds(keyFiles.map((f) => f.replace(/\.key$/, "")), keysDir);
+        keyAgentIds = agentKeyIds;
+        if (agentKeyIds.length > 0) {
+            console.log(`  ${render.icons.ok} Keys found: ${render.wrap(render.c.bold, String(agentKeyIds.length))} agent(s) in ${render.wrap(render.c.dim, keysDir)}`);
+            if (nodeKeyIds.length > 0) {
+                console.log(`     ${render.icons.info} ${render.wrap(render.c.dim, `${nodeKeyIds.length} node-scoped federation key(s) present — not agent signing keys; skipping`)}`);
+            }
+        }
+        else if (nodeKeyIds.length > 0) {
+            // Node keys but no agent key: functionally there is no agent identity
+            // here. Report it plainly (not the old DECODER false alarm) and point
+            // at the real remedy. Kept a warn — not an issues++ — so a genuine
+            // federation-only host doesn't newly fail doctor's exit code.
+            console.log(`  ${render.icons.warn} No agent signing key found — only ${render.wrap(render.c.bold, String(nodeKeyIds.length))} node-scoped federation key(s) in ${render.wrap(render.c.dim, keysDir)}`);
+            console.log(`     ${render.wrap(render.c.dim, "These are Fabric node keys, not agent identities. Fix:")} flair init --agent-id <your-agent>`);
         }
         else {
             console.log(`  ${render.icons.error} Keys directory exists but no .key files found`);
@@ -12103,13 +12129,24 @@ program
                             // nothing else identifies one — the only case doctor can
                             // infer without being told (see inferSoleAgentId's doc
                             // comment in doctor-client.ts for why 0/2+ keys don't guess).
-                            const fixAgentId = opts.agent || process.env.FLAIR_AGENT_ID || anyKnownAgentId || inferSoleAgentId(keyAgentIds);
+                            // flair#1193: resolveFixAgentId additionally refuses a
+                            // node-scoped federation id from ANY source (inference, env,
+                            // or a wired block a prior buggy run may have poisoned) — a
+                            // node id can't sign, so wiring it would authenticate the
+                            // connector as a phantom unregistered node.
+                            const fixAgentId = resolveFixAgentId({
+                                optsAgent: opts.agent,
+                                envAgentId: process.env.FLAIR_AGENT_ID,
+                                anyKnownAgentId,
+                                keyAgentIds,
+                                keysDir: defaultKeysDir(),
+                            });
                             if (!fixAgentId) {
                                 if (keyAgentIds.length > 1) {
                                     console.log(`     ${render.icons.warn} Cannot auto-wire ${client.label}: multiple agents found (${[...keyAgentIds].sort().join(", ")}) — pass --agent <id> to choose which one`);
                                 }
                                 else {
-                                    console.log(`     ${render.icons.warn} Cannot auto-wire ${client.label}: no agent registered — run \`flair agent add <id>\` first, then re-run \`flair doctor --fix\``);
+                                    console.log(`     ${render.icons.warn} Cannot auto-wire ${client.label}: no agent identity found in keys/ — run \`flair init --agent <name>\` or \`flair agent add <name>\` before wiring a connector`);
                                 }
                             }
                             else {

package/dist/doctor-client.js

@@ -907,3 +907,78 @@ export function classifyKeyFile(agentId, seedValid, registration, baseUrl) {
         reason: `agent '${agentId}' is not registered on ${baseUrl}${registration?.detail ? ` (${registration.detail})` : ""}`,
     };
 }
+// ── Node-scoped federation keys vs agent signing keys (flair#1193) ─────────
+//
+// `~/.flair/keys/` is a namespace shared by two writers with two file shapes:
+//
+//   • agent Ed25519 signing keys — a 32-byte raw seed at `<name>.key`, ALWAYS
+//     written together with a sibling `<name>.pub` (see the keypair write in
+//     src/cli.ts: the seed and the public key are emitted in the same block).
+//   • node-scoped federation keys — `flair_<hex8>.key`, an AES-256-GCM
+//     keystore blob written by FileKeyStore during Fabric provisioning
+//     (flair#1026). The id is minted as `flair_${randomBytes(4).toString("hex")}`
+//     in resources/Federation.ts, and NO `.pub` is ever written for it.
+//
+// Nothing used to tell them apart, so doctor tried to Ed25519-parse the node
+// blob — a "DECODER routines::unsupported" warning that reads as agent-auth
+// breakage when agent auth is fine — and `doctor --fix` could infer the node
+// id as the sole "agent" and wire it as a connector identity, authenticating
+// as a phantom, unregistered node whose key cannot sign (flair#1193).
+//
+// The guard is STRUCTURAL, not a parse attempt: a node id matches
+// `flair_<hex8>` AND has no sibling `.pub`. We deliberately do NOT classify by
+// parsing the file and treating a decode failure as "must be a node key" —
+// that is the exact fails-open move flair#1026 warns against (a genuinely
+// corrupt agent key would be misread as a node key and silently skipped).
+// A real agent always has a `.pub`; a node key never does, so `.pub` presence
+// is the primary, falsifiable signal and classification never depends on the
+// parse-failure of the thing being classified.
+/** The shape a Fabric node id always has: `flair_` + 8 lowercase hex chars. */
+const NODE_KEY_ID_RE = /^flair_[0-9a-f]{8}$/;
+/**
+ * True iff `id` names a node-scoped federation key rather than an agent
+ * signing key: it is shaped like a node id AND has no sibling `<id>.pub` in
+ * `keysDir`. Both conditions are required — an agent that happened to be named
+ * `flair_deadbeef` would still have a `.pub`, so it is never misclassified.
+ */
+export function isNodeKeyId(id, keysDir) {
+    if (!NODE_KEY_ID_RE.test(id))
+        return false;
+    return !existsSync(join(keysDir, `${id}.pub`));
+}
+/**
+ * Partition `.key`-derived ids into agent signing keys and node-scoped
+ * federation keys (see isNodeKeyId). Node keys must never feed agent handling —
+ * Ed25519 parsing, registration checks, or connector-identity inference
+ * (flair#1193) — so callers keep only `agentKeyIds` for those paths and report
+ * `nodeKeyIds` informatively.
+ */
+export function partitionKeyIds(ids, keysDir) {
+    const agentKeyIds = [];
+    const nodeKeyIds = [];
+    for (const id of ids) {
+        (isNodeKeyId(id, keysDir) ? nodeKeyIds : agentKeyIds).push(id);
+    }
+    return { agentKeyIds, nodeKeyIds };
+}
+/**
+ * Resolve the agent id `doctor --fix` should wire a connector as, or undefined
+ * when none can be safely determined. A node-scoped federation id is NEVER
+ * returned regardless of source (flair#1193): it cannot sign, so wiring it
+ * yields a connector that authenticates as a phantom unregistered node and
+ * fails every read/write. When this returns undefined the caller MUST refuse
+ * and tell the user to create/register an agent — never fall back to a node id.
+ *
+ * `keyAgentIds` is expected to already be node-free (its producer partitions
+ * node keys out at enumeration), so `inferSoleAgentId` never sees one; the
+ * explicit `isNodeKeyId` guard additionally covers `optsAgent` / `envAgentId` /
+ * `anyKnownAgentId`, since a prior buggy run may have poisoned a wired block
+ * with a node id that would otherwise be read back and re-propagated.
+ */
+export function resolveFixAgentId(args) {
+    const { optsAgent, envAgentId, anyKnownAgentId, keyAgentIds, keysDir } = args;
+    const candidate = optsAgent || envAgentId || anyKnownAgentId || inferSoleAgentId(keyAgentIds);
+    if (candidate && isNodeKeyId(candidate, keysDir))
+        return undefined;
+    return candidate;
+}

package/dist/resources/mcp-tools.js

@@ -376,7 +376,15 @@ async function bootstrap(agent, args) {
     // flair#831 — attach the running Flair version to the RESPONSE (not the
     // delegated request body) so the calling agent learns the server version
     // on its very first call.
-    const result = unwrap(await h.post(body));
+    //
+    // flair#1182 — `unwrap` is async: it must be AWAITED before the result is
+    // spread, exactly as every sibling tool does (`await unwrap(...)` in
+    // memory_store / memory_update / memory_get). Without the await, `result` is
+    // the still-pending PROMISE, and `{ ...aPromise }` copies no own-enumerable
+    // keys — so the entire computed payload (resolved agentId, scope, soul,
+    // memories, predicted, the #1182.1 containers, the abstention verdict) was
+    // silently discarded and the caller saw ONLY the injected `flairVersion`.
+    const result = await unwrap(await h.post(body));
     if (result && typeof result === "object" && !Array.isArray(result)) {
         return { ...result, flairVersion: resolveVersion() };
     }
@@ -384,14 +392,29 @@ async function bootstrap(agent, args) {
 }
 async function soulSet(agent, args) {
     const Cls = await handler("Soul");
-    const h = new Cls(undefined, delegationContext(agent));
-    // Soul records are keyed `id = agentId:key` (see flair-client SoulApi.set and
-    // schemas/memory.graphql). Use PUT with the explicit id so soul_get's
-    // `${agentId}:${key}` lookup finds it — a plain post() would mint a random id
-    // and orphan the entry from get(). Soul.put enforces write ownership via
-    // resolveAgentAuth (non-admin can only write agentId === self).
+    // flair#1181 — this write MUST go through a COLLECTION-bound instance
+    // (`collectionResource(Cls, ctx).post(...)`), the same create path the sibling
+    // write tools use (memoryStore / workspaceSet / orgEvent). The previous
+    // `new Cls(undefined, ctx).put({ id, ... })` was a PUT on an UNLOADED instance:
+    // an unloaded instance has no primary key, so Harper's instance put()/save()
+    // threw `Invalid primary key type: undefined` (the same defect class the
+    // memoryGet/update/delete/soulGet by-id READS were migrated off of — see those
+    // wrappers, and resources/in-process.ts's header: "flair itself got [collection
+    // binding] wrong in four MCP tool paths"). soul_set's only prior test drove a
+    // MOCKED handler, so the real instance-put never ran and it shipped broken on
+    // the connector path.
+    //
+    // A COLLECTION post (not a static `Cls.put(record, ctx)`) is the right form:
+    // it routes through Soul.post(), which stamps createdAt (a schema-required,
+    // non-null field). Static `Cls.put` reaches Soul.put(), which does NOT stamp
+    // createdAt on a create, so it fails a "Property createdAt is required"
+    // validation. Soul.post honors the explicit body `id`, so the record is still
+    // keyed `id = agentId:key` and soul_get's `${agentId}:${key}` lookup finds it —
+    // a random-id create would orphan the entry from get(). Soul.post enforces
+    // write ownership via resolveAgentAuth (non-admin can only write agentId === self).
     const id = `${agent.agentId}:${args?.key}`;
-    return unwrap(await h.put({
+    const h = await collectionResource(Cls, delegationContext(agent));
+    return unwrap(await h.post({
         id,
         agentId: agent.agentId,
         key: args?.key,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.44.5",
+  "version": "0.44.7",
   "packageManager": "bun@1.3.10",
   "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",