ParlorNet
Turn-based game server for any computer, old or new
Clients | Protocols | Browsers | Telnet programs | Docs | Source

Accounts, sign-in, sign-up and administration

Three separate pieces, each replaceable:

  1. Sign-in and sign-up methods (how a player proves who they are, and how an account is made): two pluggable registries, run as one dialogue the server drives. The operator picks one of each.
  2. Account management (parlord/accounts.py): players, sessions, lockouts, suspending, resetting, deleting.
  3. The admin panel: configures the server from what is installed.

The table host only ever sees a player id and a display name; games see seat numbers. The threat model, the trust boundaries and the reasons behind this design are in docs/security-design.md.

Methods

Sign-in methods, checked at every sign-in:

MethodCredentialRecovery
nonethe name alone; anyone may be anyone (a LAN, a festival)-
passworda password the player chose: 8 to 64 printable ASCII characters (spaces inside are kept), stored as a salted scrypt hashwith an address on file: answer reset at the password question, a code goes by mail, then a new password; without one: the operator's reset gives a one-time password (it works for 24 hours) to sign in with once and choose a new one
totpthe current 6-digit code of an authenticator app; the code is the credential, not a second factoranswer reset at the code question and a new setup goes to the address on file, never anywhere else, with a code typed first to prove the mailbox, then a code from the new setup; the operator's reset mails a setup alone

Sign-up methods, which make the account and set up what the sign-in method needs:

MethodSteps
nonenothing: the name is claimed
passwordchoose a password, type it again
emailconfirm the name (y/n; asked only after HELO, not after REG), give an address; with sign-in totp the mail is the authenticator setup (a QR code as a GIF, so any old mail reader can show it, and the key as text) and a first code finishes it; with sign-in password the mail is an 8-digit code, typed back, and then a password is chosen and typed again. An address that already has a name gets a notice instead ("someone asked to sign up with this address; your name is ..."), and the dialogue goes on exactly as for a free address, so it never tells whether, or to whom, an address belongs. An address gets one sign-up email in 7 days, and at most a set number of sign-ups wait for their code at once (Sign-up limits, below)

Verification is always a value typed back (a code), never a link to click.

Pairs that work: none + none (a festival), password + password (the container's default), password + email, totp + email (parlornet.org). Anything else is refused: sign-in none needs nothing set up, sign-in password needs a sign-up that sets one, sign-in totp needs its setup mailed. The admin menus refuse such a pair with the reason (changing the sign-in method brings the sign-up it needs); a pair from the command line that cannot work falls back to the sign-in method's usual sign-up with a warning in the log.

The greeting names both: PARLOR/1 parlornet.org AUTH=totp SIGNUP=email, with LABEL=... only if the operator set a label of their own. More methods can be added to either registry (an external directory, federated identity) without client changes, because of the dialogue below.

Wrong answers

Every wrong answer counts toward the name's lockout: a wrong password or authenticator code, and a wrong code at a recovery step (the mailed code, the new authenticator's code). The name is locked 1 minute after one, 15 minutes after three, growing by the same factor each time, at most 4 hours; it survives restarts. Each 8 hours without a wrong answer halve the count, so it does not stay high for ever. The refusal carries the reason and the wait for programs: ERR LOCKED wait=60 Wrong password; try again in 60 seconds. A right answer clears the count, and so does a right mailed code at a recovery (the mailbox is proven).

Budgets per address and for the server. A wrong answer for a name its client address has not signed in from in the last 30 days also counts against that address (12 a day) and the whole server (48 a day); once either is spent, untrusted addresses are refused before anything is checked (ERR LOCKED wait=N Too many wrong answers from your address, ERR BUSY wait=N Too many wrong answers on this server; try later, or answer reset). An address a player signed in from is never held up by them. docs/security-design.md has the arithmetic.

A locked name can still recover by mail. While a name with an address on file is locked, HELO name still asks the question, with a note that sign-in waits and that reset gets a code (or a new setup) by email now; any other answer is refused without being checked. Recovery has its own limits instead: 2 recovery mails a day for one name asked from one client address, the mail caps below, 3 tries for each mailed code, and codes of 8 digits. From an address the player signed in from before, the shared caps for the name and its address do not apply, so strangers asking for it cannot use up its owner's recovery. So someone who keeps guessing a name can keep its sign-in locked, but not its owner's recovery. A name without an address is recovered by the operator.

