bsv-sdk 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5d32b117209fc6509e5020811725c5b5bb5e776c57fbd0f3cb0afa8cf3cc12ca
-  data.tar.gz: 2fa913c8e3fe270b53a1748e2ff4bdb8055945b625a9e3075eb293b78d581fe4
+  metadata.gz: e6f6657530a3e07510c21eeb919dd276a99b680a825b1d63c8e3c05731f36107
+  data.tar.gz: 0e44275e673ea30e56d4996d1f21e98e8bb22803815da60ab1f32fefcc61b327
 SHA512:
-  metadata.gz: 82e8ca0cf9e266d7c80fe8be42be40450e5a3495db083f90aa098aaf7ff0186ecc4a63b3a1efd9b7447738d857b930f655be291ad098a83ef7a6d0095df0b4d0
-  data.tar.gz: 103b3246361a57c3b1161c789c097c147b6c7070781094587f59bdee6caf3141bb5b22934a89e1bfdd4e514b4f45eb2edd1ae218fc92f23e2d520a3a56f72113
+  metadata.gz: 1e3bbb1cf676054dbf64cfcb94d3edd33e290f9d64734ec828ed1673b97f65ddb25b83e087e6e592ca036d1699a4ded46c974491f6a828b975b2c739e57e214e
+  data.tar.gz: 0de23da3bb0755d7dcf515f75638286479828c6dac0957532aedbfe28abad6bf8efee8c13b8092e5d05826559fdb16f7c102b84c242885b089022f90b638de05

data/CHANGELOG.md

@@ -5,6 +5,36 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2026-04-04
+
+### Added
+
+#### Overlay
+
+- **SHIP/SLAP overlay services** — `BSV::Overlay` module for topic-based transaction broadcasting and service discovery.
+  - `TopicBroadcaster` (aliased as `SHIPBroadcaster`) — broadcasts tagged BEEF to topic-interested hosts with configurable acknowledgement modes (all/any/specific hosts) and STEAK response parsing.
+  - `LookupResolver` — discovers competent hosts via SLAP trackers, queries in parallel, aggregates and deduplicates results. TTL-based host caching.
+  - `HostReputationTracker` — EWMA latency scoring with exponential backoff, DNS error escalation, thread-safe. Optional persistence via injectable store adapter.
+  - `AdminTokenTemplate` — decode/lock/unlock for SHIP/SLAP advertisement PushDrop tokens with BRC-42 wallet key derivation.
+  - Abstract base classes (`LookupFacilitator`, `BroadcastFacilitator`) with default HTTPS implementations — all dependencies injectable via constructor.
+  - SSRF protection for SLAP-discovered domains (private/loopback IP rejection).
+
+#### Identity
+
+- **Identity client** — `BSV::Identity` module for certificate-based identity resolution and publication.
+  - `Client` — resolve identities by key or attributes, publicly reveal certificate fields on-chain, revoke revelations. All overlay dependencies injectable.
+  - `IdentityParser` — converts identity certificates to `DisplayableIdentity`, handling all 9 known types (xCert, discordCert, phoneCert, emailCert, identiCert, registrant, coolCert, anyone, self) plus generic field-name heuristic fallback.
+  - Types: `DisplayableIdentity`, `IdentityCertificate`, `CertifierInfo`, `ClientOptions` with cross-SDK constant alignment.
+  - Certificate verifier injectable with safe-by-default (raises `NotImplementedError`).
+
+#### Script
+
+- **PushDropTemplate** — reusable wallet-aware PushDrop template with BRC-42 key derivation, optional ECDSA field signing, and P2PKH lock/unlock. Used by Identity client, reusable for ContactsManager and other PushDrop-based features.
+
+### Fixed
+
+- `ProtoWallet` parameter name mismatch: `_originator:` → `originator:` to match the `WalletInterface` contract.
+
 ## [0.4.0] - 2026-04-01
 
 ### Added

data/lib/bsv/identity/client.rb

