@everystack/server 0.2.13 → 0.2.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/server",
-  "version": "0.2.13",
+  "version": "0.2.14",
   "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 */
@@ -262,6 +270,74 @@ 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.
+ *
+ * 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, same as the API _action path. HTTP events are rejected: this
+ * function must never be wired to a Function URL or the CDN.
+ */
+export function createOpsLambdaHandler(
+  options: OpsLambdaHandlerOptions
+): (event: Record<string, unknown>) => Promise<unknown> {
+  let cached: { ctx: PluginContext; actions: Record<string, ActionHandler> } | null = null;
+
+  async function ensureInitialized() {
+    if (cached) return cached;
+    const ctx = await options.context();
+    const actions: Record<string, ActionHandler> = {};
+    for (const plugin of options.plugins) {
+      const contribution = await plugin(ctx);
+      if (contribution.actions) Object.assign(actions, contribution.actions);
+    }
+    Object.assign(actions, options.actions ?? {});
+    cached = { ctx, actions };
+    log('info', 'Ops handlers initialized', { actions: Object.keys(actions).length });
+    return cached;
+  }
+
+  return async (event: Record<string, unknown>): Promise<unknown> => {
+    if (!('_action' in event) || typeof event._action !== 'string') {
+      // Not an operator invoke. Reject HTTP-shaped events explicitly.
+      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' };
+    }
+
+    const { ctx, actions } = await ensureInitialized();
+    const actionName = event._action as string;
+    const actionHandler = actions[actionName];
+    if (!actionHandler) {
+      return { error: `Unknown action: ${actionName}` };
+    }
+    log('info', 'Ops action invoked', { action: actionName });
+    try {
+      return await actionHandler(event._payload, ctx);
+    } catch (error) {
+      log('error', 'Ops action error', { action: actionName, error: String(error) });
+      return { error: String(error) };
+    }
+  };
+}
+
 // --- SSR Fallback Plugin ---
 
 import type { PostProcessResult, WebHandlerOptions } from './ssr';
@@ -377,10 +453,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 +471,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 +485,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 +516,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 +532,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 +570,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 +623,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 +632,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 +647,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