Skip to content

Release 0.3.0 - #4

Merged
hasan-muzak merged 17 commits into
mainfrom
feat/v3-anti-spoofing-hardening
Nov 17, 2026
Merged

hasan-muzak merged 17 commits into
mainfrom
feat/v3-anti-spoofing-hardening

Conversation

@hasan-muzak

Copy link
Copy Markdown
Contributor

Releases 0.3.0 on merge (release.yml publishes when the manifest version is new).

Main changes, from the CHANGELOG:

  • Verify a backend action: read an event, check it exists, is recent (300 s by default), carries the expected tag, is identifiable and scored, then consume it once. Consume is also callable on its own and reports an already-consumed event as a typed error.
  • DeviceCheck: read and write the two DeviceCheck bits of the device behind an iOS event, retrying a 503 or a transport failure with the identical request.
  • v3 contract: refreshed OpenAPI and contract fixtures, event reason, identifiable, parsed event document with attestation (attest_skipped, downgrade), and the v3 signal constants.
  • Proxy: single-path relay contract with sanitize-and-restore of the SDK platform header, 400 missing_origin, one channel header upstream, forwarded Sec-Fetch-* and Sec-CH-UA-* headers, optional allowed origins, verbatim raw-byte forwarding, upstream redirects and out-of-range statuses answered with 502.
  • The proxy takes only a proxy key, checks the caller's public key and never sends a secret key upstream.
  • The endpoint option takes a bare https origin; plain http only for loopback with the explicit opt-in.
  • README merged with the redesigned layout from main and updated for 0.3.0.

With an Origin the proxy sends X-Fingerly-Origin only and drops the
platform header, which the API refuses alongside it. A plain HTTP
upstream is refused unless allowInsecureLoopback(true) is set and the
host is 127.0.0.1, localhost or [::1].

Refs: fingerly-io/sdks#20
Every upstream call carries the proxy key, so build() now refuses a
supplied HttpClient whose redirect policy is not Redirect.NEVER. A 3xx
answer from the upstream is answered 502 and never relayed.

Refs: fingerly-io/sdks#46
A status below 200 or above 599 is not an answer a browser, CDN or
monitor understands, so the proxy now answers 502 with
Cache-Control: no-store instead of relaying it.

Refs: fingerly-io/sdks#48
POST and OPTIONS are now compared case-sensitively, so a lowercase post
gets 405 as in the other SDKs. Tests cover no-store on 404 and 405 in the
core and every adapter, and the README asks for path(...) in every setup.

Refs: fingerly-io/sdks#49
The upstream option now takes scheme, host and an optional port only. A
path, query, fragment, whitespace or control byte is refused, and the
stored origin is rebuilt from the parsed parts. A test pins that failure
lines name neither the upstream address nor the key.

Refs: fingerly-io/sdks#50
The client endpoint now follows the proxy upstream rule: a bare https
origin rebuilt from its parsed parts, and plain HTTP only for a loopback
host with allowInsecureLoopback(true), so the secret key never travels
in the clear or to an unintended path.

Refs: fingerly-io/sdks#50
Add attestation_downgrade, probe_errors and fetch_metadata_missing
constants and include them in the v3 signal set. Cover them in the
contract test and list them in the README.

Refs: fingerly-io/server#19
Refs: fingerly-io/server#14
Refresh the vendored OpenAPI snapshot from the server export.
It adds attest_skipped, attest_key_id, the attest_key_status values
and the iOS prev_assertion continuity proof.
The proxy builder has no secretKey option and build() requires a proxy
key, so the server secret key never travels upstream. Every request must
present a public key of the proxy key's environment or gets a 401.

Refs: fingerly-io/sdks#43
fingerly.deviceCheck() queries and writes an iOS event's DeviceCheck bits,
retrying the identical request only after a 503 or a transport failure.
FingerlyApiException names each DeviceCheck error and Apple's status.
fingerly.events().verify() reads an event and checks, in order, that it exists, is no older than maxAgeSeconds (300 by default), carries the expected tag, is identifiable and scored, then consumes it once, answering a VerifyResult with the first failing reason. fingerly.events().consume() posts the consume and throws EventAlreadyConsumedException, with getConsumedAt(), on 409 event_already_consumed in either body shape.

Refs: fingerly-io/panels#13
Refresh the vendored OpenAPI snapshot and its manifest from server
0f20954: the web ticket request and next_ticket, the consume route,
consumed_at on the event read, and the DeviceCheck write token.
Refresh the vendored OpenAPI snapshot and its manifest from server
2f24510: the prototype's per-key switch and the project's token issuer
on the origins update.
@hasan-muzak
hasan-muzak merged commit 2a9f9cd into main Nov 17, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant