human-attestation 0.3.7 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d32e8f6d80fbc741b843c0d367ceec4467cd192f26792afbdeb3a1d89bec88ee
-  data.tar.gz: 5026790abb465412835388fa128314474e25fc0534eec42c7e3885bd88920b17
+  metadata.gz: 43f2e6d60bc535f28ceae3b2c18c686c9f73b4e354904c817c6da92fc6160aa6
+  data.tar.gz: c99e2870ab4e166121dc6c0821f4e41610bdb65707ddbf5bbc4b34ca1c0118c3
 SHA512:
-  metadata.gz: 75d9aad061ab6cf02a7eeb5d0249641777fcb0ece9ec863dd11aef219993a1c2d71f61415045826d17d0ca99e91db1b4a08415229771488395056d189e76dd37
-  data.tar.gz: e4190595e0c0907152ebbea6e5b12b8d0af4537fa883fc826456a7e272636411e92b698b716be4e2bff8bfc161dd34ae0c6e185b858c6c79482018fbffb05ccf
+  metadata.gz: 257c57249f1957a4aa1c335392fa003a6e1b93a38a391a9bb71f2e20bfdb7c9add13f863029026847f2c73041e22d7545609b6fe5b87d0c766a734e57f2d3cf6
+  data.tar.gz: e1edae08ce9e8aaedfe69d283fb75390c04b28eb74830e00b56185b93d839f7c1625497590141dc5c0bbf00d8a25b2ca452d9df20b0c3d77063a5d60f43c2415

data/README.md

@@ -23,20 +23,20 @@ gem install human-attestation
 ### Verifying a Claim (For Recipients)
 
 ```ruby
-require 'hap'
+require 'human_attestation'
 
 # Verify a claim from a HAP ID
-claim = Hap.verify_hap_claim("hap_abc123xyz456", "ballista.jobs")
+claim = HumanAttestation.verify_claim("hap_abc123xyz456", "ballista.jobs")
 
 if claim
   # Check if not expired
-  if Hap.claim_expired?(claim)
+  if HumanAttestation.claim_expired?(claim)
     puts "Claim has expired"
     return
   end
 
   # Verify it's for your organization
-  unless Hap.claim_for_recipient?(claim, "yourcompany.com")
+  unless HumanAttestation.claim_for_recipient?(claim, "yourcompany.com")
     puts "Claim is for a different recipient"
     return
   end
@@ -50,10 +50,10 @@ end
 ```ruby
 # Extract HAP ID from a verification URL
 url = "https://www.ballista.jobs/v/hap_abc123xyz456"
-hap_id = Hap.extract_hap_id_from_url(url)
+hap_id = HumanAttestation.extract_id_from_url(url)
 
 if hap_id
-  claim = Hap.verify_hap_claim(hap_id, "ballista.jobs")
+  claim = HumanAttestation.verify_claim(hap_id, "ballista.jobs")
   # ... handle claim
 end
 ```
@@ -62,11 +62,11 @@ end
 
 ```ruby
 # Fetch the claim
-response = Hap.fetch_claim("hap_abc123xyz456", "ballista.jobs")
+response = HumanAttestation.fetch_claim("hap_abc123xyz456", "ballista.jobs")
 
 if response[:valid] && response[:jws]
   # Verify the cryptographic signature
-  result = Hap.verify_signature(response[:jws], "ballista.jobs")
+  result = HumanAttestation.verify_signature(response[:jws], "ballista.jobs")
 
   if result[:valid]
     puts "Signature verified! Claim: #{result[:claim]}"
