@akanjs/devkit 3.1.0-rc.1 → 3.1.0-rc.3

package/mobile/nativeApp.test.ts

@@ -3,9 +3,11 @@ import path from "node:path";
 import type { AkanPlugin } from "akanjs";
 import type { AkanNativeTarget } from "../akanConfig";
 import type { App } from "../commandDecorators";
+import { CsrArtifactBuilder } from "../frontendBuild/csrArtifactBuilder";
 import { tempDirs, writeText } from "../testHelpers";
 import { NativeApp } from "./nativeApp";
 import { NativeConfig } from "./nativeConfig";
+import { NativePublicEnv } from "./nativePublicEnv";
 
 const makeTempRoot = tempDirs("akan-native-app-");
 
@@ -88,6 +90,139 @@ describe("NativeApp", () => {
     });
   });
 
+  describe("the server a release carries, signed or not", () => {
+    const releasing = async () => {
+      const root = await makeTempRoot();
+      const appPath = path.join(root, "apps/portal");
+      await writeText(
+        path.join(appPath, "env/env.server.main.ts"),
+        'export const env = { security: { jwtSecret: "main-jwt-0123456789" } };\n',
+      );
+      const server = { dir: path.join(root, "server"), entry: "main.js", env: {} };
+      await writeText(path.join(server.dir, "main.js"), 'const jwt = "main-jwt-0123456789";\n');
+      const app = {
+        ...fakeApp(),
+        cwdPath: appPath,
+        workspace: { workspaceRoot: root },
+        logger: { info: () => undefined, warn: () => undefined },
+      } as unknown as App;
+      const updates = { url: "https://releases.example.com/portal", publicKey: `${"a".repeat(43)}=` };
+      const nativeApp = new NativeApp(app, target({ updates }), "main");
+      const built: string[] = [];
+      nativeApp.assembleWeb = async () => undefined as never;
+      nativeApp.prepare = async () =>
+        ({
+          config: {},
+          api: {
+            requestedDistribution: () => ({ notice: null, unused: [] }),
+            build: async ({ profile }: { profile: string }) => {
+              built.push(profile);
+              return { artifacts: [], warnings: [] };
+            },
+            publishUpdate: async () => {
+              built.push("update");
+              return {};
+            },
+          },
+        }) as never;
+      return { appPath, server, nativeApp, built };
+    };
+
+    test("an unsigned release build and an unsigned update are refused when it holds a secret, a debug build is not searched", async () => {
+      const { server, nativeApp, built } = await releasing();
+      await expect(nativeApp.build("linux", { server })).rejects.toThrow(
+        "main.js holds apps/portal/env/env.server.main.ts security.jwtSecret",
+      );
+      await expect(nativeApp.publishUpdate("linux", { server })).rejects.toThrow("security.jwtSecret");
+      await nativeApp.build("linux", { server, profile: "debug" });
+      expect(built).toEqual(["debug"]);
+    });
+
+    test("an env file that cannot be evaluated stops the release instead of going unsearched", async () => {
+      const { appPath, server, nativeApp, built } = await releasing();
+      await writeText(path.join(server.dir, "main.js"), "\n");
+      await writeText(path.join(appPath, "env/env.server.develop.ts"), 'export { env } from "./missing";\n');
+      await expect(nativeApp.build("linux", { server })).rejects.toThrow(
+        "The server this app carries was not searched for the secret values of apps/portal/env/env.server.develop.ts",
+      );
+      expect(built).toEqual([]);
+    });
+  });
+
+  describe("the public env a build inlined, recorded in its bundle.json", () => {
+    const publicEnv = { AKAN_PUBLIC_ENV: "main", AKAN_PUBLIC_SERVE_DOMAIN: "akamir.com" };
+    const building = async (inlined: Record<string, string>, updates: object | undefined) => {
+      const root = await makeTempRoot();
+      const warned: string[] = [];
+      const app = {
+        ...fakeApp(),
+        workspace: { workspaceRoot: root },
+        dist: { cwdPath: path.join(root, "dist/apps/portal") },
+        logger: { info: () => undefined, warn: (message: string) => warned.push(message) },
+      } as unknown as App;
+      await CsrArtifactBuilder.writePublicEnv(
+        app,
+        Object.fromEntries(
+          Object.entries({ ...inlined, AKAN_PUBLIC_APP_NAME: "portal", AKAN_PUBLIC_RENDER_ENV: "csr" }).map(
+            ([key, value]) => [`process.env.${key}`, JSON.stringify(value)],
+          ),
+        ),
+      );
+      const nativeApp = new NativeApp(app, target(updates ? { updates } : {}), "main");
+      const built: string[] = [];
+      const writeBundle = async (dir: string) =>
+        await writeText(path.join(dir, "bundle.json"), JSON.stringify({ schema: 1, web: { hash: "w", files: 1 } }));
+      nativeApp.assembleWeb = async () => undefined as never;
+      nativeApp.prepare = async () =>
+        ({
+          config: { updates: { channel: "production" } },
+          api: {
+            packUpdate: async ({ out }: { out: string }) => {
+              built.push("pack");
+              await writeBundle(out);
+              return { out, manifest: { app: "com.portal.app", version: "1.0.0", nativeApi: "n", files: [] } };
+            },
+            release: async ({ outDir }: { outDir: string }) => {
+              built.push("release");
+              await writeBundle(outDir);
+              return {};
+            },
+          },
+        }) as never;
+      return { root, nativeApp, built, warned };
+    };
+    const updates = { url: "https://releases.example.com/portal", publicKey: `${"a".repeat(43)}=` };
+
+    test("a pack and a release record what the CSR build inlined, and the pack's record carries its hash", async () => {
+      const { root, nativeApp } = await building(publicEnv, updates);
+      const { pack } = await nativeApp.packUpdate("android", { out: path.join(root, "out") });
+      const bundle = await Bun.file(path.join(root, "out/bundle.json")).json();
+      expect(bundle.web).toEqual({
+        hash: "w",
+        files: 1,
+        publicEnv,
+        publicEnvHash: NativePublicEnv.hash(publicEnv),
+      });
+      expect(pack.publicEnvHash).toBe(NativePublicEnv.hash(publicEnv));
+      await nativeApp.releaseIos();
+      const release = await Bun.file(path.join(nativeApp.outDir("ios"), "bundle.json")).json();
+      expect(release.web.publicEnvHash).toBe(NativePublicEnv.hash(publicEnv));
+    });
+
+    test("an env an update cannot carry stops a target with updates before it builds, and only warns without", async () => {
+      const refused = { ...publicEnv, AKAN_PUBLIC_MAP_TOKEN: "pk.x" };
+      const withUpdates = await building(refused, updates);
+      await expect(withUpdates.nativeApp.releaseIos()).rejects.toThrow("AKAN_PUBLIC_MAP_TOKEN names a token");
+      expect(withUpdates.built).toEqual([]);
+      const without = await building(refused, undefined);
+      await without.nativeApp.releaseIos();
+      expect(without.built).toEqual(["release"]);
+      expect(without.warned.join("\n")).toContain("bundle.json records none");
+      const release = await Bun.file(path.join(without.nativeApp.outDir("ios"), "bundle.json")).json();
+      expect(release.web.publicEnv).toBeUndefined();
+    });
+  });
+
   test("a dev build bundles no page a release build left, and builds apart from the release it would empty", async () => {
     const root = await makeTempRoot();
     const app = {
@@ -232,36 +367,3 @@ describe("NativeApp", () => {
     );
   });
 });
-
-describe("a pack read back from its folder", () => {
-  test("takes the folder as the pack's place, and refuses what is not a takeable pack", async () => {
-    const root = await makeTempRoot();
-    const pack = {
-      schema: 1,
-      app: "lu",
-      target: "default",
-      platform: "android",
-      env: "main",
-      channel: "main",
-      appId: "com.lu",
-      appVersion: "1.0.0",
-      nativeApi: "0123456789abcdef",
-      webHash: "f".repeat(64),
-      files: 1,
-      size: 13,
-      out: "/elsewhere/updates/android",
-    };
-    const moved = path.join(root, "moved");
-    await writeText(path.join(moved, "pack.json"), JSON.stringify(pack));
-    expect(await NativeApp.readPack(moved)).toEqual({ ...pack, out: moved } as never);
-
-    await expect(NativeApp.readPack(path.join(root, "empty"))).rejects.toThrow("holds no pack.json");
-    const later = path.join(root, "later");
-    await writeText(path.join(later, "pack.json"), JSON.stringify({ ...pack, schema: 2 }));
-    await expect(NativeApp.readPack(later)).rejects.toThrow("schema 2");
-    const refused = path.join(root, "refused");
-    const compat = { against: "store/bundle.json", compatible: false, problems: ["deepLinks differ"] };
-    await writeText(path.join(refused, "pack.json"), JSON.stringify({ ...pack, compat }));
-    expect((await NativeApp.readPack(refused)).compat).toEqual(compat);
-  });
-});

