bunderstack 0.1.0

package/src/auth.ts

@@ -0,0 +1,102 @@
+import type { LibSQLDatabase } from 'drizzle-orm/libsql'
+
+// src/auth.ts
+import { betterAuth } from 'better-auth'
+import { drizzleAdapter } from 'better-auth/adapters/drizzle'
+
+import type { BetterAuthConfig } from './config'
+import type { AuthSessionResolver } from './access'
+import type { EmailFacade } from './email'
+
+export function createAuth(
+  db: LibSQLDatabase<Record<string, unknown>>,
+  cfg: BetterAuthConfig,
+) {
+  return betterAuth({
+    ...cfg,
+    database: drizzleAdapter(db, { provider: 'sqlite' }),
+  })
+}
+
+/**
+ * Adapt the raw better-auth instance to our internal {@link AuthSessionResolver}
+ * contract. better-auth's `getSession` has a union return (a bare session, or a
+ * `{ headers, response }` wrapper when `returnHeaders` is set); we only ever
+ * call the bare form, so we narrow on `'user' in result` and map to our shape.
+ * Keeping this adapter here means internal modules never depend on better-auth's
+ * evolving types.
+ */
+export function toAuthSessionResolver(
+  auth: ReturnType<typeof createAuth>,
+): AuthSessionResolver {
+  return {
+    api: {
+      async getSession({ headers }) {
+        const result = await auth.api.getSession({ headers })
+        if (result && 'user' in result && result.user) {
+          const session = 'session' in result ? result.session : null
+          const activeOrganizationId =
+            session &&
+            'activeOrganizationId' in session &&
+            typeof session.activeOrganizationId === 'string'
+              ? session.activeOrganizationId
+              : null
+          return {
+            user: {
+              id: result.user.id,
+              email: result.user.email,
+              name: result.user.name,
+            },
+            session: session
+              ? { activeOrganizationId }
+              : null,
+          }
+        }
+        return null
+      },
+    },
+  }
+}
+
+/**
+ * Fill better-auth's email hooks from the bunderstack email facade. Only fills
+ * gaps: user-supplied handlers always win, and nothing is injected when email
+ * isn't configured. emailAndPassword is only touched when the user enabled it
+ * (injecting it unasked would enable the feature).
+ */
+export function withEmailAuthDefaults(
+  cfg: BetterAuthConfig,
+  email: EmailFacade,
+  emailConfigured: boolean,
+): BetterAuthConfig {
+  if (!emailConfigured) return cfg
+  const out: BetterAuthConfig = { ...cfg }
+
+  if (cfg.emailAndPassword?.enabled && !cfg.emailAndPassword.sendResetPassword) {
+    out.emailAndPassword = {
+      ...cfg.emailAndPassword,
+      sendResetPassword: async ({ user, url }) => {
+        await email.send({
+          to: user.email,
+          subject: 'Reset your password',
+          text: `Click the link to reset your password:\n\n${url}\n\nIf you didn't request this, you can ignore this email.`,
+        })
+      },
+    }
+  }
+
+  if (!cfg.emailVerification?.sendVerificationEmail) {
+    out.emailVerification = {
+      ...cfg.emailVerification,
+      sendVerificationEmail: async ({ user, url }) => {
+        await email.send({
+          to: user.email,
+          subject: 'Verify your email',
+          text: `Click the link to verify your email address:\n\n${url}`,
+        })
+      },
+    }
+  }
+
+  return out
+}

package/src/config.ts

