Phase 20 — Login & User Identity

Goal: Add a user identity layer so memory, sessions, libraries, and preferences are properly partitioned per user. All stores are keyed to a user_id from day one so multi-user is a data concern, not an architecture rewrite.

1. Architecture Overview

Browser                       Gateway                        Bus / Agents
──────                        ───────                        ────────────
POST /api/auth/login ──────► validate credentials
  username + password          issue session token ────────► cookie (HTTP-only)

WS /ws/chat/{session_id} ──► check cookie
  (with cookie)                resolve user_id
                               inject into query.received
                                 {query, session_id, user_id}  ──────────────────►  GeneratorAgent
                                                                                     MemoryAgent  → MemoryService  (filter by user_id)
                                                                                     ConversationService           (tag sessions)

2. User Store

Storage

A JSON file at ~/.local2/users.json managed by a UserService. Simple, portable, no external dependency.

{
  "users": [
    {
      "user_id": "a3f8c2d1-...",   // stable UUID, assigned at creation
      "username": "richard",
      "password_hash": "$2b$12$...",  // bcrypt
      "created_at": 1750000000.0,
      "role": "admin"               // admin | user (future use)
    }
  ]
}

UserService

# src/local/services/user_service.py

class UserService:
    def create_user(self, username: str, password: str, role: str = "user") -> str:
        """Create a user. Returns user_id. Raises if username taken."""

    def authenticate(self, username: str, password: str) -> str | None:
        """Verify credentials. Returns user_id or None."""

    def get_user(self, user_id: str) -> dict | None:
        """Return user record by user_id."""

    def list_users(self) -> list[dict]:
        """Return all users (without password_hash)."""

    def change_password(self, user_id: str, new_password: str) -> None:

CLI commands

local2 useradd <username>     # prompts for password; first user gets role=admin
local2 userlist               # list users
local2 passwd <username>      # change password

3. Session Tokens

After successful login, the gateway issues a random 32-byte token (URL-safe base64), stores it server-side in a TokenStore dict mapping token → {user_id, expires_at}, and sets it as an HTTP-only cookie named local2_session.

TokenStore (in-memory, not persisted):
  { "aB3xQ...": { "user_id": "a3f8c2d1-...", "expires_at": 1750086400.0 } }

Default TTL: 30 days. Token is renewed on each authenticated request. On process restart, all tokens are invalidated — users re-login. This is acceptable for a local assistant; persistent tokens can be added later.

4. Auth API Endpoints

Auth middleware

FastAPI dependency require_auth(request) — reads local2_session cookie, validates against TokenStore, returns user_id. Applied to all /api/* endpoints and the WebSocket handshake.

Static assets (/assets/*, /) and the auth endpoints themselves are unauthenticated. The frontend handles the redirect to login if /api/auth/me returns 401.

5. WebSocket Auth

At WS /ws/chat/{session_id} connect time, the gateway reads the local2_session cookie from the WebSocket handshake headers and resolves user_id. If the token is invalid, the WebSocket is rejected with a 4001 close code. The resolved user_id is attached to the session for the lifetime of the connection.

6. Threading user_id Through the Pipeline

user_id is added to QueryReceived and flows through every downstream message that currently carries session_id.

Messages to update

Agents and services to update

7. Data Partitioning

Episodic Memory

Add user_id to every engram's metadata. Filter search_episodic with a ChromaDB where clause: {"user_id": {"$eq": user_id}}. Users never see each other's memories.

Session History

Add user_id field to each session entry in ConversationService. list_sessions(user_id) returns only that user's sessions. get_history(session_id, user_id) returns 404 if the session belongs to a different user.

Library / RAG Documents

Migration of Existing Data

Existing data has no user_id. On first startup after this phase, a migration script assigns all orphaned records to a "default" user. The first user created via local2 useradd or the setup screen should have their account linked to this "default" user_id, or a separate migration step reassigns data.

8. Frontend Changes

Login screen

The React app checks GET /api/auth/me on load. If 401, it renders a login form (username + password) instead of the chat UI. On success, the cookie is set by the server and the app renders normally.

First-run setup screen

If /api/auth/me returns a special 403 setup_required status, the app renders a "Create your account" form that calls POST /api/auth/setup. This only works once.

User indicator

Small username + logout button in the header bar next to the token gauge.

9. Sub-phases

10. Files Changed

11. Out of Scope (Phase 20)

• OAuth / SSO / external identity providers
• Email verification or password reset flow
• Role-based access control beyond admin/user distinction
• Audit logging of user actions
• Per-user model selection (each user picks their own generator model)
• Phase 19 (Preferences) — implement after this phase completes