@dokebi/cli 0.4.26 → 0.4.28

package/dist/production-doctor.js

@@ -0,0 +1,176 @@
+// `dokebi doctor --production` (D-0184 §4): the checks of a server, on the settings the app
+// reads there (DOKEBI_CONFIG, merged with the secrets file DOKEBI_SECRETS). The per-process
+// state rules mirror what the plugins refuse at start in production (D-0161), so a deploy learns
+// them before the restart instead of from a failed start.
+import { spawn } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { isAbsolute, join } from 'node:path';
+import { applySecrets, ConfigError, parseConfig, SECRETS_VARIABLE } from '@dokebi/config';
+import { kept } from './check/shared-state-rules.js';
+import { placeholderPaths } from './config-init.js';
+import { configSecrets } from './config-secrets.js';
+import { readSettings } from './config-show.js';
+import { debug, describeError } from './diagnostics.js';
+import { CliError } from './errors.js';
+import { parseObject } from './filesystem.js';
+import { optionsKey } from './manifest.js';
+import { readState } from './project-state.js';
+function valueAt(options, path) {
+    let value = options;
+    for (const key of path) {
+        if (value && typeof value === 'object' && !Array.isArray(value) && Object.hasOwn(value, key))
+            value = value[key];
+        else
+            return undefined;
+    }
+    return value;
+}
+/** `dokebi-migrate status --json` with the settings of the server; undefined when it cannot run. */
+function migrationStatus(root, env) {
+    return new Promise((resolve) => {
+        let stdout = '';
+        const child = spawn(join(root, 'node_modules', '.bin', 'dokebi-migrate'), ['status', '--json'], {
+            cwd: root,
+            env,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 60_000,
+        });
+        child.stdout.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk;
+        });
+        child.once('error', (error) => {
+            debug('dokebi-migrate status could not run', { error: describeError(error) });
+            resolve(undefined);
+        });
+        child.once('close', () => {
+            try {
+                resolve(JSON.parse(stdout));
+            }
+            catch (error) {
+                debug('dokebi-migrate status gave no JSON', { error: describeError(error) });
+                resolve(undefined);
+            }
+        });
+    });
+}
+/** The production diagnostics of the project at `root` (D-0184 §4). */
+export async function productionDiagnostics(root, env = process.env) {
+    const found = [];
+    const add = (code, severity, path, hint, plugin = null, details) => found.push({
+        code,
+        severity,
+        path,
+        plugin,
+        hint,
+        ...(details === undefined ? {} : { details }),
+    });
+    if (env.NODE_ENV !== 'production')
+        add('NODE_ENV_NOT_PRODUCTION', 'error', 'NODE_ENV', 'NODE_ENV is not production here, so this check (and an app started like this) runs with development behaviour: run it as the service runs, NODE_ENV=production npx dokebi doctor --production (the systemd unit and compose file set it)');
+    const { target, source } = await readSettings(root);
+    const secretsFile = env[SECRETS_VARIABLE] || undefined;
+    let options;
+    try {
+        options = (await applySecrets(parseConfig(source), secretsFile)).options;
+    }
+    catch (error) {
+        if (!(error instanceof ConfigError))
+            throw error;
+        // The app would refuse to start with the same code; the rest is checked on the file alone.
+        add(error.code, 'error', target.file, `${error.message}. ${error.fix}`, 'dokebi-config', {
+            issues: error.issues,
+        });
+        // A settings file that does not parse has nothing more to check; a secrets problem leaves
+        // the settings file itself readable.
+        if (!error.code.startsWith('CONFIG_SECRETS') && !/secrets file/.test(error.message))
+            return found;
+        options = parseConfig(source).options;
+    }
+    const state = readState(parseObject(await readFile(join(root, '.dokebi/state.json'), 'utf8'), 'state'));
+    const installed = new Set(state.plugins.map((plugin) => optionsKey(plugin)));
+    // The same state `dokebi check` names for several workers (D-0161): in production one process
+    // is refused too (a restart loses it).
+    const redis = Object.keys(valueAt(options['dokebi-redis'], ['connections']) ??
+        {})[0];
+    for (const item of kept(installed, options))
+        add('STATE_NOT_SHARED', 'error', item.path.join('.'), `${item.what} would live in one process and be lost on every restart; the plugin refuses to start so in production (D-0161): ${item.fix(redis)}`, item.path[0] ?? null);
+    for (const plugin of ['dokebi-lock', 'dokebi-cache'])
+        if (installed.has(plugin)) {
+            const backends = valueAt(options[plugin], ['backends']);
+            for (const [name, backend] of Object.entries(backends && typeof backends === 'object' ? backends : {}))
+                if ((valueAt(backend, ['driver']) ?? 'local') === 'local')
+                    add('STATE_NOT_SHARED', 'warning', `${plugin}.backends.${name}`, `the ${name} backend is local to one process: right for one process, wrong for a cluster or two instances that must share it; use driver: redis for shared ${plugin === 'dokebi-lock' ? 'locks' : 'cache entries'}`, plugin);
+        }
+    if (installed.has('dokebi-mail')) {
+        const driver = valueAt(options['dokebi-mail'], ['transport', 'driver']) ?? 'log';
+        if (driver === 'log' || driver === 'capture')
+            add('TRANSPORT_NOT_FOR_PRODUCTION', 'error', 'dokebi-mail.transport.driver', `the ${String(driver)} transport keeps mail in memory and the plugin refuses it in production: set options.dokebi-mail.transport to smtp or ses`, 'dokebi-mail');
+    }
+    if (installed.has('dokebi-web')) {
+        const web = options['dokebi-web'];
+        const port = valueAt(web, ['port']);
+        if (typeof port !== 'number' || port === 0)
+            add('WEB_PORT_UNSET', 'error', 'dokebi-web.port', 'the port is 0 (any free port), so the reverse proxy cannot reach the app: set the instance port (deploy init writes it)', 'dokebi-web');
+        const trust = valueAt(web, ['trustProxy']);
+        if (!Array.isArray(trust) || trust.length === 0)
+            add('TRUST_PROXY_EMPTY', 'warning', 'dokebi-web.trustProxy', 'behind a reverse proxy the app must trust its address, or it ignores X-Forwarded-Proto and -Host (http URLs, cookies without Secure, wrong client addresses): list the proxy addresses, 127.0.0.1 and ::1 on the same server', 'dokebi-web');
+        const host = valueAt(web, ['host']) ?? '127.0.0.1';
+        if (host === '0.0.0.0' || host === '::')
+            add('WEB_LISTENS_EVERYWHERE', 'warning', 'dokebi-web.host', 'the app listens on every interface, so it can be reached without the reverse proxy (no TLS): listen on 127.0.0.1 unless a firewall closes the port', 'dokebi-web');
+    }
+    if (installed.has('dokebi-storage')) {
+        const storage = options['dokebi-storage'];
+        const directory = valueAt(storage, ['directory']) ?? '.dokebi/storage';
+        if ((valueAt(storage, ['driver']) ?? 'local') === 'local' && !isAbsolute(String(directory)))
+            add('STORAGE_RELATIVE', 'warning', 'dokebi-storage.directory', `the stored files go to ${String(directory)} inside the working folder, which a new release replaces: set an absolute folder outside the release (deploy init uses /var/lib/<app>/<instance>/storage)`, 'dokebi-storage');
+    }
+    const placeholders = placeholderPaths(options);
+    if (placeholders.length)
+        add('PLACEHOLDER_LEFT', 'error', target.file, `these options still hold a <placeholder> of the sample: ${placeholders.join(', ')}; fill them in the settings (or the secrets file)`, null, { paths: placeholders });
+    if (!found.some((item) => item.code.startsWith('CONFIG_SECRETS'))) {
+        try {
+            const secrets = await configSecrets(root, env);
+            for (const warning of secrets.warnings ?? [])
+                add(warning.code, 'warning', warning.path, warning.hint);
+            const unlisted = secrets.missing.filter((path) => !secrets.listed.includes(path));
+            if (unlisted.length)
+                add('SECRETS_MISSING', 'error', target.file, `secrets the installed plugins need are not set: ${unlisted.join(', ')}; put them in the secrets file (npx dokebi config secrets --json)`, null, { paths: unlisted });
+        }
+        catch (error) {
+            if (!(error instanceof CliError))
+                throw error;
+            add(error.code, 'error', target.file, error.message);
+        }
+    }
+    if (installed.has('dokebi-migrate')) {
+        const status = await migrationStatus(root, {
+            ...env,
+            ...(env.DOKEBI_CONFIG ? {} : { DOKEBI_CONFIG: target.path }),
+        });
+        if (!status?.results)
+            add('MIGRATIONS_UNCHECKED', 'error', 'dokebi-migrate', `dokebi-migrate status could not read the migrations${status?.error?.code ? ` (${status.error.code}: ${status.error.message ?? ''})` : ''}: check its options and that the database is reachable with these settings (npx dokebi-migrate status)`, 'dokebi-migrate');
+        else
+            for (const [connection, list] of Object.entries(status.results)) {
+                const pending = list.filter((item) => item.state === 'pending');
+                const before = pending
+                    .filter((item) => item.phase !== 'post-deploy')
+                    .map((item) => item.name);
+                const after = pending
+                    .filter((item) => item.phase === 'post-deploy')
+                    .map((item) => item.name);
+                const missing = list.filter((item) => item.state === 'missing').map((item) => item.name);
+                if (before.length)
+                    add('MIGRATIONS_PENDING', 'error', `dokebi-migrate.connections.${connection}`, `${before.length} migration(s) to apply before the new code starts: ${before.join(', ')}; run npx dokebi-migrate up --phase pre-deploy --json (DEPLOY.md, release step 2)`, 'dokebi-migrate');
+                if (after.length)
+                    add('MIGRATIONS_POST_DEPLOY_PENDING', 'warning', `dokebi-migrate.connections.${connection}`, `post-deploy migration(s) wait for the switch: ${after.join(', ')}; run npx dokebi-migrate up --json after the new code runs`, 'dokebi-migrate');
+                if (missing.length)
+                    add('MIGRATION_FILE_MISSING', 'warning', `dokebi-migrate.connections.${connection}`, `applied migrations whose files are gone (an older release folder?): ${missing.join(', ')}`, 'dokebi-migrate');
+            }
+    }
+    debug('Production checks done', {
+        errors: found.filter((item) => item.severity === 'error').length,
+        warnings: found.filter((item) => item.severity === 'warning').length,
+        secretsFile: secretsFile !== undefined,
+    });
+    return found;
+}

