Startup

1. circada-server reads JSON config from -c/--config or CIRCADA_SERVER_CONFIG.

2. The config is passed to circada.server.new.

3. server:run() creates the Redis store if one was not injected.

4. The store bootstrap() step:

   • initializes server metadata on first run;

   • records the current PID and start time;

   • removes stale presence records for dead PIDs;

   • prunes missing channels from the channel index;

   • rebuilds the invisible-user counter.

5. ISUPPORT overrides are loaded from Redis.

6. TLS identity is loaded from tls.cert/tls.key.

7. The server binds host:port and starts accepting clients.

SIGTERM and SIGINT are handled by the CLI wrapper and call server:stop() for graceful shutdown.

Client registration

A new client starts with TLS user mode +Z. Registration requires:

• NICK

• USER

• completion of CAP negotiation, if started

• if sasl was negotiated: SASL success or SASL abort

Supported CAPs include:

• sasl=PLAIN

• server-time

• message-tags

• account-tag

• account-notify

• away-notify

• echo-message

• extended-join

SASL supports PLAIN only. Successful SASL sets the account, user mode +r, emits the standard logged-in/SASL success numerics, and allows registration to complete. Failed SASL blocks registration until the client either succeeds or aborts with AUTHENTICATE * followed by CAP END.

Nicknames reserved to an account cannot be used anonymously or by a different account.

Channel workflow

Joining a missing channel creates it with default modes:

+ntZ

The first user becomes the channel owner/operator. Channel state is stored in Redis:

• channel metadata and modes;

• topic and topic setter/time;

• member set;

• status sets: ops, halfops, admins, voiced;

• mask lists: bans, ban exceptions, invite exceptions, one-shot invites.

Implemented join/send gates include:

• +Z TLS-only channels;

• +R registered-account-only join/send;

• +E encrypted-channel orchestration mode (requires +R and +Z);

• +k channel key;

• +l member limit;

• +i invite-only with invite/invex masks;

• +b bans with ban exceptions;

• +n no external messages;

• +m moderated channels.

+E is set with MODE #chan +E by channel operators. Enabling +E also sets +R and +Z on the channel. MODE -E is rejected.

When the last user leaves a non-registered channel, the channel is deleted. Channels with mode +r are preserved.

Command handling

The server is table-dispatched by IRC command. Implemented handlers include:

• PING

• PONG

Additionally, the server sends periodic PING probes to idle clients. If a client does not answer before the next probe window, it is disconnected with QUIT :Ping timeout.

• CAP

• NICK

• USER

• AUTHENTICATE

• JOIN

• PART

• MODE

• TOPIC

• KICK

• WHO

• WHOIS

• LIST

• AWAY

• PRIVMSG

• NOTICE

• TAGMSG

• QUIT

• IDENTITY

• CKEY

WHO respects secret channels and invisible users. Invisible users are visible to themselves, opers, and clients that share a channel with them.

LIST returns channel information for all visible channels. Secret (+s) and private (+p) channels are hidden from non-members; oper clients can see all channels. An optional comma-separated channel list can be provided to filter results.

AWAY sets or clears the user's away status. Setting away notifies shared-channel peers who negotiated away-notify. Sending a PRIVMSG to an away user returns 301 (RPL_AWAY) to the sender.

account-notify broadcasts ACCOUNT <nick> or ACCOUNT * to shared-channel peers who negotiated the cap when the user logs in or out via SASL.

Outbound tags are filtered per recipient capability. For example, account-tag is only delivered to clients that negotiated account-tag.

IDENTITY and CKEY are CIRCADA-specific encrypted-channel commands. They use tagged NOTICE responses (@+circada/enc=1) for status, errors, and orchestration events.

IDENTITY subcommands:

• IDENTITY REGISTER <ed25519_pk_b64> <sig_b64>

• IDENTITY SHOW [account|nick]

• IDENTITY FINGERPRINT <account>

Registration is tied to the authenticated SASL account. REGISTER verifies that the provided signature signs the canonical account string with the submitted Ed25519 public key. On success the server derives and stores the account X25519 public key and fingerprint.

CKEY subcommands:

• CKEY FETCH <channel> [epoch]

• CKEY INIT <channel> <epoch> <self_wrap_b64>

• CKEY WRAP <channel> <target_account> <wrap_b64>

• CKEY ROTATE_BEGIN <channel> <new_epoch>

• CKEY ROTATE_WRAP <channel> <new_epoch> <account> <wrap_b64>

• CKEY ROTATE_COMMIT <channel> <new_epoch> <sig_b64>

• CKEY ROTATE_ABORT <channel> <new_epoch>

Orchestration notices include:

• CKEY INIT_REQUEST <channel> <epoch> <creator_identity_blob>

• CKEY WRAP_REQUEST <channel> <joiner_account> <joiner_identity_blob>

• CKEY WRAP_DELIVERY <channel> <epoch> <wrap_b64>

• CKEY ROTATE_REQUEST <channel> <new_epoch>

• CKEY ROTATE_MEMBER <channel> <new_epoch> <account> <identity_blob>

Error/status tokens are carried via CKEY ERROR <code> <target> :text. Examples: NOIDENTITY, BADSIG, IDENTITY_EXISTS, PENDING, NOTENCRYPTED, ENCDATA.

ROTATE_COMMIT signatures are mandatory. The server verifies the submitted Ed25519 signature against the rotator's registered identity and stores the submitted base64 signature in the channel audit log.

The standalone server never decrypts channel payloads. Encrypted channel messages are ordinary PRIVMSGs with opaque payload and +circada/* tags, e.g.:

@+circada/enc=1;+circada/epoch=2;+circada/nonce=...;+circada/seq=42 PRIVMSG #chan :<ciphertext_b64>

Server join/send policy still applies (+n, +m, +R, +Z, bans, invites, etc.).

Top-level fields

The admin CLI also accepts the same JSON config file. If no config file is supplied, Redis can be selected with flags:

circadactl-server \
  --redis-host 127.0.0.1 \
  --redis-port 6379 \
  --redis-db 11 \
  --prefix CIRCADA \
  account list

Minimal systemd user unit

[Unit]
Description=CIRCADA standalone IRC server
After=network-online.target redis.service
Wants=network-online.target

[Service]
Type=simple
ExecStart=%h/.local/bin/circada-server -c %h/.config/circada/server.json
Restart=on-failure
RestartSec=5
TimeoutStopSec=10

[Install]
WantedBy=default.target

Adjust paths and service ordering for your Redis deployment.

Account management

Create an account with an interactive password prompt:

circadactl-server -c /etc/circada/server.json account add alice

or pass the password explicitly:

circadactl-server -c /etc/circada/server.json account add alice 'secret-password'

List accounts:

circadactl-server -c /etc/circada/server.json account list

Delete an account and its reserved nick mappings:

circadactl-server -c /etc/circada/server.json account del alice

Reserve and release nicks:

circadactl-server -c /etc/circada/server.json account reserve-nick alice Alice
circadactl-server -c /etc/circada/server.json account release-nick alice Alice

A reserved nick can only be used by clients logged into the owning account.

ISUPPORT overrides

Set, delete, and list ISUPPORT values:

circadactl-server -c /etc/circada/server.json isupport set NETWORK ExampleNet
circadactl-server -c /etc/circada/server.json isupport del NETWORK
circadactl-server -c /etc/circada/server.json isupport list

Overrides are merged into the server's generated ISUPPORT map at startup. Restart the server after changing them.

Server/network rename

circadactl-server -c /etc/circada/server.json rename server-name irc.example.com
circadactl-server -c /etc/circada/server.json rename network-name ExampleNet

These commands update Redis metadata. On first bootstrap, config values seed metadata. On later bootstraps, existing metadata is preserved so admin renames survive restarts.