storebase-cli 1.1.0 → 1.2.0

package/README.md

@@ -7,7 +7,7 @@ The gateway provides encrypted Telegram settings at runtime. The CLI decrypts th
 ## Requirements
 
 - Node.js 18 or newer
-- Java `keytool`
+- Java 21 or newer `keytool` for the signing-profile import workflow (tested with Java 21; supports password delivery through `:env`)
 - Android SDK Build Tools `apksigner` (on `PATH`, or under `$ANDROID_SDK_ROOT/build-tools/` or `$ANDROID_HOME/build-tools/`)
 - A Telegram bot that is an administrator of the broadcast channel with permission to post
 - Telegram API ID and API hash, a stored bot MTProto session, and a separate personal-user read session
@@ -73,6 +73,52 @@ Supported categories: Education, Social, Productivity, Communication, Entertainm
 
 Use `--storage local` to opt into the older local JSON/files workflow. Its `--catalog` and `--assets-dir` options are only used in local mode.
 
+## Import a signing keystore once
+
+Version 1.2 adds a local encrypted signing vault. Create a named profile once, then select that profile for any app tag or release instead of repeatedly supplying a keystore file:
+
+```sh
+storebase-keystore import release --file /path/to/release.jks --alias release
+storebase-keystore list
+storebase-publish --signing-profile release \
+  --name "Example App" --version 2.0.0 --apk ./app-release.apk \
+  --avatar ./icon.png --category Productivity --description "Updated release."
+```
+
+Import prompts without echo for a vault passphrase (at least 12 characters, confirmed on creation), the keystore password, and the private-key password. Press Enter at the private-key prompt to reuse the keystore password. Use a long, unique vault passphrase; there is no saved unlock key or recovery service. Profile operations and profile-based publishing require an interactive terminal. Password arguments, password files, and environment variables are not accepted by these new profile commands. The older one-off `--keystore` workflow remains compatible, including its legacy runtime password variable; do not save signing passwords in `.env` or shell history.
+
+Java `keytool` validates the imported keystore, private-key alias, private-key password, and certificate. Multiple private-key entries require `--alias`. The CLI stores an encrypted copy rather than a source path, so the source keystore need not remain at the original location. `--signing-profile` cannot be combined with `--keystore` or `--alias`. Profiles are explicit, not automatically tied to app names or selected as a default.
+
+Publishing continues to **verify an already-signed APK**, not sign or re-sign it. It compares the APK certificate to the certificate validated when the profile was imported. Profile-based publishing never extracts the stored private key to disk. A different signer is rejected. Neither the keystore nor its passwords are uploaded to Telegram or the gateway; only the public certificate fingerprint belongs in release metadata.
+
+### Update, rotate, or remove
+
+```sh
+# Update passwords or replace the stored key after validating the replacement
+storebase-keystore import release --file /path/to/replacement.jks --alias release --replace
+
+# Re-encrypt every profile under a new vault passphrase
+storebase-keystore rekey
+
+# Delete a profile from the current encrypted vault
+storebase-keystore remove release
+
+# Print the location without unlocking the vault
+storebase-keystore location
+```
+
+Replacing and removing profiles require an explicit typed confirmation. Replacement validates the new keystore before atomically updating the vault; a failed import leaves the old profile intact. Changing the vault passphrase does not change the keystore's own passwords or signing key. Replacing a key does not generate Android signing lineage, change Play App Signing, or make existing installations accept a different certificate. Keep the old key backed up before rotation; otherwise updates to existing installs may become impossible.
+
+### Where secrets are stored
+
+The vault is `signing-vault.json` under `~/.local/share/storebase-cli/` on Linux, `~/Library/Application Support/storebase-cli/` on macOS, or `~/AppData/Local/storebase-cli/` on Windows. The CLI does not use the current project, repository, npm install directory, Telegram, or an environment-selected path for its production vault. It does not use an OS keychain: the separate master passphrase is requested for every command and is never stored.
+
+The complete profile collection—including keystore bytes, store password, private-key password, alias, and certificate—is encrypted with AES-256-GCM. A fresh random salt and nonce are used for each write; scrypt derives the encryption key from the master passphrase (N=32768, r=8, p=1). Authentication detects wrong passphrases and modified vaults. Writes are locked and atomic. On POSIX, the dedicated directory is mode 0700 and files are mode 0600; unsafe permissions, ownership, or symlink paths are refused. On Windows, keep the user-data directory restricted to your account using Windows permissions; ciphertext encryption is not a substitute for protecting the account.
+
+Import briefly creates a private mode-0700 temporary directory containing a mode-0600 copy of the keystore so Java can validate exactly the bytes being imported. It overwrites that copy best-effort and removes the directory in `finally`, on success or failure. Passwords are passed to Java through its child-process environment, never arguments, logs, or plaintext password files. Decrypted data exists in process memory while unlocked. Buffers are cleared best-effort, but JavaScript strings, OS swap, privileged process inspection, crashes, and malicious code running as your user cannot be made safe by this vault. Temporary files may remain after an uncatchable termination; remove orphaned `storebase-signing-import-*` directories from your OS temporary directory securely.
+
+Keep encrypted-vault backups and your master passphrase safe and separate. Losing the passphrase cannot be recovered by the CLI. Removing a profile or rekeying replaces the current vault but does not erase originals, old snapshots, filesystem journals, or backups; no forensic erasure is promised. The npm file allowlist contains only CLI JavaScript and documentation, never local vaults, `.env`, `.jks`, `.keystore`, `.p12`, or `.pfx` files.
+
 ## Telegram storage and versions
 
 Each release adds an APK document, an icon document, an optional delta document, then a JSON manifest text post. The manifest is posted last, so an incomplete upload is not listed as a release. The artifacts and metadata stay in Telegram; publishing a later version does not delete older versions.

