Build the application.
Let the fabric carry trust.

With the opt-in mdns feature, library nodes can explicitly start bounded IPv4 and IPv6 mDNS browsing or advertising. Local discovery can stop and restart while transport sessions remain alive. Wider networks use operator-pinned identities and literal socket addresses. Every discovered address remains a reachability hint; the connection still authenticates the remote node with signed transport validation, mTLS, DID binding, and PoW.

Signed contacts contain identity and authority, never network addresses. Transport reuses authenticated paths, probes explicit endpoints, or requests a consented introduction from the node that referred an identity. Introductions carry public endpoints only: nodes behind one NAT without hairpinning need mDNS or explicit local endpoints for a direct path; otherwise they stay relayed. Unsuccessful introductions leave discovery incomplete and grant no authority.

use korium::{MdnsMode, Node};

// Add features = ["mdns"] to the tagged korium dependency above.
let node = Node::builder().build().await?;
node.start_mdns(MdnsMode::Browse).await?;

// Stop local discovery without disconnecting transport sessions.
node.stop_mdns().await?;
node.start_mdns(MdnsMode::BrowseAndAdvertise).await?;

use std::time::Duration;

let node = Node::builder()
    .seed_route_validation_timeout(Duration::from_secs(2))
    .build()
    .await?;

Seed path validation defaults to two seconds, must be greater than zero, and is capped at 30 seconds. The budget is shared across the seed's endpoint hints and also applies to mDNS candidates; it does not set the subsequent discovery or QUIC handshake timeout.

use korium::{Destination, Identity};
use std::net::SocketAddr;

let identity = Identity::from_hex(
    "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
)?;
let address: SocketAddr = "203.0.113.10:4433".parse()?;

let node = Node::builder().build().await?;
node.join(identity, &[address]).await?;
node.connect(&Destination::peer(identity)?).await?;

join requires one to eight literal SocketAddr endpoints. Supply endpoints explicitly; signed contacts carry identity and authority, never network addresses.

# /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

Replace these documentation-only identities and addresses with your own. For public-network introduction, the tagged seeds.toml supplies a public seed identity and literal IPv4/IPv6 endpoints; select the saved file explicitly. Missing or invalid selected files fail startup. Required identities must all validate; optional alternatives warn on failure. Up to 64 seed identities are accepted, but only the eight most recently validated are retained as pinned lookup fallbacks. Seed hints grant no admission or application authority.

stop_mdns().await cooperatively waits for the active mDNS listener to release its sockets, without shutting down transport sessions. A later start_mdns may select browse-only or browse-and-advertise mode. DNS and mDNS are mutually exclusive per node. To switch, await the active service’s stop method before starting the other adapter.

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 korium::Destination;
use std::time::Duration;

let destination: Destination = remote_identity_hex.parse()?;
let reply = node.send(
    &destination,
    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. 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};
use korium::IncomingStreamKind;

// Caller
let destination: korium::Destination = remote_identity_hex.parse()?;
let (mut send, mut recv) = node.open_stream(&destination).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 mut body = Vec::new();
    (&mut stream.recv).take(64 * 1024 + 1).read_to_end(&mut body).await?;
    anyhow::ensure!(body.len() <= 64 * 1024, "request too large");
    stream.send.write_all(&process(from, body)).await?;
    stream.send.shutdown().await?;
}

Outgoing streams return korium::SendStream and korium::RecvStream. Use Tokio's AsyncWriteExt and AsyncReadExt; reads return zero at stream end. The stream APIs also provide finish() and bounded read_to_end(limit). Failures use StreamError and ConnectionError. End accepted writers with shutdown().await; dropping one without shutdown resets it.

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

let receipt = node.publish(
    "events/alerts",
    b"system update available".to_vec(),
).await?;
println!("queued: {}, rejected: {}", receipt.queued_peers, receipt.rejected_peers);

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

PublishReceipt reports the message ID and local queued/rejected counts. Zero or partial admission is explicit; a receipt is not a delivery acknowledgement and schedules no application retry.

Exact service DID URLs stay stable across node replacement. Obtain the complete identifier and authority commitment through trusted configuration. A service node may hold up to 64 independently signed bindings under one canonical authority root, each with its own source and issuer policy.

use korium::Destination;

// service_id is a trusted, complete did:korium:service:… URL.
node.announce_service(&service_id).await?;
let providers = caller.lookup_service(&service_id).await?;
if !providers.complete || providers.truncated {
    eprintln!("service lookup is partial");
}
for contact in providers.contacts {
    println!("verified provider {}", contact.identity.to_hex());
}
let destination = Destination::service(&service_id)?;
let stream = caller.open_stream(&destination).await?;

