@akanjs/devkit 3.1.1-rc.6 → 3.1.1-rc.8

package/cloud/cloudApi.ts

@@ -1,4 +1,4 @@
-import { isRecord } from "akanjs/common";
+import { isRecord, Logger } from "akanjs/common";
 import type { Workspace } from "../commandDecorators";
 import { CloudHttpError } from "./cloudHttpError";
 import type { AccessToken, AccessTokenDto, HostConfig } from "./constants";
@@ -86,7 +86,10 @@ export interface CloudRecord {
 export interface UpdateUploadRequest {
   appName: string;
   target: string;
-  platform: "ios" | "android";
+  platform: "ios" | "android" | "macos" | "windows" | "linux";
+  //? Absent is a phone's web bundle, so a phone request reads as it did before desktop releases.
+  kind?: "app";
+  arch?: "arm64" | "x64";
   channel: string;
   notes: string | null;
   size: number;
@@ -120,8 +123,11 @@ export class CloudApi {
     if (error.status === 401)
       return new Error("The server did not accept your sign-in: run `akan login`, then try again.", { cause: error });
     if (error.status === 403) return new Error(`The project refused: ${who}.`, { cause: error });
-    if (error.status === 400)
-      return new Error(`The project refused the request${error.error ? `: ${error.error}` : ""}.`, { cause: error });
+    if (error.status === 400) {
+      const { data } = error;
+      const why = `${error.error ? `: ${error.error}` : ""}${data ? ` ${Logger.inlineData(data)}` : ""}`;
+      return new Error(`The project refused the request${why}.`, { cause: error });
+    }
     //? A proxy, or the gateway with no replica ready, answers 503 too; only the server's own names a domain Err key.
     const { errKey } = error;
     if (error.status === 503 && unavailable && errKey && errKey !== "base.error.serverUnavailable")

package/cloud/cloudHttpError.test.ts

@@ -20,6 +20,14 @@ describe("CloudHttpError", () => {
     expect(plain.errKey).toBeNull();
   });
 
+  test("reads the data a server Err carried, and none from a body without it", () => {
+    const body = JSON.stringify({ error: "release.error.desktopMalformed", data: { reason: "a directory entry" } });
+
+    expect(new CloudHttpError(400, "Bad Request", "/x", body).data).toEqual({ reason: "a directory entry" });
+    expect(new CloudHttpError(400, "Bad Request", "/x", '{"error":"Bad Request","data":"x"}').data).toBeNull();
+    expect(new CloudHttpError(502, "Bad Gateway", "/x", "<html>502</html>").data).toBeNull();
+  });
+
   test("takes Retry-After as seconds or as a date, and nothing else", () => {
     expect(CloudHttpError.retryAfterMs("7")).toBe(7000);
     expect(CloudHttpError.retryAfterMs(new Date(Date.now() + 60_000).toUTCString())).toBeGreaterThan(55_000);

package/cloud/cloudHttpError.ts

@@ -26,9 +26,19 @@ export class CloudHttpError extends Error {
 
   /** The `error` of a JSON refusal: an Err key from the server itself, or whatever a proxy put there. */
   get error(): string | null {
+    const error = this.#payload?.error;
+    return typeof error === "string" ? error : null;
+  }
+
+  get data(): Record<string, unknown> | null {
+    const data = this.#payload?.data;
+    return isRecord(data) ? data : null;
+  }
+
+  get #payload(): Record<string, unknown> | null {
     try {
       const parsed: unknown = JSON.parse(this.body);
-      return isRecord(parsed) && typeof parsed.error === "string" ? parsed.error : null;
+      return isRecord(parsed) ? parsed : null;
     } catch {
       return null;
     }

package/cloud/cloudUpdates.ts

@@ -3,15 +3,18 @@ import { Logger } from "akanjs/common";
 import type { NativeEnv } from "../akanConfig";
 import type { App } from "../commandDecorators";
 import { ExitCodeError } from "../commandDecorators/exitCodeError";
+import type { DesktopRelease, DesktopSigner } from "../mobile/desktopRelease";
 import { type MobilePlatform, resolveMobileTargets } from "../mobile/mobileTarget";
 import { NativeApp } from "../mobile/nativeApp";
 import { NativePublicEnv } from "../mobile/nativePublicEnv";
 import { type NativeUpdatePack, UpdatePackFolder } from "../mobile/updatePackFolder";
 import { type AppBinaryDistribution, CloudApi } from "./cloudApi";
+import { CloudHttpError } from "./cloudHttpError";
 import { UpdatePackUpload } from "./updatePackUpload";
 
 //* A phone app's over-the-air updates through an Akan Cloud project, which keeps the signing key: a pack uploaded for
-//* it to sign and publish, and the store build a pack of the same commit is embedded in.
+//* it to sign and publish, and the store build a pack of the same commit is embedded in. A desktop release is signed
+//* where it was published, and goes up as it is.
 export class CloudUpdates {
   constructor(
     readonly cloudApi: CloudApi,
@@ -59,7 +62,7 @@ export class CloudUpdates {
       const release = await new UpdatePackUpload(this.cloudApi, this.devProjectId)
         .send(archive, { appName: pack.app, target: pack.target, platform: pack.platform, channel: target, notes })
         .catch((error: unknown) => {
-          throw CloudApi.refusal(error, "a pack is uploaded by a project member signed in with `akan login`");
+          throw CloudUpdates.#refusal(error, "a pack is uploaded by a project member signed in with `akan login`");
         });
       const label = `${pack.app} ${pack.target} ${pack.platform} on channel ${target}: release ${release.id}`;
       if (release.status === "rejected")
@@ -77,6 +80,48 @@ export class CloudUpdates {
     });
   }
 
+  //? `manifestUrl` is where the project serves the channel once published; before that, the URL the app was built with.
+  async pushRelease(
+    release: DesktopRelease,
+    {
+      appName,
+      target,
+      notes,
+      signer,
+      url,
+    }: { appName: string; target: string; notes: string | null; signer: DesktopSigner; url: string },
+  ) {
+    const { platform, arch, channel } = release;
+    return await release.withArchive(release.record(signer), async (archive) => {
+      const record = await new UpdatePackUpload(this.cloudApi, this.devProjectId)
+        .send(archive, { appName, target, platform, kind: "app", arch, channel, notes })
+        .catch((error: unknown) => {
+          throw CloudUpdates.#refusal(error, "a release is uploaded by a project member signed in with `akan login`");
+        });
+      const label = `${appName} ${target} ${platform}-${arch} on channel ${channel}: release ${record.id}`;
+      const problems = (record.problems ?? []).map((problem) => `  - ${problem}`).join("\n");
+      if (record.status === "rejected") throw new ExitCodeError(`The project rejected ${label}:\n${problems}`, 2);
+      const manifestUrl =
+        typeof record.manifestUrl === "string" ? record.manifestUrl : `${url}/${platform}-${arch}/${channel}.json`;
+      const what = `${label} (${release.manifest.bundle}, ${release.payloads.length + 3} files)`;
+      Logger.rawLog(
+        record.status === "published"
+          ? `Published ${what}. Installed apps read ${manifestUrl}.`
+          : `Staged ${what}. Publish it from the project's release screen; installed apps read ${manifestUrl}.`,
+      );
+      if (problems) Logger.rawLog(`The project noted:\n${problems}`);
+      return record;
+    });
+  }
+
+  //? A 400 naming a release Err key is the project's verdict on the release, as a rejected one is: a retry changes nothing.
+  static #refusal(error: unknown, who: string) {
+    const refusal = CloudApi.refusal(error, who);
+    const verdict =
+      error instanceof CloudHttpError && error.status === 400 && !!error.errKey?.startsWith("release.error.");
+    return verdict && refusal instanceof Error ? new ExitCodeError(refusal.message, 2) : refusal;
+  }
+
   //? The store build first, then a pack of the same commit: a server that registers the binary checks the pack runs in it.
   async registerBinary(
     app: App,

package/cloud/updatePackUpload.test.ts

@@ -1,6 +1,6 @@
 import { afterAll, beforeEach, describe, expect, test } from "bun:test";
 import { createHash } from "node:crypto";
-import { writeFile } from "node:fs/promises";
+import { truncate, writeFile } from "node:fs/promises";
 import path from "node:path";
 import type { Workspace } from "../commandDecorators";
 import { tempDirs } from "../testHelpers";
@@ -24,6 +24,7 @@ class FakeCloudHost {
   commitAnswers: (number | [number, string] | Response)[] = [];
   release: Record<string, unknown> = { id: "release-1", status: "published", problems: [] };
   requestRefusal: Response | null = null;
+  contentType = "application/gzip";
 
   constructor() {
     this.server = Bun.serve({ port: 0, hostname: "127.0.0.1", fetch: (request) => this.#route(request) });
@@ -42,6 +43,7 @@ class FakeCloudHost {
     this.stallPuts = false;
     this.commitAnswers = [];
     this.requestRefusal = null;
+    this.contentType = "application/gzip";
   }
 
   async #route(request: Request) {
@@ -54,7 +56,7 @@ class FakeCloudHost {
         uploadId,
         uploadUrl: `${this.host}/storage/${uploadId}?X-Amz-Signature=secret-signature`,
         expiresAt: new Date(Date.now() + 15 * 60_000).toISOString(),
-        contentType: "application/gzip",
+        contentType: this.contentType,
       });
     }
     if (url.pathname.startsWith("/storage/") && request.method === "PUT") {
@@ -302,4 +304,38 @@ describe("UpdatePackUpload", () => {
     await expect(new UpdatePackUpload(api, "project-1", quick).send(archive, fields)).rejects.toThrow("0 bytes");
     expect(cloudHost.requests).toEqual([]);
   });
+
+  test("announces a desktop release with its kind and CPU, a phone pack with neither, and PUTs the ticket's type", async () => {
+    const desktop = { ...fields, platform: "macos" as const, kind: "app" as const, arch: "arm64" as const };
+    cloudHost.contentType = "application/x-tar";
+
+    await new UpdatePackUpload(api, "project-1", quick).send(await archiveOf("release tar"), desktop);
+    await new UpdatePackUpload(api, "project-1", quick).send(await archiveOf("pack bytes"), fields);
+
+    expect(cloudHost.requests[0]).toMatchObject({ platform: "macos", kind: "app", arch: "arm64", size: 11 });
+    expect(Object.keys(cloudHost.requests[1] ?? {}).filter((key) => key === "kind" || key === "arch")).toEqual([]);
+    expect(cloudHost.puts.map((put) => put.headers["content-type"])).toEqual([
+      "application/x-tar",
+      "application/x-tar",
+    ]);
+  });
+
+  test("takes a desktop release up to 1 GiB and a phone pack up to 200 MiB, refusing more before a ticket", async () => {
+    const desktop = { ...fields, platform: "windows" as const, kind: "app" as const, arch: "x64" as const };
+    const sparse = async (bytes: number) => {
+      const archive = await archiveOf("");
+      await truncate(archive, bytes);
+      return archive;
+    };
+    const upload = new UpdatePackUpload(api, "project-1", quick);
+
+    await expect(upload.send(await sparse(UpdatePackUpload.maxBytes + 1), fields)).rejects.toThrow(
+      `The pack archive is ${UpdatePackUpload.maxBytes + 1} bytes; a project takes 1 byte to 200 MiB.`,
+    );
+    await expect(upload.send(await sparse(UpdatePackUpload.maxAppBytes + 1), desktop)).rejects.toThrow(
+      `The release archive is ${UpdatePackUpload.maxAppBytes + 1} bytes; a project takes 1 byte to 1 GiB.`,
+    );
+    expect(cloudHost.requests).toEqual([]);
+    expect(UpdatePackUpload.maxAppBytes).toBe(1_073_741_824);
+  });
 });

package/cloud/updatePackUpload.ts

@@ -16,6 +16,7 @@ interface UpdatePackUploadOptions {
 //* embedded pack; either re-hashes it, and an upload is used once, one way.
 export class UpdatePackUpload {
   static readonly maxBytes = 200 * 1024 * 1024;
+  static readonly maxAppBytes = 1024 * 1024 * 1024;
   static readonly #transientPut = new Set([0, 408, 429, 500, 502, 503, 504]);
   //? A stalled PUT never fails on its own, so each try ends once the pack would be through even at this crawl.
   static readonly #putFloorBytesPerSecond = 64 * 1024;
@@ -57,7 +58,10 @@ export class UpdatePackUpload {
   /** Puts the pack in the project's staging storage and answers the upload id a commit or a registration names. */
   async stage(archive: string, fields: Omit<UpdateUploadRequest, "size" | "sha256">): Promise<string> {
     const file = Bun.file(archive);
-    if (file.size < 1 || file.size > UpdatePackUpload.maxBytes)
+    if (fields.kind === "app") {
+      if (file.size < 1 || file.size > UpdatePackUpload.maxAppBytes)
+        throw new Error(`The release archive is ${file.size} bytes; a project takes 1 byte to 1 GiB.`);
+    } else if (file.size < 1 || file.size > UpdatePackUpload.maxBytes)
       throw new Error(`The pack archive is ${file.size} bytes; a project takes 1 byte to 200 MiB.`);
     const hasher = new Bun.CryptoHasher("sha256");
     for await (const chunk of file.stream()) hasher.update(chunk);

package/mobile/desktopRelease.test.ts

@@ -0,0 +1,402 @@
+import { describe, expect, test } from "bun:test";
+import { createHash, generateKeyPairSync, sign } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { AkanAppConfig } from "../akanConfig";
+import { tempDirs } from "../testHelpers";
+import type { DesktopArch } from "./desktopBin";
+import { DesktopRelease, type SignatureTool } from "./desktopRelease";
+import type { DesktopPlatform } from "./mobileTarget";
+
+const makeDir = tempDirs("akan-desktop-release-");
+const sha256 = (bytes: string | Uint8Array) => createHash("sha256").update(bytes).digest("hex");
+
+const keyOf = () => {
+  const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+  return {
+    publicKey: publicKey.export({ format: "der", type: "spki" }).subarray(12).toString("base64"),
+    sign: (bytes: string) => `${sign(null, Buffer.from(bytes), privateKey).toString("base64")}\n`,
+  };
+};
+const key = keyOf();
+const appId = "com.akancad.app";
+
+interface Published {
+  updatesDir: string;
+  dir: string;
+  tarSha: string;
+  delta: string;
+  build: number;
+}
+
+const publish = async ({
+  platform = "macos",
+  arch = "arm64",
+  channel = "main",
+  app = platform === "macos" ? "Akancad.app" : "akancad",
+  gz = "the release's gzip tar",
+}: {
+  platform?: DesktopPlatform;
+  arch?: DesktopArch;
+  channel?: string;
+  app?: string;
+  gz?: string;
+} = {}) => {
+  const updatesDir = await makeDir();
+  const dir = path.join(updatesDir, `${platform}-${arch}`);
+  await mkdir(path.join(dir, "app"), { recursive: true });
+  const tarSha = sha256(`${channel} tar`);
+  const from = sha256("the previous tar");
+  const delta = `${from}-${tarSha}.delta.gz`;
+  await writeFile(path.join(dir, "app", `${tarSha}.tar.gz`), gz);
+  await writeFile(path.join(dir, "app", delta), "a delta");
+  const build = 1_761_699_000;
+  const manifest = {
+    schema: 1,
+    kind: "app",
+    app: appId,
+    platform,
+    channel,
+    sequence: 1_761_700_000,
+    bundle: "1.2.0-1761700000",
+    runtimeVersion: "0.12.0",
+    version: "1.2.0",
+    build,
+    arch,
+    files: [{ path: app, sha256: tarSha, size: 2048 }],
+    archive: { sha256: tarSha, url: `app/${tarSha}.tar.gz`, size: gz.length, gzSha256: sha256(gz) },
+    patches: [{ from, url: `app/${delta}`, sha256: sha256("a delta"), size: 7 }],
+    server: true,
+  };
+  const bytes = `${JSON.stringify(manifest, null, 2)}\n`;
+  await writeFile(path.join(dir, `${channel}.json`), bytes);
+  await writeFile(path.join(dir, `${channel}.json.sig`), key.sign(bytes));
+  return { updatesDir, dir, tarSha, delta, build } satisfies Published;
+};
+
+const read = (
+  { updatesDir }: Published,
+  {
+    platform = "macos",
+    arch = "arm64",
+    channel = "main",
+    publicKey = key.publicKey,
+    id = appId,
+  }: { platform?: DesktopPlatform; arch?: DesktopArch; channel?: string; publicKey?: string; id?: string } = {},
+) => DesktopRelease.read(updatesDir, { platform, arch, channel, appId: id, publicKey });
+
+const entriesOf = (archive: string) =>
+  Bun.spawnSync(["tar", "-tf", archive]).stdout.toString().split(/\r?\n/).filter(Boolean);
+
+//? Every header, a pax one too: a file's name is the `path` of the pax header before it, else its own name field.
+const headersOf = (bytes: Uint8Array) => {
+  const headers: { type: string; name: string; prefix: string; paxKeys: string[] }[] = [];
+  let paxPath: string | null = null;
+  for (let at = 0; at + 512 <= bytes.length; ) {
+    const block = Buffer.from(bytes.subarray(at, at + 512));
+    if (block.every((byte) => byte === 0)) break;
+    const field = (from: number, width: number) => block.toString("latin1", from, from + width).replace(/\0.*$/s, "");
+    const type = field(156, 1);
+    const size = Number.parseInt(field(124, 12), 8);
+    const records = Buffer.from(bytes.subarray(at + 512, at + 512 + size))
+      .toString("utf8")
+      .split("\n")
+      .filter(Boolean);
+    at += 512 + Math.ceil(size / 512) * 512;
+    const pax = type === "x" ? records.map((record) => record.slice(record.indexOf(" ") + 1)) : [];
+    const paxKeys = pax.map((record) => record.slice(0, record.indexOf("=")));
+    headers.push({ type, name: (type === "x" ? null : paxPath) ?? field(0, 100), prefix: field(345, 155), paxKeys });
+    paxPath = type === "x" ? (pax.find((record) => record.startsWith("path="))?.slice(5) ?? null) : null;
+  }
+  return headers;
+};
+
+const extract = async (archive: string) => {
+  const out = await makeDir();
+  expect(Bun.spawnSync(["tar", "-xf", archive, "-C", out]).exitCode).toBe(0);
+  return out;
+};
+
+describe("DesktopRelease", () => {
+  test("packs only what the channel's manifest names: no other channel, earlier archive or folder record", async () => {
+    const published = await publish();
+    const { dir, tarSha, delta } = published;
+    await publish({ channel: "develop" }).then(async (other) => {
+      for (const name of ["develop.json", "develop.json.sig"])
+        await writeFile(path.join(dir, name), await readFile(path.join(other.dir, name)));
+    });
+    await writeFile(path.join(dir, "app", `${sha256("an earlier tar")}.tar.gz`), "an earlier release");
+    await writeFile(path.join(dir, "mirror.txt"), "not part of the release");
+    const release = await read(published);
+
+    const entries = await release.withArchive(release.record(null), async (archive) => entriesOf(archive));
+
+    expect(entries).toEqual([
+      "./release.json",
+      "./main.json",
+      "./main.json.sig",
+      `./app/${tarSha}.tar.gz`,
+      `./app/${delta}`,
+    ]);
+  });
+
+  test("keeps the one tar shape Akan Cloud accepts, a pax name of a long patch included", async () => {
+    const published = await publish();
+    const release = await read(published);
+
+    const headers = await release.withArchive(release.record(null), async (archive) =>
+      headersOf(await readFile(archive)),
+    );
+
+    expect(new Set(headers.map(({ type }) => type))).toEqual(new Set(["0", "x"]));
+    expect(headers.filter(({ prefix }) => prefix)).toEqual([]);
+    expect(headers.filter(({ type }) => type === "x").map(({ paxKeys }) => paxKeys)).toEqual([["path"]]);
+    const files = headers.filter(({ type }) => type === "0").map(({ name }) => name);
+    expect(files.slice(0, 3)).toEqual(["./release.json", "./main.json", "./main.json.sig"]);
+    expect(files.slice(3).every((name) => name.startsWith("./app/"))).toBe(true);
+    expect(files.slice(3)).toEqual([`./app/${published.tarSha}.tar.gz`, `./app/${published.delta}`]);
+    expect(Buffer.byteLength(`./app/${published.delta}`)).toBeGreaterThan(100);
+  });
+
+  test("the manifest and its signature go in byte for byte, beside a release.json of the CLI and the build time", async () => {
+    const published = await publish();
+    const release = await read(published);
+    const record = release.record({ teamId: "ABCDE12345" });
+
+    const out = await release.withArchive(record, extract);
+
+    for (const name of ["main.json", "main.json.sig"])
+      expect(sha256(await readFile(path.join(out, name)))).toBe(sha256(await readFile(path.join(published.dir, name))));
+    expect(await readFile(path.join(out, "release.json"), "utf8")).toBe(`${JSON.stringify(record, null, 2)}\n`);
+    expect(record).toEqual({
+      schema: 1,
+      cli: AkanAppConfig.akanVersion,
+      platform: "macos",
+      arch: "arm64",
+      channel: "main",
+      signer: { teamId: "ABCDE12345" },
+      builtAt: new Date(published.build * 1000).toISOString(),
+    });
+  });
+
+  test("leaves no archive behind, also when the upload fails", async () => {
+    const release = await read(await publish());
+    let kept = "";
+
+    await expect(
+      release.withArchive(release.record(null), async (archive) => {
+        kept = archive;
+        throw new Error("upload failed");
+      }),
+    ).rejects.toThrow("upload failed");
+    expect(await Bun.file(kept).exists()).toBe(false);
+  });
+
+  test("refuses a manifest the target's first key did not sign, before reading anything it names", async () => {
+    const published = await publish();
+
+    await expect(read(published, { publicKey: keyOf().publicKey })).rejects.toThrow(
+      "main.json.sig does not verify with updates.publicKeys[0], the one key installed apps trust",
+    );
+  });
+
+  test("refuses a release of another app, and names a channel or CPU it holds none of", async () => {
+    const published = await publish();
+
+    await expect(read(published, { id: "com.other" })).rejects.toThrow(
+      "is not a release of com.other for macos-arm64 on channel main.",
+    );
+    await expect(read(published, { channel: "develop" })).rejects.toThrow(
+      `${path.join(published.dir, "develop.json")} is missing: run \`akan publish-update\` first.`,
+    );
+    await expect(read(published, { arch: "x64" })).rejects.toThrow("macos-x64");
+  });
+
+  test("refuses an archive that is not the file the manifest names, by its length or its digest", async () => {
+    const published = await publish();
+    const archive = path.join(published.dir, "app", `${published.tarSha}.tar.gz`);
+    const release = await read(published);
+    const send = () => release.withArchive(release.record(null), async () => "sent");
+
+    await writeFile(archive, "the release's gzip tar!");
+    await expect(send()).rejects.toThrow(`${archive} is not the file main.json names: publish the release again.`);
+    await writeFile(archive, "the release's gzip taR");
+    await expect(send()).rejects.toThrow(`${archive} is not the file main.json names (its sha256 differs).`);
+  });
+});
+
+const recordingTool = (
+  answer: (cmd: string[], env: Record<string, string>) => Promise<{ code: number; output: string }>,
+) => {
+  const calls: { cmd: string[]; env: Record<string, string> }[] = [];
+  const run: SignatureTool = async (cmd, { env = {} } = {}) => {
+    calls.push({ cmd, env });
+    return await answer(cmd, env);
+  };
+  return { calls, run };
+};
+const bom = String.fromCharCode(0xfeff);
+const extractedTo = (cmd: string[]) => cmd[cmd.indexOf("-C") + 1] ?? "";
+
+describe("DesktopRelease signer", () => {
+  const macTool = (codesign: { code: number; output: string }, { plist = true } = {}) =>
+    recordingTool(async (cmd) => {
+      if (cmd[0] === "/usr/bin/tar") {
+        if (plist) await Bun.write(path.join(extractedTo(cmd), "Akancad.app/Contents/Info.plist"), "<plist/>");
+        return { code: 1, output: "tar: _CodeSignature/*: Not found in archive" };
+      }
+      return codesign;
+    });
+
+  test("macOS: the TeamIdentifier codesign shows for the app in the archive", async () => {
+    const release = await read(await publish());
+    const { calls, run } = macTool({
+      code: 0,
+      output: "Executable=…\nTeamIdentifier=ABCDE12345\nSealed Resources=none\n",
+    });
+
+    expect(await release.signer({ exeName: "akancad", host: "darwin", run })).toEqual({
+      signer: { teamId: "ABCDE12345" },
+      unread: null,
+    });
+    const [extraction, display] = calls;
+    expect(extraction?.cmd.slice(0, 3)).toEqual([
+      "/usr/bin/tar",
+      "-xzf",
+      path.join(release.dir, release.manifest.archive.url),
+    ]);
+    expect(extraction?.cmd.filter((_, idx, cmd) => cmd[idx - 1] === "--include")).toEqual([
+      "Akancad.app/Contents/Info.plist",
+      "Akancad.app/Contents/MacOS/*",
+      "Akancad.app/Contents/_CodeSignature/*",
+    ]);
+    expect(display?.cmd).toEqual([
+      "/usr/bin/codesign",
+      "--display",
+      "--verbose=2",
+      path.join(extractedTo(extraction?.cmd ?? []), "Akancad.app"),
+    ]);
+  });
+
+  test("macOS: an app signed ad hoc or not at all has no signer, and nothing to warn about", async () => {
+    const release = await read(await publish());
+    const adHoc = macTool({ code: 0, output: "Signature=adhoc\nTeamIdentifier=not set\n" });
+    const unsigned = macTool({ code: 1, output: "/tmp/x/Akancad.app: code object is not signed at all\n" });
+
+    for (const { run } of [adHoc, unsigned])
+      expect(await release.signer({ exeName: "akancad", host: "darwin", run })).toEqual({ signer: null, unread: null });
+  });
+
+  test("macOS: says why when codesign or the archive cannot tell", async () => {
+    const release = await read(await publish());
+
+    expect(
+      await release.signer({ exeName: "akancad", host: "darwin", run: macTool({ code: 1, output: "boom\n" }).run }),
+    ).toEqual({ signer: null, unread: "codesign could not read Akancad.app: boom" });
+    expect(
+      await release.signer({
+        exeName: "akancad",
+        host: "darwin",
+        run: macTool({ code: 0, output: "" }, { plist: false }).run,
+      }),
+    ).toEqual({ signer: null, unread: "the archive holds no Akancad.app/Contents/Info.plist" });
+    const { calls, run } = macTool({ code: 0, output: "TeamIdentifier=ABCDE12345\n" });
+    expect(await release.signer({ exeName: "akancad", host: "linux", run })).toEqual({
+      signer: null,
+      unread: "codesign reads a macOS app's signer on macOS only",
+    });
+    expect(calls).toEqual([]);
+  });
+
+  const windowsTool = (powershell: (out: string) => Promise<number>) =>
+    recordingTool(async (cmd, env) => {
+      if (cmd[0] === "tar.exe") {
+        await Bun.write(path.join(extractedTo(cmd), cmd.at(-1) ?? ""), "MZ");
+        return { code: 0, output: "" };
+      }
+      return { code: await powershell(env.AKAN_SIGNER_OUT), output: "" };
+    });
+
+  test("Windows: the Authenticode subject of the app's executable, read as UTF-8", async () => {
+    const release = await read(await publish({ platform: "windows", arch: "x64" }), {
+      platform: "windows",
+      arch: "x64",
+    });
+    const subject = "CN=아칸 주식회사, O=아칸 주식회사, C=KR";
+    const { calls, run } = windowsTool(async (out) => {
+      await Bun.write(out, `${bom}${subject}\r\n`);
+      return 0;
+    });
+
+    expect(await release.signer({ exeName: "akancad", host: "win32", run })).toEqual({
+      signer: { subject },
+      unread: null,
+    });
+    const [extraction, check] = calls;
+    expect(extraction?.cmd.at(-1)).toBe("akancad/akancad.exe");
+    expect(check?.env.AKAN_RELEASE_EXE).toBe(path.join(extractedTo(extraction?.cmd ?? []), "akancad/akancad.exe"));
+    expect(check?.cmd.slice(1, 4)).toEqual(["-NoProfile", "-NonInteractive", "-EncodedCommand"]);
+    expect(Buffer.from(check?.cmd[4] ?? "", "base64").toString("utf16le")).toContain(
+      "Get-AuthenticodeSignature -LiteralPath $env:AKAN_RELEASE_EXE",
+    );
+  });
+
+  test("Windows: an executable without a valid signature has no signer; a PowerShell that fails says so", async () => {
+    const release = await read(await publish({ platform: "windows", arch: "x64" }), {
+      platform: "windows",
+      arch: "x64",
+    });
+    const unsigned = windowsTool(async (out) => {
+      await Bun.write(out, `${bom}\r\n`);
+      return 0;
+    });
+    const blocked = windowsTool(async () => 1);
+
+    expect(await release.signer({ exeName: "akancad", host: "win32", run: unsigned.run })).toEqual({
+      signer: null,
+      unread: null,
+    });
+    expect(await release.signer({ exeName: "akancad", host: "win32", run: blocked.run })).toEqual({
+      signer: null,
+      unread: "PowerShell could not read the Authenticode signature of akancad/akancad.exe",
+    });
+    expect(await release.signer({ exeName: "akancad", host: "darwin", run: unsigned.run })).toEqual({
+      signer: null,
+      unread: "PowerShell reads a Windows app's Authenticode signer on Windows only",
+    });
+  });
+
+  test("Linux: no signer, and nothing run", async () => {
+    const release = await read(await publish({ platform: "linux", arch: "x64" }), { platform: "linux", arch: "x64" });
+    const { calls, run } = recordingTool(async () => ({ code: 0, output: "" }));
+
+    expect(await release.signer({ exeName: "akancad", host: "linux", run })).toEqual({ signer: null, unread: null });
+    expect(calls).toEqual([]);
+  });
+
+  test.skipIf(process.platform !== "darwin")(
+    "macOS: reads an ad hoc signature from the archive itself with the system tar and codesign",
+    async () => {
+      const build = await makeDir();
+      const contents = path.join(build, "Akancad.app", "Contents");
+      await mkdir(path.join(contents, "MacOS"), { recursive: true });
+      await mkdir(path.join(contents, "Resources"), { recursive: true });
+      await writeFile(path.join(contents, "Resources", "server.json"), "{}");
+      await writeFile(
+        path.join(contents, "Info.plist"),
+        '<?xml version="1.0" encoding="UTF-8"?>\n<plist version="1.0"><dict><key>CFBundleExecutable</key><string>akancad</string><key>CFBundleIdentifier</key><string>com.akancad.app</string></dict></plist>\n',
+      );
+      await writeFile(path.join(contents, "MacOS", "akancad"), await readFile("/usr/bin/true"));
+      const signed = Bun.spawnSync(["/usr/bin/codesign", "--force", "--sign", "-", path.join(build, "Akancad.app")]);
+      expect(signed.exitCode).toBe(0);
+      const gz = path.join(build, "release.tar.gz");
+      const tarred = Bun.spawnSync(["/usr/bin/tar", "--no-mac-metadata", "-czf", gz, "-C", build, "Akancad.app"]);
+      expect(tarred.exitCode).toBe(0);
+      const published = await publish();
+      await writeFile(path.join(published.dir, "app", `${published.tarSha}.tar.gz`), await readFile(gz));
+      const release = await read(published);
+
+      expect(await release.signer({ exeName: "akancad" })).toEqual({ signer: null, unread: null });
+    },
+  );
+});

package/mobile/desktopRelease.ts

@@ -0,0 +1,271 @@
+import { createPublicKey, verify } from "node:crypto";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { isRecord, toError } from "akanjs/common";
+import type { UpdateManifest } from "akanjs/native/api";
+import { AkanAppConfig } from "../akanConfig";
+import type { DesktopArch } from "./desktopBin";
+import type { DesktopPlatform } from "./mobileTarget";
+import { TarWriter } from "./tarWriter";
+import { UpdateUploader } from "./updateUploader";
+
+export type DesktopSigner = { teamId: string } | { subject: string } | null;
+
+/** `release.json`, the one file of a desktop release archive `publish-update` did not write. */
+export interface DesktopReleaseRecord {
+  schema: 1;
+  cli: string;
+  platform: DesktopPlatform;
+  arch: DesktopArch;
+  channel: string;
+  signer: DesktopSigner;
+  builtAt: string;
+}
+
+export type SignatureTool = (
+  cmd: string[],
+  options?: { env?: Record<string, string> },
+) => Promise<{ code: number; output: string }>;
+
+type DesktopManifest = Partial<UpdateManifest> &
+  Required<Pick<UpdateManifest, "archive" | "build" | "bundle" | "sequence">>;
+
+interface DesktopReleasePayload {
+  name: string;
+  size: number;
+  sha256: string;
+}
+
+//* One desktop channel's release as `publish-update` left it in `<updates>/<os>-<arch>/`: the signed manifest and the
+//* files it names, packed as they are, so the same folder uploaded anywhere else stays valid.
+export class DesktopRelease {
+  static readonly #ed25519Spki = Buffer.from("302a300506032b6570032100", "hex");
+  //? Constrained Language Mode (WDAC, AppLocker) refuses .NET type literals and method calls, so the script makes none.
+  //? Windows PowerShell writes its console in the OEM code page, which mangles a subject outside it; a file keeps UTF-8.
+  static readonly #authenticode = `$ErrorActionPreference = 'Stop'
+$ProgressPreference = 'SilentlyContinue'
+$signature = Get-AuthenticodeSignature -LiteralPath $env:AKAN_RELEASE_EXE
+$subject = if ("$($signature.Status)" -ceq 'Valid') { "$($signature.SignerCertificate.Subject)" } else { '' }
+Set-Content -LiteralPath $env:AKAN_SIGNER_OUT -Value $subject -Encoding UTF8`;
+
+  private constructor(
+    readonly dir: string,
+    readonly manifest: DesktopManifest,
+    readonly payloads: DesktopReleasePayload[],
+    readonly platform: DesktopPlatform,
+    readonly arch: DesktopArch,
+    readonly channel: string,
+    readonly manifestBytes: Uint8Array<ArrayBuffer>,
+    readonly signatureBytes: Uint8Array<ArrayBuffer>,
+  ) {}
+
+  static async read(
+    updatesDir: string,
+    {
+      platform,
+      arch,
+      channel,
+      appId,
+      publicKey,
+    }: { platform: DesktopPlatform; arch: DesktopArch; channel: string; appId: string; publicKey: string },
+  ) {
+    const folder = `${platform}-${arch}`;
+    const dir = path.join(updatesDir, folder);
+    const manifestPath = path.join(dir, `${channel}.json`);
+    const [manifestBytes, signatureBytes] = await Promise.all([
+      readFile(manifestPath).catch(() => null),
+      readFile(`${manifestPath}.sig`).catch(() => null),
+    ]);
+    if (!manifestBytes || !signatureBytes)
+      throw new Error(
+        `${manifestBytes ? `${manifestPath}.sig` : manifestPath} is missing: run \`akan publish-update\` first.`,
+      );
+    if (!DesktopRelease.#verifies(manifestBytes, signatureBytes, publicKey))
+      throw new Error(
+        `${manifestPath}.sig does not verify with updates.publicKeys[0], the one key installed apps trust: publish the release again.`,
+      );
+    const manifest = DesktopRelease.#parse(manifestBytes);
+    if (
+      manifest?.schema !== 1 ||
+      manifest.kind !== "app" ||
+      manifest.app !== appId ||
+      manifest.platform !== platform ||
+      manifest.arch !== arch ||
+      manifest.channel !== channel ||
+      typeof manifest.bundle !== "string" ||
+      typeof manifest.sequence !== "number" ||
+      typeof manifest.build !== "number" ||
+      !manifest.archive
+    )
+      throw new Error(`${manifestPath} is not a release of ${appId} for ${folder} on channel ${channel}.`);
+    const { archive, bundle, sequence, build } = manifest;
+    const keys = await UpdateUploader.releaseFiles(updatesDir, { dir, channel, bundle });
+    const expected = new Map(
+      [{ url: archive.url, size: archive.size, sha256: archive.gzSha256 }, ...(manifest.patches ?? [])].map(
+        ({ url, size, sha256 }) => [path.posix.normalize(url), { size, sha256 }],
+      ),
+    );
+    const payloads = keys.flatMap((key) => {
+      const name = key.slice(folder.length + 1);
+      const digest = expected.get(name);
+      return digest ? [{ name, ...digest }] : [];
+    });
+    return new DesktopRelease(
+      dir,
+      { ...manifest, archive, bundle, sequence, build },
+      payloads,
+      platform,
+      arch,
+      channel,
+      manifestBytes,
+      signatureBytes,
+    );
+  }
+
+  record(signer: DesktopSigner): DesktopReleaseRecord {
+    const { platform, arch, channel } = this;
+    const builtAt = new Date(this.manifest.build * 1000).toISOString();
+    return { schema: 1, cli: AkanAppConfig.akanVersion, platform, arch, channel, signer, builtAt };
+  }
+
+  //* Akan Cloud refuses every push in any other shape: uncompressed, regular files under `./` names, no directory
+  //* entry, no ustar prefix, no GNU L/K, a pax 'x' holding `path` alone, and release.json and the manifest pair before
+  //* any `app/` entry. What the manifest names is checked against it as it is copied.
+  async withArchive<T>(record: DesktopReleaseRecord, use: (archive: string) => Promise<T>): Promise<T> {
+    const tmp = await mkdtemp(path.join(os.tmpdir(), "akan-release-"));
+    try {
+      const archive = path.join(tmp, "release.tar");
+      const tar = await TarWriter.create(archive, { mtime: this.manifest.sequence });
+      try {
+        await tar.add("./release.json", new Blob([`${JSON.stringify(record, null, 2)}\n`]));
+        await tar.add(`./${this.channel}.json`, new Blob([this.manifestBytes]));
+        await tar.add(`./${this.channel}.json.sig`, new Blob([this.signatureBytes]));
+        for (const { name, size, sha256 } of this.payloads) {
+          const file = Bun.file(path.join(this.dir, name));
+          const what = `${path.join(this.dir, name)} is not the file ${this.channel}.json names`;
+          if (!(await file.exists()) || file.size !== size) throw new Error(`${what}: publish the release again.`);
+          if ((await tar.add(`./${name}`, file)) !== sha256) throw new Error(`${what} (its sha256 differs).`);
+        }
+        await tar.close();
+      } catch (error) {
+        await tar.discard();
+        throw error;
+      }
+      return await use(archive);
+    } finally {
+      await rm(tmp, { recursive: true, force: true });
+    }
+  }
+
+  async signer({
+    exeName,
+    host = process.platform,
+    run = DesktopRelease.#run,
+  }: {
+    exeName: string;
+    host?: NodeJS.Platform;
+    run?: SignatureTool;
+  }): Promise<{ signer: DesktopSigner; unread: string | null }> {
+    if (this.platform === "linux") return { signer: null, unread: null };
+    const app = this.manifest.files?.[0]?.path;
+    if (!app || !/^[^/\\]+$/.test(app) || app === "." || app === "..")
+      return { signer: null, unread: `${this.channel}.json names no app folder` };
+    if (this.platform === "macos" && host !== "darwin")
+      return { signer: null, unread: "codesign reads a macOS app's signer on macOS only" };
+    if (this.platform === "windows" && host !== "win32")
+      return { signer: null, unread: "PowerShell reads a Windows app's Authenticode signer on Windows only" };
+    const tmp = await mkdtemp(path.join(os.tmpdir(), "akan-signer-"));
+    try {
+      const archive = path.join(this.dir, this.manifest.archive.url);
+      return this.platform === "macos"
+        ? await DesktopRelease.#teamOf(run, archive, tmp, app)
+        : await DesktopRelease.#subjectOf(run, archive, tmp, path.posix.join(app, `${exeName}.exe`));
+    } finally {
+      await rm(tmp, { recursive: true, force: true });
+    }
+  }
+
+  //? The signature lives in the executable and _CodeSignature; Info.plist names the executable. An app signed without
+  //? resources has no _CodeSignature, and bsdtar then exits 1 for the unmatched --include though it wrote the rest.
+  static async #teamOf(run: SignatureTool, archive: string, tmp: string, app: string) {
+    const contents = `${app}/Contents`;
+    await run([
+      "/usr/bin/tar",
+      "-xzf",
+      archive,
+      "-C",
+      tmp,
+      ...["Info.plist", "MacOS/*", "_CodeSignature/*"].flatMap((entry) => ["--include", `${contents}/${entry}`]),
+    ]);
+    if (!(await Bun.file(path.join(tmp, contents, "Info.plist")).exists()))
+      return { signer: null, unread: `the archive holds no ${contents}/Info.plist` };
+    const { output } = await run(["/usr/bin/codesign", "--display", "--verbose=2", path.join(tmp, app)]);
+    const teamId = /^TeamIdentifier=([A-Z0-9]{10})$/m.exec(output)?.[1];
+    if (teamId) return { signer: { teamId }, unread: null };
+    if (/^TeamIdentifier=not set$/m.test(output) || /code object is not signed at all/.test(output))
+      return { signer: null, unread: null };
+    return { signer: null, unread: `codesign could not read ${app}: ${output.trim().split("\n")[0] ?? ""}` };
+  }
+
+  static async #subjectOf(run: SignatureTool, archive: string, tmp: string, exe: string) {
+    await run(["tar.exe", "-xzf", archive, "-C", tmp, exe]);
+    const extracted = path.join(tmp, exe);
+    if (!(await Bun.file(extracted).exists())) return { signer: null, unread: `the archive holds no ${exe}` };
+    const out = path.join(tmp, "signer.txt");
+    const { code } = await run(
+      [
+        path.join(process.env.SystemRoot ?? "C:\\Windows", "System32", "WindowsPowerShell", "v1.0", "powershell.exe"),
+        "-NoProfile",
+        "-NonInteractive",
+        "-EncodedCommand",
+        Buffer.from(DesktopRelease.#authenticode, "utf16le").toString("base64"),
+      ],
+      { env: { AKAN_RELEASE_EXE: extracted, AKAN_SIGNER_OUT: out } },
+    );
+    if (code !== 0) return { signer: null, unread: `PowerShell could not read the Authenticode signature of ${exe}` };
+    const subject = (await readFile(out, "utf8").catch(() => "")).replace(/^\uFEFF/, "").trim();
+    return { signer: subject ? { subject } : null, unread: null };
+  }
+
+  static #verifies(manifest: Uint8Array, signature: Uint8Array, publicKey: string) {
+    try {
+      const key = createPublicKey({
+        key: Buffer.concat([DesktopRelease.#ed25519Spki, Buffer.from(publicKey, "base64")]),
+        format: "der",
+        type: "spki",
+      });
+      return verify(null, manifest, key, Buffer.from(new TextDecoder().decode(signature).trim(), "base64"));
+    } catch {
+      return false;
+    }
+  }
+
+  static #parse(bytes: Uint8Array): Partial<UpdateManifest> | null {
+    try {
+      const value: unknown = JSON.parse(new TextDecoder().decode(bytes));
+      return isRecord(value) ? (value as Partial<UpdateManifest>) : null;
+    } catch {
+      return null;
+    }
+  }
+
+  static async #run(cmd: string[], { env }: { env?: Record<string, string> } = {}) {
+    try {
+      const proc = Bun.spawn(cmd, {
+        env: { ...process.env, ...env },
+        stdin: "ignore",
+        stdout: "pipe",
+        stderr: "pipe",
+      });
+      const [code, stdout, stderr] = await Promise.all([
+        proc.exited,
+        new Response(proc.stdout).text(),
+        new Response(proc.stderr).text(),
+      ]);
+      return { code, output: `${stdout}${stderr}` };
+    } catch (error) {
+      return { code: -1, output: toError(error).message };
+    }
+  }
+}

package/mobile/index.ts

@@ -1,4 +1,5 @@
 export * from "./desktopBin";
+export * from "./desktopRelease";
 export * from "./desktopServerStage";
 export * from "./mobileTarget";
 export * from "./nativeApi";
@@ -8,6 +9,7 @@ export * from "./nativePluginFolders";
 export * from "./nativePublicEnv";
 export * from "./nativeWebDir";
 export * from "./placeholderAppId";
+export * from "./tarWriter";
 export * from "./updatePackFolder";
 export * from "./updateUploader";
 export * from "./usageDescriptions";

package/mobile/nativeApp.ts

@@ -5,6 +5,7 @@ import type { AkanNativeConfig } from "akanjs/native/config";
 import type { App } from "../commandDecorators";
 import { Executor } from "../executors";
 import { type DesktopArch, DesktopBin } from "./desktopBin";
+import { DesktopRelease } from "./desktopRelease";
 import type { DesktopServerBundle } from "./desktopServerStage";
 import {
   type DesktopPlatform,
@@ -311,6 +312,22 @@ export class NativeApp {
     return path.join(this.targetRoot, "updates");
   }
 
+  //? The channel falls back as publishUpdate's does, so a push with the flags of the publish finds what it wrote.
+  async publishedRelease(platform: DesktopPlatform, { arch, channel }: { arch: DesktopArch; channel?: string | null }) {
+    this.#assertUpdates();
+    const { config } = await this.config({ platform, stageBin: false });
+    const publicKey = config.updates?.publicKeys?.[0] ?? config.updates?.publicKey;
+    if (!config.updates || !publicKey) throw new Error(`Native target '${this.target.name}' has no updates key.`);
+    const release = await DesktopRelease.read(this.updatesDir, {
+      platform,
+      arch,
+      channel: channel ?? config.updates.channel ?? "production",
+      appId: config.app.id,
+      publicKey,
+    });
+    return { release, url: config.updates.url, exeName: config.app.fileName ?? "" };
+  }
+
   /** A signed release installed apps take through the updates plugin, from a release build of this bundle. */
   async publishUpdate(
     platform: NativePlatform,

package/mobile/tarWriter.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, test } from "bun:test";
+import { createHash } from "node:crypto";
+import { mkdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { tempDirs } from "../testHelpers";
+import { TarWriter } from "./tarWriter";
+
+const makeDir = tempDirs("akan-tar-writer-");
+const delta = `./app/${"a".repeat(64)}-${"b".repeat(64)}.delta.gz`;
+const sha256 = (bytes: string | Uint8Array) => createHash("sha256").update(bytes).digest("hex");
+
+const write = async (file: string, entries: [string, string][], mtime = 1_761_700_000) => {
+  const tar = await TarWriter.create(file, { mtime });
+  const digests: string[] = [];
+  for (const [name, body] of entries) digests.push(await tar.add(name, new Blob([body])));
+  await tar.close();
+  return digests;
+};
+
+describe("TarWriter", () => {
+  test("a system tar reads back every file under its name, a 144-byte one too, and lists nothing else", async () => {
+    const dir = await makeDir();
+    const file = path.join(dir, "release.tar");
+    const entries: [string, string][] = [
+      ["./release.json", '{"schema":1}\n'],
+      [delta, "x".repeat(1_000)],
+    ];
+
+    const digests = await write(file, entries);
+
+    expect(digests).toEqual(entries.map(([, body]) => sha256(body)));
+    const listed = Bun.spawnSync(["tar", "-tf", file]).stdout.toString().split(/\r?\n/).filter(Boolean);
+    expect(listed).toEqual(entries.map(([name]) => name));
+    const out = path.join(dir, "out");
+    await mkdir(out);
+    expect(Bun.spawnSync(["tar", "-xf", file, "-C", out]).exitCode).toBe(0);
+    for (const [name, body] of entries) expect(await readFile(path.join(out, name), "utf8")).toBe(body);
+  });
+
+  test("writes ustar headers of mode 0644, owner 0 and the given mtime, padded to 512-byte blocks", async () => {
+    const dir = await makeDir();
+    const file = path.join(dir, "release.tar");
+
+    await write(file, [["./a.json", "{}"]], 1_761_700_000);
+
+    const bytes = await readFile(file);
+    const field = (at: number, width: number) => bytes.subarray(at, at + width).toString("latin1");
+    expect(field(0, 9)).toBe("./a.json\0");
+    expect(field(100, 8)).toBe("0000644\0");
+    expect(field(108, 16)).toBe("0000000\x000000000\0");
+    expect(Number.parseInt(field(136, 11), 8)).toBe(1_761_700_000);
+    expect(field(156, 1)).toBe("0");
+    expect(field(257, 8)).toBe("ustar\x0000");
+    expect(bytes.length).toBe(512 + 512 + 1024);
+    expect(bytes.subarray(1024).every((byte) => byte === 0)).toBe(true);
+  });
+
+  test("the same files and mtime make the same archive", async () => {
+    const dir = await makeDir();
+    const entries: [string, string][] = [
+      ["./main.json", "{}\n"],
+      [delta, "patch"],
+    ];
+
+    await write(path.join(dir, "one.tar"), entries);
+    await write(path.join(dir, "two.tar"), entries);
+
+    expect(sha256(await readFile(path.join(dir, "one.tar")))).toBe(sha256(await readFile(path.join(dir, "two.tar"))));
+  });
+
+  test("refuses a file whose length is not the one it was announced with", async () => {
+    const dir = await makeDir();
+    const tar = await TarWriter.create(path.join(dir, "release.tar"));
+    const grown = { size: 3, stream: () => new Blob(["abcdef"]).stream() } as unknown as Blob;
+
+    await expect(tar.add("./app/x.tar.gz", grown)).rejects.toThrow(
+      "./app/x.tar.gz changed while it was archived: 6 bytes, not 3.",
+    );
+    await tar.discard();
+  });
+
+  test("never overwrites an existing file", async () => {
+    const file = path.join(await makeDir(), "release.tar");
+    await Bun.write(file, "kept");
+
+    await expect(TarWriter.create(file)).rejects.toThrow();
+    expect(await readFile(file, "utf8")).toBe("kept");
+  });
+});

package/mobile/tarWriter.ts

@@ -0,0 +1,93 @@
+import { createHash } from "node:crypto";
+import { type FileHandle, open } from "node:fs/promises";
+
+//* An uncompressed POSIX tar of regular files, the same bytes on every OS. A system tar also writes what the host keeps
+//* beside a file (macOS bsdtar an AppleDouble `._` entry for extended attributes), which a receiver refusing unlisted
+//* entries rejects. A name past the ustar field's 100 bytes travels in a pax `path` record before its header.
+export class TarWriter {
+  static readonly #block = 512;
+  static readonly #nameBytes = 100;
+  //? The size field holds 11 octal digits.
+  static readonly #maxSize = 8 ** 11 - 1;
+  readonly #handle: FileHandle;
+  readonly #mtime: number;
+
+  private constructor(handle: FileHandle, mtime: number) {
+    this.#handle = handle;
+    this.#mtime = mtime;
+  }
+
+  //? `mtime` (seconds) goes on every entry, so the same files make the same archive.
+  static async create(file: string, { mtime = 0 }: { mtime?: number } = {}) {
+    return new TarWriter(await open(file, "wx"), mtime);
+  }
+
+  async add(name: string, source: Blob): Promise<string> {
+    const { size } = source;
+    if (size > TarWriter.#maxSize) throw new Error(`${name} is ${size} bytes, more than a tar entry holds.`);
+    if (Buffer.byteLength(name) > TarWriter.#nameBytes) {
+      const pax = Buffer.from(TarWriter.#paxRecord("path", name));
+      await this.#write(
+        TarWriter.#header(`./PaxHeaders/${name.split("/").at(-1) ?? ""}`, pax.length, this.#mtime, "x"),
+      );
+      await this.#write(pax);
+      await this.#pad(pax.length);
+    }
+    await this.#write(TarWriter.#header(name, size, this.#mtime, "0"));
+    const hasher = createHash("sha256");
+    let written = 0;
+    for await (const chunk of source.stream()) {
+      hasher.update(chunk);
+      await this.#write(chunk);
+      written += chunk.length;
+    }
+    if (written !== size) throw new Error(`${name} changed while it was archived: ${written} bytes, not ${size}.`);
+    await this.#pad(size);
+    return hasher.digest("hex");
+  }
+
+  async close() {
+    await this.#write(new Uint8Array(TarWriter.#block * 2));
+    await this.#handle.close();
+  }
+
+  async discard() {
+    await this.#handle.close().catch(() => undefined);
+  }
+
+  async #write(bytes: Uint8Array) {
+    for (let at = 0; at < bytes.length; ) at += (await this.#handle.write(bytes, at)).bytesWritten;
+  }
+
+  async #pad(size: number) {
+    const rest = size % TarWriter.#block;
+    if (rest) await this.#write(new Uint8Array(TarWriter.#block - rest));
+  }
+
+  //? A record's length counts its own digits: `<length> <key>=<value>\n`.
+  static #paxRecord(key: string, value: string) {
+    const body = Buffer.byteLength(` ${key}=${value}\n`);
+    let length = body + 1;
+    while (body + String(length).length !== length) length = body + String(length).length;
+    return `${length} ${key}=${value}\n`;
+  }
+
+  static #header(name: string, size: number, mtime: number, type: "0" | "x") {
+    const header = Buffer.alloc(TarWriter.#block);
+    header.write(name, 0, TarWriter.#nameBytes, "utf8");
+    const octal = (value: number, at: number, width: number) =>
+      header.write(`${value.toString(8).padStart(width - 1, "0")}\0`, at, width, "latin1");
+    octal(0o644, 100, 8);
+    octal(0, 108, 8);
+    octal(0, 116, 8);
+    octal(size, 124, 12);
+    octal(mtime, 136, 12);
+    header.write("        ", 148, 8, "latin1");
+    header.write(type, 156, 1, "latin1");
+    header.write("ustar\0", 257, 6, "latin1");
+    header.write("00", 263, 2, "latin1");
+    const checksum = header.reduce((sum, byte) => sum + byte, 0);
+    header.write(`${checksum.toString(8).padStart(6, "0")}\0 `, 148, 8, "latin1");
+    return header;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.1.1-rc.6",
+  "version": "3.1.1-rc.8",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -48,7 +48,7 @@
     "@earendil-works/pi-tui": "1.3.0",
     "@inquirer/prompts": "^8.7.3",
     "@tailwindcss/node": "^4.3.3",
-    "akanjs": "3.1.1-rc.6",
+    "akanjs": "3.1.1-rc.8",
     "chalk": "^6.0.1",
     "commander": "^15.0.0",
     "dayjs": "^1.11.23",