Database governance built for humans and agents — controlling changes and access across every major database.
Go cicddata-governancedata-maskingdata-securitydatabase-accessdatabase-governancedevopsdevsecopsflywaygitopsliquibasemongodbmysqloraclepostgresqlschema-migrationssecuritysql-clientsqlservertidb
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.goindex 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.mddeleted file mode 100644index 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 filteringdiff --git a/docs/plans/2025-12-11-oauth2-server-impl.md b/docs/plans/2025-12-11-oauth2-server-impl.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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:**-```-users/[email protected]-users/[email protected]-```--**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.mddeleted file mode 100644index 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)