Module prelude 

Convenience import for building applications

Re-exports

pub use crate::backend_kv_store::BackendHandler;

pub use crate::prefabs::client::peer_connection::PeerConnectionSetupAggregator;

pub use crate::prefabs::client::PrefabFunctions;

pub use crate::prefabs::client::DefaultServerConnectionSettingsBuilder;

pub use crate::prefabs::client::ServerConnectionSettings;

pub use crate::prefabs::ClientServerRemote;

pub use crate::remote_ext::remote_specialization::PeerRemote;

pub use crate::responses;

pub use crate::sign_in::SignInManagementExt;

pub use crate::remote_ext::*;

Structs

AbandonSession

Ends the C2S session session_cid locally, without waiting for the server’s ack (see proto::session_abandon). Answered with a NodeResult::Disconnect under the request’s ticket once the session has dropped.

AccountManager

The default manager for handling the list of users stored locally. It also allows for user creation, and is used especially for when creating a new user via the registration service.

ActiveSessions

AdmissionChallenge

The check a refusal asks the client to complete before it tries again.

ArgonDefaultServerSettings

ByteCount

Bytes sent and received, as read at one moment.

CNACMetadata

For passing metadata from a cnac

CallbackReceiver

A receiver for the tracked callback channel.

CitadelNode

ClassGates

The classes a connection may carry on each of its paths.

CommandPath

A position in a command hierarchy: ordered segments from the root (e.g. /HQ/Bn1/Co-A/Plt-2). An empty path is the root authority. is_ancestor_of is the “superior reads subordinate” predicate.

ConnectFail

ConnectSuccess

ConnectToHypernode

ConnectionInfo

CryptoParameters

DeRegistration

DeleteObject

DeregisterFromHypernode

Disconnect

DisconnectFromHypernode

EffectivePlan

The paths one pair of peers may use, in the order their campaign tries them. Always ends with PathKind::ServerRelay, which needs no attempt.

EncryptionAlgorithmIter

An iterator over the variants of EncryptionAlgorithm

ExplicitPanicFuture

Ensures that if a panic occurs in a task, the panic backtrace prints and halts the program

FcmKeys

GroupBroadcastCommand

GroupChannel

GroupChannelCreated

GroupChannelRecvHalf

GroupChannelSendHalf

GroupEvent

GroupMessageLimits

The per-group caps on message size and rate, enforced by the server.

HostSqlHandle

The SqlHost a crate::backend::BackendType::HostSql carries. Two handles are equal only when they are the same host, which is what “the same backend” means for them.

IfEq

InternalServerError

KemAlgorithmIter

An iterator over the variants of KemAlgorithm

KernelExecutor

Creates a KernelExecutor

KernelExecutorSettings

Used for fine-tuning parameters within the [KernelExecutor]

KexPath

The path half of one Kex stage.

MailboxDelivery

MessageGroupKey

MessageGroupOptions

Options for creating message groups

MonoRatchet

A compact ratchet meant for protocols that require smaller payloads

MutualPeer

This is to replace a tuple for greater organization

NatClass

The classification of a [NatType]: its translation models and whether IPv6 is enabled. An unidentified NAT (identification failed) classifies as unpredictable in both.

NativeIO

Default [ProtocolIO] implementation for native platforms.

NativeOrderedReliableConfig

Config for ordered reliable transport without encryption (TCP).

NativeP2PConfig

Config for P2P-capable transport (QUIC).

NativeSecureConfig

Config for ordered reliable secure transport (TLS).

NetworkError

The single error type used across the entire Citadel workspace.

NodeBuilder

Used to construct a running client/peer or server instance

NodeFuture

An awaitable future whose return value propagates any internal protocol or kernel-level errors

NodeRemote

allows convenient communication with the server

NodeTrafficSnapshot

A node’s traffic by class, as read at one moment.

ObjectId

ObjectTransferHandle

ObjectTransferHandler

ObjectTransferHandlerInner

Used to keep track of file transfer progress for either sender or receiver orientation

OutboundRequestRejected

OutboundUdpSender

P2pPathCell

