@serve.zone/interfaces 22.0.0 → 23.0.1

package/ts/requests/secret.ts

@@ -1,4 +1,5 @@
 import type * as plugins from '../plugins.js';
+import * as secretData from '../data/secret.js';
 import type {
   IResolvedSecretManifestEntry,
   ISecretMetadata,
@@ -7,19 +8,27 @@ import type {
   ISecretSetMetadata,
   ISecretVersionMetadata,
   ISecretVersionRetentionReference,
+  TSecretIngressRecipient,
+  TSecretMutationTarget,
+  TSecretValueInput,
   TSecretDelivery,
   TSecretEnvironment,
 } from '../data/secret.js';
 import type { IIdentityCredential } from '../data/user.js';
 
-export type TSecretMutationTarget =
-  | { kind: 'service'; serviceId: string }
-  | { kind: 'secret-set'; secretSetId: string };
-
-export type TSecretValueInput =
-  | { mode: 'provided'; value: string }
-  /** Server-generated runtime-only value; plaintext is never returned. */
-  | { mode: 'generated'; bytes: 32 | 48 | 64 };
+export interface IReq_GetSecretIngressRecipient
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_GetSecretIngressRecipient
+> {
+  method: 'getSecretIngressRecipient';
+  request: {
+    identity: IIdentityCredential;
+  };
+  response: {
+    recipient: TSecretIngressRecipient;
+  };
+}
 
 export interface IReq_ListSecrets extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
@@ -28,6 +37,7 @@ export interface IReq_ListSecrets extends plugins.typedrequestInterfaces.impleme
   method: 'listSecrets';
   request: {
     identity: IIdentityCredential;
+    mutationId: string;
     target: TSecretMutationTarget;
     environment?: TSecretEnvironment;
   };
@@ -45,6 +55,7 @@ export interface IReq_GetSecretMetadata extends plugins.typedrequestInterfaces.i
   method: 'getSecretMetadata';
   request: {
     identity: IIdentityCredential;
+    mutationId: string;
     secretId: string;
   };
   response: {
@@ -60,6 +71,7 @@ export interface IReq_CreateSecret extends plugins.typedrequestInterfaces.implem
   method: 'createSecret';
   request: {
     identity: IIdentityCredential;
+    mutationId: string;
     target: TSecretMutationTarget;
     key: string;
     environment: TSecretEnvironment;
@@ -85,14 +97,18 @@ export interface IReq_RotateSecret extends plugins.typedrequestInterfaces.implem
   method: 'rotateSecret';
   request: {
     identity: IIdentityCredential;
+    mutationId: string;
     secretId: string;
     valueInput: TSecretValueInput;
     expectedSecretRevision: number;
-    expectedActiveVersionId?: string;
+    expectedActiveVersionId: string;
+    /** Aggregate owner fence incremented by every secret mutation. */
+    expectedTargetSecretsRevision: number;
   };
   response: {
     secret: ISecretMetadata;
     version: ISecretVersionMetadata;
+    targetSecretsRevision: number;
   };
 }
 
@@ -106,9 +122,11 @@ export interface IReq_ChangeSecretLifecycle extends plugins.typedrequestInterfac
     secretId: string;
     action: 'retire' | 'revoke' | 'delete' | 'request-purge';
     expectedSecretRevision: number;
+    expectedTargetSecretsRevision: number;
   };
   response: {
     secret: ISecretMetadata;
+    targetSecretsRevision: number;
   };
 }
 
@@ -187,6 +205,8 @@ extends plugins.typedrequestInterfaces.implementsTR<
     secretSetId: string;
     action: 'retire' | 'delete';
     expectedRevision: number;
+    /** Prevents lifecycle changes racing any secret mutation in this set. */
+    expectedSecretsRevision: number;
   };
   response: {
     secretSet: ISecretSetMetadata;
@@ -254,3 +274,178 @@ extends plugins.typedrequestInterfaces.implementsTR<
     collisions: ISecretResolutionPreviewCollision[];
   };
 }
