AUTH

Tellstone supports optional password-based authentication. When --require-pass is set, every connection must authenticate before issuing data commands (GET, SET, DEL). PING and QUIT are allowed before authentication so that load balancers and health checks can reach the server.

With RBAC and an OIDC provider configured, AUTH also accepts a bearer id_token in place of a password; its claims resolve to a role through the policy’s oauth.rules (see OAuth / OIDC).

When no password is configured (--require-pass not set), every connection starts authenticated and AUTH is a no-op that replies +OK. This preserves backward compatibility with clients that always send AUTH.

Passwords are hashed with bcrypt at startup and verified against the hash on each AUTH attempt — the plaintext password never resides in server memory.

RESP2 (Redis-compatible)

AUTH <password>
AUTH <username> <password>

• Single-password mode: AUTH <password>
• ACL-style mode: AUTH default <password>

There is exactly one principal in single-password mode: the default user. Usernames other than empty/default are rejected — with one shared password there is no identity to validate against. For multiple named users, enable RBAC with --rbac-config; AUTH <username> <password> then authenticates each user against its own bcrypt hash.

Reply: +OK on success, -ERR invalid password on failure.

Examples

> AUTH wrong-password
-ERR invalid password
> AUTH hunter2
+OK
> GET mykey
$5
hello

Native binary protocol

The client package exposes Auth:

c, err := client.Dial("127.0.0.1:9988", 2*time.Second)
if err != nil {
    log.Fatal(err)
}
defer c.Close()

scratch := make([]byte, 4096)
if err := c.Auth("hunter2", scratch); err != nil {
    log.Fatal(err)
}
// connection is now authenticated — issue Get/Set/Delete as normal

Wire format

The binary protocol Auth request uses MsgAuth message type with payload:

[2B usernameLen][username bytes][2B passwordLen][password bytes]

• usernameLen = 0 (single-password mode — empty username, default user)
• Password follows as a length-prefixed byte string

Responses:

• MsgAuthOk with payload OK on success
• MsgAuthErr with payload ERR INVALID_AUTH on authentication failure

Server-side behaviour

• The client package sends single-password mode only (username is always empty).
• The server accepts both empty and default usernames; any other username is rejected, since --require-pass authenticates against one shared password. Multiple users with distinct credentials are an RBAC feature (--rbac-config).
• bcrypt verification runs on a dedicated worker pool (4 workers by default) off the event loop, so the hashing cost never blocks I/O.

Failure rate-limiting

After 3 failed AUTH attempts the server closes the connection automatically. The counter resets on a successful authentication. Failed attempts are logged at WARN level with the remote address and attempt count.