Agent signing keys and signed requests

How an agent proves who it is to people and systems outside email: agent assertions (signed JWTs that any service can verify against a published key set) and signed HTTP requests (Web Bot Auth), so a website can tell which agent made a request and that it came through this deployment.

1. What it is for, and what it is not

Not in scope: signing email bodies (DKIM already authenticates mail), client TLS certificates, exporting a private key, or importing a key someone else generated. Private keys never leave the Worker.

2. Keys

• Generation. 32 bytes from the platform CSPRNG become the Ed25519 seed (SigningKey::from_bytes). The seed is sealed at once with the pm1 envelope (Security). It is zeroised in memory after each use (zeroize). A key created lazily by a signing request, or by POST …/keys, emits identity.key_created; the new key of a rotation emits identity.key_rotated instead.
• States. active (signs and is published) → retiring (published, does not sign, until verify_until) → retired (not published; the row is kept until identity deletion so its thumbprint is never reused). A rotation makes a new key active at once and the previous one retiring with verify_until = now + PM_IDENTITY_KEY_OVERLAP_DAYS (default 7). A revocation (POST …/keys/{kid}/revoke) moves any key straight to retired, for a suspected compromise (O3).
• Master-key rotation. pmail secrets rotate-master re-seals identity_keys.private_enc and the web_bot_auth seeds like every other sealed value. Signatures and thumbprints do not change (O8).
• Paused, suspended or deleted identities cannot sign. The order matches sends (Outbound › Policy pipeline): an identity of a suspended tenant gets 403 tenant_suspended (checked first), a paused identity gets 409 identity_paused, and a deleting or deleted identity gets 404 identity_not_found, as on every other route. Their JWKS is withdrawn (404) while they are paused or suspended. This is the kill switch: a verifier that refetches the JWKS stops accepting the identity within the cache time (O1, O7). Key management (…/keys, rotate, revoke) stays available while an identity is paused, so a suspected leak can be handled before it resumes.

3. Publication

3.1 Identity JWKS

GET https://{PM_API_HOST}/.well-known/jwks/{identity_id}.json, no authentication:

{ "keys": [
  { "kty": "OKP", "crv": "Ed25519", "x": "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo",
    "kid": "kPrK_qmxVWaYVA9wwBF6Iuo3vVzz7TxHCTwXBygrS4k", "alg": "EdDSA", "use": "sig" } ] }

• It lists active and retiring keys. Cache-Control: public, max-age=300. Content-Type: application/jwk-set+json.
• An unknown, deleted, paused or suspended identity gets the same 404 identity_not_found, so the endpoint reveals nothing beyond what a valid assertion already names.
• Identity IDs are ULIDs and are never derived from addresses, so the endpoint cannot be used to test whether an address exists.

3.2 Web Bot Auth key directory

With PM_WEB_BOT_AUTH=on, GET https://{PM_API_HOST}/.well-known/http-message-signatures-directory returns the deployment keys (active and retiring) as a JWKS, as the directory draft and Cloudflare’s page require:

• Content-Type: application/http-message-signatures-directory+json, Cache-Control: max-age=86400, served over HTTPS only.
• The response is signed once per listed key: Signature-Input with the component ("@authority";req), alg="ed25519", keyid = the key’s thumbprint, a 64-byte random nonce, tag="http-message-signatures-directory", created = now and expires = now + 300, and the matching Signature. This stops anyone from mirroring the directory and registering it as theirs. At most three keys are listed (one active, two retiring), so the headers stay small (O12).
• With PM_WEB_BOT_AUTH=off the path returns 404 key_not_found.

Registering the directory with Cloudflare’s verified-bot programme (dashboard, “Bot Submission Form”, verification method “Request Signature”) is an operator decision documented in Self-hosting. Signatures verify for any Web Bot Auth verifier without it.

4. Agent assertions

4.1 Request

POST /v1/identities/{identity_id}/assertions with permission identities:sign. Each call mints a new token, so an Idempotency-Key header is ignored and never recorded: a replay record would store the token, which is never stored (§4.2).

{ "audience": "https://portal.supplier.example",
  "expires_in": 300,
  "nonce": "b3f1c2…",
  "ext": { "booking_ref": "BK-2291" } }

4.2 Token

Header {"alg":"EdDSA","typ":"agent-assertion+jwt","kid":"<thumbprint>"}. Claims:

Response 201:

{ "assertion": "eyJhbGciOiJFZERTQSIs…", "kid": "kPrK_qmx…", "expires_at": "2026-10-09T12:05:00Z",
  "jwks_uri": "https://api.pylotamail.com/.well-known/jwks/idn_01J9….json" }

The token is never stored or logged; only a count is kept (usage_daily.metric = 'assertions').

4.3 How a verifier checks it

This is in the Agents guide for integrators, and in the Rust SDK as verify_assertion (Rust workspace §11) and the CLI as pmail assertions verify:

1. Decode the header. alg must be EdDSA and typ must be agent-assertion+jwt. Reject anything else (no none, no algorithm switching).
2. iss must be an issuer you trust, for example https://api.pylotamail.com. Never fetch keys from a URL the token supplies.
3. Fetch {iss}/.well-known/jwks/{sub}.json (cache for at most 5 minutes) and pick the key whose kid matches. None found → reject.
4. Verify the Ed25519 signature over the JWS signing input.
5. aud must equal your own audience. Check nbf and exp, allowing 60 seconds of clock skew.
6. Keep jti until exp and reject a repeat.

5. Signed HTTP requests (Web Bot Auth)

5.1 Request

POST /v1/identities/{identity_id}/http-signatures with permission identities:sign. The Worker never makes the request itself; it returns headers for the agent’s HTTP client to attach. As for assertions, an Idempotency-Key header is ignored and never recorded.

{ "url": "https://www.brightwell.example/fleet/availability?from=2026-10-12",
  "method": "GET",
  "expires_in": 60,
  "components": ["@authority", "signature-agent", "from"] }

Refused with 422 web_bot_auth_disabled when PM_WEB_BOT_AUTH=off, and with 403 policy_denied when tenant policy web_bot_auth.allowed is false (O9, O13).

5.2 Response

Response 200 (nothing is created or stored):

{ "headers": {
    "Signature-Agent": "\"https://api.pylotamail.com\"",
    "From": "bookings.brightwell@pylotamail.com",
    "Signature-Input": "sig1=(\"@authority\" \"signature-agent\" \"from\");created=1791547200;expires=1791547260;keyid=\"poqkLGiymh_W0uP6PZFw-dvez3QJT5SolqXBCW38r0U\";alg=\"ed25519\";nonce=\"e8N7S2MF…\";tag=\"web-bot-auth\"",
    "Signature": "sig1=:jdq0SqOwHdyHr9+r5jw3iYZH6aNGKijYp/EstF4RQTQdi5N5YYKrD+mCT1HA1nZDsi6nJKuHxUi/5Syp3rLWBA==:" },
  "expires_at": "2026-10-09T12:01:00Z" }

• Signature-Agent is a structured-field string, in double quotes, naming the deployment’s origin. Its directory is at that origin’s well-known path (§3.2).
• From carries the identity’s primary address (RFC 9110 From: the address of whoever is responsible for the request). It is signed, so the site knows which agent made the request and how to reach its operator.
• The signature base is built by core::httpsig::signature_base exactly as RFC 9421 §2.5, and signed with the deployment’s active key. nonce is 64 random bytes, base64.
• The count is kept as usage_daily.metric = 'http_signatures'. Signatures are not logged.

Spike S13 checks the format against https://crawltest.com/cdn-cgi/web-bot-auth, which returns 401 for a correctly formatted message with an unknown key, 200 for a known key that verifies and 400 otherwise (Web Bot Auth, read 2026-10-09). Pass: 401 before registration. Fallback: signed HTTP requests stay off in v1.0 (PM_WEB_BOT_AUTH cannot be turned on); assertions are unaffected.

6. Permissions, limits and plans

• New permission identities:sign. It is granted like any other permission (there are no wildcard permissions): a tenant key holds it when it is in the key’s list, and an identity key holds it only when granted, for its own identity. Platform and partner keys cannot sign as an identity: creating a platform or partner key with identities:sign is refused with 400 invalid_request and details.reason = "permission_not_allowed_for_level". In the console, the owner’s and admins’ session principals hold it, so they can create keys that carry it.
• Console: owners and admins create, rotate and revoke identity keys on the identity page (sensitive actions: re-authentication and an audit row, identity_key.create, identity_key.rotate or identity_key.revoke; the API writes the same audit actions). Everyone in the workspace can see the key IDs and the JWKS link.
• Rate limit binding RL_SIGN: 600 signing calls a minute per identity, for assertions and HTTP signatures together. Over it: 429 rate_limited.
• Signing is included in every plan and is not metered against an allowance.

7. API, MCP and CLI

MCP tools mail_sign_assertion and mail_sign_http_request (both identities:sign) mirror the two POST endpoints. CLI: pmail identity-keys list|create|rotate|revoke, pmail assertions create|verify, and pmail http-sign.

Events: identity.key_created, identity.key_rotated and identity.key_revoked, each with identity_id and kid (identity.key_rotated also carries previous_kid). They are identity events, written after the D1 change through the identity’s mailbox like the other identity.* events. Errors: the new web_bot_auth_disabled (422) and policy_denied (403); key_not_found (404), the existing code for a missing key, also covers an unknown kid and the directory while it is off; plus the existing tenant_suspended (checked first, before identity_paused), identity_not_found, identity_paused, invalid_request, permission_denied, scope_denied and rate_limited.

8. Data model

-- D1: identity_keys (replaces the earlier P1 sketch)
CREATE TABLE identity_keys (
  id           TEXT PRIMARY KEY,                    -- RFC 7638 thumbprint, base64url
  identity_id  TEXT NOT NULL REFERENCES identities(id),
  tenant_id    TEXT NOT NULL,
  alg          TEXT NOT NULL CHECK (alg = 'EdDSA'),
  public_jwk   TEXT NOT NULL,
  private_enc  BLOB NOT NULL,                       -- pm1 envelope of the 32-byte seed
  status       TEXT NOT NULL CHECK (status IN ('active','retiring','retired')),
  created_at   INTEGER NOT NULL,
  verify_until INTEGER,                             -- set when retiring
  retired_at   INTEGER
);
CREATE UNIQUE INDEX identity_keys_one_active ON identity_keys (identity_id) WHERE status = 'active';

-- D1: signing_keys gains a purpose and a public key
--   purpose CHECK (purpose IN ('thread','link','cursor','web_bot_auth'))
--   kid     CHECK ((purpose = 'web_bot_auth' AND length(kid) = 43) OR (purpose <> 'web_bot_auth' AND length(kid) = 1))
--   public_jwk TEXT   -- set for web_bot_auth only

-- D1: thumbprints that must never be published again
CREATE TABLE key_tombstones (
  kid        TEXT PRIMARY KEY,                      -- RFC 7638 thumbprint of a deleted identity key
  deleted_at INTEGER NOT NULL
);

usage_daily gains the metrics assertions and http_signatures. Identity erasure (and tenant erasure, for every identity of the tenant) deletes the identity’s identity_keys rows and records each thumbprint in key_tombstones, a separate table that does for key IDs what address_tombstones does for addresses: key generation refuses a thumbprint found there and draws a new seed, so a deleted key ID is never published again.

9. Configuration

10. Security and privacy

• Private keys are generated, sealed, used and zeroised inside the Worker. No API returns them.
• An assertion discloses the identity’s address, display name and workspace name to its audience, which is the point of it. It never contains the owner’s personal data.
• Web Bot Auth attributes requests to the deployment and, through From, to an identity. An identity whose agent misbehaves on the web is paused like any other abuse case; pausing withdraws its JWKS and stops new signatures at once.
• Replay: assertions carry jti and short expiry; HTTP signatures carry nonce, created and expires. Verifiers keep the replay caches.

11. Tests