@serve.zone/interfaces 20.0.0 → 20.2.0

package/ts/private/canonicaljson.ts

@@ -0,0 +1,221 @@
+export const strictCanonicalJsonRules = Object.freeze({
+  version: 1 as const,
+  encoding: 'utf-8' as const,
+  objectKeyOrdering: 'utf-16-code-unit-ascending' as const,
+  arrayOrdering: 'preserved-dense' as const,
+  unicodeNormalization: 'preserved' as const,
+  numberEncoding: 'safe-integer-json-no-negative-zero' as const,
+  digest: 'sha256-lowercase-hex' as const,
+});
+
+export type TCanonicalJsonFailure = (reasonArg: string) => never;
+
+const assertUnicodeScalarString = (
+  valueArg: string,
+  fieldNameArg: string,
+  failArg: TCanonicalJsonFailure,
+): void => {
+  for (let index = 0; index < valueArg.length; index++) {
+    const codeUnit = valueArg.charCodeAt(index);
+    if (codeUnit >= 0xd800 && codeUnit <= 0xdbff) {
+      const followingCodeUnit = valueArg.charCodeAt(index + 1);
+      if (
+        !Number.isInteger(followingCodeUnit) ||
+        followingCodeUnit < 0xdc00 ||
+        followingCodeUnit > 0xdfff
+      ) {
+        failArg(`${fieldNameArg} must not contain an unpaired UTF-16 surrogate`);
+      }
+      index++;
+      continue;
+    }
+    if (codeUnit >= 0xdc00 && codeUnit <= 0xdfff) {
+      failArg(`${fieldNameArg} must not contain an unpaired UTF-16 surrogate`);
+    }
+  }
+};
+
+const readStrictRecord = (
+  valueArg: object,
+  fieldNameArg: string,
+  failArg: TCanonicalJsonFailure,
+): Record<string, unknown> => {
+  const prototype = Object.getPrototypeOf(valueArg);
+  if (prototype !== Object.prototype && prototype !== null) {
+    return failArg(`${fieldNameArg} must be a plain object`);
+  }
+  const record = valueArg as Record<string, unknown>;
+  const ownKeys = Reflect.ownKeys(record);
+  if (ownKeys.some((keyArg) => typeof keyArg !== 'string')) {
+    return failArg(`${fieldNameArg} must not contain symbol keys`);
+  }
+  for (const key of ownKeys as string[]) {
+    const descriptor = Object.getOwnPropertyDescriptor(record, key);
+    if (
+      !descriptor ||
+      !descriptor.enumerable ||
+      !Object.hasOwn(descriptor, 'value')
+    ) {
+      return failArg(
+        `${fieldNameArg} must contain enumerable data properties only`,
+      );
+    }
+  }
+  return record;
+};
+
+const readStrictArray = (
+  valueArg: unknown[],
+  fieldNameArg: string,
+  failArg: TCanonicalJsonFailure,
+): unknown[] => {
+  if (Object.getPrototypeOf(valueArg) !== Array.prototype) {
+    return failArg(`${fieldNameArg} must be a dense plain array`);
+  }
+  for (let index = 0; index < valueArg.length; index++) {
+    if (!Object.hasOwn(valueArg, index)) {
+      return failArg(`${fieldNameArg} must not contain sparse entries`);
+    }
+    const descriptor = Object.getOwnPropertyDescriptor(valueArg, String(index));
+    if (
+      !descriptor ||
+      !descriptor.enumerable ||
+      !Object.hasOwn(descriptor, 'value')
+    ) {
+      return failArg(`${fieldNameArg} must contain enumerable data entries only`);
+    }
+  }
+  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
+    ) {
+      return failArg(`${fieldNameArg} must not contain extra properties`);
+    }
+  }
+  return valueArg;
+};
+
+export const canonicalizeStrictJson = (
+  valueArg: unknown,
+  failArg: TCanonicalJsonFailure,
+  fieldNameArg = 'canonical JSON input',
+): string => {
+  const ancestors = new Set<object>();
+
+  const visit = (currentValueArg: unknown, currentFieldNameArg: string): string => {
+    if (currentValueArg === null) {
+      return 'null';
+    }
+    if (typeof currentValueArg === 'boolean') {
+      return currentValueArg ? 'true' : 'false';
+    }
+    if (typeof currentValueArg === 'string') {
+      assertUnicodeScalarString(currentValueArg, currentFieldNameArg, failArg);
+      return JSON.stringify(currentValueArg);
+    }
+    if (typeof currentValueArg === 'number') {
+      if (
+        !Number.isSafeInteger(currentValueArg) ||
+        Object.is(currentValueArg, -0)
+      ) {
+        return failArg(`${currentFieldNameArg} must contain safe integers only`);
+      }
+      return String(currentValueArg);
+    }
+    if (!currentValueArg || typeof currentValueArg !== 'object') {
+      return failArg(`${currentFieldNameArg} contains a non-JSON value`);
+    }
+    if (ancestors.has(currentValueArg)) {
+      return failArg(`${currentFieldNameArg} contains a cycle`);
+    }
+
+    ancestors.add(currentValueArg);
+    try {
+      if (Array.isArray(currentValueArg)) {
+        const array = readStrictArray(
+          currentValueArg,
+          currentFieldNameArg,
+          failArg,
+        );
+        return `[${array
+          .map((entryArg, indexArg) =>
+            visit(entryArg, `${currentFieldNameArg}[${indexArg}]`),
+          )
+          .join(',')}]`;
+      }
+
+      const record = readStrictRecord(
+        currentValueArg,
+        currentFieldNameArg,
+        failArg,
+      );
+      const keys = Object.keys(record).sort((leftArg, rightArg) => {
+        return leftArg < rightArg ? -1 : leftArg > rightArg ? 1 : 0;
+      });
+      return `{${keys
+        .map((keyArg) => {
+          assertUnicodeScalarString(
+            keyArg,
+            `${currentFieldNameArg} key`,
+            failArg,
+          );
+          return `${JSON.stringify(keyArg)}:${visit(
+            record[keyArg],
+            `${currentFieldNameArg}.${keyArg}`,
+          )}`;
+        })
+        .join(',')}}`;
+    } finally {
+      ancestors.delete(currentValueArg);
+    }
+  };
+
+  return visit(valueArg, fieldNameArg);
+};
+
+export const createSha256Hex = async (
+  contentsArg: Uint8Array,
+  failArg: TCanonicalJsonFailure,
+): Promise<string> => {
+  const subtle = globalThis.crypto?.subtle;
+  if (!subtle) {
+    return failArg('Web Crypto SHA-256 is unavailable in this runtime');
+  }
+  const digest = await subtle.digest('SHA-256', new Uint8Array(contentsArg));
+  return Array.from(new Uint8Array(digest), (byteArg) =>
+    byteArg.toString(16).padStart(2, '0'),
+  ).join('');
+};
+
+export const createCanonicalJsonSha256Hex = async (
+  canonicalJsonArg: string,
+  failArg: TCanonicalJsonFailure,
+): Promise<string> => {
+  return createSha256Hex(new TextEncoder().encode(canonicalJsonArg), failArg);
+};
+
+export const deepFreezeValue = <T>(
+  valueArg: T,
+  seenArg = new WeakSet<object>(),
+): T => {
+  if (!valueArg || typeof valueArg !== 'object') {
+    return valueArg;
+  }
+  const object = valueArg as object;
+  if (ArrayBuffer.isView(object) || seenArg.has(object)) {
+    return valueArg;
+  }
+  seenArg.add(object);
+  for (const key of Reflect.ownKeys(object)) {
+    const descriptor = Object.getOwnPropertyDescriptor(object, key);
+    if (descriptor && Object.hasOwn(descriptor, 'value')) {
+      deepFreezeValue(descriptor.value, seenArg);
+    }
+  }
+  return Object.freeze(valueArg);
+};

