Skip to content
GitHub

Strutvane 0.2 is still being built. These pages describe how it will work; anything marked "Coming in 0.2" doesn't exist yet. Release notes and support policy.

Authentication

View as Markdownllms.txt

Authentication is how your app knows who is making a request: someone signs in once, and every later request carries proof that it’s them. (Deciding what they may do is authorization, a separate step.) In Strutvane, authentication comes from @strutvane/auth, which is part of every new app. You choose what it does in the installer, and you can change your mind later in config/auth.ts.

This page covers every sign-in method, two-factor, passkeys, sessions, API tokens, teams, impersonation and the switches that turn each feature on or off.

A new app with the default answers (email and password) already has sign-in. Start the app and sign in as the first admin from the API:

Terminal window
curl -i -X POST http://localhost:3000/login \
-H "Content-Type: application/json" \
-H "Origin: http://localhost:3000" \
-d '{"email":"admin@my-app.test","password":"the-password-the-installer-showed-you"}'

What you’ll see (something like this):

HTTP/1.1 200 OK
content-type: application/json
set-cookie: strutvane_session=4kQ…; HttpOnly; SameSite=Lax; Path=/
{"status":"signed-in"}

The strutvane_session cookie is your session: a random id the browser sends with every later request, so the app knows it’s you. On https the cookie is named __Host-strutvane_session, which a sibling subdomain can’t set or overwrite. (The prototype still calls it sv_session.) Ask who you are:

Terminal window
curl http://localhost:3000/user -H "Cookie: strutvane_session=<the value from set-cookie>"

What you’ll see:

{
"user": { "id": "1", "email": "admin@my-app.test", "name": "Admin", "emailVerified": true, "twoFactorEnabled": false },
"session": { "method": "password", "createdAt": 1763198521000, "passwordConfirmedAt": null },
"impersonator": null,
"team": null,
"roles": ["admin"]
}

In a real app you rarely call these routes by hand: the sign-in screen in your React UI does it for you. If the installer generated the admin password, the admin must choose a new one before doing anything else (see The first admin).

The installer asks about sign-in in its Sign-in and Teams groups (see Installation). Each answer switches on features in config/auth.ts.

# Question Choices (default bold) What it switches on
5 ★ How do people sign in? Email and password, email link only (passwordless), no sign-in password sign-in, or emailLink, or nothing
6 Extra sign-in security two-factor, email verification, passkeys, public registration (off) twoFactor, emailVerification, passkeys, registration
7 Social login none, Google, Microsoft, GitHub, Apple the social-login add-on
8 Enterprise SSO (needs teams) no, yes the sso add-on
9 API access for other apps personal access tokens, OAuth 2.1 server, none apiTokens, or the oauth-server add-on
10 Starting roles admin + member, admin + manager + member + viewer the role preset admin-member or admin-manager-member-viewer
11 ★ Teams no, yes teams
12 How a request picks its team team switcher in the app, subdomain how the current team is chosen

★ means the question is asked in Recommended mode; the others take their default unless you choose Custom.

What 0.2 shows you: a question that brings a package is shown only once that package is published and compatible. In 0.2 that hides question 7 (social login), question 8 (SSO) and the “OAuth 2.1 server” choice in question 9; they appear in the installer when their packages ship. (The installer prototype, spike 13, still shows every question; hiding them is decided and not built yet.)

The three sign-in modes (question 5):

  • Email and password follows Fortify’s model. Password reset is always part of it.
  • Email link only is passwordless: people type their email and get a single-use link that signs them in. Two-factor and passkeys still work on top.
  • No sign-in is for internal tools behind a gateway. Your generated API then requires an API token on every route unless you opt a route out, so nothing is open by accident (deny by default).

Every switch lives in config/auth.ts, one switch per feature. The installer writes your answers into this file, and you change them there. There are no AUTH_* keys in .env, and there’s no AUTH_SECRET: your APP_KEY is the one root secret (see Secrets and APP_KEY).

The feature names are the same everywhere: in the installer, in config/auth.ts and in these docs.

Switch Library default Default install What it gives you
registration off off /register (public sign-up)
emailVerification off on signed verification links, /email/verification-notification
passwordReset always on always on /forgot-password, /reset-password
passwordConfirmation off on /user/confirm-password and the password.confirm middleware
twoFactor off on authenticator-app codes and recovery codes
passkeys off off passkey sign-in and passkeys as a second factor
emailLink off off passwordless /email-link
apiTokens off on personal access tokens
teams off off teams, invitations, switching
impersonation off off users with the impersonate ability can sign in as another user

There are two sets of defaults, on purpose:

  • Library default is what defineAuthConfig uses for a switch you leave out: every optional feature off. Forgetting a line can only switch something off, never open something up.
  • Default install is what the installer writes when you keep its default answers. It writes every switch explicitly, so the file shows exactly what your app does.

Here is a typical file, with two-factor, email verification and passkeys on:

config/auth.ts
import { defineAuthConfig } from '@strutvane/auth'
export default defineAuthConfig({
appUrl: process.env.APP_URL ?? 'http://localhost:3000',
features: {
registration: false,
emailVerification: true,
passwordConfirmation: true,
twoFactor: true,
passkeys: true,
emailLink: false,
apiTokens: true,
teams: false,
impersonation: false,
},
passkeys: { rpId: 'localhost', rpName: 'My App', origins: ['http://localhost:3000'] },
roles: 'admin-member',
})

What you’ll see: the app starts with exactly those routes. If you turn on passkeys without the passkeys block, start-up stops with:

TypeError: auth config: features.passkeys needs a `passkeys: { rpId, rpName, origins }` block

A switched-off feature doesn’t exist. It has no routes, and its paths answer with the same 404, byte for byte, as a path that was never there. Its services refuse too, with not_found, so calling one from your own controller can’t bring it back. Why: a 403 would tell an attacker the feature exists.

HTTP/1.1 404 Not Found
content-type: application/problem+json
{"type":"about:blank","title":"Not found.","status":404,"code":"not_found"}

Send the email and password. Add "remember": true for a long-lived session (see Sessions).

Terminal window
curl -i -X POST http://localhost:3000/login \
-H "Content-Type: application/json" \
-H "Origin: http://localhost:3000" \
-d '{"email":"ada@my-app.test","password":"correct horse battery staple","remember":true}'

What you’ll see: one of two answers.

{"status":"signed-in"}

or, when the user has two-factor turned on:

{"status":"two-factor-required","methods":["totp","recovery-code","passkey"]}

In the second case the user is not signed in yet. They hold a short pending session (10 minutes) that counts as a guest everywhere, until they answer the two-factor challenge.

Every failure gives the same answer, whether the email is unknown or the password is wrong, so nobody can find out which emails have accounts:

HTTP/1.1 422 Unprocessable Content
content-type: application/problem+json
{"type":"about:blank","title":"These credentials do not match our records.","status":422,"code":"invalid_credentials"}

Behind the scenes:

  • Passwords are hashed by the framework’s Hash service, which auth uses (see Hashing). The default is scrypt (ln=17, about 128 MiB of memory per hash), Node’s built-in memory-hard algorithm. Old hashes are upgraded on the next sign-in. argon2 comes later as an opt-in hasher package; it isn’t in 0.2.
  • An unknown email still runs one full hash, so the response time doesn’t give it away either.
  • Every sign-in starts a new session id, so an id planted before sign-in is useless (session fixation).

To sign out:

Terminal window
curl -X POST http://localhost:3000/logout -H "Origin: http://localhost:3000" -H "Cookie: strutvane_session=<your session>"

What you’ll see: 204 No Content, and the cookie is cleared.

Every new password (registration, reset, change) follows NIST SP 800-63B by default:

  • at least 12 characters and at most 128;
  • not found in a list of breached passwords;
  • no composition rules (“one capital, one digit, one symbol”): they make passwords harder to remember without making them harder to guess.

The default rule is Password.min(12).uncompromised(). Apps that are required to use composition rules can add mixedCase(), numbers() and symbols(). A refused password answers with one issue per problem:

{
"type": "about:blank",
"title": "Choose a stronger password.",
"status": 422,
"code": "weak_password",
"issues": [
{ "path": ["password"], "field": "password", "code": "too_short", "message": "The password must be at least 12 characters." }
]
}

