"""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)