easycontract 0.1.0__tar.gz → 0.1.1__tar.gz

easycontract-0.1.1/CHANGELOG.md

@@ -0,0 +1,114 @@
+# Changelog
+
+All notable changes to the `easycontract` Python SDK.
+
+## 0.1.1 (2026-10-07)
+
+**Security (audit 2026-10-07)**
+
+- `requests>=2.33.0,<3` (was `>=2.31`): older `requests` releases are affected
+  by CVE-2024-35195, CVE-2024-47081 and CVE-2026-25645.
+- Resource identifiers are validated as UUIDs before a path is built, and
+  free-text segments (catalog keys, language codes) are percent-encoded: an
+  id such as `"abc/../../webhooks/123"` used to make `requests` resolve the
+  dot segments and call ANOTHER endpoint with the caller's API key. Invalid
+  ids now raise `ValueError` before any request is sent.
+
+**Features**
+
+- Asynchronous malware scan of uploaded documents: `document["scan"]`
+  (`status` pending/clean/infected/error/not_scanned, `engine`, `signature`,
+  `scanned_at`), event `document.scanned`, and
+  `client.envelopes.rescan_document(envelope_id, document_id)` to retry a
+  failed scan. Signers only see and sign documents once they are clean.
+- Invitation e-mails are held back until the malware verdict:
+  `signer["link_delivery"] == "pending_scan"` while waiting (the `sign_url`
+  values stay valid); `envelope["void_reason_code"] == "malware_detected"`
+  when the platform stopped an envelope.
+- Identity images retention mode: `envelopes.create(..., kyc_images_retention=
+  "after_in_person_check")` (also on `templates.create`/`update` and
+  `templates.create_envelope`) keeps a verified signer's document/selfie
+  images until the requester records the face-to-face check with
+  `client.identity.confirm_in_person(envelope_id, signer_id, note=...)`
+  (event `signer.kyc_confirmed_in_person`); the default "after_review" purges
+  N days after the reviewer's decision. `identity_verification` carries
+  `images_retention` and `confirmed_in_person`.
+- Embedded signing (§10.3): `client.organization.update(embed_allowed_origins=[...])`
+  registers the web origins allowed to frame the signer flow, and
+  `client.envelopes.create_embedded_session(envelope_id, signer_id, origin=...,
+  return_url=..., language=..., ttl_minutes=...)` mints the ephemeral `url`
+  (token `em_…`) to open in an `<iframe allow="camera">` (postMessage events
+  `ready`/`signed`/`declined`/`expired`) or by redirect (`return_url`). The
+  organization exposes `embed_allowed_origins`.
+- Biometrics (Enterprise): `envelopes.create(..., biometrics=True)` and
+  `templates.create_envelope(..., biometrics=True)` offer signers the optional
+  stroke capture; `signer["biometrics"]` carries its status (hash, points,
+  consent version, `erased_at`), never the vector;
+  `envelopes.erase_signer_biometrics(envelope_id, signer_id, reason=...)`
+  erases it (GDPR art. 17); `download_evidence(..., include_biometrics=True)`
+  adds the vectors to the ZIP on explicit request.
+- `envelopes.create(..., language=...)` sets the document language.
+- Identity proofing (Pro+): `auth_methods` accepts `"kyc"` on signers and
+  template roles; `signer["identity_verification"]` carries the status
+  (provider, method, document type/country, name match, hash), never the
+  provider payload; `download_evidence(..., include_identity_proofs=True)` adds
+  the full results to the ZIP on explicit request. The organization exposes
+  `kyc` (switch state) and `features.kyc`.
+- In-house identity review: `client.identity.pending_reviews()`,
+  `client.identity.get(envelope_id, signer_id)`,
+  `client.identity.download_document(envelope_id, signer_id, document_id)`
+  (every download is recorded in the evidence trail) and
+  `client.identity.review(envelope_id, signer_id, decision="approve"|"reject",
+  verified_name=..., reason=...)`. `identity_verification` now carries
+  `checks`, `documents` (hashes, never the images), `reviewed_by` and
+  `images_purge_at`; `download_evidence(..., include_identity_proofs=True)`
+  also adds the images still retained.
+- `envelopes.add_signer(..., kyc_document_type=..., kyc_document_number=...)`
+  registers what the requester knows about the signer's document; a
+  different declaration is refused at capture. Signers expose
+  `kyc_expected_document_type` and `kyc_expected_document_number_set`.
+- Identity endpoints (`identity.pending_reviews()`, `identity.get()`) now
+  return `declared_document_number`, `verified_name` and `signer_full_name`
+  so the tenant can validate on its own platform; the signer summary inside
+  envelopes keeps status only. New outbound events `signer.kyc_submitted`,
+  `signer.kyc_verified` and `signer.kyc_failed` (webhooks and `GET /events/`).
+- Retention: `envelopes.create(..., document_type=...)` (catalogue in
+  `retention.document_types()`, unsuitable types are refused, caution types
+  carry `document_type_warning`), `envelopes.set_legal_hold(envelope_id,
+  reason=...)` / `release_legal_hold()`, `retention.overview(within_days=90)`
+  and `organization.update(retention_policies={...})`. Envelopes expose
+  `document_type`, `document_type_warning` and `legal_hold`; new outbound
+  event `envelope.blocked` is documented.
+
+- `envelopes.download_final_document(envelope_id, document_id, to=None)`:
+  downloads the stamped final PDF of one document (PAdES-B-LTA sealed on the
+  Enterprise plan). Seal details are exposed under `documents[].final.pades`
+  when fetching the envelope with `expand=["documents"]`.
+
+## 0.1.0 (2026-09-25) — published: https://pypi.org/project/easycontract/0.1.0/
+
+Initial release.
+
+- `EasyContract` client: `X-Api-Key` auth, per-POST `Idempotency-Key`,
+  bounded retries (429 + GET 5xx) honoring `Retry-After`, typed RFC 7807
+  error hierarchy, context-manager support (`close()`).
+- Full resource coverage of the v1 API (envelopes, templates, webhooks,
+  events, organization, members, invitations) with cursor auto-paging and
+  anti-loop guards.
+- `webhooks.verify_signature`: fail-closed HMAC-SHA256 with timestamp
+  replay check.
+
+### Behaviour notes
+
+- `idempotency_key` accepts a non-empty `str` (sent as-is), `None` or
+  `True` (a random UUID is generated per call), or `False` (header
+  omitted). Any other value is coerced with `str()` (e.g. a `uuid.UUID`
+  is sent as its string form).
+- File uploads: seekable files are re-wound and re-sent in full on
+  retries; non-seekable streams (pipes, sockets) are sent exactly once —
+  a 429 on such an upload raises `RateLimitError` instead of retrying
+  with an empty body.
+- `webhooks.verify_signature` verifies over the raw request bytes; the
+  payload is decoded only after the HMAC check passes.
+- `tolerance=None` in `verify_signature` disables the timestamp replay
+  check (opt-out; not recommended).

