feat(e2e-helpers): fabriquer un portefeuille, pour un test comme pour un déploiement

Trois appelants veulent la même chose — un portefeuille neuf, ses octets et son mot de passe : la suite du polyfill à son démarrage, la suite d'une application au sien, et un humain une fois pour provisionner un déploiement. Rien ne produisait ce fichier ; il fallait aller le chercher à la main sur nextgraph.eu. Mêmes entrées, mêmes sorties, mais des appelants de nature différente : une suite ne va pas lancer un sous-processus et analyser sa sortie, et un humain ne va pas écrire un fichier jetable pour appeler une fonction. Donc une fonction, et un script mince par-dessus. mintWalletBytes(password, name) rend les OCTETS, pas un chemin. C'est une correction de ce qui existait : exportWalletFile imposait le disque à tout le monde, et la suite applicative écrivait un fichier temporaire pour le relire aussitôt en mémoire, puis devait le nettoyer. Elle ne le fait plus — serveApp prend les octets. Qui veut un fichier l'écrit ; personne n'y est forcé. Le script exige --password et refuse d'en inventer un, et refuse d'écraser un .ngw existant sans --force, vérifié AVANT de fabriquer quoi que ce soit. Exécuté pour de vrai : 800 octets, et le mot de passe imprimé est celui passé en entrée. C'est le seul des trois cas qu'aucune suite n'exerce, donc le seul qui pouvait être livré cassé sans que rien ne le dise. Ce qui ne change pas : les suites fabriquent un portefeuille par exécution et n'en héritent jamais ; le provisionnement veut l'inverse, durable et conservé. Ils partagent la fabrication et l'export, ils divergent sur la durée de vie. Les identifiants en dur deviennent un paramètre — les suites passent toujours les leurs, le script prend ceux qu'on lui donne, et il n'existe aucun mot de passe par défaut.
2026-08-16 15:44:37 +02:00
parent 07dfe68473
commit b50591f5bd
9 changed files with 239 additions and 27 deletions
@@ -14,7 +14,8 @@
 *
 * ── The five things it gives you ─────────────────────────────────────────────
 *  - a WALLET: minted for this run, exported as bytes an application can serve, imported into
- *    a profile (`wallet.ts`);
+ *    a profile (`wallet.ts`) — and, for the one-off that provisions a deployment rather than a
+ *    run, the same minting behind an executable (`bin/mint-wallet.ts`);
 *  - the BROKER CROSSING, which dispatches on the screen it can see and identifies the
 *    application by ORIGIN (`broker.ts`, `nextgraph-ui.ts`);
 *  - PROFILES that belong to one run and are cleaned up after it (`profiles.ts`, `browser.ts`);
