@tpsdev-ai/flair-client 0.49.0 → 0.50.0

package/dist/auth.d.ts

@@ -7,7 +7,55 @@
 import { type KeyObject } from "node:crypto";
 /** Resolve an Ed25519 private key from a file (base64 PKCS8 DER or raw 32-byte seed). */
 export declare function loadPrivateKey(path: string): KeyObject;
+/** Injectable homes so tests can diverge `$HOME` / `os.homedir()` / passwd home. */
+export interface HomeSources {
+    homedir: string;
+    envHome?: string;
+    userHomedir?: string;
+}
+/**
+ * Homes to probe, computed at CALL TIME (flair#1271).
+ *
+ * MCP hosts (npx under Cursor / Grok Bot / Claude Code) often have a different
+ * env than the shell that ran `flair agent add`. `os.homedir()` is the
+ * documented resolver — called here, not cached at module load — and we also
+ * keep `$HOME` and `os.userInfo().homedir` when they differ so a sanitized
+ * MCP `HOME` still finds `~/.flair/keys/<id>.key` on the real account home.
+ *
+ * Empty / relative values are dropped: `path.resolve("")` is cwd, which is
+ * exactly the footgun this function exists to refuse.
+ *
+ * `sources` is for tests: a fixture that puts the key only on `userHomedir`
+ * while `homedir`/`envHome` point at a sandbox must FAIL if the passwd-home
+ * probe is dropped.
+ */
+export declare function callTimeHomes(sources?: HomeSources): string[];
+/** Expand a leading `~/` against `home`. Unexpanded `~` with no home is left intact. */
+export declare function expandHomePrefix(p: string, home: string): string;
+/** Candidate key files for `agentId`, in probe order. Deduplicated. */
+export declare function keyPathCandidates(agentId: string, keyPath?: string, homes?: string[]): string[];
+/** How the request that failed was authenticated. */
+export type KeyAuthMethod = "ed25519" | "basic" | "none";
+/** Snapshot of a key-file lookup — attached to 401/403 so the error can name paths. */
+export interface KeyLookupState {
+    agentId: string;
+    /** `os.homedir()` at lookup time (may be empty if it was unusable). */
+    home: string;
+    candidates: {
+        path: string;
+        exists: boolean;
+    }[];
+    resolvedPath: string | null;
+    /** True when this request carried an Ed25519 Authorization header. */
+    signed: boolean;
+    /** What was actually sent. Basic-auth 401s must not push FLAIR_KEY_PATH. */
+    authMethod?: KeyAuthMethod;
+}
+/** Inspect standard key locations. Does not cache — call at request time (flair#1271). */
+export declare function inspectKeyLookup(agentId: string, keyPath?: string, homes?: string[]): Omit<KeyLookupState, "signed" | "authMethod">;
 /** Find the agent's private key file from standard locations. */
-export declare function resolveKeyPath(agentId: string, keyPath?: string): string | null;
+export declare function resolveKeyPath(agentId: string, keyPath?: string, homes?: string[]): string | null;
+/** Actor + state + remedy for a 401/403 (flair#1271). */
+export declare function formatKeyLookup(state: KeyLookupState): string;
 /** Build an Authorization header for a Flair request. */
 export declare function signRequest(agentId: string, privateKey: KeyObject, method: string, path: string): string;

package/dist/auth.js

@@ -6,8 +6,8 @@
  */
 import { randomUUID, sign as ed25519Sign, createPrivateKey } from "node:crypto";
 import { readFileSync, existsSync } from "node:fs";
-import { resolve } from "node:path";
-import { homedir } from "node:os";
+import { homedir, userInfo } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
 import { readEnvOrUnset } from "./env-guard.js";
 const PKCS8_ED25519_PREFIX = Buffer.from("302e020100300506032b657004220420", "hex");
 /** Resolve an Ed25519 private key from a file (base64 PKCS8 DER or raw 32-byte seed). */
@@ -20,22 +20,136 @@ export function loadPrivateKey(path) {
         : decoded;
     return createPrivateKey({ key: der, format: "der", type: "pkcs8" });
 }
