@tpsdev-ai/flair 0.32.0 → 0.34.0

package/dist/component-env.js

@@ -0,0 +1,286 @@
+// ─── The deployed component's `.env` (flair#1005 item 2, flair#1000, flair#1011) ──
+//
+// A publicly-reachable Flair served an OAuth discovery document whose issuer and
+// every endpoint were `http://127.0.0.1:9980`, so no remote client could complete
+// an authorization flow (flair#1000). The cause was `FLAIR_PUBLIC_URL` being unset
+// on the instance: `resources/OAuth.ts` and `resources/AdminInstance.ts` fall back
+// to the bind address when it is absent.
+//
+// The value has to arrive as an ENVIRONMENT VARIABLE in the component's process.
+// The only channel a deploying client controls is a `.env` file inside the
+// component payload, and Harper reads that file only because flair#1010 added
+//
+//     loadEnv:
+//       files: '.env'
+//
+// to the shipped config.yaml, declared above `jsResource`. Without that block the
+// file is inert — present on disk, never in `process.env`. Read config.yaml's own
+// comment for the ordering constraint and for why `loadEnv` supplies APPLICATION
+// variables only: it runs after Harper has already composed its own configuration.
+//
+// ── Why exactly one key ships, and no secret ever does ──────────────────────────
+//
+// The deploy payload is not transient. Harper's `deploy_component` ingests the
+// whole tarball into an `hdb_deployment` row's `payload_blob`, and that row is the
+// channel peers read the component from and the source for rollback
+// (harper/dist/components/operations.js — "The row also holds the payload in a Blob
+// attribute, which doubles as the source for peer replication and (later)
+// rollback"). So anything in the payload is persisted on every node for as long as
+// the deployment record lives. A public URL is fine there. A password is not.
+//
+// `HDB_ADMIN_PASSWORD` additionally cannot work from here even if that were
+// acceptable: Harper composes its own configuration before component `.env` files
+// load, so the name Harper itself consumes at startup is already resolved by the
+// time `loadEnv` fires. Shipping it would put a credential in a component directory
+// that only flair reads, fed from a different source than Harper's own copy, with
+// nothing detecting divergence (flair#1011). `FLAIR_ADMIN_PASSWORD` is flair's own
+// name for flair's own need and does reach its reader in time — but it is still a
+// password, and the payload-persistence argument above applies to it unchanged.
+//
+// Hence: the file this module generates carries `FLAIR_PUBLIC_URL` and nothing
+// else, and `assertNoSecretKeys` is a runtime guard, not a comment.
+/** The file Harper's `loadEnv` plugin is pointed at by flair's config.yaml. */
+export const COMPONENT_ENV_FILENAME = ".env";
+/** The one key `flair deploy` supplies. */
+export const PUBLIC_URL_KEY = "FLAIR_PUBLIC_URL";
+/**
+ * Key names that must never appear in a `.env` flair GENERATES.
+ *
+ * An operator's own file is a different matter — see `planComponentEnv`, which
+ * preserves whatever they wrote and warns by key NAME (never value) rather than
+ * silently dropping or shipping it.
+ */
+export const NEVER_GENERATED_SECRET_KEYS = [
+    "HDB_ADMIN_PASSWORD",
+    "FLAIR_ADMIN_PASSWORD",
+    "FLAIR_ADMIN_PASS",
+    "FABRIC_PASSWORD",
+    "FLAIR_CLUSTER_ADMIN_PASS",
+    "CLI_TARGET_PASSWORD",
+    // The DCR initial access token (resources/dcr-gate.ts). It is a bearer
+    // credential for an unauthenticated public endpoint, so it belongs in the
+    // process environment, never in a deploy payload — that payload is ingested
+    // into an hdb_deployment row and replicated to every node, per the argument
+    // at the top of this file.
+    "FLAIR_OAUTH_DCR_TOKEN",
+];
+/**
+ * A key name that looks like it carries a credential. Used for the operator-facing
+ * notice only — matching is on the NAME, and the value is never read, printed, or
+ * compared.
+ */
+export function looksLikeSecretKey(name) {
+    return /(PASSWORD|PASSWD|SECRET|TOKEN|_KEY|APIKEY|CREDENTIAL)/i.test(name);
+}
+/**
+ * Is this URL one only the machine serving it can reach?
+ *
+ * Deliberately a TEXT test, not a DNS lookup: this decides what gets baked into a
+ * deployed artifact, and a resolver answer at deploy time is not a property of the
+ * artifact. The IPv4 pattern is anchored end-to-end on purpose — a prefix test
+ * (`startsWith("127.")`) also matches hostnames like `127.0.0.1.example.com`, which
+ * are ordinary DNS names that merely happen to begin with those digits.
+ */
+export function isLoopbackUrl(raw) {
+    if (!raw)
+        return false;
+    let host;
+    try {
+        host = new URL(raw).hostname;
+    }
+    catch {
+        return false;
+    }
+    return isLoopbackHost(host);
+}
+export function isLoopbackHost(host) {
+    const h = host.replace(/^\[|\]$/g, "").toLowerCase();
+    if (h === "localhost" || h.endsWith(".localhost"))
+        return true;
+    if (h === "::1" || h === "0:0:0:0:0:0:0:1")
+        return true;
+    return /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(h);
+}
+// A `.env` assignment line. `export ` is accepted because dotenv-style files
+// commonly carry it and an operator who wrote `export FLAIR_PUBLIC_URL=...` has
+// unambiguously set the key — treating that as "absent" and appending a second
+// assignment would be the clobber this module exists to avoid.
+const ASSIGNMENT_RE = /^[ \t]*(?:export[ \t]+)?([A-Za-z_][A-Za-z0-9_]*)[ \t]*=/;
+/** Key NAMES present in a `.env`, in file order. Never returns values. */
+export function envKeyNames(text) {
+    if (!text)
+        return [];
+    const names = [];
+    for (const line of text.split(/\r?\n/)) {
+        const m = ASSIGNMENT_RE.exec(line);
+        if (m && !names.includes(m[1]))
+            names.push(m[1]);
+    }
+    return names;
+}
+/**
+ * The value assigned to `key`, or null. The single value this module reads is
+ * `FLAIR_PUBLIC_URL`, which is not a secret; nothing here reads any other value.
+ */
+export function readEnvValue(text, key) {
+    if (!text)
+        return null;
+    for (const line of text.split(/\r?\n/)) {
+        const m = ASSIGNMENT_RE.exec(line);
+        if (!m || m[1] !== key)
+            continue;
+        let v = line.slice(line.indexOf("=") + 1).trim();
+        if ((v.startsWith('"') && v.endsWith('"') && v.length >= 2) ||
+            (v.startsWith("'") && v.endsWith("'") && v.length >= 2)) {
+            v = v.slice(1, -1);
+        }
+        return v;
+    }
+    return null;
+}
+/**
+ * Throws if the transition from `existing` to `generated` INTRODUCES any key flair
+ * must never generate.
+ *
+ * Deliberately a diff and not "does the output contain a password": an operator's
+ * own `.env` may legitimately assign one, and refusing to deploy their file would
+ * break a deploy that works today. What must never happen is flair adding one. A
+ * runtime guard rather than a review convention, because the generator and this
+ * check are one edit apart forever — and `git grep NEVER_GENERATED_SECRET_KEYS`
+ * finds both ends of it.
+ */
+export function assertNoSecretKeysAdded(existing, generated) {
+    const before = new Set(envKeyNames(existing));
+    const added = envKeyNames(generated).filter((n) => !before.has(n) && NEVER_GENERATED_SECRET_KEYS.includes(n));
+    if (added.length) {
+        throw new Error(`refusing to generate a component ${COMPONENT_ENV_FILENAME} that adds ${added.join(", ")}: ` +
+            `the deploy payload is persisted in Harper's hdb_deployment record and replicated to ` +
+            `every node, so flair must add no credential to it (flair#1011)`);
+    }
+}
+/**
+ * Decide what `.env` a deploy should ship.
+ *
+ * `existing` is the CONTENT of a `.env` already in the package root, or null. It is
+ * never modified in place and never overwritten on disk — the caller stages a copy.
+ * That is the answer to "do not silently clobber an operator's existing `.env`":
+ * flair MERGES, and merging here means "append the one key when it is absent, and
+ * change nothing at all when it is present".
+ *
+ * Why merge rather than refuse: a `.env` in the package root already ships today
+ * (Harper's packer includes every non-`node_modules` file under the deploy root), so
+ * an operator can legitimately be relying on one, and refusing would break a deploy
+ * that works. Why the operator's value wins rather than the deploy target: an
+ * instance is routinely fronted by a hostname that is not the URL the deploy is
+ * addressed to — a CDN, a reverse proxy, a vanity domain — and that hostname is
+ * exactly what OAuth clients must be told. Overwriting it with the Fabric URL would
+ * break the deployment the value exists to fix. The disagreement is printed, so the
+ * choice is visible rather than silent.
+ *
+ * `publicUrl` is null when the deploy has no non-loopback target to advertise; the
+ * plan is then "unchanged" — writing `http://127.0.0.1:...` into a shipped `.env` is
+ * the precise misconfiguration flair#1000 is about, so it is never generated.
+ */
+export function planComponentEnv(existing, publicUrl) {
+    const notices = [];
+    // Whatever the operator wrote, say out loud which credential-shaped KEYS are
+    // about to be persisted in the replicated deployment record. Names only.
+    const secretish = envKeyNames(existing).filter(looksLikeSecretKey);
+    if (secretish.length) {
+        notices.push(`${COMPONENT_ENV_FILENAME} in the deploy root assigns ${secretish.join(", ")} — a deploy ` +
+            `payload is stored in Harper's deployment record and replicated to every node, so ` +
+            `those values travel with it. flair adds no credential of its own.`);
+    }
+    const operatorValue = readEnvValue(existing, PUBLIC_URL_KEY);
+    if (operatorValue !== null) {
+        if (publicUrl && operatorValue !== publicUrl) {
+            notices.push(`${PUBLIC_URL_KEY} is already set in ${COMPONENT_ENV_FILENAME} to ${operatorValue} — ` +
+                `keeping it. The deploy target is ${publicUrl}; if the instance is fronted by a ` +
+                `proxy or CDN the existing value is the correct one, otherwise edit that file.`);
+        }
+        if (isLoopbackUrl(operatorValue)) {
+            notices.push(`${PUBLIC_URL_KEY} in ${COMPONENT_ENV_FILENAME} is a loopback address ` +
+                `(${operatorValue}). OAuth discovery and A2A discovery advertise it verbatim, so ` +
+                `remote clients will be told to connect to their own machine (flair#1000).`);
+        }
+        return { action: "operator-value-kept", text: null, effectiveValue: operatorValue, notices };
+    }
+    if (!publicUrl) {
+        return { action: "unchanged", text: null, effectiveValue: null, notices };
+    }
+    const base = existing ?? "";
+    const separator = base.length === 0 || base.endsWith("\n") ? "" : "\n";
+    const text = `${base}${separator}${PUBLIC_URL_KEY}=${publicUrl}\n`;
+    assertNoSecretKeysAdded(existing, text);
+    return { action: "added", text, effectiveValue: publicUrl, notices };
+}
+/**
+ * The remedy string for a missing/loopback `FLAIR_PUBLIC_URL`. One definition so
+ * `flair deploy` and `flair doctor` cannot drift into naming different files.
+ *
+ * It names all three things an operator needs: the FILE, the KEY, and the fact that
+ * the file is only read because config.yaml declares Harper's `loadEnv` plugin —
+ * without which the file is present and inert, which is what made flair#1000 hard
+ * to see.
+ */
+export function publicUrlRemedy(envPath, exampleUrl = "https://flair.example.com") {
+    return (`set ${PUBLIC_URL_KEY}=${exampleUrl} in ${envPath} (Harper reads a component's ` +
+        `${COMPONENT_ENV_FILENAME} only because flair's config.yaml declares the loadEnv plugin, ` +
+        `above jsResource), then restart the instance`);
+}
+/**
+ * What `flair doctor` should say about the instance's advertised public URL.
+ *
+ * Scope, stated rather than implied: doctor diagnoses the instance on THIS machine,
+ * reached over loopback. It cannot observe whether that instance is also reachable
+ * at a public address, so "unset, and the instance is public" is not a state it can
+ * detect — an unconditional finding there would fire on every laptop install, and a
+ * check that always fires is noise, not a gate. What it CAN detect without guessing
+ * is DRIFT: the value exists somewhere, and the running instance is still advertising
+ * loopback anyway. That is the exact shape of flair#1000 (a `.env` was placed and the
+ * issuer never changed, because no `loadEnv` declaration existed to read it), and it
+ * has no false positives.
+ *
+ * The unset-everywhere case is reported as information, not a finding, with the full
+ * remedy — so an operator who IS running this publicly is told precisely what to do.
+ */
+export function describePublicUrlFinding(input) {
+    const { advertisedIssuer, componentEnvValue, processEnvValue, componentEnvPath } = input;
+    // Nothing to say if the instance could not be asked.
+    if (advertisedIssuer === null)
+        return null;
+    if (!isLoopbackUrl(advertisedIssuer)) {
+        return {
+            isIssue: false,
+            icon: "ok",
+            message: `OAuth/A2A discovery advertises ${advertisedIssuer}`,
+        };
+    }
+    if (componentEnvValue !== null && !isLoopbackUrl(componentEnvValue)) {
+        return {
+            isIssue: true,
+            icon: "error",
+            message: `${PUBLIC_URL_KEY} is set in ${componentEnvPath} but discovery still advertises ` +
+                `${advertisedIssuer} — the file is not reaching process.env, so every URL this ` +
+                `instance publishes points at its own loopback (flair#1000)`,
+            fixHint: `confirm config.yaml declares "loadEnv: files: '${COMPONENT_ENV_FILENAME}'" ABOVE ` +
+                `jsResource, then restart — a component .env is inert without that declaration`,
+        };
+    }
+    if (componentEnvValue === null && processEnvValue !== null && !isLoopbackUrl(processEnvValue)) {
+        return {
+            isIssue: true,
+            icon: "error",
+            message: `${PUBLIC_URL_KEY} is set in this shell but discovery advertises ${advertisedIssuer} — ` +
+                `the server reads its own environment, not yours`,
+            fixHint: publicUrlRemedy(componentEnvPath, processEnvValue),
+        };
+    }
+    return {
+        isIssue: false,
+        icon: "warn",
+        message: `${PUBLIC_URL_KEY} is not set — OAuth and A2A discovery advertise ${advertisedIssuer}, ` +
+            `which is correct for a local-only install and unusable for any remote client`,
+        fixHint: `if this instance is reachable at a public URL, ${publicUrlRemedy(componentEnvPath)}`,
+    };
+}

