hard: registration wallet-existence checks are TOCTOU — concurrent registers create duplicate identities

[EmeditWeb]

Problem

AuthService.register() (src/modules/auth/auth.service.ts, lines 46–77) enforces uniqueness application-side: findByWallet() then checkUsernameExists() then createProfile() — three separate round trips with no transaction and no reliance on a database-level unique constraint. Two concurrent registrations with the same wallet (double-click, retry storm, deliberate race) both observe "no existing wallet" and both insert. Same for usernames.

Downstream blast radius: identity lookups key on wallet address throughout the platform (loans, reputation reads, liquidity summaries). Duplicate profiles mean some requests resolve to identity A while others hit identity B — split credit history, split balances display, and an authentication ambiguity where findOrCreateUser()'s upsert (line 148) silently adopts whichever row the onConflict target selects. On-chain, one wallet maps to one borrower; off-chain now mapping to two profiles corrupts every reconciliation job.

If the users.wallet_address unique constraint exists in the schema, the second insert errors — but the current code surfaces it as a generic 500 rather than AUTH_WALLET_EXISTS, and username uniqueness handling is equally accidental.

Ground Rules

1. Read context/architecture-context.md, context/code-standards.md, context/progress-tracker.md in full
2. Read src/database/repositories/users.repository.ts in full
3. Inspect the actual table schema/constraints before coding; do not assume them

What To Build

1. Ensure DB-level UNIQUE constraints exist on users.wallet_address and users.username; add a migration if missing.
2. Rewrite register() to attempt the insert directly and map unique-violation errors to the existing structured 409 codes (AUTH_WALLET_EXISTS, AUTH_USERNAME_TAKEN) — eliminating the pre-check race entirely.
3. Wrap profile creation + avatar upload + token issuance failure handling so a failed registration does not leave orphaned avatar objects.
4. Tests: parallel duplicate-wallet registrations yield exactly one profile and one 409; duplicate username likewise; sequential re-register returns the same structured 409 as today (compatibility).

Files To Touch

• src/modules/auth/auth.service.ts
• src/database/repositories/users.repository.ts
• migration file
• tests
• relevant docs/progress tracker

Acceptance Criteria

• Uniqueness enforced by the database, not by racy pre-checks
• Error responses unchanged for legitimate callers
• Race covered by automated test
• Suite green

Mandatory Checks Before Opening PR

Standard checklist applies. PRs failing any check will be closed without review.

[mimi-esc]

I'd like to apply for this issue, I will resolve the registration TOCTOU race condition in auth.service.ts and submit PR within 2 days

[Godfrey-Delight]

Hello maintainer, please assign this to me. I would confirm the actual state of wallet_address/username constraints in the schema (not assumed) per the ground rules, and add a migration if either is missing a DB-level unique index. Rewrite register() to drop the findByWallet() → checkUsernameExists() pre-check sequence and instead attempt the insert directly, catching the unique-violation error code and mapping it to AUTH_WALLET_EXISTS or AUTH_USERNAME_TAKEN so the race is closed at the database level rather than papered over in application logic. I'll wrap profile creation, avatar upload, and token issuance in proper failure handling so a rejected registration cleans up any avatar object it already uploaded rather than leaving it orphaned. Tests will cover concurrent duplicate-wallet and duplicate-username registrations (asserting exactly one profile + one 409 each), plus a sequential re-register case to confirm the 409 response shape is unchanged for existing callers.

[k-deejah]

I’m interested in taking on issue #120 because it addresses a critical backend security and consistency problem: the TOCTOU race in registration.

I have experience working on backend security fixes, database validation, and race-condition-sensitive flows, and I’m comfortable tracing an issue from the service layer through repositories, database constraints, and automated tests. For this issue, I would first inspect the required architecture/context documents, repository implementation, and actual database schema to verify the existing wallet_address and username constraints rather than making assumptions.

My approach would be to enforce uniqueness at the database level, then refactor register() so the insert itself becomes the source of truth instead of relying on racy existence checks. I would correctly map unique-violation errors to the existing AUTH_WALLET_EXISTS and AUTH_USERNAME_TAKEN responses so existing callers retain the expected behavior.

I would also handle failures across profile creation, avatar upload, and token issuance carefully, including cleanup of any uploaded avatar when registration ultimately fails. Finally, I would add concurrent registration tests for duplicate wallets and usernames, verifying that exactly one registration succeeds and the competing request receives the expected 409 response, alongside sequential re-registration tests for compatibility.

I can work within the existing project conventions and will run the required checks before submitting the PR. I’m prepared to investigate the schema first, implement the fix cleanly, and submit the completed work within the requested timeframe.

[grantfox-oss]

🦊 GrantFox — @Godfrey-Delight has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #120)
2. Your PR will be reviewed by the StepFi-app maintainers

Good luck! Track your progress on GrantFox.