The dialogue: sign-in, sign-up, recovery

Sign in and New account are separate. USER name signs in a name that has an account and refuses one that has not (ERR NOPLAYER); REG name makes a new account and refuses a taken name (ERR NAMEINUSE). So a mistyped name at a sign-in never becomes an account. HELO name, the original request, still does either (docs/protocol.md). The words new and guest are reserved: some frontends take them at their login prompt to start a sign-up (telnet's new, FIBS's guest), so the core refuses them as names under every method (ERR RESERVED), whichever request asks.

FrontendSign inNew accountA name with no account at the login
web (6500)Sign in (/login.htm): the name, and the credential box unless the server signs in by name alone (USER)New account (/signup.htm): the name wanted, then the sign-up steps as pages (REG)"There is no account named x here", with a link to New account
telnet (6502)Login (your name, or "new" for a new account): with a name (USER)new (any case), then the name wanted, then the steps (REG)"There is no account named x here. To make one, type new at the Login prompt."
IOS (6503)the name and password at the login (HELO)the same: a free name runs the sign-up in the client's window, with its own question (y/n under email, the password typed again under password)signs up, as IOS let a free name log in
FIBS (6505)the name and password at login: (USER)guest, then name x and the steps (REG), the FIBS way"There is no account named x here. New here? Log in as guest."
Outland (6506)the Gateway's account name and password (USER)on the web or by telnetV 1 (no such account), with a pointer to the web and telnet
DOoM (6507)connect name password (USER)request name, then the steps as prompts (REG)"There is no player named x here. To make an account, enter `request x'."

Under sign-in none a name is the whole sign-in and nothing can be lost to a typing mistake, so FIBS and Outland logins take a free name as they always did (HELO); the web and telnet keep Sign in and New account apart there too.

The server drives every flow a step at a time, and every step is one of a few generic kinds. Any server extension that can show a line of text and read one back can run them, so a player can sign up from a 1997 Mac client as well as from the web:

KindOn the wireWhat a server extension does
infoINF text lines before an ASK (74 characters each)show the lines
askASK field labelshow the label, read a line, send AUT field value
secretASK field label secretthe same without echo
confirmASK field label yna yes/no question; answer y or n
doneOK ...signed in (see Credentials and sessions)
refusedERR code [wait=N] textshow the text; wait is the seconds before trying again

An ASK may also carry cred: it asks for the account's credential (the password, the authenticator code) or for a password being chosen at sign-up. Info lines that only help (such as "Forgot it? Answer reset ...") are sent as INF too but are optional: a server extension that cannot show them still gets the question.

Anything that is not a line of text (the QR code) travels by mail, never through the server extension. So a TOTP sign-up works on a text-only client:

> REG tia < INF New account: tia. < INF Signing up needs an authenticator app (Google Authenticator, Authy, < INF 1Password...). < INF We email you its setup, a QR code and a key you can type in by hand. < ASK email Email_address > AUT email tia@example.org < INF We sent your authenticator setup to tia@example.org. < INF Scan its QR code (or type its key) in an authenticator app, < INF then type the 6-digit code the app shows. < ASK code Authenticator_code secret > AUT code 482913 < OK -

And a password sign-up and sign-in:

> REG bo < INF New account bo: choose a password. < INF A password is 8 to 64 characters: letters, digits, punctuation, spaces. < ASK password Choose_a_password secret cred > AUT password bo secret 1 < ASK confirm Type_it_again secret cred > AUT confirm bo secret 1 < OK - > USER bo (another time) < ASK password Password secret cred > AUT password bo secret 1 < OK -

PWD (signed in, sign-in password) runs the change flow: current password, new password, the new one again; the player's other sessions end.

HELO name x: a one-line shortcut for direct 8-bit clients under sign-in totp only (x is the current code, with the same lockouts and no replay). It is refused under password (the password is asked for), ignored under none. Server extensions never use it.

Server extensions never volunteer a credential. A server extension signs in with the name alone. If its client supplied a password with the login (the IOS or FIBS password, the Outland Gateway's password, the web form's field), that value answers only a question flagged cred, and only the first one; every other question is asked with the server's own label. If the server asks nothing (sign-in none) or nothing flagged cred (the confirm, address and code of an email sign-up), the supplied value is dropped: never sent to the core, logged or kept.