Each issue has the same shape everywhere: path (the location as a list), field (the same path as one dotted string, such as items.0.title), a stable code and a message from the message catalog. More detail: Passwords.

An email link (also called a magic link) signs someone in without a password. Turn on emailLink, or answer “Email link only” in the installer.

Step 1: ask for a link.

Terminal window
curl -X POST http://localhost:3000/email-link \
-H "Content-Type: application/json" \
-H "Origin: http://localhost:3000" \
-d '{"email":"ada@my-app.test"}'

What you’ll see:

{"status":"sent"}

You get this answer even for an unknown email, so it can’t be used to find accounts. If the account exists, a mail with a link like http://localhost:3000/email-link/<token> is sent.

Step 2: use the link. The link opens a page in your app, which confirms with a POST (mail scanners open links with GET to check them, and must not use up the link):

Terminal window
curl -X POST http://localhost:3000/email-link/<token> \
-H "Content-Type: application/json" \
-H "Origin: http://localhost:3000" \
-H "Cookie: sv_link=<the nonce cookie set in step 1 (the prototype's name)>" \
-d '{"remember":false}'

What you’ll see: {"status":"signed-in"}, or two-factor-required when the user has two-factor on (an email link never skips 2FA).

The link:

  • works once and expires after 15 minutes;
  • is bound to the browser that asked for it with a cookie, so a forwarded or intercepted link is useless on another device. Opening it in the wrong browser doesn’t use it up, so the right browser can still use it.

A passkey is a sign-in key stored on your phone, laptop or password manager (the WebAuthn standard). It can’t be phished, and it replaces both the password and the second step. Turn on passkeys and give the passkeys block in config/auth.ts.

A passkey sign-in is two requests that your sign-in page makes with the browser’s navigator.credentials.get():

resources/ui/lib/passkey-sign-in.ts
import { startAuthentication } from '@simplewebauthn/browser'
export async function signInWithPasskey(): Promise<void> {
const options = await fetch('/passkeys/options', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ mode: 'passwordless' }),
}).then((response) => response.json())
const response = await startAuthentication({ optionsJSON: options })
const result = await fetch('/passkeys/authenticate', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ response, remember: true }),
}).then((res) => res.json())
console.log(result) // { status: 'signed-in' }
}

What you’ll see: the browser shows its passkey prompt, then { status: 'signed-in' }. A passkey counts as two factors (the device plus your fingerprint, face or PIN), so a user with two-factor on isn’t asked for a code.

The mode is passwordless for signing in, second-factor for answering a two-factor challenge with a passkey, and confirm for confirming your password when you have no password. Signed-in users manage their passkeys at /user/passkeys (add, list, rename, remove; several per user).

Public sign-up is off by default, because most B2B apps invite people instead. Turn it on with registration: true (or the installer’s “public registration” choice).

Terminal window
curl -X POST http://localhost:3000/register \
-H "Content-Type: application/json" \
-H "Origin: http://localhost:3000" \
-d '{"name":"Grace","email":"grace@example.com","password":"correct horse battery staple"}'

What you’ll see:

  • With email verification on: {"status":"verification-sent"}, and no session yet. You get the same answer when the email is already taken; the owner of that address gets a “someone tried to register” mail instead. So registration can’t reveal who has an account.
  • With email verification off: {"status":"signed-in"}. A taken email has to be reported, as email_taken (rate-limited per IP).

New users get no roles. Give them roles yourself, or through a team invitation.

passwordReset is always on: an account with a password can always get back in. It’s two requests, like Laravel:

Terminal window
curl -X POST http://localhost:3000/forgot-password \
-H "Content-Type: application/json" -H "Origin: http://localhost:3000" \
-d '{"email":"ada@my-app.test"}'

What you’ll see: {"status":"sent"}, for known and unknown emails alike. The mail links to http://localhost:3000/reset-password/<token>; your reset page then sends:

Terminal window
curl -X POST http://localhost:3000/reset-password \
-H "Content-Type: application/json" -H "Origin: http://localhost:3000" \
-d '{"token":"<token from the link>","password":"a brand new long password"}'

