openqodex 0.1.0

package/lenses/react-stale-closure-in-callback.md

@@ -0,0 +1,28 @@
+---
+name: react-stale-closure-in-callback
+description: Event handler / timer closure captures a stale state value
+triggers:
+  files:
+    - "*.tsx"
+    - "*.jsx"
+    - "**/*.tsx"
+    - "**/*.jsx"
+  hunk_regex: "\\b(setTimeout|setInterval|addEventListener|subscribe|on[A-Z]\\w+)\\b"
+confidence_floor: 0.75
+---
+
+A callback registered inside a render (event listener, `setTimeout`,
+`setInterval`, subscription, or memoized handler) reads `useState`
+values from the enclosing scope. Once registered, the closure keeps
+the **initial** state forever; later re-renders don't refresh it.
+The user sees "I clicked the new value but got the old one."
+
+Flag when the callback's body reads a useState variable AND the
+callback is registered outside an effect with that variable in its
+dependency list.
+
+Suppress when:
+- the value is accessed via a `useRef.current` indirection
+- the callback is re-registered each render via a `useEffect` with the
+  stateful deps listed (so the closure refreshes)
+- the value is provably immutable (initialized once, never reset)

package/lenses/react-state-set-in-render.md

@@ -0,0 +1,33 @@
+---
+name: react-state-set-in-render
+description: useState setter called during render body, infinite loop
+triggers:
+  files:
+    - "*.tsx"
+    - "*.jsx"
+    - "**/*.tsx"
+    - "**/*.jsx"
+  hunk_regex: "\\bset[A-Z]\\w*\\s*\\("
+confidence_floor: 0.75
+---
+
+A `useState` setter called from the top-level render body (not inside
+an event handler, effect, or callback) triggers a re-render, which
+calls the component again, which calls the setter again: an infinite
+re-render. React 18+ throws "Too many re-renders" but only at runtime,
+and only when the path is actually hit; conditional set-in-render
+escapes static analysis.
+
+Flag a `setX(...)` call placed:
+- at the top level of a functional component body
+- inside an `if` / ternary / short-circuit that has a chance of
+  evaluating to true on first render
+
+Suppress when the call is inside:
+- a `useEffect` / `useLayoutEffect` body
+- a handler returned from JSX (`onClick={() => setX(...)}`)
+- a `useState` initial-value function (`useState(() => ...)`)
+- the conditional `if (cond) { setX(prev => ...) }` "derive state from
+  props" pattern, where `cond` compares the prop to existing state
+  and is provably guarded (this is the React-docs-blessed escape
+  hatch; raise only if the guard looks broken)

package/lenses/react-use-effect-missing-cleanup.md

@@ -0,0 +1,29 @@
+---
+name: react-use-effect-missing-cleanup
+description: useEffect subscribes / starts a timer / opens a socket without returning a cleanup
+triggers:
+  files:
+    - "*.tsx"
+    - "*.jsx"
+    - "**/*.tsx"
+    - "**/*.jsx"
+  hunk_regex: "useEffect\\s*\\([\\s\\S]{0,400}?(addEventListener|setInterval|setTimeout|subscribe|new\\s+WebSocket|new\\s+EventSource|observe\\()"
+confidence_floor: 0.7
+---
+
+A `useEffect` registers a subscription, timer, observer, or event
+listener but never returns a cleanup function. When the component
+unmounts (or the effect re-runs because a dep changed) the
+side-effect keeps running against a stale component: a memory leak in
+the cheap case, double-fire in state-mutating handlers in the bad
+case, "can't update unmounted component" warnings either way.
+
+Flag when the effect body contains `addEventListener`, `setInterval`,
+`setTimeout`, a `.subscribe(`, `new WebSocket`, `new EventSource`, or
+a `MutationObserver` / `IntersectionObserver` / `ResizeObserver`
+without a matching `return () => { ... }` that removes / clears /
+unsubscribes / disconnects it.
+
+Suppress when the side-effect is intentionally one-shot and the
+target lives at most as long as the component (e.g. a `setTimeout`
+whose handler navigates away unconditionally).

package/lenses/react-use-effect-missing-deps.md

