Jws unstable

Compact JSON Web Signatures.

The signing algorithm is the key's: sign writes it into the protected header and verify rejects a token whose alg differs. verifyWithKeySet resolves the key from the Jwks service and requires an allowlist of asymmetric algorithms. Headers with crit or b64 are rejected.

Bound untrusted token length before verification; this module does not impose a token-size limit.

HMAC signatures run on the Mac service. On Node.js and Bun, NodeCrypto.layerMac and BunCrypto.layerMac compute them synchronously with node:crypto instead of through Web Crypto for byte-backed keys, such as those from Jwk.importSecret.

10 exports Since v4.1.1 Source

Cryptography

sign

unstable

Since v4.1.1

Signs a payload as a compact JWS with the key's algorithm.

See

verify

Signature

declare const sign: <K extends SigningKey, H extends object & { [P in keyof H]: Schema.Json | undefined } = Header>(payload: Uint8Array, key: K, header?: Header & H) => Effect.Effect<Redacted.Redacted<string>, JoseError.JoseError, KeyRequirements<K>>

Example Signing and verifying a payload

import { Effect, Layer, Redacted } from "effect"
import { Mac, SecureRandom, Signature } from "effect/crypto"
import { Jwk, Jws } from "effect/jose"

const layer = Layer.mergeAll(Mac.layerWebCrypto, Signature.layerWebCrypto).pipe(
  Layer.provide(SecureRandom.layerWebCrypto)
)

const payload = await Effect.runPromise(Effect.gen(function*() {
  // Fixed public example material; generate application secrets securely.
  const key = yield* Jwk.importSecret(
    Redacted.make({ kty: "oct", k: "BwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwc" } as const),
    "HS256"
  )
  const token = yield* Jws.sign(new TextEncoder().encode("hello"), key)
  const verified = yield* Jws.verify(token, key)
  return new TextDecoder().decode(verified.payload)
}).pipe(Effect.provide(layer)))
payload // => "hello"

verify

unstable

Since v4.1.1

Verifies a compact JWS with a key. The token's alg must be the key's algorithm.

See

sign
verifyWithKeySet for resolving the key from the Jwks service

Signature

declare const verify: <K extends VerificationKey>(token: string | Redacted.Redacted<string>, key: K) => Effect.Effect<Verified, JoseError.JoseError, KeyRequirements<K>>

verifyWithKeySet

unstable

Since v4.1.1

Verifies a compact JWS with a public key resolved from the Jwks service by the token's alg and kid.

Details

The token's alg must be in algorithms, which is checked before any key lookup. The resolved key's algorithm must match the token's. HMAC tokens are always rejected.

See

verify for verifying with a known key

Signature

declare const verifyWithKeySet: (...args: [token: string | Redacted<string>, options: VerifyWithKeySetOptions]) => Effect<Verified & {
  readonly key: PublicKey;
}, JoseError, Signature | Jwks>

Models

Header

interface unstable

Since v4.1.1

Standard header parameters to sign. Signing also accepts additional JSON-valued parameters. alg comes from the key and kid defaults to the key's.

Signature

interface Header {
  readonly alg?: undefined;
  readonly b64?: undefined;
  readonly crit?: undefined;
  readonly cty?: string;
  readonly kid?: string;
  readonly typ?: string;
}

KeyRequirements

type unstable

Since v4.1.1

Services required to sign or verify with a key of type K: Mac for HMAC keys and Signature for asymmetric keys. A union of key types requires both.

Signature

type KeyRequirements<K extends SigningKey | VerificationKey> = K extends SecretKey<HmacAlgorithm> ? Mac.Mac : Signature.Signature

ProtectedHeader

type unstable

Since v4.1.1

An authenticated JWS protected header.

Signature

type ProtectedHeader = typeof ProtectedHeader.Type

Requirements

type unstable

Since v4.1.1

Services required to sign and verify with any key.

Signature

type Requirements = Mac.Mac | Signature.Signature

Verified

interface unstable

Since v4.1.1

The protected header and payload of a verified JWS.

Signature

interface Verified {
  readonly payload: Uint8Array;
  readonly protectedHeader: {
    [key: string]: Json;
    readonly alg: "RS256" | "RS384" | "RS512" | "PS256" | "PS384" | "PS512" | "ES256" | "ES384" | "ES512" | "EdDSA" | "HS256" | "HS384" | "HS512";
    readonly cty?: string;
    readonly kid?: string;
    readonly typ?: string;
  };
}

VerifyWithKeySetOptions

interface unstable

Since v4.1.1

Options for verifyWithKeySet.

Signature

interface VerifyWithKeySetOptions {
  readonly algorithms: readonly Array<"RS256" | "RS384" | "RS512" | "PS256" | "PS384" | "PS512" | "ES256" | "ES384" | "ES512" | "EdDSA">;
}

Schemas

ProtectedHeader

unstable

Since v4.1.1

Schema for an authenticated JWS protected header, including additional JSON-valued parameters.

Signature

declare const ProtectedHeader: StructWithRest<Struct<{
  readonly alg: Literals<readonly ["HS256", "HS384", "HS512", "RS256", "RS384", "RS512", "PS256", "PS384", "PS512", "ES256", "ES384", "ES512", "EdDSA"]>;
  readonly cty: optionalKey<String>;
  readonly kid: optionalKey<String>;
  readonly typ: optionalKey<String>;
}>, readonly [$Record<String, Codec<Json, Json, never, never>>]>