@omg-dev/server 0.4.24

package/src/storage.ts

@@ -0,0 +1,384 @@
+// Object storage for vibes apps — mode-aware just like triggers.
+//
+// User-facing API:
+//   import { storage } from "@omg-dev/server"
+//
+//   // Server route handlers:
+//   const { url, key } = await storage.uploadUrl({ key: "avatar.png", contentType: "image/png" })
+//   const url2 = await storage.downloadUrl("avatar.png")
+//   const items = await storage.list({ prefix: "" })
+//   await storage.delete("avatar.png")
+//
+// Runtime modes:
+//   - VIBES_MODE=prod (default in deployed bundles): every call POSTs to the
+//     in-VM agent's /_storage/* endpoints, which forward to the orchestrator.
+//     The orchestrator mints presigned PUT/GET URLs against Tigris and the
+//     browser uploads/downloads direct.
+//   - VIBES_MODE=dev (set by the vite-plugin during `bun dev`): files are
+//     stored on the local filesystem under .vibes/storage/<scope>/<...>/<key>.
+//     `uploadUrl()` returns a local Vite-server URL that handles the PUT;
+//     `downloadUrl()` returns the same path for GET. No Tigris, no orchestrator.
+//
+// Auth scoping:
+//   - scope: "user" (default) — the file lives under the authed user's
+//     prefix. `ctx.userId` (from @omg-dev/auth middleware) is used as the
+//     userId. If the request has no authed user, throws.
+//   - scope: "app" — shared across all users of the app. Useful for things
+//     like a logo or static assets the app developer wants to manage at
+//     runtime. (App-level write authorization is the caller's responsibility.)
+
+import path from "node:path"
+import fs from "node:fs"
+import crypto from "node:crypto"
+import { ctxStore, ctx } from "./ctx.ts"
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export type StorageScope = "user" | "app"
+
+export interface UploadUrlOptions {
+  /** Object key. Must match /^[a-zA-Z0-9._\-\/]{1,256}$/. Forward slashes are OK as folder separators. */
+  key: string
+  /** Content-Type the browser will PUT. Baked into the presigned signature. Defaults to "application/octet-stream". */
+  contentType?: string
+  /** "user" (default) or "app". */
+  scope?: StorageScope
+  /** Explicit userId. Defaults to ctx.userId for scope="user". */
+  userId?: string
+}
+
+export interface DownloadUrlOptions {
+  scope?: StorageScope
+  userId?: string
+}
+
+export interface ListOptions {
+  /** Optional sub-prefix within the (scope, userId) namespace. */
+  prefix?: string
+  scope?: StorageScope
+  userId?: string
+  /** Max items to return; default 200, cap 1000. */
+  limit?: number
+}
+
+export interface PresignedUploadResult {
+  url: string
+  method: "PUT"
+  key: string
+  expiresAt: string
+  /** Max bytes the orchestrator signed for; the browser must not exceed it. */
+  maxBytes: number
+}
+
+export interface PresignedDownloadResult {
+  url: string
+  method: "GET"
+  key: string
+  expiresAt: string
+}
+
+export interface StorageItem {
+  /** Full Tigris key (or local FS path in dev). Treat as opaque. */
+  key: string
+  /** User-facing relative path within the (scope, user) bucket. */
+  relPath: string
+  size: number
+  lastModified: string
+  contentType?: string
+}
+
+// Handler decorators (build-time markers). The vite-plugin scanner detects
+// `storage.onUpload(...)` / `storage.onDelete(...)` and emits entries into
+// `.vibes/triggers.json` with kind "storage:upload" / "storage:delete". The
+// runtime function just returns the handler unchanged so unit tests can
+// import + invoke directly.
+export type StorageEvent =
+  | { kind: "upload"; key: string; size: number; contentType: string; userId: string | null }
+  | { kind: "delete"; key: string; userId: string | null }
+export type StorageEventHandler = (ctx: import("./ctx.ts").VibesCtx, evt: StorageEvent) => unknown | Promise<unknown>
+
+function onUpload(handler: StorageEventHandler): StorageEventHandler {
+  return handler
+}
+function onDelete(handler: StorageEventHandler): StorageEventHandler {
+  return handler
+}
+
+// ── Mode detection (mirrors triggers.ts) ─────────────────────────────────────
+
+let _vibesMode: "dev" | "prod" | null = null
+function vibesMode(): "dev" | "prod" {
+  if (_vibesMode) return _vibesMode
+  const env = (typeof process !== "undefined" ? process.env?.VIBES_MODE : undefined) ?? ""
+  _vibesMode = env === "dev" ? "dev" : "prod"
+  return _vibesMode
+}
+
+// ── Common validators ───────────────────────────────────────────────────────
+
+const KEY_RE = /^[a-zA-Z0-9._\-/]{1,256}$/
+function validateKey(key: string): void {
+  if (!KEY_RE.test(key)) {
+    throw new Error(`storage: invalid key ${JSON.stringify(key)}`)
+  }
+  if (key.includes("..") || key.startsWith("/") || key.includes("//")) {
+    throw new Error(`storage: key cannot contain traversal segments or empty parts`)
+  }
+}
+
+function resolveScope(scope: StorageScope | undefined, userId: string | undefined): { scope: StorageScope; userId: string } {
+  const s: StorageScope = scope ?? "user"
+  if (s === "user") {
+    const resolved = userId ?? ctx.userId ?? ""
+    if (!resolved) {
+      throw new Error(
+        `storage: scope="user" requires an authed user — pass storage.upload(...) from a route that's behind VibesAuthGuard or set scope:"app" explicitly.`,
+      )
+    }
+    return { scope: "user", userId: resolved }
+  }
+  return { scope: "app", userId: "" }
+}
+
+// ── Public storage API ───────────────────────────────────────────────────────
+
+async function uploadUrl(opts: UploadUrlOptions): Promise<PresignedUploadResult> {
+  validateKey(opts.key)
+  const { scope, userId } = resolveScope(opts.scope, opts.userId)
+  if (vibesMode() === "dev") {
+    return devUploadUrl(opts.key, scope, userId, opts.contentType)
+  }
+  return prodPresign("put", opts.key, scope, userId, opts.contentType)
+}
+
+async function downloadUrl(key: string, opts: DownloadUrlOptions = {}): Promise<PresignedDownloadResult> {
+  validateKey(key)
+  const { scope, userId } = resolveScope(opts.scope, opts.userId)
+  if (vibesMode() === "dev") {
+    return devDownloadUrl(key, scope, userId)
+  }
+  const res = await prodPresign("get", key, scope, userId)
+  return { url: res.url, method: "GET", key: res.key, expiresAt: res.expiresAt }
+}
+
+async function list(opts: ListOptions = {}): Promise<StorageItem[]> {
+  const { scope, userId } = resolveScope(opts.scope, opts.userId)
+  if (vibesMode() === "dev") {
+    return devList(scope, userId, opts.prefix ?? "")
+  }
+  return prodList(scope, userId, opts.prefix ?? "", opts.limit ?? 200)
+}
+
+async function del(
+  key: string,
+  opts: { scope?: StorageScope; userId?: string } = {},
+): Promise<void> {
+  validateKey(key)
+  const { scope, userId } = resolveScope(opts.scope, opts.userId)
+  if (vibesMode() === "dev") {
+    return devDelete(key, scope, userId)
+  }
+  return prodDelete(key, scope, userId)
+}
+
+export const storage = {
+  uploadUrl,
+  downloadUrl,
+  list,
+  delete: del,
+  onUpload,
+  onDelete,
+}
+
+// ── prod-mode: HTTP to the agent ─────────────────────────────────────────────
+
+const AGENT_BASE = "http://localhost:8080"
+
+async function prodPresign(
+  action: "put" | "get",
+  key: string,
+  scope: StorageScope,
+  userId: string,
+  contentType?: string,
+): Promise<PresignedUploadResult> {
+  const res = await fetch(`${AGENT_BASE}/_storage/presign`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ action, key, scope, userId, contentType }),
+  })
+  if (!res.ok) {
+    const text = await res.text().catch(() => "")
+    throw new Error(`storage.${action === "put" ? "uploadUrl" : "downloadUrl"}(${JSON.stringify(key)}) agent ${res.status}: ${text.slice(0, 200)}`)
+  }
+  const body = (await res.json()) as { url: string; expiresAt: string; key: string; method: string; maxBytes?: number }
+  return {
+    url: body.url,
+    method: action === "put" ? "PUT" : ("GET" as unknown as "PUT"),
+    key: body.key,
+    expiresAt: body.expiresAt,
+    maxBytes: body.maxBytes ?? 25 * 1024 * 1024,
+  }
+}
+
+async function prodList(scope: StorageScope, userId: string, prefix: string, limit: number): Promise<StorageItem[]> {
+  const res = await fetch(`${AGENT_BASE}/_storage/list`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ scope, userId, prefix, limit }),
+  })
+  if (!res.ok) {
+    const text = await res.text().catch(() => "")
+    throw new Error(`storage.list agent ${res.status}: ${text.slice(0, 200)}`)
+  }
+  const body = (await res.json()) as Array<{
+    key: string
+    relPath: string
+    size: number
+    lastModified: string
+    contentType?: string
+  }>
+  return body.map(o => ({
+    key: o.key,
+    relPath: o.relPath,
+    size: o.size,
+    lastModified: o.lastModified,
+    contentType: o.contentType,
+  }))
+}
+
+async function prodDelete(key: string, scope: StorageScope, userId: string): Promise<void> {
+  const res = await fetch(`${AGENT_BASE}/_storage/delete`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ key, scope, userId }),
+  })
+  if (!res.ok && res.status !== 204) {
+    const text = await res.text().catch(() => "")
+    throw new Error(`storage.delete agent ${res.status}: ${text.slice(0, 200)}`)
+  }
+}
+
+// ── dev-mode: local FS shim ──────────────────────────────────────────────────
+//
+// Dev storage lives under .vibes/storage/ inside the project root. The
+// vite-plugin registers a middleware at /_vibes_storage that serves GETs
+// and accepts PUTs against this directory — so uploadUrl/downloadUrl just
+// return that same URL with a signed token in the query string.
+
+function devRoot(): string {
+  // Resolve relative to the cwd of the dev server (always the project root
+  // for `bun dev` in a vibes app). Cached lazily.
+  return path.resolve(process.cwd(), ".vibes", "storage")
+}
+
+function devPath(scope: StorageScope, userId: string, key: string): string {
+  const base = scope === "user" ? path.join("users", userId) : "app"
+  return path.join(devRoot(), base, key)
+}
+
+function devRelative(scope: StorageScope, userId: string, key: string): string {
+  return scope === "user" ? `users/${userId}/${key}` : `app/${key}`
+}
+
+const DEV_TOKEN_SECRET = process.env.VIBES_DEV_STORAGE_SECRET ?? "vibes-dev-storage"
+function devSignToken(rel: string, action: "put" | "get", expiresAt: number): string {
+  const h = crypto.createHmac("sha256", DEV_TOKEN_SECRET)
+  h.update(`${rel}|${action}|${expiresAt}`)
+  return `${expiresAt}.${h.digest("hex").slice(0, 16)}`
+}
+
+/**
+ * Verify a dev-storage signed token. Exported so the vite-plugin middleware
+ * can call into it without duplicating crypto. (Internal use; not part of the
+ * @omg-dev/server public API.)
+ */
+export function _verifyDevStorageToken(rel: string, action: "put" | "get", token: string): boolean {
+  const [expStr, sig] = token.split(".")
+  if (!expStr || !sig) return false
+  const exp = Number(expStr)
+  if (!Number.isFinite(exp) || exp < Date.now()) return false
+  return devSignToken(rel, action, exp).split(".")[1] === sig
+}
+
+/**
+ * Write a file into the dev storage tree under the given namespace. Exported
+ * so the vite-plugin middleware can perform the PUT after verifying the
+ * token. Creates parent directories as needed.
+ */
+export function _devStorageWrite(scope: StorageScope, userId: string, key: string, data: Buffer | Uint8Array): void {
+  const dst = devPath(scope, userId, key)
+  fs.mkdirSync(path.dirname(dst), { recursive: true })
+  fs.writeFileSync(dst, data)
+}
+
+/**
+ * Resolve a dev storage file to its absolute filesystem path so the plugin
+ * middleware can stream the GET. Returns null if the file does not exist.
+ */
+export function _devStorageRead(scope: StorageScope, userId: string, key: string): string | null {
+  const src = devPath(scope, userId, key)
+  if (!fs.existsSync(src)) return null
+  return src
+}
+
+function devUploadUrl(key: string, scope: StorageScope, userId: string, contentType?: string): PresignedUploadResult {
+  const rel = devRelative(scope, userId, key)
+  const expiresAt = Date.now() + 5 * 60 * 1000
+  const token = devSignToken(rel, "put", expiresAt)
+  return {
+    url: `/_vibes_storage/${rel}?t=${token}${contentType ? `&ct=${encodeURIComponent(contentType)}` : ""}`,
+    method: "PUT",
+    key: rel,
+    expiresAt: new Date(expiresAt).toISOString(),
+    maxBytes: 25 * 1024 * 1024,
+  }
+}
+
+function devDownloadUrl(key: string, scope: StorageScope, userId: string): PresignedDownloadResult {
+  const rel = devRelative(scope, userId, key)
+  const expiresAt = Date.now() + 60 * 60 * 1000
+  const token = devSignToken(rel, "get", expiresAt)
+  return {
+    url: `/_vibes_storage/${rel}?t=${token}`,
+    method: "GET",
+    key: rel,
+    expiresAt: new Date(expiresAt).toISOString(),
+  }
+}
+
+function devList(scope: StorageScope, userId: string, prefix: string): StorageItem[] {
+  const root = devPath(scope, userId, prefix || ".")
+  if (!fs.existsSync(root)) return []
+  const out: StorageItem[] = []
+  function walk(dir: string): void {
+    for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, ent.name)
+      if (ent.isDirectory()) {
+        walk(full)
+        continue
+      }
+      if (!ent.isFile()) continue
+      const st = fs.statSync(full)
+      const base = devPath(scope, userId, "")
+      const rel = path.relative(base, full).replaceAll(path.sep, "/")
+      out.push({
+        key: rel,
+        relPath: rel,
+        size: st.size,
+        lastModified: st.mtime.toISOString(),
+      })
+    }
+  }
+  walk(root)
+  return out
+}
+
+function devDelete(key: string, scope: StorageScope, userId: string): void {
+  const src = devPath(scope, userId, key)
+  if (fs.existsSync(src)) {
+    fs.rmSync(src)
+  }
+}
+
+// Silence unused-import warning from `ctxStore` when only `ctx` is referenced.
+void ctxStore