AGENTS.md

AGENTS.md — OpenVibe.Mail

Project Overview

OpenVibe.Mail is openvibe.email: masks that protect you, burners that self-destruct, an inbox for every agent, and
person mail (read your mailbox, compose, custom domains, forwarding, read-only IMAP of another provider, opt-in Inbox
AI). M1 is receive-only: Stalwart Community listens on port 25; the service hands out addresses that resolve into
mailboxes, and nothing sends or relays outside OpenVibe unless MAIL_OUTBOUND=on and an outbound provider are both
configured (external sending is M2 and off by default).

• Domain: openvibe.email · Port: 5250 (API; SMTP 25, JMAP/IMAP loopback) · Service id: mail ·
  Env prefix: MAIL
• Runtime: Node 22, Express 4, PostgreSQL 18 through openvibe-sdk/db (PGlite in development/tests), Stalwart
  Community 1.0.3 pinned in [deploy/stalwart/VERSION](deploy/stalwart/VERSION), imapflow/mailparser/nodemailer
  for the optional person-mail paths.
• Read first: [README.md](README.md), [docs/INBOX-AI.md](docs/INBOX-AI.md), [docs/INSTALL.md](docs/INSTALL.md),
  [docs/DNS.md](docs/DNS.md), [docs/INBOX.md](docs/INBOX.md).

Network context: identity, tokens, staff roles, verified emails and the trust check are OpenVibe.Network
(identity.trust.read, identity.emails.read). Account export/deletion is ADR-033 through OpenVibe.Events. Mail AI
(server/ai/inbox.js) is optional. The mail server is Stalwart's own process; this repository ships its declarative
config and a Node API, not a modified Stalwart. Message bodies are read from Stalwart over loopback JMAP and are never
written to logs, events or the database (the one exception is Inbox AI's opt-in summary/editable draft, and the draft
is the only generated body persisted).

Commands

npm ci                         # install (contracts/sdk/shared pinned by tag)
npm start                      # node server/index.js (API; Stalwart runs separately)
npm test                       # unit: PGlite, in-process Network and in-memory mail server
npm run test:pg                # the same through PostgreSQL
npm run test:stalwart          # acceptance: real Stalwart + PostgreSQL (MinIO with STALWART_BLOB_STORE=s3)
npm run init-db                # node deploy/init-db.js (apply migrations before systemd starts the service)
npm run stalwart:fetch         # verify/download the pinned Stalwart (sha256)
npm run stalwart:render        # config.toml → rendered/config.json + rendered/plan.json
npm run stalwart:apply         # reconcile the plan over loopback JMAP
node --check <file.js>         # syntax check (no linter configured)

No build step: the page and assets are served from [public/](public/) (css/inbox.css, css/mail.css, js/inbox.js,
js/compose.js, js/mail.js, js/mail-providers.js).

Architecture at a Glance

• Entry: [server/index.js](server/index.js) — database/migrations, mail server client, events relay, purge,
  agent-mail, Inbox AI, IMAP pull and forwarding jobs, then the listener; each job is due-based and stops on SIGTERM.
• App factory: [server/app.js](server/app.js) — helmet/CSP, /auth, CORS, /api/v1, /internal/, machine
  endpoints, the page/static mount [server/http/pages.js](server/http/pages.js), error handler.
• Config: [server/config.js](server/config.js) — load(env) is pure; production /etc/openvibe/mail.env.
• Domains: [server/domain/](server/domain/) — masks.js, burners.js, agent-inboxes.js, agent-answering.js,
  agent-reply.js, addresses.js, messages.js, mailboxes.js, reading.js (HTML cleaning), sending.js,
  compose.js, custom-domains.js, forwarding.js, person-mail.js, mail-search.js, inbox-ai*.js,
  imap-connections.js, imap-secrets.js, outbound-providers.js, provider-*.js, limits.js,
  network-policy.js.
• Mail server: [server/stalwart/](server/stalwart/) — client.js (loopback JMAP), smtp.js, code.js;
  [server/imap/client.js](server/imap/client.js) for the read-only IMAP pull.
• HTTP: [server/http/](server/http/) — api.js, principal.js, person-routes.js, reading-routes.js,
  agent-mail.js, imap-routes.js, workspace-routes.js, cors.js, discovery.js, pages.js, mail-copy.js.
• Jobs: [server/jobs/](server/jobs/) — purge.js (expiry), agent-mail.js, inbox-ai.js, imap-pull.js,
  forwarding.js, workspace.js.
