Skip to content
Effect 4.0 is here. One ecosystem. Zero dependencies.

Jwk unstable

JSON Web Keys and the algorithm-bound keys the other effect/jose modules use.

A key is imported for one algorithm and keeps it: a JWS or JWE operation takes its algorithm from the key, so a token cannot pick another one. The imported key wraps an effect/crypto key object, which redacts itself when printed and caches its native key.

Importing honours the JWK's alg, use, and key_ops members, and rejects RSA keys shorter than 2048 bits.

33 exports Since v4.1.1 Source

Constructors

generateKeyPair

unstable
Since v4.1.1

Generates a key pair for an asymmetric algorithm and returns it as JWKs.

See

Signature

declare const generateKeyPair: (...args: [options: GenerateKeyPairOptions]) => Effect<KeyPair, JoseError, Signature>

generateSecret

unstable
Since v4.1.1

Generates a redacted secret JWK carrying its alg, use, and optional kid.

Details

HMAC keys contain 32, 48, or 64 random bytes for HS256, HS384, or HS512. Direct A256GCM keys contain 32 bytes and use enc instead of sig.

See

Signature

declare function generateSecret(algorithm: SecretAlgorithm, options?: {
  readonly kid?: string;
}): Effect<Redacted<{
  readonly alg?: string;
  readonly k: string;
  readonly key_ops?: readonly Array<string>;
  readonly kid?: string;
  readonly kty: "oct";
  readonly use?: string;
}>, never, SecureRandom>

importPkcs8

unstable
Since v4.1.1

Imports a redacted PKCS#8 private key from DER bytes or PEM text for an asymmetric algorithm.

See

Signature

declare const importPkcs8: (...args: [input: Redacted<string | Uint8Array<ArrayBufferLike>>, algorithm: "RS256" | "RS384" | "RS512" | "PS256" | "PS384" | "PS512" | "ES256" | "ES384" | "ES512" | "EdDSA", options?: {
  readonly kid?: string;
}]) => Effect<PrivateKey, JoseError, never>

importPrivate

unstable
Since v4.1.1

Imports a private JWK for an asymmetric algorithm.

See

Signature

declare const importPrivate: (...args: [input: Redacted<{
  readonly alg?: string;
  readonly d: string;
  readonly dp: string;
  readonly dq: string;
  readonly e: string;
  readonly key_ops?: readonly Array<string>;
  readonly kid?: string;
  readonly kty: "RSA";
  readonly n: string;
  readonly oth?: undefined;
  readonly p: string;
  readonly q: string;
  readonly qi: string;
  readonly use?: string;
} | {
  readonly alg?: string;
  readonly crv: "P-256" | "P-384" | "P-521";
  readonly d: string;
  readonly key_ops?: readonly Array<string>;
  readonly kid?: string;
  readonly kty: "EC";
  readonly use?: string;
  readonly x: string;
  readonly y: string;
} | {
  readonly alg?: string;
  readonly crv: "Ed25519";
  readonly d: string;
  readonly key_ops?: readonly Array<string>;
  readonly kid?: string;
  readonly kty: "OKP";
  readonly use?: string;
  readonly x: string;
}>, algorithm: "RS256" | "RS384" | "RS512" | "PS256" | "PS384" | "PS512" | "ES256" | "ES384" | "ES512" | "EdDSA"]) => Effect<PrivateKey, JoseError, never>

importPublic

unstable
Since v4.1.1

Imports a public JWK for an asymmetric algorithm.

Details

The key's family and curve must fit the algorithm, and any alg, use, or key_ops member must allow verification with it. Private members are rejected. To import untrusted JSON, decode it with PublicJwk first.

See

Signature

