@everystack/server 0.2.13 → 0.2.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/server",
-  "version": "0.2.13",
+  "version": "0.2.15",
   "description": "Server runtime primitives for Lambda — event adapters, routing, SSR, image processing",
   "license": "AGPL-3.0-only",
   "publishConfig": {

package/src/db.ts

@@ -42,6 +42,28 @@ export function getDatabaseUrl(): string {
   throw new Error('DATABASE_URL not set — link an sst.aws.Postgres or sst.Secret, or set process.env.DATABASE_URL');
 }
 
+/**
+ * Resolve the operator (privileged) database URL, if configured.
+ *
+ * The API connection (DATABASE_URL) should be least-privilege and RLS-gated.
+ * Operator tasks — migrations, seed, console, raw queries — need a role that
+ * owns the schema and sees all rows. Keep them on separate credentials so the
+ * API Lambda never holds the operator secret.
+ *
+ * Returns null when no admin URL is configured (single-credential setup).
+ */
+export function getAdminDatabaseUrl(): string | null {
+  // SST Secret — PascalCase (Resource.AdminDatabaseUrl.value)
+  const pascal = tryResource(() => (Resource as any).AdminDatabaseUrl?.value as string);
+  if (pascal) return pascal;
+  // SST Secret — raw env name (Resource.ADMIN_DATABASE_URL.value)
+  const raw = tryResource(() => (Resource as any).ADMIN_DATABASE_URL?.value as string);
+  if (raw) return raw;
+  // process.env fallback
+  if (process.env.ADMIN_DATABASE_URL) return process.env.ADMIN_DATABASE_URL;
+  return null;
+}
+
 export function getJwtSecret(): Uint8Array {
   // PascalCase Resource (Resource.JwtSecret.value)
   const pascal = tryResource(() => (Resource as any).JwtSecret?.value as string);
@@ -94,3 +116,59 @@ export function getSql(): ReturnType<typeof postgres> {
   }
   return sqlClient;
 }
+
+// Lazy singleton operator DB connection (separate from the API connection)
+let adminDbInstance: ReturnType<typeof drizzle> | null = null;
+let adminSqlClient: ReturnType<typeof postgres> | null = null;
+let adminFallbackWarned = false;
+
+/**
+ * Operator database connection for privileged tasks (migrate, seed, console).
+ *
+ * Connects with ADMIN_DATABASE_URL when configured. When it isn't, falls back
+ * to the regular DATABASE_URL connection with a one-time warning — existing
+ * single-credential apps keep working, but RLS is only fail-closed once the
+ * credentials are split. See docs/plans/admin-database-url.md.
+ */
+export function createAdminDb<T extends Record<string, unknown>>(
+  schema: T,
+  options?: { maxConnections?: number }
+): {
+  db: ReturnType<typeof drizzle>;
+  schema: T;
+} {
+  if (adminDbInstance) return { db: adminDbInstance, schema };
+
+  const adminUrl = getAdminDatabaseUrl();
+  if (!adminUrl) {
+    if (!adminFallbackWarned) {
+      adminFallbackWarned = true;
+      console.warn(
+        '[everystack/db] ADMIN_DATABASE_URL not set — operator tasks are using the '
+        + 'API connection (DATABASE_URL). If that role has BYPASSRLS, your RLS policies '
+        + 'are not enforced. Split the credentials: docs/plans/admin-database-url.md'
+      );
+    }
+    return createDb(schema, options);
+  }
+
+  adminSqlClient = postgres(adminUrl, {
+    max: options?.maxConnections ?? 1,
+    idle_timeout: 60,
+    connect_timeout: 5,
+    max_lifetime: 60 * 5,
+    ssl: 'require',
+  });
+  adminDbInstance = drizzle(adminSqlClient, { schema });
+  return { db: adminDbInstance, schema };
+}
+
+/**
+ * Raw postgres.js client for the operator connection.
+ * Must be called after createAdminDb(). Falls back to the API client when
+ * the credentials aren't split (same fallback as createAdminDb).
+ */
+export function getAdminSql(): ReturnType<typeof postgres> {
+  if (adminSqlClient) return adminSqlClient;
+  return getSql();
+}

package/src/plugin.ts

@@ -27,6 +27,14 @@ import {
 export interface PluginContext {
   /** Drizzle database connection */
   db: any;
+  /**
+   * Operator (privileged) connection for migrate/seed/console — see
+   * createAdminDb(). When present, dbPlugin runs ALL operator actions on it
+   * instead of `db`, so `db` can be a least-privilege, RLS-gated role.
+   * In a dedicated ops Lambda, set both `db` and `adminDb` to the admin
+   * connection.
+   */
+  adminDb?: any;
   /** App schema (all tables) */
   schema: Record<string, any>;
   /** Shared JWT verification — one function, used by all plugins */
@@ -103,6 +111,14 @@ export interface PluginLambdaHandlerOptions {
   actions?: Record<string, ActionHandler>;
   /** Override default Cache-Control headers */
   cache?: ServerCacheConfig;
+  /**
+   * Serve HTTP. Default true. Set false for an operator Lambda (server/ops.ts):
+   * routes are not built and HTTP-shaped events are rejected with 403 — the
+   * function answers `_action` invokes only. IAM (lambda:InvokeFunction) is the
+   * auth layer. Use with createAdminDb() so the privileged credential lives
+   * here, not in the HTTP-facing API function.
+   */
+  http?: boolean;
 }
 
 // --- Plugin Lambda Handler Implementation ---
@@ -110,9 +126,10 @@ export interface PluginLambdaHandlerOptions {
 export function createPluginLambdaHandler(
   options: PluginLambdaHandlerOptions
 ): (event: APIGatewayProxyEventV2 | Record<string, unknown>) => Promise<APIGatewayProxyStructuredResultV2 | unknown> {
+  const httpEnabled = options.http !== false;
   let cached: {
     ctx: PluginContext;
-    router: (path: string, method: string) => Handler;
+    router?: (path: string, method: string) => Handler;
     actions: Record<string, ActionHandler>;
     logSink?: LogSink;
   } | null = null;
@@ -128,11 +145,6 @@ export function createPluginLambdaHandler(
       contributions.push(await plugin(ctx));
     }
 
-    // Collect routes (plugin order = priority)
-    const pluginRoutes = contributions.flatMap(c => c.routes ?? []);
-    const appRoutes = options.routes?.(ctx) ?? [];
-    const allRoutes = [...pluginRoutes, ...appRoutes];
-
     // Collect actions (app-level takes precedence on collision)
     const pluginActions: Record<string, ActionHandler> = {};
     for (const contribution of contributions) {
@@ -142,6 +154,20 @@ export function createPluginLambdaHandler(
     }
     const allActions = { ...pluginActions, ...(options.actions ?? {}) };
 
+    // Operator mode (http: false) — actions only. Skip routing entirely;
+    // HTTP-shaped events are rejected below. Routes contributed by plugins
+    // are intentionally ignored.
+    if (!httpEnabled) {
+      cached = { ctx, actions: allActions };
+      log('info', 'Plugin handlers initialized (actions only)', { plugins: options.plugins.length });
+      return cached;
+    }
+
+    // Collect routes (plugin order = priority)
+    const pluginRoutes = contributions.flatMap(c => c.routes ?? []);
+    const appRoutes = options.routes?.(ctx) ?? [];
+    const allRoutes = [...pluginRoutes, ...appRoutes];
+
     // Collect log sink (first one wins)
     const logSink = contributions.find(c => c.logSink)?.logSink;
 
@@ -174,6 +200,20 @@ export function createPluginLambdaHandler(
       }
     }
 
+    // Operator mode — reject anything that isn't an `_action` invoke. A caller
+    // with IAM invoke rights can hand the function any event shape; refuse to
+    // route HTTP on the privileged connection.
+    if (!httpEnabled) {
+      if ('requestContext' in event || 'rawPath' in event) {
+        return {
+          statusCode: 403,
+          headers: { 'Content-Type': 'application/json', 'cache-control': 'no-store' },
+          body: JSON.stringify({ error: 'Forbidden' }),
+        };
+      }
+      return { error: 'Missing _action' };
+    }
+
     // HTTP event — Function URL or API Gateway
     const httpEvent = event as APIGatewayProxyEventV2;
     const requestId =
@@ -186,7 +226,7 @@ export function createPluginLambdaHandler(
       const request = eventToRequest(httpEvent);
       const path = httpEvent.rawPath;
       const method = httpEvent.requestContext.http.method;
-      const handlerFn = router(path, method);
+      const handlerFn = router!(path, method);
       const response = await handlerFn(request);
       const result = await responseToResult(response);
 
@@ -262,6 +302,36 @@ export function createPluginLambdaHandler(
   };
 }
 
+// --- Ops Lambda Handler (actions only) ---
+
+export interface OpsLambdaHandlerOptions {
+  /** Creates the shared context. Use createAdminDb() here — this Lambda is
+   *  the operator entrypoint and should hold the privileged credential. */
+  context: () => Promise<PluginContext>;
+  /** Plugins to collect actions from. Routes/handlers they contribute are ignored. */
+  plugins: Plugin[];
+  /** App-level actions merged with plugin actions (app wins on collision). */
+  actions?: Record<string, ActionHandler>;
+}
+
+/**
+ * Dedicated operator entrypoint — handles `_action` invokes only.
+ *
+ * Thin alias for `createPluginLambdaHandler({ ...options, http: false })`.
+ * Deploy as a separate Lambda (server/ops.ts) and link ADMIN_DATABASE_URL to
+ * it instead of the API function. IAM (lambda:InvokeFunction) is the auth
+ * layer; HTTP-shaped events are rejected.
+ *
+ * @deprecated Prefer `createPluginLambdaHandler({ http: false })` directly.
+ */
+export function createOpsLambdaHandler(
+  options: OpsLambdaHandlerOptions
+): (event: Record<string, unknown>) => Promise<unknown> {
+  return createPluginLambdaHandler({ ...options, http: false }) as (
+    event: Record<string, unknown>
+  ) => Promise<unknown>;
+}
+
 // --- SSR Fallback Plugin ---
 
 import type { PostProcessResult, WebHandlerOptions } from './ssr';
@@ -377,10 +447,15 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
   return async (ctx: PluginContext): Promise<PluginContribution> => {
     const actions: Record<string, ActionHandler> = {};
 
+    // Operator connection: all actions below run privileged tasks (DDL,
+    // unrestricted reads). Prefer the dedicated admin connection so the API
+    // connection can be least-privilege and RLS-gated.
+    const opsDb = ctx.adminDb ?? ctx.db;
+
     // --- migrate ---
-    actions.migrate = async (_payload, ctx) => {
+    actions.migrate = async (_payload, _ctx) => {
       const { runMigrations } = await import('./migrate');
-      return await runMigrations(ctx.db, options.migrationsFolder);
+      return await runMigrations(opsDb, options.migrationsFolder);
     };
 
     // --- seed (only when app provides a seed function) ---
@@ -390,7 +465,7 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
         if (ctx.environment !== 'dev') {
           return { error: 'Seed is only available in dev environment' };
         }
-        return await seedFn(ctx.db, ctx.schema);
+        return await seedFn(opsDb, ctx.schema);
       };
     }
 
@@ -404,14 +479,14 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
       const dropStatements = schemas
         .map(s => `DROP SCHEMA IF EXISTS ${s} CASCADE;`)
         .join('\n    ');
-      await ctx.db.execute(sql.raw(`
+      await opsDb.execute(sql.raw(`
     ${dropStatements}
     CREATE SCHEMA public;
     GRANT ALL ON SCHEMA public TO postgres;
     GRANT ALL ON SCHEMA public TO public;
   `));
       const { runMigrations } = await import('./migrate');
-      const result = await runMigrations(ctx.db, options.migrationsFolder);
+      const result = await runMigrations(opsDb, options.migrationsFolder);
       return { reset: true, ...result };
     };
 
@@ -435,7 +510,7 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
     };
 
     // --- db:query ---
-    actions['db:query'] = async (payload, ctx) => {
+    actions['db:query'] = async (payload, _ctx) => {
       const { sql: querySql } = payload as { sql: string };
       if (!querySql) {
         return { error: 'SQL query is required' };
@@ -451,7 +526,7 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
       }
       try {
         const { sql } = await import('drizzle-orm');
-        let queryDb = ctx.db;
+        let queryDb = opsDb;
         const readUrl = options.readDatabaseUrl ?? process.env.READ_DATABASE_URL;
         if (readUrl && readUrl !== process.env.DATABASE_URL) {
           const { drizzle } = await import('drizzle-orm/postgres-js');
@@ -489,7 +564,7 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
           // Auth signal — helpers write to this during eval, we read it after
           const authSignal = { user: null as Record<string, unknown> | null, changed: false };
           const authHelpers = createAuthHelpers({
-            db: ctx.db,
+            db: opsDb,
             schema: ctx.schema,
             signal: authSignal,
             ...options.consoleAuth,
@@ -542,7 +617,7 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
 
             if (sandbox) {
               try {
-                await ctx.db.transaction(async (tx: any) => {
+                await opsDb.transaction(async (tx: any) => {
                   await applySettings(tx);
                   result = await evalExpression(tx);
                   throw SANDBOX_ROLLBACK;
@@ -551,14 +626,14 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
                 if (err !== SANDBOX_ROLLBACK) throw err;
               }
             } else {
-              result = await ctx.db.transaction(async (tx: any) => {
+              result = await opsDb.transaction(async (tx: any) => {
                 await applySettings(tx);
                 return evalExpression(tx);
               });
             }
           } else if (sandbox) {
             try {
-              await ctx.db.transaction(async (tx: any) => {
+              await opsDb.transaction(async (tx: any) => {
                 result = await evalExpression(tx);
                 throw SANDBOX_ROLLBACK;
               });
@@ -566,7 +641,7 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
               if (err !== SANDBOX_ROLLBACK) throw err;
             }
           } else {
-            result = await evalExpression(ctx.db);
+            result = await evalExpression(opsDb);
           }
 
           // Safe-serialize: handle circular refs, Symbols, and complex objects