Acds

Enumerations
enum	acds_session_type_t { SESSION_TYPE_DIRECT_TCP = 0 , SESSION_TYPE_WEBRTC = 1 }
	Session connection type. More...

ACDS Error Handling
enum	acip_error_code_t {   ACIP_ERROR_NONE = 0 , ACIP_ERROR_SESSION_NOT_FOUND = 1 , ACIP_ERROR_SESSION_FULL = 2 , ACIP_ERROR_INVALID_PASSWORD = 3 ,   ACIP_ERROR_INVALID_SIGNATURE = 4 , ACIP_ERROR_RATE_LIMITED = 5 , ACIP_ERROR_STRING_TAKEN = 6 , ACIP_ERROR_STRING_INVALID = 7 ,   ACIP_ERROR_INTERNAL = 255 }
	ACIP error codes. More...
	acip_error_t

ACDS Session Management Messages
	acip_session_create_t
	acip_session_created_t
	acip_session_lookup_t
	acip_session_info_t
	acip_session_join_t
	acip_session_joined_t
	acip_session_leave_t
	acip_session_end_t
	acip_session_reconnect_t
struct	__attribute__ ((packed))
	SESSION_CREATE (PACKET_TYPE_ACIP_SESSION_CREATE) - Create new session.

ACDS WebRTC Signaling Messages
	acip_webrtc_sdp_t
	acip_webrtc_ice_t

ACDS String Reservation Messages (Future)
	acip_string_reserve_t
	acip_string_reserved_t
	acip_string_renew_t
	acip_string_release_t

ACDS Protocol Constants
#define	ACIP_MAX_SESSION_STRING_LEN   48
	Maximum session string length (e.g., "swift-river-mountain" = 20 chars)
#define	ACIP_SESSION_EXPIRATION_MS   (24ULL * 60 * 60 * 1000)
	Session expiration time (24 hours in milliseconds)
#define	ACIP_DISCOVERY_DEFAULT_PORT   27225
	Discovery server default port.

Detailed Description

This module defines the binary message formats for the ACIP discovery protocol. All messages use packed structs sent over TCP using the existing ACIP packet infrastructure (packet_header_t + payload).

PROTOCOL DESIGN:

• Raw TCP transport (port 27225 default)
• Binary ACIP packets (NOT JSON)
• Reuses existing crypto handshake (CRYPTO_KEY_EXCHANGE_*, CRYPTO_AUTH_*)
• Ed25519 identity signatures for session authentication
• Ephemeral sessions (24-hour expiration)

MESSAGE STRUCTURE:

All ACDS messages follow the standard ACIP packet structure:

• Header: packet_header_t (magic, type, length, CRC32, client_id)
• Payload: Message-specific packed struct (defined here)

INTEGRATION WITH OTHER MODULES:

• network/acip/protocol.h: Defines ACIP packet types (100-199)
• network/packet.h: Provides packet infrastructure (header, CRC, etc.)
• src/acds/: ACDS server implementation

Note

All structures are packed with attribute((packed)) for wire format.

Payload sizes include both fixed and variable-length portions.

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

January 2026

Version

1.0 (ACIP Protocol Refactoring)

Macro Definition Documentation

ACIP_DISCOVERY_DEFAULT_PORT

#define ACIP_DISCOVERY_DEFAULT_PORT   27225

#include <acds.h>

Discovery server default port.

Definition at line 484 of file network/acip/acds.h.

ACIP_MAX_SESSION_STRING_LEN

#define ACIP_MAX_SESSION_STRING_LEN   48

#include <acds.h>

Maximum session string length (e.g., "swift-river-mountain" = 20 chars)

Definition at line 478 of file network/acip/acds.h.

ACIP_SESSION_EXPIRATION_MS

#define ACIP_SESSION_EXPIRATION_MS   (24ULL * 60 * 60 * 1000)

#include <acds.h>

Session expiration time (24 hours in milliseconds)

Definition at line 481 of file network/acip/acds.h.

Enumeration Type Documentation

acds_session_type_t

enum acds_session_type_t

#include <acds.h>

Session connection type.

Determines how clients connect to the session host:

