@everystack/server 0.2.11 → 0.2.13

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.11",
+  "version": "0.2.13",
   "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/console/auth-helpers.ts

@@ -0,0 +1,140 @@
+/**
+ * Console auth helpers — login, asUser, logout.
+ *
+ * These are injected into the console eval scope. They query the DB directly
+ * (no HTTP round-trip) since IAM is the trust boundary for console access.
+ *
+ * Auth state flows through a mutable `AuthSignal` object:
+ * - Helpers write to it during eval
+ * - Console action reads it after eval and includes `_auth` in the response
+ * - CLI picks up `_auth` and updates its session state
+ */
+
+import { eq } from 'drizzle-orm';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface AuthSignal {
+  /** Set by login/asUser, cleared by logout */
+  user: Record<string, unknown> | null;
+  /** Whether the signal was touched during this eval */
+  changed: boolean;
+}
+
+export interface AuthHelperOptions {
+  /** Drizzle database connection */
+  db: any;
+  /** App schema — must contain a users-like table */
+  schema: Record<string, any>;
+  /** Table name in schema that holds users (default: 'users') */
+  usersTable?: string;
+  /** Column that stores the email (default: 'email') */
+  emailColumn?: string;
+  /** Column that stores the hashed password (default: 'encryptedPassword') */
+  passwordColumn?: string;
+  /** Columns to include in the auth claims (default: ['id', 'email', 'role']) */
+  claimColumns?: string[];
+  /** The mutable signal that helpers write auth state to */
+  signal: AuthSignal;
+}
+
+// ─── Factory ────────────────────────────────────────────────────────────────
+
+/**
+ * Create login/asUser/logout functions for the console eval scope.
+ *
+ * Returns an object that can be spread into the eval context:
+ * ```
+ * const { login, asUser, logout } = createAuthHelpers({ db, schema, signal });
+ * ```
+ */
+export function createAuthHelpers(options: AuthHelperOptions): {
+  login: (email: string, password: string) => Promise<Record<string, unknown>>;
+  asUser: (id: string) => Promise<Record<string, unknown>>;
+  logout: () => { logged_out: true };
+} {
+  const {
+    db,
+    schema,
+    usersTable = 'users',
+    emailColumn = 'email',
+    passwordColumn = 'encryptedPassword',
+    claimColumns = ['id', 'email', 'role'],
+    signal,
+  } = options;
+
+  const table = schema[usersTable];
+  if (!table) {
+    // Return stubs that explain the problem
+    const err = async () => { throw new Error(`Auth helpers require a "${usersTable}" table in schema`); };
+    return { login: err as any, asUser: err as any, logout: () => ({ logged_out: true }) };
+  }
+
+  function extractClaims(row: Record<string, unknown>): Record<string, unknown> {
+    const claims: Record<string, unknown> = {};
+    for (const col of claimColumns) {
+      if (row[col] !== undefined) {
+        // Map 'id' to 'sub' for JWT convention
+        const key = col === 'id' ? 'sub' : col;
+        claims[key] = row[col];
+      }
+    }
+    return claims;
+  }
+
+  async function login(email: string, password: string): Promise<Record<string, unknown>> {
+    if (!email || !password) throw new Error('Usage: login(email, password)');
+
+    const emailCol = table[emailColumn];
+    if (!emailCol) throw new Error(`Column "${emailColumn}" not found on ${usersTable} table`);
+
+    const rows = await db.select().from(table).where(eq(emailCol, email)).limit(1);
+    const user = rows[0];
+    if (!user) throw new Error(`No user found with ${emailColumn}: ${email}`);
+
+    const storedHash = user[passwordColumn];
+    if (!storedHash) throw new Error(`No password set for this user (column: ${passwordColumn})`);
+
+    // Dynamic import to avoid hard dependency on @everystack/auth
+    let verifyPassword: (password: string, stored: string) => Promise<boolean>;
+    try {
+      const auth = await import('@everystack/auth');
+      verifyPassword = auth.verifyPassword;
+    } catch {
+      throw new Error('login() requires @everystack/auth to be installed');
+    }
+
+    const valid = await verifyPassword(password, storedHash);
+    if (!valid) throw new Error('Invalid password');
+
+    const claims = extractClaims(user);
+    signal.user = claims;
+    signal.changed = true;
+    return { logged_in: true, ...claims };
+  }
+
+  async function asUser(id: string): Promise<Record<string, unknown>> {
+    if (!id) throw new Error('Usage: asUser(id)');
+
+    // Find the primary key column — try 'id' first
+    const idCol = table.id;
+    if (!idCol) throw new Error(`Column "id" not found on ${usersTable} table`);
+
+    const rows = await db.select().from(table).where(eq(idCol, id)).limit(1);
+    const user = rows[0];
+    if (!user) throw new Error(`No user found with id: ${id}`);
+
+    const claims = extractClaims(user);
+    signal.user = claims;
+    signal.changed = true;
+    return { logged_in: true, ...claims };
+  }
+
+  function logout(): { logged_out: true } {
+    signal.user = null;
+    signal.changed = true;
+    return { logged_out: true };
+  }
+
+  return { login, asUser, logout };
+}

