@cosmicdrift/kumiko-guards 0.413.1 → 0.415.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. package/README.md +15 -9
  2. package/package.json +4 -4
  3. package/src/_lib/agent-docs-api-nodes.ts +9 -2
  4. package/src/_lib/agent-docs-api-render.ts +31 -10
  5. package/src/_lib/agent-docs-api.ts +13 -9
  6. package/src/_lib/agent-docs-feature-imports.ts +12 -1
  7. package/src/_lib/baseline-compare.ts +1 -2
  8. package/src/_lib/doc-status.ts +8 -4
  9. package/src/_lib/dockerfile.ts +28 -5
  10. package/src/_lib/escaped-literal.ts +26 -0
  11. package/src/_lib/npm-registry.ts +2 -2
  12. package/src/_lib/run-slots.ts +4 -6
  13. package/src/_lib/security-audit.ts +22 -6
  14. package/src/_lib/test-es-raw-writes.ts +5 -3
  15. package/src/changes.json +51 -0
  16. package/src/check-security.ts +4 -3
  17. package/src/guard-app-dockerfile.ts +29 -12
  18. package/src/guard-ignore-tag-reason.ts +18 -4
  19. package/src/guard-internal-subpath-imports.ts +35 -25
  20. package/src/guard-rls-session-settings.ts +48 -6
  21. package/src/guard-schema-cli-features.ts +22 -1
  22. package/src/guard-security-plugin-suppression.ts +368 -0
  23. package/src/guard-test-es-row-writes.ts +2 -1
  24. package/src/guard-unsafe-array-param.ts +4 -7
  25. package/src/pre-push.sh +46 -6
  26. package/src/run-guards.ts +2 -28
  27. package/src/run-repo-checks.ts +0 -6
  28. package/src/run-steps-parallel.ts +4 -4
  29. package/src/run-ui-guards.ts +1 -15
  30. package/src/_lib/german-test-title.ts +0 -94
  31. package/src/_lib/primitives-access.ts +0 -23
  32. package/src/check-predicates.ts +0 -244
  33. package/src/guard-admin-api.ts +0 -138
  34. package/src/guard-direct-fetch.ts +0 -161
  35. package/src/guard-error-reasons.ts +0 -210
  36. package/src/guard-event-store-writes.ts +0 -124
  37. package/src/guard-i18n-locale-terminology.ts +0 -134
  38. package/src/guard-no-custom-primitives.ts +0 -193
  39. package/src/guard-no-date-api.ts +0 -183
  40. package/src/guard-no-direct-fs.ts +0 -346
  41. package/src/guard-no-direct-process-env.ts +0 -127
  42. package/src/guard-no-inline-styles.ts +0 -64
  43. package/src/guard-no-raw-hooks.ts +0 -80
  44. package/src/guard-no-temporal-polyfill-import.ts +0 -131
  45. package/src/guard-primitives-discipline.ts +0 -357
  46. package/src/guard-raw-classname.ts +0 -117
  47. package/src/guard-raw-interactive-elements.ts +0 -164
  48. package/src/guard-restricted-symbols.ts +0 -155
  49. package/src/guard-silent-skip.ts +0 -186
  50. package/src/guard-test-es-fixtures.ts +0 -85
  51. package/src/guard-test-title.ts +0 -159
  52. package/src/guard-thin-wrappers.ts +0 -471
  53. package/src/guard-unsafe-json-parse.ts +0 -87
package/README.md CHANGED
@@ -1,10 +1,12 @@
1
1
  # @cosmicdrift/kumiko-guards
2
2
 
3
- AST-based security guards for a single Kumiko repo: direct filesystem
4
- access, direct fetch, direct entity writes, admin-API misuse, tenant
5
- escalation, undeclared escape hatches, `openToAll` without a reason, and
6
- missing access-denied tests. Every finding must clear the repo's own
7
- security baseline — there is no per-guard skip flag.
3
+ AST guards and repo checks for a single Kumiko repo that need more than one
4
+ file: direct entity writes, tenant escalation, undeclared escape hatches,
5
+ `openToAll` without a reason, missing access-denied tests and the repo checks.
6
+ Single-file checks (direct fs/fetch, date API, test titles, raw HTML, ...) live in
7
+ the Biome preset `@cosmicdrift/kumiko-framework/biome-rules` as builtins and
8
+ GritQL plugins. Every finding must clear the repo's own security baseline;
9
+ there is no per-guard skip flag.
8
10
 
