@serve.zone/coremail 1.0.0

package/ts/classes.auth.ts

@@ -0,0 +1,321 @@
+import * as plugins from './plugins.js';
+import type {
+  ICoreMailAuthLimiterSnapshot,
+  ICoreMailControlSession,
+  ICoreMailPeer,
+  ICoreMailWorkloadSession,
+  TCoreMailSession,
+} from './interfaces.js';
+import {
+  requireCoreMailIdentifier,
+  requireCoreMailSafeInteger,
+} from './coremail.selectors.js';
+
+type TCoreMailDesiredState = plugins.serveZoneInterfaces.data.ICoreMailDesiredState;
+type TCoreMailBinding = plugins.serveZoneInterfaces.data.ICoreMailBindingDesiredState;
+type TCoreMailVerifier =
+  plugins.serveZoneInterfaces.data.ICoreMailBindingCredentialVerifier;
+
+export const coreMailSessionKey = 'coremail.authenticated-session';
+export const coreMailPreAuthDeadlineKey = 'coremail.pre-auth-deadline';
+
+export class CoreMailAuthenticationError extends Error {
+  public constructor() {
+    super('CoreMail authentication failed.');
+    this.name = 'CoreMailAuthenticationError';
+  }
+}
+
+export class CoreMailAuthorizationError extends Error {
+  public constructor() {
+    super('CoreMail authority is unavailable.');
+    this.name = 'CoreMailAuthorizationError';
+  }
+}
+
+export class CoreMailCapabilityDeniedError extends Error {
+  public constructor() {
+    super('CoreMail operation is not permitted by this authority.');
+    this.name = 'CoreMailCapabilityDeniedError';
+  }
+}
+
+export class CoreMailAuthLimiter {
+  private inFlight = 0;
+  private tokens: number;
+  private lastRefillAt: number;
+
+  public constructor(
+    private readonly maximumInFlight = 4,
+    private readonly capacity = 8,
+    private readonly refillPerSecond = 2,
+    private readonly now: () => number = Date.now,
+  ) {
+    this.tokens = capacity;
+    this.lastRefillAt = now();
+  }
+
+  private refill(): void {
+    const now = this.now();
+    const elapsedMs = Math.max(0, now - this.lastRefillAt);
+    if (elapsedMs < 1_000) {
+      return;
+    }
+    const intervals = Math.floor(elapsedMs / 1_000);
+    this.tokens = Math.min(
+      this.capacity,
+      this.tokens + (intervals * this.refillPerSecond),
+    );
+    this.lastRefillAt += intervals * 1_000;
+  }
+
+  public snapshot(): ICoreMailAuthLimiterSnapshot {
+    this.refill();
+    return { inFlight: this.inFlight, tokens: this.tokens };
+  }
+
+  public async run<T>(workArg: () => Promise<T>): Promise<T> {
+    this.refill();
+    if (this.inFlight >= this.maximumInFlight || this.tokens < 1) {
+      throw new CoreMailAuthenticationError();
+    }
+    this.tokens--;
+    this.inFlight++;
+    try {
+      return await workArg();
+    } finally {
+      this.inFlight--;
+    }
+  }
+}
+
+const findAcceptedVerifier = (
+  credentialsArg: TCoreMailVerifier[],
+  credentialIdArg: string,
+  credentialVersionArg: number,
+  nowArg: number,
+): TCoreMailVerifier | undefined => credentialsArg.find((credentialArg) =>
+  credentialArg.credentialId === credentialIdArg
+  && credentialArg.version === credentialVersionArg
+  && (
+    credentialArg.state === 'current'
+    || (
+      credentialArg.state === 'retiring'
+      && credentialArg.acceptUntil !== undefined
+      && credentialArg.acceptUntil >= nowArg
+    )
+  )
+);
+
+export class CoreMailAuth {
+  public readonly limiter = new CoreMailAuthLimiter();
+
+  public constructor(
+    private readonly controlBootstrap:
+      plugins.serveZoneInterfaces.data.ICoreMailControlBootstrap,
+    private readonly getActiveDesiredState: () =>
+      Promise<TCoreMailDesiredState | null>,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  private requireFreshPeer(peerArg: ICoreMailPeer): void {
+    const deadline = peerArg.context.state[coreMailPreAuthDeadlineKey];
+    if (
+      peerArg.data.has(coreMailSessionKey)
+      || !Number.isSafeInteger(deadline)
+      || Number(deadline) < this.now()
+    ) {
+      peerArg.close(4401, 'authentication required');
+      throw new CoreMailAuthenticationError();
+    }
+  }
+
+  private async verify(
+    verifierArg: TCoreMailVerifier | undefined,
+    secretArg: string,
+  ): Promise<void> {
+    if (
+      !verifierArg
+      || typeof secretArg !== 'string'
+      || secretArg.length < 32
+      || secretArg.length > 512
+    ) {
+      throw new CoreMailAuthenticationError();
+    }
+    const verified = await this.limiter.run(async () =>
+      plugins.argon2.verify(verifierArg.verificationHash, secretArg)
+    );
+    if (!verified) {
+      throw new CoreMailAuthenticationError();
+    }
+  }
+
+  public async authenticateControl(
+    peerArg: ICoreMailPeer,
+    requestArg:
+      plugins.serveZoneInterfaces.requests.coremail.IReq_CoreMailAuthenticateControl['request'],
+  ): Promise<ICoreMailControlSession> {
+    this.requireFreshPeer(peerArg);
+    try {
+      const credentialId = requireCoreMailIdentifier(
+        requestArg.credentialId,
+        'credentialId',
+      );
+      const credentialVersion = requireCoreMailSafeInteger(
+        requestArg.credentialVersion,
+        'credentialVersion',
+        1,
+      );
+      const verifier = findAcceptedVerifier(
+        this.controlBootstrap.credentials,
+        credentialId,
+        credentialVersion,
+        this.now(),
+      );
+      await this.verify(verifier, requestArg.credentialSecret);
+      const session = Object.freeze<ICoreMailControlSession>({
+        kind: 'control',
+        peerId: peerArg.id,
+        credentialId,
+        credentialVersion,
+        authenticatedAt: this.now(),
+      });
+      peerArg.data.set(coreMailSessionKey, session);
+      return session;
+    } catch {
+      peerArg.close(4401, 'authentication failed');
+      throw new CoreMailAuthenticationError();
+    }
+  }
+
+  public async authenticateWorkload(
+    peerArg: ICoreMailPeer,
+    requestArg:
+      plugins.serveZoneInterfaces.requests.coremail.IReq_CoreMailAuthenticateWorkload['request'],
+  ): Promise<ICoreMailWorkloadSession> {
+    this.requireFreshPeer(peerArg);
+    try {
+      const desiredState = await this.getActiveDesiredState();
+      const bindingId = requireCoreMailIdentifier(
+        requestArg.bindingId,
+        'bindingId',
+      );
+      const credentialId = requireCoreMailIdentifier(
+        requestArg.credentialId,
+        'credentialId',
+      );
+      const credentialVersion = requireCoreMailSafeInteger(
+        requestArg.credentialVersion,
+        'credentialVersion',
+        1,
+      );
+      const binding = desiredState?.bindings.find((bindingArg) =>
+        bindingArg.bindingId === bindingId
+        && bindingArg.state !== 'disabled'
+      );
+      const verifier = binding && findAcceptedVerifier(
+        binding.credentials,
+        credentialId,
+        credentialVersion,
+        this.now(),
+      );
+      await this.verify(verifier, requestArg.credentialSecret);
+      const allowedOperations =
+        plugins.serveZoneInterfaces.data.resolveCoreMailWorkloadOperations(
+          binding!.state,
+          binding!.capabilities,
+        );
+      const session = Object.freeze<ICoreMailWorkloadSession>({
+        kind: 'workload',
+        peerId: peerArg.id,
+        tenantId: binding!.tenantId,
+        serviceId: binding!.serviceId,
+        bindingId: binding!.bindingId,
+        bindingRevision: binding!.revision,
+        configEpoch: desiredState!.configEpoch,
+        credentialId,
+        credentialVersion,
+        bindingState: binding!.state as 'active' | 'draining',
+        capabilities: Object.freeze([...binding!.capabilities]) as
+          plugins.serveZoneInterfaces.data.TCoreMailCapability[],
+        allowedOperations: Object.freeze([...allowedOperations]) as
+          plugins.serveZoneInterfaces.data.TCoreMailWorkloadOperation[],
+        coreMailTransferOrigin: desiredState!.gateway.coreMailTransferOrigin,
+        authenticatedAt: this.now(),
+      });
+      peerArg.data.set(coreMailSessionKey, session);
+      return session;
+    } catch {
+      peerArg.close(4401, 'authentication failed');
+      throw new CoreMailAuthenticationError();
+    }
+  }
+
+  public requireControlSession(peerArg: ICoreMailPeer): ICoreMailControlSession {
+    const session = peerArg.data.get(coreMailSessionKey) as TCoreMailSession | undefined;
+    if (!session || session.kind !== 'control' || session.peerId !== peerArg.id) {
+      peerArg.close(4403, 'authority unavailable');
+      throw new CoreMailAuthorizationError();
+    }
+    const verifier = findAcceptedVerifier(
+      this.controlBootstrap.credentials,
+      session.credentialId,
+      session.credentialVersion,
+      this.now(),
+    );
+    if (!verifier) {
+      peerArg.close(4403, 'authority expired');
+      throw new CoreMailAuthorizationError();
+    }
+    return session;
+  }
+
+  public async requireWorkloadSession(
+    peerArg: ICoreMailPeer,
+    operationArg: plugins.serveZoneInterfaces.data.TCoreMailWorkloadOperation,
+  ): Promise<{
+    session: ICoreMailWorkloadSession;
+    binding: TCoreMailBinding;
+  }> {
+    const session = peerArg.data.get(coreMailSessionKey) as TCoreMailSession | undefined;
+    if (!session || session.kind !== 'workload' || session.peerId !== peerArg.id) {
+      peerArg.close(4403, 'authority unavailable');
+      throw new CoreMailAuthorizationError();
+    }
+    const desiredState = await this.getActiveDesiredState();
+    const binding = desiredState?.bindings.find((bindingArg) =>
+      bindingArg.bindingId === session.bindingId
+      && bindingArg.serviceId === session.serviceId
+      && bindingArg.tenantId === session.tenantId
+      && bindingArg.revision === session.bindingRevision
+      && bindingArg.state === session.bindingState
+    );
+    const verifier = binding && findAcceptedVerifier(
+      binding.credentials,
+      session.credentialId,
+      session.credentialVersion,
+      this.now(),
+    );
+    if (
+      !desiredState
+      || desiredState.configEpoch !== session.configEpoch
+      || !binding
+      || !verifier
+    ) {
+      peerArg.close(4403, 'authority expired');
+      throw new CoreMailAuthorizationError();
+    }
+    const allowedOperations =
+      plugins.serveZoneInterfaces.data.resolveCoreMailWorkloadOperations(
+        binding.state,
+        binding.capabilities,
+      );
+    if (
+      !session.allowedOperations.includes(operationArg)
+      || !allowedOperations.includes(operationArg)
+    ) {
+      throw new CoreMailCapabilityDeniedError();
+    }
+    return { session, binding };
+  }
+}

package/ts/classes.config.ts

@@ -0,0 +1,104 @@
+import * as plugins from './plugins.js';
+import type { ICoreMailConfig } from './interfaces.js';
+
+const requireEnv = (keyArg: string): string => {
+  const value = process.env[keyArg];
+  if (!value || value.trim() !== value) {
+    throw new Error(`CoreMail requires a non-empty canonical ${keyArg}.`);
+  }
+  return value;
+};
+
+const parsePositiveInteger = (valueArg: string, keyArg: string, maximumArg: number): number => {
+  if (!/^[1-9][0-9]*$/.test(valueArg)) {
+    throw new Error(`${keyArg} must be a positive integer.`);
+  }
+  const value = Number(valueArg);
+  if (!Number.isSafeInteger(value) || value > maximumArg) {
+    throw new Error(`${keyArg} is outside the supported range.`);
+  }
+  return value;
+};
+
+const parsePlainJson = (valueArg: string, keyArg: string): Record<string, unknown> => {
+  const parsed: unknown = JSON.parse(valueArg);
+  if (
+    !parsed
+    || typeof parsed !== 'object'
+    || Array.isArray(parsed)
+    || Object.getPrototypeOf(parsed) !== Object.prototype
+  ) {
+    throw new Error(`${keyArg} must contain one plain JSON object.`);
+  }
+  return parsed as Record<string, unknown>;
+};
+
+const parseHostnames = (valueArg: string): string[] => {
+  const hostnames = valueArg.split(',');
+  if (
+    hostnames.length === 0
+    || hostnames.length > 16
+    || hostnames.some((entryArg) =>
+      entryArg.trim() !== entryArg
+      || !/^[a-z0-9](?:[a-z0-9.-]{0,251}[a-z0-9])?$/.test(entryArg)
+      || entryArg.includes('..')
+    )
+    || new Set(hostnames).size !== hostnames.length
+  ) {
+    throw new Error('COREMAIL_HOSTNAMES must be a unique canonical hostname list.');
+  }
+  return hostnames;
+};
+
+export const readCoreMailConfig = (): ICoreMailConfig => {
+  const controlBootstrap =
+    plugins.serveZoneInterfaces.data.normalizeCoreMailControlBootstrap(
+      parsePlainJson(
+        requireEnv(plugins.serveZoneInterfaces.data.coreMailRuntimeKeys.controlBootstrap),
+        plugins.serveZoneInterfaces.data.coreMailRuntimeKeys.controlBootstrap,
+      ),
+    );
+  const serviceId = requireEnv('COREMAIL_SERVICE_ID');
+  if (controlBootstrap.coreMailServiceId !== serviceId) {
+    throw new Error('CoreMail control bootstrap is bound to another service.');
+  }
+  const storageDescriptor = parsePlainJson(
+    requireEnv('COREMAIL_STORAGE_DESCRIPTOR'),
+    'COREMAIL_STORAGE_DESCRIPTOR',
+  );
+  return Object.freeze({
+    port: parsePositiveInteger(process.env.COREMAIL_PORT ?? '3000', 'COREMAIL_PORT', 65_535),
+    hostnames: Object.freeze(
+      parseHostnames(process.env.COREMAIL_HOSTNAMES ?? 'coremail.serve.zone'),
+    ) as unknown as string[],
+    mongoDescriptor: Object.freeze({
+      mongoDbUrl: requireEnv('COREMAIL_MONGODB_URL'),
+      mongoDbName: requireEnv('COREMAIL_MONGODB_NAME'),
+      maxPoolSize: parsePositiveInteger(
+        process.env.COREMAIL_MONGODB_MAX_POOL_SIZE ?? '50',
+        'COREMAIL_MONGODB_MAX_POOL_SIZE',
+        500,
+      ),
+      maxIdleTimeMS: 300_000,
+      serverSelectionTimeoutMS: 10_000,
+      socketTimeoutMS: 30_000,
+    }),
+    storageDescriptor: Object.freeze(storageDescriptor),
+    bucketName: requireEnv('COREMAIL_BUCKET_NAME'),
+    controlBootstrap,
+    resolveRuntimeSecret: requireEnv,
+    replica: Object.freeze({
+      taskId: requireEnv('COREMAIL_TASK_ID'),
+      serviceId,
+      rolloutId: requireEnv('COREMAIL_ROLLOUT_ID'),
+      rolloutGeneration: parsePositiveInteger(
+        requireEnv('COREMAIL_ROLLOUT_GENERATION'),
+        'COREMAIL_ROLLOUT_GENERATION',
+        Number.MAX_SAFE_INTEGER,
+      ),
+      imageDigest: plugins.serveZoneInterfaces.data.normalizeCoreMailSha256(
+        requireEnv('COREMAIL_IMAGE_DIGEST'),
+      ),
+    }),
+  });
+};

package/ts/classes.coremail.ts

@@ -0,0 +1,249 @@
+import * as plugins from './plugins.js';
+import { CoreMailAuth } from './classes.auth.js';
+import { readCoreMailConfig } from './classes.config.js';
+import { CoreMailDesiredStateService } from './classes.desiredstate.js';
+import {
+  CoreMailGateway,
+  CoreMailOutboundWorker,
+} from './classes.gateway.js';
+import { CoreMailInboundService } from './classes.inbound.js';
+import { CoreMailMaintenanceService } from './classes.maintenance.js';
+import {
+  createCoreMailModels,
+  prepareCoreMailModelsForTransactions,
+  type ICoreMailModels,
+} from './classes.models.js';
+import { CoreMailServer } from './classes.server.js';
+import { CoreMailStorage } from './classes.storage.js';
+import { CoreMailSubmissionService } from './classes.submissions.js';
+import { CoreMailTransferService } from './classes.transfer.js';
+import type { ICoreMailConfig } from './interfaces.js';
+
+type TLifecycleState =
+  | 'new'
+  | 'starting'
+  | 'running'
+  | 'stopping'
+  | 'failed'
+  | 'stopped';
+
+export class CoreMail {
+  public readonly config: ICoreMailConfig;
+  public readonly database: plugins.smartdata.SmartdataDb;
+  public readonly models: ICoreMailModels;
+  public readonly storage: CoreMailStorage;
+  public readonly transfers: CoreMailTransferService;
+  public readonly desiredState: CoreMailDesiredStateService;
+  public readonly auth: CoreMailAuth;
+  public readonly submissions: CoreMailSubmissionService;
+  public readonly inbound: CoreMailInboundService;
+  public readonly maintenance: CoreMailMaintenanceService;
+  public readonly gateway: CoreMailGateway;
+  public readonly server: CoreMailServer;
+  public readonly outboundWorker: CoreMailOutboundWorker;
+
+  private lifecycleState: TLifecycleState = 'new';
+  private startPromise: Promise<void> | null = null;
+  private stopPromise: Promise<void> | null = null;
+  private databaseStarted = false;
+  private storageStarted = false;
+  private gatewayStarted = false;
+  private serverStarted = false;
+  private workerStarted = false;
+  private maintenanceStarted = false;
+
+  public constructor(configArg: ICoreMailConfig = readCoreMailConfig()) {
+    this.config = configArg;
+    this.database = new plugins.smartdata.SmartdataDb(configArg.mongoDescriptor);
+    this.models = createCoreMailModels(this.database);
+    this.storage = new CoreMailStorage(
+      configArg.storageDescriptor,
+      configArg.bucketName,
+    );
+    this.transfers = new CoreMailTransferService(this.models, this.storage);
+    let server: CoreMailServer | undefined;
+    this.desiredState = new CoreMailDesiredStateService(
+      this.database,
+      this.models,
+      this.storage,
+      this.transfers,
+      configArg.replica,
+      (bindingArg, configEpochArg) =>
+        server?.activeSessionCounts(bindingArg, configEpochArg) ?? [],
+    );
+    this.auth = new CoreMailAuth(
+      configArg.controlBootstrap,
+      this.desiredState.getActiveDesiredState,
+    );
+    this.submissions = new CoreMailSubmissionService(
+      this.database,
+      this.models,
+      this.storage,
+      this.transfers,
+    );
+    this.inbound = new CoreMailInboundService(
+      this.database,
+      this.models,
+      this.transfers,
+      configArg.replica.serviceId,
+      this.desiredState.getActiveDesiredState,
+      configArg.resolveRuntimeSecret,
+    );
+    this.gateway = new CoreMailGateway(
+      configArg,
+      this.models,
+      this.transfers,
+      this.inbound,
+      this.desiredState.getActiveDesiredState,
+    );
+    this.maintenance = new CoreMailMaintenanceService(this.models, this.storage);
+    this.server = server = new CoreMailServer(
+      configArg,
+      this.database,
+      this.storage,
+      this.transfers,
+      this.desiredState,
+      this.auth,
+      this.submissions,
+      this.inbound,
+      this.gateway,
+    );
+    this.outboundWorker = new CoreMailOutboundWorker(
+      this.models,
+      this.transfers,
+      this.gateway,
+      configArg.replica.taskId,
+      configArg.replica.serviceId,
+    );
+  }
+
+  public async start(): Promise<void> {
+    if (this.lifecycleState === 'running') return;
+    if (this.lifecycleState === 'starting') {
+      await this.startPromise;
+      return;
+    }
+    if (this.lifecycleState !== 'new') {
+      throw new Error(`CoreMail cannot start from lifecycle state "${this.lifecycleState}".`);
+    }
+    this.lifecycleState = 'starting';
+    const startPromise = this.startInternal();
+    this.startPromise = startPromise;
+    try {
+      await startPromise;
+      this.lifecycleState = 'running';
+    } catch (error) {
+      try {
+        await this.stopStartedResources();
+        this.lifecycleState = 'stopped';
+      } catch (cleanupError) {
+        this.lifecycleState = 'failed';
+        throw new AggregateError(
+          [error, cleanupError],
+          'CoreMail startup and cleanup both failed.',
+        );
+      }
+      throw error;
+    } finally {
+      if (this.startPromise === startPromise) {
+        this.startPromise = null;
+      }
+    }
+  }
+
+  private async startInternal(): Promise<void> {
+    await this.database.init();
+    this.databaseStarted = true;
+    await Promise.all(
+      Object.values(this.models).map((modelArg) => modelArg.init()),
+    );
+    await prepareCoreMailModelsForTransactions(this.models);
+    await this.storage.start();
+    this.storageStarted = true;
+    await this.desiredState.start();
+    this.gateway.start();
+    this.gatewayStarted = true;
+    await this.server.start();
+    this.serverStarted = true;
+    this.maintenance.start();
+    this.maintenanceStarted = true;
+    this.outboundWorker.start();
+    this.workerStarted = true;
+  }
+
+  public async stop(): Promise<void> {
+    if (this.lifecycleState === 'stopped') return;
+    if (this.lifecycleState === 'stopping') {
+      await this.stopPromise;
+      return;
+    }
+    if (this.lifecycleState === 'starting') {
+      await this.startPromise?.catch(() => undefined);
+    }
+    this.lifecycleState = 'stopping';
+    const stopPromise = this.stopStartedResources();
+    this.stopPromise = stopPromise;
+    try {
+      await stopPromise;
+      this.lifecycleState = 'stopped';
+    } catch (error) {
+      this.lifecycleState = 'failed';
+      throw error;
+    } finally {
+      if (this.stopPromise === stopPromise) {
+        this.stopPromise = null;
+      }
+    }
+  }
+
+  private async stopStartedResources(): Promise<void> {
+    const errors: unknown[] = [];
+    const stopOne = async (
+      startedArg: boolean,
+      stopArg: () => Promise<void>,
+      markStoppedArg: () => void,
+    ) => {
+      if (!startedArg) return;
+      try {
+        await stopArg();
+        markStoppedArg();
+      } catch (error) {
+        errors.push(error);
+      }
+    };
+    await stopOne(
+      this.workerStarted,
+      () => this.outboundWorker.stop(),
+      () => { this.workerStarted = false; },
+    );
+    await stopOne(
+      this.serverStarted,
+      () => this.server.stop(),
+      () => { this.serverStarted = false; },
+    );
+    await stopOne(
+      this.maintenanceStarted,
+      () => this.maintenance.stop(),
+      () => { this.maintenanceStarted = false; },
+    );
+    await stopOne(
+      this.gatewayStarted,
+      () => this.gateway.stop(),
+      () => { this.gatewayStarted = false; },
+    );
+    await this.transfers.stop().catch((error) => errors.push(error));
+    await stopOne(
+      this.storageStarted,
+      () => this.storage.stop(),
+      () => { this.storageStarted = false; },
+    );
+    await stopOne(
+      this.databaseStarted,
+      () => this.database.close(),
+      () => { this.databaseStarted = false; },
+    );
+    if (errors.length > 0) {
+      throw new AggregateError(errors, 'CoreMail lifecycle shutdown failed.');
+    }
+  }
+}