Implement Out-of-Band Security Notifications for Timelock Actions #145
Description
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
-
Self-hosted indexer (The Graph, Ponder, or custom)
- Pro: Full control, no third-party dependency
- Con: Infrastructure cost
-
Third-party service (Alchemy Webhooks, QuickNode Streams)
- Pro: No infrastructure needed
- Con: Vendor dependency
-
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)