@xemahq/oidc-issuer

Layer 0 — pure, framework-agnostic OpenID-Connect issuing primitives: signing-key rotation with overlapping kids, JWS minting, JWKS + discovery document construction, and the RFC 8693 token-exchange grant shape. Zero runtime dependencies (Node crypto only); zero framework dependency; zero domain concepts.

This is the signing counterpart to @xemahq/oidc-guard. One package verifies, one package signs, and no service implements either.

Why both halves are one contract

The two packages must agree on JWS details that a unit test of either side alone will not catch — above all the IEEE P1363 encoding of ECDSA signatures, where Node's default (DER) produces a token that is well-formed, correctly signed, and rejected by every compliant verifier.

tests/round-trip-with-oidc-guard.spec.ts therefore mints with this package and verifies with the real oidc-guard, rather than asserting against a second copy of our own assumptions.

Signing keys

const key = SigningKey.generate(SigningAlgorithm.ES256);

kid is the RFC 7638 JWK thumbprint, never a random id. That is load-bearing for rotation: the thumbprint is a pure function of the public key, so a key restored from storage always publishes under the kid that every already-minted token references. A random id would let one physical key appear under two kids across a restart, and every token issued before it would then reference a kid absent from the JWKS.

SigningAlgorithm is deliberately a subset of what oidc-guard verifies — RS256 and ES256. A verifier must accept whatever a third-party provider chose; an issuer only needs one good option per key type, and every algorithm offered is one a downgrade attempt can name.

Rotation: the ring, not the key

const rotated = ring.rotate(SigningKey.generate(SigningAlgorithm.ES256), {
  overlapSeconds: 7200,
});

Rotation without overlap is indistinguishable from a key compromise at the receiver: every token signed by the outgoing key references a kid no longer in the JWKS, so verification fails closed for the whole remaining lifetime of every token in flight. KeyRing keeps the outgoing key published (and therefore verifying) while it is no longer signing.

overlapSeconds is required and has no default. A default would be a guess about the caller's token lifetimes, and a guess that is too short produces a fleet-wide verification failure that appears only once the last correctly signed token expires — long after the rotation looked successful. It must exceed the longest token lifetime the issuer mints.

KeyRing is immutable, and rotate returns a new ring. A mutable ring invites rotate-in-place on one replica, which is exactly the operation that must never be local: a replica that rotated alone signs with a key no other replica publishes, and roughly 1/N of tokens fail verification depending on which replica answered the JWKS request. That does not reproduce under a single-replica test.

Persistence is a compare-and-set

SigningKeyStore is the seam; the store defines version (a row version, an ETag, a counter). replace must fail rather than overwrite when the stored version has moved, because rotation is time-triggered and every replica reaches the condition at approximately the same instant. The losing replica re-reads and adopts the winner's ring; it does not retry its own rotation.

Minting

const { token, expiresIn } = new JwtSigner().mint(
  ring,
  { sub: 'user-1', org_roles: ['admin'] },
  { issuer, lifetimeSeconds: 300 },
);

The signer owns iat / exp / nbf / jti and refuses a caller that supplies any of them — a caller-supplied lifetime is a caller-chosen one, which defeats every TTL bound the issuer exists to enforce. iss is likewise overridden, never merged: it is what a receiver pins trust to, so letting a caller set it would let one tenant mint tokens claiming another's issuer.

Every token carries the active kid in its header. Without it a receiver cannot resolve the key once a second one exists, and rotation stops being transparent.

Published documents

buildJwksDocument(ring) and buildDiscoveryDocument({ issuer, jwksUri }).

The discovery document is deliberately small. oidc-guard's IssuerMetadataResolver reads exactly one field — jwks_uri — and that is why an existing consumer can verify tokens from a new issuer without a code change. Nothing else is advertised speculatively, because every advertised capability is one a caller may legitimately expect to work; response_types_supported is an honest empty array, which is what stops a client library attempting an interactive flow against a machine-only issuer.

Serve one issuer per tenant. oidc-guard's OidcTokenVerifier resolves the tenant from the issuer path and refuses a token it cannot place. An issuer serving one flat URL for every tenant is therefore not a drop-in for an existing consumer fleet — it fails closed everywhere. A realm-shaped issuer (<base>/realms/<realm>) keeps extractRealmFromIssuer, the allow-list and the tenant fence all working unchanged.

Token exchange

Types and constants for RFC 8693 — TOKEN_EXCHANGE_GRANT_TYPE, TokenType, and buildActorChain for the nested act claim.

The exchange policy (who may impersonate whom, which audiences a subject may reach) is deliberately absent: that decision needs a grant store and a tenancy model, both of which belong to the issuing service, not to a Layer-0 primitive.

buildActorChain nests the new actor outside the one it inherited. Reversing that reads as "the user acted on behalf of the service", which inverts responsibility in every audit record derived from the token.

License

Apache-2.0 · xema.dev