feat(media): add admin media CRUD preview and storage cleanup

2026-02-12 19:15:26 +01:00
parent 3e4f0b6c75
commit 7d9bc9dca9
11 changed files with 699 additions and 10 deletions
--- a/TODO.md
+++ b/TODO.md
@@ -273,6 +273,7 @@ This file is the single source of truth for roadmap and delivery progress.
 - [2026-02-12] MVP1 media upload pipeline started: admin `/api/media/upload` accepts metadata + file upload with permission checks, stores files via local adapter (`.data/media`), and persists upload metadata to `MediaAsset`.
 - [2026-02-12] Upload storage is now provider-based (`local` + `s3`) via `CMS_MEDIA_STORAGE_PROVIDER`; admin-side GUI toggle remains a later MVP item.
 - [2026-02-12] Media storage keys now use asset-centric layout (`tenant/<id>/asset/<assetId>/<fileRole>/<assetId>__<variant>.<ext>`) with DB-managed media taxonomy.
+- [2026-02-12] Admin media CRUD now includes list-to-detail flow (`/media/:id`) with metadata edit and delete actions.

 ## How We Use This File

--- a/apps/admin/src/app/api/media/file/[id]/route.ts
+++ b/apps/admin/src/app/api/media/file/[id]/route.ts
@@ -0,0 +1,120 @@
+import { readFile } from "node:fs/promises"
+import path from "node:path"
+import { GetObjectCommand } from "@aws-sdk/client-s3"
+import { hasPermission } from "@cms/content/rbac"
+import { getMediaAssetById } from "@cms/db"
+
+import { auth, resolveRoleFromAuthSession } from "@/lib/auth/server"
+import { resolveLocalMediaBaseDirectory } from "@/lib/media/local-storage"
+import { createS3Client, resolveS3Config } from "@/lib/media/s3-storage"
+import { resolveMediaStorageProvider } from "@/lib/media/storage"
+
+export const runtime = "nodejs"
+
+type RouteContext = {
+  params: Promise<{ id: string }>
+}
+
+async function readFromLocalStorage(storageKey: string): Promise<Uint8Array> {
+  const baseDirectory = resolveLocalMediaBaseDirectory()
+  const outputPath = path.join(baseDirectory, storageKey)
+
+  return readFile(outputPath)
+}
+
+async function readFromS3Storage(storageKey: string): Promise<Uint8Array> {
+  const config = resolveS3Config()
+  const client = createS3Client(config)
+
+  const response = await client.send(
+    new GetObjectCommand({
+      Bucket: config.bucket,
+      Key: storageKey,
+    }),
+  )
+
+  if (!response.Body) {
+    throw new Error("S3 object body is empty")
+  }
+
+  return response.Body.transformToByteArray()
+}
+
+function toBody(data: Uint8Array): BodyInit {
+  const bytes = new Uint8Array(data.byteLength)
+  bytes.set(data)
+  return bytes
+}
+
+export async function GET(request: Request, context: RouteContext): Promise<Response> {
+  const session = await auth.api
+    .getSession({
+      headers: request.headers,
+    })
+    .catch(() => null)
+  const role = resolveRoleFromAuthSession(session)
+
+  if (!role) {
+    return Response.json(
+      {
+        message: "Unauthorized",
+      },
+      { status: 401 },
+    )
+  }
+
+  if (!hasPermission(role, "media:read", "team")) {
+    return Response.json(
+      {
+        message: "Missing permission: media:read",
+      },
+      { status: 403 },
+    )
+  }
+
+  const { id } = await context.params
+  const asset = await getMediaAssetById(id)
+
+  if (!asset || !asset.storageKey) {
+    return Response.json(
+      {
+        message: "Media file not found",
+      },
+      { status: 404 },
+    )
+  }
+
+  const preferred = resolveMediaStorageProvider(process.env.CMS_MEDIA_STORAGE_PROVIDER)
+  const reads =
+    preferred === "s3"
+      ? [
+          () => readFromS3Storage(asset.storageKey as string),
+          () => readFromLocalStorage(asset.storageKey as string),
+        ]
+      : [
+          () => readFromLocalStorage(asset.storageKey as string),
+          () => readFromS3Storage(asset.storageKey as string),
+        ]
+
+  for (const read of reads) {
+    try {
+      const data = await read()
+      return new Response(toBody(data), {
+        status: 200,
+        headers: {
+          "content-type": asset.mimeType || "application/octet-stream",
+          "cache-control": "private, max-age=0, no-store",
+        },
+      })
+    } catch {
+      // Try next backend.
+    }
+  }
+
+  return Response.json(
+    {
+      message: "Unable to read media file from configured storage backends",
+    },
+    { status: 404 },
+  )
+}
--- a/apps/admin/src/app/media/[id]/page.tsx
+++ b/apps/admin/src/app/media/[id]/page.tsx
@@ -0,0 +1,423 @@
+import { deleteMediaAsset, getMediaAssetById, updateMediaAsset } from "@cms/db"
+import { Button } from "@cms/ui/button"
+import Link from "next/link"
+import { redirect } from "next/navigation"
+
+import { AdminShell } from "@/components/admin-shell"
+import { deleteStoredMediaObject } from "@/lib/media/storage"
+import { requirePermissionForRoute } from "@/lib/route-guards"
+
+export const dynamic = "force-dynamic"
+
+type SearchParamsInput = Record<string, string | string[] | undefined>
+
+type PageProps = {
+  params: Promise<{ id: string }>
+  searchParams: Promise<SearchParamsInput>
+}
+
+function readFirstValue(value: string | string[] | undefined): string | null {
+  if (Array.isArray(value)) {
+    return value[0] ?? null
+  }
+
+  return value ?? null
+}
+
+function readInputString(formData: FormData, field: string): string {
+  const value = formData.get(field)
+  return typeof value === "string" ? value.trim() : ""
+}
+
+function readNullableString(formData: FormData, field: string): string | null {
+  const value = readInputString(formData, field)
+  return value.length > 0 ? value : null
+}
+
+function readNullableInt(formData: FormData, field: string): number | null {
+  const value = readInputString(formData, field)
+
+  if (!value) {
+    return null
+  }
+
+  const parsed = Number.parseInt(value, 10)
+
+  if (!Number.isFinite(parsed)) {
+    return null
+  }
+
+  return parsed
+}
+
+function readTags(formData: FormData): string[] {
+  const raw = readInputString(formData, "tags")
+
+  if (!raw) {
+    return []
+  }
+
+  return raw
+    .split(",")
+    .map((item) => item.trim())
+    .filter((item) => item.length > 0)
+}
+
+function redirectWithState(mediaAssetId: string, params: { notice?: string; error?: string }) {
+  const query = new URLSearchParams()
+
+  if (params.notice) {
+    query.set("notice", params.notice)
+  }
+
+  if (params.error) {
+    query.set("error", params.error)
+  }
+
+  const value = query.toString()
+  redirect(value ? `/media/${mediaAssetId}?${value}` : `/media/${mediaAssetId}`)
+}
+
+function toLocalDateTimeInputValue(date: Date): string {
+  const offset = date.getTimezoneOffset() * 60_000
+  return new Date(date.getTime() - offset).toISOString().slice(0, 16)
+}
+
+export default async function MediaAssetEditorPage({ params, searchParams }: PageProps) {
+  const role = await requirePermissionForRoute({
+    nextPath: "/media",
+    permission: "media:read",
+    scope: "team",
+  })
+  const resolvedParams = await params
+  const mediaAssetId = resolvedParams.id
+
+  const [resolvedSearchParams, asset] = await Promise.all([
+    searchParams,
+    getMediaAssetById(mediaAssetId),
+  ])
+
+  if (!asset) {
+    redirect("/media?error=Media+asset+not+found")
+  }
+  const mediaAsset = asset
+
+  const notice = readFirstValue(resolvedSearchParams.notice)
+  const error = readFirstValue(resolvedSearchParams.error)
+  const previewUrl = mediaAsset.storageKey ? `/api/media/file/${mediaAsset.id}` : null
+  const isImage = Boolean(mediaAsset.mimeType?.startsWith("image/"))
+  const isVideo = Boolean(mediaAsset.mimeType?.startsWith("video/"))
+
+  async function updateMediaAssetAction(formData: FormData) {
+    "use server"
+
+    await requirePermissionForRoute({
+      nextPath: "/media",
+      permission: "media:write",
+      scope: "team",
+    })
+
+    try {
+      await updateMediaAsset({
+        id: mediaAssetId,
+        title: readInputString(formData, "title"),
+        type: readInputString(formData, "type"),
+        description: readNullableString(formData, "description"),
+        altText: readNullableString(formData, "altText"),
+        source: readNullableString(formData, "source"),
+        copyright: readNullableString(formData, "copyright"),
+        author: readNullableString(formData, "author"),
+        tags: readTags(formData),
+        mimeType: readNullableString(formData, "mimeType"),
+        width: readNullableInt(formData, "width"),
+        height: readNullableInt(formData, "height"),
+        sizeBytes: readNullableInt(formData, "sizeBytes"),
+        isPublished: readInputString(formData, "isPublished") === "true",
+      })
+    } catch {
+      redirectWithState(mediaAssetId, {
+        error: "Failed to update media asset. Validate values and try again.",
+      })
+    }
+
+    redirectWithState(mediaAssetId, { notice: "Media asset updated." })
+  }
+
+  async function deleteMediaAssetAction() {
+    "use server"
+
+    await requirePermissionForRoute({
+      nextPath: "/media",
+      permission: "media:write",
+      scope: "team",
+    })
+
+    try {
+      if (mediaAsset.storageKey) {
+        await deleteStoredMediaObject(mediaAsset.storageKey)
+      }
+
+      await deleteMediaAsset(mediaAssetId)
+    } catch {
+      redirectWithState(mediaAssetId, {
+        error:
+          "Failed to delete media asset and file from storage. Check storage config and links.",
+      })
+    }
+
+    redirect("/media?notice=Media+asset+deleted")
+  }
+
+  return (
+    <AdminShell
+      role={role}
+      activePath="/media"
+      badge="Admin App"
+      title="Media Asset"
+      description="View, edit, and delete uploaded media metadata."
+    >
+      {notice ? (
+        <section className="rounded-xl border border-emerald-300 bg-emerald-50 px-4 py-3 text-sm text-emerald-800">
+          {notice}
+        </section>
+      ) : null}
+
+      {error ? (
+        <section className="rounded-xl border border-red-300 bg-red-50 px-4 py-3 text-sm text-red-800">
+          {error}
+        </section>
+      ) : null}
+
+      <section className="rounded-xl border border-neutral-200 p-6">
+        <h3 className="text-lg font-medium">Preview</h3>
+        <p className="mt-1 text-sm text-neutral-600">
+          {mediaAsset.mimeType ? `MIME: ${mediaAsset.mimeType}` : "MIME: unknown"}
+        </p>
+
+        <div className="mt-4 rounded-lg border border-neutral-200 bg-neutral-50 p-3">
+          {!previewUrl ? (
+            <p className="text-sm text-neutral-600">
+              No stored file is linked for this media asset.
+            </p>
+          ) : isImage ? (
+            // biome-ignore lint/performance/noImgElement: Auth-protected media preview requires direct browser request with session cookies.
+            <img
+              src={previewUrl}
+              alt={mediaAsset.altText || mediaAsset.title}
+              className="max-h-[26rem] w-auto rounded border border-neutral-200 bg-white"
+            />
+          ) : isVideo ? (
+            // biome-ignore lint/a11y/useMediaCaption: Preview uses source assets without guaranteed caption tracks.
+            <video
+              src={previewUrl}
+              controls
+              preload="metadata"
+              className="max-h-[26rem] w-full rounded border border-neutral-200 bg-black"
+            />
+          ) : (
+            <p className="text-sm text-neutral-700">
+              Inline preview is not available for this media type.
+            </p>
+          )}
+        </div>
+
+        {previewUrl ? (
+          <a
+            href={previewUrl}
+            target="_blank"
+            rel="noreferrer"
+            className="mt-3 inline-block text-sm text-neutral-700 underline underline-offset-2"
+          >
+            Open raw media file
+          </a>
+        ) : null}
+      </section>
+
+      <section className="rounded-xl border border-neutral-200 p-6">
+        <div className="flex flex-wrap items-center justify-between gap-3">
+          <div>
+            <h2 className="text-xl font-medium">{mediaAsset.title}</h2>
+            <p className="mt-1 text-xs text-neutral-600">ID: {mediaAsset.id}</p>
+          </div>
+          <Link href="/media" className="text-sm text-neutral-700 underline underline-offset-2">
+            Back to media list
+          </Link>
+        </div>
+
+        <form action={updateMediaAssetAction} className="mt-6 space-y-3">
+          <div className="grid gap-3 md:grid-cols-2">
+            <label className="space-y-1">
+              <span className="text-xs text-neutral-600">Title</span>
+              <input
+                name="title"
+                defaultValue={mediaAsset.title}
+                required
+                className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
+              />
+            </label>
+            <label className="space-y-1">
+              <span className="text-xs text-neutral-600">Type</span>
+              <select
+                name="type"
+                defaultValue={mediaAsset.type}
+                className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
+              >
+                <option value="artwork">artwork</option>
+                <option value="banner">banner</option>
+                <option value="promotion">promotion</option>
+                <option value="video">video</option>
+                <option value="gif">gif</option>
+                <option value="generic">generic</option>
+              </select>
+            </label>
+          </div>
+
+          <label className="space-y-1">
+            <span className="text-xs text-neutral-600">Description</span>
+            <textarea
+              name="description"
+              rows={3}
+              defaultValue={mediaAsset.description ?? ""}
+              className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
+            />
+          </label>
+
+          <div className="grid gap-3 md:grid-cols-2">
+            <label className="space-y-1">
+              <span className="text-xs text-neutral-600">Alt text</span>
+              <input
+                name="altText"
+                defaultValue={mediaAsset.altText ?? ""}
+                className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
+              />
+            </label>
+            <label className="space-y-1">
+              <span className="text-xs text-neutral-600">Author</span>
+              <input
+                name="author"
+                defaultValue={mediaAsset.author ?? ""}
+                className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
+              />
+            </label>
+          </div>
+
+          <div className="grid gap-3 md:grid-cols-2">
+            <label className="space-y-1">
+              <span className="text-xs text-neutral-600">Source</span>
+              <input
+                name="source"
+                defaultValue={mediaAsset.source ?? ""}
+                className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
+              />
+            </label>
+            <label className="space-y-1">
+              <span className="text-xs text-neutral-600">Copyright</span>
+              <input
+                name="copyright"
+                defaultValue={mediaAsset.copyright ?? ""}
+                className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
+              />
+            </label>
+          </div>
+
+          <div className="grid gap-3 md:grid-cols-3">
+            <label className="space-y-1">
+              <span className="text-xs text-neutral-600">MIME type</span>
+              <input
+                name="mimeType"
+                defaultValue={mediaAsset.mimeType ?? ""}
+                className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
+              />
+            </label>
+            <label className="space-y-1">
+              <span className="text-xs text-neutral-600">Width</span>
+              <input
+                name="width"
+                type="number"
+                min={1}
+                defaultValue={mediaAsset.width ?? ""}
+                className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
+              />
+            </label>
+            <label className="space-y-1">
+              <span className="text-xs text-neutral-600">Height</span>
+              <input
+                name="height"
+                type="number"
+                min={1}
+                defaultValue={mediaAsset.height ?? ""}
+                className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
+              />
+            </label>
+          </div>
+
+          <div className="grid gap-3 md:grid-cols-2">
+            <label className="space-y-1">
+              <span className="text-xs text-neutral-600">Size (bytes)</span>
+              <input
+                name="sizeBytes"
+                type="number"
+                min={0}
+                defaultValue={mediaAsset.sizeBytes ?? ""}
+                className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
+              />
+            </label>
+            <label className="space-y-1">
+              <span className="text-xs text-neutral-600">Tags (comma-separated)</span>
+              <input
+                name="tags"
+                defaultValue={mediaAsset.tags.join(", ")}
+                className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
+              />
+            </label>
+          </div>
+
+          <label className="inline-flex items-center gap-2 text-sm text-neutral-700">
+            <input
+              type="checkbox"
+              name="isPublished"
+              value="true"
+              defaultChecked={mediaAsset.isPublished}
+              className="size-4"
+            />
+            Published
+          </label>
+
+          <div className="grid gap-3 md:grid-cols-2">
+            <label className="space-y-1">
+              <span className="text-xs text-neutral-600">Storage key</span>
+              <input
+                value={mediaAsset.storageKey ?? "-"}
+                readOnly
+                className="w-full rounded border border-neutral-200 bg-neutral-50 px-3 py-2 text-xs text-neutral-600"
+              />
+            </label>
+            <label className="space-y-1">
+              <span className="text-xs text-neutral-600">Last updated</span>
+              <input
+                value={toLocalDateTimeInputValue(mediaAsset.updatedAt)}
+                readOnly
+                className="w-full rounded border border-neutral-200 bg-neutral-50 px-3 py-2 text-xs text-neutral-600"
+              />
+            </label>
+          </div>
+
+          <Button type="submit">Save changes</Button>
+        </form>
+      </section>
+
+      <section className="rounded-xl border border-red-300 bg-red-50 p-6">
+        <h3 className="text-lg font-medium text-red-800">Danger Zone</h3>
+        <p className="mt-1 text-sm text-red-700">
+          Deleting this media asset is permanent. Any linked artwork rendition references will also
+          be removed.
+        </p>
+        <form action={deleteMediaAssetAction} className="mt-4">
+          <Button type="submit" variant="secondary" className="border border-red-300 text-red-800">
+            Delete media asset
+          </Button>
+        </form>
+      </section>
+    </AdminShell>
+  )
+}
--- a/apps/admin/src/app/media/page.tsx
+++ b/apps/admin/src/app/media/page.tsx
@@ -1,4 +1,5 @@
 import { getMediaFoundationSummary, listMediaAssets } from "@cms/db"
