CoreMail is the authenticated mail persistence and delivery-orchestration service for serve.zone workloads. Workloads use @serve.zone/platformclient; CoreMail talks directly to the platform mail gateway implemented by dcrouter. Coreflow provisions and reconciles bindings but does not proxy message traffic.

Installation

pnpm add @serve.zone/coremail

The package exports the service lifecycle and its strict configuration reader:

import { CoreMail, readCoreMailConfig } from '@serve.zone/coremail';

const coreMail = new CoreMail(readCoreMailConfig());
await coreMail.start();

process.once('SIGTERM', () => {
  void coreMail.stop();
});

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Architecture

workload
  └─ @serve.zone/platformclient
       └─ authenticated TypedSocket + grant-authorized HTTPS transfers
             └─ CoreMail
                  ├─ SmartData: bindings, grants, submissions, delivery state
                  ├─ SmartBucket: message parts and immutable MIME objects
                  └─ authenticated TypedSocket ── dcrouter mail gateway

dcrouter ── grant-authorized HTTPS transfers ── CoreMail transfer origin

Cloudly desired state ── Coreflow reconciliation ── CoreMail

CoreMail enforces these boundaries:

Workload, tenant, binding, credential version, binding revision, and desired state epoch are server-owned session authority.
Active and draining bindings derive their exact permitted operation set from the shared contract; disabled bindings cannot authenticate.
Every reconnect requires a new Argon2id-authenticated handshake.
TypedSocket tags are routing metadata, never authentication.
Message bytes never travel as JSON, base64 RPC payloads, or VirtualStreams. One-time grants authorize bounded HTTP PUT or GET transfers.
Only grant-token SHA-256 digests are persisted. Plaintext bearer and credential material is never stored or logged.
SmartData owns all structured persistence, indexes, cursor pagination, fixed-window quotas, pending-inbound gauges, compare-and-set transitions, and worker leases.
SmartBucket owns all message parts and immutable serialized MIME objects, with exact length and SHA-256 reconciliation.
The service has no filesystem persistence path and no raw MongoDB access.

Runtime surfaces

One strict hostname surface is exposed:

GET /live reports process liveness.
GET /ready reports database, exact object-storage, desired-state, and authenticated gateway readiness.
GET|PUT /transfers/:grantId consumes one-time transfer capabilities.
GET /socket upgrades to the authenticated TypedSocket RPC transport.

HTTP TypedRequest and built-in routes are disabled. WebSocket messages are limited to 64 KiB, unauthenticated connections have five seconds to complete their first authentication request, and HTTP connection/header/request deadlines are enforced by SmartServe.

Configuration

Coreflow and the deployment secret foundation provide runtime configuration. Malformed startup configuration terminates startup. Missing desired-state secret references keep the affected gateway or cursor operation unavailable.

Variable	Purpose
`COREMAIL_PORT`	Listener port; defaults to `3000`
`COREMAIL_HOSTNAMES`	Comma-separated canonical strict-surface hostnames; defaults to `coremail.serve.zone`
`COREMAIL_SERVICE_ID`	CoreMail service identity
`COREMAIL_TASK_ID`	Current immutable workload task identity
`COREMAIL_ROLLOUT_ID`	Current rollout identity
`COREMAIL_ROLLOUT_GENERATION`	Current rollout generation
`COREMAIL_IMAGE_DIGEST`	Current immutable `sha256:` image digest
`COREMAIL_MONGODB_URL`	MongoDB descriptor URL consumed only by SmartData
`COREMAIL_MONGODB_NAME`	SmartData database name
`COREMAIL_MONGODB_MAX_POOL_SIZE`	Bounded SmartData connection pool; defaults to `50`
`COREMAIL_STORAGE_DESCRIPTOR`	SmartBucket descriptor JSON
`COREMAIL_BUCKET_NAME`	SmartBucket bucket name
`COREMAIL_CONTROL_BOOTSTRAP`	Verifier-only Coreflow bootstrap contract JSON
`${gateway.credentialSecretKey}`	Runtime-only dcrouter peer credential referenced by desired state
`${cursorKeys[].secretKey}`	Runtime-only HMAC keys referenced by current/retiring desired-state cursor keys

COREMAIL_CONTROL_BOOTSTRAP contains verifier material only. The matching plaintext control credential is delivered only to Coreflow. Desired state contains key references for gateway and rotating cursor credentials, never their plaintext values. gateway.endpointUrl is the dcrouter TypedSocket endpoint. gateway.coreMailTransferOrigin is CoreMail's canonical HTTPS origin; dcrouter must return that exact origin during authentication before it can use CoreMail-issued path-only transfer grants.

Persistence and delivery behavior

Outbound submission preparation is idempotent per authenticated binding. The first durable insert consumes one atomic fixed-UTC minute and day quota unit; exact replays consume none. Every part has a unique immutable object key and exact declared integrity. Finalization reads verified parts, produces deterministic MIME with no Bcc header, publishes that MIME exactly once, and queues a lease-fenced worker. The downstream transport identity is the CoreMail submission ID and remains stable across ambiguous responses and retries.

Inbound SMTP recipient resolution returns short-lived opaque handles. The gateway uploads one immutable MIME object, after which CoreMail resumes a SmartData saga that consumes handles and creates one delivery per binding. Pending, fetching, and fetched deliveries consume the binding's pending-inbound quota until the first successful acknowledgement. Workloads list deliveries through a bounded cursor, fetch MIME through a one-time grant, and may acknowledge only after the exact fetch completes. Cursor signatures rotate through current and bounded retiring desired-state keys without exposing runtime secret material.

Desired-state activation uses immutable snapshots and a strictly increasing configEpoch compare-and-set pointer. Replayed or stale configurations cannot replace newer authority.

Terminal outbound submissions and acknowledged inbound deliveries retain their records and owned objects for 30 days. Abandoned outbound preparations and handoff/idempotency receipts also expire after 30 days. Expired transfer grants and recipient handles retain their records for another 24 hours. Pending, fetching, and fetched inbound deliveries are never age-purged; their MIME stays stored until acknowledgement and the acknowledged-delivery retention period have elapsed.

Development

pnpm install
pnpm run build
pnpm test
tsbuild check 'test/**/*'

The production image is built natively for linux/amd64 and linux/arm64:

pnpm run build:docker
pnpm run release:docker

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the license.md file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

readme.md

@serve.zone/coremail