Security & Authentication
TLS termination, multi-user credentials, MongoDB SCRAM-SHA-256, and MySQL GRANT/REVOKE.
1. Security Model Overview
KOLMOS never starts in a trust-all mode: you must supply `--username`/`--password` (or the `KOLMOS_SERVE_PASSWORD` environment variable) before `serve` will boot. Beyond that base credential, security is configured per protocol — TLS is shared across all three wire listeners, but authentication depth (single user vs. multi-user, SCRAM vs. cleartext, table-level grants) differs between Postgres, MySQL, and MongoDB wire. Know which guarantees apply to which protocol before you expose a port publicly.
2. Enabling TLS
Pass both `--tls-cert` and `--tls-key` (PEM-encoded) to `serve` to turn on rustls TLS termination across the Postgres, MySQL, and MongoDB wire listeners at once. Once configured, TLS is mandatory: a client that tries to connect in plaintext is rejected outright rather than silently downgraded. Omit both flags to run unencrypted (fine for a local dev loop, not for anything reachable over the network).
kolmos --root /data serve --host 0.0.0.0 \
--tls-cert /certs/server.crt \
--tls-key /certs/server.key \
--username kolmos --password my-secret-password3. Multi-User Authentication (--auth-file)
`--auth-file <path>` adds extra accounts on top of `--username`/`--password` — one `username:password` pair per line, blank lines and `#` comments ignored. This works for the **Postgres and MySQL wire protocols only**. MongoDB wire is intentionally single shared-identity: `--auth-file` accounts do not apply to Mongo clients, which authenticate as the one configured user via SCRAM. Plan multi-tenant credentials accordingly — don't assume an `--auth-file` account you created will work against port 27017.
# auth.txt — one account per line, additive to --username/--password
alice:alice-secret-pw
bob:bob-secret-pw
kolmos --root /data serve --username kolmos --password root-pw --auth-file ./auth.txt
# Connect as an auth-file account over MySQL or Postgres wire:
mysql -h 127.0.0.1 -P 3306 -u alice -p
psql "postgres://bob:bob-secret-pw@127.0.0.1:5432/main"4. MongoDB Authentication (SCRAM-SHA-256)
The MongoDB wire listener implements real RFC 5802 SCRAM-SHA-256 (4096 iterations) against the single configured `--username`/`--password` identity — the same mechanism `mongosh`, Mongoose, and PyMongo already speak by default, so no client-side changes are needed. There is currently no per-database or per-collection Mongo user model; every authenticated client shares one identity's privileges.
mongosh "mongodb://kolmos:my-secret-password@127.0.0.1:27017/?authMechanism=SCRAM-SHA-256&authSource=admin&directConnection=true"5. MySQL Table Grants (GRANT / REVOKE)
MySQL wire additionally supports a lightweight, in-memory ACL layer: standard `GRANT`/`REVOKE` statements for `SELECT`, `INSERT`, `UPDATE`, and `DELETE` scoped to `(user, table)`. The model is default-allow — an explicit `REVOKE` denies a privilege, and a later `GRANT` undoes that revoke. Grants are **not persisted** across server restarts, and this ACL layer does not exist for Postgres or MongoDB wire.
-- Restrict a MySQL-wire user to read-only on one table:
REVOKE INSERT, UPDATE, DELETE ON employees FROM 'alice'@'%';
GRANT SELECT ON employees TO 'alice'@'%';6. Known Security Limitations (v1)
Be aware of these current constraints when threat-modeling a deployment: - **No password hashing at rest:** both `--username`/`--password` and `--auth-file` entries are stored and compared in plaintext. - **No cross-protocol RBAC:** the MySQL GRANT/REVOKE system does not extend to Postgres or MongoDB wire. - **No Mongo multi-user:** `--auth-file` has no effect on the MongoDB listener. - Treat `--auth-file` and TLS key material as sensitive deployment secrets — mount them read-only and keep them out of source control.