"""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. The admin username is stored as free text, so it is checked against ``secret_guard`` like every other free-text field: a wallet secret pasted there by accident is refused instead of stored (sections 2 and 15). The password is deliberately not checked, because a long passphrase is a legitimate password and refusing one would block the user's own login. """ import hashlib import hmac import secrets from datetime import datetime, timedelta, timezone from database import get_app_settings, save_app_settings from secret_guard import find_secret, rejection_message 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 # The bounds of the admin account. The username is a label; the password is the # only credential the app stores, and a short one is the easiest way to lose the # protection the login adds, so a minimum length is enforced on the server and # not only in the form (sections 15 and 31 point 1). ADMIN_USERNAME_MAX_LENGTH = 60 PASSWORD_MIN_LENGTH = 8 PASSWORD_MAX_LENGTH = 200 # ``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 normalize_admin_username(value): """Return a trimmed admin username, which must be non-empty text. A value that does not fit raises ``ValueError`` with a message the caller can show; the HTTP handler maps it to a ``400`` and the maintenance command to a failed exit. A value that looks like a wallet secret is refused for the same reason, and the message never repeats the value (sections 2 and 15). That check runs before the length limit, so a seed phrase pasted here is answered with what it looks like rather than with "too long", which would invite the user to shorten the phrase instead of removing it. """ if not isinstance(value, str): raise ValueError("admin username must be text") username = value.strip() if not username: raise ValueError("admin username must not be empty") label = find_secret(username) if label is not None: raise ValueError(rejection_message("admin username", label)) if len(username) > ADMIN_USERNAME_MAX_LENGTH: raise ValueError("admin username is too long") return username def validate_admin_credentials(payload): """Return the normalized ``(username, password)`` of a new admin account. The account is created once, on the first run, and the password is stored only as a scrypt hash (section 31 point 1). The password is not trimmed: what the user typed is what is stored, and what the login form sends back. """ if not isinstance(payload, dict): raise ValueError("payload must be a JSON object") username = normalize_admin_username(payload.get("username")) password = payload.get("password") if not isinstance(password, str): raise ValueError("password must be text") if len(password) < PASSWORD_MIN_LENGTH: raise ValueError( f"password must be at least {PASSWORD_MIN_LENGTH} characters" ) if len(password) > PASSWORD_MAX_LENGTH: raise ValueError("password is too long") return username, password 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)