lcp-sdk 1.0.2 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 62c022daa49deaca29686086da6cb24e3b8f8cba2fd65fc5fd8443f306d0ce66
-  data.tar.gz: ef2ff43e0a408396682c561924f25aaa53d4bfba7b6dedef3a564bdb133d188f
+  metadata.gz: 703d40a739d0c90ec564532625d80d28c118177c6ffabea4435e00d276a299b1
+  data.tar.gz: 3b6861a3b2c9203f7daa6948f8bbe94c34849c5f1dd6c3303c7bc019c151cc7d
 SHA512:
-  metadata.gz: 277d5be9e17a4e2ef371958c59e054eb99f3da93b016c498c6645fc1509cf2cc3fd5ce32352bde969e55fde44d8852144efc1fd8cfbe9c63cec54d984a7f711f
-  data.tar.gz: 1d7b8d764af3c8adbbbf8ff2ab6236450553b3b5313ede6375798c8d87ed2fc60fa821b656dfa113ae0164f750ec6511e0d47caf56a1b844ce5b2fc02f1fa2a8
+  metadata.gz: 162396e876b349241cf03a867480fb9bfd4240a0ce454db072540f173ed70332e57ed982aac35e088c6cb4be823ef487b970773f3941535cba0d6760184cf948
+  data.tar.gz: 294d1fd238144a806ef492ee55baa2702b5d730cf8728966f3661a0b1a4ad6734c0cb65cedf4b3b30ac75eb3100515f8d43d12bdb2b0abecede91fcad5ea1abd

data/README.md

@@ -11,3 +11,26 @@ The SDK provides generated payload models, `LcpSdk::SchemaValidator` full Draft
 `LcpSdk::Signing` raw-body HMAC helpers, webhook verification, and
 `LcpSdk::Client` operations for leads, calls, bids, status, capabilities, and
 offers. See the shared [SDK contract](../../../docs/SDK-ROADMAP.md).
+## Shared lead slots and contact hashes (v1.1, LEP-0003)
+
+The typed payload declarations gained the optional v1.1 fields
+`slots_available` (ping), `slots_claimed` (bid), and `contacted_hashes`
+(post). The SDK ships the only sanctioned contact-hash builder —
+`HMAC-SHA256(pair_secret, normalized_preimage)` (lowercase hex), reusing the
+package's existing HMAC-SHA256 signing primitive: phone preimages are the
+verbatim wire bytes per SPEC.md §9; email preimages use the §9 pinned
+candidate canonical (trim surrounding whitespace, ASCII-lowercase the domain,
+local-part bytes verbatim, plus-addresses distinct), and email-form
+`contacted_hashes` ENTRIES stay emission-gated until the #153 T9 executed
+vectors publish. Pinned rows live in
+[`test-vectors/sdk/contact-hash.json`](../../../test-vectors/sdk/contact-hash.json).
+Slot fields are capability-gated, never ignore-gated (SPEC.md §8): senders
+MUST only include them toward a receiver advertising a full
+`major.minor.patch` element with `major == 1` and `minor >= 1`, compared as
+parsed semver; the example below shows the gate and the SDK validator
+rejecting slot fields toward a v1.0-only advertisement.
+
+```ruby
+digest = LcpSdk::Signing.contact_hash(buyer_pair_secret, "+15125550147", "phone")
+validator.validate_envelope(ping, receiver_advertised_lcp_versions: caps["lcp_versions"])
+```

data/lib/generated_models.rb

@@ -4,9 +4,9 @@ module LcpSdk
   EnvelopeModel = Struct.new(:version, :message, :payload, keyword_init: true)
   LeadPayload = Struct.new(:lead_id, :status, :channel, :consumer, :location, :attributes, :external_id, :submitted_at, :compliance, :provenance, :exclusivity, :contact_window, :lead_quality, :expiry, :attachments, keyword_init: true)
   CallPayload = Struct.new(:lead_id, :status, :channel, :consumer, :location, :call, :external_id, :submitted_at, :compliance, :provenance, :attributes, :expiry, :exclusivity, :attachments, keyword_init: true)
