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

package/src/secrets/generated-aws-control-plane.js

@@ -0,0 +1,259 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AwsGeneratedSecretInitializationError = void 0;
+exports.createAwsGeneratedSecretInitializationControlPlane = createAwsGeneratedSecretInitializationControlPlane;
+const node_crypto_1 = require("node:crypto");
+const client_secrets_manager_1 = require("@aws-sdk/client-secrets-manager");
+const model_js_1 = require("./model.js");
+class AwsGeneratedSecretInitializationError extends Error {
+    code;
+    constructor(code) {
+        super(`Generated secret initialization failed (${code}).`);
+        this.name = 'AwsGeneratedSecretInitializationError';
+        this.code = code;
+    }
+}
+exports.AwsGeneratedSecretInitializationError = AwsGeneratedSecretInitializationError;
+const inspectionDelaysMilliseconds = [0, 100, 250, 500, 1_000];
+const generatedSecretNamePattern = /^ebk\/(development|staging|production)\/([a-z0-9][a-z0-9-]{0,62})\/([A-Za-z][A-Za-z0-9]{0,63})$/;
+const metadataTextPattern = /^[^\0]{1,256}$/;
+const slugPattern = /^[a-z0-9][a-z0-9-]{0,62}$/;
+const generatedSecretTagKeys = [
+    'ebk:generation',
+    'ebk:logical-name',
+    'ebk:management',
+    'ebk:owner',
+    'ebk:slice',
+    'ebk:stage',
+    'ebk:workspace',
+];
+function expectedVersionId(name, generation) {
+    return (0, node_crypto_1.createHash)('sha256')
+        .update('ebk-generated-secret-initialization-v2\0', 'utf8')
+        .update(name, 'utf8')
+        .update('\0', 'utf8')
+        .update(generation, 'utf8')
+        .digest('hex');
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isResourceNotFound(error) {
+    return (isRecord(error) &&
+        (error['name'] === 'ResourceNotFoundException' ||
+            error['Code'] === 'ResourceNotFoundException' ||
+            error['code'] === 'ResourceNotFoundException'));
+}
+function requireInput(input) {
+    const name = generatedSecretNamePattern.exec(input.name);
+    if (!isRecord(input) ||
+        name === null ||
+        input.description !== `EBK generated secret ${name[3]}` ||
+        input.generation !== 'hmac-key-ring-v1' ||
+        !isRecord(input.tags) ||
+        Object.keys(input.tags).length !== generatedSecretTagKeys.length ||
+        generatedSecretTagKeys.some((key) => !Object.prototype.hasOwnProperty.call(input.tags, key)) ||
+        input.tags['ebk:generation'] !== 'hmac-key-ring-v1' ||
+        input.tags['ebk:logical-name'] !== name[3] ||
+        input.tags['ebk:management'] !== 'generated-secret' ||
+        !slugPattern.test(input.tags['ebk:owner'] ?? '') ||
+        input.tags['ebk:slice'] !== name[2] ||
+        input.tags['ebk:stage'] !== name[1] ||
+        !slugPattern.test(input.tags['ebk:workspace'] ?? '') ||
+        Object.entries(input.tags).some(([key, value]) => !metadataTextPattern.test(key) ||
+            typeof value !== 'string' ||
+            !metadataTextPattern.test(value))) {
+        throw new AwsGeneratedSecretInitializationError('generated-secret-input-invalid');
+    }
+}
+function tagsToAws(tags) {
+    return Object.keys(tags)
+        .sort()
+        .map((Key) => ({ Key, Value: tags[Key] }));
+}
+function exactTags(value, expected) {
+    if (!Array.isArray(value) || value.length !== Object.keys(expected).length) {
+        return false;
+    }
+    const observed = {};
+    for (const entry of value) {
+        if (!isRecord(entry) ||
+            typeof entry['Key'] !== 'string' ||
+            typeof entry['Value'] !== 'string' ||
+            Object.prototype.hasOwnProperty.call(observed, entry['Key'])) {
+            return false;
+        }
+        observed[entry['Key']] = entry['Value'];
+    }
+    return Object.entries(expected).every(([key, expectedValue]) => observed[key] === expectedValue);
+}
+function arnMatchesName(arn, name) {
+    if (!(0, model_js_1.isExactSecretArn)(arn))
+        return false;
+    const marker = `:secret:${name}-`;
+    const markerIndex = arn.lastIndexOf(marker);
+    return (markerIndex > 0 &&
+        /^[A-Za-z0-9]{6}$/.test(arn.slice(markerIndex + marker.length)));
+}
+function inspectVersionState(output, versionId) {
+    const versions = output.VersionIdsToStages;
+    if (versions === undefined || Object.keys(versions).length !== 1) {
+        return 'conflicting';
+    }
+    const entry = Object.entries(versions)[0];
+    return entry?.[0] === versionId &&
+        Array.isArray(entry[1]) &&
+        entry[1].length === 1 &&
+        entry[1][0] === 'AWSCURRENT'
+        ? 'current'
+        : 'conflicting';
+}
+function requireDescribeOutput(value, input) {
+    if (!isRecord(value) ||
+        typeof value['ARN'] !== 'string' ||
+        !arnMatchesName(value['ARN'], input.name) ||
+        value['Name'] !== input.name ||
+        value['Description'] !== input.description ||
+        value['DeletedDate'] !== undefined ||
+        value['RotationEnabled'] === true ||
+        !exactTags(value['Tags'], input.tags)) {
+        throw new AwsGeneratedSecretInitializationError('generated-secret-observation-invalid');
+    }
+    return {
+        arn: value['ARN'],
+        state: inspectVersionState(value, expectedVersionId(input.name, input.generation)),
+    };
+}
+function requireCreateOutput(value, input, versionId) {
+    if (!isRecord(value) ||
+        typeof value['ARN'] !== 'string' ||
+        !arnMatchesName(value['ARN'], input.name) ||
+        value['Name'] !== input.name ||
+        value['VersionId'] !== versionId) {
+        throw new AwsGeneratedSecretInitializationError('generated-secret-observation-invalid');
+    }
+    return value;
+}
+function defaultClient(configuration) {
+    const client = new client_secrets_manager_1.SecretsManagerClient(configuration);
+    return {
+        send(command) {
+            if (command instanceof client_secrets_manager_1.DescribeSecretCommand) {
+                return client.send(command);
+            }
+            return client.send(command);
+        },
+    };
+}
+async function defaultWait(milliseconds) {
+    if (milliseconds === 0)
+        return;
+    await new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+/**
+ * Generates one declared machine value inside the AWS adapter and atomically
+ * creates its Secrets Manager container. The public API accepts no plaintext
+ * and returns only applied/unchanged metadata. Plaintext necessarily exists
+ * transiently in this trusted process and the AWS SDK request, but it is never
+ * returned, logged, or persisted by EBK.
+ */
+function createAwsGeneratedSecretInitializationControlPlane(options = {}) {
+    const client = options.client ?? defaultClient(options.clientConfiguration ?? {});
+    const generateBytes = options.randomBytes ?? node_crypto_1.randomBytes;
+    const wait = options.wait ?? defaultWait;
+    const inspectExact = async (input) => {
+        requireInput(input);
+        let rawOutput;
+        try {
+            rawOutput = await client.send(new client_secrets_manager_1.DescribeSecretCommand({ SecretId: input.name }));
+        }
+        catch (error) {
+            if (isResourceNotFound(error))
+                return { state: 'missing' };
+            throw new AwsGeneratedSecretInitializationError('generated-secret-read-failed');
+        }
+        return requireDescribeOutput(rawOutput, input);
+    };
+    const inspectAfterCreate = async (input) => {
+        let finalInspection = { state: 'missing' };
+        for (const delay of inspectionDelaysMilliseconds) {
+            await wait(delay);
+            finalInspection = await inspectExact(input);
+            if (finalInspection.state !== 'missing')
+                return finalInspection;
+        }
+        return finalInspection;
+    };
+    return Object.freeze({
+        async inspect(input) {
+            return (await inspectExact(input)).state;
+        },
+        async initializeGenerated(input) {
+            requireInput(input);
+            const initial = await inspectExact(input);
+            if (initial.state === 'current')
+                return 'unchanged';
+            if (initial.state !== 'missing') {
+                throw new AwsGeneratedSecretInitializationError('generated-secret-state-conflicting');
+            }
+            let idBytes;
+            let keyBytes;
+            try {
+                idBytes = generateBytes(12);
+                keyBytes = generateBytes(32);
+            }
+            catch {
+                idBytes?.fill(0);
+                keyBytes?.fill(0);
+                throw new AwsGeneratedSecretInitializationError('generated-secret-input-invalid');
+            }
+            if (idBytes.length !== 12 || keyBytes.length !== 32) {
+                idBytes.fill(0);
+                keyBytes.fill(0);
+                throw new AwsGeneratedSecretInitializationError('generated-secret-input-invalid');
+            }
+            const versionId = expectedVersionId(input.name, input.generation);
+            let responseAccepted = false;
+            try {
+                try {
+                    // SecretString is intentionally created only in the trusted adapter.
+                    // JavaScript strings cannot be zeroized; never expose this command or
+                    // its input through logs, return values, evidence, or dependency hooks.
+                    const secretString = JSON.stringify({
+                        current: {
+                            id: `ebk-${idBytes.toString('hex')}`,
+                            secret: keyBytes.toString('base64url'),
+                        },
+                    });
+                    const output = await client.send(new client_secrets_manager_1.CreateSecretCommand({
+                        ClientRequestToken: versionId,
+                        Description: input.description,
+                        Name: input.name,
+                        SecretString: secretString,
+                        Tags: tagsToAws(input.tags),
+                    }));
+                    requireCreateOutput(output, input, versionId);
+                    responseAccepted = true;
+                }
+                catch {
+                    responseAccepted = false;
+                }
+            }
+            finally {
+                idBytes.fill(0);
+                keyBytes.fill(0);
+            }
+            const finalInspection = await inspectAfterCreate(input);
+            if (finalInspection.state === 'current') {
+                return responseAccepted ? 'applied' : 'unchanged';
+            }
+            if (finalInspection.state === 'conflicting') {
+                throw new AwsGeneratedSecretInitializationError('generated-secret-state-conflicting');
+            }
+            throw new AwsGeneratedSecretInitializationError(responseAccepted
+                ? 'generated-secret-observation-invalid'
+                : 'generated-secret-write-failed');
+        },
+    });
+}
+//# sourceMappingURL=generated-aws-control-plane.js.map

package/src/secrets/metadata.js

@@ -23,8 +23,9 @@ function expectedDeclarations(declarations, scope) {
     const names = new Set();
     for (const declaration of declarations) {
         (0, model_js_1.validateSecretMetadataDeclaration)(declaration);
-        if (declaration.source !== 'operator') {
-            throw new model_js_1.SecretMetadataModelError(`declarations.${declaration.logicalName}.source`, 'must be operator for the operator-secret metadata path');
+        if (declaration.source !== 'operator' &&
+            declaration.source !== 'generated') {
+            throw new model_js_1.SecretMetadataModelError(`declarations.${declaration.logicalName}.source`, 'must be operator or generated for the deployed-secret metadata path');
         }
         if (names.has(declaration.logicalName)) {
             throw new model_js_1.SecretMetadataModelError('declarations', 'must not contain duplicate logical names');
@@ -54,6 +55,17 @@ function identityDisposition(observed, expectedTags) {
     }
     return present.length === identityTagKeys.length ? 'owned' : 'ambiguous';
 }
+function managementDisposition(observed, expectedTags) {
+    const actualManagement = observed.tags[model_js_1.SECRET_METADATA_TAG_KEYS.management];
+    const expectedManagement = expectedTags[model_js_1.SECRET_METADATA_TAG_KEYS.management];
+    const actualGeneration = observed.tags[model_js_1.SECRET_METADATA_TAG_KEYS.generation];
+    const expectedGeneration = expectedTags[model_js_1.SECRET_METADATA_TAG_KEYS.generation];
+    if (actualManagement === expectedManagement &&
+        actualGeneration === expectedGeneration) {
+        return 'owned';
+    }
+    return 'conflicting';
+}
 function tagsDiffer(observed, expected) {
     return Object.entries(expected).some(([key, value]) => observed.tags[key] !== value);
 }
@@ -83,12 +95,17 @@ function reconcileSecretMetadata(input) {
         const actual = observed.get(name);
         if (actual === undefined) {
             findings.push(finding('missing-container', name, declaration.logicalName, 'blocking'));
-            proposedMutations.push({
-                description: `EBK operator secret ${declaration.logicalName}`,
-                kind: 'create-empty-container',
-                name,
-                tags: expectedTags,
-            });
+            // A generated value and its container are one atomic Secrets Manager
+            // creation. Metadata reconciliation may create only value-free operator
+            // containers; the generated initializer owns the generated container.
+            if (declaration.source !== 'generated') {
+                proposedMutations.push({
+                    description: `EBK ${declaration.source} secret ${declaration.logicalName}`,
+                    kind: 'create-empty-container',
+                    name,
+                    tags: expectedTags,
+                });
+            }
             continue;
         }
         const ownership = identityDisposition(actual, expectedTags);
@@ -100,6 +117,11 @@ function reconcileSecretMetadata(input) {
             findings.push(finding('identity-conflict', name, declaration.logicalName, 'blocking'));
             continue;
         }
+        const management = managementDisposition(actual, expectedTags);
+        if (management === 'conflicting') {
+            findings.push(finding('identity-conflict', name, declaration.logicalName, 'blocking'));
+            continue;
+        }
         if (tagsDiffer(actual, expectedTags)) {
             findings.push(finding('tag-drift', name, declaration.logicalName, 'warning'));
             proposedMutations.push({
@@ -118,8 +140,10 @@ function reconcileSecretMetadata(input) {
                 input.scope.workspace &&
             actual.tags[model_js_1.SECRET_METADATA_TAG_KEYS.stage] === input.scope.stage &&
             actual.tags[model_js_1.SECRET_METADATA_TAG_KEYS.slice] === input.scope.slice &&
-            actual.tags[model_js_1.SECRET_METADATA_TAG_KEYS.management] ===
-                model_js_1.OPERATOR_SECRET_MANAGEMENT_CLASS) {
+            (actual.tags[model_js_1.SECRET_METADATA_TAG_KEYS.management] ===
+                model_js_1.OPERATOR_SECRET_MANAGEMENT_CLASS ||
+                actual.tags[model_js_1.SECRET_METADATA_TAG_KEYS.management] ===
+                    model_js_1.GENERATED_SECRET_MANAGEMENT_CLASS)) {
             findings.push(finding('orphan-container', actual.name, actual.tags[model_js_1.SECRET_METADATA_TAG_KEYS.logicalName], 'warning'));
         }
     }
@@ -156,6 +180,10 @@ function preflightSecretMetadata(input) {
             findings.push(finding('identity-conflict', name, declaration.logicalName, 'blocking'));
             continue;
         }
+        if (managementDisposition(actual, expectedTags) === 'conflicting') {
+            findings.push(finding('identity-conflict', name, declaration.logicalName, 'blocking'));
+            continue;
+        }
         if (!actual.versionStages.includes('AWSCURRENT')) {
             findings.push(finding('missing-current-version', name, declaration.logicalName, 'blocking'));
         }

package/src/secrets/model.d.ts

@@ -1,7 +1,10 @@
 export declare const OPERATOR_SECRET_MANAGEMENT_CLASS: "operator-secret";
+export declare const GENERATED_SECRET_MANAGEMENT_CLASS: "generated-secret";
+export declare const GENERATED_HMAC_SECRET_LOGICAL_NAME: "GeneratedPerformanceLoadHmacKeys";
 export declare const SECRET_CANONICAL_STAGES: readonly ["development", "staging", "production"];
 export type SecretCanonicalStage = (typeof SECRET_CANONICAL_STAGES)[number];
 export declare const SECRET_METADATA_TAG_KEYS: {
+    readonly generation: "ebk:generation";
     readonly logicalName: "ebk:logical-name";
     readonly management: "ebk:management";
     readonly owner: "ebk:owner";
@@ -15,11 +18,14 @@ export type SecretMetadataRotation = {
     mode: 'provider-managed';
 };
 export interface SecretMetadataDeclaration {
+    generation?: {
+        kind: 'hmac-key-ring-v1';
+    };
     logicalName: string;
     owner: string;
     requiredStages: readonly string[];
     rotation: SecretMetadataRotation;
-    source: 'aws-managed' | 'database-bootstrap' | 'operator';
+    source: 'aws-managed' | 'database-bootstrap' | 'generated' | 'operator';
     valueKind: 'binary' | 'json' | 'string';
 }
 export interface SecretManagementScope {
@@ -29,6 +35,7 @@ export interface SecretManagementScope {
 }
 export interface ObservedSecretMetadata {
     arn: string;
+    deletionPendingUntil?: string;
     name: string;
     rotationEnabled: boolean;
     tags: Readonly<Record<string, string>>;

package/src/secrets/model.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SecretMetadataModelError = exports.SECRET_METADATA_TAG_KEYS = exports.SECRET_CANONICAL_STAGES = exports.OPERATOR_SECRET_MANAGEMENT_CLASS = void 0;
+exports.SecretMetadataModelError = exports.SECRET_METADATA_TAG_KEYS = exports.SECRET_CANONICAL_STAGES = exports.GENERATED_HMAC_SECRET_LOGICAL_NAME = exports.GENERATED_SECRET_MANAGEMENT_CLASS = exports.OPERATOR_SECRET_MANAGEMENT_CLASS = void 0;
 exports.isSecretCanonicalStage = isSecretCanonicalStage;
 exports.validateSecretManagementScope = validateSecretManagementScope;
 exports.validateSecretMetadataDeclaration = validateSecretMetadataDeclaration;
@@ -10,12 +10,15 @@ exports.canonicalOperatorSecretTags = canonicalOperatorSecretTags;
 exports.isExactSecretArn = isExactSecretArn;
 exports.isRotationCompliant = isRotationCompliant;
 exports.OPERATOR_SECRET_MANAGEMENT_CLASS = 'operator-secret';
+exports.GENERATED_SECRET_MANAGEMENT_CLASS = 'generated-secret';
+exports.GENERATED_HMAC_SECRET_LOGICAL_NAME = 'GeneratedPerformanceLoadHmacKeys';
 exports.SECRET_CANONICAL_STAGES = [
     'development',
     'staging',
     'production',
 ];
 exports.SECRET_METADATA_TAG_KEYS = {
+    generation: 'ebk:generation',
     logicalName: 'ebk:logical-name',
     management: 'ebk:management',
     owner: 'ebk:owner',
@@ -64,12 +67,20 @@ function validateSecretMetadataDeclaration(declaration) {
             declaration.requiredStages.length) {
         throw new SecretMetadataModelError('declaration.requiredStages', 'must contain unique canonical deployed stages');
     }
-    if (!['aws-managed', 'database-bootstrap', 'operator'].includes(declaration.source)) {
+    if (!['aws-managed', 'database-bootstrap', 'generated', 'operator'].includes(declaration.source)) {
         throw new SecretMetadataModelError('declaration.source', 'must name a supported value authority');
     }
     if (!['binary', 'json', 'string'].includes(declaration.valueKind)) {
         throw new SecretMetadataModelError('declaration.valueKind', 'must name a supported value shape');
     }
+    if ((declaration.source === 'generated') !==
+        (declaration.generation !== undefined) ||
+        (declaration.generation !== undefined &&
+            (declaration.generation.kind !== 'hmac-key-ring-v1' ||
+                Object.keys(declaration.generation).length !== 1 ||
+                declaration.valueKind !== 'json'))) {
+        throw new SecretMetadataModelError('declaration.generation', 'must select the supported value-blind JSON generator exactly when source is generated');
+    }
     if (!['manual', 'provider-managed'].includes(declaration.rotation.mode)) {
         throw new SecretMetadataModelError('declaration.rotation.mode', 'must be manual or provider-managed');
     }
@@ -82,6 +93,9 @@ function validateObservedSecretMetadata(observed) {
         throw new SecretMetadataModelError('observed.name', 'must be a concrete secret name');
     }
     if (typeof observed.rotationEnabled !== 'boolean' ||
+        (observed.deletionPendingUntil !== undefined &&
+            (typeof observed.deletionPendingUntil !== 'string' ||
+                Number.isNaN(Date.parse(observed.deletionPendingUntil)))) ||
         typeof observed.tags !== 'object' ||
         observed.tags === null ||
         Array.isArray(observed.tags) ||
@@ -106,8 +120,15 @@ function canonicalOperatorSecretTags(scope, declaration) {
     validateSecretManagementScope(scope);
     validateSecretMetadataDeclaration(declaration);
     return Object.freeze({
+        ...(declaration.generation === undefined
+            ? {}
+            : {
+                [exports.SECRET_METADATA_TAG_KEYS.generation]: declaration.generation.kind,
+            }),
         [exports.SECRET_METADATA_TAG_KEYS.logicalName]: declaration.logicalName,
-        [exports.SECRET_METADATA_TAG_KEYS.management]: exports.OPERATOR_SECRET_MANAGEMENT_CLASS,
+        [exports.SECRET_METADATA_TAG_KEYS.management]: declaration.source === 'generated'
+            ? exports.GENERATED_SECRET_MANAGEMENT_CLASS
+            : exports.OPERATOR_SECRET_MANAGEMENT_CLASS,
         [exports.SECRET_METADATA_TAG_KEYS.owner]: declaration.owner,
         [exports.SECRET_METADATA_TAG_KEYS.slice]: scope.slice,
         [exports.SECRET_METADATA_TAG_KEYS.stage]: scope.stage,

package/src/secrets/operator.d.ts

@@ -1,4 +1,5 @@
-import { type SecretMetadataMutationIntent, type SecretMetadataPreflightResult, type SecretMetadataReconciliationResult } from './metadata.js';
+import { AwsGeneratedSecretInitializationError } from './generated-aws-control-plane.js';
+import { type SecretMetadataFinding, type SecretMetadataMutationIntent, type SecretMetadataPreflightResult, type SecretMetadataReconciliationResult } from './metadata.js';
 import { type ObservedSecretMetadata, type SecretManagementScope, type SecretMetadataDeclaration } from './model.js';
 export interface ListedSecretContainer {
     arn: string;
@@ -20,12 +21,40 @@ export interface SecretMetadataControlPlane {
     describe(input: {
         arn: string;
     }): Promise<ObservedSecretMetadata>;
+    describeExact(input: {
+        includePlannedDeletion?: boolean;
+        name: string;
+    }): Promise<ObservedSecretMetadata | undefined>;
     list(input: {
         includePlannedDeletion?: boolean;
         namePrefix: string;
     }): Promise<readonly ListedSecretContainer[]>;
     tag(input: TagSecretContainerInput): Promise<void>;
 }
+export interface GeneratedSecretInitializationControlPlane {
+    /**
+     * Atomically create the container and generated value inside the concrete
+     * control-plane adapter. The plaintext must never be returned to this
+     * orchestration layer.
+     */
+    initializeGenerated(input: {
+        description: string;
+        generation: 'hmac-key-ring-v1';
+        name: string;
+        tags: Readonly<Record<string, string>>;
+    }): Promise<'applied' | 'unchanged'>;
+    /**
+     * Describe and validate the exact named container, provenance metadata, and
+     * deterministic generated version. Implementations must not use an
+     * eventually consistent inventory/list operation for this attestation.
+     */
+    inspect(input: {
+        description: string;
+        generation: 'hmac-key-ring-v1';
+        name: string;
+        tags: Readonly<Record<string, string>>;
+    }): Promise<'conflicting' | 'current' | 'missing'>;
+}
 export interface ProtectedSecretLifecycleControlPlane extends SecretMetadataControlPlane {
     restore(input: {
         arn: string;
@@ -37,6 +66,14 @@ export interface ProtectedSecretLifecycleControlPlane extends SecretMetadataCont
         recoveryUntil: string;
     }>;
 }
+export interface GeneratedSecretRetirementControlPlane extends Pick<ProtectedSecretLifecycleControlPlane, 'describeExact' | 'scheduleRetirement'> {
+    deleteImmediately(input: {
+        arn: string;
+    }): Promise<void>;
+    restore(input: {
+        arn: string;
+    }): Promise<void>;
+}
 export interface ProtectedSecretOperatorAuthorization {
     approved: true;
     authority: 'protected-secret-operator';
@@ -45,9 +82,10 @@ export interface ProtectedSecretOperatorAuthorization {
 }
 export type SecretProtectedLifecycleAction = 'deploy' | 'recover' | 'remove' | 'unlock';
 export declare class SecretOperatorControlPlaneError extends Error {
-    readonly operation: 'create-empty' | 'describe' | 'inventory' | 'list' | 'recover' | 'retire' | 'tag';
+    readonly operation: 'create-empty' | 'describe' | 'inventory' | 'initialize-generated' | 'list' | 'recover' | 'retire' | 'tag';
+    readonly diagnosticCode?: AwsGeneratedSecretInitializationError['code'];
     readonly code: 'secret-control-plane-apply-failed' | 'secret-control-plane-inventory-failed' | 'secret-control-plane-inventory-invalid' | 'secret-control-plane-protected-action-failed';
-    constructor(code: SecretOperatorControlPlaneError['code'], operation: 'create-empty' | 'describe' | 'inventory' | 'list' | 'recover' | 'retire' | 'tag');
+    constructor(code: SecretOperatorControlPlaneError['code'], operation: 'create-empty' | 'describe' | 'inventory' | 'initialize-generated' | 'list' | 'recover' | 'retire' | 'tag', diagnosticCode?: AwsGeneratedSecretInitializationError['code']);
 }
 export interface SecretMetadataOperatorResult {
     after?: SecretMetadataReconciliationResult;
@@ -56,6 +94,33 @@ export interface SecretMetadataOperatorResult {
     mode: 'apply' | 'report';
     outcome: 'applied' | 'applied-with-findings' | 'blocked' | 'reported';
 }
+export interface GeneratedSecretInitializationResult {
+    findings: readonly SecretMetadataFinding[];
+    initialized: readonly {
+        logicalName: string;
+        name: string;
+    }[];
+    mode: 'apply' | 'report';
+    outcome: 'applied' | 'blocked' | 'reported' | 'unchanged';
+    proposed: readonly {
+        logicalName: string;
+        name: string;
+    }[];
+}
+export interface GeneratedSecretRetirementResult {
+    deletionMode: 'immediate' | 'recovery-window';
+    outcome: 'not-applicable' | 'retired';
+    recoveryWindowDays?: 7;
+    secrets: readonly {
+        generation: 'hmac-key-ring-v1';
+        logicalName: string;
+        name: string;
+        outcome: 'already-scheduled' | 'deleted' | 'not-found' | 'scheduled';
+        recoveryUntil?: string;
+        source: 'generated';
+    }[];
+    stage: string;
+}
 export interface SecretDeployPreflightResult extends SecretMetadataPreflightResult {
     action: SecretProtectedLifecycleAction;
     bypassed: boolean;
@@ -79,12 +144,35 @@ export declare function runSecretMetadataOperator(input: {
     mode?: 'apply' | 'report';
     scope: SecretManagementScope;
 }): Promise<SecretMetadataOperatorResult>;
+export declare function runGeneratedSecretInitializer(input: {
+    initializationControlPlane: GeneratedSecretInitializationControlPlane;
+    logicalName: string;
+    metadataControlPlane: SecretMetadataControlPlane;
+    declarations: readonly SecretMetadataDeclaration[];
+    mode?: 'apply' | 'report';
+    scope: SecretManagementScope;
+}): Promise<GeneratedSecretInitializationResult>;
 export declare function runSecretDeployPreflight(input: {
     action: SecretProtectedLifecycleAction;
     controlPlane: SecretMetadataControlPlane;
     declarations: readonly SecretMetadataDeclaration[];
     scope: SecretManagementScope;
 }): Promise<SecretDeployPreflightResult>;
+/**
+ * Retires only exact framework-generated stage secrets after a
+ * successful native Slice removal. This path never reads a secret value,
+ * inventories a prefix, or operates on operator/database-bootstrap secrets.
+ */
+export declare function runGeneratedSecretRetirement(input: {
+    accountId: string;
+    controlPlane: GeneratedSecretRetirementControlPlane;
+    declarations: readonly SecretMetadataDeclaration[];
+    now?: () => number;
+    partition: 'aws' | 'aws-cn' | 'aws-us-gov';
+    region: string;
+    scope: SecretManagementScope;
+    waitBeforeRetry?: (delayMs: number) => Promise<void>;
+}): Promise<GeneratedSecretRetirementResult>;
 export declare function runProtectedSecretLifecycle(input: {
     action: 'recover';
     authorization: ProtectedSecretOperatorAuthorization;