@atlasauth/cli 0.25.1 → 0.27.0

package/dist/commands/config.js

@@ -34,10 +34,12 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_CONFIG_FILES = void 0;
+exports.didYouMean = didYouMean;
 exports.config = config;
 exports.resolveFormat = resolveFormat;
 exports.planConfigImport = planConfigImport;
 exports.diffFields = diffFields;
+exports.printedFields = printedFields;
 exports.readSecretsEnv = readSecretsEnv;
 exports.unresolvedPlaceholders = unresolvedPlaceholders;
 exports.configTypes = configTypes;
@@ -57,6 +59,9 @@ const serialize_1 = require("../serialize");
 const backend_1 = require("@atlasauth/backend");
 const shared_1 = require("./shared");
 const secrets_1 = require("../secrets");
+const redact_1 = require("../redact");
+/** The refusal `rotate_secret` answers when the secret is the one already stored. */
+const isSameSecretRefusal = (err) => err instanceof backend_1.AtlasApiError && err.status === 422 && /must differ/.test(err.message);
 // ───────────────────────────── small helpers ─────────────────────────────
 /** GET a `{ data: [...] }` list envelope, tolerating an absent/garbled body. */
 async function listData(http, path) {
@@ -130,12 +135,14 @@ function registry() {
             async apply(http, config) {
                 await http.put('/v1/messaging_providers/email', compact(withoutMarkers(config)));
             },
-            normalize: (c) => redactSecrets(c, ['config']),
+            fileKeys: ['transport', 'from_address', 'mode', 'config'],
+            reportsSecrets: true,
         },
         // 1. Instance config (auth_config + allowed origins) — the §9.3 singleton.
         {
             kind: 'singleton',
             type: 'instance',
+            fileKeys: ['allowed_origins', 'auth_config'],
             async fetchLive(http) {
                 const inst = await http.get('/v1/instance');
                 const hints = obj(inst.allowed_origin_integrations ?? null);
@@ -185,6 +192,7 @@ function registry() {
         {
             kind: 'singleton',
             type: 'org_settings_schema',
+            fileKeys: ['schema'],
             async fetchLive(http) {
                 try {
                     const s = await http.get('/v1/organization_settings_schema');
@@ -205,6 +213,7 @@ function registry() {
         {
             kind: 'collection',
             type: 'redirect_urls',
+            fileKeys: ['url'],
             keyOf: (c) => String(obj(c).url ?? ''),
             async fetchLive(http) {
                 const rows = await listData(http, '/v1/redirect_urls');
@@ -221,6 +230,7 @@ function registry() {
         {
             kind: 'collection',
             type: 'oauth_clients',
+            fileKeys: [...OAUTH_CLIENT_KEYS, ...OAUTH_CLIENT_WRITE_KEYS],
             keyOf: (c) => String(obj(c).name ?? ''),
             async fetchLive(http) {
                 const rows = await listData(http, '/v1/oauth_clients');
@@ -278,12 +288,37 @@ function registry() {
                     throw err;
                 }
             },
-            normalize: (c) => redactSecrets(c, ['before_user_create']),
+            fileKeys: ['before_user_create'],
+            nestedKeys: { before_user_create: ['url', 'timeout_ms', 'fail_closed', 'enabled', 'signing_secret'] },
+            reportsSecrets: true,
         },
         // 5. Social / enterprise OAuth providers — key = the catalog provider slug.
         {
             kind: 'collection',
             type: 'oauth_providers',
+            fileKeys: [...OAUTH_PROVIDER_KEYS, 'client_secret', 'values', 'settings'],
+            validate(config) {
+                const { provider, mode } = obj(config);
+                if (mode === undefined || mode === 'native' || mode === 'redirect' || hasPlaceholder(mode))
+                    return [];
+                return [`oauth_providers ${String(provider)}: mode must be native or redirect, got ${JSON.stringify(mode)}.`];
+            },
+            reportsSecrets: true,
+            defaulted: ['mode'],
+            writeOnly: ['values'],
+            warnings(config, live) {
+                const c = obj(config);
+                const lv = obj(live ?? null);
+                const inFile = typeof c.client_secret === 'string' && c.client_secret !== '';
+                const out = [];
+                if (c.mode === 'redirect' && !inFile && !lv.client_secret) {
+                    out.push(`oauth_providers ${String(c.provider)}: mode redirect needs a client_secret, and neither the file nor the instance has one.`);
+                }
+                if ((c.mode ?? lv.mode) === 'native' && inFile) {
+                    out.push(`oauth_providers ${String(c.provider)}: secret unused in native mode. Remove client_secret, or set mode: redirect.`);
+                }
+                return out;
+            },
             keyOf: (c) => String(obj(c).provider ?? ''),
             async fetchLive(http) {
                 const rows = await listData(http, '/v1/oauth_providers');
@@ -292,7 +327,11 @@ function registry() {
                     .map((r) => ({
                     key: String(r.provider ?? ''),
                     id: String(r.provider ?? ''),
-                    config: pick(r, OAUTH_PROVIDER_KEYS),
+                    config: {
+                        ...obj(pick(r, OAUTH_PROVIDER_KEYS)),
+                        ...(r.setting_values && Object.keys(r.setting_values).length ? { settings: r.setting_values } : {}),
+                        ...(r.has_secret === true ? { client_secret: SECRET_SET } : {}),
+                    },
                 }));
             },
             create: putProvider,
@@ -305,13 +344,15 @@ function registry() {
         {
             kind: 'collection',
             type: 'custom_oauth_providers',
+            fileKeys: [...CUSTOM_PROVIDER_KEYS, ...CUSTOM_PROVIDER_WRITE_KEYS],
+            reportsSecrets: true,
             keyOf: (c) => String(obj(c).provider_key ?? ''),
             async fetchLive(http) {
                 const rows = await listData(http, '/v1/custom_oauth_providers');
                 return rows.map((r) => ({
                     key: String(r.provider_key ?? ''),
                     id: String(r.id ?? ''),
-                    config: pick(r, CUSTOM_PROVIDER_KEYS),
+                    config: { ...obj(pick(r, CUSTOM_PROVIDER_KEYS)), ...(r.has_secret === true ? { client_secret: SECRET_SET } : {}) },
                 }));
             },
             async create(http, config) {
@@ -330,6 +371,7 @@ function registry() {
         {
             kind: 'collection',
             type: 'resource_servers',
+            fileKeys: [...RESOURCE_SERVER_KEYS, 'publish_resource_metadata', 'access_token_format', 'refresh_token_absolute_ttl_seconds', 'refresh_token_idle_ttl_seconds', 'introspection_client_ids'],
             keyOf: (c) => String(obj(c).identifier ?? ''),
             async fetchLive(http) {
                 const rows = await listData(http, '/v1/resource_servers');
@@ -358,6 +400,7 @@ function registry() {
         {
             kind: 'collection',
             type: 'jwt_templates',
+            fileKeys: ['name', 'claims'],
             keyOf: (c) => String(obj(c).name ?? ''),
             async fetchLive(http) {
                 const rows = await listData(http, '/v1/jwt_templates');
@@ -382,6 +425,7 @@ function registry() {
         {
             kind: 'collection',
             type: 'permissions',
+            fileKeys: PERMISSION_KEYS,
             keyOf: (c) => String(obj(c).key ?? ''),
             async fetchLive(http) {
                 const rows = await listData(http, '/v1/permissions');
@@ -404,6 +448,7 @@ function registry() {
         {
             kind: 'collection',
             type: 'roles',
+            fileKeys: [...ROLE_KEYS, 'visibility'],
             keyOf: (c) => String(obj(c).key ?? ''),
             async fetchLive(http) {
                 const rows = await listData(http, '/v1/roles');
@@ -436,6 +481,25 @@ function registry() {
         {
             kind: 'collection',
             type: 'webhook_endpoints',
+            fileKeys: [...WEBHOOK_KEYS, 'secret'],
+            validate(config) {
+                const { url, secret } = obj(config);
+                if (secret === undefined || secret === null || hasPlaceholder(secret))
+                    return [];
+                if (typeof secret === 'string' && WEBHOOK_SECRET.test(secret))
+                    return [];
+                return [`webhook_endpoints ${String(url)}: secret must start with "whsec_" followed by 32 to 256 characters (letters, digits, + / = _ -). Omit it and Atlas generates one.`];
+            },
+            // A dry-run rotation tells a new secret from the stored one without revealing either.
+            async secretChanged(http, live, config) {
+                try {
+                    await http.post(`/v1/webhook_endpoints/${enc(live.id)}/rotate_secret?dry_run=true`, { secret: obj(config).secret });
+                    return true;
+                }
+                catch (err) {
+                    return isSameSecretRefusal(err) ? false : null;
+                }
+            },
             keyOf: (c) => String(obj(c).url ?? ''),
             async fetchLive(http) {
                 const rows = await listData(http, '/v1/webhook_endpoints');
@@ -453,10 +517,22 @@ function registry() {
                     enabled_events: c.enabled_events ?? [],
                     // Sent on create so a paused endpoint is never live, even briefly.
                     ...(typeof c.active === 'boolean' ? { active: c.active } : {}),
+                    ...(typeof c.secret === 'string' ? { secret: c.secret } : {}),
                 });
             },
             async update(http, live, config) {
-                await http.patch(`/v1/webhook_endpoints/${enc(live.id)}`, compact(config, true));
+                // PATCH leaves the signing secret alone; only rotate_secret changes it.
+                const { secret, ...rest } = obj(config);
+                await http.patch(`/v1/webhook_endpoints/${enc(live.id)}`, compact(rest, true));
+                if (typeof secret !== 'string' || !secret)
+                    return;
+                try {
+                    await http.post(`/v1/webhook_endpoints/${enc(live.id)}/rotate_secret`, { secret });
+                }
+                catch (err) {
+                    if (!isSameSecretRefusal(err))
+                        throw err;
+                }
             },
             async remove(http, live) {
                 await http.delete(`/v1/webhook_endpoints/${enc(live.id)}`);
@@ -466,11 +542,14 @@ function registry() {
         {
             kind: 'collection',
             type: 'sso_connections',
+            fileKeys: [...SSO_KEYS, ...SSO_WRITE_KEYS],
+            reportsSecrets: true,
+            writeOnly: ['saml_idp_certificate'],
             keyOf: ssoKey,
             async fetchLive(http) {
                 const rows = await listData(http, '/v1/sso_connections');
                 return rows.map((r) => {
-                    const config = pick(r, SSO_KEYS);
+                    const config = { ...obj(pick(r, SSO_KEYS)), ...(r.has_secret === true ? { oidc_client_secret: SECRET_SET, discourse_secret: SECRET_SET } : {}) };
                     return { key: ssoKey(config), id: String(r.id ?? ''), config };
                 });
             },
@@ -491,6 +570,7 @@ function registry() {
         {
             kind: 'collection',
             type: 'sso_onboarding_profiles',
+            fileKeys: SSO_PROFILE_KEYS,
             keyOf: (c) => String(obj(c).name ?? ''),
             async fetchLive(http) {
                 let rows;
@@ -521,6 +601,7 @@ function registry() {
         {
             kind: 'collection',
             type: 'billing_plans',
+            fileKeys: [...BILLING_KEYS, 'grace_days', 'provider_price_id', 'annual_amount', 'seat_feature_id', 'promotion'],
             keyOf: (c) => String(obj(c).slug ?? ''),
             async fetchLive(http) {
                 const rows = await listData(http, '/v1/billing/plans');
@@ -546,6 +627,7 @@ function registry() {
         {
             kind: 'collection',
             type: 'notification_templates',
+            fileKeys: NOTIFICATION_KEYS,
             keyOf: (c) => String(obj(c).name ?? ''),
             async fetchLive(http) {
                 const rows = await listData(http, '/v1/notification_templates');
@@ -571,6 +653,7 @@ function registry() {
         {
             kind: 'collection',
             type: 'email_templates',
+            fileKeys: EMAIL_KEYS,
             keyOf: (c) => String(obj(c).name ?? ''),
             async fetchLive(http) {
                 const rows = await listData(http, '/v1/email_templates');
@@ -596,6 +679,7 @@ function registry() {
         {
             kind: 'collection',
             type: 'organization_policies',
+            fileKeys: ORG_POLICY_KEYS,
             keyOf: (c) => String(obj(c).organization_id ?? ''),
             async fetchLive(http) {
                 const orgs = await listData(http, '/v1/organizations');
@@ -648,6 +732,7 @@ function registry() {
         {
             kind: 'singleton',
             type: 'cookie_consent',
+            fileKeys: COOKIE_CONSENT_KEYS,
             async fetchLive(http) {
                 let cc;
                 try {
@@ -677,6 +762,7 @@ function registry() {
         {
             kind: 'singleton',
             type: 'sign_in_with_atlas',
+            fileKeys: ['enabled', 'connection_id'],
             async fetchLive(http) {
                 let live;
                 try {
@@ -705,6 +791,7 @@ function registry() {
         {
             kind: 'singleton',
             type: 'signing_key_policy',
+            fileKeys: ['prepublish_days'],
             async fetchLive(http) {
                 let live;
                 try {
@@ -754,6 +841,20 @@ const OAUTH_CLIENT_KEYS = [
     'access_token_format',
     'token_lifetimes',
 ];
+/** What a file may also send on an OAuth client: accepted on write, never exported. */
+const OAUTH_CLIENT_WRITE_KEYS = [
+    'application_type',
+    'client_secret',
+    'secret_expires_in_seconds',
+    'jwks',
+    'jwks_uri',
+    'tls_client_auth_subject_dn',
+    'frontchannel_logout_session_required',
+    'disabled',
+    'metadata',
+    'external_ref',
+    'add_redirect_origins',
+];
 const OAUTH_PROVIDER_KEYS = [
     'provider',
     'enabled',
@@ -761,6 +862,7 @@ const OAUTH_PROVIDER_KEYS = [
     'allow_sign_up',
     'scopes',
     'client_id',
+    'mode',
 ];
 const RESOURCE_SERVER_KEYS = [
     'identifier',
@@ -794,6 +896,18 @@ const CUSTOM_PROVIDER_KEYS = [
     'allow_sign_in',
     'allow_sign_up',
 ];
+const CUSTOM_PROVIDER_WRITE_KEYS = [
+    'client_secret',
+    'end_session_endpoint',
+    'revocation_endpoint',
+    'host_params_schema',
+    'data_only',
+    'scope_separator',
+    'userinfo_auth',
+    'client_assertion_audience',
+    'logout',
+    'idp_initiated_login',
+];
 const WEBHOOK_KEYS = ['url', 'enabled_events', 'active'];
 const SSO_KEYS = [
     'type',
@@ -812,6 +926,29 @@ const SSO_KEYS = [
     'claim_role_mappings',
     'default_role_id',
 ];
+const SSO_WRITE_KEYS = [
+    'oidc_client_secret',
+    'saml_idp_certificate',
+    'saml_single_logout',
+    'saml_idp_slo_url',
+    'saml_idp_slo_response_url',
+    'saml_idp_slo_binding',
+    'saml_idp_slo_soap_url',
+    'saml_require_encrypted_assertions',
+    'saml_acs_path',
+    'require_consent_screen',
+    'discourse_secret',
+    'provisioning_mode',
+    'manual_endpoints',
+    'github_access',
+    'attribute_mapping',
+    'oidc_scopes',
+    'profile_mapping',
+    'token_endpoint_auth_method',
+    'client_assertion_audience',
+    'logout',
+    'idp_initiated_login',
+];
 const SSO_PROFILE_KEYS = ['name', 'allowed_connection_types', 'organization_id', 'company_name', 'allow_scim', 'intents', 'return_url'];
 const COOKIE_CONSENT_KEYS = ['enabled', 'script_url', 'script_id', 'site_id', 'blocking_mode', 'extra_origins', 'settings_link', 'culture', 'host_aliases'];
 const BILLING_KEYS = [
@@ -852,18 +989,109 @@ function obj(config) {
 }
 /** What a write-only secret looks like on the live side, and in a plan. */
 const SECRET_SET = '(secret set)';
-const SECRET_KEY = /(secret|token|password|passwd|api_?key|private_?key)/i;
+const isObj = (x) => x !== null && typeof x === 'object' && !Array.isArray(x);
 /**
- * Show each secret value under `groups` as "(secret set)" so a plan never echoes it
- * and compares equal to the live "(secret set)". An unresolved \${VAR} stays visible
- * (apply refuses it), as does an empty value.
+ * Bring a file's secrets and the live document to one comparable shape. A secret
+ * value becomes "(secret set)", so a plan never holds it and it compares equal to
+ * the live marker. `unverifiable` lists the secrets set on both sides, or that the
+ * API never reports (`reported` false): Atlas cannot say whether they differ, so
+ * they are not drift, and the plan says so. A secret the API reports as unset stays
+ * a difference. An unresolved ${VAR} stays visible (apply refuses it), as does an
+ * empty value.
  */
-function redactSecrets(config, groups) {
-    const out = { ...obj(config) };
-    const mask = (g) => Object.fromEntries(Object.entries(g).map(([k, v]) => [k, SECRET_KEY.test(k) && typeof v === 'string' && v !== '' && !/^\$\{[A-Z0-9_]+\}$/.test(v) ? SECRET_SET : v]));
-    for (const g of groups)
-        if (out[g] && typeof out[g] === 'object' && !Array.isArray(out[g]))
-            out[g] = mask(obj(out[g]));
+function reconcileSecrets(desired, live, reported, prefix = '') {
+    if (!isObj(desired))
+        return { desired, live, unverifiable: [] };
+    const d = { ...desired };
+    const l = isObj(live) ? { ...live } : {};
+    const unverifiable = [];
+    for (const [k, v] of Object.entries(desired)) {
+        const path = prefix ? `${prefix}.${k}` : k;
+        if (isObj(v)) {
+            const inner = reconcileSecrets(v, l[k], reported, path);
+            d[k] = inner.desired;
+            if (isObj(l[k]))
+                l[k] = inner.live;
+            unverifiable.push(...inner.unverifiable);
+        }
+        else if ((0, redact_1.isSecretKey)(k) && typeof v === 'string' && v !== '' && v !== SECRET_SET && !(0, redact_1.isPlaceholder)(v)) {
+            if (l[k] === SECRET_SET) {
+                d[k] = SECRET_SET;
+                unverifiable.push(path);
+            }
+            else if (l[k] === undefined || l[k] === null) {
+                d[k] = SECRET_SET;
+                if (!reported) {
+                    l[k] = SECRET_SET;
+                    unverifiable.push(path);
+                }
+            }
+        }
+    }
+    return { desired: d, live: isObj(live) || unverifiable.length ? l : live, unverifiable };
+}
+/** The live document without the secret markers and server defaults the file says nothing about. */
+function withoutUnstated(live, desired, defaulted = []) {
+    if (!isObj(live))
+        return live;
+    const want = isObj(desired) ? desired : {};
+    const out = {};
+    for (const [k, v] of Object.entries(live)) {
+        if (!(k in want) && (v === SECRET_SET || defaulted.includes(k)))
+            continue;
+        out[k] = isObj(v) && isObj(want[k]) ? withoutUnstated(v, want[k]) : v;
+    }
+    return out;
+}
+/** How close two key names are (edit distance). */
+function distance(a, b) {
+    let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        const row = [i];
+        for (let j = 1; j <= b.length; j++)
+            row[j] = Math.min(prev[j] + 1, row[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        prev = row;
+    }
+    return prev[b.length];
+}
+function didYouMean(key, known) {
+    const norm = (x) => x.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase();
+    const best = [...known].sort((a, b) => distance(norm(key), a) - distance(norm(key), b))[0];
+    return best && distance(norm(key), best) <= Math.max(2, Math.floor(key.length / 3)) ? ` (did you mean ${best}?)` : '';
+}
+/** The keys in one parsed resource file that no spec knows, each named with its nearest real key. */
+function unknownFileKeys(spec, doc) {
+    const out = [];
+    const check = (value, known, label) => {
+        if (!isObj(value))
+            return;
+        for (const k of Object.keys(value))
+            if (!known.includes(k))
+                out.push(`${label}: ${k}${didYouMean(k, known)}`);
+    };
+    if (spec.kind === 'collection') {
+        for (const entry of asArray(doc))
+            check(entry, spec.fileKeys, `${spec.type} ${spec.keyOf(entry) || '(no key)'}`);
+    }
+    else if (spec.fileKeys) {
+        check(doc, spec.fileKeys, spec.type);
+        for (const [k, known] of Object.entries(spec.nestedKeys ?? {}))
+            if (isObj(doc))
+                check(doc[k], known, `${spec.type}.${k}`);
+    }
+    return out;
+}
+/** The API's rule for a client-chosen webhook signing secret, including its `atlas_<env>_whsec_` form. */
+const WEBHOOK_SECRET = /^(?:atlas_(?:live|test)_)?whsec_[A-Za-z0-9+/=_-]{32,256}$/;
+/** A `${VAR}` still in a value: there is nothing to check yet, and apply refuses it on its own. */
+const hasPlaceholder = (v) => typeof v === 'string' && /\$\{[A-Z0-9_]+\}/.test(v);
+/** What one resource file's values break, from each spec's own rules. */
+function invalidFileValues(spec, doc) {
+    if (spec.kind !== 'collection' || !spec.validate)
+        return [];
+    const out = [];
+    for (const entry of asArray(doc))
+        out.push(...spec.validate(entry));
     return out;
 }
 /** A document without any "(secret set)" marker: what an export writes and what apply sends. */
@@ -910,6 +1138,8 @@ async function putProvider(http, config) {
     // Credential-less providers (siwe, siws, siwb, siwf) take verifier settings instead.
     if (c.settings && typeof c.settings === 'object' && !Array.isArray(c.settings))
         body.settings = c.settings;
+    if (c.mode !== undefined)
+        body.mode = c.mode;
     const provider = String(c.provider ?? '');
     if (Object.keys(body).length) {
         await http.put(`/v1/oauth_providers/${enc(provider)}`, body);
@@ -976,10 +1206,10 @@ function resolveDir(values) {
     return (0, args_1.str)(values, 'dir') || './atlas-config';
 }
 /** Build the config HTTP client from the resolved profile credential. */
-function requireHttp(ctx, values) {
+function requireHttp(ctx, values, onUnknownFields) {
     const auth = (0, shared_1.resolveAuth)(ctx, values);
     const make = ctx.makeHttp ?? config_http_1.createConfigHttp;
-    return make({ secretKey: auth.secretKey, apiUrl: auth.apiUrl });
+    return make({ secretKey: auth.secretKey, apiUrl: auth.apiUrl, ...(onUnknownFields ? { onUnknownFields } : {}) });
 }
 /** Write every resource type's live config to `dir` (deterministic, secrets omitted); returns the file count. */
 async function writeExport(http, dir, format) {
@@ -998,7 +1228,7 @@ async function writeExport(http, dir, format) {
             const entries = (await spec.fetchLive(http)).filter((e) => !e.managedBy);
             // Deterministic: entries sorted by natural key, keys sorted inside each.
             const sorted = [...entries].sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
-            const doc = sorted.map((e) => (0, serialize_1.canonicalize)(e.config));
+            const doc = sorted.map((e) => (0, serialize_1.canonicalize)(withoutMarkers(e.config)));
             (0, node_fs_1.writeFileSync)((0, node_path_1.join)(dir, `${spec.type}.${ext}`), (0, serialize_1.serialize)(doc, format));
             fileCount += 1;
         }
@@ -1027,6 +1257,16 @@ async function planConfigImport(http, opts) {
         throw new errors_1.CliError(`Config directory not found: ${dir}. Run 'atlas config export' first.`);
     }
     const present = new Set((0, node_fs_1.readdirSync)(dir));
+    const files = registry().flatMap((spec) => present.has(`${spec.type}.${ext}`) ? [{ spec, doc: (0, serialize_1.deserialize)((0, node_fs_1.readFileSync)((0, node_path_1.join)(dir, `${spec.type}.${ext}`), 'utf8'), format) }] : []);
+    const unknown = files.flatMap(({ spec, doc }) => unknownFileKeys(spec, doc));
+    if (unknown.length)
+        throw new errors_1.CliError(`Unknown key(s) in the config:\n  ${unknown.join('\n  ')}`);
+    const invalid = files.flatMap(({ spec, doc }) => invalidFileValues(spec, interpolate(doc, env)));
+    if (invalid.length)
+        throw new errors_1.CliError(`Invalid value(s) in the config:\n  ${invalid.join('\n  ')}`);
+    const rotate = opts.rotateSecrets === true;
+    const warnings = [];
+    const unverifiableSecrets = [];
     const changes = [];
     let unchanged = 0;
     const skippedDeletes = [];
@@ -1048,12 +1288,21 @@ async function planConfigImport(http, opts) {
                 unchanged += 1;
                 continue;
             }
-            const live = liveRaw === null ? null : comparable(norm(liveRaw), desiredN, prune);
-            if (live !== null && (0, serialize_1.deepEqual)(desiredN, live)) {
+            if (liveRaw === null) {
+                const masked = reconcileSecrets(desiredN, undefined, true).desired;
+                changes.push({ type: spec.type, action: 'create', key: '', after: masked, raw: desiredN, apply: () => spec.apply(http, desired, applyOpts) });
+                continue;
+            }
+            const seen = withoutUnstated(comparable(norm(liveRaw), desiredN, prune), desiredN);
+            const r = reconcileSecrets(desiredN, seen, spec.reportsSecrets === true);
+            const forced = rotate ? r.unverifiable : [];
+            if (!rotate)
+                unverifiableSecrets.push(...r.unverifiable.map((path) => ({ type: spec.type, key: '', path })));
+            if (forced.length === 0 && (0, serialize_1.deepEqual)(r.desired, r.live)) {
                 unchanged += 1;
                 continue;
             }
-            changes.push({ type: spec.type, action: live === null ? 'create' : 'update', key: '', ...(live === null ? {} : { before: live }), after: desiredN, apply: () => spec.apply(http, desired, applyOpts) });
+            changes.push({ type: spec.type, action: 'update', key: '', before: r.live, after: r.desired, raw: desiredN, changedSecrets: forced, apply: () => spec.apply(http, desired, applyOpts) });
             continue;
         }
         // Collection: diff desired-by-key against live-by-key.
@@ -1069,19 +1318,40 @@ async function planConfigImport(http, opts) {
         const liveByKey = new Map(live.map((e) => [e.key, e]));
         for (const [key, cfg] of desiredByKey) {
             const existing = liveByKey.get(key);
+            warnings.push(...(spec.warnings?.(cfg, existing?.config) ?? []));
             if (!existing) {
-                changes.push({ type: spec.type, action: 'create', key, after: cfg, apply: () => spec.create(http, cfg) });
+                changes.push({ type: spec.type, action: 'create', key, after: reconcileSecrets(cfg, undefined, true).desired, raw: cfg, apply: () => spec.create(http, cfg) });
+                continue;
             }
-            else if (!(0, serialize_1.deepEqual)(cfg, comparable(existing.config, cfg, prune))) {
-                if (!spec.update) {
-                    throw new errors_1.CliError(`${spec.type} '${key}' changed but is immutable; recreate it instead.`);
+            const seen = withoutUnstated(comparable(existing.config, cfg, prune), cfg, spec.defaulted);
+            const r = reconcileSecrets(cfg, seen, spec.reportsSecrets === true);
+            const unverifiable = [...r.unverifiable];
+            const liveSeen = obj(r.live);
+            for (const k of spec.writeOnly ?? []) {
+                if (obj(r.desired)[k] === undefined)
+                    continue;
+                liveSeen[k] = obj(r.desired)[k];
+                unverifiable.push(k);
+            }
+            let forced = rotate ? unverifiable : [];
+            let unknownToApi = rotate ? [] : unverifiable;
+            if (spec.secretChanged && unverifiable.length) {
+                const changed = await spec.secretChanged(http, existing, cfg);
+                if (changed !== null) {
+                    forced = changed ? unverifiable : [];
+                    unknownToApi = [];
                 }
-                const upd = spec.update;
-                changes.push({ type: spec.type, action: 'update', key, before: comparable(existing.config, cfg, prune), after: cfg, apply: () => upd(http, existing, cfg) });
             }
-            else {
+            unverifiableSecrets.push(...unknownToApi.map((path) => ({ type: spec.type, key, path })));
+            if (forced.length === 0 && (0, serialize_1.deepEqual)(r.desired, liveSeen)) {
                 unchanged += 1;
+                continue;
+            }
+            if (!spec.update) {
+                throw new errors_1.CliError(`${spec.type} '${key}' changed but is immutable; recreate it instead.`);
             }
+            const upd = spec.update;
+            changes.push({ type: spec.type, action: 'update', key, before: liveSeen, after: r.desired, raw: cfg, changedSecrets: forced, apply: () => upd(http, existing, cfg) });
         }
         for (const entry of live) {
             if (desiredByKey.has(entry.key))
@@ -1100,7 +1370,7 @@ async function planConfigImport(http, opts) {
             }
         }
     }
-    return { changes, unchanged, skippedDeletes, managed };
+    return { changes, unchanged, skippedDeletes, managed, warnings, unverifiableSecrets };
 }
 /** True for a non-empty object whose every leaf is `null` (a file that only clears fields). */
 function onlyNulls(x) {
@@ -1120,7 +1390,6 @@ function onlyNulls(x) {
 function comparable(live, desired, prune) {
     if (prune)
         return live;
-    const isObj = (x) => x !== null && typeof x === 'object' && !Array.isArray(x);
     if (!isObj(live) || !isObj(desired))
         return live;
     const out = {};
@@ -1180,6 +1449,7 @@ async function promoteConfig(ctx, values) {
         const plan = await planConfigImport(target.http, { dir, format, env: ctx.env, prune });
         ctx.io.out(`Promoting ${from} -> ${to}`);
         printPlan(ctx, plan.changes, plan.unchanged, plan.skippedDeletes, { dryRun, prune });
+        printPlanNotes(ctx, plan);
         if (dryRun)
             return 0;
         for (const change of plan.changes)
@@ -1197,8 +1467,9 @@ async function importConfig(ctx, values) {
     const format = resolveFormat(values);
     const dryRun = values['dry-run'] === true;
     const prune = values.prune === true;
-    const plan = await planConfigImport(http, { dir, format, env: readSecretsEnv(ctx, values), prune, forceHook: values['force-hook'] === true });
+    const plan = await planConfigImport(http, { dir, format, env: readSecretsEnv(ctx, values), prune, forceHook: values['force-hook'] === true, rotateSecrets: values['rotate-secret'] === true });
     printPlan(ctx, plan.changes, plan.unchanged, plan.skippedDeletes, { dryRun, prune });
+    printPlanNotes(ctx, plan);
     if (dryRun)
         return 0;
     for (const change of plan.changes)
@@ -1211,7 +1482,6 @@ async function importConfig(ctx, values) {
 }
 /** Leaf-level differences between two documents, as dotted paths (arrays compare whole). */
 function diffFields(before, after, path = '') {
-    const isObj = (x) => x !== null && typeof x === 'object' && !Array.isArray(x);
     if (isObj(before) && isObj(after)) {
         const keys = [...new Set([...Object.keys(before), ...Object.keys(after)])].sort();
         return keys.flatMap((k) => diffFields(before[k], after[k], path ? `${path}.${k}` : k));
@@ -1223,6 +1493,35 @@ function diffFields(before, after, path = '') {
     return [{ path: path || '(document)', ...(before === undefined ? {} : { before }), ...(after === undefined ? {} : { after }) }];
 }
 const show = (v) => (v === undefined ? '(unset)' : typeof v === 'string' ? JSON.stringify(v) : JSON.stringify(v));
+/**
+ * The only form a change's fields are printed or serialised in. A secret-named
+ * string is `<redacted>` with a changed flag, whatever the resource; everything else
+ * goes through the deep redactor.
+ */
+function printedFields(c) {
+    const reveal = (0, redact_1.revealingSecrets)();
+    const diffs = diffFields(c.before, reveal ? (c.raw ?? c.after) : c.after);
+    const rows = diffs.map((f) => {
+        const leaf = f.path.split('.').pop();
+        const textual = [f.before, f.after].every((v) => v === undefined || v === null || typeof v === 'string');
+        if (!reveal && (0, redact_1.isSecretKey)(leaf) && textual && !(0, redact_1.isPlaceholder)(f.after))
+            return { path: f.path, redacted: true, changed: true };
+        return { path: f.path, ...(f.before === undefined ? {} : { before: (0, redact_1.redactDeep)(f.before, leaf) }), ...(f.after === undefined ? {} : { after: (0, redact_1.redactDeep)(f.after, leaf) }) };
+    });
+    for (const path of c.changedSecrets ?? [])
+        if (!rows.some((r) => r.path === path))
+            rows.push({ path, redacted: true, changed: true });
+    return rows;
+}
+const printedLine = (f) => (f.redacted ? `${f.path}: ${redact_1.REDACTED} (changed)` : `${f.path}: ${show(f.before)} -> ${show(f.after)}`);
+/** The plan's advice: warnings, and the secrets Atlas cannot compare. */
+function printPlanNotes(ctx, plan) {
+    for (const w of plan.warnings)
+        ctx.io.out(`warning: ${w}`);
+    for (const u of plan.unverifiableSecrets) {
+        ctx.io.out(`note: ${u.type}${u.key ? ` ${u.key}` : ''} ${u.path}: Atlas does not return this value, so a change to it cannot be detected. Send it again with --rotate-secret.`);
+    }
+}
 /**
  * `atlas config plan`: a Terraform-style, read-only diff of a config directory
  * (`atlas config export` output, committed to git) against the live instance.
@@ -1234,14 +1533,14 @@ async function planConfig(ctx, values, source) {
     const { dir, format, env } = source;
     const where = source.label ?? dir;
     const prune = values.prune === true;
-    const plan = await planConfigImport(http, { dir, format, env, prune });
+    const plan = await planConfigImport(http, { dir, format, env, prune, rotateSecrets: values['rotate-secret'] === true });
     const deletes = prune ? [] : plan.skippedDeletes;
     const all = plan.changes;
     const rows = all.map((c) => ({
         type: c.type,
         key: c.key || null,
         action: c.action,
-        fields: c.action === 'update' ? diffFields(c.before, c.after) : [],
+        fields: c.action === 'update' ? printedFields(c) : [],
     }));
     const pending = rows.length;
     if (values.json === true) {
@@ -1251,6 +1550,8 @@ async function planConfig(ctx, values, source) {
             unchanged: plan.unchanged,
             unmanaged_live: deletes.map((d) => ({ type: d.type, key: d.key || null })),
             managed_by_platform: plan.managed.map((m) => ({ type: m.type, key: m.key, managed_by: m.managedBy })),
+            warnings: plan.warnings,
+            unverifiable_secrets: plan.unverifiableSecrets.map((u) => ({ type: u.type, key: u.key || null, path: u.path })),
             has_changes: pending > 0,
         }, null, 2));
     }
@@ -1262,8 +1563,8 @@ async function planConfig(ctx, values, source) {
             ctx.io.out('');
             ctx.io.out(`${sign[c.action]} ${label} (${c.action})`);
             if (c.action === 'update') {
-                for (const f of diffFields(c.before, c.after))
-                    ctx.io.out(`    ${f.path}: ${show(f.before)} -> ${show(f.after)}`);
+                for (const f of printedFields(c))
+                    ctx.io.out(`    ${printedLine(f)}`);
             }
         }
         if (deletes.length) {
@@ -1278,6 +1579,9 @@ async function planConfig(ctx, values, source) {
             for (const m of plan.managed)
                 ctx.io.out(`    ${m.type} ${m.key} (${m.managedBy})`);
         }
+        if (plan.warnings.length || plan.unverifiableSecrets.length)
+            ctx.io.out('');
+        printPlanNotes(ctx, plan);
         if (pending === 0)
             ctx.io.out(`No drift: the instance matches ${where}.`);
     }
@@ -1420,10 +1724,21 @@ async function applyCommand(ctx, args) {
         return planCommand(ctx, args);
     const source = await resolveSource(ctx, args);
     try {
-        const kept = keepingSecrets(requireHttp(ctx, values), (0, args_1.str)(values, 'out') || (0, secrets_1.productDir)(ctx.env, 'atlas'));
+        const onUnknownFields = (n) => ctx.io.err(`atlas: warning: ${n.method} ${n.path} ignored field(s) ${n.fields}${n.suggestions ? ` (did you mean: ${n.suggestions})` : ''}. This instance is lenient; set auth_config.strictRequestBodies to refuse them.`);
+        const kept = keepingSecrets(requireHttp(ctx, values, onUnknownFields), (0, args_1.str)(values, 'out') || (0, secrets_1.productDir)(ctx.env, 'atlas'));
         const prune = values.prune === true;
-        const plan = await planConfigImport(kept.http, { dir: source.dir, format: source.format, env: source.env, prune, forceHook: values['force-hook'] === true });
+        const plan = await planConfigImport(kept.http, { dir: source.dir, format: source.format, env: source.env, prune, forceHook: values['force-hook'] === true, rotateSecrets: values['rotate-secret'] === true });
         printPlan(ctx, plan.changes, plan.unchanged, plan.skippedDeletes, { dryRun: false, prune });
+        for (const c of plan.changes) {
+            if (c.action !== 'update')
+                continue;
+            const fields = printedFields(c);
+            if (fields.length)
+                ctx.io.out(`  ~ ${c.key ? `${c.type} ${c.key}` : c.type}:`);
+            for (const f of fields)
+                ctx.io.out(`      ${printedLine(f)}`);
+        }
+        printPlanNotes(ctx, plan);
         if (plan.changes.length === 0) {
             ctx.io.out('No changes to apply.');
             return 0;
@@ -1471,7 +1786,8 @@ function keepingSecrets(http, dir) {
             if (path === '/v1/oauth_clients' && typeof r.client_secret === 'string') {
                 entries = { ATLAS_CLIENT_ID: String(r.client_id ?? ''), ATLAS_CLIENT_SECRET: r.client_secret };
             }
-            else if (path === '/v1/webhook_endpoints' && typeof r.secret === 'string') {
+            else if (path === '/v1/webhook_endpoints' && typeof r.secret === 'string' && !body?.secret) {
+                // A secret the file chose is already the caller's; only a minted one needs keeping.
                 entries = { ATLAS_WEBHOOK_SECRET: r.secret };
             }
             if (entries) {
@@ -1515,16 +1831,22 @@ function asArray(value) {
  * on disk. An unset variable is left verbatim so the plan surfaces it rather
  * than silently blanking a credential.
  */
-function interpolate(value, env) {
+function interpolate(value, env, key) {
     if (typeof value === 'string') {
-        return value.replace(/\$\{([A-Z0-9_]+)\}/g, (match, name) => env[name] ?? match);
+        return value.replace(/\$\{([A-Z0-9_]+)\}/g, (match, name) => {
+            const resolved = env[name];
+            if (resolved === undefined)
+                return match;
+            (0, redact_1.rememberResolved)(key, resolved);
+            return resolved;
+        });
     }
     if (Array.isArray(value))
-        return value.map((v) => interpolate(v, env));
+        return value.map((v) => interpolate(v, env, key));
     if (value !== null && typeof value === 'object') {
         const out = {};
         for (const [k, v] of Object.entries(value))
-            out[k] = interpolate(v, env);
+            out[k] = interpolate(v, env, k);
         return out;
     }
     return value;