+import Link from "next/link"

 import { AdminShell } from "@/components/admin-shell"
 import { FlashQueryCleanup } from "@/components/media/flash-query-cleanup"
@@ -123,12 +124,13 @@ export default async function MediaManagementPage({
                <th className="py-2 pr-4">Size</th>
                <th className="py-2 pr-4">Published</th>
                <th className="py-2 pr-4">Updated</th>
+                <th className="py-2 pr-4">Actions</th>
              </tr>
            </thead>
            <tbody>
              {assets.length === 0 ? (
                <tr>
-                  <td className="py-3 text-neutral-500" colSpan={6}>
+                  <td className="py-3 text-neutral-500" colSpan={7}>
                    No media assets yet. Upload your first asset above.
                  </td>
                </tr>
@@ -147,6 +149,14 @@ export default async function MediaManagementPage({
                    <td className="py-3 pr-4 text-neutral-600">
                      {asset.updatedAt.toLocaleDateString("en-US")}
                    </td>
+                    <td className="py-3 pr-4">
+                      <Link
+                        href={`/media/${asset.id}`}
+                        className="text-xs font-medium text-neutral-700 underline underline-offset-2"
+                      >
+                        Open
+                      </Link>
+                    </td>
                  </tr>
                ))
              )}
--- a/apps/admin/src/lib/media/local-storage.ts
+++ b/apps/admin/src/lib/media/local-storage.ts
@@ -1,4 +1,4 @@
-import { mkdir, writeFile } from "node:fs/promises"
+import { mkdir, rm, writeFile } from "node:fs/promises"
 import path from "node:path"

 import { buildMediaStorageKey } from "@/lib/media/storage-key"
@@ -15,7 +15,7 @@ type StoredUpload = {
  storageKey: string
 }

-function resolveBaseDirectory(): string {
+export function resolveLocalMediaBaseDirectory(): string {
  const configured = process.env.CMS_MEDIA_LOCAL_STORAGE_DIR?.trim()

  if (configured) {
@@ -33,7 +33,7 @@ export async function storeUploadLocally(params: StoreLocalUploadParams): Promis
    variant: params.variant,
    fileName: params.file.name,
  })
-  const baseDirectory = resolveBaseDirectory()
+  const baseDirectory = resolveLocalMediaBaseDirectory()
  const outputPath = path.join(baseDirectory, storageKey)

  await mkdir(path.dirname(outputPath), { recursive: true })
@@ -43,3 +43,24 @@ export async function storeUploadLocally(params: StoreLocalUploadParams): Promis

  return { storageKey }
 }
+
+export async function deleteLocalStorageObject(storageKey: string): Promise<boolean> {
+  const baseDirectory = resolveLocalMediaBaseDirectory()
+  const outputPath = path.join(baseDirectory, storageKey)
+
+  try {
+    await rm(outputPath)
+    return true
+  } catch (error) {
+    const code =
+      typeof error === "object" && error !== null && "code" in error
+        ? String((error as { code?: unknown }).code)
+        : ""
+
+    if (code === "ENOENT") {
+      return false
+    }
+
+    throw error
+  }
+}
--- a/apps/admin/src/lib/media/s3-storage.ts
+++ b/apps/admin/src/lib/media/s3-storage.ts
@@ -1,4 +1,4 @@
-import { PutObjectCommand, S3Client } from "@aws-sdk/client-s3"
+import { DeleteObjectCommand, PutObjectCommand, S3Client } from "@aws-sdk/client-s3"

 import { buildMediaStorageKey } from "@/lib/media/storage-key"

@@ -27,7 +27,7 @@ function parseBoolean(value: string | undefined): boolean {
  return value?.toLowerCase() === "true"
 }

-function resolveS3Config(): S3Config {
+export 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()
@@ -50,7 +50,7 @@ function resolveS3Config(): S3Config {
  }
 }

-function createS3Client(config: S3Config): S3Client {
+export function createS3Client(config: S3Config): S3Client {
  return new S3Client({
    region: config.region,
    endpoint: config.endpoint,
@@ -87,3 +87,17 @@ export async function storeUploadToS3(params: StoreS3UploadParams): Promise<Stor

  return { storageKey }
 }
+
+export async function deleteS3Object(storageKey: string): Promise<boolean> {
+  const config = resolveS3Config()
+  const client = createS3Client(config)
+
+  await client.send(
+    new DeleteObjectCommand({
+      Bucket: config.bucket,
+      Key: storageKey,
+    }),
+  )
+
+  return true
+}
--- a/apps/admin/src/lib/media/storage.ts
+++ b/apps/admin/src/lib/media/storage.ts
@@ -1,5 +1,5 @@
-import { storeUploadLocally } from "@/lib/media/local-storage"
-import { storeUploadToS3 } from "@/lib/media/s3-storage"
+import { deleteLocalStorageObject, storeUploadLocally } from "@/lib/media/local-storage"
+import { deleteS3Object, storeUploadToS3 } from "@/lib/media/s3-storage"

 export type MediaStorageProvider = "local" | "s3"

@@ -121,3 +121,29 @@ export async function storeUpload(params: StoreUploadParams): Promise<StoredUplo
    provider,
  }
 }
+
+export async function deleteStoredMediaObject(storageKey: string): Promise<void> {
+  const preferred = resolveMediaStorageProvider(process.env.CMS_MEDIA_STORAGE_PROVIDER)
+  const deleteOperations =
+    preferred === "s3"
+      ? [() => deleteS3Object(storageKey), () => deleteLocalStorageObject(storageKey)]
+      : [() => deleteLocalStorageObject(storageKey), () => deleteS3Object(storageKey)]
+  const errors: string[] = []
+
+  for (const performDelete of deleteOperations) {
+    try {
+      const deleted = await performDelete()
+
+      if (deleted) {
+        return
+      }
+    } catch (error) {
+      const detail = describeS3Error(error)
+      errors.push(detail)
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new Error(`Storage object deletion failed for key "${storageKey}": ${errors.join(" | ")}`)
+  }
+}
--- a/packages/content/src/media.ts
+++ b/packages/content/src/media.ts
@@ -29,6 +29,23 @@ export const createMediaAssetInputSchema = z.object({
  isPublished: z.boolean().optional(),
 })

+export const updateMediaAssetInputSchema = z.object({
+  id: z.string().uuid(),
+  type: mediaAssetTypeSchema.optional(),
+  title: z.string().min(1).max(180).optional(),
+  description: z.string().max(5000).nullable().optional(),
+  altText: z.string().max(1000).nullable().optional(),
+  source: z.string().max(500).nullable().optional(),
+  copyright: z.string().max(500).nullable().optional(),
+  author: z.string().max(180).nullable().optional(),
+  tags: z.array(z.string().min(1).max(100)).optional(),
+  mimeType: z.string().max(180).nullable().optional(),
+  width: z.number().int().positive().nullable().optional(),
+  height: z.number().int().positive().nullable().optional(),
+  sizeBytes: z.number().int().min(0).nullable().optional(),
+  isPublished: z.boolean().optional(),
+})
+
 export const createArtworkInputSchema = z.object({
  title: z.string().min(1).max(180),
  slug: z.string().min(1).max(180),
@@ -66,6 +83,7 @@ export const attachArtworkRenditionInputSchema = z.object({
 export type MediaAssetType = z.infer<typeof mediaAssetTypeSchema>
 export type ArtworkRenditionSlot = z.infer<typeof artworkRenditionSlotSchema>
 export type CreateMediaAssetInput = z.infer<typeof createMediaAssetInputSchema>
+export type UpdateMediaAssetInput = z.infer<typeof updateMediaAssetInputSchema>
 export type CreateArtworkInput = z.infer<typeof createArtworkInputSchema>
 export type CreateGroupingInput = z.infer<typeof createGroupingInputSchema>
 export type LinkArtworkGroupingInput = z.infer<typeof linkArtworkGroupingInputSchema>
--- a/packages/db/src/index.ts
+++ b/packages/db/src/index.ts
@@ -7,11 +7,14 @@ export {
  createGallery,
  createMediaAsset,
  createTag,
+  deleteMediaAsset,
+  getMediaAssetById,
  getMediaFoundationSummary,
  linkArtworkToGrouping,
  listArtworks,
  listMediaAssets,
  listMediaFoundationGroups,
+  updateMediaAsset,
 } from "./media-foundation"
 export {
  createPost,
--- a/packages/db/src/media-foundation.test.ts
+++ b/packages/db/src/media-foundation.test.ts
@@ -7,7 +7,7 @@ const { mockDb } = vi.hoisted(() => ({
    artworkCategory: { upsert: vi.fn() },
    artworkTag: { upsert: vi.fn() },
    artworkRendition: { upsert: vi.fn() },
-    mediaAsset: { create: vi.fn() },
+    mediaAsset: { create: vi.fn(), findUnique: vi.fn(), update: vi.fn(), delete: vi.fn() },
    artwork: { create: vi.fn() },
    gallery: { create: vi.fn() },
    album: { create: vi.fn() },
@@ -24,7 +24,10 @@ import {
  attachArtworkRendition,
  createArtwork,
  createMediaAsset,
+  deleteMediaAsset,
+  getMediaAssetById,
  linkArtworkToGrouping,
+  updateMediaAsset,
 } from "./media-foundation"

 describe("media foundation service", () => {
@@ -36,6 +39,15 @@ describe("media foundation service", () => {
      if ("create" in value) {
        value.create.mockReset()
      }
+      if ("findUnique" in value) {
+        value.findUnique.mockReset()
+      }
+      if ("update" in value) {
+        value.update.mockReset()
+      }
+      if ("delete" in value) {
+        value.delete.mockReset()
+      }
    }
  })

@@ -90,4 +102,22 @@ describe("media foundation service", () => {
    expect(mockDb.mediaAsset.create).toHaveBeenCalledTimes(1)
    expect(mockDb.artwork.create).toHaveBeenCalledTimes(1)
  })
+
+  it("handles media asset read/update/delete operations", async () => {
+    mockDb.mediaAsset.findUnique.mockResolvedValue({ id: "asset-1" })
+    mockDb.mediaAsset.update.mockResolvedValue({ id: "asset-1", title: "Updated" })
+    mockDb.mediaAsset.delete.mockResolvedValue({ id: "asset-1" })
+
+    await getMediaAssetById("asset-1")
+    await updateMediaAsset({
+      id: "c58f3aca-f958-4079-b2df-c9edf3a5fb0a",
+      title: "Updated",
+      tags: ["a", "b"],
+    })
+    await deleteMediaAsset("asset-1")
+
+    expect(mockDb.mediaAsset.findUnique).toHaveBeenCalledTimes(1)
+    expect(mockDb.mediaAsset.update).toHaveBeenCalledTimes(1)
+    expect(mockDb.mediaAsset.delete).toHaveBeenCalledTimes(1)
+  })
 })
--- a/packages/db/src/media-foundation.ts
+++ b/packages/db/src/media-foundation.ts
@@ -4,6 +4,7 @@ import {
  createGroupingInputSchema,
  createMediaAssetInputSchema,
  linkArtworkGroupingInputSchema,
+  updateMediaAssetInputSchema,
 } from "@cms/content"

 import { db } from "./client"
@@ -107,6 +108,28 @@ export async function createMediaAsset(input: unknown) {
  })
 }

+export async function getMediaAssetById(id: string) {
+  return db.mediaAsset.findUnique({
+    where: { id },
+  })
+}
+
+export async function updateMediaAsset(input: unknown) {
+  const payload = updateMediaAssetInputSchema.parse(input)
+  const { id, ...data } = payload
+
+  return db.mediaAsset.update({
+    where: { id },
+    data,
+  })
+}
+
+export async function deleteMediaAsset(id: string) {
+  return db.mediaAsset.delete({
+    where: { id },
+  })
+}
+
 export async function createArtwork(input: unknown) {
  const payload = createArtworkInputSchema.parse(input)