Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

docs: record connector secret reuse review and validation evidence

M0e896d226edc
diff --git a/docs/design/connector-secret-reuse.md b/docs/design/connector-secret-reuse.md
index 46ea7a545..6fded188f 100644
--- a/docs/design/connector-secret-reuse.md
+++ b/docs/design/connector-secret-reuse.md
@@ -1,7 +1,8 @@
# Connector Secret reuse: implementation plan and audit
-Status: plan reviewed before implementation. Baseline: `55e2ad8f2` on
-`feat/ux-improvements-32`, after pulling the latest remote changes.
+Status: implemented and validated on `feat/ux-improvements-32`; see the
+implementation and validation record below. The plan was reviewed twice
+before and during implementation, with findings recorded in this document.
## Goal and scope
@@ -108,21 +109,140 @@ not invent authentication headers.
## Plan audit before implementation
-| Review question | Finding and resolution |
-| --- | --- |
-| Is the scope frontend-only? | Yes. Read backend contracts as evidence; change only Control UI and this document. |
-| Does the plan address both reported dead ends? | Yes: existing-secret selection at creation and reassignment for an existing `envSecret`. |
-| Could reuse overwrite or delete shared credentials? | Reference-only paths must have no Secret create/update/delete calls, including error cleanup. |
-| Could reassignment clobber a concurrent edit? | Compare the displayed spec with a fresh snapshot and use live UID/resourceVersion for the final write. |
-| Could a key rename silently break authentication? | Preserve each existing destination and require an explicit replacement key when it is absent in the new Secret. |
-| Is missing-secret repair preserved? | Keep the current set/rotate editor and offer change-assignment independently of stale Secret status. |
-| Can a new reference be mistaken for a ready connector? | Keep saved and ready states separate; use existing generation-correlated polling. |
-| Are all credential types interchangeable? | No. Keep OAuth and recipe ownership boundaries and explain static remote placeholder limitations. |
-| Can visual evidence prove live integration? | No. Local synthetic screenshots plus frontend tests verify UI contracts; deployed runtime remains a separate lane. |
+| Review question | Finding and resolution |
+| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
+| Is the scope frontend-only? | Yes. Read backend contracts as evidence; change only Control UI and this document. |
+| Does the plan address both reported dead ends? | Yes: existing-secret selection at creation and reassignment for an existing `envSecret`. |
+| Could reuse overwrite or delete shared credentials? | Reference-only paths must have no Secret create/update/delete calls, including error cleanup. |
+| Could reassignment clobber a concurrent edit? | Compare the displayed spec with a fresh snapshot and use live UID/resourceVersion for the final write. |
+| Could a key rename silently break authentication? | Preserve each existing destination and require an explicit replacement key when it is absent in the new Secret. |
+| Is missing-secret repair preserved? | Keep the current set/rotate editor and offer change-assignment independently of stale Secret status. |
+| Can a new reference be mistaken for a ready connector? | Keep saved and ready states separate; use existing generation-correlated polling. |
+| Are all credential types interchangeable? | No. Keep OAuth and recipe ownership boundaries and explain static remote placeholder limitations. |
+| Can visual evidence prove live integration? | No. Local synthetic screenshots plus frontend tests verify UI contracts; deployed runtime remains a separate lane. |
Audit verdict: proceed with the above constraints. No user decision or backend
work is needed for the planned static credential fixes.
+## Implementation review of the inherited WIP
+
+Second review, performed on the uncommitted selector/reassignment WIP found in
+the working tree on top of `54a30f064`. The WIP was adopted, not restarted.
+Findings and resolutions:
+
+1. **Appended test cases were structurally broken (harness, not product).**
+ The new `connectorCredentials.test.ts` cases passed bare arrays to
+ `it.each`, so Vitest spread each case into positional arguments: `items`
+ arrived as `undefined` or as a single Secret object instead of the items
+ array. The cases need one extra array level; no implementation change.
+2. **A stale or missing key could be answered with a value prompt.**
+ `validateCredentialAttach('use-existing', …)` intentionally allows keys that
+ are not yet stored in the selected Secret (the keyless-attach flow writes
+ those values into the shared Secret). The reference-only selector inherited
+ that behavior, so a key missing from the selected Secret produced "Enter a
+ credential value" — exactly the value re-entry this plan forbids.
+ Resolution: `validateCredentialAttach` gains an options object with
+ `storedKeysOnly`; the reuse selector, creation validation, reassignment
+ gating, and the pre-mutation verifier use it so a missing or stale key
+ reports a key-selection error, and a supplied value is rejected. Keyless
+ attach keeps its existing permissive behavior.
+3. **Focus was dropped when the change flow closed.** The edit page swaps the
+ whole credentials panel, so after cancel or finish the opener button
+ remounts and keyboard focus fell to `<body>`. Resolution: the page returns
+ focus to the "Change assigned Secret" trigger once the panel has reloaded.
+4. **The rotation busy interlock had no coverage.**
+ `UpdateConnectorCredentials` now reports busy while its confirm dialog is
+ open, which drives the page's duplicate-submit guard and tab/back
+ navigation lock. Tests pin the dialog-open busy report and the guard.
+5. **Cosmetic.** The edit-page fragment around `UpdateConnectorCredentials`
+ was misindented (formatter fixes it). The "Manage connector Secrets" link
+ inside the selector stays clickable while the fieldset is disabled; that is
+ acceptable read-only navigation, not a mutation path.
+6. **Verified non-issues.** Reference-only paths never call
+ `createMcpSecret`, `updateMcpSecret`, or `deleteMcpSecret`, including the
+ create form's rollback (gated on `willCreateSecret`, which is false in
+ reference mode). Reassignment rechecks the displayed snapshot and the live
+ UID/resourceVersion before and after verification, writes only
+ `spec.envSecret`, and never cleans up either shared Secret on error.
+ Unchanged assignments are refused client- and helper-side. Keyless attach,
+ OAuth, recipe ownership, and remote auth-header placeholders keep their
+ existing boundaries.
+
## Implementation and validation record
-To be completed as implementation milestones are verified.
+All work is frontend-only: Control UI plus this document. Implementation
+milestones:
+
+1. **Reference-only selection contract.** `validateCredentialAttach` accepts
+ an `AttachValidationOptions` argument; `storedKeysOnly` requires every key
+ to exist in the selected Secret, answers a missing or stale key with a
+ key-selection error (never a value request), and rejects any supplied
+ value. It is used by the reuse selector, the creation form's validation,
+ the reassignment gate, and `verifyExistingCredentialSelection`. Keyless
+ attach keeps its existing behavior of writing new keys (with values) into
+ a shared Secret.
+2. **Creation reuse.** The creation Secrets step offers a third choice, "Use
+ an existing Secret", backed by `ExistingConnectorSecretFields`: explicit
+ loading, error/retry, and empty states, an on-demand refresh, and explicit
+ key → environment-variable mappings with no value inputs. Submission
+ verifies the Secret's live identity and keys before any access-scope
+ creation or connector write; the rollback path can only delete a Secret
+ the same submission created (`willCreateSecret` stays false in reference
+ mode), so a failed creation never touches the shared Secret.
+3. **Reassignment.** Eligible managed, enabled, static connectors with a
+ valid `spec.envSecret` show an "Assigned Secret" section with "Change
+ assigned Secret" beside the untouched rotation editor.
+ `ChangeConnectorSecret` preserves each destination environment variable,
+ requires an explicit replacement key when the new Secret lacks one,
+ confirms with the old and new Secret names, and saves only
+ `spec.envSecret` through `changeConnectorSecretReference` (fresh snapshot
+ plus UID/resourceVersion checks before the write, unchanged-assignment
+ refusal, and no Secret create/update/delete on any error path). Readiness
+ reuses the bounded generation-correlated `useRolloutWait` observation;
+ saved and ready remain separate states. Recipe-owned, OAuth, disabled, and
+ keyless connectors keep their existing surfaces, and the eligible change
+ trigger is hidden otherwise.
+4. **Focus and interlocks.** The edit page returns keyboard focus to the
+ "Change assigned Secret" trigger after cancel or finish, waiting out the
+ post-save reload. `UpdateConnectorCredentials` reports busy while its
+ confirm dialog is open, which drives the page's duplicate-submit guard and
+ the tab/back navigation lock; the change flow feeds the same `attachBusy`
+ signal.
+5. **Management guidance.** The Secrets → Connectors header explains that
+ reusable Secrets are assigned during connector creation or from the
+ connector's Credentials tab via Change assigned Secret; other scopes keep
+ the generic subtitle.
+
+Validation evidence (Node 24, `UV_USE_IO_URING=0` on every npm command):
+
+- Focused suites, `npm test -- --maxWorkers=1` over `CreateMcpServerForm`,
+ `EditMcpServerPageAttach`, `EditMcpServerPageCredentials`,
+ `UpdateConnectorCredentials`, `SecretsTable`,
+ `lib/connectorCredentials`, plus the new `ChangeConnectorSecret` and
+ `ExistingConnectorSecretFields` suites: 8 files, 254 tests passed.
+- New coverage includes: selector loading/error/retry/empty and refresh;
+ auto-mapping with destination preservation when keys differ; stale/missing
+ keys producing key-selection errors without value prompts; unchanged
+ assignment no-op; blocked-reason display; confirmation naming both Secrets
+ and "Other connectors keep their current assignments"; the spec-only PUT
+ carrying UID and resourceVersion; concurrent-change refusal; 409 and
+ uncertain-save handling with no shared-Secret cleanup; correlated
+ readiness success and bounded timeout recovery; page-level eligibility
+ gating (recipe-owned hides the trigger); the busy tab interlock; focus
+ return after cancel and after finish; the rotation confirm-dialog busy
+ report; and the Secrets guidance copy.
+- `node_modules/.bin/tsc --noEmit --incremental false -p tsconfig.json` —
+ clean.
+- `npm run style-rules` (repository root) — 0 errors; one pre-existing
+ desktop-app warning outside this change's scope.
+- Prettier written over every changed file; `git diff --check` clean.
+- Full Control UI suite: 251 files, 2885 tests passed; `npm run build`
+ completed successfully.
+
+Limits: all evidence is local and synthetic. No authenticated live product
+session was available, so no live backend, E2E, or deployed-runtime behavior
+is claimed. The planning screenshots under the ignored
+`.local-notes/infra/runs/connector-secrets-ui/` show the pre-change UI only.
+Backend reconciliation (HCC resolving a referenced Secret and restarting the
+workload) is outside frontend evidence and stays governed by the existing
+contract tests.