@nakedev/go-scaffold 0.5.1 → 0.5.3

package/templates/add/auth/internal/app/user/adapters/outbound/postgres/mfa_store.go.hbs

@@ -92,7 +92,7 @@ func (s *PostgresMFAStore) CreateChallenge(ctx context.Context, hash string, cha
 	if hash == "" || challenge.UserID == uuid.Nil || !challenge.ExpiresAt.After(time.Now()) {
 		return fmt.Errorf("MFA challenge is invalid")
 	}
-	row := MFAChallenge{ChallengeHash: hash, UserID: challenge.UserID, ExpiresAt: challenge.ExpiresAt}
+	row := MFAChallenge{ChallengeHash: hash, UserID: challenge.UserID, SessionID: challenge.SessionID, UserAgent: challenge.UserAgent, ExpiresAt: challenge.ExpiresAt}
 	return tx.From(ctx, s.db).WithContext(ctx).Create(&row).Error
 }
 
@@ -101,8 +101,8 @@ func (s *PostgresMFAStore) ConsumeChallenge(ctx context.Context, hash string) (p
 	err := tx.From(ctx, s.db).WithContext(ctx).Raw(
 		`DELETE FROM user_svc.mfa_challenges
 		 WHERE challenge_hash = ? AND expires_at > now()
-		 RETURNING user_id, expires_at`, hash,
-	).Row().Scan(&challenge.UserID, &challenge.ExpiresAt)
+		 RETURNING user_id, session_id, user_agent, expires_at`, hash,
+	).Row().Scan(&challenge.UserID, &challenge.SessionID, &challenge.UserAgent, &challenge.ExpiresAt)
 	if errors.Is(err, sql.ErrNoRows) {
 		return ports.MFAChallenge{}, false, nil
 	}

package/templates/add/auth/internal/app/user/adapters/outbound/postgres/model.go.hbs

@@ -37,12 +37,15 @@ type AuthToken struct {
 	TokenHash         string     `gorm:"primaryKey;type:text"`
 	UserID            uuid.UUID  `gorm:"type:uuid;not null;index:idx_auth_tokens_user_kind,priority:1"`
 	Kind              string     `gorm:"type:varchar(20);not null;index:idx_auth_tokens_user_kind,priority:2"`
+	SessionID         uuid.UUID  `gorm:"type:uuid;not null;index:idx_auth_tokens_user_session,priority:1"`
+	UserAgent         string     `gorm:"type:text;not null;default:''"`
 	ExpiresAt         time.Time  `gorm:"not null;index:idx_auth_tokens_expires_at"`
 	AbsoluteExpiresAt *time.Time `gorm:"index:idx_auth_tokens_absolute_expires_at"`
 	Provider          string     `gorm:"type:varchar(20);not null;default:''"`
 	CodeChallenge     string     `gorm:"type:text;not null;default:''"`
 	Nonce             string     `gorm:"type:text;not null;default:''"`
-	CreatedAt         time.Time
+	CreatedAt         time.Time  `gorm:"not null"`
+	LastUsedAt        time.Time  `gorm:"not null;index:idx_auth_tokens_user_session,priority:3"`
 }
 
 func (AuthToken) TableName() string { return "user_svc.auth_tokens" }
@@ -69,6 +72,8 @@ func (MFAEnrollment) TableName() string { return "user_svc.mfa_enrollments" }
 type MFAChallenge struct {
 	ChallengeHash string    `gorm:"type:text;primaryKey"`
 	UserID        uuid.UUID `gorm:"type:uuid;not null;index:idx_mfa_challenges_user"`
+	SessionID     uuid.UUID `gorm:"type:uuid;not null;default:'00000000-0000-0000-0000-000000000000'"`
+	UserAgent     string    `gorm:"type:text;not null;default:''"`
 	ExpiresAt     time.Time `gorm:"not null;index:idx_mfa_challenges_expires_at"`
 	CreatedAt     time.Time
 }

package/templates/add/auth/internal/app/user/adapters/outbound/postgres/repository.go.hbs

@@ -12,6 +12,7 @@ import (
 
 	"github.com/google/uuid"
 	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
 )
 
 type Repository struct {
@@ -68,6 +69,20 @@ func (r *Repository) FindIdentity(ctx context.Context, userID uuid.UUID, provide
 	return toDomainIdentity(&row), nil
 }
 
+func (r *Repository) ListIdentities(ctx context.Context, userID uuid.UUID) ([]domain.Identity, error) {
+	var rows []Identity
+	if err := tx.From(ctx, r.db).WithContext(ctx).
+		Where("user_id = ?", userID).
+		Order("created_at ASC, id ASC").Find(&rows).Error; err != nil {
+		return nil, persistenceError(err)
+	}
+	items := make([]domain.Identity, len(rows))
+	for i := range rows {
+		items[i] = *toDomainIdentity(&rows[i])
+	}
+	return items, nil
+}
+
 func (r *Repository) FindIdentityByProviderUID(ctx context.Context, provider domain.Provider, providerUID string) (*domain.Identity, error) {
 	var row Identity
 	if err := tx.From(ctx, r.db).WithContext(ctx).
@@ -88,6 +103,34 @@ func (r *Repository) UpdateIdentity(ctx context.Context, identity *domain.Identi
 	return persistenceError(tx.From(ctx, r.db).WithContext(ctx).Save(&row).Error)
 }
 
+// DeleteIdentity locks the user's identity rows before checking the count so
+// two concurrent unlink requests cannot both remove the last login method.
+func (r *Repository) DeleteIdentity(ctx context.Context, userID uuid.UUID, provider domain.Provider) error {
+	return persistenceError(tx.From(ctx, r.db).WithContext(ctx).Transaction(func(db *gorm.DB) error {
+		var rows []Identity
+		if err := db.Clauses(clause.Locking{Strength: "UPDATE"}).
+			Where("user_id = ?", userID).
+			Order("created_at ASC, id ASC").Find(&rows).Error; err != nil {
+			return err
+		}
+
+		var target *Identity
+		for i := range rows {
+			if rows[i].Provider == string(provider) {
+				target = &rows[i]
+				break
+			}
+		}
+		if target == nil {
+			return domain.ErrNotFound
+		}
+		if len(rows) <= 1 {
+			return domain.ErrLastIdentity
+		}
+		return db.Delete(&Identity{}, "id = ? AND user_id = ?", target.ID, userID).Error
+	}))
+}
+
 // CreateUserWithIdentity inserts the profile and its first login method in
 // one transaction. A user without an identity cannot authenticate.
 func (r *Repository) CreateUserWithIdentity(ctx context.Context, user *domain.User, identity *domain.Identity) error {

package/templates/add/auth/internal/app/user/adapters/outbound/postgres/tokenstore_pg.go.hbs

@@ -66,16 +66,23 @@ func (s *PgTokenStore) SetRefreshToken(ctx context.Context, tokenHash string, to
 		TokenHash:         tokenHash,
 		UserID:            token.UserID,
 		Kind:              kindRefresh,
+		SessionID:         token.SessionID,
+		UserAgent:         token.UserAgent,
 		ExpiresAt:         token.ExpiresAt,
 		AbsoluteExpiresAt: &token.AbsoluteExpiresAt,
+		CreatedAt:         token.CreatedAt,
+		LastUsedAt:        token.LastUsedAt,
 	}
 	return tx.From(ctx, s.db).WithContext(ctx).
 		Where("token_hash = ?", tokenHash).
 		Assign(map[string]any{
 			"user_id":             token.UserID,
 			"kind":                kindRefresh,
+			"session_id":          token.SessionID,
+			"user_agent":          token.UserAgent,
 			"expires_at":          token.ExpiresAt,
 			"absolute_expires_at": token.AbsoluteExpiresAt,
+			"last_used_at":        token.LastUsedAt,
 			"provider":            "",
 			"code_challenge":      "",
 			"nonce":               "",
@@ -96,12 +103,15 @@ func (s *PgTokenStore) ConsumeRefreshToken(ctx context.Context, tokenHash string
 			DELETE FROM user_svc.auth_tokens
 				 WHERE token_hash = ? AND kind = ? AND expires_at > now()
 				   AND (absolute_expires_at IS NULL OR absolute_expires_at > now())
-				 RETURNING user_id, expires_at, absolute_expires_at
+			RETURNING user_id, session_id, user_agent, created_at, last_used_at, expires_at, absolute_expires_at
 		)
-		INSERT INTO user_svc.auth_tokens (token_hash, user_id, kind, expires_at, absolute_expires_at)
-		SELECT ?, user_id, ?, expires_at, COALESCE(absolute_expires_at, expires_at) FROM consumed
-		RETURNING user_id, expires_at, absolute_expires_at`,
-		tokenHash, kindRefresh, tokenHash, kindRefreshUsed).Row().Scan(&token.UserID, &token.ExpiresAt, &token.AbsoluteExpiresAt)
+		INSERT INTO user_svc.auth_tokens (token_hash, user_id, kind, session_id, user_agent, expires_at, absolute_expires_at, created_at, last_used_at)
+		SELECT ?, user_id, ?, session_id, user_agent, expires_at, COALESCE(absolute_expires_at, expires_at), created_at, last_used_at FROM consumed
+		RETURNING user_id, session_id, user_agent, created_at, last_used_at, expires_at, absolute_expires_at`,
+		tokenHash, kindRefresh, tokenHash, kindRefreshUsed).Row().Scan(
+		&token.UserID, &token.SessionID, &token.UserAgent, &token.CreatedAt, &token.LastUsedAt,
+		&token.ExpiresAt, &token.AbsoluteExpiresAt,
+	)
 	if errors.Is(err, sql.ErrNoRows) {
 		return ports.RefreshTokenRecord{}, false, nil
 	}
@@ -129,6 +139,33 @@ func (s *PgTokenStore) RevokeAllRefreshTokens(ctx context.Context, userID uuid.U
 		Delete(&AuthToken{}).Error
 }
 
+func (s *PgTokenStore) ListRefreshSessions(ctx context.Context, userID uuid.UUID) ([]ports.RefreshSession, error) {
+	var rows []AuthToken
+	err := tx.From(ctx, s.db).WithContext(ctx).
+		Where("user_id = ? AND kind = ? AND expires_at > now() AND (absolute_expires_at IS NULL OR absolute_expires_at > now())", userID, kindRefresh).
+		Order("last_used_at DESC, created_at DESC").Find(&rows).Error
+	if err != nil {
+		return nil, err
+	}
+	out := make([]ports.RefreshSession, 0, len(rows))
+	for _, row := range rows {
+		out = append(out, ports.RefreshSession{
+			ID: row.SessionID, UserAgent: row.UserAgent, CreatedAt: row.CreatedAt,
+			LastUsedAt: row.LastUsedAt, ExpiresAt: row.ExpiresAt,
+		})
+	}
+	return out, nil
+}
+
+func (s *PgTokenStore) RevokeRefreshSession(ctx context.Context, userID, sessionID uuid.UUID) error {
+	if userID == uuid.Nil || sessionID == uuid.Nil {
+		return fmt.Errorf("session identity is invalid")
+	}
+	return tx.From(ctx, s.db).WithContext(ctx).
+		Where("user_id = ? AND kind = ? AND session_id = ?", userID, kindRefresh, sessionID).
+		Delete(&AuthToken{}).Error
+}
+
 func (s *PgTokenStore) IsRefreshTokenUsed(ctx context.Context, tokenHash string) (uuid.UUID, bool, error) {
 	return s.lookup(ctx, tokenHash, kindRefreshUsed)
 }
@@ -139,6 +176,7 @@ func (s *PgTokenStore) SetLoginTransaction(ctx context.Context, stateHash string
 	}
 	row := AuthToken{
 		TokenHash:     stateHash,
+		UserID:        transaction.UserID,
 		Kind:          kindOAuthState,
 		ExpiresAt:     transaction.ExpiresAt,
 		Provider:      transaction.Provider,
@@ -148,7 +186,7 @@ func (s *PgTokenStore) SetLoginTransaction(ctx context.Context, stateHash string
 	return tx.From(ctx, s.db).WithContext(ctx).
 		Where("token_hash = ?", stateHash).
 		Assign(map[string]any{
-			"user_id":        uuid.Nil,
+			"user_id":        transaction.UserID,
 			"kind":           kindOAuthState,
 			"expires_at":     transaction.ExpiresAt,
 			"provider":       transaction.Provider,
@@ -162,8 +200,9 @@ func (s *PgTokenStore) ConsumeLoginTransaction(ctx context.Context, stateHash st
 	err := tx.From(ctx, s.db).WithContext(ctx).Raw(
 		`DELETE FROM user_svc.auth_tokens
 		 WHERE token_hash = ? AND kind = ? AND expires_at > now()
