waybetter 0.1.1 → 0.6.0

package/cli/remote.mjs

@@ -0,0 +1,260 @@
+// Remote and WSL builds for `waybetter release macos|linux`: the committed state of an app (its
+// git HEAD plus every submodule at the commit the app records) is exported, sent to the machine
+// that builds it, built there through `waybetter build-env` (no build path in the binary) and the
+// artifacts come back to be scanned (`waybetter privacy-scan`) and, later, signed on this machine.
+// Nothing here touches the working tree the developer has open, and no key ever leaves this
+// machine: the remote build is unsigned (updater artifacts off), signing is `waybetter release`.
+//
+// The export is `git archive` of the app at HEAD plus `git archive` of each submodule at the commit
+// HEAD points to, read from the local submodule repository. A submodule's newest commits do not
+// have to be on any remote, so nothing is ever fetched from origin.
+//
+// Where it builds is never written down here: an SSH target (user@host, WAYBETTER_MAC_SSH or
+// --remote), its key (WAYBETTER_MAC_SSH_KEY or --ssh-key) and a WSL distro (--wsl,
+// WAYBETTER_WSL_DISTRO) come from the caller. The remote scripts use a login shell (macOS: bun,
+// cargo and node exist only there) and a clean PATH (WSL: no Windows programs shadowing the
+// Linux ones).
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, join, relative, resolve } from 'node:path';
+import { assertClean } from './privacy.mjs';
+
+class RemoteError extends Error {}
+const fail = message => { throw new RemoteError(message); };
+
+/** Single-quotes a value for a POSIX shell. */
+export const shq = value => `'${String(value).replaceAll("'", `'\\''`)}'`;
+
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, { encoding: 'utf8', windowsHide: true, maxBuffer: 1 << 28, ...options });
+  if (result.error) fail(`${command}: ${result.error.message}`);
+  return result;
+}
+
+function git(root, args, options) {
+  const result = run('git', ['-C', root, ...args], options);
+  if (result.status !== 0) fail(`git ${args[0]} failed: ${(result.stderr || '').trim().split('\n')[0]}`);
+  return result.stdout ?? '';
+}
+
+/** A file of the committed state (`git show <ref>:<path>`), for the version and product name. */
+export const committedFile = (root, path, ref = 'HEAD') => git(root, ['show', `${ref}:${path}`]);
+
+/** The submodules `ref` (default HEAD) records: [{ path, sha }]. */
+export function committedSubmodules(root, ref = 'HEAD') {
+  return git(root, ['ls-tree', '-r', ref])
+    .split('\n')
+    .map(line => /^160000 commit ([0-9a-f]{40})\t(.+)$/.exec(line))
+    .filter(Boolean)
+    .map(([, sha, path]) => ({ path, sha }));
+}
+
+/**
+ * Exports the committed state of `root` (HEAD, and each submodule at its recorded commit) to a
+ * `.tar.gz` at `file`. Returns `{ sha, submodules, file, bytes, dirty }`; `dirty` lists tracked
+ * files changed in the working tree, which the export ignores by design.
+ */
+export function exportCommitted({ root, file, ref = 'HEAD', exclude = [], log = () => {} }) {
+  const sha = git(root, ['rev-parse', `${ref}^{commit}`]).trim();
+  const submodules = committedSubmodules(root, sha);
+  const dirty = git(root, ['status', '--porcelain', '--untracked-files=no']).split('\n').filter(Boolean).length;
+  const staging = mkdtempSync(join(tmpdir(), 'wb-export-'));
+  try {
+    const parts = [{ repo: root, ref: sha, prefix: '' }, ...submodules.map(({ path, sha: ref }) => ({ repo: join(root, path), ref, prefix: `${path}/`, path }))];
+    for (const [index, part] of parts.entries()) {
+      if (part.path && !existsSync(join(part.repo, '.git'))) fail(`submodule ${part.path} is not checked out here (needed for commit ${part.ref.slice(0, 12)})`);
+      const tarName = `part-${index}.tar`;
+      // `exclude` (paths of the app repo the build never reads, e.g. screenshots) keeps the upload small.
+      const skip = part.path ? [] : ['--', '.', ...exclude.map(path => `:(exclude)${path}`)];
+      const args = ['archive', '--format=tar', ...(part.prefix ? [`--prefix=${part.prefix}`] : []), '-o', join(staging, tarName), part.ref, ...skip];
+      // Blobs as committed: the developer's core.autocrlf must not decide the line endings of the build.
+      const archived = run('git', ['-C', part.repo, '-c', 'core.autocrlf=false', ...args]);
+      if (archived.status !== 0) fail(`git archive ${part.path ?? 'app'} at ${part.ref.slice(0, 12)} failed: ${(archived.stderr || '').trim().split('\n')[0]} (is that commit in the local repository?)`);
+      // Relative names and cwd: a drive letter in an argument reads as a remote host to GNU tar.
+      mkdirSync(join(staging, 'tree'), { recursive: true });
+      const unpacked = run('tar', ['-xf', tarName, '-C', 'tree'], { cwd: staging });
+      if (unpacked.status !== 0) fail(`tar -x failed: ${(unpacked.stderr || '').trim().split('\n')[0]}`);
+      rmSync(join(staging, tarName));
+    }
+    mkdirSync(resolve(file, '..'), { recursive: true });
+    const outName = 'export.tgz';
+    const packed = run('tar', ['-czf', outName, '-C', 'tree', '.'], { cwd: staging });
+    if (packed.status !== 0) fail(`tar -c failed: ${(packed.stderr || '').trim().split('\n')[0]}`);
+    writeFileSync(file, readFileSync(join(staging, outName)));
+  } finally {
+    rmSync(staging, { recursive: true, force: true });
+  }
+  const bytes = statSync(file).size;
+  log(`export: ${sha.slice(0, 12)}${submodules.map(s => ` + ${s.path}@${s.sha.slice(0, 12)}`).join('')} -> ${(bytes / 1048576).toFixed(1)} MB${dirty ? ` (${dirty} tracked file(s) changed in the working tree are NOT included)` : ''}`);
+  return { sha, submodules, file, bytes, dirty };
+}
+
+/** Remote work folders are relative to the login home. */
+const workDirOf = (dir, artifact) => (dir ?? `waybetter-builds/${artifact}`).replace(/^~\//, '').replace(/^\/+/, '') || `waybetter-builds/${artifact}`;
+const sha256Line = 'if command -v shasum >/dev/null 2>&1; then shasum -a 256 "$@"; else sha256sum "$@"; fi';
+
+/**
+ * The macOS build script (bash, run in a login shell on the Mac): unpack, install, universal
+ * ad-hoc-signed .app and .dmg through build-env, the updater bundle as a tar.gz of the .app; the
+ * dmg and the tar.gz under space-free names, and the .app itself, in `out/`. It never installs,
+ * quits or replaces an app on the Mac: whoever runs the app there swaps it in.
+ */
+export function macBuildScript({ workDir, sha, artifact, productName, version, desktopDir, prepareCommand }) {
+  const app = `${productName}.app`;
+  return `#!/bin/bash
+set -eu
+# Low priority: the Mac may be recording or running an app while this compiles.
+renice -n 10 $$ >/dev/null 2>&1 || true
+# rustup first: Homebrew's Rust has no x86_64 standard library, which a universal build needs.
+export PATH="$HOME/.cargo/bin:$PATH"
+WORK="$HOME/${workDir}"
+SRC="$WORK/src"
+OUT="$WORK/out"
+cd "$WORK"
+rm -rf "$SRC" "$OUT"
+# -m: files get the time of unpacking. git archive stamps every file with its commit time, which is older
+# than the cached build in CARGO_TARGET_DIR: cargo would take a changed source for unchanged and reuse stale objects.
+mkdir -p "$SRC" "$OUT"
+tar -xzmf "$WORK/source-${sha.slice(0, 12)}.tgz" -C "$SRC"
+cd "$SRC"
+rustup target add aarch64-apple-darwin x86_64-apple-darwin
+${prepareCommand}
+cd ${shq(desktopDir)}
+# Ad-hoc signature (no Developer ID yet: Gatekeeper's "Open Anyway" path, not "is damaged"), no
+# updater bundle from Tauri (it needs the signing key, which never leaves the release machine).
+printf '%s' '{"bundle":{"createUpdaterArtifacts":false,"macOS":{"signingIdentity":"-"}}}' > "$WORK/override.json"
+export CARGO_TARGET_DIR="$WORK/target"
+bun "$SRC/waybetter/packages/waybetter/bin/waybetter.mjs" build-env -- bunx tauri build --target universal-apple-darwin --bundles app,dmg --ci --config "$WORK/override.json"
+BUNDLE="$CARGO_TARGET_DIR/universal-apple-darwin/release/bundle"
+DMG="$(ls "$BUNDLE"/dmg/*_${version}_universal.dmg | head -1)"
+cp "$DMG" "$OUT/${artifact}_${version}_universal.dmg"
+# Owner 0/root: the archive must not carry the Mac account name in its entry headers.
+COPYFILE_DISABLE=1 tar --uid 0 --gid 0 --uname root --gname wheel -czf "$OUT/${artifact}_${version}_universal.app.tar.gz" -C "$BUNDLE/macos" ${shq(app)}
+ditto "$BUNDLE/macos/"${shq(app)} "$OUT/"${shq(app)}
+cd "$OUT"
+set -- *.dmg *.tar.gz
+${sha256Line} > SHA256SUMS
+ls -ln "$OUT"
+echo "REMOTE_BUILD_OK ${sha.slice(0, 12)}"
+`;
+}
+
+/**
+ * The Linux build script (bash, run in WSL or on any Ubuntu 22.04): clean PATH, unpack, install,
+ * AppImage and .deb through build-env with Tauri's updater bundle off (on Linux the signed
+ * AppImage itself is the update payload), copied to `out/` under space-free names.
+ */
+export function linuxBuildScript({ workDir, sha, artifact, version, desktopDir, prepareCommand, tarball, outDir }) {
+  return `#!/bin/bash
+set -eu
+# A clean PATH: under WSL the Windows programs (a Windows bun, node, cargo) would shadow these.
+export PATH="$HOME/.bun/bin:$HOME/.cargo/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
+export APPIMAGE_EXTRACT_AND_RUN=1
+WORK="$HOME/${workDir}"
+SRC="$WORK/src"
+cd "$HOME"
+mkdir -p "$WORK"
+rm -rf "$SRC"
+mkdir -p "$SRC"
+tar -xzmf "$(wslpath -u ${shq(tarball)} 2>/dev/null || echo ${shq(tarball)})" -C "$SRC"
+cd "$SRC"
+${prepareCommand}
+cd ${shq(desktopDir)}
+printf '%s' '{"bundle":{"createUpdaterArtifacts":false}}' > "$WORK/override.json"
+export CARGO_TARGET_DIR="$WORK/target"
+bun "$SRC/waybetter/packages/waybetter/bin/waybetter.mjs" build-env -- bunx tauri build --bundles appimage,deb --ci --config "$WORK/override.json"
+BUNDLE="$CARGO_TARGET_DIR/release/bundle"
+OUTDIR="$(wslpath -u ${shq(outDir)} 2>/dev/null || echo ${shq(outDir)})"
+mkdir -p "$OUTDIR"
+cp "$(ls "$BUNDLE"/appimage/*_${version}_amd64.AppImage | head -1)" "$OUTDIR/${artifact}_${version}_amd64.AppImage"
+cp "$(ls "$BUNDLE"/deb/*_${version}_amd64.deb | head -1)" "$OUTDIR/${artifact}_${version}_amd64.deb"
+ls -ln "$OUTDIR"
+echo "REMOTE_BUILD_OK ${sha.slice(0, 12)}"
+`;
+}
+
+const sshOptions = ({ key }) => ['-o', 'BatchMode=yes', '-o', 'IdentitiesOnly=yes', '-o', 'ConnectTimeout=15', '-o', 'ServerAliveInterval=30', ...(key ? ['-i', key] : [])];
+
+/** Runs a command and streams its output; the exit code decides. */
+function stream(command, args, { log, label }) {
+  log(`${label}: ${command} ${args.map(a => (/\s/.test(a) ? '"…"' : a)).join(' ').slice(0, 160)}`);
+  const result = spawnSync(command, args, { stdio: 'inherit', windowsHide: true });
+  if (result.error) fail(`${command}: ${result.error.message}`);
+  if (result.status !== 0) fail(`${label} failed (exit ${result.status})`);
+}
+
+/**
+ * Builds the committed state of the app on a Mac over SSH and brings the .dmg and the .app.tar.gz
+ * back to `<outDir>/build/macos`. Returns `{ version, sha, dir, dmg, updater }`.
+ */
+export function buildMacRemote({ config, target, key, remoteDir, ref = 'HEAD', env = process.env, log = console.log }) {
+  if (!target || !/^[A-Za-z0-9._-]+@[A-Za-z0-9._:-]+$/.test(target)) fail('a Mac needs --remote user@host (or WAYBETTER_MAC_SSH)');
+  const { root } = config;
+  const version = JSON.parse(committedFile(root, 'package.json', ref)).version;
+  const productName = JSON.parse(committedFile(root, relTauri(config, 'tauri.conf.json'), ref)).productName;
+  const workDir = workDirOf(remoteDir, config.artifact);
+  const dir = join(config.outDir, 'build', 'macos');
+  mkdirSync(dir, { recursive: true });
+  for (const name of readdirSync(dir)) rmSync(join(dir, name), { force: true, recursive: true });
+  const scratch = mkdtempSync(join(tmpdir(), 'wb-mac-'));
+  try {
+    const exported = exportCommitted({ root, file: join(scratch, 'source.tgz'), ref, exclude: config.exportExclude, log });
+    const short = exported.sha.slice(0, 12);
+    const script = macBuildScript({ workDir, sha: exported.sha, artifact: config.artifact, productName, version, desktopDir: relative(root, config.desktopDir).replaceAll('\\', '/'), prepareCommand: config.prepareCommand });
+    writeFileSync(join(scratch, 'build.sh'), script.replaceAll('\r\n', '\n'));
+    const ssh = sshOptions({ key });
+    stream('ssh', [...ssh, target, `mkdir -p "$HOME/${workDir}" && find "$HOME/${workDir}" -maxdepth 1 -name 'source-*.tgz' -delete`], { log, label: 'mac: prepare' });
+    stream('scp', [...ssh, join(scratch, 'source.tgz'), `${target}:${workDir}/source-${short}.tgz`], { log, label: 'mac: upload' });
+    stream('scp', [...ssh, join(scratch, 'build.sh'), `${target}:${workDir}/build.sh`], { log, label: 'mac: upload script' });
+    const started = Date.now();
+    // A login shell: bun, cargo and node are set up in the Mac account's profile only.
+    stream('ssh', [...ssh, target, `zsh -lic "bash $HOME/${workDir}/build.sh"`], { log, label: 'mac: build' });
+    log(`mac: build took ${Math.round((Date.now() - started) / 1000)} s`);
+    stream('scp', [...ssh, `${target}:${workDir}/out/${config.artifact}_${version}_universal.dmg`, `${target}:${workDir}/out/${config.artifact}_${version}_universal.app.tar.gz`, dir], { log, label: 'mac: fetch' });
+    return { version, sha: exported.sha, dir, dmg: join(dir, `${config.artifact}_${version}_universal.dmg`), updater: join(dir, `${config.artifact}_${version}_universal.app.tar.gz`) };
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Builds the committed state of the app in a WSL distro (Ubuntu 22.04: the glibc floor) and puts
+ * the AppImage and the .deb in `<outDir>/build/linux`. Returns `{ version, sha, dir, appimage, deb }`.
+ */
+export function buildLinuxWsl({ config, distro = 'Ubuntu-22.04', remoteDir, ref = 'HEAD', env = process.env, log = console.log }) {
+  if (process.platform !== 'win32') fail('--wsl runs from Windows; on Linux run the build on the machine itself');
+  if (!/^[A-Za-z0-9._-]+$/.test(distro)) fail('bad WSL distro name');
+  const { root } = config;
+  const version = JSON.parse(committedFile(root, 'package.json', ref)).version;
+  const workDir = workDirOf(remoteDir, config.artifact);
+  const dir = join(config.outDir, 'build', 'linux');
+  mkdirSync(dir, { recursive: true });
+  for (const name of readdirSync(dir)) rmSync(join(dir, name), { force: true, recursive: true });
+  const scratch = mkdtempSync(join(tmpdir(), 'wb-linux-'));
+  try {
+    const exported = exportCommitted({ root, file: join(scratch, 'source.tgz'), ref, exclude: config.exportExclude, log });
+    const script = linuxBuildScript({ workDir, sha: exported.sha, artifact: config.artifact, version, desktopDir: relative(root, config.desktopDir).replaceAll('\\', '/'), prepareCommand: config.prepareCommand, tarball: join(scratch, 'source.tgz'), outDir: dir });
+    writeFileSync(join(scratch, 'build.sh'), script.replaceAll('\r\n', '\n'));
+    const started = Date.now();
+    // MSYS_NO_PATHCONV: Git Bash must not rewrite the /mnt paths of the script.
+    const wslScript = `/mnt/${scratch[0].toLowerCase()}/${scratch.slice(3).replaceAll('\\', '/')}/build.sh`;
+    const result = spawnSync('wsl', ['-d', distro, '--', 'bash', wslScript], { stdio: 'inherit', windowsHide: true, env: { ...env, MSYS_NO_PATHCONV: '1' } });
+    if (result.status !== 0) fail(`linux build in WSL ${distro} failed (exit ${result.status})`);
+    log(`linux: build took ${Math.round((Date.now() - started) / 1000)} s`);
+    return { version, sha: exported.sha, dir, appimage: join(dir, `${config.artifact}_${version}_amd64.AppImage`), deb: join(dir, `${config.artifact}_${version}_amd64.deb`) };
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+}
+
+const relTauri = (config, name) => `${relative(config.root, config.tauriDir).replaceAll('\\', '/')}/${name}`;
+
+/** Scans built artifacts here (the terms never leave this machine) and prints their sizes. */
+export function scanBuilt(config, files, { env = process.env, log = console.log } = {}) {
+  for (const file of files) {
+    if (!existsSync(file)) fail(`expected build output missing: ${file}`);
+    log(`built: ${basename(file)} ${(statSync(file).size / 1048576).toFixed(1)} MB`);
+  }
+  assertClean(files, { terms: config.forbiddenTerms, allowlist: config.privacyAllowlist, cwd: config.root, env, log, label: 'release: privacy-scan' });
+}

package/cli/store.mjs

@@ -0,0 +1,326 @@
+// `waybetter store build|sign|verify`: builds an app's part of the shared wayBetter Store catalog,
+// signs it offline with the store's Ed25519 key, and verifies it. The rules are the ones the apps
+// enforce natively (waybetter-host `store::catalog`); docs/STORE.md in the framework has the format.
+//
+//   waybetter store build --config store.config.mjs [--out dir] [--base https://…/store/]
+//   waybetter store sign [catalog.json] --key <private key> [--pub <public key file>]
+//   waybetter store sign --init --key <private key> --pub <public key file>   (once; never overwrites)
+//   waybetter store verify [catalog.json] --pub <public key file> [--app id]
+//
+// The private key is a PKCS#8 PEM that stays where it is: nothing here prints, copies or moves it.
+// `--key` defaults to $WAYBETTER_STORE_KEY. The signature file `<catalog>.sig` is the base64 of the
+// 64-byte signature over the exact catalog bytes; a public key file is the base64 of the raw 32 bytes.
+import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, sign, verify } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+export const CATALOG_FORMAT = 2;
+export const DEFAULT_BASE = 'https://waybetter.fyi/store/';
+/** The framework's download hosts (waybetter-host `DEFAULT_HOSTS`). */
+export const DEFAULT_HOSTS = [
+  { host: 'waybetter.fyi', rawFilesOnly: false },
+  { host: 'cdn1.crt.fyi', rawFilesOnly: false },
+  { host: 'git.crt.fyi', rawFilesOnly: true },
+];
+export const PERMISSIONS = ['storage', 'ui', 'clipboard', 'account', 'users', 'commands', 'network', 'network:none'];
+const MAX_BYTES = 2 * 1024 * 1024;
+const MAX_ITEMS = 500;
+const MAX_CATALOG_BYTES = 1024 * 1024;
+// SPKI DER prefix of an Ed25519 public key; the raw 32 bytes follow it.
+const SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+
+export const sha256 = bytes => createHash('sha256').update(bytes).digest('hex');
+
+/** A plugin header (waybetter-host `parse_meta`), enough for the catalog: name, description, version, author, permissions. */
+export function pluginHeader(source) {
+  const meta = { name: '', description: '', version: '', author: '', permissions: null };
+  const body = /^?\s*\/\*\*([\s\S]*?)\*\//.exec(source)?.[1];
+  if (!body) return meta;
+  for (const raw of body.split(/\r?\n/)) {
+    const line = raw.trim().replace(/^\*+/, '').trim();
+    const match = /^@(\w+)\s*(.*)$/.exec(line);
+    if (!match) continue;
+    const [, key, value] = match;
+    if (key === 'permissions') {
+      const list = value.split(/[\s,]+/).map(token => token.toLowerCase()).filter(token => token && token !== 'none');
+      for (const token of list) if (!PERMISSIONS.includes(token)) throw new Error(`unknown permission ${token}`);
+      meta.permissions = [...new Set([...(meta.permissions ?? []), ...list])];
+    // Same cap as the plugin store's parse_meta (300 characters, no control characters).
+    } else if (key in meta) meta[key] = [...value.trim()].filter(ch => ch >= ' ').slice(0, 300).join('');
+  }
+  return meta;
+}
+
+// ---- Validation (the same rules as waybetter-host store::catalog) ------------------------------
+
+const validAppId = id => typeof id === 'string' && /^[a-z0-9-]{1,32}$/.test(id);
+const validId = id => typeof id === 'string' && /^[a-z0-9-]{1,40}$/.test(id);
+const text = (value, max) => typeof value === 'string' && [...value].length <= max && !/[\p{Cc}]/u.test(value);
+const hex = value => typeof value === 'string' && /^#[0-9a-fA-F]{6}$/.test(value);
+export const validFileName = file => typeof file === 'string' && file.length > '.plugin.js'.length && file.length <= 128
+  && file.endsWith('.plugin.js') && !file.startsWith('.') && /^[A-Za-z0-9_\-. ]+$/.test(file);
+
+/** An https URL native code may download from (waybetter-host `allowed_download_url`). */
+export function allowedUrl(value, hosts = DEFAULT_HOSTS) {
+  let url;
+  try { url = new URL(value); } catch { return false; }
+  if (url.protocol !== 'https:' || url.username || url.password || url.port || url.hash || url.href.length > 2048) return false;
+  const rule = hosts.find(h => h.host === url.hostname);
+  if (!rule) return false;
+  if (rule.rawFilesOnly) {
+    const segments = url.pathname.split('/').slice(1);
+    return segments.length >= 4 && segments[2] === 'raw' && segments.every(s => s && s !== '..');
+  }
+  return true;
+}
+
+const ITEM_FIELDS = new Set(['apps', 'kind', 'id', 'name', 'author', 'version', 'description', 'category', 'tags', 'url', 'file', 'sha256', 'size', 'preview', 'permissions', 'colors', 'language', 'license', 'credits']);
+const LANGUAGE = /^[A-Za-z]{2,8}(-[A-Za-z0-9]{1,8})*$/;
+
+/** Problems with one item; `hosts` checks the download hosts (the reading app's own items). */
+export function itemProblems(item, hosts) {
+  const bad = [];
+  if (!item || typeof item !== 'object' || Array.isArray(item)) return ['not an object'];
+  for (const key of Object.keys(item)) if (!ITEM_FIELDS.has(key)) bad.push(`unknown field ${key}`);
+  if (!Array.isArray(item.apps) || !item.apps.length || item.apps.length > 16 || !item.apps.every(validAppId) || new Set(item.apps).size !== item.apps.length) bad.push('apps');
+  if (item.kind !== 'theme' && item.kind !== 'plugin' && item.kind !== 'strings') bad.push('kind');
+  // Any item may name its licence and credit its authors; only a string pack has a language.
+  if ((item.license !== undefined && (!text(item.license, 60) || !String(item.license).trim())) || (item.credits !== undefined && !text(item.credits, 600))) bad.push('license or credits');
+  if (item.kind !== 'strings' && item.language !== undefined) bad.push('language');
+  if (!validId(item.id)) bad.push('id');
+  if (!text(item.name, 60) || !String(item.name).trim() || !text(item.author ?? '', 60) || !text(item.description ?? '', 600)) bad.push('name, author or description');
+  if (!text(item.version, 32) || !item.version || !text(item.category ?? '', 32)) bad.push('version or category');
+  if (item.tags !== undefined && (!Array.isArray(item.tags) || item.tags.length > 12 || !item.tags.every(tag => text(tag, 32)))) bad.push('tags');
+  if (typeof item.url !== 'string' || !item.url.startsWith('https://') || (hosts && !allowedUrl(item.url, hosts))) bad.push('url (host not allowed)');
+  if (item.preview !== undefined && (typeof item.preview !== 'string' || !item.preview.startsWith('https://') || (hosts && !allowedUrl(item.preview, hosts)))) bad.push('preview');
+  if (typeof item.sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(item.sha256)) bad.push('sha256');
+  if (!Number.isInteger(item.size) || item.size <= 0 || item.size > MAX_BYTES) bad.push('size');
+  if (item.kind === 'plugin') {
+    if (!validFileName(item.file) || item.colors != null) bad.push('plugin file');
+    const p = item.permissions;
+    if (p != null && (!Array.isArray(p) || !p.every(x => PERMISSIONS.includes(x)) || new Set(p).size !== p.length || (p.includes('network') && p.includes('network:none')))) bad.push('permissions');
+  }
+  if (item.kind === 'strings') {
+    if (item.file !== undefined || item.permissions !== undefined || item.colors !== undefined) bad.push('string pack fields');
+    if (typeof item.language !== 'string' || !LANGUAGE.test(item.language)) bad.push('language');
+  }
+  if (item.kind === 'theme') {
+    if (item.file !== undefined || item.permissions !== undefined) bad.push('theme fields');
+    const c = item.colors;
+    if (c != null && (typeof c !== 'object' || Object.keys(c).some(k => !['bg', 'surface', 'text', 'accent'].includes(k)) || !hex(c.bg) || !hex(c.text) || !hex(c.accent) || (c.surface !== undefined && !hex(c.surface)))) bad.push('colors');
+  }
+  return bad;
+}
+
+/** Problems with a whole catalog (empty = valid). `app`: that app's items are held to `hosts`. */
+export function catalogProblems(catalog, { app, hosts = DEFAULT_HOSTS } = {}) {
+  const out = [];
+  if (!catalog || typeof catalog !== 'object') return ['catalog: not an object'];
+  for (const key of Object.keys(catalog)) if (!['format', 'name', 'generatedAt', 'items'].includes(key)) out.push(`catalog: unknown field ${key}`);
+  if (catalog.format !== CATALOG_FORMAT) out.push(`catalog: format must be ${CATALOG_FORMAT}`);
+  if (typeof catalog.name !== 'string' || typeof catalog.generatedAt !== 'string') out.push('catalog: name and generatedAt are strings');
+  if (!Array.isArray(catalog.items)) return [...out, 'catalog: items must be a list'];
+  if (catalog.items.length > MAX_ITEMS) out.push(`catalog: more than ${MAX_ITEMS} items`);
+  const ids = new Set();
+  const files = new Set();
+  for (const item of catalog.items) {
+    const where = `item ${item?.kind}:${item?.id}`;
+    for (const problem of itemProblems(item, app && item?.apps?.includes(app) ? hosts : undefined)) out.push(`${where}: invalid ${problem}`);
+    for (const a of Array.isArray(item?.apps) ? item.apps : []) {
+      const id = `${a}/${item.kind}/${item.id}`;
+      if (ids.has(id)) out.push(`${where}: duplicate for app ${a}`);
+      ids.add(id);
+      if (item.file) {
+        const file = `${a}/${String(item.file).toLowerCase()}`;
+        if (files.has(file)) out.push(`${where}: duplicate plugin file for app ${a}`);
+        files.add(file);
+      }
+    }
+  }
+  return out;
+}
+
+// ---- Build ------------------------------------------------------------------------------------
+
+/**
+ * Builds `config.app`'s part of the shared catalog in `out`: writes the files the config returns,
+ * replaces the app's items (other apps' items stay as they are), removes files only the app's old
+ * items used, validates the whole catalog and writes `catalog.json` (sign it afterwards).
+ *
+ * config: { app, name?, base?, out?, hosts?, items(context) → [{ kind, id, name, author, version,
+ *   description, category, tags, file (plugins), permissions (plugins), colors (themes), language
+ *   (string packs), license, credits,
+ *   path ('plugins/x.plugin.js'), bytes (Buffer|string), preview?: { path, bytes } }] }
+ */
+export async function buildStore(config, options = {}) {
+  const app = config.app;
+  if (!validAppId(app)) throw new Error('config.app must be an app id (a-z, 0-9, -)');
+  const base = options.base ?? config.base ?? DEFAULT_BASE;
+  if (!/^https:\/\/[^/]+\/(.*\/)?$/.test(base)) throw new Error('base must be an https URL ending in /');
+  const out = resolve(options.out ?? config.out ?? '.');
+  const hosts = config.hosts ?? DEFAULT_HOSTS;
+  const catalogPath = join(out, 'catalog.json');
+  const previous = existsSync(catalogPath) ? JSON.parse(readFileSync(catalogPath, 'utf8')) : null;
+  const kept = [];
+  const oldFiles = new Set();
+  for (const item of previous?.format === CATALOG_FORMAT ? previous.items : []) {
+    if (!item.apps?.includes(app)) { kept.push(item); continue; }
+    for (const url of [item.url, item.preview]) if (url?.startsWith(base)) oldFiles.add(url.slice(base.length));
+    const others = item.apps.filter(a => a !== app);
+    if (others.length) kept.push({ ...item, apps: others });
+  }
+  const inside = path => {
+    const target = resolve(out, path);
+    const rel = relative(out, target);
+    if (!rel || rel.startsWith('..') || isAbsolute(rel) || !/^[\w.\-/]+$/.test(path)) throw new Error(`file path must stay inside the store folder: ${path}`);
+    return target;
+  };
+  const entries = await config.items({ app, base, out });
+  const items = [];
+  const files = new Map();
+  const toBytes = value => (Buffer.isBuffer(value) ? value : Buffer.from(String(value), 'utf8'));
+  for (const entry of entries) {
+    const bytes = toBytes(entry.bytes);
+    files.set(entry.path, { target: inside(entry.path), bytes });
+    const item = { apps: [app], kind: entry.kind, id: entry.id, name: entry.name, author: entry.author ?? '', version: entry.version, description: entry.description ?? '', category: entry.category ?? '', tags: entry.tags ?? [], url: `${base}${entry.path}` };
+    if (entry.kind === 'plugin') item.file = entry.file;
+    item.sha256 = sha256(bytes);
+    item.size = bytes.length;
+    if (entry.preview) {
+      files.set(entry.preview.path, { target: inside(entry.preview.path), bytes: toBytes(entry.preview.bytes) });
+      item.preview = `${base}${entry.preview.path}`;
+    }
+    if (entry.kind === 'plugin') item.permissions = entry.permissions ?? null;
+    if (entry.kind === 'theme' && entry.colors) item.colors = entry.colors;
+    if (entry.kind === 'strings') item.language = entry.language;
+    if (entry.license !== undefined) item.license = entry.license;
+    if (entry.credits !== undefined) item.credits = entry.credits;
+    items.push(item);
+  }
+  const catalog = {
+    format: CATALOG_FORMAT,
+    name: config.name ?? previous?.name ?? 'wayBetter Store',
+    generatedAt: new Date().toISOString().replace(/\.\d+Z$/, 'Z'),
+    items: [...kept, ...items],
+  };
+  // Nothing is written unless the whole catalog is valid.
+  const problems = catalogProblems(catalog, { app, hosts });
+  if (problems.length) throw new Error(`the catalog would be invalid:\n  ${problems.join('\n  ')}`);
+  const json = `${JSON.stringify(catalog, null, 2)}\n`;
+  if (Buffer.byteLength(json) > MAX_CATALOG_BYTES) throw new Error('the catalog is larger than apps accept (1 MiB)');
+  for (const { target, bytes } of files.values()) { mkdirSync(dirname(target), { recursive: true }); writeFileSync(target, bytes); }
+  // Files this app's previous build wrote and no item uses any more (never another app's files).
+  const stillUsed = new Set(kept.flatMap(item => [item.url, item.preview]).filter(url => url?.startsWith(base)).map(url => url.slice(base.length)));
+  for (const path of oldFiles) if (!files.has(path) && !stillUsed.has(path)) rmSync(inside(path), { force: true });
+  mkdirSync(out, { recursive: true });
+  writeFileSync(catalogPath, json);
+  return { catalog, path: catalogPath, items };
+}
+
+// ---- Keys and signatures ----------------------------------------------------------------------
+
+export function rawPublicKey(publicKey) {
+  const der = publicKey.export({ format: 'der', type: 'spki' });
+  if (der.length !== 44 || !der.subarray(0, 12).equals(SPKI_PREFIX)) throw new Error('not an Ed25519 public key');
+  return der.subarray(12);
+}
+
+export function publicKeyFromBase64(value) {
+  const raw = Buffer.from(value.trim(), 'base64');
+  if (raw.length !== 32) throw new Error('a public key file must be the base64 of 32 raw bytes');
+  return createPublicKey({ key: Buffer.concat([SPKI_PREFIX, raw]), format: 'der', type: 'spki' });
+}
+
+/** Creates the store key once (0600, never overwritten) and writes its public key file. */
+export function initKey(keyPath, pubPath) {
+  if (existsSync(keyPath)) {
+    const base64 = rawPublicKey(createPublicKey(createPrivateKey(readFileSync(keyPath)))).toString('base64');
+    if (!existsSync(pubPath) || readFileSync(pubPath, 'utf8').trim() !== base64) { mkdirSync(dirname(pubPath), { recursive: true }); writeFileSync(pubPath, `${base64}\n`); }
+    return { created: false, publicKey: base64 };
+  }
+  mkdirSync(dirname(keyPath), { recursive: true });
+  const { privateKey, publicKey } = generateKeyPairSync('ed25519');
+  writeFileSync(keyPath, privateKey.export({ format: 'pem', type: 'pkcs8' }), { mode: 0o600, flag: 'wx' });
+  const base64 = rawPublicKey(publicKey).toString('base64');
+  mkdirSync(dirname(pubPath), { recursive: true });
+  writeFileSync(pubPath, `${base64}\n`);
+  return { created: true, publicKey: base64 };
+}
+
+/** Signs the exact bytes of `file` into `<file>.sig`; returns the public key (base64) that verifies it. */
+export function signFile(file, keyPath) {
+  const privateKey = createPrivateKey(readFileSync(keyPath));
+  const signature = sign(null, readFileSync(file), privateKey).toString('base64');
+  writeFileSync(`${file}.sig`, `${signature}\n`);
+  return rawPublicKey(createPublicKey(privateKey)).toString('base64');
+}
+
+/** Whether `<file>.sig` verifies with any of the public keys (base64 strings). */
+export function verifyFile(file, publicKeys) {
+  const signature = Buffer.from(readFileSync(`${file}.sig`, 'utf8').trim(), 'base64');
+  if (signature.length !== 64) return false;
+  const body = readFileSync(file);
+  return publicKeys.some(key => verify(null, body, publicKeyFromBase64(key), signature));
+}
+
+// ---- Command line -----------------------------------------------------------------------------
+
+const USAGE = `Usage:
+  waybetter store build --config <store.config.mjs> [--out <dir>] [--base <https://…/store/>]
+  waybetter store sign [catalog.json] --key <private key> [--pub <public key file>]
+  waybetter store sign --init --key <private key> --pub <public key file>
+  waybetter store verify [catalog.json] --pub <public key file>... [--app <id>]`;
+
+function parse(argv) {
+  const out = { positional: [], pub: [], init: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    const value = () => { const next = argv[++i]; if (next === undefined) throw new Error(`${arg} needs a value`); return next; };
+    if (arg === '--init') out.init = true;
+    else if (arg === '--pub') out.pub.push(resolve(value()));
+    else if (arg === '--key' || arg === '--config' || arg === '--out' || arg === '--base' || arg === '--app') out[arg.slice(2)] = value();
+    else if (arg.startsWith('--')) throw new Error(`unknown option ${arg}`);
+    else out.positional.push(arg);
+  }
+  return out;
+}
+
+/** Runs `waybetter store …`; returns the lines to print. Throws on errors. */
+export async function storeCommand(argv) {
+  const [command, ...rest] = argv;
+  const options = parse(rest);
+  const catalog = resolve(options.positional[0] ?? 'catalog.json');
+  const key = options.key ? resolve(options.key) : process.env.WAYBETTER_STORE_KEY;
+  if (command === 'build') {
+    if (!options.config) throw new Error(`build needs --config\n${USAGE}`);
+    const config = (await import(pathToFileURL(resolve(options.config)).href)).default;
+    const { path, items } = await buildStore(config, { out: options.out, base: options.base });
+    const count = kind => items.filter(item => item.kind === kind).length;
+    return [`store: ${config.app}: ${count('plugin')} plugins, ${count('theme')} themes → ${path}`, 'Now sign it: waybetter store sign <catalog.json> --key <private key>'];
+  }
+  if (command === 'sign') {
+    if (!key) throw new Error('sign needs --key (or WAYBETTER_STORE_KEY)');
+    if (options.init) {
+      if (!options.pub.length) throw new Error('--init needs --pub');
+      const { created, publicKey } = initKey(key, options.pub[0]);
+      return [`${created ? 'Created the store key' : 'Store key already exists'}; public key ${publicKey} → ${options.pub[0]}`];
+    }
+    if (!existsSync(key)) throw new Error(`no store key at ${key} (create it once with --init)`);
+    const publicKey = signFile(catalog, key);
+    const keys = options.pub.length ? options.pub.map(file => readFileSync(file, 'utf8').trim()) : [publicKey];
+    if (!verifyFile(catalog, keys)) throw new Error(`signature of ${catalog} does NOT verify with ${options.pub.join(', ') || 'the key'}`);
+    return [`Signed and verified ${catalog}.sig`];
+  }
+  if (command === 'verify') {
+    if (!options.pub.length) throw new Error('verify needs --pub');
+    const keys = options.pub.map(file => readFileSync(file, 'utf8').trim());
+    if (!verifyFile(catalog, keys)) throw new Error(`signature of ${catalog} does NOT verify with ${options.pub.join(', ')}`);
+    const problems = catalogProblems(JSON.parse(readFileSync(catalog, 'utf8')), { app: options.app });
+    if (problems.length) throw new Error(`${catalog} is signed but invalid:\n  ${problems.join('\n  ')}`);
+    return [`Verified ${catalog}.sig`];
+  }
+  throw new Error(USAGE);
+}
+
+export { USAGE as STORE_USAGE };