@@ -79,89 +79,58 @@ end
 ### Signing Claims (For Verification Authorities)
 
 ```ruby
-require 'hap'
+require 'human_attestation'
 require 'json'
 
 # Generate a key pair (do this once, store securely)
-private_key, public_key = Hap.generate_key_pair
+private_key, public_key = HumanAttestation.generate_key_pair
 
 # Export public key for /.well-known/hap.json
-jwk = Hap.export_public_key_jwk(public_key, "my_key_001")
+jwk = HumanAttestation.export_public_key_jwk(public_key, "my_key_001")
 well_known = { issuer: "my-va.com", keys: [jwk] }
 puts JSON.pretty_generate(well_known)
 
 # Create and sign a claim
-claim = Hap.create_human_effort_claim(
+claim = HumanAttestation.create_claim(
   method: "physical_mail",
+  description: "Priority mail packet with handwritten cover letter",
   recipient_name: "Acme Corp",
   domain: "acme.com",
-  tier: "standard",
   issuer: "my-va.com",
-  expires_in_days: 730 # 2 years
+  expires_in_days: 730, # 2 years
+  cost: { amount: 1500, currency: "USD" },
+  time: 1800,
+  physical: true
 )
 
-jws = Hap.sign_claim(claim, private_key, kid: "my_key_001")
+jws = HumanAttestation.sign_claim(claim, private_key, kid: "my_key_001")
 puts "Signed JWS: #{jws}"
 ```
 
-### Creating Recipient Commitment Claims
-
-```ruby
-claim = Hap.create_recipient_commitment_claim(
-  recipient_name: "Acme Corp",
-  recipient_domain: "acme.com",
-  commitment: "review_verified",
-  issuer: "my-va.com",
-  expires_in_days: 365
-)
-
-jws = Hap.sign_claim(claim, private_key, kid: "my_key_001")
-```
-
 ## API Reference
 
 ### Verification Functions
 
-| Method                                  | Description                                     |
-| --------------------------------------- | ----------------------------------------------- |
-| `Hap.verify_hap_claim(hap_id, issuer)`  | Fetch and verify a claim, returns claim or nil  |
-| `Hap.fetch_claim(hap_id, issuer)`       | Fetch raw verification response from VA         |
-| `Hap.verify_signature(jws, issuer)`     | Verify JWS signature against VA's public keys   |
-| `Hap.fetch_public_keys(issuer)`         | Fetch VA's public keys from well-known endpoint |
-| `Hap.valid_hap_id?(id)`                 | Check if string matches HAP ID format           |
-| `Hap.extract_hap_id_from_url(url)`      | Extract HAP ID from verification URL            |
-| `Hap.claim_expired?(claim)`             | Check if claim has passed expiration            |
-| `Hap.claim_for_recipient?(claim, domain)` | Check if claim targets specific recipient         |
+| Method                                            | Description                                     |
+| ------------------------------------------------- | ----------------------------------------------- |
+| `HumanAttestation.verify_claim(hap_id, issuer)`   | Fetch and verify a claim, returns claim or nil  |
+| `HumanAttestation.fetch_claim(hap_id, issuer)`    | Fetch raw verification response from VA         |
+| `HumanAttestation.verify_signature(jws, issuer)`  | Verify JWS signature against VA's public keys   |
+| `HumanAttestation.fetch_public_keys(issuer)`      | Fetch VA's public keys from well-known endpoint |
+| `HumanAttestation.valid_id?(id)`                  | Check if string matches HAP ID format           |
+| `HumanAttestation.extract_id_from_url(url)`       | Extract HAP ID from verification URL            |
+| `HumanAttestation.claim_expired?(claim)`          | Check if claim has passed expiration            |
+| `HumanAttestation.claim_for_recipient?(claim, domain)` | Check if claim targets specific recipient  |
 
 ### Signing Functions (For VAs)
 