package/dist/project-inspector.js

@@ -1,5 +1,6 @@
 import { readdir, readFile, realpath, stat } from 'node:fs/promises';
 import { join } from 'node:path';
+import { applySecrets, ConfigError, SECRETS_VARIABLE } from '@dokebi/config';
 import satisfies from 'semver/functions/satisfies.js';
 import valid from 'semver/functions/valid.js';
 import { CONFIG_FILE, configTarget, FRESH_COPY_FIX, LEGACY_CONFIG_FILE, parseProjectConfig, readProjectConfigSource, } from './configuration.js';
@@ -193,7 +194,22 @@ export class ProjectInspector {
                     throw new CliError((await exists(await securePath(root, CONFIG_FILE)))
                         ? 'CONFIG_CONFLICT'
                         : 'MIGRATION_REQUIRED', 'Explicit YAML migration is required');
-                return parseProjectConfig(await read(configFile));
+                const parsed = parseProjectConfig(await read(configFile));
+                // D-0184: on a server the options are the settings with the secrets file merged.
+                const secrets = process.env[SECRETS_VARIABLE];
+                if (!secrets)
+                    return parsed;
+                try {
+                    const merged = await applySecrets({ schemaVersion: 1, options: parsed.options }, secrets);
+                    return { ...parsed, options: merged.options };
+                }
+                catch (error) {
+                    if (!(error instanceof ConfigError))
+                        throw error;
+                    throw new CliError(error.code, error.message, {
+                        details: { issues: error.issues, fix: error.fix },
+                    });
+                }
             });
         result.requiredPlugins =
             (await check('node_modules/@dokebi/core/package.json', () => readRequiredPlugins(root))) ??

