feat: Auto-provision users during OAuth login

[nycomp]

Background

When users sign in to campus-admin via OAuth (Google, GitHub, etc.), the authentication flow completes but the application crashes with a 500 error:

ServerError: Document/row with id 'test_student@nyjc.edu.sg' not found in collection/table 'users'

Problem Investigation

The OAuth callback flow works like this:

1. User clicks "Sign In" → redirected to Google/GitHub/etc.
2. Provider redirects back with authorization code
3. Backend exchanges code for access token and user info (email, name)
4. Credentials are stored in the database
5. Session is updated with the user_id
6. User is redirected back to campus-admin

However, when campus-admin tries to display the dashboard, it calls push_context() to load the authenticated user's details. This looks up the user in the users table... but the user record was never created in step 4.

Your Task

Implement auto-provisioning of user records during the OAuth callback flow. When a user successfully authenticates via OAuth, their user record should be created automatically if it doesn't already exist.

Key Requirements

1. Idempotent operation: If the user already exists, return the existing record
2. Minimal database changes: Only create if necessary
3. Consistent across providers: All OAuth providers (Google, GitHub, Discord) should use the same mechanism
4. Thread-safe: Handle race conditions if two requests try to create the same user simultaneously

Files to Investigate

• campus/auth/resources/user.py - User resource with CRUD operations
• campus/auth/oauth_proxy/google/proxy.py - Google OAuth callback
• campus/auth/oauth_proxy/github/proxy.py - GitHub OAuth callback
• campus/auth/oauth_proxy/discord/proxy.py - Discord OAuth callback

Acceptance Criteria

• User records are created automatically on first OAuth login
• Subsequent logins retrieve the existing user record
• No 500 errors when new users log in
• All three OAuth providers (Google, GitHub, Discord) work correctly

Testing Hints

• Check the Railway logs for campus-auth after deploying your changes
• Try logging in with a test account that doesn't exist in the database
• Verify the user record is created correctly with email and name

---

Subscribed: @saltensity

[nycomp]

💡 Proposed Implementation

Interface to Add

Add a method to the UsersResource class:

Method signature:

get_or_create(user_id: schema.UserId, email: schema.Email, name: schema.String) -> campus.model.User

• try to fetch existing user, catch NotFoundError, create new user if needed

Location: campus/auth/resources/user.py, inside the UsersResource class

---

Callsites to Update

After the OAuth provider obtains user information from the external provider (email, name), add a call to your new method before storing credentials.

Files to modify:

• campus/auth/oauth_proxy/google/proxy.py - in the handle_auth_callback() method, after getting user_id from userinfo
• campus/auth/oauth_proxy/github/proxy.py - in the handle_callback() method, after getting user_id from userinfo
• campus/auth/oauth_proxy/discord/proxy.py - in the handle_callback() method, after getting user_id from userinfo

Timing: The call should happen after domain validation (if present) but before resources.credentials[PROVIDER][user_id].update()

---

Additional Consideration

The existing new() method in UsersResource currently accepts **kwargs. You may want to make its parameters more explicit (email, name) to make the interface clearer and catch type errors earlier.

[nycomp]

🧪 Testing Requirements

Test File Location

COMPLETED: Tests have been implemented as integration tests (not unit tests) since they test the full resource-storage interaction:

campus/tests/integration/auth/resources/test_user.py

This follows the pattern: tests/integration/{module}/{resources}/test_{resource}.py

---

How Testing Works in This Project

Important: Integration tests use real storage operations (not mocks). The storage layer automatically selects an appropriate backend:

Environment	Table Storage	Collection Storage
Test (STORAGE_MODE=1)	SQLite (in-memory)	MemoryCollection
Production	PostgreSQL	MongoDB

When tests run with STORAGE_MODE=1, all storage operations use fast in-memory backends automatically. This means integration tests use real storage operations against in-memory databases.

---

Test Class Structure

import unittest
from campus.auth.resources.user import UsersResource
from campus.common import schema
import campus.storage.testing


class TestUsersResourceGetOrCreate(unittest.TestCase):
    """Integration tests for UsersResource.get_or_create() method."""

    @classmethod
    def setUpClass(cls):
        """Configure test storage and import resources once before all tests."""
        # MUST configure test storage BEFORE importing auth resources
        # (to avoid storage initialization order issues)
        campus.storage.testing.configure_test_storage()

        # Lazy import after test mode is configured
        from campus.auth.resources.user import UsersResource

        # Initialize storage schema
        UsersResource.init_storage()
        cls.resource = UsersResource()

    @classmethod
    def tearDownClass(cls):
        """Clean up test storage after all tests."""
        campus.storage.testing.reset_test_storage()

    def setUp(self):
        """Clean and reinitialize storage before each test."""
        campus.storage.testing.reset_test_storage()
        # Reinitialize table schema after reset
        UsersResource.init_storage()

    def test_get_or_create_creates_new_user_when_not_exists(self):
        """Should create a new user record when email doesn't exist in database."""
        email = schema.Email("new_user1@example.com")
        name = "New_User1"
        user_id = schema.UserID(email)

        user = self.resource.get_or_create(email, name)

        # Verify user was created
        self.assertIsNotNone(user)
        self.assertEqual(user.email, email)
        self.assertEqual(user.name, name)
        # Verify can retrieve from storage
        retrieved_user = self.resource[user_id].get()
        self.assertEqual(retrieved_user.id, user.id)

    # ... additional test methods ...

---

Run Tests

# Run integration tests for auth resources
python tests/run_tests.py integration

# Or run specific test file
.venv/Scripts/python.exe -m unittest tests.integration.auth.resources.test_user -v

---

Implementation Status

✅ COMPLETED:

• get_or_create(email, name) method implemented in UsersResource
• Updated Google OAuth proxy to use get_or_create()
• Integration tests implemented (8/8 passing)
• Type checks passing (0 errors)
• Method signature simplified: user_id parameter removed (derived from email)