Skip to main content

User Deletion

This chapter describes the Core implementation of the user deletion lifecycle. It is focused on user account state, credential cleanup, and wallet privilege management.

The lifecycle consists of three actions: marking a user for deletion, reversing a pending deletion, and finalizing deletion after the retention period expires.

Business Flow​

  1. Mark for Deletion:

    • A user can be marked for deletion by an authenticated Broker Partner System or by a DEUSS Backoffice Administrator.
    • In the partner flow, the caller must be authenticated through mTLS and may act only on users belonging to its own broker scope. In the admin flow, the Backoffice user must have a registry or user-management role.
    • The Registry Service verifies that the user is currently active from a deletion-state perspective (deletion_state = NONE).
    • Before the user can enter deletion, the system checks that the user is not an acting user for any active company and is not linked as an employee to an active company.
    • If the checks pass, the user is moved to PENDING, deletion_date is calculated from configuration, and the action is audit logged.

  2. On-Chain Privilege Revocation:

    • Users operate through standard wallets rather than dedicated company smart contracts.
    • After the off-chain state is changed to PENDING, the Registry Service creates a chain_operations record to revoke the user's wallet privileges.
    • JobRunnr processes the operation asynchronously and removes the wallet address from the relevant platform access control lists.
    • This prevents the pending-deletion user from performing further on-chain actions during the retention period.

  3. Reverse Deletion:

    • A pending user deletion can be cancelled while deletion_state = PENDING.
    • The Registry Service validates the caller's authorization and tenant scope, restores deletion_state = NONE, clears deletion_date, and logs the reversal.
    • A follow-up chain_operations record is created so JobRunnr can restore the user's wallet privileges across the relevant smart contracts.
    • Reversal is not allowed once the user has moved beyond the pending deletion stage.

  4. Final Deletion:

    • A scheduled system job scans for users with deletion_state = PENDING and expired deletion_date.
    • If eligible users are found, the job performs a hybrid cleanup: security credentials are removed, personal data is anonymized, and the user record is retained only in the form needed for historical audit references.
    • Associated passkey records are hard-deleted. The user's email address is scrambled or replaced with an anonymized value, and identity verification state is reset.
    • The user is then moved to DELETED.

State Lifecycle​

Sequence Diagram​

Constraints and Failure Handling​

Deletion is rejected when the caller is not authenticated, lacks the required role, or attempts to act outside the broker tenant scope. It is also rejected when the user is not in the expected deletion state.

The key business constraint is organizational linkage. A user who is still an acting user or employee of an active company cannot be deleted until those relationships are removed or transferred.

Blockchain execution failures are tracked through chain_operations. Temporary submission failures are retried by the background worker. If retries are exhausted or the transaction reverts on-chain, the operation is marked as failed and requires administrative follow-up.