The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.
TypeScript aialternativeauthdatabasedenoembeddingsexamplefirebasenextjsoauth2pgvectorpostgispostgrespostgresqlpostgrestrealtimesupabasevectorswebsockets
feat: introduce safeSql function to pg-meta (#44467)
Charisc372e77c8b36
diff --git a/packages/pg-meta/src/index.ts b/packages/pg-meta/src/index.tsindex 0e498b0e93a..a9b038d4bb8 100644--- a/packages/pg-meta/src/index.ts+++ b/packages/pg-meta/src/index.ts@@ -33,6 +33,9 @@ export * from './sql/studio/sql-editor'export * from './sql/studio/role-impersonation'export * from './sql/studio/integrations'+export { ident, literal, keyword, safeSql, joinSqlFragments } from './pg-format'+export type { SafeSqlFragment } from './pg-format'+export default {roles,columns,diff --git a/packages/pg-meta/src/pg-format/index.ts b/packages/pg-meta/src/pg-format/index.tsindex a2f99321676..e6f92ea6a23 100644--- a/packages/pg-meta/src/pg-format/index.ts+++ b/packages/pg-meta/src/pg-format/index.ts@@ -10,6 +10,38 @@ export interface PgFormatConfig {pattern: PgFormatConfigPattern}+/**+ * A branded string type representing a SQL fragment that is safe to compose+ * into queries.+ * Values of this type are either:+ * - Static strings in source code (no interpolation)+ * - Outputs of `ident()`, `literal()`, or `keyword()` (properly escaped or+ * validated)+ * - Compositions via `safeSql` template tag (enforces SafeSqlFragment-only+ * interpolations)+ * - Compositions via `joinFragments` (enforces SafeSqlFragment inputs)+ *+ * Never cast arbitrary strings to this type — use ident/literal/keyword/safeSql+ * instead.+ */+export type SafeSqlFragment = string & { readonly __safeSqlFragmentBrand: never }++export type SqlFragmentSeparator =+ | ','+ | ', '+ | ';\n'+ | ' and '+ | ' AND '+ | ' or '+ | ' OR '+ | ' union all '+ | ' union '+ | ' UNION ALL '+ | ' UNION '+ | '\n'+ | '\n\n'+ | ' '+const FMT_PATTERN_CONFIG: PgFormatConfigPattern = {ident: 'I',literal: 'L',@@ -42,15 +74,15 @@ function arrayToList(useSpace: boolean, array: unknown[], formatter: (value: unk// Ported from PostgreSQL 9.2.4 source code in src/interfaces/libpq/fe-exec.c// eslint-disable-next-line radar/cognitive-complexity-export function ident(value?: unknown): string {+export function ident(value?: unknown): SafeSqlFragment {if (value === undefined || value === null) {throw new Error('SQL identifier cannot be null or undefined')} else if (value === false) {- return '"f"'+ return '"f"' as SafeSqlFragment} else if (value === true) {- return '"t"'+ return '"t"' as SafeSqlFragment} else if (value instanceof Date) {- return `"${formatDate(value.toISOString())}"`+ return `"${formatDate(value.toISOString())}"` as SafeSqlFragment} else if (Array.isArray(value)) {const temporary: string[] = []for (const element of value) {@@ -62,7 +94,7 @@ export function ident(value?: unknown): string {temporary.push(ident(element))}}- return temporary.toString()+ return temporary.toString() as SafeSqlFragment} else if (value === Object(value)) {throw new Error('SQL identifier cannot be an object')}@@ -71,7 +103,7 @@ export function ident(value?: unknown): string {// do not quote a valid, unquoted identifierif (/^[_a-z][\d$_a-z]*$/.test(tident) === true && isReserved(tident) === false) {- return tident+ return tident as SafeSqlFragment}let quoted = '"'@@ -82,42 +114,42 @@ export function ident(value?: unknown): string {quoted += '"'- return quoted+ return quoted as SafeSqlFragment}// Ported from PostgreSQL 9.2.4 source code in src/interfaces/libpq/fe-exec.c// eslint-disable-next-line radar/cognitive-complexity-export function literal(value?: unknown): string {+export function literal(value?: unknown): SafeSqlFragment {let tliteral = ''let explicitCast: string | undefinedif (value === undefined || value === null) {- return 'NULL'+ return 'NULL' as SafeSqlFragment}if (typeof value === 'bigint') {- return BigInt(value).toString()+ return BigInt(value).toString() as SafeSqlFragment}if (value === Number.POSITIVE_INFINITY) {- return "'Infinity'"+ return "'Infinity'" as SafeSqlFragment}if (value === Number.NEGATIVE_INFINITY) {- return "'-Infinity'"+ return "'-Infinity'" as SafeSqlFragment}if (Number.isNaN(value)) {- return "'NaN'"+ return "'NaN'" as SafeSqlFragment}if (typeof value === 'number') {// Test must be AFTER other special case number tests- return Number(value).toString()+ return Number(value).toString() as SafeSqlFragment}if (value === false) {- return "'f'"+ return "'f'" as SafeSqlFragment}if (value === true) {- return "'t'"+ return "'t'" as SafeSqlFragment}if (value instanceof Date) {- return `'${formatDate(value.toISOString())}'`+ return `'${formatDate(value.toISOString())}'` as SafeSqlFragment}if (Array.isArray(value)) {const temporary: string[] = []@@ -128,7 +160,7 @@ export function literal(value?: unknown): string {temporary.push(literal(element))}}- return temporary.toString()+ return temporary.toString() as SafeSqlFragment}if (value === Object(value)) {explicitCast = 'jsonb'@@ -161,7 +193,21 @@ export function literal(value?: unknown): string {quoted += `::${explicitCast}`}- return quoted+ return quoted as SafeSqlFragment+}++/**+ * Marks SQL keywords (e.g., 'BEFORE', 'instead of') as safe for interpolation.+ * Only letters, numbers, underscores, and spaces are allowed, to prevent+ * injection.+ */+export function keyword(value: string): SafeSqlFragment {+ if (!/^[A-Za-z][A-Za-z0-9_ ]*$/.test(value)) {+ throw new Error(+ `Not a valid keyword: "${value}". Only letters, numbers, underscores, and spaces are permitted.`+ )+ }+ return value as SafeSqlFragment}// eslint-disable-next-line radar/cognitive-complexity@@ -266,3 +312,29 @@ export function withArray(fmt: string, parameters: unknown[]): string {export function format(fmt: string, ...arguments_: unknown[]): string {return withArray(fmt, arguments_)}++/**+ * Tagged template literal for composing SQL fragments safely.+ * Only accepts SafeSqlFragment interpolations — plain strings are rejected at+ * compile time.+ */+export function safeSql(+ strings: TemplateStringsArray,+ ...interpolated: Array<SafeSqlFragment>+): SafeSqlFragment {+ return strings.reduce(+ (result, string, i) => result + string + (interpolated[i] ?? ''),+ ''+ ) as SafeSqlFragment+}++/**+ * Joins an array of already-safe SQL fragments with a fixed structural+ * separator.+ */+export function joinSqlFragments(+ fragments: Array<SafeSqlFragment>,+ separator: SqlFragmentSeparator+): SafeSqlFragment {+ return fragments.join(separator) as SafeSqlFragment+}diff --git a/packages/pg-meta/test/pg-format.test.ts b/packages/pg-meta/test/pg-format.test.tsindex 13628fc112f..48d5e9d0e8c 100644--- a/packages/pg-meta/test/pg-format.test.ts+++ b/packages/pg-meta/test/pg-format.test.ts@@ -1,6 +1,6 @@-import { describe, expect, test } from 'vitest'+import { describe, expect, expectTypeOf, test } from 'vitest'-import { ident, literal } from '../src/pg-format'+import { ident, keyword, literal, safeSql } from '../src/pg-format'describe('pg-format', () => {describe('ident', () => {@@ -139,4 +139,165 @@ describe('pg-format', () => {expect(literal('C:\\Users\\test')).toBe("E'C:\\\\Users\\\\test'")})})++ describe('keyword', () => {+ test('accepts single uppercase words', () => {+ expect(keyword('BEFORE')).toBe('BEFORE')+ expect(keyword('AFTER')).toBe('AFTER')+ expect(keyword('ROW')).toBe('ROW')+ })++ test('accepts lowercase and mixed case', () => {+ expect(keyword('instead of')).toBe('instead of')+ expect(keyword('Each Row')).toBe('Each Row')+ })++ test('accepts words with underscores and digits', () => {+ expect(keyword('EACH_ROW')).toBe('EACH_ROW')+ expect(keyword('col2')).toBe('col2')+ })++ test('rejects empty string', () => {+ expect(() => keyword('')).toThrow('Not a valid keyword')+ })++ test('rejects strings starting with a digit', () => {+ expect(() => keyword('1BEFORE')).toThrow('Not a valid keyword')+ })++ test('rejects strings with semicolons', () => {+ expect(() => keyword('BEFORE;')).toThrow('Not a valid keyword')+ })++ test('rejects strings with dashes', () => {+ expect(() => keyword('BE-FORE')).toThrow('Not a valid keyword')+ })++ test('rejects strings with single quotes', () => {+ expect(() => keyword("BE'FORE")).toThrow('Not a valid keyword')+ })++ test('rejects strings with parentheses', () => {+ expect(() => keyword('fn()')).toThrow('Not a valid keyword')+ })+ })++ describe('safeSql', () => {+ test('returns a plain string when there are no interpolations', () => {+ const result = safeSql`SELECT 1`+ expect(result).toBe('SELECT 1')+ })++ test('interpolates ident values', () => {+ const table = ident('my_table')+ const result = safeSql`SELECT * FROM ${table}`+ expect(result).toBe('SELECT * FROM my_table')+ })++ test('interpolates literal values', () => {+ const value = literal('hello')+ const result = safeSql`SELECT ${value}`+ expect(result).toBe("SELECT 'hello'")+ })++ test('interpolates multiple values', () => {+ const table = ident('users')+ const col = ident('email')+ const val = literal('[email protected]')+ const result = safeSql`SELECT ${col} FROM ${table} WHERE ${col} = ${val}`+ expect(result).toBe(`SELECT email FROM users WHERE email = '[email protected]'`)+ })++ test('handles ident with special characters', () => {+ const table = ident('my "table"')+ const result = safeSql`SELECT * FROM ${table}`+ expect(result).toBe('SELECT * FROM "my ""table"""')+ })++ test('literal: escapes classic quote bypass', () => {+ const val = literal("' OR '1'='1")+ const result = safeSql`SELECT * FROM users WHERE password = ${val}`+ expect(result).toBe("SELECT * FROM users WHERE password = ''' OR ''1''=''1'")+ })++ test('literal: escapes UNION SELECT attack', () => {+ const val = literal("x' UNION SELECT username, password FROM admins --")+ const result = safeSql`SELECT name FROM products WHERE id = ${val}`+ expect(result).toBe(+ "SELECT name FROM products WHERE id = 'x'' UNION SELECT username, password FROM admins --'"+ )+ })++ test('literal: escapes stacked query injection', () => {+ const val = literal("1'; DROP TABLE users; --")+ const result = safeSql`SELECT * FROM users WHERE id = ${val}`+ expect(result).toBe("SELECT * FROM users WHERE id = '1''; DROP TABLE users; --'")+ })++ test('literal: escapes comment-based injection', () => {+ const val = literal("admin'--")+ const result = safeSql`SELECT * FROM users WHERE username = ${val}`+ expect(result).toBe("SELECT * FROM users WHERE username = 'admin''--'")+ })++ test('ident: escapes SQL keyword injection in table name', () => {+ const table = ident('users WHERE 1=1 --')+ const result = safeSql`SELECT * FROM ${table}`+ expect(result).toBe('SELECT * FROM "users WHERE 1=1 --"')+ })++ test('ident: escapes stacked query injection in column name', () => {+ const col = ident('id; DROP TABLE users')+ const result = safeSql`SELECT ${col} FROM users`+ expect(result).toBe('SELECT "id; DROP TABLE users" FROM users')+ })++ test('handles literal with null', () => {+ const val = literal(null)+ const result = safeSql`SELECT ${val}`+ expect(result).toBe('SELECT NULL')+ })++ test('handles literal with numbers', () => {+ const val = literal(42)+ const result = safeSql`SELECT ${val}`+ expect(result).toBe('SELECT 42')+ })++ test('can be nested', () => {+ const col = ident('id')+ const inner = safeSql`SELECT ${col} FROM ${ident('items')}`+ const outer = safeSql`WITH cte AS (${inner}) SELECT * FROM cte`+ expect(outer).toBe('WITH cte AS (SELECT id FROM items) SELECT * FROM cte')+ })+ })++ describe('safeSql type safety', () => {+ test('rejects a plain string interpolation', () => {+ const unsafeValue = 'malicious'+ // @ts-expect-error plain string is not a SafeSqlFragment+ safeSql`SELECT * FROM ${unsafeValue}`+ })++ test('rejects a number interpolation', () => {+ // @ts-expect-error number is not a SafeSqlFragment+ safeSql`SELECT * FROM users LIMIT ${10}`+ })++ test('rejects an object interpolation', () => {+ const obj = { table: 'users' }+ // @ts-expect-error object is not a SafeSqlFragment+ safeSql`SELECT * FROM ${obj}`+ })++ test('accepts SafeSqlFragment from ident', () => {+ const result = safeSql`SELECT * FROM ${ident('users')}`+ expectTypeOf(result).toBeString+ })++ test('accepts SafeSqlFragment from literal', () => {+ const result = safeSql`SELECT ${literal('value')}`+ expectTypeOf(result).toBeString+ })+ })})