Skip to content

8. Signed Namespaces

Date: 2026-03-30

Status

Accepted

Context

Data Mesher currently requires every file name to be explicitly listed in the files config section, mapped to a list of authorized ED25519 signing keys. This works well for a known set of files (e.g. DNS zone files), but prevents use cases where nodes need to publish files dynamically without prior configuration changes.

For example, a decentralized document publishing system would need each node to publish files under its own namespace without pre-registering every file name in the cluster configuration. Nodes should be able to join the mesh and start publishing immediately in some use-cases.

Data Mesher already has the infrastructure to solve this. Each node has an ED25519 identity keypair, and the network key signs each node's public key into a certificate. This certificate infrastructure is currently used only for TLS mutual authentication between nodes.

The core insight is that authorization can be derived from the file path itself: if a file's path embeds the signer's public key, and the signer holds a valid certificate signed by the network key, any node can verify both identity and network membership -- no per-file allowlist needed.

Decision

Certificate format

Certificates contain a peer name, the peer's public key, a validity period, and a signature from the network key:

1
[pubkey (32)] [not_before (8)] [not_after (8)] [name (64, null-padded)] [signature (64)]

Total: 176 bytes fixed. The signature covers all preceding fields.

The network key holder is responsible for ensuring peer name uniqueness within a network when signing certificates.

Namespace path format

Files under a signed namespace use paths of the form:

1
{namespace}/{url_encoded_public_key}

Where {url_encoded_public_key} is the signer's ED25519 public key encoded using unpadded base64url (RFC 4648). Namespace names must match ^[a-z0-9_]{1,255}$.

This embeds the authorized signer directly in the path, making authorization self-evident from the file name alone.

Authorization model

A namespaces config field is added to each network alongside the existing files section:

1
2
3
4
5
6
[network]
id = "..."
namespaces = ["dns", "web"]

[network.files]
"dns/cnames" = ["P6AE0lukf9_qmVglYrGPNYo5ZnpFrnqLeAzlCZF0lTk"]

When a file is submitted, authorization proceeds as follows:

  1. Static files (files config) are checked first via exact name match
  2. If no static match, the name is parsed as {namespace}/{pubkey}
  3. The namespace must be in the network's configured namespaces list
  4. The signer's key (SignedBy) must match the public key in the path
  5. A valid certificate must be attached to the signature
  6. The certificate's IdentityKey must equal SignedBy
  7. The certificate must be signed by the network key
  8. The signature timestamp must fall within the certificate's validity period

Static file authorization (files) takes precedence and does not require a certificate.

Certificate distribution

When a node publishes a file under a signed namespace, its certificate is included in the HTTP request headers (X-Certificate) alongside the file signature. This allows any receiving node to verify that the signer is a legitimate network member, even if the signature was relayed transitively through other nodes.

Verification uses the network's public key (network.id).

Replication model

Signed namespace files replicate exactly like static file entries: signatures are gossiped and file content is auto-downloaded to all nodes. There is no difference in replication behavior -- signed namespaces only change how authorization is determined.

Examples

Given a network with namespaces = ["dns", "web"] and a node whose public key URL-encodes to DSKLzYkc0YIICBQ7nisbsCVkCvD_iL8qAZxKax1bk10:

  • dns/DSKLzYkc0YIICBQ7nisbsCVkCvD_iL8qAZxKax1bk10 -- accepted (namespace configured, key matches signer, valid certificate signed by network key)
  • web/DSKLzYkc0YIICBQ7nisbsCVkCvD_iL8qAZxKax1bk10 -- accepted (different namespace, same node)
  • dns/x4Fz9kR2mNpVwLjYhQeXs7bAuGcC_tD3iO6PaS8Wnv0 -- rejected (signer key does not match key in path)
  • dns/DSKLzYkc0YIICBQ7nisbsCVkCvD_iL8qAZxKax1bk10 without certificate -- rejected (certificate required)
  • dns/DSKLzYkc0YIICBQ7nisbsCVkCvD_iL8qAZxKax1bk10 with expired certificate -- rejected (signature time outside certificate validity)
  • cache/DSKLzYkc0YIICBQ7nisbsCVkCvD_iL8qAZxKax1bk10 -- rejected (namespace not configured)
  • any file signed with a certificate not signed by the network key -- rejected

Security considerations

No impersonation: A node can only write to paths containing its own public key. Since the path key must match SignedBy and the certificate's IdentityKey, a node cannot publish under another node's namespace.

One key per node: Since signed namespaces use the node's identity key (one per node, certified by the network key), a node cannot generate additional keys to claim multiple namespaces within the same prefix.

Network key as trust boundary: Only nodes with a valid certificate signed by the network key can publish under signed namespaces. The network private key is held by the cluster administrator.

Certificate expiry as revocation: Certificates have a validity period. A node whose certificate is not renewed is automatically excluded from publishing. This provides a natural revocation mechanism without requiring an explicit revocation list. In future, a separate revocation list can be implemented to revoke in a more timely fashion.

Cross-network isolation: Each network has its own key and namespace configuration. A certificate signed by one network key cannot authorize publishing to a different network's namespaces.

Consequences

Any application built on Data Mesher can define a namespace for dynamic, per-node file publishing. Nodes publish under their own namespace using their existing identity key -- no additional key management is needed.

Unlike the files model, which requires listing every authorized key per file name, signed namespaces allow nodes to come and go without redeploying configuration. A new node only needs a certificate signed by the network key to start publishing. No cluster-wide configuration update is required.

The existing files model is unchanged. Networks that do not use signed namespaces see no change in behavior.

The namespaces list structure is intentionally simple. Per-namespace options can be added later without changing the core authorization mechanism.