@dokebi/template-inertia 0.4.2 → 0.4.5

package/dist/vite-files.js

@@ -0,0 +1,633 @@
+// D-0129: which files the Vite dev server of an Inertia app may serve. Vite's default
+// `server.fs.allow` is the workspace root, so before this the dev routes of `dokebi dev` answered
+// every file of the project: `GET /build/dokebi.yaml?raw` returned the whole configuration with
+// its secrets, `/build/src/main.ts?raw` the server code, and through a `devHosts` tunnel all of it
+// was public. The policy is enforced by the framework, not by each app's vite.config:
+//
+// - `config` hook: `server.fs.strict: true`, an allow list narrowed to what the browser needs (the
+//   views folders of the apps, the folders of the browser entries, node_modules, Vite's client,
+//   `allow` of the plugin options) and a deny list that always holds DEV_FILES_DENY. Vite merges
+//   the patch into the app's config: the app may add to allow and deny, never remove an entry.
+// - `configResolved`: strict turned off or deny entries removed by another plugin are put back,
+//   with a warning.
+// - a middleware before Vite's own, which judges every request again on its decoded, normalized
+//   path and on the real path of symlinks (the deny list, the allow list, the modules the served
+//   modules import), refuses Vite's open-in-editor endpoint to remote hosts, and answers a remote
+//   host (a `devHosts` tunnel) a short 403 without paths, also in place of Vite's own 403 page.
+//   On loopback the 403 keeps the details for the developer.
+//
+// `dokebiInertia()` carries this policy; the Vite host of `dokebi dev` adds `dokebiDevFiles()` for
+// a vite.config without it (older projects), so upgrading the package is enough.
+import { existsSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { realpath } from 'node:fs/promises';
+import { isIP } from 'node:net';
+import { dirname, isAbsolute, join, posix, relative, resolve, sep } from 'node:path';
+import { diagnostics } from '@dokebi/core/libraries';
+const { describeError } = diagnostics;
+/**
+ * Files the dev server never serves, whatever the app's config says (Vite globs: a pattern
+ * without `/` matches the name in every folder; letter case is ignored). Vite's own defaults are
+ * included, because a deny list replaces them.
+ */
+export const DEV_FILES_DENY = Object.freeze([
+    // Vite 8's defaults.
+    '.env',
+    '.env.*',
+    '*.{crt,pem,key,p12,pfx,cer,der}',
+    '.npmrc',
+    '.yarnrc.yml',
+    '**/.git/**',
+    // The framework's configuration (every secret of the app) and its state and backups.
+    'dokebi.yaml',
+    'dokebi.*.yaml',
+    'dokebi.yml',
+    'dokebi.*.yml',
+    'dokebi.json',
+    '**/.dokebi/**',
+    // Compose files with database passwords (dokebi init / `dokebi dev` infra).
+    'compose.yaml',
+    'compose.yml',
+    'compose.*.yaml',
+    'compose.*.yml',
+    'docker-compose*.yaml',
+    'docker-compose*.yml',
+    // Keys, credentials and local databases.
+    '*.{p8,jks,keystore,csr,kdbx}',
+    'id_{rsa,dsa,ecdsa,ed25519}*',
+    '**/.ssh/**',
+    '.yarnrc',
+    '.netrc',
+    '.pgpass',
+    '.htpasswd',
+    '*.{sqlite,sqlite3,db}',
+    '*.backup',
+]);
+/**
+ * Header the app process sets on every request it forwards to the Vite host: `loopback` or
+ * `remote`, from the browser's socket peer, the forwarding headers and the host name it judged
+ * (isRemoteRequest, §12). Any value the browser sent is replaced. Without it (Vite run on its
+ * own) the Vite host judges its own socket, the forwarding headers and the Host header.
+ */
+export const DEV_CLIENT_HEADER = 'x-dokebi-dev-client';
+/** The whole 403 a remote host gets: no path, no allow list. */
+export const FORBIDDEN_SHORT = '403 Forbidden\n';
+/** Whether a host name (no port, no brackets) is this machine: a remote one gets no details. */
+export function isLoopbackHost(name) {
+    const host = name.toLowerCase().replace(/\.$/, '');
+    if (host === 'localhost' || host.endsWith('.localhost'))
+        return true;
+    if (isIP(host) === 4)
+        return host.startsWith('127.');
+    if (isIP(host) === 6)
+        return host === '::1' || host === '0:0:0:0:0:0:0:1' || /^::ffff:127\./.test(host);
+    return false;
+}
+/** `Host` header → host name without port and brackets. */
+function hostName(header) {
+    const value = Array.isArray(header) ? (header[0] ?? '') : (header ?? '');
+    return value
+        .trim()
+        .replace(/^\[([^\]]*)\](?::\d+)?$/, '$1')
+        .replace(/:\d+$/, '');
+}
+/**
+ * Headers a proxy or tunnel adds (D-0129 §12). Any of them makes a request remote: a tunnel
+ * client runs on this machine (its socket is loopback) and may rewrite Host to localhost, so
+ * neither the socket nor the Host header alone tells a local browser from a forwarded one.
+ */
+export const FORWARDING_HEADERS = Object.freeze([
+    'forwarded',
+    'x-forwarded-for',
+    'x-forwarded-host',
+    'x-forwarded-proto',
+    'x-forwarded-port',
+    'x-forwarded-server',
+    'x-original-forwarded-for',
+    'x-real-ip',
+    'x-client-ip',
+    'x-cluster-client-ip',
+    'true-client-ip',
+    'cf-connecting-ip',
+    'cf-connecting-ipv6',
+    'cf-ray',
+    'cf-visitor',
+    'cdn-loop',
+    'fastly-client-ip',
+    'fly-client-ip',
+    'x-azure-clientip',
+    'x-appengine-user-ip',
+    'via',
+]);
+/** Whether a socket peer address is this machine (127.0.0.0/8, ::1, ::ffff:127.x). */
+export function isLoopbackAddress(address) {
+    return address !== undefined && isIP(address) !== 0 && isLoopbackHost(address);
+}
+/**
+ * Whether a request comes from another machine (a `devHosts` tunnel, a proxy, a LAN address).
+ * Local, and so shown details, only when the socket peer is loopback, no forwarding header is
+ * present, the Host is a loopback name and the app process (DEV_CLIENT_HEADER, when set) said
+ * loopback too. An unknown peer counts as remote.
+ */
+export function isRemoteRequest(headers, peer) {
+    const marker = headers[DEV_CLIENT_HEADER];
+    if (marker !== undefined && marker !== 'loopback')
+        return true;
+    if (FORWARDING_HEADERS.some((name) => headers[name] !== undefined))
+        return true;
+    if (!isLoopbackAddress(peer))
+        return true;
+    return !isLoopbackHost(hostName(headers.host));
+}
+/**
+ * A Vite deny glob as a regular expression on an absolute `/` path, matched like Vite matches it
+ * (picomatch with `dot` and `nocase`; a pattern without `/` matches in every folder). Supports
+ * `*`, `**`, `?` and `{a,b}`, which is all DEV_FILES_DENY and ordinary app entries use.
+ */
+export function denyPattern(glob) {
+    const pattern = glob.includes('/') ? glob : `**/${glob}`;
+    const literal = (text) => text
+        .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+        .replace(/\*/g, '[^/]*')
+        .replace(/\?/g, '[^/]');
+    let source = '';
+    let index = 0;
+    while (index < pattern.length) {
+        if (pattern.startsWith('**/', index)) {
+            source += '(?:.*/)?';
+            index += 3;
+        }
+        else if (pattern.startsWith('/**', index) && index + 3 === pattern.length) {
+            // A folder pattern (`**/.git/**`) matches the folder itself and everything in it.
+            source += '(?:/.*)?';
+            index += 3;
+        }
+        else if (pattern.startsWith('**', index)) {
+            source += '.*';
+            index += 2;
+        }
+        else if (pattern[index] === '{' && pattern.indexOf('}', index) !== -1) {
+            const close = pattern.indexOf('}', index);
+            source += `(?:${pattern
+                .slice(index + 1, close)
+                .split(',')
+                .map(literal)
+                .join('|')})`;
+            index = close + 1;
+        }
+        else {
+            source += literal(pattern[index]);
+            index += 1;
+        }
+    }
+    return new RegExp(`^${source}$`, 'i');
+}
+/** Folders under the Vite root that hold server code: never allowed as a whole for an entry. */
+const SERVER_FOLDERS = /^(?:|src|src\/apps|src\/apps\/[^/]+|src\/shared|src\/infra|tests?|scripts|tools)$/;
+/** An app's views folder in the framework layout (D-0031): `src/apps/<app>/views/…`. */
+const VIEWS = /^src\/apps\/[^/]+\/views(?:\/|$)/;
+/** Vite's own and plugin URLs that name no file: passed to Vite as they are. */
+const VIRTUAL = ['/@vite/', '/@id/__x00__', '/@dokebi-served/', '/@react-refresh'];
+/** Vite's open-in-editor endpoint (launch-editor), which answers this machine only. */
+const isEditor = (path) => path === '/__open-in-editor' || path.startsWith('/__open-in-editor/');
+const slash = (path) => (sep === '/' ? path : path.split(sep).join('/'));
+const within = (dir, path) => path === dir || path.startsWith(dir.endsWith('/') ? dir : `${dir}/`);
+/** The project-relative path of `path` with `/`, or undefined when it is outside `root`. */
+function inside(root, path) {
+    const rel = slash(relative(root, path));
+    return rel === '..' || rel.startsWith('../') || isAbsolute(rel) ? undefined : rel;
+}
+/** Whether `plugins` (Vite's raw, possibly nested list) holds a plugin named `name`. */
+function hasPlugin(plugins, name) {
+    if (Array.isArray(plugins))
+        return plugins.some((item) => hasPlugin(item, name));
+    return (typeof plugins === 'object' && plugins !== null && plugins.name === name);
+}
+/** The entry files of the browser build: `build.rolldownOptions.input` (or rollup's), literal `optimizeDeps.entries`. */
+function entryFiles(config, root) {
+    const values = (input) => typeof input === 'string'
+        ? [input]
+        : Array.isArray(input)
+            ? input
+            : input && typeof input === 'object'
+                ? Object.values(input)
+                : [];
+    const files = [
+        ...values(config.build?.rolldownOptions?.input ?? config.build?.rollupOptions?.input),
+        ...values(config.optimizeDeps?.entries).filter((entry) => typeof entry === 'string' && !/[*?{}[\]!]/.test(entry)),
+    ];
+    return files
+        .filter((file) => typeof file === 'string' && file.length > 0)
+        .map((file) => slash(resolve(root, file)));
+}
+/** The views folders of the apps under `root` (the framework layout), as absolute paths. */
+function viewFolders(root) {
+    const apps = join(root, 'src', 'apps');
+    if (!existsSync(apps))
+        return [];
+    return readdirSync(apps, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && existsSync(join(apps, entry.name, 'views')))
+        .map((entry) => slash(join(apps, entry.name, 'views')))
+        .sort();
+}
+/** Every node_modules from `root` up (hoisted workspace installs), as absolute paths. */
+function moduleFolders(root) {
+    const found = [];
+    for (let dir = root;; dir = dirname(dir)) {
+        const candidate = join(dir, 'node_modules');
+        if (existsSync(candidate))
+            found.push(slash(candidate));
+        if (dirname(dir) === dir)
+            return found;
+    }
+}
+function realOr(path) {
+    try {
+        return slash(realpathSync(path));
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR')
+            return path;
+        throw error;
+    }
+}
+/**
+ * The dev file policy of one Vite config (one plugin instance). `owner` `dev-host` is the copy the
+ * Vite host of `dokebi dev` adds: it stays inactive when the app's config has `dokebiInertia()`.
+ */
+export class DevFilesPolicy {
+    #logger;
+    #options;
+    #owner;
+    #active = false;
+    #root = '';
+    #realRoot = '';
+    #base = '/';
+    #fs;
+    #deny = [];
+    #safe;
+    #allowSeen = -1;
+    #allowReal = [];
+    constructor(logger, options, owner) {
+        this.#logger = logger;
+        this.#options = options;
+        this.#owner = owner;
+    }
+    /** The deny entries this policy always keeps (DEV_FILES_DENY and the plugin's `deny`). */
+    get required() {
+        return [...new Set([...DEV_FILES_DENY, ...(this.#options.deny ?? [])])];
+    }
+    /** The `config` hook (dev server only): the policy as a patch, and warnings for a weaker config. */
+    config(raw, command) {
+        this.#active = false;
+        if (command !== 'serve')
+            return null;
+        const config = (raw ?? {});
+        if (this.#owner === 'dev-host' && hasPlugin(config.plugins, 'dokebi-inertia')) {
+            this.#logger.log('debug', 'Inertia dev file policy comes from dokebiInertia() of the config');
+            return null;
+        }
+        this.#active = true;
+        const root = slash(resolve(typeof config.root === 'string' ? config.root : process.cwd()));
+        const fs = config.server?.fs;
+        if (fs?.strict === false)
+            this.#logger.log('warn', 'server.fs.strict: false is ignored: the Inertia dev server keeps strict (D-0129)', { code: 'INERTIA_DEV_FILES_STRICT' });
+        if (Array.isArray(fs?.deny)) {
+            const own = new Set(fs.deny);
+            const kept = this.required.filter((entry) => !own.has(entry));
+            if (kept.length)
+                this.#logger.log('warn', "server.fs.deny of the Vite config does not replace the framework's deny list: its entries are added and the framework's stay (D-0129)", { code: 'INERTIA_DEV_FILES_DENY', kept });
+        }
+        if (Array.isArray(fs?.allow))
+            for (const entry of fs.allow) {
+                if (typeof entry !== 'string')
+                    continue;
+                const path = slash(resolve(root, entry));
+                const rel = inside(root, path);
+                if (within(path, root) || (rel !== undefined && SERVER_FOLDERS.test(rel)))
+                    this.#logger.log('warn', 'server.fs.allow of the Vite config lets the dev server serve server code; allow only the folders the browser loads (D-0129)', { code: 'INERTIA_DEV_FILES_ALLOW', allow: entry });
+            }
+        const views = viewFolders(root);
+        const entries = entryFiles(config, root);
+        const allow = new Set(views);
+        for (const file of entries) {
+            const folder = slash(dirname(file));
+            const rel = inside(root, folder);
+            // An entry beside server code (the root, src/, an app folder) allows only itself; the
+            // modules it imports are served because it imports them.
+            if (within(folder, root) || (rel !== undefined && SERVER_FOLDERS.test(rel)))
+                allow.add(file);
+            else if (!views.some((view) => within(view, folder)))
+                allow.add(folder);
+        }
+        if (views.length === 0 && entries.length === 0) {
+            // No browser folder to narrow to (not the framework layout, no build input): the root,
+            // minus the deny list.
+            this.#logger.log('warn', 'No views folder and no build input found: the Inertia dev server serves the Vite root, minus the deny list (D-0129). Set build.rollupOptions.input or dokebiInertia({ allow })', { code: 'INERTIA_DEV_FILES_ROOT', root });
+            allow.add(root);
+        }
+        for (const folder of moduleFolders(root))
+            allow.add(folder);
+        for (const extra of this.#options.allow ?? [])
+            allow.add(slash(resolve(root, extra)));
+        const patch = {
+            server: { fs: { strict: true, allow: [...allow], deny: this.required } },
+        };
+        this.#logger.log('debug', 'Inertia dev file policy prepared', {
+            owner: this.#owner,
+            root,
+            allow: patch.server.fs.allow,
+            deny: patch.server.fs.deny.length,
+        });
+        return patch;
+    }
+    /** The `configResolved` hook: repairs what a later plugin loosened and keeps the live config. */
+    configResolved(config) {
+        if (config.command !== 'serve')
+            this.#active = false;
+        if (this.#active &&
+            this.#owner === 'dev-host' &&
+            config.plugins?.some((plugin) => plugin.name === 'dokebi-inertia'))
+            this.#active = false;
+        const fs = config.server?.fs;
+        if (!this.#active || !fs) {
+            this.#active = false;
+            return;
+        }
+        this.#root = slash(config.root ?? process.cwd());
+        this.#realRoot = realOr(this.#root);
+        this.#base = config.base || '/';
+        this.#fs = fs;
+        this.#deny = [];
+        this.#safe = config.safeModulePaths instanceof Set ? config.safeModulePaths : undefined;
+        this.#repair();
+        if (config.cacheDir && !fs.allow.some((dir) => within(dir, slash(config.cacheDir ?? ''))))
+            fs.allow.push(slash(config.cacheDir));
+        this.#allowSeen = -1;
+        this.#logger.log('debug', 'Inertia dev file policy active', {
+            owner: this.#owner,
+            root: this.#root,
+            base: this.#base,
+            allow: fs.allow,
+            deny: fs.deny.length,
+            importGraph: this.#safe !== undefined,
+        });
+    }
+    /**
+     * Puts back strict and the required deny entries when a plugin loosened them (its
+     * `configResolved` runs after this one's, so this runs again when the server is configured and
+     * when a request finds strict off), with a warning; compiles the deny list the middleware uses.
+     */
+    #repair() {
+        const fs = this.#fs;
+        if (!fs)
+            return;
+        if (fs.strict !== true) {
+            this.#logger.log('warn', 'server.fs.strict was turned off after the Inertia dev file policy; it is on again (D-0129)', { code: 'INERTIA_DEV_FILES_STRICT', restored: true });
+            fs.strict = true;
+        }
+        const present = new Set(fs.deny);
+        const restored = this.required.filter((entry) => !present.has(entry));
+        if (restored.length) {
+            this.#logger.log('warn', 'Deny entries of the Inertia dev file policy were removed from server.fs.deny; they are kept (D-0129)', { code: 'INERTIA_DEV_FILES_DENY', restored });
+            fs.deny.push(...restored);
+        }
+        if (restored.length || this.#deny.length !== fs.deny.length)
+            this.#deny = fs.deny.map((glob) => ({ glob, pattern: denyPattern(glob) }));
+    }
+    /** The middleware to add before Vite's own (undefined when this copy is inactive). */
+    middleware() {
+        if (!this.#active)
+            return undefined;
+        this.#repair();
+        return (request, response, next) => {
+            const fs = this.#fs;
+            if (fs && (fs.strict !== true || fs.deny.length !== this.#deny.length))
+                this.#repair();
+            const headers = request.headers ?? {};
+            const remote = isRemoteRequest(headers, request.socket?.remoteAddress);
+            if (remote)
+                quietForbidden(response);
+            const url = String(request.url ?? '/');
+            // Every method is judged: Vite's file middlewares (sirv: the root, `/@fs/`, public) answer
+            // any method, so a POST to a symlink in a views folder returned its target (Vite checks the
+            // link's own path only, audit R5). Only Vite's ping (Accept: text/x-vite-ping), which Vite
+            // answers 204 for every path and method before any file, skips the judgement; its
+            // open-in-editor middleware runs before the ping answer, so the editor rule holds for it too.
+            if (headers.accept === 'text/x-vite-ping') {
+                const path = remote ? this.#normalize(url) : undefined;
+                if (typeof path === 'string' && isEditor(path))
+                    this.#refuse(response, { reason: 'editor', path }, remote);
+                else
+                    next();
+                return;
+            }
+            this.#judge(url, remote).then((refusal) => {
+                if (refusal === undefined)
+                    next();
+                else
+                    this.#refuse(response, refusal, remote);
+            }, (error) => {
+                // Fail closed: a check that cannot decide serves nothing.
+                this.#logger.log('error', 'Inertia dev file check failed', {
+                    code: 'INERTIA_DEV_FILES_FAILED',
+                    path: url.slice(0, 200),
+                    error: describeError(error),
+                });
+                this.#refuse(response, { reason: 'failed', path: url }, remote);
+            });
+        };
+    }
+    /**
+     * The path of a request URL as any later reader could make of it: the base removed, decoded
+     * until it no longer changes (`%252e` too), separators and dot segments normalized; a refusal
+     * when it does not decode to a path.
+     */
+    #normalize(url) {
+        let path = url.split('?', 1)[0]?.split('#', 1)[0] ?? '/';
+        if (this.#base !== '/' && path.startsWith(this.#base))
+            path = path.slice(this.#base.length - 1);
+        // Decoded until it no longer changes (`%252e` too), separators and dot segments normalized:
+        // the policy judges what any later reader could make of the URL.
+        let decoded = path;
+        for (let round = 0; round < 4; round++) {
+            let next;
+            try {
+                next = decodeURIComponent(decoded);
+            }
+            catch (error) {
+                if (!(error instanceof URIError))
+                    throw error;
+                return { reason: 'malformed', path };
+            }
+            if (next === decoded)
+                break;
+            decoded = next;
+        }
+        if (decoded.includes('\0'))
+            return { reason: 'malformed', path };
+        let normalized = posix.normalize(decoded.replaceAll('\\', '/'));
+        if (!normalized.startsWith('/'))
+            normalized = `/${normalized}`;
+        return normalized;
+    }
+    async #judge(url, remote) {
+        const normalized = this.#normalize(url);
+        if (typeof normalized !== 'string')
+            return normalized;
+        if (isEditor(normalized))
+            return remote ? { reason: 'editor', path: normalized } : undefined;
+        if (VIRTUAL.some((prefix) => normalized.startsWith(prefix)))
+            return undefined;
+        if (normalized.startsWith('/@fs/'))
+            return this.#file(normalized.slice(4), normalized);
+        if (normalized.startsWith('/@id/')) {
+            const id = normalized.slice(5);
+            const rule = this.#denied(id);
+            if (rule)
+                return { reason: 'denied', path: normalized, rule };
+            return id.startsWith('/') ? this.#file(join(this.#root, id), normalized) : undefined;
+        }
+        if (normalized.startsWith('/@')) {
+            // A plugin's virtual URL, unless it names a file under the root.
+            const rule = this.#denied(normalized);
+            if (rule)
+                return { reason: 'denied', path: normalized, rule };
+            const file = join(this.#root, normalized);
+            return existsSync(file) ? this.#file(file, normalized) : undefined;
+        }
+        return this.#file(join(this.#root, normalized), normalized);
+    }
+    /** A file path (lexical, absolute): the deny list on it and on its real path, then allow. */
+    async #file(lexical, shown) {
+        const file = slash(lexical);
+        const lexicalRule = this.#denied(file);
+        if (lexicalRule)
+            return { reason: 'denied', path: shown, rule: lexicalRule };
+        let real;
+        try {
+            real = slash(await realpath(file));
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === 'ENOENT' || code === 'ENOTDIR')
+                real = null;
+            else {
+                if (this.#logger.isEnabled('debug'))
+                    this.#logger.log('debug', 'Inertia dev file check cannot read a path', {
+                        path: shown.slice(0, 200),
+                        error: describeError(error),
+                    });
+                return { reason: 'unreadable', path: shown };
+            }
+        }
+        // Missing: Vite answers 404, or resolves it (an extension) and checks the allow list itself.
+        if (real === null)
+            return undefined;
+        const realRule = this.#denied(real);
+        if (realRule)
+            return { reason: 'denied', path: shown, rule: realRule };
+        // The real path decides: a link inside a views folder to server code is server code.
+        return this.#allowed(real) ? undefined : { reason: 'outside', path: shown };
+    }
+    #denied(path) {
+        const subject = path.startsWith('/') ? path : `/${path}`;
+        return this.#deny.find(({ pattern }) => pattern.test(subject))?.glob;
+    }
+    #allowed(path) {
+        const safe = this.#safe;
+        if (safe && (safe.has(path) || (path.endsWith('.map') && safe.has(path.slice(0, -4)))))
+            return true;
+        const allow = this.#fs?.allow ?? [];
+        if (this.#allowSeen !== allow.length) {
+            this.#allowReal = allow.map(realOr);
+            this.#allowSeen = allow.length;
+        }
+        if (allow.some((dir) => within(dir, path)) || this.#allowReal.some((dir) => within(dir, path)))
+            return true;
+        // An app added while the dev server runs: its views folder is allowed like the others.
+        for (const root of new Set([this.#root, this.#realRoot])) {
+            const rel = inside(root, path);
+            const match = rel === undefined ? null : VIEWS.exec(rel);
+            if (!match)
+                continue;
+            const folder = slash(join(root, match[0].replace(/\/$/, '')));
+            if (existsSync(folder) && statSync(folder).isDirectory()) {
+                allow.push(folder);
+                this.#logger.log('debug', 'Inertia dev file policy allows a new views folder', {
+                    folder,
+                });
+                return true;
+            }
+        }
+        return false;
+    }
+    #refuse(response, refusal, remote) {
+        if (this.#logger.isEnabled('debug'))
+            this.#logger.log('debug', 'Inertia dev server refused a file', {
+                path: refusal.path.slice(0, 200),
+                reason: refusal.reason,
+                rule: refusal.rule,
+                remote,
+            });
+        if (response.headersSent) {
+            response.end();
+            return;
+        }
+        response.statusCode = 403;
+        response.setHeader('content-type', 'text/plain; charset=utf-8');
+        response.setHeader('cache-control', 'no-store');
+        if (remote) {
+            response.end(FORBIDDEN_SHORT);
+            return;
+        }
+        const why = {
+            denied: `it matches ${refusal.rule ?? 'an entry'} of server.fs.deny`,
+            outside: 'it is outside the folders the browser loads (server.fs.allow)',
+            malformed: 'the URL does not decode to a path',
+            editor: 'open-in-editor answers this machine only',
+            unreadable: 'its path cannot be read',
+            failed: 'the file check failed (see the dokebi dev output)',
+        }[refusal.reason];
+        response.end(`403 Restricted (D-0129): ${refusal.path} is not served by the Vite dev server: ${why}.\n` +
+            `Served folders (server.fs.allow):\n${(this.#fs?.allow ?? []).map((dir) => `- ${dir}`).join('\n')}\n` +
+            'Add a folder the browser loads with dokebiInertia({ allow: [...] }) in vite.config.ts; files that hold secrets or server code stay out.\n');
+    }
+}
+/**
+ * For a remote request: any 403 (Vite's own page names the absolute path and the allow list)
+ * goes out as FORBIDDEN_SHORT instead.
+ */
+function quietForbidden(response) {
+    const write = response.write?.bind(response);
+    const end = response.end.bind(response);
+    const forbidden = () => response.statusCode === 403 && response.headersSent !== true;
+    if (write)
+        response.write = (chunk, ...rest) => forbidden() ? true : write(chunk, ...rest);
+    response.end = (...args) => {
+        if (!forbidden())
+            return end(...args);
+        response.setHeader('content-type', 'text/plain; charset=utf-8');
+        response.removeHeader?.('content-length');
+        return end(FORBIDDEN_SHORT);
+    };
+}
+/**
+ * The dev file policy as a plugin of its own, for a vite.config without `dokebiInertia()` (which
+ * carries the same policy): the Vite host of `dokebi dev` adds it; it stays inactive next to
+ * `dokebiInertia()`.
+ */
+export function dokebiDevFiles(logger, options = {}) {
+    const policy = new DevFilesPolicy(logger, options, 'dev-host');
+    return {
+        name: 'dokebi-inertia:dev-files',
+        enforce: 'pre',
+        config: (config, env) => policy.config(config, env.command),
+        configResolved: (config) => policy.configResolved(config),
+        configureServer(server) {
+            const guard = policy.middleware();
+            if (guard)
+                server.middlewares.use(guard);
+        },
+    };
+}