discovery.h File Reference

Parallel mDNS and ACDS session discovery. More...

Go to the source code of this file.

Data Structures
struct	discovery_result_t
	Result from session discovery. More...
struct	discovery_config_t
	Session discovery configuration. More...

Functions
void	discovery_config_init_defaults (discovery_config_t *config)
	Initialize discovery config with defaults.
asciichat_error_t	discover_session_parallel (const char *session_string, const discovery_config_t *config, discovery_result_t *result)
	Look up session in parallel on mDNS and ACDS.
bool	is_session_string (const char *str)
	Check if a string matches session string pattern.
discovery_tui_server_t *	discovery_mdns_query (int timeout_ms, int max_servers, bool quiet, int *out_count)
	Discover ASCII-Chat servers on local network via mDNS.
void	discovery_mdns_free (discovery_tui_server_t *servers)
	Free memory from mDNS discovery results.
void	pubkey_to_hex (const uint8_t pubkey[32], char hex_out[65])
	Convert Ed25519 public key to hex string.
asciichat_error_t	hex_to_pubkey (const char *hex_str, uint8_t pubkey_out[32])
	Convert hex string to Ed25519 public key.

Detailed Description

Parallel mDNS and ACDS session discovery.

Implements concurrent lookup on both mDNS (local LAN) and ACDS (internet discovery) with "race to success" semantics - whichever discovery method finds the session first is used.

Three Usage Modes:

1. mDNS-only (safest, no ACDS)
   • Input: session string only
   • Searches mDNS for TXT record containing session_string
   • No ACDS lookup, no network calls
   • Use case: Local LAN connections where server is on same network
   • Command: ascii-chat swift-river-mountain
2. Verified ACDS (parallel with pubkey check)
   • Input: session string + expected server pubkey
   • Searches mDNS (timeout 2s) AND ACDS (timeout 5s) in parallel threads
   • Verifies discovered server pubkey matches expected key in BOTH sources
   • Requires explicit --server-key flag with Ed25519 public key
   • Command: ascii-chat --server-key $pubkey swift-river-mountain
3. Insecure ACDS (parallel without verification)
   • Input: session string only
   • Searches mDNS (timeout 2s) AND ACDS (timeout 5s) in parallel threads
   • No pubkey verification (MITM-vulnerable, requires explicit --acds-insecure flag)
   • Use case: Test/development environments only
   • Command: ascii-chat --acds-insecure swift-river-mountain

Thread Architecture:

Both lookups run concurrently:

discover_session_parallel()
  │
  ├─ Thread A (mDNS):
  │   └─ Query TXT records, parse session_string
  │   └─ Extract host_pubkey from TXT
  │   └─ Return: IPv4/IPv6, port, pubkey (2s timeout)
  │
  ├─ Thread B (ACDS):
  │   └─ Connect to ACDS server
  │   └─ SESSION_LOOKUP request
  │   └─ Return: host_pubkey, session_info (5-8s timeout)
  │   └─ SESSION_JOIN to get server_address/port
  │
  └─ Whichever completes first wins, other is cancelled

Security Model:

• mDNS verification: TXT record contains host_pubkey=<hex>, client checks against --server-key
• ACDS verification: ACDS stores host_pubkey, SESSION_LOOKUP returns it, client verifies
• Cross-verification: If both succeed, MUST have same pubkey (prevents split-brain)
• TOFU on first use: When no --server-key specified, mDNS-only mode (trust first TXT record seen)

Author

Claude claud.nosp@m.e@an.nosp@m.throp.nosp@m.ic.c.nosp@m.om

Date

January 2026

Definition in file discovery.h.

Function Documentation

discover_session_parallel()

asciichat_error_t discover_session_parallel	(	const char *	session_string,
		const discovery_config_t *	config,
		discovery_result_t *	result
	)

Look up session in parallel on mDNS and ACDS.

Spawns two concurrent threads to search both mDNS (local LAN) and ACDS (internet). Returns immediately when either finds the session, cancelling the other search.

Verification Logic:

If config->expected_pubkey is set:

• mDNS result: Verify TXT record contains matching host_pubkey
• ACDS result: Verify SESSION_LOOKUP response contains matching host_pubkey
• If both find result: Verify they have same pubkey (cross-check)
• On mismatch: Return ERROR_CRYPTO_VERIFY_FAILED