• DIRECT_TCP: Clients connect directly to server IP:port (default, requires public IP)
• WEBRTC: Clients use WebRTC P2P mesh with STUN/TURN (works behind NAT)

Enumerator
SESSION_TYPE_DIRECT_TCP	Direct TCP connection to server IP:port (default)
SESSION_TYPE_WEBRTC	WebRTC P2P mesh with STUN/TURN relay.

Definition at line 67 of file network/acip/acds.h.

             {
  SESSION_TYPE_DIRECT_TCP = 0, 
  SESSION_TYPE_WEBRTC = 1      
} acds_session_type_t;

acip_error_code_t

enum acip_error_code_t

#include <acds.h>

ACIP error codes.

Standard error codes returned in ACIP error responses.

Enumerator
ACIP_ERROR_NONE	No error (success)
ACIP_ERROR_SESSION_NOT_FOUND	Session does not exist.
ACIP_ERROR_SESSION_FULL	Session has reached max participants.
ACIP_ERROR_INVALID_PASSWORD	Password verification failed.
ACIP_ERROR_INVALID_SIGNATURE	Identity signature invalid.
ACIP_ERROR_RATE_LIMITED	Too many requests from this IP.
ACIP_ERROR_STRING_TAKEN	Requested string already reserved.
ACIP_ERROR_STRING_INVALID	String format invalid.
ACIP_ERROR_INTERNAL	Internal server error.

Definition at line 457 of file network/acip/acds.h.

             {
  ACIP_ERROR_NONE = 0,              
  ACIP_ERROR_SESSION_NOT_FOUND = 1, 
  ACIP_ERROR_SESSION_FULL = 2,      
  ACIP_ERROR_INVALID_PASSWORD = 3,  
  ACIP_ERROR_INVALID_SIGNATURE = 4, 
  ACIP_ERROR_RATE_LIMITED = 5,      
  ACIP_ERROR_STRING_TAKEN = 6,      
  ACIP_ERROR_STRING_INVALID = 7,    
  ACIP_ERROR_INTERNAL = 255         
} acip_error_code_t;

Function Documentation

__attribute__()

struct __attribute__

(

(packed)

)

#include <acds.h>

SESSION_CREATE (PACKET_TYPE_ACIP_SESSION_CREATE) - Create new session.

ERROR (PACKET_TYPE_ACIP_ERROR) - Generic error response.

STRING_RELEASE (PACKET_TYPE_ACIP_STRING_RELEASE) - Release string reservation.

STRING_RENEW (PACKET_TYPE_ACIP_STRING_RENEW) - Renew string reservation.

STRING_RESERVED (PACKET_TYPE_ACIP_STRING_RESERVED) - String reservation response.

STRING_RESERVE (PACKET_TYPE_ACIP_STRING_RESERVE) - Reserve a session string.

WEBRTC_ICE (PACKET_TYPE_ACIP_WEBRTC_ICE) - ICE candidate relay.

WEBRTC_SDP (PACKET_TYPE_ACIP_WEBRTC_SDP) - SDP offer/answer relay.

SESSION_RECONNECT (PACKET_TYPE_ACIP_SESSION_RECONNECT) - Reconnect to session.

SESSION_END (PACKET_TYPE_ACIP_SESSION_END) - End session (host only)

SESSION_LEAVE (PACKET_TYPE_ACIP_SESSION_LEAVE) - Leave session.

SESSION_JOINED (PACKET_TYPE_ACIP_SESSION_JOINED) - Session join response.

SESSION_JOIN (PACKET_TYPE_ACIP_SESSION_JOIN) - Join existing session.

SESSION_INFO (PACKET_TYPE_ACIP_SESSION_INFO) - Session info response.

SESSION_LOOKUP (PACKET_TYPE_ACIP_SESSION_LOOKUP) - Lookup session by string.

SESSION_CREATED (PACKET_TYPE_ACIP_SESSION_CREATED) - Session created response.

Direction: Client -> Discovery Server

Payload structure (fixed + variable):

• Fixed part: acip_session_create_t (295 bytes)
• Variable part: reserved_string (if reserved_string_len > 0)

