particle-academy/fancy-service-token
Service tokens from a Laravel app to its Python or Node sidecar: a short-lived HMAC-SHA256 token (audience, issuer, expiry, the caller's request id, a nonce) on every outgoing request via Http::withServiceToken(), plus a verifier held to the same shared fixtures. Standard library only, no JWT library. Pairs with fancy-service-token (PyPI) and @particle-academy/fancy-service-token.
composer require particle-academy/fancy-service-tokenAPI surface
Headless package — drive it from code or an agent. No component grid.
fancy-service-token (PHP / Laravel)
Short-lived service tokens from a Laravel app to its sidecar. Every request the app makes to its Python or Node sidecar carries a token signed with a shared key; the sidecar verifies it before reading the body and refuses every other caller.
- Signer with Laravel HTTP client integration:
Http::withServiceToken('ocr-sidecar'). - Audience, issuer, a short expiry, the caller's request id, and a nonce per token so a sidecar can refuse replays.
- Key rotation: sign with the new key; verifiers accept the old one during a grace window.
- HMAC-SHA256 with
hash_hmac/hash_equalsonly. No JWT library, no cryptography of our own, no runtime dependency beyond Laravel itself. - A framework-free
Verifiertoo, for an app that receives tokens.
Sidecar verifiers: fancy-service-token
on PyPI (Starlette / FastAPI) and @particle-academy/fancy-service-token
on npm. All three legs run the same fixture file byte for byte.
For agents. This package is not listed on the Fancy MCP catalog server yet. The server,
https://ui.particle.academy/mcp(streamable HTTP, no API key; MCP idfancy-ui), lists the released Fancy packages with install commands and docs. How an agent installs and uses this package is in AGENTS.md.
Install
composer require particle-academy/fancy-service-token
php artisan vendor:publish --tag=fancy-service-token-config # optional
FANCY_SERVICE_TOKEN_ISSUER=laravel-app
FANCY_SERVICE_TOKEN_KEY_ID=k2026b
FANCY_SERVICE_TOKEN_SECRET=base64:... # php -r "echo 'base64:'.base64_encode(random_bytes(32));"
Give the sidecar the same secret under the same key id, and configure its
verifier with issuer=laravel-app and its own audience.
Use
use Illuminate\Support\Facades\Http;
$response = Http::withServiceToken('ocr-sidecar')
->post('http://127.0.0.1:8090/ocr', ['document' => $id]);
Every send gets a fresh token, made at send time in request middleware, so
reusing the pending request or using retry() never resends a nonce the sidecar
has already accepted. The request also carries X-Request-Id.
Without the HTTP client:
use FancyServiceToken\Facades\ServiceToken;
$headers = ServiceToken::headers('ocr-sidecar'); // [X-Fancy-Service-Token => ..., X-Request-Id => ...]
$token = ServiceToken::sign('ocr-sidecar');
The request id
It joins a sidecar's log lines to the Laravel request that caused them. In
order: your resolver (ServiceToken::requestIdUsing(fn () => $traceId)), else
the incoming request's X-Request-Id when it is 1-128 chars of
[A-Za-z0-9._:-], else a UUID generated once per incoming request. Anything
else an ingress sends is replaced, never forwarded.
Key rotation
- Give the sidecar the new key next to the old one, with the old one's
accept_untilset a little past your longest token lifetime. - Switch
FANCY_SERVICE_TOKEN_KEY_ID/_SECREThere to the new key. - After
accept_until, remove the old key from the sidecar.
The signer only ever signs with key. previous (with accept_until, unix
seconds, inclusive) is used only by a verifier in this app.
Verifying in Laravel
For an app that also receives tokens (a sidecar calling back):
$verdict = ServiceToken::verifier('laravel-app-callbacks')->verify($request->header('X-Fancy-Service-Token'));
if (! $verdict->ok) {
abort(401, $verdict->reason->value);
}
$verdict->claims->requestId;
It uses your cache store's atomic add() for nonces.
Configuration
config/fancy-service-token.php. Every limit is a setting, with a secure default.
| key | default | |
|---|---|---|
issuer |
FANCY_SERVICE_TOKEN_ISSUER |
required |
key.id, key.secret |
default, FANCY_SERVICE_TOKEN_SECRET |
the secret is raw bytes or base64: |
previous.id, .secret, .accept_until |
unset | rotation, verifier only |
ttl |
60 |
seconds |
nonce |
true |
|
min_key_bytes |
32 |
|
header |
X-Fancy-Service-Token |
|
request_id_header |
X-Request-Id |
|
verify.clock_skew |
10 |
|
verify.max_lifetime |
300 |
|
verify.max_token_bytes |
1024 |
|
verify.require_nonce |
true |
|
verify.replay_cache_store |
default store |
Configuration errors are thrown when a token is first asked for, not at boot, and name the setting, never its value.
Refusal reasons
missing, malformed, bad_signature, expired, not_yet_valid,
wrong_audience, replayed: a fixed set shared by all three legs. A wrong
issuer, an unknown key id and a previous key past its grace window are all
bad_signature (no key is held for that issuer and id).
The token format (fst1)
fst1.<payload>.<signature>
-
payloadis the unpadded base64url (RFC 4648 section 5) of seven ASCII fields joined by a single LF (0x0A), in this order, with no trailing LF:# field grammar 1 kidkey id1-64 of [A-Za-z0-9._-]2 ississuer1-128 of [A-Za-z0-9._:/-]3 audaudience1-128 of [A-Za-z0-9._:/-]4 iatissued atunix seconds, decimal, 1-12 digits, no leading zero 5 expexpires atas iat; must be greater thaniat6 ridrequest id1-128 of [A-Za-z0-9._:-]7 nonceempty, or 16-128 of [A-Za-z0-9_-](the signer uses 16 random bytes: 22 chars) -
signatureis the unpadded base64url ofHMAC-SHA256(secret, ASCII("fst1." + payload)): 32 bytes, so 43 characters. -
base64url must be canonical: right alphabet, no padding, no whitespace, and the unused low bits of the last character clear.
-
Sent in one header,
X-Fancy-Service-Tokenby default.
A verifier checks in this order and stops at the first failure (the fixtures pin it):
- absent or empty:
missing - longer than
max_token_bytes:malformed - not three dot-separated parts, prefix not
fst1, signature not 43 characters, either part not canonical base64url:malformed - payload not ASCII, not seven fields, a field outside its grammar,
exp <= iat,exp - iat > max_lifetime, or no nonce while one is required:malformed - unknown
kid, HMAC mismatch (hash_equals), a previous key pastaccept_until, orissnot the configured issuer:bad_signature audnot the verifier's audience:wrong_audiencenow + clock_skew < iat:not_yet_validnow >= exp + clock_skew:expired- nonce already recorded:
replayed. Recorded only here, so a token refused for an earlier reason never spends one.
Conformance
conformance/service-token-v1.json is generated in fancy-service-token-py
from the format definition alone and copied here byte for byte. This suite runs
every verify case and checks that the signer reproduces the sign cases exactly.
License
MIT

