@pgpmjs/core 6.26.1 → 6.27.0

package/esm/init/client.js

@@ -1,6 +1,6 @@
 import { Logger } from '@pgpmjs/logger';
 import { getPgPool } from 'pg-cache';
-import { generateCreateBaseRolesSQL, generateCreateUserSQL, generateCreateTestUsersSQL, generateRemoveUserSQL } from '../roles';
+import { generateCreateBaseRolesSQL, generateCreateClientRoleSQL, generateCreateUserSQL, generateCreateTestUsersSQL, generateRemoveUserSQL } from '../roles';
 const log = new Logger('init');
 export class PgpmInit {
     pool;
@@ -26,6 +26,24 @@ export class PgpmInit {
             throw error;
         }
     }
+    /**
+     * Bootstrap the restricted client role (authenticated_client) for SQL-level
+     * proxy clients. Opt-in via `pgpm admin-users bootstrap --client`.
+     * Callers should use getConnEnvOptions() from @pgpmjs/env to get merged values.
+     * @param roles - Role mapping from getConnEnvOptions().roles!
+     */
+    async bootstrapClientRole(roles) {
+        try {
+            log.info('Bootstrapping PGPM client role...');
+            const sql = generateCreateClientRoleSQL(roles);
+            await this.pool.query(sql);
+            log.success('Successfully bootstrapped PGPM client role');
+        }
+        catch (error) {
+            log.error('Failed to bootstrap client role:', error);
+            throw error;
+        }
+    }
     /**
      * Bootstrap test roles (app_user, app_admin with grants to base roles).
      * Callers should use getConnEnvOptions() from @pgpmjs/env to get merged values.

package/esm/roles/index.js

@@ -95,6 +95,93 @@ $do$;
 COMMIT;
 `;
 }
+/**
+ * Generate SQL to create the restricted `authenticated_client` role used by
+ * SQL-level proxy clients (opt-in via `admin-users bootstrap --client`).
+ *
+ * The role inherits table/schema grants from `authenticated` and gets a
+ * server-enforced statement_timeout baseline. Grant-level hardening such as
+ * revoking set_config()/pg_notify() from PUBLIC is intentionally left to the
+ * proxy deployment config, since those revokes affect every non-superuser
+ * role in the database (the app server and job workers depend on both).
+ *
+ * @param roles - Role mapping from getConnEnvOptions().roles!
+ * @param statementTimeout - Baseline statement_timeout for the role (default '15s')
+ */
+export function generateCreateClientRoleSQL(roles, statementTimeout = '15s') {
+    if (!roles) {
+        throw new Error('generateCreateClientRoleSQL: roles parameter is undefined. ' +
+            'Ensure getConnEnvOptions().roles is defined.');
+    }
+    if (!roles.authenticated || !roles.authenticatedClient) {
+        throw new Error('generateCreateClientRoleSQL: roles is missing required properties. ' +
+            `Got: authenticated=${roles.authenticated}, authenticatedClient=${roles.authenticatedClient}. ` +
+            'Ensure all role names are defined in your configuration.');
+    }
+    const r = {
+        authenticated: roles.authenticated,
+        authenticatedClient: roles.authenticatedClient
+    };
+    return `
+BEGIN;
+DO $do$
+DECLARE
+  v_authenticated text := ${sqlLiteral(r.authenticated)};
+  v_client text := ${sqlLiteral(r.authenticatedClient)};
+  v_statement_timeout text := ${sqlLiteral(statementTimeout)};
+BEGIN
+  -- Create client role: pre-check + exception handling for TOCTOU safety
+  IF NOT EXISTS (SELECT 1 FROM pg_catalog.pg_roles WHERE rolname = v_client) THEN
+    BEGIN
+      EXECUTE format('CREATE ROLE %I', v_client);
+    EXCEPTION
+      WHEN duplicate_object THEN
+        -- 42710: Role already exists (race condition); safe to ignore
+        NULL;
+      WHEN unique_violation THEN
+        -- 23505: Concurrent CREATE ROLE hit unique index; safe to ignore
+        NULL;
+      WHEN insufficient_privilege THEN
+        -- 42501: Must surface this error - caller lacks permission
+        RAISE;
+    END;
+  END IF;
+
+  -- Strip escalation attributes (safe to run even if role already exists)
+  EXECUTE format('ALTER ROLE %I WITH NOCREATEDB NOSUPERUSER NOCREATEROLE NOLOGIN NOREPLICATION NOBYPASSRLS', v_client);
+
+  -- Inherit table/schema grants from authenticated
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_auth_members am
+    JOIN pg_roles r1 ON am.roleid = r1.oid
+    JOIN pg_roles r2 ON am.member = r2.oid
+    WHERE r1.rolname = v_authenticated AND r2.rolname = v_client
+  ) THEN
+    BEGIN
+      EXECUTE format('GRANT %I TO %I', v_authenticated, v_client);
+    EXCEPTION
+      WHEN unique_violation THEN
+        -- 23505: Membership was granted concurrently; safe to ignore
+        NULL;
+      WHEN undefined_object THEN
+        -- 42704: One of the roles doesn't exist; log notice and continue
+        RAISE NOTICE 'Missing role when granting % to %', v_authenticated, v_client;
+      WHEN insufficient_privilege THEN
+        -- 42501: Must surface this error - caller lacks permission
+        RAISE;
+      WHEN invalid_grant_operation THEN
+        -- 0LP01: Must surface this error - invalid grant operation
+        RAISE;
+    END;
+  END IF;
+
+  -- Server-enforced baseline statement timeout for the client role
+  EXECUTE format('ALTER ROLE %I SET statement_timeout = %L', v_client, v_statement_timeout);
+END
+$do$;
+COMMIT;
+`;
+}
 /**
  * Generate SQL to create a user with password and grant base roles.
  * Callers should use getConnEnvOptions() from @pgpmjs/env to get merged values.

package/init/client.d.ts

@@ -10,6 +10,13 @@ export declare class PgpmInit {
      * @param roles - Role mapping from getConnEnvOptions().roles!
      */
     bootstrapRoles(roles: RoleMapping): Promise<void>;
