Download the PHP package mohemian/flink-sdk-php without Composer

flink-sdk-php

Verify FLINK's signed assertions in a Laravel backend. An embedded FLINK journey hands your page the applicant's eID data (from ID Austria, for example) together with a copy signed by FLINK. This package verifies that signed copy, so your backend can check that the names and birthdate in a submitted form are the ones the eID returned. The same verifier checks FLINK's other signed assertions, such as a session's results.

Using Statamic? Follow docs/statamic.md end to end.

Install

PHP 8.2+ (8.3+ for Laravel 13), Laravel 10 to 13, ext-intl.

Verify a prefill

On the page, launch the journey with this session's reference and post prefillJwt from onResult to your backend (see the browser SDK docs):

On the backend:

Or as a validation rule, which keeps the verified prefill for you:

Flink::prefill() throws a FlinkException unless every one of these holds:

• signed by FLINK: RS256 only, key chosen by kid from FLINK's JWKS (cached a day, refetched at most once a minute for an unknown kid), header typ = flow-prefill+jwt; otherwise InvalidSignature, or InvalidAssertion for another typ
• iss = FLINK_URL, aud = your page's origin, not expired, ver = 1 (iat and exp allow 5 seconds of clock skew)
• tenant_id is yours and journey is one of FLINK_JOURNEYS: any FLINK tenant can register your origin, so aud alone is not enough
• method is one you accept (prefill.allowed_methods, default ['eid']). eid is any eID provider route (ID Austria, SkIDentity or SK Authentigate); the claim does not say which one
• reference is this session's (or the one you pass as the second argument), so a JWT copied from someone else's browser fails

Everything but the signature is an InvalidAssertion. Two failures are deliberately not a FlinkException, because a broken setup should fail loudly rather than refuse every applicant quietly: MissingConfiguration for an unset variable, and KeysUnavailable when FLINK's keys cannot be fetched (a wrong FLINK_URL, or an outage).

A journey with no identity step (email only, say) issues a JWT without method, and the prefill is refused. That is deliberate: nothing in such a JWT is identity-backed, the email address included, so it cannot stand in for a verified identity.

changed() returns the verified fields the submission changed or left out, as dotted keys; pass only: to compare a subset. It compares strings after trimming and Unicode NFC normalisation, and nothing more. Which changes you accept is your policy: docs/statamic.md locks names and birthdate and lets the address change.

Flink::reference() issues this session's reference on first use (@flinkReference in Blade), Flink::forgetReference() rotates it, so one journey run backs one submission. $prefill->id is the JWT's jti: the same on every retry of one release, so to be sure of one submission per release regardless of the session, accept each id once.

The JWT is personal data that stays verifiable after it expires: send it in a request body, verify it as soon as it arrives (it expires 5 minutes after the journey ends), and do not log or store it.

Verify any FLINK assertion

Every assertion FLINK signs verifies the same way; the caller always names the type it expects, so one type is never accepted as another (a results assertion never expires, so accepting it as a prefill would make it replayable forever):

Testing your app

Flink::fake() verifies against a key generated for the test, and signs assertions your config accepts, so your tests never reach FLINK:

Operations

• php artisan flink:keys:clear forgets the cached keys, so the next verification fetches them.
• php artisan about shows the FLINK settings.
• Set flink.events to dispatch AssertionVerified and AssertionRejected for an audit log. The rejection carries the expected type, the reason and the exception class as strings, never the JWT or its claims, so a queued listener can take it.
• flink.cache picks the store, key and lifetime of the cached keys; FLINK_JWKS_URL overrides where they come from.

Develop

License

MIT