package/mobile/nativeApp.ts

@@ -1,7 +1,7 @@
-import { rm } from "node:fs/promises";
 import path from "node:path";
 import type { AkanNativeConfig } from "@akanjs/native/config";
 import type { NativeEnv } from "akanjs";
+import { toError } from "akanjs/common";
 import type { App } from "../commandDecorators";
 import { Executor } from "../executors";
 import { type DesktopArch, DesktopBin } from "./desktopBin";
@@ -17,13 +17,16 @@ import { NativeApi, type NativeBuildApiModule } from "./nativeApi";
 import { NativeAppLine, type NativeAppLineRead } from "./nativeAppLine";
 import { NativeConfig } from "./nativeConfig";
 import { NativePluginFolders } from "./nativePluginFolders";
+import { NativePublicEnv, type PublicEnv } from "./nativePublicEnv";
 import { NativeWebDir } from "./nativeWebDir";
 import { ServerBundleSecrets } from "./serverBundleSecrets";
+import { type NativeUpdatePack, UpdatePackFolder } from "./updatePackFolder";
 
 type TaskOptions = Parameters<NativeBuildApiModule["build"]>[0];
 type DeviceSelector = NonNullable<Parameters<NativeBuildApiModule["run"]>[0]["device"]>;
 type ReleaseOptions = Parameters<NativeBuildApiModule["release"]>[0];
 type AndroidSigning = Extract<ReleaseOptions, { platform: "android" }>["signing"];
