map: a traced package must also establish the API before it can be a DB sink

Review of this branch caught a false-candidate path, and checking it against main showed the class is
older than this branch: package provenance was being treated as API provenance.

`.query()` / `.execute()` / `.from().insert()` are generic method names. Any receiver that resolved to a
real package was admitted as a SQL sink, so an `@apollo/client` instance — a genuine dependency with
nothing to do with SQL — produced `attribution: 'import'` and a precise SQL-injection candidate for a
GraphQL call. That rule would block legitimate traffic and mitigate nothing, which is the worst shape a
generated rule can have.

    main:  const local = new ApolloClient(); local.query(req.body.sql)   -> candidate  (already live)
    main:  import { client } from './lib/gql'; client.query(...)         -> no sink
    here:  both shapes                                                  -> candidate

So the imported-client hop widened an existing hole rather than opening one. The fix is at the root: a DB
recognizer now requires the resolved package to establish a database API (`isDbPackage`, covering the
inference list plus real drivers not in it, and subpath imports such as `drizzle-orm/node-postgres`).

A traced package that is NOT a DB provider keeps its inventory entry — a `.query()` on an unknown client
is worth a human's attention — but it is marked `apiUnconfirmed`, which means: no rule, no `provider:
'sql'` claim, and no `candidateFamily` either. Advertising the sql-injection family on a GraphQL call
would mis-classify it for any consumer that reads the family without checking `ruleGeneratable`.

The refusal says which of the two things is missing, since they ask a reviewer to check different things:
"not a known db provider: it does not establish a db API (method name alone is not evidence)" vs the
existing untraceable-receiver and inferred-package reasons.

Coverage: both Apollo shapes (imported and same-file) plus controls for `pg` and a `drizzle-orm` subpath,
and a new adversarial corpus case — a non-DB client with a `.query()` method is precisely a lookalike, so
it belongs in that category. Verified 5 assertions fail with the gate disabled. 927 tests.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: patchstackdave

src/map/flows.ts

@@ -193,7 +193,12 @@ function linkFlows(
         : 'heuristic';
       const roles = new Set<ArgumentRole>(matched.flatMap(({ roles: rs }) => [...rs]));
       // Prefer a role that maps to a mitigation class over a generic one (a value can reach two args).
-      const family = [...roles].map((r) => CANDIDATE_FAMILIES[sink.kind]?.[r]).find(Boolean);
+      // A sink whose package does not establish this API cannot support the mitigation class either:
+      // labelling a GraphQL `.query()` as the sql-injection family would mis-classify it for any consumer
+      // that reads `candidateFamily` without also checking `ruleGeneratable`.
+      const family = sink.apiUnconfirmed
+        ? undefined
+        : [...roles].map((r) => CANDIDATE_FAMILIES[sink.kind]?.[r]).find(Boolean);
       const argumentRole = family
         ? [...roles].find((r) => CANDIDATE_FAMILIES[sink.kind]?.[r])
         : [...roles].find((r) => r !== 'unknown') ?? (proven ? 'unknown' : undefined);
@@ -211,6 +216,9 @@ function linkFlows(
       // from the receiver, so `res.locals.db.query(x)` in a file that happens to import `pg` looks
       // identical to a real pool — and `res.locals.db` may be any app object. Such sinks stay in the
       // inventory for review; they just cannot compile a rule that blocks live traffic on a guess.
+      if (sink.apiUnconfirmed) {
+        reasons.push(`sink package "${sink.package}" is not a known ${sink.kind} provider: it does not establish a ${sink.kind} API (method name alone is not evidence)`);
+      }
       if (sink.attribution !== 'import' && sink.attribution !== 'global') {
         reasons.push(sink.attribution === 'inferred'
           ? `sink package "${sink.package}" was inferred from the file's other imports, not from the receiver (${sink.kind}.${sink.op ?? '?'}): the receiver may be any app object`

src/map/sinks.ts