@@ -0,0 +1,353 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module BSV
+  module Identity
+    # Client for resolving and publishing identity information on the BSV overlay network.
+    #
+    # Wraps wallet discovery and overlay broadcasting to provide a high-level
+    # interface for the BSV Identity protocol:
+    #
+    # - Resolve identities by key or attributes via {#resolve_by_identity_key} and
+    #   {#resolve_by_attributes}.
+    # - Publicly reveal certificate fields on-chain via {#publicly_reveal_attributes}.
+    # - Revoke an existing revelation via {#revoke_certificate_revelation}.
+    #
+    # All overlay dependencies (broadcaster, resolver) are injectable for testing.
+    #
+    # @example Resolve an identity
+    #   client = BSV::Identity::Client.new(wallet: my_wallet)
+    #   identities = client.resolve_by_identity_key(identity_key: pubkey_hex)
+    #
+    # @example Publicly reveal certificate fields
+    #   client = BSV::Identity::Client.new(wallet: my_wallet, broadcaster: my_broadcaster)
+    #   result = client.publicly_reveal_attributes(certificate, fields_to_reveal: ['email'])
+    class Client
+      # Default certificate verifier — raises NotImplementedError because certificate
+      # verification depends on BSV::Auth::Certificate, which is a separate HLR.
+      DEFAULT_VERIFIER = lambda do |_certificate|
+        raise NotImplementedError,
+              'Certificate verification requires BSV::Auth::Certificate (not yet implemented)'
+      end
+
+      # @param wallet [#discover_by_identity_key, #discover_by_attributes,
+      #   #prove_certificate, #create_action, #get_network] BRC-100 wallet interface
+      # @param options [ClientOptions, nil] identity protocol options (default: ClientOptions::DEFAULT)
+      # @param originator [String, nil] optional FQDN of the originating application
+      # @param certificate_verifier [#call, nil] callable that verifies a certificate;
+      #   defaults to a lambda that raises NotImplementedError
+      # @param broadcaster [BSV::Overlay::TopicBroadcaster, nil] injectable broadcaster;
+      #   built from the wallet's network preset when nil
+      # @param resolver [BSV::Overlay::LookupResolver, nil] injectable lookup resolver;
+      #   built from the wallet's network preset when nil
+      def initialize(
+        wallet:,
+        options: nil,
+        originator: nil,
+        certificate_verifier: nil,
+        broadcaster: nil,
+        resolver: nil
+      )
+        @wallet               = wallet
+        @options              = options || default_options
+        @originator           = originator
+        @certificate_verifier = certificate_verifier || DEFAULT_VERIFIER
+        @broadcaster          = broadcaster
+        @resolver             = resolver
+      end
+
+      # Resolves displayable identities issued to a given identity key.
+      #
+      # Delegates to the wallet's +discover_by_identity_key+ and maps each
+      # returned certificate through {IdentityParser.parse}.
+      #
+      # @param identity_key [String] compressed public key hex
+      # @param limit [Integer, nil] maximum number of certificates to return
+      # @param offset [Integer, nil] number of certificates to skip
+      # @return [Array<DisplayableIdentity>]
+      def resolve_by_identity_key(identity_key:, limit: nil, offset: nil)
+        args = { identity_key: identity_key }
+        args[:limit]  = limit  unless limit.nil?
+        args[:offset] = offset unless offset.nil?
+
+        result = @wallet.discover_by_identity_key(args, originator: @originator)
+        parse_certificates(result)
+      end
+
+      # Resolves displayable identities matching specific certificate attribute values.
+      #
+      # Delegates to the wallet's +discover_by_attributes+ and maps each
+      # returned certificate through {IdentityParser.parse}.
+      #
+      # @param attributes [Hash] field name/value pairs to match
+      # @param limit [Integer, nil] maximum number of certificates to return
+      # @param offset [Integer, nil] number of certificates to skip
+      # @return [Array<DisplayableIdentity>]
+      def resolve_by_attributes(attributes:, limit: nil, offset: nil)
+        args = { attributes: attributes }
+        args[:limit]  = limit  unless limit.nil?
+        args[:offset] = offset unless offset.nil?
+
+        result = @wallet.discover_by_attributes(args, originator: @originator)
+        parse_certificates(result)
+      end
+
+      # Publicly reveals selected fields from a certificate by creating an
+      # on-chain identity token and broadcasting it to the overlay network.
+      #
+      # The certificate is first optionally verified via the injected verifier,
+      # then the wallet proves the selected fields to the "anyone" verifier
+      # (PrivateKey(1) public key). A PushDrop locking script is constructed from
+      # the certificate JSON plus keyring, and the resulting transaction is
+      # broadcast to +tm_identity+.
+      #
+      # @param certificate [Hash] wallet certificate hash
+      # @param fields_to_reveal [Array<String>] field names to include in the revelation
+      # @return [BSV::Overlay::OverlayBroadcastResult]
+      # @raise [ArgumentError] if the certificate has no fields or fields_to_reveal is empty
+      # @raise [RuntimeError] if certificate verification fails or create_action returns no tx
+      def publicly_reveal_attributes(certificate, fields_to_reveal:)
+        fields = certificate[:fields] || certificate['fields'] || {}
+        raise ArgumentError, 'Public reveal failed: Certificate has no fields to reveal!' if fields.empty?
+        raise ArgumentError, 'Public reveal failed: You must reveal at least one field!' if fields_to_reveal.empty?
+
+        verify_certificate(certificate)
+
+        # Prove the certificate to the "anyone" verifier (PrivateKey(1) public key)
+        anyone_pubkey = BSV::Script::PushDropTemplate::GENERATOR_PUBKEY_HEX
+        prove_result  = @wallet.prove_certificate(
+          { certificate: certificate, fields_to_reveal: fields_to_reveal, verifier: anyone_pubkey },
+          originator: @originator
+        )
+        keyring = prove_result[:keyring_for_verifier]
+
+        # Build the PushDrop payload with ONLY the revealed fields — never
+        # broadcast the full certificate (encrypted values for unrevealed
+        # fields must not be written on-chain).
+        revealed_fields = fields_to_reveal.each_with_object({}) do |name, h|
+          h[name] = fields[name.to_s] || fields[name.to_sym]
+        end
+
+        payload = JSON.generate(
+          type: certificate[:type] || certificate['type'],
+          serialNumber: certificate[:serial_number] || certificate['serial_number'] || certificate[:serialNumber] || certificate['serialNumber'],
+          subject: certificate[:subject] || certificate['subject'],
+          certifier: certificate[:certifier] || certificate['certifier'],
+          revocationOutpoint: certificate[:revocation_outpoint] || certificate['revocation_outpoint'] || certificate[:revocationOutpoint] || certificate['revocationOutpoint'],
+          fields: revealed_fields,
+          keyring: keyring
+        )
+
+        # Construct the locking script via PushDropTemplate
+        template = BSV::Script::PushDropTemplate.new(wallet: @wallet, originator: @originator)
+        locking_script = template.lock(
+          fields: [payload],
+          protocol_id: @options.protocol_id,
+          key_id: @options.key_id,
+          counterparty: 'anyone'
+        )
+
+        # Create the transaction
+        create_result = @wallet.create_action(
+          {
+            description: 'Create a new Identity Token',
+            outputs: [
+              {
+                satoshis: @options.token_amount,
+                locking_script: locking_script.to_hex,
+                output_description: 'Identity Token'
+              }
+            ],
+            options: { randomize_outputs: false }
+          },
+          originator: @originator
+        )
+
+        raise 'Public reveal failed: failed to create action!' if create_result[:tx].nil?
+
+        tx = BSV::Transaction::Transaction.from_beef(create_result[:tx])
+        broadcaster_for_action.broadcast(tx)
+      end
+
+      # Revokes a publicly revealed certificate by spending the identity token.
+      #
+      # Queries the +ls_identity+ lookup service for the revelation output identified
+      # by +serial_number+, then creates a spending transaction via the wallet and
+      # broadcasts it to +tm_identity+.
+      #
+      # @param serial_number [String] Base64 serial number of the certificate revelation to revoke
+      # @return [void]
+      # @raise [RuntimeError] if the revelation cannot be found or the transaction cannot be created
+      def revoke_certificate_revelation(serial_number)
+        question = BSV::Overlay::LookupQuestion.new(
+          service: Constants::SERVICE,
+          query: { serial_number: serial_number }
+        )
+        answer = resolver_for_action.query(question)
+
+        raise 'Revoke failed: could not find revelation output' unless answer.type == 'output-list'
+        raise 'Revoke failed: no outputs found for serial number' if answer.outputs.empty?
+
+        output     = answer.outputs.first
+        beef_bytes = output['beef'] || output[:beef]
+        raise 'Revoke failed: overlay response missing BEEF data' unless beef_bytes
+
+        raw_idx = output['outputIndex'] || output[:output_index]
+        raise 'Revoke failed: overlay response missing outputIndex' if raw_idx.nil?
+
+        output_idx = raw_idx.to_i
+        raise 'Revoke failed: invalid outputIndex from overlay' if output_idx.negative?
+
+        beef = BSV::Transaction::Beef.from_binary(beef_bytes)
+        tx   = beef.transactions.last&.transaction
+        raise 'Revoke failed: no transaction found in BEEF' unless tx
+        raise 'Revoke failed: outputIndex out of range' if output_idx >= tx.outputs.length
+        txid    = tx.txid_hex
+        outpoint = "#{txid}.#{output_idx}"
+
+        # Create a spending transaction; use unlocking_script_length so the wallet
+        # produces a signable transaction that can then be signed and broadcast.
+        create_result = @wallet.create_action(
+          {
+            description: 'Spend certificate revelation token',
+            input_beef: beef_bytes,
+            inputs: [
+              {
+                input_description: 'Revelation token',
+                outpoint: outpoint,
+                unlocking_script_length: BSV::Script::PushDropTemplate::Unlocker::ESTIMATED_LENGTH
+              }
+            ],
+            options: { randomize_outputs: false, no_send: true }
+          },
+          originator: @originator
+        )
+
+        raise 'Revoke failed: failed to create signable transaction' if create_result[:signable_transaction].nil?
+
+        signable = create_result[:signable_transaction]
+        partial_tx = BSV::Transaction::Transaction.from_beef(signable[:tx])
+
+        # Unlock via PushDrop
+        template = BSV::Script::PushDropTemplate.new(wallet: @wallet, originator: @originator)
+        unlocker = template.unlock(
+          protocol_id: @options.protocol_id,
+          key_id: @options.key_id,
+          counterparty: 'anyone'
+        )
+        # Sign the first (and only) input in the spending transaction.
+        # output_idx is the index in the *source* tx; the spending tx input is always 0.
+        spending_input_idx = 0
+        unlocking_script = unlocker.sign(partial_tx, spending_input_idx)
+
+        sign_result = @wallet.sign_action(
+          {
+            reference: signable[:reference],
+            spends: { spending_input_idx => { unlocking_script: unlocking_script.to_hex } },
+            options: { no_send: true }
+          },
+          originator: @originator
+        )
+
+        raise 'Revoke failed: failed to sign transaction' if sign_result[:tx].nil?
+
+        signed_tx = BSV::Transaction::Transaction.from_beef(sign_result[:tx])
+        broadcaster_for_action.broadcast(signed_tx)
+      end
+
+      private
+
+      # Maps an array of raw certificate hashes to DisplayableIdentity objects.
+      #
+      # Each certificate hash (as returned by the wallet's discovery methods) is
+      # wrapped in an IdentityCertificate and parsed via IdentityParser.
+      #
+      # @param result [Hash, nil] wallet discovery result with :certificates key
+      # @return [Array<DisplayableIdentity>]
+      def parse_certificates(result)
+        certs = result && result[:certificates]
+        return [] if certs.nil? || certs.empty?
+
+        certs.map { |cert| IdentityParser.parse(wrap_certificate(cert)) }
+      end
+
+      # Wraps a raw certificate hash in an IdentityCertificate, extracting
+      # decrypted_fields and certifier_info where present.
+      #
+      # @param cert [Hash] raw certificate hash from the wallet
+      # @return [IdentityCertificate]
+      def wrap_certificate(cert)
+        decrypted   = cert[:decrypted_fields] || cert['decrypted_fields'] || {}
+        certifier_h = cert[:certifier_info]   || cert['certifier_info']   || {}
+
+        certifier_info = if certifier_h && !certifier_h.empty?
+                           CertifierInfo.new(
+                             name: certifier_h[:name] || certifier_h['name'] || '',
+                             icon_url: certifier_h[:icon_url] || certifier_h['icon_url']
+                           )
+                         end
+
+        IdentityCertificate.new(
+          certificate: cert,
+          decrypted_fields: decrypted,
+          certifier_info: certifier_info
+        )
+      end
+
+      # Calls the injected certificate verifier, wrapping any errors in a
+      # standardised RuntimeError message.
+      #
+      # @param certificate [Hash]
+      # @raise [RuntimeError] if verification fails
+      def verify_certificate(certificate)
+        @certificate_verifier.call(certificate)
+      rescue NotImplementedError
+        raise
+      rescue StandardError => e
+        raise "Public reveal failed: Certificate verification failed! (#{e.message})"
+      end
+
+      # Returns the broadcaster to use for overlay actions, building one from
+      # the wallet's network when no injectable broadcaster was provided.
+      #
+      # @return [BSV::Overlay::TopicBroadcaster]
+      def broadcaster_for_action
+        return @broadcaster if @broadcaster
+
+        network = wallet_network
+        BSV::Overlay::TopicBroadcaster.new(
+          [Constants::TOPIC],
+          network_preset: network
+        )
+      end
+
+      # Returns the lookup resolver to use for overlay queries, building one from
+      # the wallet's network when no injectable resolver was provided.
+      #
+      # @return [BSV::Overlay::LookupResolver]
+      def resolver_for_action
+        return @resolver if @resolver
+
+        network = wallet_network
+        BSV::Overlay::LookupResolver.new(network_preset: network)
+      end
+
+      # Queries the wallet for the current network and converts the string to a symbol.
+      #
+      # @return [Symbol] :mainnet or :testnet
+      def wallet_network
+        result = @wallet.get_network({}, originator: @originator)
+        net_str = result[:network] || result['network'] || 'mainnet'
+        net_str.to_sym
+      end
+
+      # Returns the default ClientOptions.
+      #
+      # @return [ClientOptions]
+      def default_options
+        ClientOptions::DEFAULT
+      end
+    end
+  end
+end