If config->expected_pubkey is NULL but config->insecure_mode is true:

• Skip all verification, accept first result found
• WARNING: Vulnerable to MITM attacks!

If config->expected_pubkey is NULL and config->insecure_mode is false:

• Search mDNS only (ACDS thread not started)
• Use TOFU (Trust On First Use): accept first mDNS result found

Thread Lifecycle:

• Both threads start immediately
• Whichever completes first signals success via condition variable
• Other thread is joined (cleaned up)
• Function returns with result

Parameters

session_string	Session string to find (e.g., "swift-river-mountain")
config	Discovery configuration
result	Discovery result (output)

Returns

ASCIICHAT_OK on success, error code on failure

Note

This function BLOCKS until one discovery method succeeds or both timeout

Not thread-safe for concurrent calls - use only one discovery at a time

Definition at line 655 of file discovery.c.

                                                                        {
  if (!session_string || !config || !result) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters to discover_session_parallel");
    return ERROR_INVALID_PARAM;
  }
 
  // Validate session string format
  if (!is_session_string(session_string)) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid session string format");
    return ERROR_INVALID_PARAM;
  }
 
  memset(result, 0, sizeof(*result));
  log_info("Discovery: Looking up session '%s'", session_string);
 
  // Initialize thread state
  discovery_thread_state_t state;
  memset(&state, 0, sizeof(state));
  state.result = result;
  mutex_init(&state.lock);
  cond_init(&state.signal);
 
  // Determine which discovery methods to use
  bool use_mdns = true;
  bool use_acds = config->expected_pubkey != NULL || config->insecure_mode;
 
  if (!use_acds) {
    log_debug("Discovery: mDNS-only mode (no --server-key and no --acds-insecure)");
  }
 
  // Spawn mDNS thread
  asciichat_thread_t mdns_thread;
  asciichat_thread_init(&mdns_thread);
 
  if (use_mdns) {
    mdns_thread_context_t *mdns_ctx = SAFE_MALLOC(sizeof(*mdns_ctx), mdns_thread_context_t *);
    if (!mdns_ctx) {
      SET_ERRNO(ERROR_MEMORY, "Failed to allocate mDNS context");
      mutex_destroy(&state.lock);
      cond_destroy(&state.signal);
      return ERROR_MEMORY;
    }
 
    mdns_ctx->session_string = session_string;
    mdns_ctx->state = &state;
    mdns_ctx->expected_pubkey = config->expected_pubkey;
 
    int thread_err = asciichat_thread_create(&mdns_thread, mdns_thread_fn, mdns_ctx);
    if (thread_err != 0) {
      log_warn("Discovery: Failed to spawn mDNS thread");
      SAFE_FREE(mdns_ctx);
      use_mdns = false;
    }
  }
 
  // Spawn ACDS thread
  asciichat_thread_t acds_thread;
  asciichat_thread_init(&acds_thread);
 
  if (use_acds) {
    acds_thread_context_t *acds_ctx = SAFE_MALLOC(sizeof(*acds_ctx), acds_thread_context_t *);
    if (!acds_ctx) {
      SET_ERRNO(ERROR_MEMORY, "Failed to allocate ACDS context");
      if (use_mdns && asciichat_thread_is_initialized(&mdns_thread)) {
        asciichat_thread_join(&mdns_thread, NULL);
      }
      mutex_destroy(&state.lock);
      cond_destroy(&state.signal);
      return ERROR_MEMORY;
    }
 
    acds_ctx->session_string = session_string;
    acds_ctx->state = &state;
    acds_ctx->config = config;
 
    int thread_err = asciichat_thread_create(&acds_thread, acds_thread_fn, acds_ctx);
    if (thread_err != 0) {
      log_warn("Discovery: Failed to spawn ACDS thread");
      SAFE_FREE(acds_ctx);
      use_acds = false;
    }
  }
 
  // Wait for result (mDNS timeout 2s + ACDS timeout 5s max)
  uint32_t wait_timeout_ms = config->acds_timeout_ms + 1000;
  mutex_lock(&state.lock);
  {
    uint32_t elapsed_ms = 0;
    while (!state.found && elapsed_ms < wait_timeout_ms) {
      // Check if both threads are done
      if (state.mdns_done && state.acds_done) {
        break;
      }
 
      // Wait with timeout
      cond_timedwait(&state.signal, &state.lock, 500);
      elapsed_ms += 500;
    }
  }
  mutex_unlock(&state.lock);
 
  // Join threads
  if (use_mdns && asciichat_thread_is_initialized(&mdns_thread)) {
    asciichat_thread_join(&mdns_thread, NULL);
  }
  if (use_acds && asciichat_thread_is_initialized(&acds_thread)) {
    asciichat_thread_join(&acds_thread, NULL);
  }
 
  // Cleanup
  mutex_destroy(&state.lock);
  cond_destroy(&state.signal);
 
  // Check result
  if (!result->success) {
    SET_ERRNO(ERROR_NOT_FOUND, "Session '%s' not found (mDNS/ACDS timeout)", session_string);
    return ERROR_NOT_FOUND;
  }
 
  log_info("Discovery: Session '%s' discovered via %s", session_string,
           result->source == DISCOVERY_SOURCE_MDNS ? "mDNS" : "ACDS");
 
  return ASCIICHAT_OK;
}

