Build the application.
Let the fabric carry trust.

Disable public bootstrap when your deployment distributes explicit seed identities and socket addresses. A join address is an untrusted reachability hint; the connection still authenticates the remote node with mTLS, DID binding, and PoW.

let node = Node::builder()
    .bootstrap(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?;

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. 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. Announcements publish signed, expiring liveness; lookups return candidates, never 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);
}

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 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 or a general-purpose resolver.

# The standalone binary requires both features.
cargo build --release --bin korium --features cli,dns

# CLI bootstrap is opt-in. The DNS listener defaults to loopback:5353
# when --dns is omitted.
korium \
  --port 4433 \
  --dns 0.0.0.0:5353 \
  --bootstrap \
  --identity-file /var/lib/korium/identity

use std::net::SocketAddr;

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

// Default: loopback on UDP 5353.
let local_dns = node.start_default_dns_listener().await?;

// Or expose an explicit address for a controlled gateway.
let bind: SocketAddr = "0.0.0.0:5353".parse()?;
let gateway_dns = node.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.33
          args:
            - --port
            - "4433"
            - --dns
            - 0.0.0.0:5353
            - --bootstrap
            - --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.
• 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 verified service presents an offline-authored authority bundle bound to its node key. Build fails if the proof is malformed, expired, rooted in another namespace, or bound to a different keypair.

let service = Node::builder()
    .contact(persisted_keypair, persisted_pow)
    .with_service_identity(namespace_root, 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?);
}

Scale out a verified service without the root secret

This workflow is for the service-instance holder or its control plane, not an ordinary calling client. The namespace root grants a bounded delegation capability before its private key is destroyed; the authorized instance can then issue exact-URN child credentials without choosing a new service name or policy. Enable Korium's authoring feature in the binary or control-plane tool that performs the first two phases.

1. While the namespace-root secret still exists

The root must issue the parent a v2 bundle with explicit delegation permission. Keep the root public key before destroying the private key.

use korium::authoring::{
    DelegableUrnAuthorityBundleSpec,
    ExactUrnDelegationPermission,
    LeaseTerms,
    UrnBindingProofSpec,
};

let parent_proof = UrnBindingProofSpec::direct(
    &namespace_root,
    &instance_issuer,
    "urn:korium:acme/payments",
    parent_key.public_key_bytes(),
    parent_terms,
)
.sign()?;

let parent_bundle = DelegableUrnAuthorityBundleSpec {
    urn_binding_proof: parent_proof,
    allow_sources,
    grant_issuers,
    delegation: ExactUrnDelegationPermission {
        max_depth: 1,
        nonce: root_authorization_nonce,
    },
}
.sign(&namespace_root)?;

let namespace_root_public = namespace_root.public_bytes();

max_depth: 1 is the normal scale-out posture: the original instance may authorize children, but those children cannot delegate again. The value limits ancestry depth, not the number of sibling replicas the parent may authorize.

2. After the namespace-root secret has been destroyed

The authorized parent generates or receives a child key, then signs a child bundle. authorize() verifies the supplied parent bundle before signing and requires the child validity window to stay within the parent's.

use korium::{
    authoring::{ExactUrnInstanceDelegationSpec, LeaseTerms},
    Keypair,
};

let (child_key, child_pow) = Keypair::generate()?;

let child_bundle = ExactUrnInstanceDelegationSpec {
    namespace_root: namespace_root_public,
    parent_key: &parent_key,
    verified_parent_bundle: &parent_bundle,
    child_public_key: child_key.public_key_bytes(),
    terms: LeaseTerms {
        not_before_unix_seconds: now,
        expires_unix_seconds: now + 300,
    },
    nonce: child_delegation_nonce,
}
.authorize()?;

The child authoring API deliberately accepts no URN, allow_sources, or grant_issuers; all three are inherited from the root-signed parent bundle. Persist the child key, matching PoW proof, child bundle, root public key, and the authorization nonces according to your control-plane durability and audit requirements. The namespace-root private key is not required.

3. Start the child normally

let child = korium::Node::builder()
    .contact(child_key, child_pow)
    .with_service_identity(namespace_root_public, child_bundle)
    .build()
    .await?;

This is the entire runtime integration. NodeBuilder checks that the bundle terminates at the supplied child key. Korium then embeds and verifies the delegated proof through its existing TLS, connection, destination, and stream paths; no transport-specific delegation API is needed.

Rotate the namespace root

Removing a node from a namespace means redeploying that namespace under a new root. A node pins its acceptance policy separately from the root its own credential chains to, so the rollout can proceed as a three-wave rolling redeployment instead of a flag day.

// Waves 1 and 2 carry the identical acceptance policy, so no wave
// ever presents a credential the rest of the fleet cannot root.
let node = Node::builder()
    .contact(persisted_keypair, persisted_pow)
    .with_service_identity(own_credential_root, signed_bundle)
    .accepting_namespace_root_transition(
        new_primary_root,
        old_retiring_root,
        retire_after_unix_seconds,
    )
    .build()
    .await?;

• A chain rooted at the retiring root verifies only while now < retire_after; its verified expiry becomes min(chain_expiry, retire_after), so admitted connections close at retirement.
• Exposure is bounded only once wave 1 has reached every node — a node never reached has no knowledge of T. Treat completion of wave 1, not its start, as the start of the bound.
• Retirement is fail-closed at the deadline: now == retire_after is already refused.
• The build rejects equal primary and retiring roots, a deadline not in the future, and a node whose own credential root neither entry accepts.
• Persist keypairs and PoW proofs. Regenerating them changes every DID, invalidating grant_issuers entries and forcing PoW re-mining fleet-wide.