@serve.zone/interfaces 23.2.0 → 24.0.0

package/ts/data/secret.ts

@@ -14,6 +14,7 @@ export type TSecretVersionLifecycleState =
   | 'active'
   | 'retired'
   | 'revoked'
+  | 'purge-pending'
   | 'purged';
 
 /** Retired versions remain usable only through an already-accepted manifest. */
@@ -89,6 +90,10 @@ export interface ISecretVersionRetentionReference {
   expiresAt?: number;
 }
 
+export const secretVersionRetentionReferenceLimits = Object.freeze({
+  pageSizeMaximum: 256,
+});
+
 /** Browser-safe logical secret metadata. It never contains value material. */
 export interface ISecretMetadata {
   id: string;
@@ -116,15 +121,61 @@ export interface ISecretMetadata {
 export interface ISecretVersionMetadata {
   id: string;
   secretId: string;
+  revision: number;
   lifecycleState: TSecretVersionLifecycleState;
   createdAt: number;
   createdBy: string;
   source: TSecretManagementSource;
   retiredAt?: number;
   revokedAt?: number;
+  purgeOperationId?: string;
   purgedAt?: number;
 }
 
+/** Irreversibly erases every platform-managed copy after all references are gone. */
+export interface ISecretVersionPurgeIntentV1 {
+  schemaVersion: 1;
+  mutationId: string;
+  secretId: string;
+  secretVersionId: string;
+  expectedSecretRevision: number;
+  expectedSecretVersionRevision: number;
+  expectedTargetSecretsRevision: number;
+}
+
+export interface ISecretVersionPurgeFailureV1 {
+  code: string;
+  retryable: boolean;
+  failedAt: number;
+}
+
+interface ISecretVersionPurgeOperationBaseV1 {
+  schemaVersion: 1;
+  id: string;
+  revision: number;
+  intent: ISecretVersionPurgeIntentV1;
+  intentDigest: TSha256Digest;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export type TSecretVersionPurgeOperationV1 =
+  | (ISecretVersionPurgeOperationBaseV1 & {
+      state: 'pending' | 'erasing';
+      failure?: never;
+      purgedAt?: never;
+    })
+  | (ISecretVersionPurgeOperationBaseV1 & {
+      state: 'failed';
+      failure: ISecretVersionPurgeFailureV1;
+      purgedAt?: never;
+    })
+  | (ISecretVersionPurgeOperationBaseV1 & {
+      state: 'succeeded';
+      failure?: never;
+      purgedAt: number;
+    });
+
 export interface ISecretSetMetadata {
   id: string;
   organizationId: string;
@@ -370,12 +421,264 @@ const isSecretEnvironment = (valueArg: unknown): valueArg is string => (
   typeof valueArg === 'string' && secretEnvironmentRegex.test(valueArg)
 );
 
+const isNonNegativeSafeInteger = (valueArg: unknown): valueArg is number => (
+  Number.isSafeInteger(valueArg) && (valueArg as number) >= 0
+);
+
+const isPositiveSafeInteger = (valueArg: unknown): valueArg is number => (
+  Number.isSafeInteger(valueArg) && (valueArg as number) > 0
+);
+
 export const validateSecretMutationId = (mutationIdArg: unknown): string[] => (
   isSecretIdentifier(mutationIdArg)
     ? []
     : ['mutationId must be a canonical identifier']
 );
 
+export const validateSecretVersionRetentionReferences = (
+  referencesArg: unknown,
+): string[] => {
+  if (!Array.isArray(referencesArg)
+    || referencesArg.length > secretVersionRetentionReferenceLimits.pageSizeMaximum) {
+    return ['secret version retention references must be a bounded array'];
+  }
+  const errors: string[] = [];
+  const kinds = new Set<TSecretVersionRetentionReferenceKind>([
+    'desired-manifest',
+    'applied-manifest',
+    'previous-accepted-manifest',
+    'rollback-manifest',
+    'backup',
+    'retention-window',
+  ]);
+  let previousSortKey: string | undefined;
+  for (const [index, referenceArg] of referencesArg.entries()) {
+    if (!isRecord(referenceArg)
+      || !hasOnlyKeys(referenceArg, ['kind', 'resourceId', 'expiresAt'])
+      || !kinds.has(referenceArg.kind as TSecretVersionRetentionReferenceKind)
+      || !isSecretIdentifier(referenceArg.resourceId)
+      || (referenceArg.expiresAt !== undefined
+        && !isNonNegativeSafeInteger(referenceArg.expiresAt))) {
+      errors.push(`secret version retention references[${index}] must be canonical`);
+      continue;
+    }
+    const sortKey = `${referenceArg.kind}\0${referenceArg.resourceId}\0${
+      referenceArg.expiresAt === undefined
+        ? ''
+        : String(referenceArg.expiresAt).padStart(16, '0')
+    }`;
+    if (previousSortKey !== undefined && sortKey <= previousSortKey) {
+      errors.push('secret version retention references must be uniquely sorted');
+    }
+    previousSortKey = sortKey;
+  }
+  return errors;
+};
+
+export const validateSecretVersionMetadata = (
+  versionArg: unknown,
+): string[] => {
+  if (!isRecord(versionArg)) return ['secret version metadata must be an object'];
+  const errors: string[] = [];
+  if (!hasOnlyKeys(versionArg, [
+    'id',
+    'secretId',
+    'revision',
+    'lifecycleState',
+    'createdAt',
+    'createdBy',
+    'source',
+    'retiredAt',
+    'revokedAt',
+    'purgeOperationId',
+    'purgedAt',
+  ])) {
+    errors.push('secret version metadata contains unsupported fields');
+  }
+  if (!isSecretIdentifier(versionArg.id) || !isSecretIdentifier(versionArg.secretId)) {
+    errors.push('secret version metadata identity must be canonical');
+  }
+  if (!isPositiveSafeInteger(versionArg.revision)) {
+    errors.push('secret version metadata revision must be positive');
+  }
+  if (!['active', 'retired', 'revoked', 'purge-pending', 'purged']
+    .includes(versionArg.lifecycleState as string)) {
+    errors.push('secret version metadata lifecycleState must be canonical');
+  }
+  if (!isNonNegativeSafeInteger(versionArg.createdAt)
+    || !isSecretIdentifier(versionArg.createdBy)
+    || !['operator', 'appstore', 'mail', 'oidc', 'webpush', 'platform', 'system']
+      .includes(versionArg.source as string)) {
+    errors.push('secret version metadata creation fields must be canonical');
+  }
+  for (const field of ['retiredAt', 'revokedAt', 'purgedAt'] as const) {
+    if (versionArg[field] !== undefined && !isNonNegativeSafeInteger(versionArg[field])) {
+      errors.push(`secret version metadata ${field} must be a non-negative integer`);
+    }
+  }
+  const hasPurgeOperationId = isSecretIdentifier(versionArg.purgeOperationId);
+  if (versionArg.lifecycleState === 'purge-pending') {
+    if (!hasPurgeOperationId || versionArg.purgedAt !== undefined) {
+      errors.push('purge-pending secret version metadata requires only a purge operation');
+    }
+  } else if (versionArg.lifecycleState === 'purged') {
+    if (!hasPurgeOperationId || !isNonNegativeSafeInteger(versionArg.purgedAt)) {
+      errors.push('purged secret version metadata requires a purge operation and purgedAt');
+    }
+  } else if (versionArg.purgeOperationId !== undefined || versionArg.purgedAt !== undefined) {
+    errors.push('non-purging secret version metadata forbids purge fields');
+  }
+  return errors;
+};
+
+export const validateSecretVersionPurgeIntent = (
+  intentArg: unknown,
+): string[] => {
+  if (!isRecord(intentArg)
+    || !hasExactKeys(intentArg, [
+      'schemaVersion',
+      'mutationId',
+      'secretId',
+      'secretVersionId',
+      'expectedSecretRevision',
+      'expectedSecretVersionRevision',
+      'expectedTargetSecretsRevision',
+    ])) {
+    return ['secret version purge intent must use its exact schema'];
+  }
+  const errors = validateSecretMutationId(intentArg.mutationId);
+  if (intentArg.schemaVersion !== 1) {
+    errors.push('secret version purge intent schemaVersion must be 1');
+  }
+  for (const field of ['secretId', 'secretVersionId'] as const) {
+    if (!isSecretIdentifier(intentArg[field])) {
+      errors.push(`secret version purge intent ${field} must be canonical`);
+    }
+  }
+  for (const field of ['expectedSecretRevision', 'expectedSecretVersionRevision'] as const) {
+    if (!isPositiveSafeInteger(intentArg[field])) {
+      errors.push(`secret version purge intent ${field} must be positive`);
+    }
+  }
+  if (!isNonNegativeSafeInteger(intentArg.expectedTargetSecretsRevision)) {
+    errors.push('secret version purge intent expectedTargetSecretsRevision must be non-negative');
+  }
+  return errors;
+};
+
+export const createSecretVersionPurgeIntentDigestInput = (
+  intentArg: ISecretVersionPurgeIntentV1,
+): string => JSON.stringify({
+  schemaVersion: intentArg.schemaVersion,
+  purpose: 'serve.zone/secret-version-purge',
+  mutationId: intentArg.mutationId,
+  secretId: intentArg.secretId,
+  secretVersionId: intentArg.secretVersionId,
+  expectedSecretRevision: intentArg.expectedSecretRevision,
+  expectedSecretVersionRevision: intentArg.expectedSecretVersionRevision,
+  expectedTargetSecretsRevision: intentArg.expectedTargetSecretsRevision,
+});
+
+export const computeSecretVersionPurgeIntentDigest = async (
+  intentArg: ISecretVersionPurgeIntentV1,
+): Promise<TSha256Digest> => {
+  if (validateSecretVersionPurgeIntent(intentArg).length > 0) {
+    throw new Error('secret version purge intent must be canonical');
+  }
+  const digest = new Uint8Array(await globalThis.crypto.subtle.digest(
+    'SHA-256',
+    new TextEncoder().encode(createSecretVersionPurgeIntentDigestInput(intentArg)),
+  ));
+  return `sha256:${[...digest]
+    .map((byteArg) => byteArg.toString(16).padStart(2, '0'))
+    .join('')}` as TSha256Digest;
+};
+
+export const verifySecretVersionPurgeIntentDigest = async (
+  intentArg: ISecretVersionPurgeIntentV1,
+  digestArg: unknown,
+): Promise<boolean> => {
+  try {
+    return typeof digestArg === 'string'
+      && secretDigestRegex.test(digestArg)
+      && digestArg === await computeSecretVersionPurgeIntentDigest(intentArg);
+  } catch {
+    return false;
+  }
+};
+
+export const validateSecretVersionPurgeOperation = async (
+  operationArg: unknown,
+): Promise<string[]> => {
+  if (!isRecord(operationArg)) return ['secret version purge operation must be an object'];
+  const state = operationArg.state;
+  const expectedKeys = state === 'failed'
+    ? [
+        'schemaVersion', 'id', 'revision', 'intent', 'intentDigest', 'state',
+        'failure', 'createdAt', 'updatedAt',
+      ]
+    : state === 'succeeded'
+      ? [
+          'schemaVersion', 'id', 'revision', 'intent', 'intentDigest', 'state',
+          'purgedAt', 'createdAt', 'updatedAt',
+        ]
+      : [
+          'schemaVersion', 'id', 'revision', 'intent', 'intentDigest', 'state',
+          'createdAt', 'updatedAt',
+        ];
+  if (!['pending', 'erasing', 'failed', 'succeeded'].includes(state as string)
+    || !hasExactKeys(operationArg, expectedKeys)) {
+    return ['secret version purge operation must use its exact state schema'];
+  }
+  const errors = validateSecretVersionPurgeIntent(operationArg.intent);
+  if (operationArg.schemaVersion !== 1) {
+    errors.push('secret version purge operation schemaVersion must be 1');
+  }
+  if (!isSecretIdentifier(operationArg.id) || !isPositiveSafeInteger(operationArg.revision)) {
+    errors.push('secret version purge operation identity and revision must be canonical');
+  }
+  if (!isNonNegativeSafeInteger(operationArg.createdAt)
+    || !isNonNegativeSafeInteger(operationArg.updatedAt)
+    || (operationArg.updatedAt as number) < (operationArg.createdAt as number)) {
+    errors.push('secret version purge operation timestamps must be ordered');
+  }
+  if (isRecord(operationArg.intent)
+    && typeof operationArg.intentDigest === 'string'
+    && secretDigestRegex.test(operationArg.intentDigest)) {
+    try {
+      if (!await verifySecretVersionPurgeIntentDigest(
+        operationArg.intent as unknown as ISecretVersionPurgeIntentV1,
+        operationArg.intentDigest,
+      )) {
+        errors.push('secret version purge operation intentDigest does not match');
+      }
+    } catch {
+      errors.push('secret version purge operation intentDigest cannot be verified');
+    }
+  } else {
+    errors.push('secret version purge operation intentDigest must be canonical');
+  }
+  if (state === 'failed') {
+    if (!isRecord(operationArg.failure)
+      || !hasExactKeys(operationArg.failure, ['code', 'retryable', 'failedAt'])
+      || typeof operationArg.failure.code !== 'string'
+      || !/^[A-Z][A-Z0-9_]{0,127}$/.test(operationArg.failure.code)
+      || typeof operationArg.failure.retryable !== 'boolean'
+      || !isNonNegativeSafeInteger(operationArg.failure.failedAt)
+      || (operationArg.failure.failedAt as number) < (operationArg.createdAt as number)
+      || (operationArg.failure.failedAt as number) > (operationArg.updatedAt as number)) {
+      errors.push('secret version purge operation failure must be canonical');
+    }
+  }
+  if (state === 'succeeded'
+    && (!isNonNegativeSafeInteger(operationArg.purgedAt)
+      || (operationArg.purgedAt as number) < (operationArg.createdAt as number)
+      || (operationArg.purgedAt as number) > (operationArg.updatedAt as number))) {
+    errors.push('succeeded secret version purge operation requires a canonical purgedAt');
+  }
+  return errors;
+};
+
 export const validateSecretOwner = (ownerArg: unknown): string[] => {
   if (!isRecord(ownerArg)) return ['secret owner must be an object'];
   const shapeByKind = {
@@ -446,6 +749,105 @@ export const validateSecretDelivery = (deliveryArg: unknown): string[] => {
   return errors;
 };
 
+export const validateSecretMetadata = (secretArg: unknown): string[] => {
+  if (!isRecord(secretArg)) return ['secret metadata must be an object'];
+  const expectedKeys = [
+    'id',
+    'organizationId',
+    'owner',
+    'key',
+    'environment',
+    'name',
+    ...(secretArg.description === undefined ? [] : ['description']),
+    'tags',
+    'managementSource',
+    'managementScope',
+    'defaultDelivery',
+    'lifecycleState',
+    ...(secretArg.activeVersion === undefined ? [] : ['activeVersion']),
+    'versionCount',
+    'revision',
+    'createdAt',
+    'updatedAt',
+    ...(secretArg.lastRotatedAt === undefined ? [] : ['lastRotatedAt']),
+  ];
+  const errors: string[] = [];
+  if (!hasExactKeys(secretArg, expectedKeys)) {
+    errors.push('secret metadata must use its exact schema');
+  }
+  if (!isSecretIdentifier(secretArg.id) || !isSecretIdentifier(secretArg.organizationId)) {
+    errors.push('secret metadata identity must be canonical');
+  }
+  errors.push(...validateSecretOwner(secretArg.owner));
+  if (!isSecretKey(secretArg.key) || !isSecretEnvironment(secretArg.environment)) {
+    errors.push('secret metadata key and environment must be canonical');
+  }
+  if (typeof secretArg.name !== 'string'
+    || secretArg.name.trim() !== secretArg.name
+    || secretArg.name.length < 1
+    || secretArg.name.length > 200
+    || (secretArg.description !== undefined
+      && (typeof secretArg.description !== 'string' || secretArg.description.length > 2000))) {
+    errors.push('secret metadata name and description must be bounded');
+  }
+  if (!Array.isArray(secretArg.tags) || secretArg.tags.length > 64) {
+    errors.push('secret metadata tags must be a bounded array');
+  } else {
+    const tagKeys: string[] = [];
+    for (const [index, tagArg] of secretArg.tags.entries()) {
+      if (!isRecord(tagArg)
+        || !hasExactKeys(tagArg, ['key', 'value'])
+        || typeof tagArg.key !== 'string'
+        || tagArg.key.length < 1
+        || tagArg.key.length > 100
+        || typeof tagArg.value !== 'string'
+        || tagArg.value.length > 500) {
+        errors.push(`secret metadata tags[${index}] must use the bounded key/value schema`);
+      } else {
+        tagKeys.push(tagArg.key);
+      }
+    }
+    if (new Set(tagKeys).size !== tagKeys.length) {
+      errors.push('secret metadata tag keys must be unique');
+    }
+  }
+  if (!['operator', 'appstore', 'mail', 'oidc', 'webpush', 'platform', 'system']
+    .includes(secretArg.managementSource as string)) {
+    errors.push('secret metadata managementSource must be canonical');
+  } else {
+    errors.push(...validateSecretManagementScope(
+      secretArg.managementSource as TSecretManagementSource,
+      secretArg.managementScope,
+    ));
+  }
+  errors.push(...validateSecretDelivery(secretArg.defaultDelivery));
+  if (!['active', 'retired', 'revoked', 'deleted'].includes(secretArg.lifecycleState as string)) {
+    errors.push('secret metadata lifecycleState must be canonical');
+  }
+  if (secretArg.activeVersion !== undefined) {
+    if (!isRecord(secretArg.activeVersion)
+      || !hasExactKeys(secretArg.activeVersion, ['secretId', 'secretVersionId'])
+      || secretArg.activeVersion.secretId !== secretArg.id
+      || !isSecretIdentifier(secretArg.activeVersion.secretVersionId)) {
+      errors.push('secret metadata activeVersion must be a canonical self-reference');
+    }
+  }
+  if (!isNonNegativeSafeInteger(secretArg.versionCount)
+    || !isPositiveSafeInteger(secretArg.revision)
+    || !isNonNegativeSafeInteger(secretArg.createdAt)
+    || !isNonNegativeSafeInteger(secretArg.updatedAt)
+    || (secretArg.updatedAt as number) < (secretArg.createdAt as number)) {
+    errors.push('secret metadata counts, revision, and timestamps must be canonical');
+  }
+  if (secretArg.lastRotatedAt !== undefined
+    && (!isNonNegativeSafeInteger(secretArg.lastRotatedAt)
+      || (secretArg.lastRotatedAt as number) < (secretArg.createdAt as number)
+      || (secretArg.lastRotatedAt as number) > (secretArg.updatedAt as number))) {
+    errors.push('secret metadata lastRotatedAt must be within its lifetime');
+  }
+  return errors;
+};
+
 export const validateSecretValueInput = (valueInputArg: unknown): string[] => {
   if (!isRecord(valueInputArg)) return ['valueInput must be an object'];
   if (valueInputArg.mode === 'sealed') {
@@ -1306,8 +1708,6 @@ export type TSecretRecipientMetadata =
   | IRetiringSecretRecipientMetadata
   | IRevokedSecretRecipientMetadata;
 
-export type TSecretIngressRecipient = TSecretRecipientMetadata;
-
 export const secretRecipientLimits = Object.freeze({
   maximumRecipients: 64,
 });
@@ -1424,20 +1824,6 @@ export const validateSecretValueInputForRecipient = async (
   return errors;
 };
 
-/** Retiring recipients open only already-issued envelopes before their deadline. */
-export const canOpenIssuedSecretEnvelope = (
-  recipientArg: TSecretRecipientMetadata,
-  issuedAtArg: number,
-  nowArg: number,
-): boolean => Number.isSafeInteger(issuedAtArg)
-  && Number.isSafeInteger(nowArg)
-  && issuedAtArg >= recipientArg.activatedAt
-  && issuedAtArg <= nowArg
-  && (recipientArg.lifecycleState === 'active'
-  || (recipientArg.lifecycleState === 'retiring'
-    && issuedAtArg < recipientArg.acceptUntil
-    && nowArg < recipientArg.acceptUntil));
-
 const canonicalSecretOwner = (ownerArg: TSecretOwner): Record<string, string> => {
   switch (ownerArg.kind) {
     case 'service': return { kind: ownerArg.kind, serviceId: ownerArg.serviceId };