Service IDs use did:korium:service:z<authority-commitment>:<label>/[path/]service, capped at 192 bytes and 32 path segments including the service. The readable label grants no DNS ownership. There is no namespace directory, prefix lookup, wildcard, scan, or cursor API. Lookup returns ProviderLookup { contacts, complete, truncated }, with at most 16 contacts from 256 verified candidates. Incomplete discovery is distinct from no providers. A selected provider failure ends the operation without fallback.

Service and resource records replicate only within their authority partition. Scoped contacts carry signed replica entitlement. Node routing positions derive from PoW, while final DHT ordering remains XOR-distance based. Hashing is not confidentiality: scoped contacts expose exact entitlement identifiers and authority evidence.

Use typed destinations and handle failures

Parse identity hex into Identity, seed endpoints into SocketAddr, and node or service targets into Destination at application boundaries.

use korium::{Destination, Identity};

let identity = Identity::from_hex(&peer_identity_hex)?;
let destination = Destination::service_on(identity, &service_id)?;
node.connect(&destination).await?;
let response = node.send(&destination, request.clone(), timeout).await?;

let discovered = Destination::service(&service_id)?;
let response = node.send(&discovered, request, timeout).await?;

• Methods including lookup_contact, join, and is_connected take Identity values; join takes SocketAddr values.
• Queries return Result<_, NodeError>. Distinguish NotFound, IncompleteDiscovery, NotConfigured, TimedOut, and subsystem or transport errors when policy depends on the failure. Discovery actor failure is NodeError::Unavailable(Subsystem::Discovery).
• lookup_service and lookup_resource return ProviderLookup. Check both complete and truncated before treating results as complete.
• Caller request timeout covers discovery, connection, stream setup, and response reading. A timeout does not establish non-delivery; Korium does not replay application requests.
• Destination::service_on(identity, service_id) pins one replica and verifies that peer’s exact live binding. It performs no provider selection or fallback.

Connection and raw-stream setup, including resource destinations, contact lookup, and join have a 30-second total budget. Explicit resource lookup has 15 seconds; explicit service lookup has 60 seconds; state queries have seven seconds. Implicit provider selection inside a request, connection, stream, or tunnel setup also shares that operation's own deadline. A join remains successful if its optional self-contact publication fails. Incomplete or truncated results are distinct from an empty complete result. A remote refusal of the exact service-binding query returns NodeError::Refused; generic stream rejection is a stream failure, not proof of a service mismatch.

An application-owned ResourceDescriptor pairs one exact service with an opaque resource ID. A separately trusted placement authority signs where that object may be advertised. Service authority alone cannot authorize resource placement.

// Resource discovery and issuance use the default authz feature.
use korium::{Destination, ResourceDescriptor, authority::PlacementAuthorityKey};

let resource = ResourceDescriptor::new(&service_id, "repos/project/readme")?;
// Issue offline; provision the trusted public key to callers independently.
let owner = PlacementAuthorityKey::generate();
let placement = owner.authorize_placement(
    resource.clone(), provider.peer_endpoint().pubkey, placement_terms,
)?;
provider.announce_resource(&placement).await?;
let found = caller.lookup_resource(&resource, &owner.public_bytes()).await?;
if !found.complete || found.truncated {
    eprintln!("resource lookup is partial");
}
for contact in found.contacts {
    println!("verified provider {}", contact.identity.to_hex());
}
let destination = Destination::resource(&resource, &owner.public_bytes())?;
let stream = caller.open_stream(&destination).await?;

• Resource IDs are canonical printable ASCII and capped at 192 bytes. Descriptors use bounded KRR1 encoding and do not authenticate their own mapping.
• Placements bind the descriptor, provider key, and a validity interval of at most one hour. The provider also needs the exact service binding.
• At most 4096 active resource announcements share a node’s capacity. Lookup returns contacts, complete, and truncated; completion never proves every provider was found.
• Resource lookup is exact. The selected provider is used directly without a service-only lookup or silent failover.
• Destination::resource validates the trusted placement key before network work. Use it with connect, send, open_stream, tunnel entry methods, or their explicit-source variants. Resource destinations have no text form and cannot be constructed by parsing a string.
• unannounce_resource(&resource, &authority_key) stops renewal; remote records expire normally. Withdraw an active placement before replacing it.
• Descriptors and placements are visible to DHT participants. The receiving application must verify an invocation grant before accessing the object.

