Media Library — current implementation
Source review: 2026-10-20, HEAD f38ee3c6ced7fcab6b34955a65cfb955ec097567, root package 1.6.9. This page supersedes the October 14 diagrams for current behavior. Each edge below follows the linked implementation; conditional paths are labeled. It is a source review, not a live deployment check.
2026-11-05 deletion update: deleteAsset records an asset.delete_started audit plan before the catalog cascade, keeps the name held during object removal, and resumes a failed or interrupted delete when the same ID is deleted again. The deletion sequence and risk note below reflect the current code at 3c6086c04. Sources: delete workflow, recovery tests.
Components
flowchart LR
UI["core/admin media UI"] --> AC["media-client"]
AC --> AR["admin media routes"]
AR --> AS["admin media-service"]
AS -->|local| ML["MediaLibrary"]
AS -->|MEDIA_API_URL| NR["media-nuxt routes"]
NR --> MA["media-auth principal and scope"]
MA --> SL["scoped MediaLibrary"]
SL --> ML
ML --> CAT["CatalogStore / JobStore / AuditStore"]
ML --> BLOB["BlobStore"]
ML --> IMG["image transformer / sanitizer"]
CAT -->|local| SQL["SQLite"]
CAT -->|Dynamo backend| DDB["DynamoDB"]
BLOB -->|local| FS["filesystem"]
BLOB -->|Dynamo backend| S3["S3 or MinIO"]
S3 -->|AWS ObjectCreated under m/| SQS["SQS media queue"]
SQS --> WORKER["media worker"]
WORKER --> ML
The admin server sanitizes forwarded uploads before presign; its local library injects the full sanitizer. Web routes inject the web sanitizer and use getScopedMediaLibrary; the worker is a trusted unscoped caller. Tenant-token parsing exists, but verifyMediaTenantToken returns null, so tenant Bearers currently receive 401. The admin token remains the usable HTTP principal. The admin database selector does not select the DAM store. Sources: admin media service, web media auth, tenant-token verifier, web library factory, worker, SAM resources.
Domain and ports
classDiagram
class MediaAsset {
+string id
+MediaTenant tenant
+MediaKind kind
+string path
+string sha256
+number byteSize
+Record meta
}
class MediaChild {
+string id
+string assetId
+MediaChildVariant variant
+ChildStatus status
+string path
}
class JobRecord {
+string id
+string assetId
+string childId
+JobStatus status
+number attempts
}
class AuditEvent {
+string entityId
+string action
+string correlationId
}
class MediaLibrary {
+ingest(input)
+registerRemoteAsset(input)
+renameAsset(id, request)
+runMaterializeJob(id)
+deleteAsset(id)
}
class CatalogStore {
<<interface>>
+insertAsset(asset)
+renameAsset(input)
+deleteAssetCascade(id)
}
class BlobStore {
<<interface>>
+put(key, data, options)
+get(key)
+delete(key)
}
class JobStore {
<<interface>>
+claimQueuedJob(id, claimed)
+finalizeRunningJob(id, startedAt, next)
}
class AuditStore {
<<interface>>
+append(event)
}
MediaAsset "1" --> "0..*" MediaChild : assetId
MediaAsset "1" --> "0..*" JobRecord : assetId
MediaChild "1" --> "0..*" JobRecord : childId
MediaLibrary ..> CatalogStore
MediaLibrary ..> BlobStore
MediaLibrary ..> JobStore
MediaLibrary ..> AuditStore
These are implemented TypeScript types and the concrete MediaLibrary class. Audit events reference entities by ID but have no enforced relational association, so no association is drawn. CatalogStore, BlobStore, JobStore, and AuditStore are injected ports; SQLite, filesystem, DynamoDB, and S3 are adapter implementations. The SQL and Dynamo catalogs implement name claims, rename, and conditional child/job writes differently. Sources: domain types, ports, library, SQLite stores, Dynamo stores, PostgreSQL adapter.
Upload and validation
sequenceDiagram
actor Operator
participant Admin as Admin UI and service
participant API as media-nuxt ingest routes
participant Scope as Media principal and scoped library
participant Store as Reserved catalog and blob store
Operator->>Admin: Choose file and metadata
alt Admin uses local media library
Admin->>Store: MediaLibrary.ingest with full sanitizer
Store-->>Admin: Registered asset
else Admin forwards to media API
Admin->>Admin: Sanitize supported input
alt SVG
Admin->>API: POST ingest/svg
API->>Scope: Authenticate and validate scope
Scope->>Store: Ingest checked SVG
else Other supported kind
Admin->>API: POST ingest/presign with byteSize
API->>Scope: Authenticate, validate kind and tenant
Scope->>Store: Reserve name
API-->>Admin: Signed PUT URL and headers
Admin->>Store: PUT exact bytes
Admin->>API: POST ingest/complete
API->>Scope: Authenticate and check reservation
Scope->>Store: Head, digest, sanitize if needed, register
end
Store-->>Admin: Asset and URLs
end
Admin-->>Operator: Asset or mapped error
The admin upload route receives base64 JSON and decodes into a buffer. Forwarded SVG uses its own authenticated route; other kinds use presign/PUT/complete. The presign route checks declared size against per-kind caps; tenant requests require byteSize and are limited to raster types, though tenant tokens are presently disabled. complete checks the reservation and stored object, computes its digest, applies conditional in-place raster sanitization where needed, and registers the result. A repeated completion for an already registered asset returns it without re-sanitizing. PDF/MP4 preSanitized signatures have a compatibility mode: missing signature or key may still be honored for an admin request, as described in the route; this is not a fully enforced signature requirement. Sources: admin upload, admin upload route, presign, complete, SVG route, sanitizer, upload caps, upload lifecycle.
Processing
sequenceDiagram
participant Caller as Request or worker
participant Library as MediaLibrary
participant Jobs as JobStore
participant Transform as ImageTransformer
participant Blobs as BlobStore
participant Catalog as CatalogStore
Caller->>Library: Materialize or re-run recipes
Library->>Jobs: Insert and claim job
Jobs-->>Library: Lease
Library->>Blobs: Read original
Library->>Transform: Run image recipe
Transform-->>Library: Output bytes and metadata
Library->>Blobs: Put deterministic variant key
Library->>Catalog: Conditionally finalize job and child
Catalog-->>Library: Updated, moved, missing or lost lease
Library-->>Caller: Current child and job
On ingest, metadata and image catalog variants (t, 640, 1280, 1920) are attempted by the request hook except when the AWS queue owns the work. Explicit materialization uses SQS when MEDIA_QUEUE_URL is configured and otherwise runs inline. The S3 ObjectCreated notification also feeds the queue, and the worker waits briefly for registration if the event wins the race. Only the image transformer is implemented; other transform recipes remain unsupported. Output is still written to a deterministic key before lease-conditioned catalog finalization. Rename-aware retries reduce moved-asset races but do not make blob publication atomic. Sources: on-ingest recipes, dispatch, worker, materialize runner, transformer registry, SAM queue and trigger.
Retrieval, editing, renaming and deletion
sequenceDiagram
actor Operator
participant UI as Admin media page
participant API as Admin or web media route
participant Library as Scoped or local MediaLibrary
participant Catalog as CatalogStore
participant Blobs as BlobStore
participant Audit as AuditStore
Operator->>UI: Open asset
UI->>API: GET asset detail
API->>Library: getAsset and listChildren
Library->>Catalog: Read catalog
Catalog-->>UI: Asset, children, jobs, processing and URLs
opt Edit details or tags
UI->>API: PATCH metadata
API->>Library: updateAssetMeta with edit validation
end
opt Rename file
UI->>API: POST rename
API->>Library: renameAsset
Library->>Blobs: Copy to new keys
Library->>Catalog: Atomic name and row switch
Library->>Blobs: Remove old keys
end
opt Delete asset after UI Undo window
UI->>API: DELETE asset
API->>Library: deleteAsset
Library->>Audit: Record delete_started with object paths
Library->>Catalog: Cascade asset and children, hold name
Library->>Blobs: Delete recorded object keys
alt object delete fails or process stops
Library->>Audit: Record delete_failed if process survives
Operator->>API: Repeat DELETE with the same asset ID
API->>Library: resumeDelete from audit plan
Library->>Blobs: Retry remaining object keys
end
end
Catalog reads are authenticated. Public /m/** or CloudFront object delivery is separate and has no admin Bearer check. Admin details and tag editing use explicit forms; metadata PATCH validates human edits, while internal measured-metadata writes use a separate path. Rename changes public keys and has no redirect from old URLs. The catalog switch is atomic within an adapter; copy and cleanup span storage, with audit-led resumption on later reads/renames. Delete rejects fresh running jobs. Its audit plan and name hold make a repeated delete of the gone ID recover failed object removal and invalidation; no scheduled sweep of open plans is implemented. Sources: admin editing, rename UI, admin service, scoped library, rename workflow, delete workflow, local delivery, URL projection.
Lifecycle and deployment
flowchart TD
Select["Select file and metadata"] --> Validate["Validate kind, size and sanitize"]
Validate --> Reserve["Reserve name or ingest locally"]
Reserve --> Store["Store original and catalog asset"]
Store --> Recipes["Run or queue on-ingest recipes"]
Recipes --> Retrieve["List, detail and public object URL"]
Retrieve --> Edit["Edit metadata or tags"]
Edit --> Rename["Optional rename with copy, switch and cleanup"]
Rename --> Process["Optional re-run or custom image variant"]
Process --> Delete["Optional delete after client Undo window"]
Delete --> Cascade["Catalog cascade then object removal"]
flowchart LR
Host["Host admin node-server"] --> LDB["Admin SQLite and filesystem media"]
Docker["Docker admin or development"] --> Emu["DynamoDB Local and MinIO"]
Docker --> PG["PostgreSQL for posts and messages"]
Web["Web Nitro runtime"] -->|DATA_BACKEND sqlite or postgres| WLocal["SQLite and filesystem media"]
Web -->|DATA_BACKEND dynamodb| Emu
Lambda["SAM web Lambda"] --> AWSDB["DynamoDB media table"]
Lambda --> AWSS3["Private S3 assets bucket"]
AWSS3 --> Queue["S3 notification to SQS"]
Queue --> Worker["Media worker Lambda"]
AWSS3 --> CF["CloudFront OAC delivery"]
The PostgreSQL media catalog adapter exists as a package, but getMediaLibrary still falls back to SQLite/filesystem when DATA_BACKEND=postgres outside Lambda. The admin’s own media library stays local unless MEDIA_API_URL is configured; the admin database selector controls posts/messages, not this media backend. AWS Lambda always uses DynamoDB/S3. Docker test emulates Lambda with local AWS services; it does not prove CloudFront behavior. Sources: media factory, admin factory, Compose, SAM template, PostgreSQL media adapter.
Verified gaps and recommendations
| Current mechanism | Consequence or proposed improvement |
|---|---|
Tenant tokens are classified but verifyMediaTenantToken always returns null. |
Tenant access is not live; implement and test a token map before describing multi-tenant HTTP access as enabled. |
Presigned bytes occupy their final public key before complete sanitizes and registers them. |
A pending object may be retrievable by key; consider private staging or a delivery check before claiming that invalid bytes were never public. |
| Missing PDF/MP4 pre-sanitization signature can be honored for an admin request in compatibility mode. | Decide when to enforce signatures and test key rotation before treating this as a hard trust boundary. |
| Variant writes use deterministic keys before conditional job/child finalization. | Consider attempt-specific storage keys with a compatible public URL contract. |
| Delete records intent and object paths before catalog removal, but recovery requires a repeated DELETE for the gone ID. | Consider an authenticated recovery view or scheduled sweep for abandoned plans; retain the name-hold ownership checks. |
| Rename has audit-led retry on later reads, but no scheduled reconciler is evidenced. | Define retention and a reconciliation trigger for abandoned cleanup if required. |
The operational risks are inferences from code paths, not reproduced incidents. For the November correction, the focused media deletion test passed; browser flow, live stores, Docker, AWS, IAM policy behavior and accessibility were not exercised.