@scalebun/cli 1.13.0 → 2.0.1

package/lib/commands/ota-keys.js

@@ -36,11 +36,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.spkiFingerprint = exports.KEY_ID_FILE = exports.PUBLIC_KEY_FILE = exports.PRIVATE_KEY_FILE = exports.KEY_DIR = void 0;
+exports.privateKeyPath = privateKeyPath;
+exports.readLocalKeyId = readLocalKeyId;
+exports.readLocalPrivatePem = readLocalPrivatePem;
+exports.localPublicPem = localPublicPem;
 exports.ensureKeyDirGitignored = ensureKeyDirGitignored;
-exports.rawPublicKeyHex = rawPublicKeyHex;
-exports.localPublicKeyHex = localPublicKeyHex;
 exports.registerOtaKeysCommand = registerOtaKeysCommand;
-exports.signBundleHash = signBundleHash;
 const crypto = __importStar(require("crypto"));
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
@@ -51,44 +53,70 @@ const context_1 = require("../utils/context");
 const prompt_1 = require("../utils/prompt");
 const output_1 = require("../utils/output");
 const client_1 = require("../api/client");
+const signing_1 = require("../utils/signing");
+Object.defineProperty(exports, "spkiFingerprint", { enumerable: true, get: function () { return signing_1.spkiFingerprint; } });
 /**
- * Bundle signing keys (OTA-03).
+ * OTA signing keys for SB-OTA-RSA-SHA256-V1 (RSA-3072 / SHA-256).
  *
- * The security model, which is the reason this command exists at all: the
- * private key is generated on the developer's machine and NEVER leaves it. Only
- * the public half is uploaded. A server that cannot sign cannot forge a bundle,
+ * The security model, and the reason this command exists: the private key is
+ * generated on the developer's machine and NEVER leaves it. Only the SPKI PUBLIC
+ * key is uploaded/registered. A server that cannot sign cannot forge a release,
  * so a compromise of ScaleBun's infrastructure still cannot push code to a
  * customer's users.
  *
- * `scalebun ota generate-key-pair` was referenced in the product documentation
- * before it existed — the docs described verification the SDK never performed
- * and a command the CLI never registered. This implements it.
+ * (Pre-1.14 ScaleBun signed with ed25519 over the bundle's SHA-256. That path is
+ * removed: the protocol is now native-verifiable RSA on every supported Android
+ * API level. Legacy ed25519 key ROWS remain readable in the dashboard, labelled
+ * "Ed25519 — Legacy"; new keys are RSA only.)
  */
