Files
pages/docs/design/domain-namespace-federation.md
T
Anya Tokugawa c1175d389f Implement Knowledge City platform, organizer and DAV integration
Capture accumulated application, UI, CLI, regression tests and design documentation changes, including task project mapping and default CalDAV list naming.

Keep deployment data, backups, local credentials and build artifacts out of Git. Move the Compose enrollment token to an ignored local environment file.
2026-09-27 14:44:43 +09:00

245 lines
9.5 KiB
Markdown

# Domain Namespace and Federation
## Decisions
### Paths are Domain-local
A semantic path is identified by the pair:
```text
(domain_uuid, normalized_path)
```
Therefore `/handbook` in the Sales Domain and `/handbook` in the Engineering
Domain are different bindings and do not conflict.
The `paths` table uses a composite primary key:
```sql
CREATE TABLE paths_v2 (
domain_uuid TEXT NOT NULL,
path TEXT NOT NULL,
object_uuid TEXT NOT NULL,
created_at INTEGER NOT NULL,
is_primary INTEGER NOT NULL DEFAULT 0,
PRIMARY KEY (domain_uuid, path)
);
```
Existing rows are assigned to the current default Domain during migration.
All path reads and mutations must receive the request Domain UUID explicitly;
silently using a process-wide default is prohibited in request handlers.
### Objects are instance-global
Page Objects are not owned by a Domain. Their UUID is globally unique within
an instance, while a Domain owns bindings from its paths to Object UUIDs.
This preserves the MagicPage property:
```text
sales.example.test/guide ─┐
engineering.example.test/guide ├─> Page UUID 7a…
support.example.test/runbook ─┘
```
Revisions, immutable Documents, tags, and assets remain attached to Object
identity. Authorization may still restrict which Domains may bind or expose
an Object.
If stronger tenant isolation is later required, it belongs in policy and
storage-placement layers rather than by weakening UUID identity.
## Link addressing
Links have two forms:
- Same Domain: a root-relative semantic path such as `/guide`.
- Another Domain or another instance: an absolute URL containing the
destination FQDN, such as `https://engineering.example.test/guide`.
A cross-Domain link must not be stored as a bare `/guide`, because its meaning
would change with the request Host. Internally, a locally managed destination
may additionally retain `domain_uuid` for rename tracking, but its rendered
and exported form is still an absolute URL.
Object addresses (`uuid:`, `rev:`, and `asset:`) are local-instance addresses.
To address another instance they require an origin:
```text
https://engineering.example.test/o/uuid:…
https://engineering.example.test/o/rev:…
```
No request should transparently resolve a remote UUID against the local
SQLite database.
## Local and remote Domains
A configured FQDN does not by itself mean that a Domain is remote. One
PagesWiki instance may serve several local FQDNs. Domain placement therefore
must be explicit:
| placement | Meaning |
| --- | --- |
| `local` | This instance serves the Domain and owns its path namespace. |
| `remote` | The Domain is a catalog entry served by another instance. |
A remote Domain has no writable local path namespace. Its origin is derived
from its owning Campus FQDN and Domain host. Proxying remote content is not
implicit.
Implemented additive Domain fields:
```sql
placement TEXT NOT NULL DEFAULT 'local',
```
The URL scheme is transport policy and is not part of Campus or Domain
identity.
## Host resolution
Campus stores an FQDN without `http://` or `https://`. A Domain host resolves
as follows:
- empty host: the Campus FQDN;
- label without a dot: `label.<campus-fqdn>`;
- host containing a dot: the host is already an FQDN and is used unchanged.
Resolution is exact. An unknown request Host does not fall back to an
arbitrary default Domain. The Domain with an empty host is selected only when
the request Host equals its Campus FQDN.
## Campus authority modes
Campus configuration has an explicit authority mode:
| mode | Responsibility |
| --- | --- |
| `standalone` | All Campus and local Domain configuration is maintained on this instance. |
| `controller` | This instance is authoritative for a Campus topology and publishes desired configuration for managed instances. |
| `managed` | This instance accepts topology configuration from one external Campus controller. Local topology edits are disabled. |
Implemented additive Campus fields:
```sql
authority_mode TEXT NOT NULL DEFAULT 'standalone',
fqdn TEXT NOT NULL
```
The FQDN identifies the Campus in every authority mode. A controller Campus
may contain both local and remote Domain records. A managed instance stores
the controller Campus UUID, FQDN, and Domain UUIDs unchanged.
A Domain owned by a controller Campus also records `instance_fqdn`. This is
the concrete PagesWiki instance selected to serve that Domain. Controller
Domains require this value; standalone Domains default it to the Campus FQDN.
Managed instances treat Domain topology as read-only because those records
are reconciled from the controller.
Controller instances issue random enrollment tokens. Only a SHA-256 token
hash is stored by the controller, and the plaintext token is displayed once.
A joining instance presents the token, its FQDN, and the SHA-256 fingerprint
of its persistent Ed25519 public key.
The enrollment request includes that public key and a signature over the
normalized instance FQDN and enrollment token, so the controller verifies
proof-of-possession before recording the fingerprint.
Registration creates a pending instance. An administrator verifies its
fingerprint and approves it before it becomes available in the Domain
placement selector. The placement stores both the instance FQDN and
fingerprint. Re-registering the same FQDN with a different fingerprint
creates another pending identity and never inherits the old approval.
Pending instances receive Campus metadata but no Domain assignments. Revoking
an instance disables Domains assigned to that exact FQDN and fingerprint.
Enrollment tokens are individually revocable.
An external Campus is initialized with:
```text
pageswiki --add-external-campus CAMPUS_FQDN TOKEN
```
Development environments may explicitly select unencrypted transport with
`--add-external-campus-http CAMPUS_FQDN TOKEN`. HTTP is never selected
implicitly; the standard command always uses HTTPS.
Either enrollment form may be combined with `--no-default-campus` for a
dedicated managed instance. Its bootstrap standalone Campus and Domain remain
available while enrollment or approval is pending, and are removed
transactionally after the controller assigns the first enabled Domain.
`PAGESWIKI_INSTANCE_FQDN` supplies the joining instance FQDN. Enrollment
fetches and applies the controller Campus name, title, default language,
FQDN, and Domain snapshot. These fields are read-only locally. The token is
stored under the data directory with mode `0600`; the instance Ed25519 private
key is also stored with mode `0600`.
The Managed Campus Save action performs a Controller health probe without
making inherited fields editable. The management view displays a yellow-green
lamp after a successful probe and a red lamp after failure. The transport
(`https` or explicitly selected `http`) is retained from enrollment. Delete
detaches the Managed Campus, its Domain projections, Domain settings, and
Path bindings; Page Objects and immutable Revisions remain intact.
## Domain-scoped settings
Campus and Domain topology are instance-level administration. All other
settings use `(domain_uuid, key)` identity. This includes locale, timezone,
theme, home path, editor behavior, navigation, and
maintenance preferences. Legacy settings are assigned to the default Domain;
new Domains start with product defaults.
The displayed Wiki name is not an independent setting: it is always the
resolved Domain title. Recent Objects are selected by Domain Path bindings.
The administration view may inspect another Domain through an explicit
Campus and Domain selector.
## Configuration distribution
Federation is desired-state synchronization, not shared SQLite access.
The preferred flow is:
1. A controller publishes a versioned, signed Campus manifest.
2. A managed instance authenticates with its enrollment token and pulls the
manifest.
3. The instance validates schema version, Campus UUID, allowed hostnames, and
monotonic manifest revision.
4. It applies the manifest transactionally.
5. It reports the applied revision and validation errors.
Pulling avoids requiring inbound administrative access to every managed
instance. A push notification may trigger a pull, but does not contain
authoritative configuration itself.
The manifest controls topology and presentation defaults only. It must not
carry SQLite files, revisions, Documents, local secrets, OIDC client secrets,
Macaroon root keys, or instance-private signing keys.
## Security requirements
- Transport security policy is evaluated separately from the stored FQDN.
- Controller manifests require signature verification and replay protection.
- A managed instance is pinned to one Campus UUID and controller identity.
- Hostname changes require explicit allow-list validation.
- Local emergency override and last-known-good rollback are retained.
- Controller unavailability does not remove the last applied configuration.
- Remote links are rendered as external navigation, never server-side fetched
merely because a page contains the link.
## Migration order
1. [x] Add placement and authority metadata. Remote Domains have no local
writable Path namespace, and managed Campus topology is read-only.
2. [x] Rebuild `paths` with `(domain_uuid, path)` identity and assign legacy
rows to the default Domain.
3. [x] Thread Domain UUID through Store APIs, server handlers, recursive
operations, browser/tree queries, and the data CLI.
4. [x] Add cross-Domain absolute-link helpers and tests.
5. [x] Add signed controller manifests and managed-instance reconciliation.
Steps 2 and 3 shipped together. Adding `domain_uuid` while leaving unscoped
queries would have created cross-Domain data disclosure.