docs(adr): Per-Fleet managing identity — binding config, context switch & verification by brettchien · Pull Request #19 · openabdev/studio

brettchien · 2026-08-13T02:37:30Z

Drafted by Orca (ecs-claude) — flagging authorship since the fleet shares one GitHub identity.

Design stub (Status: Proposed) making the per-Fleet managing identity explicit, switchable, and verified — a declare → switch → observe → reconcile loop:

FleetBinding config (declare) — maps each managed Fleet → its managing context (account/role/region for AWS; context/namespace for k8s later). Operator/CP config, not the agent's Spec.identity.
Active context switch (apply) — selecting a Fleet binds subsequent calls to that Fleet's credential (the chosen profile / assumed role), instead of falling through to whatever ambient [default] the chain resolves first. Proactive fix.
RuntimeContext panel + IdentityMismatch (observe & reconcile) — read-only projection of the effective principal / account / region / source per Instance/Fleet, with a non-blocking warning when effective ≠ declared binding.

Why now: today's deploy_list AccessDenied was not a missing permission — the SDK chain silently resolved a static [default] profile (IAM user, wrong account/region) before the task-role provider, discovered only via a manual sts get-caller-identity. Declaring the binding + switching to it up front prevents the wrong-account call; the panel + mismatch verify it took.

Deliberately scoped as operator credential selection, not per-caller authz (still deferred per ADR-2). Vendor terms scoped to the driver (STS today, kubectl auth whoami later). Builds on ADR-2 (deployment-control-plane) and ADR-5 (desktop-core-sidecar); note the sidecar's ambient lazy resolution must be parameterized per Fleet to honor a binding (§4). Open questions — binding storage vs fleet-store #18, principal_source → concrete credential mapping, preflight scope — in §5. Stub to align direction, not a finished decision.

🤖 Generated with Claude Code

Authored by Orca (ecs-claude). Read-only RuntimeContext projection + Studio panel surfacing the effective principal/account/region per Instance/Fleet; observability only, no authz change (ADR-2 deferred authz stands). Motivated by the deploy_list static-default-profile fallback incident. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