{easycontract-0.1.0 → easycontract-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: easycontract
-Version: 0.1.0
+Version: 0.1.1
 Summary: SDK oficial de Python para el API de easycontract (firma electrónica eIDAS)
 Project-URL: Documentation, https://easycontract.online/docs/api
 Author-email: Román Ramírez <roman@easycontract.online>
@@ -18,7 +18,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Security
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
-Requires-Dist: requests<3,>=2.31
+Requires-Dist: requests<3,>=2.33.0
 Description-Content-Type: text/markdown
 
 # easycontract — SDK de Python
@@ -81,8 +81,17 @@ client.templates.add_field(
 
 ## Receta 2 — Firma embebida (embedded signing)
 
-Con `deliver_emails=False` recibes el `sign_url` de un solo uso por firmante y
-lo integras en tu propia aplicación (redirect o iframe):
+El firmante firma dentro de tu aplicación (el caso RootedArbiter). Tres pasos:
+
+1. Registra una vez los orígenes de tu web (https; `http://localhost:…` solo
+   en desarrollo). La lista se sustituye entera:
+
+```python
+client.organization.update(embed_allowed_origins=["https://arbiter.rootedcon.com"])
+```
+
+2. Envía sin emails y, cuando el ponente esté delante de tu página, acuña una
+   sesión efímera para ESE firmante (60 minutos por defecto, caduca al firmar):
 
 ```python
 result = client.templates.create_envelope(
@@ -91,12 +100,41 @@ result = client.templates.create_envelope(
     send=True,
     deliver_emails=False,
 )
-sign_url = result["signers"][0]["sign_url"]
-# → redirige al ponente a sign_url sin salir de tu flujo
+signer = result["signers"][0]
+session = client.envelopes.create_embedded_session(
+    result["envelope"]["id"],
+    signer["id"],
+    origin="https://arbiter.rootedcon.com",
+    return_url="https://arbiter.rootedcon.com/contratos/42/firmado",  # opcional
+    language="es",
+)
+embed_url = session["url"]  # token em_…: un firmante, un origen, caduca
+```
+
+3. Ábrela en un iframe y escucha los eventos, o redirige al ponente y recíbelo
+   de vuelta en `return_url` con `?easycontract_event=signed&envelope_id=…&signer_id=…`:
+
+```html
+<iframe src="{{ embed_url }}" allow="camera" style="width:100%;height:80vh;border:0"></iframe>
+<script>
+window.addEventListener("message", (e) => {
+  if (e.origin !== "https://app.easycontract.online") return;   // el origen de easycontract
+  if (e.data?.source !== "easycontract") return;
+  // e.data.event ∈ ready | signed | declined | expired; e.data.envelope_id, signer_id
+});
+</script>
 ```
 
-El enlace es personal, caduca (14 días por defecto, `expires_in_days` para
-cambiarlo) y queda invalidado al firmar o rechazar.
+La página de firma responde con `Content-Security-Policy: frame-ancestors
+<tu origen>` y no depende de cookies (funciona con las de terceros
+bloqueadas); el OTP y la verificación de identidad, si el firmante los exige,
+se piden dentro del mismo marco (`allow="camera"` para la captura del
+documento). El `postMessage` es solo señal de interfaz: confirma siempre en
+servidor con el webhook `signer.signed` o `client.envelopes.get(...)`. Cada
+sesión y su apertura (con el origen) quedan en el expediente de evidencias.
+
+El `sign_url` clásico de `deliver_emails=False` sigue existiendo para el
+redirect simple (14 días, `expires_in_days` para cambiarlo).
 
 ## Receta 3 — Webhooks vs. polling
 
@@ -174,3 +212,42 @@ members = client.members.list()
 invite = client.invitations.create(email="colega@example.com", role="member")
 # invite["accept_url"] — entrégalo tú o deja que easycontract lo envíe por email
 ```
+
+## Validar la identidad del firmante en tu plataforma (KYC)
+
+Con el proceso propio de easycontract, el firmante fotografía su documento y se hace un
+selfie; la decisión es de la organización. Puedes tomarla desde tu propio sistema:
+
+```python
+from easycontract import EasyContract
+
+client = EasyContract(api_key="ec_live_...")
+
+# 1. Suscríbete a los eventos (o sondea GET /events/): signer.kyc_submitted avisa de
+#    cada caso pendiente; signer.kyc_verified / signer.kyc_failed, de la decisión.
+for case in client.identity.pending_reviews()["data"]:
+    envelope_id, signer = case["envelope_id"], case["signer"]
+    identity = case["identity_verification"]  # estado, comprobaciones, datos declarados
+
+    # 2. Recupera las imágenes (cada descarga queda en el audit trail del documento)
+    for document in identity["documents"]:
+        client.identity.download_document(
+            envelope_id, signer["id"], document["id"], to=f"/tmp/{document['kind']}.jpg"
+        )
+
+    # 3. Valida con tus reglas: número declarado, caducidad, cotejo visual o tu propio motor
+    ok = identity["declared_document_number"] == mi_registro[signer["email"]].dni
+
+    # 4. Decide; el firmante recibe el resultado por correo
+    client.identity.review(
+        envelope_id,
+        signer["id"],
+        decision="approve" if ok else "reject",
+        verified_name=signer["full_name"],
+        reason="" if ok else "El número de documento no coincide con nuestro registro",
+    )
+```
+
+Las imágenes se purgan a los N días de la decisión (`organization.kyc.image_retention_days`);
+el resultado completo sigue disponible en el paquete de evidencias con
+`download_evidence(..., include_identity_proofs=True)`.

{easycontract-0.1.0 → easycontract-0.1.1}/README.md

@@ -58,8 +58,17 @@ client.templates.add_field(
 
 ## Receta 2 — Firma embebida (embedded signing)
 
-Con `deliver_emails=False` recibes el `sign_url` de un solo uso por firmante y
-lo integras en tu propia aplicación (redirect o iframe):
+El firmante firma dentro de tu aplicación (el caso RootedArbiter). Tres pasos:
+
+1. Registra una vez los orígenes de tu web (https; `http://localhost:…` solo
+   en desarrollo). La lista se sustituye entera:
+
+```python
+client.organization.update(embed_allowed_origins=["https://arbiter.rootedcon.com"])
+```
+
+2. Envía sin emails y, cuando el ponente esté delante de tu página, acuña una
+   sesión efímera para ESE firmante (60 minutos por defecto, caduca al firmar):
 
 ```python
 result = client.templates.create_envelope(
@@ -68,12 +77,41 @@ result = client.templates.create_envelope(
     send=True,
     deliver_emails=False,
 )
-sign_url = result["signers"][0]["sign_url"]
-# → redirige al ponente a sign_url sin salir de tu flujo
+signer = result["signers"][0]
+session = client.envelopes.create_embedded_session(
+    result["envelope"]["id"],
+    signer["id"],
+    origin="https://arbiter.rootedcon.com",
+    return_url="https://arbiter.rootedcon.com/contratos/42/firmado",  # opcional
+    language="es",
+)
+embed_url = session["url"]  # token em_…: un firmante, un origen, caduca
+```
+
+3. Ábrela en un iframe y escucha los eventos, o redirige al ponente y recíbelo
+   de vuelta en `return_url` con `?easycontract_event=signed&envelope_id=…&signer_id=…`:
+
+```html
+<iframe src="{{ embed_url }}" allow="camera" style="width:100%;height:80vh;border:0"></iframe>
+<script>
+window.addEventListener("message", (e) => {
+  if (e.origin !== "https://app.easycontract.online") return;   // el origen de easycontract
+  if (e.data?.source !== "easycontract") return;
+  // e.data.event ∈ ready | signed | declined | expired; e.data.envelope_id, signer_id
+});
+</script>
 ```
 
-El enlace es personal, caduca (14 días por defecto, `expires_in_days` para
-cambiarlo) y queda invalidado al firmar o rechazar.
+La página de firma responde con `Content-Security-Policy: frame-ancestors
+<tu origen>` y no depende de cookies (funciona con las de terceros
+bloqueadas); el OTP y la verificación de identidad, si el firmante los exige,
+se piden dentro del mismo marco (`allow="camera"` para la captura del
+documento). El `postMessage` es solo señal de interfaz: confirma siempre en
+servidor con el webhook `signer.signed` o `client.envelopes.get(...)`. Cada
+sesión y su apertura (con el origen) quedan en el expediente de evidencias.
+
+El `sign_url` clásico de `deliver_emails=False` sigue existiendo para el
+redirect simple (14 días, `expires_in_days` para cambiarlo).
 
 ## Receta 3 — Webhooks vs. polling
 
@@ -151,3 +189,42 @@ members = client.members.list()
 invite = client.invitations.create(email="colega@example.com", role="member")
 # invite["accept_url"] — entrégalo tú o deja que easycontract lo envíe por email
 ```
+
+## Validar la identidad del firmante en tu plataforma (KYC)
+
+Con el proceso propio de easycontract, el firmante fotografía su documento y se hace un
+selfie; la decisión es de la organización. Puedes tomarla desde tu propio sistema:
+
+```python
+from easycontract import EasyContract
+
+client = EasyContract(api_key="ec_live_...")
+
+# 1. Suscríbete a los eventos (o sondea GET /events/): signer.kyc_submitted avisa de
+#    cada caso pendiente; signer.kyc_verified / signer.kyc_failed, de la decisión.
+for case in client.identity.pending_reviews()["data"]:
+    envelope_id, signer = case["envelope_id"], case["signer"]
+    identity = case["identity_verification"]  # estado, comprobaciones, datos declarados
+
+    # 2. Recupera las imágenes (cada descarga queda en el audit trail del documento)
+    for document in identity["documents"]:
+        client.identity.download_document(
+            envelope_id, signer["id"], document["id"], to=f"/tmp/{document['kind']}.jpg"
+        )
+
+    # 3. Valida con tus reglas: número declarado, caducidad, cotejo visual o tu propio motor
+    ok = identity["declared_document_number"] == mi_registro[signer["email"]].dni
+
+    # 4. Decide; el firmante recibe el resultado por correo
+    client.identity.review(
+        envelope_id,
+        signer["id"],
+        decision="approve" if ok else "reject",
+        verified_name=signer["full_name"],
+        reason="" if ok else "El número de documento no coincide con nuestro registro",
+    )
+```
+
+Las imágenes se purgan a los N días de la decisión (`organization.kyc.image_retention_days`);
+el resultado completo sigue disponible en el paquete de evidencias con
+`download_evidence(..., include_identity_proofs=True)`.

{easycontract-0.1.0 → easycontract-0.1.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "easycontract"
-version = "0.1.0"
+version = "0.1.1"
 description = "SDK oficial de Python para el API de easycontract (firma electrónica eIDAS)"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -20,7 +20,9 @@ classifiers = [
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
 dependencies = [
-    "requests>=2.31,<3",
+    # >=2.33.0: older releases carry CVE-2024-35195, CVE-2024-47081 and
+    # CVE-2026-25645 (audit 2026-10-07, A1)
+    "requests>=2.33.0,<3",
 ]
 
 [project.urls]
@@ -36,4 +38,4 @@ packages = ["src/easycontract"]
 [tool.hatch.build.targets.sdist]
 # Internal material never ships in the sdist. (hatchling still adds the
 # repo-root .gitignore to the sdist; it holds nothing sensitive.)
-exclude = ["SECURITY-AUDIT*.md", "dist/"]
+exclude = ["SECURITY-AUDIT*.md", "dist/", "uv.lock"]

{easycontract-0.1.0 → easycontract-0.1.1}/src/easycontract/__init__.py

@@ -6,7 +6,7 @@ client = EasyContract(api_key="ec_test_...")
 envelope = client.envelopes.create(title="Contrato", retention_period_months=72)
 """
 
-__version__ = "0.1.0"
+__version__ = "0.1.1"
 
 from . import webhooks
 from .client import EasyContract

{easycontract-0.1.0 → easycontract-0.1.1}/src/easycontract/client.py

@@ -25,9 +25,11 @@ from .errors import APIError, error_from_response
 from .resources import (
     Envelopes,
     Events,
+    Identity,
     Invitations,
     Members,
     Organization,
+    Retention,
     Templates,
     Webhooks,
 )
@@ -102,6 +104,9 @@ class EasyContract:
         )
 
         self.envelopes = Envelopes(self)
+
+        self.identity = Identity(self)
+        self.retention = Retention(self)
         self.templates = Templates(self)
         self.webhooks = Webhooks(self)
         self.events = Events(self)

{easycontract-0.1.0 → easycontract-0.1.1}/src/easycontract/resources.py

@@ -7,10 +7,33 @@ asserts full coverage, so the SDK cannot drift from the API contract.
 from __future__ import annotations
 
 import io
+import uuid
 from pathlib import Path
+from urllib.parse import quote
 
 from .errors import EasyContractError
 
+
+def _id(value) -> str:
+    """A resource identifier as a path segment: it must be a UUID (every
+    resource id of the API is). Anything else — "../webhooks/x", "a?b",
+    "a#b" — is refused before a request is built, so an id taken from
+    outside can never steer the call to another endpoint (audit
+    2026-10-07, A2)."""
+    try:
+        return str(uuid.UUID(str(value)))
+    except (ValueError, TypeError, AttributeError):
+        raise ValueError(f"invalid identifier {value!r}: expected a UUID") from None
+
+
+def _seg(value) -> str:
+    """A free-text path segment (catalog key, language code), fully escaped."""
+    text = str(value)
+    if text in ("", ".", ".."):
+        raise ValueError(f"invalid path segment {value!r}")
+    return quote(text, safe="")
+
+
 # (HTTP method, spec path) → dotted SDK method. CI-enforced coverage.
 OPERATIONS: dict[tuple[str, str], str] = {
     ("GET", "/whoami/"): "client.whoami",
@@ -31,8 +54,46 @@ OPERATIONS: dict[tuple[str, str], str] = {
         "POST",
         "/envelopes/{envelope_id}/signers/{signer_id}/remind/",
     ): "client.envelopes.remind_signer",
+    (
+        "POST",
+        "/envelopes/{envelope_id}/signers/{signer_id}/embedded-session/",
+    ): "client.envelopes.create_embedded_session",
     ("POST", "/envelopes/{envelope_id}/void/"): "client.envelopes.void",
     ("GET", "/envelopes/{envelope_id}/certificate/"): "client.envelopes.download_certificate",
+    (
+        "POST",
+        "/envelopes/{envelope_id}/documents/{document_id}/rescan/",
+    ): "client.envelopes.rescan_document",
+    (
+        "GET",
+        "/envelopes/{envelope_id}/documents/{document_id}/final/",
+    ): "client.envelopes.download_final_document",
+    ("POST", "/envelopes/{envelope_id}/legal-hold/"): "client.envelopes.set_legal_hold",
+    ("DELETE", "/envelopes/{envelope_id}/legal-hold/"): "client.envelopes.release_legal_hold",
+    ("GET", "/retention/"): "client.retention.overview",
+    ("GET", "/document-types/"): "client.retention.document_types",
+    ("PATCH", "/organization/"): "client.organization.update",
+    ("GET", "/identity-reviews/"): "client.identity.pending_reviews",
+    (
+        "GET",
+        "/envelopes/{envelope_id}/signers/{signer_id}/identity/",
+    ): "client.identity.get",
+    (
+        "GET",
+        "/envelopes/{envelope_id}/signers/{signer_id}/identity/documents/{document_id}/",
+    ): "client.identity.download_document",
+    (
+        "POST",
+        "/envelopes/{envelope_id}/signers/{signer_id}/identity/review/",
+    ): "client.identity.review",
+    (
+        "POST",
+        "/envelopes/{envelope_id}/signers/{signer_id}/identity/confirm-in-person/",
+    ): "client.identity.confirm_in_person",
+    (
+        "DELETE",
+        "/envelopes/{envelope_id}/signers/{signer_id}/biometrics/",
+    ): "client.envelopes.erase_signer_biometrics",
     ("GET", "/envelopes/{envelope_id}/evidence/"): "client.envelopes.download_evidence",
     ("GET", "/templates/"): "client.templates.list",
     ("POST", "/templates/"): "client.templates.create",
@@ -133,18 +194,34 @@ class Envelopes(_Resource):
         retention_period_months: int,
         signing_order: str = "parallel",
         metadata: dict | None = None,
+        language: str | None = None,
+        biometrics: bool = False,
+        document_type: str | None = None,
+        kyc_images_retention: str | None = None,
         idempotency_key: str | None = None,
     ) -> dict:
+        """`biometrics=True` offers signers the OPTIONAL stroke capture (only
+        effective when the organization enabled it: Enterprise + DPIA).
+        `document_type` is a key of `client.retention.document_types()`.
+        `kyc_images_retention`: "after_review" (default) or
+        "after_in_person_check" — keep the identity images until you record
+        the face-to-face check with `client.identity.confirm_in_person`."""
+        body: dict = {
+            "title": title,
+            "retention_period_months": retention_period_months,
+            "signing_order": signing_order,
+            "metadata": metadata or {},
+        }
+        if language:
+            body["language"] = language
+        if biometrics:
+            body["biometrics"] = True
+        if document_type:
+            body["document_type"] = document_type
+        if kyc_images_retention:
+            body["kyc_images_retention"] = kyc_images_retention
         return self._client.request(
-            "POST",
-            "/envelopes/",
-            json={
-                "title": title,
-                "retention_period_months": retention_period_months,
-                "signing_order": signing_order,
-                "metadata": metadata or {},
-            },
-            idempotency_key=idempotency_key,
+            "POST", "/envelopes/", json=body, idempotency_key=idempotency_key
         )
 
     def list(
@@ -167,7 +244,7 @@ class Envelopes(_Resource):
 
     def get(self, envelope_id: str, *, expand: list[str] | None = None) -> dict:
         params = {"expand": ",".join(expand)} if expand else None
-        return self._client.request("GET", f"/envelopes/{envelope_id}/", params=params)
+        return self._client.request("GET", f"/envelopes/{_id(envelope_id)}/", params=params)
 
     def add_document(
         self,
@@ -179,7 +256,7 @@ class Envelopes(_Resource):
     ) -> dict:
         return self._client.request(
             "POST",
-            f"/envelopes/{envelope_id}/documents/",
+            f"/envelopes/{_id(envelope_id)}/documents/",
             files={"file": _file_tuple(file, name, content_type)},
         )
 
@@ -192,6 +269,8 @@ class Envelopes(_Resource):
         phone: str = "",
         order: int | None = None,
         auth_methods: list[str] | None = None,
+        kyc_document_type: str = "",
+        kyc_document_number: str = "",
         idempotency_key: str | None = None,
     ) -> dict:
         body = {"full_name": full_name, "email": email, "phone": phone}
@@ -201,7 +280,7 @@ class Envelopes(_Resource):
             body["auth_methods"] = auth_methods
         return self._client.request(
             "POST",
-            f"/envelopes/{envelope_id}/signers/",
+            f"/envelopes/{_id(envelope_id)}/signers/",
             json=body,
             idempotency_key=idempotency_key,
         )
@@ -219,29 +298,121 @@ class Envelopes(_Resource):
             body["expires_in_days"] = expires_in_days
         return self._client.request(
             "POST",
-            f"/envelopes/{envelope_id}/send/",
+            f"/envelopes/{_id(envelope_id)}/send/",
             json=body,
             idempotency_key=idempotency_key,
         )
 
     def remind_signer(self, envelope_id: str, signer_id: str) -> dict:
         """Re-send the signing link (a FRESH one; previous links die)."""
-        return self._client.request("POST", f"/envelopes/{envelope_id}/signers/{signer_id}/remind/")
+        return self._client.request(
+            "POST", f"/envelopes/{_id(envelope_id)}/signers/{_id(signer_id)}/remind/"
+        )
+
+    def create_embedded_session(
+        self,
+        envelope_id: str,
+        signer_id: str,
+        *,
+        origin: str,
+        return_url: str | None = None,
+        language: str | None = None,
+        ttl_minutes: int | None = None,
+        idempotency_key: str | None = None,
+    ) -> dict:
+        """Embedded signing (§10.3): an ephemeral `url` for ONE pending signer
+        and ONE origin registered with `client.organization.update(
+        embed_allowed_origins=[...])`. Open it in an `<iframe allow="camera">`
+        (the page posts ready/signed/declined/expired to your window) or
+        redirect to it and get the signer back on `return_url`. Confirm the
+        outcome server-side (webhook `signer.signed` or `envelopes.get`)."""
+        body: dict = {"origin": origin}
+        if return_url is not None:
+            body["return_url"] = return_url
+        if language is not None:
+            body["language"] = language
+        if ttl_minutes is not None:
+            body["ttl_minutes"] = ttl_minutes
+        return self._client.request(
+            "POST",
+            f"/envelopes/{_id(envelope_id)}/signers/{_id(signer_id)}/embedded-session/",
+            json=body,
+            idempotency_key=idempotency_key,
+        )
+
+    def set_legal_hold(self, envelope_id: str, *, reason: str) -> dict:
+        """Suspend retention blocking/purge (litigation, authority request)."""
+        return self._client.request(
+            "POST", f"/envelopes/{_id(envelope_id)}/legal-hold/", json={"reason": reason}
+        )
+
+    def release_legal_hold(self, envelope_id: str) -> dict:
+        return self._client.request("DELETE", f"/envelopes/{_id(envelope_id)}/legal-hold/")
 
     def void(self, envelope_id: str, *, reason: str = "") -> dict:
         return self._client.request(
-            "POST", f"/envelopes/{envelope_id}/void/", json={"reason": reason}
+            "POST", f"/envelopes/{_id(envelope_id)}/void/", json={"reason": reason}
         )
 
     def download_certificate(self, envelope_id: str, *, to: str | Path | None = None) -> bytes:
-        content = self._client.request("GET", f"/envelopes/{envelope_id}/certificate/", raw=True)
+        content = self._client.request(
+            "GET", f"/envelopes/{_id(envelope_id)}/certificate/", raw=True
+        )
         if to is not None:
             Path(to).write_bytes(content)
         return content
 
-    def download_evidence(self, envelope_id: str, *, to: str | Path | None = None) -> bytes:
+    def erase_signer_biometrics(
+        self, envelope_id: str, signer_id: str, *, reason: str = ""
+    ) -> dict:
+        """Erase a signer's biometric sample (consent withdrawn). The hash and
+        the audit trail stay; `signer["biometrics"]["erased_at"]` is set."""
+        return self._client.request(
+            "DELETE",
+            f"/envelopes/{_id(envelope_id)}/signers/{_id(signer_id)}/biometrics/",
+            params={"reason": reason} if reason else None,
+        )
+
+    def rescan_document(self, envelope_id: str, document_id: str) -> dict:
+        """Retry the asynchronous malware scan of a document whose scan ended
+        in `error` (or a legacy `not_scanned` one). The verdict arrives later:
+        `document["scan"]["status"]` or the `document.scanned` event."""
+        return self._client.request(
+            "POST", f"/envelopes/{_id(envelope_id)}/documents/{_id(document_id)}/rescan/"
+        )
+
+    def download_final_document(
+        self, envelope_id: str, document_id: str, *, to: str | Path | None = None
+    ) -> bytes:
+        """The stamped final PDF of one document (PAdES-B-LTA sealed on
+        Enterprise). Seal details come with `get(..., expand=["documents"])`
+        under `documents[].final.pades`."""
+        content = self._client.request(
+            "GET", f"/envelopes/{_id(envelope_id)}/documents/{_id(document_id)}/final/", raw=True
+        )
+        if to is not None:
+            Path(to).write_bytes(content)
+        return content
+
+    def download_evidence(
+        self,
+        envelope_id: str,
+        *,
+        to: str | Path | None = None,
+        include_biometrics: bool = False,
+        include_identity_proofs: bool = False,
+    ) -> bytes:
         """The full evidence ZIP — what a tenant would take to court."""
-        content = self._client.request("GET", f"/envelopes/{envelope_id}/evidence/", raw=True)
+        content = self._client.request(
+            "GET",
+            f"/envelopes/{_id(envelope_id)}/evidence/",
+            params={
+                **({"include_biometrics": "true"} if include_biometrics else {}),
+                **({"include_identity_proofs": "true"} if include_identity_proofs else {}),
+            }
+            or None,
+            raw=True,
+        )
         if to is not None:
             Path(to).write_bytes(content)
         return content
@@ -257,26 +428,30 @@ class Templates(_Resource):
         signing_order: str = "parallel",
         metadata: dict | None = None,
         variables: list[dict] | None = None,
+        document_type: str | None = None,
+        kyc_images_retention: str | None = None,
         idempotency_key: str | None = None,
     ) -> dict:
+        body: dict = {
+            "name": name,
+            "retention_period_months": retention_period_months,
+            "description": description,
+            "signing_order": signing_order,
+            "metadata": metadata or {},
+            "variables": variables or [],
+        }
+        if document_type:
+            body["document_type"] = document_type
+        if kyc_images_retention:
+            body["kyc_images_retention"] = kyc_images_retention
         return self._client.request(
-            "POST",
-            "/templates/",
-            json={
-                "name": name,
-                "retention_period_months": retention_period_months,
-                "description": description,
-                "signing_order": signing_order,
-                "metadata": metadata or {},
-                "variables": variables or [],
-            },
-            idempotency_key=idempotency_key,
+            "POST", "/templates/", json=body, idempotency_key=idempotency_key
         )
 
     def update(self, template_id: str, **changes) -> dict:
         """PATCH settings: name, description, signing_order,
         retention_period_months, variables (schema list), metadata."""
-        return self._client.request("PATCH", f"/templates/{template_id}/", json=changes)
+        return self._client.request("PATCH", f"/templates/{_id(template_id)}/", json=changes)
 
     def catalog(self, *, language: str | None = None) -> dict:
         """Starter templates shipped with the platform (house drafts)."""
@@ -288,7 +463,7 @@ class Templates(_Resource):
     ) -> dict:
         return self._client.request(
             "POST",
-            f"/templates/catalog/{catalog_key}/clone/",
+            f"/templates/catalog/{_seg(catalog_key)}/clone/",
             json={"name": name},
             idempotency_key=idempotency_key,
         )
@@ -298,7 +473,7 @@ class Templates(_Resource):
     ) -> dict:
         return self._client.request(
             "POST",
-            f"/templates/{template_id}/duplicate/",
+            f"/templates/{_id(template_id)}/duplicate/",
             json={"name": name},
             idempotency_key=idempotency_key,
         )
@@ -325,10 +500,12 @@ class Templates(_Resource):
         ):
             if value is not None:
                 body[key] = value
-        return self._client.request("POST", f"/templates/{template_id}/documents/", json=body)
+        return self._client.request("POST", f"/templates/{_id(template_id)}/documents/", json=body)
 
     def get_document(self, template_id: str, document_id: str) -> dict:
-        return self._client.request("GET", f"/templates/{template_id}/documents/{document_id}/")
+        return self._client.request(
+            "GET", f"/templates/{_id(template_id)}/documents/{_id(document_id)}/"
+        )
 
     def update_document(
         self,
@@ -353,15 +530,18 @@ class Templates(_Resource):
             if v is not None
         }
         return self._client.request(
-            "PATCH", f"/templates/{template_id}/documents/{document_id}/", json=body
+            "PATCH", f"/templates/{_id(template_id)}/documents/{_id(document_id)}/", json=body
         )
 
     def delete_document(self, template_id: str, document_id: str) -> None:
-        self._client.request("DELETE", f"/templates/{template_id}/documents/{document_id}/")
+        self._client.request(
+            "DELETE", f"/templates/{_id(template_id)}/documents/{_id(document_id)}/"
+        )
 
     def get_translation(self, template_id: str, document_id: str, language: str) -> dict:
         return self._client.request(
-            "GET", f"/templates/{template_id}/documents/{document_id}/translations/{language}/"
+            "GET",
+            f"/templates/{_id(template_id)}/documents/{_id(document_id)}/translations/{_seg(language)}/",
         )
 
     def put_translation(
@@ -388,14 +568,14 @@ class Templates(_Resource):
         }
         return self._client.request(
             "PUT",
-            f"/templates/{template_id}/documents/{document_id}/translations/{language}/",
+            f"/templates/{_id(template_id)}/documents/{_id(document_id)}/translations/{_seg(language)}/",
             json=body,
         )
 
     def delete_translation(self, template_id: str, document_id: str, language: str) -> None:
         self._client.request(
             "DELETE",
-            f"/templates/{template_id}/documents/{document_id}/translations/{language}/",
+            f"/templates/{_id(template_id)}/documents/{_id(document_id)}/translations/{_seg(language)}/",
         )
 
     def download_docx(
@@ -403,7 +583,7 @@ class Templates(_Resource):
     ) -> bytes:
         """Editable DOCX of an authored document (edit in Word, upload back)."""
         content = self._client.request(
-            "GET", f"/templates/{template_id}/documents/{document_id}/docx/", raw=True
+            "GET", f"/templates/{_id(template_id)}/documents/{_id(document_id)}/docx/", raw=True
         )
         if to is not None:
             Path(to).write_bytes(content)
@@ -415,7 +595,7 @@ class Templates(_Resource):
         """Replace an authored document's text with the uploaded DOCX."""
         return self._client.request(
             "POST",
-            f"/templates/{template_id}/documents/{document_id}/docx/",
+            f"/templates/{_id(template_id)}/documents/{_id(document_id)}/docx/",
             files={"file": _file_tuple(file, name or "document.docx", DOCX_MIME)},
             data={"name": name} if name else None,
         )
@@ -439,7 +619,7 @@ class Templates(_Resource):
         if language:
             body["language"] = language
         content = self._client.request(
-            "POST", f"/templates/{template_id}/preview/", json=body, raw=True
+            "POST", f"/templates/{_id(template_id)}/preview/", json=body, raw=True
         )
         if to is not None:
             Path(to).write_bytes(content)
@@ -451,10 +631,10 @@ class Templates(_Resource):
 
     def get(self, template_id: str, *, expand: list[str] | None = None) -> dict:
         params = {"expand": ",".join(expand)} if expand else None
-        return self._client.request("GET", f"/templates/{template_id}/", params=params)
+        return self._client.request("GET", f"/templates/{_id(template_id)}/", params=params)
 
     def delete(self, template_id: str) -> None:
-        self._client.request("DELETE", f"/templates/{template_id}/")
+        self._client.request("DELETE", f"/templates/{_id(template_id)}/")
 
     def add_document(
         self,
@@ -466,7 +646,7 @@ class Templates(_Resource):
     ) -> dict:
         return self._client.request(
             "POST",
-            f"/templates/{template_id}/documents/",
+            f"/templates/{_id(template_id)}/documents/",
             files={"file": _file_tuple(file, name, content_type)},
         )
 
@@ -484,7 +664,7 @@ class Templates(_Resource):
             body["order"] = order
         if auth_methods is not None:
             body["auth_methods"] = auth_methods
-        return self._client.request("POST", f"/templates/{template_id}/roles/", json=body)
+        return self._client.request("POST", f"/templates/{_id(template_id)}/roles/", json=body)
 
     def add_field(
         self,
@@ -504,7 +684,7 @@ class Templates(_Resource):
     ) -> dict:
         return self._client.request(
             "POST",
-            f"/templates/{template_id}/fields/",
+            f"/templates/{_id(template_id)}/fields/",
             json={
                 "document_id": document_id,
                 "role": role,
@@ -532,6 +712,8 @@ class Templates(_Resource):
         expires_in_days: int | None = None,
         deliver_emails: bool = True,
         language: str | None = None,
+        kyc_images_retention: str | None = None,
+        biometrics: bool = False,
         idempotency_key: str | None = None,
     ) -> dict:
         """The one-call automation flow (§10.4): instantiate and optionally
@@ -548,11 +730,15 @@ class Templates(_Resource):
         }
         if language is not None:
             body["language"] = language
+        if kyc_images_retention:
+            body["kyc_images_retention"] = kyc_images_retention
+        if biometrics:
+            body["biometrics"] = True
         if expires_in_days is not None:
             body["expires_in_days"] = expires_in_days
         return self._client.request(
             "POST",
-            f"/templates/{template_id}/envelopes/",
+            f"/templates/{_id(template_id)}/envelopes/",
             json=body,
             idempotency_key=idempotency_key,
         )
@@ -574,10 +760,10 @@ class Webhooks(_Resource):
         return self._client.request("GET", "/webhooks/", params=params)
 
     def delete(self, endpoint_id: str) -> None:
-        self._client.request("DELETE", f"/webhooks/{endpoint_id}/")
+        self._client.request("DELETE", f"/webhooks/{_id(endpoint_id)}/")
 
     def redeliver(self, delivery_id: str) -> dict:
-        return self._client.request("POST", f"/webhooks/deliveries/{delivery_id}/redeliver/")
+        return self._client.request("POST", f"/webhooks/deliveries/{_id(delivery_id)}/redeliver/")
 
 
 class Events(_Resource):
@@ -609,21 +795,107 @@ class Events(_Resource):
         return self._auto_paging("/events/", **params)
 
 
+class Retention(_Resource):
+    """Evidence retention: what ends soon (export it!), blocked, legal holds,
+    and the document type catalogue with suggested retention."""
+
+    def overview(self, *, within_days: int = 90) -> dict:
+        return self._client.request("GET", "/retention/", params={"within_days": within_days})
+
+    def document_types(self) -> dict:
+        return self._client.request("GET", "/document-types/")
+
+
+class Identity(_Resource):
+    """Signer identity proofing (factor `kyc`). With the in-house process the
+    tenant reviews: list pending cases, look at the images (every view is
+    recorded in the evidence trail) and decide."""
+
+    def pending_reviews(self) -> dict:
+        return self._client.request("GET", "/identity-reviews/")
+
+    def get(self, envelope_id: str, signer_id: str) -> dict:
+        return self._client.request(
+            "GET", f"/envelopes/{_id(envelope_id)}/signers/{_id(signer_id)}/identity/"
+        )
+
+    def download_document(
+        self, envelope_id: str, signer_id: str, document_id: str, *, to: str | Path | None = None
+    ) -> bytes:
+        content = self._client.request(
+            "GET",
+            f"/envelopes/{_id(envelope_id)}/signers/{_id(signer_id)}/identity/documents/{_id(document_id)}/",
+            raw=True,
+        )
+        if to is not None:
+            Path(to).write_bytes(content)
+        return content
+
+    def review(
+        self,
+        envelope_id: str,
+        signer_id: str,
+        *,
+        decision: str,
+        verified_name: str = "",
+        reason: str = "",
+    ) -> dict:
+        """`decision` is "approve" or "reject" (a rejection needs a reason)."""
+        body = {"decision": decision}
+        if verified_name:
+            body["verified_name"] = verified_name
+        if reason:
+            body["reason"] = reason
+        return self._client.request(
+            "POST",
+            f"/envelopes/{_id(envelope_id)}/signers/{_id(signer_id)}/identity/review/",
+            json=body,
+        )
+
+    def confirm_in_person(self, envelope_id: str, signer_id: str, *, note: str = "") -> dict:
+        """Record that the signer was matched against the document face to
+        face (access control, registration desk). On envelopes created with
+        `kyc_images_retention="after_in_person_check"` this starts the image
+        purge clock; it is always recorded in the evidence trail."""
+        body = {"note": note} if note else {}
+        return self._client.request(
+            "POST",
+            f"/envelopes/{_id(envelope_id)}/signers/{_id(signer_id)}/identity/confirm-in-person/",
+            json=body,
+        )
+
+
 class Organization(_Resource):
     def get(self) -> dict:
         """Org info including plan limits and features."""
         return self._client.request("GET", "/organization/")
 
+    def update(
+        self,
+        *,
+        retention_policies: dict | None = None,
+        embed_allowed_origins: list[str] | None = None,
+    ) -> dict:
+        """Organization settings an API key may change: retention policy per
+        document type (months within the plan's range) and the web origins
+        allowed to embed the signer flow (the FULL list; [] disables it)."""
+        body: dict = {}
+        if retention_policies is not None:
+            body["retention_policies"] = retention_policies
+        if embed_allowed_origins is not None:
+            body["embed_allowed_origins"] = list(embed_allowed_origins)
+        return self._client.request("PATCH", "/organization/", json=body)
+
 
 class Members(_Resource):
     def list(self) -> dict:
         return self._client.request("GET", "/members/")
 
     def change_role(self, membership_id: str, *, role: str) -> dict:
-        return self._client.request("PATCH", f"/members/{membership_id}/", json={"role": role})
+        return self._client.request("PATCH", f"/members/{_id(membership_id)}/", json={"role": role})
 
     def remove(self, membership_id: str) -> None:
-        self._client.request("DELETE", f"/members/{membership_id}/")
+        self._client.request("DELETE", f"/members/{_id(membership_id)}/")
 
 
 class Invitations(_Resource):
@@ -650,4 +922,4 @@ class Invitations(_Resource):
         return self._client.request("GET", "/invitations/", params=params)
 
     def cancel(self, invite_id: str) -> None:
-        self._client.request("DELETE", f"/invitations/{invite_id}/")
+        self._client.request("DELETE", f"/invitations/{_id(invite_id)}/")

{easycontract-0.1.0 → easycontract-0.1.1}/tests/smoke_test.py

@@ -255,6 +255,25 @@ expect_sig_err(
     secret=SECRET,
 )
 
+# ------------------------------------------- 6 bis. path identifiers (A2)
+from easycontract import EasyContract as ProbeClient  # noqa: E402
+
+probe = ProbeClient(api_key="ec_test_probe", base_url="https://api.example.com/api/v1")
+sent_paths: list[str] = []
+probe.request = lambda method, path, **kw: sent_paths.append(path) or {}
+good = "6F9619FF-8B86-D011-B42D-00C04FC964FF"
+probe.envelopes.get(good)
+ok("UUID ids are normalised into the path", sent_paths[-1] == f"/envelopes/{good.lower()}/")
+for bad in ("abc/../../webhooks/123", "x?expand=all", "x#frag", "", None):
+    try:
+        probe.envelopes.release_legal_hold(bad)
+        ok(f"non-UUID id refused ({bad!r})", False)
+    except ValueError:
+        ok(f"non-UUID id refused ({bad!r})", True)
+probe.templates.get_translation(good, good, "es/../x")
+ok("text segments are escaped", sent_paths[-1].endswith("/translations/es%2F..%2Fx/"))
+ok("no request was built for refused ids", len(sent_paths) == 2)
+
 # --------------------------------------------------------- 7. version wiring
 from easycontract import __version__  # noqa: E402
 

easycontract-0.1.0/CHANGELOG.md

@@ -1,19 +0,0 @@
-# Changelog — easycontract Python SDK
-
-## 0.1.0 (unreleased)
-
-First public release. Notes for integrators:
-
-- `EasyContract.request(..., idempotency_key=...)`: `None` (default) and `True`
-  generate a UUID per logical request, reused across retries; `False` sends no
-  header; any other value (a `str`, a `uuid.UUID`…) is sent as `str(value)`.
-- Uploads: file objects passed in `files` are closed once the request finishes.
-  A non-seekable stream (pipe, socket) is sent once and never retried; pass a
-  path, `bytes` or a seekable file to get 429 retries.
-- `webhooks.verify_signature`: `tolerance=0` is strict; only `tolerance=None`
-  disables the replay window. Verification runs over the raw bytes and every
-  failure raises `SignatureVerificationError`, never a decode/parse error.
-- Auto-pagination raises `EasyContractError` on a page without `data` or on a
-  cursor that does not advance, instead of looping or crashing.
-- Runtime dependency pinned to `requests>=2.31,<3`. Licence declared as
-  `LicenseRef-easycontract-proprietary` (PEP 639) with `LICENSE.txt`.