logicspike/docs

Authentication & Team

Authentication Flows (Technical Specification)

This document outlines the complete technical routing, database transactions, and data flows for authenticating users within the LogicSpike platform.

1. Registration & Login (Email & Password)

Registration (POST /manager/auth/register)

  • Payload: { "email": "...", "password": "...", "name": "...", "workspaceName": "..." }
  • Validation: Zod schema validation in the Manager service.
  • Process (ACID Transaction):
    1. Hashes password securely via @repo/core-auth.
    2. Creates users record.
    3. Creates userAuthProviders record (provider: "email").
    4. Creates a tenants (Workspace) record using a URL-friendly slug based on workspaceName.
    5. Links the User and Tenant via memberships (Role: "role_owner").
    6. Provisions default services in tenantServices.
  • Response: Yields an access_token containing user, tenant, role, and PBAC permissions.

Standard Login (POST /manager/auth/login)

  • Payload: { "email": "...", "password": "..." }
  • Process:
    1. Looks up userAuthProviders by email.
    2. Uses timing-safe string comparison to verify the provided password against the hashed stored password.
    3. Checks user.isTwoFactorEnabled. If true, returns { "mfa_required": true } instead of a token and expects a TOTP verification. If false, issues the access_token JWT immediately.

2. OAuth Registration & Login (Google)

OAuth Flow (POST /manager/auth/oauth)

Handles both new users and returning users seamlessly through a single endpoint.

  • Payload: { "email": "...", "provider": "google", "providerUserId": "..." }
  • Process:
    • Automatically checks if the email already exists in the users table.
    • New User: Executes the exact same account creation ACID transaction as Email Registration, but skips the password hash step and marks the email as verified (isVerified: true).
    • Existing User: Automatically links the Google account by inserting a new record into userAuthProviders, enabling seamless transitions between email login and Google login.
  • Response: Yields the access_token JWT.

3. Phone Verification & Login

LogicSpike supports phone numbers as an alternate login method, but phone numbers are not automatically linked across services like OAuth emails are.

Linking a Phone Number (PATCH /manager/auth/phone)

  • Requires an active access_token JWT.
  • Automatically updates the user's profile and sets phoneVerified: false.
  • Used heavily for SMS-based notifications or future SMS-based 2FA.

Phone Login (POST /manager/login/phone)

  • Requests the system to send an OTP SMS to the linked phone number.
  • Response: Only returns 200 OK if the user is found and the phone is properly linked.

4. Two-Factor Authentication (TOTP)

The platform supports Time-based One-Time Passwords (TOTP) compliant with RFC 6238 via the otpauth library.

Setup and Enable

  1. Setup (POST /manager/auth/mfa/setup): Generates a Base32 20-byte secret and returns an otpauth:// URL (to generate a QR code on the frontend).
  2. Enable (POST /manager/auth/mfa/enable): The user scans the QR code and enters the 6-digit TOTP code. The backend validates it against the pending secret and updates the user record: isTwoFactorEnabled = true.

Validating 2FA During Login

When isTwoFactorEnabled is true, the initial POST /auth/login endpoint purposefully withholds the access_token.

  • The frontend must capture the { "mfa_required": true } response and prompt for the 6-digit Authenticator code.
  • Verify (POST /manager/auth/mfa/verify): Endpoint validates the { "email", "code" } payload. Upon success, it generates and releases the final robust JWT access_token.

Gateway Architecture

All of the above endpoints reside in the manager app, which is deeply shielded.

  • The Cloudflare gateway exposes proxy routes (/manager/auth/*).
  • Because these routes are used for acquiring tokens, they are explicitly whitelisted as Public Paths in the gateway middleware.
  • To securely bypass the Manager's internal internet blockade, the Gateway forcefully attaches the x-gateway-key secret header to all proxy requests.
Authentication & Team