Skip to content

Class BSV::Auth::VerifiableCertificate

Inherits: BSV::Auth::Certificate

A Certificate subclass for selective field revelation on the verifier side.

VerifiableCertificate holds a verifier-specific keyring — a map from field names to Base64-encoded symmetric keys encrypted for the verifier. Calling {#decrypt_fields} decrypts each entry in the keyring using the verifier's wallet and then uses the recovered key to decrypt the corresponding field value from the base certificate.

Protocol details

Each keyring entry is decrypted via BRC-42 key derivation:

  • Protocol: +[2, 'certificate field encryption']+
  • Key ID: +"#{serial_number} #{field_name}"+
  • Counterparty: the certificate subject public key

Wallet parameters are duck-typed — any object responding to :decrypt is accepted. No direct dependency on BSV::Wallet::Client is introduced here.

  • @see BSV::Auth::Certificate base class
  • @see BSV::Auth::MasterCertificate for creating certificates and keyrings

Attributes

decrypted_fields [R]

  • @return [Hash, nil] field name → decrypted plaintext string, or nil before decryption

keyring [R]

  • @return [Hash] field name → Base64-encoded verifier-specific encrypted key

Public Class Methods

from_certificate(certificate, keyring)

Construct a VerifiableCertificate from a base Certificate and a keyring. - @param certificate [Certificate] any Certificate instance (or duck-typed object responding to +type+, +serial_number+, +subject+, +certifier+, +revocation_outpoint+, +fields+, +signature+) - @param keyring [Hash] field name → Base64-encoded verifier-specific encrypted key - @return [VerifiableCertificate]

from_hash(hash)

Construct a VerifiableCertificate from a plain Hash.

Accepts both snake_case and camelCase key variants. - @param hash [Hash] certificate data including +keyring+ and optional +decrypted_fields+ - @return [VerifiableCertificate]

Public Instance Methods

decrypt_fields(verifier_wallet, privileged: = false, privileged_reason: = nil)

Decrypt selectively revealed certificate fields using the verifier's wallet.

Algorithm: 1. Raises if keyring is nil or empty. 2. For each field in keyring: 1. Decrypts the encrypted revelation key via verifier_wallet.decrypt, using protocol +[2, 'certificate field encryption']+ and key_id +"#{serial_number} #{field_name}"+, counterparty = subject. 2. Uses the recovered bytes as a {BSV::Primitives::SymmetricKey}. 3. Decrypts the corresponding encrypted field value. 4. Stores the UTF-8 plaintext. 3. Caches and returns the decrypted fields hash. - @param verifier_wallet [#decrypt] wallet belonging to the verifier - @param privileged [Boolean] whether this is a privileged operation - @param privileged_reason [String, nil] reason for privileged access - @raise [ArgumentError] if +keyring+ is nil or empty - @raise [RuntimeError] if decryption fails for any field - @return [Hash] field name → decrypted plaintext string

initialize(type:, serial_number:, subject:, certifier:, revocation_outpoint:, fields:, keyring:, signature: = nil, decrypted_fields: = nil)

  • @param type [String] Base64 string (32 bytes decoded)
  • @param serial_number [String] Base64 string (32 bytes decoded)
  • @param subject [String] compressed public key hex
  • @param certifier [String] compressed public key hex
  • @param revocation_outpoint [String] +"."+
  • @param fields [Hash] field name strings to encrypted value strings (Base64)
  • @param keyring [Hash] field name strings to Base64-encoded verifier-specific encrypted keys
  • @param signature [String, nil] DER-encoded signature hex, or nil
  • @param decrypted_fields [Hash, nil] pre-populated decrypted fields, or nil
  • @return [VerifiableCertificate] a new instance of VerifiableCertificate

to_h()

Return the certificate as a plain Hash with snake_case keys, including keyring and decrypted_fields (if present). - @return [Hash]