Authorization & Sessions

VitNode implements two isolated sessions: a public session for the community site and a separate admin session for the AdminCP. Both use opaque random tokens stored as SHA-256 hashes in PostgreSQL.

Quick startCopy Anchor Link

Customize session parameters in apps/api/src/vitnode.api.config.ts:

import { buildApiConfig } from "@vitnode/core/vitnode.config"

export const vitNodeApiConfig = buildApiConfig({
  authorization: {
    cookieExpires: 1000 * 60 * 60 * 24 * 30, // 30 days for public users
    adminCookieExpires: 1000 * 60 * 30, // sign staff out after 30 idle minutes
    cookieDomain: ".yourdomain.com", // Optional cross-subdomain sharing
  },
})

The Two-Session ModelCopy Anchor Link

AdminCP Session TimeoutCopy Anchor Link

The AdminCP is the keys to the kingdom, so its session is deliberately short-lived. Staff are asked to sign in again when:

• They go quiet for an hour. Every AdminCP request pushes the expiry an hour ahead, so an admin who keeps working is never interrupted. Leave the tab alone for an hour and it signs itself out and lands on the sign-in page, with a toast explaining why. Tune the window with adminCookieExpires.
• They close every AdminCP tab. Open AdminCP tabs keep a heartbeat going. Open the AdminCP again after every tab was closed and VitNode ends the old session instead of letting it back in. A page reload, or opening one more AdminCP tab while another is still open, is not affected. This check is skipped when cookieDomain is set: a browser can only see tabs on its own origin, so an AdminCP tab open on another subdomain would look closed.
• They close the browser. The vitnode_auth_admin cookie has no expiry date, so the browser drops it when it shuts down.

Security GuaranteesCopy Anchor Link

• SHA-256 Token Storage: The raw token is stored only in the user's HttpOnly cookie. The database stores only its cryptographic hash.
• Device Pinning: Tokens are bound to a verified device ID. Tokens copied to another device without the matching device cookie are rejected.
• Fast 60-Second Caching: Active sessions are cached in Redis for up to 60 seconds, eliminating database query overhead on repeated requests.
• Canonical Email Identity: Addresses are stored in their canonical form, so Gmail dot, googlemail.com and +tag variants cannot become a second account. See One Mailbox, One Account.

One Mailbox, One AccountCopy Anchor Link

jankowalski@gmail.com and jan.kowalski@gmail.com look like two addresses. Gmail ignores the dots, so they are one mailbox - and a site that treats them as two lets the same person hold two accounts, dodge a ban, or farm their own referral link.

VitNode stores the canonical form of an address, so those tricks collapse into a single account:

The rules are per-provider, because they are only true per-provider:

• Dots are removed for gmail.com and googlemail.com only. Everywhere else a dot is part of the mailbox, so jan.kowalski@company.com is left alone.
• googlemail.com folds into gmail.com. Google treats them as one domain.
• +tag suffixes are dropped for Gmail and for the providers that document sub-addressing: Outlook, Hotmail, Live, MSN, iCloud, Proton, Fastmail, GMX, Yandex and Zoho. Mail sent to the canonical address still lands in the same inbox.
• Everything else is kept as typed, lowercased. A + can be a real character in a corporate address, so guessing there would lock people out.
• Yahoo's - aliases are deliberately left alone, because jan-kowalski@yahoo.com is a perfectly ordinary name.

SELECT
  replace(split_part(split_part(lower("email"), '@', 1), '+', 1), '.', '') AS mailbox,
  array_agg("email")
FROM "core_users"
WHERE lower("email") LIKE '%@gmail.com' OR lower("email") LIKE '%@googlemail.com'
GROUP BY 1
HAVING count(*) > 1;

authorization Options ReferenceCopy Anchor Link

Turning off password sign-inCopy Anchor Link

Running a passkeys-only or social-login-only community? Switch passwords off:

export const vitNodeApiConfig = buildApiConfig({
  authorization: {
    password: false,
  },
})

With passwords off:

• /login hides the email + password form and Forgot password?. It keeps SSO buttons and Sign in with a passkey - if neither is configured, members see a "Signing in is unavailable" notice.
• /register hides the sign-up form. New accounts can still come in through SSO; with no SSO provider, the page says registration is unavailable and the "Sign up" link on /login goes away.
• /login/reset-password answers "not found".
• The API refuses POST /users/sign_in (for members), /users/sign_up, /users/reset-password, /users/change-password and password-based SSO linking with 403.
• A stored password no longer counts as a way into the account, so members can't remove their last passkey unless they have another passkey or a linked SSO provider.

Password hashes already in the database are left alone, so switching enabled back to true restores password sign-in for everyone who had one.

Learn MoreCopy Anchor Link