storebase-cli 1.0.0 → 1.2.0

package/README.md

@@ -1,41 +1,57 @@
 # StoreBase App Publisher CLI
 
-A dependency-free npm CLI for validating and releasing a signed Android APK into a local StoreBase app-list catalog. This package is intentionally isolated under `cli/`; it does not change the StoreBase frontend.
+A Node.js CLI for validating signed Android releases and storing APKs, optional deltas, app icons, and version metadata directly in a Telegram broadcast channel. Release manifests are immutable and versioned; the CLI preserves every release and can keep a separate Telegram record identifying an app's default pinned version.
+
+The gateway provides encrypted Telegram settings at runtime. The CLI decrypts them in memory, connects directly to Telegram, and never writes Telegram credentials to disk. The gateway does not relay APKs or catalog metadata.
 
 ## 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
+
+## Install and test
+
+For local development:
+
+```sh
+cd cli
+npm install
+npm test
+```
+
+Install the published package globally with:
+
+```sh
+npm install --global storebase-cli
+```
 
-## Install from this repository
+To install this checkout globally:
 
 ```sh
 npm install --global ./cli
-storebase-publish
 ```
 
-The CLI prompts for the app name, avatar image, version, APK, category, description, and signing keystore. The supported categories match StoreBase Explore:
+## Runtime configuration
 
-- Education
-- Social
-- Productivity
-- Communication
-- Entertainment
-- Games
-- Business
-- Shopping
-- Finance
-- Utilities
-- Health & Fitness
-- Travel & Navigation
-- AI & Machine Learning
+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`.
 
-The keystore password is requested with hidden terminal input. For automation, set `STOREBASE_KEYSTORE_PASSWORD` in the process environment instead. **Do not put the password in a command-line argument.** If the keystore contains more than one private-key alias, the CLI asks which alias to use (or accepts `--alias`).
+```dotenv
+STOREBASE_GATEWAY_URL=https://storebase.wasmer.app
+STOREBASE_GATEWAY_PUBLISH_TOKEN=<same-secret-configured-on-the-gateway>
+```
+
+The gateway must also have its existing Telegram environment configured: `STOREBASE_TELEGRAM_API_ID`, `STOREBASE_TELEGRAM_API_HASH`, `STOREBASE_TELEGRAM_SESSION` (the bot's stored MTProto session), `STOREBASE_TELEGRAM_READ_SESSION` (a personal-user session with channel access), and `STOREBASE_TELEGRAM_CHANNEL`. The publisher bootstrap returns only the API ID/hash, bot session, reader session, and channel; it excludes the bot token. The shared publisher token is checked before those settings are returned. Do not place credentials in source code, command-line arguments, or this npm package.
+
+At runtime, the CLI creates an ephemeral RSA keypair, requests settings over HTTPS, decrypts the AES-GCM envelope in memory, and passes the values directly to the Telegram client. It does not persist decrypted settings or include them in CLI output. This remains a personal-use design, not a production identity or device-attestation system. Anyone who obtains the publisher token can obtain the encrypted bot session; keep that token restricted and rotate it if exposed.
 
-The CLI runs `keytool` and `apksigner`, and refuses to add the release unless the APK is signed and its signer certificate matches the selected private-key certificate in the provided keystore. The password is written briefly to a mode-0600 temporary file for `keytool`, then the file is overwritten best-effort and removed. The keystore itself is never copied to the catalog.
+For a direct local Telegram connection instead, place the Telegram variables above in the CLI environment and pass `--telegram-config local`. The gateway remains the default for publishing and catalog commands.
 
-## Non-interactive example
+## Publish a release
+
+The publisher prompts for missing app details. The signing-keystore password is read through hidden terminal input or from `STOREBASE_KEYSTORE_PASSWORD`; it is never accepted as a CLI option. If a keystore has multiple private-key aliases, use `--alias` or select one interactively.
 
 ```sh
 STOREBASE_KEYSTORE_PASSWORD="$KEYSTORE_PASSWORD" storebase-publish \
