sd_jwt 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 15befa7b04cc0779c3a130c585c3f493ad0271c213a2022296038f6762749c0a
+  data.tar.gz: 27fae66b5f1c27040b5dd19bf5d5370d42f002b1feaaafc3fabb8b2d297b8b82
+SHA512:
+  metadata.gz: 5d573a2a3934b2e987c50167397a4db4a8637b13caf8793251d666b8dff2310dcedda3d4fe33cc371bb3cd47292500a3f6381f7caa40b299cb0eb9245bf32fe4
+  data.tar.gz: 11d3e8fc6c8f31fa03a8867819833eb18fa42369a09492523d58759050f59606df68113bdc5cd5e1b41e1171fcf5cd768b4608ceb1710b7cd69b72b189c63083

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0 - 2026-10-12
+
+Initial release.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,122 @@
+# SDJWT
+
+Issue, selectively present, and verify [RFC 9901](https://www.rfc-editor.org/rfc/rfc9901.html) SD-JWTs in Ruby. Signatures use [ruby-jwt](https://github.com/jwt/ruby-jwt) and OpenSSL; this gem implements disclosures, recursive claim processing, and holder key binding.
+
+## Install
+
+```ruby
+gem "sd_jwt", "~> 0.1.0"
+```
+
+Ruby 3.3 or later, JRuby, and TruffleRuby are tested in CI. Runtime dependencies are `json` (2.19.4 or later, including 3.x) and `jwt` (3.3.x). No other gem in the JSON formats family is required.
+
+## Issue and verify
+
+```ruby
+require "sd_jwt"
+
+issuer_key = OpenSSL::PKey::EC.generate("prime256v1")
+holder_key = OpenSSL::PKey::EC.generate("prime256v1")
+holder_jwk = JWT::JWK.new(holder_key).export.transform_keys(&:to_s)
+
+issuer = SDJWT::Issuer.new(signing_key: issuer_key, alg: "ES256")
+credential = issuer.issue(
+  { "iss" => "https://issuer.example", "exp" => Time.now.to_i + 3600,
+    "name" => "Example", "address" => { "street" => "Harbor Street", "city" => "Port" } },
+  disclose: ["/name", "/address", "/address/street"],
+  decoys: 2,
+  holder_jwk: holder_jwk,
+  header: { "typ" => "example+sd-jwt", "kid" => "key-1" }
+)
+
+held = SDJWT.parse(credential.to_s) # Unauthenticated holder-side parsing.
+presentation = held.present(
+  only: ["/name"],
+  key_binding: { key: holder_key, alg: "ES256", aud: "https://verifier.example", nonce: "transaction-nonce" }
+)
+
+verifier = SDJWT::Verifier.new(
+  algorithms: ["ES256"],
+  issuer_key: issuer_key, # Or ->(untrusted_header, untrusted_payload) { trusted_key_lookup(...) }
+  issuer: "https://issuer.example",
+  required_claims: ["iss", "exp", "cnf"],
+  require_key_binding: true,
+  audience: "https://verifier.example",
+  nonce: "transaction-nonce",
+  max_kb_age: 300
+)
+result = verifier.verify(presentation)
+result.claims                    # Immutable, authenticated disclosed claims.
+result.key_binding_verified      # true
+```
+
+Keys in claim and header hashes must be strings. Values must be JSON data. Generation rejects reserved `_sd`, `_sd_alg`, and `...` members. `SdJwt` is a compatibility alias for `SDJWT`.
+
+Use `token.disclosed_paths` to enumerate available disclosure paths. `present(only:)` automatically includes disclosed parents needed by a selected child. Selecting a parent includes its directly visible contents, but does not select separately hidden children. Array indices refer to the original issuer payload: hidden array entries disappear from the verified result. Selecting no paths sends no disclosures. Creating a new presentation removes an existing KB-JWT; pass `key_binding:` to bind the new presentation.
+
+`decoys:` adds that many digests to each object `_sd` array, including arrays within parent disclosures. It does not add dummy array elements. Digest arrays are sorted. Salts contain 128 random bits. The total number of issued disclosures and decoys is bounded by `max_disclosures`.
+
+## Supported scope
+
+| Feature | Support |
+| --- | --- |
+| RFC 9901 Compact, Flattened JSON, General JSON | Read, write, present, verify |
+| Object claims, array entries, recursive disclosure | Supported |
+| Unknown application claims and header parameters | Preserved |
+| Hashes | `sha-256` default; `sha-384` and `sha-512` require verifier opt-in |
+| Issuer signatures | ES256/384/512, RS256/384/512, PS256/384/512; HS256/384/512 only when explicitly configured |
+| Holder key binding | `cnf.jwk` with public EC or RSA keys, KB-JWT type/time/audience/nonce/presentation digest |
+| JSON duplicate names, non-finite values, invalid UTF-8 | Rejected with both json 2.x and 3.x |
+| SD-JWT VC / W3C VC profile rules, revocation, trust discovery | Application responsibility |
+| EdDSA, symmetric holder keys, other `cnf` methods, custom JOSE critical extensions, unencoded payloads | Unsupported |
+| CBOR SD-CWT | Unsupported |
+
+`none` is always rejected. Holder keys are P-256/P-384/P-521 or RSA with a 2048–8192 bit odd modulus and an odd public exponent of at least 3. RSA issuer keys also require at least 2048 bits and a valid public exponent. HMAC requires random secrets of at least 32/48/64 bytes for HS256/384/512; PEM, DER, and SSH asymmetric key encodings are rejected as HMAC secrets. Applications may restrict holder signature algorithms further with `key_binding_algorithms:`. Signing uses jwt's token API; JSON signatures, including unprotected `alg`, use its JWA implementation over the unchanged encoded input. PSS verification calls OpenSSL directly to enforce JOSE's exact salt length, which ruby-jwt's permissive PSS verification does not enforce. No signature primitive is implemented here.
+
+## JWS JSON
+
+```ruby
+flattened = credential.to_json(format: :flattened)
+general = credential.to_json(format: :general)
+verifier.verify(SDJWT.parse(flattened).present(only: ["/name"], key_binding: {
+  key: holder_key, alg: "ES256", aud: "https://verifier.example", nonce: "transaction-nonce"
+}))
+```
+
+General JSON verification requires **every signature** to pass. RFC 9901 section 8.3 places `disclosures` and `kb_jwt` only in the first signature's unprotected header; the same disclosure set is processed for all signatures, and key binding covers the first signature's Compact representation. Additional signatures are preserved when presenting. A multi-signature token must be written as General JSON. A token with other unprotected headers must remain JSON because Compact cannot retain those headers. Issuance creates one signature; externally co-signed General tokens are accepted.
+
+Unprotected headers are not trustworthy identity evidence. Even protected headers and payloads passed to a key resolver have not yet been authenticated. Restrict `iss`/`kid` resolution to an explicit trust configuration; never fetch arbitrary header URLs. `headers` contains the merged headers for each verified signature; use the original `signatures` representation to distinguish protected from unprotected metadata.
+
+## Verification policy and limits
+
+`Verifier.new` requires a nonempty signing algorithm allowlist. `required_claims:` defines validity claims that must survive disclosure; hidden `exp`, `aud`, or `cnf` claims cannot otherwise be detected. `issuer:` requires an exact issuer match. A present credential `aud` must match `audience:`; to require its presence, add `aud` to `required_claims`. `exp` and `nbf` are checked after disclosure reconstruction; `leeway:` defaults to zero.
+
+Set `require_key_binding: true` based on your application's policy, not on whether a KB-JWT happens to arrive. With it enabled, a nonempty `audience:` and `nonce:` are required, and `iat` must fall between the current time minus `max_kb_age` and the current time. Without it, any supplied KB-JWT is structurally parsed but does not establish holder authentication; `result.key_binding_verified` remains false. Nonce generation, transaction replay storage, key revocation, credential profile rules, and required `typ` values belong to the application.
+
+Default limits are 1 MiB serialized input, 1000 disclosures, nesting depth 32, and 16 General signatures. Configure `max_bytes:`, `max_disclosures:`, `max_depth:`, and `max_signatures:` on parsing/verifying; issuance accepts the first three. Verifying an existing `Token` reapplies the verifier's limits. Cryptographic inputs always use strict parsing; `strict: false` is rejected rather than downgrading errors to warnings.
+
+Failures use `SDJWT::ParseError`, `ValidationError` (with `pointer` for disclosure path failures), `ConversionError`, or `VerificationError`, all under `SDJWT::Error`. Library errors omit claim values and salts. Application callback errors remain the application's responsibility.
+
+## Development and reference data
+
+```sh
+bundle install
+bundle exec rake test
+COVERAGE=1 bundle exec rake test
+bundle exec rubocop
+bundle exec rbs -I sig validate
+bundle exec ruby script/benchmark.rb
+python3 -m venv tmp/interop-venv
+tmp/interop-venv/bin/python -m pip install --require-hashes -r script/python_requirements.txt
+bundle exec ruby script/interop.rb
+```
+
+Tests fetch RFC 9901 by a pinned SHA-256 into ignored `tmp/rfc/sources`, then extract all 57 source/artwork blocks and 87 fixed disclosure/digest pairs into ignored `tmp/rfc/fixtures`, with the source notices and Revised BSD notification. Nothing fetched is committed or packaged. The package includes only this project's MIT implementation, original protocol metadata, types, and documentation. `script/python_requirements.txt` pins the Python reference and dependency archive hashes; their source and license notices remain in the ignored virtual environment.
+
+Display line wrapping is removed inside encoded strings and token blocks. Original text and the extraction inventory are retained next to each fixture. Illustrative snippets with ellipses remain text. The section 8.3 General example uses two illustrative signatures that do not verify with the Appendix A.5 key; it is tested for structural preservation and disclosure reconstruction, with signature rejection explicitly checked. Generated two-key General tokens test successful all-signature verification. Issuance uses compact JSON, while RFC disclosures often contain spaces; original RFC disclosures and digests are checked byte-for-byte, and deterministic issuance is tested separately with compact encoding.
+
+Interoperability compares Python `sd-jwt` 0.10.4 in both directions for nested claims, array entries, decoys, holder presentations and key binding, plus all eight complete RFC tokens. Its older JSON serialization is not used as an oracle for RFC 9901's final JSON syntax. The OpenWallet Foundation JavaScript implementation was also consulted for current RFC coverage. RFC errata were checked on 2026-10-11; none were listed. `script/update_registry.rb` audits the IANA JWT claim registrations without importing registry documents into the package.
+
+For deterministic tests only, explicitly require `sd_jwt/testing` and wrap issuance in `SDJWT::Testing.with_salts([...])`. Never use supplied salts in production.
+
+See [SECURITY.md](SECURITY.md) for reporting and audit status. Released under the [MIT license](LICENSE.txt).

data/SECURITY.md

@@ -0,0 +1,14 @@
+# Security policy
+
+Report suspected vulnerabilities privately through [GitHub security advisories](https://github.com/ydah/sd_jwt/security/advisories/new).
+If private reporting is unavailable, email t.yudai92@gmail.com. Do not include live credentials, private keys, or personal disclosures in a public issue.
+
+Security fixes target the latest published release. Upgrade to the latest release before reporting an already resolved issue.
+
+`SDJWT.parse` and `Token#unverified_claims` do not authenticate credentials. Only consume trusted claims from `Verifier#verify`.
+The application must establish issuer trust, restrict algorithms, require the validity claims its profile needs, and decide whether holder key binding is mandatory.
+Use fresh unpredictable nonces, enforce one-time transaction use, keep signing keys out of logs, and validate the credential's profile and issuer-supplied metadata separately.
+
+No independent external human security audit has been completed for this initial release. Automated negative tests and interoperability checks do not replace that audit.
+
+An independent implementation review on 2026-10-11 added regression tests and fixes for asymmetric key encodings used as HMAC secrets, undersized HMAC/RSA keys, invalid RSA public exponents, and nonstandard RSA-PSS salt lengths. It also checked disclosure reconstruction, transaction binding, time boundaries, and parser limits. This review did not audit OpenSSL or ruby-jwt internals, perform timing analysis, or assess an application's issuer trust and replay controls.

data/data/protocol.yml

@@ -0,0 +1,14 @@
+# Original protocol metadata; no RFC text, examples, or grammars are included.
+claims:
+  _sd: {type: array_of_digest_strings, section: '4.2.4.1'}
+  '...': {type: digest_string, section: '4.2.4.2'}
+  _sd_alg: {type: hash_algorithm, section: '4.1.1'}
+  sd_hash: {type: presentation_digest, section: '4.3'}
+hash_algorithms:
+  sha-256: {bytes: 32, default: true}
+  sha-384: {bytes: 48, default: false}
+  sha-512: {bytes: 64, default: false}
+media_types:
+  - application/sd-jwt
+  - application/sd-jwt+json
+  - application/kb+jwt

data/lib/sd_jwt/codec.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "openssl"
+require "jwt"
+require "set" # rubocop:disable Lint/RedundantRequireStatement -- Required by Ruby 3.3 and 3.4.
+
+module SDJWT
+  module Codec
+    MAX_BYTES = 1_048_576
+    MAX_DEPTH = 32
+    MAX_DISCLOSURES = 1000
+    MAX_SIGNATURES = 16
+    ALGORITHMS = %w[ES256 ES384 ES512 RS256 RS384 RS512 PS256 PS384 PS512 HS256 HS384 HS512].freeze
+
+    # Keep JSON generation local: some TruffleRuby versions round Float#to_s incorrectly.
+    class SigningToken < JWT::Token
+      def encoded_header
+        @encoded_header ||= Codec.encode(Codec.generate(header))
+      end
+
+      def encoded_payload
+        @encoded_payload ||= Codec.encode(Codec.generate(payload))
+      end
+    end
+
+    module_function
+
+    def limits(max_bytes:, max_depth:, max_disclosures:, max_signatures: MAX_SIGNATURES)
+      values = { max_bytes: max_bytes, max_depth: max_depth, max_disclosures: max_disclosures, max_signatures: max_signatures }
+      raise ArgumentError, "Limits must be positive integers" unless values.values.all? { |n| n.is_a?(Integer) && n.positive? }
+
+      values.freeze
+    end
+
+    def parse_json(source, max_depth: MAX_DEPTH)
+      raise ParseError, "JSON input must be a string" unless source.is_a?(String)
+
+      source = source.dup.force_encoding(Encoding::UTF_8)
+      raise ParseError, "Invalid UTF-8 JSON" unless source.valid_encoding?
+
+      value = JSON.parse(source, allow_duplicate_key: false, max_nesting: max_depth, allow_nan: false)
+      copy(value, max_depth: max_depth)
+    rescue JSON::ParserError, ValidationError, EncodingError, ArgumentError
+      raise ParseError, "Invalid JSON", cause: nil
+    end
+
+    def generate(value)
+      JSON.generate(precise(value), max_nesting: false, allow_nan: false)
+    rescue JSON::GeneratorError, EncodingError, ArgumentError
+      raise ValidationError, "Invalid JSON value", cause: nil
+    end
+
+    def precise(value)
+      case value
+      when Hash then value.transform_values { |item| precise(item) }
+      when Array then value.map { |item| precise(item) }
+      when Float
+        raise ValidationError, "Non-finite number" unless value.finite?
+        return value unless RUBY_ENGINE == "truffleruby"
+
+        number = format("%.17g", value)
+        number += ".0" unless number.match?(/[.eE]/)
+        JSON::Fragment.new(number)
+      else value
+      end
+    end
+
+    def copy(value, max_depth: MAX_DEPTH, depth: 0)
+      raise ValidationError, "Nesting limit exceeded" if depth > max_depth
+
+      case value
+      when Hash
+        raise ValidationError, "JSON members must be strings" unless value.keys.all?(String)
+
+        value.to_h { |key, item| [key.dup, copy(item, max_depth: max_depth, depth: depth + 1)] }
+      when Array then value.map { |item| copy(item, max_depth: max_depth, depth: depth + 1) }
+      when String
+        raise ValidationError, "Invalid UTF-8 string" unless value.encoding == Encoding::UTF_8 || value.ascii_only?
+        raise ValidationError, "Invalid UTF-8 string" unless value.valid_encoding?
+
+        value.dup
+      when Float
+        raise ValidationError, "Non-finite number" unless value.finite?
+
+        value
+      when Integer, TrueClass, FalseClass, NilClass then value
+      else raise ValidationError, "Unsupported JSON value"
+      end
+    end
+
+    def freeze_tree(value)
+      case value
+      when Hash then value.each do |key, item|
+        key.freeze
+        freeze_tree(item)
+      end
+      when Array then value.each { |item| freeze_tree(item) }
+      end
+      value.freeze
+    end
+
+    def encode(bytes)
+      Base64.urlsafe_encode64(bytes, padding: false)
+    end
+
+    def decode(value, empty: false)
+      raise ParseError, "Invalid base64url" unless value.is_a?(String) && value.match?(/\A[A-Za-z0-9_-]*\z/) && (empty || !value.empty?)
+
+      decoded = Base64.urlsafe_decode64(value)
+      raise ParseError, "Noncanonical base64url" unless encode(decoded) == value
+
+      decoded
+    rescue ArgumentError
+      raise ParseError, "Invalid base64url", cause: nil
+    end
+
+    def signing_algorithm(algorithm)
+      raise ValidationError, "Unsupported signing algorithm" unless ALGORITHMS.include?(algorithm)
+
+      algorithm
+    end
+
+    def allowlist(algorithms)
+      unless algorithms.is_a?(Array) && !algorithms.empty? && algorithms.all? { |alg| ALGORITHMS.include?(alg) }
+        raise ArgumentError, "A nonempty supported signing algorithm allowlist is required"
+      end
+
+      algorithms.map(&:dup).each(&:freeze).freeze
+    end
+
+    def validate_claim_types(claims)
+      %w[iss sub jti].each do |name|
+        raise ValidationError, "Invalid registered claim type" if claims.key?(name) && !claims[name].is_a?(String)
+      end
+      %w[exp nbf iat].each do |name|
+        next unless claims.key?(name)
+
+        value = claims[name]
+        raise ValidationError, "Invalid NumericDate claim" unless value.is_a?(Numeric) && value.finite?
+      end
+      if claims.key?("aud")
+        audience = claims["aud"]
+        unless audience.is_a?(String) || (audience.is_a?(Array) && !audience.empty? && audience.all?(String))
+          raise ValidationError, "Invalid audience claim type"
+        end
+      end
+      raise ValidationError, "Invalid confirmation claim type" if claims.key?("cnf") && !claims["cnf"].is_a?(Hash)
+    end
+
+    def sign(payload, key:, algorithm:, header: {})
+      signing_algorithm(algorithm)
+      validate_hmac_key(key, algorithm)
+      validate_rsa_key(key.is_a?(JWT::JWK::KeyBase) ? key.verify_key : key) if algorithm.start_with?("RS", "PS")
+      raise ValidationError, "Protected header algorithm mismatch" if header.key?("alg") && header["alg"] != algorithm
+      raise ValidationError, "Unsupported protected header" if header.keys.intersect?(%w[crit b64 disclosures kb_jwt])
+
+      token = SigningToken.new(payload: payload, header: header)
+      token.sign!(key: key, algorithm: algorithm)
+      token.jwt
+    rescue JWT::EncodeError, JWT::DecodeError, OpenSSL::OpenSSLError, ArgumentError
+      raise ValidationError, "Signing failed", cause: nil
+    end
+
+    def validate_hmac_key(key, algorithm)
+      return unless algorithm.start_with?("HS")
+
+      secret = key.is_a?(JWT::JWK::KeyBase) ? key.verify_key : key
+      minimum = algorithm.delete_prefix("HS").to_i / 8
+      raise ValidationError, "HMAC requires a secret at least as long as the hash output" unless secret.is_a?(String) && secret.bytesize >= minimum
+      raise ValidationError, "Asymmetric key material cannot be an HMAC secret" if asymmetric_key_material?(secret)
+    end
+
+    def asymmetric_key_material?(secret)
+      return true if secret.b.include?("-----BEGIN ") || secret.b.match?(/\A\s*(?:ssh-|ecdsa-sha2-)/n)
+
+      # Also recognize DER encodings. Supplying a password prevents terminal prompts.
+      OpenSSL::PKey.read(secret, "")
+      true
+    rescue OpenSSL::OpenSSLError, ArgumentError
+      false
+    end
+
+    def validate_rsa_key(key)
+      return if key.is_a?(OpenSSL::PKey::RSA) && key.n.num_bits >= 2048 && key.n.to_i.odd? && key.e.to_i >= 3 && key.e.to_i.odd? && key.e < key.n
+
+      raise ValidationError, "RSA requires a valid public exponent and an odd modulus of at least 2048 bits"
+    end
+
+    def jwt_parts(compact, max_depth: MAX_DEPTH)
+      raise ParseError, "Invalid JWS" unless compact.is_a?(String)
+
+      parts = compact.split(".", -1)
+      raise ParseError, "Invalid JWS" unless parts.length == 3
+
+      header = parts[0].empty? ? {} : parse_json(decode(parts[0]), max_depth: max_depth)
+      payload = parse_json(decode(parts[1]), max_depth: max_depth)
+      decode(parts[2])
+      raise ParseError, "JWS header and payload must be objects" unless header.is_a?(Hash) && payload.is_a?(Hash)
+
+      [parts, header, payload]
+    end
+
+    def verify_signature(compact, key:, algorithms:, unprotected: {}, max_depth: MAX_DEPTH)
+      parts, protected_header, payload = jwt_parts(compact, max_depth: max_depth)
+      raise VerificationError, "Overlapping JWS headers" if protected_header.keys.intersect?(unprotected.keys)
+      raise VerificationError, "Unsupported critical or unencoded JWS" if protected_header.keys.intersect?(%w[crit b64])
+      raise VerificationError, "Unsupported unprotected security header" if unprotected.keys.intersect?(%w[crit b64])
+
+      header = protected_header.merge(unprotected)
+      algorithm = header["alg"]
+      raise VerificationError, "Signing algorithm is not allowed" unless algorithms.include?(algorithm)
+      raise VerificationError, "Missing verification key" if key.nil?
+
+      if key.is_a?(JWT::JWK::KeyBase)
+        raise VerificationError, "Verification JWK algorithm mismatch" if key[:alg] && key[:alg] != algorithm
+        raise VerificationError, "Verification JWK use mismatch" if key[:use] && key[:use] != "sig"
+        if key[:key_ops] && (!key[:key_ops].is_a?(Array) || !key[:key_ops].include?("verify"))
+          raise VerificationError, "Verification JWK does not permit verification"
+        end
+
+        key = key.verify_key
+      end
+      validate_hmac_key(key, algorithm)
+      validate_rsa_key(key) if algorithm.start_with?("RS", "PS")
+      signature = decode(parts[2])
+      expected_bytes = { "ES256" => 64, "ES384" => 96, "ES512" => 132 }[algorithm]
+      raise VerificationError, "Invalid ECDSA signature length" if expected_bytes && signature.bytesize != expected_bytes
+
+      data = parts.first(2).join(".")
+      valid = if algorithm.start_with?("PS")
+                # ruby-jwt accepts arbitrary PSS salt lengths; JOSE requires the hash length.
+                digest = algorithm.sub("PS", "SHA")
+                key.verify_pss(digest, signature, data, salt_length: :digest, mgf1_hash: digest)
+              else
+                verifiers = JWT::JWA.create_verifiers(algorithms: [algorithm], keys: [key], preferred_algorithm: algorithm)
+                verifiers.any? { |verifier| verifier.verify(data: data, signature: signature) }
+              end
+      raise VerificationError, "Invalid signature" unless valid
+
+      [payload, header]
+    rescue JWT::DecodeError, JWT::EncodeError, OpenSSL::OpenSSLError, ArgumentError, TypeError, NoMethodError
+      raise VerificationError, "Signature verification failed", cause: nil
+    end
+  end
+end

data/lib/sd_jwt/disclosure.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module SDJWT
+  class Disclosure
+    attr_reader :encoded, :salt, :name, :value
+
+    def self.parse(encoded, max_depth: Codec::MAX_DEPTH)
+      raw = Codec.parse_json(Codec.decode(encoded), max_depth: max_depth)
+      new(raw, encoded: encoded, max_depth: max_depth)
+    end
+
+    def initialize(raw, encoded: nil, max_depth: Codec::MAX_DEPTH)
+      raise ParseError, "Invalid disclosure structure" unless raw.is_a?(Array) && [2, 3].include?(raw.length) && raw[0].is_a?(String)
+      raise ParseError, "Invalid disclosure claim name" if raw.length == 3 && (!raw[1].is_a?(String) || %w[_sd ...].include?(raw[1]))
+
+      raw = Codec.copy(raw, max_depth: max_depth)
+      @salt = raw[0].freeze
+      @name = raw.length == 3 ? raw[1].freeze : nil
+      @value = Codec.freeze_tree(raw.last)
+      @encoded = (encoded || Codec.encode(Codec.generate(raw))).dup.freeze
+      freeze
+    end
+
+    def array_element?
+      name.nil?
+    end
+
+    def digest(algorithm = "sha-256")
+      HashAlg.digest(encoded, algorithm)
+    end
+
+    def to_s
+      encoded
+    end
+  end
+end

data/lib/sd_jwt/errors.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module SDJWT
+  class Error < StandardError; end
+  class ParseError < Error; end
+
+  class ValidationError < Error
+    attr_reader :pointer
+
+    def initialize(message, pointer: "")
+      @pointer = pointer
+      super(message)
+    end
+  end
+
+  class ConversionError < Error; end
+  class VerificationError < Error; end
+end

data/lib/sd_jwt/hash_alg.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module SDJWT
+  module HashAlg
+    ALGORITHMS = { "sha-256" => "SHA256", "sha-384" => "SHA384", "sha-512" => "SHA512" }.freeze
+
+    module_function
+
+    def validate(name, allowed: ALGORITHMS.keys)
+      raise ValidationError, "Unsupported disclosure hash algorithm" unless ALGORITHMS.key?(name) && allowed.include?(name)
+
+      name
+    end
+
+    def digest(value, algorithm = "sha-256")
+      validate(algorithm)
+      raise ValidationError, "Digest input must be ASCII" unless value.is_a?(String) && value.ascii_only?
+
+      Codec.encode(OpenSSL::Digest.digest(ALGORITHMS.fetch(algorithm), value))
+    end
+  end
+end

data/lib/sd_jwt/issuer.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module SDJWT
+  class Issuer
+    def initialize(signing_key:, alg: "ES256", hash_alg: "sha-256", max_bytes: Codec::MAX_BYTES,
+                   max_depth: Codec::MAX_DEPTH, max_disclosures: Codec::MAX_DISCLOSURES)
+      @key = signing_key
+      @algorithm = Codec.signing_algorithm(alg)
+      @hash_algorithm = HashAlg.validate(hash_alg)
+      @limits = Codec.limits(max_bytes: max_bytes, max_depth: max_depth, max_disclosures: max_disclosures)
+    end
+
+    def issue(claims, disclose: [], decoys: 0, holder_jwk: nil, header: {})
+      raise ValidationError, "Claims and header must be objects" unless claims.is_a?(Hash) && header.is_a?(Hash)
+      raise ArgumentError, "Decoys must be a nonnegative integer" unless decoys.is_a?(Integer) && decoys >= 0
+      unless disclose.is_a?(Array) && disclose.length <= @limits[:max_disclosures] && decoys <= @limits[:max_disclosures]
+        raise ValidationError, "Disclosure limit exceeded"
+      end
+      raise ValidationError, "Duplicate disclosure path" unless disclose.uniq.length == disclose.length
+
+      payload = Codec.copy(claims, max_depth: @limits[:max_depth])
+      reject_reserved(payload)
+      Codec.validate_claim_types(payload)
+
+      if holder_jwk
+        raise ValidationError, "Confirmation claim already exists" if payload.key?("cnf")
+
+        payload["cnf"] = { "jwk" => KeyBinding.public_jwk(holder_jwk) }
+      end
+      finalized = Set.new
+      object_parents = disclose.map { |path| Pointer.locate(payload, path).first }.grep(Hash).map(&:object_id).uniq
+      raise ValidationError, "Disclosure and decoy limit exceeded" if disclose.length + (decoys * object_parents.length) > @limits[:max_disclosures]
+
+      disclosures = disclose.sort_by { |path| -Pointer.tokens(path).length }.map do |path|
+        parent, name = Pointer.locate(payload, path)
+        add_decoys(parent[name], decoys, finalized)
+        raw = parent.is_a?(Array) ? [salt, parent[name]] : [salt, name, parent.delete(name)]
+        disclosure = Disclosure.new(raw, max_depth: @limits[:max_depth] + 2)
+        digest = disclosure.digest(@hash_algorithm)
+        if parent.is_a?(Array)
+          parent[name] = { "..." => digest }
+        else
+          (parent["_sd"] ||= []) << digest
+        end
+        disclosure.encoded
+      end
+      add_decoys(payload, decoys, finalized)
+      payload["_sd_alg"] = @hash_algorithm
+      compact = Codec.sign(payload, key: @key, algorithm: @algorithm, header: Codec.copy(header))
+      SDJWT.parse(([compact] + disclosures + [""]).join("~"), **@limits)
+    end
+
+    private
+
+    def salt
+      if defined?(Testing) && Thread.current[:sd_jwt_test_salts]
+        return Thread.current[:sd_jwt_test_salts].shift || raise(ValidationError, "Test salts exhausted")
+      end
+
+      Codec.encode(SecureRandom.random_bytes(16))
+    end
+
+    def reject_reserved(value)
+      case value
+      when Hash
+        raise ValidationError, "Reserved claim name" if value.keys.intersect?(%w[_sd _sd_alg ...])
+
+        value.each_value { |item| reject_reserved(item) }
+      when Array then value.each { |item| reject_reserved(item) }
+      end
+    end
+
+    def add_decoys(value, count, finalized)
+      case value
+      when Hash
+        value.each_value { |item| add_decoys(item, count, finalized) }
+        return unless value.key?("_sd") && finalized.add?(value.object_id)
+
+        count.times { value["_sd"] << HashAlg.digest(Codec.encode(SecureRandom.random_bytes(32)), @hash_algorithm) }
+        value["_sd"].sort!
+      when Array then value.each { |item| add_decoys(item, count, finalized) }
+      end
+    end
+  end
+end