What a server extension can show. A server extension declares the kinds it can show with CAN kind[,kind...] (text, secret, yn, info) before HELO (or USER, REG); without CAN all four are assumed. When the next step needs a kind the server extension did not declare, the server refuses it cleanly with ERR CANNOT this client cannot show the next step; use the web or telnet.

Server extensionDeclaresSign-inSign-up and recovery
web (6500)allPOST forms: the welcome form's password field answers the credential question; other steps are pages (info paragraphs, a text or password box, Yes/No)yes
telnet (6502)alllines and prompts, secrets not echoedyes; P (or password) in the menu changes the password
IOS (6503), e.g. Reversi The Eclipseallthe IOS password answers the credential question; with none, it is a prompt with the server's label (Password: , Authenticator code: ) in the client's window, which Eclipse forwards while it waits for the first <ios> lineyes, in the same window before the lobby: a free name runs the sign-up flow (HELO)
FIBS (6505): MacFIBS, FIBS/W, xfibs, CLIPallthe password answers the credential question; other steps are promptsyes, after guest and name x (the login itself only signs in)
DOoM (6507): BobGrid, telnet and MUD clientsallthe password answers the credential question; other steps are promptsyes, with request name (the connect line itself only signs in)
Outland Gateway (6506)secretthe password in the Gateway's login packet answers the credential questionno: a name with no account is refused (V 1) with a pointer to the web or telnet, where accounts are made
native clients (6501)all unless they send CANas the protocolas the protocol

The shared helper for line-based adapters is sign_in_lines in adapters/common.py: an adapter gives it the name, the client's password, a prompt(label, secret) and a show(lines), or neither if its client cannot be asked anything after its login.

Credentials and sessions

After a successful check the accounts component creates a session, the same for every method including none:

What server extensions do with sessions:

Server extensionSession
webcookie pn=<sid>; Path=/; HttpOnly; SameSite=Lax, no expiry (ends with the browser); for a browser that returns no cookie, s=<sid> in links, decided on the first page after sign-in (the redirect carries a one-time 60-second handle, not the session). Every page resumes with SES. Actions carry x= (an HMAC of the session id) against cross-site requests. "Sign out" (OUT) on every page, "Sign out everywhere" (OUT all) and "Change your password" in the lobby
telnet, IOS, FIBS, Outlandthe connection's own sign-in; OUT when the player leaves

No server extension ever shows a credential or a session id.

Who is online

A player with an account is signed up. A player is online only while they are signed in and doing something. Every who list shows only the players who are online. That covers IOS who, FIBS who and rawwho, CLIP's who rows, the Outland lobby, telnet's who and plain menu, the web lobby's "Online now" line, and the protocol's WHO.

A player counts as signed in while they have a live connection on any frontend, or a web session that has not ended. Live connections include the public port, telnet, IOS, FIBS and Outland. A web session ends when the player signs out, when it expires, or when the operator or a password change ends it.

A player counts as active if their last activity was no more than presence.idle seconds ago. The default is 1800 seconds, which is 30 minutes. The operator can change it in the admin menus under Server, Idle time, to anything from 1 minute to 7 days, or in the settings file. A connection that stays open but idle stops counting once that time is up.

Activity means things the player does. Signing in counts. So do the requests NEW, JON, LVE, INV, UNV, RES, MOV, CHK, UND, END, CHT, PWD, PRF SET, PRF DEL and ACT. Looking does not count. Frontends send LST, IVL, WHO, VUE, SIN, WAT, SEE, GAM, MOTD, PRF GET and PRF LST on their own every few seconds, so these requests never keep anyone online. Resuming a session with SES does not count either.

Some of a frontend's commands need no request to the core. Examples are a chat between two IOS players, who, or a FIBS toggle. For these, the server extension sends ACT. Telnet, IOS and FIBS report every key or line the player sends. Outland reports every record the player's Backgammon program sends. Each of them sends ACT at most once every 30 seconds (CoreClient.user_input in adapters/common.py).

The web sends ACT for every page the player asks for. It does not send it for what a page fetches by itself. That means /seq.htm, which the page's script checks for news, and /board.gif. It also means the table page's own reloads, from the meta refresh or from the script, which carry a=1 in the address.

The Outland adapter rolls the dice when its player's turn starts. That roll is a MOV, so it counts as activity, but it only happens during a game the player is playing.

The bot is online whenever its process is connected, whatever it last did. Its lobby connection keeps each bot name signed in.

