Files
Steven Masley 03cba25a63 feat: list a workspace build's secrets in coder secret list (#30388)
`coder secret list` now shows the current workspace build's secrets next to your user secrets, and which user secrets they replace. Part of [RELAY-7](https://linear.app/codercom/issue/RELAY-7/agent-relay-deliver-provider-credentials-via-coder-secrets-instead-of).

**Stack** (design decisions in #30248)
1. #30248 Database schema, queries, and RBAC
2. #30249 Encryption at rest
3. #30250 Set secrets on workspace builds
4. #30251 Deliver secrets to the agent
5. #30252 Docs
6. **#30388 List a build's secrets (this PR)**
7. #30459 Audit a build's secrets

- New `GET /workspacebuilds/{workspacebuild}/secrets` lists a build's secrets (metadata only, never values) and which user secret each one replaces.
- Inside a workspace, `coder secret list` includes the current build's secrets. Outside a workspace, use `--workspace` or `--build-id`.
- The agent now exposes `CODER_WORKSPACE_BUILD_ID`, so the CLI knows which build it is running in.
- The agent manifest and the new endpoint use one shared resolver, so they always agree on which secret wins.
- The user secret API is unchanged.

<details>
<summary>Implementation details</summary>

- The manifest carries `workspace_build_id`; the agent sets it as `CODER_WORKSPACE_BUILD_ID`.
- `coderd/workspacesecrets.Resolve(user, build, policy)` decides which secret is delivered on each env var and file. The manifest no longer relies on entry order.
- `codersdk.WorkspaceSecret` embeds `UserSecret` and adds `workspace_build_id`, `ephemeral`, `cleared_at`, `env_replaces`, and `file_replaces`. Secrets whose values a later build cleared are still listed, with `cleared_at` set.
- CLI columns: `source` and `replaced by` are shown by default only when a build is included; `ephemeral` is opt-in. The CLI makes two requests: user secrets, then build secrets.
- Agents that predate the build ID fall back to `CODER_WORKSPACE_ID` and its latest build.

</details>

<details>
<summary>Decision log</summary>

(existing decision log, unchanged)

</details>

---

*Created by Coder Agents on behalf of @Emyrk.*
2026-10-15 17:40:00 -05:00

105 lines
3.3 KiB
Go

// Package workspacesecrets decides which secrets are delivered to a
// workspace and on which targets. The agent manifest and the workspace build
// secrets API both use Resolve so they always agree.
package workspacesecrets
import (
"path"
"github.com/google/uuid"
)
// FilePathPolicy controls whether secrets may be delivered as files.
type FilePathPolicy int
const (
// FilePathAllowed delivers file_path targets.
FilePathAllowed FilePathPolicy = iota
// FilePathBlocked drops every secret's file_path target, as set by the
// deployment's user secret file path option. Env targets are still
// delivered.
FilePathBlocked
)
// Secret is a candidate for delivery to a workspace. Value may be empty when
// only metadata is needed.
type Secret struct {
ID uuid.UUID
EnvName string
FilePath string
// Enabled is false for disabled user secrets. It is ignored for build
// secrets, which cannot be disabled.
Enabled bool
Value string
}
// Resolved is a Secret with its delivery outcome.
type Resolved struct {
Secret
// DeliveredEnvName and DeliveredFilePath are the targets the secret is
// actually delivered on. They are empty when the secret is disabled, the
// target is unset, blocked by policy, or taken by another secret.
DeliveredEnvName string
DeliveredFilePath string
// EnvReplacedBy and FileReplacedBy hold the ID of the secret delivered
// on this secret's target instead of it.
EnvReplacedBy uuid.NullUUID
FileReplacedBy uuid.NullUUID
}
// Delivered reports whether the secret is delivered on any target.
func (r Resolved) Delivered() bool {
return r.DeliveredEnvName != "" || r.DeliveredFilePath != ""
}
// Resolve returns the delivery outcome of the user secrets and the workspace
// build secrets, each in input order.
//
// Build secrets win over user secrets that share an env_name or file_path.
// Disabled user secrets are never delivered and never replace or get
// replaced. Env names are compared exactly. File paths are compared after
// path.Clean, so "~/a//b" and "~/a/b" collide, but "~/a" and "/home/<user>/a"
// cannot be matched on the server and do not.
func Resolve(user, build []Secret, policy FilePathPolicy) (resolvedUser, resolvedBuild []Resolved) {
envOwner := map[string]uuid.UUID{}
fileOwner := map[string]uuid.UUID{}
resolve := func(s Secret, enabled bool) Resolved {
r := Resolved{Secret: s}
if !enabled {
return r
}
if claim(envOwner, s.EnvName, s.ID, &r.EnvReplacedBy) {
r.DeliveredEnvName = s.EnvName
}
if policy == FilePathAllowed && s.FilePath != "" && claim(fileOwner, path.Clean(s.FilePath), s.ID, &r.FileReplacedBy) {
r.DeliveredFilePath = s.FilePath
}
return r
}
// Build secrets claim targets first, so they take precedence.
resolvedBuild = make([]Resolved, len(build))
for i, s := range build {
resolvedBuild[i] = resolve(s, true)
}
resolvedUser = make([]Resolved, len(user))
for i, s := range user {
resolvedUser[i] = resolve(s, s.Enabled)
}
return resolvedUser, resolvedBuild
}
// claim assigns key to id unless another secret already holds it, in which
// case that secret's ID is stored in replacedBy.
func claim(owners map[string]uuid.UUID, key string, id uuid.UUID, replacedBy *uuid.NullUUID) bool {
if key == "" {
return false
}
if owner, taken := owners[key]; taken {
*replacedBy = uuid.NullUUID{UUID: owner, Valid: true}
return false
}
owners[key] = id
return true
}