Update API Reference with roles, push, WebAuthn endpoints; update Self-Hosting with VAPID setup

2026-06-28 18:02:44 -04:00
parent 92ecc2ec7d
commit cf29d789b5
2 changed files with 166 additions and 5 deletions
@@ -299,6 +299,117 @@ Execute webhook (public, no auth required):
 }
 ```

+## Roles & Permissions
+
+### POST /servers/:serverID/roles
+
+```json
+{
+  "name": "Moderator",
+  "color": "#fe8019",
+  "permissions": 76,
+  "position": 1
+}
+```
+
+Create a role. Requires `MANAGE_SERVER` permission.
+
+### GET /servers/:serverID/roles
+
+List roles for a server.
+
+### PATCH /servers/:serverID/roles/:roleID
+
+```json
+{
+  "name": "New Name",
+  "color": "#fabd2f",
+  "permissions": 127
+}
+```
+
+Update a role. Requires `MANAGE_SERVER` permission.
+
+### DELETE /servers/:serverID/roles/:roleID
+
+Delete a role. Cannot delete the default `@everyone` role. Requires `MANAGE_SERVER` permission.
+
+### PUT /servers/:serverID/members/:userID/roles
+
+```json
+{
+  "role_ids": ["uuid1", "uuid2"]
+}
+```
+
+Set member roles (replaces existing). Requires `MANAGE_SERVER` permission.
+
+### GET /servers/:serverID/members/:userID/roles
+
+Get roles assigned to a member.
+
+### Permission Constants
+
+| Permission | Bit | Value |
+|-----------|-----|-------|
+| VIEW_CHANNEL | 0 | 1 |
+| SEND_MESSAGES | 1 | 2 |
+| MANAGE_MESSAGES | 2 | 4 |
+| KICK_MEMBERS | 3 | 8 |
+| BAN_MEMBERS | 4 | 16 |
+| MANAGE_SERVER | 5 | 32 |
+| MANAGE_CHANNELS | 6 | 64 |
+| ADMINISTRATOR | 7 | 128 |
+| CONNECT_VOICE | 8 | 256 |
+| SPEAK_VOICE | 9 | 512 |
+| SHARE_SCREEN | 10 | 1024 |
+
+## Push Notifications
+
+### GET /push/vapid-public-key
+
+Returns the VAPID public key for push subscription.
+
+### POST /push/subscribe
+
+```json
+{
+  "endpoint": "https://...",
+  "p256dh": "...",
+  "auth": "..."
+}
+```
+
+Subscribe to push notifications.
+
+### POST /push/unsubscribe
+
+```json
+{
+  "endpoint": "https://..."
+}
+```
+
+Unsubscribe from push notifications.
+
+## WebAuthn (Scaffolding)
+
+### POST /auth/webauthn/register/begin
+
+Begin passkey registration. Returns WebAuthn options.
+
+### POST /auth/webauthn/register/finish
+
+Finish passkey registration. (Not yet implemented)
+
+### POST /auth/webauthn/login/begin
+
+Begin passkey login. (Not yet implemented)
+
+### POST /auth/webauthn/login/finish
+
+Finish passkey login. (Not yet implemented)
+
 ## File Upload

 ### POST /upload
@@ -24,14 +24,13 @@ Copy `.env.example` to `.env` and set:
 # App
 DUMPSTER_HOST=chat.your.domain
 DUMPSTER_PORT=8080
-DUMPSTER_SECRET=<random-secret>
+DUMPSTER_SECRET=<random>

 # Database
 POSTGRES_HOST=postgres
 POSTGRES_PORT=5432
 POSTGRES_USER=dumpster
-POSTGRES_PASSWORD=<random-password>
-POSTGRES_DB=dumpster
+POSTGRES_PASSWORD=<random>

 # Cache
 VALKEY_URL=redis://valkey:6379
@@ -40,7 +39,6 @@ VALKEY_URL=redis://valkey:6379
 MINIO_ENDPOINT=minio:9000
 MINIO_ACCESS_KEY=<random>
 MINIO_SECRET_KEY=<random>
-MINIO_BUCKET=dumpster-files

 # Voice/video (optional)
 LIVEKIT_API_KEY=<random>
@@ -48,6 +46,11 @@ LIVEKIT_API_SECRET=<random>

 # Giphy (optional)
 GIPHY_API_KEY=<your-key>
+
+# Push notifications (optional)
+VAPID_PUBLIC_KEY=<generated>
+VAPID_PRIVATE_KEY=<generated>
+VAPID_SUBJECT=mailto:admin@your.domain
 ```

 ## Ports required
@@ -102,7 +105,7 @@ Remove `auto_https off` and Caddy will fetch Let's Encrypt certificates.
 3. Add the bot to a server
 4. Run the bot:
   ```bash
-   BOT_TOKEN=<token> go run ./examples/modbot/main.go
+   BOT_TOKEN=*** go run ./examples/modbot/main.go
   ```

 ## Webhooks
@@ -115,3 +118,50 @@ Remove `auto_https off` and Caddy will fetch Let's Encrypt certificates.
     -H "Content-Type: application/json" \
     -d '{"content": "Hello from webhook!", "username": "GitHub"}'
   ```
+
+## Push notifications
+
+To enable push notifications:
+
+1. Generate VAPID keys:
+   ```bash
+   # Use any VAPID key generator, e.g.:
+   go run -exec "go run ./cmd/gen-vapid" . 
+   # Or use an online generator
+   ```
+
+2. Add to `.env`:
+   ```env
+   VAPID_PUBLIC_KEY=<generated>
+   VAPID_PRIVATE_KEY=<generated>
+   VAPID_SUBJECT=mailto:admin@your.domain
+   ```
+
+3. Users can subscribe via the web UI (browser notifications)
+
+## Roles & permissions
+
+Default roles are seeded when creating a server:
+- `@everyone` - Basic permissions (view, send, voice)
+- Server owner can create additional roles via `/servers/:id/roles`
+
+Permission bits:
+- VIEW_CHANNEL (1), SEND_MESSAGES (2), MANAGE_MESSAGES (4)
+- KICK_MEMBERS (8), BAN_MEMBERS (16)
+- MANAGE_SERVER (32), MANAGE_CHANNELS (64), ADMINISTRATOR (128)
+- CONNECT_VOICE (256), SPEAK_VOICE (512), SHARE_SCREEN (1024)
+
+## TUI client
+
+```bash
+# Build
+make build-tui
+
+# Run with env vars
+DUMPSTER_SERVER=https://chat.your.domain \
+DUMPSTER_TOKEN=*** \
+./dumpster-tui
+
+# Or with config file (~/.config/dumpster/config.yaml)
+./dumpster-tui
+```