@everystack/events 0.4.3 → 0.4.4

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to `@everystack/events` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.4] - 2026-10-30
+
+### Added
+
+- createListener takes a role and switches to it once per session
+
 ## [0.4.3] - 2026-10-23
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/events",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "description": "PostgreSQL LISTEN/NOTIFY bridge for serverless — WebSocket fan-out + Lambda invocation",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -64,7 +64,7 @@
     }
   },
   "dependencies": {
-    "@everystack/model": "0.4.23"
+    "@everystack/model": "0.4.25"
   },
   "peerDependencies": {
     "@aws-sdk/client-apigatewaymanagementapi": "3.1053.0",
@@ -105,10 +105,11 @@
     "@types/react": "19.2.14",
     "drizzle-orm": "0.41.0",
     "jest": "29.7.0",
+    "postgres": "3.4.9",
     "react": "19.2.0",
     "ts-jest": "29.4.9",
     "typescript": "5.9.3",
-    "@everystack/auth": "0.4.9"
+    "@everystack/auth": "0.4.10"
   },
   "scripts": {
     "test": "jest",

package/src/listener.ts

@@ -276,6 +276,26 @@ async function reconcile(
   await loadEventActions(pgClient, actionCache);
 }
 
+// --- Session role ---
+
+const ROLE_NAME = /^[a-z_][a-z0-9_]*$/;
+
+/** The role is spliced into SET ROLE, so it must be a plain identifier; never the lifecycle role. */
+function assertListenerRole(role: string): void {
+  if (!ROLE_NAME.test(role)) throw new Error(`Invalid role name: ${JSON.stringify(role)}`);
+  if (role === 'everystack_lifecycle') throw new Error('the listener must not run as everystack_lifecycle: pass an application role (e.g. admin)');
+}
+
+/**
+ * Switch the session to `role` and prove it took. Session-level, not SET LOCAL: LISTEN is
+ * session-scoped and the listener holds one session for its whole run, outside any transaction.
+ */
+async function switchSessionRole(pgClient: InternalListenerOptions['pgClient'], role: string): Promise<void> {
+  await pgClient.query(`SET ROLE ${role}`);
+  const { rows } = await pgClient.query('SELECT current_user AS role');
+  if (rows[0]?.role !== role) throw new Error(`role ${role} was not set: current_user is ${String(rows[0]?.role)}`);
+}
+
 // --- Internal (testable) listener factory ---
 
 interface InternalListenerOptions {
@@ -294,6 +314,8 @@ interface InternalListenerOptions {
   heartbeatInterval?: number;
   eventActions?: EventActionsOptions;
   kvsClient?: KvsClient | null;
+  /** See ListenerOptions.role. */
+  role?: string;
 }
 
 interface HandlerEvent {
@@ -311,11 +333,22 @@ export function createListenerInternal(options: InternalListenerOptions) {
     heartbeatInterval = 30000,
     eventActions,
     kvsClient = null,
+    role,
   } = options;
+  if (role !== undefined) assertListenerRole(role);
 
   return async function handler(event: HandlerEvent = {}): Promise<{ status: string; reason?: string }> {
-    // 1. Connect
+    // 1. Connect, then switch role before anything else runs in this session. This is the only
+    // connect: the session is never re-opened, so the switch covers everything after it.
     await pgClient.connect();
+    if (role !== undefined) {
+      try {
+        await switchSessionRole(pgClient, role);
+      } catch (err) {
+        await pgClient.end().catch(() => {});
+        throw err;
+      }
+    }
 
     // 2. Acquire advisory lock
     const { rows } = await pgClient.query(
@@ -393,6 +426,7 @@ export function createListenerInternal(options: InternalListenerOptions) {
 // --- Public API ---
 
 export function createListener(options: ListenerOptions) {
+  if (options.role !== undefined) assertListenerRole(options.role);
   return async function handler(_event?: unknown): Promise<{ status: string; reason?: string }> {
     // Dynamic imports to avoid bundling AWS SDK when not needed
     const { default: pg } = await import('pg' as string);
@@ -449,6 +483,7 @@ export function createListener(options: ListenerOptions) {
       heartbeatInterval: options.heartbeatInterval,
       eventActions: options.eventActions,
       kvsClient,
+      role: options.role,
     });
 
     return internal({});

package/src/types.ts

@@ -50,6 +50,12 @@ export interface ListenerOptions {
   reconcile?: (db: unknown) => Promise<void>;
   heartbeatInterval?: number;
   eventActions?: EventActionsOptions;
+  /**
+   * An application role to `SET ROLE` to right after connect, checked with `current_user`.
+   * Lets the listener connect as a least-privilege login (NOINHERIT, granted the role) instead
+   * of the owner. Each invocation opens a new session and switches it. Omit to stay as the login.
+   */
+  role?: string;
 }
 
 // --- Subscription (internal NOTIFY payloads) ---