Accounts, sessions and deployment
The official desktop default is https://circagraph.org. In Server connection, connect to other HTTPS origins as well, or disconnect from all of them and continue working locally. HTTP is accepted only for loopback development origins. Only the connected origins are persisted; desktop credentials live in native process memory and a restart requires signing in again.
Several servers on the desktop
The desktop connects to up to eight servers at once, each with its own sign-in. Signing in to one server, signing out of it or disconnecting from it leaves the others as they are. Once more than one server is connected, the dialog is named Servers (n). It lists each server with its account and offers Use, Sign in, Sign out and Disconnect.
One server is in use at a time:
- The account button shows its account.
- New timelines are saved to it.
- Comparisons are of its timelines.
- The plugin library opens on it.
When a server timeline is open, the server in use is always that timeline's server. Opening a timeline from another server switches to that server without signing in again. Use is unavailable while a server timeline is open. The server in use is listed first and is used again at the next start.
When several servers are connected, the desktop shows which server each item comes from with a chip naming it:
- The dashboard lists your timelines and favorites from every server you are signed in to, and public timelines from every reachable server.
- The open timeline shows a chip with its server.
- The plugin library can browse any connected server's plugins.
Desktop timeline links name their server too: #server/<origin>/timeline/<id>. Disconnecting from the server in use keeps its open timeline as an unsaved local copy and switches to the next server.
Accounts support username/password, Google, GitHub, Facebook and Microsoft sign-in, and directory (LDAP / Active Directory) sign-in on servers that configure it. Private timelines and explicit viewer/contributor/writer memberships apply equally to browser and desktop requests. Public timelines can be viewed without signing in. Open Your Circagraph account to see active sessions and sign out every other session. Social accounts initially receive a generated username, shown in the account button and usable for sharing.
Agreeing to the terms
Every account agrees to the terms of service and privacy policy in force (#277; server/policies.mjs):
- Registering with a password needs the unticked I agree to the terms of service and have read the privacy policy box. The form sends the version shown (
acceptTerms, the policies' effective date from/api/session'sterms), and the server refuses a missing or older one with 400. The version and time are kept with the pending registration and copied to the account it becomes. - A new account from Google, GitHub or Facebook exists before it has agreed, but cannot sign in until it confirms an email address, and the same box is required at that step (
POST /api/auth/email/enroll). - Existing accounts, made before the version in force (or before an administrator ran the bootstrap), have none recorded:
/api/sessionreportsuser.termsRequired, and a panel under the header on every page asks them to agree (POST /api/auth/terms). Until they do, the server refuses their browser and desktop sessions' changes with 403 andterms. Still allowed: every read (and the query and search POSTs), signing out, the rest of the account's own settings and security under/api/auth/except creating API keys, deleting the account or its timelines, exporting a file, reporting and asking for a moderation review. API keys made before keep working, so integrations do not stop until their owner signs in.
Each account keeps terms_version and terms_accepted_at. When either policy changes materially, set POLICY_VERSION (and oc_policy_version() in schema.sql, which a test keeps equal) to the new effective date: every account is then asked again.
Configure circagraph.org
Build the app, apply npm run migrate using a migration database account, and serve it behind an HTTPS reverse proxy. Set APP_ORIGIN=https://circagraph.org with no trailing slash. The existing schema migration is idempotent and adds identity, device approval, throttle and session columns to older installations.
Each provider is disabled unless both its client ID and secret are set on the Node server. To turn a configured provider off without removing its credentials, for example while its app review or business verification is pending, set OAUTH_<NAME>_ENABLED=false (OAUTH_GOOGLE_ENABLED, OAUTH_GITHUB_ENABLED, OAUTH_FACEBOOK_ENABLED, OAUTH_MICROSOFT_ENABLED; 0, no and off also work) and restart. Its button disappears and new sign-ins with it are refused; accounts that linked it can still unlink it under Sign-in methods. Remove the setting, or set it to true, to turn the provider back on. Secrets belong in deployment environment variables or a secret manager, never TypeScript, HTML, desktop build variables or committed files. Compose forwards the settings listed in .env.example.
| Provider | Environment variables | Registered callback URL |
|---|---|---|
OAUTH_GOOGLE_CLIENT_ID, OAUTH_GOOGLE_CLIENT_SECRET | https://circagraph.org/api/auth/google/callback | |
| GitHub | OAUTH_GITHUB_CLIENT_ID, OAUTH_GITHUB_CLIENT_SECRET | https://circagraph.org/api/auth/github/callback |
OAUTH_FACEBOOK_CLIENT_ID, OAUTH_FACEBOOK_CLIENT_SECRET, OAUTH_FACEBOOK_GRAPH_VERSION | https://circagraph.org/api/auth/facebook/callback | |
| Microsoft | OAUTH_MICROSOFT_CLIENT_ID, OAUTH_MICROSOFT_CLIENT_SECRET, optional OAUTH_MICROSOFT_TENANT, OAUTH_MICROSOFT_LABEL | https://circagraph.org/api/auth/microsoft/callback |
Google uses a confidential Web application OAuth client and the openid profile scopes. Configure the consent screen and authorized redirect URI in Google Cloud. GitHub uses a confidential OAuth app with read:user; configure its homepage and callback. Facebook uses a Meta app with Facebook Login, public_profile and the callback under Valid OAuth Redirect URIs; set its Graph API version explicitly, for example vN.N matching that app. Microsoft is described under Microsoft sign-in. Complete the provider's production/domain/app review requirements before allowing ordinary users to sign in. Development callback URLs must match APP_ORIGIN exactly; separate development registrations are preferable.
Microsoft sign-in (Entra ID)
For schools and organisations on Microsoft 365, whose accounts are in Entra ID (formerly Azure AD) with no directory the server could reach over LDAP, and for personal Microsoft accounts. It is OpenID Connect: the authorization code flow with S256 PKCE and a nonce, scopes openid profile.
- In the Microsoft Entra admin center, open Identity → Applications → App registrations → New registration. Name it after the site.
- Supported account types: Accounts in this organizational directory only for one school, Accounts in any organizational directory for any school or organisation, or the option that adds personal Microsoft accounts. Match it with
OAUTH_MICROSOFT_TENANT(below); Microsoft refuses a sign-in the registration doesn't allow, and the server refuses a token from a tenant the setting doesn't allow. - Redirect URI: platform Web,
https://circagraph.org/api/auth/microsoft/callback(yourAPP_ORIGINfollowed by/api/auth/microsoft/callback). - Copy the Application (client) ID into
OAUTH_MICROSOFT_CLIENT_ID. Under Certificates & secrets → Client secrets, add a secret and copy its Value (not its ID) intoOAUTH_MICROSOFT_CLIENT_SECRET. Secrets expire (at most two years): note the date and replace it before then. - No API permissions need adding:
openidandprofileare granted to every registration. Some tenants require an administrator's consent before their users can sign in to a new app; an administrator can grant it under Enterprise applications → the app → Permissions.
OAUTH_MICROSOFT_TENANT decides whose accounts may sign in:
| Value | Who can sign in |
|---|---|
organizations (default) | Any work or school account, from any tenant; not personal Microsoft accounts |
common | Work, school and personal Microsoft accounts |
consumers | Personal Microsoft accounts only |
| a tenant ID or domain | Only that tenant's accounts, for example 0f2e… or school.example (one school's accounts) |
A domain is turned into its tenant ID once, from the tenant's OpenID configuration. A value that is none of these stops the server at startup. OAUTH_MICROSOFT_LABEL names the button, for example "School account" (default "Microsoft").
The server checks the ID token's RS256 signature against the tenant's published keys, its issuer (https://login.microsoftonline.com/<tid>/v2.0, with the token's own tenant ID tid, which must be the configured tenant when one is set), audience, nonce, expiry and issue time. The account is identified by the token's tenant ID and object ID (oid), stored as <tid>:<oid>: the same person in the same tenant always signs in to the same account, while an email address or username at Microsoft, which can be reassigned, is never used. Nothing else from the token is kept; Microsoft's tokens are discarded once the identity is verified. A first sign-in creates an account with a generated username, which then gives and confirms an email address and a year of birth, as with the other providers. Signed-in accounts link and unlink Microsoft under Account → Sign-in methods.
References: Google web authorization, Google identity verification, GitHub authorization, Facebook manual login flow, Facebook secure requests, Microsoft identity platform authorization code flow, Microsoft ID token claims.
Do not register desktop callback URLs with these providers. The provider login always completes on the web server. The desktop uses the account established there.
Directory sign-in (LDAP and Active Directory)
A server for a school or organisation can let people sign in with the accounts they already have in its directory: Active Directory, OpenLDAP, 389 Directory Server, FreeIPA or another LDAP server (#286). Sign in with the configured label (for example "School account") then appears on /login, beside any social providers. It is off unless LDAP_URL is set.
| Setting | Meaning |
|---|---|
LDAP_URL | The directory: ldaps://dc.school.example (port 636), or ldap://… with LDAP_STARTTLS=1. Plain ldap:// without STARTTLS is refused unless LDAP_ALLOW_INSECURE=1, since passwords would cross in clear. |
LDAP_STARTTLS | 1 to upgrade an ldap:// connection with STARTTLS. |
LDAP_TLS_CA | A PEM file of the certificate authority that signed the directory's certificate, when it is not publicly trusted (an internal CA). Certificates are always verified; TLS 1.2 is the minimum. |
LDAP_BIND_DN | The service account the server searches with, such as CN=openchronology,OU=Service,DC=school,DC=example. Leave it and the password empty for an anonymous search, where the directory allows one. |
LDAP_BIND_PASSWORD | That service account's password. Give the account read access only. |
LDAP_BASE_DN | Where to look for people, such as DC=school,DC=example or OU=Students,DC=school,DC=example. Required. |
LDAP_USER_FILTER | How a typed username finds its account; {username} is replaced by the escaped name. Default, for Active Directory: (&(objectClass=user)(sAMAccountName={username})). OpenLDAP: (uid={username}). |
LDAP_USERNAME_ATTRIBUTE | The attribute a new account's Circagraph username is taken from (default sAMAccountName; uid for OpenLDAP). |
LDAP_REQUIRED_GROUP | Optionally, the DN of a group a person must belong to (through memberOf; OpenLDAP needs its memberof overlay). |
LDAP_NESTED_GROUPS | 1 on Active Directory to count membership through nested groups too. |
LDAP_LABEL | What the sign-in button calls it (default "Directory account"), at most 40 characters. |
LDAP_CHECK_MINUTES | How often accounts are checked against the directory, ending the access of people who left it (see below). Default 60; 0 turns the check off. |
Signing in looks the person up with the service account (exactly one entry must match), then binds to the directory as that entry with the password they typed; an empty password is refused before anything is sent, since many directories treat it as an anonymous bind. The password is used only for that bind: it is not stored, logged or sent anywhere else. Unknown names, wrong passwords and people outside the required group all get the same "Username or password is incorrect." Directory sign-ins share the password sign-in's rate limit (ten a minute per address) and its answer to repeated failures for a name: human verification, or a short delay with checks off (see Human verification), never a lockout. Linking a directory account is limited to ten attempts a minute per account and per address. The server refuses to start with an incomplete or unsafe configuration.
A directory account is held as the provider identity ldap, keyed by Active Directory's objectGUID (or the standard entryUUID, else the entry's DN), so renaming the account in the directory keeps it. The first sign-in creates an account named after the directory account when that username is free and allowed (lowercased, with dots and spaces as hyphens), else a generated one. Like a new social account, it then gives an email address to confirm and a year of birth before it can sign in, so the server needs email configured (Resend). Two-factor authentication, suspensions and session rules apply as for any account. An existing account can link a directory account on Account → Sign-in methods within five minutes of signing in, and unlink it as it unlinks a social provider. Matching email addresses never merge accounts.
An account that signs in only through its directory account (no password and no other provider, as one made by a directory sign-in is) stays under the directory's control: removing the person from the directory, or from LDAP_REQUIRED_GROUP, stops them signing in. So it cannot set a password, link a social provider or sign in with a passkey alone (each refused with 403); a passkey still answers its two-factor step. Forgot password sends it no link (with the same answer as for any address), and a reset link would be refused. GET /api/auth/account reports this as security.directory_only, and the account page hides the options it cannot use. When directory sign-in is turned off, or the person moves off the directory, an administrator releases the account in /admin (Release from directory, see administration): its directory account is unlinked, it is signed out everywhere, and it is emailed a link to choose a password; Forgot password then works for it. This is never automatic, so a directory left unconfigured by mistake releases nobody. An account that had a password or a social provider before linking a directory account keeps them: the directory was never its only way in. Removing someone from the directory ends what they already have at the next periodic check, described below; suspend the account in /admin to end it at once.
When someone leaves the directory. A sign-in checks the directory only when it happens, and sessions (up to fourteen days, or a day idle) and API keys (up to a year) outlast it. So every LDAP_CHECK_MINUTES (hourly by default) the server looks up each account with a directory identity, with the service account and by its objectGUID, entryUUID or DN, under LDAP_BASE_DN and in LDAP_REQUIRED_GROUP when that is set (#408). When the entry is gone, out of the group, or disabled (Active Directory's userAccountControl), the account's sessions end and its API keys are revoked, as after a password reset, once: the server logs it and records it in oc_admin_audit as directory-left, with the reason. The account is not suspended or released. An account that signs in only through its directory cannot sign in again until the directory lets the person back in; one that also has a password or another provider keeps them and can sign in with those, and is not signed out again on later checks. When the person is found again, or signs in through the directory, a later departure is acted on again. For access that must end now, suspend the account in /admin.
Nobody is signed out because the directory cannot be checked. When it cannot be reached, the service account's bind fails or a search fails, the check changes nothing, logs Directory check skipped: …, and tries again at the next one. The same holds when a check would end access for more than half of the directory accounts not already ended, and more than five of them, at once: that is far more likely a wrong LDAP_BASE_DN or LDAP_REQUIRED_GROUP than people leaving, and the log says so. A genuine departure that large is left to administrators, who suspend those accounts. One check runs per interval however many server processes share the database.
The desktop app signs in to such a server through Sign in using your browser, which completes on the website.
Schools on Microsoft 365 whose accounts are only in Entra ID (formerly Azure AD) have no LDAP directory to point at; they use Microsoft sign-in instead (#292).
Browser and desktop flow
Browser sessions use 256-bit random credentials stored as SHA-256 hashes in PostgreSQL. Session cookies are HTTP-only, SameSite=Lax, Path=/ and use Secure plus the __Host- prefix when APP_ORIGIN is HTTPS. Sign-in replaces an existing session. Both anonymous sign-in and authenticated writes require a CSRF token bound to a server-issued cookie/session, and foreign Origin mutation requests are rejected. The server returns identity-provider availability to the UI; disabled providers have no sign-in buttons.
Social authorization uses a ten-minute, browser-bound, one-use state record and an allowlisted local return location. Google, GitHub and Microsoft additionally use S256 PKCE; Google and Microsoft ID tokens are checked against the provider's RSA signing keys, issuer, audience, nonce and expiry. GitHub and Facebook identities come from authenticated provider API calls; Facebook includes appsecret_proof. Before a web provider redirect, authenticated editable timeline contents can be saved in a temporary browser record and recovered on return, retaining the original server revision for conflict detection. Guest drafts are in memory only and are not written to this record; export .ochx before leaving the editor to sign in. If browser storage is unavailable, the app asks the user to export before navigating. Provider tokens are discarded after identity verification and are never returned to the frontend or saved as application sessions.
Accounts are identified by (provider, provider subject). Matching email addresses do not merge accounts. An existing signed-in user can explicitly Link Google/GitHub/Facebook/Microsoft in the web account dialog. Linking requires the same application session that started the flow and rejects a provider identity already belonging to another account. The desktop can use any linked provider through its system-browser sign-in flow; linking itself is performed on the website.
Sign in using your browser in the desktop opens the configured server in the operating system browser. The desktop displays a ten-character code (as two groups of five, such as K7MPQ-2XRTA). After signing in, the website's approval page (/connect/desktop/<code>) shows what the server recorded when the desktop app started the request:
- The computer, as it names itself: the computer's name (on macOS the name in Sharing settings, on Windows the computer name, on Linux the host name) and its system, which the desktop app sends when it starts signing in, so a person can tell their own computer from someone else's.
- When it started, and the address it came from.
- The program, by its User-Agent.
Whoever starts a request chooses the name and the User-Agent, so the page labels them as the request describes itself, never as verified. It says plainly to approve only a sign-in just started on one's own computer, and the code must be typed from the desktop app's window: the link carries the code, but the page does not fill it in, and it asks for the code from one's own screen, never from a message or from someone reading it out.
Another network. A person's own computer is usually on the same network as the browser approving it. The server compares the two addresses: the same IPv4 address (a household or office behind one public address), the same IPv6 /64 (one network, whose devices pick their own last 64 bits), or both on this computer (loopback) count as the same network. When they differ, the page says so prominently; when they can't be compared (one IPv4 and one IPv6, as on a network with both, or an address missing), it says that instead. Either way, approving then takes a second confirmation, a box to tick: "I started this sign-in myself, on my own computer, on another network". The server enforces it too: an approval of such a request without otherNetwork: true is refused with 409 and the request stays pending. A VPN or a phone's connection is the usual innocent reason.
Approval needs a browser session on the site (not a desktop session or an API key), signed in within five minutes, and emails the account (with the time, the address and the computer's name as it gave it, when email is configured). Approval exchanges a separate secret held by the native process for a desktop session, expires after ten minutes and can be consumed only once. Polling is limited to once every three seconds. A desktop session is accepted only as a Bearer credential; a browser cookie is accepted only as a web session. Native HTTPS requests verify certificates, do not follow redirects, and stay under the configured origin's API. The bearer and pending authorization secret never enter the webview, localStorage or browser cookies. Switching servers/disconnecting invalidates pending native responses and clears all credentials.
Sessions expire after fourteen days or twenty-four hours of inactivity. Activity updates at most once every five minutes. What an open page does on its own (the live-update stream and its revision polling) is not activity, so a tab left open does not keep an idle session alive. Logout revokes the current database record; Sign out other sessions revokes all other browser and desktop records immediately. There is no silent refresh token or persistent desktop login store.
Passwords and throttles
Passwords use salted scrypt with N=131072, r=8, p=1 and constant-time comparison, following the OWASP scrypt guidance. Each Node process runs at most PASSWORD_HASH_CONCURRENCY password derivations at once (1–64; by default one per available CPU core, at least two, and one fewer than libuv's worker threads, UV_THREADPOOL_SIZE, default 4, so with the defaults three on a machine with three or more cores). Each takes about 128 MiB, so raise UV_THREADPOOL_SIZE and check memory before raising it. Sign-in, registration, password resets and changes and the administrator password tools all share these slots. A request that finds them all busy waits in line, first come first served, for up to five seconds and then gets 503 "Sign-in is busy"; a password reset link is checked before any hashing. Older version-1 hashes are verified and upgraded on successful login. New passwords require 15–1024 characters with a matching confirmation; existing shorter passwords remain usable for sign-in. Spaces, Unicode, pasted passwords, and password managers are supported, without arbitrary composition rules or periodic expiry. New passwords are checked against known breached passwords through the padded HIBP range API using only the first five SHA-1 hash characters; stored passwords remain salted scrypt. A failed safety check blocks new password creation, not existing sign-ins; missing and social-only accounts perform the same costly verification work, waiting for and holding a slot just as a real check does, and receive the same failure message.
Sign-in, social starts and device approvals share database-backed throttles (ten attempts per minute per client address) across instances, with an additional local memory cap. There is no hard limit per account, since usernames are public and one would let anyone lock an account's owner out; repeated failures for an account ask for human verification instead (below). These checks, and the human verification, come before any password work. File conversion has a separate per-user throttle. An IPv6 client counts by its /64 network rather than its whole address, since one connection is usually given a whole /64, and an IPv4 address written IPv6-mapped (::ffff:a.b.c.d) as the IPv4 address. Queries of timelines without an account have their own limit, 600 a minute per address in each process (administration). By default the client address is the direct TCP peer. Set TRUST_PROXY=1 only when a trusted proxy overwrites X-Forwarded-For with one validated client IP and direct access to the Node port is blocked; chains and malformed headers are ignored. The Compose port is bound to host loopback. Configure the proxy's request-body limit to at least the .och file limit for uploads (TIMELINE_FILE_BYTES, 64 MiB by default).
Human verification
Actions spam would use ask for a quick check first. The server refuses them with 428 and a challenge; the web editor, website and desktop app show it in a small dialog and retry with the answer in an X-Challenge header. Each answer works once, for the action it was issued for.
| Action | When it asks |
|---|---|
| Registration, Forgot password, adding an email address | Always: these send email to an address the requester types. |
| Password and directory sign-in | After three failures in fifteen minutes from the client address or for the account, for each further attempt, instead of locking it out. |
| Opening a pull request or commenting on one | When the account is newer than CHALLENGE_TRUST_DAYS (default 7) and is not the timeline's owner or a member. Administrators are never asked. |
| Publishing a plugin | Always, except for administrators. |
CHALLENGE_PROVIDER chooses the check:
pow(default) is self-hosted proof of work. The browser finds a number whose SHA-256 with a server-signed salt matches, trying up toCHALLENGE_DIFFICULTY(default 150,000) hashes, which takes under a second on a typical computer and a few seconds on a phone. Nothing is sent to a third party and the strict content security policy is unchanged. Answers expire after ten minutes and are recorded inoc_challenge_usesso they cannot be replayed. An answer must carry its salt exactly as issued (fixed-width fields), so the same answer cannot be split differently between salt and number to count again. Proof of work makes each submission cost a bot CPU time and slows bulk scripts, but a determined attacker with native code can still answer quickly; the rate limits above still apply.turnstileuses Cloudflare Turnstile. Create a widget for your hostname and setTURNSTILE_SITE_KEYandTURNSTILE_SECRET_KEY. The server checks each token with Cloudflare's siteverify API, including its action and hostname, and the content security policy then allowshttps://challenges.cloudflare.comscripts and frames. Visitors' browsers contact Cloudflare. Signed-in desktop and API-key sessions, which cannot show the widget, are given proof of work; signing up or signing in from the desktop app is not possible with Turnstile, so use Sign in using your browser.offdisables checks, for example behind another bot filter. Sign-in then answers three failures in fifteen minutes for an account by delaying each further sign-in for it by 1.5 seconds rather than refusing it, so nobody can lock its owner out; the per-address limit still applies, but guessing one account's password from many addresses is limited only by that delay and password-work capacity, so a public server should usepoworturnstile.
Challenges are signed with a key derived from AUTH_ENCRYPTION_KEY; without it, each process signs its own, which only suits a single development server. Without TRUST_PROXY=1 behind a reverse proxy, every anonymous visitor shares the proxy's address, so after three sign-in failures from anyone, every sign-in asks for a check until the window passes (rather than being locked out).
Resend and verified registration
Set RESEND_API_KEY, AUTH_EMAIL_FROM (for example Circagraph <accounts@circagraph.org>), and AUTH_ENCRYPTION_KEY in your server environment. Generate the encryption key once with node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))". Keep it secret and back it up separately from the database: losing it prevents decrypting enrolled authenticator secrets. Do not regenerate it on container rebuilds.
Verify the sending domain in Resend and apply its DNS instructions for SPF/DKIM; configure DMARC appropriate to the domain. Use a restricted sending API key. The app uses the Resend HTTPS API, so SMTP configuration is unnecessary. Start the durable delivery worker with docker compose --profile mail up --build --wait -d. Jobs are encrypted in PostgreSQL, retried with exponential backoff, and use stable Resend idempotency keys. Expired queued messages and temporary proofs are removed by the worker. Emails contain plain text; no timeline data is sent to Resend.
Registration is disabled until email delivery and encryption are configured. A signup creates a pending record, not an account or session. The emailed confirmation expires after 24 hours, requires an explicit POST, and is bound to the browser that requested it. Open it in that browser; mail scanners cannot confirm by fetching a link. Tokens appear in URL fragments, are removed from browser history by the account page, and are stored only as hashes in the database. Register again to request another confirmation. Existing accounts and new social accounts must confirm an email address before obtaining an application session. Provider email claims never implicitly link accounts.
Accounts are for people 13 and older (ages). Registration asks for a year of birth, kept with the pending record and copied to the account when it is confirmed. A new social account gives it at the email step, before it can obtain a session; one that gives an age under 13 is deleted there, since it cannot have been used.
Two-factor authentication and recovery
Two-factor authentication is on while an account has an authenticator app or at least one passkey; either answers it. (A password reset removes passkeys but leaves it on, answered by recovery codes until a factor is added again.) In /account, enroll an authenticator app using the supplied key or otpauth link and confirm its six-digit code. TOTP uses RFC 6238, 30-second steps, a one-step clock tolerance, and rejects already consumed codes. Synchronize the server clock. Encrypted secrets use AES-256-GCM with account-bound authenticated data. Ten random 128-bit recovery codes are shown once and stored only as hashes; each works once after a successful password or social sign-in. Store them offline.
When enabled, application MFA applies to both password and social logins. A browser-bound challenge expires after five minutes and closes after five failed attempts; it provides no timeline access. Because each new sign-in makes a new challenge, wrong answers also count against the account across challenges: after ten in fifteen minutes (a window that starts at the first), authenticator and recovery codes are refused without being checked until the window ends, and the account is emailed, at most once a day, since whoever is guessing has its password or a linked sign-in. A passkey still answers the step during that time: its answer is a signature that cannot be guessed, so the owner is not locked out by someone else's guessing. The window is short so that someone who has only the first factor cannot keep the owner out for long, and ten allows for two challenges' worth of mistyped codes; it caps guessing at about a thousand codes a day where fifty a minute were possible before. Changing or resetting the password clears the count. Desktop sign-in uses the system browser and explicit device approval after a fully authenticated, recent browser sign-in. This also supports verified registration and MFA without exposing credentials to the webview.
Security changes require a live session, the current password where the account has one, and a fresh authenticator/recovery code or a passkey if MFA is enabled. The password confirms the change however long ago the session began; an account without one (signed up through a provider) needs a sign-in within five minutes instead. Enrollment, disablement, and recovery-code replacement (and adding or removing a passkey) revoke other sessions and every API key, and send notifications. Password changes revoke all sessions and API keys. Security changes also revoke approved-but-unclaimed desktop authorizations, so an earlier device approval cannot restore access after a password reset. Provider linking and desktop approval require recent authentication as well.
Forgot-password links expire after 30 minutes and work once. Recovery requests return the same response for eligible and unknown accounts. Resetting a password revokes all sessions and API keys, removes the account's passkeys, and does not disable MFA. Passkeys go because one can sign in on its own: a passkey someone else added must not outlast the reset. When passkeys were the account's only second factor, MFA stays on with its recovery codes, which answer the two-factor step and confirm adding an authenticator app or a passkey again. A password change made while signed in keeps the passkeys. Email changes require reauthentication, confirmation of the new address in the requesting browser, and notify the old address; confirmation revokes sessions and API keys. There is no email-only MFA bypass. Losing both the authenticator and recovery codes requires an operator-reviewed recovery policy; automated support bypass is deliberately unavailable.
TOTP is opt-in and is not phishing resistant; passkeys are. This release does not claim an independent security audit or regulatory certification.
Passkeys
A passkey (WebAuthn, #372) is a key pair held by the device, a phone or a security key, unlocked with a fingerprint, face or PIN. The site keeps only its public key, and a passkey made for one site's address answers nowhere else, so it cannot be phished.
Managing them. Under Account → Security, Add a passkey asks for a name and the same confirmation as any security change (the current password and, with two-factor authentication on, a code or another passkey), then the browser makes the passkey. Each is listed with its name, when it was added and when it was last used, and can be renamed (no confirmation) or removed (confirmed). An account has at most twenty. The first passkey of an account without an authenticator app turns two-factor authentication on and shows ten recovery codes, as enrolling an app does; later ones keep the codes. Adding or removing a passkey signs out every other session and pending desktop sign-in, and emails the account. Removing the last passkey of an account without an app turns two-factor authentication off and deletes the recovery codes; removing the app of an account with passkeys leaves it on, codes and all. Passkeys are managed only from a browser session on the site.
As a second factor. After a password, provider or directory sign-in, the two-factor step offers Use a passkey instead beside the code field. Recovery codes keep working. Every confirmation that accepts a code (security changes, API keys, unlinking a provider, deleting the account, and administration and moderation decisions in /admin) accepts a passkey instead: the form's Use a passkey button, or, in /admin, leaving the code empty.
Signing in with a passkey alone. Sign in with a passkey on /login lets the browser offer any passkey it holds for the site (a discoverable credential) and signs in with no password. A passkey that verified the person is two factors in itself (something held, and a PIN or biometric), so no further step follows and the session counts as having passed two-factor authentication. It is on by default; set PASSKEY_SIGN_IN=false (also 0, no, off) to keep passkeys as a second factor only, which hides the button and refuses the sign-in (404). It is a site setting, not an account one: an account that does not want it removes its passkeys, or uses an app instead. Passkeys made as non-discoverable credentials (some security keys) still answer the two-factor step. These sign-ins share the password sign-in's limit of ten a minute per client address; asking for the sign-in options has its own limit, so each passkey sign-in counts once. As with a password, a browser already signed in may sign in with a passkey, which replaces its session.
In the username field's autofill. Where the browser supports conditional mediation (#403), /login's username field (autocomplete="username webauthn") also lists the site's passkeys among its suggestions, and picking one signs in exactly as the button does: the same options, the same server checks, the same limits. While the sign-in form is shown, the page keeps a navigator.credentials.get({ mediation: 'conditional' }) request pending on a challenge from POST /api/auth/passkeys/sign-in/options (platform/lib/passkey-autofill.js). Challenges keep their five minutes and their single use: rather than one that lives as long as the page, the page asks for a new one thirty seconds before the old one expires, at once after a refused attempt (later ones wait five seconds, doubling, up to five minutes, as do failures to get one), and when the page comes back into view with its challenge stale or restored from the back-forward cache. A hidden page asks for nothing. An open page so asks for about one challenge every four and a half minutes, far inside the options' limit of ten a minute per address, and the server needs no longer-lived challenge, nor another kind of one. The pending request is aborted before the button's own request, a password sign-in, leaving the form or the page, since a browser runs one passkey request at a time; a password sign-in or button that fails starts it again. Browsers without conditional mediation, PASSKEY_SIGN_IN=false and pages without JavaScript are unchanged: the field is a plain username field and nothing is asked for.
What the server checks. Verification is the server's own (server/webauthn.mjs, on node:crypto alone; no WebAuthn library is added): the CBOR attestation object and authenticator data, and COSE public keys for EdDSA (Ed25519), ES256 (P-256) and RS256 (2048 bits or more).
- The relying party is the site's configured address,
APP_ORIGIN: its host is the RP ID, and the address itself the only origin accepted (no cross-origin frames). A passkey made under one address does not work under another, so changingAPP_ORIGIN's host means adding passkeys again. Browsers allow WebAuthn only over HTTPS, or onlocalhost. - User verification is required: an answer without it is refused, as is one without user presence.
- Each challenge is 256 random bits, stored as its SHA-256 for five minutes, bound to the session (adding, confirming) or the sign-in page's browser nonce (signing in, the two-factor step), and deleted as it is answered, whether or not the answer verifies, on a small connection pool of its own so that it stays deleted even when the change it confirms fails; a replayed answer finds nothing. Unanswered ones are swept as they expire. A security change ends the account's outstanding passkey challenges with its other sessions.
- The signature counter: when an authenticator keeps one, each use must report a higher count than the last, or the passkey is refused as possibly copied (removing it and adding it again clears this). Synced passkeys report 0 and are not checked.
- Attestation is not requested (
none) or checked, so any authenticator the browser accepts may be added; the AAGUID it reports is stored unverified.
Stored per passkey in oc_passkeys: the credential ID, the COSE public key and its algorithm, the signature counter, the transports the browser reported, the AAGUID, its name, and when it was added and last used. Challenges are in oc_passkey_challenges until answered or expired. None of it is secret, and none of it needs AUTH_ENCRYPTION_KEY, though passkeys, like the rest of two-factor authentication, need email and the key configured.
Desktop. The desktop app signs in through Sign in using your browser, which completes on the website, so a passkey works there as a second factor or alone, unchanged. The app itself never asks for one: its native sign-in form uses a password only and sends an account with two-factor authentication to the browser. Without a server, the desktop has no accounts, so passkeys do not apply to local timelines.
Verification
test/passkeys.test.mjs checks passkey verification with a software authenticator (each algorithm; a wrong origin or RP ID, a missing user verification, a counter that went backwards, a forged signature, malformed CBOR; challenges answered once), test/passkeys-postgres.mjs the routes against PostgreSQL, test/passkey-autofill.test.mjs when the autofill's challenge is replaced, and test/passkeys-live-postgres.mjs adding, using and removing one in Chromium with its virtual authenticator, signing in from the username field's autofill too. Core tests cover browser-bound CSRF, PKCE, Google JWT signatures/claims, malformed upstream responses, one-use OAuth callbacks, web/native session separation, and directory filter escaping, settings and identities. test/ldap-postgres.mjs signs in against a real OpenLDAP server (a Docker container it starts itself, or LDAP_TEST_URL), and skips when neither is available. test/device-approval-live-postgres.mjs approves a desktop sign-in on its page in Chromium, typing the code, and one from another network with the second confirmation; test/auth.test.mjs checks which addresses count as the same network. The PostgreSQL GitHub CI job runs the real HTTP account, sharing, identity-linking, device approval (with the request's details, the 409 for another network without confirmation, and the approval email), idle/absolute expiry, revocation and SQLite exchange tests with mocked provider HTTP responses. Native tests check credential removal, URL restrictions and connection changes. No live provider credentials are needed in CI. Actual provider registrations and the live circagraph.org deployment must be configured by the operator before provider login can work publicly.
Next.js platform integration
Browser accounts live at /login and /account. App Router handlers own /api/session, /api/auth/*, and all protected timeline APIs. OAuth callbacks retain the same provider URLs under /api/auth/<provider>/callback; register those URLs on https://circagraph.org. Return destinations are restricted to application pages, never arbitrary URLs. Desktop authorization opens /connect/desktop/<code> and redirects through Next login if necessary. Legacy /#desktop/<code> links redirect to that page.
The platform uses the existing PostgreSQL-backed session/OAuth service, with Next.js handling business pages and routing. No provider credentials are exposed to client components. SSR checks access independently of API checks, and private pages never enter a shared static cache. The per-request CSP nonce supports Next hydration without allowing arbitrary inline scripts.