-  PingPayload = Struct.new(:ping_id, :lead_reference, :phone_hash, :country_code, :vertical, :floor_price_cents, :currency, :publisher_id, :offer_id, :email_hash, :attributes, keyword_init: true)
-  PostPayload = Struct.new(:lead_id, :delivered_at, :price_cents, :currency, :buyer_id, :consumer, :location, :attributes, :submitted_at, :offer_id, :buyer_reference, :pricing, :compliance, :provenance, :call, :attachments, keyword_init: true)
-  BidPayload = Struct.new(:ping_id, :decision, :bid_price_cents, :currency, :estimated_contact_seconds, :buyer_reference, :reject_reason, :capacity_remaining, keyword_init: true)
+  PingPayload = Struct.new(:ping_id, :lead_reference, :phone_hash, :country_code, :vertical, :floor_price_cents, :currency, :publisher_id, :offer_id, :email_hash, :attributes, :slots_available, keyword_init: true)
+  PostPayload = Struct.new(:lead_id, :delivered_at, :price_cents, :currency, :buyer_id, :consumer, :location, :attributes, :submitted_at, :offer_id, :buyer_reference, :pricing, :compliance, :provenance, :contacted_hashes, :call, :attachments, keyword_init: true)
+  BidPayload = Struct.new(:ping_id, :decision, :bid_price_cents, :currency, :estimated_contact_seconds, :buyer_reference, :reject_reason, :capacity_remaining, :slots_claimed, keyword_init: true)
   AckPayload = Struct.new(:original_message_id, :status, :errors, :lead_id, :request_id, :rejection_reason, keyword_init: true)
   EventPayload = Struct.new(:lead_id, :event, :timestamp, :details, :external_reference, keyword_init: true)
   OfferModel = Struct.new(:offer_id, :buyer_id, :vertical, :countries, :floor_price_cents, :currency, :tenant_id, :active, :routing_mode, :schema_version, :extensions, :allowed_publisher_ids, :allowed_brand_ids, :attribute_equals, :attribute_in, :monthly_minimum_payable, :monthly_maximum_payable, :monthly_quota_timezone, :monthly_quota_policy, :payable_rules, :call_routing_mode, :connect_timeout_seconds, keyword_init: true)

data/lib/lcp_sdk.rb

@@ -20,7 +20,47 @@ module LcpSdk
     end
 
     def sign(secret, timestamp, idempotency_key, body)
-      OpenSSL::HMAC.hexdigest("SHA256", secret, canonical_bytes(timestamp, idempotency_key, body))
+      hmac_hex(secret, canonical_bytes(timestamp, idempotency_key, body))
+    end
+
+    # The single HMAC-SHA256 → lowercase-hex construction in this SDK (SPEC.md §9).
+    # Signing and contact hashes share it; nothing else computes a keyed digest.
+    def hmac_hex(secret, data)
+      OpenSSL::HMAC.hexdigest("SHA256", secret, data)
+    end
+
+    CONTACT_HASH_DOMAINS = ["phone", "email"].freeze
+
+    # SPEC.md §9 pinned contact preimage. Phone: the wire value verbatim,
+    # byte-for-byte — no folding, stripping, or reformatting (the reference
+    # platform's phone_hash builder is the executed baseline). Email: the §9
+    # pinned candidate canonical — trim surrounding whitespace, ASCII-lowercase
+    # the domain, keep the local-part bytes verbatim, plus-addresses distinct.
+    # Email-form contacted_hashes ENTRIES stay emission-gated until #153 T9
+    # executed vectors publish; this is the pinned compute rule every
+    # contact-hash vector row reproduces under.
+    def normalize_contact(value, domain = "phone")
+      case domain
+      when "phone" then value
+      when "email"
+        trimmed = value.strip
+        separator = trimmed.rindex("@")
+        raise ArgumentError, "email contact preimage must contain '@'" unless separator
+        local = trimmed[0...separator]
+        host = trimmed[(separator + 1)..].chars.map { |c| c =~ /\A[A-Z]\z/ ? c.downcase : c }.join
+        "#{local}@#{host}"
+      else
+        raise ArgumentError, "unknown contact domain #{domain.inspect} (expected phone or email)"
+      end
+    end
+
+    # Per-pair contact hash (SPEC.md §9, LEP-0003 §3): lowercase-hex
+    # HMAC-SHA256(pair_secret, normalized_preimage) keyed with the secret
+    # shared with the message's receiver. phone_hash, email_hash, and
+    # contacted_hashes entries all ride this one construction — never an
+    # unsalted digest, never SHA-1.
+    def contact_hash(secret, value, domain = "phone")
+      hmac_hex(secret, normalize_contact(value, domain))
     end
 
     def verify(secret, signature, timestamp, idempotency_key, body, max_skew_seconds: 300, now: Time.now.utc)
@@ -62,6 +102,41 @@ module LcpSdk
     true
   end
 