-| Method                                      | Description                              |
-| ------------------------------------------- | ---------------------------------------- |
-| `Hap.generate_key_pair`                     | Generate Ed25519 key pair                |
-| `Hap.export_public_key_jwk(key, kid)`       | Export public key as JWK                 |
-| `Hap.sign_claim(claim, private_key, kid:)`  | Sign a claim, returns JWS                |
-| `Hap.generate_hap_id`                       | Generate cryptographically secure HAP ID |
-| `Hap.create_human_effort_claim(...)`        | Create human_effort claim with defaults  |
-| `Hap.create_recipient_commitment_claim(...)` | Create recipient_commitment claim         |
-
-### Constants
-
-```ruby
-# Claim types
-Hap::CLAIM_TYPE_HUMAN_EFFORT         # "human_effort"
-Hap::CLAIM_TYPE_RECIPIENT_COMMITMENT # "recipient_commitment"
-
-# Verification methods
-Hap::METHOD_PHYSICAL_MAIL   # "physical_mail"
-Hap::METHOD_VIDEO_INTERVIEW # "video_interview"
-Hap::METHOD_PAID_ASSESSMENT # "paid_assessment"
-Hap::METHOD_REFERRAL        # "referral"
-
-# Commitment levels
-Hap::COMMITMENT_REVIEW_VERIFIED     # "review_verified"
-Hap::COMMITMENT_PRIORITIZE_VERIFIED # "prioritize_verified"
-Hap::COMMITMENT_RESPOND_VERIFIED    # "respond_verified"
-```
+| Method                                                | Description                              |
+| ----------------------------------------------------- | ---------------------------------------- |
+| `HumanAttestation.generate_key_pair`                  | Generate Ed25519 key pair                |
+| `HumanAttestation.export_public_key_jwk(key, kid)`    | Export public key as JWK                 |
+| `HumanAttestation.sign_claim(claim, private_key, kid:)` | Sign a claim, returns JWS              |
+| `HumanAttestation.generate_id`                        | Generate cryptographically secure HAP ID |
+| `HumanAttestation.create_claim(...)`                  | Create claim with defaults               |
 
 ## Requirements
 