data/lib/bsv/identity/constants.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module BSV
+  module Identity
+    # Protocol constants and well-known values for the BSV Identity system.
+    module Constants
+      # Overlay topic name for identity transactions.
+      TOPIC = 'tm_identity'
+
+      # Lookup service identifier for identity queries.
+      SERVICE = 'ls_identity'
+
+      # Maps symbolic names to their Base64-encoded 32-byte certificate type identifiers.
+      #
+      # Values are byte-exact matches with the TS SDK (ts-sdk/src/identity/types/index.ts)
+      # and Go SDK (go-sdk/identity/types.go).
+      KNOWN_IDENTITY_TYPES = {
+        x_cert: 'vdDWvftf1H+5+ZprUw123kjHlywH+v20aPQTuXgMpNc=',
+        discord_cert: '2TgqRC35B1zehGmB21xveZNc7i5iqHc0uxMb+1NMPW4=',
+        phone_cert: 'mffUklUzxbHr65xLohn0hRL0Tq2GjW1GYF/OPfzqJ6A=',
+        email_cert: 'exOl3KM0dIJ04EW5pZgbZmPag6MdJXd3/a1enmUU/BA=',
+        identi_cert: 'z40BOInXkI8m7f/wBrv4MJ09bZfzZbTj2fJqCtONqCY=',
+        registrant: 'YoPsbfR6YQczjzPdHCoGC7nJsOdPQR50+SYqcWpJ0y0=',
+        cool_cert: 'AGfk/WrT1eBDXpz3mcw386Zww2HmqcIn3uY6x4Af1eo=',
+        anyone: 'mfkOMfLDQmrr3SBxBQ5WeE+6Hy3VJRFq6w4A5Ljtlis=',
+        self: 'Hkge6X5JRxt1cWXtHLCrSTg6dCVTxjQJJ48iOYd7n3g='
+      }.freeze
+
+      # Fallback identity used when no verified identity information is available.
+      DEFAULT_IDENTITY = DisplayableIdentity.new(
+        name: 'Unknown Identity',
+        avatar_url: 'XUUB8bbn9fEthk15Ge3zTQXypUShfC94vFjp65v7u5CQ8qkpxzst',
+        abbreviated_key: '',
+        identity_key: '',
+        badge_icon_url: 'XUUV39HVPkpmMzYNTx7rpKzJvXfeiVyQWg2vfSpjBAuhunTCA9uG',
+        badge_label: 'Not verified by anyone you trust.',
+        badge_click_url: 'https://projectbabbage.com/docs/unknown-identity'
+      ).freeze
+    end
+  end
+end