Files
kandev/docs/specs/workspaces/secret-scope-transfer.md
T

337 lines
18 KiB
Markdown

---
status: shipped
created: 2026-08-11
owner: tbd
---
# Copy and Move Secrets Between Scopes
## Why
Moving a credential between a workspace and the user's Global set (or between
workspaces) currently means reveal, copy the plaintext, create a new secret,
and delete the old one. Users must handle the value outside Kandev, which is
both tedious and leak-prone. Kandev should copy or move a secret across scopes
as one operation, without ever showing the value.
## What
- Every secret row on the Global secrets page (`/settings/general/secrets`) and
on a Workspace secrets page (`/settings/workspace/:id/secrets`) offers a
**Copy/Move** action.
- The action opens one dialog that works the same on both pages. It contains:
- a **Copy / Move** radio (default Copy);
- a **destination** picker: **General** plus every workspace; when the source
secret is Workspace-scoped its own workspace is excluded, and when the
source is Global, General is excluded (a same-scope destination is a no-op);
- an editable **target name** field, pre-filled with
`<name> (from Global)` for a Global source or `<name> (from <workspace
name>)` for a Workspace source.
- **Copy** creates a new secret in the destination scope with the chosen name
and the source's value. The source stays.
- **Move** copies the secret to the destination and then removes the source, as
one atomic operation. The dialog states that the original will be removed
from its current scope.
- Workspace-to-workspace copy/move is supported through the destination picker.
- The persisted default target name is locale-independent: the origin token is
the literal string `Global` for a Global source and the raw workspace name
for a Workspace source. Only the surrounding pattern
(`<name> (from <origin>)`). The dialog default is truncated so
its UTF-8 encoding is at most 100 bytes, matching the backend's byte-based
name limit.
- If the chosen target name already exists in the destination scope, the
operation is blocked: the name field is marked invalid (red) with an error
message. The backend enforces this **atomically** inside the same transaction
that creates the copy and returns `409 Conflict`; the dialog also pre-checks
against loaded destination names when available.
- Copying or moving into the scope the secret already belongs to is rejected
with a clear validation error.
- Copying or moving a secret to a workspace requires that the destination
workspace exists and that the caller has access to it; a workspace source
also requires access to its owning workspace. Missing, unauthorized, or
nonexistent targets resolve to "not found" and never disclose whether the
secret or workspace exists.
- After a successful operation the visible lists update immediately: the
source list drops the secret after a Move, and the destination list shows
the new secret when it is the page being viewed. A Move or Copy into General
always adds the returned item to the Global store, regardless of which page
started it.
- The flow never reveals or copies plaintext through the UI; the encrypted
value moves between rows server-side.
## API surface
### HTTP
```text
POST /api/v1/secrets/:id/copy?workspace_id=<source-workspace-id>
POST /api/v1/secrets/:id/move?workspace_id=<source-workspace-id>
```text
The `workspace_id` query parameter identifies the source secret's workspace and
is required when the source is Workspace-scoped (matching the existing scoped
CRUD routes). The request body:
```json
{
"target_scope": "global" | "workspace",
"target_workspace_id": "<id>",
"name": "<optional target name>"
}
```
- `target_workspace_id` is required when `target_scope` is `workspace`.
- `name` is optional with presence semantics: a JSON-omitted `name` means "use
the source secret's name"; a present `name` must be non-empty after trimming
(an explicitly empty or whitespace-only name is a `400` validation error),
and an explicit JSON `null` is rejected as a `400` validation error rather
than treated as omitted. The name limit is 100 UTF-8 bytes after trimming,
matching the existing create/update validation.
- Success returns `201 Created` with the new `SecretListItem` (for Move the
source is already deleted at that point).
- Errors:
- `400` invalid payload or validation (bad scope/workspace combination,
same-scope destination, invalid name);
- `404` missing or unauthorized source, or missing/unauthorized destination
workspace;
- `409` target name conflict (atomically detected);
- `500` sanitized internal failure (decryption, storage). Details go to
server logs, never the response.
### WebSocket
```text
secrets.copy
secrets.move
```text
Payload: `{ "id": "<source>", "workspace_id": "<source-workspace>",
"target_scope": "global" | "workspace", "target_workspace_id": "<id>", "name":
"<optional>" }` (`name` follows the same presence semantics as HTTP;
`workspace_id` follows the same source-scoping rule as the HTTP query
parameter: omitted or empty selects a Global source, and a Workspace source
requires a non-empty value, resolving to not-found when missing). Success
responses return the new `SecretListItem` as the WS payload (same fields as
the HTTP response), mirroring the existing `secrets.create` convention. Error
codes: `ErrorCodeConflict` (name conflict), `ErrorCodeNotFound`
(missing/unauthorized source or destination), `ErrorCodeBadRequest`
(validation), `ErrorCodeInternalError` (unexpected failures, sanitized).
### Go service surface
```go
type CopySecretRequest struct {
Scope SecretScope `json:"target_scope"`
WorkspaceID string `json:"target_workspace_id"`
Name *string `json:"name,omitempty"` // omitted = use source name; null/empty/whitespace = validation error
}
var ErrSecretNameConflict = errors.New("a secret with this name already exists in the target scope")
var ErrWorkspaceAccessDenied = errors.New("workspace access denied or workspace not found")
var ErrSecretValidation = errors.New("secret validation failed")
```
Handlers classify exclusively with `errors.Is` against these sentinels and
`ErrNotFound`; they never match error text.
Because Go's standard JSON decoding maps both an omitted key and an explicit
`null` to a nil pointer, the request type (or the handler decode path)
implements presence-aware decoding: a custom `UnmarshalJSON` records whether
the `name` key was present, so the service rejects explicit `null` as a
validation error while defaulting a truly omitted key to the source name.
func (s *Service) Copy(ctx context.Context, sourceID, sourceWorkspaceID string, req *CopySecretRequest) (*SecretListItem, error)
func (s *Service) Move(ctx context.Context, sourceID, sourceWorkspaceID string, req *CopySecretRequest) (*SecretListItem, error)
```
The database schema is unchanged and `scope`/`workspace_id` stay immutable;
the `ScopedSecretStore` interface gains the two transfer methods below. The
service authorizes and validates, then delegates to atomic store operations:
```go
// ScopedSecretStore additions. sourceWorkspaceID is the RESOLVED source's
// workspace ("" for a Global source); a Move locks it alongside the
// destination so concurrent same-source moves serialize without deadlock.
// verifyDestination runs inside the transfer transaction while the
// destination lock is held, before the conflict check and insert; returning
// an error rolls back and surfaces that error (the service maps it to
// ErrWorkspaceAccessDenied / 404).
CopyScoped(ctx context.Context, sourceID, sourceWorkspaceID string, targetScope SecretScope, targetWorkspaceID, targetName string, verifyDestination func(context.Context) error) (*Secret, error)
MoveScoped(ctx context.Context, sourceID, sourceWorkspaceID string, targetScope SecretScope, targetWorkspaceID, targetName string, verifyDestination func(context.Context) error) (*Secret, error)
```
`CopyScoped` checks the target name and inserts the copy in one transaction;
`MoveScoped` additionally deletes the source in the same transaction. Both
return `ErrSecretNameConflict` when the target name is already taken and
`ErrNotFound` when the source row is absent. `UserVisibleStore` delegates and
rejects internal (`github:` prefix) source IDs. The encrypted value is copied
without passing plaintext through the service.
Store invariants for the transfer operations:
- The copied row is created with the caller's `user_id` (the same scoping the
regular create path writes); a transfer never produces an unowned row.
- The source select and the Move source delete use the same per-user
visibility predicate as the rest of the store, so a user can only move rows
they can see.
- The target-name conflict check compares the normalized scope (a legacy
empty stored scope is Global), so a legacy Global row can never be bypassed.
- The check-then-insert is atomic on both supported dialects: SQLite starts
the transaction with `BEGIN IMMEDIATE` (writer lock up front), and
PostgreSQL executes `BEGIN` then a `pg_advisory_xact_lock` on the target
scope's lock key on that same transaction before the source select and
conflict check, serializing competing writers so exactly one copy/move wins
a same-target-name race under READ COMMITTED. The PostgreSQL statement never
runs on SQLite. No schema or uniqueness-constraint change; pre-existing
duplicate names remain allowed by the regular create path.
- Lock scheme (single authoritative contract, PostgreSQL only): the secrets
package exports `WorkspaceLockKey(workspaceID string) int64`, a
deterministic FNV-1a 64-bit hash of the `kandev-secret-transfer:` prefix
plus the workspace ID — stable across restarts, collision-safe for UUID
inputs (a theoretical hash collision only over-serializes, never corrupts)
— plus a distinct stable constant `GlobalSecretTransferLockKey` for Global
targets. A transfer acquires the destination scope's key (and the source
workspace's key for Move, in sorted key order) and, while holding it, runs
the destination existence/authorization verification inside the transaction
before the conflict check and insert. The workspace-deletion transaction's
secret-cleanup step (`DeleteWorkspaceSecretsTx`) acquires the same
workspace key at its start and holds it to commit. Interleavings are
therefore closed: a transfer that inserts before a deletion commits is
cleaned up by that deletion under the same lock, and a transfer that starts
after the deletion commits observes the workspace gone and fails closed. On
SQLite the secrets database's single writer serializes transfer and
cleanup; the residual cross-database window matches the existing create
path (no schema change). A deterministic race test (separate connections,
channel-scheduled) proves no secret remains attached to a deleted workspace,
and a concurrent same-name test with a Global target proves exactly one
winner on the Global lock.
## Permissions
- A Global source is visible to the caller through the existing global access
rules; a Workspace source resolves only when the caller is authorized for
that workspace (same `GetWorkspaceSecret` path as the scoped CRUD routes).
- A workspace destination requires both existence and authorization. The
workspace authorizer is enforced for authenticated callers; a separate
existence check runs even in auth-disabled/unscoped contexts so a copy/move
can never attach a secret to a phantom workspace ID.
- Missing, unauthorized, or nonexistent sources/destinations all resolve to
"not found" — the error never reveals whether the secret or workspace
exists.
- Backend-owned internal secret IDs (`github:` prefix) are not addressable and
resolve to "not found".
## Failure modes
- **Target name conflict:** the operation fails closed with `409 Conflict` and
a message naming the scope and the conflicting name. The conflict check and
the copy share one transaction, and competing transfers are serialized
(writer lock up front on SQLite, advisory transaction lock on PostgreSQL), so
concurrent requests with the same target name yield exactly one success and
`409` for the others; nothing partial is created.
- **Same-scope destination:** rejected with a validation error before any
transfer mutation (a read-only source resolution may already have happened).
- **Source missing or unauthorized:** `404`, nothing changes.
- **Destination missing or unauthorized:** `404`, nothing changes; existence is
verified even when authorization is disabled. If the workspace-existence
checker is not wired, workspace destinations fail closed (same `404`).
- **Move failure:** the copy and the source deletion are one transaction. Any
failure (including a crash) rolls back; the source remains intact and no
copy exists. There is no intermediate dual-state or compensation window.
- **Internal failure (decryption, storage, or a database error inside an
authorization/existence lookup):** `500` with a sanitized message; full
details are logged server-side. Values never appear in error payloads. Only
the known "missing or unauthorized" sentinels (secret, workspace) map to
`404`; unknown errors are never reclassified as client mistakes.
- **Destination workspace fetch failure (dialog pre-check):** the dialog falls
back to the backend's authoritative `409`; the pre-check is best-effort only.
- **Workspace list failed to load (settings hydration failure):** the dialog
shows a localized retry/failure state and disables submit instead of
presenting an empty destination picker; a Global source must never see a
form with zero valid destinations.
- **Workspace list loaded successfully but is empty:** the dialog shows a
localized "no valid destinations" state (rather than an empty picker) and
keeps submit disabled; a Global source has no valid target and must not be
able to submit.
- **Source deleted or destination unavailable while the dialog is open:** the
backend returns `404` (deliberately ambiguous between a missing source and a
missing/unauthorized destination, so it never discloses which). The dialog
shows a localized generic failure message and stays open; rows are never
removed automatically on a `404`, and no destination item is added. The
source list refreshes on the next navigation or reload.
## Scenarios
- **GIVEN** a Global secret named `API Key`, **WHEN** the user opens Copy/Move
on it, chooses Copy, destination `My Workspace`, and keeps the default name
`API Key (from Global)`, **THEN** a Workspace secret named
`API Key (from Global)` with the same value appears in `My Workspace` and
the Global secret remains.
- **GIVEN** a Workspace secret in `My Workspace`, **WHEN** the user chooses
Move to General, **THEN** a Global secret with the chosen name exists with
the same value and the Workspace secret is gone, and the Global store gains
the returned item even though the operation started on the Workspace page.
- **GIVEN** a Global secret, **WHEN** the user chooses Move to `My Workspace`,
**THEN** the Workspace secret is created and the Global secret is removed.
- **GIVEN** a Workspace secret in `A`, **WHEN** the user copies it to
workspace `B`, **THEN** a Workspace secret in `B` exists with the same value
and the secret in `A` remains.
- **GIVEN** a destination scope that already has a secret with the chosen
name, **WHEN** the user submits Copy or Move, **THEN** the operation is
blocked with `409`, the name field is marked invalid with an error, and
neither the destination nor the source changes.
- **GIVEN** two concurrent copy requests with the same target name into an
empty destination scope, **WHEN** both submit, **THEN** exactly one succeeds
and the other receives `409`; the destination contains one secret.
- **GIVEN** a source secret and a destination equal to the source's own scope
and workspace, **WHEN** the user submits, **THEN** a validation error is
returned and nothing changes.
- **GIVEN** a caller without access to the destination workspace, **WHEN** the
caller submits a copy/move into it, **THEN** the operation fails with `404`
without disclosing the workspace's secrets.
- **GIVEN** a destination workspace ID that does not exist and authentication
disabled, **WHEN** the caller submits a copy/move into it, **THEN** the
operation fails with `404` and no secret is created.
- **GIVEN** an internal backend-owned secret ID (`github:` prefix), **WHEN**
the caller submits a copy/move of it, **THEN** the operation fails with
`404`.
- **GIVEN** a user on the Global secrets page who copies a secret to a
workspace, **WHEN** the copy completes, **THEN** the Global list is
unchanged and no workspace-scoped item is added to the Global store.
- **GIVEN** a user on a Workspace secrets page who moves a secret to General,
**WHEN** the move completes, **THEN** the workspace list no longer contains
the secret and the Global store gains it.
- **GIVEN** a Global source named with multibyte characters, **WHEN** the
dialog computes the default target name, **THEN** the default is truncated so
its UTF-8 length is at most 100 bytes and the copy succeeds without a
backend validation error.
## Mobile design contract
- Entry point: the Copy/Move button on a secret row opens the same dialog on
phone widths, from both the Global and Workspace secrets pages.
- Presentation: the dialog adapts to the phone viewport (full-height
sheet/drawer behavior rather than a centered desktop box), keeps the
Settings content area as the single scroll owner, respects safe areas, and
restores focus on close; Escape and back navigation close it.
- Interaction: the Copy/Move radios, destination picker, and name field use
touch-sized targets (at least 44px), rows stack to one column, and there is
no horizontal overflow. The destination picker is operable by touch and
keyboard alike.
- Accessibility: the dialog has a `DialogTitle`, real `Label`/`htmlFor`
associations for the name and destination controls (never placeholder-only),
a labeled Copy/Move radio group, conflict errors associated via
`aria-describedby`, and keyboard-operable radios (Tab/Arrow/Space).
- Parity: phone users can complete the full copy and move flows, including
choosing a workspace destination and correcting a conflicting target name.
## Out of scope
- Bulk copy/move of multiple secrets at once.
- Automatic conflict resolution (overwrite, auto-rename); conflicts always
block and require the user to change the target name.
- Copying values into literal environment variables or non-secret storage.
- Changing scope in place: scope and workspace remain immutable; copy/move is
the supported way to transfer authority.
- Live propagation of the copied value to running tasks or terminals.