@empire-builder-kit/nx 1.0.0-rc.4 → 1.0.0-rc.41

package/src/workspace-deployment/migration-evidence.d.ts

@@ -0,0 +1,29 @@
+export declare const WORKSPACE_DEPLOYMENT_MIGRATION_SCHEMA_VERSION: 1;
+export type WorkspaceDeploymentMigrationStage = 'development' | 'staging' | 'production';
+export interface WorkspaceDeploymentMigrationCoordinate {
+    accountId: string;
+    region: string;
+    stage: WorkspaceDeploymentMigrationStage;
+}
+export interface WorkspaceDeploymentMigrationEvidence {
+    decision: 'claim-existing-workspace-deployments';
+    kind: 'ebk-workspace-deployment-migration';
+    previousPolicySha256: string;
+    schemaVersion: typeof WORKSPACE_DEPLOYMENT_MIGRATION_SCHEMA_VERSION;
+    tuples: readonly {
+        accountId: string;
+        occupancy: 'empty' | 'existing-workspace';
+        region: string;
+        resourceIdentityDigests: readonly string[];
+        stage: WorkspaceDeploymentMigrationStage;
+    }[];
+    workspaceDeploymentId: string;
+    workspaceName: string;
+}
+export declare function validateWorkspaceDeploymentMigrationEvidence(input: {
+    evidence: unknown;
+    expectedCoordinates: readonly WorkspaceDeploymentMigrationCoordinate[];
+    expectedPreviousPolicySha256?: string;
+    workspaceDeploymentId: string;
+    workspaceName?: string;
+}): WorkspaceDeploymentMigrationEvidence;

package/src/workspace-deployment/migration-evidence.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WORKSPACE_DEPLOYMENT_MIGRATION_SCHEMA_VERSION = void 0;
+exports.validateWorkspaceDeploymentMigrationEvidence = validateWorkspaceDeploymentMigrationEvidence;
+exports.WORKSPACE_DEPLOYMENT_MIGRATION_SCHEMA_VERSION = 1;
+const SHA256 = /^[a-f0-9]{64}$/u;
+const WORKSPACE_NAME = /^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/u;
+function exactKeys(value, expected) {
+    return (JSON.stringify(Object.keys(value).sort()) ===
+        JSON.stringify([...expected].sort()));
+}
+function hasExactOccupancyTuples(value, expected) {
+    if (!Array.isArray(value) || value.length > 3)
+        return false;
+    if (value.length !== expected.length)
+        return false;
+    return value.every((candidate, index) => {
+        if (!candidate ||
+            typeof candidate !== 'object' ||
+            Array.isArray(candidate)) {
+            return false;
+        }
+        const tuple = candidate;
+        const digests = tuple.resourceIdentityDigests;
+        if (!exactKeys(tuple, [
+            'accountId',
+            'occupancy',
+            'region',
+            'resourceIdentityDigests',
+            'stage',
+        ]) ||
+            tuple.accountId !== expected[index]?.accountId ||
+            tuple.region !== expected[index]?.region ||
+            tuple.stage !== expected[index]?.stage ||
+            (tuple.occupancy !== 'empty' &&
+                tuple.occupancy !== 'existing-workspace') ||
+            !Array.isArray(digests) ||
+            digests.length > 256 ||
+            digests.some((digest) => typeof digest !== 'string' || !SHA256.test(digest)) ||
+            new Set(digests).size !== digests.length ||
+            JSON.stringify([...digests].sort()) !== JSON.stringify(digests)) {
+            return false;
+        }
+        return tuple.occupancy === 'empty'
+            ? digests.length === 0
+            : digests.length > 0;
+    });
+}
+function validateWorkspaceDeploymentMigrationEvidence(input) {
+    if (!input.evidence ||
+        typeof input.evidence !== 'object' ||
+        Array.isArray(input.evidence)) {
+        throw new Error('Workspace deployment migration evidence must be one exact object.');
+    }
+    const evidence = input.evidence;
+    if (!exactKeys(evidence, [
+        'decision',
+        'kind',
+        'previousPolicySha256',
+        'schemaVersion',
+        'tuples',
+        'workspaceDeploymentId',
+        'workspaceName',
+    ]) ||
+        evidence.kind !== 'ebk-workspace-deployment-migration' ||
+        evidence.schemaVersion !== exports.WORKSPACE_DEPLOYMENT_MIGRATION_SCHEMA_VERSION ||
+        evidence.decision !== 'claim-existing-workspace-deployments' ||
+        typeof evidence.workspaceName !== 'string' ||
+        evidence.workspaceName.length > 214 ||
+        !WORKSPACE_NAME.test(evidence.workspaceName) ||
+        (input.workspaceName !== undefined &&
+            evidence.workspaceName !== input.workspaceName) ||
+        evidence.workspaceDeploymentId !== input.workspaceDeploymentId ||
+        typeof evidence.previousPolicySha256 !== 'string' ||
+        !SHA256.test(evidence.previousPolicySha256) ||
+        (input.expectedPreviousPolicySha256 !== undefined &&
+            evidence.previousPolicySha256 !== input.expectedPreviousPolicySha256) ||
+        !hasExactOccupancyTuples(evidence.tuples, input.expectedCoordinates)) {
+        throw new Error('Workspace deployment migration evidence does not exactly bind the prior policy, generated workspace identity, and configured AWS tuples.');
+    }
+    return evidence;
+}
+//# sourceMappingURL=migration-evidence.js.map