declare const importPublic: (...args: [jwk: {
  readonly alg?: string;
  readonly d?: undefined;
  readonly dp?: undefined;
  readonly dq?: undefined;
  readonly e: string;
  readonly k?: undefined;
  readonly key_ops?: readonly Array<string>;
  readonly kid?: string;
  readonly kty: "RSA";
  readonly n: string;
  readonly oth?: undefined;
  readonly p?: undefined;
  readonly q?: undefined;
  readonly qi?: undefined;
  readonly use?: string;
} | {
  readonly alg?: string;
  readonly crv: "P-256" | "P-384" | "P-521";
  readonly d?: undefined;
  readonly dp?: undefined;
  readonly dq?: undefined;
  readonly k?: undefined;
  readonly key_ops?: readonly Array<string>;
  readonly kid?: string;
  readonly kty: "EC";
  readonly oth?: undefined;
  readonly p?: undefined;
  readonly q?: undefined;
  readonly qi?: undefined;
  readonly use?: string;
  readonly x: string;
  readonly y: string;
} | {
  readonly alg?: string;
  readonly crv: "Ed25519";
  readonly d?: undefined;
  readonly dp?: undefined;
  readonly dq?: undefined;
  readonly k?: undefined;
  readonly key_ops?: readonly Array<string>;
  readonly kid?: string;
  readonly kty: "OKP";
  readonly oth?: undefined;
  readonly p?: undefined;
  readonly q?: undefined;
  readonly qi?: undefined;
  readonly use?: string;
  readonly x: string;
}, algorithm: "RS256" | "RS384" | "RS512" | "PS256" | "PS384" | "PS512" | "ES256" | "ES384" | "ES512" | "EdDSA"]) => Effect<PublicKey, JoseError, never>

importSecret

unstable
Since v4.1.1

Imports an octet JWK for HMAC signatures or for direct A256GCM encryption.

Details

HS256, HS384, and HS512 keys need at least 32, 48, and 64 bytes respectively; dir keys need exactly 32. Any alg, use, or key_ops member must allow the algorithm; key_ops must allow both of its operations.

See

Signature

declare const importSecret: <A extends SecretAlgorithm>(...args: [input: Redacted<{
  readonly alg?: string;
  readonly k: string;
  readonly key_ops?: readonly Array<string>;
  readonly kid?: string;
  readonly kty: "oct";
  readonly use?: string;
}>, algorithm: A]) => Effect<SecretKey<A>, JoseError, never>

Example Importing an HS256 key 

import { Effect, Redacted } from "effect"
import { Jwk } from "effect/jose"


// Fixed public example material; generate application secrets securely.
const secret = Redacted.make({ kty: "oct", k: "BwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwc" } as const)
const key = await Effect.runPromise(Jwk.importSecret(secret, "HS256"))
key.algorithm // => "HS256"

importSpki

unstable
Since v4.1.1

Imports an SPKI public key from DER bytes or PEM text for an asymmetric algorithm.

See

Signature

declare const importSpki: (...args: [input: string | Uint8Array<ArrayBufferLike>, algorithm: "RS256" | "RS384" | "RS512" | "PS256" | "PS384" | "PS512" | "ES256" | "ES384" | "ES512" | "EdDSA", options?: {
  readonly kid?: string;
}]) => Effect<PublicKey, JoseError, never>

Cryptography

thumbprint

unstable
Since v4.1.1

Computes an RFC 7638 JWK thumbprint, encoded as unpadded base64url.

Details

Uses SHA-256 by default; SHA-384 and SHA-512 are also supported. Only required key members are hashed, so metadata does not affect the result. Asymmetric private keys have the same thumbprint as their public keys. A secret key's thumbprint is a hash of the secret, so treat it as sensitive.

See

Signature

declare const thumbprint: (...args: [input: ThumbprintInput, hash: Algorithm]) => Effect<string, JoseError, Digest>

thumbprintUri

unstable
Since v4.1.1

Computes an RFC 9278 JWK thumbprint URI using SHA-256 by default.

See

Signature

declare function thumbprintUri(input: ThumbprintInput, hash: Algorithm): Effect<string, JoseError, Digest>

Encoding

exportPkcs8

unstable
Since v4.1.1

Exports a private key as redacted PKCS#8 DER bytes, or redacted PEM text with format: "pem".

See

Signature

declare function exportPkcs8(key: PrivateKey, options: {
  readonly format: "pem";
}): Effect<Redacted<string>, JoseError>
declare function exportPkcs8(key: PrivateKey, options?: {
  readonly format?: "der";
}): Effect<Redacted<Uint8Array<ArrayBufferLike>>, JoseError>
declare function exportPkcs8(key: PrivateKey, options?: {
  readonly format?: "pem" | "der";
}): Effect<Redacted<string | Uint8Array<ArrayBufferLike>>, JoseError>

