aether-federation

Cross-instance interoperability and federated auth

The aether-federation crate enables cross-instance interoperability between independently hosted Aether servers. It provides a handshake protocol, server registry, asset transfer with integrity verification, federated authentication, and health monitoring.

Overview

Federation allows self-hosted Aether worlds to connect with each other, forming a decentralized network. Players can traverse between independently operated servers while retaining their identity and assets. The system includes:

• Handshake protocol for establishing trust between servers.
• Server registry for discovering and tracking federated instances.
• Asset transfer with hash-based integrity verification.
• Federated authentication that validates player identity across server boundaries.
• Health monitoring to track the availability of federated peers.
• Routing tables for resolving portal destinations to specific server endpoints.

Key Types

FederationRuntime

The top-level runtime that manages federation state and processes cross-instance transactions.

use aether_federation::{FederationRuntime, FederationRuntimeConfig};

let config = FederationRuntimeConfig {
    max_peers: 100,
    handshake_timeout_seconds: 30,
    health_check_interval_seconds: 60,
};
let runtime = FederationRuntime::new(config);

HandshakeManager

Manages the challenge-response handshake that establishes trust between two servers.

use aether_federation::{
    HandshakeManager, HandshakeChallenge, HandshakeResponse, HandshakeState,
};

let mut handshake = HandshakeManager::new();
let challenge = handshake.create_challenge(peer_id);
let response = handshake.respond(&challenge, &our_credentials)?;

ServerRegistry

Maintains a list of known federated servers with their status and capabilities.

use aether_federation::{ServerRegistry, FederatedServer, ServerStatus};

let mut registry = ServerRegistry::new();
registry.register(FederatedServer {
    endpoint: "https://worlds.example.com".into(),
    status: ServerStatus::Online,
    worlds: vec!["plaza".into(), "arena".into()],
});

RoutingTable

Resolves portal destinations to specific server endpoints for cross-instance navigation.

use aether_federation::{RoutingTable, PortalRoute, ResolvedDestination};

let mut routing = RoutingTable::new();
routing.add_route(PortalRoute {
    pattern: "aether://example.com/*".into(),
    server: "https://example.com:8443".into(),
});
let dest = routing.resolve("aether://example.com/plaza")?;

AssetVerification

Validates transferred assets against their content hashes to prevent tampering.

use aether_federation::{AssetVerification, VerificationResult};

let result = AssetVerification::verify(&asset_bytes, &expected_hash);
assert!(result.is_valid());

HealthMonitor

Periodically checks the availability of federated peers and tracks uptime history.

use aether_federation::{HealthMonitor, HealthStatus, HealthRecord};

let mut monitor = HealthMonitor::new();
monitor.check(peer_id).await;
let status: HealthStatus = monitor.status(peer_id);

Usage Examples

Establishing Federation

use aether_federation::{
    HandshakeManager, ServerRegistry, FederatedServer,
    FederationAuthRequest, FederationAuthResult,
};

let mut handshake = HandshakeManager::new();
let mut registry = ServerRegistry::new();

// Server A initiates handshake with Server B
let challenge = handshake.create_challenge(server_b_id);
// Server B responds, completing the handshake
let session = handshake.complete(response)?;

registry.register(FederatedServer {
    endpoint: server_b_endpoint,
    status: ServerStatus::Online,
    worlds: vec![],
});

Cross-Instance Asset Transfer

use aether_federation::{
    FederationAssetReference, AssetIntegrityPolicy, HashMismatchAction,
};

let asset_ref = FederationAssetReference {
    origin_server: "https://example.com".into(),
    asset_hash: content_hash,
    policy: AssetIntegrityPolicy {
        on_mismatch: HashMismatchAction::Reject,
    },
};