Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,20 @@
# Changelog

## 0.4.0

- Named constants for every closed string set the API sends: `Signal` (every
signal group and detector), `SuspectLevel`, `Confidence`, `EventState`,
`Environment`, `Platform`, `AnonymityNetwork`, `DeviceKind`, `VisitorKind`,
`AttestationState`, `AttestationStatus`, `AttestSkippedReason`,
`VerifyReason`, `WebhookEventType` and `WebhookEnvironment`. They are
`String` constants, so they work in `switch`, and the accessors stay
strings, so a value the server adds later still reads.
`EventTrigger.SIGNAL_` and `VerifyResult.REASON_` are the same strings.
- `Signal` matches the server's signal list, including `repeated_reinstall`,
`device_activity_high` and `device_activity_very_high`.
- `Event.getAnonymityNetwork()` documents `relay`, which the server already
sends.

## 0.3.0

- Synced the vendored `v: 3` OpenAPI and fixture contract snapshot, added
Expand Down
53 changes: 45 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,12 +35,12 @@ Java 11 or newer, and Kotlin and Scala through the same artifacts. Releases are
<dependency>
<groupId>io.fingerly</groupId>
<artifactId>fingerly-server</artifactId>
<version>0.3.0</version>
<version>0.4.0</version>
</dependency>
```

```kotlin
implementation("io.fingerly:fingerly-server:0.3.0")
implementation("io.fingerly:fingerly-server:0.4.0")
```

For the proxy, add the adapter for your stack as well (see [Artifacts](#artifacts)).
Expand All @@ -52,14 +52,15 @@ import io.fingerly.server.Event;
import io.fingerly.server.EventListParams;
import io.fingerly.server.EventPage;
import io.fingerly.server.FingerlyClient;
import io.fingerly.server.SuspectLevel;

FingerlyClient fingerly = FingerlyClient.builder()
.secretKey(System.getenv("FINGERLY_SECRET_KEY"))
.build();

Event event = fingerly.events().get(requestId);
EventPage page = fingerly.events().list(
EventListParams.builder().level("high").limit(50).build());
EventListParams.builder().level(SuspectLevel.HIGH).limit(50).build());
```

