@tpsdev-ai/flair 0.37.0 → 0.38.0

package/dist/lib/mcp-enable.js

@@ -101,10 +101,14 @@
  *     `dist/lib/mcp/wellKnown.js`'s `buildAuthorizationServerMetadata`
  *     (lines 129-166), which advertises `registration_endpoint`/
  *     `token_endpoint` unconditionally (NOTE: `registration_endpoint` is
- *     advertised even though DCR is disabled — the plugin doesn't condition
- *     that field on `dynamicClientRegistration.enabled`; a POST there still
- *     404s per dcr.js:165-167, this is just a metadata-completeness quirk of
- *     the installed package, not a gap in our config) and
+ *     advertised even though DCR is disabled — CORRECTED 2026-08-05: that was
+ *     true of the version this was written against and is FALSE of the
+ *     installed one. wellKnown.js:142 now reads
+ *     `...(dcrEnabled(mcpConfig) ? { registration_endpoint: … } : {})`, so the
+ *     field is OMITTED whenever DCR is off — which is every instance `enable`
+ *     configures. selfVerifyMcpMetadata required it and therefore failed on a
+ *     correctly enabled surface; see the note at that check. A verified fact
+ *     carries the date it was verified, and this one expired.) and
  *     `client_id_metadata_document_supported: true` whenever
  *     `clientIdMetadataDocuments.enabled !== false` (wellKnown.js:164 — true
  *     by default, which is what our config relies on), and
@@ -135,6 +139,7 @@
  *     in `cimd.js`, so listing an extra host is not a meaningful risk
  *     expansion.
  */
+import { probeSecretsCapability, pushSecrets, PROCESS_ENV_TIER } from "./secrets-push.js";
 import { existsSync, mkdirSync, writeFileSync, chmodSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, dirname } from "node:path";
@@ -216,6 +221,30 @@ export function isFabricOrigin(url) {
  * installed 5.1.17 SDK). Anything else defaults to `env-file` — the
  * documented, universally-supported fallback. Always overridable.
  */
