Implement Out-of-Band Security Notifications for Timelock Actions

[hadv]

Overview

The timelock mechanism (24-48 hours) is useless without notifications. Users must be alerted when security-critical actions are proposed so they can cancel malicious actions within the timelock window.

This is the most critical security improvement for EthAura.

Problem Statement

Current State:
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│ Attacker        │     │ 48-hour         │     │ User doesn't    │
│ proposes new    │ ──► │ timelock        │ ──► │ check app       │
│ passkey         │     │ starts          │     │                 │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                                        │
                                                        ▼
                                               ┌─────────────────┐
                                               │ Account         │
                                               │ takeover!       │
                                               └─────────────────┘

Risk: If a user doesn't manually check the app during the 48-hour window, the attacker succeeds.

Solution

Proposed State:
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│ Attacker        │     │ 48-hour         │     │ User receives   │
│ proposes new    │ ──► │ timelock        │ ──► │ email/push      │
│ passkey         │     │ starts          │     │ notification    │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                                        │
                                                        ▼
                                               ┌─────────────────┐
                                               │ User cancels    │
                                               │ from any device │
                                               └─────────────────┘

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                   Notification System                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  On-Chain Events         Indexer/Backend         User Alerts   │
│  ┌─────────────┐        ┌─────────────┐        ┌─────────────┐ │
│  │ ActionProp- │  ───►  │ Event       │  ───►  │ Email       │ │
│  │ osed(...)   │        │ Listener    │        │ Push        │ │
│  │ RecoveryIn- │        │             │        │ SMS         │ │
│  │ itiated(..) │        │             │        │ Telegram    │ │
│  └─────────────┘        └─────────────┘        └─────────────┘ │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Events to Monitor

Event	Priority	Message
ActionProposed	🔴 Critical	"Passkey update proposed. If not you, cancel within 48h"
RecoveryInitiated	🔴 Critical	"Recovery started. If not you, cancel within 24h"
RecoveryApproved	🟠 High	"Guardian approved recovery"
GuardianAdded	🟠 High	"New guardian added to your account"
GuardianRemoved	🟠 High	"Guardian removed from your account"
ActionExecuted	🟡 Medium	"Passkey successfully updated"
ActionCancelled	🟢 Info	"Proposed action was cancelled"

Implementation Phases

Phase 1: Backend Event Indexer

• Create event listener service for P256Account events
• Index events to database (account → user mapping)
• Store user notification preferences
• API endpoint for pending actions per account

Phase 2: Email Notifications

• Email template for security alerts
• SendGrid/SES integration
• Unsubscribe handling
• Rate limiting (prevent spam)

Phase 3: Push Notifications

• Firebase Cloud Messaging setup
• Service worker for web push
• Mobile push (if React Native app exists)
• Notification permission flow in UI

Phase 4: Frontend Integration

• Notification preferences in Settings
• Email verification flow
• Push notification opt-in
• Pending actions dashboard
• One-click cancel from notification link

Phase 5: Additional Channels (Optional)

• SMS notifications (Twilio)
• Telegram bot integration
• Discord webhook

User Settings UI

┌─────────────────────────────────────────────────────────────────┐
│  Security Notifications                                         │
│                                                                 │
│  Get notified about security-critical events:                   │
│                                                                 │
│  ☑ Email (user@example.com)                    [Change Email]  │
│  ☑ Push notifications                          [Test]          │
│  ☐ SMS (+1 555-0123)                           [Add Phone]     │
│  ☐ Telegram (@username)                        [Connect]       │
│                                                                 │
│  Alert Types:                                                   │
│  ☑ Passkey changes (proposed/executed)                         │
│  ☑ Recovery attempts                                           │
│  ☑ Guardian changes                                            │
│  ☐ All transactions (high volume)                              │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Email Template Example

Subject: ⚠️ Security Alert: Passkey Update Proposed for Your EthAura Account

------------------------------------------------------------------

A passkey update has been proposed for your account:

Account: 0x1234...5678
Proposed at: 2024-01-15 10:30 UTC
Executable after: 2024-01-17 10:30 UTC (48 hours)

IF THIS WAS NOT YOU:
Cancel immediately: https://app.ethaura.io/cancel/0xactionhash

This action will replace your passkey. If an attacker proposed
this, they will gain full control of your account.

Time remaining to cancel: 47 hours 30 minutes

------------------------------------------------------------------
You received this because you have security alerts enabled.
Manage preferences: https://app.ethaura.io/settings/notifications

Technical Considerations

Event Indexing Options

1. Self-hosted indexer (The Graph, Ponder, or custom)

   • Pro: Full control, no third-party dependency
   • Con: Infrastructure cost

2. Third-party service (Alchemy Webhooks, QuickNode Streams)

   • Pro: No infrastructure needed
   • Con: Vendor dependency

3. Hybrid (third-party webhook → our notification service)

   • Pro: Best of both worlds
   • Con: More complexity

Database Schema

-- User notification preferences
CREATE TABLE notification_preferences (
  account_address VARCHAR(42) PRIMARY KEY,
  email VARCHAR(255),
  email_verified BOOLEAN DEFAULT FALSE,
  push_enabled BOOLEAN DEFAULT FALSE,
  push_subscription JSONB,
  phone VARCHAR(20),
  telegram_chat_id VARCHAR(50),
  created_at TIMESTAMP,
  updated_at TIMESTAMP
);

-- Sent notifications (for deduplication)
CREATE TABLE sent_notifications (
  id SERIAL PRIMARY KEY,
  account_address VARCHAR(42),
  event_type VARCHAR(50),
  tx_hash VARCHAR(66),
  channel VARCHAR(20),
  sent_at TIMESTAMP,
  UNIQUE(account_address, event_type, tx_hash, channel)
);

Acceptance Criteria

• Users can register email for notifications
• Email sent within 1 minute of on-chain event
• Push notification sent within 30 seconds
• Cancel link in email works correctly
• Notification preferences saved and respected
• Rate limiting prevents notification spam
• Unsubscribe works correctly

Security Considerations

• Email verification required before sending alerts
• Cancel links should require re-authentication (passkey)
• Rate limit notifications to prevent DoS
• Don't expose sensitive data in notification content
• Secure webhook endpoints

Estimated Effort

• Backend indexer + email: 1 week
• Push notifications: 3-4 days
• Frontend settings UI: 2-3 days
• Testing + polish: 2-3 days

Total: 2-3 weeks

Dependencies

• P256Account events already emit correctly ✅
• Backend infrastructure (Node.js/Python service)
• Email service (SendGrid, AWS SES)
• Push service (Firebase, OneSignal)

Related Issues

• Parent: Risk Analysis improvements
• Related: Implement Transaction Simulation for Enhanced Wallet Security #140 Transaction Simulation (complementary feature)