The server extensions that announce arrivals and departures work from the same list, which they check every few seconds. When a player passes presence.idle without activity, the others get the protocol's own departure notice. On FIBS that is "X logs out.", on CLIP it is line 8, on IOS it is <ios> [X disconnected, and on Outland it is a player-left record. When the player does something again, the others get the arrival notice: "X logs in.", CLIP line 7, or <ios> [X(-) connected. Only activity brings a player back and only the idle time takes them away, so the notices do not repeat back and forth.

An invitation to a player who is not online is kept like any other. It waits in the player's IVL until they accept or decline it, until it is withdrawn, or until it expires after an hour. INV answers OK offline instead of OK, so the inviter's frontend can say that the player is away.

Account management interface

parlord/accounts.py, class Accounts: the only code that decides who a connection is. The core calls greeting, begin (HELO, USER, REG), answer (AUT), resume (SES), current (every request), sign_out (OUT), change (PWD); the admin calls suspend, reset, delete; sweep drops expired sessions. It keeps players and sessions in parlord's SQLite database.

Admin panel

Blue-screen menus over telnet, in the manner of dialog and whiptail (a blue screen, grey dialog boxes with shadows, highlighted buttons; arrow keys, Tab, Enter and Esc), served by their own operator extension (adapters/admin.py) on the admin port, 6510. 80x24, in the pc (CP437), utf8 and ASCII character sets with ANSI colour. The menus:

Settings live in the SQLite database and take effect at once; the command line (--auth, --signup) and the container's environment (PARLOR_AUTH, PARLOR_SIGNUP) only give defaults. A settings file (--settings-file) can supply secrets such as email.smtp_password without writing them to the database; a value set in the menus takes precedence.

The message of the day is plain ASCII, at most 20 lines; a line of up to 73 characters is shown as written on every frontend (the web shows it in <pre>, telnet before the login prompt, the protocol's MOTD), so it can hold an ASCII layout. parlornet.org's is deploy/motd.txt, an ASCII box 39 columns wide (a 40-column screen shows it whole, without wrapping onto blank lines) with the contribute address below it, so an address of any length leaves the box intact, and last two lines that say it is a server setting, the file's path and when it last changed (plain text: an operator who writes their own message drops them). The web shows it in an ivory box under a light green "Message of the Day" header. It is given with --motd (PARLOR_MOTD_FILE) until the menus set one. Where it says {contribute}, the contribute address goes: the setting site.contribute_url from the menus (Server, Contribute) or the settings file, else the environment's PARLOR_CONTRIBUTE_URL, else the project's home, https://github.com/eric-cgn/parlornet, where anyone can get the source to run a server or contribute. Set to nothing in any of those places, it is cleared, and every line holding {contribute} is left out, so no marker ever shows.

Two sockets. The menus have no power of their own. They talk to parlord's admin socket (127.0.0.1:6599, JSON lines, parlord/admin.py), which speaks TLS 1.3 with a pre-shared key like the extension channel but accepts only keys enrolled with the admin role (python -m parlord.frontends --keys DIR add admin --role admin; the container's start script does this), so no player-facing server extension can make admin requests. The admin port, 6510, is what the operator reaches: publish it on the host's 127.0.0.1 only (ssh -L 6510:127.0.0.1:6510, then telnet 127.0.0.1 6510). Since operators publish ports as they like, the menus also ask for the admin password.

First launch. While no admin password is set, parlord makes a one-time setup password at each start and prints it in its log (docker logs) with how to reach the admin port. Signing in with it allows only setting the permanent admin password (at least 8 characters), which is stored as a salted scrypt hash. Wrong admin passwords lock the admin sign-in on the players' schedule for the client address they come from (the admin adapter passes it), so a guesser at one address cannot keep the operator out from another; the counts are kept in memory. A forgotten password is cleared with python -m parlord.admin --db /data/parlord.db --reset-password; the next start prints a new setup password.

Email

