Your privacy choices

We use necessary cookies, and others only if you allow them. You can change your mind at any time.

FS

particle-academy/fancy-service-token

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.

Backend · renders no UIPHP
1 downloads this month1 downloads all-time
Backend · renders no UI
Nothing to preview — install it and call the typed API, or hand it to an agent.
$composer require particle-academy/fancy-service-token

API surface

Headless package — drive it from code or an agent. No component grid.

This package renders no UI surface. It exposes a typed PHP API; issues are tracked on GitHub.
readmeREADME.mdView on GitHub →

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_equals only. No JWT library, no cryptography of our own, no runtime dependency beyond Laravel itself.
  • A framework-free Verifier too, 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 id fancy-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

  1. Give the sidecar the new key next to the old one, with the old one's accept_until set a little past your longest token lifetime.
  2. Switch FANCY_SERVICE_TOKEN_KEY_ID / _SECRET here to the new key.
  3. 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>
  • payload is 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 kid key id 1-64 of [A-Za-z0-9._-]
    2 iss issuer 1-128 of [A-Za-z0-9._:/-]
    3 aud audience 1-128 of [A-Za-z0-9._:/-]
    4 iat issued at unix seconds, decimal, 1-12 digits, no leading zero
    5 exp expires at as iat; must be greater than iat
    6 rid request id 1-128 of [A-Za-z0-9._:-]
    7 nonce empty, or 16-128 of [A-Za-z0-9_-] (the signer uses 16 random bytes: 22 chars)
  • signature is the unpadded base64url of HMAC-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-Token by default.

A verifier checks in this order and stops at the first failure (the fixtures pin it):

  1. absent or empty: missing
  2. longer than max_token_bytes: malformed
  3. not three dot-separated parts, prefix not fst1, signature not 43 characters, either part not canonical base64url: malformed
  4. 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
  5. unknown kid, HMAC mismatch (hash_equals), a previous key past accept_until, or iss not the configured issuer: bad_signature
  6. aud not the verifier's audience: wrong_audience
  7. now + clock_skew < iat: not_yet_valid
  8. now >= exp + clock_skew: expired
  9. 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

What next
Install it, then call the API from your code or over MCP.