e2a 2.0.0__tar.gz → 2.1.0__tar.gz

{e2a-2.0.0 → e2a-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: e2a
-Version: 2.0.0
+Version: 2.1.0
 Summary: Python SDK for the e2a protocol — email-to-agent authentication
 Project-URL: Homepage, https://e2a.dev
 Project-URL: Repository, https://github.com/Mnexa-AI/e2a
@@ -48,6 +48,17 @@ For WebSocket real-time delivery:
 pip install e2a[ws]
 ```
 
+## Upgrading from 1.x to 2.0
+
+Webhook-parsed emails now refuse to expose claim fields (`sender`, `subject`, `text_body`, …) until the HMAC signature is verified — `email.sender` raises `UnverifiedEmailError` instead of silently returning attacker-controllable data. The one-line fix is to switch `client.parse(body)` → `client.parse_webhook(body)`:
+
+```diff
+- email = client.parse(await request.body())
++ email = client.parse_webhook(await request.body())
+```
+
+`parse_webhook` reads the secret from `E2A_WEBHOOK_SECRET`; set it before upgrading. If you must inspect the payload before verifying, use `email.unverified_payload`. REST-fetched emails (`client.get_message`) are unaffected — they're pre-verified via the bearer token. Full background in the [PR](https://github.com/Mnexa-AI/e2a/pull/57).
+
 ## Import paths
 
 The stable, pinned API surface lives under `e2a.v1`:
@@ -72,15 +83,22 @@ client = E2AClient()
 
 Mount the webhook in your web framework:
 
+Webhook payloads are HMAC-signed. The SDK gates field access behind verification — accessing `email.sender`, `email.subject`, etc. on an unverified payload raises `UnverifiedEmailError`. Use `client.parse_webhook(...)` to parse + verify in one call:
+
 **FastAPI:**
 ```python
-from fastapi import FastAPI, Request
+from fastapi import FastAPI, Request, HTTPException
 
 app = FastAPI()
 
 @app.post("/webhook")
 async def webhook(request: Request):
-    email = client.parse(await request.body())
+    try:
+        email = client.parse_webhook(await request.body())  # reads E2A_WEBHOOK_SECRET
+    except PermissionError:
+        raise HTTPException(401, "bad signature")
+    # ValueError is raised if no secret is configured — let it 500 so a misconfig
+    # surfaces loudly, or catch it here to return a clearer message.
     print(f"From: {email.sender}, Subject: {email.subject}")
     email.reply("Thanks for reaching out!")
     return {"ok": True}
@@ -88,17 +106,22 @@ async def webhook(request: Request):
 
 **Flask:**
 ```python
-from flask import Flask, request
+from flask import Flask, request, abort
 
 app = Flask(__name__)
 
 @app.post("/webhook")
 def webhook():
-    email = client.parse(request.get_data())
+    try:
+        email = client.parse_webhook(request.get_data())
+    except PermissionError:
+        abort(401)
     email.reply("Thanks for reaching out!")
     return {"ok": True}
 ```
 
+Get a signing secret from the dashboard's Settings → Webhook signing secrets (or `POST /api/v1/users/me/signing-secrets`). Set it as `E2A_WEBHOOK_SECRET` so `parse_webhook` picks it up automatically, or pass it explicitly: `client.parse_webhook(body, secret="whsec_...")`.
+
 ## Raw vs high-level API
 
 The SDK has two layers:
@@ -132,7 +155,7 @@ whether the other side is a human replying from Gmail or another e2a agent.
 ```python
 @app.post("/webhook")
 async def webhook(request: Request):
-    email = client.parse(await request.body())
+    email = client.parse_webhook(await request.body())
 
     if email.conversation_id:
         # Follow-up — route to the existing conversation
@@ -220,7 +243,7 @@ Inbound email attachments are automatically parsed and available on
 `email.attachments`:
 
 ```python
-email = client.parse(body)
+email = client.parse_webhook(body)
 for att in email.attachments:
     print(f"{att.filename} ({att.content_type}, {att.size} bytes)")
     save_file(att.filename, att.data)
@@ -273,7 +296,7 @@ client = AsyncE2AClient()  # reads E2A_API_KEY from env
 
 @app.post("/webhook")
 async def webhook(request: Request):
-    email = client.parse(await request.body())
+    email = await client.parse_webhook(await request.body())
     await email.reply("Thanks!", conversation_id="conv_123")
     return {"ok": True}
 ```
@@ -393,9 +416,13 @@ print(result.status, result.message_id)
 | `auth` | `AuthHeaders` | Full authentication details |
 | `raw_message` | `bytes` | Raw RFC 2822 email bytes |
 
+All claim fields (`message_id`, `sender`, `recipient`, `to`, `cc`, `subject`, `text_body`, `html_body`, `attachments`, `conversation_id`, `received_at`) are gated — accessing them on an unverified webhook payload raises `UnverifiedEmailError`. Always-available regardless of verification: `auth`, `raw_message`, `is_verified`, `verified`, `unverified_payload`. Emails returned by `client.get_message(...)` are pre-verified (the bearer token already authenticated the channel). `client.get_messages(...)` returns lightweight `MessageSummary` items, not `InboundEmail`, so the gate doesn't apply.
+
 **Methods:**
 
+- `email.verify_signature(secret=None)` → `bool` — verifies the HMAC; falls back to `E2A_WEBHOOK_SECRET`. Sets the verified flag on success so claim fields become accessible.
 - `email.reply(body, html_body=None, conversation_id=None, attachments=None)` → `SendResult`
+- `email.unverified_payload` — escape hatch for inspection (debugging, logging) without verifying. Treat as untrusted.
 
 ## API Reference
 
@@ -403,8 +430,9 @@ print(result.status, result.message_id)
 
 High-level sync client. `api_key` falls back to `E2A_API_KEY` env var.
 
-- `client.parse(body)` → `InboundEmail` — accepts bytes, str, dict, or `MessageDetail`
-- `client.get_message(message_id)` → `InboundEmail`
+- `client.parse_webhook(body, secret=None)` → `InboundEmail` — parse + HMAC-verify (recommended for webhook handlers). Reads `E2A_WEBHOOK_SECRET` if no secret is passed; raises `PermissionError` on bad signature.
+- `client.parse(body)` → `InboundEmail` — accepts bytes, str, dict, or `MessageDetail`. Returns *unverified* — claim fields raise `UnverifiedEmailError` until `email.verify_signature()` succeeds.
+- `client.get_message(message_id)` → `InboundEmail` — pre-verified (REST channel auth)
 - `client.get_messages(status="unread", page_size=50)` → `MessageList`
 - `client.reply(message_id, body, ...)` → `SendResult`
 - `client.send(to, subject, body, ...)` → `SendResult`
@@ -422,11 +450,13 @@ Same as `E2AClient` — all I/O methods are `async`. `parse()` is sync (no I/O n
 - `InboundEmail` / `AsyncInboundEmail` — parsed email with `.reply()`
 - `Attachment` — `filename`, `content_type`, `data` (bytes), `size`
 - `SendResult` — `status`, `message_id`, `method`
-- `AuthHeaders` — `verified`, `sender`, `entity_type`, `domain_check`, `delegation`, `signature`, `timestamp`
+- `AuthHeaders` — `verified`, `sender`, `entity_type`, `domain_check`, `delegation`, `signature`, `timestamp`, `message_id`, `body_hash`
 
 ### Exceptions
 
 - `E2AApiError` — API error (has `status_code` and `message`)
+- `UnverifiedEmailError` — raised on `InboundEmail` claim-field access before `verify_signature()` has succeeded
+- `PermissionError` — raised by `parse_webhook` on bad signature
 
 ## License
 

{e2a-2.0.0 → e2a-2.1.0}/README.md

@@ -14,6 +14,17 @@ For WebSocket real-time delivery:
 pip install e2a[ws]
 ```
 
+## Upgrading from 1.x to 2.0
+
+Webhook-parsed emails now refuse to expose claim fields (`sender`, `subject`, `text_body`, …) until the HMAC signature is verified — `email.sender` raises `UnverifiedEmailError` instead of silently returning attacker-controllable data. The one-line fix is to switch `client.parse(body)` → `client.parse_webhook(body)`:
+
+```diff
+- email = client.parse(await request.body())
++ email = client.parse_webhook(await request.body())
+```
+
+`parse_webhook` reads the secret from `E2A_WEBHOOK_SECRET`; set it before upgrading. If you must inspect the payload before verifying, use `email.unverified_payload`. REST-fetched emails (`client.get_message`) are unaffected — they're pre-verified via the bearer token. Full background in the [PR](https://github.com/Mnexa-AI/e2a/pull/57).
+
 ## Import paths
 
 The stable, pinned API surface lives under `e2a.v1`:
@@ -38,15 +49,22 @@ client = E2AClient()
 
 Mount the webhook in your web framework:
 
+Webhook payloads are HMAC-signed. The SDK gates field access behind verification — accessing `email.sender`, `email.subject`, etc. on an unverified payload raises `UnverifiedEmailError`. Use `client.parse_webhook(...)` to parse + verify in one call:
+
 **FastAPI:**
 ```python
-from fastapi import FastAPI, Request
+from fastapi import FastAPI, Request, HTTPException
 
 app = FastAPI()
 
 @app.post("/webhook")
 async def webhook(request: Request):
-    email = client.parse(await request.body())
+    try:
+        email = client.parse_webhook(await request.body())  # reads E2A_WEBHOOK_SECRET
+    except PermissionError:
+        raise HTTPException(401, "bad signature")
+    # ValueError is raised if no secret is configured — let it 500 so a misconfig
+    # surfaces loudly, or catch it here to return a clearer message.
     print(f"From: {email.sender}, Subject: {email.subject}")
     email.reply("Thanks for reaching out!")
     return {"ok": True}
@@ -54,17 +72,22 @@ async def webhook(request: Request):
 
 **Flask:**
 ```python
-from flask import Flask, request
+from flask import Flask, request, abort
 
 app = Flask(__name__)
 
 @app.post("/webhook")
 def webhook():
-    email = client.parse(request.get_data())
+    try:
+        email = client.parse_webhook(request.get_data())
+    except PermissionError:
+        abort(401)
     email.reply("Thanks for reaching out!")
     return {"ok": True}
 ```
 
+Get a signing secret from the dashboard's Settings → Webhook signing secrets (or `POST /api/v1/users/me/signing-secrets`). Set it as `E2A_WEBHOOK_SECRET` so `parse_webhook` picks it up automatically, or pass it explicitly: `client.parse_webhook(body, secret="whsec_...")`.
+
 ## Raw vs high-level API
 
 The SDK has two layers:
@@ -98,7 +121,7 @@ whether the other side is a human replying from Gmail or another e2a agent.
 ```python
 @app.post("/webhook")
 async def webhook(request: Request):
-    email = client.parse(await request.body())
+    email = client.parse_webhook(await request.body())
 
     if email.conversation_id:
         # Follow-up — route to the existing conversation
@@ -186,7 +209,7 @@ Inbound email attachments are automatically parsed and available on
 `email.attachments`:
 
 ```python
-email = client.parse(body)
+email = client.parse_webhook(body)
 for att in email.attachments:
     print(f"{att.filename} ({att.content_type}, {att.size} bytes)")
     save_file(att.filename, att.data)
@@ -239,7 +262,7 @@ client = AsyncE2AClient()  # reads E2A_API_KEY from env
 
 @app.post("/webhook")
 async def webhook(request: Request):
-    email = client.parse(await request.body())
+    email = await client.parse_webhook(await request.body())
     await email.reply("Thanks!", conversation_id="conv_123")
     return {"ok": True}
 ```
@@ -359,9 +382,13 @@ print(result.status, result.message_id)
 | `auth` | `AuthHeaders` | Full authentication details |
 | `raw_message` | `bytes` | Raw RFC 2822 email bytes |
 
+All claim fields (`message_id`, `sender`, `recipient`, `to`, `cc`, `subject`, `text_body`, `html_body`, `attachments`, `conversation_id`, `received_at`) are gated — accessing them on an unverified webhook payload raises `UnverifiedEmailError`. Always-available regardless of verification: `auth`, `raw_message`, `is_verified`, `verified`, `unverified_payload`. Emails returned by `client.get_message(...)` are pre-verified (the bearer token already authenticated the channel). `client.get_messages(...)` returns lightweight `MessageSummary` items, not `InboundEmail`, so the gate doesn't apply.
+
 **Methods:**
 
+- `email.verify_signature(secret=None)` → `bool` — verifies the HMAC; falls back to `E2A_WEBHOOK_SECRET`. Sets the verified flag on success so claim fields become accessible.
 - `email.reply(body, html_body=None, conversation_id=None, attachments=None)` → `SendResult`
+- `email.unverified_payload` — escape hatch for inspection (debugging, logging) without verifying. Treat as untrusted.
 
 ## API Reference
 
@@ -369,8 +396,9 @@ print(result.status, result.message_id)
 
 High-level sync client. `api_key` falls back to `E2A_API_KEY` env var.
 
-- `client.parse(body)` → `InboundEmail` — accepts bytes, str, dict, or `MessageDetail`
-- `client.get_message(message_id)` → `InboundEmail`
+- `client.parse_webhook(body, secret=None)` → `InboundEmail` — parse + HMAC-verify (recommended for webhook handlers). Reads `E2A_WEBHOOK_SECRET` if no secret is passed; raises `PermissionError` on bad signature.
+- `client.parse(body)` → `InboundEmail` — accepts bytes, str, dict, or `MessageDetail`. Returns *unverified* — claim fields raise `UnverifiedEmailError` until `email.verify_signature()` succeeds.
+- `client.get_message(message_id)` → `InboundEmail` — pre-verified (REST channel auth)
 - `client.get_messages(status="unread", page_size=50)` → `MessageList`
 - `client.reply(message_id, body, ...)` → `SendResult`
 - `client.send(to, subject, body, ...)` → `SendResult`
@@ -388,11 +416,13 @@ Same as `E2AClient` — all I/O methods are `async`. `parse()` is sync (no I/O n
 - `InboundEmail` / `AsyncInboundEmail` — parsed email with `.reply()`
 - `Attachment` — `filename`, `content_type`, `data` (bytes), `size`
 - `SendResult` — `status`, `message_id`, `method`
-- `AuthHeaders` — `verified`, `sender`, `entity_type`, `domain_check`, `delegation`, `signature`, `timestamp`
+- `AuthHeaders` — `verified`, `sender`, `entity_type`, `domain_check`, `delegation`, `signature`, `timestamp`, `message_id`, `body_hash`
 
 ### Exceptions
 
 - `E2AApiError` — API error (has `status_code` and `message`)
+- `UnverifiedEmailError` — raised on `InboundEmail` claim-field access before `verify_signature()` has succeeded
+- `PermissionError` — raised by `parse_webhook` on bad signature
 
 ## License
 

{e2a-2.0.0 → e2a-2.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "e2a"
-version = "2.0.0"
+version = "2.1.0"
 description = "Python SDK for the e2a protocol — email-to-agent authentication"
 readme = "README.md"
 license = "Apache-2.0"

{e2a-2.0.0 → e2a-2.1.0}/src/e2a/v1/client.py

@@ -123,8 +123,8 @@ class E2AClient:
         works. Raises :class:`PermissionError` on signature failure
         (so a webhook handler can let the exception bubble to a 401).
 
-        ``secret`` defaults to the ``E2A_HMAC_SECRET`` environment
-        variable.
+        ``secret`` defaults to the ``E2A_WEBHOOK_SECRET`` environment
+        variable (with ``E2A_HMAC_SECRET`` accepted as a deprecated alias).
         """
         email = self.parse(body)
         if not email.verify_signature(secret):

{e2a-2.0.0 → e2a-2.1.0}/src/e2a/v1/handler.py

@@ -131,6 +131,36 @@ def _verify_auth_headers(
     return hmac.compare_digest(h.signature, expected)
 
 
+_warned_legacy_env = False
+
+
+def _resolve_webhook_secret() -> str:
+    """Read the webhook signing secret from env, preferring the new name.
+
+    Order: ``E2A_WEBHOOK_SECRET`` (canonical) → ``E2A_HMAC_SECRET`` (legacy
+    alias, kept for backward compatibility with SDK 2.0). Emits a one-time
+    DeprecationWarning when only the legacy name is set so users notice
+    before the alias is removed in a future major release.
+    """
+    val = os.environ.get("E2A_WEBHOOK_SECRET", "")
+    if val:
+        return val
+    legacy = os.environ.get("E2A_HMAC_SECRET", "")
+    if legacy:
+        global _warned_legacy_env
+        if not _warned_legacy_env:
+            import warnings
+            warnings.warn(
+                "E2A_HMAC_SECRET is deprecated; rename it to E2A_WEBHOOK_SECRET. "
+                "The legacy name will be removed in a future major release.",
+                DeprecationWarning,
+                stacklevel=3,
+            )
+            _warned_legacy_env = True
+        return legacy
+    return ""
+
+
 @dataclass
 class Attachment:
     """An email attachment."""
@@ -312,9 +342,9 @@ class InboundEmail:
         On success, transitions this instance to the "verified" state
         so subsequent property reads (sender, subject, body, …) work.
 
-        ``secret`` defaults to the ``E2A_HMAC_SECRET`` environment
-        variable when omitted, so the standard webhook-handler pattern
-        is just::
+        ``secret`` defaults to the ``E2A_WEBHOOK_SECRET`` environment
+        variable when omitted (with ``E2A_HMAC_SECRET`` accepted as a
+        deprecated alias), so the standard webhook-handler pattern is::
 
             email = client.parse(body)
             if not email.verify_signature():
@@ -336,11 +366,11 @@ class InboundEmail:
         a verify attempt that always fails.
         """
         if secret is None:
-            secret = os.environ.get("E2A_HMAC_SECRET", "")
+            secret = _resolve_webhook_secret()
         if not secret:
             raise ValueError(
                 "verify_signature requires a secret. Pass it explicitly "
-                "or set E2A_HMAC_SECRET in the environment."
+                "or set E2A_WEBHOOK_SECRET in the environment."
             )
         ok = _verify_auth_headers(self._auth, self._raw_message, secret)
         if ok:
@@ -672,11 +702,11 @@ class AsyncInboundEmail:
     def verify_signature(self, secret: Optional[str] = None) -> bool:
         """See :meth:`InboundEmail.verify_signature` — identical contract."""
         if secret is None:
-            secret = os.environ.get("E2A_HMAC_SECRET", "")
+            secret = _resolve_webhook_secret()
         if not secret:
             raise ValueError(
                 "verify_signature requires a secret. Pass it explicitly "
-                "or set E2A_HMAC_SECRET in the environment."
+                "or set E2A_WEBHOOK_SECRET in the environment."
             )
         ok = _verify_auth_headers(self._auth, self._raw_message, secret)
         if ok:

{e2a-2.0.0 → e2a-2.1.0}/tests/test_v1_handler.py

@@ -452,18 +452,20 @@ def test_unverified_email_allows_verify_inputs():
 
 def test_verify_signature_with_no_secret_and_no_env_raises(monkeypatch):
     """No secret + no env → ValueError (better than silent False)."""
+    monkeypatch.delenv("E2A_WEBHOOK_SECRET", raising=False)
     monkeypatch.delenv("E2A_HMAC_SECRET", raising=False)
     raw = _make_raw_email()
     data = _make_webhook_data(raw)
     email = build_inbound_email(data, _mock_client())
 
-    with pytest.raises(ValueError, match="E2A_HMAC_SECRET"):
+    with pytest.raises(ValueError, match="E2A_WEBHOOK_SECRET"):
         email.verify_signature()
 
 
 def test_verify_signature_reads_env_when_no_arg(monkeypatch):
-    """Default secret comes from E2A_HMAC_SECRET when not passed."""
-    monkeypatch.setenv("E2A_HMAC_SECRET", "wrong-secret-but-not-empty")
+    """Default secret comes from E2A_WEBHOOK_SECRET when not passed."""
+    monkeypatch.delenv("E2A_HMAC_SECRET", raising=False)
+    monkeypatch.setenv("E2A_WEBHOOK_SECRET", "wrong-secret-but-not-empty")
     raw = _make_raw_email()
     data = _make_webhook_data(raw)
     email = build_inbound_email(data, _mock_client())
@@ -474,6 +476,46 @@ def test_verify_signature_reads_env_when_no_arg(monkeypatch):
     assert email.verify_signature() is False
 
 
+def test_verify_signature_falls_back_to_legacy_env(monkeypatch, recwarn):
+    """E2A_HMAC_SECRET still works for SDK 2.0 users, with a deprecation warning."""
+    # Reset the module-level "warned once" flag so this test sees the warning
+    # regardless of test ordering.
+    from e2a.v1 import handler as _handler
+    _handler._warned_legacy_env = False
+
+    monkeypatch.delenv("E2A_WEBHOOK_SECRET", raising=False)
+    monkeypatch.setenv("E2A_HMAC_SECRET", "wrong-secret-but-not-empty")
+    raw = _make_raw_email()
+    data = _make_webhook_data(raw)
+    email = build_inbound_email(data, _mock_client())
+
+    assert email.verify_signature() is False  # called the verify path
+    deprecations = [w for w in recwarn.list if issubclass(w.category, DeprecationWarning)]
+    assert any("E2A_HMAC_SECRET" in str(w.message) for w in deprecations), (
+        "expected DeprecationWarning mentioning E2A_HMAC_SECRET"
+    )
+
+
+def test_verify_signature_prefers_canonical_env_over_legacy(monkeypatch):
+    """When both names are set, E2A_WEBHOOK_SECRET wins (no warning)."""
+    from e2a.v1 import handler as _handler
+    _handler._warned_legacy_env = False
+
+    monkeypatch.setenv("E2A_WEBHOOK_SECRET", "canonical-wrong")
+    monkeypatch.setenv("E2A_HMAC_SECRET", "legacy-wrong")
+    raw = _make_raw_email()
+    data = _make_webhook_data(raw)
+    email = build_inbound_email(data, _mock_client())
+
+    import warnings
+    with warnings.catch_warnings(record=True) as caught:
+        warnings.simplefilter("always")
+        assert email.verify_signature() is False
+        assert not any(issubclass(w.category, DeprecationWarning) for w in caught), (
+            "should not warn when canonical env var is set"
+        )
+
+
 def test_verify_signature_unlocks_field_access_on_success():
     """A successful verify_signature() flips _verified and unlocks fields."""
     raw = _make_raw_email()