Flights/api_docs/stafftraveler_findings.md

# StaffTraveler — complete findings

Single source of truth for the StaffTraveler reverse-engineering effort. Verified by HTTP captures, Firestore REST probes, and Hermes bytecode analysis against the live `stafftraveler-prod` Firebase project. Raw artifacts in `stafftraveler_captures/`.

Source app: `com.stafftraveler.webview` v3.12.0 (build 1880000346), iOS UA `stafftraveler/560 CFNetwork/3860.500.112 Darwin/25.4.0`. Web client at `https://app.stafftraveler.com` (same Firebase project, same Firestore rules — used for inspection because it sends the long-poll fallback transport instead of gRPC).

## TL;DR for the iOS Flights integration

To show flight loads inside our app:

1. Add a secondary `FirebaseApp` named e.g. `StaffTravelerFirebaseApp` configured with the **web** API key + GMPID below.
2. Sign in as the user with Firebase Auth (email/password) → store refresh token in Keychain.
3. To search routes, `POST https://api.stafftraveler.com/v1/commands/user/searchFlightsByRoute` with the Bearer ID token.
4. To **unlock** loads on a flight, `POST .../createLoadsRequests` with the flight object + `isPriorityRequest: false` — costs **1 credit per new flight**, idempotent on replay.
5. After unlock, attach a Firestore snapshot listener on `derivedLoadsReports.where("flightId", "==", flightIdV3).order("createdAt", desc)` to receive live load updates.
6. Optional surface for "what's happening on my own airline": query `trackedFlights.where("scheduledFlight.airlineStCode", "==", userStCode)` to see flights other employees on the same airline have requested.

You **cannot** show real load numbers for a flight without first calling `createLoadsRequests` on that specific flight. There is no bulk/peek endpoint — verified extensively (see "Security model").

---

## Architecture

React Native + Hermes bytecode iOS/Android app with a thin native shell. All business logic in `assets/index.android.bundle`. Backend is Firebase:

| Component | Service |
|-----------|---------|
| Auth | Firebase Auth (email/password, Google, Apple, Facebook) |
| Real-time data | Cloud Firestore (`stafftraveler-prod`) |
| Mutations | Custom HTTP commands API at `api.stafftraveler.com/v1/commands/user/<name>` (likely Cloud Functions) |
| Config | Firebase Remote Config (controls API base URL, Typesense host/key, feature flags) |
| Search index | Typesense (`enhk2ji1vu6csxzrp-1.a1.typesense.net`) — server-side, not hit directly by the client |
| Push | FCM / APNs |
| Static CDN | `images.stafftraveler.com` |

