# Proxy Route Flow (`src/routes/proxy.ts`)

This document explains how proxy requests move through the backend when calling:

- `/proxy/by-id/:integrationId/{*path}`
- `/proxy/encrypted/:integrationId/{*path}`

Both endpoints let clients call third-party provider APIs (Google, Notion, etc.) through our backend while enforcing ownership checks, path restrictions, and token handling.

## High-level architecture

`src/routes/proxy.ts` is the HTTP entrypoint. It:

1. Authenticates the user via JWT
2. Applies per-user rate limiting (100 requests/minute)
3. Normalizes request params, headers, and query
4. Delegates to controller logic:
   - non-encrypted flow: `forwardByIntegrationId(...)`
   - encrypted flow: `forwardWithEncryptedTokens(...)`
5. Returns upstream status/body with a safe subset of headers

## Shared route behavior

Both routes in `src/routes/proxy.ts` share these behaviors:

- `authenticateJWT` middleware requires a valid bearer token.
- `proxyRateLimit` limits calls by authenticated user ID (falls back to IP).
- `integrationId` is validated for presence in the route handler.
- wildcard `{*path}` is normalized into a leading-slash path (for example, `v1/users/me` -> `/v1/users/me`).
- query and headers are normalized into `Record<string, string>` using `toSingleValueRecord`.

## Flow A: `/proxy/by-id/:integrationId/{*path}` (standard token storage)

### Route layer (`src/routes/proxy.ts`)

1. Extracts `integrationId` and wildcard `path`.
2. Builds a `ProxyRequest` object:
   - `method`
   - `path`
   - normalized `query`
   - normalized `headers`
   - `body`
3. Calls `forwardByIntegrationId(integrationId, userId, request)`.
4. Sets returned headers and forwards status/data to the client.

### Controller layer (`src/controllers/proxy/forward.ts`)

`forwardByIntegrationId(...)`:

1. Validates ObjectId format.
2. Loads `OAuthIntegration` by ID.
3. Verifies integration ownership (`integration.user === userId`).
4. Delegates to `forward(provider, userId, request)`.

`forward(...)`:

1. Loads provider proxy config (`getProviderProxyConfig`).
2. Enforces max body size for non-GET requests.
3. Blocks sensitive provider paths using `blockedPaths`.
4. Loads the user's provider integration.
5. Runs provider-specific request validation via forwarder hook.
6. Resolves OAuth token refresh config from provider registry.
7. Gets a valid access token through `getValidAccessToken(...)` (auto-refresh when close to expiry).
8. Resolves final upstream base URL/path.
9. Builds outgoing headers:
   - `Accept: application/json`
   - provider auth header (for example, bearer token)
   - `Content-Type: application/json` for non-GET with body
   - provider-specific header overrides via forwarder hook
10. Sends upstream request with axios (30s timeout).
11. Converts upstream `401/403` into `NotAuthorizedError`.
12. Returns upstream response with safe headers only (`content-type`, `x-request-id`, `retry-after`).

## Flow B: `/proxy/encrypted/:integrationId/{*path}` (encrypted token storage)

This is the key-split flow for integrations saved in encrypted mode.

### Route layer (`src/routes/proxy.ts`)

1. Reads `X-Encryption-Key` header (required).
2. Parses it via `parseKeyFromString(...)` into client key share bytes.
3. Validates `integrationId` and normalizes path/query/headers/body.
4. Calls `forwardWithEncryptedTokens(integrationId, userId, clientKeyShare, request)`.
5. For success: forwards status/data and safe headers.
6. For errors:
   - derives `statusCode` from error object (default `500`)
   - returns `{ success: false, error }`
   - if status is `401` or `403`, also returns:
     - `authError: true`
     - `reconnectRequired: true`

### Controller layer (`src/controllers/proxy/forwardEncrypted.ts`)

`forwardWithEncryptedTokens(...)`:

1. Validates ObjectId format.
2. Loads integration and verifies ownership.
3. Ensures integration uses `encryptionMode === 'encrypted'`.
4. Loads provider config and applies body-size and blocked-path checks.
5. Runs provider-specific validation hook.
6. Resolves provider base URL and target URL.
7. Executes request with one auth retry loop:
   - fetches decrypted valid token via `getValidAccessTokenEncrypted(...)`
   - on retry, passes `forceRefresh = true`
   - builds provider headers and sends upstream request
   - if upstream returns `401` on first attempt, retries once after forced refresh
8. Returns upstream response (status, data, safe headers).
9. Maps network/timeout failures to `BadRequestError`.

## Token lifecycle differences

- Standard route (`/by-id`):
  - uses backend token cache/token manager flow (`getValidAccessToken`)
  - refreshes according to provider refresh configuration

- Encrypted route (`/encrypted`):
  - decrypts stored token material using client key share + server share
  - refreshes and then re-encrypts/persists updated tokens through encrypted token service
  - performs one forced-refresh retry after upstream `401`

## Security and safety controls

- JWT required for all proxy calls.
- Integration ownership enforced server-side.
- Per-user rate limiting applied before forwarding.
- Provider-specific blocked paths prevent unsafe endpoint forwarding.
- Request body size limits prevent large payload abuse.
- Only safe response headers are exposed back to clients.
- Encrypted route requires client key share header.

## Typical request sequence (encrypted flow)

1. Client sends request to `/proxy/encrypted/:integrationId/...` with:
   - bearer token
   - `X-Encryption-Key`
2. Route validates inputs and delegates to encrypted controller.
3. Controller validates integration + ownership + mode.
4. Token service decrypts and refreshes token if needed.
5. Backend forwards request to provider API.
6. If provider returns `401`, backend refreshes token and retries once.
7. Backend returns provider response (or structured error with reconnect hints).

## Files involved

- `src/routes/proxy.ts`
- `src/controllers/proxy/forward.ts`
- `src/controllers/proxy/forwardEncrypted.ts`
- `src/services/oauth/providers/tokenManager.ts`
- `src/services/oauth/encryptedTokenService.ts`
- `src/services/proxy/providerConfig.ts`
- `src/services/oauth/forwarder/*`