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

package/src/generators/slice/built-in-plan-authorization-infrastructure-files.js

@@ -1,235 +1,930 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.renderStandardSliceAuthorizationInfrastructureFiles = renderStandardSliceAuthorizationInfrastructureFiles;
-const MACHINE_CLIENT_PROVISIONER_SOURCE = `import boto3,datetime,json,logging,os,urllib.request
-from botocore.exceptions import ClientError
-cognito=boto3.client("cognito-idp")
-secrets=boto3.client("secretsmanager")
-logger=logging.getLogger()
-logger.setLevel(logging.INFO)
-
-def emit(event,level,outcome,message,error_code=None):
-    attributes={
-        "requestType":str(event.get("RequestType","unknown"))[:32],
+/**
+ * Managed Node.js CloudFormation custom-resource handler. The handler string
+ * 'authorization/machine-client-provisioner.handler' and the custom-resource
+ * contract (physical id, Data keys, secret document) are unchanged from the
+ * retired Python provisioner; only the two owner-approved fixes differ:
+ * rotation refusals precede any Cognito create, and Delete acts only on the
+ * physical id this provisioner returns.
+ */
+function machineClientProvisionerSource(name) {
+    return `import { request } from 'node:https';
+import {
+  CognitoIdentityProviderClient,
+  CreateUserPoolClientCommand,
+  DeleteUserPoolClientCommand,
+  DescribeUserPoolClientCommand,
+  ListUserPoolClientsCommand,
+} from '@aws-sdk/client-cognito-identity-provider';
+import {
+  GetSecretValueCommand,
+  PutSecretValueCommand,
+  SecretsManagerClient,
+  UpdateSecretVersionStageCommand,
+} from '@aws-sdk/client-secrets-manager';
+import { createLogger, type Logger } from '@empire-builder-kit/runtime/logging';
+
+/**
+ * AWS-internal CloudFormation custom resource for the Slice's confidential
+ * Cognito machine client. The client secret moves only from Cognito into the
+ * generated Secrets Manager container; it never reaches a response, a log
+ * record, or an error reason.
+ */
+export interface MachineClientProperties {
+  ClientName: string;
+  CredentialGeneration: string;
+  ResourceServerIdentifier: string;
+  RetirePreviousGeneration: string;
+  Scopes: string[];
+  SecretArn: string;
+  UserPoolId: string;
+}
+
+export interface MachineClientProvisionerEvent {
+  LogicalResourceId: string;
+  PhysicalResourceId?: string;
+  RequestId: string;
+  RequestType: string;
+  ResourceProperties: MachineClientProperties;
+  ResponseURL: string;
+  StackId: string;
+}
+
+export interface MachineClientProvisionerDependencies {
+  cognito: { send(command: any): Promise<any> };
+  logger: Logger;
+  /** Resolves only after CloudFormation has accepted the response. */
+  respond(responseUrl: string, body: string): Promise<void>;
+  secrets: { send(command: any): Promise<any> };
+}
+
+interface CredentialVersion {
+  document: Record<string, unknown>;
+  versionId: string;
+}
+
+// Reasons keep the exact tokens CloudFormation showed before the Node.js
+// port. Bundles are minified, so names are literals, never class names.
+type ProvisioningErrorName =
+  | 'AttributeError'
+  | 'HTTPError'
+  | 'JSONDecodeError'
+  | 'KeyError'
+  | 'TypeError'
+  | 'URLError'
+  | 'ValueError';
+
+const PROVISIONING_ERROR_NAMES = new Set<string>([
+  'AttributeError',
+  'HTTPError',
+  'JSONDecodeError',
+  'KeyError',
+  'TypeError',
+  'URLError',
+  'ValueError',
+]);
+
+class ProvisioningError extends Error {
+  constructor(name: ProvisioningErrorName, message: string) {
+    super(message);
+    this.name = name;
+  }
+}
+
+function refuse(message: string): ProvisioningError {
+  return new ProvisioningError('ValueError', message);
+}
+
+function errorField(error: unknown, field: '$metadata' | 'name'): unknown {
+  return typeof error === 'object' && error !== null
+    ? (error as Record<string, unknown>)[field]
+    : undefined;
+}
+
+function reasonFor(error: unknown): string {
+  const name = errorField(error, 'name');
+  if (typeof name === 'string' && PROVISIONING_ERROR_NAMES.has(name)) {
+    return name;
+  }
+  const metadata = errorField(error, '$metadata');
+  if (typeof metadata === 'object' && metadata !== null) return 'ClientError';
+  return typeof name === 'string' && /^[A-Za-z][A-Za-z0-9]{0,127}$/.test(name)
+    ? name
+    : 'Error';
+}
+
+function isNamed(error: unknown, name: string): boolean {
+  return errorField(error, 'name') === name;
+}
+
+/** JSON truthiness exactly as the original provisioner evaluated it. */
+function present(value: unknown): boolean {
+  if (Array.isArray(value)) return value.length > 0;
+  if (typeof value === 'object' && value !== null) {
+    return Object.keys(value).length > 0;
+  }
+  return Boolean(value);
+}
+
+function required(record: Record<string, unknown>, key: string): unknown {
+  if (!(key in record)) throw new ProvisioningError('KeyError', key);
+  return record[key];
+}
+
+function slotOf(value: unknown): string {
+  if (typeof value !== 'string') {
+    throw new ProvisioningError(
+      'AttributeError',
+      'Machine credential generation is not text.',
+    );
+  }
+  return value.split('-', 1)[0];
+}
+
+function parseCredentialDocument(value: unknown): Record<string, unknown> {
+  let document: unknown;
+  try {
+    document = JSON.parse(value as string);
+  } catch {
+    throw new ProvisioningError(
+      'JSONDecodeError',
+      'Machine credential document is not JSON.',
+    );
+  }
+  if (
+    typeof document !== 'object' ||
+    document === null ||
+    Array.isArray(document)
+  ) {
+    throw new ProvisioningError(
+      'TypeError',
+      'Machine credential document is not a JSON object.',
+    );
+  }
+  return document as Record<string, unknown>;
+}
+
+function logDimension(value: string | undefined): string {
+  const normalized = (value ?? '').trim();
+  return normalized.length > 0 &&
+    normalized.length <= 128 &&
+    [...normalized].every((character) => {
+      const code = character.charCodeAt(0);
+      return code > 31 && code !== 127;
+    })
+    ? normalized
+    : 'unknown';
+}
+
+export function createMachineClientProvisioner(
+  dependencies: MachineClientProvisionerDependencies,
+): (event: MachineClientProvisionerEvent) => Promise<void> {
+  const { cognito, logger, respond, secrets } = dependencies;
+
+  async function readVersion(
+    secretArn: string,
+    stage: 'AWSCURRENT' | 'AWSPREVIOUS',
+  ): Promise<CredentialVersion | undefined> {
+    let value: Record<string, unknown>;
+    try {
+      value = await secrets.send(
+        new GetSecretValueCommand({ SecretId: secretArn, VersionStage: stage }),
+      );
+    } catch (error) {
+      if (
+        isNamed(error, 'ResourceNotFoundException') ||
+        isNamed(error, 'InvalidRequestException')
+      ) {
+        return undefined;
+      }
+      throw error;
+    }
+    const document = parseCredentialDocument(required(value, 'SecretString'));
+    return {
+      document,
+      versionId: required(value, 'VersionId') as string,
+    };
+  }
+
+  async function findClient(
+    userPoolId: string,
+    clientName: string,
+  ): Promise<Record<string, unknown> | undefined> {
+    let nextToken: string | undefined;
+    do {
+      const page = await cognito.send(
+        new ListUserPoolClientsCommand({
+          UserPoolId: userPoolId,
+          MaxResults: 60,
+          ...(nextToken ? { NextToken: nextToken } : {}),
+        }),
+      );
+      for (const summary of page.UserPoolClients ?? []) {
+        if (summary.ClientName === clientName) {
+          const described = await cognito.send(
+            new DescribeUserPoolClientCommand({
+              UserPoolId: userPoolId,
+              ClientId: required(summary, 'ClientId') as string,
+            }),
+          );
+          return required(described, 'UserPoolClient') as Record<
+            string,
+            unknown
+          >;
+        }
+      }
+      nextToken = page.NextToken;
+    } while (nextToken);
+    return undefined;
+  }
+
+  async function ensureClient(
+    properties: MachineClientProperties,
+  ): Promise<Record<string, unknown>> {
+    const client = await findClient(
+      properties.UserPoolId,
+      properties.ClientName,
+    );
+    if (client && present(client)) return client;
+    const created = await cognito.send(
+      new CreateUserPoolClientCommand({
+        UserPoolId: properties.UserPoolId,
+        ClientName: properties.ClientName,
+        GenerateSecret: true,
+        AllowedOAuthFlows: ['client_credentials'],
+        AllowedOAuthFlowsUserPoolClient: true,
+        AllowedOAuthScopes: properties.Scopes,
+        AccessTokenValidity: 15,
+        TokenValidityUnits: { AccessToken: 'minutes' },
+        EnableTokenRevocation: true,
+        PreventUserExistenceErrors: 'ENABLED',
+      }),
+    );
+    return required(created, 'UserPoolClient') as Record<string, unknown>;
+  }
+
+  async function deleteClient(
+    userPoolId: string,
+    clientId: unknown,
+  ): Promise<void> {
+    try {
+      await cognito.send(
+        new DeleteUserPoolClientCommand({
+          UserPoolId: userPoolId,
+          ClientId: clientId as string,
+        }),
+      );
+    } catch (error) {
+      if (!isNamed(error, 'ResourceNotFoundException')) throw error;
     }
-    if error_code:
-        attributes["errorCode"]=str(error_code)[:128]
-    record={
-        "attributes":attributes,
-        "component":"machine-client-provisioner",
-        "feature":"authorization",
-        "level":level,
-        "message":message,
-        "operation":"machine-client.provision",
-        "outcome":outcome,
-        "requestId":str(event.get("RequestId","unknown"))[:128],
-        "schemaVersion":1,
-        "slice":os.environ.get("EBK_SLICE",""),
-        "stage":os.environ.get("EBK_STAGE",""),
-        "timestamp":datetime.datetime.now(
-            datetime.timezone.utc
-        ).isoformat(timespec="milliseconds").replace("+00:00","Z"),
-        "workspace":os.environ.get("EBK_WORKSPACE",""),
+  }
+
+  function record(
+    event: MachineClientProvisionerEvent,
+    outcome: 'failure' | 'success',
+    errorCode?: string,
+    skipped?: string,
+  ): void {
+    const attributes: Record<string, string> = {
+      requestType: String(event.RequestType ?? 'unknown').slice(0, 32),
+    };
+    if (errorCode) attributes.errorCode = errorCode.slice(0, 128);
+    if (skipped) attributes.skipped = skipped;
+    const input = {
+      attributes,
+      context: {
+        requestId: String(event.RequestId ?? 'unknown').slice(0, 128),
+      },
+      outcome,
+    };
+    if (outcome === 'success') {
+      logger.info('Machine client provisioning completed.', input);
+    } else {
+      logger.error('Machine client provisioning failed.', input);
     }
-    encoded=json.dumps(record,separators=(",",":"),sort_keys=True)
-    if level=="ERROR":
-        logger.error(encoded)
-    else:
-        logger.info(encoded)
-
-def respond(event,status,physical,data=None,reason=None):
-    body=json.dumps({
-        "Status":status,
-        "Reason":reason or status,
-        "PhysicalResourceId":physical,
-        "StackId":event["StackId"],
-        "RequestId":event["RequestId"],
-        "LogicalResourceId":event["LogicalResourceId"],
-        "NoEcho":False,
-        "Data":data or {},
-    }).encode()
-    request=urllib.request.Request(
-        event["ResponseURL"],
-        data=body,
-        headers={"content-type":"","content-length":str(len(body))},
-        method="PUT",
-    )
-    with urllib.request.urlopen(request):
-        pass
-
-def read_version(secret_arn,stage):
-    try:
-        value=secrets.get_secret_value(
-            SecretId=secret_arn,
-            VersionStage=stage,
-        )
-        document=json.loads(value["SecretString"])
-        document["_versionId"]=value["VersionId"]
-        return document
-    except ClientError as error:
-        if error.response["Error"]["Code"] in (
-            "ResourceNotFoundException",
-            "InvalidRequestException",
-        ):
-            return None
-        raise
-
-def find_client(user_pool_id,client_name):
-    paginator=cognito.get_paginator("list_user_pool_clients")
-    for page in paginator.paginate(UserPoolId=user_pool_id,MaxResults=60):
-        for summary in page.get("UserPoolClients",[]):
-            if summary.get("ClientName")==client_name:
-                return cognito.describe_user_pool_client(
-                    UserPoolId=user_pool_id,
-                    ClientId=summary["ClientId"],
-                )["UserPoolClient"]
-    return None
-
-def ensure_client(properties):
-    client=find_client(properties["UserPoolId"],properties["ClientName"])
-    if client:
-        return client
-    return cognito.create_user_pool_client(
-        UserPoolId=properties["UserPoolId"],
-        ClientName=properties["ClientName"],
-        GenerateSecret=True,
-        AllowedOAuthFlows=["client_credentials"],
-        AllowedOAuthFlowsUserPoolClient=True,
-        AllowedOAuthScopes=properties["Scopes"],
-        AccessTokenValidity=15,
-        TokenValidityUnits={"AccessToken":"minutes"},
-        EnableTokenRevocation=True,
-        PreventUserExistenceErrors="ENABLED",
-    )["UserPoolClient"]
-
-def delete_client(user_pool_id,client_id):
-    try:
-        cognito.delete_user_pool_client(
-            UserPoolId=user_pool_id,
-            ClientId=client_id,
-        )
-    except ClientError as error:
-        if error.response["Error"]["Code"]!="ResourceNotFoundException":
-            raise
-
-def handler(event,context):
-    properties=event["ResourceProperties"]
-    physical="ebk-machine-client-"+properties["ResourceServerIdentifier"]
-    try:
-        current=read_version(properties["SecretArn"],"AWSCURRENT")
-        previous=read_version(properties["SecretArn"],"AWSPREVIOUS")
-        if event["RequestType"]=="Delete":
-            for document in (current,previous):
-                if document and document.get("clientId"):
-                    delete_client(properties["UserPoolId"],document["clientId"])
-            emit(
-                event,
-                "INFO",
-                "success",
-                "Machine client provisioning completed.",
-            )
-            respond(event,"SUCCESS",physical)
-            return
-
-        generation=properties["CredentialGeneration"]
-        retire=properties["RetirePreviousGeneration"]=="true"
-        if retire and not current:
-            raise ValueError("No current machine credential generation exists.")
-        client=ensure_client(properties)
-        client_id=client["ClientId"]
-        rollback=(
-            current
-            and previous
-            and current.get("generation")!=generation
-            and previous.get("generation")==generation
-        )
-        if rollback:
-            if retire:
-                raise ValueError("Restore and prove the rollback generation before retiring the displaced generation.")
-            if previous.get("clientId")!=client_id:
-                raise ValueError("Rollback generation does not match its existing Cognito client.")
-            secrets.update_secret_version_stage(
-                SecretId=properties["SecretArn"],
-                VersionStage="AWSCURRENT",
-                MoveToVersionId=previous["_versionId"],
-                RemoveFromVersionId=current["_versionId"],
-            )
-            current,previous=previous,current
-        elif current and current.get("generation")!=generation:
-            if previous:
-                raise ValueError("Retire the previous generation before beginning another rotation.")
-            old_slot=current["generation"].split("-",1)[0]
-            new_slot=generation.split("-",1)[0]
-            if old_slot==new_slot:
-                raise ValueError("Credential generation must alternate blue and green slots.")
-            if retire:
-                raise ValueError("Create and prove a new generation before retiring the previous one.")
-
-        if not rollback and (
-            not current
-            or current.get("generation")!=generation
-            or current.get("clientId")!=client_id
-        ):
-            secrets.put_secret_value(
-                SecretId=properties["SecretArn"],
-                SecretString=json.dumps({
-                    "clientId":client_id,
-                    "clientSecret":client["ClientSecret"],
-                    "generation":generation,
-                },separators=(",",":")),
-            )
-            previous=current
-
-        if retire:
-            if not previous:
-                raise ValueError("No previous machine credential generation exists.")
-            previous_id=previous.get("clientId")
-            if previous_id and previous_id!=client_id:
-                delete_client(properties["UserPoolId"],previous_id)
-            version_id=previous.get("_versionId")
-            if version_id:
-                secrets.update_secret_version_stage(
-                    SecretId=properties["SecretArn"],
-                    VersionStage="AWSPREVIOUS",
-                    RemoveFromVersionId=version_id,
-                )
-
-        accepted_client_ids=[client_id]
+  }
+
+  async function respondTo(
+    event: MachineClientProvisionerEvent,
+    status: 'FAILED' | 'SUCCESS',
+    physicalResourceId: string,
+    data?: Record<string, string>,
+    reason?: string,
+  ): Promise<void> {
+    const body = JSON.stringify({
+      Status: status,
+      Reason: reason || status,
+      PhysicalResourceId: physicalResourceId,
+      StackId: event.StackId,
+      RequestId: event.RequestId,
+      LogicalResourceId: event.LogicalResourceId,
+      NoEcho: false,
+      Data: data ?? {},
+    });
+    await respond(event.ResponseURL, body);
+  }
+
+  return async function provisionMachineClient(event) {
+    const properties = event.ResourceProperties;
+    const physical =
+      'ebk-machine-client-' + properties.ResourceServerIdentifier;
+    // Delete acts only on the resource this provisioner returned. Any other
+    // physical id is acknowledged without reading or deleting a credential.
+    const foreignDelete =
+      event.RequestType === 'Delete' && event.PhysicalResourceId !== physical;
+    const responsePhysicalId =
+      foreignDelete && event.PhysicalResourceId
+        ? event.PhysicalResourceId
+        : physical;
+    try {
+      if (foreignDelete) {
+        record(event, 'success', undefined, 'foreign-physical-resource-id');
+        await respondTo(event, 'SUCCESS', responsePhysicalId);
+        return;
+      }
+      const property = (key: keyof MachineClientProperties) =>
+        required(properties as unknown as Record<string, unknown>, key);
+      let current = await readVersion(
+        property('SecretArn') as string,
+        'AWSCURRENT',
+      );
+      let previous = await readVersion(
+        property('SecretArn') as string,
+        'AWSPREVIOUS',
+      );
+      if (event.RequestType === 'Delete') {
+        for (const version of [current, previous]) {
+          if (version && present(version.document.clientId)) {
+            await deleteClient(
+              properties.UserPoolId,
+              version.document.clientId,
+            );
+          }
+        }
+        record(event, 'success');
+        await respondTo(event, 'SUCCESS', responsePhysicalId);
+        return;
+      }
+
+      const generation = property('CredentialGeneration');
+      const retire = property('RetirePreviousGeneration') === 'true';
+      if (retire && !current) {
+        throw refuse('No current machine credential generation exists.');
+      }
+      const rollbackFrom =
+        current &&
+        previous &&
+        current.document.generation !== generation &&
+        previous.document.generation === generation
+          ? { current, previous }
+          : undefined;
+      // Every rotation refusal precedes the first Cognito call, so a refused
+      // deployment never creates an orphaned client.
+      if (rollbackFrom) {
+        if (retire) {
+          throw refuse(
+            'Restore and prove the rollback generation before retiring the displaced generation.',
+          );
+        }
+      } else if (current && current.document.generation !== generation) {
+        if (previous) {
+          throw refuse(
+            'Retire the previous generation before beginning another rotation.',
+          );
+        }
         if (
-            not retire
-            and previous
-            and previous.get("clientId")
-            and previous["clientId"]!=client_id
-        ):
-            accepted_client_ids.append(previous["clientId"])
-        emit(
-            event,
-            "INFO",
-            "success",
-            "Machine client provisioning completed.",
-        )
-        respond(event,"SUCCESS",physical,{
-            "AcceptedClientIdsJson":json.dumps(
-                accepted_client_ids,
-                separators=(",",":"),
-            ),
-            "ClientId":client_id,
-        })
-    except Exception as error:
-        emit(
-            event,
-            "ERROR",
-            "failure",
-            "Machine client provisioning failed.",
-            type(error).__name__,
-        )
-        respond(event,"FAILED",physical,reason=type(error).__name__)
+          slotOf(required(current.document, 'generation')) ===
+          slotOf(generation)
+        ) {
+          throw refuse(
+            'Credential generation must alternate blue and green slots.',
+          );
+        }
+        if (retire) {
+          throw refuse(
+            'Create and prove a new generation before retiring the previous one.',
+          );
+        }
+      }
+
+      // A rollback reuses the displaced client and never creates one.
+      const client = rollbackFrom
+        ? await findClient(properties.UserPoolId, properties.ClientName)
+        : await ensureClient(properties);
+      const clientId = client ? required(client, 'ClientId') : undefined;
+      if (rollbackFrom) {
+        if (!client || rollbackFrom.previous.document.clientId !== clientId) {
+          throw refuse(
+            'Rollback generation does not match its existing Cognito client.',
+          );
+        }
+        await secrets.send(
+          new UpdateSecretVersionStageCommand({
+            SecretId: properties.SecretArn,
+            VersionStage: 'AWSCURRENT',
+            MoveToVersionId: rollbackFrom.previous.versionId,
+            RemoveFromVersionId: rollbackFrom.current.versionId,
+          }),
+        );
+        current = rollbackFrom.previous;
+        previous = rollbackFrom.current;
+      }
+
+      if (
+        !rollbackFrom &&
+        (!current ||
+          current.document.generation !== generation ||
+          current.document.clientId !== clientId)
+      ) {
+        await secrets.send(
+          new PutSecretValueCommand({
+            SecretId: properties.SecretArn,
+            SecretString: JSON.stringify({
+              clientId,
+              clientSecret: required(client ?? {}, 'ClientSecret'),
+              generation,
+            }),
+          }),
+        );
+        previous = current;
+      }
+
+      if (retire) {
+        if (!previous) {
+          throw refuse('No previous machine credential generation exists.');
+        }
+        const previousId = previous.document.clientId;
+        if (present(previousId) && previousId !== clientId) {
+          await deleteClient(properties.UserPoolId, previousId);
+        }
+        if (present(previous.versionId)) {
+          await secrets.send(
+            new UpdateSecretVersionStageCommand({
+              SecretId: properties.SecretArn,
+              VersionStage: 'AWSPREVIOUS',
+              RemoveFromVersionId: previous.versionId,
+            }),
+          );
+        }
+      }
+
+      const acceptedClientIds: unknown[] = [clientId];
+      if (
+        !retire &&
+        previous &&
+        present(previous.document.clientId) &&
+        previous.document.clientId !== clientId
+      ) {
+        acceptedClientIds.push(previous.document.clientId);
+      }
+      record(event, 'success');
+      await respondTo(event, 'SUCCESS', responsePhysicalId, {
+        AcceptedClientIdsJson: JSON.stringify(acceptedClientIds),
+        ClientId: clientId as string,
+      });
+    } catch (error) {
+      const reason = reasonFor(error);
+      record(event, 'failure', reason);
+      await respondTo(event, 'FAILED', responsePhysicalId, undefined, reason);
+    }
+  };
+}
+
+/** PUTs the presigned CloudFormation response and waits for acceptance. */
+export function putCloudFormationResponse(
+  responseUrl: string,
+  body: string,
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const outgoing = request(
+      responseUrl,
+      {
+        // Like urllib, never pool the socket: a connection kept across a
+        // frozen Lambda environment can be dead when the next request thaws.
+        headers: {
+          connection: 'close',
+          'content-length': String(Buffer.byteLength(body)),
+          'content-type': '',
+        },
+        method: 'PUT',
+      },
+      (response) => {
+        response.on('error', () =>
+          reject(new ProvisioningError('URLError', 'Response stream failed.')),
+        );
+        response.on('end', () => {
+          const status = response.statusCode ?? 0;
+          if (status >= 200 && status < 300) resolve();
+          else {
+            reject(
+              new ProvisioningError(
+                'HTTPError',
+                'CloudFormation rejected the response with HTTP ' +
+                  status +
+                  '.',
+              ),
+            );
+          }
+        });
+        response.resume();
+      },
+    );
+    outgoing.on('error', () =>
+      reject(new ProvisioningError('URLError', 'Response delivery failed.')),
+    );
+    outgoing.end(body);
+  });
+}
+
+const logger = createLogger({
+  component: 'machine-client-provisioner',
+  feature: 'authorization',
+  operation: 'machine-client.provision',
+  slice: '${name}',
+  stage: logDimension(process.env.EBK_STAGE),
+  workspace: logDimension(process.env.EBK_WORKSPACE),
+});
+
+export const handler = createMachineClientProvisioner({
+  cognito: new CognitoIdentityProviderClient({}),
+  logger,
+  respond: putCloudFormationResponse,
+  secrets: new SecretsManagerClient({}),
+});
+`;
+}
+function machineClientProvisionerSpec(name) {
+    return `import {
+  CreateUserPoolClientCommand,
+  DeleteUserPoolClientCommand,
+  DescribeUserPoolClientCommand,
+  ListUserPoolClientsCommand,
+} from '@aws-sdk/client-cognito-identity-provider';
+import {
+  GetSecretValueCommand,
+  PutSecretValueCommand,
+  UpdateSecretVersionStageCommand,
+} from '@aws-sdk/client-secrets-manager';
+import {
+  createLogger,
+  type LogEntry,
+} from '@empire-builder-kit/runtime/logging';
+import { describe, expect, it } from 'vitest';
+import {
+  createMachineClientProvisioner,
+  type MachineClientProvisionerEvent,
+} from './machine-client-provisioner.js';
+
+const POOL = 'pool-1';
+const SECRET = 'arn:aws:secretsmanager:region:account:secret:machine-client';
+const SLICE = '${name}';
+const PHYSICAL = 'ebk-machine-client-' + SLICE + '-development';
+
+class MemoryAws {
+  readonly calls: string[] = [];
+  readonly clients = new Map<string, { name: string; secret: string }>();
+  readonly logs: LogEntry[] = [];
+  readonly responses: Array<Record<string, unknown>> = [];
+  readonly versions: Array<{ id: string; stages: string[]; value: string }> =
+    [];
+  private created = 0;
+
+  readonly cognito = {
+    send: async (command: unknown) => {
+      if (command instanceof ListUserPoolClientsCommand) {
+        this.calls.push('ListUserPoolClients');
+        return {
+          UserPoolClients: [...this.clients].map(([id, client]) => ({
+            ClientId: id,
+            ClientName: client.name,
+          })),
+        };
+      }
+      if (command instanceof DescribeUserPoolClientCommand) {
+        this.calls.push('DescribeUserPoolClient');
+        const id = command.input.ClientId ?? '';
+        const client = this.clients.get(id);
+        return {
+          UserPoolClient: { ClientId: id, ClientSecret: client?.secret },
+        };
+      }
+      if (command instanceof CreateUserPoolClientCommand) {
+        this.calls.push('CreateUserPoolClient');
+        this.created += 1;
+        const id = 'client-' + this.created;
+        const secret = 'never-log-secret-' + this.created;
+        this.clients.set(id, { name: command.input.ClientName ?? '', secret });
+        return { UserPoolClient: { ClientId: id, ClientSecret: secret } };
+      }
+      if (command instanceof DeleteUserPoolClientCommand) {
+        this.calls.push('DeleteUserPoolClient:' + command.input.ClientId);
+        this.clients.delete(command.input.ClientId ?? '');
+        return {};
+      }
+      throw new Error('Unexpected Cognito command.');
+    },
+  };
+
+  readonly secrets = {
+    send: async (command: unknown) => {
+      if (command instanceof GetSecretValueCommand) {
+        const stage = command.input.VersionStage ?? '';
+        this.calls.push('GetSecretValue:' + stage);
+        const version = this.versions.find(({ stages }) =>
+          stages.includes(stage),
+        );
+        if (!version) {
+          throw Object.assign(new Error('absent'), {
+            $metadata: {},
+            name: 'ResourceNotFoundException',
+          });
+        }
+        return { SecretString: version.value, VersionId: version.id };
+      }
+      if (command instanceof PutSecretValueCommand) {
+        this.calls.push('PutSecretValue');
+        this.label('AWSPREVIOUS');
+        for (const version of this.versions) {
+          if (version.stages.includes('AWSCURRENT')) {
+            version.stages = ['AWSPREVIOUS'];
+          }
+        }
+        this.versions.push({
+          id: 'v' + (this.versions.length + 1),
+          stages: ['AWSCURRENT'],
+          value: command.input.SecretString ?? '',
+        });
+        return {};
+      }
+      if (command instanceof UpdateSecretVersionStageCommand) {
+        const { MoveToVersionId, RemoveFromVersionId, VersionStage } =
+          command.input;
+        this.calls.push(
+          'UpdateSecretVersionStage:' +
+            VersionStage +
+            ':' +
+            (MoveToVersionId ?? '-') +
+            ':' +
+            RemoveFromVersionId,
+        );
+        if (VersionStage === 'AWSCURRENT') {
+          this.label('AWSPREVIOUS');
+          this.version(RemoveFromVersionId).stages = ['AWSPREVIOUS'];
+          this.version(MoveToVersionId).stages = ['AWSCURRENT'];
+        } else {
+          this.label(VersionStage ?? '');
+        }
+        return {};
+      }
+      throw new Error('Unexpected Secrets Manager command.');
+    },
+  };
+
+  readonly logger = createLogger({
+    component: 'machine-client-provisioner',
+    feature: 'authorization',
+    operation: 'machine-client.provision',
+    sink: (entry) => this.logs.push(entry as LogEntry),
+    slice: SLICE,
+    stage: 'development',
+    workspace: 'fixture',
+  });
+
+  private label(stage: string) {
+    for (const version of this.versions) {
+      version.stages = version.stages.filter((label) => label !== stage);
+    }
+  }
+
+  private version(id: string | undefined) {
+    const version = this.versions.find((candidate) => candidate.id === id);
+    if (!version) throw new Error('Unknown secret version.');
+    return version;
+  }
+
+  async invoke(
+    requestType: 'Create' | 'Delete' | 'Update',
+    generation: string,
+    options: { physicalResourceId?: string; retire?: boolean } = {},
+  ) {
+    this.calls.length = 0;
+    let release!: () => void;
+    let settled = false;
+    const provision = createMachineClientProvisioner({
+      cognito: this.cognito,
+      logger: this.logger,
+      respond: (_url, body) => {
+        this.responses.push(JSON.parse(body));
+        return new Promise<void>((resolve) => {
+          release = resolve;
+        });
+      },
+      secrets: this.secrets,
+    });
+    const event: MachineClientProvisionerEvent = {
+      LogicalResourceId: 'MachineClient',
+      PhysicalResourceId:
+        requestType === 'Create'
+          ? undefined
+          : (options.physicalResourceId ?? PHYSICAL),
+      RequestId: 'request-' + (this.responses.length + 1),
+      RequestType: requestType,
+      ResourceProperties: {
+        ClientName: SLICE + '-machine-development-' + generation,
+        CredentialGeneration: generation,
+        ResourceServerIdentifier: SLICE + '-development',
+        RetirePreviousGeneration: options.retire ? 'true' : 'false',
+        Scopes: [SLICE + '-development/proof-read'],
+        SecretArn: SECRET,
+        UserPoolId: POOL,
+      },
+      ResponseURL: 'https://cloudformation-response.invalid/response',
+      StackId: 'stack-1',
+    };
+    const expected = this.responses.length + 1;
+    const running = provision(event).then(() => {
+      settled = true;
+    });
+    for (let turn = 0; this.responses.length < expected && turn < 100; turn++) {
+      await new Promise((resolve) => setImmediate(resolve));
+    }
+    expect(this.responses).toHaveLength(expected);
+    // CloudFormation must have the response before the handler may finish.
+    expect(settled).toBe(false);
+    release();
+    await running;
+    return this.responses[expected - 1];
+  }
+
+  current() {
+    return JSON.parse(
+      this.versions.find(({ stages }) => stages.includes('AWSCURRENT'))
+        ?.value ?? 'null',
+    );
+  }
+}
+
+describe('generated machine-client provisioner', () => {
+  it('creates, replays, rotates, retires, and deletes with exact outputs', async () => {
+    const aws = new MemoryAws();
+
+    const created = await aws.invoke('Create', 'blue-1');
+    expect(created).toMatchObject({
+      Data: { AcceptedClientIdsJson: '["client-1"]', ClientId: 'client-1' },
+      PhysicalResourceId: PHYSICAL,
+      Status: 'SUCCESS',
+    });
+    expect(aws.versions[0].value).toBe(
+      '{"clientId":"client-1","clientSecret":"never-log-secret-1","generation":"blue-1"}',
+    );
+
+    const replay = await aws.invoke('Update', 'blue-1');
+    expect(aws.calls).toEqual([
+      'GetSecretValue:AWSCURRENT',
+      'GetSecretValue:AWSPREVIOUS',
+      'ListUserPoolClients',
+      'DescribeUserPoolClient',
+    ]);
+    expect(replay.Data).toEqual(created.Data);
+
+    const rotated = await aws.invoke('Update', 'green-2');
+    expect(rotated.Data).toEqual({
+      AcceptedClientIdsJson: '["client-2","client-1"]',
+      ClientId: 'client-2',
+    });
+    expect((await aws.invoke('Update', 'green-2')).Data).toEqual(rotated.Data);
+
+    const retired = await aws.invoke('Update', 'green-2', { retire: true });
+    expect(aws.calls).toContain('DeleteUserPoolClient:client-1');
+    expect(aws.calls.at(-1)).toBe('UpdateSecretVersionStage:AWSPREVIOUS:-:v1');
+    expect(retired.Data).toEqual({
+      AcceptedClientIdsJson: '["client-2"]',
+      ClientId: 'client-2',
+    });
+
+    expect(await aws.invoke('Delete', 'green-2')).toMatchObject({
+      Data: {},
+      Status: 'SUCCESS',
+    });
+    expect(aws.calls).toContain('DeleteUserPoolClient:client-2');
+    expect(aws.clients.size).toBe(0);
+
+    const serialized = JSON.stringify([aws.logs, aws.responses]);
+    expect(serialized).not.toContain('never-log-secret');
+    expect(
+      aws.logs.every(
+        ({ component }) => component === 'machine-client-provisioner',
+      ),
+    ).toBe(true);
+  });
+
+  it('rolls back to the displaced generation without writing a secret', async () => {
+    const aws = new MemoryAws();
+    await aws.invoke('Create', 'blue-1');
+    await aws.invoke('Update', 'green-2');
+
+    const restored = await aws.invoke('Update', 'blue-1');
+    expect(aws.calls).toEqual([
+      'GetSecretValue:AWSCURRENT',
+      'GetSecretValue:AWSPREVIOUS',
+      'ListUserPoolClients',
+      'DescribeUserPoolClient',
+      'UpdateSecretVersionStage:AWSCURRENT:v1:v2',
+    ]);
+    expect(restored.Data).toEqual({
+      AcceptedClientIdsJson: '["client-1","client-2"]',
+      ClientId: 'client-1',
+    });
+    expect(aws.current().generation).toBe('blue-1');
+  });
+
+  it('refuses unsafe rotations before creating any Cognito client', async () => {
+    const aws = new MemoryAws();
+    await aws.invoke('Create', 'blue-1');
+
+    for (const [generation, retire] of [
+      ['blue-3', false],
+      ['green-2', true],
+    ] as const) {
+      const refused = await aws.invoke('Update', generation, { retire });
+      expect(refused).toMatchObject({ Reason: 'ValueError', Status: 'FAILED' });
+      expect(aws.calls).toEqual([
+        'GetSecretValue:AWSCURRENT',
+        'GetSecretValue:AWSPREVIOUS',
+      ]);
+    }
+    await aws.invoke('Update', 'green-2');
+    expect(await aws.invoke('Update', 'blue-3')).toMatchObject({
+      Reason: 'ValueError',
+      Status: 'FAILED',
+    });
+    expect(aws.calls).not.toContain('CreateUserPoolClient');
+    expect(aws.clients.size).toBe(2);
+    expect(aws.logs.at(-1)).toMatchObject({
+      attributes: { errorCode: 'ValueError', requestType: 'Update' },
+      level: 'ERROR',
+      outcome: 'failure',
+    });
+  });
+
+  it('acknowledges a Delete for another physical id without touching a client', async () => {
+    const aws = new MemoryAws();
+    await aws.invoke('Create', 'blue-1');
+
+    const foreign = await aws.invoke('Delete', 'blue-1', {
+      physicalResourceId: 'replaced-resource',
+    });
+    expect(foreign).toMatchObject({
+      PhysicalResourceId: 'replaced-resource',
+      Status: 'SUCCESS',
+    });
+    expect(aws.calls).toEqual([]);
+    expect(aws.clients.size).toBe(1);
+  });
+});
 `;
+}
 /** @internal */
 function renderStandardSliceAuthorizationInfrastructureFiles(name, pascalName) {
     return {
-        'authorization/machine-client-provisioner.py': MACHINE_CLIENT_PROVISIONER_SOURCE,
+        'authorization/machine-client-provisioner.ts': machineClientProvisionerSource(name),
+        'authorization/machine-client-provisioner.spec.ts': machineClientProvisionerSpec(name),
+        'authorization/groups.mjs': `/** Exact physical Cognito identities; product policy keeps its logical roles. */
+export function sliceAuthorizationGroupNames(stage) {
+  if (['development', 'staging', 'production'].includes(stage)) {
+    return { admin: '${name}-admin', testWriter: '${name}-test-writer' };
+  }
+  if (!/^personal-[a-f0-9]{24}$/.test(stage)) {
+    throw new Error('Slice authorization requires a canonical or exact task stage.');
+  }
+  return {
+    admin: '${name}-' + stage + '-admin',
+    testWriter: '${name}-' + stage + '-test-writer',
+  };
+}
+
+export function sliceAuthorizationRoles(stage, roles) {
+  const groups = sliceAuthorizationGroupNames(stage);
+  if (groups.admin === '${name}-admin') return [...roles];
+  // Canonical claims must not grant task authority. Never strip a foreign
+  // task suffix: only this task's exact physical names become logical roles.
+  return roles
+    .filter((role) => role !== '${name}-admin' && role !== '${name}-test-writer')
+    .map((role) => role === groups.admin
+      ? '${name}-admin'
+      : role === groups.testWriter ? '${name}-test-writer' : role);
+}
+`,
+        'authorization/groups.d.mts': `export function sliceAuthorizationGroupNames(stage: string): {
+  admin: string;
+  testWriter: string;
+};
+export function sliceAuthorizationRoles(stage: string, roles: readonly string[]): string[];
+`,
         'infra/authorization.ts': `import { createHash } from 'node:crypto';
