validpay 1.0.1__tar.gz → 1.2.0__tar.gz

{validpay-1.0.1 → validpay-1.2.0}/CHANGELOG.md

@@ -5,6 +5,27 @@ All notable changes to the ValidPay Python SDK 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).
 
+## [1.1.0] - 2026-06-12
+
+### Changed
+
+- **Split-key protection (Patent C) is now the default** (Prompt 094).
+  `create_intent()` splits the AES key into two XOR shares: Share A is
+  returned as `result.key`, Share B is stored on the ValidPay server.
+  The full decryption key never exists on any single system after the
+  call returns. Pass `split_key=False` for the legacy single-key flow.
+- `verify_intent()` now verifies split-key intents transparently: when
+  the API marks an intent `split_key`, it fetches Share B from the
+  fragment endpoint and XOR-combines it with the key you pass (Share A),
+  instead of raising `split_key_required`. Legacy intents verify exactly
+  as before.
+
+### Deprecated
+
+- `create_split_key_intent()` — now an alias for `create_intent()` (which
+  does split-key by default). Emits `DeprecationWarning`; will be removed
+  in 2.0.
+
 ## [1.0.1] - 2026-06-08
 
 ### Changed

{validpay-1.0.1/validpay.egg-info → validpay-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: validpay
-Version: 1.0.1
+Version: 1.2.0
 Summary: Official ValidPay Python SDK — client-side AES-256-GCM encryption + ValidPay API client
 Author-email: ValidPay <dev@validpay.com>
 License: MIT License
@@ -89,12 +89,15 @@ client = ValidPayClient(api_key="vp_live_xxx")
 
 # Create a single intent — the payload is encrypted locally before
 # anything leaves your process. Only the ciphertext is sent to ValidPay.
+# Split-key protection (Patent C) is the default since 1.1.0: result.key
+# is Share A of the AES key; Share B lives on the ValidPay server. The
+# full decryption key never exists on any single system.
 result = client.create_intent(
     document_type="check",
     payload={"payee": "John Doe", "amount": 1500.00, "check_number": "10042"},
 )
 print(result.retrieval_id)  # vp_abc123def456
-print(result.key)           # base64 AES-256 key — deliver out-of-band
+print(result.key)           # base64 key Share A — embed in the QR / deliver out-of-band
 
 # Create up to 100 intents in one round trip.
 results = client.create_intent_batch([
@@ -143,26 +146,37 @@ timestamps but never enforces them; this preserves the blind intermediary
 model (the server never decides whether a document is "still good").
 
 The same `valid_from` / `valid_until` keyword arguments are accepted by
-`create_intent_batch` (per-item), `create_split_key_intent`, and
-`create_selective_intent`.
+`create_intent_batch` (per-item) and `create_selective_intent`.
 
-### Split-key intents (Patent C)
+### Split-key intents (Patent C) — the default
 
-Splits the AES key into two XOR shares: Share A is returned to the caller
-(typically embedded in the QR code), Share B is stored server-side. Neither
-share alone can decrypt the payload.
+All documents created with SDK v1.1+ use split-key by default: the AES
+key is split into two XOR shares — Share A is returned to the caller
+(typically embedded in the QR code), Share B is stored server-side.
+Neither share alone can decrypt the payload, so the full decryption key
+never exists on any single system.
 
 ```python
-result = client.create_split_key_intent(
+result = client.create_intent(
     document_type="ssn_card",
     payload={"ssn": "123-45-6789"},
 )
-# result.key is Share A — pair it with Share B at verification time.
+# result.key is Share A — verify_intent pairs it with Share B automatically.
 
-verified = client.verify_split_key_intent(result.retrieval_id, result.key)
+verified = client.verify_intent(result.retrieval_id, result.key)
 print(verified.payload)
 ```
 
+#### Backward compatibility
+
+- `create_intent(..., split_key=False)` gives the legacy single-key flow
+  (the returned `key` is the full AES key).
+- `create_split_key_intent()` is a deprecated alias for `create_intent()`
+  — 1.0.x code keeps working, with a `DeprecationWarning`.
+- `verify_intent` detects legacy vs split-key intents from the API
+  response, so it verifies both; `verify_split_key_intent()` also still
+  works.
+
 ### Selective disclosure (Patent E)
 
 Each field is encrypted with its own per-field key. A disclosure policy maps
@@ -207,12 +221,15 @@ for event in history:
 - `session` — optionally provide a `requests.Session` for connection
   pooling, custom adapters, or mocking in tests.
 
-### `client.create_intent(document_type, payload) -> CreateIntentResult`
+### `client.create_intent(document_type, payload, *, split_key=True) -> CreateIntentResult`
 
 Encrypts `payload` (any JSON-serializable value) under a freshly
 generated AES-256 key and registers it with ValidPay. Returns the
-retrieval id and the key. **The key is never sent to ValidPay** — you
-must hand it off out-of-band to whoever needs to verify the intent.
+retrieval id and the key material: **Share A** of the split key by
+default (Share B goes to the server; neither alone decrypts), or the
+full AES key with `split_key=False`. **The full key is never sent to
+ValidPay** — hand the returned key off out-of-band to whoever needs to
+verify the intent.
 
 ### `client.create_intent_batch(intents) -> list[CreateIntentResult]`
 

{validpay-1.0.1 → validpay-1.2.0}/README.md

@@ -33,12 +33,15 @@ client = ValidPayClient(api_key="vp_live_xxx")
 
 # Create a single intent — the payload is encrypted locally before
 # anything leaves your process. Only the ciphertext is sent to ValidPay.
+# Split-key protection (Patent C) is the default since 1.1.0: result.key
+# is Share A of the AES key; Share B lives on the ValidPay server. The
+# full decryption key never exists on any single system.
 result = client.create_intent(
     document_type="check",
     payload={"payee": "John Doe", "amount": 1500.00, "check_number": "10042"},
 )
 print(result.retrieval_id)  # vp_abc123def456
-print(result.key)           # base64 AES-256 key — deliver out-of-band
+print(result.key)           # base64 key Share A — embed in the QR / deliver out-of-band
 
 # Create up to 100 intents in one round trip.
 results = client.create_intent_batch([
@@ -87,26 +90,37 @@ timestamps but never enforces them; this preserves the blind intermediary
 model (the server never decides whether a document is "still good").
 
 The same `valid_from` / `valid_until` keyword arguments are accepted by
-`create_intent_batch` (per-item), `create_split_key_intent`, and
-`create_selective_intent`.
+`create_intent_batch` (per-item) and `create_selective_intent`.
 
-### Split-key intents (Patent C)
+### Split-key intents (Patent C) — the default
 
-Splits the AES key into two XOR shares: Share A is returned to the caller
-(typically embedded in the QR code), Share B is stored server-side. Neither
-share alone can decrypt the payload.
+All documents created with SDK v1.1+ use split-key by default: the AES
+key is split into two XOR shares — Share A is returned to the caller
+(typically embedded in the QR code), Share B is stored server-side.
+Neither share alone can decrypt the payload, so the full decryption key
+never exists on any single system.
 
 ```python
-result = client.create_split_key_intent(
+result = client.create_intent(
     document_type="ssn_card",
     payload={"ssn": "123-45-6789"},
 )
-# result.key is Share A — pair it with Share B at verification time.
+# result.key is Share A — verify_intent pairs it with Share B automatically.
 
-verified = client.verify_split_key_intent(result.retrieval_id, result.key)
+verified = client.verify_intent(result.retrieval_id, result.key)
 print(verified.payload)
 ```
 
+#### Backward compatibility
+
+- `create_intent(..., split_key=False)` gives the legacy single-key flow
+  (the returned `key` is the full AES key).
+- `create_split_key_intent()` is a deprecated alias for `create_intent()`
+  — 1.0.x code keeps working, with a `DeprecationWarning`.
+- `verify_intent` detects legacy vs split-key intents from the API
+  response, so it verifies both; `verify_split_key_intent()` also still
+  works.
+
 ### Selective disclosure (Patent E)
 
 Each field is encrypted with its own per-field key. A disclosure policy maps
@@ -151,12 +165,15 @@ for event in history:
 - `session` — optionally provide a `requests.Session` for connection
   pooling, custom adapters, or mocking in tests.
 
-### `client.create_intent(document_type, payload) -> CreateIntentResult`
+### `client.create_intent(document_type, payload, *, split_key=True) -> CreateIntentResult`
 
 Encrypts `payload` (any JSON-serializable value) under a freshly
 generated AES-256 key and registers it with ValidPay. Returns the
-retrieval id and the key. **The key is never sent to ValidPay** — you
-must hand it off out-of-band to whoever needs to verify the intent.
+retrieval id and the key material: **Share A** of the split key by
+default (Share B goes to the server; neither alone decrypts), or the
+full AES key with `split_key=False`. **The full key is never sent to
+ValidPay** — hand the returned key off out-of-band to whoever needs to
+verify the intent.
 
 ### `client.create_intent_batch(intents) -> list[CreateIntentResult]`
 

{validpay-1.0.1 → validpay-1.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "validpay"
-version = "1.0.1"
+version = "1.2.0"
 description = "Official ValidPay Python SDK — client-side AES-256-GCM encryption + ValidPay API client"
 readme = "README.md"
 license = { file = "LICENSE" }

{validpay-1.0.1 → validpay-1.2.0}/validpay/__init__.py

@@ -14,6 +14,7 @@ from .binding import (
 )
 from .client import ValidPayClient
 from .crypto import (
+    build_aad,
     build_key_map,
     combine_key_shares,
     compute_commitment_hash,
@@ -37,6 +38,7 @@ __all__ = [
     "encrypt",
     "decrypt",
     "compute_commitment_hash",
+    "build_aad",
     "split_key",
     "combine_key_shares",
     "encrypt_fields",
@@ -49,4 +51,4 @@ __all__ = [
     "OfflineVerifyResult",
 ]
 
-__version__ = "1.0.1"
+__version__ = "1.2.0"

{validpay-1.0.1 → validpay-1.2.0}/validpay/client.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import json
+import warnings
 from typing import Any, Dict, Iterable, List, Mapping, Optional
 from urllib.parse import quote
 
@@ -9,6 +10,7 @@ import requests
 from ._timelock import compute_time_lock_status as _compute_time_lock_status
 from ._timelock import validate_time_lock as _validate_time_lock
 from .crypto import (
+    build_aad,
     build_key_map,
     combine_key_shares,
     compute_commitment_hash,
@@ -26,6 +28,42 @@ DEFAULT_BASE_URL = "https://api.validpay.com"
 DEFAULT_TIMEOUT = 30.0
 
 
+def _verify_commitment(data: Mapping[str, Any]) -> bool:
+    """Version-aware commitment check (Prompt 097 C-1).
+
+    v2 commitments are SHA-256(ciphertext): recompute over the received
+    ``encrypted_payload`` and compare. v1 (legacy SHA-256(plaintext)) is a
+    confirmation-oracle risk and is intentionally skipped — those documents
+    expire naturally. Returns whether integrity was confirmed; raises on a
+    v2 mismatch (the ciphertext was swapped after issuance).
+    """
+    commitment_hash = data.get("commitment_hash")
+    version = data.get("commitment_version", 1)
+    if not commitment_hash or not isinstance(version, int) or version < 2:
+        return False
+    if compute_commitment_hash(data["encrypted_payload"]) != commitment_hash:
+        raise ValidPayError(
+            "integrity_failure",
+            "INTEGRITY VERIFICATION FAILED — the ciphertext does not match the "
+            "commitment hash recorded at issuance. This document may have been "
+            "tampered with.",
+        )
+    return True
+
+
+def _aad_for(data: Mapping[str, Any]) -> Optional[str]:
+    """AAD to pass to decrypt (Prompt 097 M-5). For v2 intents, reconstruct it
+    from the server-returned metadata so a server that altered document_type
+    or the validity window fails the GCM tag check. None for legacy v1."""
+    if not isinstance(data.get("encryption_version"), int) or data["encryption_version"] < 2:
+        return None
+    return build_aad(
+        data.get("document_type", ""),
+        data.get("valid_from"),
+        data.get("valid_until"),
+    )
+
+
 class ValidPayClient:
     """Client for the ValidPay API.
 
@@ -57,9 +95,17 @@ class ValidPayClient:
         *,
         valid_from: Optional[str] = None,
         valid_until: Optional[str] = None,
+        split_key: bool = True,
     ) -> CreateIntentResult:
         """Encrypt ``payload`` locally and register it with the ValidPay API.
 
+        As of SDK 1.1.0 this uses **split-key protection (Patent C) by
+        default**: the AES-256 key is split into two XOR shares — Share A
+        is returned to you (embed it in the QR code exactly as you would
+        the key before), Share B is stored on the ValidPay server. The
+        full decryption key never exists on any single system after this
+        call returns.
+
         Args:
             document_type: A short string identifying the document kind
                 (``"check"``, ``"money_order"``, ``"ssn_card"``, etc.).
@@ -71,25 +117,41 @@ class ValidPayClient:
                 Verification, blind intermediary preserved).
             valid_until: Optional ISO-8601 timestamp. The verifier surfaces
                 "expired" status after this time.
+            split_key: Default ``True``. Set ``False`` for the legacy
+                single-key flow, where ``key`` in the result is the full
+                AES key. Verification of legacy intents is unchanged.
 
         Returns:
             A :class:`CreateIntentResult` containing the retrieval id and
-            the freshly-generated AES key (base64).
+            the key material (base64): **Share A** when ``split_key=True``
+            (the default), the full AES key when ``split_key=False``.
         """
         if not document_type:
             raise ValidPayError("invalid_argument", "document_type is required")
         _validate_time_lock(valid_from, valid_until)
 
-        key = generate_key()
+        full_key = generate_key()
+        share_b: Optional[str] = None
+        result_key = full_key
+        if split_key:
+            result_key, share_b = split_key_fn(full_key)
+
         plaintext = json.dumps(payload)
-        commitment_hash = compute_commitment_hash(plaintext)
-        encrypted_payload = encrypt(plaintext, key)
+        # M-5: bind document_type + validity window as AAD.
+        aad = build_aad(document_type, valid_from, valid_until)
+        encrypted_payload = encrypt(plaintext, full_key, aad)
+        # Commitment v2: hash the ciphertext, not the plaintext (C-1).
+        commitment_hash = compute_commitment_hash(encrypted_payload)
 
         body: Dict[str, Any] = {
             "document_type": document_type,
             "encrypted_payload": encrypted_payload,
             "commitment_hash": commitment_hash,
+            "encryption_version": 2,
         }
+        if split_key:
+            body["split_key"] = True
+            body["key_fragment_b"] = share_b
         if valid_from is not None:
             body["valid_from"] = valid_from
         if valid_until is not None:
@@ -110,7 +172,7 @@ class ValidPayClient:
                 details=data,
             )
 
-        return CreateIntentResult(retrieval_id=retrieval_id, key=key)
+        return CreateIntentResult(retrieval_id=retrieval_id, key=result_key)
 
     def create_intent_batch(
         self,
@@ -162,10 +224,15 @@ class ValidPayClient:
             key = generate_key()
             keys.append(key)
             plaintext = json.dumps(item["payload"])
+            # M-5: bind document_type + validity window as AAD per item.
+            aad = build_aad(doc_type, valid_from, valid_until)
+            encrypted_payload = encrypt(plaintext, key, aad)
             req_item: Dict[str, Any] = {
                 "document_type": doc_type,
-                "encrypted_payload": encrypt(plaintext, key),
-                "commitment_hash": compute_commitment_hash(plaintext),
+                "encrypted_payload": encrypted_payload,
+                # Commitment v2: hash the ciphertext, not the plaintext (C-1).
+                "commitment_hash": compute_commitment_hash(encrypted_payload),
+                "encryption_version": 2,
             }
             if valid_from is not None:
                 req_item["valid_from"] = valid_from
@@ -200,6 +267,32 @@ class ValidPayClient:
             out.append(CreateIntentResult(retrieval_id=retrieval_id, key=keys[i]))
         return out
 
+    def _fetch_fragment_b(self, retrieval_id: str) -> str:
+        """Fetch Share B from the public fragment endpoint (Patent C)."""
+        fragment_data = self._request(
+            "GET",
+            f"/v1/intent/{quote(retrieval_id, safe='')}/fragment",
+            auth=False,
+        )
+        if isinstance(fragment_data, dict) and fragment_data.get("error"):
+            raise ValidPayError(
+                str(fragment_data.get("error")),
+                f"Fragment retrieval failed: {fragment_data.get('error')}",
+                details=fragment_data,
+            )
+        share_b = (
+            fragment_data.get("fragment_b")
+            if isinstance(fragment_data, dict)
+            else None
+        )
+        if not share_b:
+            raise ValidPayError(
+                "missing_fragment",
+                "Server did not return key fragment",
+                details=fragment_data,
+            )
+        return share_b
+
     def verify_intent(
         self,
         retrieval_id: str,
@@ -258,33 +351,21 @@ class ValidPayClient:
                 "Use verify_selective_intent(retrieval_id, key, role) instead of verify_intent().",
             )
 
-        # Split-Key Verification (Patent C). The caller passed a single key,
-        # but this intent was issued with a key split into two shares —
-        # verify_intent doesn't have enough information to reconstruct.
+        # Split-Key Verification (Patent C). Since 1.1.0 split-key is the
+        # default issue path, so the key the caller holds is Share A —
+        # fetch Share B from the fragment endpoint and XOR-combine, so
+        # create_intent -> verify_intent round-trips keep working.
         if data.get("split_key"):
-            raise ValidPayError(
-                "split_key_required",
-                f"Intent {retrieval_id} uses split-key protection. "
-                "Use verify_split_key_intent(retrieval_id, share_a) instead of verify_intent().",
-            )
+            key = combine_key_shares(key, self._fetch_fragment_b(retrieval_id))
 
-        decrypted = decrypt(data["encrypted_payload"], key)
+        # Commitment check over the ciphertext (C-1) — proves the server
+        # hasn't swapped the blob. Done before decryption since it no longer
+        # needs the plaintext. Legacy v1 intents skip this check.
+        integrity_verified = _verify_commitment(data)
 
-        # Hybrid Commitment Scheme — proves the server hasn't swapped the
-        # ciphertext. Server is blind so it can't forge a matching hash.
-        # Legacy intents (no hash stored) still verify, just without this check.
-        commitment_hash = data.get("commitment_hash")
-        integrity_verified = False
-        if commitment_hash:
-            actual_hash = compute_commitment_hash(decrypted)
-            if actual_hash != commitment_hash:
-                raise ValidPayError(
-                    "integrity_failure",
-                    "INTEGRITY VERIFICATION FAILED — the decrypted payload does not match "
-                    "the commitment hash stored at issuance. This may indicate server-side "
-                    "tampering or payload corruption.",
-                )
-            integrity_verified = True
+        # M-5: pass the reconstructed AAD for v2 intents so altered metadata
+        # fails the GCM tag check.
+        decrypted = decrypt(data["encrypted_payload"], key, _aad_for(data))
 
         try:
             payload = json.loads(decrypted)
@@ -319,63 +400,26 @@ class ValidPayClient:
         valid_from: Optional[str] = None,
         valid_until: Optional[str] = None,
     ) -> CreateIntentResult:
-        """Create an intent with split-key protection (Patent C).
-
-        The AES-256 key is split into two XOR shares. Share A is returned
-        to the caller (for embedding in the QR code). Share B is stored on
-        the ValidPay server. Neither share alone can decrypt the payload —
-        both are required at verification time.
+        """Deprecated alias for :meth:`create_intent` (since SDK 1.1.0).
 
-        The full key exists only transiently in this process; it is never
-        persisted, never sent over the wire, and never logged.
-
-        Args:
-            document_type: A short string identifying the document kind.
-            payload: Any JSON-serializable object.
-
-        Returns:
-            A :class:`CreateIntentResult` whose ``key`` is **Share A**, not
-            the full key. Embed it in the QR code as you would the regular key.
+        Split-key protection (Patent C) is the default for
+        ``create_intent`` now, so this method adds nothing. It is kept so
+        1.0.x code keeps working; new code should call ``create_intent``.
         """
-        if not document_type:
-            raise ValidPayError("invalid_argument", "document_type is required")
-        _validate_time_lock(valid_from, valid_until)
-
-        full_key = generate_key()
-        share_a, share_b = split_key_fn(full_key)
-
-        plaintext = json.dumps(payload)
-        commitment_hash = compute_commitment_hash(plaintext)
-        encrypted_payload = encrypt(plaintext, full_key)
-
-        body: Dict[str, Any] = {
-            "document_type": document_type,
-            "encrypted_payload": encrypted_payload,
-            "commitment_hash": commitment_hash,
-            "split_key": True,
-            "key_fragment_b": share_b,
-        }
-        if valid_from is not None:
-            body["valid_from"] = valid_from
-        if valid_until is not None:
-            body["valid_until"] = valid_until
-
-        data = self._request(
-            "POST",
-            "/v1/intent",
-            body=body,
-            auth=True,
+        warnings.warn(
+            "create_split_key_intent() is deprecated since validpay 1.1.0: "
+            "create_intent() uses split-key protection by default. Call "
+            "create_intent() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.create_intent(
+            document_type,
+            payload,
+            valid_from=valid_from,
+            valid_until=valid_until,
+            split_key=True,
         )
-
-        retrieval_id = data.get("retrieval_id") if isinstance(data, dict) else None
-        if not retrieval_id:
-            raise ValidPayError(
-                "invalid_response",
-                "API response missing retrieval_id",
-                details=data,
-            )
-
-        return CreateIntentResult(retrieval_id=retrieval_id, key=share_a)
 
     def verify_split_key_intent(
         self,
@@ -425,43 +469,14 @@ class ValidPayClient:
                 },
             )
 
-        fragment_data = self._request(
-            "GET",
-            f"/v1/intent/{quote(retrieval_id, safe='')}/fragment",
-            auth=False,
-        )
-        if isinstance(fragment_data, dict) and fragment_data.get("error"):
-            raise ValidPayError(
-                str(fragment_data.get("error")),
-                f"Fragment retrieval failed: {fragment_data.get('error')}",
-                details=fragment_data,
-            )
-        share_b = (
-            fragment_data.get("fragment_b")
-            if isinstance(fragment_data, dict)
-            else None
-        )
-        if not share_b:
-            raise ValidPayError(
-                "missing_fragment",
-                "Server did not return key fragment",
-                details=fragment_data,
-            )
+        share_b = self._fetch_fragment_b(retrieval_id)
 
-        full_key = combine_key_shares(share_a, share_b)
-        decrypted = decrypt(data["encrypted_payload"], full_key)
+        # Commitment check over the ciphertext (C-1); legacy v1 skips.
+        integrity_verified = _verify_commitment(data)
 
-        commitment_hash = data.get("commitment_hash")
-        integrity_verified = False
-        if commitment_hash:
-            actual_hash = compute_commitment_hash(decrypted)
-            if actual_hash != commitment_hash:
-                raise ValidPayError(
-                    "integrity_failure",
-                    "INTEGRITY VERIFICATION FAILED — the decrypted payload does not match "
-                    "the commitment hash stored at issuance.",
-                )
-            integrity_verified = True
+        full_key = combine_key_shares(share_a, share_b)
+        # M-5: AAD bound for v2 intents.
+        decrypted = decrypt(data["encrypted_payload"], full_key, _aad_for(data))
 
         try:
             payload = json.loads(decrypted)
@@ -543,9 +558,11 @@ class ValidPayClient:
         key_map = build_key_map(field_keys, disclosure_policy)
         encrypted_key_map = encrypt(json.dumps(key_map), master_key)
 
-        full_plaintext = json.dumps(payload)
-        commitment_hash = compute_commitment_hash(full_plaintext)
         envelope = json.dumps(encrypted_fields)
+        # Commitment v2: hash the transported ciphertext envelope, not the
+        # plaintext (C-1). Role-independent — the server hashes this exact
+        # string and the verifier recomputes it.
+        commitment_hash = compute_commitment_hash(envelope)
 
         qr_key = master_key
         key_fragment_b: Optional[str] = None
@@ -692,20 +709,10 @@ class ValidPayClient:
 
         payload = decrypt_fields(encrypted_fields, field_keys)
 
-        integrity_verified = False
-        commitment_hash = data.get("commitment_hash")
-        if commitment_hash and role == "full":
-            all_keys = key_map.get("full", {})
-            full_payload = decrypt_fields(encrypted_fields, all_keys)
-            full_plaintext = json.dumps(full_payload)
-            actual_hash = compute_commitment_hash(full_plaintext)
-            if actual_hash != commitment_hash:
-                raise ValidPayError(
-                    "integrity_failure",
-                    "INTEGRITY VERIFICATION FAILED — the decrypted payload does not match "
-                    "the commitment hash stored at issuance.",
-                )
-            integrity_verified = True
+        # Commitment over the ciphertext envelope (C-1) — role-independent
+        # now, since it no longer requires decrypting the full payload.
+        # Legacy v1 intents skip this check.
+        integrity_verified = _verify_commitment(data)
 
         valid_from_str = data.get("valid_from")
         valid_until_str = data.get("valid_until")

{validpay-1.0.1 → validpay-1.2.0}/validpay/crypto.py

@@ -75,16 +75,20 @@ def combine_key_shares(share_a: str, share_b: str) -> str:
     return base64.b64encode(key_bytes).decode("ascii")
 
 
-def compute_commitment_hash(plaintext: str) -> str:
-    """SHA-256 commitment hash of the plaintext payload (Hybrid Commitment Scheme).
-
-    Computed at issuance and stored alongside the ciphertext on the server.
-    At verification time, the same hash is recomputed against the freshly
-    decrypted plaintext; a mismatch proves the server tampered with or
-    swapped the ciphertext, since SHA-256 is one-way and the server cannot
-    forge a matching hash without the decryption key.
+def compute_commitment_hash(ciphertext_b64: str) -> str:
+    """SHA-256 commitment hash over the *ciphertext* blob (commitment v2).
+
+    Pass the base64 ValidPay wire blob returned by :func:`encrypt` — NOT the
+    plaintext. Hashing the ciphertext lets the server publish the commitment
+    on the public verify endpoint without creating a confirmation oracle:
+    SHA-256(plaintext) over a low-entropy structured document (a check, an
+    SSN card) can be brute-forced offline to recover contents without the
+    key, which broke the "we cannot read your documents" promise (Prompt 097
+    C-1). The commitment still proves the server hasn't swapped the blob
+    between issuance and verification — the verifier recomputes
+    SHA-256(ciphertext) and compares.
     """
-    return hashlib.sha256(plaintext.encode("utf-8")).hexdigest()
+    return hashlib.sha256(ciphertext_b64.encode("utf-8")).hexdigest()
 
 
 def _decode_key(key: str) -> bytes:
@@ -100,26 +104,36 @@ def _decode_key(key: str) -> bytes:
     return buf
 
 
-def encrypt(plaintext: str, key: str) -> str:
+def encrypt(plaintext: str, key: str, aad: str | None = None) -> str:
     """Encrypt ``plaintext`` (UTF-8) with the given base64 AES-256 key.
 
     Returns a base64 string in the ValidPay wire format::
 
         base64(iv[12] || authTag[16] || ciphertext)
+
+    ``aad`` (Prompt 097 M-5) is optional Associated Authenticated Data — when
+    supplied, the same string MUST be passed to :func:`decrypt` or the GCM tag
+    check fails. Use :func:`build_aad` to bind document metadata.
     """
     key_bytes = _decode_key(key)
     iv = os.urandom(_IV_BYTES)
     aesgcm = AESGCM(key_bytes)
+    aad_bytes = aad.encode("utf-8") if aad else None
     # cryptography's AESGCM.encrypt returns ``ciphertext || authTag``.
     # Rearrange to match the ValidPay/Node wire format: iv || authTag || ciphertext.
-    ct_with_tag = aesgcm.encrypt(iv, plaintext.encode("utf-8"), None)
+    ct_with_tag = aesgcm.encrypt(iv, plaintext.encode("utf-8"), aad_bytes)
     auth_tag = ct_with_tag[-_TAG_BYTES:]
     ciphertext = ct_with_tag[:-_TAG_BYTES]
     return base64.b64encode(iv + auth_tag + ciphertext).decode("ascii")
 
 
-def decrypt(blob: str, key: str) -> str:
-    """Decrypt a ValidPay-format base64 blob and return the plaintext (UTF-8)."""
+def decrypt(blob: str, key: str, aad: str | None = None) -> str:
+    """Decrypt a ValidPay-format base64 blob and return the plaintext (UTF-8).
+
+    ``aad`` must match the value passed to :func:`encrypt` (Prompt 097 M-5);
+    a mismatch (e.g. a server that altered the bound metadata) raises
+    ``decryption_failed``.
+    """
     key_bytes = _decode_key(key)
 
     try:
@@ -138,17 +152,56 @@ def decrypt(blob: str, key: str) -> str:
     ciphertext = buf[_IV_BYTES + _TAG_BYTES:]
 
     aesgcm = AESGCM(key_bytes)
+    aad_bytes = aad.encode("utf-8") if aad else None
     try:
-        plaintext = aesgcm.decrypt(iv, ciphertext + auth_tag, None)
+        plaintext = aesgcm.decrypt(iv, ciphertext + auth_tag, aad_bytes)
     except InvalidTag as exc:
         raise ValidPayError(
             "decryption_failed",
-            "Decryption failed — wrong key or tampered blob",
+            "Decryption failed — wrong key, tampered blob, or altered bound metadata",
         ) from exc
 
     return plaintext.decode("utf-8")
 
 
+def build_aad(
+    document_type: str,
+    valid_from: str | None = None,
+    valid_until: str | None = None,
+) -> str:
+    """Canonical AAD for AES-GCM metadata binding (Prompt 097 M-5).
+
+    Binds ``document_type`` and the validity window so a blind/compromised
+    server cannot silently alter them (e.g. change "check" to "other"). The
+    output MUST be byte-identical across every SDK and the website verifier,
+    so:
+
+      - keys are emitted in a fixed order (document_type, valid_from, valid_until);
+      - JSON is compact (no spaces) — matches JS ``JSON.stringify``;
+      - timestamps are normalized to **epoch milliseconds** rather than raw
+        ISO strings. The server reformats timestamps (``2026-08-01T00:00:00Z``
+        becomes ``...:00.000Z``), so binding the raw string would break
+        verification of legitimate time-locked documents. Epoch ms parse
+        identically on both sides regardless of ISO formatting.
+    """
+    payload = {
+        "document_type": document_type,
+        "valid_from": _epoch_ms(valid_from),
+        "valid_until": _epoch_ms(valid_until),
+    }
+    return json.dumps(payload, separators=(",", ":"))
+
+
+def _epoch_ms(iso: str | None) -> int | None:
+    if not iso:
+        return None
+    from datetime import datetime
+
+    # Accept the trailing 'Z' (UTC) that fromisoformat rejected before 3.11.
+    parsed = datetime.fromisoformat(iso.replace("Z", "+00:00"))
+    return int(parsed.timestamp() * 1000)
+
+
 def encrypt_fields(payload: dict, generate_key_fn=None) -> tuple[dict, dict]:
     """Encrypt each field in payload separately (Selective Field Disclosure, Patent E).
 

{validpay-1.0.1 → validpay-1.2.0/validpay.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: validpay
-Version: 1.0.1
+Version: 1.2.0
 Summary: Official ValidPay Python SDK — client-side AES-256-GCM encryption + ValidPay API client
 Author-email: ValidPay <dev@validpay.com>
 License: MIT License
@@ -89,12 +89,15 @@ client = ValidPayClient(api_key="vp_live_xxx")
 
 # Create a single intent — the payload is encrypted locally before
 # anything leaves your process. Only the ciphertext is sent to ValidPay.
+# Split-key protection (Patent C) is the default since 1.1.0: result.key
+# is Share A of the AES key; Share B lives on the ValidPay server. The
+# full decryption key never exists on any single system.
 result = client.create_intent(
     document_type="check",
     payload={"payee": "John Doe", "amount": 1500.00, "check_number": "10042"},
 )
 print(result.retrieval_id)  # vp_abc123def456
-print(result.key)           # base64 AES-256 key — deliver out-of-band
+print(result.key)           # base64 key Share A — embed in the QR / deliver out-of-band
 
 # Create up to 100 intents in one round trip.
 results = client.create_intent_batch([
@@ -143,26 +146,37 @@ timestamps but never enforces them; this preserves the blind intermediary
 model (the server never decides whether a document is "still good").
 
 The same `valid_from` / `valid_until` keyword arguments are accepted by
-`create_intent_batch` (per-item), `create_split_key_intent`, and
-`create_selective_intent`.
+`create_intent_batch` (per-item) and `create_selective_intent`.
 
-### Split-key intents (Patent C)
+### Split-key intents (Patent C) — the default
 
-Splits the AES key into two XOR shares: Share A is returned to the caller
-(typically embedded in the QR code), Share B is stored server-side. Neither
-share alone can decrypt the payload.
+All documents created with SDK v1.1+ use split-key by default: the AES
+key is split into two XOR shares — Share A is returned to the caller
+(typically embedded in the QR code), Share B is stored server-side.
+Neither share alone can decrypt the payload, so the full decryption key
+never exists on any single system.
 
 ```python
-result = client.create_split_key_intent(
+result = client.create_intent(
     document_type="ssn_card",
     payload={"ssn": "123-45-6789"},
 )
-# result.key is Share A — pair it with Share B at verification time.
+# result.key is Share A — verify_intent pairs it with Share B automatically.
 
-verified = client.verify_split_key_intent(result.retrieval_id, result.key)
+verified = client.verify_intent(result.retrieval_id, result.key)
 print(verified.payload)
 ```
 
+#### Backward compatibility
+
+- `create_intent(..., split_key=False)` gives the legacy single-key flow
+  (the returned `key` is the full AES key).
+- `create_split_key_intent()` is a deprecated alias for `create_intent()`
+  — 1.0.x code keeps working, with a `DeprecationWarning`.
+- `verify_intent` detects legacy vs split-key intents from the API
+  response, so it verifies both; `verify_split_key_intent()` also still
+  works.
+
 ### Selective disclosure (Patent E)
 
 Each field is encrypted with its own per-field key. A disclosure policy maps
@@ -207,12 +221,15 @@ for event in history:
 - `session` — optionally provide a `requests.Session` for connection
   pooling, custom adapters, or mocking in tests.
 
-### `client.create_intent(document_type, payload) -> CreateIntentResult`
+### `client.create_intent(document_type, payload, *, split_key=True) -> CreateIntentResult`
 
 Encrypts `payload` (any JSON-serializable value) under a freshly
 generated AES-256 key and registers it with ValidPay. Returns the
-retrieval id and the key. **The key is never sent to ValidPay** — you
-must hand it off out-of-band to whoever needs to verify the intent.
+retrieval id and the key material: **Share A** of the split key by
+default (Share B goes to the server; neither alone decrypts), or the
+full AES key with `split_key=False`. **The full key is never sent to
+ValidPay** — hand the returned key off out-of-band to whoever needs to
+verify the intent.
 
 ### `client.create_intent_batch(intents) -> list[CreateIntentResult]`