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

package/src/secrets/operator.js

@@ -2,17 +2,23 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SecretOperatorControlPlaneError = void 0;
 exports.runSecretMetadataOperator = runSecretMetadataOperator;
+exports.runGeneratedSecretInitializer = runGeneratedSecretInitializer;
 exports.runSecretDeployPreflight = runSecretDeployPreflight;
+exports.runGeneratedSecretRetirement = runGeneratedSecretRetirement;
 exports.runProtectedSecretLifecycle = runProtectedSecretLifecycle;
 const deterministic_order_js_1 = require("../deterministic-order.js");
+const generated_aws_control_plane_js_1 = require("./generated-aws-control-plane.js");
 const metadata_js_1 = require("./metadata.js");
 const model_js_1 = require("./model.js");
 class SecretOperatorControlPlaneError extends Error {
     operation;
+    diagnosticCode;
     code;
-    constructor(code, operation) {
-        super(`Secret metadata ${operation} failed (${code}).`);
+    constructor(code, operation, diagnosticCode) {
+        super(`Secret metadata ${operation} failed (${code}).` +
+            (diagnosticCode ? ` Reason: ${diagnosticCode}.` : ''));
         this.operation = operation;
+        this.diagnosticCode = diagnosticCode;
         this.name = 'SecretOperatorControlPlaneError';
         this.code = code;
     }
@@ -26,10 +32,28 @@ function safeControlPlaneError(error, code, operation) {
     if (error instanceof SecretOperatorControlPlaneError) {
         return error;
     }
+    // Preserve only our finite, value-blind diagnostic vocabulary. Never attach
+    // the raw SDK error, message, stack, request or cause: they may hold values.
+    if (error instanceof generated_aws_control_plane_js_1.AwsGeneratedSecretInitializationError) {
+        const diagnosticCode = Object.getOwnPropertyDescriptor(error, 'code')?.value;
+        switch (diagnosticCode) {
+            case 'generated-secret-input-invalid':
+            case 'generated-secret-observation-invalid':
+            case 'generated-secret-read-failed':
+            case 'generated-secret-state-conflicting':
+            case 'generated-secret-write-failed':
+                return new SecretOperatorControlPlaneError(code, operation, diagnosticCode);
+        }
+    }
     return new SecretOperatorControlPlaneError(code, operation);
 }
 async function collectSecretMetadata(controlPlane, scope, options = {}) {
     const namePrefix = canonicalPrefix(scope);
+    const exactNames = [...new Set(options.exactNames ?? [])].sort(deterministic_order_js_1.compareUtf16);
+    if (exactNames.length !== (options.exactNames ?? []).length ||
+        exactNames.some((name) => !name.startsWith(namePrefix))) {
+        throw new SecretOperatorControlPlaneError('secret-control-plane-inventory-invalid', 'inventory');
+    }
     let listed;
     try {
         listed = await controlPlane.list({
@@ -50,8 +74,21 @@ async function collectSecretMetadata(controlPlane, scope, options = {}) {
             !item.name.startsWith(namePrefix))) {
         throw new SecretOperatorControlPlaneError('secret-control-plane-inventory-invalid', 'inventory');
     }
+    const inventory = [...listed];
+    for (const created of options.newlyCreated ?? []) {
+        if (typeof created !== 'object' ||
+            created === null ||
+            typeof created.arn !== 'string' ||
+            typeof created.name !== 'string' ||
+            !created.name.startsWith(namePrefix)) {
+            throw new SecretOperatorControlPlaneError('secret-control-plane-inventory-invalid', 'inventory');
+        }
+        if (!inventory.some(({ arn, name }) => arn === created.arn && name === created.name)) {
+            inventory.push(created);
+        }
+    }
     try {
-        return await Promise.all([...listed]
+        const described = await Promise.all(inventory
             .sort((left, right) => (0, deterministic_order_js_1.compareUtf16)(left.name, right.name))
             .map(async (item) => {
             const description = await controlPlane.describe({ arn: item.arn });
@@ -61,6 +98,24 @@ async function collectSecretMetadata(controlPlane, scope, options = {}) {
             }
             return description;
         }));
+        for (const name of exactNames) {
+            if (described.some((secret) => secret.name === name))
+                continue;
+            const exact = await controlPlane.describeExact({
+                ...(options.includePlannedDeletion === undefined
+                    ? {}
+                    : { includePlannedDeletion: options.includePlannedDeletion }),
+                name,
+            });
+            if (exact === undefined)
+                continue;
+            (0, model_js_1.validateObservedSecretMetadata)(exact);
+            if (exact.name !== name || !exact.arn.includes(`:secret:${name}-`)) {
+                throw new SecretOperatorControlPlaneError('secret-control-plane-inventory-invalid', 'describe');
+            }
+            described.push(exact);
+        }
+        return described.sort((left, right) => (0, deterministic_order_js_1.compareUtf16)(left.name, right.name));
     }
     catch (error) {
         throw safeControlPlaneError(error, 'secret-control-plane-inventory-failed', 'describe');
@@ -72,17 +127,19 @@ function hasAmbiguousOwnership(findings) {
 async function applyMutation(controlPlane, mutation) {
     try {
         if (mutation.kind === 'create-empty-container') {
-            await controlPlane.createEmpty({
+            const created = await controlPlane.createEmpty({
                 description: mutation.description,
                 name: mutation.name,
                 tags: mutation.tags,
             });
+            return Object.freeze({ arn: created.arn, name: mutation.name });
         }
         else {
             await controlPlane.tag({
                 arn: mutation.arn,
                 tags: mutation.tags,
             });
+            return undefined;
         }
     }
     catch (error) {
@@ -91,11 +148,34 @@ async function applyMutation(controlPlane, mutation) {
 }
 async function runSecretMetadataOperator(input) {
     const mode = input.mode ?? 'report';
-    const observed = await collectSecretMetadata(input.controlPlane, input.scope);
+    (0, model_js_1.validateSecretManagementScope)(input.scope);
+    const logicalNames = new Set();
+    for (const declaration of input.declarations) {
+        (0, model_js_1.validateSecretMetadataDeclaration)(declaration);
+        if (logicalNames.has(declaration.logicalName)) {
+            throw new SecretOperatorControlPlaneError('secret-control-plane-inventory-invalid', 'inventory');
+        }
+        logicalNames.add(declaration.logicalName);
+    }
+    // A generated secret's container and first value are one CreateSecret
+    // transaction. Keep it entirely out of the value-free metadata operator so
+    // this path cannot pre-create or retag the generated container.
+    const generatedNames = new Set(input.declarations
+        .filter((declaration) => declaration.source === 'generated' &&
+        declaration.requiredStages.includes(input.scope.stage))
+        .map((declaration) => (0, model_js_1.canonicalOperatorSecretName)(input.scope, declaration.logicalName)));
+    const declarations = input.declarations.filter((declaration) => declaration.source !== 'generated');
+    const exactNames = declarations
+        .filter((declaration) => declaration.requiredStages.includes(input.scope.stage))
+        .map((declaration) => (0, model_js_1.canonicalOperatorSecretName)(input.scope, declaration.logicalName));
+    const observed = await collectSecretMetadata(input.controlPlane, input.scope, {
+        exactNames,
+    });
+    const operatorObserved = observed.filter((secret) => !generatedNames.has(secret.name));
     const before = (0, metadata_js_1.reconcileSecretMetadata)({
-        declarations: input.declarations,
+        declarations,
         mode,
-        observed,
+        observed: operatorObserved,
         scope: input.scope,
     });
     if (mode === 'report') {
@@ -115,15 +195,18 @@ async function runSecretMetadataOperator(input) {
         });
     }
     const applied = [];
+    const newlyCreated = [];
     for (const mutation of before.authorizedMutations) {
-        await applyMutation(input.controlPlane, mutation);
+        const created = await applyMutation(input.controlPlane, mutation);
+        if (created)
+            newlyCreated.push(created);
         applied.push(mutation);
     }
-    const afterObserved = await collectSecretMetadata(input.controlPlane, input.scope);
+    const afterObserved = await collectSecretMetadata(input.controlPlane, input.scope, { exactNames, newlyCreated });
     const after = (0, metadata_js_1.reconcileSecretMetadata)({
-        declarations: input.declarations,
+        declarations,
         mode: 'report',
-        observed: afterObserved,
+        observed: afterObserved.filter((secret) => !generatedNames.has(secret.name)),
         scope: input.scope,
     });
     return Object.freeze({
@@ -134,6 +217,139 @@ async function runSecretMetadataOperator(input) {
         outcome: after.status === 'clean' ? 'applied' : 'applied-with-findings',
     });
 }
+async function runGeneratedSecretInitializer(input) {
+    const mode = input.mode ?? 'report';
+    if (mode !== 'apply' && mode !== 'report') {
+        throw new SecretOperatorControlPlaneError('secret-control-plane-protected-action-failed', 'initialize-generated');
+    }
+    (0, model_js_1.validateSecretManagementScope)(input.scope);
+    const names = new Set();
+    for (const declaration of input.declarations) {
+        (0, model_js_1.validateSecretMetadataDeclaration)(declaration);
+        if (names.has(declaration.logicalName)) {
+            throw new SecretOperatorControlPlaneError('secret-control-plane-protected-action-failed', 'initialize-generated');
+        }
+        names.add(declaration.logicalName);
+    }
+    const declaration = input.declarations.find(({ logicalName }) => logicalName === input.logicalName);
+    if (declaration?.source !== 'generated' ||
+        declaration.generation === undefined ||
+        !declaration.requiredStages.includes(input.scope.stage)) {
+        throw new SecretOperatorControlPlaneError('secret-control-plane-protected-action-failed', 'initialize-generated');
+    }
+    const name = (0, model_js_1.canonicalOperatorSecretName)(input.scope, declaration.logicalName);
+    const description = `EBK ${declaration.source} secret ${declaration.logicalName}`;
+    const expectedTags = (0, model_js_1.canonicalOperatorSecretTags)(input.scope, declaration);
+    const observed = await collectSecretMetadata(input.metadataControlPlane, input.scope, { exactNames: [name] });
+    // This operation owns exactly one generated declaration. Other operator or
+    // generated containers in the same Slice are outside its reconciliation
+    // scope and must not be misclassified as orphans.
+    const targetObserved = observed.filter((item) => item.name === name);
+    const findings = (0, metadata_js_1.preflightSecretMetadata)({
+        declarations: [declaration],
+        observed: targetObserved,
+        scope: input.scope,
+    }).findings;
+    const actual = targetObserved[0];
+    const missingContainer = actual === undefined &&
+        findings.length === 1 &&
+        findings[0]?.code === 'missing-container';
+    const blocking = !missingContainer &&
+        (actual === undefined ||
+            findings.some(({ code }) => code !== 'missing-current-version') ||
+            Object.entries(expectedTags).some(([key, value]) => actual?.tags[key] !== value));
+    let inspection = missingContainer
+        ? 'missing'
+        : 'conflicting';
+    if (!blocking && !missingContainer) {
+        try {
+            inspection = await input.initializationControlPlane.inspect({
+                description,
+                generation: declaration.generation.kind,
+                name,
+                tags: expectedTags,
+            });
+        }
+        catch (error) {
+            throw safeControlPlaneError(error, 'secret-control-plane-inventory-failed', 'initialize-generated');
+        }
+    }
+    const metadataCurrent = findings.length === 0;
+    const stateConsistent = missingContainer || (metadataCurrent && inspection === 'current');
+    const proposed = stateConsistent && inspection === 'missing'
+        ? [{ logicalName: declaration.logicalName, name }]
+        : [];
+    const effectiveBlocking = blocking || !stateConsistent;
+    if (mode === 'report') {
+        return Object.freeze({
+            findings: Object.freeze(findings),
+            initialized: Object.freeze([]),
+            mode,
+            outcome: effectiveBlocking ? 'blocked' : 'reported',
+            proposed: Object.freeze(proposed),
+        });
+    }
+    if (effectiveBlocking) {
+        return Object.freeze({
+            findings: Object.freeze(findings),
+            initialized: Object.freeze([]),
+            mode,
+            outcome: 'blocked',
+            proposed: Object.freeze([]),
+        });
+    }
+    if (inspection === 'current') {
+        return Object.freeze({
+            findings: Object.freeze([]),
+            initialized: Object.freeze([]),
+            mode,
+            outcome: 'unchanged',
+            proposed: Object.freeze([]),
+        });
+    }
+    let initializationOutcome;
+    try {
+        initializationOutcome =
+            await input.initializationControlPlane.initializeGenerated({
+                description,
+                generation: declaration.generation.kind,
+                name,
+                tags: expectedTags,
+            });
+    }
+    catch (error) {
+        throw safeControlPlaneError(error, 'secret-control-plane-apply-failed', 'initialize-generated');
+    }
+    let finalInspection;
+    try {
+        finalInspection = await input.initializationControlPlane.inspect({
+            description,
+            generation: declaration.generation.kind,
+            name,
+            tags: expectedTags,
+        });
+    }
+    catch (error) {
+        throw safeControlPlaneError(error, 'secret-control-plane-inventory-failed', 'initialize-generated');
+    }
+    if (finalInspection !== 'current') {
+        throw new SecretOperatorControlPlaneError('secret-control-plane-apply-failed', 'initialize-generated', finalInspection === 'conflicting'
+            ? 'generated-secret-state-conflicting'
+            : 'generated-secret-observation-invalid');
+    }
+    // The exact-name control-plane inspection above is the postcondition.
+    // ListSecrets is eventually consistent and can omit a newly created secret
+    // for minutes, so it is not safe evidence for this just-completed mutation.
+    return Object.freeze({
+        findings: Object.freeze([]),
+        initialized: Object.freeze(initializationOutcome === 'applied'
+            ? [{ logicalName: declaration.logicalName, name }]
+            : []),
+        mode,
+        outcome: initializationOutcome,
+        proposed: Object.freeze(proposed),
+    });
+}
 async function runSecretDeployPreflight(input) {
     if (input.action !== 'deploy') {
         return Object.freeze({
@@ -143,7 +359,12 @@ async function runSecretDeployPreflight(input) {
             ready: true,
         });
     }
-    const observed = await collectSecretMetadata(input.controlPlane, input.scope);
+    const exactNames = input.declarations
+        .filter((declaration) => declaration.requiredStages.includes(input.scope.stage))
+        .map((declaration) => (0, model_js_1.canonicalOperatorSecretName)(input.scope, declaration.logicalName));
+    const observed = await collectSecretMetadata(input.controlPlane, input.scope, {
+        exactNames,
+    });
     const result = (0, metadata_js_1.preflightSecretMetadata)({
         declarations: input.declarations,
         observed,
@@ -155,6 +376,232 @@ async function runSecretDeployPreflight(input) {
         bypassed: false,
     });
 }
+function hasExactTags(actual, expected) {
+    const actualKeys = Object.keys(actual).sort(deterministic_order_js_1.compareUtf16);
+    const expectedKeys = Object.keys(expected).sort(deterministic_order_js_1.compareUtf16);
+    return (actualKeys.length === expectedKeys.length &&
+        actualKeys.every((key, index) => key === expectedKeys[index] && actual[key] === expected[key]));
+}
+function isExactGeneratedSecret(observed, declaration, scope, authority) {
+    const name = (0, model_js_1.canonicalOperatorSecretName)(scope, declaration.logicalName);
+    const arnPrefix = `arn:${authority.partition}:secretsmanager:${authority.region}:${authority.accountId}:secret:${name}-`;
+    const tags = (0, model_js_1.canonicalOperatorSecretTags)(scope, declaration);
+    return (declaration.source === 'generated' &&
+        declaration.generation?.kind === 'hmac-key-ring-v1' &&
+        tags[model_js_1.SECRET_METADATA_TAG_KEYS.management] ===
+            model_js_1.GENERATED_SECRET_MANAGEMENT_CLASS &&
+        observed.name === name &&
+        observed.arn.startsWith(arnPrefix) &&
+        /^[A-Za-z0-9]{6}$/.test(observed.arn.slice(arnPrefix.length)) &&
+        hasExactTags(observed.tags, tags));
+}
+const GENERATED_SECRET_ABSENCE_POLL_INTERVAL_MS = 2_000;
+const GENERATED_SECRET_ABSENCE_TIMEOUT_MS = 10 * 60 * 1_000;
+const GENERATED_SECRET_FORCE_DELETE_CLOCK_SKEW_MS = 5 * 60 * 1_000;
+const GENERATED_SECRET_RECOVERY_WINDOW_MS = 7 * 24 * 60 * 60 * 1_000;
+function isWithinGeneratedSecretRecoveryWindow(recoveryUntil, observedAt) {
+    if (typeof recoveryUntil !== 'string')
+        return false;
+    const recoveryUntilTimestamp = Date.parse(recoveryUntil);
+    return (!Number.isNaN(recoveryUntilTimestamp) &&
+        recoveryUntilTimestamp <=
+            observedAt +
+                GENERATED_SECRET_RECOVERY_WINDOW_MS +
+                GENERATED_SECRET_FORCE_DELETE_CLOCK_SKEW_MS);
+}
+/**
+ * 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.
+ */
+async function runGeneratedSecretRetirement(input) {
+    (0, model_js_1.validateSecretManagementScope)(input.scope);
+    if (!/^\d{12}$/.test(input.accountId) ||
+        !/^[a-z]{2}(?:-gov)?-[a-z]+-\d$/.test(input.region)) {
+        throw new SecretOperatorControlPlaneError('secret-control-plane-protected-action-failed', 'retire');
+    }
+    const logicalNames = new Set();
+    for (const declaration of input.declarations) {
+        (0, model_js_1.validateSecretMetadataDeclaration)(declaration);
+        if (logicalNames.has(declaration.logicalName)) {
+            throw new SecretOperatorControlPlaneError('secret-control-plane-inventory-invalid', 'inventory');
+        }
+        logicalNames.add(declaration.logicalName);
+    }
+    const declarations = input.declarations
+        .filter((declaration) => declaration.source === 'generated' &&
+        declaration.generation?.kind === 'hmac-key-ring-v1' &&
+        declaration.logicalName === model_js_1.GENERATED_HMAC_SECRET_LOGICAL_NAME &&
+        declaration.requiredStages.includes(input.scope.stage))
+        .sort((left, right) => (0, deterministic_order_js_1.compareUtf16)(left.logicalName, right.logicalName));
+    const deletionMode = input.scope.stage === 'production' ? 'recovery-window' : 'immediate';
+    const secrets = [];
+    for (const declaration of declarations) {
+        const name = (0, model_js_1.canonicalOperatorSecretName)(input.scope, declaration.logicalName);
+        let observed;
+        try {
+            observed = await input.controlPlane.describeExact({
+                includePlannedDeletion: true,
+                name,
+            });
+        }
+        catch (error) {
+            throw safeControlPlaneError(error, 'secret-control-plane-inventory-failed', 'describe');
+        }
+        if (observed === undefined) {
+            secrets.push(Object.freeze({
+                generation: 'hmac-key-ring-v1',
+                logicalName: declaration.logicalName,
+                name,
+                outcome: 'not-found',
+                source: 'generated',
+            }));
+            continue;
+        }
+        try {
+            (0, model_js_1.validateObservedSecretMetadata)(observed);
+        }
+        catch {
+            throw new SecretOperatorControlPlaneError('secret-control-plane-inventory-invalid', 'inventory');
+        }
+        if (!isExactGeneratedSecret(observed, declaration, input.scope, {
+            accountId: input.accountId,
+            partition: input.partition,
+            region: input.region,
+        })) {
+            throw new SecretOperatorControlPlaneError('secret-control-plane-inventory-invalid', 'inventory');
+        }
+        const now = input.now ?? Date.now;
+        if (observed.deletionPendingUntil !== undefined &&
+            deletionMode === 'recovery-window') {
+            const observedAt = now();
+            if (!isWithinGeneratedSecretRecoveryWindow(observed.deletionPendingUntil, observedAt)) {
+                throw new SecretOperatorControlPlaneError('secret-control-plane-inventory-invalid', 'inventory');
+            }
+            secrets.push(Object.freeze({
+                generation: 'hmac-key-ring-v1',
+                logicalName: declaration.logicalName,
+                name,
+                outcome: 'already-scheduled',
+                recoveryUntil: observed.deletionPendingUntil,
+                source: 'generated',
+            }));
+            continue;
+        }
+        if (deletionMode === 'immediate') {
+            const waitBeforeRetry = input.waitBeforeRetry ??
+                ((delayMs) => new Promise((resolve) => setTimeout(resolve, delayMs)));
+            const waitForState = async (expected) => {
+                const deadline = now() + GENERATED_SECRET_ABSENCE_TIMEOUT_MS;
+                while (true) {
+                    let remaining;
+                    try {
+                        remaining = await input.controlPlane.describeExact({
+                            includePlannedDeletion: true,
+                            name,
+                        });
+                    }
+                    catch (error) {
+                        throw safeControlPlaneError(error, 'secret-control-plane-inventory-failed', 'describe');
+                    }
+                    if (remaining === undefined) {
+                        if (expected === 'absent')
+                            return;
+                    }
+                    else {
+                        try {
+                            (0, model_js_1.validateObservedSecretMetadata)(remaining);
+                        }
+                        catch {
+                            throw new SecretOperatorControlPlaneError('secret-control-plane-inventory-invalid', 'inventory');
+                        }
+                        if (!isExactGeneratedSecret(remaining, declaration, input.scope, {
+                            accountId: input.accountId,
+                            partition: input.partition,
+                            region: input.region,
+                        })) {
+                            throw new SecretOperatorControlPlaneError('secret-control-plane-inventory-invalid', 'inventory');
+                        }
+                        if (expected === 'active' &&
+                            remaining.deletionPendingUntil === undefined) {
+                            return;
+                        }
+                    }
+                    if (now() >= deadline) {
+                        throw new SecretOperatorControlPlaneError('secret-control-plane-protected-action-failed', 'retire');
+                    }
+                    await waitBeforeRetry(GENERATED_SECRET_ABSENCE_POLL_INTERVAL_MS);
+                }
+            };
+            if (observed.deletionPendingUntil !== undefined) {
+                if (Date.parse(observed.deletionPendingUntil) <=
+                    now() + GENERATED_SECRET_FORCE_DELETE_CLOCK_SKEW_MS) {
+                    await waitForState('absent');
+                    secrets.push(Object.freeze({
+                        generation: 'hmac-key-ring-v1',
+                        logicalName: declaration.logicalName,
+                        name,
+                        outcome: 'deleted',
+                        source: 'generated',
+                    }));
+                    continue;
+                }
+                try {
+                    await input.controlPlane.restore({ arn: observed.arn });
+                }
+                catch (error) {
+                    throw safeControlPlaneError(error, 'secret-control-plane-protected-action-failed', 'recover');
+                }
+                await waitForState('active');
+            }
+            try {
+                await input.controlPlane.deleteImmediately({ arn: observed.arn });
+            }
+            catch (error) {
+                throw safeControlPlaneError(error, 'secret-control-plane-protected-action-failed', 'retire');
+            }
+            await waitForState('absent');
+            secrets.push(Object.freeze({
+                generation: 'hmac-key-ring-v1',
+                logicalName: declaration.logicalName,
+                name,
+                outcome: 'deleted',
+                source: 'generated',
+            }));
+            continue;
+        }
+        let scheduled;
+        try {
+            scheduled = await input.controlPlane.scheduleRetirement({
+                arn: observed.arn,
+                recoveryWindowDays: 7,
+            });
+        }
+        catch (error) {
+            throw safeControlPlaneError(error, 'secret-control-plane-protected-action-failed', 'retire');
+        }
+        if (!isWithinGeneratedSecretRecoveryWindow(scheduled.recoveryUntil, now())) {
+            throw new SecretOperatorControlPlaneError('secret-control-plane-protected-action-failed', 'retire');
+        }
+        secrets.push(Object.freeze({
+            generation: 'hmac-key-ring-v1',
+            logicalName: declaration.logicalName,
+            name,
+            outcome: 'scheduled',
+            recoveryUntil: scheduled.recoveryUntil,
+            source: 'generated',
+        }));
+    }
+    return Object.freeze({
+        deletionMode,
+        outcome: declarations.length === 0 ? 'not-applicable' : 'retired',
+        ...(deletionMode === 'recovery-window'
+            ? { recoveryWindowDays: 7 }
+            : {}),
+        secrets: Object.freeze(secrets),
+        stage: input.scope.stage,
+    });
+}
 const canonicalStages = new Set(['development', 'staging', 'production']);
 const logicalNamePattern = /^[A-Za-z][A-Za-z0-9]{0,63}$/;
 function validateProtectedAuthorization(authorization, logicalName, scope) {
@@ -186,7 +633,10 @@ async function runProtectedSecretLifecycle(input) {
             input.recoveryWindowDays > 30)) {
         throw new SecretOperatorControlPlaneError('secret-control-plane-protected-action-failed', 'retire');
     }
-    const observed = await collectSecretMetadata(input.controlPlane, input.scope, { includePlannedDeletion: true });
+    const observed = await collectSecretMetadata(input.controlPlane, input.scope, {
+        exactNames: [(0, model_js_1.canonicalOperatorSecretName)(input.scope, input.logicalName)],
+        includePlannedDeletion: true,
+    });
     const matches = observed.filter((secret) => isOwnedOperatorSecret(secret, input.logicalName, input.scope));
     if (matches.length !== 1) {
         throw new SecretOperatorControlPlaneError('secret-control-plane-inventory-invalid', 'inventory');

package/src/secrets/personal-command.d.ts

@@ -4,9 +4,17 @@ export interface HumanSecretCeremony {
     readonly [HUMAN_SECRET_CEREMONY]: true;
     actor: 'human';
     agentDelegated: boolean;
+    /** Name (never value) of the first agent or CI marker variable detected. */
+    detectedMarker?: string;
     interactive: boolean;
     stdinIsTty: boolean;
 }
+export type PersonalSecretOperation = 'remove' | 'set';
+interface HumanRequiredDetail {
+    detectedMarker?: string;
+    operation: PersonalSecretOperation;
+    reason: 'agent-or-ci' | 'capability' | 'terminal';
+}
 export interface HiddenSecretInputReader {
     readHidden(input: {
         logicalName: string;
@@ -49,7 +57,7 @@ export interface PersonalSecretCommandResult {
 }
 export declare class PersonalSecretCommandError extends Error {
     readonly code: 'personal-secret-account-invalid' | 'personal-secret-command-invalid' | 'personal-secret-confirmation-required' | 'personal-secret-hidden-input-failed' | 'personal-secret-human-required' | 'personal-secret-stage-invalid' | 'personal-secret-store-failed' | 'personal-secret-value-invalid';
-    constructor(code: PersonalSecretCommandError['code']);
+    constructor(code: PersonalSecretCommandError['code'], detail?: HumanRequiredDetail);
 }
 interface PersonalSecretEnvironment {
     accountId: string;
@@ -74,10 +82,18 @@ export interface RemovePersonalSecretInput extends PersonalSecretEnvironment {
  */
 export declare function issueHumanSecretCeremony(input: {
     agentDelegated: boolean;
+    detectedMarker?: string;
     interactive: boolean;
     stdinIsTty: boolean;
 }): HumanSecretCeremony;
-export declare function assertHumanSecretCeremony(ceremony: HumanSecretCeremony): void;
+/**
+ * `set` carries a human-supplied value, so it refuses every agent or CI
+ * marker: a real TTY proves nothing when an agent owns the terminal. `remove`
+ * carries no value and only targets the human's personal development stage,
+ * so an agent-delegated session may start it; it still needs a local
+ * interactive terminal where the human types the hidden confirmation.
+ */
+export declare function assertHumanSecretCeremony(ceremony: HumanSecretCeremony, operation: PersonalSecretOperation): void;
 export declare function setPersonalSstSecret(input: SetPersonalSecretInput): Promise<PersonalSecretCommandResult>;
 export declare function removePersonalSstSecret(input: RemovePersonalSecretInput): Promise<PersonalSecretCommandResult>;
 export {};