alfred-proxy/README.md

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:

   npm install
   

3. Copy .env.example to .env and configure:

   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:

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