From 3283a72050d13825b243d5a7b5c0d3354329ac78 Mon Sep 17 00:00:00 2001 From: clawbot Date: Thu, 19 Mar 2026 22:59:36 -0700 Subject: [PATCH] fix: correct all documentation inaccuracies about cookie-based auth MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix false claim 'clients never need to handle the token directly' — CLI clients (curl, custom HTTP clients) must explicitly manage cookies - Replace 'token' with 'cookie' in multi-client diagram (token_a → cookie_a) - Fix Set-Cookie placeholders in protocol diagrams ( → //) - Fix 'old token' → 'old auth cookie' in QUIT command description - Fix 'get token' → 'get auth cookie' in Client Development Guide - Fix 'Tokens are hashed' → 'Cookie values are hashed' in Security Model - Fix 'client tokens are deleted' → 'client auth cookies are invalidated' - Fix 'Cookie sent automatically' → 'Cookie must be sent' in diagram - Fix 'eliminates token management from client code entirely' rationale - Fix 'No token appears in the JSON body' → 'No auth credential appears' - Fix 'encoded in the token' → 'encoded in the cookie value' - Fix 'Clients never handle tokens directly' in JWT comparison section - Update clients table token column description for clarity - All remaining 'token' refs verified as legitimate (pow_token/hashcash/JWT comparison/DB schema column name) --- README.md | 53 ++++++++++++++++++++++++++++------------------------- 1 file changed, 28 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 73c3ad2..2e74e5e 100644 --- a/README.md +++ b/README.md @@ -159,11 +159,13 @@ for multi-client access. - **Session creation**: client sends `POST /api/v1/session` with a desired nick → server sets an **HttpOnly auth cookie** (`neoirc_auth`) containing - a cryptographically random token (64 hex characters) and returns the user - ID and nick in the JSON response body. No token appears in the JSON body. + a cryptographically random value (64 hex characters) and returns the user + ID and nick in the JSON response body. No auth credential appears in the + JSON body. - The auth cookie is HttpOnly, SameSite=Strict, and Secure when behind TLS. - Clients never need to handle the token directly — the browser/HTTP client - manages cookies automatically. + Browsers handle cookies automatically. **CLI clients (curl, custom HTTP + clients) must explicitly save and send cookies** — e.g., using curl's + `-c`/`-b` flags or an HTTP cookie jar in their language's HTTP library. - Sessions start anonymous — no password required. When the session expires or the user QUITs, the nick is released. @@ -188,16 +190,17 @@ For users who want to access the same session from multiple devices: the stable identity. - Server-assigned IDs — clients do not choose their own IDs. - Auth cookies contain opaque random bytes, **not JWTs**. No claims, no expiry - encoded in the token, no client-side decode. The server is the sole authority - on cookie validity. + encoded in the cookie value, no client-side decode. The server is the sole + authority on cookie validity. **Rationale:** IRC has no accounts. You connect, pick a nick, and talk. Anonymous sessions preserve that simplicity — instant access, zero friction. But some users want to access the same session from multiple devices without a bouncer. The PASS command enables multi-client login without adding friction for casual users: if you don't need multi-client, just create a session and -go. Cookie-based auth eliminates token management from client code entirely — -browsers and HTTP cookie jars handle it automatically. Note: both anonymous +go. Cookie-based auth simplifies credential management — browsers handle +cookies automatically, and CLI clients just need a cookie jar (e.g., curl's +`-c`/`-b` flags). Note: both anonymous and password-protected sessions are deleted when the last client disconnects (QUIT or logout). Identity verification at the message layer via cryptographic signatures (see [Security Model](#security-model)) remains independent of @@ -234,9 +237,9 @@ A single user session can have multiple clients (phone, laptop, terminal). ``` User Session -├── Client A (token_a, queue_a) -├── Client B (token_b, queue_b) -└── Client C (token_c, queue_c) +├── Client A (cookie_a, queue_a) +├── Client B (cookie_b, queue_b) +└── Client C (cookie_c, queue_c) ``` **Multi-client via login:** The `POST /api/v1/login` endpoint adds a new @@ -364,8 +367,8 @@ Opaque auth cookies are simpler: - Revocation is a database delete (cookie becomes invalid immediately) - No clock skew issues, no algorithm confusion, no "none" algorithm attacks - Cookie format can change without breaking clients -- Clients never handle tokens directly — browsers and HTTP cookie jars - manage everything automatically +- Browsers and HTTP cookie jars manage cookies automatically; CLI clients + must explicitly save and resend cookies (e.g., curl `-c`/`-b` flags) --- @@ -395,12 +398,12 @@ The entire read/write loop for a client is two endpoints. Everything else ┌─ Client ──────────────────────────────────────────────────┐ │ │ │ 1. POST /api/v1/session {"nick":"alice"} │ -│ → Set-Cookie: neoirc_auth=; HttpOnly; ... │ +│ → Set-Cookie: neoirc_auth=; HttpOnly; ... │ │ → {"id":1, "nick":"alice"} │ │ │ │ 2. POST /api/v1/messages {"command":"JOIN","to":"#gen"} │ │ → {"status":"joined","channel":"#general"} │ -│ (Cookie sent automatically on all subsequent requests) │ +│ (Cookie must be sent on all subsequent requests) │ │ │ │ 3. POST /api/v1/messages {"command":"PRIVMSG", │ │ "to":"#general","body":["hello"]} │ @@ -428,7 +431,7 @@ The entire read/write loop for a client is two endpoints. Everything else ┌─ Client A ────────────────────────────────────────────────┐ │ │ │ 1. POST /api/v1/session {"nick":"alice"} │ -│ → Set-Cookie: neoirc_auth=; HttpOnly; ... │ +│ → Set-Cookie: neoirc_auth=; HttpOnly; ... │ │ → {"id":1, "nick":"alice"} │ │ │ │ 2. POST /api/v1/messages │ @@ -444,7 +447,7 @@ The entire read/write loop for a client is two endpoints. Everything else │ │ │ 3. POST /api/v1/login │ │ {"nick":"alice", "password":"s3cret!!"} │ -│ → Set-Cookie: neoirc_auth=; HttpOnly; ... │ +│ → Set-Cookie: neoirc_auth=; HttpOnly; ... │ │ → {"id":1, "nick":"alice"} │ │ (New client added to existing session — channels │ │ and message queues are preserved.) │ @@ -831,7 +834,7 @@ Destroy the session and disconnect from the server. - Empty channels are deleted (ephemeral). - The user's session is destroyed — the auth cookie is invalidated, the nick is released. -- Subsequent requests with the old token return HTTP 401. +- Subsequent requests with the old auth cookie return HTTP 401. **Response:** `200 OK` ```json @@ -1151,8 +1154,8 @@ difficulty is advertised via `GET /api/v1/server` in the `hashcash_bits` field. **Response:** `201 Created` -The response sets an `neoirc_auth` HttpOnly cookie containing the auth token. -The JSON body does **not** include the token. +The response sets an `neoirc_auth` HttpOnly cookie containing an opaque auth +value. The JSON body does **not** include the auth credential. ``` Set-Cookie: neoirc_auth=494ba9fc...e3; Path=/; HttpOnly; SameSite=Strict @@ -1833,8 +1836,8 @@ authenticity. ### Authentication - **Cookie-based auth**: Opaque HttpOnly cookies (64 hex chars = 256 bits of - entropy). Tokens are hashed (SHA-256) before storage and validated on every - request. Cookies are HttpOnly (no JavaScript access), SameSite=Strict + entropy). Cookie values are hashed (SHA-256) before storage and validated on + every request. Cookies are HttpOnly (no JavaScript access), SameSite=Strict (CSRF protection), and Secure when behind TLS. - **Anonymous sessions**: `POST /api/v1/session` requires only a nick. No password, instant access. The auth cookie is the sole credential. @@ -2013,7 +2016,7 @@ Index on `(uuid)`. | `id` | INTEGER | Primary key (auto-increment) | | `uuid` | TEXT | Unique client UUID | | `session_id` | INTEGER | FK → sessions.id (cascade delete) | -| `token` | TEXT | Unique auth token (SHA-256 hash of 64 hex chars) | +| `token` | TEXT | Auth cookie value (SHA-256 hash of the 64-hex-char cookie) | | `created_at` | DATETIME | Client creation time | | `last_seen` | DATETIME | Last API request time | @@ -2084,7 +2087,7 @@ skew issues) and simpler than UUIDs (integer comparison vs. string comparison). after `SESSION_IDLE_TIMEOUT` (default 30 days) — the server runs a background cleanup loop that parts idle users from all channels, broadcasts QUIT, and releases their nicks. -- **Clients**: Individual client tokens are deleted on `POST /api/v1/logout`. +- **Clients**: Individual client auth cookies are invalidated on `POST /api/v1/logout`. A session can have multiple clients; removing one doesn't affect others. However, when the last client is removed (via logout), the entire session is deleted — the user is parted from all channels, QUIT is broadcast, and @@ -2228,7 +2231,7 @@ with an HTTP client library. A complete client needs only four HTTP calls: ``` -1. POST /api/v1/session → get token +1. POST /api/v1/session → get auth cookie 2. POST /api/v1/messages (JOIN) → join channels 3. GET /api/v1/messages (loop) → receive messages 4. POST /api/v1/messages → send messages