bazis 0.96.1

package/library/jwt/TokenIssuer.ts

@@ -0,0 +1,149 @@
+import {
+  RegisteredClaims,
+  TOKEN_USE_CLAIM,
+  type CustomClaims,
+  type JwtPayload,
+  type TokenUse,
+} from "./claims";
+import { JwtEncoder } from "./JwtEncoder";
+import { JwtValidator, type VerifiedToken } from "./JwtValidator";
+import { JwtClaimError } from "./errors";
+import type { SigningAlgorithm } from "./signing/SigningAlgorithm";
+import type { JwtKeyRing } from "./JwtKeyRing";
+
+export interface TokenIssuerConfig {
+  /** `iss` claim written to every token of this kind. */
+  readonly issuer: string;
+  /**
+   * `aud` claim binding tokens to this kind (e.g. `user`, `admin`, `employee`).
+   * Tokens of one kind never validate against another kind's audience.
+   */
+  readonly audience: string;
+  /** Signs and verifies tokens of this kind. Use a distinct key per kind. */
+  readonly algorithm: SigningAlgorithm | JwtKeyRing;
+  /** Optional separate algorithm for refresh tokens (defaults to {@link algorithm}). */
+  readonly refreshAlgorithm?: SigningAlgorithm | JwtKeyRing;
+  /** Finite, positive access token lifetime in seconds. */
+  readonly accessTtlSeconds: number;
+  /** Finite, positive refresh token lifetime in seconds. */
+  readonly refreshTtlSeconds: number;
+  /** Finite, non-negative clock skew leeway for validation (seconds). */
+  readonly clockSkewSeconds?: number;
+  /** Bound both issued and received compact JWS tokens. Default 16384. */
+  readonly maxTokenLength?: number;
+}
+
+/** An access + refresh token pair, shaped for an OAuth-style response. */
+export interface TokenPair {
+  readonly accessToken: string;
+  readonly refreshToken: string;
+  readonly tokenType: "Bearer";
+  /** Access token lifetime in seconds. */
+  readonly expiresIn: number;
+}
+
+/**
+ * Issues and verifies access/refresh tokens for a single audience ("kind").
+ *
+ * Access and refresh tokens are both signed JWTs (stateless): they carry a
+ * `token_use` claim so a refresh token can never be presented as an access
+ * token and vice versa. Each kind has its own signing key and `aud`, so a
+ * token minted for one kind (e.g. `user`) is cryptographically rejected by
+ * another kind's validator (e.g. `admin`).
+ *
+ * Rotation here is stateless — {@link rotate} verifies a refresh token and
+ * mints a fresh pair. Reuse detection / revocation requires a store and is
+ * intentionally left to the application layer.
+ */
+export class TokenIssuer {
+  private readonly accessEncoder: JwtEncoder;
+  private readonly refreshEncoder: JwtEncoder;
+  private readonly accessValidator: JwtValidator;
+  private readonly refreshValidator: JwtValidator;
+  private readonly config: TokenIssuerConfig;
+
+  public constructor(config: TokenIssuerConfig) {
+    if (config === null || typeof config !== "object" || Array.isArray(config)) {
+      throw new TypeError("TokenIssuer config must be an object");
+    }
+    this.config = Object.freeze({ ...config });
+    for (const field of ["issuer", "audience"] as const) {
+      if (typeof this.config[field] !== "string" || this.config[field].length === 0) {
+        throw new TypeError(`TokenIssuer ${field} must be a non-empty string`);
+      }
+    }
+    for (const field of ["accessTtlSeconds", "refreshTtlSeconds"] as const) {
+      const value = this.config[field];
+      if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+        throw new RangeError(`TokenIssuer ${field} must be finite and positive`);
+      }
+    }
+    const refreshAlgorithm = this.config.refreshAlgorithm === undefined ? this.config.algorithm : this.config.refreshAlgorithm;
+    this.accessEncoder = new JwtEncoder(this.config.algorithm, this.config);
+    this.refreshEncoder = new JwtEncoder(refreshAlgorithm, this.config);
+    this.accessValidator = this.buildValidator(this.config.algorithm, "access");
+    this.refreshValidator = this.buildValidator(refreshAlgorithm, "refresh");
+  }
+
+  /** Mints a fresh access + refresh pair for the given subject. */
+  public async issue(subject: string, claims?: CustomClaims): Promise<TokenPair> {
+    if (typeof subject !== "string" || subject.length === 0) {
+      throw new JwtClaimError(RegisteredClaims.Subject, "must be a non-empty string");
+    }
+    if (claims !== undefined && (claims === null || typeof claims !== "object" || Array.isArray(claims))) {
+      throw new TypeError("Custom claims must be an object");
+    }
+    const [accessToken, refreshToken] = await Promise.all([
+      this.accessEncoder.encode(this.buildPayload(subject, "access", this.config.accessTtlSeconds, claims)),
+      this.refreshEncoder.encode(this.buildPayload(subject, "refresh", this.config.refreshTtlSeconds)),
+    ]);
+    return { accessToken, refreshToken, tokenType: "Bearer", expiresIn: this.config.accessTtlSeconds };
+  }
+
+  /** Verifies an access token; throws a {@link JwtError} on any problem. */
+  public verifyAccess(token: string): Promise<VerifiedToken> {
+    return this.accessValidator.validate(token);
+  }
+
+  /** Verifies a refresh token; throws a {@link JwtError} on any problem. */
+  public verifyRefresh(token: string): Promise<VerifiedToken> {
+    return this.refreshValidator.validate(token);
+  }
+
+  /**
+   * Verifies a refresh token and issues a brand-new pair for the same subject.
+   * Optionally refreshes the access-token claims (e.g. updated roles).
+   */
+  public async rotate(refreshToken: string, claims?: CustomClaims): Promise<TokenPair> {
+    const { payload } = await this.verifyRefresh(refreshToken);
+    const subject = payload[RegisteredClaims.Subject];
+    if (typeof subject !== "string" || subject.length === 0) {
+      throw new JwtClaimError(RegisteredClaims.Subject, "refresh subject is required");
+    }
+    return this.issue(subject, claims);
+  }
+
+  private buildValidator(algorithm: SigningAlgorithm | JwtKeyRing, use: TokenUse): JwtValidator {
+    return new JwtValidator(algorithm, {
+      issuer: this.config.issuer,
+      audience: this.config.audience,
+      expectedTokenUse: use,
+      clockSkewSeconds: this.config.clockSkewSeconds,
+      maxTokenLength: this.config.maxTokenLength,
+    });
+  }
+
+  private buildPayload(subject: string, use: TokenUse, ttlSeconds: number, claims?: CustomClaims): JwtPayload {
+    const now = Date.now() / 1000;
+    return {
+      ...claims,
+      [RegisteredClaims.Subject]: subject,
+      [RegisteredClaims.Issuer]: this.config.issuer,
+      [RegisteredClaims.Audience]: this.config.audience,
+      [RegisteredClaims.IssuedAt]: now,
+      [RegisteredClaims.ExpiresAt]: now + ttlSeconds,
+      [RegisteredClaims.JwtId]: crypto.randomUUID(),
+      [TOKEN_USE_CLAIM]: use,
+    };
+  }
+}

