Add Google OAuth sessions and team access UI (#8)

* Add Google OAuth sessions and team access UI

* Fix OAuth review issues and e2e CORS

* Fix team access review bugs

* Gate destructive Prisma sync

---------

Co-authored-by: chris <chris@chrisdeMac-mini.local>

Author: fakechris

.env.example

@@ -1,5 +1,11 @@
 DATABASE_URL=postgresql://involute:involute@127.0.0.1:5434/involute?schema=public
-AUTH_TOKEN=changeme-set-your-token # Change this for any non-local environment.
-VIEWER_ASSERTION_SECRET=compose-viewer-secret # Change this for any non-local environment.
+AUTH_TOKEN=changeme-set-your-token # Trusted CLI/dev bearer token. Not required for browser sessions.
+VIEWER_ASSERTION_SECRET=compose-viewer-secret # Trusted impersonation for CLI/dev only.
 ALLOW_ADMIN_FALLBACK=false # Set true only for local/dev bootstrap flows.
+APP_ORIGIN=http://localhost:4201
+GOOGLE_OAUTH_CLIENT_ID=
+GOOGLE_OAUTH_CLIENT_SECRET=
+GOOGLE_OAUTH_REDIRECT_URI=http://localhost:4200/auth/google/callback
+GOOGLE_OAUTH_ADMIN_EMAILS=
+SESSION_TTL_SECONDS=2592000
 PORT=4200

README.md

@@ -21,20 +21,34 @@ Create a repo-root `.env` file based on `.env.example`:
 DATABASE_URL=postgresql://involute:involute@127.0.0.1:5434/involute?schema=public
 AUTH_TOKEN=changeme-set-your-token
 VIEWER_ASSERTION_SECRET=compose-viewer-secret
+APP_ORIGIN=http://localhost:4201
+GOOGLE_OAUTH_CLIENT_ID=...
+GOOGLE_OAUTH_CLIENT_SECRET=...
+GOOGLE_OAUTH_REDIRECT_URI=http://localhost:4200/auth/google/callback
+GOOGLE_OAUTH_ADMIN_EMAILS=you@example.com
 PORT=4200
 ```
 
 Required server variables:
 
 - `DATABASE_URL` — PostgreSQL connection string
-- `AUTH_TOKEN` — bearer token expected by the API and CLI clients
-- `VIEWER_ASSERTION_SECRET` — HMAC secret used to verify signed viewer assertions for trusted impersonation
+- `APP_ORIGIN` — browser origin used for cookie/CORS handling and post-login redirects
 - `PORT` — API port (defaults to `4200`)
 
+Optional but recommended server variables:
+
+- `AUTH_TOKEN` — trusted bearer token used by the CLI and local/dev bootstrap flows
+- `VIEWER_ASSERTION_SECRET` — HMAC secret used to verify signed viewer assertions for trusted impersonation
+- `GOOGLE_OAUTH_CLIENT_ID` — Google OAuth client id for browser sign-in
+- `GOOGLE_OAUTH_CLIENT_SECRET` — Google OAuth client secret
+- `GOOGLE_OAUTH_REDIRECT_URI` — Google callback URL handled by the API server
+- `GOOGLE_OAUTH_ADMIN_EMAILS` — comma-separated allowlist of emails that should become `ADMIN`
+- `SESSION_TTL_SECONDS` — browser session lifetime in seconds
+
 Optional web runtime variables:
 
 - `VITE_INVOLUTE_GRAPHQL_URL` — override the web app GraphQL endpoint (default: `http://localhost:4200/graphql`)
-- `VITE_INVOLUTE_AUTH_TOKEN` — provide the web app bearer token at build/dev time
+- `VITE_INVOLUTE_AUTH_TOKEN` — trusted local/dev bearer token for bypassing browser login
 - `VITE_INVOLUTE_VIEWER_ASSERTION` — signed viewer assertion to act as a specific user without exposing the server secret
 
 ## Quick start
@@ -54,6 +68,8 @@ curl http://localhost:4201
 
 Then open `http://localhost:4201` in your browser.
 
+If Google OAuth is configured, the web nav will expose `Sign in with Google` and use session cookies. If it is not configured, the browser can still talk to the API with `VITE_INVOLUTE_AUTH_TOKEN` for trusted local development.
+
 Compose defaults:
 
 - API: `http://localhost:4200`
@@ -103,7 +119,7 @@ Recommended acceptance checks:
 Start the API:
 
 ```bash
-DATABASE_URL="postgresql://involute:involute@127.0.0.1:5434/involute?schema=public" AUTH_TOKEN="changeme-set-your-token" VIEWER_ASSERTION_SECRET="compose-viewer-secret" pnpm --filter @involute/server exec tsx src/index.ts
+DATABASE_URL="postgresql://involute:involute@127.0.0.1:5434/involute?schema=public" AUTH_TOKEN="changeme-set-your-token" VIEWER_ASSERTION_SECRET="compose-viewer-secret" APP_ORIGIN="http://127.0.0.1:4201" GOOGLE_OAUTH_REDIRECT_URI="http://127.0.0.1:4200/auth/google/callback" pnpm --filter @involute/server exec tsx src/index.ts
 ```
 
 Start the web app:
@@ -128,6 +144,15 @@ pnpm --filter @involute/cli exec node dist/index.js config set viewer-assertion
 
 The web UI can use the same signed assertion via `VITE_INVOLUTE_VIEWER_ASSERTION` or localStorage key `involute.viewerAssertion`.
 
+## Auth and permissions
+
+- Browser auth now supports Google OAuth plus session cookies.
+- `AUTH_TOKEN` and viewer assertions remain available for trusted CLI/dev flows.
+- Teams now have `PUBLIC` / `PRIVATE` visibility.
+- Team edits are gated by membership role: `EDITOR` or `OWNER`.
+- Team access management is currently exposed through GraphQL mutations: `teamUpdateAccess`, `teamMembershipUpsert`, and `teamMembershipRemove`.
+- A dedicated team-admin UI is still pending; this is the backend and runtime foundation.
+
 ## Quality gates
 
 Unit and integration checks:
@@ -177,8 +202,9 @@ pnpm --filter @involute/cli exec node dist/index.js import team --token "$LINEAR
 
 ## Current focus
 
-- Make single-team import a repeatable acceptance loop
-- Keep the compose stack and CI reproducible
-- Lock the core board lifecycle down with E2E before the larger UI/UX redesign
+- Make the current stack deployable on VPS and Railway
+- Replace the shared-token-only model with Google OAuth plus sessions
+- Add team visibility and edit permissions without regressing the single-team import loop
+- Keep the compose stack and CI reproducible while the product boundary hardens
 
 See [docs/vision.md](docs/vision.md) and [docs/milestones.md](docs/milestones.md) for the product direction.

docker-compose.yml

@@ -26,12 +26,18 @@ services:
       - /bin/sh
       - -lc
     command: >
-      pnpm --filter @involute/server exec prisma db push --skip-generate &&
+      if [ "${PRISMA_ALLOW_DATA_LOSS:-false}" = "true" ]; then
+        pnpm --filter @involute/server exec prisma db push --accept-data-loss --skip-generate;
+      else
+        pnpm --filter @involute/server exec prisma db push --skip-generate ||
+        pnpm --filter @involute/server exec prisma migrate deploy;
+      fi &&
       if [ "${SEED_DATABASE:-true}" = "true" ]; then
         pnpm --filter @involute/server exec prisma db seed;
       fi
     environment:
       DATABASE_URL: postgresql://involute:involute@db:5432/involute?schema=public
+      PRISMA_ALLOW_DATA_LOSS: ${PRISMA_ALLOW_DATA_LOSS:-false}
       SEED_DATABASE: ${SEED_DATABASE:-true}
     restart: "no"
 

docs/milestones.md

@@ -2,7 +2,7 @@
 
 ## M0: Single-team migration acceptance
 
-Status: in progress, core path now implemented.
+Status: done.
 
 Done:
 
@@ -18,9 +18,44 @@ Exit criteria:
 - `pnpm e2e` is green locally and in CI
 - `docker compose up --build -d db server web` is a stable demo path
 
-## M1: UI/UX redesign
+## M1: Deployable self-hosting
 
-Status: queued behind stability.
+Status: next.
+
+Scope:
+
+- ship a production deployment path for VPS and Railway
+- define `.env.production` expectations and runtime secrets
+- add reverse proxy / TLS guidance and database backup guidance
+- keep Docker images and compose-based demo/runtime aligned
+
+Exit criteria:
+
+- a fresh host can run Involute with Postgres, API, and web using documented steps
+- deployment docs are specific enough to reproduce without reading the source
+- image publishing and runtime config are consistent with the supported hosting path
+
+## M2: Auth and team permissions
+
+Status: next, after deployment is pinned down.
+
+Scope:
+
+- move away from the current shared-token simplification
+- add a real session-backed viewer model
+- start with Google OAuth rather than magic-link email
+- add `admin`, `team visibility`, and `team membership` edit boundaries
+
+Exit criteria:
+
+- an admin can sign in and manage access without touching raw headers
+- public teams are readable but not writable by non-members
+- private teams are only visible to members and admins
+- team members can be granted viewer/editor-style access explicitly
+
+## M3: UI/UX redesign
+
+Status: later, after M1 and M2.
 
 Scope:
 
@@ -31,9 +66,9 @@ Scope:
 Exit criteria:
 
 - visual direction is intentional and no longer feels placeholder-like
-- redesign does not regress the M0 lifecycle and import flow
+- redesign does not regress the M0 lifecycle, deployment path, or team permission model
 
-## M2: Multi-team workspace import
+## M4: Multi-team workspace import
 
 Status: later.
 
@@ -47,13 +82,3 @@ Exit criteria:
 
 - multiple Linear teams can be brought in predictably
 - repeated imports have explicit behavior and reporting
-
-## M3: Auth and multi-user hardening
-
-Status: later.
-
-Scope:
-
-- move away from the current shared-token simplification
-- define a real viewer identity model
-- add clearer trust boundaries for API and UI clients

docs/review/triage.md

@@ -16,14 +16,21 @@
   - `G9`：[`e2e/board-flow.spec.ts`](e2e/board-flow.spec.ts) 已补“导入后看板展示正确”的 Playwright 验收；fixture 脚本在 [`packages/server/scripts/import-board-fixture.ts`](packages/server/scripts/import-board-fixture.ts)。
   - `G10`：[`packages/web/src/routes/BoardPage.tsx`](packages/web/src/routes/BoardPage.tsx) 继续拆出 [`BoardCreateIssueDialog.tsx`](packages/web/src/components/BoardCreateIssueDialog.tsx) 和 [`BoardLoadMoreNotice.tsx`](packages/web/src/components/BoardLoadMoreNotice.tsx)，已不再属于当前 bug 清单。
 
+## 当前状态说明
+
+- 本文后续的 `G1-G12` 详细条目和逐条矩阵，保留的是 2026-04-04 做 triage 时的历史证据快照。
+- 它们的价值在于说明“这些问题最初是怎么被发现和归并的”，不是当前 `main` 的开放缺陷列表。
+- 判断当前状态时，应以上面的 `2026-04-05 收尾结论` 为准。
+- 当前主线下一阶段工作已从 review 修 bug 转向部署、身份体系、权限边界和后续 UI/UX 迭代。
+
 ## 判定口径
 
 - `成立`：当前主线代码中仍然存在，且原 review 的问题表述基本准确。
 - `部分成立`：问题方向是对的，但严重性、触发条件或细节表述不准确，或只剩下部分子问题。
 - `已修复/已过期`：review 当时可能成立，但当前主线代码已不再成立。
 - `当前非缺陷/延期`：这是产品缺口、范围取舍或后续里程碑工作，不计入当前缺陷清单。
 
-## Canonical 问题清单（已去重，按重要性排序）
+## Canonical 问题清单（历史快照，非当前开放问题）
 
 ### G1 [P0] 看板列仍然硬编码 6 个 workflow state，非标准状态的 issue 会在 Board 中“消失”
 

docs/vision.md

@@ -21,14 +21,15 @@ If this path is stable, the product is already useful for migration rehearsal, a
 
 ## What we are optimizing for now
 
-- Reliable single-team import and verification
-- Reproducible local stack through Docker Compose
-- Stable issue lifecycle in the UI: create, edit, comment, delete
-- Automated end-to-end acceptance coverage before a larger UI/UX rewrite
+- Stable self-hosted deployment on VPS or Railway
+- Simple multi-user access with Google OAuth and session auth
+- Team-level visibility and edit permissions
+- Keep the single-team import and issue lifecycle green while the product boundary hardens
 
 ## Explicitly not optimizing for yet
 
 - Multi-team workspace import
 - Large-scale performance work
 - Final visual design language
 - Enterprise auth and permission boundaries
+- Magic-link email auth and provider sprawl

e2e/board-flow.spec.ts

@@ -11,7 +11,7 @@ test.describe('board flow', () => {
     page.on('dialog', (dialog) => dialog.accept());
 
     await page.goto('/');
-    await expect(page.getByRole('heading', { name: 'Board' })).toBeVisible();
+    await expect(page.getByRole('heading', { name: 'Board', exact: true })).toBeVisible();
     await expect(page.getByText('Workflow overview for Involute.')).toBeVisible();
 
     await page.getByRole('button', { name: 'Create issue' }).click();
@@ -65,7 +65,7 @@ test.describe('board flow', () => {
       runBoardFixtureCommand('seed');
 
       await page.goto('/');
-      await expect(page.getByRole('heading', { name: 'Board' })).toBeVisible();
+      await expect(page.getByRole('heading', { name: 'Board', exact: true })).toBeVisible();
 
       await page.getByLabel('Select team').selectOption({ label: 'Imported Acceptance Team' });
 

e2e/setup-backend.sh

@@ -8,6 +8,8 @@ DATABASE_URL="${E2E_DATABASE_URL:-postgresql://involute:involute@127.0.0.1:${DB_
 AUTH_TOKEN="${E2E_AUTH_TOKEN:-e2e-auth-token}"
 VIEWER_ASSERTION_SECRET="${E2E_VIEWER_ASSERTION_SECRET:-e2e-viewer-assertion-secret}"
 SERVER_PORT="${E2E_SERVER_PORT:-4300}"
+WEB_PORT="${E2E_WEB_PORT:-4301}"
+APP_ORIGIN="${E2E_APP_ORIGIN:-http://127.0.0.1:${WEB_PORT}}"
 
 export COMPOSE_PROJECT_NAME
 export DB_PORT
@@ -35,6 +37,7 @@ DATABASE_URL="$DATABASE_URL" pnpm --filter @involute/server exec prisma db push
 DATABASE_URL="$DATABASE_URL" pnpm --filter @involute/server exec prisma db seed
 
 exec env \
+  APP_ORIGIN="$APP_ORIGIN" \
   DATABASE_URL="$DATABASE_URL" \
   AUTH_TOKEN="$AUTH_TOKEN" \
   ALLOW_ADMIN_FALLBACK="false" \

packages/server/package.json

@@ -20,7 +20,7 @@
     "typecheck": "pnpm --filter @involute/shared build && pnpm exec prisma generate && pnpm exec tsc -p tsconfig.json --noEmit && pnpm exec tsc -p tsconfig.prisma.json",
     "setup:web-ui-validation": "pnpm exec tsx src/validation-data-setup.ts",
     "setup:son-validation": "pnpm exec tsx src/son-validation-restore.ts",
-    "test": "pnpm --filter @involute/shared build && pnpm exec prisma generate && pnpm exec prisma db push --skip-generate && node scripts/run-vitest.mjs",
+    "test": "pnpm --filter @involute/shared build && pnpm exec prisma generate && sh -c 'if [ \"${PRISMA_ALLOW_DATA_LOSS:-false}\" = \"true\" ]; then pnpm exec prisma db push --accept-data-loss --skip-generate; else pnpm exec prisma db push --skip-generate || pnpm exec prisma migrate deploy; fi' && node scripts/run-vitest.mjs",
     "lint": "pnpm --filter @involute/shared build && pnpm exec prisma generate && pnpm exec tsc -p tsconfig.json --noEmit && pnpm exec tsc -p tsconfig.prisma.json"
   },
   "prisma": {

packages/server/prisma/schema.prisma

@@ -7,13 +7,31 @@ datasource db {
   url      = env("DATABASE_URL")
 }
 
+enum GlobalRole {
+  ADMIN
+  USER
+}
+
+enum TeamVisibility {
+  PRIVATE
+  PUBLIC
+}
+
+enum TeamMembershipRole {
+  VIEWER
+  EDITOR
+  OWNER
+}
+
 model Team {
   id              String          @id @default(uuid()) @db.Uuid
   key             String          @unique
   name            String
+  visibility      TeamVisibility  @default(PRIVATE)
   nextIssueNumber Int             @default(1)
   states          WorkflowState[]
   issues          Issue[]
+  memberships     TeamMembership[]
 
   @@index([key])
 }
@@ -41,8 +59,39 @@ model User {
   id             String    @id @default(uuid()) @db.Uuid
   name           String
   email          String    @unique
+  avatarUrl      String?
+  googleSubject  String?   @unique
+  globalRole     GlobalRole @default(USER)
   assignedIssues Issue[]   @relation("IssueAssignee")
   comments       Comment[]
+  memberships    TeamMembership[]
+  sessions       Session[]
+}
+
+model Session {
+  id        String   @id @default(uuid()) @db.Uuid
+  tokenHash String   @unique
+  createdAt DateTime @default(now())
+  expiresAt DateTime
+  userId    String   @db.Uuid
+  user      User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  @@index([userId])
+  @@index([expiresAt])
+}
+
+model TeamMembership {
+  id        String             @id @default(uuid()) @db.Uuid
+  teamId    String             @db.Uuid
+  userId    String             @db.Uuid
+  role      TeamMembershipRole
+  createdAt DateTime           @default(now())
+  team      Team               @relation(fields: [teamId], references: [id], onDelete: Cascade)
+  user      User               @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  @@unique([teamId, userId])
+  @@index([teamId])
+  @@index([userId])
 }
 
 model Issue {