pakstr 0.29.0 → 0.30.0

package/README.md

@@ -95,6 +95,16 @@ containers alike, because all of them are created the same way. Leave it unset o
 workstation, where Docker's default network is what you want - host networking is not
 available on Docker Desktop for macOS.
 
+**Timeouts.** So a stalled build or an unresponsive Docker daemon fails instead of hanging
+the job, the Gradle build and the builder image pull are stopped after 60 minutes, signing
+after 15, file copies into and out of containers after 10, and other Docker calls after 2.
+Containers left by a stopped or failed run are removed. If a cold build on a slow runner needs
+longer, raise the build limit with `PAKSTR_BUILD_TIMEOUT_MINUTES` (`0` disables it):
+
+```bash
+PAKSTR_BUILD_TIMEOUT_MINUTES=120 npx pakstr run
+```
+
 ---
 
 ## Documentation & License

package/android-template/app/src/debug/AndroidManifest.xml

@@ -1,6 +1,9 @@
 <?xml version="1.0" encoding="utf-8"?>
-<manifest xmlns:android="http://schemas.android.com/apk/res/android">
-    <application>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:tools="http://schemas.android.com/tools">
+    <application
+        android:memtagMode="sync"
+        tools:replace="android:memtagMode">
         <activity-alias
             android:name=".debug.DeveloperToolsDebugLauncher"
             android:enabled="true"

package/android-template/app/src/main/AndroidManifest.xml

@@ -23,6 +23,7 @@
         android:fullBackupContent="@xml/backup_rules"
         android:icon="@mipmap/ic_launcher"
         android:label="@string/app_name"
+        android:memtagMode="async"
         android:networkSecurityConfig="@xml/network_security_config"
         android:roundIcon="@mipmap/ic_launcher_round"
         android:supportsRtl="true"

package/dist/cli.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runCLI = runCLI;
+const path_1 = __importDefault(require("path"));
 const build_1 = require("./commands/build");
 const sign_1 = require("./commands/sign");
 const publish_1 = require("./commands/publish");
