@serve.zone/interfaces 21.1.0 → 23.0.0

package/ts/data/coremail.ts

@@ -10,7 +10,7 @@
 export type TCoreMailSha256 = `sha256:${string}`;
 
 export type TCoreMailCapability = 'outbound' | 'inbound';
-export type TCoreMailBindingState = 'active' | 'disabled';
+export type TCoreMailBindingState = 'active' | 'draining' | 'disabled';
 export type TCoreMailCredentialState = 'current' | 'retiring';
 export type TCoreMailCredentialVerifierFormat = 'argon2id-v1';
 export type TCoreMailPartKind = 'text' | 'html' | 'attachment';
@@ -30,6 +30,16 @@ export type TCoreMailInboundDeliveryState = 'pending' | 'fetching' | 'fetched' |
 export type TCoreMailInboundAckOutcome = 'processed' | 'discarded';
 export type TCoreMailRecipientAction = 'accept' | 'reject' | 'defer';
 export type TCoreMailReconciliationState = 'applying' | 'ready' | 'failed';
+export type TCoreMailWorkloadOperation =
+  | 'coreMailPrepareOutboundSubmission'
+  | 'coreMailPrepareOutboundPartUpload'
+  | 'coreMailCompleteOutboundPartUpload'
+  | 'coreMailFinalizeOutboundSubmission'
+  | 'coreMailGetOutboundSubmission'
+  | 'coreMailListInboundDeliveries'
+  | 'coreMailPrepareInboundFetch'
+  | 'coreMailCompleteInboundFetch'
+  | 'coreMailAcknowledgeInboundDelivery';
 
 export type TCoreMailErrorCode =
   | 'AUTHENTICATION_FAILED'
@@ -43,6 +53,7 @@ export type TCoreMailErrorCode =
   | 'INVALID_RECIPIENT'
   | 'INVALID_HEADER'
   | 'PAYLOAD_LIMIT_EXCEEDED'
+  | 'QUOTA_EXCEEDED'
   | 'IDEMPOTENCY_CONFLICT'
   | 'STATE_CONFLICT'
   | 'TRANSFER_GRANT_EXPIRED'
@@ -52,6 +63,9 @@ export type TCoreMailErrorCode =
   | 'TRANSFER_ENCODING_UNSUPPORTED'
   | 'OBJECT_INTEGRITY_CONFLICT'
   | 'DELIVERY_NOT_FETCHED'
+  | 'DELIVERY_DEFERRED'
+  | 'DELIVERY_FAILED'
+  | 'DELIVERY_DEAD_LETTERED'
   | 'GATEWAY_UNAVAILABLE'
   | 'RECONCILIATION_FENCE_MISMATCH';
 
@@ -111,6 +125,7 @@ export interface ICoreMailTransferGrant {
   sha256: TCoreMailSha256;
   lengthBytes: number;
   contentType: string;
+  issuedAt: number;
   expiresAt: number;
 }
 
@@ -138,8 +153,10 @@ export interface ICoreMailSubmission {
   transportMessageId?: string;
   attempts: number;
   nextAttemptAt?: number;
+  error?: ICoreMailErrorData;
   acceptedAt?: number;
   deliveredAt?: number;
+  terminalAt?: number;
   createdAt: number;
   updatedAt: number;
 }
