diff --git a/CHANGELOG.md b/CHANGELOG.md index 9cc45d7..d1183dd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,40 @@ # Changelog +## 0.3.0 + +- Added `fingerly.events.verify(request_id, max_age_seconds=300, tag=None, + consume=True)`, on `Fingerly` and `AsyncFingerly`, which reads an event and + checks it exists, is recent, carries the expected `tag`, is identifiable and + scored, then consumes it once, answering a `VerifyResult`; and + `fingerly.events.consume(request_id)`, answering a `ConsumeResult` or raising + `FingerlyEventAlreadyConsumedError` with `consumed_at`. +- Added `fingerly.device_check.query(request_id)` and + `fingerly.device_check.write(request_id, bit0=None, bit1=None)`, on + `Fingerly` and `AsyncFingerly`, which spend the DeviceCheck token held for + an iOS event to read or set the device's two bits. Answers are + `DeviceCheckBits` and `DeviceCheckWriteResult`; errors raise + `FingerlyDeviceCheckError` with the API `code` and, on `apple_rejected`, + `apple_status`. A `503` or a transport failure is retried with the identical + request. +- Refreshed the vendored v3 OpenAPI and contract fixtures, removing retired + deferred supplement schemas and routes, and added `Event.reason`, + `Event.url_host`, `Event.url_path`, `Event.identifiable`, + `Event.parse_document()`, `EventDocument`, `Attestation`, and `SIGNAL_NAMES` + covering all v3 signals (`attestation_failed`, `attestation_downgrade`, + `device_inconsistent`, `report_incomplete`, `probe_errors`, + `fetch_metadata_missing`, `web_ticket_missing`, `web_ticket_invalid`, + `tampering`, `custom_root_ca`, `secondary_user_profile`), with `attest_skipped` and `downgrade` on + `Attestation`. +- Updated `FingerlyProxy` (ASGI and WSGI) to enforce the single-path + `proxy.md` relay contract: sanitize-and-restore validation of + `x-fingerly-sdk-platform`, rejection with HTTP `400` (`missing_origin`) when + both `Origin` and a valid `x-fingerly-sdk-platform` are absent (never + synthesising `x-fingerly-origin`), forwarding of `Sec-Fetch-*` and + `Sec-CH-UA-*` client metadata headers, optional cross-origin + `allowed_origins` CORS handling, and verbatim raw-byte forwarding. +- `FingerlyProxy` requires `proxy_key`, checks the browser's same-environment + public key on every request, and never sends a secret key upstream. + ## 0.2.0 - `Event.project_id` is the Fingerly project an event belongs to, on single diff --git a/README.md b/README.md index f0b9bc5..e4b8cfb 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,7 @@ Two clients share one API: `Fingerly` for synchronous code such as Django and Fl **2. Install.** ```sh -pip install fingerly +pip install "fingerly>=0.3.0" ``` **3. Read an event.** @@ -98,7 +98,9 @@ Full documentation: [docs.fingerly.io/docs/sdks/python](https://docs.fingerly.io | I want to | Go to | | --- | --- | -| Read an event, or verify a backend action | [Read events](#read-events) | +| Read an event | [Read events](#read-events) | +| Verify and consume an event before a backend action | [Verify a backend action](#verify-a-backend-action) | +| Read or write an iOS device's DeviceCheck bits | [Read and write Apple DeviceCheck bits](#read-and-write-apple-devicecheck-bits) | | Check a webhook signature | [Verify webhooks](#verify-webhooks) | | Keep identification working behind content blockers | [First-party proxy](#first-party-proxy) | | Mount the proxy in FastAPI, Django or Flask | [Framework guides](#framework-guides) | @@ -107,6 +109,7 @@ Full documentation: [docs.fingerly.io/docs/sdks/python](https://docs.fingerly.io ## Contents - [Read events](#read-events) +- [Read and write Apple DeviceCheck bits](#read-and-write-apple-devicecheck-bits) - [Verify webhooks](#verify-webhooks) - [First-party proxy](#first-party-proxy) - [Framework guides](#framework-guides) @@ -121,7 +124,7 @@ Full documentation: [docs.fingerly.io/docs/sdks/python](https://docs.fingerly.io ## Read events -Event reads require `fly_sk_{production|staging|development}_…` keys. Requests go to `https://api.fingerly.io`; `endpoint` overrides that for a local API. Public, proxy, management, malformed and unsupported keys are rejected before network access. Requests do not follow redirects. `get` and `list` each perform one request and never retry. +Event reads require `fly_sk_{production|staging|development}_…` keys. Requests go to `https://api.fingerly.io`; `endpoint` overrides that for a local API. `endpoint` takes a scheme, a host and an optional port and nothing else: a path, query, fragment, credentials, space or control character is refused when the client is built. It must be `https`. Plain `http` is accepted only for `127.0.0.1`, `localhost` or `[::1]`, and only with `allow_insecure_loopback=True`, which is meant for local development and tests. Public, proxy, management, malformed and unsupported keys are rejected before network access. Requests do not follow redirects. `get` and `list` each perform one request and never retry. | | `Fingerly` | `AsyncFingerly` | | --- | --- | --- | @@ -141,12 +144,14 @@ Send the `requestId` the browser SDK returned to your server and read it there w | `event_pending` | `FingerlyEventPendingError`, a `FingerlyAPIError` | The request id was accepted but its event is not recorded yet. It is not a verdict. Try again after `retry_after` seconds, or verify asynchronously, for example from a webhook. The SDK never retries on its own. | | `event_not_found` | a plain `FingerlyAPIError` | The request id was never issued for this key's environment, or the event is past the 30-day retention. | -The archived `document` arrives moments after the event itself, so check `has_document` rather than assuming it is there. +The archived `document` arrives moments after the event itself, so check `has_document` rather than assuming it is there, and call `event.parse_document()` when you want a typed `EventDocument`. ### Event fields - `ip_network` is the network the request came from (an IPv4 /24 or an IPv6 /40, such as `203.0.113.0/24`); the API never returns the address. -- `document`, when available, is an allow-listed view of the archived request with no raw signals, user agent or address. +- When a submission is unidentifiable (`event.identifiable is False`, such as insufficient entropy, a genuine embedded WebView, or an unmatched high-risk Web payload), `event.visitor_id` is `""`. There are no `deferred_token`, `deferred_signals` or `supplements` fields in `v: 3`. +- `document`, when available, is an allow-listed view of the archived request with no raw signals, user agent or address. `event.parse_document()` decodes it into a typed `EventDocument` (including `attestation: Optional[Attestation]`). A native `Attestation` also carries `attest_skipped` (the app's reason for sending no proof) and `downgrade` (the report named an install an attested device owns). +- `SIGNAL_NAMES` lists the canonical signal identifiers, including the `v: 3` anti-spoofing and integrity signals `"attestation_failed"`, `"attestation_downgrade"`, `"device_inconsistent"`, `"report_incomplete"`, `"probe_errors"`, `"fetch_metadata_missing"`, `"web_ticket_missing"`, `"web_ticket_invalid"`, `"tampering"`, `"custom_root_ca"` and `"secondary_user_profile"`. - `suspect_score` is `None` when the request was not scored, and must not be treated as zero. - `project_id` is the UUID string of the Fingerly project the event belongs to, on both `events.get` and the rows of `events.list`; it is `None` when an older server does not send it. - `Event` declares every documented field as an attribute and falls back to the decoded body for fields added later, so a new server field needs no SDK upgrade. @@ -157,7 +162,73 @@ The archived `document` arrives moments after the event itself, so check `has_do ### Verify a backend action -Read the event with a server-only key. Check that its tag matches your action, that it is recent, that its environment is correct, and that it was scored. Apply your own policy to the server's verdict. Do not authorize an action using scores or visitor identifiers supplied by the browser. Tags correlate events; they do not replace your application's authentication or replay protection. A tag must never hold a personal identifier, such as a user ID, email, install ID or advertising ID, because the server keeps tags in long-lived rollups. A `FingerlyEventPendingError` means the server has not decided yet: retry after `retry_after` seconds or verify asynchronously, and do not refuse the action as fraud on that answer alone. The framework guides below answer it with `503` and `Retry-After`. +Send the browser's `requestId` to your server and verify it there with a server-only key. `fingerly.events.verify` reads the event and runs these checks in order, stopping at the first that fails: + +| Order | Reason | Fails when | +| --- | --- | --- | +| 1 | `not_found` | The event does not exist for this key's environment. | +| 2 | `too_old` | It occurred more than `max_age_seconds` ago (300 by default). A missing or unreadable `occurred_at` fails too. | +| 3 | `tag_mismatch` | You passed `tag` and the event's tag is not exactly that. | +| 4 | `unidentifiable` | The event has no visitor id. | +| 5 | `unscored` | The event has no `suspect_score`. | +| 6 | `already_consumed` | The event was consumed before. | + +Consumption comes last, only when every other check passed, so one event backs one decision: a replayed `requestId` answers `already_consumed`. Pass `consume=False` to check without consuming. The result is a `VerifyResult` with `ok`, `reason` (`""` when `ok`) and `event` (`None` only for `not_found`). + +`verify` never judges the score: that policy stays with you. Check `suspect_level` or `suspect_score` after `ok`. + +```python +result = fingerly.events.verify(request_id, tag="checkout") +if not result.ok: + refuse(result.reason) +elif result.event.suspect_level == "high": + send_to_review(result.event) +else: + allow() +``` + +`AsyncFingerly` has the same call as a coroutine. An invalid option (a `max_age_seconds` that is not a positive integer, an empty `tag`) raises `TypeError` before anything is sent. `fingerly.events.consume(request_id)` consumes an event on its own: the first call answers a `ConsumeResult` with `first=True`, and every later one raises `FingerlyEventAlreadyConsumedError`, a `FingerlyAPIError` whose `consumed_at` says when. Neither call is retried. + +Do not authorize an action using scores or visitor identifiers supplied by the browser. Tags correlate events; they do not replace your application's authentication. A tag must never hold a personal identifier, such as a user ID, email, install ID or advertising ID, because the server keeps tags in long-lived rollups. `verify` raises every error other than `event_not_found` and `event_already_consumed`. A `FingerlyEventPendingError` means the server has not decided yet: retry after `retry_after` seconds or verify asynchronously, and do not refuse the action as fraud on that answer alone. The framework guides below answer it with `503` and `Retry-After`. + +## Read and write Apple DeviceCheck bits + +For an iOS identification whose App Attest evidence carried a DeviceCheck token, Fingerly holds the token for one hour, and a secret key of the same project and environment can spend it once: to read the device's two bits from Apple, or to set them. The bits mean what you decide; Fingerly never stores or reads them. + +Apple treats a DeviceCheck token as single-use, so a read and a write each need their own identification. A once-per-device free trial takes two: + +1. Query on the identification that asks for the trial. If the bit says the device already had one, refuse it. +2. Otherwise grant the trial and record the grant in your own data. +3. Write the bit on the next identification from that install. Until the write lands, your own record of the grant is what stops a second trial. + +```python +from fingerly import FingerlyDeviceCheckError + +# The identification that asks for the trial. +try: + bits = fingerly.device_check.query(request_id) + used_on_device = bits.found and bits.bit0 +except FingerlyDeviceCheckError as error: + if error.code not in ("device_check_not_held", "device_check_spent"): + raise + used_on_device = False # no answer, not a verdict + +# The next identification, after you recorded the grant. +fingerly.device_check.write(next_request_id, bit0=True) +``` + +`AsyncFingerly` has the same calls as coroutines. `write` sends only the bits you name; naming neither raises `TypeError` before anything is sent. + +Every non-2xx answer raises `FingerlyDeviceCheckError` (a `FingerlyAPIError`); branch on `code`: + +| Status | `code` | +| --- | --- | +| `404` | `device_check_not_held` | +| `409` | `device_check_spent`, `device_check_busy` or `credential_unavailable` | +| `422` | `bits_required` or `apple_rejected` (with Apple's HTTP status in `apple_status`) | +| `503` | `device_check_unavailable` | + +A `503` or a transport failure leaves the token held, and the SDK retries the identical request, at most twice. A held token kept for a retry accepts only the request it was first used for: a retry with the other operation or other bits answers `409 device_check_spent`. No other answer is retried. ## Verify webhooks @@ -208,22 +279,29 @@ The [framework guides](#framework-guides) show each in full. ### What the proxy does -The browser SDK posts both of its calls, the identification and the report that follows it, to that one path. The proxy forwards each, as it is, to Fingerly's one ingest URL, `https://api.fingerly.io/api/v1/ingest`, and to nothing else. A path other than the configured one gets `404`, and any method but `POST` gets `405`. Event reads need a secret key and stay unreachable from a browser by construction. +Browser and proxied native client SDKs post a single `v: 3` identification envelope to that one path. The proxy forwards its raw request body bytes verbatim (without JSON decoding or re-serialising) to Fingerly's one ingest URL, `https://api.fingerly.io/api/v1/ingest`, and to nothing else. Event reads need a secret key and stay unreachable from a browser by construction. | Situation | Answer | | --- | --- | -| Path other than the configured one | `404` | -| Method other than `POST` | `405` | -| Public key from a different environment than the proxy key | `401` | +| Path other than the configured one (`/supplement` subpaths included) | `404` | +| Method other than `POST` (plus `OPTIONS` when `allowed_origins` is configured), matched exactly, so `post` gets `405` too | `405` | +| No public key from the same environment as the proxy key | `401`, nothing forwarded | +| Neither `Origin` nor a validated `x-fingerly-sdk-platform` | `400` (`missing_origin`) | | Body over 1 MiB (enforced while streaming rather than after buffering) | `413` | | WSGI body the server cannot read, such as broken chunked framing | `400` | | Fingerly cannot be reached in time | `504 Gateway timeout` | -| Any other upstream failure: a refused connection, a malformed or truncated response, or one over 4 MiB | `502 Bad gateway` | +| Any other upstream failure: a refused connection, a malformed or truncated response, one over 4 MiB, an upstream redirect or a status outside 200 to 599 | `502 Bad gateway` | | `client_ip` callback returns no valid address | `500` with the one line `The client IP callback returned no valid address` | -The browser must present a public key from the same environment as the proxy key, or the request gets `401`. Responses are marked `no-store`. The `504` and `502` answers are short plain text marked `no-store`, and each writes one line, with no stack trace, to the `fingerly.proxy` logger. +Responses are marked `no-store`. A redirect is never followed, whatever transport you supply. The `504` and `502` answers are short plain text marked `no-store`, and each writes one line, with no stack trace, to the `fingerly.proxy` logger. The line names the kind of failure only, never the upstream address or a key. -Only the content type, the visitor metadata Fingerly needs, and an `idempotency-key` are forwarded. Customer cookies and authorization headers are never passed on. The proxy reports itself upstream as `python/` in `x-fingerly-proxy-version`, which the dashboard shows per proxy, and sends `fingerly-python/` as its user agent. +### Keys and headers + +`proxy_key` is required, and a missing or malformed one fails when the proxy is built. The caller must present a public key (`fly_pk_…`) from the same environment as the proxy key, or the request gets `401` and nothing is forwarded. Upstream, the proxy sends that public key as `X-API-Key` and its own proxy key as `X-Fingerly-Proxy-Key`; a secret key is never part of the proxy. + +Incoming headers follow the sanitize-and-restore sequence: all incoming `x-fingerly-*`, `cookie` and `authorization` headers are stripped, restoring `x-fingerly-sdk-platform` only when it matches an exact lowercase native or bridge platform (`ios`, `android`, `react-native`, `react-native-ios`, `react-native-android`, `flutter`, `flutter-ios`, `flutter-android`, `lynx-ios`, `lynx-android`, `capacitor`, `kotlin-multiplatform`). Requests carrying neither `Origin` nor a validated `x-fingerly-sdk-platform` are rejected locally with `400` (`missing_origin`), and `x-fingerly-origin` is never synthesized from `Host`, `Referer` or the request URL. Exactly one channel goes upstream: a request with an `Origin` is forwarded as a browser call with `x-fingerly-origin` and without the platform header, as the API treats the same request sent to it directly. + +Alongside verified proxy metadata (`x-fingerly-host` included), only `content-type`, `x-api-key`, `user-agent`, `idempotency-key`, `sec-fetch-*` and `sec-ch-ua-*` are forwarded. Customer cookies and authorization headers are never passed on. The proxy reports itself upstream as `python/0.3.0` in `x-fingerly-proxy-version`, which the dashboard shows per proxy, and sends `fingerly-python/0.3.0` as its user agent. Back to the browser it relays only `content-type`, `x-request-id`, `ratelimit-limit`, `ratelimit-remaining` and `retry-after`, plus its own `cache-control: no-store` and a `content-length` for the decoded body. A content blocker can match a response header by name, so an allowlist is what keeps anything naming Fingerly off the page. @@ -252,6 +330,20 @@ Taking the application-relative path rather than the whole one is what makes a s The proxy opens its upstream connections on first use, one pool per standard. Close whichever you used when your app shuts down: `proxy.close()` for WSGI, `await proxy.aclose()` for ASGI. A WSGI process can simply exit. +### Testing against a local API + +`upstream` replaces the API origin for testing against a local API. It takes a scheme, a host and an optional port and nothing else: a path, query, fragment, credentials, space or control character is refused when the proxy is built. It must be `https`. Plain `http` is accepted only for `127.0.0.1`, `localhost` or `[::1]`, and only with `allow_insecure_loopback=True`, which is meant for local development and tests: + +```python +proxy = FingerlyProxy( + proxy_key=os.environ["FINGERLY_PROXY_KEY"], + path="/k7x2qm4a", + client_ip=lambda request: request.peer_host, + upstream="http://127.0.0.1:8080", + allow_insecure_loopback=True, +) +``` + ## Framework guides Each guide is a complete app. Replace `/k7x2qm4a` with the path the dashboard issued, and set `FINGERLY_SECRET_KEY` and `FINGERLY_PROXY_KEY`. The browser posts identifications to the proxy path and sends the `requestId` it gets back to `/verify/`, where your server reads the event with its secret key. @@ -313,7 +405,11 @@ async def verify(request_id: str, request: Request): raise HTTPException(503, headers={"Retry-After": retry_after}) from None except FingerlyAPIError as error: raise HTTPException(404 if error.status == 404 else 502) from None - return {"visitor_id": event.visitor_id, "suspect_score": event.suspect_score} + return { + "identifiable": event.identifiable, + "visitor_id": event.visitor_id, + "suspect_score": event.suspect_score, + } ``` @@ -407,7 +503,11 @@ def verify(request, request_id): status = 404 if error.status == 404 else 502 return JsonResponse({"error": error.code}, status=status) return JsonResponse( - {"visitor_id": event.visitor_id, "suspect_score": event.suspect_score} + { + "identifiable": event.identifiable, + "visitor_id": event.visitor_id, + "suspect_score": event.suspect_score, + } ) ``` @@ -465,7 +565,11 @@ def verify(request_id): return {"error": error.code}, 503, {"Retry-After": retry_after} except FingerlyAPIError as error: abort(404 if error.status == 404 else 502) - return {"visitor_id": event.visitor_id, "suspect_score": event.suspect_score} + return { + "identifiable": event.identifiable, + "visitor_id": event.visitor_id, + "suspect_score": event.suspect_score, + } ``` diff --git a/contract/manifest.json b/contract/manifest.json index 7303153..f5d8ba0 100644 --- a/contract/manifest.json +++ b/contract/manifest.json @@ -1,8 +1,8 @@ { "schema": 1, - "serverCommit": "e22f96777b0d029464baa4e127d7a346b684d478", + "serverCommit": "2f24510cfb9a41f780936841cc47ca8a1c012201", "files": { - "openapi.json": "850e7627dbbf1789fe7a0a214ae28838f2cd80d42e251f9994f5cb42d72e6009", + "openapi.json": "87c3881291f8a9cba673f2a62a3bad85f6ff7f8195c01efcae54f84f6887bd93", "fixtures.json": "3fbf2efbcf3c8ebced3d2c9f2a3c1f5752ee94ece63d5c110291d9a8251ff68f" } } diff --git a/contract/openapi.json b/contract/openapi.json index e1483dd..487d545 100644 --- a/contract/openapi.json +++ b/contract/openapi.json @@ -1,6 +1,80 @@ { "components": { "schemas": { + "AttestEnvelope": { + "properties": { + "assertion": { + "description": "Base64 CBOR App Attest assertion object", + "type": "string" + }, + "attestation_object": { + "description": "Base64 CBOR App Attest attestation object", + "type": "string" + }, + "certificate_chain": { + "description": "Base64 DER X.509 certificate chain for Android key registration", + "items": { + "type": "string" + }, + "type": "array" + }, + "challenge": { + "description": "Stateless server-signed challenge ticket", + "type": "string" + }, + "device_token": { + "description": "Optional standard Base64 Apple DeviceCheck token, at most 4 KiB decoded, bound into statementDigest. Held for one hour and spent by POST /events/{request_id}/device-check/query", + "type": "string" + }, + "device_token_write": { + "description": "Optional second standard Base64 Apple DeviceCheck token, at most 4 KiB decoded, bound into statementDigest. Held for one hour and spent by PUT /events/{request_id}/device-check", + "type": "string" + }, + "install_id": { + "description": "Canonical 36-char lowercase UUIDv4 matching sources.identity.value.install_id", + "type": "string" + }, + "key_id": { + "description": "Base64 App Attest key ID (iOS) or 64-char hex SPKI SHA-256 (Android)", + "type": "string" + }, + "mode": { + "description": "app_attest_register, app_attest_assert, android_key_register, or android_key_assert", + "type": "string" + }, + "play_integrity_token": { + "description": "Optional Google Play Integrity token with requestHash equal to hex(statementDigest)", + "type": "string" + }, + "prev_assertion": { + "description": "iOS, app_attest_register only: standard Base64 CBOR App Attest assertion by the previous confirmed key (prev_key_id) with clientDataHash equal to statementDigest", + "type": "string" + }, + "prev_key_id": { + "description": "Optional key ID of the previous confirmed key: 64-char hex (Android) or standard Base64 App Attest key ID (iOS, app_attest_register only)", + "type": "string" + }, + "prev_signature": { + "description": "Optional Base64 ASN.1 DER signature by retiring Android key over identical framedPreimage", + "type": "string" + }, + "reattest_attempt": { + "description": "Inline Android lease renewal attempt counter (0 or 1)", + "format": "int64", + "type": "integer" + }, + "signature": { + "description": "Base64 ASN.1 DER SHA256withECDSA signature over framedPreimage", + "type": "string" + } + }, + "required": [ + "challenge", + "install_id", + "mode" + ], + "type": "object" + }, "AttestationChallengeOut": { "properties": { "app_attest": { @@ -15,6 +89,10 @@ "description": "Whether to send a DeviceCheck token with the App Attest evidence", "type": "boolean" }, + "digest_salt": { + "description": "The project's 32-byte name digest salt, unpadded base64url. The SDK caches it per SDK key and sends each name digest as the first 16 bytes of HMAC-SHA256(salt, name) in hex, with digest_salt_id. Absent when the server has none to give; the SDK then uses 32 zero bytes", + "type": "string" + }, "expires_at": { "description": "When the nonce becomes unusable", "format": "date-time", @@ -436,10 +514,29 @@ }, "IdentifyIn": { "properties": { + "attest": { + "anyOf": [ + { + "$ref": "#/components/schemas/AttestEnvelope" + }, + { + "type": "null" + } + ], + "description": "Hardware attestation envelope bound to raw signals bytes (v3 native SDKs)" + }, + "attest_skipped": { + "description": "Native only, and only without attest: why the SDK sent no attestation. One of not_offered, unsupported, challenge_unavailable, key_error, timeout, backoff, install_unavailable. Diagnostic; it never lowers the score", + "type": "string" + }, "consent": { "description": "The SDK's consent state; must be granted, or the request is refused with consent_required", "type": "string" }, + "op": { + "description": "Empty for a report. ticket asks for a web freshness ticket instead: a public key on the web only, with a body of v, op and sdk, answered 200 with ticket and expires_at, never charged", + "type": "string" + }, "sdk": { "$ref": "#/components/schemas/SDKInfo", "description": "Which SDK collected these signals" @@ -450,30 +547,65 @@ "type": "object" }, "tag": { - "description": "An opaque value echoed back on the event and kept in long-lived rollups. A label for your own systems, such as a client or app name; never a personal identifier (user ID, email, install ID or advertising ID)", + "description": "An opaque value echoed back on the event and kept in long-lived rollups. A label for your own systems, such as a client or app name; never a personal identifier (user ID, email, install ID or advertising ID). A value holding a control character (U+0000 to U+001F, U+007F) is refused with invalid_request", "type": "string" + }, + "ticket": { + "description": "Web only: the freshness ticket from a ticket request or the previous answer's next_ticket. Single use, bound to the key and page origin, valid for 300 seconds. A native report carrying one is refused with invalid_request", + "type": "string" + }, + "ticket_pow": { + "description": "Web only, next to a ticket whose answer carried pow_bits: the smallest decimal nonce n, from 0 up, such that SHA-256(ticket || ':' || n) starts with at least pow_bits zero bits", + "type": "string" + }, + "v": { + "description": "Wire envelope version. Must equal 3.", + "format": "int64", + "type": "integer" } }, "type": "object" }, "IdentifyOut": { "properties": { - "app_attest_key": { - "description": "unknown when the report asserted with an App Attest key the server does not hold; the iOS SDK then attests a new key on its next collection. Absent otherwise", + "attest_key_id": { + "description": "Native only, present whenever attest was sent: the key_id the server evaluated, copied from attest.key_id", "type": "string" }, - "deferred_token": { - "description": "Short-lived capability for the deferred signal report", + "attest_key_status": { + "description": "Native only, present whenever attest was sent: registered (the key was verified, stored and owns the install), valid (an assertion verified against a stored key), rekey_required (the key is unknown or expired), rejected (attestation failed)", "type": "string" }, "duplicate": { - "description": "This submission was answered before; the verdict belongs to the first one", + "description": "This submission was answered before; the verdict replays the first one", "type": "boolean" }, "identifiable": { "description": "False when the report carried too little to identify anyone", "type": "boolean" }, + "next_attestation": { + "anyOf": [ + { + "$ref": "#/components/schemas/AttestationChallengeOut" + }, + { + "type": "null" + } + ], + "description": "Fresh attestation challenge ticket and dynamic offer flags for the next native submission" + }, + "next_ticket": { + "anyOf": [ + { + "$ref": "#/components/schemas/WebTicketOut" + }, + { + "type": "null" + } + ], + "description": "Web only: a fresh freshness ticket for the next report from this page, so it needs no ticket request" + }, "reason": { "description": "Why enrichment did not happen. Only answered to a secret key; a browser or app reads it on the server-side event read", "type": "string" @@ -511,7 +643,7 @@ "type": "integer" }, "visitor_id": { - "description": "Who this visitor is, stable across their visits", + "description": "Who this visitor is, stable across their visits; empty when unidentifiable", "type": "string" }, "visitor_is_new": { @@ -556,10 +688,29 @@ }, "IngestIn": { "properties": { + "attest": { + "anyOf": [ + { + "$ref": "#/components/schemas/AttestEnvelope" + }, + { + "type": "null" + } + ], + "description": "Hardware attestation envelope bound to raw signals bytes (v3 native SDKs)" + }, + "attest_skipped": { + "description": "Native only, and only without attest: why the SDK sent no attestation. One of not_offered, unsupported, challenge_unavailable, key_error, timeout, backoff, install_unavailable. Diagnostic; it never lowers the score", + "type": "string" + }, "consent": { "description": "The SDK's consent state; must be granted, or the request is refused with consent_required", "type": "string" }, + "op": { + "description": "Empty for a report. ticket asks for a web freshness ticket instead: a public key on the web only, with a body of v, op and sdk, answered 200 with ticket and expires_at, never charged", + "type": "string" + }, "sdk": { "$ref": "#/components/schemas/SDKInfo", "description": "Which SDK collected these signals" @@ -570,12 +721,21 @@ "type": "object" }, "tag": { - "description": "An opaque value echoed back on the event and kept in long-lived rollups; never a personal identifier. Identify only", + "description": "An opaque value echoed back on the event and kept in long-lived rollups; never a personal identifier. A value holding a control character (U+0000 to U+001F, U+007F) is refused with invalid_request", "type": "string" }, - "token": { - "description": "The deferred_token returned by identify. Present only on a deferred report", + "ticket": { + "description": "Web only: the freshness ticket from a ticket request or the previous answer's next_ticket. A native report carrying one is refused with invalid_request", "type": "string" + }, + "ticket_pow": { + "description": "Web only: the proof of work for a ticket whose answer carried pow_bits", + "type": "string" + }, + "v": { + "description": "Wire envelope version. Must equal 3.", + "format": "int64", + "type": "integer" } }, "type": "object" @@ -636,6 +796,41 @@ ], "type": "object" }, + "PrivateAccessTokenIssuerIn": { + "properties": { + "directory_url": { + "description": "Instead of token_key: the issuer's HTTPS directory, read for its current type 2 keys", + "type": "string" + }, + "issuer_name": { + "description": "The issuer's server name, host and optional port. Defaults to the directory URL's host", + "type": "string" + }, + "token_key": { + "description": "The issuer's token type 2 key, base64url: a DER SubjectPublicKeyInfo of a 2048-bit RSASSA-PSS key with SHA-384", + "type": "string" + } + }, + "type": "object" + }, + "PrivateAccessTokenIssuerOut": { + "properties": { + "directory_url": { + "type": "string" + }, + "issuer_name": { + "type": "string" + }, + "token_key": { + "description": "base64url, padded", + "type": "string" + } + }, + "required": [ + "issuer_name" + ], + "type": "object" + }, "ProjectArchivedOut": { "properties": { "archived": { @@ -948,6 +1143,29 @@ ], "type": "object" }, + "SDKEventConsumeOut": { + "properties": { + "consumed_at": { + "description": "When it was consumed, RFC 3339", + "format": "date-time", + "type": "string" + }, + "first": { + "description": "Always true: a later consume is answered 409 event_already_consumed", + "type": "boolean" + }, + "request_id": { + "description": "The event consumed", + "type": "string" + } + }, + "required": [ + "consumed_at", + "first", + "request_id" + ], + "type": "object" + }, "SDKEventOut": { "properties": { "agent": { @@ -965,6 +1183,14 @@ "asn_name": { "type": "string" }, + "consumed_at": { + "description": "When the event was first consumed with POST /events/{request_id}/consume. Absent while it has not been", + "format": "date-time", + "type": [ + "string", + "null" + ] + }, "country_code": { "type": "string" }, @@ -1183,6 +1409,21 @@ "description": "The human-readable stem, such as fly_pk_production", "type": "string" }, + "private_access_token_issuer": { + "anyOf": [ + { + "$ref": "#/components/schemas/PrivateAccessTokenIssuerOut" + }, + { + "type": "null" + } + ], + "description": "Prototype: the project's token issuer, on the answer to an origins update" + }, + "private_access_tokens": { + "description": "Prototype: whether a capable Safari is asked for a Private Access Token when the page requests a web ticket", + "type": "boolean" + }, "project_id": { "type": "string" }, @@ -1203,6 +1444,11 @@ "status": { "description": "active or revoked", "type": "string" + }, + "web_ticket_pow_bits": { + "description": "Proof of work, in leading zero bits, the key's web freshness tickets ask for; 0 is none", + "format": "int64", + "type": "integer" } }, "required": [ @@ -1218,9 +1464,11 @@ "last4", "name", "prefix", + "private_access_tokens", "project_id", "require_attestation", - "status" + "status", + "web_ticket_pow_bits" ], "type": "object" }, @@ -1341,21 +1589,6 @@ ], "type": "object" }, - "SupplementOut": { - "properties": { - "duplicate": { - "description": "The identical supplement was accepted before", - "type": "boolean" - }, - "request_id": { - "type": "string" - } - }, - "required": [ - "request_id" - ], - "type": "object" - }, "UsageDayOut": { "properties": { "billable": { @@ -1571,6 +1804,29 @@ ], "type": "object" }, + "WebTicketOut": { + "properties": { + "expires_at": { + "description": "When the ticket stops being accepted, RFC 3339 UTC", + "format": "date-time", + "type": "string" + }, + "pow_bits": { + "description": "Present when the key asks for proof of work: the leading zero bits ticket_pow must produce", + "format": "int64", + "type": "integer" + }, + "ticket": { + "description": "Unpadded base64url ticket, sent as ticket on the next report", + "type": "string" + } + }, + "required": [ + "expires_at", + "ticket" + ], + "type": "object" + }, "WebhookDeliveriesOut": { "properties": { "deliveries": { @@ -2075,10 +2331,10 @@ "x-title": "Get an event" } }, - "/api/v1/events/{request_id}/device-check": { - "put": { - "description": "Spends the DeviceCheck token held for this iOS event, once, to set bit0, bit1 or both with Apple, using your project's own Apple key. A bit left out keeps its value. The bits mean what you decide; Fingerly never reads them. Tokens are held for one hour, only for events whose App Attest evidence covered them, and only when DeviceCheck is switched on for the project's Apple credential.", - "operationId": "setDeviceDevicecheckBits", + "/api/v1/events/{request_id}/consume": { + "post": { + "description": "Marks one identification event as consumed, atomically and once per organization, so a request ID handed from a page to your backend backs one decision only. The first call answers `200` with `first: true`; every later call answers `409 event_already_consumed`, with the first consume's time in the error's `details` entry for the field `consumed_at`. Read and check the event before you consume it. The flag is kept with the event and erased with it.", + "operationId": "markEventConsumedOnce", "parameters": [ { "in": "path", @@ -2089,38 +2345,12 @@ } } ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "properties": { - "bit0": { - "description": "The value to set for the first bit. Leave out to keep it", - "type": [ - "boolean", - "null" - ] - }, - "bit1": { - "description": "The value to set for the second bit. Leave out to keep it", - "type": [ - "boolean", - "null" - ] - } - }, - "type": "object" - } - } - }, - "required": true - }, "responses": { "200": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DeviceCheckWriteOut" + "$ref": "#/components/schemas/SDKEventConsumeOut" } } }, @@ -2154,7 +2384,7 @@ } } }, - "description": "`device_check_not_held`: no token is held for that event" + "description": "`event_not_found`: no event with that request ID in this key's environment, or it is older than 30 days. `event_pending`: the identification is still being recorded; retry after the `Retry-After` seconds" }, "409": { "content": { @@ -2164,7 +2394,7 @@ } } }, - "description": "`device_check_spent`, `device_check_busy` or `credential_unavailable`" + "description": "`event_already_consumed`: consumed before; `details[0]` is `{\"field\": \"consumed_at\", \"issue\": \"\"}`" }, "422": { "content": { @@ -2174,7 +2404,7 @@ } } }, - "description": "`bits_required` or `apple_rejected`" + "description": "The request could not be validated." }, "503": { "content": { @@ -2184,7 +2414,7 @@ } } }, - "description": "`device_check_unavailable`: retry within the hour" + "description": "`events_unavailable`: retry after the `Retry-After` seconds" }, "default": { "content": { @@ -2202,18 +2432,18 @@ "secretKey": [] } ], - "summary": "Set the device's DeviceCheck bits", + "summary": "Mark an event consumed, once", "tags": [ "Server API" ], "x-category": "Server API", - "x-title": "Write an event's DeviceCheck bits" + "x-title": "Consume an event" } }, - "/api/v1/events/{request_id}/device-check/query": { - "post": { - "description": "Spends the DeviceCheck token held for this iOS event, once, to read the device's two bits from Apple. A token spent on a read cannot also write; to mark a device, write instead.", - "operationId": "readDeviceDevicecheckBits", + "/api/v1/events/{request_id}/device-check": { + "put": { + "description": "Spends the write DeviceCheck token held for this iOS event, once, to set bit0, bit1 or both with Apple, using your project's own Apple key. A bit left out keeps its value. The bits mean what you decide; Fingerly never reads them. Apple answers a write with no previous value; the event's read token, spent by the query route, is separate, so one identification supports one read and one write. Tokens are held for one hour, only for events whose App Attest evidence covered them, and only when DeviceCheck is switched on for the project's Apple credential. After a `503`, retry with the same bits: a token kept for a retry accepts only the request it was first used for.", + "operationId": "setDeviceDevicecheckBits", "parameters": [ { "in": "path", @@ -2224,12 +2454,38 @@ } } ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "bit0": { + "description": "The value to set for the first bit. Leave out to keep it", + "type": [ + "boolean", + "null" + ] + }, + "bit1": { + "description": "The value to set for the second bit. Leave out to keep it", + "type": [ + "boolean", + "null" + ] + } + }, + "type": "object" + } + } + }, + "required": true + }, "responses": { "200": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DeviceCheckQueryOut" + "$ref": "#/components/schemas/DeviceCheckWriteOut" } } }, @@ -2263,7 +2519,7 @@ } } }, - "description": "`device_check_not_held`: no token is held for that event" + "description": "`device_check_not_held`: no write token is held for that event" }, "409": { "content": { @@ -2273,7 +2529,7 @@ } } }, - "description": "`device_check_spent`, `device_check_busy` or `credential_unavailable`" + "description": "`device_check_spent`: already used, or a retry that is not the first request; `device_check_busy` or `credential_unavailable`" }, "422": { "content": { @@ -2283,7 +2539,7 @@ } } }, - "description": "The request could not be validated." + "description": "`bits_required` or `apple_rejected`" }, "503": { "content": { @@ -2311,18 +2567,18 @@ "secretKey": [] } ], - "summary": "Read the device's DeviceCheck bits", + "summary": "Set the device's DeviceCheck bits", "tags": [ "Server API" ], "x-category": "Server API", - "x-title": "Read an event's DeviceCheck bits" + "x-title": "Write an event's DeviceCheck bits" } }, - "/api/v1/events/{request_id}/supplement": { + "/api/v1/events/{request_id}/device-check/query": { "post": { - "description": "Attaches the signals a browser collects after its initial budget to an identification that has already been answered. It never changes the visitor, the score, billing or webhooks. The JavaScript SDK sends it automatically. Resending the same report is answered as a duplicate.", - "operationId": "submitDeferredReport", + "description": "Spends the read DeviceCheck token held for this iOS event, once, to read the device's two bits from Apple. Apple asks for each token to be used once, so the event holds a second token for the write route: to read and then mark a device, read and write on the same identification. After a `503`, retry the read: a token kept for a retry accepts only the request it was first used for.", + "operationId": "readDeviceDevicecheckBits", "parameters": [ { "in": "path", @@ -2333,45 +2589,16 @@ } } ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "properties": { - "consent": { - "description": "The SDK's consent state; must be granted, or the request is refused with consent_required", - "type": "string" - }, - "sdk": { - "$ref": "#/components/schemas/SDKInfo", - "description": "Which SDK collected these signals" - }, - "signals": { - "additionalProperties": {}, - "description": "A report containing only the deferred tier", - "type": "object" - }, - "token": { - "description": "The deferred_token returned by identify", - "type": "string" - } - }, - "type": "object" - } - } - }, - "required": true - }, "responses": { - "202": { + "200": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SupplementOut" + "$ref": "#/components/schemas/DeviceCheckQueryOut" } } }, - "description": "Accepted" + "description": "OK" }, "401": { "content": { @@ -2381,9 +2608,9 @@ } } }, - "description": "No usable x-api-key header was presented" + "description": "No usable secret SDK key was presented" }, - "402": { + "403": { "content": { "application/json": { "schema": { @@ -2391,7 +2618,17 @@ } } }, - "description": "The organization this key belongs to is not accepting traffic" + "description": "The organization is suspended or closed" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "`device_check_not_held`: no read token is held for that event" }, "409": { "content": { @@ -2401,7 +2638,7 @@ } } }, - "description": "A different deferred report was already accepted for this request" + "description": "`device_check_spent`: already used, or a retry that is not the first request; `device_check_busy` or `credential_unavailable`" }, "422": { "content": { @@ -2411,7 +2648,7 @@ } } }, - "description": "The request could not be validated." + "description": "`apple_rejected`: Apple rejected the token; `apple_status` says how" }, "503": { "content": { @@ -2421,7 +2658,7 @@ } } }, - "description": "The report could not be accepted just now" + "description": "`device_check_unavailable`: retry within the hour" }, "default": { "content": { @@ -2436,15 +2673,15 @@ }, "security": [ { - "publicKey": [] + "secretKey": [] } ], - "summary": "Submit a deferred report", + "summary": "Read the device's DeviceCheck bits", "tags": [ - "Client API" + "Server API" ], - "x-category": "Client API", - "x-title": "Submit a deferred report" + "x-category": "Server API", + "x-title": "Read an event's DeviceCheck bits" } }, "/api/v1/identify": { @@ -2492,6 +2729,16 @@ }, "description": "The organization this key belongs to is not accepting traffic" }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "The Idempotency-Key was reused with a different payload, or the original request is still in progress" + }, "413": { "content": { "application/json": { @@ -2561,7 +2808,7 @@ }, "/api/v1/ingest": { "post": { - "description": "The one URL the client SDKs and every first-party proxy post to. A body with a `token` is a deferred report and is answered `202` with `request_id` and `duplicate`, exactly as the deferred report route answers. Any other body is an identification and is answered `200` exactly as the identify route answers.\n\nIt exists so a proxy can forward everything it receives to a single path, and so the SDK can post both calls to one path of the customer's choosing, with nothing appended that a content blocker could match across sites.\n\nThe `X-Request-Id` response header names this HTTP exchange, for support and logs. It is not the `request_id` in the body, which names the identification and is what `GET /events/{request_id}` reads.", + "description": "The one URL the client SDKs and every first-party proxy post to. Forwards the single-pass v3 identification envelope and answers `200` with the verdict, exactly as the identify route answers.\n\nIt exists so a proxy can forward everything it receives to a single path of the customer's choosing, with nothing appended that a content blocker could match across sites. An `Idempotency-Key` header is required on every call.\n\nThe `X-Request-Id` response header names this HTTP exchange, for support and logs. It is not the `request_id` in the body, which names the identification and is what `GET /events/{request_id}` reads.", "operationId": "submitFromClientSdk", "requestBody": { "content": { @@ -2584,7 +2831,7 @@ }, "description": "OK" }, - "202": { + "401": { "content": { "application/json": { "schema": { @@ -2592,9 +2839,9 @@ } } }, - "description": "The deferred report was accepted" + "description": "No usable x-api-key header was presented" }, - "401": { + "402": { "content": { "application/json": { "schema": { @@ -2602,9 +2849,9 @@ } } }, - "description": "No usable x-api-key header was presented" + "description": "The organization this key belongs to is not accepting traffic" }, - "402": { + "409": { "content": { "application/json": { "schema": { @@ -2612,7 +2859,7 @@ } } }, - "description": "The organization this key belongs to is not accepting traffic" + "description": "The Idempotency-Key was reused with a different payload, or the original request is still in progress" }, "413": { "content": { @@ -5333,7 +5580,7 @@ "type": "array" }, "allowed_android_signers": { - "description": "SHA-256 signing certificate digests, 64 hex characters", + "description": "SHA-256 signing certificate digests, 64 hex characters (colon separators accepted). Required alongside allowed_android_packages in production or when require_attestation is true", "items": { "type": "string" }, @@ -5365,8 +5612,11 @@ ] }, "hide_client_score": { - "description": "Withhold suspect_score and suspect_level from a browser, an app, a proxy and a hosted domain. Defaults to false", - "type": "boolean" + "description": "Withhold suspect_score and suspect_level from a browser, an app, a proxy and a hosted domain. Defaults to true for a public key and false for a secret key", + "type": [ + "boolean", + "null" + ] }, "kind": { "description": "public or secret", @@ -5375,6 +5625,13 @@ "name": { "description": "What the key is called. The only part a person can recognise once the secret is masked", "type": "string" + }, + "require_attestation": { + "description": "Refuse native reports whose hardware attestation did not verify", + "type": [ + "boolean", + "null" + ] } }, "type": "object" @@ -5503,7 +5760,7 @@ "type": "array" }, "allowed_android_signers": { - "description": "SHA-256 signing certificate digests, 64 hex characters. Empty means not configured", + "description": "SHA-256 signing certificate digests, 64 hex characters (colon separators accepted). Required alongside allowed_android_packages in production or when require_attestation is true", "items": { "type": "string" }, @@ -5794,6 +6051,32 @@ "type": "string" }, "type": "array" + }, + "private_access_token_issuer": { + "anyOf": [ + { + "$ref": "#/components/schemas/PrivateAccessTokenIssuerIn" + }, + { + "type": "null" + } + ], + "description": "Prototype: the token issuer of the key's whole project. Leave out to keep it; send an empty object to clear it" + }, + "private_access_tokens": { + "description": "Prototype: ask Safari on iOS 16+ and macOS 13+ for a Private Access Token when the page requests a web ticket. Needs a public key in a project that names a token issuer. Leave out to keep the current setting", + "type": [ + "boolean", + "null" + ] + }, + "web_ticket_pow_bits": { + "description": "Proof of work the key's web freshness tickets ask for, 0 (off) to 22 leading zero bits. Leave out to keep the current setting", + "format": "int64", + "type": [ + "integer", + "null" + ] } }, "type": "object" diff --git a/src/fingerly/__init__.py b/src/fingerly/__init__.py index 86f19f0..e3e7c56 100644 --- a/src/fingerly/__init__.py +++ b/src/fingerly/__init__.py @@ -12,34 +12,67 @@ from __future__ import annotations -from ._client import AsyncEvents, AsyncFingerly, Events, Fingerly +from ._client import ( + AsyncDeviceCheck, + AsyncEvents, + AsyncFingerly, + DeviceCheck, + Events, + Fingerly, +) from ._errors import ( FingerlyAPIError, FingerlyConnectionError, + FingerlyDeviceCheckError, FingerlyError, + FingerlyEventAlreadyConsumedError, FingerlyEventPendingError, FingerlyTimeoutError, ) -from ._models import Event, EventPage, EventTrigger +from ._models import ( + SIGNAL_NAMES, + Attestation, + ConsumeResult, + DeviceCheckBits, + DeviceCheckWriteResult, + Event, + EventDocument, + EventPage, + EventTrigger, + VerifyReason, + VerifyResult, +) from ._proxy import FingerlyProxy, ProxyRequest from ._version import __version__ from ._webhooks import verify_webhook __all__ = [ + "SIGNAL_NAMES", + "AsyncDeviceCheck", "AsyncEvents", "AsyncFingerly", + "Attestation", + "ConsumeResult", + "DeviceCheck", + "DeviceCheckBits", + "DeviceCheckWriteResult", "Event", + "EventDocument", "EventPage", "EventTrigger", "Events", "Fingerly", "FingerlyAPIError", "FingerlyConnectionError", + "FingerlyDeviceCheckError", "FingerlyError", + "FingerlyEventAlreadyConsumedError", "FingerlyEventPendingError", "FingerlyProxy", "FingerlyTimeoutError", "ProxyRequest", + "VerifyReason", + "VerifyResult", "__version__", "verify_webhook", ] diff --git a/src/fingerly/_asgi.py b/src/fingerly/_asgi.py index a4f3245..c70ef3f 100644 --- a/src/fingerly/_asgi.py +++ b/src/fingerly/_asgi.py @@ -23,7 +23,7 @@ class ASGIProxy: - """ASGI application serving the browser SDK's same-origin requests. + """ASGI application relaying single-path raw-byte Fingerly ingest requests. Reached as ``proxy.asgi``. Route the dashboard-issued path to it under FastAPI, Starlette, Django 3+, Quart, Litestar or any other ASGI @@ -56,7 +56,7 @@ async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None: try: body = await _read_body(receive, self._proxy.max_body_bytes) except BodyTooLargeError: - await _send(send, self._proxy.too_large()) + await _send(send, self._proxy.too_large(screening.cors)) return if body is None: await self._answer_nobody(send) diff --git a/src/fingerly/_client.py b/src/fingerly/_client.py index cc32e9e..de7eaf9 100644 --- a/src/fingerly/_client.py +++ b/src/fingerly/_client.py @@ -4,9 +4,10 @@ import asyncio import threading +import time import warnings from collections.abc import Mapping -from datetime import datetime +from datetime import datetime, timezone from types import TracebackType from typing import Any, Optional, TypeVar, Union @@ -16,25 +17,57 @@ DEFAULT_ENDPOINT, Secret, no_cookies, + normalize_api_origin, normalize_api_version, - normalize_endpoint, parse_key, positive_seconds, ) -from ._errors import FingerlyAPIError, FingerlyConnectionError, FingerlyTimeoutError +from ._errors import ( + FingerlyAPIError, + FingerlyConnectionError, + FingerlyEventAlreadyConsumedError, + FingerlyTimeoutError, +) from ._http import MAX_RESPONSE_BYTES, AsyncPool, Reply, ResponseTooLargeError, SyncPool -from ._models import Event, EventPage, parse_event, parse_page +from ._models import ( + ConsumeResult, + DeviceCheckBits, + DeviceCheckWriteResult, + Event, + EventPage, + VerifyResult, + failed_check, + parse_consume, + parse_device_check_bits, + parse_device_check_write, + parse_event, + parse_page, + parse_verified_event, +) from ._transport import ( KeyAuth, api_error, decode_json, + device_check_body, + device_check_error, event_path, headers_for, + is_not_found, list_params, + verify_options, ) DEFAULT_TIMEOUT = 10.0 +#: How old an event ``events.verify`` accepts by default, in seconds. +DEFAULT_MAX_AGE_SECONDS = 300 + + +def _now() -> datetime: + """The current instant, timezone-aware, that an event's age is taken from.""" + return datetime.now(timezone.utc) + + _Self = TypeVar("_Self", bound="_BaseFingerly") @@ -47,16 +80,22 @@ def __init__( endpoint: Optional[str] = None, timeout: float = DEFAULT_TIMEOUT, api_version: str = "v1", + allow_insecure_loopback: bool = False, ) -> None: """Validates every option before any client is built. Args: secret_key: A server-only key, ``fly_sk_{environment}_…``. Its prefix names the environment read. - endpoint: Overrides the Fingerly API origin, for a local API. + endpoint: Overrides the Fingerly API origin, for a local API. Only + a scheme, a host and an optional port, such as + ``https://api.example.com:8443``; ``https`` is required. timeout: One deadline, in seconds, over the whole request: connecting, sending, the response headers and the body. api_version: API route version; the server must support it. + allow_insecure_loopback: For local development and tests only: + lets ``endpoint`` be plain ``http`` on 127.0.0.1, localhost or + [::1]. Every other ``http`` endpoint is refused either way. Raises: TypeError: If any option is invalid. Nothing is sent until then. @@ -64,7 +103,11 @@ def __init__( # Validate the key even when an endpoint is given, so a public, proxy # or management key can never reach an API that would accept it. parse_key(secret_key, "sk") - origin = DEFAULT_ENDPOINT if endpoint is None else normalize_endpoint(endpoint) + origin = normalize_api_origin( + DEFAULT_ENDPOINT if endpoint is None else endpoint, + allow_insecure_loopback, + "endpoint", + ) self._secret_key = Secret(secret_key) self._base_url = f"{origin}/api/{normalize_api_version(api_version)}" self._timeout = positive_seconds(timeout, "timeout") @@ -115,6 +158,81 @@ def get(self, request_id: str) -> Event: """ return parse_event(self._client._request(event_path(request_id))) + def consume(self, request_id: str) -> ConsumeResult: + """Marks an event as consumed, so it backs one decision only. + + The first call answers with ``first=True``; every later one raises. + Never retried. + + Args: + request_id: The ``request_id`` returned by identification. + + Raises: + TypeError: If the request id is empty. Nothing is sent. + FingerlyEventAlreadyConsumedError: ``409 event_already_consumed`` + when the event was consumed before; ``consumed_at`` says when. + FingerlyAPIError: ``404 event_not_found``, and any other non-2xx + answer. + FingerlyTimeoutError: If the request exceeds the client timeout. + """ + path = event_path(request_id) + "/consume" + return parse_consume(self._client._request(path, method="POST")) + + def verify( + self, + request_id: str, + *, + max_age_seconds: int = DEFAULT_MAX_AGE_SECONDS, + tag: Optional[str] = None, + consume: bool = True, + ) -> VerifyResult: + """Reads an event and checks it can back a backend action. + + The checks run in this order and stop at the first failure: the event + exists (``not_found``), it occurred at most ``max_age_seconds`` ago + (``too_old``; a missing or unreadable time fails too), it carries + ``tag`` exactly when one is given (``tag_mismatch``), it has a + visitor id (``unidentifiable``) and a score (``unscored``). Only then, + unless ``consume=False``, is it consumed (``already_consumed``). The + score's value is never judged: that policy stays with the caller. + + Args: + request_id: The ``request_id`` returned by identification. + max_age_seconds: Oldest acceptable event, in seconds. + tag: The tag the event must carry, or None to skip the check. + consume: Whether to consume the event when every check passes. + + Raises: + TypeError: If an option or the request id is unusable. Nothing is + sent. + FingerlyEventPendingError: ``404 event_pending``; not a verdict. + FingerlyAPIError: Any answer other than ``event_not_found`` and, + on consume, ``event_already_consumed``. + FingerlyTimeoutError: If a request exceeds the client timeout. + """ + verify_options(max_age_seconds, tag, consume) + path = event_path(request_id) + try: + payload = self._client._request(path) + except FingerlyAPIError as error: + if is_not_found(error): + return VerifyResult(ok=False, reason="not_found") + raise + event, occurred = parse_verified_event(payload) + reason = failed_check(event, occurred, _now(), max_age_seconds, tag) + if reason: + return VerifyResult(ok=False, reason=reason, event=event) + if consume: + try: + self._client._request(path + "/consume", method="POST") + except FingerlyEventAlreadyConsumedError: + return VerifyResult(ok=False, reason="already_consumed", event=event) + except FingerlyAPIError as error: + if is_not_found(error): + return VerifyResult(ok=False, reason="not_found") + raise + return VerifyResult(ok=True, reason="", event=event) + def list( self, from_: Union[datetime, str, None] = None, @@ -155,6 +273,43 @@ async def get(self, request_id: str) -> Event: """ return parse_event(await self._client._request(event_path(request_id))) + async def consume(self, request_id: str) -> ConsumeResult: + """Marks an event as consumed. See :meth:`Events.consume`.""" + path = event_path(request_id) + "/consume" + return parse_consume(await self._client._request(path, method="POST")) + + async def verify( + self, + request_id: str, + *, + max_age_seconds: int = DEFAULT_MAX_AGE_SECONDS, + tag: Optional[str] = None, + consume: bool = True, + ) -> VerifyResult: + """Reads and checks an event, then consumes it. See :meth:`Events.verify`.""" + verify_options(max_age_seconds, tag, consume) + path = event_path(request_id) + try: + payload = await self._client._request(path) + except FingerlyAPIError as error: + if is_not_found(error): + return VerifyResult(ok=False, reason="not_found") + raise + event, occurred = parse_verified_event(payload) + reason = failed_check(event, occurred, _now(), max_age_seconds, tag) + if reason: + return VerifyResult(ok=False, reason=reason, event=event) + if consume: + try: + await self._client._request(path + "/consume", method="POST") + except FingerlyEventAlreadyConsumedError: + return VerifyResult(ok=False, reason="already_consumed", event=event) + except FingerlyAPIError as error: + if is_not_found(error): + return VerifyResult(ok=False, reason="not_found") + raise + return VerifyResult(ok=True, reason="", event=event) + async def list( self, from_: Union[datetime, str, None] = None, @@ -172,6 +327,134 @@ async def list( return parse_page(await self._client._request("/events", params)) +class DeviceCheck: + """Spends the DeviceCheck token held for an iOS event, once. + + Reached as ``fingerly.device_check``. Each held token pays for one Apple + call: a read or a write, never both. To read the bits and then set them, + read on one identification and write on the next. + + A ``503 device_check_unavailable`` or a transport failure is retried with + the identical request: a token kept after an answer that was not definite + accepts only the request it was first used for. + """ + + def __init__(self, client: Fingerly) -> None: + self._client = client + + def query(self, request_id: str) -> DeviceCheckBits: + """Reads the device's two bits from Apple, spending the event's token. + + Args: + request_id: The ``request_id`` of an iOS identification made within + the last hour. + + Raises: + FingerlyDeviceCheckError: On any non-2xx answer; see its ``code``. + FingerlyTimeoutError: If every attempt timed out. + FingerlyConnectionError: If the API could not be reached. + """ + path = device_check_path(request_id) + "/query" + return parse_device_check_bits(self._spend("POST", path, None)) + + def write( + self, + request_id: str, + bit0: Optional[bool] = None, + bit1: Optional[bool] = None, + ) -> DeviceCheckWriteResult: + """Sets bit0, bit1 or both with Apple, spending the event's token. + + A bit left as None keeps its value. + + Raises: + TypeError: If neither bit is given. Nothing is sent. + FingerlyDeviceCheckError: On any non-2xx answer; see its ``code``. + FingerlyTimeoutError: If every attempt timed out. + FingerlyConnectionError: If the API could not be reached. + """ + body = device_check_body(bit0, bit1) + path = device_check_path(request_id) + return parse_device_check_write(self._spend("PUT", path, body)) + + def _spend( + self, method: str, path: str, body: Optional[bytes] + ) -> Mapping[str, Any]: + for attempt in range(len(_DEVICE_CHECK_RETRY_DELAYS) + 1): + try: + return self._client._request(path, method=method, content=body) + except FingerlyAPIError as error: + if error.status != 503 or attempt == len(_DEVICE_CHECK_RETRY_DELAYS): + raise device_check_error(error) from None + time.sleep(_retry_delay(attempt, error.retry_after)) + except (FingerlyTimeoutError, FingerlyConnectionError): + if attempt == len(_DEVICE_CHECK_RETRY_DELAYS): + raise + time.sleep(_retry_delay(attempt, None)) + raise AssertionError("unreachable") # pragma: no cover + + +class AsyncDeviceCheck: + """Asyncio DeviceCheck reads and writes. Reached as ``fingerly.device_check``. + + See :class:`DeviceCheck`; the coroutines take the same arguments. + """ + + def __init__(self, client: AsyncFingerly) -> None: + self._client = client + + async def query(self, request_id: str) -> DeviceCheckBits: + """Reads the device's two bits. See :meth:`DeviceCheck.query`.""" + path = device_check_path(request_id) + "/query" + return parse_device_check_bits(await self._spend("POST", path, None)) + + async def write( + self, + request_id: str, + bit0: Optional[bool] = None, + bit1: Optional[bool] = None, + ) -> DeviceCheckWriteResult: + """Sets bit0, bit1 or both. See :meth:`DeviceCheck.write`.""" + body = device_check_body(bit0, bit1) + path = device_check_path(request_id) + return parse_device_check_write(await self._spend("PUT", path, body)) + + async def _spend( + self, method: str, path: str, body: Optional[bytes] + ) -> Mapping[str, Any]: + for attempt in range(len(_DEVICE_CHECK_RETRY_DELAYS) + 1): + try: + return await self._client._request(path, method=method, content=body) + except FingerlyAPIError as error: + if error.status != 503 or attempt == len(_DEVICE_CHECK_RETRY_DELAYS): + raise device_check_error(error) from None + await asyncio.sleep(_retry_delay(attempt, error.retry_after)) + except (FingerlyTimeoutError, FingerlyConnectionError): + if attempt == len(_DEVICE_CHECK_RETRY_DELAYS): + raise + await asyncio.sleep(_retry_delay(attempt, None)) + raise AssertionError("unreachable") # pragma: no cover + + +#: Pauses before each DeviceCheck retry, in seconds. A ``Retry-After`` answer +#: replaces the pause, up to :data:`_MAX_DEVICE_CHECK_RETRY_DELAY`. +_DEVICE_CHECK_RETRY_DELAYS: tuple[float, ...] = (0.25, 1.0) +_MAX_DEVICE_CHECK_RETRY_DELAY = 5.0 + +_JSON_BODY = {"content-type": "application/json"} + + +def device_check_path(request_id: str) -> str: + """The DeviceCheck path of one event, the id encoded as one segment.""" + return event_path(request_id) + "/device-check" + + +def _retry_delay(attempt: int, retry_after: Optional[float]) -> float: + if retry_after is not None: + return min(retry_after, _MAX_DEVICE_CHECK_RETRY_DELAY) + return _DEVICE_CHECK_RETRY_DELAYS[attempt] + + class Fingerly(_BaseFingerly): """The Fingerly server SDK for synchronous code. @@ -192,6 +475,7 @@ def __init__( api_version: str = "v1", transport: Optional[httpx.BaseTransport] = None, limits: Optional[httpx.Limits] = None, + allow_insecure_loopback: bool = False, ) -> None: """See :class:`_BaseFingerly` for the shared arguments. @@ -201,7 +485,9 @@ def __init__( limits: Connections this client may hold across its pools. The default lets 256 concurrent reads reuse connections. """ - super().__init__(secret_key, endpoint, timeout, api_version) + super().__init__( + secret_key, endpoint, timeout, api_version, allow_insecure_loopback + ) def build(pool_transport: Optional[httpx.BaseTransport]) -> httpx.Client: return httpx.Client( @@ -216,6 +502,7 @@ def build(pool_transport: Optional[httpx.BaseTransport]) -> httpx.Client: self._pool = SyncPool(build, self._timeout, limits, transport) self.events = Events(self) + self.device_check = DeviceCheck(self) def close(self) -> None: """Closes the pooled connections. Safe to call more than once.""" @@ -233,9 +520,14 @@ def __exit__( self.close() def _request( - self, path: str, params: Optional[Mapping[str, str]] = None + self, + path: str, + params: Optional[Mapping[str, str]] = None, + *, + method: str = "GET", + content: Optional[bytes] = None, ) -> Mapping[str, Any]: - """Performs one GET and decodes its body. Never retries. + """Performs one request and decodes its body. Never retries. Raises: FingerlyTimeoutError: If the request exceeds the client timeout. @@ -244,7 +536,13 @@ def _request( """ _warn_if_on_an_event_loop() try: - reply = self._pool.request("GET", path, params=params) + reply = self._pool.request( + method, + path, + params=params, + content=content, + headers=_JSON_BODY if content is not None else None, + ) except httpx.TimeoutException as error: raise FingerlyTimeoutError() from error except httpx.HTTPError as error: @@ -273,6 +571,7 @@ def __init__( api_version: str = "v1", transport: Optional[httpx.AsyncBaseTransport] = None, limits: Optional[httpx.Limits] = None, + allow_insecure_loopback: bool = False, ) -> None: """See :class:`_BaseFingerly` for the shared arguments. @@ -282,7 +581,9 @@ def __init__( limits: Connections this client may hold across its pools. The default lets 256 concurrent reads reuse connections. """ - super().__init__(secret_key, endpoint, timeout, api_version) + super().__init__( + secret_key, endpoint, timeout, api_version, allow_insecure_loopback + ) def build( pool_transport: Optional[httpx.AsyncBaseTransport], @@ -299,6 +600,7 @@ def build( self._pool = AsyncPool(build, self._timeout, limits, transport) self.events = AsyncEvents(self) + self.device_check = AsyncDeviceCheck(self) async def aclose(self) -> None: """Closes the pooled connections. Safe to call more than once.""" @@ -316,9 +618,14 @@ async def __aexit__( await self.aclose() async def _request( - self, path: str, params: Optional[Mapping[str, str]] = None + self, + path: str, + params: Optional[Mapping[str, str]] = None, + *, + method: str = "GET", + content: Optional[bytes] = None, ) -> Mapping[str, Any]: - """Performs one GET and decodes its body. Never retries. + """Performs one request and decodes its body. Never retries. Raises: FingerlyTimeoutError: If the request exceeds the client timeout. @@ -326,7 +633,13 @@ async def _request( FingerlyAPIError: On any non-2xx response. """ try: - reply = await self._pool.request("GET", path, params=params) + reply = await self._pool.request( + method, + path, + params=params, + content=content, + headers=_JSON_BODY if content is not None else None, + ) except httpx.TimeoutException as error: raise FingerlyTimeoutError() from error except httpx.HTTPError as error: diff --git a/src/fingerly/_config.py b/src/fingerly/_config.py index 646d8f8..e547bd5 100644 --- a/src/fingerly/_config.py +++ b/src/fingerly/_config.py @@ -122,6 +122,69 @@ def normalize_endpoint(value: str) -> str: return value.rstrip("/") +#: Printable ASCII with no space: anything else in an API origin option is a +#: copy and paste mistake, never part of an origin. +_ORIGIN_BYTES = re.compile(r"\A[\x21-\x7e]+\Z") + +#: The only hosts a plain HTTP API origin may name, and only when +#: ``allow_insecure_loopback`` is set. +LOOPBACK_HOSTS = frozenset({"127.0.0.1", "localhost", "::1"}) + + +def normalize_api_origin( + value: object, allow_insecure_loopback: bool, name: str +) -> str: + """Validates an API origin option and rebuilds it from its parts. + + Only a scheme, a host and an optional port are accepted: no path, query, + fragment, credentials, space or control byte. The scheme is ``https``; + plain ``http`` is accepted only for 127.0.0.1, localhost or [::1], and only + when ``allow_insecure_loopback`` is set, because a key travels with every + request. The value is never echoed in the error. + + Args: + value: The option as the caller gave it. + allow_insecure_loopback: Whether plain HTTP on a loopback host is + allowed, for local development and tests. + name: The option's name, for the error. + + Raises: + TypeError: If the value is not such an origin. + """ + if not isinstance(allow_insecure_loopback, bool): + raise TypeError("allow_insecure_loopback must be a bool") + problem = f"{name} must be an https:// origin with only a host and an optional port" + if not isinstance(value, str) or _ORIGIN_BYTES.match(value) is None: + raise TypeError(problem) + try: + parts = urlsplit(value) + port = parts.port # Validated on access, not by urlsplit. + httpx.URL(value) + except (ValueError, httpx.InvalidURL): + raise TypeError(problem) from None + host = parts.hostname or "" + if ( + parts.scheme not in ("http", "https") + or not host + or "@" in parts.netloc + or "?" in value + or "#" in value + or parts.path not in ("", "/") + ): + raise TypeError(problem) + if parts.scheme == "http" and not ( + allow_insecure_loopback and host in LOOPBACK_HOSTS + ): + raise TypeError( + f"{name} must use https; plain http is allowed only for 127.0.0.1, " + "localhost or [::1] with allow_insecure_loopback=True" + ) + netloc = f"[{host}]" if ":" in host else host + if port is not None: + netloc = f"{netloc}:{port}" + return f"{parts.scheme}://{netloc}" + + def normalize_api_version(version: str = "v1") -> str: """Validates an API route version before it is spliced into a URL. diff --git a/src/fingerly/_errors.py b/src/fingerly/_errors.py index 7113108..dbc84e3 100644 --- a/src/fingerly/_errors.py +++ b/src/fingerly/_errors.py @@ -70,6 +70,50 @@ def __repr__(self) -> str: return f"{type(self).__name__}(status={self.status}, code={self.code!r})" +class FingerlyDeviceCheckError(FingerlyAPIError): + """Raised for any non-2xx answer from a DeviceCheck read or write. + + Branch on ``code``: + + - ``device_check_not_held`` (404): no token is held for that event. Decide + without the bits. + - ``device_check_spent`` (409): the token was already used, or a retry was + not the same request as the first attempt. Use another identification. + - ``device_check_busy`` (409): another call is using the token right now. + - ``credential_unavailable`` (409): the project's Apple key is missing, + refused by Apple, or has DeviceCheck off. The token is kept. + - ``bits_required`` (422): a write named neither bit. + - ``apple_rejected`` (422): Apple rejected the token, which is used up; + ``apple_status`` holds Apple's HTTP status. + - ``device_check_unavailable`` (503): Apple or storage could not answer; + the token is kept. The SDK has already retried the same request. + + Attributes: + apple_status: Apple's HTTP status on ``apple_rejected``, else None. + """ + + def __init__( + self, + message: str, + status: int, + *, + code: Optional[str] = None, + details: Any = None, + request_id: Optional[str] = None, + retry_after: Optional[float] = None, + apple_status: Optional[int] = None, + ) -> None: + super().__init__( + message, + status, + code=code, + details=details, + request_id=request_id, + retry_after=retry_after, + ) + self.apple_status = apple_status + + class FingerlyEventPendingError(FingerlyAPIError): """Raised for ``404 event_pending`` from an event read. @@ -80,3 +124,37 @@ class FingerlyEventPendingError(FingerlyAPIError): retention) does not raise this class. Reads are never retried automatically. """ + + +class FingerlyEventAlreadyConsumedError(FingerlyAPIError): + """Raised for ``409 event_already_consumed`` from an event consume. + + The event was consumed before, so it already backed one decision. It is + still a :class:`FingerlyAPIError`, with ``status`` 409 and ``code`` + ``event_already_consumed``. + + Attributes: + consumed_at: When the event was first consumed, as the RFC 3339 string + the API sent, or None when the answer did not say. + """ + + def __init__( + self, + message: str, + status: int, + *, + code: Optional[str] = None, + details: Any = None, + request_id: Optional[str] = None, + retry_after: Optional[float] = None, + consumed_at: Optional[str] = None, + ) -> None: + super().__init__( + message, + status, + code=code, + details=details, + request_id=request_id, + retry_after=retry_after, + ) + self.consumed_at = consumed_at diff --git a/src/fingerly/_models.py b/src/fingerly/_models.py index 7f66f85..99cb8ea 100644 --- a/src/fingerly/_models.py +++ b/src/fingerly/_models.py @@ -9,9 +9,9 @@ import re from collections.abc import Mapping, Sequence -from dataclasses import dataclass, field -from datetime import datetime -from typing import Any, Optional +from dataclasses import dataclass, field, replace +from datetime import datetime, timezone +from typing import Any, Literal, Optional from ._errors import FingerlyError @@ -21,13 +21,90 @@ r"(?:[Zz]|(?P[+-])(?P\d{2}):?(?P\d{2}))\Z" ) +#: Canonical v3 risk signal and signal-group names reported in event triggers +#: and archived risk assessments. +SIGNAL_NAMES: tuple[str, ...] = ( + "tor", + "datacenter_proxy", + "proxy", + "datacenter_ip", + "residential_proxy", + "residential_proxy_low_confidence", + "residential_proxy_medium_confidence", + "residential_proxy_high_confidence", + "vpn", + "vpn_public", + "vpn_timezone", + "vpn_relay", + "vpn_mobile", + "vpn_os_mismatch", + "vpn_low_confidence", + "vpn_medium_confidence", + "vpn_high_confidence", + "ip_blocklist", + "ip_blocklist_email_spam", + "ip_blocklist_attack_source", + "ip_reputation", + "ip_abuser", + "network_anomaly", + "bogon_ip", + "anycast_ip", + "location_spoofing", + "geo_mismatch", + "ios_simulator", + "simulator", + "android_emulator", + "emulator", + "virtual_machine", + "jailbroken_device", + "jailbreak", + "rooted_device", + "root_apps", + "play_device_integrity_failed", + "cloned_app", + "app_cloner", + "play_app_unrecognized", + "device_farm", + "app_attest_key_churn", + "mitm_attack", + "frida_detected", + "frida", + "browser_tampering", + "tampering", + "antidetect_browser", + "fingerprint_suppressed", + "developer_tools", + "remote_control", + "bot", + "automation", + "bad_bot", + "fetch_metadata_missing", + "web_ticket_missing", + "web_ticket_invalid", + "high_activity", + "incognito_mode", + "incognito", + "privacy_settings", + "embedded_web_view", + "active_call", + "attestation_missing", + "attestation_failed", + "attestation_downgrade", + "device_inconsistent", + "report_incomplete", + "probe_errors", + "custom_root_ca", + "secondary_user_profile", +) + @dataclass(frozen=True) class EventTrigger: """One signal group that contributed to an event's suspect score. Attributes: - signal: The signal group, such as ``vpn`` or ``bot``. + signal: The signal group, such as ``vpn``, ``bot`` or + ``attestation_failed``. weight: The group's combined weight in this score. confidence: ``low``, ``medium`` or ``high``. """ @@ -37,17 +114,78 @@ class EventTrigger: confidence: Optional[str] = None +@dataclass(frozen=True) +class Attestation: + """Platform-neutral hardware attestation verdict from an archived document. + + Attributes: + state: ``attested``, ``not_attested`` or ``failed``. + status: ``verified``, ``indeterminate``, ``invalid``, ``absent`` or + ``unconfigured``. + attest_skipped: Native only: the app's own reason for sending no + attestation, such as ``not_offered``, ``unsupported`` or + ``timeout``. Diagnostic only; it never lowers the score. + downgrade: Native only: an unproven or rejected report named an + install an attested device owns, so it was answered + unidentifiable. + """ + + state: str + status: str + platform: Optional[str] = None + reason: Optional[str] = None + chain_length: Optional[int] = None + attestation_security_level: Optional[str] = None + keymint_security_level: Optional[str] = None + device_locked: Optional[bool] = None + verified_boot_state: Optional[str] = None + nonce: Optional[str] = None + revocation_checked: bool = False + package_bound: bool = False + signer_bound: bool = False + attest_skipped: Optional[str] = None + downgrade: bool = False + mode: Optional[str] = None + app_id: Optional[str] = None + environment: Optional[str] = None + receipt: Optional[str] = None + risk_metric: Optional[int] = None + risk_metric_age_h: Optional[int] = None + device_check: Optional[str] = None + play_integrity: Optional[Mapping[str, Any]] = None + raw: Mapping[str, Any] = field(default_factory=dict, repr=False) + + +@dataclass(frozen=True) +class EventDocument: + """Allow-listed view of an archived identification submission.""" + + schema: int + request_id: str + occurred_at: datetime + sdk_platform: str + sdk_version: str + ip_network: Optional[str] = None + ip: Optional[Mapping[str, Any]] = None + ip_error: Optional[str] = None + risk: Optional[Mapping[str, Any]] = None + attestation: Optional[Attestation] = None + velocity: Optional[Mapping[str, Any]] = None + raw: Mapping[str, Any] = field(default_factory=dict, repr=False) + + @dataclass(frozen=True) class Event: """A stored identification event. ``suspect_score`` is ``None`` when the request was not scored, which must - not be read as zero. ``ip_network`` is the network the request came from - (an IPv4 /24 or an IPv6 /40, such as ``203.0.113.0/24``); the API never - returns the address. ``document`` is an allow-listed view of the archived - request (schema, request id, time, SDK, network, IP classification and - city-level location, risk, attestation and velocity), with no raw signals, - user agent or address; its contents are not a public contract. + not be read as zero. ``visitor_id`` is ``""`` when the submission was + unidentifiable (``identifiable == false``). ``ip_network`` is the network + the request came from (an IPv4 /24 or an IPv6 /40, such as + ``203.0.113.0/24``); the API never returns the address. ``document`` is an + allow-listed view of the archived request (schema, request id, time, SDK, + network, IP classification and city-level location, risk, attestation and + velocity), with no raw signals, user agent or address. Attributes: project_id: The Fingerly project the event belongs to, as a UUID @@ -66,9 +204,12 @@ class Event: sdk_version: str has_document: bool triggers: Sequence[EventTrigger] + reason: Optional[str] = None suspect_score: Optional[int] = None suspect_level: Optional[str] = None origin: Optional[str] = None + url_host: Optional[str] = None + url_path: Optional[str] = None tag: Optional[str] = None project_id: Optional[str] = None ip_network: Optional[str] = None @@ -85,6 +226,17 @@ class Event: document: Optional[Mapping[str, Any]] = None raw: Mapping[str, Any] = field(default_factory=dict, repr=False) + @property + def identifiable(self) -> bool: + """Whether this event resolved to a non-empty visitor identifier.""" + return bool(self.visitor_id) + + def parse_document(self) -> Optional[EventDocument]: + """Parses ``document`` into a typed :class:`EventDocument`, if present.""" + if self.document is None: + return None + return parse_document(self.document) + def __getattr__(self, name: str) -> Any: """Reads a field the API added after this SDK was released. @@ -118,6 +270,174 @@ class EventPage: page_size: int +@dataclass(frozen=True) +class DeviceCheckBits: + """What Apple holds for the device behind an iOS event. + + The bits mean what you decided they mean; Fingerly never reads them. + + Attributes: + found: False when Apple holds no bits for the device yet. Both bits + are then False. + bit0: The first bit. + bit1: The second bit. + last_update: When the bits last changed, as ``YYYY-MM``, or None when + Apple holds no bits. + """ + + found: bool + bit0: bool + bit1: bool + last_update: Optional[str] = None + + +@dataclass(frozen=True) +class DeviceCheckWriteResult: + """The bits Apple accepted on a write. + + Attributes: + bit0: The value set for the first bit, or None when it was left out. + bit1: The value set for the second bit, or None when it was left out. + """ + + bit0: Optional[bool] = None + bit1: Optional[bool] = None + + +@dataclass(frozen=True) +class ConsumeResult: + """The answer to consuming an event. + + Attributes: + request_id: The consumed event's request id. + consumed_at: When it was consumed, as the RFC 3339 string the API sent. + first: True when this call consumed it. + """ + + request_id: str + consumed_at: str + first: bool + + +#: Why :meth:`Events.verify` refused an event, or ``""`` when it passed. +VerifyReason = Literal[ + "", + "not_found", + "too_old", + "tag_mismatch", + "unidentifiable", + "unscored", + "already_consumed", +] + + +@dataclass(frozen=True) +class VerifyResult: + """The outcome of :meth:`Events.verify`. + + Attributes: + ok: True when every check passed, and the event was consumed unless + ``consume=False``. + reason: ``""`` when ``ok``; otherwise the first check that failed: + ``not_found``, ``too_old``, ``tag_mismatch``, ``unidentifiable``, + ``unscored`` or ``already_consumed``. + event: The event read, or None only for ``not_found``. When its + ``occurred_at`` was missing or unreadable (reason ``too_old``), + ``event.occurred_at`` is the earliest UTC ``datetime`` and + ``event.raw`` holds what the API sent. + """ + + ok: bool + reason: VerifyReason + event: Optional[Event] = None + + +def parse_consume(payload: Mapping[str, Any]) -> ConsumeResult: + """Builds :class:`ConsumeResult` from a consume answer.""" + return ConsumeResult( + request_id=_require(payload, "request_id", str), + consumed_at=_require(payload, "consumed_at", str), + first=_require(payload, "first", bool), + ) + + +_UNKNOWN_INSTANT = datetime.min.replace(tzinfo=timezone.utc) + + +def parse_verified_event( + payload: Mapping[str, Any], +) -> tuple[Event, Optional[datetime]]: + """Builds the event ``verify`` checks, tolerating what the checks judge. + + A missing ``visitor_id`` reads as ``""`` (unidentifiable), and a missing or + unreadable ``occurred_at`` as the earliest instant, so either becomes a + failed check instead of an exception. + + Returns: + The event, and its ``occurred_at`` or None when it was unusable. + """ + occurred: Optional[datetime] + try: + occurred = parse_instant(payload.get("occurred_at")) # type: ignore[arg-type] + except (FingerlyError, ValueError): + occurred = None + patched = dict(payload) + patched["occurred_at"] = "0001-01-01T00:00:00Z" + if not isinstance(patched.get("visitor_id"), str): + patched["visitor_id"] = "" + event = replace( + parse_event(patched), + occurred_at=occurred if occurred is not None else _UNKNOWN_INSTANT, + raw=payload, + ) + return event, occurred + + +def failed_check( + event: Event, + occurred: Optional[datetime], + now: datetime, + max_age_seconds: int, + tag: Optional[str], +) -> VerifyReason: + """The first of ``verify``'s checks before consumption that fails, or ``""``. + + The order is fixed: age, tag, identifiability, scoring. The score's value, + level and triggers are never looked at. + """ + if occurred is None or (now - occurred).total_seconds() > max_age_seconds: + return "too_old" + if tag is not None and (event.tag or "") != tag: + return "tag_mismatch" + if not event.visitor_id: + return "unidentifiable" + if event.suspect_score is None: + return "unscored" + return "" + + +def parse_device_check_bits(payload: Mapping[str, Any]) -> DeviceCheckBits: + """Builds :class:`DeviceCheckBits` from a query answer.""" + last_update = payload.get("last_update") + return DeviceCheckBits( + found=_require(payload, "found", bool), + bit0=_require(payload, "bit0", bool), + bit1=_require(payload, "bit1", bool), + last_update=last_update + if isinstance(last_update, str) and last_update + else None, + ) + + +def parse_device_check_write(payload: Mapping[str, Any]) -> DeviceCheckWriteResult: + """Builds :class:`DeviceCheckWriteResult` from a write answer.""" + bit0, bit1 = payload.get("bit0"), payload.get("bit1") + return DeviceCheckWriteResult( + bit0=bit0 if isinstance(bit0, bool) else None, + bit1=bit1 if isinstance(bit1, bool) else None, + ) + + def parse_event(payload: Mapping[str, Any]) -> Event: """Builds an :class:`Event` from a decoded response body. @@ -141,9 +461,12 @@ def parse_event(payload: Mapping[str, Any]) -> Event: sdk_version=_require(payload, "sdk_version", str), has_document=bool(payload.get("has_document", False)), triggers=[_parse_trigger(row) for row in payload.get("triggers") or ()], + reason=payload.get("reason"), suspect_score=payload.get("suspect_score"), suspect_level=payload.get("suspect_level"), origin=payload.get("origin"), + url_host=payload.get("url_host"), + url_path=payload.get("url_path"), tag=payload.get("tag"), project_id=payload.get("project_id"), ip_network=payload.get("ip_network") or None, @@ -199,6 +522,63 @@ def parse_instant(value: str) -> datetime: ) +def parse_document(payload: Mapping[str, Any]) -> EventDocument: + """Builds an :class:`EventDocument` from an archived document mapping.""" + sdk_raw = payload.get("sdk") + sdk: Mapping[str, Any] = sdk_raw if isinstance(sdk_raw, Mapping) else {} + att_raw = payload.get("attestation") + attestation = _parse_attestation(att_raw) if isinstance(att_raw, Mapping) else None + return EventDocument( + schema=int(payload.get("schema", 1)), + request_id=_require(payload, "request_id", str), + occurred_at=parse_instant(_require(payload, "occurred_at", str)), + sdk_platform=str(sdk.get("platform", "")), + sdk_version=str(sdk.get("version", "")), + ip_network=payload.get("ip_network") or None, + ip=payload.get("ip") if isinstance(payload.get("ip"), Mapping) else None, + ip_error=payload.get("ip_error"), + risk=payload.get("risk") if isinstance(payload.get("risk"), Mapping) else None, + attestation=attestation, + velocity=( + payload.get("velocity") + if isinstance(payload.get("velocity"), Mapping) + else None + ), + raw=payload, + ) + + +def _parse_attestation(payload: Mapping[str, Any]) -> Attestation: + """Builds an :class:`Attestation` from an archived attestation mapping.""" + play = payload.get("play_integrity") + return Attestation( + state=_require(payload, "state", str), + status=_require(payload, "status", str), + platform=payload.get("platform"), + reason=payload.get("reason"), + chain_length=payload.get("chain_length"), + attestation_security_level=payload.get("attestation_security_level"), + keymint_security_level=payload.get("keymint_security_level"), + device_locked=payload.get("device_locked"), + verified_boot_state=payload.get("verified_boot_state"), + nonce=payload.get("nonce"), + revocation_checked=bool(payload.get("revocation_checked", False)), + package_bound=bool(payload.get("package_bound", False)), + signer_bound=bool(payload.get("signer_bound", False)), + attest_skipped=payload.get("attest_skipped"), + downgrade=bool(payload.get("downgrade", False)), + mode=payload.get("mode"), + app_id=payload.get("app_id"), + environment=payload.get("environment"), + receipt=payload.get("receipt"), + risk_metric=payload.get("risk_metric"), + risk_metric_age_h=payload.get("risk_metric_age_h"), + device_check=payload.get("device_check"), + play_integrity=play if isinstance(play, Mapping) else None, + raw=payload, + ) + + def _parse_trigger(payload: Mapping[str, Any]) -> EventTrigger: """Builds one :class:`EventTrigger`, tolerating a missing confidence.""" return EventTrigger( diff --git a/src/fingerly/_proxy.py b/src/fingerly/_proxy.py index 08dc00f..daefd46 100644 --- a/src/fingerly/_proxy.py +++ b/src/fingerly/_proxy.py @@ -19,6 +19,7 @@ from dataclasses import dataclass from http import HTTPStatus from typing import TYPE_CHECKING, Callable, NamedTuple, Optional +from urllib.parse import urlsplit import httpx @@ -42,6 +43,7 @@ KeyScope, Secret, no_cookies, + normalize_api_origin, normalize_api_version, normalize_endpoint, parse_key, @@ -77,6 +79,42 @@ "retry-after", ) +#: Exact lowercase native and bridge SDK platform identifiers allowed through +#: the sanitize-and-restore header sequence. +VALID_SDK_PLATFORMS = frozenset( + { + "ios", + "android", + "react-native", + "react-native-ios", + "react-native-android", + "flutter", + "flutter-ios", + "flutter-android", + "lynx-ios", + "lynx-android", + "capacitor", + "kotlin-multiplatform", + } +) + +#: Browser fetch-metadata and client-hint headers forwarded verbatim when present. +CLIENT_METADATA_HEADERS = ( + "sec-fetch-site", + "sec-fetch-mode", + "sec-fetch-dest", + "sec-ch-ua", + "sec-ch-ua-mobile", + "sec-ch-ua-platform", +) + +CORS_ALLOW_HEADERS = "content-type, x-api-key, idempotency-key, x-fingerly-sdk-platform" +CORS_EXPOSE_HEADERS = "x-request-id, ratelimit-limit, ratelimit-remaining, retry-after" +MISSING_ORIGIN_BODY = ( + b'{"error":{"code":"missing_origin",' + b'"message":"Origin header is required","status":400}}' +) + class Headers(Mapping[str, str]): """Case-insensitive, read-only view of one request's headers. @@ -159,16 +197,17 @@ class Screening(NamedTuple): Attributes: refusal: The response to send, when the request is refused. - api_key: The key to present upstream, when it is not. + api_key: The browser's public key to present upstream, when it is not. client_ip: The visitor address ``client_ip`` resolved, when it is not. + cors: Matched cross-origin ``Origin``, when ``allowed_origins`` matched. """ refusal: Optional[ProxyResponse] api_key: str = "" client_ip: str = "" + cors: Optional[str] = None def __repr__(self) -> str: - # In the deprecated secret-key mode ``api_key`` is the secret itself. return ( f"Screening(refusal={self.refusal!r}, api_key={REDACTED}, " f"client_ip={self.client_ip!r})" @@ -206,15 +245,16 @@ def __init__( self, client_ip: Callable[[ProxyRequest], str], proxy_key: Optional[str] = None, - secret_key: Optional[str] = None, path: Optional[str] = None, api_version: str = "v1", upstream: Optional[str] = None, max_body_bytes: int = DEFAULT_MAX_BODY_BYTES, timeout: float = DEFAULT_TIMEOUT, + allowed_origins: Optional[Sequence[str]] = None, transport: Optional[httpx.BaseTransport] = None, async_transport: Optional[httpx.AsyncBaseTransport] = None, limits: Optional[httpx.Limits] = None, + allow_insecure_loopback: bool = False, ) -> None: """Validates every option before either handler exists. @@ -223,8 +263,9 @@ def __init__( app trusts. Never read the left-most ``X-Forwarded-For`` value: the visitor writes it. Called under both standards, so it must be synchronous. - proxy_key: A proxy key, ``fly_px_…``, held only on your server. - secret_key: Deprecated alternative to ``proxy_key``. + proxy_key: Required. A proxy key, ``fly_px__…``, held + only on your server. Browsers must present a public key, + ``fly_pk_…``, for the same environment. path: The path the dashboard issued for this proxy, such as ``/k7x2qm4a``, within the application. When set, only that path is answered, exactly, and anything else gets 404. It @@ -232,7 +273,12 @@ def __init__( as either present or already stripped by the mount. Omit it when the framework already routes only that path here. api_version: Version of the upstream ingest URL. - upstream: Overrides the API origin implied by the key. + upstream: Overrides the API origin implied by the key. Only a + scheme, a host and an optional port, such as + ``https://api.example.com:8443``; ``https`` is required. + allow_insecure_loopback: For local development and tests only: + lets ``upstream`` be plain ``http`` on 127.0.0.1, localhost or + [::1]. Every other ``http`` upstream is refused either way. max_body_bytes: Larger request bodies are refused with 413. timeout: One deadline, in seconds, over the whole upstream exchange: connecting, sending, the response headers and the @@ -246,26 +292,25 @@ def __init__( Raises: TypeError: If a credential, route, limit or callback is invalid. """ - if not proxy_key and not secret_key: + if not proxy_key: raise TypeError("A Fingerly proxy key is required") - if proxy_key and secret_key: - raise TypeError("Pass proxy_key or deprecated secret_key, not both") if not callable(client_ip): raise TypeError("client_ip is required") - self._uses_proxy_key = bool(proxy_key) - raw_key: str = proxy_key or secret_key or "" - self._scope: KeyScope = parse_key( - raw_key, "px" if self._uses_proxy_key else "sk" - ) - self._key = Secret(raw_key) + self._scope: KeyScope = parse_key(proxy_key, "px") + self._key = Secret(proxy_key) self._upstream_url = ( - normalize_endpoint(upstream if upstream is not None else DEFAULT_ENDPOINT) + normalize_api_origin( + upstream if upstream is not None else DEFAULT_ENDPOINT, + allow_insecure_loopback, + "upstream", + ) + f"/api/{normalize_api_version(api_version)}/ingest" ) self._path = None if path is None else _normalize_path(path) self._max_body_bytes = positive_int(max_body_bytes, "max_body_bytes") self._timeout = positive_seconds(timeout, "timeout") + self._allowed_origins = _parse_allowed_origins(allowed_origins) self._client_ip = client_ip self._transport = transport self._async_transport = async_transport @@ -275,10 +320,9 @@ def __init__( self._lock = threading.Lock() def __repr__(self) -> str: - kind = "proxy_key" if self._uses_proxy_key else "secret_key" return ( f"FingerlyProxy(path={self._path!r}, upstream={self._upstream_url!r}, " - f"{kind}={self._key!r})" + f"proxy_key={self._key!r})" ) @property @@ -312,35 +356,55 @@ def screen(self, request: ProxyRequest) -> Screening: if not self._answers(request): return Screening(_refuse(404, "Not Found")) + origin = request.headers.get("origin", "").strip() + cors = origin if origin and origin in self._allowed_origins else None + + if request.method == "OPTIONS" and cors is not None: + return Screening(_preflight(cors), cors=cors) + if request.method != "POST": - return Screening(_refuse(405, "Method Not Allowed", (("allow", "POST"),))) + allow = "POST, OPTIONS" if self._allowed_origins else "POST" + return Screening( + _refuse(405, "Method Not Allowed", (("allow", allow),), cors=cors), + cors=cors, + ) api_key = self._upstream_key_for(request.headers.get("x-api-key")) if api_key is None: - return Screening(_refuse(401, "Unauthorized")) + return Screening(_refuse(401, "Unauthorized", cors=cors), cors=cors) + + # Sanitize-and-restore Step 1-4: capture validated x-fingerly-sdk-platform + # before stripping incoming x-fingerly-* headers, and reject with 400 + # missing_origin iff both Origin and validated platform are empty. + raw_platform = request.headers.get("x-fingerly-sdk-platform", "") + sdk_platform = raw_platform if raw_platform in VALID_SDK_PLATFORMS else "" + if not origin and not sdk_platform: + return Screening( + _json_refuse(400, MISSING_ORIGIN_BODY, cors=cors), cors=cors + ) # Refuse on the declared size first; the adapter enforces the real one. declared = request.headers.get("content-length", "") if declared.isdecimal() and int(declared) > self._max_body_bytes: - return Screening(_refuse(413, "Payload Too Large")) + return Screening(_refuse(413, "Payload Too Large", cors=cors), cors=cors) client_ip = self._resolve_client_ip(request) if client_ip is None: - return Screening(_refuse(500, NO_CLIENT_IP)) + return Screening(_refuse(500, NO_CLIENT_IP, cors=cors), cors=cors) - return Screening(None, api_key, client_ip) + return Screening(None, api_key, client_ip, cors) - def too_large(self) -> ProxyResponse: + def too_large(self, cors: Optional[str] = None) -> ProxyResponse: """The response for a body that exceeded the limit while streaming.""" - return _refuse(413, "Payload Too Large") + return _refuse(413, "Payload Too Large", cors=cors) def client_gone(self) -> ProxyResponse: """The response recorded for a visitor who disconnected first.""" return _refuse(499, "Client closed request") - def malformed(self) -> ProxyResponse: + def malformed(self, cors: Optional[str] = None) -> ProxyResponse: """The response for a request body the server could not read.""" - return _refuse(400, "Bad Request") + return _refuse(400, "Bad Request", cors=cors) def forward( self, screening: Screening, request: ProxyRequest, body: bytes @@ -356,8 +420,8 @@ def forward( "POST", self._upstream_url, headers=_on_the_wire(headers), content=body ) except (httpx.HTTPError, ResponseTooLargeError) as error: - return self._upstream_failed(error) - return _relay(reply) + return self._upstream_failed(error, cors=screening.cors) + return self._relay_or_refuse(reply, cors=screening.cors) async def aforward( self, screening: Screening, request: ProxyRequest, body: bytes @@ -369,10 +433,26 @@ async def aforward( "POST", self._upstream_url, headers=_on_the_wire(headers), content=body ) except (httpx.HTTPError, ResponseTooLargeError) as error: - return self._upstream_failed(error) - return _relay(reply) + return self._upstream_failed(error, cors=screening.cors) + return self._relay_or_refuse(reply, cors=screening.cors) + + def _relay_or_refuse( + self, reply: Reply, cors: Optional[str] = None + ) -> ProxyResponse: + """Relays an answer, or answers 502 for a status the proxy never relays. + + A redirect is never followed or passed on, since its target would + receive the proxy key on the next hop, and a status outside 200 to 599 + is not one a browser or an intermediary can act on. + """ + if not (200 <= reply.status <= 599) or 300 <= reply.status <= 399: + logger.warning("Proxy upstream failed: unexpected status") + return _refuse(502, "Bad gateway", cors=cors) + return _relay(reply, cors=cors) - def _upstream_failed(self, error: Exception) -> ProxyResponse: + def _upstream_failed( + self, error: Exception, cors: Optional[str] = None + ) -> ProxyResponse: """Answers an upstream failure without raising, in one log line. A timeout is a 504 and anything else a 502, so no framework turns @@ -380,18 +460,18 @@ def _upstream_failed(self, error: Exception) -> ProxyResponse: """ if isinstance(error, httpx.TimeoutException): logger.warning("Proxy upstream timed out after %.1f s", self._timeout) - return _refuse(504, "Gateway timeout") + return _refuse(504, "Gateway timeout", cors=cors) logger.warning("Proxy upstream failed: %s", _failure_reason(error)) - return _refuse(502, "Bad gateway") + return _refuse(502, "Bad gateway", cors=cors) def upstream_headers( self, request: ProxyRequest, api_key: str, client_ip: Optional[str] = None ) -> dict[str, str]: - """Builds the upstream headers. + """Builds the upstream headers from scratch. - Nothing is copied wholesale: only the body's content type, the visitor - metadata Fingerly needs, the version this proxy reports, and an - idempotency key when the SDK sent one. + All incoming ``x-fingerly-*``, ``cookie`` and ``authorization`` headers + are stripped; only verified proxy metadata and allowlisted client + headers cross the proxy boundary. Args: request: The incoming request. @@ -407,19 +487,33 @@ def upstream_headers( if client_ip is None: raise TypeError(NO_CLIENT_IP) - headers = { - "content-type": request.headers.get("content-type", "application/json"), + headers: dict[str, str] = { + "content-type": request.headers.get("content-type") or "application/json", "x-api-key": api_key, + "x-fingerly-proxy-key": self._key.reveal(), "x-fingerly-client-ip": client_ip, - "x-fingerly-origin": request.headers.get("origin", ""), "x-fingerly-user-agent": request.headers.get("user-agent", ""), "x-fingerly-proxy-version": PROXY_VERSION, } - if self._uses_proxy_key: - headers["x-fingerly-proxy-key"] = self._key.reveal() + # One channel only: a browser Origin wins, as it does when the same + # request is sent to the API directly. The API refuses a proxied + # request that carries both. + origin = request.headers.get("origin", "").strip() + raw_platform = request.headers.get("x-fingerly-sdk-platform", "") + if origin: + headers["x-fingerly-origin"] = origin + elif raw_platform in VALID_SDK_PLATFORMS: + headers["x-fingerly-sdk-platform"] = raw_platform + host = request.headers.get("host", "").strip() + if host: + headers["x-fingerly-host"] = host idempotency_key = request.headers.get("idempotency-key") if idempotency_key: headers["idempotency-key"] = idempotency_key + for name in CLIENT_METADATA_HEADERS: + value = request.headers.get(name) + if value: + headers[name] = value return headers def close(self) -> None: @@ -475,17 +569,14 @@ def _answers(self, request: ProxyRequest) -> bool: return request.path == self._path def _upstream_key_for(self, presented: Optional[str]) -> Optional[str]: - """Decides which key to present upstream. + """Checks the browser's key before anything is forwarded. - With a proxy key the browser must supply a public key for the same - environment, which the proxy forwards alongside its own. The - deprecated secret-key mode authenticates on its own. + The browser must supply a public key, ``fly_pk_…``, for the proxy + key's environment. The proxy forwards it alongside its own proxy key. Returns: - The key to forward, or None when the caller is unauthorised. + The public key to forward, or None when the caller is unauthorised. """ - if not self._uses_proxy_key: - return self._key.reveal() try: browser = parse_key(presented or "", "pk") except TypeError: @@ -611,8 +702,51 @@ def _report_bad_client_ip() -> None: ) +def _parse_allowed_origins(origins: Optional[Sequence[str]]) -> frozenset[str]: + """Validates configured cross-origin browser origins.""" + if origins is None: + return frozenset() + if isinstance(origins, (str, bytes)) or not isinstance(origins, Sequence): + raise TypeError("allowed_origins must be a sequence of origin strings") + validated: set[str] = set() + for item in origins: + if not isinstance(item, str): + raise TypeError("allowed_origins entries must be strings") + normalized = normalize_endpoint(item.strip()) + if urlsplit(normalized).path: + raise TypeError("allowed_origins entries must be bare HTTP(S) origins") + validated.add(normalized) + return frozenset(validated) + + +def _cors_headers(cors: Optional[str]) -> list[tuple[str, str]]: + """Builds cross-origin CORS response headers when an allowed origin matched.""" + if cors is None: + return [] + return [ + ("access-control-allow-origin", cors), + ("vary", "Origin"), + ("access-control-allow-methods", "POST, OPTIONS"), + ("access-control-allow-headers", CORS_ALLOW_HEADERS), + ("access-control-expose-headers", CORS_EXPOSE_HEADERS), + ] + + +def _preflight(cors: str) -> ProxyResponse: + """Builds a 204 preflight response for a matched cross-origin request.""" + headers = [ + ("cache-control", "no-store"), + ("allow", "POST, OPTIONS"), + *_cors_headers(cors), + ] + return ProxyResponse(204, headers, b"") + + def _refuse( - status: int, message: str, extra: Sequence[tuple[str, str]] = () + status: int, + message: str, + extra: Sequence[tuple[str, str]] = (), + cors: Optional[str] = None, ) -> ProxyResponse: """Builds a plain-text refusal that never reaches Fingerly.""" body = message.encode("ascii") @@ -622,6 +756,18 @@ def _refuse( ("cache-control", "no-store"), ] headers.extend(extra) + headers.extend(_cors_headers(cors)) + return ProxyResponse(status, headers, body) + + +def _json_refuse(status: int, body: bytes, cors: Optional[str] = None) -> ProxyResponse: + """Builds a structured JSON refusal before upstream forwarding.""" + headers = [ + ("content-type", "application/json"), + ("content-length", str(len(body))), + ("cache-control", "no-store"), + *_cors_headers(cors), + ] return ProxyResponse(status, headers, body) @@ -638,7 +784,7 @@ def _failure_reason(error: Exception) -> str: return "transport error" -def _relay(reply: Reply) -> ProxyResponse: +def _relay(reply: Reply, cors: Optional[str] = None) -> ProxyResponse: """Returns the upstream response to the browser, allowlisted headers only. The body was read in full before this runs, so a truncated answer is a @@ -654,6 +800,7 @@ def _relay(reply: Reply) -> ProxyResponse: if name in reply.headers and reply.headers[name].isascii() ] headers.append(("cache-control", "no-store")) + headers.extend(_cors_headers(cors)) if reply.status not in BODILESS_STATUSES: headers.append(("content-length", str(len(body)))) return ProxyResponse(reply.status, headers, body) diff --git a/src/fingerly/_transport.py b/src/fingerly/_transport.py index f85ae27..1eee4e6 100644 --- a/src/fingerly/_transport.py +++ b/src/fingerly/_transport.py @@ -16,7 +16,12 @@ import httpx from ._config import REDACTED, Secret, positive_int -from ._errors import FingerlyAPIError, FingerlyEventPendingError +from ._errors import ( + FingerlyAPIError, + FingerlyDeviceCheckError, + FingerlyEventAlreadyConsumedError, + FingerlyEventPendingError, +) from ._version import __version__ #: Sent on every request so events record which SDK build made them. @@ -53,7 +58,13 @@ def event_path(request_id: str) -> str: Args: request_id: The ``request_id`` returned by identification. + + Raises: + TypeError: If the id is empty, which would address the event list + instead of one event. Nothing is sent. """ + if not str(request_id): + raise TypeError("request_id must be a non-empty string") # quote() leaves dots alone and httpx removes a "." or ".." segment before # sending, so an id of "." would read the event list instead of one event. # The id usually comes from the browser. @@ -187,11 +198,14 @@ def api_error( code: Optional[str] = None details: Any = None request_id: Optional[str] = None + payload: Any = None try: payload = json.loads(body) error = payload.get("error") if isinstance(payload, dict) else None if isinstance(error, dict) and isinstance(error.get("code"), str): code = _redact(error["code"], secret_key) + elif isinstance(payload, dict) and isinstance(payload.get("code"), str): + code = _redact(payload["code"], secret_key) if isinstance(error, dict) and error.get("details") is not None: # A JSON round-trip redacts nested values without walking the tree. details = json.loads(_redact(json.dumps(error["details"]), secret_key)) @@ -201,18 +215,117 @@ def api_error( # A non-JSON body still reports its HTTP status, and its contents are # deliberately dropped rather than surfaced. pass + message = f"Fingerly API returned HTTP {status}" + seconds = retry_after_seconds(retry_after) + if status == 409 and code == "event_already_consumed": + consumed_at = _consumed_at(payload) + return FingerlyEventAlreadyConsumedError( + message, + status, + code=code, + details=details, + request_id=request_id, + retry_after=seconds, + consumed_at=_redact(consumed_at, secret_key) if consumed_at else None, + ) error_class = ( FingerlyEventPendingError if status == 404 and code == "event_pending" else FingerlyAPIError ) return error_class( - f"Fingerly API returned HTTP {status}", + message, status, code=code, details=details, request_id=request_id, - retry_after=retry_after_seconds(retry_after), + retry_after=seconds, + ) + + +def _consumed_at(payload: Any) -> Optional[str]: + """Reads ``consumed_at`` from an ``event_already_consumed`` body. + + It may sit at the top level, inside ``error``, or as an ``error.details`` + entry whose ``field`` is ``consumed_at`` and whose ``issue`` is the time. + """ + if not isinstance(payload, dict): + return None + if isinstance(payload.get("consumed_at"), str): + return str(payload["consumed_at"]) + error = payload.get("error") + if not isinstance(error, dict): + return None + if isinstance(error.get("consumed_at"), str): + return str(error["consumed_at"]) + details = error.get("details") + if isinstance(details, list): + for detail in details: + if isinstance(detail, dict) and detail.get("field") == "consumed_at": + issue = detail.get("issue") + return issue if isinstance(issue, str) else None + return None + + +def verify_options(max_age_seconds: int, tag: Optional[str], consume: bool) -> None: + """Validates the options of ``events.verify`` before anything is sent. + + Raises: + TypeError: If ``max_age_seconds`` is not a positive integer, ``tag`` + is not None or a non-empty string (an empty tag would match + untagged events), or ``consume`` is not a bool. + """ + positive_int(max_age_seconds, "max_age_seconds") + if tag is not None and (not isinstance(tag, str) or not tag): + raise TypeError("tag must be None or a non-empty string") + if not isinstance(consume, bool): + raise TypeError("consume must be a bool") + + +def is_not_found(error: FingerlyAPIError) -> bool: + """Whether an API error is ``404 event_not_found``, and nothing else.""" + return error.status == 404 and error.code == "event_not_found" + + +def device_check_body(bit0: Optional[bool], bit1: Optional[bool]) -> bytes: + """Builds a DeviceCheck write body, naming only the bits given. + + Raises: + TypeError: If neither bit is given, or a bit is not a bool. Nothing is + sent, so the held token is not touched. + """ + bits: dict[str, bool] = {} + for name, value in (("bit0", bit0), ("bit1", bit1)): + if value is None: + continue + if not isinstance(value, bool): + raise TypeError(f"{name} must be a bool or None") + bits[name] = value + if not bits: + raise TypeError("Name bit0, bit1 or both") + return json.dumps(bits, separators=(",", ":")).encode() + + +def device_check_error(error: FingerlyAPIError) -> FingerlyDeviceCheckError: + """Re-types an API error from a DeviceCheck route, reading ``apple_status``.""" + apple_status: Optional[int] = None + if error.code == "apple_rejected" and isinstance(error.details, list): + for detail in error.details: + if isinstance(detail, dict) and detail.get("field") == "apple_status": + issue = detail.get("issue") + if isinstance(issue, str) and issue.isdigit(): + apple_status = int(issue) + elif isinstance(issue, int) and not isinstance(issue, bool): + apple_status = issue + break + return FingerlyDeviceCheckError( + str(error), + error.status, + code=error.code, + details=error.details, + request_id=error.request_id, + retry_after=error.retry_after, + apple_status=apple_status, ) diff --git a/src/fingerly/_version.py b/src/fingerly/_version.py index d03a63a..d60e763 100644 --- a/src/fingerly/_version.py +++ b/src/fingerly/_version.py @@ -4,4 +4,4 @@ send and the version the proxy reports upstream all come from here. """ -__version__ = "0.2.0" +__version__ = "0.3.0" diff --git a/src/fingerly/_wsgi.py b/src/fingerly/_wsgi.py index 922e826..fc9da92 100644 --- a/src/fingerly/_wsgi.py +++ b/src/fingerly/_wsgi.py @@ -20,7 +20,7 @@ class WSGIProxy: - """WSGI application serving the browser SDK's same-origin requests. + """WSGI application relaying single-path raw-byte Fingerly ingest requests. Reached as ``proxy.wsgi``. Mount it at the dashboard-issued path under Flask, Django's sync stack, Pyramid or any other WSGI framework:: @@ -48,9 +48,9 @@ def __call__( # A visitor can send broken framing at will. Servers report it with # types of their own, none shared, and uncaught each one is an # error-level traceback in the server's log. - return _write(start_response, self._proxy.malformed()) + return _write(start_response, self._proxy.malformed(screening.cors)) if body is None: - return _write(start_response, self._proxy.too_large()) + return _write(start_response, self._proxy.too_large(screening.cors)) response = self._proxy.forward(screening, request, body) return _write(start_response, response) diff --git a/tests/raw_upstream.py b/tests/raw_upstream.py new file mode 100644 index 0000000..4afe9d2 --- /dev/null +++ b/tests/raw_upstream.py @@ -0,0 +1,84 @@ +"""A raw socket upstream on 127.0.0.1, for answers httpx mocks cannot express.""" + +from __future__ import annotations + +import socket +import threading +from typing import Any + +from test_proxy import PATH, PROXY_KEY + +from fingerly import FingerlyProxy + + +class RawUpstream: + """A socket server on 127.0.0.1 that answers every request with fixed bytes. + + Attributes: + port: The bound port. + hits: How many requests it received. + """ + + def __init__(self, answer: bytes) -> None: + self._answer = answer + self._socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM) + self._socket.bind(("127.0.0.1", 0)) + self._socket.listen(16) + self.port: int = self._socket.getsockname()[1] + self.hits = 0 + self._thread = threading.Thread(target=self._serve, daemon=True) + self._thread.start() + + @property + def origin(self) -> str: + return f"http://127.0.0.1:{self.port}" + + def _serve(self) -> None: + while True: + try: + connection, _ = self._socket.accept() + except OSError: + return + with connection: + connection.settimeout(2) + data = b"" + try: + while b"\r\n\r\n" not in data: + chunk = connection.recv(65536) + if not chunk: + break + data += chunk + head, _, rest = data.partition(b"\r\n\r\n") + length = 0 + for line in head.split(b"\r\n")[1:]: + name, _, value = line.partition(b":") + if name.strip().lower() == b"content-length": + length = int(value.strip()) + while len(rest) < length: + chunk = connection.recv(65536) + if not chunk: + break + rest += chunk + self.hits += 1 + connection.sendall(self._answer) + except OSError: + continue + + def close(self) -> None: + self._socket.close() + + +def answering(status: str, extra: str = "") -> RawUpstream: + """A raw upstream whose every answer has this status line code.""" + return RawUpstream( + f"HTTP/1.1 {status} Answer\r\n{extra}content-type: application/json\r\n" + "content-length: 2\r\nconnection: close\r\n\r\n{}".encode() + ) + + +def real(upstream: str, **options: Any) -> FingerlyProxy: + """A proxy that sends over the network to a loopback upstream.""" + options.setdefault("proxy_key", PROXY_KEY) + options.setdefault("path", PATH) + options.setdefault("client_ip", lambda request: "203.0.113.10") + return FingerlyProxy(upstream=upstream, allow_insecure_loopback=True, **options) diff --git a/tests/test_client_endpoint.py b/tests/test_client_endpoint.py new file mode 100644 index 0000000..4d0724e --- /dev/null +++ b/tests/test_client_endpoint.py @@ -0,0 +1,93 @@ +"""The events client accepts only a bare https origin as its endpoint.""" + +from __future__ import annotations + +from typing import Any + +import pytest +from conftest import SECRET_KEY, Recorder, event_body, json_response + +from fingerly import AsyncFingerly, Fingerly + +CLIENTS = [Fingerly, AsyncFingerly] + + +@pytest.mark.parametrize("cls", CLIENTS) +@pytest.mark.parametrize( + "endpoint", + [ + "http://api.invalid", + "http://192.0.2.10:8080", + "https://api.invalid/prefix", + "https://api.invalid/a/../b", + "https://api.invalid//", + "https://api.invalid?", + "https://api.invalid?x=1", + "https://api.invalid#", + "https://api.invalid#f", + "https://user:pass@api.invalid", + "https://@api.invalid", + "https://api.invalid\n", + "https://api.invalid ", + " https://api.invalid", + "https://api.invalid\r\nx-injected: 1", + "https://api.invalid\t", + "https://é.invalid", + "ftp://api.invalid", + "api.invalid", + "", + ], +) +def test_refuses_anything_but_a_bare_https_origin(cls: Any, endpoint: str) -> None: + for allow in (False, True): + with pytest.raises(TypeError, match="endpoint must") as raised: + cls( + secret_key=SECRET_KEY, + endpoint=endpoint, + allow_insecure_loopback=allow, + ) + message = str(raised.value) + assert "api.invalid" not in message + assert SECRET_KEY not in message + + +@pytest.mark.parametrize("cls", CLIENTS) +@pytest.mark.parametrize( + "endpoint", ["http://127.0.0.1:9", "http://localhost:9", "http://[::1]:9"] +) +def test_plain_http_loopback_needs_the_flag(cls: Any, endpoint: str) -> None: + with pytest.raises(TypeError, match="allow_insecure_loopback"): + cls(secret_key=SECRET_KEY, endpoint=endpoint) + cls(secret_key=SECRET_KEY, endpoint=endpoint, allow_insecure_loopback=True) + + +def test_the_flag_must_be_a_bool() -> None: + with pytest.raises(TypeError): + Fingerly( + secret_key=SECRET_KEY, + allow_insecure_loopback="yes", # type: ignore[arg-type] + ) + + +@pytest.mark.parametrize( + ("endpoint", "expected"), + [ + ("https://api.invalid", "https://api.invalid/api/v1/events/id"), + ("https://api.invalid/", "https://api.invalid/api/v1/events/id"), + ("https://api.invalid:8443", "https://api.invalid:8443/api/v1/events/id"), + ("https://API.invalid", "https://api.invalid/api/v1/events/id"), + ("http://127.0.0.1:9", "http://127.0.0.1:9/api/v1/events/id"), + ], +) +def test_the_base_url_is_rebuilt_from_scheme_host_and_port( + endpoint: str, expected: str +) -> None: + recorder = Recorder(json_response(event_body())) + with Fingerly( + secret_key=SECRET_KEY, + endpoint=endpoint, + allow_insecure_loopback=True, + transport=recorder.transport(), + ) as fingerly: + fingerly.events.get("id") + assert recorder.url == expected diff --git a/tests/test_contract.py b/tests/test_contract.py index 4adadfb..7e82118 100644 --- a/tests/test_contract.py +++ b/tests/test_contract.py @@ -16,7 +16,14 @@ from referencing import Registry, Resource from referencing.jsonschema import DRAFT202012 -from fingerly import Fingerly, FingerlyAPIError, verify_webhook +from fingerly import ( + SIGNAL_NAMES, + Attestation, + EventDocument, + Fingerly, + FingerlyAPIError, + verify_webhook, +) CONTRACT = Path(__file__).resolve().parent.parent / "contract" SPEC: dict[str, Any] = json.loads((CONTRACT / "openapi.json").read_text()) @@ -138,3 +145,127 @@ def test_rejects_a_stale_server_signing_fixture(self) -> None: signature=fixture["signature"], now=stale, ) + + +class TestV3Contract: + def test_v3_openapi_and_models(self) -> None: + assert "/api/v1/events/{request_id}/supplement" not in SPEC["paths"] + assert "SupplementOut" not in SPEC["components"]["schemas"] + assert "AttestEnvelope" in SPEC["components"]["schemas"] + + v3_signals = [ + "attestation_failed", + "attestation_downgrade", + "device_inconsistent", + "report_incomplete", + "probe_errors", + "fetch_metadata_missing", + "web_ticket_missing", + "web_ticket_invalid", + "tampering", + "custom_root_ca", + "secondary_user_profile", + ] + for sig in v3_signals: + assert sig in SIGNAL_NAMES + + payload: dict[str, Any] = { + "request_id": "0199a963-e400-7000-8000-000000000099", + "project_id": "0199a963-e400-7000-8000-0000000000a1", + "visitor_id": "", + "occurred_at": "2026-09-17T12:00:00Z", + "state": "unavailable", + "reason": "ip_lookup_failed", + "environment": "development", + "platform": "android", + "sdk_platform": "android", + "sdk_version": "0.3.0", + "url_host": "shop.test", + "url_path": "/checkout", + "suspect_score": None, + "triggers": [ + {"signal": sig, "weight": 4, "confidence": "high"} for sig in v3_signals + ], + "has_document": True, + "document": { + "schema": 1, + "request_id": "0199a963-e400-7000-8000-000000000099", + "occurred_at": "2026-09-17T12:00:00Z", + "sdk": {"platform": "android", "version": "0.3.0"}, + "ip_network": "203.0.113.0/24", + "attestation": { + "state": "attested", + "platform": "android", + "status": "verified", + "revocation_checked": True, + "package_bound": True, + "signer_bound": True, + }, + }, + } + errors = list(validator_for("SDKEventOut").iter_errors(payload)) + assert not errors, [err.message for err in errors] + + with Fingerly( + secret_key=SECRET_KEY, + transport=Recorder(json_response(payload)).transport(), + ) as client: + event = client.events.get(payload["request_id"]) + + assert event.visitor_id == "" + assert event.identifiable is False + assert event.reason == "ip_lookup_failed" + assert event.url_host == "shop.test" + assert event.url_path == "/checkout" + assert [t.signal for t in event.triggers] == v3_signals + doc = event.parse_document() + assert isinstance(doc, EventDocument) + assert isinstance(doc.attestation, Attestation) + assert doc.attestation.status == "verified" + assert doc.attestation.platform == "android" + assert doc.attestation.attest_skipped is None + assert doc.attestation.downgrade is False + + def test_reads_attest_skipped_and_downgrade(self) -> None: + payload: dict[str, Any] = { + "request_id": "0199a963-e400-7000-8000-000000000098", + "project_id": "0199a963-e400-7000-8000-0000000000a1", + "visitor_id": "", + "occurred_at": "2026-09-17T12:00:00Z", + "state": "enriched", + "environment": "development", + "platform": "ios", + "sdk_platform": "ios", + "sdk_version": "0.3.0", + "suspect_score": 30, + "suspect_level": "high", + "triggers": [ + {"signal": "attestation_failed", "weight": 30, "confidence": "high"} + ], + "has_document": True, + "document": { + "schema": 1, + "request_id": "0199a963-e400-7000-8000-000000000098", + "occurred_at": "2026-09-17T12:00:00Z", + "sdk": {"platform": "ios", "version": "0.3.0"}, + "attestation": { + "state": "not_attested", + "platform": "ios", + "status": "absent", + "attest_skipped": "timeout", + "downgrade": True, + }, + }, + } + + with Fingerly( + secret_key=SECRET_KEY, + transport=Recorder(json_response(payload)).transport(), + ) as client: + event = client.events.get(payload["request_id"]) + + doc = event.parse_document() + assert isinstance(doc, EventDocument) + assert isinstance(doc.attestation, Attestation) + assert doc.attestation.attest_skipped == "timeout" + assert doc.attestation.downgrade is True diff --git a/tests/test_device_check.py b/tests/test_device_check.py new file mode 100644 index 0000000..715de8b --- /dev/null +++ b/tests/test_device_check.py @@ -0,0 +1,291 @@ +"""DeviceCheck reads and writes: shapes, typed errors and the retry rule.""" + +from __future__ import annotations + +import json +from typing import Any + +import httpx +import pytest +from conftest import SECRET_KEY, Recorder, error_response, json_response, run + +import fingerly._client as client_module +from fingerly import ( + AsyncFingerly, + DeviceCheckBits, + DeviceCheckWriteResult, + Fingerly, + FingerlyAPIError, + FingerlyConnectionError, + FingerlyDeviceCheckError, +) + +REQUEST_ID = "0199a963-e400-7000-8000-000000000001" +BASE = "https://api.fingerly.io/api/v1/events/" + REQUEST_ID + + +@pytest.fixture(autouse=True) +def no_pause(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setattr(client_module, "_DEVICE_CHECK_RETRY_DELAYS", (0.0, 0.0)) + + +def sync_client(recorder: Recorder) -> Fingerly: + return Fingerly(secret_key=SECRET_KEY, transport=recorder.transport()) + + +def async_client(recorder: Recorder) -> AsyncFingerly: + return AsyncFingerly(secret_key=SECRET_KEY, transport=recorder.transport()) + + +def query_both(recorder: Recorder) -> list[Any]: + """Runs the same query on the sync and the async client.""" + results: list[Any] = [] + for build in (sync_client, async_client): + try: + if build is sync_client: + results.append(sync_client(recorder).device_check.query(REQUEST_ID)) + else: + + async def go() -> DeviceCheckBits: + async with async_client(recorder) as fingerly: + return await fingerly.device_check.query(REQUEST_ID) + + results.append(run(go())) + except FingerlyAPIError as error: + results.append(error) + return results + + +def write_both(recorder: Recorder, **bits: Any) -> list[Any]: + results: list[Any] = [] + try: + results.append(sync_client(recorder).device_check.write(REQUEST_ID, **bits)) + except FingerlyAPIError as error: + results.append(error) + + async def go() -> DeviceCheckWriteResult: + async with async_client(recorder) as fingerly: + return await fingerly.device_check.write(REQUEST_ID, **bits) + + try: + results.append(run(go())) + except FingerlyAPIError as error: + results.append(error) + return results + + +def apple_rejected(status: int) -> httpx.Response: + return json_response( + { + "error": { + "code": "apple_rejected", + "message": "Apple rejected the request", + "status": 422, + "details": [ + { + "field": "apple_status", + "location": "upstream", + "issue": str(status), + } + ], + }, + "request_id": "trace", + }, + 422, + ) + + +class TestShapes: + def test_query_posts_with_no_body_and_reads_the_bits(self) -> None: + recorder = Recorder( + json_response( + {"found": True, "bit0": True, "bit1": False, "last_update": "2026-10"} + ) + ) + results = query_both(recorder) + assert ( + results + == [ + DeviceCheckBits( + found=True, bit0=True, bit1=False, last_update="2026-10" + ) + ] + * 2 + ) + for request in recorder.requests: + assert request.method == "POST" + assert str(request.url) == BASE + "/device-check/query" + assert request.headers["x-api-key"] == SECRET_KEY + assert request.content == b"" + + def test_query_without_bits_has_no_last_update(self) -> None: + recorder = Recorder( + json_response({"found": False, "bit0": False, "bit1": False}) + ) + assert ( + query_both(recorder) + == [DeviceCheckBits(found=False, bit0=False, bit1=False, last_update=None)] + * 2 + ) + + def test_write_puts_only_the_named_bits(self) -> None: + recorder = Recorder(json_response({"bit1": True})) + results = write_both(recorder, bit1=True) + assert results == [DeviceCheckWriteResult(bit0=None, bit1=True)] * 2 + for request in recorder.requests: + assert request.method == "PUT" + assert str(request.url) == BASE + "/device-check" + assert request.headers["x-api-key"] == SECRET_KEY + assert request.headers["content-type"] == "application/json" + assert json.loads(request.content) == {"bit1": True} + + def test_write_sends_false(self) -> None: + recorder = Recorder(json_response({"bit0": False, "bit1": True})) + assert ( + write_both(recorder, bit0=False, bit1=True) + == [DeviceCheckWriteResult(bit0=False, bit1=True)] * 2 + ) + assert json.loads(recorder.requests[0].content) == {"bit0": False, "bit1": True} + + def test_write_with_no_bit_sends_nothing(self) -> None: + recorder = Recorder(json_response({})) + with pytest.raises(TypeError): + sync_client(recorder).device_check.write(REQUEST_ID) + with pytest.raises(TypeError): + sync_client(recorder).device_check.write(REQUEST_ID, bit0=1) # type: ignore[arg-type] + + async def go() -> None: + async with async_client(recorder) as fingerly: + await fingerly.device_check.write(REQUEST_ID) + + with pytest.raises(TypeError): + run(go()) + assert recorder.calls == 0 + + def test_request_id_is_one_segment(self) -> None: + recorder = Recorder( + json_response({"found": False, "bit0": False, "bit1": False}) + ) + sync_client(recorder).device_check.query("../a") + assert recorder.url == ( + "https://api.fingerly.io/api/v1/events/%2E%2E%2Fa/device-check/query" + ) + + +class TestErrors: + @pytest.mark.parametrize( + ("code", "status"), + [ + ("device_check_not_held", 404), + ("device_check_spent", 409), + ("device_check_busy", 409), + ("credential_unavailable", 409), + ("bits_required", 422), + ], + ) + def test_each_code_is_typed_and_not_retried(self, code: str, status: int) -> None: + recorder = Recorder(error_response(code, status)) + for result in query_both(recorder) + write_both(recorder, bit0=True): + assert isinstance(result, FingerlyDeviceCheckError) + assert result.code == code + assert result.status == status + assert result.apple_status is None + assert result.request_id == "trace" + assert recorder.calls == 4 + + def test_apple_rejected_carries_apples_status(self) -> None: + recorder = Recorder(apple_rejected(400)) + for result in query_both(recorder) + write_both(recorder, bit0=True): + assert isinstance(result, FingerlyDeviceCheckError) + assert result.code == "apple_rejected" + assert result.status == 422 + assert result.apple_status == 400 + assert recorder.calls == 4 + + @pytest.mark.parametrize("status", [429, 500, 502]) + def test_other_failures_are_not_retried(self, status: int) -> None: + recorder = Recorder(error_response("server_error", status)) + for result in query_both(recorder): + assert isinstance(result, FingerlyDeviceCheckError) + assert result.status == status + assert recorder.calls == 2 + + +class TestRetry: + def test_503_retries_the_identical_write(self) -> None: + recorder = Recorder( + error_response("device_check_unavailable", 503), + json_response({"bit0": True}), + ) + assert sync_client(recorder).device_check.write( + REQUEST_ID, bit0=True + ) == DeviceCheckWriteResult(bit0=True) + assert recorder.calls == 2 + first, second = recorder.requests + assert (first.method, str(first.url), first.content) == ( + second.method, + str(second.url), + second.content, + ) + assert json.loads(second.content) == {"bit0": True} + + def test_503_retries_the_identical_query_async(self) -> None: + recorder = Recorder( + error_response("device_check_unavailable", 503), + error_response("device_check_unavailable", 503), + json_response({"found": True, "bit0": False, "bit1": True}), + ) + + async def go() -> DeviceCheckBits: + async with async_client(recorder) as fingerly: + return await fingerly.device_check.query(REQUEST_ID) + + assert run(go()) == DeviceCheckBits(found=True, bit0=False, bit1=True) + assert recorder.calls == 3 + assert {(r.method, str(r.url), r.content) for r in recorder.requests} == { + ("POST", BASE + "/device-check/query", b"") + } + + def test_503_gives_up_after_three_attempts(self) -> None: + recorder = Recorder(error_response("device_check_unavailable", 503)) + results = write_both(recorder, bit1=False) + for result in results: + assert isinstance(result, FingerlyDeviceCheckError) + assert result.code == "device_check_unavailable" + assert recorder.calls == 6 + + def test_transport_failure_retries_the_same_request(self) -> None: + seen: list[httpx.Request] = [] + + def flaky(request: httpx.Request) -> httpx.Response: + seen.append(request) + if len(seen) == 1: + raise httpx.ConnectError("refused", request=request) + return json_response({"bit0": True}) + + recorder = Recorder.of(flaky) + assert sync_client(recorder).device_check.write( + REQUEST_ID, bit0=True + ) == DeviceCheckWriteResult(bit0=True) + assert len(seen) == 2 + assert seen[0].content == seen[1].content == b'{"bit0":true}' + + def test_transport_failure_surfaces_after_the_retries(self) -> None: + def down(request: httpx.Request) -> httpx.Response: + raise httpx.ConnectError("refused", request=request) + + recorder = Recorder.of(down) + with pytest.raises(FingerlyConnectionError): + sync_client(recorder).device_check.query(REQUEST_ID) + assert recorder.calls == 3 + + def test_409_after_a_503_is_not_retried(self) -> None: + recorder = Recorder( + error_response("device_check_unavailable", 503), + error_response("device_check_spent", 409), + json_response({"bit0": True}), + ) + with pytest.raises(FingerlyDeviceCheckError) as raised: + sync_client(recorder).device_check.write(REQUEST_ID, bit0=True) + assert raised.value.code == "device_check_spent" + assert recorder.calls == 2 diff --git a/tests/test_events_verify.py b/tests/test_events_verify.py new file mode 100644 index 0000000..b15cc96 --- /dev/null +++ b/tests/test_events_verify.py @@ -0,0 +1,390 @@ +"""Consuming events and verifying one before a backend action.""" + +from __future__ import annotations + +from datetime import datetime, timedelta, timezone +from typing import Any, Callable, Optional + +import httpx +import pytest +from conftest import ( + SECRET_KEY, + Recorder, + _fresh, + error_response, + event_body, + json_response, + run, +) + +from fingerly import ( + AsyncFingerly, + ConsumeResult, + Fingerly, + FingerlyAPIError, + FingerlyEventAlreadyConsumedError, + FingerlyEventPendingError, + VerifyResult, +) + +REQUEST_ID = "0199a963-e400-7000-8000-000000000001" +EVENT_PATH = "/api/v1/events/" + REQUEST_ID +CONSUME_PATH = EVENT_PATH + "/consume" +CONSUMED_AT = "2026-11-17T10:00:00Z" + +#: The literal 409 body and the standard error envelope carrying the same time. +ALREADY_CONSUMED_BODIES = [ + {"code": "event_already_consumed", "consumed_at": CONSUMED_AT}, + { + "error": { + "code": "event_already_consumed", + "message": "Event already consumed", + "status": 409, + "details": [ + {"field": "consumed_at", "issue": CONSUMED_AT, "location": "body"} + ], + } + }, +] + + +def ago(seconds: float) -> str: + """An RFC 3339 time that many seconds before now.""" + moment = datetime.now(timezone.utc) - timedelta(seconds=seconds) + return moment.isoformat().replace("+00:00", "Z") + + +def fresh_event(**overrides: Any) -> dict[str, Any]: + """An event that passes every verify check.""" + body = event_body(occurred_at=ago(10), suspect_score=12, tag="checkout") + body.update(overrides) + return body + + +def consumed() -> httpx.Response: + return json_response( + {"request_id": REQUEST_ID, "consumed_at": CONSUMED_AT, "first": True} + ) + + +def api( + get: Optional[httpx.Response] = None, post: Optional[httpx.Response] = None +) -> Recorder: + """A recorder answering the event read and the consume by route.""" + + def answer(request: httpx.Request) -> httpx.Response: + if request.method == "GET" and request.url.path == EVENT_PATH and get: + return _fresh(get) + if request.method == "POST" and request.url.path == CONSUME_PATH and post: + return _fresh(post) + raise AssertionError(f"unexpected {request.method} {request.url.path}") + + return Recorder.of(answer) + + +def posts(recorder: Recorder) -> int: + return sum(1 for request in recorder.requests if request.method == "POST") + + +def on_both( + build: Callable[[], Recorder], method: str, *args: Any, **kwargs: Any +) -> list[tuple[Any, Recorder]]: + """Runs one events call on the sync and the async client. + + Returns: + For each client, the result or the raised error, and its recorder. + """ + outcomes: list[tuple[Any, Recorder]] = [] + recorder = build() + try: + client = Fingerly(secret_key=SECRET_KEY, transport=recorder.transport()) + outcomes.append((getattr(client.events, method)(*args, **kwargs), recorder)) + except Exception as error: + outcomes.append((error, recorder)) + + recorder = build() + + async def go() -> Any: + async with AsyncFingerly( + secret_key=SECRET_KEY, transport=recorder.transport() + ) as fingerly: + return await getattr(fingerly.events, method)(*args, **kwargs) + + try: + outcomes.append((run(go()), recorder)) + except Exception as error: + outcomes.append((error, recorder)) + return outcomes + + +class TestConsume: + def test_decodes_the_first_consumption(self) -> None: + for result, recorder in on_both( + lambda: api(post=consumed()), "consume", REQUEST_ID + ): + assert result == ConsumeResult( + request_id=REQUEST_ID, consumed_at=CONSUMED_AT, first=True + ) + (request,) = recorder.requests + assert request.method == "POST" + assert request.url.raw_path == CONSUME_PATH.encode() + assert request.headers["x-api-key"] == SECRET_KEY + assert request.content == b"" + + def test_escapes_the_request_id_into_one_segment(self) -> None: + recorder = Recorder(consumed()) + client = Fingerly(secret_key=SECRET_KEY, transport=recorder.transport()) + client.events.consume("a/b.c") + assert recorder.requests[0].url.raw_path == ( + b"/api/v1/events/a%2Fb%2Ec/consume" + ) + + @pytest.mark.parametrize("body", ALREADY_CONSUMED_BODIES) + def test_a_second_consumption_raises_the_typed_error( + self, body: dict[str, Any] + ) -> None: + build = lambda: api(post=json_response(body, 409)) # noqa: E731 + for error, _ in on_both(build, "consume", REQUEST_ID): + assert isinstance(error, FingerlyEventAlreadyConsumedError) + assert isinstance(error, FingerlyAPIError) + assert error.status == 409 + assert error.code == "event_already_consumed" + assert error.consumed_at == CONSUMED_AT + assert str(error) == "Fingerly API returned HTTP 409" + + def test_a_missing_consumed_at_is_none(self) -> None: + recorder = Recorder(error_response("event_already_consumed", 409)) + client = Fingerly(secret_key=SECRET_KEY, transport=recorder.transport()) + with pytest.raises(FingerlyEventAlreadyConsumedError) as caught: + client.events.consume(REQUEST_ID) + assert caught.value.consumed_at is None + + def test_an_unknown_event_raises_the_plain_api_error(self) -> None: + build = lambda: api(post=error_response("event_not_found", 404)) # noqa: E731 + for error, _ in on_both(build, "consume", REQUEST_ID): + assert type(error) is FingerlyAPIError + assert error.status == 404 + assert error.code == "event_not_found" + + def test_is_never_retried(self) -> None: + build = lambda: api(post=error_response("unavailable", 503)) # noqa: E731 + for error, recorder in on_both(build, "consume", REQUEST_ID): + assert isinstance(error, FingerlyAPIError) + assert recorder.calls == 1 + + def test_an_empty_request_id_is_refused_before_any_request(self) -> None: + for error, recorder in on_both(api, "consume", ""): + assert isinstance(error, TypeError) + assert recorder.calls == 0 + + +def verify_both( + get: Optional[httpx.Response] = None, + post: Optional[httpx.Response] = None, + **options: Any, +) -> list[tuple[Any, Recorder]]: + return on_both(lambda: api(get, post), "verify", REQUEST_ID, **options) + + +class TestVerify: + def test_ok_consumes_once_after_the_read(self) -> None: + get = json_response(fresh_event()) + for result, recorder in verify_both(get, consumed(), tag="checkout"): + assert isinstance(result, VerifyResult) + assert result.ok is True + assert result.reason == "" + assert result.event is not None + assert result.event.request_id == REQUEST_ID + methods = [(r.method, r.url.raw_path) for r in recorder.requests] + assert methods == [ + ("GET", EVENT_PATH.encode()), + ("POST", CONSUME_PATH.encode()), + ] + + def test_not_found_on_the_read(self) -> None: + get = error_response("event_not_found", 404) + for result, recorder in verify_both(get): + assert result == VerifyResult(ok=False, reason="not_found", event=None) + assert posts(recorder) == 0 + + def test_too_old(self) -> None: + get = json_response(fresh_event(occurred_at=ago(3600))) + for result, recorder in verify_both(get): + assert (result.ok, result.reason) == (False, "too_old") + assert result.event is not None + assert posts(recorder) == 0 + + @pytest.mark.parametrize("occurred_at", ["yesterday", "2026-13-45T00:00:00Z", 5]) + def test_an_unreadable_time_is_too_old(self, occurred_at: Any) -> None: + get = json_response(fresh_event(occurred_at=occurred_at)) + for result, recorder in verify_both(get): + assert (result.ok, result.reason) == (False, "too_old") + assert result.event is not None + assert result.event.raw["occurred_at"] == occurred_at + assert posts(recorder) == 0 + + def test_a_missing_time_is_too_old(self) -> None: + body = fresh_event() + del body["occurred_at"] + for result, recorder in verify_both(json_response(body)): + assert (result.ok, result.reason) == (False, "too_old") + assert posts(recorder) == 0 + + def test_a_future_time_passes_the_age_check(self) -> None: + get = json_response(fresh_event(occurred_at=ago(-120))) + for result, _ in verify_both(get, consumed()): + assert result.ok is True + + def test_default_max_age_is_300_seconds(self) -> None: + for result, _ in verify_both( + json_response(fresh_event(occurred_at=ago(200))), consumed() + ): + assert result.ok is True + for result, _ in verify_both(json_response(fresh_event(occurred_at=ago(400)))): + assert result.reason == "too_old" + + def test_max_age_seconds_is_honoured(self) -> None: + get = json_response(fresh_event(occurred_at=ago(200))) + for result, _ in verify_both(get, max_age_seconds=100): + assert result.reason == "too_old" + get = json_response(fresh_event(occurred_at=ago(400))) + for result, _ in verify_both(get, consumed(), max_age_seconds=600): + assert result.ok is True + + @pytest.mark.parametrize("event_tag", ["signup", None, ""]) + def test_tag_mismatch(self, event_tag: Optional[str]) -> None: + body = fresh_event(tag=event_tag) + if event_tag is None: + del body["tag"] + for result, recorder in verify_both(json_response(body), tag="checkout"): + assert (result.ok, result.reason) == (False, "tag_mismatch") + assert result.event is not None + assert posts(recorder) == 0 + + def test_no_tag_option_skips_the_tag_check(self) -> None: + get = json_response(fresh_event(tag="anything")) + for result, _ in verify_both(get, consumed()): + assert result.ok is True + + @pytest.mark.parametrize("visitor_id", ["", None]) + def test_unidentifiable(self, visitor_id: Optional[str]) -> None: + body = fresh_event(visitor_id=visitor_id) + if visitor_id is None: + del body["visitor_id"] + for result, recorder in verify_both(json_response(body)): + assert (result.ok, result.reason) == (False, "unidentifiable") + assert result.event is not None + assert posts(recorder) == 0 + + def test_unscored(self) -> None: + body = fresh_event() + del body["suspect_score"] + for result, recorder in verify_both(json_response(body)): + assert (result.ok, result.reason) == (False, "unscored") + assert posts(recorder) == 0 + for result, recorder in verify_both( + json_response(fresh_event(suspect_score=None)) + ): + assert result.reason == "unscored" + assert posts(recorder) == 0 + + def test_the_score_value_is_not_judged(self) -> None: + get = json_response( + fresh_event( + suspect_score=100, + suspect_level="high", + triggers=[{"signal": "tor", "weight": 100}], + ) + ) + for result, _ in verify_both(get, consumed()): + assert result.ok is True + + @pytest.mark.parametrize("body", ALREADY_CONSUMED_BODIES) + def test_already_consumed(self, body: dict[str, Any]) -> None: + get = json_response(fresh_event()) + for result, recorder in verify_both(get, json_response(body, 409)): + assert (result.ok, result.reason) == (False, "already_consumed") + assert result.event is not None + assert posts(recorder) == 1 + + def test_not_found_on_consume(self) -> None: + get = json_response(fresh_event()) + post = error_response("event_not_found", 404) + for result, recorder in verify_both(get, post): + assert result == VerifyResult(ok=False, reason="not_found", event=None) + assert posts(recorder) == 1 + + def test_other_consume_errors_are_raised(self) -> None: + get = json_response(fresh_event()) + for error, recorder in verify_both(get, error_response("unavailable", 503)): + assert isinstance(error, FingerlyAPIError) + assert error.status == 503 + assert posts(recorder) == 1 + + def test_consume_false_never_posts(self) -> None: + get = json_response(fresh_event()) + for result, recorder in verify_both(get, consume=False): + assert result.ok is True + assert result.reason == "" + assert posts(recorder) == 0 + + def test_checks_stop_at_the_first_failure_in_order(self) -> None: + cases = [ + ( + { + "occurred_at": ago(3600), + "tag": "other", + "visitor_id": "", + "suspect_score": None, + }, + "too_old", + ), + ({"tag": "other", "visitor_id": "", "suspect_score": None}, "tag_mismatch"), + ({"visitor_id": "", "suspect_score": None}, "unidentifiable"), + ] + for overrides, reason in cases: + get = json_response(fresh_event(**overrides)) + for result, recorder in verify_both(get, tag="checkout"): + assert result.reason == reason + assert posts(recorder) == 0 + + @pytest.mark.parametrize( + ("get", "kind"), + [ + (error_response("event_pending", 404), FingerlyEventPendingError), + (error_response("unauthorized", 401), FingerlyAPIError), + (error_response("rate_limited", 429), FingerlyAPIError), + (error_response("internal", 500), FingerlyAPIError), + ], + ) + def test_read_errors_other_than_not_found_are_raised( + self, get: httpx.Response, kind: type + ) -> None: + for error, recorder in verify_both(get): + assert isinstance(error, kind) + assert recorder.calls == 1 + + @pytest.mark.parametrize( + "options", + [ + {"max_age_seconds": 0}, + {"max_age_seconds": -5}, + {"max_age_seconds": 1.5}, + {"max_age_seconds": True}, + {"max_age_seconds": "300"}, + {"tag": ""}, + {"tag": 5}, + {"consume": "yes"}, + ], + ) + def test_invalid_options_are_refused_before_any_request( + self, options: dict[str, Any] + ) -> None: + for error, recorder in verify_both(**options): + assert isinstance(error, TypeError) + assert recorder.calls == 0 + + def test_an_empty_request_id_is_refused_before_any_request(self) -> None: + for error, recorder in on_both(api, "verify", ""): + assert isinstance(error, TypeError) + assert recorder.calls == 0 diff --git a/tests/test_frameworks.py b/tests/test_frameworks.py index b171818..7e8581c 100644 --- a/tests/test_frameworks.py +++ b/tests/test_frameworks.py @@ -108,9 +108,17 @@ def test_forwards_from_a_route_at_the_issued_path(self) -> None: assert str(forwarded.url) == INGEST assert forwarded.headers["x-fingerly-client-ip"] == "203.0.113.5" assert forwarded.headers["x-fingerly-proxy-key"] == PROXY_KEY - assert forwarded.headers["x-fingerly-proxy-version"] == "python/0.2.0" + assert forwarded.headers["x-fingerly-proxy-version"] == "python/0.3.0" assert "cookie" not in forwarded.headers + (missing_origin,) = self.post( + app, + [PATH], + headers={"x-api-key": PUBLIC_KEY, "cf-connecting-ip": "203.0.113.5"}, + ) + assert missing_origin.status_code == 400 + assert missing_origin.json()["error"]["code"] == "missing_origin" + def test_a_mount_at_the_issued_path_answers_nothing(self) -> None: # Starlette redirects the bare mount path to its slashed form, and the # proxy answers the exact path only, which is why the README routes. @@ -176,16 +184,36 @@ def home() -> str: def test_forwards_beside_the_host_app(self) -> None: upstream = Upstream() + raw_v3 = b'{"v":3,"signals":{"latency":142.50}}' with self.flask_client(build(upstream)) as client: - identified = client.post( - PATH, headers=BROWSER_HEADERS, content=b'{"signals":{}}' + identified = client.post(PATH, headers=BROWSER_HEADERS, content=raw_v3) + native = client.post( + PATH, + headers={ + "x-api-key": PUBLIC_KEY, + "cf-connecting-ip": "203.0.113.5", + "x-fingerly-sdk-platform": "android", + "idempotency-key": "idem-flask-v3-0001", + }, + content=raw_v3, + ) + missing_origin = client.post( + PATH, + headers={ + "x-api-key": PUBLIC_KEY, + "cf-connecting-ip": "203.0.113.5", + }, + content=raw_v3, ) - reported = client.post( - PATH, headers=BROWSER_HEADERS, content=b'{"token":"deferred"}' + supplement = client.post( + PATH + "/supplement", headers=BROWSER_HEADERS, content=raw_v3 ) home = client.get("/") - assert (identified.status_code, reported.status_code) == (200, 200) + assert (identified.status_code, native.status_code) == (200, 200) + assert missing_origin.status_code == 400 + assert missing_origin.json()["error"]["code"] == "missing_origin" + assert supplement.status_code == 404 assert identified.json() == {"request_id": "identified"} assert identified.headers["cache-control"] == "no-store" assert_relays_nothing_naming_fingerly(identified) @@ -194,9 +222,14 @@ def test_forwards_beside_the_host_app(self) -> None: assert [str(request.url) for request in upstream.requests] == [INGEST] * 2 forwarded = upstream.requests[0] + assert forwarded.content == raw_v3 assert forwarded.headers["x-fingerly-client-ip"] == "203.0.113.5" - assert forwarded.headers["x-fingerly-proxy-version"] == "python/0.2.0" + assert forwarded.headers["x-fingerly-proxy-version"] == "python/0.3.0" assert "cookie" not in forwarded.headers + native_forwarded = upstream.requests[1] + assert native_forwarded.content == raw_v3 + assert native_forwarded.headers["x-fingerly-sdk-platform"] == "android" + assert "x-fingerly-origin" not in native_forwarded.headers def test_forwards_from_a_deployment_under_a_sub_uri(self) -> None: # DispatcherMiddleware rather than httpx's script_name, because httpx diff --git a/tests/test_http.py b/tests/test_http.py index 48c5f79..29fea1c 100644 --- a/tests/test_http.py +++ b/tests/test_http.py @@ -121,7 +121,12 @@ def test_a_trickling_upstream_cannot_extend_a_sync_read( self, upstream: Upstream ) -> None: upstream.mode = "trickle" - with Fingerly(secret_key=SECRET_KEY, endpoint=upstream.url, timeout=0.5) as f: + with Fingerly( + secret_key=SECRET_KEY, + endpoint=upstream.url, + timeout=0.5, + allow_insecure_loopback=True, + ) as f: started = time.monotonic() with pytest.raises(FingerlyTimeoutError): f.events.get("id") @@ -134,7 +139,10 @@ def test_a_trickling_upstream_cannot_extend_an_async_read( async def read() -> float: async with AsyncFingerly( - secret_key=SECRET_KEY, endpoint=upstream.url, timeout=0.5 + secret_key=SECRET_KEY, + endpoint=upstream.url, + timeout=0.5, + allow_insecure_loopback=True, ) as f: started = time.monotonic() with pytest.raises(FingerlyTimeoutError): diff --git a/tests/test_packaging.py b/tests/test_packaging.py index 9f63abd..20948ce 100644 --- a/tests/test_packaging.py +++ b/tests/test_packaging.py @@ -40,6 +40,7 @@ def test_the_proxy_identifies_itself_upstream() -> None: "PATH_INFO": "/p", "CONTENT_LENGTH": "2", "HTTP_X_API_KEY": "fly_pk_development_test", + "HTTP_ORIGIN": "https://shop.test", "wsgi.input": __import__("io").BytesIO(b"{}"), } proxy.wsgi(environ, lambda status, headers: None) diff --git a/tests/test_proxy.py b/tests/test_proxy.py index 889df9b..c3509f3 100644 --- a/tests/test_proxy.py +++ b/tests/test_proxy.py @@ -27,6 +27,7 @@ PUBLIC_KEY = "fly_pk_development_test" PATH = "/k7x2qm4a" INGEST = "https://api.fingerly.io/api/v1/ingest" +BROWSER = {"x-api-key": PUBLIC_KEY, "origin": "https://shop.test"} def proxy(recorder: Recorder, **options: Any) -> FingerlyProxy: @@ -153,10 +154,6 @@ class TestConstruction: def test_requires_a_proxy_key_and_a_client_ip(self) -> None: with pytest.raises(TypeError): FingerlyProxy(client_ip=lambda request: "") - with pytest.raises(TypeError): - FingerlyProxy( - client_ip=lambda request: "", proxy_key=PROXY_KEY, secret_key="x" - ) with pytest.raises(TypeError): FingerlyProxy(client_ip=None, proxy_key=PROXY_KEY) # type: ignore[arg-type] @@ -176,7 +173,7 @@ def test_normalizes_trailing_slashes_off_the_path(self) -> None: for adapter, call in both( proxy(recorder := Recorder(json_response({})), path=" /k7x2qm4a// ") ): - status, _, _ = call(adapter, headers={"x-api-key": PUBLIC_KEY}) + status, _, _ = call(adapter, headers=BROWSER) assert status == 200 assert recorder.calls == 2 @@ -191,17 +188,19 @@ def test_rejects_unusable_limits(self, limits: dict[str, Any]) -> None: class TestForwarding: @pytest.mark.parametrize( - "payload", [b'{"signals":{}}', b'{"token":"deferred","signals":{}}'] + "payload", + [ + b'{"v":3,"signals":{"latency":142.50,"sci":1e-05}}', + b'{"v":3,"sdk":{"platform":"web","version":"0.3.0"},"signals":{}}', + ], ) - def test_forwards_both_calls_to_the_one_ingest_url(self, payload: bytes) -> None: - # The identification and the deferred report share one path, and the - # API tells them apart by the body, so the proxy never looks inside. + def test_forwards_raw_v3_payload_verbatim_to_the_one_ingest_url( + self, payload: bytes + ) -> None: for adapter, call in both( proxy(recorder := Recorder(json_response({"ok": 1}))) ): - status, _, body = call( - adapter, headers={"x-api-key": PUBLIC_KEY}, body=payload - ) + status, _, body = call(adapter, headers=BROWSER, body=payload) assert status == 200 assert body == b'{"ok": 1}' assert [str(request.url) for request in recorder.requests] == [INGEST] * 2 @@ -210,7 +209,7 @@ def test_forwards_both_calls_to_the_one_ingest_url(self, payload: bytes) -> None def test_forwards_to_the_configured_versions_ingest_url(self) -> None: recorder = Recorder(json_response({})) for adapter, call in both(proxy(recorder, api_version="v2")): - status, _, _ = call(adapter, headers={"x-api-key": PUBLIC_KEY}) + status, _, _ = call(adapter, headers=BROWSER) assert status == 200 assert [str(request.url) for request in recorder.requests] == [ "https://api.fingerly.io/api/v2/ingest" @@ -220,9 +219,7 @@ def test_answers_whatever_was_routed_to_it_without_a_path(self) -> None: recorder = Recorder(json_response({})) for adapter, call in both(proxy(recorder, path=None)): for path in [PATH, "/anything/at/all", ""]: - status, _, _ = call( - adapter, path=path, headers={"x-api-key": PUBLIC_KEY} - ) + status, _, _ = call(adapter, path=path, headers=BROWSER) assert status == 200 assert [str(request.url) for request in recorder.requests] == [INGEST] * 6 @@ -246,7 +243,7 @@ def test_sends_only_vetted_visitor_metadata(self) -> None: assert upstream.headers["x-fingerly-origin"] == "https://shop.test" assert upstream.headers["x-fingerly-user-agent"] == "Firefox" assert upstream.headers["idempotency-key"] == "idem-1" - assert upstream.headers["x-fingerly-proxy-version"] == "python/0.2.0" + assert upstream.headers["x-fingerly-proxy-version"] == "python/0.3.0" assert "cookie" not in upstream.headers assert "authorization" not in upstream.headers @@ -271,7 +268,7 @@ def test_relays_only_the_allowlisted_headers(self) -> None: }, ) for adapter, call in both(proxy(Recorder(upstream))): - _, headers, body = call(adapter, headers={"x-api-key": PUBLIC_KEY}) + _, headers, body = call(adapter, headers=BROWSER) assert body == plain assert headers == { "content-type": "application/json", @@ -296,13 +293,13 @@ def test_honours_a_mount_at_the_path_from_either_standard(self, path: str) -> No mounted.asgi, path=path, root_path=PATH, - headers={"x-api-key": PUBLIC_KEY}, + headers=BROWSER, ) wsgi_status, _, _ = call_wsgi( mounted.wsgi, path="", script_name=PATH, - headers={"x-api-key": PUBLIC_KEY}, + headers=BROWSER, ) assert (asgi_status, wsgi_status) == (200, 200) assert recorder.calls == 2 @@ -317,13 +314,13 @@ def test_serves_a_deployment_under_a_sub_uri(self) -> None: mounted.asgi, path="/shop" + PATH, root_path="/shop", - headers={"x-api-key": PUBLIC_KEY}, + headers=BROWSER, ) wsgi_status, _, _ = call_wsgi( mounted.wsgi, path=PATH, script_name="/shop", - headers={"x-api-key": PUBLIC_KEY}, + headers=BROWSER, ) assert (asgi_status, wsgi_status) == (200, 200) assert recorder.calls == 2 @@ -336,13 +333,13 @@ def test_serves_a_sub_uri_deployment_that_also_mounts_the_proxy(self) -> None: mounted.asgi, path="/shop" + PATH, root_path="/shop" + PATH, - headers={"x-api-key": PUBLIC_KEY}, + headers=BROWSER, ) wsgi_status, _, _ = call_wsgi( mounted.wsgi, path="", script_name="/shop" + PATH, - headers={"x-api-key": PUBLIC_KEY}, + headers=BROWSER, ) assert (asgi_status, wsgi_status) == (200, 200) assert recorder.calls == 2 @@ -368,6 +365,7 @@ def read(self, size: Optional[int] = -1) -> bytes: "PATH_INFO": PATH, "CONTENT_LENGTH": str(len(payload)), "HTTP_X_API_KEY": PUBLIC_KEY, + "HTTP_ORIGIN": "https://shop.test", "wsgi.input": Socket(payload), } statuses: list[str] = [] @@ -380,7 +378,7 @@ def test_reassembles_a_streamed_asgi_body(self) -> None: payload = b'{"signals":"' + b"x" * 300 + b'"}' call_asgi( proxy(recorder).asgi, - headers={"x-api-key": PUBLIC_KEY}, + headers=BROWSER, body=payload, chunks=4, ) @@ -401,6 +399,8 @@ def test_refuses_anything_but_post(self) -> None: "path", [ "/k7x2qm4a/admin", + "/k7x2qm4a/supplement", + "/k7x2qm4a/events/req_1/supplement", "/k7x2qm4a/api/v1/identify", "/k7x2qm4ax", "/other", @@ -410,8 +410,9 @@ def test_refuses_anything_but_post(self) -> None: ) def test_refuses_every_path_but_the_configured_one(self, path: str) -> None: for adapter, call in both(proxy(recorder := Recorder(json_response({})))): - status, _, _ = call(adapter, path=path, headers={"x-api-key": PUBLIC_KEY}) + status, headers, _ = call(adapter, path=path, headers=BROWSER) assert status == 404 + assert headers["cache-control"] == "no-store" assert recorder.calls == 0 @pytest.mark.parametrize( @@ -446,11 +447,9 @@ def test_matches_the_path_exactly_as_sent(self, raw: str) -> None: def test_accepts_the_exact_path_with_a_query(self) -> None: recorder = Recorder(json_response({})) app = proxy(recorder) - call_asgi(app.asgi, raw_path=PATH, headers={"x-api-key": PUBLIC_KEY}) + call_asgi(app.asgi, raw_path=PATH, headers=BROWSER) for raw in [PATH + "?v=1", "https://shop.test" + PATH + "?v=1"]: - status, _, _ = call_wsgi( - app.wsgi, raw_uri=raw, headers={"x-api-key": PUBLIC_KEY} - ) + status, _, _ = call_wsgi(app.wsgi, raw_uri=raw, headers=BROWSER) assert status == 200 assert recorder.calls == 3 @@ -516,9 +515,7 @@ def test_refuses_an_oversized_declared_body(self) -> None: for adapter, call in both( proxy(recorder := Recorder(json_response({})), max_body_bytes=4) ): - status, _, _ = call( - adapter, headers={"x-api-key": PUBLIC_KEY}, body=b"far too long" - ) + status, _, _ = call(adapter, headers=BROWSER, body=b"far too long") assert status == 413 assert recorder.calls == 0 @@ -527,7 +524,7 @@ def test_refuses_an_oversized_streamed_body(self) -> None: recorder = Recorder(json_response({})) status, _, _ = call_asgi( proxy(recorder, max_body_bytes=4).asgi, - headers={"x-api-key": PUBLIC_KEY}, + headers=BROWSER, body=b"far too long", chunks=4, ) @@ -563,7 +560,11 @@ def client_ip(request: ProxyRequest) -> str: ): call( adapter, - headers={"x-api-key": PUBLIC_KEY, "CF-Connecting-IP": "203.0.113.7"}, + headers={ + "x-api-key": PUBLIC_KEY, + "origin": "https://shop.test", + "CF-Connecting-IP": "203.0.113.7", + }, ) assert len(seen) == 2 @@ -601,7 +602,7 @@ def test_refuses_anything_but_one_ip_literal( recorder = Recorder(json_response({})) injected = proxy(recorder, client_ip=lambda request: address) for adapter, call in both(injected): - status, headers, body = call(adapter, headers={"x-api-key": PUBLIC_KEY}) + status, headers, body = call(adapter, headers=BROWSER) assert status == 500 assert body == b"The client IP callback returned no valid address" assert headers["content-type"] == "text/plain; charset=utf-8" @@ -619,7 +620,7 @@ def test_treats_a_raising_callback_as_the_same_mistake_and_logs_once( ) for adapter, call in both(strict): for _ in range(3): - status, _, _ = call(adapter, headers={"x-api-key": PUBLIC_KEY}) + status, _, _ = call(adapter, headers=BROWSER) assert status == 500 assert recorder.calls == 0 assert len(caplog.records) == 1 @@ -629,7 +630,7 @@ def test_treats_a_raising_callback_as_the_same_mistake_and_logs_once( def test_forwards_a_valid_address(self, address: str) -> None: recorder = Recorder(json_response({})) for adapter, call in both(proxy(recorder, client_ip=lambda request: address)): - status, _, _ = call(adapter, headers={"x-api-key": PUBLIC_KEY}) + status, _, _ = call(adapter, headers=BROWSER) assert status == 200 assert [r.headers["x-fingerly-client-ip"] for r in recorder.requests] == [ address @@ -640,22 +641,61 @@ def test_resolves_the_address_before_reading_the_body(self) -> None: recorder = Recorder(json_response({})) status, _, _ = call_wsgi( proxy(recorder, client_ip=lambda request: "").wsgi, - headers={"x-api-key": PUBLIC_KEY}, + headers=BROWSER, ) assert status == 500 assert recorder.calls == 0 -class TestDeprecatedSecretKey: - def test_forwards_the_secret_key_without_a_public_key(self) -> None: +class TestNoSecretKeyUpstream: + """The proxy holds only a proxy key and never relays a secret key.""" + + def test_has_no_secret_key_parameter(self) -> None: + with pytest.raises(TypeError): + FingerlyProxy( # type: ignore[call-arg] + client_ip=lambda request: "203.0.113.10", + secret_key="fly_sk_development_test", + ) + with pytest.raises(TypeError): + FingerlyProxy( # type: ignore[call-arg] + client_ip=lambda request: "203.0.113.10", + proxy_key=PROXY_KEY, + secret_key="fly_sk_development_test", + ) + + def test_requires_a_well_formed_proxy_key(self) -> None: + for key in [None, "", "fly_px_", "fly_px_moon_test", "fly_px_development_a b"]: + with pytest.raises(TypeError): + FingerlyProxy(client_ip=lambda request: "203.0.113.10", proxy_key=key) + + def test_refuses_a_browser_presenting_a_secret_key(self) -> None: + recorder = Recorder(json_response({})) + for adapter, call in both(proxy(recorder)): + for presented in [ + "fly_sk_development_test", + "fly_pk_production_test", + "fly_px_development_test", + "", + ]: + headers = {"origin": "https://shop.test"} + if presented: + headers["x-api-key"] = presented + status, response_headers, _ = call(adapter, headers=headers) + assert status == 401 + assert response_headers["content-type"].startswith("text/plain") + assert response_headers["cache-control"] == "no-store" + assert recorder.calls == 0 + + def test_forwards_only_the_public_key_and_the_proxy_key(self) -> None: recorder = Recorder(json_response({})) - legacy = proxy(recorder, proxy_key=None, secret_key="fly_sk_development_test") - for adapter, call in both(legacy): - status, _, _ = call(adapter, headers={}) + for adapter, call in both(proxy(recorder)): + status, _, _ = call(adapter, headers=BROWSER) assert status == 200 + assert len(recorder.requests) == 2 for upstream in recorder.requests: - assert upstream.headers["x-api-key"] == "fly_sk_development_test" - assert "x-fingerly-proxy-key" not in upstream.headers + assert upstream.headers["x-api-key"] == PUBLIC_KEY + assert upstream.headers["x-fingerly-proxy-key"] == PROXY_KEY + assert not any("fly_sk_" in value for value in upstream.headers.values()) class TestLifecycle: @@ -703,7 +743,7 @@ def test_never_replays_an_upstream_cookie_for_the_next_visitor(self) -> None: recorder = Recorder(upstream) for adapter, call in both(proxy(recorder)): for _ in range(3): - call(adapter, headers={"x-api-key": PUBLIC_KEY}) + call(adapter, headers=BROWSER) assert recorder.calls == 6 assert all("cookie" not in request.headers for request in recorder.requests) @@ -756,7 +796,7 @@ def raising(request: httpx.Request) -> httpx.Response: caplog.set_level("WARNING", logger="fingerly.proxy") for adapter, call in both(proxy(Recorder.of(raising))): - got, headers, payload = call(adapter, headers={"x-api-key": PUBLIC_KEY}) + got, headers, payload = call(adapter, headers=BROWSER) assert (got, payload) == (status, body) assert headers["cache-control"] == "no-store" assert headers["content-type"] == "text/plain; charset=utf-8" @@ -778,7 +818,7 @@ def test_refuses_an_upstream_body_over_the_cap( ) caplog.set_level("WARNING", logger="fingerly.proxy") for adapter, call in both(proxy(recorder)): - status, _, payload = call(adapter, headers={"x-api-key": PUBLIC_KEY}) + status, _, payload = call(adapter, headers=BROWSER) assert (status, payload) == (502, b"Bad gateway") assert all("over 4 MiB" in r.getMessage() for r in caplog.records) @@ -788,7 +828,7 @@ def truncated(request: httpx.Request) -> httpx.Response: return httpx.Response(200, stream=Chunks([b'{"request_id":'], failure)) for adapter, call in both(proxy(Recorder.of(truncated))): - status, _, payload = call(adapter, headers={"x-api-key": PUBLIC_KEY}) + status, _, payload = call(adapter, headers=BROWSER) assert (status, payload) == (502, b"Bad gateway") @@ -831,7 +871,10 @@ async def send(message: MutableMapping[str, Any]) -> None: "method": "POST", "path": PATH, "root_path": "", - "headers": [(b"x-api-key", PUBLIC_KEY.encode())], + "headers": [ + (b"x-api-key", PUBLIC_KEY.encode()), + (b"origin", b"https://shop.test"), + ], } await asyncio.wait_for(app(scope, receive, send), 5) # Nothing left running once the visitor is gone. @@ -857,7 +900,12 @@ def test_forwards_non_ascii_visitor_headers_byte_for_byte(self) -> None: ) environ_ua = "Mozilla \xe9" # PEP 3333: Latin-1 decoded, as here status, _, _ = call_wsgi( - app.wsgi, headers={"x-api-key": PUBLIC_KEY, "user-agent": environ_ua} + app.wsgi, + headers={ + "x-api-key": PUBLIC_KEY, + "origin": "https://shop.test", + "user-agent": environ_ua, + }, ) assert status == 200 assert recorder.calls == 2 @@ -866,3 +914,167 @@ def test_forwards_non_ascii_visitor_headers_byte_for_byte(self) -> None: assert sent[0][b"x-fingerly-user-agent"] == "Mozilla é".encode() assert sent[0][b"x-fingerly-origin"] == "ü".encode() assert sent[1][b"x-fingerly-user-agent"] == b"Mozilla \xe9" + + +class TestV3RelayConformance: + def test_rejects_originless_browser_requests_and_invalid_sdk_platforms( + self, + ) -> None: + import json + + recorder = Recorder(json_response({"request_id": "one"})) + app = proxy(recorder) + for adapter, call in both(app): + status, headers, body = call( + adapter, + headers={ + "x-api-key": PUBLIC_KEY, + "host": "shop.test", + "referer": "https://shop.test/checkout", + }, + ) + assert status == 400 + assert headers["cache-control"] == "no-store" + assert json.loads(body)["error"]["code"] == "missing_origin" + + for invalid in [ + "", + "web", + "iOS", + "ANDROID", + " ios", + "ios ", + "ios\n", + "ios, android", + "unknown", + ]: + status, headers, body = call( + adapter, + headers={ + "x-api-key": PUBLIC_KEY, + "x-fingerly-sdk-platform": invalid, + "x-fingerly-origin": "https://forged.test", + "x-fingerly-proxy-key": "fly_px_development_forged", + "x-fingerly-client-ip": "1.2.3.4", + }, + ) + assert status == 400, invalid + assert headers["cache-control"] == "no-store" + assert json.loads(body)["error"]["code"] == "missing_origin" + assert recorder.calls == 0 + + def test_sanitizes_and_restores_valid_native_platforms_without_origin( + self, + ) -> None: + valid_platforms = [ + "ios", + "android", + "react-native", + "react-native-ios", + "react-native-android", + "flutter", + "flutter-ios", + "flutter-android", + "lynx-ios", + "lynx-android", + "capacitor", + "kotlin-multiplatform", + ] + raw_payload = b'{"v":3,"signals":{"latency":142.50,"sci":1e-05}}' + recorder = Recorder( + httpx.Response( + 409, + content=b'{"error":{"code":"request_in_progress","status":409}}', + headers={ + "content-type": "application/json", + "retry-after": "1", + "x-request-id": "req-409", + }, + ) + ) + app = proxy(recorder) + for platform in valid_platforms: + for adapter, call in both(app): + status, headers, _ = call( + adapter, + headers={ + "x-api-key": PUBLIC_KEY, + "X-Fingerly-SDK-Platform": platform, + "idempotency-key": "idem-py-native-0001", + "x-fingerly-origin": "https://forged.test", + "x-fingerly-proxy-key": "fly_px_development_forged", + "x-fingerly-client-ip": "1.2.3.4", + "x-fingerly-edge-tls-version": "TLSv1.3", + "cookie": "sid=secret", + "authorization": "Bearer secret", + }, + body=raw_payload, + ) + assert status == 409 + assert headers["retry-after"] == "1" + assert headers["cache-control"] == "no-store" + sent = recorder.requests[-1] + assert sent.content == raw_payload + assert sent.headers["x-fingerly-sdk-platform"] == platform + assert "x-fingerly-origin" not in sent.headers + assert sent.headers["x-fingerly-proxy-key"] == PROXY_KEY + assert sent.headers["x-fingerly-client-ip"] == "203.0.113.10" + assert "x-fingerly-edge-tls-version" not in sent.headers + assert sent.headers["idempotency-key"] == "idem-py-native-0001" + assert "cookie" not in sent.headers + assert "authorization" not in sent.headers + + def test_forwards_client_metadata_and_honours_cors_allowlist(self) -> None: + raw_payload = b'{"v":3,"signals":{"latency":142.50}}' + recorder = Recorder( + httpx.Response( + 200, + content=b'{"request_id":"ok"}', + headers={"content-type": "application/json", "retry-after": "2"}, + ) + ) + app = proxy(recorder, allowed_origins=["https://app.shop.test"]) + for adapter, call in both(app): + pre_status, pre_headers, pre_body = call( + adapter, + method="OPTIONS", + headers={"origin": "https://app.shop.test"}, + body=b"", + ) + assert pre_status == 204 + assert pre_body == b"" + assert pre_headers["access-control-allow-origin"] == "https://app.shop.test" + assert ( + "x-fingerly-sdk-platform" in pre_headers["access-control-allow-headers"] + ) + assert "retry-after" in pre_headers["access-control-expose-headers"] + + status, headers, _ = call( + adapter, + headers={ + "x-api-key": PUBLIC_KEY, + "origin": "https://app.shop.test", + "idempotency-key": "idem-py-web-00001", + "sec-fetch-site": "same-site", + "sec-fetch-mode": "cors", + "sec-fetch-dest": "empty", + "sec-ch-ua": '"Chromium";v="130"', + "sec-ch-ua-mobile": "?0", + "sec-ch-ua-platform": '"macOS"', + "x-fingerly-sdk-platform": "web", + }, + body=raw_payload, + ) + assert status == 200 + assert headers["access-control-allow-origin"] == "https://app.shop.test" + assert "retry-after" in headers["access-control-expose-headers"] + sent = recorder.requests[-1] + assert sent.content == raw_payload + assert sent.headers["x-fingerly-origin"] == "https://app.shop.test" + assert "x-fingerly-sdk-platform" not in sent.headers + assert sent.headers["sec-fetch-site"] == "same-site" + assert sent.headers["sec-fetch-mode"] == "cors" + assert sent.headers["sec-fetch-dest"] == "empty" + assert sent.headers["sec-ch-ua"] == '"Chromium";v="130"' + assert sent.headers["sec-ch-ua-mobile"] == "?0" + assert sent.headers["sec-ch-ua-platform"] == '"macOS"' diff --git a/tests/test_proxy_channel.py b/tests/test_proxy_channel.py new file mode 100644 index 0000000..2f2b85c --- /dev/null +++ b/tests/test_proxy_channel.py @@ -0,0 +1,74 @@ +"""One channel upstream, and an https upstream unless loopback is allowed.""" + +from __future__ import annotations + +import pytest +from conftest import Recorder, json_response +from test_proxy import BROWSER, PROXY_KEY, PUBLIC_KEY, both, proxy + +from fingerly import FingerlyProxy + + +class TestOneChannelUpstream: + def test_origin_wins_over_a_valid_platform(self) -> None: + recorder = Recorder(json_response({"request_id": "r"})) + for adapter, call in both(proxy(recorder)): + status, _, _ = call( + adapter, headers={**BROWSER, "x-fingerly-sdk-platform": "ios"} + ) + assert status == 200 + sent = recorder.requests[-1] + assert sent.headers["x-fingerly-origin"] == "https://shop.test" + assert "x-fingerly-sdk-platform" not in sent.headers + + def test_a_native_call_keeps_its_platform(self) -> None: + recorder = Recorder(json_response({})) + for adapter, call in both(proxy(recorder)): + status, _, _ = call( + adapter, + headers={"x-api-key": PUBLIC_KEY, "x-fingerly-sdk-platform": "android"}, + ) + assert status == 200 + sent = recorder.requests[-1] + assert sent.headers["x-fingerly-sdk-platform"] == "android" + assert "x-fingerly-origin" not in sent.headers + + +class TestHttpsUpstream: + @pytest.mark.parametrize( + "upstream", + ["http://upstream.invalid", "http://192.0.2.10:8080", "http://10.0.0.1"], + ) + def test_plain_http_on_another_host_is_refused(self, upstream: str) -> None: + for allow in (False, True): + with pytest.raises(TypeError, match="upstream must use https") as raised: + FingerlyProxy( + proxy_key=PROXY_KEY, + upstream=upstream, + allow_insecure_loopback=allow, + client_ip=lambda _: "", + ) + assert upstream not in str(raised.value) + + @pytest.mark.parametrize( + "upstream", ["http://127.0.0.1:9", "http://localhost:9", "http://[::1]:9"] + ) + def test_plain_http_loopback_needs_the_flag(self, upstream: str) -> None: + with pytest.raises(TypeError, match="allow_insecure_loopback"): + FingerlyProxy( + proxy_key=PROXY_KEY, upstream=upstream, client_ip=lambda _: "" + ) + FingerlyProxy( + proxy_key=PROXY_KEY, + upstream=upstream, + allow_insecure_loopback=True, + client_ip=lambda _: "", + ) + + def test_the_flag_must_be_a_bool(self) -> None: + with pytest.raises(TypeError): + FingerlyProxy( + proxy_key=PROXY_KEY, + client_ip=lambda _: "", + allow_insecure_loopback="yes", # type: ignore[arg-type] + ) diff --git a/tests/test_proxy_exact.py b/tests/test_proxy_exact.py new file mode 100644 index 0000000..aa8115c --- /dev/null +++ b/tests/test_proxy_exact.py @@ -0,0 +1,78 @@ +"""Exact path, exact method, and no-store on every refusal.""" + +from __future__ import annotations + +import pytest +from conftest import Recorder, json_response +from test_proxy import BROWSER, PATH, both, call_asgi, call_wsgi, proxy + + +@pytest.mark.parametrize("method", ["post", "Post", "pOST", "GET", "PUT", "DELETE"]) +def test_only_an_exact_post_is_forwarded(method: str) -> None: + recorder = Recorder(json_response({})) + for adapter, call in both(proxy(recorder)): + got, headers, _ = call(adapter, method=method, headers=BROWSER) + assert got == 405 + assert headers["allow"] == "POST" + assert headers["cache-control"] == "no-store" + assert recorder.calls == 0 + + +@pytest.mark.parametrize("method", ["options", "OPTIONS"]) +def test_options_without_cors_is_a_405(method: str) -> None: + recorder = Recorder(json_response({})) + for adapter, call in both(proxy(recorder)): + got, headers, _ = call(adapter, method=method, headers=BROWSER) + assert got == 405 + assert headers["cache-control"] == "no-store" + + +def test_lowercase_options_is_not_a_preflight() -> None: + recorder = Recorder(json_response({})) + app = proxy(recorder, allowed_origins=["https://shop.test"]) + for adapter, call in both(app): + got, headers, _ = call(adapter, method="options", headers=BROWSER) + assert got == 405 + assert headers["allow"] == "POST, OPTIONS" + assert headers["cache-control"] == "no-store" + + +@pytest.mark.parametrize( + "path", [PATH + "/", "/" + PATH, PATH + "x", PATH.upper(), "/x/.." + PATH] +) +def test_near_misses_are_uncacheable_404s(path: str) -> None: + recorder = Recorder(json_response({})) + for adapter, call in both(proxy(recorder)): + got, headers, _ = call(adapter, path=path, headers=BROWSER) + assert got == 404 + assert headers["cache-control"] == "no-store" + assert recorder.calls == 0 + + +@pytest.mark.parametrize( + "raw", [PATH + "%2F", "/x/.." + PATH, "/." + PATH, "/k7x2qm4%61"] +) +def test_raw_targets_that_decode_to_the_path_are_404s(raw: str) -> None: + recorder = Recorder(json_response({})) + app = proxy(recorder) + status, headers, _ = call_asgi(app.asgi, path=PATH, headers=BROWSER, raw_path=raw) + assert (status, headers["cache-control"]) == (404, "no-store") + status, headers, _ = call_wsgi(app.wsgi, path=PATH, headers=BROWSER, raw_uri=raw) + assert (status, headers["cache-control"]) == (404, "no-store") + assert recorder.calls == 0 + + +@pytest.mark.parametrize( + "raw", + [ + "http://shop.test/x/../k7x2qm4a", + "http://shop.test/k7x2qm4%61", + "http://shop.test/./k7x2qm4a", + ], +) +def test_absolute_form_targets_are_matched_raw(raw: str) -> None: + recorder = Recorder(json_response({})) + app = proxy(recorder) + status, headers, _ = call_wsgi(app.wsgi, path=PATH, headers=BROWSER, raw_uri=raw) + assert (status, headers["cache-control"]) == (404, "no-store") + assert recorder.calls == 0 diff --git a/tests/test_proxy_redirects.py b/tests/test_proxy_redirects.py new file mode 100644 index 0000000..0fbb794 --- /dev/null +++ b/tests/test_proxy_redirects.py @@ -0,0 +1,64 @@ +"""No upstream redirect is followed or relayed, whatever transport is supplied.""" + +from __future__ import annotations + +from collections.abc import Iterator +from typing import Any + +import httpx +import pytest +from conftest import Recorder +from raw_upstream import RawUpstream, answering, real +from test_proxy import BROWSER, both, proxy + + +@pytest.fixture +def target() -> Iterator[RawUpstream]: + server = answering("200") + yield server + server.close() + + +@pytest.mark.parametrize("status", [300, 301, 302, 303, 304, 307, 308, 399]) +def test_a_redirect_answer_is_a_bad_gateway(status: int) -> None: + recorder = Recorder( + httpx.Response(status, headers={"location": "https://elsewhere.invalid/"}) + ) + for adapter, call in both(proxy(recorder)): + got, headers, payload = call(adapter, headers=BROWSER) + assert (got, payload) == (502, b"Bad gateway") + assert headers["cache-control"] == "no-store" + assert "location" not in headers + assert recorder.calls == 2 + + +@pytest.mark.parametrize("status", [301, 302, 303, 307, 308]) +def test_no_redirect_is_followed_with_the_key(status: int, target: RawUpstream) -> None: + first = answering(str(status), f"location: {target.origin}/collect\r\n") + try: + for supplied in (False, True): + options: dict[str, Any] = {} + if supplied: + # The proxy's own client wraps a supplied transport with + # redirects off, so the transport cannot turn them on. + options["transport"] = httpx.HTTPTransport() + options["async_transport"] = httpx.AsyncHTTPTransport() + for adapter, call in both(real(first.origin, **options)): + got, headers, _ = call(adapter, headers=BROWSER) + assert got == 502 + assert headers["cache-control"] == "no-store" + assert first.hits == 4 + assert target.hits == 0 + finally: + first.close() + + +def test_a_redirect_log_names_no_upstream(caplog: pytest.LogCaptureFixture) -> None: + caplog.set_level("DEBUG", logger="fingerly.proxy") + recorder = Recorder(httpx.Response(307, headers={"location": "https://x.invalid"})) + for adapter, call in both(proxy(recorder, upstream="https://upstream.invalid")): + call(adapter, headers=BROWSER) + assert caplog.records + for record in caplog.records: + assert "upstream.invalid" not in record.getMessage() + assert "x.invalid" not in record.getMessage() diff --git a/tests/test_proxy_status.py b/tests/test_proxy_status.py new file mode 100644 index 0000000..de19006 --- /dev/null +++ b/tests/test_proxy_status.py @@ -0,0 +1,39 @@ +"""An upstream status outside 200 to 599 is answered 502.""" + +from __future__ import annotations + +import pytest +from conftest import Recorder, json_response +from raw_upstream import answering, real +from test_proxy import BROWSER, both, proxy + + +@pytest.mark.parametrize("status", [100, 101, 199, 600, 700, 999]) +def test_a_status_outside_200_to_599_is_a_bad_gateway(status: int) -> None: + recorder = Recorder(json_response({}, status=status)) + for adapter, call in both(proxy(recorder)): + got, headers, payload = call(adapter, headers=BROWSER) + assert (got, payload) == (502, b"Bad gateway") + assert headers["cache-control"] == "no-store" + + +@pytest.mark.parametrize("status", [200, 299, 400, 599]) +def test_a_status_at_the_edges_is_relayed(status: int) -> None: + recorder = Recorder(json_response({}, status=status)) + for adapter, call in both(proxy(recorder)): + got, headers, _ = call(adapter, headers=BROWSER) + assert got == status + assert headers["cache-control"] == "no-store" + + +@pytest.mark.parametrize("code", ["600", "999"]) +def test_a_raw_out_of_range_status_is_a_bad_gateway(code: str) -> None: + upstream = answering(code) + try: + for adapter, call in both(real(upstream.origin)): + got, headers, _ = call(adapter, headers=BROWSER) + assert got == 502 + assert headers["cache-control"] == "no-store" + assert upstream.hits == 2 + finally: + upstream.close() diff --git a/tests/test_proxy_upstream.py b/tests/test_proxy_upstream.py new file mode 100644 index 0000000..34e1b1b --- /dev/null +++ b/tests/test_proxy_upstream.py @@ -0,0 +1,87 @@ +"""The upstream option is a bare origin, and failure logs never name it.""" + +from __future__ import annotations + +import socket + +import pytest +from conftest import Recorder, json_response +from raw_upstream import real +from test_proxy import BROWSER, PROXY_KEY, both, proxy + +from fingerly import FingerlyProxy + + +@pytest.mark.parametrize( + "upstream", + [ + "https://upstream.invalid/prefix", + "https://upstream.invalid/a/../b", + "https://upstream.invalid//", + "https://upstream.invalid?", + "https://upstream.invalid?x=1", + "https://upstream.invalid#", + "https://upstream.invalid#f", + "https://user:pass@upstream.invalid", + "https://@upstream.invalid", + "https://upstream.invalid\n", + "https://upstream.invalid ", + " https://upstream.invalid", + "https://upstream.invalid\r\nx-injected: 1", + "https://upstream.invalid\t", + "https://upstréam.invalid", + "ftp://upstream.invalid", + "https://", + "upstream.invalid", + "", + ], +) +def test_refuses_anything_but_a_bare_https_origin(upstream: str) -> None: + for allow in (False, True): + with pytest.raises(TypeError, match="upstream must") as raised: + FingerlyProxy( + proxy_key=PROXY_KEY, + upstream=upstream, + allow_insecure_loopback=allow, + client_ip=lambda _: "", + ) + assert "upstream.invalid" not in str(raised.value) + assert PROXY_KEY not in str(raised.value) + + +@pytest.mark.parametrize( + ("upstream", "expected"), + [ + ("https://upstream.invalid", "https://upstream.invalid/api/v1/ingest"), + ("https://upstream.invalid/", "https://upstream.invalid/api/v1/ingest"), + ( + "https://upstream.invalid:8443", + "https://upstream.invalid:8443/api/v1/ingest", + ), + ("https://UPSTREAM.invalid", "https://upstream.invalid/api/v1/ingest"), + ], +) +def test_the_target_is_rebuilt_from_scheme_host_and_port( + upstream: str, expected: str +) -> None: + recorder = Recorder(json_response({})) + for adapter, call in both(proxy(recorder, upstream=upstream)): + assert call(adapter, headers=BROWSER)[0] == 200 + assert {str(request.url) for request in recorder.requests} == {expected} + + +def test_an_unreachable_upstream_is_not_named(caplog: pytest.LogCaptureFixture) -> None: + closed = socket.socket() + closed.bind(("127.0.0.1", 0)) + port = closed.getsockname()[1] + closed.close() + caplog.set_level("DEBUG", logger="fingerly.proxy") + for adapter, call in both(real(f"http://127.0.0.1:{port}")): + got, _, payload = call(adapter, headers=BROWSER) + assert got == 502 + assert b"127.0.0.1" not in payload + assert caplog.records + for record in caplog.records: + text = record.getMessage() + for leak in ("127.0.0.1", str(port), "ingest", "http", PROXY_KEY): + assert leak not in text diff --git a/tests/test_redaction.py b/tests/test_redaction.py index 9d15153..c52d5d3 100644 --- a/tests/test_redaction.py +++ b/tests/test_redaction.py @@ -40,11 +40,10 @@ def _objects() -> list[Any]: reader = Fingerly(secret_key=SECRET_KEY) areader = AsyncFingerly(secret_key=SECRET_KEY) proxy = FingerlyProxy(proxy_key=PROXY_KEY, client_ip=lambda r: "203.0.113.1") - legacy = FingerlyProxy(secret_key=SECRET_KEY, client_ip=lambda r: "203.0.113.1") - return [reader, reader.events, areader, proxy, proxy.asgi, proxy.wsgi, legacy] + return [reader, reader.events, areader, proxy, proxy.asgi, proxy.wsgi] -@pytest.mark.parametrize("index", range(7)) +@pytest.mark.parametrize("index", range(6)) def test_no_object_shows_a_credential(index: int) -> None: value = _objects()[index] dumped = _state(value) diff --git a/tests/test_regressions.py b/tests/test_regressions.py index 0266038..1a2c179 100644 --- a/tests/test_regressions.py +++ b/tests/test_regressions.py @@ -63,7 +63,13 @@ def test_declared_length_superscript_does_not_raise(self) -> None: request = ProxyRequest( "POST", "/x", - Headers([("x-api-key", PUBLIC_KEY), ("content-length", "²")]), + Headers( + [ + ("x-api-key", PUBLIC_KEY), + ("origin", "https://shop.test"), + ("content-length", "²"), + ] + ), ) assert proxy.screen(request).refusal is None @@ -75,6 +81,7 @@ def _wsgi_call(proxy: FingerlyProxy, **environ: Any) -> tuple[str, bytes]: "REQUEST_METHOD": "POST", "PATH_INFO": "/x", "HTTP_X_API_KEY": PUBLIC_KEY, + "HTTP_ORIGIN": "https://shop.test", "REMOTE_ADDR": "203.0.113.7", } chunks = proxy.wsgi( @@ -175,7 +182,10 @@ async def send(message: Any) -> None: "raw_path": b"/x", "root_path": "", "query_string": b"", - "headers": [(b"x-api-key", PUBLIC_KEY.encode())], + "headers": [ + (b"x-api-key", PUBLIC_KEY.encode()), + (b"origin", b"https://shop.test"), + ], } await app(scope, receive, send) return sent @@ -198,7 +208,10 @@ async def send(_message: Any) -> None: "method": "POST", "path": "/x", "root_path": "", - "headers": [(b"x-api-key", PUBLIC_KEY.encode())], + "headers": [ + (b"x-api-key", PUBLIC_KEY.encode()), + (b"origin", b"https://shop.test"), + ], } await proxy.asgi(scope, receive, send) @@ -217,7 +230,13 @@ def test_a_surrogate_escaped_value_does_not_raise(self) -> None: request = ProxyRequest( "POST", "/x", - Headers([("x-api-key", PUBLIC_KEY), ("user-agent", "caf\udce9")]), + Headers( + [ + ("x-api-key", PUBLIC_KEY), + ("origin", "https://shop.test"), + ("user-agent", "caf\udce9"), + ] + ), ) assert proxy.forward(proxy.screen(request), request, b"{}").status == 422 @@ -265,7 +284,7 @@ class TestEndpointsRefusedAtConstruction: def test_fails_before_any_request(self, endpoint: str) -> None: with pytest.raises(TypeError, match="endpoint must be"): Fingerly(secret_key=SECRET_KEY, endpoint=endpoint) - with pytest.raises(TypeError, match="endpoint must be"): + with pytest.raises(TypeError, match="upstream must"): FingerlyProxy( proxy_key=PROXY_KEY, upstream=endpoint, client_ip=lambda _: "" ) @@ -273,11 +292,17 @@ def test_fails_before_any_request(self, endpoint: str) -> None: class TestScreeningRedaction: def test_repr_does_not_print_the_key_it_will_present(self) -> None: - proxy = FingerlyProxy(secret_key=SECRET_KEY, client_ip=lambda _: "203.0.113.7") - screening = proxy.screen(ProxyRequest("POST", "/x", Headers([]))) - assert screening.api_key == SECRET_KEY - assert SECRET_KEY not in repr(screening) - assert SECRET_KEY not in str(screening) + proxy = FingerlyProxy(proxy_key=PROXY_KEY, client_ip=lambda _: "203.0.113.7") + screening = proxy.screen( + ProxyRequest( + "POST", + "/x", + Headers([("origin", "https://shop.test"), ("x-api-key", PUBLIC_KEY)]), + ) + ) + assert screening.api_key == PUBLIC_KEY + assert PUBLIC_KEY not in repr(screening) + assert PUBLIC_KEY not in str(screening) class TestOneTlsContext: