クリーンアーキテクチャ設計書¶

// Domain Entities
package domain

import "time"

// User represents a locally cached user from Cognito
type User struct {
    UserID       string
    CognitoSub   string    // Cognito's user UUID
    Email        string
    CreatedAt    time.Time
    UpdatedAt    time.Time
}

// UserSession represents an active login session
type UserSession struct {
    SessionID       string
    UserID          string
    RefreshTokenJti string    // JWT ID of associated refresh token
    CreatedAt       time.Time
    ExpiresAt       time.Time
}

// DeviceRegistration tracks user devices
type DeviceRegistration struct {
    DeviceID      string
    UserID        string
    Fingerprint   string    // Hash of User-Agent + IP
    DeviceName    string    // e.g., "Chrome on MacOS"
    LastSeenAt    time.Time
    RegisteredAt  time.Time
}

// BlockedToken represents a revoked JWT
type BlockedToken struct {
    TokenJti  string
    UserID    string
    RevokedAt time.Time
    ExpiresAt time.Time
}

// RefreshTokenGrant tracks refresh token issuance
type RefreshTokenGrant struct {
    GrantID   string
    UserID    string
    JTI       string    // JWT ID
    IssuedAt  time.Time
    ExpiresAt time.Time
    RevokedAt *time.Time
}

// Value Objects
type AccessToken struct {
    Token     string
    Claims    TokenClaims
    ExpiresAt time.Time
}

type RefreshToken struct {
    Token     string
    JTI       string
    ExpiresAt time.Time
}

type TokenClaims struct {
    Sub      string                 // Cognito Sub
    Exp      int64                  // Expiration (unix)
    Iat      int64                  // Issued at (unix)
    Aud      string                 // Audience
    Custom   map[string]interface{} // Custom claims
}

type DeviceFingerprint struct {
    Value string
}

type CognitoUserAttributes struct {
    Sub       string
    Email     string
    EmailVerified bool
    Name      string
    UpdatedAt int64
}

// Application DTOs
package application

import "time"

// ===== Login Use Case =====
type LoginInput struct {
    Email      string
    Password   string
    DeviceID   string // Client-provided device identifier
    Fingerprint string // User-Agent + IP hash
}

type LoginOutput struct {
    UserID       string
    SessionID    string
    AccessToken  string
    RefreshToken string
    ExpiresIn    int // Access token TTL in seconds
    TokenType    string // "Bearer"
}

// ===== Logout Use Case =====
type LogoutInput struct {
    UserID     string
    SessionID  string
    RefreshTokenJti string
}

type LogoutOutput struct {
    Success   bool
    RevokedAt time.Time
}

// ===== RefreshToken Use Case =====
type RefreshTokenInput struct {
    RefreshToken string
}

type RefreshTokenOutput struct {
    AccessToken string
    ExpiresIn   int
    TokenType   string
}

// ===== RegisterDevice Use Case =====
type RegisterDeviceInput struct {
    UserID      string
    DeviceID    string
    Fingerprint string
    DeviceName  string
}

type RegisterDeviceOutput struct {
    DeviceID   string
    RegisteredAt time.Time
}

// ===== SyncCognito Use Case =====
type SyncCognitoInput struct {
    CognitoSub string
    Email      string
    Name       string
}

type SyncCognitoOutput struct {
    UserID      string
    CreatedAt   time.Time
    IsNewUser   bool
}

// ===== RevokeToken Use Case =====
type RevokeTokenInput struct {
    TokenJti  string
    UserID    string
    ExpiresAt time.Time
}

type RevokeTokenOutput struct {
    Success   bool
    RevokedAt time.Time
}

// Application Ports - Repository Interfaces
package ports

import (
    "context"
    "time"
)

// UserRepository ユーザー管理
type UserRepository interface {
    FindByCognitoSub(ctx context.Context, cognitoSub string) (*User, error)
    FindByUserID(ctx context.Context, userID string) (*User, error)
    Save(ctx context.Context, user *User) error
    Update(ctx context.Context, user *User) error
}