exportPrivate

unstable
Since v4.1.1

Exports a private key as a JWK carrying its alg, kid, and use: "sig".

See

Signature

declare function exportPrivate(key: PrivateKey): Effect<Redacted<{
  readonly alg?: string;
  readonly d: string;
  readonly dp: string;
  readonly dq: string;
  readonly e: string;
  readonly key_ops?: readonly Array<string>;
  readonly kid?: string;
  readonly kty: "RSA";
  readonly n: string;
  readonly oth?: undefined;
  readonly p: string;
  readonly q: string;
  readonly qi: string;
  readonly use?: string;
} | {
  readonly alg?: string;
  readonly crv: "P-256" | "P-384" | "P-521";
  readonly d: string;
  readonly key_ops?: readonly Array<string>;
  readonly kid?: string;
  readonly kty: "EC";
  readonly use?: string;
  readonly x: string;
  readonly y: string;
} | {
  readonly alg?: string;
  readonly crv: "Ed25519";
  readonly d: string;
  readonly key_ops?: readonly Array<string>;
  readonly kid?: string;
  readonly kty: "OKP";
  readonly use?: string;
  readonly x: string;
}>, JoseError>

exportPublic

unstable
Since v4.1.1

Exports a public key as a JWK carrying its alg, kid, and use: "sig".

See

Signature

declare function exportPublic(key: PublicKey): Effect<{
  readonly alg?: string;
  readonly d?: undefined;
  readonly dp?: undefined;
  readonly dq?: undefined;
  readonly e: string;
  readonly k?: undefined;
  readonly key_ops?: readonly Array<string>;
  readonly kid?: string;
  readonly kty: "RSA";
  readonly n: string;
  readonly oth?: undefined;
  readonly p?: undefined;
  readonly q?: undefined;
  readonly qi?: undefined;
  readonly use?: string;
} | {
  readonly alg?: string;
  readonly crv: "P-256" | "P-384" | "P-521";
  readonly d?: undefined;
  readonly dp?: undefined;
  readonly dq?: undefined;
  readonly k?: undefined;
  readonly key_ops?: readonly Array<string>;
  readonly kid?: string;
  readonly kty: "EC";
  readonly oth?: undefined;
  readonly p?: undefined;
  readonly q?: undefined;
  readonly qi?: undefined;
  readonly use?: string;
  readonly x: string;
  readonly y: string;
} | {
  readonly alg?: string;
  readonly crv: "Ed25519";
  readonly d?: undefined;
  readonly dp?: undefined;
  readonly dq?: undefined;
  readonly k?: undefined;
  readonly key_ops?: readonly Array<string>;
  readonly kid?: string;
  readonly kty: "OKP";
  readonly oth?: undefined;
  readonly p?: undefined;
  readonly q?: undefined;
  readonly qi?: undefined;
  readonly use?: string;
  readonly x: string;
}, JoseError>

exportSpki

unstable
Since v4.1.1

Exports a public key as SPKI DER bytes, or as PEM text with format: "pem".

See

Signature

declare function exportSpki(key: PublicKey, options: {
  readonly format: "pem";
}): Effect<string, JoseError>
declare function exportSpki(key: PublicKey, options?: {
  readonly format?: "der";
}): Effect<Uint8Array<ArrayBufferLike>, JoseError>
declare function exportSpki(key: PublicKey, options?: {
  readonly format?: "pem" | "der";
}): Effect<string | Uint8Array<ArrayBufferLike>, JoseError>

Models

Algorithm

type unstable
Since v4.1.1

A JWS algorithm.

Signature

type Algorithm = typeof Algorithm.Type

AsymmetricAlgorithm

type unstable
Since v4.1.1

An asymmetric signature algorithm.

Signature

type AsymmetricAlgorithm = typeof AsymmetricAlgorithm.Type

GenerateKeyPairOptions

interface unstable
Since v4.1.1

Options for generateKeyPair.

Signature