… verify) Authored by Orca (ecs-claude). Adds FleetBinding config (Fleet -> managing context) and active context-switch on top of the read-only RuntimeContext panel, forming a declare->switch->observe->reconcile loop. Still operator credential selection, not per-caller authz (ADR-2 stands). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…ADR slice 1) (#20) studio-cp::observe_identity runs STS GetCallerIdentity and returns a generic, read-only RuntimeContext (principal / principal_kind role-vs-user / scope=account / location=region / source hint / caller_id). oab-mcp exposes it as a new read-only `runtime_context` MCP tool. First slice of ADR #19 (Per-Fleet managing identity) — observability only, no authz, no config/switch/UI yet. Would have surfaced the deploy_list static-default-profile fallback (user/... vs assumed-role/...) at a glance. Co-authored-by: Orca (ecs-claude) <orca@ecs.local> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

…slice 2) Declarative Fleet→managing-credential bindings, and the switch that makes a bound cluster's calls run under its credential instead of the ambient [default]. - studio-cp: `FleetBinding` / `FleetBindings` (serde), `default_bindings_path` ($OAB_FLEETS_CONFIG, else ~/.config/oab-studio/fleets.toml), `load_bindings` (missing file => empty, opt-in), `resolve_binding_config` (profile-first + optional region, layered on the standard chain). - oab-mcp: loads bindings at startup; `aws_for(cluster)` resolves the bound config once (memoized) and every deploy_* tool now switches through it, falling back to the default chain when no binding governs the cluster. `runtime_context` takes an optional cluster and reports the binding in effect. Profile-first per the agreed slice-2 scope; assume-role and the IdentityMismatch reconcile flag are later slices. Binding config is operator-side selection, kept separate from the Fleet Store (#18) observed/lease state. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Closes the declare→switch→observe→reconcile loop: compare the resolved caller principal against the binding's expected_principal. - studio-cp: `principal_matches(expected, actual)` — a read-only warning signal (never an authz gate). Handles STS assumed-role vs IAM role shape and a trailing `*` wildcard; a static `user/...` never satisfies a role expectation (exactly the fallback we want flagged). Unit-tested incl. the incident case. - oab-mcp: `runtime_context` now reports `expected_principal` and `identity_matches` (null when no expectation is declared). Stacks on the slice-2 FleetBinding switch. Assume-role credential form is the next slice (its provider API is version-sensitive; landing it isolated). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…slice 2) (#21) Declarative Fleet→managing-credential bindings, and the switch that makes a bound cluster's calls run under its credential instead of the ambient [default]. - studio-cp: `FleetBinding` / `FleetBindings` (serde), `default_bindings_path` ($OAB_FLEETS_CONFIG, else ~/.config/oab-studio/fleets.toml), `load_bindings` (missing file => empty, opt-in), `resolve_binding_config` (profile-first + optional region, layered on the standard chain). - oab-mcp: loads bindings at startup; `aws_for(cluster)` resolves the bound config once (memoized) and every deploy_* tool now switches through it, falling back to the default chain when no binding governs the cluster. `runtime_context` takes an optional cluster and reports the binding in effect. Profile-first per the agreed slice-2 scope; assume-role and the IdentityMismatch reconcile flag are later slices. Binding config is operator-side selection, kept separate from the Fleet Store (#18) observed/lease state. Co-authored-by: Orca (ecs-claude) <orca@ecs.local> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Closes the declare→switch→observe→reconcile loop: compare the resolved caller principal against the binding's expected_principal. - studio-cp: `principal_matches(expected, actual)` — a read-only warning signal (never an authz gate). Handles STS assumed-role vs IAM role shape and a trailing `*` wildcard; a static `user/...` never satisfies a role expectation (exactly the fallback we want flagged). Unit-tested incl. the incident case. - oab-mcp: `runtime_context` now reports `expected_principal` and `identity_matches` (null when no expectation is declared). Stacks on the slice-2 FleetBinding switch. Assume-role credential form is the next slice (its provider API is version-sensitive; landing it isolated). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Closes the declare→switch→observe→reconcile loop: compare the resolved caller principal against the binding's expected_principal. - studio-cp: `principal_matches(expected, actual)` — a read-only warning signal (never an authz gate). Handles STS assumed-role vs IAM role shape and a trailing `*` wildcard; a static `user/...` never satisfies a role expectation (exactly the fallback we want flagged). Unit-tested incl. the incident case. - oab-mcp: `runtime_context` now reports `expected_principal` and `identity_matches` (null when no expectation is declared). Stacks on the slice-2 FleetBinding switch. Assume-role credential form is the next slice (its provider API is version-sensitive; landing it isolated). Co-authored-by: Orca (ecs-claude) <orca@ecs.local> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

…A+B) (#26) The visible config surface the ADR #19 read model was missing: which fleet this Studio is managing, against which credential/account, and the ability to switch between fleets from the UI. - oab-mcp: new read-only `fleet_config` tool (9th tool) — lists the configured per-fleet bindings (name/cluster/region/profile/expected_principal) plus the config file path and default cluster. Server now retains the bindings path. Profiles are names, not secrets. Catalog test + module doc updated. - src-tauri: `fleet_config` bridge command (mirrors runtime_context). - console: FleetConfig view-model + Source method (Tauri + Mock fixture); a pure `fleetConfigHtml` renderer (one switchable button per fleet, empty state shows where to add bindings). Clicking a fleet re-points every read (roster + identity) at its cluster — the ADR "switch" step, which through oab-mcp's per-cluster binding changes the managing credential. 7 new render tests. Slice A (view) + B (switch) of the config panel. Editing (write-back to fleets.toml) is slice C, stacked on this. Co-authored-by: Orca (ecs-claude) <orca@ecs.local> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

… C) The edit half of the config panel: the operator edits the raw fleets.toml in a CodeMirror TOML editor and saves; the change validates, persists, and hot-reloads without a restart. Completes declare(edit) → switch → observe → reconcile. - studio-cp: `read_bindings_text` / `write_bindings_atomic` (temp+rename) / `save_bindings_text` — validate the text parses BEFORE writing (a bad edit never lands on disk) and store bytes verbatim, so comments/layout survive with no format-preserving lib. Unit tests: round-trip, reject-invalid-without-write, missing-file-is-empty. - oab-mcp: `fleet_config` now also returns the raw `text`; new write tool `fleet_config_write { text }` validates + writes + hot-reloads (bindings moved behind an RwLock; the per-cluster resolved-config memo is cleared on write). Catalog is 10 tools. - src-tauri: `fleet_config_write` bridge command. - console: CodeMirror 6 TOML editor (StreamLanguage + legacy TOML mode) mounted imperatively in a section separate from the re-rendered panel, so switching fleets never wipes an open edit. "Edit config" opens it; Save calls the write tool and surfaces a parse error inline; Cancel discards. 1 new render test. Slice C of the config panel, stacked on the A+B view/switch slice. Editing is raw-text (operator chose a TOML editor over a structured form). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