// UserSessionRepository セッション管理
type UserSessionRepository interface {
    FindBySessionID(ctx context.Context, sessionID string) (*UserSession, error)
    FindActiveByUserID(ctx context.Context, userID string) ([]*UserSession, error)
    Save(ctx context.Context, session *UserSession) error
    Delete(ctx context.Context, sessionID string) error
}

// DeviceRegistrationRepository デバイス管理
type DeviceRegistrationRepository interface {
    FindByUserIDAndFingerprint(ctx context.Context, userID, fingerprint string) (*DeviceRegistration, error)
    FindByUserID(ctx context.Context, userID string) ([]*DeviceRegistration, error)
    Save(ctx context.Context, device *DeviceRegistration) error
    UpdateLastSeen(ctx context.Context, deviceID string) error
}

// BlockedTokenRepository トークンブロックリスト
type BlockedTokenRepository interface {
    IsBlocked(ctx context.Context, jti string) (bool, error)
    Add(ctx context.Context, jti string, expiresAt time.Time) error
    RemoveExpired(ctx context.Context) error
}

// RefreshTokenGrantRepository リフレッシュトークン払い出し記録
type RefreshTokenGrantRepository interface {
    FindByJTI(ctx context.Context, jti string) (*RefreshTokenGrant, error)
    Save(ctx context.Context, grant *RefreshTokenGrant) error
    RevokeByUserID(ctx context.Context, userID string) error
}

// EventPublisher イベント発行
type EventPublisher interface {
    Publish(ctx context.Context, eventType string, payload map[string]interface{}) error
}

// Application Ports - External Service Interfaces
package ports

import "context"

// CognitoAuthProvider AWS Cognito 認証
type CognitoAuthProvider interface {
    InitiateAuth(ctx context.Context, email, password string) (*CognitoAuthResponse, error)
    GetUserAttributes(ctx context.Context, accessToken string) (*CognitoUserAttributes, error)
}

type CognitoAuthResponse struct {
    IDToken      string
    AccessToken  string
    RefreshToken string
    ExpiresIn    int
}

// PermissionServiceClient Permission Service (gRPC) 権限チェック
type PermissionServiceClient interface {
    CheckUserSuspended(ctx context.Context, userID string) (bool, error)
}

// TokenSigningProvider JWT トークン署名
type TokenSigningProvider interface {
    GenerateAccessToken(ctx context.Context, claims TokenClaims) (string, error)
    GenerateRefreshToken(ctx context.Context, userID, jti string) (string, error)
    VerifyAccessToken(ctx context.Context, token string) (*TokenClaims, error)
    VerifyRefreshToken(ctx context.Context, token string) (*TokenClaims, error)
}

// Mappers - Domain ↔ DTO conversion
package adapters

import "domain"
import "application"

// MapLoginInputToDomain HTTP request → Domain login context
func MapLoginInputToDomain(input *LoginInput) *domain.LoginContext {
    return &domain.LoginContext{
        Email:       input.Email,
        DeviceID:    input.DeviceID,
        Fingerprint: input.Fingerprint,
    }
}

// MapCognitoResponseToUser Cognito response → Domain User entity
func MapCognitoResponseToUser(cognitoAttrs *domain.CognitoUserAttributes) *domain.User {
    return &domain.User{
        CognitoSub: cognitoAttrs.Sub,
        Email:      cognitoAttrs.Email,
        CreatedAt:  time.Now(),
        UpdatedAt:  time.Now(),
    }
}

// MapUserSessionToOutput Domain session → HTTP response DTO
func MapUserSessionToOutput(session *domain.UserSession, accessToken, refreshToken string) *LoginOutput {
    return &LoginOutput{
        SessionID:    session.SessionID,
        AccessToken:  accessToken,
        RefreshToken: refreshToken,
        ExpiresIn:    3600,
        TokenType:    "Bearer",
    }
}