@@ -0,0 +1,152 @@
+// src/config.ts
+import { betterAuth } from 'better-auth'
+import { z } from 'zod'
+
+import type { TableAccessInput } from './access'
+import type { IdempotencyConfig } from './idempotency'
+import type { RateLimitConfig } from './rate-limit'
+
+import { validateEnv, type BaseEnv, type EnvConfigInput } from './env'
+import type { EmailConfigInput } from './email'
+
+import {
+  resolveBuckets,
+  type ResolvedStorageBuckets,
+  type StorageConfigInput,
+} from './storage/buckets'
+
+export type BetterAuthConfig = Omit<
+  NonNullable<Parameters<typeof betterAuth>[0]>,
+  'database'
+>
+
+export const BunderstackOptionsSchema = z.object({
+  schema: z.record(z.string(), z.unknown()),
+  access: z.record(z.string(), z.any()).optional(),
+  database: z
+    .object({ url: z.string().optional(), authToken: z.string().optional() })
+    .optional(),
+  auth: z.record(z.string(), z.unknown()).optional(),
+  // Loose: bucket access/scope hold functions that can't survive strict zod
+  // (mirrors how `access` is loose). Resolution happens in resolveBuckets.
+  storage: z.unknown().optional(),
+  // Loose: holds zod schemas. Validation happens in validateEnv.
+  env: z.unknown().optional(),
+  // Loose: provider may be a function/adapter. Resolution happens in createEmail.
+  email: z.unknown().optional(),
+  // Loose: a tRPC router or builder callback. Resolved in createBunderstack.
+  trpc: z.unknown().optional(),
+  rateLimit: z
+    .union([
+      z.boolean(),
+      z.object({
+        windowMs: z.number().optional(),
+        max: z.number().optional(),
+      }),
+    ])
+    .optional(),
+  idempotency: z
+    .union([z.boolean(), z.object({ ttlMs: z.number().optional() })])
+    .optional(),
+  realtime: z
+    .union([
+      z.boolean(),
+      z.object({
+        keepaliveMs: z.number().optional(),
+        bufferSize: z.number().optional(),
+        redis: z
+          .union([
+            z.string(),
+            z.object({ url: z.string(), token: z.string().optional() }),
+          ])
+          .optional(),
+      }),
+    ])
+    .optional(),
+})
+
+export type BunderstackConfig<
+  TSchema extends Record<string, unknown>,
+  TAccess extends Record<string, TableAccessInput> | undefined =
+    | Record<string, TableAccessInput>
+    | undefined,
+  TStorage extends StorageConfigInput | undefined =
+    | StorageConfigInput
+    | undefined,
+  TEnv extends EnvConfigInput | undefined = EnvConfigInput | undefined,
+> = Omit<
+  z.input<typeof BunderstackOptionsSchema>,
+  'schema' | 'access' | 'auth' | 'storage' | 'env' | 'email' | 'trpc'
+> & {
+  schema: TSchema
+  access?: TAccess
+  auth?: BetterAuthConfig
+  storage?: TStorage
+  env?: TEnv
+  email?: EmailConfigInput
+  // `trpc` is intentionally NOT declared here: createBunderstack intersects
+  // its own inference-friendly `trpc` declaration (router | builder callback)
+  // so the callback's `t` parameter gets contextual typing.
+  rateLimit?: boolean | RateLimitConfig
+  idempotency?: boolean | IdempotencyConfig
+  realtime?:
+    | boolean
+    | {
+        keepaliveMs?: number
+        bufferSize?: number
+        redis?: string | { url: string; token?: string }
+      }
+}
+
+export type ResolvedConfig = {
+  database: { url: string; authToken?: string }
+  auth: BetterAuthConfig
+  storage: ResolvedStorageBuckets
+  realtime?:
+    | boolean
+    | {
+        keepaliveMs?: number
+        bufferSize?: number
+        redis?: string | { url: string; token?: string }
+      }
+}
+
+export function resolveConfig<TSchema extends Record<string, unknown>>(
+  options: BunderstackConfig<TSchema>,
+  env?: BaseEnv,
+): ResolvedConfig {
+  const parsed = BunderstackOptionsSchema.parse(options)
+  // Self-validate when the caller didn't pass a pre-validated env, so
+  // resolveConfig stays usable standalone.
+  const resolvedEnv =
+    env ?? validateEnv(options.env as EnvConfigInput | undefined)
+
+  return {
+    database: {
+      url: parsed.database?.url ?? resolvedEnv.DATABASE_URL,
+      authToken: parsed.database?.authToken ?? resolvedEnv.DATABASE_AUTH_TOKEN,
+    },
+    auth: (() => {
+      const authInput = options.auth ?? {}
+      return {
+        ...authInput,
+        secret: authInput.secret ?? resolvedEnv.AUTH_SECRET,
+      }
+    })(),
+    storage: resolveBuckets(options.storage),
+    realtime: parsed.realtime,
+  }
+}
+
+export function resolveRealtimeRedisUrl(
+  realtime: ResolvedConfig['realtime'],
+  env?: BaseEnv,
+): string | undefined {
+  const fromConfig =
+    typeof realtime === 'object' && realtime.redis
+      ? typeof realtime.redis === 'string'
+        ? realtime.redis
+        : realtime.redis.url
+      : undefined
+  return fromConfig ?? env?.REDIS_URL ?? process.env.REDIS_URL ?? undefined
+}

