storebase-cli 1.1.0 → 1.3.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
@@ -34,6 +34,17 @@ To install this checkout globally:
 npm install --global ./cli
 ```
 
+## Agent skill: complete end-to-end workflows
+
+Version 1.3 bundles a real agent skill with YAML frontmatter and detailed workflow references. It covers CLI setup, runtime publisher keys, encrypted gateway bootstrap, signing-profile import/reuse/replacement/rekey/removal, approved APK/icon/metadata publishing, immutable Telegram history and deltas, default-version pins, catalog downloads, Apps/Explore limitations, Android direct Telegram access and install approval/reopen behavior, local Wasmer deployment, and source/release testing.
+
+```sh
+storebase-skill path
+storebase-skill install --dir ./agent-skills
+```
+
+`path` prints the installed `SKILL.md`. `install --dir <skills-root>` copies the skill into `<skills-root>/storebase/` and refuses to overwrite an existing destination. Choose the skills root supported by your agent and enable/reload it there when required; this command does not change agent configuration. Upgrading npm updates the bundled skill, not previously copied installations. The skill's entry point is [`skills/storebase/SKILL.md`](skills/storebase/SKILL.md); its linked references contain full command examples and troubleshooting. Multi-line shell examples in this README use POSIX syntax; use a single line or PowerShell continuations on Windows. Native Windows APK-tool discovery and Android installation must be verified separately.
+
 ## Runtime configuration
 
 Gateway mode is the default. `storebase-telegram list`, `metadata`, and `download` use the read-only catalog bootstrap and do not require publisher credentials. `storebase-publish` and `storebase-telegram pin` use the separate publisher bootstrap and require the same high-entropy `STOREBASE_GATEWAY_PUBLISH_TOKEN` in the gateway's secret environment and the CLI runtime. Keep that token in a secret manager or mode-0600 `.env` file; do not commit it. In an interactive terminal, these write commands prompt for it without echoing it when the environment variable is absent; non-interactive runs must set the environment variable. The gateway URL is optional and defaults to `https://storebase.wasmer.app`.
@@ -73,6 +84,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/bin/storebase-skill.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+
+const source = path.resolve(__dirname, '..', 'skills', 'storebase');
+const DOCUMENTS = [
+  'SKILL.md',
+  'references/cli-workflows.md',
+  'references/runtime-and-android.md',
+  'references/updates-and-development.md',
+];
+
+function parseArguments(args) {
+  if (!args.length || (args.length === 1 && ['--help', '-h'].includes(args[0]))) return { command: 'help' };
+  if (args.length === 1 && args[0] === 'path') return { command: 'path' };
+  if (args.length === 3 && args[0] === 'install' && args[1] === '--dir' && args[2].trim() && !args[2].startsWith('--')) {
+    return { command: 'install', root: path.resolve(args[2]) };
+  }
+  throw new Error('Use storebase-skill path or storebase-skill install --dir <skills-root>.');
+}
+
+async function main(args = process.argv.slice(2)) {
+  const options = parseArguments(args);
+  if (options.command === 'help') {
+    process.stdout.write(`StoreBase agent skill\n\nUsage:\n  storebase-skill path\n  storebase-skill install --dir <skills-root>\n\npath prints the bundled SKILL.md location. install copies the skill into the\nstorebase child of the chosen root. Existing destinations are never overwritten.\nEnable or reload the skill in your agent separately when required.\n`);
+    return;
+  }
+  if (options.command === 'path') {
+    await fs.access(path.join(source, 'SKILL.md'));
+    process.stdout.write(`${path.join(source, 'SKILL.md')}\n`);
+    return;
+  }
+  // Read only the explicitly packaged documents, never arbitrary local files.
+  const documents = await Promise.all(DOCUMENTS.map(async name => [name, await fs.readFile(path.join(source, name))]));
+  await fs.mkdir(options.root, { recursive: true });
+  const destination = path.join(options.root, 'storebase');
+  try {
+    await fs.mkdir(destination);
+  } catch (error) {
+    if (error.code === 'EEXIST') throw new Error(`Skill destination already exists; review or back it up before replacing it: ${destination}`);
+    throw error;
+  }
+  try {
+    for (const [name, content] of documents) {
+      const file = path.join(destination, name);
+      await fs.mkdir(path.dirname(file), { recursive: true });
+      await fs.writeFile(file, content, { flag: 'wx' });
+    }
+  } catch (error) {
+    await fs.rm(destination, { recursive: true, force: true });
+    throw error;
+  }
+  process.stdout.write(`StoreBase skill installed: ${path.join(destination, 'SKILL.md')}\nEnable or reload it using your agent's skill settings when required.\n`);
+}
+
+if (require.main === module) main().catch(error => {
+  process.stderr.write(`storebase-skill: ${error.message}\n`);
+  process.exitCode = 1;
+});
+
+module.exports = { parseArguments, main, DOCUMENTS };

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 };