# Alfred Proxy

OAuth2 proxy server for Alfred Mobile app, providing secure WebSocket connection to OpenClaw Gateway with authentication, user preferences sync, and push notifications.

## Features

- **OAuth2 Authentication**: Authentik integration with JWT validation
- **WebSocket Proxy**: Routes mobile app connections to OpenClaw Gateway
- **User Preferences**: Per-user settings storage and sync
- **Push Notifications**: FCM integration for alerts and alarms
- **TTS Service**: ElevenLabs text-to-speech endpoint
- **File Uploads**: Media upload support for voice messages

## Setup

### Prerequisites

- Node.js 18+ 
- Firebase Admin SDK credentials (for push notifications)
- Authentik OAuth2 provider (or compatible OAuth server)
- OpenClaw Gateway instance

### Installation

1. Clone the repository
2. Install dependencies:
   ```bash
   npm install
   ```

3. Copy `.env.example` to `.env` and configure:
   ```bash
   cp .env.example .env
   ```

4. Edit `.env` with your values:
   - `OPENCLAW_TOKEN`: Get from your OpenClaw configuration
   - `AUTHENTIK_URL`: Your OAuth provider URL
   - `AUTHENTIK_CLIENT_ID`: OAuth client ID from your provider
   - `ELEVENLABS_API_KEY`: (Optional) For text-to-speech

5. Add Firebase credentials:
   - Download `service-account.json` from Firebase Console
   - Place in project root (already in .gitignore)

### Running

**Development:**
```bash
node server.js
```

**Production (systemd):**
```bash
# Copy service file
sudo cp alfred-proxy.service /etc/systemd/system/

# Enable and start
sudo systemctl enable alfred-proxy
sudo systemctl start alfred-proxy
```

## API Endpoints

### HTTP Endpoints

- `GET /health` - Health check
- `POST /api/notify` - Send notification to mobile devices
- `POST /api/tts` - Text-to-speech generation
- `POST /api/upload` - File upload
- `POST /api/alarm/dismiss` - Broadcast alarm dismissal

### WebSocket

- `ws://localhost:18790` - WebSocket proxy to OpenClaw
  - Requires `Authorization: Bearer <oauth-token>` header
  - Injects OpenClaw gateway token
  - Routes user messages to appropriate sessions

## Security

### Required Environment Variables

All sensitive values MUST be set via environment variables. The code defaults to empty strings for:
- `OPENCLAW_TOKEN`
- `AUTHENTIK_URL`
- `AUTHENTIK_CLIENT_ID`
- `ELEVENLABS_API_KEY`

### Protected Files (.gitignore)

- `.env` - Environment variables
- `service-account.json` - Firebase credentials
- `fcm-tokens.json` - User FCM tokens
- `users/` - User preferences
- `uploads/` - Generated TTS files

**Never commit these files!**

## User Preferences

Per-user settings are stored in `users/{userId}.json`:

```json
{
  "assistantName": "Jarvis",
  "voiceId": "voice-id-here"
}
```

Users can customize their assistant name and voice through the mobile app.

## Architecture

```
Mobile App (OAuth) 
    ↓
alfred-proxy (validates JWT, injects OpenClaw token)
    ↓
OpenClaw Gateway
    ↓
Agent Session
```

## Development

**Watch mode:**
```bash
npm run dev  # if you have nodemon
```

**Logs:**
```bash
tail -f /tmp/alfred-proxy.log  # systemd
# or
journalctl --user -u alfred-proxy -f
```

## License

MIT

## Security Notice

This is middleware security software. Ensure:
- OAuth tokens are kept secure
- OpenClaw token has appropriate permissions
- SSL/TLS enabled for production (use `wss://` not `ws://`)
- Firewall rules restrict access appropriately