feat: Email-Only User Registration

[islandbitcoin]

Overview

Implement email-only authentication flow for new user registration, allowing users to sign up with just an email address (no phone required).

PR: #212
Branch: feat/email-registration
Status: Ready for review

Feature Description

User Flow

1. Client calls newUserEmailRegistrationInitiate with email address
2. Backend creates Kratos identity, sends OTP via recovery flow
3. Client calls newUserEmailRegistrationValidate with flowId + code
4. Backend validates code, creates account if new, returns auth token

Key Components

• GraphQL Mutations:
  • newUserEmailRegistrationInitiate - Start email registration
  • newUserEmailRegistrationValidate - Complete with OTP code
• Kratos Integration: New schema email_no_password_v0
• Account Upgrade: Device accounts can upgrade to email accounts
• Schema Upgrade Paths:
  • Device → Email (replaces traits)
  • Phone → Phone+Email (adds email trait)

Files Changed (43 files, +855/-216)

• src/graphql/public/root/mutation/new-user-email-registration-*.ts
• src/app/authentication/email.ts
• src/services/kratos/auth-email-no-password.ts
• src/app/accounts/create-account.ts
• src/app/accounts/upgrade-device-account.ts
• src/domain/authentication/registration-payload-validator.ts
• dev/ory/kratos.yml

Known Issues / Follow-up Work

🔴 HIGH PRIORITY (Security)

• Account Enumeration Vulnerability

  • Location: src/services/kratos/auth-email-no-password.ts lines 73-78
  • Issue: createIdentityForEmailRegistration() reveals whether email is already registered
  • Mitigation: Return consistent response regardless of email existence

• Missing TOTP Flow Completion

  • Location: newUserEmailRegistrationValidate returns totpRequired but no follow-up
  • Issue: If TOTP is required, no mutation exists to complete the flow
  • Action: Document expected client behavior or implement TOTP verification step

• Race Condition in Account Creation

  • Location: new-user-email-registration-validate.ts lines 63-78
  • Issue: Concurrent code validations could create duplicate accounts
  • Mitigation: Add distributed lock or database constraint

🟡 MEDIUM PRIORITY (Tech Debt)

• Inconsistent Error Handling - "dead branch" error message (line 162-163)
• Hardcoded Schema ID - Should use SchemaIdType.EmailNoPasswordV0 enum
• Known Account Enumeration TODO - FIXME at lines 415-419 not addressed
• Missing Transaction Handling - Multi-step operations in upgrade-device-account.ts

🟢 LOW PRIORITY

• Unused import pattern in validate mutation
• Undocumented GraphQL complexity value (120)
• Direct Kratos DB access (documented workaround for issue #3163)

Testing Status

• TypeScript compiles (yarn tsc --noEmit - 0 errors)
• Integration tests (pre-existing failures unrelated to this PR)

Dependencies

• Ory Kratos configuration update required
• No external feature dependencies

Related Issues/PRs

• Blocks: feat(invite): Referral system with Email/SMS/WhatsApp invites #259 (feat/invite) - Email invite validation depends on this feature

[patoo0x]

📋 Definition of Done — 💰 150,000 sats (bundled with flash-mobile#540)

⚠️ Bundled bounty: This issue is paired with flash-mobile#540 (mobile frontend). Both backend + mobile must be completed together for the full 150,000 sats payout.

Expected Behavior After Fix:

• New users can register with only an email address (no phone number required)
• User receives OTP via email, enters it to complete registration
• Account is created with full wallet access after email verification
• Existing device accounts can upgrade to email accounts
• Existing phone accounts can add email as an additional identity
• Mobile app has a complete email registration UI flow (input, OTP entry, success)
• No regression to existing phone-based registration

Deliverables:

• Backend PR against main (closes #260)
• Mobile PR against main (closes flash-mobile#540)
• Unit tests for backend auth flow (initiate, validate, error cases)
• Screen recording showing: full email registration from app launch → OTP → wallet access
• Lightning address provided in your first comment on this issue

Review Gate:

• All existing tests pass
• Ben signs off (backend)
• Nick signs off (mobile)
• Dread final approval

Payment: 150,000 sats via Lightning on merge.
See CONTRIBUTING.md for full details.

[HuiNeng6]

/attempt

Proposal - Email-Only User Registration Bundle

I'd like to work on this bundled bounty (flash#260 + flash-mobile#540).

Backend Approach (flash#260):

• Add emailRegistrationInitiate mutation to send OTP via SendGrid
• Add emailRegistrationValidate mutation to verify OTP and create account
• Implement OTP generation with 6-digit code, 5-min expiry
• Store pending registrations in MongoDB with TTL
• Add upgradeDeviceAccount mutation for existing device accounts
• Add �ddEmailIdentity mutation for existing phone accounts

Mobile Approach (flash-mobile#540):

• Create EmailRegistrationScreen with email input
• Create OTPVerificationScreen for code entry
• Add upgrade flow for device accounts
• Integrate with existing auth context
• Handle all error states (invalid email, expired OTP, etc.)

Technical Stack:

• Backend: TypeScript, Node.js, GraphQL, MongoDB, SendGrid
• Mobile: React Native, TypeScript

Timeline: 7-10 days for complete bundle with tests

Lightning address: [需要提供]

Ready to start immediately!