feat(secrets): copy and move secrets between global and workspace scopes (#2583)
This commit is contained in:
@@ -0,0 +1,336 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user