interface GenerateKeyPairOptions {
  readonly algorithm: "RS256" | "RS384" | "RS512" | "PS256" | "PS384" | "PS512" | "ES256" | "ES384" | "ES512" | "EdDSA";
  readonly kid?: string;
  readonly modulusLength?: number;
}

HmacAlgorithm

type unstable
Since v4.1.1

An HMAC signature algorithm using SHA-256, SHA-384, or SHA-512.

Signature

type HmacAlgorithm = "HS256" | "HS384" | "HS512"

KeyPair

interface unstable
Since v4.1.1

A generated public JWK and its private JWK, both carrying alg, use: "sig", and the requested kid.

Signature

interface KeyPair {
  readonly privateKey: Redacted<{
    readonly alg?: string;
    readonly d: string;
    readonly dp: string;
    readonly dq: string;
    readonly e: string;
    readonly key_ops?: readonly Array<string>;
    readonly kid?: string;
    readonly kty: "RSA";
    readonly n: string;
    readonly oth?: undefined;
    readonly p: string;
    readonly q: string;
    readonly qi: string;
    readonly use?: string;
  } | {
    readonly alg?: string;
    readonly crv: "P-256" | "P-384" | "P-521";
    readonly d: string;
    readonly key_ops?: readonly Array<string>;
    readonly kid?: string;
    readonly kty: "EC";
    readonly use?: string;
    readonly x: string;
    readonly y: string;
  } | {
    readonly alg?: string;
    readonly crv: "Ed25519";
    readonly d: string;
    readonly key_ops?: readonly Array<string>;
    readonly kid?: string;
    readonly kty: "OKP";
    readonly use?: string;
    readonly x: string;
  }>;
  readonly publicKey: {
    readonly alg?: string;
    readonly d?: undefined;
    readonly dp?: undefined;
    readonly dq?: undefined;
    readonly e: string;
    readonly k?: undefined;
    readonly key_ops?: readonly Array<string>;
    readonly kid?: string;
    readonly kty: "RSA";
    readonly n: string;
    readonly oth?: undefined;
    readonly p?: undefined;
    readonly q?: undefined;
    readonly qi?: undefined;
    readonly use?: string;
  } | {
    readonly alg?: string;
    readonly crv: "P-256" | "P-384" | "P-521";
    readonly d?: undefined;
    readonly dp?: undefined;
    readonly dq?: undefined;
    readonly k?: undefined;
    readonly key_ops?: readonly Array<string>;
    readonly kid?: string;
    readonly kty: "EC";
    readonly oth?: undefined;
    readonly p?: undefined;
    readonly q?: undefined;
    readonly qi?: undefined;
    readonly use?: string;
    readonly x: string;
    readonly y: string;
  } | {
    readonly alg?: string;
    readonly crv: "Ed25519";
    readonly d?: undefined;
    readonly dp?: undefined;
    readonly dq?: undefined;
    readonly k?: undefined;
    readonly key_ops?: readonly Array<string>;
    readonly kid?: string;
    readonly kty: "OKP";
    readonly oth?: undefined;
    readonly p?: undefined;
    readonly q?: undefined;
    readonly qi?: undefined;
    readonly use?: string;
    readonly x: string;
  };
}

PrivateJwk

type unstable
Since v4.1.1

An RSA, P-256, P-384, P-521, or Ed25519 private JWK.

Signature

type PrivateJwk = typeof PrivateJwk.Type

PrivateKey

interface unstable
Since v4.1.1

A private key bound to one asymmetric algorithm.

Signature

interface PrivateKey {
  readonly _tag: "PrivateKey";
  readonly algorithm: "RS256" | "RS384" | "RS512" | "PS256" | "PS384" | "PS512" | "ES256" | "ES384" | "ES512" | "EdDSA";
  readonly key: PrivateKey;
  readonly kid: string | undefined;
}

PublicJwk

type unstable
Since v4.1.1

An RSA, P-256, P-384, P-521, or Ed25519 public JWK.

Signature

type PublicJwk = typeof PublicJwk.Type

PublicKey

interface unstable
Since v4.1.1

A public key bound to one asymmetric algorithm, with the JWK it was imported from.

Signature