package/src/workspace-deployment/migration.d.ts

@@ -0,0 +1,27 @@
+import { type RepositoryOperatingPolicy } from '../repository-policy/index.js';
+export { WORKSPACE_DEPLOYMENT_MIGRATION_SCHEMA_VERSION, validateWorkspaceDeploymentMigrationEvidence, type WorkspaceDeploymentMigrationCoordinate, type WorkspaceDeploymentMigrationEvidence, type WorkspaceDeploymentMigrationStage, } from './migration-evidence.js';
+export declare function validateRepositoryPolicyWorkspaceDeploymentMigration(input: {
+    evidence: unknown;
+    policy: RepositoryOperatingPolicy;
+    workspaceName: string;
+}): void;
+export declare function migrateRepositoryPolicyWorkspaceDeploymentIdentity(input: {
+    evidence: unknown;
+    evidenceBytes: string;
+    evidencePath: string;
+    legacyPolicy: Readonly<Record<string, unknown>>;
+    previousPolicyBytes: string;
+    sourceLabel: string;
+    workspaceDeploymentId: string;
+    workspaceName: string;
+}): RepositoryOperatingPolicy;
+export declare function renewRepositoryPolicyWorkspaceDeploymentMigration(input: {
+    evidence: unknown;
+    evidenceBytes: string;
+    evidencePath: string;
+    previousEvidencePath: string;
+    previousPolicyBytes: string;
+    proposedPolicy: RepositoryOperatingPolicy;
+    sourceLabel: string;
+    workspaceName: string;
+}): RepositoryOperatingPolicy;

