Authentication & Workspace Authorization

Relevant source files

The following files were used as context for generating this wiki page:

• lib/auth/server.ts
• lib/auth/workspace.ts
• lib/db/actions.ts
• lib/db/schema.ts
• README.md
• test/workspace-authorization.test.ts
• app/api/drafts/route.ts

Authentication identifies unique users, while Workspace Authorization enforces multi-tenant data isolation. Vantage integrates Neon Auth (Managed Better Auth) for user identity and a custom workspace ownership model for resource protection.

Sources: README.md:8-10, lib/db/schema.ts:98-100

User Authentication

Vantage uses Neon Auth to manage user sessions and credentials. The application requires environment variables for NEON_AUTH_BASE_URL and NEON_AUTH_COOKIE_SECRET to operate the authentication middleware and session retrieval.

Authentication Flow

1. A user attempts to sign in via /auth/sign-in or sign up via /auth/sign-up.
2. Neon Auth validates credentials and sets a secure cookie.
3. The server-side auth.getSession() helper retrieves the active user session.
4. If a session exists, the system redirects the user to their active workspace or the onboarding flow.

Sources: README.md:14-20, app/page.tsx:22-50

Workspace Architecture

Workspaces act as the primary container for all platform data, including sources, documents, leads, and drafts. Each workspace is owned by a specific user identified by ownerUserId.

Workspace Data Model

The workspace table defines the tenant structure and resource limits.

Field	Type	Description
id	uuid	Primary key and unique workspace identifier.
name	text	Display name for the workspace (1–100 characters).
ownerUserId	text	The Neon Auth user ID who owns this workspace.
plan	text	The billing plan (default: free).
budgetUsdMonth	numeric	Monthly spending limit for paid provider calls.

Sources: lib/db/schema.ts:90-112, lib/db/actions.ts:16-18

The diagram shows the relationship between a User and their Workspaces, where a workspace acts as a parent for all operational data. Sources: lib/db/schema.ts:90-150

Workspace Authorization

Workspace authorization ensures that authenticated users only access data belonging to workspaces they own. This logic is centralized in the authorizeWorkspace utility.

Access Control Logic

• Unauthenticated: Requests without a valid session receive a 401 Unauthorized response.
• Unauthorized Owner: Authenticated users attempting to access a workspace they do not own receive a 403 Forbidden response.
• Authorized: Access is granted only if the session.user.id matches the workspace.ownerUserId.

Sources: test/workspace-authorization.test.ts:41-69, lib/db/actions.ts:25-27

API Route Protection

Every protected API route, such as the drafts endpoint, performs an authorization check before processing requests.

// app/api/drafts/route.ts
const authorization = await authorizeWorkspace(workspaceId);
if (!authorization.ok) {
  return NextResponse.json(
    { error: authorization.error },
    { status: authorization.status },
  );
}

Sources: app/api/drafts/route.ts:24-30

The flow diagram illustrates the sequential checks performed to ensure secure data access within a specific workspace. Sources: test/workspace-authorization.test.ts:41-70

Admin Authorization

Special administrative actions, such as toggling global source switches, require Admin status. Admin identification relies on the VANTAGE_ADMIN_USER_IDS environment variable.

Admin Verification Rules

• The system parses a comma-separated list of IDs from VANTAGE_ADMIN_USER_IDS.
• isAdmin verifies if the current user's ID exists within this list.
• Cross-site requests to admin endpoints are blocked using Origin and sec-fetch-site header verification.

Sources: test/source-switch-admin.test.ts:70-85, test/source-switch-admin.test.ts:100-115

Summary

Vantage implements a strict multi-tenant architecture where Authentication via Neon Auth establishes identity, and Workspace Authorization restricts data access based on resource ownership. Security is maintained by consistent application of the authorizeWorkspace check across both UI components and API routes.