@cosmicdrift/kumiko-guards 0.1.0

package/src/guard-access-denied-test.ts

@@ -0,0 +1,135 @@
+#!/usr/bin/env bun
+/**
+ * Guard: role-restricted write handlers need an access-denied test.
+ *
+ * Rule: any `defineWriteHandler`/`*.writeHandler` call whose `access` object
+ * has a `roles` property (and no `openToAll`, and no anonymous/all role) must
+ * have a test somewhere in the repo that mentions the handler AND asserts a
+ * rejection (AccessDeniedError / access_denied / 403). Matching is file-level
+ * and within the handler's own repo, same contract as guard-tenant-escalation.
+ *
+ * Tripwire: a false-negative (a weak name match hiding a real gap) is
+ * tolerated; a false-positive on a clean repo is not.
+ *
+ * Usage:
+ *   bun guards/guard-access-denied-test.ts
+ *   Baseline: bun guards/run-guards.ts --write-security-baseline
+ */
+
+import * as path from "node:path";
+import { type SourceFile, SyntaxKind } from "ts-morph";
+import { findRepoRootFor } from "./_lib/baseline-compare";
+import { type AstGuard, type GuardViolation, runStandalone, type ScanSpec } from "./_lib/guard-kit";
+import {
+  escapeRegExp,
+  literalStringOf,
+  mentionsAsWord,
+  nameForms,
+} from "./_lib/handler-name-forms";
+import { resolveRepoRoots } from "./_lib/roots";
+
+const ROOT = process.cwd();
+const SCAN: ScanSpec = {
+  scope: "source",
+  extensions: ["ts"],
+  frameworkWithin: ["packages/*/src/**", "samples/**"],
+};
+const TEST_FILE = /\.test\.ts$/;
+
+// Any role that lets an unauthenticated/unrestricted caller through means
+// nobody is actually excluded by this handler's roles.
+const OPEN_ROLE_RE = /["'`](?:anonymous|all)["'`]|\baccess\.(?:all|anonymous)\b/;
+
+type RoleRestrictedHandler = { name: string; file: string; line: number };
+
+export function findRoleRestrictedWriteHandlers(
+  files: readonly SourceFile[],
+): RoleRestrictedHandler[] {
+  const out: RoleRestrictedHandler[] = [];
+  for (const sf of files) {
+    if (TEST_FILE.test(sf.getFilePath())) continue;
+    for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+      const callee = call.getExpression().getText();
+      if (callee !== "defineWriteHandler" && !/\.writeHandler$/.test(callee)) continue;
+      const arg = call.getArguments()[0];
+      if (!arg || arg.getKind() !== SyntaxKind.ObjectLiteralExpression) continue;
+      const obj = arg.asKindOrThrow(SyntaxKind.ObjectLiteralExpression);
+      const name = literalStringOf(obj.getProperty("name"));
+      if (!name) continue;
+      const accessProp = obj.getProperty("access");
+      if (!accessProp || accessProp.getKind() !== SyntaxKind.PropertyAssignment) continue;
+      const accessInit = accessProp.asKindOrThrow(SyntaxKind.PropertyAssignment).getInitializer();
+      if (!accessInit || accessInit.getKind() !== SyntaxKind.ObjectLiteralExpression) continue;
+      const accessObj = accessInit.asKindOrThrow(SyntaxKind.ObjectLiteralExpression);
+      if (accessObj.getProperty("openToAll")) continue;
+      const rolesProp = accessObj.getProperty("roles");
+      if (!rolesProp) continue;
+      if (
+        rolesProp.getKind() !== SyntaxKind.PropertyAssignment &&
+        rolesProp.getKind() !== SyntaxKind.ShorthandPropertyAssignment
+      )
+        continue;
+      if (OPEN_ROLE_RE.test(rolesProp.getText())) continue;
+      out.push({ name, file: sf.getFilePath(), line: call.getStartLineNumber() });
+    }
+  }
+  return out;
+}
+
+const ACCESS_DENIED_ASSERTION = /\bAccessDeniedError\b|\baccess_denied\b|\b403\b/;
+
+const SHORT_WORD = /^[a-z0-9]+$/;
+
+// A single lowercase word ("create", "approve") is common enough in
+// unrelated test scaffolding (createTestStack, approveAll) that a bare word-
+// boundary match is too loose — only count it as a string-literal end
+// ("approve"/"feat:write:approve") or a property access (Handlers.approve).
+export function testMentionsHandler(text: string, handlerName: string): boolean {
+  return nameForms(handlerName).some((form) => {
+    if (!SHORT_WORD.test(form)) return mentionsAsWord(text, form);
+    const esc = escapeRegExp(form);
+    return new RegExp(`[:"'\`]${esc}["'\`]|\\.${esc}\\b`).test(text);
+  });
+}
+
+export function findHandlersWithoutAccessDeniedTest(
+  files: readonly SourceFile[],
+  roots: readonly { readonly absPath: string }[] = [],
+): RoleRestrictedHandler[] {
+  const repoKeyOf = (filePath: string): string => findRepoRootFor(filePath, roots)?.absPath ?? "";
+  const testTextsByRepo = new Map<string, string[]>();
+  for (const sf of files) {
+    if (!TEST_FILE.test(sf.getFilePath())) continue;
+    const text = sf.getFullText();
+    if (!ACCESS_DENIED_ASSERTION.test(text)) continue;
+    const repoKey = repoKeyOf(sf.getFilePath());
+    const texts = testTextsByRepo.get(repoKey) ?? [];
+    texts.push(text);
+    testTextsByRepo.set(repoKey, texts);
+  }
+  return findRoleRestrictedWriteHandlers(files).filter((h) => {
+    const testTexts = testTextsByRepo.get(repoKeyOf(h.file)) ?? [];
+    return !testTexts.some((text) => testMentionsHandler(text, h.name));
+  });
+}
+
+export const guard: AstGuard = {
+  name: "Access-Denied-Test Guard",
+  scan: SCAN,
+  security: true,
+  hint: "Role-restricted write handlers need a test that references the handler and asserts a caller without the role is rejected (AccessDeniedError / access_denied / 403). Existing gaps are frozen in the security baseline; after closing one: `bun guards/run-guards.ts --write-security-baseline`.",
+  run(files) {
+    // consumer CI scans only its own repo, so a sibling repo's test must not count as coverage
+    const violations: GuardViolation[] = findHandlersWithoutAccessDeniedTest(
+      files,
+      resolveRepoRoots(),
+    ).map((h) => ({
+      file: path.relative(ROOT, h.file),
+      line: h.line,
+      message: `role-restricted write handler "${h.name}" has no access-denied test — add a test that references the handler and asserts a caller without the role is rejected (AccessDeniedError / access_denied / 403).`,
+    }));
+    return { violations };
+  },
+};
+
+if (import.meta.main) runStandalone(guard);

