@cosmicdrift/kumiko-guards 0.377.0 → 0.378.0

package/README.md

@@ -67,8 +67,9 @@ drops it.
 A POSIX-sh pre-push hook, wired by copying the package's `hooks/pre-push`
 shim to `.husky/pre-push`. The shim execs the nearest executable
 `node_modules/.bin/kumiko-pre-push` from the repo root upwards (so worktrees
-without their own `node_modules` resolve via the parent install) and fails
-closed with a `bun install` hint when none exists. Inside
+without their own `node_modules` resolve via the parent install, up to and
+including `$HOME`, skipping ancestors owned by another user or writable by
+group/others) and fails closed with a `bun install` hint when none exists. Inside
 the cosmicdriftgamestudio parent workspace it runs a scoped `bun check` for
 the pushing repo only; in a standalone clone it runs the repo's own
 `package.json` `test` script. From a `.wt/<name>` worktree under the parent

package/hooks/pre-push

@@ -8,15 +8,35 @@ fi
 # Walk up so a worktree without its own node_modules resolves via the parent
 # install, but not past an enclosing repository: a bin above that boundary
 # belongs to another project. `[ -x ]` also skips a broken (uninstalled) symlink.
+# A bin in an ancestor that is owned by someone else or group/world-writable
+# (/tmp, /Users/Shared) is attacker-plantable and must never be exec'd, and
+# $HOME is the upper trust boundary (inclusive), compared by physical path
+# because git prints REPO_ROOT resolved: a trailing slash or a symlinked home
+# would otherwise never match and the walk would continue to /.
+HOME_BOUND=""
+if [ -n "$HOME" ] && [ -d "$HOME" ]; then
+  HOME_BOUND="$(cd "$HOME" 2>/dev/null && pwd -P)"
+fi
 BIN=""
 DIR="$REPO_ROOT"
 while true; do
-  CANDIDATE="$DIR/node_modules/.bin/kumiko-pre-push"
-  if [ -x "$CANDIDATE" ]; then
-    BIN="$CANDIDATE"
-    break
+  TRUSTED=1
+  if [ "$DIR" != "$REPO_ROOT" ]; then
+    if [ ! -O "$DIR" ] || [ -n "$(find "$DIR" -maxdepth 0 \( -perm -0020 -o -perm -0002 \) -print 2>/dev/null)" ]; then
+      TRUSTED=0
+    fi
+  fi
+  if [ "$TRUSTED" = 1 ]; then
+    BIN_DIR="$DIR/node_modules/.bin"
+    CANDIDATE="$BIN_DIR/kumiko-pre-push"
+    # The bin dir itself must be user-owned and not group/world-writable, or a
+    # planted entry could replace the real bin.
+    if [ -x "$CANDIDATE" ] && [ -O "$BIN_DIR" ] && [ -z "$(find "$BIN_DIR" -maxdepth 0 \( -perm -0020 -o -perm -0002 \) -print 2>/dev/null)" ]; then
+      BIN="$CANDIDATE"
+      break
+    fi
   fi
-  if [ "$DIR" = "/" ]; then
+  if [ "$DIR" = "/" ] || { [ -n "$HOME_BOUND" ] && [ "$DIR" = "$HOME_BOUND" ]; }; then
     break
   fi
   if [ "$DIR" != "$REPO_ROOT" ] && [ -e "$DIR/.git" ]; then

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-guards",
-  "version": "0.377.0",
+  "version": "0.378.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>",
@@ -59,6 +59,6 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-framework": "0.377.0"
+    "@cosmicdrift/kumiko-framework": "0.378.0"
   }
 }

package/src/changes.json

