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

4.3 KiB

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.