Security

Binding for implementation. This page is the threat model and the security rules every other design must respect: authentication, authorisation, tenant isolation, secrets, cryptography, untrusted content, SSRF, abuse controls, the supply chain and logging. Where another design owns a mechanism (for example the thread token in Threading), this page states the security property and links to it.

1. Assets and invariants

Each invariant below is enforced in code and covered by a named test (section 13).

2. Trust boundaries

                  TB1                                         TB2 / TB3 / TB7
 Internet MTA ─┬ SMTP ──▶ Email Routing ──▶ email()          Integrator, agent ── HTTPS ──▶ fetch() (API host)
               └ SMTP ──▶ SES receiving ──▶ S3, SNS (TB5)      /v1  /mcp                          │
                                              │              Person, browser ── HTTPS ──▶ fetch() (console host)
                                              ▼                /console/*                         ▼
                        ┌─────────────────────────────── Worker (one deployment) ─────────────────────┐
                        │  router + auth ──▶ D1 scope check ──▶ Durable Object (owner re-check)        │
                        │  queues (pointers) · R2 · Vectorize · Workers AI                              │
                        └──────┬──────────────────────────────┬──────────────────────────────┬──────────┘
                           TB4 │ signed POST              TB5 │ API calls, sockets       TB5 │ SNS POST, SQS poll
                               ▼                              ▼                              ▼
                     integrator webhook URLs     Cloudflare APIs, SES, S3, DoH,     AWS SNS and SQS (SES
                                                 RDAP, scanner, SMTP relays,        delivery and inbound
                                                 Google, GitHub                     notifications)
 TB6: people and systems that operate the deployment (Cloudflare account members, platform-key holders,
      the CLI machine, the release pipeline)
 TB8: third-party services and sites that receive agent assertions and signed HTTP requests, and anyone
      who fetches the public JWKS and key directory (GET /.well-known/* on the API host)

3. STRIDE threat model

Each row names its mitigation and the test that proves it. Tests named in the edge-case register are reused; the others are defined in section 13.

3.1 TB1: internet → inbound sources

3.2 TB2: integrator → REST API

3.3 TB3: agent → MCP

3.4 TB4: Worker → webhook endpoints

3.5 TB5: Worker ↔ Cloudflare APIs, AWS, SMTP relays, OAuth providers, DoH, RDAP, scanner

3.6 TB6: operators of the deployment

3.7 TB7: people → console

The console’s own rules are in Console and workspaces and Cloud sign-up; section 4.9 states the security properties.

3.8 TB8: agent proofs → third parties

How assertions and signed requests are built is in Agent signing keys; these are the security properties.

4. Authentication

4.1 Key format

pmk_{mode}_{lookup}_{secret}

mode    live | test                         (follows the key's tenant; platform keys are live)
lookup  12 chars, lower-case Crockford base32 (alphabet 0123456789abcdefghjkmnpqrstvwxyz), 60 random bits
secret  52 chars, same alphabet, encoding 32 random bytes (256 bits)

regex   ^pmk_(live|test)_[0-9a-hjkmnp-tv-z]{12}_[0-9a-hjkmnp-tv-z]{52}$
example pmk_live_7k2m9q4xa0bc_…(52 characters)

• All randomness comes from platform::Rng. A lookup collision on insert (unique index) is retried with a new value.
• The value returned once as secret by POST /v1/keys and POST /v1/keys/{id}/rotate is the whole string. It is never stored, logged or returned again.
• api_keys.hash is hex(HMAC-SHA256(PM_KEY_PEPPER, <whole key string>)).

4.2 Verification

Every authenticated request (REST and MCP) runs auth::authenticate once, before routing to a handler:

1. Read Authorization: Bearer <token>. Missing, or not matching the regex: 401 unauthenticated.
2. SELECT … FROM api_keys WHERE lookup = ?1 (one indexed D1 read; no cross-request cache, so a revocation takes effect on the next request).
3. Compute mac = HMAC-SHA256(PM_KEY_PEPPER, token). If no row was found, compute it anyway and compare against a fixed dummy value, so a miss and a mismatch cost the same.
4. Compare mac with hex_decode(hash) using Mac::verify_slice (hmac =0.13.0, whose output type compares in constant time). Never compare hex strings with ==.
5. If that fails and prev_hash is set and now < prev_expires_at, compare with prev_hash the same way.
6. No match: 401 unauthenticated. The response is byte-identical for an unknown lookup, a wrong secret and an expired overlap (except request_id).
7. Only now: revoked_at set → 401 key_revoked; expires_at ≤ now → 401 key_expired.
8. The mode in the token must equal the row’s mode; otherwise 401 unauthenticated.
9. Resolve Scope { key_id, level, tenant_id, identity_id, mode, permissions }. For tenant and identity keys, permissions is the key’s list plus the implicit usage:read (section 4.6), and the tenant row is loaded; a tenant in status erasing or erased gives 401 key_revoked (its keys were revoked by the erasure job; this covers the window before that step commits). A suspended tenant still authenticates: suspension is enforced by policy (403 tenant_suspended on sends, FR-TEN-3).

4.3 last_used_at

After a successful authentication the handler schedules, with wait_until (never on the response path):

UPDATE api_keys SET last_used_at = ?1
WHERE id = ?2 AND (last_used_at IS NULL OR last_used_at < ?1 - 60000);

At most one write per key per minute (data model). A failure of this write is logged and ignored.

4.4 Expiry

expires_at is optional and checked on every request (step 7). GET /v1/me returns it so agents can warn before expiry. Expired keys are kept for audit and can be deleted (revoked) like any other.

4.5 Rotation

POST /v1/keys/{key_id}/rotate { "overlap_hours": 0–168 }:

1. Generate a new 32-byte secret; keep id, lookup, level, scope and permissions.
2. In one D1 statement: prev_hash = hash, prev_expires_at = now + overlap_hours, hash = HMAC(new token). With overlap_hours = 0, prev_hash and prev_expires_at are set to NULL.
3. Return the new token once; audit key.rotate.

A second rotation during an overlap replaces prev_hash with the current hash, so at most two secrets are ever valid. Revocation (DELETE /v1/keys/{key_id}) sets revoked_at and clears prev_hash.

4.6 Creating keys (FR-KEY-1)

POST /v1/keys checks, in this order:

1. The request. permissions is required and non-empty at every level, level: platform included: there is no implicit full set (400 invalid_request when it is missing or empty). pmail keys create without --permissions exits 2 with a message (CLI and setup).

2. Permissions allowed at the new key’s level. Some permissions can never be held at some levels, whoever the caller is. Listing one is 400 invalid_request with details.reason = "permission_not_allowed_for_level":

   Permission	Platform key	Tenant key	Identity key
   tenants:manage, platform:ops (platform-only)	yes	no	no
   members:read, members:manage, suppressions:manage, audit:read, usage:read (tenant-only)	yes	yes	no
   identities:sign	no	yes	yes, for its own identity
   Every other permission	yes	yes	yes

3. Scope. Every condition below holds; otherwise 403 key_scope_exceeded:

   Caller level	New key’s level	Tenant	Identity
   platform	any	any existing tenant (tenant, identity levels)	any identity of that tenant (identity level)
   tenant	tenant or identity	must equal the caller’s tenant	any identity of the caller’s tenant
   identity	identity	must equal the caller’s tenant	must equal the caller’s identity

   and permissions is a subset of the caller’s permissions.

• Implicit usage:read. Every tenant and identity key holds usage:read for its own workspace without listing it: authentication adds it to the resolved permissions (section 4.2, step 9). A key reaches only its own workspace, so the grant never reaches another one. An identity key still cannot list it (step 2), and a platform key holds it only when listed.
• The caller needs keys:manage. The new key’s mode is its tenant’s mode; platform keys are live.
• created_by_key_id records the lineage. Revoking a key does not revoke its children; the compromised-key runbook (Observability) revokes descendants explicitly.

4.7 Unauthenticated routes

Only these routes skip authentication, and they are listed explicitly in the router table: GET /health, GET /openapi.json, GET /v1/plans, GET /.well-known/security.txt, the identity JWKS GET /.well-known/jwks/{identity_id}.json and the Web Bot Auth key directory GET /.well-known/http-message-signatures-directory (404 key_not_found while PM_WEB_BOT_AUTH=off; both serve public keys only, Agent signing keys §3), the SNS notification endpoints POST /hooks/ses (SES delivery events) and POST /hooks/ses/inbound (SES inbound notifications), both authenticated by the SNS signature (section 3.5), and signed links GET /v1/links/{token} (authenticated by their MAC, section 7.3). The console (/console/*) and the Stripe webhook (/billing/stripe/webhook) are separate route tables with session and signature checks of their own. In the console table, the routes that need no session are the sign-in, sign-up, waitlist, OAuth start and callback, and invitation-accept routes, and the unsubscribe pair (GET and POST /console/notifications/unsubscribe), which is authenticated by its token alone (section 4.9). Which host answers which path is in section 4.9. The Worker does not serve an MTA-STS policy: the operator publishes one as the self-hosting guide describes.

4.8 The first platform key

No API call can create a key without a key, and the CLI never reads a secret back from the Worker. The CLI therefore mints a platform key only together with a PM_KEY_PEPPER it has just generated and still holds in memory (CLI and setup › The bootstrap key):

1. pmail setup generates the pepper, uploads it with wrangler secret put, computes the hash of a new platform key with it, and inserts the api_keys row and a key.create audit row through the Cloudflare D1 query API with the operator’s CLOUDFLARE_API_TOKEN. This bootstrap key expires after 24 hours; pmail keys create --level platform --permissions … (an explicit list: a platform key has no implicit permission set, §4.6) then creates the long-lived key through POST /v1/keys like any other.
2. A re-run of setup that finds the pepper already set and keys in api_keys stops: the CLI cannot know the old pepper. Only pmail setup --rotate-pepper replaces it, which invalidates every key (the PM_KEY_PEPPER procedure in section 6.2).

4.9 Console authentication and hosts

People authenticate to the console; the REST API and /mcp accept API keys only. The flows are in Console › Sign-in and Cloud sign-up §3–§5. The security properties:

5. Authorisation and tenant isolation

5.1 Deny-by-default router table

Every route is registered with its method, path pattern, required permission(s), scope rule and idempotency rule. The router is built from that table only; a request matching no entry gets 404 with the standard envelope. A route cannot be registered without a permission list and a scope rule (the registration function takes them as non-optional arguments), and public routes use the explicit Scope::Public variant. The permission list may be empty only for Scope::Public and for the two routes that every key may call on its own workspace: GET /v1/me and GET /v1/tenants/{tenant_id}. For the second, foreign_permissions (tenants:manage) is required as well when the target is not the key’s own tenant, and always for a platform key. A unit test fails when any other route has an empty list. GET /v1/usage is not one of them: it is registered with usage:read, which every tenant and identity key holds implicitly for its own workspace (section 4.6), while a platform key needs it listed and must pass tenant_id (400 invalid_request without it).

// crates/worker/src/auth/routes.rs
pub enum Scope {
    Public,                                  // section 4.7 only
    AnyKey,                                  // GET /v1/me
    PlatformOnly,                            // e.g. POST /v1/tenants, POST /v1/webhooks, /v1/platform/*
    TenantPath { param: &'static str },      // /v1/tenants/{tenant_id}/...
    IdentityPath { param: &'static str },    // /v1/identities/{identity_id}/...
    Resource { kind: ResourceKind, param: &'static str }, // domain, webhook, key, erasure, export
    TenantFilter,                            // collection with optional tenant_id filter (GET /v1/usage, /v1/audit-events)
}

pub struct RouteSpec {
    pub method: Method,
    pub pattern: &'static str,
    pub permissions: &'static [Permission],  // all required
    pub foreign_permissions: &'static [Permission], // also required when the target is not the key's own tenant
    pub scope: Scope,
    pub idempotency: Idempotency,            // Required | Optional
    pub min_level: Option<Level>,            // e.g. Tenant for tenant search (FR-SRCH-10)
}

Builds with the itest-hooks cargo feature expose the table at GET /__test/routes, so the attack suite can prove it covers every route (Testing).

5.2 Order of checks

For each request, before any Durable Object or R2 call:

1. Authenticate (section 4.2).
2. Permission. The key must hold every permission in RouteSpec.permissions; otherwise 403 permission_denied with details.required. This check does not depend on the target, so it leaks nothing.
3. Level. If the route is above the key’s level and the target is the key’s own tenant (an identity key holding search:read on POST /v1/tenants/{own}/search), the result is 403 scope_denied (F3). A route that needs a permission the key’s level can never hold (a tenant key on GET /v1/tenants, which needs tenants:manage) already failed step 2 with permission_denied. This also reveals nothing, because the target is the key’s own tenant.
4. Resolve the target’s owner from D1 with the key’s scope as a mandatory parameter of the data-access function (tenant_id is a required argument of every tenant-data query):
   • TenantPath: the tenant ID must equal the key’s tenant (platform keys: the tenant must exist).
   • IdentityPath: SELECT tenant_id, status, mailbox_do_id FROM identities WHERE id = ?1, then compare with the key; identity keys must match their own identity.
   • Resource: load the row and compare its tenant_id (and identity_id where relevant). The platform domain (tenant_id IS NULL) is readable by every key with domains:read.
   • Any mismatch returns the resource’s own *_not_found code with the same body as for a non-existent ID. The check runs whether or not the ID exists, so both paths do one D1 read.
5. Body and query parameters naming a tenant or identity (tenant_id in POST /v1/keys, POST /v1/erasure-requests, POST /v1/exports, identity_ids filters, tenant_id filters): for non-platform keys, a value outside the key’s scope returns 404 tenant_not_found or 404 identity_not_found (for POST /v1/keys, 403 key_scope_exceeded, as api.md states). A value equal to the key’s own scope is accepted. Missing values default to the key’s scope; a platform key has no default tenant, so on GET /v1/usage it must pass tenant_id (400 invalid_request).
6. Call the Durable Object with an RpcEnvelope carrying tenant_id, identity_id, actor_key_id and request_id taken from the resolved scope, never from the request. The object compares them with the owner in its meta and refuses a mismatch with internal_error, logging rpc_owner_mismatch and incrementing rpc_owner_mismatch_total, which alerts at 1 (Design conventions). TenantQuota and Notifier keep their owner in their meta table under tenant_id, written by QuotaRequest::Init and NotifierRequest::Init when the tenant is created, like the other objects (Data model §3).

5.3 Cross-level read access

• An identity key reaches its tenant’s domains read-only with domains:read, and its tenant’s webhook endpoints and deliveries read-only with webhooks:read (api.md). Writes to either from an identity key return 403 scope_denied.
• webhooks:manage includes webhooks:read. platform:ops can only be held by platform keys, like tenants:manage.
• Quarantined, hidden and throttled mail in lists (FR-IN-5). This rule is the reference the API, MCP and console pages follow. A mail list (GET /v1/identities/{identity_id}/messages, and every MCP tool and console view built on it) excludes messages with status quarantined, hidden or throttled by default, whatever the key holds. One of them appears only when both hold: the request filters on that status (status=quarantined, status=hidden or status=throttled), and the key holds quarantine:review. A key without quarantine:review that sends such a filter gets 200 with none of those messages, never 403, as search treats include_quarantined. A thread list has no status filter, so it never shows them. The dedicated quarantine list (GET /v1/identities/{identity_id}/quarantine) requires quarantine:review and lists only quarantined messages. Reading a quarantined, hidden or throttled message by ID (the message itself, its attachments, its raw MIME or its thread view) requires quarantine:review too; otherwise 404 message_not_found, the same answer as for a message that does not exist, so its presence is not revealed.
• Search keeps its own explicit flag and does not contradict the list rule: it never returns hidden or throttled mail, and returns quarantined mail only when the request sets include_quarantined (or uses is:quarantined) and the key holds quarantine:review; without quarantine:review the flag is ignored, never refused (Search § 2).
• Attachments with a risk require quarantine:review (api.md).
• Resuming an identity paused for abuse_threshold requires a tenant or platform key and is audit-logged (api.md).

5.4 Agentic planner and MCP scope

• The planner’s tools are built from the caller’s resolved scope. Tool arguments can narrow the scope (fewer identities, more filters) but never widen it: identity IDs outside the caller’s set are dropped, include_quarantined is honoured only when the caller holds quarantine:review and asked for it, and an attempt to widen is recorded in the trace (F10, Search).
• MCP tools call the same handler functions as REST, through the same RouteSpec entries, so the permission, level and owner checks are identical.

5.5 Inbound isolation

The email() handler takes tenant and identity only from the directory row of the envelope recipient. Header recipients, sub-address tags and message content never select an identity (A2). Thread tokens are bound to the identity ID, so a token minted for one identity never verifies for another (Threading).

6. Secrets

6.1 Inventory

Rules:

• No derivation. No secret is derived from another (no HKDF from a master key). Each is generated independently.
• Never on disk. pmail setup uploads generated secrets with wrangler secret put and does not write them anywhere unless --print-secrets is passed.
• Never read back. Worker secrets are write-only and the signing_keys keyring has no read API. The CLI only ever knows a secret it has just generated. Sealed values that the Worker must use again (SMTP passwords, TOTP secrets, PKCE verifiers, identity and web_bot_auth seeds) are never returned by any API, logged or included in exports; the domain object shows smtp.host, port, username and probe_from, never the password, and an identity key shows only its public JWK.
• Never logged. Secrets, tokens, Authorization headers, signatures, signed-link tokens, minted agent assertions and unsubscribe tokens are never logged at any level (section 12).
• Read once per isolate, through platform::Secrets, and held only in memory. The opened keyring is cached per isolate for 5 minutes (Data model › Notes).

6.2 Rotation procedures

pmail secrets rotate-master. Worker secrets are write-only, so the rotation never needs the old value:

1. Every ciphertext carries the key ID of the key that sealed it (section 7.2).
2. The CLI generates a new key K2 and uploads it as the secret PM_MASTER_KEY_NEXT.
3. While PM_MASTER_KEY_NEXT is set, the Worker decrypts with whichever of PM_MASTER_KEY and PM_MASTER_KEY_NEXT matches the ciphertext’s key ID, and seals every new value with PM_MASTER_KEY_NEXT. The */15 cron re-seals up to 500 values per run in webhook_endpoints.secret_enc, webhook_endpoints.prev_secret_enc, identity_keys.private_enc, signing_keys.ciphertext, domains.smtp_sealed, domains.smtp_pending_sealed, users.totp_sealed, users.recovery_codes_sealed and oauth_states.pkce_sealed whose key ID is not kid(K2).
4. The CLI polls D1 through the Cloudflare D1 query API until no value has a different key ID, then uploads PM_MASTER_KEY = K2 and deletes PM_MASTER_KEY_NEXT.
5. The Worker logs secrets_reseal_progress counts; the CLI prints them.

