Skip to content

Class BSV::Auth::Certificate

Inherits: Object

Identity certificate as per the BRC-52 Wallet interface specification.

A certificate binds identity attributes (fields) to a subject public key, and is signed by a certifier. The binary serialisation format is shared across all BSV SDKs (Go, TypeScript, Python, Ruby) so that certificates produced by one SDK can be verified by another.

All field values are expected to be Base64-encoded encrypted strings. Signing and verification use BRC-42 key derivation:

  • Protocol: +[2, 'certificate signature']+
  • Key ID: +"#{type} #{serial_number}"+
  • Counterparty on sign: +'anyone'+ (default for create_signature)
  • Counterparty on verify: the certifier's compressed public key hex

Wallet parameters are duck-typed — any object responding to create_signature, verify_signature, and get_public_key is accepted. No direct dependency on BSV::Wallet::Client is introduced here.

  • @see https://hub.bsvblockchain.org/brc/wallet/0052 BRC-52

Constants

CERT_FIELD_ENC_PROTOCOL

Not documented.

CERT_SIG_PROTOCOL

Not documented.

Attributes

certifier [RW]

  • @return [String] compressed public key hex (66 characters)

fields [R]

  • @return [Hash] mapping field name strings to value strings

revocation_outpoint [R]

  • @return [String] outpoint string +"."+

serial_number [R]

  • @return [String] Base64 string decoding to 32 bytes

signature [RW]

  • @return [String, nil] DER-encoded signature as hex string, or nil if unsigned

subject [R]

  • @return [String] compressed public key hex (66 characters)

type [R]

  • @return [String] Base64 string decoding to 32 bytes

Public Class Methods

certificate_field_encryption_details(field_name, serial_number = nil)

Returns the protocol ID and key ID for certificate field encryption.

When serial_number is provided (for verifier keyring creation) the key ID is +"#{serial_number} #{field_name}"+. Without a serial number (for master keyring creation) the key ID is just the field_name. - @param field_name [String] name of the certificate field - @param serial_number [String, nil] certificate serial number (Base64) - @return [Hash] +{ protocol_id:, key_id: }+

from_binary(data)

Deserialise a certificate from its binary format.

When a signature is present in the trailing bytes, it is parsed via {BSV::Primitives::Signature.from_der} to ensure strict DER normalisation before being re-serialised as hex. - @param data [String] binary string - @raise [ArgumentError] - @return [Certificate]

from_hash(hash)

Construct a Certificate from a plain Hash.

Accepts both snake_case and camelCase key variants for each field so that wire-format hashes can be passed in directly. - @param hash [Hash] certificate data with snake_case or camelCase keys - @return [Certificate]

Public Instance Methods

initialize(type:, serial_number:, subject:, certifier:, revocation_outpoint:, fields:, signature: = 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 value strings
  • @param signature [String, nil] DER-encoded signature hex, or nil
  • @return [Certificate] a new instance of Certificate

sign(certifier_wallet)

Sign the certificate using the provided certifier wallet.

The certifier field is updated to the wallet's identity key before signing. Raises if the certificate is already signed. - @param certifier_wallet [#create_signature, #get_public_key] certifier wallet - @raise [ArgumentError] if the certificate already has a signature

to_binary(include_signature: = true)

Serialise the certificate into its binary format.

The binary format is byte-compatible with all other BSV SDK implementations. Fields are sorted lexicographically by name. - @param include_signature [Boolean] whether to append the signature bytes - @return [String] binary string

to_h()

Return the certificate as a plain Hash with snake_case keys.

JSON serialisation is simply cert.to_h.to_json. - @return [Hash]

verify(verifier_wallet = nil)

Verify the certificate's signature.

Uses a fresh +'anyone'+ Client as the verifier, which matches the TS SDK behaviour. If no signature is present, raises ArgumentError. - @param verifier_wallet [#verify_signature, nil] wallet to verify with; defaults to +BSV::Wallet::Client.new('anyone', storage: BSV::Wallet::Store::Memory.new)+ - @raise [ArgumentError] if the certificate has no signature - @return [Boolean] +true+ if the signature is valid