@akanjs/devkit 3.1.1-rc.7 → 3.1.1-rc.9

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";
@@ -123,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

@@ -9,6 +9,7 @@ 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
@@ -61,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")
@@ -95,14 +96,15 @@ export class CloudUpdates {
       const record = await new UpdatePackUpload(this.cloudApi, this.devProjectId)
         .send(archive, { appName, target, platform, kind: "app", arch, channel, notes })
         .catch((error: unknown) => {
-          throw CloudApi.refusal(error, "a release is uploaded by a project member signed in with `akan login`");
+          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)`;
+        typeof record.manifestUrl === "string" ? record.manifestUrl : `${url}/${platform}-${arch}/${channel}/app.json`;
+      const files = 1 + release.manifestFiles.length + release.payloads.length;
+      const what = `${label} (${release.manifest.bundle}, ${files} files)`;
       Logger.rawLog(
         record.status === "published"
           ? `Published ${what}. Installed apps read ${manifestUrl}.`
@@ -113,6 +115,14 @@ export class CloudUpdates {
     });
   }
 
+  //? 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/mobile/desktopRelease.test.ts

@@ -2,6 +2,7 @@ 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 * as nativeApi from "akanjs/native/api";
 import { AkanAppConfig } from "../akanConfig";
 import { tempDirs } from "../testHelpers";
 import type { DesktopArch } from "./desktopBin";
@@ -13,12 +14,18 @@ const sha256 = (bytes: string | Uint8Array) => createHash("sha256").update(bytes
 
 const keyOf = () => {
   const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+  const raw = publicKey.export({ format: "der", type: "spki" }).subarray(12).toString("base64");
+  const signature = (bytes: string) => sign(null, Buffer.from(bytes), privateKey).toString("base64");
   return {
-    publicKey: publicKey.export({ format: "der", type: "spki" }).subarray(12).toString("base64"),
-    sign: (bytes: string) => `${sign(null, Buffer.from(bytes), privateKey).toString("base64")}\n`,
+    publicKey: raw,
+    keyId: nativeApi.keyIdOf(raw),
+    sign: (bytes: string) => `${signature(bytes)}\n`,
+    seal: (bytes: string) =>
+      `${JSON.stringify({ manifest: Buffer.from(bytes).toString("base64"), keyId: nativeApi.keyIdOf(raw), signature: signature(bytes) }, null, 2)}\n`,
   };
 };
 const key = keyOf();
+const spare = keyOf();
 const appId = "com.akancad.app";
 
 interface Published {
@@ -35,12 +42,18 @@ const publish = async ({
   channel = "main",
   app = platform === "macos" ? "Akancad.app" : "akancad",
   gz = "the release's gzip tar",
+  target = "default",
+  signer = key,
+  pair = "same",
 }: {
   platform?: DesktopPlatform;
   arch?: DesktopArch;
   channel?: string;
   app?: string;
   gz?: string;
+  target?: string;
+  signer?: ReturnType<typeof keyOf>;
+  pair?: "same" | "earlier" | "none";
 } = {}) => {
   const updatesDir = await makeDir();
   const dir = path.join(updatesDir, `${platform}-${arch}`);
@@ -68,9 +81,17 @@ const publish = async ({
     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));
+  await mkdir(path.join(dir, channel), { recursive: true });
+  await writeFile(
+    path.join(dir, channel, "app.json"),
+    signer.seal(`${JSON.stringify({ ...manifest, schema: 2, target }, null, 2)}\n`),
+  );
+  if (pair !== "none") {
+    const earlier = { ...manifest, sequence: manifest.sequence - 100, bundle: "1.1.0-1761699900" };
+    const bytes = `${JSON.stringify(pair === "same" ? manifest : earlier, 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;
 };
 
@@ -80,14 +101,57 @@ const read = (
     platform = "macos",
     arch = "arm64",
     channel = "main",
-    publicKey = key.publicKey,
+    publicKeys = [key.publicKey, spare.publicKey],
+    revokedKeys = [],
+    target = "default",
     id = appId,
-  }: { platform?: DesktopPlatform; arch?: DesktopArch; channel?: string; publicKey?: string; id?: string } = {},
-) => DesktopRelease.read(updatesDir, { platform, arch, channel, appId: id, publicKey });
+  }: {
+    platform?: DesktopPlatform;
+    arch?: DesktopArch;
+    channel?: string;
+    publicKeys?: string[];
+    revokedKeys?: string[];
+    target?: string;
+    id?: string;
+  } = {},
+) =>
+  DesktopRelease.read(updatesDir, {
+    platform,
+    arch,
+    channel,
+    appId: id,
+    target,
+    publicKeys,
+    revokedKeys,
+    api: nativeApi,
+  });
 
 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);