References discovery_thread_state_t::acds_done, discovery_config_t::acds_timeout_ms, ASCIICHAT_OK, asciichat_thread_create(), asciichat_thread_init(), asciichat_thread_is_initialized(), asciichat_thread_join(), cond_destroy(), cond_init(), cond_timedwait(), acds_thread_context_t::config, ERROR_INVALID_PARAM, ERROR_MEMORY, ERROR_NOT_FOUND, mdns_thread_context_t::expected_pubkey, discovery_config_t::expected_pubkey, discovery_thread_state_t::found, discovery_config_t::insecure_mode, is_session_string(), discovery_thread_state_t::lock, log_debug, log_info, log_warn, discovery_thread_state_t::mdns_done, mutex_destroy(), mutex_init(), mutex_lock, mutex_unlock, discovery_thread_state_t::result, SAFE_FREE, SAFE_MALLOC, mdns_thread_context_t::session_string, acds_thread_context_t::session_string, SET_ERRNO, discovery_thread_state_t::signal, discovery_result_t::source, mdns_thread_context_t::state, acds_thread_context_t::state, and discovery_result_t::success.

Referenced by client_main().

discovery_config_init_defaults()

void discovery_config_init_defaults

(

discovery_config_t *

config

)

Initialize discovery config with defaults.

Sets sensible defaults:

• ACDS server: localhost:27225 (debug), acds.ascii-chat.com (release)
• Timeouts: mdns=2000ms, acds=5000ms
• Verification: None (expected_pubkey=NULL)
• Insecure mode: false

Parameters

config

Configuration to initialize

Definition at line 633 of file discovery.c.

                                                                {
  if (!config)
    return;
 
  memset(config, 0, sizeof(*config));
 
  // Check if debug or release build
#ifdef NDEBUG
  // Release: use internet ACDS
  strncpy(config->acds_server, "discovery.ascii-chat.com", sizeof(config->acds_server) - 1);
#else
  // Debug: use local ACDS
  strncpy(config->acds_server, "127.0.0.1", sizeof(config->acds_server) - 1);
#endif
 
  config->acds_port = 27225;
  config->mdns_timeout_ms = 2000;
  config->acds_timeout_ms = 5000;
  config->insecure_mode = false;
  config->expected_pubkey = NULL;
}

References discovery_config_t::acds_port, discovery_config_t::acds_server, discovery_config_t::acds_timeout_ms, discovery_config_t::expected_pubkey, discovery_config_t::insecure_mode, and discovery_config_t::mdns_timeout_ms.

Referenced by client_main().

discovery_mdns_free()

void discovery_mdns_free

(

discovery_tui_server_t *

servers

)

Free memory from mDNS discovery results.

Definition at line 408 of file discovery.c.

                                                          {
  SAFE_FREE(servers);
}

References SAFE_FREE.

Referenced by discovery_tui_free_results().

discovery_mdns_query()

discovery_tui_server_t * discovery_mdns_query	(	int	timeout_ms,
		int	max_servers,
		bool	quiet,
		int *	out_count
	)

Discover ASCII-Chat servers on local network via mDNS.

Queries for mDNS _ascii-chat._tcp services and returns discovered servers. This is the core discovery function used by both:

• Parallel discovery threads (discover_session_parallel)
• TUI wrapper (discovery_tui_query)