package/bin/storebase-keystore.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+'use strict';
+const fs = require('node:fs/promises');
+const { SigningVault, vaultPath } = require('../lib/signing-vault');
+const { hidden, question, newPassphrase } = require('../lib/secure-prompt');
+const { profileName, importProfile, clearProfiles } = require('../lib/signing-profiles');
+
+function parseArguments(args) {
+  if (!args.length || args.includes('--help') || args.includes('-h')) return { command: 'help' };
+  const [command, ...rest] = args;
+  if (!['import', 'list', 'remove', 'rekey', 'location'].includes(command)) throw new Error('Unknown keystore command. Use --help.');
+  const result = { command };
+  if (['import', 'remove'].includes(command)) result.name = profileName(rest.shift());
+  while (rest.length) {
+    const arg = rest.shift();
+    if (command === 'import' && arg === '--replace' && !result.replace) result.replace = true;
+    else if (command === 'import' && ['--file', '--alias'].includes(arg)) {
+      const key = arg.slice(2);
+      if (result[key] !== undefined || !rest[0] || rest[0].startsWith('--')) throw new Error('Invalid or duplicate keystore option.');
+      result[key] = rest.shift();
+    } else throw new Error('Unexpected keystore argument. Password arguments are not supported.');
+  }
+  if (command === 'import' && !result.file) throw new Error('Import requires --file <keystore>.');
+  return result;
+}
+
+async function main(args = process.argv.slice(2)) {
+  const opts = parseArguments(args);
+  if (opts.command === 'help') {
+    process.stdout.write(`StoreBase encrypted signing profiles\n\nCommands:\n  storebase-keystore import <profile> --file <keystore> [--alias <alias>] [--replace]\n  storebase-keystore list\n  storebase-keystore remove <profile>\n  storebase-keystore rekey\n  storebase-keystore location\n\nSecrets are collected only through hidden terminal prompts. The encrypted vault is\noutside the project in your user data directory. Its master passphrase is never saved.\nUse --signing-profile <profile> with storebase-publish to reuse a verified certificate.\nImport --replace replaces a profile; it does not create Android signing lineage.\n`);
+    return;
+  }
+  if (opts.command === 'location') { process.stdout.write(`${vaultPath()}\n`); return; }
+  const vault = new SigningVault();
+  let exists = true;
+  try { await fs.lstat(vaultPath()); } catch (e) { if (e.code === 'ENOENT') exists = false; else throw e; }
+  if (!exists && opts.command !== 'import') throw new Error('No signing vault exists. Import a keystore first.');
+  let passphrase = exists ? await hidden('Vault passphrase') : await newPassphrase();
+  let data;
+  let imported;
+  try {
+    data = await vault.read(passphrase);
+    if (opts.command === 'list') {
+      for (const name of Object.keys(data.profiles).sort()) {
+        const p = data.profiles[name];
+        process.stdout.write(`${name}\talias=${JSON.stringify(p.alias)}\tSHA256=${p.fingerprint}\n`);
+      }
+      if (!Object.keys(data.profiles).length) process.stdout.write('No signing profiles stored.\n');
+    } else if (opts.command === 'import') {
+      const replacing = Object.hasOwn(data.profiles, opts.name);
+      if (replacing && !opts.replace) throw new Error('Profile already exists. Use --replace to explicitly rotate or update it.');
+      if (opts.replace) {
+        if (!replacing) throw new Error('Cannot replace a profile that does not exist.');
+        process.stdout.write('Replacing a signing key may prevent Android updates to existing installs. Keep a secure backup of the old key.\n');
+        if (await question(`Type REPLACE ${opts.name} to continue: `) !== `REPLACE ${opts.name}`) throw new Error('Cancelled.');
+      }
+      let storePassword = await hidden('Keystore password');
+      let keyPassword = await hidden('Private-key password (Enter to reuse keystore password)');
+      if (!keyPassword) keyPassword = storePassword;
+      try { imported = await importProfile(opts.file, storePassword, keyPassword, opts.alias); }
+      finally { storePassword = ''; keyPassword = ''; }
+      await vault.mutate(passphrase, (current) => {
+        if (JSON.stringify(current.profiles[opts.name]) !== JSON.stringify(data.profiles[opts.name])) throw new Error('Profile changed concurrently. Retry.');
+        current.profiles[opts.name] = imported;
+      });
+      process.stdout.write(`Signing profile ${opts.replace ? 'replaced' : 'imported'}. Original keystore was not changed or uploaded.\n`);
+    } else if (opts.command === 'remove') {
+      if (!Object.hasOwn(data.profiles, opts.name)) throw new Error('Signing profile not found.');
+      if (await question(`Type REMOVE ${opts.name} to delete its stored keystore and passwords: `) !== `REMOVE ${opts.name}`) throw new Error('Cancelled.');
+      await vault.mutate(passphrase, (current) => {
+        if (JSON.stringify(current.profiles[opts.name]) !== JSON.stringify(data.profiles[opts.name])) throw new Error('Profile changed concurrently. Retry.');
+        delete current.profiles[opts.name];
+      });
+      process.stdout.write('Signing profile removed. Original source files and backups are not deleted.\n');
+    } else if (opts.command === 'rekey') {
+      let replacement = await newPassphrase();
+      try { await vault.rekey(passphrase, replacement); } finally { replacement = ''; }
+      process.stdout.write('Vault passphrase changed; all profiles re-encrypted.\n');
+    }
+  } finally {
+    passphrase = '';
+    clearProfiles(data);
+    if (imported) { imported.keystore = ''; imported.storePassword = ''; imported.keyPassword = ''; }
+  }
+}
+if (require.main === module) main().catch((error) => {
+  process.stderr.write(`storebase-keystore: ${error.message}\n`); process.exitCode = 1;
+});
+module.exports = { parseArguments, main };

