opentrust 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1be8ac1901adb4eba6e169948dd6172743d816f582c73beb84a6665757cec2ab
-  data.tar.gz: d0f5877799fb975d2f9d34601bf86103d4f5109ce1e031e6b6daf3f6b745d4c4
+  metadata.gz: 810e3839ac5fe409bc140e8bf26e34bafaf795ee9f3cc5601f64d616c5774b60
+  data.tar.gz: 5c828d92c69579e6e191629ef860d0404179dd410f20b8c9f9aba13330c972c0
 SHA512:
-  metadata.gz: c0a3d367db5b5697fbf9de7618c6cb29d29e4ea5ddd3628f1aca17befa00812622a52e44ccbc498bbf07ca428d63467848f568e0a95098976f3436e353a9d81e
-  data.tar.gz: b416321fcf6e6c13fc299148d668dfdab3fbae2def6bc1671594f237c8012d8b5fb604210a5e12ca174eadd98f643947d998ab72dc39c8a90938104307bed34e
+  metadata.gz: 55bbf1b388e709db9e4d7676cd47eebdef55e06a2d9b0a0ab81beabd788b7a424f70e8b899c6e5a8f142f76e247d686eb06d71c918d921554e94a8b39b424cf9
+  data.tar.gz: 765c55288178d3c0780c981b8042e469fcbb0eef305c6e0d8a1319829c2f5098191a8bca61f46ff5e690a770d1be0f6b0a5ad57128750ef21300e73993492e68

data/README.md

@@ -21,7 +21,7 @@ result.notice          # keep this in front of anyone who sees the result
 result.checks_remaining
 
 client.lookup_many(%w[9876543210 9000000001])          # up to 100, all or nothing