@@ -99,7 +163,8 @@ describe("DesktopRelease", () => {
     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 mkdir(path.join(dir, "develop"), { recursive: true });
+      for (const name of ["develop.json", "develop.json.sig", "develop/app.json"])
         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");
@@ -110,6 +175,7 @@ describe("DesktopRelease", () => {
 
     expect(entries).toEqual([
       "./release.json",
+      "./main/app.json",
       "./main.json",
       "./main.json.sig",
       `./app/${tarSha}.tar.gz`,
@@ -117,18 +183,36 @@ describe("DesktopRelease", () => {
     ]);
   });
 
-  test("the manifest and its signature go in byte for byte, beside a release.json of the CLI and the build time", async () => {
+  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, 4)).toEqual(["./release.json", "./main/app.json", "./main.json", "./main.json.sig"]);
+    expect(files.slice(4).every((name) => name.startsWith("./app/"))).toBe(true);
+    expect(files.slice(4)).toEqual([`./app/${published.tarSha}.tar.gz`, `./app/${published.delta}`]);
+    expect(Buffer.byteLength(`./app/${published.delta}`)).toBeGreaterThan(100);
+  });
+
+  test("the envelope and the v1 pair 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"])
+    for (const name of ["main/app.json", "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,
+      schema: 2,
       cli: AkanAppConfig.akanVersion,
       platform: "macos",
       arch: "arm64",
@@ -151,22 +235,50 @@ describe("DesktopRelease", () => {
     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 () => {
+  test("refuses an envelope no key of the ring signs, or a revoked one, before reading anything it names", async () => {
     const published = await publish();
+    const envelope = path.join(published.dir, "main", "app.json");
+    const untrusted = `${envelope}: the update envelope is signed by key ${key.keyId}, which is not trusted; publish the release again.`;
+
+    await expect(read(published, { publicKeys: [keyOf().publicKey] })).rejects.toThrow(untrusted);
+    await expect(read(published, { revokedKeys: [key.keyId] })).rejects.toThrow(untrusted);
+  });
 
-    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("takes a release a later key signed, and leaves out a v1 pair that is not that release", async () => {
+    const entriesFor = async (published: Published) => {
+      const release = await read(published);
+      return await release.withArchive(release.record(null), async (archive) => entriesOf(archive).slice(0, 4));
+    };
+    const tail = (published: Published) => `./app/${published.tarSha}.tar.gz`;
+
+    const bySpare = await publish({ signer: spare, pair: "earlier" });
+    expect(await entriesFor(bySpare)).toEqual([
+      "./release.json",
+      "./main/app.json",
+      tail(bySpare),
+      `./app/${bySpare.delta}`,
+    ]);
+    const unpaired = await publish({ pair: "none" });
+    expect((await entriesFor(unpaired)).slice(0, 3)).toEqual(["./release.json", "./main/app.json", tail(unpaired)]);
+    const forged = await publish();
+    await writeFile(
+      path.join(forged.dir, "main.json.sig"),
+      spare.sign(await readFile(path.join(forged.dir, "main.json"), "utf8")),
     );
+    expect((await entriesFor(forged)).slice(0, 3)).toEqual(["./release.json", "./main/app.json", tail(forged)]);
   });
 
   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.",
+      "is not a release of com.other target default for macos-arm64 on channel main.",
+    );
+    await expect(read(published, { target: "pilot" })).rejects.toThrow(
+      `is not a release of ${appId} target pilot 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.`,
+      `${path.join(published.dir, "develop", "app.json")} is missing: run \`akan publish-update\` first.`,
     );
     await expect(read(published, { arch: "x64" })).rejects.toThrow("macos-x64");
   });
@@ -178,9 +290,9 @@ describe("DesktopRelease", () => {
     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 expect(send()).rejects.toThrow(`${archive} is not the file main/app.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).`);
+    await expect(send()).rejects.toThrow(`${archive} is not the file main/app.json names (its sha256 differs).`);
   });
 });
 

package/mobile/desktopRelease.ts

@@ -1,4 +1,3 @@
-import { createPublicKey, verify } from "node:crypto";
 import { mkdtemp, readFile, rm } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -7,14 +6,18 @@ import type { UpdateManifest } from "akanjs/native/api";
 import { AkanAppConfig } from "../akanConfig";
 import type { DesktopArch } from "./desktopBin";
 import type { DesktopPlatform } from "./mobileTarget";
+import type { NativeBuildApiModule } from "./nativeApi";
 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. */
+/**
+ * `release.json`, the one file of a desktop release archive `publish-update` did not write. Schema 2: the archive holds
+ * the release's envelope, and its v1 pair only when that is the same release.
+ */
 export interface DesktopReleaseRecord {
-  schema: 1;
+  schema: 2;
   cli: string;
   platform: DesktopPlatform;
   arch: DesktopArch;
@@ -37,10 +40,15 @@ interface DesktopReleasePayload {
   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.
+interface DesktopReleaseManifestFile {
+  name: string;
+  bytes: Uint8Array<ArrayBuffer>;
+}
+
+//* One desktop channel's release as `publish-update` left it in `<updates>/<os>-<arch>/`: the signed envelope, the v1
+//* pair of the same release, and the files the manifest 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'
@@ -56,8 +64,7 @@ Set-Content -LiteralPath $env:AKAN_SIGNER_OUT -Value $subject -Encoding UTF8`;
     readonly platform: DesktopPlatform,
     readonly arch: DesktopArch,
     readonly channel: string,
-    readonly manifestBytes: Uint8Array<ArrayBuffer>,
-    readonly signatureBytes: Uint8Array<ArrayBuffer>,
+    readonly manifestFiles: DesktopReleaseManifestFile[],
   ) {}
 
   static async read(
@@ -67,39 +74,48 @@ Set-Content -LiteralPath $env:AKAN_SIGNER_OUT -Value $subject -Encoding UTF8`;
       arch,
       channel,
       appId,
-      publicKey,
-    }: { platform: DesktopPlatform; arch: DesktopArch; channel: string; appId: string; publicKey: string },
+      target,
+      publicKeys,
+      revokedKeys = [],
+      api,
+    }: {
+      platform: DesktopPlatform;
+      arch: DesktopArch;
+      channel: string;
+      appId: string;
+      target?: string;
+      publicKeys: readonly string[];
+      revokedKeys?: readonly string[];
+      api: Pick<NativeBuildApiModule, "openEnvelope" | "verifyManifest">;
+    },
   ) {
     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);