What you’ll see: 204 No Content. The reset link:

  • is signed by the framework’s one signer, the same one that signs verification links, signed routes and temporary file links. A changed link answers 403 invalid_signature, an expired one 403 signature_expired;
  • lasts 60 minutes and works once;
  • dies if the password changes any other way.

A successful reset signs the user out everywhere: it revokes every session, every API token, every remembered device and every pending email link, and it lifts a lockout.

A signed-in user changes their own password with PUT /user/password and { "current": "…", "password": "…" }.

With emailVerification on, new users get a signed link: the framework’s one signer adds an HMAC over the path, the query, the expiry and a purpose, with a key derived from your APP_KEY, so the link can’t be edited or forged. It has Laravel’s shape:

http://localhost:3000/email/verify/42/9f2c1e7a0b4d6f8e1a3c5b7d9e0f2a4c6b8d0e1f?expires=1763202121&signature=5d1c…
  • 42 is the user id; the hash part is tied to the current email address, so the link stops working if the address changes.
  • The link is valid for 60 minutes by default. Opening it again after it worked is harmless.
  • A changed link answers 403 invalid_signature, an expired one 403 signature_expired. (The prototype signs with its own HMAC and answers both with 422 INVALID_TOKEN.)

A signed-in user asks for a new link:

Terminal window
curl -X POST http://localhost:3000/email/verification-notification -H "Origin: http://localhost:3000" -H "Cookie: strutvane_session=<your session>"

What you’ll see: {"status":"sent"}, or {"status":"already-verified"}. Resending waits 60 seconds between mails and allows 6 per hour.

To require a verified email on a route, use the verified middleware (see Middleware for routes). Unverified users get 403 email_not_verified. More detail: Email Verification.

Two-factor authentication (2FA) asks for a second proof after the password: a 6-digit code from an authenticator app (Google Authenticator, 1Password, Authy…). The codes follow the TOTP standard (RFC 6238), built on Node’s own node:crypto with no extra dependency.

Turning it on is two steps, so nobody locks themselves out. Both need a recent password confirmation.

Terminal window
# Step 1: get a secret to scan
curl -X POST http://localhost:3000/user/two-factor-authentication -H "Origin: http://localhost:3000" -H "Cookie: strutvane_session=<your session>"

What you’ll see:

{"secret":"JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP","otpauthUri":"otpauth://totp/my-app.test:ada%40my-app.test?secret=JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP&issuer=my-app.test"}

Show otpauthUri as a QR code. Then prove the app works with a current code:

Terminal window
# Step 2: confirm with a code from the app
curl -X POST http://localhost:3000/user/confirmed-two-factor-authentication \
-H "Content-Type: application/json" -H "Origin: http://localhost:3000" -H "Cookie: strutvane_session=<your session>" \
-d '{"code":"123456"}'

What you’ll see: the recovery codes, shown this once:

{"recoveryCodes":["7KQPM-X3RTN","H9WCD-2MZFA","…eight more…"]}

A recovery code is a one-time backup for when the phone is lost. There are 10 (twoFactor.recoveryCodes, 8 to 10), each works once, and POST /user/two-factor-recovery-codes replaces them all.

Answering the challenge at sign-in, after two-factor-required:

Terminal window
curl -X POST http://localhost:3000/two-factor-challenge \
-H "Content-Type: application/json" -H "Origin: http://localhost:3000" -H "Cookie: strutvane_session=<pending session>" \
-d '{"code":"123456","rememberDevice":true}'

Send "recoveryCode": "7KQPM-X3RTN" instead of code to use a recovery code. What you’ll see: {"status":"signed-in"}, with a new session id.

Good to know:

  • A code works once. Each 30-second step can be used a single time, even by two requests at the same moment, so a code read over your shoulder is useless.
  • “Remember this device” skips the code on this browser for 30 days, for this user only (twoFactor.rememberDeviceDays; 0 turns it off). Turning 2FA off forgets every remembered device.
  • The secret is stored encrypted (AES-256-GCM) and bound to the user.
  • DELETE /user/two-factor-authentication turns 2FA off.

More detail: Two-Factor Authentication.