-client.report(phone: "9876543210", reason_code: "cod_refusal", notes: "Refused 3 COD orders in March", incident_at: Date.new(2026, 3, 14),
+client.report(phone: "9876543210", reason_code: "chargeback", notes: "Disputed 3 card payments in March", incident_at: Date.new(2026, 3, 14),
               confirmed_by: "bank", evidence_ref: "your-ticket-123")   # optional: who confirmed it (shown to others), and a private reference
 
 # up to 100 at once; one bad row never stops the rest
@@ -33,6 +33,19 @@ client.reason_codes                                     # => [#<struct code="cha
 client.me                                               # => { "checks_remaining" => ..., ... }
 ```
 
+## Send hashes instead of phone numbers
+
+Pass `hash_numbers: true` and the library sends the SHA-256 of each number instead of the number, so OpenTrust never receives it. It also sends `phone_length`, the length of the text it hashed (always 13), which OpenTrust checks to catch a hash of a differently written number. A report also sends the last four digits, so merchants and admins have something to recognise it by.
+
+```ruby
+client = OpenTrust::Client.new(hash_numbers: true)
+client.lookup("98765 43210")           # sends only the hash and its length (always 13)
+OpenTrust.hash_phone("98765 43210")    # => "f3a47ce5ce3d4ca8ad15225a245b2759022f79489f5c62719b8c9490f7aab90e"
+client.verify_hashing("98765 43210")   # development aid: asks OpenTrust to compare (sends the number: use a test number)
+```
+
+The format is exact, and a hash computed from a differently written number just finds nothing, so use the helper instead of hashing by hand. It is tested against the shared [test vectors](https://github.com/parity/opentrust/blob/main/sdks/phone-hash-vectors.json). A hash of a phone number can in principle be reversed by trying every possible number: this limits what is sent and stored, it does not make a number anonymous.
+
 ## Please don't block checkout on OpenTrust
 
 Results are unverified observations from individual merchants. Use them as one input, have a person review decisions that matter, and fail open if OpenTrust is unreachable:

data/lib/opentrust/client.rb

@@ -9,7 +9,8 @@ module OpenTrust
   # not a finding about anyone. Use them as one input among others.
   #
   # `reports` and `report_count` only hold OTHER merchants' reports. `own_report` says whether you have shared this number yourself.
-  Lookup = Struct.new(:phone_last4, :report_count, :reports, :own_report, :notice, :checks_remaining, keyword_init: true) do
+  # `phone_sha256` is set when the number was sent as a hash (then `phone_last4` is empty: we never saw the number).
+  Lookup = Struct.new(:phone_last4, :phone_sha256, :report_count, :reports, :own_report, :notice, :checks_remaining, keyword_init: true) do
     def reported?
       report_count.to_i.positive?
     end
@@ -42,24 +43,29 @@ module OpenTrust
   class Client
     DEFAULT_BASE_URL = "https://opentrust.in/api/v1".freeze
 
+    # hash_numbers: send the SHA-256 of each number (see OpenTrust::Phone) instead of the number, so OpenTrust never receives it.
+    # A hash can in principle be reversed by brute force, so this limits what is sent; it does not make a number anonymous.
     # adapter: optional callable (method, url, headers, body) -> [status, body_string], mainly for tests.
-    def initialize(api_key: ENV["OPENTRUST_API_KEY"], base_url: ENV.fetch("OPENTRUST_BASE_URL", DEFAULT_BASE_URL), timeout: 5, adapter: nil)
+    def initialize(api_key: ENV["OPENTRUST_API_KEY"], base_url: ENV.fetch("OPENTRUST_BASE_URL", DEFAULT_BASE_URL), timeout: 5, adapter: nil, hash_numbers: false)
       raise ArgumentError, "api_key is required (or set OPENTRUST_API_KEY)" if api_key.to_s.empty?
 
       @api_key = api_key
       @base_url = base_url.chomp("/")
       @timeout = timeout
       @adapter = adapter
+      @hash_numbers = hash_numbers
     end
 
     # Check one number. Uses one check from your allowance.
     def lookup(phone)
-      lookup_from(request(:post, "/lookups", phone: phone))
+      lookup_from(request(:post, "/lookups", number_fields(phone)))
     end
 
     # Check up to 100 numbers. All or nothing: if you don't have enough checks, none are used.
     def lookup_many(phones)
-      body = request(:post, "/lookups/batch", phones: Array(phones))
+      list = Array(phones)
+      payload = @hash_numbers ? { phone_sha256s: list.map { |p| Phone.sha256(p) }, phone_length: Phone::HASHED_LENGTH } : { phones: list }
+      body = request(:post, "/lookups/batch", payload)
       body.fetch("results").map { |r| lookup_from(r.merge("notice" => body["notice"], "checks_remaining" => body["checks_remaining"])) }
     end
 
@@ -88,7 +94,7 @@ module OpenTrust
 
     # Withdraw your own report for a number. Raises NotFoundError if you have no active report for it.
     def withdraw_report(phone)
-      body = request(:delete, "/reports", phone: phone)
+      body = request(:delete, "/reports", number_fields(phone))
       Withdrawal.new(phone_last4: body["phone_last4"], status: body["status"])
     end
 
@@ -102,16 +108,31 @@ module OpenTrust
       request(:get, "/me")
     end
 
+    # A development aid: asks OpenTrust whether it computes the same SHA-256 as this library for a number. Use a test number, not a
+    # customer's: it sends the number. Returns a Hash with "match" (true or false). It costs no checks.
+    def verify_hashing(test_phone)
+      request(:post, "/phone_hash/check", phone: test_phone, phone_sha256: Phone.sha256(test_phone))
+    end
+
     private
 
     def report_payload(phone:, reason_code:, notes: nil, incident_at: nil, confirmed_by: nil, evidence_ref: nil)
       incident_at = incident_at.iso8601 if incident_at.respond_to?(:iso8601)
-      { phone: phone, reason_code: reason_code, notes: notes, incident_at: incident_at, confirmed_by: confirmed_by, evidence_ref: evidence_ref }.compact
+      number_fields(phone, with_last4: true).merge(reason_code: reason_code, notes: notes, incident_at: incident_at, confirmed_by: confirmed_by, evidence_ref: evidence_ref).compact
+    end
+
+    # The number, or (with hash_numbers) its SHA-256 and, for a report, its last four digits.
+    def number_fields(phone, with_last4: false)
+      return { phone: phone } unless @hash_numbers
+
+      fields = { phone_sha256: Phone.sha256(phone), phone_length: Phone.hashed_length(phone) }
+      fields[:phone_last4] = Phone.last4(phone) if with_last4
+      fields
     end
 
     def lookup_from(h)
       Lookup.new(
-        phone_last4: h["phone_last4"], report_count: h["report_count"], own_report: h["own_report"], notice: h["notice"], checks_remaining: h["checks_remaining"],
+        phone_last4: h["phone_last4"], phone_sha256: h["phone_sha256"], report_count: h["report_count"], own_report: h["own_report"], notice: h["notice"], checks_remaining: h["checks_remaining"],
         reports: Array(h["reports"]).map do |r|
           Report.new(reason_code: r["reason_code"], reason: r["reason"], notes: r["notes"], incident_at: r["incident_at"], confirmed_by: r["confirmed_by"], reported_at: r["reported_at"], reporter_verified: r["reporter_verified"])
         end

data/lib/opentrust/errors.rb

@@ -10,6 +10,9 @@ module OpenTrust
     end
   end
 
+  # Raised before anything is sent: the number is not an Indian mobile number, so it cannot be checked or hashed.
+  class InvalidPhoneError < ArgumentError; end
+
   class ConnectionError < Error; end        # network failure or timeout
   class AuthenticationError < Error; end    # 401: missing or invalid API key
   class NoChecksError < Error; end          # 402: allowance used up

data/lib/opentrust/phone.rb

@@ -0,0 +1,48 @@
+require "digest"
+
+module OpenTrust
+  # The one place the number format is defined. OpenTrust accepts either a phone number or its SHA-256, and a hash only matches
+  # if it is computed exactly like this:
+  #
+  #   1. keep the digits, drop a leading 91 (12 digits) or 0 (11 digits), leaving 10 digits starting 6, 7, 8 or 9
+  #   2. prefix "+91", for example "+919876543210"
+  #   3. SHA-256 of that text, as 64 lowercase hex characters
+  #
+  # A hash that does not match simply finds nothing, so use this helper (and the shared test vectors) rather than hashing by hand.
+  module Phone
+    HASHED_LENGTH = 13 # +91 and ten digits
+
+    module_function
+
+    # "+91" followed by the ten digits. Raises InvalidPhoneError for anything that is not an Indian mobile number.
+    def normalize(raw)
+      digits = raw.to_s.gsub(/\D/, "")
+      digits = digits[2..-1] if digits.length == 12 && digits.start_with?("91")
+      digits = digits[1..-1] if digits.length == 11 && digits.start_with?("0")
+      raise InvalidPhoneError, "not a valid Indian mobile number" unless digits.match?(/\A[6-9]\d{9}\z/)
+
+      "+91#{digits}"
+    end
+
+    # The 64 lowercase hex characters OpenTrust expects as phone_sha256.
+    def sha256(raw)
+      Digest::SHA256.hexdigest(normalize(raw))
+    end
+
+    # The length of the text that is hashed (13), sent as phone_length. OpenTrust refuses any other value, which catches hashes of a
+    # differently written number (10 = just the digits, 11 = leading 0, 12 = 91 without the +).
+    def hashed_length(raw)
+      normalize(raw).length
+    end
+
+    # The last four digits, sent with a hashed report so merchants and admins have something to recognise it by.
+    def last4(raw)
+      normalize(raw)[-4..-1]
+    end
+  end
+
+  # Hash a number the way OpenTrust expects. Same as Phone.sha256.
+  def self.hash_phone(raw)
+    Phone.sha256(raw)
+  end
+end

data/lib/opentrust/version.rb

@@ -1,3 +1,3 @@
 module OpenTrust
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/opentrust.rb

@@ -1,3 +1,4 @@
 require_relative "opentrust/version"
 require_relative "opentrust/errors"
+require_relative "opentrust/phone"
 require_relative "opentrust/client"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: opentrust
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - ParityCube
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-12 00:00:00.000000000 Z
+date: 2026-10-14 00:00:00.000000000 Z
 dependencies: []
 description: Check mobile numbers against experiences shared by other Indian merchants,
   and share your own. A small, dependency-free client for https://opentrust.in.
@@ -22,6 +22,7 @@ files:
 - lib/opentrust.rb
 - lib/opentrust/client.rb
 - lib/opentrust/errors.rb
+- lib/opentrust/phone.rb
 - lib/opentrust/version.rb
 homepage: https://opentrust.in/docs
 licenses: