@serve.zone/interfaces 20.2.0 → 21.1.0

package/ts/data/coremail.ts

@@ -12,6 +12,7 @@ export type TCoreMailSha256 = `sha256:${string}`;
 export type TCoreMailCapability = 'outbound' | 'inbound';
 export type TCoreMailBindingState = 'active' | 'disabled';
 export type TCoreMailCredentialState = 'current' | 'retiring';
+export type TCoreMailCredentialVerifierFormat = 'argon2id-v1';
 export type TCoreMailPartKind = 'text' | 'html' | 'attachment';
 export type TCoreMailTransferMethod = 'PUT' | 'GET';
 export type TCoreMailSubmissionState =
@@ -163,6 +164,8 @@ export interface ICoreMailBindingCredentialVerifier {
   credentialId: string;
   version: number;
   state: TCoreMailCredentialState;
+  /** Versioned verifier contract. CoreMail currently accepts only argon2id-v1. */
+  format: TCoreMailCredentialVerifierFormat;
   /** Password-verifier string only. Plaintext credential material is never part of desired state. */
   verificationHash: string;
   acceptUntil?: number;
@@ -195,6 +198,28 @@ export interface ICoreMailGatewayDesiredState {
   credentialSecretKey: string;
 }
 
+/**
+ * Bootstrap authority installed in CoreMail before Coreflow can reconcile
+ * ordinary desired state. The verifier payload is safe to deliver as runtime
+ * configuration; the matching plaintext is delivered only to Coreflow.
+ */
+export interface ICoreMailControlBootstrap {
+  schemaVersion: 1;
+  coreMailServiceId: string;
+  credentials: ICoreMailBindingCredentialVerifier[];
+}
+
+/**
+ * dcrouter-owned desired state for one authenticated CoreMail gateway peer.
+ * transferOrigin is authoritative control-plane data, never peer supplied.
+ */
+export interface ICoreMailGatewayPeerDesiredState {
+  schemaVersion: 1;
+  coreMailServiceId: string;
+  transferOrigin: string;
+  credentials: ICoreMailBindingCredentialVerifier[];
+}
+
 export interface ICoreMailDesiredState {
   schemaVersion: 1;
   configEpoch: number;
@@ -275,3 +300,19 @@ export const coreMailLimits = Object.freeze({
   transferIdleTimeoutMs: 15 * 1000,
   transferOverallTimeoutMs: 2 * 60 * 1000,
 } as const);
+
+export const coreMailCredentialVerifierPolicy = Object.freeze({
+  format: 'argon2id-v1' as const,
+  version: 19,
+  memoryCost: 65_536,
+  timeCost: 3,
+  parallelism: 1,
+  saltLengthBytes: 16,
+  hashLengthBytes: 32,
+} as const);
+
+export const coreMailRuntimeKeys = Object.freeze({
+  controlBootstrap: 'COREMAIL_CONTROL_BOOTSTRAP',
+  controlCredentialSecret: 'COREMAIL_CONTROL_CREDENTIAL_SECRET',
+  gatewayCredentialSecret: 'COREMAIL_GATEWAY_CREDENTIAL',
+} as const);

package/ts/data/index.ts

@@ -2,6 +2,7 @@ export * from './cloudlyconfig.js';
 export * from './cluster.js';
 export * from './config.js';
 export * from './coremail.js';
+export * from './coremail.runtime.js';
 export * from './deployment.js';
 export * from './deploymentadoption.js';
 export * from './deploymentoperation.js';

package/ts/requests/coremail.ts

@@ -242,6 +242,8 @@ export interface IReq_CoreMailGatewayAuthenticate extends plugins.typedrequestIn
   response: {
     authenticated: true;
     credentialVersion: number;
+    /** dcrouter's authoritative, control-plane-bound origin for CoreMail transfer paths. */
+    coreMailTransferOrigin: string;
   };
 }
 

package/ts/requests/status.ts

@@ -2,6 +2,16 @@ import * as plugins from '../plugins.js';
 import * as serviceInterfaces from '../data/service.js';
 import * as userInterfaces from '../data/user.js';
 
+type TReportReconciliationRolloutIdentity =
+  | {
+      rolloutId: string;
+      rolloutGeneration: number;
+    }
+  | {
+      rolloutId?: never;
+      rolloutGeneration?: never;
+    };
+
 /**
  * a status update dashboard
  */
@@ -23,17 +33,19 @@ export interface IRequest_Coreflow_Cloudly_ReportReconciliationStatus
     IRequest_Coreflow_Cloudly_ReportReconciliationStatus
   > {
   method: 'reportReconciliationStatus';
-  request: {
-    identity: userInterfaces.IIdentity;
-    serviceId: string;
-    serviceName?: string;
-    stage: string;
-    stageKey?: string;
-    status: serviceInterfaces.TServiceReconciliationStatus;
-    domainName?: string;
-    message?: string;
-    errorText?: string;
-    reportedAt?: number;
-  };
+  request:
+    & {
+      identity: userInterfaces.IIdentity;
+      serviceId: string;
+      serviceName?: string;
+      stage: string;
+      stageKey?: string;
+      status: serviceInterfaces.TServiceReconciliationStatus;
+      domainName?: string;
+      message?: string;
+      errorText?: string;
+      reportedAt?: number;
+    }
+    & TReportReconciliationRolloutIdentity;
   response: {};
 }