From ab3959565b7ac031714d83d6553bc68fe7fc8e5d Mon Sep 17 00:00:00 2001 From: hasan-muzak Date: Mon, 16 Nov 2026 10:11:47 +0300 Subject: [PATCH 01/16] Sync v3 contract and enforce single-path proxy sanitize-and-restore contract --- CHANGELOG.md | 17 +++ contract/manifest.json | 4 +- contract/openapi.json | 299 +++++++++++++++++--------------------- src/fingerly/__init__.py | 12 +- src/fingerly/_asgi.py | 4 +- src/fingerly/_models.py | 211 ++++++++++++++++++++++++++- src/fingerly/_proxy.py | 181 +++++++++++++++++++---- src/fingerly/_version.py | 2 +- src/fingerly/_wsgi.py | 6 +- tests/test_contract.py | 82 ++++++++++- tests/test_frameworks.py | 47 +++++- tests/test_packaging.py | 1 + tests/test_proxy.py | 261 +++++++++++++++++++++++++++------ tests/test_regressions.py | 31 +++- 14 files changed, 900 insertions(+), 258 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9cc45d7..59b3eca 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,22 @@ # Changelog +## 0.3.0 + +- 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`, `device_inconsistent`, + `report_incomplete`, `tampering`, `custom_root_ca`, + `secondary_user_profile`). +- 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. + ## 0.2.0 - `Event.project_id` is the Fingerly project an event belongs to, on single diff --git a/contract/manifest.json b/contract/manifest.json index 7303153..ae1bfff 100644 --- a/contract/manifest.json +++ b/contract/manifest.json @@ -1,8 +1,8 @@ { "schema": 1, - "serverCommit": "e22f96777b0d029464baa4e127d7a346b684d478", + "serverCommit": "c3deba4d383e5b92f9708a1570c125c3c9531023", "files": { - "openapi.json": "850e7627dbbf1789fe7a0a214ae28838f2cd80d42e251f9994f5cb42d72e6009", + "openapi.json": "7a0f21ed27c7b01901f7be80b8070cc792b94d4c5bf239c0f0bee4e19662044d", "fixtures.json": "3fbf2efbcf3c8ebced3d2c9f2a3c1f5752ee94ece63d5c110291d9a8251ff68f" } } diff --git a/contract/openapi.json b/contract/openapi.json index e1483dd..5e0038c 100644 --- a/contract/openapi.json +++ b/contract/openapi.json @@ -1,6 +1,72 @@ { "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 Base64 Apple DeviceCheck token bound into statementDigest", + "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_key_id": { + "description": "Optional retiring 64-char hex Android key ID during 24h lease rollover", + "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": { @@ -436,6 +502,17 @@ }, "IdentifyIn": { "properties": { + "attest": { + "anyOf": [ + { + "$ref": "#/components/schemas/AttestEnvelope" + }, + { + "type": "null" + } + ], + "description": "Hardware attestation envelope bound to raw signals bytes (v3 native SDKs)" + }, "consent": { "description": "The SDK's consent state; must be granted, or the request is refused with consent_required", "type": "string" @@ -452,28 +529,40 @@ "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)", "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", - "type": "string" - }, - "deferred_token": { - "description": "Short-lived capability for the deferred signal report", + "attest_key_status": { + "description": "rekey_required when the presented v3 attestation key is unknown or expired", "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" + }, "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 +600,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,6 +645,17 @@ }, "IngestIn": { "properties": { + "attest": { + "anyOf": [ + { + "$ref": "#/components/schemas/AttestEnvelope" + }, + { + "type": "null" + } + ], + "description": "Hardware attestation envelope bound to raw signals bytes (v3 native SDKs)" + }, "consent": { "description": "The SDK's consent state; must be granted, or the request is refused with consent_required", "type": "string" @@ -570,12 +670,13 @@ "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", "type": "string" }, - "token": { - "description": "The deferred_token returned by identify. Present only on a deferred report", - "type": "string" + "v": { + "description": "Wire envelope version. Must equal 3.", + "format": "int64", + "type": "integer" } }, "type": "object" @@ -1341,21 +1442,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": { @@ -2319,59 +2405,30 @@ "x-title": "Read an event's DeviceCheck bits" } }, - "/api/v1/events/{request_id}/supplement": { + "/api/v1/identify": { "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", - "parameters": [ - { - "in": "path", - "name": "request_id", - "required": true, - "schema": { - "type": "string" - } - } - ], + "description": "Submits the signal report a client SDK collected and answers with the request ID, the visitor ID and its confidence. There is no second call to make.\n\nA browser, an app, a proxy and a hosted domain also receive `suspect_score` and `suspect_level`, unless the key withholds them, and never `triggers`. A secret key called directly from a backend receives the score, the level and the `triggers`.\n\nThe client SDKs build and send this request. `signals` is produced by them and is not a public contract. Send an `Idempotency-Key` header, and the same value on every retry, so a retried identification is answered and charged once.\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": "identifyVisitor", "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" + "$ref": "#/components/schemas/IdentifyIn" } } }, "required": true }, "responses": { - "202": { + "200": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SupplementOut" + "$ref": "#/components/schemas/IdentifyOut" } } }, - "description": "Accepted" + "description": "OK" }, "401": { "content": { @@ -2401,96 +2458,7 @@ } } }, - "description": "A different deferred report was already accepted for this request" - }, - "422": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - }, - "description": "The request could not be validated." - }, - "503": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - }, - "description": "The report could not be accepted just now" - }, - "default": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - }, - "description": "An unexpected error occurred." - } - }, - "security": [ - { - "publicKey": [] - } - ], - "summary": "Submit a deferred report", - "tags": [ - "Client API" - ], - "x-category": "Client API", - "x-title": "Submit a deferred report" - } - }, - "/api/v1/identify": { - "post": { - "description": "Submits the signal report a client SDK collected and answers with the request ID, the visitor ID and its confidence. There is no second call to make.\n\nA browser, an app, a proxy and a hosted domain also receive `suspect_score` and `suspect_level`, unless the key withholds them, and never `triggers`. A secret key called directly from a backend receives the score, the level and the `triggers`.\n\nThe client SDKs build and send this request. `signals` is produced by them and is not a public contract. Send an `Idempotency-Key` header, and the same value on every retry, so a retried identification is answered and charged once.\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": "identifyVisitor", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/IdentifyIn" - } - } - }, - "required": true - }, - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/IdentifyOut" - } - } - }, - "description": "OK" - }, - "401": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - }, - "description": "No usable x-api-key header was presented" - }, - "402": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - }, - "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": { @@ -2561,7 +2529,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 +2552,7 @@ }, "description": "OK" }, - "202": { + "401": { "content": { "application/json": { "schema": { @@ -2592,9 +2560,9 @@ } } }, - "description": "The deferred report was accepted" + "description": "No usable x-api-key header was presented" }, - "401": { + "402": { "content": { "application/json": { "schema": { @@ -2602,9 +2570,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 +2580,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 +5301,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" }, @@ -5375,6 +5343,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 +5478,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" }, diff --git a/src/fingerly/__init__.py b/src/fingerly/__init__.py index 86f19f0..05c98c4 100644 --- a/src/fingerly/__init__.py +++ b/src/fingerly/__init__.py @@ -20,15 +20,25 @@ FingerlyEventPendingError, FingerlyTimeoutError, ) -from ._models import Event, EventPage, EventTrigger +from ._models import ( + SIGNAL_NAMES, + Attestation, + Event, + EventDocument, + EventPage, + EventTrigger, +) from ._proxy import FingerlyProxy, ProxyRequest from ._version import __version__ from ._webhooks import verify_webhook __all__ = [ + "SIGNAL_NAMES", "AsyncEvents", "AsyncFingerly", + "Attestation", "Event", + "EventDocument", "EventPage", "EventTrigger", "Events", 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/_models.py b/src/fingerly/_models.py index 7f66f85..4745ff2 100644 --- a/src/fingerly/_models.py +++ b/src/fingerly/_models.py @@ -21,13 +21,85 @@ 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", + "high_activity", + "incognito_mode", + "incognito", + "privacy_settings", + "embedded_web_view", + "active_call", + "attestation_missing", + "attestation_failed", + "device_inconsistent", + "report_incomplete", + "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 +109,70 @@ 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``. + """ + + 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 + 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 +191,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 +213,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. @@ -141,9 +280,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 +341,61 @@ 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)), + 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..57c70c7 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 @@ -77,6 +78,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. @@ -161,11 +198,13 @@ class Screening(NamedTuple): refusal: The response to send, when the request is refused. api_key: The 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. @@ -212,6 +251,7 @@ def __init__( 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, @@ -266,6 +306,7 @@ def __init__( 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 @@ -312,35 +353,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 +417,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 _relay(reply, cors=screening.cors) async def aforward( self, screening: Screening, request: ProxyRequest, body: bytes @@ -369,10 +430,12 @@ 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 _relay(reply, cors=screening.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 +443,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 +470,31 @@ 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-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() + origin = request.headers.get("origin", "").strip() + if origin: + headers["x-fingerly-origin"] = origin + raw_platform = request.headers.get("x-fingerly-sdk-platform", "") + if 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: @@ -611,8 +686,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 +740,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 +768,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 +784,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/_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/test_contract.py b/tests/test_contract.py index 4adadfb..713f0fd 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,76 @@ 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", + "device_inconsistent", + "report_incomplete", + "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" 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_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..85bc154 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: @@ -176,7 +177,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 +192,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 +213,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 +223,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 +247,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 +272,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 +297,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 +318,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 +337,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 +369,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 +382,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 +403,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 +414,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 +451,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 +519,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 +528,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 +564,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 +606,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 +624,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 +634,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,7 +645,7 @@ 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 @@ -651,7 +656,7 @@ def test_forwards_the_secret_key_without_a_public_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={}) + status, _, _ = call(adapter, headers={"origin": "https://shop.test"}) assert status == 200 for upstream in recorder.requests: assert upstream.headers["x-api-key"] == "fly_sk_development_test" @@ -703,7 +708,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 +761,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 +783,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 +793,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 +836,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 +865,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 +879,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_regressions.py b/tests/test_regressions.py index 0266038..c51adf5 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 @@ -274,7 +293,9 @@ 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([]))) + screening = proxy.screen( + ProxyRequest("POST", "/x", Headers([("origin", "https://shop.test")])) + ) assert screening.api_key == SECRET_KEY assert SECRET_KEY not in repr(screening) assert SECRET_KEY not in str(screening) From f0b80de24d835614e5f55b6e49a8dc34ec86dfa1 Mon Sep 17 00:00:00 2001 From: hasan-muzak Date: Mon, 16 Nov 2026 14:19:42 +0300 Subject: [PATCH 02/16] Update README documentation for 0.3.0 and v3 contract --- README.md | 83 ++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 60 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 861a727..fe54203 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,15 @@ # fingerly -Server-side event reads, webhook verification and a same-origin proxy for +Server-side event reads, webhook verification and a first-party proxy for Python. Two clients share one API: `Fingerly` for synchronous code such as Django and Flask, and `AsyncFingerly` for asyncio code such as FastAPI and Starlette. Python 3.9 or newer. One runtime dependency, `httpx`. The proxy serves both ASGI and WSGI, so it mounts under either. +```sh +pip install "fingerly>=0.3.0" +``` + ```python import os from fingerly import Fingerly @@ -49,9 +53,18 @@ never follow one. `FingerlyTimeoutError` and `FingerlyConnectionError` cover a deadline and an unreachable API; all three derive from `FingerlyError`. `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. +/40, such as `203.0.113.0/24`); the API never returns the 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, and `event.parse_document()` decodes it into a typed +`EventDocument` (including `attestation: Optional[Attestation]`). `SIGNAL_NAMES` +lists the canonical signal identifiers, including the `v: 3` anti-spoofing and +integrity signals `"attestation_failed"`, `"device_inconsistent"`, +`"report_incomplete"`, `"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. `Event` declares every documented field as an attribute and falls back to the decoded body for fields added later, so a new server field @@ -77,7 +90,8 @@ one of two codes: retention. The archived `document` arrives moments after the event itself, so check -`has_document` rather than assuming it is there. +`has_document` rather than assuming it is there, and call +`event.parse_document()` when you want a typed `EventDocument`. ## Verify a backend action @@ -200,24 +214,35 @@ const fingerly = await load({ apiKey: 'fly_pk_…', endpoints: '/k7x2qm4a' }) ### 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 +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. Any path other +than the configured one (retired `/supplement` subpaths included) gets `404`, +and any method other than `POST` (plus `OPTIONS` when `allowed_origins` is +configured) gets `405`. Event reads need a secret key and stay unreachable from a browser by construction. -The browser must present a public key from the same environment as the proxy -key, or the request gets `401`. Bodies over 1 MiB get `413`, enforced -while streaming rather than after buffering, and under WSGI a body the server -cannot read, such as broken chunked framing, gets `400`. Responses are marked -`no-store`. - -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 +The caller must present a public key from the same environment as the proxy +key, or the request gets `401`. 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. Bodies over 1 MiB get `413`, enforced while streaming rather than +after buffering, and under WSGI a body the server cannot read, such as broken +chunked framing, gets `400`. Responses are marked `no-store`. + +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/` as its user agent. +`fingerly-python/0.3.0` as its user agent. When Fingerly cannot be reached in time the proxy answers `504 Gateway timeout`, and on any other upstream failure, such as a refused connection, a @@ -335,7 +360,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, + } ``` The same works under `uvicorn --workers 4` or gunicorn's uvicorn worker: each @@ -426,7 +455,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, + } ) ``` @@ -480,7 +513,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, + } ``` A `DispatcherMiddleware` mount answers everything under its path too, which is From ca93134f6fd4f71f271ee1a5d2044f0c40996e66 Mon Sep 17 00:00:00 2001 From: muzakon Date: Mon, 16 Nov 2026 17:40:46 +0300 Subject: [PATCH 03/16] Forward one channel and require an https proxy upstream A request carrying both Origin and a valid platform header now goes upstream with x-fingerly-origin only, matching the direct API path; the API refuses a proxied request that carries both. The upstream must be https; plain http is allowed only on a loopback host with allow_insecure_loopback=True, so the proxy key never travels in clear. Refs: fingerly-io/sdks#20 --- README.md | 24 ++++++++++-- src/fingerly/_config.py | 42 +++++++++++++++++++++ src/fingerly/_proxy.py | 19 ++++++++-- tests/test_proxy_channel.py | 74 +++++++++++++++++++++++++++++++++++++ tests/test_regressions.py | 2 +- 5 files changed, 154 insertions(+), 7 deletions(-) create mode 100644 tests/test_proxy_channel.py diff --git a/README.md b/README.md index fe54203..88caa69 100644 --- a/README.md +++ b/README.md @@ -223,6 +223,21 @@ and any method other than `POST` (plus `OPTIONS` when `allowed_origins` is configured) gets `405`. Event reads need a secret key and stay unreachable from a browser by construction. +`upstream` replaces the API origin for testing against a local API. 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, +) +``` + The caller must present a public key from the same environment as the proxy key, or the request gets `401`. Incoming headers follow the sanitize-and-restore sequence: all incoming `x-fingerly-*`, `cookie` and `authorization` headers are @@ -233,9 +248,12 @@ lowercase native or bridge platform (`ios`, `android`, `react-native`, `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. Bodies over 1 MiB get `413`, enforced while streaming rather than -after buffering, and under WSGI a body the server cannot read, such as broken -chunked framing, gets `400`. Responses are marked `no-store`. +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. Bodies over +1 MiB get `413`, enforced while streaming rather than after buffering, and +under WSGI a body the server cannot read, such as broken chunked framing, gets +`400`. Responses are marked `no-store`. Alongside verified proxy metadata (`x-fingerly-host` included), only `content-type`, `x-api-key`, `user-agent`, `idempotency-key`, `sec-fetch-*` and diff --git a/src/fingerly/_config.py b/src/fingerly/_config.py index 646d8f8..c124dc2 100644 --- a/src/fingerly/_config.py +++ b/src/fingerly/_config.py @@ -122,6 +122,48 @@ def normalize_endpoint(value: str) -> str: return value.rstrip("/") +#: 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 requires ``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") + try: + origin = normalize_endpoint(value) # type: ignore[arg-type] + except TypeError: + raise TypeError( + f"{name} must be an HTTP(S) URL without credentials, query, or fragment" + ) from None + parts = urlsplit(origin) + if parts.scheme == "http" and not ( + allow_insecure_loopback and (parts.hostname or "") 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" + ) + return origin + + 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/_proxy.py b/src/fingerly/_proxy.py index 57c70c7..62e29d0 100644 --- a/src/fingerly/_proxy.py +++ b/src/fingerly/_proxy.py @@ -43,6 +43,7 @@ KeyScope, Secret, no_cookies, + normalize_api_origin, normalize_api_version, normalize_endpoint, parse_key, @@ -255,6 +256,7 @@ def __init__( 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. @@ -273,6 +275,10 @@ def __init__( 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. + ``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 @@ -300,7 +306,11 @@ def __init__( ) self._key = Secret(raw_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) @@ -479,11 +489,14 @@ def upstream_headers( } 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 - raw_platform = request.headers.get("x-fingerly-sdk-platform", "") - if raw_platform in VALID_SDK_PLATFORMS: + elif raw_platform in VALID_SDK_PLATFORMS: headers["x-fingerly-sdk-platform"] = raw_platform host = request.headers.get("host", "").strip() if host: 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_regressions.py b/tests/test_regressions.py index c51adf5..9a88b32 100644 --- a/tests/test_regressions.py +++ b/tests/test_regressions.py @@ -284,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 _: "" ) From 0b7c02102d81dcb75f037d132e01035ff7e7830b Mon Sep 17 00:00:00 2001 From: muzakon Date: Mon, 16 Nov 2026 17:41:24 +0300 Subject: [PATCH 04/16] Answer an upstream redirect with 502 The proxy's own client never follows a redirect, also around a caller-supplied transport, and a 3xx answer is now refused with 502 instead of being relayed, so its target never sees the proxy key. Refs: fingerly-io/sdks#46 --- README.md | 8 ++-- src/fingerly/_proxy.py | 17 ++++++- tests/raw_upstream.py | 84 +++++++++++++++++++++++++++++++++++ tests/test_proxy_redirects.py | 64 ++++++++++++++++++++++++++ 4 files changed, 168 insertions(+), 5 deletions(-) create mode 100644 tests/raw_upstream.py create mode 100644 tests/test_proxy_redirects.py diff --git a/README.md b/README.md index 88caa69..2d2bb92 100644 --- a/README.md +++ b/README.md @@ -264,9 +264,11 @@ never passed on. The proxy reports itself upstream as `python/0.3.0` in When Fingerly cannot be reached in time the proxy answers `504 Gateway timeout`, and on any other upstream failure, such as a refused connection, a -malformed or truncated response or one over 4 MiB, `502 Bad gateway`. Both are -short plain text marked `no-store`, and each writes one line, with no stack -trace, to the `fingerly.proxy` logger. +malformed or truncated response or one over 4 MiB, `502 Bad gateway`. A +redirect is never followed, whatever transport you supply, and an upstream +redirect is answered `502` too. All of these are short plain text marked +`no-store`, and each writes one line, with no stack trace, to the +`fingerly.proxy` logger. Back to the browser it relays only `content-type`, `x-request-id`, `ratelimit-limit`, `ratelimit-remaining` and `retry-after`, plus its own diff --git a/src/fingerly/_proxy.py b/src/fingerly/_proxy.py index 62e29d0..6278ba9 100644 --- a/src/fingerly/_proxy.py +++ b/src/fingerly/_proxy.py @@ -428,7 +428,7 @@ def forward( ) except (httpx.HTTPError, ResponseTooLargeError) as error: return self._upstream_failed(error, cors=screening.cors) - return _relay(reply, cors=screening.cors) + return self._relay_or_refuse(reply, cors=screening.cors) async def aforward( self, screening: Screening, request: ProxyRequest, body: bytes @@ -441,7 +441,20 @@ async def aforward( ) except (httpx.HTTPError, ResponseTooLargeError) as error: return self._upstream_failed(error, cors=screening.cors) - return _relay(reply, 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 an upstream redirect. + + A redirect is never followed or passed on, since its target would + receive the proxy key on the next hop. + """ + if 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, cors: Optional[str] = None 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_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() From e638d9459fa785c6e8723869f4aae66b06b5178f Mon Sep 17 00:00:00 2001 From: muzakon Date: Mon, 16 Nov 2026 17:42:32 +0300 Subject: [PATCH 05/16] Answer out-of-range upstream statuses with 502 An upstream status below 200 or above 599 is now answered 502 with Cache-Control: no-store, as in the Go proxy, instead of reaching the browser as a status line nothing in between understands. Refs: fingerly-io/sdks#48 --- README.md | 6 +++--- src/fingerly/_proxy.py | 7 ++++--- tests/test_proxy_status.py | 39 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 46 insertions(+), 6 deletions(-) create mode 100644 tests/test_proxy_status.py diff --git a/README.md b/README.md index 2d2bb92..a480488 100644 --- a/README.md +++ b/README.md @@ -266,9 +266,9 @@ When Fingerly cannot be reached in time the proxy answers `504 Gateway timeout`, and on any other upstream failure, such as a refused connection, a malformed or truncated response or one over 4 MiB, `502 Bad gateway`. A redirect is never followed, whatever transport you supply, and an upstream -redirect is answered `502` too. All of these are short plain text marked -`no-store`, and each writes one line, with no stack trace, to the -`fingerly.proxy` logger. +redirect or a status outside 200 to 599 is answered `502` too. All of these +are short plain text marked `no-store`, and each writes one line, with no stack +trace, to the `fingerly.proxy` logger. Back to the browser it relays only `content-type`, `x-request-id`, `ratelimit-limit`, `ratelimit-remaining` and `retry-after`, plus its own diff --git a/src/fingerly/_proxy.py b/src/fingerly/_proxy.py index 6278ba9..fcd1f1a 100644 --- a/src/fingerly/_proxy.py +++ b/src/fingerly/_proxy.py @@ -446,12 +446,13 @@ async def aforward( def _relay_or_refuse( self, reply: Reply, cors: Optional[str] = None ) -> ProxyResponse: - """Relays an answer, or answers 502 for an upstream redirect. + """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. + 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 300 <= reply.status <= 399: + 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) 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() From 8b807bc356444e9a9ae5a5ba83b09c1cbd13686c Mon Sep 17 00:00:00 2001 From: muzakon Date: Mon, 16 Nov 2026 17:43:05 +0300 Subject: [PATCH 06/16] Pin exact path and method rules with proxy tests The proxy already matched the method exactly and marked every refusal no-store; these tests hold it there under both adapters: post and Post get 405, near-miss, encoded and absolute-form targets get 404. Refs: fingerly-io/sdks#49 --- README.md | 8 ++-- tests/test_proxy_exact.py | 78 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 82 insertions(+), 4 deletions(-) create mode 100644 tests/test_proxy_exact.py diff --git a/README.md b/README.md index a480488..fa754e5 100644 --- a/README.md +++ b/README.md @@ -218,10 +218,10 @@ 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. Any path other -than the configured one (retired `/supplement` subpaths included) gets `404`, -and any method other than `POST` (plus `OPTIONS` when `allowed_origins` is -configured) gets `405`. Event reads need a secret key and stay unreachable from -a browser by construction. +than the configured one (`/supplement` subpaths included) gets `404`, and any +method other than `POST` (plus `OPTIONS` when `allowed_origins` is configured) +gets `405`. The method is matched exactly, so `post` gets `405` too. Event +reads need a secret key and stay unreachable from a browser by construction. `upstream` replaces the API origin for testing against a local API. It must be `https`. Plain `http` is accepted only for `127.0.0.1`, `localhost` or 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 From 5b28112cb185216fe1c405b5d2ba3dc916ee8294 Mon Sep 17 00:00:00 2001 From: muzakon Date: Mon, 16 Nov 2026 17:43:56 +0300 Subject: [PATCH 07/16] Accept only a bare origin as the proxy upstream The upstream takes a scheme, a host and an optional port: a path, query, fragment, credentials, space or control byte is refused, and the target is rebuilt from the parsed parts. Failure log lines name the kind of failure only, never the upstream address. Refs: fingerly-io/sdks#50 --- README.md | 13 +++--- src/fingerly/_config.py | 41 ++++++++++++----- src/fingerly/_proxy.py | 5 ++- tests/test_proxy_upstream.py | 87 ++++++++++++++++++++++++++++++++++++ 4 files changed, 129 insertions(+), 17 deletions(-) create mode 100644 tests/test_proxy_upstream.py diff --git a/README.md b/README.md index fa754e5..47bb762 100644 --- a/README.md +++ b/README.md @@ -223,10 +223,12 @@ method other than `POST` (plus `OPTIONS` when `allowed_origins` is configured) gets `405`. The method is matched exactly, so `post` gets `405` too. Event reads need a secret key and stay unreachable from a browser by construction. -`upstream` replaces the API origin for testing against a local API. 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: +`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( @@ -268,7 +270,8 @@ malformed or truncated response or one over 4 MiB, `502 Bad gateway`. A redirect is never followed, whatever transport you supply, and an upstream redirect or a status outside 200 to 599 is answered `502` too. All of these are short plain text marked `no-store`, and each writes one line, with no stack -trace, to the `fingerly.proxy` logger. +trace, to the `fingerly.proxy` logger. The line names the kind of failure only, +never the upstream address or a key. Back to the browser it relays only `content-type`, `x-request-id`, `ratelimit-limit`, `ratelimit-remaining` and `retry-after`, plus its own diff --git a/src/fingerly/_config.py b/src/fingerly/_config.py index c124dc2..e547bd5 100644 --- a/src/fingerly/_config.py +++ b/src/fingerly/_config.py @@ -122,6 +122,10 @@ 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"}) @@ -130,9 +134,11 @@ def normalize_endpoint(value: str) -> str: def normalize_api_origin( value: object, allow_insecure_loopback: bool, name: str ) -> str: - """Validates an API origin option and requires ``https``. + """Validates an API origin option and rebuilds it from its parts. - Plain ``http`` is accepted only for 127.0.0.1, localhost or [::1], and only + 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. @@ -147,21 +153,36 @@ def normalize_api_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: - origin = normalize_endpoint(value) # type: ignore[arg-type] - except TypeError: - raise TypeError( - f"{name} must be an HTTP(S) URL without credentials, query, or fragment" - ) from None - parts = urlsplit(origin) + 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 (parts.hostname or "") in LOOPBACK_HOSTS + 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" ) - return origin + 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: diff --git a/src/fingerly/_proxy.py b/src/fingerly/_proxy.py index fcd1f1a..b0e03af 100644 --- a/src/fingerly/_proxy.py +++ b/src/fingerly/_proxy.py @@ -274,8 +274,9 @@ 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. - ``https`` is required. + 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. 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 From 42ccc394ccd19d3393dfb7dc2e7d81e79b1247c1 Mon Sep 17 00:00:00 2001 From: muzakon Date: Mon, 16 Nov 2026 17:44:40 +0300 Subject: [PATCH 08/16] Events client endpoint requires an https origin The events client endpoint follows the proxy upstream rule: a bare https origin rebuilt from its parts, plain http only on a loopback host with allow_insecure_loopback=True, so the secret key never travels in clear or to a path the operator did not mean. Refs: fingerly-io/sdks#50 --- README.md | 11 +++-- src/fingerly/_client.py | 26 ++++++++-- tests/test_client_endpoint.py | 93 +++++++++++++++++++++++++++++++++++ tests/test_http.py | 12 ++++- 4 files changed, 132 insertions(+), 10 deletions(-) create mode 100644 tests/test_client_endpoint.py diff --git a/README.md b/README.md index 47bb762..a7e631b 100644 --- a/README.md +++ b/README.md @@ -40,9 +40,14 @@ In a web app, build the client once and reuse it: see 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. +`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. `FingerlyAPIError` provides `status`, and optional `code`, `details`, `request_id` and `retry_after`, the seconds a `429`, a `503` or a diff --git a/src/fingerly/_client.py b/src/fingerly/_client.py index cc32e9e..22e0248 100644 --- a/src/fingerly/_client.py +++ b/src/fingerly/_client.py @@ -16,8 +16,8 @@ DEFAULT_ENDPOINT, Secret, no_cookies, + normalize_api_origin, normalize_api_version, - normalize_endpoint, parse_key, positive_seconds, ) @@ -47,16 +47,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 +70,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") @@ -192,6 +202,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 +212,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( @@ -273,6 +286,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 +296,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], 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_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): From 1cca18328df260e2e5376dac70934d915d3d195c Mon Sep 17 00:00:00 2001 From: muzakon Date: Mon, 16 Nov 2026 20:54:25 +0300 Subject: [PATCH 09/16] Add the 0.3.0 risk signals to the SDK types Add attestation_downgrade, probe_errors and fetch_metadata_missing to the signal list, and decode attest_skipped and downgrade on the archived attestation. Cover both in the contract tests and the README. Refs: fingerly-io/server#19 Refs: fingerly-io/server#14 --- CHANGELOG.md | 8 ++++--- README.md | 9 +++++--- src/fingerly/_models.py | 13 +++++++++++ tests/test_contract.py | 49 +++++++++++++++++++++++++++++++++++++++++ 4 files changed, 73 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 59b3eca..8cd7979 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,9 +6,11 @@ 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`, `device_inconsistent`, - `report_incomplete`, `tampering`, `custom_root_ca`, - `secondary_user_profile`). + covering all v3 signals (`attestation_failed`, `attestation_downgrade`, + `device_inconsistent`, `report_incomplete`, `probe_errors`, + `fetch_metadata_missing`, `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 diff --git a/README.md b/README.md index a7e631b..5b6e0da 100644 --- a/README.md +++ b/README.md @@ -67,9 +67,12 @@ available, is an allow-listed view of the archived request with no raw signals, user agent or address, and `event.parse_document()` decodes it into a typed `EventDocument` (including `attestation: Optional[Attestation]`). `SIGNAL_NAMES` lists the canonical signal identifiers, including the `v: 3` anti-spoofing and -integrity signals `"attestation_failed"`, `"device_inconsistent"`, -`"report_incomplete"`, `"tampering"`, `"custom_root_ca"` and -`"secondary_user_profile"`. +integrity signals `"attestation_failed"`, `"attestation_downgrade"`, +`"device_inconsistent"`, `"report_incomplete"`, `"probe_errors"`, +`"fetch_metadata_missing"`, `"tampering"`, `"custom_root_ca"` and +`"secondary_user_profile"`. 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). `suspect_score` is `None` when the request was not scored, and must not be treated as zero. `Event` declares every documented field as an attribute and falls back to the decoded body for fields added later, so a new server field diff --git a/src/fingerly/_models.py b/src/fingerly/_models.py index 4745ff2..334ae98 100644 --- a/src/fingerly/_models.py +++ b/src/fingerly/_models.py @@ -78,6 +78,7 @@ "bot", "automation", "bad_bot", + "fetch_metadata_missing", "high_activity", "incognito_mode", "incognito", @@ -86,8 +87,10 @@ "active_call", "attestation_missing", "attestation_failed", + "attestation_downgrade", "device_inconsistent", "report_incomplete", + "probe_errors", "custom_root_ca", "secondary_user_profile", ) @@ -117,6 +120,12 @@ class Attestation: 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 @@ -132,6 +141,8 @@ class Attestation: 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 @@ -384,6 +395,8 @@ def _parse_attestation(payload: Mapping[str, Any]) -> Attestation: 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"), diff --git a/tests/test_contract.py b/tests/test_contract.py index 713f0fd..f5c8b41 100644 --- a/tests/test_contract.py +++ b/tests/test_contract.py @@ -155,8 +155,11 @@ def test_v3_openapi_and_models(self) -> None: v3_signals = [ "attestation_failed", + "attestation_downgrade", "device_inconsistent", "report_incomplete", + "probe_errors", + "fetch_metadata_missing", "tampering", "custom_root_ca", "secondary_user_profile", @@ -218,3 +221,49 @@ def test_v3_openapi_and_models(self) -> None: 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 From c519abcc9af1687cc822a4b340d319a996a27aee Mon Sep 17 00:00:00 2001 From: muzakon Date: Mon, 16 Nov 2026 23:30:21 +0300 Subject: [PATCH 10/16] Sync the 0.3.0 API contract Refresh the vendored OpenAPI snapshot from the server export. It adds attest_skipped, attest_key_id, the attest_key_status values and the iOS prev_assertion continuity proof. --- contract/manifest.json | 4 ++-- contract/openapi.json | 31 +++++++++++++++++++++++++------ 2 files changed, 27 insertions(+), 8 deletions(-) diff --git a/contract/manifest.json b/contract/manifest.json index ae1bfff..f0bbb9d 100644 --- a/contract/manifest.json +++ b/contract/manifest.json @@ -1,8 +1,8 @@ { "schema": 1, - "serverCommit": "c3deba4d383e5b92f9708a1570c125c3c9531023", + "serverCommit": "597aa2d131a3a7849b357aea9e1c78979ce509fd", "files": { - "openapi.json": "7a0f21ed27c7b01901f7be80b8070cc792b94d4c5bf239c0f0bee4e19662044d", + "openapi.json": "02f0f08285f49f18d903d6a926695c1fc76cd70e5f93979799468112584bc807", "fixtures.json": "3fbf2efbcf3c8ebced3d2c9f2a3c1f5752ee94ece63d5c110291d9a8251ff68f" } } diff --git a/contract/openapi.json b/contract/openapi.json index 5e0038c..458c632 100644 --- a/contract/openapi.json +++ b/contract/openapi.json @@ -42,8 +42,12 @@ "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 retiring 64-char hex Android key ID during 24h lease rollover", + "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": { @@ -513,6 +517,10 @@ ], "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" @@ -527,7 +535,7 @@ "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" }, "v": { @@ -540,8 +548,12 @@ }, "IdentifyOut": { "properties": { + "attest_key_id": { + "description": "Native only, present whenever attest was sent: the key_id the server evaluated, copied from attest.key_id", + "type": "string" + }, "attest_key_status": { - "description": "rekey_required when the presented v3 attestation key is unknown or expired", + "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": { @@ -656,6 +668,10 @@ ], "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" @@ -670,7 +686,7 @@ "type": "object" }, "tag": { - "description": "An opaque value echoed back on the event and kept in long-lived rollups; never a personal identifier", + "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" }, "v": { @@ -5333,8 +5349,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", From ad529c82135ae1d025d39c6e8cb12eb55c8e48a0 Mon Sep 17 00:00:00 2001 From: muzakon Date: Tue, 17 Nov 2026 00:23:56 +0300 Subject: [PATCH 11/16] Require a proxy key and never forward the secret key FingerlyProxy takes proxy_key only and has no secret_key parameter, so the server secret key never travels upstream. Every request must present a public key of the proxy key's environment or gets a 401. Refs: fingerly-io/sdks#43 --- CHANGELOG.md | 2 ++ README.md | 8 ++++-- src/fingerly/_proxy.py | 38 +++++++++----------------- tests/test_proxy.py | 57 +++++++++++++++++++++++++++++++-------- tests/test_redaction.py | 5 ++-- tests/test_regressions.py | 14 ++++++---- 6 files changed, 78 insertions(+), 46 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8cd7979..24e50ef 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,8 @@ 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 diff --git a/README.md b/README.md index 5b6e0da..3b4f686 100644 --- a/README.md +++ b/README.md @@ -248,8 +248,12 @@ proxy = FingerlyProxy( ) ``` -The caller must present a public key from the same environment as the proxy -key, or the request gets `401`. Incoming headers follow the sanitize-and-restore +`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`, diff --git a/src/fingerly/_proxy.py b/src/fingerly/_proxy.py index b0e03af..daefd46 100644 --- a/src/fingerly/_proxy.py +++ b/src/fingerly/_proxy.py @@ -197,7 +197,7 @@ 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. """ @@ -208,7 +208,6 @@ class Screening(NamedTuple): 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})" @@ -246,7 +245,6 @@ 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, @@ -265,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 @@ -293,19 +292,13 @@ 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_api_origin( upstream if upstream is not None else DEFAULT_ENDPOINT, @@ -327,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 @@ -498,12 +490,11 @@ def upstream_headers( 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-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. @@ -578,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: diff --git a/tests/test_proxy.py b/tests/test_proxy.py index 85bc154..c3509f3 100644 --- a/tests/test_proxy.py +++ b/tests/test_proxy.py @@ -154,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] @@ -651,16 +647,55 @@ def test_resolves_the_address_before_reading_the_body(self) -> None: 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={"origin": "https://shop.test"}) + 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: 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 9a88b32..1a2c179 100644 --- a/tests/test_regressions.py +++ b/tests/test_regressions.py @@ -292,13 +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") + proxy = FingerlyProxy(proxy_key=PROXY_KEY, client_ip=lambda _: "203.0.113.7") screening = proxy.screen( - ProxyRequest("POST", "/x", Headers([("origin", "https://shop.test")])) + ProxyRequest( + "POST", + "/x", + Headers([("origin", "https://shop.test"), ("x-api-key", PUBLIC_KEY)]), + ) ) - assert screening.api_key == SECRET_KEY - assert SECRET_KEY not in repr(screening) - assert SECRET_KEY not in str(screening) + assert screening.api_key == PUBLIC_KEY + assert PUBLIC_KEY not in repr(screening) + assert PUBLIC_KEY not in str(screening) class TestOneTlsContext: From f77cd3f353b314e9e52842a8d441c5010b101955 Mon Sep 17 00:00:00 2001 From: muzakon Date: Tue, 17 Nov 2026 01:12:35 +0300 Subject: [PATCH 12/16] Read and write the DeviceCheck bits of an event fingerly.device_check.query and write spend the token held for an iOS event, on the sync and the async client. Errors are typed by the API code, apple_rejected carries Apple's status, and a 503 or a transport failure is retried with the identical request. --- CHANGELOG.md | 8 + README.md | 47 ++++++ contract/manifest.json | 4 +- contract/openapi.json | 10 +- src/fingerly/__init__.py | 17 ++- src/fingerly/_client.py | 178 ++++++++++++++++++++++- src/fingerly/_errors.py | 44 ++++++ src/fingerly/_models.py | 56 +++++++ src/fingerly/_transport.py | 48 +++++- tests/test_device_check.py | 291 +++++++++++++++++++++++++++++++++++++ 10 files changed, 687 insertions(+), 16 deletions(-) create mode 100644 tests/test_device_check.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 24e50ef..e4168e3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,14 @@ ## 0.3.0 +- 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`, diff --git a/README.md b/README.md index 3b4f686..018548f 100644 --- a/README.md +++ b/README.md @@ -115,6 +115,53 @@ A `FingerlyEventPendingError` means the server has not decided yet: retry after 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`: `device_check_not_held` (404), `device_check_spent`, +`device_check_busy` or `credential_unavailable` (409), `bits_required` or +`apple_rejected` (422, with Apple's HTTP status in `apple_status`), and +`device_check_unavailable` (503). + +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. + ## Webhooks ```python diff --git a/contract/manifest.json b/contract/manifest.json index f0bbb9d..638c8bf 100644 --- a/contract/manifest.json +++ b/contract/manifest.json @@ -1,8 +1,8 @@ { "schema": 1, - "serverCommit": "597aa2d131a3a7849b357aea9e1c78979ce509fd", + "serverCommit": "4aeea102b5ec934037942daae5e517ec44a747ac", "files": { - "openapi.json": "02f0f08285f49f18d903d6a926695c1fc76cd70e5f93979799468112584bc807", + "openapi.json": "e2a1b8135fcea1e227a91346b10e465bdff849511632bd38acb46bbb5248bff7", "fixtures.json": "3fbf2efbcf3c8ebced3d2c9f2a3c1f5752ee94ece63d5c110291d9a8251ff68f" } } diff --git a/contract/openapi.json b/contract/openapi.json index 458c632..27682cf 100644 --- a/contract/openapi.json +++ b/contract/openapi.json @@ -2179,7 +2179,7 @@ }, "/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.", + "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. Apple answers a write with no previous value, and a token spent on a write cannot also read. 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": [ { @@ -2266,7 +2266,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": { @@ -2314,7 +2314,7 @@ }, "/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.", + "description": "Spends the 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 a token spent on a read cannot also write: to read and then mark a device, read on one identification and write on the next. After a `503`, retry the read: a token kept for a retry accepts only the request it was first used for.", "operationId": "readDeviceDevicecheckBits", "parameters": [ { @@ -2375,7 +2375,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": { @@ -2385,7 +2385,7 @@ } } }, - "description": "The request could not be validated." + "description": "`apple_rejected`: Apple rejected the token; `apple_status` says how" }, "503": { "content": { diff --git a/src/fingerly/__init__.py b/src/fingerly/__init__.py index 05c98c4..0b347c5 100644 --- a/src/fingerly/__init__.py +++ b/src/fingerly/__init__.py @@ -12,10 +12,18 @@ 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, FingerlyEventPendingError, FingerlyTimeoutError, @@ -23,6 +31,8 @@ from ._models import ( SIGNAL_NAMES, Attestation, + DeviceCheckBits, + DeviceCheckWriteResult, Event, EventDocument, EventPage, @@ -34,9 +44,13 @@ __all__ = [ "SIGNAL_NAMES", + "AsyncDeviceCheck", "AsyncEvents", "AsyncFingerly", "Attestation", + "DeviceCheck", + "DeviceCheckBits", + "DeviceCheckWriteResult", "Event", "EventDocument", "EventPage", @@ -45,6 +59,7 @@ "Fingerly", "FingerlyAPIError", "FingerlyConnectionError", + "FingerlyDeviceCheckError", "FingerlyError", "FingerlyEventPendingError", "FingerlyProxy", diff --git a/src/fingerly/_client.py b/src/fingerly/_client.py index 22e0248..d2afe88 100644 --- a/src/fingerly/_client.py +++ b/src/fingerly/_client.py @@ -4,6 +4,7 @@ import asyncio import threading +import time import warnings from collections.abc import Mapping from datetime import datetime @@ -23,11 +24,22 @@ ) from ._errors import FingerlyAPIError, FingerlyConnectionError, FingerlyTimeoutError from ._http import MAX_RESPONSE_BYTES, AsyncPool, Reply, ResponseTooLargeError, SyncPool -from ._models import Event, EventPage, parse_event, parse_page +from ._models import ( + DeviceCheckBits, + DeviceCheckWriteResult, + Event, + EventPage, + parse_device_check_bits, + parse_device_check_write, + parse_event, + parse_page, +) from ._transport import ( KeyAuth, api_error, decode_json, + device_check_body, + device_check_error, event_path, headers_for, list_params, @@ -182,6 +194,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. @@ -229,6 +369,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.""" @@ -246,9 +387,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. @@ -257,7 +403,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: @@ -315,6 +467,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.""" @@ -332,9 +485,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. @@ -342,7 +500,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/_errors.py b/src/fingerly/_errors.py index 7113108..4706008 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. diff --git a/src/fingerly/_models.py b/src/fingerly/_models.py index 334ae98..9428d69 100644 --- a/src/fingerly/_models.py +++ b/src/fingerly/_models.py @@ -268,6 +268,62 @@ 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 + + +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. diff --git a/src/fingerly/_transport.py b/src/fingerly/_transport.py index f85ae27..59b5dc6 100644 --- a/src/fingerly/_transport.py +++ b/src/fingerly/_transport.py @@ -16,7 +16,11 @@ import httpx from ._config import REDACTED, Secret, positive_int -from ._errors import FingerlyAPIError, FingerlyEventPendingError +from ._errors import ( + FingerlyAPIError, + FingerlyDeviceCheckError, + FingerlyEventPendingError, +) from ._version import __version__ #: Sent on every request so events record which SDK build made them. @@ -216,6 +220,48 @@ def api_error( ) +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, + ) + + def _redact(value: str, secret_key: Union[Secret, str]) -> str: """Strips the secret key from anything an error may carry to logs.""" key = secret_key.reveal() if isinstance(secret_key, Secret) else secret_key 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 From e704be2ecd3b6b56440e968a6043fcbe70226545 Mon Sep 17 00:00:00 2001 From: muzakon Date: Tue, 17 Nov 2026 01:27:56 +0300 Subject: [PATCH 13/16] Verify and consume events on the backend fingerly.events.verify reads an event and checks, in order, that it exists, is recent, carries the expected tag, is identifiable and scored, then consumes it once so one event backs one decision. fingerly.events.consume posts the consume on its own and raises FingerlyEventAlreadyConsumedError, with consumed_at, on a repeat. Both are on the sync and the async client and are never retried. Refs: fingerly-io/panels#13 --- CHANGELOG.md | 6 + README.md | 57 +++++- src/fingerly/__init__.py | 8 + src/fingerly/_client.py | 137 ++++++++++++- src/fingerly/_errors.py | 34 ++++ src/fingerly/_models.py | 118 ++++++++++- src/fingerly/_transport.py | 71 ++++++- tests/test_events_verify.py | 390 ++++++++++++++++++++++++++++++++++++ 8 files changed, 803 insertions(+), 18 deletions(-) create mode 100644 tests/test_events_verify.py diff --git a/CHANGELOG.md b/CHANGELOG.md index e4168e3..0f097f4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,12 @@ ## 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 diff --git a/README.md b/README.md index 018548f..191a907 100644 --- a/README.md +++ b/README.md @@ -103,17 +103,52 @@ The archived `document` arrives moments after the event itself, so check ## 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: + +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 diff --git a/src/fingerly/__init__.py b/src/fingerly/__init__.py index 0b347c5..e3e7c56 100644 --- a/src/fingerly/__init__.py +++ b/src/fingerly/__init__.py @@ -25,18 +25,22 @@ FingerlyConnectionError, FingerlyDeviceCheckError, FingerlyError, + FingerlyEventAlreadyConsumedError, FingerlyEventPendingError, FingerlyTimeoutError, ) from ._models import ( SIGNAL_NAMES, Attestation, + ConsumeResult, DeviceCheckBits, DeviceCheckWriteResult, Event, EventDocument, EventPage, EventTrigger, + VerifyReason, + VerifyResult, ) from ._proxy import FingerlyProxy, ProxyRequest from ._version import __version__ @@ -48,6 +52,7 @@ "AsyncEvents", "AsyncFingerly", "Attestation", + "ConsumeResult", "DeviceCheck", "DeviceCheckBits", "DeviceCheckWriteResult", @@ -61,10 +66,13 @@ "FingerlyConnectionError", "FingerlyDeviceCheckError", "FingerlyError", + "FingerlyEventAlreadyConsumedError", "FingerlyEventPendingError", "FingerlyProxy", "FingerlyTimeoutError", "ProxyRequest", + "VerifyReason", + "VerifyResult", "__version__", "verify_webhook", ] diff --git a/src/fingerly/_client.py b/src/fingerly/_client.py index d2afe88..de7eaf9 100644 --- a/src/fingerly/_client.py +++ b/src/fingerly/_client.py @@ -7,7 +7,7 @@ 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 @@ -22,17 +22,27 @@ 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 ( + 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, @@ -42,11 +52,22 @@ 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") @@ -137,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, @@ -177,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, diff --git a/src/fingerly/_errors.py b/src/fingerly/_errors.py index 4706008..dbc84e3 100644 --- a/src/fingerly/_errors.py +++ b/src/fingerly/_errors.py @@ -124,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 9428d69..aa8b423 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 @@ -302,6 +302,118 @@ class DeviceCheckWriteResult: 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") diff --git a/src/fingerly/_transport.py b/src/fingerly/_transport.py index 59b5dc6..1eee4e6 100644 --- a/src/fingerly/_transport.py +++ b/src/fingerly/_transport.py @@ -19,6 +19,7 @@ from ._errors import ( FingerlyAPIError, FingerlyDeviceCheckError, + FingerlyEventAlreadyConsumedError, FingerlyEventPendingError, ) from ._version import __version__ @@ -57,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. @@ -191,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)) @@ -205,21 +215,78 @@ 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. 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 From c431a095ce4b85005f29b996e87dfb8d03318ed4 Mon Sep 17 00:00:00 2001 From: muzakon Date: Tue, 17 Nov 2026 02:23:18 +0300 Subject: [PATCH 14/16] Sync the API contract for tickets, consume and DeviceCheck Refresh the vendored OpenAPI snapshot and its manifest from server 0f20954: the web ticket request and next_ticket, the consume route, consumed_at on the event read, and the DeviceCheck write token. --- contract/manifest.json | 4 +- contract/openapi.json | 232 +++++++++++++++++++++++++++++++++++++++-- 2 files changed, 228 insertions(+), 8 deletions(-) diff --git a/contract/manifest.json b/contract/manifest.json index 638c8bf..6a06721 100644 --- a/contract/manifest.json +++ b/contract/manifest.json @@ -1,8 +1,8 @@ { "schema": 1, - "serverCommit": "4aeea102b5ec934037942daae5e517ec44a747ac", + "serverCommit": "0f20954b09e4cbc1e9d399e322c6c97f9d009492", "files": { - "openapi.json": "e2a1b8135fcea1e227a91346b10e465bdff849511632bd38acb46bbb5248bff7", + "openapi.json": "34cb38e0e9fa15442e5ef8acc44b3c3b326976afd5f54eead2759e40ee53c1cd", "fixtures.json": "3fbf2efbcf3c8ebced3d2c9f2a3c1f5752ee94ece63d5c110291d9a8251ff68f" } } diff --git a/contract/openapi.json b/contract/openapi.json index 27682cf..6b7a3cf 100644 --- a/contract/openapi.json +++ b/contract/openapi.json @@ -23,7 +23,11 @@ "type": "string" }, "device_token": { - "description": "Optional Base64 Apple DeviceCheck token bound into statementDigest", + "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": { @@ -85,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", @@ -525,6 +533,10 @@ "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" @@ -538,6 +550,14 @@ "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", @@ -575,6 +595,17 @@ ], "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" @@ -676,6 +707,10 @@ "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" @@ -689,6 +724,14 @@ "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" }, + "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", @@ -1065,6 +1108,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": { @@ -1082,6 +1148,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" }, @@ -1320,6 +1394,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": [ @@ -1337,7 +1416,8 @@ "prefix", "project_id", "require_attestation", - "status" + "status", + "web_ticket_pow_bits" ], "type": "object" }, @@ -1673,6 +1753,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": { @@ -2177,9 +2280,118 @@ "x-title": "Get an event" } }, + "/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", + "name": "request_id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SDKEventConsumeOut" + } + } + }, + "description": "OK" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "No usable secret SDK key was presented" + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "The organization is suspended or closed" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "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": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "`event_already_consumed`: consumed before; `details[0]` is `{\"field\": \"consumed_at\", \"issue\": \"\"}`" + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "The request could not be validated." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "`events_unavailable`: retry after the `Retry-After` seconds" + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "An unexpected error occurred." + } + }, + "security": [ + { + "secretKey": [] + } + ], + "summary": "Mark an event consumed, once", + "tags": [ + "Server API" + ], + "x-category": "Server API", + "x-title": "Consume 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. Apple answers a write with no previous value, and a token spent on a write cannot also read. 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.", + "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": [ { @@ -2256,7 +2468,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": { @@ -2314,7 +2526,7 @@ }, "/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. Apple asks for each token to be used once, so a token spent on a read cannot also write: to read and then mark a device, read on one identification and write on the next. After a `503`, retry the read: a token kept for a retry accepts only the request it was first used for.", + "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": [ { @@ -2365,7 +2577,7 @@ } } }, - "description": "`device_check_not_held`: no token is held for that event" + "description": "`device_check_not_held`: no read token is held for that event" }, "409": { "content": { @@ -5788,6 +6000,14 @@ "type": "string" }, "type": "array" + }, + "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" From bd27a8d324096a54e6e8805b1479764f8744498d Mon Sep 17 00:00:00 2001 From: muzakon Date: Tue, 17 Nov 2026 02:46:39 +0300 Subject: [PATCH 15/16] Sync the API contract for the Private Access Token prototype Refresh the vendored OpenAPI snapshot and its manifest from server 2f24510: the prototype's per-key switch and the project's token issuer on the origins update. --- contract/manifest.json | 4 +-- contract/openapi.json | 69 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 71 insertions(+), 2 deletions(-) diff --git a/contract/manifest.json b/contract/manifest.json index 6a06721..f5d8ba0 100644 --- a/contract/manifest.json +++ b/contract/manifest.json @@ -1,8 +1,8 @@ { "schema": 1, - "serverCommit": "0f20954b09e4cbc1e9d399e322c6c97f9d009492", + "serverCommit": "2f24510cfb9a41f780936841cc47ca8a1c012201", "files": { - "openapi.json": "34cb38e0e9fa15442e5ef8acc44b3c3b326976afd5f54eead2759e40ee53c1cd", + "openapi.json": "87c3881291f8a9cba673f2a62a3bad85f6ff7f8195c01efcae54f84f6887bd93", "fixtures.json": "3fbf2efbcf3c8ebced3d2c9f2a3c1f5752ee94ece63d5c110291d9a8251ff68f" } } diff --git a/contract/openapi.json b/contract/openapi.json index 6b7a3cf..487d545 100644 --- a/contract/openapi.json +++ b/contract/openapi.json @@ -796,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": { @@ -1374,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" }, @@ -1414,6 +1464,7 @@ "last4", "name", "prefix", + "private_access_tokens", "project_id", "require_attestation", "status", @@ -6001,6 +6052,24 @@ }, "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", From ab898e8305a0fac5631358ad498c6c26d38058e6 Mon Sep 17 00:00:00 2001 From: muzakon Date: Tue, 17 Nov 2026 03:10:42 +0300 Subject: [PATCH 16/16] Add the web ticket signals to the SDK types --- CHANGELOG.md | 4 ++-- README.md | 4 ++-- src/fingerly/_models.py | 2 ++ tests/test_contract.py | 2 ++ 4 files changed, 8 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0f097f4..d1183dd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -22,8 +22,8 @@ `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`, `tampering`, `custom_root_ca`, - `secondary_user_profile`), with `attest_skipped` and `downgrade` on + `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 diff --git a/README.md b/README.md index 191a907..3a75cf7 100644 --- a/README.md +++ b/README.md @@ -69,8 +69,8 @@ user agent or address, and `event.parse_document()` decodes it into a typed 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"`, `"tampering"`, `"custom_root_ca"` and -`"secondary_user_profile"`. A native `Attestation` also carries +`"fetch_metadata_missing"`, `"web_ticket_missing"`, `"web_ticket_invalid"`, +`"tampering"`, `"custom_root_ca"` and `"secondary_user_profile"`. 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). `suspect_score` is `None` when the request was not scored, and must not be diff --git a/src/fingerly/_models.py b/src/fingerly/_models.py index aa8b423..99cb8ea 100644 --- a/src/fingerly/_models.py +++ b/src/fingerly/_models.py @@ -79,6 +79,8 @@ "automation", "bad_bot", "fetch_metadata_missing", + "web_ticket_missing", + "web_ticket_invalid", "high_activity", "incognito_mode", "incognito", diff --git a/tests/test_contract.py b/tests/test_contract.py index f5c8b41..7e82118 100644 --- a/tests/test_contract.py +++ b/tests/test_contract.py @@ -160,6 +160,8 @@ def test_v3_openapi_and_models(self) -> None: "report_incomplete", "probe_errors", "fetch_metadata_missing", + "web_ticket_missing", + "web_ticket_invalid", "tampering", "custom_root_ca", "secondary_user_profile",