alfred-proxy/SETUP.md

# Alfred Proxy Setup Guide

## Quick Start

### 1. Install Dependencies

```bash
cd ~/.openclaw/workspace/alfred-proxy
npm install
```

### 2. Create Authentik OAuth Provider

**In Authentik admin:**

1. Navigate to **Applications** → **Providers** → **Create**
2. Select **OAuth2/OpenID Provider**
3. Fill in:
   - **Name**: `Alfred Mobile OAuth`
   - **Authentication flow**: `default-authentication-flow`
   - **Authorization flow**: `default-provider-authorization-explicit-consent`
   - **Client type**: `Public`
   - **Client ID**: (will be auto-generated, note this down!)
   - **Redirect URIs**: 
     ```
     alfredmobile://oauth/callback
     http://localhost:8080/callback
     ```
   - **Signing Key**: Select an existing certificate
   - **Scopes**: Add `openid`, `profile`, `email`

4. Click **Create**

5. **Copy the Client ID** from the provider details page

### 3. Create Authentik Application

1. Navigate to **Applications** → **Applications** → **Create**
2. Fill in:
   - **Name**: `Alfred Mobile`
   - **Slug**: `alfred-mobile`
   - **Provider**: Select `Alfred Mobile OAuth` (the provider you just created)
   - **UI settings**: (optional) Add icon, description
   - **Policy engine mode**: `any`

3. Click **Create**

### 4. Configure the Proxy

```bash
cd ~/.openclaw/workspace/alfred-proxy

# Copy example config
cp .env.example .env

# Edit with your Authentik client ID
nano .env
```

Update `.env`:
```bash
AUTHENTIK_CLIENT_ID=<paste-your-client-id-here>
```

### 5. Test Locally (No Auth)

```bash
# Disable auth for testing
echo "REQUIRE_AUTH=false" >> .env

# Start proxy
npm run dev
```

In another terminal:
```bash
# Test health check
curl http://localhost:18790/health

# Test WebSocket (requires wscat: npm install -g wscat)
wscat -c ws://localhost:18790
```

If you see OpenClaw's connect challenge, the proxy is working! ✅

### 6. Switch OpenClaw to Localhost

```bash
openclaw config get gateway.bind  # Should show "lan" currently

# Switch to localhost only
cat >> ~/.openclaw/openclaw.json << 'EOF'
{
  "gateway": {
    "bind": "loopback"
  }
}
EOF

# Or use the gateway tool
openclaw gateway config apply <<< '{"gateway":{"bind":"loopback"}}'

# Restart gateway
systemctl --user restart openclaw-gateway.service

# Verify
openclaw config get gateway.bind  # Should show "loopback"
```

### 7. Enable Auth

```bash
# Re-enable auth
nano .env  # Set REQUIRE_AUTH=true

# Restart proxy
# (If running npm run dev, Ctrl+C and restart)
```

### 8. Install as Systemd Service

```bash
cd ~/.openclaw/workspace/alfred-proxy

# Install service
mkdir -p ~/.config/systemd/user
cp alfred-proxy.service ~/.config/systemd/user/

# Create override file with your Client ID
mkdir -p ~/.config/systemd/user/alfred-proxy.service.d
cat > ~/.config/systemd/user/alfred-proxy.service.d/override.conf << EOF
[Service]
Environment="AUTHENTIK_CLIENT_ID=YOUR_CLIENT_ID_HERE"
EOF

# Reload systemd
systemctl --user daemon-reload

# Enable and start
systemctl --user enable alfred-proxy.service
systemctl --user start alfred-proxy.service

# Check status
systemctl --user status alfred-proxy.service

# View logs
journalctl --user -u alfred-proxy.service -f
```

### 9. Expose via Network (Optional)

**Option A: Expose directly (for testing on local network)**

Update `.env`:
```bash
# Listen on all interfaces instead of just localhost
# (only if you understand the security implications)
PROXY_PORT=0.0.0.0:18790
```

**Option B: Expose via HAProxy with SSL (recommended)**

See README.md for HAProxy configuration.

### 10. Test with OAuth Token

**Get a test token from Authentik:**

```bash
# Use Authentik's OAuth2 token endpoint
curl -X POST https://auth.dnspegasus.net/application/o/token/ \
  -d "grant_type=password" \
  -d "username=YOUR_USERNAME" \
  -d "password=YOUR_PASSWORD" \
  -d "client_id=YOUR_CLIENT_ID"
```

Or use the Authentik admin UI to generate a token.

**Test with the token:**

```bash
wscat -c ws://localhost:18790 -H "Authorization: Bearer YOUR_TOKEN"
```

## Troubleshooting

### Proxy won't start

**Check Node.js:**
```bash
node --version  # Should be v24+
```

**Check dependencies:**
```bash
cd ~/.openclaw/workspace/alfred-proxy
npm install
```

### "ECONNREFUSED" connecting to OpenClaw

**Check OpenClaw is running:**
```bash
systemctl --user status openclaw-gateway.service
```

**Check OpenClaw bind mode:**
```bash
openclaw config get gateway.bind  # Should be "loopback"
```

**Test OpenClaw directly:**
```bash
wscat -c ws://127.0.0.1:18789
```

### "Invalid token" error

**Verify Authentik URL:**
```bash
curl https://auth.dnspegasus.net/.well-known/openid-configuration
```

**Test token validation:**
```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://auth.dnspegasus.net/application/o/userinfo/
```

**Check Client ID matches:**
- `.env` has correct `AUTHENTIK_CLIENT_ID`
- Token was issued for the correct client

### Logs show nothing

**Check service is running:**
```bash
systemctl --user is-active alfred-proxy.service
```

**Increase log verbosity:**
Edit the service to add `--debug` flag (future enhancement).

## Next Steps

1. **Configure Android app** to use OAuth flow
2. **Add HAProxy SSL** for production access
3. **Set up monitoring** for the proxy service
4. **Configure firewall** rules if exposing externally

## Security Checklist

- [ ] OpenClaw bound to localhost only
- [ ] Proxy validates all OAuth tokens
- [ ] OpenClaw token not exposed to clients
- [ ] HTTPS/WSS for external access
- [ ] Firewall rules in place
- [ ] Monitoring and logs configured
- [ ] Authentik user management set up
- [ ] Test token revocation works