… C) (#30) The edit half of the config panel: the operator edits the raw fleets.toml in a CodeMirror TOML editor and saves; the change validates, persists, and hot-reloads without a restart. Completes declare(edit) → switch → observe → reconcile. - studio-cp: `read_bindings_text` / `write_bindings_atomic` (temp+rename) / `save_bindings_text` — validate the text parses BEFORE writing (a bad edit never lands on disk) and store bytes verbatim, so comments/layout survive with no format-preserving lib. Unit tests: round-trip, reject-invalid-without-write, missing-file-is-empty. - oab-mcp: `fleet_config` now also returns the raw `text`; new write tool `fleet_config_write { text }` validates + writes + hot-reloads (bindings moved behind an RwLock; the per-cluster resolved-config memo is cleared on write). Catalog is 10 tools. - src-tauri: `fleet_config_write` bridge command. - console: CodeMirror 6 TOML editor (StreamLanguage + legacy TOML mode) mounted imperatively in a section separate from the re-rendered panel, so switching fleets never wipes an open edit. "Edit config" opens it; Save calls the write tool and surfaces a parse error inline; Cancel discards. 1 new render test. Slice C of the config panel, stacked on the A+B view/switch slice. Editing is raw-text (operator chose a TOML editor over a structured form). Co-authored-by: Orca (ecs-claude) <orca@ecs.local> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

…nabdev#24) Surfaces "who am I managing this cluster as, against what account" in the Studio desktop skin — the visible panel the ADR's read model was built for. - src-tauri: `runtime_context` bridge command (mirrors deploy_list) → oab-mcp's runtime_context tool. - console: `RuntimeContext` view-model + Source method (Tauri + Mock); a pure `identityHtml` renderer showing principal / account / region / source / binding, with a role-vs-static-user kind badge and an IdentityMismatch highlight when the resolved principal fails the binding's expected_principal. Fetched once on boot; browser build uses a fixture. 6 new render tests. Verified locally: tsc --noEmit clean, vitest 14/14, vite build OK. The Rust bridge compiles via desktop.yml (compile-linux). Co-authored-by: Orca (ecs-claude) <orca@ecs.local> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

brettchien and others added 2 commits August 13, 2026 10:37

brettchien changed the title ~~docs(adr): Runtime Identity & Context panel — surface effective principal per Instance~~ docs(adr): Per-Fleet managing identity — binding config, context switch & verification Aug 13, 2026

brettchien marked this pull request as ready for review August 13, 2026 03:44

brettchien mentioned this pull request Aug 13, 2026

feat(cp): runtime_context — surface effective managing identity (ADR #19 slice 1) #20

Merged

brettchien merged commit 19e90ce into main Aug 13, 2026
1 check passed

brettchien deleted the docs/adr-runtime-identity-panel branch August 13, 2026 04:13

This was referenced Aug 13, 2026

feat(cp): FleetBinding config + per-fleet credential switch (ADR #19 slice 2) #21

Merged

feat(cp): IdentityMismatch reconcile check (ADR #19 slice 3) #22

Closed

brettchien mentioned this pull request Aug 13, 2026

feat(cp): IdentityMismatch reconcile check (ADR #19 slice 3) #23

Merged

This was referenced Aug 13, 2026

feat(desktop): Runtime identity/context panel (ADR #19) #24

Closed

feat(studio): fleet config panel — view + switch active fleet (ADR #19 A+B) #26

Merged

feat(studio): edit fleets.toml in-app — CodeMirror TOML editor (ADR #19 C) #27

Closed

brettchien mentioned this pull request Aug 13, 2026

feat(studio): edit fleets.toml in-app — CodeMirror TOML editor (ADR #19 C) #30

Merged

brettchien mentioned this pull request Aug 13, 2026

docs(adr): Fleet as usage-based grouping + Studio connection model #33

Merged

Navigation Menu

Uh oh!

docs(adr): Per-Fleet managing identity — binding config, context switch & verification - #19

docs(adr): Per-Fleet managing identity — binding config, context switch & verification#19
brettchien merged 2 commits into
mainfrom
docs/adr-runtime-identity-panel

brettchien commented Aug 13, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

brettchien commented Aug 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

brettchien commented Aug 13, 2026 •

edited

Loading