package/src/console/meta.ts

@@ -0,0 +1,138 @@
+/**
+ * Console schema introspection.
+ *
+ * Returns table, column, and RPC metadata for dot commands (.tables,
+ * .columns, .rpc) and tab completion. Pure function — no DB calls.
+ */
+
+import {
+  is, Table,
+  getTableColumns,
+  getTableName,
+} from 'drizzle-orm';
+import { getTableConfig } from 'drizzle-orm/pg-core';
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface ColumnMeta {
+  /** Database column name */
+  name: string;
+  /** JS property name on the table object */
+  property: string;
+  /** Simplified type: uuid, text, timestamp, bigint, etc. */
+  type: string;
+  notNull: boolean;
+  hasDefault: boolean;
+  primaryKey: boolean;
+}
+
+export interface TableMeta {
+  /** PascalCase model name (e.g. "Users") */
+  name: string;
+  /** Database table name (e.g. "users") */
+  dbName: string;
+  columns: ColumnMeta[];
+}
+
+export interface ConsoleMeta {
+  tables: TableMeta[];
+  rpcNames: string[];
+  scope: string[];
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function toPascalCase(str: string): string {
+  return str
+    .replace(/(^|[_-])([a-z])/g, (_, __, c) => c.toUpperCase())
+    .replace(/^[a-z]/, (c) => c.toUpperCase());
+}
+
+/**
+ * Simplify Drizzle column type strings.
+ * "PgUUID" → "uuid", "PgText" → "text", "PgTimestamp" → "timestamp"
+ */
+function simplifyType(columnType: string): string {
+  return columnType.replace(/^Pg/, '').toLowerCase();
+}
+
+/** Detect which columns form the primary key (composite PK support). */
+function detectPkColumns(table: any): Set<string> {
+  const pkProps = new Set<string>();
+  const columns = getTableColumns(table);
+
+  // Single-column PKs
+  for (const [prop, col] of Object.entries(columns)) {
+    if ((col as any).primary) pkProps.add(prop);
+  }
+  if (pkProps.size > 0) return pkProps;
+
+  // Composite PKs via table config
+  try {
+    const config = getTableConfig(table as any);
+    if (config.primaryKeys.length > 0) {
+      const pk = config.primaryKeys[0];
+      const dbNames = new Set(pk.columns.map((c: any) => c.name));
+      for (const [prop, col] of Object.entries(columns)) {
+        if (dbNames.has((col as any).name)) pkProps.add(prop);
+      }
+    }
+  } catch {
+    // Not a pg table — skip composite PK detection
+  }
+
+  return pkProps;
+}
+
+// ─── Main ────────────────────────────────────────────────────────────────────
+
+/**
+ * Build console introspection metadata from a Drizzle schema and plugin context.
+ * No database calls — purely reads schema metadata.
+ */
+export function getConsoleMeta(
+  schema: Record<string, any>,
+  ctx?: { rpc?: Record<string, unknown>; [key: string]: unknown },
+): ConsoleMeta {
+  const tables: TableMeta[] = [];
+
+  for (const [key, value] of Object.entries(schema)) {
+    if (!is(value, Table)) continue;
+
+    const table = value;
+    const pkProps = detectPkColumns(table);
+    const columns: ColumnMeta[] = [];
+
+    for (const [prop, col] of Object.entries(getTableColumns(table))) {
+      columns.push({
+        name: (col as any).name,
+        property: prop,
+        type: simplifyType((col as any).columnType ?? 'unknown'),
+        notNull: !!(col as any).notNull,
+        hasDefault: !!(col as any).hasDefault,
+        primaryKey: pkProps.has(prop),
+      });
+    }
+
+    tables.push({
+      name: toPascalCase(key),
+      dbName: getTableName(table),
+      columns,
+    });
+  }
+
+  // Sort tables alphabetically by model name
+  tables.sort((a, b) => a.name.localeCompare(b.name));
+
+  const rpcNames = ctx?.rpc ? Object.keys(ctx.rpc).sort() : [];
+
+  // Build scope list: drizzle ops + model names + plugin context
+  const drizzleOps = ['eq', 'and', 'or', 'gt', 'lt', 'gte', 'lte', 'ne', 'count', 'sum', 'avg', 'sql', 'desc', 'asc'];
+  const modelNames = tables.map(t => t.name);
+  const base = ['db', 'schema', 'ctx', ...drizzleOps, ...modelNames];
+  if (ctx?.notifications) base.push('notifications');
+  if (ctx?.rpc) base.push('rpc');
+  const scope = base;
+
+  return { tables, rpcNames, scope };
+}

package/src/console/models.ts

@@ -0,0 +1,288 @@
+/**
+ * ActiveRecord-style model layer for Drizzle schemas.
+ *
+ * Generates chainable, thenable query builders from schema tables:
+ *
+ *   await Users.find(123)
+ *   await Posts.where({ state: 'active' }).orderBy('createdAt', 'desc').limit(10)
+ *   await Users.where({ role: 'admin' }).count()
+ *   await Posts.first()
+ *
+ * Models are auto-generated from the schema and exposed in the console eval scope.
+ * PascalCase naming: schema key `users` → model `Users`.
+ */
+
+import {
+  is, Table,
+  getTableColumns,
+  eq, and, isNull, desc as drizzleDesc, asc as drizzleAsc, count as drizzleCount,
+} from 'drizzle-orm';
+import { getTableConfig } from 'drizzle-orm/pg-core';
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+interface PrimaryKeyInfo {
+  /** Single column PK, or null for composite */
+  column: any | null;
+  /** Composite PK columns (property names), empty for single */
+  compositeColumns: string[];
+}
+
+// ─── Query Builder ───────────────────────────────────────────────────────────
+
+/**
+ * Chainable, thenable query builder. Implements `.then()` so `await` resolves
+ * the query directly — no explicit `.execute()` needed.
+ */
+export class ModelQuery {
+  private _db: any;
+  private _table: any;
+  private _conditions: any[];
+  private _orderBys: any[];
+  private _limitVal: number | null;
+  private _offsetVal: number | null;
+
+  constructor(db: any, table: any) {
+    this._db = db;
+    this._table = table;
+    this._conditions = [];
+    this._orderBys = [];
+    this._limitVal = null;
+    this._offsetVal = null;
+  }
+
+  private _clone(): ModelQuery {
+    const q = new ModelQuery(this._db, this._table);
+    q._conditions = [...this._conditions];
+    q._orderBys = [...this._orderBys];
+    q._limitVal = this._limitVal;
+    q._offsetVal = this._offsetVal;
+    return q;
+  }
+
+  /** Filter by column equality. `{ col: null }` maps to `IS NULL`. */
+  where(conditions: Record<string, unknown>): ModelQuery {
+    const q = this._clone();
+    for (const [col, val] of Object.entries(conditions)) {
+      const column = this._table[col];
+      if (!column) throw new Error(`Unknown column: ${col}`);
+      if (val === null) {
+        q._conditions.push(isNull(column));
+      } else {
+        q._conditions.push(eq(column, val));
+      }
+    }
+    return q;
+  }
+
+  /** Order by column. Direction defaults to `'asc'`. */
+  orderBy(column: string, direction: 'asc' | 'desc' = 'asc'): ModelQuery {
+    const q = this._clone();
+    const col = this._table[column];
+    if (!col) throw new Error(`Unknown column: ${column}`);
+    q._orderBys.push(direction === 'desc' ? drizzleDesc(col) : drizzleAsc(col));
+    return q;
+  }
+
+  limit(n: number): ModelQuery {
+    const q = this._clone();
+    q._limitVal = n;
+    return q;
+  }
+
+  offset(n: number): ModelQuery {
+    const q = this._clone();
+    q._offsetVal = n;
+    return q;
+  }
+
+  private _build() {
+    let query = this._db.select().from(this._table);
+    if (this._conditions.length) {
+      query = query.where(
+        this._conditions.length === 1
+          ? this._conditions[0]
+          : and(...this._conditions),
+      );
+    }
+    if (this._orderBys.length) query = query.orderBy(...this._orderBys);
+    if (this._limitVal !== null) query = query.limit(this._limitVal);
+    if (this._offsetVal !== null) query = query.offset(this._offsetVal);
+    return query;
+  }
+
+  /** Thenable — makes `await ModelQuery` resolve the query. */
+  then<T>(
+    resolve: (value: any[]) => T,
+    reject?: (reason: any) => T,
+  ): Promise<T> {
+    return this._build().then(resolve, reject);
+  }
+
+  /** Return first row or undefined. */
+  async first(): Promise<any | undefined> {
+    const rows = await this.limit(1);
+    return rows[0];
+  }
+
+  /** Return last row (by PK desc) or undefined. Falls back to query order reversed. */
+  async last(): Promise<any | undefined> {
+    // If no explicit orderBy, try to order by PK descending
+    if (this._orderBys.length === 0) {
+      const pk = detectPrimaryKey(this._table);
+      if (pk.column) {
+        return this.orderBy(findColumnPropertyName(this._table, pk.column), 'desc').limit(1).first();
+      }
+    }
+    // With explicit order, just take the last of the full result
+    const rows = await this;
+    return rows[rows.length - 1];
+  }
+
+  /** Count matching rows. */
+  async count(): Promise<number> {
+    let query = this._db.select({ count: drizzleCount() }).from(this._table);
+    if (this._conditions.length) {
+      query = query.where(
+        this._conditions.length === 1
+          ? this._conditions[0]
+          : and(...this._conditions),
+      );
+    }
+    const rows = await query;
+    return Number(rows[0]?.count ?? 0);
+  }
+
+  /** Alias for the builder itself (semantics: "all matching rows"). */
+  all(): ModelQuery {
+    return this._clone();
+  }
+}
+
+// ─── Model Interface ─────────────────────────────────────────────────────────
+
+export interface Model {
+  /** Find by primary key. Accepts a value (single PK) or object (composite PK). */
+  find(id: unknown): Promise<any | undefined>;
+  /** Filter by column equality. Chainable. */
+  where(conditions: Record<string, unknown>): ModelQuery;
+  /** All rows (chainable). */
+  all(): ModelQuery;
+  /** First row. */
+  first(): Promise<any | undefined>;
+  /** Last row (by PK desc). */
+  last(): Promise<any | undefined>;
+  /** Count all rows. */
+  count(): Promise<number>;
+  /** Raw drizzle table reference (escape hatch). */
+  table: any;
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function toPascalCase(str: string): string {
+  return str
+    .replace(/(^|[_-])([a-z])/g, (_, __, c) => c.toUpperCase())
+    .replace(/^[a-z]/, (c) => c.toUpperCase());
+}
+
+function detectPrimaryKey(table: any): PrimaryKeyInfo {
+  const columns = getTableColumns(table);
+
+  // Check single-column PKs first
+  for (const [, col] of Object.entries(columns)) {
+    if ((col as any).primary) {
+      return { column: col, compositeColumns: [] };
+    }
+  }
+
+  // Check composite PKs via table config
+  try {
+    const config = getTableConfig(table as any);
+    if (config.primaryKeys.length > 0) {
+      const pk = config.primaryKeys[0];
+      // Map DB column names back to schema property names
+      const dbNames = new Set(pk.columns.map((c: any) => c.name));
+      const propNames: string[] = [];
+      for (const [prop, col] of Object.entries(columns)) {
+        if (dbNames.has((col as any).name)) {
+          propNames.push(prop);
+        }
+      }
+      return { column: null, compositeColumns: propNames };
+    }
+  } catch {
+    // Not a pg table, skip composite PK detection
+  }
+
+  return { column: null, compositeColumns: [] };
+}
+
+/** Find the schema property name for a column object. */
+function findColumnPropertyName(table: any, column: any): string {
+  const columns = getTableColumns(table);
+  for (const [prop, col] of Object.entries(columns)) {
+    if (col === column) return prop;
+  }
+  return 'id'; // fallback
+}
+
+// ─── Factory ─────────────────────────────────────────────────────────────────
+
+/**
+ * Generate ActiveRecord-style models from a Drizzle schema.
+ *
+ * Returns a `Record<PascalCaseName, Model>` that can be spread into the
+ * console eval scope.
+ */
+export function createModels(
+  db: any,
+  schema: Record<string, any>,
+): Record<string, Model> {
+  const models: Record<string, Model> = {};
+
+  for (const [key, value] of Object.entries(schema)) {
+    if (!is(value, Table)) continue;
+
+    const table = value;
+    const name = toPascalCase(key);
+    const pk = detectPrimaryKey(table);
+    const base = () => new ModelQuery(db, table);
+
+    models[name] = {
+      table,
+
+      find: async (id: unknown) => {
+        if (pk.column) {
+          // Single PK
+          const rows = await db.select().from(table).where(eq(pk.column, id)).limit(1);
+          return rows[0];
+        }
+        if (pk.compositeColumns.length > 0 && id && typeof id === 'object') {
+          // Composite PK — id is { userId: '...', postId: '...' }
+          const conditions = pk.compositeColumns.map((prop) => {
+            const col = (table as any)[prop];
+            const val = (id as Record<string, unknown>)[prop];
+            if (val === undefined) throw new Error(`Missing composite PK field: ${prop}`);
+            return eq(col, val);
+          });
+          const rows = await db
+            .select()
+            .from(table)
+            .where(conditions.length === 1 ? conditions[0] : and(...conditions))
+            .limit(1);
+          return rows[0];
+        }
+        throw new Error(`${name} has no detectable primary key`);
+      },
+
+      where: (conditions) => base().where(conditions),
+      all: () => base(),
+      first: () => base().first(),
+      last: () => base().last(),
+      count: () => base().count(),
+    };
+  }
+
+  return models;
+}

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

@@ -355,6 +355,15 @@ export interface DbPluginOptions {
   allowConsole?: boolean;
   /** Read replica URL for db:query (default: process.env.READ_DATABASE_URL) */
   readDatabaseUrl?: string;
+  /** pgSettings callback for console auth context — applied via SET LOCAL when user is present */
+  pgSettings?: (user: Record<string, unknown> | null) => Record<string, string>;
+  /** Console auth helper config — column names for login/asUser (defaults to everystack conventions) */
+  consoleAuth?: {
+    usersTable?: string;
+    emailColumn?: string;
+    passwordColumn?: string;
+    claimColumns?: string[];
+  };
 }
 
 /**
@@ -459,27 +468,126 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
 
     // --- console ---
     if (options.allowConsole !== false) {
+      actions['console:meta'] = async (_payload, ctx) => {
+        const { getConsoleMeta } = await import('./console/meta');
+        return getConsoleMeta(ctx.schema, ctx);
+      };
+
       actions.console = async (payload, ctx) => {
-        const { expression } = payload as { expression: string };
+        const { expression, user: payloadUser, sandbox } = payload as {
+          expression: string;
+          user?: Record<string, unknown>;
+          sandbox?: boolean;
+        };
         if (!expression) return { error: 'No expression provided' };
         try {
-          const { eq, and, or, gt, lt, gte, lte, ne, count, sum, avg, sql, desc, asc } =
-            await import('drizzle-orm');
-          const evalContext: Record<string, unknown> = {
-            ctx,
-            db: ctx.db, schema: ctx.schema,
-            eq, and, or, gt, lt, gte, lte, ne, count, sum, avg, sql, desc, asc,
-          };
-          // Expose plugin-contributed context (notifications, rpc, etc.)
-          if (ctx.notifications) evalContext.notifications = ctx.notifications;
-          if (ctx.rpc) evalContext.rpc = ctx.rpc;
-          const AsyncFunction = Object.getPrototypeOf(async function(){}).constructor;
-          const fn = new AsyncFunction(
-            ...Object.keys(evalContext),
-            `return (${expression})`,
-          );
-          const result = await fn(...Object.values(evalContext));
-          return { result };
+          const drizzle = await import('drizzle-orm');
+          const { eq, and, or, gt, lt, gte, lte, ne, count, sum, avg, sql, desc, asc } = drizzle;
+          const { createModels } = await import('./console/models');
+          const { createAuthHelpers } = await import('./console/auth-helpers');
+
+          // 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,
+            schema: ctx.schema,
+            signal: authSignal,
+            ...options.consoleAuth,
+          });
+
+          // Sentinel for sandbox rollback
+          const SANDBOX_ROLLBACK = Symbol('sandbox_rollback');
+
+          async function evalExpression(db: any) {
+            const models = createModels(db, ctx.schema);
+            const evalContext: Record<string, unknown> = {
+              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,
+            };
+            if (ctx.notifications) evalContext.notifications = ctx.notifications;
+            if (ctx.rpc) evalContext.rpc = ctx.rpc;
+            const AsyncFunction = Object.getPrototypeOf(async function(){}).constructor;
+            const fn = new AsyncFunction(
+              ...Object.keys(evalContext),
+              `return (${expression})`,
+            );
+            return fn(...Object.values(evalContext));
+          }
+
+          let result: unknown;
+
+          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'];
+              if (role) {
+                if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(role)) {
+                  throw new Error(`Invalid role name: ${role}`);
+                }
+                await tx.execute(sql.raw(`SET LOCAL ROLE ${role}`));
+              }
+              for (const [key, value] of Object.entries(settings)) {
+                if (key !== 'role' && value !== undefined && value !== '') {
+                  await tx.execute(sql`SELECT set_config(${key}, ${value}, true)`);
+                }
+              }
+            }
+
+            if (sandbox) {
+              try {
+                await ctx.db.transaction(async (tx: any) => {
+                  await applySettings(tx);
+                  result = await evalExpression(tx);
+                  throw SANDBOX_ROLLBACK;
+                });
+              } catch (err: unknown) {
+                if (err !== SANDBOX_ROLLBACK) throw err;
+              }
+            } else {
+              result = await ctx.db.transaction(async (tx: any) => {
+                await applySettings(tx);
+                return evalExpression(tx);
+              });
+            }
+          } else if (sandbox) {
+            try {
+              await ctx.db.transaction(async (tx: any) => {
+                result = await evalExpression(tx);
+                throw SANDBOX_ROLLBACK;
+              });
+            } catch (err: unknown) {
+              if (err !== SANDBOX_ROLLBACK) throw err;
+            }
+          } else {
+            result = await evalExpression(ctx.db);
+          }
+
+          // 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: safeResult };
+          if (authSignal.changed) {
+            response._auth = { user: authSignal.user };
+          }
+          return response;
         } catch (err: any) {
           return { error: err.message || String(err) };
         }