// Infrastructure - Dependency Injection (uber-go/fx)
package infrastructure

import (
    "context"
    "go.uber.org/fx"
    "database/sql"
    "github.com/redis/go-redis/v9"
    "github.com/gin-gonic/gin"
    "google.golang.org/grpc"
)

// Module provides all infrastructure dependencies
var Module = fx.Module("infrastructure",
    fx.Provide(
        // MySQL
        provideDatabaseConnection,

        // Redis
        provideRedisClient,

        // AWS Cognito (AuthPort)
        provideCognitoClient,

        // QueuePort (Beta: Redis+BullMQ/asynq, Prod: OCI Queue)
        provideQueueAdapter,

        // gRPC clients
        providePermissionServiceClient,

        // Repositories
        provideUserRepository,
        provideUserSessionRepository,
        provideDeviceRegistrationRepository,
        provideBlockedTokenRepository,
        provideRefreshTokenGrantRepository,

        // External Service Adapters
        provideCognitoAuthAdapter,
        providePermissionServiceAdapter,
        provideTokenSigningAdapter,

        // Event Publisher (QueuePort-backed)
        provideQueueEventPublisher,

        // Gin Engine
        provideGinEngine,

        // Controllers/Handlers
        provideLoginHandler,
        provideLogoutHandler,
        provideRefreshTokenHandler,
        provideSyncHandler,

        // Use Cases
        provideLoginUseCase,
        provideLogoutUseCase,
        provideRefreshTokenUseCase,
        provideRegisterDeviceUseCase,
        provideSyncCognitoUseCase,
        provideRevokeTokenUseCase,
    ),
)

func provideDatabaseConnection() (*sql.DB, error) {
    // go-sql-driver/mysql 用 DSN。Beta: XServer VPS 上の MySQL 8.x、Prod: OCI MySQL HeatWave
    return sql.Open("mysql", "user:pass@tcp(db:3306)/recuerdo?parseTime=true&charset=utf8mb4")
}

// provideQueueAdapter は QueuePort の実装を環境に応じて返す
func provideQueueAdapter(cfg *Config) (application.QueuePort, error) {
    switch cfg.Queue.Provider {
    case "redis-bullmq":
        return adapter.NewRedisBullMQAdapter(cfg.Queue.RedisAddr), nil
    case "oci-queue":
        return adapter.NewOCIQueueAdapter(cfg.Queue.OCIQueueID)
    default:
        return nil, fmt.Errorf("unknown queue provider: %s", cfg.Queue.Provider)
    }
}

func provideRedisClient() *redis.Client {
    return redis.NewClient(&redis.Options{
        Addr: "redis:6379",
    })
}

func provideGinEngine(
    loginHandler *LoginHandler,
    logoutHandler *LogoutHandler,
    refreshHandler *RefreshTokenHandler,
) *gin.Engine {
    engine := gin.Default()

    // Routes
    engine.POST("/api/auth/login", loginHandler.Handle)
    engine.POST("/api/auth/logout", logoutHandler.Handle)
    engine.POST("/api/auth/refresh", refreshHandler.Handle)
    engine.GET("/api/auth/sessions", sessionListHandler)
    engine.GET("/health", healthCheckHandler)

    return engine
}

func main() {
    app := fx.New(
        fx.Module("recerdo-auth",
            infrastructure.Module,
        ),
        fx.Invoke(startServer),
    )
    app.Run()
}

// Unit Tests - Login Use Case
package application

import (
    "context"
    "testing"
    "time"
    "github.com/stretchr/testify/assert"
    "github.com/stretchr/testify/mock"
)