package/library/jwt/TokenService.ts

@@ -0,0 +1,51 @@
+import { TokenIssuer, type TokenIssuerConfig } from "./TokenIssuer";
+
+/**
+ * Registry of {@link TokenIssuer}s keyed by token kind.
+ *
+ * Each kind (e.g. `user`, `admin`, `employee`) is fully isolated: its own
+ * signing key and audience. Adding a new kind is purely additive — extend the
+ * config map, no existing code changes. The generic key type `K` gives callers
+ * compile-time safety over which kinds exist.
+ *
+ * The concrete kinds are defined by the application, not this library. Pass a
+ * string-literal union as `K` for compile-time safety over which kinds exist:
+ *
+ * @example
+ * type Kind = "user" | "admin";
+ * const tokens = new TokenService<Kind>({
+ *   user:  { issuer, audience: "user",  algorithm: userKey,  accessTtlSeconds: 900, refreshTtlSeconds: 1_209_600 },
+ *   admin: { issuer, audience: "admin", algorithm: adminKey, accessTtlSeconds: 600, refreshTtlSeconds: 86_400 },
+ * });
+ * const pair = await tokens.forKind("user").issue("user-42");
+ */
+export class TokenService<K extends string = string> {
+  private readonly issuers: ReadonlyMap<K, TokenIssuer>;
+
+  public constructor(kinds: Readonly<Record<K, TokenIssuerConfig>>) {
+    const entries = (Object.entries(kinds) as Array<[K, TokenIssuerConfig]>).map(
+      ([kind, config]) => [kind, new TokenIssuer(config)] as const,
+    );
+    if (entries.length === 0) {
+      throw new Error("TokenService requires at least one token kind");
+    }
+    this.issuers = new Map(entries);
+  }
+
+  /** Returns the issuer for a kind; throws if the kind is not registered. */
+  public forKind(kind: K): TokenIssuer {
+    const issuer = this.issuers.get(kind);
+    if (issuer === undefined) {
+      throw new Error(`Unknown token kind '${kind}'`);
+    }
+    return issuer;
+  }
+
+  public has(kind: K): boolean {
+    return this.issuers.has(kind);
+  }
+
+  public kinds(): readonly K[] {
+    return [...this.issuers.keys()];
+  }
+}

