@superblocksteam/sdk 2.0.123 → 2.0.124-next.0

package/src/cli-replacement/home-npmrc.mts

@@ -0,0 +1,409 @@
+import { mkdir } from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import {
+  type NpmRegistryClient,
+  type NpmRegistryFetchResult,
+  PRESERVE_NPMRC_SCOPES,
+  restoreInitialNpmrc,
+  snapshotInitialNpmrc,
+  type SnapshotInitialNpmrcOutcome,
+  writeNpmrc,
+} from "@superblocksteam/vite-plugin-file-sync/npm-registry";
+
+import { getErrorMeta, type Logger } from "../telemetry/logging.js";
+
+/**
+ * File mode applied to the userconfig after every write. `0o400` (owner
+ * read, no write) strips the owner write bit so any `npm config set` or
+ * stray write that opens the file `O_WRONLY` fails loudly instead of
+ * silently retargeting the configured registry. The atomic rename inside
+ * `writeNpmrc` is governed by parent-dir perms — not the target's mode —
+ * so this writer can still re-sync the file on subsequent config changes.
+ * The stricter mode is a speed bump, not a security boundary: the CLI
+ * user can always `chmod +w` first.
+ */
+export const HOME_NPMRC_MODE = 0o400;
+
+const LOG_PREFIX = "[home-npmrc]";
+
+/**
+ * Most recent `snapshotInitialNpmrc` outcome, keyed by userconfig target
+ * path. `syncHomeNpmrc` runs once per `NpmRegistryClient` cache refresh,
+ * so the snapshot (taken on a `configured`/`stale` resolve) and the
+ * destructive restore (on a later `not-configured` resolve) happen on
+ * SEPARATE invocations within one pod's lifetime. We remember the outcome
+ * across invocations so the not-configured branch can refuse to unlink the
+ * userconfig when the snapshot is known to have FAILED — a silent EXDEV
+ * (target and backup on different filesystems) leaves a real baked-in file
+ * with no backup, and unlinking it would fail the customer's install open
+ * to public npm (APPS-4428).
+ *
+ * Keyed by path so the test suite's per-test tmpdir `homeDir`s stay
+ * isolated. Absent (never snapshotted this process — e.g. not-configured
+ * from boot, or the policy-only path that deliberately skips the snapshot)
+ * preserves the original APPS-4328 behaviour: a missing backup is "nothing
+ * to preserve", so the unlink is allowed.
+ */
+const lastSnapshotOutcomeByPath = new Map<
+  string,
+  SnapshotInitialNpmrcOutcome
+>();
+
+/**
+ * Resolves the Superblocks-owned npm userconfig path. Centralised so the
+ * image-build and CLI auto-upgrade `--userconfig=` plumbing and the
+ * runtime writer all agree on the same location. The file lives inside a
+ * hidden directory, so it is named `npmrc` (without a leading dot) by
+ * convention; the directory itself carries the visibility bit. `homeDir`
+ * defaults to `os.homedir()`; tests override it.
+ */
+export function superblocksNpmrcPath(homeDir?: string): string {
+  return path.join(homeDir ?? os.homedir(), ".superblocks", "npmrc");
+}
+
+/**
+ * Resolves the directory npm should write its per-run debug logs to during
+ * Superblocks-spawned installs in the live-edit pod. Unlike
+ * `superblocksNpmrcPath` (home-based), this is rooted at the application
+ * working directory — `<app>/.superblocks/logs` — so each app's install
+ * logs are co-located with the app and collectable from a predictable
+ * place. Wired into the subprocess env as `NPM_CONFIG_LOGS_DIR` via
+ * `buildInstallEnv`; npm creates the directory if it does not exist.
+ */
+export function superblocksLogsPath(appDir: string): string {
+  return path.join(appDir, ".superblocks", "logs");
+}
+
+/**
+ * Resolves the on-disk backup path for the Superblocks-owned npm
+ * userconfig. Symmetric with `superblocksNpmrcPath`: lives next to the
+ * userconfig under `~/.superblocks/`. `syncHomeNpmrc` hardlinks the
+ * image-baked userconfig to this path on the first `configured` resolve
+ * so a later transition to `not-configured` has a baseline to restore
+ * from (APPS-4328) — mirroring the project-`.npmrc` capture/restore added
+ * in APPS-4320.
+ *
+ * The leading-dot filename mirrors the project-side `NPMRC_DEFAULT_FILENAME`
+ * convention even though the live userconfig is `npmrc` (no dot). The dot
+ * here is a convention-only marker that this file is the backup, not the
+ * active userconfig.
+ */
+export function superblocksNpmrcBackupPath(homeDir?: string): string {
+  return path.join(homeDir ?? os.homedir(), ".superblocks", "npmrc.default");
+}
+
+/**
+ * Outcome reported by `syncHomeNpmrc`. Surfaced for tracing + tests rather
+ * than passed back to the caller's control flow — every outcome here is a
+ * success from the dev-startup point of view (the writer is best-effort
+ * and never throws).
+ */
+export type SyncHomeNpmrcOutcome =
+  /** Config is set and `~/.superblocks/npmrc` was created or rewritten. */
+  | "written"
+  /**
+   * Server returned `not-configured`. The image-default userconfig (if
+   * any) was restored from the `~/.superblocks/npmrc.default` backup
+   * captured on a prior configured boot. If no backup exists and the
+   * userconfig is Superblocks-owned, the file is removed entirely rather
+   * than left pinned at a previous org's registry/token (APPS-4328).
+   *
+   * This is what the gpoulios-sb review on PR #19621 flagged: long-lived
+   * Superblocks-spawned npm/pnpm processes pinned at the userconfig must
+   * not silently inherit a configured-org's registry after the org has
+   * been deconfigured. While live-edit pods are single-tenant per EE
+   * deployment so cross-org leakage isn't reachable, leaving the stale
+   * file behind is still wrong — rollback-to-default is the right
+   * semantic.
+   */
+  | "restored-not-configured"
+  /**
+   * Cold cache + the registry server is unreachable (or JWT refresh
+   * failed). We can't tell "deliberately unset" from a transient outage,
+   * so we leave the userconfig whatever it currently is rather than
+   * punch a hole in the CLI auto-upgrade about to run.
+   */
+  | "skipped-unreachable"
+  /**
+   * `snapshotInitialNpmrc` failed silently this pod (e.g. EXDEV — target
+   * and backup straddle filesystems), so a real baked-in userconfig
+   * exists with NO restore baseline. We fail closed on both sides of the
+   * lifecycle so the baked file is never lost (APPS-4428):
+   *
+   *   - On a `configured` resolve we refuse to overwrite the baked file
+   *     with the managed private-registry content. A later
+   *     `not-configured` transition could not undo the rewrite — restore
+   *     from backup is impossible (no backup) and unlinking would delete
+   *     the baseline. Leave the baked file in place; the customer's
+   *     install routes through the image-baked registry until the next
+   *     sync (or pod boot) where the snapshot succeeds.
+   *
+   *   - On a `not-configured` resolve (separate cache-refresh invocation)
+   *     we withhold the unlink for the same reason: the file IS the baked
+   *     baseline (the configured branch skipped the rewrite), so deleting
+   *     it would break the install path.
+   *
+   * Distinct from `restored-not-configured` so telemetry doesn't conflate
+   * "rolled back to baseline" with "left alone because we couldn't".
+   */
+  | "skipped-snapshot-failed"
+  /** The sync failed; the file is unchanged. Details in the warn log. */
+  | "error";
+
+export interface SyncHomeNpmrcResult {
+  outcome: SyncHomeNpmrcOutcome;
+  /** Absolute path that was inspected / mutated. */
+  path: string;
+  /** Resolved fetch source when `outcome === "written"`. */
+  source?: NpmRegistryFetchResult["source"];
+}
+
+export interface SyncHomeNpmrcDeps {
+  /**
+   * Pre-constructed client with the LD-flag check, JWT provider, and
+   * `refreshJwt` hook bound. We deliberately do not instantiate one
+   * inside this helper: AppShell + TemplateRenderer share a single
+   * client with the dev-server session so cache TTL, 401 retry, and
+   * stale-fallback are coherent across all userconfig materialisation
+   * sites.
+   */
+  npmRegistryClient: NpmRegistryClient;
+  logger: Logger;
+  /**
+   * Override for `os.homedir()`. Tests redirect to an isolated tmpdir so
+   * the real `~/.superblocks/` is never touched. Production callers
+   * leave it unset.
+   */
+  homeDir?: string;
+}
+
+/**
+ * Materialises `~/.superblocks/npmrc` from the server-fetched per-org
+ * npm registry config. Designed to run at dev-server CLI startup, after
+ * the `NpmRegistryClient` is wired but BEFORE the global Superblocks CLI
+ * auto-upgrade: with the file in place and the auto-upgrade invoking
+ * npm with `NPM_CONFIG_USERCONFIG=~/.superblocks/npmrc`, the
+ * `npm install -g @superblocksteam/cli@…` invocation resolves through
+ * the customer's private registry rather than `registry.npmjs.org`.
+ *
+ * Behaviour:
+ *
+ *   - `client.getConfig()` resolves `configured` (or `stale`): snapshot
+ *     the image-default userconfig to `~/.superblocks/npmrc.default`
+ *     (once per pod boot via `link(2)`), then write
+ *     `~/.superblocks/npmrc` atomically with mode `0o400`. The snapshot
+ *     captures whatever the image baked (EE GHPR scope + token, or a
+ *     no-file baseline on a fresh developer laptop) so the
+ *     `not-configured` branch below has a baseline to restore from. The
+ *     parent dir is `mkdir -p`'d first so a fresh `$HOME` on a
+ *     developer's laptop is handled the same as a pod where the image
+ *     already pre-creates `/home/node/.superblocks/`. If the snapshot
+ *     attempt FAILS against a real baked file (e.g. EXDEV), we fail
+ *     closed and SKIP the rewrite: see `skipped-snapshot-failed` in
+ *     `SyncHomeNpmrcOutcome` for why (APPS-4428).
+ *
+ *   - `client.getConfig()` resolves `not-configured`: restore the
+ *     image-default userconfig from the `~/.superblocks/npmrc.default`
+ *     backup captured on a prior `configured` boot. When no backup
+ *     exists (cold boot where the org was deconfigured before the first
+ *     `configured` resolve), the userconfig is unlinked entirely so a
+ *     long-lived Superblocks-spawned npm/pnpm process cannot silently
+ *     inherit a previously-configured org's registry/token. Closes the
+ *     stale-userconfig hole flagged on PR #19621 (APPS-4328). One
+ *     exception: if this process already SAW a snapshot attempt FAIL for
+ *     this path, the configured branch above will have left the baked
+ *     userconfig in place (no managed rewrite happened), so unlinking
+ *     here would delete the baked baseline. Withhold the unlink (APPS-4428).
+ *
+ *   - `client.getConfig()` resolves `unreachable`: cold cache + the
+ *     registry server is down (or JWT refresh failed). Leave the file
+ *     alone — the fail-closed gate in the CLI auto-upgrade is the
+ *     backstop if the upgrade reaches a public registry.
+ *
+ *   - Any throw (fs error, etc.): log + return `outcome: "error"`. We
+ *     must not crash dev-server startup on a best-effort step.
+ *
+ * Idempotent for a given resolved config — safe to invoke on every
+ * `NpmRegistryClient` cache refresh as well as on startup.
+ */
+export async function syncHomeNpmrc(
+  deps: SyncHomeNpmrcDeps,
+): Promise<SyncHomeNpmrcResult> {
+  const targetPath = superblocksNpmrcPath(deps.homeDir);
+  const backupPath = superblocksNpmrcBackupPath(deps.homeDir);
+
+  let result: NpmRegistryFetchResult;
+  try {
+    result = await deps.npmRegistryClient.getConfig();
+  } catch (error) {
+    // `NpmRegistryClient` only throws for the deliberate-denial branches
+    // (RBAC 403, malformed request 400, double-401). All three signal a
+    // structurally broken session — surface the warn but keep the
+    // userconfig as-is rather than forging a "default" file that masks
+    // the real failure.
+    deps.logger.warn(
+      `${LOG_PREFIX} client.getConfig() failed; ~/.superblocks/npmrc left unchanged`,
+      { path: targetPath, ...getErrorMeta(error) },
+    );
+    return { outcome: "error", path: targetPath };
+  }
+
+  if (result.source === "unreachable") {
+    deps.logger.warn(
+      `${LOG_PREFIX} registry server unreachable with no cached config; ~/.superblocks/npmrc left unchanged`,
+      { path: targetPath },
+    );
+    return { outcome: "skipped-unreachable", path: targetPath };
+  }
+
+  if (!result.config.configured) {
+    if (result.config.allowInstallScripts === false) {
+      // Org policy disallows install scripts even without registry rows.
+      // Write a policy-only userconfig with `ignore-scripts=true`.
+      //
+      // IMPORTANT: we deliberately skip `snapshotInitialNpmrc` here.
+      // On a repeated sync the target already contains our own policy
+      // file; snapshotting it would poison the backup with policy content
+      // instead of the image-baked baseline, so a later flip to
+      // allowInstallScripts=true could never restore the original.
+      try {
+        await mkdir(path.dirname(targetPath), { recursive: true });
+        await writeNpmrc(targetPath, result.config, {
+          preserveScopeLines: PRESERVE_NPMRC_SCOPES,
+          mode: HOME_NPMRC_MODE,
+        });
+        deps.logger.info(
+          `${LOG_PREFIX} wrote policy-only userconfig (ignore-scripts)`,
+          { path: targetPath },
+        );
+        return { outcome: "written", path: targetPath };
+      } catch (error) {
+        deps.logger.warn(`${LOG_PREFIX} policy-only write failed`, {
+          path: targetPath,
+          ...getErrorMeta(error),
+        });
+        return { outcome: "error", path: targetPath };
+      }
+    } else {
+      // Restore the image-default userconfig from the backup captured on a
+      // prior configured boot. When the backup is absent (the org was never
+      // configured on this pod, OR the pod was rewritten before this
+      // commit landed) the userconfig is unlinked instead — leaving a
+      // stale Superblocks-owned userconfig in place would silently pin
+      // npm/pnpm at a previous org's registry/token, the exact hole
+      // gpoulios-sb flagged on PR #19621.
+      //
+      // EXCEPT when this process's most recent snapshot attempt FAILED:
+      // the snapshot ran against a real baked-in userconfig but `link(2)`
+      // failed silently (e.g. EXDEV across filesystems), so no backup
+      // exists for an unrelated reason. Unlinking here would delete a file
+      // that SHOULD have been preserved and restored. We can't distinguish
+      // that from "no backup" inside `restoreInitialNpmrc`, so we withhold
+      // the unlink option and leave the userconfig in place (APPS-4428).
+      // Absent state (never snapshotted: not-configured from boot, or the
+      // policy-only path) keeps the original APPS-4328 unlink behaviour.
+      const snapshotFailed =
+        lastSnapshotOutcomeByPath.get(targetPath) === "failed";
+      if (snapshotFailed) {
+        deps.logger.warn(
+          `${LOG_PREFIX} registry not configured but the userconfig snapshot failed earlier; leaving the userconfig in place rather than risk deleting an un-backed-up baseline`,
+          { path: targetPath },
+        );
+      }
+      // Best-effort: `restoreInitialNpmrc` swallows fs errors as
+      // warn-and-no-op so dev-server startup never crashes on cleanup.
+      try {
+        await restoreInitialNpmrc(targetPath, backupPath, {
+          unlinkTargetWhenBackupMissing: !snapshotFailed,
+        });
+        // On the `snapshotFailed` branch we passed
+        // `unlinkTargetWhenBackupMissing: false`, so `restoreInitialNpmrc`
+        // intentionally no-ops (leaves the userconfig in place). Return
+        // the dedicated `skipped-snapshot-failed` outcome rather than
+        // `restored-not-configured` — nothing was restored or removed,
+        // and conflating the two would mislead telemetry/dashboards into
+        // thinking the baseline rollback ran when it didn't. The warn
+        // above already describes the decision; an info log here would
+        // contradict it during incident investigation.
+        if (snapshotFailed) {
+          return { outcome: "skipped-snapshot-failed", path: targetPath };
+        }
+        deps.logger.info(
+          `${LOG_PREFIX} registry not configured; restored image-default userconfig (or removed Superblocks-owned file when no backup exists)`,
+          { path: targetPath },
+        );
+        return { outcome: "restored-not-configured", path: targetPath };
+      } catch (error) {
+        deps.logger.warn(`${LOG_PREFIX} restore failed`, {
+          path: targetPath,
+          ...getErrorMeta(error),
+        });
+        return { outcome: "error", path: targetPath };
+      }
+    }
+  }
+
+  try {
+    // `mkdir -p` so a fresh `$HOME` (developer laptop, unprovisioned
+    // sandbox) doesn't ENOENT inside `writeNpmrc`'s atomic-rename. Pod
+    // images already create `/home/node/.superblocks/` at build time, so
+    // this is a no-op there.
+    await mkdir(path.dirname(targetPath), { recursive: true });
+    // Snapshot the image-default userconfig BEFORE the first rewrite so
+    // the not-configured branch above has a restore baseline. Hardlink
+    // is atomic + idempotent: only one of N concurrent callers wins
+    // (kernel-serialised), and a subsequent `writeNpmrc` tmp+rename
+    // gives the userconfig a fresh inode while the backup inode (the
+    // baked content) stays alive. EEXIST after the first capture is
+    // expected and not a warning.
+    //
+    // Remember the outcome so a later `not-configured` resolve (a
+    // separate `syncHomeNpmrc` invocation) can tell whether a usable
+    // backup actually exists before it asks `restoreInitialNpmrc` to
+    // unlink the userconfig. A silent `failed` here (e.g. EXDEV) must
+    // NOT lead the not-configured branch to delete a real baked file
+    // that has no backup (APPS-4428).
+    const snapshotOutcome = await snapshotInitialNpmrc(targetPath, backupPath);
+    lastSnapshotOutcomeByPath.set(targetPath, snapshotOutcome);
+
+    // FAIL CLOSED on snapshot failure (APPS-4428, gpoulios-sb review of
+    // PR #19690). When a real baked file existed but the hardlink to
+    // `backupPath` failed (only `"failed"` reports this — `"no-source"`
+    // means there was nothing to snapshot in the first place), we have
+    // no way to undo a managed rewrite later: a `not-configured`
+    // transition could not restore the baseline (no backup) and could
+    // not safely unlink the file (it would delete the baseline). The
+    // earlier guard only addressed the unlink side and let the rewrite
+    // happen anyway, which still left stale private-registry config and
+    // auth on disk after deconfigure. The only safe choice is to leave
+    // the baked userconfig alone here — the install path falls back to
+    // whatever the image baked (typically EE GHPR), which is the
+    // pre-private-registry default behaviour.
+    if (snapshotOutcome === "failed") {
+      deps.logger.warn(
+        `${LOG_PREFIX} userconfig snapshot failed; refusing to overwrite the baked userconfig with managed private-registry content (no restore baseline exists)`,
+        { path: targetPath, source: result.source },
+      );
+      return { outcome: "skipped-snapshot-failed", path: targetPath };
+    }
+
+    await writeNpmrc(targetPath, result.config, {
+      preserveScopeLines: PRESERVE_NPMRC_SCOPES,
+      mode: HOME_NPMRC_MODE,
+    });
+    deps.logger.info(`${LOG_PREFIX} wrote ~/.superblocks/npmrc`, {
+      path: targetPath,
+      source: result.source,
+      mode: HOME_NPMRC_MODE.toString(8).padStart(4, "0"),
+    });
+    return { outcome: "written", path: targetPath, source: result.source };
+  } catch (error) {
+    deps.logger.warn(`${LOG_PREFIX} write failed`, {
+      path: targetPath,
+      ...getErrorMeta(error),
+    });
+    return { outcome: "error", path: targetPath };
+  }
+}