+    /**
+     * Bootstrap the restricted client role (authenticated_client) for SQL-level
+     * proxy clients. Opt-in via `pgpm admin-users bootstrap --client`.
+     * Callers should use getConnEnvOptions() from @pgpmjs/env to get merged values.
+     * @param roles - Role mapping from getConnEnvOptions().roles!
+     */
+    bootstrapClientRole(roles: RoleMapping): Promise<void>;
     /**
      * Bootstrap test roles (app_user, app_admin with grants to base roles).
      * Callers should use getConnEnvOptions() from @pgpmjs/env to get merged values.

package/init/client.js

@@ -29,6 +29,24 @@ class PgpmInit {
             throw error;
         }
     }
+    /**
+     * Bootstrap the restricted client role (authenticated_client) for SQL-level
+     * proxy clients. Opt-in via `pgpm admin-users bootstrap --client`.
+     * Callers should use getConnEnvOptions() from @pgpmjs/env to get merged values.
+     * @param roles - Role mapping from getConnEnvOptions().roles!
+     */
+    async bootstrapClientRole(roles) {
+        try {
+            log.info('Bootstrapping PGPM client role...');
+            const sql = (0, roles_1.generateCreateClientRoleSQL)(roles);
+            await this.pool.query(sql);
+            log.success('Successfully bootstrapped PGPM client role');
+        }
+        catch (error) {
+            log.error('Failed to bootstrap client role:', error);
+            throw error;
+        }
+    }
     /**
      * Bootstrap test roles (app_user, app_admin with grants to base roles).
      * Callers should use getConnEnvOptions() from @pgpmjs/env to get merged values.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pgpmjs/core",
-  "version": "6.26.1",
+  "version": "6.27.0",
   "author": "Constructive <developers@constructive.io>",
   "description": "PGPM Package and Migration Tools",
   "main": "index.js",
@@ -48,21 +48,21 @@
     "makage": "^0.3.0"
   },
   "dependencies": {
-    "@pgpmjs/env": "^2.26.0",
+    "@pgpmjs/env": "^2.26.1",
     "@pgpmjs/logger": "^2.13.0",
-    "@pgpmjs/server-utils": "^3.14.0",
-    "@pgpmjs/types": "^2.30.0",
+    "@pgpmjs/server-utils": "^3.14.1",
+    "@pgpmjs/types": "^2.31.0",
     "csv-to-pg": "^3.20.1",
     "genomic": "^5.6.2",
     "glob": "^13.0.6",
     "minimatch": "^10.2.5",
     "parse-package-name": "^1.0.0",
     "pg": "^8.21.0",
-    "pg-cache": "^3.13.0",
+    "pg-cache": "^3.13.1",
     "pg-env": "^1.17.0",
     "pgsql-deparser": "^17.18.3",
     "pgsql-parser": "^17.9.15",
     "yanse": "^0.2.1"
   },
-  "gitHead": "8b9a410cb57ddbd0fa685c6177b979a97178bd4e"
+  "gitHead": "5a7e92e9849aa715367a33fa78a23c5f9adaefa0"
 }

package/roles/index.d.ts

@@ -6,6 +6,20 @@ import { RoleMapping, TestUserCredentials } from '@pgpmjs/types';
  * @throws Error if roles is undefined or missing required properties
  */
 export declare function generateCreateBaseRolesSQL(roles: RoleMapping): string;