package/library/jwt/base64url.ts

@@ -0,0 +1,61 @@
+const encoder = new TextEncoder();
+const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+
+/** RFC 4648 base64url encode without padding. Hot path — reuses TextEncoder. */
+export function base64UrlEncode(bytes: Uint8Array): string {
+  let binary = "";
+  for (let index = 0; index < bytes.length; index += 1) {
+    binary += String.fromCharCode(bytes[index]!);
+  }
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+/** Strict, canonical RFC 4648 base64url without padding. Empty input decodes to empty bytes. */
+export function base64UrlDecode(value: string): Uint8Array {
+  if (typeof value !== "string" || /[^A-Za-z0-9_-]/.test(value) || value.length % 4 === 1) {
+    throw new TypeError("Malformed base64url");
+  }
+  const remainder = value.length % 4;
+  const last = alphabet.indexOf(value.at(-1) ?? "");
+  if ((remainder === 2 && (last & 15) !== 0) || (remainder === 3 && (last & 3) !== 0)) {
+    throw new TypeError("Non-canonical base64url padding bits");
+  }
+  const normalized = value.replace(/-/g, "+").replace(/_/g, "/");
+  const padding = normalized.length % 4 === 0 ? "" : "=".repeat(4 - (normalized.length % 4));
+  const binary = atob(normalized + padding);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index += 1) {
+    bytes[index] = binary.charCodeAt(index);
+  }
+  return bytes;
+}
+
+export function base64UrlEncodeString(value: string): string {
+  return base64UrlEncode(encoder.encode(value));
+}
+
+export function base64UrlDecodeToString(value: string): string {
+  return decoder.decode(base64UrlDecode(value));
+}
+
+/** Returns the bytes as a standalone ArrayBuffer (strict BufferSource for Web Crypto). */
+export function toArrayBuffer(view: Uint8Array): ArrayBuffer {
+  return view.buffer.slice(view.byteOffset, view.byteOffset + view.byteLength) as ArrayBuffer;
+}
+
+/**
+ * Byte comparison without a match-position-dependent early return.
+ * JavaScript execution has no constant-time guarantee; JWT HMAC verification
+ * uses Web Crypto instead. Kept as a compatible public helper.
+ */
+export function timingSafeEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) {
+    return false;
+  }
+  let diff = 0;
+  for (let index = 0; index < a.length; index += 1) {
+    diff |= a[index]! ^ b[index]!;
+  }
+  return diff === 0;
+}

package/library/jwt/claims.ts