Parameters

timeout_ms	Query timeout in milliseconds (default: 2000)
max_servers	Maximum servers to discover (default: 20)
quiet	If true, suppresses progress messages
out_count	Output: number of servers discovered

Returns

Array of discovered servers, or NULL on error. Use discovery_mdns_free() to free.

Discover ASCII-Chat servers on local network via mDNS.

Parameters

timeout_ms	Query timeout in milliseconds
max_servers	Maximum servers to discover
quiet	If true, suppresses progress messages
out_count	Output: number of servers discovered

Returns

Array of discovered servers, or NULL on error. Use discovery_mdns_free() to free.

Definition at line 320 of file discovery.c.

                                                                                                          {
  if (!out_count) {
    SET_ERRNO(ERROR_INVALID_PARAM, "out_count pointer is NULL");
    return NULL;
  }
 
  *out_count = 0;
 
  // Apply defaults
  if (timeout_ms <= 0) {
    timeout_ms = 2000;
  }
  if (max_servers <= 0) {
    max_servers = 20;
  }
 
  // Allocate state for collecting servers
  mdns_query_state_t state;
  memset(&state, 0, sizeof(state));
  state.capacity = max_servers;
  state.timeout_ms = timeout_ms;
  state.start_time_ms = discovery_get_time_ms();
 
  // Allocate server array
  state.servers = SAFE_MALLOC((size_t)state.capacity * sizeof(discovery_tui_server_t), discovery_tui_server_t *);
  if (!state.servers) {
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate mDNS discovery server array");
    return NULL;
  }
  memset(state.servers, 0, state.capacity * sizeof(discovery_tui_server_t));
 
  if (!quiet) {
    log_info("mDNS: Searching for ASCII-Chat servers on local network (timeout: %dms)", state.timeout_ms);
    printf("🔍 Searching for ASCII-Chat servers on LAN...\n");
  }
 
  // Initialize mDNS
  asciichat_mdns_t *mdns = asciichat_mdns_init();
  if (!mdns) {
    log_warn("mDNS: Failed to initialize mDNS - discovery unavailable");
    SAFE_FREE(state.servers);
    return NULL;
  }
 
  // Start mDNS query for _ascii-chat._tcp services
  asciichat_error_t query_result =
      asciichat_mdns_query(mdns, "_ascii-chat._tcp.local", discovery_mdns_callback, &state);
 
  if (query_result != ASCIICHAT_OK) {
    log_info("mDNS: Query failed - no servers found via service discovery");
    asciichat_mdns_shutdown(mdns);
    SAFE_FREE(state.servers);
    return NULL;
  }
 
  // Poll for responses until timeout
  int64_t deadline = state.start_time_ms + state.timeout_ms;
  while (!state.query_complete && discovery_get_time_ms() < deadline) {
    int poll_timeout = (int)(deadline - discovery_get_time_ms());
    if (poll_timeout < 0) {
      poll_timeout = 0;
    }
    if (poll_timeout > 100) {
      poll_timeout = 100; // Check every 100ms
    }
    asciichat_mdns_update(mdns, poll_timeout);
  }
 
  // Cleanup mDNS
  asciichat_mdns_shutdown(mdns);
 
  if (!quiet) {
    if (state.count > 0) {
      printf("✅ Found %d ASCII-Chat server%s on LAN\n", state.count, state.count == 1 ? "" : "s");
      log_info("mDNS: Found %d server(s)", state.count);
    } else {
      printf("❌ No ASCII-Chat servers found on LAN\n");
      log_info("mDNS: No servers found");
    }
  }
 
  *out_count = state.count;
  return state.servers;
}

References asciichat_mdns_init(), asciichat_mdns_query(), asciichat_mdns_shutdown(), asciichat_mdns_update(), ASCIICHAT_OK, mdns_query_state_t::capacity, mdns_query_state_t::count, ERROR_INVALID_PARAM, ERROR_MEMORY, log_info, log_warn, mdns_query_state_t::query_complete, SAFE_FREE, SAFE_MALLOC, mdns_query_state_t::servers, SET_ERRNO, mdns_query_state_t::start_time_ms, and mdns_query_state_t::timeout_ms.

Referenced by discovery_tui_query().

hex_to_pubkey()

asciichat_error_t hex_to_pubkey	(	const char *	hex_str,
		uint8_t	pubkey_out[32]
	)

