Account transfer — design

Status: approved design, ready for an implementation plan
Date: 2026-08-11
Depends on: migration 00183 (users.deleted_at, soft delete), aclSpecificityLadder
(dms/adapters/acl_pg.go), usersLackingDocumentRead (httpapi/assign_guard.go)

The problem

SoftDeleteUser is unconditional. There is no precondition check anywhere between the admin
pressing Delete and the account being stripped. Deletion today removes everything that
grants the person access — role bindings, ACL entries, position assignments, group
memberships, delegations, secure-folder key wraps — and keeps the users row so historical
references still resolve to a name.

What it does not do is deal with anything the person still holds. Five things strand:

Doctrine

Transfer authority, never attribution.

Signatures (signatures.signer_user_id), document versions (document_versions.created_by),
the append-only audit chain, sent letters, meterai_records.requested_by — these keep the
original person's name forever. Moving them would falsify the record, which is the one thing
a records system must never do.

Only two classes of thing move:

• Authority — what the person may do that someone must continue doing (ownership).
• Obligation — work assigned to them that blocks until someone acts (tasks, requests,
  locks, in-flight ceremonies).

Everything else is history and stays put. This single rule decides most of the questions
below, and any future question about a table not listed here.

Decisions taken

Model

The blocking set

One read-only computation, used by three callers (the transfer screen, the delete
precondition, and the transfer executor). It returns, for a given user, a list of
(category, table, count, sample) rows.

type HoldingKind string   // "ownership" | "obligation" | "lock" | "vault" | "link"

type Holding struct {
    Kind      HoldingKind
    Category  string   // stable machine key, e.g. "documents.owned", "workflow.tasks"
    Count     int
    Blocking  bool     // does this refuse a delete?
    Transferable bool  // can the executor move it?
    SampleIDs []string // at most 5, for the UI to link to
}

Blocking and Transferable are separate axes on purpose. A Private Vault wrap is blocking
and NOT transferable — which is exactly the case that needs its own confirmation path. A
share link is transferable and not blocking.

Initial catalogue:

Why in-flight signatures are NOT transferable

A pending signature is a named legal party's obligation, not a work item. Reassigning it
would mean person B's signature appears where person A was asked to sign, under an audit
chain that says A was invited. The only correct outcomes are cancel (voiding the
ceremony and, for a paid seal, routing it to the existing repair queue from migration 00175)
or let A complete it before the account goes. The transfer screen offers cancel; it never
offers reassign.

This is the same principle as signatures.signer_user_id never moving. It is the doctrine
applied to something that has not happened yet.

Flow

A. Standalone transfer (POST /admin/users/{id}/transfer)

1. Admin opens Admin → Users → ⋮ → Transfer holdings.
2. Screen loads GET /admin/users/{id}/holdings — the blocking set, grouped by category,
   each with a count and up to five sample links.
3. Admin picks one successor. The picker is the existing subject picker, restricted to
   live, enabled users, excluding the leaver.
4. Eligibility check runs immediately, before anything is offered. See Security below.
5. Optional per-category override: a category can be pointed at a different successor, or
   excluded from this run.
6. Non-transferable categories are shown with what they do offer (cancel, or the loss
   confirmation).
7. Admin confirms. The executor runs in one transaction and writes one audit event per
   category plus one summary event.
8. Result screen: what moved, what did not, what is left.

The account is untouched — still enabled, still logged in. Transfer is not deletion.

B. Delete with a non-empty blocking set

DELETE /admin/users/{id} gains a precondition. When the blocking set is non-empty it
returns 409 with code auth.user.holdings_outstanding and the blocking set in the problem
detail. The UI turns that into the transfer screen with a "then delete" checkbox, so the
common path is one flow, not two.

?force=true is not offered. The only bypass is the vault loss confirmation, which is
its own explicit body field naming the folder ids being abandoned — not a general override.

C. Vault loss

If vault.sole_wrap is non-empty, the transfer screen shows each affected folder by name
with the plain sentence: this folder's contents cannot be recovered after this account is
deleted; no administrator, including you, can restore them. Proceeding requires typing the
folder count. The body carries abandon_vaults: ["<folder-id>", ...] — an explicit list, so
a stale UI cannot abandon a vault that appeared after the screen loaded.

