Files
pages/docs/design/domain-namespace-federation.md
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

9.5 KiB

Domain Namespace and Federation

Decisions

Paths are Domain-local

A semantic path is identified by the pair:

(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:

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:

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.

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:

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:

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:

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:

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. Add placement and authority metadata. Remote Domains have no local writable Path namespace, and managed Campus topology is read-only.
  2. Rebuild paths with (domain_uuid, path) identity and assign legacy rows to the default Domain.
  3. Thread Domain UUID through Store APIs, server handlers, recursive operations, browser/tree queries, and the data CLI.
  4. Add cross-Domain absolute-link helpers and tests.
  5. 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.