Convert hex string to Ed25519 public key.

Converts 64-character hex string to 32-byte binary pubkey.

Parameters

hex_str	Hex string (64 characters)
pubkey_out	Output binary pubkey (32 bytes)

Returns

ASCIICHAT_OK on success, ERROR_INVALID_PARAM if invalid hex

Definition at line 55 of file discovery.c.

                                                                             {
  if (!hex_str || !pubkey_out) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid hex_str or pubkey_out pointer");
    return ERROR_INVALID_PARAM;
  }
 
  if (strlen(hex_str) != 64) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Hex string must be exactly 64 characters");
    return ERROR_INVALID_PARAM;
  }
 
  for (int i = 0; i < 32; i++) {
    char hex_byte[3];
    hex_byte[0] = hex_str[i * 2];
    hex_byte[1] = hex_str[i * 2 + 1];
    hex_byte[2] = '\0';
 
    if (!isxdigit(hex_byte[0]) || !isxdigit(hex_byte[1])) {
      SET_ERRNO(ERROR_INVALID_PARAM, "Invalid hex character in string");
      return ERROR_INVALID_PARAM;
    }
 
    pubkey_out[i] = (uint8_t)strtol(hex_byte, NULL, 16);
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, and SET_ERRNO.

Referenced by client_main().

is_session_string()

bool is_session_string

(

const char *

str

)

Check if a string matches session string pattern.

Validates that input matches three-word pattern: word-word-word Each word is 3-64 characters of alphanumerics and hyphens (RFC 952).

Examples:

• ✅ swift-river-mountain - valid
• ✅ cat-dog-bird - valid
• ❌ swift - invalid (only one word)
• ❌ swift-river- - invalid (trailing hyphen)
• ❌ swift_river_mountain - invalid (underscores not allowed)

Parameters

str	String to validate

Returns

true if matches session string pattern, false otherwise

Note

Used by src/main.c to detect binary-level session string argument

Definition at line 83 of file discovery.c.

                                        {
  if (!str || strlen(str) == 0)
    return false;
 
  // Parse as word-word-word where each word is 3-64 alphanumerics
  // Hyphens are separators between words
  // No leading/trailing hyphens, no consecutive hyphens
  size_t len = strlen(str);
 
  // Check length bounds (minimum: "a-a-a" = 5, maximum: 64 chars per word * 3 + 2 hyphens = 194)
  if (len < 5 || len > 194) {
    return false;
  }
 
  // Must not start or end with hyphen
  if (str[0] == '-' || str[len - 1] == '-') {
    return false;
  }
 
  // Count words separated by hyphens
  int word_count = 1; // Start with 1 (not 0) to account for first word
  int current_word_len = 0;
  bool last_was_hyphen = false;
 
  for (size_t i = 0; i < len; i++) {
    char c = str[i];
 
    if (isalnum(c)) {
      current_word_len++;
 
      // Individual word must be 3-64 characters
      if (current_word_len > 64) {
        return false;
      }
      last_was_hyphen = false;
    } else if (c == '-') {
      // Hyphen marks end of current word
      if (last_was_hyphen) {
        // Consecutive hyphens
        return false;
      }
 
      // Current word must have been at least 3 chars
      if (current_word_len < 3) {
        return false;
      }
 
      word_count++;
      current_word_len = 0;
      last_was_hyphen = true;
    } else {
      // Invalid character
      return false;
    }
  }
 
  // Final word must be 3-64 characters
  if (current_word_len < 3 || current_word_len > 64) {
    return false;
  }
 
  // Must have exactly 3 words
  return word_count == 3;
}

Referenced by discover_session_parallel(), and parse_client_address().

pubkey_to_hex()

void pubkey_to_hex	(	const uint8_t	pubkey[32],
		char	hex_out[65]
	)

Convert Ed25519 public key to hex string.

Converts 32-byte binary pubkey to lowercase hex (64 characters).

Parameters

pubkey	Binary public key (32 bytes)
hex_out	Output hex string buffer (must be at least 65 bytes)

Definition at line 46 of file discovery.c.

                                                               {
  if (!pubkey || !hex_out)
    return;
  for (int i = 0; i < 32; i++) {
    sprintf(hex_out + (i * 2), "%02x", pubkey[i]);
  }
  hex_out[64] = '\0';
}