JWK — keys as JSON

A JSON Web Key (RFC 7517) is a portable JSON representation of a cryptographic key. Every signing, verifying, encrypting, and decrypting operation in unjwt starts with a key — and JWK is the lingua franca for carrying that key through config files, environment variables, databases, and across the wire.

{
  "kty": "oct",
  "k": "GawgguFyGrWKav7AX4VKUg",
  "alg": "HS256",
  "kid": "4c3d-..."
}

Import:

import { generateJWK, importKey, exportKey } from "unjwt/jwk";
// or from the flat barrel:
import { generateJWK } from "unjwt";

Basic usage

The most common operation — create a key:

import { generateJWK } from "unjwt/jwk";

// Symmetric — one JWK
const hmacKey = await generateJWK("HS256");
// { kty: "oct", k: "...", alg: "HS256", kid: "4c3d-..." }

// Asymmetric — a pair
const { privateKey, publicKey } = await generateJWK("RS256");

Every JWK produced by generateJWK() includes:

• kty — key type ("oct" | "RSA" | "EC" | "OKP").
• alg — the algorithm it's meant for (e.g. "HS256", "RS256", "Ed25519").
• kid — an auto-generated UUID, which any JWT signed with this key will carry in its header for routing.

Those three fields are why the rest of the library "just works" — sign(), verify(), encrypt(), decrypt() all read them and do the right thing.

The JWK shape

Every JWK has a kty (key type) field that determines its other properties:

A JWK is public if it carries no d (or has no d equivalent for oct); private if it does.

unjwt provides type guards to distinguish:

import { isPublicJWK, isPrivateJWK, isSymmetricJWK } from "unjwt/utils";

if (isSymmetricJWK(key)) {
  /* kty === "oct" */
}
if (isPublicJWK(key)) {
  /* asymmetric, no d */
}
if (isPrivateJWK(key)) {
  /* asymmetric, has d */
}

What you can do with a JWK

• Generate one — generateJWK().
• Import existing material — importKey().
• Export a CryptoKey to JWK — exportKey().
• Convert to/from PEM — importPEM() / exportPEM().
• Wrap / unwrap a key with another key — wrapKey() / unwrapKey().
• Derive from a password — deriveJWKFromPassword().
• Rotate using a JWK Set — JWK Sets.
• Cache to avoid repeat imports — JWK cache.

Going further

• Generating keys → — generateKey vs generateJWK, algorithms, curves, RSA modulus.
• Importing & exporting → — importKey, exportKey, the expect option.
• PEM conversion → — importPEM / exportPEM.
• Wrapping & unwrapping → — wrapping a CEK for custom protocols.
• Password derivation → — PBES2 and PBKDF2.
• JWK Sets → — multi-key selection, JWKS endpoints, key rotation.
• JWK cache → — controlling how imported CryptoKeys are memoized.