@serve.zone/interfaces 20.2.0 → 21.0.0

package/ts/data/coremail.runtime.ts

@@ -0,0 +1,675 @@
+import {
+  canonicalizeStrictJson,
+  createCanonicalJsonSha256Hex,
+  deepFreezeValue,
+  strictCanonicalJsonRules,
+} from '../private/canonicaljson.js';
+import {
+  coreMailCredentialVerifierPolicy,
+  type ICoreMailBindingCredentialVerifier,
+  type ICoreMailBindingDesiredState,
+  type ICoreMailControlBootstrap,
+  type ICoreMailDesiredState,
+  type ICoreMailGatewayDesiredState,
+  type ICoreMailGatewayPeerDesiredState,
+  type TCoreMailCapability,
+  type TCoreMailSha256,
+} from './coremail.js';
+
+export const coreMailCanonicalJsonRules = strictCanonicalJsonRules;
+
+export const coreMailContractLimits = Object.freeze({
+  maximumIdentifierBytes: 128,
+  maximumEnvironmentKeyBytes: 128,
+  maximumEndpointBytes: 2_048,
+  maximumMailboxBytes: 254,
+  maximumBindings: 10_000,
+  maximumCredentialsPerAuthority: 16,
+  maximumAllowedSendersPerBinding: 1_000,
+  maximumInboundRecipientsPerBinding: 10_000,
+} as const);
+
+export class CoreMailContractError extends Error {
+  public constructor(reasonArg: string) {
+    super(`CoreMail contract error: ${reasonArg}`);
+    this.name = 'CoreMailContractError';
+  }
+}
+
+type TStrictRecord = Record<string, unknown>;
+
+const fail = (reasonArg: string): never => {
+  throw new CoreMailContractError(reasonArg);
+};
+
+const compareStrings = (leftArg: string, rightArg: string): number =>
+  leftArg < rightArg ? -1 : leftArg > rightArg ? 1 : 0;
+
+const readRecord = (valueArg: unknown, pathArg: string): TStrictRecord => {
+  if (
+    !valueArg
+    || typeof valueArg !== 'object'
+    || Array.isArray(valueArg)
+    || (
+      Object.getPrototypeOf(valueArg) !== Object.prototype
+      && Object.getPrototypeOf(valueArg) !== null
+    )
+  ) {
+    return fail(`${pathArg} must be a plain object`);
+  }
+  return valueArg as TStrictRecord;
+};
+
+const assertKeys = (
+  recordArg: TStrictRecord,
+  pathArg: string,
+  requiredKeysArg: string[],
+  optionalKeysArg: string[] = [],
+): void => {
+  const allowedKeys = new Set([...requiredKeysArg, ...optionalKeysArg]);
+  const keys = Reflect.ownKeys(recordArg);
+  if (keys.some((keyArg) => typeof keyArg !== 'string')) {
+    fail(`${pathArg} must not contain symbol keys`);
+  }
+  for (const requiredKey of requiredKeysArg) {
+    if (!Object.hasOwn(recordArg, requiredKey)) {
+      fail(`${pathArg}.${requiredKey} is required`);
+    }
+  }
+  for (const key of keys as string[]) {
+    const descriptor = Object.getOwnPropertyDescriptor(recordArg, key);
+    if (
+      !descriptor
+      || !descriptor.enumerable
+      || !Object.hasOwn(descriptor, 'value')
+    ) {
+      fail(`${pathArg}.${key} must be an enumerable data property`);
+    }
+    if (!allowedKeys.has(key)) {
+      fail(`${pathArg}.${key} is not allowed`);
+    }
+  }
+};
+
+const readArray = (
+  valueArg: unknown,
+  pathArg: string,
+  maximumLengthArg: number,
+): unknown[] => {
+  if (!Array.isArray(valueArg) || Object.getPrototypeOf(valueArg) !== Array.prototype) {
+    return fail(`${pathArg} must be a plain array`);
+  }
+  if (valueArg.length > maximumLengthArg) {
+    fail(`${pathArg} exceeds its maximum length of ${maximumLengthArg}`);
+  }
+  for (let index = 0; index < valueArg.length; index++) {
+    if (!Object.hasOwn(valueArg, index)) {
+      fail(`${pathArg} must not contain sparse entries`);
+    }
+    const descriptor = Object.getOwnPropertyDescriptor(valueArg, String(index));
+    if (
+      !descriptor
+      || !descriptor.enumerable
+      || !Object.hasOwn(descriptor, 'value')
+    ) {
+      fail(`${pathArg}[${index}] must be an enumerable data property`);
+    }
+  }
+  for (const key of Reflect.ownKeys(valueArg)) {
+    if (key === 'length') {
+      continue;
+    }
+    if (
+      typeof key !== 'string'
+      || !/^(?:0|[1-9][0-9]*)$/.test(key)
+      || Number(key) >= valueArg.length
+    ) {
+      fail(`${pathArg} must not contain extra properties`);
+    }
+  }
+  return valueArg;
+};
+
+const requireString = (
+  valueArg: unknown,
+  pathArg: string,
+  maximumBytesArg: number,
+): string => {
+  if (typeof valueArg !== 'string' || valueArg.length === 0) {
+    return fail(`${pathArg} must be a non-empty string`);
+  }
+  if (new TextEncoder().encode(valueArg).byteLength > maximumBytesArg) {
+    fail(`${pathArg} exceeds ${maximumBytesArg} UTF-8 bytes`);
+  }
+  return valueArg;
+};
+
+const identifierRegex = /^[A-Za-z0-9](?:[A-Za-z0-9._:-]{0,126}[A-Za-z0-9])?$/;
+
+const requireIdentifier = (valueArg: unknown, pathArg: string): string => {
+  const value = requireString(
+    valueArg,
+    pathArg,
+    coreMailContractLimits.maximumIdentifierBytes,
+  );
+  if (!identifierRegex.test(value)) {
+    fail(`${pathArg} must be a canonical identifier`);
+  }
+  return value;
+};
+
+const requireSafeInteger = (
+  valueArg: unknown,
+  pathArg: string,
+  minimumArg: number,
+): number => {
+  if (!Number.isSafeInteger(valueArg) || (valueArg as number) < minimumArg) {
+    return fail(`${pathArg} must be a safe integer greater than or equal to ${minimumArg}`);
+  }
+  return valueArg as number;
+};
+
+const decodeCanonicalBase64 = (
+  valueArg: string,
+  expectedBytesArg: number,
+  pathArg: string,
+): void => {
+  if (!/^[A-Za-z0-9+/]+$/.test(valueArg)) {
+    fail(`${pathArg} must use unpadded standard base64`);
+  }
+  const paddedValue = `${valueArg}${'='.repeat((4 - (valueArg.length % 4)) % 4)}`;
+  let decoded: string;
+  try {
+    decoded = globalThis.atob(paddedValue);
+  } catch {
+    return fail(`${pathArg} must be valid base64`);
+  }
+  if (decoded.length !== expectedBytesArg) {
+    fail(`${pathArg} must encode exactly ${expectedBytesArg} bytes`);
+  }
+  const canonical = globalThis.btoa(decoded).replace(/=+$/u, '');
+  if (canonical !== valueArg) {
+    fail(`${pathArg} must be canonical unpadded base64`);
+  }
+};
+
+export const normalizeCoreMailSha256 = (
+  valueArg: unknown,
+  pathArg = 'sha256',
+): TCoreMailSha256 => {
+  if (
+    typeof valueArg !== 'string'
+    || !/^sha256:[0-9a-f]{64}$/.test(valueArg)
+  ) {
+    return fail(`${pathArg} must be a canonical sha256:<64 lowercase hex> digest`);
+  }
+  return valueArg as TCoreMailSha256;
+};
+
+export const normalizeCoreMailCredentialVerifier = (
+  valueArg: unknown,
+  pathArg = 'credential',
+): ICoreMailBindingCredentialVerifier => {
+  const record = readRecord(valueArg, pathArg);
+  assertKeys(
+    record,
+    pathArg,
+    ['credentialId', 'version', 'state', 'format', 'verificationHash'],
+    ['acceptUntil'],
+  );
+  const credentialId = requireIdentifier(record.credentialId, `${pathArg}.credentialId`);
+  const version = requireSafeInteger(record.version, `${pathArg}.version`, 1);
+  const state = record.state === 'current' || record.state === 'retiring'
+    ? record.state
+    : fail(`${pathArg}.state must be current or retiring`);
+  const format = record.format === coreMailCredentialVerifierPolicy.format
+    ? record.format
+    : fail(`${pathArg}.format must be ${coreMailCredentialVerifierPolicy.format}`);
+  const verificationHash = requireString(
+    record.verificationHash,
+    `${pathArg}.verificationHash`,
+    512,
+  );
+  const match = verificationHash.match(
+    /^\$argon2id\$v=19\$m=65536,t=3,p=1\$([A-Za-z0-9+/]+)\$([A-Za-z0-9+/]+)$/,
+  );
+  if (!match) {
+    return fail(`${pathArg}.verificationHash must use the canonical argon2id-v1 PHC form`);
+  }
+  const [, saltBase64, digestBase64] = match;
+  decodeCanonicalBase64(
+    saltBase64,
+    coreMailCredentialVerifierPolicy.saltLengthBytes,
+    `${pathArg}.verificationHash salt`,
+  );
+  decodeCanonicalBase64(
+    digestBase64,
+    coreMailCredentialVerifierPolicy.hashLengthBytes,
+    `${pathArg}.verificationHash digest`,
+  );
+
+  if (state === 'current' && Object.hasOwn(record, 'acceptUntil')) {
+    fail(`${pathArg}.acceptUntil is forbidden for a current credential`);
+  }
+  if (state === 'retiring' && !Object.hasOwn(record, 'acceptUntil')) {
+    fail(`${pathArg}.acceptUntil is required for a retiring credential`);
+  }
+
+  const normalized: ICoreMailBindingCredentialVerifier = {
+    credentialId,
+    version,
+    state,
+    format,
+    verificationHash,
+  };
+  if (state === 'retiring') {
+    normalized.acceptUntil = requireSafeInteger(
+      record.acceptUntil,
+      `${pathArg}.acceptUntil`,
+      1,
+    );
+  }
+  return deepFreezeValue(normalized);
+};
+
+const normalizeCredentialSet = (
+  valueArg: unknown,
+  pathArg: string,
+): ICoreMailBindingCredentialVerifier[] => {
+  const credentials = readArray(
+    valueArg,
+    pathArg,
+    coreMailContractLimits.maximumCredentialsPerAuthority,
+  ).map((entryArg, indexArg) =>
+    normalizeCoreMailCredentialVerifier(entryArg, `${pathArg}[${indexArg}]`),
+  );
+  if (credentials.length === 0) {
+    fail(`${pathArg} must contain at least one credential`);
+  }
+  if (credentials.filter((entryArg) => entryArg.state === 'current').length !== 1) {
+    fail(`${pathArg} must contain exactly one current credential`);
+  }
+  const identities = new Set<string>();
+  const versions = new Set<number>();
+  for (const credential of credentials) {
+    const identity = `${credential.credentialId}:${credential.version}`;
+    if (identities.has(identity) || versions.has(credential.version)) {
+      fail(`${pathArg} contains a duplicate credential identity or version`);
+    }
+    identities.add(identity);
+    versions.add(credential.version);
+  }
+  const current = credentials.find((entryArg) => entryArg.state === 'current')!;
+  if (credentials.some((entryArg) =>
+    entryArg.state === 'retiring' && entryArg.version >= current.version
+  )) {
+    fail(`${pathArg} current credential must have the greatest version`);
+  }
+  return credentials.sort((leftArg, rightArg) =>
+    leftArg.version - rightArg.version
+    || compareStrings(leftArg.credentialId, rightArg.credentialId),
+  );
+};
+
+const mailboxLocalPartRegex = /^[a-z0-9!#$%&'*+/=?^_`{|}~.-]+$/;
+const mailboxDomainLabelRegex = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+
+const requireCanonicalMailbox = (valueArg: unknown, pathArg: string): string => {
+  const value = requireString(
+    valueArg,
+    pathArg,
+    coreMailContractLimits.maximumMailboxBytes,
+  );
+  const atIndex = value.lastIndexOf('@');
+  const localPart = atIndex > 0 ? value.slice(0, atIndex) : '';
+  const domain = atIndex > 0 ? value.slice(atIndex + 1) : '';
+  const domainLabels = domain.split('.');
+  if (
+    value !== value.toLowerCase()
+    || localPart.length === 0
+    || localPart.length > 64
+    || !mailboxLocalPartRegex.test(localPart)
+    || localPart.startsWith('.')
+    || localPart.endsWith('.')
+    || localPart.includes('..')
+    || domain.length === 0
+    || domain.length > 253
+    || domainLabels.length < 2
+    || domainLabels.some((labelArg) => !mailboxDomainLabelRegex.test(labelArg))
+  ) {
+    fail(`${pathArg} must be a canonical lowercase mailbox`);
+  }
+  return value;
+};
+
+const normalizeUniqueSortedStrings = (
+  valueArg: unknown,
+  pathArg: string,
+  maximumLengthArg: number,
+  normalizeEntryArg: (entryArg: unknown, pathArg: string) => string,
+): string[] => {
+  const values = readArray(valueArg, pathArg, maximumLengthArg).map(
+    (entryArg, indexArg) => normalizeEntryArg(entryArg, `${pathArg}[${indexArg}]`),
+  );
+  if (new Set(values).size !== values.length) {
+    fail(`${pathArg} must contain unique values`);
+  }
+  return values.sort();
+};
+
+const normalizeCapabilities = (
+  valueArg: unknown,
+  pathArg: string,
+): TCoreMailCapability[] => {
+  const capabilities = readArray(valueArg, pathArg, 2).map((entryArg, indexArg) => {
+    if (entryArg !== 'outbound' && entryArg !== 'inbound') {
+      return fail(`${pathArg}[${indexArg}] must be outbound or inbound`);
+    }
+    return entryArg;
+  });
+  if (capabilities.length === 0 || new Set(capabilities).size !== capabilities.length) {
+    fail(`${pathArg} must contain unique capabilities`);
+  }
+  return capabilities.sort();
+};
+
+const normalizeLimits = (
+  valueArg: unknown,
+  pathArg: string,
+): NonNullable<ICoreMailBindingDesiredState['limits']> => {
+  const record = readRecord(valueArg, pathArg);
+  assertKeys(
+    record,
+    pathArg,
+    [],
+    ['messagesPerMinute', 'messagesPerDay', 'maxPendingInbound'],
+  );
+  if (Object.keys(record).length === 0) {
+    fail(`${pathArg} must not be empty`);
+  }
+  const normalized: NonNullable<ICoreMailBindingDesiredState['limits']> = {};
+  for (const key of [
+    'messagesPerMinute',
+    'messagesPerDay',
+    'maxPendingInbound',
+  ] as const) {
+    if (Object.hasOwn(record, key)) {
+      normalized[key] = requireSafeInteger(record[key], `${pathArg}.${key}`, 1);
+    }
+  }
+  return normalized;
+};
+
+const normalizeBinding = (
+  valueArg: unknown,
+  pathArg: string,
+): ICoreMailBindingDesiredState => {
+  const record = readRecord(valueArg, pathArg);
+  assertKeys(
+    record,
+    pathArg,
+    [
+      'schemaVersion',
+      'bindingId',
+      'serviceId',
+      'tenantId',
+      'revision',
+      'state',
+      'capabilities',
+      'credentials',
+      'allowedSenders',
+      'inboundRecipients',
+    ],
+    ['defaultSender', 'limits'],
+  );
+  if (record.schemaVersion !== 1) {
+    fail(`${pathArg}.schemaVersion must be 1`);
+  }
+  const state = record.state === 'active' || record.state === 'disabled'
+    ? record.state
+    : fail(`${pathArg}.state must be active or disabled`);
+  const capabilities = normalizeCapabilities(record.capabilities, `${pathArg}.capabilities`);
+  const allowedSenders = normalizeUniqueSortedStrings(
+    record.allowedSenders,
+    `${pathArg}.allowedSenders`,
+    coreMailContractLimits.maximumAllowedSendersPerBinding,
+    requireCanonicalMailbox,
+  );
+  const inboundRecipients = normalizeUniqueSortedStrings(
+    record.inboundRecipients,
+    `${pathArg}.inboundRecipients`,
+    coreMailContractLimits.maximumInboundRecipientsPerBinding,
+    requireCanonicalMailbox,
+  );
+  if (!capabilities.includes('outbound') && allowedSenders.length > 0) {
+    fail(`${pathArg}.allowedSenders requires the outbound capability`);
+  }
+  if (!capabilities.includes('inbound') && inboundRecipients.length > 0) {
+    fail(`${pathArg}.inboundRecipients requires the inbound capability`);
+  }
+
+  const normalized: ICoreMailBindingDesiredState = {
+    schemaVersion: 1,
+    bindingId: requireIdentifier(record.bindingId, `${pathArg}.bindingId`),
+    serviceId: requireIdentifier(record.serviceId, `${pathArg}.serviceId`),
+    tenantId: requireIdentifier(record.tenantId, `${pathArg}.tenantId`),
+    revision: requireSafeInteger(record.revision, `${pathArg}.revision`, 1),
+    state,
+    capabilities,
+    credentials: normalizeCredentialSet(record.credentials, `${pathArg}.credentials`),
+    allowedSenders,
+    inboundRecipients,
+  };
+  if (Object.hasOwn(record, 'defaultSender')) {
+    normalized.defaultSender = requireCanonicalMailbox(
+      record.defaultSender,
+      `${pathArg}.defaultSender`,
+    );
+    if (!allowedSenders.includes(normalized.defaultSender)) {
+      fail(`${pathArg}.defaultSender must be present in allowedSenders`);
+    }
+  }
+  if (Object.hasOwn(record, 'limits')) {
+    normalized.limits = normalizeLimits(record.limits, `${pathArg}.limits`);
+  }
+  return normalized;
+};
+
+const requireCanonicalUrl = (
+  valueArg: unknown,
+  pathArg: string,
+  protocolArg: 'https:' | 'wss:',
+  originOnlyArg: boolean,
+): string => {
+  const value = requireString(
+    valueArg,
+    pathArg,
+    coreMailContractLimits.maximumEndpointBytes,
+  );
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    return fail(`${pathArg} must be an absolute URL`);
+  }
+  if (
+    url.protocol !== protocolArg
+    || url.username
+    || url.password
+    || url.search
+    || url.hash
+  ) {
+    fail(`${pathArg} must be a credential-free canonical ${protocolArg} URL`);
+  }
+  if (originOnlyArg && url.pathname !== '/') {
+    fail(`${pathArg} must be an origin without a path`);
+  }
+  const canonical = originOnlyArg
+    ? url.origin
+    : url.toString();
+  if (canonical !== value) {
+    fail(`${pathArg} must already be in canonical URL form`);
+  }
+  return canonical;
+};
+
+const normalizeGateway = (
+  valueArg: unknown,
+  pathArg: string,
+): ICoreMailGatewayDesiredState => {
+  const record = readRecord(valueArg, pathArg);
+  assertKeys(
+    record,
+    pathArg,
+    ['endpointUrl', 'credentialId', 'credentialVersion', 'credentialSecretKey'],
+  );
+  const credentialSecretKey = requireString(
+    record.credentialSecretKey,
+    `${pathArg}.credentialSecretKey`,
+    coreMailContractLimits.maximumEnvironmentKeyBytes,
+  );
+  if (!/^[A-Z][A-Z0-9_]{0,127}$/.test(credentialSecretKey)) {
+    fail(`${pathArg}.credentialSecretKey must be a canonical environment key`);
+  }
+  return {
+    endpointUrl: requireCanonicalUrl(
+      record.endpointUrl,
+      `${pathArg}.endpointUrl`,
+      'wss:',
+      false,
+    ),
+    credentialId: requireIdentifier(record.credentialId, `${pathArg}.credentialId`),
+    credentialVersion: requireSafeInteger(
+      record.credentialVersion,
+      `${pathArg}.credentialVersion`,
+      1,
+    ),
+    credentialSecretKey,
+  };
+};
+
+export const normalizeCoreMailDesiredState = (
+  valueArg: unknown,
+): ICoreMailDesiredState => {
+  const record = readRecord(valueArg, 'desiredState');
+  assertKeys(record, 'desiredState', ['schemaVersion', 'configEpoch', 'bindings', 'gateway']);
+  if (record.schemaVersion !== 1) {
+    fail('desiredState.schemaVersion must be 1');
+  }
+  const bindings = readArray(
+    record.bindings,
+    'desiredState.bindings',
+    coreMailContractLimits.maximumBindings,
+  ).map((entryArg, indexArg) =>
+    normalizeBinding(entryArg, `desiredState.bindings[${indexArg}]`),
+  );
+  const bindingIds = new Set<string>();
+  const activeInboundRecipients = new Set<string>();
+  for (const binding of bindings) {
+    if (bindingIds.has(binding.bindingId)) {
+      fail('desiredState.bindings contains a duplicate bindingId');
+    }
+    bindingIds.add(binding.bindingId);
+    if (binding.state === 'active') {
+      for (const recipient of binding.inboundRecipients) {
+        if (activeInboundRecipients.has(recipient)) {
+          fail('active inbound recipient ownership must be unique');
+        }
+        activeInboundRecipients.add(recipient);
+      }
+    }
+  }
+  bindings.sort((leftArg, rightArg) =>
+    compareStrings(leftArg.bindingId, rightArg.bindingId),
+  );
+  return deepFreezeValue({
+    schemaVersion: 1,
+    configEpoch: requireSafeInteger(record.configEpoch, 'desiredState.configEpoch', 1),
+    bindings,
+    gateway: normalizeGateway(record.gateway, 'desiredState.gateway'),
+  });
+};
+
+export const canonicalizeCoreMailDesiredState = (
+  valueArg: unknown,
+): string => {
+  return canonicalizeStrictJson(
+    normalizeCoreMailDesiredState(valueArg),
+    fail,
+    'CoreMail desired state',
+  );
+};
+
+export const createCoreMailDesiredStateDigest = async (
+  valueArg: unknown,
+): Promise<TCoreMailSha256> => {
+  const digestHex = await createCanonicalJsonSha256Hex(
+    canonicalizeCoreMailDesiredState(valueArg),
+    fail,
+  );
+  return `sha256:${digestHex}` as TCoreMailSha256;
+};
+
+export const verifyCoreMailDesiredStateDigest = async (
+  valueArg: unknown,
+  digestArg: unknown,
+): Promise<boolean> => {
+  return normalizeCoreMailSha256(digestArg, 'desiredStateDigest')
+    === await createCoreMailDesiredStateDigest(valueArg);
+};
+
+export const normalizeCoreMailControlBootstrap = (
+  valueArg: unknown,
+): ICoreMailControlBootstrap => {
+  const record = readRecord(valueArg, 'controlBootstrap');
+  assertKeys(
+    record,
+    'controlBootstrap',
+    ['schemaVersion', 'coreMailServiceId', 'credentials'],
+  );
+  if (record.schemaVersion !== 1) {
+    fail('controlBootstrap.schemaVersion must be 1');
+  }
+  return deepFreezeValue({
+    schemaVersion: 1,
+    coreMailServiceId: requireIdentifier(
+      record.coreMailServiceId,
+      'controlBootstrap.coreMailServiceId',
+    ),
+    credentials: normalizeCredentialSet(
+      record.credentials,
+      'controlBootstrap.credentials',
+    ),
+  });
+};
+
+export const normalizeCoreMailGatewayPeerDesiredState = (
+  valueArg: unknown,
+): ICoreMailGatewayPeerDesiredState => {
+  const record = readRecord(valueArg, 'gatewayPeer');
+  assertKeys(
+    record,
+    'gatewayPeer',
+    ['schemaVersion', 'coreMailServiceId', 'transferOrigin', 'credentials'],
+  );
+  if (record.schemaVersion !== 1) {
+    fail('gatewayPeer.schemaVersion must be 1');
+  }
+  return deepFreezeValue({
+    schemaVersion: 1,
+    coreMailServiceId: requireIdentifier(
+      record.coreMailServiceId,
+      'gatewayPeer.coreMailServiceId',
+    ),
+    transferOrigin: requireCanonicalUrl(
+      record.transferOrigin,
+      'gatewayPeer.transferOrigin',
+      'https:',
+      true,
+    ),
+    credentials: normalizeCredentialSet(
+      record.credentials,
+      'gatewayPeer.credentials',
+    ),
+  });
+};