Identity & Authentication

Clubs, credentials, the lock hierarchy, KeyMaster authority, OAuth2 login, email verification, the authentication flow with rate limiting, CSRF protection, and the tamper-evident security audit chain — the complete identity and access control system.

1. Clubs — Identity and Permission Units

In Udanax-Gold, a Club is the fundamental identity unit. Every user, group, and permission set is a Club. Clubs own works, control access, and sign content. There is no separate "user" concept — everything is a Club.

Club structure

Club types

System clubs

Every server starts with four system clubs created at initialization:

2. Credentials

A club can have one of two credential types:

When a password is set, the server also generates (or re-encrypts) the club's Ed25519 signing key, encrypted with a key derived from the password via Argon2id:

// From identity.rs club_set_password()
if is_personal {
    if let Some(existing_sk) = existing_signing_key {
        // Re-encrypt the signing key with the new password
        let encrypted = encrypt_signing_key(&sk, password)?;
        club.set_encrypted_signing_key(Some(encrypted));
    } else if club.encrypted_signing_key().is_none() {
        // Generate a new Ed25519 keypair for this club
        let (encrypted, signing_key) = generate_club_keypair(password)?;
        club.set_encrypted_signing_key(Some(encrypted));
        session.set_club_signing_key(Some(signing_key));  // available in-session
    }
}

3. The Lock Hierarchy

Locks control access to clubs. A club may have a lock that must be opened before the club's authority can be used. The lock system implements the Strategy pattern via the Lock trait:

The Lock hierarchy. Each lock type implements the Lock trait. MultiLock composes multiple locks (OR semantics).

Lock types

4. KeyMaster — Authority Tracking

The KeyMaster tracks which clubs a session has proven identity for. When a lock is opened, the resulting KeyMaster contains the set of authorized club IDs.

Two kinds of authority

After successful login, update_authority() walks the club membership graph to expand actual_authority — if you're a member of "editors" and "editors" is a member of "staff", you get authority over all three.

Signature authority

For provenance signing, the KeyMaster also tracks signature authority — the right to use a club's signing key. This is checked via has_signature_authority(club_id, &clubs), which walks the signature_club chain to verify the session controls the key.

5. The Authentication Flow

Authentication is a two-step challenge-response protocol. The client first requests a lock (step 1), then submits credentials to open it (step 2):

The two-step authentication flow. The server stores the lock as "pending" on the session between steps 1 and 2.

What happens on success

1. The KeyMaster is created with authority for the club
2. update_authority() expands to include group memberships
3. If login was via password, the club's encrypted signing key is decrypted and stored in the session (in-memory only)
4. The rate-limit counter is cleared
5. The event is logged as SECURITY:login_succeeded

Public login (anonymous)

For anonymous access, the server uses a BooLock that always opens:

pub fn login_public(&mut self, session_id: SessionId) -> Result<KeyMaster, ServerError> {
    let lock = BooLock::new(self.system_clubs.public_club);
    self.authenticate(session_id, &lock, &LockCredential::Boo)
}

6. Rate Limiting & Brute-Force Protection

Xudanu implements per-club rate limiting for login attempts. This is deliberately per-club (not per-IP) because:

• Multiple users may share an IP (NAT, corporate network)
• An attacker targeting a specific account should be blocked regardless of source IP
• The IP-level rate limiting is handled separately by the SecurityMonitor

The rate limit is checked in authenticate_with_pending before attempting to open the lock:

if let Some(tracker) = self.login_attempts.get_mut(&club_id) {
    if now.duration_since(tracker.window_start) > CLUB_LOGIN_ATTEMPT_WINDOW {
        tracker.count = 0;     // window reset
        tracker.window_start = now;
    }
    if tracker.count >= MAX_CLUB_LOGIN_ATTEMPTS {
        security_warn!(
            club_id = ?club_id,
            event = "SECURITY:login_rate_limited",
            "login rate limited"
        );
        return Err(ServerError::Unauthorized(
            "too many login attempts for this account, try again later".into()
        ));
    }
}

7. CSRF Protection

The WebSocket connection is protected by CSRF (Cross-Site Request Forgery) tokens. The server generates a random token that the client must include in the WebSocket upgrade request:

8. OAuth2: GitHub & Google Login

Xudanu supports OAuth2 login through GitHub and Google, allowing users to authenticate without creating a password. The flow follows the standard OAuth2 authorization code pattern.

The OAuth2 flow. The state token prevents CSRF attacks on the callback. After fetching the user profile, the server finds or creates a club and establishes a session.

OAuth state management

Account linking

