@tpsdev-ai/flair-client 0.44.12 → 0.45.0

package/dist/auth.js

@@ -8,6 +8,7 @@ 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 { 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). */
 export function loadPrivateKey(path) {
@@ -25,8 +26,12 @@ export function resolveKeyPath(agentId, keyPath) {
         const resolved = resolve(keyPath.replace(/^~/, homedir()));
         return existsSync(resolved) ? resolved : null;
     }
+    // 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 = [
-        process.env.FLAIR_KEY_DIR ? resolve(process.env.FLAIR_KEY_DIR, `${agentId}.key`) : null,
+        keyDir ? resolve(keyDir, `${agentId}.key`) : null,
         resolve(homedir(), ".flair", "keys", `${agentId}.key`),
         resolve(homedir(), ".tps", "secrets", "flair", `${agentId}-priv.key`),
     ].filter(Boolean);

package/dist/client.js

@@ -9,6 +9,7 @@
  */
 import { createHash, createPrivateKey } from "node:crypto";
 import { loadPrivateKey, resolveKeyPath, signRequest } from "./auth.js";
+import { readEnvOrUnset } from "./env-guard.js";
 const DEFAULT_URL = "http://localhost:19926";
 const DEFAULT_TIMEOUT = 30_000;
 export class FlairClient {
@@ -28,17 +29,22 @@ export class FlairClient {
     timeoutMs;
     basicAuth = null;
     constructor(config) {
-        this.url = (config.url ?? process.env.FLAIR_URL ?? DEFAULT_URL).replace(/\/$/, "");
-        this.agentId = config.agentId || process.env.FLAIR_AGENT_ID || "";
+        // Every env fallback below goes through readEnvOrUnset (flair#1254): a
+        // wholesale unsubstituted `${...}` interpolation literal — the shape an
+        // MCP-host config template leaves behind when it fails to substitute —
+        // reads as UNSET, so the existing defaults apply instead of the literal
+        // winning the `??`/`||` chain and poisoning the connection.
+        this.url = (config.url ?? readEnvOrUnset("FLAIR_URL") ?? DEFAULT_URL).replace(/\/$/, "");
+        this.agentId = config.agentId || readEnvOrUnset("FLAIR_AGENT_ID") || "";
         this.keyPath = config.keyPath;
         if (config.privateKey !== undefined) {
             this.rawPrivateKey = config.privateKey;
         }
-        this.claimedClient = config.claimedClient || process.env.FLAIR_CLIENT || undefined;
+        this.claimedClient = config.claimedClient || readEnvOrUnset("FLAIR_CLIENT") || undefined;
         this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT;
         // Basic auth fallback for standalone deployments without Ed25519 keys
-        const adminUser = config.adminUser ?? process.env.FLAIR_ADMIN_USER;
-        const adminPass = config.adminPassword ?? process.env.FLAIR_ADMIN_PASSWORD;
+        const adminUser = config.adminUser ?? readEnvOrUnset("FLAIR_ADMIN_USER");
+        const adminPass = config.adminPassword ?? readEnvOrUnset("FLAIR_ADMIN_PASSWORD");
         if (adminUser && adminPass) {
             this.basicAuth = `Basic ${Buffer.from(`${adminUser}:${adminPass}`).toString("base64")}`;
         }

package/dist/env-guard.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Interpolation-literal env guard (flair#1254, generalizing flair#1250/#1253).
+ *
+ * An MCP/agent host config template often forwards env like
+ *   "env": { "FLAIR_URL": "${FLAIR_URL}" }
+ * expecting the host to substitute `${FLAIR_URL}` with the real value. When
+ * the variable is unset and the host does NOT substitute, the consumer process
+ * is handed the LITERAL string `"${FLAIR_URL}"`. That literal is truthy, so it
+ * wins every `value ?? default` / `value || default` chain and the sensible
+ * default never applies — the connection then fails pointing nowhere near the
+ * real cause.
+ *
+ * flair#1253 stripped such literals at flair-mcp's process boundary, but the
+ * root exposure is HERE: FlairClient's constructor independently re-reads
+ * `process.env.FLAIR_*` as its own fallback, so every consumer of this client
+ * (CLI, adk, langgraph, n8n, ...) had the identical exposure and would each
+ * have needed its own boundary strip. This guard makes the client's own env
+ * fallbacks treat a wholesale `${...}` literal as absent, so the existing
+ * defaults (DEFAULT_URL, key-path derivation, no-basic-auth) apply instead —
+ * no new hardcoded defaults are introduced. flair-mcp's boundary strip stays
+ * as defense-in-depth.
+ *
+ * Semantics intentionally identical to packages/flair-mcp/src/env-guard.ts.
+ * Duplicated (not imported) because the dependency points the other way:
+ * flair-mcp depends on flair-client, and flair-client is zero-dep.
+ */
+/**
+ * True iff `value` is an unsubstituted interpolation literal like `${FLAIR_URL}`
+ * — i.e. the whole (trimmed) value is a single `${...}` placeholder the host
+ * never expanded. A value that merely CONTAINS a `${...}` (e.g. a real URL with
+ * a fragment) is left alone: only a wholesale placeholder is treated as unset.
+ */
+export declare function isUnsubstitutedInterpolation(value: string): boolean;
+/**
+ * Read an env var, treating an unsubstituted `${...}` interpolation literal as
+ * unset: returns `undefined` for such a literal (and for a genuinely absent
+ * var) so a downstream default applies instead of the literal being used
+ * verbatim. A real value is returned unchanged (NOT trimmed — only the
+ * placeholder check trims).
+ */
+export declare function readEnvOrUnset(name: string, env?: NodeJS.ProcessEnv): string | undefined;

package/dist/env-guard.js

@@ -0,0 +1,48 @@
+/**
+ * Interpolation-literal env guard (flair#1254, generalizing flair#1250/#1253).
+ *
+ * An MCP/agent host config template often forwards env like
+ *   "env": { "FLAIR_URL": "${FLAIR_URL}" }
+ * expecting the host to substitute `${FLAIR_URL}` with the real value. When
+ * the variable is unset and the host does NOT substitute, the consumer process
+ * is handed the LITERAL string `"${FLAIR_URL}"`. That literal is truthy, so it
+ * wins every `value ?? default` / `value || default` chain and the sensible
+ * default never applies — the connection then fails pointing nowhere near the
+ * real cause.
+ *
+ * flair#1253 stripped such literals at flair-mcp's process boundary, but the
+ * root exposure is HERE: FlairClient's constructor independently re-reads
+ * `process.env.FLAIR_*` as its own fallback, so every consumer of this client
+ * (CLI, adk, langgraph, n8n, ...) had the identical exposure and would each
+ * have needed its own boundary strip. This guard makes the client's own env
+ * fallbacks treat a wholesale `${...}` literal as absent, so the existing
+ * defaults (DEFAULT_URL, key-path derivation, no-basic-auth) apply instead —
+ * no new hardcoded defaults are introduced. flair-mcp's boundary strip stays
+ * as defense-in-depth.
+ *
+ * Semantics intentionally identical to packages/flair-mcp/src/env-guard.ts.
+ * Duplicated (not imported) because the dependency points the other way:
+ * flair-mcp depends on flair-client, and flair-client is zero-dep.
+ */
+/**
+ * True iff `value` is an unsubstituted interpolation literal like `${FLAIR_URL}`
+ * — i.e. the whole (trimmed) value is a single `${...}` placeholder the host
+ * never expanded. A value that merely CONTAINS a `${...}` (e.g. a real URL with
+ * a fragment) is left alone: only a wholesale placeholder is treated as unset.
+ */
+export function isUnsubstitutedInterpolation(value) {
+    return /^\$\{.*\}$/.test(value.trim());
+}
+/**
+ * Read an env var, treating an unsubstituted `${...}` interpolation literal as
+ * unset: returns `undefined` for such a literal (and for a genuinely absent
+ * var) so a downstream default applies instead of the literal being used
+ * verbatim. A real value is returned unchanged (NOT trimmed — only the
+ * placeholder check trims).
+ */
+export function readEnvOrUnset(name, env = process.env) {
+    const v = env[name];
+    if (v === undefined)
+        return undefined;
+    return isUnsubstitutedInterpolation(v) ? undefined : v;
+}

package/package.json

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