Build the application.
Let the fabric carry trust.

Default-feature library nodes browse and advertise Korium nodes over bounded IPv4 and IPv6 mDNS. Local discovery can stop and restart while transport sessions remain alive. Wider networks can use operator-pinned identities and literal socket addresses, or explicitly opt into bounded public DNS bootstrap. Every discovered address remains a reachability hint; the connection still authenticates the remote node with signed transport validation, mTLS, DID binding, and PoW.

use korium::{MdnsMode, Node};

// Default: browse and advertise during construction.
let local_node = Node::builder().build().await?;

// Browse without advertising this node.
let browse_only = Node::builder()
    .mdns(false)
    .build()
    .await?;
browse_only.start_mdns(MdnsMode::Browse).await?;

// Stop multicast without disconnecting transport sessions, then restart
// in either supported mode.
browse_only.stop_mdns().await?;
browse_only
    .start_mdns(MdnsMode::BrowseAndAdvertise)
    .await?;

// Default is false; opt in independently of mDNS.
let public_node = Node::builder()
    .bootstrap(true)
    .build()
    .await?;

let node = Node::builder()
    .mdns(false)
    .build()
    .await?;

node.join(
    "0123...64-hex-characters...cdef",
    &["203.0.113.10:4433".to_string()],
).await?;

node.connect("0123...64-hex-characters...cdef").await?;

# /etc/korium/seeds.toml
[seed.primary]
identity = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
endpoints = ["203.0.113.10:4433", "[2001:db8::10]:4433"]
required = true

# No seed file is loaded unless its path is explicit.
korium --seeds-file /etc/korium/seeds.toml

# A repeatable best-effort alternative:
korium --join 203.0.113.10:4433/0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

# Or opt into bounded public DNS hints:
korium --bootstrap

stop_mdns().await cooperatively waits for the active standalone or combined mDNS listener to release its sockets, without shutting down transport sessions. A later start_mdns may select browse-only or browse-and-advertise mode. Stopping a combined DNS/mDNS listener also stops its regular-DNS socket, so restart the combined listener when both services are required.

Use PLAIN request streams for bounded request/response work. Requests are capped at 64 KiB; callers always provide their own end-to-end timeout.

use std::time::Duration;

let reply = node.send(
    &remote_identity_hex,
    br#"{"op":"status"}"#.to_vec(),
    Duration::from_secs(5),
).await?;

let mut requests = node.incoming_requests().await?;

while let Some((from, pubkey, body, ctx, reply)) = requests.recv().await {
    // Inspect ctx and authorize before changing state.
    let response = handle(from, pubkey, body, ctx).await;
    let _ = reply.send(response);
}

incoming_requests is take-once and is the only request-serving API; the synchronous set_request_handler shortcut was removed in 0.8.28. recv() yields the five-field IncomingRequest tuple; inspect the context before handling the body, then send the response through the returned channel. Own the receiving task, and keep draining it.

Use RAW streams for custom framing, file transfer, interactive sessions, or protocols that need full duplex. Korium authenticates and bounds stream admission; your protocol owns framing and payload limits.

use tokio::io::{AsyncReadExt, AsyncWriteExt};

// Caller
let (mut send, mut recv) = node.open_stream(&remote_identity_hex).await?;
send.write_all(b"hello").await?;
send.finish()?;
let reply = recv.read_to_end(64 * 1024).await?;

// Receiver: take this once, then keep draining it.
let mut incoming = node.incoming_streams().await?;
while let Some((from, mut stream)) = incoming.recv().await {
    if stream.kind() != IncomingStreamKind::Raw { continue; }
    let body = stream.recv.read_to_end(64 * 1024).await?;
    stream.send.write_all(&process(from, body)).await?;
    stream.send.shutdown().await?;
}

Use GossipSub for many-to-many events where duplicate, delayed, or reordered delivery is acceptable. Messages are signed and replay-bounded; publication does not grant application membership.

node.subscribe("events/alerts").await?;
let mut messages = node.messages().await?; // take once

node.publish(
    "events/alerts",
    b"system update available".to_vec(),
).await?;

while let Some(message) = messages.recv().await {
    consume(message).await?;
}

