diff --git a/CHANGELOG.md b/CHANGELOG.md
index 87f776b..f9aaec0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,31 @@
# Changelog
+## 0.3.0
+
+- Synced the vendored `v: 3` OpenAPI and fixture contract snapshot, added
+ `Event.getReason()` and `EventTrigger` v3 signal constants, and documented
+ empty `visitor_id` (`""`) on unidentifiable events.
+- Enforced the `proxy.md` sanitize-and-restore contract across `FingerlyProxy`
+ and all servlet/WebFlux adapters: validated `X-Fingerly-SDK-Platform`
+ restoration after stripping `x-fingerly-*`, HTTP `400 missing_origin` when
+ both `Origin` and a validated native platform header are absent (never
+ synthesizing `X-Fingerly-Origin`), forwarding `Sec-Fetch-*` and `Sec-CH-UA-*`
+ headers, and optional cross-origin CORS support.
+- `FingerlyProxy` requires a `fly_px_` proxy key and checks the caller's
+ public key on every request; a secret key is never sent upstream.
+- `fingerly.deviceCheck().query(requestId)` and
+ `fingerly.deviceCheck().write(requestId, DeviceCheckWrite)` (with
+ `queryAsync` and `writeAsync`) read and write an iOS event's DeviceCheck
+ bits. They retry the identical request only after a `503` or a transport
+ failure, and `FingerlyApiException` names each DeviceCheck error code and
+ `getAppleStatus()`.
+- Added `fingerly.events().verify(requestId, VerifyOptions)` (with
+ `verify(requestId)` and `verifyAsync`), which reads an event and checks it exists, is recent
+ (`maxAgeSeconds`, 300 by default), carries the expected `tag`, is
+ identifiable and scored, then consumes it once, and
+ `fingerly.events().consume(requestId)` (with `consumeAsync`), which throws
+ `EventAlreadyConsumedException` on `409 event_already_consumed`.
+
## 0.2.0
- `Event.getProjectId()` returns the Fingerly project an event belongs to, on
diff --git a/README.md b/README.md
index 872ceec..795bde6 100644
--- a/README.md
+++ b/README.md
@@ -35,12 +35,12 @@ Java 11 or newer, and Kotlin and Scala through the same artifacts. Releases are
io.fingerlyfingerly-server
- 0.2.0
+ 0.3.0
```
```kotlin
-implementation("io.fingerly:fingerly-server:0.2.0")
+implementation("io.fingerly:fingerly-server:0.3.0")
```
For the proxy, add the adapter for your stack as well (see [Artifacts](#artifacts)).
@@ -82,6 +82,7 @@ Full documentation: [docs.fingerly.io/docs/sdks/java](https://docs.fingerly.io/d
| Read an event, or verify a backend action | [Read events](#read-events), [Verify a backend action](#verify-a-backend-action) |
| Read without blocking a thread | [Blocking and non-blocking reads](#blocking-and-non-blocking-reads) |
| Handle errors and unscored events | [Errors](#errors), [Unscored events](#unscored-events) |
+| Allow one free trial per iOS device | [DeviceCheck bits on iOS](#devicecheck-bits-on-ios) |
| Check a webhook signature | [Verify webhooks](#verify-webhooks) |
| Keep identification working behind content blockers | [First-party proxy](#first-party-proxy) |
| Pick the adapter for Spring Boot, Tomcat, Jetty or WebFlux | [Artifacts](#artifacts), [Adapters](#adapters) |
@@ -96,6 +97,7 @@ Full documentation: [docs.fingerly.io/docs/sdks/java](https://docs.fingerly.io/d
- [Unscored events](#unscored-events)
- [Read an event you just identified](#read-an-event-you-just-identified)
- [Verify a backend action](#verify-a-backend-action)
+- [DeviceCheck bits on iOS](#devicecheck-bits-on-ios)
- [Verify webhooks](#verify-webhooks)
- [First-party proxy](#first-party-proxy)
- [Development and release preparation](#development-and-release-preparation)
@@ -119,7 +121,7 @@ The servlet APIs and Spring are `provided`: the container supplies them, so noth
## Read events
-Event reads require `fly_sk_{production|staging|development}_…` keys. Requests go to `https://api.fingerly.io`; `endpoint()` overrides that for a local API. Public, proxy, management, malformed and unsupported keys are rejected before network access, 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`.
+Event reads require `fly_sk_{production|staging|development}_…` keys. Requests go to `https://api.fingerly.io`; `endpoint()` overrides that. It takes `https://host` with an optional port and nothing else: a path, query, fragment, credentials, whitespace or control byte is refused by `build()`. A plain `http` endpoint is refused too, except for a local API with `allowInsecureLoopback(true)` and a host of `127.0.0.1`, `localhost` or `[::1]`. Public, proxy, management, malformed and unsupported keys are rejected 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.
@@ -137,7 +139,7 @@ Mono event = Mono.fromFuture(() -> fingerly.events().getAsync(requestId))
An answer larger than 4 MiB is refused rather than buffered: the client throws `FingerlyException`, the proxy answers 502. A gzip or deflate answer is decoded.
-Every client and proxy in a process shares one HTTP/1.1 connection pool, so building one per request still reuses connections. The pool is replaced every two minutes so DNS changes are picked up; a request in flight finishes on the connection it started on. Before JDK 21 a replaced pool cannot be closed and keeps its idle connections until the JDK's keep-alive timeout (20 minutes by default), so there it is replaced every 20 minutes instead. There is no cookie jar. Pass `httpClient()` to use your own client instead; configure it with `HttpClient.Redirect.NEVER`.
+Every client and proxy in a process shares one HTTP/1.1 connection pool, so building one per request still reuses connections. The pool is replaced every two minutes so DNS changes are picked up; a request in flight finishes on the connection it started on. Before JDK 21 a replaced pool cannot be closed and keeps its idle connections until the JDK's keep-alive timeout (20 minutes by default), so there it is replaced every 20 minutes instead. There is no cookie jar. Pass `httpClient()` to use your own client instead; it must be built with `HttpClient.Redirect.NEVER` (the JDK default). `FingerlyProxy` refuses any other redirect policy when it is built, since every upstream call carries the proxy key.
## Errors
@@ -204,11 +206,87 @@ try {
Retry a pending read a bounded number of times, for example from a scheduled job; never sleep on an event loop. `isEventNotFound()` means a request id that was never issued, or one past retention, and is never pending.
-The archived document arrives moments after the event itself, so check `hasDocument()` rather than assuming it is there.
+The archived document arrives moments after the event itself, so check `hasDocument()` rather than assuming it is there, and read `getDocument()` for the allow-listed archived `JsonNode` (`risk`, `attestation`, `ip_network` and `velocity`, with no raw signals, user agent or address). When a submission is unidentifiable (`identifiable == false`, such as insufficient entropy, a genuine embedded WebView, or an unmatched high-risk Web payload), `getVisitorId()` is `""`; there are no `deferred_token`, `deferred_signals` or `supplements` fields in `v: 3`.
+
+`EventTrigger.V3_SIGNALS` groups the `v: 3` anti-spoofing and integrity signal constants on `EventTrigger`: `SIGNAL_ATTESTATION_FAILED` (`"attestation_failed"`), `SIGNAL_ATTESTATION_DOWNGRADE` (`"attestation_downgrade"`), `SIGNAL_DEVICE_INCONSISTENT` (`"device_inconsistent"`), `SIGNAL_REPORT_INCOMPLETE` (`"report_incomplete"`), `SIGNAL_PROBE_ERRORS` (`"probe_errors"`), `SIGNAL_FETCH_METADATA_MISSING` (`"fetch_metadata_missing"`), `SIGNAL_WEB_TICKET_MISSING` (`"web_ticket_missing"`), `SIGNAL_WEB_TICKET_INVALID` (`"web_ticket_invalid"`), `SIGNAL_TAMPERING` (`"tampering"`), `SIGNAL_CUSTOM_ROOT_CA` (`"custom_root_ca"`) and `SIGNAL_SECONDARY_USER_PROFILE` (`"secondary_user_profile"`).
## 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. A pending event (`isPending()`) is not a verdict: retry after `getRetryAfter()` seconds or 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.
+Send the request id from the browser or app to your backend and verify it there with a server-only key. `fingerly.events().verify(requestId, options)` reads the event and checks, in this order, stopping at the first that fails:
+
+1. `not_found`: no event has this request id (never issued, or past retention).
+2. `too_old`: the event is older than `maxAgeSeconds` (300 by default). A missing or unreadable `occurred_at` counts as too old.
+3. `tag_mismatch`: a `tag` was set and the event's tag is not exactly it. An untagged event never matches.
+4. `unidentifiable`: the event's `getVisitorId()` is `""`.
+5. `unscored`: the event was not scored.
+6. `already_consumed`: every check passed, but another call consumed the event first.
+
+It consumes the event last, only when every other check passes, so one event backs one decision: a second verify of the same request id answers `already_consumed`. `VerifyOptions.builder().consume(false)` skips the consume. `getReason()` is one of the `VerifyResult.REASON_` constants, `""` when `isOk()`, and `getEvent()` is the event read (null only for `not_found`).
+
+`verify` never looks at the suspect score, level or triggers: that policy stays with you, applied after `isOk()`.
+
+```java
+import io.fingerly.server.VerifyOptions;
+import io.fingerly.server.VerifyResult;
+
+VerifyResult result;
+try {
+ result = fingerly.events().verify(requestId,
+ VerifyOptions.builder().tag("checkout").maxAgeSeconds(120).build());
+} catch (FingerlyApiException e) {
+ if (e.isPending()) return "retry"; // not decided yet: read again after e.getRetryAfter() seconds
+ throw e;
+}
+if (!result.isOk()) {
+ return "refuse"; // result.getReason() says which check failed
+}
+Event event = result.getEvent();
+if ("high".equals(event.getSuspectLevel())
+ || event.getTriggers().stream()
+ .anyMatch(t -> EventTrigger.SIGNAL_ATTESTATION_FAILED.equals(t.getSignal()))) {
+ return "refuse";
+}
+```
+
+`verify(requestId)` uses the defaults, and `verifyAsync` returns a `CompletableFuture` for non-blocking code. Invalid options (a `maxAgeSeconds` that is not positive, or an empty `tag`) throw `IllegalArgumentException` at `build()`, before any request. Any other error, `event_pending` included, is thrown as from `get`. A pending event (`isPending()`) is not a verdict: retry after `getRetryAfter()` seconds or verify asynchronously, rather than refusing the action.
+
+To consume an event yourself, call `fingerly.events().consume(requestId)` (or `consumeAsync`). The first call returns a `ConsumeResult` with `getConsumedAt()` and `isFirst()`; every later one throws `EventAlreadyConsumedException`, a `FingerlyApiException` with status `409`, code `event_already_consumed` and `getConsumedAt()`. Consumes are never 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. Never put a personal identifier (user ID, email, install ID or advertising ID) in a tag: the server keeps tags in long-lived rollups.
+
+## DeviceCheck bits on iOS
+
+For an iOS identification whose App Attest evidence carried an Apple DeviceCheck token, Fingerly holds the token for one hour, and your backend can spend it once to read or to write the device's two bits. The bits survive a reinstall, and they mean what you decide.
+
+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 bits say the device already had one, refuse it.
+2. Otherwise grant the trial and record the grant in your own data, then write the bit on the device's next identification. Until the write lands, your own record is what stops a second trial.
+
+```java
+import io.fingerly.server.DeviceCheckBits;
+import io.fingerly.server.DeviceCheckWrite;
+import io.fingerly.server.FingerlyApiException;
+
+// On the identification that asks for the trial.
+try {
+ DeviceCheckBits bits = fingerly.deviceCheck().query(requestId);
+ if (bits.isFound() && bits.getBit0()) {
+ return "offer-paid-plan";
+ }
+} catch (FingerlyApiException e) {
+ if (!e.isDeviceCheckNotHeld() && !e.isDeviceCheckSpent()) throw e;
+ // No token for this event: decide without the bits.
+}
+trials.grant(accountId, event.getVisitorId());
+
+// On the next identification from the same install.
+fingerly.deviceCheck().write(nextRequestId, DeviceCheckWrite.builder().bit0(true).build());
+```
+
+`queryAsync` and `writeAsync` return a `CompletableFuture` for non-blocking code. A write names `bit0`, `bit1` or both; `DeviceCheckWrite.builder().build()` with neither throws `IllegalArgumentException`.
+
+The SDK retries a call, with the identical request, only after a `503` or a transport failure, up to twice. The API keeps the token after such an answer only for a retry of the same request: the other operation, or a write with other bits, answers `409 device_check_spent`. Errors arrive as `FingerlyApiException`: `isDeviceCheckNotHeld()` (`404`), `isDeviceCheckSpent()`, `isDeviceCheckBusy()`, `isCredentialUnavailable()` (`409`), `isBitsRequired()`, `isAppleRejected()` (`422`, with Apple's status in `getAppleStatus()`) and `isDeviceCheckUnavailable()` (`503`). Never rely on the bits as the only fraud check, and give customers a way to have them reset.
## Verify webhooks
@@ -238,7 +316,9 @@ FingerlyProxy proxy = FingerlyProxy.builder()
`clientIp` must return exactly one IPv4 or IPv6 address. Anything else (null, empty, a list, a port, a host name) is a configuration error: the request is refused with a 500 saying "The client IP callback returned no valid address", nothing is sent upstream, and the mistake is logged once.
-`path` is optional where the framework already routes only that path to the proxy, and required by the WebFlux adapter, which sees every request.
+Set `path` in every setup, as the examples below do. The servlet filters accept a proxy without one where the container maps only that path to the filter, but then the container decides what reaches it, including paths it normalises, such as a trailing slash or a dot segment. With `path` set, the proxy compares the raw path itself and answers near misses with its own uncacheable `404`, or passes them to the application. The WebFlux adapter, which sees every request, requires it.
+
+`upstream(...)` changes the API origin. It takes `https://host` with an optional port and nothing else: a path, query, fragment, credentials, whitespace or control byte is refused when the proxy is built. A plain `http` upstream is refused too, except for local development with `allowInsecureLoopback(true)` and a host of `127.0.0.1`, `localhost` or `[::1]`.
Then point the browser SDK at the same path:
@@ -338,25 +418,30 @@ Build a `ProxyRequest` (method, raw path, headers, body, `remoteAddress`) and wr
### What the proxy does
-The browser SDK posts both of its calls to that one path, and the proxy forwards every `POST` it answers to Fingerly's one ingest URL, `https://api.fingerly.io/api/v1/ingest` (`apiVersion` changes only the version in it). Any other method gets `405`. Event reads need a secret key and stay unreachable from a browser by construction.
+Browser and proxied native client SDKs post a single `v: 3` identification envelope to that one path, and the proxy forwards every `POST` it answers with its raw request body bytes untouched to Fingerly's one ingest URL, `https://api.fingerly.io/api/v1/ingest` (`apiVersion` changes only the version in it). Any method other than `POST` (plus `OPTIONS` when `allowedOrigins(...)` is configured) gets `405`, with `Cache-Control: no-store`. Methods are compared exactly, so `post` gets `405` too. Event reads need a secret key and stay unreachable from a browser by construction.
-With `path` set, the proxy answers exactly that path, compared with the whole raw request path including any context path, case-sensitively. A trailing or doubled slash, a dot segment, percent encoding or a path parameter makes a different path: it gets `404`, or passes through to the application under a filter, as does anything under the path. Without `path`, it answers whatever the framework routed to it. `path` must be a plain absolute path such as `/k7x2qm4a`.
+With `path` set, the proxy answers exactly that path, compared with the whole raw request path including any context path, case-sensitively. A trailing or doubled slash, a dot segment, percent encoding or a path parameter makes a different path: it gets `404`, or passes through to the application under a filter, as does anything under the path (including retired `/supplement` subpaths). Without `path`, it answers whatever the framework routed to it. `path` must be a plain absolute path such as `/k7x2qm4a`.
| Situation | Answer |
| --- | --- |
| Path other than the configured one | `404`, or passed through to the application under a filter |
-| Method other than `POST` | `405` |
-| Public key from a different environment than the proxy key | `401` |
+| Method other than `POST` (or `OPTIONS` when `allowedOrigins(...)` is configured) | `405` |
+| Missing `X-Api-Key`, a secret key, or a public key from a different environment than the proxy key | `401` |
+| Neither an `Origin` nor a validated `X-Fingerly-SDK-Platform` | `400` (`missing_origin`) |
| Body over 1 MiB (enforced while reading rather than after buffering) | `413` |
| Upstream did not answer within `timeout()` (5 seconds by default) | `504` ("Gateway timeout") |
-| Anything else: refused, reset, truncated, larger than 4 MiB, or compressed in a way that cannot be decoded | `502` ("Bad gateway") |
+| Anything else: refused, reset, truncated, larger than 4 MiB, compressed in a way that cannot be decoded, a redirect (never followed), or a status outside 200 to 599 | `502` ("Bad gateway") |
| `clientIp` returns no valid address | `500` ("The client IP callback returned no valid address") |
-The browser must present a public key from the same environment as the proxy key, or the request gets `401`. Only the content type, the visitor metadata Fingerly needs, and an `Idempotency-Key` are forwarded; customer cookies and authorization headers never are, and a visitor header that could not be forwarded is dropped. The proxy reports itself upstream as `java/0.2.0`, which the dashboard shows per proxy.
+The proxy key (`fly_px_{production|staging|development}_…`) is required: `build()` throws `IllegalArgumentException` when it is missing or malformed. On every request the caller's `X-Api-Key` must be a public key (`fly_pk_…`) from the same environment as the proxy key. Anything else, a missing header, another environment's key or a secret `fly_sk_` key, gets a plain-text `401` with `Cache-Control: no-store`, and nothing is forwarded. Upstream receives the proxy key as `X-Fingerly-Proxy-Key` and the caller's public key as `X-Api-Key`; a secret key is never sent.
+
+Incoming headers follow the sanitize-and-restore sequence: all incoming `X-Fingerly-*`, `Cookie` and `Authorization` headers are stripped, restoring `X-Fingerly-SDK-Platform` only if 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`). When both `Origin` and a validated `X-Fingerly-SDK-Platform` are absent, the request is rejected locally with `400` (`missing_origin`), and `X-Fingerly-Origin` is never synthesized from `Host`, `Referer` or the request URL. A request carries one channel upstream: with an `Origin`, the proxy sends `X-Fingerly-Origin` and drops the platform header, as the API does on a direct call; without one, it sends the validated `X-Fingerly-SDK-Platform`.
+
+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 never are, and a visitor header that could not be forwarded is dropped. The proxy reports itself upstream as `java/0.3.0`, which the dashboard shows per proxy.
Only `Content-Type`, `X-Request-Id`, `RateLimit-Limit`, `RateLimit-Remaining` and `Retry-After` are relayed back, plus `Cache-Control: no-store`, so nothing on the response names Fingerly. The answer is read whole before anything is relayed, so a truncated one is never passed on as a success.
-One line is logged per failure, without a stack trace or a key, to the `System.Logger` named `io.fingerly.server.FingerlyProxy` at `WARNING` (which reaches SLF4J, Logback or Log4j through their usual bridges), or to your own `log(...)` callback.
+Every refusal and failure answer carries `Cache-Control: no-store`. One line is logged per failure, naming only the kind of failure, never the upstream address, a stack trace or a key, to the `System.Logger` named `io.fingerly.server.FingerlyProxy` at `WARNING` (which reaches SLF4J, Logback or Log4j through their usual bridges), or to your own `log(...)` callback.
Every adapter asks `proxy.handles(path)` before reading anything. A filter may be mapped more broadly than the one path the proxy owns, and calling `handle()` to find out would have consumed a request body the application still needs.
@@ -374,7 +459,7 @@ The vendored synthetic contract snapshot makes tests independent of sibling repo
Source structure
-`FingerlyClient` holds the options; `EventsService` owns the reads and the list filters, and `Event`, `EventPage` and `EventListParams` are what they speak in. `Webhooks` verifies signatures. `FingerlyProxy` holds every proxy decision, with `ProxyRequest` and `ProxyResponse` as the neutral shapes the adapters translate to. `SharedHttp` is the process-wide connection pool, `BoundedBody` reads every answer within its limit, and `Deadlines` is the one timer thread behind every deadline. `Keys` validates every caller-supplied option before any network access, and `Json` keeps the Jackson configuration in one place so a caller's own `ObjectMapper` cannot change how responses are read.
+`FingerlyClient` holds the options; `EventsService` owns the reads and the list filters, and `Event`, `EventPage` and `EventListParams` are what they speak in. It also verifies and consumes events, with `VerifyOptions`, `VerifyResult`, `ConsumeResult` and `EventAlreadyConsumedException`. `DeviceCheckService` spends an event's DeviceCheck token, with `DeviceCheckBits`, `DeviceCheckWrite` and `DeviceCheckWriteResult`. `Webhooks` verifies signatures. `FingerlyProxy` holds every proxy decision, with `ProxyRequest` and `ProxyResponse` as the neutral shapes the adapters translate to. `SharedHttp` is the process-wide connection pool, `BoundedBody` reads every answer within its limit, and `Deadlines` is the one timer thread behind every deadline. `Keys` validates every caller-supplied option before any network access, and `Json` keeps the Jackson configuration in one place so a caller's own `ObjectMapper` cannot change how responses are read.
diff --git a/contract/manifest.json b/contract/manifest.json
index 7303153..f5d8ba0 100644
--- a/contract/manifest.json
+++ b/contract/manifest.json
@@ -1,8 +1,8 @@
{
"schema": 1,
- "serverCommit": "e22f96777b0d029464baa4e127d7a346b684d478",
+ "serverCommit": "2f24510cfb9a41f780936841cc47ca8a1c012201",
"files": {
- "openapi.json": "850e7627dbbf1789fe7a0a214ae28838f2cd80d42e251f9994f5cb42d72e6009",
+ "openapi.json": "87c3881291f8a9cba673f2a62a3bad85f6ff7f8195c01efcae54f84f6887bd93",
"fixtures.json": "3fbf2efbcf3c8ebced3d2c9f2a3c1f5752ee94ece63d5c110291d9a8251ff68f"
}
}
diff --git a/contract/openapi.json b/contract/openapi.json
index e1483dd..487d545 100644
--- a/contract/openapi.json
+++ b/contract/openapi.json
@@ -1,6 +1,80 @@
{
"components": {
"schemas": {
+ "AttestEnvelope": {
+ "properties": {
+ "assertion": {
+ "description": "Base64 CBOR App Attest assertion object",
+ "type": "string"
+ },
+ "attestation_object": {
+ "description": "Base64 CBOR App Attest attestation object",
+ "type": "string"
+ },
+ "certificate_chain": {
+ "description": "Base64 DER X.509 certificate chain for Android key registration",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "challenge": {
+ "description": "Stateless server-signed challenge ticket",
+ "type": "string"
+ },
+ "device_token": {
+ "description": "Optional standard Base64 Apple DeviceCheck token, at most 4 KiB decoded, bound into statementDigest. Held for one hour and spent by POST /events/{request_id}/device-check/query",
+ "type": "string"
+ },
+ "device_token_write": {
+ "description": "Optional second standard Base64 Apple DeviceCheck token, at most 4 KiB decoded, bound into statementDigest. Held for one hour and spent by PUT /events/{request_id}/device-check",
+ "type": "string"
+ },
+ "install_id": {
+ "description": "Canonical 36-char lowercase UUIDv4 matching sources.identity.value.install_id",
+ "type": "string"
+ },
+ "key_id": {
+ "description": "Base64 App Attest key ID (iOS) or 64-char hex SPKI SHA-256 (Android)",
+ "type": "string"
+ },
+ "mode": {
+ "description": "app_attest_register, app_attest_assert, android_key_register, or android_key_assert",
+ "type": "string"
+ },
+ "play_integrity_token": {
+ "description": "Optional Google Play Integrity token with requestHash equal to hex(statementDigest)",
+ "type": "string"
+ },
+ "prev_assertion": {
+ "description": "iOS, app_attest_register only: standard Base64 CBOR App Attest assertion by the previous confirmed key (prev_key_id) with clientDataHash equal to statementDigest",
+ "type": "string"
+ },
+ "prev_key_id": {
+ "description": "Optional key ID of the previous confirmed key: 64-char hex (Android) or standard Base64 App Attest key ID (iOS, app_attest_register only)",
+ "type": "string"
+ },
+ "prev_signature": {
+ "description": "Optional Base64 ASN.1 DER signature by retiring Android key over identical framedPreimage",
+ "type": "string"
+ },
+ "reattest_attempt": {
+ "description": "Inline Android lease renewal attempt counter (0 or 1)",
+ "format": "int64",
+ "type": "integer"
+ },
+ "signature": {
+ "description": "Base64 ASN.1 DER SHA256withECDSA signature over framedPreimage",
+ "type": "string"
+ }
+ },
+ "required": [
+ "challenge",
+ "install_id",
+ "mode"
+ ],
+ "type": "object"
+ },
"AttestationChallengeOut": {
"properties": {
"app_attest": {
@@ -15,6 +89,10 @@
"description": "Whether to send a DeviceCheck token with the App Attest evidence",
"type": "boolean"
},
+ "digest_salt": {
+ "description": "The project's 32-byte name digest salt, unpadded base64url. The SDK caches it per SDK key and sends each name digest as the first 16 bytes of HMAC-SHA256(salt, name) in hex, with digest_salt_id. Absent when the server has none to give; the SDK then uses 32 zero bytes",
+ "type": "string"
+ },
"expires_at": {
"description": "When the nonce becomes unusable",
"format": "date-time",
@@ -436,10 +514,29 @@
},
"IdentifyIn": {
"properties": {
+ "attest": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/AttestEnvelope"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Hardware attestation envelope bound to raw signals bytes (v3 native SDKs)"
+ },
+ "attest_skipped": {
+ "description": "Native only, and only without attest: why the SDK sent no attestation. One of not_offered, unsupported, challenge_unavailable, key_error, timeout, backoff, install_unavailable. Diagnostic; it never lowers the score",
+ "type": "string"
+ },
"consent": {
"description": "The SDK's consent state; must be granted, or the request is refused with consent_required",
"type": "string"
},
+ "op": {
+ "description": "Empty for a report. ticket asks for a web freshness ticket instead: a public key on the web only, with a body of v, op and sdk, answered 200 with ticket and expires_at, never charged",
+ "type": "string"
+ },
"sdk": {
"$ref": "#/components/schemas/SDKInfo",
"description": "Which SDK collected these signals"
@@ -450,30 +547,65 @@
"type": "object"
},
"tag": {
- "description": "An opaque value echoed back on the event and kept in long-lived rollups. A label for your own systems, such as a client or app name; never a personal identifier (user ID, email, install ID or advertising ID)",
+ "description": "An opaque value echoed back on the event and kept in long-lived rollups. A label for your own systems, such as a client or app name; never a personal identifier (user ID, email, install ID or advertising ID). A value holding a control character (U+0000 to U+001F, U+007F) is refused with invalid_request",
"type": "string"
+ },
+ "ticket": {
+ "description": "Web only: the freshness ticket from a ticket request or the previous answer's next_ticket. Single use, bound to the key and page origin, valid for 300 seconds. A native report carrying one is refused with invalid_request",
+ "type": "string"
+ },
+ "ticket_pow": {
+ "description": "Web only, next to a ticket whose answer carried pow_bits: the smallest decimal nonce n, from 0 up, such that SHA-256(ticket || ':' || n) starts with at least pow_bits zero bits",
+ "type": "string"
+ },
+ "v": {
+ "description": "Wire envelope version. Must equal 3.",
+ "format": "int64",
+ "type": "integer"
}
},
"type": "object"
},
"IdentifyOut": {
"properties": {
- "app_attest_key": {
- "description": "unknown when the report asserted with an App Attest key the server does not hold; the iOS SDK then attests a new key on its next collection. Absent otherwise",
+ "attest_key_id": {
+ "description": "Native only, present whenever attest was sent: the key_id the server evaluated, copied from attest.key_id",
"type": "string"
},
- "deferred_token": {
- "description": "Short-lived capability for the deferred signal report",
+ "attest_key_status": {
+ "description": "Native only, present whenever attest was sent: registered (the key was verified, stored and owns the install), valid (an assertion verified against a stored key), rekey_required (the key is unknown or expired), rejected (attestation failed)",
"type": "string"
},
"duplicate": {
- "description": "This submission was answered before; the verdict belongs to the first one",
+ "description": "This submission was answered before; the verdict replays the first one",
"type": "boolean"
},
"identifiable": {
"description": "False when the report carried too little to identify anyone",
"type": "boolean"
},
+ "next_attestation": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/AttestationChallengeOut"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Fresh attestation challenge ticket and dynamic offer flags for the next native submission"
+ },
+ "next_ticket": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/WebTicketOut"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Web only: a fresh freshness ticket for the next report from this page, so it needs no ticket request"
+ },
"reason": {
"description": "Why enrichment did not happen. Only answered to a secret key; a browser or app reads it on the server-side event read",
"type": "string"
@@ -511,7 +643,7 @@
"type": "integer"
},
"visitor_id": {
- "description": "Who this visitor is, stable across their visits",
+ "description": "Who this visitor is, stable across their visits; empty when unidentifiable",
"type": "string"
},
"visitor_is_new": {
@@ -556,10 +688,29 @@
},
"IngestIn": {
"properties": {
+ "attest": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/AttestEnvelope"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Hardware attestation envelope bound to raw signals bytes (v3 native SDKs)"
+ },
+ "attest_skipped": {
+ "description": "Native only, and only without attest: why the SDK sent no attestation. One of not_offered, unsupported, challenge_unavailable, key_error, timeout, backoff, install_unavailable. Diagnostic; it never lowers the score",
+ "type": "string"
+ },
"consent": {
"description": "The SDK's consent state; must be granted, or the request is refused with consent_required",
"type": "string"
},
+ "op": {
+ "description": "Empty for a report. ticket asks for a web freshness ticket instead: a public key on the web only, with a body of v, op and sdk, answered 200 with ticket and expires_at, never charged",
+ "type": "string"
+ },
"sdk": {
"$ref": "#/components/schemas/SDKInfo",
"description": "Which SDK collected these signals"
@@ -570,12 +721,21 @@
"type": "object"
},
"tag": {
- "description": "An opaque value echoed back on the event and kept in long-lived rollups; never a personal identifier. Identify only",
+ "description": "An opaque value echoed back on the event and kept in long-lived rollups; never a personal identifier. A value holding a control character (U+0000 to U+001F, U+007F) is refused with invalid_request",
"type": "string"
},
- "token": {
- "description": "The deferred_token returned by identify. Present only on a deferred report",
+ "ticket": {
+ "description": "Web only: the freshness ticket from a ticket request or the previous answer's next_ticket. A native report carrying one is refused with invalid_request",
"type": "string"
+ },
+ "ticket_pow": {
+ "description": "Web only: the proof of work for a ticket whose answer carried pow_bits",
+ "type": "string"
+ },
+ "v": {
+ "description": "Wire envelope version. Must equal 3.",
+ "format": "int64",
+ "type": "integer"
}
},
"type": "object"
@@ -636,6 +796,41 @@
],
"type": "object"
},
+ "PrivateAccessTokenIssuerIn": {
+ "properties": {
+ "directory_url": {
+ "description": "Instead of token_key: the issuer's HTTPS directory, read for its current type 2 keys",
+ "type": "string"
+ },
+ "issuer_name": {
+ "description": "The issuer's server name, host and optional port. Defaults to the directory URL's host",
+ "type": "string"
+ },
+ "token_key": {
+ "description": "The issuer's token type 2 key, base64url: a DER SubjectPublicKeyInfo of a 2048-bit RSASSA-PSS key with SHA-384",
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "PrivateAccessTokenIssuerOut": {
+ "properties": {
+ "directory_url": {
+ "type": "string"
+ },
+ "issuer_name": {
+ "type": "string"
+ },
+ "token_key": {
+ "description": "base64url, padded",
+ "type": "string"
+ }
+ },
+ "required": [
+ "issuer_name"
+ ],
+ "type": "object"
+ },
"ProjectArchivedOut": {
"properties": {
"archived": {
@@ -948,6 +1143,29 @@
],
"type": "object"
},
+ "SDKEventConsumeOut": {
+ "properties": {
+ "consumed_at": {
+ "description": "When it was consumed, RFC 3339",
+ "format": "date-time",
+ "type": "string"
+ },
+ "first": {
+ "description": "Always true: a later consume is answered 409 event_already_consumed",
+ "type": "boolean"
+ },
+ "request_id": {
+ "description": "The event consumed",
+ "type": "string"
+ }
+ },
+ "required": [
+ "consumed_at",
+ "first",
+ "request_id"
+ ],
+ "type": "object"
+ },
"SDKEventOut": {
"properties": {
"agent": {
@@ -965,6 +1183,14 @@
"asn_name": {
"type": "string"
},
+ "consumed_at": {
+ "description": "When the event was first consumed with POST /events/{request_id}/consume. Absent while it has not been",
+ "format": "date-time",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
"country_code": {
"type": "string"
},
@@ -1183,6 +1409,21 @@
"description": "The human-readable stem, such as fly_pk_production",
"type": "string"
},
+ "private_access_token_issuer": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/PrivateAccessTokenIssuerOut"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Prototype: the project's token issuer, on the answer to an origins update"
+ },
+ "private_access_tokens": {
+ "description": "Prototype: whether a capable Safari is asked for a Private Access Token when the page requests a web ticket",
+ "type": "boolean"
+ },
"project_id": {
"type": "string"
},
@@ -1203,6 +1444,11 @@
"status": {
"description": "active or revoked",
"type": "string"
+ },
+ "web_ticket_pow_bits": {
+ "description": "Proof of work, in leading zero bits, the key's web freshness tickets ask for; 0 is none",
+ "format": "int64",
+ "type": "integer"
}
},
"required": [
@@ -1218,9 +1464,11 @@
"last4",
"name",
"prefix",
+ "private_access_tokens",
"project_id",
"require_attestation",
- "status"
+ "status",
+ "web_ticket_pow_bits"
],
"type": "object"
},
@@ -1341,21 +1589,6 @@
],
"type": "object"
},
- "SupplementOut": {
- "properties": {
- "duplicate": {
- "description": "The identical supplement was accepted before",
- "type": "boolean"
- },
- "request_id": {
- "type": "string"
- }
- },
- "required": [
- "request_id"
- ],
- "type": "object"
- },
"UsageDayOut": {
"properties": {
"billable": {
@@ -1571,6 +1804,29 @@
],
"type": "object"
},
+ "WebTicketOut": {
+ "properties": {
+ "expires_at": {
+ "description": "When the ticket stops being accepted, RFC 3339 UTC",
+ "format": "date-time",
+ "type": "string"
+ },
+ "pow_bits": {
+ "description": "Present when the key asks for proof of work: the leading zero bits ticket_pow must produce",
+ "format": "int64",
+ "type": "integer"
+ },
+ "ticket": {
+ "description": "Unpadded base64url ticket, sent as ticket on the next report",
+ "type": "string"
+ }
+ },
+ "required": [
+ "expires_at",
+ "ticket"
+ ],
+ "type": "object"
+ },
"WebhookDeliveriesOut": {
"properties": {
"deliveries": {
@@ -2075,10 +2331,10 @@
"x-title": "Get an event"
}
},
- "/api/v1/events/{request_id}/device-check": {
- "put": {
- "description": "Spends the DeviceCheck token held for this iOS event, once, to set bit0, bit1 or both with Apple, using your project's own Apple key. A bit left out keeps its value. The bits mean what you decide; Fingerly never reads them. Tokens are held for one hour, only for events whose App Attest evidence covered them, and only when DeviceCheck is switched on for the project's Apple credential.",
- "operationId": "setDeviceDevicecheckBits",
+ "/api/v1/events/{request_id}/consume": {
+ "post": {
+ "description": "Marks one identification event as consumed, atomically and once per organization, so a request ID handed from a page to your backend backs one decision only. The first call answers `200` with `first: true`; every later call answers `409 event_already_consumed`, with the first consume's time in the error's `details` entry for the field `consumed_at`. Read and check the event before you consume it. The flag is kept with the event and erased with it.",
+ "operationId": "markEventConsumedOnce",
"parameters": [
{
"in": "path",
@@ -2089,38 +2345,12 @@
}
}
],
- "requestBody": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "bit0": {
- "description": "The value to set for the first bit. Leave out to keep it",
- "type": [
- "boolean",
- "null"
- ]
- },
- "bit1": {
- "description": "The value to set for the second bit. Leave out to keep it",
- "type": [
- "boolean",
- "null"
- ]
- }
- },
- "type": "object"
- }
- }
- },
- "required": true
- },
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
- "$ref": "#/components/schemas/DeviceCheckWriteOut"
+ "$ref": "#/components/schemas/SDKEventConsumeOut"
}
}
},
@@ -2154,7 +2384,7 @@
}
}
},
- "description": "`device_check_not_held`: no token is held for that event"
+ "description": "`event_not_found`: no event with that request ID in this key's environment, or it is older than 30 days. `event_pending`: the identification is still being recorded; retry after the `Retry-After` seconds"
},
"409": {
"content": {
@@ -2164,7 +2394,7 @@
}
}
},
- "description": "`device_check_spent`, `device_check_busy` or `credential_unavailable`"
+ "description": "`event_already_consumed`: consumed before; `details[0]` is `{\"field\": \"consumed_at\", \"issue\": \"\"}`"
},
"422": {
"content": {
@@ -2174,7 +2404,7 @@
}
}
},
- "description": "`bits_required` or `apple_rejected`"
+ "description": "The request could not be validated."
},
"503": {
"content": {
@@ -2184,7 +2414,7 @@
}
}
},
- "description": "`device_check_unavailable`: retry within the hour"
+ "description": "`events_unavailable`: retry after the `Retry-After` seconds"
},
"default": {
"content": {
@@ -2202,18 +2432,18 @@
"secretKey": []
}
],
- "summary": "Set the device's DeviceCheck bits",
+ "summary": "Mark an event consumed, once",
"tags": [
"Server API"
],
"x-category": "Server API",
- "x-title": "Write an event's DeviceCheck bits"
+ "x-title": "Consume an event"
}
},
- "/api/v1/events/{request_id}/device-check/query": {
- "post": {
- "description": "Spends the DeviceCheck token held for this iOS event, once, to read the device's two bits from Apple. A token spent on a read cannot also write; to mark a device, write instead.",
- "operationId": "readDeviceDevicecheckBits",
+ "/api/v1/events/{request_id}/device-check": {
+ "put": {
+ "description": "Spends the write DeviceCheck token held for this iOS event, once, to set bit0, bit1 or both with Apple, using your project's own Apple key. A bit left out keeps its value. The bits mean what you decide; Fingerly never reads them. Apple answers a write with no previous value; the event's read token, spent by the query route, is separate, so one identification supports one read and one write. Tokens are held for one hour, only for events whose App Attest evidence covered them, and only when DeviceCheck is switched on for the project's Apple credential. After a `503`, retry with the same bits: a token kept for a retry accepts only the request it was first used for.",
+ "operationId": "setDeviceDevicecheckBits",
"parameters": [
{
"in": "path",
@@ -2224,12 +2454,38 @@
}
}
],
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "bit0": {
+ "description": "The value to set for the first bit. Leave out to keep it",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "bit1": {
+ "description": "The value to set for the second bit. Leave out to keep it",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+ }
+ }
+ },
+ "required": true
+ },
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
- "$ref": "#/components/schemas/DeviceCheckQueryOut"
+ "$ref": "#/components/schemas/DeviceCheckWriteOut"
}
}
},
@@ -2263,7 +2519,7 @@
}
}
},
- "description": "`device_check_not_held`: no token is held for that event"
+ "description": "`device_check_not_held`: no write token is held for that event"
},
"409": {
"content": {
@@ -2273,7 +2529,7 @@
}
}
},
- "description": "`device_check_spent`, `device_check_busy` or `credential_unavailable`"
+ "description": "`device_check_spent`: already used, or a retry that is not the first request; `device_check_busy` or `credential_unavailable`"
},
"422": {
"content": {
@@ -2283,7 +2539,7 @@
}
}
},
- "description": "The request could not be validated."
+ "description": "`bits_required` or `apple_rejected`"
},
"503": {
"content": {
@@ -2311,18 +2567,18 @@
"secretKey": []
}
],
- "summary": "Read the device's DeviceCheck bits",
+ "summary": "Set the device's DeviceCheck bits",
"tags": [
"Server API"
],
"x-category": "Server API",
- "x-title": "Read an event's DeviceCheck bits"
+ "x-title": "Write an event's DeviceCheck bits"
}
},
- "/api/v1/events/{request_id}/supplement": {
+ "/api/v1/events/{request_id}/device-check/query": {
"post": {
- "description": "Attaches the signals a browser collects after its initial budget to an identification that has already been answered. It never changes the visitor, the score, billing or webhooks. The JavaScript SDK sends it automatically. Resending the same report is answered as a duplicate.",
- "operationId": "submitDeferredReport",
+ "description": "Spends the read DeviceCheck token held for this iOS event, once, to read the device's two bits from Apple. Apple asks for each token to be used once, so the event holds a second token for the write route: to read and then mark a device, read and write on the same identification. After a `503`, retry the read: a token kept for a retry accepts only the request it was first used for.",
+ "operationId": "readDeviceDevicecheckBits",
"parameters": [
{
"in": "path",
@@ -2333,45 +2589,16 @@
}
}
],
- "requestBody": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "consent": {
- "description": "The SDK's consent state; must be granted, or the request is refused with consent_required",
- "type": "string"
- },
- "sdk": {
- "$ref": "#/components/schemas/SDKInfo",
- "description": "Which SDK collected these signals"
- },
- "signals": {
- "additionalProperties": {},
- "description": "A report containing only the deferred tier",
- "type": "object"
- },
- "token": {
- "description": "The deferred_token returned by identify",
- "type": "string"
- }
- },
- "type": "object"
- }
- }
- },
- "required": true
- },
"responses": {
- "202": {
+ "200": {
"content": {
"application/json": {
"schema": {
- "$ref": "#/components/schemas/SupplementOut"
+ "$ref": "#/components/schemas/DeviceCheckQueryOut"
}
}
},
- "description": "Accepted"
+ "description": "OK"
},
"401": {
"content": {
@@ -2381,9 +2608,9 @@
}
}
},
- "description": "No usable x-api-key header was presented"
+ "description": "No usable secret SDK key was presented"
},
- "402": {
+ "403": {
"content": {
"application/json": {
"schema": {
@@ -2391,7 +2618,17 @@
}
}
},
- "description": "The organization this key belongs to is not accepting traffic"
+ "description": "The organization is suspended or closed"
+ },
+ "404": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ },
+ "description": "`device_check_not_held`: no read token is held for that event"
},
"409": {
"content": {
@@ -2401,7 +2638,7 @@
}
}
},
- "description": "A different deferred report was already accepted for this request"
+ "description": "`device_check_spent`: already used, or a retry that is not the first request; `device_check_busy` or `credential_unavailable`"
},
"422": {
"content": {
@@ -2411,7 +2648,7 @@
}
}
},
- "description": "The request could not be validated."
+ "description": "`apple_rejected`: Apple rejected the token; `apple_status` says how"
},
"503": {
"content": {
@@ -2421,7 +2658,7 @@
}
}
},
- "description": "The report could not be accepted just now"
+ "description": "`device_check_unavailable`: retry within the hour"
},
"default": {
"content": {
@@ -2436,15 +2673,15 @@
},
"security": [
{
- "publicKey": []
+ "secretKey": []
}
],
- "summary": "Submit a deferred report",
+ "summary": "Read the device's DeviceCheck bits",
"tags": [
- "Client API"
+ "Server API"
],
- "x-category": "Client API",
- "x-title": "Submit a deferred report"
+ "x-category": "Server API",
+ "x-title": "Read an event's DeviceCheck bits"
}
},
"/api/v1/identify": {
@@ -2492,6 +2729,16 @@
},
"description": "The organization this key belongs to is not accepting traffic"
},
+ "409": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ },
+ "description": "The Idempotency-Key was reused with a different payload, or the original request is still in progress"
+ },
"413": {
"content": {
"application/json": {
@@ -2561,7 +2808,7 @@
},
"/api/v1/ingest": {
"post": {
- "description": "The one URL the client SDKs and every first-party proxy post to. A body with a `token` is a deferred report and is answered `202` with `request_id` and `duplicate`, exactly as the deferred report route answers. Any other body is an identification and is answered `200` exactly as the identify route answers.\n\nIt exists so a proxy can forward everything it receives to a single path, and so the SDK can post both calls to one path of the customer's choosing, with nothing appended that a content blocker could match across sites.\n\nThe `X-Request-Id` response header names this HTTP exchange, for support and logs. It is not the `request_id` in the body, which names the identification and is what `GET /events/{request_id}` reads.",
+ "description": "The one URL the client SDKs and every first-party proxy post to. Forwards the single-pass v3 identification envelope and answers `200` with the verdict, exactly as the identify route answers.\n\nIt exists so a proxy can forward everything it receives to a single path of the customer's choosing, with nothing appended that a content blocker could match across sites. An `Idempotency-Key` header is required on every call.\n\nThe `X-Request-Id` response header names this HTTP exchange, for support and logs. It is not the `request_id` in the body, which names the identification and is what `GET /events/{request_id}` reads.",
"operationId": "submitFromClientSdk",
"requestBody": {
"content": {
@@ -2584,7 +2831,7 @@
},
"description": "OK"
},
- "202": {
+ "401": {
"content": {
"application/json": {
"schema": {
@@ -2592,9 +2839,9 @@
}
}
},
- "description": "The deferred report was accepted"
+ "description": "No usable x-api-key header was presented"
},
- "401": {
+ "402": {
"content": {
"application/json": {
"schema": {
@@ -2602,9 +2849,9 @@
}
}
},
- "description": "No usable x-api-key header was presented"
+ "description": "The organization this key belongs to is not accepting traffic"
},
- "402": {
+ "409": {
"content": {
"application/json": {
"schema": {
@@ -2612,7 +2859,7 @@
}
}
},
- "description": "The organization this key belongs to is not accepting traffic"
+ "description": "The Idempotency-Key was reused with a different payload, or the original request is still in progress"
},
"413": {
"content": {
@@ -5333,7 +5580,7 @@
"type": "array"
},
"allowed_android_signers": {
- "description": "SHA-256 signing certificate digests, 64 hex characters",
+ "description": "SHA-256 signing certificate digests, 64 hex characters (colon separators accepted). Required alongside allowed_android_packages in production or when require_attestation is true",
"items": {
"type": "string"
},
@@ -5365,8 +5612,11 @@
]
},
"hide_client_score": {
- "description": "Withhold suspect_score and suspect_level from a browser, an app, a proxy and a hosted domain. Defaults to false",
- "type": "boolean"
+ "description": "Withhold suspect_score and suspect_level from a browser, an app, a proxy and a hosted domain. Defaults to true for a public key and false for a secret key",
+ "type": [
+ "boolean",
+ "null"
+ ]
},
"kind": {
"description": "public or secret",
@@ -5375,6 +5625,13 @@
"name": {
"description": "What the key is called. The only part a person can recognise once the secret is masked",
"type": "string"
+ },
+ "require_attestation": {
+ "description": "Refuse native reports whose hardware attestation did not verify",
+ "type": [
+ "boolean",
+ "null"
+ ]
}
},
"type": "object"
@@ -5503,7 +5760,7 @@
"type": "array"
},
"allowed_android_signers": {
- "description": "SHA-256 signing certificate digests, 64 hex characters. Empty means not configured",
+ "description": "SHA-256 signing certificate digests, 64 hex characters (colon separators accepted). Required alongside allowed_android_packages in production or when require_attestation is true",
"items": {
"type": "string"
},
@@ -5794,6 +6051,32 @@
"type": "string"
},
"type": "array"
+ },
+ "private_access_token_issuer": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/PrivateAccessTokenIssuerIn"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Prototype: the token issuer of the key's whole project. Leave out to keep it; send an empty object to clear it"
+ },
+ "private_access_tokens": {
+ "description": "Prototype: ask Safari on iOS 16+ and macOS 13+ for a Private Access Token when the page requests a web ticket. Needs a public key in a project that names a token issuer. Leave out to keep the current setting",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "web_ticket_pow_bits": {
+ "description": "Proof of work the key's web freshness tickets ask for, 0 (off) to 22 leading zero bits. Leave out to keep the current setting",
+ "format": "int64",
+ "type": [
+ "integer",
+ "null"
+ ]
}
},
"type": "object"
diff --git a/fingerly-server-jakarta/src/main/java/io/fingerly/server/jakarta/FingerlyProxyFilter.java b/fingerly-server-jakarta/src/main/java/io/fingerly/server/jakarta/FingerlyProxyFilter.java
index f0b11ba..173ddf6 100644
--- a/fingerly-server-jakarta/src/main/java/io/fingerly/server/jakarta/FingerlyProxyFilter.java
+++ b/fingerly-server-jakarta/src/main/java/io/fingerly/server/jakarta/FingerlyProxyFilter.java
@@ -20,7 +20,7 @@
import java.util.concurrent.CompletableFuture;
/**
- * Serves the browser SDK's same-origin requests under Jakarta Servlet.
+ * Serves Fingerly Web and native client SDK first-party requests under Jakarta Servlet.
*
*
For Spring Boot 3, Tomcat 10 and newer, Jetty 11 and newer, and anything
* else on {@code jakarta.servlet}. Spring Boot 2 and older containers want
@@ -142,8 +142,11 @@ private static ProxyRequest toProxyRequest(HttpServletRequest http) throws IOExc
.contentLength(http.getContentLengthLong())
.remoteAddress(http.getRemoteAddr());
- for (String name : Collections.list(http.getHeaderNames())) {
- builder.headers(name, Collections.list(http.getHeaders(name)));
+ java.util.Enumeration headerNames = http.getHeaderNames();
+ if (headerNames != null) {
+ for (String name : Collections.list(headerNames)) {
+ builder.headers(name, Collections.list(http.getHeaders(name)));
+ }
}
return builder.build();
}
@@ -158,7 +161,10 @@ private static void write(HttpServletResponse out, ProxyResponse result) throws
for (Map.Entry header : result.headers()) {
out.addHeader(header.getKey(), header.getValue());
}
- out.setContentLength(result.contentLength());
- out.getOutputStream().write(result.body());
+ int status = result.status();
+ if (status != 204 && status != 205 && status != 304) {
+ out.setContentLength(result.contentLength());
+ out.getOutputStream().write(result.body());
+ }
}
}
diff --git a/fingerly-server-jakarta/src/test/java/io/fingerly/server/jakarta/FingerlyProxyFilterTest.java b/fingerly-server-jakarta/src/test/java/io/fingerly/server/jakarta/FingerlyProxyFilterTest.java
index 955d46c..a951989 100644
--- a/fingerly-server-jakarta/src/test/java/io/fingerly/server/jakarta/FingerlyProxyFilterTest.java
+++ b/fingerly-server-jakarta/src/test/java/io/fingerly/server/jakarta/FingerlyProxyFilterTest.java
@@ -170,13 +170,14 @@ private static FingerlyProxy proxy(String upstream) {
return FingerlyProxy.builder()
.proxyKey(PROXY_KEY)
.path(PATH)
+ .allowInsecureLoopback(true)
.upstream(upstream)
.clientIp(request -> request.header("CF-Connecting-IP"))
.build();
}
@ParameterizedTest
- @ValueSource(strings = {"/orders", "/k7x2qm4a/admin"})
+ @ValueSource(strings = {"/orders", "/k7x2qm4a/admin", "/k7x2qm4a/supplement"})
void passesOtherPathsAlongWithTheBodyIntact(String path) throws Exception {
byte[] body = "{\"order\":1}".getBytes(StandardCharsets.UTF_8);
HttpServletRequest request =
@@ -216,6 +217,22 @@ void refusesAWrongMethodOnAnOwnedPathItself() throws Exception {
assertEquals(List.of("POST"), written.headers.get("Allow"));
}
+ @ParameterizedTest
+ @ValueSource(strings = {"post", "Post", "PUT"})
+ void refusesAMethodThatIsNotExactlyPostUncacheable(String method) throws Exception {
+ HttpServletRequest request = request(method, PATH, Map.of(), new byte[0]);
+ Written written = new Written();
+ List