+    const envelopeName = `${channel}/app.json`;
+    const envelopePath = path.join(dir, channel, "app.json");
+    const envelope = await readFile(envelopePath).catch(() => null);
+    if (!envelope) throw new Error(`${envelopePath} is missing: run \`akan publish-update\` first.`);
+    const opened = DesktopRelease.#open(api, envelope, publicKeys, revokedKeys);
+    if (typeof opened === "string") throw new Error(`${envelopePath}: ${opened}; publish the release again.`);
+    const manifest = DesktopRelease.#parse(opened);
     if (
-      manifest?.schema !== 1 ||
+      manifest?.schema !== 2 ||
       manifest.kind !== "app" ||
       manifest.app !== appId ||
       manifest.platform !== platform ||
       manifest.arch !== arch ||
       manifest.channel !== channel ||
+      manifest.target !== target ||
       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}.`);
+      throw new Error(
+        `${envelopePath} is not a release of ${appId}${target ? ` target ${target}` : ""} for ${folder} on channel ${channel}.`,
+      );
     const { archive, bundle, sequence, build } = manifest;
+    const legacy = await DesktopRelease.#legacyPair(api, dir, channel, publicKeys[0], 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(
@@ -118,19 +134,41 @@ Set-Content -LiteralPath $env:AKAN_SIGNER_OUT -Value $subject -Encoding UTF8`;
       platform,
       arch,
       channel,