+  # SPEC.md §8 capability gate (LEP-0003): v1.1 slot fields are
+  # capability-gated, never ignore-gated — the ping/bid/post objects are
+  # closed, so a v1.0 schema-validating receiver REJECTS the fields. Senders
+  # MUST only include them toward a receiver whose lcp_versions advertisement
+  # parses to a full major.minor.patch element with major == 1 and minor >= 1
+  # (never a string literal or prefix).
+  SLOT_FIELDS = ["slots_available", "slots_claimed", "contacted_hashes"].freeze
+
+  def receiver_advertises_slot_fields(advertised_lcp_versions)
+    Array(advertised_lcp_versions).any? do |element|
+      parts = element.to_s.split(".")
+      next false unless parts.size == 3 && parts.all? { |part| !part.empty? && part.match?(/\A\d+\z/) }
+      parts[0].to_i == 1 && parts[1].to_i >= 1
+    end
+  end
+
+  def slot_fields_present(payload)
+    return [] unless payload.is_a?(Hash)
+    present = SLOT_FIELDS.select { |field| payload.key?(field) }
+    if payload["event"] == "CONTACTED" && payload["details"].is_a?(Hash) && payload["details"].key?("contacted_hashes")
+      present = present + ["details.contacted_hashes"]
+    end
+    present
+  end
+
+  # Errors when an envelope carries v1.1 slot fields but the receiver's
+  # advertisement does not support them (§8 gate; invalid example D). An empty
+  # list is capability-compatibility, not a schema verdict.
+  def slot_capability_errors(envelope, advertised_lcp_versions)
+    payload = envelope.dig("lcp", "payload")
+    present = slot_fields_present(payload)
+    return [] if present.empty? || receiver_advertises_slot_fields(advertised_lcp_versions)
+    present.map { |field| "#{field} requires the receiver to advertise a full-semver LCP version with major 1 and minor >= 1 (SPEC.md §8 capability gate)" }
+  end
+
   class Client
     def initialize(endpoint, sender_id: nil, api_key: nil, hmac_secret: nil, max_retries: 2)
       @endpoint = endpoint.delete_suffix("/"); @sender_id = sender_id; @api_key = api_key; @hmac_secret = hmac_secret; @max_retries = max_retries

data/lib/schema-bundle.json

@@ -113,6 +113,12 @@
       "reject_reason": {
         "description": "Why the buyer rejected (e.g. out_of_hours, capacity_full, vertical_mismatch, price_too_low). Open enumeration. Optional.",
         "type": "string"
+      },
+      "slots_claimed": {
+        "description": "v1.1 (LEP-0003 \u00a72): buyer slots this buyer claims if selected. The claim is a request, not a reservation \u2014 the platform awards slots at post time (delivery is the claim event; bids are non-binding). Only meaningful with decision 'accept'; absent = 1. Capped at exactly 1 for v1.1: multi-slot agency claims (N > 1) have no delivery path on the per-(lead, offer) award guard and no awarded-count wire signal, so they are deferred (LEP-0003 Deferred questions, #153 T5) \u2014 this schema enforces maximum: 1 now. Capability-gated (SPEC.md \u00a78): senders MUST NOT include v1.1 slot fields toward receivers whose lcp_versions advertisement does not parse to major == 1, minor >= 1.",
+        "maximum": 1,
+        "minimum": 1,
+        "type": "integer"
       }
     },
     "required": [
@@ -658,7 +664,7 @@
           },
           "locale": {
             "description": "BCP-47 language tag (e.g. en-AU, es-US).",
-            "pattern": "^[a-z]{2,3}(-[A-Z][a-zA-Z]{1,7})?$",
+            "pattern": "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$",
             "type": "string"
           },
           "phone": {
@@ -841,6 +847,8 @@
                 "type": "string"
               },
               "attestation": {
+                "maxLength": 8192,
+                "pattern": "^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$",
                 "type": "string"
               }
             },
@@ -1136,6 +1144,17 @@
       "expiry": {
         "$ref": "core.json#/$defs/expiry"
       },