TUNNEL lets a local TCP client reach an in-process stream handler on a destination node. Every tunnel uses a QUIC TUNNEL stream through the fabric. Enabling an exit opens no remote TCP listener; only the local entry listens for TCP clients.

use std::net::SocketAddr;
use korium::{Destination, IncomingStreamKind, Node};
use tokio::io::{AsyncReadExt, AsyncWriteExt};

// Destination: enable the exit and consume Tunnel streams.
let destination = Node::builder()
    .bind_addr("127.0.0.1:0".parse()?)
    .admit_authenticated_peers()
    .tunnel()
    .build().await?;
let mut incoming = destination.incoming_streams().await?;
let destination_identity_hex = destination.identity();
let handler = tokio::spawn(async move {
    while let Some((_from, mut stream)) = incoming.recv().await {
        if stream.kind() != IncomingStreamKind::Tunnel { continue; }
        let mut body = Vec::new();
        (&mut stream.recv).take(64 * 1024 + 1).read_to_end(&mut body).await?;
        anyhow::ensure!(body.len() <= 64 * 1024, "request too large");
        stream.send.write_all(&body).await?;
        stream.send.shutdown().await?;
    }
    Ok::<(), anyhow::Error>(())
});

// Entry: bind a local port for the legacy TCP client.
let entry = Node::builder().bind_addr("127.0.0.1:0".parse()?).build().await?;
entry.join(destination.peer_identity(), &[destination.bind_addr()]).await?;
let listen: SocketAddr = "127.0.0.1:13306".parse()?;
let target: Destination = destination_identity_hex.parse()?;
let listener = entry
    .start_tunnel_entry(listen, &target)
    .await?;

// Retain the listener while clients use its local port.
println!("TCP entry: {}", listener.local_addr());
tokio::signal::ctrl_c().await?;
// Await release of the listener port and its sessions.
listener.stop().await?;
// Node shutdown drains owned work within its bounded grace period.
entry.shutdown().await;
destination.shutdown().await;
handler.await??;

TunnelEntry::stop().await closes the listener and awaits its sessions within a two-second grace period. If cleanup exceeds that budget, it aborts the listener and returns NodeError::TimedOut. Dropping the handle or a pending stop future requests an abort; release finishes when the runtime processes it. A completed stop has released the port and listener slot.

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.

# Install the tagged release with the regular DNS adapter and CLI.
CARGO_NET_GIT_FETCH_WITH_CLI=true cargo install --git ssh://git@gitlab.com/korium.io/korium.git \
  --tag v0.11.0 --locked --features cli,dns korium

# Without a flag the daemon starts neither DNS nor mDNS.
korium --port 4433 --dns 127.0.0.1:5335 --seeds-file /etc/korium/seeds.toml \
  --identity-file /var/lib/korium/identity

# Alternative build/mode: --features cli,mdns and --mdns advertise.
# DNS and mDNS cannot be selected together.

// Add features = ["dns"] to the tagged korium dependency above.
use std::net::SocketAddr;
use korium::Node;

let node = Node::builder().build().await?;
let local_dns = node.start_default_dns_listener().await?;
node.stop_dns_listener().await?;

// Bind an explicitly controlled gateway address instead.
let bind: SocketAddr = "0.0.0.0:5335".parse()?;
let gateway_dns = node.start_dns_listener_at(bind).await?;

Query exact service identifiers

The DNS owner is _korium._udp.s1.<base32-service-id-labels>.svc.: lowercase unpadded base32 of the complete canonical service DID URL, split into labels of at most 63 bytes. Identifiers whose encoded owner exceeds the DNS name limit require native APIs. Identity-only k1 rows resolve global contacts; scoped service replies use independently resolvable k2 targets.

# Export SERVICE_DID with the trusted complete service identifier.
owner=$(python3 - <<'DNS_OWNER'
import base64
import os
encoded = base64.b32encode(os.environ["SERVICE_DID"].encode())
labels = encoded.decode().lower().rstrip("=")
print("_korium._udp.s1." + ".".join(
    labels[i:i+63] for i in range(0, len(labels), 63)
) + ".svc.")
DNS_OWNER
)
dig @127.0.0.1 -p 5335 "$owner" SRV +bufsize=1232

Kubernetes gateway