// Test Case 1: Login - Successful authentication and session creation
func TestLogin_Success(t *testing.T) {
    // Arrange
    mockCognitoAuth := new(MockCognitoAuthProvider)
    mockUserRepo := new(MockUserRepository)
    mockSessionRepo := new(MockUserSessionRepository)
    mockDeviceRepo := new(MockDeviceRegistrationRepository)
    mockPermissionClient := new(MockPermissionServiceClient)
    mockTokenSigner := new(MockTokenSigningProvider)
    mockEventPublisher := new(MockEventPublisher)

    cognitoAttrs := &domain.CognitoUserAttributes{
        Sub:   "cognito-sub-123",
        Email: "user@example.com",
    }

    mockCognitoAuth.On("InitiateAuth", mock.Anything, "user@example.com", "password").
        Return(&domain.CognitoAuthResponse{
            IDToken:      "id-token",
            AccessToken:  "cognito-access-token",
            RefreshToken: "refresh-token",
            ExpiresIn:    3600,
        }, nil)

    mockCognitoAuth.On("GetUserAttributes", mock.Anything, "cognito-access-token").
        Return(cognitoAttrs, nil)

    mockUserRepo.On("FindByCognitoSub", mock.Anything, "cognito-sub-123").
        Return(&domain.User{
            UserID:     "user-123",
            CognitoSub: "cognito-sub-123",
            Email:      "user@example.com",
        }, nil)

    mockPermissionClient.On("CheckUserSuspended", mock.Anything, "user-123").
        Return(false, nil)

    mockDeviceRepo.On("FindByUserIDAndFingerprint", mock.Anything, "user-123", "fingerprint-xyz").
        Return(nil, nil) // New device

    mockDeviceRepo.On("Save", mock.Anything, mock.Anything).Return(nil)

    mockSessionRepo.On("Save", mock.Anything, mock.Anything).Return(nil)

    mockTokenSigner.On("GenerateAccessToken", mock.Anything, mock.Anything).
        Return("generated-access-token", nil)

    mockTokenSigner.On("GenerateRefreshToken", mock.Anything, "user-123", mock.Anything).
        Return("generated-refresh-token", nil)

    mockEventPublisher.On("Publish", mock.Anything, "auth.user_login", mock.Anything).
        Return(nil)

    useCase := NewLoginUseCase(
        mockCognitoAuth,
        mockUserRepo,
        mockSessionRepo,
        mockDeviceRepo,
        mockPermissionClient,
        mockTokenSigner,
        mockEventPublisher,
    )

    input := &LoginInput{
        Email:       "user@example.com",
        Password:    "password",
        DeviceID:    "device-456",
        Fingerprint: "fingerprint-xyz",
    }

    // Act
    output, err := useCase.Execute(context.Background(), input)

    // Assert
    assert.NoError(t, err)
    assert.Equal(t, "user-123", output.UserID)
    assert.Equal(t, "generated-access-token", output.AccessToken)
    assert.Equal(t, "generated-refresh-token", output.RefreshToken)
    assert.Equal(t, "Bearer", output.TokenType)
    assert.Equal(t, 3600, output.ExpiresIn)

    mockCognitoAuth.AssertCalled(t, "InitiateAuth", mock.Anything, "user@example.com", "password")
    mockPermissionClient.AssertCalled(t, "CheckUserSuspended", mock.Anything, "user-123")
    mockEventPublisher.AssertCalled(t, "Publish", mock.Anything, "auth.user_login", mock.Anything)
}

