Media Service — Vision & Product Spec

Last Updated: 2026-04-29 Status: Active Service: apps/media-service (Cloudflare Worker, port 8789)

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

5.2 Status Machine

[*] → PENDING_UPLOAD
        (presign creates the row)
 
PENDING_UPLOAD → UPLOADED
        (client calls /upload/complete after R2 PUT)
 
PENDING_UPLOAD → [garbage collected]
        (stale cleanup cron: 24h with no completion)
 
UPLOADED → [deleted]
        (user or system calls DELETE /files/:id)

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

Beyond PBAC, the assertMediaAccess() function enforces:

• Uploader match: record.uploadedBy === userId
• Tenant match: record.tenantId === tenantId

A user must be the uploader OR a member of the same workspace to modify a file. system:owner bypasses this entirely.

6.4 SSRF Protection (URL Ingest)

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

• Hostname deny list: localhost, *.local, *.internal
• Private IP deny list: 127.*, 10.*, 192.168.*, 172.16-31.*, 169.254.*, ::1, fe80:, fc00:, fd00:
• 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

Public media is served directly from R2's public access URL:

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

In production, this is fronted by a custom domain (media.logicspike.com) via Cloudflare DNS with automatic SSL.

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
• Infinite scroll — Cursor-based pagination, loads more on scroll
• Upload zone — Drag & drop at the top of the page

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