-		 RETURNING provider, code_challenge, nonce, expires_at`,
+		 RETURNING user_id, provider, code_challenge, nonce, expires_at`,
 		stateHash, kindOAuthState).Row().Scan(
+		&transaction.UserID,
 		&transaction.Provider,
 		&transaction.CodeChallenge,
 		&transaction.Nonce,

package/templates/add/auth/internal/app/user/adapters/outbound/postgres/tokenstore_pg_test.go.hbs

@@ -101,3 +101,39 @@ func refreshTokenRecordForTest(userID uuid.UUID) ports.RefreshTokenRecord {
 	now := time.Now()
 	return ports.RefreshTokenRecord{UserID: userID, ExpiresAt: now.Add(time.Hour), AbsoluteExpiresAt: now.Add(24 * time.Hour)}
 }
+
+func TestPgTokenStore_ListAndRevokeRefreshSessions(t *testing.T) {
+	db := tokenStoreDBForTest(t)
+	store := NewPgTokenStore(db)
+	ctx := context.Background()
+	userID := uuid.New()
+	currentID := uuid.New()
+	remoteID := uuid.New()
+	now := time.Now()
+	hashes := []string{"real-pg-session-current-" + uuid.NewString(), "real-pg-session-remote-" + uuid.NewString()}
+	for i, sessionID := range []uuid.UUID{currentID, remoteID} {
+		if err := store.SetRefreshToken(ctx, hashes[i], ports.RefreshTokenRecord{
+			UserID: userID, SessionID: sessionID, UserAgent: "test-device",
+			CreatedAt: now.Add(-time.Hour), LastUsedAt: now.Add(-time.Duration(i) * time.Minute),
+			ExpiresAt: now.Add(time.Hour), AbsoluteExpiresAt: now.Add(24 * time.Hour),
+		}); err != nil {
+			t.Fatalf("seed session %d: %v", i, err)
+		}
+	}
+	t.Cleanup(func() { _ = db.Exec("DELETE FROM user_svc.auth_tokens WHERE token_hash IN ?", hashes).Error })
+
+	sessions, err := store.ListRefreshSessions(ctx, userID)
+	if err != nil || len(sessions) != 2 {
+		t.Fatalf("list sessions = %+v, err=%v", sessions, err)
+	}
+	if sessions[0].ID != currentID || sessions[0].UserAgent != "test-device" {
+		t.Fatalf("sessions were not ordered/decoded correctly: %+v", sessions)
+	}
+	if err := store.RevokeRefreshSession(ctx, userID, remoteID); err != nil {
+		t.Fatalf("revoke session: %v", err)
+	}
+	sessions, err = store.ListRefreshSessions(ctx, userID)
+	if err != nil || len(sessions) != 1 || sessions[0].ID != currentID {
+		t.Fatalf("sessions after revoke = %+v, err=%v", sessions, err)
+	}
+}

package/templates/add/auth/internal/app/user/adapters/outbound/redis/tokenstore.go.hbs

@@ -76,6 +76,48 @@ redis.call("DEL", KEYS[1])
 return #hashes
 `)
 
+var listRefreshSessionsScript = redis.NewScript(`
+local sessions = {}
+local hashes = redis.call("SMEMBERS", KEYS[1])
+for _, hash in ipairs(hashes) do
+  local key = KEYS[2] .. hash
+  local raw = redis.call("GET", key)
+  local ttl = redis.call("PTTL", key)
+  if not raw or ttl < 1 then
+    redis.call("SREM", KEYS[1], hash)
+  else
+    local decoded, token_data = pcall(cjson.decode, raw)
+    if decoded and type(token_data) == "table" and token_data.user_id == ARGV[1] and
+       type(token_data.session_id) == "string" and token_data.session_id ~= "" then
+      table.insert(sessions, token_data)
+    elseif not decoded or type(token_data) ~= "table" or token_data.user_id ~= ARGV[1] then
+      redis.call("SREM", KEYS[1], hash)
+    end
+  end
+end
+return cjson.encode(sessions)
+`)
+
+var revokeRefreshSessionScript = redis.NewScript(`
+local hashes = redis.call("SMEMBERS", KEYS[1])
+local revoked = 0
+for _, hash in ipairs(hashes) do
+  local key = KEYS[2] .. hash
+  local raw = redis.call("GET", key)
+  if raw then
+    local decoded, token_data = pcall(cjson.decode, raw)
+    if decoded and type(token_data) == "table" and token_data.user_id == ARGV[1] and token_data.session_id == ARGV[2] then
+      redis.call("DEL", key)
+      redis.call("SREM", KEYS[1], hash)
+      revoked = revoked + 1
+    end
+  else
+    redis.call("SREM", KEYS[1], hash)
+  end
+end
+return revoked
+`)
+
 func (s *RedisTokenStore) SetRefreshToken(ctx context.Context, tokenHash string, token ports.RefreshTokenRecord) error {
 	ttl := time.Until(token.ExpiresAt)
 	if token.UserID == uuid.Nil || ttl <= 0 || token.AbsoluteExpiresAt.IsZero() || token.AbsoluteExpiresAt.Before(token.ExpiresAt) {
@@ -151,6 +193,39 @@ func (s *RedisTokenStore) RevokeAllRefreshTokens(ctx context.Context, userID uui
 	return err
 }
 
+func (s *RedisTokenStore) ListRefreshSessions(ctx context.Context, userID uuid.UUID) ([]ports.RefreshSession, error) {
+	result, err := listRefreshSessionsScript.Run(ctx, s.rdb,
+		[]string{refreshUserKeyPrefix + userID.String(), refreshKeyPrefix}, userID.String()).Result()
+	if err != nil {
+		return nil, err
+	}
+	raw, ok := result.(string)
+	if !ok || raw == "" {
+		return []ports.RefreshSession{}, nil
+	}
+	var tokens []ports.RefreshTokenRecord
+	if err := json.Unmarshal([]byte(raw), &tokens); err != nil {
+		return nil, fmt.Errorf("decode refresh sessions: %w", err)
+	}
+	out := make([]ports.RefreshSession, 0, len(tokens))
+	for _, token := range tokens {
+		out = append(out, ports.RefreshSession{
+			ID: token.SessionID, UserAgent: token.UserAgent, CreatedAt: token.CreatedAt,
+			LastUsedAt: token.LastUsedAt, ExpiresAt: token.ExpiresAt,
+		})
+	}
+	return out, nil
+}
+
+func (s *RedisTokenStore) RevokeRefreshSession(ctx context.Context, userID, sessionID uuid.UUID) error {
+	if userID == uuid.Nil || sessionID == uuid.Nil {
+		return fmt.Errorf("session identity is invalid")
+	}
+	_, err := revokeRefreshSessionScript.Run(ctx, s.rdb,
+		[]string{refreshUserKeyPrefix + userID.String(), refreshKeyPrefix}, userID.String(), sessionID.String()).Result()
+	return err
+}
+
 func (s *RedisTokenStore) IsRefreshTokenUsed(ctx context.Context, tokenHash string) (uuid.UUID, bool, error) {
 	raw, err := s.rdb.Get(ctx, refreshUsedKeyPrefix+tokenHash).Result()
 	if err == redis.Nil {

package/templates/add/auth/internal/app/user/adapters/outbound/redis/tokenstore_test.go.hbs

@@ -70,6 +70,42 @@ func TestRefreshTokenRecord_JSONUsesLuaFieldNames(t *testing.T) {
 	}
 }
 
+func TestRedisTokenStore_ListAndRevokeRefreshSessions(t *testing.T) {
+	client := redisClientForTest(t)
+	store := NewRedisTokenStore(client, nil)
+	ctx := context.Background()
+	userID := uuid.New()
+	currentID := uuid.New()
+	remoteID := uuid.New()
+	current := testRefreshTokenRecord(userID)
+	current.SessionID = currentID
+	current.UserAgent = "current-device"
+	remote := testRefreshTokenRecord(userID)
+	remote.SessionID = remoteID
+	remote.UserAgent = "remote-device"
+	currentHash := "real-redis-session-current-" + uuid.NewString()
+	remoteHash := "real-redis-session-remote-" + uuid.NewString()
+	if err := store.SetRefreshToken(ctx, currentHash, current); err != nil {
+		t.Fatalf("seed current session: %v", err)
+	}
+	if err := store.SetRefreshToken(ctx, remoteHash, remote); err != nil {
+		t.Fatalf("seed remote session: %v", err)
+	}
+	t.Cleanup(func() { _ = store.RevokeAllRefreshTokens(ctx, userID) })
+
+	sessions, err := store.ListRefreshSessions(ctx, userID)
+	if err != nil || len(sessions) != 2 {
+		t.Fatalf("list sessions = %+v, err=%v", sessions, err)
+	}
+	if err := store.RevokeRefreshSession(ctx, userID, remoteID); err != nil {
+		t.Fatalf("revoke session: %v", err)
+	}
+	sessions, err = store.ListRefreshSessions(ctx, userID)
+	if err != nil || len(sessions) != 1 || sessions[0].ID != currentID {
+		t.Fatalf("sessions after revoke = %+v, err=%v", sessions, err)
+	}
+}
+
 func TestRedisTokenStore_ConsumeRefreshToken_ConcurrentRealRedis(t *testing.T) {
 	client := redisClientForTest(t)
 	store := NewRedisTokenStore(client, nil)

package/templates/add/auth/internal/app/user/application/dto.go.hbs

@@ -12,17 +12,49 @@ type RegisterInput struct {
 	Email    string
 	Password string
 	Name     string
+	Session  SessionContext
 }
 
 type LoginInput struct {
 	Email    string
 	Password string
+	Session  SessionContext
 }
 
 type LoginExchangeInput struct {
 	Code         string
 	State        string
 	CodeVerifier string
+	Session      SessionContext
+}
+
+type SessionContext struct {
+	ID        uuid.UUID
+	UserAgent string
+	CreatedAt time.Time
+}
+
+type Session struct {
+	ID         uuid.UUID
+	UserAgent  string
+	CreatedAt  time.Time
+	LastUsedAt time.Time
+	ExpiresAt  time.Time
+	Current    bool
+}
+
+// IdentityResponse is the safe public view of a login identity. Provider
+// subjects and password hashes never cross the application/HTTP boundary.
+type IdentityResponse struct {
+	ID        uuid.UUID
+	Provider  string
+	CreatedAt time.Time
+}
+
+func ToIdentityResponse(identity domain.Identity) IdentityResponse {
+	return IdentityResponse{
+		ID: identity.ID, Provider: string(identity.Provider), CreatedAt: identity.CreatedAt,
+	}
 }
 
 type AuthResponse struct {

package/templates/add/auth/internal/app/user/application/errors.go.hbs

@@ -60,3 +60,19 @@ func errMFAConfig() error {
 func errUnknownRole() error {
 	return domain.Rule("USER_UNKNOWN_ROLE", "unknown role code", domain.ErrUnknownRole)
 }
+
+func errIdentityAlreadyLinked() error {
+	return domain.Rule("AUTH_IDENTITY_ALREADY_LINKED", "this login method is already linked", domain.ErrIdentityAlreadyLinked)
+}
+
+func errIdentityConflict() error {
+	return domain.Rule("AUTH_IDENTITY_CONFLICT", "this provider account is linked to another user", domain.ErrConflict)
+}
+
+func errIdentityNotFound() error {
+	return domain.Rule("AUTH_IDENTITY_NOT_FOUND", "login method not found", domain.ErrNotFound)
+}
+
+func errLastIdentity() error {
+	return domain.Rule("AUTH_LAST_IDENTITY", "you cannot remove your last login method", domain.ErrLastIdentity)
+}

package/templates/add/auth/internal/app/user/application/external_login.go.hbs

@@ -12,6 +12,8 @@ import (
 
 	"{{goModule}}/internal/app/user/domain"
 	"{{goModule}}/internal/shared/id"
+
+	"github.com/google/uuid"
 )
 
 // BeginLogin accepts the browser client's state and S256 PKCE challenge and
@@ -19,6 +21,21 @@ import (
 // The server persists a hashed state transaction binding provider, challenge,
 // and OIDC nonce before the callback reaches ExchangeLogin.
 func (s *Service) BeginLogin(ctx context.Context, providerName string, in LoginStartInput) (*Authorization, error) {
+	return s.beginProviderLogin(ctx, providerName, in, uuid.Nil)
+}
+
+// BeginIdentityLink starts an OAuth transaction that is bound to the
+// authenticated user. It is deliberately separate from BeginLogin: the
+// public login flow may resolve any user, while a link flow must never be
+// allowed to attach an identity to whichever account the provider returns.
+func (s *Service) BeginIdentityLink(ctx context.Context, userID uuid.UUID, providerName string, in LoginStartInput) (*Authorization, error) {
+	if userID == uuid.Nil {
+		return nil, NewOAuthError(OAuthStateInvalid, fmt.Errorf("authenticated user is required to link an identity"))
+	}
+	return s.beginProviderLogin(ctx, providerName, in, userID)
+}
+
+func (s *Service) beginProviderLogin(ctx context.Context, providerName string, in LoginStartInput, userID uuid.UUID) (*Authorization, error) {
 	provider, ok := s.providers.Lookup(providerName)
 	if !ok {
 		return nil, NewOAuthError(OAuthProviderUnavailable, fmt.Errorf("provider %q is not configured", providerName))
@@ -46,6 +63,7 @@ func (s *Service) BeginLogin(ctx context.Context, providerName string, in LoginS
 	}
 	if err := s.oauthTransactions.SetLoginTransaction(ctx, hashToken(in.State), LoginTransaction{
 		Provider:      providerName,
+		UserID:        userID,
 		CodeChallenge: in.CodeChallenge,
 		Nonce:         nonce,
 		ExpiresAt:     clock().Add(s.config.OAuthStateTTL),
@@ -56,37 +74,48 @@ func (s *Service) BeginLogin(ctx context.Context, providerName string, in LoginS
 }
 
 func (s *Service) ExchangeLogin(ctx context.Context, providerName string, in LoginExchangeInput) (*AuthResult, error) {
+	identity, err := s.exchangeExternalIdentity(ctx, providerName, in, uuid.Nil)
+	if err != nil {
+		return nil, err
+	}
+	u, err := s.findOrCreateExternalUser(ctx, identity)
+	if err != nil {
+		return nil, NewOAuthError(OAuthFailed, fmt.Errorf("resolve external identity: %w", err))
+	}
+	return s.completeLogin(ctx, u, in.Session)
+}
+
+// exchangeExternalIdentity consumes the one-time transaction before asking
+// the provider to complete the code exchange. The transaction's UserID is
+// zero for public login and is the authenticated caller for identity linking.
+func (s *Service) exchangeExternalIdentity(ctx context.Context, providerName string, in LoginExchangeInput, userID uuid.UUID) (ExternalIdentity, error) {
 	provider, ok := s.providers.Lookup(providerName)
 	if !ok {
-		return nil, NewOAuthError(OAuthProviderUnavailable, fmt.Errorf("provider %q is not configured", providerName))
+		return ExternalIdentity{}, NewOAuthError(OAuthProviderUnavailable, fmt.Errorf("provider %q is not configured", providerName))
 	}
 	if !validOAuthValue(in.State) || !validPKCEValue(in.CodeVerifier) {
-		return nil, NewOAuthError(OAuthStateInvalid, fmt.Errorf("state and code verifier are required"))
+		return ExternalIdentity{}, NewOAuthError(OAuthStateInvalid, fmt.Errorf("state and code verifier are required"))
 	}
 	if !validOAuthValue(in.Code) {
-		return nil, NewOAuthError(OAuthFailed, fmt.Errorf("authorization code is missing"))
+		return ExternalIdentity{}, NewOAuthError(OAuthFailed, fmt.Errorf("authorization code is missing"))
 	}
 
 	transaction, ok, err := s.oauthTransactions.ConsumeLoginTransaction(ctx, hashToken(in.State))
 	if err != nil {
-		return nil, NewOAuthError(OAuthProviderUnavailable, fmt.Errorf("consume oauth transaction: %w", err))
+		return ExternalIdentity{}, NewOAuthError(OAuthProviderUnavailable, fmt.Errorf("consume oauth transaction: %w", err))
 	}
-	if !ok || transaction.Provider != providerName || !validPKCEVerifier(in.CodeVerifier, transaction.CodeChallenge) {
-		return nil, NewOAuthError(OAuthStateInvalid, fmt.Errorf("oauth state or PKCE verifier is invalid"))
+	if !ok || transaction.Provider != providerName || transaction.UserID != userID || !validPKCEVerifier(in.CodeVerifier, transaction.CodeChallenge) {
+		return ExternalIdentity{}, NewOAuthError(OAuthStateInvalid, fmt.Errorf("oauth state or PKCE verifier is invalid"))
 	}
 
 	identity, err := provider.Complete(ctx, LoginCompleteInput{Code: in.Code, CodeVerifier: in.CodeVerifier, Nonce: transaction.Nonce})
 	if err != nil {
-		return nil, mapProviderError(err)
+		return ExternalIdentity{}, mapProviderError(err)
 	}
 	if identity.Provider != providerName {
-		return nil, NewOAuthError(OAuthFailed, fmt.Errorf("provider identity name does not match the requested provider"))
-	}
-	u, err := s.findOrCreateExternalUser(ctx, identity)
-	if err != nil {
-		return nil, NewOAuthError(OAuthFailed, fmt.Errorf("resolve external identity: %w", err))
+		return ExternalIdentity{}, NewOAuthError(OAuthFailed, fmt.Errorf("provider identity name does not match the requested provider"))
 	}
-	return s.completeLogin(ctx, u)
+	return identity, nil
 }
 
 func validPKCEVerifier(verifier, challenge string) bool {

package/templates/add/auth/internal/app/user/application/identities.go.hbs

@@ -0,0 +1,97 @@
+package application
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+
+	"{{goModule}}/internal/app/user/domain"
+
+	"github.com/google/uuid"
+)
+
+func (s *Service) ListIdentities(ctx context.Context, userID uuid.UUID) ([]IdentityResponse, error) {
+	items, err := s.repo.ListIdentities(ctx, userID)
+	if err != nil {
+		return nil, fmt.Errorf("list login identities: %w", err)
+	}
+
+	out := make([]IdentityResponse, len(items))
+	for i := range items {
+		out[i] = ToIdentityResponse(items[i])
+	}
+	return out, nil
+}
+
+func (s *Service) ExchangeIdentityLink(ctx context.Context, userID uuid.UUID, providerName string, in LoginExchangeInput) (*IdentityResponse, error) {
+	if userID == uuid.Nil {
+		return nil, NewOAuthError(OAuthStateInvalid, fmt.Errorf("authenticated user is required to link an identity"))
+	}
+
+	identity, err := s.exchangeExternalIdentity(ctx, providerName, in, userID)
+	if err != nil {
+		return nil, err
+	}
+	return s.linkExternalIdentity(ctx, userID, identity)
+}
+
+func (s *Service) linkExternalIdentity(ctx context.Context, userID uuid.UUID, info ExternalIdentity) (*IdentityResponse, error) {
+	provider := domain.Provider(strings.TrimSpace(info.Provider))
+	if userID == uuid.Nil || provider == "" || strings.TrimSpace(info.Subject) == "" {
+		return nil, NewOAuthError(OAuthFailed, fmt.Errorf("external identity is incomplete"))
+	}
+
+	// Replaying the same provider account from the same user is idempotent.
+	// A provider subject already owned by another user is a conflict and must
+	// never be silently moved between accounts.
+	if existing, err := s.repo.FindIdentityByProviderUID(ctx, provider, info.Subject); err == nil {
+		if existing.UserID != userID {
+			return nil, errIdentityConflict()
+		}
+		out := ToIdentityResponse(*existing)
+		return &out, nil
+	} else if !errors.Is(err, domain.ErrNotFound) {
+		return nil, fmt.Errorf("find linked identity: %w", err)
+	}
+
+	// The database permits one identity per provider for each user. Return a
+	// controlled conflict instead of exposing a persistence duplicate error.
+	if _, err := s.repo.FindIdentity(ctx, userID, provider); err == nil {
+		return nil, errIdentityAlreadyLinked()
+	} else if !errors.Is(err, domain.ErrNotFound) {
+		return nil, fmt.Errorf("check existing provider identity: %w", err)
+	}
+
+	providerUID := info.Subject
+	identity := &domain.Identity{
+		ID: uuid.New(), UserID: userID, Provider: provider, ProviderUID: &providerUID,
+	}
+	if err := s.repo.CreateIdentity(ctx, identity); err != nil {
+		if errors.Is(err, domain.ErrConflict) {
+			return nil, errIdentityAlreadyLinked()
+		}
+		return nil, fmt.Errorf("link identity: %w", err)
+	}
+
+	out := ToIdentityResponse(*identity)
+	return &out, nil
+}
+
+func (s *Service) UnlinkIdentity(ctx context.Context, userID uuid.UUID, providerName string) error {
+	provider := domain.Provider(strings.TrimSpace(providerName))
+	if userID == uuid.Nil || provider == "" {
+		return errIdentityNotFound()
+	}
+	if err := s.repo.DeleteIdentity(ctx, userID, provider); err != nil {
+		switch {
+		case errors.Is(err, domain.ErrLastIdentity):
+			return errLastIdentity()
+		case errors.Is(err, domain.ErrNotFound):
+			return errIdentityNotFound()
+		default:
+			return fmt.Errorf("unlink identity: %w", err)
+		}
+	}
+	return nil
+}