fix: preserve remote OpenCode auth providers (#3382) (#3421)

This commit is contained in:
Carlos Florêncio
2026-09-05 20:32:25 +00:00
committed by GitHub
parent 73a399472d
commit 782c8a4006
19 changed files with 890 additions and 26 deletions
@@ -0,0 +1,53 @@
# ADR-2026-09-05-agent-owned-credential-file-conflicts: Agent-owned credential file conflicts
**Status:** accepted
**Date:** 2026-09-05
**Area:** backend
## Context
Remote credential methods identify source files and target directories. The shared transfer layer treats each file as an opaque value and replaces its target.
This behavior is correct for single-session token files. It is destructive for OpenCode `auth.json`, which is a provider map.
An SSH target can contain provider logins that do not exist on the Kandev host. A task launch currently removes those target-only entries.
The transfer layer cannot safely infer a file format from its path. Different agents can also change their credential formats independently.
## Decision
The agent remote-auth descriptor owns the existing-file policy. The default policy replaces the target to keep current behavior for opaque credential files.
OpenCode declares a top-level JSON-object merge for `auth.json`. The shared transfer layer applies this policy before it writes the target.
The merge preserves target-only providers and adds source-only providers. A source entry replaces the target entry for the same provider.
The transfer fails closed when an existing target is unreadable or is not a valid JSON object. The transfer does not replace that target.
## Consequences
- SSH task launches preserve OpenCode logins that exist only on the target.
- A selected host login remains authoritative when both hosts contain the same provider.
- Other agents keep their current replacement behavior.
- Persistent file transports need a target-read capability for merge policies.
- Isolated transports validate and write the source because no user target exists.
- New structured credential files can declare a policy without path checks in executor code.
- A concurrent agent write can still race with a read-merge-write transfer. This change does not add a remote file-lock protocol.
## Alternatives Considered
### Refuse every existing credential file
This policy prevents rotation and makes the selected copy method ineffective on persistent executors.
### Back up every replaced file
This policy retains old secrets and creates an unbounded set of credential copies on the remote host.
### Merge every JSON credential file
JSON structure does not imply merge semantics. A generic merge can create an invalid credential document for another agent.
### Add OpenCode path logic to the SSH uploader
This policy couples the transport to one agent and leaves the same transfer rule inconsistent on other executors.
+1
View File
@@ -242,3 +242,4 @@ Read individual ADRs for full context. Create new ones via `/record decision` or
| 2026-09-03-separate-system-data-storage-pages | [Separate System Data and Storage Pages](2026-09-03-separate-system-data-storage-pages.md) | accepted | frontend | 2026-09-03 |
| 2026-09-04-generation-fenced-task-environment-ownership | [Fence Task Environment Ownership by Generation](2026-09-04-generation-fenced-task-environment-ownership.md) | accepted | backend | 2026-09-04 |
| 2026-09-04-use-repository-token-for-runtime-pin-prs | [Use the built-in Actions token for runtime pin PRs](2026-09-04-use-repository-token-for-runtime-pin-prs.md) | accepted | workflow, security | 2026-09-04 |
| 2026-09-05-agent-owned-credential-file-conflicts | [Agent-owned credential file conflicts](2026-09-05-agent-owned-credential-file-conflicts.md) | accepted | backend | 2026-09-05 |
@@ -0,0 +1,77 @@
---
created: 2026-09-05
status: done
requirements:
- REQ-EXECUTORS-SSH-EXECUTOR-001
system_design:
- ../../specs/executors/system-design/ssh-executor.md
legacy_specs: []
---
# Implementation Plan: Preserve OpenCode SSH Credentials
## Overview
The fix adds an agent-owned policy for credential-file conflicts. OpenCode uses that policy to merge provider maps before a remote write.
One vertical work order changes the descriptor, transfer layer, transports, tests, and public executor reference. This order keeps one regression boundary.
## Scope
### In scope
- Preserve OpenCode providers that exist only in the target `auth.json`.
- Copy source-only providers and replace same-provider target entries with source entries.
- Leave an unreadable or malformed existing target unchanged.
- Keep the existing replace policy for other credential files.
- Document the SSH credential-copy behavior.
### Out of scope
- A user-selectable conflict policy.
- Timestamped credential backups.
- A remote lock for concurrent OpenCode writes.
- Changes to environment-based credential methods.
## Technical approach
Add an internal existing-file policy to `agents.RemoteAuthMethod`. Copy the policy into `remoteauth.Method` without adding a frontend contract.
Set the JSON-object merge policy only on the OpenCode file method. Keep replacement as the zero-value policy.
Add a narrow target-read interface beside `FileUploader`. Implement it for the persistent Sprites and SSH transports.
Isolated local and Kubernetes targets validate and write the source object. They do not require a target read.
Update `UploadCredentialFiles` to read and merge only when the selected method declares the merge policy. Return an error before each write when the merge input is invalid.
Use deterministic JSON encoding and private file mode for merged output. Keep existing write behavior for a missing target and for all replacement methods.
Update the SSH executor reference in `docs/public/executors.md`. State the OpenCode merge and malformed-file behavior.
## Tests
- `AC-EXECUTORS-SSH-EXECUTOR-001.11`: Add transfer tests for target-only, source-only, and same-provider entries.
- `AC-EXECUTORS-SSH-EXECUTOR-001.11`: Add an SSH integration test with an existing remote OpenCode provider map.
- `AC-EXECUTORS-SSH-EXECUTOR-001.12`: Add transfer and SSH tests that preserve malformed target bytes.
- Add a transfer test that keeps an isolated OpenCode credential copy working.
- Add catalog tests that make sure only OpenCode declares the merge policy.
- Keep a replacement test for an opaque credential file.
## Work orders
- [x] [Task 01: Merge OpenCode credential provider maps](task-01-merge-opencode-credential-providers.md)
## Verification results
- Focused Go tests: 19 passed in three packages.
- Specification linter: passed.
- Public documentation tests: 61 passed.
- Published documentation validator: 45 pages passed.
- Git diff check: passed.
## Risks
- A source-wins collision replaces the remote login for the same provider.
- A read-merge-write sequence does not protect against an agent write at the same time.
- Transport-specific missing-file errors must map to one shared absent-target result.
@@ -0,0 +1,109 @@
---
id: "01-merge-opencode-credential-providers"
title: "Merge OpenCode credential provider maps"
status: done
wave: 1
depends_on: []
plan: "plan.md"
requirements:
- REQ-EXECUTORS-SSH-EXECUTOR-001
acceptance_criteria:
- AC-EXECUTORS-SSH-EXECUTOR-001.11
- AC-EXECUTORS-SSH-EXECUTOR-001.12
system_design:
- ../../specs/executors/system-design/ssh-executor.md
---
# Task 01: Merge OpenCode Credential Provider Maps
## Summary
Add an agent-owned merge policy to the remote credential pipeline. Use it to preserve existing OpenCode provider logins on remote executors.
## In scope
- Add the internal credential-file conflict policy to agent and catalog models.
- Declare the JSON-object merge policy for OpenCode.
- Add target reads to persistent credential file transports.
- Keep isolated credential targets on the validated write path.
- Merge provider maps in the shared credential uploader.
- Preserve an existing target when a read or parse fails.
- Add focused unit and SSH integration tests.
- Update the public SSH executor reference.
## Out of scope
- A settings control for conflict behavior.
- Credential backups.
- Provider-specific deep merges below the top-level provider key.
- Remote file locking.
## Acceptance
- A copy preserves target-only providers and adds source-only providers.
- A source provider replaces a target provider with the same key.
- An unreadable or malformed existing target remains byte-for-byte unchanged.
- An unreadable source file reports a credential-copy error and does not write a target.
- A malformed source file reports a credential-copy error and does not write a target.
## Verification
```bash
cd apps/backend && go test ./internal/agent/agents ./internal/agent/remoteauth ./internal/agent/runtime/lifecycle -run 'Test(OpenCodeACPRemoteAuth|BuildCatalog|UploadCredentialFiles|SeedAgentSessionDir_OpenCode|SSHExecutorUploadCredentials|SSHFileUploader)' -count=1
python3 scripts/lint-spec-files.py --all
node --test scripts/validate-public-docs.test.mjs
node scripts/validate-public-docs.mjs
git diff --check
```
## Files likely touched
- `apps/backend/internal/agent/agents/agent.go`
- `apps/backend/internal/agent/agents/opencode_acp.go`
- `apps/backend/internal/agent/agents/opencode_acp_test.go`
- `apps/backend/internal/agent/remoteauth/catalog.go`
- `apps/backend/internal/agent/remoteauth/catalog_test.go`
- `apps/backend/internal/agent/runtime/lifecycle/credential_uploader.go`
- `apps/backend/internal/agent/runtime/lifecycle/credential_uploader_test.go`
- `apps/backend/internal/agent/runtime/lifecycle/agent_session_seeder.go`
- `apps/backend/internal/agent/runtime/lifecycle/executor_sprites.go`
- `apps/backend/internal/agent/runtime/lifecycle/executor_ssh_credentials.go`
- `apps/backend/internal/agent/runtime/lifecycle/executor_ssh_credentials_remote_test.go`
- `docs/public/executors.md`
## Dependencies
None.
## Risks
- Each transport reports a missing file differently. The shared reader contract must normalize this condition.
- The source-wins collision rule can replace one existing provider login by design.
## Parallelism
`sequential`
## Inputs
- `REQ-EXECUTORS-SSH-EXECUTOR-001`
- `docs/specs/executors/system-design/ssh-executor.md`
- `docs/decisions/2026-09-05-agent-owned-credential-file-conflicts.md`
- GitHub issue `kdlbs/kandev#3382`
- Existing `FileUploader` and passthrough JSON merge patterns.
## Results
Implemented the agent-owned JSON-object conflict policy for OpenCode credentials. SSH and Sprites read persistent targets before the merge.
Isolated targets validate and write the source object. Malformed inputs leave an existing target unchanged, and unreadable or malformed sources report a credential-copy error before any write.
Public docs updated: `docs/public/executors.md` (reference).
Verification results:
- Focused Go tests: 19 passed in three packages.
- Specification linter: passed.
- Public documentation tests: 61 passed.
- Published documentation validator: 45 pages passed.
- Git diff check: passed.
+5 -1
View File
@@ -382,7 +382,11 @@ Run **Test Connection**, independently verify the observed SHA256 host fingerpri
The profile editor exposes remote shell and agent-readiness checks. Backend/API configuration also recognizes `ssh_workdir_root` (default `~/.kandev`) and `ssh_shell`; the current profile UI exposes `ssh_shell` but not a workdir-root field.
The remote-auth card is built from the currently enabled agents. Depending on an agent's declared methods, it can copy selected local credential files, resolve a stored secret into that agent's authentication environment variable, or run an agent-specific setup script on the remote host. GitHub can use an explicitly selected `GITHUB_TOKEN` secret as an unmanaged profile override; Kandev does not copy the host-active `gh` token. These transfers write sensitive material under the remote user's home and are best-effort, verify authentication on the remote after saving. Although the profile editor also stores Git name/email controls for SSH, the current SSH runtime does not apply them; configure Git identity on the remote host yourself.
The remote-auth card is built from the currently enabled agents. Depending on an agent's declared methods, it can copy selected local credential files, resolve a stored secret into that agent's authentication environment variable, or run an agent-specific setup script on the remote host. GitHub can use an explicitly selected `GITHUB_TOKEN` secret as an unmanaged profile override; Kandev does not copy the host-active `gh` token.
OpenCode credential copies merge top-level provider entries with the existing remote `auth.json`. Remote-only providers remain, and the selected host entry replaces the same provider on the remote. If either file is unreadable or is not a JSON object, Kandev leaves the remote file unchanged and reports the credential-copy error.
These transfers write sensitive material under the remote user's home and are best-effort. Verify authentication on the remote after saving. Although the profile editor also stores Git name/email controls for SSH, the current SSH runtime does not apply them; configure Git identity on the remote host yourself.
</details>
@@ -29,6 +29,8 @@ Today the only ways to run an agent are: (1) locally on the user's own machine (
- **AC-EXECUTORS-SSH-EXECUTOR-001.8:** One SSH connection per `(host, user, identity-source)`, opened lazily and reused across all the executor's sessions on that host. Each session adds:
- **AC-EXECUTORS-SSH-EXECUTOR-001.9:** When a resumable SSH session's prior remote controller is confirmed absent, the system shall start a fresh controller in the preserved task workspace and load the preserved provider conversation.
- **AC-EXECUTORS-SSH-EXECUTOR-001.10:** When the system cannot determine whether a prior remote controller is alive because the SSH probe fails, resume shall fail without starting a replacement controller.
- **AC-EXECUTORS-SSH-EXECUTOR-001.11:** When Kandev copies OpenCode `auth.json` to an SSH host, it shall preserve target-only providers and copy source providers. The source entry shall replace the target entry when both files contain the same provider.
- **AC-EXECUTORS-SSH-EXECUTOR-001.12:** When the source or existing target is unreadable or is not a JSON object, Kandev shall leave the target unchanged. Kandev shall report the credential-copy error.
## System design
@@ -18,6 +18,7 @@ This design preserves the technical source detail for `REQ-EXECUTORS-SSH-EXECUTO
| Requirement | Design section |
| --- | --- |
| `REQ-EXECUTORS-SSH-EXECUTOR-001` | [Migrated source detail](#migrated-source-detail) |
| `AC-EXECUTORS-SSH-EXECUTOR-001.11` and `AC-EXECUTORS-SSH-EXECUTOR-001.12` | [Credential-file conflict policy](#credential-file-conflict-policy) |
## Migrated source detail
@@ -135,6 +136,26 @@ Multiple sessions in the *same* task share the same worktree on disk (same files
- The existing `executor_sprites_credentials.go` selection + upload logic for `remote_credentials` / `remote_auth_secrets` is the reference; SSH v1 wires the uploader and writes credentials to the SSH user's home dir.
- GitHub CLI token: same special case as Sprites (run `gh auth token` locally, inject as env var).
### Credential-file conflict policy
The agent descriptor owns the policy for an existing credential file. The transfer layer must not infer file semantics from a path or an executor type.
OpenCode declares a top-level JSON-object merge for `auth.json`. The transfer layer reads the target before it writes the source file.
The transfer layer preserves providers that exist only in the target. It adds providers that exist only in the source.
When both files contain a provider, the source entry replaces the target entry. This rule preserves the selected host credential as the copy source.
When the target does not exist, the transfer layer writes the source object. Other agent credential files keep the existing replace policy.
The merge requires two valid JSON objects. An unreadable or malformed target causes a copy error and remains unchanged.
The merge runs in the shared credential-upload path. Persistent transports expose target reads only for this policy and keep ordinary writes unchanged.
An isolated transport has no pre-existing user file. It validates the source object and writes it without a target read.
This design follows [ADR-2026-09-05-agent-owned-credential-file-conflicts](../../../decisions/2026-09-05-agent-owned-credential-file-conflicts.md).
### Recovery after backend restart
- Persist in `ExecutorRunning.Metadata` (allow-listed in `persistentMetadataKeys`): `ssh_host`, `ssh_port`, `ssh_user`, `ssh_host_fingerprint`, `ssh_remote_task_dir`, `ssh_remote_session_dir`, `ssh_remote_agentctl_port`, `ssh_remote_agentctl_pid`, `ssh_local_forward_port`, `ssh_workdir_root`, `ssh_proxy_jump`, `ssh_identity_source`, `ssh_identity_file`.