-      manifestBytes,
-      signatureBytes,
+      [{ name: envelopeName, bytes: envelope }, ...legacy],
+    );
+  }
+
+  //? An app built before protocol v2 reads the pair, signed with the first key only; a pair of an earlier release is
+  //? left out, since it would publish that release again to those apps.
+  static async #legacyPair(
+    api: Pick<NativeBuildApiModule, "verifyManifest">,
+    dir: string,
+    channel: string,
+    publicKey: string | undefined,
+    manifest: Partial<UpdateManifest>,
+  ): Promise<DesktopReleaseManifestFile[]> {
+    const [bytes, signature] = await Promise.all(
+      [`${channel}.json`, `${channel}.json.sig`].map((name) => readFile(path.join(dir, name)).catch(() => null)),
     );
+    if (!bytes || !signature || !publicKey) return [];
+    const v1 = DesktopRelease.#parse(bytes);
+    if (v1?.schema !== 1 || v1.bundle !== manifest.bundle || v1.sequence !== manifest.sequence) return [];
+    if (!api.verifyManifest(bytes, new TextDecoder().decode(signature).trim(), publicKey)) return [];
+    return [
+      { name: `${channel}.json`, bytes },
+      { name: `${channel}.json.sig`, bytes: signature },
+    ];
   }
 
   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 };
+    return { schema: 2, cli: AkanAppConfig.akanVersion, platform, arch, channel, signer, builtAt };
   }
 
-  //* Uncompressed, regular files only under `./` names, no directory entries; what the manifest names is checked
-  //* against it while it is copied, so the archive holds the bytes the manifest signs for.
+  //* 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, the envelope and the v1 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 {
@@ -138,11 +176,10 @@ Set-Content -LiteralPath $env:AKAN_SIGNER_OUT -Value $subject -Encoding UTF8`;
       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, bytes } of this.manifestFiles) await tar.add(`./${name}`, new Blob([bytes]));
         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`;
+          const what = `${path.join(this.dir, name)} is not the file ${this.channel}/app.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).`);
         }
@@ -169,7 +206,7 @@ Set-Content -LiteralPath $env:AKAN_SIGNER_OUT -Value $subject -Encoding UTF8`;
     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` };
+      return { signer: null, unread: `${this.channel}/app.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")
@@ -227,16 +264,16 @@ Set-Content -LiteralPath $env:AKAN_SIGNER_OUT -Value $subject -Encoding UTF8`;
     return { signer: subject ? { subject } : null, unread: null };
   }
 
-  static #verifies(manifest: Uint8Array, signature: Uint8Array, publicKey: string) {
+  static #open(
+    api: Pick<NativeBuildApiModule, "openEnvelope">,
+    envelope: Uint8Array,
+    publicKeys: readonly string[],
+    revokedKeys: readonly string[],
+  ): Uint8Array | 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;
+      return api.openEnvelope(new TextDecoder().decode(envelope), publicKeys, revokedKeys).manifest;
+    } catch (error) {
+      return toError(error).message;
     }
   }
 

package/mobile/nativeApi.test.ts

@@ -42,6 +42,9 @@ describe("NativeApi", () => {
   });
 
   test("refuses an API older than the one the build calls into, and another major, before anything builds", async () => {
+    await expect(NativeApi.load(await installVendoredApi("0.12.0"))).rejects.toThrow(
+      "install matching versions of akanjs and @akanjs/cli",
+    );
     await expect(NativeApi.load(await installVendoredApi("0.10.0"))).rejects.toThrow(
       "install matching versions of akanjs and @akanjs/cli",
     );
@@ -51,6 +54,6 @@ describe("NativeApi", () => {
     expect((await NativeApi.load(await installVendoredApi(NativeApi.minimumVersion))).API_VERSION).toBe(
       NativeApi.minimumVersion,
     );
-    expect((await NativeApi.load(await installVendoredApi("0.12.0"))).API_VERSION).toBe("0.12.0");
+    expect((await NativeApi.load(await installVendoredApi("0.13.4"))).API_VERSION).toBe("0.13.4");
   });
 });

package/mobile/nativeApi.ts

