RequestSeal.JOSE.JWS (RequestSeal v0.1.0)

Copy Markdown View Source

Compact RFC 7515 signatures over exact protected and payload segments.

sign/4 takes ordered header pairs, nonempty payload bytes, an algorithm-bound KeyHandle or Policy.signer, and only timeout: milliseconds (default 5,000; 1–300,000). Protected headers use compact JSON: top-level members keep caller order, and nested JSON objects are serialized in map order. Callers needing exact protected bytes use sign_protected/4. No received header is serialized again.

sign_protected/4 accepts caller-serialized protected JSON bytes without reserialization, with the same bounds and header rejections as Header.json/1. Payload, signer, timeout, and compact-output bounds match sign/4.

verify/2 takes a map containing exactly :algorithms (nonempty unique list of the eight Crypto JWS names), :timeout (1–300,000), and :key_resolver. The arity-one resolver receives %{algorithm: wire_name, header: map} and returns {:ok, %{algorithm: same_wire_name, key: PublicKey_or_verify_fun}} or :error. A verification function receives ({:jws, name}, base, signature); HMAC secrets remain inside that function's custody. All callbacks use the custody worker and an absolute operation deadline. kid and x5c are only untrusted header data; they establish no key trust or network permission.

Returns {:ok, compact} / {:ok, Result} or {:error, JOSE.Error}. Empty payloads reject as :detached_payload. Cryptographic validity supplies no principal, claims validation, freshness, replay protection, or authorization.

Summary

Functions

sign(header, payload, signer, opts \\ [])

sign_protected(protected_json, payload, signer, opts \\ [])

@spec sign_protected(
  binary(),
  binary(),
  RequestSeal.KeyHandle.t() | RequestSeal.Policy.signer(),
  keyword()
) :: {:ok, binary()} | {:error, RequestSeal.JOSE.Error.t()}

Sign caller-serialized protected JSON bytes without reserialization.

verify(compact, policy)

@spec verify(binary(), map()) ::
  {:ok, RequestSeal.JOSE.JWS.Result.t()} | {:error, RequestSeal.JOSE.Error.t()}