storebase-cli 1.0.0 → 1.1.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`
 - 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
 
-## Install from this repository
+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
-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 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.
+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.
 
-## Non-interactive example
+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 \
@@ -49,18 +65,39 @@ 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.
 
-## Output
+## Telegram storage and versions
 
-By default, running from a project directory creates or updates:
+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.
 
-- `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.
+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.
 
-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.
+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-publish.js

@@ -1,8 +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 {
   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',
+  'android-version-code', 'minimum-android-version-code', 'delta', 'delta-base-version-code',
 ]);
 
 function parseArguments(args) {
@@ -34,7 +42,37 @@ 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
+
+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) {
@@ -115,6 +153,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'],
   };
 }
 
@@ -144,6 +186,14 @@ 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);
 
@@ -151,16 +201,41 @@ async function main() {
   const entries = await inspectKeystore(input.keystorePath, password);
   const entry = await selectEntry(entries, input.alias);
   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`);
+  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');
 }
 

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

package/lib/gateway-client.js

@@ -0,0 +1,259 @@
+'use strict';
+
+const {
+  createDecipheriv,
+  generateKeyPairSync,
+  privateDecrypt,
+  constants,
+  sign,
+  randomUUID,
+} = require('node:crypto');
+
+const PROTOCOL = 'STOREBASE_GATEWAY_V1';
+const APP_ID = 'com.nexuss0781.storebase';
+const CATALOG_BOOTSTRAP_PATH = '/api/v1/catalog/bootstrap';
+const PUBLISHER_BOOTSTRAP_PATH = '/api/v1/publisher/bootstrap';
+const TOKEN_PATTERN = /^[A-Za-z0-9_-]{32,256}$/;
+const MAX_RESPONSE_BYTES = 2 * 1024 * 1024 + 64 * 1024;
+
+function fail(message) {
+  throw new Error(message);
+}
+
+function base64Bytes(value, label, maxBytes) {
+  if (typeof value !== 'string' || !value || value.length > Math.ceil(maxBytes * 4 / 3) + 8) {
+    fail(`Gateway response has an invalid ${label}.`);
+  }
+  const decoded = Buffer.from(value, 'base64');
+  if (!decoded.length || decoded.length > maxBytes || decoded.toString('base64') !== value) {
+    fail(`Gateway response has an invalid ${label}.`);
+  }
+  return decoded;
+}
+
+function canonicalRequest({ appId, requestId, timestamp, publicKey, publishToken, path }) {
+  const fields = [PROTOCOL, 'POST', path, appId, requestId, String(timestamp), publicKey];
+  if (path === PUBLISHER_BOOTSTRAP_PATH) fields.push(publishToken || '');
+  return fields.join('\n');
+}
+
+function canonicalPublisherRequest(request) {
+  return canonicalRequest({ ...request, path: PUBLISHER_BOOTSTRAP_PATH });
+}
+
+function envelopeAad(envelope) {
+  return [PROTOCOL, APP_ID, envelope.requestId, envelope.issuedAt].join('\n');
+}
+
+function validateCatalogSettings(settings) {
+  const telegram = settings?.telegram;
+  if (!settings || settings.schemaVersion !== 1 || settings.settingsVersion !== 1
+      || !telegram || !Number.isSafeInteger(telegram.apiId) || telegram.apiId <= 0
+      || typeof telegram.apiHash !== 'string' || !telegram.apiHash
+      || typeof telegram.readSession !== 'string' || !telegram.readSession
+      || typeof telegram.channel !== 'string' || !telegram.channel.trim()
+      || Object.hasOwn(telegram, 'botSession') || Object.hasOwn(telegram, 'botToken')) {
+    fail('Gateway returned invalid read-only Telegram settings.');
+  }
+  return settings;
+}
+
+function validatePublisherSettings(settings) {
+  const telegram = settings?.telegram;
+  if (!settings || settings.schemaVersion !== 1 || settings.settingsVersion !== 1
+      || !telegram || !Number.isSafeInteger(telegram.apiId) || telegram.apiId <= 0
+      || typeof telegram.apiHash !== 'string' || !telegram.apiHash
+      || typeof telegram.botSession !== 'string' || !telegram.botSession
+      || typeof telegram.readSession !== 'string' || !telegram.readSession
+      || typeof telegram.channel !== 'string' || !telegram.channel.trim()
+      || Object.hasOwn(telegram, 'botToken')) {
+    fail('Gateway returned invalid Telegram publisher settings.');
+  }
+  return settings;
+}
+
+function decryptSettings(envelope, privateKey, requestId, validator = validatePublisherSettings) {
+  if (!envelope || envelope.protocol !== PROTOCOL || envelope.appId !== APP_ID
+      || envelope.requestId !== requestId || typeof envelope.issuedAt !== 'string'
+      || envelope.keyWrap !== 'RSA-OAEP-SHA256' || envelope.contentEncryption !== 'AES-256-GCM') {
+    fail('Gateway returned an invalid or mismatched encrypted settings envelope.');
+  }
+  const wrappedKey = base64Bytes(envelope.encryptedKey, 'wrapped key', 16 * 1024);
+  const iv = base64Bytes(envelope.iv, 'initialization vector', 32);
+  const ciphertext = base64Bytes(envelope.ciphertext, 'ciphertext', MAX_RESPONSE_BYTES);
+  const tag = base64Bytes(envelope.tag, 'authentication tag', 32);
+  if (iv.length !== 12 || tag.length !== 16) fail('Gateway returned an invalid encryption envelope.');
+
+  let contentKey;
+  let plaintext;
+  try {
+    contentKey = privateDecrypt({
+      key: privateKey,
+      padding: constants.RSA_PKCS1_OAEP_PADDING,
+      oaepHash: 'sha256',
+    }, wrappedKey);
+    if (contentKey.length !== 32) fail('Gateway returned an invalid content key.');
+    const decipher = createDecipheriv('aes-256-gcm', contentKey, iv);
+    decipher.setAAD(Buffer.from(envelopeAad(envelope), 'utf8'));
+    decipher.setAuthTag(tag);
+    plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+    return validator(JSON.parse(plaintext.toString('utf8')));
+  } catch {
+    fail('Could not authenticate or decrypt the gateway settings response.');
+  } finally {
+    contentKey?.fill(0);
+    plaintext?.fill(0);
+    wrappedKey.fill(0);
+    iv.fill(0);
+    ciphertext.fill(0);
+    tag.fill(0);
+  }
+}
+
+function resolveGatewayUrl(env, pathname) {
+  const configured = env.STOREBASE_GATEWAY_URL || 'https://storebase.wasmer.app';
+  let base;
+  try {
+    base = new URL(configured);
+  } catch {
+    fail('STOREBASE_GATEWAY_URL must be a valid HTTPS URL.');
+  }
+  const loopback = ['localhost', '127.0.0.1', '::1', '[::1]'].includes(base.hostname);
+  if ((base.protocol !== 'https:' && !loopback) || base.username || base.password || base.search || base.hash) {
+    fail('STOREBASE_GATEWAY_URL must use HTTPS and must not contain credentials, query parameters, or a fragment.');
+  }
+  return new URL(pathname, base);
+}
+
+async function fetchEncryptedSettings(env, pathname, validator, options = {}) {
+  const publisher = pathname === PUBLISHER_BOOTSTRAP_PATH;
+  const publishToken = publisher ? env.STOREBASE_GATEWAY_PUBLISH_TOKEN : undefined;
+  if (publisher && (typeof publishToken !== 'string' || !TOKEN_PATTERN.test(publishToken))) {
+    fail('Set STOREBASE_GATEWAY_PUBLISH_TOKEN to the high-entropy publisher access token.');
+  }
+  const endpoint = resolveGatewayUrl(env, pathname);
+  const keyPair = generateKeyPairSync('rsa', { modulusLength: 2048 });
+  const publicKey = keyPair.publicKey.export({ format: 'der', type: 'spki' }).toString('base64');
+  const requestId = (options.randomUUID || randomUUID)();
+  const timestamp = (options.now || Date.now)();
+  const unsigned = {
+    appId: APP_ID,
+    requestId,
+    timestamp,
+    publicKey,
+    ...(publisher ? { publishToken } : {}),
+  };
+  const signature = sign(
+    'RSA-SHA256',
+    Buffer.from(canonicalRequest({ ...unsigned, path: pathname }), 'utf8'),
+    keyPair.privateKey,
+  ).toString('base64');
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), options.timeoutMs || 15_000);
+  timeout.unref?.();
+
+  try {
+    const response = await (options.fetch || globalThis.fetch)(endpoint, {
+      method: 'POST',
+      redirect: 'error',
+      signal: controller.signal,
+      headers: { 'content-type': 'application/json', accept: 'application/json' },
+      body: JSON.stringify({ ...unsigned, signature }),
+    });
+    const length = Number(response.headers?.get?.('content-length'));
+    if (Number.isFinite(length) && length > MAX_RESPONSE_BYTES) fail('Gateway response exceeded the allowed size.');
+    if (!response.ok) fail(`Gateway bootstrap failed with HTTP ${response.status}.`);
+    const text = await response.text();
+    if (Buffer.byteLength(text, 'utf8') > MAX_RESPONSE_BYTES) fail('Gateway response exceeded the allowed size.');
+    let envelope;
+    try { envelope = JSON.parse(text); } catch { fail('Gateway returned an invalid response.'); }
+    return decryptSettings(envelope, keyPair.privateKey, requestId, validator);
+  } catch (error) {
+    if (/^Gateway |^Set STOREBASE_|^Could not authenticate|^Gateway response/.test(error.message || '')) throw error;
+    if (error?.name === 'AbortError') fail('Gateway bootstrap timed out.');
+    fail('Could not connect to the StoreBase gateway bootstrap.');
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+async function fetchPublisherSettings(env = process.env, options = {}) {
+  return fetchEncryptedSettings(env, PUBLISHER_BOOTSTRAP_PATH, validatePublisherSettings, options);
+}
+
+async function fetchCatalogSettings(env = process.env, options = {}) {
+  return fetchEncryptedSettings(env, CATALOG_BOOTSTRAP_PATH, validateCatalogSettings, options);
+}
+
+function scrubConnectionError(error, runtimeEnv) {
+  let message = String(error?.message || 'Telegram connection failed.');
+  for (const secret of Object.values(runtimeEnv)) {
+    if (secret && secret.length > 8) message = message.split(secret).join('[redacted]');
+  }
+  return new Error(message);
+}
+
+async function connectTelegramFromGateway(env = process.env, options = {}) {
+  const settings = await (options.fetchSettings || fetchPublisherSettings)(env, options);
+  const telegram = settings.telegram;
+  const runtimeEnv = {
+    STOREBASE_TELEGRAM_API_ID: String(telegram.apiId),
+    STOREBASE_TELEGRAM_API_HASH: telegram.apiHash,
+    STOREBASE_TELEGRAM_SESSION: telegram.botSession,
+    STOREBASE_TELEGRAM_READ_SESSION: telegram.readSession,
+    STOREBASE_TELEGRAM_CHANNEL: telegram.channel,
+  };
+  try {
+    const connector = options.connectTelegram || require('./telegram-client').connectTelegram;
+    const connection = await connector(runtimeEnv, { requireReader: true });
+    delete connection.session;
+    delete connection.readSession;
+    delete connection.hasStoredSession;
+    return connection;
+  } catch (error) {
+    throw scrubConnectionError(error, runtimeEnv);
+  } finally {
+    for (const key of Object.keys(runtimeEnv)) runtimeEnv[key] = '';
+    telegram.apiHash = '';
+    telegram.botSession = '';
+    telegram.readSession = '';
+    telegram.channel = '';
+  }
+}
+
+async function connectTelegramReaderFromGateway(env = process.env, options = {}) {
+  const settings = await (options.fetchSettings || fetchCatalogSettings)(env, options);
+  const telegram = settings.telegram;
+  const runtimeEnv = {
+    STOREBASE_TELEGRAM_API_ID: String(telegram.apiId),
+    STOREBASE_TELEGRAM_API_HASH: telegram.apiHash,
+    STOREBASE_TELEGRAM_READ_SESSION: telegram.readSession,
+    STOREBASE_TELEGRAM_CHANNEL: telegram.channel,
+  };
+  try {
+    const connector = options.connectTelegramReader || require('./telegram-client').connectTelegramReader;
+    return await connector(runtimeEnv);
+  } catch (error) {
+    throw scrubConnectionError(error, runtimeEnv);
+  } finally {
+    for (const key of Object.keys(runtimeEnv)) runtimeEnv[key] = '';
+    telegram.apiHash = '';
+    telegram.readSession = '';
+    telegram.channel = '';
+  }
+}
+
+module.exports = {
+  APP_ID,
+  CATALOG_BOOTSTRAP_PATH,
+  PUBLISHER_BOOTSTRAP_PATH,
+  canonicalPublisherRequest,
+  canonicalRequest,
+  connectTelegramFromGateway,
+  connectTelegramReaderFromGateway,
+  decryptSettings,
+  fetchCatalogSettings,
+  fetchPublisherSettings,
+  validateCatalogSettings,
+  validatePublisherSettings,
+};