Skip to main content

​
Authentication and Permissions

Source: equa-server/modules/auth/src/

​
Authentication Methods

Equa supports three authentication methods, all resulting in a server-side session.

​
1. Password Login

Source: equa-server/modules/auth/src/authentication.ts
  • Password hashing: bcryptjs (10 rounds)
  • Two-factor authentication: Supported via twoFactorToken
  • Email verification: Required before login
  • Temporary passwords: Supported via checkTempPassword()
  • On success: session.user = result.user.id (line 72)

​
2. Google OAuth

Source: equa-server/modules/auth/src/google-auth.ts, equa-server/modules/api/src/server.ts
  • Supports both ID tokens and access tokens
  • Validates email verification status
  • Checks audience (aud) matches client ID
  • Validates g_csrf_token cookie/body consistency in API middleware before Google auth endpoint execution
  • Auto-registration: Creates user if email not found (random password assigned)
  • On success: session.user = user.id (line 88)
Source: equa-server/modules/auth/src/magic-link.ts
Note: magic-link.ts is currently an untracked file in the equa-server repo. It imports a MagicLinks entity from persistence that has not yet been added to schema.ts. This feature is in development but not yet integrated into the database schema.
Functions:
  • sendMagicLink() — Creates magic link record and sends email
  • verifyMagicLink() — Validates token, checks expiry, marks as used
  • magicLinkLogin() — Creates session after verification
  • cleanupExpiredMagicLinks() — Cleanup for expired links

​
Session Management

Source: equa-server/modules/auth/src/sessions.ts Sessions are persisted in the sessions table with columns: id, expires (indexed), user (indexed), json.

​
Authorization Model (RBAC)

Source: equa-server/modules/auth/src/authorization.ts, equa-server/docs/cascading-permission.puml

​
Entities

​
Permission Check Flow

  1. Endpoint declares requires?: PermissionCheck property
  2. vineyard-lawn calls the permission check function before the handler
  3. Check verifies:
    • User is logged in (requireLoggedInSync())
    • User has required role/permission for the target organization
  4. If check fails, returns 403 Forbidden

​
Key Authorization Functions

Source: equa-server/modules/auth/src/authorization.ts

​
Cascading Permission Model

Source: equa-server/docs/cascading-permission.puml The cascading permission model supports nested organizations with permission inheritance:
  • Direct permissions: User has a role directly assigned in the organization
  • Indirect permissions: User inherits permissions from a parent organization
  • Union: For read operations, permissions from parent and child are combined
  • Intersection: For write operations, only overlapping permissions apply

​
Role Tables

​
Permission Enumeration

Source: Confluence KnowledgeBase — Equa App Permissions (by Christopher Johnson)

​
Organization Permissions (15)

​
Site Permissions (2, for site admins only)

The authorization module maps these to endpoint-level checks:
  • requirePermissions() — generic permission check
  • canWriteSite() / canReadSite() — site-level admin access
  • canEditCapTable, canViewOrganization, canEditMembers, canEditOrganizationBilling, etc. — organization-level checks used in endpoint definitions

​
Security Notes

  • No explicit rate limiting middleware found in the codebase
  • Registration IP limit: REGISTRATION_IP_LIMIT (default: 20; applied in modules/referral/src/referral.ts)
  • Domain blacklist: domain_blacklists table
  • Email blacklist: email_blacklists table
  • Email verification required before login
  • Two-factor authentication supported but optional