@@ -6,9 +6,9 @@ export type NativeBuildApiModule = typeof NativeBuildApi;
 export class NativeApi {
   //* The build API versions itself; a major this devkit was not written against is refused before anything builds.
   static readonly supportedMajor = 0;
-  //? An update release's `revoke` and `resetSequence` arrived in 0.12.0, and an older API would publish without them;
-  //? `requestedDistribution` in 0.11.0; akanjs 3.0.x vendors 0.10.0.
-  static readonly minimumVersion = "0.12.0";
+  //? A desktop release's envelope and `updates.target` arrived in 0.13.0, and an older API refuses the key; an update
+  //? release's `revoke` and `resetSequence` in 0.12.0; `requestedDistribution` in 0.11.0; akanjs 3.0.x vendors 0.10.0.
+  static readonly minimumVersion = "0.13.0";
 
   /** The API of the akanjs the app installed: the workspace package inside this repo, akanjs's vendored copy elsewhere. */
   static entryOf(appDir: string): string {

package/mobile/nativeApp.test.ts

@@ -341,8 +341,8 @@ describe("NativeApp", () => {
       (await new NativeApp(fakeApp(), target({ basePath: undefined, updates }), env).config({ platform: "android" }))
         .config.updates;
 
-    expect(await built("main")).toEqual({ ...updates, channel: "main" });
-    expect(await built("debug")).toEqual({ ...updates, channel: "debug" });
+    expect(await built("main")).toEqual({ ...updates, channel: "main", target: "default" });
+    expect(await built("debug")).toEqual({ ...updates, channel: "debug", target: "default" });
   });
 
   test("a desktop app is this computer's platform", () => {

package/mobile/nativeApp.ts

@@ -27,7 +27,7 @@ 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">;
+type ReleaseRevocation = Pick<Parameters<NativeBuildApiModule["checkPublishUpdate"]>[0], "revoke" | "resetSequence">;
 
 export interface NativeRunOptions {
   device?: DeviceSelector;
@@ -315,17 +315,24 @@ export class NativeApp {
   //? 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 [api, { config }] = await Promise.all([
+      NativeApi.load(this.app.cwdPath),
+      this.config({ platform, stageBin: false }),
+    ]);
+    const { updates } = config;
+    const publicKeys = updates?.publicKeys ?? (updates?.publicKey ? [updates.publicKey] : []);
+    if (!updates || !publicKeys.length) 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",
+      channel: channel ?? updates.channel ?? "production",
       appId: config.app.id,
-      publicKey,
+      ...(updates.target ? { target: updates.target } : {}),
+      publicKeys,
+      revokedKeys: updates.revokedKeys ?? [],
+      api,
     });
-    return { release, url: config.updates.url, exeName: config.app.fileName ?? "" };
+    return { release, url: updates.url, exeName: config.app.fileName ?? "" };
   }
 
   /** A signed release installed apps take through the updates plugin, from a release build of this bundle. */
@@ -345,7 +352,7 @@ export class NativeApp {
       arch?: DesktopArch;
       sign?: boolean;
       notarize?: boolean;
-    } & PhoneRevocation = {},
+    } & ReleaseRevocation = {},
   ) {
     NativeApp.#assertServerPlatform(platform, server);
     this.#assertUpdates();
@@ -399,8 +406,8 @@ export class NativeApp {
 
   /**
    * What publishing refuses once the release is built: no updates settings, an invalid config, no signing key or
-   * 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.
+   * another app's, a desktop release whose server presence is not its channel's previous release's, and a release whose
+   * revocations no app would take.
    */
   async assertPublishable(
     platform: NativePlatform,
@@ -410,7 +417,7 @@ export class NativeApp {
       arch,
       revoke,
       resetSequence,
-    }: { channel?: string; server?: boolean; arch?: DesktopArch } & PhoneRevocation = {},
+    }: { channel?: string; server?: boolean; arch?: DesktopArch } & ReleaseRevocation = {},
   ) {
     this.#assertUpdates();
     const [api, { config }] = await Promise.all([

package/mobile/nativeConfig.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, test } from "bun:test";
+import { generateKeyPairSync } from "node:crypto";
 import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 import type { AkanNativeTarget } from "../akanConfig";
@@ -42,7 +43,9 @@ const adminTarget: AkanNativeTarget = {
   },
 };
 
-const updatesKey = Buffer.alloc(32, 7).toString("base64");
+const ed25519Key = () =>
+  generateKeyPairSync("ed25519").publicKey.export({ format: "der", type: "spki" }).subarray(12).toString("base64");
+const updatesKey = ed25519Key();
 
 describe("NativeConfig.build", () => {
   test("hands the dmg window over with its pictures resolved against the app folder", () => {
@@ -224,19 +227,22 @@ describe("NativeConfig.build", () => {
       url,
       publicKey: updatesKey,
       channel: "develop",
+      target: "admin",
     });
     expect(build({ url, publicKey: updatesKey, channel: "beta", readyTimeout: 15_000 }, "main").updates).toEqual({
       url,
       publicKey: updatesKey,
       channel: "beta",
       readyTimeout: 15_000,
+      target: "admin",
     });
-    expect(build({ url, publicKey: updatesKey }).updates).toEqual({ url, publicKey: updatesKey });
-    const spare = Buffer.alloc(32, 8).toString("base64");
+    expect(build({ url, publicKey: updatesKey }).updates).toEqual({ url, publicKey: updatesKey, target: "admin" });
+    const spare = ed25519Key();
     expect(build({ url, publicKeys: [updatesKey, spare] }, "main").updates).toEqual({
       url,
       publicKeys: [updatesKey, spare],
       channel: "main",
+      target: "admin",
     });
     const report = { url: "https://cloud.example.com/api/ota/report/abcdefghijklmnop" };
     expect(build({ url, publicKey: updatesKey, report }, "main").updates).toEqual({
@@ -244,6 +250,7 @@ describe("NativeConfig.build", () => {
       publicKey: updatesKey,
       channel: "main",
       report,
+      target: "admin",
     });
     expect(build({ url, publicKey: updatesKey }, "main").plugins).toContain("updates");
     expect(build(undefined, "main").plugins).not.toContain("updates");
@@ -457,7 +464,7 @@ describe("NativeConfig.build", () => {
     });
 
     expect(config.plugins).toEqual([...NativeConfig.basePlugins, "updates"]);
-    expect(config.updates).toEqual(updates);
+    expect(config.updates).toEqual({ ...updates, target: minimalTarget.name });
   });
 
   test("an updates channel left unnamed is the backend env the binary is built for", () => {
@@ -479,10 +486,11 @@ describe("NativeConfig.build", () => {
         ...(env ? { env } : {}),
       }).config.updates;
 
-    expect(build("debug")).toEqual({ ...updates, channel: "debug" });
-    expect(build("main")).toEqual({ ...updates, channel: "main" });
-    expect(build("debug", "pilot")).toEqual({ ...updates, channel: "pilot" });
-    expect(build()).toEqual(updates);
+    const target = minimalTarget.name;
+    expect(build("debug")).toEqual({ ...updates, channel: "debug", target });
+    expect(build("main")).toEqual({ ...updates, channel: "main", target });
+    expect(build("debug", "pilot")).toEqual({ ...updates, channel: "pilot", target });
+    expect(build()).toEqual({ ...updates, target });
   });
 
   test("keeps a file name the runtime accepts", () => {

package/mobile/nativeConfig.ts

@@ -267,7 +267,7 @@ export class NativeConfig {
   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;
-    return url && keys ? { ...rest, url, ...keys, ...(channel ? { channel } : {}) } : undefined;
+    return url && keys ? { ...rest, url, ...keys, ...(channel ? { channel } : {}), target: target.name } : undefined;
   }
 
   /** Letters, digits, `.`, `_` and `-` only; the folder name of an akan app already is one almost always. */

package/mobile/updateUploader.test.ts

@@ -83,6 +83,40 @@ describe("UpdateUploader", () => {
     );
   });
 
+  test("uploads a desktop release's envelope, with the v1 pair only when the pair is that release", async () => {
+    const manifest = { kind: "app", bundle: "1.3.0-3000", archive: { url: `app/${sha("c")}.tar.gz` }, patches: [] };
+    await inUpdatesDir(
+      {
+        [`macos-arm64/app/${sha("c")}.tar.gz`]: "tar",
+        "macos-arm64/main/app.json": envelope(manifest),
+        "macos-arm64/main.json": JSON.stringify({ ...manifest, bundle: "1.2.0-2000" }),
+        "macos-arm64/main.json.sig": "sig",
+        "macos-arm64/beta/app.json": envelope({ ...manifest, bundle: "1.4.0-4000" }),
+        "macos-arm64/beta.json": JSON.stringify({ ...manifest, bundle: "1.4.0-4000" }),
+        "macos-arm64/beta.json.sig": "sig",
+      },
+      async (updatesDir) => {
+        const dir = path.join(updatesDir, "macos-arm64");
+        const upload = async (channel: string, bundle: string) => {
+          const { bucket, writes } = fakeBucket();
+          await new UpdateUploader(bucket, "").upload(updatesDir, { dir, channel, bundle });
+          return writes.map(({ key }) => key);
+        };
+
+        expect(await upload("main", "1.3.0-3000")).toEqual([
+          `macos-arm64/app/${sha("c")}.tar.gz`,
+          "macos-arm64/main/app.json",
+        ]);
+        expect(await upload("beta", "1.4.0-4000")).toEqual([
+          `macos-arm64/app/${sha("c")}.tar.gz`,
+          "macos-arm64/beta.json.sig",
+          "macos-arm64/beta.json",
+          "macos-arm64/beta/app.json",
+        ]);
+      },
+    );
+  });
+
   test("uploads a phone release's own files and envelope, never pack records or another manifest beside them", async () => {
     await inUpdatesDir(
       {

package/mobile/updateUploader.ts

@@ -51,12 +51,8 @@ export class UpdateUploader {
   //* APIs, which a later publish from another machine may have replaced.
   static async releaseFiles(updatesDir: string, { dir, channel, bundle }: PublishedUpdate): Promise<string[]> {
     const keyOf = (file: unknown) => UpdateUploader.#keyOf(updatesDir, dir, file);
-    const desktop = await UpdateUploader.#read<UpdateManifest>(path.join(dir, `${channel}.json`));
-    if (desktop?.bundle === bundle) {
-      const archive = desktop.archive?.url;
-      const patches = UpdateUploader.#field(desktop.patches, "url");
-      return [archive, ...patches, `${channel}.json.sig`, `${channel}.json`].map(keyOf);
-    }
+    const v1 = await UpdateUploader.#read<UpdateManifest>(path.join(dir, `${channel}.json`));
+    const pair = v1?.bundle === bundle ? [`${channel}.json.sig`, `${channel}.json`] : [];
     const names = await readdir(path.join(dir, channel)).catch(() => [] as string[]);
     for (const name of names.filter((name) => name.endsWith(".json"))) {
       const envelope = await UpdateUploader.#read<UpdateEnvelope>(path.join(dir, channel, name));
@@ -65,6 +61,8 @@ export class UpdateUploader {
           ? UpdateUploader.#parse<UpdateManifest>(Buffer.from(envelope.manifest, "base64").toString("utf8"))
           : null;
       if (manifest?.bundle !== bundle) continue;
+      if (manifest.kind === "app")
+        return [...UpdateUploader.#appFiles(manifest), ...pair, `${channel}/${name}`].map(keyOf);
       const hashes = [...new Set(UpdateUploader.#field(manifest.files, "sha256"))];
       if (!hashes.every((hash): hash is string => typeof hash === "string" && /^[0-9a-f]{64}$/.test(hash)))
         throw new Error(
@@ -72,9 +70,14 @@ export class UpdateUploader {
         );
       return [...hashes.map((hash) => `${UpdatePackFolder.filesDir}/${hash}`), `${channel}/${name}`].map(keyOf);
     }
+    if (v1 && pair.length) return [...UpdateUploader.#appFiles(v1), ...pair].map(keyOf);
     throw new Error(`${dir} holds no ${channel} manifest of release ${bundle}; nothing was uploaded.`);
   }
 
+  static #appFiles(manifest: Partial<UpdateManifest>): unknown[] {
+    return [manifest.archive?.url, ...UpdateUploader.#field(manifest.patches, "url")];
+  }
+
   static #keyOf(updatesDir: string, dir: string, file: unknown) {
     const resolved = typeof file === "string" ? path.resolve(dir, file) : "";
     const key = path.relative(updatesDir, resolved);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.1.1-rc.7",
+  "version": "3.1.1-rc.9",
   "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.7",
+    "akanjs": "3.1.1-rc.9",
     "chalk": "^6.0.1",
     "commander": "^15.0.0",
     "dayjs": "^1.11.23",