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.
245 lines
9.5 KiB
Markdown
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.
|