diff --git a/CHANGELOG.md b/CHANGELOG.md index e93b316..73e267e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,20 @@ # Changelog +## Unreleased + +- `Event.getProjectId()` returns the Fingerly project an event belongs to, on + single reads and list rows. It is null when the server does not send it. +- Webhook `data` for `identification.completed` and `visitor.suspect` (and + `identification.refused` when the key was known) carries `project_id`; read + it from `getData()`. +- Events carry `ip_network` (`getIpNetwork()`), an IPv4 /24 or IPv6 /40, + instead of `ip_address`; the API no longer returns the address. +- `getDeferredSignals()` is removed: single-event reads no longer return the + deferred report. +- `getDocument()` is an allow-listed view of the archived submission, without + raw signals, user agent or address. +- The vendored contract snapshot is refreshed. + ## 0.1.0 First release: event reads, webhook verification and the same-origin proxy, diff --git a/README.md b/README.md index 9cc7570..9f77d95 100644 --- a/README.md +++ b/README.md @@ -39,6 +39,9 @@ before network access, by `build()` rather than by the first call. Requests do not follow redirects. `get` and `list` each perform one request and never retry. A null, empty, `.` or `..` request id is an `IllegalArgumentException`. +`getProjectId()` is the UUID of the Fingerly project the event belongs to, on +`get` and on every `list` row; it is null when an older server does not send it. + ## Artifacts Java has no single HTTP server standard, so the proxy ships an adapter per @@ -186,6 +189,8 @@ Apply your own policy to the server's verdict. A pending event verify asynchronously, rather than refusing the action. 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. +Never put a personal identifier (user ID, email, install ID or advertising ID) +in a tag: the server keeps tags in long-lived rollups. ## Webhooks @@ -205,7 +210,10 @@ matching signature in the comma-separated header is accepted; at most 32 are read. Malformed or missing input is a false result, never an exception. `WebhookEvent.getData()` stays a `JsonNode`, so a new event type needs no SDK -upgrade; `getDataJson()` is the same as text. +upgrade; `getDataJson()` is the same as text. `identification.completed` and +`visitor.suspect` carry the event's project as `data.project_id`; +`identification.refused` carries it only when the refused request named a known +key. Read it with `getData().path("project_id")`. ## Same-origin proxy diff --git a/contract/fixtures.json b/contract/fixtures.json index 51f1a0f..5c9c949 100644 --- a/contract/fixtures.json +++ b/contract/fixtures.json @@ -3,6 +3,7 @@ { "body": { "request_id": "0199a963-e400-7000-8000-000000000001", + "project_id": "0199a963-e400-7000-8000-0000000000a1", "visitor_id": "visitor-test", "occurred_at": "2026-09-17T12:00:00Z", "state": "enriched", @@ -10,7 +11,7 @@ "platform": "web", "sdk_platform": "web", "sdk_version": "0.1.0", - "ip_address": "203.0.113.10", + "ip_network": "203.0.113.0/24", "suspect_score": 0, "suspect_level": "low", "triggers": [], @@ -23,6 +24,7 @@ { "body": { "request_id": "0199a963-e400-7000-8000-000000000001", + "project_id": "0199a963-e400-7000-8000-0000000000a1", "visitor_id": "visitor-test", "occurred_at": "2026-09-17T12:00:00Z", "state": "unavailable", @@ -30,7 +32,7 @@ "platform": "web", "sdk_platform": "web", "sdk_version": "0.1.0", - "ip_address": "203.0.113.10", + "ip_network": "203.0.113.0/24", "suspect_score": null, "triggers": [], "has_document": false @@ -42,6 +44,7 @@ { "body": { "request_id": "0199a963-e400-7000-8000-000000000001", + "project_id": "0199a963-e400-7000-8000-0000000000a1", "visitor_id": "visitor-test", "occurred_at": "2026-09-17T12:00:00Z", "state": "enriched", @@ -49,7 +52,7 @@ "platform": "web", "sdk_platform": "web", "sdk_version": "0.1.0", - "ip_address": "203.0.113.10", + "ip_network": "203.0.113.0/24", "suspect_score": 0, "suspect_level": "low", "triggers": [], @@ -58,24 +61,11 @@ "schema": 1, "request_id": "0199a963-e400-7000-8000-000000000001", "occurred_at": "2026-09-17T12:00:00Z", - "organization_id": "tenant-test", - "project_id": "", - "sdk_key_id": "", - "environment": "development", "sdk": { "platform": "", "version": "" }, - "client_ip": "203.0.113.10", - "signals": null - }, - "deferred_signals": { - "fonts": { - "status": "ok", - "value": [ - "Arial" - ] - } + "ip_network": "203.0.113.0/24" } }, "name": "archived", @@ -87,6 +77,7 @@ "rows": [ { "request_id": "0199a963-e400-7000-8000-000000000001", + "project_id": "0199a963-e400-7000-8000-0000000000a1", "visitor_id": "visitor-test", "occurred_at": "2026-09-17T12:00:00Z", "state": "enriched", @@ -94,7 +85,7 @@ "platform": "web", "sdk_platform": "web", "sdk_version": "0.1.0", - "ip_address": "203.0.113.10", + "ip_network": "203.0.113.0/24", "suspect_score": 0, "suspect_level": "low", "triggers": [], @@ -203,33 +194,33 @@ "webhooks": [ { "name": "current", - "payload": "{\"id\":\"evt_contract\",\"type\":\"identification.completed\",\"data\":{\"request_id\":\"0199a963-e400-7000-8000-000000000001\"}}", + "payload": "{\"id\":\"evt_contract\",\"type\":\"identification.completed\",\"data\":{\"request_id\":\"0199a963-e400-7000-8000-000000000001\",\"project_id\":\"0199a963-e400-7000-8000-0000000000a1\"}}", "secret": "whsec_contract_current", - "signature": "sha256=f222a3199dae906df4608030c73d742410e40f003bd7b25292db11edb306b9d4", + "signature": "sha256=cba83ffd4a95e203b68a3ca967fde148975766425da50f6d5f8dc973994823e5", "timestamp": "1789646400", "valid": true }, { "name": "rotation_current", - "payload": "{\"id\":\"evt_contract\",\"type\":\"identification.completed\",\"data\":{\"request_id\":\"0199a963-e400-7000-8000-000000000001\"}}", + "payload": "{\"id\":\"evt_contract\",\"type\":\"identification.completed\",\"data\":{\"request_id\":\"0199a963-e400-7000-8000-000000000001\",\"project_id\":\"0199a963-e400-7000-8000-0000000000a1\"}}", "secret": "whsec_contract_current", - "signature": "sha256=f222a3199dae906df4608030c73d742410e40f003bd7b25292db11edb306b9d4,sha256=4d373c753341ff05adb96484a1ff629204fffb1889582a7ac905d61c60de35b5", + "signature": "sha256=cba83ffd4a95e203b68a3ca967fde148975766425da50f6d5f8dc973994823e5,sha256=ca64b6fb3b42c701bb03d7394d8a2111bfb4b3d364de1fa24ee3edd59e59bbd5", "timestamp": "1789646400", "valid": true }, { "name": "rotation_previous", - "payload": "{\"id\":\"evt_contract\",\"type\":\"identification.completed\",\"data\":{\"request_id\":\"0199a963-e400-7000-8000-000000000001\"}}", + "payload": "{\"id\":\"evt_contract\",\"type\":\"identification.completed\",\"data\":{\"request_id\":\"0199a963-e400-7000-8000-000000000001\",\"project_id\":\"0199a963-e400-7000-8000-0000000000a1\"}}", "secret": "whsec_contract_previous", - "signature": "sha256=f222a3199dae906df4608030c73d742410e40f003bd7b25292db11edb306b9d4,sha256=4d373c753341ff05adb96484a1ff629204fffb1889582a7ac905d61c60de35b5", + "signature": "sha256=cba83ffd4a95e203b68a3ca967fde148975766425da50f6d5f8dc973994823e5,sha256=ca64b6fb3b42c701bb03d7394d8a2111bfb4b3d364de1fa24ee3edd59e59bbd5", "timestamp": "1789646400", "valid": true }, { "name": "tampered", - "payload": "{\"id\":\"evt_contract\",\"type\":\"identification.completed\",\"data\":{\"request_id\":\"0199a963-e400-7000-8000-000000000001\"}} ", + "payload": "{\"id\":\"evt_contract\",\"type\":\"identification.completed\",\"data\":{\"request_id\":\"0199a963-e400-7000-8000-000000000001\",\"project_id\":\"0199a963-e400-7000-8000-0000000000a1\"}} ", "secret": "whsec_contract_current", - "signature": "sha256=f222a3199dae906df4608030c73d742410e40f003bd7b25292db11edb306b9d4", + "signature": "sha256=cba83ffd4a95e203b68a3ca967fde148975766425da50f6d5f8dc973994823e5", "timestamp": "1789646400", "valid": false } diff --git a/contract/manifest.json b/contract/manifest.json index ea0b946..7303153 100644 --- a/contract/manifest.json +++ b/contract/manifest.json @@ -1,8 +1,8 @@ { "schema": 1, - "serverCommit": "0c3fcf69928a3b75847d73203b1c881d14011e4c", + "serverCommit": "e22f96777b0d029464baa4e127d7a346b684d478", "files": { - "openapi.json": "36430ff82eec2126879ede24bd175ec0ba40e4547a50a7b0530bd2dd4ee9e711", - "fixtures.json": "379517de50da86ac559c6b0a4c47f4959fd35bc0e31538329cc66331ded1ea8e" + "openapi.json": "850e7627dbbf1789fe7a0a214ae28838f2cd80d42e251f9994f5cb42d72e6009", + "fixtures.json": "3fbf2efbcf3c8ebced3d2c9f2a3c1f5752ee94ece63d5c110291d9a8251ff68f" } } diff --git a/contract/openapi.json b/contract/openapi.json index 3c04ded..e1483dd 100644 --- a/contract/openapi.json +++ b/contract/openapi.json @@ -11,10 +11,18 @@ "description": "Base64-encoded one-use attestation nonce", "type": "string" }, + "device_check": { + "description": "Whether to send a DeviceCheck token with the App Attest evidence", + "type": "boolean" + }, "expires_at": { "description": "When the nonce becomes unusable", "format": "date-time", "type": "string" + }, + "play_integrity": { + "description": "Whether to send a Play Integrity token bound to this challenge", + "type": "boolean" } }, "required": [ @@ -23,6 +31,91 @@ ], "type": "object" }, + "AttestationCredentialOut": { + "properties": { + "client_email": { + "description": "Google only", + "type": "string" + }, + "cloud_project_number": { + "description": "Google only", + "format": "int64", + "type": "integer" + }, + "created_at": { + "format": "date-time", + "type": "string" + }, + "daily_budget": { + "description": "Google only", + "format": "int64", + "type": "integer" + }, + "device_check_enabled": { + "description": "Apple only", + "type": "boolean" + }, + "fingerprint": { + "description": "Lowercase hex SHA-256 of the public key, to recognise the key without the secret", + "type": "string" + }, + "key_id": { + "description": "Apple only", + "type": "string" + }, + "last_error": { + "description": "A short token for the last refusal from Apple or Google, such as apple-401", + "type": "string" + }, + "last_error_at": { + "format": "date-time", + "type": [ + "string", + "null" + ] + }, + "last_used_at": { + "format": "date-time", + "type": [ + "string", + "null" + ] + }, + "provider": { + "description": "apple or google-play", + "type": "string" + }, + "team_id": { + "description": "Apple only", + "type": "string" + }, + "updated_at": { + "format": "date-time", + "type": "string" + } + }, + "required": [ + "created_at", + "fingerprint", + "provider", + "updated_at" + ], + "type": "object" + }, + "AttestationCredentialsOut": { + "properties": { + "credentials": { + "items": { + "$ref": "#/components/schemas/AttestationCredentialOut" + }, + "type": "array" + } + }, + "required": [ + "credentials" + ], + "type": "object" + }, "CreatedWebhookOut": { "properties": { "endpoint": { @@ -38,6 +131,47 @@ ], "type": "object" }, + "DeviceCheckQueryOut": { + "properties": { + "bit0": { + "type": "boolean" + }, + "bit1": { + "type": "boolean" + }, + "found": { + "description": "False when Apple holds no bits for the device", + "type": "boolean" + }, + "last_update": { + "description": "When the bits last changed, YYYY-MM", + "type": "string" + } + }, + "required": [ + "bit0", + "bit1", + "found" + ], + "type": "object" + }, + "DeviceCheckWriteOut": { + "properties": { + "bit0": { + "type": [ + "boolean", + "null" + ] + }, + "bit1": { + "type": [ + "boolean", + "null" + ] + } + }, + "type": "object" + }, "ErrorBody": { "properties": { "code": { @@ -129,7 +263,8 @@ "has_document": { "type": "boolean" }, - "ip_address": { + "ip_network": { + "description": "The network the request came from: an IPv4 /24 or an IPv6 /40, such as 203.0.113.0/24", "type": "string" }, "occurred_at": { @@ -144,6 +279,10 @@ "platform": { "type": "string" }, + "project_id": { + "description": "The project the event belongs to", + "type": "string" + }, "reason": { "description": "Why enrichment did not happen, on an unavailable event", "type": "string" @@ -195,7 +334,6 @@ "required": [ "environment", "has_document", - "ip_address", "occurred_at", "platform", "request_id", @@ -312,7 +450,7 @@ "type": "object" }, "tag": { - "description": "An opaque value echoed back on the event", + "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" } }, @@ -320,6 +458,10 @@ }, "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", "type": "string" @@ -428,7 +570,7 @@ "type": "object" }, "tag": { - "description": "An opaque value echoed back on the event. Identify only", + "description": "An opaque value echoed back on the event and kept in long-lived rollups; never a personal identifier. Identify only", "type": "string" }, "token": { @@ -494,6 +636,123 @@ ], "type": "object" }, + "ProjectArchivedOut": { + "properties": { + "archived": { + "type": "boolean" + }, + "id": { + "type": "string" + } + }, + "required": [ + "archived", + "id" + ], + "type": "object" + }, + "ProjectOut": { + "properties": { + "created_at": { + "format": "date-time", + "type": "string" + }, + "id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "organization_id": { + "type": "string" + }, + "status": { + "type": "string" + } + }, + "required": [ + "created_at", + "id", + "name", + "organization_id", + "status" + ], + "type": "object" + }, + "ProjectPurgeOut": { + "properties": { + "archive_copies_expire_by": { + "description": "When the last archived copy of the project's data, written before per-project archiving, expires; absent if the project never sent traffic", + "format": "date-time", + "type": [ + "string", + "null" + ] + }, + "completed_at": { + "format": "date-time", + "type": [ + "string", + "null" + ] + }, + "id": { + "type": "string" + }, + "next_attempt_at": { + "description": "When a pending pass runs next", + "format": "date-time", + "type": "string" + }, + "pass": { + "description": "first, ten minutes after the request, or sweep, a day after the first finished", + "type": "string" + }, + "project_id": { + "type": "string" + }, + "status": { + "description": "pending, then done", + "type": "string" + } + }, + "required": [ + "id", + "next_attempt_at", + "pass", + "project_id", + "status" + ], + "type": "object" + }, + "ProjectPurgesOut": { + "properties": { + "purges": { + "items": { + "$ref": "#/components/schemas/ProjectPurgeOut" + }, + "type": "array" + } + }, + "required": [ + "purges" + ], + "type": "object" + }, + "ProjectsOut": { + "properties": { + "projects": { + "items": { + "$ref": "#/components/schemas/ProjectOut" + }, + "type": "array" + } + }, + "required": [ + "projects" + ], + "type": "object" + }, "ProxyCredentialOut": { "properties": { "created_at": { @@ -712,15 +971,11 @@ "country_name": { "type": "string" }, - "deferred_signals": { - "description": "The deferred report attached to this request, when one arrived. Its contents are not a public contract.", - "type": "object" - }, "device_kind": { "type": "string" }, "document": { - "description": "The archived submission as Fingerly stored it, with the threshold and weights profile that scored it. Present when has_document is true. Its contents are not a public contract.", + "description": "What Fingerly keeps of the submission, present when has_document is true: the schema, request id, time, SDK, IP network, the city-level IP answer, the risk score and triggers, attestation and the velocity decisions. Never the raw signals, the user agent or the address. Its contents are not a public contract.", "type": [ "object", "null" @@ -732,7 +987,8 @@ "has_document": { "type": "boolean" }, - "ip_address": { + "ip_network": { + "description": "The network the request came from: an IPv4 /24 or an IPv6 /40, such as 203.0.113.0/24", "type": "string" }, "occurred_at": { @@ -747,6 +1003,10 @@ "platform": { "type": "string" }, + "project_id": { + "description": "The project the event belongs to", + "type": "string" + }, "reason": { "description": "Why enrichment did not happen, on an unavailable event", "type": "string" @@ -798,7 +1058,6 @@ "required": [ "environment", "has_document", - "ip_address", "occurred_at", "platform", "request_id", @@ -1097,67 +1356,234 @@ ], "type": "object" }, - "VisitorErasureOut": { + "UsageDayOut": { "properties": { - "completed_at": { - "description": "When everything else was removed", - "format": "date-time", - "type": [ - "string", - "null" - ] + "billable": { + "description": "How much of it was on a production key", + "format": "int64", + "type": "integer" }, - "id": { - "type": "string" + "billed_micros": { + "format": "int64", + "type": "integer" }, - "requested_at": { - "description": "When it was asked for, and when the identity itself was removed", + "checks": { + "description": "Everything that arrived, including what was refused", + "format": "int64", + "type": "integer" + }, + "date": { "format": "date-time", "type": "string" }, - "status": { - "description": "pending while the stored identifications and archived submissions are being removed, then done", - "type": "string" + "rejected": { + "description": "Rate-limited or out of credit", + "format": "int64", + "type": "integer" }, - "visitor_id": { - "type": "string" - } - }, - "required": [ - "id", - "requested_at", - "status", - "visitor_id" - ], - "type": "object" - }, - "VisitorErasuresOut": { - "properties": { - "erasures": { - "items": { - "$ref": "#/components/schemas/VisitorErasureOut" - }, - "type": "array" + "settled": { + "type": "boolean" + }, + "test": { + "description": "Counted and never billed", + "format": "int64", + "type": "integer" } }, "required": [ - "erasures" + "billable", + "billed_micros", + "checks", + "date", + "rejected", + "settled", + "test" ], "type": "object" }, - "WebhookDeliveriesOut": { + "UsageKeyOut": { "properties": { - "deliveries": { - "items": { - "$ref": "#/components/schemas/WebhookDeliveryOut" - }, - "type": "array" + "billable": { + "format": "int64", + "type": "integer" }, - "next_cursor": { - "type": [ - "string", - "null" - ] + "billed_micros": { + "format": "int64", + "type": "integer" + }, + "checks": { + "format": "int64", + "type": "integer" + }, + "environment": { + "type": "string" + }, + "id": { + "type": "string" + }, + "kind": { + "description": "public or secret", + "type": "string" + }, + "last4": { + "type": "string" + }, + "last_used_at": { + "description": "Written best-effort and batched", + "format": "date-time", + "type": [ + "string", + "null" + ] + }, + "name": { + "type": "string" + }, + "prefix": { + "type": "string" + }, + "rejected": { + "format": "int64", + "type": "integer" + }, + "status": { + "type": "string" + } + }, + "required": [ + "billable", + "billed_micros", + "checks", + "environment", + "id", + "rejected" + ], + "type": "object" + }, + "UsageOut": { + "properties": { + "days": { + "items": { + "$ref": "#/components/schemas/UsageDayOut" + }, + "type": "array" + }, + "from": { + "format": "date-time", + "type": "string" + }, + "keys": { + "items": { + "$ref": "#/components/schemas/UsageKeyOut" + }, + "type": "array" + }, + "pending_checks": { + "format": "int64", + "type": "integer" + }, + "pending_days": { + "format": "int64", + "type": "integer" + }, + "pending_micros": { + "format": "int64", + "type": "integer" + }, + "rate_per_check_micros": { + "format": "int64", + "type": "integer" + }, + "rate_per_lookup_micros": { + "format": "int64", + "type": "integer" + }, + "settled_through": { + "format": "date-time", + "type": [ + "string", + "null" + ] + }, + "to": { + "format": "date-time", + "type": "string" + } + }, + "required": [ + "days", + "from", + "keys", + "pending_checks", + "pending_days", + "pending_micros", + "rate_per_check_micros", + "rate_per_lookup_micros", + "to" + ], + "type": "object" + }, + "VisitorErasureOut": { + "properties": { + "completed_at": { + "description": "When everything else was removed", + "format": "date-time", + "type": [ + "string", + "null" + ] + }, + "id": { + "type": "string" + }, + "requested_at": { + "description": "When it was asked for, and when the identity itself was removed", + "format": "date-time", + "type": "string" + }, + "status": { + "description": "pending while the stored identifications and archived submissions are being removed, then done", + "type": "string" + }, + "visitor_id": { + "type": "string" + } + }, + "required": [ + "id", + "requested_at", + "status", + "visitor_id" + ], + "type": "object" + }, + "VisitorErasuresOut": { + "properties": { + "erasures": { + "items": { + "$ref": "#/components/schemas/VisitorErasureOut" + }, + "type": "array" + } + }, + "required": [ + "erasures" + ], + "type": "object" + }, + "WebhookDeliveriesOut": { + "properties": { + "deliveries": { + "items": { + "$ref": "#/components/schemas/WebhookDeliveryOut" + }, + "type": "array" + }, + "next_cursor": { + "type": [ + "string", + "null" + ] } }, "required": [ @@ -1403,7 +1829,7 @@ } } }, - "description": "Challenges are being requested faster than the rate limit allows" + "description": "Challenges are being requested faster than the key's, the address's or the organization's rate limit allows; retry after Retry-After" }, "503": { "content": { @@ -1516,6 +1942,16 @@ }, "description": "No usable secret SDK key was presented" }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "The organization is suspended or closed" + }, "422": { "content": { "application/json": { @@ -1585,6 +2021,16 @@ }, "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": { @@ -1629,10 +2075,10 @@ "x-title": "Get an event" } }, - "/api/v1/events/{request_id}/supplement": { - "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", + "/api/v1/events/{request_id}/device-check": { + "put": { + "description": "Spends the DeviceCheck token held for this iOS event, once, to set bit0, bit1 or both with Apple, using your project's own Apple key. A bit left out keeps its value. The bits mean what you decide; Fingerly never reads them. Tokens are held for one hour, only for events whose App Attest evidence covered them, and only when DeviceCheck is switched on for the project's Apple credential.", + "operationId": "setDeviceDevicecheckBits", "parameters": [ { "in": "path", @@ -1648,22 +2094,19 @@ "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" + "bit0": { + "description": "The value to set for the first bit. Leave out to keep it", + "type": [ + "boolean", + "null" + ] }, - "token": { - "description": "The deferred_token returned by identify", - "type": "string" + "bit1": { + "description": "The value to set for the second bit. Leave out to keep it", + "type": [ + "boolean", + "null" + ] } }, "type": "object" @@ -1673,15 +2116,15 @@ "required": true }, "responses": { - "202": { + "200": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SupplementOut" + "$ref": "#/components/schemas/DeviceCheckWriteOut" } } }, - "description": "Accepted" + "description": "OK" }, "401": { "content": { @@ -1691,9 +2134,9 @@ } } }, - "description": "No usable x-api-key header was presented" + "description": "No usable secret SDK key was presented" }, - "402": { + "403": { "content": { "application/json": { "schema": { @@ -1701,7 +2144,17 @@ } } }, - "description": "The organization this key belongs to is not accepting traffic" + "description": "The organization is suspended or closed" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "`device_check_not_held`: no token is held for that event" }, "409": { "content": { @@ -1711,7 +2164,7 @@ } } }, - "description": "A different deferred report was already accepted for this request" + "description": "`device_check_spent`, `device_check_busy` or `credential_unavailable`" }, "422": { "content": { @@ -1721,7 +2174,7 @@ } } }, - "description": "The request could not be validated." + "description": "`bits_required` or `apple_rejected`" }, "503": { "content": { @@ -1731,7 +2184,7 @@ } } }, - "description": "The report could not be accepted just now" + "description": "`device_check_unavailable`: retry within the hour" }, "default": { "content": { @@ -1746,37 +2199,37 @@ }, "security": [ { - "publicKey": [] + "secretKey": [] } ], - "summary": "Submit a deferred report", + "summary": "Set the device's DeviceCheck bits", "tags": [ - "Client API" + "Server API" ], - "x-category": "Client API", - "x-title": "Submit a deferred report" + "x-category": "Server API", + "x-title": "Write an event's DeviceCheck bits" } }, - "/api/v1/identify": { + "/api/v1/events/{request_id}/device-check/query": { "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" - } + "description": "Spends the DeviceCheck token held for this iOS event, once, to read the device's two bits from Apple. A token spent on a read cannot also write; to mark a device, write instead.", + "operationId": "readDeviceDevicecheckBits", + "parameters": [ + { + "in": "path", + "name": "request_id", + "required": true, + "schema": { + "type": "string" } - }, - "required": true - }, + } + ], "responses": { "200": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/IdentifyOut" + "$ref": "#/components/schemas/DeviceCheckQueryOut" } } }, @@ -1790,9 +2243,9 @@ } } }, - "description": "No usable x-api-key header was presented" + "description": "No usable secret SDK key was presented" }, - "402": { + "403": { "content": { "application/json": { "schema": { @@ -1800,9 +2253,9 @@ } } }, - "description": "The organization this key belongs to is not accepting traffic" + "description": "The organization is suspended or closed" }, - "413": { + "404": { "content": { "application/json": { "schema": { @@ -1810,9 +2263,246 @@ } } }, - "description": "The body is over 1 MiB" + "description": "`device_check_not_held`: no token is held for that event" }, - "422": { + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "`device_check_spent`, `device_check_busy` or `credential_unavailable`" + }, + "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": "`device_check_unavailable`: retry within the hour" + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "An unexpected error occurred." + } + }, + "security": [ + { + "secretKey": [] + } + ], + "summary": "Read the device's DeviceCheck bits", + "tags": [ + "Server API" + ], + "x-category": "Server API", + "x-title": "Read an event's DeviceCheck bits" + } + }, + "/api/v1/events/{request_id}/supplement": { + "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" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "consent": { + "description": "The SDK's consent state; must be granted, or the request is refused with consent_required", + "type": "string" + }, + "sdk": { + "$ref": "#/components/schemas/SDKInfo", + "description": "Which SDK collected these signals" + }, + "signals": { + "additionalProperties": {}, + "description": "A report containing only the deferred tier", + "type": "object" + }, + "token": { + "description": "The deferred_token returned by identify", + "type": "string" + } + }, + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "202": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SupplementOut" + } + } + }, + "description": "Accepted" + }, + "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" + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "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" + }, + "413": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "The body is over 1 MiB" + }, + "422": { "content": { "application/json": { "schema": { @@ -1830,7 +2520,7 @@ } } }, - "description": "The organization is over its rate limit" + "description": "The SDK key or the organization is over its rate limit; retry after Retry-After. A secret key called from a backend is also told which limit in Fingerly-RateLimit-Scope" }, "503": { "content": { @@ -1952,7 +2642,7 @@ } } }, - "description": "The organization is over its rate limit" + "description": "The SDK key or the organization is over its rate limit; retry after Retry-After. A secret key called from a backend is also told which limit in Fingerly-RateLimit-Scope" }, "503": { "content": { @@ -1976,6 +2666,9 @@ } }, "security": [ + { + "publicKey": [] + }, { "secretKey": [] } @@ -2021,7 +2714,7 @@ } } }, - "description": "The management key's role does not allow this" + "description": "The management key's role does not allow this, or its organization is suspended or closed" }, "404": { "content": { @@ -2076,11 +2769,1282 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/HostedDomainsOut" + "$ref": "#/components/schemas/HostedDomainsOut" + } + } + }, + "description": "OK" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "No usable management key was presented" + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Only an admin key may manage hosted domains" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "No such resource in the key's organization" + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "The request could not be validated." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "An unexpected error occurred." + } + }, + "security": [ + { + "managementKey": [] + } + ], + "summary": "List hosted domains", + "tags": [ + "Management API" + ], + "x-category": "Management: hosted domains", + "x-title": "List hosted domains" + }, + "post": { + "description": "Registers a subdomain of your site for Fingerly to serve the browser SDK on, and asks for its certificate. It becomes `active` once your CNAME to `target` resolves and the certificate is issued. Omit `path` for a random one.", + "operationId": "addHostedDomain", + "parameters": [ + { + "in": "path", + "name": "organization_id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "hostname": { + "description": "A subdomain of your site, such as k7.shop.example, that you will CNAME to target", + "type": "string" + }, + "path": { + "description": "Where the browser SDK posts on it. Omit it for a random one", + "type": "string" + } + }, + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "201": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HostedDomainOut" + } + } + }, + "description": "Created" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "No usable management key was presented" + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Only an admin key may manage hosted domains" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "No such resource in the key's organization" + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "The hostname is taken, or hosted domains are not available" + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "The hostname or path is not usable" + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "An unexpected error occurred." + } + }, + "security": [ + { + "managementKey": [] + } + ], + "summary": "Add a hosted domain", + "tags": [ + "Management API" + ], + "x-category": "Management: hosted domains", + "x-title": "Add a hosted domain" + } + }, + "/api/v1/management/organizations/{organization_id}/hosted-domains/{hosted_domain_id}": { + "delete": { + "operationId": "removeHostedDomain", + "parameters": [ + { + "in": "path", + "name": "organization_id", + "required": true, + "schema": { + "type": "string" + } + }, + { + "in": "path", + "name": "hosted_domain_id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "No Content" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "No usable management key was presented" + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Only an admin key may manage hosted domains" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "No such resource in the key's organization" + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "The request could not be validated." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "An unexpected error occurred." + } + }, + "security": [ + { + "managementKey": [] + } + ], + "summary": "Remove a hosted domain", + "tags": [ + "Management API" + ], + "x-category": "Management: hosted domains", + "x-title": "Remove a hosted domain" + } + }, + "/api/v1/management/organizations/{organization_id}/hosted-domains/{hosted_domain_id}/check": { + "post": { + "operationId": "checkHostedDomainNow", + "parameters": [ + { + "in": "path", + "name": "organization_id", + "required": true, + "schema": { + "type": "string" + } + }, + { + "in": "path", + "name": "hosted_domain_id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HostedDomainOut" + } + } + }, + "description": "OK" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "No usable management key was presented" + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Only an admin key may manage hosted domains" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "No such resource in the key's organization" + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "The request could not be validated." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "An unexpected error occurred." + } + }, + "security": [ + { + "managementKey": [] + } + ], + "summary": "Check a hosted domain now", + "tags": [ + "Management API" + ], + "x-category": "Management: hosted domains", + "x-title": "Check a hosted domain" + } + }, + "/api/v1/management/organizations/{organization_id}/projects": { + "get": { + "description": "Every project of the organization, archived ones included.", + "operationId": "listProjects", + "parameters": [ + { + "in": "path", + "name": "organization_id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectsOut" + } + } + }, + "description": "OK" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "No usable management key was presented" + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "The management key's role does not allow this, or its organization is suspended or closed" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "No such resource in the key's organization" + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "The request could not be validated." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "An unexpected error occurred." + } + }, + "security": [ + { + "managementKey": [] + } + ], + "summary": "List projects", + "tags": [ + "Management API" + ], + "x-category": "Management: projects", + "x-title": "List projects" + }, + "post": { + "description": "One project per client app or site keeps its visitors, velocity, keys and data apart from every other project. `name` is 1 to 128 characters and unique in the organization.", + "operationId": "createProject", + "parameters": [ + { + "in": "path", + "name": "organization_id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "name": { + "type": "string" + } + }, + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "201": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectOut" + } + } + }, + "description": "Created" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "No usable management key was presented" + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Only an admin key may create a project" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "No such resource in the key's organization" + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "The name is taken, or the organization is at its project limit" + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "The request could not be validated." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "An unexpected error occurred." + } + }, + "security": [ + { + "managementKey": [] + } + ], + "summary": "Create a project", + "tags": [ + "Management API" + ], + "x-category": "Management: projects", + "x-title": "Create a project" + } + }, + "/api/v1/management/organizations/{organization_id}/projects/{project_id}": { + "delete": { + "description": "Revokes the project's keys, so its traffic stops at once, and keeps its data. There is no un-archive.", + "operationId": "archiveProject", + "parameters": [ + { + "in": "path", + "name": "organization_id", + "required": true, + "schema": { + "type": "string" + } + }, + { + "in": "path", + "name": "project_id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectArchivedOut" + } + } + }, + "description": "OK" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "No usable management key was presented" + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Only an admin key may archive a project" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "No such resource in the key's organization" + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "The request could not be validated." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "An unexpected error occurred." + } + }, + "security": [ + { + "managementKey": [] + } + ], + "summary": "Archive a project", + "tags": [ + "Management API" + ], + "x-category": "Management: projects", + "x-title": "Archive a project" + } + }, + "/api/v1/management/organizations/{organization_id}/projects/{project_id}/attestation-credentials": { + "get": { + "description": "Metadata only: the Team ID, key ID or Cloud project number, a fingerprint of the public key and the last error the platform returned. The secret is never returned.", + "operationId": "listProjectAppleAndGoogleCredentials", + "parameters": [ + { + "description": "The organization the project belongs to", + "in": "path", + "name": "organization_id", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "The project the credentials are for", + "in": "path", + "name": "project_id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AttestationCredentialsOut" + } + } + }, + "description": "OK" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "No usable management key was presented" + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "The management key's role does not allow this, or its organization is suspended or closed" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "No such resource in the key's organization" + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "The request could not be validated." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "An unexpected error occurred." + } + }, + "security": [ + { + "managementKey": [] + } + ], + "summary": "List a project's Apple and Google credentials", + "tags": [ + "Management API" + ], + "x-category": "Management: platform credentials", + "x-title": "List platform credentials" + } + }, + "/api/v1/management/organizations/{organization_id}/projects/{project_id}/attestation-credentials/apple": { + "delete": { + "description": "Takes effect everywhere within ten minutes. Owner or admin only.", + "operationId": "deleteProjectAppleKey", + "parameters": [ + { + "description": "The organization the project belongs to", + "in": "path", + "name": "organization_id", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "The project the credentials are for", + "in": "path", + "name": "project_id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "No Content" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "No usable management key was presented" + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "The management key's role does not allow this, or its organization is suspended or closed" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "The project has no Apple credential" + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "The request could not be validated." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "An unexpected error occurred." + } + }, + "security": [ + { + "managementKey": [] + } + ], + "summary": "Delete a project's Apple key", + "tags": [ + "Management API" + ], + "x-category": "Management: platform credentials", + "x-title": "Delete the Apple credential" + }, + "put": { + "description": "The key (a .p8 file with DeviceCheck enabled) is used only for this project's apps: to refresh App Attest receipts and, with device_check_enabled, to read and write DeviceCheck bits on your backend's request. It is sealed on arrival and never returned. Owner or admin only.", + "operationId": "uploadOrReplaceProjectAppleKey", + "parameters": [ + { + "description": "The organization the project belongs to", + "in": "path", + "name": "organization_id", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "The project the credential is for", + "in": "path", + "name": "project_id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "device_check_enabled": { + "description": "Ask iOS apps for a DeviceCheck token and hold it for this project's backend for one hour. Defaults to false", + "type": "boolean" + }, + "key_id": { + "description": "The 10-character ID of the key, as App Store Connect shows it", + "type": "string" + }, + "private_key": { + "description": "The PEM contents of the .p8 file. The key must have DeviceCheck enabled. Never returned", + "type": "string" + }, + "team_id": { + "description": "The 10-character Apple Team ID that owns the apps", + "type": "string" + } + }, + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AttestationCredentialOut" + } + } + }, + "description": "OK" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "No usable management key was presented" + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "The management key's role does not allow this, or its organization is suspended or closed" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "No such resource in the key's organization" + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "The key or an identifier is not valid" + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Credentials cannot be stored on this deployment" + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "An unexpected error occurred." + } + }, + "security": [ + { + "managementKey": [] + } + ], + "summary": "Upload or replace a project's Apple key", + "tags": [ + "Management API" + ], + "x-category": "Management: platform credentials", + "x-title": "Set the Apple credential" + } + }, + "/api/v1/management/organizations/{organization_id}/projects/{project_id}/attestation-credentials/google-play": { + "delete": { + "description": "Takes effect everywhere within ten minutes. Owner or admin only.", + "operationId": "deleteProjectGoogleServiceAccount", + "parameters": [ + { + "description": "The organization the project belongs to", + "in": "path", + "name": "organization_id", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "The project the credentials are for", + "in": "path", + "name": "project_id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "No Content" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "No usable management key was presented" + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "The management key's role does not allow this, or its organization is suspended or closed" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "The project has no Google Play credential" + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "The request could not be validated." + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "An unexpected error occurred." + } + }, + "security": [ + { + "managementKey": [] + } + ], + "summary": "Delete a project's Google service account", + "tags": [ + "Management API" + ], + "x-category": "Management: platform credentials", + "x-title": "Delete the Google Play credential" + }, + "put": { + "description": "A service account in the Google Cloud project linked to the app in Play Console, used only to decode this project's Play Integrity tokens, within daily_budget decodes a day. Sealed on arrival and never returned. Owner or admin only.", + "operationId": "uploadOrReplaceProjectGoogleServiceAccount", + "parameters": [ + { + "description": "The organization the project belongs to", + "in": "path", + "name": "organization_id", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "The project the credential is for", + "in": "path", + "name": "project_id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "cloud_project_number": { + "description": "The number of the Google Cloud project linked to the app in Play Console", + "format": "int64", + "type": "integer" + }, + "daily_budget": { + "description": "Play Integrity decodes Fingerly may spend per UTC day. Defaults to 4000, leaving the rest of Google's 10000 to your own use", + "format": "int64", + "type": [ + "integer", + "null" + ] + }, + "service_account": { + "description": "The JSON key file of a service account in that project. Never returned", + "type": "string" + } + }, + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AttestationCredentialOut" + } + } + }, + "description": "OK" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "No usable management key was presented" + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "The management key's role does not allow this, or its organization is suspended or closed" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "No such resource in the key's organization" + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "The service account or a field is not valid" + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Credentials cannot be stored on this deployment" + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "An unexpected error occurred." + } + }, + "security": [ + { + "managementKey": [] + } + ], + "summary": "Upload or replace a project's Google service account", + "tags": [ + "Management API" + ], + "x-category": "Management: platform credentials", + "x-title": "Set the Google Play credential" + } + }, + "/api/v1/management/organizations/{organization_id}/projects/{project_id}/installs/{platform}/{install_id}": { + "delete": { + "description": "Erases the visitor an iOS or Android app install resolved to in this project, for a data subject's request that names the app and the install rather than a visitor ID. `install_id` is the identifier the Fingerly SDK stored in the app. Visitors are never shared between projects, so this finds the project's visitor and no other; the erasure then proceeds as one by visitor ID, and the answer lists it.\n\n404 `install_not_found` means no stored identity maps to the install, so no data can be linked to it.", + "operationId": "eraseVisitorOfOneAppInstall", + "parameters": [ + { + "description": "The organization", + "in": "path", + "name": "organization_id", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "The project the app belongs to", + "in": "path", + "name": "project_id", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "ios or android", + "in": "path", + "name": "platform", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "The install identifier the Fingerly SDK stored in the app", + "in": "path", + "name": "install_id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "202": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VisitorErasuresOut" } } }, - "description": "OK" + "description": "Accepted" }, "401": { "content": { @@ -2100,7 +4064,7 @@ } } }, - "description": "Only an admin key may manage hosted domains" + "description": "Only an admin key may erase a visitor" }, "404": { "content": { @@ -2110,7 +4074,7 @@ } } }, - "description": "No such resource in the key's organization" + "description": "No such project, or no visitor holds that install" }, "422": { "content": { @@ -2120,7 +4084,7 @@ } } }, - "description": "The request could not be validated." + "description": "The platform is not ios or android" }, "default": { "content": { @@ -2138,56 +4102,47 @@ "managementKey": [] } ], - "summary": "List hosted domains", + "summary": "Erase the visitor of one app install", "tags": [ "Management API" ], - "x-category": "Management: hosted domains", - "x-title": "List hosted domains" - }, - "post": { - "description": "Registers a subdomain of your site for Fingerly to serve the browser SDK on, and asks for its certificate. It becomes `active` once your CNAME to `target` resolves and the certificate is issued. Omit `path` for a random one.", - "operationId": "addHostedDomain", + "x-category": "Management: visitors", + "x-title": "Erase an app install" + } + }, + "/api/v1/management/organizations/{organization_id}/projects/{project_id}/purge": { + "get": { + "operationId": "listProjectPurgePasses", "parameters": [ { + "description": "The organization", "in": "path", "name": "organization_id", "required": true, "schema": { "type": "string" } + }, + { + "description": "The project", + "in": "path", + "name": "project_id", + "required": true, + "schema": { + "type": "string" + } } ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "properties": { - "hostname": { - "description": "A subdomain of your site, such as k7.shop.example, that you will CNAME to target", - "type": "string" - }, - "path": { - "description": "Where the browser SDK posts on it. Omit it for a random one", - "type": "string" - } - }, - "type": "object" - } - } - }, - "required": true - }, "responses": { - "201": { + "200": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/HostedDomainOut" + "$ref": "#/components/schemas/ProjectPurgesOut" } } }, - "description": "Created" + "description": "OK" }, "401": { "content": { @@ -2207,7 +4162,7 @@ } } }, - "description": "Only an admin key may manage hosted domains" + "description": "Only an admin key may purge a project" }, "404": { "content": { @@ -2219,16 +4174,6 @@ }, "description": "No such resource in the key's organization" }, - "409": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - }, - "description": "The hostname is taken, or hosted domains are not available" - }, "422": { "content": { "application/json": { @@ -2237,7 +4182,7 @@ } } }, - "description": "The hostname or path is not usable" + "description": "The request could not be validated." }, "default": { "content": { @@ -2255,19 +4200,19 @@ "managementKey": [] } ], - "summary": "Add a hosted domain", + "summary": "List a project's purge passes", "tags": [ "Management API" ], - "x-category": "Management: hosted domains", - "x-title": "Add a hosted domain" - } - }, - "/api/v1/management/organizations/{organization_id}/hosted-domains/{hosted_domain_id}": { - "delete": { - "operationId": "removeHostedDomain", + "x-category": "Management: projects", + "x-title": "Get a project purge" + }, + "post": { + "description": "Owner or admin, or an admin management key. Archives the project if it is not archived yet - its keys are revoked at once, so no new data arrives - and deletes all of its data: its archived submissions, its stored identifications and rollups, its visitor identities, the webhook events that name it, its keys' attestation state and its Apple and Google platform credentials. There is no undo.\n\nIt runs twice: ten minutes after the request, and again a day after the first pass finished, for anything delivered late. Asking while a pass is pending returns it; asking after the purge finished queues another pass. Usage counts and the project's revoked keys are kept, because invoices and usage reports name them.\n\n`archive_copies_expire_by` is when the last archived copy written before per-project archiving expires.", + "operationId": "deleteAllOfProjectData", "parameters": [ { + "description": "The organization", "in": "path", "name": "organization_id", "required": true, @@ -2276,8 +4221,9 @@ } }, { + "description": "The project", "in": "path", - "name": "hosted_domain_id", + "name": "project_id", "required": true, "schema": { "type": "string" @@ -2285,8 +4231,15 @@ } ], "responses": { - "204": { - "description": "No Content" + "202": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectPurgeOut" + } + } + }, + "description": "Accepted" }, "401": { "content": { @@ -2306,7 +4259,7 @@ } } }, - "description": "Only an admin key may manage hosted domains" + "description": "Only an admin key may purge a project" }, "404": { "content": { @@ -2344,19 +4297,21 @@ "managementKey": [] } ], - "summary": "Remove a hosted domain", + "summary": "Delete all of a project's data", "tags": [ "Management API" ], - "x-category": "Management: hosted domains", - "x-title": "Remove a hosted domain" + "x-category": "Management: projects", + "x-title": "Purge a project" } }, - "/api/v1/management/organizations/{organization_id}/hosted-domains/{hosted_domain_id}/check": { - "post": { - "operationId": "checkHostedDomainNow", + "/api/v1/management/organizations/{organization_id}/projects/{project_id}/usage": { + "get": { + "description": "The same report for the keys of one project, for re-billing one client.", + "operationId": "readOneProjectMeteredTrafficPerDayAndPerKey", "parameters": [ { + "description": "The organization to report on", "in": "path", "name": "organization_id", "required": true, @@ -2365,10 +4320,35 @@ } }, { - "in": "path", - "name": "hosted_domain_id", - "required": true, + "description": "The project to report on", + "in": "query", + "name": "project_id", + "schema": { + "type": "string" + } + }, + { + "description": "First day, YYYY-MM-DD. Defaults to 30 days ago", + "in": "query", + "name": "from", + "schema": { + "type": "string" + } + }, + { + "description": "Last day, exclusive, YYYY-MM-DD. Defaults to tomorrow", + "in": "query", + "name": "to", + "schema": { + "type": "string" + } + }, + { + "description": "all, live or test", + "in": "query", + "name": "scope", "schema": { + "default": "all", "type": "string" } } @@ -2378,7 +4358,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/HostedDomainOut" + "$ref": "#/components/schemas/UsageOut" } } }, @@ -2402,7 +4382,7 @@ } } }, - "description": "Only an admin key may manage hosted domains" + "description": "Only an admin key may read usage" }, "404": { "content": { @@ -2412,7 +4392,7 @@ } } }, - "description": "No such resource in the key's organization" + "description": "No such project" }, "422": { "content": { @@ -2424,6 +4404,16 @@ }, "description": "The request could not be validated." }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "This deployment has no warehouse" + }, "default": { "content": { "application/json": { @@ -2440,12 +4430,12 @@ "managementKey": [] } ], - "summary": "Check a hosted domain now", + "summary": "Read one project's metered traffic, per day and per key", "tags": [ "Management API" ], - "x-category": "Management: hosted domains", - "x-title": "Check a hosted domain" + "x-category": "Management: usage", + "x-title": "Get project usage" } }, "/api/v1/management/organizations/{organization_id}/proxy-credentials": { @@ -2910,7 +4900,7 @@ } } }, - "description": "The management key's role does not allow this" + "description": "The management key's role does not allow this, or its organization is suspended or closed" }, "404": { "content": { @@ -3422,7 +5412,7 @@ } } }, - "description": "The management key's role does not allow this" + "description": "The management key's role does not allow this, or its organization is suspended or closed" }, "404": { "content": { @@ -3569,7 +5559,7 @@ } } }, - "description": "The management key's role does not allow this" + "description": "The management key's role does not allow this, or its organization is suspended or closed" }, "404": { "content": { @@ -3705,7 +5695,7 @@ } } }, - "description": "The management key's role does not allow this" + "description": "The management key's role does not allow this, or its organization is suspended or closed" }, "404": { "content": { @@ -3841,7 +5831,7 @@ } } }, - "description": "The management key's role does not allow this" + "description": "The management key's role does not allow this, or its organization is suspended or closed" }, "404": { "content": { @@ -3958,7 +5948,7 @@ } } }, - "description": "The management key's role does not allow this" + "description": "The management key's role does not allow this, or its organization is suspended or closed" }, "404": { "content": { @@ -4067,7 +6057,7 @@ } } }, - "description": "The management key's role does not allow this" + "description": "The management key's role does not allow this, or its organization is suspended or closed" }, "404": { "content": { @@ -4387,6 +6377,139 @@ "x-title": "Save key platform weights" } }, + "/api/v1/management/organizations/{organization_id}/usage": { + "get": { + "description": "The organization's usage, as the console's usage screen reads it: whole UTC days, half-open, `scope` all, live or test, with billed amounts and settled days.", + "operationId": "readMeteredTrafficPerDayAndPerKey", + "parameters": [ + { + "description": "The organization to report on", + "in": "path", + "name": "organization_id", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "The project to report on", + "in": "query", + "name": "project_id", + "schema": { + "type": "string" + } + }, + { + "description": "First day, YYYY-MM-DD. Defaults to 30 days ago", + "in": "query", + "name": "from", + "schema": { + "type": "string" + } + }, + { + "description": "Last day, exclusive, YYYY-MM-DD. Defaults to tomorrow", + "in": "query", + "name": "to", + "schema": { + "type": "string" + } + }, + { + "description": "all, live or test", + "in": "query", + "name": "scope", + "schema": { + "default": "all", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UsageOut" + } + } + }, + "description": "OK" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "No usable management key was presented" + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Only an admin key may read usage" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "No such resource in the key's organization" + }, + "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": "This deployment has no warehouse" + }, + "default": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "An unexpected error occurred." + } + }, + "security": [ + { + "managementKey": [] + } + ], + "summary": "Read metered traffic, per day and per key", + "tags": [ + "Management API" + ], + "x-category": "Management: usage", + "x-title": "Get usage" + } + }, "/api/v1/management/organizations/{organization_id}/visitor-erasures": { "get": { "description": "The last hundred erasures, newest first, each pending or done.", @@ -4642,7 +6765,7 @@ } } }, - "description": "The management key's role does not allow this" + "description": "The management key's role does not allow this, or its organization is suspended or closed" }, "404": { "content": { @@ -4730,7 +6853,7 @@ } } }, - "description": "The management key's role does not allow this" + "description": "The management key's role does not allow this, or its organization is suspended or closed" }, "404": { "content": { @@ -4844,7 +6967,7 @@ } } }, - "description": "The management key's role does not allow this" + "description": "The management key's role does not allow this, or its organization is suspended or closed" }, "404": { "content": { @@ -4933,7 +7056,7 @@ } } }, - "description": "The management key's role does not allow this" + "description": "The management key's role does not allow this, or its organization is suspended or closed" }, "404": { "content": { @@ -5073,7 +7196,7 @@ } } }, - "description": "The management key's role does not allow this" + "description": "The management key's role does not allow this, or its organization is suspended or closed" }, "404": { "content": { @@ -5177,7 +7300,7 @@ } } }, - "description": "The management key's role does not allow this" + "description": "The management key's role does not allow this, or its organization is suspended or closed" }, "404": { "content": { @@ -5293,7 +7416,7 @@ } } }, - "description": "The management key's role does not allow this" + "description": "The management key's role does not allow this, or its organization is suspended or closed" }, "404": { "content": { @@ -5389,7 +7512,7 @@ } } }, - "description": "The management key's role does not allow this" + "description": "The management key's role does not allow this, or its organization is suspended or closed" }, "404": { "content": { @@ -5468,7 +7591,7 @@ } } }, - "description": "The management key's role does not allow this" + "description": "The management key's role does not allow this, or its organization is suspended or closed" }, "404": { "content": { @@ -5529,7 +7652,10 @@ "Client API", "Server API", "Management: keys", + "Management: projects", + "Management: usage", "Management: hosted domains", + "Management: platform credentials", "Management: visitors", "Management: webhooks", "Management: risk weights" diff --git a/fingerly-server/src/main/java/io/fingerly/server/Event.java b/fingerly-server/src/main/java/io/fingerly/server/Event.java index 5911c9f..f9ca36b 100644 --- a/fingerly-server/src/main/java/io/fingerly/server/Event.java +++ b/fingerly-server/src/main/java/io/fingerly/server/Event.java @@ -47,8 +47,11 @@ public final class Event { private String tag; - @JsonProperty("ip_address") - private String ipAddress; + @JsonProperty("project_id") + private String projectId; + + @JsonProperty("ip_network") + private String ipNetwork; @JsonProperty("country_code") private String countryCode; @@ -91,9 +94,6 @@ public final class Event { private JsonNode document; - @JsonProperty("deferred_signals") - private JsonNode deferredSignals; - @JsonIgnore private transient JsonNode raw; private transient String rawJson; @@ -165,9 +165,21 @@ public String getTag() { return tag; } - /** The visitor's IP address. */ - public String getIpAddress() { - return ipAddress; + /** + * The Fingerly project the event belongs to, a UUID. Null when the server + * predates projects and did not send one. + */ + public String getProjectId() { + return projectId; + } + + /** + * The network the request came from: an IPv4 /24 or an IPv6 /40, such as + * {@code 203.0.113.0/24}. The API never returns the address itself. Null + * when absent. + */ + public String getIpNetwork() { + return ipNetwork; } /** ISO 3166-1 alpha-2 country of the address. */ @@ -254,8 +266,12 @@ public boolean hasDocument() { } /** - * The archived submission with the threshold and weights that scored it, - * when {@link #hasDocument()} is true and the archive could be read. + * An allow-listed view of the archived submission, when + * {@link #hasDocument()} is true and the archive could be read: schema, + * request id, time, SDK platform and version, IP network, IP + * classification (network, city-level location, detections), risk, + * attestation and velocity. It carries no raw signals, user agent or + * address. * *

