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

Verify Fancy service tokens in a Node sidecar: the same fst1 verifier as the Python leg, with a connect-style middleware that refuses before the body is read. node:crypto only, zero runtime dependencies. Pairs with particle-academy/fancy-service-token.

Backend · renders no UITS
493 downloads this month493 downloads all-time
Backend · renders no UI
Nothing to preview — install it and call the typed API, or hand it to an agent.
$npm install @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 code API; issues are tracked on GitHub.
readmeREADME.mdView on GitHub →

@particle-academy/fancy-service-token

Verify Fancy service tokens in a Node sidecar. A Laravel app signs a short-lived token on every request it makes to its sidecar (particle-academy/fancy-service-token); this package checks it before the request body is read and refuses every other caller with a named reason.

  • The verifier mirror of the PHP signer and the Python verifier (fancy-service-token on PyPI). All three run the same fixture file byte for byte.
  • HMAC-SHA256 with node:crypto only (createHmac, timingSafeEqual). No JWT library, no cryptography of our own, zero runtime dependencies.
  • Refusals carry one reason from a fixed set, never exception text; nothing it logs contains a token, a nonce or a secret.

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

npm install @particle-academy/fancy-service-token

Node 22 or later.

Use

import express from "express";
import { Verifier, serviceTokenMiddleware, currentRequestId } from "@particle-academy/fancy-service-token";

const verifier = new Verifier({
  keys: [{ kid: "k2026b", secret: Buffer.from(process.env.SERVICE_TOKEN_KEY!, "hex") }],
  audience: "ocr-sidecar",
  issuer: "laravel-app",
});

const app = express();
app.use(serviceTokenMiddleware({ verifier, log: (e) => logger[e.level](e) })); // BEFORE any body parser
app.use(express.json());

app.post("/ocr", (req, res) => {
  const { requestId } = req.serviceToken!;
});

The middleware is connect-style (req, res, next), so Express, Connect, Polka and a bare node:http handler all take it. Mount it before any body parser: it decides from req.headers alone and, on a refusal, never reads the body and never calls next(). The refusal also sets Connection: close, so the unread body is not parsed as a next request on the socket.

Verifier.verify(token, now?) works without the middleware too, and never throws: it returns { ok: true, claims } or { ok: false, reason }.

Refusals

401, Cache-Control: no-store, WWW-Authenticate: FancyServiceToken error="<reason>" and an x-request-id header. The body is the Fancy error envelope (the fancy-http-errors envelope.schema.json): exactly error, message and requestId, nothing else. The reason is in the WWW-Authenticate header, never in the body; message is one fixed English sentence per reason, identical in the Python and Node legs (conformance/refusal-messages.json). requestId is the incoming x-request-id when it matches ^[A-Za-z0-9._:-]{1,128}$, else a fresh UUID v4, and is echoed in an x-request-id response header.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: FancyServiceToken error="expired"
x-request-id: 3f6c0a52-6f1e-4b43-9d55-1f0d2b1f7e10
Cache-Control: no-store
Content-Type: application/json

{"error":"service_token_refused","message":"The service token has expired.","requestId":"3f6c0a52-6f1e-4b43-9d55-1f0d2b1f7e10"}

The request-id header name is the requestIdHeader option (default x-request-id). The sentences are exported as REFUSAL_MESSAGES.

reason means message
missing no token header, or an empty one This request carries no service token.
malformed not a well-formed fst1 token, longer than maxTokenBytes, a lifetime above maxLifetime, no nonce while requireNonce is on, or the header sent twice The service token could not be read.
bad_signature HMAC mismatch, unknown key id, a previous key past its grace window, or an issuer other than the configured one The service token signature does not match a known key.
expired now >= exp + clockSkew The service token has expired.
not_yet_valid now + clockSkew < iat The service token is not valid yet.
wrong_audience signed correctly, for a different sidecar The service token was issued for a different service.
replayed the nonce was already accepted (or the replay store is full: it fails closed) The service token has already been used.

Request id

The caller's request id is signed into the token. After verification it is on req.serviceToken.requestId and, for code running inside next() (including after an await), in currentRequestId(). Stream event callbacks such as req.on("data") are emitted from the socket's own async context, so read req.serviceToken there. The log option receives { level, message, reason?, requestId?, errorClass? } events.

Configuration

option default
keys required { kid, secret: Uint8Array, acceptUntil? }; secrets of at least minKeyBytes
audience required this sidecar's name
issuer required the Laravel app's name
clockSkew 10 seconds of tolerance on both ends
maxLifetime 300 the longest exp - iat accepted
maxTokenBytes 1024 checked before any parsing
requireNonce true
minKeyBytes 32
replayStore new MemoryReplayStore() anything with add(key, expiresAt, now): boolean; null turns replay checks off
clock Date.now milliseconds

serviceTokenMiddleware({ verifier, header = "x-fancy-service-token", exemptPaths = [], log }). exemptPaths are exact path matches (the query string is ignored), for a health check. MemoryReplayStore(maxEntries = 100_000) is per process; run several processes and you need a shared store.

Key rotation

Sign with the new key in Laravel; here, hold both and give the old one an acceptUntil (unix seconds, inclusive):

keys: [{ kid: "k2026b", secret: next }, { kid: "k2026a", secret: previous, acceptUntil: 1793000030 }]

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_-]
  • 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.

Checks run in this order and stop at the first failure (the fixtures pin it):

  1. absent or empty: missing
  2. longer than maxTokenBytes: 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 > maxLifetime, or no nonce while one is required: malformed
  5. unknown kid, HMAC mismatch (constant time), a previous key past acceptUntil, or iss not the configured issuer: bad_signature
  6. aud not this sidecar: wrong_audience
  7. now + clockSkew < iat: not_yet_valid
  8. now >= exp + clockSkew: 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 the shared fixture file, generated in fancy-service-token-py from the format definition alone and copied here byte for byte; the suite pins its SHA-256.

License

MIT

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