@@ -53,10 +54,13 @@ export { serveOnEphemeralPort } from "./serve";
 export { BROKER_LOGIN_MS, BROKER_ROUND_TRIP_MS, completeBrokerLogin, setupBrokerPage } from "./broker";

 export {
+  DEFAULT_WALLET_NAME,
  createWalletInContext,
  emptyProfileContext,
+  exportWalletBytes,
  exportWalletFile,
  importWalletFile,
+  mintWalletBytes,
  mintWalletProfile,
  mintWalletProfileKeepingContext,
  type WalletCredentials,
@@ -1,5 +1,5 @@
 /**
- * The page that fetches a wallet's bytes — bundled and served by `exportWalletFile`.
+ * The page that fetches a wallet's bytes — bundled and served by `exportWalletBytes`.
 *
 * ── Why a page has to do this at all ─────────────────────────────────────────
 * A wallet's bytes exist only inside the broker iframe: `wallet_get_file()` is an RPC to the
@@ -1,6 +1,6 @@
 /**
 * The wallet lifecycle: mint one by driving the wallet application's real interface, get its
- * bytes out as a `.ngw` file, and put a `.ngw` file into a browser profile.
+ * bytes out (`.ngw` contents, file optional), and put a `.ngw` file into a browser profile.
 *
 * ── Why the real interface and not a shortcut ────────────────────────────────
 * A wallet obtained any other way is not the one a person has. The wallet application is an
@@ -26,7 +26,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { closeQuietly, within } from "./deadline";
-import { launchWatchedContext, newPage } from "./browser";
+import { closeContext, launchWatchedContext, newPage } from "./browser";
 import { newRunProfile, type RunProfile } from "./profiles";
 import { serveOnEphemeralPort } from "./serve";
 import { setupBrokerPage } from "./broker";
@@ -55,6 +55,16 @@ export interface WalletCredentials {
  readonly password: string;
 }

+/**
+ * The name a wallet gets when the caller has no opinion about it.
+ *
+ * A wallet's name is what a person types to pick one among several, and nothing in NextGraph
+ * keys off it — so a caller minting the only wallet it will ever hold has nothing to decide
+ * here. The PASSWORD never gets a default: it is the only thing between the file and whoever
+ * finds it, and a defaulted one would be a published secret.
+ */
+export const DEFAULT_WALLET_NAME = "ng-wallet";
+
 /**
 * Create a wallet in `ctx`'s profile by walking the wallet application, then unlock it once.
 *
@@ -201,19 +211,26 @@ function buildExportBundle(): string {
 }

 /**
- * Materialize the wallet held by `ctx`'s profile as a `.ngw` file at `ngwPath`, and return its
- * size in bytes.
+ * The bytes of the wallet held by `ctx`'s profile — the contents of a `.ngw` file, without a
+ * `.ngw` file.
 *
 * Why an application's own suite needs this: a deployment that hands a wallet out — an access
 * barrier with a download link, say — must be tested against a REAL wallet. Serving a
 * placeholder there makes the download step a decoration: importing it cannot let anybody in,
 * so the check that the link works cannot fail for the right reason.
+ *
+ * ── Why BYTES are the primitive and the file the convenience ─────────────────
+ * Every caller here already has the bytes in hand — they arrive from the broker iframe — and
+ * only some of them want a file. This used to write one unconditionally, so a suite that
+ * serves a wallet from memory had to name a temp path, write it, read it straight back and
+ * remember to remove it: three steps and a cleanup to get back what the function had. A caller
+ * that genuinely wants a file writes these bytes (or calls {@link exportWalletFile}), which is
+ * one step in the direction nobody has to undo.
 */
-export async function exportWalletFile(
+export async function exportWalletBytes(
  ctx: BrowserContext,
-  ngwPath: string,
  walletPassword: string,
-): Promise<number> {
+): Promise<Uint8Array> {
  const bundle = buildExportBundle();
  const html =
    '<!DOCTYPE html><html><head><meta charset="utf-8"><title>wallet export</title></head>' +
@@ -249,10 +266,63 @@ export async function exportWalletFile(
          ).__ngWalletExport.file(),
      ),
    );
-    fs.writeFileSync(ngwPath, Buffer.from(exported.b64, "base64"));
-    return exported.len;
+    return new Uint8Array(Buffer.from(exported.b64, "base64"));
  } finally {
    await closeQuietly("the wallet export page", () => page.close());
    close();
  }
 }
+
+/**
+ * The same wallet, written to `ngwPath`, returning its size in bytes.
+ *
+ * For the callers that want a FILE — a browser's file input takes a path, and a person
+ * provisioning a deployment has to put the wallet somewhere. Everyone else takes the bytes.
+ */
+export async function exportWalletFile(
+  ctx: BrowserContext,
+  ngwPath: string,
+  walletPassword: string,
+): Promise<number> {
+  const bytes = await exportWalletBytes(ctx, walletPassword);
+  fs.writeFileSync(ngwPath, bytes);
+  return bytes.length;
+}
+
+/**
+ * A wallet that did not exist a moment ago, as the bytes of a `.ngw`: mint one by walking the
+ * wallet application, take its bytes out, and drop everything else.
+ *
+ * The one call behind all three callers who need a fresh wallet — this package's own suite, a
+ * consuming application's suite, and a person provisioning a deployment (see `bin/mint-wallet.ts`,
+ * which is this function plus a `writeFileSync` and two `console.log`s).
+ *
+ * ── What it deliberately does NOT keep ───────────────────────────────────────
+ * The browser profile the wallet was minted in is discarded here. That is not a shortcut: the
+ * wallet's repos live on the broker and the bytes returned are what opens them, so the profile
+ * is scaffolding in every one of the three cases — including the durable one, where what is
+ * kept is the FILE the caller writes, never a browser directory.
+ *
+ * A suite that needs the profile to survive — because its actors sign in THROUGH it rather than
+ * importing the file — composes the two halves itself: {@link mintWalletProfile} for a profile
+ * that lasts the run, then {@link exportWalletBytes} over it. Same minting, same export,
+ * different lifetime, which is the only thing the two paths disagree about.
+ */
+export async function mintWalletBytes(
+  password: string,
+  name: string = DEFAULT_WALLET_NAME,
+): Promise<Uint8Array> {
+  const profile = await mintWalletProfile(`minting the wallet "${name}"`, { name, password });
+  try {
+    // A context of its own over the profile, opened after the creation one closed — the order
+    // `mintWalletProfile` already imposes, and the one every export in this repository uses.
+    const ctx = await launchWatchedContext("wallet-export", profile.dir);
+    try {
+      return await exportWalletBytes(ctx, password);
+    } finally {
+      await closeContext("wallet-export", ctx);
+    }
+  } finally {
+    profile.discard();
+  }
+}