Service URNs stay stable while node identities rotate. Exact-service announcements publish signed, expiring liveness; optional namespace memberships provide a separate, bounded directory of service names. Neither lookup grants authority.

let service = "urn:korium:acme/payments";

// Serving node
node.announce_service(service).await?;

// Consumer
for (identity, addresses) in node.lookup_service_endpoints(service).await? {
    println!("{} at {:?}", identity.to_hex(), addresses);
}

use korium::NamespaceDiscoveryTrust;

let discovery = NamespaceDiscoveryTrust::new(
    "urn:korium:acme",
    namespace_discovery_root,
)?;

for member in node.lookup_namespace(&discovery).await? {
    println!("{} expires at {}", member.service_urn, member.expires_unix_seconds);
    let instances = node.lookup_service(&member.service_urn).await?;
    // Authenticate each instance; membership is discovery evidence only.
    println!("{} live candidates", instances.len());
}

NamespaceDiscoveryTrust is request-scoped and may accept a primary plus bounded retiring discovery root. There is no public announce_namespace operation: a service receives a signed NamespaceServiceMembershipSpec through with_namespace_service_membership, then announce_service publishes the membership beside exact service liveness.

Publish exact resources or bounded parent prefixes under a namespace or service URN. Consumers always query an exact resource and receive bounded fresh candidates.

use korium::ResourceSelector;

let context = "urn:korium:acme/storage";

node.announce_resource(
    context,
    ResourceSelector::prefix("repos/project"),
).await?;

if let Some(found) = node
    .lookup_resource(context, "repos/project/readme")
    .await?
{
    for candidate in found.candidates {
        node.connect(&candidate.identity.to_hex()).await?;
    }
}

• Resource strings are canonical printable ASCII and capped at 1024 bytes.
• No list-all, wildcard, regex, glob, or prefix-enumeration lookup exists.
• Use opaque, keyed, or tenant-scoped names when discovery subjects are sensitive.
• unannounce_resource stops republishing; old records expire naturally.

TUNNEL lets a local TCP client reach an in-process stream handler on a destination node. The entry tries native TLS 1.3 mTLS/TCP first and falls back to a QUIC TUNNEL stream through the fabric.

use std::net::SocketAddr;
use korium::{IncomingStreamKind, Node};

// Destination: enable the exit and consume Tunnel streams.
let destination = Node::builder().tunnel().build().await?;
let mut incoming = destination.incoming_streams().await?;

// Entry: bind a local port for the legacy TCP client.
let entry = Node::new().await?;
let listen: SocketAddr = "127.0.0.1:13306".parse()?;
let (handle, shutdown) = entry
    .start_tunnel_entry(listen, &destination_identity_hex)
    .await?;

// Later: stop accepting and await clean termination.
shutdown.notify_one();
handle.await??;

The regular DNS shim lets DNS-native workloads consume Korium identity and service discovery without embedding the Rust API. It is an authoritative, non-recursive UDP listener backed by the node's bounded DHT lookups—not a replacement for CoreDNS, a general-purpose resolver, or Korium's separate local-node mDNS service.

# Default binary: CLI, regular DNS, mDNS, and authz.
cargo build --release --bin korium --features cli,dns,mdns

# Regular DNS defaults to loopback:5353 when --dns is omitted.
# CLI mDNS and public DNS bootstrap are separate explicit choices.
korium \
  --port 4433 \
  --dns 127.0.0.1:5353 \
  --mdns advertise \
  --bootstrap \
  --identity-file /var/lib/korium/identity

use std::net::SocketAddr;
use korium::MdnsMode;

// Reserve one lifecycle for separate regular-DNS and mDNS sockets.
let node = Node::builder().mdns(false).build().await?;

// On Unix: regular DNS on loopback:5353 plus local browsing/advertising.
let local_dns = node
    .start_default_dns_listener_with_mdns(MdnsMode::BrowseAndAdvertise)
    .await?;

// A regular-DNS-only gateway may use an explicit controlled address.
let gateway = Node::builder().mdns(false).build().await?;
let bind: SocketAddr = "0.0.0.0:5353".parse()?;
let gateway_dns = gateway.start_dns_listener_at(bind).await?;

Query service URNs

A single-segment service URN maps deterministically to a DNS owner. For example, urn:korium:acme.example/payments becomes _korium._udp.u1.acme.example._svc.payments.svc.