+type PhoneRevocation = Pick<Parameters<NativeBuildApiModule["checkPublishUpdate"]>[0], "revoke" | "resetSequence">;
 
 export interface NativeRunOptions {
   device?: DeviceSelector;
@@ -56,25 +59,6 @@ export interface NativeDevOptions extends NativeRunOptions {
   lang: string;
 }
 
-/** `<out>/pack.json`: what a signer needs of a pack, read instead of the log. */
-export interface NativeUpdatePack {
-  schema: 1;
-  app: string;
-  target: string;
-  platform: MobilePlatform;
-  env: NativeEnv;
-  channel: string;
-  appId: string;
-  appVersion: string;
-  nativeApi: string;
-  /** bundle.json `web.hash`: the web files as served, the part of a bundle id that names its content. */
-  webHash: string;
-  files: number;
-  size: number;
-  out: string;
-  compat?: { against: string; compatible: boolean; problems: string[] };
-}
-
 /** One native target of an app on the native runtime (a phone, or this computer as a desktop app): where it builds,
  * what it ships, and the calls into the API. */
 export class NativeApp {
@@ -224,16 +208,23 @@ export class NativeApp {
     NativeApp.#assertServerPlatform(platform, server);
     NativeApp.assertInstaller(platform, installer);
     await this.assembleWeb(platform);
+    const publicEnv = await this.#publicEnv();
     const { api, config } = await this.prepare(platform, server, arch);
     const distribution = await this.#distribution(api, platform, profile, { sign, notarize }, server);
-    return await api.build({
-      ...this.#task(platform, config, { env: await this.#runtimeEnv(server) }),
-      profile,
-      ...(arch ? { arch } : {}),
-      ...(platform === "windows" ? { windows: { ...(installer ? { installer } : {}), ...distribution.windows } } : {}),
-      ...(platform === "macos" ? { macos: { ...distribution.macos, ...(installer ? { dmg: true } : {}) } } : {}),
-      ...(platform === "linux" && installer ? { linux: { appImage: true } } : {}),
-    });
+    return await this.#recorded(
+      this.outDir(platform),
+      publicEnv,
+      api.build({
+        ...this.#task(platform, config, { env: await this.#runtimeEnv(server) }),
+        profile,
+        ...(arch ? { arch } : {}),
+        ...(platform === "windows"
+          ? { windows: { ...(installer ? { installer } : {}), ...distribution.windows } }
+          : {}),
+        ...(platform === "macos" ? { macos: { ...distribution.macos, ...(installer ? { dmg: true } : {}) } } : {}),
+        ...(platform === "linux" && installer ? { linux: { appImage: true } } : {}),
+      }),
+    );
   }
 
   async run(
@@ -302,12 +293,17 @@ export class NativeApp {
 
   async releaseIos({ teamId, adHoc = false }: { teamId?: string; adHoc?: boolean } = {}) {
     await this.assembleWeb("ios");
+    const publicEnv = await this.#publicEnv();
     const { api, config } = await this.prepare("ios");
-    return await api.release({
-      ...this.#task("ios", config, { env: await this.#runtimeEnv() }),
-      platform: "ios",
-      signing: { ...(teamId ? { teamId } : {}), ...(adHoc ? { distribution: "ad-hoc" as const } : {}) },
-    });
+    return await this.#recorded(
+      this.outDir("ios"),
+      publicEnv,
+      api.release({
+        ...this.#task("ios", config, { env: await this.#runtimeEnv() }),
+        platform: "ios",
+        signing: { ...(teamId ? { teamId } : {}), ...(adHoc ? { distribution: "ad-hoc" as const } : {}) },
+      }),
+    );
   }
 
   /** Where publishUpdate writes: upload this folder as the target's updates.url. */
@@ -324,7 +320,15 @@ export class NativeApp {
       arch,
       sign = false,
       notarize = false,
-    }: { channel?: string; server?: DesktopServerBundle; arch?: DesktopArch; sign?: boolean; notarize?: boolean } = {},
+      revoke,
+      resetSequence,
+    }: {
+      channel?: string;
+      server?: DesktopServerBundle;
+      arch?: DesktopArch;
+      sign?: boolean;
+      notarize?: boolean;
+    } & PhoneRevocation = {},
   ) {
     NativeApp.#assertServerPlatform(platform, server);
     this.#assertUpdates();
@@ -340,11 +344,14 @@ export class NativeApp {
       ...(arch ? { arch } : {}),
       ...(distribution.macos ? { macos: distribution.macos } : {}),
       ...(distribution.windows ? { windows: distribution.windows } : {}),
+      ...(revoke?.length ? { revoke } : {}),
+      ...(resetSequence ? { resetSequence } : {}),
     });
   }
 
-  //* Only what the command asked for is signed or uploaded; a signed app's server is searched for the workspace's
-  //* secret values first, and the one line naming the identity and the service comes right before the build.
+  //* Only what the command asked for is signed or uploaded. A release's server is searched for the workspace's secret
+  //* values first, signed or not: an unsigned app is handed out too, and an update is published to every install. The
+  //* one line naming the identity and the service comes right before the build.
   async #distribution(
     api: NativeBuildApiModule,
     platform: NativePlatform,
