easycontract 0.1.0__tar.gz → 0.1.4__tar.gz

easycontract-0.1.4/CHANGELOG.md

@@ -0,0 +1,162 @@
+# Changelog
+
+All notable changes to the `easycontract` Python SDK.
+
+## 0.1.4 (2026-10-20)
+
+**Features**
+
+- Projects (paid plans): `client.projects.list/create/get/update`. An
+  organization key sees everything; a project key only its project.
+  `project=` on `envelopes.create`, `envelopes.list`, `templates.create_envelope`
+  and `webhooks.create` (organization keys only). `client.whoami()` now returns
+  `project` (null = organization key) and `key`.
+- Webhooks: `client.webhooks.get`, `update` (url, event_types, is_active,
+  description) and `rotate_secret(grace_period_hours=24)`, which returns the
+  new `secret` once.
+
+**Fixes**
+
+- `easycontract.webhooks.verify_signature` accepts ANY `v1=` in the header
+  and `secret` may be a list: after a rotation, during the grace period,
+  deliveries carry `v1=<new>,v1=<old>`. 0.1.3 and earlier only checked the
+  last `v1` (the old secret), so they failed once you switched to the new one
+  before the grace period ended.
+
+## 0.1.3 (2026-10-20)
+
+**Features**
+
+- Cryptographic restrictions: `client.organization.update(seal_profile=
+  "hybrid" | "classic", acknowledge=True)` chooses how the platform seals
+  the certificate, the final PDFs and the evidence package (hybrid ECDSA +
+  ML-DSA-87, or ECDSA only). `client.organization.get()["cryptography"]`
+  shows the choice and what each option implies; every envelope reports the
+  profile frozen at send in `seal_profile`.
+- The evidence package (`client.envelopes.download_evidence(...)`) is now an ASiC-E
+  container (still a `.zip`) signed by the platform.
+
+## 0.1.2 (2026-10-19)
+
+**Features**
+
+- Machine-drafted template translations: `client.templates.autotranslate(
+  template_id, document_id, language, acknowledge=True)` queues a draft made
+  by the platform's translators and reviewed by a panel with quorum;
+  `client.templates.get_translation_job(job_id)` returns its progress,
+  `verdict` (`consensus`, `quorum`, `no_quorum`, `unreviewed`, `simulated`)
+  and the reviewers' notes with English back-translations. The result is
+  always a draft that a person approves in the panel.
+- The platform now has 16 languages (es, en, ca, gl, eu, ast, an, oc, pt, fr,
+  it, de, ru, zh-hans, ar, he) for `language` everywhere.
+
+## 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.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: easycontract
-Version: 0.1.0
+Version: 0.1.4
 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.4}/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.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "easycontract"
-version = "0.1.0"
+version = "0.1.4"
 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.4}/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.4"
 
 from . import webhooks
 from .client import EasyContract

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

@@ -25,9 +25,12 @@ from .errors import APIError, error_from_response
 from .resources import (
     Envelopes,
     Events,
+    Identity,
     Invitations,
     Members,
     Organization,
+    Projects,
+    Retention,
     Templates,
     Webhooks,
 )
@@ -102,8 +105,12 @@ class EasyContract:
         )
 
         self.envelopes = Envelopes(self)
+
+        self.identity = Identity(self)
+        self.retention = Retention(self)
         self.templates = Templates(self)
         self.webhooks = Webhooks(self)
+        self.projects = Projects(self)
         self.events = Events(self)
         self.organization = Organization(self)
         self.members = Members(self)