@goodandready/dsh-key-rotation 0.8.20 → 0.8.21

package/lib/client.js

@@ -139,6 +139,11 @@ window.__ModuleLoader__.load({
       emptyDesc: 'Add a provider and at least one API key name to start rotating.',
       errorTitle: 'Could not load settings',
       retry: 'Retry',
+      chooseProvider: 'Choose a provider',
+      readOnly: 'Settings are read-only.',
+      settingsChanged: 'The settings service changed. Discard this draft and reload before saving.',
+      saveRefused: 'The host did not accept this save. Your draft is kept; discard it to load the latest settings.',
+      saveUnconfirmed: 'The save result could not be confirmed. Your draft is kept; reload before trying again.',
       unavailableTitle: 'Settings bridge unavailable',
       unavailableDesc: 'The host did not expose the dsh-key-rotation settings namespace. Reopen Settings or check the plugin is enabled.',
       modalClose: 'Close dialog',
@@ -278,6 +283,11 @@ window.__ModuleLoader__.load({
       emptyDesc: '添加提供商及至少一个 API 密钥名称以开始轮换。',
       errorTitle: '无法加载设置',
       retry: '重试',
+      chooseProvider: '请选择提供商',
+      readOnly: '当前设置为只读。',
+      settingsChanged: '设置服务已变更。请放弃当前草稿并重新加载后再保存。',
+      saveRefused: '宿主未接受此次保存。草稿已保留；放弃草稿可加载最新设置。',
+      saveUnconfirmed: '无法确认保存结果。草稿已保留，请重新加载后再试。',
       unavailableTitle: '设置桥接不可用',
       unavailableDesc: '宿主未暴露 dsh-key-rotation 设置命名空间。请重新打开设置或检查插件是否已启用。',
       modalClose: '关闭对话框',
@@ -644,13 +654,17 @@ window.__ModuleLoader__.load({
       );
     }
 
-    // Provider registration is not part of configForms's value. Fetch it
+    // Provider registration is not part of settingsScope's value. Fetch it
     // independently, and never turn an unavailable catalog into proof of absence.
-    function useProviderCatalog() {
+    function useProviderCatalog(enabled = true) {
       const [catalog, setCatalog] = React.useState({ status: 'loading', providers: [] });
       const requestRef = React.useRef(null);
       const reload = React.useCallback(() => {
         requestRef.current?.abort();
+        if (!enabled) {
+          setCatalog({ status: 'unavailable', providers: [] });
+          return Promise.resolve();
+        }
         const controller = new AbortController();
         requestRef.current = controller;
         setCatalog((s) => ({ ...s, status: 'loading' }));
@@ -672,7 +686,7 @@ window.__ModuleLoader__.load({
               setCatalog((s) => ({ ...s, status: 'error' }));
             }
           });
-      }, []);
+      }, [enabled]);
       React.useEffect(() => {
         reload();
         // A provider may have been installed/enabled while this page was open.
@@ -685,55 +699,182 @@ window.__ModuleLoader__.load({
       return { ...catalog, reload };
     }
 
+    // Services from different core generations are optional at the plugin boundary.
+    // One binding belongs to one Cordis activation, not to each React page mount.
+    function createSettingsSource(ctx) {
+      const listeners = new Set();
+      const candidates = new Map();
+      let value = { kind: null, service: null };
+      const publish = () => {
+        const kind = candidates.has('configForm') ? 'configForm'
+          : candidates.has('settingsScope') ? 'settingsScope' : null;
+        const service = candidates.get(kind) ?? null;
+        if (value.kind === kind && value.service === service) return;
+        value = { kind, service };
+        for (const listener of [...listeners]) listener();
+      };
+      if (typeof ctx?.inject === 'function') {
+        const watch = (name, kind, resolve) => {
+          ctx.inject([name], (owner) => {
+            let service;
+            try { service = resolve(owner.get(name)); } catch (_) { return; }
+            if (!service || typeof service.getSnapshot !== 'function'
+              || typeof service.subscribe !== 'function') return;
+            candidates.set(kind, service);
+            publish();
+            owner.effect(() => () => {
+              if (candidates.get(kind) === service) candidates.delete(kind);
+              publish();
+            });
+          });
+        };
+        watch('configForms', 'configForm', (forms) => forms?.get?.(NS));
+        watch('settingsScope', 'settingsScope', (binder) => binder?.bind?.({ namespace: NS }));
+        if (typeof ctx.effect === 'function') {
+          ctx.effect(() => () => { candidates.clear(); publish(); listeners.clear(); });
+        }
+      }
+      return {
+        getSnapshot: () => value,
+        subscribe: (listener) => { listeners.add(listener); return () => listeners.delete(listener); },
+      };
+    }
+
+    function sameJson(a, b) {
+      if (Object.is(a, b)) return true;
+      if (!a || !b || typeof a !== 'object' || typeof b !== 'object'
+        || Array.isArray(a) !== Array.isArray(b)) return false;
+      const keys = Object.keys(a);
+      return keys.length === Object.keys(b).length
+        && keys.every((key) => Object.prototype.hasOwnProperty.call(b, key) && sameJson(a[key], b[key]));
+    }
+
+    // A redacted, resolved snapshot is not a complete user section. Submit only
+    // changed top-level fields; arrays are intentionally edited atomically.
+    function changedSettingsOps(base, next) {
+      const keys = new Set([...Object.keys(base), ...Object.keys(next)]);
+      return [...keys].filter((key) => !sameJson(base[key], next[key])).map((key) =>
+        next[key] === undefined ? { op: 'unset', path: [key] }
+          : { op: 'set', path: [key], value: next[key] });
+    }
+
+    function requireJson(value, depth = 0) {
+      if (depth > 40) throw new Error('Configuration is nested too deeply');
+      if (value === null || typeof value === 'string' || typeof value === 'boolean') return;
+      if (typeof value === 'number' && Number.isFinite(value)) return;
+      if (Array.isArray(value)) { value.forEach(child => requireJson(child, depth + 1)); return; }
+      if (value && typeof value === 'object') {
+        for (const [key, child] of Object.entries(value)) {
+          if (['__proto__', 'constructor', 'prototype'].includes(key)) throw new Error('Unsafe configuration field');
+          if (child !== undefined) requireJson(child, depth + 1);
+        }
+        return;
+      }
+      throw new Error('Configuration must contain finite, JSON-compatible values');
+    }
+
+
+    function reorderKeys(entry, order) {
+      const next = { ...entry, keys: order.map(index => entry.keys[index]) };
+      for (const [field, fallback] of [['weights', 1], ['expiresAt', 0]]) {
+        if (Array.isArray(entry[field]) && entry[field].length) next[field] = order.map(index => entry[field][index] ?? fallback);
+      }
+      return next;
+    }
+
+    function validatePoolDraft(providers) {
+      if (!Array.isArray(providers)) throw new Error('Provider pools must be an array');
+      const names = new Set();
+      for (const entry of providers) {
+        if (!entry || typeof entry.provider !== 'string' || !entry.provider.trim()
+          || names.has(entry.provider) || !Array.isArray(entry.keys)
+          || entry.keys.some(key => typeof key !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
+          || new Set(entry.keys).size !== entry.keys.length) {
+          throw new Error('Choose a unique provider and valid, unique credential reference names');
+        }
+        names.add(entry.provider);
+      }
+    }
+
+    async function settingsResponse(response) {
+      let data;
+      try { data = await response.json(); }
+      catch (_) { throw new Error('Settings response is not valid JSON (HTTP ' + response.status + ')'); }
+      if (!response.ok || data?.error) {
+        throw new Error(data?.error?.message || 'Settings request failed (HTTP ' + response.status + ')');
+      }
+      if (!data || typeof data !== 'object' || Array.isArray(data)) throw new Error('Invalid settings response');
+      return data;
+    }
+
     function KeyRotationSection(props) {
       const t = resolveT(props);
-      const configForms = React.useMemo(() => {
-        try {
-          if (props.ctx && props.ctx.configForms) {
-            return props.ctx.configForms.get(NS);
-          }
-        } catch (_) {
-          return null;
-        }
-        return null;
-      }, [props.ctx]);
+      const settingsBinding = React.useSyncExternalStore(
+        props.settingsSource.subscribe, props.settingsSource.getSnapshot
+      );
+      const settingsScope = settingsBinding.service;
+      const settingsContract = settingsBinding.kind;
+      const bindingRef = React.useRef(settingsBinding);
+      bindingRef.current = settingsBinding;
       // #273: getSnapshot must be referentially stable or React 18 unmounts the tree
       const scopeCacheRef = React.useRef({ has: false, value: null });
       const getScopeSnapshot = React.useCallback(() => {
-        if (!configForms || typeof configForms.getSnapshot !== 'function') return null;
+        if (!settingsScope || typeof settingsScope.getSnapshot !== 'function') return null;
         let next = null;
         try {
-          next = configForms.getSnapshot();
+          next = settingsScope.getSnapshot();
         } catch (_) {
           return null;
         }
         const prev = scopeCacheRef.current;
+        if (prev.service !== settingsScope) prev.has = false;
         if (prev.has && Object.is(prev.value, next)) return prev.value;
         // shallow-compare common snapshot shape to avoid identity thrash
         if (prev.has && prev.value && next
-          && prev.value.status === next.status
-          && prev.value.revision === next.revision
-          && prev.value.value === next.value) {
+          && Object.keys(prev.value).length === Object.keys(next).length
+          && Object.keys(next).every((key) => Object.is(prev.value[key], next[key]))) {
           return prev.value;
         }
-        scopeCacheRef.current = { has: true, value: next };
+        scopeCacheRef.current = { has: true, value: next, service: settingsScope };
         return next;
-      }, [configForms]);
+      }, [settingsScope]);
       const scopeSnapshot = React.useSyncExternalStore(
-        React.useMemo(() => (cb) => (configForms && typeof configForms.subscribe === 'function' ? configForms.subscribe(cb) : () => {}), [configForms]),
+        React.useMemo(() => (cb) => (settingsScope && typeof settingsScope.subscribe === 'function' ? settingsScope.subscribe(cb) : () => {}), [settingsScope]),
         getScopeSnapshot
       );
-      const [state, setState] = React.useState({ status: 'loading', value: null, revision: 0, error: '', providers: [] });
-      const catalog = useProviderCatalog();
+      const [state, setState] = React.useState({ status: 'loading', value: null, revision: undefined, writable: false, error: '', providers: [] });
+      const stateRef = React.useRef(state);
+      const updateState = React.useCallback((update) => {
+        const next = typeof update === 'function' ? update(stateRef.current) : update;
+        stateRef.current = next;
+        setState(next);
+      }, []);
+      const catalog = useProviderCatalog(Boolean(settingsScope) && scopeSnapshot?.mode !== 'memory');
       const latestScopeSnapshot = React.useRef(scopeSnapshot);
       latestScopeSnapshot.current = scopeSnapshot;
-      // #290: surface configForms availability as card state
-      React.useEffect(() => {
-        if (!configForms) {
-          setState((s) => (s.status === 'unavailable' ? s : { ...s, status: 'unavailable' }));
-        }
-      }, [configForms]);
       const [draft, setDraft] = React.useState(null);
+      const draftRef = React.useRef(null);
+      const draftBaseRef = React.useRef(null);
+      const saveInFlightRef = React.useRef(false);
+      const [saving, setSaving] = React.useState(false);
+      const [importing, setImporting] = React.useState(false);
+      const importRef = React.useRef(false);
+      const importCancelRef = React.useRef(null);
+      const editEpochRef = React.useRef(0);
+      const mountedRef = React.useRef(true);
+      const readRef = React.useRef({ generation: 0, controller: null });
+      const saveControllerRef = React.useRef(null);
+      React.useEffect(() => {
+        mountedRef.current = true;
+        return () => {
+          mountedRef.current = false;
+          editEpochRef.current++;
+          readRef.current.generation++;
+          readRef.current.controller?.abort();
+          saveControllerRef.current?.abort();
+          importCancelRef.current?.();
+        };
+      }, []);
       // ── all hooks live ABOVE any early return (React error 310 otherwise) ──
       const [search, setSearch] = React.useState('');
       const [statusFilter, setStatusFilter] = React.useState('all');
@@ -743,6 +884,7 @@ window.__ModuleLoader__.load({
       const [bulkCooldown, setBulkCooldown] = React.useState('');
       const [undo, setUndo] = React.useState(null);
       const undoTimer = React.useRef(null);
+      React.useEffect(() => () => { if (undoTimer.current) clearTimeout(undoTimer.current); }, []);
       // #289 a11y: confirm dialog focus trap / Escape / restore (hooks above returns)
       const modalReturnFocusRef = React.useRef(null);
       const modalCardRef = React.useRef(null);
@@ -790,13 +932,36 @@ window.__ModuleLoader__.load({
       const [testingProgress, setTestingProgress] = React.useState({});
       const [secretDraft, setSecretDraft] = React.useState({});
       const [secretError, setSecretError] = React.useState('');
+      const secretWritesRef = React.useRef(new Set());
       const stashUndo = (u) => { setUndo(u); if (undoTimer.current) clearTimeout(undoTimer.current); undoTimer.current = setTimeout(() => setUndo(null), 5000); };
-      const doUndo = () => { if (!undo) return; const u = undo; setUndo(null); setField((cur) => {
-        const providers = [...(cur.providers ?? [])];
-        if (u.type === 'provider') providers.splice(Math.min(u.index, providers.length), 0, u.entry);
-        else if (providers[u.index]) { const keys=[...providers[u.index].keys]; keys.splice(Math.min(u.kIndex, keys.length), 0, u.key); providers[u.index] = { ...providers[u.index], keys }; }
-        return { ...cur, providers };
-      }); };
+      const doUndo = () => {
+        if (!undo || saveInFlightRef.current || importRef.current || !stateRef.current.writable) return;
+        const u = undo;
+        setField((cur) => {
+          const providers = [...(cur.providers ?? [])];
+          if (u.type === 'provider') {
+            if (providers.some(p => p.provider === u.entry.provider)) return cur;
+            providers.splice(Math.min(u.index, providers.length), 0, u.entry);
+          } else {
+            // Other providers may have been removed or re-ordered since Undo
+            // was staged. Identity, not the old displayed index, selects it.
+            const index = providers.findIndex(p => p.provider === u.provider);
+            if (index < 0 || providers[index].keys.includes(u.key)) return cur;
+            const entry = { ...providers[index] };
+            const at = Math.min(u.kIndex, entry.keys.length);
+            entry.keys = [...entry.keys]; entry.keys.splice(at, 0, u.key);
+            for (const [field, fallback] of [['weights', 1], ['expiresAt', 0]]) {
+              if (u[field] !== undefined || entry[field]?.length) {
+                const values = Array.from({ length: entry.keys.length - 1 }, (_, i) => entry[field]?.[i] ?? fallback);
+                values.splice(at, 0, u[field] ?? fallback); entry[field] = values;
+              }
+            }
+            providers[index] = entry;
+          }
+          return { ...cur, providers };
+        });
+        setUndo(null);
+      };
       // Both buttons must run the same live probe, never a presence-only check.
       // Serialize probes: a large pool must not burst /models requests. The ref
       // also guards repeated clicks before React has rendered disabled buttons.
@@ -852,41 +1017,70 @@ window.__ModuleLoader__.load({
         return runKeyTests(refs, providerId);
       };
 
-      const load = React.useCallback(() => {
-        const scopeIsReady = () => latestScopeSnapshot.current?.status === 'ready'
-          && latestScopeSnapshot.current.value;
-        setState((s) => ({ ...s, status: 'loading', error: '' }));
-        fetch(CONFIG_PATH, { headers: { accept: 'application/json' } })
-          .then((r) => r.json())
-          .then((data) => {
-            // The scope may have become ready while this fallback was in flight.
-            // A bridge snapshot must not replace that newer value or its revision.
-            if (scopeIsReady()) return;
-            setState({
-              status: 'ready',
-              value: data.value ?? null,
-              revision: data.revision ?? 0,
-              providers: Array.isArray(data.providers) ? data.providers : [],
-              error: data.error ? data.error.message : '',
-            });
-          })
-          .catch((e) => {
-            if (!scopeIsReady()) setState((s) => ({ ...s, status: 'error', error: String(e) }));
-          });
-      }, []);
+      const acceptSnapshot = React.useCallback((snapshot, source) => {
+        if (!mountedRef.current || bindingRef.current.service !== source) return;
+        if (!snapshot || snapshot.status === 'unavailable' || snapshot.mode === 'memory'
+          || snapshot.available === false) {
+          updateState((s) => ({ ...s, status: 'unavailable', writable: false, source }));
+          return;
+        }
+        if (!snapshot.value || typeof snapshot.value !== 'object' || Array.isArray(snapshot.value)
+          || !Number.isSafeInteger(snapshot.revision) || snapshot.revision < 0) {
+          throw new Error('Invalid settings snapshot or revision');
+        }
+        updateState((s) => {
+          if (s.source === source && Number.isSafeInteger(s.revision) && s.revision > snapshot.revision) return s;
+          return { ...s, status: 'ready', value: snapshot.value, revision: snapshot.revision,
+            writable: snapshot.writable === true, source };
+        });
+      }, [updateState]);
+
+      const load = React.useCallback(async (force = false) => {
+        const source = bindingRef.current.service;
+        const snapshot = latestScopeSnapshot.current;
+        const generation = ++readRef.current.generation;
+        readRef.current.controller?.abort();
+        if (!source || snapshot?.status === 'unavailable' || snapshot?.mode === 'memory') {
+          acceptSnapshot(null, source);
+          return;
+        }
+        updateState((s) => ({ ...s, error: '' }));
+        if (!force && snapshot?.status === 'ready') {
+          try { acceptSnapshot(snapshot, source); }
+          catch (error) { updateState((s) => ({ ...s, status: s.value ? 'ready' : 'error', error: error.message })); }
+          return;
+        }
+        const controller = new AbortController();
+        readRef.current.controller = controller;
+        const timeout = setTimeout(() => controller.abort(), 15000);
+        updateState((s) => ({ ...s, status: s.value ? s.status : 'loading' }));
+        try {
+          const data = await settingsResponse(await fetch(CONFIG_PATH, {
+            headers: { accept: 'application/json' }, signal: controller.signal,
+          }));
+          if (controller.signal.aborted || generation !== readRef.current.generation || !mountedRef.current) return;
+          acceptSnapshot(data, source);
+        } catch (error) {
+          if (generation !== readRef.current.generation || !mountedRef.current) return;
+          updateState((s) => ({ ...s, status: s.value ? 'ready' : 'error', error: String(error?.message ?? error) }));
+        } finally {
+          clearTimeout(timeout);
+          if (readRef.current.controller === controller) readRef.current.controller = null;
+        }
+      }, [acceptSnapshot, updateState]);
 
       React.useEffect(() => {
-        if (scopeSnapshot && scopeSnapshot.status === 'ready' && scopeSnapshot.value) {
-          setState((s) => ({
-            ...s,
-            status: 'ready',
-            value: scopeSnapshot.value,
-            revision: scopeSnapshot.revision ?? s.revision,
-          }));
+        readRef.current.generation++;
+        readRef.current.controller?.abort();
+        if (!settingsScope || scopeSnapshot?.status === 'unavailable' || scopeSnapshot?.mode === 'memory') {
+          acceptSnapshot(null, settingsScope);
+        } else if (scopeSnapshot?.status === 'ready') {
+          try { acceptSnapshot(scopeSnapshot, settingsScope); }
+          catch (error) { updateState((s) => ({ ...s, status: s.value ? 'ready' : 'error', error: error.message })); }
         } else {
-          load();
+          void load();
         }
-      }, [load, scopeSnapshot]);
+      }, [settingsScope, scopeSnapshot, load, acceptSnapshot, updateState]);
 
       const val = draft ?? state.value;
       const status = useRotationStatus();
@@ -960,7 +1154,9 @@ window.__ModuleLoader__.load({
       };
       const saveSecret = async (ref, rowKey) => {
         const value = secretDraft[rowKey];
-        if (!value) return;
+        if (!value || secretWritesRef.current.has(ref)) return;
+        secretWritesRef.current.add(ref);
+        try {
         setSecretError('');
         // Pre-save validation (issue #118)
         setValidating(ref);
@@ -973,7 +1169,7 @@ window.__ModuleLoader__.load({
           setSecretError(t('keyWriteFailed').replace('{msg}', msg));
           return;
         }
-        fetch('/dsh-key-rotation/key', {
+        await fetch('/dsh-key-rotation/key', {
           method: 'PUT',
           headers: { 'content-type': 'application/json' },
           body: JSON.stringify({ ref, value }),
@@ -988,11 +1184,12 @@ window.__ModuleLoader__.load({
             }
             setSecretDraft((cur) => {
               const next = { ...cur };
-              delete next[rowKey];
+              if (next[rowKey] === value) delete next[rowKey];
               return next;
             });
           })
           .catch((e) => setSecretError(t('keyWriteFailed').replace('{msg}', String(e?.message ?? e))));
+        } finally { secretWritesRef.current.delete(ref); }
       };
       // #290: explicit card states — loading / error / unavailable / empty / ready
       if (state.status === 'loading' || (!val && state.status !== 'error' && state.status !== 'unavailable')) {
@@ -1008,13 +1205,13 @@ window.__ModuleLoader__.load({
           })
         );
       }
-      if (state.status === 'error') {
+      if (state.status === 'error' && !val) {
         return React.createElement('div', { className: 'krot-state-block', role: 'alert', style: { padding: '12px 0', display: 'flex', flexDirection: 'column', gap: '10px', alignItems: 'flex-start' } },
           React.createElement('p', { className: 'krot-err', style: { margin: 0 } }, t('errorTitle') + (state.error ? (': ' + state.error) : '')),
           React.createElement('button', { type: 'button', className: 'krot-btn', onClick: () => load() }, t('retry'))
         );
       }
-      if (state.status === 'unavailable' || !configForms) {
+      if (state.status === 'unavailable' || !settingsScope) {
         return React.createElement('div', { className: 'krot-state-block', role: 'status', style: { padding: '12px 0', display: 'flex', flexDirection: 'column', gap: '6px' } },
           React.createElement('p', { style: { fontSize: 14, fontWeight: 600, color: 'var(--dsw-alias-label-primary)', margin: 0 } }, t('unavailableTitle')),
           React.createElement('p', { className: 'krot-hint', style: { margin: 0 } }, t('unavailableDesc'))
@@ -1024,8 +1221,73 @@ window.__ModuleLoader__.load({
       const providers = catalog.providers;
       const providerById = new Map(providers.map((p) => [p.id, p.name]));
 
-      const setField = (fn) => setDraft(fn(val));
-      const providerList = Array.isArray(val.providers) ? val.providers.filter((p) => Array.isArray(p.keys) && p.keys.length > 0).filter((p) => !search || p.provider.toLowerCase().includes(search.toLowerCase())) : [];
+      const setField = (fn, fromImport = false) => {
+        if (!mountedRef.current || saveInFlightRef.current || (importRef.current && !fromImport)
+          || !stateRef.current.writable) return;
+        const current = draftRef.current ?? stateRef.current.value;
+        if (!current) return;
+        const next = fn(current);
+        if (sameJson(current, next)) return;
+        if (!draftBaseRef.current) {
+          draftBaseRef.current = { value: structuredClone(current), revision: stateRef.current.revision,
+            source: bindingRef.current.service };
+        }
+        const unchanged = sameJson(draftBaseRef.current.value, next);
+        if (unchanged) draftBaseRef.current = null;
+        draftRef.current = unchanged ? null : next;
+        setDraft(draftRef.current);
+        updateState((s) => ({ ...s, error: '' }));
+      };
+      const clearDraft = () => {
+        editEpochRef.current++;
+        draftBaseRef.current = null;
+        draftRef.current = null;
+        setDraft(null);
+        setUndo(null);
+        setSelected(new Set());
+        if (undoTimer.current) clearTimeout(undoTimer.current);
+      };
+      const readImport = (file, stage) => {
+        if (!file || saveInFlightRef.current || importRef.current || !stateRef.current.writable) return;
+        if (file.size > 1024 * 1024) { setSecretError('Import file exceeds 1 MiB'); return; }
+        const epoch = editEpochRef.current;
+        const source = bindingRef.current.service;
+        importRef.current = true;
+        setImporting(true);
+        const reader = new FileReader();
+        let finished = false;
+        const finish = () => {
+          if (finished) return;
+          finished = true;
+          clearTimeout(timeout);
+          importCancelRef.current = null;
+          importRef.current = false;
+          if (mountedRef.current) setImporting(false);
+        };
+        const timeout = setTimeout(() => {
+          if (mountedRef.current) setSecretError('Import file read timed out');
+          finish(); reader.abort?.();
+        }, 15000);
+        importCancelRef.current = () => { finish(); reader.abort?.(); };
+        reader.onload = () => {
+          if (finished) return;
+          try {
+            if (!mountedRef.current || epoch !== editEpochRef.current || source !== bindingRef.current.service) return;
+            const value = JSON.parse(String(reader.result));
+            requireJson(value);
+            stage(value);
+          } catch (error) {
+            if (mountedRef.current) setSecretError(String(error?.message ?? error));
+          } finally { finish(); }
+        };
+        reader.onerror = reader.onabort = () => { if (mountedRef.current) setSecretError('Could not read the import file'); finish(); };
+        try { reader.readAsText(file); }
+        catch (error) { if (mountedRef.current) setSecretError(String(error?.message ?? error)); finish(); }
+      };
+      const providerList = (Array.isArray(val.providers) ? val.providers : [])
+        .map((entry, pIndex) => ({ entry, pIndex }))
+        .filter(({ entry }) => entry && typeof entry.provider === 'string')
+        .filter(({ entry }) => !search || entry.provider.toLowerCase().includes(search.toLowerCase()));
 
       const setProvider = (index, id) => setField((cur) => {
         const next = [...(Array.isArray(cur.providers) ? cur.providers : [])];
@@ -1038,20 +1300,21 @@ window.__ModuleLoader__.load({
         const allRefs = providers.flatMap((prov) => prov?.keys ?? []);
         entry.keys = [...(entry.keys ?? []), nextKeyRef(entry.provider, entry.keys, allRefs)];
         // keep weights aligned with keys (#215): new key gets default weight 1
-        if (Array.isArray(entry.weights) && entry.weights.length > 0) entry.weights = [...entry.weights, 1];
+        for (const [field, fallback] of [['weights', 1], ['expiresAt', 0]]) {
+          if (Array.isArray(entry[field]) && entry[field].length) entry[field] = Array.from({ length: entry.keys.length }, (_, i) => entry[field][i] ?? fallback);
+        }
         providers[pIndex] = entry;
         return { ...cur, providers };
       });
-      const removeKey = (pIndex, kIndex) => { setField((cur) => {
-        const next = [...(Array.isArray(cur.providers) ? cur.providers : [])];
-        stashUndo({ type: 'key', index: pIndex, kIndex, key: next[pIndex]?.keys?.[kIndex] });
-        next[pIndex] = { ...next[pIndex], keys: (next[pIndex].keys ?? []).filter((_, i) => i !== kIndex) };
-        // weights are positional - drop along with the key (#215)
-        if (Array.isArray(next[pIndex].weights) && next[pIndex].weights.length > 0) {
-          next[pIndex] = { ...next[pIndex], weights: next[pIndex].weights.filter((_, i) => i !== kIndex) };
-        }
+      const removeKey = (pIndex, kIndex) => setField((cur) => {
+        const next = [...(cur.providers ?? [])];
+        const entry = next[pIndex];
+        if (!entry || !entry.keys[kIndex]) return cur;
+        stashUndo({ type: 'key', provider: entry.provider, kIndex, key: entry.keys[kIndex],
+          weights: entry.weights?.[kIndex], expiresAt: entry.expiresAt?.[kIndex] });
+        next[pIndex] = reorderKeys(entry, entry.keys.map((_, index) => index).filter(index => index !== kIndex));
         return { ...cur, providers: next };
-      }); };
+      });
       const removeProvider = (pIndex) => setField((cur) => {
         const arr = Array.isArray(cur.providers) ? cur.providers : [];
         stashUndo({ type: 'provider', index: pIndex, entry: arr[pIndex] });
@@ -1060,23 +1323,13 @@ window.__ModuleLoader__.load({
       // Key order is attempt order — move it with buttons, do not retype names.
       const moveKey = (pIndex, kIndex, delta) => setField((cur) => {
         const providers = [...(cur.providers ?? [])];
-        const entry = { ...(providers[pIndex] ?? {}) };
-        const keys = [...(entry.keys ?? [])];
+        const entry = providers[pIndex];
+        if (!entry) return cur;
+        const order = entry.keys.map((_, index) => index);
         const target = kIndex + delta;
-        if (target < 0 || target >= keys.length) return cur;
-        const moved = keys[kIndex];
-        keys[kIndex] = keys[target];
-        keys[target] = moved;
-        entry.keys = keys;
-        // weights are positional - swap along with the keys (#215)
-        const weights = [...(entry.weights ?? [])];
-        if (weights.length > 0) {
-          const w = weights[kIndex];
-          weights[kIndex] = weights[target];
-          weights[target] = w;
-          entry.weights = weights;
-        }
-        providers[pIndex] = entry;
+        if (target < 0 || target >= order.length) return cur;
+        [order[kIndex], order[target]] = [order[target], order[kIndex]];
+        providers[pIndex] = reorderKeys(entry, order);
         return { ...cur, providers };
       });
       // #215: set a single key's round-robin weight (integer >= 1)
@@ -1104,48 +1357,80 @@ window.__ModuleLoader__.load({
 
       const addProvider = () => setField((cur) => ({
         ...cur,
-        providers: [...(Array.isArray(cur.providers) ? cur.providers : []), { provider: '', keys: [''] }],
+        providers: [...(Array.isArray(cur.providers) ? cur.providers : []), { provider: '', keys: [] }],
       }));
 
-      const save = () => {
-        if (!draft) return;
-        setState((s) => ({ ...s, status: 'saving', error: '' }));
-        const saveViaBridge = () => {
-          fetch(CONFIG_PATH, {
-            method: 'PUT',
-            headers: { 'content-type': 'application/json' },
-            body: JSON.stringify({ section: draft, expectedRevision: state.revision }),
-          })
-            .then((r) => r.json())
-            .then((data) => {
-              if (data.error) {
-                setState((s) => ({ ...s, status: 'error', error: data.error.message }));
-                return;
-              }
-              setState((s) => ({ status: 'ready', value: data.value ?? draft, revision: data.revision ?? s.revision, error: '', providers: s.providers }));
-              setDraft(null);
-            })
-            .catch((e) => setState((s) => ({ ...s, status: 'error', error: String(e) })));
-        };
-        if (configForms && typeof configForms.set === 'function') {
-          (async () => {
-            try {
-              for (const [k, v] of Object.entries(draft)) {
-                await configForms.set(k, v);
-              }
-              setState((s) => ({ ...s, status: 'ready', value: draft, error: '' }));
-              setDraft(null);
-            } catch (_) {
-              saveViaBridge();
-            }
-          })();
+      const save = async () => {
+        const savingDraft = draftRef.current;
+        const base = draftBaseRef.current;
+        if (!savingDraft || !base || saveInFlightRef.current || importRef.current) return;
+        if (!stateRef.current.writable || bindingRef.current.service !== base.source) {
+          updateState((s) => ({ ...s, error: t('settingsChanged') }));
+          return;
+        }
+        const expectedRevision = base.revision;
+        if (!Number.isSafeInteger(expectedRevision) || expectedRevision < 0) {
+          updateState((s) => ({ ...s, error: t('settingsChanged') }));
           return;
         }
-        saveViaBridge();
+        let ops;
+        try {
+          ops = changedSettingsOps(base.value, savingDraft); requireJson(ops);
+          if (ops.some(op => op.path[0] === 'providers')) validatePoolDraft(savingDraft.providers);
+        }
+        catch (error) { updateState((s) => ({ ...s, error: error.message })); return; }
+        if (!ops.length) { clearDraft(); return; }
+        saveInFlightRef.current = true;
+        setSaving(true);
+        editEpochRef.current++;
+        readRef.current.generation++;
+        readRef.current.controller?.abort();
+        updateState((s) => ({ ...s, error: '' }));
+        const controller = new AbortController();
+        saveControllerRef.current = controller;
+        let timeout;
+        try {
+          const expired = new Promise((_, reject) => {
+            timeout = setTimeout(() => {
+              controller.abort();
+              reject(new Error(t('saveUnconfirmed')));
+            }, 15000);
+          });
+          const operation = async () => {
+            if (settingsContract === 'configForm' && typeof base.source.mutate === 'function') {
+              const accepted = await base.source.mutate(ops, expectedRevision);
+              if (accepted !== true) throw new Error(t('saveRefused'));
+              const committed = base.source.getSnapshot();
+              // Shared native queues can settle before publishing this write's
+              // snapshot. Confirm an older/absent snapshot through the bridge.
+              if (committed?.status === 'ready' && committed.revision > expectedRevision) return committed;
+              return settingsResponse(await fetch(CONFIG_PATH, { headers: { accept: 'application/json' }, signal: controller.signal }));
+            }
+            // Legacy client mutate resolves void on BOTH success and refusal.
+            // Host-side mutate, reached through this bridge, throws on refusal.
+            return settingsResponse(await fetch(CONFIG_PATH, {
+              method: 'PUT', headers: { 'content-type': 'application/json' },
+              body: JSON.stringify({ ops, expectedRevision }), signal: controller.signal,
+            }));
+          };
+          const committed = await Promise.race([operation(), expired]);
+          if (!mountedRef.current) return;
+          if (bindingRef.current.service !== base.source) throw new Error(t('saveUnconfirmed'));
+          if (committed?.available === false || committed?.status === 'unavailable'
+            || !committed?.value || !Number.isSafeInteger(committed.revision)
+            || committed.revision < expectedRevision) throw new Error(t('saveUnconfirmed'));
+          acceptSnapshot(committed, base.source);
+          clearDraft();
+        } catch (error) {
+          if (mountedRef.current) updateState((s) => ({ ...s, status: s.value ? 'ready' : 'error', error: String(error?.message ?? error) }));
+        } finally {
+          clearTimeout(timeout);
+          saveInFlightRef.current = false;
+          if (saveControllerRef.current === controller) saveControllerRef.current = null;
+          if (mountedRef.current) setSaving(false);
+        }
       };
 
-      
-
       const field = (labelText, node) => h('label', { className: 'krot-field' },
         h('span', { className: 'krot-label' }, labelText), node);
 
@@ -1156,12 +1441,13 @@ window.__ModuleLoader__.load({
         placeholder,
       });
 
-      const btn = (labelText, onClick, opts) => h('button', {
-        className: 'krot-btn' + (opts && opts.primary ? ' krot-save' : ''),
-        onClick,
-        disabled: Boolean(opts && opts.disabled),
-        title: (opts && opts.title) || undefined,
-      }, labelText);
+      const btn = (labelText, onClick, opts = {}) => {
+        const { primary, className = '', ...rest } = opts;
+        return h('button', { type: 'button', ...rest,
+          className: 'krot-btn' + (primary ? ' krot-save' : '') + (className ? ' ' + className : ''),
+          onClick, disabled: Boolean(rest.disabled),
+        }, labelText);
+      };
 
       // Key state dot: color and label read at a glance; "key not found"
       // catches an env-name typo that would otherwise stay silent.
@@ -1187,8 +1473,8 @@ window.__ModuleLoader__.load({
       };
 
       const searchInput = h('input', { className: 'krot-in', placeholder: 'Search providers…', value: search, onChange: (e) => setSearch(e.target.value), style: { marginBottom: '8px' } });
-      const providerRows = providerList.map((entry, pIndex) => {
-        const options = [];
+      const providerRows = providerList.map(({ entry, pIndex }) => {
+        const options = [h('option', { key: '', value: '' }, t('chooseProvider'))];
         if (entry.provider && !providerById.has(entry.provider)) {
           options.push(h('option', { key: entry.provider, value: entry.provider }, entry.provider + ' (' + (catalog.status === 'ready' ? t('notRegistered')
             : catalog.status === 'loading' ? t('loading') : t('providerCatalogUnavailable')) + ')'));
@@ -1230,7 +1516,7 @@ window.__ModuleLoader__.load({
         const keyRows = filteredIndices.map(({ key, kIndex }) => {
           const st = keyStatus(entry.provider, key);
           const info = keyInfo(entry.provider, key);
-          const rowKey = entry.provider + '/' + kIndex;
+          const rowKey = entry.provider + '/' + key;
           const typed = secretDraft[rowKey];
           const fromEnv = Boolean(info && info.source === 'env');
 
@@ -1261,7 +1547,7 @@ window.__ModuleLoader__.load({
               placeholder: info && info.tail ? '••••' + info.tail : t('keyValuePlaceholder'),
               onChange: (e) => setSecretDraft((cur) => ({ ...cur, [rowKey]: e.target.value })),
             }));
-            if (typed) meta.push(btn('✓', () => saveSecret(key, rowKey), { title: t('keySave'), key: 'w' }));
+            if (typed) meta.push(btn('✓', () => saveSecret(key, rowKey), { title: t('keySave'), key: 'save-secret' }));
           }
           if (info && typeof info.usage === 'number' && info.usage > 0) {
             let tip = 'requests through this key';
@@ -1318,7 +1604,7 @@ window.__ModuleLoader__.load({
             btn('✕', () => removeKey(pIndex, kIndex), { title: t('removeKey') }),
           ));
 
-          return h('div', { key: kIndex, className: 'krot-key' },
+          return h('div', { key, className: 'krot-key' },
             nameRow,
             h('div', { className: 'krot-meta' }, meta),
           );
@@ -1440,8 +1726,9 @@ window.__ModuleLoader__.load({
               setField((cur) => {
                 const next = [...(cur.providers ?? [])];
                 if (!next[pIndex]) return cur;
-                const sorted = [...(next[pIndex].keys ?? [])].sort((a, b) => usageOf(b) - usageOf(a));
-                next[pIndex] = { ...next[pIndex], keys: sorted };
+                const entry = next[pIndex];
+                const order = entry.keys.map((_, index) => index).sort((a, b) => usageOf(entry.keys[b]) - usageOf(entry.keys[a]));
+                next[pIndex] = reorderKeys(entry, order);
                 return { ...cur, providers: next };
               });
             }, { title: t('sortUsage') }),
@@ -1485,7 +1772,7 @@ window.__ModuleLoader__.load({
           h('div', { className: 'krot-keys' }, keyRows),
           h(UpdaterSection, { t }),
       h('div', { className: 'krot-foot' },
-            btn(t('addKey'), () => addKey(pIndex), { title: t('addKeyTitle') }),
+            btn(t('addKey'), () => addKey(pIndex), { title: t('addKeyTitle'), disabled: !entry.provider.trim() }),
             switchesLine,
             budgetLine,
             sloLine,
@@ -1599,10 +1886,10 @@ window.__ModuleLoader__.load({
             });
           }, { disabled: selected.size === 0 || !bulkCooldown }),
           btn(t('bulkRemove'), () => {
-            const ids = [...selected];
-            if (!ids.length) return;
+            const ids = new Set(selected);
+            if (!ids.size) return;
             setConfirmModal({
-              title: t('confirmBulkRemoveTitle').replace('{n}', String(ids.length)),
+              title: t('confirmBulkRemoveTitle').replace('{n}', String(ids.size)),
               desc: t('confirmBulkRemoveDesc'),
               actionLabel: t('bulkRemove'),
               danger: true,
@@ -1661,11 +1948,11 @@ window.__ModuleLoader__.load({
           field(t('selfHealingLabel'), textInput(String(val.selfHealingIntervalMinutes ?? 30), (v) => setField((cur) => ({ ...cur, selfHealingIntervalMinutes: Number(v) || 0 })))),
           field(t('proactiveGuardLabel'), h('label', { style: { display: 'flex', alignItems: 'center', gap: '8px', height: '36px', cursor: 'pointer' } }, [
             h('input', {
-              type: 'checkbox',
+              key: 'input', type: 'checkbox',
               checked: val.proactiveRateLimitGuard ?? true,
               onChange: (e) => setField((cur) => ({ ...cur, proactiveRateLimitGuard: e.target.checked })),
             }),
-            h('span', { style: { fontSize: '13px', color: 'var(--dsw-alias-label-secondary)' } }, t('proactiveGuardLabel')),
+            h('span', { key: 'label', style: { fontSize: '13px', color: 'var(--dsw-alias-label-secondary)' } }, t('proactiveGuardLabel')),
           ]))
         )
       );
@@ -1683,15 +1970,15 @@ window.__ModuleLoader__.load({
             const a = document.createElement('a'); a.href = url; a.download = 'pools.json'; a.click(); URL.revokeObjectURL(url);
           }, {}),
           h('label', { className: 'krot-btn', style: { cursor: 'pointer' } }, t('importPools'), h('input', { type: 'file', accept: '.json', style: { display: 'none' }, onChange: (e) => {
-            const f = e.target.files[0]; if (!f) return;
-            const reader = new FileReader();
-            reader.onload = () => { try { const imp = JSON.parse(String(reader.result)); if (!Array.isArray(imp)) throw new Error('expected array'); setField((cur) => {
-              const curProviders = Array.isArray(cur.providers) ? [...cur.providers] : [];
-              const map = new Map(curProviders.map((p) => [p.provider, p]));
-              for (const p of imp) { if (p && typeof p.provider === 'string') map.set(p.provider, p); }
-              return { ...cur, providers: [...map.values()] };
-            }); } catch (err) { setSecretError(String(err.message || err)); } };
-            reader.readAsText(f);
+            const file = e.target.files[0]; e.target.value = '';
+            readImport(file, (imported) => {
+              validatePoolDraft(imported);
+              setField((cur) => {
+                const map = new Map((cur.providers ?? []).map((p) => [p.provider, p]));
+                for (const p of imported) map.set(p.provider, p);
+                return { ...cur, providers: [...map.values()] };
+              }, true);
+            });
           } })),
           btn(t('snapshotExport'), () => {
             fetch('/dsh-key-rotation/snapshot', { headers: { accept: 'application/json' } })
@@ -1704,19 +1991,16 @@ window.__ModuleLoader__.load({
               .catch((e) => setSecretError(String(e?.message ?? e)));
           }, {}),
           h('label', { className: 'krot-btn', style: { cursor: 'pointer' } }, t('snapshotImport'), h('input', { type: 'file', accept: '.json', style: { display: 'none' }, onChange: (e) => {
-            const f = e.target.files[0]; if (!f) return;
-            const reader2 = new FileReader();
-            reader2.onload = () => {
-              try {
-                const snap = JSON.parse(String(reader2.result));
-                if (!snap || typeof snap !== 'object' || Array.isArray(snap)) throw new Error('expected snapshot object');
-                fetch('/dsh-key-rotation/snapshot', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ snapshot: snap }) })
-                  .then((r) => r.json().then((data) => ({ ok: r.ok, data })))
-                  .then(({ ok, data }) => { if (!ok) throw new Error(data?.error?.message ?? 'import failed'); load(); })
-                  .catch((err) => setSecretError(t('keyWriteFailed').replace('{msg}', String(err?.message ?? err))));
-              } catch (err) { setSecretError(String(err.message || err)); }
-            };
-            reader2.readAsText(f);
+            const file = e.target.files[0]; e.target.value = '';
+            readImport(file, (imported) => {
+              const snap = imported?.snapshot ?? imported;
+              if (!snap || typeof snap !== 'object' || Array.isArray(snap)) throw new Error('Expected a settings snapshot');
+              if (Object.prototype.hasOwnProperty.call(snap, 'providers')) validatePoolDraft(snap.providers);
+              const patch = { ...snap };
+              // Exported empty secret fields mean "not included", not "erase".
+              if (!patch.webhookActionToken) delete patch.webhookActionToken;
+              setField((cur) => ({ ...cur, ...patch }), true);
+            });
           } }))
         ),
         h('p', { className: 'krot-hint', style: { marginTop: '4px' } }, t('keyHint'))
@@ -1724,7 +2008,7 @@ window.__ModuleLoader__.load({
 
       const alerts = [
         secretError ? h('div', { key: 'se', className: 'krot-alert-bad' }, secretError) : null,
-        state.error ? h('div', { key: 'st', className: 'krot-alert-bad' }, state.error) : null,
+        state.error ? h('div', { key: 'st', role: 'alert', className: 'krot-alert-bad' }, state.error) : null,
         undo ? h('div', { key: 'un', className: 'krot-alert-ok' },
           h('span', null, undo.type === 'provider' ? t('undoProvider') : t('undoKey')),
           btn(t('undo'), doUndo, { className: 'krot-btn-sm' })
@@ -1773,19 +2057,28 @@ window.__ModuleLoader__.load({
         h('div', { className: 'krot-page-sub' }, t('header.sub'))
       );
 
-      return h('div', { className: 'krot' },
+      return h('div', { className: 'krot', 'aria-busy': saving || importing },
         confirmModalEl,
         headerSection,
         statsSection,
-        poolsSection,
-        failoverSection,
-        timingSection,
-        backupSection,
+        h('fieldset', { disabled: saving || importing || !state.writable,
+          style: { border: 0, padding: 0, margin: 0, minWidth: 0, display: 'flex', flexDirection: 'column', gap: '14px' } },
+          poolsSection,
+          failoverSection,
+          timingSection,
+          backupSection,
+        ),
         alerts.length > 0 ? h('div', { style: { display: 'flex', flexDirection: 'column', gap: '8px' } }, alerts) : null,
         h('div', { className: 'krot-foot', style: { marginTop: '6px', paddingTop: '14px', borderTop: '1px solid var(--dsw-alias-border-l2)' } },
-          btn(t('save'), save, { primary: true }),
-          btn(t('discard'), load, {}),
-          state.status === 'saving' ? h('span', { className: 'krot-hint' }, t('saving')) : null,
+          btn(t('save'), save, { primary: true, disabled: saving || importing || !state.writable || !draft }),
+          btn(t('discard'), () => {
+            if (saveInFlightRef.current || importRef.current) return;
+            clearDraft();
+            setSecretError('');
+            void load();
+          }, { disabled: saving || importing }),
+          saving || importing ? h('span', { className: 'krot-hint' }, t(saving ? 'saving' : 'loading')) : null,
+          !state.writable ? h('span', { className: 'krot-hint' }, t('readOnly')) : null,
         )
       );
     }
@@ -1867,6 +2160,7 @@ window.__ModuleLoader__.load({
     }
 
     function apply(ctx) {
+      const settingsSource = createSettingsSource(ctx);
       ctx.effect(() => ctx.locale.register(NS, { en, zh }), 'dsh-key-rotation: dictionaries');
       // Header chip (#201): status dot in the session header utilities slot,
       // same slot dsh-gitea / dsh-subscriptions use for their header widgets.
@@ -1908,35 +2202,24 @@ window.__ModuleLoader__.load({
                 h('path', { d: 'M3.5 5.25L7 8.75L10.5 5.25' })))),
           (page || open) ? h('div', { className: 'krot-card-body' }, h(KeyRotationErrorBoundary, null, h(KeyRotationSection, { ...props, locale }))) : null);
       }
-      // #275: card only — no top-level sidebar row. The host sidebar is a
-      // shared flat list; a duplicate row wastes a slot and confuses Settings.
-      // Plugin-list seat (plugins.item) first: it is what the current core
-      // (0.1.6-alpha.2) renders as the plugin's own page with its configuration. The
-      // label is a static string on purpose — it is resolved while the page renders,
-      // and a locale lookup there would take the whole client batch down with it.
-      try {
-        ctx.slots.inject('plugins.item', () =>
-          ctx.slots.register(
-            { name: 'plugins.item', id: ROW_ID, order: 60, label: () => 'Key Rotation', locale: NS, inject: () => ({ ctx }) },
-            KeyRotationCard,
-          ));
-        // Row seat and the legacy seat stay as fallbacks.
-        ctx.slots.inject('plugins.row.config', () =>
-          ctx.slots.register(
-            { name: 'plugins.row.config', key: ROW_CONFIG_KEY, locale: NS, inject: () => ({ ctx }) },
-            KeyRotationCard,
-          ));
-        ctx.slots.inject('settings.plugin.item', () =>
-          ctx.slots.register(
-            { name: 'settings.plugin.item', key: NS, locale: NS, inject: () => ({ ctx }) },
-            KeyRotationCard,
+      // Register each available seat independently. A missing legacy seat must
+      // not prevent the current bundle or row seat from registering.
+      for (const [name, key] of [
+        ['plugins.bundle.config', PKG],
+        ['plugins.row.config', ROW_CONFIG_KEY],
+        ['settings.plugin.item', NS],
+      ]) {
+        try {
+          ctx.slots.inject(name, () => ctx.slots.register(
+            { name, key, locale: NS, inject: () => ({ ctx, settingsSource }) }, KeyRotationCard,
           ));
-      } catch (e) {
-        bestEffort('slots.register.log', () => { console.error('[dsh-key-rotation] settings seats register failed', e); });
+        } catch (error) {
+          bestEffort('slots.register.log', () => { console.error('[dsh-key-rotation] settings seat unavailable', name, error); });
+        }
       }
     }
 
-    module.exports = { apply, inject: ['slots', 'locale', 'configForms'] };
+    module.exports = { apply, inject: ['slots', 'locale'] };
     return module.exports;
   },
     updateCheck: 'Check for updates',