The client requests creation of a new session with specific capabilities, optionally providing a pre-reserved session string. The server responds with SESSION_CREATED containing the session identifier.

Direction: Discovery Server -> Client

Payload structure (fixed + variable):

• Fixed part: acip_session_created_t (66 bytes)
• Variable part: stun_server_t[stun_count] + turn_server_t[turn_count]

The server responds to SESSION_CREATE with the generated session identifier, session string (either auto-generated or the provided reserved string), and optional STUN/TURN server information for WebRTC connectivity.

Note

STUN server configuration (stun_server_t) is defined in networking/webrtc/stun.h

TURN server configuration (turn_server_t) is defined in networking/webrtc/turn.h

Direction: Client -> Discovery Server

The client queries for session information using the session string. Server responds with SESSION_INFO containing basic session metadata (but NOT the server connection information, which is only revealed after successful authentication via SESSION_JOIN).

Direction: Discovery Server -> Client

SECURITY NOTE: Does NOT include server connection information (IP/port). Server address is only revealed after authentication via SESSION_JOIN. This prevents IP address leakage to unauthenticated clients.

Direction: Client -> Discovery Server

Payload structure: acip_session_join_t (241 bytes fixed)

The client requests to join an existing session, providing identity proof via Ed25519 signature and optionally a password. Server responds with SESSION_JOINED containing server connection information upon successful authentication.

Direction: Discovery Server -> Client

CRITICAL SECURITY: Server connection information (IP/port) is ONLY revealed after successful authentication (password verification or identity verification). This prevents IP address leakage to unauthenticated clients who only know the session string.

Direction: Client -> Discovery Server

The client gracefully leaves a session, allowing the server to update participant count and potentially notify other participants.

Direction: Host -> Discovery Server

The session host terminates the session, preventing new joins and notifying all participants. Requires signature proof of host identity.

Direction: Client -> Discovery Server

The client reconnects to a session after disconnection, using stored participant ID and identity proof to resume participation.

Direction: Bidirectional (relayed through discovery server)

Payload structure (fixed + variable):

• Fixed: acip_webrtc_sdp_t (50 bytes)
• Variable: sdp_data (SDP string)

WebRTC session description protocol messages are relayed through the discovery server to facilitate peer-to-peer connection establishment.

Direction: Bidirectional (relayed through discovery server)

Payload structure (fixed + variable):

• Fixed: acip_webrtc_ice_t (50 bytes)
• Variable: candidate (ICE candidate string)

WebRTC ICE candidates are relayed through the discovery server to facilitate NAT traversal during peer-to-peer connection establishment.

Direction: Client -> Discovery Server

FUTURE FEATURE: Reserve a memorable session string for future use, preventing others from using it for a specified duration.

Direction: Discovery Server -> Client

FUTURE FEATURE: Confirms successful string reservation or reports error.

Direction: Client -> Discovery Server

FUTURE FEATURE: Extends an existing string reservation before expiration.

Direction: Client -> Discovery Server

FUTURE FEATURE: Voluntarily releases a reserved string before expiration.

Direction: Discovery Server -> Client

Generic error response used when no specific response packet type exists. Contains error code and human-readable message.

< Ed25519 public key of session host

< Signs: type || timestamp || capabilities

< Unix ms (replay protection)

< Bit 0: video, Bit 1: audio

< 1-8 participants allowed

< acds_session_type_t: 0=DIRECT_TCP (default), 1=WEBRTC

< 0 = no password, 1 = password protected

< Argon2id hash (only if has_password == 1)

< 0 = require verification, 1 = allow public IP disclosure (explicit –acds-expose-ip opt-in)

< 0 = auto-generate, >0 = use provided string

< IPv4/IPv6 address or hostname (null-terminated)

< Port number for client connection

< Length of session string (e.g., 20 for "swift-river-mountain")

< Null-padded session string

< UUID as bytes (not string)

< Unix ms (created_at + 24 hours)

< Number of STUN servers

< Number of TURN servers

< 0 = not found, 1 = found

< Valid only if found == 1

< Host's Ed25519 public key

< Session capabilities

< acds_session_type_t: 0=DIRECT_TCP, 1=WEBRTC

