Appearance
Authentication
Sign-in is off by default, which is what makes a fresh clone usable. Turn it on with NOTESFLOW_REQUIRE_AUTH=1 and the whole permission model applies.
How somebody signs in
Four roads, and they all end at the same gate — one account, identified by an email address. Who is let in is decided in exactly one place, whichever road somebody took, so a rule cannot be remembered on three roads and forgotten on the fourth.
A link in an email
Ask for a link, receive it, open it. Every link and notice is sent one of two ways:
- By the server, over SMTP. Set
NOTESFLOW_SMTP_URLto your mail provider's relay —smtps://user:[email protected]:465, orsmtp://…:587, which upgrades to TLS when the relay offers it — andNOTESFLOW_MAIL_FROMto who it is from (Notesflow <[email protected]>, on a domain whose SPF and DKIM include that provider, or it lands in spam).NOTESFLOW_MAIL_REPLY_TOandNOTESFLOW_MAIL_BRAND(the name messages are signed with,Notesflowby default) are optional. Every message is worded already, in plain text and HTML. - By a webhook. Set
NOTESFLOW_LINK_WEBHOOKand each becomes a POST of{ email, url, purpose, message: { subject, text, html } }to a URL you control, which can forwardmessageas it is or word its own.NOTESFLOW_LINK_WEBHOOK_SECRETis sent as a bearer token, because that endpoint mints credentials and should not accept requests from anybody who finds it.
With both set, SMTP is used and the server says so at startup. /admin → Mail says which is in use and sends an owner a test message, to their own address only, with what the relay said if it fails.
Or set it in the console. An owner can set the relay — host, port, TLS or STARTTLS, user name, password, From, Reply-To and the name messages are signed with — or a webhook and its secret, in /admin → Mail. That wins over the environment, reaches every server at once without a restart, and Use the environment's settings removes it again. SMTP settings are tried against the relay before they are saved, and not saved if it refuses, because the same relay sends every sign-in link — yours too. The password is sealed with NOTESFLOW_SECRET and never shown again; rotating that secret stops mail set here until it is set again (it does not fall back to the environment). If settings made here ever stop links arriving and nobody can sign in to fix them, set NOTESFLOW_MAIL_IGNORE_CONSOLE=1 and restart: that server uses the environment's settings whatever the console says.
purpose says what the mail is for: sign-in, sign-up, account-exists, reset-password, password-changed, two-step-changed, confirm-email, email-changed, confirm-deletion, confirm-sso, package-ending and package-decided, and for billing invoice-issued, invoice-overdue, package-held, payment-received, credit-note-issued, refund-sent and credit-changed (with credit: { amount, currency, balance, applied, reason, workspace? }; see Billing and invoices), and mail-test. A webhook receiver that ignores it still delivers a working link; it just words every one as a sign-in.
package-ending is a notice that a package ends within a week. It also carries notice: { package, until, workspace?, then }: the package's name, when it ends, the workspace's name (absent for a person's own account package), and what applies afterwards, in words. The link is the workspace's console.
A failure to deliver is reported, not swallowed. "We have sent you a link" when nothing was sent is the worst possible answer: the person waits, tries again, and waits again.
A notice nobody is waiting on — an address or password changed, a package ending, an invoice, a payment, a credit — is instead kept and tried again when the relay refuses it or cannot be reached: after 1, 5, 15, 60 and 240 minutes, 12 hours, then a day twice, about two and a half days in all. Each refusal is logged at warn; one given up on is logged at error. /admin → Mail lists what is owed and what was given up, with the relay's last answer, and an owner can Try again now. The metrics carry notesflow_mail_waiting and notesflow_mail_given_up. A link that signs in, confirms or resets is never kept: it is a credential, it expires, and the person who asked for it is told at once. A message may arrive twice if a server stops between the relay taking it and the server noting so, but never not at all while the relay comes back in time.
Without either, links are printed to the server's output. That is a development affordance — as is NOTESFLOW_LINK_LOG, which appends them to a file for the browser suites. A log of sign-in links is a log of live credentials.
A password
On by default; an operator can switch passwords off for the deployment. Somebody can then:
- create an account with an address and a password. The confirmation link asks for the password again, so a stranger cannot plant a password on somebody else's address and have its owner confirm it with one unsuspecting click;
- sign in with it;
- reset it from a mailed link. A reset ends every session and does not sign in, so two-step sign-in still stands between a read mailbox and the account;
- set, change or remove one in Settings.
Passwords need 12 characters and are refused if they are common, a run like abcdef…, or the person's own address or name. There are no composition rules. They are stored with scrypt.
Wrong passwords pause sign-in for that account — 15 seconds after five in a row, doubling to at most 15 minutes — counted in the database so every server shares the count. A pause is never a lockout, which anybody could trigger against anybody.
Nothing on a sign-in page says whether an address has an account. Sign-up, reset and password sign-in answer the same words for every address, after the same amount of work.
OAuth
Google and GitHub have presets. Give one a client id and secret and it appears as a sign-in button. Either set them in the platform console under How people get in — a form per provider, with the redirect URI to paste into the provider, and Turn off and Forget — or in the environment:
bash
NOTESFLOW_OAUTH_GOOGLE_ID=… NOTESFLOW_OAUTH_GOOGLE_SECRET=…
NOTESFLOW_OAUTH_GITHUB_ID=… NOTESFLOW_OAUTH_GITHUB_SECRET=…The console wins, per provider, and Forget hands that provider back to the environment. Changes reach every server at once, with no restart. A secret set in the console is sealed under NOTESFLOW_SECRET; after rotating that, the provider shows as not offered rather than quietly falling back to the environment's. The state parameter is signed and round-tripped through a cookie rather than stored server-side — it exists to prove the callback belongs to a flow this browser started, without which somebody can hand a person a callback URL and sign them into the attacker's account.
A workspace's own SSO
For a company's own directory, see single sign-on, which is per workspace and configured by its own admin rather than by an operator. The provider's word alone never decides whose account somebody signs in to: the first sign-in is confirmed by mail, unless the domain is proven. Its groups can decide roles, and a directory can sync the member list over SCIM.
Two-step sign-in
Anybody can add an authenticator app as a second step, from Settings, with ten single-use recovery codes. It is asked after a password and after an emailed link — the mailbox is the account's real root, so a second step that a read mailbox could skip would protect little. OAuth providers and a company's SSO are not asked; they run their own.
The half-signed-in moment is a single-use challenge: five minutes and five tries, then start again. It is made before anything is decided about workspaces, so half a sign-in accepts no invitation.
Signing in is not joining
Having an account and belonging to a workspace are two different things. A person becomes a member of a workspace only through:
- an invitation to it — an admin names an address and the role it may join as;
- its SSO domain claim;
- its directory, over SCIM — which writes an invitation that the person's own sign-in spends;
- being its first member;
- the workspace admitting anybody signed in, if it, or the deployment for it, says so.
Anybody else who signs in at a workspace's address is a visitor: they see exactly what has been shared with them, and nothing else. A member an admin removed stays removed when they sign in again.
How people get in
The operator decides, in the platform console (/admin) under How people get in:
| Setting | Choices |
|---|---|
| New accounts | Invitation only, or Anyone may sign up |
| A workspace that has not chosen | Is invitation only, or Admits anyone signed in |
| Passwords | on (default) or off |
| Refuse passwords known from breaches | off (default) or on — sends five characters of the password's hash to Have I Been Pwned, never the password, and lets sign-up through if that service is down |
| A workspace of their own for anybody who belongs nowhere | off (default) or on — made once, at their first sign-in, as its admin |
Left unset, the first two follow NOTESFLOW_ALLOW_OPEN_SIGNUP, so an existing deployment behaves as it always did. They are separate because a public platform wants the first open and the second closed: anyone may make an account, and is a visitor everywhere until an invitation, a claimed domain or a workspace's own choice says otherwise. With one switch, a stranger signing up at /w/acme would have joined acme.
Anyone may sign up is refused while sign-in links are only printed, because every new account's first step is a link.
Each workspace can also make its own choice in its settings.
A workspace's own sign-in rules
A password outlives the mailbox and the directory account a company closes when somebody leaves. So a workspace can set rules for its members, in its console behind manage_sso:
- Members must sign in through single sign-on — through one of its connections;
- Members must use two-step sign-in;
- Members may not sign in with a password.
A member whose session does not meet a rule is refused there — open pages close the moment a rule is turned on — and is shown which rule and what to do. See single sign-on.
Every session records how it was made — link, password, oauth:<provider> or sso:<connection> — and whether a second factor was given, and Settings shows how beside each one.
Rate limits
/api/auth/request-link sends mail to whatever address it is given. Unthrottled, that is an open relay: anyone can make your mail service send unlimited messages to addresses of their choosing until your provider suspends you for it.
| Limit | Window |
|---|---|
| 5 requests naming one address, from anywhere | 1 hour |
| 10 requests from one caller, whatever addresses they name | 10 minutes |
| 30 redemption attempts from one caller | 10 minutes |
| 50 password sign-ins from one network | 10 minutes |
These limits are per process; only the per-account password pause is shared through the database. Running the browser sign-in suites repeatedly means restarting the server between batches; the symptom is "No sign-in link arrived".
NOTESFLOW_TRUST_PROXY decides whether x-forwarded-for identifies the caller. Set it only behind something you control — otherwise callers pick their own identity and these limits stop meaning anything.
Sessions
Signed with NOTESFLOW_SECRET. Leave it unset and a random key is generated at every start, which signs everybody out on every restart. The same secret seals two-step secrets and SSO client secrets, so rotating it makes those unreadable — people with two-step sign-in then need a recovery code, or an operator's reset.
Sessions live in the control plane, not in a workspace, because one account with memberships in three workspaces signs in once.
When somebody is locked out
An owner can reset an account's sign-in from the platform console: the password, the two-step secret and the recovery codes go, every session ends, the address is told, and the audit log records it. Operators never see or set anybody's password, and a workspace admin cannot touch one at all — their tools are removing a member and requiring SSO.
The way back in
NOTESFLOW_ADMIN_EMAILS promotes the addresses it names to admin at every start. It is an environment variable rather than a row precisely so it cannot be deleted by whatever went wrong — it is the deliberate way back into a deployment whose only admin has left.
Not built
Passkeys, a CAPTCHA for sign-up, and a QR code for the authenticator app (the key and an otpauth:// link are shown instead).