sparda-mcp 0.67.0 → 0.68.0

package/src/ubg/extract.js

@@ -363,6 +363,243 @@ function collectEffectClients(body) {
   return labeled;
 }
 
+// Persistence-client packages: a binding imported from one, or built (`new`/call) from such an
+// import, is a PROVEN database handle — by provenance, not by its name (ADR-068). Used to close
+// the opaque-write hole: an UNKNOWN method on a proven handle (`db.nukeEverything(...)`) must be
+// treated as a write, not ignored, or an unguarded custom write passes invisible.
+const DB_PACKAGES = new Set([
+  'knex',
+  'pg',
+  'pg-pool',
+  'mysql',
+  'mysql2',
+  'mysql2/promise',
+  'mongoose',
+  'mongodb',
+  'sequelize',
+  'typeorm',
+  'drizzle-orm',
+  '@prisma/client',
+  'better-sqlite3',
+  '@libsql/client',
+  'postgres',
+  'sqlite3',
+  '@mikro-orm/core',
+  'objection',
+  'kysely',
+]);
+
+// Methods on a DB handle that are clearly READS — never flagged as an opaque write.
+const DB_KNOWN_READ = new Set([
+  'select',
+  'find',
+  'findone',
+  'findmany',
+  'findunique',
+  'findfirst',
+  'findall',
+  'first',
+  'get',
+  'getone',
+  'getmany',
+  'count',
+  'exists',
+  'all',
+  'aggregate',
+  'scan',
+  'list',
+  'fetch',
+  'read',
+  'describe',
+  'explain',
+  'has',
+  'pluck',
+  'stream',
+  'cursor',
+  'iterate',
+  'tolist',
+  'toarray',
+]);
+// Plumbing / chaining / promise / introspection / wiring on a DB handle — never an effect. Also
+// parks the ambiguous raw-SQL methods (`raw`/`query`/`execute`) OUT of the opaque-write fallback:
+// their literal-vs-dynamic read/write split is a separate follow-on (ADR-068), and firing them
+// blindly would flood reads. So V1 catches the custom-named write (`db.archiveAll()`), not raw SQL.
+const DB_NON_EFFECT = new Set([
+  'then',
+  'catch',
+  'finally',
+  'tostring',
+  'valueof',
+  'tosql',
+  'toquery',
+  'clone',
+  'as',
+  'ref',
+  'unref',
+  'on',
+  'off',
+  'once',
+  'emit',
+  'addlistener',
+  'removelistener',
+  'destroy',
+  'end',
+  'connect',
+  'disconnect',
+  'close',
+  'release',
+  'begin',
+  'commit',
+  'rollback',
+  'savepoint',
+  'transaction',
+  'pipe',
+  'listen',
+  'use',
+  'ping',
+  'authenticate',
+  'sync',
+  'define',
+  'model',
+  'prepare',
+  'unprepare',
+  'bind',
+  'escape',
+  'format',
+  'migrate',
+  'seed',
+  'schema',
+  'fn',
+  'client',
+  'pool',
+  'raw',
+  'query',
+  'execute',
+  'exec',
+  'command',
+  'sql',
+  'template',
+  'with',
+  'withschema',
+  'table',
+]);
+
+// Auth packages whose guard middleware PROVABLY DENIES (401/403/throw) on missing/invalid auth.
+// A catalog of VERIFIED published facts (versioned, auditable) — NOT a name guess (ADR-069): the
+// claim is "`passport.authenticate()` denies", checkable by anyone reading passport once. This is
+// what lets an opaque npm auth guard count as VERIFIED instead of merely asserted, so a real app
+// on passport/express-jwt can legitimately reach PROVEN. Innate immunity: know the known pathogens.
+const AUTH_GUARD_PACKAGES = new Set([
+  'passport',
+  'express-jwt',
+  'express-oauth2-jwt-bearer',
+  'express-openid-connect',
+  'connect-ensure-login',
+  'express-basic-auth',
+  '@clerk/clerk-sdk-node',
+]);
+
+const objectOptionIsFalse = (objNode, key) =>
+  objNode?.type === 'ObjectExpression' &&
+  objNode.properties.some(
+    (p) =>
+      p.type === 'ObjectProperty' &&
+      p.key?.type === 'Identifier' &&
+      p.key.name === key &&
+      p.value.type === 'BooleanLiteral' &&
+      p.value.value === false,
+  );
+
+// Is this call a known auth-lib DENY-form middleware, per the provenance map `pkgOf`
+// (localName → package)? Deny-FORM precision keeps the catalog honest — a form that does NOT
+// auto-deny is abstained on (stays asserted, the safe direction), never falsely verified:
+//   • passport.authenticate(strategy, opts?) denies UNLESS a custom callback fn is passed
+//     (then the deny logic is the user's, not passport's default 401).
+//   • express-jwt expressjwt(opts) throws UNLESS `credentialsRequired: false`.
+export function authDenyCall(node, pkgOf) {
+  if (node?.type !== 'CallExpression' || !pkgOf) return false;
+  const callee = node.callee;
+  if (
+    callee.type === 'MemberExpression' &&
+    callee.object.type === 'Identifier' &&
+    callee.property.type === 'Identifier' &&
+    callee.property.name === 'authenticate' &&
+    pkgOf.get(callee.object.name) === 'passport'
+  ) {
+    const hasCallback = node.arguments.some(
+      (a) => a.type === 'ArrowFunctionExpression' || a.type === 'FunctionExpression',
+    );
+    return !hasCallback;
+  }
+  if (callee.type === 'Identifier') {
+    const pkg = pkgOf.get(callee.name);
+    if (!pkg || !AUTH_GUARD_PACKAGES.has(pkg)) return false;
+    if (pkg === 'express-jwt')
+      return !objectOptionIsFalse(node.arguments[0], 'credentialsRequired');
+    return true;
+  }
+  return false;
+}
+
+// Provenance for auth guards: the import map (localName → package) plus the local const names
+// bound to a deny-form auth call (`const requireAuth = passport.authenticate('jwt')`). Same shape
+// as collectDbHandles/collectEffectClients — provenance, never a name test.
+export function collectAuthGuards(body) {
+  const pkgOf = new Map();
+  for (const node of body)
+    if (node.type === 'ImportDeclaration')
+      for (const s of node.specifiers) pkgOf.set(s.local.name, node.source.value);
+  const denyBindings = new Set();
+  for (const node of body) {
+    if (node.type !== 'VariableDeclaration') continue;
+    for (const d of node.declarations)
+      if (d.id.type === 'Identifier' && authDenyCall(d.init, pkgOf))
+        denyBindings.add(d.id.name);
+  }
+  return { pkgOf, denyBindings };
+}
+
+// Vars/params bound to a database handle, by IMPORT PROVENANCE (same shape as
+// collectEffectClients): imported from a DB package, or `new X()`/`X(...)`/alias of a labeled
+// binding. Deliberately provenance-only — never a name test — so `const db = notARealDb` is NOT
+// a handle, and a handle named `store` still IS one.
+function collectDbHandles(body) {
+  const labeled = new Set();
+  const isLabeled = (n) => n?.type === 'Identifier' && labeled.has(n.name);
+  for (const node of body) {
+    if (node.type === 'ImportDeclaration') {
+      if (DB_PACKAGES.has(node.source.value))
+        for (const s of node.specifiers) labeled.add(s.local.name);
+      continue;
+    }
+    if (node.type !== 'VariableDeclaration') continue;
+    for (const d of node.declarations) {
+      const init = d.init;
+      if (!init || d.id.type !== 'Identifier') continue;
+      const requirePkg =
+        init.type === 'CallExpression' &&
+        init.callee.type === 'Identifier' &&
+        init.callee.name === 'require' &&
+        init.arguments[0]?.type === 'StringLiteral'
+          ? init.arguments[0].value
+          : null;
+      if (
+        (requirePkg && DB_PACKAGES.has(requirePkg)) ||
+        (init.type === 'CallExpression' &&
+          init.callee.type === 'CallExpression' &&
+          init.callee.callee?.type === 'Identifier' &&
+          init.callee.callee.name === 'require' &&
+          DB_PACKAGES.has(init.callee.arguments?.[0]?.value)) ||
+        (init.type === 'NewExpression' && isLabeled(init.callee)) ||
+        (init.type === 'CallExpression' && isLabeled(init.callee)) ||
+        isLabeled(init)
+      )
+        labeled.add(d.id.name);
+    }
+  }
+  return labeled;
+}
+
 // TypeORM repository provenance — like the effect-client label, but for ORM repositories, so a
 // `repo.save()` / `this.userRepo.save()` resolves to a db_write with its entity table even though
 // the table is nowhere in the call. Two sources: (1) a class constructor param that is an injected