# Ask the Kubernetes Service explicitly; do not replace cluster DNS.
dig @korium-dns.platform.svc.cluster.local \
  _korium._udp.u1.acme.example._svc.payments.svc. SRV

dig @korium-dns.platform.svc.cluster.local \
  _korium._udp.u1.acme.example._svc.payments.svc. SVCB

Kubernetes gateway

The following skeleton keeps the Korium identity on persistent storage and publishes DNS only through an internal UDP Service. Replace the image and storage class for your environment.

apiVersion: v1
kind: Service
metadata:
  name: korium-dns
  namespace: platform
spec:
  selector:
    app: korium-dns
  ports:
    - name: dns
      port: 53
      targetPort: dns
      protocol: UDP
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: korium-dns
  namespace: platform
spec:
  serviceName: korium-dns
  replicas: 1
  selector:
    matchLabels:
      app: korium-dns
  template:
    metadata:
      labels:
        app: korium-dns
    spec:
      securityContext:
        runAsNonRoot: true
        runAsUser: 10001
        runAsGroup: 10001
        fsGroup: 10001
        fsGroupChangePolicy: OnRootMismatch
      containers:
        - name: korium
          image: registry.example/korium:0.8.38
          args:
            - --port
            - "4433"
            - --dns
            - 0.0.0.0:5353
            - --join
            - 203.0.113.10:4433/0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
            - --identity-file
            - /var/lib/korium/identity
          ports:
            - name: fabric
              containerPort: 4433
              protocol: UDP
            - name: dns
              containerPort: 5353
              protocol: UDP
          securityContext:
            allowPrivilegeEscalation: false
            readOnlyRootFilesystem: true
            capabilities:
              drop: ["ALL"]
          volumeMounts:
            - name: identity
              mountPath: /var/lib/korium
  volumeClaimTemplates:
    - metadata:
        name: identity
      spec:
        accessModes: ["ReadWriteOnce"]
        resources:
          requests:
            storage: 1Gi

• External DNS exposure requires an explicit non-loopback bind plus source-spoofing and rate controls.
• The listener is UDP-only, authoritative, non-recursive, and accepts exactly one IN-class question per packet.
• Regular DNS and mDNS reject oversized headers, malformed structure, unsupported record surfaces, and wrong destination or source-port semantics before deeper processing.
• Responses are capped at 1232 bytes, in-flight queries at 64, and query work at 2 seconds.
• Records use a 15-second TTL; service lookup gets a bounded 1.5-second DHT budget.
• DNS output remains discovery evidence, not service authority or authorization. Korium mTLS and application policy still apply.
• Persist the identity file with mode 0600. A new identity changes the gateway's node identity and requires new PoW.

A service-authorized node presents a bounded, offline-authored chain from a configured NamespaceAuthorityTrust to one exact service URN, an immutable service policy, a policy-bound node issuer, and the node's terminal mTLS key. Build fails if the chain is malformed, outside its scope or validity, changes policy, or binds a different keypair.

use korium::{
    authoring::{
        ExactServiceDelegationSpec, LeaseTerms, NamespaceAuthorityChain,
        NamespaceAuthorityKey, NamespaceAuthorityScope,
        PolicyBoundNodeIssuerGrantSpec, PolicyBoundNodeIssuerKey,
        ServiceAuthorityBundleSpec,
    },
    NamespaceAuthorityTrust,
};

let namespace_trust = NamespaceAuthorityTrust::new(
    "urn:korium:acme",
    namespace_root.public_bytes(),
    4,
)?;
let exact_service_chain = NamespaceAuthorityChain::root(&namespace_trust)?
    .delegate_exact_service(
        &namespace_trust,
        &namespace_root,
        ExactServiceDelegationSpec {
            child_public_key: service_issuer.public_bytes(),
            scope: NamespaceAuthorityScope::exact_service(
                "urn:korium:acme/payments",
            )?,
            terms: service_issuer_terms,
            nonce: exact_service_nonce,
        },
    )?;

