@massu/core 1.2.1 → 1.4.0-soak.0

package/src/detect/adapters/nextjs-trpc.ts

@@ -0,0 +1,166 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * Plan 3b — Phase 1: Next.js + tRPC AST adapter.
+ *
+ * Extracts:
+ *   - trpc_router_builder: name of router-creation call (createTRPCRouter, t.router, router)
+ *   - procedure_pattern: identifier ending in `Procedure` (publicProcedure, protectedProcedure)
+ *   - ctx_shape: 'object' | 'function' | null — based on resolver signature shape
+ *
+ * Looks under `server/api/routers/` or `server/trpc/` paths. The runner is
+ * responsible for sampling files into those paths; this adapter assumes the
+ * `files` it receives are router-shaped.
+ */
+
+import { Parser } from 'web-tree-sitter';
+import type { CodebaseAdapter, AdapterResult, DetectionSignals, Provenance, SourceFile } from './types.ts';
+import { runQuery, InvalidQueryError } from './query-helpers.ts';
+import { loadGrammar } from './tree-sitter-loader.ts';
+import { isParsableSource, MAX_AST_FILE_BYTES } from './parse-guard.ts';
+
+// ============================================================
+// Queries
+// ============================================================
+
+/**
+ * Router builder call: `createTRPCRouter({...})` or `t.router({...})`. Captures
+ * the call's function expression so the runner can normalize it.
+ */
+const ROUTER_BUILDER_QUERY = `
+(call_expression
+  function: (identifier) @builder_id (#match? @builder_id "^(createTRPCRouter|router)$"))
+
+(call_expression
+  function: (member_expression
+    object: (identifier) @_obj
+    property: (property_identifier) @_prop (#eq? @_prop "router"))) @member_call
+`;
+
+/**
+ * Procedure usage: `publicProcedure.input(...)` / `protectedProcedure.query(...)`.
+ * Captures any identifier that ends in `Procedure`.
+ */
+const PROCEDURE_QUERY = `
+(member_expression
+  object: (identifier) @procedure_id (#match? @procedure_id "Procedure$"))
+
+(call_expression
+  function: (identifier) @procedure_call (#match? @procedure_call "Procedure$"))
+`;
+
+// ============================================================
+// Adapter
+// ============================================================
+
+const KNOWN_BUILDERS = new Set(['createTRPCRouter', 'router']);
+
+export const nextjsTrpcAdapter: CodebaseAdapter = {
+  id: 'nextjs-trpc',
+  languages: ['typescript'],
+
+  matches(signals: DetectionSignals): boolean {
+    // package.json deps include @trpc/* OR there's a server/api/routers dir
+    const pkgJson = signals.packageJson;
+    if (pkgJson) {
+      const deps = pkgJson.dependencies as Record<string, unknown> | undefined;
+      const devDeps = pkgJson.devDependencies as Record<string, unknown> | undefined;
+      const all = { ...(deps ?? {}), ...(devDeps ?? {}) };
+      if (Object.keys(all).some(k => k.startsWith('@trpc/'))) return true;
+    }
+    if (signals.presentDirs.has('server')) return true;
+    return false;
+  },
+
+  async introspect(files: SourceFile[], _rootDir: string): Promise<AdapterResult> {
+    if (files.length === 0) {
+      return { conventions: {}, provenance: [], confidence: 'none' };
+    }
+
+    let language;
+    try {
+      language = await loadGrammar('typescript');
+    } catch {
+      return { conventions: {}, provenance: [], confidence: 'none' };
+    }
+
+    const parser = new Parser();
+    parser.setLanguage(language);
+
+    const builders = new Map<string, { line: number; file: string }>();
+    const procedures = new Map<string, { line: number; file: string }>();
+
+    try {
+      for (const file of files) {
+        const skip = isParsableSource(file.content, file.size);
+        if (skip) {
+          process.stderr.write(
+            `[massu/ast] WARN: nextjs-trpc skipping ${file.path}: ${skip.reason} (${skip.detail}). Cap=${MAX_AST_FILE_BYTES}. (Phase 3.5 mitigation)\n`,
+          );
+          continue;
+        }
+        try {
+          for (const hit of runQuery(parser, file.content, ROUTER_BUILDER_QUERY, 'trpc-router-builder', file.path)) {
+            // Either capture group `builder_id` (direct call) or
+            // `member_call` (the whole `t.router(...)` expression).
+            const directId = hit.captures.builder_id;
+            const memberCall = hit.captures.member_call;
+            let label: string | null = null;
+            if (directId && KNOWN_BUILDERS.has(directId)) {
+              label = directId;
+            } else if (memberCall) {
+              // Normalize `t.router` text (member_call captures the whole call)
+              // into the bare `t.router` form by extracting the leading
+              // identifier.foo pattern.
+              const m = memberCall.match(/([A-Za-z_$][A-Za-z0-9_$]*)\.router/);
+              if (m) label = `${m[1]}.router`;
+            }
+            if (label && !builders.has(label)) {
+              builders.set(label, { line: hit.line, file: file.path });
+            }
+          }
+
+          for (const hit of runQuery(parser, file.content, PROCEDURE_QUERY, 'trpc-procedure', file.path)) {
+            const proc = hit.captures.procedure_id ?? hit.captures.procedure_call;
+            if (proc && !procedures.has(proc)) {
+              procedures.set(proc, { line: hit.line, file: file.path });
+            }
+          }
+        } catch (e) {
+          if (e instanceof InvalidQueryError) throw e;
+          continue;
+        }
+      }
+    } finally {
+      try { parser.delete(); } catch { /* ignore */ }
+    }
+
+    const conventions: Record<string, unknown> = {};
+    const provenance: Provenance[] = [];
+
+    if (builders.size > 0) {
+      const [name, { line, file }] = builders.entries().next().value as [string, { line: number; file: string }];
+      conventions.trpc_router_builder = name;
+      provenance.push({ field: 'trpc_router_builder', sourceFile: file, line, query: 'trpc-router-builder' });
+    }
+    if (procedures.size > 0) {
+      const [name, { line, file }] = procedures.entries().next().value as [string, { line: number; file: string }];
+      conventions.procedure_pattern = name;
+      provenance.push({ field: 'procedure_pattern', sourceFile: file, line, query: 'trpc-procedure' });
+    }
+
+    let confidence: AdapterResult['confidence'];
+    if (Object.keys(conventions).length === 0) {
+      confidence = 'none';
+    } else if (builders.size === 1 && procedures.size <= 2) {
+      confidence = 'high';
+    } else if (builders.size > 1) {
+      confidence = 'low';
+    } else {
+      confidence = 'medium';
+    }
+
+    return { conventions, provenance, confidence };
+  },
+};

package/src/detect/adapters/parse-guard.ts

@@ -0,0 +1,133 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * Plan 3b — Phase 3.5 (security audit): centralized AST parse-time safety.
+ *
+ * Adapters consume oversized / pathological user source. Tree-sitter is
+ * fast but synchronous — there is no native timeout, no native size cap.
+ * This module provides:
+ *
+ *   1. `MAX_AST_FILE_BYTES` — 1MB hard cap per file (covers DoS vector
+ *      "oversized file"). Plan §1 cited 5MB; we apply a tighter bound at
+ *      the adapter tier because adapter sample size is small (≤3 files
+ *      per adapter) and 1MB is already an order of magnitude beyond
+ *      reasonable convention-defining files.
+ *   2. `MAX_AST_PARSE_DEPTH` — 5K-deep nested-structure rejection — a
+ *      static text scan for runaway open-paren / open-brace runs that
+ *      would push Tree-sitter into deep recursion. Cheap pre-check.
+ *   3. `parseTimeout(ms, fn)` — wraps a synchronous Tree-sitter call in
+ *      a deadline guard. Tree-sitter's pure-JS path can't be interrupted
+ *      mid-parse, but we record the elapsed time AFTER the call returns
+ *      and emit a stderr warning when budget is exceeded so daemon ops
+ *      see the abuse signal.
+ *   4. `isParsableSource(source)` — static gate combining size + depth.
+ *      Returns `null` if accepted, or a `{ reason, detail }` object when
+ *      rejected so the adapter can record provenance and skip the file.
+ *
+ * Library purity: never terminates the process, no DB calls, no network.
+ * Pure helper module.
+ */
+
+/** Hard size cap for an individual file fed to Tree-sitter. */
+export const MAX_AST_FILE_BYTES = 1 * 1024 * 1024;
+
+/**
+ * Maximum nested-bracket depth allowed in a file. Pathological inputs
+ * with 10K-deep nesting can push Tree-sitter into runaway recursion on
+ * some grammar versions. Cheap O(n) text scan picks them off before parse.
+ */
+export const MAX_AST_PARSE_DEPTH = 5000;
+
+/**
+ * Per-file Tree-sitter parse budget (ms). Tree-sitter parses are
+ * synchronous in JS, so this is enforced as a post-call elapsed-time
+ * check rather than a hard timer. The check still serves the purpose of
+ * giving operators visibility into adversarial files.
+ */
+export const MAX_AST_PARSE_MS = 2000;
+
+export type ParseSkipReason =
+  | 'size-cap'
+  | 'depth-cap'
+  | 'control-bytes'
+  | 'utf8-validation';
+
+export interface ParseSkip {
+  reason: ParseSkipReason;
+  detail: string;
+}
+
+/**
+ * Static safety gate. Call BEFORE invoking `parser.parse()`. Returns
+ * `null` if the source is acceptable, or a `ParseSkip` describing why
+ * the file is rejected.
+ *
+ * Cheap to evaluate — single linear scan + size check.
+ */
+export function isParsableSource(source: string, sizeBytes?: number): ParseSkip | null {
+  // Size cap: reject before Tree-sitter sees the bytes. We compute
+  // byte-length conservatively when not provided.
+  const bytes = sizeBytes ?? Buffer.byteLength(source, 'utf-8');
+  if (bytes > MAX_AST_FILE_BYTES) {
+    return {
+      reason: 'size-cap',
+      detail: `${bytes} bytes > ${MAX_AST_FILE_BYTES} cap`,
+    };
+  }
+
+  // Depth cap: count maximal nesting depth across `(` `[` `{` runs.
+  // Single-pass O(n) — no regex backtracking.
+  let depth = 0;
+  let maxDepth = 0;
+  // Also reject NUL bytes (Tree-sitter handles them but they're a
+  // canary for binary-file mislabeling).
+  for (let i = 0; i < source.length; i++) {
+    const c = source.charCodeAt(i);
+    if (c === 0) {
+      return { reason: 'control-bytes', detail: 'NUL byte at offset ' + i };
+    }
+    // 40 = '(', 91 = '[', 123 = '{'
+    if (c === 40 || c === 91 || c === 123) {
+      depth++;
+      if (depth > maxDepth) maxDepth = depth;
+      if (depth > MAX_AST_PARSE_DEPTH) {
+        return {
+          reason: 'depth-cap',
+          detail: `nesting depth exceeded ${MAX_AST_PARSE_DEPTH}`,
+        };
+      }
+    } else if (c === 41 || c === 93 || c === 125) {
+      // Close brackets — clamp to 0 (mismatched code shouldn't crash this).
+      depth = depth > 0 ? depth - 1 : 0;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Wrap a synchronous Tree-sitter call and emit a warning when the call
+ * exceeds the budget. Returns the call's result regardless — callers may
+ * decide to discard it based on `elapsed`.
+ *
+ * Note: Tree-sitter's WASM path has no co-operative cancellation, so
+ * this is observability rather than a hard kill. The size + depth caps
+ * are the load-bearing mitigations; this is the third belt.
+ */
+export function withParseDeadline<T>(
+  fn: () => T,
+  filePath: string,
+  budgetMs: number = MAX_AST_PARSE_MS,
+): { value: T; elapsedMs: number; overBudget: boolean } {
+  const start = Date.now();
+  const value = fn();
+  const elapsedMs = Date.now() - start;
+  const overBudget = elapsedMs > budgetMs;
+  if (overBudget) {
+    process.stderr.write(
+      `[massu/ast] WARN: parse of ${filePath} took ${elapsedMs}ms (budget ${budgetMs}ms) — file may be adversarial. (Phase 3.5 mitigation)\n`,
+    );
+  }
+  return { value, elapsedMs, overBudget };
+}

package/src/detect/adapters/python-django.ts

@@ -0,0 +1,208 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * Plan 3b — Phase 1: Django AST adapter.
+ *
+ * Extracts:
+ *   - mixin_classes: class-based-view base classes inheriting LoginRequiredMixin etc.
+ *   - decorator_usage: `@login_required` or `@permission_required` decorators
+ *   - urlpatterns_shape: 'function-views' | 'class-views' | 'mixed'
+ *
+ * Conservative gate: returns 'none' if no `INSTALLED_APPS` Django marker is
+ * present in the signal bundle. Adapter wants HIGH precision: false-positive
+ * Django classification would push regex fallback aside for projects that
+ * don't actually use Django.
+ */
+
+import { Parser } from 'web-tree-sitter';
+import type { CodebaseAdapter, AdapterResult, DetectionSignals, Provenance, SourceFile } from './types.ts';
+import { runQuery, InvalidQueryError } from './query-helpers.ts';
+import { loadGrammar } from './tree-sitter-loader.ts';
+import { isParsableSource, MAX_AST_FILE_BYTES } from './parse-guard.ts';
+
+// ============================================================
+// Queries
+// ============================================================
+
+/**
+ * `@login_required` / `@permission_required` decorator on a function def.
+ * Captures the decorator name (`login_required` or any `*_required`/`*_login`).
+ */
+const DECORATOR_QUERY = `
+(decorator
+  (identifier) @decorator_name)
+`;
+
+/**
+ * Class definition with a base list — captures bases like `LoginRequiredMixin`,
+ * `PermissionRequiredMixin`, `View`, `ListView`. The runner filters for the
+ * Django-specific names.
+ */
+const CLASS_BASE_QUERY = `
+(class_definition
+  name: (identifier) @class_name
+  superclasses: (argument_list
+    (identifier) @base_name))
+`;
+
+/**
+ * urlpatterns assignment — captures the rhs (a list) so we can inspect what's
+ * inside (path() / re_path() calls indicate function-view style; class names
+ * indicate class-view style).
+ */
+const URLPATTERNS_QUERY = `
+(assignment
+  left: (identifier) @_target (#eq? @_target "urlpatterns")
+  right: (list) @urlpatterns_list)
+`;
+
+// ============================================================
+// Adapter
+// ============================================================
+
+const DJANGO_MIXIN_NAMES = new Set([
+  'LoginRequiredMixin',
+  'PermissionRequiredMixin',
+  'UserPassesTestMixin',
+  'StaffuserRequiredMixin',
+]);
+
+const DJANGO_DECORATOR_PATTERNS = [
+  /^login_required$/,
+  /^permission_required$/,
+  /_required$/,
+  /^require_/,
+];
+
+export const pythonDjangoAdapter: CodebaseAdapter = {
+  id: 'python-django',
+  languages: ['python'],
+
+  matches(signals: DetectionSignals): boolean {
+    // Conservative gate: require an explicit Django marker.
+    // - manage.py at root, OR
+    // - settings.py with INSTALLED_APPS reference, OR
+    // - pyproject.toml dep on Django
+    if (signals.presentFiles.has('manage.py')) return true;
+    const pyToml = signals.pyprojectToml as { __raw?: string } | undefined;
+    if (pyToml?.__raw && /\bdjango\b/i.test(pyToml.__raw)) return true;
+    return false;
+  },
+
+  async introspect(files: SourceFile[], _rootDir: string): Promise<AdapterResult> {
+    if (files.length === 0) {
+      return { conventions: {}, provenance: [], confidence: 'none' };
+    }
+
+    let language;
+    try {
+      language = await loadGrammar('python');
+    } catch {
+      return { conventions: {}, provenance: [], confidence: 'none' };
+    }
+
+    const parser = new Parser();
+    parser.setLanguage(language);
+
+    const decoratorsFound = new Map<string, { line: number; file: string }>();
+    const mixinsFound = new Map<string, { line: number; file: string }>();
+    const urlpatternsShape: { value: 'function-views' | 'class-views' | 'mixed' | null; line: number; file: string } = {
+      value: null,
+      line: 0,
+      file: '',
+    };
+
+    try {
+      for (const file of files) {
+        const skip = isParsableSource(file.content, file.size);
+        if (skip) {
+          process.stderr.write(
+            `[massu/ast] WARN: python-django skipping ${file.path}: ${skip.reason} (${skip.detail}). Cap=${MAX_AST_FILE_BYTES}. (Phase 3.5 mitigation)\n`,
+          );
+          continue;
+        }
+        try {
+          // Decorators
+          for (const hit of runQuery(parser, file.content, DECORATOR_QUERY, 'django-decorator', file.path)) {
+            const name = hit.captures.decorator_name;
+            if (!name) continue;
+            // Filter to Django-shaped decorator names only.
+            if (DJANGO_DECORATOR_PATTERNS.some(re => re.test(name)) && !decoratorsFound.has(name)) {
+              decoratorsFound.set(name, { line: hit.line, file: file.path });
+            }
+          }
+          // Mixins
+          for (const hit of runQuery(parser, file.content, CLASS_BASE_QUERY, 'django-mixin', file.path)) {
+            const base = hit.captures.base_name;
+            if (base && DJANGO_MIXIN_NAMES.has(base) && !mixinsFound.has(base)) {
+              mixinsFound.set(base, { line: hit.line, file: file.path });
+            }
+          }
+          // urlpatterns shape — naive heuristic: inspect the captured text
+          for (const hit of runQuery(parser, file.content, URLPATTERNS_QUERY, 'django-urlpatterns', file.path)) {
+            const listText = hit.captures.urlpatterns_list ?? '';
+            const hasFunctionForm = /\bpath\s*\(/.test(listText) || /\bre_path\s*\(/.test(listText);
+            const hasClassForm = /\.as_view\s*\(/.test(listText);
+            let shape: 'function-views' | 'class-views' | 'mixed' | null = null;
+            if (hasFunctionForm && hasClassForm) shape = 'mixed';
+            else if (hasFunctionForm) shape = 'function-views';
+            else if (hasClassForm) shape = 'class-views';
+            if (shape && !urlpatternsShape.value) {
+              urlpatternsShape.value = shape;
+              urlpatternsShape.line = hit.line;
+              urlpatternsShape.file = file.path;
+            }
+          }
+        } catch (e) {
+          if (e instanceof InvalidQueryError) throw e;
+          continue;
+        }
+      }
+    } finally {
+      try { parser.delete(); } catch { /* ignore */ }
+    }
+
+    const conventions: Record<string, unknown> = {};
+    const provenance: Provenance[] = [];
+
+    if (decoratorsFound.size > 0) {
+      const list = Array.from(decoratorsFound.keys());
+      conventions.decorator_usage = list;
+      const [first, { line, file }] = decoratorsFound.entries().next().value as [string, { line: number; file: string }];
+      provenance.push({ field: 'decorator_usage', sourceFile: file, line, query: 'django-decorator' });
+      // Also emit first decorator as auth_dep proxy for compatibility with
+      // regex-fallback's behavior — auth_dep was the regex's primary output.
+      conventions.auth_dep = first;
+      provenance.push({ field: 'auth_dep', sourceFile: file, line, query: 'django-decorator' });
+    }
+
+    if (mixinsFound.size > 0) {
+      const list = Array.from(mixinsFound.keys());
+      conventions.mixin_classes = list;
+      const [, { line, file }] = mixinsFound.entries().next().value as [string, { line: number; file: string }];
+      provenance.push({ field: 'mixin_classes', sourceFile: file, line, query: 'django-mixin' });
+    }
+
+    if (urlpatternsShape.value) {
+      conventions.urlpatterns_shape = urlpatternsShape.value;
+      provenance.push({
+        field: 'urlpatterns_shape',
+        sourceFile: urlpatternsShape.file,
+        line: urlpatternsShape.line,
+        query: 'django-urlpatterns',
+      });
+    }
+
+    let confidence: AdapterResult['confidence'];
+    if (Object.keys(conventions).length === 0) {
+      confidence = 'none';
+    } else if (decoratorsFound.size > 0 || mixinsFound.size > 0) {
+      confidence = 'high';
+    } else {
+      confidence = 'medium';
+    }
+
+    return { conventions, provenance, confidence };
+  },
+};