@@ -49,18 +65,85 @@ STOREBASE_KEYSTORE_PASSWORD="$KEYSTORE_PASSWORD" storebase-publish \
   --alias release
 ```
 
-Available options: `--name`, `--avatar`, `--version`, `--apk`, `--category`, `--description`, `--keystore`, `--alias`, `--catalog`, `--assets-dir`, and `--help`.
+The CLI runs `keytool` and `apksigner`, and refuses to publish unless the APK signer certificate matches the selected private-key certificate in the provided keystore. The keystore is used only for verification and is never uploaded.
+
+For the `StoreBase` app, provide `--android-version-code` on every release. A matching `.sbd` patch can be attached using `--delta <file.sbd> --delta-base-version-code <installed-code>`; the CLI stores the patch in the same Telegram channel and includes its message ID, hash, size, base code, package ID, and release code in the versioned manifest.
+
+Supported categories: Education, Social, Productivity, Communication, Entertainment, Games, Business, Shopping, Finance, Utilities, Health & Fitness, Travel & Navigation, and AI & Machine Learning.
+
+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.
 
-## Output
+### Where secrets are stored
 
-By default, running from a project directory creates or updates:
+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.
 
-- `storebase-app-list.json` — schema version 1, with one latest-version listing per app name/slug.
-- `storebase-app-assets/<app-id>/<version>/` — content-addressed APK and avatar files referenced by the JSON manifest.
+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.
 
-The catalog entry contains the app name, avatar path, version, APK path, category, description, the public SHA-256 signing-certificate fingerprint, and publish timestamp. Releasing the same app again updates its catalog entry; a different version gets a separate artifact path. The previous artifacts are not removed.
+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.
+
+Each manifest begins with `STOREBASE_MANIFEST_V1` and includes app metadata, version, publish time, signing-certificate fingerprint, and Telegram message IDs, sizes, and SHA-256 hashes for its artifacts. StoreBase Android releases also include the package name, Android `versionCode`, and optional minimum required code. Publishing the same app/version and content is idempotent; changed content cannot overwrite an existing version.
+
+An optional `STOREBASE_DEFAULT_VERSION_V1` message stores the default-version pointer separately, so pinning a release never edits or replaces its immutable manifest. If no explicit pin exists, the newest release is the default. Use `storebase-telegram pin <app-id> <version>` to set or change the default. The CLI list shows every version and the default; metadata and downloads without `--version` use that default.
+
+```sh
+# See all apps, versions, and each app's default version
+storebase-telegram list
+
+# Select a default version; this adds a small metadata record in Telegram
+storebase-telegram pin storebase 1.2.0
+
+# Omit --version to use the pinned default (or newest release if unpinned)
+storebase-telegram metadata storebase
+storebase-telegram download storebase --kind apk --out ./downloads
+
+# Select a specific historical version
+storebase-telegram metadata storebase --version 1.1.0
+storebase-telegram download storebase --version 1.1.0 --kind all --out ./downloads
+```
 
-The current StoreBase repository has no app-list API or deployment endpoint. Therefore this CLI creates a **local app-list release artifact only**; it does not upload to a server, publish the npm package, or make the app appear in the existing UI yet. A later frontend/backend change can consume `storebase-app-list.json` without changing this CLI's input contract.
+Downloads are size- and SHA-256-verified. Filenames include the app ID, version, artifact kind, and content hash to avoid replacing a different release.
 
 ## Development
 

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

@@ -3,6 +3,10 @@
 
 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,
@@ -10,9 +14,13 @@ const {
   validateInput,
   verifyApkSignature,
 } = require('../lib/publisher');
+const { connectTelegram, disconnectTelegram } = require('../lib/telegram-client');
+const { createTelegramStorage } = require('../lib/telegram-storage');
 
 const OPTION_NAMES = new Set([
-  'name', 'avatar', 'version', 'apk', 'category', 'description', 'keystore', 'alias', 'catalog', 'assets-dir',
+  'name', 'avatar', 'version', 'apk', 'category', 'description', 'keystore', 'alias', 'storage', 'catalog', 'assets-dir',
+  'telegram-config', 'signing-profile',
+  'android-version-code', 'minimum-android-version-code', 'delta', 'delta-base-version-code',
 ]);
 
 function parseArguments(args) {
@@ -34,45 +42,41 @@ function parseArguments(args) {
 }
 
 function showHelp() {
-  stdout.write(`StoreBase app publisher\n\nUsage:\n  storebase-publish [options]\n\nOptions (omitted values are prompted interactively):\n  --name <name>            App name\n  --avatar <file>          PNG, JPEG, or WebP avatar file\n  --version <version>      App version\n  --apk <file>             Signed Android APK\n  --category <category>    One of the 13 StoreBase categories\n  --description <text>     App description\n  --keystore <file>        Signing keystore used for the APK\n  --alias <name>           Private-key alias, if the keystore has multiple\n  --catalog <file>         App-list JSON (default: ./storebase-app-list.json)\n  --assets-dir <directory> Artifact directory (default: next to the catalog)\n  -h, --help               Show this help\n\nThe keystore password is entered in a hidden prompt, or read from\nSTOREBASE_KEYSTORE_PASSWORD for unattended use. It is never accepted as a CLI argument.\n`);
-}
+  stdout.write(`StoreBase app publisher
 