Your own UI uses cookie sessions. The cookie holds a random id; the database stores only a keyed digest of it, so a database leak doesn’t hand out live sessions.

Setting in config/auth.ts Default Meaning
sessions.idleMinutes 120 signed out after 2 hours without a request
sessions.absoluteHours 12 signed out 12 hours after signing in, whatever happens
sessions.rememberDays 30 “remember me” sessions last 30 days
sessions.confirmPasswordMinutes 180 how long a password confirmation counts
sessions.twoFactorPendingMinutes 10 how long a half-done 2FA sign-in waits

“Remember me” is a long-lived session, not a separate cookie, so it shows up in the sessions list and can be revoked like any other.

Users see and end their own sessions:

Terminal window
curl http://localhost:3000/user/sessions -H "Cookie: strutvane_session=<your session>"

What you’ll see:

[
{"handle":"a1b2c3d4e5f60718","current":true,"method":"password","createdAt":1763198521000,"lastSeenAt":1763199002000,"ip":"127.0.0.1","userAgent":"Mozilla/5.0"},
{"handle":"0f1e2d3c4b5a6978","current":false,"method":"passkey","createdAt":1763112121000,"lastSeenAt":1763140000000,"ip":"203.0.113.7","userAgent":"Safari"}
]
  • DELETE /user/sessions/0f1e2d3c4b5a6978 signs out that one session.
  • DELETE /user/other-sessions signs out every session but this one, and answers {"revoked": 1}.

The session id also changes whenever privileges change: on sign-in, after 2FA, when switching teams and when impersonating.

Some actions are sensitive enough to ask for the password again, even when signed in: turning 2FA on or off, new recovery codes, starting an impersonation. The passwordConfirmation switch gives you the confirmation route and the password.confirm middleware. Without a recent confirmation these actions answer:

HTTP/1.1 423 Locked
content-type: application/problem+json
{"type":"about:blank","title":"Confirm your password to continue.","status":423,"code":"password_confirmation_required"}

Confirm, then retry:

Terminal window
curl -X POST http://localhost:3000/user/confirm-password \
-H "Content-Type: application/json" -H "Origin: http://localhost:3000" -H "Cookie: strutvane_session=<your session>" \
-d '{"password":"correct horse battery staple"}'

What you’ll see: 204 No Content. The confirmation counts for 3 hours. Users without a password confirm with a passkey (mode: "confirm").

Personal access tokens let scripts, mobile apps and other servers call your API without a browser session (Laravel Sanctum’s tokens). Turn on apiTokens (the installer’s default for question 9).

Create one while signed in:

Terminal window
curl -X POST http://localhost:3000/user/api-tokens \
-H "Content-Type: application/json" -H "Origin: http://localhost:3000" -H "Cookie: strutvane_session=<your session>" \
-d '{"name":"CI deploy","abilities":["post.view","post.create"],"expiresInDays":90}'

What you’ll see:

{
"plainText": "svp_3fKq9ZbX0aLmN2pQrS7tUvWx4yZ1Ab2Cd3Ef5Gh6Ij7k9QxA1b",
"token": {"id":"t_01","name":"CI deploy","abilities":["post.view","post.create"],"createdAt":1763198521000,"lastUsedAt":null,"expiresAt":1770974521000}
}

plainText is shown once. Only a keyed digest is stored, so nobody, you included, can read it again. Copy it now.

Use it with a Bearer header:

Terminal window
curl http://localhost:3000/api/posts -H "Authorization: Bearer svp_3fKq9ZbX0aLmN2pQrS7tUvWx4yZ1Ab2Cd3Ef5Gh6Ij7k9QxA1b"
  • Format: svp_ + 40 random characters + a 6-character checksum. The prefix lets GitHub and other secret scanners spot a leaked token; the checksum rejects typos without a database lookup.
  • Abilities are what the token may do: post.view, post.* or *. A token can only get abilities inside the app’s allowed list (tokens.abilities, default ['*']). The request must pass both the token’s abilities and your policies.
  • Expiry: 1 year by default (tokens.defaultExpiryDays), at most tokens.maxExpiryDays.
  • A bearer request never falls back to the cookie, and it skips the CSRF check, because browsers never attach bearer headers by themselves.
  • GET /user/api-tokens lists tokens (never the secret); DELETE /user/api-tokens/t_01 revokes one. A password reset revokes them all.
  • lastUsedAt is updated at most once a minute.