• Database: [server/db.js](server/db.js) and [migrations/](migrations/): mail_addresses, mail_directory_accounts
  (the SQL directory view Stalwart reads), settings/outbox, rate limits, observed messages, mask expiry, agent
  answering, Inbox AI consent/triage, IMAP mailboxes, outbound providers/domains, person mail, workspace, spam
  scoring, event_outbox (with its rejected partial index).
• Stalwart config: [deploy/stalwart/config.toml](deploy/stalwart/config.toml) is the source of truth;
  render.js produces the data store and plan, apply.js reconciles over JMAP. It creates the SQL directory, the
  base/mask/burner domains (allowRelaying = false), the blob store (fs or S3), spam filter and exactly three
  listeners (SMTP 25, JMAP/management + IMAP on loopback); every default submission/HTTPS/POP3/Sieve listener is
  removed. The directory-created account gets the User role or Stalwart refuses its own mail.
• Deploy: [deploy/systemd/openvibe-mail.service](deploy/systemd/openvibe-mail.service) (API),
  [deploy/systemd/openvibe-stalwart.service](deploy/systemd/openvibe-stalwart.service) and
  [deploy/systemd/openvibe-stalwart.slice](deploy/systemd/openvibe-stalwart.slice) (memory cap),
  [deploy/nginx/openvibe.email.conf](deploy/nginx/openvibe.email.conf) (API/health/ready/auth; /internal/ closed).
  M1 is not deployed from this repository — [docs/INSTALL.md](docs/INSTALL.md) is the operator's handoff.

Ownership and Boundaries

Mail owns masks, burners, agent inboxes and their answering state, the directory view, person-mail addresses,
settings, observed message metadata, rate limits, Inbox AI consent/summaries/drafts, IMAP mailbox settings and the
outbox. It does not own identity/verified emails/trust (Network), mail delivery or blobs (Stalwart), event delivery
(Events), AI (the AI service), or the host/DNS (Host/operator). It never stores a message body as a row; message
content lives in Stalwart and is read on demand for its owner. Another person's mask, burner or inbox answers 404,
never 403.

Addresses, Reading and Sending

• Masks (<site>.<code>@mask.openvibe.email) deliver into the owner's mailbox; disabling one makes it bounce. A
  mask may carry expires_days; the purge job disables it and the directory stops resolving it.
• Burners are receive-only and expire after 10m/1h/1d/7d or the first message; the 10-minute burner needs no
  account and is read with its returned x-mail-burner-token. Every unexpired burner is its own directory
  account, so one burner's mail is never readable in another's. Expired: the mail is deleted, the account removed and
  the address bounces.
• Agent inboxes (<name>.<owner>@openvibe.email) are aliases on the owner's mailbox. Answering is a switch, off
  by default, turned on for one agent; the due poll then publishes mail.agent_inbox.received once per unseen
  non-spam, non-blocked letter. The agent reads with mail.agent.read and replies with mail.agent.reply, always
  from the agent's address to the sender and nobody else, plain text, with In-Reply-To/References.
• Delivered-To: a mask/agent inbox is matched only against the first Delivered-To header Stalwart stamps —
  never a sender-written To/Cc/Delivered-To. A burner's account is read with no recipient filtering at all.
• HTML reading: [server/domain/reading.js](server/domain/reading.js) sanitizes with an allow-list; style is
  limited to layout/colour with no url(), expression() or @import; links only http(s)/mailto with
  rel="noopener noreferrer". Remote images become alt text (blocked_images) until ?images=1 (https only); the
  page renders it in an iframe with no allow-scripts and its own default-src 'none' CSP.
• Person mail: a person can create a named address/alias, compose plain text, attach a custom domain and forward a
  copy to a verified Network email. Sending needs a verified account email, a one-day-old account, a verified sender
  domain and a live trust check. 20 recipients/day rising to 50/100 with age and history; 10 recipients/message; no
  bulk mode. Hard bounces/complaints pause the sender; every message carries a report link and
  X-OpenVibe-Report-Abuse.
• Forwarding rechecks Network ownership at creation and before every copy; only non-junk plain-text messages
  without attachments are copied; an ambiguous provider answer is not retried automatically.
• Outbound is closed by default. MAIL_OUTBOUND=on plus an enabled provider is required; with it off, a reply to
  a non-OpenVibe address answers 409 mail.outbound_closed and stays pending, never lost.
• IMAP pull is TLS only, read-only, app password sealed with MAIL_SECRETS_KEY; it never writes back.
• Limits: 20 masks, 5 live burners/person; account-less 10-minute burners 10/IP/hour and 2,000 live globally
  (503 mail.burner_capacity); counters are in PostgreSQL, so a restart is not a fresh allowance.

API and Scopes