Transport. Plain SMTP only: host, port, a user and password that can only send, and a From address (settings email.smtp_host, email.smtp_port, email.smtp_user, email.smtp_password, email.from). The connection is always encrypted and the relay's certificate is always verified against the system's CA certificates, for the host name in email.smtp_host (so set the relay's name, not its address): STARTTLS on any port but 465, implicit TLS on 465 (or with email.smtp_tls=tls). A relay that offers no STARTTLS, or whose certificate does not verify, gets nothing, neither the credentials nor the mail; the step is refused with ERR NOMAIL. For a relay with a certificate from a CA of your own, name that CA's certificate file in email.smtp_ca_file (settings file). The public release contains no mail provider's API, SDK or credentials of any other kind; any provider that offers SMTP works. Until a relay is set the transport is log: nothing is sent, and the log gets the address and subject only, never the body.

Codes. Mailed codes are 8 digits, single use, valid for 10 minutes at a recovery and for as long as the sign-up may wait for it (an hour) at a sign-up; three wrong entries void the code, and at a recovery each counts toward the name's lockout.

Sign-up limits. Three settings (admin menus, Sign-in, Sign-up limits; or the settings file):

SettingDefaultWhat
signup.address_cooldown7 days (604800 seconds)After a sign-up email to an address (the code, the authenticator setup, or the notice to an address that already has a name), no other sign-up email goes to it for this long.
signup.max_pending20Email sign-ups waiting for their code at once.
signup.pending_ttl1 hour (3600 seconds)How long a sign-up waits for its code; then it ends, its place is free and so is its name.

Caps. parlord counts a send before it is made, in sliding windows kept in SQLite (so restarts do not reset them). Defaults, each a setting (email.limit.<key>) the admin menus can change up to a ceiling:

PerDefault
address3 an hour, 6 a day, at least 60 seconds apart; recovery mail to an address on file counts only recovery mail to it, so sign-ups naming that address cannot use up its owner's recovery
name2 an hour (not for recovery), 4 a day; recovery from an address the player signed in from is not counted here (it has its own 2 a day)
name, asked from one client address2 recovery mails a day
connection2; after that the player must reconnect
client address (the public port's peer; the address a server extension passes with SRC)4 an hour, 10 a day, sign-up and recovery together; and no more sign-up mail for the day once 2 addresses mailed for it bounced
sign-up, whole server3 a minute, 20 an hour, 60 a day; 30 a day to addresses never verified before
recovery asked by strangers, whole server3 a minute, 20 an hour, 60 a day: a budget of its own, so a flood of sign-ups cannot use it up
owners' own recovery, whole server20 an hour, 60 a day: asked from an address the player signed in from, or finished with the right mailed code; strangers' requests never count here

The cap for new addresses bounds how many bounces a flood of made-up addresses can cause, while returning players keep signing in. Set the server-wide caps (sign-up and recovery together) under your relay's own limits. Separately, one client address may start at most 20 sign-ups in 10 minutes (any sign-up method).

When a cap is hit, the step is refused with ERR BUSY or ERR PAUSED and a message that says which limit and when to try again (wait=N). Nothing is queued or sent later.

Addresses in the mail tables. The mail log (email_log, kept 3 days), the blocked addresses (email_blocked) and the cooldown (signup_cooldown) hold an address only as HMAC-SHA256 under a random key of the database's own, so the database keeps no list of addresses that never became accounts; an account's own address is on its player row. Rows from an earlier version are hashed when the database is opened.

Never send again to an address in parlord's email_blocked table. It is filled by permanent failures at submission (SMTP 5xx for that recipient) and from a plain file named by the setting email.blocked_file (one address a line, # for comments), read when it changes. The public release only reads the file; filling it from a provider's bounce and complaint list is the operator's own, separate service. Bounces are counted by who asked for the mail: the client address that asked for the latest mail to a blocked address, or the address itself when that is not known. One client address whose sign-ups bounce is refused sign-up mail for the day (above). If bounces come from more than 3 such requesters in 24 hours, parlord holds sign-up mail until the operator resumes sending in the admin menus; recovery mail to addresses on file is never held.

Message content is fixed: the code or the setup, its lifetime and the server name. It never includes the player's chosen name or anything else the requester typed except the address it goes to, so the sign-up form cannot be used to send someone a message. One recipient per message.

Operator controls. The admin menus show the counters, can pause email sending and can change the caps. Every shipped server extension passes its client's address with SRC (docs/protocol.md); the public port uses the connection's own. IPv6 addresses are counted by their /48. The Status screen shows the server's wrong-answer and mail budgets, with an alarm when one is used up, and Clear budgets frees them without a restart (each name's lockout and caps stay); it also shows the sign-up limits and clears address cooldowns (Sign-up limits, above).

This doc on GitHub


 These pages cover every ParlorNet server. | Source code | ParlorNet is free software.