package/dist/remote-verify.d.ts

@@ -0,0 +1,31 @@
+export interface RemoteCheck {
+    readonly name: string;
+    readonly ok: boolean;
+    /** A failed check that is only a warning (the result stays ok). */
+    readonly warning?: boolean;
+    readonly status?: number;
+    readonly detail: string;
+    readonly ms: number;
+}
+export interface RemoteVerifyResult {
+    readonly ok: boolean;
+    readonly url: string;
+    readonly checks: readonly RemoteCheck[];
+    readonly certificate?: {
+        readonly subject: string;
+        readonly issuer: string;
+        readonly validTo: string;
+        readonly daysLeft: number;
+    };
+}
+export interface RemoteVerifyOptions {
+    readonly root?: string;
+    readonly timeoutMs?: number;
+    /** Trusted certificates besides the system's (tests: a local CA). */
+    readonly ca?: string;
+    /** The port of the plain http check (default 80; tests use a free one). */
+    readonly httpPort?: number;
+}
+/** `dokebi verify --remote` (D-0184 §4). */
+export declare function remoteVerify(input: string, options?: RemoteVerifyOptions): Promise<RemoteVerifyResult>;
+export declare function remoteVerifyText(result: RemoteVerifyResult): string;

package/dist/remote-verify.js

