@cosmicdrift/kumiko-guards 0.340.0 → 0.342.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-guards",
-  "version": "0.340.0",
+  "version": "0.342.0",
   "description": "AST-based security guards for Kumiko repos: direct-fs/fetch, tenant escalation, admin-API, escape hatches and related checks, run over a shared ts-morph project.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -28,7 +28,7 @@
     "kumiko-pre-push": "./src/pre-push.sh"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-repo-manifest": "0.340.0",
+    "@cosmicdrift/kumiko-repo-manifest": "0.342.0",
     "ts-morph": "^28.0.0"
   },
   "publishConfig": {

package/src/_lib/guard-kit.ts

@@ -56,7 +56,7 @@ export type AstGuard = {
   /** `roots` are the same roots `runGuards` scanned `files` with — a guard classifying paths against repo roots (`relFromRepoRoot`) must use these, not re-derive its own single-repo `resolveRepoRoots()`, or a multi-root caller's roots never reach it. */
   run(files: readonly SourceFile[], roots?: readonly RepoRoot[]): GuardOutcome;
   /** Ratchet guards only: freeze the current findings into that guard's own baseline file. */
-  writeBaseline?(files: readonly SourceFile[]): void;
+  writeBaseline?(files: readonly SourceFile[], roots?: readonly RepoRoot[]): void;
 };
 
 export function isSecurityGuard(guard: Pick<AstGuard, "security">): boolean {
@@ -195,6 +195,8 @@ export function baselineRatchet(args: {
   readonly file: string;
   readonly formatVersion: number;
   readonly unit: string;
+  /** A missing baseline file counts as an empty baseline (every current entry is a regression) instead of a warning. For guards whose suppression must not hold without a frozen file. */
+  readonly failClosed?: boolean;
 }): {
   write(current: Readonly<Record<string, number>>): void;
   check(
@@ -229,6 +231,13 @@ export function baselineRatchet(args: {
       readonly resolveLine?: (file: string) => number;
     },
   ): GuardViolation[] => {
+    if (!existsSync(args.file) && args.failClosed === true) {
+      return compareToBaseline(current, {}).regressions.map((regression) => ({
+        file: regression.file,
+        line: opts?.resolveLine?.(regression.file) ?? 1,
+        message: `${args.unit} without a baseline file (${args.file}): ${regression.current} not frozen. ${remediation}`,
+      }));
+    }
     if (!existsSync(args.file)) {
       console.log(
         `  No baseline found (${args.file}). Freeze it first with \`--write-baseline\` — warning until then, no fail.`,

package/src/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.341.0",
+    "type": "breaking",
+    "title": "Repo-local direct-fs exceptions with a frozen reason, bundled read-only assets",
+    "detail": "`guard-no-direct-fs` has a repo-local exception: `// kumiko-lint-ignore direct-fs <reason>` on the `node:fs` import (or the line above) suppresses the finding only while the `<file>::<reason>` pair is frozen in `.kumiko-direct-fs-baseline.json` at the repo root. It fails closed: without a baseline file, with an unreadable file, with a changed reason, or with more markers than frozen, the finding stays. A bare tag without a reason does not count. Freeze with `kumiko-guards guards --write-baseline --guard=\"No-Direct-Fs Guard\"`. The guard hint now points to the marker, `FileStorageProvider` and `readBundledAsset`. `AstGuard.writeBaseline` receives the scanned roots as an optional second argument, and `baselineRatchet` takes an opt-in `failClosed` that treats a missing baseline file as empty.\n**Migration (breaking-ish):** the framework allowlist no longer contains `src/marketing/render-landing.ts` and `src/marketing/rebuild-pages-job.ts` for every repo. Apps that have these files (today money-horse, phronexsis, show-pony, publicstatus) put `// kumiko-lint-ignore direct-fs <reason>` above the `node:fs` import in each file and run `kumiko-guards guards --write-baseline --guard=\"No-Direct-Fs Guard\"` once in the app repo. Commit the generated `.kumiko-direct-fs-baseline.json`.\n`@cosmicdrift/kumiko-server-runtime` can ship read-only files from an app's own build. Declare them in `package.json` under `kumiko.assets` (`[{ \"name\": \"inter-bold.ttf\", \"source\": \"packages/site-kit/fonts/inter-bold.ttf\" }]`, `source` relative to the app's `package.json`). `buildProdBundle` copies them to `dist/kumiko-bundled-assets/`, which the static file server does not serve, and fails the build on an invalid name, a duplicate, a source outside the package or a missing file. `readBundledAsset(name)` and `resolveBundledAsset(name)` read the dist copy in prod and the declared source in dev, so apps need no `node:fs` for it.",
+    "migration": "The allowlist no longer frees src/marketing/render-landing.ts and src/marketing/rebuild-pages-job.ts in every repo. Put // kumiko-lint-ignore direct-fs <reason> above the node:fs import in each such file, run kumiko-guards guards --write-baseline --guard=\"No-Direct-Fs Guard\" once and commit .kumiko-direct-fs-baseline.json."
+  },
   {
     "version": "0.340.0",
     "type": "improvement",

package/src/guard-no-direct-fs.ts

@@ -19,17 +19,29 @@
  * one repo cannot silently free node:fs in another under the same relative
  * path.
  *
+ * Repo-local exception for a justified import (tooling, build-time reads):
+ *   // kumiko-lint-ignore direct-fs <reason>
+ * on the import line or the line directly above. A bare tag without a reason
+ * does not count. The marker suppresses only while its `<file>::<reason>` pair
+ * is frozen in `.kumiko-direct-fs-baseline.json` at the repo root — fail-closed:
+ * no file, an unreadable file, a changed reason or more markers than frozen
+ * all make the guard fail. Freeze with:
+ *   kumiko-guards guards --write-baseline --guard="No-Direct-Fs Guard"
+ *
  * Usage:
  *   bun guards/guard-no-direct-fs.ts
  *
  * Exit 1 on violations in non-allowlisted files, 0 when clean.
  */
 
-import { relative as pathRelative } from "node:path";
+import { existsSync } from "node:fs";
+import { join, relative as pathRelative } from "node:path";
 import { Node, type SourceFile, SyntaxKind } from "ts-morph";
 import {
   type AstGuard,
+  baselineRatchet,
   findRepoRootFor,
+  type GuardViolation,
   relFromRepoRoot,
   runStandalone,
   type ScanSpec,
@@ -86,8 +98,10 @@ const ALLOWLIST: readonly AllowEntry[] = [
   },
 
   // server-runtime: prod bundle build + static asset delivery from the
-  // build output (no user-controlled path).
+  // build output (no user-controlled path). bundled-assets.ts reads declared
+  // read-only assets, name-pattern + containment checked.
   { repo: "kumiko-framework", pattern: /^packages\/server-runtime\/src\/build-prod-bundle\.ts$/ },
+  { repo: "kumiko-framework", pattern: /^packages\/server-runtime\/src\/bundled-assets\.ts$/ },
   {
     repo: "kumiko-framework",
     pattern: /^packages\/server-runtime\/src\/run-prod-app-static-files\.ts$/,
@@ -110,12 +124,6 @@ const ALLOWLIST: readonly AllowEntry[] = [
   // walk from cwd, no user input as a path.
   { repo: "kumiko-enterprise", pattern: /^packages\/ai-foundation\/src\/prompt\/corpus\.ts$/ },
 
-  // App repos: marketing landing-page renderer, iterates over a fixed
-  // language enum (LANGS/SUPPORTED_LANGS) — no user input in the path.
-  // repo:"*" — same relative path is intentional across flat-layout apps.
-  { repo: "*", pattern: /(^|\/)src\/marketing\/render-landing\.ts$/ },
-  { repo: "*", pattern: /(^|\/)src\/marketing\/rebuild-pages-job\.ts$/ },
-
   // kumiko-enterprise publish pipeline: materialize.ts is the guarded
   // place (writeMaterializedTree — resolve()+startsWith(root+sep) check,
   // same pattern as local-provider.ts). build.ts/feature.ts/validate.ts
@@ -153,6 +161,100 @@ interface Violation {
   moduleSpecifier: string;
 }
 
+const BASELINE_FILE = ".kumiko-direct-fs-baseline.json";
+// Must sit in a // comment, so a string literal describing the marker does not suppress.
+const MARKER_WITH_REASON_RE = /(^|\s)\/\/\s*kumiko-lint-ignore direct-fs\s+(\S.*)$/;
+
+const MARKER_REMEDIATION =
+  "New, reworded or unfrozen direct-fs marker. Prefer FileStorageProvider or readBundledAsset; " +
+  'otherwise freeze the exception with `kumiko-guards guards --write-baseline --guard="No-Direct-Fs Guard"` ' +
+  "so the baseline diff shows up in review.";
+
+type RootMarkers = {
+  readonly root: RepoRoot;
+  /** `<file>::<reason>` -> distinct marker lines (1-based). */
+  readonly linesByKey: Map<string, Set<number>>;
+};
+
+function ratchetFor(root: RepoRoot) {
+  return baselineRatchet({
+    file: join(root.absPath, BASELINE_FILE),
+    formatVersion: 1,
+    unit: "direct-fs marker(s)",
+    failClosed: true,
+  });
+}
+
+function markerFor(
+  lines: readonly string[],
+  importLine: number,
+): { readonly reason: string; readonly line: number } | undefined {
+  const sameLine = MARKER_WITH_REASON_RE.exec(lines[importLine - 1] ?? "")?.[2];
+  if (sameLine !== undefined) return { reason: sameLine.trim(), line: importLine };
+  const above = MARKER_WITH_REASON_RE.exec(lines[importLine - 2] ?? "")?.[2];
+  return above === undefined ? undefined : { reason: above.trim(), line: importLine - 1 };
+}
+
+function countsOf(markers: RootMarkers): Record<string, number> {
+  return Object.fromEntries([...markers.linesByKey].map(([key, lines]) => [key, lines.size]));
+}
+
+function collect(
+  files: readonly SourceFile[],
+  roots: readonly RepoRoot[],
+): { readonly unsuppressed: GuardViolation[]; readonly markers: Map<string, RootMarkers> } {
+  const unsuppressed: GuardViolation[] = [];
+  const markers = new Map<string, RootMarkers>();
+
+  for (const sf of files) {
+    const file = sf.getFilePath();
+    const rel = relFromRepoRoot(file, roots);
+    if (EXCLUDE.test(rel)) continue;
+    const root = findRepoRootFor(file, roots);
+    if (isRepoAllowlisted(root?.name, rel)) continue;
+    const lines = sf.getFullText().split("\n");
+    for (const v of findDirectFsImports(sf)) {
+      const marker = root === undefined ? undefined : markerFor(lines, v.line);
+      if (root !== undefined && marker !== undefined) {
+        const entry = markers.get(root.absPath) ?? { root, linesByKey: new Map() };
+        const key = `${rel}::${marker.reason}`;
+        const set = entry.linesByKey.get(key) ?? new Set<number>();
+        set.add(marker.line);
+        entry.linesByKey.set(key, set);
+        markers.set(root.absPath, entry);
+        continue;
+      }
+      unsuppressed.push({
+        // cwd-relative, not repo-relative `rel` — the security baseline
+        // needs an unambiguous path to resolve back to (repo, relPath).
+        file: pathRelative(process.cwd(), file),
+        line: v.line,
+        message: `[${v.moduleSpecifier}] direct fs import outside allowlist`,
+      });
+    }
+  }
+  return { unsuppressed, markers };
+}
+
+function markerViolations(markers: ReadonlyMap<string, RootMarkers>): GuardViolation[] {
+  return [...markers.values()].flatMap((m) =>
+    ratchetFor(m.root)
+      .check(countsOf(m), MARKER_REMEDIATION, {
+        resolveLine: (key) => [...(m.linesByKey.get(key) ?? [])].sort((a, b) => a - b)[0] ?? 1,
+      })
+      .map((v) => {
+        const [relFile] = v.file.split("::");
+        const isMarkerKey = v.file.includes("::") && relFile !== undefined;
+        return {
+          ...v,
+          file: isMarkerKey ? pathRelative(process.cwd(), join(m.root.absPath, relFile)) : v.file,
+          // A frozen security baseline must never excuse an unfrozen marker.
+          neverFrozen: true,
+        };
+      }),
+  );
+}
+
 function findDynamicFsRequires(sf: SourceFile): Violation[] {
   const violations: Violation[] = [];
 
@@ -208,28 +310,20 @@ export const guard: AstGuard = {
   name: "No-Direct-Fs Guard",
   scan: SCAN,
   security: true,
-  hint: "Direct node:fs import outside the allowlist — use FileStorageProvider (packages/framework/src/files/) instead of wiring fs yourself. The path-traversal guard (resolveContainedPath) only exists there. Legitimate new tooling caller? Extend the allowlist in guard-no-direct-fs.ts, with a reason + repo scope.",
+  hint: 'Direct node:fs import outside the allowlist — use FileStorageProvider (packages/framework/src/files/) instead of wiring fs yourself; the path-traversal guard (resolveContainedPath) only exists there. Read-only files your own build ships: declare them under package.json `kumiko.assets` and use readBundledAsset(name) from @cosmicdrift/kumiko-server-runtime. Legitimate tooling exception: mark the import with `// kumiko-lint-ignore direct-fs <reason>` and freeze it with `kumiko-guards guards --write-baseline --guard="No-Direct-Fs Guard"` (.kumiko-direct-fs-baseline.json, reviewed as a diff).',
   run(files, roots: readonly RepoRoot[] = resolveRepoRoots()) {
-    const violations: Array<{ file: string; line: number; message: string }> = [];
-
-    for (const sf of files) {
-      const file = sf.getFilePath();
-      const rel = relFromRepoRoot(file, roots);
-      if (EXCLUDE.test(rel)) continue;
-      const root = findRepoRootFor(file, roots);
-      if (isRepoAllowlisted(root?.name, rel)) continue;
-      for (const v of findDirectFsImports(sf)) {
-        violations.push({
-          // cwd-relative, not repo-relative `rel` — the security baseline
-          // needs an unambiguous path to resolve back to (repo, relPath).
-          file: pathRelative(process.cwd(), file),
-          line: v.line,
-          message: `[${v.moduleSpecifier}] direct fs import outside allowlist`,
-        });
+    const { unsuppressed, markers } = collect(files, roots);
+    return { violations: [...unsuppressed, ...markerViolations(markers)] };
+  },
+  writeBaseline(files, roots: readonly RepoRoot[] = resolveRepoRoots()) {
+    const { markers } = collect(files, roots);
+    for (const m of markers.values()) ratchetFor(m.root).write(countsOf(m));
+    // A repo whose last marker is gone keeps a stale baseline unless it is shrunk too.
+    for (const root of roots) {
+      if (!markers.has(root.absPath) && existsSync(join(root.absPath, BASELINE_FILE))) {
+        ratchetFor(root).write({});
       }
     }
-
-    return { violations };
   },
 };
 

package/src/run-guards.ts

@@ -160,7 +160,10 @@ export function runGuardsCli(argv: readonly string[], deps: RunGuardsCliDeps = {
       return 1;
     }
     const project = buildSharedProject([target], deps.writeBaselineRoots);
-    target.writeBaseline(filesForGuard(project, target, deps.writeBaselineRoots));
+    target.writeBaseline(
+      filesForGuard(project, target, deps.writeBaselineRoots),
+      deps.writeBaselineRoots,
+    );
     return 0;
   }
   const strictSecurityBaseline = flags.includes("--strict-security-baseline");