Section 31 point 1: admin credentials, signed session, and CSRF

This commit is contained in:
ai-bot committed 2026-10-13 15:02:44 +00:00
1 parent 55f76d0991
commit d33be384bd
1 file changed
+196
+196
View File
@@ -0,0 +1,196 @@
"""Admin credentials, signed sessions, and CSRF tokens for VardKey.
Section 31 point 1 puts the whole app behind an admin login. This module is the
only place that knows how the credential is stored and how a session is proven:
- The password is stored **only** as a ``hashlib.scrypt`` hash with a random
salt per password, and compared with ``hmac.compare_digest``. No hand-written
cryptography is involved, and the admin password is the only credential the
app stores — it is an app login, not a wallet secret.
- A session is a signed cookie: HMAC-SHA256 over an expiry timestamp, keyed by a
``session_secret`` that is generated once and kept in ``app_settings``. There
is no session table, so a session survives a restart.
- A CSRF token is a double-submit value: the same random token in a readable
cookie and in a request header, compared with ``hmac.compare_digest``.
The three settings live in the ``app_settings`` table from section 31 point 7,
so no new table is needed.
"""
import hashlib
import hmac
import secrets
from datetime import datetime, timedelta, timezone
from database import get_app_settings, save_app_settings
ADMIN_USERNAME_SETTING = "admin_username"
ADMIN_PASSWORD_HASH_SETTING = "admin_password_hash"
SESSION_SECRET_SETTING = "session_secret"
SESSION_COOKIE = "vardkey_session"
CSRF_COOKIE = "vardkey_csrf"
CSRF_HEADER = "X-CSRF-Token"
# A month is long enough that the single local user is not asked to log in again
# on every visit, and the cookie is still bounded.
SESSION_TTL_SECONDS = 30 * 24 * 60 * 60
# ``hashlib.scrypt`` parameters. The salt is random per password, so two equal
# passwords never share a hash. 2**14 needs 16 MiB, which is inside OpenSSL's
# default memory limit.
SCRYPT_N = 2**14
SCRYPT_R = 8
SCRYPT_P = 1
SCRYPT_DKLEN = 32
SCRYPT_SALT_BYTES = 16
SCRYPT_PREFIX = "scrypt"
def hash_password(password):
"""Return a self-describing scrypt hash for the password.
The stored value carries its own parameters and salt, so the format can be
changed later without invalidating an existing password.
"""
salt = secrets.token_bytes(SCRYPT_SALT_BYTES)
digest = hashlib.scrypt(
password.encode("utf-8"),
salt=salt,
n=SCRYPT_N,
r=SCRYPT_R,
p=SCRYPT_P,
dklen=SCRYPT_DKLEN,
)
return (
f"{SCRYPT_PREFIX}${SCRYPT_N}${SCRYPT_R}${SCRYPT_P}"
f"${salt.hex()}${digest.hex()}"
)
def verify_password(password, stored):
"""Return True when the password matches the stored hash.
A malformed stored value is a failed match, never an error, so a broken row
cannot be turned into a traceback.
"""
if not isinstance(stored, str) or not isinstance(password, str):
return False
parts = stored.split("$")
if len(parts) != 6 or parts[0] != SCRYPT_PREFIX:
return False
_, n, r, p, salt_hex, digest_hex = parts
try:
salt = bytes.fromhex(salt_hex)
expected = bytes.fromhex(digest_hex)
digest = hashlib.scrypt(
password.encode("utf-8"),
salt=salt,
n=int(n),
r=int(r),
p=int(p),
dklen=len(expected),
)
except (ValueError, TypeError):
return False
return hmac.compare_digest(digest, expected)
def get_admin(database_path="data/vardkey.sqlite3"):
"""Return the stored ``(username, password_hash)``, either of which may be None."""
settings = get_app_settings(database_path)
return (
settings.get(ADMIN_USERNAME_SETTING),
settings.get(ADMIN_PASSWORD_HASH_SETTING),
)
def admin_configured(database_path="data/vardkey.sqlite3"):
"""Return True when an admin username and password are stored.
The first run has none, and the app answers with the create-admin page
instead of the login form (section 31 point 1).
"""
username, password_hash = get_admin(database_path)
return bool(username and password_hash)
def set_admin(username, password, database_path="data/vardkey.sqlite3"):
"""Store the admin username and the scrypt hash of the password."""
save_app_settings(
{
ADMIN_USERNAME_SETTING: username,
ADMIN_PASSWORD_HASH_SETTING: hash_password(password),
},
database_path,
)
def authenticate(username, password, database_path="data/vardkey.sqlite3"):
"""Return True when the credentials match the stored admin."""
stored_username, stored_hash = get_admin(database_path)
if not stored_username or not stored_hash:
return False
if not isinstance(username, str):
return False
# Both comparisons run, so a wrong username and a wrong password are equally
# slow.
username_ok = hmac.compare_digest(username, stored_username)
password_ok = verify_password(password, stored_hash)
return username_ok and password_ok
def session_secret(database_path="data/vardkey.sqlite3"):
"""Return the session secret, generating and storing it once."""
stored = get_app_settings(database_path).get(SESSION_SECRET_SETTING)
if stored:
return stored
secret = secrets.token_hex(32)
save_app_settings({SESSION_SECRET_SETTING: secret}, database_path)
return secret
def _sign(secret, payload):
"""Return the HMAC-SHA256 signature of a payload, as hex."""
return hmac.new(
secret.encode("utf-8"), payload.encode("utf-8"), hashlib.sha256
).hexdigest()
def create_session_token(database_path="data/vardkey.sqlite3", now=None):
"""Return a signed session token that expires after the session lifetime."""
moment = now or datetime.now(timezone.utc)
expires = int((moment + timedelta(seconds=SESSION_TTL_SECONDS)).timestamp())
payload = str(expires)
return f"{payload}.{_sign(session_secret(database_path), payload)}"
def verify_session_token(token, database_path="data/vardkey.sqlite3", now=None):
"""Return True when the token is signed correctly and has not expired."""
if not isinstance(token, str) or "." not in token:
return False
payload, _, signature = token.partition(".")
expected = _sign(session_secret(database_path), payload)
if not hmac.compare_digest(signature, expected):
return False
try:
expires = int(payload)
except ValueError:
return False
moment = now or datetime.now(timezone.utc)
return expires > int(moment.timestamp())
def new_csrf_token():
"""Return a fresh CSRF token."""
return secrets.token_hex(32)
def csrf_tokens_match(cookie_value, header_value):
"""Return True when the CSRF cookie and the CSRF header are the same token."""
if not cookie_value or not header_value:
return False
if not isinstance(cookie_value, str) or not isinstance(header_value, str):
return False
return hmac.compare_digest(cookie_value, header_value)