Media Service — Vision & Product Spec

Last Updated: 2026-10-12 (storage and security sections); the rest dates from 2026-04-29 Status: Active Service: apps/media-service (Cloudflare Worker, port 8801)

The Media Service is LogicSpike's centralized file storage platform — the single layer through which every image, video, document, and asset in the system flows. It is to media what the Manager is to identity: the authoritative source of truth.

1. Purpose (The Why)

Every LogicSpike service produces or consumes media:

Without a centralized media layer, each service would implement its own upload logic, storage keys, access control, and CDN delivery — duplicating security surface and fragmenting the user's asset library.

The Media Service exists to:

1. Unify storage — One R2 bucket, one key namespace, one DB table.
2. Centralize access control — PBAC-guarded uploads and deletions, gateway-verified identity.
3. Provide a shared asset library — Users upload once, use everywhere. A blog cover image can be reused in a newsletter without re-uploading.
4. Deliver fast — Cloudflare R2 with public read access via CDN, zero-egress costs.

2. Target Audience

3. Core Features & Value Props

3.1 Current State (v1 — Shipped)

3.2 Target State (v2 — This Build)

3.3 Future (v3+)

4. Architecture Overview

4.1 System Context

4.2 Upload Flow (Critical Path)

4.3 R2 Key Namespace

All files follow a deterministic path structure:

Tenant-scoped (workspace content):
  {tenantId}/{serviceCode}/{YYYY}/{MM}/{nanoid}.{ext}
  └── ls_abc123/blog/2026/04/xK9mQ2pL.webp
 
User-scoped (personal, no workspace context):
  users/{userId}/{serviceCode}/{YYYY}/{MM}/{nanoid}.{ext}
  └── users/user_789/avatar/2026/04/aB3nR7kW.jpg

5. Data Model

5.1 media_files Table

Also: media_file_tags (media_id, tenant_id, tag) and media_file_favorites (media_id, user_id, tenant_id), both removed with their file. Migration manual-migrations/2026-10-13-media-library-v2.sql.

5.2 Status Machine

[*] → PENDING_UPLOAD
        (presign creates the row)
 
PENDING_UPLOAD → UPLOADED
        (client calls /upload/complete after the R2 PUT; media checks the object
         exists at the declared size)
 
PENDING_UPLOAD → [removed]
        (MediaJanitor: 24h with no completion)
 
UPLOADED → ARCHIVED
        (DELETE /files/:id, bulk delete)
 
ARCHIVED → [removed]
        (permanent delete; or MediaJanitor 30 days after archiving, non-public only)
 
UPLOADED (delegated) → [removed]
        (the owning service releases it: mailbox after sending, forms when the
         submission is deleted; unsent mail attachments after 30 days)

Bytes are always deleted before the row, and a failed byte delete keeps the row. The cleanup runs on a Durable Object alarm (src/do/media-janitor.ts), because the account has no cron slots left; the old scheduled handler never ran.

5.3 Allowed MIME Types

6. Security Model

6.1 Authentication Chain

Browser → Gateway (JWT verify + subscription guard)
       → x-user-id / x-tenant-id / x-user-permissions headers
       → Media Service (reads headers, trusts gateway)

The media service does not verify JWTs. Identity is delegated to the gateway.

6.2 Permission-Based Access Control (PBAC)

6.3 Ownership Enforcement

Reading is decided by canReadMedia and managing by canManageMedia (packages/core-media):

• Read: public → anyone; tenant → members of that workspace; private → the uploader; delegated → only with a capability token from the owning service, bound to the user, workspace and subject (v2 tokens, one signing key per service).
• Manage (archive, delete, restore): the uploader, inside the file's own workspace; or media:files.admin / system:owner in that workspace. Having uploaded a file to a workspace you've left grants nothing (fixed 2026-10-12).
• Single-file routes look a file up in the caller's workspace only: another workspace's id reads as 404.
• Change visibility (PATCH /files/:id/visibility, canChangeMediaVisibility): Media library uploads only (files added by Blog, Social, Newsletter or Collections keep the visibility their feature set; form and mail files are service-managed). The uploader may choose Public, Workspace or Only me; media:files.admin / system:owner may switch a colleague's file Public ↔ Workspace but never into or out of Only me. Crossing public moves the bytes between buckets (copy → switch if unchanged → delete the old copy, or undo). Audit G24.

6.4 SSRF Protection (URL Ingest)

The /upload/ingest-url endpoint fetches external URLs server-side. Guards:

• Hostname deny list: localhost, *.local, *.internal
• Private IPv4: 0/8, 10/8, 127/8, 100.64/10, 169.254/16, 172.16/12, 192.0.0/24, 192.168/16, 198.18/15, 224+
• Private IPv6 (brackets stripped first; the old pattern never matched because URL.hostname keeps them): ::, ::1, fe80::/10, fc00::/7, 64:ff9b::/96, and IPv4-mapped ::ffff: addresses judged by the IPv4 inside
• Redirect re-validation: Each redirect hop is re-checked (max 3 hops)
• Known gap: No DNS rebinding protection (documented, acceptable for now)

6.5 Multi-Tenant Isolation Invariant

R2 key isolation is structural — the {tenantId}/ prefix in every key makes cross-tenant object access impossible via path traversal. The DB layer reinforces this with the tenant_id filter on every query.