package/src/guard-admin-api.ts

@@ -0,0 +1,134 @@
+#!/usr/bin/env bun
+/**
+ * Guard: blocks calls to the event-store admin API (`appendRaw`/`appendRawBatch`)
+ * outside allowed paths.
+ *
+ * The admin API is a Marten bypass for legacy data imports (prod-readiness
+ * wave 3, step 3.1). It BYPASSES the pipeline — no projections, no
+ * postSave hooks, no SSE/search/audit. Used accidentally from application
+ * code, that causes state inconsistencies that surface very late (at the
+ * next projection rebuild, or never).
+ *
+ * Second line of defense next to the deep-import path: even if someone pulls
+ * `@kubiko/framework/event-store/admin-api` directly, this guard catches it
+ * at the next `bun kumiko check`.
+ *
+ * Usage:
+ *   bun guards/guard-admin-api.ts
+ *
+ * Exit 1 if violations found, 0 if clean.
+ */
+
+import * as path from "node:path";
+import { type CallExpression, type Identifier, type SourceFile, SyntaxKind } from "ts-morph";
+import { type AstGuard, runStandalone, type ScanSpec } from "./_lib/guard-kit";
+
+const ROOT = process.cwd();
+
+const SCAN: ScanSpec = { scope: "source", extensions: ["ts"] };
+
+// Test files may use the API freely — they are the primary verifiers.
+// App code is never shipped through tests.
+const EXCLUDE = /(__tests__|\.test\.ts$|\.integration\.ts$|\.d\.ts$)/;
+
+// Allowed callers: migration runners (sample-local, src/ and bin/) +
+// admin scripts + the definition itself + this guard script.
+const ALLOWLIST: readonly RegExp[] = [
+  /^samples\/[^/]+\/src\/migration\//,
+  /^scripts\/migrations\//,
+  /^packages\/framework\/src\/event-store\/admin-api\.ts$/,
+  /^scripts\/guard-admin-api\.ts$/,
+];
+
+const GUARDED_CALLS = new Set(["appendRaw", "appendRawBatch"]);
+
+export interface Violation {
+  file: string;
+  line: number;
+  functionName: string;
+  enclosingFunction: string;
+}
+
+function collectViolations(sourceFile: SourceFile): Violation[] {
+  const violations: Violation[] = [];
+  const relativePath = path.relative(ROOT, sourceFile.getFilePath());
+  if (isAllowed(relativePath)) return violations;
+
+  const calls = sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression);
+  for (const call of calls) {
+    const fnName = getCalleeName(call);
+    if (!fnName || !GUARDED_CALLS.has(fnName)) continue;
+    violations.push({
+      file: relativePath,
+      line: call.getStartLineNumber(),
+      functionName: fnName,
+      enclosingFunction: findEnclosingName(call),
+    });
+  }
+  return violations;
+}
+
+function isAllowed(relativePath: string): boolean {
+  return ALLOWLIST.some((re) => re.test(relativePath));
+}
+
+// Extract the called name. Handles:
+//   appendRaw(...)              → "appendRaw"   (Identifier)
+//   someNamespace.appendRaw(...) → "appendRaw"  (PropertyAccessExpression)
+// Any other callee shape returns null — we only want bare-name / qualified-name
+// references to the known function names.
+function getCalleeName(call: CallExpression): string | null {
+  const expr = call.getExpression();
+  if (expr.getKind() === SyntaxKind.Identifier) {
+    return (expr as Identifier).getText();
+  }
+  if (expr.getKind() === SyntaxKind.PropertyAccessExpression) {
+    const name = expr.asKindOrThrow(SyntaxKind.PropertyAccessExpression).getName();
+    return name;
+  }
+  return null;
+}
+
+function findEnclosingName(call: CallExpression): string {
+  let cur = call.getParent();
+  while (cur) {
+    if (cur.isKind(SyntaxKind.FunctionDeclaration) || cur.isKind(SyntaxKind.MethodDeclaration)) {
+      return cur.getName() ?? "<anonymous>";
+    }
+    if (cur.isKind(SyntaxKind.FunctionExpression) || cur.isKind(SyntaxKind.ArrowFunction)) {
+      const parent = cur.getParent();
+      if (parent?.isKind(SyntaxKind.VariableDeclaration)) return parent.getName();
+      if (parent?.isKind(SyntaxKind.PropertyAssignment)) return parent.getName();
+      return "<anonymous>";
+    }
+    cur = cur.getParent();
+  }
+  return "<top-level>";
+}
+
+export const guard: AstGuard = {
+  name: "Admin-API Guard",
+  scan: SCAN,
+  // App repos are not exempt — appendRaw/appendRawBatch bypasses the pipeline there too (infra#502).
+  security: true,
+  hint: "Admin-API (appendRaw/appendRawBatch) umgeht die Pipeline — erlaubt nur in samples/*/migration/ oder scripts/migrations/. Für Domain-Events: ctx.appendEvent / write-Handler.",
+  run(files) {
+    const violations: Array<{ file: string; line: number; message: string }> = [];
+
+    for (const sf of files) {
+      const file = sf.getFilePath();
+      if (EXCLUDE.test(file)) continue;
+      for (const v of collectViolations(sf)) {
+        violations.push({
+          file: v.file,
+          line: v.line,
+          message: `${v.functionName}(...) in ${v.enclosingFunction}`,
+        });
+      }
+    }
+
+    return { violations };
+  },
+};
+
+if (import.meta.main) runStandalone(guard);