All API routes are /api/v1, take a Network bearer or the same-site session cookie; a cross-origin browser may use a
Bearer from a first-party origin (CORS); a cookie write must come from openvibe.email (Sec-Fetch-Site/Origin).
An app token names the person (on_behalf_of) and holds mail.addresses.write or mail.messages.read; the
Companion-style token holds mail.mask.manage; a typed token is refused. A service acting for a person uses
X-OV-Subject.

Core routes: GET /me/mail, masks (/masks, /:id, /:id/disable), burners (/burners,
/:id/messages, /:id/code), agent inboxes (/agent-inboxes, /:id/messages, /:id/answering),
blocks (/me/mail/blocks), GET|POST /me/mail/messages[...] (reading, read/unread, delete, attachments),
person-mail/addresses/compose/domains/forwarding/IMAP/Inbox AI per [docs/INBOX-AI.md](docs/INBOX-AI.md), and the
internal agent routes. The message list returns { id, from, subject, received_at } and nothing else; /code
returns the code, never the body.

Conventions

• CommonJS, 4-space indent, single quotes, semicolons; no linter/formatter.
• Never log a body, a subject, an address's mail or a code. Metadata-only events: mail.mask.created,
  mail.received (address, sender, message id, time — no subject/body/code), mail.agent_inbox.received (excerpt
  ≤4000 chars, never HTML/attachment, nothing for spam/blocked).
• New schema = a new migrations/NNNN_name.sql (expand-only); never edit one that has run. The directory view is
  read by Stalwart, so a column change is a coordinated deploy.
• Stalwart config is declarative: edit [deploy/stalwart/config.toml](deploy/stalwart/config.toml), then render and
  apply. Never edit the rendered data store by hand or leave a default listener enabled.
• CSP: add origins to helmet in [server/app.js](server/app.js); the message iframe has its own stricter policy.
• Phone first: the one page and the inbox fit 390 px; no Font Awesome; "Calm reduces, only Off removes" (a block or
  disabled mask suppresses, only purge/delete removes).
• Empty states use the shared kit; keep the page's copy to what M1 does today (receive, show a code, never a body
  unless its owner asks).

Key Pitfalls

• One burner = one account. Never pool or merge burners into one mailbox; a forgeable To/Cc/Delivered-To must not
  move mail between burners or agent inboxes. [test/stalwart/integration.test.js](test/stalwart/integration.test.js)
  proves it with a real Stalwart.
• Directory vs expiry: an expired/disabled address must resolve to no directory row and bounce; do not "keep it
  working" for a grace period.
• Bodies: only the owner reads a message; the code extractor must discard the body as soon as it has the code.
  An attachment is allow-listed/application/octet-stream with nosniff.
• Outbound off is the default safety: do not make a route that quietly sends externally because a provider key is
  present. GET /internal/mail/outbound tells callers the truth.
• Inbox AI is opt-in and consent-scoped; the draft is editable and is the only generated body persisted; a reply
  stays a draft until the person sends it (see [docs/INBOX-AI.md](docs/INBOX-AI.md)).
• Custom domains: verify DNS/ownership before accepting; the inbound path and states are in
  [docs/DNS.md](docs/DNS.md). Never show a domain as verified before it is.
• Ports: only 25 inbound is open; 587/465 stay closed. JMAP/IMAP listen on loopback. Do not expose them.
• event_outbox needs its rejected partial index (migration 0007).
• M1 is not deployed from this repo. Do not add a deploy step here; the operator follows INSTALL.md.

Testing

npm test runs unit tests on PGlite with an in-process Network and an in-memory mail server: masks, burners, agent
inboxes/answering, directory, reading/sanitizing/images, person mail, provider adapters/router/webhooks, IMAP,
Inbox AI, purge, API/page, CORS/nginx, Stalwart client, companion masks, workspace and your-address. npm run test:pg
for PostgreSQL. npm run test:stalwart is the real acceptance run (real Stalwart + PostgreSQL) and also runs in CI.
Always node --check changed files.

Documentation

• [README.md](README.md) — person mail, M1.5 reading, M1 pieces, API, events, agent answering, contracts, Stalwart,
  tests, layout, limits, install.
• [docs/INBOX-AI.md](docs/INBOX-AI.md) — consent, rules, journal, undo and receipts.
• [docs/INBOX.md](docs/INBOX.md), [docs/INSTALL.md](docs/INSTALL.md), [docs/DNS.md](docs/DNS.md).
• [deploy/stalwart/config.toml](deploy/stalwart/config.toml), [deploy/stalwart/VERSION](deploy/stalwart/VERSION),
  [SECURITY.md](SECURITY.md), [.env.example](.env.example).