hadv / hadv/ethaura

Implement Out-of-Band Security Notifications for Timelock Actions

Open
#145 0 comments 0 reactions 0 assignees View on GitHub
⛨ security critical enhancement notification UI/UX
Dominant language
JavaScript
Stars
2
Forks
0
PR merge metrics
No merged PRs in 30d

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

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

```sql
-- 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: #140 Transaction Simulation (complementary feature)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.