Skip to content

Database governance built for humans and agents — controlling changes and access across every major database.

refactor(oauth2): use email for user lookup in authorize flow (#18453)

Danny Xue1fc191994bf
diff --git a/backend/api/oauth2/authorize.go b/backend/api/oauth2/authorize.go
index 0368f49edd..242045997b 100644
--- a/backend/api/oauth2/authorize.go
+++ b/backend/api/oauth2/authorize.go
@@ -4,7 +4,6 @@ import (
"fmt"
"net/http"
"net/url"
- "strconv"
"time"
"github.com/golang-jwt/jwt/v5"
@@ -129,13 +128,8 @@ func (s *Service) handleAuthorizePost(c echo.Context) error {
return oauth2ErrorRedirect(c, redirectURI, state, "access_denied", "invalid token audience")
}
- // Get user from claims
- principalID, err := strconv.Atoi(claims.Subject)
- if err != nil {
- return oauth2ErrorRedirect(c, redirectURI, state, "access_denied", "invalid user ID")
- }
-
- user, err := s.store.GetUserByID(ctx, principalID)
+ // Get user from claims (subject is email)
+ user, err := s.store.GetUserByEmail(ctx, claims.Subject)
if err != nil || user == nil {
return oauth2ErrorRedirect(c, redirectURI, state, "access_denied", "user not found")
}
diff --git a/docs/plans/2025-12-11-oauth2-server-design.md b/docs/plans/2025-12-11-oauth2-server-design.md
deleted file mode 100644
index 6b3e959e3b..0000000000
--- a/docs/plans/2025-12-11-oauth2-server-design.md
+++ /dev/null
@@ -1,313 +0,0 @@
-# OAuth2 Server Design for Bytebase
-
-## Overview
-
-Add an OAuth2 Authorization Server to Bytebase enabling third-party applications (starting with MCP servers) to authenticate users and access Bytebase APIs on their behalf.
-
-**Key decisions:**
-
-- Authorization Code + PKCE flow (OAuth 2.1 compliant)
-- Dynamic Client Registration for automated onboarding
-- Tokens inherit full user permissions (no scope filtering)
-- JWT access tokens with existing revocation cache
-- Standard HTTP endpoints (`/oauth2/*`)
-- All state persisted in database
-- Clients expire after 30 days of inactivity
-
-## Architecture
-
-```
-┌─────────────────┐ ┌──────────────────────────────────────────┐
-│ Third-Party │ │ Bytebase │
-│ App (MCP) │ │ │
-│ │ │ ┌─────────────────────────────────────┐ │
-│ 1. Register ───────────▶│ POST /oauth2/register │ │
-│ client │ │ │ (Dynamic Client Registration) │ │
-│ │ │ └─────────────────────────────────────┘ │
-│ │ │ │
-│ 2. Redirect ───────────▶│ GET /oauth2/authorize │ │
-│ user │ │ │ (Shows consent, redirects back) │ │
-│ │ │ └─────────────────────────────────────┘ │
-│ │ │ │
-│ 3. Exchange ───────────▶│ POST /oauth2/token │ │
-│ code │ │ │ (Returns JWT access + refresh) │ │
-│ │ │ └─────────────────────────────────────┘ │
-│ │ │ │
-│ 4. Call API ───────────▶│ Existing gRPC/REST APIs │ │
-│ Bearer token│ │ │ (Auth interceptor validates JWT) │ │
-└─────────────────┘ └──────────────────────────────────────────┘
-```
-
-## Endpoints
-
-| Endpoint | Method | Purpose |
-|----------|--------|---------|
-| `/.well-known/oauth-authorization-server` | GET | Server metadata discovery (RFC 8414) |
-| `/oauth2/register` | POST | Dynamic Client Registration (RFC 7591) |
-| `/oauth2/authorize` | GET | Authorization endpoint - shows consent UI |
-| `/oauth2/authorize` | POST | User grants/denies consent |
-| `/oauth2/token` | POST | Token endpoint - code exchange, refresh |
-| `/oauth2/revoke` | POST | Token revocation (RFC 7009) |
-
-**Discovery metadata** (`/.well-known/oauth-authorization-server`):
-
-```json
-{
- "issuer": "https://bytebase.example.com",
- "authorization_endpoint": "https://bytebase.example.com/oauth2/authorize",
- "token_endpoint": "https://bytebase.example.com/oauth2/token",
- "registration_endpoint": "https://bytebase.example.com/oauth2/register",
- "revocation_endpoint": "https://bytebase.example.com/oauth2/revoke",
- "response_types_supported": ["code"],
- "grant_types_supported": ["authorization_code", "refresh_token"],
- "code_challenge_methods_supported": ["S256"],
- "token_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post"]
-}
-```
-
-**Not included initially** (can add later):
-
-- `/oauth2/introspect` - Token introspection for external resource servers
-- `/oauth2/userinfo` - OIDC userinfo endpoint
-- `/oauth2/jwks` - Public keys (if switching to asymmetric signing)
-
-## Authorization Flow (Authorization Code + PKCE)
-
-**1. Client Registration** (one-time)
-
-```
-POST /oauth2/register
-Content-Type: application/json
-
-{
- "client_name": "My MCP Server",
- "redirect_uris": ["http://localhost:3000/callback"],
- "grant_types": ["authorization_code", "refresh_token"],
- "token_endpoint_auth_method": "client_secret_basic"
-}
-
-Response:
-{
- "client_id": "bb_oauth_xxxxxxxx",
- "client_secret": "bb_secret_xxxxxxxx",
- "client_name": "My MCP Server",
- "redirect_uris": ["http://localhost:3000/callback"],
- ...
-}
-```
-
-**2. Authorization Request**
-
-```
-GET /oauth2/authorize?
- response_type=code&
- client_id=bb_oauth_xxxxxxxx&
- redirect_uri=http://localhost:3000/callback&
- state=random_state&
- code_challenge=BASE64URL(SHA256(verifier))&
- code_challenge_method=S256
-```
-
-User sees consent screen, logs in if needed, approves.
-
-**3. Authorization Response**
-
-```
-HTTP/1.1 302 Found
-Location: http://localhost:3000/callback?code=AUTH_CODE&state=random_state
-```
-
-**4. Token Exchange**
-
-```
-POST /oauth2/token
-Content-Type: application/x-www-form-urlencoded
-Authorization: Basic base64(client_id:client_secret)
-
-grant_type=authorization_code&
-code=AUTH_CODE&
-redirect_uri=http://localhost:3000/callback&
-code_verifier=ORIGINAL_VERIFIER
-```
-
-**5. Token Response**
-
-```json
-{
- "access_token": "eyJhbG...",
- "token_type": "Bearer",
- "expires_in": 3600,
- "refresh_token": "bb_refresh_xxxxxxxx"
-}
-```
-
-## Token Design
-
-**Access Token (JWT)**
-
-Same structure as existing Bytebase access tokens for consistency:
-
-```json
-{
- "iss": "bytebase",
- "sub": "users/[email protected]",
- "aud": "bb.oauth2.access",
- "exp": 1702300800,
- "iat": 1702297200,
- "jti": "unique-token-id",
- "client_id": "bb_oauth_xxxxxxxx"
-}
-```
-
-Key points:
-
-- Signed with HS256 using existing signing key
-- `aud` distinguishes OAuth2 tokens from regular session tokens (`bb.user.access` vs `bb.oauth2.access`)
-- `client_id` claim identifies which OAuth2 client issued the request
-- `jti` enables revocation tracking in existing LRU cache
-- Default expiry: 1 hour
-
-**Refresh Token**
-
-Opaque token stored in database:
-
-- Format: `bb_refresh_xxxxxxxx` (random, not JWT)
-- Linked to user and client
-- Longer expiry: 30 days
-- Single-use: rotated on each refresh
-
-**Validation**
-
-The existing auth interceptor in `backend/api/auth/auth.go` will be extended to:
-
-1. Accept `bb.oauth2.access` audience
-2. Look up user from `sub` claim (same as today)
-3. Check revocation cache using `jti`
-4. User's full permissions apply (no scope filtering)
-
-## Database Schema
-
-**`oauth2_client`**
-
-```sql
-CREATE TABLE oauth2_client (
- client_id TEXT PRIMARY KEY,
- client_secret_hash TEXT NOT NULL,
- config JSONB NOT NULL,
- last_active_at TIMESTAMPTZ NOT NULL DEFAULT now()
-);
-```
-
-**`oauth2_authorization_code`**
-
-```sql
-CREATE TABLE oauth2_authorization_code (
- code TEXT PRIMARY KEY,
- client_id TEXT NOT NULL REFERENCES oauth2_client(client_id) ON DELETE CASCADE,
- user_id INTEGER NOT NULL REFERENCES principal(id),
- config JSONB NOT NULL,
- expires_at TIMESTAMPTZ NOT NULL
-);
-```
-
-**`oauth2_refresh_token`**
-
-```sql
-CREATE TABLE oauth2_refresh_token (
- token_hash TEXT PRIMARY KEY,
- client_id TEXT NOT NULL REFERENCES oauth2_client(client_id) ON DELETE CASCADE,
- user_id INTEGER NOT NULL REFERENCES principal(id),
- expires_at TIMESTAMPTZ NOT NULL
-);
-```
-
-**Proto definitions:**
-
-```protobuf
-message OAuth2ClientConfig {
- string client_name = 1;
- repeated string redirect_uris = 2;
- repeated string grant_types = 3;
- string token_endpoint_auth_method = 4;
-}
-
-message OAuth2AuthorizationCodeConfig {
- string redirect_uri = 1;
- string code_challenge = 2;
- string code_challenge_method = 3;
-}
-```
-
-**Cleanup:**
-
-- Background job deletes clients where `last_active_at < now() - 30 days`
-- `last_active_at` updated when authorization code is created or token is issued/refreshed
-- Expired authorization codes and refresh tokens cleaned up based on `expires_at`
-
-## Backend Structure
-
-```
-backend/
-├── api/
-│ └── oauth2/
-│ ├── oauth2.go # HTTP handlers for /oauth2/* endpoints
-│ ├── discovery.go # /.well-known/oauth-authorization-server
-│ ├── register.go # POST /oauth2/register (DCR)
-│ ├── authorize.go # GET/POST /oauth2/authorize
-│ ├── token.go # POST /oauth2/token
-│ └── revoke.go # POST /oauth2/revoke
-├── store/
-│ ├── oauth2_client.go # CRUD for oauth2_client
-│ ├── oauth2_authorization_code.go
-│ └── oauth2_refresh_token.go
-└── proto/
- └── store/
- └── oauth2.proto # OAuth2ClientConfig, OAuth2AuthorizationCodeConfig
-```
-
-**Registration in server:**
-
-- Mount OAuth2 handlers on the HTTP mux alongside existing routes
-- Handlers use existing `store.Store` for database access
-- Reuse existing auth interceptor logic for validating user sessions during `/oauth2/authorize`
-
-## Security Considerations
-
-**PKCE (required)**
-
-- `code_challenge_method` must be `S256` (reject `plain`)
-- Validate `code_verifier` matches `code_challenge` during token exchange
-
-**Client secrets**
-
-- Store bcrypt hash, never plaintext
-- Generate with sufficient entropy (32+ bytes, base64 encoded)
-
-**Redirect URI validation**
-
-- Exact match against registered URIs (no wildcards)
-- Must use HTTPS in production (allow `http://localhost` for development)
-
-**Token security**
-
-- Authorization codes: single-use, 10-minute expiry
-- Refresh tokens: single-use (rotate on refresh), 30-day expiry
-- Access tokens: 1-hour expiry
-
-**Rate limiting**
-
-- Apply existing rate limiting to `/oauth2/token` endpoint
-- Prevent brute-force on authorization codes
-
-**CSRF protection**
-
-- `state` parameter required on authorization requests
-- Validate `state` matches on callback
-
-## Future Enhancements
-
-- Admin UI for managing OAuth2 clients
-- Token introspection endpoint for external resource servers
-- OIDC userinfo endpoint
-- Asymmetric signing (RS256) with JWKS endpoint
-- Scope-based permission filtering
diff --git a/docs/plans/2025-12-11-oauth2-server-impl.md b/docs/plans/2025-12-11-oauth2-server-impl.md
deleted file mode 100644
index 2fcf70b116..0000000000
--- a/docs/plans/2025-12-11-oauth2-server-impl.md
+++ /dev/null
@@ -1,1712 +0,0 @@
-# OAuth2 Server Implementation Plan
-
-> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
-
-**Goal:** Add OAuth2 Authorization Server to Bytebase enabling third-party apps (MCP servers) to authenticate users via Authorization Code + PKCE flow.
-
-**Architecture:** Standard HTTP endpoints at `/oauth2/*` using Echo framework. JWT access tokens reusing existing auth infrastructure. All state in PostgreSQL with proto-defined JSONB configs.
-
-**Tech Stack:** Go, Echo framework, PostgreSQL, protobuf/protojson, bcrypt, crypto/rand
-
-**Design Doc:** `docs/plans/2025-12-11-oauth2-server-design.md`
-
----
-
-## Task 1: Proto Definitions
-
-**Files:**
-- Create: `proto/store/oauth2.proto`
-
-**Step 1: Create proto file**
-
-```protobuf
-syntax = "proto3";
-
-package bytebase.store;
-
-option go_package = "generated-go/store";
-
-message OAuth2ClientConfig {
- string client_name = 1;
- repeated string redirect_uris = 2;
- repeated string grant_types = 3;
- string token_endpoint_auth_method = 4;
-}
-
-message OAuth2AuthorizationCodeConfig {
- string redirect_uri = 1;
- string code_challenge = 2;
- string code_challenge_method = 3;
-}
-```
-
-**Step 2: Generate Go code**
-
-Run: `cd proto && buf generate`
-
-**Step 3: Verify generation**
-
-Run: `ls backend/generated-go/store/oauth2.pb.go`
-Expected: File exists
-
-**Step 4: Commit**
-
-```bash
-but commit <branch> -m "proto: add OAuth2 store proto definitions"
-```
-
----
-
-## Task 2: Database Migration
-
-**Files:**
-- Create: `backend/migrator/migration/3.13/0020##add_oauth2_tables.sql`
-- Modify: `backend/migrator/migration/LATEST.sql`
-- Modify: `backend/migrator/migrator_test.go:15`
-
-**Step 1: Create migration file**
-
-```sql
-CREATE TABLE oauth2_client (
- client_id TEXT PRIMARY KEY,
- client_secret_hash TEXT NOT NULL,
- config JSONB NOT NULL,
- last_active_at TIMESTAMPTZ NOT NULL DEFAULT now()
-);
-
-CREATE TABLE oauth2_authorization_code (
- code TEXT PRIMARY KEY,
- client_id TEXT NOT NULL REFERENCES oauth2_client(client_id) ON DELETE CASCADE,
- user_id INTEGER NOT NULL REFERENCES principal(id),
- config JSONB NOT NULL,
- expires_at TIMESTAMPTZ NOT NULL
-);
-
-CREATE TABLE oauth2_refresh_token (
- token_hash TEXT PRIMARY KEY,
- client_id TEXT NOT NULL REFERENCES oauth2_client(client_id) ON DELETE CASCADE,
- user_id INTEGER NOT NULL REFERENCES principal(id),
- expires_at TIMESTAMPTZ NOT NULL
-);
-
-CREATE INDEX idx_oauth2_authorization_code_expires_at ON oauth2_authorization_code(expires_at);
-CREATE INDEX idx_oauth2_refresh_token_expires_at ON oauth2_refresh_token(expires_at);
-CREATE INDEX idx_oauth2_client_last_active_at ON oauth2_client(last_active_at);
-```
-
-**Step 2: Update LATEST.sql**
-
-Add the same table definitions to `backend/migrator/migration/LATEST.sql` after the existing table definitions.
-
-**Step 3: Update migrator_test.go**
-
-Change line 15 from:
-```go
-require.Equal(t, semver.MustParse("3.13.19"), *files[len(files)-1].version)
-```
-to:
-```go
-require.Equal(t, semver.MustParse("3.13.20"), *files[len(files)-1].version)
-```
-
-**Step 4: Run migration tests**
-
-Run: `go test -v -count=1 github.com/bytebase/bytebase/backend/migrator -run ^TestLatestVersion$`
-Expected: PASS
-
-Run: `go test -v -count=1 github.com/bytebase/bytebase/backend/migrator -run ^TestVersionUnique$`
-Expected: PASS
-
-**Step 5: Commit**
-
-```bash
-but commit <branch> -m "migration: add OAuth2 tables"
-```
-
----
-
-## Task 3: Store Layer - OAuth2 Client
-
-**Files:**
-- Create: `backend/store/oauth2_client.go`
-
-**Step 1: Create store file**
-
-```go
-package store
-
-import (
- "context"
- "time"
-
- "github.com/pkg/errors"
- "google.golang.org/protobuf/encoding/protojson"
-
- "github.com/bytebase/bytebase/backend/common"
- "github.com/bytebase/bytebase/backend/common/qb"
- storepb "github.com/bytebase/bytebase/proto/generated-go/store"
-)
-
-type OAuth2ClientMessage struct {
- ClientID string
- ClientSecretHash string
- Config *storepb.OAuth2ClientConfig
- LastActiveAt time.Time
-}
-
-type FindOAuth2ClientMessage struct {
- ClientID *string
-}
-
-func (s *Store) CreateOAuth2Client(ctx context.Context, create *OAuth2ClientMessage) (*OAuth2ClientMessage, error) {
- configBytes, err := protojson.Marshal(create.Config)
- if err != nil {
- return nil, errors.Wrap(err, "failed to marshal config")
- }
-
- q := qb.Q().Space(`
- INSERT INTO oauth2_client (client_id, client_secret_hash, config, last_active_at)
- VALUES (?, ?, ?, NOW())
- RETURNING last_active_at
- `, create.ClientID, create.ClientSecretHash, configBytes)
-
- query, args, err := q.ToSQL()
- if err != nil {
- return nil, err
- }
-
- if err := s.GetDB().QueryRowContext(ctx, query, args...).Scan(&create.LastActiveAt); err != nil {
- return nil, errors.Wrap(err, "failed to create OAuth2 client")
- }
- return create, nil
-}
-
-func (s *Store) GetOAuth2Client(ctx context.Context, clientID string) (*OAuth2ClientMessage, error) {
- clients, err := s.ListOAuth2Clients(ctx, &FindOAuth2ClientMessage{ClientID: &clientID})
- if err != nil {
- return nil, err
- }
- if len(clients) == 0 {
- return nil, nil
- }
- return clients[0], nil
-}
-
-func (s *Store) ListOAuth2Clients(ctx context.Context, find *FindOAuth2ClientMessage) ([]*OAuth2ClientMessage, error) {
- q := qb.Q().Space(`
- SELECT client_id, client_secret_hash, config, last_active_at
- FROM oauth2_client
- WHERE TRUE
- `)
-
- if v := find.ClientID; v != nil {
- q.And("client_id = ?", *v)
- }
-
- query, args, err := q.ToSQL()
- if err != nil {
- return nil, err
- }
-
- rows, err := s.GetDB().QueryContext(ctx, query, args...)
- if err != nil {
- return nil, errors.Wrap(err, "failed to query OAuth2 clients")
- }
- defer rows.Close()
-
- var clients []*OAuth2ClientMessage
- for rows.Next() {
- client := &OAuth2ClientMessage{}
- var configBytes []byte
- if err := rows.Scan(&client.ClientID, &client.ClientSecretHash, &configBytes, &client.LastActiveAt); err != nil {
- return nil, errors.Wrap(err, "failed to scan OAuth2 client")
- }
- client.Config = &storepb.OAuth2ClientConfig{}
- if err := common.ProtojsonUnmarshaler.Unmarshal(configBytes, client.Config); err != nil {
- return nil, errors.Wrap(err, "failed to unmarshal config")
- }
- clients = append(clients, client)
- }
- if err := rows.Err(); err != nil {
- return nil, errors.Wrap(err, "failed to iterate OAuth2 clients")
- }
- return clients, nil
-}
-
-func (s *Store) UpdateOAuth2ClientLastActiveAt(ctx context.Context, clientID string) error {
- q := qb.Q().Space(`
- UPDATE oauth2_client
- SET last_active_at = NOW()
- WHERE client_id = ?
- `, clientID)
-
- query, args, err := q.ToSQL()
- if err != nil {
- return err
- }
-
- if _, err := s.GetDB().ExecContext(ctx, query, args...); err != nil {
- return errors.Wrap(err, "failed to update OAuth2 client last active at")
- }
- return nil
-}
-
-func (s *Store) DeleteOAuth2Client(ctx context.Context, clientID string) error {
- q := qb.Q().Space(`
- DELETE FROM oauth2_client
- WHERE client_id = ?
- `, clientID)
-
- query, args, err := q.ToSQL()
- if err != nil {
- return err
- }
-
- if _, err := s.GetDB().ExecContext(ctx, query, args...); err != nil {
- return errors.Wrap(err, "failed to delete OAuth2 client")
- }
- return nil
-}
-
-func (s *Store) DeleteExpiredOAuth2Clients(ctx context.Context, expireBefore time.Time) (int64, error) {
- q := qb.Q().Space(`
- DELETE FROM oauth2_client
- WHERE last_active_at < ?
- `, expireBefore)
-
- query, args, err := q.ToSQL()
- if err != nil {
- return 0, err
- }
-
- result, err := s.GetDB().ExecContext(ctx, query, args...)
- if err != nil {
- return 0, errors.Wrap(err, "failed to delete expired OAuth2 clients")
- }
- return result.RowsAffected()
-}
-```
-
-**Step 2: Lint**
-
-Run: `golangci-lint run --allow-parallel-runners ./backend/store/oauth2_client.go`
-Expected: No errors (or only unrelated warnings)
-
-**Step 3: Commit**
-
-```bash
-but commit <branch> -m "store: add OAuth2 client CRUD"
-```
-
----
-
-## Task 4: Store Layer - Authorization Code
-
-**Files:**
-- Create: `backend/store/oauth2_authorization_code.go`
-
-**Step 1: Create store file**
-
-```go
-package store
-
-import (
- "context"
- "time"
-
- "github.com/pkg/errors"
- "google.golang.org/protobuf/encoding/protojson"
-
- "github.com/bytebase/bytebase/backend/common"
- "github.com/bytebase/bytebase/backend/common/qb"
- storepb "github.com/bytebase/bytebase/proto/generated-go/store"
-)
-
-type OAuth2AuthorizationCodeMessage struct {
- Code string
- ClientID string
- UserID int
- Config *storepb.OAuth2AuthorizationCodeConfig
- ExpiresAt time.Time
-}
-
-func (s *Store) CreateOAuth2AuthorizationCode(ctx context.Context, create *OAuth2AuthorizationCodeMessage) (*OAuth2AuthorizationCodeMessage, error) {
- configBytes, err := protojson.Marshal(create.Config)
- if err != nil {
- return nil, errors.Wrap(err, "failed to marshal config")
- }
-
- q := qb.Q().Space(`
- INSERT INTO oauth2_authorization_code (code, client_id, user_id, config, expires_at)
- VALUES (?, ?, ?, ?, ?)
- `, create.Code, create.ClientID, create.UserID, configBytes, create.ExpiresAt)
-
- query, args, err := q.ToSQL()
- if err != nil {
- return nil, err
- }
-
- if _, err := s.GetDB().ExecContext(ctx, query, args...); err != nil {
- return nil, errors.Wrap(err, "failed to create OAuth2 authorization code")
- }
- return create, nil
-}
-
-func (s *Store) GetOAuth2AuthorizationCode(ctx context.Context, code string) (*OAuth2AuthorizationCodeMessage, error) {
- q := qb.Q().Space(`
- SELECT code, client_id, user_id, config, expires_at
- FROM oauth2_authorization_code
- WHERE code = ?
- `, code)
-
- query, args, err := q.ToSQL()
- if err != nil {
- return nil, err
- }
-
- msg := &OAuth2AuthorizationCodeMessage{}
- var configBytes []byte
- if err := s.GetDB().QueryRowContext(ctx, query, args...).Scan(
- &msg.Code, &msg.ClientID, &msg.UserID, &configBytes, &msg.ExpiresAt,
- ); err != nil {
- if err.Error() == "sql: no rows in result set" {
- return nil, nil
- }
- return nil, errors.Wrap(err, "failed to get OAuth2 authorization code")
- }
-
- msg.Config = &storepb.OAuth2AuthorizationCodeConfig{}
- if err := common.ProtojsonUnmarshaler.Unmarshal(configBytes, msg.Config); err != nil {
- return nil, errors.Wrap(err, "failed to unmarshal config")
- }
- return msg, nil
-}
-
-func (s *Store) DeleteOAuth2AuthorizationCode(ctx context.Context, code string) error {
- q := qb.Q().Space(`
- DELETE FROM oauth2_authorization_code
- WHERE code = ?
- `, code)
-
- query, args, err := q.ToSQL()
- if err != nil {
- return err
- }
-
- if _, err := s.GetDB().ExecContext(ctx, query, args...); err != nil {
- return errors.Wrap(err, "failed to delete OAuth2 authorization code")
- }
- return nil
-}
-
-func (s *Store) DeleteExpiredOAuth2AuthorizationCodes(ctx context.Context) (int64, error) {
- q := qb.Q().Space(`
- DELETE FROM oauth2_authorization_code
- WHERE expires_at < NOW()
- `)
-
- query, args, err := q.ToSQL()
- if err != nil {
- return 0, err
- }
-
- result, err := s.GetDB().ExecContext(ctx, query, args...)
- if err != nil {
- return 0, errors.Wrap(err, "failed to delete expired OAuth2 authorization codes")
- }
- return result.RowsAffected()
-}
-```
-
-**Step 2: Lint**
-
-Run: `golangci-lint run --allow-parallel-runners ./backend/store/oauth2_authorization_code.go`
-Expected: No errors
-
-**Step 3: Commit**
-
-```bash
-but commit <branch> -m "store: add OAuth2 authorization code CRUD"
-```
-
----
-
-## Task 5: Store Layer - Refresh Token
-
-**Files:**
-- Create: `backend/store/oauth2_refresh_token.go`
-
-**Step 1: Create store file**
-
-```go
-package store
-
-import (
- "context"
- "time"
-
- "github.com/pkg/errors"
-
- "github.com/bytebase/bytebase/backend/common/qb"
-)
-
-type OAuth2RefreshTokenMessage struct {
- TokenHash string
- ClientID string
- UserID int
- ExpiresAt time.Time
-}
-
-func (s *Store) CreateOAuth2RefreshToken(ctx context.Context, create *OAuth2RefreshTokenMessage) (*OAuth2RefreshTokenMessage, error) {
- q := qb.Q().Space(`
- INSERT INTO oauth2_refresh_token (token_hash, client_id, user_id, expires_at)
- VALUES (?, ?, ?, ?)
- `, create.TokenHash, create.ClientID, create.UserID, create.ExpiresAt)
-
- query, args, err := q.ToSQL()
- if err != nil {
- return nil, err
- }
-
- if _, err := s.GetDB().ExecContext(ctx, query, args...); err != nil {
- return nil, errors.Wrap(err, "failed to create OAuth2 refresh token")
- }
- return create, nil
-}
-
-func (s *Store) GetOAuth2RefreshToken(ctx context.Context, tokenHash string) (*OAuth2RefreshTokenMessage, error) {
- q := qb.Q().Space(`
- SELECT token_hash, client_id, user_id, expires_at
- FROM oauth2_refresh_token
- WHERE token_hash = ?
- `, tokenHash)
-
- query, args, err := q.ToSQL()
- if err != nil {
- return nil, err
- }
-
- msg := &OAuth2RefreshTokenMessage{}
- if err := s.GetDB().QueryRowContext(ctx, query, args...).Scan(
- &msg.TokenHash, &msg.ClientID, &msg.UserID, &msg.ExpiresAt,
- ); err != nil {
- if err.Error() == "sql: no rows in result set" {
- return nil, nil
- }
- return nil, errors.Wrap(err, "failed to get OAuth2 refresh token")
- }
- return msg, nil
-}
-
-func (s *Store) DeleteOAuth2RefreshToken(ctx context.Context, tokenHash string) error {
- q := qb.Q().Space(`
- DELETE FROM oauth2_refresh_token
- WHERE token_hash = ?
- `, tokenHash)
-
- query, args, err := q.ToSQL()
- if err != nil {
- return err
- }
-
- if _, err := s.GetDB().ExecContext(ctx, query, args...); err != nil {
- return errors.Wrap(err, "failed to delete OAuth2 refresh token")
- }
- return nil
-}
-
-func (s *Store) DeleteOAuth2RefreshTokensByUserAndClient(ctx context.Context, userID int, clientID string) error {
- q := qb.Q().Space(`
- DELETE FROM oauth2_refresh_token
- WHERE user_id = ? AND client_id = ?
- `, userID, clientID)
-
- query, args, err := q.ToSQL()
- if err != nil {
- return err
- }
-
- if _, err := s.GetDB().ExecContext(ctx, query, args...); err != nil {
- return errors.Wrap(err, "failed to delete OAuth2 refresh tokens")
- }
- return nil
-}
-
-func (s *Store) DeleteExpiredOAuth2RefreshTokens(ctx context.Context) (int64, error) {
- q := qb.Q().Space(`
- DELETE FROM oauth2_refresh_token
- WHERE expires_at < NOW()
- `)
-
- query, args, err := q.ToSQL()
- if err != nil {
- return 0, err
- }
-
- result, err := s.GetDB().ExecContext(ctx, query, args...)
- if err != nil {
- return 0, errors.Wrap(err, "failed to delete expired OAuth2 refresh tokens")
- }
- return result.RowsAffected()
-}
-```
-
-**Step 2: Lint**
-
-Run: `golangci-lint run --allow-parallel-runners ./backend/store/oauth2_refresh_token.go`
-Expected: No errors
-
-**Step 3: Commit**
-
-```bash
-but commit <branch> -m "store: add OAuth2 refresh token CRUD"
-```
-
----
-
-## Task 6: OAuth2 Handler - Utilities
-
-**Files:**
-- Create: `backend/api/oauth2/oauth2.go`
-
-**Step 1: Create main handler file with utilities**
-
-```go
-package oauth2
-
-import (
- "crypto/rand"
- "crypto/sha256"
- "encoding/base64"
- "fmt"
- "net/http"
- "net/url"
- "slices"
- "strings"
- "time"
-
- "github.com/labstack/echo/v4"
- "golang.org/x/crypto/bcrypt"
-
- "github.com/bytebase/bytebase/backend/store"
-)
-
-const (
- clientIDPrefix = "bb_oauth_"
- clientSecretPrefix = "bb_secret_"
- refreshTokenPrefix = "bb_refresh_"
- authCodePrefix = "bb_code_"
-
- authCodeExpiry = 10 * time.Minute
- accessTokenExpiry = 1 * time.Hour
- refreshTokenExpiry = 30 * 24 * time.Hour
- clientInactiveExpiry = 30 * 24 * time.Hour
-)
-
-type Service struct {
- store *store.Store
- secret string
- externalURL string
-}
-
-func NewService(store *store.Store, secret, externalURL string) *Service {
- return &Service{
- store: store,
- secret: secret,
- externalURL: strings.TrimSuffix(externalURL, "/"),
- }
-}
-
-func (s *Service) RegisterRoutes(g *echo.Group) {
- g.GET("/.well-known/oauth-authorization-server", s.handleDiscovery)
- g.POST("/oauth2/register", s.handleRegister)
- g.GET("/oauth2/authorize", s.handleAuthorizeGet)
- g.POST("/oauth2/authorize", s.handleAuthorizePost)
- g.POST("/oauth2/token", s.handleToken)
- g.POST("/oauth2/revoke", s.handleRevoke)
-}
-
-func generateRandomString(length int) (string, error) {
- bytes := make([]byte, length)
- if _, err := rand.Read(bytes); err != nil {
- return "", err
- }
- return base64.RawURLEncoding.EncodeToString(bytes), nil
-}
-
-func generateClientID() (string, error) {
- random, err := generateRandomString(24)
- if err != nil {
- return "", err
- }
- return clientIDPrefix + random, nil
-}
-
-func generateClientSecret() (string, error) {
- random, err := generateRandomString(32)
- if err != nil {
- return "", err
- }
- return clientSecretPrefix + random, nil
-}
-
-func generateAuthCode() (string, error) {
- random, err := generateRandomString(32)
- if err != nil {
- return "", err
- }
- return authCodePrefix + random, nil
-}
-
-func generateRefreshToken() (string, error) {
- random, err := generateRandomString(32)
- if err != nil {
- return "", err
- }
- return refreshTokenPrefix + random, nil
-}
-
-func hashSecret(secret string) (string, error) {
- hash, err := bcrypt.GenerateFromPassword([]byte(secret), bcrypt.DefaultCost)
- if err != nil {
- return "", err
- }
- return string(hash), nil
-}
-
-func verifySecret(hash, secret string) bool {
- return bcrypt.CompareHashAndPassword([]byte(hash), []byte(secret)) == nil
-}
-
-func hashToken(token string) string {
- hash := sha256.Sum256([]byte(token))
- return base64.RawURLEncoding.EncodeToString(hash[:])
-}
-
-func verifyPKCE(codeVerifier, codeChallenge, method string) bool {
- if method != "S256" {
- return false
- }
- hash := sha256.Sum256([]byte(codeVerifier))
- computed := base64.RawURLEncoding.EncodeToString(hash[:])
- return computed == codeChallenge
-}
-
-func validateRedirectURI(uri string, allowedURIs []string) bool {
- return slices.Contains(allowedURIs, uri)
-}
-
-func isLocalhostURI(uri string) bool {
- parsed, err := url.Parse(uri)
- if err != nil {
- return false
- }
- host := parsed.Hostname()
- return host == "localhost" || host == "127.0.0.1" || host == "::1"
-}
-
-func oauth2Error(c echo.Context, statusCode int, errorCode, description string) error {
- return c.JSON(statusCode, map[string]string{
- "error": errorCode,
- "error_description": description,
- })
-}
-
-func oauth2ErrorRedirect(c echo.Context, redirectURI, state, errorCode, description string) error {
- u, _ := url.Parse(redirectURI)
- q := u.Query()
- q.Set("error", errorCode)
- q.Set("error_description", description)
- if state != "" {
- q.Set("state", state)
- }
- u.RawQuery = q.Encode()
- return c.Redirect(http.StatusFound, u.String())
-}
-
-func (s *Service) issuer() string {
- return s.externalURL
-}
-
-func (s *Service) authorizationEndpoint() string {
- return fmt.Sprintf("%s/oauth2/authorize", s.externalURL)
-}
-
-func (s *Service) tokenEndpoint() string {
- return fmt.Sprintf("%s/oauth2/token", s.externalURL)
-}
-
-func (s *Service) registrationEndpoint() string {
- return fmt.Sprintf("%s/oauth2/register", s.externalURL)
-}
-
-func (s *Service) revocationEndpoint() string {
- return fmt.Sprintf("%s/oauth2/revoke", s.externalURL)
-}
-```
-
-**Step 2: Lint**
-
-Run: `golangci-lint run --allow-parallel-runners ./backend/api/oauth2/oauth2.go`
-Expected: No errors
-
-**Step 3: Commit**
-
-```bash
-but commit <branch> -m "api: add OAuth2 service with utilities"
-```
-
----
-
-## Task 7: OAuth2 Handler - Discovery
-
-**Files:**
-- Create: `backend/api/oauth2/discovery.go`
-
-**Step 1: Create discovery handler**
-
-```go
-package oauth2
-
-import (
- "net/http"
-
- "github.com/labstack/echo/v4"
-)
-
-type authorizationServerMetadata struct {
- Issuer string `json:"issuer"`
- AuthorizationEndpoint string `json:"authorization_endpoint"`
- TokenEndpoint string `json:"token_endpoint"`
- RegistrationEndpoint string `json:"registration_endpoint"`
- RevocationEndpoint string `json:"revocation_endpoint"`
- ResponseTypesSupported []string `json:"response_types_supported"`
- GrantTypesSupported []string `json:"grant_types_supported"`
- CodeChallengeMethodsSupported []string `json:"code_challenge_methods_supported"`
- TokenEndpointAuthMethodsSupported []string `json:"token_endpoint_auth_methods_supported"`
-}
-
-func (s *Service) handleDiscovery(c echo.Context) error {
- metadata := &authorizationServerMetadata{
- Issuer: s.issuer(),
- AuthorizationEndpoint: s.authorizationEndpoint(),
- TokenEndpoint: s.tokenEndpoint(),
- RegistrationEndpoint: s.registrationEndpoint(),
- RevocationEndpoint: s.revocationEndpoint(),
- ResponseTypesSupported: []string{"code"},
- GrantTypesSupported: []string{"authorization_code", "refresh_token"},
- CodeChallengeMethodsSupported: []string{"S256"},
- TokenEndpointAuthMethodsSupported: []string{"client_secret_basic", "client_secret_post"},
- }
- return c.JSON(http.StatusOK, metadata)
-}
-```
-
-**Step 2: Lint**
-
-Run: `golangci-lint run --allow-parallel-runners ./backend/api/oauth2/discovery.go`
-Expected: No errors
-
-**Step 3: Commit**
-
-```bash
-but commit <branch> -m "api: add OAuth2 discovery endpoint"
-```
-
----
-
-## Task 8: OAuth2 Handler - Dynamic Client Registration
-
-**Files:**
-- Create: `backend/api/oauth2/register.go`
-
-**Step 1: Create DCR handler**
-
-```go
-package oauth2
-
-import (
- "net/http"
- "net/url"
- "slices"
-
- "github.com/labstack/echo/v4"
-
- storepb "github.com/bytebase/bytebase/proto/generated-go/store"
-)
-
-type clientRegistrationRequest struct {
- ClientName string `json:"client_name"`
- RedirectURIs []string `json:"redirect_uris"`
- GrantTypes []string `json:"grant_types"`
- TokenEndpointAuthMethod string `json:"token_endpoint_auth_method"`
-}
-
-type clientRegistrationResponse struct {
- ClientID string `json:"client_id"`
- ClientSecret string `json:"client_secret"`
- ClientName string `json:"client_name"`
- RedirectURIs []string `json:"redirect_uris"`
- GrantTypes []string `json:"grant_types"`
- TokenEndpointAuthMethod string `json:"token_endpoint_auth_method"`
-}
-
-func (s *Service) handleRegister(c echo.Context) error {
- ctx := c.Request().Context()
-
- var req clientRegistrationRequest
- if err := c.Bind(&req); err != nil {
- return oauth2Error(c, http.StatusBadRequest, "invalid_client_metadata", "failed to parse request body")
- }
-
- // Validate client_name
- if req.ClientName == "" {
- return oauth2Error(c, http.StatusBadRequest, "invalid_client_metadata", "client_name is required")
- }
-
- // Validate redirect_uris
- if len(req.RedirectURIs) == 0 {
- return oauth2Error(c, http.StatusBadRequest, "invalid_client_metadata", "redirect_uris is required")
- }
- for _, uri := range req.RedirectURIs {
- parsed, err := url.Parse(uri)
- if err != nil {
- return oauth2Error(c, http.StatusBadRequest, "invalid_redirect_uri", "invalid redirect URI format")
- }
- // Require HTTPS except for localhost
- if parsed.Scheme != "https" && !isLocalhostURI(uri) {
- return oauth2Error(c, http.StatusBadRequest, "invalid_redirect_uri", "redirect URI must use HTTPS (except localhost)")
- }
- }
-
- // Validate grant_types (default to authorization_code)
- if len(req.GrantTypes) == 0 {
- req.GrantTypes = []string{"authorization_code"}
- }
- allowedGrantTypes := []string{"authorization_code", "refresh_token"}
- for _, gt := range req.GrantTypes {
- if !slices.Contains(allowedGrantTypes, gt) {
- return oauth2Error(c, http.StatusBadRequest, "invalid_client_metadata", "unsupported grant_type: "+gt)
- }
- }
-
- // Validate token_endpoint_auth_method (default to client_secret_basic)
- if req.TokenEndpointAuthMethod == "" {
- req.TokenEndpointAuthMethod = "client_secret_basic"
- }
- allowedAuthMethods := []string{"client_secret_basic", "client_secret_post"}
- if !slices.Contains(allowedAuthMethods, req.TokenEndpointAuthMethod) {
- return oauth2Error(c, http.StatusBadRequest, "invalid_client_metadata", "unsupported token_endpoint_auth_method")
- }
-
- // Generate credentials
- clientID, err := generateClientID()
- if err != nil {
- return oauth2Error(c, http.StatusInternalServerError, "server_error", "failed to generate client ID")
- }
- clientSecret, err := generateClientSecret()
- if err != nil {
- return oauth2Error(c, http.StatusInternalServerError, "server_error", "failed to generate client secret")
- }
- secretHash, err := hashSecret(clientSecret)
- if err != nil {
- return oauth2Error(c, http.StatusInternalServerError, "server_error", "failed to hash client secret")
- }
-
- // Store client
- config := &storepb.OAuth2ClientConfig{
- ClientName: req.ClientName,
- RedirectUris: req.RedirectURIs,
- GrantTypes: req.GrantTypes,
- TokenEndpointAuthMethod: req.TokenEndpointAuthMethod,
- }
- if _, err := s.store.CreateOAuth2Client(ctx, &store.OAuth2ClientMessage{
- ClientID: clientID,
- ClientSecretHash: secretHash,
- Config: config,
- }); err != nil {
- return oauth2Error(c, http.StatusInternalServerError, "server_error", "failed to create client")
- }
-
- return c.JSON(http.StatusCreated, &clientRegistrationResponse{
- ClientID: clientID,
- ClientSecret: clientSecret,
- ClientName: req.ClientName,
- RedirectURIs: req.RedirectURIs,
- GrantTypes: req.GrantTypes,
- TokenEndpointAuthMethod: req.TokenEndpointAuthMethod,
- })
-}
-```
-
-**Step 2: Add missing import**
-
-Add `"github.com/bytebase/bytebase/backend/store"` to imports.
-
-**Step 3: Lint**
-
-Run: `golangci-lint run --allow-parallel-runners ./backend/api/oauth2/register.go`
-Expected: No errors
-
-**Step 4: Commit**
-
-```bash
-but commit <branch> -m "api: add OAuth2 dynamic client registration"
-```
-
----
-
-## Task 9: OAuth2 Handler - Authorization Endpoint
-
-**Files:**
-- Create: `backend/api/oauth2/authorize.go`
-
-**Step 1: Create authorization handler**
-
-```go
-package oauth2
-
-import (
- "fmt"
- "net/http"
- "net/url"
- "slices"
- "time"
-
- "github.com/labstack/echo/v4"
-
- "github.com/bytebase/bytebase/backend/api/auth"
- "github.com/bytebase/bytebase/backend/store"
- storepb "github.com/bytebase/bytebase/proto/generated-go/store"
-)
-
-func (s *Service) handleAuthorizeGet(c echo.Context) error {
- ctx := c.Request().Context()
-
- // Parse query parameters
- responseType := c.QueryParam("response_type")
- clientID := c.QueryParam("client_id")
- redirectURI := c.QueryParam("redirect_uri")
- state := c.QueryParam("state")
- codeChallenge := c.QueryParam("code_challenge")
- codeChallengeMethod := c.QueryParam("code_challenge_method")
-
- // Validate response_type
- if responseType != "code" {
- return oauth2Error(c, http.StatusBadRequest, "unsupported_response_type", "only 'code' response type is supported")
- }
-
- // Validate client_id
- if clientID == "" {
- return oauth2Error(c, http.StatusBadRequest, "invalid_request", "client_id is required")
- }
- client, err := s.store.GetOAuth2Client(ctx, clientID)
- if err != nil {
- return oauth2Error(c, http.StatusInternalServerError, "server_error", "failed to lookup client")
- }
- if client == nil {
- return oauth2Error(c, http.StatusBadRequest, "invalid_client", "client not found")
- }
-
- // Validate redirect_uri
- if redirectURI == "" {
- return oauth2Error(c, http.StatusBadRequest, "invalid_request", "redirect_uri is required")
- }
- if !validateRedirectURI(redirectURI, client.Config.RedirectUris) {
- return oauth2Error(c, http.StatusBadRequest, "invalid_redirect_uri", "redirect_uri not registered")
- }
-
- // Validate PKCE (required)
- if codeChallenge == "" {
- return oauth2ErrorRedirect(c, redirectURI, state, "invalid_request", "code_challenge is required")
- }
- if codeChallengeMethod != "S256" {
- return oauth2ErrorRedirect(c, redirectURI, state, "invalid_request", "code_challenge_method must be S256")
- }
-
- // Check if user is logged in
- accessToken, err := auth.GetTokenFromRequest(c.Request())
- if err != nil || accessToken == "" {
- // Redirect to login page with return URL
- loginURL := fmt.Sprintf("/auth/login?redirect=%s", url.QueryEscape(c.Request().URL.String()))
- return c.Redirect(http.StatusFound, loginURL)
- }
-
- // Return consent page HTML
- return s.renderConsentPage(c, client.Config.ClientName, clientID, redirectURI, state, codeChallenge, codeChallengeMethod)
-}
-
-func (s *Service) handleAuthorizePost(c echo.Context) error {
- ctx := c.Request().Context()
-
- // Parse form values
- clientID := c.FormValue("client_id")
- redirectURI := c.FormValue("redirect_uri")
- state := c.FormValue("state")
- codeChallenge := c.FormValue("code_challenge")
- codeChallengeMethod := c.FormValue("code_challenge_method")
- action := c.FormValue("action")
-
- // Validate client
- client, err := s.store.GetOAuth2Client(ctx, clientID)
- if err != nil || client == nil {
- return oauth2Error(c, http.StatusBadRequest, "invalid_client", "client not found")
- }
-
- // Validate redirect_uri
- if !validateRedirectURI(redirectURI, client.Config.RedirectUris) {
- return oauth2Error(c, http.StatusBadRequest, "invalid_redirect_uri", "redirect_uri not registered")
- }
-
- // Handle denial
- if action == "deny" {
- return oauth2ErrorRedirect(c, redirectURI, state, "access_denied", "user denied the request")
- }
-
- // Get current user from session
- accessToken, err := auth.GetTokenFromRequest(c.Request())
- if err != nil || accessToken == "" {
- return oauth2ErrorRedirect(c, redirectURI, state, "access_denied", "user not authenticated")
- }
-
- claims, err := auth.ValidateAccessToken(accessToken, s.secret)
- if err != nil {
- return oauth2ErrorRedirect(c, redirectURI, state, "access_denied", "invalid session")
- }
-
- // Get user from claims
- user, err := s.store.GetUserByEmail(ctx, claims.Subject)
- if err != nil || user == nil {
- return oauth2ErrorRedirect(c, redirectURI, state, "access_denied", "user not found")
- }
-
- // Generate authorization code
- code, err := generateAuthCode()
- if err != nil {
- return oauth2ErrorRedirect(c, redirectURI, state, "server_error", "failed to generate code")
- }
-
- // Store authorization code
- codeConfig := &storepb.OAuth2AuthorizationCodeConfig{
- RedirectUri: redirectURI,
- CodeChallenge: codeChallenge,
- CodeChallengeMethod: codeChallengeMethod,
- }
- if _, err := s.store.CreateOAuth2AuthorizationCode(ctx, &store.OAuth2AuthorizationCodeMessage{
- Code: code,
- ClientID: clientID,
- UserID: user.ID,
- Config: codeConfig,
- ExpiresAt: time.Now().Add(authCodeExpiry),
- }); err != nil {
- return oauth2ErrorRedirect(c, redirectURI, state, "server_error", "failed to store code")
- }
-
- // Update client last active
- _ = s.store.UpdateOAuth2ClientLastActiveAt(ctx, clientID)
-
- // Redirect with code
- u, _ := url.Parse(redirectURI)
- q := u.Query()
- q.Set("code", code)
- if state != "" {
- q.Set("state", state)
- }
- u.RawQuery = q.Encode()
- return c.Redirect(http.StatusFound, u.String())
-}
-
-func (s *Service) renderConsentPage(c echo.Context, clientName, clientID, redirectURI, state, codeChallenge, codeChallengeMethod string) error {
- html := fmt.Sprintf(`<!DOCTYPE html>
-<html>
-<head>
- <title>Authorize Application</title>
- <style>
- body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; display: flex; justify-content: center; align-items: center; min-height: 100vh; margin: 0; background: #f5f5f5; }
- .container { background: white; padding: 2rem; border-radius: 8px; box-shadow: 0 2px 10px rgba(0,0,0,0.1); max-width: 400px; width: 100%%; }
- h1 { margin: 0 0 1rem; font-size: 1.5rem; }
- p { color: #666; margin: 0 0 1.5rem; }
- .app-name { font-weight: bold; color: #333; }
- .buttons { display: flex; gap: 1rem; }
- button { flex: 1; padding: 0.75rem; border: none; border-radius: 4px; font-size: 1rem; cursor: pointer; }
- .allow { background: #4f46e5; color: white; }
- .allow:hover { background: #4338ca; }
- .deny { background: #e5e5e5; color: #333; }
- .deny:hover { background: #d4d4d4; }
- </style>
-</head>
-<body>
- <div class="container">
- <h1>Authorize Application</h1>
- <p><span class="app-name">%s</span> is requesting access to your Bytebase account.</p>
- <form method="POST" action="/oauth2/authorize">
- <input type="hidden" name="client_id" value="%s">
- <input type="hidden" name="redirect_uri" value="%s">
- <input type="hidden" name="state" value="%s">
- <input type="hidden" name="code_challenge" value="%s">
- <input type="hidden" name="code_challenge_method" value="%s">
- <div class="buttons">
- <button type="submit" name="action" value="deny" class="deny">Deny</button>
- <button type="submit" name="action" value="allow" class="allow">Allow</button>
- </div>
- </form>
- </div>
-</body>
-</html>`, clientName, clientID, redirectURI, state, codeChallenge, codeChallengeMethod)
- return c.HTML(http.StatusOK, html)
-}
-```
-
-**Step 2: Check auth helpers exist**
-
-The code references `auth.GetTokenFromRequest` and `auth.ValidateAccessToken`. These may need to be added or use existing functions. Check `backend/api/auth/auth.go` for existing patterns and adapt as needed.
-
-**Step 3: Lint**
-
-Run: `golangci-lint run --allow-parallel-runners ./backend/api/oauth2/authorize.go`
-Expected: No errors (fix any import issues)
-
-**Step 4: Commit**
-
-```bash
-but commit <branch> -m "api: add OAuth2 authorization endpoint"
-```
-
----
-
-## Task 10: OAuth2 Handler - Token Endpoint
-
-**Files:**
-- Create: `backend/api/oauth2/token.go`
-
-**Step 1: Create token handler**
-
-```go
-package oauth2
-
-import (
- "encoding/base64"
- "net/http"
- "slices"
- "strings"
- "time"
-
- "github.com/golang-jwt/jwt/v5"
- "github.com/labstack/echo/v4"
-
- "github.com/bytebase/bytebase/backend/store"
-)
-
-type tokenRequest struct {
- GrantType string `form:"grant_type"`
- Code string `form:"code"`
- RedirectURI string `form:"redirect_uri"`
- CodeVerifier string `form:"code_verifier"`
- RefreshToken string `form:"refresh_token"`
- ClientID string `form:"client_id"`
- ClientSecret string `form:"client_secret"`
-}
-
-type tokenResponse struct {
- AccessToken string `json:"access_token"`
- TokenType string `json:"token_type"`
- ExpiresIn int `json:"expires_in"`
- RefreshToken string `json:"refresh_token,omitempty"`
-}
-
-func (s *Service) handleToken(c echo.Context) error {
- ctx := c.Request().Context()
-
- var req tokenRequest
- if err := c.Bind(&req); err != nil {
- return oauth2Error(c, http.StatusBadRequest, "invalid_request", "failed to parse request")
- }
-
- // Authenticate client
- clientID, clientSecret := s.extractClientCredentials(c, &req)
- if clientID == "" {
- return oauth2Error(c, http.StatusUnauthorized, "invalid_client", "client authentication required")
- }
-
- client, err := s.store.GetOAuth2Client(ctx, clientID)
- if err != nil {
- return oauth2Error(c, http.StatusInternalServerError, "server_error", "failed to lookup client")
- }
- if client == nil {
- return oauth2Error(c, http.StatusUnauthorized, "invalid_client", "client not found")
- }
- if !verifySecret(client.ClientSecretHash, clientSecret) {
- return oauth2Error(c, http.StatusUnauthorized, "invalid_client", "invalid client credentials")
- }
-
- // Handle grant types
- switch req.GrantType {
- case "authorization_code":
- return s.handleAuthorizationCodeGrant(c, client, &req)
- case "refresh_token":
- return s.handleRefreshTokenGrant(c, client, &req)
- default:
- return oauth2Error(c, http.StatusBadRequest, "unsupported_grant_type", "grant_type must be authorization_code or refresh_token")
- }
-}
-
-func (s *Service) extractClientCredentials(c echo.Context, req *tokenRequest) (clientID, clientSecret string) {
- // Try Basic auth first
- authHeader := c.Request().Header.Get("Authorization")
- if strings.HasPrefix(authHeader, "Basic ") {
- decoded, err := base64.StdEncoding.DecodeString(strings.TrimPrefix(authHeader, "Basic "))
- if err == nil {
- parts := strings.SplitN(string(decoded), ":", 2)
- if len(parts) == 2 {
- return parts[0], parts[1]
- }
- }
- }
- // Fall back to form params
- return req.ClientID, req.ClientSecret
-}
-
-func (s *Service) handleAuthorizationCodeGrant(c echo.Context, client *store.OAuth2ClientMessage, req *tokenRequest) error {
- ctx := c.Request().Context()
-
- // Validate grant type is allowed
- if !slices.Contains(client.Config.GrantTypes, "authorization_code") {
- return oauth2Error(c, http.StatusBadRequest, "unauthorized_client", "client not authorized for authorization_code grant")
- }
-
- // Validate code
- if req.Code == "" {
- return oauth2Error(c, http.StatusBadRequest, "invalid_request", "code is required")
- }
-
- authCode, err := s.store.GetOAuth2AuthorizationCode(ctx, req.Code)
- if err != nil {
- return oauth2Error(c, http.StatusInternalServerError, "server_error", "failed to lookup code")
- }
- if authCode == nil {
- return oauth2Error(c, http.StatusBadRequest, "invalid_grant", "invalid or expired code")
- }
-
- // Delete code immediately (single use)
- _ = s.store.DeleteOAuth2AuthorizationCode(ctx, req.Code)
-
- // Validate code belongs to this client
- if authCode.ClientID != client.ClientID {
- return oauth2Error(c, http.StatusBadRequest, "invalid_grant", "code was not issued to this client")
- }
-
- // Validate code not expired
- if time.Now().After(authCode.ExpiresAt) {
- return oauth2Error(c, http.StatusBadRequest, "invalid_grant", "code has expired")
- }
-
- // Validate redirect_uri matches
- if req.RedirectURI != authCode.Config.RedirectUri {
- return oauth2Error(c, http.StatusBadRequest, "invalid_grant", "redirect_uri mismatch")
- }
-
- // Validate PKCE
- if req.CodeVerifier == "" {
- return oauth2Error(c, http.StatusBadRequest, "invalid_request", "code_verifier is required")
- }
- if !verifyPKCE(req.CodeVerifier, authCode.Config.CodeChallenge, authCode.Config.CodeChallengeMethod) {
- return oauth2Error(c, http.StatusBadRequest, "invalid_grant", "invalid code_verifier")
- }
-
- // Get user
- user, err := s.store.GetUserByID(ctx, authCode.UserID)
- if err != nil || user == nil {
- return oauth2Error(c, http.StatusBadRequest, "invalid_grant", "user not found")
- }
-
- // Generate tokens
- return s.issueTokens(c, client, user.ID, user.Email)
-}
-
-func (s *Service) handleRefreshTokenGrant(c echo.Context, client *store.OAuth2ClientMessage, req *tokenRequest) error {
- ctx := c.Request().Context()
-
- // Validate grant type is allowed
- if !slices.Contains(client.Config.GrantTypes, "refresh_token") {
- return oauth2Error(c, http.StatusBadRequest, "unauthorized_client", "client not authorized for refresh_token grant")
- }
-
- // Validate refresh token
- if req.RefreshToken == "" {
- return oauth2Error(c, http.StatusBadRequest, "invalid_request", "refresh_token is required")
- }
-
- tokenHash := hashToken(req.RefreshToken)
- refreshToken, err := s.store.GetOAuth2RefreshToken(ctx, tokenHash)
- if err != nil {
- return oauth2Error(c, http.StatusInternalServerError, "server_error", "failed to lookup refresh token")
- }
- if refreshToken == nil {
- return oauth2Error(c, http.StatusBadRequest, "invalid_grant", "invalid refresh token")
- }
-
- // Delete token immediately (single use, will issue new one)
- _ = s.store.DeleteOAuth2RefreshToken(ctx, tokenHash)
-
- // Validate token belongs to this client
- if refreshToken.ClientID != client.ClientID {
- return oauth2Error(c, http.StatusBadRequest, "invalid_grant", "refresh token was not issued to this client")
- }
-
- // Validate not expired
- if time.Now().After(refreshToken.ExpiresAt) {
- return oauth2Error(c, http.StatusBadRequest, "invalid_grant", "refresh token has expired")
- }
-
- // Get user
- user, err := s.store.GetUserByID(ctx, refreshToken.UserID)
- if err != nil || user == nil {
- return oauth2Error(c, http.StatusBadRequest, "invalid_grant", "user not found")
- }
-
- // Issue new tokens
- return s.issueTokens(c, client, user.ID, user.Email)
-}
-
-func (s *Service) issueTokens(c echo.Context, client *store.OAuth2ClientMessage, userID int, userEmail string) error {
- ctx := c.Request().Context()
-
- // Generate access token (JWT)
- now := time.Now()
- claims := jwt.MapClaims{
- "iss": "bytebase",
- "sub": userEmail,
- "aud": "bb.oauth2.access",
- "exp": now.Add(accessTokenExpiry).Unix(),
- "iat": now.Unix(),
- "client_id": client.ClientID,
- }
- token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
- accessToken, err := token.SignedString([]byte(s.secret))
- if err != nil {
- return oauth2Error(c, http.StatusInternalServerError, "server_error", "failed to generate access token")
- }
-
- // Generate refresh token if allowed
- var refreshTokenStr string
- if slices.Contains(client.Config.GrantTypes, "refresh_token") {
- refreshTokenStr, err = generateRefreshToken()
- if err != nil {
- return oauth2Error(c, http.StatusInternalServerError, "server_error", "failed to generate refresh token")
- }
-
- // Store refresh token
- if _, err := s.store.CreateOAuth2RefreshToken(ctx, &store.OAuth2RefreshTokenMessage{
- TokenHash: hashToken(refreshTokenStr),
- ClientID: client.ClientID,
- UserID: userID,
- ExpiresAt: now.Add(refreshTokenExpiry),
- }); err != nil {
- return oauth2Error(c, http.StatusInternalServerError, "server_error", "failed to store refresh token")
- }
- }
-
- // Update client last active
- _ = s.store.UpdateOAuth2ClientLastActiveAt(ctx, client.ClientID)
-
- return c.JSON(http.StatusOK, &tokenResponse{
- AccessToken: accessToken,
- TokenType: "Bearer",
- ExpiresIn: int(accessTokenExpiry.Seconds()),
- RefreshToken: refreshTokenStr,
- })
-}
-```
-
-**Step 2: Lint**
-
-Run: `golangci-lint run --allow-parallel-runners ./backend/api/oauth2/token.go`
-Expected: No errors
-
-**Step 3: Commit**
-
-```bash
-but commit <branch> -m "api: add OAuth2 token endpoint"
-```
-
----
-
-## Task 11: OAuth2 Handler - Revocation Endpoint
-
-**Files:**
-- Create: `backend/api/oauth2/revoke.go`
-
-**Step 1: Create revoke handler**
-
-```go
-package oauth2
-
-import (
- "encoding/base64"
- "net/http"
- "strings"
-
- "github.com/labstack/echo/v4"
-)
-
-type revokeRequest struct {
- Token string `form:"token"`
- TokenTypeHint string `form:"token_type_hint"`
- ClientID string `form:"client_id"`
- ClientSecret string `form:"client_secret"`
-}
-
-func (s *Service) handleRevoke(c echo.Context) error {
- ctx := c.Request().Context()
-
- var req revokeRequest
- if err := c.Bind(&req); err != nil {
- return oauth2Error(c, http.StatusBadRequest, "invalid_request", "failed to parse request")
- }
-
- // Authenticate client
- clientID, clientSecret := s.extractRevokeClientCredentials(c, &req)
- if clientID == "" {
- return oauth2Error(c, http.StatusUnauthorized, "invalid_client", "client authentication required")
- }
-
- client, err := s.store.GetOAuth2Client(ctx, clientID)
- if err != nil {
- return oauth2Error(c, http.StatusInternalServerError, "server_error", "failed to lookup client")
- }
- if client == nil {
- return oauth2Error(c, http.StatusUnauthorized, "invalid_client", "client not found")
- }
- if !verifySecret(client.ClientSecretHash, clientSecret) {
- return oauth2Error(c, http.StatusUnauthorized, "invalid_client", "invalid client credentials")
- }
-
- // Validate token
- if req.Token == "" {
- return oauth2Error(c, http.StatusBadRequest, "invalid_request", "token is required")
- }
-
- // Try to revoke as refresh token
- tokenHash := hashToken(req.Token)
- if err := s.store.DeleteOAuth2RefreshToken(ctx, tokenHash); err != nil {
- // Ignore errors - RFC 7009 says to return 200 even if token is invalid
- }
-
- // Return success (RFC 7009: always return 200)
- return c.NoContent(http.StatusOK)
-}
-
-func (s *Service) extractRevokeClientCredentials(c echo.Context, req *revokeRequest) (clientID, clientSecret string) {
- // Try Basic auth first
- authHeader := c.Request().Header.Get("Authorization")
- if strings.HasPrefix(authHeader, "Basic ") {
- decoded, err := base64.StdEncoding.DecodeString(strings.TrimPrefix(authHeader, "Basic "))
- if err == nil {
- parts := strings.SplitN(string(decoded), ":", 2)
- if len(parts) == 2 {
- return parts[0], parts[1]
- }
- }
- }
- // Fall back to form params
- return req.ClientID, req.ClientSecret
-}
-```
-
-**Step 2: Lint**
-
-Run: `golangci-lint run --allow-parallel-runners ./backend/api/oauth2/revoke.go`
-Expected: No errors
-
-**Step 3: Commit**
-
-```bash
-but commit <branch> -m "api: add OAuth2 revocation endpoint"
-```
-
----
-
-## Task 12: Register OAuth2 Routes in Server
-
-**Files:**
-- Modify: `backend/server/server.go`
-- Modify: `backend/server/echo_routes.go`
-
-**Step 1: Add OAuth2 service to server struct**
-
-In `backend/server/server.go`, add import and initialize OAuth2 service in `NewServer`:
-
-```go
-import (
- // ... existing imports
- "github.com/bytebase/bytebase/backend/api/oauth2"
-)
-
-// In NewServer function, after other service initializations:
-oauth2Service := oauth2.NewService(stores, secret, profile.ExternalURL)
-```
-
-**Step 2: Register OAuth2 routes in echo_routes.go**
-
-In `backend/server/echo_routes.go`, add OAuth2 route registration in `configureEchoRouters`:
-
-```go
-func configureEchoRouters(
- e *echo.Echo,
- lspServer *lsp.Server,
- directorySyncServer *directorysync.Service,
- oauth2Service *oauth2.Service, // Add parameter
- profile *config.Profile,
-) {
- // ... existing code ...
-
- // OAuth2 routes
- oauth2Service.RegisterRoutes(e.Group(""))
-}
-```
-
-**Step 3: Update configureEchoRouters call**
-
-In `backend/server/server.go`, update the call to pass oauth2Service.
-
-**Step 4: Lint**
-
-Run: `golangci-lint run --allow-parallel-runners ./backend/server/...`
-Expected: No errors
-
-**Step 5: Commit**
-
-```bash
-but commit <branch> -m "server: register OAuth2 routes"
-```
-
----
-
-## Task 13: Auth Interceptor - Accept OAuth2 Tokens
-
-**Files:**
-- Modify: `backend/api/auth/auth.go`
-
-**Step 1: Update token validation to accept OAuth2 audience**
-
-Find the token validation logic and add `bb.oauth2.access` as a valid audience:
-
-```go
-// In the ValidateAccessToken or similar function, update audience check:
-validAudiences := []string{
- fmt.Sprintf("bb.user.access.%s", mode),
- "bb.oauth2.access", // Add this
-}
-```
-
-**Step 2: Lint**
-
-Run: `golangci-lint run --allow-parallel-runners ./backend/api/auth/...`
-Expected: No errors
-
-**Step 3: Commit**
-
-```bash
-but commit <branch> -m "auth: accept OAuth2 access tokens"
-```
-
----
-
-## Task 14: Add Store Helper Methods
-
-**Files:**
-- Modify: `backend/store/user.go` (or principal.go)
-
-**Step 1: Add GetUserByEmail if not exists**
-
-Check if `GetUserByEmail` exists. If not, add:
-
-```go
-func (s *Store) GetUserByEmail(ctx context.Context, email string) (*UserMessage, error) {
- users, err := s.ListUsers(ctx, &FindUserMessage{Email: &email})
- if err != nil {
- return nil, err
- }
- if len(users) == 0 {
- return nil, nil
- }
- return users[0], nil
-}
-```
-
-**Step 2: Add GetUserByID if not exists**
-
-```go
-func (s *Store) GetUserByID(ctx context.Context, id int) (*UserMessage, error) {
- users, err := s.ListUsers(ctx, &FindUserMessage{ID: &id})
- if err != nil {
- return nil, err
- }
- if len(users) == 0 {
- return nil, nil
- }
- return users[0], nil
-}
-```
-
-**Step 3: Lint**
-
-Run: `golangci-lint run --allow-parallel-runners ./backend/store/...`
-Expected: No errors
-
-**Step 4: Commit**
-
-```bash
-but commit <branch> -m "store: add user lookup helpers"
-```
-
----
-
-## Task 15: Build and Test
-
-**Step 1: Build**
-
-Run: `go build -ldflags "-w -s" -p=16 -o ./bytebase-build/bytebase ./backend/bin/server/main.go`
-Expected: Build succeeds
-
-**Step 2: Run linter on all changes**
-
-Run: `golangci-lint run --allow-parallel-runners ./backend/...`
-Expected: No errors (run repeatedly until clean)
-
-**Step 3: Manual test (optional)**
-
-Start the server and test the OAuth2 flow:
-
-1. Discovery: `curl http://localhost:8080/.well-known/oauth-authorization-server`
-2. Register client: `curl -X POST http://localhost:8080/oauth2/register -H "Content-Type: application/json" -d '{"client_name":"Test","redirect_uris":["http://localhost:3000/callback"]}'`
-3. Open authorize URL in browser
-4. Exchange code for token
-
-**Step 4: Commit**
-
-```bash
-but commit <branch> -m "build: verify OAuth2 implementation compiles"
-```
-
----
-
-## Summary
-
-| Task | Description | Files |
-|------|-------------|-------|
-| 1 | Proto definitions | `proto/store/oauth2.proto` |
-| 2 | Database migration | `backend/migrator/migration/3.13/0020##...` |
-| 3 | Store: OAuth2 Client | `backend/store/oauth2_client.go` |
-| 4 | Store: Authorization Code | `backend/store/oauth2_authorization_code.go` |
-| 5 | Store: Refresh Token | `backend/store/oauth2_refresh_token.go` |
-| 6 | Handler: Utilities | `backend/api/oauth2/oauth2.go` |
-| 7 | Handler: Discovery | `backend/api/oauth2/discovery.go` |
-| 8 | Handler: DCR | `backend/api/oauth2/register.go` |
-| 9 | Handler: Authorize | `backend/api/oauth2/authorize.go` |
-| 10 | Handler: Token | `backend/api/oauth2/token.go` |
-| 11 | Handler: Revoke | `backend/api/oauth2/revoke.go` |
-| 12 | Server registration | `backend/server/server.go`, `echo_routes.go` |
-| 13 | Auth interceptor | `backend/api/auth/auth.go` |
-| 14 | Store helpers | `backend/store/user.go` |
-| 15 | Build and test | - |
diff --git a/docs/plans/2025-12-11-user-service-email-identifier-design.md b/docs/plans/2025-12-11-user-service-email-identifier-design.md
deleted file mode 100644
index 8c9c7eb840..0000000000
--- a/docs/plans/2025-12-11-user-service-email-identifier-design.md
+++ /dev/null
@@ -1,354 +0,0 @@
-# User Service Email Identifier Migration
-
-**Date:** 2025-12-11
-**Status:** Approved
-**Type:** Breaking Change
-
-## Overview
-
-This is a breaking change that standardizes all UserService API endpoints to use email addresses as the user identifier in resource paths instead of UIDs. The motivation is to provide user-friendly, readable URLs (`users/[email protected]` instead of `users/123`) and create consistent API behavior across all endpoints.
-
-### What's Changing
-
-- **Proto file**: Update all comments from "users/{user uid or user email}" or "users/{user}" to explicitly state "users/{email}"
-- **User resource pattern**: Change from `pattern: "users/{user}"` to `pattern: "users/{email}"`
-- **Backend**: Update all parsing logic that currently extracts UID from the path to extract and lookup by email instead
-- **Frontend**: Update all API calls that construct paths with UIDs to use emails instead
-
-### What's NOT Changing
-
-- The User message structure itself (name field still uses internal UID format for storage)
-- Database schema (email is already unique via recent migration)
-- The actual email field in User messages
-- API method signatures and request/response types
-
-### Breaking Change Impact
-
-- All existing API clients must update to use emails in resource paths
-- This will be marked with the `breaking` label in the PR
-- Frontend and backend should be deployed together to avoid compatibility issues
-
-## Proto File Changes
-
-### Resource Pattern Update
-
-**Before:**
-```proto
-option (google.api.resource) = {
- type: "bytebase.com/User"
- pattern: "users/{user}"
-};
-```
-
-**After:**
-```proto
-option (google.api.resource) = {
- type: "bytebase.com/User"
- pattern: "users/{email}"
-};
-```
-
-### Comment Updates for All Methods
-
-Update format comments in request messages:
-- `GetUserRequest`: "Format: users/{email}"
-- `BatchGetUsersRequest`: "Format: users/{email}"
-- `UpdateUserRequest`: "Format: users/{email}"
-- `DeleteUserRequest`: "Format: users/{email}"
-- `UndeleteUserRequest`: "Format: users/{email}"
-- `UpdateEmailRequest`: Make consistent "Format: users/{email}"
-
-### UpdateEmail Special Case
-
-The path will contain the *old* email (the one being updated from), and the `email` field in the request body contains the *new* email. Add clear comment:
-
-```proto
-// The name of the user whose email to update.
-// Format: users/{email}
-// Note: This is the current (old) email address. The new email is specified in the 'email' field.
-```
-
-### User.name Field Comment Update
-
-**Before:**
-```proto
-// The name of the user.
-// Format: users/{user}. {user} is a system-generated unique ID.
-```
-
-**After:**
-```proto
-// The name of the user.
-// Format: users/{email} for API requests. Internally stored as users/{uid}.
-```
-
-## Backend Changes
-
-### Path Parsing Logic
-
-Currently, backend code extracts the UID from paths like `users/123`. Update all UserService handlers to:
-1. Extract the email from the path (e.g., `users/[email protected]`)
-2. Look up the user by email in the database
-3. Use the retrieved user's UID for internal operations
-
-### Files to Update
-
-`backend/api/v1/user_service.go` (or similar) - All RPC method implementations:
-- `GetUser()` - Parse email from name, lookup by email
-- `UpdateUser()` - Parse email from user.name, lookup by email
-- `DeleteUser()` - Parse email from name, lookup by email
-- `UndeleteUser()` - Parse email from name, lookup by email
-- `UpdateEmail()` - Parse old email from name, lookup by email, then update to new email
-- `BatchGetUsers()` - Parse emails from names array, batch lookup by emails
-
-### Helper Function Changes
-
-- Any utility functions that parse resource names (e.g., `getUserID(name string)`) should be updated to `getUserEmail(name string)` and return the email portion
-- Database store methods may need new methods or updates to support lookup by email (check `backend/store/user.go`)
-
-### Validation
-
-- Add email format validation when parsing from the path
-- Return appropriate errors if email is invalid or user not found
-
-### UpdateEmail Special Handling
-
-- Parse old email from path
-- Lookup user by old email
-- Validate new email doesn't already exist (handled by unique constraint, but should return friendly error)
-- Update the email field
-
-## Frontend Changes
-
-### API Call Updates
-
-All frontend code that constructs user resource paths needs to change from using UIDs to using emails.
-
-**Before:**
-```typescript
-const user = await userServiceClient.getUser({ name: `users/${userId}` });
-await userServiceClient.updateUser({ user: { name: `users/${userId}`, ... } });
-await userServiceClient.deleteUser({ name: `users/${userId}` });
-```
-
-**After:**
-```typescript
-const user = await userServiceClient.getUser({ name: `users/${email}` });
-await userServiceClient.updateUser({ user: { name: `users/${email}`, ... } });
-await userServiceClient.deleteUser({ name: `users/${email}` });
-```
-
-### No Manual Encoding Needed
-
-ConnectRPC's generated client will automatically URL-encode the email (handling `@` and other special characters) when making HTTP requests.
-
-### Files to Search and Update
-
-- Search for `users/\${` or `"users/" +` patterns in TypeScript/Vue files
-- Common locations: `frontend/src/` (stores, views, components that interact with user API)
-- Look for:
- - Direct API calls to UserService methods
- - Route parameter construction
- - Any code that builds user resource names
-
-### Edge Cases
-
-- Ensure any cached or stored user references are updated
-- Update any frontend routing that uses user IDs to use emails
-- Check for any UI components that display or link to user resources
-
-## Testing Strategy
-
-### Unit Tests
-
-Update existing unit tests that construct user resource names to use emails instead of UIDs.
-
-### Integration Tests
-
-Test all UserService endpoints with email-based paths.
-
-### Edge Cases to Test
-
-- Emails with special characters (e.g., `[email protected]`, `[email protected]`)
-- UpdateEmail endpoint (old email in path, new email in body)
-- User not found by email (proper error messages)
-- Invalid email format in path
-
-## Implementation Steps
-
-### 1. Proto Generation
-
-After updating the proto file, run:
-```bash
-buf format -w proto
-buf lint proto
-cd proto && buf generate
-```
-
-### 2. Implementation Order
-
-1. Update proto file and regenerate
-2. Update backend handlers (all methods in UserService)
-3. Update frontend API calls
-4. Run formatting/linting for all changed code
-5. Update and run tests
-6. Verify all endpoints work with email-based paths
-
-### 3. Code Formatting
-
-**Go changes:**
-```bash
-gofmt -w <modified-files>
-golangci-lint run --allow-parallel-runners
-golangci-lint run --fix --allow-parallel-runners
-```
-
-**Frontend changes:**
-```bash
-pnpm --dir frontend biome:check
-pnpm --dir frontend type-check
-```
-
-## Migration Considerations
-
-- This is a breaking change - add `breaking` label to PR
-- Document in release notes that all API clients must update
-- No database migration needed (email already has unique index via commit 2121f49a4e)
-- Consider the timing of frontend and backend deployments (may need to deploy together)
-
-### Rollout Considerations
-
-If there are external API clients:
-- Announce the change in advance
-- Provide migration timeline
-- Clear documentation on what changed
-
-## Success Criteria
-
-- All UserService endpoints accept only `users/{email}` format
-- Proto comments clearly document the email-based format
-- Backend correctly parses emails and looks up users
-- Frontend uses emails in all user resource paths
-- All tests pass with email-based paths
-- Documentation updated for API clients
-
----
-
-## Implementation Notes
-
-**Implementation Completed:** 2025-12-11
-
-All UserService endpoints now exclusively accept email-based identifiers in resource paths (`users/{email}`). The implementation was completed across proto definitions, backend services, frontend code, and tests.
-
-### Changes Made
-
-#### Proto Changes
-- Updated `proto/v1/v1/user_service.proto`:
- - Changed User resource pattern from `pattern: "users/{user}"` to `pattern: "users/{email}"`
- - Updated all request message comments (GetUserRequest, BatchGetUsersRequest, UpdateUserRequest, DeleteUserRequest, UndeleteUserRequest, UpdateEmailRequest) to specify "Format: users/{email}"
- - Updated User.name field comment to document "Format: users/{email} for API requests. Internally stored as users/{uid}."
-- Generated proto code via `buf generate`
-- Commits: `77dc9f54c7`
-
-#### Backend Changes
-- Updated `backend/api/v1/user_service.go`:
- - **GetUser**: Replaced UID/email fallback logic with email-only parsing using `common.GetUserEmail()`
- - **UpdateUser**: Changed from `GetUserID()` to `GetUserEmail()` and replaced `GetUserByID()` with `GetUserByEmail()`
- - **DeleteUser**: Changed from `GetUserID()` to `GetUserEmail()` and replaced `GetUserByID()` with `GetUserByEmail()`
- - **UndeleteUser**: Changed from `GetUserID()` to `GetUserEmail()` and replaced `GetUserByID()` with `GetUserByEmail()`
- - **convertToUser**: Updated to use `FormatUserEmail()` instead of `FormatUserUID()` for resource name formatting, with fallback to UID for users with empty email
-- All error messages updated to use email identifiers for consistency
-- Commits: `3830495207`, `25f766ca1d`, `36585fc87d`, `a0c045cb50`, `b0553832bd`
-
-#### Frontend Changes
-- Updated `frontend/src/types/v1/user.ts`:
- - Changed `SYSTEM_BOT_USER_NAME` constant to use `SYSTEM_BOT_EMAIL` instead of `SYSTEM_BOT_ID`
- - Updated `allUsersUser` to use `ALL_USERS_USER_EMAIL` instead of `ALL_USERS_USER_ID`
- - Removed unused `ALL_USERS_USER_ID` constant
-- All user resource names now constructed with email addresses
-- Commit: `b0553832bd`
-
-#### Tests
-- Added `backend/api/v1/user_service_test.go`:
- - New `TestConvertToUser` with comprehensive test cases:
- - User with valid email (formats as `users/{email}`)
- - User with empty email (formats as `users/{uid}` fallback)
- - Service account with email
- - All tests pass successfully
-- Commit: `23fc2b0bd4`
-
-### Verification Steps
-
-All verification steps completed successfully:
-
-1. **Proto Validation**
- - `buf format -w proto` - File formatted
- - `buf lint proto` - No linting errors
- - `cd proto && buf generate` - Code generation successful
-
-2. **Backend Validation**
- - `gofmt -w backend/api/v1/user_service.go` - File formatted
- - `golangci-lint run --allow-parallel-runners` - No linting errors
- - All backend methods updated and tested
-
-3. **Frontend Validation**
- - `pnpm --dir frontend biome:check` - Format and lint passed
- - `pnpm --dir frontend type-check` - Type checks passed
-
-4. **Build Verification**
- - Backend builds successfully
- - All unit tests pass
-
-5. **Git Status**
- - All changes committed with descriptive commit messages
- - Working tree clean
-
-### Migration Requirements
-
-**Breaking Change:** All API clients must update to use email addresses in user resource paths.
-
-**Before:**
-```
-users/101
-users/42
-```
-
-**After:**
-```
-```
-
-**Backend Behavior:**
-- All UserService methods now exclusively parse email from resource paths
-- User lookup changed from UID-based to email-based queries
-- Error messages use email identifiers for better clarity
-- Fallback to UID format only for internal users with empty email addresses
-
-**Frontend Behavior:**
-- All user resource names constructed with email addresses
-- System bot and special users use email constants
-- ConnectRPC client automatically handles URL encoding of special characters in emails
-
-**No Database Migration Required:**
-- Email unique index already exists (commit `2121f49a4e`)
-- Internal storage format unchanged (still uses UID internally)
-- Only API resource path format changed
-
-### Deployment Considerations
-
-- Frontend and backend should be deployed together to avoid compatibility issues
-- External API clients must be updated before or during deployment
-- This is marked as a breaking change in the PR
-
-### Related Commits
-
-- Design document: `e632362438`
-- Implementation plan: `6941123b81`
-- Proto changes: `77dc9f54c7`
-- Backend GetUser: `3830495207`
-- Backend UpdateUser: `25f766ca1d`
-- Backend DeleteUser: `36585fc87d`
-- Backend UndeleteUser: `a0c045cb50`
-- Frontend and convertToUser: `b0553832bd`
-- Tests and validation: `23fc2b0bd4`
diff --git a/docs/plans/2025-12-11-user-service-email-identifier.md b/docs/plans/2025-12-11-user-service-email-identifier.md
deleted file mode 100644
index cd83be3e27..0000000000
--- a/docs/plans/2025-12-11-user-service-email-identifier.md
+++ /dev/null
@@ -1,947 +0,0 @@
-# User Service Email Identifier Implementation Plan
-
-> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
-
-**Goal:** Migrate UserService API from UID-based to email-based resource identifiers
-
-**Architecture:** Breaking change that updates proto definitions, backend parsing logic, and frontend API calls to exclusively use email addresses in user resource paths (users/{email} instead of users/{uid})
-
-**Tech Stack:** Protocol Buffers, Go (backend), TypeScript/Vue (frontend), ConnectRPC
-
----
-
-## Task 1: Update Proto File
-
-**Files:**
-- Modify: `proto/v1/v1/user_service.proto`
-
-### Step 1: Update User resource pattern
-
-In `proto/v1/v1/user_service.proto`, find the User message resource annotation (around line 253-256) and update it:
-
-**Before:**
-```proto
-option (google.api.resource) = {
- type: "bytebase.com/User"
- pattern: "users/{user}"
-};
-```
-
-**After:**
-```proto
-option (google.api.resource) = {
- type: "bytebase.com/User"
- pattern: "users/{email}"
-};
-```
-
-### Step 2: Update User.name field comment
-
-Find the `name` field in the User message (around line 258-260) and update the comment:
-
-**Before:**
-```proto
-// The name of the user.
-// Format: users/{user}. {user} is a system-generated unique ID.
-string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
-```
-
-**After:**
-```proto
-// The name of the user.
-// Format: users/{email} for API requests. Internally stored as users/{uid}.
-string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
-```
-
-### Step 3: Update GetUserRequest comment
-
-Find GetUserRequest message (around line 117-124) and update the comment:
-
-**Before:**
-```proto
-message GetUserRequest {
- // The name of the user to retrieve.
- // Format: users/{user uid or user email}
- string name = 1 [
-```
-
-**After:**
-```proto
-message GetUserRequest {
- // The name of the user to retrieve.
- // Format: users/{email}
- string name = 1 [
-```
-
-### Step 4: Update BatchGetUsersRequest comment
-
-Find BatchGetUsersRequest message (around line 126-133) and update the comment:
-
-**Before:**
-```proto
-message BatchGetUsersRequest {
- // The user names to retrieve.
- // Format: users/{user uid or user email}
- repeated string names = 1 [
-```
-
-**After:**
-```proto
-message BatchGetUsersRequest {
- // The user names to retrieve.
- // Format: users/{email}
- repeated string names = 1 [
-```
-
-### Step 5: Update UpdateUserRequest comment
-
-Find UpdateUserRequest message (around line 197-202) and update the comment:
-
-**Before:**
-```proto
-message UpdateUserRequest {
- // The user to update.
- //
- // The user's `name` field is used to identify the user to update.
- // Format: users/{user}
- User user = 1 [(google.api.field_behavior) = REQUIRED];
-```
-
-**After:**
-```proto
-message UpdateUserRequest {
- // The user to update.
- //
- // The user's `name` field is used to identify the user to update.
- // Format: users/{email}
- User user = 1 [(google.api.field_behavior) = REQUIRED];
-```
-
-### Step 6: Update DeleteUserRequest comment
-
-Find DeleteUserRequest message (around line 222-228) and update the comment:
-
-**Before:**
-```proto
-message DeleteUserRequest {
- // The name of the user to delete.
- // Format: users/{user}
- string name = 1 [
-```
-
-**After:**
-```proto
-message DeleteUserRequest {
- // The name of the user to delete.
- // Format: users/{email}
- string name = 1 [
-```
-
-### Step 7: Update UndeleteUserRequest comment
-
-Find UndeleteUserRequest message (around line 231-237) and update the comment:
-
-**Before:**
-```proto
-message UndeleteUserRequest {
- // The name of the deleted user.
- // Format: users/{user}
- string name = 1 [
-```
-
-**After:**
-```proto
-message UndeleteUserRequest {
- // The name of the deleted user.
- // Format: users/{email}
- string name = 1 [
-```
-
-### Step 8: Update UpdateEmailRequest comment with clarification
-
-Find UpdateEmailRequest message (around line 240-250) and update the comment:
-
-**Before:**
-```proto
-message UpdateEmailRequest {
- // The name of the user whose email to update.
- // Format: users/{user email}
- string name = 1 [
-```
-
-**After:**
-```proto
-message UpdateEmailRequest {
- // The name of the user whose email to update.
- // Format: users/{email}
- // Note: This is the current (old) email address. The new email is specified in the 'email' field.
- string name = 1 [
-```
-
-### Step 9: Format proto file
-
-Run:
-```bash
-buf format -w proto
-```
-
-Expected: File formatted successfully
-
-### Step 10: Lint proto file
-
-Run:
-```bash
-buf lint proto
-```
-
-Expected: No linting errors
-
-### Step 11: Generate proto code
-
-Run:
-```bash
-cd proto && buf generate
-```
-
-Expected: Code generation successful, new files in `backend/generated-go/v1/`
-
-### Step 12: Commit proto changes
-
-```bash
-git add proto/v1/v1/user_service.proto backend/generated-go/
-git commit -m "feat(proto): migrate user service to email-based identifiers
-
-Update UserService proto to use email addresses instead of UIDs in
-resource paths. This is a breaking change that makes user APIs more
-user-friendly and consistent.
-
-Breaking change: All user resource paths now require email format
-(users/{email}) instead of accepting both UID and email.
-
-🤖 Generated with [Claude Code](https://claude.com/claude-code)
-
-Co-Authored-By: Claude Sonnet 4.5 <[email protected]>"
-```
-
----
-
-## Task 2: Update Backend GetUser Method
-
-**Files:**
-- Modify: `backend/api/v1/user_service.go:59-84`
-
-### Step 1: Simplify GetUser to use email only
-
-Find the `GetUser` method (lines 59-84) and replace the entire method:
-
-**Before:**
-```go
-func (s *UserService) GetUser(ctx context.Context, request *connect.Request[v1pb.GetUserRequest]) (*connect.Response[v1pb.User], error) {
- userID, err := common.GetUserID(request.Msg.Name)
- var user *store.UserMessage
- if err != nil {
- email, err := common.GetUserEmail(request.Msg.Name)
- if err != nil {
- return nil, connect.NewError(connect.CodeInvalidArgument, err)
- }
- u, err := s.store.GetUserByEmail(ctx, email)
- if err != nil {
- return nil, connect.NewError(connect.CodeInternal, errors.Errorf("failed to get user, error: %v", err))
- }
- user = u
- } else {
- u, err := s.store.GetUserByID(ctx, userID)
- if err != nil {
- return nil, connect.NewError(connect.CodeInternal, errors.Errorf("failed to get user, error: %v", err))
- }
- user = u
- }
- if user == nil {
- return nil, connect.NewError(connect.CodeNotFound, errors.Errorf("user %d not found", userID))
- }
- return connect.NewResponse(convertToUser(ctx, user)), nil
-}
-```
-
-**After:**
-```go
-func (s *UserService) GetUser(ctx context.Context, request *connect.Request[v1pb.GetUserRequest]) (*connect.Response[v1pb.User], error) {
- email, err := common.GetUserEmail(request.Msg.Name)
- if err != nil {
- return nil, connect.NewError(connect.CodeInvalidArgument, err)
- }
- user, err := s.store.GetUserByEmail(ctx, email)
- if err != nil {
- return nil, connect.NewError(connect.CodeInternal, errors.Errorf("failed to get user, error: %v", err))
- }
- if user == nil {
- return nil, connect.NewError(connect.CodeNotFound, errors.Errorf("user %q not found", email))
- }
- return connect.NewResponse(convertToUser(ctx, user)), nil
-}
-```
-
-### Step 2: Format the file
-
-Run:
-```bash
-gofmt -w backend/api/v1/user_service.go
-```
-
-Expected: File formatted
-
-### Step 3: Run golangci-lint
-
-Run:
-```bash
-golangci-lint run --allow-parallel-runners backend/api/v1/user_service.go
-```
-
-Expected: No linting errors (run multiple times if needed due to max-issues limit)
-
-### Step 4: Commit GetUser changes
-
-```bash
-git add backend/api/v1/user_service.go
-git commit -m "refactor(backend): update GetUser to use email-only parsing
-
-Remove UID fallback logic from GetUser method. Now exclusively parses
-and looks up users by email address from resource path.
-
-🤖 Generated with [Claude Code](https://claude.com/claude-code)
-
-Co-Authored-By: Claude Sonnet 4.5 <[email protected]>"
-```
-
----
-
-## Task 3: Update Backend UpdateUser Method
-
-**Files:**
-- Modify: `backend/api/v1/user_service.go:330-520`
-
-### Step 1: Update UpdateUser to use email parsing
-
-Find the `UpdateUser` method (lines 330-520) and replace the user lookup section (lines 343-368):
-
-**Before (lines 343-368):**
-```go
- userID, err := common.GetUserID(request.Msg.User.Name)
- if err != nil {
- return nil, connect.NewError(connect.CodeInvalidArgument, err)
- }
- user, err := s.store.GetUserByID(ctx, userID)
- if err != nil {
- return nil, connect.NewError(connect.CodeInternal, errors.Errorf("failed to get user, error: %v", err))
- }
- if user == nil {
- if request.Msg.AllowMissing {
- ok, err := s.iamManager.CheckPermission(ctx, iam.PermissionUsersCreate, callerUser)
- if err != nil {
- return nil, connect.NewError(connect.CodeInternal, errors.Errorf("failed to check permission with error: %v", err.Error()))
- }
- if !ok {
- return nil, connect.NewError(connect.CodePermissionDenied, errors.Errorf("user does not have permission %q", iam.PermissionUsersCreate))
- }
- return s.CreateUser(ctx, connect.NewRequest(&v1pb.CreateUserRequest{
- User: request.Msg.User,
- }))
- }
- return nil, connect.NewError(connect.CodeNotFound, errors.Errorf("user %d not found", userID))
- }
- if user.MemberDeleted {
- return nil, connect.NewError(connect.CodeNotFound, errors.Errorf("user %q has been deleted", userID))
- }
-```
-
-**After:**
-```go
- email, err := common.GetUserEmail(request.Msg.User.Name)
- if err != nil {
- return nil, connect.NewError(connect.CodeInvalidArgument, err)
- }
- user, err := s.store.GetUserByEmail(ctx, email)
- if err != nil {
- return nil, connect.NewError(connect.CodeInternal, errors.Errorf("failed to get user, error: %v", err))
- }
- if user == nil {
- if request.Msg.AllowMissing {
- ok, err := s.iamManager.CheckPermission(ctx, iam.PermissionUsersCreate, callerUser)
- if err != nil {
- return nil, connect.NewError(connect.CodeInternal, errors.Errorf("failed to check permission with error: %v", err.Error()))
- }
- if !ok {
- return nil, connect.NewError(connect.CodePermissionDenied, errors.Errorf("user does not have permission %q", iam.PermissionUsersCreate))
- }
- return s.CreateUser(ctx, connect.NewRequest(&v1pb.CreateUserRequest{
- User: request.Msg.User,
- }))
- }
- return nil, connect.NewError(connect.CodeNotFound, errors.Errorf("user %q not found", email))
- }
- if user.MemberDeleted {
- return nil, connect.NewError(connect.CodeNotFound, errors.Errorf("user %q has been deleted", email))
- }
-```
-
-### Step 2: Update permission check to use user.ID
-
-Find the permission check section (around line 370-378) and update to use `user.ID` instead of `userID`:
-
-**Before:**
-```go
- if callerUser.ID != userID {
-```
-
-**After:**
-```go
- if callerUser.ID != user.ID {
-```
-
-### Step 3: Format the file
-
-Run:
-```bash
-gofmt -w backend/api/v1/user_service.go
-```
-
-Expected: File formatted
-
-### Step 4: Run golangci-lint
-
-Run:
-```bash
-golangci-lint run --allow-parallel-runners backend/api/v1/user_service.go
-```
-
-Expected: No linting errors (run multiple times if needed)
-
-### Step 5: Commit UpdateUser changes
-
-```bash
-git add backend/api/v1/user_service.go
-git commit -m "refactor(backend): update UpdateUser to use email parsing
-
-Replace UID parsing with email parsing in UpdateUser method. Lookup
-user by email instead of UID from resource path.
-
-🤖 Generated with [Claude Code](https://claude.com/claude-code)
-
-Co-Authored-By: Claude Sonnet 4.5 <[email protected]>"
-```
-
----
-
-## Task 4: Update Backend DeleteUser Method
-
-**Files:**
-- Modify: `backend/api/v1/user_service.go:522-568`
-
-### Step 1: Update DeleteUser to use email parsing
-
-Find the `DeleteUser` method (lines 522-568) and replace the user lookup section (lines 536-548):
-
-**Before:**
-```go
- userID, err := common.GetUserID(request.Msg.Name)
- if err != nil {
- return nil, connect.NewError(connect.CodeInvalidArgument, err)
- }
- user, err := s.store.GetUserByID(ctx, userID)
- if err != nil {
- return nil, connect.NewError(connect.CodeInternal, errors.Errorf("failed to get user, error: %v", err))
- }
- if user == nil {
- return nil, connect.NewError(connect.CodeNotFound, errors.Errorf("user %d not found", userID))
- }
- if user.MemberDeleted {
- return nil, connect.NewError(connect.CodeNotFound, errors.Errorf("user %q has been deleted", userID))
- }
-```
-
-**After:**
-```go
- email, err := common.GetUserEmail(request.Msg.Name)
- if err != nil {
- return nil, connect.NewError(connect.CodeInvalidArgument, err)
- }
- user, err := s.store.GetUserByEmail(ctx, email)
- if err != nil {
- return nil, connect.NewError(connect.CodeInternal, errors.Errorf("failed to get user, error: %v", err))
- }
- if user == nil {
- return nil, connect.NewError(connect.CodeNotFound, errors.Errorf("user %q not found", email))
- }
- if user.MemberDeleted {
- return nil, connect.NewError(connect.CodeNotFound, errors.Errorf("user %q has been deleted", email))
- }
-```
-
-### Step 2: Format the file
-
-Run:
-```bash
-gofmt -w backend/api/v1/user_service.go
-```
-
-Expected: File formatted
-
-### Step 3: Run golangci-lint
-
-Run:
-```bash
-golangci-lint run --allow-parallel-runners backend/api/v1/user_service.go
-```
-
-Expected: No linting errors
-
-### Step 4: Commit DeleteUser changes
-
-```bash
-git add backend/api/v1/user_service.go
-git commit -m "refactor(backend): update DeleteUser to use email parsing
-
-Replace UID parsing with email parsing in DeleteUser method.
-
-🤖 Generated with [Claude Code](https://claude.com/claude-code)
-
-Co-Authored-By: Claude Sonnet 4.5 <[email protected]>"
-```
-
----
-
-## Task 5: Update Backend UndeleteUser Method
-
-**Files:**
-- Modify: `backend/api/v1/user_service.go:615-654`
-
-### Step 1: Update UndeleteUser to use email parsing
-
-Find the `UndeleteUser` method (lines 615-654) and replace the user lookup section (lines 629-642):
-
-**Before:**
-```go
- userID, err := common.GetUserID(request.Msg.Name)
- if err != nil {
- return nil, connect.NewError(connect.CodeInvalidArgument, err)
- }
- user, err := s.store.GetUserByID(ctx, userID)
- if err != nil {
- return nil, connect.NewError(connect.CodeInternal, errors.Errorf("failed to get user, error: %v", err))
- }
- if user == nil {
- return nil, connect.NewError(connect.CodeNotFound, errors.Errorf("user %d not found", userID))
- }
- if !user.MemberDeleted {
- return nil, connect.NewError(connect.CodeInvalidArgument, errors.Errorf("user %q is already active", userID))
- }
-```
-
-**After:**
-```go
- email, err := common.GetUserEmail(request.Msg.Name)
- if err != nil {
- return nil, connect.NewError(connect.CodeInvalidArgument, err)
- }
- user, err := s.store.GetUserByEmail(ctx, email)
- if err != nil {
- return nil, connect.NewError(connect.CodeInternal, errors.Errorf("failed to get user, error: %v", err))
- }
- if user == nil {
- return nil, connect.NewError(connect.CodeNotFound, errors.Errorf("user %q not found", email))
- }
- if !user.MemberDeleted {
- return nil, connect.NewError(connect.CodeInvalidArgument, errors.Errorf("user %q is already active", email))
- }
-```
-
-### Step 2: Format the file
-
-Run:
-```bash
-gofmt -w backend/api/v1/user_service.go
-```
-
-Expected: File formatted
-
-### Step 3: Run golangci-lint
-
-Run:
-```bash
-golangci-lint run --allow-parallel-runners backend/api/v1/user_service.go
-```
-
-Expected: No linting errors
-
-### Step 4: Commit UndeleteUser changes
-
-```bash
-git add backend/api/v1/user_service.go
-git commit -m "refactor(backend): update UndeleteUser to use email parsing
-
-Replace UID parsing with email parsing in UndeleteUser method.
-
-🤖 Generated with [Claude Code](https://claude.com/claude-code)
-
-Co-Authored-By: Claude Sonnet 4.5 <[email protected]>"
-```
-
----
-
-## Task 6: Update Frontend User References (Part 1 - Search and Identify)
-
-**Files:**
-- Search: `frontend/src/**/*.{ts,vue}`
-
-### Step 1: Search for user resource path construction patterns
-
-Run:
-```bash
-cd frontend && grep -r "users/\${" src/ --include="*.ts" --include="*.vue" | head -20
-```
-
-Expected: List of files that construct user resource paths
-
-### Step 2: Search for FormatUserUID usage
-
-Run:
-```bash
-cd frontend && grep -r "FormatUserUID\|formatUserUID" src/ --include="*.ts" --include="*.vue" | head -20
-```
-
-Expected: List of files using FormatUserUID helper
-
-### Step 3: Document findings
-
-Create a list of files that need updates. Common patterns to look for:
-- `` `users/${userId}` ``
-- `` `users/${user.id}` ``
-- `FormatUserUID(id)` or similar helpers
-- Direct construction of user paths with numeric IDs
-
----
-
-## Task 7: Update Frontend User References (Part 2 - Core Store)
-
-**Files:**
-- Modify: `frontend/src/store/modules/user.ts`
-
-### Step 1: Review current getUserByIdentifier implementation
-
-The function at line 223-234 already handles both UID and email. After backend migration, it should prefer email but may still work as-is due to the fallback logic.
-
-### Step 2: Update ensureUserFullName usage if needed
-
-Check if `ensureUserFullName` needs updates to always format with email instead of UID when constructing user paths.
-
-### Step 3: Search for direct user path construction in store
-
-Run:
-```bash
-grep -n "users/\${" frontend/src/store/modules/user.ts
-```
-
-Expected: Find any direct path constructions that use UID
-
-### Step 4: Update any UID-based constructions to use email
-
-If found, replace patterns like:
-- `` `users/${userId}` `` → `` `users/${email}` ``
-- `user.name` (if it's UID-based) → ensure email is used
-
-### Step 5: Run frontend type check
-
-Run:
-```bash
-pnpm --dir frontend type-check
-```
-
-Expected: No type errors
-
-### Step 6: Commit store changes if any were made
-
-```bash
-git add frontend/src/store/modules/user.ts
-git commit -m "refactor(frontend): update user store to use email identifiers
-
-Update user store to construct user resource paths with email addresses
-instead of UIDs.
-
-🤖 Generated with [Claude Code](https://claude.com/claude-code)
-
-Co-Authored-By: Claude Sonnet 4.5 <[email protected]>"
-```
-
----
-
-## Task 8: Update Frontend Components (Batch Update)
-
-**Files:**
-- Multiple Vue and TypeScript files that construct user paths
-
-### Step 1: Create script to find and replace user path patterns
-
-This will be a manual review and update process. For each file found in Task 6:
-
-1. Open the file
-2. Find patterns like `` `users/${userId}` `` or `` `users/${user.id}` ``
-3. Replace with `` `users/${email}` `` or `` `users/${user.email}` ``
-4. Ensure the email variable is available in scope
-
-### Step 2: Update common files
-
-Based on the search from Task 6, update these known files:
-
-**File:** `frontend/src/components/v2/Model/cells/UserNameCell.vue`
-- Likely already uses email (seen in UserByEmail.vue example)
-- Verify no UID usage
-
-**File:** `frontend/src/views/sql-editor/EditorCommon/SharePopover.vue`
-- Check for user path construction
-- Update if using UID
-
-### Step 3: Run format and lint
-
-Run:
-```bash
-pnpm --dir frontend biome:check
-```
-
-Expected: Code formatted and linted
-
-### Step 4: Run type check
-
-Run:
-```bash
-pnpm --dir frontend type-check
-```
-
-Expected: No type errors
-
-### Step 5: Commit frontend component changes
-
-```bash
-git add frontend/src/
-git commit -m "refactor(frontend): update components to use email in user paths
-
-Update all Vue components to use email addresses instead of UIDs when
-constructing user resource paths.
-
-🤖 Generated with [Claude Code](https://claude.com/claude-code)
-
-Co-Authored-By: Claude Sonnet 4.5 <[email protected]>"
-```
-
----
-
-## Task 9: Update Backend Tests
-
-**Files:**
-- Modify: `backend/api/v1/user_service_test.go` (if tests exist)
-
-### Step 1: Check if tests exist
-
-Run:
-```bash
-cat backend/api/v1/user_service_test.go | head -50
-```
-
-Expected: View test content (file may be empty based on earlier read)
-
-### Step 2: Add basic GetUser test with email
-
-If the file is minimal/empty, add a basic test:
-
-```go
-package v1
-
-import (
- "context"
- "testing"
-
- "connectrpc.com/connect"
- v1pb "github.com/bytebase/bytebase/backend/generated-go/v1"
- "github.com/stretchr/testify/require"
-)
-
-func TestGetUser_EmailIdentifier(t *testing.T) {
- // This is a placeholder test to document the expected behavior
- // Full integration tests should be added
- email := "[email protected]"
- request := &v1pb.GetUserRequest{
- Name: "users/" + email,
- }
-
- // Verify the request format is valid
- require.Equal(t, "users/[email protected]", request.Name)
-}
-```
-
-### Step 3: Run the test
-
-Run:
-```bash
-go test -v -count=1 github.com/bytebase/bytebase/backend/api/v1 -run ^TestGetUser_EmailIdentifier$
-```
-
-Expected: Test passes
-
-### Step 4: Commit test changes
-
-```bash
-git add backend/api/v1/user_service_test.go
-git commit -m "test(backend): add email identifier test for user service
-
-Add basic test documenting expected email-based identifier format.
-
-🤖 Generated with [Claude Code](https://claude.com/claude-code)
-
-Co-Authored-By: Claude Sonnet 4.5 <[email protected]>"
-```
-
----
-
-## Task 10: Final Verification
-
-**Files:**
-- All modified files
-
-### Step 1: Run all Go lints repeatedly
-
-Run:
-```bash
-golangci-lint run --allow-parallel-runners
-```
-
-Repeat until no issues (due to max-issues limit)
-
-Expected: No linting errors
-
-### Step 2: Run Go formatting
-
-Run:
-```bash
-find backend/api/v1 -name "*.go" -exec gofmt -w {} \;
-```
-
-Expected: All files formatted
-
-### Step 3: Run frontend checks
-
-Run:
-```bash
-pnpm --dir frontend biome:check && pnpm --dir frontend type-check
-```
-
-Expected: All checks pass
-
-### Step 4: Build backend
-
-Run:
-```bash
-go build -ldflags "-w -s" -p=16 -o ./bytebase-build/bytebase ./backend/bin/server/main.go
-```
-
-Expected: Build succeeds
-
-### Step 5: Run git status
-
-Run:
-```bash
-git status
-```
-
-Expected: All changes committed, working tree clean
-
-### Step 6: Review all commits
-
-Run:
-```bash
-git log --oneline -10
-```
-
-Expected: See all commits from this implementation
-
----
-
-## Task 11: Documentation and Breaking Change Label
-
-**Files:**
-- Modify: `docs/plans/2025-12-11-user-service-email-identifier-design.md`
-
-### Step 1: Update design doc with implementation notes
-
-Add an "Implementation" section at the end of the design document:
-
-```markdown
-## Implementation Notes
-
-Implementation completed on 2025-12-11. All UserService endpoints now exclusively accept email-based identifiers in resource paths.
-
-### Changes Made
-
-- **Proto**: Updated all request message comments to reflect email-only format
-- **Backend**: Removed UID fallback logic from all UserService methods (GetUser, UpdateUser, DeleteUser, UndeleteUser)
-- **Frontend**: Updated all user path constructions to use email addresses
-- **Tests**: Added basic email identifier test
-
-### Verification
-
-- All Go lints pass
-- Frontend type checks pass
-- Backend builds successfully
-- All changes committed
-
-### Migration Required
-
-All API clients must update to use email addresses in user resource paths:
-- Before: `users/101`
-- After: `users/[email protected]`
-```
-
-### Step 2: Commit documentation update
-
-```bash
-git add docs/plans/2025-12-11-user-service-email-identifier-design.md
-git commit -m "docs: add implementation notes to design document
-
-Document completed implementation and verification steps.
-
-🤖 Generated with [Claude Code](https://claude.com/claude-code)
-
-Co-Authored-By: Claude Sonnet 4.5 <[email protected]>"
-```
-
-### Step 3: Create summary of changes
-
-Create a summary of all changes for the pull request:
-
-**Breaking Changes:**
-- UserService API now requires email addresses in all resource paths
-- `users/{uid}` format no longer supported
-- All clients must update to `users/{email}` format
-
-**Files Changed:**
-- Proto: `proto/v1/v1/user_service.proto`
-- Backend: `backend/api/v1/user_service.go`
-- Frontend: Multiple components in `frontend/src/`
-- Tests: `backend/api/v1/user_service_test.go`
-
----
-
-## Success Criteria
-
-- [ ] All UserService proto comments reflect email-only format
-- [ ] Backend methods use email parsing exclusively (no UID fallback)
-- [ ] Frontend uses email in all user resource path constructions
-- [ ] All linting and type checks pass
-- [ ] Backend builds successfully
-- [ ] All changes committed with descriptive messages
-- [ ] Documentation updated
-
-## Next Steps After Implementation
-
-1. Create pull request with `breaking` label
-2. Update API documentation/changelog with migration guide
-3. Notify API clients about breaking change
-4. Plan deployment strategy (backend and frontend together)