More detail: API Tokens.

With teams on, each team is one customer company, and people see only their team’s data (tenancy). Every user has a current team; the framework feeds it into the ORM’s tenant scope on every request.

Terminal window
# Create a team (you become its admin)
curl -X POST http://localhost:3000/teams -H "Content-Type: application/json" -H "Origin: http://localhost:3000" -H "Cookie: strutvane_session=<your session>" -d '{"name":"Acme"}'
# Invite someone as a member
curl -X POST http://localhost:3000/teams/7/invitations -H "Content-Type: application/json" -H "Origin: http://localhost:3000" -H "Cookie: strutvane_session=<your session>" -d '{"email":"grace@example.com","role":"member"}'

What you’ll see:

{"id":"7","name":"Acme","role":"admin"}
{"id":"inv_3","email":"grace@example.com","role":"member","expiresAt":1763803321000}
  • Invitations are mailed as a link to /team-invitations/<token>. They work once, last 7 days, only for the invited email address, and only once that address is verified. The invitee accepts with POST /team-invitations/accept and {"token":"…"}.
  • Roles come from the preset chosen in question 10: admin-member (admin, member) or admin-manager-member-viewer. What each role may do is decided by your policies.
  • A team always keeps at least one admin. Removing or demoting the last one answers 409 last_admin.
  • Switching (POST /teams/7/switch) changes the current team and starts a new session id. Removing someone from a team takes effect on their very next request.
  • Team routes: GET /teams, GET /teams/7/members, PUT /teams/7/members/<user> (change role), DELETE /teams/7/members/<user>.

Outsiders get 404, never 403, so team ids can’t be probed.

Impersonation lets a support person sign in as another user to see what they see. Turn on impersonation.

Terminal window
curl -X POST http://localhost:3000/impersonate/42 -H "Origin: http://localhost:3000" -H "Cookie: strutvane_session=<admin session>"

What you’ll see: 204 No Content and a new session, signed in as user 42. GET /user now shows "impersonator": {"id":"1","name":"Admin","email":"admin@my-app.test"}; your UI must show a banner with a “Leave” button when it’s set.

The rules:

  • You need the impersonate ability. Only the admin role holds it by default; give it to a support role in your policies if you need to. You also need a recent password confirmation.
  • Nobody can impersonate a user who also holds impersonate, or who has a higher role. So a support person can never become an admin. Never yourself, never nested.
  • Lasts at most 1 hour. DELETE /impersonate leaves and gives you a fresh session of your own.
  • While impersonating you can’t change the user’s password, two-factor, passkeys, tokens or sessions.
  • The start and the end are written to the audit log.

The installer creates the first admin account by running your seeder. Its email (default admin@<your-app>.test) is in .env as SEED_ADMIN_EMAIL. Its password is never written to any file:

  • In an interactive install, a generated password is shown once in the summary box. Copy it. It must be changed at first sign-in, and auth enforces this: the account can’t do anything else until it has chosen a new password. A generated password has been on your screen, so it shouldn’t stay in use.
  • You can type your own instead (masked, at least 12 characters; STRUT_ADMIN_PASSWORD in CI). A typed password isn’t forced to change: you chose it.

Lost it? Set a new one:

Terminal window
node strut user:password admin@my-app.test

Every sign-in route is rate-limited per IP address and per account. IPv6 addresses are grouped by /64, so rotating through one network’s addresses doesn’t help. Limits use the cache (the database by default), never process memory, so they hold across several app servers.

Limit (limits.*) Default
loginPerIp 10 per minute
loginPerAccount 20 per 15 minutes
registerPerIp 10 per hour
resetPerIp, resetPerAccount 5 and 3 per 15 minutes
emailLinkPerIp, emailLinkPerAccount 5 and 3 per 15 minutes
twoFactorPerAccount 10 per 5 minutes
passkeyPerIp 20 per minute
confirmPasswordPerAccount 5 per 5 minutes

