Linking a wallet changes how an existing account can be identified or accessed. The operation should require current proof of the application account and proof of the wallet being added. An address copied into a browser field supplies neither on its own.
This is a design proposal for the unimplemented Wallet Membership Kit. It is independent of NOVA and does not claim NFT gating or a delivered account-linking feature. The worksheet contains proposed review cases, all marked Not run.
Decide what the link permits
Write down whether the wallet will become a sign-in method, a membership lookup identity or simply a saved public address. These choices have different recovery consequences. If the link enables sign-in, losing the existing account session and controlling the wallet may allow access under the selected policy.
Require the user to reauthenticate before changing a sensitive account relationship. OWASP's authentication guidance recommends reauthentication for sensitive features and after relevant risk events. Choose the proof appropriate to the existing account system, then bind the wallet-link request to that authenticated user. OWASP authentication guidance.
Do not let a request body choose the account that will receive the link. The server should resolve the application user from the verified session and saved operation. Display that user identity alongside the wallet address before asking for confirmation.
Give the wallet a clearly scoped challenge
ERC-4361 defines domain-bound sign-in messages and verification requirements. Use a maintained verifier for the supported wallet type and expected chain. For linking, additionally bind the verified challenge to the saved account-link operation and its intended application user. The account relationship is application policy beyond the message's basic verification. Sign-In with Ethereum.
The proposed link record stores a wallet identity, the application user, the operation identifier and the verification time. It should also identify the network context required by the selected verification method. A contract address on one chain must not silently reuse verification evidence from another.
ERC-1271 supplies the contract-signature verification interface and notes that validity may depend on external state. Confirm whether the supported account set includes such wallets before treating every signature as ordinary address recovery. Contract signatures.
| Relationship event | Proposed requirement | Unresolved product decision |
|---|---|---|
| Add wallet | Fresh account proof and wallet proof | May one account hold several wallets? |
| Wallet already linked | Stop and explain a conflict | Is transfer ever permitted? |
| Remove wallet | Reauthenticate and inspect recovery options | Can the final sign-in method be removed? |
| Recover account | Apply a separately agreed recovery process | Who can review disputed ownership? |
| Change chain context | Verify the supported identity rule | Is the existing link still applicable? |
Prevent conflicting links at commit time
If the product rule allows one account per wallet identity, enforce that rule in the database. PostgreSQL supports unique constraints over multiple columns. Choose the identity columns from the actual domain model, then let the database reject competing claims to the same relationship. PostgreSQL constraints.
The conflict response should avoid revealing another user's private account details. Explain that the wallet cannot be linked through this operation and provide the defined recovery route. Do not resolve the conflict by moving the relationship to whichever request arrived last.
Cookie-authenticated link and unlink endpoints also need protection against cross-site request forgery. OWASP recommends established CSRF controls for state-changing requests and advises against using GET for those changes. Apply the existing application's protection rather than building a separate unprotected wallet endpoint. CSRF prevention.
Make unlinking and recovery reviewable
Before unlinking, show whether the user will retain another verified sign-in route. Record the removed relationship and invalidate access paths that depended on it according to the agreed session policy. A successful unlink should not leave a wallet-specific session with unexplained continuing access.
Recovery needs its own evidence requirements. A support operator should not move a wallet link merely because someone knows the address or can reproduce a public transaction. Define what proof can restore the application account, who reviews exceptions and how conflicting requests are handled.
Download the account-linking worksheet to record these choices and plan concurrent-link, unlink and recovery cases. Keep the cases marked Not run until an implementation produces evidence.
The Wallet Membership Kit blueprint can frame a custom integration with an existing account system. Bring the current authentication methods, desired wallet role and recovery rules before agreeing the first release.