9
11
  ```
10
12
  bun node_modules/@cosmicdrift/kumiko-guards/src/run-guards.ts [--explain|--write-security-baseline]
@@ -81,10 +83,14 @@ worktree's own `package.json` scripts `typecheck`, `lint`, `test`, and
81
83
  as in `kumiko check`), `checks`, `comment-lang` and `public-exports-changelog`.
82
84
  The repo that ships this package runs its checked-out `packages/guards/src/cli.ts`
83
85
  for these. There is no bypass switch. A `check-wt.sh` that wraps this hook (via
84
- `exec` or as a child process) is recognised by process ancestry, so the hook
85
- does not call it again and skips the pre-flight steps (`pre-push-extra.sh`,
86
- upgrade-state guard, gitleaks) the outer run already did; an exported variable
87
- cannot skip either.
86
+ `exec` or as a child process) is recognised, so the hook does not call it again
87
+ and skips the pre-flight steps (`pre-push-extra.sh`, upgrade-state guard,
88
+ gitleaks) the outer run already did. Recognition needs the recorded owner PID
89
+ (`KUMIKO_CHECK_WT_OWNER`) to be this process or an ancestor running
90
+ `scripts/check-wt.sh`, and a random `KUMIKO_CHECK_WT_NONCE` that matches the
91
+ 0600 file `kumiko-prepush-<pid>` in the git common dir. Setting the variables by
92
+ hand (`KUMIKO_CHECK_WT_OWNER=$$ git push`) therefore skips nothing; the files of
93
+ finished runs are swept by the next push.
88
94
 
89
95
  Extension point: a tracked, executable `scripts/pre-push-extra.sh` runs
90
96
  before the main check in every branch (worktree, parent-scoped, and
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cosmicdrift/kumiko-guards",
3
- "version": "0.413.1",
3
+ "version": "0.415.0",
4
4
  "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.",
5
5
  "license": "MIT",
6
6
  "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -36,7 +36,7 @@
36
36
  "kumiko-pre-push": "./src/pre-push.sh"
37
37
  },
38
38
  "dependencies": {
39
- "@cosmicdrift/kumiko-types": "0.413.1",
39
+ "@cosmicdrift/kumiko-types": "0.415.0",
40
40
  "ts-morph": "^28.0.0",
41
41
  "zod": "^4.6.7"
42
42
  },
@@ -52,7 +52,7 @@
52
52
  "LICENSE"
53
53
  ],
54
54
  "peerDependencies": {
55
- "@cosmicdrift/kumiko-framework": "0.413.1"
55
+ "@cosmicdrift/kumiko-framework": "0.415.0"
56
56
  },
57
57
  "peerDependenciesMeta": {
58
58
  "@cosmicdrift/kumiko-framework": {
@@ -60,6 +60,6 @@
60
60
  }
61
61
  },
62
62
  "devDependencies": {
63
- "@cosmicdrift/kumiko-framework": "0.413.1"
63
+ "@cosmicdrift/kumiko-framework": "0.415.0"
64
64
  }
65
65
  }
@@ -45,8 +45,12 @@ export function isPublicClassMember(member: Node): boolean {
45
45
  )
46
46
  return false;
47
47
  return (
48
- !(Node.isPropertyDeclaration(member) || Node.isMethodDeclaration(member)) ||
49
- !member.getName().startsWith("#")
48
+ !(
49
+ Node.isPropertyDeclaration(member) ||
50
+ Node.isMethodDeclaration(member) ||
51
+ Node.isGetAccessorDeclaration(member) ||
52
+ Node.isSetAccessorDeclaration(member)
53
+ ) || !member.getName().startsWith("#")
50
54
  );
51
55
  }
52
56
 
@@ -83,6 +87,9 @@ function classTypeRoots(node: ClassDeclaration): Node[] {
83
87
  if (Node.isMethodDeclaration(member) || Node.isConstructorDeclaration(member)) {
84
88
  roots.push(...member.getParameters(), ...presentNodes(member.getReturnTypeNode()));
85
89
  }
90
+ if (Node.isGetAccessorDeclaration(member))
91
+ roots.push(...presentNodes(member.getReturnTypeNode()));
92
+ if (Node.isSetAccessorDeclaration(member)) roots.push(...member.getParameters());
86
93
  }
87
94
  return roots;
88
95
  }
@@ -1,5 +1,6 @@
1
1
  import {
2
2
  type ClassDeclaration,
3
+ type ClassMemberTypes,
3
4
  type EnumDeclaration,
4
5
  type FunctionDeclaration,
5
6
  type InterfaceDeclaration,
@@ -173,6 +174,29 @@ function renderEnum(node: EnumDeclaration): string[] {
173
174
  return [`enum ${node.getName()} { ${members.join(", ")} }${docSuffix(node)}`];
174
175
  }
175
176
 
177
+ function renderClassMember(
178
+ member: ClassMemberTypes,
179
+ getterNames: ReadonlySet<string>,
180
+ ): string | undefined {
181
+ if (!isPublicClassMember(member)) return undefined;
182
+ const isStatic = Node.isStaticable(member) && member.isStatic() ? "static " : "";
183
+ const line = (name: string, text: string): string =>
184
+ `${INDENT}${isStatic}${name}: ${text};${docSuffix(member)}`;
185
+ if (Node.isPropertyDeclaration(member)) {
186
+ return line(member.getName(), typeText(member.getTypeNode(), 1, INDENT));
187
+ }
188
+ if (Node.isMethodDeclaration(member)) {
189
+ return `${INDENT}${isStatic}${member.getName()}${signatureText(member)};${docSuffix(member)}`;
190
+ }
191
+ if (Node.isGetAccessorDeclaration(member)) {
192
+ return line(member.getName(), typeText(member.getReturnTypeNode(), 1, INDENT));
193
+ }
194
+ if (Node.isSetAccessorDeclaration(member) && !getterNames.has(member.getName())) {
195
+ return line(member.getName(), typeText(member.getParameters()[0]?.getTypeNode(), 1, INDENT));
196
+ }
197
+ return undefined;
198
+ }
199
+
176
200
  function renderClass(node: ClassDeclaration): string[] {
177
201
  const base = node.getExtends();
178
202
  const extendsText = base === undefined ? "" : ` extends ${nodeText(base)}`;
@@ -183,17 +207,14 @@ function renderClass(node: ClassDeclaration): string[] {
183
207
  lines.push(`${INDENT}constructor(${ctor.getParameters().map(parameterText).join(", ")});`);
184
208
  }
185
209
  }
210
+ const getterNames = new Set(
211
+ node
212
+ .getMembers()
213
+ .flatMap((member) => (Node.isGetAccessorDeclaration(member) ? [member.getName()] : [])),
214
+ );
186
215
  for (const member of node.getMembers()) {
187
- if (!isPublicClassMember(member)) continue;
188
- const isStatic = Node.isStaticable(member) && member.isStatic() ? "static " : "";
189
- if (Node.isPropertyDeclaration(member)) {
190
- const text = typeText(member.getTypeNode(), 1, INDENT);
191
- lines.push(`${INDENT}${isStatic}${member.getName()}: ${text};${docSuffix(member)}`);
192
- } else if (Node.isMethodDeclaration(member)) {
193
- lines.push(
194
- `${INDENT}${isStatic}${member.getName()}${signatureText(member)};${docSuffix(member)}`,
195
- );
196
- }
216
+ const line = renderClassMember(member, getterNames);
217
+ if (line !== undefined) lines.push(line);
197
218
  }
198
219
  if (lines.length === 0) return [`${head} {}${docSuffix(node)}`];
199
220
  return [`${head} {${docSuffix(node)}`, ...lines, "}"];
@@ -1,6 +1,6 @@
1
1
  import { existsSync, readFileSync, realpathSync } from "node:fs";
2
2
  import { join, relative, sep } from "node:path";
3
- import { Node, type Project, type SourceFile } from "ts-morph";
3
+ import { Node, type Project, type SourceFile, type VariableDeclaration } from "ts-morph";
4
4
  import {
5
5
  type ApiTypeDeclaration,
6
6
  isApiTypeDeclaration,
@@ -131,23 +131,27 @@ function isInsideInternalMember(node: Node): boolean {
131
131
  .some((ancestor) => !isApiTypeDeclaration(ancestor) && isInternalApi(ancestor));
132
132
  }
133
133
 
134
+ type ReferencedDeclaration = ApiTypeDeclaration | VariableDeclaration;
135
+
134
136
  function referencedDeclarations(
135
137
  node: Node,
136
138
  isRepoSource: (file: SourceFile) => boolean,
137
- ): ApiTypeDeclaration[] {
138
- const found: ApiTypeDeclaration[] = [];
139
+ ): ReferencedDeclaration[] {
140
+ const found: ReferencedDeclaration[] = [];
139
141
  for (const reference of referencedTypeNodes(node)) {
140
142
  if (isInsideInternalMember(reference)) continue;
141
143
  const nameNode = Node.isTypeReference(reference)
142
144
  ? reference.getTypeName()
143
145
  : Node.isExpressionWithTypeArguments(reference)
144
146
  ? reference.getExpression()
145
- : undefined;
147
+ : Node.isTypeQuery(reference)
148
+ ? reference.getExprName()
149
+ : undefined;
146
150
  const symbol = nameNode?.getSymbol();
147
151
  const target = symbol?.getAliasedSymbol() ?? symbol;
148
152
  for (const declaration of target?.getDeclarations() ?? []) {
149
153
  if (
150
- isApiTypeDeclaration(declaration) &&
154
+ (isApiTypeDeclaration(declaration) || Node.isVariableDeclaration(declaration)) &&
151
155
  !isInternalApi(declaration) &&
152
156
  isRepoSource(declaration.getSourceFile())
153
157
  ) {
@@ -158,7 +162,7 @@ function referencedDeclarations(
158
162
  return found;
159
163
  }
160
164
 
161
- function declarationName(node: ApiTypeDeclaration): string {
165
+ function declarationName(node: ReferencedDeclaration): string {
162
166
  return node.getName() ?? "default";
163
167
  }
164
168
 
@@ -211,7 +215,7 @@ export function renderApiDocs(repoRoot: string, project: Project): ReadonlyMap<s
211
215
  files.set(entry.file, finishFile(entry.sourceRel, body));
212
216
  });
213
217
 
214
- const referenced = new Set<ApiTypeDeclaration>();
218
+ const referenced = new Set<ReferencedDeclaration>();
215
219
  while (pending.length > 0) {
216
220
  const node = pending.pop();
217
221
  if (node === undefined) break;
@@ -234,10 +238,10 @@ export function renderApiDocs(repoRoot: string, project: Project): ReadonlyMap<s
234
238
 
235
239
  function renderReferencedTypes(
236
240
  repoRoot: string,
237
- referenced: ReadonlySet<ApiTypeDeclaration>,
241
+ referenced: ReadonlySet<ReferencedDeclaration>,
238
242
  ): string {
239
243
  const root = realpathSync(repoRoot);
240
- const byModule = new Map<string, ApiTypeDeclaration[]>();
244
+ const byModule = new Map<string, ReferencedDeclaration[]>();
241
245
  for (const declaration of referenced) {
242
246
  const moduleRel = relative(root, realFilePath(declaration.getSourceFile()))
243
247
  .split(sep)
@@ -114,6 +114,11 @@ function exportEntries(repoRoot: string, project: Project, site: FeatureDefiniti
114
114
  return entries;
115
115
  }
116
116
 
117
+ const EQUALITY_OPERATORS: ReadonlySet<SyntaxKind> = new Set([
118
+ SyntaxKind.EqualsEqualsEqualsToken,
119
+ SyntaxKind.EqualsEqualsToken,
120
+ ]);
121
+
117
122
  // `options.<flag> === true ? <factory>() : …` inside an exported factory means
118
123
  // that factory with `{ <flag>: true }` builds the feature.
119
124
  function flagCall(name: string, fn: FunctionDeclaration, factoryName: string): string | undefined {
@@ -124,7 +129,13 @@ function flagCall(name: string, fn: FunctionDeclaration, factoryName: string): s
124
129
  if (!Node.isCallExpression(whenTrue) || whenTrue.getExpression().getText() !== factoryName) {
125
130
  continue;
126
131
  }
127
- if (!Node.isBinaryExpression(condition) || condition.getRight().getText() !== "true") continue;
132
+ if (
133
+ !Node.isBinaryExpression(condition) ||
134
+ condition.getRight().getText() !== "true" ||
135
+ !EQUALITY_OPERATORS.has(condition.getOperatorToken().getKind())
136
+ ) {
137
+ continue;
138
+ }
128
139
  const flag = condition.getLeft();
129
140
  if (Node.isPropertyAccessExpression(flag)) return `${name}({ ${flag.getName()}: true })`;
130
141
  }
@@ -34,8 +34,7 @@ export function compareToBaseline(
34
34
  return { regressions, reduced, reductions };
35
35
  }
36
36
 
37
- // Shared by the import/symbol-restriction guards (guard-no-direct-fs,
38
- // guard-restricted-symbols): relativize an absolute file path against the
37
+ // Shared by the path-allowlist guards: relativize an absolute file path against the
39
38
  // real repo root so ALLOWLIST/EXCLUDE regexes match a stable, anchored path
40
39
  // instead of an arbitrary substring. resolveRepoRoots() finds the repo the
41
40
  // path actually lives under; the marker-slice below is a fallback ONLY for
@@ -1,4 +1,4 @@
1
- import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
1
+ import { existsSync, readdirSync, readFileSync } from "node:fs";
2
2
  import { join, relative } from "node:path";
3
3
  import type { RepoRoot } from "./roots";
4
4
 
@@ -117,7 +117,8 @@ function statusDependentFieldProblems(status: string, fields: Map<string, string
117
117
  return problems;
118
118
  }
119
119
 
120
- export function parseStatusFrontmatter(content: string): ParsedFrontmatter {
120
+ export function parseStatusFrontmatter(rawContent: string): ParsedFrontmatter {
121
+ const content = rawContent.replace(/^\uFEFF/, "").replace(/\r\n/g, "\n");
121
122
  if (!content.startsWith("---\n"))
122
123
  return invalid("no status frontmatter (file must start with '---')");
123
124
  const end = content.indexOf("\n---", 4);
@@ -174,7 +175,10 @@ export function statusDocHygieneWarnings(doc: StatusDoc): readonly string[] {
174
175
  }
175
176
 
176
177
  function collectMarkdownFiles(dir: string, walkRoot: string, out: string[]): void {
177
- for (const name of readdirSync(dir)) {
178
+ for (const entry of readdirSync(dir, { withFileTypes: true })) {
179
+ // A symlink to a parent directory would recurse forever.
180
+ if (entry.isSymbolicLink()) continue;
181
+ const name = entry.name;
178
182
  const abs = join(dir, name);
179
183
  // Segments below the walk root only: a checkout under ~/marketing/ must not hide every doc.
180
184
  if (
@@ -184,7 +188,7 @@ function collectMarkdownFiles(dir: string, walkRoot: string, out: string[]): voi
184
188
  ) {
185
189
  continue;
186
190
  }
187
- if (statSync(abs).isDirectory()) collectMarkdownFiles(abs, walkRoot, out);
191
+ if (entry.isDirectory()) collectMarkdownFiles(abs, walkRoot, out);
188
192
  else if (name.endsWith(".md")) out.push(abs);
189
193
  }
190
194
  }
@@ -3,25 +3,40 @@ export type DockerStage = { readonly lines: readonly string[] };
3
3
  export const NPM_AUTH_SECRET_ID = "npm_auth_token";
4
4
 
5
5
  const FROM_RE = /^\s*FROM\s/i;
6
- const BUN_INSTALL_RE = /^\s*RUN\s+.*\bbun\s+install\b/;
6
+ const BUN_INSTALL_RE = /^\s*RUN\s+.*\bbun\s+(?:install|i)\b/;
7
+ const RUN_RE = /^\s*RUN\s/i;
8
+ const HEREDOC_START_RE = /(?<![<$(])<<(?!<)[-~]?\s*(["']?)([A-Za-z_][A-Za-z0-9_]*)\1/;
7
9
  const COPY_FROM_RE = /^\s*COPY\s+--from=/;
8
10
  const COPY_RE = /^\s*COPY\s+/;
9
11
  const COPY_CONTEXT_RE = /^\s*COPY\s+(?:--\S+\s+)*\.\/?\s+\S+\s*$/;
10
12
  const LEGACY_TOKEN_ARG_RE = /^\s*ARG\s+(\S+\s+)*NPM_AUTH_TOKEN(\s*=.*)?\s*$/;
11
13
  const LEGACY_TOKEN_ENV_RE = /^\s*ENV\s+.*\bNPM_AUTH_TOKEN\b/;
12
14
 
13
- // Docker line continuations (`\` at EOL) merged so a multi-line RUN/COPY
14
- // still matches as one logical instruction.
15
+ // Docker line continuations (`\` at EOL) and RUN heredoc bodies merged so a
16
+ // multi-line RUN/COPY still matches as one logical instruction.
15
17
  export function joinContinuations(dockerfileText: string): string[] {
16
18
  const out: string[] = [];
17
19
  let buffer = "";
20
+ let heredocEnd: string | undefined;
18
21
  for (const raw of dockerfileText.split("\n")) {
19
22
  const line = raw.replace(/\r$/, "");
23
+ if (heredocEnd !== undefined) {
24
+ if (line.trim() === heredocEnd) {
25
+ heredocEnd = undefined;
26
+ out.push(buffer);
27
+ buffer = "";
28
+ } else {
29
+ buffer = `${buffer} ${line}`;
30
+ }
31
+ continue;
32
+ }
20
33
  buffer = buffer.length > 0 ? `${buffer} ${line}` : line;
21
34
  if (/\\\s*$/.test(line)) {
22
35
  buffer = buffer.replace(/\\\s*$/, "");
23
36
  continue;
24
37
  }
38
+ heredocEnd = RUN_RE.test(buffer) ? HEREDOC_START_RE.exec(buffer)?.[2] : undefined;
39
+ if (heredocEnd !== undefined) continue;
25
40
  out.push(buffer);
26
41
  buffer = "";
27
42
  }
@@ -84,15 +99,23 @@ export function declaresLegacyTokenArg(line: string): boolean {
84
99
 
85
100
  // A mount that only lands at /run/secrets passes BuildKit but 401s in the
86
101
  // install: the RUN must expose the secret under a variable the registry
87
- // config reads, via the mount's `env=` option or an inline assignment.
102
+ // config reads, via the mount's `env=` option or an inline assignment that
103
+ // reads the mounted file (an unrelated `VAR=dummy` leaves the token unset).
88
104
  export function mountsNpmAuthSecret(line: string, tokenVariables: ReadonlySet<string>): boolean {
89
105
  return [...line.matchAll(/--mount=(\S+)/g)].some((match) => {
90
106
  const options = (match[1] ?? "").split(",");
91
107
  if (!options.includes("type=secret") || !options.includes(`id=${NPM_AUTH_SECRET_ID}`)) {
92
108
  return false;
93
109
  }
110
+ const mountedPath =
111
+ options.find((option) => option.startsWith("target="))?.slice("target=".length) ??
112
+ `/run/secrets/${NPM_AUTH_SECRET_ID}`;
113
+ const readsMountedFile = (variable: string) =>
114
+ new RegExp(`\\b${variable}=["']?\\$\\(\\s*cat\\s+${escapeRegExp(mountedPath)}\\s*\\)`).test(
115
+ line,
116
+ );
94
117
  return [...tokenVariables].some(
95
- (variable) => options.includes(`env=${variable}`) || new RegExp(`\\b${variable}=`).test(line),
118
+ (variable) => options.includes(`env=${variable}`) || readsMountedFile(variable),
96
119
  );
97
120
  });
