# Route Spec

## Route ID
`auth-anonymous-session`

## Endpoint
`POST /api/v1/auth/anonymous/session`

## Human Description
Creates or restores a backend anonymous user session for the current app install. The mobile app calls this when it needs a real backend identity for public actions and Firebase anonymous sign-in is unavailable or has not returned a usable token.

## Authentication
- Required: `no`
- Auth type: `install device id`
- Required roles/scopes: `none`

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

### Body
```json
{
  "device": {
    "deviceId": "duuble-android-3e5a0e3a2e8d49b7a9a5c2d4f8a1b6c0",
    "platform": "android"
  }
}
```

### Validation Rules
- `device.deviceId`: required, 16-255 characters. The mobile app stores it locally for the app install; uninstall/reinstall creates a new anonymous identity.
- `device.platform`: required, enum `ios|android`.

## Responses
### Success: `200 OK`
When returned:
- The install device id was accepted and mapped to an anonymous-only backend user.

Body:
```json
{
  "success": true,
  "message": "Anonymous session started",
  "data": {
    "accessToken": "jwt_access_token",
    "refreshToken": "jwt_refresh_token",
    "accessTokenExpiresAt": null,
    "isNewUser": true,
    "onboarding": {
      "nextStep": "verified_identity"
    }
  }
}
```

### 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 a `users` row with random anonymous profile details when this install id has not been seen before.
- Creates or resolves a `user_identities` row with provider `anonymous`.
- Creates backend access and refresh tokens.

## Idempotency and Retries
- Idempotent: `conditionally`
- Retry guidance: safe to retry with the same install device id. Reusing the same id returns the same anonymous backend identity.

## Security and Abuse Controls
- Anonymous sessions are still backend users. They are subject to the same authenticated route authorization, duplicate-vote rules, rate limits, reporting, and abuse controls as other backend sessions.
- Anonymous sessions do not satisfy full-profile or hub membership gates.