@cosmicdrift/kumiko-guards 0.1.0

package/LICENSE

@@ -0,0 +1,57 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             Marc Frost
+
+Licensed Work:        @cosmicdrift/kumiko-guards
+                      The Licensed Work is © 2026 Marc Frost.
+
+Additional Use Grant: 
+You may use the Licensed Work in production for any purpose, including 
+commercially, EXCEPT for the Restricted Use. 
+
+"Restricted Use" is defined as using the Licensed Work to provide a platform 
+or service to third parties that allows them to host, deploy, or run their 
+own applications built with the Licensed Work. This includes, but is not 
+limited to: managed hosting services, software-as-a-service (SaaS) platforms, 
+platform-as-a-service (PaaS), developer platforms, or any multi-tenant 
+managed offering of the Licensed Work.
+
+This restriction does not apply to the Licensor, any entity controlled by, 
+controlling, or under common control with the Licensor ("Affiliates"), or 
+contractors acting on their behalf. The Licensor remains free to use the 
+Licensed Work for any purpose, including for the operation of kumiko.rocks.
+
+Change Date:          2030-05-05
+Change License:       Apache License, Version 2.0
+
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative works, 
+redistribute, and make non-production use of the Licensed Work. The Licensor may 
+make an Additional Use Grant, above, permitting limited production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly 
+available distribution of the Licensed Work under this License, whichever comes 
+first, this License will convert to the Change License.
+
+This Business Source License governs use of the Licensed Work in all cases, except 
+as to any use that is explicitly granted in the Additional Use Grant above or 
+under the Change License after the Change Date.
+
+If your use of the Licensed Work does not comply with the requirements of this 
+License, you must cease use of the Licensed Work immediately.
+
+All copies of the Licensed Work, and all derivative works thereof, must include 
+this License.
+
+This License does not grant you any right, title, or interest in any trademark, 
+logo, or branding of the Licensor, except as required to comply with this License.
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN 
+“AS IS” BASIS. LICENSOR DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 
+WITHOUT LIMITATION WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, 
+TITLE, AND NON-INFRINGEMENT. IN NO EVENT WILL LICENSOR BE LIABLE FOR ANY DAMAGES 
+ARISING OUT OF OR RELATED TO THIS LICENSE OR THE USE OF THE LICENSED WORK.

package/README.md

@@ -0,0 +1,16 @@
+# @cosmicdrift/kumiko-guards
+
+AST-based security guards for a single Kumiko repo: direct filesystem
+access, direct fetch, direct entity writes, admin-API misuse, tenant
+escalation, undeclared escape hatches, `openToAll` without a reason, and
+missing access-denied tests. Every finding must clear the repo's own
+security baseline — there is no per-guard skip flag.
+
+```
+bun node_modules/@cosmicdrift/kumiko-guards/src/run-guards.ts [--explain|--write-security-baseline]
+```
+
+The baseline lives at `.kumiko-security-baseline.json` in the consumer
+repo's root. `--explain` prints the resolved repo and per-guard scan scope
+without running any guard; `--write-security-baseline` freezes current
+findings into the baseline file.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@cosmicdrift/kumiko-guards",
+  "version": "0.1.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>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CosmicDriftGameStudio/kumiko-framework.git",
+    "directory": "packages/guards"
+  },
+  "bugs": {
+    "url": "https://github.com/CosmicDriftGameStudio/kumiko-framework/issues"
+  },
+  "homepage": "https://kumiko.rocks",
+  "type": "module",
+  "kumiko": {
+    "runtime": "dev"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "@cosmicdrift/kumiko-repo-manifest": "0.1.0",
+    "ts-morph": "^28.0.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "!src/**/__tests__/**",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/_lib/baseline-compare.ts

@@ -0,0 +1,56 @@
+// Shared by baseline-ratchet guards (check-complexity, guard-pii-
+// annotations) and the security-baseline module: per-file current-vs-baseline
+// count diff. More than baseline is a regression; less is allowed but doesn't
+// auto-update the baseline.
+export interface BaselineRegression {
+  readonly file: string;
+  readonly baseline: number;
+  readonly current: number;
+}
+
+export function compareToBaseline(
+  current: Readonly<Record<string, number>>,
+  baseline: Readonly<Record<string, number>>,
+): {
+  regressions: BaselineRegression[];
+  reduced: number;
+  reductions: BaselineRegression[];
+} {
+  const regressions: BaselineRegression[] = [];
+  const reductions: BaselineRegression[] = [];
+  let reduced = 0;
+  for (const file of new Set([...Object.keys(current), ...Object.keys(baseline)])) {
+    const expected = baseline[file] ?? 0;
+    const actual = current[file] ?? 0;
+    if (actual > expected) {
+      regressions.push({ file, baseline: expected, current: actual });
+    } else if (actual < expected) {
+      reduced += expected - actual;
+      reductions.push({ file, baseline: expected, current: actual });
+    }
+  }
+  regressions.sort((a, b) => a.file.localeCompare(b.file));
+  reductions.sort((a, b) => a.file.localeCompare(b.file));
+  return { regressions, reduced, reductions };
+}
+
+// Shared by the import/symbol-restriction guards (guard-no-direct-fs,
+// guard-restricted-symbols): relativize an absolute file path against the
+// real repo root so ALLOWLIST/EXCLUDE regexes match a stable, anchored path
+// instead of an arbitrary substring. resolveRepoRoots() finds the repo the
+// path actually lives under; the marker-slice below is a fallback ONLY for
+// ts-morph's in-memory test filesystem, whose paths never match a real repo
+// root (e.g. "/packages/framework/src/x.ts" in a unit test). Unresolvable
+// paths throw — returning the absolute path re-opens ancestor-segment
+// EXCLUDE false-negatives (tools/bin matching above the repo root).
+export function findRepoRootFor<T extends { readonly absPath: string }>(
+  filePath: string,
+  roots: ReadonlyArray<T>,
+): T | undefined {
+  for (const root of roots) {
+    if (filePath === root.absPath || filePath.startsWith(`${root.absPath}/`)) {
+      return root;
+    }
+  }
+  return undefined;
+}

package/src/_lib/generic-reason.ts

@@ -0,0 +1,39 @@
+import { type Node, SyntaxKind } from "ts-morph";
+
+const GENERIC_REASONS = new Set([
+  "",
+  "todo",
+  "tbd",
+  "fixme",
+  "legacy",
+  "temp",
+  "temporary",
+  "hack",
+  "wip",
+  "n/a",
+  "na",
+  "none",
+  "-",
+  "?",
+  "reason",
+  "xxx",
+]);
+
+const GENERIC_PREFIXES = ["todo:", "fixme:", "tbd:"];
+
+// undefined = not statically judgeable (template with substitutions, identifier, call), not "generic".
+export function literalReasonText(node: Node | undefined): string | undefined {
+  if (!node) return undefined;
+  if (node.isKind(SyntaxKind.StringLiteral)) return node.getLiteralValue();
+  if (node.isKind(SyntaxKind.NoSubstitutionTemplateLiteral)) return node.getLiteralValue();
+  return undefined;
+}
+
+export function isGenericReason(text: string): boolean {
+  const lowered = text.trim().toLowerCase();
+  if (GENERIC_PREFIXES.some((prefix) => lowered.startsWith(prefix))) {
+    return true;
+  }
+  const stripped = lowered.replace(/[.!:;,]+$/, "").trim();
+  return GENERIC_REASONS.has(stripped);
+}