Authentication & Configuration¶

Quick start¶

fastboxex setup     # asks for your login and password once
fastboxex doctor    # checks everything

Scripts then need one line, from any folder:

from fastboxex import Platform

p = Platform.auto_login()                    # the exchange
arena = Platform.auto_login(runtime="arena")  # arenas
print(p.username, p.user_id)

`Platform.auto_login()`¶

Resolves everything itself, in this order:

What	From
Server	`Config.toml`, see search order
Login, password	Environment, central `.env`, then a local `.env`
Anything missing	Asked at the terminal, then offered to be saved centrally

Without a terminal it raises an error naming fastboxex setup instead of hanging.

runtime is "exchange", "arena" or a runtime id. A selection in your code always wins. Without one, FASTBOXEX_RUNTIME_ID applies, else the only runtime you can reach, else the only exchange, else login fails listing the choices.

`Platform.login()`¶

The same with explicit credentials:

import os

from fastboxex import Platform, load_config

cfg = load_config()
p = Platform.login(cfg, "alice", os.environ["FASTBOXEX_PASS"], runtime="arena")

Every profile is probed at once and the first reachable one, in file order, is used. An unreachable campus address therefore costs about two seconds, once.

Student self-registration¶

Production deployments may enable email-whitelisted registration. Only emails on the exchange whitelist can request an account.

from fastboxex import Platform, load_config

cfg = load_config()

msg = Platform.register(
    cfg,
    username="student01",
    password="pass123",
    email="student01@sjtu.edu.cn",
)
print(msg)  # Confirmation code sent to your email

code = input("Registration code: ").strip()
msg = Platform.confirm_registration(cfg, "student01@sjtu.edu.cn", code)
print(msg)  # Account created; you can now login

The binary login protocol carries passwords in a 16-byte field, so registration rejects passwords longer than 16 bytes.

After confirmation, use the normal login flow.

Password reset¶

If you forget your password, request a reset token via email:

from fastboxex import Platform, load_config

cfg = load_config()

msg = Platform.forgot_password(cfg, "student01@sjtu.edu.cn")
print(msg)  # If an account exists for this email, a reset code has been sent

Then reset with the emailed 5-digit code:

code = input("Reset code: ").strip()
msg = Platform.reset_password(cfg, "student01@sjtu.edu.cn", code, "newpass123")
print(msg)  # Password updated successfully

Anti-enumeration

forgot_password always returns the same generic success message regardless of whether the email exists. This prevents attackers from discovering valid emails.

Rate limiting applies: you must wait 60 seconds between reset requests for the same email. Reset codes expire after 30 minutes.

Where settings live¶

See the config reference for the search order, the Config.toml format and every environment variable.

Never commit .env

A project-local .env holds your password. fastboxex setup saves it centrally, outside any repository, which is why that is the recommended place.