+/**
+ * ── The hostname no longer selects the mechanism (flair#1094) ───────────────
+ *
+ * This used to be `isFabricOrigin(url) ? "fabric-env-secrets" : "env-file"`, and
+ * that was wrong in BOTH directions on the day it was replaced:
+ *
+ *   - `tps.dtrt.harperfabric.com` runs Harper 5.1.26 and has no secrets
+ *     operations at all — measured; `set_secret` answers "Operation 'set_secret'
+ *     not found", identical to an invented operation — and was selected for the
+ *     automated mechanism purely because of its name.
+ *   - a self-hosted Harper 5.2 with the Pro env-secrets component is fully
+ *     capable and was sent down the manual Studio path for not matching.
+ *
+ * A hostname is not a capability, and neither is a version — the write
+ * operations and the Pro decryptor that makes a `processEnv` secret reach the
+ * process ship separately. `probeSecretsCapability` asks the target instead, and
+ * the answer decides at provisioning time.
+ *
+ * What remains here is the STAGING FILE's flavour of instructions, which is
+ * genuinely about where the operator will paste if we end up falling back.
+ * Fabric operators paste into Studio; everyone else edits a unit file. That is a
+ * UI fact about a human, not a claim about the server, so a hostname is a
+ * reasonable signal for it and a wrong guess costs only slightly-off prose.
+ */
 export function selectSecretsMechanism(instanceUrl, override) {
     if (override)
         return override;
@@ -605,12 +634,61 @@ export async function selfVerifyMcpMetadata(issuer, deps = {}) {
     catch {
         return { ok: false, detail: `${url} did not return JSON` };
     }
+    // ── The flair's-own-server check runs BEFORE the shape check (flair#1094) ──
+    //
+    // It used to run after, and that made the DEFAULT flag-off case misreport.
+    // flair's own document omits `registration_endpoint` unless DCR is enabled,
+    // which it is not by default — so the shape check fired first and returned
+    // "the metadata shape is unexpected", which is true, useless, and points at
+    // shapes when the cause is an unset environment variable.
+    //
+    // `token_endpoint` is present in that document either way, so testing the
+    // discriminator first names the real cause in EVERY flag-off case rather than
+    // only when DCR happens to be on. Found by writing the test that pins this
+    // relationship, not by reading the code.
+    if (typeof body?.token_endpoint === "string" && body.token_endpoint === `${normalizedIssuer}/OAuthToken`) {
+        return {
+            ok: false,
+            issuer: body?.issuer,
+            registrationEndpoint: body?.registration_endpoint,
+            tokenEndpoint: body.token_endpoint,
+            detail: `${url} answered with flair's OWN OAuth 2.1 authorization server, not the MCP one ` +
+                `(token_endpoint=${body.token_endpoint}) — the /mcp surface is NOT enabled on that instance. ` +
+                `Is FLAIR_MCP_OAUTH actually set on the restarted instance, and is the '@harperfast/oauth' ` +
+                `component declared in its config.yaml?`,
+        };
+    }
+    // ── registration_endpoint is OPTIONAL and must not be required (Kern, #1101) ─
+    //
+    // Requiring it made self-verify fail on a CORRECTLY enabled instance — the
+    // exact configuration `enable` itself creates.
+    //
+    // RFC 8414 marks the field optional, and BOTH authorization servers in this
+    // system omit it when DCR is off:
+    //   - flair's own AS: resources/oauth-discovery.ts, conditional spread on
+    //     dcrEnabled(), default off.
+    //   - the MCP plugin: @harperfast/oauth/dist/lib/mcp/wellKnown.js:142,
+    //     `...(dcrEnabled(mcpConfig) ? { registration_endpoint: … } : {})`.
+    //
+    // And `enable` writes `dynamicClientRegistration: { enabled: false }` by
+    // design — DCR is unsupported on this surface (#756). So the plugin omits the
+    // field on every instance this command configures, and self-verify then
+    // reported "the metadata shape is unexpected" on a working MCP surface,
+    // sending the operator to debug metadata fields instead.
+    //
+    // The module header above still claims the plugin advertises it
+    // "unconditionally". That was true of the version it was written against and
+    // is false of the installed one — corrected there too. A verified fact carries
+    // the date it was verified, and this one expired.
+    //
+    // Required: issuer and token_endpoint, both always present in both servers.
+    // registration_endpoint is validated only when it appears.
     if (body?.issuer !== normalizedIssuer ||
-        typeof body?.registration_endpoint !== "string" ||
-        typeof body?.token_endpoint !== "string") {
+        typeof body?.token_endpoint !== "string" ||
+        (body?.registration_endpoint !== undefined && typeof body.registration_endpoint !== "string")) {
         return {
             ok: false,
-            detail: `${url} responded but the metadata shape is unexpected (issuer/registration_endpoint/token_endpoint) — got issuer=${JSON.stringify(body?.issuer)}`,
+            detail: `${url} responded but the metadata shape is unexpected (issuer/token_endpoint) — got issuer=${JSON.stringify(body?.issuer)}`,
         };
     }
     // flair#1000: this path is now served by flair ITSELF when FLAIR_MCP_OAUTH is
@@ -759,11 +837,45 @@ export async function enableMcp(params, deps = {}) {
             idpClientSecret: params.idpClientSecret,
         });
         currentStep = "secrets-provisioning";
+        // Stage first, unconditionally. If the push works the file is a no-op the
+        // operator never opens; if anything about the push is uncertain they still
+        // have the thing that always works, without a re-run. Staging costs a 0600
+        // write; not staging costs an operator stranded mid-enable.
         const secretsResult = provisionSecrets(params.instance, bundle, {
             mechanism: params.secretsMechanism,
             stagingPath: params.secretsStagingPath,
         });
-        push(true, `mechanism: ${secretsResult.mechanism}; ${secretsResult.varNames.length} vars staged at ${secretsResult.path} (0600). ${secretsResult.instructions}`);
+        // Ask the TARGET whether it can take these, rather than inferring from its
+        // hostname or its version (flair#1094 — see selectSecretsMechanism's note).
+        // An explicit --secrets-mechanism is an operator override and is honoured
+        // without a probe: they have said what they want.
+        let secretsPushed = false;
+        if (!params.secretsMechanism) {
+            const cap = await probeSecretsCapability(resolveOpsUrl(params.instance), basicAuthHeader(params.adminUser, params.adminPass), { fetchImpl: deps.fetchImpl });
+            if (cap.available && cap.publicKeyPem) {
+                const pushResult = await pushSecrets(resolveOpsUrl(params.instance), basicAuthHeader(params.adminUser, params.adminPass), bundle, cap.publicKeyPem, { fetchImpl: deps.fetchImpl });
+                secretsPushed = pushResult.allOk;
+                if (secretsPushed) {
+                    push(true, `${secretsResult.varNames.length} vars pushed to the target as enc:v1 env-secrets (tier ${PROCESS_ENV_TIER}); ` +
+                        `values were sealed locally and never sent in plaintext. Staged copy at ${secretsResult.path} (0600) is unused. ` +
+                        `Self-verify below is what proves they were DECRYPTED into the process — a target that stores them without an ` +
+                        `active env-secrets decryptor will fail there, not here.`);
+                }
+                else {
+                    const failed = pushResult.results.filter((r) => !r.ok).map((r) => `${r.name} (${r.detail})`).join("; ");
+                    push(true, `push attempted and did not complete for: ${failed}. Falling back to the staged file at ${secretsResult.path} (0600). ` +
+                        `${secretsResult.instructions}`);
+                }
+            }
+            else {
+                push(true, `mechanism: ${secretsResult.mechanism}; ${secretsResult.varNames.length} vars staged at ${secretsResult.path} (0600). ` +
+                    `${cap.reason}. ${secretsResult.instructions}`);
+            }
+        }
+        else {
+            push(true, `mechanism: ${secretsResult.mechanism} (explicit --secrets-mechanism, no capability probe); ` +
+                `${secretsResult.varNames.length} vars staged at ${secretsResult.path} (0600). ${secretsResult.instructions}`);
+        }
         // ── Identity mapping (Credential kind:idp) ────────────────────────────────
         currentStep = "identity-mapping";
         const mapping = await provisionIdpIdentityMapping({

package/dist/lib/secret-envelope.js

@@ -0,0 +1,76 @@
+/**
+ * Client-side `enc:v1:` secret envelopes — the wire format Harper's env-secrets
+ * feature reads (`hdb_secret` store and encrypted `.env` entries).
+ *
+ * ── Why this is reimplemented rather than imported ──────────────────────────
+ * `harper@5.2.0` ships this as `utility/secretEnvelope.ts`, deliberately free of
+ * Harper imports and described in its own header as "safe to publish". We could
+ * import it — except that `flair mcp enable` builds the envelope for a REMOTE
+ * target whose Harper version is discovered at runtime and is routinely NEWER
+ * than the one flair bundles. Importing would tie the format we can produce to
+ * the engine we happen to ship, which is exactly backwards: the local engine has
+ * nothing to do with what the remote instance can read.
+ *
+ * So it is reimplemented, and the compatibility claim is TESTED rather than
+ * asserted — test/unit/secret-envelope.test.ts runs Harper's own
+ * `decryptEnvelope` (vendored verbatim into the test as a reference oracle)
+ * against envelopes this module produces. A round-trip against ourselves would
+ * only prove self-consistency, which is worth nothing here: the reader is
+ * someone else's code.
+ *
+ * ── The format, from harper@5.2.0 utility/secretEnvelope.ts ─────────────────
+ * Hybrid: AES-256-GCM encrypts the value, RSA-OAEP(SHA-256) wraps the AES key.
+ *
+ *   envelope = base64url(JSON.stringify({ kid, k, iv, ct, tag }))
+ *   kid = sha256(DER SPKI of the public key), hex
+ *   k   = base64(RSA-OAEP(aesKey))     iv  = base64(12 random bytes)
+ *   ct  = base64(ciphertext)           tag = base64(GCM auth tag)
+ *
+ * The `enc:v1:` marker is NOT part of the body — it is added by callers, the
+ * same split Harper uses (the marker lives in `utility/envFile.ts`).
+ *
+ * Nothing here reads or writes a secret to disk, and no value is logged. The
+ * plaintext exists only as an argument.
+ */
+import { createCipheriv, createHash, createPublicKey, publicEncrypt, randomBytes, constants } from "node:crypto";
+/** Marker prefixed to an envelope body. Harper keys the encrypted-value path on this. */
+export const ENV_ENCRYPTED_PREFIX = "enc:v1:";
+/**
+ * SHA-256 (hex) of the DER SPKI public key — the stable key id used as `kid`.
+ *
+ * The server derives `kid` from the sealed body and trusts only that one, never
+ * a separate client-supplied field, so getting this wrong surfaces as a refusal
+ * to decrypt rather than as a silently-wrong secret.
+ */
+export function fingerprintOf(publicKeyPem) {
+    const der = createPublicKey(publicKeyPem).export({ type: "spki", format: "der" });
+    return createHash("sha256").update(der).digest("hex");
+}
+/**
+ * Seal `plaintext` for the holder of `publicKeyPem`. Returns the envelope BODY,
+ * without the `enc:v1:` marker.
+ *
+ * Randomised per call (fresh AES key and IV), so two calls on the same input
+ * differ — which is why the tests assert decryptability by the reference
+ * implementation rather than comparing against a fixed string.
+ */
+export function encryptEnvelope(plaintext, publicKeyPem, kid) {
+    const aesKey = randomBytes(32);
+    const iv = randomBytes(12);
+    const cipher = createCipheriv("aes-256-gcm", aesKey, iv);
+    const ct = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    const k = publicEncrypt({ key: publicKeyPem, padding: constants.RSA_PKCS1_OAEP_PADDING, oaepHash: "sha256" }, aesKey);
+    const envelope = {
+        kid: kid ?? fingerprintOf(publicKeyPem),
+        k: k.toString("base64"),
+        iv: iv.toString("base64"),
+        ct: ct.toString("base64"),
+        tag: tag.toString("base64"),
+    };
+    return Buffer.from(JSON.stringify(envelope)).toString("base64url");
+}
+/** Seal and prefix — what a caller sends as `set_secret`'s `envelope` field. */
+export function sealSecret(plaintext, publicKeyPem) {
+    return ENV_ENCRYPTED_PREFIX + encryptEnvelope(plaintext, publicKeyPem);
+}

package/dist/lib/secrets-push.js

@@ -0,0 +1,128 @@
+/**
+ * Pushing `mcp enable`'s staged secrets to the target over the ops API, when the
+ * target can actually take them (flair#1094).
+ *
+ * ── What replaced what ──────────────────────────────────────────────────────
+ * The mechanism used to be chosen by HOSTNAME: `selectSecretsMechanism` returned
+ * `fabric-env-secrets` for anything ending `.harperfabric.com` and `env-file`
+ * otherwise. That is wrong in both directions and was wrong in both directions
+ * on the day it was replaced:
+ *
+ *   - tps.dtrt.harperfabric.com runs Harper 5.1.26 and has NO secrets
+ *     operations — measured, `set_secret` answers "Operation 'set_secret' not
+ *     found", identical to an operation that does not exist at all — and was
+ *     selected for the automated mechanism because of its name.
+ *   - a self-hosted Harper 5.2 with the Pro env-secrets component is fully
+ *     capable and was sent down the manual Fabric Studio path because its
+ *     hostname did not match.
+ *
+ * A hostname is not a capability. Nor is a version: the write operations and the
+ * decryptor that makes a `processEnv` secret reach the process ship separately
+ * (core vs Pro). So this asks the target directly.
+ *
+ * ── What this probe does and does not establish ─────────────────────────────
+ * It establishes that the secrets OPERATIONS exist, by asking for the public key
+ * we would need anyway. It does NOT establish that the Pro decryptor is active,
+ * and no read-only call can — a secret only proves it was decrypted by being
+ * present in the process.
+ *
+ * That check already exists downstream, though NOT for the reason first claimed
+ * here. The well-known endpoint does not stop answering when the flag is off —
+ * flair serves its OWN OAuth 2.1 discovery document in that case
+ * (resources/oauth-discovery.ts). What distinguishes them is a DISCRIMINATOR:
+ * flair's document advertises `<issuer>/OAuthToken`, the plugin's advertises
+ * `<issuer>/oauth/mcp/token`, and self-verify tests for the former by name.
+ *
+ * So a push that lands in `hdb_secret` and is never decrypted shows up as a
+ * self-verify failure naming FLAIR_MCP_OAUTH — because of a comparison, not an
+ * absence. That relationship spans two files and is pinned by a test in
+ * test/unit/secrets-push.test.ts; without it, changing either side silently
+ * disables the only thing standing between "stored" and "working".
+ *
+ * ── Failure direction ───────────────────────────────────────────────────────
+ * Every uncertain outcome falls back to the staged-file flow. That path works
+ * today, on every target, and costs the operator a paste. Pushing a secret at an
+ * endpoint that may not exist costs a silent flag-OFF boot, which is the exact
+ * failure this automation is meant to remove.
+ */
+import { sealSecret } from "./secret-envelope.js";
+/** `set_secret`'s delivery tier. `processEnv` is global and cannot be scoped —
+ *  which is what `FLAIR_MCP_OAUTH` and the signing key PEM need, since both are
+ *  read from `process.env` and never from YAML. */
+export const PROCESS_ENV_TIER = "processEnv";
+async function opsCall(opsUrl, authHeader, body, fetchImpl) {
+    const res = await fetchImpl(opsUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: authHeader },
+        body: JSON.stringify(body),
+    });
+    const text = await res.text().catch(() => "");
+    let json = null;
+    try {
+        json = JSON.parse(text);
+    }
+    catch { /* non-JSON body — keep the text */ }
+    return { ok: res.ok, status: res.status, json, text };
+}
+/**
+ * Ask the target whether it can take pushed secrets, by requesting the key we
+ * would encrypt to. Never throws: an unreachable or unparseable target is a
+ * fall-back-and-say-why, not a crash mid-enable.
+ */
+export async function probeSecretsCapability(opsUrl, authHeader, deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    let r;
+    try {
+        r = await opsCall(opsUrl, authHeader, { operation: "get_secrets_public_key" }, fetchImpl);
+    }
+    catch (err) {
+        return { available: false, reason: `could not reach the ops API to ask (${err?.message ?? err}) — using the staged-file flow` };
+    }
+    // "Operation '<name>' not found" is how Harper answers an operation it does
+    // not have, and it is byte-identical to the answer for an invented one. That
+    // is the signal for a target older than the env-secrets feature.
+    const errText = String(r.json?.error ?? r.text ?? "");
+    if (/not found/i.test(errText) && /get_secrets_public_key/.test(errText)) {
+        return { available: false, reason: "the target's Harper has no env-secrets operations (needs 5.2 or newer) — using the staged-file flow" };
+    }
+    if (!r.ok) {
+        return { available: false, reason: `the target refused the capability probe (HTTP ${r.status}${errText ? `: ${errText.slice(0, 120)}` : ""}) — using the staged-file flow` };
+    }
+    const pem = extractPublicKeyPem(r.json);
+    if (!pem) {
+        // Answered, but not with something we can encrypt to. Undeterminable is
+        // treated exactly like unavailable — see the failure-direction note above.
+        return { available: false, reason: "the target answered the probe without a usable public key — using the staged-file flow" };
+    }
+    return { available: true, reason: "target supports env-secrets; pushing over the ops API", publicKeyPem: pem };
+}
+/** Pull the PEM out of whatever shape the operation returns, without guessing
+ *  at a value that is not obviously a key. */
+function extractPublicKeyPem(json) {
+    const candidates = [json, json?.public_key, json?.publicKey, json?.key, json?.pem, json?.data?.public_key];
+    for (const c of candidates) {
+        if (typeof c === "string" && c.includes("BEGIN PUBLIC KEY"))
+            return c;
+    }
+    return undefined;
+}
+/**
+ * Seal and set each var. Values are encrypted client-side, so plaintext never
+ * appears in a request body — and never in this module's return value either:
+ * results carry NAMES and outcomes only.
+ */
+export async function pushSecrets(opsUrl, authHeader, vars, publicKeyPem, deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const results = [];
+    for (const [name, value] of Object.entries(vars)) {
+        try {
+            const r = await opsCall(opsUrl, authHeader, { operation: "set_secret", name, envelope: sealSecret(value, publicKeyPem), tier: PROCESS_ENV_TIER }, fetchImpl);
+            const err = String(r.json?.error ?? "").slice(0, 140);
+            results.push({ name, ok: r.ok, detail: r.ok ? undefined : `HTTP ${r.status}${err ? `: ${err}` : ""}` });
+        }
+        catch (err) {
+            results.push({ name, ok: false, detail: String(err?.message ?? err).slice(0, 140) });
+        }
+    }
+    return { allOk: results.every((x) => x.ok), results };
+}

package/docs/hosted-on-fabric.md

@@ -59,6 +59,26 @@ On Fabric, configuration goes through the component's environment, not a local `
 
 On Fabric / managed deploys, environment variables are provisioned through Harper's Fabric secrets mechanism (encrypted at rest with `enc:v1:` storage format).
 
+### How `flair mcp enable` delivers its secrets
+
+`flair mcp enable` needs five variables live in the target's process before it restarts — including `FLAIR_MCP_OAUTH` and the RS256 signing key, both read from `process.env` only and therefore impossible to deliver via `set_configuration`.
+
+It asks the target what it can do, rather than assuming from the hostname or the version:
+
+| The target… | What happens |
+|-------------|--------------|
+| supports Harper's env-secrets operations | the five vars are **sealed locally** and pushed over the ops API. No manual step, no re-run. |
+| does not have them (Harper older than 5.2) | the vars are staged to a `0600` file and you apply them yourself, then re-run with `--confirm-secrets-applied` |
+| is unreachable, refuses the probe, or answers unusably | same staged-file fallback, and the output says **which** of those happened |
+
+Values are encrypted **before leaving your machine** — AES-256-GCM on the value, RSA-OAEP(SHA-256) wrapping the key, addressed to a public key fetched from the target. Plaintext never appears in a request body, and the command's output carries variable *names* only.
+
+The staging file is written in every case, so a fallback never strands you mid-run. When the push succeeds it simply goes unused.
+
+> **What the probe does not promise.** It establishes that the target accepts secrets, not that it will *decrypt* them — no read-only call can, since a secret only proves it was decrypted by being present in the process. The **self-verify** step at the end is what proves that. Note the endpoint does *not* go quiet when the flag is off — flair serves its own OAuth 2.1 discovery document instead, and self-verify tells them apart by the advertised `token_endpoint` (`/OAuthToken` is flair's own; the MCP one is `/oauth/mcp/token`). So a secret that is stored and never decrypted fails at self-verify with a message naming `FLAIR_MCP_OAUTH`, rather than reporting success.
+
+`--secrets-mechanism <fabric-env-secrets|env-file>` remains an explicit override and skips the probe entirely.
+
 ---
 
 ## Agent authentication

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.37.0",
+  "version": "0.38.0",
   "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",