**4. Verify a webhook.**
Expand Down Expand Up @@ -96,6 +97,7 @@ Full documentation: [docs.fingerly.io/docs/sdks/java](https://docs.fingerly.io/d
- [Errors](#errors)
- [Unscored events](#unscored-events)
- [Read an event you just identified](#read-an-event-you-just-identified)
- [Named values](#named-values)
- [Verify a backend action](#verify-a-backend-action)
- [DeviceCheck bits on iOS](#devicecheck-bits-on-ios)
- [Verify webhooks](#verify-webhooks)
Expand Down Expand Up @@ -208,7 +210,27 @@ Retry a pending read a bounded number of times, for example from a scheduled job

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"`).
## Named values

The string fields with a fixed set of values have a class of constants each, holding the exact strings the API sends. The accessors stay plain strings, so a value the server adds after this SDK was released still reads normally: compare with `equals` or `switch`, and keep a default branch.

| Constants | Values of |
| --- | --- |
| `Signal` | `EventTrigger.getSignal()` (signal groups, such as `Signal.VPN`) and the archived document's `risk.triggers[].signal` (detectors, such as `Signal.VPN_PUBLIC`) |
| `SuspectLevel` | `Event.getSuspectLevel()` and `EventListParams.Builder.level()` |
| `Confidence` | `EventTrigger.getConfidence()` |
| `EventState`, `Environment`, `Platform` | `Event.getState()`, `getEnvironment()`, `getPlatform()` |
| `AnonymityNetwork`, `DeviceKind`, `VisitorKind` | `Event.getAnonymityNetwork()`, `getDeviceKind()`, `getVisitorKind()` |
| `AttestationState`, `AttestationStatus`, `AttestSkippedReason` | the archived document's `attestation.state`, `attestation.status` and `attestation.attest_skipped` |
| `VerifyReason` | `VerifyResult.getReason()` |
| `WebhookEventType`, `WebhookEnvironment` | `WebhookEvent.getType()`, `getEnvironment()` |

```java
boolean suppressed = event.getTriggers().stream()
.anyMatch(t -> Signal.FINGERPRINT_SUPPRESSED.equals(t.getSignal()));
```

`EventTrigger.V3_SIGNALS` groups the `v: 3` anti-spoofing and integrity signals: `Signal.ATTESTATION_FAILED`, `ATTESTATION_DOWNGRADE`, `DEVICE_INCONSISTENT`, `REPORT_INCOMPLETE`, `PROBE_ERRORS`, `FETCH_METADATA_MISSING`, `WEB_TICKET_MISSING`, `WEB_TICKET_INVALID`, `TAMPERING`, `CUSTOM_ROOT_CA` and `SECONDARY_USER_PROFILE`. The `EventTrigger.SIGNAL_` constants are the same strings.

## Verify a backend action

Expand All @@ -221,11 +243,13 @@ Send the request id from the browser or app to your backend and verify it there
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`).
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 `VerifyReason` constants (`VerifyReason.OK`, `""`, 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.Signal;
import io.fingerly.server.SuspectLevel;
import io.fingerly.server.VerifyOptions;
import io.fingerly.server.VerifyResult;

Expand All @@ -241,9 +265,9 @@ if (!result.isOk()) {
return "refuse"; // result.getReason() says which check failed
}
Event event = result.getEvent();
if ("high".equals(event.getSuspectLevel())
if (SuspectLevel.HIGH.equals(event.getSuspectLevel())
|| event.getTriggers().stream()
.anyMatch(t -> EventTrigger.SIGNAL_ATTESTATION_FAILED.equals(t.getSignal()))) {
.anyMatch(t -> Signal.ATTESTATION_FAILED.equals(t.getSignal()))) {
return "refuse";
}
```
Expand Down Expand Up @@ -296,6 +320,19 @@ Verify the exact raw bytes before parsing them. Signatures cover the timestamp a

`WebhookEvent.getData()` stays a `JsonNode`, so a new event type needs no SDK 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")`.

```java
switch (event.getType()) {
case WebhookEventType.VISITOR_SUSPECT:
review(event.getData().path("request_id").asText());
break;
case WebhookEventType.IDENTIFICATION_COMPLETED:
record(event.getData());
break;
default:
break; // a type added later: acknowledge it and move on
}
```

## First-party proxy

Content blockers refuse browser requests to third-party APIs, and a refused identification is a visitor never identified. Create a proxy in the dashboard (**Integration > Proxy keys**) and mount it at the path it issued, such as `/k7x2qm4a`, and those requests become first-party. The proxy key is what lets that hop declare the visitor's real address, origin and user agent; a public key alone never can, so nobody can spoof them.
Expand Down Expand Up @@ -437,7 +474,7 @@ The proxy key (`fly_px_{production|staging|development}_…`) is required: `buil

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.
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.4.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.

Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
package io.fingerly.server;

/**
* The {@link Event#getAnonymityNetwork()} values, as the exact strings the API
* sends. The accessor is null on an ordinary connection.
*/
public final class AnonymityNetwork {

private AnonymityNetwork() {}

/** A Tor exit node. */
public static final String TOR = "tor";

/** A privacy relay such as Apple's Private Relay. */
public static final String RELAY = "relay";

/** A reported VPN endpoint. */
public static final String VPN = "vpn";

/** A proxy. */
public static final String PROXY = "proxy";

/** A hosting or datacenter network. */
public static final String HOSTING = "hosting";
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
package io.fingerly.server;

/**
* Why a native SDK sent no attestation, as the exact strings of
* {@code attestation.attest_skipped} in {@link Event#getDocument()}.
* The app reports it about itself; it is diagnostic only and never changes
* the score.
*/
public final class AttestSkippedReason {

private AttestSkippedReason() {}

/** Attestation was not offered. */
public static final String NOT_OFFERED = "not_offered";

/** Attestation is not supported on the device. */
public static final String UNSUPPORTED = "unsupported";

/** No attestation challenge was available. */
public static final String CHALLENGE_UNAVAILABLE = "challenge_unavailable";

/** The attestation key failed. */
public static final String KEY_ERROR = "key_error";

/** Attestation timed out. */
public static final String TIMEOUT = "timeout";

/** The SDK was backing off from attestation. */
public static final String BACKOFF = "backoff";

/** The install ID was unavailable. */
public static final String INSTALL_UNAVAILABLE = "install_unavailable";
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
package io.fingerly.server;

/**
* The server's verdict on a native event's hardware evidence, as the exact
* strings of {@code attestation.state} in {@link Event#getDocument()}.
*
* <pre>{@code
* String state = event.getDocument().path("attestation").path("state").asText();
* if (AttestationState.FAILED.equals(state)) {
* return "refuse";
* }
* }</pre>
*/
public final class AttestationState {

private AttestationState() {}

/** The hardware evidence verified. */
public static final String ATTESTED = "attested";

/** No evidence that could be proven was offered. */
public static final String NOT_ATTESTED = "not_attested";

/** The evidence failed verification. */
public static final String FAILED = "failed";
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
package io.fingerly.server;

/**
* The detail behind {@link AttestationState}, as the exact strings of
* {@code attestation.status} in {@link Event#getDocument()}.
*/
public final class AttestationStatus {

private AttestationStatus() {}

/** The evidence verified. */
public static final String VERIFIED = "verified";

/** The evidence could not be checked either way. */
public static final String INDETERMINATE = "indeterminate";

/** The evidence was rejected. */
public static final String INVALID = "invalid";

/** The report carried no evidence. */
public static final String ABSENT = "absent";

/** The key has nothing configured to verify the evidence against. */
public static final String UNCONFIGURED = "unconfigured";
}
16 changes: 16 additions & 0 deletions fingerly-server/src/main/java/io/fingerly/server/Confidence.java
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
package io.fingerly.server;

/** The {@link EventTrigger#getConfidence()} values, as the exact strings the API sends. */
public final class Confidence {

private Confidence() {}

/** Low confidence. */
public static final String LOW = "low";

/** Medium confidence. */
public static final String MEDIUM = "medium";

/** High confidence. */
public static final String HIGH = "high";
}
19 changes: 19 additions & 0 deletions fingerly-server/src/main/java/io/fingerly/server/DeviceKind.java
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
package io.fingerly.server;

/** The {@link Event#getDeviceKind()} values, as the exact strings the API sends. */
public final class DeviceKind {

private DeviceKind() {}

/** A desktop or laptop. */
public static final String DESKTOP = "desktop";

/** A phone. */
public static final String MOBILE = "mobile";

/** A tablet. */
public static final String TABLET = "tablet";

/** A client with no device at all. */
public static final String SERVER = "server";
}
16 changes: 16 additions & 0 deletions fingerly-server/src/main/java/io/fingerly/server/Environment.java
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
package io.fingerly.server;

/** The {@link Event#getEnvironment()} values, as the exact strings the API sends. */
public final class Environment {

private Environment() {}

/** Production. */
public static final String PRODUCTION = "production";

/** Staging. */
public static final String STAGING = "staging";

/** Development. */
public static final String DEVELOPMENT = "development";
}
20 changes: 11 additions & 9 deletions fingerly-server/src/main/java/io/fingerly/server/Event.java
Original file line number Diff line number Diff line change
Expand Up @@ -124,7 +124,7 @@ public Instant getOccurredAt() {
return occurredAt;
}

/** {@code enriched}, or {@code unavailable} when the lookup could not run. */
/** {@code enriched}, or {@code unavailable} when the lookup could not run. See {@link EventState}. */
public String getState() {
return state;
}
Expand All @@ -134,12 +134,12 @@ public String getReason() {
return reason;
}

/** {@code production}, {@code staging} or {@code development}. */
/** {@code production}, {@code staging} or {@code development}. See {@link Environment}. */
public String getEnvironment() {
return environment;
}

/** The scoring profile applied: {@code web}, {@code android} or {@code ios}. */
/** The scoring profile applied: {@code web}, {@code android} or {@code ios}. See {@link Platform}. */
public String getPlatform() {
return platform;
}
Expand Down Expand Up @@ -212,8 +212,9 @@ public String getAsnName() {
}

/**
* {@code tor}, {@code vpn}, {@code proxy} or {@code hosting}. Null on an
* ordinary connection, which is most of them.
* {@code tor}, {@code relay}, {@code vpn}, {@code proxy} or {@code hosting}
* (see {@link AnonymityNetwork}). Null on an ordinary connection, which is
* most of them.
*/
public String getAnonymityNetwork() {
return anonymityNetwork;
Expand All @@ -234,12 +235,12 @@ public String getOs() {
return os;
}

/** {@code desktop}, {@code mobile}, {@code tablet} or {@code server}. */
/** {@code desktop}, {@code mobile}, {@code tablet} or {@code server}. See {@link DeviceKind}. */
public String getDeviceKind() {
return deviceKind;
}

/** {@code human}, {@code ai_bot}, {@code automation} or {@code search_crawler}. */
/** {@code human}, {@code ai_bot}, {@code automation} or {@code search_crawler}. See {@link VisitorKind}. */
public String getVisitorKind() {
return visitorKind;
}
Expand All @@ -259,7 +260,7 @@ public boolean isScored() {
return suspectScore != null;
}

/** {@code low}, {@code medium} or {@code high}. Null when not scored. */
/** {@code low}, {@code medium} or {@code high} (see {@link SuspectLevel}). Null when not scored. */
public String getSuspectLevel() {
return suspectLevel;
}
Expand All @@ -280,7 +281,8 @@ public boolean hasDocument() {
* 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.
* address. {@link AttestationState} and {@link AttestationStatus} name the
* values of {@code attestation.state} and {@code attestation.status}.
*
* <p>Its contents are deliberately opaque, not a public contract.
*/
Expand Down
Loading
Loading