interface PublicKey {
  readonly _tag: "PublicKey";
  readonly algorithm: "RS256" | "RS384" | "RS512" | "PS256" | "PS384" | "PS512" | "ES256" | "ES384" | "ES512" | "EdDSA";
  readonly jwk: {
    readonly alg?: string;
    readonly d?: undefined;
    readonly dp?: undefined;
    readonly dq?: undefined;
    readonly e: string;
    readonly k?: undefined;
    readonly key_ops?: readonly Array<string>;
    readonly kid?: string;
    readonly kty: "RSA";
    readonly n: string;
    readonly oth?: undefined;
    readonly p?: undefined;
    readonly q?: undefined;
    readonly qi?: undefined;
    readonly use?: string;
  } | {
    readonly alg?: string;
    readonly crv: "P-256" | "P-384" | "P-521";
    readonly d?: undefined;
    readonly dp?: undefined;
    readonly dq?: undefined;
    readonly k?: undefined;
    readonly key_ops?: readonly Array<string>;
    readonly kid?: string;
    readonly kty: "EC";
    readonly oth?: undefined;
    readonly p?: undefined;
    readonly q?: undefined;
    readonly qi?: undefined;
    readonly use?: string;
    readonly x: string;
    readonly y: string;
  } | {
    readonly alg?: string;
    readonly crv: "Ed25519";
    readonly d?: undefined;
    readonly dp?: undefined;
    readonly dq?: undefined;
    readonly k?: undefined;
    readonly key_ops?: readonly Array<string>;
    readonly kid?: string;
    readonly kty: "OKP";
    readonly oth?: undefined;
    readonly p?: undefined;
    readonly q?: undefined;
    readonly qi?: undefined;
    readonly use?: string;
    readonly x: string;
  };
  readonly key: PublicKey;
  readonly kid: string | undefined;
}

SecretAlgorithm

type unstable
Since v4.1.1

The algorithms of a symmetric key: HMAC signatures, or direct A256GCM encryption.

Signature

type SecretAlgorithm = HmacAlgorithm | "dir"

SecretJwk

type unstable
Since v4.1.1

An octet-sequence JWK.

Signature

type SecretJwk = typeof SecretJwk.Type

SecretKey

interface unstable
Since v4.1.1

A symmetric key bound to an HMAC signature algorithm or to direct A256GCM encryption.

Signature

interface SecretKey<A extends SecretAlgorithm = SecretAlgorithm> {
  readonly _tag: "SecretKey";
  readonly algorithm: A;
  readonly key: A extends HmacAlgorithm ? Key<Algorithm> : Key<Algorithm>;
  readonly kid: string | undefined;
}

SigningKey

type unstable
Since v4.1.1

A key that signs JWS and JWT tokens.

Signature

type SigningKey = PrivateKey | SecretKey<HmacAlgorithm>

ThumbprintInput

type unstable
Since v4.1.1

A JWK or imported key whose thumbprint can be computed. Private and secret JWKs must be redacted.

Signature

type ThumbprintInput = PublicJwk | Redacted.Redacted<PrivateJwk | SecretJwk> | PublicKey | PrivateKey | SecretKey

VerificationKey

type unstable
Since v4.1.1

A key that verifies JWS and JWT tokens.

Signature

type VerificationKey = PublicKey | SecretKey<HmacAlgorithm>

Schemas

Algorithm

unstable
Since v4.1.1

Schema for the JWS algorithms: HS256, HS384, HS512, and the asymmetric algorithms.

Signature

declare const Algorithm: Literals<readonly ["HS256", "HS384", "HS512", "RS256", "RS384", "RS512", "PS256", "PS384", "PS512", "ES256", "ES384", "ES512", "EdDSA"]>

AsymmetricAlgorithm

unstable
Since v4.1.1

Schema for RSA, RSA-PSS, and ECDSA signatures with SHA-256, SHA-384, or SHA-512, and EdDSA signatures with Ed25519.

Signature

declare const AsymmetricAlgorithm: Literals<readonly ["RS256", "RS384", "RS512", "PS256", "PS384", "PS512", "ES256", "ES384", "ES512", "EdDSA"]>

PrivateJwk

unstable
Since v4.1.1