@@ -158,6 +175,13 @@ export interface ICoreMailInboundDelivery {
   subject?: string;
   receivedAt: number;
   updatedAt: number;
+  acknowledgedAt?: number;
+  acknowledgedOutcome?: TCoreMailInboundAckOutcome;
+}
+
+export interface ICoreMailInboundDeliveryPage {
+  deliveries: ICoreMailInboundDelivery[];
+  nextCursor?: string;
 }
 
 export interface ICoreMailBindingCredentialVerifier {
@@ -172,7 +196,7 @@ export interface ICoreMailBindingCredentialVerifier {
 }
 
 export interface ICoreMailBindingDesiredState {
-  schemaVersion: 1;
+  schemaVersion: 2;
   bindingId: string;
   serviceId: string;
   tenantId: string;
@@ -183,15 +207,17 @@ export interface ICoreMailBindingDesiredState {
   allowedSenders: string[];
   inboundRecipients: string[];
   defaultSender?: string;
-  limits?: {
-    messagesPerMinute?: number;
-    messagesPerDay?: number;
-    maxPendingInbound?: number;
+  limits: {
+    messagesPerMinute: number;
+    messagesPerDay: number;
+    maxPendingInbound: number;
   };
 }
 
 export interface ICoreMailGatewayDesiredState {
   endpointUrl: string;
+  /** Canonical CoreMail HTTPS origin authorized for path-only transfer grants. */
+  coreMailTransferOrigin: string;
   credentialId: string;
   credentialVersion: number;
   /** Key in CoreMail's resolved runtime secret material, never a plaintext value. */
@@ -220,11 +246,21 @@ export interface ICoreMailGatewayPeerDesiredState {
   credentials: ICoreMailBindingCredentialVerifier[];
 }
 
+export interface ICoreMailRuntimeKeyReference {
+  keyId: string;
+  version: number;
+  state: TCoreMailCredentialState;
+  /** Key in CoreMail's resolved runtime secret material, never a plaintext value. */
+  secretKey: string;
+  acceptUntil?: number;
+}
+
 export interface ICoreMailDesiredState {
-  schemaVersion: 1;
+  schemaVersion: 2;
   configEpoch: number;
   bindings: ICoreMailBindingDesiredState[];
   gateway: ICoreMailGatewayDesiredState;
+  cursorKeys: ICoreMailRuntimeKeyReference[];
 }
 
 export interface ICoreMailReplicaIdentity {
@@ -239,7 +275,9 @@ export interface ICoreMailBindingReconciliationStatus {
   bindingId: string;
   revision: number;
   state: TCoreMailBindingState;
-  activeSessionsByCredentialVersion: Array<{
+  pendingInboundCount: number;
+  activeSessionsByCredential: Array<{
+    credentialId: string;
     version: number;
     count: number;
   }>;
@@ -281,7 +319,10 @@ export interface ICoreMailGatewayOutboundStatus {
   >;
   attempts: number;
   nextAttemptAt?: number;
+  error?: ICoreMailErrorData;
   smtpCode?: number;
+  deliveredAt?: number;
+  terminalAt?: number;
   updatedAt: number;
 }
 
@@ -295,12 +336,83 @@ export const coreMailLimits = Object.freeze({
   aggregateAttachmentBytes: 17 * 1024 * 1024,
   mimeFramingBytes: 512 * 1024,
   serializedMimeBytes: 30 * 1024 * 1024,
+  recipientCount: 100,
+  inboundPageSize: 100,
+  inboundPageBytes: 56 * 1024,
+  cursorBytes: 1_024,
+  cursorMinimumDecodedBytes: 32,
+  routingHandleTtlMs: 5 * 60 * 1000,
   transferGrantTtlMs: 5 * 60 * 1000,
   transferHeaderTimeoutMs: 10 * 1000,
   transferIdleTimeoutMs: 15 * 1000,
   transferOverallTimeoutMs: 2 * 60 * 1000,
 } as const);
 
+export const coreMailTransferTokenPolicy = Object.freeze({
+  format: 'base64url-256' as const,
+  decodedBytes: 32,
+  encodedCharacters: 43,
+});
+
+export const coreMailWorkloadOperationPolicy = Object.freeze({
+  active: Object.freeze({
+    outbound: Object.freeze([
+      'coreMailPrepareOutboundSubmission',
+      'coreMailPrepareOutboundPartUpload',
+      'coreMailCompleteOutboundPartUpload',
+      'coreMailFinalizeOutboundSubmission',
+      'coreMailGetOutboundSubmission',
+    ] satisfies TCoreMailWorkloadOperation[]),
+    inbound: Object.freeze([
+      'coreMailListInboundDeliveries',
+      'coreMailPrepareInboundFetch',
+      'coreMailCompleteInboundFetch',
+      'coreMailAcknowledgeInboundDelivery',
+    ] satisfies TCoreMailWorkloadOperation[]),
+  }),
+  draining: Object.freeze({
+    outbound: Object.freeze([
+      'coreMailGetOutboundSubmission',
+    ] satisfies TCoreMailWorkloadOperation[]),
+    inbound: Object.freeze([
+      'coreMailListInboundDeliveries',
+      'coreMailPrepareInboundFetch',
+      'coreMailCompleteInboundFetch',
+      'coreMailAcknowledgeInboundDelivery',
+    ] satisfies TCoreMailWorkloadOperation[]),
+  }),
+  disabled: Object.freeze({
+    outbound: Object.freeze([] satisfies TCoreMailWorkloadOperation[]),
+    inbound: Object.freeze([] satisfies TCoreMailWorkloadOperation[]),
+  }),
+});
+
+export const coreMailRetentionPolicy = Object.freeze({
+  terminalOutboundMs: 30 * 24 * 60 * 60 * 1000,
+  acknowledgedInboundMs: 30 * 24 * 60 * 60 * 1000,
+  idempotencyReceiptMs: 30 * 24 * 60 * 60 * 1000,
+  expiredCapabilityMs: 24 * 60 * 60 * 1000,
+  pendingInboundAgePurge: false as const,
+});
+
+export const coreMailQuotaPolicy = Object.freeze({
+  windows: 'fixed-utc-minute-and-day' as const,
+  outboundUnit: 'first-durable-idempotency-insert' as const,
+  outboundReplayConsumesUnit: false as const,
+  pendingInboundStates: ['pending', 'fetching', 'fetched'] as const,
+  inboundAcknowledgementReleasesUnit: true as const,
+});
+
+export const coreMailTransferProtocol = Object.freeze({
+  pathPrefix: '/transfers/',
+  authorizationScheme: 'Bearer',
+  putSuccessStatus: 204,
+  getSuccessStatus: 200,
+  requireContentLength: true,
+  requireContentType: true,
+  integritySource: 'grant-metadata-and-completion' as const,
+});
+
 export const coreMailCredentialVerifierPolicy = Object.freeze({
   format: 'argon2id-v1' as const,
   version: 19,

package/ts/data/deploymentoperation.ts

@@ -3,7 +3,7 @@ import type { IGatewayRouteDnsResult } from './gateway.js';
 import type { IImageRolloutStatus, IImmutableImageDeploymentPlan, TSha256Digest } from './immutableimage.js';
 import { normalizeImmutableReleaseTag, normalizeSha256Digest } from './immutableimage.js';
 import type { IRegistryTarget } from './registry.js';
-import { normalizeServiceAbsolutePath, validateServiceContainerArgs, validateServiceSecretFiles } from './service.js';
+import { normalizeServiceAbsolutePath, validateServiceContainerArgs } from './service.js';
 import type { TServiceTargetPortRef } from './serviceports.js';
 
 export type TDeploymentOperationMode = 'existing-service' | 'greenfield';
@@ -162,10 +162,12 @@ export const validateDeploymentProposedConfiguration = (
     || configurationArg.projectName.length > 200) {
     errors.push('projectName must be bounded and non-empty');
   }
-  if (!validateStringArray(configurationArg.targetPlatforms, 8, (platformArg) => (
-    /^[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$/.test(platformArg)
-  ))) {
-    errors.push('targetPlatforms must be unique canonical platform identifiers');
+  if (!validateStringArray(configurationArg.targetPlatforms, 2, (platformArg) => (
+    platformArg === 'linux/amd64' || platformArg === 'linux/arm64'
+  )) || (configurationArg.targetPlatforms as string[]).length === 0
+    || JSON.stringify(configurationArg.targetPlatforms)
+      !== JSON.stringify([...(configurationArg.targetPlatforms as string[])].sort())) {
+    errors.push('targetPlatforms must be a sorted non-empty supported platform set');
   }
   if (!validateStringArray(configurationArg.publicDomains, 32, (domainArg) => (
     canonicalizeDeploymentHostname(domainArg) === domainArg
@@ -177,33 +179,7 @@ export const validateDeploymentProposedConfiguration = (
   ))) {
     errors.push('environmentVariableNames must be unique canonical names');
   }
-  if (!validateStringArray(configurationArg.secretReferenceIds, 64, (idArg) => (
-    idArg.length <= 253 && /^[A-Za-z0-9][A-Za-z0-9:._-]*$/.test(idArg)
-  ))) {
-    errors.push('secretReferenceIds must be unique canonical identifiers');
-  }
-  const volumeMountPaths = Array.isArray(configurationArg.volumeMounts)
-    ? configurationArg.volumeMounts.flatMap((mountArg) => (
-      isRecord(mountArg) && typeof mountArg.mountPath === 'string' ? [mountArg.mountPath] : []
-    ))
-    : [];
   errors.push(...validateServiceContainerArgs(configurationArg.containerArgs));
-  errors.push(...validateServiceSecretFiles(configurationArg.secretFiles, volumeMountPaths));
-  if (Array.isArray(configurationArg.secretFiles)
-    && Array.isArray(configurationArg.environmentVariableNames)) {
-    const publicEnvironmentNames = new Set(
-      configurationArg.environmentVariableNames.filter((nameArg): nameArg is string => (
-        typeof nameArg === 'string'
-      )),
-    );
-    if (configurationArg.secretFiles.some((fileArg) => (
-      isRecord(fileArg)
-      && typeof fileArg.sourceKey === 'string'
-      && publicEnvironmentNames.has(fileArg.sourceKey)
-    ))) {
-      errors.push('secretFiles source keys must not be declared as environment variables');
-    }
-  }
   if (!Array.isArray(configurationArg.containerPorts)
     || configurationArg.containerPorts.length > 64
     || configurationArg.containerPorts.some((portArg) => !Number.isSafeInteger(portArg)

package/ts/data/deploymentpreflight.ts

@@ -1,10 +1,10 @@
 import type {
+  TImmutableContainerPlatform,
   TOciManifestMediaType,
   TSha256Digest,
 } from './immutableimage.js';
 import { normalizeImmutableReleaseTag, normalizeSha256Digest } from './immutableimage.js';
 import type { TServiceDeploymentCapability } from './user.js';
-import type { IServiceSecretFile } from './service.js';
 import type {
   IDeploymentRouteRequest,
   IServiceDeploymentOperation,
@@ -145,14 +145,11 @@ export interface IDeploymentPreflightProposedConfiguration {
   schemaVersion: 1;
   declarationComplete: boolean;
   projectName: string;
-  targetPlatforms: string[];
+  targetPlatforms: TImmutableContainerPlatform[];
   publicDomains: string[];
   environmentVariableNames: string[];
-  secretReferenceIds: string[];
   /** Exact OCI/Docker argument vector appended after the image entrypoint. */
   containerArgs?: string[];
-  /** Secret-bundle keys that must be delivered only as Docker secret files. */
-  secretFiles?: IServiceSecretFile[];
   containerPorts: number[];
   volumeMounts: IDeploymentPreflightProposedVolumeMount[];
   requiredCapabilities: Array<'database' | 'objectstorage' | 'pushnotification'>;

package/ts/data/hostedapp.ts

@@ -2,6 +2,58 @@ export type THostedAppHostType = 'onebox' | 'cloudly' | string;
 
 export const hostedAppOidcRoleClaim = 'roles' as const;
 export const hostedAppOidcAppInstanceIdClaim = 'servezone_app_instance_id' as const;
+export const hostedAppMachineServiceIdClaim = 'servezone_service_id' as const;
+export const hostedAppMachineAudience = 'serve.zone/hosted-app-lifecycle' as const;
+
+export interface IHostedAppMachineClaims {
+  sub: string;
+  aud: typeof hostedAppMachineAudience;
+  iat: number;
+  exp: number;
+  [hostedAppOidcAppInstanceIdClaim]: string;
+  [hostedAppMachineServiceIdClaim]: string;
+}
+
+export const createHostedAppMachineSubject = (appInstanceIdArg: string): string => (
+  `urn:serve.zone:hosted-app:${appInstanceIdArg}`
+);
+
+export const validateHostedAppMachineClaims = (
+  claimsArg: unknown,
+  expectedArg: {
+    appInstanceId: string;
+    serviceId: string;
+    nowEpochSeconds?: number;
+  },
+): string[] => {
+  if (!claimsArg || typeof claimsArg !== 'object' || Array.isArray(claimsArg)) {
+    return ['hosted app machine claims must be an object'];
+  }
+  const claims = claimsArg as Record<string, unknown>;
+  const errors: string[] = [];
+  if (claims.sub !== createHostedAppMachineSubject(expectedArg.appInstanceId)) {
+    errors.push('hosted app machine subject does not match');
+  }
+  if (claims.aud !== hostedAppMachineAudience) {
+    errors.push('hosted app machine audience does not match');
+  }
+  if (claims[hostedAppOidcAppInstanceIdClaim] !== expectedArg.appInstanceId) {
+    errors.push('hosted app machine app instance does not match');
+  }
+  if (claims[hostedAppMachineServiceIdClaim] !== expectedArg.serviceId) {
+    errors.push('hosted app machine service does not match');
+  }
+  const now = expectedArg.nowEpochSeconds ?? Math.floor(Date.now() / 1000);
+  if (!Number.isSafeInteger(claims.iat) || (claims.iat as number) < 0
+    || (claims.iat as number) > now) {
+    errors.push('hosted app machine issued-at time is malformed');
+  }
+  if (!Number.isSafeInteger(claims.exp) || (claims.exp as number) <= now
+    || (Number.isSafeInteger(claims.iat) && (claims.exp as number) <= (claims.iat as number))) {
+    errors.push('hosted app machine expiry is malformed or expired');
+  }
+  return errors;
+};
 
 export interface IHostedAppRoleDefinition {
   /** Stable role identifier emitted in the hosted app's audience-scoped token. */
@@ -276,7 +328,7 @@ export type THostedAppRuntimeStatus =
   | 'stopped'
   | 'unknown';
 
-export type THostedAppBootstrapActionType = 'setupLink' | 'credentials' | 'message';
+export type THostedAppBootstrapActionType = 'setupRoute' | 'message';
 
 export type THostedAppBootstrapActionStatus =
   | 'requested'
@@ -293,21 +345,12 @@ export type THostedAppUpgradeStatus =
   | 'success'
   | 'failed';
 
-export interface IHostedAppRuntimeIdentity {
-  appInstanceId: string;
-  appControlToken: string;
-  hostType?: THostedAppHostType;
-}
-
-export interface IHostedAppBootstrapAction {
+interface IHostedAppBootstrapActionBase {
   id: string;
-  type: THostedAppBootstrapActionType;
+  /** Server-managed CAS revision incremented on every action transition. */
+  revision: number;
   status: THostedAppBootstrapActionStatus;
   label: string;
-  url?: string;
-  username?: string;
-  password?: string;
-  message?: string;
   expiresAt?: number;
   createdAt: number;
   updatedAt: number;
@@ -315,6 +358,18 @@ export interface IHostedAppBootstrapAction {
   dismissedAt?: number;
 }
 
+export type IHostedAppBootstrapAction =
+  | (IHostedAppBootstrapActionBase & {
+      type: 'setupRoute';
+      route: string;
+      message?: never;
+    })
+  | (IHostedAppBootstrapActionBase & {
+      type: 'message';
+      route?: never;
+      message: string;
+    });
+
 export interface IHostedAppUpgradeState {
   status: THostedAppUpgradeStatus;
   appTemplateId?: string;
@@ -347,9 +402,80 @@ export interface IHostedAppLifecycleState extends IHostedAppLifecycleReport {
   upgradeState?: IHostedAppUpgradeState;
 }
 
-export type IHostedAppBootstrapActionRequest = Omit<
-  IHostedAppBootstrapAction,
-  'id' | 'status' | 'createdAt' | 'updatedAt' | 'completedAt' | 'dismissedAt'
-> & {
-  id?: string;
+type THostedAppBootstrapActionServerFields =
+  | 'id'
+  | 'revision'
+  | 'status'
+  | 'createdAt'
+  | 'updatedAt'
+  | 'completedAt'
+  | 'dismissedAt';
+
+export type IHostedAppBootstrapActionRequest =
+  | (Omit<
+      Extract<IHostedAppBootstrapAction, { type: 'setupRoute' }>,
+      THostedAppBootstrapActionServerFields
+    > & { id?: string })
+  | (Omit<
+      Extract<IHostedAppBootstrapAction, { type: 'message' }>,
+      THostedAppBootstrapActionServerFields
+    > & { id?: string });
+
+export const normalizeHostedAppSetupRoute = (routeArg: unknown): string | undefined => {
+  if (typeof routeArg !== 'string'
+    || !routeArg.startsWith('/')
+    || routeArg.startsWith('//')
+    || /[\\?#\s]/.test(routeArg)
+    || /%5c/i.test(routeArg)) {
+    return undefined;
+  }
+  const parsed = new URL(routeArg, 'https://app.invalid');
+  return parsed.pathname === routeArg ? routeArg : undefined;
+};
+
+export const validateHostedAppBootstrapActionRequest = (
+  actionArg: unknown,
+): string[] => {
+  if (!actionArg || typeof actionArg !== 'object' || Array.isArray(actionArg)) {
+    return ['hosted app bootstrap action must be an object'];
+  }
+  const action = actionArg as Record<string, unknown>;
+  const errors: string[] = [];
+  const allowedKeys = action.type === 'setupRoute'
+    ? new Set(['id', 'type', 'label', 'route', 'expiresAt'])
+    : action.type === 'message'
+      ? new Set(['id', 'type', 'label', 'message', 'expiresAt'])
+      : new Set(['id', 'type', 'label', 'expiresAt']);
+  if (Object.keys(action).some((keyArg) => !allowedKeys.has(keyArg))) {
+    errors.push('hosted app bootstrap action contains fields outside its schema');
+  }
+  if (action.id !== undefined
+    && (typeof action.id !== 'string'
+      || !/^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/.test(action.id))) {
+    errors.push('hosted app bootstrap action id must be canonical');
+  }
+  if (action.expiresAt !== undefined
+    && (!Number.isSafeInteger(action.expiresAt) || (action.expiresAt as number) < 1)) {
+    errors.push('hosted app bootstrap action expiresAt must be a positive integer');
+  }
+  if (action.type !== 'setupRoute' && action.type !== 'message') {
+    errors.push('hosted app bootstrap action type is unsupported');
+  }
+  if (typeof action.label !== 'string' || !action.label.trim() || action.label.length > 200) {
+    errors.push('hosted app bootstrap action label must be bounded');
+  }
+  if (action.type === 'setupRoute') {
+    if (normalizeHostedAppSetupRoute(action.route) !== action.route) {
+      errors.push('hosted app setup route must be a canonical same-origin absolute path');
+    }
+    if ('message' in action) errors.push('hosted app setup route forbids message');
+  }
+  if (action.type === 'message') {
+    if (typeof action.message !== 'string' || !action.message.trim()
+      || action.message.length > 4000) {
+      errors.push('hosted app bootstrap message must be bounded');
+    }
+    if ('route' in action) errors.push('hosted app message forbids route');
+  }
+  return errors;
 };