@dokebi/cli 0.4.2 → 0.4.27

package/dist/check/project-rules.js

@@ -4,16 +4,22 @@
 //                     GUIDE_BLOCK_MODIFIED (the AGENTS.md installed list between its markers) and
 //                     MODIFIED_TEMPLATE (a plugin file declared `owner: 'cli'`, D-0065 §11).
 //                     Files scaffolded for the developer (`owner: 'user'`) are never reported.
-//   secret-in-config  a plugin check's SECRET_IN_CONFIG (doctor PLUGIN_CHECK) when dokebi.yaml
-//                     can reach version control (tracked, or not ignored by git)
+//   secret-in-config  a plugin check's SECRET_IN_CONFIG (doctor PLUGIN_CHECK), an option the
+//                     plugin schema marks secret (`writeOnly`, D-0073 addendum 2), or any value
+//                     that is a URL with a password (`scheme://user:password@host`, AI-M04 F9),
+//                     or the first admin password a recipe wrote (initialPassword of any
+//                     section: first-admin, the older blog-admin or a renamed one, D-0115),
+//                     when dokebi.yaml can reach version control (tracked, or not ignored by git)
 import { execFile } from 'node:child_process';
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { isMap, isScalar, parseDocument } from 'yaml';
-import { CONFIG_FILE, CONFIG_IGNORES } from '../configuration.js';
+import { isMap, isScalar, isSeq, parseDocument } from 'yaml';
+import { CONFIG_FILE, CONFIG_IGNORES, configTarget } from '../configuration.js';
 import { debug, describeError, isMissing } from '../diagnostics.js';
 import { CliError } from '../errors.js';
+import { adminSections } from '../first-admin.js';
 import { AGENTS_FILE, INSTALLED_START } from '../project-guide.js';
