Fediversity

Feature Specification: Component bind

Created: 2026-10-07

Status: Implemented

Input: Reconstructed from the code of core/components/hosting-provider/bind/ and the self-hosted provider of core/resources/dns/ at 093e68b6f, issues #200 and #1374.

User Scenarios & Testing (mandatory)

User Story 1 - Serve the group apex from its own nameservers (Priority: P1)

A hosting provider holds its apex itself. Each DNS node of the hosting-provider group runs an authoritative BIND server. One node is the primary of the apex, and the others transfer the zone from it as secondaries. At deploy time, the octodns-zone effect pushes the records of the nodes into the primary with the publisher key. The self-hosted provider of the dns resource points at the primary.

Why this priority: without it, no group name resolves and no node finds its peers.

Independent Test: a VM test pushes the zone into the primary, checks the transfer to the secondary and a refused transfer to another host, and resolves the group nodes from a peer.

Acceptance Scenarios:

  1. Given a primary, When the primary notifies a secondary, Then the secondary transfers the zone under its TSIG key, and a host that is not a listed secondary gets no transfer.
  2. Given a nameserver name inside the apex without a glue address, When the setup evaluates, Then the evaluation fails.

User Story 2 - Let operator deploys publish app names (Priority: P2)

An operator deploy publishes the address of its app under the apex of the provider, with the operator key. The key cannot take a provider name. It can also add operator domains to an RFC 9432 catalog zone, which the primary and the secondaries then serve.

Why this priority: a wrong grant lets an operator take over provider names.

Independent Test: a VM test publishes, repoints and releases an app name, checks the refusals of the operator key, and adds an operator domain to the catalog. A unit test checks the grant.

Acceptance Scenarios:

  1. Given the operator key, When it writes the apex, a reserved name, or a record that is not an address below the apex, Then the server refuses the update.
  2. Given a catalog on a primary, When the operator key adds a member, Then the primary seeds the member zone one time with its start of authority and nameservers, and all servers serve it.

User Story 3 - Sign the apex (Priority: P3)

A provider wants a signed apex, so that the registry can publish a delegation signer record. The primary signs the apex inline with one combined signing key from the KV store, and exports the delegation signer record and the public key for the registrar. The secondaries hold no key and serve the signed zone as they receive it (#1374).

Why this priority: DNSSEC is optional, but a broken key makes the apex fail validation everywhere.

Independent Test: VM tests of the key render and the key mint, and a unit test of the signing setup.

Acceptance Scenarios:

  1. Given signing is on and the KV store has no key, When the primary starts, Then it fails closed and writes no key.

Edge Cases

  • Two DNS nodes of the roster with the same label fail the evaluation. Without the group wiring, two nodes with the default label both seed themselves as the first nameserver, and the zone answers wrong.
  • The primary raises the seed serial above the serials of the secondaries before the server starts. It refreshes the seed only while the zone is provably unpublished.
  • The primary refuses a catalog member that is malformed, above the apex, above an admitted member, or below the catalog, and leaves it in the catalog. Of two overlapping members, the first wins. The zone data of a member that drops out stays on disk, and the zone serves it again when the member returns for the same deployment. When the member returns for another deployment, as fediversity-owner.ext names it, the primary removes the zone file and the journal before it loads the zone. A member that changes owner and stays in the catalog keeps its zone data.
  • An incumbent secondary that cannot use a TSIG key MAY get its transfer by address.
  • The backup reads the apex by a transfer under the publisher key, without the start of authority, the apex nameservers and the DNSSEC records, and fails when the transfer has no start of authority. The restore replaces each record set of the backup with a dynamic update, so the serial increases and the secondaries follow. It does not remove a record set that is not in the backup.

Requirements (mandatory)

Functional Requirements

  • FR-001: The component MUST serve the apex of the deployment and request a SPIFFE identity for the node.
  • FR-002: A node MUST act as primary when it has no primary to transfer from, and as secondary otherwise.
  • FR-003: A secondary MUST refuse all transfers. A primary MUST notify its listed secondaries and allow transfers only to them.
  • FR-004: The publisher key MUST be able to write any record under the apex. The operator key MUST be able to write only address records below the apex, never the apex or a reserved name, and only add members to the catalog, each with the addresses that may transfer it.
  • FR-005: The primary MUST refuse a catalog member that is malformed or overlaps a configured zone or an admitted member, and MUST process the catalog after start, at a short interval, and on each change.
  • FR-006: A challenge key MUST be able to write only the ACME challenge text record of its challenge zones.
  • FR-007: When signing is on, the primary MUST sign the apex inline with one combined signing key. The algorithm and the signature validity MUST be settings with safe defaults.
  • FR-008: The signing key MUST be in place with its roles before the server starts. Its preparation MUST fail closed.
  • FR-009: Each key render MUST wait for the secrets of the node, MUST fail after a bounded wait and never write an empty secret, and MUST run again when a secret, the signing key or the catalog changes.
  • FR-010: The node MUST open the DNS port on TCP and UDP. The server MUST NOT act as an open resolver.
  • FR-011: The evaluation MUST fail on an incoherent setup: a secondary that does not serve the apex, or that has a publisher or signing key; an operator key without a publisher key; a catalog on a primary that lacks either key; signing without a key source; two lanes that name the same zone; two grants that name the same key.
  • FR-012: The build MUST check the server configuration and all its zones without the real secrets, and the installed configuration MUST keep the real paths.
  • FR-013: A primary with a publisher key MUST stream the records of the apex as the server user to a bucket of garage. A secondary MUST NOT have a backup.

Key Entities

  • Apex zone: the zone of the apex on the primary, seeded with a low serial that stays above the secondaries.
  • Publisher key, operator key, challenge key: the TSIG keys for whole-zone writes, operator writes and ACME challenges.
  • Catalog zone: the RFC 9432 catalog of operator domains.
  • Signing key: the combined signing key of the apex, from the KV store (see openbao).
  • Offsite backup: the records of the apex, including the operator records. It does not hold the operator zones, the challenge zones or the DNSSEC keys.

Success Criteria (mandatory)

Measurable Outcomes

  • SC-001: The VM tests of the zone push and of the operator publish pass.
  • SC-002: The VM tests of the key render and the key mint pass.
  • SC-003: The unit tests of the setups for delegated zones, signing, the group zone, DNS routing, operator publish and the apex group pass.

Assumptions

  • The roster puts the component on each DNS node, with a distinct label and a real internal address.
  • The secrets reach the node as files through the vars plumbing and the KV store (see spire, openbao).
  • The setups decide which nodes resolve through the server (see network, 005).
  • The deployer reaches the primary on the DNS port.

Known Deviations

None.