bunderstack 0.1.0

package/src/storage/buckets.ts

@@ -0,0 +1,273 @@
+// src/storage/buckets.ts
+import type { OperationRule, ScopeResolver } from '../access'
+
+// ---------------------------------------------------------------------------
+// Input types (developer-facing config)
+// ---------------------------------------------------------------------------
+
+export type BucketBackendInput =
+  | {
+      s3: {
+        bucket: string
+        region?: string
+        endpoint?: string
+        publicUrl?: string
+      }
+    }
+  | { local: string }
+
+export type BucketConfigInput = {
+  visibility?: 'public' | 'private'
+  access?: {
+    create?: OperationRule
+    get?: OperationRule
+    delete?: OperationRule
+  }
+  upload?: { maxSize?: string | number; accept?: string[] }
+  transforms?: boolean
+  scope?: ScopeResolver
+  quota?: { perUser?: string | number; perScope?: string | number }
+} & Partial<BucketBackendInput>
+
+export type StorageConfigInput = {
+  s3?: true | { endpoint?: string }
+  local?: true | string
+  defaultBucket?: string
+  buckets?: Record<string, BucketConfigInput>
+}
+
+// ---------------------------------------------------------------------------
+// Resolved types (internal)
+// ---------------------------------------------------------------------------
+
+export type ResolvedBackend =
+  | { type: 'local'; path: string }
+  | {
+      type: 's3'
+      bucket: string
+      region: string
+      endpoint?: string
+      accessKeyId: string
+      secretAccessKey: string
+      publicUrl?: string
+    }
+
+export type ResolvedBucket = {
+  name: string
+  backend: ResolvedBackend
+  visibility: 'public' | 'private'
+  access: { create: OperationRule; get: OperationRule; delete: OperationRule }
+  upload?: { maxSizeBytes?: number; accept?: string[] }
+  transforms: boolean
+  scope?: ScopeResolver
+  quota?: { perUserBytes?: number; perScopeBytes?: number }
+}
+
+export type ResolvedStorageBuckets = {
+  defaultBucket: string
+  buckets: Map<string, ResolvedBucket>
+}
+
+// ---------------------------------------------------------------------------
+// parseSize
+// ---------------------------------------------------------------------------
+
+const SIZE_UNITS: Record<string, number> = {
+  b: 1,
+  kb: 1024,
+  mb: 1024 * 1024,
+  gb: 1024 * 1024 * 1024,
+}
+
+export function parseSize(value: string | number): number {
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value) || value < 0 || !Number.isInteger(value)) {
+      throw new Error(`[bunderstack] invalid size "${value}"`)
+    }
+    return value
+  }
+
+  const trimmed = value.trim()
+  if (trimmed === '') throw new Error(`[bunderstack] invalid size "${value}"`)
+
+  const match = /^(\d+(?:\.\d+)?)\s*([a-z]*)$/i.exec(trimmed)
+  if (!match) throw new Error(`[bunderstack] invalid size "${value}"`)
+
+  const numStr = match[1]
+  if (numStr === undefined)
+    throw new Error(`[bunderstack] invalid size "${value}"`)
+  const num = parseFloat(numStr)
+  const unit = (match[2] ?? '').toLowerCase()
+
+  if (unit === '') return Math.floor(num)
+
+  const multiplier = SIZE_UNITS[unit]
+  if (multiplier === undefined)
+    throw new Error(`[bunderstack] invalid size "${value}"`)
+
+  return Math.floor(num * multiplier)
+}
+
+// ---------------------------------------------------------------------------
+// Shared backend resolution
+// ---------------------------------------------------------------------------
+
+function resolveSharedBackend(
+  input: StorageConfigInput | undefined,
+  env: Record<string, string | undefined>,
+): ResolvedBackend {
+  if (!input) return { type: 'local', path: './uploads' }
+
+  if ('local' in input && input.local !== undefined) {
+    return {
+      type: 'local',
+      path: input.local === true ? './uploads' : input.local,
+    }
+  }
+
+  if ('s3' in input && input.s3 !== undefined) {
+    const s3Cfg = typeof input.s3 === 'object' ? input.s3 : {}
+    return {
+      type: 's3',
+      bucket: env['S3_BUCKET'] ?? '',
+      region: env['S3_REGION'] ?? 'us-east-1',
+      endpoint: s3Cfg.endpoint ?? env['S3_ENDPOINT'],
+      accessKeyId: env['S3_ACCESS_KEY_ID'] ?? '',
+      secretAccessKey: env['S3_SECRET_ACCESS_KEY'] ?? '',
+    }
+  }
+
+  return { type: 'local', path: './uploads' }
+}
+
+// ---------------------------------------------------------------------------
+// Per-bucket backend resolution
+// ---------------------------------------------------------------------------
+
+function resolveBucketBackend(
+  bucketInput: BucketConfigInput,
+  sharedBackend: ResolvedBackend,
+  env: Record<string, string | undefined>,
+): ResolvedBackend {
+  if ('s3' in bucketInput && bucketInput.s3 !== undefined) {
+    const block = bucketInput.s3
+    return {
+      type: 's3',
+      bucket: block.bucket,
+      region: block.region ?? env['S3_REGION'] ?? 'us-east-1',
+      endpoint: block.endpoint ?? env['S3_ENDPOINT'],
+      accessKeyId: env['S3_ACCESS_KEY_ID'] ?? '',
+      secretAccessKey: env['S3_SECRET_ACCESS_KEY'] ?? '',
+      publicUrl: block.publicUrl,
+    }
+  }
+
+  if ('local' in bucketInput && bucketInput.local !== undefined) {
+    return { type: 'local', path: bucketInput.local }
+  }
+
+  return sharedBackend
+}
+
+// ---------------------------------------------------------------------------
+// Bucket resolution
+// ---------------------------------------------------------------------------
+
+function resolveSingleBucket(
+  name: string,
+  input: BucketConfigInput,
+  sharedBackend: ResolvedBackend,
+  env: Record<string, string | undefined>,
+): ResolvedBucket {
+  const visibility = input.visibility ?? 'private'
+  const backend = resolveBucketBackend(input, sharedBackend, env)
+
+  const defaultGet: OperationRule = visibility === 'public' ? 'public' : 'owner'
+
+  const access: ResolvedBucket['access'] = {
+    create: input.access?.create ?? 'authenticated',
+    get: input.access?.get ?? defaultGet,
+    delete: input.access?.delete ?? 'owner',
+  }
+
+  let upload: ResolvedBucket['upload'] | undefined = undefined
+  if (input.upload !== undefined) {
+    upload = {}
+    if (input.upload.maxSize !== undefined) {
+      upload.maxSizeBytes = parseSize(input.upload.maxSize)
+    }
+    if (input.upload.accept !== undefined) {
+      upload.accept = input.upload.accept
+    }
+  }
+
+  let quota: ResolvedBucket['quota'] | undefined = undefined
+  if (input.quota !== undefined) {
+    quota = {}
+    if (input.quota.perUser !== undefined) {
+      quota.perUserBytes = parseSize(input.quota.perUser)
+    }
+    if (input.quota.perScope !== undefined) {
+      quota.perScopeBytes = parseSize(input.quota.perScope)
+    }
+  }
+
+  return {
+    name,
+    backend,
+    visibility,
+    access,
+    upload,
+    transforms: input.transforms ?? false,
+    scope: input.scope,
+    quota,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// resolveBuckets
+// ---------------------------------------------------------------------------
+
+export function resolveBuckets(
+  input: StorageConfigInput | undefined,
+  env: Record<string, string | undefined> = process.env,
+): ResolvedStorageBuckets {
+  const sharedBackend = resolveSharedBackend(input, env)
+  const bucketsInput = input?.buckets
+
+  const declaredNames = bucketsInput ? Object.keys(bucketsInput) : []
+  const defaultBucketName =
+    input?.defaultBucket ??
+    // A single declared bucket is unambiguous — treat it as the default.
+    (declaredNames.length === 1 ? declaredNames[0]! : 'default')
+
+  const buckets = new Map<string, ResolvedBucket>()
+
+  if (!bucketsInput || Object.keys(bucketsInput).length === 0) {
+    // Synthesize a single default bucket
+    const defaultBucket = resolveSingleBucket(
+      defaultBucketName,
+      {},
+      sharedBackend,
+      env,
+    )
+    buckets.set(defaultBucketName, defaultBucket)
+    return { defaultBucket: defaultBucketName, buckets }
+  }
+
+  // Validate defaultBucket is declared
+  if (!(defaultBucketName in bucketsInput)) {
+    throw new Error(
+      `[bunderstack] defaultBucket "${defaultBucketName}" is not a declared bucket`,
+    )
+  }
+
+  for (const [name, bucketInput] of Object.entries(bucketsInput)) {
+    buckets.set(
+      name,
+      resolveSingleBucket(name, bucketInput, sharedBackend, env),
+    )
+  }
+
+  return { defaultBucket: defaultBucketName, buckets }
+}

package/src/storage/delete.ts

@@ -0,0 +1,27 @@
+// src/storage/delete.ts
+import type { LibSQLDatabase } from 'drizzle-orm/libsql'
+
+import type { StorageAdapter } from './index'
+
+import { deleteFileMetaRow } from './file-meta'
+
+/**
+ * Delete a logical file: its transform-cache derivatives (under
+ * `${fileId}__transforms/`), the original object, and the file-meta row.
+ *
+ * All deletion goes through this helper so the model stays addable to a future
+ * blob/file split (see file-meta.ts header) — never inline `adapter.delete`.
+ */
+export async function deleteFileWithDerivatives(
+  adapter: StorageAdapter,
+  db: LibSQLDatabase<Record<string, unknown>>,
+  fileId: string,
+): Promise<void> {
+  if (adapter.list) {
+    const derivs = await adapter.list(`${fileId}__transforms/`)
+    // Ignore individual derivative-delete errors — orphan sweep is the backstop.
+    await Promise.all(derivs.map((k) => adapter.delete(k).catch(() => {})))
+  }
+  await adapter.delete(fileId)
+  await deleteFileMetaRow(db, fileId)
+}

package/src/storage/file-meta.ts

@@ -0,0 +1,224 @@
+/*
+ * DEFERRED — logical/physical blob/file split
+ *
+ * The current model is 1:1 logical-file = physical-object: one row in
+ * bunderstack_file_meta maps to exactly one object in storage. A future
+ * blob/file split would introduce:
+ *
+ *   bunderstackBlob { key, bucket, size, contentType, refcount, createdAt }
+ *   bunderstackFile { id, blobKey, ownerId, scopeJson, status, filename,
+ *                     createdAt, confirmedAt, deletedAt }
+ *
+ * This would enable:
+ *   - Soft/shadow delete (file.deletedAt + per-bucket retention policy)
+ *   - Transfer ownership/scope (mutate file.ownerId / scopeJson, no byte movement)
+ *   - Duplicate/share to many users or orgs by reference (refcount++) so sharing
+ *     to N users stores bytes once; or by-copy via S3 CopyObject.
+ *
+ * Deletion would decrement refcount; bytes removed only at 0; orphan sweep also
+ * reaps refcount=0 blobs (self-heals crash mid-decrement).
+ *
+ * Deferred because refcount correctness is a real cost vs. current need.
+ *
+ * Two forward-compat invariants keep this addable without breaking the public API:
+ *   1. fileId is opaque — clients never parse it.
+ *   2. All deletion goes through the storage delete helper, never inline.
+ *
+ * See docs/plans/2026-06-28-multi-bucket-storage-design.md §6 for full rationale.
+ */
+
+import type { LibSQLDatabase } from 'drizzle-orm/libsql'
+
+import { eq, and, lt, sql } from 'drizzle-orm'
+
+import type { ScopeMap } from '../access'
+
+import { rowMatchesScope } from '../access'
+import { bunderstackFiles } from '../internal-tables'
+
+export type FileMetaRow = typeof bunderstackFiles.$inferSelect
+
+// ─── CRUD ─────────────────────────────────────────────────────────────────────
+
+export async function insertPendingFile(
+  db: LibSQLDatabase<Record<string, unknown>>,
+  input: {
+    fileId: string
+    bucket: string
+    ownerId: string | null
+    scopeJson: string | null
+    filename: string | null
+    contentType: string | null
+  },
+): Promise<void> {
+  await db.insert(bunderstackFiles).values({
+    fileId: input.fileId,
+    bucket: input.bucket,
+    ownerId: input.ownerId,
+    scopeJson: input.scopeJson,
+    filename: input.filename,
+    contentType: input.contentType,
+    status: 'pending',
+    createdAt: Date.now(),
+    confirmedAt: null,
+    size: null,
+  })
+}
+
+export async function insertReadyFile(
+  db: LibSQLDatabase<Record<string, unknown>>,
+  input: {
+    fileId: string
+    bucket: string
+    ownerId: string | null
+    scopeJson: string | null
+    filename: string | null
+    contentType: string | null
+    size: number | null
+  },
+): Promise<void> {
+  const now = Date.now()
+  await db.insert(bunderstackFiles).values({
+    fileId: input.fileId,
+    bucket: input.bucket,
+    ownerId: input.ownerId,
+    scopeJson: input.scopeJson,
+    filename: input.filename,
+    contentType: input.contentType,
+    size: input.size,
+    status: 'ready',
+    createdAt: now,
+    confirmedAt: now,
+  })
+}
+
+export async function markFileReady(
+  db: LibSQLDatabase<Record<string, unknown>>,
+  fileId: string,
+  patch: { size: number | null; contentType: string | null },
+): Promise<void> {
+  await db
+    .update(bunderstackFiles)
+    .set({
+      status: 'ready',
+      confirmedAt: Date.now(),
+      size: patch.size,
+      contentType: patch.contentType,
+    })
+    .where(eq(bunderstackFiles.fileId, fileId))
+}
+
+export async function getFileMeta(
+  db: LibSQLDatabase<Record<string, unknown>>,
+  fileId: string,
+): Promise<FileMetaRow | null> {
+  const rows = await db
+    .select()
+    .from(bunderstackFiles)
+    .where(eq(bunderstackFiles.fileId, fileId))
+    .limit(1)
+  return rows[0] ?? null
+}
+
+export async function deleteFileMetaRow(
+  db: LibSQLDatabase<Record<string, unknown>>,
+  fileId: string,
+): Promise<void> {
+  await db.delete(bunderstackFiles).where(eq(bunderstackFiles.fileId, fileId))
+}
+
+// ─── Sweep ────────────────────────────────────────────────────────────────────
+
+export async function listStalePendingFiles(
+  db: LibSQLDatabase<Record<string, unknown>>,
+  olderThanMs: number,
+): Promise<FileMetaRow[]> {
+  return db
+    .select()
+    .from(bunderstackFiles)
+    .where(
+      and(
+        eq(bunderstackFiles.status, 'pending'),
+        lt(bunderstackFiles.createdAt, olderThanMs),
+      ),
+    )
+}
+
+// ─── Quota ────────────────────────────────────────────────────────────────────
+
+export async function sumReadySize(
+  db: LibSQLDatabase<Record<string, unknown>>,
+  q: { bucket: string; ownerId?: string; scopeJson?: string },
+): Promise<number> {
+  const conditions = [
+    eq(bunderstackFiles.status, 'ready'),
+    eq(bunderstackFiles.bucket, q.bucket),
+  ]
+  if (q.ownerId !== undefined) {
+    conditions.push(eq(bunderstackFiles.ownerId, q.ownerId))
+  }
+  if (q.scopeJson !== undefined) {
+    conditions.push(eq(bunderstackFiles.scopeJson, q.scopeJson))
+  }
+
+  const rows = await db
+    .select({
+      total: sql<number>`coalesce(sum(${bunderstackFiles.size}), 0)`,
+    })
+    .from(bunderstackFiles)
+    .where(and(...conditions))
+
+  const raw = rows[0]?.total ?? 0
+  return Number(raw)
+}
+
+// ─── Scope helpers ────────────────────────────────────────────────────────────
+
+export function scopeToJson(scope: ScopeMap | undefined | null): string | null {
+  if (scope == null) return null
+  const keys = Object.keys(scope)
+  if (keys.length === 0) return null
+  const sorted = keys.sort()
+  const ordered: Record<string, string | string[]> = {}
+  for (const k of sorted) {
+    const value = scope[k]
+    if (value !== undefined) ordered[k] = value
+  }
+  return JSON.stringify(ordered)
+}
+
+function isScopeMap(value: unknown): value is ScopeMap {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return false
+  }
+  for (const item of Object.values(value)) {
+    if (typeof item === 'string') continue
+    if (Array.isArray(item) && item.every((entry) => typeof entry === 'string'))
+      continue
+    return false
+  }
+  return true
+}
+
+export function parseScopeJson(json: string | null): ScopeMap | null {
+  if (json == null) return null
+  try {
+    const parsed = JSON.parse(json)
+    return isScopeMap(parsed) ? parsed : null
+  } catch {
+    // Corrupt/legacy scope_json should not crash a read; treat as no scope.
+    return null
+  }
+}
+
+export function fileMatchesScope(
+  row: FileMetaRow,
+  requesterScope: ScopeMap | undefined,
+): boolean {
+  if (requesterScope == null || Object.keys(requesterScope).length === 0) {
+    return true
+  }
+  if (row.scopeJson == null) return false
+  const parsed = parseScopeJson(row.scopeJson) ?? {}
+  return rowMatchesScope(parsed, requesterScope)
+}

package/src/storage/index.ts

@@ -0,0 +1,31 @@
+// src/storage/index.ts
+import { LocalStorageAdapter } from './local'
+import { S3StorageAdapter } from './s3'
+
+export type { LocalStorageAdapter, S3StorageAdapter }
+
+export interface PresignPutOptions {
+  contentType?: string
+  expiresIn: number
+}
+export interface PresignGetOptions {
+  expiresIn: number
+}
+
+export interface StorageAdapter {
+  upload(
+    fileId: string,
+    data: Blob | ArrayBuffer,
+    contentType: string,
+  ): Promise<void>
+  get(fileId: string): Promise<Response>
+  delete(fileId: string): Promise<void>
+  exists(fileId: string): Promise<boolean>
+  // Optional — present on S3, absent on local (router uses proxy path for local)
+  presignPut?(key: string, opts: PresignPutOptions): Promise<string>
+  presignGet?(key: string, opts: PresignGetOptions): Promise<string>
+  stat?(key: string): Promise<{ size: number; contentType: string } | null>
+  publicUrlFor?(key: string): string | undefined
+  /** List full object keys under a prefix (used to reap transform derivatives). */
+  list?(prefix: string): Promise<string[]>
+}

package/src/storage/local.ts

@@ -0,0 +1,69 @@
+// src/storage/local.ts
+import { mkdir, readdir } from 'node:fs/promises'
+import { join } from 'node:path'
+
+export class LocalStorageAdapter {
+  private readonly basePath: string
+  constructor(basePath: string) {
+    this.basePath = basePath
+  }
+
+  private filePath(fileId: string) {
+    return join(this.basePath, fileId)
+  }
+
+  async upload(
+    fileId: string,
+    data: Blob | ArrayBuffer,
+    contentType: string,
+  ): Promise<void> {
+    await mkdir(this.basePath, { recursive: true })
+    const bytes = data instanceof Blob ? await data.arrayBuffer() : data
+    await Bun.write(
+      Bun.file(this.filePath(fileId), { type: contentType }),
+      bytes,
+    )
+  }
+
+  async get(fileId: string): Promise<Response> {
+    const file = Bun.file(this.filePath(fileId))
+    if (!(await file.exists()))
+      return new Response('Not found', { status: 404 })
+    return new Response(file, {
+      headers: {
+        'Content-Type': file.type,
+        'Cache-Control': 'public, max-age=31536000',
+      },
+    })
+  }
+
+  async delete(fileId: string): Promise<void> {
+    const file = Bun.file(this.filePath(fileId))
+    if (await file.exists()) await file.unlink()
+  }
+
+  async exists(fileId: string): Promise<boolean> {
+    return Bun.file(this.filePath(fileId)).exists()
+  }
+
+  async stat(
+    key: string,
+  ): Promise<{ size: number; contentType: string } | null> {
+    const file = Bun.file(this.filePath(key))
+    if (!(await file.exists())) return null
+    return { size: file.size, contentType: file.type }
+  }
+
+  async list(prefix: string): Promise<string[]> {
+    const cleanPrefix = prefix.replace(/\/$/, '')
+    const dir = join(this.basePath, cleanPrefix)
+    let entries: string[]
+    try {
+      entries = await readdir(dir)
+    } catch {
+      // Missing dir (or prefix isn't a directory) → no derivatives.
+      return []
+    }
+    return entries.map((name) => `${cleanPrefix}/${name}`)
+  }
+}

package/src/storage/registry.ts

@@ -0,0 +1,40 @@
+// src/storage/registry.ts
+import type {
+  ResolvedBackend,
+  ResolvedBucket,
+  ResolvedStorageBuckets,
+} from './buckets'
+import type { StorageAdapter } from './index'
+
+import { LocalStorageAdapter } from './local'
+import { S3StorageAdapter } from './s3'
+
+export interface BucketStorage {
+  bucket: ResolvedBucket
+  adapter: StorageAdapter
+}
+export type BucketStorageRegistry = Map<string, BucketStorage>
+
+export function createAdapter(backend: ResolvedBackend): StorageAdapter {
+  if (backend.type === 'local') {
+    return new LocalStorageAdapter(backend.path)
+  }
+  return new S3StorageAdapter({
+    bucket: backend.bucket,
+    region: backend.region,
+    accessKeyId: backend.accessKeyId,
+    secretAccessKey: backend.secretAccessKey,
+    endpoint: backend.endpoint,
+    publicUrl: backend.publicUrl,
+  })
+}
+
+export function createBucketStorages(
+  resolved: ResolvedStorageBuckets,
+): BucketStorageRegistry {
+  const registry: BucketStorageRegistry = new Map()
+  for (const [name, bucket] of resolved.buckets) {
+    registry.set(name, { bucket, adapter: createAdapter(bucket.backend) })
+  }
+  return registry
+}