@serve.zone/coremail 1.2.0 → 1.3.0

package/ts/classes.submissions.ts

@@ -1,9 +1,16 @@
 import * as plugins from './plugins.js';
+import {
+  CoreMailAuthorizationError,
+  CoreMailCapabilityDeniedError,
+} from './classes.auth.js';
 import { type ICoreMailModels } from './classes.models.js';
 import { CoreMailStorage, createSha256 } from './classes.storage.js';
 import { CoreMailTransferService } from './classes.transfer.js';
 import {
+  assertCoreMailSenderAllowed,
+  createCoreMailRawOutboundMessage,
   createCoreMailSubmissionDigest,
+  normalizeCoreMailEnvelope,
   normalizeCoreMailOutboundMessage,
 } from './coremail.validation.js';
 import { createCoreMailMime } from './coremail.mime.js';
@@ -13,12 +20,18 @@ import {
   incrementCoreMailQuotaCounter,
   withCoreMailTransaction,
 } from './coremail.quota.js';
+import {
+  ensureCoreMailStatCounter,
+  createCoreMailStatDescriptor,
+  incrementCoreMailStatCounter,
+} from './coremail.stats.js';
 import {
   requireCoreMailIdentifier,
   requireCoreMailUuid,
 } from './coremail.selectors.js';
 import type { ICoreMailSubmissionRecord } from './coremail.persistence.js';
 import type {
+  ICoreMailRawSubmissionInput,
   ICoreMailWorkloadSession,
   ISubmissionPartRecord,
   ITransferAuthority,
@@ -30,6 +43,42 @@ type TStoredSubmission =
   plugins.smartdata.TStoredDocument<ICoreMailSubmissionRecord>;
 
 const maximumPartBytes = plugins.serveZoneInterfaces.data.coreMailLimits.attachmentBytes;
+const maximumRawMimeBytes =
+  plugins.serveZoneInterfaces.data.coreMailLimits.serializedMimeBytes;
+
+/**
+ * The operation that authorizes creating a new outbound submission. An SMTP
+ * submission creates one without a typed request, so it is gated by exactly
+ * the rule `CoreMailAuthService.requireWorkloadSession` applies to its API
+ * counterpart.
+ */
+const rawSubmissionOperation = 'coreMailPrepareOutboundSubmission' as const;
+
+const assertRawSubmissionAuthority = (
+  sessionArg: ICoreMailWorkloadSession,
+  bindingArg: TBinding,
+): void => {
+  if (
+    bindingArg.tenantId !== sessionArg.tenantId
+    || bindingArg.serviceId !== sessionArg.serviceId
+    || bindingArg.bindingId !== sessionArg.bindingId
+    || bindingArg.revision !== sessionArg.bindingRevision
+    || bindingArg.state !== sessionArg.bindingState
+  ) {
+    throw new CoreMailAuthorizationError();
+  }
+  const allowedOperations =
+    plugins.serveZoneInterfaces.data.resolveCoreMailWorkloadOperations(
+      bindingArg.state,
+      bindingArg.capabilities,
+    );
+  if (
+    !allowedOperations.includes(rawSubmissionOperation)
+    || !sessionArg.allowedOperations.includes(rawSubmissionOperation)
+  ) {
+    throw new CoreMailCapabilityDeniedError();
+  }
+};
 
 const authorityFilter = (
   sessionArg: ICoreMailWorkloadSession,
@@ -60,6 +109,11 @@ const toPublicSubmission = (
     idempotencyKey: submissionArg.idempotencyKey,
     submissionDigest: submissionArg.submissionDigest,
     state: submissionArg.state,
+    // Records written before the discriminator existed are API submissions,
+    // and the wire type omits the field for exactly that case.
+    ...(submissionArg.source === undefined || submissionArg.source === 'api'
+      ? {}
+      : { source: submissionArg.source }),
     parts: submissionArg.parts.map((partArg) => ({
       partId: partArg.partId,
       state: partArg.state,
@@ -140,6 +194,7 @@ export class CoreMailSubmissionService {
       idempotencyKey: requestArg.idempotencyKey,
       submissionDigest,
       state: 'preparing',
+      source: 'api',
       message,
       parts,
       attempts: 0,
@@ -223,6 +278,146 @@ export class CoreMailSubmissionService {
     }
   }
 
+  /**
+   * Accept an exact-byte SMTP submission from an authenticated MSA session.
+   *
+   * CoreMail never parses, rewrites, or re-encodes `rawMime`. The bytes become
+   * the submission's immutable MIME directly, so the existing outbound worker
+   * and gateway hand an SMTP submission off exactly as they hand off an API
+   * submission that `finalize()` has published.
+   *
+   * The write order mirrors `finalize()`: the record that owns the object key
+   * is committed first and only becomes worker-visible once the bytes are
+   * durably stored, so a failure between the two steps leaves a retirable
+   * record rather than an object no record refers to.
+   */
+  public async submitRaw(
+    sessionArg: ICoreMailWorkloadSession,
+    bindingArg: TBinding,
+    inputArg: ICoreMailRawSubmissionInput,
+  ): Promise<{
+    submissionId: string;
+    submissionDigest: plugins.serveZoneInterfaces.data.TCoreMailSha256;
+  }> {
+    assertRawSubmissionAuthority(sessionArg, bindingArg);
+    const envelope = normalizeCoreMailEnvelope({
+      mailFrom: inputArg.envelope.from,
+      rcptTo: inputArg.envelope.to,
+    });
+    if (envelope.mailFrom === '') {
+      throw new Error('CoreMail raw submission requires an envelope sender.');
+    }
+    assertCoreMailSenderAllowed(envelope.mailFrom, bindingArg);
+    // Buffer is a Uint8Array subclass, so a listener may hand either over.
+    if (
+      !(inputArg.rawMime instanceof Uint8Array)
+      || inputArg.rawMime.byteLength === 0
+    ) {
+      throw new Error('CoreMail raw submission requires nonempty RFC822 bytes.');
+    }
+    if (inputArg.rawMime.byteLength > maximumRawMimeBytes) {
+      throw new Error('CoreMail raw submission exceeds its byte budget.');
+    }
+    const rawMime = new Uint8Array(inputArg.rawMime);
+    const message = createCoreMailRawOutboundMessage(envelope);
+    const idempotencyKey = `smtp:${plugins.nodeCrypto.randomUUID()}`;
+    const submissionDigest = createCoreMailSubmissionDigest(
+      idempotencyKey,
+      message,
+    );
+    const submissionId = plugins.nodeCrypto.randomUUID();
+    const mimeObjectKey =
+      `outbound-mime/${submissionId}/${submissionDigest.slice(7)}`;
+    const mimeSha256 = createSha256(rawMime);
+    const createdAt = this.now();
+    const submission: ICoreMailSubmissionRecord = {
+      submissionId,
+      tenantId: sessionArg.tenantId,
+      serviceId: sessionArg.serviceId,
+      bindingId: sessionArg.bindingId,
+      bindingRevision: sessionArg.bindingRevision,
+      revision: 0,
+      idempotencyKey,
+      submissionDigest,
+      state: 'ready',
+      source: 'smtp',
+      message,
+      parts: [],
+      mimeObjectKey,
+      mimeSha256,
+      mimeLengthBytes: rawMime.byteLength,
+      attempts: 0,
+      createdAt,
+      updatedAt: createdAt,
+    };
+    const quotaNow = this.now();
+    const quota = createCoreMailOutboundQuotaDescriptors({
+      tenantId: sessionArg.tenantId,
+      serviceId: sessionArg.serviceId,
+      bindingId: sessionArg.bindingId,
+      bindingRevision: sessionArg.bindingRevision,
+    }, quotaNow);
+    await ensureCoreMailQuotaCounter(this.models, quota.minute);
+    await ensureCoreMailQuotaCounter(this.models, quota.day);
+    await withCoreMailTransaction(this.database, async (transactionArg) => {
+      await incrementCoreMailQuotaCounter(
+        this.models,
+        quota.day,
+        bindingArg.limits.messagesPerDay,
+        quotaNow,
+        transactionArg,
+        quota.dayRetryAfterMs,
+      );
+      await incrementCoreMailQuotaCounter(
+        this.models,
+        quota.minute,
+        bindingArg.limits.messagesPerMinute,
+        quotaNow,
+        transactionArg,
+        quota.minuteRetryAfterMs,
+      );
+      const inserted = await this.models.Submission.exact.insert(
+        submission,
+        { session: transactionArg },
+      );
+      if (inserted.status === 'conflict') {
+        throw new Error('CoreMail submission identity conflicts with persisted intent.');
+      }
+      return { submissionId };
+    });
+    const committed = await this.models.Submission.exact.findStoredOne({
+      ...authorityFilter(sessionArg, submissionId),
+    });
+    if (!committed || committed.submissionDigest !== submissionDigest) {
+      throw new Error('CoreMail committed submission is unavailable.');
+    }
+    const published = await this.storage.putBytesExact(
+      mimeObjectKey,
+      rawMime,
+      'message/rfc822',
+      maximumRawMimeBytes,
+      AbortSignal.timeout(
+        plugins.serveZoneInterfaces.data.coreMailLimits.transferOverallTimeoutMs,
+      ),
+    );
+    if (
+      published.sha256 !== mimeSha256
+      || published.lengthBytes !== rawMime.byteLength
+    ) {
+      throw new Error('CoreMail published MIME integrity conflicts.');
+    }
+    const queuedAt = this.now();
+    const handoff = await this.publishSubmission(
+      committed,
+      'submittedSmtp',
+      queuedAt,
+    );
+    if (handoff.status !== 'transitioned') {
+      throw new Error('CoreMail raw submission publication fence changed.');
+    }
+    return { submissionId, submissionDigest };
+  }
+
   public async preparePartUpload(
     sessionArg: ICoreMailWorkloadSession,
     requestArg:
@@ -491,18 +686,11 @@ export class CoreMailSubmissionService {
       throw new Error('CoreMail published MIME integrity conflicts.');
     }
     const queuedAt = this.now();
-    const update = await this.models.Submission.exact.transition({
-      current: claim.document,
-      change: (modelArg) => {
-        modelArg.mimePublishedAt = queuedAt;
-        modelArg.workerRetryAt = queuedAt;
-        modelArg.updatedAt = queuedAt;
-        modelArg.revision += 1;
-        delete modelArg.leaseOwnerTaskId;
-        delete modelArg.leaseToken;
-        delete modelArg.leaseExpiresAt;
-      },
-    });
+    const update = await this.publishSubmission(
+      claim.document,
+      'submittedApi',
+      queuedAt,
+    );
     if (update.status !== 'transitioned') {
       const replay = await this.requireSubmission(
         sessionArg,
@@ -527,6 +715,53 @@ export class CoreMailSubmissionService {
     };
   }
 
+  /**
+   * Publish an owned immutable MIME and hand the submission to the worker.
+   *
+   * The submitted counter is incremented in the same transaction as the
+   * transition that publishes, and only when `statsSubmittedCountedAt` is
+   * still absent. An interrupted publication that finalization later repeats
+   * therefore republishes without counting a second submission.
+   */
+  private async publishSubmission(
+    currentArg: TStoredSubmission,
+    kindArg: 'submittedApi' | 'submittedSmtp',
+    queuedAtArg: number,
+  ): Promise<plugins.smartdata.TExactTransitionResult<ICoreMailSubmissionRecord>> {
+    const alreadyCounted = currentArg.statsSubmittedCountedAt !== undefined;
+    const descriptor = createCoreMailStatDescriptor(currentArg, queuedAtArg);
+    if (!alreadyCounted) {
+      await ensureCoreMailStatCounter(this.models, descriptor);
+    }
+    return await withCoreMailTransaction(this.database, async (transactionArg) => {
+      const transitioned = await this.models.Submission.exact.transition({
+        current: currentArg,
+        change: (modelArg) => {
+          modelArg.mimePublishedAt = queuedAtArg;
+          modelArg.workerRetryAt = queuedAtArg;
+          modelArg.updatedAt = queuedAtArg;
+          modelArg.revision += 1;
+          if (!alreadyCounted) {
+            modelArg.statsSubmittedCountedAt = queuedAtArg;
+          }
+          delete modelArg.leaseOwnerTaskId;
+          delete modelArg.leaseToken;
+          delete modelArg.leaseExpiresAt;
+        },
+      }, { session: transactionArg });
+      if (transitioned.status === 'transitioned' && !alreadyCounted) {
+        await incrementCoreMailStatCounter(
+          this.models,
+          descriptor,
+          kindArg,
+          queuedAtArg,
+          transactionArg,
+        );
+      }
+      return transitioned;
+    });
+  }
+
   public async get(
     sessionArg: ICoreMailWorkloadSession,
     requestArg:

package/ts/coremail.errors.ts

@@ -0,0 +1,111 @@
+import * as plugins from './plugins.js';
+import {
+  CoreMailAuthenticationError,
+  CoreMailAuthorizationError,
+  CoreMailCapabilityDeniedError,
+} from './classes.auth.js';
+import { CoreMailQuotaExceededError } from './coremail.quota.js';
+import { logCoreMailFailure } from './coremail.log.js';
+
+type TErrorCode = plugins.serveZoneInterfaces.data.TCoreMailErrorCode;
+
+export const privacySafeError = (
+  errorArg: unknown,
+): plugins.typedrequest.TypedResponseError => {
+  let code: TErrorCode = 'INVALID_REQUEST';
+  let retryable = false;
+  if (errorArg instanceof CoreMailAuthenticationError) {
+    code = 'AUTHENTICATION_FAILED';
+  } else if (errorArg instanceof CoreMailCapabilityDeniedError) {
+    code = 'CAPABILITY_DENIED';
+  } else if (errorArg instanceof CoreMailAuthorizationError) {
+    code = 'AUTHORITY_REVOKED';
+  } else if (errorArg instanceof CoreMailQuotaExceededError) {
+    return new plugins.typedrequest.TypedResponseError('CoreMail request rejected.', {
+      code: 'QUOTA_EXCEEDED',
+      retryable: true,
+      ...(errorArg.retryAfterMs === undefined
+        ? {}
+        : { retryAfterMs: errorArg.retryAfterMs }),
+    } satisfies plugins.serveZoneInterfaces.data.ICoreMailErrorData);
+  } else if (
+    errorArg instanceof plugins.serveZoneInterfaces.data.CoreMailContractError
+  ) {
+    code = errorArg.code;
+  } else if (
+    errorArg instanceof Error
+    && errorArg.message.includes('gateway')
+    && errorArg.message.includes('unavailable')
+  ) {
+    code = 'GATEWAY_UNAVAILABLE';
+    retryable = true;
+  } else if (
+    errorArg instanceof Error
+    && errorArg.message.includes('idempotency')
+  ) {
+    code = 'IDEMPOTENCY_CONFLICT';
+  } else if (
+    errorArg instanceof Error
+    && errorArg.message.includes('fence')
+  ) {
+    code = 'STATE_CONFLICT';
+    retryable = true;
+  } else if (
+    errorArg instanceof Error
+    && (
+      errorArg.message.includes('byte budget')
+      || errorArg.message.includes('content budget')
+      || errorArg.message.includes('exceeds')
+    )
+  ) {
+    code = 'PAYLOAD_LIMIT_EXCEEDED';
+  }
+  return new plugins.typedrequest.TypedResponseError('CoreMail request rejected.', {
+    code,
+    retryable,
+  } satisfies plugins.serveZoneInterfaces.data.ICoreMailErrorData);
+};
+
+/**
+ * Register one typed handler with uniform failure redaction.
+ *
+ * Both peer-facing routers use this. The workload socket and the gateway
+ * socket are different peers, but a caller on either side has to be able to
+ * tell `QUOTA_EXCEEDED` from `STATE_CONFLICT`, so both must answer with the
+ * typed `ICoreMailErrorData` envelope rather than an opaque message.
+ *
+ * `handlerArg` is typed as typedrequest's own `THandlerFunction` rather than
+ * a hand-written signature: since typedrequest 8 both sides are wrapped in
+ * the `TReverseVirtualStreamDirections` mapped type, which does not reduce
+ * inside a generic wrapper, so any restatement of the shape stops being
+ * assignable. Concrete `IReq_*` types reduce normally, which is why the call
+ * sites need no change.
+ */
+export const addPrivacySafeTypedHandler = <
+  TRequest extends plugins.typedrequestInterfaces.ITypedRequest,
+>(
+  routerArg: plugins.typedrequest.TypedRouter,
+  scopeArg: 'server' | 'gateway',
+  methodArg: TRequest['method'],
+  handlerArg: plugins.typedrequest.THandlerFunction<TRequest>,
+): void => {
+  routerArg.addTypedHandler(new plugins.typedrequest.TypedHandler<TRequest>(
+    methodArg,
+    async (requestArg, toolsArg) => {
+      try {
+        return await handlerArg(requestArg, toolsArg);
+      } catch (error) {
+        const safeError = privacySafeError(error);
+        if (safeError.errorData?.code === 'INVALID_REQUEST') {
+          await logCoreMailFailure(
+            scopeArg,
+            'UNEXPECTED_HANDLER_FAILURE',
+            error,
+            { method: methodArg },
+          ).catch(() => undefined);
+        }
+        throw safeError;
+      }
+    },
+  ));
+};

package/ts/coremail.log.ts

@@ -40,6 +40,7 @@ export const logCoreMailFailure = async (
     | 'lifecycle'
     | 'retention'
     | 'server'
+    | 'smtp'
     | 'transfer'
     | 'worker',
   codeArg: string,

package/ts/coremail.mime.ts

@@ -92,3 +92,92 @@ export const createCoreMailMime = (
   }
   return encoded;
 };
+
+/** Bytes of a stored message that are read to find its headers. */
+export const coreMailHeaderScanBytes = 64 * 1024;
+
+const decodeEncodedWords = (valueArg: string): string =>
+  valueArg.replace(
+    /=\?([A-Za-z0-9._-]+)\?([BbQq])\?([^?]*)\?=/g,
+    (matchArg, charsetArg: string, encodingArg: string, payloadArg: string) => {
+      const charset = charsetArg.toLowerCase();
+      // Only the charsets Node decodes natively; anything else keeps its raw
+      // encoded-word so nothing is silently corrupted.
+      if (charset !== 'utf-8' && charset !== 'us-ascii' && charset !== 'iso-8859-1') {
+        return matchArg;
+      }
+      const nodeCharset = charset === 'iso-8859-1' ? 'latin1' : 'utf8';
+      try {
+        if (encodingArg.toLowerCase() === 'b') {
+          return Buffer.from(payloadArg, 'base64').toString(nodeCharset);
+        }
+        const quoted = payloadArg
+          .replaceAll('_', ' ')
+          .replace(/=([0-9A-Fa-f]{2})/g, (_matchArg, hexArg: string) =>
+            String.fromCharCode(Number.parseInt(hexArg, 16))
+          );
+        return Buffer.from(quoted, 'binary').toString(nodeCharset);
+      } catch {
+        return matchArg;
+      }
+    },
+  );
+
+const sanitizeHeaderValue = (
+  valueArg: string,
+  maximumBytesArg: number,
+): string | undefined => {
+  let value = valueArg.replace(/[\u0000-\u001f\u007f]/g, ' ').trim();
+  if (!value) return undefined;
+  while (Buffer.byteLength(value, 'utf8') > maximumBytesArg) {
+    value = value.slice(0, -1).trim();
+    if (!value) return undefined;
+  }
+  return value;
+};
+
+/**
+ * Read `Message-ID` and `Subject` out of an RFC 5322 header block.
+ *
+ * `bytesArg` is a bounded prefix of the stored message, so a header block that
+ * does not end inside it is treated as absent rather than guessed at. Folded
+ * continuation lines are unfolded, `Subject` encoded-words are decoded when
+ * that is possible without a dependency, and both values are trimmed to the
+ * byte budgets the delivery record enforces.
+ */
+export const parseCoreMailMessageHeaders = (
+  bytesArg: Uint8Array,
+): { messageId?: string; subject?: string } => {
+  const text = Buffer.from(bytesArg).toString('binary');
+  const boundary = text.indexOf('\r\n\r\n');
+  const headerSection = boundary < 0 ? text : text.slice(0, boundary);
+  const unfolded: string[] = [];
+  for (const rawLine of headerSection.split('\r\n')) {
+    if (/^[ \t]/.test(rawLine) && unfolded.length > 0) {
+      unfolded[unfolded.length - 1] += ` ${rawLine.trim()}`;
+      continue;
+    }
+    unfolded.push(rawLine);
+  }
+  const result: { messageId?: string; subject?: string } = {};
+  for (const line of unfolded) {
+    const separator = line.indexOf(':');
+    if (separator < 1) continue;
+    const name = line.slice(0, separator).trim().toLowerCase();
+    const rawValue = line.slice(separator + 1);
+    if (name === 'message-id' && result.messageId === undefined) {
+      const value = sanitizeHeaderValue(
+        Buffer.from(rawValue, 'binary').toString('utf8'),
+        998,
+      );
+      if (value) result.messageId = value;
+    } else if (name === 'subject' && result.subject === undefined) {
+      const value = sanitizeHeaderValue(
+        decodeEncodedWords(Buffer.from(rawValue, 'binary').toString('utf8')),
+        768,
+      );
+      if (value) result.subject = value;
+    }
+  }
+  return result;
+};