@@ -0,0 +1,30 @@
+---
+name: react-use-effect-missing-deps
+description: useEffect / useMemo / useCallback with an incomplete dependency array
+triggers:
+  files:
+    - "*.tsx"
+    - "*.jsx"
+    - "**/*.tsx"
+    - "**/*.jsx"
+  hunk_regex: "\\b(useEffect|useMemo|useCallback|useLayoutEffect)\\s*\\("
+confidence_floor: 0.75
+---
+
+A `useEffect` / `useMemo` / `useCallback` hook reads a value from
+component scope (state, props, derived variable, function) but omits
+it from the dependency array. On re-render the closure captures the
+stale value and the effect either runs against outdated data, never
+re-runs when it should, or memoizes incorrectly.
+
+Flag when the hook's body references an identifier that is **not** in
+its second-argument array and is **not** stable across renders
+(`useRef.current`, module-level constant, dispatch from `useReducer`,
+setter returned by `useState`).
+
+Suppress when:
+- the deps array is omitted entirely (then it runs every render, a
+  different bug, but separate finding)
+- the referenced identifier is a setter / ref / constant
+- a lint comment explicitly disables `react-hooks/exhaustive-deps`
+  with a justification on the line above

package/lenses/regexp-from-user-input.md

@@ -0,0 +1,43 @@
+---
+name: regexp-from-user-input
+description: new RegExp(...) built from user input, ReDoS / injection
+triggers:
+  files:
+    - "*.ts"
+    - "*.tsx"
+    - "*.js"
+    - "*.jsx"
+    - "*.mjs"
+    - "*.cjs"
+    - "**/*.ts"
+    - "**/*.tsx"
+    - "**/*.js"
+    - "**/*.jsx"
+    - "**/*.mjs"
+    - "**/*.cjs"
+  hunk_regex: "new\\s+RegExp\\s*\\("
+security: true
+confidence_floor: 0.7
+---
+
+`new RegExp(input)` is called with a value derived from request
+input. Two problems:
+1. **ReDoS**: a crafted input like `(a+)+$` chained with a long
+   string of `a`'s freezes the V8 regex engine, hanging the request
+   thread (a single attacker can take down the API with one call).
+2. **Regex injection**: the input redefines the search semantics:
+   `.*` instead of the literal dot the dev expected.
+
+Flag when the first argument to `new RegExp(...)` is a value
+sourced from `req.body|req.query|req.params|form input|env`.
+
+Suppress when:
+- the input has been run through `escapeRegExp` (treats it as a
+  literal pattern)
+- the regex compile is bounded by a length check (`if (input.length
+  > 64) return 400`) and a complexity-aware runtime (`re2` library,
+  which is linear-time)
+- the input is matched against an allow-list before compile
+- the regex is for a non-blocking single-shot search against a
+  bounded short string (still recommend escapeRegExp, but the DoS
+  window is closed)

package/lenses/return-shape-contract-break.md

