@theowlops/boombot 0.0.0-stage → 1.1.0

package/dist/cli/config-file.js

@@ -0,0 +1,133 @@
+/**
+ * BoomBot config file: read/write/validate `~/.boombot/config.json`.
+ *
+ * Format matches the spec shared with the gateway (executor A): the gateway
+ * reads exactly these fields. Channel sections are optional. Secrets are
+ * stored in the file (permissions 0600 on POSIX — a no-op on Windows, see
+ * SECURITY.md §5) — API keys are stored as sha256
+ * hashes only; the raw key is printed once at generation time and never
+ * persisted or logged.
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import { chmodSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+export class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ConfigError';
+    }
+}
+/** `~/...` → absolute path using the current user's home directory. */
+export function expandTilde(p) {
+    if (p === '~')
+        return homedir();
+    if (p.startsWith('~/') || p.startsWith('~\\'))
+        return path.join(homedir(), p.slice(2));
+    return p;
+}
+/** Safe profile names cannot escape `~/.boombot/profiles`. */
+export function isValidProfileName(value) {
+    return /^[a-z0-9][a-z0-9_-]{0,63}$/u.test(value);
+}
+/** Config path: `$BOOMBOT_CONFIG`, a named profile, or the legacy default. */
+export function resolveConfigPath() {
+    const fromEnv = process.env['BOOMBOT_CONFIG'];
+    if (fromEnv !== undefined && fromEnv !== '')
+        return expandTilde(fromEnv);
+    const profile = process.env['BOOMBOT_PROFILE'];
+    if (profile !== undefined && profile !== '') {
+        if (!isValidProfileName(profile)) {
+            throw new ConfigError('BOOMBOT_PROFILE must match [a-z0-9][a-z0-9_-]{0,63}');
+        }
+        return path.join(homedir(), '.boombot', 'profiles', profile, 'config.json');
+    }
+    return path.join(homedir(), '.boombot', 'config.json');
+}
+/** Load config from disk. Returns `null` when the file does not exist. */
+export function loadConfig(configPath = resolveConfigPath()) {
+    let raw;
+    try {
+        raw = readFileSync(configPath, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw new ConfigError(`cannot read config file ${configPath}: ${err.message}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new ConfigError(`config file ${configPath} is not valid JSON: ${err.message}`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new ConfigError(`config file ${configPath} must contain a JSON object`);
+    }
+    return parsed;
+}
+/** True when the config contains any secret material (tokens, key hash). */
+export function configHasSecrets(config) {
+    return (config.apiKeyHash !== undefined ||
+        (config.telegram?.botToken ?? '') !== '' ||
+        (config.discord?.botToken ?? '') !== '' ||
+        (config.slack?.botToken ?? '') !== '' ||
+        (config.whatsapp?.accessToken ?? '') !== '');
+}
+/**
+ * Write config to disk (creates parent dirs). When the config contains
+ * secrets the file is chmod'ed to 0600.
+ *
+ * POSIX-only: on Windows `chmodSync` cannot set ACLs (no-op), so the file
+ * is NOT actually protected there — `boombot doctor` reports WARN instead
+ * of PASS in that case. See SECURITY.md §5.
+ */
+export function saveConfig(config, configPath = resolveConfigPath(), flag = 'w') {
+    mkdirSync(path.dirname(configPath), { recursive: true });
+    writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', {
+        encoding: 'utf8', flag, mode: configHasSecrets(config) ? 0o600 : 0o666,
+    });
+    if (configHasSecrets(config)) {
+        chmodSync(configPath, 0o600);
+    }
+}
+/** Basic validation; returns a list of human-readable problems (empty = valid). */
+export function validateConfig(config) {
+    const problems = [];
+    if (typeof config.host !== 'string' || config.host.trim() === '') {
+        problems.push('host must be a non-empty string');
+    }
+    if (!Number.isInteger(config.port) || config.port < 1 || config.port > 65535) {
+        problems.push('port must be an integer between 1 and 65535');
+    }
+    if (typeof config.dataDir !== 'string' || config.dataDir.trim() === '') {
+        problems.push('dataDir must be a non-empty string');
+    }
+    if (config.apiKeyHash !== undefined && !/^[0-9a-f]{64}$/.test(config.apiKeyHash)) {
+        problems.push('apiKeyHash must be a sha256 hex string (64 lowercase hex chars)');
+    }
+    return problems;
+}
+/** Generate a fresh API key: 32 random bytes as hex; hash with sha256. */
+/**
+ * sha256 hex digest of an API key — the only form ever persisted. The gateway
+ * computes the same digest in its `auth.ts`; this is the single owner of the
+ * recipe on the CLI side, so nothing else re-implements it and drifts.
+ */
+export function hashApiKey(apiKey) {
+    return createHash('sha256').update(apiKey, 'utf8').digest('hex');
+}
+export function generateApiKey() {
+    const apiKey = randomBytes(32).toString('hex');
+    return { apiKey, apiKeyHash: hashApiKey(apiKey) };
+}
+/** Current permission bits of a file (e.g. 0o600), or null when it cannot be stat'ed. */
+export function fileModeBits(filePath) {
+    try {
+        return statSync(filePath).mode & 0o777;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/cli/master-key.js

@@ -0,0 +1,78 @@
+/**
+ * Master key for provider API-key encryption (`@boombot/protocol`).
+ *
+ * The gateway refuses to boot without `BOOMBOT_MASTER_KEY` (its provider
+ * service stores keys AES-256-GCM encrypted). For the `npm i -g` golden path
+ * (`boombot setup` → `boombot gateway`) the wizard generates the key once and
+ * stores it at `~/.boombot/master.key` (next to the config file, mode 0600 on
+ * POSIX); `boombot gateway` loads it into the environment before booting the
+ * gateway in-process.
+ *
+ * The raw key is never printed or logged — only its presence is reported.
+ */
+import { randomBytes } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { resolveConfigPath } from "./config-file.js";
+/**
+ * Default master-key path: `master.key` next to the config file
+ * (`~/.boombot/master.key` unless `$BOOMBOT_CONFIG` points elsewhere).
+ */
+export function resolveMasterKeyPath(configPath = resolveConfigPath()) {
+    return path.join(path.dirname(configPath), 'master.key');
+}
+/** Read the stored master key, or `null` when absent/empty/unreadable. */
+export function loadMasterKey(keyPath = resolveMasterKeyPath()) {
+    let raw;
+    try {
+        raw = readFileSync(keyPath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    const key = raw.trim();
+    return key === '' ? null : key;
+}
+/** True when a master key is available (file or environment). */
+export function hasMasterKey(keyPath = resolveMasterKeyPath()) {
+    const fromEnv = process.env['BOOMBOT_MASTER_KEY'];
+    if (fromEnv !== undefined && fromEnv !== '')
+        return true;
+    return existsSync(keyPath) && loadMasterKey(keyPath) !== null;
+}
+/**
+ * Return the existing master key, generating and persisting a fresh one
+ * (0600 on POSIX; best-effort on Windows, see SECURITY.md §5) when absent.
+ */
+export function ensureMasterKey(keyPath = resolveMasterKeyPath()) {
+    const existing = loadMasterKey(keyPath);
+    if (existing !== null)
+        return existing;
+    const key = randomBytes(32).toString('hex');
+    mkdirSync(path.dirname(keyPath), { recursive: true });
+    writeFileSync(keyPath, `${key}\n`, { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+    if (process.platform !== 'win32') {
+        chmodSync(keyPath, 0o600);
+    }
+    return key;
+}
+/**
+ * Make sure `BOOMBOT_MASTER_KEY` is set in this process before the gateway
+ * boots (the CLI runs the gateway in-process). Prefers an already-set env
+ * var; falls back to the stored key file.
+ *
+ * Throws a human-readable error when no key can be found — the caller
+ * (`boombot gateway`) surfaces it instead of the gateway's boot crash.
+ */
+export function ensureMasterKeyEnv(keyPath = resolveMasterKeyPath()) {
+    const fromEnv = process.env['BOOMBOT_MASTER_KEY'];
+    if (fromEnv !== undefined && fromEnv !== '')
+        return;
+    const stored = loadMasterKey(keyPath);
+    if (stored === null) {
+        throw new Error('no master key found: the gateway needs BOOMBOT_MASTER_KEY to decrypt provider API keys.\n' +
+            `Run \`boombot setup\` to generate one (stored at ${keyPath}, mode 0600), ` +
+            'or set BOOMBOT_MASTER_KEY in the environment.');
+    }
+    process.env['BOOMBOT_MASTER_KEY'] = stored;
+}

package/dist/cli/open-browser.js

@@ -0,0 +1,59 @@
+/**
+ * Best-effort "open this URL in the user's browser".
+ *
+ * Used by `boombot gateway` after the server is listening. Platform-native:
+ * `open` (macOS), `cmd /c start` (Windows), `xdg-open` (Linux/others).
+ * Never throws and never blocks the CLI: headless machines, missing helpers
+ * or a denied spawn all degrade to "the URL was printed, open it yourself".
+ */
+import { spawn } from 'node:child_process';
+/** Opt-out env var (headless servers, CI): `BOOMBOT_NO_BROWSER=1`. */
+export const NO_BROWSER_ENV = 'BOOMBOT_NO_BROWSER';
+function browserCommand(url) {
+    if (process.env[NO_BROWSER_ENV] === '1')
+        return null;
+    switch (process.platform) {
+        case 'darwin':
+            return { cmd: 'open', args: [url] };
+        case 'win32':
+            // `start` needs a (possibly empty) window title as its first argument.
+            return { cmd: 'cmd', args: ['/c', 'start', '', url] };
+        default:
+            return { cmd: 'xdg-open', args: [url] };
+    }
+}
+/**
+ * Open `url` in the default browser. Resolves `true` when the OS accepted
+ * the request, `false` when there was nothing to try or it failed.
+ * Never rejects.
+ */
+export async function openBrowser(url) {
+    const target = browserCommand(url);
+    if (target === null)
+        return false;
+    return new Promise((resolve) => {
+        let settled = false;
+        const done = (ok) => {
+            if (!settled) {
+                settled = true;
+                resolve(ok);
+            }
+        };
+        let child;
+        try {
+            // No shell: the URL is passed as a single argv entry (injection-safe).
+            // Detached + unref'd: the browser outlives the CLI; the CLI never
+            // waits for it.
+            child = spawn(target.cmd, target.args, { detached: true, stdio: 'ignore' });
+        }
+        catch {
+            done(false);
+            return;
+        }
+        child.once('error', () => done(false));
+        child.unref();
+        // Don't wait for the browser to exit — a short grace period is enough
+        // to catch an immediate spawn failure (e.g. helper not installed).
+        setTimeout(() => done(true), 400);
+    });
+}

package/dist/cli/web-assets.js

@@ -0,0 +1,58 @@
+/**
+ * Locate the bundled web-UI assets (`dist/web/`) from the CLI.
+ *
+ * Mirrors the gateway's file-relative resolution (`static.ts`), so
+ * `boombot doctor` can report whether the UI the gateway would serve actually
+ * exists — without depending on `process.cwd()`.
+ *
+ * Layouts handled (first existing directory wins):
+ * - npm dist, bundled CLI:  `dist/bin/boombot.js`      → `dist/web/`
+ * - npm dist, per-file tsc: `dist/bin/commands/*.js`  → `dist/web/`
+ * - monorepo dev:           `apps/cli/src/commands/*` → `apps/web/dist/`
+ * - `BOOMBOT_WEB_ROOT` (when set): explicit operator override, authoritative —
+ *   a missing path reports not-found instead of probing other locations.
+ */
+import { existsSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+function moduleDir() {
+    return path.dirname(fileURLToPath(import.meta.url));
+}
+/** `true` when `dir` looks like `<pkg>/dist/bin[/…]` (the npm dist layout). */
+export function isDistLayoutDir(dir) {
+    const parts = dir.split(path.sep);
+    const distIndex = parts.lastIndexOf('dist');
+    return distIndex >= 0 && parts[distIndex + 1] === 'bin';
+}
+function isDirectory(p) {
+    try {
+        return existsSync(p) && statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export function resolveWebAssets() {
+    const dir = moduleDir();
+    const isDistLayout = isDistLayoutDir(dir);
+    const override = process.env['BOOMBOT_WEB_ROOT'];
+    if (override !== undefined && override.trim() !== '') {
+        // Authoritative: an explicit override never falls back to probing.
+        const resolved = path.resolve(override);
+        const found = isDirectory(resolved);
+        return { found, path: found ? resolved : null, isDistLayout };
+    }
+    const candidates = [
+        // dist/bin/boombot.js → dist/web ; dist/bin/commands/x.js → dist/web
+        path.resolve(dir, '..', 'web'),
+        path.resolve(dir, '..', '..', 'web'),
+        // apps/cli/src → apps/web/dist (monorepo dev, `vite build` output)
+        path.resolve(dir, '..', '..', '..', 'apps', 'web', 'dist'),
+    ];
+    for (const candidate of candidates) {
+        if (isDirectory(candidate)) {
+            return { found: true, path: candidate, isDistLayout };
+        }
+    }
+    return { found: false, path: null, isDistLayout };
+}

package/dist/gateway/auth.js

@@ -0,0 +1,46 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+/**
+ * Bearer authentication for the gateway HTTP server.
+ *
+ * The operator's API key is never stored: `config.apiKeyHash` holds the
+ * SHA-256 hex digest (written once by the setup flow), and every request's
+ * `Authorization: Bearer <key>` is hashed and compared in constant time.
+ * Failing checks never reveal whether the key was missing, malformed, or
+ * wrong — all are 401.
+ */
+/** SHA-256 hex digest of a raw API key. The raw key itself is never persisted. */
+export function hashApiKey(key) {
+    return createHash('sha256').update(key, 'utf8').digest('hex');
+}
+/** Extract the bearer token from `Authorization: Bearer <token>`. Undefined when absent or malformed. */
+export function extractBearerToken(req) {
+    const header = req.headers.authorization;
+    if (typeof header !== 'string')
+        return undefined;
+    const [scheme, token] = header.split(' ');
+    if (scheme?.toLowerCase() !== 'bearer' || !token)
+        return undefined;
+    return token;
+}
+function safeEqualHex(a, b) {
+    const aBuf = Buffer.from(a, 'utf8');
+    const bBuf = Buffer.from(b, 'utf8');
+    // timingSafeEqual throws on length mismatch; lengths differ only when the
+    // stored hash is corrupt, which must fail closed anyway.
+    return aBuf.length === bBuf.length && timingSafeEqual(aBuf, bBuf);
+}
+/**
+ * Check bearer auth for an incoming request. Fail-closed: when the gateway
+ * has no `apiKeyHash` configured, every check fails with AUTH_NOT_CONFIGURED.
+ * Callers translate a failed check into a 401 error envelope.
+ */
+export function checkAuth(req, config) {
+    if (!config.apiKeyHash) {
+        return { ok: false, code: 'AUTH_NOT_CONFIGURED', message: 'Gateway API key is not configured' };
+    }
+    const token = extractBearerToken(req);
+    if (!token || !safeEqualHex(hashApiKey(token), config.apiKeyHash)) {
+        return { ok: false, code: 'UNAUTHORIZED', message: 'Invalid or missing API key' };
+    }
+    return { ok: true };
+}

package/dist/gateway/config-format.js

@@ -0,0 +1,202 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { extname, join } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+/**
+ * Config file format.
+ *
+ * `config.yml` is the primary format because YAML allows **comments** — and a
+ * config file with a channel section where each field can be annotated
+ * (`# Slack: app-level token, starts with xapp-`) is something JSON cannot do.
+ * `config.json` is still read so old setups don't break.
+ *
+ * Format is chosen by FILE EXTENSION: `.json` goes through `JSON.parse` (keeps
+ * the old error message the tests assert on), every other extension goes to the
+ * YAML parser. YAML 1.2 is a superset of JSON, so JSON content read by the YAML
+ * parser still parses correctly — meaning a `$BOOMBOT_CONFIG` pointing at an
+ * odd path won't be misread.
+ *
+ * Why a separate module: `config.ts` owns the *schema* (which keys, which
+ * types), while this module owns the *format* (reading text into an object,
+ * and YAML coercion rules). Mixing both into one file means every format
+ * change touches the schema too.
+ */
+/** File probe order when `$BOOMBOT_CONFIG` is unset; first existing file wins. */
+export const CONFIG_FILE_NAMES = ['config.yml', 'config.yaml', 'config.json'];
+/** Default config directory: `~/.boombot`. */
+export function defaultConfigDir(env = process.env) {
+    const profile = env['BOOMBOT_PROFILE'];
+    if (profile === undefined || profile === '')
+        return join(homedir(), '.boombot');
+    if (!/^[a-z0-9][a-z0-9_-]{0,63}$/u.test(profile)) {
+        throw new Error('BOOMBOT_PROFILE must match [a-z0-9][a-z0-9_-]{0,63}');
+    }
+    return join(homedir(), '.boombot', 'profiles', profile);
+}
+/** Default WRITE path: `~/.boombot/config.yml`. */
+export function defaultConfigPath(env = process.env) {
+    return join(defaultConfigDir(env), 'config.yml');
+}
+/**
+ * READ path: `$BOOMBOT_CONFIG` when set, otherwise the first existing file in
+ * `CONFIG_FILE_NAMES`, otherwise the default write path (so error messages
+ * and the first write point at the same place).
+ *
+ * Deliberately does not hard-prefer `config.yml`: a running machine may have a
+ * legacy `config.json`, and forcing the user to rename the file before the
+ * gateway boots is the surest way to hand them a 401 they can't explain.
+ */
+export function resolveConfigFilePath(env = process.env) {
+    const explicit = env['BOOMBOT_CONFIG'];
+    if (explicit !== undefined && explicit !== '')
+        return explicit;
+    for (const name of CONFIG_FILE_NAMES) {
+        const candidate = join(defaultConfigDir(env), name);
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return defaultConfigPath(env);
+}
+/** Describes a value's type for error messages; never prints the value (may be a secret). */
+function describe(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'a list';
+    switch (typeof value) {
+        case 'object':
+            return 'a mapping';
+        case 'number':
+            return 'a number';
+        case 'boolean':
+            return 'a boolean';
+        default:
+            return `a ${typeof value}`;
+    }
+}
+/**
+ * Reads a config file into a raw object. A missing file yields `{}` (config is
+ * optional). A present-but-broken file throws — never return `{}` for a file
+ * that reads but is wrong, because then the gateway would run on defaults while
+ * the user believes their config was applied.
+ */
+export function readConfigObject(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return {};
+        throw new Error(`Cannot read gateway config at ${path}: ${error.message}`);
+    }
+    const isJson = extname(path).toLowerCase() === '.json';
+    let parsed;
+    if (isJson) {
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            throw new Error(`Gateway config at ${path} is not valid JSON`);
+        }
+    }
+    else {
+        try {
+            parsed = parseYaml(raw, { version: '1.2' });
+        }
+        catch (error) {
+            throw new Error(`Gateway config at ${path} is not valid YAML: ${error.message}`);
+        }
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`Gateway config at ${path} must be a ${isJson ? 'JSON object' : 'YAML mapping'}`);
+    }
+    return parsed;
+}
+/** Channel fields that take a boolean; every other field is a string (or list of strings). */
+const CHANNEL_BOOLEAN_FIELDS = new Set(['enabled']);
+const CHANNEL_LIST_FIELDS = new Set(['allowlistChatIds']);
+/**
+ * Every field `ChannelConnectionConfig` declares. Used to CATCH MISSPELLED
+ * NAMES: `botToke:` in YAML would be silently swallowed and surface as "channel
+ * not running" — the most time-expensive kind of bug to track down.
+ *
+ * This is a shared allowlist, not a per-channel schema: `telegram.accessToken`
+ * still passes. True per-channel validation needs a full schema; all that's
+ * needed here is catching typos.
+ */
+const KNOWN_CHANNEL_FIELDS = new Set([
+    'enabled',
+    'botToken',
+    'allowlistChatIds',
+    'guildId',
+    'publicKey',
+    'signingSecret',
+    'appToken',
+    'phoneNumberId',
+    'accessToken',
+    'verifyToken',
+    'bridgeUrl',
+    'oaToken',
+    'pageAccessToken',
+    'appSecret',
+    'appId',
+    'clientSecret',
+]);
+/**
+ * Coerces a scalar value to a string.
+ *
+ * YAML turns an unquoted `phoneNumberId: 1029384756` into a **number**. That's
+ * the most natural way to write it, so coerce to string instead of forcing the
+ * user to remember quoting — BUT only when the number survived intact. IDs past
+ * 2^53 lose digits going through JS's number type, and an ID wrong in its last
+ * few digits is the worst kind of bug in this file: the channel silently sends
+ * to the wrong place. In that case throw and tell the user to quote it, rather
+ * than guessing.
+ */
+function coerceScalarString(value, at) {
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' && Number.isSafeInteger(value))
+        return String(value);
+    const hint = typeof value === 'number' ? ' — quote it to keep every digit' : '';
+    throw new Error(`Gateway config "${at}" must be a string (got ${describe(value)})${hint}`);
+}
+/**
+ * Normalizes a channel section: drops empty fields, coerces types, and rejects
+ * unknown fields.
+ *
+ * `configPath` is only used so error messages name the right file when multiple
+ * config sources exist (`.yml` next to `.json`).
+ */
+export function coerceChannelSection(kind, raw, configPath) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        throw new Error(`Gateway config at ${configPath}: "channels.${kind}" must be a mapping`);
+    }
+    const section = {};
+    for (const [field, value] of Object.entries(raw)) {
+        if (!KNOWN_CHANNEL_FIELDS.has(field)) {
+            throw new Error(`Gateway config at ${configPath}: unknown field "channels.${kind}.${field}"`);
+        }
+        // An empty `field:` in YAML yields null — treat as undeclared.
+        if (value === undefined || value === null)
+            continue;
+        const at = `channels.${kind}.${field}`;
+        if (CHANNEL_BOOLEAN_FIELDS.has(field)) {
+            if (typeof value !== 'boolean') {
+                throw new Error(`Gateway config "${at}" must be a boolean (got ${describe(value)})`);
+            }
+            section[field] = value;
+        }
+        else if (CHANNEL_LIST_FIELDS.has(field)) {
+            if (!Array.isArray(value)) {
+                throw new Error(`Gateway config "${at}" must be a list (got ${describe(value)})`);
+            }
+            section[field] = value.map((item) => coerceScalarString(item, `${at}[]`));
+        }
+        else {
+            section[field] = coerceScalarString(value, at);
+        }
+    }
+    return section;
+}