@@ -0,0 +1,204 @@
+// `dokebi verify --remote <https-url>` (D-0184 §4): checks a deployed site from the outside —
+// its TLS certificate, the http to https redirect, the health routes and the security headers.
+// Nothing local runs; the result says which check failed and why.
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { connect } from 'node:tls';
+import { parseConfig } from '@dokebi/config';
+import { readSettings } from './config-show.js';
+import { debug, describeError } from './diagnostics.js';
+import { CliError } from './errors.js';
+/** Days left below which the certificate check warns (renewal should have happened). */
+const RENEW_DAYS = 14;
+/** HSTS max-age below this many seconds (180 days) is a warning. */
+const HSTS_MIN = 15_552_000;
+function fetchOnce(url, timeoutMs, ca) {
+    return new Promise((resolve, reject) => {
+        const send = url.protocol === 'https:' ? httpsRequest : httpRequest;
+        const request = send(url, {
+            method: 'GET',
+            headers: { 'user-agent': 'dokebi-verify-remote', accept: '*/*' },
+            timeout: timeoutMs,
+            ...(ca === undefined ? {} : { ca }),
+        }, (response) => {
+            // Only the status and headers matter; the body is read to the end and dropped.
+            response.resume();
+            response.once('end', () => resolve({ status: response.statusCode ?? 0, headers: response.headers }));
+            response.once('error', reject);
+        });
+        request.once('timeout', () => request.destroy(new Error(`no answer within ${timeoutMs} ms`)));
+        request.once('error', reject);
+        request.end();
+    });
+}
+function certificateOf(url, timeoutMs, ca) {
+    return new Promise((resolve, reject) => {
+        const socket = connect({
+            host: url.hostname,
+            port: Number(url.port || 443),
+            servername: url.hostname,
+            timeout: timeoutMs,
+            ...(ca === undefined ? {} : { ca }),
+        });
+        socket.once('secureConnect', () => {
+            const certificate = socket.getPeerCertificate();
+            socket.end();
+            if (!socket.authorized)
+                reject(new Error(String(socket.authorizationError)));
+            else
+                resolve(certificate);
+        });
+        socket.once('timeout', () => socket.destroy(new Error(`no TLS handshake within ${timeoutMs} ms`)));
+        socket.once('error', reject);
+    });
+}
+function header(answer, name) {
+    const value = answer.headers[name];
+    return Array.isArray(value) ? value.join(', ') : value;
+}
+/** The health routes of the project's settings when run in one, else the defaults. */
+async function healthRoutes(root) {
+    const defaults = { live: '/health/live', ready: '/health/ready' };
+    if (root === undefined)
+        return defaults;
+    try {
+        const { source } = await readSettings(root);
+        const routes = parseConfig(source).options['dokebi-web']?.healthRoutes;
+        return {
+            live: typeof routes?.live === 'string' ? routes.live : defaults.live,
+            ready: typeof routes?.ready === 'string' ? routes.ready : defaults.ready,
+        };
+    }
+    catch (error) {
+        // Outside a project (or settings that do not parse) the default routes are checked.
+        debug('verify --remote uses the default health routes', { error: describeError(error) });
+        return defaults;
+    }
+}
+/** `dokebi verify --remote` (D-0184 §4). */
+export async function remoteVerify(input, options = {}) {
+    let url;
+    try {
+        url = new URL(input);
+    }
+    catch (cause) {
+        throw new CliError('USAGE', `--remote ${input}: an https URL such as https://shop.example.com`, {
+            phase: 'arguments',
+            cause,
+        });
+    }
+    if (url.protocol !== 'https:' || url.username || url.password)
+        throw new CliError('USAGE', '--remote takes an https URL without credentials', {
+            phase: 'arguments',
+            details: { fix: 'npx dokebi verify --remote https://<domain> --json' },
+        });
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const routes = await healthRoutes(options.root);
+    const checks = [];
+    const timed = async (name, run) => {
+        const started = Date.now();
+        try {
+            checks.push({ name, ...(await run()), ms: Date.now() - started });
+        }
+        catch (error) {
+            checks.push({
+                name,
+                ok: false,
+                detail: describeError(error).split('\n')[0] ?? 'failed',
+                ms: Date.now() - started,
+            });
+        }
+    };
+    let certificate;
+    await timed('tls', async () => {
+        const peer = await certificateOf(url, timeoutMs, options.ca);
+        const daysLeft = Math.floor((Date.parse(peer.valid_to) - Date.now()) / 86_400_000);
+        certificate = {
+            subject: String(peer.subject?.CN ?? ''),
+            issuer: String(peer.issuer?.O ?? peer.issuer?.CN ?? ''),
+            validTo: new Date(peer.valid_to).toISOString(),
+            daysLeft,
+        };
+        return daysLeft < RENEW_DAYS
+            ? {
+                ok: false,
+                warning: true,
+                detail: `the certificate ends in ${daysLeft} days (renewal should have happened)`,
+            }
+            : { ok: true, detail: `valid for ${url.hostname}, ${daysLeft} days left` };
+    });
+    await timed('redirect', async () => {
+        const plain = new URL(url);
+        plain.protocol = 'http:';
+        plain.port = options.httpPort === undefined ? '' : String(options.httpPort);
+        const answer = await fetchOnce(plain, timeoutMs);
+        const location = header(answer, 'location') ?? '';
+        const ok = [301, 302, 307, 308].includes(answer.status) && location.startsWith('https://');
+        return ok
+            ? { ok, status: answer.status, detail: `http answers ${answer.status} to ${location}` }
+            : {
+                ok,
+                warning: true,
+                status: answer.status,
+                detail: `http answers ${answer.status} without a redirect to https`,
+            };
+    });
+    for (const [name, path] of [
+        ['live', routes.live],
+        ['ready', routes.ready],
+    ])
+        await timed(name, async () => {
+            const answer = await fetchOnce(new URL(path, url), timeoutMs, options.ca);
+            return {
+                ok: answer.status === 200,
+                status: answer.status,
+                detail: answer.status === 200 ? `${path} answers 200` : `${path} answers ${answer.status}`,
+            };
+        });
+    await timed('headers', async () => {
+        const answer = await fetchOnce(url, timeoutMs, options.ca);
+        const problems = [];
+        const notes = [];
+        const hsts = header(answer, 'strict-transport-security');
+        const age = Number(/max-age=(\d+)/i.exec(hsts ?? '')?.[1] ?? Number.NaN);
+        if (!hsts)
+            problems.push('no Strict-Transport-Security');
+        else if (!(age >= HSTS_MIN))
+            notes.push(`Strict-Transport-Security max-age ${age} is under 180 days`);
+        if (header(answer, 'x-content-type-options')?.toLowerCase() !== 'nosniff')
+            problems.push('no X-Content-Type-Options: nosniff');
+        // Framing and the referrer policy matter for pages (D-0149 sets them on HTML answers); an
+        // API answer at the URL needs HSTS and nosniff only.
+        const html = /text\/html/i.test(header(answer, 'content-type') ?? '');
+        const csp = header(answer, 'content-security-policy') ?? '';
+        if (html && !header(answer, 'x-frame-options') && !/frame-ancestors/i.test(csp))
+            problems.push('no X-Frame-Options or CSP frame-ancestors');
+        if (html && !header(answer, 'referrer-policy'))
+            notes.push('no Referrer-Policy');
+        if (header(answer, 'x-powered-by'))
+            problems.push('X-Powered-By names the server software');
+        return problems.length
+            ? { ok: false, status: answer.status, detail: [...problems, ...notes].join('; ') }
+            : notes.length
+                ? { ok: false, warning: true, status: answer.status, detail: notes.join('; ') }
+                : {
+                    ok: true,
+                    status: answer.status,
+                    detail: html
+                        ? 'HSTS, nosniff, framing and referrer policy set'
+                        : `HSTS and nosniff set (a ${header(answer, 'content-type')?.split(';')[0] ?? 'non-HTML'} answer: framing and referrer policy not checked)`,
+                };
+    });
+    const ok = checks.every((check) => check.ok || check.warning === true);
+    debug('Remote site checked', {
+        host: url.hostname,
+        ok,
+        failed: checks.filter((check) => !check.ok).map((check) => check.name),
+    });
+    return { ok, url: url.href, checks, ...(certificate ? { certificate } : {}) };
+}
+export function remoteVerifyText(result) {
+    return `${result.checks
+        .map((check) => `${check.ok ? 'ok' : check.warning ? 'WARN' : 'FAIL'} ${check.name} (${check.ms} ms): ${check.detail}`)
+        .join('\n')}\n${result.ok ? `verify --remote ok: ${result.url}` : `verify --remote FAILED: ${result.url}`}\n`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dokebi/cli",
-  "version": "0.4.26",
+  "version": "0.4.28",
   "description": "Project scaffolding, plugin catalog, recipes, install and verification CLI for Dokebi.",
   "keywords": [
     "dokebi",
@@ -34,8 +34,8 @@
   },
   "dependencies": {
     "semver": "7.8.5",
-    "@dokebi/core": "^0.4.2",
-    "@dokebi/config": "^0.4.2",
+    "@dokebi/core": "^0.4.3",
+    "@dokebi/config": "^0.4.3",
     "yaml": "2.9.1"
   },
   "devDependencies": {