The right answer is almost always to have the leaver add a second member wrap while they
can still log in. The screen says so, first, above the destructive option.

Security design

Transfer is a privilege-granting operation. Five rules:

1. Its own permission — users.transfer. Not folded into users.admin. Otherwise
   everyone who can delete an account can absorb everything it held, and offboarding becomes
   a privilege-escalation primitive.

2. The successor must pass the assign-beyond-ACL guard. Reuse
   usersLackingDocumentRead (httpapi/assign_guard.go) — the same check that decides
   whether a person may be assigned a workflow step. Without this, "transfer to me" is a
   one-click read of everything the leaver could read. Where the successor lacks access, the
   executor refuses that item and reports it; it never silently grants.

The exception, stated explicitly: ownership transfer necessarily confers access, since
owner implies Manage. So documents.owned and folders.owned require the successor to
already hold at least Read on the item, or the admin must accept an explicit
grant_access: true flag which is recorded in the audit event as a deliberate widening.

3. Step-up required. Same class as break-glass. Fail-closed: no valid step-up grant, no
   transfer.

4. One transaction, idempotent, fail-closed. A partial transfer is worse than none — it
   leaves a person half-owning things with no record of which half. Re-running with the same
   (leaver, successor, categories) must be a no-op, so the executor filters on the leaver
   still being the current holder rather than blindly updating.

5. The audit event names rows, not counts. "moved 43 documents" is unauditable. Each
   category event carries the id list (capped, with the full list written to the audit
   payload). This is the record of a privilege change and it has to answer which.

Two things that must not regress

• Read-model rebuild. Moving owner_id without calling ReplaceDocumentReadModel /
  ReplaceFolderReadModel leaves document_acl_read.is_owner pointing at the ghost, and
  the ladder keeps resolving against it. Folder ownership moves must walk the subtree
  (FolderIDsUnderSubtree).
• Deleted users must stay invisible. The successor picker, the holdings screen and the
  result screen all read /admin/users; that endpoint excludes deleted users by default and
  needs ?include_deleted=true only where a historical name is being rendered. The leaver
  themself is addressed by id, never by list membership.

Data

No new tables are strictly required — every change is an UPDATE on an existing column. One
new table is added for the record:

-- Migration 001XX
CREATE TABLE account_transfers (
    id            uuid PRIMARY KEY,
    from_user_id  text NOT NULL,
    to_user_id    text NOT NULL,
    -- category -> {moved: n, refused: n, ids: [...]}
    outcome       jsonb NOT NULL DEFAULT '{}'::jsonb,
    abandoned_vaults text[] NOT NULL DEFAULT '{}',
    performed_by  text NOT NULL,
    performed_at  timestamptz NOT NULL DEFAULT now()
);
CREATE INDEX account_transfers_from_idx ON account_transfers (from_user_id, performed_at DESC);

The audit chain already records the event; this table exists so the user screen can show
"holdings transferred to X on date Y" without reconstructing it from audit entries.

Out of scope

• Rules-based / per-position routing (rejected above).
• Transferring anything in the attribution class. Ever.
• Bulk transfer of many leavers at once. One account at a time; a bulk wrapper can come later
  over the same executor.
• Re-wrapping Private Vault keys. The server cannot, and no design makes it able to.

Testing

Backend verification follows the house rule — never go test against the shared DSN.
The blocking-set query and the executor are exercised against a scratch pgvector/pgvector:pg17
in dind with a seeded fixture; the eligibility and precedence logic is pure and gets a scratch
go run harness. End-to-end runs against the demo with a non-admin leaver, since every demo
user is admin by default and an all-admin roster cannot prove the guard fires.

Specific cases that must be covered because they are where this breaks:

1. Owner moves → document_acl_read.is_owner follows, and the ladder resolves for the
   successor and no longer for the leaver.
2. Folder owner moves → the whole subtree's read model is rebuilt, not just the folder row.
3. Successor lacking Read → that item is refused and reported, and no grant is written.
4. Re-running the same transfer → no-op, no duplicate audit event.
5. Delete with a pending workflow task → 409 with the category named, not a generic error.
6. Sole Private Vault wrap → delete refused; with abandon_vaults naming that folder,
   permitted, and the folder is recorded as abandoned.