package/dist/deploy.js

@@ -1,8 +1,10 @@
 import { spawn } from "node:child_process";
-import { dirname, join, resolve } from "node:path";
-import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { cpSync, existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
+import { COMPONENT_ENV_FILENAME, PUBLIC_URL_KEY, isLoopbackUrl, planComponentEnv, publicUrlRemedy, } from "./component-env.js";
 import { awaitOriginQuiescent, awaitReplicationConvergence, defaultConvergenceDeps, parseReplicationFailure, } from "./replication-convergence.js";
 // Files that must be present in a Flair package for deployment.
 // Mirrors the `files` array in package.json — keep in sync.
@@ -564,6 +566,159 @@ async function verifyResourcesServing(baseUrl, resources, fetchImpl) {
             `component is not serving; likely deployed the wrong package root`);
     }
 }
+// ─── The component `.env` the deploy ships (flair#1005 item 2) ────────────────
+//
+// `harper deploy` packs its own CWD — every file under it except `node_modules`
+// (harper/dist/bin/cliOperations.js sets `skip_node_modules` unless explicitly
+// disabled, and harper/dist/components/packageComponent.js's `isExcluded` is the
+// only other filter). So a `.env` sitting in the deploy root ships; there is no
+// entries list to add it to, and no `.env` is special-cased away. Verified by
+// running harper's own packer over a directory containing one.
+//
+// What this must NOT do is write into `packageRoot`. That directory is an
+// npm-installed package — frequently not writable by the deploying user, shared by
+// every deploy from this machine, and, when the operator has put their own `.env`
+// there, theirs. So when flair has a key to add, it copies the deploy root to a
+// temp directory, writes the merged file THERE, and points harper at the copy. The
+// operator's tree is read and never written.
+//
+// The copy skips `node_modules` for the obvious reason (it can be gigabytes) and
+// for the correctness one: harper excludes it at pack time regardless, so the
+// resulting payload is identical. `deploy-staging.test.ts` asserts that identity
+// with harper's real packer rather than trusting this paragraph.
+const STAGING_PREFIX = "flair-deploy-";
+/** True for any path inside a `node_modules` directory under `root`. */
+function isNodeModulesPath(root, path) {
+    const rel = relative(root, path);
+    return rel !== "" && rel.split(sep).includes("node_modules");
+}
+/**
+ * Resolve the value `FLAIR_PUBLIC_URL` should carry for this deploy, or null.
+ *
+ * The deploy already knows this: `url` is the target it hands to harper AND the
+ * base URL it verifies the served API against immediately afterwards. A loopback
+ * target yields null — baking `http://127.0.0.1:...` into a shipped `.env` is
+ * precisely the misconfiguration flair#1000 is about, so it is never generated.
+ *
+ * Anything that is not an absolute http(s) URL also yields null. `--target` is
+ * operator-supplied and reaches here before harper has had a chance to reject it,
+ * and a value that is not a URL cannot be the base of a discovery document — so
+ * "cannot be determined" is answered by supplying nothing rather than by baking in
+ * a string that would make every advertised endpoint malformed.
+ */
+export function resolveDeployPublicUrl(url) {
+    const trimmed = String(url ?? "").replace(/\/+$/, "");
+    let parsed;
+    try {
+        parsed = new URL(trimmed);
+    }
+    catch {
+        return null;
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+        return null;
+    return isLoopbackUrl(trimmed) ? null : trimmed;
+}
+/**
+ * Prepare the directory harper will pack, supplying `FLAIR_PUBLIC_URL` when the
+ * payload does not already carry it. Returns `packageRoot` unchanged (and a no-op
+ * cleanup) whenever there is nothing to add — the common cases being a loopback
+ * target and an operator who has already set the key.
+ */
+export function stageDeployRoot(packageRoot, publicUrl) {
+    const envPath = join(packageRoot, COMPONENT_ENV_FILENAME);
+    const existing = existsSync(envPath) ? readFileSync(envPath, "utf8") : null;
+    const plan = planComponentEnv(existing, publicUrl);
+    if (plan.text === null) {
+        return { dir: packageRoot, plan, cleanup: () => { } };
+    }
+    const dir = mkdtempSync(join(tmpdir(), STAGING_PREFIX));
+    try {
+        cpSync(packageRoot, dir, {
+            recursive: true,
+            dereference: false,
+            verbatimSymlinks: true,
+            filter: (src) => !isNodeModulesPath(packageRoot, src),
+        });
+        // 0600 even though the generated content is a public URL: an operator's own
+        // keys may have been merged through, and the file's permissions should not
+        // depend on what happens to be in it.
+        writeFileSync(join(dir, COMPONENT_ENV_FILENAME), plan.text, { mode: 0o600 });
+    }
+    catch (err) {
+        rmSync(dir, { recursive: true, force: true });
+        throw err;
+    }
+    return { dir, plan, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+}
+// ─── Post-deploy: is the instance advertising a URL a client can reach? ───────
+//
+// This is the check that makes the writer above testable in production rather than
+// merely present. flair#1000 was a deploy that reported success while the served
+// OAuth discovery document named `http://127.0.0.1:9980` for every endpoint, so a
+// remote client followed discovery to its own loopback. Nothing in the deploy
+// noticed, because nothing looked.
+//
+// A failure here fails the command even though the component IS deployed — the same
+// contract as verifyResourcesServing above ("the tool must not be able to lie"). A
+// deploy that leaves an instance no client can authorize against is not a success,
+// and the operator needs to hear that at deploy time rather than from a user.
+//
+// An unreadable document is NOT treated as a pass: it is reported as a check that
+// did not run, with the reason.
+//
+// It POLLS rather than reading once. A Fabric restart is rolling, so for a while
+// after `harper deploy` returns, a request to the cluster can be answered by a node
+// that has not restarted yet and is still running the previous environment. Reading
+// once would turn that race into a failed deploy for a change that was fine. The
+// poll only ever converts a "not yet" into a wait — a genuinely misconfigured
+// instance still fails, at the deadline.
+export const OAUTH_METADATA_PATH = "/OAuthMetadata";
+export const DEFAULT_ISSUER_CHECK_TIMEOUT_MS = 60_000;
+export const ISSUER_CHECK_POLL_INTERVAL_MS = 5_000;
+/** One read of the discovery document. `issuer: null` means "could not be read". */
+async function readAdvertisedIssuer(url, fetchImpl) {
+    try {
+        const res = await fetchImpl(url, { method: "GET", signal: AbortSignal.timeout(10_000) });
+        if (!res.ok)
+            return { issuer: null, detail: `HTTP ${res.status} from ${url}` };
+        const doc = (await res.json());
+        if (typeof doc?.issuer !== "string" || doc.issuer === "") {
+            return { issuer: null, detail: `${url} returned no issuer` };
+        }
+        return { issuer: doc.issuer, detail: `issuer ${doc.issuer}` };
+    }
+    catch (err) {
+        return { issuer: null, detail: `${url} could not be read: ${err?.message ?? err}` };
+    }
+}
+export async function verifyPublicIssuer(o) {
+    const { baseUrl, timeoutMs = DEFAULT_ISSUER_CHECK_TIMEOUT_MS, pollIntervalMs = ISSUER_CHECK_POLL_INTERVAL_MS, fetchImpl = fetch, onProgress, } = o;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = `${base}${OAUTH_METADATA_PATH}`;
+    onProgress?.(`checking ${OAUTH_METADATA_PATH} advertises a reachable issuer...`);
+    const deadline = Date.now() + timeoutMs;
+    let last = await readAdvertisedIssuer(url, fetchImpl);
+    for (;;) {
+        if (last.issuer !== null && !isLoopbackUrl(last.issuer)) {
+            return { checked: true, issuer: last.issuer, detail: last.detail };
+        }
+        if (Date.now() >= deadline)
+            break;
+        onProgress?.(last.issuer === null
+            ? `${OAUTH_METADATA_PATH} not readable yet (${last.detail}) — retrying...`
+            : `${OAUTH_METADATA_PATH} still advertises ${last.issuer} — the restart may not have reached every node yet, retrying...`);
+        await sleep(Math.min(pollIntervalMs, Math.max(0, deadline - Date.now())));
+        last = await readAdvertisedIssuer(url, fetchImpl);
+    }
+    if (last.issuer !== null) {
+        throw new Error(`deploy verification: ${url} advertises issuer ${last.issuer} — a loopback address, which ` +
+            `every remote client will follow to its own machine (flair#1000). ${PUBLIC_URL_KEY} is ` +
+            `not reaching the deployed component's process.env. Fix: ` +
+            `${publicUrlRemedy(`${COMPONENT_ENV_FILENAME} in the deploy root`, base)}, then re-deploy.`);
+    }
+    return { checked: false, issuer: null, detail: last.detail };
+}
 // The tool must not be able to lie. harper's deploy CLI can print
 // "Successfully deployed" for an empty component — the only way to know the
 // deploy actually worked is to curl the served API and check it isn't 404.
@@ -607,7 +762,25 @@ export async function deploy(opts) {
         CLI_TARGET_USERNAME: opts.fabricUser,
         CLI_TARGET_PASSWORD: opts.fabricPassword,
     };
-    const { replicationWarning, convergedAfterReplicationError } = await runHarperDeploy(harperBin, args, packageRoot, childEnv, opts, url, project);
+    // flair#1005 item 2: supply FLAIR_PUBLIC_URL to the component being deployed.
+    // `deployRoot` is packageRoot itself whenever there is nothing to add.
+    const publicUrl = resolveDeployPublicUrl(url);
+    const staged = stageDeployRoot(packageRoot, publicUrl);
+    for (const notice of staged.plan.notices) {
+        console.warn(`⚠ flair deploy: ${notice}`);
+        opts.onProgress?.(notice);
+    }
+    if (staged.plan.action === "added") {
+        opts.onProgress?.(`shipping ${COMPONENT_ENV_FILENAME} with ${PUBLIC_URL_KEY}=${staged.plan.effectiveValue}`);
+    }
+    let replicationWarning;
+    let convergedAfterReplicationError;
+    try {
+        ({ replicationWarning, convergedAfterReplicationError } = await runHarperDeploy(harperBin, args, staged.dir, childEnv, opts, url, project));
+    }
+    finally {
+        staged.cleanup();
+    }
     // harper can print "Successfully deployed" for a component that isn't
     // actually serving anything (the incident this closes: an empty deploy,
     // reported success, /Memory 404ing in prod). Verify by curling the served
@@ -622,6 +795,20 @@ export async function deploy(opts) {
             timeoutMs: opts.verifyTimeoutMs ?? DEFAULT_VERIFY_TIMEOUT_MS,
             onProgress: opts.onProgress,
         });
+        // Only meaningful for a target that is not loopback: a local Harper SHOULD
+        // advertise loopback, and asserting otherwise there would be wrong.
+        if (publicUrl) {
+            const issuerCheck = await verifyPublicIssuer({ baseUrl: url, onProgress: opts.onProgress });
+            if (issuerCheck.checked) {
+                opts.onProgress?.(`discovery advertises ${issuerCheck.issuer}`);
+            }
+            else {
+                // Not a pass. Say which check did not run, and why.
+                console.warn(`⚠ flair deploy: could not verify the advertised OAuth issuer — ${issuerCheck.detail}. ` +
+                    `This check did NOT run; ${PUBLIC_URL_KEY} may or may not have taken effect.`);
+                opts.onProgress?.(`issuer check did not run — ${issuerCheck.detail}`);
+            }
+        }
     }
     return {
         url,