stack/docs/federation/SETUP.md

Federated Tier Setup Guide

KBN-101 N-1 hold: This page is non-operative until KBN-101-08 activates a reviewed release. It does not authorize a deployment operation, initialization artifacts, implicit extension/schema/migration creation, raw CREATE, direct database initialization, or a Gateway against an unverified database. The prior direct-start wording is retired; its regression fixture is owned by KBN-101-06.

Activation-only sequence

The deployment control plane—not an operator shell or deployment lifecycle hook—performs this exact sequence after activation authorization:

1. External privileged bootstrap provisions the approved database/extension prerequisites.
2. The renderer installs the generation-pinned verified-TLS materials and roles.
3. The dedicated one-shot runner executes mosaic-db-migrator --run.
4. The same runner executes mosaic-db-migrator --verify, including readiness and the importer-target attestation where that route is enabled.
5. Only after successful verification may Gateway reach its independent verified-TLS Gateway readiness gate.

No step may be reordered, skipped, replaced by a raw SQL command, or delegated to an initialization hook. A missing extension, schema, migration, role, secret generation, or readiness proof is a failed control-plane precondition; it is not an instruction to start Compose, retry startup, or create anything directly.

N-1 status and required disposition

The current branch retains historical federation artifacts, but they are not a deployable procedure. docs/federation/TASKS.md records their shipped status only. KBN-101-02 retires runtime/init DDL; KBN-101-05 owns the renderer/deployment handoff; KBN-101-06 verifies the finite scanner and command matrix; and KBN-101-07 owns this operator route. A path named in an inventory, a historical-status label, or a normative requirement cannot suppress the semantic checks above.

Until the activation certificate names an exact release, use no database startup or recovery command from this document. For the produced importer interface, see the federated tier migration contract; it is likewise non-operative until activation.

Federation and Step-CA reference

Federation uses PostgreSQL 17 with pgvector, Valkey, and a shared configuration across multiple Gateway instances. Step-CA issues federation peer X.509 certificates whose custom OIDs carry a grant and subject identity. The following facts are reference material only; provisioning and secret delivery remain deployment-control-plane work under the activation sequence.

OID	Name	Description
1.3.6.1.4.1.99999.1	mosaic_grant_id	Federation grant UUID
1.3.6.1.4.1.99999.2	mosaic_subject_user_id	Subject user UUID

The internal arc 1.3.6.1.4.1.99999 is development-only. Before an externally reachable production deployment, register an IANA Private Enterprise Number and version the assignments. Each value is DER-encoded as an ASN.1 UTF8String containing the UUID.

The future activated Gateway requires STEP_CA_URL, STEP_CA_PROVISIONER_PASSWORD, STEP_CA_PROVISIONER_KEY_JSON, STEP_CA_ROOT_CERT_PATH, and BETTER_AUTH_SECRET through the reviewed secret mechanism. These names do not authorize shell exports, copied credential files, or an ad hoc service start.

Failure disposition

• A TLS, CA, SAN, role, runner, or readiness failure is a control-plane incident. Preserve only sanitized evidence and follow the approved rollback/repair record.
• A pgvector/extension failure is a failed external-bootstrap or runner precondition. Do not use direct extension SQL, init artifacts, or a startup retry as remediation.
• A port, container, or Valkey problem does not permit bypassing the activation sequence.
• Federation peer-key rotation remains deferred until its separately approved migration plan; do not rotate BETTER_AUTH_SECRET without that plan.