On top, an account is locked after 5 failed password attempts in a row: first for 60 seconds, then twice as long after each further failure, up to 1 hour (lockout.threshold, baseSeconds, maxSeconds). Unknown emails lock exactly like real ones, so a lockout reveals nothing. A lockout blocks password sign-in only: password reset, email links and passkeys still work, and a reset lifts it.

HTTP/1.1 429 Too Many Requests
retry-after: 120
content-type: application/problem+json
{"type":"about:blank","title":"Too many attempts. Please try again later.","status":429,"code":"rate_limited"}

Every important step emits an event (sign-in, failed sign-in, 2FA enabled, token created, impersonation started…). The framework writes these security events to the audit_events table. Per-record history (“who changed this invoice”) is a separate add-on, @strutvane/activity-log. See Audit.

Events carry ids, methods and counts only. A test runs every feature end to end and proves that no password, token, code, cookie, link or 2FA secret ever reaches an event or a log line.

Mails go out in the background, so how long a response takes never depends on whether an account exists.

APP_KEY is the one root secret for sign-in; there’s no separate AUTH_SECRET. The installer generates 32 random bytes and writes them to .env only:

.env
APP_KEY=base64:SQpRxdLTPsuY+mWH31AJzjjhxEVSsw3vP56QbLlnh48=

Never copy that value: generate your own with node strut key:generate.

Every feature derives its own key from it through the framework’s keyring: keyring.derive(purpose) is HKDF-SHA256 over APP_KEY with the salt strutvane and the info strutvane:<purpose>:v1. A key made for one purpose (say, session digests) can’t be used for another (say, verification links).

Every stored secret (session ids, API tokens, reset and email-link tokens, recovery codes) is a keyed digest: an HMAC-SHA-256 with a derived key. A leaked database alone isn’t enough to use them.

Rotating APP_KEY signs nobody out. node strut key:rotate moves the old key to APP_PREVIOUS_KEYS. When a digest doesn’t match under APP_KEY, auth tries every key in APP_PREVIOUS_KEYS, and on a match stores the digest again under the current key. Drop an old key from the list once nothing uses it. See Encryption.

You protect your own routes with middleware aliases, like Laravel:

Alias Lets the request through when… Otherwise
auth someone is signed in (a pending 2FA session doesn’t count) 401 unauthenticated
guest nobody is signed in refused (the exact answer isn’t decided yet)
verified the email is verified 403 email_not_verified
password.confirm the password was confirmed recently 423 password_confirmation_required
abilities:post.create the bearer token has that ability refused (the exact answer isn’t decided yet)
routes/api.ts
import { defineRoutes, Route } from '@strutvane/framework'
import { PostController } from '../app/http/controllers/post.controller.ts'
export default defineRoutes([
Route.apiResource('posts', PostController).middlewareFor(['store', 'update', 'destroy'], 'auth'),
])

The auth tables are ordinary migrations in your app, applied by node strut migrate, with a real users model. They’re all marked internal, so they never get an automatic API or admin screen:

users, user_roles, sessions, auth_one_time_tokens (reset, email-link, passkey-challenge and remembered-device tokens), two_factor_recovery_codes, passkeys, personal_access_tokens, teams, team_members, team_invitations.

On MySQL, emails are compared with a binary collation, so Ada@x.test and ada@x.test can’t become two accounts by accident.