package/src/workspace-deployment/migration.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateWorkspaceDeploymentMigrationEvidence = exports.WORKSPACE_DEPLOYMENT_MIGRATION_SCHEMA_VERSION = void 0;
+exports.validateRepositoryPolicyWorkspaceDeploymentMigration = validateRepositoryPolicyWorkspaceDeploymentMigration;
+exports.migrateRepositoryPolicyWorkspaceDeploymentIdentity = migrateRepositoryPolicyWorkspaceDeploymentIdentity;
+exports.renewRepositoryPolicyWorkspaceDeploymentMigration = renewRepositoryPolicyWorkspaceDeploymentMigration;
+const node_crypto_1 = require("node:crypto");
+const index_js_1 = require("../repository-policy/index.js");
+const identity_js_1 = require("./identity.js");
+const migration_evidence_js_1 = require("./migration-evidence.js");
+var migration_evidence_js_2 = require("./migration-evidence.js");
+Object.defineProperty(exports, "WORKSPACE_DEPLOYMENT_MIGRATION_SCHEMA_VERSION", { enumerable: true, get: function () { return migration_evidence_js_2.WORKSPACE_DEPLOYMENT_MIGRATION_SCHEMA_VERSION; } });
+Object.defineProperty(exports, "validateWorkspaceDeploymentMigrationEvidence", { enumerable: true, get: function () { return migration_evidence_js_2.validateWorkspaceDeploymentMigrationEvidence; } });
+const WORKSPACE_NAME = /^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/u;
+function expectedTupleCoordinates(policy) {
+    let region;
+    let accounts;
+    try {
+        region = (0, index_js_1.configuredDeploymentRegion)(policy.deploymentRegion);
+        accounts = (0, index_js_1.configuredDeploymentAccountTopology)(policy.deploymentProfile, policy.deploymentAccounts);
+    }
+    catch (error) {
+        throw new Error(`Workspace deployment migration must bind the exact intended Region and every active-stage account in the same policy change: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return (0, index_js_1.activeDeploymentStages)(policy.deploymentProfile)
+        .map((stage) => ({
+        accountId: accounts[stage],
+        region,
+        stage,
+    }))
+        .sort((left, right) => left.stage < right.stage ? -1 : left.stage > right.stage ? 1 : 0);
+}
+function requireWorkspaceName(workspaceName) {
+    if (workspaceName.length > 214 || !WORKSPACE_NAME.test(workspaceName)) {
+        throw new Error('Workspace deployment migration requires the exact generated root package name.');
+    }
+    return workspaceName;
+}
+function migrationProvenance(input) {
+    return {
+        evidencePath: input.evidencePath,
+        evidenceSha256: (0, node_crypto_1.createHash)('sha256')
+            .update(input.evidenceBytes, 'utf8')
+            .digest('hex'),
+        kind: 'migrated',
+        schemaVersion: 1,
+    };
+}
+function validateRepositoryPolicyWorkspaceDeploymentMigration(input) {
+    if (input.policy.workspaceDeploymentProvenance.kind !== 'migrated') {
+        throw new Error('Workspace deployment migration validation requires migrated provenance.');
+    }
+    (0, migration_evidence_js_1.validateWorkspaceDeploymentMigrationEvidence)({
+        evidence: input.evidence,
+        expectedCoordinates: expectedTupleCoordinates(input.policy),
+        workspaceDeploymentId: input.policy.workspaceDeploymentId,
+        workspaceName: requireWorkspaceName(input.workspaceName),
+    });
+}
+function migrateRepositoryPolicyWorkspaceDeploymentIdentity(input) {
+    const workspaceDeploymentId = (0, identity_js_1.normalizeWorkspaceDeploymentId)(input.workspaceDeploymentId);
+    const workspaceName = requireWorkspaceName(input.workspaceName);
+    const existingWorkspaceDeploymentId = input.legacyPolicy.workspaceDeploymentId;
+    if (existingWorkspaceDeploymentId !== undefined &&
+        existingWorkspaceDeploymentId !== workspaceDeploymentId) {
+        throw new Error('Workspace deployment identity is immutable after it is committed.');
+    }
+    if (Object.prototype.hasOwnProperty.call(input.legacyPolicy, 'workspaceDeploymentProvenance')) {
+        throw new Error('Workspace deployment provenance is already committed and cannot be replaced through prerelease migration.');
+    }
+    const legacyPolicy = { ...input.legacyPolicy };
+    delete legacyPolicy.workspaceDeploymentMigration;
+    const policy = (0, index_js_1.parseRepositoryOperatingPolicy)(JSON.stringify({
+        ...legacyPolicy,
+        workspaceDeploymentId,
+        workspaceDeploymentProvenance: migrationProvenance(input),
+    }), `${input.sourceLabel} with explicit workspace-deployment migration`);
+    (0, migration_evidence_js_1.validateWorkspaceDeploymentMigrationEvidence)({
+        evidence: input.evidence,
+        expectedCoordinates: expectedTupleCoordinates(policy),
+        expectedPreviousPolicySha256: (0, node_crypto_1.createHash)('sha256')
+            .update(input.previousPolicyBytes)
+            .digest('hex'),
+        workspaceDeploymentId,
+        workspaceName,
+    });
+    return policy;
+}
+function renewRepositoryPolicyWorkspaceDeploymentMigration(input) {
+    if (input.evidencePath === input.previousEvidencePath) {
+        throw new Error('A migrated workspace topology change requires a new versioned evidence path so prior ownership evidence remains retained.');
+    }
+    const workspaceName = requireWorkspaceName(input.workspaceName);
+    const policy = (0, index_js_1.parseRepositoryOperatingPolicy)(JSON.stringify({
+        ...input.proposedPolicy,
+        workspaceDeploymentProvenance: migrationProvenance(input),
+    }), `${input.sourceLabel} with renewed workspace-deployment migration evidence`);
+    (0, migration_evidence_js_1.validateWorkspaceDeploymentMigrationEvidence)({
+        evidence: input.evidence,
+        expectedCoordinates: expectedTupleCoordinates(policy),
+        expectedPreviousPolicySha256: (0, node_crypto_1.createHash)('sha256')
+            .update(input.previousPolicyBytes)
+            .digest('hex'),
+        workspaceDeploymentId: policy.workspaceDeploymentId,
+        workspaceName,
+    });
+    return policy;
+}
+//# sourceMappingURL=migration.js.map

package/src/workspace-deployment/ownership.d.ts

@@ -0,0 +1,81 @@
+import { SSMClient, type SSMClientConfig } from '@aws-sdk/client-ssm';
+import { type CanonicalDeploymentStage, type RepositoryOperatingPolicy } from '../repository-policy/index.js';
+export declare const WORKSPACE_STAGE_OWNERSHIP_SCHEMA_VERSION: 1;
+export interface WorkspaceDeploymentIdentity {
+    workspaceDeploymentId: string;
+    workspaceName: string;
+}
+export interface WorkspaceStageOwnershipTarget extends WorkspaceDeploymentIdentity {
+    accountId: string;
+    region: string;
+    stage: CanonicalDeploymentStage;
+}
+type WorkspaceStageOwnerIdentity = Pick<WorkspaceStageOwnershipTarget, 'accountId' | 'region' | 'stage' | 'workspaceDeploymentId'>;
+export interface WorkspaceStageOwnerRecord {
+    accountId: string;
+    kind: 'ebk-workspace-stage-owner';
+    region: string;
+    schemaVersion: typeof WORKSPACE_STAGE_OWNERSHIP_SCHEMA_VERSION;
+    stage: CanonicalDeploymentStage;
+    workspaceDeploymentId: string;
+}
+export interface WorkspaceStageOwnershipClaimPlan {
+    digestInput: string;
+    parameterArn: string;
+    parameterName: string;
+    stackName: string;
+    template: Readonly<Record<string, unknown>>;
+    value: string;
+}
+export type WorkspaceStageOwnershipInspection = {
+    accountId: string;
+    expectedOwner: WorkspaceStageOwnerRecord;
+    parameterArn: string;
+    parameterName: string;
+    region: string;
+    stage: CanonicalDeploymentStage;
+    status: 'owned';
+} | {
+    accountId: string;
+    expectedOwner: WorkspaceStageOwnerRecord;
+    parameterArn: string;
+    parameterName: string;
+    region: string;
+    stage: CanonicalDeploymentStage;
+    status: 'unclaimed';
+} | {
+    accountId: string;
+    actualOwner?: WorkspaceStageOwnerRecord;
+    expectedOwner: WorkspaceStageOwnerRecord;
+    parameterArn: string;
+    parameterName: string;
+    reason: 'different-owner' | 'malformed-record' | 'unexpected-identity';
+    region: string;
+    stage: CanonicalDeploymentStage;
+    status: 'conflict';
+};
+export interface WorkspaceStageOwnershipInspectionOptions {
+    client?: Pick<SSMClient, 'send'>;
+    clientFactory?: (configuration: SSMClientConfig) => Pick<SSMClient, 'send'>;
+    configFilepath?: string;
+    credentialsFilepath?: string;
+    profile?: string;
+}
+export declare function workspaceStageOwnerParameterName(stage: CanonicalDeploymentStage): string;
+export declare function workspaceStageOwnerParameterArn(input: Pick<WorkspaceStageOwnershipTarget, 'accountId' | 'region' | 'stage'>): string;
+export declare function createWorkspaceStageOwnerRecord(input: WorkspaceStageOwnerIdentity): WorkspaceStageOwnerRecord;
+export declare function canonicalWorkspaceStageOwner(input: WorkspaceStageOwnerIdentity): string;
+export declare function workspaceStageOwnershipTarget(workspaceRoot: string, stage: CanonicalDeploymentStage, policy?: RepositoryOperatingPolicy): WorkspaceStageOwnershipTarget;
+export declare function createWorkspaceStageOwnershipClaimPlan(input: WorkspaceStageOwnershipTarget): WorkspaceStageOwnershipClaimPlan;
+/** Bind the stage-authority change set to the already-claimed tuple. AWS
+ * resolves the exact SSM value while evaluating CloudFormation Rules, before
+ * any IAM resource in the authority stack can be changed. */
+export declare function bindStageAuthorityTemplateToWorkspaceOwner(template: Readonly<Record<string, unknown>>, input: WorkspaceStageOwnershipTarget): Readonly<Record<string, unknown>>;
+export declare function inspectWorkspaceStageOwnership(input: WorkspaceStageOwnershipTarget, options?: WorkspaceStageOwnershipInspectionOptions): Promise<WorkspaceStageOwnershipInspection>;
+export declare function assertWorkspaceStageOwnership(input: WorkspaceStageOwnershipTarget, options?: WorkspaceStageOwnershipInspectionOptions): Promise<WorkspaceStageOwnershipInspection & {
+    status: 'owned';
+}>;
+export declare function assertWorkspaceStageOwnershipForWorkspace(workspaceRoot: string, stage: CanonicalDeploymentStage, options?: WorkspaceStageOwnershipInspectionOptions): Promise<WorkspaceStageOwnershipInspection & {
+    status: 'owned';
+}>;
+export {};