-/** Find the agent's private key file from standard locations. */
-export function resolveKeyPath(agentId, keyPath) {
+/**
+ * Homes to probe, computed at CALL TIME (flair#1271).
+ *
+ * MCP hosts (npx under Cursor / Grok Bot / Claude Code) often have a different
+ * env than the shell that ran `flair agent add`. `os.homedir()` is the
+ * documented resolver — called here, not cached at module load — and we also
+ * keep `$HOME` and `os.userInfo().homedir` when they differ so a sanitized
+ * MCP `HOME` still finds `~/.flair/keys/<id>.key` on the real account home.
+ *
+ * Empty / relative values are dropped: `path.resolve("")` is cwd, which is
+ * exactly the footgun this function exists to refuse.
+ *
+ * `sources` is for tests: a fixture that puts the key only on `userHomedir`
+ * while `homedir`/`envHome` point at a sandbox must FAIL if the passwd-home
+ * probe is dropped.
+ */
+export function callTimeHomes(sources) {
+    const homes = [];
+    const push = (h) => {
+        if (h && isAbsolute(h) && !homes.includes(h))
+            homes.push(h);
+    };
+    if (sources) {
+        push(sources.homedir);
+        push(sources.envHome);
+        push(sources.userHomedir);
+        return homes;
+    }
+    push(homedir());
+    push(process.env.HOME);
+    try {
+        push(userInfo().homedir);
+    }
+    catch {
+        // No passwd entry (some containers). Skip — do not fall back to cwd.
+    }
+    return homes;
+}
+/** Expand a leading `~/` against `home`. Unexpanded `~` with no home is left intact. */
+export function expandHomePrefix(p, home) {
+    if (p === "~")
+        return home || p;
+    if ((p.startsWith("~/") || p.startsWith("~\\")) && home) {
+        return join(home, p.slice(2));
+    }
+    return p;
+}
+/**
+ * Make `p` absolute without turning an unexpanded `~` into a cwd-relative path.
+ * Operator-supplied relative paths (no `~`) still resolve against cwd.
+ */
+function toAbsoluteKeyPath(p) {
+    if (!p)
+        return null;
+    if (isAbsolute(p))
+        return p;
+    if (p.startsWith("~"))
+        return null;
+    return resolve(p);
+}
+/** Candidate key files for `agentId`, in probe order. Deduplicated. */
+export function keyPathCandidates(agentId, keyPath, homes = callTimeHomes()) {
+    const primaryHome = homes[0] ?? "";
     if (keyPath) {
-        const resolved = resolve(keyPath.replace(/^~/, homedir()));
-        return existsSync(resolved) ? resolved : null;
+        const abs = toAbsoluteKeyPath(expandHomePrefix(keyPath, primaryHome));
+        return abs ? [abs] : [];
     }
+    const out = [];
     // flair#1254: an unsubstituted `${FLAIR_KEY_DIR}` literal reads as unset, so
     // key resolution falls through to the standard locations below instead of
     // probing a directory literally named "${FLAIR_KEY_DIR}".
     const keyDir = readEnvOrUnset("FLAIR_KEY_DIR");
-    const candidates = [
-        keyDir ? resolve(keyDir, `${agentId}.key`) : null,
-        resolve(homedir(), ".flair", "keys", `${agentId}.key`),
-        resolve(homedir(), ".tps", "secrets", "flair", `${agentId}-priv.key`),
-    ].filter(Boolean);
-    return candidates.find(existsSync) ?? null;
+    if (keyDir) {
+        const absDir = toAbsoluteKeyPath(expandHomePrefix(keyDir, primaryHome));
+        if (absDir)
+            out.push(join(absDir, `${agentId}.key`));
+    }
+    for (const home of homes) {
+        out.push(join(home, ".flair", "keys", `${agentId}.key`));
+        out.push(join(home, ".tps", "secrets", "flair", `${agentId}-priv.key`));
+    }
+    return [...new Set(out)];
+}
+function authMethodOf(state) {
+    if (state.authMethod)
+        return state.authMethod;
+    return state.signed ? "ed25519" : "none";
+}
+/** Inspect standard key locations. Does not cache — call at request time (flair#1271). */
+export function inspectKeyLookup(agentId, keyPath, homes) {
+    const resolvedHomes = homes ?? callTimeHomes();
+    const candidates = keyPathCandidates(agentId, keyPath, resolvedHomes).map((path) => ({
+        path,
+        exists: existsSync(path),
+    }));
+    return {
+        agentId,
+        home: resolvedHomes[0] ?? "",
+        candidates,
+        resolvedPath: candidates.find((c) => c.exists)?.path ?? null,
+    };
+}
+/** Find the agent's private key file from standard locations. */
+export function resolveKeyPath(agentId, keyPath, homes) {
+    return inspectKeyLookup(agentId, keyPath, homes).resolvedPath;
+}
+/** Actor + state + remedy for a 401/403 (flair#1271). */
+export function formatKeyLookup(state) {
+    const actor = state.agentId
+        ? `agent '${state.agentId}'`
+        : "this agent (FLAIR_AGENT_ID unset)";
+    const method = authMethodOf(state);
+    if (method === "basic") {
+        return (`${actor} sent this request with Basic admin credentials (FLAIR_ADMIN_USER / FLAIR_ADMIN_PASSWORD), not an Ed25519 key.\n` +
+            "The server rejected those admin credentials. Check FLAIR_ADMIN_USER and FLAIR_ADMIN_PASSWORD — this 401 is not a missing agent key.");
+    }
+    const stateLine = method === "ed25519"
+        ? `${actor} signed with ${state.resolvedPath}.`
+        : `${actor} sent this request without a signing key.`;
+    const homeLine = `os.homedir() at lookup: ${state.home || "(empty — refused to fall back to cwd)"}`;
+    const looked = state.candidates.length === 0
+        ? "Looked for a key at: (no candidate paths — home could not be resolved)."
+        : [
+            "Looked for a key at:",
+            ...state.candidates.map((c) => `  ${c.path} (${c.exists ? "found" : "missing"})`),
+        ].join("\n");
+    const remedy = method === "ed25519"
+        ? "The server rejected the signature. Confirm the agent is registered (`flair agent add <id>`) and this key matches the Agent record. A daemon restart can also produce this — check `flair status`."
+        : "If `flair agent add` wrote the key, this process's home may differ from that shell, or the file appeared after an earlier lookup. Retry the tool (misses are no longer cached). Still missing? Set FLAIR_KEY_PATH to the absolute path of the .key file.";
+    return `${stateLine}\n${homeLine}\n${looked}\n${remedy}`;
 }
 /** Build an Authorization header for a Flair request. */
 export function signRequest(agentId, privateKey, method, path) {

package/dist/client.d.ts

@@ -7,6 +7,7 @@
  *   const results = await flair.memory.search('that thing')
  *   const ctx = await flair.bootstrap({ maxTokens: 4000 })
  */
+import { type KeyLookupState } from "./auth.js";
 import type { FlairClientConfig, Memory, MemoryType, Durability, Visibility, SoulEntry, SearchResult, BootstrapResult, Relationship } from "./types.js";
 export declare class FlairClient {
     readonly url: string;
@@ -19,9 +20,10 @@ export declare class FlairClient {
      *  MemoryApi reads this to (optionally) stamp memory write payloads. */
     readonly claimedClient: string | undefined;
     private privateKey;
-    private keyResolved;
     private keyPath;
     private rawPrivateKey;
+    /** Last file-key lookup — attached to 401/403 so the error can name paths (flair#1271). */
+    private lastKeyLookup;
     private timeoutMs;
     private basicAuth;
     constructor(config: FlairClientConfig);
@@ -76,6 +78,11 @@ declare class MemoryApi {
         /** Cosine-similarity threshold hint for the server's dedup gate.
          *  Default (server-side): 0.95 */
         dedupThreshold?: number;
+        /** Citation-on-write (flair#1147 / #744). IDs of memories that informed
+         *  this write. Forwarded only when the caller supplies a non-empty array;
+         *  the server credits each id through the same usage ledger as
+         *  POST /RecordUsage and strips the field before persisting. */
+        usedMemoryIds?: string[];
     }): Promise<Memory>;
     /**
      * Update an existing memory by id. Dedup-BYPASSED (this IS the intentional
@@ -99,6 +106,7 @@ declare class MemoryApi {
      */
     update(id: string, content: string, opts?: {
         preserveHistory?: boolean;
+        usedMemoryIds?: string[];
     }): Promise<Memory>;
     /** Search memories by meaning. Optionally filter to facts valid at a specific point in time. */
     search(query: string, opts?: {
@@ -234,6 +242,10 @@ export declare class FlairError extends Error {
     readonly path: string;
     readonly status: number;
     readonly body: string;
-    constructor(method: string, path: string, status: number, body: string);
+    /** Key-file lookup at the request that failed — named on 401/403 (flair#1271). */
+    readonly keyLookup?: KeyLookupState | undefined;
+    constructor(method: string, path: string, status: number, body: string, 
+    /** Key-file lookup at the request that failed — named on 401/403 (flair#1271). */
+    keyLookup?: KeyLookupState | undefined);
 }
 export {};

package/dist/client.js

@@ -8,7 +8,7 @@
  *   const ctx = await flair.bootstrap({ maxTokens: 4000 })
  */
 import { createHash, createPrivateKey } from "node:crypto";
-import { loadPrivateKey, resolveKeyPath, signRequest } from "./auth.js";
+import { inspectKeyLookup, loadPrivateKey, signRequest } from "./auth.js";
 import { readEnvOrUnset } from "./env-guard.js";
 const DEFAULT_URL = "http://localhost:19926";
 const DEFAULT_TIMEOUT = 30_000;
@@ -23,9 +23,10 @@ export class FlairClient {
      *  MemoryApi reads this to (optionally) stamp memory write payloads. */
     claimedClient;
     privateKey = null;
-    keyResolved = false;
     keyPath;
     rawPrivateKey;
+    /** Last file-key lookup — attached to 401/403 so the error can name paths (flair#1271). */
+    lastKeyLookup;
     timeoutMs;
     basicAuth = null;
     constructor(config) {
@@ -53,9 +54,12 @@ export class FlairClient {
         this.soul = new SoulApi(this);
     }
     resolveKey() {
-        if (this.keyResolved)
+        // Cache a FOUND key only. A miss must be retried on the next request —
+        // flair#1271: `flair agent add` can write ~/.flair/keys/<id>.key after
+        // this client was constructed (or after an earlier probe), and a cached
+        // null left flair-mcp 401ing until FLAIR_KEY_PATH was set by hand.
+        if (this.privateKey)
             return this.privateKey;
-        this.keyResolved = true;
         // In-memory key takes priority over file-based resolution.
         if (this.rawPrivateKey) {
             if (typeof this.rawPrivateKey === "string") {
@@ -64,14 +68,29 @@ export class FlairClient {
             else {
                 this.privateKey = this.rawPrivateKey;
             }
+            this.lastKeyLookup = {
+                agentId: this.agentId,
+                home: "",
+                candidates: [],
+                resolvedPath: "(in-memory)",
+                signed: true,
+                authMethod: "ed25519",
+            };
             return this.privateKey;
         }
-        const path = resolveKeyPath(this.agentId, this.keyPath);
-        if (path) {
+        // inspectKeyLookup calls os.homedir() at this moment — not a module-load
+        // snapshot, not cwd (flair#1271).
+        const lookup = inspectKeyLookup(this.agentId, this.keyPath);
+        if (lookup.resolvedPath) {
             // Key file exists — failure to parse is a hard error.
             // Silent fallback to unauthenticated would be a security risk.
-            this.privateKey = loadPrivateKey(path);
+            this.privateKey = loadPrivateKey(lookup.resolvedPath);
         }
+        this.lastKeyLookup = {
+            ...lookup,
+            signed: this.privateKey != null,
+            authMethod: this.privateKey ? "ed25519" : "none",
+        };
         return this.privateKey;
     }
     /** Make an authenticated request to Flair. */
@@ -83,6 +102,16 @@ export class FlairClient {
         }
         else if (this.basicAuth) {
             headers["Authorization"] = this.basicAuth;
+            // Basic-only snapshot — do not spread a prior inspectKeyLookup result.
+            // A 401 here is about admin credentials, not key-file paths (review on #1390).
+            this.lastKeyLookup = {
+                agentId: this.agentId,
+                home: "",
+                candidates: [],
+                resolvedPath: null,
+                signed: false,
+                authMethod: "basic",
+            };
         }
         const res = await fetch(`${this.url}${path}`, {
             method,
@@ -92,7 +121,7 @@ export class FlairClient {
         });
         if (!res.ok) {
             const text = await res.text().catch(() => "");
-            throw new FlairError(method, path, res.status, text.slice(0, 500));
+            throw new FlairError(method, path, res.status, text.slice(0, 500), this.lastKeyLookup);
         }
         const text = await res.text();
         return text ? JSON.parse(text) : {};
@@ -154,6 +183,11 @@ class MemoryApi {
             record.dedup = opts.dedup;
         if (opts.dedupThreshold !== undefined)
             record.dedupThreshold = opts.dedupThreshold;
+        // flair#1147: citation-on-write passthrough — only when supplied, so an
+        // omitted list is byte-identical to a pre-#1147 write.
+        if (Array.isArray(opts.usedMemoryIds) && opts.usedMemoryIds.length > 0) {
+            record.usedMemoryIds = opts.usedMemoryIds;
+        }
         // flair#718 authorship-provenance: forward this process's claimed client
         // label (config.claimedClient / FLAIR_CLIENT env) only when set — the
         // server folds it into provenance.claimed.client and strips it from the
@@ -222,6 +256,9 @@ class MemoryApi {
             // flair#718 authorship-provenance — see write()'s identical comment above.
             if (this.client.claimedClient)
                 record.claimedClient = this.client.claimedClient;
+            if (Array.isArray(opts.usedMemoryIds) && opts.usedMemoryIds.length > 0) {
+                record.usedMemoryIds = opts.usedMemoryIds;
+            }
             // The Memory schema does not expose a working HTTP POST route (see
             // resources/Memory.ts) — Memory.post() is only reachable in-process
             // (resources/mcp-tools.ts). So the supersede-link write goes through
@@ -242,6 +279,9 @@ class MemoryApi {
         // flair#718 authorship-provenance — see write()'s identical comment above.
         if (this.client.claimedClient)
             merged.claimedClient = this.client.claimedClient;
+        if (Array.isArray(opts.usedMemoryIds) && opts.usedMemoryIds.length > 0) {
+            merged.usedMemoryIds = opts.usedMemoryIds;
+        }
         const response = await this.client.request("PUT", `/Memory/${id}`, merged);
         return { ...merged, id, ...(response ?? {}) };
     }
@@ -470,12 +510,16 @@ export class FlairError extends Error {
     path;
     status;
     body;
-    constructor(method, path, status, body) {
+    keyLookup;
+    constructor(method, path, status, body, 
+    /** Key-file lookup at the request that failed — named on 401/403 (flair#1271). */
+    keyLookup) {
         super(`Flair ${method} ${path} → ${status}: ${body}`);
         this.method = method;
         this.path = path;
         this.status = status;
         this.body = body;
+        this.keyLookup = keyLookup;
         this.name = "FlairError";
     }
 }

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export { FlairClient, FlairError, canonicalRelationshipId } from "./client.js";
-export { loadPrivateKey, resolveKeyPath, signRequest } from "./auth.js";
+export { loadPrivateKey, resolveKeyPath, signRequest, inspectKeyLookup, formatKeyLookup, keyPathCandidates, callTimeHomes, expandHomePrefix, } from "./auth.js";
+export type { KeyLookupState, KeyAuthMethod, HomeSources } from "./auth.js";
 export type { FlairClientConfig, Memory, MemoryType, Durability, Visibility, SoulEntry, SearchResult, BootstrapResult, Relationship, } from "./types.js";

package/dist/index.js

@@ -1,2 +1,2 @@
 export { FlairClient, FlairError, canonicalRelationshipId } from "./client.js";
-export { loadPrivateKey, resolveKeyPath, signRequest } from "./auth.js";
+export { loadPrivateKey, resolveKeyPath, signRequest, inspectKeyLookup, formatKeyLookup, keyPathCandidates, callTimeHomes, expandHomePrefix, } from "./auth.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair-client",
-  "version": "0.49.0",
+  "version": "0.50.0",
   "description": "Lightweight client for Flair — identity, memory, and soul for AI agents. Zero heavy dependencies.",
   "type": "module",
   "main": "dist/index.js",