@serve.zone/coremail 1.0.0

package/dist_ts/interfaces.d.ts

@@ -0,0 +1,92 @@
+import type * as plugins from './plugins.js';
+export type TCoreMailSessionKind = 'control' | 'workload';
+export interface ICoreMailReplicaRuntime {
+    taskId: string;
+    serviceId: string;
+    rolloutId: string;
+    rolloutGeneration: number;
+    imageDigest: plugins.serveZoneInterfaces.data.TCoreMailSha256;
+}
+export interface ICoreMailConfig {
+    port: number;
+    hostnames: string[];
+    mongoDescriptor: {
+        mongoDbUrl: string;
+        mongoDbName: string;
+        maxPoolSize: number;
+        maxIdleTimeMS: number;
+        serverSelectionTimeoutMS: number;
+        socketTimeoutMS: number;
+    };
+    storageDescriptor: Record<string, unknown>;
+    bucketName: string;
+    controlBootstrap: plugins.serveZoneInterfaces.data.ICoreMailControlBootstrap;
+    resolveRuntimeSecret: (secretKeyArg: string) => string;
+    replica: ICoreMailReplicaRuntime;
+}
+export interface ICoreMailControlSession {
+    kind: 'control';
+    peerId: string;
+    credentialId: string;
+    credentialVersion: number;
+    authenticatedAt: number;
+}
+export interface ICoreMailWorkloadSession {
+    kind: 'workload';
+    peerId: string;
+    tenantId: string;
+    serviceId: string;
+    bindingId: string;
+    bindingRevision: number;
+    configEpoch: number;
+    credentialId: string;
+    credentialVersion: number;
+    bindingState: 'active' | 'draining';
+    capabilities: plugins.serveZoneInterfaces.data.TCoreMailCapability[];
+    allowedOperations: plugins.serveZoneInterfaces.data.TCoreMailWorkloadOperation[];
+    coreMailTransferOrigin: string;
+    authenticatedAt: number;
+}
+export type TCoreMailSession = ICoreMailControlSession | ICoreMailWorkloadSession;
+export type TTransferAuthorityKind = 'control' | 'gateway' | 'workload';
+export type TTransferGrantPurpose = 'desired-state-upload' | 'outbound-part-upload' | 'outbound-mime-download' | 'inbound-mime-upload' | 'inbound-mime-download';
+export interface ITransferAuthority {
+    kind: TTransferAuthorityKind;
+    tenantId: string;
+    serviceId: string;
+    bindingId: string;
+}
+export interface ISubmissionPartRecord {
+    partId: string;
+    kind: plugins.serveZoneInterfaces.data.TCoreMailPartKind;
+    contentType: string;
+    filename?: string;
+    contentId?: string;
+    sha256: plugins.serveZoneInterfaces.data.TCoreMailSha256;
+    lengthBytes: number;
+    objectKey: string;
+    state: 'missing' | 'uploading' | 'complete' | 'failed';
+    grantId?: string;
+}
+export interface ICoreMailReadiness {
+    live: boolean;
+    database: boolean;
+    objectStorage: boolean;
+    exactUpload: boolean;
+    exactPurge: boolean;
+    controlBootstrap: boolean;
+    gateway: boolean;
+}
+export interface ICoreMailAuthLimiterSnapshot {
+    inFlight: number;
+    tokens: number;
+}
+export interface ICoreMailPeer {
+    id: string;
+    data: Map<string, unknown>;
+    close(code?: number, reason?: string): void;
+    terminate(): void;
+    context: {
+        state: Record<string, unknown>;
+    };
+}

package/dist_ts/interfaces.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW50ZXJmYWNlcy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL2ludGVyZmFjZXMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IiJ9

package/dist_ts/plugins.d.ts

@@ -0,0 +1,11 @@
+export * as typedrequest from '@api.global/typedrequest';
+export * as typedrequestInterfaces from '@api.global/typedrequest-interfaces';
+export * as typedserver from '@api.global/typedserver';
+export * as typedsocket from '@api.global/typedsocket';
+export * as projectinfo from '@push.rocks/projectinfo';
+export * as smartbucket from '@push.rocks/smartbucket';
+export * as smartdata from '@push.rocks/smartdata';
+export * as smartlog from '@push.rocks/smartlog';
+export * as serveZoneInterfaces from '@serve.zone/interfaces';
+export * as argon2 from 'argon2';
+export * as nodeCrypto from 'node:crypto';

package/dist_ts/plugins.js

