validpay 1.1.0__tar.gz → 1.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: validpay
-Version: 1.1.0
+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

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "validpay"
-version = "1.1.0"
+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.1.0 → 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.1.0 → validpay-1.2.0}/validpay/client.py

@@ -10,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,
@@ -27,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.
 
@@ -100,13 +137,17 @@ class ValidPayClient:
             result_key, share_b = split_key_fn(full_key)
 
         plaintext = json.dumps(payload)
-        commitment_hash = compute_commitment_hash(plaintext)
-        encrypted_payload = encrypt(plaintext, full_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
@@ -183,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
@@ -312,23 +358,14 @@ class ValidPayClient:
         if data.get("split_key"):
             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)
@@ -434,20 +471,12 @@ class ValidPayClient:
 
         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)
@@ -529,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
@@ -678,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.1.0 → 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.1.0 → validpay-1.2.0/validpay.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: validpay
-Version: 1.1.0
+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