@@ -0,0 +1,71 @@
+---
+name: return-shape-contract-break
+description: A function/endpoint that returns a structured object drops or renames a key/column its callers read
+triggers:
+  files:
+    - "*.sql"
+    - "**/*.sql"
+    - "*.ts"
+    - "*.tsx"
+    - "*.js"
+    - "*.jsx"
+    - "**/*.ts"
+    - "**/*.tsx"
+    - "**/*.js"
+    - "**/*.jsx"
+  hunk_regex: "jsonb_build_object|json_build_object|jsonb_agg|json_agg|RETURNS\\s+(jsonb|json|TABLE|record|setof)|return\\s+\\{|res\\.json\\(|c\\.json\\(|\\bNextResponse\\.json\\("
+confidence_floor: 0.7
+---
+
+A function, RPC, or endpoint that returns a structured payload (a
+`jsonb_build_object` / `json_agg` in SQL, a returned object literal,
+a `res.json(...)` / `c.json(...)` / `NextResponse.json(...)` body, a
+`RETURNS TABLE`/composite shape) has the SET OF KEYS it returns
+CHANGED by this diff: a key or column present on the `-` side is gone
+or renamed on the `+` side. Removing or renaming a field from a
+payload something already consumes is a silent breaking change: every
+reader that referenced the old key now gets `undefined` / `NULL`, and
+nothing in the producing file errors, so the diff reads clean in
+isolation.
+
+This is the highest-recall way to miss a real bug on an otherwise
+tidy refactor. The evidence is the SHAPE of the returned document
+across the diff, not the logic inside it: compare the keys emitted on
+the `-` side against the `+` side, key by key.
+
+Flag when this diff:
+- removes a key from a `jsonb_build_object` / object literal /
+  response body that the previous version emitted, OR
+- renames such a key (old name vanishes, new name appears), OR
+- drops a column from a `RETURNS TABLE` / view / `SELECT *`-feeding
+  shape,
+
+AND you cannot see, within the diff, that every consumer of the old
+key was also removed. Trace the consumer when you can (search for the
+key name, the RPC/function name, or the endpoint path); a removed key
+that is still read downstream is a `major` breaking change. When the
+consumer is out of the diff and you cannot confirm it was updated,
+still raise it; default to "this breaks a contract" rather than
+assuming the caller was migrated.
+
+A strong corroborating signal: the diff also DELETES a comment or
+doc that asserted the contract (e.g. a comment promising keys are
+"additive" / "kept for back-compat" / "stable"). When a PR removes
+language that promised stability and the code then breaks it, that is
+a high-confidence flag; read the removed comments, not just the
+removed code.
+
+Suppress when:
+- the diff also removes (or the change description states it
+  removes) every consumer of the dropped key; a coordinated removal is not a
+  break,
+- the key is renamed AND the diff updates the readers in the same
+  change,
+- the payload is brand-new in this change (no prior `-` side), so there
+  is no existing contract to break,
+- the field is internal/never-serialized (e.g. a temp variable in a
+  CTE that was never part of the returned object).
+
+Severity: `major` when a removed/renamed key is consumed by code
+outside the diff (real break); `minor` when the consumer is unclear
+but the field plausibly mattered.

package/lenses/secrets-logged-in-error-path.md

@@ -0,0 +1,60 @@
+---
+name: secrets-logged-in-error-path
+description: Error / catch path logs an object that includes secrets, tokens, or request headers
+triggers:
+  files:
+    - "*.ts"
+    - "*.tsx"
+    - "*.js"
+    - "*.jsx"
+    - "*.mjs"
+    - "*.cjs"
+    - "*.py"
+    - "*.go"
+    - "*.rb"
+    - "*.java"
+    - "*.kt"
+    - "**/*.ts"
+    - "**/*.tsx"
+    - "**/*.js"
+    - "**/*.jsx"
+    - "**/*.mjs"
+    - "**/*.cjs"
+    - "**/*.py"
+    - "**/*.go"
+    - "**/*.rb"
+    - "**/*.java"
+    - "**/*.kt"
+  hunk_regex: "catch\\s*\\(|console\\.(log|error|warn)|logger\\.(error|warn|info)|log\\.(error|warn|info)|printStackTrace\\s*\\("
+security: true
+confidence_floor: 0.7
+---
+
+An error / catch handler logs an object that includes credentials,
+authorization headers, API keys, request bodies (which may include
+passwords), or full HTTP request/response payloads. These show up
+in log aggregators (Datadog, Sentry, CloudWatch) where engineers,
+support, or third-party integrations can read them: a compliance
+issue at minimum, a credential-leak vector at worst.
+
+Flag when a log call inside a catch / error path passes:
+- a full `req` / `request` / `ctx.request` object
+- a full `error` whose properties include request headers /
+  response bodies (look for axios / fetch error shapes: `err.config.headers`,
+  `err.response.config.headers`)
+- a literal `password` / `token` / `secret` / `api_key` / `apiKey`
+  variable
+- environment-derived secrets
+
+Suppress when:
+- the log payload is the explicit error message string only
+- the object is passed through a redaction layer (`pino` with
+  `redact`, `winston` with format filter, custom `scrubSecrets`
+  helper), visible on the same call or in the logger setup
+- the only fields included are explicitly safe ones (status code,
+  method, path, user id)
+
+In Java and Kotlin the idiom is `e.printStackTrace()` or
+`logger.error(message, e)` where the exception, or an object logged
+beside it, carries the request headers, an `Authorization` value or a
+provider token.