No SSL pinning. No App Check enforcement (Play Integrity classes are bundled but the `createFirebaseCommand` fetch doesn't attach an `X-Firebase-AppCheck` header, and the web client makes every request with just the ID token).

## Firebase project config

From APK `res/values/strings.xml` and the web client's IndexedDB:

| Key | Value |
|-----|-------|
| Project ID | `stafftraveler-prod` |
| **Web API key** (the one that works for REST) | `AIzaSyD82Hiqx-jAbHF8faMGSveqLw8CdX8a-Uc` |
| Web App ID / GMPID | `1:628258099825:web:35b20eaab4d441894041d0` |
| Android API key | `AIzaSyC2zG6ArnguzzdWsLYV1qjQznma0zl1Q0s` (locked to the signed APK) |
| Android App ID | `1:628258099825:android:5fb976ba6ad1bb05` |
| Sender ID | `628258099825` |
| Firestore | `(default)` database |
| RTDB | `https://stafftraveler-prod.firebaseio.com` (registered but unused for loads) |
| Storage | `stafftraveler-prod.appspot.com` |

For an iOS integration, register a new web/iOS app in the same Firebase console — but the existing web app credentials above are sufficient for direct REST and the web SDK in our app.

## Auth

```
POST https://identitytoolkit.googleapis.com/v1/accounts:signInWithPassword?key=<web-key>
Content-Type: application/json
{ "email": "...", "password": "...", "returnSecureToken": true }
→ { idToken, refreshToken, expiresIn: "3600", localId: <uid>, ... }
```

The ID token is a 1-hour JWT; refresh via `securetoken.googleapis.com/v1/token?key=<web-key>` with `grant_type=refresh_token&refresh_token=...`. The Firebase SDK does this transparently.

Token claims include `email`, `user_id`, `is_registered`. Issuer `https://securetoken.google.com/stafftraveler-prod`, audience `stafftraveler-prod`.

## HTTP commands API

```
POST https://api.stafftraveler.com/v1/commands/user/<commandName>
Authorization: Bearer <firebase id token>
Content-Type: application/json
x-stafftraveler-client: mobile          ← the iOS app sends this; web sends "web". Probably not enforced.
{ ... command-specific body ... }
```

Response: `{ payload: <result> }` on success, `{ isError: true, payload: <message> }` on validation/business errors. Both come back HTTP 200; check the `isError` flag.

`api_commands_url` is fetched from Remote Config at startup. The deployed value is `https://api.stafftraveler.com/v1/commands/user`. The bundle disassembly confirms there is no other path prefix — tested `/public/`, `/internal/`, `/admin/`, `/v2/`, `/flights/`, `/loads/`, `/system/`, `/airline/` → all 404.

Also exposed on the same host: `GET /health` → `{message:"ok", serverTime:...}`.

### Command inventory (all 34, via `createFirebaseCommand` enumeration)

**Reads (free, idempotent):**
- `searchFlightsByRoute` — flight schedule by origin/destination/date
- `searchFlightsByCode` — flight schedule by flight number
- `appActive` — heartbeat; needs `{localDateIso, appType}`; returns `{payload: null}`
- `mobile` — stub, returns `"not implemented"`

**Mutations (most of these spend credits or modify account state):**

```
addAirlineDetails       addCreditsForPurchase   addComment              addIdentity
appLogout               createLoadsRequests     createTip               deleteLoadsRequest
deleteUserAccount       disableAllAutoRequestSubscriptions
disableFlightStatusUpdates  enableFlightStatusUpdates  discardHint
flagLoadsReport         omitIdentity            pinFlight               unpinFlight
registerUser            removeComment           reportComment
reopenLoadsRequest      reviseLoadsReport       requestLockForLoadsRequest
unlockLoadsRequest      setAutoRequestSubscription  submitFeedback
submitLoadsReport       unlikeTip               updateUserProfile       upgradeLoadsRequest
```

### `searchFlightsByRoute` — confirmed payload

```json
{
  "originIata": "DFW",
  "destinationIata": "LAS",
  "dates": ["2026-04-22"],
  "maxConnections": 0,
  "allowNearbyDepartures": false,
  "allowNearbyArrivals": false,
  "payloadType": "passenger",
  "includeMultipleCarriers": false
}
```

Response: `{ payload: { directFlights: [...], connectingFlights: [...], numberOfDiscardedFlights, settingsFilteredCount, messages } }`.

Flight object fields:
```
id, id_v2, id_v3 (= "AA_2178_DFW_2026_04_22"),
airlineId, airlineStCode, flightCode, flightNumber,
departureAirportId, departureAirportIata, arrivalAirportId, arrivalAirportIata,
departureTimeLocal, departureTimeUtc, arrivalTimeLocal, arrivalTimeUtc,
durationMinutes, isCargoFlight,
flightEquipmentId, flightEquipmentIata,
seatsTotal, seatsByClass: { first, business, premiumEconomy, economy }
```

`id_v3` format is `{airlineId}_{flightNumber}_{departureIata}_{YYYY}_{MM}_{DD}`. **This is the key used everywhere downstream** (Firestore docs, command bodies, etc).

`seatsByClass` is the **aircraft cabin configuration**, NOT current availability — that's a separate Firestore lookup.

### `createLoadsRequests` — confirmed payload

Body is a **bare JSON array** (no outer wrapper) of full flight objects, each with one extra field `isPriorityRequest: bool`:

```json
[
  { ...full flight from search response..., "isPriorityRequest": false }
]
```

Response:
```json
{
  "payload": {
    "numberOfRequests": 0,
    "numberOfRequestsPaidFor": 0,
    "numberOfRequestsPaidForPriority": 0,
    "hasSufficientCredits": true,
    "verifiedRequests": [
      {
        "flightId": "AA_2178_DFW_2026_04_22",
        "isExisting": true,
        "isDuplicateForUser": true,
        "isRequestUpdateForUser": false,
        "hasDeparted": false,
        "isCancelled": false,
        "isPriorityRequest": false,
        "hasRecentLoads": false,        ← summary flag; actual loads come from Firestore
        "scheduledFlight": { ... full flight ... }
      }
    ]
  }
}
```

**Idempotency:** Replaying the same flight returns `numberOfRequests: 0` + `isDuplicateForUser: true` + **no credit charged**. Useful as a "what's the current state" probe — pay for the first call only, then replay free.

## Firestore — the data plane

REST endpoint: `https://firestore.googleapis.com/v1/projects/stafftraveler-prod/databases/(default)/documents`

**Required headers on every read:**
```
Authorization: Bearer <firebase id token>
X-Firebase-GMPID: 1:628258099825:web:35b20eaab4d441894041d0
?key=AIzaSyD82Hiqx-jAbHF8faMGSveqLw8CdX8a-Uc       (URL query)
```

Omitting `?key=` or the GMPID gives `403 PERMISSION_DENIED` even with a valid token — the project-consumer context is required.

**Why mobile mitm couldn't see this:** the iOS Firebase SDK uses gRPC over HTTP/2 to `firestore.googleapis.com`. Many proxies show those streams as opaque binary frames. The web client uses the long-poll fallback (`Listen/channel?VER=8&TYPE=xmlhttp`) with URL-encoded JSON bodies — fully decodable. That's why the answer only fell out via the browser.

### Loads — `derivedLoadsReports`

The single most important query for the integration:

```json
POST documents:runQuery
{
  "structuredQuery": {
    "from": [{"collectionId": "derivedLoadsReports"}],
    "where": {
      "fieldFilter": {
        "field": {"fieldPath": "flightId"},
        "op": "EQUAL",
        "value": {"stringValue": "AA_2178_DFW_2026_04_22"}
      }
    },
    "orderBy": [
      {"field": {"fieldPath": "createdAt"}, "direction": "DESCENDING"},
      {"field": {"fieldPath": "__name__"}, "direction": "DESCENDING"}
    ]
  }
}
```

Doc shape (verified live capture, AA2178 2026-04-22):

```json
{
  "flightId": "AA_2178_DFW_2026_04_22",
  "openSeats": {
    "first":  { "count": 3 },
    "eco":    { "count": 9 }
    // also: business, premiumEconomy. Absent class = 0/unknown.
  },
  "staffListing": {
    "type": "available",         // also: "upgrade" variants per checkForLoads heuristic
    "count": 6,                  // # standby/listed non-rev passengers
    "countByClass": {}
  },
  "responseTimeSeconds": 196,
  "numberOfCreditsRewarded": 1,
  "isFlagged": false,
  "isFlaggedConfirmed": false,
  "seatsAvailabilityScore": 0.79,   // 0-1; app uses for color coding
  "hasClosedRequest": true,
  "isJackpotHit": false,
  "isPriorityRequest": false,
  "createdAt": "2026-04-22T18:42:51.313Z",
  "expireAt":  "2026-07-21T21:45:00Z",   // ~90 days
  "creatorName": "M",                    // first letter only (privacy)
  "creatorImageUrl": "https://images.stafftraveler.com/avatars/happysuitcase.png",
  "creatorImagePath": "avatars/happysuitcase.png"
}
```

### `trackedFlights` — request state

One doc per (flight, anyone-who-requested-it). Doc ID = `id_v3` of the flight. Key fields:

```
scheduledFlight: { full flight object — same shape as searchFlightsByRoute }
status: "open" | "closed"
createdBy: <uid of original requester>
createdAt, statusChangedAt, expireAt
priority: integer
priorityElevatedAt
isPriorityRequest, isAutoRequest, isLocked, isCancelled, isDeleted, isDelayed, isDiverted
hasDeparted, hasArrived, hasBeenRefunded
lockedBy, lockedAt                           ← while a reporter is filling it in
loadsUpdateRequestedBy
currentLoadsReportId                         ← doc ID into derivedLoadsReports
seatsAvailabilityScore                       ← summary score (also in derivedLoadsReports)
reportAuthorList: [<uid>]                    ← who has reported on this flight
reportAuthors: { <uid>: true, ... }
subscribedUsers: { <uid>: true, ... }        ← all users tracking this flight
subscribedUserList: [<uid>]
statusUpdatesSubscribedUserIds: [<uid>]
usersRequestingLoads: { <uid>: <ts>, ... }   ← users currently requesting an update
usersRequestingPriority: { ... }
usersEligibleForRefund: { <uid>: 1, ... }
sita: { ... rich live SITA flight record (gate, registration, flight times, marketing carriers, etc) ... }
__checksums: { typesense: "..." }
```

### Other Firestore listeners the web client opens (captured)

From the live `Listen/channel` body capture in `firestore_listen_targets_and_queries.txt`:

| Target | Use |
|--------|-----|
| `users/{uid}` | profile |
| `userHints/{uid}`, `userRequestCounters/{uid}`, `userPriorityRequestCounters/{uid}`, `userCredits/{uid}`, `userAchievements/{uid}`, `userMetrics/{uid}`, `userFlightSearchHistory/{uid}` | per-user state |
| `airportsByIata/{IATA}` | airport metadata |
| `airlinesBySt/{stCode}` | airline metadata by ST code |
| `airlineNotesBySt/{stCode}` | non-rev policy notes |
| `flightEquipment/{type}` | aircraft type info |
| `conversations/{flightId_v3}` | per-flight comment thread |
| `users/{uid}/pinnedFlights` (subcoll. query) | pinned flights |
| `users/{uid}/connectingFlights` (subcoll. query) | connecting flight definitions |
| `trackedFlights/{flightId_v3}/statusUpdates` (subcoll. query) | flight status change feed |
| `trackedFlights` query | see "Security model" — airline-scoped |
| `autoRequestRecords` query filtered by `subscribedUserIds ARRAY_CONTAINS uid` AND `isActive == true` | user's auto-subscriptions |

## Security model (the load-data unlock)

This is the constraint that defines the integration shape. Verified by exhaustive probing.

**Rules summary** (inferred from observed access pattern):

| Collection | Rule (effective) |
|------------|------------------|
| `__system/*`, `__derived/nonRevAgreementsBySt`, `airlines/*`, `airlinesBySt/*`, `airportsByIata/*`, `airlineNotesBySt/*`, `flightEquipment/*`, `tips/*`, `autoRequestRecords/*`, `conversations/*` | Public read for any authenticated user |
| `users/{uid}`, `userCredits/{uid}`, all other `user*/{uid}` | Owner-only |
| `trackedFlights` query (`list`) | Allowed only when filtered by `scheduledFlight.airlineStCode == <user's own airline>` |
| `trackedFlights/{id}` direct read (`get`) | Allowed if same-airline OR createdBy == auth.uid |
| `trackedFlights/{id}/statusUpdates` subcollection | Allowed only if you own/created the flight |
| `derivedLoadsReports` query and direct-get | Allowed only if you have a matching `trackedFlights/{flightId}` where you're the creator/subscriber |
| `scheduledFlights/{id}`, `flightRecord/{id}`, `flights/{id}` | Denied for direct-get on any flight |

**Verified 2026-04-22:**
- AA2178 query (I have a request on it) → 200, returns the load doc.
- WN862 query (someone else's request, my airline) → 403.
- Direct GET on `derivedLoadsReports/dVb4zStjhITceArRgLBB` (WN862's load doc, ID extracted from the trackedFlight doc which IS readable as same-airline) → still 403. Same token, same headers. So knowing the doc ID is not a bypass.
- DL/AA/UA/JBU/etc trackedFlights queries → 403 across all 9 airlines tested.
- Same-airline trackedFlights query → 500+ historic WN flights returned (status=closed mostly), confirming the airline-scope leak.

**Net consequence:** there is no "peek" path. To see load numbers on a flight, you must spend a credit on it via `createLoadsRequests`. After that, both the trackedFlight and derivedLoadsReports become readable indefinitely (or until the flight expires ~90 days later), and snapshot listeners deliver new community-submitted reports for free.

The same-airline `trackedFlights` listing exposes one useful summary signal without paying: `seatsAvailabilityScore` (0–1) on flights other employees on your own airline have asked about. Coarse go/no-go indicator, no class-level breakdown.

## Public reference data worth caching

Pulled and saved to `stafftraveler_captures/`:

- **`__derived/nonRevAgreementsBySt`** (`nonRevAgreementsBySt.json`) — full interline matrix: 300 airlines, each with an array of airline ST codes they have non-rev agreements with. Useful for filtering search results to "airlines I can actually non-rev on" without us building this ourselves.
- **`airlinesBySt/*`** (`airlinesBySt_full.json`) — ST-code → airline directory.

Both stable, refresh occasionally.

## What the iOS app actually needs

Concrete integration plan:

1. **Secondary FirebaseApp** `StaffTravelerApp` configured with the web key + GMPID above. Initialize on first user-opt-in.
2. **Auth screen** — email/password login → store refresh token in Keychain. Surface "no StaffTraveler account? Sign up in the StaffTraveler app first" — `addAirlineDetails` verification has to happen there.
3. **Bridge user state** — read `users/{uid}` (gets `airlineStCode`, name) and `userCredits/{uid}` (gets balance). Display credit balance in our UI.
4. **Search**: `POST /v1/commands/user/searchFlightsByRoute`. Free.
5. **Flight row UI**: for each result, attach a Firestore snapshot listener on `derivedLoadsReports.where("flightId", "==", flightId_v3)`.
   - If the listener gets a doc → render loads inline.
   - If 403 → flight isn't unlocked yet; show a "Request loads (1 credit)" CTA.
6. **Request CTA** → `POST /v1/commands/user/createLoadsRequests` with the full flight + `isPriorityRequest: false`. Idempotent — surface "you already requested this" if `isDuplicateForUser: true`.
7. **Comments / status feed (optional)** — listeners on `conversations/{flightId}` and `trackedFlights/{flightId}/statusUpdates`.
8. **Token refresh** — let Firebase iOS SDK handle it. Don't try to do it manually.

Mutations to wire later if useful: `pinFlight`/`unpinFlight`, `setAutoRequestSubscription` (auto-poll a recurring route), `submitLoadsReport` (let the user contribute back if they're at the gate). Skip everything else.

## Captures (raw artifacts)

In `stafftraveler_captures/`:

- `searchFlightsByRoute_DFW-LAS_request.json` / `_response.json` — schedule API
- `createLoadsRequests_AA2178_request.json` / `_response.json` / `_response_headers.txt` — load-request API
- `derivedLoadsReports_AA2178_request.json` / `_response.json` — actual loads readout
- `firestore_listen_targets_and_queries.txt` — all `addTarget` bodies the web client opens in a session
- `nonRevAgreementsBySt.json` — interline matrix
- `airlinesBySt_full.json` — airline directory
- `firestore_schema.md`, `url_surface_crawl.md`, `README.md` — interim notes

## Things that are NOT possible

Documenting the dead ends so we don't relitigate:

- **Cross-airline load enumeration** — blocked by the `airlineStCode` filter on `trackedFlights` and the createdBy check on `derivedLoadsReports`. Tested across 9 airline codes.
- **Bulk peek at multiple flights' loads in one call** — no API. Each flight needs its own credit unlock.
- **Reading another user's `derivedLoadsReports` by knowing the doc ID** — rule evaluates the doc's `flightId` against your tracked flights. Direct-GET on a known foreign doc ID returns 403.
- **Spoofing airline membership** — token claims are server-issued; `setAirlineStCodes` is a real command but changing your airline would affect the user's actual account.
- **Anonymous Firebase Auth on this project** — the Android API key is restricted to the signed APK package + cert SHA1. The web key is unrestricted on `signInWithPassword` but you still need real credentials.
- **App Check bypass** — moot; not enforced in practice.