Hi.
", + "spf_verdict": "PASS", + "dkim_verdict": "GRAY", + } + row = InboundEmail(**(fields | overrides)) + session.add(row) + await session.flush() + return row + + +# ------------------------------------------------------------------- auth --- + + +@pytest.mark.parametrize("path", [URL, f"{URL}/inbound_x"]) +async def test_a_request_without_a_key_is_refused(app_client: AsyncClient, path: str) -> None: + response = await app_client.get(path) + + assert response.status_code == 401 + assert response.json()["error"]["type"] == "authentication_failed" + + +# ------------------------------------------------------------------- list --- + + +async def test_an_empty_project_lists_nothing_rather_than_failing( + app_client: AsyncClient, db_session: AsyncSession +) -> None: + _, key = await _project_key(db_session, owner="a@example.com") + await db_session.commit() + + response = await app_client.get(URL, headers=_auth(key)) + + assert response.status_code == 200 + assert response.json() == {"data": [], "has_more": False} + + +async def test_the_list_describes_each_message_and_carries_no_body( + app_client: AsyncClient, db_session: AsyncSession +) -> None: + project_id, key = await _project_key(db_session, owner="a@example.com") + row = await _message(db_session, project_id=project_id) + await db_session.commit() + + (item,) = (await app_client.get(URL, headers=_auth(key))).json()["data"] + + assert item["id"] == row.id + assert item["from"] == "ada@other.org" + assert item["to"] == ["support@example.com"] + assert item["subject"] == "Hello there" + assert item["domain"] == "example.com" + assert item["verdicts"]["spf"] == "PASS" + assert item["verdicts"]["dkim"] == "GRAY" + # SES did not say, which is null and not a pass. + assert item["verdicts"]["virus"] is None + assert item["attachment_count"] == 0 + # A page of a hundred messages with their HTML in it is not what a list is for. + for absent in ("text", "html", "headers", "attachments"): + assert absent not in item + + +async def test_nothing_internal_ever_appears_in_a_response( + app_client: AsyncClient, db_session: AsyncSession +) -> None: + """The bucket and the key say where a customer's mail is stored. Neither is + the caller's to know, and neither is any use to them. + """ + project_id, key = await _project_key(db_session, owner="a@example.com") + row = await _message(db_session, project_id=project_id) + await db_session.commit() + + listed = (await app_client.get(URL, headers=_auth(key))).text + detail = (await app_client.get(f"{URL}/{row.id}", headers=_auth(key))).text + + for body in (listed, detail): + assert "seskit-inbound-123456789012" not in body + assert "storage_key" not in body + assert "storage_bucket" not in body + assert row.storage_key not in body + assert "project_id" not in body + + +async def test_another_projects_mail_is_never_listed( + app_client: AsyncClient, db_session: AsyncSession +) -> None: + mine, key = await _project_key(db_session, owner="a@example.com") + theirs, _ = await _project_key(db_session, owner="b@example.com") + await _message(db_session, project_id=mine, subject="mine") + await _message(db_session, project_id=theirs, subject="theirs", second=1) + await db_session.commit() + + subjects = [ + m["subject"] for m in (await app_client.get(URL, headers=_auth(key))).json()["data"] + ] + + assert subjects == ["mine"] + + +async def test_the_list_is_newest_first_and_pages_by_cursor( + app_client: AsyncClient, db_session: AsyncSession +) -> None: + project_id, key = await _project_key(db_session, owner="a@example.com") + ids = [(await _message(db_session, project_id=project_id, second=n)).id for n in range(5)] + await db_session.commit() + newest_first = list(reversed(ids)) + + first = (await app_client.get(URL, params={"limit": 2}, headers=_auth(key))).json() + second = ( + await app_client.get( + URL, + params={"limit": 2, "starting_after": first["data"][-1]["id"]}, + headers=_auth(key), + ) + ).json() + third = ( + await app_client.get( + URL, + params={"limit": 2, "starting_after": second["data"][-1]["id"]}, + headers=_auth(key), + ) + ).json() + + assert [m["id"] for m in first["data"]] == newest_first[:2] + assert first["has_more"] is True + assert [m["id"] for m in second["data"]] == newest_first[2:4] + assert second["has_more"] is True + assert [m["id"] for m in third["data"]] == newest_first[4:] + # The last page says so, and costs no request that comes back empty. + assert third["has_more"] is False + + +async def test_a_page_is_stable_while_mail_arrives_underneath_it( + app_client: AsyncClient, db_session: AsyncSession +) -> None: + """The reason for a cursor over an offset. With an offset, a message arriving + between two pages shifts every row down one and the reader silently skips + the one that moved across the boundary. + """ + project_id, key = await _project_key(db_session, owner="a@example.com") + for n in range(4): + await _message(db_session, project_id=project_id, second=n) + await db_session.commit() + first = (await app_client.get(URL, params={"limit": 2}, headers=_auth(key))).json() + + await _message(db_session, project_id=project_id, second=100) + await db_session.commit() + + second = ( + await app_client.get( + URL, + params={"limit": 2, "starting_after": first["data"][-1]["id"]}, + headers=_auth(key), + ) + ).json() + seen = [m["id"] for m in first["data"]] + [m["id"] for m in second["data"]] + assert len(seen) == len(set(seen)) == 4 + + +async def test_a_cursor_from_another_project_is_a_404_not_a_page( + app_client: AsyncClient, db_session: AsyncSession +) -> None: + """The comparison is lexical, so a foreign id would otherwise position a page + of real messages by a value the caller cannot see - a wrong answer that + looks like a right one. + """ + mine, key = await _project_key(db_session, owner="a@example.com") + theirs, _ = await _project_key(db_session, owner="b@example.com") + await _message(db_session, project_id=mine) + foreign = await _message(db_session, project_id=theirs, second=50) + await db_session.commit() + + response = await app_client.get(URL, params={"starting_after": foreign.id}, headers=_auth(key)) + + assert response.status_code == 404 + assert response.json()["error"]["type"] == "not_found" + + +async def test_an_unknown_cursor_is_a_404_not_an_empty_page( + app_client: AsyncClient, db_session: AsyncSession +) -> None: + _, key = await _project_key(db_session, owner="a@example.com") + await db_session.commit() + + response = await app_client.get( + URL, params={"starting_after": "inbound_nope"}, headers=_auth(key) + ) + + assert response.status_code == 404 + + +async def test_the_domain_filter_narrows_the_list_and_ignores_case( + app_client: AsyncClient, db_session: AsyncSession +) -> None: + project_id, key = await _project_key(db_session, owner="a@example.com") + await _message(db_session, project_id=project_id, domain="example.com", second=1) + await _message(db_session, project_id=project_id, domain="example.net", second=2) + await db_session.commit() + + response = await app_client.get(URL, params={"domain": " Example.NET "}, headers=_auth(key)) + + assert [m["domain"] for m in response.json()["data"]] == ["example.net"] + + +@pytest.mark.parametrize("limit", [0, 101, -1]) +async def test_a_page_size_out_of_range_is_refused( + app_client: AsyncClient, db_session: AsyncSession, limit: int +) -> None: + _, key = await _project_key(db_session, owner="a@example.com") + await db_session.commit() + + response = await app_client.get(URL, params={"limit": limit}, headers=_auth(key)) + + assert response.status_code in (400, 422) + assert "error" in response.json() + + +# ----------------------------------------------------------------- detail --- + + +async def test_one_message_comes_back_in_full( + app_client: AsyncClient, db_session: AsyncSession +) -> None: + project_id, key = await _project_key(db_session, owner="a@example.com") + row = await _message( + db_session, + project_id=project_id, + envelope_from="bounce@other.org", + envelope_to=["support@example.com", "bcc@example.com"], + reply_to=["replies@other.org"], + message_id_header="abc@other.org", + in_reply_to="first@example.com", + reference_ids=["root@example.com", "first@example.com"], + attachments=[ + { + "index": 0, + "filename": "report.pdf", + "content_type": "application/pdf", + "size": 9, + "inline": False, + "content_id": None, + } + ], + headers=[["Subject", "Hello there"], ["X-Odd", "1"]], + size_bytes=1234, + ) + await db_session.commit() + + body = (await app_client.get(f"{URL}/{row.id}", headers=_auth(key))).json() + + assert body["id"] == row.id + assert body["text"] == "Hi." + assert body["html"] == "Hi.
" + assert body["envelope_from"] == "bounce@other.org" + # A blind copy is in the envelope list and in neither header list. + assert body["recipients"] == ["support@example.com", "bcc@example.com"] + assert body["to"] == ["support@example.com"] + assert body["message_id"] == "abc@other.org" + assert body["in_reply_to"] == "first@example.com" + assert body["references"] == ["root@example.com", "first@example.com"] + assert body["reply_to"] == ["replies@other.org"] + assert body["attachments"] == [ + { + "index": 0, + "filename": "report.pdf", + "content_type": "application/pdf", + "size": 9, + "inline": False, + "content_id": None, + } + ] + assert body["attachment_count"] == 1 + assert body["headers"] == [ + {"name": "Subject", "value": "Hello there"}, + {"name": "X-Odd", "value": "1"}, + ] + assert body["size"] == 1234 + + +async def test_hostile_content_is_returned_exactly_as_sent( + app_client: AsyncClient, db_session: AsyncSession +) -> None: + """The API describes what arrived; it does not clean it. A consumer that + renders it has to treat it as hostile, and the field says so. + """ + project_id, key = await _project_key(db_session, owner="a@example.com") + hostile = '
'
+ row = await _message(db_session, project_id=project_id, html_body=hostile)
+ await db_session.commit()
+
+ body = (await app_client.get(f"{URL}/{row.id}", headers=_auth(key))).json()
+
+ assert body["html"] == hostile
+
+
+async def test_another_projects_message_is_a_404_never_a_403(
+ app_client: AsyncClient, db_session: AsyncSession
+) -> None:
+ """A 403 would confirm the id exists. It must look exactly like one that
+ never did.
+ """
+ _, key = await _project_key(db_session, owner="a@example.com")
+ theirs, _ = await _project_key(db_session, owner="b@example.com")
+ foreign = await _message(db_session, project_id=theirs)
+ await db_session.commit()
+
+ foreign_response = await app_client.get(f"{URL}/{foreign.id}", headers=_auth(key))
+ unknown_response = await app_client.get(f"{URL}/inbound_01NEVEREXISTED", headers=_auth(key))
+
+ assert foreign_response.status_code == 404
+ assert foreign_response.json() == unknown_response.json()
+
+
+async def test_an_unreadable_message_is_still_a_message(
+ app_client: AsyncClient, db_session: AsyncSession
+) -> None:
+ project_id, key = await _project_key(db_session, owner="a@example.com")
+ row = await _message(
+ db_session,
+ project_id=project_id,
+ parse_failed=True,
+ text_body="",
+ html_body="",
+ from_address="",
+ subject="",
+ )
+ await db_session.commit()
+
+ body = (await app_client.get(f"{URL}/{row.id}", headers=_auth(key))).json()
+
+ assert body["parse_failed"] is True
+ assert body["text"] == ""
+ assert body["attachments"] == []
+
+
+# -------------------------------------------------- the original's lifetime ---
+
+
+async def test_the_original_is_available_until_retention_passes(
+ app_client: AsyncClient, db_session: AsyncSession
+) -> None:
+ project_id, key = await _project_key(db_session, owner="a@example.com")
+ live = await _message(db_session, project_id=project_id, second=1)
+ expired = await _message(
+ db_session,
+ project_id=project_id,
+ second=2,
+ raw_expires_at=datetime.now(UTC) - timedelta(days=1),
+ )
+ unknown = await _message(db_session, project_id=project_id, second=3, raw_expires_at=None)
+ await db_session.commit()
+
+ async def available(row: InboundEmail) -> bool:
+ body = (await app_client.get(f"{URL}/{row.id}", headers=_auth(key))).json()
+ return bool(body["raw_available"])
+
+ assert await available(live) is True
+ assert await available(expired) is False
+ # Unknown is not "gone": the answer is "may still be there", and the download
+ # settles it.
+ assert await available(unknown) is True
+
+
+async def test_the_parsed_message_is_still_readable_after_the_original_expires(
+ app_client: AsyncClient, db_session: AsyncSession
+) -> None:
+ """The row outlives the bucket on purpose: it costs almost nothing and the
+ files cost storage.
+ """
+ project_id, key = await _project_key(db_session, owner="a@example.com")
+ row = await _message(
+ db_session, project_id=project_id, raw_expires_at=datetime.now(UTC) - timedelta(days=1)
+ )
+ await db_session.commit()
+
+ response = await app_client.get(f"{URL}/{row.id}", headers=_auth(key))
+
+ assert response.status_code == 200
+ assert response.json()["text"] == "Hi."
+ assert response.json()["raw_available"] is False
+
+
+async def test_a_response_carries_the_rate_limit_headers(
+ app_client: AsyncClient, db_session: AsyncSession
+) -> None:
+ _, key = await _project_key(db_session, owner="a@example.com")
+ await db_session.commit()
+
+ response = await app_client.get(URL, headers=_auth(key))
+
+ assert response.headers["X-RateLimit-Limit"]
+ assert response.headers["X-RateLimit-Remaining"]
+ assert response.headers["X-RateLimit-Reset"]
From 70669a455dd696353f17fcbda4887f20215e0be6 Mon Sep 17 00:00:00 2001
From: Otitodev <198799600+Otitodev@users.noreply.github.com>
Date: Mon, 5 Oct 2026 06:29:36 +0100
Subject: [PATCH 4/7] feat(api): download an attachment, or the original
message
GET /v1/inbound/{id}/attachments/{index} returns one attachment's bytes and
GET /v1/inbound/{id}/raw returns the message exactly as SES received it, as
an .eml. Both fetch the stored message from the project's bucket, on the
project's own key in the project's own region.
These serve bytes a stranger wrote, from the API's own origin, and that is
the whole risk. Whatever the sender declared, the response is a download and
not a document: always application/octet-stream, Content-Disposition:
attachment, nosniff so a browser cannot decide the bytes are HTML, and a CSP
sandbox as what is left if one renders it anyway - no script, no forms, no
same-origin access. no-store, because this is somebody's private mail. A test
sends a file that declares itself text/html and contains script, and asserts
it arrives unaltered and as opaque bytes: the API contains hostile content
and does not pretend to clean it.
Filenames are the last thing between a sender's string and a header. The
parser already reduces them, and content_disposition does not rely on that:
both the plain and the encoded form are built from the same basename, so
neither can carry a path or a name made only of dots, and an empty name
becomes "attachment" in both. Probed against a quote breakout, a CRLF
Set-Cookie, a backslash path and a NUL before it was trusted, and a test
sends a message whose attachment name carries a path and a CRLF-delimited
Set-Cookie through RFC 2231, then asserts on the bytes of the response that
no such header exists.
A request that can be refused without touching S3 is refused first, because
each fetch is a transfer of up to 40 MB and one the caller could have been
told about for free is a cost. An attachment index that does not exist, a
message past retention, an id from another project and a project that is not
connected all fail before any fetch, and tests assert the store was not
asked. Ownership is checked before anything is fetched, so a stranger cannot
make the server read somebody else's mail even to be told it is not theirs.
Retention removes objects at a day boundary, so the date can say "still
there" while the bucket says otherwise; that is a 404 with the same message
and not a server error. A missing s3:GetObject is reported as a permission
failure and not as a missing message, because a user told their mail is gone
when it is a policy to fix would reasonably panic. The parsed message outlives
all of this on purpose.
The fakes for received mail go into app_client by default, for the reason the
provider and provisioner fakes are there: no test should be able to reach AWS
by forgetting to substitute something. That also closes a gap left when the
inbound provisioner dependency was added without an override.
---
apps/api/src/seskit_api/dependencies.py | 18 +-
apps/api/src/seskit_api/routes/v1/inbound.py | 189 ++++++++-
docs/reference/api.md | 67 ++++
docs/reference/openapi.json | 144 +++++++
.../core/src/seskit_core/services/__init__.py | 2 +
.../core/src/seskit_core/services/inbound.py | 5 +
tests/conftest.py | 19 +
tests/fakes/inbound.py | 84 ++++
tests/test_v1_inbound_downloads.py | 377 ++++++++++++++++++
9 files changed, 901 insertions(+), 4 deletions(-)
create mode 100644 tests/fakes/inbound.py
create mode 100644 tests/test_v1_inbound_downloads.py
diff --git a/apps/api/src/seskit_api/dependencies.py b/apps/api/src/seskit_api/dependencies.py
index e798bc0..857142e 100644
--- a/apps/api/src/seskit_api/dependencies.py
+++ b/apps/api/src/seskit_api/dependencies.py
@@ -25,6 +25,7 @@
from seskit_core.security.sessions import SessionData, read_session
from seskit_core.services import (
InboundProvisionerFactory,
+ InboundStoreFactory,
ProviderFactory,
ProvisionerFactory,
get_default_project,
@@ -33,7 +34,12 @@
touch_last_used,
verify_api_key,
)
-from seskit_provider_aws_ses import SESEventProvisioner, SESInboundProvisioner, SESProvider
+from seskit_provider_aws_ses import (
+ S3InboundStore,
+ SESEventProvisioner,
+ SESInboundProvisioner,
+ SESProvider,
+)
from sqlalchemy.ext.asyncio import AsyncSession
@@ -113,6 +119,16 @@ def get_inbound_provisioner_factory() -> InboundProvisionerFactory:
return SESInboundProvisioner
+def get_inbound_store_factory() -> InboundStoreFactory:
+ """How a route reads a stored message back out of its bucket.
+
+ Separate from the provisioner because reading mail and building the plumbing
+ for it are different capabilities with different permissions - a key that
+ can fetch an object does not need to be able to create a bucket.
+ """
+ return S3InboundStore
+
+
async def get_optional_user(
request: Request,
db: Annotated[AsyncSession, Depends(get_session)],
diff --git a/apps/api/src/seskit_api/routes/v1/inbound.py b/apps/api/src/seskit_api/routes/v1/inbound.py
index 5a0327d..a406397 100644
--- a/apps/api/src/seskit_api/routes/v1/inbound.py
+++ b/apps/api/src/seskit_api/routes/v1/inbound.py
@@ -1,4 +1,4 @@
-"""``GET /v1/inbound`` and ``GET /v1/inbound/{id}`` - mail the project received.
+"""``/v1/inbound`` - mail the project received.
The read side of receiving. Nothing here writes: a message is recorded by the
worker as it arrives, and this only says what is there.
@@ -10,16 +10,28 @@
from __future__ import annotations
-from typing import Annotated
+import re
+from typing import Annotated, Any
+from urllib.parse import quote
from fastapi import APIRouter, Depends, Path, Query, Response
+from seskit_core.config import Settings
from seskit_core.db import get_session
+from seskit_core.email.parse import read_attachment
from seskit_core.errors import APIError, ErrorType
from seskit_core.models import InboundEmail
+from seskit_core.models.base import utcnow
+from seskit_core.services import InboundStoreFactory, get_connection, stored_credentials
+from seskit_provider_aws_ses import EXPIRED_MESSAGE
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession
-from seskit_api.dependencies import APIContext, require_api_key
+from seskit_api.dependencies import (
+ APIContext,
+ get_app_settings,
+ get_inbound_store_factory,
+ require_api_key,
+)
from seskit_api.routes.v1.api_keys import API_RESPONSES, apply_rate_limit_headers
from seskit_api.schemas.inbound import (
InboundList,
@@ -148,3 +160,174 @@ async def list_inbound(
data=[summary_of(row) for row in rows[:limit]],
has_more=len(rows) > limit,
)
+
+
+# ------------------------------------------------------------- downloads ---
+#
+# Everything below serves bytes a stranger wrote, from the API's own origin. That
+# is the whole risk, and it is handled the same way for both routes: whatever the
+# sender declared, the response is a download and not a document. A browser that
+# is pointed at one must not render it, sniff it, run script in it, or keep it.
+
+#: Applied to every download.
+#:
+#: ``nosniff`` stops a browser deciding the bytes are HTML because they look like
+#: it. The CSP ``sandbox`` is what is left if one renders it anyway: no script, no
+#: forms, no same-origin access to anything. ``no-store`` because this is somebody's
+#: private mail and should not sit in a shared cache.
+DOWNLOAD_HEADERS = {
+ "X-Content-Type-Options": "nosniff",
+ "Content-Security-Policy": "sandbox; default-src 'none'",
+ "Cache-Control": "private, no-store",
+}
+
+_BINARY_OK: dict[int | str, dict[str, Any]] = {
+ 200: {
+ "description": "The bytes.",
+ "content": {"application/octet-stream": {"schema": {"type": "string", "format": "binary"}}},
+ }
+}
+
+_NOT_SAFE = re.compile(r"[^A-Za-z0-9._ -]")
+
+
+def content_disposition(filename: str) -> str:
+ """A ``Content-Disposition`` that is always a download, for any filename.
+
+ Two forms, because old clients read the plain one and current ones read the
+ encoded one. The plain form is reduced to characters that cannot end the
+ quoted string or start a new header; the encoded form carries the name with
+ everything outside the unreserved set percent-encoded.
+
+ Both are built from the same basename, so neither can carry a path or a name
+ that is only dots, and an empty name becomes ``attachment`` in both. A name
+ that came through the parser already has all of that - this does not rely on
+ it, because it is the last thing between a sender's string and a header, and
+ a client saving the file should not have to sanitise what it was given.
+ """
+ base = filename.replace("\\", "/").rsplit("/", 1)[-1].strip(" .") or "attachment"
+ fallback = _NOT_SAFE.sub("_", base)
+ return f"attachment; filename=\"{fallback}\"; filename*=UTF-8''{quote(base, safe='')}"
+
+
+async def _original(
+ db: AsyncSession,
+ row: InboundEmail,
+ factory: InboundStoreFactory,
+ settings: Settings,
+) -> bytes:
+ """The stored message, or the right error for why not.
+
+ The retention date is checked before anything is fetched. After it the original
+ is gone or about to be, and an S3 call to confirm costs a round trip that can
+ only produce the same answer - so a request past it is refused at once, and one
+ with no known expiry is left to the fetch to settle.
+ """
+ if row.raw_expires_at is not None and row.raw_expires_at <= utcnow():
+ raise APIError(ErrorType.NOT_FOUND, EXPIRED_MESSAGE)
+
+ connection = await get_connection(db, row.project_id)
+ if connection is None or not connection.has_credentials:
+ raise APIError(
+ ErrorType.INVALID_REQUEST,
+ "This project is not connected to AWS, so the original message cannot be "
+ "fetched. Connect it on the AWS page.",
+ )
+
+ store = factory(
+ connection.region, stored_credentials(connection, secret_key=settings.SECRET_KEY)
+ )
+ return await store.fetch_message(bucket=row.storage_bucket, key=row.storage_key)
+
+
+@router.get(
+ "/inbound/{inbound_id}/attachments/{index}",
+ response_class=Response,
+ responses={**API_RESPONSES, **_BINARY_OK},
+ summary="Download an attachment",
+)
+async def download_attachment(
+ inbound_id: Annotated[str, Path(description="The id of the received message.")],
+ index: Annotated[
+ int,
+ Path(ge=0, description="The attachment's `index` from the message's `attachments`."),
+ ],
+ db: Annotated[AsyncSession, Depends(get_session)],
+ context: Annotated[APIContext, Depends(require_api_key)],
+ settings: Annotated[Settings, Depends(get_app_settings)],
+ factory: Annotated[InboundStoreFactory, Depends(get_inbound_store_factory)],
+) -> Response:
+ """One attachment's bytes, fetched from the stored message.
+
+ **Always served as `application/octet-stream`**, whatever the sender declared,
+ with `Content-Disposition: attachment`, `nosniff` and a sandboxing CSP. The
+ declared type is on the message's `attachments` for you to read; it is never
+ one this endpoint believes. These are files a stranger sent, served from your
+ API's origin.
+
+ Needs the stored message, so it stops working when retention removes it. The
+ parsed message does not.
+ """
+ row = await _owned(db, inbound_id, context.project.id)
+ if row is None:
+ raise APIError(ErrorType.NOT_FOUND, "No received email with that id.")
+ if index >= len(row.attachments):
+ # Before the fetch: a request for an attachment that does not exist should
+ # not cost a download of the message to find that out.
+ raise APIError(ErrorType.NOT_FOUND, "That message has no attachment with that index.")
+
+ raw = await _original(db, row, factory, settings)
+ content = read_attachment(raw, index)
+ if content is None:
+ raise APIError(ErrorType.NOT_FOUND, "That message has no attachment with that index.")
+
+ out = Response(
+ content=content.data,
+ media_type="application/octet-stream",
+ headers={**DOWNLOAD_HEADERS, "Content-Disposition": content_disposition(content.filename)},
+ )
+ apply_rate_limit_headers(out, context)
+ return out
+
+
+@router.get(
+ "/inbound/{inbound_id}/raw",
+ response_class=Response,
+ responses={
+ **API_RESPONSES,
+ 200: {
+ "description": "The original message, byte for byte.",
+ "content": {"message/rfc822": {"schema": {"type": "string", "format": "binary"}}},
+ },
+ },
+ summary="Download the original message",
+)
+async def download_raw(
+ inbound_id: Annotated[str, Path(description="The id of the received message.")],
+ db: Annotated[AsyncSession, Depends(get_session)],
+ context: Annotated[APIContext, Depends(require_api_key)],
+ settings: Annotated[Settings, Depends(get_app_settings)],
+ factory: Annotated[InboundStoreFactory, Depends(get_inbound_store_factory)],
+) -> Response:
+ """The message exactly as SES received it, as an `.eml` file.
+
+ Unparsed and unmodified: every header, every part, every attachment. Useful for
+ debugging a message that did not parse as expected, and for handing to another
+ tool. It is the sender's bytes, served as a download with the same protections
+ as an attachment.
+
+ Needs the stored message, so it stops working when retention removes it.
+ """
+ row = await _owned(db, inbound_id, context.project.id)
+ if row is None:
+ raise APIError(ErrorType.NOT_FOUND, "No received email with that id.")
+
+ raw = await _original(db, row, factory, settings)
+
+ out = Response(
+ content=raw,
+ media_type="message/rfc822",
+ headers={**DOWNLOAD_HEADERS, "Content-Disposition": content_disposition(f"{row.id}.eml")},
+ )
+ apply_rate_limit_headers(out, context)
+ return out
diff --git a/docs/reference/api.md b/docs/reference/api.md
index 4035ab9..3175a08 100644
--- a/docs/reference/api.md
+++ b/docs/reference/api.md
@@ -61,6 +61,8 @@ Per project, not per key. Every response carries `X-RateLimit-Limit`,
| `GET` | [`/v1/emails/{email_id}`](#get-v1emailsemail_id) | Retrieve an email |
| `GET` | [`/v1/inbound`](#get-v1inbound) | List received emails |
| `GET` | [`/v1/inbound/{inbound_id}`](#get-v1inboundinbound_id) | Retrieve a received email |
+| `GET` | [`/v1/inbound/{inbound_id}/attachments/{index}`](#get-v1inboundinbound_idattachmentsindex) | Download an attachment |
+| `GET` | [`/v1/inbound/{inbound_id}/raw`](#get-v1inboundinbound_idraw) | Download the original message |
| `GET` | [`/v1/webhooks`](#get-v1webhooks) | List webhook endpoints |
| `GET` | [`/v1/webhooks/{endpoint_id}/deliveries`](#get-v1webhooksendpoint_iddeliveries) | List recent webhook deliveries |
@@ -270,6 +272,71 @@ was sent, and has to be treated as hostile by anything that renders it.
| `429` | Rate limit exceeded. |
+---
+
+## `GET /v1/inbound/{inbound_id}/attachments/{index}`
+
+**Download an attachment**
+
+One attachment's bytes, fetched from the stored message.
+
+**Always served as `application/octet-stream`**, whatever the sender declared,
+with `Content-Disposition: attachment`, `nosniff` and a sandboxing CSP. The
+declared type is on the message's `attachments` for you to read; it is never
+one this endpoint believes. These are files a stranger sent, served from your
+API's origin.
+
+Needs the stored message, so it stops working when retention removes it. The
+parsed message does not.
+
+**Parameters**
+
+| Name | In | | |
+|---|---|---|---|
+| `inbound_id` | path | required | The id of the received message. |
+| `index` | path | required | The attachment's `index` from the message's `attachments`. |
+
+**Responses**
+
+| Status | |
+|---|---|
+| `200` | The bytes. |
+| `401` | Invalid or missing API key. |
+| `422` | Validation Error |
+| `429` | Rate limit exceeded. |
+
+
+---
+
+## `GET /v1/inbound/{inbound_id}/raw`
+
+**Download the original message**
+
+The message exactly as SES received it, as an `.eml` file.
+
+Unparsed and unmodified: every header, every part, every attachment. Useful for
+debugging a message that did not parse as expected, and for handing to another
+tool. It is the sender's bytes, served as a download with the same protections
+as an attachment.
+
+Needs the stored message, so it stops working when retention removes it.
+
+**Parameters**
+
+| Name | In | | |
+|---|---|---|---|
+| `inbound_id` | path | required | The id of the received message. |
+
+**Responses**
+
+| Status | |
+|---|---|
+| `200` | The original message, byte for byte. |
+| `401` | Invalid or missing API key. |
+| `422` | Validation Error |
+| `429` | Rate limit exceeded. |
+
+
---
## `GET /v1/webhooks`
diff --git a/docs/reference/openapi.json b/docs/reference/openapi.json
index 00b5ea7..52d912b 100644
--- a/docs/reference/openapi.json
+++ b/docs/reference/openapi.json
@@ -2138,6 +2138,150 @@
]
}
},
+ "/v1/inbound/{inbound_id}/attachments/{index}": {
+ "get": {
+ "description": "One attachment's bytes, fetched from the stored message.\n\n**Always served as `application/octet-stream`**, whatever the sender declared,\nwith `Content-Disposition: attachment`, `nosniff` and a sandboxing CSP. The\ndeclared type is on the message's `attachments` for you to read; it is never\none this endpoint believes. These are files a stranger sent, served from your\nAPI's origin.\n\nNeeds the stored message, so it stops working when retention removes it. The\nparsed message does not.",
+ "operationId": "download_attachment_v1_inbound__inbound_id__attachments__index__get",
+ "parameters": [
+ {
+ "description": "The id of the received message.",
+ "in": "path",
+ "name": "inbound_id",
+ "required": true,
+ "schema": {
+ "description": "The id of the received message.",
+ "title": "Inbound Id",
+ "type": "string"
+ }
+ },
+ {
+ "description": "The attachment's `index` from the message's `attachments`.",
+ "in": "path",
+ "name": "index",
+ "required": true,
+ "schema": {
+ "description": "The attachment's `index` from the message's `attachments`.",
+ "minimum": 0,
+ "title": "Index",
+ "type": "integer"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "content": {
+ "application/octet-stream": {
+ "schema": {
+ "format": "binary",
+ "type": "string"
+ }
+ }
+ },
+ "description": "The bytes."
+ },
+ "401": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ },
+ "description": "Invalid or missing API key."
+ },
+ "422": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/HTTPValidationError"
+ }
+ }
+ },
+ "description": "Validation Error"
+ },
+ "429": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ },
+ "description": "Rate limit exceeded."
+ }
+ },
+ "summary": "Download an attachment",
+ "tags": [
+ "inbound"
+ ]
+ }
+ },
+ "/v1/inbound/{inbound_id}/raw": {
+ "get": {
+ "description": "The message exactly as SES received it, as an `.eml` file.\n\nUnparsed and unmodified: every header, every part, every attachment. Useful for\ndebugging a message that did not parse as expected, and for handing to another\ntool. It is the sender's bytes, served as a download with the same protections\nas an attachment.\n\nNeeds the stored message, so it stops working when retention removes it.",
+ "operationId": "download_raw_v1_inbound__inbound_id__raw_get",
+ "parameters": [
+ {
+ "description": "The id of the received message.",
+ "in": "path",
+ "name": "inbound_id",
+ "required": true,
+ "schema": {
+ "description": "The id of the received message.",
+ "title": "Inbound Id",
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "content": {
+ "message/rfc822": {
+ "schema": {
+ "format": "binary",
+ "type": "string"
+ }
+ }
+ },
+ "description": "The original message, byte for byte."
+ },
+ "401": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ },
+ "description": "Invalid or missing API key."
+ },
+ "422": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/HTTPValidationError"
+ }
+ }
+ },
+ "description": "Validation Error"
+ },
+ "429": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ },
+ "description": "Rate limit exceeded."
+ }
+ },
+ "summary": "Download the original message",
+ "tags": [
+ "inbound"
+ ]
+ }
+ },
"/v1/webhooks": {
"get": {
"description": "Every webhook endpoint registered on this key's project.\n\nThe signing secret is not included - see the note in\n``schemas/webhooks.py``. It is available on the dashboard, where it is read\nonce by a person rather than returned to code on every call.",
diff --git a/packages/core/src/seskit_core/services/__init__.py b/packages/core/src/seskit_core/services/__init__.py
index 5837fcb..f3557ef 100644
--- a/packages/core/src/seskit_core/services/__init__.py
+++ b/packages/core/src/seskit_core/services/__init__.py
@@ -58,6 +58,7 @@
)
from seskit_core.services.inbound import (
InboundProvisionerFactory,
+ InboundStoreFactory,
PolledInbox,
bucket_name_for,
count_other_receivers,
@@ -136,6 +137,7 @@
"ActivityPoint",
"EmailAlreadyRegistered",
"InboundProvisionerFactory",
+ "InboundStoreFactory",
"IssuedKey",
"Metrics",
"Outgoing",
diff --git a/packages/core/src/seskit_core/services/inbound.py b/packages/core/src/seskit_core/services/inbound.py
index 1e6d677..9e67057 100644
--- a/packages/core/src/seskit_core/services/inbound.py
+++ b/packages/core/src/seskit_core/services/inbound.py
@@ -47,6 +47,7 @@
InboundInfrastructure,
InboundProvisioner,
InboundRule,
+ InboundStore,
)
from seskit_core.services.credentials import stored_credentials
@@ -56,6 +57,10 @@
#: ``ProvisionerFactory``: so this module never imports an adapter.
InboundProvisionerFactory = Callable[[str, AWSCredentials], InboundProvisioner]
+#: Builds a reader of stored messages for a region, on one project's credentials.
+#: Injected so a route never imports an adapter, and a test can substitute one.
+InboundStoreFactory = Callable[[str, AWSCredentials], InboundStore]
+
#: Every rule name starts with this. It must equal the adapter's
#: ``RULE_NAME_PREFIX``, because the bucket policy admits only rules that carry
#: it - a rule named otherwise would be accepted by SES and its writes refused,
diff --git a/tests/conftest.py b/tests/conftest.py
index a0faaec..46fe3f9 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -36,12 +36,15 @@
os.environ.setdefault("SMTP_PORT", "1025")
os.environ.setdefault("EMAILS_FROM_EMAIL", "tests@seskit.local")
+from fakes.inbound import FakeInboundProvisioner, FakeInboundStore
from fakes.queue import FakeQueue
from fakes.ses import FakeProviderFactory, FakeProvisioner
from httpx import ASGITransport, AsyncClient
from redis.asyncio import Redis, from_url
from seskit_api.dependencies import (
get_destination_resolver,
+ get_inbound_provisioner_factory,
+ get_inbound_store_factory,
get_provider_factory,
get_provisioner_factory,
)
@@ -265,6 +268,17 @@ def provisioner_factory() -> type[FakeProvisioner]:
return FakeProvisioner
+@pytest.fixture
+def inbound_store() -> FakeInboundStore:
+ """The stored-mail reader every ``app_client`` test talks to.
+
+ Overridden for the same reason as the others: a download fetches from S3, and
+ no test should be able to reach AWS by forgetting to substitute something.
+ Seed it with ``inbound_store.put(bucket, key, raw)``.
+ """
+ return FakeInboundStore()
+
+
@pytest.fixture
def destination_resolver() -> Callable[[str], list[str]]:
"""Resolves every webhook hostname to one public address.
@@ -288,6 +302,7 @@ async def app_client(
redis_client: Redis,
provider_factory: FakeProviderFactory,
provisioner_factory: type[FakeProvisioner],
+ inbound_store: FakeInboundStore,
destination_resolver: Callable[[str], list[str]],
queue: FakeQueue,
) -> AsyncIterator[AsyncClient]:
@@ -308,6 +323,10 @@ async def _session() -> AsyncIterator[AsyncSession]:
# asks for the `provider_factory` fixture and configures it.
application.dependency_overrides[get_provider_factory] = lambda: provider_factory
application.dependency_overrides[get_provisioner_factory] = lambda: provisioner_factory
+ application.dependency_overrides[get_inbound_provisioner_factory] = lambda: (
+ FakeInboundProvisioner
+ )
+ application.dependency_overrides[get_inbound_store_factory] = lambda: inbound_store.factory
application.dependency_overrides[get_destination_resolver] = lambda: destination_resolver
# The ASGI transport does not run lifespan, so app.state.queue is never
# built - and a real pool would make every send need one anyway.
diff --git a/tests/fakes/inbound.py b/tests/fakes/inbound.py
new file mode 100644
index 0000000..7c82236
--- /dev/null
+++ b/tests/fakes/inbound.py
@@ -0,0 +1,84 @@
+"""Fakes for received mail, for tests that go through the real application.
+
+Substituted for ``S3InboundStore`` and ``SESInboundProvisioner`` so that no test
+can reach AWS by forgetting to override one. They satisfy the same Protocols as
+the real adapters, so a signature drift breaks here as well as in production.
+
+Not the fakes ``test_inbound_service`` uses. Those record calls in class-level
+state to make the refcount observable; these are the quiet versions that sit
+behind every ``app_client`` test, where nothing should be happening at all.
+"""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+from seskit_core.errors import APIError, ErrorType
+from seskit_core.providers import AWSCredentials, InboundInfrastructure, InboundRule
+
+EXPIRED = "That message is no longer in storage."
+
+
+class FakeInboundStore:
+ """Stored messages by ``(bucket, key)``, and a record of every fetch."""
+
+ def __init__(self) -> None:
+ self.objects: dict[tuple[str, str], bytes] = {}
+ self.fetches: list[tuple[str, str]] = []
+ #: Raised by every fetch when set, to stand in for a permission or a
+ #: network failure.
+ self.error: APIError | None = None
+ #: The region and key the last build was handed. Recorded because "does
+ #: this project read its mail with its own key?" is a thing a test asks.
+ self.built_with: tuple[str, AWSCredentials] | None = None
+
+ def put(self, bucket: str, key: str, raw: bytes) -> None:
+ self.objects[(bucket, key)] = raw
+
+ def factory(self, region: str, credentials: AWSCredentials) -> FakeInboundStore:
+ self.built_with = (region, credentials)
+ return self
+
+ async def fetch_message(self, *, bucket: str, key: str) -> bytes:
+ self.fetches.append((bucket, key))
+ if self.error is not None:
+ raise self.error
+ try:
+ return self.objects[(bucket, key)]
+ except KeyError:
+ raise APIError(ErrorType.NOT_FOUND, EXPIRED) from None
+
+
+class FakeInboundProvisioner:
+ """A provisioner that builds nothing and says it did."""
+
+ calls: ClassVar[list[str]] = []
+
+ def __init__(self, region: str, credentials: AWSCredentials | None = None) -> None:
+ self.region = region
+ self.credentials = credentials
+
+ async def provision_inbound(
+ self, *, bucket_name: str, topic_name: str, queue_name: str, retention_days: int
+ ) -> InboundInfrastructure:
+ FakeInboundProvisioner.calls.append("provision")
+ return InboundInfrastructure(
+ bucket=bucket_name,
+ topic_arn=f"arn:aws:sns:{self.region}:123456789012:{topic_name}",
+ queue_url=f"https://sqs.{self.region}.amazonaws.com/123456789012/{queue_name}",
+ queue_arn=f"arn:aws:sqs:{self.region}:123456789012:{queue_name}",
+ subscription_arn=f"arn:aws:sns:{self.region}:123456789012:{topic_name}:sub",
+ )
+
+ async def add_inbound_rule(
+ self, infrastructure: InboundInfrastructure, *, domain: str, rule_name: str
+ ) -> InboundRule:
+ FakeInboundProvisioner.calls.append("add_rule")
+ return InboundRule(name=rule_name, rule_set="seskit-inbound", created_rule_set=True)
+
+ async def remove_inbound_rule(self, rule: InboundRule) -> None:
+ FakeInboundProvisioner.calls.append("remove_rule")
+
+ async def remove_inbound(self, infrastructure: InboundInfrastructure) -> bool:
+ FakeInboundProvisioner.calls.append("remove")
+ return True
diff --git a/tests/test_v1_inbound_downloads.py b/tests/test_v1_inbound_downloads.py
new file mode 100644
index 0000000..4535a55
--- /dev/null
+++ b/tests/test_v1_inbound_downloads.py
@@ -0,0 +1,377 @@
+"""Downloading an attachment, and the original message (inbound email, Phase C).
+
+These routes serve bytes a stranger wrote, from the API's own origin. That is the
+whole risk and most of this file is about it: whatever the sender declared, the
+response has to be a download and not a document, and the headers that make it
+one have to be present on every path.
+
+The other thing worth asserting is what does *not* happen. A request that can be
+refused without touching S3 - an index that does not exist, an expired message, a
+project that is not connected - must be, because each fetch is a transfer of up to
+40 MB, and one the caller could have been told about for free is a cost.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+from typing import Any
+
+import pytest
+from fakes.inbound import EXPIRED, FakeInboundStore
+from fakes.ses import FAKE_CREDENTIALS, connect_project
+from httpx import AsyncClient
+from seskit_api.routes.v1.inbound import DOWNLOAD_HEADERS, content_disposition
+from seskit_core.errors import APIError, ErrorType
+from seskit_core.models import InboundEmail
+from sqlalchemy.ext.asyncio import AsyncSession
+from test_v1_inbound import _auth, _message, _project_key
+
+URL = "/v1/inbound"
+PDF = b"%PDF-1.4\n"
+HTML_ATTACHMENT = b""
+
+
+def _raw() -> bytes:
+ """A message with a PDF and a hostile HTML file, as the wire carries it."""
+ return (
+ b"From: ada@other.org\r\nTo: support@example.com\r\nSubject: with files\r\n"
+ b"MIME-Version: 1.0\r\n"
+ b'Content-Type: multipart/mixed; boundary="M"\r\n\r\n'
+ b"--M\r\nContent-Type: text/plain\r\n\r\nsee attached\r\n"
+ b"--M\r\nContent-Type: application/pdf\r\n"
+ b'Content-Disposition: attachment; filename="report.pdf"\r\n'
+ b"Content-Transfer-Encoding: base64\r\n\r\nJVBERi0xLjQK\r\n"
+ # Declares itself HTML and carries a path and a header-injection attempt in
+ # its name, which can only reach a header through RFC 2231.
+ b"--M\r\nContent-Type: text/html\r\n"
+ b"Content-Disposition: attachment;"
+ b" filename*=UTF-8''..%5C..%2Fevil%0D%0ASet-Cookie%3A%20a%3Db.html\r\n\r\n"
+ + HTML_ATTACHMENT
+ + b"\r\n--M--\r\n"
+ )
+
+
+ATTACHMENTS = [
+ {
+ "index": 0,
+ "filename": "report.pdf",
+ "content_type": "application/pdf",
+ "size": len(PDF),
+ "inline": False,
+ "content_id": None,
+ },
+ {
+ "index": 1,
+ "filename": "evil.html",
+ "content_type": "text/html",
+ "size": len(HTML_ATTACHMENT),
+ "inline": False,
+ "content_id": None,
+ },
+]
+
+
+async def _stored(
+ session: AsyncSession,
+ store: FakeInboundStore,
+ *,
+ owner: str = "a@example.com",
+ connected: bool = True,
+ **overrides: Any,
+) -> tuple[str, str, InboundEmail]:
+ """A project with a key, a message in it, and the original in the store."""
+ project_id, key = await _project_key(session, owner=owner)
+ if connected:
+ await connect_project(session, project_id)
+ row = await _message(session, project_id=project_id, attachments=ATTACHMENTS, **overrides)
+ store.put(row.storage_bucket, row.storage_key, _raw())
+ await session.commit()
+ return project_id, key, row
+
+
+# ------------------------------------------------------------- the header ---
+
+
+@pytest.mark.parametrize(
+ ("filename", "expected_plain"),
+ [
+ ("report.pdf", "report.pdf"),
+ ("../../etc/passwd", "passwd"),
+ ('a"b.txt', "a_b.txt"),
+ ("café.pdf", "caf_.pdf"),
+ ("", "attachment"),
+ ("..", "attachment"),
+ ],
+)
+def test_content_disposition_is_a_download_whatever_the_name(
+ filename: str, expected_plain: str
+) -> None:
+ header = content_disposition(filename)
+
+ assert header.startswith("attachment; ")
+ assert f'filename="{expected_plain}"' in header
+
+
+@pytest.mark.parametrize("filename", ["x\r\nSet-Cookie: a=b", 'a"; x="y', "a\\b;c=d", "\x00\x01"])
+def test_no_name_can_end_the_header_or_start_another(filename: str) -> None:
+ header = content_disposition(filename)
+
+ assert "\r" not in header
+ assert "\n" not in header
+ assert "\x00" not in header
+ # The plain form is one quoted string with nothing after the closing quote
+ # but the encoded form.
+ plain = header.split('filename="', 1)[1].split('"', 1)[0]
+ assert '"' not in plain
+ assert ";" not in plain
+ assert "\\" not in plain
+
+
+# ---------------------------------------------------------------- attachment ---
+
+
+async def test_an_attachment_comes_back_byte_for_byte_as_a_download(
+ app_client: AsyncClient, db_session: AsyncSession, inbound_store: FakeInboundStore
+) -> None:
+ _, key, row = await _stored(db_session, inbound_store)
+
+ response = await app_client.get(f"{URL}/{row.id}/attachments/0", headers=_auth(key))
+
+ assert response.status_code == 200
+ assert response.content == PDF
+ assert response.headers["content-type"] == "application/octet-stream"
+ assert response.headers["content-disposition"].startswith('attachment; filename="report.pdf"')
+ for name, value in DOWNLOAD_HEADERS.items():
+ assert response.headers[name] == value
+ assert response.headers["X-RateLimit-Limit"]
+
+
+async def test_what_the_sender_declared_is_never_believed(
+ app_client: AsyncClient, db_session: AsyncSession, inbound_store: FakeInboundStore
+) -> None:
+ """The second file declares itself text/html and contains script. Served from
+ the API's own origin as HTML it would run with whatever that origin can do.
+ It is served as opaque bytes, in a sandbox, and as a download.
+ """
+ _, key, row = await _stored(db_session, inbound_store)
+
+ response = await app_client.get(f"{URL}/{row.id}/attachments/1", headers=_auth(key))
+
+ assert response.status_code == 200
+ # Unaltered: the API does not clean what it serves, it contains it.
+ assert response.content == HTML_ATTACHMENT
+ assert response.headers["content-type"] == "application/octet-stream"
+ assert "html" not in response.headers["content-type"]
+ assert response.headers["x-content-type-options"] == "nosniff"
+ assert "sandbox" in response.headers["content-security-policy"]
+ assert response.headers["content-disposition"].startswith("attachment;")
+
+
+async def test_a_hostile_filename_cannot_reach_a_header_as_anything_but_a_name(
+ app_client: AsyncClient, db_session: AsyncSession, inbound_store: FakeInboundStore
+) -> None:
+ """The second file's name carries a path and a CRLF-delimited Set-Cookie. The
+ check is on the bytes of the response, not on how the client reads them.
+ """
+ _, key, row = await _stored(db_session, inbound_store)
+
+ response = await app_client.get(f"{URL}/{row.id}/attachments/1", headers=_auth(key))
+
+ disposition = response.headers["content-disposition"]
+ assert "set-cookie" not in {name.lower() for name in response.headers}
+ assert "\r" not in disposition
+ assert "\n" not in disposition
+ assert "/" not in disposition.split("filename=", 1)[1].split(";", 1)[0]
+ assert ".." not in disposition.split('filename="', 1)[1].split('"', 1)[0]
+
+
+async def test_an_attachment_that_does_not_exist_is_refused_without_a_download(
+ app_client: AsyncClient, db_session: AsyncSession, inbound_store: FakeInboundStore
+) -> None:
+ _, key, row = await _stored(db_session, inbound_store)
+
+ response = await app_client.get(f"{URL}/{row.id}/attachments/9", headers=_auth(key))
+
+ assert response.status_code == 404
+ assert response.json()["error"]["type"] == "not_found"
+ assert inbound_store.fetches == []
+
+
+async def test_a_negative_index_is_refused(
+ app_client: AsyncClient, db_session: AsyncSession, inbound_store: FakeInboundStore
+) -> None:
+ _, key, row = await _stored(db_session, inbound_store)
+
+ response = await app_client.get(f"{URL}/{row.id}/attachments/-1", headers=_auth(key))
+
+ assert response.status_code in (400, 404, 422)
+ assert inbound_store.fetches == []
+
+
+# ----------------------------------------------------------------- the raw ---
+
+
+async def test_the_original_comes_back_unmodified_as_an_eml_download(
+ app_client: AsyncClient, db_session: AsyncSession, inbound_store: FakeInboundStore
+) -> None:
+ _, key, row = await _stored(db_session, inbound_store)
+
+ response = await app_client.get(f"{URL}/{row.id}/raw", headers=_auth(key))
+
+ assert response.status_code == 200
+ assert response.content == _raw()
+ assert response.headers["content-type"] == "message/rfc822"
+ assert response.headers["content-disposition"].startswith(
+ f'attachment; filename="{row.id}.eml"'
+ )
+ for name, value in DOWNLOAD_HEADERS.items():
+ assert response.headers[name] == value
+
+
+async def test_the_original_is_readable_even_when_nothing_parsed(
+ app_client: AsyncClient, db_session: AsyncSession, inbound_store: FakeInboundStore
+) -> None:
+ """A message that could not be read is the one somebody most wants the
+ original of.
+ """
+ _, key, row = await _stored(
+ db_session, inbound_store, parse_failed=True, attachments=[], text_body="", html_body=""
+ )
+
+ response = await app_client.get(f"{URL}/{row.id}/raw", headers=_auth(key))
+
+ assert response.status_code == 200
+ assert response.content == _raw()
+
+
+# ------------------------------------------------------------ who may read ---
+
+
+@pytest.mark.parametrize("suffix", ["/attachments/0", "/raw"])
+async def test_a_download_without_a_key_is_refused(
+ app_client: AsyncClient, db_session: AsyncSession, inbound_store: FakeInboundStore, suffix: str
+) -> None:
+ _, _, row = await _stored(db_session, inbound_store)
+
+ response = await app_client.get(f"{URL}/{row.id}{suffix}")
+
+ assert response.status_code == 401
+ assert inbound_store.fetches == []
+
+
+@pytest.mark.parametrize("suffix", ["/attachments/0", "/raw"])
+async def test_another_projects_message_is_a_404_and_is_never_fetched(
+ app_client: AsyncClient, db_session: AsyncSession, inbound_store: FakeInboundStore, suffix: str
+) -> None:
+ """Ownership is checked before anything is fetched, so a stranger cannot make
+ the server read somebody else's mail, even to be told it is not theirs.
+ """
+ _, _, theirs = await _stored(db_session, inbound_store, owner="theirs@example.com")
+ _, mine = await _project_key(db_session, owner="mine@example.com")
+ await db_session.commit()
+
+ foreign = await app_client.get(f"{URL}/{theirs.id}{suffix}", headers=_auth(mine))
+ unknown = await app_client.get(f"{URL}/inbound_01NEVEREXISTED{suffix}", headers=_auth(mine))
+
+ assert foreign.status_code == 404
+ assert foreign.json() == unknown.json()
+ assert inbound_store.fetches == []
+
+
+# ------------------------------------------------------ the original's life ---
+
+
+@pytest.mark.parametrize("suffix", ["/attachments/0", "/raw"])
+async def test_a_message_past_retention_is_refused_without_asking_s3(
+ app_client: AsyncClient, db_session: AsyncSession, inbound_store: FakeInboundStore, suffix: str
+) -> None:
+ """After the date the original is gone or about to be, and a round trip to
+ confirm can only produce the same answer.
+ """
+ _, key, row = await _stored(
+ db_session, inbound_store, raw_expires_at=datetime.now(UTC) - timedelta(days=1)
+ )
+
+ response = await app_client.get(f"{URL}/{row.id}{suffix}", headers=_auth(key))
+
+ assert response.status_code == 404
+ assert "no longer in storage" in response.json()["error"]["message"]
+ assert inbound_store.fetches == []
+
+
+async def test_an_original_that_expired_early_says_so_rather_than_failing(
+ app_client: AsyncClient, db_session: AsyncSession, inbound_store: FakeInboundStore
+) -> None:
+ """Retention removes objects at a day boundary, so the date can say "still
+ there" while the bucket says otherwise. That is a 404 with the same message,
+ not a server error.
+ """
+ _, key, row = await _stored(db_session, inbound_store)
+ inbound_store.objects.clear()
+
+ response = await app_client.get(f"{URL}/{row.id}/raw", headers=_auth(key))
+
+ assert response.status_code == 404
+ assert response.json()["error"]["message"] == EXPIRED
+ assert len(inbound_store.fetches) == 1
+
+
+async def test_the_parsed_message_outlives_the_download(
+ app_client: AsyncClient, db_session: AsyncSession, inbound_store: FakeInboundStore
+) -> None:
+ _, key, row = await _stored(
+ db_session, inbound_store, raw_expires_at=datetime.now(UTC) - timedelta(days=1)
+ )
+
+ assert (await app_client.get(f"{URL}/{row.id}/raw", headers=_auth(key))).status_code == 404
+ assert (await app_client.get(f"{URL}/{row.id}", headers=_auth(key))).status_code == 200
+
+
+# --------------------------------------------------------- AWS credentials ---
+
+
+@pytest.mark.parametrize("suffix", ["/attachments/0", "/raw"])
+async def test_a_project_that_is_not_connected_is_told_so_and_nothing_is_fetched(
+ app_client: AsyncClient, db_session: AsyncSession, inbound_store: FakeInboundStore, suffix: str
+) -> None:
+ _, key, row = await _stored(db_session, inbound_store, connected=False)
+
+ response = await app_client.get(f"{URL}/{row.id}{suffix}", headers=_auth(key))
+
+ assert response.status_code == 400
+ assert response.json()["error"]["type"] == "invalid_request"
+ assert "not connected to AWS" in response.json()["error"]["message"]
+ assert inbound_store.fetches == []
+
+
+async def test_a_message_is_read_with_its_own_projects_key_in_its_own_region(
+ app_client: AsyncClient, db_session: AsyncSession, inbound_store: FakeInboundStore
+) -> None:
+ """Credentials belong to a project, never to the instance. Reading a message
+ on any other key would be a cross-account read.
+ """
+ _, key, row = await _stored(db_session, inbound_store)
+
+ await app_client.get(f"{URL}/{row.id}/raw", headers=_auth(key))
+
+ assert inbound_store.built_with is not None
+ region, credentials = inbound_store.built_with
+ assert region == "us-east-1"
+ assert credentials.access_key_id == FAKE_CREDENTIALS.access_key_id
+
+
+async def test_a_permission_failure_is_reported_as_one_not_as_a_missing_message(
+ app_client: AsyncClient, db_session: AsyncSession, inbound_store: FakeInboundStore
+) -> None:
+ """A missing s3:GetObject must not read as "the message is gone" - the user
+ would conclude their mail was lost when it is a policy to fix.
+ """
+ _, key, row = await _stored(db_session, inbound_store)
+ inbound_store.error = APIError(
+ ErrorType.AUTHORIZATION_FAILED, "not permitted to call s3:GetObject"
+ )
+
+ response = await app_client.get(f"{URL}/{row.id}/raw", headers=_auth(key))
+
+ assert response.status_code == 403
+ assert response.json()["error"]["type"] == "authorization_failed"
From f97252f08930c196b5baa249062a4aa67e659ffe Mon Sep 17 00:00:00 2001
From: Otitodev <198799600+Otitodev@users.noreply.github.com>
Date: Mon, 5 Oct 2026 06:35:44 +0100
Subject: [PATCH 5/7] feat(sdk): read received mail from Python
client.inbound.get, .list, .attachment and .raw, on both SesKit and
AsyncSesKit, over the endpoints the API now has. Thin like the rest of the
SDK: the request builders are shared, so the two clients cannot disagree about
a URL or a parameter name, and nothing here validates or interprets what the
API returned.
Downloads are bytes, and the transport hands them back untouched. A request
now says it wants a file, and a success is returned exactly as received:
decoding it as JSON fails and decoding it as text corrupts it. A test sends
a payload with a NUL, an 0xff and a lone 0x80 through it and asserts it comes
out identical. Errors are still JSON envelopes whichever was asked for, so a
download that fails raises the same typed exception, and it shares the retry
rule with every other call.
An id is interpolated into a URL, and `../emails` is a valid string. Quoted,
it stays one path segment that the API says it does not know, and never a
different endpoint answering with a message that parses as the wrong thing. A
test sends it through a stub and again through the real API, along with a
slash, a query, a fragment and a CRLF. The attachment index is forced through
int so nothing but a number can reach the path. (emails.get does not quote its
id; that predates this and is left for its own change.)
A verdict the API left null stays None and is never read as a pass. The body
fields carry the sender's content untouched and the docstrings say to treat
html as hostile. A list returns summaries and not full messages, as the API
does, so a page of a hundred has no bodies in it.
Tested twice, as the rest of the SDK is: against a stub, for the exact bytes
sent, and against the real application with Postgres behind it, which is the
tier that catches the SDK and the server disagreeing about a field name.
---
packages/sdk-python/src/seskit/__init__.py | 22 +-
.../sdk-python/src/seskit/_async_client.py | 52 ++-
packages/sdk-python/src/seskit/_client.py | 60 +++-
packages/sdk-python/src/seskit/_models.py | 190 +++++++++++
packages/sdk-python/src/seskit/_transport.py | 15 +-
packages/sdk-python/src/seskit/resources.py | 65 ++++
tests/test_sdk_inbound_contract.py | 192 +++++++++++
tests/test_sdk_inbound_transport.py | 300 ++++++++++++++++++
8 files changed, 883 insertions(+), 13 deletions(-)
create mode 100644 tests/test_sdk_inbound_contract.py
create mode 100644 tests/test_sdk_inbound_transport.py
diff --git a/packages/sdk-python/src/seskit/__init__.py b/packages/sdk-python/src/seskit/__init__.py
index cd741cc..f911283 100644
--- a/packages/sdk-python/src/seskit/__init__.py
+++ b/packages/sdk-python/src/seskit/__init__.py
@@ -29,8 +29,8 @@
first-class way to use SESKit.
"""
-from seskit._async_client import AsyncEmails, AsyncSesKit
-from seskit._client import Emails, SesKit
+from seskit._async_client import AsyncEmails, AsyncInbound, AsyncSesKit
+from seskit._client import Emails, Inbound, SesKit
from seskit._errors import (
AttachmentTooLarge,
AuthenticationFailed,
@@ -48,7 +48,16 @@
SESKitError,
SuppressedRecipient,
)
-from seskit._models import Accepted, Email, EmailPage
+from seskit._models import (
+ Accepted,
+ Email,
+ EmailPage,
+ InboundAttachment,
+ InboundEmail,
+ InboundPage,
+ InboundSummary,
+ Verdicts,
+)
from seskit.resources import Attachment
__version__ = "0.1.0"
@@ -56,6 +65,7 @@
__all__ = [
"Accepted",
"AsyncEmails",
+ "AsyncInbound",
"AsyncSesKit",
"Attachment",
"AttachmentTooLarge",
@@ -66,6 +76,11 @@
"EmailPage",
"EmailRejected",
"Emails",
+ "Inbound",
+ "InboundAttachment",
+ "InboundEmail",
+ "InboundPage",
+ "InboundSummary",
"InternalError",
"InvalidRecipient",
"InvalidRequest",
@@ -77,5 +92,6 @@
"SendingLimitExceeded",
"SesKit",
"SuppressedRecipient",
+ "Verdicts",
"__version__",
]
diff --git a/packages/sdk-python/src/seskit/_async_client.py b/packages/sdk-python/src/seskit/_async_client.py
index 2468f65..b750916 100644
--- a/packages/sdk-python/src/seskit/_async_client.py
+++ b/packages/sdk-python/src/seskit/_async_client.py
@@ -26,14 +26,23 @@
import httpx
-from seskit._models import Accepted, Email, EmailPage
+from seskit._models import Accepted, Email, EmailPage, InboundEmail, InboundPage
from seskit._transport import (
DEFAULT_MAX_ATTEMPTS,
DEFAULT_TIMEOUT,
BaseTransport,
Request,
)
-from seskit.resources import Attachment, build_get, build_list, build_send
+from seskit.resources import (
+ Attachment,
+ build_get,
+ build_inbound_attachment,
+ build_inbound_get,
+ build_inbound_list,
+ build_inbound_raw,
+ build_list,
+ build_send,
+)
class _AsyncTransport(BaseTransport):
@@ -66,11 +75,11 @@ async def send(self, request: Request) -> Any:
continue
if not self.should_retry(status_code=last.status_code, attempt=attempt + 1):
- return self.unwrap(last)
+ return self.unwrap(last, binary=request.binary)
await asyncio.sleep(self.backoff(last, attempt))
assert last is not None # noqa: S101 - unreachable; the loop ran at least once
- return self.unwrap(last)
+ return self.unwrap(last, binary=request.binary)
async def aclose(self) -> None:
if self._owns_client:
@@ -134,6 +143,40 @@ async def list(
return EmailPage.from_payload(payload)
+class AsyncInbound:
+ """`client.inbound` - mail your project received."""
+
+ def __init__(self, transport: _AsyncTransport) -> None:
+ self._transport = transport
+
+ async def get(self, inbound_id: str) -> InboundEmail:
+ """One received message, parsed. `NotFound` if it is not this key's project's."""
+ return InboundEmail.from_payload(await self._transport.send(build_inbound_get(inbound_id)))
+
+ async def list(
+ self,
+ *,
+ limit: int | None = None,
+ starting_after: str | None = None,
+ domain: str | None = None,
+ ) -> InboundPage:
+ """One page of received messages, newest first, without bodies."""
+ payload = await self._transport.send(
+ build_inbound_list(limit=limit, starting_after=starting_after, domain=domain)
+ )
+ return InboundPage.from_payload(payload)
+
+ async def attachment(self, inbound_id: str, index: int) -> bytes:
+ """One attachment's bytes. `index` is from the message's `attachments`."""
+ data: bytes = await self._transport.send(build_inbound_attachment(inbound_id, index))
+ return data
+
+ async def raw(self, inbound_id: str) -> bytes:
+ """The message exactly as it was received, as the bytes of an `.eml`."""
+ data: bytes = await self._transport.send(build_inbound_raw(inbound_id))
+ return data
+
+
class AsyncSesKit:
"""A SESKit instance, addressed over HTTP without blocking the loop.
@@ -162,6 +205,7 @@ def __init__(
client=http_client,
)
self.emails = AsyncEmails(self._transport)
+ self.inbound = AsyncInbound(self._transport)
async def aclose(self) -> None:
"""Release the connection pool. Not needed for a client you kept."""
diff --git a/packages/sdk-python/src/seskit/_client.py b/packages/sdk-python/src/seskit/_client.py
index 1a70015..89945e1 100644
--- a/packages/sdk-python/src/seskit/_client.py
+++ b/packages/sdk-python/src/seskit/_client.py
@@ -20,14 +20,23 @@
import httpx
-from seskit._models import Accepted, Email, EmailPage
+from seskit._models import Accepted, Email, EmailPage, InboundEmail, InboundPage
from seskit._transport import (
DEFAULT_MAX_ATTEMPTS,
DEFAULT_TIMEOUT,
BaseTransport,
Request,
)
-from seskit.resources import Attachment, build_get, build_list, build_send
+from seskit.resources import (
+ Attachment,
+ build_get,
+ build_inbound_attachment,
+ build_inbound_get,
+ build_inbound_list,
+ build_inbound_raw,
+ build_list,
+ build_send,
+)
class _Transport(BaseTransport):
@@ -62,13 +71,13 @@ def send(self, request: Request) -> Any:
continue
if not self.should_retry(status_code=last.status_code, attempt=attempt + 1):
- return self.unwrap(last)
+ return self.unwrap(last, binary=request.binary)
time.sleep(self.backoff(last, attempt))
# Out of attempts with a response in hand: raise what it says rather
# than a generic "gave up", so the caller sees the server's own reason.
assert last is not None # noqa: S101 - unreachable; the loop ran at least once
- return self.unwrap(last)
+ return self.unwrap(last, binary=request.binary)
def close(self) -> None:
if self._owns_client:
@@ -145,6 +154,48 @@ def list(
return EmailPage.from_payload(payload)
+class Inbound:
+ """`client.inbound` - mail your project received."""
+
+ def __init__(self, transport: _Transport) -> None:
+ self._transport = transport
+
+ def get(self, inbound_id: str) -> InboundEmail:
+ """One received message, parsed. `NotFound` if it is not this key's project's."""
+ return InboundEmail.from_payload(self._transport.send(build_inbound_get(inbound_id)))
+
+ def list(
+ self,
+ *,
+ limit: int | None = None,
+ starting_after: str | None = None,
+ domain: str | None = None,
+ ) -> InboundPage:
+ """One page of received messages, newest first, without bodies.
+
+ One page, not all of them. Pass `page.last_id` as `starting_after` while
+ `page.has_more`.
+ """
+ payload = self._transport.send(
+ build_inbound_list(limit=limit, starting_after=starting_after, domain=domain)
+ )
+ return InboundPage.from_payload(payload)
+
+ def attachment(self, inbound_id: str, index: int) -> bytes:
+ """One attachment's bytes. `index` is from the message's `attachments`.
+
+ Needs the stored original, so it raises `NotFound` once retention has
+ removed it. The parsed message from `get` does not expire.
+ """
+ data: bytes = self._transport.send(build_inbound_attachment(inbound_id, index))
+ return data
+
+ def raw(self, inbound_id: str) -> bytes:
+ """The message exactly as it was received, as the bytes of an `.eml`."""
+ data: bytes = self._transport.send(build_inbound_raw(inbound_id))
+ return data
+
+
class SesKit:
"""A SESKit instance, addressed over HTTP.
@@ -173,6 +224,7 @@ def __init__(
client=http_client,
)
self.emails = Emails(self._transport)
+ self.inbound = Inbound(self._transport)
def close(self) -> None:
"""Release the connection pool. Not needed for a client you kept."""
diff --git a/packages/sdk-python/src/seskit/_models.py b/packages/sdk-python/src/seskit/_models.py
index aac954b..18ce855 100644
--- a/packages/sdk-python/src/seskit/_models.py
+++ b/packages/sdk-python/src/seskit/_models.py
@@ -135,3 +135,193 @@ def __len__(self) -> int:
def last_id(self) -> str | None:
"""Pass as `starting_after` to fetch the next page. None when empty."""
return self.data[-1].id if self.data else None
+
+
+# --------------------------------------------------------------- inbound ---
+#
+# Mail the project received. Everything in these was written by somebody else:
+# nothing here is cleaned, and `html` in particular is whatever was sent.
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Verdicts:
+ """What SES concluded about a message: `PASS`, `FAIL`, `GRAY` or
+ `PROCESSING_FAILED`. `None` means SES did not say, which is not a pass.
+ """
+
+ spf: str | None = None
+ dkim: str | None = None
+ dmarc: str | None = None
+ #: `none`, `quarantine` or `reject`, and only present when DMARC failed.
+ dmarc_policy: str | None = None
+ spam: str | None = None
+ virus: str | None = None
+
+ @classmethod
+ def from_payload(cls, payload: dict[str, Any] | None) -> Verdicts:
+ data = payload or {}
+ return cls(
+ spf=data.get("spf"),
+ dkim=data.get("dkim"),
+ dmarc=data.get("dmarc"),
+ dmarc_policy=data.get("dmarc_policy"),
+ spam=data.get("spam"),
+ virus=data.get("virus"),
+ )
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class InboundAttachment:
+ """One attachment, described. Fetch the bytes with `inbound.attachment`."""
+
+ index: int
+ filename: str
+ #: What the sender *declared*. It is not checked, and a download is always
+ #: served as `application/octet-stream`.
+ content_type: str
+ size: int
+ inline: bool
+ content_id: str | None = None
+
+ @classmethod
+ def from_payload(cls, payload: dict[str, Any]) -> InboundAttachment:
+ return cls(
+ index=int(payload["index"]),
+ filename=str(payload.get("filename", "")),
+ content_type=str(payload.get("content_type", "")),
+ size=int(payload.get("size", 0)),
+ inline=bool(payload.get("inline")),
+ content_id=payload.get("content_id"),
+ )
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class InboundSummary:
+ """A received message without its body. What `inbound.list` returns."""
+
+ id: str
+ domain: str
+ from_: str
+ from_name: str
+ to: list[str]
+ cc: list[str]
+ subject: str
+ received_at: datetime | None
+ size: int
+ attachment_count: int
+ verdicts: Verdicts
+ #: A limit was hit while reading it, so something is missing here. The
+ #: original has all of it.
+ truncated: bool
+ #: Nothing could be read. Everything else is empty; `inbound.raw` has the
+ #: original until retention removes it.
+ parse_failed: bool
+ #: Whether the original is expected to still be in storage. The parsed message
+ #: stays readable either way.
+ raw_available: bool
+ raw_expires_at: datetime | None
+ raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+ @classmethod
+ def from_payload(cls, payload: dict[str, Any]) -> InboundSummary:
+ return cls(**_summary(payload))
+
+
+def _summary(payload: dict[str, Any]) -> dict[str, Any]:
+ """The fields a summary and a full message share."""
+ return {
+ "id": str(payload["id"]),
+ "domain": str(payload.get("domain", "")),
+ # `from` is a keyword; the trailing underscore is the same compromise as
+ # `Email.from_` and `send(from_=...)`.
+ "from_": str(payload.get("from", "")),
+ "from_name": str(payload.get("from_name", "")),
+ "to": list(payload.get("to") or []),
+ "cc": list(payload.get("cc") or []),
+ "subject": str(payload.get("subject", "")),
+ "received_at": _when(payload.get("received_at")),
+ "size": int(payload.get("size", 0)),
+ "attachment_count": int(payload.get("attachment_count", 0)),
+ "verdicts": Verdicts.from_payload(payload.get("verdicts")),
+ "truncated": bool(payload.get("truncated")),
+ "parse_failed": bool(payload.get("parse_failed")),
+ "raw_available": bool(payload.get("raw_available")),
+ "raw_expires_at": _when(payload.get("raw_expires_at")),
+ "raw": payload,
+ }
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class InboundEmail(InboundSummary):
+ """One received message, in full. What `inbound.get` returns.
+
+ **The bodies are the sender's.** `html` in particular may contain script,
+ tracking images and links that lie, and has to be treated as hostile by
+ anything that renders it.
+ """
+
+ text: str
+ html: str
+ envelope_from: str
+ #: Who it was addressed to on the wire - the addresses that matched your rule.
+ #: A blind copy is here and in neither `to` nor `cc`.
+ recipients: list[str]
+ reply_to: list[str]
+ #: Without angle brackets. Empty if the sender gave none.
+ message_id: str
+ in_reply_to: str
+ references: list[str]
+ attachments: list[InboundAttachment]
+ #: `(name, value)` as sent, in order, up to a limit. Raw and untrusted.
+ headers: list[tuple[str, str]]
+
+ @classmethod
+ def from_payload(cls, payload: dict[str, Any]) -> InboundEmail:
+ return cls(
+ **_summary(payload),
+ text=str(payload.get("text", "")),
+ html=str(payload.get("html", "")),
+ envelope_from=str(payload.get("envelope_from", "")),
+ recipients=list(payload.get("recipients") or []),
+ reply_to=list(payload.get("reply_to") or []),
+ message_id=str(payload.get("message_id", "")),
+ in_reply_to=str(payload.get("in_reply_to", "")),
+ references=list(payload.get("references") or []),
+ attachments=[
+ InboundAttachment.from_payload(a) for a in payload.get("attachments") or []
+ ],
+ headers=[(str(h["name"]), str(h["value"])) for h in payload.get("headers") or []],
+ )
+
+
+@dataclass(frozen=True, slots=True)
+class InboundPage:
+ """One page of `inbound.list`, newest first.
+
+ One page and not everything, for the reason `EmailPage` is: a loop that
+ silently made more requests would turn one line into an unbounded number of
+ them against somebody's rate limit.
+ """
+
+ data: list[InboundSummary]
+ has_more: bool
+ raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+ @classmethod
+ def from_payload(cls, payload: dict[str, Any]) -> InboundPage:
+ return cls(
+ data=[InboundSummary.from_payload(row) for row in payload.get("data") or []],
+ has_more=bool(payload.get("has_more")),
+ raw=payload,
+ )
+
+ def __iter__(self) -> Any:
+ return iter(self.data)
+
+ def __len__(self) -> int:
+ return len(self.data)
+
+ @property
+ def last_id(self) -> str | None:
+ """Pass as `starting_after` to fetch the next page. None when empty."""
+ return self.data[-1].id if self.data else None
diff --git a/packages/sdk-python/src/seskit/_transport.py b/packages/sdk-python/src/seskit/_transport.py
index eeee121..2a79256 100644
--- a/packages/sdk-python/src/seskit/_transport.py
+++ b/packages/sdk-python/src/seskit/_transport.py
@@ -54,6 +54,10 @@ class Request:
json: dict[str, Any] | None = None
params: dict[str, Any] | None = None
headers: dict[str, str] = field(default_factory=dict)
+ #: The answer is a file, not JSON. A download is returned as bytes exactly as
+ #: received - decoding it as JSON would fail, and decoding it as text would
+ #: corrupt it. Errors are still JSON envelopes either way.
+ binary: bool = False
def new_idempotency_key() -> str:
@@ -116,8 +120,15 @@ def headers(self, extra: dict[str, str] | None = None) -> dict[str, str]:
# ------------------------------------------------------------ answers ---
- def unwrap(self, response: httpx.Response) -> Any:
- """The response body, or the exception its error envelope describes."""
+ def unwrap(self, response: httpx.Response, *, binary: bool = False) -> Any:
+ """The response body, or the exception its error envelope describes.
+
+ ``binary`` is for a download: a success is the bytes, untouched. A failure is
+ always a JSON envelope, so it is read the same way whichever was asked for.
+ """
+ if binary and response.is_success:
+ return response.content
+
try:
payload = response.json()
except ValueError:
diff --git a/packages/sdk-python/src/seskit/resources.py b/packages/sdk-python/src/seskit/resources.py
index a56357b..e3f2ee6 100644
--- a/packages/sdk-python/src/seskit/resources.py
+++ b/packages/sdk-python/src/seskit/resources.py
@@ -16,6 +16,7 @@
import base64
from typing import Any
+from urllib.parse import quote
from seskit._transport import Request, new_idempotency_key
@@ -24,6 +25,7 @@
Attachment = tuple[str, bytes, str]
EMAILS = "/emails"
+INBOUND = "/inbound"
def _recipients(value: str | list[str] | None) -> list[str] | None:
@@ -122,3 +124,66 @@ def build_list(
if value is not None:
params[name] = value
return Request(method="GET", path=EMAILS, params=params or None)
+
+
+# --------------------------------------------------------------- inbound ---
+
+
+def _segment(value: str) -> str:
+ """An id as one path segment, whatever it contains.
+
+ Ids are interpolated into a URL, and an id with a slash in it would otherwise
+ reach a different endpoint - ``../emails`` is a valid string. Quoting makes it
+ one segment that the API will say it does not know.
+ """
+ return quote(value, safe="")
+
+
+def build_inbound_get(inbound_id: str) -> Request:
+ """`GET /v1/inbound/{id}`."""
+ return Request(method="GET", path=f"{INBOUND}/{_segment(inbound_id)}")
+
+
+def build_inbound_list(
+ *,
+ limit: int | None = None,
+ starting_after: str | None = None,
+ domain: str | None = None,
+) -> Request:
+ """`GET /v1/inbound`, newest first, without bodies.
+
+ Cursor rather than offset, for the reason `emails.list` is: a message arriving
+ between two pages shifts every row of an offset down one.
+ """
+ params: dict[str, Any] = {}
+ for name, value in (
+ ("limit", limit),
+ ("starting_after", starting_after),
+ ("domain", domain),
+ ):
+ if value is not None:
+ params[name] = value
+ return Request(method="GET", path=INBOUND, params=params or None)
+
+
+def build_inbound_attachment(inbound_id: str, index: int) -> Request:
+ """`GET /v1/inbound/{id}/attachments/{index}`, as bytes.
+
+ ``index`` is forced through ``int`` so nothing but a number can reach the path.
+ """
+ return Request(
+ method="GET",
+ path=f"{INBOUND}/{_segment(inbound_id)}/attachments/{int(index)}",
+ headers={"Accept": "*/*"},
+ binary=True,
+ )
+
+
+def build_inbound_raw(inbound_id: str) -> Request:
+ """`GET /v1/inbound/{id}/raw`, as bytes."""
+ return Request(
+ method="GET",
+ path=f"{INBOUND}/{_segment(inbound_id)}/raw",
+ headers={"Accept": "*/*"},
+ binary=True,
+ )
diff --git a/tests/test_sdk_inbound_contract.py b/tests/test_sdk_inbound_contract.py
new file mode 100644
index 0000000..97a0277
--- /dev/null
+++ b/tests/test_sdk_inbound_contract.py
@@ -0,0 +1,192 @@
+"""The SDK's inbound calls against the real API (inbound email, Phase C).
+
+``tests/test_sdk_inbound_transport.py`` asserts the client sends what it thinks it
+sends. This asserts that what it thinks is right: the same client, pointed at the
+actual application, with the actual Postgres behind it. A stub written from the
+author's memory of the API agrees with a misremembering for ever; here a wrong
+field name is a missing attribute and a renamed error type is an exception nobody
+can catch.
+
+Like ``test_sdk_contract`` it uses the async client, because ``httpx.ASGITransport``
+is async-only. The two clients share the builders, the URL, the headers and the
+transport rule, so what is proved here holds for both.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+
+import pytest
+from fakes.inbound import FakeInboundStore
+from httpx import AsyncClient
+from seskit import InboundEmail, InboundSummary, NotFound
+from sqlalchemy.ext.asyncio import AsyncSession
+from test_sdk_contract import _key, _sdk
+from test_v1_inbound import _message
+from test_v1_inbound_downloads import PDF, _raw, _stored
+
+
+async def test_the_list_reads_back_what_the_api_sent(
+ app_client: AsyncClient, db_session: AsyncSession
+) -> None:
+ project_id, key = await _key(db_session)
+ await _message(db_session, project_id=project_id, subject="Hello there")
+ await db_session.commit()
+
+ page = await _sdk(app_client, key).inbound.list()
+
+ assert len(page) == 1
+ (row,) = page.data
+ assert isinstance(row, InboundSummary)
+ assert not isinstance(row, InboundEmail)
+ assert row.subject == "Hello there"
+ assert row.from_ == "ada@other.org"
+ assert row.to == ["support@example.com"]
+ assert row.verdicts.spf == "PASS"
+ assert row.verdicts.dkim == "GRAY"
+ # Left null by the API, so None here - not a pass.
+ assert row.verdicts.virus is None
+ assert row.received_at is not None
+ assert row.received_at.tzinfo is not None
+ assert page.has_more is False
+
+
+async def test_one_message_reads_back_in_full(
+ app_client: AsyncClient, db_session: AsyncSession
+) -> None:
+ project_id, key = await _key(db_session)
+ row = await _message(
+ db_session,
+ project_id=project_id,
+ envelope_to=["support@example.com", "bcc@example.com"],
+ message_id_header="abc@other.org",
+ reference_ids=["root@example.com"],
+ attachments=[
+ {
+ "index": 0,
+ "filename": "report.pdf",
+ "content_type": "application/pdf",
+ "size": 9,
+ "inline": False,
+ "content_id": None,
+ }
+ ],
+ headers=[["Subject", "Hello there"], ["X-Odd", "1"]],
+ )
+ await db_session.commit()
+
+ message = await _sdk(app_client, key).inbound.get(row.id)
+
+ assert isinstance(message, InboundEmail)
+ assert message.text == "Hi."
+ assert message.html == "Hi.
" + assert message.recipients == ["support@example.com", "bcc@example.com"] + assert message.message_id == "abc@other.org" + assert message.references == ["root@example.com"] + assert [a.filename for a in message.attachments] == ["report.pdf"] + assert message.attachments[0].index == 0 + assert message.headers == [("Subject", "Hello there"), ("X-Odd", "1")] + assert message.raw_available is True + + +async def test_paging_by_last_id_neither_skips_nor_repeats( + app_client: AsyncClient, db_session: AsyncSession +) -> None: + project_id, key = await _key(db_session) + for n in range(5): + await _message(db_session, project_id=project_id, second=n, subject=f"m{n}") + await db_session.commit() + inbound = _sdk(app_client, key).inbound + + seen: list[str] = [] + page = await inbound.list(limit=2) + seen += [row.subject for row in page] + while page.has_more: + page = await inbound.list(limit=2, starting_after=page.last_id) + seen += [row.subject for row in page] + + assert seen == ["m4", "m3", "m2", "m1", "m0"] + + +async def test_the_domain_filter_reaches_the_api( + app_client: AsyncClient, db_session: AsyncSession +) -> None: + project_id, key = await _key(db_session) + await _message(db_session, project_id=project_id, domain="example.com", second=1) + await _message(db_session, project_id=project_id, domain="example.net", second=2) + await db_session.commit() + + page = await _sdk(app_client, key).inbound.list(domain="example.net") + + assert [row.domain for row in page] == ["example.net"] + + +async def test_another_projects_message_is_not_found( + app_client: AsyncClient, db_session: AsyncSession +) -> None: + _, mine = await _key(db_session, owner="mine@example.com") + theirs_project, _ = await _key(db_session, owner="theirs@example.com") + foreign = await _message(db_session, project_id=theirs_project) + await db_session.commit() + + with pytest.raises(NotFound): + await _sdk(app_client, mine).inbound.get(foreign.id) + + +async def test_an_id_that_tries_to_reach_another_endpoint_is_just_not_found( + app_client: AsyncClient, db_session: AsyncSession +) -> None: + """Against the real API, not a stub: ``../emails`` has to arrive as one + segment that nothing matches, and not as a different endpoint's answer. + """ + _, key = await _key(db_session) + await db_session.commit() + + with pytest.raises(NotFound): + await _sdk(app_client, key).inbound.get("../emails") + + +# ------------------------------------------------------------- downloads --- + + +async def test_an_attachment_and_the_original_come_back_byte_for_byte( + app_client: AsyncClient, db_session: AsyncSession, inbound_store: FakeInboundStore +) -> None: + """The bytes survive a trip through the real API and the real transport: no + decoding as text, no JSON, nothing between a PDF in a bucket and a PDF in the + caller's hands. + """ + _, key, row = await _stored(db_session, inbound_store, owner="owner@example.com") + inbound = _sdk(app_client, key).inbound + + assert await inbound.attachment(row.id, 0) == PDF + assert await inbound.raw(row.id) == _raw() + + +async def test_an_attachment_that_does_not_exist_is_not_found( + app_client: AsyncClient, db_session: AsyncSession, inbound_store: FakeInboundStore +) -> None: + _, key, row = await _stored(db_session, inbound_store, owner="owner@example.com") + + with pytest.raises(NotFound): + await _sdk(app_client, key).inbound.attachment(row.id, 9) + + +async def test_a_download_after_retention_is_not_found_but_the_message_still_reads( + app_client: AsyncClient, db_session: AsyncSession, inbound_store: FakeInboundStore +) -> None: + _, key, row = await _stored( + db_session, + inbound_store, + owner="owner@example.com", + raw_expires_at=datetime.now(UTC) - timedelta(days=1), + ) + inbound = _sdk(app_client, key).inbound + + with pytest.raises(NotFound) as caught: + await inbound.raw(row.id) + + assert "no longer in storage" in str(caught.value) + message = await inbound.get(row.id) + assert message.text == "Hi." + assert message.raw_available is False diff --git a/tests/test_sdk_inbound_transport.py b/tests/test_sdk_inbound_transport.py new file mode 100644 index 0000000..a616935 --- /dev/null +++ b/tests/test_sdk_inbound_transport.py @@ -0,0 +1,300 @@ +"""The SDK's inbound calls, against a stub server (inbound email, Phase C). + +What a request looks like and what a response becomes, with no real server, so +these run anywhere and can assert on the exact bytes that would have gone out. +``tests/test_sdk_inbound_contract.py`` is the other half: the same client pointed +at the real application. + +Two things are specific to this resource. A download is *bytes*, and the transport +has to hand them back untouched - decoding them as JSON fails and decoding them as +text corrupts them. And an id is interpolated into a URL, so what an id can reach +is worth a test of its own. +""" + +from __future__ import annotations + +from typing import Any + +import httpx +import pytest +from seskit import ( + AsyncSesKit, + InboundEmail, + InboundPage, + InboundSummary, + NotFound, + SesKit, + Verdicts, +) +from test_sdk_transport import API_KEY, BASE_URL, Recorder, _client, _error, _ok + +SUMMARY: dict[str, Any] = { + "id": "inbound_01J8XQ", + "domain": "example.com", + "from": "ada@other.org", + "from_name": "Ada Lovelace", + "to": ["support@example.com"], + "cc": [], + "subject": "Hello there", + "received_at": "2026-10-05T10:00:00+00:00", + "size": 4821, + "attachment_count": 1, + "verdicts": {"spf": "PASS", "dkim": "GRAY", "dmarc": None, "spam": "PASS", "virus": None}, + "truncated": False, + "parse_failed": False, + "raw_available": True, + "raw_expires_at": "2026-11-04T10:00:00+00:00", +} + +FULL: dict[str, Any] = { + **SUMMARY, + "text": "Hi.", + "html": "Hi.
", + "envelope_from": "bounce@other.org", + "recipients": ["support@example.com", "bcc@example.com"], + "reply_to": ["replies@other.org"], + "message_id": "abc@other.org", + "in_reply_to": "first@example.com", + "references": ["root@example.com", "first@example.com"], + "attachments": [ + { + "index": 0, + "filename": "report.pdf", + "content_type": "application/pdf", + "size": 9, + "inline": False, + "content_id": None, + } + ], + "headers": [{"name": "Subject", "value": "Hello there"}], +} + +#: Not text, not UTF-8, with a NUL in it: what a PDF looks like to a decoder. +BINARY = b"%PDF-1.4\n\x00\xff\xfe\x80binary\r\n" + + +def _bytes(content: bytes = BINARY, status_code: int = 200) -> httpx.Response: + return httpx.Response(status_code, content=content) + + +# --------------------------------------------------------------- reading --- + + +def test_a_received_message_becomes_an_inbound_email() -> None: + recorder = Recorder(_ok(FULL)) + + message = _client(recorder).inbound.get("inbound_01J8XQ") + + assert isinstance(message, InboundEmail) + assert recorder.requests[0].method == "GET" + assert recorder.requests[0].url.path == "/v1/inbound/inbound_01J8XQ" + assert message.id == "inbound_01J8XQ" + # `from` is a keyword, so the attribute carries a trailing underscore. + assert message.from_ == "ada@other.org" + assert message.text == "Hi." + assert message.html == "Hi.
" + assert message.recipients == ["support@example.com", "bcc@example.com"] + assert message.references == ["root@example.com", "first@example.com"] + assert message.attachments[0].filename == "report.pdf" + assert message.attachments[0].index == 0 + assert message.headers == [("Subject", "Hello there")] + assert message.received_at is not None + assert message.received_at.year == 2026 + + +def test_a_verdict_the_api_left_null_stays_none_and_is_never_a_pass() -> None: + message = _client(Recorder(_ok(FULL))).inbound.get("inbound_01J8XQ") + + assert message.verdicts == Verdicts( + spf="PASS", dkim="GRAY", dmarc=None, spam="PASS", virus=None + ) + assert message.verdicts.virus is None + assert message.verdicts.dmarc_policy is None + + +def test_a_page_is_summaries_and_carries_no_body() -> None: + recorder = Recorder( + _ok({"data": [SUMMARY, {**SUMMARY, "id": "inbound_01J8XR"}], "has_more": True}) + ) + + page = _client(recorder).inbound.list() + + assert isinstance(page, InboundPage) + assert len(page) == 2 + assert page.has_more is True + assert page.last_id == "inbound_01J8XR" + assert all(isinstance(row, InboundSummary) for row in page) + assert not any(isinstance(row, InboundEmail) for row in page) + assert not hasattr(page.data[0], "html") + + +def test_an_empty_page_has_no_last_id() -> None: + page = _client(Recorder(_ok({"data": [], "has_more": False}))).inbound.list() + + assert page.last_id is None + assert len(page) == 0 + + +def test_list_sends_only_the_filters_it_was_given() -> None: + recorder = Recorder(_ok({"data": [], "has_more": False})) + client = _client(recorder) + + client.inbound.list() + client.inbound.list(limit=5, starting_after="inbound_x", domain="example.com") + + assert dict(recorder.requests[0].url.params) == {} + assert dict(recorder.requests[1].url.params) == { + "limit": "5", + "starting_after": "inbound_x", + "domain": "example.com", + } + + +def test_a_field_this_version_does_not_know_is_kept() -> None: + """A client from before a field existed still hands it to the caller.""" + message = _client(Recorder(_ok({**FULL, "thread_id": "t_1"}))).inbound.get("inbound_01J8XQ") + + assert message.raw["thread_id"] == "t_1" + + +def test_a_sparse_payload_still_reads() -> None: + message = _client(Recorder(_ok({"id": "inbound_1"}))).inbound.get("inbound_1") + + assert message.id == "inbound_1" + assert message.attachments == [] + assert message.headers == [] + assert message.verdicts == Verdicts() + assert message.received_at is None + + +# ------------------------------------------------------------- downloads --- + + +def test_an_attachment_is_the_bytes_untouched() -> None: + """Not decoded as JSON, which would fail, and not as text, which would + corrupt it: a NUL, an 0xff and a lone 0x80 all have to survive. + """ + recorder = Recorder(_bytes()) + + data = _client(recorder).inbound.attachment("inbound_01J8XQ", 0) + + assert data == BINARY + assert isinstance(data, bytes) + request = recorder.requests[0] + assert request.url.path == "/v1/inbound/inbound_01J8XQ/attachments/0" + # A download does not claim to want JSON. + assert request.headers["Accept"] == "*/*" + assert request.headers["Authorization"] == f"Bearer {API_KEY}" + + +def test_the_original_is_the_bytes_untouched() -> None: + recorder = Recorder(_bytes(b"From: a@b.org\r\n\r\n\xff\x00body")) + + data = _client(recorder).inbound.raw("inbound_01J8XQ") + + assert data == b"From: a@b.org\r\n\r\n\xff\x00body" + assert recorder.requests[0].url.path == "/v1/inbound/inbound_01J8XQ/raw" + + +def test_a_download_that_fails_is_still_a_typed_error() -> None: + """Errors are JSON envelopes whether or not a file was asked for.""" + recorder = Recorder(_error(404, "not_found", "That message is no longer in storage.")) + + with pytest.raises(NotFound) as caught: + _client(recorder).inbound.raw("inbound_01J8XQ") + + assert "no longer in storage" in str(caught.value) + + +def test_a_download_is_tried_again_on_a_server_error() -> None: + """It shares the retry rule with every other call.""" + recorder = Recorder(_error(500, "internal_error"), _bytes()) + + assert _client(recorder).inbound.raw("inbound_01J8XQ") == BINARY + assert len(recorder.requests) == 2 + + +def test_a_refusal_is_not_retried_when_a_file_was_asked_for() -> None: + recorder = Recorder(_error(404, "not_found"), _bytes()) + + with pytest.raises(NotFound): + _client(recorder).inbound.attachment("inbound_01J8XQ", 0) + + assert len(recorder.requests) == 1 + + +# ------------------------------------------------- what an id can reach --- + + +def test_an_id_cannot_leave_its_path_segment() -> None: + """Ids go into a URL, and ``../emails`` is a valid string. Quoted, it stays + one segment, which the API will say it does not know - and never a different + endpoint answering with a message that parses as the wrong thing. + """ + recorder = Recorder(_error(404, "not_found")) + + with pytest.raises(NotFound): + _client(recorder).inbound.get("../emails") + + assert recorder.requests[0].url.raw_path == b"/v1/inbound/..%2Femails" + + +@pytest.mark.parametrize("bad_id", ["a/b", "a?x=1", "a#frag", "a b", "\r\nX: y"]) +def test_no_id_adds_a_segment_a_query_or_a_header(bad_id: str) -> None: + recorder = Recorder(_error(404, "not_found")) + + with pytest.raises(NotFound): + _client(recorder).inbound.raw(bad_id) + + request = recorder.requests[0] + assert request.url.raw_path.count(b"/") == 4 + assert request.url.query == b"" + assert request.url.fragment == "" + assert "X" not in request.headers + + +def test_an_index_that_is_not_a_number_never_reaches_the_url() -> None: + recorder = Recorder(_bytes()) + + with pytest.raises(ValueError): + _client(recorder).inbound.attachment("inbound_01J8XQ", "0/../../raw") # type: ignore[arg-type] + + assert recorder.requests == [] + + +# ------------------------------------------------- the two clients agree --- + + +async def test_the_async_client_sends_the_same_request_and_returns_the_same_bytes() -> None: + """What is proved here and in the contract file holds for both: the request + builders, the URL, the headers and the transport rule are shared. + """ + sync_recorder = Recorder(_bytes()) + async_recorder = Recorder(_bytes()) + sync_client: SesKit = _client(sync_recorder) + async_client = AsyncSesKit( + api_key=API_KEY, + base_url=BASE_URL, + http_client=httpx.AsyncClient(transport=httpx.MockTransport(async_recorder)), + ) + + from_sync = sync_client.inbound.attachment("inbound_01J8XQ", 2) + from_async = await async_client.inbound.attachment("inbound_01J8XQ", 2) + + assert from_sync == from_async == BINARY + one, two = sync_recorder.requests[0], async_recorder.requests[0] + assert (one.method, one.url, one.content) == (two.method, two.url, two.content) + assert one.headers["Accept"] == two.headers["Accept"] == "*/*" + + +async def test_the_async_client_reads_a_message_the_same_way() -> None: + client = AsyncSesKit( + api_key=API_KEY, + base_url=BASE_URL, + http_client=httpx.AsyncClient(transport=httpx.MockTransport(Recorder(_ok(FULL)))), + ) + + message = await client.inbound.get("inbound_01J8XQ") + + assert message.subject == "Hello there" + assert message.attachments[0].filename == "report.pdf" From 38c5f140eead19786bfcbb6baf901c4eca0fb618 Mon Sep 17 00:00:00 2001 From: Otitodev <198799600+Otitodev@users.noreply.github.com> Date: Mon, 5 Oct 2026 06:35:58 +0100 Subject: [PATCH 6/7] fix(api): keep a Content-Security-Policy a route set itself SecurityHeadersMiddleware assigned the dashboard's policy to every response, including /v1, so a route that set its own was silently overwritten. The attachment download sets `sandbox; default-src 'none'` as the layer that is left if a browser renders a stranger's file despite octet-stream, attachment and nosniff. It never reached the client: the response carried `script-src 'self'` instead. The stricter header was discarded and the looser one shipped, with nothing anywhere to say so. Found by the download tests, which assert the header on the response and not on the code that sets it - which is the only reason it was found. The middleware now adds the dashboard policy only when the route has not set one. The rest of the headers are still applied either way, and a route that sets none still gets the dashboard's, so the change cannot leave a page without a policy; a test asserts both halves. The guard was run against the old middleware and fails there. Also fixes the download tests' own helper, which passed `attachments` twice when a test overrode it. --- .../api/src/seskit_api/middleware/security.py | 8 ++++- tests/test_security_headers.py | 31 +++++++++++++++++++ tests/test_v1_inbound_downloads.py | 5 ++- 3 files changed, 42 insertions(+), 2 deletions(-) diff --git a/apps/api/src/seskit_api/middleware/security.py b/apps/api/src/seskit_api/middleware/security.py index e4799d2..0ca630b 100644 --- a/apps/api/src/seskit_api/middleware/security.py +++ b/apps/api/src/seskit_api/middleware/security.py @@ -91,7 +91,13 @@ async def dispatch( response = await call_next(request) - response.headers["Content-Security-Policy"] = policy_for(nonce) + # A route that set its own policy keeps it. This is the dashboard's + # policy, written for pages that render here; applying it over a route + # that deliberately set a stricter one - a download of somebody else's + # file, which sets `sandbox` - would silently discard the stricter one + # and ship the looser, with nothing to say so. + if "Content-Security-Policy" not in response.headers: + response.headers["Content-Security-Policy"] = policy_for(nonce) response.headers["X-Content-Type-Options"] = "nosniff" response.headers["X-Frame-Options"] = "DENY" # same-origin rather than no-referrer: an unsubscribe token or an email diff --git a/tests/test_security_headers.py b/tests/test_security_headers.py index ee6da6e..9a191a8 100644 --- a/tests/test_security_headers.py +++ b/tests/test_security_headers.py @@ -19,8 +19,10 @@ import re from pathlib import Path +from typing import Any import pytest +from fastapi import Response from httpx import AsyncClient from seskit_api.middleware.security import BASE_POLICY, HSTS, policy_for @@ -217,3 +219,32 @@ def test_the_base_policy_leaves_scripts_to_be_completed() -> None: all, because it would look complete. """ assert "script-src" not in BASE_POLICY + + +async def test_a_route_that_sets_its_own_policy_keeps_it(app: Any, client: AsyncClient) -> None: + """Found by a test for something else. A download of somebody's file sets a + `sandbox` policy, and the middleware overwrote it with the dashboard's, which + allows `script-src 'self'`: the stricter header was discarded and the looser + one shipped, with nothing anywhere to say so. + """ + + async def strict() -> Response: + return Response("x", headers={"Content-Security-Policy": "sandbox; default-src 'none'"}) + + app.add_api_route("/_strict_policy", strict) + + response = await client.get("/_strict_policy") + + assert response.headers["Content-Security-Policy"] == "sandbox; default-src 'none'" + # Only the policy yields; the rest of the headers are still applied. + assert response.headers["X-Frame-Options"] == "DENY" + assert response.headers["X-Content-Type-Options"] == "nosniff" + + +async def test_a_route_that_sets_no_policy_still_gets_the_dashboards(client: AsyncClient) -> None: + """The other half: letting a route override must not leave every other one + without a policy. + """ + policy = (await client.get("/healthz")).headers["Content-Security-Policy"] + + assert "script-src 'self' 'nonce-" in policy diff --git a/tests/test_v1_inbound_downloads.py b/tests/test_v1_inbound_downloads.py index 4535a55..6274de5 100644 --- a/tests/test_v1_inbound_downloads.py +++ b/tests/test_v1_inbound_downloads.py @@ -83,7 +83,10 @@ async def _stored( project_id, key = await _project_key(session, owner=owner) if connected: await connect_project(session, project_id) - row = await _message(session, project_id=project_id, attachments=ATTACHMENTS, **overrides) + # Defaults first, so a test that overrides `attachments` replaces them + # instead of passing the keyword twice. + fields: dict[str, Any] = {"attachments": ATTACHMENTS, **overrides} + row = await _message(session, project_id=project_id, **fields) store.put(row.storage_bucket, row.storage_key, _raw()) await session.commit() return project_id, key, row From 4ef75488365bfcb303c69afe2bd663dd6a86fb71 Mon Sep 17 00:00:00 2001 From: Otitodev <198799600+Otitodev@users.noreply.github.com> Date: Mon, 5 Oct 2026 06:38:12 +0100 Subject: [PATCH 7/7] docs: describe received mail, and how it is kept safe The events reference gains `email.received`: the payload, every field, and what makes it different from the others. It carries `inbound_id` and no `email_id`, and it describes the message without carrying it - no body, no headers, no attachment - so the call that fetches the rest is named beside it. A verdict of null is documented as "Amazon SES did not say" and explicitly not a pass, since a reader filtering on spam would otherwise treat an unchecked message as clean. The page also says every active endpoint receives it and that a receiver which validates `type` against a fixed list should add it before turning receiving on, because that is the one way this could surprise somebody. The SDK reference gains the four calls, with the two things a reader most needs to be told: attachment and raw return bytes untouched and stop working when retention removes the original while the parsed message does not, and html in a received message is the sender's and has to be treated as hostile. The security model gains a section for what is a third untrusted boundary and the first one SESKit serves from: why an announcement is believed only if it is ours, why a download is a download whatever the sender declared, why the API does not clean what it returns, why verdicts are recorded and never acted on, and what is and is not logged. Its response-headers row now says a route may set a stricter policy of its own and keep it, which was not true until the previous commit, and its "not covered yet" list says plainly that received mail is not quarantined and attachments are not scanned by SESKit itself. The API reference is generated and was regenerated with the endpoints; this is the prose. A link to an endpoint uses the generator's own anchor, which mkdocs --strict confirms. --- docs/design/security-model.md | 51 ++++++++++++++++++++++++- docs/guides/webhooks.md | 5 +++ docs/reference/events.md | 71 +++++++++++++++++++++++++++++++++-- docs/reference/sdk.md | 27 +++++++++++++ 4 files changed, 150 insertions(+), 4 deletions(-) diff --git a/docs/design/security-model.md b/docs/design/security-model.md index 00cff00..3411831 100644 --- a/docs/design/security-model.md +++ b/docs/design/security-model.md @@ -149,6 +149,52 @@ later without a flag day. after a logout cannot re-display the previous user's dashboard from the browser cache. +## Received mail is hostile input + +Everything in a message somebody sent to you was written by somebody who may mean +you harm. It is a third untrusted boundary, and unlike the two above it is one +SESKit serves *from*. + +**Announcements are believed only if they are ours.** Nothing in an SES +notification is secret: the message id is written into the headers of every +message SES delivers. So the project a message belongs to comes from the +recipient's domain, and is accepted only if it is one of the projects the queue +was read for and the bucket is the one SESKit created. Every way of being wrong +is dropped the same way, before anything is downloaded, so a probe learns nothing +from the difference. + +**A download is a download, whatever the sender declared.** Attachments and the +original message are always served with `Content-Disposition: attachment`, +`X-Content-Type-Options: nosniff` and `Content-Security-Policy: sandbox; +default-src 'none'`, and attachments as `application/octet-stream` regardless of +the type they claim. The filename is the sender's string and is reduced to a +plain basename in both forms of the header, so it cannot carry a path or end the +header. A test sends a file that declares itself HTML and carries script, and a +name containing a CRLF-delimited `Set-Cookie`, and checks the bytes of the +response. + +**The API does not clean what it returns.** `html` and the headers come back +exactly as sent, and the field descriptions say to treat them as hostile. A +sanitiser here would be a second place for a consumer to be wrong. + +**Verdicts are recorded and never acted on.** Amazon SES takes no action on a +failed SPF, DKIM or DMARC check, and neither does SESKit; whether to trust a +message is the reader's decision. A verdict that was not given is stored and +returned as `null`, never as a pass. + +**Storage.** The bucket is private, encrypted, accessible over TLS only, and +writable by receipt rules from this account named `seskit-*` and nothing else. The +original is removed after the retention period; the parsed message is not, so a +message past retention is still readable but its attachments can no longer be +downloaded. + +**Credentials are the project's own.** A message is read with the key of the +project that received it, in its own region. There is no instance-wide key. + +**Nothing from the message is logged.** Sender, recipients, subject and bodies +stay out of logs; an error raised while handling a message is recorded by its type +alone, because its text can carry a fragment of the mail. + ## Response headers Set by one middleware on every response, because the failure mode of @@ -156,7 +202,7 @@ per-route security is a route somebody forgot. | Header | | |---|---| -| `Content-Security-Policy` | `default-src 'self'`, with a per-request nonce for the two inline theme scripts. No `unsafe-inline`, no `unsafe-eval` | +| `Content-Security-Policy` | `default-src 'self'`, with a per-request nonce for the two inline theme scripts. No `unsafe-inline`, no `unsafe-eval`. A route that sets a stricter policy of its own keeps it - downloads of received mail do - and the middleware does not overwrite it | | `X-Frame-Options` / `frame-ancestors` | `DENY` / `'none'`. Every destructive action on the dashboard is a one-click form, which is what clickjacking needs | | `form-action 'self'` | The directive framing protection has no answer for: injected markup posting a CSRF token to another origin | | `X-Content-Type-Options` | `nosniff` | @@ -209,6 +255,9 @@ Stated plainly rather than left to be discovered: - **No HTTP API for the suppression list.** Addresses are suppressed automatically and managed on the dashboard; there is no `/v1` endpoint to read or bulk-load the list. See [suppression](../guides/suppression.md). +- **Received mail is not quarantined.** Amazon SES scans it for spam and viruses + and SESKit records the verdicts, but neither blocks a message from being + stored or served. SESKit does not scan attachments itself. - **No RBAC.** An account owns its projects; there are no roles or team members. - **No per-IP rate limit.** Limits are per project for the API and per account diff --git a/docs/guides/webhooks.md b/docs/guides/webhooks.md index 85521e5..f001a27 100644 --- a/docs/guides/webhooks.md +++ b/docs/guides/webhooks.md @@ -29,6 +29,11 @@ The body is the same normalised event the dashboard stores: } ``` +!!! note "Received mail arrives here too" + Mail sent *to* a domain you receive for produces an `email.received` event. + It has no `email_id` — it carries `inbound_id` — and describes the message + without carrying it. See the [events reference](../reference/events.md#emailreceived). + !!! important "Webhooks need delivery events set up first" Without a configuration set, Amazon SES publishes nothing, so there is nothing to forward. See [delivery events](delivery-events.md). diff --git a/docs/reference/events.md b/docs/reference/events.md index babbdfc..ade46cf 100644 --- a/docs/reference/events.md +++ b/docs/reference/events.md @@ -7,7 +7,7 @@ it forwards to your [webhooks](../guides/webhooks.md). ```text email.sent email.delivered email.bounced email.suppressed -email.opened email.clicked email.complained +email.opened email.clicked email.complained email.received ``` | Type | Emitted when | @@ -19,6 +19,7 @@ email.opened email.clicked email.complained | `email.opened` | The tracking pixel loaded — only with [tracking on](../guides/delivery-events.md#open-and-click-tracking) | | `email.clicked` | A rewritten link was followed — tracking only | | `email.suppressed` | SESKit added an address to the [suppression list](../guides/suppression.md) | +| `email.received` | Mail arrived for one of your domains — see [below](#emailreceived) | SES emits more types than these — `Reject`, `Rendering Failure`, `DeliveryDelay` — which SESKit records but does not currently forward. @@ -42,8 +43,8 @@ SES emits more types than these — `Reject`, `Rendering Failure`, | Field | | |---|---| | `id` | Unique per event. **Deduplicate on this** — delivery is at-least-once | -| `type` | One of the seven above | -| `email_id` | The message this is about; matches `GET /v1/emails/{id}` | +| `type` | One of the eight above | +| `email_id` | The message this is about; matches `GET /v1/emails/{id}`. **Absent on `email.received`**, which carries `inbound_id` instead | | `created_at` | When the event *happened*, not when SESKit heard about it | | `data` | Type-dependent. Always includes `to` | @@ -96,6 +97,70 @@ anything an hour ago. An address already on the list produces no second event, so a repeat bounce is not something your application has to deduplicate. +## `email.received` + +Raised when mail arrives for a domain you have receiving turned on for, and +readable through the [`/v1/inbound` endpoints](api.md#get-v1inbound). It is about a message somebody sent **to you**, so it has no +`email_id`: it carries `inbound_id`, which matches `GET /v1/inbound/{id}`. + +```json +{ + "id": "evt_01J8XQ...", + "type": "email.received", + "inbound_id": "inbound_01J8XQ...", + "created_at": "2026-10-05T10:00:00+00:00", + "data": { + "domain": "example.com", + "from": "ada@other.org", + "from_name": "Ada Lovelace", + "to": ["support@example.com"], + "cc": [], + "recipients": ["support@example.com"], + "subject": "Hello there", + "received_at": "2026-10-05T10:00:00+00:00", + "size": 4821, + "attachment_count": 1, + "verdicts": { + "spf": "PASS", + "dkim": "GRAY", + "dmarc": "PASS", + "spam": "PASS", + "virus": null + }, + "truncated": false, + "parse_failed": false + } +} +``` + +**It describes the message and does not carry it.** There is no body, no +headers and no attachment in the payload, however large the mail is. Fetch the +message with `GET /v1/inbound/{inbound_id}` — that is the call that returns the +bodies, the headers and the attachments. + +| Field | | +|---|---| +| `inbound_id` | The received message. Use it to fetch the rest | +| `from` | The address in the `From` header. Anybody can write anything there — see `verdicts` | +| `to` | The `To` header | +| `recipients` | Who the message was addressed to **on the wire** — the address that actually received it. A blind copy is in this list and in neither `to` nor `cc` | +| `verdicts` | What Amazon SES concluded: `PASS`, `FAIL`, `GRAY` or `PROCESSING_FAILED`. SESKit records them and acts on none | +| `truncated` | A limit was hit while reading the message, so something is missing from the stored copy | +| `parse_failed` | Nothing could be read. The message still exists and `GET /v1/inbound/{id}/raw` has the original | + +**A verdict that is `null` means Amazon SES did not say.** It is not a pass. +Filter on spam or failed authentication only after checking for it, or an +unchecked message will read as a clean one. + +`created_at` is when the message was *received*, not when SESKit processed it. + +Delivery is at-least-once, as for every other event, so **deduplicate on `id`**. +A message that is announced twice produces one event. + +Every active endpoint receives it, as with every other type. If yours checks +`type` against a fixed list, add `email.received` before you turn receiving on. +Nothing is sent until you do. + ## Timestamps `created_at` is when the event occurred at the provider, not when SESKit diff --git a/docs/reference/sdk.md b/docs/reference/sdk.md index fa0640a..a1f6d5e 100644 --- a/docs/reference/sdk.md +++ b/docs/reference/sdk.md @@ -107,6 +107,33 @@ while True: cursor = page.last_id ``` +## Received mail + +```python +page = client.inbound.list(domain="example.com") +message = client.inbound.get(page.data[0].id) + +print(message.from_, message.subject) +print(message.text) + +pdf = client.inbound.attachment(message.id, 0) # bytes +eml = client.inbound.raw(message.id) # bytes +``` + +`list` returns **summaries** — who, what, when, how big, and what Amazon SES +concluded — with no bodies, so a page of a hundred stays small. `get` returns +the whole message. Like `emails.list`, it is **one page**: pass `page.last_id` +as `starting_after` while `page.has_more`. + +`attachment` and `raw` return **bytes, untouched**. They need the stored +original, so they raise `NotFound` once your [retention period](configuration.md) +has removed it. The parsed message from `get` does not expire. + +**Everything in a received message was written by somebody else.** `html` in +particular is exactly what was sent and may contain script, tracking images and +links that lie; do not render it in a page that carries your own credentials. +A verdict that is `None` means Amazon SES did not say — it is not a pass. + ## Async The same surface, awaited: