@everystack/server 0.2.12 → 0.2.14

package/README.md

@@ -16,6 +16,7 @@ pnpm add @everystack/server
 | `@everystack/server/db` | SST Resource-linked database connection |
 | `@everystack/server/ssr` | Expo web SSR bundle serving |
 | `@everystack/server/image` | On-demand image resizing via Sharp |
+| `@everystack/server/media` | Fingerprinted media asset URL resolver |
 | `@everystack/server/migrate` | Drizzle migration runner |
 | `@everystack/server/worker` | SQS job queue consumer |
 | `@everystack/server/stubs` | esbuild bundling helpers for client packages |
@@ -212,6 +213,60 @@ Validates URL query params into transform options:
 | `q` | 1–100 | Quality |
 | `dpr` | 1–3 | Device pixel ratio (multiplies w/h) |
 
+## Media Assets (`@everystack/server/media`)
+
+Resolves logical media asset paths to fingerprinted CDN URLs. During `everystack update`, media assets are uploaded with content-hash suffixes (e.g., `logo-a1b2c3d4.png`) and a `media-manifest.json` is written to the media bucket. This module loads that manifest and resolves URLs at runtime.
+
+### `createMediaResolver(config)`
+
+```typescript
+import { createMediaResolver } from '@everystack/server/media';
+
+const media = createMediaResolver({
+  bucket: Resource.Media.name,  // S3 bucket with media-manifest.json
+  cdnUrl: process.env.CDN_URL,  // CDN base URL (no trailing slash)
+  ttlMs: 60_000,                // Manifest cache TTL (default: 1 minute)
+});
+```
+
+### `resolve(logicalPath)`
+
+Async. Returns the fingerprinted CDN URL. Falls back to the logical path if the manifest is unavailable or the path isn't mapped.
+
+```typescript
+const logoUrl = await media.resolve('email/logo.png');
+// → "https://cdn.example.com/email/logo-a1b2c3d4.png"
+```
+
+### `resolveSync(logicalPath)`
+
+Sync. Uses the cached manifest only. Returns `null` if no manifest has been loaded yet.
+
+```typescript
+const url = media.resolveSync('og/default.png');
+// → "https://cdn.example.com/og/default-f6e5d4c3.png" or null
+```
+
+### `preload()`
+
+Loads the manifest during Lambda init. Call this in `createLambdaHandler`'s `init` to amortize the S3 call across all requests.
+
+```typescript
+export const handler = createLambdaHandler({
+  init: async () => {
+    await media.preload();
+    return { api };
+  },
+  // ...
+});
+```
+
+**Caching behavior:**
+- Manifest cached in module scope across warm Lambda invocations
+- After TTL expires, revalidates via `HeadObject` ETag comparison (one cheap HEAD call)
+- Full re-fetch only when the manifest content changes
+- S3 errors return stale cache gracefully
+
 ## Migrations (`@everystack/server/migrate`)
 
 ### `runMigrations(db, migrationsFolder)`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/server",
