@spec auth_daemon_opts(keyword()) :: {:ok, keyword()} | {:error, :ssh_auth_required}

Build the :ssh.daemon authentication options, failing closed.

Returns {:ok, opts} for allow_anonymous: true (no auth) or authorized_keys_dir: dir (public-key auth), and {:error, :ssh_auth_required} when neither is given so the caller refuses to start an anonymous surface.

@spec banner_probe(
  charlist() | String.t() | :inet.ip_address(),
  :inet.port_number(),
  timeout()
) :: :ok | {:error, :no_banner | :not_ssh | {:connect_failed, term()}}

Probe an SSH listener by reading its banner, not just opening a socket.

A daemon that accepts and immediately hangs up is indistinguishable from a working one to a bare connect, so a health check built on connect alone passes during the outage it exists to catch. :ok only when the peer actually says SSH-2.0.

@spec bind_address(keyword()) :: :any | :loopback

The address the daemon binds, decided from the auth posture.

Anonymous surfaces bind loopback unless the exposure is separately acknowledged with anonymous_public: true (or RAXOL_SSH_ANONYMOUS_PUBLIC=1 in the environment), so allow_anonymous: true alone can never open a surface to the network. Key-authenticated surfaces bind all interfaces.

Returns a specification to start this module under a supervisor.

See Supervisor.

@spec connection_count(GenServer.server()) :: non_neg_integer()

Returns the current number of active connections.

@spec default_host_keys_dir() :: String.t()

Default directory for SSH host keys: a persistent per-user path.

A host key under /tmp rotates on reboot, which trains clients to click through the host-key-changed warning -- the one warning that matters. Keys live under the user's home so they survive restarts.

@spec ensure_host_keys(String.t()) ::
  :ok | {:error, {:ssh_host_keys_insecure, [String.t()]}}

Ensure dir holds a usable host key, generating an ed25519 key with owner-only permissions when none exists (mode 0600 on POSIX, a protected current-user-only ACL on Windows). Fails closed with {:error, {:ssh_host_keys_insecure, paths}} when an existing key is readable by another identity: a readable host key means every client's host-key trust is forgeable, so the server must not start.

@spec format_peer(term()) :: String.t()

A peer address as a loggable string; anything that is not an IP tuple (the :unknown bucket) is printed as-is rather than crashing a log line.

@spec host_key_algs(String.t()) :: [String.t()]

Algorithm labels of the host keys present in dir, ed25519 first.

@spec missing_anonymous_caps(keyword()) :: [atom()]

The resource caps an anonymous surface must declare, or the empty list.

When auth is off, every cap is required explicitly (a positive integer; the timeouts are milliseconds) rather than defaulted: fifty concurrent anonymous shells must be a stated decision, not an omission. Authenticated surfaces keep their defaults and return [].

@spec port(GenServer.server()) :: :inet.port_number()

The port the daemon is actually listening on (resolved even when the server was started with port 0).

@spec posture_line(map()) :: String.t()

One greppable line stating the security posture this server resolved to: bind address, port, auth mode, resource caps, and host key algorithms. Logged at boot; the posture is the thing that goes wrong silently, so it is said out loud where people already look.

@spec register_connection(GenServer.server(), term()) ::
  :ok | {:error, :max_connections | :ip_limit}

Registers a new connection from peer_ip.

Returns :ok, {:error, :max_connections} (global cap), or {:error, :ip_limit} (this peer already holds max_per_ip connections, so a single host cannot exhaust the pool).

@spec sanitize_tenant(String.t() | charlist()) :: String.t() | nil

Normalize a client-supplied SSH username to a tenant name, or nil when it is not a safe, canonical path component. Shared with the tenant-option derivation so the key lookup and the workspace mapping can never disagree about which directory a username names. Names are canonical lowercase — a mixed-case username is refused, not case-folded, so one principal has exactly one path and one ledger key on every filesystem.

@spec tenant_user_dir(String.t(), String.t() | charlist()) :: String.t()

The per-tenant SSH key directory for user: <tenants_dir>/<user>/ssh (holding that tenant's authorized_keys). An unsafe username maps to a reserved path no tenant directory can ever occupy, so its key lookup fails and auth is refused.

@spec unregister_connection(GenServer.server(), term()) :: :ok

Unregisters a connection from peer_ip when it closes.