data/lib/human_attestation/compact.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+require "ed25519"
+require "base64"
+require "cgi"
+require "time"
+
+module HumanAttestation
+  # HAP Compact Format utilities for space-efficient serialization
+  #
+  # Format: HAP{version}.{id}.{method}.{to_name}.{to_domain}.{at}.{exp}.{iss}.{signature}
+  #
+  # Note: Effort dimensions (cost, time, physical, energy) are NOT included in compact format.
+  # Compact is for QR codes - minimal representation. Full claims in JWS include all dimensions.
+  #
+  # @example
+  #   HAP1.hap_abc123xyz456.ba_priority_mail.Acme%20Corp.acme%2Ecom.1706169600.1769241600.ballista%2Ejobs.MEUCIQDx...
+  module Compact
+    module_function
+
+    # Encodes a field for compact format (URL-encode + encode dots)
+    #
+    # @param value [String] The value to encode
+    # @return [String] Encoded value
+    def encode_compact_field(value)
+      CGI.escape(value.to_s).gsub(".", "%2E")
+    end
+
+    # Decodes a compact format field
+    #
+    # @param value [String] The encoded value
+    # @return [String] Decoded value
+    def decode_compact_field(value)
+      CGI.unescape(value)
+    end
+
+    # Base64url encode without padding
+    #
+    # @param data [String] Binary data to encode
+    # @return [String] Base64url encoded string
+    def base64url_encode(data)
+      Base64.urlsafe_encode64(data, padding: false)
+    end
+
+    # Base64url decode
+    #
+    # @param data [String] Base64url encoded string
+    # @return [String] Decoded binary data
+    def base64url_decode(data)
+      Base64.urlsafe_decode64(data)
+    end
+
+    # Convert ISO 8601 timestamp to Unix epoch seconds
+    #
+    # @param iso [String] ISO 8601 timestamp
+    # @return [Integer] Unix timestamp
+    def iso_to_unix(iso)
+      Time.parse(iso).to_i
+    end
+
+    # Convert Unix epoch seconds to ISO 8601 timestamp
+    #
+    # @param unix [Integer] Unix timestamp
+    # @return [String] ISO 8601 timestamp
+    def unix_to_iso(unix)
+      Time.at(unix).utc.iso8601
+    end
+
+    # Encodes a HAP claim and signature into compact format (9 fields)
+    #
+    # @param claim [Hash] The claim to encode
+    # @param signature [String] The Ed25519 signature bytes (64 bytes)
+    # @return [String] Compact format string
+    def encode_compact(claim, signature)
+      to = claim[:to] || {}
+      name = to[:name] || ""
+      domain = to[:domain] || ""
+
+      at_unix = iso_to_unix(claim[:at])
+      exp_unix = claim[:exp] ? iso_to_unix(claim[:exp]) : 0
+
+      [
+        "HAP#{COMPACT_VERSION}",
+        claim[:id],
+        claim[:method] || "",
+        encode_compact_field(name),
+        encode_compact_field(domain),
+        at_unix.to_s,
+        exp_unix.to_s,
+        encode_compact_field(claim[:iss]),
+        base64url_encode(signature)
+      ].join(".")
+    end
+
+    # Decodes a compact format string into claim and signature
+    #
+    # @param compact [String] The compact format string
+    # @return [Hash] { claim: Hash, signature: String }
+    # @raise [ArgumentError] If format is invalid
+    def decode_compact(compact)
+      raise ArgumentError, "Invalid HAP Compact format" unless valid_compact?(compact)
+
+      parts = compact.split(".")
+      raise ArgumentError, "Invalid HAP Compact format: expected 9 fields" unless parts.length == 9
+
+      version, hap_id, method, encoded_name, encoded_domain, at_unix_str, exp_unix_str, encoded_iss, sig_b64 = parts
+
+      raise ArgumentError, "Unsupported compact version: #{version}" unless version == "HAP#{COMPACT_VERSION}"
+
+      name = decode_compact_field(encoded_name)
+      domain = decode_compact_field(encoded_domain)
+      iss = decode_compact_field(encoded_iss)
+      at_unix = at_unix_str.to_i
+      exp_unix = exp_unix_str.to_i
+      signature = base64url_decode(sig_b64)
+
+      at = unix_to_iso(at_unix)
+      exp = exp_unix != 0 ? unix_to_iso(exp_unix) : nil
+
+      claim = {
+        v: VERSION_PROTOCOL,
+        id: hap_id,
+        method: method,
+        description: "", # Not included in compact format
+        to: { name: name },
+        at: at,
+        iss: iss
+      }
+      claim[:to][:domain] = domain unless domain.empty?
+      claim[:exp] = exp if exp
+
+      { claim: claim, signature: signature }
+    end
+
+    # Validates if a string is a valid HAP Compact format
+    #
+    # @param compact [String] The string to validate
+    # @return [Boolean] true if valid compact format
+    def valid_compact?(compact)
+      COMPACT_REGEX.match?(compact.to_s)
+    end
+
+    # Builds the compact payload (everything before the signature)
+    # This is what gets signed.
+    #
+    # @param claim [Hash] The claim
+    # @return [String] Compact payload string (8 fields)
+    def build_compact_payload(claim)
+      to = claim[:to] || {}
+      name = to[:name] || ""
+      domain = to[:domain] || ""
+
+      at_unix = iso_to_unix(claim[:at])
+      exp_unix = claim[:exp] ? iso_to_unix(claim[:exp]) : 0
+
+      [
+        "HAP#{COMPACT_VERSION}",
+        claim[:id],
+        claim[:method] || "",
+        encode_compact_field(name),
+        encode_compact_field(domain),
+        at_unix.to_s,
+        exp_unix.to_s,
+        encode_compact_field(claim[:iss])
+      ].join(".")
+    end
+
+    # Signs a claim and returns it in compact format
+    #
+    # @param claim [Hash] The claim to sign
+    # @param private_key [Ed25519::SigningKey] The Ed25519 private key
+    # @return [String] Signed compact format string
+    def sign_compact(claim, private_key)
+      payload = build_compact_payload(claim)
+      signature = private_key.sign(payload)
+      "#{payload}.#{base64url_encode(signature)}"
+    end
+
+    # Verifies a compact format string using provided public keys
+    #
+    # @param compact [String] The compact format string
+    # @param public_keys [Array<Hash>] Array of JWK public keys to try
+    # @return [Hash] { valid: Boolean, claim: Hash or nil, error: String or nil }
+    def verify_compact(compact, public_keys)
+      return { valid: false, error: "Invalid compact format" } unless valid_compact?(compact)
+
+      # Split to get payload and signature
+      last_dot = compact.rindex(".")
+      payload = compact[0...last_dot]
+      sig_b64 = compact[(last_dot + 1)..]
+      signature = base64url_decode(sig_b64)
+
+      # Try each public key
+      public_keys.each do |jwk|
+        begin
+          x_bytes = base64url_decode(jwk[:x] || jwk["x"])
+          verify_key = Ed25519::VerifyKey.new(x_bytes)
+
+          # Verify signature
+          verify_key.verify(signature, payload)
+
+          # Signature is valid
+          decoded = decode_compact(compact)
+          return { valid: true, claim: decoded[:claim] }
+        rescue Ed25519::VerifyError, StandardError
+          # Try next key
+          next
+        end
+      end
+
+      { valid: false, error: "Signature verification failed" }
+    end
+
+    # Generates a verification URL with embedded compact claim
+    #
+    # @param base_url [String] Base verification URL (e.g., "https://ballista.jobs/v")
+    # @param compact [String] The compact format string
+    # @return [String] URL with compact claim in query parameter
+    def generate_verification_url(base_url, compact)
+      "#{base_url}?c=#{CGI.escape(compact)}"
+    end
+
+    # Extracts compact claim from a verification URL
+    #
+    # @param url [String] The verification URL
+    # @return [String, nil] Compact string or nil if not found
+    def extract_compact_from_url(url)
+      uri = URI.parse(url)
+      params = URI.decode_www_form(uri.query || "").to_h
+      compact = params["c"]
+      return compact if compact && valid_compact?(compact)
+
+      nil
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/{hap → human_attestation}/sign.rb