The following skeleton keeps the Korium identity on persistent storage and publishes DNS only through an internal UDP Service. Replace the placeholder image with your 0.11.0 build including cli,dns, and select your storage class. Provision the volume directory writable by UID/GID 65532; an existing identity file must be owned by that user with mode 0600. Group access alone is insufficient, and the directory needs write access when creating an identity. Keep the existing key and proof.

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: 65532
        runAsGroup: 65532
      containers:
        - name: korium
          image: registry.example/korium:0.11.0
          args:
            - --port
            - "4433"
            - --dns
            - 0.0.0.0:5335
            - --join
            - 203.0.113.10:4433/0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
            - --identity-file
            - /var/lib/korium/identity
          ports:
            - name: fabric
              containerPort: 4433
              protocol: UDP
            - name: dns
              containerPort: 5335
              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 512 bytes without EDNS, or the advertised size clamped to 512–1232 bytes. In-flight queries are capped at 64 and query work at 2 seconds. Oversized required RRsets produce TC; this UDP-only shim cannot serve TCP retries.
• Records use a 15-second TTL; service lookup gets a bounded 1.5-second DHT budget. Unresolved well-formed names return SERVFAIL; NXDOMAIN is reserved for impossible names or absent leaves of resolved contacts.
• 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 ServiceAuthorityTrust to one exact service DID URL, 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::{
    authority::{
        ExactServiceDelegationSpec, LeaseTerms, ServiceAuthorityChain,
        AuthorityKey, ServiceAuthorityScope,
        PolicyBoundNodeIssuerGrantSpec, PolicyBoundNodeIssuerKey,
        ServiceAuthorityBundleSpec,
    },
    ServiceAuthorityTrust,
};

let service_trust = ServiceAuthorityTrust::new(
    authority_root.service_root_did("acme")?,
    authority_root.public_bytes(),
    4,
)?;
let exact_service_chain = ServiceAuthorityChain::root(&service_trust)?
    .delegate_exact_service(
        &service_trust,
        &authority_root,
        ExactServiceDelegationSpec {
            child_public_key: service_issuer.public_bytes(),
            scope: ServiceAuthorityScope::exact_service(
                &authority_root.service_did("acme", "payments")?,
            )?,
            terms: service_issuer_terms,
            nonce: exact_service_nonce,
        },
    )?;

let node_issuer_grant = PolicyBoundNodeIssuerGrantSpec {
    service_trust: service_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 {
    service_trust: service_trust.clone(),
    node_issuer_grant: node_issuer_grant.clone(),
    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.

The default authz feature exposes korium::authority for offline issuance. Keep issuer private keys in that control-plane tool. Ordinary serving nodes need only the signed bundle and configured service roots.

Every entry in allow_sources must belong to an explicitly configured service authority. Readable-label equality and discovery never create network trust; configure one ServiceAuthorityTrust for each authority root that may authorize a source.

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

assert!(service.service_ids().contains(&service_id.as_str()));

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

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

The snippets use provisioned keys, fresh nonces, nested lease terms, exact source service IDs, and trusted grant issuers. A node accepts at most 64 bindings under one root; send_as, open_stream_as, and tunnel _as APIs select a source service explicitly. A malformed source is InvalidInput; a service the node does not host is SourceServiceNotHosted. An ambiguous implicit source is rejected as AmbiguousSourceService. These checks happen before discovery, dialing, stream creation, or listener binding. Request contexts expose source_service_id() and destination_service_id().

Verified evidence is read-only. Inspect a VerifiedGrant through issuer(), audience(), action(), resource(), expires_unix_seconds(), app_claims(), and revocation_id(). A VerifiedServiceBinding exposes service_id(), node_public_key(), and expires_unix_seconds(). Applications cannot construct or modify either verified value.

Build bounded issuer links

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

use korium::authority::{
    ServiceSubtreeDelegationSpec, ServiceAuthorityScope,
};

let subtree_chain = ServiceAuthorityChain::root(&service_trust)?
    .delegate_subtree(
        &service_trust,
        &authority_root,
        ServiceSubtreeDelegationSpec {
            child_public_key: platform_issuer.public_bytes(),
            scope: ServiceAuthorityScope::subtree(
                &format!("{}/platform", authority_root.service_root_did("acme")?),
            )?,
            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 DID URL, allow_sources, and grant_issuers. The node issuer cannot widen scope or change policy.

Redeploy with a fresh terminal binding

Keep the stable service DID URL 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 {
    service_trust: service_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_authorities(vec![service_trust], vec![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 DID URL, source allowlist, or grant-issuer policy.
• Replacing a compromised authority 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. Authority selection is fixed when the node is built.