@futdevpro/fsm-dynamo 1.20.2 → 1.20.5

package/src/_modules/deployment/_collections/atomic-rollback-manifest.util.ts

@@ -0,0 +1,455 @@
+import * as CryptoJS from 'crypto-js';
+
+import {
+  DyFM_AtomicRollbackAuthority_Interface,
+  DyFM_AtomicRollbackConfiguration_Interface,
+  DyFM_AtomicRollbackEnvironment_Type,
+  DyFM_AtomicRollbackImage_Interface,
+  DyFM_AtomicRollbackLocalValidation_Interface,
+  DyFM_AtomicRollbackManifest_Interface,
+  DyFM_AtomicRollbackPostCheck_Interface
+} from '../_models/atomic-rollback-manifest.interface';
+
+const dyfm_exactManifestKeys: string = [
+  'authority',
+  'configuration',
+  'contractVersion',
+  'environment',
+  'images',
+  'operationId',
+  'postChecks',
+  'sourceRevision',
+  'targetChecksum',
+].join(',');
+const dyfm_exactAuthorityKeys: string = 'evidenceId,principalId';
+const dyfm_exactConfigurationKeys: string = 'compatibilityVersion,policyChecksum,revision,sha256';
+const dyfm_exactImageKeys: string = 'digest,immutableReference,mutableReference,service,version';
+const dyfm_exactPostCheckKeys: string = 'checkId,endpoint,expectedProbeContract,service';
+const dyfm_revisionPattern: RegExp = /^[0-9a-f]{40}$/u;
+const dyfm_sha256Pattern: RegExp = /^[0-9a-f]{64}$/u;
+const dyfm_digestPattern: RegExp = /^sha256:[0-9a-f]{64}$/u;
+const dyfm_operationPattern: RegExp = /^rollback_[0-9a-f]{32}$/u;
+const dyfm_safeIdPattern: RegExp = /^[a-z0-9][a-z0-9._-]{0,127}$/u;
+const dyfm_versionPattern: RegExp = /^[0-9A-Za-z][0-9A-Za-z._-]{0,63}$/u;
+const dyfm_compatibilityPattern: RegExp = /^[a-z0-9][a-z0-9-]{1,63}\/[1-9][0-9]{0,8}$/u;
+const dyfm_contractPattern: RegExp = /^[a-z0-9][a-z0-9-]{1,63}\/[1-9][0-9]{0,8}$/u;
+const dyfm_imageReferencePattern: RegExp =
+  /^(?:[a-z0-9]+(?:[._-][a-z0-9]+)*(?::[0-9]+)?\/)+[a-z0-9]+(?:[._-][a-z0-9]+)*:[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u;
+
+/** Determines whether an unknown value is a non-array object. */
+function dyfm_isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** Compares an object's sorted keys with one exact key signature. */
+function dyfm_hasExactKeys(value: Record<string, unknown>, expected: string): boolean {
+  return Object.keys(value).sort().join(',') === expected;
+}
+
+/** Narrows a value to a deployment environment supported by the contract. */
+function dyfm_isEnvironment(value: unknown): value is DyFM_AtomicRollbackEnvironment_Type {
+  return value === 'test' || value === 'production';
+}
+
+/** Allows bounded HTTPS probes and service-local HTTP probes without credentials or query data. */
+function dyfm_isSafePostCheckEndpoint(value: string, service: string): boolean {
+  if (value.length > 2048) {
+    return false;
+  }
+  try {
+    const endpoint: URL = new URL(value);
+
+    if (
+      endpoint.username
+      || endpoint.password
+      || endpoint.search
+      || endpoint.hash
+      || !/^\/[A-Za-z0-9/_-]{0,127}$/u.test(endpoint.pathname)
+    ) {
+      return false;
+    }
+
+    if (endpoint.protocol === 'https:') {
+      return true;
+    }
+
+    return endpoint.protocol === 'http:'
+      && [ service, '127.0.0.1', 'localhost' ].includes(endpoint.hostname);
+  } catch {
+    return false;
+  }
+}
+
+/** Parses bounded deployment authority evidence without returning rejected content. */
+function dyfm_parseAuthority(
+  value: unknown,
+  gapCodes: string[],
+): DyFM_AtomicRollbackAuthority_Interface | undefined {
+  if (!dyfm_isRecord(value) || !dyfm_hasExactKeys(value, dyfm_exactAuthorityKeys)) {
+    gapCodes.push('FDP|ATOMIC_ROLLBACK|AUTHORITY_SHAPE_INVALID');
+
+    return undefined;
+  }
+
+  if (typeof value.principalId !== 'string' || !dyfm_safeIdPattern.test(value.principalId)) {
+    gapCodes.push('FDP|ATOMIC_ROLLBACK|AUTHORITY_PRINCIPAL_INVALID');
+  }
+
+  if (typeof value.evidenceId !== 'string' || !dyfm_sha256Pattern.test(value.evidenceId)) {
+    gapCodes.push('FDP|ATOMIC_ROLLBACK|AUTHORITY_EVIDENCE_INVALID');
+  }
+
+  if (
+    typeof value.principalId !== 'string'
+    || typeof value.evidenceId !== 'string'
+    || gapCodes.some((code: string): boolean => code.startsWith('FDP|ATOMIC_ROLLBACK|AUTHORITY_'))
+  ) {
+    return undefined;
+  }
+
+  return { principalId: value.principalId, evidenceId: value.evidenceId };
+}
+
+/** Parses an exact configuration and compatibility target. */
+function dyfm_parseConfiguration(
+  value: unknown,
+  gapCodes: string[],
+): DyFM_AtomicRollbackConfiguration_Interface | undefined {
+  if (!dyfm_isRecord(value) || !dyfm_hasExactKeys(value, dyfm_exactConfigurationKeys)) {
+    gapCodes.push('FDP|ATOMIC_ROLLBACK|CONFIGURATION_SHAPE_INVALID');
+
+    return undefined;
+  }
+
+  if (typeof value.revision !== 'string' || !dyfm_revisionPattern.test(value.revision)) {
+    gapCodes.push('FDP|ATOMIC_ROLLBACK|CONFIGURATION_REVISION_INVALID');
+  }
+
+  if (typeof value.sha256 !== 'string' || !dyfm_sha256Pattern.test(value.sha256)) {
+    gapCodes.push('FDP|ATOMIC_ROLLBACK|CONFIGURATION_CHECKSUM_INVALID');
+  }
+
+  if (
+    typeof value.compatibilityVersion !== 'string'
+    || !dyfm_compatibilityPattern.test(value.compatibilityVersion)
+  ) {
+    gapCodes.push('FDP|ATOMIC_ROLLBACK|CONFIGURATION_COMPATIBILITY_INVALID');
+  }
+
+  if (typeof value.policyChecksum !== 'string' || !dyfm_sha256Pattern.test(value.policyChecksum)) {
+    gapCodes.push('FDP|ATOMIC_ROLLBACK|CONFIGURATION_POLICY_CHECKSUM_INVALID');
+  }
+
+  if (
+    typeof value.revision !== 'string'
+    || typeof value.sha256 !== 'string'
+    || typeof value.compatibilityVersion !== 'string'
+    || typeof value.policyChecksum !== 'string'
+    || gapCodes.some((code: string): boolean => code.startsWith('FDP|ATOMIC_ROLLBACK|CONFIGURATION_'))
+  ) {
+    return undefined;
+  }
+
+  return {
+    revision: value.revision,
+    sha256: value.sha256,
+    compatibilityVersion: value.compatibilityVersion,
+    policyChecksum: value.policyChecksum,
+  };
+}
+
+/** Parses the complete immutable image promotion set. */
+function dyfm_parseImages(value: unknown, gapCodes: string[]): DyFM_AtomicRollbackImage_Interface[] {
+  if (!Array.isArray(value) || value.length < 1 || value.length > 16) {
+    gapCodes.push('FDP|ATOMIC_ROLLBACK|IMAGE_SET_CARDINALITY_INVALID');
+
+    return [];
+  }
+  const images: DyFM_AtomicRollbackImage_Interface[] = [];
+
+  for (const candidate of value) {
+    if (!dyfm_isRecord(candidate) || !dyfm_hasExactKeys(candidate, dyfm_exactImageKeys)) {
+      gapCodes.push('FDP|ATOMIC_ROLLBACK|IMAGE_SHAPE_INVALID');
+      continue;
+    }
+    const service: string | undefined = typeof candidate.service === 'string' ? candidate.service : undefined;
+    const version: string | undefined = typeof candidate.version === 'string' ? candidate.version : undefined;
+    const immutableReference: string | undefined = typeof candidate.immutableReference === 'string'
+      ? candidate.immutableReference
+      : undefined;
+    const mutableReference: string | undefined = typeof candidate.mutableReference === 'string'
+      ? candidate.mutableReference
+      : undefined;
+    const digest: string | undefined = typeof candidate.digest === 'string' ? candidate.digest : undefined;
+
+    if (!service || !dyfm_safeIdPattern.test(service)) {
+      gapCodes.push('FDP|ATOMIC_ROLLBACK|IMAGE_SERVICE_INVALID');
+      continue;
+    }
+
+    if (!version || !dyfm_versionPattern.test(version)) {
+      gapCodes.push(`FDP|ATOMIC_ROLLBACK|IMAGE_VERSION_INVALID|${service}`);
+      continue;
+    }
+
+    if (
+      !immutableReference
+      || immutableReference.length > 512
+      || !dyfm_imageReferencePattern.test(immutableReference)
+      || !immutableReference.endsWith(`/${service}:release-${version}`)
+    ) {
+      gapCodes.push(`FDP|ATOMIC_ROLLBACK|IMAGE_IMMUTABLE_REFERENCE_INVALID|${service}`);
+      continue;
+    }
+
+    if (
+      !mutableReference
+      || mutableReference.length > 512
+      || !dyfm_imageReferencePattern.test(mutableReference)
+      || !mutableReference.endsWith(`/${service}:release`)
+    ) {
+      gapCodes.push(`FDP|ATOMIC_ROLLBACK|IMAGE_MUTABLE_REFERENCE_INVALID|${service}`);
+      continue;
+    }
+
+    if (
+      immutableReference.slice(0, immutableReference.lastIndexOf(':'))
+      !== mutableReference.slice(0, mutableReference.lastIndexOf(':'))
+    ) {
+      gapCodes.push(`FDP|ATOMIC_ROLLBACK|IMAGE_REPOSITORY_MISMATCH|${service}`);
+      continue;
+    }
+
+    if (!digest || !dyfm_digestPattern.test(digest)) {
+      gapCodes.push(`FDP|ATOMIC_ROLLBACK|IMAGE_DIGEST_INVALID|${service}`);
+      continue;
+    }
+    images.push({
+      service: service,
+      version: version,
+      immutableReference: immutableReference,
+      mutableReference: mutableReference,
+      digest: digest,
+    });
+  }
+  const services: string[] = images.map((image: DyFM_AtomicRollbackImage_Interface): string => image.service);
+
+  if (new Set(services).size !== services.length) {
+    gapCodes.push('FDP|ATOMIC_ROLLBACK|IMAGE_SERVICE_DUPLICATED');
+  }
+
+  return images;
+}
+
+/** Parses bounded post-deployment checks targeting manifest services only. */
+function dyfm_parsePostChecks(value: unknown, gapCodes: string[]): DyFM_AtomicRollbackPostCheck_Interface[] {
+  if (!Array.isArray(value) || value.length < 1 || value.length > 32) {
+    gapCodes.push('FDP|ATOMIC_ROLLBACK|POST_CHECK_SET_CARDINALITY_INVALID');
+
+    return [];
+  }
+  const postChecks: DyFM_AtomicRollbackPostCheck_Interface[] = [];
+
+  for (const candidate of value) {
+    if (!dyfm_isRecord(candidate) || !dyfm_hasExactKeys(candidate, dyfm_exactPostCheckKeys)) {
+      gapCodes.push('FDP|ATOMIC_ROLLBACK|POST_CHECK_SHAPE_INVALID');
+      continue;
+    }
+    const checkId: string | undefined = typeof candidate.checkId === 'string' ? candidate.checkId : undefined;
+    const service: string | undefined = typeof candidate.service === 'string' ? candidate.service : undefined;
+    const endpoint: string | undefined = typeof candidate.endpoint === 'string' ? candidate.endpoint : undefined;
+    const expectedProbeContract: string | undefined = typeof candidate.expectedProbeContract === 'string'
+      ? candidate.expectedProbeContract
+      : undefined;
+
+    if (!checkId || !dyfm_safeIdPattern.test(checkId)) {
+      gapCodes.push('FDP|ATOMIC_ROLLBACK|POST_CHECK_ID_INVALID');
+      continue;
+    }
+
+    if (!service || !dyfm_safeIdPattern.test(service)) {
+      gapCodes.push(`FDP|ATOMIC_ROLLBACK|POST_CHECK_SERVICE_INVALID|${checkId}`);
+      continue;
+    }
+
+    if (!endpoint || !dyfm_isSafePostCheckEndpoint(endpoint, service)) {
+      gapCodes.push(`FDP|ATOMIC_ROLLBACK|POST_CHECK_ENDPOINT_INVALID|${checkId}`);
+      continue;
+    }
+
+    if (!expectedProbeContract || !dyfm_contractPattern.test(expectedProbeContract)) {
+      gapCodes.push(`FDP|ATOMIC_ROLLBACK|POST_CHECK_CONTRACT_INVALID|${checkId}`);
+      continue;
+    }
+    postChecks.push({
+      checkId: checkId,
+      service: service,
+      endpoint: endpoint,
+      expectedProbeContract: expectedProbeContract,
+    });
+  }
+
+  if (
+    new Set(postChecks.map((check: DyFM_AtomicRollbackPostCheck_Interface): string => check.checkId)).size
+    !== postChecks.length
+  ) {
+    gapCodes.push('FDP|ATOMIC_ROLLBACK|POST_CHECK_ID_DUPLICATED');
+  }
+
+  return postChecks;
+}
+
+/** Creates the exact, insertion-order-independent JSON value hashed by every producer and consumer. */
+function dyfm_canonicalTarget(manifest: DyFM_AtomicRollbackManifest_Interface): string {
+  return JSON.stringify({
+    contractVersion: manifest.contractVersion,
+    operationId: manifest.operationId,
+    environment: manifest.environment,
+    authority: {
+      principalId: manifest.authority.principalId,
+      evidenceId: manifest.authority.evidenceId,
+    },
+    sourceRevision: manifest.sourceRevision,
+    configuration: {
+      revision: manifest.configuration.revision,
+      sha256: manifest.configuration.sha256,
+      compatibilityVersion: manifest.configuration.compatibilityVersion,
+      policyChecksum: manifest.configuration.policyChecksum,
+    },
+    images: [ ...manifest.images ].sort(
+      (left: DyFM_AtomicRollbackImage_Interface, right: DyFM_AtomicRollbackImage_Interface): number => left.service
+        .localeCompare(right.service),
+    ).map((image: DyFM_AtomicRollbackImage_Interface): DyFM_AtomicRollbackImage_Interface => ({
+      service: image.service,
+      version: image.version,
+      immutableReference: image.immutableReference,
+      mutableReference: image.mutableReference,
+      digest: image.digest,
+    })),
+    postChecks: [ ...manifest.postChecks ].sort(
+      (left: DyFM_AtomicRollbackPostCheck_Interface, right: DyFM_AtomicRollbackPostCheck_Interface): number => left
+        .checkId.localeCompare(right.checkId),
+    ).map((check: DyFM_AtomicRollbackPostCheck_Interface): DyFM_AtomicRollbackPostCheck_Interface => ({
+      checkId: check.checkId,
+      service: check.service,
+      endpoint: check.endpoint,
+      expectedProbeContract: check.expectedProbeContract,
+    })),
+  });
+}
+
+/** Canonical manifest checksum and strict content-free local validation. */
+export class DyFM_AtomicRollbackManifest_Util {
+  /** Calculates the canonical SHA-256 target checksum for a typed manifest. */
+  public static computeTargetChecksum(manifest: DyFM_AtomicRollbackManifest_Interface): string {
+    return CryptoJS.SHA256(dyfm_canonicalTarget(manifest)).toString();
+  }
+
+  /** Validates an unknown manifest without reflecting rejected content. */
+  public static validate(value: unknown): DyFM_AtomicRollbackLocalValidation_Interface {
+    if (!dyfm_isRecord(value) || !dyfm_hasExactKeys(value, dyfm_exactManifestKeys)) {
+      return {
+        contractVersion: 'fdp-atomic-rollback-local-validation/1',
+        valid: false,
+        environment: 'invalid',
+        operationId: 'invalid',
+        targetChecksum: 'invalid',
+        serviceCount: 0,
+        postCheckCount: 0,
+        gapCodes: [ 'FDP|ATOMIC_ROLLBACK|MANIFEST_SHAPE_INVALID' ],
+      };
+    }
+
+    const gapCodes: string[] = [];
+
+    if (value.contractVersion !== 'fdp-atomic-rollback-manifest/1') {
+      gapCodes.push('FDP|ATOMIC_ROLLBACK|CONTRACT_VERSION_INVALID');
+    }
+
+    if (typeof value.operationId !== 'string' || !dyfm_operationPattern.test(value.operationId)) {
+      gapCodes.push('FDP|ATOMIC_ROLLBACK|OPERATION_ID_INVALID');
+    }
+
+    if (!dyfm_isEnvironment(value.environment)) {
+      gapCodes.push('FDP|ATOMIC_ROLLBACK|ENVIRONMENT_INVALID');
+    }
+
+    if (typeof value.sourceRevision !== 'string' || !dyfm_revisionPattern.test(value.sourceRevision)) {
+      gapCodes.push('FDP|ATOMIC_ROLLBACK|SOURCE_REVISION_INVALID');
+    }
+    const authority: DyFM_AtomicRollbackAuthority_Interface | undefined = dyfm_parseAuthority(
+      value.authority,
+      gapCodes,
+    );
+    const configuration: DyFM_AtomicRollbackConfiguration_Interface | undefined = dyfm_parseConfiguration(
+      value.configuration,
+      gapCodes,
+    );
+    const images: DyFM_AtomicRollbackImage_Interface[] = dyfm_parseImages(value.images, gapCodes);
+    const postChecks: DyFM_AtomicRollbackPostCheck_Interface[] = dyfm_parsePostChecks(value.postChecks, gapCodes);
+    const imageServices: Set<string> = new Set(images.map(
+      (image: DyFM_AtomicRollbackImage_Interface): string => image.service,
+    ));
+
+    if (
+      postChecks.some(
+        (check: DyFM_AtomicRollbackPostCheck_Interface): boolean => !imageServices.has(check.service),
+      )
+    ) {
+      gapCodes.push('FDP|ATOMIC_ROLLBACK|POST_CHECK_SERVICE_NOT_TARGETED');
+    }
+
+    if (typeof value.targetChecksum !== 'string' || !dyfm_sha256Pattern.test(value.targetChecksum)) {
+      gapCodes.push('FDP|ATOMIC_ROLLBACK|TARGET_CHECKSUM_INVALID');
+    }
+
+    let manifest: DyFM_AtomicRollbackManifest_Interface | undefined;
+
+    if (
+      !gapCodes.length
+      && typeof value.operationId === 'string'
+      && dyfm_isEnvironment(value.environment)
+      && authority
+      && typeof value.sourceRevision === 'string'
+      && configuration
+      && images.length > 0
+      && postChecks.length > 0
+      && typeof value.targetChecksum === 'string'
+    ) {
+      manifest = {
+        contractVersion: 'fdp-atomic-rollback-manifest/1',
+        operationId: value.operationId,
+        environment: value.environment,
+        authority: authority,
+        sourceRevision: value.sourceRevision,
+        configuration: configuration,
+        images: images,
+        postChecks: postChecks,
+        targetChecksum: value.targetChecksum,
+      };
+
+      if (this.computeTargetChecksum(manifest) !== value.targetChecksum) {
+        gapCodes.push('FDP|ATOMIC_ROLLBACK|TARGET_CHECKSUM_MISMATCH');
+        manifest = undefined;
+      }
+    }
+
+    const normalizedGapCodes: string[] = [ ...new Set(gapCodes) ].sort();
+
+    return {
+      contractVersion: 'fdp-atomic-rollback-local-validation/1',
+      valid: !normalizedGapCodes.length,
+      environment: dyfm_isEnvironment(value.environment) ? value.environment : 'invalid',
+      operationId: !normalizedGapCodes.length && typeof value.operationId === 'string'
+        ? value.operationId
+        : 'invalid',
+      targetChecksum: !normalizedGapCodes.length && typeof value.targetChecksum === 'string'
+        ? value.targetChecksum
+        : 'invalid',
+      serviceCount: images.length,
+      postCheckCount: postChecks.length,
+      gapCodes: normalizedGapCodes,
+      ...(manifest ? { manifest: manifest } : {}),
+    };
+  }
+}

package/src/_modules/deployment/_models/atomic-rollback-manifest.interface.ts

@@ -0,0 +1,59 @@
+/** Deployment environments accepted by the shared atomic rollback contract. */
+export type DyFM_AtomicRollbackEnvironment_Type = 'test' | 'production';
+
+/** Content-free authority reference supplied by the deployment control plane. */
+export interface DyFM_AtomicRollbackAuthority_Interface {
+  principalId: string;
+  evidenceId: string;
+}
+
+/** Exact version-controlled configuration and database compatibility target. */
+export interface DyFM_AtomicRollbackConfiguration_Interface {
+  revision: string;
+  sha256: string;
+  compatibilityVersion: string;
+  policyChecksum: string;
+}
+
+/** One immutable image target and its mutable release promotion destination. */
+export interface DyFM_AtomicRollbackImage_Interface {
+  service: string;
+  version: string;
+  immutableReference: string;
+  mutableReference: string;
+  digest: string;
+}
+
+/** One bounded post-deployment probe tied to a service in the image set. */
+export interface DyFM_AtomicRollbackPostCheck_Interface {
+  checkId: string;
+  service: string;
+  endpoint: string;
+  expectedProbeContract: string;
+}
+
+/** Complete versioned target for an atomic multi-service rollout or rollback. */
+export interface DyFM_AtomicRollbackManifest_Interface {
+  contractVersion: 'fdp-atomic-rollback-manifest/1';
+  operationId: string;
+  environment: DyFM_AtomicRollbackEnvironment_Type;
+  authority: DyFM_AtomicRollbackAuthority_Interface;
+  sourceRevision: string;
+  configuration: DyFM_AtomicRollbackConfiguration_Interface;
+  images: DyFM_AtomicRollbackImage_Interface[];
+  postChecks: DyFM_AtomicRollbackPostCheck_Interface[];
+  targetChecksum: string;
+}
+
+/** Bounded content-free validation evidence for an unknown manifest value. */
+export interface DyFM_AtomicRollbackLocalValidation_Interface {
+  contractVersion: 'fdp-atomic-rollback-local-validation/1';
+  valid: boolean;
+  environment: DyFM_AtomicRollbackEnvironment_Type | 'invalid';
+  operationId: string | 'invalid';
+  targetChecksum: string | 'invalid';
+  serviceCount: number;
+  postCheckCount: number;
+  gapCodes: string[];
+  manifest?: DyFM_AtomicRollbackManifest_Interface;
+}

package/src/_modules/deployment/index.ts

@@ -0,0 +1,2 @@
+export * from './_collections/atomic-rollback-manifest.util';
+export * from './_models/atomic-rollback-manifest.interface';