# Route Spec

## Route ID
`auth-firebase-token`

## Endpoint
`POST /api/v1/auth/firebase/token`

## Human Description
Exchanges a Firebase phone-auth or Firebase anonymous ID token for a Duuble backend session.

## Authentication
- Required: `no` (Firebase ID token acts as credential)
- Auth type: `firebase id token`
- Required roles/scopes: `none`

## Request
### Headers
- `Content-Type: application/json`

### Body
```json
{
  "idToken": "firebase_id_token",
  "device": {
    "deviceId": "dev_abcd1234",
    "platform": "android"
  }
}
```

### Validation Rules
- `idToken`: required.
- `device.deviceId`: required.
- `device.platform`: required, enum `ios|android`.
- Firebase token must be issued by the configured Firebase project.
- Firebase `phone` tokens create or restore a verified phone identity.
- Firebase `anonymous` tokens create or restore an anonymous-only backend identity.
- Other Firebase sign-in providers are rejected.

## Responses
### Success: `200 OK`
When returned:
- Firebase token is valid and maps to a phone-authenticated or anonymous backend identity.

Body:
```json
{
  "success": true,
  "message": "Firebase sign-in successful",
  "data": {
    "accessToken": "jwt_access_token",
    "refreshToken": "jwt_refresh_token",
    "accessTokenExpiresAt": "2026-02-18T13:34:56Z",
    "isNewUser": false,
    "onboarding": {
      "nextStep": "completed"
    }
  }
}
```

### Error: `401 Unauthorized`
When returned:
- Firebase ID token is invalid, expired, from the wrong project, or uses an unsupported sign-in provider.

Body:
```json
{
  "success": false,
  "error": {
    "code": "FIREBASE_TOKEN_INVALID",
    "message": "Firebase authentication failed.",
    "details": {}
  }
}
```

### Error: `422 Unprocessable Entity`
When returned:
- Required request fields are missing or malformed.

Body:
```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Invalid request.",
    "details": {}
  }
}
```

## Data & Caching Dependencies
- **Spanner Tables:** `users, user_identities (Read/Write)`
- **Redis Cache:** `refresh_tokens (Write)`
- **GCS Storage:** `None`
- **Edge Cache (CDN):** `No`

## Side Effects
- Creates or resolves the user identity for the Firebase phone number or Firebase anonymous subject.
- When a phone Firebase token is exchanged while the request carries an anonymous backend access token, the backend merges eligible anonymous public activity into the phone identity.
- Creates backend access and refresh tokens.

## Idempotency and Retries
- Idempotent: `conditionally`
- Retry guidance: safe to retry with the same valid Firebase ID token until it expires.