@@ -1,4 +1,28 @@
 [
+  {
+    "version": "0.378.0",
+    "type": "fix",
+    "title": "Direct-entity-writes guard catches imported event-store tables",
+    "detail": "Table identifiers are resolved through import aliases to their definition, so direct insert/update/delete on an event-store table imported from another file of the scanned repo is no longer missed. Findings now show the full receiver (ctx.db). Existing consumers can get new findings that were previously hidden."
+  },
+  {
+    "version": "0.378.0",
+    "type": "improvement",
+    "title": "Faster, leaner guard run",
+    "detail": "Four AST guards skip files that cannot contain their anchor names before walking every node, and Direct-Entity-Writes only resolves symbols for table arguments named like an event-sourced table. Findings are identical."
+  },
+  {
+    "version": "0.378.0",
+    "type": "fix",
+    "title": "Pre-push shim skips untrusted ancestors and stops at $HOME",
+    "detail": "The shim walked up to / and could exec a kumiko-pre-push planted in /tmp or another shared directory. The walk now ends at $HOME and skips ancestors that another user owns or that group or others can write to."
+  },
+  {
+    "version": "0.378.0",
+    "type": "fix",
+    "title": "Pre-push shim also vets node_modules/.bin",
+    "detail": "The shim now requires node_modules/.bin itself to be owned by the user and not group or world writable before executing kumiko-pre-push from it, in the guards hook and the dev-server husky template."
+  },
   {
     "version": "0.377.0",
     "type": "improvement",

package/src/guard-api-object-form.ts

@@ -41,6 +41,8 @@ const REGISTRAR_TYPE_MARKER = "FeatureRegistrar";
 const FEATURE_FACTORY_NAME = "defineFeature";
 const REGISTRAR_RECEIVER_NAMES: ReadonlySet<string> = new Set(["r", "registrar"]);
 const EXCLUDED_PATH = /(\/__tests__\/fixtures\/|\.d\.ts$)/;
+// Cheap text superset of what positionalCallMethod can match; skips the AST walk for most files.
+const REGISTRAR_METHOD_ACCESS = new RegExp(`\\.\\s*(?:${REGISTRAR_METHODS.join("|")})\\b`);
 const UPGRADE_HINT = "run `bun kumiko-upgrade --apply` (codemod object-form)";
 
 type ReceiverResolution = "registrar" | "other" | "unresolved";
@@ -145,39 +147,51 @@ function positionalCallMethod(call: CallExpression): RegistrarMethod | undefined
 
 export type ObjectFormFinding = { file: string; line: number; message: string };
 
+function positionalCallFindings(sf: SourceFile, file: string): ObjectFormFinding[] {
+  if (!REGISTRAR_METHOD_ACCESS.test(sf.getFullText())) return [];
+  const out: ObjectFormFinding[] = [];
+  for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+    const method = positionalCallMethod(call);
+    if (method === undefined) continue;
+    out.push({
+      file,
+      line: call.getStartLineNumber(),
+      message: `positional r.${method}(…) removed in 0.366 — ${UPGRADE_HINT}`,
+    });
+  }
+  return out;
+}
+
+function crudFindings(sf: SourceFile, file: string): ObjectFormFinding[] {
+  // Every crud local name is CRUD_FUNCTION_NAME itself or an import alias of it.
+  if (!sf.getFullText().includes(CRUD_FUNCTION_NAME)) return [];
+  const crudNames = crudLocalNames(sf);
+  const out: ObjectFormFinding[] = [];
+  for (const id of sf.getDescendantsOfKind(SyntaxKind.Identifier)) {
+    if (!crudNames.has(id.getText())) continue;
+    const parent = id.getParent();
+    const isCall = Node.isCallExpression(parent) && parent.getExpression() === id;
+    const isImportOrExport =
+      Node.isImportSpecifier(parent) ||
+      Node.isExportSpecifier(parent) ||
+      id.getFirstAncestorByKind(SyntaxKind.ImportDeclaration) !== undefined;
+    if (!isCall && !isImportOrExport) continue;
+    if (Node.isImportSpecifier(parent) && parent.getAliasNode() === id) continue;
+    out.push({
+      file,
+      line: id.getStartLineNumber(),
+      message: `registerEntityCrud removed in 0.366 — use r.crud(…); ${UPGRADE_HINT}`,
+    });
+  }
+  return out;
+}
+
 export function findPositionalRegistrarCalls(files: readonly SourceFile[]): ObjectFormFinding[] {
   const out: ObjectFormFinding[] = [];
   for (const sf of files) {
     if (EXCLUDED_PATH.test(sf.getFilePath())) continue;
     const file = relativeToCwd(sf.getFilePath());
-    const crudNames = crudLocalNames(sf);
-
-    for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
-      const method = positionalCallMethod(call);
-      if (method === undefined) continue;
-      out.push({
-        file,
-        line: call.getStartLineNumber(),
-        message: `positional r.${method}(…) removed in 0.366 — ${UPGRADE_HINT}`,
-      });
-    }
-
-    for (const id of sf.getDescendantsOfKind(SyntaxKind.Identifier)) {
-      if (!crudNames.has(id.getText())) continue;
-      const parent = id.getParent();
-      const isCall = Node.isCallExpression(parent) && parent.getExpression() === id;
-      const isImportOrExport =
-        Node.isImportSpecifier(parent) ||
-        Node.isExportSpecifier(parent) ||
-        id.getFirstAncestorByKind(SyntaxKind.ImportDeclaration) !== undefined;
-      if (!isCall && !isImportOrExport) continue;
-      if (Node.isImportSpecifier(parent) && parent.getAliasNode() === id) continue;
-      out.push({
-        file,
-        line: id.getStartLineNumber(),
-        message: `registerEntityCrud removed in 0.366 — use r.crud(…); ${UPGRADE_HINT}`,
-      });
-    }
+    out.push(...positionalCallFindings(sf, file), ...crudFindings(sf, file));
   }
   return out;
 }

package/src/guard-direct-entity-writes.ts

@@ -156,21 +156,26 @@ export function unwrapTableExpression(node: Node): Node {
 // declaration disambiguates them.
 type TableId = string; // "${filePath}::${name}"
 
-function declIdOf(id: import("ts-morph").Identifier): TableId | undefined {
+function declIdOf(id: Identifier): TableId | undefined {
   const symbol = id.getSymbol();
   if (!symbol) return undefined;
-  const decls = symbol.getDeclarations();
+  // An imported identifier's own declaration is the ImportSpecifier; follow the alias
+  // chain (barrels, renames) so the ID matches the one built at the definition.
+  const resolved = symbol.isAlias() ? (symbol.getAliasedSymbol() ?? symbol) : symbol;
+  const decls = resolved.getDeclarations();
   if (decls.length === 0) return undefined;
   // Param-only symbols are factory pass-throughs — skip.
   if (decls.every((d) => d.getKind() === SyntaxKind.Parameter)) return undefined;
   const first = decls[0];
   if (!first) return undefined;
-  return `${first.getSourceFile().getFilePath()}::${id.getText()}`;
+  const name = Node.hasName(first) ? first.getName() : id.getText();
+  return `${first.getSourceFile().getFilePath()}::${name}`;
 }
 
 export function collectEsTables(files: readonly SourceFile[]): Set<TableId> {
   const tables = new Set<TableId>();
   for (const sf of files) {
+    if (!sf.getFullText().includes("createEventStoreExecutor")) continue;
     for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
       const expr = call.getExpression();
       if (expr.getText() !== "createEventStoreExecutor") continue;
@@ -251,6 +256,8 @@ function rebuildableEntityTableDeclId(
   return declIdOf(nameNode.asKindOrThrow(SyntaxKind.Identifier));
 }
 
+const ENTITY_METHOD_ACCESS = /\.\s*entity\b/;
+
 // Tables registered via `r.entity({ name, ...entityDef })` as a rebuildable implicit
 // projection, linked entity→table via the shared entity-def symbol (see header), not by name string.
 export function collectEntityProjectionTables(files: readonly SourceFile[]): Set<TableId> {
@@ -259,6 +266,7 @@ export function collectEntityProjectionTables(files: readonly SourceFile[]): Set
 
   // Pass 1: entity-def decls that r.entity makes rebuildable (+ {table} override).
   for (const sf of files) {
+    if (!ENTITY_METHOD_ACCESS.test(sf.getFullText())) continue;
     for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
       const registration = entityRegistrationOf(call);
       if (!registration) continue;
@@ -270,6 +278,7 @@ export function collectEntityProjectionTables(files: readonly SourceFile[]): Set
   // Pass 2: `const xTable = buildEntityTable(<name>, <entityDef>)` where entityDef
   // is in the rebuildable set → xTable is a rebuildable entity table.
   for (const sf of files) {
+    if (!sf.getFullText().includes("buildEntityTable")) continue;
     for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
       const did = rebuildableEntityTableDeclId(call, rebuildableEntities);
       if (did) tables.add(did);
@@ -427,14 +436,37 @@ function hasAnyTableWriteOrDeclaration(files: readonly SourceFile[]): boolean {
   return false;
 }
 
+// A TableId ends in `::<identifier text>`, so a table argument whose text is no ES table name
+// can never match; filtering on the name avoids a symbol lookup (TS program build) per call.
+function tableNamesOf(tableIds: ReadonlySet<TableId>): Set<string> {
+  return new Set([...tableIds].map((tableId) => tableId.slice(tableId.lastIndexOf("::") + 2)));
+}
+
+// Local names an import can give a table in this file (`import { a as b }` -> b). Syntactic,
+// so a rename or barrel re-export never hides an ES table from the name prefilter.
+function importedBindingNames(sf: SourceFile): Set<string> {
+  const names = new Set<string>();
+  for (const declaration of sf.getImportDeclarations()) {
+    const defaultName = declaration.getDefaultImport()?.getText();
+    if (defaultName) names.add(defaultName);
+    for (const specifier of declaration.getNamedImports()) {
+      names.add(specifier.getAliasNode()?.getText() ?? specifier.getName());
+    }
+  }
+  return names;
+}
+
 export function scanDirectWrites(
   sf: SourceFile,
   esTables: ReadonlySet<TableId>,
 ): Omit<Violation, "file">[] {
   const out: Omit<Violation, "file">[] = [];
+  // Superset of every name a write may use for an ES table: definition names plus import bindings.
+  const candidateNames = new Set([...tableNamesOf(esTables), ...importedBindingNames(sf)]);
   for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
     const w = resolveWrite(call);
     if (!w) continue;
+    if (!candidateNames.has(w.tableArg.getText())) continue;
 
     // Walk the receiver chain down to its leftmost identifier. For `db.insert`
     // that's `db`; for `ctx.db.raw` (function-form arg0) that's `ctx`; for
@@ -457,7 +489,7 @@ export function scanDirectWrites(
       if (isInsideProjectionApply(call)) continue;
       out.push({
         line: call.getStartLineNumber(),
-        receiver: receiverName,
+        receiver: w.receiver.getText(),
         op: w.op,
         table: w.tableArg.getText(),
         snippet: call.getText().slice(0, 120),
@@ -468,7 +500,7 @@ export function scanDirectWrites(
 
     out.push({
       line: call.getStartLineNumber(),
-      receiver: receiverName,
+      receiver: w.receiver.getText(),
       op: w.op,
       table: w.tableArg.getText(),
       snippet: call.getText().slice(0, 120),

package/src/guard-escape-hatch-declared.ts

@@ -128,6 +128,7 @@ function scannableFiles(files: readonly SourceFile[]): SourceFile[] {
 export function systemScopeDirs(files: readonly SourceFile[]): string[] {
   const dirs: string[] = [];
   for (const sf of scannableFiles(files)) {
+    if (!sf.getFullText().includes("systemScope")) continue;
     for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
       const expr = call.getExpression();
       if (
@@ -189,6 +190,10 @@ function isTenantDbExpression(node: Node): boolean {
   return (node.getSymbol()?.getDeclarations() ?? []).some(isTenantDbDeclaration);
 }
 
+// Text prefilters: a node walk per rule per file is the guard's dominant cost, and
+// a rule's anchor name must appear verbatim in any file it can fire on.
+const RAW_ACCESS = /\.\s*raw\b/;
+
 function findRawFindings(
   sf: SourceFile,
   root: string,
@@ -196,6 +201,7 @@ function findRawFindings(
 ): EscapeHatchFinding[] {
   if (isInSystemScope(sf.getFilePath(), systemDirs)) return [];
   const out: EscapeHatchFinding[] = [];
+  if (!RAW_ACCESS.test(sf.getFullText())) return out;
   for (const pa of sf.getDescendantsOfKind(SyntaxKind.PropertyAccessExpression)) {
     if (pa.getName() !== "raw") continue;
     if (!isTenantDbExpression(pa.getExpression())) continue;
@@ -217,6 +223,7 @@ function findUnsafeRawFindings(
 ): EscapeHatchFinding[] {
   if (isInSystemScope(sf.getFilePath(), systemDirs)) return [];
   const out: EscapeHatchFinding[] = [];
+  if (!sf.getFullText().includes("unsafeRaw")) return out;
   for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
     const expr = call.getExpression();
     if (!expr.isKind(SyntaxKind.PropertyAccessExpression)) continue;
@@ -531,6 +538,8 @@ function findSystemIdentityFindings(
   systemDirs: readonly string[],
 ): EscapeHatchFinding[] {
   const out: EscapeHatchFinding[] = [];
+  const text = sf.getFullText();
+  if (!text.includes("queryAs") && !text.includes("writeAs")) return out;
   for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
     const expr = call.getExpression();
     if (!expr.isKind(SyntaxKind.PropertyAccessExpression)) continue;
@@ -562,6 +571,7 @@ function findUnsafeAllTenantsFindings(
   systemDirs: readonly string[],
 ): EscapeHatchFinding[] {
   const out: EscapeHatchFinding[] = [];
+  if (!sf.getFullText().includes("unsafeAllTenants")) return out;
   for (const prop of sf.getDescendantsOfKind(SyntaxKind.PropertyAssignment)) {
     const nameNode = prop.getNameNode();
     if (!nameNode.isKind(SyntaxKind.Identifier) || nameNode.getText() !== "unsafeAllTenants") {
@@ -609,6 +619,8 @@ const GENERIC_REASON_METHODS = new Set(["acknowledgeCrossTenant", "unsafeRaw"]);
 
 function findGenericReasonMethodCalls(sf: SourceFile, root: string): GenericReasonFinding[] {
   const out: GenericReasonFinding[] = [];
+  const text = sf.getFullText();
+  if (![...GENERIC_REASON_METHODS].some((method) => text.includes(method))) return out;
   for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
     const expr = call.getExpression();
     if (!expr.isKind(SyntaxKind.PropertyAccessExpression)) continue;
@@ -634,6 +646,7 @@ function findGenericReasonDeclareEscapeHatchCalls(
   root: string,
 ): GenericReasonFinding[] {
   const out: GenericReasonFinding[] = [];
+  if (!sf.getFullText().includes("declareEscapeHatch")) return out;
   for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
     const callee = call.getExpression();
     if (!callee.isKind(SyntaxKind.Identifier) || callee.getText() !== "declareEscapeHatch") {
@@ -662,6 +675,7 @@ function findGenericReasonObjectProperty(
   propertyName: string,
 ): GenericReasonFinding[] {
   const out: GenericReasonFinding[] = [];
+  if (!sf.getFullText().includes(propertyName)) return out;
   for (const pa of sf.getDescendantsOfKind(SyntaxKind.PropertyAssignment)) {
     if (pa.getName() !== propertyName) continue;
     const init = pa.getInitializer();

package/src/guard-pre-es-patterns.ts

@@ -68,6 +68,8 @@ type Pattern = {
 // identifier in the AST (not in strings, not in comments).
 function identifierHits(sf: SourceFile, name: string): Array<{ line: number; snippet: string }> {
   const out: Array<{ line: number; snippet: string }> = [];
+  // Cheap text prefilter: a full descendant walk over every file costs seconds.
+  if (!sf.getFullText().includes(name)) return out;
   for (const id of sf.getDescendantsOfKind(SyntaxKind.Identifier)) {
     if (id.getText() !== name) continue;
     out.push({
@@ -85,6 +87,7 @@ function stringLiteralHits(
   literal: string,
 ): Array<{ line: number; snippet: string }> {
   const out: Array<{ line: number; snippet: string }> = [];
+  if (!sf.getFullText().includes(literal)) return out;
   for (const lit of sf.getDescendantsOfKind(SyntaxKind.StringLiteral)) {
     if (lit.getLiteralText() !== literal) continue;
     out.push({
@@ -129,6 +132,7 @@ const PATTERNS: readonly Pattern[] = [
       // Match `.postEvent(` property accesses to distinguish from the word
       // "postEvent" in prose. Identifier scan would miss method invocations.
       const out: Array<{ line: number; snippet: string }> = [];
+      if (!sf.getFullText().includes("postEvent")) return out;
       for (const pa of sf.getDescendantsOfKind(SyntaxKind.PropertyAccessExpression)) {
         if (pa.getName() !== "postEvent") continue;
         // Only flag when invoked as a method — a property read named

package/src/guard-renderer-boundaries.ts

@@ -6,9 +6,9 @@
  * belongs in `src/web` instead.
  *
  * `src/web/**` is the browser layer and not scanned at all: it may import
- * everything. `src/headless/**` and `src/live/**` only get the import rules:
- * the apex page builder emits HTML strings and the live dispatcher is a fetch
- * client, so the symbol and JSX-tag rules would be noise there. They stay free
+ * everything. `src/headless/**`, `src/flow-diagram/**` and `src/live/**` only get
+ * the import rules: the apex page builder emits HTML strings, the flow diagram
+ * emits SVG strings and the live dispatcher is a fetch client, so the symbol and JSX-tag rules would be noise there. They stay free
  * of react-dom, jsdom and any import of `src/web`.
  *
  * Deliberately simple: a regex scan over the source text. False positives
@@ -70,7 +70,7 @@ const FORBIDDEN_SYMBOLS = [
 const FORBIDDEN_JSX_TAG = /(^|\s|>|\()<([a-z][a-zA-Z0-9-]*)(?=[\s/>])/g;
 
 // Subtrees of packages/renderer/src that carry only the import rules.
-const IMPORT_RULES_ONLY_DIRS = ["headless", "live"] as const;
+const IMPORT_RULES_ONLY_DIRS = ["headless", "flow-diagram", "live"] as const;
 
 // The browser layer may import anything, so it is not scanned.
 const UNSCANNED_TOP_LEVEL_DIRS = ["web"] as const;