# Provider Integration Hardening Notes

Use these checks when reviewing async HTTP/provider resolver code (debrid, payments, media APIs, webhooks, external SaaS clients).

## Retry safety

- Do not apply one retry policy to all methods.
- Retry safe/idempotent reads (`GET`, `HEAD`, `OPTIONS`) for transient network errors and 502/503/504.
- Treat side-effecting `POST` timeouts as ambiguous: the provider may have processed the request already. Retry only when the endpoint is documented idempotent, has an idempotency key, or duplicate creation is harmless and deduplicated by provider/hash.
- Prefer bounded backoff/jitter for production load; avoid tight retry loops.

## Credential leakage

- Query-param credentials (`apikey`, `token`, `access_token`, etc.) can leak through request URLs in logs, traces, and exception chains.
- Prefer provider-supported auth headers.
- If query auth is unavoidable, ensure exceptions returned/logged by app code do not chain raw client exceptions that carry request URLs, or redact URLs centrally.
- Tests should simulate a request error with a credential-bearing request and assert user-visible errors/logged messages do not include the credential.

## Returned URL safety

- Validate provider-returned playback/webhook/download URLs before handing them to clients.
- For playable stream URLs, prefer HTTPS-only; reject relative URLs, script/file/ftp schemes, protocol-relative URLs, and embedded username/password.
- If internal/private hosts are a threat for a specific app, add explicit SSRF-style host/IP guards.

## Provider payload bounds and sanitization

- Provider-controlled filenames/titles should be normalized before response/log use:
  - strip control characters
  - collapse paths to basename
  - reject `.` and `..`
  - cap length (e.g. 255 chars)
  - default empty/non-string names to `unknown`
- Numeric fields should reject negative, non-finite, and absurdly large values.
- In per-file result loops, skip malformed items rather than failing the entire resolve when other valid files exist.
- Cap fan-out over provider-returned lists (e.g. first 50 items) before making per-item network calls.

## Data integrity for account/list APIs

- When a provider create/upload call is followed by a broad list endpoint (`mylist`, `browse`, `items`), filter list results back to the created id and/or requested hash/source.
- Do not return unrelated stale account resources for the current resolve request.
- Add tests where the list contains an unrelated item before the expected item.

## Account auto-selection

- If auto-selecting an external-provider account, skip providers with no registered resolver/client instead of failing on the first stored account when a later usable account exists.
- Preserve explicit-account semantics: explicit account ownership should still be verified and should not silently switch accounts.