+
+const isRecord = (valueArg: unknown): valueArg is Record<string, unknown> => (
+  Boolean(valueArg) && typeof valueArg === 'object' && !Array.isArray(valueArg)
+);
+
+export const validateCreateSecretRequest = async (
+  requestArg: unknown,
+  activeIngressRecipientArg: TSecretIngressRecipient,
+): Promise<string[]> => {
+  if (!requestArg || typeof requestArg !== 'object' || Array.isArray(requestArg)) {
+    return ['create secret request must be an object'];
+  }
+  const request = requestArg as Record<string, unknown>;
+  const errors = secretData.validateSecretMutationId(request.mutationId);
+  const allowedKeys = new Set([
+    'identity',
+    'mutationId',
+    'target',
+    'key',
+    'environment',
+    'name',
+    'description',
+    'tags',
+    'delivery',
+    'valueInput',
+    'expectedTargetSecretsRevision',
+  ]);
+  if (Object.keys(request).some((keyArg) => !allowedKeys.has(keyArg))) {
+    errors.push('create secret request contains fields outside its schema');
+  }
+  if (!request.identity || typeof request.identity !== 'object'
+    || typeof (request.identity as Record<string, unknown>).jwt !== 'string') {
+    errors.push('create secret identity must be a JWT credential');
+  }
+  if (!request.target || typeof request.target !== 'object' || Array.isArray(request.target)) {
+    errors.push('create secret target must be an owner object');
+  } else {
+    errors.push(...secretData.validateSecretOwner(request.target));
+  }
+  if (typeof request.key !== 'string' || !/^[A-Z_][A-Z0-9_]{0,252}$/.test(request.key)) {
+    errors.push('create secret key must be canonical');
+  }
+  if (typeof request.environment !== 'string'
+    || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(request.environment)) {
+    errors.push('create secret environment must be canonical');
+  }
+  if (typeof request.name !== 'string'
+    || request.name.trim() !== request.name
+    || request.name.length < 1
+    || request.name.length > 200) {
+    errors.push('create secret name must be a bounded non-empty string');
+  }
+  if (request.description !== undefined
+    && (typeof request.description !== 'string' || request.description.length > 2000)) {
+    errors.push('create secret description must be a bounded string');
+  }
+  if (request.tags !== undefined) {
+    if (!Array.isArray(request.tags) || request.tags.length > 64) {
+      errors.push('create secret tags must be a bounded array');
+    } else {
+      const tagKeys: string[] = [];
+      request.tags.forEach((tagArg, indexArg) => {
+        if (!isRecord(tagArg)
+          || JSON.stringify(Object.keys(tagArg).sort()) !== JSON.stringify(['key', 'value'])
+          || typeof tagArg.key !== 'string'
+          || tagArg.key.length < 1
+          || tagArg.key.length > 100
+          || typeof tagArg.value !== 'string'
+          || tagArg.value.length > 500) {
+          errors.push(`create secret tags[${indexArg}] must use the bounded key/value schema`);
+        } else {
+          tagKeys.push(tagArg.key);
+        }
+      });
+      if (new Set(tagKeys).size !== tagKeys.length) {
+        errors.push('create secret tag keys must be unique');
+      }
+    }
+  }
+  const deliveryErrors = secretData.validateSecretDelivery(request.delivery);
+  errors.push(...deliveryErrors);
+  if (!Number.isSafeInteger(request.expectedTargetSecretsRevision)
+    || (request.expectedTargetSecretsRevision as number) < 0) {
+    errors.push('create secret target revision must be a non-negative integer');
+  }
+  const canBuildContext = secretData.validateSecretMutationId(request.mutationId).length === 0
+    && secretData.validateSecretOwner(request.target).length === 0
+    && typeof request.key === 'string'
+    && /^[A-Z_][A-Z0-9_]{0,252}$/.test(request.key)
+    && typeof request.environment === 'string'
+    && /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(request.environment)
+    && deliveryErrors.length === 0
+    && Number.isSafeInteger(request.expectedTargetSecretsRevision)
+    && (request.expectedTargetSecretsRevision as number) >= 0;
+  const expectedContext = canBuildContext
+    ? secretData.createSecretCreateEnvelopeContext({
+        mutationId: request.mutationId as string,
+        target: request.target as TSecretMutationTarget,
+        key: request.key as string,
+        environment: request.environment as TSecretEnvironment,
+        delivery: request.delivery as TSecretDelivery,
+        expectedTargetSecretsRevision: request.expectedTargetSecretsRevision as number,
+      })
+    : new Uint8Array();
+  errors.push(...await secretData.validateSecretValueInputForRecipient(
+    request.valueInput,
+    activeIngressRecipientArg,
+    expectedContext,
+  ));
+  return errors;
+};
+
+export const validateRotateSecretRequest = async (
+  requestArg: unknown,
+  activeIngressRecipientArg: TSecretIngressRecipient,
+): Promise<string[]> => {
+  if (!requestArg || typeof requestArg !== 'object' || Array.isArray(requestArg)) {
+    return ['rotate secret request must be an object'];
+  }
+  const request = requestArg as Record<string, unknown>;
+  const errors = secretData.validateSecretMutationId(request.mutationId);
+  if (JSON.stringify(Object.keys(request).sort()) !== JSON.stringify([
+    'expectedActiveVersionId',
+    'expectedSecretRevision',
+    'expectedTargetSecretsRevision',
+    'identity',
+    'mutationId',
+    'secretId',
+    'valueInput',
+  ])) {
+    errors.push('rotate secret request must use its exact schema');
+  }
+  if (!request.identity || typeof request.identity !== 'object'
+    || typeof (request.identity as Record<string, unknown>).jwt !== 'string') {
+    errors.push('rotate secret identity must be a JWT credential');
+  }
+  for (const field of ['secretId', 'expectedActiveVersionId'] as const) {
+    if (typeof request[field] !== 'string'
+      || !/^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/.test(request[field] as string)) {
+      errors.push(`rotate secret ${field} must be canonical`);
+    }
+  }
+  if (!Number.isSafeInteger(request.expectedSecretRevision)
+    || (request.expectedSecretRevision as number) < 1) {
+    errors.push('rotate secret revision must be a positive integer');
+  }
+  if (!Number.isSafeInteger(request.expectedTargetSecretsRevision)
+    || (request.expectedTargetSecretsRevision as number) < 0) {
+    errors.push('rotate secret target revision must be a non-negative integer');
+  }
+  const canBuildContext = secretData.validateSecretMutationId(request.mutationId).length === 0
+    && typeof request.secretId === 'string'
+    && /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/.test(request.secretId)
+    && typeof request.expectedActiveVersionId === 'string'
+    && /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/.test(request.expectedActiveVersionId)
+    && Number.isSafeInteger(request.expectedSecretRevision)
+    && (request.expectedSecretRevision as number) >= 1
+    && Number.isSafeInteger(request.expectedTargetSecretsRevision)
+    && (request.expectedTargetSecretsRevision as number) >= 0;
+  const expectedContext = canBuildContext
+    ? secretData.createSecretRotateEnvelopeContext({
+        mutationId: request.mutationId as string,
+        secretId: request.secretId as string,
+        expectedSecretRevision: request.expectedSecretRevision as number,
+        expectedActiveVersionId: request.expectedActiveVersionId as string,
+        expectedTargetSecretsRevision: request.expectedTargetSecretsRevision as number,
+      })
+    : new Uint8Array();
+  errors.push(...await secretData.validateSecretValueInputForRecipient(
+    request.valueInput,
+    activeIngressRecipientArg,
+    expectedContext,
+  ));
+  return errors;
+};