When a user signs in via OAuth for the first time, the server creates a personal club with no password (OAuth is the credential). On subsequent logins, the find_link() method looks up the existing club by (provider, provider_user_id). A single club can be linked to both GitHub and Google simultaneously.

CLI flags

--github-client-id <id>       --github-client-secret <secret>
--google-client-id <id>       --google-client-secret <secret>
--oauth-redirect-base <url>

9. Email Verification

Personal clubs can have an email address that must be verified before the account is considered trusted. The verification system uses single-use BLAKE3-hashed tokens with a 24-hour TTL.

The flow

1. Signup: Client creates a personal club and sets an email via club_set_email()
2. Issue: VerificationTokenStore::issue(club_id, email) generates a 32-byte random token, stores its BLAKE3 hash (the raw token is never persisted), and returns the raw token
3. Deliver: The EmailProvider sends a verification URL (https://server/verify?token=...) to the email address
4. Redeem: The user clicks the link; redeem(raw_token) hashes it, looks up the pending entry, checks expiry, atomically removes it (single-use), and returns (club_id, email)
5. Mark verified: mark_club_verified(club_id) sets the club's verified flag

Email providers

Token parameters

10. Session Lifecycle

1. Connect: WebSocket connection established. A Session is created with a unique SessionId. Default timeout: 1 hour (DEFAULT_SESSION_TIMEOUT = 3600s).
2. Authenticate: Client calls login(club_id) then authenticate_with_pending(credential). On success, the session gains KeyMaster authority and (if password login) the decrypted Ed25519 signing key.
3. Author identity: For CRDT editing, the session registers an OtreeAuthorIdentity (public key, display name, club ID) for attribution.
4. Operate: All subsequent operations are performed under the session's authority. The SecurityMonitor tracks request rate, violations, and permission denials.
5. Disconnect / timeout: Session is cleaned up. Awareness state is removed from CRDT. Active edits are preserved (auto-saved via CRDT materialization). The signing key is dropped from memory.

Session fields

11. The Security Audit Chain

Every security-relevant event is written to a tamper-evident chained log at data/security.log.*. The log uses SHA-256 chaining: each line's hash incorporates the previous line's hash, forming an unbreakable chain from a random seed file (security.log.seed).

The chained hash makes tampering detectable. Modifying any line invalidates all subsequent chain hashes.

The ChainedLogWriter

The ChainedLogWriter<W: Write> is a generic writer that transparently adds chain hashes. It wraps any Write target (file, stdout):

impl<W: Write> Write for ChainedLogWriter<W> {
    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
        let line = String::from_utf8_lossy(buf);
        let chain_input = format!("{}{}", self.prev_hash, line.trim());
        let chain_hash = sha256_hex(chain_input.as_bytes());
        self.prev_hash = chain_hash.clone();
        let chained_line = format!("{} chain={}\n", line.trim(), chain_hash);
        self.inner.write_all(chained_line.as_bytes())?;
        Ok(buf.len())
    }
}

Verification

The verify-security-log CLI subcommand walks the entire log from the seed and checks every chain hash:

cargo run --release --features server --bin xudanu-server -- verify-security-log data

The same chain technique is used by the attribution log for tamper-evident provenance recording.

12. SecurityMonitor & Threat Detection

The SecurityMonitor (in transport/audit.rs) is the real-time defense layer. It tracks counters per-session and per-IP, escalating threat levels when patterns are detected.

Audit event types

Threat levels

Each session and IP accumulates a ThreatLevel based on sliding-window counters:

Sliding window counters

The monitor uses SlidingCounter — a fixed-window counter that resets after the window expires:

struct SlidingCounter {
    count: u32,
    window_start: Instant,
    window_secs: u64,
}

impl SlidingCounter {
    fn bump(&mut self) -> u32 {
        if self.window_start.elapsed().as_secs() >= self.window_secs {
            self.count = 0;                    // window expired, reset
            self.window_start = Instant::now();
        }
        self.count += 1;
        self.count
    }
}

Counters are tracked both per-session and per-IP, giving both granular (this session is malicious) and aggregate (this IP is running a botnet) detection.

13. Security Configuration Reference

The SecurityConfig struct controls all rate-limiting thresholds:

Club login rate limiting (separate)

Audit log backends

14. Provenance & Attribution

Once authenticated, every edit a session makes is cryptographically signed with the club's Ed25519 key. This creates per-span provenance that answers "who wrote this?" at the character level. The full provenance system — signing, verification, the tamper-evident attribution log, transclusion attribution, historical attestation, attestation reports, federation cluster consensus, and W3C PROV-JSON export — is documented in the dedicated guide:

15. Udanax-Gold Comparison

16. Source Code Map