@@ -503,6 +740,8 @@ export function parseModule(absFile) {
 
   for (const node of facts.ast.program.body) collectTopLevel(node, facts, absFile, false);
   facts.effectClients = collectEffectClients(facts.ast.program.body);
+  facts.dbHandles = collectDbHandles(facts.ast.program.body);
+  facts.authGuards = collectAuthGuards(facts.ast.program.body);
   return facts;
 }
 
@@ -1194,7 +1433,7 @@ export function scanFunction(fnNode, env = {}) {
     isolation: 'default',
     tryId: null,
     catchOf: null,
-    reqDerived: collectReqDerived(fnNode),
+    reqDerived: collectReqDerived(fnNode, env.reqDerivedSeed),
     // symbolic `this.<field>` bindings, supplied by the caller when this body is a
     // CLASS METHOD reached through `new X(req.params.collection)` — lets a
     // `this.knex(this.collection)` inside a service resolve to `:collection`.
@@ -1202,6 +1441,7 @@ export function scanFunction(fnNode, env = {}) {
     // effect-labeled bindings of the owning module (import-provenance), so a call on an
     // SDK client is recognized by origin. Absent → the path/command catalog still applies.
     effectClients: env.effectClients ?? null,
+    dbHandles: env.dbHandles ?? null,
     // TypeORM repository provenance: class-injected repo fields (env.repoFields, from the owning
     // class) merged with local `getRepository(Entity)` vars found in THIS body → receiver → table.
     repoTables: mergeRepoTables(env.repoFields, collectRepoVars(fnNode)),
@@ -1353,6 +1593,38 @@ function callAssertsOwnership(node) {
   return false;
 }
 
+// Does this `if` assert caller-ownership by FETCH-THEN-COMPARE — the most common hand-rolled
+// authorization check: `if (row.ownerId !== req.user.id) return res.sendStatus(403)`. The scope
+// lives in a value comparison + deny, NOT in a `where` clause, so `whereOwnerScoped` abstains and
+// O7 false-positives. This is the deterministic half of the generate-and-check loop (ADR-074): a
+// proposed ownership witness ("scope is proven by comparing <field> to the principal, gating a
+// deny") is VERIFIED here against the AST. SOUND both ways, adversarially tested:
+//   • the compared-against value must be the caller's VERIFIED identity (`valueIsIdentity` rejects
+//     `req.body.ownerId` — an attacker-controlled spoof — even though it is named like an owner);
+//   • the branch must actually DENY (a throw or a 401/403 response) — a compare that only logs
+//     proves nothing and is rejected.
+// Advisory-only (feeds O7, never a hard rule), so it can never create a false PROVEN; at worst a
+// mis-clear drops an advisory that was already non-gating.
+function ifAssertsOwnership(node) {
+  if (node.type !== 'IfStatement') return false;
+  let denies = false;
+  walkNodes(node.consequent, (c) => {
+    if (c.type === 'ThrowStatement') denies = true;
+    if (c.type === 'CallExpression' && deniedStatusOf(c)) denies = true;
+  });
+  if (!denies) return false;
+  let owns = false;
+  walkNodes(node.test, (b) => {
+    if (b.type !== 'BinaryExpression' || !/^[=!]==?$/.test(b.operator)) return;
+    // one side is the caller's verified identity, the OTHER is a fetched field (a member access
+    // like `row.ownerId`). Order-agnostic. `valueIsIdentity` is the honesty gate — request input
+    // (`req.body.*`, `req.params.*`) is never identity, so a spoofable compare is rejected.
+    if (valueIsIdentity(b.left) && b.right?.type === 'MemberExpression') owns = true;
+    if (valueIsIdentity(b.right) && b.left?.type === 'MemberExpression') owns = true;
+  });
+  return owns;
+}
+
 // does this `where` target a specific object by a bare `id` key (the BOLA shape)?
 function whereHasIdKey(whereNode) {
   if (whereNode?.type !== 'ObjectExpression') return false;
@@ -1384,7 +1656,7 @@ function optionValueOf(arg, name) {
   return null;
 }
 
-function reqParamName(node, reqDerived, thisSymbols) {
+export function reqParamName(node, reqDerived, thisSymbols) {
   node = unwrapTS(node);
   if (node?.type === 'Identifier') return reqDerived?.get(node.name) ?? null;
   if (node?.type !== 'MemberExpression') return null;
@@ -1405,22 +1677,72 @@ function reqParamName(node, reqDerived, thisSymbols) {
 }
 
 // map local vars assigned straight from a request member: `const c = req.params.collection`
-// → { c: ':collection' }. One shallow pass; deterministic; bounded by the function body.
-function collectReqDerived(fnNode) {
+// → { c: ':collection' }. Also follows the two commonest value-flow shapes the direct-member
+// case misses — OBJECT DESTRUCTURING (`const { title, body } = req.body` → title/body carry
+// the request taint, the dominant handler idiom) and IDENTIFIER ALIAS (`const b = req.body;
+// const c = b`). One source-order pass — earlier bindings are in the map when a later one
+// references them; deterministic; bounded by the function body. UNDER-approximates on
+// purpose (a missed alias is a false-negative on an advisory taint tag, never a hidden
+// write) — see valueTainted.
+//
+// `seed` (interprocedural, ADR-066): request-derived PARAMETER bindings supplied by the
+// caller — when a handler calls `saveItem(req.body)`, the resolver seeds `saveItem`'s param
+// as request-derived so a write inside it taints. Seeded first so a local re-binding in the
+// body can still override. MUST-analysis: the caller only seeds a param it PROVED tainted.
+export function collectReqDerived(fnNode, seed = null) {
   const map = new Map();
+  if (seed) for (const [k, v] of seed) map.set(k, v);
+  // non-null request-taint marker if `init` is request-derived: a req member (`req.body`),
+  // or an identifier already tracked as request-derived (`b` after `const b = req.body`).
+  const reqSourceOf = (init) => {
+    const node = unwrapTS(init);
+    if (!node) return null;
+    if (node.type === 'Identifier') return map.get(node.name) ?? null;
+    if (node.type === 'MemberExpression') return reqParamName(node, map);
+    return null;
+  };
   const walk = (n) => {
     if (!n || typeof n !== 'object') return;
     if (Array.isArray(n)) {
       for (const x of n) walk(x);
       return;
     }
-    if (
-      n.type === 'VariableDeclarator' &&
-      n.id?.type === 'Identifier' &&
-      n.init?.type === 'MemberExpression'
-    ) {
-      const name = reqParamName(n.init, null);
-      if (name) map.set(n.id.name, name);
+    if (n.type === 'VariableDeclarator') {
+      if (n.id?.type === 'Identifier' && n.init?.type === 'MemberExpression') {
+        const name = reqParamName(n.init, map);
+        if (name) map.set(n.id.name, name);
+      } else if (n.id?.type === 'Identifier' && n.init?.type === 'Identifier') {
+        // alias: `const c = b` where b is already request-derived
+        const src = map.get(n.init.name);
+        if (src) map.set(n.id.name, src);
+      } else if (n.id?.type === 'ObjectPattern' && reqSourceOf(n.init)) {
+        // destructure: `const { title, body: b, ...rest } = req.body` — each binding is
+        // request-derived; a named binding carries its KEY as the symbolic leaf (`:title`).
+        const src = reqSourceOf(n.init);
+        for (const prop of n.id.properties) {
+          if (prop.type === 'RestElement' && prop.argument?.type === 'Identifier') {
+            map.set(prop.argument.name, src); // rest carries the whole source taint
+            continue;
+          }
+          if (prop.type !== 'ObjectProperty') continue;
+          const key =
+            prop.key?.type === 'Identifier'
+              ? prop.key.name
+              : prop.key?.type === 'StringLiteral'
+                ? prop.key.value
+                : null;
+          // local binding: `{ title }` (value=title), `{ title: t }` (value=t),
+          // `{ title = 'x' }` (value=AssignmentPattern → left)
+          const val = prop.value;
+          const local =
+            val?.type === 'Identifier'
+              ? val.name
+              : val?.type === 'AssignmentPattern' && val.left?.type === 'Identifier'
+                ? val.left.name
+                : null;
+          if (key && local) map.set(local, `:${key}`);
+        }
+      }
     }
     for (const k of Object.keys(n)) {
       if (
@@ -1556,6 +1878,11 @@ function visit(node, out, ctx) {
   // can only ever downgrade a critical to an advisory, never verify a guard.
   if (node.type === 'ThrowStatement') out.credentialSignals.denies4xxOrThrows = true;
 
+  // G1b (O7/BOLA only): fetch-then-compare ownership — `if (row.ownerId !== req.user.id) deny`.
+  // The deterministic witness verifier (ADR-074), clears the same advisory as G1 (callAssertsOwnership),
+  // sound both ways. Runs on every IfStatement, so it must be in `visit`, not `inspectCall`.
+  if (ifAssertsOwnership(node)) out.ownerAsserted = true;
+
   // try/catch — try-effects are compensable by catch-effects (SBIR §2.2)
   if (node.type === 'TryStatement') {
     const tryLine = node.loc?.start.line ?? 0;
@@ -1575,8 +1902,7 @@ function visit(node, out, ctx) {
       out.guardSignals.deniesWithStatus = true;
     else if (n === 'HttpException' || n === 'HttpError')
       for (const a of node.arguments)
-        if (a.type === 'NumericLiteral' && (a.value === 401 || a.value === 403))
-          out.guardSignals.deniesWithStatus = true;
+        if (isDenyStatusArg(a)) out.guardSignals.deniesWithStatus = true;
     // any error/response CONSTRUCTED with an unauthorized/forbidden code or a 401/403
     // status — `new DubApiError({ code: "unauthorized" })`, `new Response(_, { status:
     // 403 })`. A general REST/Next idiom, so a resolved auth wrapper reads as a denial.
@@ -2009,6 +2335,33 @@ function inspectCall(node, out, ctx) {
         line,
       });
     }
+    return;
+  }
+
+  // ---- opaque write on a PROVEN persistence handle (ADR-068 — the effect-bias inversion).
+  // Reached only AFTER every known ORM/SDK/HTTP/fs handler has declined. An UNKNOWN method called
+  // DIRECTLY on a database handle (`db.archiveAll(...)`) can't be read — but the safe direction is
+  // INVERTED here vs everywhere else: a missed write is a HIDDEN HOLE (an unguarded custom write
+  // goes invisible), while an over-flagged read is only a surfaceable false positive. So treat it
+  // as a write. Marked `opaque` with a null table, so it fires ONLY the guard obligation (O1) and
+  // NEVER fabricates column/atomicity precision (O2/O3 skip a table-less write). Gated hard to
+  // avoid a flood: the receiver must be a handle IDENTIFIER (builder continuations sit on a CALL
+  // receiver, ORM verbs are handled above), and the method must be neither a known read nor
+  // plumbing. Provenance-based (dbHandles), never a name test — so this can only RAISE a finding.
+  if (
+    ctx.dbHandles &&
+    callee.object.type === 'Identifier' &&
+    ctx.dbHandles.has(callee.object.name) &&
+    !DB_KNOWN_READ.has(methodLower) &&
+    !DB_NON_EFFECT.has(methodLower)
+  ) {
+    pushEffect(out, ctx, {
+      effectType: 'db_write',
+      op: 'unknown',
+      table: null,
+      opaque: true,
+      line,
+    });
   }
 }
 
@@ -2105,11 +2458,8 @@ function isDenyOptions(arg) {
   for (const p of arg.properties) {
     if (p.type !== 'ObjectProperty' || p.key?.type !== 'Identifier') continue;
     if (p.key.name === 'status' || p.key.name === 'statusCode') {
-      if (
-        p.value?.type === 'NumericLiteral' &&
-        (p.value.value === 401 || p.value.value === 403)
-      )
-        return true;
+      // { status: 403 } OR { status: HttpStatus.FORBIDDEN } (named constant, ADR-073)
+      if (isDenyStatusArg(p.value)) return true;
     } else if (p.key.name === 'code') {
       if (
         p.value?.type === 'StringLiteral' &&
@@ -2160,8 +2510,19 @@ function statusIn4xx(node) {
   return false;
 }
 
+// A deny STATUS argument: the numeric 401/403, OR the named HTTP constant `X.FORBIDDEN` /
+// `X.UNAUTHORIZED` (http-status-codes' `StatusCodes.FORBIDDEN`, Nest's `HttpStatus.FORBIDDEN`, …).
+// The status NAME is a conserved denial signal regardless of spelling — recognizing it is honest
+// (FORBIDDEN is 403 by definition, not a fuzzy name), and closes a huge real gap: a guard that
+// throws `new HttpException(_, StatusCodes.FORBIDDEN)` (ghostfolio does this on 91 permission guards)
+// used to read asserted only because SPARDA saw the constant, not a literal 403 (ADR-073).
+const isDenyStatusArg = (a) =>
+  (a?.type === 'NumericLiteral' && (a.value === 401 || a.value === 403)) ||
+  (a?.type === 'MemberExpression' &&
+    a.property?.type === 'Identifier' &&
+    (a.property.name === 'FORBIDDEN' || a.property.name === 'UNAUTHORIZED'));
+
 function deniedStatusOf(node) {
-  const isDeny = (v) => v === 401 || v === 403;
   // NextResponse.json(_, { status: 401 }) / res.json(_, { status: 403 }) — the deny is
   // in the init object, not a .status() chain. A first-class Next/Web-Response idiom.
   if (
@@ -2171,13 +2532,12 @@ function deniedStatusOf(node) {
     node.arguments.some(isDenyOptions)
   )
     return true;
-  // res.sendStatus(401) / res.status(401)... — a direct deny status
+  // res.sendStatus(401) / res.status(401)... — a direct deny status (numeric or named constant)
   if (
     node.type === 'CallExpression' &&
     node.callee?.type === 'MemberExpression' &&
     node.callee.property?.name === 'sendStatus' &&
-    node.arguments[0]?.type === 'NumericLiteral' &&
-    isDeny(node.arguments[0].value)
+    isDenyStatusArg(node.arguments[0])
   )
     return true;
   let cur = node;
@@ -2186,8 +2546,7 @@ function deniedStatusOf(node) {
       cur.type === 'CallExpression' &&
       cur.callee?.type === 'MemberExpression' &&
       cur.callee.property?.name === 'status' &&
-      cur.arguments[0]?.type === 'NumericLiteral' &&
-      isDeny(cur.arguments[0].value)
+      isDenyStatusArg(cur.arguments[0])
     )
       return true;
     cur =
@@ -2458,7 +2817,15 @@ function literalPairsOf(clause) {
   return pairs;
 }
 
-// middleware classifier: name smell OR observed 401/403 denial → guard
+// middleware classifier: name smell OR observed 401/403 denial → guard. `assertedGuard`
+// is an extractor's explicit "this chain step gates by name, unverified" flag (ADR-063,
+// the principal-injection param decorators `@GetUser`/`@Principal` whose bare names carry
+// no GUARD_NAME token) — honored here so a marked step reads as an ASSERTED guard without
+// widening GUARD_NAME globally (which would misclassify a plain `getUser` middleware).
 export function isGuardLike(name, scan) {
-  return GUARD_NAME.test(name ?? '') || Boolean(scan?.guardSignals.deniesWithStatus);
+  return (
+    GUARD_NAME.test(name ?? '') ||
+    Boolean(scan?.guardSignals?.deniesWithStatus) ||
+    Boolean(scan?.assertedGuard)
+  );
 }