@@ -353,29 +360,40 @@ export class NativeApp {
     server: DesktopServerBundle | undefined,
   ) {
     const distribution = api.requestedDistribution(platform, profile, request);
+    if (server && profile === "release") await this.#assertServerClean(server);
     if (!distribution.notice) {
       if (distribution.unused.length && (platform === "macos" || platform === "windows"))
         this.app.logger.info(`${distribution.unused.join(", ")} set: this build is not signed without --sign.`);
       return distribution;
     }
-    if (server) {
-      const unread = await new ServerBundleSecrets(this.app.workspace.workspaceRoot, this.app.cwdPath).assertClean(
-        server.dir,
-      );
-      if (unread.length)
-        this.app.logger.warn(`Not searched for secrets, as they could not be evaluated: ${unread.join(", ")}.`);
-    }
     this.app.logger.warn(distribution.notice);
     return distribution;
   }
 
+  async #assertServerClean(server: DesktopServerBundle) {
+    const unread = await new ServerBundleSecrets(this.app.workspace.workspaceRoot, this.app.cwdPath).assertClean(
+      server.dir,
+    );
+    if (unread.length)
+      throw new Error(
+        `The server this app carries was not searched for the secret values of ${unread.join(", ")}, which could not be evaluated with no app env set, so the release stops here.`,
+      );
+  }
+
   /**
    * What publishing refuses once the release is built: no updates settings, an invalid config, no signing key or
-   * another app's, and a desktop release whose server presence is not its channel's previous release's.
+   * another app's, a desktop release whose server presence is not its channel's previous release's, and a phone release
+   * whose revocations no phone would take.
    */
   async assertPublishable(
     platform: NativePlatform,
-    { channel, server = false, arch }: { channel?: string; server?: boolean; arch?: DesktopArch } = {},
+    {
+      channel,
+      server = false,
+      arch,
+      revoke,
+      resetSequence,
+    }: { channel?: string; server?: boolean; arch?: DesktopArch } & PhoneRevocation = {},
   ) {
     this.#assertUpdates();
     const [api, { config }] = await Promise.all([
@@ -392,14 +410,13 @@ export class NativeApp {
         server,
         ...(channel ? { channel } : {}),
         ...(arch ? { arch } : {}),
+        ...(revoke?.length ? { revoke } : {}),
+        ...(resetSequence ? { resetSequence } : {}),
       });
     } catch (error) {
-      throw new Error(
-        `Native target '${this.target.name}': ${error instanceof Error ? error.message : String(error)}`,
-        {
-          cause: error,
-        },
-      );
+      throw new Error(`Native target '${this.target.name}': ${toError(error).message}`, {
+        cause: error,
+      });
     }
   }
 
