[pull] master from supabase:master

.claude/skills/safe-sql-execution/SKILL.md

@@ -0,0 +1,378 @@
+---
+name: safe-sql-execution
+description: Safely execute SQL queries against a user database without risking SQL injection or other security vulnerabilities.
+---
+
+# Safe SQL execution
+
+Supabase Studio executes SQL statements directly against the user's database.
+Because this is the authenticated user's own database, our security model is
+different from most frontend applications: a user should be able to execute any
+SQL statement, as long as it is proven that they themselves authored it. What
+we SHOULD NOT ALLOW is execution of SQL statements that can be influenced by an
+attacker, such as through URL parameters.
+
+## Security model
+
+The security model for SQL execution in Supabase Studio is based on the
+principle of "proven authorship". This means that a user should only be able to
+execute SQL statements that they have explicitly authored, and not statements
+that can be influenced by external input.
+
+There are three classes of SQL fragments:
+
+1.  Hardcoded within the application code. These are safe to execute because
+    they cannot be influenced by an attacker. They can be marked with the
+    `safeSql` utility with `pg-meta`:
+
+    ```ts
+    import { safeSql } from '@supabase/pg-meta'
+
+    const sql = safeSql`
+      SELECT *
+      FROM users
+      WHERE id = 1
+    `
+    ```
+
+    `safeSql` automatically creates a string of the branded type
+    `SafeSqlFragment`. (See Provenance Tracking below.)
+
+2.  Third-party influenceable. These are SQL fragments that can be influenced
+    by an attacker, such as through URL parameters or LLM output. These should
+    be marked with the `untrustedSql` utility with `pg-meta`:
+
+    ```ts
+    import { untrustedSql } from '@supabase/pg-meta'
+
+    const unsafeQuery = searchParams.get('query')
+    const querySql = untrustedSql(unsafeQuery)
+    ```
+
+    `untrustedSql` creates a string of the branded type `UntrustedSqlFragment`.
+    (See Provenance Tracking below.)
+
+3.  User-authored. These are SQL fragments that are authored by the user
+    themselves within the UI, for example in a text input field. Because the
+    user is the author, these should be considered safe to execute.
+
+    However, there is a caveat, where third-party and user-authored code can
+    mix, contaminating the user-authored code (for example, if an input is
+    prefilled from an unsanitized URL parameter). Provenance tracking helps us
+    track these cases.
+
+    For example, a safe input component could be implemented as follows by requiring that its placeholder and controlled value are of type `SafeSqlFragment`. In this case we can use its onChange to promote the user input to `SafeSqlFragment` type, because we know that the user is the author of the input. An implementation of this is in
+    @apps/studio/components/ui/SafeSqlInput.tsx:
+
+    ```ts
+    import { rawSql, type SafeSqlFragment } from '@supabase/pg-meta'
+    import type { ChangeEvent, ComponentProps } from 'react'
+    import { Input } from 'ui-patterns/DataInputs/Input'
+
+    type InputProps = ComponentProps<typeof Input>
+
+    export type SafeSqlInputProps = Omit<
+      InputProps, 'placeholder' | 'value' | 'onChange'
+    > & {
+      placeholder?: SafeSqlFragment
+      value: SafeSqlFragment
+      onChange?:
+        (event: ChangeEvent<HTMLInputElement>, value: SafeSqlFragment) => void
+    }
+
+    export const SafeSqlInput = ({ onChange, ...props }: SafeSqlInputProps) => (
+      <Input
+        {...props}
+        onChange={(event) => onChange?.(event, rawSql(event.target.value))}
+      />
+    )
+    ```
+
+    This is pretty much the ONLY VALID USE CASE of the rawSql export from
+    pg-meta, and it should be used with caution.
+
+## Provenance tracking
+
+Branded types are used to track the provenance of SQL fragments. The types,
+exported from `pg-meta`, are:
+
+- `SafeSqlFragment`: represents SQL fragments that are safe to execute, because
+  they are either hardcoded in the application or authored by the user
+  themselves.
+- `UntrustedSqlFragment`: represents SQL fragments that can be influenced by an
+  attacker, such as through URL parameters or LLM output.
+
+These are valid ways to generate a `SafeSqlFragment`:
+
+- Using the `safeSql` utility from `pg-meta` to create hardcoded SQL fragments.
+- Using the sanitization utilities from `pg-meta` to sanitize untrusted input
+  and promote it to a `SafeSqlFragment`:
+  - `ident`
+  - `literal`
+  - `keyword`
+- Using the safe SQL manipulation utilities:
+  - `joinSqlFragments`
+  - `trimSafeSqlFragment`
+
+`UntrustedSqlFragments` can be generated from raw strings using
+`untrustedSql()`.
+
+There is also a union type, `DisplayableSqlFragment`, which represents SQL fragments that can be safely displayed in the UI, but not necessarily executed. This includes both `SafeSqlFragment` and `UntrustedSqlFragment`.
+
+## Security of SQL round-tripped from the user's database
+
+SQL derived directly from catalog tables (e.g., function definitions, RLS
+expressions, etc.) is considered safe, and it is promoted AT THE POINT OF
+BEING QUERIED from the database. In most cases, this is in an
+apps/studio/data/\*_/_.ts file, in the utility function that makes the API or
+database fetch.
+
+A critical exception to the safety of SQL round-tripped from the database is
+user snippets. These must NEVER BE CONSIDERED SAFE because they are both (a)
+externally influenceable and (b) auto-saved. The snippet type uses the
+`unchecked_sql` property, which is an `UntrustedSqlFragment`, to enforce this.
+
+## Promoting SQL fragments to `SafeSqlFragment` type
+
+Given an insecure string or `UntrustedSqlFragment`, how do we promote it safely
+to a `SafeSqlFragment`?
+
+### Sanitization utilities
+
+This is the preferred method when the input is sanitizable, e.g., it is a
+relation name, a column name, will be compared as a literal, etc.
+
+The pg-meta library provides the following sanitization utilities that can be
+used to safely promote untrusted input to `SafeSqlFragment`:
+
+- `ident`: for sanitizing identifiers such as table names or column names.
+- `literal`: for sanitizing literal values that will be used in SQL statements.
+- `keyword`: for sanitizing SQL keywords.
+
+### `acceptUntrustedSql`
+
+Some untrusted SQL fragments cannot be sanitized with the above utilities. For
+example, the `USING` expression in the RLS policy editor is an arbitrary SQL
+expression.
+
+In these cases, we can promote the SQL fragment _upon explicit user action_.
+User action indicates that the user has seen the SQL and is OK with running it.
+For example, an explicit user action could be clicking a "Run" button.
+
+The promotion happens with the `acceptUntrustedSql` utility from `pg-meta`,  
+which takes an `UntrustedSqlFragment` and returns a `SafeSqlFragment`.
+
+This utility MUST ONLY BE USED IN event handlers. It should NEVER be used in
+a useQuery, direct in the render body of a component, in a useEffect, or
+anywhere it could auto-run without explicit user action.
+
+This is safe:
+
+```ts
+import { acceptUntrustedSql } from '@supabase/pg-meta'
+
+function SafeComponent() {
+  const { mutate: execute } = useExecuteSqlMutation()
+
+  const handleRun = () => {
+    // ✅ GOOD: Safe because it is in an event handler which requires a user
+    // click
+    execute({ sql: acceptUntrustedSql(/* sql */) })
+  }
+
+  return (
+    <button onClick={handleRun}>Run</button>
+  )
+}
+```
+
+This is unsafe:
+
+```ts
+import { acceptUntrustedSql } from '@supabase/pg-meta'
+
+function UnsafeComponent() {
+  const { data } = useQuery({
+    queryKey: ['execute-sql', sql],
+    queryFn: () => {
+      // 🛑 BAD: Unsafe because it is in a query which could auto-run without
+      // explicit user action
+      return execute({ sql: acceptUntrustedSql(/* sql */) })
+    },
+  })
+}
+```
+
+## Type guarantees
+
+SQL run against the user's Postgres database runs through the `executeSql`
+function, which only takes arguments of type `SafeSqlFragment` for the SQL
+parameter. Raw strings or `UntrustedSqlFragment`s will error at compile time.
+
+## Examples
+
+### Hard-coded SQL
+
+```ts
+// ✅ GOOD: Automatically safe with `safeSql` utility
+const selectStatement = safeSql`select 1`
+```
+
+### SQL with sanitizable interpolations
+
+```ts
+// ✅ GOOD: `pg-meta` utilities sanitize the input
+const tableName = ident(userInputTableName)
+const searchString = literal(userInputSearchString)
+const sqlStatement = safeSql`
+  SELECT *
+  FROM ${tableName}
+  WHERE search_column = ${searchString}
+`
+```
+
+```ts
+// 🛑 BAD: Passing raw strings will type error
+const tableName = 'my_table'
+const sqlStatement = safeSql`
+  SELECT *
+  FROM ${tableName}
+`
+```
+
+### Non-sanitizable SQL from a user input
+
+```ts
+// ✅ GOOD: SafeSqlInput only allows a value that is a SafeSqlFragment
+import { SafeSqlInput } from '@apps/studio/components/ui/SafeSqlInput'
+
+function MyComponent() {
+  const [sql, setSql] = useState<SafeSqlFragment>(safeSql``)
+
+  return (
+    <SafeSqlInput
+      placeholder={safeSql`Enter your SQL query here...`}
+      value={sql}
+      onChange={(event, value) => setSql(value)}
+    />
+  )
+}
+```
+
+```ts
+// 🛑 BAD: This input mixes SafeSqlFragments and unsafe strings
+
+function MyBadComponent() {
+  const [sql, setSql] = useState<SafeSqlFragment>(safeSql``)
+
+  return (
+    <Input
+    // 🛑 BAD: This is unsafe because the placeholder is a raw string
+      placeholder="Enter your SQL query here..."
+      value={sql}
+      onChange={(event) => setSql(event.target.value)}
+    />
+  )
+}
+```
+
+### Round-tripping SQL from the database (NOT snippet content)
+
+```ts
+// ✅ GOOD: SQL from the database is promoted to SafeSqlFragment at the point 
+// of fetching
+
+// data/function-definitions.ts
+function markFunctionDefinitionSafe(
+  functionDefinition: FunctionDefinition
+): SafeFunctionDefinition {
+  return {
+    ...functionDefinition,
+    definition: functionDefinition.definition as SafeSqlFragment,
+  }
+}
+
+// data/function-definitions.ts
+function getFunctionDefinitions() {
+  return GET(`/function-definitions`).then((functionDefinitions) =>
+    functionDefinitions.map(markFunctionDefinitionSafe)
+  )
+}
+```
+
+```ts
+// 🛑 BAD: Strings are promoted to SafeSqlFragment in a utility function, where
+// it is impossible to easily determine the safety of the input
+
+// utils.ts
+function markFunctionDefinitionSafe(
+  functionDefinition: FunctionDefinition
+): SafeFunctionDefinition {
+  return {
+    ...functionDefinition,
+    definition: functionDefinition.definition as SafeSqlFragment,
+  }
+}
+
+// Component.ts
+function MyComponent() {
+  const { data: functionDefinitions } = useFunctionDefinitions()
+  const safeFunctionDefinitions = functionDefinitions.map(markFunctionDefinitionSafe)
+}
+```
+
+### Snippet content is ALWAYS UNSAFE
+
+Snippets are auto-persisted to the database and can be created or modified 
+through externally influenceable channels (e.g., prefilled from URL params). 
+The `unchecked_sql` property is typed as `UntrustedSqlFragment` to enforce this 
+— it must only be promoted to `SafeSqlFragment` via `acceptUntrustedSql` in an 
+event handler that requires explicit user action.
+
+```ts
+// 🛑 BAD: Snippet content is executed automatically via useQuery, with no
+// explicit user action confirming that the user has reviewed the SQL.
+import { acceptUntrustedSql } from '@supabase/pg-meta'
+
+function UnsafeSnippetPreview({ snippet }: { snippet: Snippet }) {
+  const { data } = useExecuteSqlQuery({
+    sql: acceptUntrustedSql(snippet.content.unchecked_sql),
+  })
+
+  return <Results data={data} />
+}
+```
+
+```ts
+// 🛑 BAD: Casting bypasses the type system entirely. The snippet's
+// `unchecked_sql` is `UntrustedSqlFragment` for a reason — never cast it.
+function UnsafeSnippetRunner({ snippet }: { snippet: Snippet }) {
+  const { mutate: execute } = useExecuteSqlMutation()
+
+  useEffect(() => {
+    execute({ sql: snippet.content.unchecked_sql as SafeSqlFragment })
+  }, [snippet])
+}
+```
+
+```ts
+// ✅ GOOD: Snippet content is only promoted to SafeSqlFragment inside an event
+// handler, after the user clicks Run. The user has seen the SQL in the editor
+// and explicitly chosen to execute it.
+import { acceptUntrustedSql } from '@supabase/pg-meta'
+
+function SnippetRunner({ snippet }: { snippet: Snippet }) {
+  const { mutate: execute } = useExecuteSqlMutation()
+
+  const handleRun = () => {
+    execute({ sql: acceptUntrustedSql(snippet.content.unchecked_sql) })
+  }
+
+  return (
+    <>
+      <SnippetEditor snippet={snippet} />
+      <button onClick={handleRun}>Run</button>
+    </>
+  )
+}
+```

apps/docs/public/humans.txt

@@ -51,6 +51,7 @@ Chase Cresgy
 Chase Granberry
 Chris Caruso
 Chris Chandler
+Chris Chapman (Chappie)
 Chris Copplestone
 Chris Gwilliams
 Chris Martin