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

package/mobile/nativePublicEnv.ts

@@ -0,0 +1,116 @@
+import { createHash } from "node:crypto";
+import type { App } from "../commandDecorators";
+import { WorkspaceExecutor } from "../executors";
+import { CsrArtifactBuilder } from "../frontendBuild/csrArtifactBuilder";
+
+export type PublicEnv = Record<string, string>;
+
+//* The `AKAN_PUBLIC_*` a native web build inlines: an update has to repeat them, because the API host and the env an
+//* installed binary talks to live there and nowhere else. Keys akan.config.ts derives are left out, as Akan Cloud does.
+export class NativePublicEnv {
+  static readonly derivedKeys = [
+    "AKAN_PUBLIC_APP_NAME",
+    "AKAN_PUBLIC_BASE_PATHS",
+    "AKAN_PUBLIC_API_PREFIX",
+    "AKAN_PUBLIC_WS_PREFIX",
+    "AKAN_PUBLIC_RENDER_ENV",
+    "AKAN_PUBLIC_DEFAULT_LOCALE",
+    "AKAN_PUBLIC_LOCALES",
+  ];
+  //? Akan Cloud's own limits on a recorded env: a build it would refuse fails here, before anything is signed.
+  static readonly #keyPattern = /^AKAN_PUBLIC_[A-Z0-9_]{1,128}$/;
+  static readonly #secretWords = ["SECRET", "TOKEN", "PASSWORD", "PRIVATE", "CREDENTIAL"];
+  static readonly #maxKeys = 256;
+  static readonly #maxBytes = 64 * 1024;
+
+  static of(env: Record<string, unknown>): PublicEnv {
+    return Object.fromEntries(
+      Object.keys(env)
+        .filter((key) => key.startsWith("AKAN_PUBLIC_") && !NativePublicEnv.derivedKeys.includes(key))
+        .sort()
+        .map((key) => [key, String(env[key])]),
+    );
+  }
+
+  static hash(publicEnv: PublicEnv) {
+    return createHash("sha256")
+      .update(JSON.stringify(NativePublicEnv.of(publicEnv)))
+      .digest("hex");
+  }
+
+  static problems(publicEnv: Record<string, unknown>) {
+    const keys = Object.keys(publicEnv);
+    const problems = keys.flatMap((key) => {
+      const value = publicEnv[key];
+      if (!NativePublicEnv.#keyPattern.test(key)) return [`${key} is not an AKAN_PUBLIC_[A-Z0-9_] name`];
+      const word = NativePublicEnv.#secretWords.find((secret) => key.includes(secret));
+      if (word) return [`${key} names a ${word.toLowerCase()}, which a page bundle must not carry`];
+      if (typeof value !== "string") return [`${key} is not a string`];
+      // biome-ignore lint/suspicious/noControlCharactersInRegex: the control characters are what is refused
+      if (/[\u0000-\u001f\u007f]/.test(value)) return [`${key} holds a control character`];
+      return [];
+    });
+    if (keys.length > NativePublicEnv.#maxKeys)
+      problems.push(`${keys.length} keys, more than ${NativePublicEnv.#maxKeys}`);
+    const bytes = Buffer.byteLength(JSON.stringify(publicEnv));
+    if (bytes > NativePublicEnv.#maxBytes) problems.push(`${bytes} bytes, more than ${NativePublicEnv.#maxBytes}`);
+    return problems;
+  }
+
+  /** The keys whose values differ, or that only one side has. */
+  static diff(a: PublicEnv, b: PublicEnv) {
+    return [...new Set([...Object.keys(a), ...Object.keys(b)])]
+      .filter((key) => a[key] !== b[key])
+      .sort((x, y) => (x < y ? -1 : x > y ? 1 : 0));
+  }
+
+  /** What the app's last `akan build` inlined, or null when it built no CSR bundle. */
+  static async built(app: App): Promise<PublicEnv | null> {
+    const file = Bun.file(CsrArtifactBuilder.publicEnvPath(app));
+    if (!(await file.exists())) return null;
+    return NativePublicEnv.of((await file.json()) as Record<string, unknown>);
+  }
+
+  /** A bundle.json's record, or null when it has none (a build from before the record, or no file at all). */
+  static async recordedIn(bundleFile: string): Promise<PublicEnv | null> {
+    const file = Bun.file(bundleFile);
+    if (!(await file.exists())) return null;
+    const bundle = (await file.json()) as { web?: { publicEnv?: PublicEnv } };
+    return bundle.web?.publicEnv ?? null;
+  }
+
+  /** `--public-env`: a JSON map of the values, or the bundle.json of the store build that recorded them. */
+  static async load(file: string): Promise<PublicEnv> {
+    const source = Bun.file(file);
+    if (!(await source.exists())) throw new Error(`--public-env ${file} does not exist.`);
+    const json = (await source.json().catch(() => null)) as Record<string, unknown> | null;
+    if (!json || typeof json !== "object" || Array.isArray(json))
+      throw new Error(`--public-env ${file} is not a JSON object of AKAN_PUBLIC_* values or a bundle.json.`);
+    const isBundle = json.schema === 1 && typeof json.web === "object";
+    const map = isBundle ? (json.web as { publicEnv?: Record<string, unknown> }).publicEnv : json;
+    if (!map) throw new Error(`--public-env ${file} is a bundle.json from a build that recorded no public env.`);
+    const derived = Object.keys(map).filter((key) => NativePublicEnv.derivedKeys.includes(key));
+    if (derived.length)
+      throw new Error(`--public-env ${file} sets ${derived.join(", ")}, which akan.config.ts decides.`);
+    const problems = NativePublicEnv.problems(map);
+    if (problems.length) throw new Error(`--public-env ${file} is refused:\n- ${problems.join("\n- ")}`);
+    return NativePublicEnv.of(map);
+  }
+
+  //* Exactly these values and the ones akan.config.ts derives: the shell's and `.env`'s other AKAN_PUBLIC_* are dropped.
+  static pin(publicEnv: PublicEnv) {
+    for (const key of Object.keys(process.env))
+      if (key.startsWith("AKAN_PUBLIC_") && !NativePublicEnv.derivedKeys.includes(key)) delete process.env[key];
+    Object.assign(process.env, publicEnv);
+    WorkspaceExecutor.publicEnvPin = publicEnv;
+  }
+
+  /** Why a pack's bundle cannot ship to the store build `shipped`, as far as the public env goes. */
+  static async problemAgainst(shipped: string, bundle: string) {
+    const [before, now] = await Promise.all([NativePublicEnv.recordedIn(shipped), NativePublicEnv.recordedIn(bundle)]);
+    if (!before) return null;
+    const differs = NativePublicEnv.diff(before, now ?? {});
+    if (!differs.length) return null;
+    return `public env ${differs.join(", ")} differs from the store build's (pass --public-env ${shipped} to repeat it)`;
+  }
+}

package/mobile/serverBundleSecrets.test.ts

@@ -47,6 +47,85 @@ describe("ServerBundleSecrets", () => {
     for (const secret of ["main-mail-pass", "0f9e8d7c", "MIIEvQ"]) expect(message).not.toContain(secret);
   });
 
+  test("passes a server whose vendor and lib code hold a token endpoint and a default password the env files hold too", async () => {
+    const { root, appDir, bundle } = await workspace();
+    await write(
+      path.join(root, "libs/shared/env/env.server.testing.ts"),
+      'export const env = { rootAdminInfo: { accountId: "admin@example.com", password: "admin1234" }, iapVerify: { google: { token_uri: "https://oauth2.googleapis.com/token" } } };\n',
+    );
+    await write(
+      path.join(root, "libs/shared/lib/option.ts"),
+      'export const rootAdmin = { accountId: "admin@mydomain.com", password: "admin1234" };\n',
+    );
+    await write(
+      path.join(root, "libs/shared/env/env.server.example.ts"),
+      'export const env = { pass: "main-mail-pass" };\n',
+    );
+    await write(path.join(bundle, "chunk-vendor.js"), 'const tokenUrl = "https://oauth2.googleapis.com/token";\n');
+    await write(path.join(bundle, "chunk-shared.js"), 'const fallback = { password: "admin1234" };\n');
+    expect(await new ServerBundleSecrets(root, appDir).assertClean(bundle)).toEqual([]);
+
+    await write(path.join(bundle, "chunk-mail.js"), 'const pass = "main-mail-pass";\n');
+    await expect(new ServerBundleSecrets(root, appDir).assertClean(bundle)).rejects.toThrow(
+      "chunk-mail.js holds apps/demo/env/env.server.main.ts mailer.auth.pass",
+    );
+  });
+
+  test("still refuses a long secret the code holds as well, a webhook and a URL's password", async () => {
+    const { root, appDir, bundle } = await workspace();
+    const hook = "https://hooks.slack.com/services/T0/B0/AbCdEf0123456789XyZ";
+    await write(
+      path.join(appDir, "env/env.server.develop.ts"),
+      `export const env = { slack: { webhookUrl: "${hook}" }, database: { postgres: { url: "postgres://app:pg-pass-0123@db/app" } } };\n`,
+    );
+    await write(
+      path.join(root, "libs/util/srvkit/fallback.ts"),
+      `export const jwt = "lib-jwt-0123456789";\nexport const hook = "${hook}";\n`,
+    );
+    await write(
+      path.join(bundle, "server.js"),
+      `const jwt = "lib-jwt-0123456789"; const hook = "${hook}"; const pg = "postgres://app:" + (process.env.PG ?? "pg-pass-0123") + "@db/app";\n`,
+    );
+    const message = await new ServerBundleSecrets(root, appDir)
+      .assertClean(bundle)
+      .then(() => "")
+      .catch((error: Error) => error.message);
+    expect(message).toContain("server.js holds libs/util/env/env.server.testing.ts security.jwtSecret");
+    expect(message).toContain("server.js holds apps/demo/env/env.server.develop.ts slack.webhookUrl");
+    expect(message).toContain("server.js holds apps/demo/env/env.server.develop.ts database.postgres.url");
+    expect(message).toContain(
+      "A value a profile build still holds sits in code or a file the server carries: take it out there.",
+    );
+    for (const secret of ["lib-jwt-0123456789", "hooks.slack.com", "pg-pass-0123"])
+      expect(message).not.toContain(secret);
+  });
+
+  test("finds a secret with non-ASCII characters in the bundle Bun printed, and in a file copied as UTF-8", async () => {
+    const { root, appDir, bundle } = await workspace();
+    const secrets = { pass: "pässwörd-ünïcode-1234", apiKey: `비밀 "it's" ${"😀"}-5678` };
+    await write(
+      path.join(appDir, "env/env.server.debug.ts"),
+      `export const env = { mailer: ${JSON.stringify(secrets)} };\n`,
+    );
+    const source = path.join(root, "carried.ts");
+    await write(source, `export const mailer = ${JSON.stringify(secrets)};\n`);
+    const built = await Bun.build({ entrypoints: [source], outdir: bundle, target: "bun", minify: true });
+    expect(built.success).toBe(true);
+    expect(await Bun.file(path.join(bundle, "carried.js")).text()).not.toContain("ä");
+    const message = await new ServerBundleSecrets(root, appDir)
+      .assertClean(bundle)
+      .then(() => "")
+      .catch((error: Error) => error.message);
+    expect(message).toContain("carried.js holds apps/demo/env/env.server.debug.ts mailer.pass");
+    expect(message).toContain("carried.js holds apps/demo/env/env.server.debug.ts mailer.apiKey");
+
+    await Bun.write(path.join(bundle, "carried.js"), "\n");
+    await Bun.write(path.join(bundle, "settings.json"), JSON.stringify({ pass: secrets.pass }));
+    await expect(new ServerBundleSecrets(root, appDir).assertClean(bundle)).rejects.toThrow(
+      "settings.json holds apps/demo/env/env.server.debug.ts mailer.pass",
+    );
+  });
+
   test("names an env file it could not evaluate instead of passing it silently", async () => {
     const { root, appDir, bundle } = await workspace();
     await write(

package/mobile/serverBundleSecrets.ts

@@ -8,21 +8,20 @@ interface SecretValue {
   value: string;
 }
 
-//* A signed app leaves the building, and a notarized one goes to Apple first: before either, every secret value the
-//* workspace's server env files hold is looked for in the server the app carries, whatever put it there.
+//* A release leaves the building, signed or not, and an update goes to a feed anyone reads: before either, every secret
+//* value the workspace's server env files hold is looked for in the server the app carries, whatever put it there.
 export class ServerBundleSecrets {
   static readonly #largestFile = 64 * 1024 * 1024;
+  static readonly #printer = new Bun.Transpiler({ loader: "js", target: "bun" });
+  static readonly #notSource = new Set(["node_modules", "env", "private", "public", "dist"]);
 
   constructor(
     readonly workspaceRoot: string,
     readonly appDir: string,
   ) {}
 
-  /** The app's `env/env.server.<name>.ts` and every lib's, but the type and example files. */
   async envFiles(): Promise<string[]> {
-    const libsDir = path.join(this.workspaceRoot, "libs");
-    const libs = await readdir(libsDir).catch(() => [] as string[]);
-    const dirs = [path.join(this.appDir, "env"), ...libs.map((lib) => path.join(libsDir, lib, "env"))];
+    const dirs = [path.join(this.appDir, "env"), ...(await this.#libDirs()).map((lib) => path.join(lib, "env"))];
     const files = await Promise.all(
       dirs.map(async (dir) =>
         (await readdir(dir).catch(() => [] as string[]))
@@ -45,27 +44,59 @@ export class ServerBundleSecrets {
         unread.push(ServerBundleSecrets.#relative(this.workspaceRoot, file));
       }
     }
-    const found: string[] = [];
+    if (!secrets.length) return unread;
+    const sought = secrets.map((secret) => ({ secret, needles: ServerBundleSecrets.#needles(secret.value) }));
+    const found: { bundled: string; secret: SecretValue }[] = [];
     for (const bundled of await ServerBundleSecrets.#files(bundleDir)) {
       const text = await readFile(bundled, "latin1");
-      for (const secret of secrets)
-        if (ServerBundleSecrets.#needles(secret.value).some((needle) => text.includes(needle)))
-          found.push(
-            `${ServerBundleSecrets.#relative(bundleDir, bundled)} holds ${ServerBundleSecrets.#relative(this.workspaceRoot, secret.file)} ${secret.path}`,
-          );
+      for (const { secret, needles } of sought)
+        if (needles.some((needle) => text.includes(needle))) found.push({ bundled, secret });
     }
-    if (found.length)
+    const coded = found.length ? await this.#coded(found.map(({ secret }) => secret.value)) : new Set<string>();
+    const leaks = found
+      .filter(({ secret }) => !coded.has(secret.value))
+      .map(
+        ({ bundled, secret }) =>
+          `${ServerBundleSecrets.#relative(bundleDir, bundled)} holds ${ServerBundleSecrets.#relative(this.workspaceRoot, secret.file)} ${secret.path}`,
+      );
+    if (leaks.length)
       throw new Error(
-        `The server this app carries holds secret values from the workspace's env files, so it is not signed or sent anywhere:\n  ${[...new Set(found)].join("\n  ")}\nBuild its server with a profile (native.desktop.server.profile), whose bundle carries no secret.`,
+        `The server this app carries holds secret values of the workspace's env files, so the release stops here:\n  ${[...new Set(leaks)].join("\n  ")}\nBuild its server with a profile (native.desktop.server.profile), whose bundle leaves the env files' secrets out. A value a profile build still holds sits in code or a file the server carries: take it out there.`,
       );
     return unread;
   }
 
-  //? A multi-line key sits in a bundle as a JS string, escaped; one long line of it is enough to recognise.
+  //? A short or plain value the app's or a lib's own code holds as well (a default password) is that code's, which
+  //? the bundle carries with or without the env file; a long mixed one is a secret copied into the code.
+  async #coded(values: string[]): Promise<Set<string>> {
+    const plain = [...new Set(values)].filter((value) => !ServerEnvProfile.distinctive(value));
+    const coded = new Set<string>();
+    if (!plain.length) return coded;
+    for (const dir of [this.appDir, ...(await this.#libDirs())])
+      for (const file of await ServerBundleSecrets.#sources(dir)) {
+        const text = await readFile(file, "utf8");
+        for (const value of plain) if (text.includes(value)) coded.add(value);
+      }
+    return coded;
+  }
+
+  async #libDirs() {
+    const libsDir = path.join(this.workspaceRoot, "libs");
+    return (await readdir(libsDir).catch(() => [] as string[])).map((lib) => path.join(libsDir, lib));
+  }
+
+  //? A multi-line key sits in a bundle as a JS string, escaped; one long line of it is enough to recognise. Bun prints
+  //? a string's non-ASCII characters as `\xNN` / `\uNNNN`, and the bundle is read byte for byte, so as UTF-8.
   static #needles(value: string): string[] {
     const escaped = JSON.stringify(value).slice(1, -1);
     const line = value.split(/\r?\n/).find((part) => part.length >= 32);
-    return [...new Set([value, escaped, ...(line ? [line] : [])])];
+    const forms = [value, escaped, ServerBundleSecrets.#printed(value), ...(line ? [line] : [])];
+    return [...new Set(forms.map((form) => Buffer.from(form, "utf8").toString("latin1")))];
+  }
+
+  static #printed(value: string) {
+    const code = ServerBundleSecrets.#printer.transformSync(`export default ${JSON.stringify(value)};`);
+    return /^export default (["'`])([\s\S]*)\1;?\s*$/.exec(code)?.[2] ?? value;
   }
 
   static #relative(from: string, to: string) {
@@ -82,4 +113,17 @@ export class ServerBundleSecrets {
     }
     return files;
   }
+
+  static async #sources(dir: string): Promise<string[]> {
+    const files: string[] = [];
+    for (const entry of await readdir(dir, { withFileTypes: true }).catch(() => [])) {
+      if (entry.name.startsWith(".")) continue;
+      const file = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (!ServerBundleSecrets.#notSource.has(entry.name)) files.push(...(await ServerBundleSecrets.#sources(file)));
+      } else if (/\.(?:[cm]?[jt]sx?|json)$/.test(entry.name) && !/\.(?:test|spec)\.[cm]?[jt]sx?$/.test(entry.name))
+        files.push(file);
+    }
+    return files;
+  }
 }

package/mobile/updatePackFolder.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import { tempDirs, writeText } from "../testHelpers";
+import { UpdatePackFolder } from "./updatePackFolder";
+
+const makeTempRoot = tempDirs("akan-update-pack-");
+
+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 UpdatePackFolder.read(moved)).toEqual({ ...pack, out: moved } as never);
+
+    await expect(UpdatePackFolder.read(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(UpdatePackFolder.read(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 UpdatePackFolder.read(refused)).compat).toEqual(compat);
+  });
+
+  test("is written without the folder it was packed to, which holds this machine's paths", async () => {
+    const out = path.join(await makeTempRoot(), "updates", "android");
+    const pack = { schema: 1, app: "lu", target: "default", platform: "android", files: 1, out } as const;
+
+    await UpdatePackFolder.write(pack as never);
+
+    const written = await Bun.file(path.join(out, "pack.json")).text();
+    expect(written).not.toContain(out);
+    expect(JSON.parse(written)).toEqual({ schema: 1, app: "lu", target: "default", platform: "android", files: 1 });
+    expect((await UpdatePackFolder.read(out)).out).toBe(out);
+  });
+});
+
+describe("a pack's verdict on the store build it was compared with", () => {
+  test("is none without a comparison or for one it runs in, and exit 2 with what differs otherwise", () => {
+    const out = "/work/updates/android";
+    expect(UpdatePackFolder.storeBuildVerdict({ out })).toBeNull();
+    const against = "store/bundle.json";
+    expect(UpdatePackFolder.storeBuildVerdict({ out, compat: { against, compatible: true, problems: [] } })).toBeNull();
+
+    const verdict = UpdatePackFolder.storeBuildVerdict(
+      { out, compat: { against, compatible: false, problems: ["deepLinks differ", "camera added"] } },
+      "Run `akan release-android lu`, then register that build.",
+    );
+    expect(verdict?.exitCode).toBe(2);
+    expect(verdict?.message).toBe(
+      `The pack in ${out} needs a new store build; it differs from the one ${against} came from:\n- deepLinks differ\n- camera added\nRun \`akan release-android lu\`, then register that build.`,
+    );
+  });
+});
+
+describe("a pack's archive", () => {
+  test("holds the files its template lists and the records there, never another pack's files", async () => {
+    const out = path.join(await makeTempRoot(), "updates", "android");
+    const listed = "a".repeat(64);
+    await writeText(path.join(out, "manifest.template.json"), JSON.stringify({ files: [{ sha256: listed }] }));
+    await writeText(path.join(out, "bundle.json"), "{}");
+    await writeText(path.join(out, "pack.json"), "{}");
+    await writeText(path.join(out, "files", listed), "listed");
+    await writeText(path.join(out, "files", "b".repeat(64)), "an earlier pack's");
+
+    const entries = await UpdatePackFolder.withArchive({ out } as never, async (archive) =>
+      Bun.spawnSync(["tar", "-tzf", archive]).stdout.toString().split(/\r?\n/).filter(Boolean).sort(),
+    );
+
+    expect(entries).toEqual(["./bundle.json", `./files/${listed}`, "./manifest.template.json", "./pack.json"]);
+  });
+
+  test("refuses a template that names a file by anything but its sha256", async () => {
+    const out = path.join(await makeTempRoot(), "pack");
+    await writeText(path.join(out, "manifest.template.json"), JSON.stringify({ files: [{ sha256: "../pack.json" }] }));
+    await expect(UpdatePackFolder.withArchive({ out } as never, async () => null)).rejects.toThrow(
+      "lists a file whose sha256 is not 64 hex digits",
+    );
+    await expect(
+      UpdatePackFolder.withArchive({ out: path.join(out, "none") } as never, async () => null),
+    ).rejects.toThrow("holds no manifest.template.json");
+  });
+});

package/mobile/updatePackFolder.ts

@@ -0,0 +1,131 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import type { BundleInfo, UpdateManifest } from "@akanjs/native/api";
+import type { NativeEnv } from "akanjs";
+import { ExitCodeError } from "../commandDecorators/exitCodeError";
+import type { MobilePlatform } from "./mobileTarget";
+
+export interface NativeUpdatePackCompat {
+  /** The store build's bundle.json the pack was compared with. */
+  against: string;
+  compatible: boolean;
+  problems: 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;
+  /** bundle.json `web.publicEnvHash`: the AKAN_PUBLIC_* the page inlined, which the store build must share. */
+  publicEnvHash?: string;
+  files: number;
+  size: number;
+  /** The folder it was read from or packed to; pack.json leaves it out. */
+  out: string;
+  compat?: NativeUpdatePackCompat;
+}
+
+//* The folder `akan pack-update` writes for a signer or Akan Cloud: the native build API writes `files/<sha256>`,
+//* bundle.json and manifest.template.json, and akan writes pack.json and compat.json beside them.
+export class UpdatePackFolder {
+  static readonly packFile = "pack.json";
+  static readonly compatFile = "compat.json";
+  static readonly bundleFile = "bundle.json";
+  static readonly templateFile = "manifest.template.json";
+  static readonly filesDir = "files";
+  static readonly #records = [
+    UpdatePackFolder.templateFile,
+    UpdatePackFolder.bundleFile,
+    UpdatePackFolder.packFile,
+    UpdatePackFolder.compatFile,
+  ];
+  static readonly #sha256 = /^[0-9a-f]{64}$/;
+
+  /** akan's own records: a pack that fails must not leave the previous pack's behind for whoever reads the exit code. */
+  static async clear(dir: string) {
+    await Promise.all(
+      [UpdatePackFolder.packFile, UpdatePackFolder.compatFile].map((name) => rm(path.join(dir, name), { force: true })),
+    );
+  }
+
+  /** A pack read back from its folder wherever it was moved. */
+  static async read(dir: string): Promise<NativeUpdatePack> {
+    const file = Bun.file(path.join(dir, UpdatePackFolder.packFile));
+    if (!(await file.exists()))
+      throw new Error(`${dir} holds no ${UpdatePackFolder.packFile}: give the folder \`akan pack-update\` wrote.`);
+    const pack = (await file.json()) as NativeUpdatePack;
+    if (pack.schema !== 1)
+      throw new Error(`${dir}/${UpdatePackFolder.packFile} is schema ${pack.schema}, and this akan reads schema 1.`);
+    return { ...pack, out: path.resolve(dir) };
+  }
+
+  //? Without `out`: the record travels in the pack's archive, and the folder is wherever it is read from.
+  static async write({ out, ...record }: NativeUpdatePack) {
+    await Bun.write(path.join(out, UpdatePackFolder.packFile), `${JSON.stringify(record, null, 2)}\n`);
+  }
+
+  static async writeCompat(pack: NativeUpdatePack, compat: NativeUpdatePackCompat) {
+    pack.compat = compat;
+    await Bun.write(path.join(pack.out, UpdatePackFolder.compatFile), `${JSON.stringify(compat, null, 2)}\n`);
+  }
+
+  /** The bundle.json a store build and a pack both carry. */
+  static async readBundle(file: string): Promise<BundleInfo> {
+    return (await Bun.file(file).json()) as BundleInfo;
+  }
+
+  //* Exit 2, not a thrown 1: a CI tells "this needs a new store build" apart from a pack that broke.
+  static storeBuildVerdict({ out, compat }: Pick<NativeUpdatePack, "out" | "compat">, then?: string) {
+    if (!compat || compat.compatible) return null;
+    return new ExitCodeError(
+      `The pack in ${out} needs a new store build; it differs from the one ${compat.against} came from:\n- ${compat.problems.join("\n- ")}${then ? `\n${then}` : ""}`,
+      2,
+    );
+  }
+
+  /** The pack as the tgz Akan Cloud takes: the files its manifest template lists, and the records beside them. */
+  static async withArchive<T>(pack: NativeUpdatePack, use: (archive: string) => Promise<T>): Promise<T> {
+    const { templateFile, filesDir } = UpdatePackFolder;
+    const template = Bun.file(path.join(pack.out, templateFile));
+    if (!(await template.exists()))
+      throw new Error(`${pack.out} holds no ${templateFile}: give the folder \`akan pack-update\` wrote.`);
+    const { files = [] } = (await template.json()) as Partial<UpdateManifest>;
+    const hashes = [...new Set(files.map((file) => file.sha256 as unknown))];
+    if (!hashes.every((hash): hash is string => typeof hash === "string" && UpdatePackFolder.#sha256.test(hash)))
+      throw new Error(`${pack.out}/${templateFile} lists a file whose sha256 is not 64 hex digits.`);
+    const present = await Promise.all(
+      UpdatePackFolder.#records.map((name) => Bun.file(path.join(pack.out, name)).exists()),
+    );
+    const entries = [
+      ...UpdatePackFolder.#records.filter((_, idx) => present[idx]),
+      ...hashes.map((hash) => `${filesDir}/${hash}`),
+    ];
+    const dir = await mkdtemp(path.join(os.tmpdir(), "akan-pack-"));
+    try {
+      //? files/ keeps every earlier pack's files (content-addressed), so the folder itself is not the pack; the names
+      //? go on stdin, not argv, because a Windows command line holds 32 KiB.
+      // A relative archive name, so GNU tar never reads a Windows drive letter (`C:\…`) as a remote `host:file` spec.
+      const tar = Bun.spawn(["tar", "-czf", "pack.tgz", "-C", pack.out, "-T", "-"], {
+        cwd: dir,
+        stdin: new Blob([entries.map((entry) => `./${entry}\n`).join("")]),
+        stdout: "ignore",
+        stderr: "pipe",
+      });
+      const [code, stderr] = await Promise.all([tar.exited, new Response(tar.stderr).text()]);
+      if (code !== 0) throw new Error(`tar of ${pack.out} failed: ${stderr.trim()}`);
+      return await use(path.join(dir, "pack.tgz"));
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  }
+}