@@ -0,0 +1,12 @@
+export * as typedrequest from '@api.global/typedrequest';
+export * as typedrequestInterfaces from '@api.global/typedrequest-interfaces';
+export * as typedserver from '@api.global/typedserver';
+export * as typedsocket from '@api.global/typedsocket';
+export * as projectinfo from '@push.rocks/projectinfo';
+export * as smartbucket from '@push.rocks/smartbucket';
+export * as smartdata from '@push.rocks/smartdata';
+export * as smartlog from '@push.rocks/smartlog';
+export * as serveZoneInterfaces from '@serve.zone/interfaces';
+export * as argon2 from 'argon2';
+export * as nodeCrypto from 'node:crypto';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicGx1Z2lucy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL3BsdWdpbnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLFlBQVksTUFBTSwwQkFBMEIsQ0FBQztBQUN6RCxPQUFPLEtBQUssc0JBQXNCLE1BQU0scUNBQXFDLENBQUM7QUFDOUUsT0FBTyxLQUFLLFdBQVcsTUFBTSx5QkFBeUIsQ0FBQztBQUN2RCxPQUFPLEtBQUssV0FBVyxNQUFNLHlCQUF5QixDQUFDO0FBQ3ZELE9BQU8sS0FBSyxXQUFXLE1BQU0seUJBQXlCLENBQUM7QUFDdkQsT0FBTyxLQUFLLFdBQVcsTUFBTSx5QkFBeUIsQ0FBQztBQUN2RCxPQUFPLEtBQUssU0FBUyxNQUFNLHVCQUF1QixDQUFDO0FBQ25ELE9BQU8sS0FBSyxRQUFRLE1BQU0sc0JBQXNCLENBQUM7QUFDakQsT0FBTyxLQUFLLG1CQUFtQixNQUFNLHdCQUF3QixDQUFDO0FBQzlELE9BQU8sS0FBSyxNQUFNLE1BQU0sUUFBUSxDQUFDO0FBQ2pDLE9BQU8sS0FBSyxVQUFVLE1BQU0sYUFBYSxDQUFDIn0=

package/license.md

@@ -0,0 +1,19 @@
+Copyright (c) 2014 Task Venture Capital GmbH (hello@task.vc)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@serve.zone/coremail",
+  "version": "1.0.0",
+  "description": "Authenticated mail persistence and delivery orchestration for serve.zone workloads.",
+  "main": "dist_ts/index.js",
+  "typings": "dist_ts/index.d.ts",
+  "type": "module",
+  "author": "Task Venture Capital GmbH",
+  "license": "MIT",
+  "devDependencies": {
+    "@git.zone/tsbuild": "^4.4.2",
+    "@git.zone/tsdocker": "^3.1.1",
+    "@git.zone/tsrun": "^2.0.6",
+    "@git.zone/tstest": "^3.6.7",
+    "@git.zone/tswatch": "^3.3.5",
+    "@push.rocks/smartmongo": "^7.0.0",
+    "@types/node": "^26.1.1"
+  },
+  "dependencies": {
+    "@api.global/typedrequest": "^3.7.0",
+    "@api.global/typedrequest-interfaces": "^4.0.0",
+    "@api.global/typedserver": "^8.10.0",
+    "@api.global/typedsocket": "^5.1.0",
+    "@push.rocks/projectinfo": "^5.1.0",
+    "@push.rocks/smartbucket": "^4.11.0",
+    "@push.rocks/smartdata": "^10.4.0",
+    "@push.rocks/smartlog": "^3.2.2",
+    "@serve.zone/interfaces": "^22.0.0",
+    "argon2": "^0.45.1"
+  },
+  "files": [
+    "ts/**/*",
+    "dist_ts/**/*",
+    "cli.js",
+    ".smartconfig.json",
+    "readme.md",
+    "changelog.md",
+    "license.md"
+  ],
+  "scripts": {
+    "test": "tstest test/ --verbose --logfile --timeout 60",
+    "start": "node ./cli.js",
+    "startTs": "node ./cli.ts.js",
+    "build": "tsbuild tsfolders",
+    "build:docker": "tsdocker build --verbose",
+    "release:docker": "tsdocker push --verbose"
+  }
+}

package/readme.md

@@ -0,0 +1,199 @@
+# @serve.zone/coremail
+
+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
+
+```bash
+pnpm add @serve.zone/coremail
+```
+
+The package exports the service lifecycle and its strict configuration reader:
+
+```typescript
+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/](https://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/](https://code.foss.global/) account to submit Pull Requests
+directly.
+
+## Architecture
+
+```text
+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
+
+```bash
+pnpm install
+pnpm run build
+pnpm test
+tsbuild check 'test/**/*'
+```
+
+The production image is built natively for `linux/amd64` and `linux/arm64`:
+
+```bash
+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](./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.
+
+### Company Information
+
+Task Venture Capital GmbH<br>
+Registered at District Court Bremen HRB 35230 HB, Germany
+
+For any legal inquiries or further information, please contact us via email at
+hello@task.vc.
+
+By using this repository, you acknowledge that you have read and understood
+these terms. If you do not agree with them, you must not use the repository.

package/ts/00_commitinfo_data.ts

@@ -0,0 +1,8 @@
+/**
+ * autocreated commitinfo by @push.rocks/commitinfo
+ */
+export const commitinfo = {
+  name: '@serve.zone/coremail',
+  version: '1.0.0',
+  description: 'Authenticated mail persistence and delivery orchestration for serve.zone workloads.'
+}