+      "extensions": {
+        "additionalProperties": true,
+        "description": "v1.1 (LEP-0006 Track B): namespaced deployment-specific data (SPEC.md section 6; governance/EXTENSION-REGISTRY.md). Keys MUST follow {org}.{division}.{purpose} - at least three lowercase dot-separated segments - and lcp.core.* is reserved for the core. Values stay deployment-defined: the core does not and cannot validate namespaced payloads. Shape authority for a registered namespace is its record (LEP-0006 section B.2 defines {org}.form.questions: at most 25 entries of question_id/question_text/answer_text, question_text at most 300 and answer_text at most 1000 characters). These are receiver rules, not schema rules: a receiver that implements a registered form.questions namespace MUST validate entries and accept or reject the message (LCP-100), while receivers that do not recognize a namespace ignore its value. Bound hierarchy (LEP-0006 section B.2): the registered form.questions shape ceiling is 133,140 B worst-case UTF-8, receivers SHOULD reject extension totals above the 32 KiB soft policy target (a fully shape-conformant sender can exceed it; issue #197 tracks the re-tune), and the operative hard bound is the transport body cap (max_body_bytes, default 2,000,000 B). Never ping_safe: this field exists only on lead and post - ping/bid/ack keep their strict allowlists - and a platform MUST NOT derive ping attributes, compliance_flags, or any other ping field from extension content. Extension content is lead/post PII-scope content: it inherits section 9 retention and erasure, and question/answer text MUST NOT carry contact values, government identifiers, payment credentials, consent tokens, or evidence values (those have structured homes in consumer, compliance.consent_evidence[], and attachments[]).",
+        "propertyNames": {
+          "not": {
+            "pattern": "^lcp\\.core\\."
+          },
+          "pattern": "^[a-z0-9][a-z0-9_-]*(\\.[a-z0-9][a-z0-9_-]*){2,}$"
+        },
+        "type": "object"
+      },
       "external_id": {
         "description": "Publisher's internal lead ID.",
         "type": "string"
@@ -1591,6 +1610,28 @@
     "$id": "https://lcp.dev/schemas/ping.json",
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "additionalProperties": false,
+    "allOf": [
+      {
+        "$comment": "LEP-0003 \u00a71/F8 (invalid example B): exclusive is exactly the one-slot special case. When the exclusivity hint is present and 'exclusive', slots_available MUST be 1 \u2014 an exclusive ping advertising more is a semantic error, rejected by this conditional, not just by prose. Absent slots_available stays legal (v1.0 behavior).",
+        "if": {
+          "properties": {
+            "exclusivity": {
+              "const": "exclusive"
+            }
+          },
+          "required": [
+            "exclusivity"
+          ]
+        },
+        "then": {
+          "properties": {
+            "slots_available": {
+              "const": 1
+            }
+          }
+        }
+      }
+    ],
     "description": "Non-PII offer to buyers. STRICT ALLOWLIST \u2014 additionalProperties: false. No PII fields are permitted. The conformance runner also validates that every field in attributes is tagged ping_safe: true in the vertical schema. Created by Spear Systems (a Spear company). Open standard \u2014 Apache 2.0, free to implement.",
     "properties": {
       "attributes": {
@@ -1749,6 +1790,11 @@
         },
         "type": "object"
       },
+      "slots_available": {
+        "description": "v1.1 (LEP-0003): remaining buyer-award slots of this lead that can still be sold at ping time, INCLUDING the slot this ping's recipient may win. A slot counts a distinct awarded buyer, never delivered copies (SPEC.md \u00a73 slot semantics). For exclusivity 'exclusive' this MUST be 1 \u2014 the one-slot special case (enforced by the top-level conditional in this schema). Absent = the platform does not advertise slot state (v1.0 behavior). A platform MUST NOT send slots_available: 0; zero remaining means stop pinging. Non-PII integer count carrying no consumer data: it joins the ping strict allowlist as a reviewed non-PII field, and conformance keeps rejecting every other field outside the allowlist (LCP-008 PII_IN_PING protection preserved) and every attribute not tagged ping_safe: true in the vertical schema. Capability-gated (SPEC.md \u00a78): senders MUST NOT include v1.1 slot fields toward receivers whose lcp_versions advertisement does not parse to major == 1, minor >= 1.",
+        "minimum": 1,
+        "type": "integer"
+      },
       "state_region": {
         "type": "string"
       },
@@ -1884,6 +1930,16 @@
       "consumer": {
         "$ref": "core.json#/$defs/consumer"
       },
+      "contacted_hashes": {
+        "$comment": "No uniqueItems (LEP-0003 \u00a74): the wire array tolerates duplicates; the receiver merges by digest set per lead (at-least-once + set-union accumulation). maxItems 100: the record leaves the post-direction array bound open as a Deferred question ('a lead's contact attempts are naturally bounded'); this implementation bound is set generously above any realistic per-lead contact history so no conformant sender is clipped, while keeping the post payload bounded and rejecting bulk-suppression-sync misuse of this field (bulk sync stays out of scope; if production posts ever approach this bound, bulk routes to a dedicated mechanism). The CONTACTED event-report direction has its own tighter ingest bound (32 entries per report, SPEC.md \u00a74).",
+        "description": "v1.1 (LEP-0003 \u00a73): parties already contacted for this lead by the publisher or prior slot holders, re-keyed under THIS receiving buyer's per-pair secret. Each entry is HMAC-SHA256(pair_secret, contact-preimage) \u2014 lowercase 64-hex, the same form as phone_hash (SPEC.md \u00a79); the unsalted SHA-1-shaped digest of the reference network is explicitly NOT adopted (enumerable keyspaces invert it; \u00a714 blocker B3). The platform matches digests only against values it holds in plaintext for this pair and cannot verify reported digests without the plaintext \u2014 the trust model is format + count sanity plus authenticated-sender attestation, scoped to one lead_id. Absent = the platform has no contact reports; [] = the platform attests no prior contacts (the two are distinct). Preimage rules and the phone-only/email-gated state are normative in SPEC.md \u00a79. Capability-gated (SPEC.md \u00a78): senders MUST NOT include v1.1 fields toward receivers whose lcp_versions advertisement does not parse to major == 1, minor >= 1.",
+        "items": {
+          "pattern": "^[a-f0-9]{64}$",
+          "type": "string"
+        },
+        "maxItems": 100,
+        "type": "array"
+      },
       "currency": {
         "$ref": "core.json#/$defs/currency"
       },
@@ -1894,6 +1950,17 @@
       "exclusivity": {
         "$ref": "core.json#/$defs/exclusivity"
       },
+      "extensions": {
+        "additionalProperties": true,
+        "description": "v1.1 (LEP-0006 Track B): namespaced deployment-specific data (SPEC.md section 6; governance/EXTENSION-REGISTRY.md). Keys MUST follow {org}.{division}.{purpose} - at least three lowercase dot-separated segments - and lcp.core.* is reserved for the core. Values stay deployment-defined: the core does not and cannot validate namespaced payloads. Shape authority for a registered namespace is its record (LEP-0006 section B.2 defines {org}.form.questions: at most 25 entries of question_id/question_text/answer_text, question_text at most 300 and answer_text at most 1000 characters). These are receiver rules, not schema rules: a receiver that implements a registered form.questions namespace MUST validate entries and accept or reject the message (LCP-100), while receivers that do not recognize a namespace ignore its value. Bound hierarchy (LEP-0006 section B.2): the registered form.questions shape ceiling is 133,140 B worst-case UTF-8, receivers SHOULD reject extension totals above the 32 KiB soft policy target (a fully shape-conformant sender can exceed it; issue #197 tracks the re-tune), and the operative hard bound is the transport body cap (max_body_bytes, default 2,000,000 B). Never ping_safe: this field exists only on lead and post - ping/bid/ack keep their strict allowlists - and a platform MUST NOT derive ping attributes, compliance_flags, or any other ping field from extension content. Extension content is lead/post PII-scope content: it inherits section 9 retention and erasure, and question/answer text MUST NOT carry contact values, government identifiers, payment credentials, consent tokens, or evidence values (those have structured homes in consumer, compliance.consent_evidence[], and attachments[]).",
+        "propertyNames": {
+          "not": {
+            "pattern": "^lcp\\.core\\."
+          },
+          "pattern": "^[a-z0-9][a-z0-9_-]*(\\.[a-z0-9][a-z0-9_-]*){2,}$"
+        },
+        "type": "object"
+      },
       "lead_id": {
         "type": "string"
       },

data/lib/schema_validator.rb

@@ -53,8 +53,15 @@ module LcpSdk
       true
     end
 
-    def validate_envelope(envelope)
+    def validate_envelope(envelope, receiver_advertised_lcp_versions: nil)
       validate("schemas/envelope.json", envelope)
+      # Optional SPEC.md §8 capability gate: slot fields toward a receiver that
+      # does not advertise v1.1 are a conformance failure (the v1.0 closed
+      # allowlist cannot parse them).
+      if receiver_advertised_lcp_versions
+        gate_errors = LcpSdk.slot_capability_errors(envelope, receiver_advertised_lcp_versions)
+        raise SchemaValidationError, "LCP capability gate: #{gate_errors.join('; ')}" unless gate_errors.empty?
+      end
       type = envelope.dig("lcp", "message", "type")
       raise SchemaValidationError, "missing lcp.message.type" unless type.is_a?(String)
       payload = envelope.dig("lcp", "payload")

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lcp-sdk
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.1.1
 platform: ruby
 authors:
 - Spear Systems
@@ -64,7 +64,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: LCP Lead Context Protocol SDK
 test_files: []