bunderstack 0.15.1 → 0.16.0

package/src/manifest.ts

@@ -5,13 +5,13 @@ import type { Dialect } from './dialect'
 import type { EnvConfigInput } from './env'
 import type { JobsDefs } from './jobs/define'
 import type { ResolvedBucket, ResolvedStorageBuckets } from './storage/buckets'
-import { parseCron } from './jobs/cron'
+
 import {
-  bunderstackCronRuns,
   bunderstackFiles,
   bunderstackIdempotency,
   bunderstackJobs,
 } from './internal-tables'
+import { parseCron } from './jobs/cron'
 
 export type ManifestEnvVar = {
   key: string
@@ -47,8 +47,12 @@ const nonEmpty = z.string().min(1)
 const migrationDirectory = nonEmpty.refine(
   (value) =>
     value.startsWith('/') ||
-    (!value.includes('\\') && value.split('/').every((part) => part !== '..' && part !== '')),
-  { message: 'migrationsDirectory must be an absolute path or a relative path without traversal' },
+    (!value.includes('\\') &&
+      value.split('/').every((part) => part !== '..' && part !== '')),
+  {
+    message:
+      'migrationsDirectory must be an absolute path or a relative path without traversal',
+  },
 )
 const cronSchedule = nonEmpty.refine(
   (value) => {
@@ -85,7 +89,10 @@ const manifestSchema = z
         defaultBucket: nonEmpty,
         buckets: z.array(
           z
-            .object({ name: nonEmpty, visibility: z.enum(['public', 'private']) })
+            .object({
+              name: nonEmpty,
+              visibility: z.enum(['public', 'private']),
+            })
             .strict(),
         ),
       })
@@ -133,13 +140,16 @@ function sortBy<T>(entries: readonly T[], key: (entry: T) => string): T[] {
 function rejectDuplicates(collection: string, values: readonly string[]): void {
   const seen = new Set<string>()
   for (const value of values) {
-    if (seen.has(value)) throw new Error(`[bunderstack] duplicate ${collection} "${value}"`)
+    if (seen.has(value))
+      throw new Error(`[bunderstack] duplicate ${collection} "${value}"`)
     seen.add(value)
   }
 }
 
 function describeTables(schema: Record<string, unknown>) {
-  const systemNames = new Set<string>(systemTables().map((table) => table.physicalName))
+  const systemNames = new Set<string>(
+    systemTables().map((table) => table.physicalName),
+  )
   return sortBy(
     Object.entries(schema).flatMap(([exportName, value]) =>
       isTable(value) && !systemNames.has(getTableName(value))
@@ -163,16 +173,19 @@ function describeSection(
 
 function systemTables() {
   return [
-    { exportName: '_system.files', physicalName: getTableName(bunderstackFiles), system: true },
+    {
+      exportName: '_system.files',
+      physicalName: getTableName(bunderstackFiles),
+      system: true,
+    },
     {
       exportName: '_system.idempotency',
       physicalName: getTableName(bunderstackIdempotency),
       system: true,
     },
-    { exportName: '_system.jobs', physicalName: getTableName(bunderstackJobs), system: true },
     {
-      exportName: '_system.scheduledRuns',
-      physicalName: getTableName(bunderstackCronRuns),
+      exportName: '_system.jobs',
+      physicalName: getTableName(bunderstackJobs),
       system: true,
     },
   ]
@@ -180,13 +193,34 @@ function systemTables() {
 
 export function parseManifest(value: unknown): BunderstackManifest {
   const manifest = manifestSchema.parse(value) as BunderstackManifest
-  rejectDuplicates('database physical table', manifest.database.tables.map((entry) => entry.physicalName))
-  rejectDuplicates('database export table', manifest.database.tables.map((entry) => entry.exportName))
-  rejectDuplicates('storage bucket', manifest.storage.buckets.map((entry) => entry.name))
-  rejectDuplicates('environment key', manifest.environment.map((entry) => entry.key))
-  rejectDuplicates('background job', manifest.background.jobs.map((entry) => entry.name))
-  rejectDuplicates('background cron', manifest.background.cron.map((entry) => entry.name))
-  rejectDuplicates('background maintenance', manifest.background.maintenance.map((entry) => entry.name))
+  rejectDuplicates(
+    'database physical table',
+    manifest.database.tables.map((entry) => entry.physicalName),
+  )
+  rejectDuplicates(
+    'database export table',
+    manifest.database.tables.map((entry) => entry.exportName),
+  )
+  rejectDuplicates(
+    'storage bucket',
+    manifest.storage.buckets.map((entry) => entry.name),
+  )
+  rejectDuplicates(
+    'environment key',
+    manifest.environment.map((entry) => entry.key),
+  )
+  rejectDuplicates(
+    'background job',
+    manifest.background.jobs.map((entry) => entry.name),
+  )
+  rejectDuplicates(
+    'background cron',
+    manifest.background.cron.map((entry) => entry.name),
+  )
+  rejectDuplicates(
+    'background maintenance',
+    manifest.background.maintenance.map((entry) => entry.name),
+  )
   return manifest
 }
 
@@ -210,14 +244,20 @@ export function buildManifest(args: {
       ? [{ key: 'SMTP_URL', required: true, scope: 'server' as const }]
       : []),
   ]
-  rejectDuplicates('environment key', environment.map((entry) => entry.key))
+  rejectDuplicates(
+    'environment key',
+    environment.map((entry) => entry.key),
+  )
 
   return parseManifest({
     version: 3,
     database: {
       dialect: args.dialect,
       migrationsDirectory: args.migrationsDirectory,
-      tables: sortBy([...systemTables(), ...describeTables(args.schema)], (entry) => entry.physicalName),
+      tables: sortBy(
+        [...systemTables(), ...describeTables(args.schema)],
+        (entry) => entry.physicalName,
+      ),
     },
     storage: {
       defaultBucket: args.storage.defaultBucket,
@@ -249,7 +289,11 @@ export function buildManifest(args: {
         (entry) => entry.name,
       ),
       maintenance: [
-        { name: 'storage-sweep', schedule: '0 4 * * *', timezone: 'UTC' as const },
+        {
+          name: 'storage-sweep',
+          schedule: '0 4 * * *',
+          timezone: 'UTC' as const,
+        },
       ],
     },
   })

package/src/realtime/index.ts

@@ -5,6 +5,7 @@ import {
   checkAccessSync,
   resolveSession,
   rowMatchesScope,
+  tableEntryForName,
   type AccessUser,
   type AuthSessionResolver,
   type ResolvedAccess,
@@ -55,15 +56,6 @@ export type RealtimeBroker = {
   ): void | Promise<void>
 }
 
-function tableEntry(
-  access: ResolvedAccess,
-  tableName: string,
-): ResolvedTableAccess | undefined {
-  for (const entry of access.values()) {
-    if (entry.tableName === tableName) return entry
-  }
-  return undefined
-}
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === 'object' && !Array.isArray(value)
@@ -166,7 +158,7 @@ export function createRealtimeBroker(opts: {
     record: Record<string, unknown>,
     id: unknown,
   ): boolean {
-    const entry = tableEntry(opts.access, table)
+    const entry = tableEntryForName(opts.access, table)
     if (!entry) return false
     const topicMatch =
       s.subscriptions.has(table) ||
@@ -232,7 +224,7 @@ export function createRealtimeBroker(opts: {
       subscribers.delete(id)
     },
     publish(table, action, record) {
-      const entry = tableEntry(opts.access, table)
+      const entry = tableEntryForName(opts.access, table)
       if (!entry) return
       const eventId = nextId++
       buffer.push({ eventId, table, action, record })

package/src/realtime/redis.ts

@@ -12,9 +12,9 @@ import type { RealtimeAction, RealtimeBroker } from './index'
 import {
   checkAccessSync,
   rowMatchesScope,
+  tableEntryForName,
   type AccessUser,
   type ResolvedAccess,
-  type ResolvedTableAccess,
 } from '../access'
 
 export type RedisLike = {
@@ -45,15 +45,6 @@ type WireEvent = {
   record: Record<string, unknown>
 }
 
-function tableEntry(
-  access: ResolvedAccess,
-  name: string,
-): ResolvedTableAccess | undefined {
-  for (const entry of access.values())
-    if (entry.tableName === name) return entry
-  return undefined
-}
-
 function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === 'object' && !Array.isArray(value)
 }
@@ -109,7 +100,7 @@ export function createRedisRealtimeBroker(opts: {
     table: string,
     record: Record<string, unknown>,
   ): boolean {
-    const entry = tableEntry(opts.access, table)
+    const entry = tableEntryForName(opts.access, table)
     if (!entry) return false
     const id = record['id']
     const topicMatch =
@@ -208,7 +199,7 @@ export function createRedisRealtimeBroker(opts: {
       subscribers.delete(id)
     },
     async publish(table, action, record) {
-      if (!tableEntry(opts.access, table)) return
+      if (!tableEntryForName(opts.access, table)) return
       try {
         const client = getRedis()
         const eventId = await client.incr(counterKey)

package/src/routes.ts

@@ -0,0 +1,137 @@
+// src/routes.ts — mounting user-supplied Hono routes inside the app.
+
+/** A route as Hono reports it on `app.routes`. */
+export type DeclaredRoute = { method: string; path: string }
+
+const RESERVED_EXACT = ['/health', '/api/health', '/api/realtime'] as const
+
+const RESERVED_PREFIXES = [
+  '/api/auth/',
+  '/api/trpc/',
+  '/api/files/',
+  '/files/',
+] as const
+
+/** The first path segment under `/api/`, or undefined when not under it. */
+function apiSegment(path: string): string | undefined {
+  if (!path.startsWith('/api/')) return undefined
+  return path.slice('/api/'.length).split('/')[0]
+}
+
+function collisionFor(
+  route: DeclaredRoute,
+  tableNames: readonly string[],
+): string | undefined {
+  const { path } = route
+  if (RESERVED_EXACT.includes(path as (typeof RESERVED_EXACT)[number])) {
+    return `it is reserved by bunderstack`
+  }
+  for (const prefix of RESERVED_PREFIXES) {
+    if (path.startsWith(prefix)) {
+      return `"${prefix}*" is reserved by bunderstack`
+    }
+  }
+  const segment = apiSegment(path)
+  if (segment === undefined) return undefined
+  if (segment === '*' || segment.startsWith(':')) {
+    return `a parameter or wildcard here would shadow every generated CRUD route`
+  }
+  if (tableNames.includes(segment)) {
+    return `it collides with the generated CRUD route for table "${segment}"`
+  }
+  return undefined
+}
+
+/**
+ * Throws when any declared route would collide with a bunderstack route.
+ *
+ * Custom routes are registered before the built-ins, so a collision silently
+ * shadows core behaviour — including authentication. Failing at construction is
+ * the cheapest place to find out.
+ */
+export function validateCustomRoutes(
+  routes: readonly DeclaredRoute[],
+  tableNames: readonly string[],
+): void {
+  const problems: string[] = []
+  for (const route of routes) {
+    const reason = collisionFor(route, tableNames)
+    if (reason) {
+      problems.push(`  ${route.method} ${route.path} — ${reason}`)
+    }
+  }
+  if (problems.length === 0) return
+  throw new Error(
+    `[bunderstack] routes: ${problems.length} route(s) collide with bunderstack's own:\n${problems.join('\n')}\nChoose different paths.`,
+  )
+}
+
+import type { Hono } from 'hono'
+
+import type { AccessUser, AuthSessionResolver } from './access'
+import type { DbFor } from './db'
+import type { EmailFacade } from './email'
+import type { JobsRuntimeFacade } from './jobs/define'
+import type { RealtimeFacade } from './realtime/facade'
+import type { AuthInstance, StorageFacade } from './index'
+
+import { resolveAccessUser, resolveSession } from './access'
+
+export type RouteContext<
+  TSchema extends Record<string, unknown> = Record<string, unknown>,
+  TEnvResult = Record<string, unknown>,
+> = {
+  db: DbFor<TSchema>
+  env: TEnvResult
+  storage: StorageFacade
+  email: EmailFacade
+  jobs: JobsRuntimeFacade
+  realtime: RealtimeFacade<TSchema>
+  auth: AuthInstance
+  /** Resolve the caller's session. Costs an auth round-trip; call only when needed. */
+  getSession(
+    request: Request,
+  ): Promise<{ user: AccessUser | null; activeOrganizationId: string | null }>
+  /** Convenience wrapper over getSession when the organization is irrelevant. */
+  getUser(request: Request): Promise<AccessUser | null>
+}
+
+/** Alias mirroring the JobContext / BunderstackJobContext pair. */
+export type BunderstackRouteContext<
+  TSchema extends Record<string, unknown> = Record<string, unknown>,
+  TEnvResult = Record<string, unknown>,
+> = RouteContext<TSchema, TEnvResult>
+
+export type RoutesBuilder<
+  TSchema extends Record<string, unknown> = Record<string, unknown>,
+  TEnvResult = Record<string, unknown>,
+> = (ctx: RouteContext<TSchema, TEnvResult>) => Hono
+
+export function createRouteContext<
+  TSchema extends Record<string, unknown>,
+  TEnvResult,
+>(deps: {
+  db: DbFor<TSchema>
+  env: TEnvResult
+  storage: StorageFacade
+  email: EmailFacade
+  jobs: JobsRuntimeFacade
+  realtime: RealtimeFacade<TSchema>
+  auth: AuthInstance
+  authResolver: AuthSessionResolver | undefined
+}): RouteContext<TSchema, TEnvResult> {
+  return {
+    db: deps.db,
+    env: deps.env,
+    storage: deps.storage,
+    email: deps.email,
+    jobs: deps.jobs,
+    realtime: deps.realtime,
+    auth: deps.auth,
+    // Lazy on purpose: a webhook has no session, and resolving one eagerly
+    // would spend an auth round-trip per request on a value nobody reads.
+    getSession: (request) => resolveSession(deps.authResolver, request.headers),
+    getUser: (request) => resolveAccessUser(deps.authResolver, request.headers),
+  }
+}
+

package/src/storage/buckets.ts

@@ -266,7 +266,8 @@ export function resolveBuckets(
   input: StorageConfigInput | undefined,
   env: Record<string, string | undefined> = process.env,
 ): ResolvedStorageBuckets {
-  const sharedBackend = platformS3Backend(env) ?? resolveSharedBackend(input, env)
+  const sharedBackend =
+    platformS3Backend(env) ?? resolveSharedBackend(input, env)
   const bucketsInput = input?.buckets
 
   const declaredNames = bucketsInput ? Object.keys(bucketsInput) : []

package/src/storage/file-meta.ts

@@ -29,8 +29,8 @@
 
 import { eq, and, lt, sql } from 'drizzle-orm'
 
-import type { AnyDb } from '../dialect'
 import type { ScopeMap } from '../access'
+import type { AnyDb } from '../dialect'
 
 import { rowMatchesScope } from '../access'
 import { bunderstackFiles, filesTableFor } from '../internal-tables'

package/src/storage/router.ts

@@ -27,11 +27,7 @@ import {
   sumReadySize,
   type FileMetaRow,
 } from './file-meta'
-import {
-  parseTransformSpec,
-  transformHash,
-  transformImage,
-} from './thumbnails'
+import { parseTransformSpec, transformHash, transformImage } from './thumbnails'
 
 export interface BucketStorageRouterOptions {
   registry: BucketStorageRegistry
@@ -379,7 +375,7 @@ export function buildBucketStorageRouter(
     if (!entry) return apiError(c, ErrorCode.NOT_FOUND, 'Unknown bucket', 404)
     const { bucket, adapter } = entry
 
-    const mountPrefix = c.req.routePath.replace(/\/:[^\/]+\/\*$/, '')
+    const mountPrefix = c.req.routePath.replace(/\/:[^/]+\/\*$/, '')
     const id = c.req.path.slice(`${mountPrefix}/${bucketName}/`.length)
     const fileId = `${bucketName}/${id}`
 

package/src/storage/s3.ts

@@ -39,11 +39,17 @@ export class S3StorageAdapter implements StorageAdapter {
   }
 
   async get(fileId: string): Promise<Response> {
-    const exists = await this.client.exists(fileId)
-    if (!exists) return new Response('Not found', { status: 404 })
+    // `stat` (a HEAD, same cost as `exists`) is the only way to learn the
+    // stored Content-Type: a lazily-constructed `client.file(key)` reports
+    // `type: ""` — it never stats, and unlike `Bun.file` it does not guess
+    // from the extension either.
+    const info = await this.stat(fileId)
+    if (!info) return new Response('Not found', { status: 404 })
     const file = this.client.file(fileId)
     return new Response(file.stream(), {
-      headers: { 'Content-Type': file.type ?? 'application/octet-stream' },
+      headers: {
+        'Content-Type': info.contentType || 'application/octet-stream',
+      },
     })
   }
 

package/src/trpc.ts

@@ -5,9 +5,9 @@ import superjson from 'superjson'
 import type { AccessUser } from './access'
 import type { DbFor } from './db'
 import type { EmailFacade } from './email'
+import type { StorageFacade } from './index'
 import type { JobsRuntimeFacade } from './jobs/index'
 import type { RealtimeFacade } from './realtime/facade'
-import type { StorageFacade } from './index'
 
 export type TRPCContext<
   TSchema extends Record<string, unknown>,

package/src/jobs/cron-auth.ts

@@ -1,28 +0,0 @@
-import { createHmac, timingSafeEqual } from 'node:crypto'
-
-function canonical(taskId: string, slot: number): string {
-  return `${taskId}\n${slot}`
-}
-
-export function signScheduleRequest(
-  secret: string,
-  taskId: string,
-  slot: number,
-): string {
-  const digest = createHmac('sha256', secret)
-    .update(canonical(taskId, slot))
-    .digest('hex')
-  return `sha256=${digest}`
-}
-
-export function verifyScheduleRequest(
-  secret: string,
-  taskId: string,
-  slot: number,
-  signature: string,
-): boolean {
-  if (!/^sha256=[0-9a-f]{64}$/.test(signature)) return false
-  const expected = Buffer.from(signScheduleRequest(secret, taskId, slot))
-  const received = Buffer.from(signature)
-  return timingSafeEqual(expected, received)
-}

package/src/jobs/cron-router.ts

@@ -1,131 +0,0 @@
-import { Hono } from 'hono'
-import { and, eq, lt } from 'drizzle-orm'
-
-import type { AnyDb } from '../dialect'
-import type { BackgroundDefs } from './define'
-
-import { verifyScheduleRequest } from './cron-auth'
-import { runCronSlot, runScheduledSlot } from './cron-runner'
-import { cronRunsTableFor } from '../internal-tables'
-
-const MAX_SLOT_AGE_MS = 60 * 60_000
-const MAX_FUTURE_SLOT_MS = 60_000
-const STORAGE_SWEEP_SCHEDULE = '0 4 * * *'
-const SCHEDULED_RUN_RETENTION_MS = 30 * 24 * 60 * 60_000
-
-export function buildCronRouter(args: {
-  db: AnyDb
-  defs: BackgroundDefs
-  ctx: Record<string, unknown>
-  secret: string
-  storage: { sweep: () => Promise<unknown> }
-  now?: () => number
-}): Hono {
-  const app = new Hono()
-  const now = args.now ?? Date.now
-
-  app.post('/cron/:name', async (c) => {
-    const name = c.req.param('name')
-    const slotText = c.req.header('X-Bunderstack-Cron-Slot')
-    const signature = c.req.header('X-Bunderstack-Cron-Signature')
-    const slot = Number(slotText)
-    if (!slotText || !Number.isSafeInteger(slot) || !signature) {
-      return c.json({ error: 'invalid schedule signature' }, 401)
-    }
-    if (!verifyScheduleRequest(args.secret, `cron:${name}`, slot, signature)) {
-      return c.json({ error: 'invalid schedule signature' }, 401)
-    }
-    const definition = args.defs[name]
-    if (!definition || definition.kind !== 'cron') {
-      return c.json({ error: 'unknown cron' }, 404)
-    }
-    const current = now()
-    if (
-      slot % 60_000 !== 0 ||
-      slot < current - MAX_SLOT_AGE_MS ||
-      slot > current + MAX_FUTURE_SLOT_MS
-    ) {
-      return c.json({ error: 'invalid cron slot' }, 400)
-    }
-    try {
-      const result = await runCronSlot({
-        db: args.db,
-        defs: args.defs,
-        ctx: args.ctx,
-        name,
-        slot,
-        now: current,
-      })
-      return c.json(
-        result,
-        result.status === 'running' ? 202 : 200,
-      )
-    } catch (error) {
-      if (
-        error instanceof Error &&
-        error.message === '[bunderstack] cron slot does not match its schedule'
-      ) {
-        return c.json({ error: 'invalid cron slot' }, 400)
-      }
-      return c.json({ error: 'cron handler failed' }, 500)
-    }
-  })
-
-  app.post('/maintenance/:name', async (c) => {
-    const name = c.req.param('name')
-    const slotText = c.req.header('X-Bunderstack-Cron-Slot')
-    const signature = c.req.header('X-Bunderstack-Cron-Signature')
-    const slot = Number(slotText)
-    if (!slotText || !Number.isSafeInteger(slot) || !signature) {
-      return c.json({ error: 'invalid schedule signature' }, 401)
-    }
-    if (!verifyScheduleRequest(args.secret, `maintenance:${name}`, slot, signature)) {
-      return c.json({ error: 'invalid schedule signature' }, 401)
-    }
-    if (name !== 'storage-sweep') {
-      return c.json({ error: 'unknown maintenance task' }, 404)
-    }
-    const current = now()
-    if (
-      slot % 60_000 !== 0 ||
-      slot < current - MAX_SLOT_AGE_MS ||
-      slot > current + MAX_FUTURE_SLOT_MS
-    ) {
-      return c.json({ error: 'invalid cron slot' }, 400)
-    }
-    try {
-      const result = await runScheduledSlot({
-        db: args.db,
-        taskId: 'maintenance:storage-sweep',
-        schedule: STORAGE_SWEEP_SCHEDULE,
-        slot,
-        now: current,
-        run: async () => {
-          await args.storage.sweep()
-        },
-      })
-      if (result.status === 'succeeded') {
-        const t = cronRunsTableFor(args.db)
-        await args.db
-          .delete(t)
-          .where(
-            and(
-              eq(t.status, 'succeeded'),
-              lt(t.finishedAt, current - SCHEDULED_RUN_RETENTION_MS),
-            ),
-          )
-      }
-      return c.json(result, result.status === 'running' ? 202 : 200)
-    } catch (error) {
-      if (
-        error instanceof Error &&
-        error.message === '[bunderstack] cron slot does not match its schedule'
-      ) {
-        return c.json({ error: 'invalid cron slot' }, 400)
-      }
-      return c.json({ error: 'maintenance handler failed' }, 500)
-    }
-  })
-
-  return app
-}