@serve.zone/interfaces 23.2.0 → 24.0.0

package/ts/requests/secret.ts

@@ -2,13 +2,15 @@ import type * as plugins from '../plugins.js';
 import * as secretData from '../data/secret.js';
 import type {
   IResolvedSecretManifestEntry,
+  IActiveSecretRecipientMetadata,
   ISecretMetadata,
   ISecretSetAttachment,
   ISecretSetConsumerRolloutStatus,
   ISecretSetMetadata,
   ISecretVersionMetadata,
+  ISecretVersionPurgeIntentV1,
   ISecretVersionRetentionReference,
-  TSecretIngressRecipient,
+  TSecretVersionPurgeOperationV1,
   TSecretMutationTarget,
   TSecretValueInput,
   TSecretDelivery,
@@ -26,7 +28,7 @@ extends plugins.typedrequestInterfaces.implementsTR<
     identity: IIdentityCredential;
   };
   response: {
-    recipient: TSecretIngressRecipient;
+    recipient: IActiveSecretRecipientMetadata;
   };
 }
 
@@ -120,7 +122,7 @@ export interface IReq_ChangeSecretLifecycle extends plugins.typedrequestInterfac
   request: {
     identity: IIdentityCredential;
     secretId: string;
-    action: 'retire' | 'revoke' | 'delete' | 'request-purge';
+    action: 'retire' | 'revoke' | 'delete';
     expectedSecretRevision: number;
     expectedTargetSecretsRevision: number;
   };
@@ -140,10 +142,44 @@ extends plugins.typedrequestInterfaces.implementsTR<
     identity: IIdentityCredential;
     secretId: string;
     secretVersionId: string;
+    cursor?: string;
+    limit?: number;
   };
   response: {
-    purgeAllowed: boolean;
+    schemaVersion: 1;
+    secret: ISecretMetadata;
+    version: ISecretVersionMetadata;
+    targetSecretsRevision: number;
+    eligible: boolean;
+    blockers: TSecretVersionPurgeBlocker[];
+    blockingReferenceCount: number;
     references: ISecretVersionRetentionReference[];
+    nextCursor?: string;
+    referencesTruncated: boolean;
+    operation?: TSecretVersionPurgeOperationV1;
+  };
+}
+
+export type TSecretVersionPurgeBlocker =
+  | 'version-active'
+  | 'retention-reference'
+  | 'purge-pending'
+  | 'already-purged';
+
+export interface IReq_PurgeSecretVersion
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_PurgeSecretVersion
+> {
+  method: 'purgeSecretVersion';
+  request: ISecretVersionPurgeIntentV1 & {
+    identity: IIdentityCredential;
+  };
+  response: {
+    secret: ISecretMetadata;
+    version: ISecretVersionMetadata;
+    operation: TSecretVersionPurgeOperationV1;
+    targetSecretsRevision: number;
   };
 }
 