-  "version": "0.2.12",
+  "version": "0.2.14",
   "description": "Server runtime primitives for Lambda — event adapters, routing, SSR, image processing",
   "license": "AGPL-3.0-only",
   "publishConfig": {
@@ -51,6 +51,10 @@
     "./kvs": {
       "types": "./src/kvs.ts",
       "default": "./src/kvs.ts"
+    },
+    "./media": {
+      "types": "./src/media.ts",
+      "default": "./src/media.ts"
     }
   },
   "scripts": {

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/media.ts

@@ -0,0 +1,126 @@
+/**
+ * @everystack/server/media — Fingerprinted media asset URL resolver.
+ *
+ * Loads the media manifest from S3 and resolves logical asset names
+ * to fingerprinted CDN URLs. Lazy-loaded, cached with TTL for
+ * revalidation on new deploys.
+ *
+ * Usage:
+ *   const media = createMediaResolver({ bucket: Resource.Media.name, cdnUrl: process.env.CDN_URL });
+ *   await media.preload();
+ *   const url = await media.resolve('email/logo.png');
+ *   // → "https://cdn.example.com/email/logo-a1b2c3d4.png"
+ */
+
+export interface MediaManifest {
+  version: number;
+  generatedAt: string;
+  files: Record<string, string>;
+}
+
+export interface MediaResolverConfig {
+  /** S3 bucket name for media assets. */
+  bucket: string;
+  /** AWS region (defaults to process.env.AWS_REGION). */
+  region?: string;
+  /** CDN base URL (e.g., 'https://cdn.example.com'). No trailing slash. */
+  cdnUrl?: string;
+  /** Manifest TTL in milliseconds. Default: 60_000 (1 minute). */
+  ttlMs?: number;
+}
+
+interface CachedManifest {
+  manifest: MediaManifest;
+  etag: string;
+  loadedAt: number;
+}
+
+export function createMediaResolver(config: MediaResolverConfig): MediaResolver {
+  const {
+    bucket,
+    ttlMs = 60_000,
+  } = config;
+  const region = config.region || process.env.AWS_REGION;
+  const cdnUrl = (config.cdnUrl || '').replace(/\/$/, '');
+
+  let cached: CachedManifest | null = null;
+
+  async function loadManifest(): Promise<MediaManifest | null> {
+    const now = Date.now();
+
+    if (cached && (now - cached.loadedAt) < ttlMs) {
+      return cached.manifest;
+    }
+
+    try {
+      const { S3Client, GetObjectCommand, HeadObjectCommand } = await import('@aws-sdk/client-s3');
+      const client = new S3Client({ region });
+
+      // ETag-based revalidation: cheap HEAD instead of full GET
+      if (cached) {
+        const head = await client.send(new HeadObjectCommand({
+          Bucket: bucket,
+          Key: 'media-manifest.json',
+        }));
+        if (head.ETag === cached.etag) {
+          cached.loadedAt = now;
+          return cached.manifest;
+        }
+      }
+
+      const response = await client.send(new GetObjectCommand({
+        Bucket: bucket,
+        Key: 'media-manifest.json',
+      }));
+      if (!response.Body) return cached?.manifest ?? null;
+
+      const bytes = await response.Body.transformToByteArray();
+      const manifest: MediaManifest = JSON.parse(
+        Buffer.from(bytes).toString('utf8'),
+      );
+
+      cached = {
+        manifest,
+        etag: response.ETag || '',
+        loadedAt: now,
+      };
+      return manifest;
+    } catch {
+      // S3 error — return stale cache if available
+      return cached?.manifest ?? null;
+    }
+  }
+
+  return {
+    async resolve(logicalPath: string): Promise<string> {
+      const manifest = await loadManifest();
+      const resolved = manifest?.files[logicalPath] ?? logicalPath;
+      return cdnUrl ? `${cdnUrl}/${resolved}` : `/${resolved}`;
+    },
+
+    resolveSync(logicalPath: string): string | null {
+      if (!cached) return null;
+      const resolved = cached.manifest.files[logicalPath] ?? logicalPath;
+      return cdnUrl ? `${cdnUrl}/${resolved}` : `/${resolved}`;
+    },
+
+    async preload(): Promise<void> {
+      await loadManifest();
+    },
+
+    clearCache(): void {
+      cached = null;
+    },
+  };
+}
+
+export interface MediaResolver {
+  /** Resolve a logical media path to a fingerprinted CDN URL. Falls back to logical path if manifest unavailable. */
+  resolve(logicalPath: string): Promise<string>;
+  /** Sync resolve from cached manifest. Returns null if no manifest cached. */
+  resolveSync(logicalPath: string): string | null;
+  /** Pre-load the manifest. Call during Lambda init. */
+  preload(): Promise<void>;
+  /** Clear the cached manifest (for testing). */
+  clearCache(): void;
+}

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,
@@ -504,6 +585,7 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
               ctx,
               db, schema: ctx.schema,
               eq, and, or, gt, lt, gte, lte, ne, count, sum, avg, sql, desc, asc,
+              current_user: payloadUser ?? null,
               ...models,
               ...authHelpers,
             };
@@ -519,8 +601,10 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
 
           let result: unknown;
 
-          if (payloadUser && options.pgSettings) {
-            const settings = options.pgSettings(payloadUser);
+          if (options.pgSettings) {
+            // Always apply pgSettings when configured — enforces RLS.
+            // Without a logged-in user, pgSettings(null) returns anon role settings.
+            const settings = options.pgSettings(payloadUser ?? null);
 
             async function applySettings(tx: any) {
               const role = settings['role'];
@@ -538,9 +622,8 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
             }
 
             if (sandbox) {
-              // pgSettings + sandbox: apply settings, eval, capture result, rollback
               try {
-                await ctx.db.transaction(async (tx: any) => {
+                await opsDb.transaction(async (tx: any) => {
                   await applySettings(tx);
                   result = await evalExpression(tx);
                   throw SANDBOX_ROLLBACK;
@@ -549,16 +632,14 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
                 if (err !== SANDBOX_ROLLBACK) throw err;
               }
             } else {
-              // pgSettings without sandbox: normal transaction
-              result = await ctx.db.transaction(async (tx: any) => {
+              result = await opsDb.transaction(async (tx: any) => {
                 await applySettings(tx);
                 return evalExpression(tx);
               });
             }
           } else if (sandbox) {
-            // Sandbox without auth: wrap in transaction and rollback
             try {
-              await ctx.db.transaction(async (tx: any) => {
+              await opsDb.transaction(async (tx: any) => {
                 result = await evalExpression(tx);
                 throw SANDBOX_ROLLBACK;
               });
@@ -566,11 +647,24 @@ 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
+          // that Lambda can't JSON.stringify (e.g. Drizzle schema objects)
+          let safeResult: unknown;
+          try {
+            JSON.stringify(result);
+            safeResult = result;
+          } catch {
+            // Not JSON-serializable — return a useful string representation
+            safeResult = typeof result === 'object' && result !== null
+              ? `[${result.constructor?.name ?? 'Object'}: keys=${Object.keys(result).join(', ')}]`
+              : String(result);
           }
 
           // Build response with optional auth side-channel
-          const response: Record<string, unknown> = { result };
+          const response: Record<string, unknown> = { result: safeResult };
           if (authSignal.changed) {
             response._auth = { user: authSignal.user };
           }