Media API

This guide documents the media proxy endpoint that provides secure access to uploaded media files stored in Firebase Storage.

Overview

The media API provides a proxy layer between clients and Firebase Storage, handling:

• Media file serving via secure URLs
• Token-based access validation
• Redirect-based delivery with caching

Endpoint

GET|HEAD /media/{id}[.{ext}]

Where:

• {id}: Media document ID (minimum 8 characters)
• {ext}: Optional file extension (ignored for lookup)

Implementation

Entry: apps/functions/media.js

Flow:

1. Extract media ID from request path (strips extension if present)
2. Validate ID format (minimum 8 characters, lowercase)
3. Look up media document in media/{id} collection
4. Extract objectPath and downloadToken from document
5. Construct Firebase Storage download URL
6. Proxy‑stream bytes from Firebase Storage to the client (supports Range requests); HEAD returns headers only

Data Model

Media documents in media/{id}:

• userId: string - Owner of the media file
• keyHash: string - Hash of API key used to upload
• url: string - Original upload URL
• contentType: string - MIME type
• objectPath: string - Storage bucket path
• downloadToken: string - Firebase Storage access token
• createdAt: timestamp

Response Headers

• Content-Type: from upstream or application/octet-stream
• Accept-Ranges: bytes
• Cache-Control: public, max-age=3600

Error Responses

The media API uses the standard error handling system with structured responses.

Error Response Format

{
  "error": {
    "code": "not_found",
    "message": "Media not found",
    "timestamp": "2025-08-29T00:02:14.654Z",
    "requestId": "abb6930d-2b57-4d44-9d63-19d5a9c8d077"
  }
}

Common Error Codes

Code	Status	Description
not_found	404	Media ID not found or invalid format
method_not_allowed	405	Non-GET request
internal_error	500	Server error

Request Tracking

This endpoint does not attach request IDs, but you can include your own X-Request-ID header for client correlation.

Security

• Media access is controlled by Firebase Storage download tokens
• No authentication required at proxy level (token-based security)
• Short redirect cache prevents token exposure in browser history
• Firebase Storage provides long-term caching for actual media delivery

Configuration

Environment variables:

• MEDIA_BUCKET - Firebase Storage bucket name (optional, uses default if not set)

Usage

# Access media file
GET /media/abcd1234

# With file extension (extension ignored for lookup)
GET /media/abcd1234.jpg

The proxy returns a redirect to the actual Firebase Storage URL with appropriate access tokens.