Shared, live view of a virtual connection’s P2pPath, read by the application’s channel and written when a P2P connection is established, lost, or given up on. Every change is published, so an application can subscribe instead of polling.

P2pPathStatus

A snapshot of a virtual connection’s path and of its background upgrade campaign.

PairFeasibility

What the server knows about a pair beyond their offers.

PathAttemptOutcome

One upgrade attempt of a P2P connection’s background campaign.

PathBytesSnapshot

A peer connection’s bytes on each path, as read at one moment.

PathClasses

A set of PathClasses.

PathControl

Asks a connection’s P2P campaign to try again (see the module docs). It outlives PeerChannel::split, as P2pPathCell does.

PathOffer

What one peer brings to its key exchange: what it refuses, and whether it holds a TURN relay configuration for this attempt.

PathPolicy

A server’s validated path precedence. Order is precedence: the campaign tries the enabled rules before the server relay in this order.

PathRestrictions

Paths a peer refuses to use, whatever the server allows: for example Direct and PeerRelay for a user who never wants a peer to learn their IP address.

PathRule

One path’s entry in a PathPolicy.

PeerChannel

PeerChannelCreated

PeerChannelRecvHalf

A stream interface for receiving secure packets NOTE: on drop, if this is used for a P2P connection, disconnection will occur

PeerChannelSendHalf

PeerCommand

PeerEvent

PeerInfo

Contains info about a peer, used for giving the user access to usernames and names of peers

PeerPathOutcome

The kernel’s copy of an attempt’s outcome, named by session and connection.

PersistenceHandler

This is what every C/NAC gets. This gets called before making I/O operations

PlannedPath

One path of an EffectivePlan.

PreSharedKey

ProbeServer

Sends a liveness probe to the server of session_cid now and reports its round trip, or that no answer came within timeout (see proto::server_probe).

PullObject

QuicRedirectSignal

Redirect signal carrying QUIC connection parameters.

ReKey

ReKeyResult

ReVFSResult

RebindFailure

One endpoint that could not be moved. It keeps its old socket.

RebindReport

What a rebind did to each live endpoint.

Rebound

One endpoint moved from from to to.

RegisterFailure

RegisterOkay

RegisterToHypernode

RtdbConfig

For use in the TOML config as well as for during the Post-login phase

SecBuffer

A memory-secure wrapper for shipping around Bytes

SecrecyModeIter

An iterator over the variants of SecrecyMode

SecureBufMutHandle

SecurityKeyChallenge

One request for a touch. Answer it once, or drop it to decline.

SecurityKeyPrf

The SDK’s end of the channel; pass it in crate::auth::SignInFactors.

SecurityKeyRequest

What the embedding application must ask a security key for: a WebAuthn ceremony for relying party rp_id, with the PRF extension evaluated at prf_eval_salt.

SecurityLevelIter

An iterator over the variants of SecurityLevel

SendObject

ServerMiscSettings

Miscellaneous settings for a node serving connections

ServerOnlySessionInitSettings

ServerProbeResult

The outcome of NodeRequest::ProbeServer.

ServicesConfig

ServicesObject

Passed to the services handler post-login at the server. Intended to be passed to the client afterwards

SessionInfo

SessionList

SessionSecuritySettings

SessionSecuritySettingsBuilder

SetPeerTurnConfig

Supplies (Some) or withdraws (None) the TURN relay configuration for the next P2P attempt between session_cid and peer_cid. Both peers must supply one for the relay to be used; it is consumed by that attempt. Local only — credentials are never sent over the wire.

SigAlgorithmIter

An iterator over the variants of SigAlgorithm

SignInCredential

One enrolled factor, as ListCredentials reports it.

SignInFactors

The factors a post-quantum sign-in (or a management step-up) offers. Offer what the user gave; the account’s policy decides what suffices, and the server never says which was wrong.

SqlStatement

One statement and its positional (?) parameters.

StackedRatchet

A container meant to establish perfect forward secrecy AND scrambling w/ an independent key This is meant for messages, not file transfer. File transfers should use a single key throughout the entire file

StageOutcome

How one stage of an attempt ended.

StunServers

A validated list of at least MIN_STUN_SERVERS distinct host:port STUN endpoints, in the order given. Cheap to clone.

SymmetricIdentifierHandle

A convenience structure for executing commands that depend on a specific registered user

SymmetricIdentifierHandleRef

A reference to a user identifier

TcpToQuicUpgrade

TCP-to-QUIC protocol upgrade.

Ticket

A type sent through the server when a request is made

TrackedCallbackChannel

A tracked callback channel that provides request-response tracking and monitoring.

TrackedCallbackChannelPayload

A payload for the tracked callback channel.

TransferMetadata

Platform-portable file metadata returned by PlatformOps::open_and_validate_for_transfer.

TurnRelayConfig

Everything the relay needs for one P2P attempt. Both peers must supply one; the lower-CID peer allocates, the other dials the relayed address.

TurnServerConfig

TURN server configuration for NAT traversal relay.

TurnServerCredential

One TURN server and the long-term credential used to authenticate against it.

TurnUrl

A parsed RFC 7065 TURN URI: turn:host[:port][?transport=udp|tcp] or turns:host[:port][?transport=tcp].

UdpChannel

UdpModeIter

An iterator over the variants of UdpMode

VirtualObjectMetadata

WebRTCCompatChannel

WebSocketEndpoint

A ws:// or wss:// URL naming a Citadel server.

Enums

AdmissionProvider

Who issues the tokens a challenge asks for. A client that does not know a provider ignores the challenge (it decodes as absent) and shows a plain refusal.

AuthenticationRequest

Arguments for connecting to a node

BackendType

Used when constructing the account manager

ClientConnectionType

Type of client-to-server connection.

ConnectMode

How a client asks the server to treat a login for an account that the server already holds a session for.

ConnectProtocol

For saving the state of client-side connections

EncryptionAlgorithm

FactorKind

What a factor is derived from.

GenericNetworkStream

GroupBroadcast

Enum representing different types of group broadcast messages

GroupBroadcastPayload

GroupHierarchyMode

How a group’s encryption is structured. Flat is the ordinary zero-trust CGKA where every member shares one epoch key; CommandHierarchy adds the Decentralized Hierarchy Encryption overlay where a superior can read its subordinates’ messages (see ReadPolicy).

GroupMemberAlterMode

GroupMessageLimitsError

Why GroupMessageLimits::new refused its arguments.

GroupMessageRefusal

Why the server refused to relay a group message. The message reached nobody.

GroupType

HeaderObfuscatorSettings

IpTranslationClass

How a NAT translates the IP address, as [IpTranslation] without its addresses.

KemAlgorithm

MemberState

NodeRequest

These are sent down the stack into the server. Most of the requests expect a ticket ID in order for processes sitting above the [Kernel] to know how the request went

NodeResult

This type is for relaying results between the lower-level protocol and the higher-level kernel

NodeType

Used for determining the proper action when loading the server

ObjectTransferOrientation

ObjectTransferStatus

P2pPath

The path carrying a P2P connection’s traffic.

PathClass

A class of traffic, for deciding which paths may carry it.

PathKind

A network path a peer connection can take.

PathPlanKind

Which paths an attempt was planned to try.

PathPolicyError

Why a PathPolicy was refused.

PathStage

A stage of an upgrade attempt, in the order an attempt runs them.

PeerConnectionType

Type of peer-to-peer connection.

PeerResponse

PeerSignal

PortTranslationClass

How a NAT translates the port, as [PortTranslation] without its ports or deltas.

ProposedCredentials

When creating credentials, this is required

ReKeyReturnType

ReadPolicy

Who can read a hierarchy-group message.

SecrecyMode

SecurityKeyCeremony

SecurityKeyPurpose

Why the SDK is asking.

SecurityLevel

Provides the enumeration for all security levels

ServerMode

Capability-based server configuration.

ServerProbeOutcome

How a probe ended.

SessionScope

What a session that has signed in may do.

SigAlgorithm

SignInManagementOp

A change to an account’s sign-in factors. Each one needs a fresh proof of the account’s factors (a step-up), except the two a recovery session may make.

SignInManagementOutcome

What a SignInManagementOp that the server carried out returns to the application.

SignInPolicy

Which factors a sign-in must prove.

SqlValue

A value bound into, or read out of, a statement. Integers must stay within ±2^53 so a JS host can carry them as numbers; CIDs, which do not, travel as decimal text.

StageFailure

Why a stage did not connect. Paired with its PathStage, which says where.

StorageQuota

How much RE-VFS storage a SqlHost grants.

StunServersError

Why a STUN server list was refused.

TransferType

TurnPolicy

When the relay is used for a P2P attempt.

TurnTransport

How the client reaches the TURN server. The relayed leg (TURN server ↔ peer) is always UDP.

UdpMode

UserIdentifier

A convenience wrapper for passing arguments to functions that require searches for a user

VirtualConnectionType

Unified type representing all possible virtual connections.

Constants

AES_GCM_NONCE_LENGTH_BYTES

ASCON_NONCE_LENGTH_BYTES

C2S_IDENTITY_CID

Constant for C2S identity (target_cid = 0 means server).

CHA_CHA_NONCE_LENGTH_BYTES

KEM_ALGORITHM_COUNT

KYBER_NONCE_LENGTH_BYTES

LARGEST_NONCE_LEN

MAX_ATTEMPT_TIMEOUT

The longest attempt timeout a rule may set.

MIN_ATTEMPT_TIMEOUT

The shortest attempt timeout a rule may set.

MIN_STUN_SERVERS

The fewest distinct servers a list may name: NAT classification needs three observations.

PEER_MAILBOX_MAP

The byte map ((cid, 0, PEER_MAILBOX_MAP, <uuid>)) where a server holds the signals it mails to an offline cid, each a serialized PeerSignal, until cid next connects. Unbounded: nothing caps how many a member accumulates.

Traits

AlgorithmsExt

IfEqConditional

IfTrueConditional

NativeServerModeExt

Extension trait for ServerMode<NativeIO> convenience methods.

NetKernel

The NetKernel is the thread-safe interface between the single-threaded OR multi-threaded async protocol and your network application

ObjectSource

PairMap

PlatformOps

Platform-specific capabilities extending the transport abstraction.

Ratchet

For allowing registration inside the toolset

Remote

RuntimeFuture

SqlHost

SQL storage supplied by the host.

SyncIO

Convenient serialization methods for types that #[derive(Serialize, Deserialize)]

TargetLockedRemote

Then

Functions

add_inner

calculate_optimal_argon_params

Uses: https://www.ory.sh/choose-recommended-argon2-parameters-password-hashing/ “To reach the desired execution time, you can tweak two variables. It is recommended to start with the highest amount of memory possible and one iteration. Reduce the memory until one hashing operation takes less than your desired duration. Next, advance the number of iterations to approach the desired execution time as close as possible”

challenge_of

The challenge a connect or register error carries, when the server’s refusal sent one.

effective_plan

The plan for a pair: each enabled rule of policy, in order up to and including the server relay, kept only when neither peer refuses it and the pair can use it. Direct needs NATs that admit a hole punch; PeerRelay needs a forwarder; Turn needs both peers to hold a TURN config.

load_server_endpoint

The WebSocket URL the account cid registered to, or None for an account whose server is its address.

prepare_virtual_path

read_one_packet_as_framed

security_key_channel

A channel for security-key requests: hand the first half to the SDK, serve the second.

username_to_cid

Generates a CID given a username.

validate_virtual_path

write_one_packet

Type Aliases

DefaultNodeBuilder

Default node builder type using platform-appropriate transport

DefaultTransport

Platform-appropriate default transport.

FactorId

The server’s identifier for one enrolled factor of an account. Unique within the account and never reused, so a removed factor’s id cannot come to mean a different factor.

LightweightNodeBuilder

Lightweight node builder using MonoRatchet for reduced cryptographic overhead

RestoredUdpChannels

Every UDP channel a P2P path recovery restores, in order (see PeerChannel::upgrade).

SqlRow

A result row, columns in the order the statement selected them.

TrackedCallbackError

Error type for tracked callback channel operations.

VirtualTargetType

Alias for VirtualConnectionType (for readability in target contexts).

Attribute Macros

async_trait