@@ -15,9 +16,14 @@ const deletePublisher_1 = require("./commands/deletePublisher");
 const dotenv_1 = require("./core/dotenv");
 const package_json_1 = __importDefault(require("../package.json"));
 async function runCLI(argv) {
-    // Auto-load a local `.env` (gitignored) so `pakstr run` works out of the box
-    // after `pakstr init`. Existing env vars (e.g. CI secrets) always win.
-    (0, dotenv_1.loadDotEnv)();
+    const command = argv[0];
+    const args = argv.slice(1);
+    const configFlag = extractFlag(args, "--config");
+    // Auto-load the `.env` (gitignored) next to the config file, where
+    // `pakstr init` writes it, so `pakstr run` works out of the box. Without
+    // --config that is the current directory. Existing env vars (e.g. CI
+    // secrets) always win.
+    (0, dotenv_1.loadDotEnv)(configDir(configFlag));
     if (argv.includes("--help") || argv.includes("-h")) {
         printHelp();
         return;
@@ -26,13 +32,10 @@ async function runCLI(argv) {
         console.log(package_json_1.default.version);
         return;
     }
-    const command = argv[0];
-    const args = argv.slice(1);
     if (!command) {
         printHelp();
         return;
     }
-    const configFlag = extractFlag(args, "--config");
     switch (command) {
         case "init":
             await (0, init_1.initCommand)({ force: args.includes("--force"), out: configFlag });
@@ -99,6 +102,10 @@ function extractFlag(args, flag) {
         return undefined;
     return args[i + 1];
 }
+/** Directory of the config file, resolved the same way as loadPakstrConfig. */
+function configDir(configFlag) {
+    return configFlag ? path_1.default.dirname(path_1.default.resolve(configFlag)) : process.cwd();
+}
 function printHelp() {
     console.log(`
 Pakstr — one-step nsec -> build -> sign -> publish.

package/dist/commands/artifactPublisher.js

@@ -0,0 +1,125 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stageArtifact = stageArtifact;
+exports.publishArtifact = publishArtifact;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+/**
+ * Copy `artifactPath` into a fresh staging directory next to `finalPath`, so
+ * publishArtifact can move it into place with a same-filesystem rename.
+ * Returns the staged path; the staging directory is removed on failure.
+ * `description` names the artifact in errors (e.g. "built APK").
+ */
+function stageArtifact(artifactPath, finalPath, description = "built APK") {
+    const parent = path_1.default.dirname(finalPath);
+    const stageDir = fs_1.default.mkdtempSync(path_1.default.join(parent, ".pakstr-stage-"));
+    const stagedPath = path_1.default.join(stageDir, "app.apk");
+    try {
+        fs_1.default.copyFileSync(artifactPath, stagedPath, fs_1.default.constants.COPYFILE_EXCL);
+        if (fs_1.default.statSync(stagedPath).size !== fs_1.default.statSync(artifactPath).size) {
+            throw new Error(`Staged copy of the ${description} is incomplete (size mismatch); ` +
+                "the existing output was left unchanged");
+        }
+    }
+    catch (error) {
+        fs_1.default.rmSync(stageDir, { recursive: true, force: true });
+        throw error;
+    }
+    return stagedPath;
+}
+/**
+ * Publish a staged APK at `finalPath` without ever leaving the user without
+ * their previous APK.
+ *
+ * The previous APK is copied into the staging directory, then the staged APK
+ * atomically replaces `finalPath` (it is never deleted first). If publication
+ * fails, the previous APK is restored from the backup. The staging directory
+ * (which holds the backup) is only removed once `finalPath` is known to hold a
+ * good APK; if restoring fails it is kept so the backup is never lost.
+ */
+function publishArtifact(stagedPath, finalPath) {
+    const stageDir = path_1.default.dirname(stagedPath);
+    const backupPath = path_1.default.join(stageDir, "previous.apk");
+    if (isInside(path_1.default.resolve(finalPath), path_1.default.resolve(stageDir))) {
+        throw new Error(`Staging directory must not contain the output APK: ${stageDir}`);
+    }
+    let hadPreviousOutput;
+    try {
+        hadPreviousOutput = existingOutputIsFile(finalPath);
+        if (hadPreviousOutput) {
+            fs_1.default.copyFileSync(finalPath, backupPath, fs_1.default.constants.COPYFILE_EXCL);
+            if (fs_1.default.statSync(backupPath).size !== fs_1.default.statSync(finalPath).size) {
+                throw new Error("Backup of the previous APK is incomplete");
+            }
+        }
+    }
+    catch (error) {
+        // `finalPath` has not been touched yet, so the staging directory holds
+        // nothing worth keeping.
+        removeStageDir(stageDir);
+        throw error;
+    }
+    let replacedOutput = false;
+    try {
+        fs_1.default.renameSync(stagedPath, finalPath);
+        replacedOutput = true;
+        const stat = fs_1.default.lstatSync(finalPath);
+        if (!stat.isFile() || stat.isSymbolicLink()) {
+            throw new Error("Final APK publication failed");
+        }
+    }
+    catch (error) {
+        try {
+            restorePreviousOutput(finalPath, backupPath, hadPreviousOutput, replacedOutput);
+        }
+        catch (restoreError) {
+            throw new Error(`Failed to publish the new APK and restore the previous APK. ` +
+                `Previous APK kept at: ${backupPath}`, { cause: new AggregateError([error, restoreError]) });
+        }
+        removeStageDir(stageDir);
+        throw error;
+    }
+    removeStageDir(stageDir);
+}
+function restorePreviousOutput(finalPath, backupPath, hadPreviousOutput, replacedOutput) {
+    if (!hadPreviousOutput) {
+        // Don't leave a rejected artifact behind at the output path.
+        if (replacedOutput && fs_1.default.lstatSync(finalPath, { throwIfNoEntry: false })?.isFile()) {
+            fs_1.default.unlinkSync(finalPath);
+        }
+        return;
+    }
+    // A failed rename leaves the destination untouched, so the previous APK is
+    // usually still in place; only restore when it was replaced or is missing.
+    if (!replacedOutput && existingOutputIsFile(finalPath))
+        return;
+    fs_1.default.renameSync(backupPath, finalPath);
+    if (!existingOutputIsFile(finalPath)) {
+        throw new Error("Restored APK is not a regular file");
+    }
+}
+function existingOutputIsFile(finalPath) {
+    const stat = fs_1.default.lstatSync(finalPath, { throwIfNoEntry: false });
+    if (!stat)
+        return false;
+    if (!stat.isFile() || stat.isSymbolicLink()) {
+        throw new Error(`Output path must be a regular file: ${finalPath}`);
+    }
+    return true;
+}
+function removeStageDir(stageDir) {
+    try {
+        fs_1.default.rmSync(stageDir, { recursive: true, force: true });
+    }
+    catch (error) {
+        console.warn("Warning: failed to remove APK staging directory:", error instanceof Error ? error.message : "unknown cleanup error");
+    }
+}
+function isInside(child, parent) {
+    const relative = path_1.default.relative(parent, child);
+    return (relative === "" ||
+        (relative.split(path_1.default.sep)[0] !== ".." && !path_1.default.isAbsolute(relative)));
+}

package/dist/commands/build.js

@@ -11,6 +11,7 @@ const releaseWorkspace_1 = require("../android/releaseWorkspace");
 const pakstrConfig_1 = require("../core/pakstrConfig");
 const androidProject_1 = require("../core/androidProject");
 const createRunner_1 = require("../runners/createRunner");
+const artifactPublisher_1 = require("./artifactPublisher");
 /**
  * `pakstr build` — produce an UNSIGNED release APK at `build.out`.
  * Spec §5.2. No nsec required.
@@ -24,7 +25,11 @@ async function buildCommand(configPath) {
     console.log("📱 Out:", finalPath);
     console.log("🏗️  Builder:", config.build.builder);
     validateOutputParent(finalPath);
-    removeExistingOutput(finalPath);
+    // Whatever happens next, the APK at finalPath is no longer the signed output
+    // of this config: on success it is replaced by a new unsigned APK, and on
+    // failure it is kept but may be an older build (e.g. a previous versionCode).
+    // Removing its sidecars makes publish refuse it until `pakstr sign` runs.
+    removeStaleSigningSidecars(finalPath);
     const templateRoot = await (0, template_1.ensureTemplate)();
     const workspace = (0, releaseWorkspace_1.createReleaseWorkspace)(templateRoot);
     let stagedPath;
@@ -53,7 +58,7 @@ async function buildCommand(configPath) {
         if (!result.unsigned) {
             throw new Error("Build runner did not produce an unsigned release APK");
         }
-        stagedPath = stageArtifact(result.artifactPath, finalPath);
+        stagedPath = (0, artifactPublisher_1.stageArtifact)(result.artifactPath, finalPath);
     }
     catch (error) {
         primaryError = error;
@@ -67,7 +72,6 @@ async function buildCommand(configPath) {
     }
     if (primaryError || cleanupError) {
         removeStagedArtifact(stagedPath);
-        removeExistingOutput(finalPath);
         if (primaryError) {
             if (cleanupError) {
                 console.error("Workspace cleanup also failed:", safeErrorMessage(cleanupError));
@@ -79,7 +83,7 @@ async function buildCommand(configPath) {
     if (!stagedPath) {
         throw new Error("Build completed without a staged APK");
     }
-    publishArtifact(stagedPath, finalPath);
+    (0, artifactPublisher_1.publishArtifact)(stagedPath, finalPath);
     console.log("\n✅ BUILD COMPLETE (unsigned)");
     console.log("📦 Output:", finalPath);
     console.log("➡️  Next: pakstr sign");
@@ -102,33 +106,15 @@ function validateOutputParent(finalPath) {
         }
     }
 }
-function stageArtifact(artifactPath, finalPath) {
-    const parent = path_1.default.dirname(finalPath);
-    const stageDir = fs_1.default.mkdtempSync(path_1.default.join(parent, ".pakstr-stage-"));
-    const stagedPath = path_1.default.join(stageDir, "app.apk");
-    fs_1.default.copyFileSync(artifactPath, stagedPath, fs_1.default.constants.COPYFILE_EXCL);
-    if (fs_1.default.statSync(stagedPath).size !== fs_1.default.statSync(artifactPath).size) {
-        fs_1.default.rmSync(stageDir, { recursive: true, force: true });
-        throw new Error("Staged APK size does not match built artifact");
-    }
-    return stagedPath;
-}
-function publishArtifact(stagedPath, finalPath) {
-    removeExistingOutput(finalPath);
-    fs_1.default.renameSync(stagedPath, finalPath);
-    fs_1.default.rmSync(path_1.default.dirname(stagedPath), { recursive: true, force: true });
-    if (!fs_1.default.existsSync(finalPath) || !fs_1.default.lstatSync(finalPath).isFile()) {
-        throw new Error("Final APK publication failed");
-    }
-}
-function removeExistingOutput(finalPath) {
-    if (!fs_1.default.existsSync(finalPath))
-        return;
-    const stat = fs_1.default.lstatSync(finalPath);
-    if (!stat.isFile() || stat.isSymbolicLink()) {
-        throw new Error(`Refusing to remove non-regular output path: ${finalPath}`);
+function removeStaleSigningSidecars(apkPath) {
+    for (const sidecar of [`${apkPath}.signer-sha256`, `${apkPath}.identity-proof`]) {
+        try {
+            fs_1.default.rmSync(sidecar, { force: true });
+        }
+        catch (error) {
+            console.warn(`Warning: could not remove stale signing sidecar ${sidecar}:`, safeErrorMessage(error));
+        }
     }
-    fs_1.default.unlinkSync(finalPath);
 }
 function removeStagedArtifact(stagedPath) {
     if (!stagedPath)

package/dist/commands/publish.js

@@ -10,6 +10,7 @@ const artifactUpload_1 = require("../core/artifactUpload");
 const blossom_1 = require("../core/blossom");
 const giteaRelease_1 = require("../core/giteaRelease");
 const identityProof_1 = require("../core/identityProof");
+const apkSignature_1 = require("../core/apkSignature");
 const nostr_1 = require("../core/nostr");
 const pakstrConfig_1 = require("../core/pakstrConfig");
 const nsite_1 = require("../core/nsite");
@@ -56,6 +57,9 @@ async function publishCommand(configPath, options = {}) {
             dryRun: options.dryRun,
             fetchImpl,
         });
+        reportNsitePartialFailures(nsite);
+        if (options.verify && !options.dryRun)
+            await (0, nsite_1.verifyNsite)(nsite, transport, fetchImpl);
         const result = { artifactUrl: "", uploadProvider: null, nsite };
         if (options.outJson) {
             fs_1.default.writeFileSync(options.outJson, JSON.stringify({
@@ -95,6 +99,10 @@ async function publishCommand(configPath, options = {}) {
             throw new Error(`Signer certificate sidecar not found: ${certShaPath}. Run \`pakstr sign\` first.`);
         }
         signerCertificateSha256 = fs_1.default.readFileSync(certShaPath, "utf8").trim();
+        // The sidecar must describe the APK actually being published: a rebuilt or
+        // failed-sign APK left next to sidecars from an earlier sign is refused.
+        // The identity proof is bound to this certificate by parseIdentityProofSidecar.
+        assertApkSignedWith(apkPath, signerCertificateSha256, certShaPath);
         const proofPath = `${apkPath}.identity-proof`;
         if (zapstoreEnabled && fs_1.default.existsSync(proofPath)) {
             identityProof = (0, identityProof_1.parseIdentityProofSidecar)(fs_1.default.readFileSync(proofPath, "utf8").trim(), proofPath, signerCertificateSha256);
@@ -300,9 +308,9 @@ async function publishCommand(configPath, options = {}) {
             dryRun: options.dryRun,
             fetchImpl,
         });
-        if (nsiteResult.partialFailures > 0) {
-            console.log(`⚠️  Nsite published with ${nsiteResult.partialFailures} target failure(s)`);
-        }
+        reportNsitePartialFailures(nsiteResult);
+        if (options.verify && !options.dryRun)
+            await (0, nsite_1.verifyNsite)(nsiteResult, transport, fetchImpl);
     }
     const result = {
         artifactUrl,
@@ -343,3 +351,29 @@ async function publishCommand(configPath, options = {}) {
     }
     return result;
 }
+function reportNsitePartialFailures(result) {
+    if (result.partialFailures > 0) {
+        console.log(`⚠️  Nsite published with ${result.partialFailures} target failure(s)`);
+    }
+}
+function assertApkSignedWith(apkPath, expectedSha256, certShaPath) {
+    if (!/^[0-9a-f]{64}$/.test(expectedSha256)) {
+        throw new Error(`Signer certificate sidecar ${certShaPath} is not a lowercase SHA-256. Run \`pakstr sign\` again.`);
+    }
+    let actual;
+    try {
+        actual = (0, apkSignature_1.readApkSignerCertificateSha256)(apkPath);
+    }
+    catch (error) {
+        if (!(error instanceof apkSignature_1.ApkSignatureError))
+            throw error;
+        if (error.reason === "unsigned") {
+            throw new Error(`APK at ${apkPath} is not signed (${error.message}). Run \`pakstr sign\` first.`);
+        }
+        throw new Error(`Cannot use the APK at ${apkPath}: ${error.message}. Rebuild and sign it with \`pakstr run\`.`);
+    }
+    if (actual !== expectedSha256) {
+        throw new Error(`APK at ${apkPath} is signed with certificate ${actual}, but ${certShaPath} expects ${expectedSha256}. ` +
+            "The sidecar is stale or the APK was replaced; run `pakstr sign` to sign the current APK.");
+    }
+}

package/dist/commands/run.js

@@ -25,19 +25,31 @@ const publish_1 = require("./publish");
 async function runCommand(configPath, options = {}) {
     // Step 1: load & validate config, pre-validate nsecs.
     const config = (0, pakstrConfig_1.loadPakstrConfig)(configPath);
-    // Verify PAKSTR_NSEC present (fail fast before any work).
-    (0, nostr_1.requireSigningNsec)(process.env);
+    // Verify PAKSTR_NSEC (fail fast before any work). A dry run skips build and
+    // sign, so it only needs the publish key checked below — which is
+    // PAKSTR_NSEC itself unless publish.publishKey names a separate one.
+    if (!options.dryRun)
+        (0, nostr_1.requireSigningNsec)(process.env);
     // Pre-validate the Nostr publish nsec when Zapstore, Blossom, or nsite needs it.
     if (config.publish.zapstoreEnabled || config.publish.nsite.enabled || (config.publish.upload.enabled && config.publish.upload.provider === "blossom")) {
+        const envVar = config.publish.publishKey === undefined
+            ? "PAKSTR_NSEC"
+            : config.publish.publishKey === null
+                ? "PAKSTR_PUBLISH_NSEC"
+                : config.publish.publishKey;
         if (!(0, nostr_1.isPublishNsecPresent)(config.publish.publishKey, process.env)) {
-            const envVar = config.publish.publishKey === undefined
-                ? "PAKSTR_NSEC"
-                : config.publish.publishKey === null
-                    ? "PAKSTR_PUBLISH_NSEC"
-                    : config.publish.publishKey;
             throw new Error(`${envVar} is required for publishing and must not be empty. ` +
                 `Pre-validation failed before any build work.`);
         }
+        // Decode it too, so a malformed key fails here rather than after build
+        // and sign (where sign would also silently skip the identity proof).
+        try {
+            (0, nostr_1.resolvePublishNsec)(config.publish.publishKey, process.env);
+        }
+        catch (error) {
+            throw new Error(`${envVar} is not a valid nsec: ${error instanceof Error ? error.message : String(error)}. ` +
+                `Pre-validation failed before any build work.`);
+        }
     }
     console.log("\n🚀 pakstr run");
     console.log("App:", config.app.appName, `(${config.app.appId})`);
@@ -62,6 +74,9 @@ async function runCommand(configPath, options = {}) {
         console.log("\n✅ pakstr run complete (dry-run)");
         return;
     }
+    // Keystores already on disk belong to the user (pakstr never writes one), so
+    // only files that appear or change during this run are treated as leaks.
+    const keystoresBefore = findKeystores(config);
     // Step 3: build the unsigned APK.
     console.log("\n— Step 1/3: build —");
     await (0, build_1.buildCommand)(config.configPath || undefined);
@@ -81,36 +96,52 @@ async function runCommand(configPath, options = {}) {
     }
     // Step 6: cleanup. The signed APK at build.out is the artifact and is kept.
     // Derived signing material is cleaned up inside the sign runner (tmpfs).
-    verifyNoLeakedKeystores(config);
+    verifyNoLeakedKeystores(config, keystoresBefore);
     console.log("\n✅ pakstr run complete");
     console.log("Signed APK:", path_1.default.resolve(config.build.out));
 }
-/** Best-effort: ensure no derived .p12 keystore leaked onto disk (§7). */
-function verifyNoLeakedKeystores(config) {
-    const buildDir = path_1.default.join(config.configDir, "build");
-    if (!fs_1.default.existsSync(buildDir))
-        return;
+/**
+ * Keystore files under `<configDir>/build`, mapped to a fingerprint that
+ * changes when a file is replaced (inode) or written in place (size, mtime,
+ * and ctime, which also changes if mtime is reset afterwards).
+ */
+function findKeystores(config) {
+    const found = new Map();
     const walk = (dir) => {
-        const found = [];
-        for (const entry of fs_1.default.readdirSync(dir, { withFileTypes: true })) {
+        let entries;
+        try {
+            entries = fs_1.default.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
             const p = path_1.default.join(dir, entry.name);
             if (entry.isDirectory())
-                found.push(...walk(p));
-            else if (entry.name.endsWith(".p12") || entry.name.endsWith(".keystore"))
-                found.push(p);
+                walk(p);
+            else if (entry.name.endsWith(".p12") || entry.name.endsWith(".keystore")) {
+                const stat = fs_1.default.lstatSync(p, { throwIfNoEntry: false });
+                if (stat) {
+                    found.set(p, [stat.dev, stat.ino, stat.size, stat.mtimeMs, stat.ctimeMs].join(":"));
+                }
+            }
         }
-        return found;
     };
-    const leaked = walk(buildDir);
+    walk(path_1.default.join(config.configDir, "build"));
+    return found;
+}
+/**
+ * Ensure no derived keystore leaked onto disk during this run (§7). Never
+ * deletes anything: a keystore may be the user's own (customer-keystore flow,
+ * exported derived keys), and pakstr cannot tell the two apart reliably.
+ */
+function verifyNoLeakedKeystores(config, before) {
+    const leaked = [...findKeystores(config)]
+        .filter(([file, fingerprint]) => before.get(file) !== fingerprint)
+        .map(([file]) => file);
     if (leaked.length > 0) {
-        for (const f of leaked) {
-            try {
-                fs_1.default.rmSync(f, { force: true });
-            }
-            catch {
-                /* ignore */
-            }
-        }
-        throw new Error(`Derived keystore material leaked onto disk: ${leaked.join(", ")}`);
+        throw new Error(`Keystore files appeared or changed during this run: ${leaked.join(", ")}. ` +
+            "pakstr never writes signing keys to disk, so these may be leaked key material; " +
+            "they were left in place. Inspect them and delete any you did not create.");
     }
 }

package/dist/core/apkSignature.js

@@ -0,0 +1,197 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApkSignatureError = void 0;
+exports.readApkSignerCertificateSha256 = readApkSignerCertificateSha256;
+const crypto_1 = require("crypto");
+const fs_1 = __importDefault(require("fs"));
+/**
+ * Reads the signing certificate of an APK from its APK Signing Block (APK
+ * Signature Scheme v2/v3, which `pakstr sign` always produces: min SDK 28).
+ *
+ * This identifies the certificate the APK claims to be signed with; it does not
+ * cryptographically verify the signature (Android and apksigner do that on
+ * install). It lets `pakstr publish` refuse an APK whose signer does not match
+ * the `.signer-sha256` sidecar, e.g. an unsigned rebuild next to stale sidecars.
+ *
+ * Format: https://source.android.com/docs/security/features/apksigning/v2
+ */
+const EOCD_SIGNATURE = 0x06054b50;
+const EOCD_MIN_SIZE = 22;
+const MAX_ZIP_COMMENT = 0xffff;
+const SIGNING_BLOCK_MAGIC = "APK Sig Block 42";
+// Signing blocks are a few KB; refuse absurd sizes from a corrupt file.
+const MAX_SIGNING_BLOCK_SIZE = 64 * 1024 * 1024;
+const SCHEMES = [
+    ["v3.1", 0x1b93ad61],
+    ["v3", 0xf05368c0],
+    ["v2", 0x7109871a],
+];
+class ApkSignatureError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = "ApkSignatureError";
+    }
+}
+exports.ApkSignatureError = ApkSignatureError;
+/** Lowercase hex SHA-256 of the APK's signing certificate (DER), as apksigner prints it. */
+function readApkSignerCertificateSha256(apkPath) {
+    const fd = fs_1.default.openSync(apkPath, "r");
+    try {
+        const block = readSigningBlock(fd, fs_1.default.fstatSync(fd).size);
+        if (!block) {
+            throw new ApkSignatureError("unsigned", "it has no APK Signature Scheme v2/v3 signing block");
+        }
+        const certificates = new Set();
+        for (const [scheme, id] of SCHEMES) {
+            const value = block.get(id);
+            if (value) {
+                for (const der of signerCertificates(value, scheme))
+                    certificates.add(certificateSha256(der, scheme));
+            }
+        }
+        if (certificates.size === 0) {
+            throw new ApkSignatureError("unsigned", "its signing block has no v2/v3 signature");
+        }
+        if (certificates.size > 1) {
+            throw new ApkSignatureError("multiple-certificates", `it is signed with ${certificates.size} different certificates (multiple signers or key rotation are not supported)`);
+        }
+        return [...certificates][0];
+    }
+    finally {
+        fs_1.default.closeSync(fd);
+    }
+}
+/** The signing block's ID → value pairs, or undefined if the APK has none. */
+function readSigningBlock(fd, fileSize) {
+    const eocd = findEndOfCentralDirectory(fd, fileSize);
+    const centralDirectorySize = eocd.record.readUInt32LE(12);
+    const centralDirectoryOffset = eocd.record.readUInt32LE(16);
+    if (centralDirectoryOffset === 0xffffffff || centralDirectorySize === 0xffffffff) {
+        throw malformed("ZIP64 archives are not supported");
+    }
+    // APK signing requires the central directory to sit directly before the EOCD.
+    if (centralDirectoryOffset + centralDirectorySize !== eocd.offset) {
+        throw malformed("the ZIP central directory is not where the end record says");
+    }
+    const footerSize = 8 + SIGNING_BLOCK_MAGIC.length;
+    if (centralDirectoryOffset < footerSize + 8)
+        return undefined;
+    const footer = read(fd, centralDirectoryOffset - footerSize, footerSize);
+    if (footer.toString("latin1", 8) !== SIGNING_BLOCK_MAGIC)
+        return undefined;
+    const blockSize = toSafeLength(footer.readBigUInt64LE(0));
+    if (blockSize < footerSize || blockSize > MAX_SIGNING_BLOCK_SIZE || blockSize + 8 > centralDirectoryOffset) {
+        throw malformed("the signing block size is invalid");
+    }
+    const blockStart = centralDirectoryOffset - blockSize - 8;
+    const block = read(fd, blockStart, blockSize + 8);
+    if (toSafeLength(block.readBigUInt64LE(0)) !== blockSize) {
+        throw malformed("the signing block header and footer sizes differ");
+    }
+    const pairs = new Map();
+    const end = block.length - footerSize;
+    for (let offset = 8; offset < end;) {
+        if (end - offset < 12)
+            throw malformed("a signing block entry is truncated");
+        const length = toSafeLength(block.readBigUInt64LE(offset));
+        if (length < 4 || length > end - offset - 8)
+            throw malformed("a signing block entry has an invalid length");
+        const id = block.readUInt32LE(offset + 8);
+        if (pairs.has(id))
+            throw malformed(`the signing block repeats entry 0x${id.toString(16)}`);
+        pairs.set(id, block.subarray(offset + 12, offset + 8 + length));
+        offset += 8 + length;
+    }
+    return pairs;
+}
+function findEndOfCentralDirectory(fd, fileSize) {
+    if (fileSize < EOCD_MIN_SIZE)
+        throw malformed("it is too small to be a ZIP archive");
+    const tailSize = Math.min(fileSize, EOCD_MIN_SIZE + MAX_ZIP_COMMENT);
+    const tail = read(fd, fileSize - tailSize, tailSize);
+    // Search backwards; the record's comment must run exactly to the end of file.
+    for (let i = tail.length - EOCD_MIN_SIZE; i >= 0; i--) {
+        if (tail.readUInt32LE(i) !== EOCD_SIGNATURE)
+            continue;
+        if (i + EOCD_MIN_SIZE + tail.readUInt16LE(i + 20) !== tail.length)
+            continue;
+        return { record: tail.subarray(i, i + EOCD_MIN_SIZE), offset: fileSize - tailSize + i };
+    }
+    throw malformed("it is not a ZIP archive (no end of central directory record)");
+}
+/** First certificate (DER) of every signer in a v2/v3 signature scheme block. */
+function signerCertificates(value, scheme) {
+    const signers = new Reader(value, `${scheme} block`).lengthPrefixed();
+    const certificates = [];
+    while (!signers.done()) {
+        const signer = signers.lengthPrefixed();
+        const signedData = signer.lengthPrefixed();
+        signedData.lengthPrefixed(); // digests
+        const certs = signedData.lengthPrefixed();
+        if (certs.done())
+            throw malformed(`a ${scheme} signer has no certificate`);
+        certificates.push(certs.lengthPrefixed().rest());
+    }
+    if (certificates.length === 0)
+        throw malformed(`the ${scheme} block has no signers`);
+    return certificates;
+}
+function certificateSha256(der, scheme) {
+    try {
+        new crypto_1.X509Certificate(der);
+    }
+    catch {
+        throw malformed(`a ${scheme} signer certificate is not valid X.509`);
+    }
+    return (0, crypto_1.createHash)("sha256").update(der).digest("hex");
+}
+/** Bounds-checked reader of uint32 length-prefixed values. */
+class Reader {
+    buffer;
+    what;
+    offset = 0;
+    constructor(buffer, what) {
+        this.buffer = buffer;
+        this.what = what;
+    }
+    done() {
+        return this.offset >= this.buffer.length;
+    }
+    lengthPrefixed() {
+        if (this.buffer.length - this.offset < 4)
+            throw malformed(`the ${this.what} is truncated`);
+        const length = this.buffer.readUInt32LE(this.offset);
+        const start = this.offset + 4;
+        if (length > this.buffer.length - start)
+            throw malformed(`the ${this.what} has an invalid length`);
+        this.offset = start + length;
+        return new Reader(this.buffer.subarray(start, start + length), this.what);
+    }
+    rest() {
+        return this.buffer.subarray(this.offset);
+    }
+}
+function read(fd, position, length) {
+    const buffer = Buffer.alloc(length);
+    let total = 0;
+    while (total < length) {
+        const bytes = fs_1.default.readSync(fd, buffer, total, length - total, position + total);
+        if (bytes === 0)
+            throw malformed("it ends unexpectedly");
+        total += bytes;
+    }
+    return buffer;
+}
+function toSafeLength(value) {
+    if (value > BigInt(Number.MAX_SAFE_INTEGER))
+        throw malformed("a length field is out of range");
+    return Number(value);
+}
+function malformed(detail) {
+    return new ApkSignatureError("malformed", detail);
+}

package/dist/core/nsite.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NSITE_MANIFEST_KIND = void 0;
 exports.publishNsite = publishNsite;
+exports.verifyNsite = verifyNsite;
 exports.inspectNsiteDirectory = inspectNsiteDirectory;
 exports.buildNsiteEventTemplates = buildNsiteEventTemplates;
 const crypto_1 = require("crypto");
@@ -90,6 +91,54 @@ async function publishNsite(options) {
         partialFailures,
     };
 }
+/**
+ * `--verify` for nsite: the manifest must be readable back from a relay that
+ * accepted it, and every file downloadable from a server that accepted its
+ * upload. Throws listing what could not be verified.
+ */
+async function verifyNsite(result, transport, fetchImpl = fetch) {
+    if (!transport.query) {
+        throw new Error("Nsite verification is not supported by this relay transport (it cannot query events)");
+    }
+    const query = transport.query.bind(transport);
+    const accepted = (targets) => targets.filter(t => t.success && !t.skipped);
+    const problems = [];
+    for (const { event, relays } of result.events.filter(e => e.event.kind === exports.NSITE_MANIFEST_KIND)) {
+        let found = false;
+        for (const relay of accepted(relays)) {
+            try {
+                found = (await query({ ids: [event.id], limit: 1 }, relay.target))?.id === event.id;
+            }
+            catch {
+                // Try the next relay.
+            }
+            if (found)
+                break;
+        }
+        if (!found)
+            problems.push(`manifest ${event.id} was not found on any relay that accepted it`);
+    }
+    for (const file of result.files) {
+        let found = false;
+        for (const server of accepted(file.servers)) {
+            try {
+                found = (await fetchImpl(`${server.target}/${file.sha256}`, { method: "HEAD" })).ok;
+            }
+            catch {
+                // Try the next server.
+            }
+            if (found)
+                break;
+        }
+        if (!found)
+            problems.push(`${file.path} is not downloadable from any server that accepted it`);
+    }
+    if (problems.length > 0) {
+        const shown = problems.slice(0, 5).join("; ");
+        const more = problems.length > 5 ? `; and ${problems.length - 5} more` : "";
+        throw new Error(`Nsite verification failed: ${shown}${more}`);
+    }
+}
 function inspectNsiteDirectory(directory) {
     const root = path_1.default.resolve(directory);
     if (!fs_1.default.existsSync(root) || !fs_1.default.lstatSync(root).isDirectory()) {

package/dist/runners/DockerGradleRunner.js

@@ -9,6 +9,7 @@ const path_1 = __importDefault(require("path"));
 const crypto_1 = require("crypto");
 const process_1 = require("./process");
 const dockerNetwork_1 = require("./dockerNetwork");
+const timeouts_1 = require("./timeouts");
 const CONTAINER_RELEASE_APK_SIGNED = "/workspace/app/build/outputs/apk/release/app-release.apk";
 const CONTAINER_RELEASE_APK_UNSIGNED = "/workspace/app/build/outputs/apk/release/app-release-unsigned.apk";
 const CONTAINER_DEBUG_APK = "/workspace/app/build/outputs/apk/debug/app-debug.apk";
@@ -22,16 +23,17 @@ class DockerGradleRunner {
         this.execute = execute;
     }
     async build(request) {
+        const timeoutMs = (0, timeouts_1.buildTimeoutMs)();
         this.checkDockerAvailable();
-        this.ensureDockerImage();
+        this.ensureDockerImage(timeoutMs);
         const storage = this.createBuildStorage(request.androidRoot);
         let primaryError;
         let result;
         try {
             result =
                 request.mode === "release"
-                    ? this.buildRelease(request, storage)
-                    : this.buildDebug(request, storage);
+                    ? this.buildRelease(request, storage, timeoutMs)
+                    : this.buildDebug(request, storage, timeoutMs);
         }
         catch (error) {
             primaryError = error;
@@ -55,10 +57,8 @@ class DockerGradleRunner {
             throw new Error("Docker build completed without a result");
         return result;
     }
-    buildDebug(request, storage) {
-        this.execute("docker", [
-            "run",
-            "--rm",
+    buildDebug(request, storage, timeoutMs) {
+        this.runBuildContainer([
             ...(0, dockerNetwork_1.dockerNetworkArgs)(),
             "-v",
             `${storage.workspaceVolume}:/workspace`,
@@ -68,17 +68,15 @@ class DockerGradleRunner {
             "./gradlew",
             "assembleDebug",
             "-Dorg.gradle.vfs.watch=false",
-        ], { streamOutput: true });
+        ], { streamOutput: true, timeoutMs, timeoutHint: (0, timeouts_1.buildTimeoutHint)("Gradle build") });
         const artifactPath = hostArtifactPath(request.androidRoot, "debug");
         this.copyFromVolume(storage.workspaceVolume, CONTAINER_DEBUG_APK, artifactPath);
         return { artifactPath: requireApk(artifactPath), unsigned: false };
     }
-    buildRelease(request, storage) {
+    buildRelease(request, storage, timeoutMs) {
         // Unsigned release build: no signing config is wired up because
         // PAKSTR_ANDROID_KEYSTORE_PATH is not set in the container environment.
-        this.execute("docker", [
-            "run",
-            "--rm",
+        this.runBuildContainer([
             ...(0, dockerNetwork_1.dockerNetworkArgs)(),
             "-v",
             `${storage.workspaceVolume}:/workspace`,
@@ -89,11 +87,27 @@ class DockerGradleRunner {
             "assembleRelease",
             "--no-daemon",
             "-Dorg.gradle.vfs.watch=false",
-        ], { env: scrubSigningEnv(process.env), streamOutput: true });
+        ], {
+            env: scrubSigningEnv(process.env),
+            streamOutput: true,
+            timeoutMs,
+            timeoutHint: (0, timeouts_1.buildTimeoutHint)("Gradle build"),
+        });
         const artifactPath = hostArtifactPath(request.androidRoot, "release-unsigned");
         this.copyFromVolume(storage.workspaceVolume, CONTAINER_RELEASE_APK_UNSIGNED, artifactPath);
         return { artifactPath: requireApk(artifactPath), unsigned: true };
     }
+    runBuildContainer(args, options) {
+        const container = `pakstr-build-${(0, crypto_1.randomUUID)()}`;
+        try {
+            this.execute("docker", ["run", "--rm", "--name", container, ...args], options);
+        }
+        catch (error) {
+            // Remove it before the workspace volume it may still hold is cleaned up.
+            (0, timeouts_1.removeFailedRunContainer)(this.execute, container);
+            throw error;
+        }
+    }
     createBuildStorage(androidRoot) {
         const suffix = (0, crypto_1.randomUUID)();
         const storage = {
@@ -101,7 +115,7 @@ class DockerGradleRunner {
         };
         assertRegularAbsolutePath(androidRoot, "Android workspace");
         try {
-            this.execute("docker", ["volume", "create", storage.workspaceVolume]);
+            this.execute("docker", ["volume", "create", storage.workspaceVolume], timeouts_1.DOCKER_COMMAND_OPTIONS);
             this.copyDirectoryToVolume(androidRoot, storage.workspaceVolume);
             return storage;
         }
@@ -127,8 +141,8 @@ class DockerGradleRunner {
                 `${volume}:/workspace`,
                 this.image,
                 "true",
-            ]);
-            this.execute("docker", ["cp", `${source}${path_1.default.sep}.`, `${container}:/workspace`]);
+            ], timeouts_1.DOCKER_COMMAND_OPTIONS);
+            this.execute("docker", ["cp", `${source}${path_1.default.sep}.`, `${container}:/workspace`], timeouts_1.DOCKER_COPY_OPTIONS);
         }
         finally {
             this.removeContainer(container);
@@ -148,8 +162,8 @@ class DockerGradleRunner {
                 `${volume}:/workspace:ro`,
                 this.image,
                 "true",
-            ]);
-            this.execute("docker", ["cp", `${container}:${source}`, destination]);
+            ], timeouts_1.DOCKER_COMMAND_OPTIONS);
+            this.execute("docker", ["cp", `${container}:${source}`, destination], timeouts_1.DOCKER_COPY_OPTIONS);
         }
         finally {
             this.removeContainer(container);
@@ -157,7 +171,7 @@ class DockerGradleRunner {
     }
     removeBuildStorage(storage) {
         try {
-            this.execute("docker", ["volume", "rm", "--force", storage.workspaceVolume]);
+            this.execute("docker", ["volume", "rm", "--force", storage.workspaceVolume], timeouts_1.DOCKER_COMMAND_OPTIONS);
         }
         catch {
             throw new Error(`Failed to remove temporary Docker volume: ${storage.workspaceVolume}`);
@@ -165,7 +179,7 @@ class DockerGradleRunner {
     }
     removeContainer(container) {
         try {
-            this.execute("docker", ["rm", "--force", container]);
+            this.execute("docker", ["rm", "--force", container], timeouts_1.DOCKER_COMMAND_OPTIONS);
         }
         catch {
             // A failed docker create leaves no container to remove.
@@ -179,14 +193,21 @@ class DockerGradleRunner {
             throw new Error("Docker is not installed or not running. Install Docker Desktop to use pakstr.");
         }
     }
-    ensureDockerImage() {
+    ensureDockerImage(timeoutMs) {
         try {
-            this.execute("docker", ["image", "inspect", this.image]);
+            this.execute("docker", ["image", "inspect", this.image], timeouts_1.DOCKER_COMMAND_OPTIONS);
             console.log(`🐳 Docker image ready: ${this.image}`);
         }
-        catch {
+        catch (error) {
+            // An unresponsive daemon is not a missing image; don't wait on a pull too.
+            if (error instanceof process_1.ProcessTimeoutError)
+                throw error;
             console.log(`⬇️ Pulling Docker image: ${this.image}`);
-            this.execute("docker", ["pull", this.image], { streamOutput: true });
+            this.execute("docker", ["pull", this.image], {
+                streamOutput: true,
+                timeoutMs,
+                timeoutHint: (0, timeouts_1.buildTimeoutHint)("image pull"),
+            });
         }
     }
 }

package/dist/runners/DockerSignRunner.js

@@ -11,6 +11,8 @@ const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
 const process_1 = require("./process");
 const dockerNetwork_1 = require("./dockerNetwork");
+const timeouts_1 = require("./timeouts");
+const artifactPublisher_1 = require("../commands/artifactPublisher");
 class DockerSignRunner {
     image;
     execute;
@@ -29,11 +31,13 @@ class DockerSignRunner {
         // (mirroring how DockerGradleRunner transports the workspace).
         const apkVolume = `pakstr-sign-apk-${(0, crypto_2.randomUUID)()}`;
         const outVolume = `pakstr-sign-out-${(0, crypto_2.randomUUID)()}`;
+        const signContainer = `pakstr-sign-${(0, crypto_2.randomUUID)()}`;
+        let hostSigned;
         let primaryError;
         let result;
         try {
-            this.execute("docker", ["volume", "create", apkVolume]);
-            this.execute("docker", ["volume", "create", outVolume]);
+            this.execute("docker", ["volume", "create", apkVolume], timeouts_1.DOCKER_COMMAND_OPTIONS);
+            this.execute("docker", ["volume", "create", outVolume], timeouts_1.DOCKER_COMMAND_OPTIONS);
             this.copyFileToVolume(request.unsignedApkPath, apkVolume, "/work/unsigned.apk");
             const password = (0, crypto_1.randomBytes)(32).toString("base64url");
             const nsecString = nsecToString(request.nsec);
@@ -51,9 +55,11 @@ class DockerSignRunner {
             if (request.identityProofPubkey) {
                 signingEnvNames.push("IDENTITY_PROOF_PUBKEY");
             }
-            const stdout = this.execute("docker", [
+            const stdout = this.runSignContainer(signContainer, [
                 "run",
                 "--rm",
+                "--name",
+                signContainer,
                 ...(0, dockerNetwork_1.dockerNetworkArgs)(),
                 "--tmpfs",
                 "/signing:mode=0700,uid=0",
@@ -67,7 +73,13 @@ class DockerSignRunner {
                 request.appId,
                 "/work/unsigned.apk",
                 "/out/signed.apk",
-            ], { env, secrets: [nsecString, password], streamOutput: true }).stdout;
+            ], {
+                env,
+                secrets: [nsecString, password],
+                streamOutput: true,
+                timeoutMs: timeouts_1.DOCKER_SIGN_TIMEOUT_MS,
+                timeoutHint: `The signing container did not finish. ${timeouts_1.DOCKER_DAEMON_HINT}`,
+            }).stdout;
             const signerSha256 = parseSignerSha(stdout);
             const identityProof = parseIdentityProof(stdout);
             if (request.identityProofPubkey && !identityProof) {
@@ -85,33 +97,50 @@ class DockerSignRunner {
                 }
             }
             // Copy the signed APK out of the output volume to the host.
-            const hostSigned = path_1.default.join(os_1.default.tmpdir(), `pakstr-signed-${(0, crypto_2.randomUUID)()}.apk`);
+            hostSigned = path_1.default.join(os_1.default.tmpdir(), `pakstr-signed-${(0, crypto_2.randomUUID)()}.apk`);
             this.copyFromVolume(outVolume, "/out/signed.apk", hostSigned);
             if (!fs_1.default.existsSync(hostSigned) || !fs_1.default.lstatSync(hostSigned).isFile()) {
                 throw new Error("Sign runner did not produce a signed APK");
             }
-            fs_1.default.mkdirSync(path_1.default.dirname(request.signedApkPath), { recursive: true });
-            fs_1.default.rmSync(request.signedApkPath, { force: true });
+            if (fs_1.default.statSync(hostSigned).size === 0) {
+                throw new Error("Sign runner produced an empty signed APK");
+            }
             const finalPath = path_1.default.resolve(request.signedApkPath);
-            // Copy (not rename) across the tmpfs → workspace device boundary; CI
-            // runners put /tmp and the checkout on different filesystems, so
-            // fs.rename fails with EXDEV. COPYFILE_FICLONE is a harmless hint.
-            fs_1.default.copyFileSync(hostSigned, finalPath, fs_1.default.constants.COPYFILE_FICLONE);
-            fs_1.default.rmSync(hostSigned, { force: true });
+            fs_1.default.mkdirSync(path_1.default.dirname(finalPath), { recursive: true });
+            // Copy (not rename) across the tmpfs → workspace device boundary into a
+            // staging directory next to the output (CI runners put /tmp and the
+            // checkout on different filesystems, so fs.rename fails with EXDEV),
+            // then replace the output without deleting the previous APK first.
+            // `pakstr sign` signs in place, so that previous APK is the unsigned one.
+            (0, artifactPublisher_1.publishArtifact)((0, artifactPublisher_1.stageArtifact)(hostSigned, finalPath, "signed APK"), finalPath);
             result = { signedApkPath: finalPath, signerSha256, identityProof: identityProof ?? undefined };
         }
         catch (error) {
             primaryError = error;
         }
         finally {
-            for (const v of [outVolume, apkVolume]) {
+            // Also covers a partial signed APK left by a failed or timed-out copy,
+            // or a directory if the container produced one. The path is our own
+            // random temp name, so a recursive removal is safe.
+            if (hostSigned) {
                 try {
-                    this.execute("docker", ["volume", "rm", "--force", v]);
+                    fs_1.default.rmSync(hostSigned, { recursive: true, force: true });
                 }
                 catch {
                     /* best-effort cleanup */
                 }
             }
+            for (const v of [outVolume, apkVolume]) {
+                try {
+                    this.execute("docker", ["volume", "rm", "--force", v], timeouts_1.DOCKER_COMMAND_OPTIONS);
+                }
+                catch (error) {
+                    // Best-effort: don't fail (or mask the real error of) the signing run.
+                    console.warn(`Warning: failed to remove temporary Docker volume ${v} ` +
+                        `(${error instanceof Error ? error.message.split("\n")[0] : "unknown error"}); ` +
+                        `remove it with: docker volume rm --force ${v}`);
+                }
+            }
         }
         if (primaryError)
             throw primaryError;
@@ -119,6 +148,16 @@ class DockerSignRunner {
             throw new Error("Sign runner completed without a result");
         return result;
     }
+    runSignContainer(container, args, options) {
+        try {
+            return this.execute("docker", args, options);
+        }
+        catch (error) {
+            // A killed docker client leaves the container (and its secrets) running.
+            (0, timeouts_1.removeFailedRunContainer)(this.execute, container);
+            throw error;
+        }
+    }
     copyFileToVolume(source, volume, destination) {
         const container = `pakstr-sign-copy-${(0, crypto_2.randomUUID)()}`;
         try {
@@ -131,8 +170,8 @@ class DockerSignRunner {
                 `${volume}:/work`,
                 this.image,
                 "true",
-            ]);
-            this.execute("docker", ["cp", source, `${container}:${destination}`]);
+            ], timeouts_1.DOCKER_COMMAND_OPTIONS);
+            this.execute("docker", ["cp", source, `${container}:${destination}`], timeouts_1.DOCKER_COPY_OPTIONS);
         }
         finally {
             this.removeContainer(container);
@@ -155,8 +194,8 @@ class DockerSignRunner {
                 `${volume}:${mountDir}:ro`,
                 this.image,
                 "true",
-            ]);
-            this.execute("docker", ["cp", `${container}:${source}`, destination]);
+            ], timeouts_1.DOCKER_COMMAND_OPTIONS);
+            this.execute("docker", ["cp", `${container}:${source}`, destination], timeouts_1.DOCKER_COPY_OPTIONS);
         }
         finally {
             this.removeContainer(container);
@@ -164,7 +203,7 @@ class DockerSignRunner {
     }
     removeContainer(container) {
         try {
-            this.execute("docker", ["rm", "--force", container]);
+            this.execute("docker", ["rm", "--force", container], timeouts_1.DOCKER_COMMAND_OPTIONS);
         }
         catch {
             /* a failed create leaves no container */

package/dist/runners/LocalGradleRunner.js

@@ -7,6 +7,7 @@ exports.LocalGradleRunner = void 0;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const process_1 = require("./process");
+const timeouts_1 = require("./timeouts");
 /**
  * Local Gradle runner for users who already have a JDK + Android SDK + Gradle
  * installed. The default and only specified builder is `docker`; this remains
@@ -15,6 +16,8 @@ const process_1 = require("./process");
 class LocalGradleRunner {
     async build(request) {
         const { androidRoot, mode } = request;
+        const timeoutMs = (0, timeouts_1.buildTimeoutMs)();
+        const timeoutHint = (0, timeouts_1.buildTimeoutHint)("Gradle build");
         const gradlewPath = path_1.default.join(androidRoot, "gradlew");
         if (!fs_1.default.existsSync(gradlewPath)) {
             throw new Error("gradlew not found in Android project root");
@@ -25,6 +28,8 @@ class LocalGradleRunner {
             (0, process_1.runProcess)(gradlewPath, ["assembleDebug"], {
                 cwd: androidRoot,
                 streamOutput: true,
+                timeoutMs,
+                timeoutHint,
             });
             return { artifactPath: requireApk(androidRoot, "debug"), unsigned: false };
         }
@@ -34,6 +39,8 @@ class LocalGradleRunner {
             cwd: androidRoot,
             env,
             streamOutput: true,
+            timeoutMs,
+            timeoutHint,
         });
         const artifactPath = requireApk(androidRoot, "release-unsigned");
         return { artifactPath, unsigned: true };

package/dist/runners/process.js

@@ -1,15 +1,44 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProcessOutputLimitError = exports.ProcessTimeoutError = void 0;
 exports.runProcess = runProcess;
 exports.redact = redact;
 const child_process_1 = require("child_process");
+class ProcessTimeoutError extends Error {
+    timeoutMs;
+    constructor(message, timeoutMs) {
+        super(message);
+        this.timeoutMs = timeoutMs;
+        this.name = "ProcessTimeoutError";
+    }
+}
+exports.ProcessTimeoutError = ProcessTimeoutError;
+/** The process wrote more than MAX_OUTPUT_BYTES to stdout or stderr and was killed. */
+class ProcessOutputLimitError extends Error {
+    maxBuffer;
+    constructor(message, maxBuffer) {
+        super(message);
+        this.maxBuffer = maxBuffer;
+        this.name = "ProcessOutputLimitError";
+    }
+}
+exports.ProcessOutputLimitError = ProcessOutputLimitError;
 const MAX_DIAGNOSTIC_LENGTH = 32 * 1024;
+// Node's spawnSync default, stated explicitly so the error can name it.
+const MAX_OUTPUT_BYTES = 1024 * 1024;
 function runProcess(command, args, options = {}) {
     const result = (0, child_process_1.spawnSync)(command, args, {
         cwd: options.cwd,
         env: options.env,
         encoding: "utf8",
         stdio: ["ignore", "pipe", "pipe"],
+        maxBuffer: MAX_OUTPUT_BYTES,
+        // SIGKILL, not the default SIGTERM: spawnSync waits for the child to exit,
+        // so a child that ignores SIGTERM (e.g. PID 1 in a container) would still
+        // block forever.
+        ...(options.timeoutMs
+            ? { timeout: options.timeoutMs, killSignal: "SIGKILL" }
+            : {}),
     });
     const stdout = redact(result.stdout ?? "", options.secrets ?? []);
     const stderr = redact(result.stderr ?? "", options.secrets ?? []);
@@ -20,6 +49,18 @@ function runProcess(command, args, options = {}) {
             process.stderr.write(stderr);
     }
     if (result.error) {
+        const code = result.error.code;
+        const label = redact([command, args[0]].filter(Boolean).join(" "), options.secrets ?? []);
+        const diagnostic = bounded(`${stderr}\n${stdout}`.trim());
+        const suffix = diagnostic ? `\n${diagnostic}` : "";
+        if (options.timeoutMs && code === "ETIMEDOUT") {
+            const hint = options.timeoutHint ? ` ${options.timeoutHint}` : "";
+            throw new ProcessTimeoutError(`${label} timed out after ${formatDuration(options.timeoutMs)} and was stopped.${hint}${suffix}`, options.timeoutMs);
+        }
+        if (code === "ENOBUFS") {
+            throw new ProcessOutputLimitError(`${label} wrote more than ${MAX_OUTPUT_BYTES / (1024 * 1024)} MiB of output and was stopped; ` +
+                `its output was cut off at that point.${suffix}`, MAX_OUTPUT_BYTES);
+        }
         throw new Error(`Failed to run ${command}: ${redact(result.error.message, options.secrets ?? [])}`);
     }
     if (result.status !== 0) {
@@ -35,6 +76,16 @@ function redact(value, secrets) {
         .sort((a, b) => b.length - a.length)
         .reduce((output, secret) => output.split(secret).join("[REDACTED]"), value);
 }
+function formatDuration(ms) {
+    if (ms % 60_000 === 0)
+        return plural(ms / 60_000, "minute");
+    if (ms % 1_000 === 0)
+        return plural(ms / 1_000, "second");
+    return `${ms} ms`;
+}
+function plural(count, unit) {
+    return `${count} ${unit}${count === 1 ? "" : "s"}`;
+}
 function bounded(value) {
     if (value.length <= MAX_DIAGNOSTIC_LENGTH)
         return value;

package/dist/runners/timeouts.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DOCKER_COPY_OPTIONS = exports.DOCKER_COMMAND_OPTIONS = exports.DOCKER_DAEMON_HINT = exports.DEFAULT_BUILD_TIMEOUT_MINUTES = exports.BUILD_TIMEOUT_ENV = exports.DOCKER_SIGN_TIMEOUT_MS = exports.DOCKER_COPY_TIMEOUT_MS = exports.DOCKER_COMMAND_TIMEOUT_MS = void 0;
+exports.buildTimeoutMs = buildTimeoutMs;
+exports.buildTimeoutHint = buildTimeoutHint;
+exports.removeFailedRunContainer = removeFailedRunContainer;
+/**
+ * Upper bounds for the subprocesses pakstr runs, so a wedged Docker daemon, a
+ * stalled network or a hung Gradle build fails with a clear error instead of
+ * blocking the CLI (and CI jobs) forever. The limits are deliberately generous:
+ * they only exist to turn an indefinite hang into a failure.
+ */
+/** Docker daemon calls (inspect, create, rm, volume) that normally take seconds. */
+exports.DOCKER_COMMAND_TIMEOUT_MS = 2 * 60_000;
+/** `docker cp` of the Android workspace or an APK. */
+exports.DOCKER_COPY_TIMEOUT_MS = 10 * 60_000;
+/** The signing container (keystore derivation, apksigner, verification). */
+exports.DOCKER_SIGN_TIMEOUT_MS = 15 * 60_000;
+/** Gradle builds and builder image pulls, which can be slow on a cold cache. */
+exports.BUILD_TIMEOUT_ENV = "PAKSTR_BUILD_TIMEOUT_MINUTES";
+exports.DEFAULT_BUILD_TIMEOUT_MINUTES = 60;
+exports.DOCKER_DAEMON_HINT = "The Docker daemon may be unresponsive; check that Docker is running (`docker info`) and try again.";
+exports.DOCKER_COMMAND_OPTIONS = {
+    timeoutMs: exports.DOCKER_COMMAND_TIMEOUT_MS,
+    timeoutHint: exports.DOCKER_DAEMON_HINT,
+};
+exports.DOCKER_COPY_OPTIONS = {
+    timeoutMs: exports.DOCKER_COPY_TIMEOUT_MS,
+    timeoutHint: exports.DOCKER_DAEMON_HINT,
+};
+/**
+ * Build/pull timeout from PAKSTR_BUILD_TIMEOUT_MINUTES (default 60). `0`
+ * disables the limit and returns undefined.
+ */
+function buildTimeoutMs(env = process.env) {
+    const raw = env[exports.BUILD_TIMEOUT_ENV]?.trim();
+    if (!raw)
+        return exports.DEFAULT_BUILD_TIMEOUT_MINUTES * 60_000;
+    const minutes = Number(raw);
+    if (!/^\d+$/.test(raw) || !Number.isSafeInteger(minutes * 60_000)) {
+        throw new Error(`${exports.BUILD_TIMEOUT_ENV} must be a whole number of minutes (0 disables the limit), got "${raw}"`);
+    }
+    return minutes === 0 ? undefined : minutes * 60_000;
+}
+function buildTimeoutHint(step) {
+    return `If the ${step} needs longer, raise ${exports.BUILD_TIMEOUT_ENV} (0 disables the limit).`;
+}
+/**
+ * Remove the named container after its `docker run` failed. When the client is
+ * killed (timeout, output limit) the container keeps running, holding its
+ * volumes and any secrets in its environment; after other failures it is
+ * usually gone already, which counts as removed. Never throws, so the caller
+ * can rethrow the original failure.
+ */
+function removeFailedRunContainer(execute, container) {
+    try {
+        execute("docker", ["rm", "--force", container], exports.DOCKER_COMMAND_OPTIONS);
+    }
+    catch (error) {
+        // Older Docker versions fail `rm --force` for a container that is gone.
+        if (error instanceof Error && error.message.includes("No such container"))
+            return;
+        console.error(`Failed to remove container ${container} after docker run failed; ` +
+            `if it is still running, remove it with: docker rm --force ${container}`);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pakstr",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "description": "CLI for packaging Nostr web apps into Android APKs",
   "type": "commonjs",
   "main": "dist/index.js",
@@ -27,6 +27,7 @@
     "README.md"
   ],
   "scripts": {
+    "prebuild": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\"",
     "build": "tsc",
     "type-test": "tsc -p tsconfig.type-tests.json",
     "test": "npm run build && npm run type-test && node --test test/*.test.js",