JSON Web Tokens

A JWT is a signed statement such as "this request is from user 42, until 10:15". The server that issues it signs it; any server holding the right key can check it without a database lookup.

Creating an instanceCopy Anchor Link

createJwt returns a signer and verifier bound to one algorithm and one set of keys. Create it once and reuse it.

import sukuCrypto from '@sukujs/crypto';

const jwt = sukuCrypto.createJwt<{ role: 'user' | 'admin' }>({
  secret: env.JWT_SECRET,
  issuer: 'my-api',
  audience: 'my-web-app',
  expiresIn: '15m',
});

In a Suku app, make it a service so routes and middlewares can ask for it.

export const Tokens = service('tokens', {
  services: { env: Env },
  create: ({ env }) =>
    sukuCrypto.createJwt<{ role: 'user' | 'admin' }>({ secret: env.JWT_SECRET, issuer: 'my-api', expiresIn: '15m' }),
});

SigningCopy Anchor Link

const token = await jwt.sign({ role: 'admin' }, { subject: user.id });

sign adds iat (issued at), exp (expiry), and the configured iss and aud.

Durations are seconds, or strings such as 30s, 15m, 12h, 7d.

VerifyingCopy Anchor Link

import sukuCrypto, { JwtError } from '@sukujs/crypto';

try {
  const payload = await jwt.verify(token);
  payload.sub;    // "42"
  payload.role;   // "admin"
} catch (error) {
  if (error instanceof JwtError) log.debug('token rejected', { code: error.code });
  throw new UnauthorizedException();
}

verify returns the payload only if every check passes.

The algorithm is fixed when you create the instance and is never taken from the token. That is what defeats two classic attacks: tokens declaring alg: none, and tokens signed with HMAC using an RSA public key as the secret.

Reading the token from a requestCopy Anchor Link

import sukuCrypto from '@sukujs/crypto';

const token = sukuCrypto.bearerToken(ctx.headers.get('authorization'));   // undefined if absent or malformed

Choosing an algorithmCopy Anchor Link

With a shared secret, anything that can verify a token can also forge one. Use a key pair as soon as a second service needs to verify.

// The auth service signs.
const issuer = sukuCrypto.createJwt({ algorithm: 'ES256', privateKey: env.JWT_PRIVATE_KEY, publicKey: env.JWT_PUBLIC_KEY, issuer: 'auth' });

// Every other service only verifies, and holds no secret.
const verifier = sukuCrypto.createJwt({ algorithm: 'ES256', publicKey: env.JWT_PUBLIC_KEY, issuer: 'auth' });

Keys may be PEM strings, JWK objects or CryptoKeys. PEM must be PKCS#8 for private keys and SPKI for public keys.

# ES256 key pair
openssl ecparam -name prime256v1 -genkey -noout | openssl pkcs8 -topk8 -nocrypt -out private.pem
openssl ec -in private.pem -pubout -out public.pem

# Convert a legacy "BEGIN RSA PRIVATE KEY" file
openssl pkcs8 -topk8 -nocrypt -in legacy.pem -out private.pem

Typed and validated payloadsCopy Anchor Link

The type parameter describes the payload for TypeScript. A schema also checks it at runtime, which matters when tokens may come from an older version of your app.

const Claims = z.object({ sub: z.string(), role: z.enum(['user', 'admin']) });

const jwt = sukuCrypto.createJwt({ secret: env.JWT_SECRET, schema: Claims });
const { role } = await jwt.verify(token);   // 'user' | 'admin', checked

OptionsCopy Anchor Link

Rotating keysCopy Anchor Link

Add the new key as the main one and move the old one to the "previous" list. New tokens are signed with the new key; old tokens keep verifying until they expire.

sukuCrypto.createJwt({ secret: env.JWT_SECRET, previousSecrets: [env.JWT_SECRET_OLD] });

Once the longest token lifetime has passed, remove the old key.

Inspecting a tokenCopy Anchor Link

decodeJwtUnverified reads the header and payload without checking anything. Its output is attacker-controlled. It is for logging and debugging, never for a decision.

const { header, payload } = sukuCrypto.decodeJwtUnverified(token);

What a JWT cannot doCopy Anchor Link

• It cannot be revoked. It is valid until it expires. Keep access tokens short-lived.
• It hides nothing. The payload is readable by anyone who has the token.
• It does not replace a session store when you need to log a user out everywhere at once.

See use cases for a complete login flow that handles all three.