+import { sliceAuthorizationGroupNames } from '../authorization/groups.mjs';
 
 const MACHINE_AUTHORIZATION_SCOPE_NAMES = [
   'delegation-use',
@@ -326,6 +1021,7 @@ export function createStandardSliceMachineAuthorization(
     options.credentialGeneration,
   );
   const resourceServerIdentifier = '${name}-' + $app.stage;
+  const groups = sliceAuthorizationGroupNames($app.stage);
   const template = {
     AWSTemplateFormatVersion: '2010-09-09',
     Description:
@@ -351,7 +1047,7 @@ export function createStandardSliceMachineAuthorization(
         Properties: {
           Description:
             'Direct human recovery and non-author review authority for ${name}.',
-          GroupName: '${name}-admin',
+          GroupName: groups.admin,
           Precedence: 10,
           UserPoolId: { Ref: 'UserPoolId' },
         },
@@ -361,7 +1057,7 @@ export function createStandardSliceMachineAuthorization(
         Properties: {
           Description:
             'Run-scoped synthetic-write authority for ${name} deployed proof.',
-          GroupName: '${name}-test-writer',
+          GroupName: groups.testWriter,
           Precedence: 20,
           UserPoolId: { Ref: 'UserPoolId' },
         },
@@ -373,8 +1069,10 @@ export function createStandardSliceMachineAuthorization(
             'EBK generated ${name} confidential machine-client credential.',
           Name: { Ref: 'SecretName' },
           Tags: [
+            { Key: 'ebk:managed-by', Value: 'empire-builder-kit' },
             { Key: 'ebk:management', Value: 'generated-machine-credential' },
             { Key: 'ebk:slice', Value: '${name}' },
+            { Key: 'ebk:stage', Value: $app.stage },
             { Key: 'sst:stage', Value: $app.stage },
           ],
         },
@@ -459,6 +1157,10 @@ export function createStandardSliceMachineAuthorization(
           '/${name}/authorization/machine-client',
         UserPoolId: options.userPoolId,
       },
+      tags: {
+        'ebk:managed-by': 'empire-builder-kit',
+        'ebk:stage': $app.stage,
+      },
       templateBody: JSON.stringify(template),
     },
   );
@@ -522,37 +1224,77 @@ line.
 
 ## Begin an overlap
 
-1. Read the current non-secret generation from the protected deployment
-   configuration.
+1. Read the current non-secret generation: the value last deployed with
+   \`EBK_MACHINE_CREDENTIAL_GENERATION\`, or \`blue-1\` if the stage was never
+   rotated. The proof result in step 5 reports it as \`credentialGeneration\`.
 2. Select the other slot and a new positive generation number, for example
    \`blue-1\` to \`green-2\`.
 3. Set \`EBK_MACHINE_CREDENTIAL_GENERATION\` to that generation and leave
    \`EBK_MACHINE_RETIRE_PREVIOUS_GENERATION\` unset.
-4. Deploy through the Slice's Nx \`deploy\` target. The AWS-internal
-   provisioner creates the replacement client and moves its credential to
-   \`AWSCURRENT\`; the former credential remains \`AWSPREVIOUS\` and its Cognito
-   client remains valid during the overlap.
+4. Deploy the Slice through the governed root lifecycle with that variable
+   in the same shell, for example:
+
+   \`\`\`bash
+   EBK_MACHINE_CREDENTIAL_GENERATION=green-2 ebk deploy development <slice> \\
+     --profile=<profile> --expectedRoleArn=<role-arn>
+   \`\`\`
+
+   A local \`nx run <slice>:deploy\` is refused outside that lifecycle. The
+   AWS-internal provisioner creates the replacement client and moves its
+   credential to \`AWSCURRENT\`; the former credential remains \`AWSPREVIOUS\`
+   and its Cognito client remains valid during the overlap.
 5. Prove the server-side token-minting journey reads \`AWSCURRENT\`, obtains a
    bounded access token, and completes its narrow capability smoke. Evidence
    may contain the client ID, generation, scope names, and outcome, but never a
-   secret or access token.
+   secret or access token. Read that result from the Slice's deployed
+   machine-authorization proof function, which no EBK command invokes yet: it
+   must return \`outcome\` \`success\`, \`probeStatus\` 200, and the new
+   \`credentialGeneration\`.
+
+Every deploy of the Slice reads these variables, and an omitted
+\`EBK_MACHINE_CREDENTIAL_GENERATION\` requests \`blue-1\`. Keep it set to the
+current generation for every later deploy of that stage; otherwise the
+provisioner rolls back to \`blue-1\`, refuses the deploy, or begins an
+unplanned rotation. Local and workflow deploys of one stage must request the
+same generation.
 
 ## Retire the previous generation
 
 Only after the new generation is proved, set
 \`EBK_MACHINE_RETIRE_PREVIOUS_GENERATION=true\` and deploy the same generation
-again through Nx. The AWS-internal provisioner deletes the previous Cognito
+again the same way. The AWS-internal provisioner deletes the previous Cognito
 client and removes its \`AWSPREVIOUS\` label without returning either
 credential. Clear the retirement flag after the successful deploy.
 
-If the replacement cannot mint and use a token, restore the prior deployment
-configuration before retirement. The provisioner recognizes that exact
+If the replacement cannot mint and use a token, deploy the prior generation
+again before retirement. The provisioner recognizes that exact
 \`AWSPREVIOUS\` generation, atomically promotes it back to \`AWSCURRENT\`, and
 keeps the failed replacement as the new rollback generation. Prove the restored
 generation before retiring anything. Never retire in the same deployment that
 creates a generation, reuse the current color for a new generation, invoke SST
 directly, or use the interactive operator-secret commands for this
 provider-generated credential.
+
+## Rotate through the protected Deploy workflow
+
+The generated protected Deploy workflow reads both variables from the
+deploying stage's GitHub environment, such as \`staging\` or \`production\`,
+and passes each to its deployment only when it is set. Set them as variables
+of that environment, never at repository or organization scope; the GitHub
+bootstrap report refuses those scopes. Before it assumes any AWS role, the
+workflow refuses a generation other than \`blue-N\` or \`green-N\`, a
+retirement flag other than \`true\` or \`false\`, a retirement without an
+explicit generation, and a retirement deploy in \`affected\` scope.
+
+1. Set \`EBK_MACHINE_CREDENTIAL_GENERATION\` in the stage's environment to the
+   new generation and run the protected Deploy for that stage with
+   \`lifecycle\` \`full\`. The default \`affected\` scope skips a Slice whose
+   source is unchanged, so it would not rotate.
+2. Prove the new generation as in step 5 of "Begin an overlap".
+3. Set \`EBK_MACHINE_RETIRE_PREVIOUS_GENERATION\` to \`true\` in the same
+   environment and run the protected Deploy again with \`lifecycle\` \`full\`.
+4. After that deploy succeeds, delete the retirement variable or set it to
+   \`false\`. Keep the generation variable at the current generation.
 `,
     };
 }