package/bin/storebase-publish.js

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 'use strict';
 
-require('dotenv').config();
-
 const { createInterface } = require('node:readline/promises');
 const { stdin, stdout } = require('node:process');
 const { connectTelegramFromGateway } = require('../lib/gateway-client');
 const { getPublisherEnvironment } = require('../lib/publisher-token');
+const { loadProfileEntry } = require('../lib/signing-profiles');
+const { hidden } = require('../lib/secure-prompt');
 const {
   CATEGORIES,
   inspectKeystore,
@@ -19,7 +19,7 @@ const { createTelegramStorage } = require('../lib/telegram-storage');
 
 const OPTION_NAMES = new Set([
   'name', 'avatar', 'version', 'apk', 'category', 'description', 'keystore', 'alias', 'storage', 'catalog', 'assets-dir',
-  'telegram-config',
+  'telegram-config', 'signing-profile',
   'android-version-code', 'minimum-android-version-code', 'delta', 'delta-base-version-code',
 ]);
 
@@ -58,7 +58,8 @@ Options (omitted app details are prompted interactively):
   --delta-base-version-code <n>         Installed base code for the patch
   --category <category>                 One of the 13 StoreBase categories
   --description <text>                  App description
-  --keystore <file>                     Signing keystore used for the APK
+  --signing-profile <profile>           Reuse a profile from storebase-keystore
+  --keystore <file>                     One-off signing keystore (no profile)
   --alias <name>                        Private-key alias, if the keystore has multiple
   --storage <backend>                   telegram (default) or local
   --telegram-config <mode>              gateway (default) or local direct Telegram settings
@@ -75,41 +76,6 @@ prompt or read from STOREBASE_KEYSTORE_PASSWORD.
 `);
 }
 
-function askHidden(label) {
-  if (!stdin.isTTY || typeof stdin.setRawMode !== 'function') {
-    return Promise.reject(new Error('Set STOREBASE_KEYSTORE_PASSWORD in the environment for non-interactive use.'));
-  }
-  return new Promise((resolve, reject) => {
-    let value = '';
-    let finished = false;
-    const cleanup = () => {
-      stdin.removeListener('data', onData);
-      try { stdin.setRawMode(false); } catch {}
-      stdin.pause();
-      stdout.write('\n');
-    };
-    const finish = (error) => {
-      if (finished) return;
-      finished = true;
-      cleanup();
-      if (error) reject(error);
-      else resolve(value);
-    };
-    const onData = (chunk) => {
-      for (const character of String(chunk)) {
-        if (character === '\u0003') return finish(new Error('Cancelled.'));
-        if (character === '\r' || character === '\n') return finish();
-        if (character === '\u007f' || character === '\b') value = value.slice(0, -1);
-        else if (character >= ' ') value += character;
-      }
-    };
-    stdout.write(`${label}: `);
-    stdin.setRawMode(true);
-    stdin.setEncoding('utf8');
-    stdin.resume();
-    stdin.on('data', onData);
-  });
-}
 
 async function collectInput(options) {
   const required = [
@@ -121,6 +87,7 @@ async function collectInput(options) {
     ['description', 'Description'],
     ['keystore', 'Signed keystore file path'],
   ];
+  if (options['signing-profile']) required.splice(required.findIndex(([key]) => key === 'keystore'), 1);
   const missing = required.filter(([key]) => !options[key]);
   if (missing.length && (!stdin.isTTY || !stdout.isTTY)) {
     throw new Error(`Missing required options: ${missing.map(([key]) => `--${key}`).join(', ')}. Prompts require an interactive terminal.`);
@@ -183,6 +150,7 @@ async function selectEntry(entries, aliasOption) {
 }
 
 async function main() {
+  require('dotenv').config();
   const parsed = parseArguments(process.argv.slice(2));
   if (parsed.help) return showHelp();
   const options = parsed.options;
@@ -194,12 +162,17 @@ async function main() {
   if (!['gateway', 'local'].includes(options['telegram-config'])) {
     throw new Error('--telegram-config must be either gateway or local.');
   }
+  if (options['signing-profile'] && (options.keystore || options.alias)) {
+    throw new Error('--signing-profile cannot be combined with --keystore or --alias.');
+  }
   const rawInput = await collectInput(options);
-  const input = await validateInput(rawInput);
-
-  const password = process.env.STOREBASE_KEYSTORE_PASSWORD ?? await askHidden('Keystore password (input hidden)');
-  const entries = await inspectKeystore(input.keystorePath, password);
-  const entry = await selectEntry(entries, input.alias);
+  let entry = options['signing-profile'] ? await loadProfileEntry(options['signing-profile']) : undefined;
+  const input = await validateInput(rawInput, { signingProfile: entry });
+  if (!entry) {
+    let password = process.env.STOREBASE_KEYSTORE_PASSWORD ?? await hidden('Keystore password');
+    try { entry = await selectEntry(await inspectKeystore(input.keystorePath, password), input.alias); }
+    finally { password = ''; }
+  }
   const certificate = verifyApkSignature(input.apkPath, entry);
   if (options.storage === 'local') {
     if (input.androidVersionCode !== undefined || input.deltaPath) {
@@ -236,10 +209,12 @@ async function main() {
       await disconnectTelegram(connection);
     }
   }
-  stdout.write('The keystore was used only to verify the APK signature; it was not copied.\n');
+  stdout.write('APK signing certificate verified. No keystore or signing passwords were uploaded.\n');
 }
 
-main().catch((error) => {
+if (require.main === module) main().catch((error) => {
   process.stderr.write(`storebase-publish: ${error.message}\n`);
   process.exitCode = 1;
 });
+
+module.exports = { parseArguments, collectInput };

package/lib/publisher.js

@@ -13,9 +13,6 @@ const { createReadStream } = require('node:fs');
 const { createHash, randomBytes } = require('node:crypto');
 const path = require('node:path');
 const { spawnSync } = require('node:child_process');
-const { createInterface } = require('node:readline/promises');
-const { stdin, stdout } = require('node:process');
-const { tmpdir } = require('node:os');
 
 const CATEGORIES = Object.freeze([
   'Education',
@@ -151,7 +148,8 @@ async function validateInput(raw, options = {}) {
   } else if (raw.deltaBaseVersionCode !== undefined && raw.deltaBaseVersionCode !== '') {
     fail('--delta-base-version-code requires --delta.');
   }
-  const keystorePath = await requireFile(raw.keystore, 'Signed keystore file', cwd);
+  if (options.signingProfile && (!/^[A-F0-9]{64}$/.test(options.signingProfile.fingerprint) || typeof options.signingProfile.alias !== 'string' || !options.signingProfile.alias)) fail('Invalid signing profile certificate.');
+  const keystorePath = options.signingProfile ? undefined : await requireFile(raw.keystore, 'Signed keystore file', cwd);
 
   return {
     id,
@@ -204,35 +202,31 @@ function parseApkSignerFingerprints(output) {
 }
 
 async function inspectKeystore(keystorePath, password) {
-  if (typeof password !== 'string') fail('A keystore password is required to verify the signing certificate.');
-  if (password.includes('\n') || password.includes('\r')) fail('Keystore passwords cannot contain line breaks.');
-  const fs = require('node:fs');
-  const folder = await require('node:fs/promises').mkdtemp(path.join(tmpdir(), 'storebase-keystore-'));
-  const passwordFile = path.join(folder, 'password');
+  if (typeof password !== 'string' || /[\r\n\0]/.test(password)) fail('A valid keystore password is required.');
   try {
-    await writeFile(passwordFile, `${password}\n`, { mode: 0o600, flag: 'wx' });
     const output = runTool('keytool', [
-      '-J-Duser.language=en',
-      '-J-Duser.country=US',
-      '-list',
-      '-v',
-      '-keystore',
-      keystorePath,
-      '-storepass:file',
-      passwordFile,
-    ]);
+      '-J-Duser.language=en', '-J-Duser.country=US', '-list', '-v',
+      '-keystore', keystorePath, '-storepass:env', 'STOREBASE_KEYTOOL_STORE_PASSWORD',
+    ], { env: { ...process.env, LC_ALL: 'C', LANG: 'C', STOREBASE_KEYTOOL_STORE_PASSWORD: password } });
     const entries = parseKeystoreEntries(output);
-    if (!entries.length) fail('The keystore has no readable private-key entry with a SHA-256 certificate.');
+    if (!entries.length) fail('No private-key certificate found.');
     return entries;
-  } finally {
-    // Best-effort overwrite before removal; the temporary directory is private (0700).
-    try {
-      const fd = fs.openSync(passwordFile, 'r+');
-      const size = fs.fstatSync(fd).size;
-      fs.writeSync(fd, Buffer.alloc(size));
-      fs.closeSync(fd);
-    } catch {}
-    await rm(folder, { recursive: true, force: true });
+  } catch {
+    fail('Could not inspect keystore. Check the password, file format, and Java keytool installation.');
+  }
+}
+
+async function verifyKeystoreKeyPassword(keystorePath, storePassword, alias, keyPassword) {
+  if (typeof keyPassword !== 'string' || /[\r\n\0]/.test(keyPassword)) fail('A valid private-key password is required.');
+  try {
+    runTool('keytool', [
+      '-J-Duser.language=en', '-J-Duser.country=US', '-certreq', '-keystore', keystorePath,
+      '-alias', alias, '-storepass:env', 'STOREBASE_KEYTOOL_STORE_PASSWORD',
+      '-keypass:env', 'STOREBASE_KEYTOOL_KEY_PASSWORD',
+    ], { env: { ...process.env, LC_ALL: 'C', LANG: 'C', STOREBASE_KEYTOOL_STORE_PASSWORD: storePassword,
+      STOREBASE_KEYTOOL_KEY_PASSWORD: keyPassword } });
+  } catch {
+    fail('Could not unlock the private key. Check its password and alias.');
   }
 }
 
@@ -390,4 +384,5 @@ module.exports = {
   validateInput,
   verifyApkSignature,
   inspectKeystore,
+  verifyKeystoreKeyPassword,
 };

package/lib/secure-prompt.js

@@ -0,0 +1,60 @@
+'use strict';
+const { stdin, stdout } = require('node:process');
+const { createInterface } = require('node:readline/promises');
+
+function hidden(label, input = stdin, output = stdout) {
+  if (!input.isTTY || !output.isTTY || typeof input.setRawMode !== 'function') {
+    return Promise.reject(new Error('Signing secrets require an interactive terminal; no password arguments or project files are accepted.'));
+  }
+  return new Promise((resolve, reject) => {
+    let value = '';
+    let done = false;
+    const wasRaw = Boolean(input.isRaw);
+    const finish = (error) => {
+      if (done) return;
+      done = true;
+      input.removeListener('data', onData);
+      input.removeListener('end', onEnd);
+      input.removeListener('error', onEnd);
+      try { input.setRawMode(wasRaw); } catch {}
+      input.pause();
+      output.write('\n');
+      const result = value;
+      value = '';
+      if (error) reject(error); else resolve(result);
+    };
+    const onEnd = () => finish(new Error('Secret input cancelled.'));
+    const onData = (chunk) => {
+      for (const ch of String(chunk)) {
+        if (ch === '\u0003' || ch === '\u0004') return onEnd();
+        if (ch === '\r' || ch === '\n') return finish();
+        if (ch === '\u007f' || ch === '\b') value = [...value].slice(0, -1).join('');
+        else if (ch >= ' ' && ch !== '\u001b') {
+          if (value.length >= 4096) return finish(new Error('Secret input is too long.'));
+          value += ch;
+        }
+      }
+    };
+    output.write(`${label} (input hidden): `);
+    input.setEncoding('utf8');
+    input.on('data', onData);
+    input.once('end', onEnd);
+    input.once('error', onEnd);
+    try { input.setRawMode(true); input.resume(); } catch { onEnd(); }
+  });
+}
+
+async function question(label) {
+  if (!stdin.isTTY || !stdout.isTTY) throw new Error('This operation requires an interactive terminal.');
+  const rl = createInterface({ input: stdin, output: stdout });
+  try { return (await rl.question(label)).trim(); } finally { rl.close(); }
+}
+
+async function newPassphrase() {
+  const passphrase = await hidden('New vault passphrase (at least 12 characters)');
+  if ([...passphrase].length < 12) throw new Error('Vault passphrase must be at least 12 characters.');
+  const confirm = await hidden('Confirm vault passphrase');
+  if (passphrase !== confirm) throw new Error('Vault passphrases do not match.');
+  return passphrase;
+}
+module.exports = { hidden, question, newPassphrase };

package/lib/signing-profiles.js

@@ -0,0 +1,83 @@
+'use strict';
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const os = require('node:os');
+const { inspectKeystore, verifyKeystoreKeyPassword } = require('./publisher');
+
+function profileName(value) {
+  if (typeof value !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(value)) {
+    throw new Error('Profile names must be 1–64 letters, numbers, underscores, or hyphens.');
+  }
+  if (['__proto__', 'constructor', 'prototype'].includes(value)) throw new Error('Reserved profile name.');
+  return value;
+}
+
+async function importProfile(file, storePassword, keyPassword, alias, options = {}) {
+  const handle = await fs.open(path.resolve(file), 'r');
+  let bytes;
+  let folder;
+  try {
+    const info = await handle.stat();
+    if (!info.isFile() || info.size < 1 || info.size > 8 * 1024 * 1024) throw new Error('Keystore must be a non-empty file of at most 8 MiB.');
+    const bounded = Buffer.alloc(8 * 1024 * 1024 + 1);
+    let count = 0;
+    try {
+      while (count < bounded.length) {
+        const { bytesRead } = await handle.read(bounded, count, bounded.length - count, null);
+        if (!bytesRead) break;
+        count += bytesRead;
+      }
+      if (count > 8 * 1024 * 1024) throw new Error('Keystore exceeds the size limit.');
+      if (!count) throw new Error('Keystore is empty.');
+      bytes = Buffer.from(bounded.subarray(0, count));
+    } finally { bounded.fill(0); }
+    folder = await fs.mkdtemp(path.join(os.tmpdir(), 'storebase-signing-import-'));
+    await fs.chmod(folder, 0o700);
+    const temporary = path.join(folder, 'keystore');
+    await fs.writeFile(temporary, bytes, { mode: 0o600, flag: 'wx' });
+    const entries = await (options.inspect || inspectKeystore)(temporary, storePassword);
+    let selected;
+    if (alias) selected = entries.find((entry) => entry.alias === alias);
+    else if (entries.length === 1) selected = entries[0];
+    if (!selected) throw new Error('Choose a valid private-key alias with --alias (required for multiple entries).');
+    await (options.verify || verifyKeystoreKeyPassword)(temporary, storePassword, selected.alias, keyPassword);
+    return { keystore: bytes.toString('base64'), storePassword, keyPassword,
+      alias: selected.alias, fingerprint: selected.fingerprint };
+  } finally {
+    await handle.close();
+    if (folder) {
+      try {
+        const file = path.join(folder, 'keystore');
+        const handle = await fs.open(file, 'r+');
+        try { await handle.write(Buffer.alloc(bytes?.length || 0), 0, bytes?.length || 0, 0); } finally { await handle.close(); }
+      } catch {}
+      await fs.rm(folder, { recursive: true, force: true });
+    }
+    bytes?.fill(0);
+  }
+}
+
+function entryForProfile(data, name) {
+  profileName(name);
+  if (!Object.hasOwn(data.profiles, name)) throw new Error('Signing profile not found. Import it with storebase-keystore import.');
+  const profile = data.profiles[name];
+  // Publishing only needs the certificate verified at import time, not a plaintext private key.
+  return { alias: profile.alias, fingerprint: profile.fingerprint };
+}
+
+function clearProfiles(data) {
+  if (!data?.profiles) return;
+  for (const profile of Object.values(data.profiles)) {
+    profile.keystore = ''; profile.storePassword = ''; profile.keyPassword = '';
+  }
+}
+async function loadProfileEntry(name, options = {}) {
+  profileName(name);
+  const vault = options.vault || new (require('./signing-vault').SigningVault)();
+  const prompt = options.prompt || require('./secure-prompt').hidden;
+  let passphrase = await prompt('Vault passphrase');
+  let data;
+  try { data = await vault.read(passphrase); return entryForProfile(data, name); }
+  finally { passphrase = ''; clearProfiles(data); }
+}
+module.exports = { profileName, importProfile, entryForProfile, clearProfiles, loadProfileEntry };

package/lib/signing-vault.js

@@ -0,0 +1,372 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { promisify } = require('node:util');
+
+const scrypt = promisify(crypto.scrypt);
+const VERSION = 1;
+const SCRYPT_N = 32768;
+const SCRYPT_R = 8;
+const SCRYPT_P = 1;
+const SCRYPT_MAXMEM = 64 * 1024 * 1024;
+const MAX_FILE_SIZE = 32 * 1024 * 1024;
+const MAX_PAYLOAD_SIZE = 31 * 1024 * 1024;
+const MAX_KEYSTORE_SIZE = 8 * 1024 * 1024;
+const AAD = Buffer.from('storebase-signing-vault:v1:scrypt-32768-8-1:aes-256-gcm', 'utf8');
+const UNLOCK_ERROR = 'Signing vault could not be unlocked; passphrase may be incorrect or vault data is damaged.';
+const LOCK_ERROR = 'Signing vault is locked by another operation; retry after it finishes.';
+
+function vaultPath() {
+  const home = os.homedir();
+  if (process.platform === 'win32') return path.join(home, 'AppData', 'Local', 'storebase-cli', 'signing-vault.json');
+  if (process.platform === 'darwin') return path.join(home, 'Library', 'Application Support', 'storebase-cli', 'signing-vault.json');
+  return path.join(home, '.local', 'share', 'storebase-cli', 'signing-vault.json');
+}
+
+function checkPassphrase(passphrase) {
+  if (typeof passphrase !== 'string' || [...passphrase].length < 12) {
+    throw new Error('Signing vault passphrase must be at least 12 characters.');
+  }
+}
+
+function validatePayload(data) {
+  if (!data || typeof data !== 'object' || Array.isArray(data)
+      || Object.getPrototypeOf(data) !== Object.prototype
+      || Object.keys(data).length !== 1 || !Object.hasOwn(data, 'profiles')) {
+    throw new Error('Signing vault data must contain only a profiles object.');
+  }
+  const profiles = data.profiles;
+  if (!profiles || typeof profiles !== 'object' || Array.isArray(profiles)
+      || Object.getPrototypeOf(profiles) !== Object.prototype) {
+    throw new Error('Signing vault profiles must be an object.');
+  }
+  for (const [name, profile] of Object.entries(profiles)) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(name)
+        || ['constructor', 'prototype', '__proto__'].includes(name)) {
+      throw new Error('Signing vault contains an invalid profile name.');
+    }
+    const fields = ['keystore', 'storePassword', 'keyPassword', 'alias', 'fingerprint'];
+    if (!profile || typeof profile !== 'object' || Array.isArray(profile)
+        || Object.getPrototypeOf(profile) !== Object.prototype
+        || Object.keys(profile).length !== fields.length
+        || fields.some((field) => !Object.hasOwn(profile, field))) {
+      throw new Error(`Signing profile "${name}" has an invalid schema.`);
+    }
+    if (typeof profile.keystore !== 'string' || profile.keystore.length === 0
+        || profile.keystore.length > Math.ceil(MAX_KEYSTORE_SIZE / 3) * 4
+        || /[^A-Za-z0-9+/=]/.test(profile.keystore)) {
+      throw new Error(`Signing profile "${name}" has invalid keystore data.`);
+    }
+    const keystoreBytes = Buffer.from(profile.keystore, 'base64');
+    if (!keystoreBytes.length || keystoreBytes.length > MAX_KEYSTORE_SIZE
+        || keystoreBytes.toString('base64') !== profile.keystore) {
+      keystoreBytes.fill(0);
+      throw new Error(`Signing profile "${name}" has invalid keystore data.`);
+    }
+    keystoreBytes.fill(0);
+    for (const field of fields.slice(1)) {
+      if (typeof profile[field] !== 'string' || profile[field].length > 4096
+          || (field !== 'storePassword' && field !== 'keyPassword' && profile[field].length === 0)
+          || (field === 'alias' && /[\x00-\x1f\x7f]/.test(profile[field]))
+          || (field === 'fingerprint' && !/^[A-F0-9]{64}$/.test(profile[field]))) {
+        throw new Error(`Signing profile "${name}" has an invalid ${field}.`);
+      }
+    }
+  }
+  const serialized = JSON.stringify(data);
+  if (Buffer.byteLength(serialized, 'utf8') > MAX_PAYLOAD_SIZE) {
+    throw new Error('Signing vault data exceeds the maximum supported size.');
+  }
+  return serialized;
+}
+
+function assertSafeStat(stat, { directory = false } = {}) {
+  if (directory ? !stat.isDirectory() : !stat.isFile()) {
+    throw new Error('Signing vault path has an unsafe file type.');
+  }
+  if (process.platform !== 'win32') {
+    if (typeof process.getuid === 'function' && stat.uid !== process.getuid()) {
+      throw new Error('Signing vault path is not owned by the current user.');
+    }
+    const mode = stat.mode & 0o777;
+    if ((mode & 0o077) !== 0 || (directory && (mode & 0o700) !== 0o700)) {
+      throw new Error('Signing vault path has unsafe permissions.');
+    }
+  }
+}
+
+async function lstatIfExists(target) {
+  try {
+    return await fs.lstat(target);
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+async function ensureParent(parent, create) {
+  const absolute = path.resolve(parent);
+  const parsed = path.parse(absolute);
+  let current = parsed.root;
+  const components = absolute.slice(parsed.root.length).split(path.sep).filter(Boolean);
+  for (let index = 0; index < components.length; index += 1) {
+    current = path.join(current, components[index]);
+    let stat = await lstatIfExists(current);
+    if (!stat && create) {
+      try {
+        await fs.mkdir(current, { mode: 0o700 });
+      } catch (error) {
+        if (error.code !== 'EEXIST') throw error;
+      }
+      stat = await lstatIfExists(current);
+    }
+    if (!stat) return false;
+    if (stat.isSymbolicLink()) throw new Error('Signing vault parent directory must not be a symlink.');
+    if (!stat.isDirectory()) throw new Error('Signing vault parent path is not a directory.');
+    if (index === components.length - 1) assertSafeStat(stat, { directory: true });
+  }
+  return true;
+}
+
+async function checkVaultFile(filePath) {
+  const stat = await lstatIfExists(filePath);
+  if (!stat) return null;
+  if (stat.isSymbolicLink()) throw new Error('Signing vault file must not be a symlink.');
+  assertSafeStat(stat);
+  if (process.platform !== 'win32' && stat.nlink !== 1) {
+    throw new Error('Signing vault file has an unsafe link count.');
+  }
+  return stat;
+}
+
+async function deriveKey(passphrase, salt) {
+  const passphraseBytes = Buffer.from(passphrase, 'utf8');
+  try {
+    return await scrypt(passphraseBytes, salt, 32, {
+      N: SCRYPT_N, r: SCRYPT_R, p: SCRYPT_P, maxmem: SCRYPT_MAXMEM,
+    });
+  } finally {
+    passphraseBytes.fill(0);
+  }
+}
+
+function decodeBase64(value, expectedLength) {
+  if (typeof value !== 'string' || /[^A-Za-z0-9+/=]/.test(value)) return null;
+  const result = Buffer.from(value, 'base64');
+  if (result.toString('base64') !== value || (expectedLength !== undefined && result.length !== expectedLength)) {
+    result.fill(0);
+    return null;
+  }
+  return result;
+}
+
+function validateEnvelope(envelope) {
+  if (!envelope || typeof envelope !== 'object' || Array.isArray(envelope)
+      || Object.getPrototypeOf(envelope) !== Object.prototype
+      || Object.keys(envelope).sort().join(',') !== 'cipher,kdf,version'
+      || envelope.version !== VERSION) throw new Error(UNLOCK_ERROR);
+  const { kdf, cipher } = envelope;
+  if (!kdf || typeof kdf !== 'object' || Array.isArray(kdf)
+      || Object.keys(kdf).sort().join(',') !== 'N,name,p,r,salt'
+      || kdf.name !== 'scrypt' || kdf.N !== SCRYPT_N || kdf.r !== SCRYPT_R || kdf.p !== SCRYPT_P
+      || !cipher || typeof cipher !== 'object' || Array.isArray(cipher)
+      || Object.keys(cipher).sort().join(',') !== 'data,iv,name,tag' || cipher.name !== 'aes-256-gcm') {
+    throw new Error(UNLOCK_ERROR);
+  }
+  const salt = decodeBase64(kdf.salt, 16);
+  const iv = decodeBase64(cipher.iv, 12);
+  const tag = decodeBase64(cipher.tag, 16);
+  const ciphertext = decodeBase64(cipher.data);
+  if (!salt || !iv || !tag || !ciphertext || ciphertext.length > MAX_PAYLOAD_SIZE) {
+    for (const buffer of [salt, iv, tag, ciphertext]) buffer?.fill(0);
+    throw new Error(UNLOCK_ERROR);
+  }
+  return { salt, iv, tag, ciphertext };
+}
+
+async function decryptEnvelope(raw, passphrase) {
+  let plaintext;
+  let key;
+  let parsed;
+  let pieces;
+  try {
+    if (raw.length > MAX_FILE_SIZE) throw new Error(UNLOCK_ERROR);
+    parsed = JSON.parse(raw.toString('utf8'));
+    pieces = validateEnvelope(parsed);
+    key = await deriveKey(passphrase, pieces.salt);
+    const decipher = crypto.createDecipheriv('aes-256-gcm', key, pieces.iv);
+    decipher.setAAD(AAD);
+    decipher.setAuthTag(pieces.tag);
+    plaintext = Buffer.concat([decipher.update(pieces.ciphertext), decipher.final()]);
+    if (plaintext.length > MAX_PAYLOAD_SIZE) throw new Error(UNLOCK_ERROR);
+    const value = JSON.parse(plaintext.toString('utf8'));
+    validatePayload(value);
+    return value;
+  } catch {
+    throw new Error(UNLOCK_ERROR);
+  } finally {
+    key?.fill(0);
+    plaintext?.fill(0);
+    if (pieces) for (const value of Object.values(pieces)) value.fill(0);
+  }
+}
+
+async function encryptPayload(data, passphrase) {
+  const serialized = validatePayload(data);
+  const plaintext = Buffer.from(serialized, 'utf8');
+  const salt = crypto.randomBytes(16);
+  const iv = crypto.randomBytes(12);
+  let key;
+  let ciphertext;
+  try {
+    key = await deriveKey(passphrase, salt);
+    const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+    cipher.setAAD(AAD);
+    ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    const envelope = {
+      version: VERSION,
+      kdf: { name: 'scrypt', N: SCRYPT_N, r: SCRYPT_R, p: SCRYPT_P, salt: salt.toString('base64') },
+      cipher: { name: 'aes-256-gcm', iv: iv.toString('base64'), tag: cipher.getAuthTag().toString('base64'), data: ciphertext.toString('base64') },
+    };
+    const output = Buffer.from(JSON.stringify(envelope), 'utf8');
+    if (output.length > MAX_FILE_SIZE) {
+      output.fill(0);
+      throw new Error('Signing vault data exceeds the maximum supported size.');
+    }
+    return output;
+  } finally {
+    plaintext.fill(0);
+    salt.fill(0);
+    iv.fill(0);
+    key?.fill(0);
+    ciphertext?.fill(0);
+  }
+}
+
+function clearData(data) {
+  if (!data?.profiles || typeof data.profiles !== 'object') return;
+  for (const profile of Object.values(data.profiles)) {
+    if (!profile || typeof profile !== 'object') continue;
+    for (const field of ['keystore', 'storePassword', 'keyPassword']) if (Object.hasOwn(profile, field)) profile[field] = '';
+  }
+}
+
+class SigningVault {
+  constructor({ filePath } = {}) {
+    this.filePath = path.resolve(filePath || vaultPath());
+  }
+
+  async _read(passphrase) {
+    checkPassphrase(passphrase);
+    const parentExists = await ensureParent(path.dirname(this.filePath), false);
+    if (!parentExists) return { profiles: {} };
+    const stat = await checkVaultFile(this.filePath);
+    if (!stat) return { profiles: {} };
+    if (stat.size > MAX_FILE_SIZE) throw new Error(UNLOCK_ERROR);
+    let handle;
+    let raw;
+    try {
+      const noFollow = fs.constants?.O_NOFOLLOW || 0;
+      handle = await fs.open(this.filePath, require('node:fs').constants.O_RDONLY | noFollow);
+      const opened = await handle.stat();
+      assertSafeStat(opened);
+      if (opened.size > MAX_FILE_SIZE) throw new Error(UNLOCK_ERROR);
+      raw = await handle.readFile();
+      return await decryptEnvelope(raw, passphrase);
+    } finally {
+      raw?.fill(0);
+      await handle?.close();
+    }
+  }
+
+  async read(passphrase) {
+    return this._read(passphrase);
+  }
+
+  async _write(data, passphrase) {
+    const output = await encryptPayload(data, passphrase);
+    const parent = path.dirname(this.filePath);
+    let tempPath;
+    let handle;
+    try {
+      // The parent and target are checked immediately before creating the atomic replacement.
+      await ensureParent(parent, true);
+      await checkVaultFile(this.filePath);
+      tempPath = path.join(parent, `.${path.basename(this.filePath)}.${process.pid}.${crypto.randomBytes(8).toString('hex')}.tmp`);
+      handle = await fs.open(tempPath, 'wx', 0o600);
+      if (process.platform !== 'win32') await handle.chmod(0o600);
+      await handle.writeFile(output);
+      await handle.sync();
+      await handle.close();
+      handle = null;
+      await checkVaultFile(this.filePath);
+      await fs.rename(tempPath, this.filePath);
+      tempPath = null;
+      if (process.platform !== 'win32') {
+        const dirHandle = await fs.open(parent, 'r');
+        try { await dirHandle.sync(); } finally { await dirHandle.close(); }
+      }
+    } finally {
+      output.fill(0);
+      await handle?.close().catch(() => {});
+      if (tempPath) await fs.unlink(tempPath).catch(() => {});
+    }
+  }
+
+  async _withLock(callback) {
+    await ensureParent(path.dirname(this.filePath), true);
+    const lockPath = `${this.filePath}.lock`;
+    let handle;
+    let lockStat;
+    try {
+      handle = await fs.open(lockPath, 'wx', 0o600);
+      if (process.platform !== 'win32') await handle.chmod(0o600);
+      lockStat = await handle.stat();
+      assertSafeStat(lockStat);
+    } catch (error) {
+      await handle?.close().catch(() => {});
+      if (error.code === 'EEXIST') throw new Error(LOCK_ERROR);
+      throw error;
+    }
+    try {
+      return await callback();
+    } finally {
+      await handle.close().catch(() => {});
+      try {
+        const current = await fs.lstat(lockPath);
+        if (!current.isSymbolicLink() && current.dev === lockStat.dev && current.ino === lockStat.ino) await fs.unlink(lockPath);
+      } catch { /* Best-effort cleanup; never remove a lock we do not own. */ }
+    }
+  }
+
+  async mutate(passphrase, updater) {
+    checkPassphrase(passphrase);
+    if (typeof updater !== 'function') throw new Error('Signing vault mutation callback is required.');
+    return this._withLock(async () => {
+      const data = await this._read(passphrase);
+      let updated;
+      let detached;
+      try {
+        const replacement = await updater(data);
+        updated = replacement === undefined ? data : replacement;
+        const serialized = validatePayload(updated);
+        detached = JSON.parse(serialized);
+        await this._write(detached, passphrase);
+      } finally { clearData(data); clearData(updated); clearData(detached); }
+    });
+  }
+
+  async rekey(oldPassphrase, newPassphrase) {
+    checkPassphrase(oldPassphrase);
+    checkPassphrase(newPassphrase);
+    return this._withLock(async () => {
+      const data = await this._read(oldPassphrase);
+      try { await this._write(data, newPassphrase); } finally { clearData(data); }
+    });
+  }
+}
+
+module.exports = { SigningVault, vaultPath };

package/package.json

@@ -1,17 +1,18 @@
 {
   "name": "storebase-cli",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Publish signed Android apps to a versioned Telegram-backed StoreBase catalog",
   "license": "UNLICENSED",
   "private": false,
   "type": "commonjs",
   "bin": {
     "storebase-publish": "bin/storebase-publish.js",
-    "storebase-telegram": "bin/storebase-telegram.js"
+    "storebase-telegram": "bin/storebase-telegram.js",
+    "storebase-keystore": "bin/storebase-keystore.js"
   },
   "files": [
-    "bin/",
-    "lib/",
+    "bin/*.js",
+    "lib/*.js",
     "README.md"
   ],
   "engines": {