@@ -0,0 +1,36 @@
+/** Registered claim names defined by RFC 7519. */
+export const RegisteredClaims = {
+  Subject: "sub",
+  Issuer: "iss",
+  Audience: "aud",
+  ExpiresAt: "exp",
+  NotBefore: "nbf",
+  IssuedAt: "iat",
+  JwtId: "jti",
+} as const;
+
+/** Custom claim distinguishing access tokens from refresh tokens. */
+export const TOKEN_USE_CLAIM = "token_use";
+
+/** Whether a token authorizes API calls (`access`) or rotation only (`refresh`). */
+export type TokenUse = "access" | "refresh";
+
+/** A JSON-serialisable claim value. */
+export type ClaimValue = string | number | boolean | readonly string[] | null;
+
+/** A decoded JWT payload — claim name to value. */
+export interface JwtPayload {
+  readonly [claim: string]: ClaimValue | undefined;
+}
+
+/** Custom claims supplied by the caller when issuing a token. */
+export interface CustomClaims {
+  readonly [claim: string]: ClaimValue;
+}
+
+/** Compact JWS header. */
+export interface JwtHeader {
+  readonly alg: string;
+  readonly typ: "JWT";
+  readonly kid?: string;
+}

package/library/jwt/errors.ts

@@ -0,0 +1,44 @@
+/** Base class for every JWT failure. Maps cleanly to HTTP 401 at the edge. */
+export class JwtError extends Error {
+  public constructor(message: string) {
+    super(message);
+    this.name = new.target.name;
+  }
+}
+
+/** Token is structurally invalid (wrong segment count, bad base64, bad JSON). */
+export class JwtMalformedError extends JwtError {}
+
+/** Header `alg` does not match the verifying algorithm (blocks `alg` confusion). */
+export class JwtAlgorithmError extends JwtError {}
+
+/** Cryptographic signature check failed. */
+export class JwtSignatureError extends JwtError {
+  public constructor() {
+    super("Invalid token signature");
+  }
+}
+
+/** `exp` claim is in the past (accounting for clock skew). */
+export class JwtExpiredError extends JwtError {
+  public constructor() {
+    super("Token has expired");
+  }
+}
+
+/** `nbf` claim is in the future (accounting for clock skew). */
+export class JwtNotYetValidError extends JwtError {
+  public constructor() {
+    super("Token is not yet valid");
+  }
+}
+
+/** A registered claim (`iss`, `aud`, `token_use`, …) failed validation. */
+export class JwtClaimError extends JwtError {
+  public constructor(
+    public readonly claim: string,
+    reason: string,
+  ) {
+    super(`Invalid '${claim}' claim: ${reason}`);
+  }
+}

package/library/jwt/index.ts

@@ -0,0 +1,59 @@
+/**
+ * JWT library for Bazis.
+ *
+ * Pure JWT logic without services, controllers or kernel dependencies: only
+ * Web Crypto and standard APIs, compatible with binary compilation
+ * (`bun build --compile`).
+ *
+ * Layers:
+ * - {@link SigningAlgorithm}: signing strategy (HS256 / RS256), caches keys.
+ * - {@link JwtKeyRing}: a set of keys addressed by `kid`, for key rotation.
+ * - {@link JwtEncoder} / {@link JwtValidator}: encoding and strict validation.
+ * - {@link TokenIssuer}: issues an access/refresh pair for one token kind.
+ * - {@link TokenService}: registry of token kinds (for example `user` / `admin`),
+ *   each with its own key and `aud`; tokens of different kinds reject each other.
+ *
+ * Secure by default: fail-closed validation, an `alg` check (protection against
+ * algorithm confusion), HMAC verification through Web Crypto, and a mandatory
+ * `token_use` binding in TokenIssuer (access ≠ refresh). Contracts: MODULE.md.
+ */
+
+export { base64UrlEncode, base64UrlDecode, base64UrlEncodeString, base64UrlDecodeToString, timingSafeEqual } from "./base64url";
+
+export {
+  RegisteredClaims,
+  TOKEN_USE_CLAIM,
+  type TokenUse,
+  type ClaimValue,
+  type JwtPayload,
+  type CustomClaims,
+  type JwtHeader,
+} from "./claims";
+
+export {
+  JwtError,
+  JwtMalformedError,
+  JwtAlgorithmError,
+  JwtSignatureError,
+  JwtExpiredError,
+  JwtNotYetValidError,
+  JwtClaimError,
+} from "./errors";
+
+export type { SigningAlgorithm } from "./signing/SigningAlgorithm";
+export { Hs256Algorithm, hs256, HS256_MIN_KEY_BYTES } from "./signing/Hs256Algorithm";
+export { Rs256Algorithm, rs256, generateRsaKeyPairPem, type Rs256KeyMaterial } from "./signing/Rs256Algorithm";
+export { decodePem, decodePemToBuffer, encodePem } from "./signing/pem";
+
+export { JwtEncoder } from "./JwtEncoder";
+export { JwtKeyRing, type JwtKeyEntry, type JwtKeyRingConfig } from "./JwtKeyRing";
+export { DEFAULT_MAX_TOKEN_LENGTH } from "./limits";
+export {
+  JwtValidator,
+  DEFAULT_CLOCK_SKEW_SECONDS,
+  type JwtValidationOptions,
+  type VerifiedToken,
+} from "./JwtValidator";
+
+export { TokenIssuer, type TokenIssuerConfig, type TokenPair } from "./TokenIssuer";
+export { TokenService } from "./TokenService";