package/ts/requests/service.ts

@@ -368,19 +368,3 @@ extends plugins.typedrequestInterfaces.implementsTR<
     success: boolean;
   };
 }
-
-export interface IRequest_Any_Cloudly_GetServiceSecretBundlesAsFlatObject
-extends plugins.typedrequestInterfaces.implementsTR<
-  plugins.typedrequestInterfaces.ITypedRequest,
-  IRequest_Any_Cloudly_GetServiceSecretBundlesAsFlatObject
-> {
-  method: 'getServiceSecretBundlesAsFlatObject';
-  request: {
-    identity: IIdentity;
-    serviceId: string;
-    environment: string;
-  };
-  response: {
-    flatKeyValueObject: {[key: string]: string};
-  };
-}

package/ts/requests/settings.ts

@@ -1,5 +1,5 @@
 import * as plugins from '../plugins.js';
-import type { ICloudlySettings, ICloudlySettingsMasked } from '../data/settings.js';
+import type { ICloudlySettings } from '../data/settings.js';
 import type { IIdentity } from '../data/user.js';
 
 // Get Settings
@@ -9,7 +9,7 @@ export interface IRequest_GetSettings extends plugins.typedrequestInterfaces.ITy
     identity?: IIdentity;
   };
   response: {
-    settings: ICloudlySettingsMasked;
+    settings: ICloudlySettings;
   };
 }
 
@@ -61,6 +61,6 @@ export interface IRequest_GetSetting extends plugins.typedrequestInterfaces.ITyp
     key: keyof ICloudlySettings;
   };
   response: {
-    value: string | undefined;
+    value: ICloudlySettings[keyof ICloudlySettings] | undefined;
   };
 }