Authentication System

VeriWorkly uses Better-Auth as its authentication framework, with passwordless email OTP as the primary method and three OAuth providers alongside it.

Authentication methods

1. Email OTP — a one-time passcode is emailed to the user; verifying it establishes a session. Configured through Better-Auth's emailOTP plugin.
2. Google OAuth
3. GitHub OAuth
4. LinkedIn OAuth

Each OAuth provider is registered only if its client ID and secret are both configured, so an unconfigured provider simply does not appear rather than failing at runtime.

Account linking

Account linking is enabled with google, github, and linkedin marked as trusted providers, so a user who signs up with email OTP and later signs in with Google lands on the same account rather than creating a duplicate.

Architecture

• Frontends (apps/studio, apps/portfolio, apps/site) use the Better-Auth client SDK for session lifecycle and the OTP verification UI.
• Backend (apps/server) is the authentication authority. Better-Auth is mounted at the /api/v1/auth base path and handles OTP generation, OAuth callbacks, session issuance, and email dispatch.

Session storage

Sessions are stored in both PostgreSQL and Redis:

• storeSessionInDatabase: true writes each session to the Session table.
• A secondaryStorage adapter backed by Redis caches session lookups, so the hot path does not hit PostgreSQL on every request.

Cookies

• Cookie prefix: veriworkly-auth.
• useSecureCookies is enabled when NODE_ENV=production, producing __Secure--prefixed cookies.
• Cross-subdomain sessions are enabled when AUTH_COOKIE_DOMAIN is set. Scoping the cookie to .veriworkly.com is what lets a login on Studio carry over to the portfolio builder and the published-portfolio host.

Proxy trust

trustedProxyHeaders is enabled, and the headers consulted for the client IP are configurable via AUTH_IP_ADDRESS_HEADERS (default: x-client-ip,x-forwarded-for,x-real-ip,cf-connecting-ip). This keeps IP-derived rate limiting and login alerts accurate behind Nginx or Cloudflare.

Configuration reference

export const auth = betterAuth({
  database: prismaAdapter(prisma, { provider: "postgresql" }),

  secondaryStorage: {/* Redis get / set / delete */},

  basePath: "/api/v1/auth",
  trustedOrigins: config.allowedOrigins,

  advanced: {
    trustedProxyHeaders: true,
    cookiePrefix: "veriworkly-auth",
    useSecureCookies: config.nodeEnv === "production",
    crossSubDomainCookies: {
      enabled: !!config.auth.cookieDomain,
      domain: config.auth.cookieDomain,
    },
  },

  plugins: [
    emailOTP({
      expiresIn: config.auth.otpTtlSeconds,
      allowedAttempts: config.auth.otpAllowedAttempts,
      sendVerificationOTP: async ({ email, otp, type }) => {
        await sendAuthOtpEmail({ email, otp, type });
      },
    }),
  ],
});

Security controls

OTP lifetime and attempts

Rate limiting

Better-Auth's own limiter runs on Redis, with a tighter custom rule on the send-OTP endpoint:

The application's own IP-based rate limiter runs in front of this as an additional layer, also at 20 requests / 60 seconds for /api/v1/auth/*.

Session cache invalidation

A before hook clears cached session data on /sign-out, /revoke-session, /revoke-sessions, /change-email, /change-password, and /delete-user, so a revoked session cannot keep working for the remainder of its Redis cache TTL. Updating or deleting a user invalidates every one of their cached sessions by token.

Automatic emails

Database hooks send transactional email on account lifecycle events:

• Welcome email — on user creation.
• New-device login alert — on session creation, including the provider, IP, and user agent. Suppressed within the first 15 seconds after signup to avoid duplicating the welcome email.
• Account deletion confirmation — before a user record is deleted.

Admin provisioning

On server boot, if no admin account exists for the configured ADMIN_EMAIL, one is provisioned automatically. ADMIN_EMAIL is compared case-insensitively and is a server-only value — it is never sent to the browser.

For the underlying tables, see Database Schema. For programmatic (non-session) access, see API Keys.