# MotorSignal — Cloudflare R2 Worker Gateway

This Cloudflare Worker acts as the secure, authenticated authorization gateway between the MotorSignal mobile application and Cloudflare R2 object storage for large 20Hz forensic telemetry ZIP bundles.

---

## Security Architecture

1. **Zero Client Secrets**: The Flutter mobile app contains zero Cloudflare API tokens, R2 access keys, or secrets.
2. **Server-Side Path Derivation**: The Worker authenticates the client's Firebase ID token and dynamically derives the object path:
   ```
   users/{authenticatedUid}/rides/{validatedRemoteRideId}/telemetry.zip
   ```
   Clients cannot override or spoof target user paths.
3. **Streamed Uploads**: The Worker streams binary ZIP payloads directly into R2 using the Cloudflare `R2Bucket` binding without memory buffering.

---

## Endpoints

### 1. Direct Binary Upload
* **Method**: `PUT`
* **Path**: `/r2/upload`
* **Headers**:
  * `Authorization`: `Bearer <FirebaseIdToken>`
  * `Content-Type`: `application/zip`
  * `X-Remote-Ride-Id`: `ride_<localRideId>_<timestamp>`
  * `X-Bundle-Sha256`: `<sha256-hash>`
  * `X-App-Version`: `1.0.2`
* **Body**: Raw binary bytes of `telemetry.zip`.
* **Response**:
  ```json
  {
    "success": true,
    "objectKey": "users/<uid>/rides/<remoteRideId>/telemetry.zip",
    "size": 348120,
    "etag": "\"8f4b2c1...\"",
    "uploadedAt": "2026-08-31T12:00:00.000Z"
  }
  ```

### 2. Upload Request Authorization
* **Method**: `POST`
* **Path**: `/r2/upload-url`
* **Headers**:
  * `Authorization`: `Bearer <FirebaseIdToken>`
  * `Content-Type`: `application/json`
* **Body**:
  ```json
  {
    "remoteRideId": "ride_14_20260831_080000"
  }
  ```

### 3. Telemetry Bundle Download
* **Method**: `GET`
* **Path**: `/r2/download?rideId=<remoteRideId>`
* **Headers**:
  * `Authorization`: `Bearer <FirebaseIdToken>`
* **Response**: Binary stream of `telemetry.zip`.

---

## Deployment & Setup

### 1. Prerequisites
Install Wrangler CLI:
```bash
npm install -g wrangler
cd cloudflare/motorsignal-r2-worker
npm install
```

### 2. Create R2 Bucket
```bash
wrangler r2 bucket create motorsignal-telemetry
```

### 3. Deploy Worker
```bash
wrangler deploy
```

### 4. Configure Secrets (if needed)
```bash
wrangler secret put FIREBASE_PROJECT_ID
```