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

Clone the repository
Install dependencies:
```
npm install
```
Copy .env.example to .env and configure:
```
cp .env.example .env
```
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
Add Firebase credentials:
- Download service-account.json from Firebase Console
- Place in project root (already in .gitignore)

Running

Development:

node server.js

Production (systemd):

# 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:

{
  "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:

npm run dev  # if you have nodemon

Logs:

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