@@ -5,21 +5,47 @@ require "json"
 require "base64"
 require "securerandom"
 require "time"
+require "digest"
 
-module Hap
+module HumanAttestation
   # Signing functions for HAP claims (for Verification Authorities)
   module Sign
     # Characters used for HAP ID generation
-    HAP_ID_CHARS = ("A".."Z").to_a + ("a".."z").to_a + ("0".."9").to_a
+    ID_CHARS = ("A".."Z").to_a + ("a".."z").to_a + ("0".."9").to_a
 
     # Generates a cryptographically secure random HAP ID
     #
     # @return [String] A HAP ID in the format hap_[a-zA-Z0-9]{12}
-    def generate_hap_id
-      suffix = Array.new(12) { HAP_ID_CHARS[SecureRandom.random_number(HAP_ID_CHARS.length)] }.join
+    def generate_id
+      suffix = Array.new(12) { ID_CHARS[SecureRandom.random_number(ID_CHARS.length)] }.join
       "hap_#{suffix}"
     end
 
+    # Generates a test HAP ID (for previews and development)
+    #
+    # @return [String] A test HAP ID in the format hap_test_[a-zA-Z0-9]{8}
+    def generate_test_id
+      suffix = Array.new(8) { ID_CHARS[SecureRandom.random_number(ID_CHARS.length)] }.join
+      "hap_test_#{suffix}"
+    end
+
+    # Checks if a HAP ID is a test ID
+    #
+    # @param id [String] The HAP ID to check
+    # @return [Boolean] true if the ID is a test ID
+    def test_id?(id)
+      TEST_ID_REGEX.match?(id)
+    end
+
+    # Computes SHA-256 hash of content with prefix
+    #
+    # @param content [String] The content to hash
+    # @return [String] Hash string in format "sha256:xxxxx"
+    def hash_content(content)
+      hash = Digest::SHA256.hexdigest(content)
+      "sha256:#{hash}"
+    end
+
     # Generates a new Ed25519 key pair for signing HAP claims
     #
     # @return [Array<Ed25519::SigningKey, Ed25519::VerifyKey>] Private and public keys
@@ -71,23 +97,28 @@ module Hap
       "#{signing_input}.#{signature_b64}"
     end
 
-    # Creates a complete human effort claim with all required fields
+    # Creates a complete HAP claim with all required fields
     #