PM_MASTER_KEY_NEXT is listed in Configuration › Secrets. pmail doctor warns while it is set, because a rotation is unfinished.

Rotating the signing keys. POST /v1/platform/keys/{purpose}/rotate (purpose is thread, link, cursor or web_bot_auth, permission platform:ops, audit-logged as signing_key.rotate with details.revoke_previous) runs one D1 batch: set verify_until on the current key (now + 90 days for thread, now + 7 days for link, now + 24 hours for cursor), and insert a new key with the next kid. Kids are single Crockford base32 characters assigned in alphabet order and wrapping after z. Any existing row with the next kid is deleted in the same batch: normally a key past its verify window that the daily clean-up has not reached yet, and only after 32 rotations of one purpose within its window a key still inside it. With the query ?revoke_previous=true, the previous kid is deleted in the same batch instead of getting a verify window, so everything it signed stops verifying at once. The response carries the purpose, the new kid, created_at and the previous kid with its verify_until (equal to the rotation time, with previous.revoked: true, when revoked), never key material. CLI: pmail keys rotate thread|link|cursor|web_bot_auth [--revoke-previous].

The purpose web_bot_auth follows the same batch with three differences: its kid is the 43-character RFC 7638 thumbprint of the new key’s public JWK (stored with it in public_jwk), not the next letter; the previous key’s verify_until is now + 7 days, during which it stays in the key directory; and the call is refused with 422 web_bot_auth_disabled while PM_WEB_BOT_AUTH=off (Agent signing keys §2).

Residual risk: without revoke_previous, a leaked signing key keeps verifying for its window (90 days, 7 days or 24 hours). After a suspected leak, rotate that purpose with revoke_previous=true, then rotate PM_MASTER_KEY, which sealed it.

7. Cryptography

7.1 Choices

No custom primitives. Truncated MACs are used only for thread tokens (40 bits, rate-limited), signed link tokens and search cursors (128 bits) and log pseudonyms (64 bits, correlation only).

7.2 Encryption envelope

pm1.{kid}.{nonce}.{ciphertext}

kid         first 8 bytes of SHA-256(key bytes), lower-case hex (16 chars); identifies the key, reveals nothing useful
nonce       12 random bytes, base64url without padding
ciphertext  AES-256-GCM ciphertext with its 16-byte tag, base64url without padding
aad         "pm1|{table}|{column}|{row id}", e.g. "pm1|webhook_endpoints|secret_enc|whk_01J9…"
            (signing_keys use "{purpose}:{kid}" as the row id, e.g. "pm1|signing_keys|ciphertext|thread:3",
            and "web_bot_auth:{thumbprint}" for the Web Bot Auth seed; identity keys use their
            thumbprint, e.g. "pm1|identity_keys|private_enc|kPrK_qmx…")

Sealed columns: webhook_endpoints.secret_enc and prev_secret_enc, identity_keys.private_enc (the 32-byte Ed25519 seed), signing_keys.ciphertext (the web_bot_auth seed included), domains.smtp_sealed (aad pm1|domains|smtp_sealed|{domain_id}) and domains.smtp_pending_sealed, users.totp_sealed, users.recovery_codes_sealed and oauth_states.pkce_sealed. The master-key rotation re-seals every one of them (section 6.2).

The associated data stops a ciphertext copied into another row or column from decrypting. With random nonces a key must seal fewer than 2^32 values; the volume here is endpoint secrets, signing keys, relay credentials, second factors and short-lived PKCE verifiers, many orders of magnitude below that.

7.3 Signed links

One link format serves large-attachment links (Outbound) and export downloads (Privacy):

https://{PM_API_HOST}/v1/links/{token}
token   = base64url(payload || HMAC-SHA256(link key {kid}, payload)[0..16])
payload = "l1:{kid}:att:{tenant_id}:{identity_id}:{message_id}:{attachment_id}:{expires_unix_s}"
        | "l1:{kid}:export:{tenant_id}:{export_id}:{expires_unix_s}"
kid     = the one-character kid of the link key that signed it (signing_keys, purpose link)

• The handler splits the token, reads the kid, looks up that link key (current, or still inside its verify window), recomputes the MAC and compares it in constant time, then checks the expiry and that the target still exists. An unknown or expired kid, a bad MAC, an expired link or a missing target all return 404 with the target’s *_not_found code (attachment_not_found or export_not_found), so a link reveals nothing about why it failed.
• No API key is needed: the MAC authenticates the link. The response uses the serving headers of section 8.5. The route is GET /v1/links/{token} in REST API.

8. Untrusted content

8.1 What is untrusted

Everything from mail (headers, display names, subjects, bodies, filenames, attachment text, DSN text), provider responses (smtpResponse, error messages), DNS answers, RDAP data and webhook endpoint responses. Untrusted strings are stored and returned, but never used as instructions, file paths, header values or SQL.

8.2 Sanitising and normalisation

The Inbound pipeline owns the details. The security properties:

• HTML is sanitised with ammonia =4.2.1 using an allow-list: no scripts, event handlers, forms, frames, objects, embeds or <meta http-equiv>; links only http, https and mailto, with rel="noopener noreferrer nofollow"; images only cid: (remote src removed). The service never renders HTML.
• Agent-facing text (extracted_text, snippets, triage and planner input) has hidden text removed (B11): zero-width and bidirectional control characters (U+200B–U+200F, U+202A–U+202E, U+2066–U+2069, U+FEFF), CSS-hidden and white-on-white content, tiny fonts and HTML comments, with the hidden_text flag set. Text is NFC-normalised and C0 control characters other than tab and newline are removed.
• Filenames are stripped of path components and control characters, capped at 255 bytes, and never used as storage keys (R2 keys use IDs only).
• Display names and subjects are stored as received, but CR and LF are rejected in every value the service writes into an outbound header (display_name validation, custom-header validation, subject).
• Tenant-defined reference patterns use the regex crate (linear time, compiled size capped at 64 KB).
• Search input is parsed into a typed tree and every term is quoted for FTS5; raw input never reaches MATCH (F1).
• All SQL uses bound parameters. Building SQL text from request or mail values is forbidden; the native test worker::db::no_formatted_sql fails on format!-built SQL in the data-access modules (Testing).

8.3 Fencing content for models

Triage and the agentic planner receive mail content only inside fences, in the format owned by Search › Fencing mail content and reused by Triage:

<<<MAIL_CONTENT nonce=K7Q2M9XWD3TJ8B5N field=subject>>>Invoice 88213 – AB12 CDE<<<END_MAIL_CONTENT nonce=K7Q2M9XWD3TJ8B5N>>>

• The nonce is 16 Crockford base32 characters from platform::Rng, new for every model call or run. core::injection::fence escapes each untrusted string first: control characters removed, runs of three or more < or > replaced so content can never form a marker, and any occurrence of the nonce replaced.
• Service-generated facts (IDs, verdicts, counts) are outside the fences; every string from mail (display names, addresses, subjects, bodies, filenames, attachment text) is inside one.
• The system prompt states that fenced text is data from third parties, that instructions inside it must be ignored, and that only the listed tools exist.
• Tool results returned to the planner (snippets, thread reads, attachment text) are fenced the same way.
• Model output is never trusted: triage output is validated against its JSON schema and recorded as failed when invalid (FR-TRI-4); planner tool calls are validated against the tool schemas (no additional properties, so a call cannot add scope fields) and the scope clamp (section 5.4); answer sentences pass the deterministic citation verifier (FR-SRCH-8). No model output is executed, rendered or used to choose a recipient.
• core::injection::scan heuristics plus the model set prompt_injection_suspected (E1).

8.4 No remote fetch

The service never fetches a URL found in mail: no link previews, no image proxy, no automatic List-Unsubscribe calls for inbound mail, no fetching of verification links (they are returned by wait, never followed). Sends accept attachment content only as content_base64; there is no “attach from URL”. POST /v1/identities/{identity_id}/http-signatures signs a URL the caller names and returns headers; the Worker never requests that URL, so it is not an SSRF path (Agent signing keys §5.1).

8.5 Serving attachments and raw MIME

GET …/attachments/{attachment_id} and GET …/messages/{message_id}/raw respond with:

Every API response also carries X-Content-Type-Options: nosniff, Referrer-Policy: no-referrer and Strict-Transport-Security: max-age=31536000; authenticated responses carry Cache-Control: no-store. The API and /mcp emit no CORS headers in v1.0: browser code cannot call them cross-origin, and keys must never be placed in browser code. The API sets and reads no cookies, so CSRF does not apply to it; when PM_CONSOLE_HOST differs from PM_API_HOST, no cookie is set or read on the API host at all (section 4.9). The console’s own headers and CSRF rules are in Console › CSRF.

9. SSRF controls

This section is the single definition of the SSRF guard (FR-WH-5). core::ssrf decides (pure functions over the URL and the resolved addresses); worker::net::GuardedHttp (crates/worker/src/net.rs) enforces, resolving through platform::Dns and sending through platform::HttpClient (the platform crate holds no business rules). One guard serves every request to a host that is not a fixed Cloudflare or AWS API host: webhook deliveries and test deliveries (Webhooks), the scanner hook in Inbound, and SMTP relay connections for smtp_relay domains (section 9.3).

9.1 URL rules (at create, update and every attempt)

1. Scheme https only. No userinfo, no fragment, length at most 2,048 bytes.

2. The host must be a DNS name of at least two labels. IP literals in any notation are refused: dotted IPv4, bracketed IPv6, and integer, hexadecimal or octal IPv4 forms such as 2130706433, 0x7f000001 and 0177.0.0.1.

3. Refused names: localhost and any name under the suffixes localhost, local, internal, invalid, test, example, onion, home.arpa and arpa; the API host PM_API_HOST and the console host PM_CONSOLE_HOST; the platform domain PM_PLATFORM_DOMAIN and every name under it. Only the reserved top-level name example is refused: second-level names such as hooks.example.com are allowed, so tests and documentation can use RFC 2606 names.

4. The port is absent, 443, or 1024 to 65535.

5. Resolve A and AAAA through the configured DoH resolvers (first resolver, then the second on error). Refuse if no address is returned, or if any returned address is in a blocked range:

   IPv4  0.0.0.0/8  10.0.0.0/8  100.64.0.0/10  127.0.0.0/8  169.254.0.0/16  172.16.0.0/12
         192.0.0.0/24  192.0.2.0/24  192.88.99.0/24  192.168.0.0/16  198.18.0.0/15
         198.51.100.0/24  203.0.113.0/24  224.0.0.0/4  240.0.0.0/4 (includes 255.255.255.255)
   IPv6  ::/128  ::1/128  ::ffff:0:0/96 (check the embedded IPv4)
         64:ff9b::/96 and 64:ff9b:1::/48 (NAT64: check the embedded IPv4)
         100::/64  2001::/23  2001:db8::/32  2002::/16 (6to4: check the embedded IPv4)
         3fff::/20  5f00::/16  fc00::/7  fe80::/10  fec0::/10  ff00::/8
   

   The table follows the IANA IPv4 and IPv6 special-purpose address registries; re-check it against the registries at build time.

Webhook create and update fail with 400 invalid_request (details.errors[].path = "url") when a rule fails. At delivery time a failure is recorded as a failed attempt with error ssrf_blocked.

9.2 Request rules

• redirect: manual; any 3xx is a failure and is never followed (FR-WH-5).
• Per-attempt deadline 15 s for webhooks (through AbortController); at most 4 KB of the response body is read, then the stream is cancelled.
• No cookies, no forwarding of any inbound header, a fixed User-Agent.
• Resolution runs before every attempt, with no cache shared between attempts. The guard cannot pin the address that the runtime’s fetch resolves, so a DNS-rebinding race remains possible; its reach is limited to addresses routable from Cloudflare’s edge, because the Worker has no Tunnel, VPC or service binding to private networks. This residual risk is accepted and recorded in the threat model (section 3.4).

9.3 Other outbound destinations

10. Rate limiting and abuse

• The rate-limiting bindings are approximate and per location. Anything that must be exact (daily send caps, the agentic budget, abuse windows) is counted in TenantQuota.
• Abuse auto-pause (FR-DLV-3): TenantQuota.outcomes keeps the last 1,000 outcomes per identity. When the complaint rate over the last 1,000 exceeds abuse.complaint_rate_pause (default 0.003), or the bounce rate over the last 200 exceeds abuse.bounce_rate_pause (default 0.05), the identity is paused with reason abuse_threshold and identity.paused is emitted with the metrics.
• Kill switches. Revoke a key (DELETE /v1/keys/{id}, immediate). Pause an identity (PATCH … {"status": "paused"}): besides stopping its sends, this stops it signing at once (409 identity_paused) and withdraws its JWKS (404 identity_not_found), so verifiers stop accepting its assertions within the 5-minute JWKS cache (FR-IDN-9, O1). Revoke one identity key (POST /v1/identities/{identity_id}/keys/{kid}/revoke) to withdraw that key alone. Suspend a tenant (PATCH /v1/tenants/{id} {"status": "suspended"}): every send is refused at once, inbound gets a temporary failure, and every identity of the tenant is paused, so the same signing stop applies. Stop signed HTTP requests for the whole deployment with PM_WEB_BOT_AUTH=off. For a platform-wide stop, suspend every tenant or roll back the Worker version with npx --yes wrangler@4.139.0 rollback.
• Platform domain reputation. Per-identity caps, complaint and bounce auto-pause, a DMARC policy ramped from p=none to p=reject on the platform domain, and custom domains encouraged (PRD risk table).

11. Supply chain

12. Logging rules

Observability defines the schema. The security rules:

• Never logged: message bodies, subjects, attachment content, filenames, display names, clear-text email addresses, raw URLs or query strings (they can contain addresses, for example /v1/identities/lookup?address=…), search queries, verification codes or links, IP addresses, Authorization headers, API key strings, webhook secrets, signed-link tokens, provider smtpResponse text, DNS TXT values, SMTP relay credentials and relay reply text, SNS message bodies (an SES inbound notification carries the message’s headers), OAuth codes, state and tokens, TOTP and recovery codes, cookie values, private keys and seeds, minted agent assertions, their audience, nonce and ext, the URL and headers of a signed HTTP request (Signature, Signature-Input, From), notification unsubscribe tokens and the bodies of notification emails.
• Logged instead: IDs (ten_, idn_, msg_, key_ …), the matched route pattern, error codes, SMTP status codes, counts, sizes, durations, and pseudonyms.
• Pseudonyms: ph_ + the first 16 hex characters of HMAC-SHA256(PM_HASH_KEY, normalised address) (the same HMAC as address_tombstones and suppressions, truncated). Search queries are logged only as query_hash = hex(HMAC-SHA256(PM_HASH_KEY, q))[..16], as in MCP.
• By construction: worker::log accepts only typed fields (IDs, codes, counts, durations, pseudonyms, and a detail string matching ^[a-z0-9_.:-]{1,64}$). There is no free-text field.
• Panics: the platform installs a panic hook that logs event = "panic" with the source location only, never the panic payload, which could contain content.
• Cloudflare invocation logs record the request URL and, for the email handler, the recipient address. The generated wrangler.toml therefore sets invocation_logs = false, and Workers traces are disabled in production (Observability).
• Audit log details_json never contains message content or clear addresses (data model).

The log-scrubbing test I5 plants canary strings in every content field and every address used by the integration suite, captures all Worker output, and fails if any canary appears.

13. Tests

14. security.txt

GET /.well-known/security.txt (RFC 9116), served when PM_SECURITY_CONTACT is set, 404 otherwise:

Contact: mailto:security@example.com
Expires: 2027-10-09T00:00:00Z
Preferred-Languages: en
Canonical: https://mail.example.com/.well-known/security.txt
Policy: https://github.com/PILOTAAI/pylota-mail/security/policy

• Contact is PM_SECURITY_CONTACT, prefixed with mailto: when it is a bare address.
• Expires is the release build date plus 365 days, compiled into the bundle. pmail doctor warns within 30 days of it; an expired file is a correct signal that the deployment is stale.
• Canonical uses PM_API_HOST. Policy points to the upstream project’s policy for flaws in the software; the Contact is the deployment’s own operator.

15. Vulnerability handling

SECURITY.md is the policy: private reporting through GitHub, acknowledgement within 3 working days, a fix and disclosure date agreed with the reporter, and fixes for the latest release only until 1.0. The process behind it:

1. Triage in a private GitHub security advisory; reproduce against a local workerd or staging.
2. Fix in the advisory’s private fork with a regression test (it::security::* or the relevant edge test).
3. Request a CVE through the advisory when the impact warrants it.
4. Release a patch with signed artefacts; publish the advisory and release notes that tell deployers what to run (pmail upgrade) and whether any key or secret rotation is needed.

16. Pre-release checklist

Before v1.0 (PRD release criterion 5) and before every minor release:

• This threat model reviewed against the code; every finding rated high fixed.
• An external penetration test completed before v1.0, findings rated high fixed and retested.
• it::security::cross_tenant_matrix and it::security::route_table_complete green (NFR-SEC-1 = 0).
• Every fuzz target clean for 24 cumulative hours on the release commit.
• cargo deny check, cargo audit and CodeQL clean (no open high-severity finding).
• SBOM, signed SHA256SUMS and attestations produced; a fresh-account pmail deploy rehearsal verified them (PRD release criterion 6).
• Secret rotation procedures in section 6.2 rehearsed on staging.
• it::logs::i5_no_content_in_logs green; the generated wrangler.toml has invocation_logs = false and traces disabled for production.
• Email preview disabled on every sending domain (Privacy).
• security.txt served on staging; SECURITY.md current.
• Signing-key rotation (thread, link and cursor) rehearsed on staging; old tokens verify until verify_until, and stop at once with revoke_previous=true.
• Identity-key rotation and revocation rehearsed on staging: a revoked key leaves the JWKS, and pausing an identity withdraws its JWKS. PM_WEB_BOT_AUTH is on only where spike S13 passed.
• With SES configured: both SNS topics have SignatureVersion=2, the inbound bucket blocks public access, and the IAM policy matches Domains on any DNS host §4.2.
• Release bundle checked for /__test/ and the itest-hooks feature.