package/lenses/sql-migration-references-later-object.md

@@ -0,0 +1,47 @@
+---
+name: sql-migration-references-later-object
+description: A migration references a column/table/function created by a later-timestamped migration (fails on fresh apply)
+triggers:
+    # Both forms: "**/" compiles to ".*/", which requires a slash before
+    # "migrations", so it covers nested dirs (supabase/migrations/...,
+    # db/migrations/...) but NOT a root-level migrations/ dir. The bare
+    # "migrations/*.sql" pattern catches that case, same dual-pattern
+    # convention the *.sql / **/*.sql lenses use.
+  files:
+    - "migrations/*.sql"
+    - "**/migrations/*.sql"
+  hunk_regex: '@include|\breferences\b|\balter\s+table\b|\badd\s+column\b|\bcreate\s+(or\s+replace\s+)?(view|function|trigger|policy)\b|\bjoin\b'
+confidence_floor: 0.75
+---
+
+Migrations apply in timestamp (filename) order. Code that runs fine
+against an already-migrated database can still break a fresh apply
+(`supabase db reset`, a clean prod deploy, CI) if a migration references
+a schema object (a column, table, type, function, policy) that is only
+created by a migration with a LATER timestamp. The bug is invisible
+locally because the object already exists; it only surfaces on a
+from-scratch run.
+
+This is especially easy to introduce with `@include`-style migrations: a
+migration that `@include`s a function file inherits every object that
+function selects/joins. If that function references a column added in a
+later migration, this migration fails first.
+
+Flag when a migration in this diff (or a function/file it `@include`s)
+references an object whose creating/altering statement lives in a
+migration timestamped AFTER this one. To check: identify the referenced
+columns/tables/functions, then search the migrations directory for where
+each is created (`ADD COLUMN`, `CREATE TABLE/FUNCTION/TYPE`) and compare
+filename timestamps. Use your tools; this needs reading files outside
+the diff.
+
+Suppress when:
+- every referenced object is created in an earlier or same-timestamp
+  migration,
+- the object is a Postgres built-in, an extension object, or created
+  outside the migrations dir (e.g. a baseline/squash schema that always
+  applies first),
+- the reference is inside a string/comment, not executed SQL.
+
+Severity: `major`: a deterministic fresh-apply / CI failure, not a
+runtime edge case.

package/lenses/sql-string-concatenation.md

