# How mDNS Network Sharing in VoiceStudio Advertises Nodes and Gates Inbound Requests

> Learn how VoiceStudio uses mDNS network sharing to advertise nodes and gate inbound requests, ensuring secure access with hostname validation and TLS certificates.

- Repository: [Palash Debnath/VoiceStudio](https://github.com/debpalash/VoiceStudio)
- Tags: internals
- Published: 2026-09-13

---

**VoiceStudio uses the Python `zeroconf` library to multicast DNS-SD records that advertise worker nodes on the local network, while strictly validating inbound Host headers and TLS certificates against the advertised hostname to prevent unauthorized access.**

VoiceStudio implements **mDNS network sharing** to eliminate the need for centralized service discovery in local deployments. When a worker node starts, it publishes its availability via multicast DNS and simultaneously enforces runtime checks that gate every inbound request against the advertised identity. This architecture ensures that only peers resolving the mDNS record can successfully communicate with the worker's inbound endpoint.

## How VoiceStudio Advertises Nodes via mDNS

The advertising workflow separates the physical bind address from the logical identity announced on the network.

### Binding the Worker Socket

When the worker initializes its inbound service in [`backend/worker/inbound/service.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/worker/inbound/service.py), it first creates a listening socket bound to a configured address—often `0.0.0.0` for IPv4 or `::` for IPv6. This **bind host** determines which network interfaces accept connections, but it is never exposed directly to peers.

Instead, the system derives an **advertised host**, defaulting to loopback addresses (`127.0.0.1` or `::1`) unless overridden by user configuration. This distinction allows the worker to listen broadly while presenting a stable, routable identity to the local network.

### Publishing the DNS-SD Record

The [`backend/worker/inbound/listener.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/worker/inbound/listener.py) file contains the mDNS publication logic using the `zeroconf` library. The worker constructs a `ServiceInfo` object with the following properties:

- **Service Type**: `_voicestudio._tcp.local.`
- **Name**: Derived from the machine hostname
- **Address**: The IPv4 or IPv6 address of the advertised host
- **Port**: The listening port of the inbound HTTP/TLS endpoint

Once registered, the record multicasts onto the local link, enabling zero-configuration discovery by other VoiceStudio instances without requiring a DNS server or static configuration files.

## Gating Inbound Requests in VoiceStudio

Advertising the endpoint is only half of the security model; VoiceStudio gates every incoming connection through hostname validation layers defined in [`backend/worker/inbound/service.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/worker/inbound/service.py).

### Host Header Validation

Upon receiving an inbound HTTP request, the worker extracts the **Host** header (or the TLS SNI name for encrypted connections). The request handler compares this value against the set of **advertised hostnames** stored during initialization. If the header does not match an advertised hostname, the worker raises a `PermissionError` and terminates the connection before processing the body.

This check prevents clients from accidentally or maliciously targeting the raw bind address, ensuring the worker only responds to requests explicitly addressed to its mDNS-published identity.

### TLS Certificate Verification

When TLS is enabled, the gating mechanism extends to cryptographic validation. The worker loads its certificate and verifies that the **advertised host** appears in the Subject Alternative Name (SAN) list. If the certificate lacks a SAN entry matching the advertised hostname, VoiceStudio raises an `ssl.SSLError` and aborts the handshake.

This binds the TLS identity to the mDNS advertisement, preventing man-in-the-middle attacks that attempt to spoof the service endpoint.

## Implementation Examples

### Advertising the Service with Zeroconf

```python
from zeroconf import ServiceInfo, Zeroconf
import socket

def publish_worker_node(advertised_host: str, port: int):
    """Register this worker as _voicestudio._tcp.local."""
    service_type = "_voicestudio._tcp.local."
    service_name = f"{socket.gethostname()}.{service_type}"
    
    info = ServiceInfo(
        type_=service_type,
        name=service_name,
        addresses=[socket.inet_aton(advertised_host)],
        port=port,
        properties={},
    )
    
    zeroconf = Zeroconf()
    zeroconf.register_service(info)
    return zeroconf

```

The production implementation maintains this `Zeroconf` instance throughout the worker lifetime in [`backend/worker/inbound/listener.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/worker/inbound/listener.py), handling teardown during graceful shutdown.

### Gating Requests by Hostname

```python
def gate_inbound_request(request, advertised_hostnames: set):
    """Reject requests not targeting an advertised hostname."""
    if request.host not in advertised_hostnames:
        raise PermissionError(
            f"Host {request.host!r} not in advertised set {advertised_hostnames}"
        )
    return process_request(request)

```

This logic executes early in the request lifecycle within [`backend/worker/inbound/service.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/worker/inbound/service.py), ensuring that invalid hosts fail fast before reaching application routes.

### Verifying TLS SANs

```python
import ssl
from cryptography import x509

def verify_advertised_host(cert_pem: bytes, advertised_host: str):
    """Ensure the certificate covers the advertised mDNS name."""
    cert = x509.load_pem_x509_certificate(cert_pem)
    san = cert.extensions.get_extension_for_class(x509.SubjectAlternativeName)
    dns_names = san.value.get_values_for_type(x509.DNSName)
    
    if advertised_host not in dns_names:
        raise ssl.SSLError("Certificate SAN does not match advertised host")

```

As implemented in [`backend/worker/inbound/service.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/worker/inbound/service.py), this verification runs during TLS context initialization and on every incoming handshake when SNI is present.

## Summary

- **mDNS network sharing in VoiceStudio** relies on the `zeroconf` library to publish `_voicestudio._tcp.local.` records containing the advertised host and port.
- The **advertised host** (exposed via DNS-SD) is decoupled from the **bind host** (the actual socket address), allowing flexible network configurations while maintaining a stable service identity.
- Inbound requests are **gated** by validating the HTTP Host header or TLS SNI against the advertised hostname set; mismatches result in immediate connection termination.
- **TLS verification** further restricts connections by requiring the advertised hostname to appear in the certificate's SAN list, cryptographically binding the mDNS identity to the transport layer.

## Frequently Asked Questions

### What is the difference between the bind host and advertised host in VoiceStudio?

The bind host determines which local network interface and address the worker's socket listens on, often set to `0.0.0.0` to accept connections from any interface. The advertised host is the identity published via mDNS—the address other nodes use to reach this worker. Keeping them separate allows the worker to listen broadly while presenting a specific, stable endpoint (such as a loopback or container-assigned address) to the discovery layer.

### How does VoiceStudio prevent unauthorized inbound connections?

VoiceStudio implements a hostname-based gating mechanism in [`backend/worker/inbound/service.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/worker/inbound/service.py). Every inbound request must present a Host header or SNI name that matches one of the pre-configured advertised hostnames. If the presented hostname does not match the mDNS-published identity, the worker rejects the connection with a `PermissionError` before processing any payload, effectively blocking direct IP access or spoofed requests.

### What mDNS service type does VoiceStudio use for node advertisement?

VoiceStudio registers services under the type `_voicestudio._tcp.local.`. This DNS-SD service type is hardcoded in [`backend/worker/inbound/listener.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/worker/inbound/listener.py) and identifies TCP-based VoiceStudio workers on the local multicast domain. Peers browse for this specific type to discover available nodes dynamically without central coordination.

### Does VoiceStudio support IPv6 addresses in mDNS advertisements?

Yes. The `zeroconf` integration in [`backend/worker/inbound/listener.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/worker/inbound/listener.py) accepts both IPv4 and IPv6 addresses in the `ServiceInfo` addresses list. When the advertised host resolves to an IPv6 address, the code passes the appropriate `socket.inet_pton` result for `AF_INET6`, allowing dual-stack or IPv6-only deployments to participate in the local mDNS discovery network.