@dotdo/postgres 0.1.0

package/dist/rls/generator.d.ts

@@ -0,0 +1,249 @@
+/**
+ * RLS Policy SQL Generator
+ *
+ * SECURITY CRITICAL: This module generates SQL statements for Row-Level Security policies.
+ * All SQL generation must prevent SQL injection attacks through proper identifier quoting
+ * and validation. Never interpolate untrusted input directly into SQL strings.
+ *
+ * Key security considerations:
+ * - All identifiers (policy names, table names, schema names) must be properly quoted
+ * - Double quotes within identifiers must be escaped by doubling them
+ * - Table names must be validated before use to prevent SQL injection
+ * - Policy expressions (USING, WITH CHECK) are passed through as-is; validation is the
+ *   responsibility of the caller or the validatePolicy function in validator.ts
+ *
+ * @module rls/generator
+ */
+import type { RLSPolicy, PGliteLike, ApplyPolicyOptions, EnableRLSOptions, DisableRLSOptions } from './policy';
+/**
+ * Generate CREATE POLICY SQL statement.
+ *
+ * Creates a PostgreSQL RLS policy with the specified configuration.
+ *
+ * SECURITY CRITICAL: This function generates SQL that controls data access.
+ * - Policy names and table names are properly quoted to prevent injection
+ * - USING and WITH CHECK expressions are passed through as-is; they must be
+ *   validated separately using validatePolicy() before calling this function
+ * - Role names are NOT quoted (PostgreSQL syntax); callers must ensure roles
+ *   are validated before passing to this function
+ *
+ * WARNING: Missing USING or WITH CHECK clauses have security implications:
+ * - SELECT without USING: PostgreSQL defaults to true (allows all rows)
+ * - INSERT without WITH CHECK: PostgreSQL defaults to true (allows all inserts)
+ * - UPDATE without USING: Cannot select rows to update
+ * - UPDATE without WITH CHECK: PostgreSQL defaults to USING clause value
+ *
+ * @param policy - The RLS policy definition
+ * @returns The complete CREATE POLICY SQL statement
+ *
+ * @example
+ * const sql = generatePolicySQL({
+ *   name: 'users_read_own',
+ *   table: 'users',
+ *   operation: 'SELECT',
+ *   using: 'user_id = current_user_id()',
+ *   roles: ['authenticated'],
+ *   type: 'permissive'
+ * })
+ * // Returns: CREATE POLICY users_read_own ON users AS PERMISSIVE FOR SELECT TO authenticated USING (user_id = current_user_id())
+ */
+export declare function generatePolicySQL(policy: RLSPolicy): string;
+/**
+ * Generate DROP POLICY SQL statement.
+ *
+ * Creates SQL to drop an existing RLS policy from a table.
+ *
+ * SECURITY: Policy name and table name are properly quoted to prevent injection.
+ *
+ * WARNING: Dropping a policy removes access controls. Ensure this is intentional
+ * and that replacement policies are in place if needed.
+ *
+ * @param policyName - The name of the policy to drop
+ * @param table - The table the policy is attached to
+ * @param ifExists - If true, adds IF EXISTS to prevent errors if policy doesn't exist
+ * @returns The complete DROP POLICY SQL statement
+ *
+ * @example
+ * generateDropPolicySQL('users_read_own', 'users', true)
+ * // Returns: DROP POLICY IF EXISTS users_read_own ON users
+ */
+export declare function generateDropPolicySQL(policyName: string, table: string, ifExists?: boolean): string;
+/**
+ * Generate ALTER TABLE ... ENABLE ROW LEVEL SECURITY SQL.
+ *
+ * Creates SQL to enable RLS on a table. Once enabled, all table access
+ * (except by table owners and superusers) is governed by RLS policies.
+ *
+ * SECURITY CRITICAL:
+ * - ENABLE ROW LEVEL SECURITY: Enables RLS but allows table owner to bypass
+ * - FORCE ROW LEVEL SECURITY: Enforces RLS even for table owner
+ *
+ * WARNING: Enabling RLS without any policies will block all access to the table
+ * (except for superusers and table owners unless FORCE is used).
+ *
+ * @param table - The table to enable RLS on
+ * @param options - Optional settings
+ * @param options.force - If true, uses FORCE ROW LEVEL SECURITY (applies to owner too)
+ * @returns The complete ALTER TABLE SQL statement
+ *
+ * @example
+ * generateEnableRLSSQL('users')               // Returns: ALTER TABLE users ENABLE ROW LEVEL SECURITY
+ * generateEnableRLSSQL('users', { force: true }) // Returns: ALTER TABLE users FORCE ROW LEVEL SECURITY
+ */
+export declare function generateEnableRLSSQL(table: string, options?: EnableRLSOptions): string;
+/**
+ * Generate ALTER TABLE ... DISABLE ROW LEVEL SECURITY SQL.
+ *
+ * Creates SQL to disable RLS on a table.
+ *
+ * SECURITY WARNING: Disabling RLS removes all row-level access controls.
+ * All users with table-level permissions will have unrestricted access to all rows.
+ * Only use this when:
+ * - Migrating to a different access control mechanism
+ * - Temporarily debugging access issues (re-enable immediately after)
+ * - The table genuinely requires no row-level restrictions
+ *
+ * @param table - The table to disable RLS on
+ * @param options - Optional settings
+ * @param options.removeForce - If true, uses NO FORCE (removes owner bypass restriction)
+ * @returns The complete ALTER TABLE SQL statement
+ *
+ * @example
+ * generateDisableRLSSQL('users')                     // Returns: ALTER TABLE users DISABLE ROW LEVEL SECURITY
+ * generateDisableRLSSQL('users', { removeForce: true }) // Returns: ALTER TABLE users NO FORCE ROW LEVEL SECURITY
+ */
+export declare function generateDisableRLSSQL(table: string, options?: DisableRLSOptions): string;
+/**
+ * Enable Row-Level Security on a table.
+ *
+ * Validates the table name and executes the ENABLE ROW LEVEL SECURITY command.
+ *
+ * SECURITY: Table name is validated to prevent SQL injection before generating SQL.
+ *
+ * @param pglite - The PGlite instance to execute against
+ * @param table - The table to enable RLS on (must pass validation)
+ * @param options - Optional settings (see generateEnableRLSSQL)
+ * @throws {Error} If table name is invalid (contains SQL injection patterns)
+ *
+ * @example
+ * await enableRLS(pglite, 'users')
+ * await enableRLS(pglite, 'users', { force: true })
+ */
+export declare function enableRLS(pglite: PGliteLike, table: string, options?: EnableRLSOptions): Promise<void>;
+/**
+ * Disable Row-Level Security on a table.
+ *
+ * Validates the table name and executes the DISABLE ROW LEVEL SECURITY command.
+ *
+ * SECURITY WARNING: This removes all row-level access controls from the table.
+ * See generateDisableRLSSQL for security considerations.
+ *
+ * @param pglite - The PGlite instance to execute against
+ * @param table - The table to disable RLS on (must pass validation)
+ * @param options - Optional settings (see generateDisableRLSSQL)
+ * @throws {Error} If table name is invalid (contains SQL injection patterns)
+ *
+ * @example
+ * await disableRLS(pglite, 'users')
+ */
+export declare function disableRLS(pglite: PGliteLike, table: string, options?: DisableRLSOptions): Promise<void>;
+/**
+ * Apply an RLS policy to a database.
+ *
+ * Creates a new RLS policy, optionally replacing an existing one with the same name.
+ *
+ * SECURITY CRITICAL: This function directly affects data access controls.
+ * - Always validate the policy using validatePolicy() before calling this function
+ * - The replace option drops the existing policy first (brief window of no protection)
+ *
+ * @param pglite - The PGlite instance to execute against
+ * @param policy - The RLS policy definition to apply
+ * @param options - Optional settings
+ * @param options.replace - If true, drops existing policy with same name first
+ * @param options.ifNotExists - If true, adds IF NOT EXISTS (no error if policy exists)
+ *
+ * @example
+ * const policy = createPolicy({
+ *   name: 'users_read_own',
+ *   table: 'users',
+ *   operation: 'SELECT',
+ *   using: 'user_id = current_user_id()'
+ * })
+ * await applyPolicy(pglite, policy)
+ */
+export declare function applyPolicy(pglite: PGliteLike, policy: RLSPolicy, options?: ApplyPolicyOptions): Promise<void>;
+/**
+ * Drop a policy by name.
+ *
+ * Removes an RLS policy from a table.
+ *
+ * SECURITY WARNING: Dropping a policy removes access controls. Ensure:
+ * - This is intentional
+ * - Replacement policies are in place if needed
+ * - The table owner bypass is acceptable, or FORCE is still enabled
+ *
+ * @param pglite - The PGlite instance to execute against
+ * @param policyName - The name of the policy to drop
+ * @param table - The table the policy is attached to
+ * @param options - Optional settings
+ * @param options.ifExists - If true, no error if policy doesn't exist
+ *
+ * @example
+ * await dropPolicy(pglite, 'users_read_own', 'users', { ifExists: true })
+ */
+export declare function dropPolicy(pglite: PGliteLike, policyName: string, table: string, options?: {
+    ifExists?: boolean;
+}): Promise<void>;
+/**
+ * Drop all policies on a table.
+ *
+ * Removes all RLS policies from a table by querying pg_policies and dropping each one.
+ *
+ * SECURITY WARNING: This removes ALL access controls from the table. Use with extreme caution.
+ * Consider disabling RLS entirely if you want to remove all restrictions, or be prepared
+ * to immediately apply new policies.
+ *
+ * @param pglite - The PGlite instance to execute against
+ * @param table - The table to remove all policies from
+ *
+ * @example
+ * // WARNING: This removes all security policies!
+ * await dropAllPolicies(pglite, 'users')
+ */
+export declare function dropAllPolicies(pglite: PGliteLike, table: string): Promise<void>;
+/**
+ * List all policies on a table.
+ *
+ * Queries the pg_policies system view to retrieve complete policy definitions.
+ *
+ * SECURITY: Table name is escaped to prevent SQL injection.
+ *
+ * @param pglite - The PGlite instance to query
+ * @param table - The table to list policies for
+ * @returns Array of complete RLSPolicy objects
+ *
+ * @example
+ * const policies = await listPolicies(pglite, 'users')
+ * console.log(policies) // [{ name: 'users_read_own', table: 'users', operation: 'SELECT', ... }]
+ */
+export declare function listPolicies(pglite: PGliteLike, table: string): Promise<RLSPolicy[]>;
+/**
+ * Check if RLS is enabled on a table.
+ *
+ * Queries the pg_class system catalog to check if row-level security is enabled.
+ *
+ * SECURITY: Table name is escaped to prevent SQL injection.
+ *
+ * @param pglite - The PGlite instance to query
+ * @param table - The table to check
+ * @returns True if RLS is enabled, false otherwise
+ * @throws {Error} If the table does not exist
+ *
+ * @example
+ * const isEnabled = await checkRLSEnabled(pglite, 'users')
+ * if (!isEnabled) {
+ *   await enableRLS(pglite, 'users')
+ * }
+ */
+export declare function checkRLSEnabled(pglite: PGliteLike, table: string): Promise<boolean>;
+//# sourceMappingURL=generator.d.ts.map

package/dist/rls/generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../../src/rls/generator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAA;AAgH9G;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAoC3D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,GAAE,OAAe,GAAG,MAAM,CAG1G;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAKtF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAKxF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,IAAI,CAAC,CAYf;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAYf;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,SAAS,EACjB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAiBf;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,UAAU,EAClB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,GAC/B,OAAO,CAAC,IAAI,CAAC,CAGf;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAStF;AA8CD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CA0B1F;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAgBzF"}