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

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, 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 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.

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

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, handling teardown during graceful shutdown.

Gating Requests by Hostname

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, ensuring that invalid hosts fail fast before reaching application routes.

Verifying TLS SANs

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, 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. 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}