Console and workspaces

Binding design for the console at /console, and for the workspaces, members, roles, invitations, sign-in and sessions behind it. It implements FR-CON-1 to FR-CON-7 and NFR-CON-1, build plan milestone M21, and the edge-case rows W8–W10 and W15–W18 in the edge-case register; and the console parts of agent signing keys (FR-IDN-6, M25) and of notifications (FR-CON-14, FR-CON-15, M26; rows O17–O19). The plan and usage page and everything about money is in Plans, metering and billing. Self-serve sign-up, Google and GitHub sign-in, two-step verification, the landing rules and the Overview (FR-CON-8 to FR-CON-13) are in Cloud sign-up, sign-in and first run, which extends this design.

What the console is

The console is for the people who run the agents. Agents keep using the REST API and MCP. The console holds the views a person needs to check on them, and the actions that should need a person: keys, domains, members, quarantine release and billing (PRD §4). It is not a webmail client: it has no compose or reply form.

• Same Worker. fetch routes /console and /console/* to console::router. With PM_CONSOLE=off those routes are not registered and answer 404 with the standard envelope (FR-CON-7), except two pairs that mail links to: the invitation-accept pair (Invitations) and the unsubscribe pair, GET and POST /console/notifications/unsubscribe (Unsubscribe links), so the List-Unsubscribe header of every notification works. The members API, invitation emails and notifications keep working.

• Its own host, if configured. The console is served on PM_CONSOLE_HOST, which defaults to PM_API_HOST. When the two differ, console paths answer only on the console host and API paths (REST /v1/* with signed links /v1/links/*, MCP /mcp, /openapi.json, /health, /.well-known/*, /hooks/* and /billing/stripe/webhook) only on the API host; anything else gets 404, and no cookie is set or read on the API host (Cloud sign-up §2).

• Rendered on the server in Rust with maud templates (layout.rs, pages/*.rs). Pages are HTML and one stylesheet, /console/assets/console.css. There is no JavaScript, no web font, and no request to another origin (FR-CON-1). maud is pinned at =0.27.0 in Rust workspace.

• Forms only. Every state change is a POST from a <form> with a CSRF token (CSRF). A GET never changes state. Lists paginate with links that carry the API’s cursor.

• Same services as the API. A console handler calls the same internal service functions as the REST handler for that action, with a session principal instead of an API key:

  pub enum Principal {
      Key(ResolvedKey),                                     // REST and MCP
      Session { user_id: String, tenant_id: String, role: Role, permissions: PermissionSet },
  }

  The permissions come from the member’s role (Roles). For every level check a session acts as a tenant-level principal of its workspace (level = tenant, tenant_id the session’s): it may do what a tenant key holding the same permissions may do (tenant search, resume of an abuse pause, tenant-scope erasure, nameservers when policy allows it), and never what needs a platform key. Validation, error codes, idempotency, metering and audit are therefore identical to the API’s.

• Budget. Server render time p95 ≤ 300 ms (NFR-CON-1). A page makes at most one D1 query for the session, then the same calls the API would make.

Workspaces

A workspace is a tenant (FR-CON-2). Everything in it (identities, domains, keys, webhooks, plan) belongs to that tenant, and its scope always comes from the session, never from a form field (W18).

• A workspace has exactly one owner and any number of members up to its seat limit. The unique partial index members_one_owner (ON members(tenant_id) WHERE role = 'owner') makes a second owner impossible at the database level.
• A person (users row) can belong to several workspaces. The session’s tenant_id is the active one; /console/workspaces lists the others and switches with a POST.
• Workspaces are created by POST /v1/tenants with owner (a platform key), which creates the users row if needed, adds the owner and emails a sign-in link. A self-hosted deployment creates its first owner on the default tenant with pmail setup --owner-email (FR-CON-7). Where PM_SIGNUP is waitlist or open (Pylota Mail Cloud), people also create their own workspace at /console/workspaces/new (Cloud sign-up §6).
• Test tenants are workspaces too. Their mail goes to the simulator as usual; the console marks them with a “Test” badge.
• There is no cross-workspace administration view in v1.0. Platform operators use platform keys and the CLI.

Roles

Four roles, with these permissions in the console. The second table lists the API permissions that each role’s session principal holds, so the same checks run as for an API key.

Rules:

• One owner. The owner cannot leave, be removed, or have their role changed; each attempt returns 409 owner_required (W10). Ownership moves only by a transfer to an existing admin (Members).
• Admins and the owner. An admin can manage admins, members and viewers, but cannot change the owner or make anyone owner.
• Keys from the console are tenant-level or identity-level, never platform-level, and can never hold a permission the session lacks (FR-KEY-1). Owners and admins hold identities:sign, so they can create API keys that sign as an identity; members and viewers cannot. The level rules of Security §4.6 apply as in the API: an identity-level key never carries a tenant-only permission (members:read, members:manage, suppressions:manage, audit:read, usage:read), so the key form does not offer them for that level.
• Tenant policy is changed with a platform key, as in the API (PATCH /v1/tenants/{id} needs tenants:manage). The settings page shows the effective policy read-only.
• Workspace settings (name, time zone, require_two_factor) are console-only owner rights, like billing: the settings form posts to a console handler that checks role = owner and updates exactly those three columns of tenants, with an audit row. It never calls PATCH /v1/tenants and never touches the platform-only fields (policy, status, mode, slug, address_suffix, billing).
• Members list. Every role can see members and pending invitations, through GET /v1/tenants/{tenant_id}/members, which needs members:read (included in members:manage).
• Quarantine release is possible for a signed-in person with the role above. On Pylota Mail Cloud no API key can release; a self-hosted deployment can also allow keys with quarantine:review (FR-CON-6).
• Every handler checks the role, through the console’s route table, which registers each route with its required permission exactly like the API’s deny-by-default table (Security). A viewer’s POST to a write route gets 403, and a resource ID from another workspace gets the same 404 as a missing one (W18).

Sign-in

Sign-in is passwordless (FR-CON-3). One request sends one email with both a magic link and a six-digit code; either signs the person in, once.

Two more ways are designed in Cloud sign-up:

• Continue with Google or GitHub (FR-CON-9), on when the deployment has that provider’s client ID and secret. Only a verified email is accepted, and it links to an existing person with the same address (Cloud sign-up §4).
• Two-step verification with an authenticator app (FR-CON-10), optional per person and required by a workspace that sets require_two_factor. It is asked for after any first factor, before the session is created (Cloud sign-up §5).

Every method ends in the same session creation (Sessions), and the landing page is chosen by Cloud sign-up §7.

Requesting a link or code

POST /console/sign-in with email:

1. Normalise the address (lower case, IDNA A-label domain) and validate it.
2. If login_tokens already has 3 rows for this address created in the last 10 minutes, answer the “too many requests, wait 10 minutes” page. The page is the same whether the address is known or not.
3. Insert a login_tokens row: a 32-byte random link token and a six-digit code from the platform RNG (uniform, by rejection sampling), stored only as token_hash and code_hash, keyed hashes under the current link signing key, whose kid goes in key_kid (Keyed hashes), with expires_at = now + 10 minutes. The row is written for every address, known or not, so the limits behave the same.
4. Answer 200 with the “check your email” page, which holds the code form.
5. After the response (wait_until), send the email only if the address belongs to an active user with at least one membership, or has a pending invitation. Otherwise send nothing.

The email goes through the normal outbound pipeline from the system identity (Identities and domains › The system identity), whose address is PM_SYSTEM_FROM (default Pylota Mail <no-reply@{PM_PLATFORM_DOMAIN}>) and whose tenant is the default tenant (billing disabled or exempt, so it is never metered), with Idempotency-Key: signin:{login_token_id}; tests use the simulator (build plan M21). It contains the link https://{PM_CONSOLE_HOST}/console/sign-in/link?t=<token>, the code, and the request time. It never says whether the address has an account.

Doing the lookup and the send after the response keeps the response identical in content and timing for registered and unregistered addresses (W15).

Using the link

GET /console/sign-in/link?t=… changes nothing. It shows a page with one Sign in button, which POSTs the token. Mail security scanners often open links in email; because the GET does not consume the token, a scanner cannot burn it.

The POST hashes the token and looks for a row that is unexpired, unused and has fewer than 10 attempts. On success it sets used_at, creates the users row if the address only had a pending invitation, sets last_login_at, asks for two-step verification if the person has it, creates a session and answers 303 to the page chosen by Cloud sign-up §7 (normally /console).

Using the code

POST /console/sign-in/code with email and code computes HMAC(link key {key_kid}, email || code) for each unexpired, unused token of the address (at most three) and compares it in constant time with that row’s code_hash. A failure increments attempts on each of them; a token reaching 10 is burned. Success continues as for the link.

Each token allows 10 attempts. On top of the per-address limits, the Workers rate-limiting binding RL_SIGNIN (Configuration › Bindings) allows 10 requests per 60 seconds per client IP, keyed by CF-Connecting-IP, on POST /console/sign-in, /console/sign-in/link, /console/sign-in/code, /console/sign-up and /console/waitlist (Cloud sign-up §10).

Keyed hashes

Link tokens, codes, invitation tokens, session cookies and OAuth state values (with their __Host-pm_oauth cookie values) are never stored. Each table keeps HMAC-SHA256(link key {kid}, value) and the key_kid it used, where the link key is the Worker-generated signing_keys key of purpose link (Configuration › Thread and link keys). Tokens and cookie values start with that one-character kid, so the Worker knows which key to hash with. For OAuth, oauth_states.state_hash and cookie_hash are hashed this way, with oauth_states.key_kid (Cloud sign-up §4).

After POST /v1/platform/keys/link/rotate, the old kid keeps verifying for 7 days. Codes and sign-in links live 10 minutes, OAuth flows 10 minutes and invitations 7 days, so they are unaffected. A session whose key_kid is not the current one is re-hashed under the current key on its next request (new id_hash and key_kid in one UPDATE), so active sessions survive a rotation; a session idle for the whole 7 days ends, as its rolling lifetime would. With ?revoke_previous=true the old kid is deleted at once: every sign-in token, invitation, OAuth flow and session hashed under it stops working, and people sign in again (Security › Rotation procedures).

login_tokens rows hold a clear address, so the daily maintenance deletes them 24 hours after they expire.

Sessions

The REST API and /mcp never read this cookie; they authenticate API keys only. The cookie is set by PM_CONSOLE_HOST; when that differs from PM_API_HOST, no cookie is set or read on the API host.

Every console request loads the session, the user and the member row for the active workspace in one D1 query:

SELECT s.user_id, s.tenant_id, s.csrf_secret, s.authenticated_at, s.last_seen_at, u.email, m.role
FROM sessions s
JOIN users u ON u.id = s.user_id AND u.status = 'active'
LEFT JOIN members m ON m.tenant_id = s.tenant_id AND m.user_id = s.user_id
WHERE s.id_hash = ?1 AND s.revoked_at IS NULL AND s.expires_at > ?2;

No row: redirect to /console/sign-in. A session whose active workspace has no member row (the person was removed) is sent to the workspace picker, so a removed member can never act in that workspace, even in a request that was already in flight.

Sign-out sets revoked_at and clears the cookie. Sign out everywhere (settings) revokes every session of the user. Revoked and expired rows are deleted 30 days later.

Re-authentication

Sensitive actions require a sign-in within the last 10 minutes and write an audit row (FR-CON-5): creating keys, creating, rotating or revoking an identity’s signing keys, inviting or removing members, changing roles, transferring ownership, adding or removing domains, releasing quarantine, erasure and legal holds, and billing (Checkout and the Customer Portal). Confirming your address after a notification bounce is audited but needs no recent sign-in, because the re-authentication code would go to the suppressed address (Notification settings).

If authenticated_at is older, the POST answers 303 to /console/reauth?next=<path>. That page sends a code to the signed-in address (a new login_tokens row, counted in the same limits), and also asks for a two-step verification code when the person is enrolled. A correct code creates a new session (new cookie, authenticated_at = now) and revokes the old one, then answers 303 to next, which must be a path under /console/. The person submits the action again; the console never replays a form on its own.

CSRF

Three layers, all required (W16):

1. Token. Every form has a hidden _csrf field: base64url(HMAC-SHA256(csrf_secret, "console-form")). A POST without it, or with a different value (constant-time comparison), gets 403.
2. Origin. Every POST must carry an Origin header equal to https://{PM_CONSOLE_HOST} (which is https://{PM_API_HOST} by default). A missing header, null, or any other value gets 403.
3. Cookie. SameSite=Lax, so cross-site POSTs carry no session at all.

The forms used before a session exists (sign-in, code, link, invitation acceptance, sign-up, waitlist) are checked by Origin alone; they cannot act as a signed-in person. The OAuth callback is a GET from the provider and is bound to the browser by its state and __Host-pm_oauth cookie instead (Cloud sign-up §4).

The unsubscribe pair (GET and POST /console/notifications/unsubscribe) is exempt from all three layers: it needs no session, and its POST is checked by neither the CSRF token nor Origin, because a mail provider sends the RFC 8058 one-click POST with neither (W16). The token in the URL is its only authority, and it can only turn one notification kind off for one person in one workspace (Unsubscribe links).

Console pages are served with Referrer-Policy: same-origin, not the API’s no-referrer. The Fetch Standard sets the Origin header of a non-CORS POST to null when the page’s referrer policy is no-referrer, which would make every legitimate form submission fail the check above.

Other console response headers: Content-Security-Policy: default-src 'none'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; form-action 'self'; frame-ancestors 'none'; base-uri 'none', Cache-Control: no-store, X-Content-Type-Options: nosniff and Strict-Transport-Security: max-age=31536000. There is no script source at all. 'unsafe-inline' for styles is there for sanitised mail, which uses inline styles and inherits the page’s policy inside its srcdoc frame.

Showing untrusted mail

Mail content is untrusted (Security). The console shows it so that it cannot act (W17):

• The default view is text: extracted_text, or the full text, HTML-escaped.
• The HTML view puts the sanitised HTML (sanitised at ingest) in <iframe sandbox srcdoc="…">. The sandbox attribute has no tokens, so the frame runs no scripts, has no same-origin access, submits no forms, opens no pop-ups and cannot navigate the page.
• Remote images are not loaded: the policy allows images only from the console itself and data:. cid: images are rewritten to the attachment URL. A Load remote images link re-renders that one message with img-src https: after a warning that the sender may learn the mail was opened.
• Quarantined messages show the text view and the quarantine reason only. Risky attachments are never offered for preview.
• Display names, subjects and filenames are always escaped; links in text view are not made clickable.

Invitations

Members are invited by email (FR-CON-4). The owner and admins can invite, from the console or with POST /v1/tenants/{id}/invitations (members:manage).

1. Validate the address and the role (admin, member or viewer). An address that is already a member is refused with 400 invalid_request.
2. If a pending invitation for the address exists (invitations_pending is unique per workspace and address), it is re-sent instead: new token, expires_at restarted, no new seat.
3. Take a seats hold in TenantQuota (ref = the new inv_ ID). With no seat left the request fails with 402 billing_limit and details.feature: "seats", before anything is written (W8, Billing).
4. Insert the invitation (token_hash and key_kid as in Keyed hashes, expires_at = now + 7 days) with its audit row and member.invited event in one D1 batch, then settle the hold.
5. Email the link https://{PM_CONSOLE_HOST}/console/invitations/accept?t=<token> from the system identity, as for sign-in. The email says who invited the person: the inviter’s name from invitations.invited_by (the signed-in user; NULL when an API key created the invitation, and then the workspace name alone). This works with PM_CONSOLE=off too: PM_CONSOLE_HOST and PM_SYSTEM_FROM are top-level settings, and with the console off the router still registers the two invitation routes (GET and POST /console/invitations/accept). Accepting there creates the user and the membership and shows “You are now a member of {workspace}”; no session is created, because the deployment has no console to sign in to.

A pending invitation counts as a seat until it is accepted, revoked or expires.

Accepting. The GET shows the workspace name and the role with one Accept button; the POST consumes the token. The link was sent to the invited address, so it proves control of it: acceptance creates the users row if needed, inserts the members row with the invited role, marks the invitation accepted, and signs the person in with the new workspace active. The seat taken by the invitation becomes the member’s seat; TenantQuota does not change. Event member.joined.

Revoking (DELETE /v1/tenants/{id}/invitations/{inv} or the console) sets revoked and releases the seat (Adjust −1). Expiry: the hourly roll-up sets expired on pending invitations past expires_at and releases their seats; acceptance also checks expires_at, so a late click never works.

Members

Changing a role (owner or admin, sensitive) updates members.role and emits member.role_changed. It takes effect on the person’s next request, because the role is read on every request.

Removing a member (owner or admin, sensitive; DELETE /v1/tenants/{id}/members/{user_id}) and leaving run one D1 batch: delete the members row, delete the person’s notification_prefs rows for this workspace, revoke every session of that user whose active workspace is this one, write the audit row and the member.removed event. Then the seat is released with Adjust −1; if that call is lost, the hourly reconciliation corrects the count. After the batch the handler calls NotifierRequest::MemberRemoved { user_id } on the workspace’s Notifier, which drops the person’s pending notifications in this workspace, so nothing more is sent to them about it (O19, Notifications §2). The person’s next request redirects to sign-in (W9). The owner cannot be removed and cannot leave (409 owner_required, W10).

Transferring ownership (owner only, sensitive) to an existing admin. One D1 batch, in this order, because the unique index on the owner is checked statement by statement:

-- ?1 tenant, ?2 current owner, ?3 target admin
UPDATE members SET role = 'admin'
WHERE tenant_id = ?1 AND user_id = ?2 AND role = 'owner'
  AND EXISTS (SELECT 1 FROM members WHERE tenant_id = ?1 AND user_id = ?3 AND role = 'admin');
UPDATE members SET role = 'owner'
WHERE tenant_id = ?1 AND user_id = ?3 AND role = 'admin'
  AND NOT EXISTS (SELECT 1 FROM members WHERE tenant_id = ?1 AND role = 'owner');

Both statements change one row, or neither does (the target is not an admin): then the request returns 400 invalid_request (“the new owner must be an admin of this workspace”) and the workspace still has its owner. The batch also writes the audit row member.ownership_transfer and two member.role_changed events. Stripe’s customer email does not change; the new owner can update it in the Customer Portal. After the batch commits, the handler sends the account email (Account emails).

Identity signing keys

The identity page /console/inboxes/{idn} has a Signing keys section for the identity’s agent signing keys (Agent signing keys). It calls the same service functions as the API’s identity-key routes:

• Each change needs a recent sign-in (Re-authentication), writes the audit row identity_key.create, identity_key.rotate or identity_key.revoke (the actions the API writes) and emits the matching identity.key_* event. A create that finds an active key, or a revoke of a key that is already retired, changes nothing and writes no audit row or event.
• Key management stays available while the identity is paused, so a suspected leak can be handled before it resumes; the page says that a paused identity’s JWKS is withdrawn and that it cannot sign.
• The page shows public data only. No private key is ever displayed, and the console has no form that mints an assertion or a signed request: agents sign through the API and MCP.

Notifications

People get email about their workspace: usage alerts, new mail in inboxes they follow, the daily list of things that need a person, and account emails (Notifications). The console owns the preferences, the unsubscribe links and the account emails its own handlers trigger.

Notification settings

/console/settings/notifications sets the signed-in person’s own preferences for the active workspace, one notification_prefs row per kind (Notifications §2). Every role can open it. Nobody can change another person’s preferences, and there is no API for them: API keys are not people.

• Saving is a POST with the CSRF token; it is not a sensitive action. It upserts the row for (user_id, tenant_id, kind) with the user and workspace taken from the session, never from the form (W18). A mode the kind does not accept, or an inbox ID outside the workspace, is refused like any invalid or foreign value; the system identity is never offered. A kind with no row follows the default of the person’s current role.
• Bounce banner. A hard bounce or complaint on a notification sets paused_reason on every preference of the person in every workspace (O17). Every console page then shows a banner, and this page explains it with a Confirm my address button. Confirming needs the session but not a recent sign-in: re-authentication codes, like every message from the system identity, are not delivered to the suppressed address. One D1 batch clears paused_reason on all of the person’s rows, removes the system identity’s suppression of their address (the default tenant’s suppressions row for it) and writes the audit row user.notifications_resume.
• Cap notice. When the person’s daily cap (50) or the workspace’s (200) has been reached, the page says so: further notifications that day go into the next daily digest (O24).
• When notifications are off. With PM_NOTIFICATIONS=off, or while the workspace is suspended, the page says that only account emails are sent (O26). With PM_BILLING=off, it says that usage covers only features with an operator quota in tenant policy (O23).

Unsubscribe links

Every usage, new_mail and needs_person email carries List-Unsubscribe: <https://{PM_CONSOLE_HOST}/console/notifications/unsubscribe?t={token}> and List-Unsubscribe-Post: List-Unsubscribe=One-Click (RFC 8058). The token (a MAC under the current link key with its kid, binding the person, the workspace and the kind, valid 90 days) is defined in Notifications §5.

• No session is needed and none is created. Both routes are exempt from the CSRF token and Origin check (CSRF), and both are served even with PM_CONSOLE=off.
• An expired, altered or foreign token (another person’s, another workspace’s, or one whose link key has left its 7-day verify window after a rotation) changes nothing and gets the same page, linking to /console/settings/notifications, whichever check failed (O18).
• It is not a sensitive action and writes no audit row: it only turns a notification off, as the person asked. account emails have no unsubscribe header.

Account emails

account emails cannot be turned off (Notifications §1). The console handlers that perform one of these actions call NotifierRequest::Account { user_id, event } on the Notifier of the person’s active workspace after their D1 batch commits:

The fourth account event, a failed payment, belongs to Billing and goes to the owner. account emails are sent with PM_NOTIFICATIONS=off, to a suspended workspace, past the daily caps and while a person’s other preferences are paused.

Screens

With PM_BILLING=off, /console/plan shows usage only, with no plans or buttons.

Tables

The schema is in Data model. How this design uses each table:

Tokens, codes, cookie values and OAuth state values in these tables are always keyed hashes under a link key, with its kid, never the value itself. Values the Worker must use again (TOTP secrets, recovery-code hashes, PKCE verifiers) are sealed under PM_MASTER_KEY instead (Security › Encryption envelope).

Audit and events

Every sensitive action writes an audit_log row in the same D1 batch as the change. For console actions actor_key_id is NULL, actor_user_id holds the person (usr_…), and details_json holds "via": "console".

The other sensitive actions use the same audit actions as the API (for example key.create, quarantine.release), so the log reads the same whichever way the action was taken. Billing actions are listed in Billing.

member.* events have no owner Durable Object. They are written to event_index as platform events with the workspace’s tenant_id and delivered like webhook.disabled (Webhooks › Platform events).

Open points

1. RL_SIGNIN. Closed: 10 requests per 60 seconds per client IP, keyed by CF-Connecting-IP (Sign-in, Cloud sign-up §10).
2. System mail sender. Closed: PM_SYSTEM_FROM is the address of the system identity that sends sign-in, invitation and notification mail (Identities and domains › The system identity) (Cloud sign-up §10, §12).
3. Actor of console actions. Closed: audit_log.actor_user_id records the person (Data model), and message.released carries released_by_user_id for a console release (Webhook events).
4. Key-based quarantine release (FR-CON-6). Closed: PM_QUARANTINE_KEY_RELEASE (Configuration) is on by default for self-hosting, and Pylota Mail Cloud sets it to off, so only a signed-in person can release there.
5. Erasure of console data. Closed: tenant erasure deletes the workspace’s members, invitations and sessions, and deletes every person it leaves with no workspace; deleting a person removes their oauth_identities and any waitlist row (Cloud sign-up §11, Privacy › Tenant scope, Privacy › People).
6. Sign-up on Pylota Mail Cloud. Closed: designed in Cloud sign-up, sign-in and first run.

Tests