jknapp
44ac8b6d1c
- Environment-based configuration (no hardcoded secrets) - OAuth authentication via Authentik - ElevenLabs TTS integration via SAG CLI - FCM push notification support - User preferences sync system - Multi-user support with per-user context files - No internal IPs or service accounts in tracked files
150 lines
3.3 KiB
Markdown
150 lines
3.3 KiB
Markdown
# 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
|