+import { ADMIN_PASSWORD_KEY } from '../recipe-login.js';
 /** git's answer for one path: 0/1 exit codes, or undefined when git or the repository is absent. */
 function git(root, args) {
     return new Promise((resolve) => {
@@ -30,14 +36,18 @@ function git(root, args) {
     });
 }
 /**
- * Whether dokebi.yaml can end up in version control: git tracks it, or git does not ignore it.
- * Without git (or outside a repository) the project's .gitignore must list it.
+ * Whether the settings file (dokebi.yaml, or the one DOKEBI_CONFIG names) can end up in version
+ * control: git tracks it, or git does not ignore it. Without git (or outside a repository) the
+ * project's .gitignore must list it. A file outside the project is not in its repository.
  */
-export async function configReachesGit(root) {
-    const tracked = await git(root, ['ls-files', '--error-unmatch', '--', CONFIG_FILE]);
+export async function configReachesGit(root, settings) {
+    if (settings && !settings.inside)
+        return false;
+    const file = settings?.file ?? CONFIG_FILE;
+    const tracked = await git(root, ['ls-files', '--error-unmatch', '--', file]);
     if (tracked === 0)
         return true;
-    const ignored = await git(root, ['check-ignore', '-q', '--', CONFIG_FILE]);
+    const ignored = await git(root, ['check-ignore', '-q', '--', file]);
     if (ignored !== undefined)
         return ignored !== 0;
     let text = '';
@@ -48,7 +58,7 @@ export async function configReachesGit(root) {
         if (!isMissing(error))
             throw new CliError('READ_FAILED', 'Cannot read .gitignore', { cause: error });
     }
-    const entry = CONFIG_IGNORES[0];
+    const entry = settings?.file ?? CONFIG_IGNORES[0];
     return !text
         .split(/\r?\n/)
         .map((line) => line.trim())
@@ -76,20 +86,204 @@ export function optionLine(source, path) {
             line++;
     return line;
 }
+/** A URL that carries a password: `scheme://user:password@host…` (a `<placeholder>` is none). */
+const PASSWORD_URL = /^[a-z][a-z0-9+.-]*:\/\/[^/\s:@]*:([^@/\s]+)@/i;
+/**
+ * Values of dokebi.yaml that are URLs with a password (AI-M04 F9): the option path and its line.
+ * Plugins read connection URLs from dokebi.yaml (it has no environment references), so the URL is
+ * fine there while the file stays out of git; only the path is returned, never the value.
+ */
+export function passwordUrls(source) {
+    const found = [];
+    const lineAt = (offset) => {
+        let line = 1;
+        for (let index = 0; index < offset; index++)
+            if (source.charCodeAt(index) === 10)
+                line++;
+        return line;
+    };
+    const walk = (node, path) => {
+        if (isMap(node))
+            for (const pair of node.items)
+                walk(pair.value, [...path, isScalar(pair.key) ? String(pair.key.value) : '?']);
+        else if (isSeq(node))
+            for (const [index, item] of node.items.entries())
+                walk(item, [...path, String(index)]);
+        else if (isScalar(node) && typeof node.value === 'string') {
+            const password = PASSWORD_URL.exec(node.value.trim())?.[1];
+            if (password && !password.startsWith('<'))
+                found.push({ path, line: lineAt(node.range?.[0] ?? 0) });
+        }
+    };
+    walk(parseDocument(source, { version: '1.2' }).contents, []);
+    return found;
+}
+/**
+ * Option paths (`[pluginId, …]`) whose schema marks the value secret (`writeOnly`, from
+ * `o.string({ secret: true })`) and that hold a value. A list of secrets is one path. Unions are
+ * followed branch by branch; only the paths are returned, never the values.
+ */
+export function schemaSecrets(options, plugins) {
+    const found = new Map();
+    // Every schema node that applies at one place (JSON Schema 2020-12, as config show reads them,
+    // R4CA-9): R4CB-11 followed properties, additionalProperties, items and anyOf/oneOf/allOf
+    // only, so a writeOnly mark under patternProperties, prefixItems, then/else or
+    // dependentSchemas of a hand-written schema was not found.
+    const walk = (value, schemas, path) => {
+        if (value === undefined || value === null)
+            return;
+        const nodes = expandSchemas(schemas);
+        if (nodes.some((node) => node.writeOnly === true)) {
+            found.set(path.join('.'), path);
+            return;
+        }
+        if (Array.isArray(value)) {
+            // A list of secrets (`items` writeOnly, no prefixItems) is one path.
+            const listed = nodes.flatMap((node) => (isSchema(node.items) ? [node.items] : []));
+            if (value.length &&
+                !nodes.some((node) => Array.isArray(node.prefixItems)) &&
+                expandSchemas(listed).some((node) => node.writeOnly === true)) {
+                found.set(path.join('.'), path);
+                return;
+            }
+            for (const [index, item] of value.entries())
+                walk(item, itemSchemas(nodes, index), [...path, String(index)]);
+            return;
+        }
+        if (typeof value !== 'object')
+            return;
+        for (const [key, child] of Object.entries(value))
+            walk(child, propertySchemas(nodes, key), [...path, key]);
+    };
+    const section = options && typeof options === 'object' ? options : {};
+    for (const { id, schema } of plugins)
+        if (Object.hasOwn(section, id))
+            walk(section[id], [schema], [id]);
+    return [...found.values()];
+}
+const isSchema = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+/** The nodes and their anyOf/oneOf/allOf, then/else and dependentSchemas forms (a mark hides). */
+function expandSchemas(schemas, depth = 0) {
+    const nodes = [];
+    for (const schema of schemas) {
+        if (!isSchema(schema))
+            continue;
+        nodes.push(schema);
+        if (depth >= 8)
+            continue;
+        const forms = [schema.then, schema.else];
+        for (const key of ['anyOf', 'oneOf', 'allOf'])
+            if (Array.isArray(schema[key]))
+                forms.push(...schema[key]);
+        if (isSchema(schema.dependentSchemas))
+            forms.push(...Object.values(schema.dependentSchemas));
+        nodes.push(...expandSchemas(forms, depth + 1));
+    }
+    return nodes;
+}
+/** `properties[key]` and the matching patternProperties; additionalProperties when none. */
+function propertySchemas(nodes, key) {
+    return nodes.flatMap((node) => {
+        const named = isSchema(node.properties) && Object.hasOwn(node.properties, key)
+            ? [node.properties[key]]
+            : [];
+        const patterns = isSchema(node.patternProperties)
+            ? Object.entries(node.patternProperties)
+                .filter(([pattern]) => {
+                try {
+                    return new RegExp(pattern, 'u').test(key);
+                }
+                catch (error) {
+                    // A pattern that does not compile is taken to apply (fail closed).
+                    debug('check: a patternProperties pattern does not compile', {
+                        error: describeError(error),
+                    });
+                    return true;
+                }
+            })
+                .map(([, schema]) => schema)
+            : [];
+        if (named.length || patterns.length)
+            return [...named, ...patterns];
+        return isSchema(node.additionalProperties) ? [node.additionalProperties] : [];
+    });
+}
+/** The schemas of item `index`: its prefixItems entry, else `items`. */
+function itemSchemas(nodes, index) {
+    return nodes.flatMap((node) => Array.isArray(node.prefixItems) && index < node.prefixItems.length
+        ? [node.prefixItems[index]]
+        : isSchema(node.items)
+            ? [node.items]
+            : []);
+}
+/** The `options` map of a dokebi.yaml source; undefined when the YAML does not parse. */
+function configOptions(source) {
+    const document = parseDocument(source, { version: '1.2' });
+    if (document.errors.length) {
+        debug('check: dokebi.yaml does not parse; schema secrets not looked for', {
+            errors: document.errors.length,
+        });
+        return undefined;
+    }
+    const data = document.toJS();
+    return data && typeof data === 'object' ? data.options : undefined;
+}
 function lineOf(text, needle) {
     const index = text.indexOf(needle);
     return index === -1 ? 0 : text.slice(0, index).split('\n').length;
 }
 export async function projectProblems(root, inspection) {
+    // M50: the settings file the app reads (DOKEBI_CONFIG, else dokebi.yaml).
+    const settings = await configTarget(root);
+    const configFile = settings.file;
     const problems = [];
     const codes = (code) => inspection.diagnostics.filter((item) => item.code === code);
+    // D-0155: a section of dokebi.yaml nothing declares (doctor UNDECLARED_SECTION, or
+    // UNKNOWN_PLUGIN for the section of a plugin that is not installed).
+    const sections = inspection.diagnostics.filter((item) => (item.code === 'UNDECLARED_SECTION' || item.code === 'UNKNOWN_PLUGIN') &&
+        item.path === configFile &&
+        item.plugin !== null);
+    if (sections.length) {
+        let text = '';
+        try {
+            text = await readFile(settings.path, 'utf8');
+        }
+        catch (error) {
+            if (!isMissing(error))
+                throw new CliError('READ_FAILED', `Cannot read ${configFile}`, { cause: error });
+        }
+        for (const item of sections)
+            problems.push({
+                rule: 'undeclared-section',
+                severity: 'warning',
+                file: configFile,
+                line: lineOf(text, `\n  ${item.plugin}:`) + (text.includes(`\n  ${item.plugin}:`) ? 1 : 0),
+                message: `options.${item.plugin} is read by nothing the framework knows (doctor ${item.code}): it is not checked at start, and config set, secret and the example do not know it`,
+                fix: item.hint ??
+                    `npx dokebi settings add ${item.plugin}, then read it with the settings declaration`,
+            });
+    }
+    // Studio v2 (10-31): a file copied from a template once lacks a later fix of the template, or an
+    // entry passes no configFile (doctor TEMPLATE_FIX_MISSING, RELOAD_NOT_WIRED): check names them
+    // too, so an app that runs check (verify) hears of them.
+    for (const item of [...codes('TEMPLATE_FIX_MISSING'), ...codes('RELOAD_NOT_WIRED')])
+        problems.push({
+            rule: 'template-fix-missing',
+            severity: 'warning',
+            file: item.path,
+            line: 0,
+            message: item.code === 'RELOAD_NOT_WIRED'
+                ? `${item.path} passes no configFile (doctor RELOAD_NOT_WIRED): the app cannot read dokebi.yaml again`
+                : `${item.path} was copied from a template that has fixes since: ${(item.details?.missing ?? []).join(', ')} (doctor TEMPLATE_FIX_MISSING)`,
+            fix: item.hint ?? 'compare the file with the template and bring the fixes over',
+        });
     for (const item of codes('MODIFIED_REGISTRATION'))
         problems.push({
             rule: 'generated-file',
             file: item.path,
             line: 1,
             message: `${item.path} is generated by the CLI and was edited (doctor MODIFIED_REGISTRATION); add, upgrade and remove refuse to run until it is restored`,
-            fix: 'undo the edit (for example git checkout -- src/dokebi.generated.ts); change plugins with npx dokebi add/remove/app/module and options in dokebi.yaml',
+            fix: 'undo the edit (for example git checkout -- src/dokebi.generated.ts) and keep code formatters out of the file (formatter-generated); change plugins with npx dokebi add/remove/app/module and options in dokebi.yaml',
         });
     for (const item of codes('MODIFIED_TEMPLATE'))
         problems.push({
@@ -118,23 +312,71 @@ export async function projectProblems(root, inspection) {
     }
     const secrets = inspection.diagnostics.filter((item) => item.code === 'PLUGIN_CHECK' &&
         item.details?.code === 'SECRET_IN_CONFIG');
-    if (secrets.length && (await configReachesGit(root))) {
-        let source = '';
-        try {
-            source = await readFile(join(root, CONFIG_FILE), 'utf8');
-        }
-        catch (error) {
-            if (!isMissing(error))
-                throw new CliError('READ_FAILED', `Cannot read ${CONFIG_FILE}`, { cause: error });
-        }
+    let source = '';
+    try {
+        source = await readFile(settings.path, 'utf8');
+    }
+    catch (error) {
+        if (!isMissing(error))
+            throw new CliError('READ_FAILED', `Cannot read ${configFile}`, { cause: error });
+    }
+    const urls = source ? passwordUrls(source) : [];
+    const options = source ? configOptions(source) : undefined;
+    const marked = source
+        ? schemaSecrets(options, inspection.plugins.map((item) => ({
+            id: (item.installed ?? item.expected).id,
+            schema: item.optionsSchema,
+        })))
+        : [];
+    // The first admin password of `recipe blog --admin login` (D-0076 §6): no plugin owns it.
+    // D-0115: whatever the section is called (first-admin, the older blog-admin, a renamed one).
+    // A plugin's own section is its schema's to judge (above).
+    const plugins = new Set(inspection.plugins.map((item) => (item.installed ?? item.expected).id));
+    const admins = new Set((options && typeof options === 'object' && !Array.isArray(options)
+        ? adminSections(options)
+        : []).filter((section) => !plugins.has(section)));
+    for (const section of admins)
+        marked.push([section, ADMIN_PASSWORD_KEY]);
+    // git is asked only when dokebi.yaml holds a secret.
+    if ((secrets.length || urls.length || marked.length) &&
+        (await configReachesGit(root, settings))) {
+        const keepOut = `keep ${configFile} out of git: list it in .gitignore (dokebi init does) and git rm --cached ${configFile}`;
+        const reported = new Set();
         for (const item of secrets) {
             const path = ['options', item.plugin ?? '', ...(item.details.optionPath ?? [])];
+            reported.add(path.join('.'));
+            problems.push({
+                rule: 'secret-in-config',
+                file: configFile,
+                line: optionLine(source, path),
+                message: `${path.slice(1).join('.')} holds a secret (doctor PLUGIN_CHECK SECRET_IN_CONFIG) and ${configFile} can reach version control (git tracks it or does not ignore it)`,
+                fix: `${item.hint ? `${item.hint}; or ` : ''}${keepOut}`,
+            });
+        }
+        for (const option of marked) {
+            const path = ['options', ...option];
+            if (reported.has(path.join('.')))
+                continue;
+            reported.add(path.join('.'));
+            debug('check: a secret option in dokebi.yaml', { path: option.join('.') });
             problems.push({
                 rule: 'secret-in-config',
-                file: CONFIG_FILE,
+                file: configFile,
                 line: optionLine(source, path),
-                message: `${path.slice(1).join('.')} holds a secret (doctor PLUGIN_CHECK SECRET_IN_CONFIG) and ${CONFIG_FILE} can reach version control (git tracks it or does not ignore it)`,
-                fix: `${item.hint ? `${item.hint}; or ` : ''}keep ${CONFIG_FILE} out of git: list it in .gitignore (dokebi init does) and git rm --cached ${CONFIG_FILE}`,
+                message: `${option.join('.')} holds a secret (${admins.has(option[0] ?? '') && option[1] === ADMIN_PASSWORD_KEY ? 'the first admin password of the recipe' : 'its plugin schema marks it secret'}) and ${configFile} can reach version control (git tracks it or does not ignore it)`,
+                fix: `${keepOut}; replace the secret if the file was already committed or pushed`,
+            });
+        }
+        for (const url of urls) {
+            if (reported.has(url.path.join('.')))
+                continue;
+            debug('check: a URL with a password in dokebi.yaml', { path: url.path.join('.') });
+            problems.push({
+                rule: 'secret-in-config',
+                file: configFile,
+                line: url.line,
+                message: `${url.path.slice(url.path[0] === 'options' ? 1 : 0).join('.')} is a URL with a password and ${configFile} can reach version control (git tracks it or does not ignore it)`,
+                fix: `${keepOut}; change that password if the file was already committed or pushed`,
             });
         }
     }

package/dist/check/seal-rules.d.ts

@@ -0,0 +1,6 @@
+import type { Problem } from './problems.js';
+export declare const SEAL_HEAD_FIX = "write <%- data.seal?.head ?? '' %> in the <head> of the layout of an app page; a page rendered outside an app route (an oauth consent page) takes context.getDependency(apps).seal(request).head (AppGroupApi of @dokebi/app ^0.4.5, empty on a plain host). A page that is no app page at all takes // dokebi-check: allow seal-head-copied <reason>";
+/** The seal head problems of one file's text (the path is project-relative, with `/`). */
+export declare function sealHeadProblems(path: string, text: string): Problem[];
+/** The seal head rule over the files under `src/` (only with @dokebi/app installed). */
+export declare function sealHeadsProblems(root: string, skip: (path: string) => boolean): Promise<Problem[]>;

package/dist/check/seal-rules.js

@@ -0,0 +1,68 @@
+// The seal head rule of `dokebi check` (a warning, R7 Codex T3 review; only with @dokebi/app):
+//   seal-head-copied  app code or a view under src/ that loads the seal forms module
+//                     `/dokebi/seal/forms.mjs` itself — a copied `<script type="module">` or
+//                     import map. @dokebi/app gives a page the head of its host: `data.seal.head`
+//                     in an app page, `AppGroupApi.seal(request).head` for a page rendered outside
+//                     an app route (an oauth consent page). A copy is written on a plain host too
+//                     and drifts from the files @dokebi/seal serves. R6 Claude T3 and R7 Codex T3
+//                     wrote it into their oauth extension, although the oauth AI.md shows `seal()`.
+// The rule reads the text of .ts/.js/.mjs/.ejs/.html files; a line comment (`//`, `*`) or an EJS
+// comment (`<%#`) that holds the path is not counted.
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { debug } from '../diagnostics.js';
+import { sources } from './form-rules.js';
+import { readMarkers } from './source-rules.js';
+const RULE = 'seal-head-copied';
+const FILES = /\.(?:ts|mts|js|mjs|ejs|html)$/;
+const FORMS = '/dokebi/seal/forms.mjs';
+/** Files larger than this are not read (generated bundles, data). */
+const MAX_BYTES = 1024 * 1024;
+export const SEAL_HEAD_FIX = "write <%- data.seal?.head ?? '' %> in the <head> of the layout of an app page; a page rendered outside an app route (an oauth consent page) takes context.getDependency(apps).seal(request).head (AppGroupApi of @dokebi/app ^0.4.5, empty on a plain host). A page that is no app page at all takes // dokebi-check: allow seal-head-copied <reason>";
+/** True when the text before `index` on its line opens a comment. */
+function inComment(line, column) {
+    const before = line.slice(0, column);
+    return /^\s*(?:\*|\/\*)/.test(line) || before.includes('//') || before.includes('<%#');
+}
+/** The seal head problems of one file's text (the path is project-relative, with `/`). */
+export function sealHeadProblems(path, text) {
+    if (!text.includes(FORMS))
+        return [];
+    const markers = readMarkers(text).filter((marker) => marker.rule === RULE);
+    const problems = [];
+    const lines = text.split('\n');
+    for (const [index, content] of lines.entries()) {
+        const column = content.indexOf(FORMS);
+        if (column === -1 || inComment(content, column))
+            continue;
+        const line = index + 1;
+        const marker = markers.find((item) => item.line === line || item.line === line - 1);
+        if (marker?.reason.replace(/\s*[-_%]*>\s*$/, '').trim())
+            continue;
+        problems.push({
+            rule: RULE,
+            severity: 'warning',
+            file: path,
+            line,
+            message: `${path} loads ${FORMS} itself: a copy of the seal head @dokebi/app gives every page of a seal host${marker ? ' (the dokebi-check marker has no reason, so it does not count)' : ''}`,
+            fix: SEAL_HEAD_FIX,
+        });
+    }
+    return problems;
+}
+/** The seal head rule over the files under `src/` (only with @dokebi/app installed). */
+export async function sealHeadsProblems(root, skip) {
+    const problems = [];
+    let files = 0;
+    for (const path of await sources(root, 'src', FILES)) {
+        if (skip(path))
+            continue;
+        const text = await readFile(join(root, path), 'utf8');
+        if (text.length > MAX_BYTES)
+            continue;
+        files++;
+        problems.push(...sealHeadProblems(path, text));
+    }
+    debug('check: seal heads', { files, problems: problems.length });
+    return problems;
+}

package/dist/check/security-rules.d.ts

@@ -0,0 +1,10 @@
+import { type Kinds, type TsNode, type TsSourceFile } from './typescript.js';
+export type SecurityRule = 'plain-password-compare' | 'csrf-exempt-unverified';
+export type Report = (node: TsNode, rule: SecurityRule, message: string, fix: string) => void;
+/** `passwordHash` → [password, hash]; `pass_phc` → [pass, phc]; `PW` → [pw]. */
+export declare function nameWords(name: string): string[];
+export declare function passwordLike(name: string): boolean;
+export declare function securityRules(file: TsSourceFile, kinds: Kinds, installed: {
+    readonly auth: boolean;
+    readonly csrf: boolean;
+}, report: Report): void;