--- 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 ` (from Global)` for a Global source or ` (from )` 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 (` (from )`). 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= POST /api/v1/secrets/:id/move?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": "", "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": "", "workspace_id": "", "target_scope": "global" | "workspace", "target_workspace_id": "", "name": "" }` (`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.