package/src/guard-cross-feature-imports.ts

@@ -0,0 +1,244 @@
+#!/usr/bin/env bun
+/**
+ * Guard: blocks cross-feature deep imports.
+ *
+ * R1 from docs/plans/architecture/lint-rules.md.
+ *
+ * What's enforced:
+ *   - A file inside feature A may not import from feature B's internals.
+ *   - Allowed cross-feature imports: the barrel (`from "../B"`, or
+ *     `"../B/index"` / `"../B/index.ts"`), and two side-effect-free public
+ *     surface modules — `"../B/contract"` and `"../B/schema/entity"` (with
+ *     or without extension). Anything else — `from "../B/types"`,
+ *     `from "../B/handlers/foo"`, `from "../B/feature"` — is rejected.
+ *   - Same-feature relative imports (`./x`, `../sibling-in-same-feature`)
+ *     stay unrestricted.
+ *   - Non-relative imports (`@cosmicdrift/kumiko-framework`, `drizzle-orm`, `zod`)
+ *     stay unrestricted.
+ *
+ * Why: deep imports couple feature B's file layout to feature A's call
+ * sites. A rename inside B silently breaks A. The barrel is B's public
+ * contract — A only sees what B chose to export.
+ *
+ * Feature-boundary inference:
+ *   - packages/bundled-features/src/<feature>/...
+ *   - samples/<sample>/src/features/<feature>/...
+ *
+ * Files outside those layouts (e.g. samples/<sample>/src/feature.ts for
+ * single-feature samples, framework internals) have no feature boundary
+ * and are skipped.
+ *
+ * Escape hatch: `// kumiko-lint-ignore cross-feature-import [reason]`
+ * on the same line as the import, or on the line directly above.
+ *
+ * Usage:
+ *   bun guards/guard-cross-feature-imports.ts
+ *
+ * Exit 1 on violations, 0 when clean.
+ */
+
+import * as path from "node:path";
+import type { SourceFile } from "ts-morph";
+import { type AstGuard, runStandalone, type ScanSpec } from "./_lib/guard-kit";
+
+const ROOT = process.cwd();
+
+const SCAN: ScanSpec = {
+  scope: "source",
+  extensions: ["ts"],
+  frameworkWithin: ["packages/*/src/**", "samples/recipes/*/src/**", "samples/apps/*/src/**"],
+};
+
+const EXCLUDE = /(__tests__|\.test\.ts$|\.integration\.ts$|\.d\.ts$|\.g\.ts$)/;
+
+// Files with an explicit, documented exception. Each entry must come with a
+// TODO naming the planned refactor — the allowlist exists to turn the guard
+// on without blocking the merge, not as a permanent home.
+const ALLOWLIST: ReadonlyArray<{ pattern: RegExp; reason: string }> = [];
+
+const IGNORE_TAG = "kumiko-lint-ignore cross-feature-import";
+
+interface Violation {
+  file: string;
+  line: number;
+  importPath: string;
+  importedFeature: string;
+  fileFeature: string;
+}
+
+type FeatureLocation = {
+  // Repo-relative path of the feature's root directory. Two files resolve
+  // to the same boundary iff they live under the same root.
+  readonly root: string;
+  readonly name: string;
+};
+
+// Identifies the feature a file belongs to. Returns null for files that
+// live outside any feature boundary (single-feature sample roots,
+// framework-internal helpers reached via the same scan).
+function locateFeature(absPath: string): FeatureLocation | null {
+  const rel = path.relative(ROOT, absPath);
+
+  const coreMatch = rel.match(/^(packages\/bundled-features\/src\/([^/]+))\//);
+  if (coreMatch?.[1] && coreMatch[2]) {
+    return { root: coreMatch[1], name: coreMatch[2] };
+  }
+
+  // Other packages/<pkg>/src layouts (framework internals, enterprise
+  // packages): the package itself is the feature boundary — enterprise
+  // ships one feature per package (packages/ai-conversation/src/
+  // feature.ts), framework packages outside bundled-features have no
+  // sub-feature concept. Safe superset: never flags same-package imports,
+  // only catches genuine cross-package deep-relative imports — which
+  // shouldn't exist anyway since packages are consumed as separate npm
+  // packages via bare specifiers, not relative paths.
+  const pkgMatch = rel.match(/^(packages\/([^/]+)\/src)\//);
+  if (pkgMatch?.[1] && pkgMatch[2]) {
+    return { root: pkgMatch[1], name: pkgMatch[2] };
+  }
+
+  const sampleMatch = rel.match(/^(samples\/[^/]+\/src\/features\/([^/]+))(\/|$)/);
+  if (sampleMatch?.[1] && sampleMatch[2]) {
+    return { root: sampleMatch[1], name: sampleMatch[2] };
+  }
+
+  // Flat-layout app repos (studio, publicstatus, show-pony, money-horse,
+  // phronexsis, offlot-app, solon): src/features/<feature>/...
+  const appMatch = rel.match(/^(src\/features\/([^/]+))(\/|$)/);
+  if (appMatch?.[1] && appMatch[2]) {
+    return { root: appMatch[1], name: appMatch[2] };
+  }
+
+  return null;
+}
+
+function isAllowlisted(filePath: string): { allowed: true; reason: string } | { allowed: false } {
+  const rel = path.relative(ROOT, filePath);
+  for (const entry of ALLOWLIST) {
+    if (entry.pattern.test(rel)) return { allowed: true, reason: entry.reason };
+  }
+  return { allowed: false };
+}
+
+// Kumiko's feature barrel (feature.ts) doubles as the registration module
+// (mounts handlers/entities) — importing it pulls in the whole server
+// graph and creates require cycles. These two are side-effect-free
+// declaration modules (contract types, entity definition) that exist
+// precisely to be read by other features, so they're allowed alongside the
+// barrel. Closed set, not "everything but the barrel": `feature`/
+// `feature.ts` must stay blocked, that's the registration module the guard
+// exists to protect.
+const PUBLIC_SURFACE_MODULES = new Set([
+  "contract",
+  "contract.ts",
+  "contract.tsx",
+  "schema/entity",
+  "schema/entity.ts",
+  "schema/entity.tsx",
+]);
+
+// True when the resolved import path points inside `featureRoot` AND
+// addresses something deeper than the barrel index. The barrel itself
+// (a) bare `featureRoot` directory or (b) `featureRoot/index` is the
+// public contract — anything else is an internal.
+function isDeepImport(resolvedAbs: string, featureRoot: string): boolean {
+  const featureRootAbs = path.join(ROOT, featureRoot);
+  const rel = path.relative(featureRootAbs, resolvedAbs);
+  if (
+    rel === "" ||
+    rel === "index" ||
+    rel === "index.ts" ||
+    rel === "index.tsx" ||
+    PUBLIC_SURFACE_MODULES.has(rel)
+  ) {
+    return false;
+  }
+  // Same-folder index without extension lookup ends up as "index" — keep
+  // that allowed; everything else (`types`, `handlers/foo`, etc.) is deep.
+  return true;
+}
+
+// Resolve a relative import to its absolute on-disk path. ts-morph's
+// SourceFile.getModuleSpecifierSourceFile() walks the same resolution the
+// compiler uses; we use it so the guard agrees with TS exactly.
+function resolveImport(sf: SourceFile, specifier: string): string | null {
+  if (!specifier.startsWith(".")) return null;
+  const importDecl = sf
+    .getImportDeclarations()
+    .find((d) => d.getModuleSpecifierValue() === specifier);
+  if (!importDecl) return null;
+  const target = importDecl.getModuleSpecifierSourceFile();
+  if (target) return target.getFilePath();
+  // The import may resolve to a barrel directory whose index.ts ts-morph
+  // didn't add to the project. Fall back to a manual join + .ts probe.
+  return path.resolve(path.dirname(sf.getFilePath()), specifier);
+}
+
+function isIgnored(sf: SourceFile, importLine: number): boolean {
+  const text = sf.getFullText();
+  const lines = text.split("\n");
+  const onLine = lines[importLine - 1] ?? "";
+  if (onLine.includes(IGNORE_TAG)) return true;
+  const above = lines[importLine - 2] ?? "";
+  return above.trim().startsWith("//") && above.includes(IGNORE_TAG);
+}
+
+function findCrossFeatureViolations(sf: SourceFile): Omit<Violation, "file">[] {
+  const fileFeature = locateFeature(sf.getFilePath());
+  if (!fileFeature) return [];
+
+  const violations: Omit<Violation, "file">[] = [];
+
+  for (const importDecl of sf.getImportDeclarations()) {
+    const specifier = importDecl.getModuleSpecifierValue();
+    if (!specifier.startsWith(".")) continue;
+
+    const resolved = resolveImport(sf, specifier);
+    if (!resolved) continue;
+
+    const importedFeature = locateFeature(resolved);
+    if (!importedFeature) continue;
+    if (importedFeature.root === fileFeature.root) continue;
+
+    if (!isDeepImport(resolved, importedFeature.root)) continue;
+
+    const line = importDecl.getStartLineNumber();
+    if (isIgnored(sf, line)) continue;
+
+    violations.push({
+      line,
+      importPath: specifier,
+      importedFeature: importedFeature.name,
+      fileFeature: fileFeature.name,
+    });
+  }
+
+  return violations;
+}
+
+export const guard: AstGuard = {
+  name: "Cross-Feature-Import Guard",
+  scan: SCAN,
+  hint: `Import from the feature's barrel ("../<feature>") instead of its internals. Escape hatch: "// ${IGNORE_TAG} [reason]" on the import line.`,
+  run(files) {
+    const violations: Array<{ file: string; line: number; message: string }> = [];
+
+    for (const sf of files) {
+      const file = sf.getFilePath();
+      if (EXCLUDE.test(file)) continue;
+      if (isAllowlisted(file).allowed) continue;
+
+      for (const v of findCrossFeatureViolations(sf)) {
+        violations.push({
+          file: path.relative(ROOT, file),
+          line: v.line,
+          message: `feature "${v.fileFeature}" → "${v.importedFeature}" (${v.importPath})`,
+        });
+      }
+    }
+
+    return { violations };
+  },
+};
+
+if (import.meta.main) runStandalone(guard);