akanjs 3.0.0-beta.30 → 3.0.0-beta.32

package/vendor/@akanjs/native/packages/cli/src/lib/macossigning.ts

@@ -0,0 +1,357 @@
+
+
+import { randomBytes } from "node:crypto";
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+import { exec, execOrThrow } from "./exec.ts";
+import { CliError, dim, log } from "./log.ts";
+import { type PlistValue, toPlist } from "./plist.ts";
+import { SigningError } from "./prepare.ts";
+import { type SigningIdentity, validIdentities } from "./signing.ts";
+
+export interface MacosSigning {
+  /** A certificate name ("Developer ID Application: Name (TEAMID)") or its SHA-1, in a keychain already. */
+  identity?: string;
+  /** A .p12 holding the identity: imported into a keychain of its own for the build, then removed. */
+  certificate?: { path: string; password: string };
+}
+
+/** App Store Connect API key (key, keyId, issuer), or a profile `xcrun notarytool store-credentials` saved. */
+export interface MacosNotarization {
+  /** The AuthKey_<id>.p8 file. */
+  key?: string;
+  keyId?: string;
+  /** The issuer id; left out for an individual API key. */
+  issuer?: string;
+  profile?: string;
+}
+
+export interface MacosBuild {
+  signing?: MacosSigning;
+  /** Release builds signed with a Developer ID only. */
+  notarize?: MacosNotarization;
+  /** A .dmg beside the app, with an Applications link; signed and notarized as the app is. */
+  dmg?: boolean;
+}
+
+export type MacosSignature = "adhoc" | "identity" | "development" | "distribution";
+
+export interface ResolvedMacosIdentity {
+  /** The certificate's SHA-1, or "-" for ad hoc. */
+  sign: string;
+  name: string;
+  kind: MacosSignature;
+  teamId?: string;
+  /** Set when the identity lives in a keychain made for this build. */
+  keychain?: string;
+}
+
+/**
+ * Entitlements the hardened runtime needs for the app's own code: Bun's JavaScriptCore writes JIT code, and the
+ * TCC resources the Info.plist asks for are refused to a hardened app that does not claim them.
+ */
+export const RUNTIME_ENTITLEMENTS: Record<string, PlistValue> = {
+  "com.apple.security.cs.allow-jit": true,
+  "com.apple.security.cs.allow-unsigned-executable-memory": true,
+};
+
+const USAGE_ENTITLEMENTS: Record<string, string> = {
+  NSCameraUsageDescription: "com.apple.security.device.camera",
+  NSMicrophoneUsageDescription: "com.apple.security.device.audio-input",
+  NSLocationUsageDescription: "com.apple.security.personal-information.location",
+  NSLocationWhenInUseUsageDescription: "com.apple.security.personal-information.location",
+  NSContactsUsageDescription: "com.apple.security.personal-information.addressbook",
+  NSCalendarsUsageDescription: "com.apple.security.personal-information.calendars",
+  NSPhotoLibraryUsageDescription: "com.apple.security.personal-information.photos-library",
+};
+
+/** The main executable's entitlements: the runtime's, those of the usage texts in `infoPlist`, then the app's own. */
+export function appEntitlements(
+  infoPlist: Record<string, PlistValue>,
+  extra: Record<string, PlistValue> = {},
+): Record<string, PlistValue> {
+  const out: Record<string, PlistValue> = { ...RUNTIME_ENTITLEMENTS };
+  for (const key of Object.keys(infoPlist)) {
+    const entitlement = USAGE_ENTITLEMENTS[key];
+    if (entitlement) out[entitlement] = true;
+  }
+  return { ...out, ...extra };
+}
+
+/**
+ * The kind of a certificate by its name. A Developer ID's parentheses hold the team id; an Apple Development
+ * certificate's hold the member's own id, so its team is not read from the name.
+ */
+export function identityKind(name: string): { kind: MacosSignature; teamId?: string } {
+  if (name.startsWith("Developer ID Application:")) {
+    const teamId = /\(([A-Z0-9]{10})\)\s*$/.exec(name)?.[1];
+    return { kind: "distribution", ...(teamId ? { teamId } : {}) };
+  }
+  if (name.startsWith("Apple Development:") || name.startsWith("Mac Developer:")) return { kind: "development" };
+  return { kind: "identity" };
+}
+
+/** The identity `wanted` names (a name or a SHA-1) among `identities`. */
+export function pickMacosIdentity(identities: SigningIdentity[], wanted: string): SigningIdentity {
+  const upper = wanted.toUpperCase();
+  const found = identities.filter((i) => i.hash === upper || i.name === wanted);
+  const [only, ...more] = found;
+  if (only && more.length === 0) return only;
+  if (more.length)
+    throw new SigningError(`several valid identities are called ${JSON.stringify(wanted)}; give its SHA-1 instead`);
+  throw new SigningError(
+    `no valid code-signing identity ${JSON.stringify(wanted)} in the keychains`,
+    identities.map((i) => i.name),
+  );
+}
+
+/**
+ * Runs `fn` with the identity `signing` names, or ad hoc without one. A certificate file goes into a keychain made for
+ * this build (on the user's search list meanwhile, so codesign finds its chain), deleted afterwards.
+ */
+export async function withMacosIdentity<T>(
+  signing: MacosSigning | undefined,
+  fn: (identity: ResolvedMacosIdentity) => Promise<T>,
+  fallback: () => Promise<ResolvedMacosIdentity>,
+): Promise<T> {
+  if (!signing?.certificate) {
+    if (!signing?.identity) return fn(await fallback());
+    const picked = pickMacosIdentity(await validIdentities(), signing.identity);
+    return fn({ sign: picked.hash, name: picked.name, ...identityKind(picked.name) });
+  }
+  const dir = mkdtempSync(join(tmpdir(), "akan-native-macos-signing-"));
+  const keychain = join(dir, "signing.keychain-db");
+  const password = randomBytes(24).toString("hex");
+  const before = await searchList();
+  try {
+    await security(["create-keychain", "-p", password, keychain]);
+    await security(["set-keychain-settings", "-lut", "21600", keychain]);
+    await security(["unlock-keychain", "-p", password, keychain]);
+
+    await security(
+      [
+        "import",
+        signing.certificate.path,
+        "-k",
+        keychain,
+        "-P",
+        signing.certificate.password,
+        "-T",
+        "/usr/bin/codesign",
+      ],
+      `the certificate ${signing.certificate.path} could not be imported (is the password right?)`,
+    );
+    
+    await security(["set-key-partition-list", "-S", "apple-tool:,apple:,codesign:", "-s", "-k", password, keychain]);
+    await security(["list-keychains", "-d", "user", "-s", keychain, ...before]);
+    const identities = await validIdentities(keychain);
+    const picked = signing.identity
+      ? pickMacosIdentity(identities, signing.identity)
+      : (identities.find((i) => identityKind(i.name).kind === "distribution") ?? identities[0]);
+    if (!picked) throw new SigningError(`${signing.certificate.path} holds no valid code-signing identity`);
+    return await fn({ sign: picked.hash, name: picked.name, keychain, ...identityKind(picked.name) });
+  } finally {
+    await exec(["/usr/bin/security", "list-keychains", "-d", "user", "-s", ...before], { echo: false });
+    await exec(["/usr/bin/security", "delete-keychain", keychain], { echo: false });
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+async function searchList(): Promise<string[]> {
+  const out = (await exec(["/usr/bin/security", "list-keychains", "-d", "user"], { echo: false })).stdout;
+  return [...out.matchAll(/"([^"]+)"/g)].flatMap((m) => (m[1] ? [m[1]] : []));
+}
+
+/** A `security` call whose failure never repeats its arguments: some carry a password. */
+async function security(args: string[], failure?: string): Promise<void> {
+  const result = await exec(["/usr/bin/security", ...args], { echo: false });
+  if (result.code !== 0)
+    throw new SigningError(failure ?? `security ${args[0]} failed: ${(result.stderr || result.stdout).trim()}`);
+}
+
+export interface CodesignOptions {
+  /** The hardened runtime and a secure timestamp, what notarization requires of every Mach-O file. */
+  hardened: boolean;
+  /** A secure timestamp without the runtime (a disk image). Default: `hardened`. */
+  timestamp?: boolean;
+  entitlements?: string;
+}
+
+/** codesign arguments for one file. Apple's timestamp server only stamps certificates Apple issued. */
+export function codesignArgs(identity: ResolvedMacosIdentity, file: string, options: CodesignOptions): string[] {
+  const timestamp = identity.sign !== "-" && (options.timestamp ?? options.hardened);
+  return [
+    "codesign",
+    "--force",
+    "--sign",
+    identity.sign,
+    ...(identity.keychain ? ["--keychain", identity.keychain] : []),
+    ...(timestamp ? ["--timestamp"] : []),
+    ...(options.hardened && identity.sign !== "-" ? ["--options", "runtime"] : []),
+    ...(options.entitlements ? ["--entitlements", options.entitlements] : []),
+    file,
+  ];
+}
+
+export async function codesign(identity: ResolvedMacosIdentity, file: string, options: CodesignOptions): Promise<void> {
+  const result = await exec(codesignArgs(identity, file, options), { echo: false });
+  if (result.code !== 0)
+    throw new SigningError(
+      `codesign with "${identity.name}" failed for ${basename(file)}: ${(result.stderr || result.stdout).trim()}`,
+    );
+}
+
+export function writeEntitlements(dir: string, entitlements: Record<string, PlistValue>): string {
+  mkdirSync(dir, { recursive: true });
+  const file = join(dir, "entitlements.plist");
+  writeFileSync(file, toPlist(entitlements));
+  return file;
+}
+
+export function notarytoolAuth(notarization: MacosNotarization): string[] {
+  if (notarization.profile) return ["--keychain-profile", notarization.profile];
+  if (!notarization.key || !notarization.keyId)
+    throw new SigningError(
+      "notarization needs an App Store Connect API key (key, keyId and, for a team key, issuer) or a keychain profile",
+    );
+  return [
+    "--key",
+    notarization.key,
+    "--key-id",
+    notarization.keyId,
+    ...(notarization.issuer ? ["--issuer", notarization.issuer] : []),
+  ];
+}
+
+interface NotarySubmission {
+  id?: string;
+  status?: string;
+  message?: string;
+}
+
+/** Submits `file` (a .zip, .dmg or .pkg), waits for Apple's verdict and refuses anything but Accepted. */
+export async function notarize(file: string, notarization: MacosNotarization): Promise<string> {
+  const auth = notarytoolAuth(notarization);
+  log.step(`notarize: ${basename(file)}`);
+  const result = await exec(["xcrun", "notarytool", "submit", file, ...auth, "--wait", "--output-format", "json"], {
+    echo: false,
+  });
+  const submission = parseSubmission(result.stdout);
+  if (submission.status === "Accepted" && submission.id) {
+    log.info(dim(`notarized: ${submission.id}`));
+    return submission.id;
+  }
+  const issues = submission.id ? await notaryIssues(submission.id, auth) : [];
+  throw new SigningError(
+    `notarization of ${basename(file)} ended ${submission.status ?? "without a verdict"}${submission.message ? `: ${submission.message}` : ""}${result.code !== 0 && !submission.status ? `\n${(result.stderr || result.stdout).trim()}` : ""}`,
+    issues,
+  );
+}
+
+export function parseSubmission(stdout: string): NotarySubmission {
+  try {
+    return JSON.parse(stdout) as NotarySubmission;
+  } catch {
+    return {};
+  }
+}
+
+async function notaryIssues(id: string, auth: string[]): Promise<string[]> {
+  const result = await exec(["xcrun", "notarytool", "log", id, ...auth], { echo: false });
+  return notaryLogIssues(result.stdout);
+}
+
+/** One line per issue of a notarytool log: the file and Apple's message. */
+export function notaryLogIssues(stdout: string): string[] {
+  try {
+    const parsed = JSON.parse(stdout) as { issues?: { path?: string; message?: string }[] | null };
+    return (parsed.issues ?? []).map((i) => `${i.path ?? "?"}: ${i.message ?? ""}`.trim());
+  } catch {
+    return [];
+  }
+}
+
+export async function staple(file: string): Promise<void> {
+  await execOrThrow(["xcrun", "stapler", "staple", file], { echo: false });
+}
+
+/** The .app as notarytool takes it: a zip that keeps the bundle's symlinks and signature. */
+export async function zipForNotary(appPath: string, zip: string): Promise<void> {
+  rmSync(zip, { force: true });
+  await execOrThrow(["ditto", "-c", "-k", "--sequesterRsrc", "--keepParent", appPath, zip], { echo: false });
+}
+
+/** A compressed disk image of the app beside a link to /Applications, the window people drag it into. */
+export async function buildDmg(appPath: string, dmgPath: string, volumeName: string, workDir: string): Promise<void> {
+  const staging = join(workDir, "dmg");
+  rmSync(staging, { recursive: true, force: true });
+  mkdirSync(staging, { recursive: true });
+  await execOrThrow(["ditto", appPath, join(staging, basename(appPath))], { echo: false });
+  symlinkSync("/Applications", join(staging, "Applications"));
+  rmSync(dmgPath, { force: true });
+  await execOrThrow(
+    [
+      "hdiutil",
+      "create",
+      "-volname",
+      volumeName,
+      "-srcfolder",
+      staging,
+      "-ov",
+      "-fs",
+      "HFS+",
+      "-format",
+      "UDZO",
+      dmgPath,
+    ],
+    { echo: false },
+  );
+  rmSync(staging, { recursive: true, force: true });
+}
+
+/** What Gatekeeper says of a notarized app or disk image, as a downloaded copy would be judged. */
+export async function assessGatekeeper(file: string, type: "execute" | "open"): Promise<void> {
+  const args =
+    type === "execute"
+      ? ["spctl", "--assess", "--type", "execute", "-vv", file]
+      : ["spctl", "--assess", "--type", "open", "--context", "context:primary-signature", "-vv", file];
+  const result = await exec(args, { echo: false });
+  if (result.code !== 0)
+    throw new CliError(`Gatekeeper refuses ${basename(file)}: ${(result.stderr || result.stdout).trim()}`);
+}
+
+/**
+ * Settings from the environment for the command line (the API takes them as options only):
+ * AKAN_NATIVE_MACOS_IDENTITY, AKAN_NATIVE_MACOS_CERTIFICATE + _PASSWORD, and AKAN_NATIVE_MACOS_NOTARY_KEY +
+ * _KEY_ID + _ISSUER or AKAN_NATIVE_MACOS_NOTARY_PROFILE.
+ */
+export function macosDistributionFromEnv(
+  env: Record<string, string | undefined> = process.env,
+): Pick<MacosBuild, "signing" | "notarize"> {
+  const identity = env.AKAN_NATIVE_MACOS_IDENTITY?.trim();
+  const certificate = env.AKAN_NATIVE_MACOS_CERTIFICATE?.trim();
+  if (certificate && env.AKAN_NATIVE_MACOS_CERTIFICATE_PASSWORD === undefined)
+    throw new SigningError("AKAN_NATIVE_MACOS_CERTIFICATE is set without AKAN_NATIVE_MACOS_CERTIFICATE_PASSWORD");
+  const signing: MacosSigning | undefined =
+    identity || certificate
+      ? {
+          ...(identity ? { identity } : {}),
+          ...(certificate
+            ? { certificate: { path: certificate, password: env.AKAN_NATIVE_MACOS_CERTIFICATE_PASSWORD ?? "" } }
+            : {}),
+        }
+      : undefined;
+  const profile = env.AKAN_NATIVE_MACOS_NOTARY_PROFILE?.trim();
+  const key = env.AKAN_NATIVE_MACOS_NOTARY_KEY?.trim();
+  const keyId = env.AKAN_NATIVE_MACOS_NOTARY_KEY_ID?.trim();
+  const issuer = env.AKAN_NATIVE_MACOS_NOTARY_ISSUER?.trim();
+  if (key && !keyId)
+    throw new SigningError("AKAN_NATIVE_MACOS_NOTARY_KEY is set without AKAN_NATIVE_MACOS_NOTARY_KEY_ID");
+  const notarize: MacosNotarization | undefined = profile
+    ? { profile }
+    : key && keyId
+      ? { key, keyId, ...(issuer ? { issuer } : {}) }
+      : undefined;
+  return { ...(signing ? { signing } : {}), ...(notarize ? { notarize } : {}) };
+}

package/vendor/@akanjs/native/packages/cli/src/lib/prepare.ts

@@ -9,7 +9,10 @@ import { ENV_TYPES_FILE, loadEnv, writeEnvTypes } from "./env.ts";
 import { exec } from "./exec.ts";
 import { findExternalScripts, injectEarlyErrors, injectInitScript } from "./html.ts";
 import { CliError, dim, log } from "./log.ts";
+import type { MacosBuild } from "./macossigning.ts";
 import { buildNumberProblem, ConfigError, dependencyProblems, type Project } from "./project.ts";
+import { type DesktopArch, hostArch } from "./updates.ts";
+import type { WindowsSigning } from "./windowssigning.ts";
 
 /**
  * debug: inspectable webview, dev signing, runtime env overrides, the dev server (akan-native run, dev,
@@ -28,6 +31,8 @@ const DEV_SERVER_PAGE = `<!doctype html>
 
 export interface WindowsBuild {
   installer?: boolean;
+  /** Authenticode for every PE file, the setup program and its uninstaller (lib/windowssigning.ts). */
+  signing?: WindowsSigning;
 }
 
 export interface BuildOptions {
@@ -63,6 +68,16 @@ export interface BuildOptions {
   ios?: IosBuild;
   /** Windows: an NSIS setup program next to the app folder (platforms/windows-installer.ts). */
   windows?: WindowsBuild;
+  /** macOS: Developer ID signing, notarization and a dmg (lib/macossigning.ts). */
+  macos?: MacosBuild;
+  /** Linux: an AppImage beside the app folder (platforms/linux-appimage.ts). */
+  linux?: LinuxBuild;
+  /** Desktop builds: the CPU the app runs on, of the same OS; a macOS app is arm64 only. Default this computer's. */
+  arch?: DesktopArch;
+}
+
+export interface LinuxBuild {
+  appImage?: boolean;
 }
 
 /** Which identity and profile an iOS device build signs with; unset: found in the keychain and Xcode's profiles. */
@@ -145,10 +160,14 @@ export interface BuildContext {
   android?: AndroidRelease;
   ios?: IosBuild;
   windows?: WindowsBuild;
+  macos?: MacosBuild;
+  linux?: LinuxBuild;
+  /** Desktop builds: see BuildOptions.arch, resolved. */
+  arch?: DesktopArch;
   /** Artifacts besides the one the builder returns (an .aab next to the .apk, a Windows setup program). */
   artifacts: { kind: "aab" | "ipa" | "installer"; path: string }[];
   /** What the builder signed with, when it signs (Android: the app's release key or the debug key). */
-  signedAs?: "debug" | "development" | "distribution";
+  signedAs?: "adhoc" | "debug" | "development" | "distribution";
   /** Called through the API (BuildOptions.api). */
   api: boolean;
   /** Android builds with pinned libraries: the license notices file written next to the app (BuildResult.licenses). */
@@ -179,6 +198,7 @@ export async function prepare(project: Project, platform: Platform, options: Bui
   if (buildProblem) throw new ConfigError("the build number", [buildProblem]);
   const needs = dependencyProblems(project.plugins, platform);
   if (needs.length) throw new CliError(`plugin dependencies on ${platform}:\n  - ${needs.join("\n  - ")}`);
+  const arch = desktopArch(platform, options.arch);
 
   if (config.web.build && !options.skipWebBuild) {
     log.step(`web build: ${config.web.build}`);
@@ -279,10 +299,23 @@ export async function prepare(project: Project, platform: Platform, options: Bui
     ...(options.android ? { android: options.android } : {}),
     ...(options.ios ? { ios: options.ios } : {}),
     ...(options.windows ? { windows: options.windows } : {}),
+    ...(options.macos ? { macos: options.macos } : {}),
+    ...(options.linux ? { linux: options.linux } : {}),
+    ...(arch ? { arch } : {}),
     artifacts: [],
   };
 }
 
+/** The arch a build makes: the one asked for, checked against the platform, else this computer's for a desktop. */
+export function desktopArch(platform: Platform, arch: DesktopArch | undefined): DesktopArch | undefined {
+  const desktop = platform === "macos" || platform === "windows" || platform === "linux";
+  if (arch !== undefined && !desktop) throw new CliError(`a CPU is chosen for a desktop build, not for ${platform}`);
+  if (arch !== undefined && arch !== "arm64" && arch !== "x64")
+    throw new CliError(`the arch is arm64 or x64 (got ${JSON.stringify(arch)})`);
+  if (platform === "macos" && arch === "x64") throw new CliError("a macOS app is built for Apple silicon (arm64) only");
+  return arch ?? (desktop ? hostArch() : undefined);
+}
+
 /** https, or http to this machine (a local test server, `akan-native update serve`). */
 export function secureUpdateUrl(url: string): boolean {
   try {

package/vendor/@akanjs/native/packages/cli/src/lib/project.ts

@@ -685,6 +685,7 @@ function checkNative(raw: AkanNativeConfig, appDir: string, problems: string[]):
   };
   dict("native.ios.infoPlist", native.ios?.infoPlist);
   dict("native.ios.entitlements", native.ios?.entitlements);
+  dict("native.macos.entitlements", native.macos?.entitlements);
   for (const key of ["manifest", "application", "activity"] as const) {
     const xml = native.android?.[key];
     if (

package/vendor/@akanjs/native/packages/cli/src/lib/signing.ts

@@ -18,9 +18,10 @@ const LOGIN_KEYCHAIN = join(userInfo().homedir, "Library", "Keychains", "login.k
 export const identityName = () => `akan-native dev: ${userInfo().username}`;
 const recordPath = (env = process.env) => join(akanNativeHome(env), "signing.json");
 
-/** Valid (trusted) code-signing identities in the keychains. */
-export async function validIdentities(): Promise<SigningIdentity[]> {
-  const out = (await exec(["/usr/bin/security", "find-identity", "-v", "-p", "codesigning"], { echo: false })).stdout;
+/** Valid (trusted) code-signing identities in the keychains, or in `keychain` only. */
+export async function validIdentities(keychain?: string): Promise<SigningIdentity[]> {
+  const args = ["/usr/bin/security", "find-identity", "-v", "-p", "codesigning", ...(keychain ? [keychain] : [])];
+  const out = (await exec(args, { echo: false })).stdout;
   return [...out.matchAll(/\d+\) ([0-9A-F]{40}) "([^"]+)"/g)].map((m) => ({ hash: m[1]!, name: m[2]! }));
 }
 

package/vendor/@akanjs/native/packages/cli/src/lib/toolchains.ts

@@ -80,6 +80,30 @@ export const TOOLCHAIN = {
       root: "bundletool.jar",
     } satisfies Download,
   },
+  /**
+   * The AppImage type 2 runtime (CLI-9), the ELF a Linux AppImage starts with: it mounts the squashfs appended to it
+   * and runs its AppRun. A dated release, since `continuous` moves; the digests are the ones GitHub publishes.
+   */
+  appimageRuntime: {
+    version: "20251108",
+    license: "MIT",
+    downloads: {
+      x64: {
+        url: "https://github.com/AppImage/type2-runtime/releases/download/20251108/runtime-x86_64",
+        sha256: "2fca8b443c92510f1483a883f60061ad09b46b978b2631c807cd873a47ec260d",
+        size: 944_632,
+        format: "file",
+        root: "runtime",
+      },
+      arm64: {
+        url: "https://github.com/AppImage/type2-runtime/releases/download/20251108/runtime-aarch64",
+        sha256: "00cbdfcf917cc6c0ff6d3347d59e0ca1f7f45a6df1a428a0d6d8a78664d87444",
+        size: 936_456,
+        format: "file",
+        root: "runtime",
+      },
+    } as Record<string, Download>,
+  },
   android: {
     buildTools: "37.0.0",
     /** Older build-tools still work (with a warning); below this they do not. */

package/vendor/@akanjs/native/packages/cli/src/lib/windowssigning.ts

@@ -0,0 +1,155 @@
+
+
+import { closeSync, existsSync, openSync, readdirSync, readSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+import { exec } from "./exec.ts";
+import { ToolchainError } from "./log.ts";
+import { SigningError } from "./prepare.ts";
+
+export interface WindowsSigning {
+  /** A .pfx holding the code-signing certificate and its key. */
+  certificate?: { path: string; password: string };
+  /** A certificate in the user's or the machine's store, by its SHA-1 thumbprint (a token or an HSM keeps its key there). */
+  thumbprint?: string;
+  /** Any other signer, run once per file with `{file}` replaced, e.g. signtool with Azure Trusted Signing's dlib. */
+  command?: string[];
+  /** RFC 3161 timestamp server. Default http://timestamp.digicert.com. */
+  timestampUrl?: string;
+}
+
+export const DEFAULT_TIMESTAMP_URL = "http://timestamp.digicert.com";
+
+/** signtool: AKAN_NATIVE_SIGNTOOL, PATH, then the newest Windows 10/11 SDK's for this CPU. */
+export function findSigntool(env: Record<string, string | undefined> = process.env): string | null {
+  if (env.AKAN_NATIVE_SIGNTOOL) return env.AKAN_NATIVE_SIGNTOOL;
+  const onPath = Bun.which("signtool");
+  if (onPath) return onPath;
+  const kits = env["ProgramFiles(x86)"] ? join(env["ProgramFiles(x86)"], "Windows Kits", "10", "bin") : null;
+  if (!kits || !existsSync(kits)) return null;
+  const arch = process.arch === "arm64" ? "arm64" : "x64";
+  const versions = readdirSync(kits)
+    .filter((name) => /^10\.\d+\.\d+\.\d+$/.test(name))
+    .sort((a, b) => compareVersions(b, a));
+  for (const version of versions) {
+    const candidate = join(kits, version, arch, "signtool.exe");
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+function compareVersions(a: string, b: string): number {
+  const [x, y] = [a.split(".").map(Number), b.split(".").map(Number)];
+  for (let i = 0; i < Math.max(x.length, y.length); i++)
+    if ((x[i] ?? 0) !== (y[i] ?? 0)) return (x[i] ?? 0) - (y[i] ?? 0);
+  return 0;
+}
+
+/** signtool's arguments after the executable, for `files` in one call. */
+export function signtoolArgs(signing: WindowsSigning, files: string[], description: string): string[] {
+  const key = signing.certificate
+    ? ["/f", signing.certificate.path, "/p", signing.certificate.password]
+    : signing.thumbprint
+      ? ["/sha1", signing.thumbprint]
+      : null;
+  if (!key) throw new SigningError("Windows signing needs a certificate (.pfx), a thumbprint or a command");
+  return [
+    "sign",
+    "/fd",
+    "sha256",
+    "/tr",
+    signing.timestampUrl ?? DEFAULT_TIMESTAMP_URL,
+    "/td",
+    "sha256",
+    "/d",
+    description,
+    ...key,
+    ...files,
+  ];
+}
+
+/** The command a `command` signer runs for one file. */
+export function signerCommand(command: string[], file: string): string[] {
+  if (!command.some((part) => part.includes("{file}"))) return [...command, file];
+  return command.map((part) => part.replaceAll("{file}", file));
+}
+
+/** Signs `files` (Authenticode, SHA-256, timestamped), then verifies each against the system's trusted roots. */
+export async function signWindowsFiles(signing: WindowsSigning, files: string[], description: string): Promise<void> {
+  if (!files.length) return;
+  if (signing.command) {
+    for (const file of files) {
+      const result = await exec(signerCommand(signing.command, file), { echo: false });
+      if (result.code !== 0)
+        throw new SigningError(`the signing command failed for ${basename(file)}: ${tail(result)}`);
+    }
+  } else {
+    const signtool = findSigntool();
+    if (!signtool)
+      throw new ToolchainError(
+        "signtool signs Windows programs: install the Windows SDK's Signing Tools (winget install Microsoft.WindowsSDK.10.0.26100) or set AKAN_NATIVE_SIGNTOOL",
+      );
+    
+    const result = await exec([signtool, ...signtoolArgs(signing, files, description)], { echo: false });
+    if (result.code !== 0) throw new SigningError(`signtool could not sign ${files.length} files: ${tail(result)}`);
+    const verified = await exec([signtool, "verify", "/pa", "/q", ...files], { echo: false });
+    if (verified.code !== 0) throw new SigningError(`signtool verify refuses the signed files: ${tail(verified)}`);
+  }
+}
+
+const tail = (result: { stdout: string; stderr: string }) =>
+  (result.stderr || result.stdout).trim().split("\n").slice(-10).join("\n");
+
+/** Every PE file under `dir` (programs, DLLs, native addons), whatever its name. */
+export function peFiles(dir: string): string[] {
+  if (!existsSync(dir)) return [];
+  return (readdirSync(dir, { recursive: true }) as string[])
+    .map((file) => join(dir, file))
+    .filter((file) => statSync(file).isFile() && isPe(file));
+}
+
+function isPe(file: string): boolean {
+  const head = Buffer.alloc(2);
+  const fd = openSync(file, "r");
+  try {
+    return readSync(fd, head, 0, 2, 0) === 2 && head.readUInt16LE(0) === 0x5a4d;
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/**
+ * Settings from the environment (the API takes them as options only): AKAN_NATIVE_WINDOWS_CERTIFICATE + _PASSWORD,
+ * AKAN_NATIVE_WINDOWS_THUMBPRINT, or AKAN_NATIVE_WINDOWS_SIGN_COMMAND (a JSON array of arguments, `{file}` replaced),
+ * and AKAN_NATIVE_WINDOWS_TIMESTAMP_URL.
+ */
+export function windowsSigningFromEnv(
+  env: Record<string, string | undefined> = process.env,
+): WindowsSigning | undefined {
+  const certificate = env.AKAN_NATIVE_WINDOWS_CERTIFICATE?.trim();
+  const thumbprint = env.AKAN_NATIVE_WINDOWS_THUMBPRINT?.replace(/\s/g, "");
+  const rawCommand = env.AKAN_NATIVE_WINDOWS_SIGN_COMMAND?.trim();
+  const timestampUrl = env.AKAN_NATIVE_WINDOWS_TIMESTAMP_URL?.trim();
+  if (certificate && env.AKAN_NATIVE_WINDOWS_CERTIFICATE_PASSWORD === undefined)
+    throw new SigningError("AKAN_NATIVE_WINDOWS_CERTIFICATE is set without AKAN_NATIVE_WINDOWS_CERTIFICATE_PASSWORD");
+  let command: string[] | undefined;
+  if (rawCommand) {
+    try {
+      command = JSON.parse(rawCommand) as string[];
+    } catch {
+      command = undefined;
+    }
+    if (!Array.isArray(command) || !command.length || command.some((part) => typeof part !== "string"))
+      throw new SigningError(
+        'AKAN_NATIVE_WINDOWS_SIGN_COMMAND must be a JSON array of strings, e.g. ["signer", "{file}"]',
+      );
+  }
+  if (!certificate && !thumbprint && !command) return undefined;
+  return {
+    ...(certificate
+      ? { certificate: { path: certificate, password: env.AKAN_NATIVE_WINDOWS_CERTIFICATE_PASSWORD ?? "" } }
+      : {}),
+    ...(thumbprint ? { thumbprint } : {}),
+    ...(command ? { command } : {}),
+    ...(timestampUrl ? { timestampUrl } : {}),
+  };
+}