@@ -20,6 +20,21 @@ const HTTP_MEMBER_METHODS = new Set(['get', 'post', 'put', 'patch', 'delete', 'h
 // When a sink's base can't be traced precisely, infer its package from the file's imports of a known
 // provider for that sink kind (a file almost always uses one db/http client).
 const DB_PACKAGES = ['@supabase/supabase-js', '@prisma/client', 'drizzle-orm', 'knex', 'kysely', 'pg', 'mysql2', 'mysql', 'sequelize', 'typeorm', 'mongoose', 'better-sqlite3'];
+// Drivers that are not in the inference list above but do establish a database API when a receiver
+// resolves to them. Extend deliberately: this list is what separates "a package we can trace" from
+// "a package that proves a DB API", and admitting the wrong one produces a false SQL-injection rule.
+const MORE_DB_PACKAGES = ['postgres', 'mssql', 'tedious', 'oracledb', 'sqlite3', 'mongodb', 'ioredis',
+  '@planetscale/database', '@neondatabase/serverless', '@libsql/client', '@vercel/postgres', 'slonik', 'sql.js'];
+/**
+ * Does `pkg` establish a DATABASE api? Package provenance is not API provenance: `.query()` is a generic
+ * method name, and an `@apollo/client` (or any HTTP-ish client) instance resolves to a real package while
+ * having nothing to do with SQL. Without this gate, `client.query(req.body.sql)` compiled a precise
+ * SQL-injection candidate for a GraphQL call — a rule that blocks legitimate traffic and mitigates nothing.
+ * Subpath imports count (`drizzle-orm/node-postgres`).
+ */
+const isDbPackage = (pkg: string) =>
+  DB_PACKAGES.includes(pkg) || MORE_DB_PACKAGES.includes(pkg) ||
+  [...DB_PACKAGES, ...MORE_DB_PACKAGES].some((p) => pkg.startsWith(p + '/'));
 const HTTP_PACKAGES = ['axios', 'got', 'node-fetch', 'undici', 'superagent', 'ky'];
 const isHttpPackage = (pkg: string) => HTTP_PACKAGES.includes(pkg) || pkg === 'node:http' || pkg === 'node:https';
 // A filesystem/process API is not only a node: builtin — these wrappers expose the same sinks, and
@@ -145,6 +160,13 @@ function directSinks(node: any, ts: TsModule, bindings: Bindings, ctx?: SinkCont
   // untraceable receiver is neither (undefined) and must not drive an auto-generated rule.
   const attributionOf = (b: { pkg?: string }, pkg: string | undefined): Sink['attribution'] =>
     b.pkg ? 'import' : pkg ? 'inferred' : undefined;
+  /**
+   * Claim `provider: 'sql'` only when the package actually establishes a database API. A traced package
+   * that is not a DB provider stays in the INVENTORY (a `.query()` on it is worth a human's attention)
+   * but is marked so no rule can be compiled from it — and it does not get to call itself SQL.
+   */
+  const dbApi = (pkg: string | undefined): { provider?: string; apiUnconfirmed?: true } =>
+    pkg && !isDbPackage(pkg) ? { apiUnconfirmed: true } : { provider: 'sql' };
   const infer = (kind: 'db' | 'http'): string | undefined => {
     const table = kind === 'db' ? DB_PACKAGES : HTTP_PACKAGES;
     for (const p of table) if (bindings.imports.has(p)) return p;
@@ -168,7 +190,7 @@ function directSinks(node: any, ts: TsModule, bindings: Bindings, ctx?: SinkCont
         const parent = n.parent;
         if (!b.local && !b.relative && parent && ts.isPropertyAccessExpression(parent) && DB_OPS.has(parent.name.text)) {
           const pkg = b.pkg ?? infer('db');
-          push({ kind: 'db', provider: 'sql', package: pkg, table, op: parent.name.text, attribution: attributionOf(b, pkg), ...spanOf(opCallOf(parent, ts)) });
+          push({ kind: 'db', ...dbApi(pkg), package: pkg, table, op: parent.name.text, attribution: attributionOf(b, pkg), ...spanOf(opCallOf(parent, ts)) });
         }
       }
       if (ts.isPropertyAccessExpression(callee)) {
@@ -191,7 +213,7 @@ function directSinks(node: any, ts: TsModule, bindings: Bindings, ctx?: SinkCont
           // receiver stays in the inventory with NO attribution — visible to a human, never auto-ruled.
           if (method === 'query' || method === 'execute') {
             const pkg = b.pkg ?? infer('db');
-            push({ kind: 'db', provider: 'sql', package: pkg, op: method, attribution: attributionOf(b, pkg), ...spanOf(n) });
+            push({ kind: 'db', ...dbApi(pkg), package: pkg, op: method, attribution: attributionOf(b, pkg), ...spanOf(n) });
           }
           // fs / exec via a namespace: `fs.writeFile(` / `child_process.exec(`. The receiver must
           // actually resolve to a filesystem/process package — the method name alone proves nothing.

src/map/types.ts

@@ -96,6 +96,13 @@ export interface Sink {
    * never drive an auto-generated rule, since any object can own a method by that name.
    */
   attribution?: 'import' | 'global' | 'inferred';
+  /**
+   * Set when the receiver resolved to a real package that does **not** establish this kind of API —
+   * package provenance is not API provenance. `client.query(x)` on an `@apollo/client` instance traces to
+   * a genuine dependency while having nothing to do with SQL. Such a sink is reported for review and can
+   * never compile a rule: a candidate here would block legitimate traffic and mitigate nothing.
+   */
+  apiUnconfirmed?: true;
   /**
    * Character span of the sink's operation call in `file` (or the endpoint's file). This is the sink's
    * IDENTITY: flow analysis binds evidence to this exact call, never to a line or an enclosing

tests/map/corpus.test.ts

@@ -156,6 +156,28 @@ const ADVERSARIAL: Case[] = [
     // The schema's `post:id` is declared but never read by the sink — proven-nothing, not blockable.
     expectRefused: [['id', /no proven local read/]],
   },
+  {
+    name: 'adversarial: a traced package that does not establish the API',
+    kind: 'adversarial',
+    pkg: { dependencies: { express: '4', '@apollo/client': '3' } },
+    files: {
+      // `.query()` is a generic method name. An ApolloClient instance resolves to a REAL dependency, so
+      // attribution alone admits it — and a GraphQL call became a precise SQL-injection candidate. Package
+      // provenance is not API provenance.
+      'src/lib/gql.ts': `
+        import { ApolloClient } from "@apollo/client";
+        export const client = new ApolloClient({ uri: "https://api.example.com" });
+      `,
+      'src/server.ts': `
+        import express from "express";
+        import { client } from "./lib/gql";
+        const app = express();
+        app.post("/graphql", async (req, res) => { await client.query(req.body.sql); res.end(); });
+      `,
+    },
+    expectCandidates: [],
+    expectRefused: [['sql', /does not establish a db API/]],
+  },
   {
     name: 'adversarial: sibling expressions must not contaminate each other',
     kind: 'adversarial',
@@ -423,9 +445,9 @@ describe('golden corpus', () => {
   it('keeps a standing adversarial category (lookalikes are how every false candidate got in)', () => {
     // Guards against the category quietly emptying out; the classes listed are the ones that have
     // actually produced false candidates, so losing one should fail loudly.
-    expect(ADVERSARIAL.length).toBeGreaterThanOrEqual(6);
+    expect(ADVERSARIAL.length).toBeGreaterThanOrEqual(7);
     const names = ADVERSARIAL.map((c) => c.name).join(' | ');
-    for (const cls of ['collide with dangerous API names', 'untraceable receivers', 'shadowing dangerous globals', 'two request namespaces', 'sibling expressions', 'different namespaces']) {
+    for (const cls of ['collide with dangerous API names', 'untraceable receivers', 'shadowing dangerous globals', 'two request namespaces', 'sibling expressions', 'different namespaces', 'does not establish the API']) {
       expect(names, `missing adversarial class: ${cls}`).toContain(cls);
     }
   });

tests/map/imported-client.test.ts

@@ -121,3 +121,83 @@ describe('the project boundary still holds', () => {
     rmSync(outside, { recursive: true, force: true });
   });
 });
+
+// Package provenance is NOT API provenance. `.query()` is a generic method name: an `@apollo/client`
+// instance resolves to a genuine dependency while having nothing to do with SQL, and admitting that as a
+// database sink compiled a precise SQL-injection candidate for a GraphQL call — a rule that would block
+// legitimate traffic and mitigate nothing. This predates the imported-client hop (a same-file
+// `new ApolloClient()` hit it too); the hop only made it easier to reach.
+describe('a traced package must also establish the API', () => {
+  let d: string;
+  beforeAll(() => {
+    d = mkdtempSync(join(tmpdir(), 'ps-api-'));
+    mkdirSync(join(d, 'src', 'lib'), { recursive: true });
+    writeFileSync(join(d, 'package.json'), JSON.stringify({
+      dependencies: { express: '4', '@apollo/client': '3', pg: '8', 'drizzle-orm': '0.30' },
+    }));
+    writeFileSync(join(d, 'src', 'lib', 'gql.ts'), `
+      import { ApolloClient } from "@apollo/client";
+      export const client = new ApolloClient({ uri: "https://api.example.com" });
+    `);
+    writeFileSync(join(d, 'src', 'lib', 'pool.ts'), `
+      import { Pool } from "pg";
+      export const pool = new Pool();
+    `);
+    writeFileSync(join(d, 'src', 'lib', 'orm.ts'), `
+      import { drizzle } from "drizzle-orm/node-postgres";
+      export const orm = drizzle({});
+    `);
+    writeFileSync(join(d, 'src', 'server.ts'), `
+      import express from "express";
+      import { ApolloClient } from "@apollo/client";
+      import { client } from "./lib/gql";
+      import { pool } from "./lib/pool";
+      import { orm } from "./lib/orm";
+      const app = express();
+      const inline = new ApolloClient({ uri: "https://api.example.com" });
+      app.post("/gql-imported", async (req, res) => { await client.query(req.body.sql); res.end(); });
+      app.post("/gql-inline", async (req, res) => { await inline.query(req.body.sql); res.end(); });
+      app.post("/pg", async (req, res) => { await pool.query(req.body.sql); res.end(); });
+      app.post("/orm", async (req, res) => { await orm.execute(req.body.sql); res.end(); });
+    `);
+  });
+  afterAll(() => rmSync(d, { recursive: true, force: true }));
+
+  const route = async (r: string) => {
+    const { map } = await buildInputMap(d);
+    return map!.endpoints.find((e) => e.route === r)!;
+  };
+
+  it.each(['/gql-imported', '/gql-inline'])('refuses a rule for a non-DB client at %s', async (r) => {
+    const e = await route(r);
+    const sink = e.sinks.find((s) => s.kind === 'db')!;
+    expect(sink.package).toBe('@apollo/client');
+    expect(sink.attribution).toBe('import');   // the package IS established…
+    expect(sink.apiUnconfirmed).toBe(true);    // …but it does not establish a DB API
+    expect(sink.provider).toBeUndefined();     // so it does not get to call itself SQL either
+    const flow = e.flows.find((f) => f.sink.kind === 'db')!;
+    expect(flow.confidence).toBe('exact-local'); // the data really does reach it
+    expect(flow.ruleGeneratable).toBe(false);
+    expect(flow.candidateFamily).toBeUndefined(); // and it must not advertise a class it cannot support
+    expect(flow.ruleGeneratableReasons!.join(' ')).toMatch(/does not establish a db API/);
+  });
+
+  it('keeps the sink in the inventory — a .query() on an unknown client is worth a human look', async () => {
+    const e = await route('/gql-imported');
+    expect(e.sinks).toHaveLength(1);
+  });
+
+  it.each([
+    ['/pg', 'pg'],
+    ['/orm', 'drizzle-orm'],
+  ])('still generates for a real driver at %s', async (r, pkg) => {
+    const e = await route(r);
+    const sink = e.sinks.find((s) => s.kind === 'db')!;
+    expect(sink.package).toBe(pkg);            // subpath imports resolve to the package
+    expect(sink.apiUnconfirmed).toBeUndefined();
+    expect(sink.provider).toBe('sql');
+    const flow = e.flows.find((f) => f.sink.kind === 'db')!;
+    expect(flow.ruleGeneratable).toBe(true);
+    expect(flow.candidateFamily).toBe('sql-injection');
+  });
+});