feat(media): support local and s3 upload providers

apps/admin/package.json

@@ -12,6 +12,7 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
+    "@aws-sdk/client-s3": "3.988.0",
     "@cms/content": "workspace:*",
     "@cms/db": "workspace:*",
     "@cms/i18n": "workspace:*",

apps/admin/src/app/api/media/upload/route.ts

@@ -2,7 +2,7 @@ import { hasPermission } from "@cms/content/rbac"
 import { createMediaAsset } from "@cms/db"
 
 import { auth, resolveRoleFromAuthSession } from "@/lib/auth/server"
-import { storeUploadLocally } from "@/lib/media/local-storage"
+import { storeUpload } from "@/lib/media/storage"
 
 export const runtime = "nodejs"
 
@@ -147,7 +147,7 @@ export async function POST(request: Request): Promise<Response> {
   }
 
   try {
-    const stored = await storeUploadLocally({
+    const stored = await storeUpload({
       file: fileEntry,
       mediaType: type,
     })
@@ -170,14 +170,17 @@ export async function POST(request: Request): Promise<Response> {
     return Response.json(
       {
         id: created.id,
+        provider: stored.provider,
         notice: "Media uploaded successfully.",
       },
       { status: 201 },
     )
-  } catch {
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Upload failed. Please try again."
+
     return Response.json(
       {
-        message: "Upload failed. Please try again.",
+        message,
       },
       { status: 500 },
     )

apps/admin/src/app/media/page.tsx

@@ -2,6 +2,7 @@ import { getMediaFoundationSummary, listMediaAssets } from "@cms/db"
 
 import { AdminShell } from "@/components/admin-shell"
 import { MediaUploadForm } from "@/components/media/media-upload-form"
+import { resolveMediaStorageProvider } from "@/lib/media/storage"
 import { requirePermissionForRoute } from "@/lib/route-guards"
 
 export const dynamic = "force-dynamic"
@@ -33,6 +34,7 @@ export default async function MediaManagementPage({
   ])
   const notice = readFirstValue(resolvedSearchParams.notice)
   const error = readFirstValue(resolvedSearchParams.error)
+  const activeStorageProvider = resolveMediaStorageProvider(process.env.CMS_MEDIA_STORAGE_PROVIDER)
 
   return (
     <AdminShell
@@ -78,8 +80,8 @@ export default async function MediaManagementPage({
       <section className="rounded-xl border border-neutral-200 p-6">
         <h2 className="text-xl font-medium">Upload Media Asset</h2>
         <p className="mt-1 text-sm text-neutral-600">
-          Files are currently stored via local adapter. S3/object storage is the next incremental
-          step.
+          Upload storage provider: <strong>{activeStorageProvider}</strong>. You can switch via
+          `CMS_MEDIA_STORAGE_PROVIDER` (`local` or `s3`) until the admin settings toggle lands.
         </p>
         <MediaUploadForm />
       </section>

apps/admin/src/lib/media/local-storage.ts

@@ -1,8 +1,9 @@
-import { randomUUID } from "node:crypto"
 import { mkdir, writeFile } from "node:fs/promises"
 import path from "node:path"
 
-type StoreUploadParams = {
+import { buildMediaStorageKey } from "@/lib/media/storage-key"
+
+type StoreLocalUploadParams = {
   file: File
   mediaType: string
 }
@@ -11,8 +12,6 @@ type StoredUpload = {
   storageKey: string
 }
 
-const FALLBACK_EXTENSION = "bin"
-
 function resolveBaseDirectory(): string {
   const configured = process.env.CMS_MEDIA_LOCAL_STORAGE_DIR?.trim()
 
@@ -23,37 +22,8 @@ function resolveBaseDirectory(): string {
   return path.resolve(process.cwd(), ".data", "media")
 }
 
-function normalizeSegment(value: string): string {
-  return value
-    .toLowerCase()
-    .replace(/[^a-z0-9._-]+/g, "-")
-    .replace(/^-+|-+$/g, "")
-}
-
-function extensionFromFilename(fileName: string): string {
-  const extension = path.extname(fileName).slice(1)
-
-  if (!extension) {
-    return FALLBACK_EXTENSION
-  }
-
-  const normalized = normalizeSegment(extension)
-
-  return normalized.length > 0 ? normalized : FALLBACK_EXTENSION
-}
-
-function buildStorageKey(mediaType: string, fileName: string): string {
-  const now = new Date()
-  const year = String(now.getUTCFullYear())
-  const month = String(now.getUTCMonth() + 1).padStart(2, "0")
-  const normalizedType = normalizeSegment(mediaType) || "generic"
-  const extension = extensionFromFilename(fileName)
-
-  return [normalizedType, year, month, `${randomUUID()}.${extension}`].join("/")
-}
-
-export async function storeUploadLocally(params: StoreUploadParams): Promise<StoredUpload> {
-  const storageKey = buildStorageKey(params.mediaType, params.file.name)
+export async function storeUploadLocally(params: StoreLocalUploadParams): Promise<StoredUpload> {
+  const storageKey = buildMediaStorageKey(params.mediaType, params.file.name)
   const baseDirectory = resolveBaseDirectory()
   const outputPath = path.join(baseDirectory, storageKey)
 

apps/admin/src/lib/media/s3-storage.ts

@@ -0,0 +1,80 @@
+import { PutObjectCommand, S3Client } from "@aws-sdk/client-s3"
+
+import { buildMediaStorageKey } from "@/lib/media/storage-key"
+
+type StoreS3UploadParams = {
+  file: File
+  mediaType: string
+}
+
+type StoredUpload = {
+  storageKey: string
+}
+
+type S3Config = {
+  bucket: string
+  region: string
+  endpoint?: string
+  accessKeyId: string
+  secretAccessKey: string
+  forcePathStyle?: boolean
+}
+
+function parseBoolean(value: string | undefined): boolean {
+  return value?.toLowerCase() === "true"
+}
+
+function resolveS3Config(): S3Config {
+  const bucket = process.env.CMS_MEDIA_S3_BUCKET?.trim()
+  const region = process.env.CMS_MEDIA_S3_REGION?.trim()
+  const accessKeyId = process.env.CMS_MEDIA_S3_ACCESS_KEY_ID?.trim()
+  const secretAccessKey = process.env.CMS_MEDIA_S3_SECRET_ACCESS_KEY?.trim()
+  const endpoint = process.env.CMS_MEDIA_S3_ENDPOINT?.trim() || undefined
+
+  if (!bucket || !region || !accessKeyId || !secretAccessKey) {
+    throw new Error(
+      "S3 storage selected but required env vars are missing: CMS_MEDIA_S3_BUCKET, CMS_MEDIA_S3_REGION, CMS_MEDIA_S3_ACCESS_KEY_ID, CMS_MEDIA_S3_SECRET_ACCESS_KEY",
+    )
+  }
+
+  return {
+    bucket,
+    region,
+    endpoint,
+    accessKeyId,
+    secretAccessKey,
+    forcePathStyle: parseBoolean(process.env.CMS_MEDIA_S3_FORCE_PATH_STYLE),
+  }
+}
+
+function createS3Client(config: S3Config): S3Client {
+  return new S3Client({
+    region: config.region,
+    endpoint: config.endpoint,
+    forcePathStyle: config.forcePathStyle,
+    credentials: {
+      accessKeyId: config.accessKeyId,
+      secretAccessKey: config.secretAccessKey,
+    },
+  })
+}
+
+export async function storeUploadToS3(params: StoreS3UploadParams): Promise<StoredUpload> {
+  const config = resolveS3Config()
+  const client = createS3Client(config)
+  const storageKey = buildMediaStorageKey(params.mediaType, params.file.name)
+  const payload = new Uint8Array(await params.file.arrayBuffer())
+
+  await client.send(
+    new PutObjectCommand({
+      Bucket: config.bucket,
+      Key: storageKey,
+      Body: payload,
+      ContentType: params.file.type || undefined,
+      ContentLength: params.file.size,
+      CacheControl: "public, max-age=31536000, immutable",
+    }),
+  )
+
+  return { storageKey }
+}

apps/admin/src/lib/media/storage-key.ts

@@ -0,0 +1,33 @@
+import { randomUUID } from "node:crypto"
+import path from "node:path"
+
+const FALLBACK_EXTENSION = "bin"
+
+function normalizeSegment(value: string): string {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+}
+
+function extensionFromFilename(fileName: string): string {
+  const extension = path.extname(fileName).slice(1)
+
+  if (!extension) {
+    return FALLBACK_EXTENSION
+  }
+
+  const normalized = normalizeSegment(extension)
+
+  return normalized.length > 0 ? normalized : FALLBACK_EXTENSION
+}
+
+export function buildMediaStorageKey(mediaType: string, fileName: string): string {
+  const now = new Date()
+  const year = String(now.getUTCFullYear())
+  const month = String(now.getUTCMonth() + 1).padStart(2, "0")
+  const normalizedType = normalizeSegment(mediaType) || "generic"
+  const extension = extensionFromFilename(fileName)
+
+  return [normalizedType, year, month, `${randomUUID()}.${extension}`].join("/")
+}

apps/admin/src/lib/media/storage.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from "vitest"
+
+import { resolveMediaStorageProvider } from "@/lib/media/storage"
+
+describe("resolveMediaStorageProvider", () => {
+  it("defaults to local when unset", () => {
+    expect(resolveMediaStorageProvider(undefined)).toBe("local")
+  })
+
+  it("resolves s3", () => {
+    expect(resolveMediaStorageProvider("s3")).toBe("s3")
+    expect(resolveMediaStorageProvider("S3")).toBe("s3")
+  })
+
+  it("falls back to local for unknown values", () => {
+    expect(resolveMediaStorageProvider("foo")).toBe("local")
+  })
+})

apps/admin/src/lib/media/storage.ts

@@ -0,0 +1,41 @@
+import { storeUploadLocally } from "@/lib/media/local-storage"
+import { storeUploadToS3 } from "@/lib/media/s3-storage"
+
+export type MediaStorageProvider = "local" | "s3"
+
+type StoreUploadParams = {
+  file: File
+  mediaType: string
+}
+
+type StoredUpload = {
+  storageKey: string
+  provider: MediaStorageProvider
+}
+
+export function resolveMediaStorageProvider(raw: string | undefined): MediaStorageProvider {
+  if (raw?.toLowerCase() === "s3") {
+    return "s3"
+  }
+
+  return "local"
+}
+
+export async function storeUpload(params: StoreUploadParams): Promise<StoredUpload> {
+  const provider = resolveMediaStorageProvider(process.env.CMS_MEDIA_STORAGE_PROVIDER)
+
+  if (provider === "s3") {
+    const stored = await storeUploadToS3(params)
+    return {
+      ...stored,
+      provider,
+    }
+  }
+
+  const stored = await storeUploadLocally(params)
+
+  return {
+    ...stored,
+    provider,
+  }
+}