6.6 Content-Type Validation Defense

The service validates MIME types at two layers to prevent content-type confusion attacks:

1. Client-declared contentType — Checked against the allowlist at presign time
2. R2 Content-Type header — Set explicitly in the presigned PUT URL via PutObjectCommand({ ContentType }), so even if the client lies about the body, browsers will interpret the served file using the declared type

This prevents an attacker from uploading a .html file disguised as image/jpeg (stored XSS via CDN).

6.7 Rate Limiting

6.8 CORS Lockdown

// Production CORS — restrict to known origins only
cors({
    origin: [
        'https://app.logicspike.com',
        'https://logicspike.com',
        process.env.NODE_ENV === 'development' && 'http://localhost:3000',
    ].filter(Boolean),
    allowMethods: ['GET', 'POST', 'PATCH', 'DELETE', 'OPTIONS'],
    maxAge: 86400,
})

7. Error Handling Contract

Every error response follows the platform-wide error envelope:

{
  "error": "Human-readable message",
  "code": "MACHINE_READABLE_CODE",
  "status": 400
}

7.1 Error Codes

7.2 Client-Side Error Recovery

The frontend useMediaUpload hook implements retry logic:

8. Observability & Monitoring

8.1 Structured Logging

Every request emits a structured JSON log line:

{
  "level": "info",
  "event": "media.upload.presign",
  "tenantId": "ls_abc123",
  "userId": "user_789",
  "mediaId": "media_xK9mQ2pL",
  "mimeType": "image/webp",
  "fileSize": 245000,
  "durationMs": 42,
  "status": 200
}

8.2 Key Metrics (Cloudflare Analytics)

8.3 Health Check

GET /health → 200 { "status": "ok", "service": "media", "version": "1.0.0" }

The gateway's health aggregator polls this every 30 seconds.

9. CDN & Caching Strategy

9.1 R2 Public Bucket Delivery

Only public files are in the public bucket (logicspike-media-local), served at:

https://pub-a2acd43000854b76860fa1b2f86aa406.r2.dev/{key}

There is no custom domain (media.vlozi.app has no DNS); moving off r2.dev is gap G6 in the audit. Every other file is in vlozi-media-private, which has no public access: a browser gets it through /files/:id/content, a third party through a presigned link (1 hour by default, up to 7 days).

9.2 Cache Headers

9.3 Why immutable?

Every uploaded file gets a unique nanoid-based key (xK9mQ2pL.webp). Files are never overwritten — updating a blog cover image creates a new key and deletes the old one. This means CDN caches never serve stale content without explicit purge, and immutable tells browsers to skip conditional requests entirely.

10. Cost Model

10.1 Cloudflare R2 Pricing (Current)

10.2 Projected Costs at Scale

10.3 Neon Postgres Costs

The media_files table is lightweight (each row ~500 bytes). At 5M rows, the table occupies ~2.5 GB including indexes — well within Neon's free tier (3 GB storage).

11. Inter-Service Communication

12. Frontend Vision

12.1 Media Module (New — /dashboard/media)

The Media module is a first-class service in the dashboard sidebar, equal in stature to Blog or Content Engine. It provides a centralized asset management experience.

Overview Page (/dashboard/media)

The landing page surfaces key metrics and recent activity:

• Hero header — "Your media, organized." with total file count badge
• Stats bar — 4 cells: Total Files, Storage Used, Images, Videos/Docs
• Recent uploads — Last 8 files in a responsive grid
• Quick upload zone — Drag & drop or click to upload

Library Page (/dashboard/media/files)

The full-power media browser:

• Filter bar — MIME type groups (All / Images / Videos / Documents) + search input
• View toggle — Grid view (thumbnails) / List view (table with metadata)
• Grid view — Responsive masonry: grid-cols-2 md:grid-cols-3 lg:grid-cols-4 xl:grid-cols-5
• File cards — Thumbnail preview, filename, size, date, service badge, hover actions
• Multi-select — Checkbox mode for bulk operations. Sticky action bar at bottom.
• Detail sheet — Click a file → side sheet with full preview, all metadata, copy URL, delete, and a Workspace / Only me / Public switch (asks before making a file public or breaking its public link)
• Infinite scroll — Cursor-based pagination, loads more on scroll
• Upload zone — Drag & drop at the top of the page, with a Workspace / Only me / Public switch (starts at Workspace every visit)

12.2 Enhanced MediaPicker (Existing — Side Drawer)

The MediaPicker component (used by blog editor, cover image picker, etc.) gets upgraded from a basic "upload + 20 thumbnails" to a mini media browser:

12.3 Navigation

Dashboard Sidebar
├── ...
├── Media               ← NEW (was "coming_soon", now "stable")
│   ├── Overview         /dashboard/media
│   └── Library          /dashboard/media/files
├── ...

13. Implementation Phases

Phase 1 — Backend Hardening (Day 1)

Phase 2 — Dashboard API Routes (Day 1)

Phase 3 — Media Module Frontend (Day 2–3)

Phase 4 — MediaPicker Upgrade (Day 3)

Phase 5 — Security Hardening (Day 4)

14. Design Language

The Media module follows the established LogicSpike dashboard aesthetic:

15. Known Gaps & Technical Debt

16. Edge Cases & Error Paths

17. Disaster Recovery

18. Cross-References