let node_issuer_grant = PolicyBoundNodeIssuerGrantSpec {
    namespace_trust: namespace_trust.clone(),
    exact_service_chain,
    node_issuer_public_key: node_issuer.public_bytes(),
    node_issuer_terms,
    node_issuer_nonce,
    policy_terms,
    allow_sources,
    grant_issuers,
}
.sign(&service_issuer)?;

let signed_bundle = ServiceAuthorityBundleSpec {
    namespace_trust: namespace_trust.clone(),
    node_issuer_grant,
    node_public_key: node_key.public_key_bytes(),
    node_terms,
    node_nonce,
}
.sign(&node_issuer)?;

The root, subtree, and exact-service issuer keys are authoring-only. The policy-bound node issuer belongs in an isolated recovery or control-plane holder; it can issue terminal bindings only for the committed service policy.

Enable Korium's authoring feature in the offline control-plane tool that creates these artifacts; ordinary serving nodes need only the signed bundle and configured namespace roots.

Every entry in allow_sources must belong to an explicitly configured namespace authority. Namespace equality and discovery membership never create network trust; configure one NamespaceAuthorityTrust for each namespace that may authorize a source.

let service = Node::builder()
    .contact(persisted_keypair, persisted_pow)
    .with_service_authority(vec![namespace_trust], signed_bundle)
    .build()
    .await?;

assert_eq!(service.service_urn(), Some("urn:korium:acme/payments"));

let mut requests = service.incoming_requests().await?;
while let Some((_from, _pubkey, body, ctx, reply)) = requests.recv().await {
    let request = parse_request(body)?;
    let grant = service.verify_action(
        &ctx,
        request.bearer_token.as_deref(),
        "payment.capture",
        &format!("payments/{}", request.payment_id),
    )?;

    let _ = reply.send(capture(request, grant).await?);
}

Build bounded issuer links

Use subtree delegation when one control plane should administer a bounded namespace or service subtree. Use exact-service delegation for a single service. Scope is parsed by URN segments, never by globs or byte prefixes, and every link carries its own validity, nonce, predecessor digest, signature domain, and remaining depth.

use korium::authoring::{
    NamespaceSubtreeDelegationSpec, NamespaceAuthorityScope,
};

let subtree_chain = NamespaceAuthorityChain::root(&namespace_trust)?
    .delegate_subtree(
        &namespace_trust,
        &namespace_root,
        NamespaceSubtreeDelegationSpec {
            child_public_key: platform_issuer.public_bytes(),
            scope: NamespaceAuthorityScope::subtree(
                "urn:korium:acme/platform",
            )?,
            terms: subtree_terms,
            nonce: subtree_nonce,
            remaining_depth: 1,
        },
    )?;

An exact-service issuer can create the policy-bound node-issuer grant, but the grant commits the exact service URN, allow_sources, and grant_issuers. The node issuer cannot widen scope or change policy.

Redeploy with a fresh terminal binding

Keep the stable service URN and the authoring-only issuer chain. The isolated policy-bound node issuer can sign a new short-lived ServiceAuthorityBundleSpec for a replacement or overlapping replica DID without entering the serving node.

let replacement_bundle = ServiceAuthorityBundleSpec {
    namespace_trust: namespace_trust.clone(),
    node_issuer_grant: node_issuer_grant.clone(),
    node_public_key: replacement_key.public_key_bytes(),
    node_terms: LeaseTerms {
        not_before_unix_seconds: now,
        expires_unix_seconds: now + 3_600,
    },
    node_nonce: replacement_nonce,
}
.sign(&node_issuer)?;

let replacement = Node::builder()
    .contact(replacement_key, replacement_pow)
    .with_service_authority(vec![namespace_trust], replacement_bundle)
    .build()
    .await?;

• Terminal node bindings are short-lived and capped by the enclosing chain, policy, node issuer, and certificate validity.
• Overlapping replacement or replica DIDs are valid while each has terminal-key possession and an unexpired chain.
• A node-issuer compromise is bounded by its lease; it cannot change the service URN, source allowlist, or grant-issuer policy.
• Replacing a compromised namespace or delegated issuer is a deployment-configured hard trust reset. Stop renewal, replace the pinned trust and affected chains, and terminate local sessions when immediate containment is required.
• There is no live service-root rollover, epoch, dual-root state, or implicit authority checkpoint. Namespace discovery root rotation remains independent and affects only lookup_namespace.