storebase-cli 0.0.0-stage → 1.1.0

package/README.md

@@ -1,3 +1,107 @@
-# Temporary Holding Version
+# StoreBase App Publisher CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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`
+- 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
+```
+
+To install this checkout globally:
+
+```sh
+npm install --global ./cli
+```
+
+## 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`.
+
+```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.
+
+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.
+
+## 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 \
+  --name "Example App" \
+  --avatar ./icon.png \
+  --version 1.2.0 \
+  --apk ./app-release.apk \
+  --category Productivity \
+  --description "A short description of the app." \
+  --keystore ./release.jks \
+  --alias release
+```
+
+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.
+
+## 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
+```
+
+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
+
+```sh
+cd cli
+npm test
+```

package/bin/storebase-publish.js

@@ -0,0 +1,245 @@
+#!/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 {
+  CATEGORIES,
+  inspectKeystore,
+  releaseApp,
+  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', 'storage', 'catalog', 'assets-dir',
+  'telegram-config',
+  'android-version-code', 'minimum-android-version-code', 'delta', 'delta-base-version-code',
+]);
+
+function parseArguments(args) {
+  const options = {};
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    if (argument === '--help' || argument === '-h') return { help: true, options };
+    if (!argument.startsWith('--')) throw new Error(`Unexpected argument: ${argument}`);
+    const equals = argument.indexOf('=');
+    const name = argument.slice(2, equals < 0 ? undefined : equals);
+    if (!OPTION_NAMES.has(name)) throw new Error(`Unknown option: --${name}`);
+    const value = equals < 0 ? args[++index] : argument.slice(equals + 1);
+    if (typeof value !== 'string' || !value.trim() || value.startsWith('--')) {
+      throw new Error(`Option --${name} requires a value.`);
+    }
+    options[name] = value;
+  }
+  return { help: false, options };
+}
+
+function showHelp() {
+  stdout.write(`StoreBase app publisher
+
+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
+  --keystore <file>                     Signing keystore used for the APK
+  --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.
+`);
+}
+
+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 = [
+    ['name', 'App name'],
+    ['avatar', 'Avatar file path'],
+    ['version', 'Version'],
+    ['apk', 'APK file path'],
+    ['category', 'Category'],
+    ['description', 'Description'],
+    ['keystore', 'Signed keystore file path'],
+  ];
+  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.`);
+  }
+
+  const rl = createInterface({ input: stdin, output: stdout });
+  try {
+    for (const [key, label] of required) {
+      if (!options[key]) {
+        if (key === 'category') {
+          stdout.write('\nAvailable categories:\n');
+          CATEGORIES.forEach((category, index) => stdout.write(`  ${index + 1}. ${category}\n`));
+        }
+        options[key] = (await rl.question(`${label}${key === 'category' ? ' (number or name)' : ''}: `)).trim();
+        if (key === 'category' && /^\d+$/.test(options[key])) {
+          const category = CATEGORIES[Number(options[key]) - 1];
+          if (category) options[key] = category;
+        }
+      }
+    }
+  } finally {
+    rl.close();
+  }
+  return {
+    name: options.name,
+    avatar: options.avatar,
+    version: options.version,
+    apk: options.apk,
+    category: options.category,
+    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'],
+  };
+}
+
+async function selectEntry(entries, aliasOption) {
+  if (aliasOption) {
+    const selected = entries.find((entry) => entry.alias === aliasOption);
+    if (!selected) throw new Error(`Keystore alias "${aliasOption}" is not a private-key entry. Available aliases: ${entries.map((entry) => entry.alias).join(', ')}.`);
+    return selected;
+  }
+  if (entries.length === 1) return entries[0];
+  if (!stdin.isTTY || !stdout.isTTY) {
+    throw new Error(`Keystore has multiple private-key aliases. Select one with --alias: ${entries.map((entry) => entry.alias).join(', ')}.`);
+  }
+  const rl = createInterface({ input: stdin, output: stdout });
+  try {
+    stdout.write(`Keystore private-key aliases: ${entries.map((entry) => entry.alias).join(', ')}\n`);
+    const alias = (await rl.question('Signing alias: ')).trim();
+    const selected = entries.find((entry) => entry.alias === alias);
+    if (!selected) throw new Error(`Unknown signing alias: ${alias}`);
+    return selected;
+  } finally {
+    rl.close();
+  }
+}
+
+async function main() {
+  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.');
+  }
+  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);
+  const certificate = verifyApkSignature(input.apkPath, entry);
+  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('The keystore was used only to verify the APK signature; it was not copied.\n');
+}
+
+main().catch((error) => {
+  process.stderr.write(`storebase-publish: ${error.message}\n`);
+  process.exitCode = 1;
+});

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