98
121
  }
@@ -0,0 +1,26 @@
1
+ import { Node } from "ts-morph";
2
+
3
+ const BACKSLASH_RE = /\\/;
4
+
5
+ // Text prefilters search raw file text, which any string-literal escape (`\_`, `\x20`, octal,
6
+ // backslash-newline continuation) can spell around; such files must still go through the AST check.
7
+ export function mayContainEscapedLiteral(text: string): boolean {
8
+ return BACKSLASH_RE.test(text);
9
+ }
10
+
11
+ // Source text of a string-like literal with escapes resolved, so `"set_config"` matches
12
+ // what the runtime sees. Literals without escapes keep their raw text (quotes included).
13
+ export function decodedLiteralText(node: Node): string {
14
+ const raw = node.getText();
15
+ if (!mayContainEscapedLiteral(raw)) return raw;
16
+ if (Node.isStringLiteral(node) || Node.isNoSubstitutionTemplateLiteral(node)) {
17
+ return node.getLiteralText();
18
+ }
19
+ if (Node.isTemplateExpression(node)) {
20
+ const spans = node
21
+ .getTemplateSpans()
22
+ .map((span) => `\${${span.getExpression().getText()}}${span.getLiteral().getLiteralText()}`);
23
+ return [node.getHead().getLiteralText(), ...spans].join("");
24
+ }
25
+ return raw;
26
+ }
@@ -92,14 +92,14 @@ export function memoizeRegistryClient(client: RegistryClient): RegistryClient {
92
92
  deprecation(name, version) {
93
93
  const key = `${name}@${version}`;
94
94
  const cached = deprecation.get(key);
95
- if (cached) return cached;
95
+ if (cached !== undefined) return cached;
96
96
  const pending = client.deprecation(name, version);
97
97
  deprecation.set(key, pending);
98
98
  return pending;
99
99
  },
100
100
  latestRelease(name) {
101
101
  const cached = latest.get(name);
102
- if (cached) return cached;
102
+ if (cached !== undefined) return cached;
103
103
  const pending = client.latestRelease(name);
104
104
  latest.set(name, pending);
105
105
  return pending;
@@ -1,4 +1,5 @@
1
1
  import {
2
+ chmodSync,
2
3
  lstatSync,
3
4
  mkdirSync,
4
5
  readFileSync,
@@ -164,16 +165,13 @@ function assertPrivateOwnDirectory(dir: string): void {
164
165
  // skip: no uid to compare against on this platform.
165
166
  if (uid === undefined) return;
166
167
  const stats = lstatSync(dir);
167
- if (
168
- stats.isSymbolicLink() ||
169
- !stats.isDirectory() ||
170
- stats.uid !== uid ||
171
- (stats.mode & 0o077) !== 0
172
- ) {
168
+ if (stats.isSymbolicLink() || !stats.isDirectory() || stats.uid !== uid) {
173
169
  throw Object.assign(new Error(`${dir} is not a private directory owned by the current user`), {
174
170
  code: "EUNSAFE",
175
171
  });
176
172
  }
173
+ // mkdir's mode is ignored for an existing dir; older versions created it 0755 under umask 022.
174
+ if ((stats.mode & 0o077) !== 0) chmodSync(dir, 0o700);
177
175
  }
178
176
 
179
177
  export function acquireGuardRunSlot(options: GuardRunSlotOptions = {}): () => void {
@@ -41,6 +41,7 @@ export type SecurityEvaluation = {
41
41
  readonly warnings: AuditAdvisory[];
42
42
  readonly suppressed: AuditAdvisory[];
43
43
  readonly usedExceptions: SecurityException[];
44
+ readonly matchedExceptions: SecurityException[];
44
45
  readonly counts: Record<Severity, number>;
45
46
  };
46
47
 
@@ -93,16 +94,21 @@ function matchesAdvisory(exceptionAdvisory: string, advisoryId: string, url: str
93
94
  return url.includes(exceptionAdvisory);
94
95
  }
95
96
 
96
- function findSecurityException(
97
+ function matchingSecurityExceptions(
97
98
  advisory: AuditAdvisory,
98
99
  exceptions: readonly SecurityException[],
99
- nowMs: number,
100
- ): SecurityException | undefined {
101
- const matching = exceptions.filter(
100
+ ): SecurityException[] {
101
+ return exceptions.filter(
102
102
  (ex) =>
103
103
  matchesAdvisory(ex.advisory, advisory.advisoryId, advisory.url) &&
104
104
  (ex.package === "*" || matchesPackageName(ex.package, advisory.package)),
105
105
  );
106
+ }
107
+
108
+ function findSecurityException(
109
+ matching: readonly SecurityException[],
110
+ nowMs: number,
111
+ ): SecurityException | undefined {
106
112
  // An expired earlier entry (e.g. bundled) must not shadow a valid later one (e.g. repo-level).
107
113
  return matching.find((ex) => isSecurityExceptionActive(ex, nowMs)) ?? matching[0];
108
114
  }
@@ -122,10 +128,13 @@ export function evaluateSecurity(
122
128
  const warnings: AuditAdvisory[] = [];
123
129
  const suppressed: AuditAdvisory[] = [];
124
130
  const usedExceptions = new Set<SecurityException>();
131
+ const matchedExceptions = new Set<SecurityException>();
125
132
 
126
133
  for (const advisory of advisories) {
127
134
  counts[advisory.severity] += 1;
128
- const exception = findSecurityException(advisory, exceptions, nowMs);
135
+ const matching = matchingSecurityExceptions(advisory, exceptions);
136
+ for (const ex of matching) matchedExceptions.add(ex);
137
+ const exception = findSecurityException(matching, nowMs);
129
138
  const covered = exception !== undefined && isSecurityExceptionActive(exception, nowMs);
130
139
 
131
140
  if (covered) {
@@ -138,7 +147,14 @@ export function evaluateSecurity(
138
147
  }
139
148
  }
140
149
 
141
- return { blocking, warnings, suppressed, usedExceptions: [...usedExceptions], counts };
150
+ return {
151
+ blocking,
152
+ warnings,
153
+ suppressed,
154
+ usedExceptions: [...usedExceptions],
155
+ matchedExceptions: [...matchedExceptions],
156
+ counts,
157
+ };
142
158
  }
143
159
 
144
160
  /** True when `bytes` starts with the gzip magic header (1f 8b). */
@@ -4,6 +4,7 @@
4
4
  // template SQL stay invisible.
5
5
  import type { SourceFile } from "ts-morph";
6
6
  import { Node, SyntaxKind } from "ts-morph";
7
+ import { decodedLiteralText, mayContainEscapedLiteral } from "./escaped-literal";
7
8
 
8
9
  export type RawWriteFinding = { readonly line: number; readonly message: string };
9
10
 
@@ -16,7 +17,7 @@ export const RAW_SQL_MESSAGE =
16
17
  "raw DELETE/UPDATE on an event-sourced table in a test: reset with resetTestTables(db, [table, eventsTable]), " +
17
18
  "change rows through the real command or updateRowViaEventStore/deleteRowViaEventStore";
18
19
 
19
- // kumiko_events UPDATEs are reported by the test-es-fixtures guard already.
20
+ // kumiko_events UPDATEs are reported by the es-literal-writes-tests Biome plugin already.
20
21
  const LITERAL_WRITE_RE =
21
22
  /\b(?:DELETE\s+FROM\s+"?(?:read_\w+|kumiko_events)|UPDATE\s+"?read_\w+)\b/i;
22
23
  const TEMPLATE_WRITE_RE = /\b(?:DELETE\s+FROM|UPDATE)\s+"?\$\{\s*(\w+)(?:\.tableName)?\s*\}/gi;
@@ -46,7 +47,7 @@ function isEventSourcedBinding(name: string, entityTables: ReadonlySet<string>):
46
47
  }
47
48
 
48
49
  function writesEventSourcedTable(node: Node, entityTables: ReadonlySet<string>): boolean {
49
- const text = node.getText();
50
+ const text = decodedLiteralText(node);
50
51
  if (LITERAL_WRITE_RE.test(text)) return true;
51
52
  if (!Node.isTemplateExpression(node)) return false;
52
53
  for (const match of text.matchAll(TEMPLATE_WRITE_RE)) {
@@ -57,7 +58,8 @@ function writesEventSourcedTable(node: Node, entityTables: ReadonlySet<string>):
57
58
 
58
59
  export function findRawSqlWrites(sourceFile: SourceFile): RawWriteFinding[] {
59
60
  const findings: RawWriteFinding[] = [];
60
- if (!SQL_WRITE_START_RE.test(sourceFile.getFullText())) return findings;
61
+ const text = sourceFile.getFullText();
62
+ if (!SQL_WRITE_START_RE.test(text) && !mayContainEscapedLiteral(text)) return findings;
61
63
  const entityTables = entityTableBindings(sourceFile);
62
64
  for (const kind of [
63
65
  SyntaxKind.StringLiteral,
package/src/changes.json CHANGED
@@ -1,4 +1,55 @@
1
1
  [
2
+ {
3
+ "version": "0.415.0",
4
+ "type": "breaking",
5
+ "title": "security-plugin-suppression guard rejects biome-ignore on the security Biome plugins",
6
+ "detail": "`biome-ignore lint/plugin` covers every plugin, so a reason of three words silenced the SSRF (`no-direct-fetch`), path-traversal (`no-direct-fs`), event-store write (`es-literal-writes`, `es-literal-writes-tests`, `restricted-event-store-symbols`) and `admin-api` checks. The new guard `security-plugin-suppression` re-runs Biome over every file with such a comment, in a temp copy with those comments neutralised and only the security plugins from the preset enabled. Each remaining diagnostic is a finding. UI plugins (raw-ui, raw-hooks, ...) and browser-side fetch in `web/**/*.tsx` stay suppressible. A Biome answer that cannot be parsed fails the guard. The guard needs `@biomejs/biome` and the `biome-rules` preset in the repo and does nothing without them.",
7
+ "migration": "Replace each suppressed call with the safe API (`egress(policy)` instead of `fetch`, `FileStorageProvider` or `readBundledAsset` instead of `node:fs`, the event-store API instead of literal writes). A reviewed exception that cannot move is frozen once with `kumiko-guards guards --write-baseline --guard=security-plugin-suppression` into `.kumiko-security-plugin-suppression-baseline.json`; without that file the guard fails closed."
8
+ },
9
+ {
10
+ "version": "0.414.0",
11
+ "type": "fix",
12
+ "title": "Error-Reasons guard accepts a prose reason in subjectForgetAfterDeleteHook",
13
+ "detail": "The reason is the forget-subject audit reason and part of the hook's systemIdentity escape-hatch reason, not an error-reason code. Apps no longer need a constant to get past the guard."
14
+ },
15
+ {
16
+ "version": "0.414.0",
17
+ "type": "breaking",
18
+ "title": "Single-file guards are replaced by the Biome preset biome-rules",
19
+ "detail": "The guards admin-api, direct-fetch, error-reasons, event-store-writes (es-literal-writes), i18n-locale-terminology, no-custom-primitives, no-date-api, no-direct-fs, no-direct-process-env, no-inline-styles, no-raw-hooks, no-temporal-polyfill-import, primitives-discipline, raw-classname, raw-interactive-elements, restricted-symbols, test-es-fixtures, test-title and unsafe-json-parse are deleted together with their baselines. Their checks run as Biome builtins or GritQL plugins from `packages/framework/presets/biome-plugins/*.grit`. New checks cover createTestDispatcher, barrel imports from the same folder, external font CDNs (also in CSS), skipped or retried tests and CSSProperties types. The guards silent-skip, thin-wrappers and check-predicates are removed without replacement (the `// @wrapper-known` and silent-skip markers are dead and can be deleted). `kumiko check` gains a `lint` step (`biome lint` in the app repo) and an `agent` step (kumiko agent lint) for apps with a kumiko.config.ts.",
20
+ "migration": "Extend the preset in your `biome.json`, replacing your own linter rules for these checks - `\"extends\": [\"@cosmicdrift/kumiko-framework/biome-rules\"]` (apps that already extend `biome-app` get it through that preset). Delete `.kumiko-direct-fs-baseline.json`, `.kumiko-test-title-baseline.json`, `.kumiko-no-custom-primitives-baseline.json` and `.kumiko-test-timeouts-baseline.json`. `bun kumiko-upgrade --apply` runs the codemod lint-ignore-to-biome, which turns `kumiko-lint-ignore <slug> <reason>` markers of the deleted guards into `biome-ignore lint/plugin: <reason>` (`lint/style/noInlineStyles` for no-inline-styles), keeps the comment form and the reason, and lists markers without a reason of at least three words. Biome applies a suppression only to the next line or node, so a marker that sat several lines above its hit moves by hand (CSS - `biome-ignore lint/plugin: <reason>` inside a comment). Remove deleted guard names from your `kumiko.json` and security baseline. Enterprise and platform extend the same preset.",
21
+ "codemod": "scripts/codemod/lint-ignore-to-biome.ts"
22
+ },
23
+ {
24
+ "version": "0.414.0",
25
+ "type": "fix",
26
+ "title": "Backslash-aware escape prefilter, Dockerfile heredoc start, stable editor handle report, IMAP host key",
27
+ "detail": "The escaped-literal prefilter treats every backslash as a possible escape, so identity escapes and backslash-newline continuations no longer hide a literal from the RLS-setting, test-ES-fixture and test-ES-row-write guards. The Dockerfile heredoc start ignores `<<<` herestrings and `$((1 << x))` shifts, so later stages are still inspected. The template editor reports its handle once per editor instance again (the reporting callback is read through a ref), instead of re-reporting on every render. The IMAP connect-target rate limit strips a trailing dot from the host before keying its buckets. Several tests are sharpened (parallel ingest progress, batch hooks, consumer audit, pre-push lane order)."
28
+ },
29
+ {
30
+ "version": "0.414.0",
31
+ "type": "fix",
32
+ "title": "Guard hardening: test titles, ignore-tag reasons, schema CLI, unsafe array params, RLS settings, internal imports",
33
+ "detail": "test-title no longer lets English apostrophes hide German words and no longer flags hex colours or row positions as issue references. ignore-tag-reason also checks tags preceded by text and counts lines in linear time. schema-cli-features accepts .js specifiers and namespace imports. unsafe-array-param sees through non-null and angle-bracket assertions. rls-session-settings splits SQL only at top-level semicolons, ignoring comments, strings and dollar-quoted bodies, and skips build, coverage and .turbo directories. internal-subpath-imports flags export-star re-exports of the testing helpers and import-equals require of internal subpaths."
34
+ },
35
+ {
36
+ "version": "0.414.0",
37
+ "type": "fix",
38
+ "title": "Guards: parser and diagnostic fixes, escape-aware prefilters",
39
+ "detail": "The app-dockerfile guard now sees RUN heredocs and the `bun i` alias, accepts an inline token assignment only when it reads the mounted secret, and takes token variables only from the private scope's registry entry. The doc-status guard tolerates CRLF and a BOM and skips symlinks while walking. Agent docs render public class accessors with their types and no longer derive a flag call from an `!== true` condition. The security check no longer calls an expired or shadowed repo exception unused. The pre-push pool floor drops from four lanes to two. The RLS-setting, test-ES-fixture and test-ES-row-write guards resolve string escapes (`_`, `\\x20`) before matching and their text prefilters no longer skip files containing escapes. Two timing-based guard tests now synchronize instead of measuring wall-clock time."
40
+ },
41
+ {
42
+ "version": "0.414.0",
43
+ "type": "fix",
44
+ "title": "pre-push re-entry needs owner command and nonce, not just an ancestor PID",
45
+ "detail": "Any shell could run `KUMIKO_CHECK_WT_OWNER=$$ git push` and the ancestor-PID check passed, switching off `pre-push-extra.sh`, the upgrade-state guard and gitleaks. Before delegating to a tracked `scripts/check-wt.sh` the hook now writes a random nonce to `kumiko-prepush-<pid>` (mode 0600) in the git common dir and passes it as `KUMIKO_CHECK_WT_NONCE`. Re-entry requires the owner to be an ancestor whose command line contains `scripts/check-wt.sh` (or the hook process itself when check-wt.sh exec'd it) and the nonce to match the file. Each outer run removes nonce files whose PID is no longer alive; if the file cannot be written the push is refused."
46
+ },
47
+ {
48
+ "version": "0.414.0",
49
+ "type": "fix",
50
+ "title": "guard slot directory from older versions is tightened, spreads no longer flagged",
51
+ "detail": "A slots directory created with mode 0755 by an earlier version made the slot check fail open on every run. A directory owned by the current user is now chmod-ed to 0700 and used; foreign owners and symlinks are still rejected. `guard-unsafe-array-param` no longer warns on spreads in the parameter list, since they bind as scalars. The generated API reference now lists unexported constants that exported types reach through `typeof`."
52
+ },
2
53
  {
3
54
  "version": "0.409.0",
4
55
  "type": "improvement",
@@ -69,11 +69,12 @@ export function shouldBlock(
69
69
  }
70
70
 
71
71
  // Bundled exceptions apply to every consumer, including those without the package, so only repo-local ones can be stale.
72
+ // "Matched" instead of "used": an expired or shadowed exception whose advisory still occurs needs a renewal, not removal.
72
73
  function findUnusedRepoExceptions(
73
74
  exceptions: readonly SecurityException[],
74
- used: readonly SecurityException[],
75
+ matched: readonly SecurityException[],
75
76
  ): SecurityException[] {
76
- return exceptions.filter((ex) => ex.source.origin === "repo" && !used.includes(ex));
77
+ return exceptions.filter((ex) => ex.source.origin === "repo" && !matched.includes(ex));
77
78
  }
78
79
 
79
80
  function printExceptionWarnings(
@@ -93,7 +94,7 @@ function printExceptionWarnings(
93
94
  }
94
95
  }
95
96
 
96
- const unusedRepoExceptions = findUnusedRepoExceptions(exceptions, evaluation.usedExceptions);
97
+ const unusedRepoExceptions = findUnusedRepoExceptions(exceptions, evaluation.matchedExceptions);
97
98
  if (unusedRepoExceptions.length > 0) {
98
99
  console.log(
99
100
  "\n WARN: security exceptions suppressed no advisory in this run — remove the entry if it is obsolete:",