package/library/jwt/limits.ts

@@ -0,0 +1,8 @@
+/** Compact JWS is ASCII. Bound work before splitting, decoding or cryptography. */
+export const DEFAULT_MAX_TOKEN_LENGTH = 16_384;
+
+export function resolveMaxTokenLength(value: number | undefined): number {
+  if (value === undefined) return DEFAULT_MAX_TOKEN_LENGTH;
+  if (!Number.isSafeInteger(value) || value < 1) throw new RangeError("JWT maxTokenLength must be a positive safe integer");
+  return value;
+}

package/library/jwt/signing/Hs256Algorithm.ts

@@ -0,0 +1,62 @@
+import { toArrayBuffer } from "../base64url";
+import type { SigningAlgorithm } from "./SigningAlgorithm";
+
+const encoder = new TextEncoder();
+
+/** Minimum key length for HS256 — matches the SHA-256 output size (RFC 2104). */
+export const HS256_MIN_KEY_BYTES = 32;
+
+/**
+ * Symmetric HMAC-SHA256 (HS256).
+ *
+ * The same key both signs and verifies, so it is suitable when a single
+ * trusted party issues and validates tokens. The imported {@link CryptoKey}
+ * is cached after first use. Caller-owned key bytes are copied immediately.
+ */
+export class Hs256Algorithm implements SigningAlgorithm {
+  public readonly alg = "HS256";
+  public readonly canSign = true;
+
+  private readonly keyBytes: Uint8Array;
+  private cryptoKey?: CryptoKey;
+
+  public constructor(secret: string | Uint8Array) {
+    if (typeof secret !== "string" && !(secret instanceof Uint8Array)) {
+      throw new TypeError("HS256 secret must be a string or Uint8Array");
+    }
+    this.keyBytes = typeof secret === "string" ? encoder.encode(secret) : new Uint8Array(secret);
+    if (this.keyBytes.length < HS256_MIN_KEY_BYTES) {
+      throw new RangeError(`HS256 secret must be at least ${HS256_MIN_KEY_BYTES} bytes`);
+    }
+  }
+
+  public async sign(signingInput: string): Promise<Uint8Array> {
+    const key = await this.importKey();
+    const signature = await crypto.subtle.sign("HMAC", key, encoder.encode(signingInput));
+    return new Uint8Array(signature);
+  }
+
+  public async verify(signingInput: string, signature: Uint8Array): Promise<boolean> {
+    const key = await this.importKey();
+    return crypto.subtle.verify("HMAC", key, toArrayBuffer(signature), encoder.encode(signingInput));
+  }
+
+  private async importKey(): Promise<CryptoKey> {
+    if (this.cryptoKey !== undefined) {
+      return this.cryptoKey;
+    }
+    this.cryptoKey = await crypto.subtle.importKey(
+      "raw",
+      toArrayBuffer(this.keyBytes),
+      { name: "HMAC", hash: "SHA-256" },
+      false,
+      ["sign", "verify"],
+    );
+    return this.cryptoKey;
+  }
+}
+
+/** Convenience factory for {@link Hs256Algorithm}. */
+export function hs256(secret: string | Uint8Array): Hs256Algorithm {
+  return new Hs256Algorithm(secret);
+}