-    # @param method [String] Verification method (e.g., "physical_mail")
+    # @param method [String] VA-specific verification method identifier
+    # @param description [String] Human-readable description of the effort
     # @param recipient_name [String] Recipient name
     # @param issuer [String] VA's domain
     # @param domain [String, nil] Recipient domain (optional)
     # @param tier [String, nil] Service tier (optional)
     # @param expires_in_days [Integer, nil] Days until expiration (optional)
-    # @return [Hash] A complete human effort claim
-    def create_human_effort_claim(method:, recipient_name:, issuer:, domain: nil, tier: nil, expires_in_days: nil)
+    # @param cost [Hash, nil] Monetary cost { amount: Integer, currency: String } (optional)
+    # @param time [Integer, nil] Time in seconds (optional)
+    # @param physical [Boolean, nil] Whether physical atoms involved (optional)
+    # @param energy [Integer, nil] Energy in kilocalories (optional)
+    # @return [Hash] A complete HAP claim
+    def create_claim(method:, description:, recipient_name:, issuer:, domain: nil, tier: nil, expires_in_days: nil, cost: nil, time: nil, physical: nil, energy: nil)
       now = Time.now.utc
 
       claim = {
         v: VERSION_PROTOCOL,
-        id: generate_hap_id,
-        type: CLAIM_TYPE_HUMAN_EFFORT,
+        id: generate_id,
         method: method,
+        description: description,
         to: { name: recipient_name },
         at: now.iso8601,
         iss: issuer
@@ -101,36 +132,11 @@ module Hap
         claim[:exp] = exp.iso8601
       end
 
-      claim
-    end
-
-    # Creates a complete recipient commitment claim with all required fields
-    #
-    # @param recipient_name [String] Recipient's name
-    # @param commitment [String] Commitment level (e.g., "review_verified")
-    # @param issuer [String] VA's domain
-    # @param recipient_domain [String, nil] Recipient's domain (optional)
-    # @param expires_in_days [Integer, nil] Days until expiration (optional)
-    # @return [Hash] A complete recipient commitment claim
-    def create_recipient_commitment_claim(recipient_name:, commitment:, issuer:, recipient_domain: nil, expires_in_days: nil)
-      now = Time.now.utc
-
-      claim = {
-        v: VERSION_PROTOCOL,
-        id: generate_hap_id,
-        type: CLAIM_TYPE_RECIPIENT_COMMITMENT,
-        recipient: { name: recipient_name },
-        commitment: commitment,
-        at: now.iso8601,
-        iss: issuer
-      }
-
-      claim[:recipient][:domain] = recipient_domain if recipient_domain
-
-      if expires_in_days
-        exp = now + (expires_in_days * 24 * 60 * 60)
-        claim[:exp] = exp.iso8601
-      end
+      # Add effort dimensions if provided
+      claim[:cost] = cost if cost
+      claim[:time] = time if time
+      claim[:physical] = physical unless physical.nil?
+      claim[:energy] = energy if energy
 
       claim
     end

data/lib/human_attestation/types.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module HumanAttestation
+  # HAP Compact format version
+  COMPACT_VERSION = "1"
+
+  # Test HAP ID format regex
+  TEST_ID_REGEX = /\Ahap_test_[a-zA-Z0-9]{8}\z/
+
+  # HAP Compact format regex (9 fields, no type)
+  COMPACT_REGEX = /\AHAP1\.hap_[a-zA-Z0-9_]+\.[^.]+\.[^.]+\.[^.]*\.\d+\.\d+\.[^.]+\.[A-Za-z0-9_-]+\z/
+
+  # Revocation reasons
+  REVOCATION_FRAUD = "fraud"
+  REVOCATION_ERROR = "error"
+  REVOCATION_LEGAL = "legal"
+  REVOCATION_USER_REQUEST = "user_request"
+end

data/lib/{hap → human_attestation}/verify.rb

@@ -8,7 +8,7 @@ require "base64"
 require "uri"
 require "time"
 
-module Hap
+module HumanAttestation
   # Verification functions for HAP claims
   module Verify
     # Default timeout for HTTP requests (seconds)
@@ -18,8 +18,8 @@ module Hap
     #
     # @param id [String] The HAP ID to validate
     # @return [Boolean] true if the ID matches the format hap_[a-zA-Z0-9]{12}
-    def valid_hap_id?(id)
-      HAP_ID_REGEX.match?(id.to_s)
+    def valid_id?(id)
+      ID_REGEX.match?(id.to_s)
     end
 
     # Fetches the public keys from a VA's well-known endpoint
@@ -47,7 +47,7 @@ module Hap
     # @param timeout [Integer] Request timeout in seconds
     # @return [Hash] The verification response from the VA
     def fetch_claim(hap_id, issuer_domain, timeout: DEFAULT_TIMEOUT)
-      return { valid: false, error: "invalid_format" } unless valid_hap_id?(hap_id)
+      return { valid: false, error: "invalid_format" } unless valid_id?(hap_id)
 
       url = "https://#{issuer_domain}/api/v1/verify/#{hap_id}"
 
@@ -115,7 +115,7 @@ module Hap
     # @param verify_sig [Boolean] Whether to verify the cryptographic signature
     # @param timeout [Integer] Request timeout in seconds
     # @return [Hash, nil] The claim if valid, nil if not found or invalid
-    def verify_hap_claim(hap_id, issuer_domain, verify_sig: true, timeout: DEFAULT_TIMEOUT)
+    def verify_claim(hap_id, issuer_domain, verify_sig: true, timeout: DEFAULT_TIMEOUT)
       response = fetch_claim(hap_id, issuer_domain, timeout: timeout)
 
       return nil unless response[:valid]
@@ -132,12 +132,12 @@ module Hap
     #
     # @param url [String] The verification URL
     # @return [String, nil] The HAP ID or nil if not found
-    def extract_hap_id_from_url(url)
+    def extract_id_from_url(url)
       uri = URI.parse(url)
       parts = uri.path.split("/")
       last_part = parts.last
 
-      valid_hap_id?(last_part) ? last_part : nil
+      valid_id?(last_part) ? last_part : nil
     rescue URI::InvalidURIError
       nil
     end
@@ -161,14 +161,7 @@ module Hap
     # @param recipient_domain [String] The expected recipient domain
     # @return [Boolean] true if the claim's target domain matches
     def claim_for_recipient?(claim, recipient_domain)
-      case claim[:type]
-      when CLAIM_TYPE_HUMAN_EFFORT
-        claim.dig(:to, :domain) == recipient_domain
-      when CLAIM_TYPE_RECIPIENT_COMMITMENT
-        claim.dig(:recipient, :domain) == recipient_domain
-      else
-        false
-      end
+      claim.dig(:to, :domain) == recipient_domain
     end
   end
 end

data/lib/human_attestation/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module HumanAttestation
+  VERSION = "0.4.2"
+end

data/lib/human_attestation.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "human_attestation/version"
+require_relative "human_attestation/types"
+require_relative "human_attestation/verify"
+require_relative "human_attestation/sign"
+require_relative "human_attestation/compact"
+
+# HAP (Human Attestation Protocol) SDK for Ruby
+#
+# HAP is an open standard for verified human effort. It enables Verification
+# Authorities (VAs) to cryptographically attest that a sender took deliberate,
+# costly action when communicating with a recipient.
+#
+# @example Verifying a claim (for recipients)
+#   claim = HumanAttestation.verify_claim("hap_abc123xyz456", "ballista.jobs")
+#   if claim && !HumanAttestation.claim_expired?(claim)
+#     puts "Verified application to #{claim[:to][:name]}"
+#   end
+#
+# @example Signing a claim (for VAs)
+#   private_key, public_key = HumanAttestation.generate_key_pair
+#   claim = HumanAttestation.create_claim(
+#     method: "ba_priority_mail",
+#     description: "Priority mail packet with handwritten cover letter",
+#     recipient_name: "Acme Corp",
+#     domain: "acme.com",
+#     issuer: "my-va.com",
+#     cost: { amount: 1500, currency: "USD" },
+#     time: 1800,
+#     physical: true
+#   )
+#   jws = HumanAttestation.sign_claim(claim, private_key, kid: "key_001")
+#
+module HumanAttestation
+  class Error < StandardError; end
+  class VerificationError < Error; end
+  class SigningError < Error; end
+
+  # Protocol version
+  VERSION_PROTOCOL = "0.1"
+
+  # HAP ID format regex
+  ID_REGEX = /\Ahap_[a-zA-Z0-9]{12}\z/
+
+  # Extend self to allow calling methods directly on the module
+  extend Verify
+  extend Sign
+  extend Compact
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: human-attestation
 version: !ruby/object:Gem::Version
-  version: 0.3.7
+  version: 0.4.2
 platform: ruby
 authors:
 - BlueScroll Inc.
@@ -90,11 +90,12 @@ extra_rdoc_files: []
 files:
 - LICENSE
 - README.md
-- lib/hap.rb
-- lib/hap/sign.rb
-- lib/hap/types.rb
-- lib/hap/verify.rb
-- lib/hap/version.rb
+- lib/human_attestation.rb
+- lib/human_attestation/compact.rb
+- lib/human_attestation/sign.rb
+- lib/human_attestation/types.rb
+- lib/human_attestation/verify.rb
+- lib/human_attestation/version.rb
 homepage: https://github.com/Blue-Scroll/hap
 licenses:
 - Apache-2.0

data/lib/hap/types.rb

@@ -1,24 +0,0 @@
-# frozen_string_literal: true
-
-module Hap
-  # Claim types
-  CLAIM_TYPE_HUMAN_EFFORT = "human_effort"
-  CLAIM_TYPE_RECIPIENT_COMMITMENT = "recipient_commitment"
-
-  # Core verification methods
-  METHOD_PHYSICAL_MAIL = "physical_mail"
-  METHOD_VIDEO_INTERVIEW = "video_interview"
-  METHOD_PAID_ASSESSMENT = "paid_assessment"
-  METHOD_REFERRAL = "referral"
-
-  # Commitment levels
-  COMMITMENT_REVIEW_VERIFIED = "review_verified"
-  COMMITMENT_PRIORITIZE_VERIFIED = "prioritize_verified"
-  COMMITMENT_RESPOND_VERIFIED = "respond_verified"
-
-  # Revocation reasons
-  REVOCATION_FRAUD = "fraud"
-  REVOCATION_ERROR = "error"
-  REVOCATION_LEGAL = "legal"
-  REVOCATION_USER_REQUEST = "user_request"
-end

data/lib/hap/version.rb

@@ -1,5 +0,0 @@
-# frozen_string_literal: true
-
-module Hap
-  VERSION = "0.3.7"
-end

data/lib/hap.rb

@@ -1,44 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "hap/version"
-require_relative "hap/types"
-require_relative "hap/verify"
-require_relative "hap/sign"
-
-# HAP (Human Attestation Protocol) SDK for Ruby
-#
-# HAP is an open standard for verified human effort. It enables Verification
-# Authorities (VAs) to cryptographically attest that a sender took deliberate,
-# costly action when communicating with a recipient.
-#
-# @example Verifying a claim (for recipients)
-#   claim = Hap.verify_hap_claim("hap_abc123xyz456", "ballista.jobs")
-#   if claim && !Hap.claim_expired?(claim)
-#     puts "Verified application to #{claim[:to][:name]}"
-#   end
-#
-# @example Signing a claim (for VAs)
-#   private_key, public_key = Hap.generate_key_pair
-#   claim = Hap.create_human_effort_claim(
-#     method: "physical_mail",
-#     recipient_name: "Acme Corp",
-#     domain: "acme.com",
-#     issuer: "my-va.com"
-#   )
-#   jws = Hap.sign_claim(claim, private_key, kid: "key_001")
-#
-module Hap
-  class Error < StandardError; end
-  class VerificationError < Error; end
-  class SigningError < Error; end
-
-  # Protocol version
-  VERSION_PROTOCOL = "0.1"
-
-  # HAP ID format regex
-  HAP_ID_REGEX = /\Ahap_[a-zA-Z0-9]{12}\z/
-
-  # Extend self to allow calling methods directly on the module
-  extend Verify
-  extend Sign
-end