< 1 = password required to join

< Unix ms

< Unix ms

< ACDS policy: server must verify client identity

< ACDS policy: client must verify server identity

< Joiner's Ed25519 public key

< Signs: type || timestamp || session_string

< Unix ms

< Cleartext password (TLS protects transport)

< 0 = failed, 1 = joined

< Error code if success == 0

< Human-readable error

< UUID for this participant (valid if success == 1)

< Session UUID

< acds_session_type_t: 0=DIRECT_TCP, 1=WEBRTC

< IPv4/IPv6 address or hostname (null-terminated)

< Port number for client connection

< Format: "{timestamp}:{session_id}"

< Base64-encoded HMAC-SHA1(secret, username)

< Host proves ownership

< Prove identity

< Session UUID

< Participant UUID

< All zeros = broadcast to all

< 0 = offer, 1 = answer

< Length of SDP data

< How long to reserve (1-365)

< Unix ms

< Error code (see acip_error_code_t)

< Human-readable error

Definition at line 1 of file network/acip/acds.h.

                                       {
  uint8_t identity_pubkey[32]; 
  uint8_t signature[64];       
  uint64_t timestamp;          
 
  uint8_t capabilities;     
  uint8_t max_participants; 
  uint8_t session_type;     
 
  uint8_t has_password;       
  uint8_t password_hash[128]; 
  uint8_t expose_ip_publicly; 
 
  uint8_t reserved_string_len; 
  // char  reserved_string[];        ///< Variable length, follows if len > 0
 
  // Server connection information (where clients should connect)
  // For DIRECT_TCP: server_address and server_port specify where to connect
  // For WEBRTC: these fields are ignored, signaling happens through ACDS
  char server_address[64]; 
  uint16_t server_port;    
} acip_session_create_t;

Variable Documentation

acip_error_t

acip_error_t

#include <acds.h>

Definition at line 448 of file network/acip/acds.h.

Referenced by acip_server_send_error(), and send_error_packet_message().

acip_session_create_t

acip_session_create_t

#include <acds.h>

Definition at line 115 of file network/acip/acds.h.

Referenced by acds_session_create().

acip_session_created_t

acip_session_created_t

#include <acds.h>

Definition at line 141 of file network/acip/acds.h.

Referenced by acds_session_create().

acip_session_end_t

acip_session_end_t

#include <acds.h>

Definition at line 278 of file network/acip/acds.h.

acip_session_info_t

acip_session_info_t

#include <acds.h>

Definition at line 191 of file network/acip/acds.h.

Referenced by acds_session_lookup().

acip_session_join_t

acip_session_join_t

#include <acds.h>

Definition at line 216 of file network/acip/acds.h.

Referenced by acds_session_join().

acip_session_joined_t

acip_session_joined_t

#include <acds.h>

Definition at line 248 of file network/acip/acds.h.

Referenced by acds_session_join().

acip_session_leave_t

acip_session_leave_t

#include <acds.h>

Definition at line 263 of file network/acip/acds.h.

acip_session_lookup_t

acip_session_lookup_t

#include <acds.h>

Definition at line 163 of file network/acip/acds.h.

Referenced by acds_session_lookup().

acip_session_reconnect_t

acip_session_reconnect_t

#include <acds.h>

Definition at line 294 of file network/acip/acds.h.

acip_string_release_t

acip_string_release_t

#include <acds.h>

Definition at line 425 of file network/acip/acds.h.

acip_string_renew_t

acip_string_renew_t

#include <acds.h>

Definition at line 408 of file network/acip/acds.h.

acip_string_reserve_t

acip_string_reserve_t

#include <acds.h>

Definition at line 374 of file network/acip/acds.h.

acip_string_reserved_t

acip_string_reserved_t

#include <acds.h>

Definition at line 390 of file network/acip/acds.h.

acip_webrtc_ice_t

acip_webrtc_ice_t

#include <acds.h>

Definition at line 347 of file network/acip/acds.h.

acip_webrtc_sdp_t

acip_webrtc_sdp_t

#include <acds.h>

Definition at line 325 of file network/acip/acds.h.