package/library/jwt/signing/Rs256Algorithm.ts

@@ -0,0 +1,133 @@
+import { toArrayBuffer } from "../base64url";
+import { decodePemToBuffer, encodePem } from "./pem";
+import type { SigningAlgorithm } from "./SigningAlgorithm";
+
+const RSA_PARAMS = { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" } as const;
+const encoder = new TextEncoder();
+
+export interface Rs256KeyMaterial {
+  /** PKCS#8 private key PEM — required to sign, optional for verify-only. */
+  readonly privateKeyPem?: string;
+  /** SPKI public key PEM — required to verify. */
+  readonly publicKeyPem: string;
+  /** `kid` header value and verify-time match (default: no `kid`). */
+  readonly keyId?: string;
+}
+
+/**
+ * Asymmetric RS256 (RSASSA-PKCS1-v1.5 + SHA-256).
+ *
+ * The private key signs; the public key verifies. Verifiers can hold only the
+ * public key, which is the recommended setup for separating an auth issuer
+ * from resource services. Imported keys are cached for the hot path.
+ */
+export class Rs256Algorithm implements SigningAlgorithm {
+  public readonly alg = "RS256";
+  public readonly canSign: boolean;
+  public readonly keyId?: string;
+
+  private cachedPrivate?: CryptoKey;
+  private cachedPublic?: CryptoKey;
+  private readonly keys: Rs256KeyMaterial;
+
+  public constructor(keys: Rs256KeyMaterial) {
+    if (keys === null || typeof keys !== "object" || Array.isArray(keys)) {
+      throw new TypeError("RS256 key material must be an object");
+    }
+    this.keys = Object.freeze({ ...keys });
+    for (const field of ["publicKeyPem", "privateKeyPem", "keyId"] as const) {
+      const value = this.keys[field];
+      if (value === undefined && field !== "publicKeyPem") continue;
+      if (typeof value !== "string" || value.length === 0) {
+        throw new TypeError(`RS256 ${field} must be a non-empty string`);
+      }
+    }
+    this.canSign = this.keys.privateKeyPem !== undefined;
+    this.keyId = this.keys.keyId;
+  }
+
+  public async sign(signingInput: string): Promise<Uint8Array> {
+    const key = await this.importPrivateKey();
+    const signature = await crypto.subtle.sign(RSA_PARAMS, key, encoder.encode(signingInput));
+    return new Uint8Array(signature);
+  }
+
+  public async verify(signingInput: string, signature: Uint8Array): Promise<boolean> {
+    const key = await this.importPublicKey();
+    return crypto.subtle.verify(RSA_PARAMS, key, toArrayBuffer(signature), encoder.encode(signingInput));
+  }
+
+  /** Exports the public key as a JWK (for serving `/.well-known/jwks.json`). */
+  public async exportPublicJwk(): Promise<Record<string, string>> {
+    const key = await this.importPublicKey();
+    const jwk = (await crypto.subtle.exportKey("jwk", key)) as { n?: string; e?: string };
+    return {
+      kty: "RSA",
+      use: "sig",
+      alg: "RS256",
+      n: jwk.n!,
+      e: jwk.e!,
+      ...(this.keyId === undefined ? {} : { kid: this.keyId }),
+    };
+  }
+
+  private async importPrivateKey(): Promise<CryptoKey> {
+    if (this.cachedPrivate !== undefined) {
+      return this.cachedPrivate;
+    }
+    if (this.keys.privateKeyPem === undefined) {
+      throw new Error("RS256 private key PEM is required for signing");
+    }
+    const key = await crypto.subtle.importKey(
+      "pkcs8",
+      decodePemToBuffer(this.keys.privateKeyPem),
+      RSA_PARAMS,
+      false,
+      ["sign"],
+    );
+    return this.cachedPrivate = this.requireStrongKey(key);
+  }
+
+  private async importPublicKey(): Promise<CryptoKey> {
+    if (this.cachedPublic !== undefined) {
+      return this.cachedPublic;
+    }
+    const key = await crypto.subtle.importKey(
+      "spki",
+      decodePemToBuffer(this.keys.publicKeyPem),
+      RSA_PARAMS,
+      true,
+      ["verify"],
+    );
+    return this.cachedPublic = this.requireStrongKey(key);
+  }
+
+  private requireStrongKey(key: CryptoKey): CryptoKey {
+    const parameters = key.algorithm;
+    if (!("modulusLength" in parameters) || typeof parameters.modulusLength !== "number" ||
+        !Number.isInteger(parameters.modulusLength) || parameters.modulusLength < 2048) {
+      throw new RangeError("RS256 keys must be at least 2048 bits");
+    }
+    return key;
+  }
+}
+
+/** Convenience factory for {@link Rs256Algorithm}. */
+export function rs256(keys: Rs256KeyMaterial): Rs256Algorithm {
+  return new Rs256Algorithm(keys);
+}
+
+/** Generates an RSA-2048 key pair as PEM strings (bootstrap / tests). */
+export async function generateRsaKeyPairPem(): Promise<{ privateKeyPem: string; publicKeyPem: string }> {
+  const pair = await crypto.subtle.generateKey(
+    { name: "RSASSA-PKCS1-v1_5", modulusLength: 2048, publicExponent: new Uint8Array([1, 0, 1]), hash: "SHA-256" },
+    true,
+    ["sign", "verify"],
+  );
+  const privateDer = new Uint8Array(await crypto.subtle.exportKey("pkcs8", pair.privateKey));
+  const publicDer = new Uint8Array(await crypto.subtle.exportKey("spki", pair.publicKey));
+  return {
+    privateKeyPem: encodePem("PRIVATE KEY", privateDer),
+    publicKeyPem: encodePem("PUBLIC KEY", publicDer),
+  };
+}

package/library/jwt/signing/SigningAlgorithm.ts

@@ -0,0 +1,18 @@
+/**
+ * A pluggable JWT signing/verification strategy (HS256, RS256, …).
+ *
+ * Implementations must be stateless from the caller's perspective and may
+ * cache imported {@link CryptoKey}s internally to keep the verify path fast.
+ */
+export interface SigningAlgorithm {
+  /** JWS `alg` header value (e.g. `HS256`, `RS256`). */
+  readonly alg: string;
+  /** Optional `kid` written to the header and matched on verify. */
+  readonly keyId?: string;
+  /** Whether this instance holds the secret/private key needed to sign. */
+  readonly canSign: boolean;
+  /** Produces the signature bytes for the `header.payload` signing input. */
+  sign(signingInput: string): Promise<Uint8Array>;
+  /** Constant-time / cryptographic verification of a detached signature. */
+  verify(signingInput: string, signature: Uint8Array): Promise<boolean>;
+}

package/library/jwt/signing/pem.ts

@@ -0,0 +1,30 @@
+/** Strips PEM armor and decodes the base64 payload to DER bytes. */
+export function decodePem(pem: string): Uint8Array {
+  const body = pem
+    .trim()
+    .split("\n")
+    .filter((line) => !line.startsWith("-----"))
+    .join("");
+  const binary = atob(body);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index += 1) {
+    bytes[index] = binary.charCodeAt(index);
+  }
+  return bytes;
+}
+
+/** Returns a standalone ArrayBuffer (strict BufferSource for Web Crypto import). */
+export function decodePemToBuffer(pem: string): ArrayBuffer {
+  const bytes = decodePem(pem);
+  return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer;
+}
+
+/** Wraps DER bytes in PEM armor with the given label. */
+export function encodePem(label: string, der: Uint8Array): string {
+  let binary = "";
+  for (let index = 0; index < der.length; index += 1) {
+    binary += String.fromCharCode(der[index]!);
+  }
+  const lines = btoa(binary).match(/.{1,64}/g) ?? [];
+  return `-----BEGIN ${label}-----\n${lines.join("\n")}\n-----END ${label}-----\n`;
+}