member-console/docs/fedwiki-setup.md

title, audience, summary

title	audience	summary
FedWiki Integration	developer admin	How member-console provisions FedWiki sites through the FarmManager API: security stack, endpoints, configuration, and local dev/test setup.

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-social	OAuth2/OIDC authentication via Keycloak (better-auth based). Configured per wiki domain in config.json under wikiDomains using oauth2_discoveryUrl. Supersedes wiki-security-passportjs.
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:

# 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-REPLACE-WITH-YOUR-USER-ACCESS-TOKEN"

The FarmManagerClient in internal/integrations/fedwiki/workflows/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.

Custom Domains

Members on an entitled plan can point domains they own at FedWiki sites. Domain names are managed by the console's domains registry (domains-registry capability): every servable name is a placement inside a claim — an operator shared-domain root, a member claim carved from it (hosted sites), or a member-owned external claim proven once by DNS verification. Operator enablement takes two steps:

1. Author the entitlement rule. Add a boolean rule with resource key external_domain_claims to the entitlement set of any plan that should include custom domains (Operator → Entitlement Sets → Rules). The affordance appears only for workspaces whose pool holds the granted entitlement.
2. Set the connect target. Configure the core domains-connect-target key (environment, config file, or CLI flag) to the DNS name or IP members should point their domains at. While unset, the custom-domain flow stays hidden even for entitled workspaces. The capability is core's — the same key gates external claims everywhere, not just FedWiki's create flow.

The member flow is verify once, place freely: a domain is verified at the account level (the member "Domains" page, or inline from the Create Site dialog), and once its claim is active the member can create sites at that name — or any name inside it (wiki.example.org, docs.wiki.example.org, …) — instantly, with no further verification. Verification shows a records table to publish: a TXT challenge at _member-console-challenge.<domain> proving control, a CNAME/A record pointing at the connect target, and an optional wildcard CNAME (*.<domain> → target) so nested names need no per-site DNS work. A Temporal workflow polls for the TXT record (24-hour window by default) and activates the claim when it appears. Verification no longer auto-creates a site — the sites list offers a one-click create once the domain verifies. Unclaimed names are never served.

While a claim is pending:

• Each poll probes both records and the status view shows a per-record result — not found yet, found-but-mismatched (with the values we observed), or found. Only the TXT challenge gates verification; the CNAME/A probe is diagnostic so members can fix routing before the site exists. Record names and values are copyable in one click.
• Check now re-probes immediately (and resets the poll backoff) instead of waiting out the interval, which grows to 15 minutes.
• Cancel verification frees the domain immediately (claim canceled) and stops the polling workflow — a mistyped domain no longer squats the name for the full window.
• The instructions stay reachable from the sites list's pending banner and from the Domains page; at most 5 claims may be pending per workspace.

Walking this flow against a real zone (and the wildcard-record trap that makes a correct setup look broken) is documented in docs/testing.md under "Live DNS verification".

Claim policy and the abandonment ledger

Because a live claim holds its whole subtree against every other workspace, abandoning one is metered. A claim that is canceled or expires without the system ever having seen a challenge-prefixed TXT record for it is recorded as an abandonment; once a workspace reaches its budget for a domain scope (the name's last two labels and everything beneath them, so cycling sibling names counts the same as cycling one), further claims there are refused until enough entries age out of the window. The refusal tells the member about their own history and when they may retry — it reveals nothing about anyone else.

A member who published the challenge record is exempt: proving zone control means cancel-and-retry stays free, and verifying a name clears the entries recorded at it and beneath it. Cancellations the console itself performs (for example when a verification workflow cannot start) are never counted, against either budget, and neither are the claims adopted for custom domains that predate the registry.

Operators can inspect live claims across all workspaces at Operator → Domains, see each claim's age, holder, placements and whether evidence was observed, force-release a squatted name, and read the effective policy values. All of the policy is per-deployment configuration:

Key	Default	Meaning
domains-claim-window	24h	Time to publish the TXT challenge
domains-pending-cap	5	Concurrent pending claims per workspace
domains-abandon-budget	3	Abandonments per scope before refusal (0 disables the ledger)
domains-abandon-window	168h	Rolling window abandonments are counted over
domains-scope-labels	2	Labels forming a scope root
domains-initiation-budget	10	New claims per workspace per 24h
domains-expiry-sweep-interval	15m	How often expired pending claims are swept

A pending claim is normally expired by its own verification workflow at the deadline. The expiry sweep is the backstop for claims whose workflow is gone — a worker crash, a terminated execution, an incompatible deploy — so a name is never held past its window by an accident of the console's own. It runs once at every boot regardless of whether Temporal is configured, and on the interval above wherever it is.

The Domains page (/domains) lists the workspace's claims with per-claim status and placement counts, hosts the DNS instructions, and releases claims that no longer hold any site. Name policy (reserved, blocked, and premium labels under shared domains, plus a built-in single-letter guard) is operator data in domains.name_rules; members see policy refusals as a plain "unavailable".

Serving authorization (/domains/ask)

The console answers the on-demand-TLS ask contract at GET /domains/ask?domain=<fqdn>: HTTP 200 authorizes certificate issuance for exactly that name (a servable placement exists in the registry), any other answer refuses it. Point Caddy at it:

{
    on_demand_tls {
        ask http://member-console:8080/domains/ask
    }
}

The endpoint is unauthenticated (TLS proxies send no credentials) — expose it to the proxy's network only. This replaces filesystem-based ask answerers (a domain is servable because the console says so, not because a directory exists). For deployments migrating off a legacy answerer, set domains-ask-fallback-url: names unknown to the registry are then forwarded to the legacy endpoint (strangler pattern) — a name the registry knows but has archived is refused locally, never resurrected by the fallback.

JSON API behavior: POST /api/fedwiki/sites with isCustomDomain: true enforces the entitlement gate (403 when not entitled) and then branches on the domain's claim state: unclaimed → 202 with the claim's DNS record details; a claim of the caller's own still pending → 400 "verification in progress"; a name inside the caller's active claim → the normal instant-create response. Conflicts with names held by others are reported only as "unavailable".

Plugin Source Code

• wiki-security-composable
• wiki-plugin-farmmanager
• wiki-plugin-useraccesstokens