package/src/crud.ts

@@ -0,0 +1,389 @@
+import type { LibSQLDatabase } from 'drizzle-orm/libsql'
+
+import { eq, getTableColumns, getTableName, isTable } from 'drizzle-orm'
+import { Hono } from 'hono'
+
+import type { RealtimeBroker } from './realtime/index'
+
+import {
+  checkAccess,
+  resolveSession,
+  rowMatchesScope,
+  stampScope,
+  sanitizeWriteBody,
+  type AccessUser,
+  type AuthSessionResolver,
+  type CrudOperation,
+  type ResolvedAccess,
+  type ResolvedTableAccess,
+  type ScopeMap,
+} from './access'
+import { ErrorCode, apiError, ListQueryError } from './errors'
+import {
+  lookupIdempotency,
+  resolveIdempotencyConfig,
+  storeIdempotency,
+  type IdempotencyConfig,
+} from './idempotency'
+import { executeList, parseListParams } from './list-query'
+import { buildScopeWhere } from './scope'
+
+export type CrudRouterOptions = {
+  auth?: AuthSessionResolver
+  access: ResolvedAccess
+  idempotency?: boolean | IdempotencyConfig
+  broker?: RealtimeBroker
+}
+
+function tableEntryForName(
+  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)
+}
+
+async function enforce(
+  operation: CrudOperation,
+  access: ResolvedTableAccess,
+  ctx: Parameters<typeof checkAccess>[1],
+) {
+  const rule = access[operation]
+  const result = await checkAccess(rule, ctx, access.ownerColumn)
+  return result
+}
+
+export function buildCrudRouter<TSchema extends Record<string, unknown>>(
+  schema: TSchema,
+  db: LibSQLDatabase<TSchema>,
+  options: CrudRouterOptions,
+): Hono {
+  const router = new Hono()
+  const { auth, access, broker } = options
+  const idempotency = resolveIdempotencyConfig(options.idempotency)
+
+  const scopeFor = (
+    tableAccess: ResolvedTableAccess,
+    ctx: {
+      user: AccessUser | null
+      session: { activeOrganizationId: string | null } | null
+      request: Request
+    },
+  ): ScopeMap | undefined =>
+    tableAccess.scope ? tableAccess.scope({ ...ctx }) : undefined
+
+  for (const table of Object.values(schema)) {
+    if (!isTable(table)) continue
+
+    const name = getTableName(table)
+    const tableAccess = tableEntryForName(access, name)
+    if (!tableAccess?.enabled) continue
+
+    const idCol = getTableColumns(table)['id']
+    if (!idCol) continue
+
+    router.get(`/${name}`, async (c) => {
+      const { user, activeOrganizationId } = await resolveSession(
+        auth,
+        c.req.raw.headers,
+      )
+      const session = { activeOrganizationId }
+      const denied = await enforce('list', tableAccess, {
+        user,
+        session,
+        request: c.req.raw,
+      })
+      if (!denied.allowed) {
+        return apiError(
+          c,
+          ErrorCode.FORBIDDEN,
+          'Forbidden',
+          denied.status === 401 ? 401 : 403,
+        )
+      }
+
+      try {
+        const params = parseListParams(new URL(c.req.url), tableAccess)
+        const scope = scopeFor(tableAccess, {
+          user,
+          session,
+          request: c.req.raw,
+        })
+        const scopeWhere = scope ? buildScopeWhere(table, scope) : undefined
+        const result = await executeList(
+          db,
+          table,
+          tableAccess,
+          params,
+          idCol,
+          scopeWhere,
+        )
+        return c.json(result)
+      } catch (err) {
+        if (err instanceof ListQueryError) {
+          return apiError(c, err.code, err.message, 400, err.details)
+        }
+        throw err
+      }
+    })
+
+    router.get(`/${name}/:id`, async (c) => {
+      const { user, activeOrganizationId } = await resolveSession(
+        auth,
+        c.req.raw.headers,
+      )
+      const session = { activeOrganizationId }
+      const rawId = c.req.param('id')
+      const id = isNaN(Number(rawId)) ? rawId : Number(rawId)
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const rows = await (db as any)
+        .select()
+        .from(table)
+        .where(eq(idCol as any, id))
+      if (!rows[0]) {
+        return apiError(c, ErrorCode.NOT_FOUND, 'Not found', 404)
+      }
+
+      const denied = await enforce('get', tableAccess, {
+        user,
+        session,
+        request: c.req.raw,
+        row: rows[0] as Record<string, unknown>,
+      })
+      if (!denied.allowed) {
+        return apiError(
+          c,
+          ErrorCode.FORBIDDEN,
+          'Forbidden',
+          denied.status === 401 ? 401 : 403,
+        )
+      }
+
+      const scope = scopeFor(tableAccess, { user, session, request: c.req.raw })
+      if (
+        scope &&
+        !rowMatchesScope(rows[0] as Record<string, unknown>, scope)
+      ) {
+        return apiError(c, ErrorCode.NOT_FOUND, 'Not found', 404)
+      }
+
+      return c.json(rows[0])
+    })
+
+    router.post(`/${name}`, async (c) => {
+      const { user, activeOrganizationId } = await resolveSession(
+        auth,
+        c.req.raw.headers,
+      )
+      const session = { activeOrganizationId }
+      const denied = await enforce('create', tableAccess, {
+        user,
+        session,
+        request: c.req.raw,
+      })
+      if (!denied.allowed) {
+        return apiError(
+          c,
+          ErrorCode.FORBIDDEN,
+          'Forbidden',
+          denied.status === 401 ? 401 : 403,
+        )
+      }
+
+      const rawBody = await c.req.text()
+      let body: unknown
+      try {
+        body = rawBody ? JSON.parse(rawBody) : null
+      } catch {
+        return apiError(c, ErrorCode.VALIDATION_ERROR, 'Invalid JSON', 400)
+      }
+      if (!isRecord(body)) {
+        return apiError(c, ErrorCode.VALIDATION_ERROR, 'Invalid JSON body', 400)
+      }
+
+      const idempotencyKey = c.req.header('Idempotency-Key')?.trim()
+      if (idempotency && idempotencyKey) {
+        const lookup = await lookupIdempotency(
+          db,
+          name,
+          idempotencyKey,
+          rawBody,
+          idempotency,
+        )
+        if (lookup.type === 'conflict') {
+          return apiError(
+            c,
+            ErrorCode.IDEMPOTENCY_CONFLICT,
+            'Idempotency key reused with different body',
+            409,
+          )
+        }
+        if (lookup.type === 'replay') {
+          return new Response(lookup.response, {
+            status: lookup.status,
+            headers: {
+              'Content-Type': 'application/json',
+              'Idempotency-Replayed': 'true',
+            },
+          })
+        }
+      }
+
+      const values = sanitizeWriteBody(
+        body,
+        tableAccess,
+        'create',
+        user?.id ?? null,
+      )
+
+      const scope = scopeFor(tableAccess, { user, session, request: c.req.raw })
+      const stamped = scope ? stampScope(values, scope) : values
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const rows = await (db as any).insert(table).values(stamped).returning()
+      const created = rows[0]
+      void broker?.publish(name, 'create', created as Record<string, unknown>)
+
+      if (idempotency && idempotencyKey) {
+        await storeIdempotency(
+          db,
+          name,
+          idempotencyKey,
+          rawBody,
+          201,
+          created,
+          idempotency,
+        )
+      }
+
+      return c.json(created, 201)
+    })
+
+    router.patch(`/${name}/:id`, async (c) => {
+      const { user, activeOrganizationId } = await resolveSession(
+        auth,
+        c.req.raw.headers,
+      )
+      const session = { activeOrganizationId }
+      const rawId = c.req.param('id')
+      const id = isNaN(Number(rawId)) ? rawId : Number(rawId)
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const existing = await (db as any)
+        .select()
+        .from(table)
+        .where(eq(idCol as any, id))
+      if (!existing[0]) {
+        return apiError(c, ErrorCode.NOT_FOUND, 'Not found', 404)
+      }
+
+      const scope = scopeFor(tableAccess, { user, session, request: c.req.raw })
+      if (
+        scope &&
+        !rowMatchesScope(existing[0] as Record<string, unknown>, scope)
+      ) {
+        return apiError(c, ErrorCode.NOT_FOUND, 'Not found', 404)
+      }
+
+      const denied = await enforce('update', tableAccess, {
+        user,
+        session,
+        request: c.req.raw,
+        row: existing[0] as Record<string, unknown>,
+      })
+      if (!denied.allowed) {
+        return apiError(
+          c,
+          ErrorCode.FORBIDDEN,
+          'Forbidden',
+          denied.status === 401 ? 401 : 403,
+        )
+      }
+
+      let body: unknown
+      try {
+        body = await c.req.json()
+      } catch {
+        return apiError(c, ErrorCode.VALIDATION_ERROR, 'Invalid JSON', 400)
+      }
+      if (!isRecord(body)) {
+        return apiError(c, ErrorCode.VALIDATION_ERROR, 'Invalid JSON body', 400)
+      }
+
+      const values = sanitizeWriteBody(
+        body,
+        tableAccess,
+        'update',
+        user?.id ?? null,
+      )
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const rows = await (db as any)
+        .update(table)
+        .set(values)
+        .where(eq(idCol as any, id))
+        .returning()
+      if (!rows[0]) {
+        return apiError(c, ErrorCode.NOT_FOUND, 'Not found', 404)
+      }
+      void broker?.publish(name, 'update', rows[0] as Record<string, unknown>)
+      return c.json(rows[0])
+    })
+
+    router.delete(`/${name}/:id`, async (c) => {
+      const { user, activeOrganizationId } = await resolveSession(
+        auth,
+        c.req.raw.headers,
+      )
+      const session = { activeOrganizationId }
+      const rawId = c.req.param('id')
+      const id = isNaN(Number(rawId)) ? rawId : Number(rawId)
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const existing = await (db as any)
+        .select()
+        .from(table)
+        .where(eq(idCol as any, id))
+      if (!existing[0]) {
+        return apiError(c, ErrorCode.NOT_FOUND, 'Not found', 404)
+      }
+
+      const scope = scopeFor(tableAccess, { user, session, request: c.req.raw })
+      if (
+        scope &&
+        !rowMatchesScope(existing[0] as Record<string, unknown>, scope)
+      ) {
+        return apiError(c, ErrorCode.NOT_FOUND, 'Not found', 404)
+      }
+
+      const denied = await enforce('delete', tableAccess, {
+        user,
+        session,
+        request: c.req.raw,
+        row: existing[0] as Record<string, unknown>,
+      })
+      if (!denied.allowed) {
+        return apiError(
+          c,
+          ErrorCode.FORBIDDEN,
+          'Forbidden',
+          denied.status === 401 ? 401 : 403,
+        )
+      }
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      await (db as any).delete(table).where(eq(idCol as any, id))
+      void broker?.publish(
+        name,
+        'delete',
+        existing[0] as Record<string, unknown>,
+      )
+      return new Response(null, { status: 204 })
+    })
+  }
+
+  return router
+}

package/src/db.ts

@@ -0,0 +1,10 @@
+import { createClient } from '@libsql/client'
+import { drizzle } from 'drizzle-orm/libsql'
+
+export function createDb<TSchema extends Record<string, unknown>>(
+  schema: TSchema,
+  cfg: { url: string; authToken?: string },
+) {
+  const client = createClient({ url: cfg.url, authToken: cfg.authToken })
+  return drizzle(client, { schema })
+}