138 lines
6.7 KiB
Markdown
138 lines
6.7 KiB
Markdown
# FedWiki Integration
|
|
|
|
This document describes how the member-console integrates with FedWiki for wiki site provisioning and management.
|
|
|
|
## Architecture Overview
|
|
|
|
The member-console manages FedWiki sites through the **FarmManager API**, a plugin that runs on a designated admin wiki site within a FedWiki farm. The security layer uses a composable architecture that separates authentication from authorization.
|
|
|
|
### Components
|
|
|
|
| Component | Package | Role |
|
|
|-----------|---------|------|
|
|
| Security layer | `wiki-security-composable` | Composable security plugin that separates authentication from authorization. Allows mixing auth providers with authorization enhancers. |
|
|
| Authentication | `wiki-security-passportjs` | OAuth2/OIDC authentication via Keycloak. Configured per wiki domain in `config.json` under `wikiDomains`. |
|
|
| Authorization | `wiki-plugin-useraccesstokens` | Adds API token (Bearer) authentication. Tokens are stored per-site in `status/user-access-tokens.json`. |
|
|
| Farm management | `wiki-plugin-farmmanager` | REST API for programmatic farm management (create, list, delete sites). Requires admin authentication. |
|
|
|
|
### How FarmManager Works
|
|
|
|
FarmManager is a **site-level plugin with farm-level scope**. It loads per-site (standard FedWiki plugin architecture), but manages all sites in the farm by resolving the parent farm directory from the current site's data path.
|
|
|
|
In practice, one site is designated as the **admin site** (e.g., `admin.localtest.me`). All farm management API calls go through this site. The plugin uses `app.securityhandler.isAdmin(req)` middleware to restrict access to farm admins.
|
|
|
|
## FarmManager API
|
|
|
|
All endpoints are served from the admin site and require admin authentication via Bearer token.
|
|
|
|
Base URL: `http://admin.localtest.me` (local dev)
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| `GET` | `/plugin/farmmanager/sites` | List all wiki sites in the farm |
|
|
| `POST` | `/plugin/farmmanager/sites` | Create a new wiki site |
|
|
| `GET` | `/plugin/farmmanager/sites/:domain` | Get details for a single site |
|
|
| `PATCH` | `/plugin/farmmanager/sites/:domain` | Partially update a site's properties |
|
|
| `DELETE` | `/plugin/farmmanager/sites/:domain` | Soft-delete (deactivate) a site |
|
|
| `DELETE` | `/plugin/farmmanager/sites/:domain?hard=true` | Permanently delete a site |
|
|
|
|
### Authentication
|
|
|
|
The member-console authenticates to the FarmManager API using a **User Access Token** (prefix: `fwuat-`), sent as a Bearer token in the `Authorization` header.
|
|
|
|
Tokens are generated by `wiki-plugin-useraccesstokens` and stored as bcrypt hashes in the admin site's `status/user-access-tokens.json`. Each token has:
|
|
- A `name` (unique per site)
|
|
- A `user` (the owner's OAuth2 identity)
|
|
- A `tokenHash` (bcrypt hash of the token)
|
|
- A `displayHint` (last 4 characters, for identification)
|
|
- Optional `scopes` (`site:read`, `site:write`)
|
|
|
|
## Member-Console Configuration
|
|
|
|
Relevant settings in `mc-config.yaml`:
|
|
|
|
```yaml
|
|
# URL of the admin wiki site (where FarmManager plugin is loaded)
|
|
fedwiki-farm-api-url: "http://admin.localtest.me"
|
|
|
|
# Domains where wiki sites can be created
|
|
fedwiki-allowed-domains:
|
|
- "localtest.me"
|
|
|
|
# URL scheme for generated site links
|
|
fedwiki-site-scheme: "http"
|
|
|
|
# User Access Token for FarmManager API authentication
|
|
fedwiki-admin-token: "fwuat-6R-p8TMlBBrwH7bV8l5oqsdoSbij5-SFHS5oVRJzGGM"
|
|
```
|
|
|
|
The `FarmManagerClient` in `internal/workflows/fedwiki/farmmanager_client.go` constructs API URLs as `baseURL + path` (e.g., `http://admin.localtest.me/plugin/farmmanager/sites`).
|
|
|
|
## Local Development Setup
|
|
|
|
### FedWiki Farm Structure
|
|
|
|
The FedWiki farm runs in Docker (see `test/compose.yaml`) on port 80 with these key directories:
|
|
|
|
```
|
|
test/data/fedwiki/ # Runtime data (mounted as /home/node/.wiki)
|
|
config.json # Farm configuration (OAuth2, wikiDomains, admin identity)
|
|
admin.localtest.me/ # Admin site (FarmManager API host)
|
|
status/
|
|
owner.json # Site owner identity (OAuth2 subject)
|
|
user-access-tokens.json # API tokens for Bearer auth
|
|
localtest.me/ # Root farm site
|
|
<subdomain>.localtest.me/ # User-created wiki sites
|
|
```
|
|
|
|
### Seed Data
|
|
|
|
Seed data lives in `test/seed/fedwiki/` and is copied to `test/data/fedwiki/` on `docker compose up` via the `fedwiki-init` container (`cp -rn`, no-clobber).
|
|
|
|
The seed includes:
|
|
- `admin.localtest.me/status/owner.json` — Admin site owner (alice, pinned ID: `a0000001-0000-4000-a000-000000000001`)
|
|
- `admin.localtest.me/status/user-access-tokens.json` — Pre-configured API token for member-console
|
|
|
|
### config.json
|
|
|
|
The `config.json` is **not seeded** — it is runtime-generated by FedWiki on first boot, or must be manually created. It contains:
|
|
|
|
- `admin` — Farm admin identity (OAuth2 subject). Must match a Keycloak user.
|
|
- `farm: true` — Enables farm mode.
|
|
- `wikiDomains` — Per-domain OAuth2 configuration (client ID/secret, Keycloak endpoints).
|
|
- `security_type`, `auth_provider`, `authz_enhancers` — Composable security stack.
|
|
|
|
If `config.json` is lost, FedWiki will generate a default one on startup, but you'll need to re-configure the OAuth2 wikiDomains and admin identity.
|
|
|
|
### Keycloak User IDs
|
|
|
|
Test user IDs are **pinned** in `test/seed/keycloak/seed-keycloak.sh` so that FedWiki seed data (owner.json, config.json) can reference them deterministically:
|
|
|
|
| User | ID | Role |
|
|
|------|----|------|
|
|
| alice | `a0000001-0000-4000-a000-000000000001` | Operator, FedWiki farm admin |
|
|
| bob | `b0000002-0000-4000-a000-000000000002` | Member |
|
|
| carlos | `c0000003-0000-4000-a000-000000000003` | Member |
|
|
| diana | `d0000004-0000-4000-a000-000000000004` | Member |
|
|
|
|
The Keycloak bootstrap `admin` user ID is assigned by Keycloak and is not pinned.
|
|
|
|
### Common Issues
|
|
|
|
**"Requested Wiki Does Not Exist" from FarmManager API**
|
|
- The admin site directory doesn't exist in `test/data/fedwiki/`. Ensure `admin.localtest.me/` exists with at least `status/owner.json`.
|
|
- Fix: Remove `test/data/fedwiki/` and restart docker compose to re-seed.
|
|
|
|
**EACCES permission denied**
|
|
- The FedWiki container runs as `node`. If the data directory is owned by root (e.g., after Docker recreates it), FedWiki can't write to it.
|
|
- Fix: `chmod -R 777 test/data/fedwiki/` or ensure your user UID matches the container's `node` user.
|
|
|
|
**Owner mismatch after Keycloak re-seed**
|
|
- If Keycloak user IDs change, the OAuth2 `id` in FedWiki's `owner.json` and `config.json` won't match. User IDs are now pinned to prevent this.
|
|
|
|
## Plugin Source Code
|
|
|
|
- [wiki-security-composable](https://git.coopcloud.tech/wiki-cafe/wiki-security-composable)
|
|
- [wiki-plugin-farmmanager](https://git.coopcloud.tech/wiki-cafe/wiki-plugin-farmmanager)
|
|
- [wiki-plugin-useraccesstokens](https://git.coopcloud.tech/wiki-cafe/wiki-plugin-useraccesstokens)
|