Auth works the same in both. The differences are around it:

  • Mail: with Docker, reset, verification, invitation and email-link mails land in Mailpit at http://localhost:8025. Without Docker, MAIL_MAILER=log writes them to your log.
  • Passkeys need an exact origin: use the address in APP_URL (http://localhost:3000), not 127.0.0.1, or the browser refuses the ceremony.
  • Commands like node strut user:password run inside the app container in Docker mode; you type them the same way.

Feature tests sign in without going through the sign-in screen. actingAs(user) takes a user model and signs that user in with a real session; withToken(token) sends an API token as a Bearer header.

tests/feature/posts.test.ts
import { beforeEach, it } from 'vitest'
import type { Application } from '@strutvane/framework'
import { client, refreshDatabase } from '@strutvane/framework/testing'
import { createApp } from '../../bootstrap/app.ts'
import { User } from '../../app/models/user.ts'
let app: Application
beforeEach(async () => {
app = createApp({ APP_ENV: 'testing', APP_KEY: 'base64:SQpRxdLTPsuY+mWH31AJzjjhxEVSsw3vP56QbLlnh48=', DB_CONNECTION: 'sqlite', DB_DATABASE: ':memory:' })
await refreshDatabase(app)
})
it('lets a signed-in user create a post', async () => {
const ada = await User.factory().create()
;(await client(app).actingAs(ada).postJson('/api/posts', { title: 'Hello' })).assertStatus(201)
})
it('refuses a request with no session and no token', async () => {
;(await client(app).postJson('/api/posts', { title: 'Hello' })).assertStatus(401)
})

What you’ll see:

✓ tests/feature/posts.test.ts (2 tests) 41ms

For an API token, use client(app).withToken(plainText) instead of actingAs(). The request then passes only with both the token’s abilities and your policies.

More detail: HTTP Tests.

Every sign-in fails with invalid_credentials

Section titled “Every sign-in fails with invalid_credentials”
{"type":"about:blank","title":"These credentials do not match our records.","status":422,"code":"invalid_credentials"}

Why: the email is unknown, the password is wrong, or the account uses an email link or passkey and has no password. All of these give the same answer on purpose. Fix: check the email in your database, then set a known password:

Terminal window
node strut user:password ada@my-app.test
Section titled “The email link says to use the same browser”
{"type":"about:blank","title":"Open the sign-in link in the same browser you requested it from.","status":422,"code":"email_link_other_browser"}

Why: the link is bound to the browser that asked for it. You requested it on your laptop and opened it on your phone. Fix: open the link in the browser where you typed your email. The link isn’t used up, so it still works there. Or request a new one from the phone.

{"type":"about:blank","title":"Not found.","status":404,"code":"not_found"}

Why: public registration is off by default. A switched-off feature has no routes. Fix: switch it on, or invite people through a team instead:

config/auth.ts
features: { registration: true },
{"type":"about:blank","title":"The code is invalid.","status":422,"code":"invalid_code"}

Why: the code was already used (each code works once), it expired (codes change every 30 seconds), or the phone’s clock is off. Fix: wait for the next code, and turn on automatic time in the phone’s settings. If the phone is lost, send a recovery code instead:

{"recoveryCode":"7KQPM-X3RTN"}

I lost my API token right after creating it

Section titled “I lost my API token right after creating it”

Why: plainText is shown once; only a digest is stored, so it can’t be shown again. Fix: revoke the old one and create a new one:

Terminal window
curl -X DELETE http://localhost:3000/user/api-tokens/t_01 -H "Origin: http://localhost:3000" -H "Cookie: strutvane_session=<your session>"

I’m locked out after a few wrong passwords

Section titled “I’m locked out after a few wrong passwords”
{"type":"about:blank","title":"Too many attempts. Please try again later.","status":429,"code":"rate_limited"}

Why: 5 failed password attempts in a row lock password sign-in for that email, for 60 seconds and then longer. Fix: wait for the time in the retry-after header, or reset the password with /forgot-password: a reset lifts the lockout.

{"type":"about:blank","title":"Confirm your password to continue.","status":423,"code":"password_confirmation_required"}

Why: turning 2FA on or off, new recovery codes and impersonation need a password confirmed in the last 3 hours. Fix: confirm first, then retry:

Terminal window
curl -X POST http://localhost:3000/user/confirm-password -H "Content-Type: application/json" -H "Origin: http://localhost:3000" -H "Cookie: strutvane_session=<your session>" -d '{"password":"your password"}'
{"type":"https://strutvane.dev/problems/csrf_token_mismatch","title":"Page expired","status":419,"code":"csrf_token_mismatch","detail":"This request could not be verified as coming from this site. Reload the page and try again."}

Why: a request that changes something, carries a session cookie and doesn’t come from your own pages is refused by the CSRF check. Auth’s routes give the same 419 csrf_token_mismatch as every other route. (The prototype’s routes still answer 403 FORBIDDEN here.) Fix: send the Origin header matching APP_URL from browser-like clients, or use an API token with Authorization: Bearer from scripts.