Schema for an RSA, P-256, P-384, P-521, or Ed25519 private JWK. RSA keys need their CRT members and cannot have more than two primes.

Signature

declare const PrivateJwk: Union<readonly [Struct<{
  readonly alg: optionalKey<String>;
  readonly d: String;
  readonly dp: String;
  readonly dq: String;
  readonly e: String;
  readonly key_ops: optionalKey<$Array<String>>;
  readonly kid: optionalKey<String>;
  readonly kty: Literal<"RSA">;
  readonly n: String;
  readonly oth: optionalKey<Never>;
  readonly p: String;
  readonly q: String;
  readonly qi: String;
  readonly use: optionalKey<String>;
}>, Struct<{
  readonly alg: optionalKey<String>;
  readonly crv: Literals<readonly ["P-256", "P-384", "P-521"]>;
  readonly d: String;
  readonly key_ops: optionalKey<$Array<String>>;
  readonly kid: optionalKey<String>;
  readonly kty: Literal<"EC">;
  readonly use: optionalKey<String>;
  readonly x: String;
  readonly y: String;
}>, Struct<{
  readonly alg: optionalKey<String>;
  readonly crv: Literal<"Ed25519">;
  readonly d: String;
  readonly key_ops: optionalKey<$Array<String>>;
  readonly kid: optionalKey<String>;
  readonly kty: Literal<"OKP">;
  readonly use: optionalKey<String>;
  readonly x: String;
}>]>

PublicJwk

unstable
Since v4.1.1

Schema for an RSA, P-256, P-384, P-521, or Ed25519 public JWK. Private and symmetric members, including RSA factors, are rejected.

Signature

declare const PublicJwk: Union<readonly [Struct<{
  readonly alg: optionalKey<String>;
  readonly d: optionalKey<Never>;
  readonly dp: optionalKey<Never>;
  readonly dq: optionalKey<Never>;
  readonly e: String;
  readonly k: optionalKey<Never>;
  readonly key_ops: optionalKey<$Array<String>>;
  readonly kid: optionalKey<String>;
  readonly kty: Literal<"RSA">;
  readonly n: String;
  readonly oth: optionalKey<Never>;
  readonly p: optionalKey<Never>;
  readonly q: optionalKey<Never>;
  readonly qi: optionalKey<Never>;
  readonly use: optionalKey<String>;
}>, Struct<{
  readonly alg: optionalKey<String>;
  readonly crv: Literals<readonly ["P-256", "P-384", "P-521"]>;
  readonly d: optionalKey<Never>;
  readonly dp: optionalKey<Never>;
  readonly dq: optionalKey<Never>;
  readonly k: optionalKey<Never>;
  readonly key_ops: optionalKey<$Array<String>>;
  readonly kid: optionalKey<String>;
  readonly kty: Literal<"EC">;
  readonly oth: optionalKey<Never>;
  readonly p: optionalKey<Never>;
  readonly q: optionalKey<Never>;
  readonly qi: optionalKey<Never>;
  readonly use: optionalKey<String>;
  readonly x: String;
  readonly y: String;
}>, Struct<{
  readonly alg: optionalKey<String>;
  readonly crv: Literal<"Ed25519">;
  readonly d: optionalKey<Never>;
  readonly dp: optionalKey<Never>;
  readonly dq: optionalKey<Never>;
  readonly k: optionalKey<Never>;
  readonly key_ops: optionalKey<$Array<String>>;
  readonly kid: optionalKey<String>;
  readonly kty: Literal<"OKP">;
  readonly oth: optionalKey<Never>;
  readonly p: optionalKey<Never>;
  readonly q: optionalKey<Never>;
  readonly qi: optionalKey<Never>;
  readonly use: optionalKey<String>;
  readonly x: String;
}>]>

SecretJwk

unstable
Since v4.1.1

Schema for an octet-sequence JWK.

Signature

declare const SecretJwk: Struct<{
  readonly alg: optionalKey<String>;
  readonly k: String;
  readonly key_ops: optionalKey<$Array<String>>;
  readonly kid: optionalKey<String>;
  readonly kty: Literal<"oct">;
  readonly use: optionalKey<String>;
}>