-const KEY_DIR = '.scalebun';
-const PRIVATE_KEY_FILE = 'ota-signing-key.pem';
+exports.KEY_DIR = '.scalebun';
+exports.PRIVATE_KEY_FILE = 'ota-signing-key.pem';
+exports.PUBLIC_KEY_FILE = 'ota-signing-key.pub.pem';
+exports.KEY_ID_FILE = 'ota-key-id.txt';
+/** Absolute path to the private key for a key dir (default ./.scalebun). */
+function privateKeyPath(keyDir = exports.KEY_DIR) {
+    return path.join(path.resolve(keyDir), exports.PRIVATE_KEY_FILE);
+}
+/** The locally stored keyId, if any (written next to the private key at generate). */
+function readLocalKeyId(keyDir = exports.KEY_DIR) {
+    try {
+        const p = path.join(path.resolve(keyDir), exports.KEY_ID_FILE);
+        if (!fs.existsSync(p))
+            return null;
+        const v = fs.readFileSync(p, 'utf8').trim();
+        return v || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The local private key PEM, if present. */
+function readLocalPrivatePem(keyDir = exports.KEY_DIR) {
+    const p = privateKeyPath(keyDir);
+    return fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : null;
+}
+/** SPKI public-key PEM derived from the local private key, if present. */
+function localPublicPem(keyDir = exports.KEY_DIR) {
+    const priv = readLocalPrivatePem(keyDir);
+    if (!priv)
+        return null;
+    try {
+        return crypto.createPublicKey(priv).export({ type: 'spki', format: 'pem' });
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Keep the private key out of version control WITHOUT relying on the operator
- * reading a warning. The previous behaviour printed "NEVER commit this — add
- * .scalebun/ to .gitignore" and stopped; anyone who scrolled past that line
- * committed their signing key, and a signing key in git history is compromised
- * even after the file is deleted.
- *
- * Rules, in order of caution:
- *   - Only the key's directory relative to cwd can be ignored by cwd's
- *     .gitignore; if --out points outside the project, we cannot help — report
- *     the manual step instead of writing a useless entry.
- *   - An existing .gitignore is appended to, never rewritten.
- *   - A missing .gitignore is created only when cwd is actually a git repo
- *     (a `.git` entry exists) — creating one in a non-repo would be litter.
- *
- * @returns a human-readable sentence describing what happened, for the summary.
+ * reading a warning. An existing .gitignore is appended to; a missing one is
+ * created only inside an actual git repo. Returns a human-readable outcome.
  */
 function ensureKeyDirGitignored(outDir, cwd = process.cwd()) {
     const rel = path.relative(cwd, outDir);
     if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
         return `outside this project — add ${outDir} to that location's .gitignore yourself`;
     }
-    // Normalise to forward slashes: gitignore patterns use `/` on every platform.
     const entry = rel.split(path.sep).join('/') + '/';
     const gitignorePath = path.join(cwd, '.gitignore');
     try {
@@ -115,301 +143,378 @@ function ensureKeyDirGitignored(outDir, cwd = process.cwd()) {
         return `could not update .gitignore (${err?.message ?? err}) — add ${entry} yourself`;
     }
 }
-/** Hex-encoded raw 32-byte ed25519 public key from a Node KeyObject. */
-function rawPublicKeyHex(publicKey) {
-    // SPKI for ed25519 is a fixed 12-byte header followed by the 32-byte key.
-    const spki = publicKey.export({ type: 'spki', format: 'der' });
-    return spki.subarray(spki.length - 32).toString('hex');
+/** A friendly default keyId like `production-2026-01`. */
+function defaultKeyId() {
+    const d = new Date();
+    return `key-${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}`;
 }
-/**
- * The public half of the local signing key, if one exists — so `register-key`
- * can offer the right value as the default instead of asking the developer to
- * paste a 64-char hex string. Reads the private key at `./.scalebun/…pem` and
- * derives the public key from it; returns null when there is no local key.
- */
-function localPublicKeyHex(keyDir = KEY_DIR) {
-    try {
-        const privatePath = path.join(path.resolve(keyDir), PRIVATE_KEY_FILE);
-        if (!fs.existsSync(privatePath))
-            return null;
-        const priv = crypto.createPrivateKey(fs.readFileSync(privatePath));
-        return rawPublicKeyHex(crypto.createPublicKey(priv));
+async function registerPublicKey(client, appId, body) {
+    await client.post(`/saas/apps/${appId}/ota/signing-keys`, body);
+}
+// ─── generate ─────────────────────────────────────────────────────────────────
+async function runGenerate(opts) {
+    const algorithm = (opts.algorithm ?? 'rsa-3072').toLowerCase();
+    const m = /^rsa-(\d+)$/.exec(algorithm);
+    if (!m) {
+        (0, output_1.fail)(`Unsupported --algorithm "${opts.algorithm}".`, ['Use rsa-3072 (recommended) or rsa-2048.'], output_1.ExitCode.Usage);
     }
-    catch {
-        return null;
+    const bits = parseInt(m[1], 10);
+    const outDir = path.resolve(opts.out ?? exports.KEY_DIR);
+    const privatePath = opts.privateKeyOut ? path.resolve(opts.privateKeyOut) : path.join(outDir, exports.PRIVATE_KEY_FILE);
+    const publicPath = opts.publicKeyOut ? path.resolve(opts.publicKeyOut) : path.join(outDir, exports.PUBLIC_KEY_FILE);
+    const keyId = (opts.keyId ?? defaultKeyId()).trim();
+    if (fs.existsSync(privatePath) && !opts.force) {
+        (0, output_1.fail)(`A signing key already exists at ${privatePath}.`, [
+            'Overwriting it means releases signed with the old key can no longer be verified',
+            'by apps that embed only the old public key. Pass --force if that is intended.',
+        ], output_1.ExitCode.Usage);
     }
+    const { privatePem, publicPem, info } = (0, signing_1.generateRsaKeyPair)({ modulusBits: bits });
+    fs.mkdirSync(path.dirname(privatePath), { recursive: true });
+    // 0600 on POSIX; the ACL call is what actually protects it on Windows.
+    fs.writeFileSync(privatePath, privatePem, { mode: 0o600 });
+    (0, credentials_1.restrictToCurrentUser)(privatePath, 'your OTA signing private key');
+    fs.writeFileSync(publicPath, publicPem);
+    // Persist the keyId next to the key so publish/register can find it.
+    fs.writeFileSync(path.join(path.dirname(privatePath), exports.KEY_ID_FILE), keyId + '\n');
+    const gitignoreOutcome = ensureKeyDirGitignored(path.dirname(privatePath));
+    console.log(`\n🔑 RSA-${info.modulusBits} signing keypair generated.\n`);
+    console.log(`  Key ID       : ${keyId}`);
+    console.log(`  Algorithm    : RSA-${info.modulusBits} / SHA-256  (SB-OTA-RSA-SHA256-V1)`);
+    console.log(`  Fingerprint  : SHA-256:${info.fingerprintDisplay}`);
+    console.log(`  Private key  : ${privatePath}`);
+    console.log(`                 NEVER commit or share this file.`);
+    console.log(`  Public key   : ${publicPath}`);
+    console.log(`  Git          : ${gitignoreOutcome}\n`);
+    const appId = opts.appId || (0, context_1.getContext)().appId;
+    if (appId) {
+        const creds = (0, credentials_1.readCredentials)();
+        if (!creds) {
+            console.log('ℹ️  Not logged in — the keypair was written but not registered.');
+            console.log(`   Register it later with:\n   scalebun ota keys register --key-id ${keyId} --public-key ${publicPath}\n`);
+            return;
+        }
+        const client = new client_1.ApiClient(creds);
+        try {
+            await registerPublicKey(client, appId, {
+                publicKey: publicPem,
+                keyId,
+                algorithm: 'RSA_SHA256',
+                name: opts.name ?? `CLI ${new Date().toISOString().slice(0, 10)}`,
+            });
+            console.log('✅ Public key registered with ScaleBun.\n');
+        }
+        catch (err) {
+            console.log(chalk_1.default.yellow(`⚠️  Could not register the public key: ${err.message}`));
+            console.log(`   Retry: scalebun ota keys register --key-id ${keyId} --public-key ${publicPath}\n`);
+        }
+    }
+    else {
+        console.log('ℹ️  Not a linked project — run `scalebun link` (or pass --app-id) to register this public key.\n');
+    }
+    console.log('Next: embed the PUBLIC key in your native app (Android assets/, iOS bundle');
+    console.log('resource) and pin its key ID. The SDK verifies every release against the');
+    console.log('embedded key and REFUSES any that does not match. See');
+    console.log('docs/ota/SB-OTA-RSA-SHA256-V1.md.\n');
 }
 function registerOtaKeysCommand(ota) {
-    ota
-        .command('generate-key-pair')
-        .description('Generate an ed25519 signing keypair locally and register the public half')
+    const keys = ota.command('keys').description('Manage OTA release signing keys (RSA-3072 / SHA-256)');
+    keys
+        .command('generate')
+        .description('Generate an RSA signing keypair locally and register the public half')
+        .option('--algorithm <alg>', 'rsa-3072 (recommended) or rsa-2048', 'rsa-3072')
+        .option('--key-id <id>', 'Stable key identifier (e.g. production-2026-01)')
+        .option('--private-key-out <path>', 'Where to write the PKCS#8 private key')
+        .option('--public-key-out <path>', 'Where to write the SPKI public key')
+        .option('--out <dir>', `Directory for both keys (default: ./${exports.KEY_DIR})`)
         .option('--app-id <id>', 'Register the public key against this app')
         .option('--name <name>', 'Label for the key in the dashboard')
-        .option('--out <dir>', `Directory for the private key (default: ./${KEY_DIR})`)
         .option('--force', 'Overwrite an existing private key')
-        .action(async (opts) => {
-        const outDir = path.resolve(opts.out ?? KEY_DIR);
-        const privatePath = path.join(outDir, PRIVATE_KEY_FILE);
-        if (fs.existsSync(privatePath) && !opts.force) {
-            console.error(`❌ A signing key already exists at ${privatePath}.\n` +
-                `   Overwriting it means every bundle signed with the old key can no longer be\n` +
-                `   verified by apps carrying the old public key. Pass --force if that is intended.`);
-            process.exit(1);
-        }
-        const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519');
-        fs.mkdirSync(outDir, { recursive: true });
-        fs.writeFileSync(privatePath, privateKey.export({ type: 'pkcs8', format: 'pem' }), 
-        // Owner read/write only on POSIX. On Windows Node silently DROPS this
-        // mode, so the explicit ACL below is what actually protects the key
-        // there — the same treatment the credentials file already gets. A
-        // signing key with weaker protection than the login token would be
-        // backwards: this file is what proves your code is yours.
-        { mode: 0o600 });
-        (0, credentials_1.restrictToCurrentUser)(privatePath, 'your OTA signing private key');
-        const gitignoreOutcome = ensureKeyDirGitignored(outDir);
-        const publicHex = rawPublicKeyHex(publicKey);
-        console.log(`\n🔑 ed25519 signing keypair generated.\n`);
-        console.log(`  Private key : ${privatePath}`);
-        console.log(`                NEVER commit or share this file.`);
-        console.log(`  Git         : ${gitignoreOutcome}`);
-        console.log(`  Public key  : ${publicHex}\n`);
-        // Register against the flagged app, or the one this project is linked to
-        // (scalebun.json) — the same resolution `publish` uses, so a linked
-        // project registers automatically without repeating --app-id.
-        const appId = opts.appId || (0, context_1.getContext)().appId;
-        if (appId) {
-            const creds = (0, credentials_1.readCredentials)();
-            if (!creds) {
-                console.error('❌ Not logged in. Run `scalebun login` first.');
-                console.error('   The keypair was still written; register it later with:');
-                console.error(`   scalebun ota register-key --public-key ${publicHex}`);
-                process.exit(1);
-            }
-            const client = new client_1.ApiClient(creds);
-            try {
-                await client.post(`/saas/apps/${appId}/ota/signing-keys`, {
-                    publicKey: publicHex,
-                    name: opts.name ?? `CLI ${new Date().toISOString().slice(0, 10)}`,
-                });
-                console.log('✅ Public key registered with ScaleBun.\n');
-            }
-            catch (err) {
-                console.error(`❌ Failed to register public key: ${err.message}`);
-                console.error(`   Retry with: scalebun ota register-key --public-key ${publicHex}\n`);
-                process.exit(1);
-            }
+        .action(runGenerate);
+    keys
+        .command('inspect')
+        .description('Validate a public key and print its algorithm, size, and fingerprint')
+        .requiredOption('--public-key <path>', 'Path to an SPKI public-key PEM')
+        .action((opts) => {
+        const p = path.resolve(opts.publicKey);
+        if (!fs.existsSync(p))
+            (0, output_1.fail)(`No such file: ${p}`, [], output_1.ExitCode.Usage);
+        try {
+            const info = (0, signing_1.inspectPublicKey)(fs.readFileSync(p));
+            console.log('');
+            console.log(`  Algorithm    : RSA-${info.modulusBits} / SHA-256`);
+            console.log(`  Modulus      : ${info.modulusBits} bits${info.modulusBits < 3072 ? '  (2048 accepted; 3072 recommended)' : ''}`);
+            console.log(`  Fingerprint  : SHA-256:${info.fingerprintDisplay}`);
+            console.log(`  Fingerprint  : ${info.fingerprint}  (hex)`);
+            console.log('');
         }
-        else {
-            console.log('ℹ️  Not a linked project — run `scalebun link` (or pass --app-id) to\n' +
-                '   register this public key automatically.\n');
+        catch (err) {
+            (0, output_1.fail)(`Invalid public key: ${err.message}`, [], output_1.ExitCode.Rejected);
         }
-        // This used to print `verifySignature: myEd25519Verifier` — a
-        // placeholder that left every adopter to hand-write ~100 lines of
-        // crypto plumbing for the most security-critical path in the product.
-        // The SDK now ships that verifier; all the developer owes is one
-        // install and the pinned key.
-        console.log('Next: install the verifier peers (once per app):\n');
-        console.log('  npm install @noble/ed25519 @noble/hashes\n');
-        console.log('Then embed the PUBLIC key in your app and enforce it at init:\n');
-        console.log('  ScaleBun.init({');
-        console.log('    // …');
-        console.log('    ota: {');
-        console.log('      enabled: true,');
-        console.log(`      publicSigningKey: '${publicHex}',`);
-        console.log('    },');
-        console.log('  })\n');
-        console.log('The SDK verifies every bundle against that key and REFUSES any update\n' +
-            'that does not match. Supply `ota.verifySignature` only if you need to\n' +
-            'override it — your own function always takes precedence.\n');
     });
-    ota
-        .command('register-key')
-        .description('Register an existing ed25519 public key with an app')
-        // Not requiredOption: on a TTY the missing pieces are prompted. --app-id
-        // resolves from scalebun.json / an app picker; --public-key defaults to the
-        // public half of the local ./.scalebun key. A non-interactive run still needs
-        // them (or a local key), so CI is not silently blocked on a prompt.
-        .option('--app-id <id>', 'Scalebun app ID (resolved from scalebun.json, else picked)')
-        .option('--public-key <hex>', 'ed25519 public key (hex or base64); read from ./.scalebun when omitted')
+    keys
+        .command('register')
+        .description('Register an existing RSA public key (SPKI PEM) with an app')
+        .option('--app-id <id>', 'Scalebun app ID (resolved from scalebun.json when omitted)')
+        .option('--key-id <id>', 'Stable key identifier (defaults to the local key id)')
+        .option('--public-key <path>', 'SPKI public-key PEM path (defaults to the local ./.scalebun key)')
         .option('--name <name>', 'Label for the key in the dashboard')
         .action(async (opts) => {
         const creds = (0, credentials_1.readCredentials)();
-        if (!creds) {
+        if (!creds)
             (0, output_1.fail)('Not logged in. Run `scalebun login` first.', [], output_1.ExitCode.Usage);
-        }
         const client = new client_1.ApiClient(creds);
         const nonInteractive = (0, resolve_1.isNonInteractive)();
-        // App id: flag > env > scalebun.json > interactive picker.
         const appId = await (0, resolve_1.resolveAppId)({ appId: opts.appId });
-        // Public key: the flag, else the public half of the local signing key
-        // (offered as the default), else typed in.
-        let publicKey = opts.publicKey?.trim();
-        if (!publicKey) {
-            const local = localPublicKeyHex();
-            if (nonInteractive) {
-                if (!local) {
-                    (0, output_1.fail)('A public key is required.', [
-                        'Pass --public-key <hex>, or run this in a terminal to read it',
-                        'from ./.scalebun automatically.',
-                    ], output_1.ExitCode.Usage);
-                }
-                publicKey = local;
-            }
-            else {
-                publicKey = (await (0, prompt_1.text)('ed25519 public key (hex)', {
-                    default: local ?? '',
-                    help: local
-                        ? 'Enter to use the public half of your local ./.scalebun signing key.'
-                        : 'Paste the 64-character hex (or base64) public key.',
-                    validate: (v) => /\s/.test(v)
-                        ? 'A key has no spaces.'
-                        : v.trim().length < 40
-                            ? 'That looks too short for an ed25519 key.'
-                            : null,
-                })).trim();
+        let pem;
+        if (opts.publicKey) {
+            const p = path.resolve(opts.publicKey);
+            if (!fs.existsSync(p))
+                (0, output_1.fail)(`No such file: ${p}`, [], output_1.ExitCode.Usage);
+            pem = fs.readFileSync(p, 'utf8');
+        }
+        else {
+            pem = localPublicPem() ?? undefined;
+            if (!pem) {
+                (0, output_1.fail)('A public key is required.', ['Pass --public-key <path> to an SPKI PEM.'], output_1.ExitCode.Usage);
             }
         }
-        // Name: the flag, else prompted with a friendly default.
+        let info;
+        try {
+            info = (0, signing_1.inspectPublicKey)(pem);
+        }
+        catch (err) {
+            (0, output_1.fail)(`Not a usable RSA public key: ${err.message}`, [], output_1.ExitCode.Rejected);
+        }
+        const keyId = (opts.keyId ?? readLocalKeyId() ?? defaultKeyId()).trim();
         let name = opts.name?.trim();
         if (!name && !nonInteractive) {
-            name = (await (0, prompt_1.text)('Key name (label shown in the dashboard)', {
-                default: 'cli',
-                allowEmpty: true,
-            })).trim();
+            name = (await (0, prompt_1.text)('Key name (label shown in the dashboard)', { default: 'cli', allowEmpty: true })).trim();
         }
         (0, prompt_1.closePrompts)();
         try {
-            await client.post(`/saas/apps/${appId}/ota/signing-keys`, {
-                publicKey,
+            await registerPublicKey(client, appId, {
+                publicKey: info.spkiPem,
+                keyId,
+                algorithm: 'RSA_SHA256',
                 name: name || 'CLI',
             });
-            console.log('\n✅ Public key registered.\n');
+            console.log(`\n✅ Public key registered (key ID ${keyId}, SHA-256:${info.fingerprintDisplay.slice(0, 23)}…).\n`);
         }
         catch (err) {
             (0, output_1.fail)(`Failed to register public key: ${err.message}`, [], output_1.ExitCode.Rejected);
         }
     });
-    ota
-        .command('keys')
+    keys
+        .command('list')
         .description('List signing keys registered for an app')
-        // Resolves from scalebun.json / a picker like every other OTA command — a
-        // linked project should not have to repeat --app-id just to list its keys.
         .option('--app-id <id>', 'Scalebun app ID (resolved from scalebun.json when omitted)')
         .action(async (opts) => {
         const creds = (0, credentials_1.readCredentials)();
-        if (!creds) {
-            console.error('❌ Not logged in. Run `scalebun login` first.');
-            process.exit(1);
-        }
+        if (!creds)
+            (0, output_1.fail)('Not logged in. Run `scalebun login` first.', [], output_1.ExitCode.Usage);
         const appId = await (0, resolve_1.resolveAppId)({ appId: opts.appId });
         const client = new client_1.ApiClient(creds);
         try {
-            const keys = await client.get(`/saas/apps/${appId}/ota/signing-keys`);
+            const rows = await client.get(`/saas/apps/${appId}/ota/signing-keys`);
             console.log(`\n🔑 Signing keys for app ${appId}:\n`);
-            if (!keys?.length) {
-                console.log('  (none — run `scalebun ota generate-key-pair`)\n');
+            if (!rows?.length) {
+                console.log('  (none — run `scalebun ota keys generate`)\n');
                 return;
             }
-            for (const k of keys) {
+            for (const k of rows) {
                 const state = k.revokedAt ? 'REVOKED' : 'active';
-                console.log(`  • ${(k.name ?? 'unnamed').padEnd(20)} ${state.padEnd(8)} ${k.publicKey.slice(0, 16)}…`);
-                console.log(`    ${k.id}`);
+                const alg = k.algorithm === 'ED25519' ? 'Ed25519 (legacy)' : k.algorithm ? k.algorithm.replace('_', '/') : 'unknown';
+                console.log(`  • ${(k.name ?? 'unnamed').padEnd(22)} ${state.padEnd(8)} ${alg}`);
+                console.log(`    id=${k.id}${k.keyId ? `  keyId=${k.keyId}` : ''}`);
             }
             console.log('');
         }
         catch (err) {
-            console.error(`❌ Failed to list keys: ${err.message}`);
-            process.exit(1);
+            (0, output_1.fail)(`Failed to list keys: ${err.message}`, [], output_1.ExitCode.Rejected);
         }
     });
-    /**
-     * `scalebun ota keys revoke` — the missing half of the state above.
-     *
-     * `ota keys` has always RENDERED a `REVOKED` state that the CLI itself could
-     * never produce: the route existed and was role-gated, and only the dashboard
-     * could reach it. Key compromise is the one signing operation that is
-     * time-critical, and a key ceremony typically runs from a hardened box with
-     * no browser session — so "open the dashboard" is exactly the wrong answer.
-     *
-     * Revocation is a soft delete server-side: the row survives for the audit
-     * trail, which is why this is a POST to /revoke and not a DELETE.
-     */
-    ota
-        .command('revoke-key')
-        .description('Revoke a signing key — bundles signed with it stop verifying')
-        .requiredOption('--key-id <id>', 'Signing key to revoke (from `scalebun ota keys`)')
+    keys
+        .command('verify')
+        .description('Prove possession of a signing key private half (proof-of-possession)')
+        .requiredOption('--challenge <id>', 'Challenge id issued by the dashboard/API')
+        .option('--private-key <path>', 'PKCS#8 private-key PEM (defaults to the local ./.scalebun key)')
+        .option('--app-id <id>', 'Scalebun app ID (resolved from scalebun.json when omitted)')
+        .option('--key-id <id>', 'Signing key ROW id (auto-resolved from the local key when omitted)')
+        .option('--json', 'Machine-readable output')
+        .action(runVerify);
+    keys
+        .command('revoke')
+        .description('Revoke a signing key — releases signed with it stop verifying')
+        .requiredOption('--key-id <id>', 'Signing key row id to revoke (from `scalebun ota keys list`)')
         .option('--app-id <id>', 'Scalebun app ID (resolved from scalebun.json when omitted)')
+        .option('--reason <text>', 'Why the key is being revoked (recorded in the audit trail)')
         .option('--yes', 'Skip the confirmation (required off a TTY)')
         .option('--json', 'Machine-readable output')
-        .action(async (opts) => {
-        const creds = (0, credentials_1.readCredentials)();
-        if (!creds)
-            (0, output_1.fail)('Not signed in.', ['Run `scalebun login` first.'], output_1.ExitCode.Usage);
-        const appId = await (0, resolve_1.resolveAppId)({ appId: opts.appId, nonInteractive: opts.json });
-        const client = new client_1.ApiClient(creds);
-        let keys;
-        try {
-            keys = await client.get(`/saas/apps/${appId}/ota/signing-keys`);
-        }
-        catch (err) {
-            (0, output_1.failFromError)('Could not list signing keys', err);
-        }
-        const target = (keys ?? []).find((k) => k.id === opts.keyId);
-        if (!target) {
-            (0, output_1.fail)(`No signing key ${opts.keyId} on this app.`, (keys ?? []).map((k) => `  ${k.id}  ${k.name ?? 'unnamed'}`), output_1.ExitCode.Usage);
-        }
-        if (target.revokedAt) {
-            // Already revoked is not a failure — a rotation script re-running must
-            // not fail the pipeline for reaching the state it wanted.
-            (0, output_1.emit)(() => console.log(`\n${chalk_1.default.dim(`${target.name ?? target.id} is already revoked.`)}\n`), { ok: true, keyId: target.id, alreadyRevoked: true });
-            return;
-        }
-        if (!opts.yes) {
-            if ((0, resolve_1.isNonInteractive)({ nonInteractive: opts.json })) {
-                (0, output_1.fail)('Refusing to revoke a signing key without confirmation.', ['Pass --yes if this is intentional.'], output_1.ExitCode.Usage);
-            }
-            console.log('');
-            console.log(chalk_1.default.yellow(`⚠️  Revoking ${chalk_1.default.bold(target.name ?? target.id)}.\n` +
-                '   Apps pinning ONLY this key will refuse every future update — that is\n' +
-                '   fail-closed by design. Register the replacement and ship a build\n' +
-                '   pinning both before revoking the old one.'));
-            const ok = await (0, prompt_1.confirmPhrase)('   Type "revoke" to confirm: ', 'revoke', {
-                caseInsensitive: true,
-            });
-            (0, prompt_1.closePrompts)();
-            if (!ok) {
-                console.log('Cancelled — the key is still active.');
-                process.exit(output_1.ExitCode.Ok);
-            }
+        .action(runRevoke);
+    // ── Back-compat aliases (pre-1.14 top-level commands) ─────────────────────────
+    // These kept working across every prior release; forward them so scripts and
+    // muscle memory survive the move under `keys`.
+    ota
+        .command('generate-key-pair')
+        .description('(alias of `ota keys generate`)')
+        .option('--algorithm <alg>', 'rsa-3072 (recommended) or rsa-2048', 'rsa-3072')
+        .option('--key-id <id>', 'Stable key identifier')
+        .option('--app-id <id>', 'Register the public key against this app')
+        .option('--name <name>', 'Label for the key in the dashboard')
+        .option('--out <dir>', `Directory for the keys (default: ./${exports.KEY_DIR})`)
+        .option('--force', 'Overwrite an existing private key')
+        .action(runGenerate);
+    ota
+        .command('revoke-key')
+        .description('(alias of `ota keys revoke`)')
+        .requiredOption('--key-id <id>', 'Signing key row id to revoke')
+        .option('--app-id <id>', 'Scalebun app ID')
+        .option('--yes', 'Skip the confirmation')
+        .option('--json', 'Machine-readable output')
+        .action(runRevoke);
+}
+/**
+ * Resolve the signing-key ROW id for a verify: prefer --key-id, else match the
+ * local private key's public fingerprint against the app's registered keys.
+ */
+async function resolveKeyRowId(client, appId, explicitKeyId, localPubKey) {
+    if (explicitKeyId)
+        return explicitKeyId;
+    if (!localPubKey) {
+        (0, output_1.fail)('Could not determine which signing key to verify.', ['Pass --key-id <row id> (see `scalebun ota keys list`), or run from a project with ./.scalebun.'], output_1.ExitCode.Usage);
+    }
+    const localFp = (0, signing_1.spkiFingerprint)(localPubKey).hex;
+    let rows;
+    try {
+        rows = await client.get(`/saas/apps/${appId}/ota/signing-keys`);
+    }
+    catch (err) {
+        (0, output_1.failFromError)('Could not list signing keys', err);
+    }
+    const match = (rows ?? []).find((k) => (k.fingerprint ?? '').toLowerCase() === localFp.toLowerCase());
+    if (!match) {
+        (0, output_1.fail)('No registered key matches your local signing key.', ['Pass --key-id <row id> explicitly (from `scalebun ota keys list`).'], output_1.ExitCode.Usage);
+    }
+    return match.id;
+}
+async function runVerify(opts) {
+    const creds = (0, credentials_1.readCredentials)();
+    if (!creds)
+        (0, output_1.fail)('Not signed in.', ['Run `scalebun login` first.'], output_1.ExitCode.Usage);
+    const appId = await (0, resolve_1.resolveAppId)({ appId: opts.appId, nonInteractive: opts.json });
+    const client = new client_1.ApiClient(creds);
+    // Load the private key locally — it NEVER leaves this machine.
+    let privatePem;
+    if (opts.privateKey) {
+        const p = path.resolve(opts.privateKey);
+        if (!fs.existsSync(p))
+            (0, output_1.fail)(`No such file: ${p}`, [], output_1.ExitCode.Usage);
+        privatePem = fs.readFileSync(p, 'utf8');
+    }
+    else {
+        privatePem = readLocalPrivatePem();
+        if (!privatePem) {
+            (0, output_1.fail)('A private key is required.', ['Pass --private-key <path> to a PKCS#8 PEM.'], output_1.ExitCode.Usage);
         }
-        try {
-            await client.post(`/saas/apps/${appId}/ota/signing-keys/${target.id}/revoke`, {});
+    }
+    let privateKey;
+    let localPubKey = null;
+    try {
+        privateKey = crypto.createPrivateKey(privatePem);
+        localPubKey = crypto.createPublicKey(privateKey);
+    }
+    catch (err) {
+        (0, output_1.fail)(`Could not read the private key: ${err.message}`, [], output_1.ExitCode.Rejected);
+        return;
+    }
+    const keyRowId = await resolveKeyRowId(client, appId, opts.keyId, localPubKey);
+    // Fetch the EXACT bytes the server stored; sign those, nothing invented locally.
+    let challenge;
+    try {
+        challenge = await client.get(`/saas/apps/${appId}/ota/signing-keys/${keyRowId}/challenges/${opts.challenge}`);
+    }
+    catch (err) {
+        (0, output_1.failFromError)('Could not fetch the challenge', err, [
+            'Check the challenge id and that it has not expired.',
+        ]);
+    }
+    if (challenge.consumed) {
+        (0, output_1.fail)('This challenge was already used.', ['Request a fresh challenge and retry.'], output_1.ExitCode.Rejected);
+    }
+    const signature = crypto
+        .sign('sha256', Buffer.from(challenge.payload, 'base64'), privateKey)
+        .toString('base64');
+    let result;
+    try {
+        result = await client.post(`/saas/apps/${appId}/ota/signing-keys/${keyRowId}/verify`, { challengeId: opts.challenge, signature });
+    }
+    catch (err) {
+        (0, output_1.failFromError)('Ownership verification failed', err, [
+            'The signature did not verify against the registered public key, or the challenge expired.',
+        ]);
+    }
+    (0, output_1.emit)(() => {
+        console.log(`\n✅ Ownership verified for key ${keyRowId}.`);
+        if (result.activated)
+            console.log('   The key is now ACTIVE.');
+        else if (result.status)
+            console.log(`   Key status: ${result.status}`);
+        console.log('');
+    }, { ok: true, keyId: keyRowId, verified: !!result.verified, activated: !!result.activated, status: result.status });
+}
+async function runRevoke(opts) {
+    const creds = (0, credentials_1.readCredentials)();
+    if (!creds)
+        (0, output_1.fail)('Not signed in.', ['Run `scalebun login` first.'], output_1.ExitCode.Usage);
+    const appId = await (0, resolve_1.resolveAppId)({ appId: opts.appId, nonInteractive: opts.json });
+    const client = new client_1.ApiClient(creds);
+    let rows;
+    try {
+        rows = await client.get(`/saas/apps/${appId}/ota/signing-keys`);
+    }
+    catch (err) {
+        (0, output_1.failFromError)('Could not list signing keys', err);
+    }
+    const target = (rows ?? []).find((k) => k.id === opts.keyId);
+    if (!target) {
+        (0, output_1.fail)(`No signing key ${opts.keyId} on this app.`, (rows ?? []).map((k) => `  ${k.id}  ${k.name ?? 'unnamed'}`), output_1.ExitCode.Usage);
+    }
+    if (target.revokedAt) {
+        (0, output_1.emit)(() => console.log(`\n${chalk_1.default.dim(`${target.name ?? target.id} is already revoked.`)}\n`), {
+            ok: true,
+            keyId: target.id,
+            alreadyRevoked: true,
+        });
+        return;
+    }
+    if (!opts.yes) {
+        if ((0, resolve_1.isNonInteractive)({ nonInteractive: opts.json })) {
+            (0, output_1.fail)('Refusing to revoke a signing key without confirmation.', ['Pass --yes if this is intentional.'], output_1.ExitCode.Usage);
         }
-        catch (err) {
-            (0, output_1.failFromError)('Could not revoke the key', err, [
-                'Revoking a signing key requires an owner or admin role.',
-            ]);
+        console.log('');
+        console.log(chalk_1.default.yellow(`⚠️  Revoking ${chalk_1.default.bold(target.name ?? target.id)}.\n` +
+            '   Apps pinning ONLY this key will refuse every future update — fail-closed by\n' +
+            '   design. Register the replacement and ship a build embedding both first.'));
+        const ok = await (0, prompt_1.confirmPhrase)('   Type "revoke" to confirm: ', 'revoke', { caseInsensitive: true });
+        (0, prompt_1.closePrompts)();
+        if (!ok) {
+            console.log('Cancelled — the key is still active.');
+            process.exit(output_1.ExitCode.Ok);
         }
-        (0, output_1.emit)(() => console.log(`\n🔒 Revoked ${chalk_1.default.bold(target.name ?? target.id)}\n`), { ok: true, keyId: target.id, revoked: true });
+    }
+    try {
+        await client.post(`/saas/apps/${appId}/ota/signing-keys/${target.id}/revoke`, {
+            reason: (opts.reason ?? '').trim() || 'Revoked via CLI',
+        });
+    }
+    catch (err) {
+        (0, output_1.failFromError)('Could not revoke the key', err, ['Revoking a signing key requires the ota.keys.revoke permission.']);
+    }
+    (0, output_1.emit)(() => console.log(`\n🔒 Revoked ${chalk_1.default.bold(target.name ?? target.id)}\n`), {
+        ok: true,
+        keyId: target.id,
+        revoked: true,
     });
 }
-/**
- * Sign a bundle hash with the locally-held private key.
- *
- * Returns null when no key is present — publishing without signing stays valid
- * for apps that have not adopted it, and `ota publish` reports which happened
- * rather than failing.
- */
-function signBundleHash(sha256Hex, keyDir) {
-    const privatePath = path.join(path.resolve(keyDir ?? KEY_DIR), PRIVATE_KEY_FILE);
-    if (!fs.existsSync(privatePath))
-        return null;
-    const privateKey = crypto.createPrivateKey(fs.readFileSync(privatePath));
-    // The signature covers the bundle's SHA-256, which the device already has from
-    // the check response and re-computes from the downloaded bytes. Signing the
-    // hash rather than the bundle keeps the CLI from re-reading 20 MB, and gives
-    // the device one value to verify that transitively covers the whole artifact.
-    const signature = crypto.sign(null, Buffer.from(sha256Hex, 'hex'), privateKey);
-    return signature.toString('hex');
-}
 //# sourceMappingURL=ota-keys.js.map