storebase-cli 1.1.0 → 1.3.0

package/lib/signing-vault.js

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

package/package.json

@@ -1,18 +1,24 @@
 {
   "name": "storebase-cli",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Publish signed Android apps to a versioned Telegram-backed StoreBase catalog",
   "license": "UNLICENSED",
   "private": false,
   "type": "commonjs",
   "bin": {
     "storebase-publish": "bin/storebase-publish.js",
-    "storebase-telegram": "bin/storebase-telegram.js"
+    "storebase-telegram": "bin/storebase-telegram.js",
+    "storebase-keystore": "bin/storebase-keystore.js",
+    "storebase-skill": "bin/storebase-skill.js"
   },
   "files": [
-    "bin/",
-    "lib/",
-    "README.md"
+    "bin/*.js",
+    "lib/*.js",
+    "README.md",
+    "skills/storebase/SKILL.md",
+    "skills/storebase/references/cli-workflows.md",
+    "skills/storebase/references/runtime-and-android.md",
+    "skills/storebase/references/updates-and-development.md"
   ],
   "engines": {
     "node": ">=18"

package/skills/storebase/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: storebase
+description: Operate StoreBase end to end. Use when installing or using storebase-cli, managing encrypted signing-keystore profiles, publishing signed Android APKs and icons to Telegram, listing or downloading immutable releases, pinning default versions, configuring the encrypted gateway or local Wasmer deployment, building the Apps/Explore Android frontend, or preparing and testing StoreBase incremental/full APK updates.
+---
+
+# StoreBase
+
+## Start here
+
+1. Identify the outcome: read a catalog, manage signing profiles, publish an approved app, operate a gateway, build Android, or release CLI software.
+2. Read [CLI workflows](references/cli-workflows.md) for exact command syntax, configuration, signing, publishing, catalog operations, and troubleshooting.
+3. Read [Runtime and Android](references/runtime-and-android.md) before gateway deployment, bootstrap changes, direct Telegram operations, or frontend work.
+4. Read [Updates and development](references/updates-and-development.md) before patch generation, Android self-updates, source builds, or release testing.
+5. Use the installed CLI's `--help` as the final authority when versions differ. Do not invent commands for unimplemented features.
+
+Resolve references relative to this `SKILL.md`, not a fixed installation path. Install with `npm install --global storebase-cli`. Locate this skill with `storebase-skill path`; copy it into an agent's chosen skills root with `storebase-skill install --dir <skills-root>`. This copies files only; enable or reload the skill using that agent's own mechanism when required.
+
+## Keep the architecture straight
+
+- Treat the npm CLI release, an Android APK release, and a gateway deployment as separate operations with separate authorization.
+- Use the gateway only to bootstrap encrypted runtime settings. Publish APKs, icons, optional deltas, immutable manifests, and default-version records directly to Telegram.
+- Use the bot session for writes and a separate personal-user session for history reads. Catalog reads do not require the publisher key.
+- Distinguish `--telegram-config local` (direct Telegram environment configuration) from `--storage local` (legacy local JSON/files storage).
+- Distinguish signing profiles from signing itself. StoreBase **verifies already-signed APKs; it never signs or re-signs them**.
+- Distinguish Apps/Explore demo listings from the Telegram-backed StoreBase self-updater. Do not promise a fully wired dynamic marketplace or general app installer where controls are only demo UI.
+
+## Follow the common end-to-end flow
+
+### First-time approved publisher
+
+1. Install Node.js, Java `keytool`, Android SDK Build Tools `apksigner`, and the CLI; inspect command help.
+2. Confirm owner approval for the exact APK release and metadata. Collect a signed APK, PNG/JPEG/WebP icon, stable app name, unique version, supported category, description, and matching keystore or existing profile.
+3. Select gateway mode (default). Supply the publisher token through a secret manager/runtime environment or hidden prompt, never an argument. Do not ask for Telegram credentials if the configured gateway can supply them.
+4. Import a named profile once with `storebase-keystore import`. Unlock the vault interactively; never put profile passwords/passphrases in arguments, environment variables, or files.
+5. Run `storebase-publish --signing-profile <profile>` with app metadata. For StoreBase itself, include an increasing Android version code. Inspect actual success/failure rather than assuming an upload succeeded.
+6. Verify with `storebase-telegram list`, `metadata <app-id> --version <version>`, and download into a chosen directory. Check version, certificate, artifact hashes/sizes, and message IDs.
+7. Pin the approved version if it should be default; verify without `--version`. Preserve older immutable releases.
+8. Report the app ID/version, new versus idempotent publication, manifest ID, verification results, and default state. Never return credentials.
+
+### Routine app update
+
+1. Preserve stable app identity and a compatible signer. Increment the release version; increment Android `versionCode` for StoreBase self-updates.
+2. Build and sign outside the publisher. Reuse the matching profile, not an unrelated replacement key.
+3. For StoreBase only, optionally prepare an `.sbd` patch from the exact installed base APK to the exact signed target APK; always keep the full APK fallback.
+4. Publish a new immutable release, download/verify it, then change the default pointer if authorized.
+5. Test a real Android device: unknown-source permission, system install approval, signer/version acceptance, and reopening. Do not promise silent installation or guaranteed foreground relaunch.
+
+### Read/download only
+
+1. Install the CLI and use default gateway mode; do not request a publisher token.
+2. Run `storebase-telegram list`; use its app ID rather than an Android package name.
+3. Inspect metadata, then download the default or explicit historical release. Downloads verify size and SHA-256.
+4. Do not pin or publish during a read-only task.
+
+### Keystore maintenance
+
+1. List profiles and compare public fingerprints.
+2. Import a new name for a separate key; use `import <profile> ... --replace` only for approved replacement.
+3. Use `rekey` to change the vault master passphrase, not Android signing identity.
+4. Securely back up the encrypted vault and original signing material before replacing/removing anything. Read the vault warnings in the CLI reference.
+5. Preserve Android compatibility: profile replacement does not create signing lineage.
+
+### Gateway, frontend, and source work
+
+1. Read both runtime/development references before deployment or Android settings changes.
+2. Keep secrets server-side and separate reader/publisher bootstrap. Verify `/api/v1/health` and encrypted bootstrap behavior without logging decrypted settings.
+3. Build frontend assets before Android sync; preserve native plugins and manifest permissions.
+4. Use local Wasmer deployment only when requested, never just to demonstrate this skill.
+5. Test device behavior separately from unit tests; distinguish demo controls from working updater functionality.
+
+## Protect secrets and release boundaries
+
+- Never put `.env`, tokens, Telegram sessions, vaults, keystores, private keys, APKs, generated patches, or local credential files in Git/npm. Use documentation placeholders only.
+- Restrict publisher keys and read sessions. Encrypted bootstrap is not production identity, device attestation, or protection against a compromised client.
+- Never print decrypted Telegram settings or copy them into Android assets, frontend bundles, release metadata, shell history, diagnostics, or chat.
+- Obtain owner approval before publishing third-party APKs; pending builds are not approval. Leave any unapproved SnapBase APK unpublished.
+- Stop on signer mismatch, immutable-version conflict, failed integrity check, or ambiguous publication. Inspect existing releases before retrying.
+- Never delete artifacts or rewrite manifests to fix releases; publish a new version. Pinning an old release does not make Android accept a downgrade.
+- Report only verified outcomes. Unit tests do not prove device installation/relaunch; publishing a skill to npm/Git does not activate it automatically in every agent.
+
+## Release this CLI and skill
+
+1. Inspect all non-secret project changes and the target branch. Keep the skill in `cli/skills/storebase/` and its install command in `cli/bin/`.
+2. Validate skill frontmatter when a validator is available; run root `npm test`, `npm run build`, and CLI package/install tests.
+3. Bump public CLI package and lockfile together. Inspect `npm pack --dry-run --json --ignore-scripts`; permit only CLI JavaScript, README/package metadata, and explicitly listed skill Markdown files.
+4. Test the exact tarball with an isolated install, `storebase-skill path`, `install`, and command help. Publish that inspected tarball with a runtime npm credential, never a repository token file.
+5. Commit approved non-secret source/docs, push the intended branch, and verify GitHub commit and npm version. Do not publish APKs or deploy a gateway as side effects.
+6. Return npm version, commit/link, skill location/install commands, passing tests, and any untested platforms or blockers.