// Test Case 2: Login - User suspended
func TestLogin_UserSuspended(t *testing.T) {
    mockCognitoAuth := new(MockCognitoAuthProvider)
    mockUserRepo := new(MockUserRepository)
    mockPermissionClient := new(MockPermissionServiceClient)

    mockCognitoAuth.On("InitiateAuth", mock.Anything, "user@example.com", "password").
        Return(&domain.CognitoAuthResponse{IDToken: "id", AccessToken: "at", RefreshToken: "rt", ExpiresIn: 3600}, nil)

    mockCognitoAuth.On("GetUserAttributes", mock.Anything, "at").
        Return(&domain.CognitoUserAttributes{Sub: "sub-123", Email: "user@example.com"}, nil)

    mockUserRepo.On("FindByCognitoSub", mock.Anything, "sub-123").
        Return(&domain.User{UserID: "user-123", CognitoSub: "sub-123"}, nil)

    mockPermissionClient.On("CheckUserSuspended", mock.Anything, "user-123").
        Return(true, nil) // User is suspended

    useCase := NewLoginUseCase(
        mockCognitoAuth,
        mockUserRepo,
        nil,
        nil,
        mockPermissionClient,
        nil,
        nil,
    )

    input := &LoginInput{Email: "user@example.com", Password: "password"}

    // Act
    output, err := useCase.Execute(context.Background(), input)

    // Assert
    assert.Error(t, err)
    assert.Nil(t, output)
    assert.Contains(t, err.Error(), "suspended")
}

// Test Case 3: RefreshToken - Generate new access token
func TestRefreshToken_Success(t *testing.T) {
    mockTokenSigner := new(MockTokenSigningProvider)
    mockGrantRepo := new(MockRefreshTokenGrantRepository)
    mockSessionRepo := new(MockUserSessionRepository)

    claims := &domain.TokenClaims{
        Sub: "cognito-sub-123",
        Exp: time.Now().Add(30 * 24 * time.Hour).Unix(),
        Iat: time.Now().Unix(),
    }

    mockTokenSigner.On("VerifyRefreshToken", mock.Anything, "refresh-token").
        Return(claims, nil)

    grant := &domain.RefreshTokenGrant{
        GrantID:   "grant-1",
        UserID:    "user-123",
        JTI:       "jti-refresh",
        ExpiresAt: time.Now().Add(30 * 24 * time.Hour),
        RevokedAt: nil,
    }

    mockGrantRepo.On("FindByJTI", mock.Anything, "jti-refresh").Return(grant, nil)

    mockTokenSigner.On("GenerateAccessToken", mock.Anything, mock.MatchedBy(func(c domain.TokenClaims) bool {
        return c.Sub == "cognito-sub-123"
    })).Return("new-access-token", nil)

    useCase := NewRefreshTokenUseCase(mockTokenSigner, mockGrantRepo, mockSessionRepo)

    input := &RefreshTokenInput{RefreshToken: "refresh-token"}

    // Act
    output, err := useCase.Execute(context.Background(), input)

    // Assert
    assert.NoError(t, err)
    assert.Equal(t, "new-access-token", output.AccessToken)
    assert.Equal(t, 3600, output.ExpiresIn)
    assert.Equal(t, "Bearer", output.TokenType)

    mockTokenSigner.AssertCalled(t, "VerifyRefreshToken", mock.Anything, "refresh-token")
    mockGrantRepo.AssertCalled(t, "FindByJTI", mock.Anything, "jti-refresh")
}

// Integration Test: MySQL UserRepository
func TestMySQLUserRepository_Integration(t *testing.T) {
    // Setup testcontainers
    ctx := context.Background()
    container, dbURL, err := setupMySQLContainer(ctx)
    assert.NoError(t, err)
    defer container.Terminate(ctx)

    db, err := sql.Open("MySQL", dbURL)
    assert.NoError(t, err)
    defer db.Close()

    repo := NewMySQLUserRepository(db)

    // Create user
    user := &domain.User{
        UserID:     "user-123",
        CognitoSub: "cognito-sub-456",
        Email:      "test@example.com",
        CreatedAt:  time.Now(),
        UpdatedAt:  time.Now(),
    }

    // Act: Save
    err = repo.Save(ctx, user)
    assert.NoError(t, err)

    // Act: FindByCognitoSub
    retrieved, err := repo.FindByCognitoSub(ctx, "cognito-sub-456")
    assert.NoError(t, err)
    assert.NotNil(t, retrieved)
    assert.Equal(t, "test@example.com", retrieved.Email)
}