@@ -0,0 +1,63 @@
+---
+name: sql-string-concatenation
+description: SQL built via string concatenation / template-string interpolation of unsanitized input
+triggers:
+  files:
+    - "*.ts"
+    - "*.tsx"
+    - "*.js"
+    - "*.jsx"
+    - "*.mjs"
+    - "*.cjs"
+    - "*.py"
+    - "*.go"
+    - "*.rb"
+    - "*.java"
+    - "*.kt"
+    - "*.cs"
+    - "*.php"
+    - "**/*.ts"
+    - "**/*.tsx"
+    - "**/*.js"
+    - "**/*.jsx"
+    - "**/*.mjs"
+    - "**/*.cjs"
+    - "**/*.py"
+    - "**/*.go"
+    - "**/*.rb"
+    - "**/*.java"
+    - "**/*.kt"
+    - "**/*.cs"
+    - "**/*.php"
+  hunk_regex: "\\b(SELECT|INSERT|UPDATE|DELETE|WHERE|VALUES)\\b|createStatement\\s*\\(|executeQuery\\s*\\(|create(Native)?Query\\s*\\("
+security: true
+confidence_floor: 0.75
+---
+
+A raw SQL string is built by concatenating / interpolating a
+variable into the query. If the variable's value traces back to a
+user input, request parameter, environment variable, or any
+external source, this is SQL injection. The diff often hides this
+behind innocuous helpers (`buildWhere(...)`, `paramFilter(...)`).
+
+Flag when:
+- `SELECT|INSERT|UPDATE|DELETE|WHERE` literal appears in a string
+  built with `+ var`, `${var}`, `format(...)`, `.format(...)`,
+  `f"..."`, or `sprintf` against a variable whose provenance is not
+  a hardcoded constant
+- the variable comes from `req.body|req.query|req.params|args|
+  argv|env|input`
+
+Suppress when:
+- the query uses parameter placeholders (`$1`, `?`, `:name`) with
+  bound values
+- the ORM call is the parameterized path (Drizzle's `eq`/`and`,
+  Kysely's `.where(col, '=', val)`, Prisma's `where: {col: val}`)
+- the interpolated value is an IDENTIFIER (table/column) and the
+  identifier is sourced from an allow-list / enum check earlier in
+  the function (still raise if you can't see the check)
+
+In Java and Kotlin the idiom is `createStatement()` plus
+`executeQuery("... " + value)`, or a JPA `createQuery` /
+`createNativeQuery` string glued together, where `prepareStatement`
+with bind parameters is the fix.

package/lenses/ssrf-server-side-fetch.md

@@ -0,0 +1,69 @@
+---
+name: ssrf-server-side-fetch
+description: Server-side HTTP request whose host or URL comes from user input
+triggers:
+  files:
+    - "*.ts"
+    - "*.tsx"
+    - "*.js"
+    - "*.mjs"
+    - "*.py"
+    - "*.rb"
+    - "*.go"
+    - "*.java"
+    - "*.kt"
+    - "**/*.ts"
+    - "**/*.tsx"
+    - "**/*.js"
+    - "**/*.mjs"
+    - "**/*.py"
+    - "**/*.rb"
+    - "**/*.go"
+    - "**/*.java"
+    - "**/*.kt"
+  hunk_regex: "fetch\\(|axios\\.|http\\.get|requests\\.(get|post)|urllib|HttpClient|RestTemplate|WebClient|Net::HTTP|http\\.NewRequest"
+security: true
+confidence_floor: 0.75
+---
+
+The server makes an HTTP request, and the host or the whole URL comes
+from a request field, a header, or a value a user stored earlier
+(a webhook target, an avatar URL, an "import from URL" box, a
+provider's base URL held in a settings row). The attacker then chooses
+where your server connects. Inside a cloud network that reaches the
+instance metadata endpoint (`169.254.169.254`), internal admin services
+on private ranges, and anything listening on localhost, none of which
+is reachable from the internet, which is exactly why they are
+unauthenticated.
+
+What to check before flagging:
+
+- Where the host comes from. Trace the value back: a request body or
+  query field, a header, or a stored row a user controls all count. A
+  constant base URL with only a path segment from input does not.
+- Whether the host is allow-listed against an explicit set, and whether
+  the check runs on the URL that is finally fetched rather than on a
+  copy parsed earlier.
+- Whether the scheme is pinned to http or https, so `file://`,
+  `gopher://` and friends are refused.
+- Whether private, loopback and link-local ranges are refused after DNS
+  resolution, not just by a string check on the hostname.
+- Whether redirects are followed. An allow-listed host that answers 302
+  to `http://169.254.169.254/` defeats a host check done once up front.
+
+What to cite: the line making the request, quoted whole with file and
+line, and, as supporting quotes, the line the untrusted host arrives on
+and any validation you did find, so the finding shows what guard is
+missing rather than asserting there is none.
+
+Suppress when:
+
+- the base URL is a constant or comes from configuration and only a path
+  or query value comes from input
+- the value is checked against an allow-list of hosts, or resolved and
+  checked against blocked ranges, before the request
+- the request goes through a proxy or fetch helper in the repository
+  that does those checks (find it and read it before deciding)
+
+A request with a trusted host and no timeout is a different problem:
+that is the `fetch-without-timeout` lens, not this one.

package/lenses/supabase-comment-on-function-unqualified.md

@@ -0,0 +1,37 @@
+---
+name: supabase-comment-on-function-unqualified
+description: COMMENT ON FUNCTION uses an unqualified name while the function is created schema-qualified
+triggers:
+  files:
+    - "*.sql"
+    - "**/*.sql"
+  hunk_regex: 'COMMENT\s+ON\s+FUNCTION'
+confidence_floor: 0.75
+---
+
+`COMMENT ON FUNCTION <name>(<args>)` resolves `<name>` against the
+applying session's `search_path` at migration time. When the function
+is created schema-qualified (`CREATE ... FUNCTION public.foo(...)`) but
+the comment names it unqualified (`COMMENT ON FUNCTION foo(...)`), the
+statement fails with `function ... does not exist` on any session whose
+`search_path` doesn't include that schema, and it's inconsistent with
+the qualified `CREATE`. A function-body `SET search_path = public,
+pg_temp` does NOT help: that governs the function's own runtime, not the
+session running the `COMMENT`.
+
+Flag when, in this diff, a `COMMENT ON FUNCTION` names a function
+unqualified while the corresponding `CREATE [OR REPLACE] FUNCTION` (in
+the same file or the migration it includes) is schema-qualified, OR when
+it diverges from the repo's prevailing convention (search sibling
+`COMMENT ON FUNCTION` statements; most will use `public.`).
+
+Suppress when:
+- the comment is already schema-qualified to match the CREATE,
+- the function is genuinely created unqualified and the repo convention
+  is unqualified comments throughout,
+- the migration explicitly `SET search_path` for the statement scope.
+
+Severity: `minor` (apply-time failure is gated on the runner's
+search_path, which in Supabase's standard runner is usually `public`, so
+it often won't fire in practice, but it's a real consistency/robustness
+defect).

package/lenses/supabase-function-default-public-execute.md

@@ -0,0 +1,50 @@
+---
+name: supabase-function-default-public-execute
+description: A new/replaced Postgres function exposed via PostgREST is left with the default PUBLIC EXECUTE grant
+triggers:
+  files:
+    - "*.sql"
+    - "**/*.sql"
+  hunk_regex: 'CREATE\s+(OR\s+REPLACE\s+)?FUNCTION'
+confidence_floor: 0.7
+---
+
+Postgres grants `EXECUTE` to `PUBLIC` by default on every new function.
+In Supabase, PostgREST exposes any function in an exposed schema
+(usually `public`) as an RPC endpoint (`POST /rest/v1/rpc/<fn>`)
+callable by the `anon` and `authenticated` roles. So a `CREATE [OR
+REPLACE] FUNCTION public.<fn>` that returns privileged data or performs
+a privileged action, with no accompanying grant management, is callable
+by anyone holding an anon/JWT key, even if the only intended caller is
+an admin-gated Edge Function using `service_role`.
+
+Flag when this diff adds or replaces a function in an exposed schema AND
+does NOT also `REVOKE EXECUTE ... FROM PUBLIC` (and grant EXECUTE only
+to the intended role, e.g. `service_role` / `authenticated`). The risk
+is highest when:
+- the name or comment signals admin/internal scope (`admin_*`,
+  `internal_*`, "admin-only", "backend"), or
+- the body reads instance-wide / cross-tenant tables (users, teams,
+  billing, activity, metrics) rather than the caller's own rows.
+
+`SECURITY INVOKER` (the default) reduces but does not remove the risk:
+RLS on the base tables only helps if RLS is actually enabled on every
+table the function touches, and the RPC endpoint is still reachable.
+Treat a missing `REVOKE PUBLIC` on a privileged function as a finding;
+recommend `REVOKE EXECUTE ON FUNCTION public.<fn>(...) FROM PUBLIC;`
+plus an explicit `GRANT` to the intended role.
+
+Suppress when:
+- the diff (or the same migration) already revokes PUBLIC and grants the
+  intended role,
+- the function returns only public, non-sensitive data and is meant to
+  be world-callable,
+- the repo has an established global migration / convention that revokes
+  PUBLIC EXECUTE on all functions (verify it exists before staying
+  silent),
+- the change is purely cosmetic (renamed param, comment) on a function
+  whose grants were already managed.
+
+Severity: `major` when an admin/privileged function is left
+PUBLIC-callable; `minor` for defense-in-depth hardening on a
+non-sensitive one.

package/lenses/supabase-security-definer-no-search-path.md

@@ -0,0 +1,34 @@
+---
+name: supabase-security-definer-no-search-path
+description: A SECURITY DEFINER function omits a pinned SET search_path, allowing search_path hijack / privilege escalation
+triggers:
+  files:
+    - "*.sql"
+    - "**/*.sql"
+  hunk_regex: 'SECURITY\s+DEFINER'
+confidence_floor: 0.7
+---
+
+A `SECURITY DEFINER` function runs with the privileges of its owner, not
+the caller. If it does not pin its `search_path`, a caller can set their
+own `search_path` so that unqualified object references inside the
+function resolve to attacker-controlled objects (a shadowing table,
+function, or operator) in a schema the caller can write, executed with
+the owner's elevated rights. This is the Postgres privilege-escalation
+footgun that Supabase's own linter flags as
+`function_search_path_mutable`.
+
+Flag a `CREATE [OR REPLACE] FUNCTION ... SECURITY DEFINER` added or
+modified in this diff that does NOT include a fixed
+`SET search_path = ...` (e.g. `SET search_path = pg_catalog, public` or
+`= ''` with fully-qualified references). Also flag when `search_path` is
+set to something a caller can still influence.
+
+Suppress when:
+- the function pins `SET search_path` to a fixed value, OR
+- every object reference in the body is already fully schema-qualified
+  AND `search_path` is set, OR
+- the function is `SECURITY INVOKER` (the default); invoker functions
+  run as the caller, so this escalation doesn't apply.
+
+Severity: `major` (privilege escalation on a definer function).

package/lenses/supabase-single-500-on-no-match.md

@@ -0,0 +1,65 @@
+---
+name: supabase-single-500-on-no-match
+description: Supabase `.single()` on a query that can legitimately return zero rows, throws PGRST116 and bubbles up as a 500
+triggers:
+  files:
+    - "*.ts"
+    - "*.tsx"
+    - "*.js"
+    - "*.jsx"
+    - "*.mjs"
+    - "*.cjs"
+    - "**/*.ts"
+    - "**/*.tsx"
+    - "**/*.js"
+    - "**/*.jsx"
+    - "**/*.mjs"
+    - "**/*.cjs"
+  hunk_regex: "\\.single\\(\\)|\\bfrom\\([^)]*\\)\\s*\\.|supabase\\.from"
+confidence_floor: 0.8
+---
+
+A Supabase query chain ends in `.single()` against a row that may
+not exist (lookup by `id` from a request param, `.eq("user_id",
+…)` where the caller may pass an unknown id, etc.). `.single()`
+throws PostgREST error `PGRST116` ("Cannot coerce the result to
+a single JSON object") when the row count is anything other than
+exactly 1. In an edge function, that error bubbles into a 500
+when the correct response is a 404, and the caller can't distinguish
+"the thing you asked for doesn't exist" from "the server broke."
+
+Flag when this diff adds (or modifies into) a Supabase query that:
+- ends in `.single()`,
+- selects / updates / deletes by an identifier (`eq("id", …)`,
+  `eq("user_id", …)`, `match({...})`),
+- where the identifier traces back to a request parameter
+  (`req.params`, `req.query`, `req.body`, `req.url`, the parsed
+  payload of an edge function),
+- AND the surrounding code does NOT catch `PGRST116` / does NOT
+  check `error.code === "PGRST116"` to map to a 404.
+
+Examples that should fire:
+- `await supabase.from("activities").update({...}).eq("id", id).single()`
+  with no PGRST116 → 404 handling
+- `await supabase.from("users").select("*").eq("email", req.body.email).single()`
+- `await supabase.from("teams").delete().eq("id", req.params.teamId).single()`
+
+Suggested fix in the description:
+- Swap `.single()` for `.maybeSingle()` (returns `{data: null,
+  error: null}` on zero rows) and have the handler return 404
+  when `data === null`, OR
+- Keep `.single()` and catch `error.code === "PGRST116"`
+  explicitly, mapping to a 404 response.
+
+Suppress when:
+- the query is filtered by a column with a unique constraint AND
+  the caller has already proven the row exists earlier in the
+  request (e.g. an auth middleware fetched the user row by id),
+- the surrounding code already handles `PGRST116` (look for the
+  literal `"PGRST116"` string in the catch or in an
+  `error.code ===` check),
+- the function uses `.maybeSingle()` instead.
+
+Severity: `major`: a 500 on a missing row is a real user-facing
+bug (looks like an outage) and a real auditing problem (alerts
+fire on 5xx, not on 404).