Files
pages/docs/design/federation-manifest-integrity.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

79 lines
4.3 KiB
Markdown

# Signed Campus manifest integrity
Implemented bounded single-writer-SQLite correction, 2026-09-14. This is not
controller HA, key rotation, multi-node metadata fencing or a new federation
trust protocol.
## Controller sequence allocation
`BuildSignedCampusManifest` canonicalizes the supplied Domain list by UUID,
rejects duplicate/missing identities and hashes the Campus plus filtered Domains.
A single SQLite `INSERT ... ON CONFLICT DO UPDATE ... RETURNING revision`
allocates the sequence against the current persisted hash:
- First content gets revision 1.
- Identical content retains its revision and timestamp.
- Changed content atomically increments the previous revision.
- Database errors and integer overflow fail, never resetting to revision 1.
The returned revision is signed with the existing Ed25519 identity. Concurrent
calls cannot sign different content with the same revision. Ordering-only changes
to the supplied Domain list do not churn revisions. This orders supplied
snapshots; it does **not** make the caller's earlier Campus/Domain reads a
transactional configuration snapshot. A controller-wide configuration generation
is still needed before claiming DR/HA or preventing an old caller snapshot from
being issued later with a newer revision.
## Managed-instance application
Verify signature, schema, Campus identity and Domain identity/hostname shape
before acquiring a database write reservation. Then, in one transaction:
1. Reserve SQLite's writer with a no-op update to the manifest-state table.
This works even for a first enrollment with no row; competing first pins
serialize instead of both reading an absent checkpoint.
2. Read the pinned fingerprint, applied revision and exact payload. Only
`sql.ErrNoRows` means an unpinned Campus. Other database errors fail closed.
3. Reject changed signing identity, lower revisions and a reused revision with
different payload. An exact duplicate succeeds without reapplying the snapshot.
4. Check authority ownership and apply the Campus/Domain snapshot using the
transaction-owned helper. Update placement/default locale as before and keep
`projectCampusAdminMembershipsTx` in this same transaction.
5. Persist the verified public key/fingerprint, revision and payload checkpoint;
commit all snapshot, inherited-permission and checkpoint changes together.
A checkpoint/projection/domain-write failure rolls everything back, including a
new trust pin. Retrying the same manifest after a rolled-back failure is safe.
No failed/replayed manifest silently retries with relaxed verification.
## Authority and legacy compatibility
A valid signature establishes a signing identity, not authority over every
local UUID. A managed snapshot cannot replace a standalone/controller Campus
or reparent a Domain UUID owned by another Campus. A new managed Campus and
updates to its own Domains remain supported, including initial pending enrollment
followed by an approved manifest that deploys Domains to the matching instance.
The legacy unsigned snapshot entry point still permits enrollment/resynchronizing
an **unpinned** managed Campus. It acquires the same writer reservation before
checking the pin. Once a signed checkpoint exists, unsigned fallback is rejected;
omitting a manifest can no longer bypass signing-identity/replay checks. Explicit
trust reset or key rotation needs a separate administrator-controlled workflow.
Initial enrollment remains trust-on-first-use through the configured controller
and enrollment transport; signing does not make an HTTP bootstrap resistant to
an active network attacker.
## Verification and remaining work
Tests cover 20 concurrent same/changed-content sequence allocations, canonical
ordering and overflow, 24 concurrent duplicate/out-of-order deliveries, competing
first keys/payloads, injected initial/updated-checkpoint and inherited-projection
failures, missing state tables, a one-connection pool, cross-authority collisions,
legacy-to-signed upgrade, approved placement/locale inheritance and unsigned
downgrade rejection. Existing managed enrollment/reconciliation tests remain in
the suite.
There are no new tables, shared keys or schema migrations. Key rotation, explicit
global authority transfer, independently versioned instance projections, bounded
configuration capture and DR/HA are follow-ups rather than implied guarantees.