Its contents are deliberately opaque, not a public contract. */ @@ -263,11 +279,6 @@ public JsonNode getDocument() { return document; } - /** The deferred report attached to this request, when one arrived. Also opaque. */ - public JsonNode getDeferredSignals() { - return deferredSignals; - } - /** * The response body exactly as it arrived, so a field the API adds after * this SDK was released is reachable without an upgrade. diff --git a/fingerly-server/src/test/java/io/fingerly/server/ContractTest.java b/fingerly-server/src/test/java/io/fingerly/server/ContractTest.java index 6766230..093518b 100644 --- a/fingerly-server/src/test/java/io/fingerly/server/ContractTest.java +++ b/fingerly-server/src/test/java/io/fingerly/server/ContractTest.java @@ -87,6 +87,9 @@ List readsEveryEventFixture() throws IOException { assertEquals(want.path("request_id").asText(), event.getRequestId()); assertEquals(want.path("visitor_id").asText(), event.getVisitorId()); assertNotNull(event.getOccurredAt(), "occurred_at did not decode"); + JsonNode project = want.path("project_id"); + assertEquals(project.isTextual() ? project.asText() : null, + event.getProjectId()); // A fixture without a score must not decode as zero. JsonNode score = want.path("suspect_score"); @@ -118,6 +121,9 @@ List readsEveryPageFixture() throws IOException { for (int i = 0; i < page.getRows().size(); i++) { assertEquals(want.path("rows").get(i).path("request_id").asText(), page.getRows().get(i).getRequestId()); + JsonNode project = want.path("rows").get(i).path("project_id"); + assertEquals(project.isTextual() ? project.asText() : null, + page.getRows().get(i).getProjectId()); } } })); @@ -165,6 +171,19 @@ List verifiesEveryWebhookFixture() throws IOException { return tests; } + @Test + void exposesTheWebhookProjectIdInData() throws IOException { + // Webhook data stays a tree; project_id is read from it like any other member. + JsonNode fixture = fixtures().path("webhooks").get(0); + WebhookEvent event = Webhooks.parse( + fixture.path("payload").asText().getBytes(StandardCharsets.UTF_8)); + JsonNode want = Json.MAPPER.readTree(fixture.path("payload").asText()) + .path("data").path("project_id"); + + assertTrue(want.isTextual(), "the webhook fixture carries no project_id"); + assertEquals(want.asText(), event.getData().path("project_id").asText()); + } + @Test void refusesAStaleWebhookFixture() throws IOException { JsonNode fixture = fixtures().path("webhooks").get(0); diff --git a/fingerly-server/src/test/java/io/fingerly/server/EventsServiceTest.java b/fingerly-server/src/test/java/io/fingerly/server/EventsServiceTest.java index 8ab8d6f..0325b83 100644 --- a/fingerly-server/src/test/java/io/fingerly/server/EventsServiceTest.java +++ b/fingerly-server/src/test/java/io/fingerly/server/EventsServiceTest.java @@ -4,6 +4,7 @@ import static io.fingerly.server.Fixtures.SECRET_KEY; import static org.junit.jupiter.api.Assertions.assertEquals; import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertNull; import static org.junit.jupiter.api.Assertions.assertSame; import static org.junit.jupiter.api.Assertions.assertThrows; import static org.junit.jupiter.api.Assertions.assertTrue; @@ -40,6 +41,27 @@ void decodesAnEventAndKeepsTheRawBody() throws IOException { } } + @Test + void decodesTheProjectId() throws IOException { + String extra = "\"project_id\":\"0199a963-e400-7000-8000-0000000000a1\","; + try (FakeApi api = FakeApi.json(200, Fixtures.event(extra))) { + Event event = client(api).events().get(REQUEST_ID); + + assertEquals("0199a963-e400-7000-8000-0000000000a1", event.getProjectId()); + } + } + + @Test + void decodesAnEventWithoutAProjectId() throws IOException { + // Servers older than projects do not send the field. + try (FakeApi api = FakeApi.json(200, Fixtures.event())) { + Event event = client(api).events().get(REQUEST_ID); + + assertEquals(REQUEST_ID, event.getRequestId()); + assertNull(event.getProjectId()); + } + } + @Test void decodesTriggers() throws IOException { String extra = "\"triggers\":[{\"signal\":\"tor\",\"weight\":14,\"confidence\":\"high\"}],"; diff --git a/fingerly-server/src/test/java/io/fingerly/server/Fixtures.java b/fingerly-server/src/test/java/io/fingerly/server/Fixtures.java index 53bc22a..3ff0518 100644 --- a/fingerly-server/src/test/java/io/fingerly/server/Fixtures.java +++ b/fingerly-server/src/test/java/io/fingerly/server/Fixtures.java @@ -31,7 +31,7 @@ static String event(String extra) { + "\"platform\":\"web\"," + "\"sdk_platform\":\"web\"," + "\"sdk_version\":\"0.1.0\"," - + "\"ip_address\":\"203.0.113.10\"," + + "\"ip_network\":\"203.0.113.0/24\"," + "\"triggers\":[]," + "\"has_document\":false" + "}";