@cosmicdrift/kumiko-guards 0.320.0 → 0.322.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-guards",
-  "version": "0.320.0",
+  "version": "0.322.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.320.0",
+    "@cosmicdrift/kumiko-repo-manifest": "0.322.0",
     "ts-morph": "^28.0.0"
   },
   "publishConfig": {

package/src/changes.json

@@ -1,4 +1,18 @@
 [
+  {
+    "version": "0.321.0",
+    "type": "improvement",
+    "title": "pre-push.sh refuses to push a stale .kumiko/upgrade-state.json",
+    "detail": "When `.kumiko/upgrade-state.json` exists at the repo root, `pre-push.sh`\nnow runs the upgrade-state guard before its main check and refuses the\npush if the guard fails, resolving `guard-upgrade-state.ts` next to the\nhook's real (symlink-resolved) script location.",
+    "migration": "A repo that has adopted `.kumiko/upgrade-state.json` and is currently\nstale now has its push blocked until the upgrade state is reconciled. A\nrepo without that marker file is unaffected."
+  },
+  {
+    "version": "0.321.0",
+    "type": "improvement",
+    "title": "New guard blocks direct writes to the event-store tables outside the event store itself",
+    "detail": "guard-event-store-writes.ts flags any UPDATE/DELETE FROM/INSERT INTO\nstring or template literal naming kumiko_events, kumiko_snapshots, or\nkumiko_archived_streams outside packages/framework/src/event-store/**\nand their db/queries/event-store*.ts backing (plus the two pre-existing,\nnamed one-time backfill exceptions). Registered in run-guards.ts.",
+    "migration": "No action needed for code that already goes through the event store's\nown primitives (append, transferAggregateStreams, archiveStream, ...).\nA direct raw-SQL write against one of these three tables from feature\ncode now fails the guard; use transferAggregateStreams for a tenant\nmove, or add a new event-store primitive instead."
+  },
   {
     "version": "0.317.0",
     "type": "fix",

package/src/guard-event-store-writes.ts

@@ -0,0 +1,124 @@
+#!/usr/bin/env bun
+/**
+ * Guard: flags string/template literals containing UPDATE/DELETE FROM/INSERT
+ * INTO against kumiko_events, kumiko_snapshots or kumiko_archived_streams
+ * outside the event store's own files.
+ *
+ * These three tables ARE the event store. A direct write from elsewhere
+ * bypasses its invariants (version-unique index, archive markers, tenant
+ * boundary). Tenant moves go through `transferAggregateStreams`
+ * (event-store/transfer.ts); any other need belongs in
+ * db/queries/event-store*.ts.
+ *
+ * Usage:
+ *   bun packages/guards/src/guard-event-store-writes.ts
+ */
+
+import { type SourceFile, SyntaxKind } from "ts-morph";
+import {
+  type AstGuard,
+  type GuardViolation,
+  relFromRepoRoot,
+  runStandalone,
+  type ScanSpec,
+} from "./_lib/guard-kit";
+import { type RepoRoot, resolveRepoRoots } from "./_lib/roots";
+
+const SCAN: ScanSpec = { scope: "source", extensions: ["ts"] };
+
+// Tests fabricate their own fixture rows directly — they are the primary
+// verifiers of the event-store primitives, not a write surface this guard
+// needs to police.
+const EXCLUDE = /(__tests__|\.test\.ts$|\.integration\.ts$|\.d\.ts$)/;
+
+// Files allowed to write these three tables directly:
+//   - event-store/** — the primitive's own home (transfer.ts, event-store.ts,
+//     snapshot.ts, archive.ts, admin-api.ts, rebuild-dead-letter.ts, ...).
+//   - db/queries/event-store*.ts — the raw-SQL backing queries the primitives
+//     call (event-store.ts, event-store-admin.ts, event-store-transfer.ts).
+//   - db/queries/backfill-pii.ts — the one-time pre-KMS plaintext backfill;
+//     rewrites payload/deletes stale snapshots in place, framework-owned.
+//   - user/db/queries/stream-tenant-backfill.ts — a one-time stream-ownership
+//     migration that predates this guard; already carries its own
+//     RAW_SQL_ALLOWLIST entry, kept here for the same reason.
+const ALLOWLIST: readonly RegExp[] = [
+  /^packages\/framework\/src\/event-store\//,
+  /^packages\/framework\/src\/db\/queries\/event-store.*\.ts$/,
+  /^packages\/framework\/src\/db\/queries\/backfill-pii\.ts$/,
+  /^packages\/bundled-features\/src\/user\/db\/queries\/stream-tenant-backfill\.ts$/,
+];
+
+const ES_TABLES = "kumiko_events|kumiko_snapshots|kumiko_archived_streams";
+// One string/template literal must carry both the write verb AND the table
+// name — a keyword in one concatenated piece and the table name (behind a
+// variable) in another is indirection this guard does not see through; the
+// event store's own queries are the only place that literal belongs.
+const WRITE_RE = new RegExp(
+  `\\b(UPDATE|DELETE\\s+FROM|INSERT\\s+INTO)\\b[\\s\\S]*?["'\`]?(${ES_TABLES})["'\`]?`,
+  "i",
+);
+
+const LITERAL_KINDS = [
+  SyntaxKind.StringLiteral,
+  SyntaxKind.NoSubstitutionTemplateLiteral,
+  SyntaxKind.TemplateExpression,
+];
+
+export type Violation = {
+  readonly file: string;
+  readonly line: number;
+  readonly snippet: string;
+};
+
+export function isAllowed(relativePath: string): boolean {
+  return ALLOWLIST.some((re) => re.test(relativePath));
+}
+
+export function collectViolations(
+  sourceFile: SourceFile,
+  roots: readonly RepoRoot[] = resolveRepoRoots(),
+): Violation[] {
+  const violations: Violation[] = [];
+  // Repo-root-relative, not `process.cwd()`-relative — a multi-repo runner
+  // (e.g. invoked from the parent workspace dir) would otherwise carry a
+  // leading `kumiko-framework/` segment that the ALLOWLIST regexes (anchored
+  // on `^packages/...`) never match, wrongly flagging every allowed file.
+  const relativePath = relFromRepoRoot(sourceFile.getFilePath(), roots);
+  if (isAllowed(relativePath)) return violations;
+
+  for (const kind of LITERAL_KINDS) {
+    for (const node of sourceFile.getDescendantsOfKind(kind)) {
+      const text = node.getText();
+      const match = WRITE_RE.exec(text);
+      if (!match) continue;
+      violations.push({
+        file: relativePath,
+        line: node.getStartLineNumber(),
+        snippet: match[0].replace(/\s+/g, " ").trim().slice(0, 120),
+      });
+    }
+  }
+  return violations;
+}
+
+export const guard: AstGuard = {
+  name: "Event-Store-Writes Guard",
+  scan: SCAN,
+  hint:
+    "kumiko_events/kumiko_snapshots/kumiko_archived_streams may only be written from " +
+    "packages/framework/src/event-store/** and their db/queries/event-store*.ts backing. " +
+    "Use transferAggregateStreams (event-store/transfer.ts) for a tenant move, or add a " +
+    "new event-store primitive instead of writing these tables from feature code.",
+  run(files, roots: readonly RepoRoot[] = resolveRepoRoots()) {
+    const violations: GuardViolation[] = [];
+    for (const sf of files) {
+      if (EXCLUDE.test(sf.getFilePath())) continue;
+      for (const v of collectViolations(sf, roots)) {
+        violations.push({ file: v.file, line: v.line, message: v.snippet });
+      }
+    }
+    return { violations };
+  },
+};
+
+if (import.meta.main) runStandalone(guard);

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

@@ -126,6 +126,11 @@ const ALLOWLIST: readonly AllowEntry[] = [
   { repo: "kumiko-enterprise", pattern: /^packages\/publish\/src\/build\.ts$/ },
   { repo: "kumiko-enterprise", pattern: /^packages\/publish\/src\/feature\.ts$/ },
   { repo: "kumiko-enterprise", pattern: /^packages\/publish\/src\/validate\.ts$/ },
+
+  // testing: `kumiko-testing integration` CLI resolves positional test-file
+  // args against the developer's cwd, local dev/CI tooling reading paths
+  // the developer typed — no server request input.
+  { repo: "kumiko-framework", pattern: /^packages\/testing\/src\/integration-runner\.ts$/ },
 ];
 
 export function isRepoAllowlisted(

package/src/pre-push.sh

@@ -86,6 +86,37 @@ if git -C "$REPO_ROOT" ls-files --error-unmatch scripts/pre-push-extra.sh >/dev/
   (cd "$REPO_ROOT" && KUMIKO_PUSH_REPO_ROOT="$REPO_ROOT" KUMIKO_PUSH_PARENT_DIR="$PARENT_DIR" "$REPO_ROOT/scripts/pre-push-extra.sh" "$@") || exit 1
 fi
 
+# Upgrade-state guard: a repo that has adopted the `.kumiko/upgrade-state.json`
+# marker must not push with it stale. Installed as a bin, `$0` here is the
+# node_modules/.bin symlink, not this file's real path — resolve the symlink
+# chain so guard-upgrade-state.ts is found next to the real script, not $0.
+resolve_script_dir() {
+  SOURCE="$1"
+  while [ -h "$SOURCE" ]; do
+    DIR="$(cd -P "$(dirname "$SOURCE")" >/dev/null 2>&1 && pwd)"
+    SOURCE="$(readlink "$SOURCE")"
+    case "$SOURCE" in
+      /*) ;;
+      *) SOURCE="$DIR/$SOURCE" ;;
+    esac
+  done
+  cd -P "$(dirname "$SOURCE")" >/dev/null 2>&1 && pwd
+}
+
+if [ -f "$REPO_ROOT/.kumiko/upgrade-state.json" ]; then
+  SCRIPT_DIR="$(resolve_script_dir "$0")"
+  GUARD_UPGRADE_STATE="$SCRIPT_DIR/guard-upgrade-state.ts"
+  if [ ! -f "$GUARD_UPGRADE_STATE" ]; then
+    echo "[pre-push] FATAL: guard-upgrade-state.ts not found next to resolved script location '$SCRIPT_DIR' — refusing push" >&2
+    exit 1
+  fi
+  echo "[pre-push] .kumiko/upgrade-state.json present — running upgrade-state guard…"
+  if ! (cd "$REPO_ROOT" && bun "$GUARD_UPGRADE_STATE"); then
+    echo "[pre-push] upgrade-state guard failed — refusing push" >&2
+    exit 1
+  fi
+fi
+
 # infra#559/#569: from a worktree, `--git-common-dir` resolves to the main
 # checkout's .git, so the branch below would scope `bun check` to the
 # canonical sibling path instead of this worktree — checking the wrong

package/src/run-guards.ts

@@ -31,6 +31,7 @@ import { guard as directEntityWrites } from "./guard-direct-entity-writes";
 import { guard as directFetch } from "./guard-direct-fetch";
 import { guard as errorReasons } from "./guard-error-reasons";
 import { guard as escapeHatchDeclared } from "./guard-escape-hatch-declared";
+import { guard as eventStoreWrites } from "./guard-event-store-writes";
 import { guard as fakeTests } from "./guard-fake-tests";
 import { guard as htmlEscape } from "./guard-html-escape";
 import { guard as i18nKeys } from "./guard-i18n-keys";
@@ -88,6 +89,7 @@ export const GUARDS = [
   writeHandlerQns,
   asCasts,
   loadallEvents,
+  eventStoreWrites,
   tableDdl,
   appFeatureStructure,
   libTestCoverage,