@@ -422,29 +439,38 @@ export class NativeApp {
   async releaseAndroid({ formats = ["aab"] }: { formats?: ("aab" | "apk")[] } = {}) {
     const signing = NativeApp.androidSigning();
     await this.assembleWeb("android");
+    const publicEnv = await this.#publicEnv();
     const { api, config } = await this.prepare("android");
-    return await api.release({
-      ...this.#task("android", config, { env: await this.#runtimeEnv() }),
-      platform: "android",
-      signing,
-      formats,
-    });
+    return await this.#recorded(
+      this.outDir("android"),
+      publicEnv,
+      api.release({
+        ...this.#task("android", config, { env: await this.#runtimeEnv() }),
+        platform: "android",
+        signing,
+        formats,
+      }),
+    );
   }
 
   /** An unsigned OTA update of this target's web bundle for `platform`, and the record `pack.json` keeps of it. */
   async packUpdate(platform: MobilePlatform, { out }: { out?: string } = {}) {
     await this.assembleWeb(platform);
+    const publicEnv = await this.#publicEnv();
     const { api, config } = await this.prepare(platform);
     if (!config.updates)
       throw new Error(
         `Native target '${this.target.name}' takes no updates: add native.updates: { url, publicKey } to akan.config.ts first.`,
       );
     const dir = path.resolve(out ?? path.join(this.updatesDir, platform));
-    //? A pack that fails must not leave the previous pack's record behind for whoever reads the exit code.
-    await Promise.all(["pack.json", "compat.json"].map((name) => rm(path.join(dir, name), { force: true })));
-    const packed = await api.packUpdate({ ...this.#task(platform, config), platform, out: dir });
+    await UpdatePackFolder.clear(dir);
+    const packed = await this.#recorded(
+      dir,
+      publicEnv,
+      api.packUpdate({ ...this.#task(platform, config), platform, out: dir }),
+    );
     const channel = config.updates.channel ?? "production";
-    const bundle = (await Bun.file(path.join(packed.out, "bundle.json")).json()) as { web: { hash: string } };
+    const bundle = await UpdatePackFolder.readBundle(path.join(packed.out, UpdatePackFolder.bundleFile));
     const pack: NativeUpdatePack = {
       schema: 1,
       app: this.app.name,
@@ -456,6 +482,7 @@ export class NativeApp {
       appVersion: packed.manifest.version,
       nativeApi: packed.manifest.nativeApi ?? "",
       webHash: bundle.web.hash,
+      ...(bundle.web.publicEnvHash ? { publicEnvHash: bundle.web.publicEnvHash } : {}),
       files: packed.manifest.files.length,
       size: packed.manifest.files.reduce((sum, file) => sum + file.size, 0),
       out: packed.out,
@@ -463,18 +490,27 @@ export class NativeApp {
     return { ...packed, channel, pack };
   }
 
-  static async writePack(pack: NativeUpdatePack) {
-    await Bun.write(path.join(pack.out, "pack.json"), `${JSON.stringify(pack, null, 2)}\n`);
-  }
-
-  /** A pack `packUpdate` wrote, read back from its folder wherever it was moved. */
-  static async readPack(dir: string): Promise<NativeUpdatePack> {
-    const file = Bun.file(path.join(dir, "pack.json"));
-    if (!(await file.exists()))
-      throw new Error(`${dir} holds no pack.json: give the folder \`akan pack-update\` wrote.`);
-    const pack = (await file.json()) as NativeUpdatePack;
-    if (pack.schema !== 1) throw new Error(`${dir}/pack.json is schema ${pack.schema}, and this akan reads schema 1.`);
-    return { ...pack, out: path.resolve(dir) };
+  //* Checked before anything is built or signed: a target with updates would ship a binary Akan Cloud cannot update.
+  async #publicEnv() {
+    const publicEnv = await NativePublicEnv.built(this.app);
+    if (!publicEnv) return null;
+    const problems = NativePublicEnv.problems(publicEnv);
+    if (!problems.length) return publicEnv;
+    const message = `The web build inlines public env an update cannot carry:\n- ${problems.join("\n- ")}`;
+    if (this.target.config.updates) throw new Error(message);
+    this.app.logger.warn(`${message}\nbundle.json records none, so no update can be checked against this build.`);
+    return null;
+  }
+
+  //? After the build: the native CLI writes bundle.json, and a phone build with updates rewrites it once more.
+  async #recorded<T>(dir: string, publicEnv: PublicEnv | null, build: Promise<T>) {
+    const result = await build;
+    const file = path.join(dir, UpdatePackFolder.bundleFile);
+    if (!publicEnv || !(await Bun.file(file).exists())) return result;
+    const bundle = await UpdatePackFolder.readBundle(file);
+    const web = { ...bundle.web, publicEnv, publicEnvHash: NativePublicEnv.hash(publicEnv) };
+    await Bun.write(file, `${JSON.stringify({ ...bundle, web }, null, 2)}\n`);
+    return result;
   }
 
   static async compareBundles(appDir: string, shipped: string, bundle: string) {

package/mobile/nativeConfig.ts

@@ -261,7 +261,8 @@ export class NativeConfig {
     };
   }
 
-  //? akanConfig refuses a target whose merged updates lack url or a key; the type still has them optional.
+  //? akanConfig refuses a target whose merged updates lack url or a key, or hold both key forms; the type still has
+  //? them optional.
   static #updates(target: AkanNativeTarget, env?: NativeEnv): NonNullable<AkanNativeConfig["updates"]> | undefined {
     const { url, publicKey, publicKeys, channel = env, ...rest } = target.updates ?? {};
     const keys = publicKeys ? { publicKeys: [...publicKeys] } : publicKey ? { publicKey } : null;

package/mobile/nativePublicEnv.test.ts

@@ -0,0 +1,131 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { WorkspaceExecutor } from "../executors";
+import { tempDirs, writeText } from "../testHelpers";
+import { NativePublicEnv } from "./nativePublicEnv";
+
+const makeTempRoot = tempDirs("akan-native-public-env-");
+
+const recorded = {
+  AKAN_PUBLIC_ENV: "main",
+  AKAN_PUBLIC_REPO_NAME: "softs2",
+  AKAN_PUBLIC_SERVE_DOMAIN: "akamir.com",
+};
+
+describe("NativePublicEnv", () => {
+  test("keeps the AKAN_PUBLIC_* the app sets, sorted, and leaves out what akan.config.ts derives", () => {
+    expect(
+      Object.keys(
+        NativePublicEnv.of({
+          AKAN_PUBLIC_SERVE_DOMAIN: "akamir.com",
+          AKAN_PUBLIC_APP_NAME: "lu",
+          AKAN_PUBLIC_BASE_PATHS: "",
+          AKAN_PUBLIC_RENDER_ENV: "csr",
+          AKAN_PUBLIC_ENV: "main",
+          JWT_SECRET: "never",
+        }),
+      ),
+    ).toEqual(["AKAN_PUBLIC_ENV", "AKAN_PUBLIC_SERVE_DOMAIN"]);
+  });
+
+  test("hashes the sorted map as JSON, whatever order it was written in", () => {
+    const reversed = Object.fromEntries(Object.entries(recorded).reverse());
+    const expected = createHash("sha256").update(JSON.stringify(recorded)).digest("hex");
+    expect(NativePublicEnv.hash(reversed)).toBe(expected);
+  });
+
+  test("refuses what Akan Cloud refuses in a recorded env", () => {
+    expect(NativePublicEnv.problems(recorded)).toEqual([]);
+    expect(
+      NativePublicEnv.problems({
+        AKAN_PUBLIC_lower: "x",
+        AKAN_PUBLIC_MAP_TOKEN: "x",
+        AKAN_PUBLIC_PORT: 8282,
+        AKAN_PUBLIC_NOTE: "line\nbreak",
+      }),
+    ).toEqual([
+      "AKAN_PUBLIC_lower is not an AKAN_PUBLIC_[A-Z0-9_] name",
+      "AKAN_PUBLIC_MAP_TOKEN names a token, which a page bundle must not carry",
+      "AKAN_PUBLIC_PORT is not a string",
+      "AKAN_PUBLIC_NOTE holds a control character",
+    ]);
+    const many = Object.fromEntries(Array.from({ length: 257 }, (_, idx) => [`AKAN_PUBLIC_K${idx}`, "v"]));
+    expect(NativePublicEnv.problems(many)).toEqual(["257 keys, more than 256"]);
+    expect(NativePublicEnv.problems({ AKAN_PUBLIC_BIG: "x".repeat(70_000) })[0]).toContain("bytes, more than 65536");
+  });
+
+  test("names the keys two maps disagree on, either side missing included", () => {
+    expect(
+      NativePublicEnv.diff(recorded, { ...recorded, AKAN_PUBLIC_SERVE_DOMAIN: "try.akanjs.com", AKAN_PUBLIC_X: "1" }),
+    ).toEqual(["AKAN_PUBLIC_SERVE_DOMAIN", "AKAN_PUBLIC_X"]);
+  });
+
+  test("loads --public-env from a JSON map or from a store build's bundle.json, and refuses the rest", async () => {
+    const root = await makeTempRoot();
+    const map = path.join(root, "store.env.json");
+    await writeText(map, JSON.stringify(recorded));
+    expect(await NativePublicEnv.load(map)).toEqual(recorded);
+
+    const bundle = path.join(root, "bundle.json");
+    await writeText(bundle, JSON.stringify({ schema: 1, web: { hash: "h", files: 1, publicEnv: recorded } }));
+    expect(await NativePublicEnv.load(bundle)).toEqual(recorded);
+    expect(await NativePublicEnv.recordedIn(bundle)).toEqual(recorded);
+
+    const older = path.join(root, "older.json");
+    await writeText(older, JSON.stringify({ schema: 1, web: { hash: "h", files: 1 } }));
+    await expect(NativePublicEnv.load(older)).rejects.toThrow("recorded no public env");
+    expect(await NativePublicEnv.recordedIn(older)).toBeNull();
+    expect(await NativePublicEnv.recordedIn(path.join(root, "missing.json"))).toBeNull();
+
+    const derived = path.join(root, "derived.json");
+    await writeText(derived, JSON.stringify({ ...recorded, AKAN_PUBLIC_APP_NAME: "lu" }));
+    await expect(NativePublicEnv.load(derived)).rejects.toThrow("AKAN_PUBLIC_APP_NAME, which akan.config.ts decides");
+
+    const secret = path.join(root, "secret.json");
+    await writeText(secret, JSON.stringify({ AKAN_PUBLIC_API_PASSWORD: "x" }));
+    await expect(NativePublicEnv.load(secret)).rejects.toThrow("names a password");
+    await expect(NativePublicEnv.load(path.join(root, "nope.json"))).rejects.toThrow("does not exist");
+  });
+
+  test("says which keys keep a pack out of a store build that recorded its env, and nothing when it recorded none", async () => {
+    const root = await makeTempRoot();
+    const shipped = path.join(root, "store.json");
+    const pack = path.join(root, "pack.json");
+    await writeText(shipped, JSON.stringify({ schema: 1, web: { publicEnv: recorded } }));
+    await writeText(
+      pack,
+      JSON.stringify({ schema: 1, web: { publicEnv: { ...recorded, AKAN_PUBLIC_SERVE_DOMAIN: "try.akanjs.com" } } }),
+    );
+    expect(await NativePublicEnv.problemAgainst(shipped, pack)).toBe(
+      `public env AKAN_PUBLIC_SERVE_DOMAIN differs from the store build's (pass --public-env ${shipped} to repeat it)`,
+    );
+    expect(await NativePublicEnv.problemAgainst(shipped, shipped)).toBeNull();
+    expect(await NativePublicEnv.problemAgainst(pack.replace("pack", "none"), pack)).toBeNull();
+  });
+
+  describe("pin", () => {
+    const saved = { ...process.env };
+    afterEach(() => {
+      for (const key of Object.keys(process.env)) if (!(key in saved)) delete process.env[key];
+      Object.assign(process.env, saved);
+      WorkspaceExecutor.publicEnvPin = null;
+    });
+
+    test("leaves exactly the pinned values and the derived ones, and outranks the root .env", async () => {
+      const root = await makeTempRoot();
+      const envFile = path.join(root, ".env");
+      await writeText(
+        envFile,
+        "AKAN_PUBLIC_REPO_NAME=from-dotenv\nAKAN_PUBLIC_SERVE_DOMAIN=try.akanjs.com\nAKAN_PUBLIC_LOG_LEVEL=debug\n",
+      );
+      Object.assign(process.env, { AKAN_PUBLIC_LOG_LEVEL: "debug", AKAN_PUBLIC_APP_NAME: "lu" });
+      NativePublicEnv.pin(recorded);
+      expect(NativePublicEnv.of(process.env)).toEqual(recorded);
+      expect(process.env.AKAN_PUBLIC_APP_NAME).toBe("lu");
+      const base = WorkspaceExecutor.getBaseDevEnv(envFile);
+      expect(base.repoName).toBe("softs2");
+      expect(base.serveDomain).toBe("akamir.com");
+    });
+  });
+});