-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);
-  });
+Usage:
+  storebase-publish [options]
+
+Options (omitted app details are prompted interactively):
+  --name <name>                         App name
+  --avatar <file>                       PNG, JPEG, or WebP avatar file
+  --version <version>                   App version
+  --apk <file>                          Signed Android APK
+  --android-version-code <n>            Required for StoreBase Android releases
+  --minimum-android-version-code <n>    Optional required-upgrade floor
+  --delta <file.sbd>                    Optional StoreBase patch artifact
+  --delta-base-version-code <n>         Installed base code for the patch
+  --category <category>                 One of the 13 StoreBase categories
+  --description <text>                  App description
+  --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
+  --catalog <file>                      Local app-list JSON (local mode only)
+  --assets-dir <directory>              Local artifact directory (local mode only)
+  -h, --help                            Show this help
+
+Gateway mode uses STOREBASE_GATEWAY_URL (optional; defaults to the StoreBase gateway)
+and STOREBASE_GATEWAY_PUBLISH_TOKEN. The gateway sends encrypted Telegram settings
+to this run only; settings are decrypted in memory and are never written to disk.
+Use --telegram-config local only when supplying Telegram settings directly in the environment.
+The bot must be a channel administrator. Keystore passwords are entered in a hidden
+prompt or read from STOREBASE_KEYSTORE_PASSWORD.
+`);
 }
 
+
 async function collectInput(options) {
   const required = [
     ['name', 'App name'],
@@ -83,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.`);
@@ -115,6 +120,10 @@ async function collectInput(options) {
     description: options.description,
     keystore: options.keystore,
     alias: options.alias,
+    androidVersionCode: options['android-version-code'],
+    minimumAndroidVersionCode: options['minimum-android-version-code'],
+    delta: options.delta,
+    deltaBaseVersionCode: options['delta-base-version-code'],
   };
 }
 