@@ -281,7 +317,7 @@ const isRecord = (valueArg: unknown): valueArg is Record<string, unknown> => (
 
 export const validateCreateSecretRequest = async (
   requestArg: unknown,
-  activeIngressRecipientArg: TSecretIngressRecipient,
+  activeIngressRecipientArg: IActiveSecretRecipientMetadata,
 ): Promise<string[]> => {
   if (!requestArg || typeof requestArg !== 'object' || Array.isArray(requestArg)) {
     return ['create secret request must be an object'];
@@ -388,7 +424,7 @@ export const validateCreateSecretRequest = async (
 
 export const validateRotateSecretRequest = async (
   requestArg: unknown,
-  activeIngressRecipientArg: TSecretIngressRecipient,
+  activeIngressRecipientArg: IActiveSecretRecipientMetadata,
 ): Promise<string[]> => {
   if (!requestArg || typeof requestArg !== 'object' || Array.isArray(requestArg)) {
     return ['rotate secret request must be an object'];
@@ -449,3 +485,209 @@ export const validateRotateSecretRequest = async (
   ));
   return errors;
 };
+
+export const validatePurgeSecretVersionRequest = (
+  requestArg: unknown,
+): string[] => {
+  try {
+    if (!isRecord(requestArg)) return ['purge secret version request must be an object'];
+    const request = requestArg as Record<string, unknown>;
+    const intent = Object.fromEntries(
+      Object.entries(request).filter(([keyArg]) => keyArg !== 'identity'),
+    );
+    const errors = secretData.validateSecretVersionPurgeIntent(intent);
+    if (!request.identity || typeof request.identity !== 'object' || Array.isArray(request.identity)
+      || JSON.stringify(Object.keys(request.identity).sort()) !== JSON.stringify(['jwt'])
+      || typeof (request.identity as Record<string, unknown>).jwt !== 'string'
+      || !(request.identity as Record<string, unknown>).jwt) {
+      errors.push('purge secret version request requires only a JWT identity');
+    }
+    return errors;
+  } catch {
+    return ['purge secret version request must be safely inspectable'];
+  }
+};
+
+export const validateGetSecretVersionPurgePreflightRequest = (
+  requestArg: unknown,
+): string[] => {
+  try {
+    if (!isRecord(requestArg)) {
+      return ['secret version purge preflight request must be an object'];
+    }
+    const expectedKeys = [
+      'identity',
+      'secretId',
+      'secretVersionId',
+      ...(requestArg.cursor === undefined ? [] : ['cursor']),
+      ...(requestArg.limit === undefined ? [] : ['limit']),
+    ];
+    const errors: string[] = [];
+    if (JSON.stringify(Object.keys(requestArg).sort())
+      !== JSON.stringify(expectedKeys.sort())) {
+      errors.push('secret version purge preflight request must use its exact schema');
+    }
+    if (!isRecord(requestArg.identity)
+      || JSON.stringify(Object.keys(requestArg.identity).sort()) !== JSON.stringify(['jwt'])
+      || typeof requestArg.identity.jwt !== 'string'
+      || !requestArg.identity.jwt) {
+      errors.push('secret version purge preflight request requires only a JWT identity');
+    }
+    for (const field of ['secretId', 'secretVersionId'] as const) {
+      if (typeof requestArg[field] !== 'string'
+        || !/^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/.test(requestArg[field])) {
+        errors.push(`secret version purge preflight ${field} must be canonical`);
+      }
+    }
+    if (requestArg.cursor !== undefined
+      && (typeof requestArg.cursor !== 'string' || requestArg.cursor.length === 0)) {
+      errors.push('secret version purge preflight cursor must be opaque and non-empty');
+    }
+    if (requestArg.limit !== undefined
+      && (!Number.isSafeInteger(requestArg.limit)
+        || (requestArg.limit as number) < 1
+        || (requestArg.limit as number)
+          > secretData.secretVersionRetentionReferenceLimits.pageSizeMaximum)) {
+      errors.push('secret version purge preflight limit must be bounded');
+    }
+    return errors;
+  } catch {
+    return ['secret version purge preflight request must be safely inspectable'];
+  }
+};
+
+export const validateSecretVersionPurgePreflightResponse = async (
+  responseArg: unknown,
+): Promise<string[]> => {
+  try {
+    if (!isRecord(responseArg)) {
+      return ['secret version purge preflight response must be an object'];
+    }
+    const response = responseArg as Record<string, unknown>;
+    const expectedKeys = [
+      'schemaVersion',
+      'secret',
+      'version',
+      'targetSecretsRevision',
+      'eligible',
+      'blockers',
+      'blockingReferenceCount',
+      'references',
+      'referencesTruncated',
+      ...(response.nextCursor === undefined ? [] : ['nextCursor']),
+      ...(response.operation === undefined ? [] : ['operation']),
+    ];
+    const errors: string[] = [];
+    if (JSON.stringify(Object.keys(response).sort())
+      !== JSON.stringify([...expectedKeys].sort())) {
+      errors.push('secret version purge preflight response must use its exact schema');
+    }
+    if (response.schemaVersion !== 1) {
+      errors.push('secret version purge preflight response schemaVersion must be 1');
+    }
+    if (secretData.validateSecretVersionMetadata(response.version).length > 0) {
+      errors.push('secret version purge preflight version must be canonical');
+    }
+    if (secretData.validateSecretMetadata(response.secret).length > 0) {
+      errors.push('secret version purge preflight secret must be canonical');
+    }
+    if (isRecord(response.secret)
+      && isRecord(response.version)
+      && response.version.secretId !== response.secret.id) {
+      errors.push('secret version purge preflight version must belong to its secret');
+    }
+    if (!Number.isSafeInteger(response.targetSecretsRevision)
+      || (response.targetSecretsRevision as number) < 0) {
+      errors.push('secret version purge preflight target revision must be non-negative');
+    }
+    const allowedBlockers = new Set<TSecretVersionPurgeBlocker>([
+      'version-active',
+      'retention-reference',
+      'purge-pending',
+      'already-purged',
+    ]);
+    if (!Array.isArray(response.blockers)
+      || response.blockers.some((blockerArg) => !allowedBlockers.has(
+        blockerArg as TSecretVersionPurgeBlocker,
+      ))
+      || new Set(response.blockers).size !== response.blockers.length
+      || JSON.stringify(response.blockers) !== JSON.stringify([...response.blockers].sort())) {
+      errors.push('secret version purge preflight blockers must be uniquely sorted');
+    }
+    if (typeof response.eligible !== 'boolean'
+      || response.eligible !== (Array.isArray(response.blockers) && response.blockers.length === 0)) {
+      errors.push('secret version purge preflight eligibility must be derived from blockers');
+    }
+    if (!Number.isSafeInteger(response.blockingReferenceCount)
+      || (response.blockingReferenceCount as number) < 0) {
+      errors.push('secret version purge preflight reference count must be non-negative');
+    }
+    errors.push(...secretData.validateSecretVersionRetentionReferences(response.references));
+    if (typeof response.referencesTruncated !== 'boolean') {
+      errors.push('secret version purge preflight referencesTruncated must be boolean');
+    }
+    if (response.nextCursor !== undefined
+      && (typeof response.nextCursor !== 'string' || response.nextCursor.length === 0)) {
+      errors.push('secret version purge preflight nextCursor must be opaque and non-empty');
+    }
+    if (response.referencesTruncated !== (response.nextCursor !== undefined)) {
+      errors.push('secret version purge preflight truncation must match nextCursor presence');
+    }
+    if (Array.isArray(response.references)
+      && Number.isSafeInteger(response.blockingReferenceCount)
+      && (response.blockingReferenceCount as number) < response.references.length) {
+      errors.push('secret version purge preflight reference count cannot be smaller than its page');
+    }
+    if (Array.isArray(response.blockers)
+      && isRecord(response.version)
+      && Number.isSafeInteger(response.blockingReferenceCount)) {
+      const expectedBlockers: TSecretVersionPurgeBlocker[] = [];
+      if (response.version.lifecycleState === 'active') expectedBlockers.push('version-active');
+      if ((response.blockingReferenceCount as number) > 0) {
+        expectedBlockers.push('retention-reference');
+      }
+      if (response.version.lifecycleState === 'purge-pending') {
+        expectedBlockers.push('purge-pending');
+      }
+      if (response.version.lifecycleState === 'purged') expectedBlockers.push('already-purged');
+      expectedBlockers.sort();
+      if (JSON.stringify(response.blockers) !== JSON.stringify(expectedBlockers)) {
+        errors.push('secret version purge preflight blockers do not match current state');
+      }
+    }
+    if (response.operation !== undefined) {
+      errors.push(...await secretData.validateSecretVersionPurgeOperation(response.operation));
+      if (isRecord(response.operation)
+        && isRecord(response.operation.intent)
+        && isRecord(response.secret)
+        && isRecord(response.version)
+        && (
+          response.operation.id !== response.version.purgeOperationId
+          || response.operation.intent.secretId !== response.secret.id
+          || response.operation.intent.secretVersionId !== response.version.id
+        )) {
+        errors.push('secret version purge preflight operation does not match its version');
+      }
+      if (isRecord(response.operation) && isRecord(response.version)) {
+        if (response.version.lifecycleState === 'purge-pending'
+          && response.operation.state === 'succeeded') {
+          errors.push('purge-pending version cannot have a succeeded purge operation');
+        }
+        if (response.version.lifecycleState === 'purged'
+          && (response.operation.state !== 'succeeded'
+            || response.operation.purgedAt !== response.version.purgedAt)) {
+          errors.push('purged version requires the matching succeeded purge operation');
+        }
+      }
+    }
+    if (isRecord(response.version)
+      && (response.version.lifecycleState === 'purge-pending'
+        || response.version.lifecycleState === 'purged')
+      && response.operation === undefined) {
+      errors.push('secret version purge preflight purging state requires its operation');
+    }
+    return errors;
+  } catch {
+    return ['secret version purge preflight response must be safely inspectable'];
+  }
+};