package/ts/requests/coremail.ts

@@ -0,0 +1,346 @@
+import type * as plugins from '../plugins.js';
+import type {
+  ICoreMailEnvelope,
+  ICoreMailDownloadGrant,
+  ICoreMailGatewayMessageDescriptor,
+  ICoreMailGatewayOutboundStatus,
+  ICoreMailInboundDelivery,
+  ICoreMailOutboundMessageDescriptor,
+  ICoreMailRecipientResolution,
+  ICoreMailReconciliationStatus,
+  ICoreMailReplicaIdentity,
+  ICoreMailSubmission,
+  ICoreMailUploadGrant,
+  TCoreMailInboundAckOutcome,
+  TCoreMailSha256,
+} from '../data/coremail.js';
+import type { IMailConnectionInfo } from '../data/mail.js';
+
+export interface IReq_CoreMailAuthenticateWorkload extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CoreMailAuthenticateWorkload
+> {
+  method: 'coreMailAuthenticateWorkload';
+  request: {
+    bindingId: string;
+    credentialId: string;
+    credentialVersion: number;
+    credentialSecret: string;
+  };
+  response: {
+    authenticated: true;
+    credentialVersion: number;
+    capabilities: Array<'outbound' | 'inbound'>;
+  };
+}
+
+export interface IReq_CoreMailPrepareOutboundSubmission extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CoreMailPrepareOutboundSubmission
+> {
+  method: 'coreMailPrepareOutboundSubmission';
+  request: {
+    /** Required replay key. Authority is added by the authenticated server session. */
+    idempotencyKey: string;
+    message: ICoreMailOutboundMessageDescriptor;
+  };
+  response: {
+    submission: ICoreMailSubmission;
+    replayed: boolean;
+  };
+}
+
+export interface IReq_CoreMailPrepareOutboundPartUpload extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CoreMailPrepareOutboundPartUpload
+> {
+  method: 'coreMailPrepareOutboundPartUpload';
+  request: {
+    submissionId: string;
+    partId: string;
+  };
+  response: {
+    grant: ICoreMailUploadGrant;
+  };
+}
+
+export interface IReq_CoreMailCompleteOutboundPartUpload extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CoreMailCompleteOutboundPartUpload
+> {
+  method: 'coreMailCompleteOutboundPartUpload';
+  request: {
+    submissionId: string;
+    partId: string;
+    grantId: string;
+    sha256: TCoreMailSha256;
+    lengthBytes: number;
+  };
+  response: {
+    submission: ICoreMailSubmission;
+  };
+}
+
+export interface IReq_CoreMailFinalizeOutboundSubmission extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CoreMailFinalizeOutboundSubmission
+> {
+  method: 'coreMailFinalizeOutboundSubmission';
+  request: {
+    submissionId: string;
+  };
+  response: {
+    submission: ICoreMailSubmission;
+  };
+}
+
+export interface IReq_CoreMailGetOutboundSubmission extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CoreMailGetOutboundSubmission
+> {
+  method: 'coreMailGetOutboundSubmission';
+  request: {
+    submissionId: string;
+  };
+  response: {
+    submission: ICoreMailSubmission;
+  };
+}
+
+export interface IReq_CoreMailListInboundDeliveries extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CoreMailListInboundDeliveries
+> {
+  method: 'coreMailListInboundDeliveries';
+  request: {
+    afterDeliveryId?: string;
+    limit: number;
+  };
+  response: {
+    deliveries: ICoreMailInboundDelivery[];
+  };
+}
+
+export interface IReq_CoreMailPrepareInboundFetch extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CoreMailPrepareInboundFetch
+> {
+  method: 'coreMailPrepareInboundFetch';
+  request: {
+    deliveryId: string;
+  };
+  response: {
+    grant: ICoreMailDownloadGrant;
+  };
+}
+
+export interface IReq_CoreMailCompleteInboundFetch extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CoreMailCompleteInboundFetch
+> {
+  method: 'coreMailCompleteInboundFetch';
+  request: {
+    deliveryId: string;
+    grantId: string;
+    sha256: TCoreMailSha256;
+    lengthBytes: number;
+  };
+  response: {
+    delivery: ICoreMailInboundDelivery;
+  };
+}
+
+export interface IReq_CoreMailAcknowledgeInboundDelivery extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CoreMailAcknowledgeInboundDelivery
+> {
+  method: 'coreMailAcknowledgeInboundDelivery';
+  request: {
+    deliveryId: string;
+    outcome: TCoreMailInboundAckOutcome;
+  };
+  response: {
+    delivery: ICoreMailInboundDelivery;
+    replayed: boolean;
+  };
+}
+
+export interface IReq_CoreMailAuthenticateControl extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CoreMailAuthenticateControl
+> {
+  method: 'coreMailAuthenticateControl';
+  request: {
+    credentialId: string;
+    credentialVersion: number;
+    credentialSecret: string;
+  };
+  response: {
+    authenticated: true;
+    replica: ICoreMailReplicaIdentity;
+  };
+}
+
+export interface IReq_CoreMailPrepareDesiredStateUpload extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CoreMailPrepareDesiredStateUpload
+> {
+  method: 'coreMailPrepareDesiredStateUpload';
+  request: {
+    expectedAppliedConfigEpoch: number;
+    configEpoch: number;
+    desiredStateDigest: TCoreMailSha256;
+    lengthBytes: number;
+  };
+  response: {
+    reconciliationId: string;
+    grant: ICoreMailUploadGrant;
+    replayed: boolean;
+  };
+}
+
+export interface IReq_CoreMailApplyDesiredState extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CoreMailApplyDesiredState
+> {
+  method: 'coreMailApplyDesiredState';
+  request: {
+    reconciliationId: string;
+    grantId: string;
+    desiredStateDigest: TCoreMailSha256;
+    lengthBytes: number;
+  };
+  response: {
+    status: ICoreMailReconciliationStatus;
+  };
+}
+
+export interface IReq_CoreMailGetReconciliationStatus extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CoreMailGetReconciliationStatus
+> {
+  method: 'coreMailGetReconciliationStatus';
+  request: {
+    configEpoch: number;
+    desiredStateDigest: TCoreMailSha256;
+  };
+  response: {
+    status: ICoreMailReconciliationStatus;
+  };
+}
+
+export interface IReq_CoreMailGatewayAuthenticate extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CoreMailGatewayAuthenticate
+> {
+  method: 'coreMailGatewayAuthenticate';
+  request: {
+    credentialId: string;
+    credentialVersion: number;
+    credentialSecret: string;
+  };
+  response: {
+    authenticated: true;
+    credentialVersion: number;
+  };
+}
+
+export interface IReq_CoreMailGatewayResolveRecipients extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CoreMailGatewayResolveRecipients
+> {
+  method: 'coreMailGatewayResolveRecipients';
+  request: {
+    envelope: ICoreMailEnvelope;
+    recipients: string[];
+    source: IMailConnectionInfo;
+  };
+  response: {
+    resolutions: ICoreMailRecipientResolution[];
+  };
+}
+
+export interface IReq_CoreMailGatewayPrepareInboundHandoff extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CoreMailGatewayPrepareInboundHandoff
+> {
+  method: 'coreMailGatewayPrepareInboundHandoff';
+  request: {
+    transportDeliveryId: string;
+    routingHandles: string[];
+    message: ICoreMailGatewayMessageDescriptor;
+    source: IMailConnectionInfo;
+  };
+  response: {
+    handoffId: string;
+    grant?: ICoreMailUploadGrant;
+    replayed: boolean;
+  };
+}
+
+export interface IReq_CoreMailGatewayCompleteInboundHandoff extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CoreMailGatewayCompleteInboundHandoff
+> {
+  method: 'coreMailGatewayCompleteInboundHandoff';
+  request: {
+    handoffId: string;
+    grantId: string;
+    sha256: TCoreMailSha256;
+    lengthBytes: number;
+  };
+  response: {
+    accepted: true;
+    deliveryIds: string[];
+    replayed: boolean;
+  };
+}
+
+export interface IReq_CoreMailGatewayPrepareOutboundHandoff extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CoreMailGatewayPrepareOutboundHandoff
+> {
+  method: 'coreMailGatewayPrepareOutboundHandoff';
+  request: {
+    transportSubmissionId: string;
+    submissionDigest: TCoreMailSha256;
+    message: ICoreMailGatewayMessageDescriptor;
+    /** CoreMail-issued GET grant. dcrouter resolves the path against the authenticated peer. */
+    grant: ICoreMailDownloadGrant;
+  };
+  response: {
+    transportMessageId: string;
+    status: ICoreMailGatewayOutboundStatus;
+    replayed: boolean;
+  };
+}
+
+export interface IReq_CoreMailGatewayCompleteOutboundHandoff extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CoreMailGatewayCompleteOutboundHandoff
+> {
+  method: 'coreMailGatewayCompleteOutboundHandoff';
+  request: {
+    transportMessageId: string;
+    grantId: string;
+    sha256: TCoreMailSha256;
+    lengthBytes: number;
+  };
+  response: {
+    status: ICoreMailGatewayOutboundStatus;
+    replayed: boolean;
+  };
+}
+
+export interface IReq_CoreMailGatewayGetOutboundStatus extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CoreMailGatewayGetOutboundStatus
+> {
+  method: 'coreMailGatewayGetOutboundStatus';
+  request: {
+    transportMessageId: string;
+  };
+  response: {
+    status: ICoreMailGatewayOutboundStatus;
+  };
+}

package/ts/requests/index.ts

@@ -8,6 +8,7 @@ import * as backupRequests from './backup.js';
 import * as certificateRequests from './certificate.js';
 import * as clusterRequests from './cluster.js';
 import * as configRequests from './config.js';
+import * as coreMailRequests from './coremail.js';
 import * as corestoreRequests from './corestore.js';
 import * as deploymentRequests from './deployment.js';
 import * as dnsRequests from './dns.js';
@@ -45,6 +46,7 @@ export {
   certificateRequests as certificate,
   clusterRequests as cluster,
   configRequests as config,
+  coreMailRequests as coremail,
   corestoreRequests as corestore,
   deploymentRequests as deployment,
   dnsRequests as dns,