@@ -141,30 +150,71 @@ 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;
+  options.storage = options.storage || 'telegram';
+  if (!['telegram', 'local'].includes(options.storage)) {
+    throw new Error('--storage must be either telegram or local.');
+  }
+  options['telegram-config'] = options['telegram-config'] || 'gateway';
+  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);
-  const result = await releaseApp(input, {
-    catalogPath: options.catalog,
-    assetsDir: options['assets-dir'],
-    signingCertificateSha256: certificate,
-  });
-
-  stdout.write(`\nRelease complete: ${result.app.name} ${result.app.version}\n`);
-  stdout.write(`App list: ${result.catalogPath}\n`);
-  stdout.write(`APK: ${result.app.apk}\n`);
-  stdout.write(`Avatar: ${result.app.avatar}\n`);
-  stdout.write('The keystore was used only to verify the APK signature; it was not copied.\n');
+  if (options.storage === 'local') {
+    if (input.androidVersionCode !== undefined || input.deltaPath) {
+      throw new Error('StoreBase Android update metadata and delta artifacts must be published through Telegram storage.');
+    }
+    const result = await releaseApp(input, {
+      catalogPath: options.catalog,
+      assetsDir: options['assets-dir'],
+      signingCertificateSha256: certificate,
+    });
+    stdout.write(`\nLocal release complete: ${result.app.name} ${result.app.version}\n`);
+    stdout.write(`App list: ${result.catalogPath}\n`);
+    stdout.write(`APK: ${result.app.apk}\n`);
+    stdout.write(`Avatar: ${result.app.avatar}\n`);
+  } else {
+    const connection = options['telegram-config'] === 'local'
+      ? await connectTelegram()
+      : await connectTelegramFromGateway(await getPublisherEnvironment());
+    try {
+      const storage = createTelegramStorage(connection.client, connection.channelEntity, {
+        readerClient: connection.readerClient,
+        readerChannel: connection.readerChannel,
+        writerChannel: connection.channelEntity,
+        channelRef: connection.channel,
+      });
+      const result = await storage.publish(input, certificate);
+      stdout.write(`\nTelegram release ${result.idempotent ? 'already exists' : 'published'}: ${input.name} ${input.version}\n`);
+      stdout.write(`Channel: ${connection.channel}\n`);
+      stdout.write(`Manifest message ID: ${result.messageId}\n`);
+      stdout.write(`APK message ID: ${result.manifest.artifacts.apk.messageId}\n`);
+      stdout.write(`Avatar message ID: ${result.manifest.artifacts.avatar.messageId}\n`);
+      if (result.manifest.artifacts.delta) stdout.write(`Delta message ID: ${result.manifest.artifacts.delta.messageId}\n`);
+    } finally {
+      await disconnectTelegram(connection);
+    }
+  }
+  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-telegram.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+'use strict';
+
+require('dotenv').config();
+
+const { stdout, stderr } = require('node:process');
+const {
+  connectTelegramFromGateway,
+  connectTelegramReaderFromGateway,
+} = require('../lib/gateway-client');
+const { getPublisherEnvironment } = require('../lib/publisher-token');
+const {
+  connectTelegram,
+  connectTelegramReader,
+  disconnectTelegram,
+} = require('../lib/telegram-client');
+const { createTelegramStorage } = require('../lib/telegram-storage');
+
+function showHelp() {
+  stdout.write(`StoreBase Telegram catalog tools
+
+Usage:
+  storebase-telegram list [--telegram-config gateway|local]
+  storebase-telegram metadata <app-id> [--version <version>] [--telegram-config gateway|local]
+  storebase-telegram download <app-id> [--version <version>] [--kind apk|avatar|delta|all] [--out <directory>] [--telegram-config gateway|local]
+  storebase-telegram pin <app-id> <version> [--telegram-config gateway|local]
+
+Catalog reads use the read-only gateway bootstrap. pin and APK publishing use the
+separate token-protected publisher bootstrap. With no --version, metadata and
+downloads use the app's pinned default, or the newest release if none is pinned.
+Gateway settings are decrypted in memory only.
+`);
+}
+
+function parseOptions(args) {
+  const options = {};
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (!arg.startsWith('--')) throw new Error(`Unexpected argument: ${arg}`);
+    const equals = arg.indexOf('=');
+    const key = arg.slice(2, equals < 0 ? undefined : equals);
+    if (!['version', 'kind', 'out', 'telegram-config'].includes(key)) throw new Error(`Unknown option: --${key}`);
+    const value = equals < 0 ? args[++index] : arg.slice(equals + 1);
+    if (typeof value !== 'string' || !value.trim() || value.startsWith('--')) throw new Error(`Option --${key} requires a value.`);
+    options[key] = value;
+  }
+  return options;
+}
+
+async function releaseConnection(mode, needsWrite) {
+  if (mode === 'local') return needsWrite ? connectTelegram() : connectTelegramReader();
+  if (mode !== 'gateway') throw new Error('--telegram-config must be either gateway or local.');
+  return needsWrite
+    ? connectTelegramFromGateway(await getPublisherEnvironment())
+    : connectTelegramReaderFromGateway();
+}
+
+async function main() {
+  const [command, ...args] = process.argv.slice(2);
+  if (!command || command === '--help' || command === '-h') return showHelp();
+  if (!['list', 'metadata', 'download', 'pin'].includes(command)) throw new Error(`Unknown command: ${command}`);
+  const needsApp = ['metadata', 'download', 'pin'].includes(command);
+  const appId = needsApp ? args.shift() : undefined;
+  if (needsApp && (!appId || appId.startsWith('--'))) throw new Error(`${command} requires an app ID.`);
+  const pinVersion = command === 'pin' ? args.shift() : undefined;
+  if (command === 'pin' && (!pinVersion || pinVersion.startsWith('--'))) throw new Error('pin requires an app ID and version.');
+  const options = parseOptions(args);
+  const mode = options['telegram-config'] || 'gateway';
+  const connection = await releaseConnection(mode, command === 'pin');
+  try {
+    const storage = createTelegramStorage(connection.client, connection.channelEntity, {
+      readerClient: connection.readerClient,
+      readerChannel: connection.readerChannel,
+      writerChannel: connection.channelEntity,
+    });
+    if (command === 'list') {
+      const apps = await storage.getCatalog();
+      if (!apps.length) {
+        stdout.write('No StoreBase releases were found in the configured Telegram channel.\n');
+        return;
+      }
+      const rows = apps.map(({ appId: id, app, defaultVersion, defaultPinned, versions }) => ({
+        appId: id,
+        name: app.name,
+        category: app.category,
+        defaultVersion,
+        defaultPinned,
+        versions: versions.map(({ manifest, messageId }) => ({
+          version: manifest.version,
+          publishedAt: manifest.publishedAt,
+          manifestMessageId: messageId,
+        })),
+      }));
+      stdout.write(`${JSON.stringify(rows, null, 2)}\n`);
+      return;
+    }
+    if (command === 'pin') {
+      const result = await storage.pinVersion(appId, pinVersion);
+      stdout.write(`Default version ${result.idempotent ? 'already set' : 'set'}: ${appId} ${pinVersion}\n`);
+      stdout.write(`Telegram message ID: ${result.messageId}\n`);
+      return;
+    }
+    if (command === 'metadata') {
+      const [release, apps] = await Promise.all([storage.getMetadata(appId, options.version), storage.getCatalog()]);
+      const app = apps.find((entry) => entry.appId === appId);
+      stdout.write(`${JSON.stringify({ ...release, defaultVersion: app?.defaultVersion }, null, 2)}\n`);
+      return;
+    }
+    const kind = options.kind || 'all';
+    const result = await storage.download(appId, options.version, kind, options.out || './storebase-downloads');
+    stdout.write(`Release: ${result.release.manifest.app.name} ${result.release.manifest.version}\n`);
+    for (const artifact of result.downloaded) stdout.write(`${artifact.kind}: ${artifact.path} (${artifact.size} bytes, sha256 ${artifact.sha256})\n`);
+  } finally {
+    await disconnectTelegram(connection);
+  }
+}
+
+main().catch((error) => {
+  stderr.write(`storebase-telegram: ${error.message}\n`);
+  process.exitCode = 1;
+});