Authentication tokens (JWT)
nish/crypto/jwt reads and writes JSON Web Tokens, the three-part
header.payload.signature strings that identity providers (Auth0, Okta,
Keycloak, Cognito, Google, Microsoft) hand to APIs in an
Authorization: Bearer header. It verifies a token's signature and then checks its
claims: when it expires, whom it was issued to, and by whom. It can also mint
tokens of its own.
It reads the compact form of RFC 7515 (JWS) under RFC 7519 (JWT), with the algorithms of RFC 7518 and RFC 8037:
| Algorithm | Verify | Sign | Key |
|---|---|---|---|
HS256, HS384, HS512 |
yes | yes | a shared secret, at least as long as the hash |
RS256, RS384, RS512 |
yes | no | an RSA public key of 2048 bits or more |
ES256 |
yes | yes | a P-256 key |
ES384 |
yes | no | a P-384 public key |
EdDSA |
yes | yes | an Ed25519 key |
A shared secret and a private key are Secret<u8[]> values
(Secrets), so the compiler keeps them
out of logs and templates. A key copies what you hand it, so you wipe your own
copy as soon as the key is made, and key.wipe() zeroes the key's copy when
you are done with it. A wiped key signs and verifies nothing.
Verifying a token
Make the key and a JwtVerifier once, at startup, then call verifyString
for each request. It answers JWT_OK or one JWT_ERR_* code, and after
JWT_OK the payload's JSON is v.claims[0 .. v.claimsLen) and its times are
v.exp, v.nbf and v.iat.
import {
JWT_ALG_HS256,
JWT_ERR_EXPIRED,
JWT_MAX_TOKEN,
JWT_OK,
JwtKey,
JwtVerifier,
jwtHmacKey,
jwtSignString,
} from "nish/crypto/jwt";
import { Secret, secret, wipe } from "nish:secret";
export const main = (): i32 => {
// At startup: a 32-byte secret, the key, and one verifier.
const raw: u8[] = new Array<u8>(32);
crypto.getRandomValues(raw);
const shared: Secret<u8[]> = secret(raw);
const key: JwtKey | null = jwtHmacKey(JWT_ALG_HS256, shared);
wipe(shared);
if (key === null) {
return 1; // a secret shorter than 32 bytes
}
const v: JwtVerifier = new JwtVerifier(JWT_MAX_TOKEN);
v.issuer = "https://auth.example";
v.audience = "orders-api";
v.leeway = toI64(30); // seconds of clock skew allowed
// A token this program minted, for the example.
const token: string | null = jwtSignString(
key,
'{"iss":"https://auth.example","aud":"orders-api","sub":"ana","exp":4102444800}',
);
if (token === null) {
return 1;
}
// Per request.
const now: i64 = toI64(Date.now()) / toI64(1000);
const code: i32 = v.verifyString(key, token, now);
if (code === JWT_OK) {
console.log(`signed in, ${v.claimsLen} bytes of claims`);
} else if (code === JWT_ERR_EXPIRED) {
console.log("expired: ask for a new token");
} else {
console.log(`refused: ${code}`);
}
key.wipe();
return 0;
};
verify(key, bytes, off, len, now) is the same check over a window of a byte
array, such as the header value in a request buffer, without copying it into
a string first.
What is refused
The key decides the algorithm. A key is made for one algorithm, and a
token verifies only when its header's alg names exactly that one. So a token
whose header says none is refused (JWT_ERR_ALG), and a token that says
HS256 is refused by an RSA key without the key ever being used as an HMAC
secret. These are the two classic JWT forgeries, and with this module
neither depends on how you call it. A header that holds alg twice, or
names an extension in crit, is refused too (JWT_ERR_HEADER).
The signature comes first. Nothing in the payload is read until the signature holds. Then the claims are checked, and the first failure is the answer:
| Claim | Rule | Refused with |
|---|---|---|
exp |
good while now - leeway < exp; required unless v.requireExp = false |
JWT_ERR_EXPIRED |
nbf |
good once nbf <= now + leeway |
JWT_ERR_NOT_YET |
iat |
not later than now + leeway |
JWT_ERR_IAT |
iss |
equal to v.issuer, when it is set |
JWT_ERR_ISSUER |
aud |
one string or an array of strings, one of which is v.audience. With v.audience unset, a token that carries an aud is refused, since it was meant for someone |
JWT_ERR_AUDIENCE |
sub |
equal to v.subject, when it is set |
JWT_ERR_SUBJECT |
Each of these claims may appear once. The times are whole seconds since 1970,
and a time claim given twice, as a string or with a fraction is
JWT_ERR_CLAIMS. Set v.typ = "JWT" (or your issuer's type, such as
at+jwt) to require a header typ as well (JWT_ERR_TYPE). It is compared
exactly, so give the spelling your issuer sends.
Each token has one spelling. Base64url padding, whitespace, + and /,
and a stray bit in a part's last character are refused (JWT_ERR_FORMAT).
A token longer than the verifier's limit is refused before any of it is
decoded (JWT_ERR_SIZE). The limit is JWT_MAX_TOKEN (8 KiB), or the size
you pass to new JwtVerifier.
Your own claims are yours to read. The verifier checks the registered
claims above and leaves the rest of the JSON in v.claims. It does not
refuse a private claim that appears twice, so read your own claims with a
parser that refuses duplicates or takes the first, never the last.
Keys from a provider
To have a provider's keys found, fetched and rotated for you, use tokens from an OpenID Connect issuer. To build them yourself:
A provider publishes its public keys as a JWK set. Decode each JWK's fields
with base64urlDecode from nish/crypto/base64url and build the key:
| JWK | Key |
|---|---|
"kty":"RSA", n, e |
jwtRsaKeyParts(JWT_ALG_RS256, n, e) |
"kty":"EC", "crv":"P-256", x, y |
jwtEcKey(JWT_ALG_ES256, point), where point is the byte 4, then x, then y |
"kty":"EC", "crv":"P-384", x, y |
jwtEcKey(JWT_ALG_ES384, point) |
"kty":"OKP", "crv":"Ed25519", x |
jwtEd25519Key(x) |
jwtRsaKey(alg, der) takes a PKCS#1 RSAPublicKey in DER instead. Each answers
null for a key it will not use: an RSA modulus below 2048 bits, a point of
the wrong length, an HMAC secret shorter than its hash.
When a provider has several keys, its tokens name one in the header's kid.
v.peekKid(bytes, off, len, out) copies it into out and answers its length,
or -1 when there is none. Use it only to choose the key: the kid is read
before any signature is checked, so it proves nothing until verify answers
JWT_OK under the key it chose.
Signing a token
jwtSignString(key, claims) signs a JSON object with an HS, ES256 or EdDSA
key and answers the token, or null when the key cannot sign (an RS or
ES384 key, or one made from a public key) or the claims are not one JSON
object. Claims outside ASCII are refused too: escape such text in the JSON
(\u00e9) or pass its UTF-8 bytes to jwtSign(key, bytes). The header is
{"alg":"…","typ":"JWT"}.
jwtSignKid(key, kid, bytes) adds a kid. The claims are signed as given,
so put the exp in yourself.
import { JWT_OK, JWT_MAX_TOKEN, JwtKey, JwtVerifier, jwtEd25519SigningKey, jwtSignKid } from "nish/crypto/jwt";
import { Secret, secret, wipe } from "nish:secret";
const bytesOf = (text: string): u8[] => {
const out: u8[] = [];
for (let i: i32 = 0; i < toI32(text.length); i++) {
out.push(toU8(text.charCodeAt(i)));
}
return out;
};
export const main = (): i32 => {
// An Ed25519 key from a 32-byte seed you keep secret.
const raw: u8[] = new Array<u8>(32);
crypto.getRandomValues(raw);
const seed: Secret<u8[]> = secret(raw);
const key: JwtKey | null = jwtEd25519SigningKey(seed);
wipe(seed);
if (key === null) {
return 1;
}
const now: i64 = toI64(Date.now()) / toI64(1000);
const claims: string = `{"sub":"ana","iat":${now},"exp":${now + toI64(900)}}`;
const token: string | null = jwtSignKid(key, "2026-10", bytesOf(claims));
if (token === null) {
return 1;
}
const ok: boolean = new JwtVerifier(JWT_MAX_TOKEN).verifyString(key, token, now) === JWT_OK;
console.log(ok ? "minted and verified" : "refused");
key.wipe();
return 0;
};
Cost
A JwtVerifier sizes its buffers once, from its limit. An HS verify then
allocates nothing past the arena block it runs in: the secret's HMAC state is
computed once, when the key is made, and copied per token, and the tag is
compared in constant time. An RS, ES or EdDSA verify allocates the arithmetic
its signature check needs, which using a = arena() around the request
releases. A verifier and an HS key are one thread's, since both hold working
state: give each worker its own.
What was checked and what is left open is in the module's security record.

