diff --git a/auth.py b/auth.py new file mode 100644 index 0000000..7874a9a --- /dev/null +++ b/auth.py @@ -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)