+/**
+ * Generate SQL to create the restricted `authenticated_client` role used by
+ * SQL-level proxy clients (opt-in via `admin-users bootstrap --client`).
+ *
+ * The role inherits table/schema grants from `authenticated` and gets a
+ * server-enforced statement_timeout baseline. Grant-level hardening such as
+ * revoking set_config()/pg_notify() from PUBLIC is intentionally left to the
+ * proxy deployment config, since those revokes affect every non-superuser
+ * role in the database (the app server and job workers depend on both).
+ *
+ * @param roles - Role mapping from getConnEnvOptions().roles!
+ * @param statementTimeout - Baseline statement_timeout for the role (default '15s')
+ */
+export declare function generateCreateClientRoleSQL(roles: RoleMapping, statementTimeout?: string): string;
 /**
  * Generate SQL to create a user with password and grant base roles.
  * Callers should use getConnEnvOptions() from @pgpmjs/env to get merged values.

package/roles/index.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateCreateBaseRolesSQL = generateCreateBaseRolesSQL;
+exports.generateCreateClientRoleSQL = generateCreateClientRoleSQL;
 exports.generateCreateUserSQL = generateCreateUserSQL;
 exports.generateCreateTestUsersSQL = generateCreateTestUsersSQL;
 exports.generateGrantRoleSQL = generateGrantRoleSQL;
@@ -103,6 +104,93 @@ $do$;
 COMMIT;
 `;
 }
+/**
+ * Generate SQL to create the restricted `authenticated_client` role used by
+ * SQL-level proxy clients (opt-in via `admin-users bootstrap --client`).
+ *
+ * The role inherits table/schema grants from `authenticated` and gets a
+ * server-enforced statement_timeout baseline. Grant-level hardening such as
+ * revoking set_config()/pg_notify() from PUBLIC is intentionally left to the
+ * proxy deployment config, since those revokes affect every non-superuser
+ * role in the database (the app server and job workers depend on both).
+ *
+ * @param roles - Role mapping from getConnEnvOptions().roles!
+ * @param statementTimeout - Baseline statement_timeout for the role (default '15s')
+ */
+function generateCreateClientRoleSQL(roles, statementTimeout = '15s') {
+    if (!roles) {
+        throw new Error('generateCreateClientRoleSQL: roles parameter is undefined. ' +
+            'Ensure getConnEnvOptions().roles is defined.');
+    }
+    if (!roles.authenticated || !roles.authenticatedClient) {
+        throw new Error('generateCreateClientRoleSQL: roles is missing required properties. ' +
+            `Got: authenticated=${roles.authenticated}, authenticatedClient=${roles.authenticatedClient}. ` +
+            'Ensure all role names are defined in your configuration.');
+    }
+    const r = {
+        authenticated: roles.authenticated,
+        authenticatedClient: roles.authenticatedClient
+    };
+    return `
+BEGIN;
+DO $do$
+DECLARE
+  v_authenticated text := ${sqlLiteral(r.authenticated)};
+  v_client text := ${sqlLiteral(r.authenticatedClient)};
+  v_statement_timeout text := ${sqlLiteral(statementTimeout)};
+BEGIN
+  -- Create client role: pre-check + exception handling for TOCTOU safety
+  IF NOT EXISTS (SELECT 1 FROM pg_catalog.pg_roles WHERE rolname = v_client) THEN
+    BEGIN
+      EXECUTE format('CREATE ROLE %I', v_client);
+    EXCEPTION
+      WHEN duplicate_object THEN
+        -- 42710: Role already exists (race condition); safe to ignore
+        NULL;
+      WHEN unique_violation THEN
+        -- 23505: Concurrent CREATE ROLE hit unique index; safe to ignore
+        NULL;
+      WHEN insufficient_privilege THEN
+        -- 42501: Must surface this error - caller lacks permission
+        RAISE;
+    END;
+  END IF;
+
+  -- Strip escalation attributes (safe to run even if role already exists)
+  EXECUTE format('ALTER ROLE %I WITH NOCREATEDB NOSUPERUSER NOCREATEROLE NOLOGIN NOREPLICATION NOBYPASSRLS', v_client);
+
+  -- Inherit table/schema grants from authenticated
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_auth_members am
+    JOIN pg_roles r1 ON am.roleid = r1.oid
+    JOIN pg_roles r2 ON am.member = r2.oid
+    WHERE r1.rolname = v_authenticated AND r2.rolname = v_client
+  ) THEN
+    BEGIN
+      EXECUTE format('GRANT %I TO %I', v_authenticated, v_client);
+    EXCEPTION
+      WHEN unique_violation THEN
+        -- 23505: Membership was granted concurrently; safe to ignore
+        NULL;
+      WHEN undefined_object THEN
+        -- 42704: One of the roles doesn't exist; log notice and continue
+        RAISE NOTICE 'Missing role when granting % to %', v_authenticated, v_client;
+      WHEN insufficient_privilege THEN
+        -- 42501: Must surface this error - caller lacks permission
+        RAISE;
+      WHEN invalid_grant_operation THEN
+        -- 0LP01: Must surface this error - invalid grant operation
+        RAISE;
+    END;
+  END IF;
+
+  -- Server-enforced baseline statement timeout for the client role
+  EXECUTE format('ALTER ROLE %I SET statement_timeout = %L', v_client, v_statement_timeout);
+END
+$do$;
+COMMIT;
+`;
+}
 /**
  * Generate SQL to create a user with password and grant base roles.
  * Callers should use getConnEnvOptions() from @pgpmjs/env to get merged values.