@nakedev/go-scaffold 0.5.1 → 0.5.3

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

@@ -0,0 +1,69 @@
+package application
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"{{goModule}}/internal/app/user/domain"
+
+	"github.com/google/uuid"
+)
+
+func TestService_IdentityLinkBindsOAuthTransactionToCaller(t *testing.T) {
+	provider, svc := validFakeProvider(t)
+	userID := uuid.New()
+	otherUserID := uuid.New()
+
+	if _, err := svc.BeginIdentityLink(context.Background(), userID, provider.Name(), validLoginStart()); err != nil {
+		t.Fatalf("begin identity link: %v", err)
+	}
+
+	_, err := svc.ExchangeIdentityLink(context.Background(), otherUserID, provider.Name(), validLoginExchange())
+	if got := oauthErrorCode(t, err); got != OAuthStateInvalid {
+		t.Fatalf("oauth code = %q, want %q", got, OAuthStateInvalid)
+	}
+	if provider.completeCnt != 0 {
+		t.Fatal("provider must not receive a transaction bound to another user")
+	}
+}
+
+func TestService_IdentityLinkIsIdempotentForSameProviderSubject(t *testing.T) {
+	provider, svc := validFakeProvider(t)
+	userID := uuid.New()
+
+	if _, err := svc.BeginIdentityLink(context.Background(), userID, provider.Name(), validLoginStart()); err != nil {
+		t.Fatalf("begin first identity link: %v", err)
+	}
+	first, err := svc.ExchangeIdentityLink(context.Background(), userID, provider.Name(), validLoginExchange())
+	if err != nil {
+		t.Fatalf("exchange first identity link: %v", err)
+	}
+
+	if _, err := svc.BeginIdentityLink(context.Background(), userID, provider.Name(), validLoginStart()); err != nil {
+		t.Fatalf("begin repeated identity link: %v", err)
+	}
+	second, err := svc.ExchangeIdentityLink(context.Background(), userID, provider.Name(), validLoginExchange())
+	if err != nil {
+		t.Fatalf("exchange repeated identity link: %v", err)
+	}
+	if first.ID != second.ID || first.Provider != second.Provider {
+		t.Fatalf("repeated link returned a different identity: first=%+v second=%+v", first, second)
+	}
+}
+
+func TestService_UnlinkIdentityRejectsRemovingLastLoginMethod(t *testing.T) {
+	userID := uuid.New()
+	providerUID := "local-user"
+	repo := &fakeRepo{}
+	repo.identities = append(repo.identities, domain.Identity{
+		ID: uuid.New(), UserID: userID, Provider: domain.ProviderLocal, ProviderUID: &providerUID,
+	})
+	svc := newTestService(repo, newFakeTokenStore())
+
+	err := svc.UnlinkIdentity(context.Background(), userID, string(domain.ProviderLocal))
+	var ruleErr *domain.RuleError
+	if !errors.As(err, &ruleErr) || ruleErr.Code != "AUTH_LAST_IDENTITY" {
+		t.Fatalf("unlink last identity error = %v, want AUTH_LAST_IDENTITY", err)
+	}
+}

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

@@ -16,8 +16,9 @@ const (
 // accessClaims — see internal/shared/middleware/auth.go for why this struct
 // is duplicated there instead of imported.
 type accessClaims struct {
-	Typ  string `json:"typ"`
-	Role string `json:"role,omitempty"`
+	Typ       string    `json:"typ"`
+	Role      string    `json:"role,omitempty"`
+	SessionID uuid.UUID `json:"sid,omitempty"`
 	// go-scaffold:jwt-claims
 	jwt.RegisteredClaims
 }
@@ -25,12 +26,14 @@ type accessClaims struct {
 func (s *Service) issueAccessToken(
 	userID uuid.UUID,
 	role string,
+	sessionID uuid.UUID,
 	// go-scaffold:issue-access-token-params
 ) (string, error) {
 	now := s.clock()
 	claims := accessClaims{
 		Typ:  tokenTypeAccess,
 		Role: role,
+		SessionID: sessionID,
 		// go-scaffold:jwt-claims-values
 		RegisteredClaims: jwt.RegisteredClaims{
 			Subject:   userID.String(),

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

@@ -55,7 +55,7 @@ func (s *Service) Register(ctx context.Context, in RegisterInput) (*AuthResult,
 	// Best-effort: a mail failure should not block registration. The user can
 	// request another link through ResendVerificationEmail.
 	s.sendVerificationEmail(ctx, u)
-	auth, err := s.issueTokens(ctx, u)
+	auth, err := s.issueTokens(ctx, u, in.Session)
 	if err != nil {
 		return nil, err
 	}
@@ -92,5 +92,5 @@ func (s *Service) Login(ctx context.Context, in LoginInput) (*AuthResult, error)
 	if err := s.repo.ClearLoginFailures(ctx, key); err != nil {
 		slog.Error("clear login failures", "error", err)
 	}
-	return s.completeLogin(ctx, u)
+	return s.completeLogin(ctx, u, in.Session)
 }

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

@@ -86,10 +86,17 @@ func ValidateMFASettings(settings MFASettings) error {
 	return nil
 }
 
-func (s *Service) completeLogin(ctx context.Context, u *domain.User) (*AuthResult, error) {
+func (s *Service) completeLogin(ctx context.Context, u *domain.User, sessions ...SessionContext) (*AuthResult, error) {
+	var session SessionContext
+	if len(sessions) > 0 {
+		session = sessions[0]
+	}
+	if session.ID == uuid.Nil {
+		session.ID = uuid.New()
+	}
 	settings := s.mfaSettings()
 	if !settings.Enabled {
-		auth, err := s.issueTokens(ctx, u)
+		auth, err := s.issueTokens(ctx, u, session)
 		if err != nil {
 			return nil, err
 		}
@@ -103,7 +110,7 @@ func (s *Service) completeLogin(ctx context.Context, u *domain.User) (*AuthResul
 		return nil, fmt.Errorf("read MFA enrollment: %w", err)
 	}
 	if !found || !enrollment.Enabled {
-		auth, err := s.issueTokens(ctx, u)
+		auth, err := s.issueTokens(ctx, u, session)
 		if err != nil {
 			return nil, err
 		}
@@ -116,6 +123,8 @@ func (s *Service) completeLogin(ctx context.Context, u *domain.User) (*AuthResul
 	}
 	if err := s.mfa.CreateChallenge(ctx, hashToken(rawChallenge), MFAChallenge{
 		UserID:    u.ID,
+		SessionID: session.ID,
+		UserAgent: normalizeUserAgent(session.UserAgent),
 		ExpiresAt: s.clock().Add(settings.ChallengeTTL),
 	}); err != nil {
 		return nil, fmt.Errorf("store MFA challenge: %w", err)
@@ -285,7 +294,7 @@ func (s *Service) VerifyMFA(ctx context.Context, rawChallenge, code string) (*Au
 	if err != nil {
 		return nil, errInvalidCredentials()
 	}
-	return s.issueTokens(ctx, u)
+	return s.issueTokens(ctx, u, SessionContext{ID: challenge.SessionID, UserAgent: challenge.UserAgent})
 }
 
 func (s *Service) requireMFA() (MFASettings, error) {

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

@@ -118,12 +118,18 @@ func (s *Service) SetRole(ctx context.Context, userID uuid.UUID, roleCode string
 // ServicePort is the inbound application boundary. HTTP, jobs, and future
 // transports depend on this capability set instead of the concrete service.
 type ServicePort interface {
+	ListIdentities(context.Context, uuid.UUID) ([]IdentityResponse, error)
+	BeginIdentityLink(context.Context, uuid.UUID, string, LoginStartInput) (*Authorization, error)
+	ExchangeIdentityLink(context.Context, uuid.UUID, string, LoginExchangeInput) (*IdentityResponse, error)
+	UnlinkIdentity(context.Context, uuid.UUID, string) error
 	// go-scaffold:service-interface
 	Register(context.Context, RegisterInput) (*AuthResult, error)
 	Login(context.Context, LoginInput) (*AuthResult, error)
 	Refresh(context.Context, string) (*AuthResponse, error)
 	Logout(context.Context, string) error
 	LogoutAll(context.Context, uuid.UUID) error
+	ListSessions(context.Context, uuid.UUID, uuid.UUID) ([]Session, error)
+	RevokeSession(context.Context, uuid.UUID, uuid.UUID) error
 	ForgotPassword(context.Context, string) error
 	ResetPassword(context.Context, string, string) error
 	VerifyEmail(context.Context, string) error

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

@@ -102,6 +102,32 @@ func (f *fakeTokenStore) RevokeAllRefreshTokens(_ context.Context, userID uuid.U
 	delete(f.sessions, userID)
 	return nil
 }
+func (f *fakeTokenStore) ListRefreshSessions(_ context.Context, userID uuid.UUID) ([]RefreshSession, error) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	out := make([]RefreshSession, 0)
+	for _, token := range f.active {
+		if token.UserID != userID || !token.ExpiresAt.After(time.Now()) {
+			continue
+		}
+		out = append(out, RefreshSession{
+			ID: token.SessionID, UserAgent: token.UserAgent, CreatedAt: token.CreatedAt,
+			LastUsedAt: token.LastUsedAt, ExpiresAt: token.ExpiresAt,
+		})
+	}
+	return out, nil
+}
+func (f *fakeTokenStore) RevokeRefreshSession(_ context.Context, userID, sessionID uuid.UUID) error {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	for hash, token := range f.active {
+		if token.UserID == userID && token.SessionID == sessionID {
+			delete(f.active, hash)
+			delete(f.sessions[userID], hash)
+		}
+	}
+	return nil
+}
 func (f *fakeTokenStore) IsRefreshTokenUsed(_ context.Context, hash string) (uuid.UUID, bool, error) {
 	f.mu.Lock()
 	defer f.mu.Unlock()
@@ -308,6 +334,7 @@ func (f *fakeMFAStore) ConsumeRecoveryCode(_ context.Context, userID uuid.UUID,
 type fakeRepo struct {
 	user              *domain.User
 	identity          *domain.Identity
+	identities        []domain.Identity
 	updateIdentityErr error
 	updateUserErr     error
 	failures          map[string]int
@@ -361,20 +388,61 @@ func (f *fakeRepo) UpdateUser(_ context.Context, u *domain.User) error {
 	return nil
 }
 func (f *fakeRepo) FindAll(context.Context, int, int) ([]domain.User, error) { return nil, nil }
-func (f *fakeRepo) FindIdentity(_ context.Context, userID uuid.UUID, _ domain.Provider) (*domain.Identity, error) {
-	if f.identity != nil && f.identity.UserID == userID {
+
+func (f *fakeRepo) FindIdentity(_ context.Context, userID uuid.UUID, provider domain.Provider) (*domain.Identity, error) {
+	for i := range f.identities {
+		if f.identities[i].UserID == userID && f.identities[i].Provider == provider {
+			copy := f.identities[i]
+			return &copy, nil
+		}
+	}
+	if f.identity != nil && f.identity.UserID == userID && f.identity.Provider == provider {
 		copy := *f.identity
 		return &copy, nil
 	}
 	return nil, domain.ErrNotFound
 }
-func (f *fakeRepo) FindIdentityByProviderUID(context.Context, domain.Provider, string) (*domain.Identity, error) {
+func (f *fakeRepo) ListIdentities(_ context.Context, userID uuid.UUID) ([]domain.Identity, error) {
+	out := make([]domain.Identity, 0, len(f.identities)+1)
+	for _, identity := range f.identities {
+		if identity.UserID == userID {
+			out = append(out, identity)
+		}
+	}
+	if f.identity != nil && f.identity.UserID == userID {
+		found := false
+		for _, identity := range out {
+			if identity.ID == f.identity.ID {
+				found = true
+				break
+			}
+		}
+		if !found {
+			out = append(out, *f.identity)
+		}
+	}
+	return out, nil
+}
+func (f *fakeRepo) FindIdentityByProviderUID(_ context.Context, provider domain.Provider, providerUID string) (*domain.Identity, error) {
+	for i := range f.identities {
+		if f.identities[i].Provider == provider && f.identities[i].ProviderUID != nil && *f.identities[i].ProviderUID == providerUID {
+			copy := f.identities[i]
+			return &copy, nil
+		}
+	}
+	if f.identity != nil && f.identity.Provider == provider && f.identity.ProviderUID != nil && *f.identity.ProviderUID == providerUID {
+		copy := *f.identity
+		return &copy, nil
+	}
 	return nil, domain.ErrNotFound
 }
 func (f *fakeRepo) CreateUserWithIdentity(context.Context, *domain.User, *domain.Identity) error {
 	return nil
 }
-func (f *fakeRepo) CreateIdentity(context.Context, *domain.Identity) error { return nil }
+func (f *fakeRepo) CreateIdentity(_ context.Context, identity *domain.Identity) error {
+	f.identities = append(f.identities, *identity)
+	return nil
+}
 func (f *fakeRepo) UpdateIdentity(_ context.Context, i *domain.Identity) error {
 	if f.updateIdentityErr != nil {
 		return f.updateIdentityErr
@@ -382,6 +450,35 @@ func (f *fakeRepo) UpdateIdentity(_ context.Context, i *domain.Identity) error {
 	f.identity = i
 	return nil
 }
+func (f *fakeRepo) DeleteIdentity(_ context.Context, userID uuid.UUID, provider domain.Provider) error {
+	count := 0
+	target := -1
+	for i := range f.identities {
+		if f.identities[i].UserID != userID {
+			continue
+		}
+		count++
+		if f.identities[i].Provider == provider {
+			target = i
+		}
+	}
+	legacyTarget := f.identity != nil && f.identity.UserID == userID && f.identity.Provider == provider
+	if legacyTarget {
+		count++
+	}
+	if target < 0 && !legacyTarget {
+		return domain.ErrNotFound
+	}
+	if count <= 1 {
+		return domain.ErrLastIdentity
+	}
+	if target >= 0 {
+		f.identities = append(f.identities[:target], f.identities[target+1:]...)
+	} else {
+		f.identity = nil
+	}
+	return nil
+}
 
 // go-scaffold:user-fake-repo-methods
 // go-scaffold:repository-stub-methods
@@ -552,8 +649,10 @@ func TestService_Refresh_DoesNotExtendTheAbsoluteLifetime(t *testing.T) {
 	raw := "bounded-refresh-token"
 	issuedAt := time.Now()
 	absoluteExpiry := issuedAt.Add(2 * time.Hour)
+	sessionID := uuid.New()
 	if err := tokens.SetRefreshToken(ctx, hashToken(raw), RefreshTokenRecord{
-		UserID:            userID,
+		UserID:            userID, SessionID: sessionID, UserAgent: "test-device",
+		CreatedAt:         issuedAt.Add(-time.Hour), LastUsedAt: issuedAt.Add(-time.Minute),
 		ExpiresAt:         issuedAt.Add(time.Hour),
 		AbsoluteExpiresAt: absoluteExpiry,
 	}); err != nil {
@@ -576,6 +675,9 @@ func TestService_Refresh_DoesNotExtendTheAbsoluteLifetime(t *testing.T) {
 	if !rotated.ExpiresAt.Equal(absoluteExpiry) {
 		t.Fatalf("rotated inactivity expiry was not capped at the absolute expiry: got %s want %s", rotated.ExpiresAt, absoluteExpiry)
 	}
+	if rotated.SessionID != sessionID || rotated.UserAgent != "test-device" {
+		t.Fatalf("refresh rotation changed session identity/metadata: got id=%s ua=%q", rotated.SessionID, rotated.UserAgent)
+	}
 }
 
 func TestService_Refresh_ReuseRevokeFailureFailsClosed(t *testing.T) {

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

@@ -3,6 +3,8 @@ package application
 import (
 	"context"
 	"fmt"
+	"sort"
+	"strings"
 	"time"
 
 	"{{goModule}}/internal/app/user/domain"
@@ -36,7 +38,9 @@ func (s *Service) Refresh(ctx context.Context, rawRefreshToken string) (*AuthRes
 	if err != nil {
 		return nil, errInvalidToken()
 	}
-	return s.issueTokens(ctx, u, token.AbsoluteExpiresAt)
+	return s.issueTokens(ctx, u, SessionContext{
+		ID: token.SessionID, UserAgent: token.UserAgent, CreatedAt: token.CreatedAt,
+	}, token.AbsoluteExpiresAt)
 }
 
 // Logout is intentional, not reuse: a missing or already-gone token still
@@ -58,10 +62,51 @@ func (s *Service) LogoutAll(ctx context.Context, userID uuid.UUID) error {
 	return s.refreshTokens.RevokeAllRefreshTokens(ctx, userID)
 }
 
-func (s *Service) issueTokens(ctx context.Context, u *domain.User, absoluteExpiresAt ...time.Time) (*AuthResponse, error) {
+func (s *Service) ListSessions(ctx context.Context, userID, currentSessionID uuid.UUID) ([]Session, error) {
+	items, err := s.refreshTokens.ListRefreshSessions(ctx, userID)
+	if err != nil {
+		return nil, fmt.Errorf("list refresh sessions: %w", err)
+	}
+	out := make([]Session, 0, len(items))
+	for _, item := range items {
+		out = append(out, Session{
+			ID: item.ID, UserAgent: item.UserAgent, CreatedAt: item.CreatedAt,
+			LastUsedAt: item.LastUsedAt, ExpiresAt: item.ExpiresAt,
+			Current: item.ID == currentSessionID,
+		})
+	}
+	sort.SliceStable(out, func(i, j int) bool {
+		return out[i].LastUsedAt.After(out[j].LastUsedAt)
+	})
+	return out, nil
+}
+
+func (s *Service) RevokeSession(ctx context.Context, userID, sessionID uuid.UUID) error {
+	if userID == uuid.Nil || sessionID == uuid.Nil {
+		return fmt.Errorf("session identity is invalid")
+	}
+	return s.refreshTokens.RevokeRefreshSession(ctx, userID, sessionID)
+}
+
+func (s *Service) issueTokens(ctx context.Context, u *domain.User, session SessionContext, absoluteExpiresAt ...time.Time) (*AuthResponse, error) {
+	clock := s.now
+	if clock == nil {
+		clock = time.Now
+	}
+	now := clock()
+	if session.ID == uuid.Nil {
+		session.ID = uuid.New()
+	}
+	if session.CreatedAt.IsZero() {
+		session.CreatedAt = now
+	}
+	if session.UserAgent = normalizeUserAgent(session.UserAgent); session.UserAgent == "" {
+		session.UserAgent = "unknown"
+	}
 	access, err := s.issueAccessToken(
 		u.ID,
 		u.Role,
+		session.ID,
 		// go-scaffold:issue-access-token-args
 	)
 	if err != nil {
@@ -71,11 +116,6 @@ func (s *Service) issueTokens(ctx context.Context, u *domain.User, absoluteExpir
 	if err != nil {
 		return nil, fmt.Errorf("generate refresh token: %w", err)
 	}
-	clock := s.now
-	if clock == nil {
-		clock = time.Now
-	}
-	now := clock()
 	abs := now.Add(s.config.JWTRefreshMaxTTL)
 	if len(absoluteExpiresAt) > 0 && !absoluteExpiresAt[0].IsZero() {
 		abs = absoluteExpiresAt[0]
@@ -87,7 +127,11 @@ func (s *Service) issueTokens(ctx context.Context, u *domain.User, absoluteExpir
 	if !expiresAt.After(now) || !abs.After(now) {
 		return nil, fmt.Errorf("refresh token lifetime is exhausted")
 	}
-	if err := s.refreshTokens.SetRefreshToken(ctx, hashToken(refresh), RefreshTokenRecord{UserID: u.ID, ExpiresAt: expiresAt, AbsoluteExpiresAt: abs}); err != nil {
+	if err := s.refreshTokens.SetRefreshToken(ctx, hashToken(refresh), RefreshTokenRecord{
+		UserID: u.ID, SessionID: session.ID, UserAgent: session.UserAgent,
+		CreatedAt: session.CreatedAt, LastUsedAt: now, ExpiresAt: expiresAt,
+		AbsoluteExpiresAt: abs,
+	}); err != nil {
 		return nil, fmt.Errorf("store refresh token: %w", err)
 	}
 	return &AuthResponse{
@@ -97,3 +141,13 @@ func (s *Service) issueTokens(ctx context.Context, u *domain.User, absoluteExpir
 		ExpiresIn:    int(s.config.JWTAccessTTL.Seconds()),
 	}, nil
 }
+
+const maxUserAgentLength = 512
+
+func normalizeUserAgent(value string) string {
+	value = strings.TrimSpace(value)
+	if len(value) > maxUserAgentLength {
+		return value[:maxUserAgentLength]
+	}
+	return value
+}

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

@@ -8,6 +8,7 @@ type RefreshTokenStore = ports.RefreshTokenStore
 type OAuthTransactionStore = ports.OAuthTransactionStore
 type RecoveryTokenStore = ports.RecoveryTokenStore
 type RefreshTokenRecord = ports.RefreshTokenRecord
+type RefreshSession = ports.RefreshSession
 type LoginTransaction = ports.LoginTransaction
 type MFAEnrollment = ports.MFAEnrollment
 type MFAChallenge = ports.MFAChallenge

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

@@ -15,7 +15,9 @@ var (
 	ErrMFAAlreadyEnabled = errors.New("MFA is already enabled")
 	ErrMFANotEnrolled    = errors.New("MFA is not enrolled")
 	ErrMFASetupRequired  = errors.New("MFA setup is required")
-	ErrUnknownRole       = errors.New("unknown role")
+	ErrUnknownRole           = errors.New("unknown role")
+	ErrIdentityAlreadyLinked = errors.New("login identity is already linked")
+	ErrLastIdentity          = errors.New("cannot remove the last login identity")
 )
 
 type RuleError struct {

package/templates/add/auth/internal/app/user/ports/repository.go.hbs

@@ -16,10 +16,12 @@ type UserRepository interface {
 	UpdateUser(context.Context, *domain.User) error
 	FindAll(context.Context, int, int) ([]domain.User, error)
 	FindIdentity(context.Context, uuid.UUID, domain.Provider) (*domain.Identity, error)
+	ListIdentities(context.Context, uuid.UUID) ([]domain.Identity, error)
 	FindIdentityByProviderUID(context.Context, domain.Provider, string) (*domain.Identity, error)
 	CreateUserWithIdentity(context.Context, *domain.User, *domain.Identity) error
 	CreateIdentity(context.Context, *domain.Identity) error
 	UpdateIdentity(context.Context, *domain.Identity) error
+	DeleteIdentity(context.Context, uuid.UUID, domain.Provider) error
 	LoginLockedUntil(context.Context, string) (time.Time, error)
 	RecordLoginFailure(context.Context, string, int, time.Duration) error
 	ClearLoginFailures(context.Context, string) error
@@ -36,21 +38,36 @@ type RoleChecker interface {
 
 type RefreshTokenRecord struct {
 	UserID            uuid.UUID `json:"user_id"`
+	SessionID         uuid.UUID `json:"session_id"`
+	UserAgent         string    `json:"user_agent"`
+	CreatedAt         time.Time `json:"created_at"`
+	LastUsedAt        time.Time `json:"last_used_at"`
 	ExpiresAt         time.Time `json:"expires_at"`
 	AbsoluteExpiresAt time.Time `json:"absolute_expires_at"`
 }
 
+type RefreshSession struct {
+	ID         uuid.UUID
+	UserAgent  string
+	CreatedAt  time.Time
+	LastUsedAt time.Time
+	ExpiresAt  time.Time
+}
+
 type RefreshTokenStore interface {
 	SetRefreshToken(context.Context, string, RefreshTokenRecord) error
 	GetRefreshToken(context.Context, string) (uuid.UUID, bool, error)
 	ConsumeRefreshToken(context.Context, string) (RefreshTokenRecord, bool, error)
 	DeleteRefreshToken(context.Context, string, uuid.UUID) error
 	RevokeAllRefreshTokens(context.Context, uuid.UUID) error
+	ListRefreshSessions(context.Context, uuid.UUID) ([]RefreshSession, error)
+	RevokeRefreshSession(context.Context, uuid.UUID, uuid.UUID) error
 	IsRefreshTokenUsed(context.Context, string) (uuid.UUID, bool, error)
 }
 
 type LoginTransaction struct {
 	Provider      string    `json:"provider"`
+	UserID        uuid.UUID `json:"user_id"`
 	CodeChallenge string    `json:"code_challenge"`
 	Nonce         string    `json:"nonce"`
 	ExpiresAt     time.Time `json:"expires_at"`
@@ -76,6 +93,8 @@ type MFAEnrollment struct {
 
 type MFAChallenge struct {
 	UserID    uuid.UUID
+	SessionID uuid.UUID
+	UserAgent string
 	ExpiresAt time.Time
 }
 

package/templates/add/auth/internal/shared/middleware/auth.go.hbs

@@ -13,14 +13,17 @@ import (
 
 const UserIDKey = "user_id"
 
+const SessionIDKey = "session_id"
+
 // go-scaffold:middleware-auth-keys
 
 // accessClaims mirrors internal/app/user's own claims shape — duplicated
 // rather than imported, since shared/ can never import a domain package.
-// The two are kept in sync by convention: sub = user id, typ = "access",
-// nothing else is load-bearing here.
+// The two are kept in sync by convention: sub = user id, typ = "access", and
+// sid = the stable refresh-session identity used by session management.
 type accessClaims struct {
-	Typ string `json:"typ"`
+	Typ       string    `json:"typ"`
+	SessionID uuid.UUID `json:"sid,omitempty"`
 	// go-scaffold:middleware-auth-claims
 	jwt.RegisteredClaims
 }
@@ -53,6 +56,9 @@ func RequireAuth(secret string) gin.HandlerFunc {
 		}
 
 		c.Set(UserIDKey, userID)
+		if claims.SessionID != uuid.Nil {
+			c.Set(SessionIDKey, claims.SessionID)
+		}
 		// go-scaffold:middleware-auth-context
 		c.Next()
 	}

package/templates/add/auth/internal/shared/middleware/auth_test.go.hbs

@@ -0,0 +1,48 @@
+package middleware
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/golang-jwt/jwt/v5"
+	"github.com/google/uuid"
+)
+
+func TestRequireAuthExposesSessionIDFromAccessToken(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	secret := "test-secret"
+	userID := uuid.New()
+	sessionID := uuid.New()
+	token := jwt.NewWithClaims(jwt.SigningMethodHS256, accessClaims{
+		Typ:       "access",
+		SessionID: sessionID,
+		RegisteredClaims: jwt.RegisteredClaims{
+			Subject:   userID.String(),
+			IssuedAt: jwt.NewNumericDate(time.Now()),
+			ExpiresAt: jwt.NewNumericDate(time.Now().Add(time.Minute)),
+		},
+	})
+	raw, err := token.SignedString([]byte(secret))
+	if err != nil {
+		t.Fatalf("sign token: %v", err)
+	}
+
+	router := gin.New()
+	router.Use(RequireAuth(secret))
+	router.GET("/", func(c *gin.Context) {
+		if got := c.MustGet(SessionIDKey); got != sessionID {
+			t.Fatalf("session id = %v, want %s", got, sessionID)
+		}
+		c.Status(http.StatusNoContent)
+	})
+	response := httptest.NewRecorder()
+	request := httptest.NewRequest(http.MethodGet, "/", nil)
+	request.Header.Set("Authorization", "Bearer "+raw)
+	router.ServeHTTP(response, request)
+	if response.Code != http.StatusNoContent {
+		t.Fatalf("status = %d, want 204", response.Code)
+	}
+}

package/templates/add/auth/migrations/create_auth_tokens.up.sql.hbs

@@ -6,12 +6,15 @@ CREATE TABLE user_svc.auth_tokens (
     token_hash TEXT PRIMARY KEY,
     user_id    UUID NOT NULL,
     kind       VARCHAR(20) NOT NULL,
+    session_id UUID NOT NULL DEFAULT '00000000-0000-0000-0000-000000000000',
+    user_agent TEXT NOT NULL DEFAULT '',
     expires_at TIMESTAMPTZ NOT NULL,
     absolute_expires_at TIMESTAMPTZ,
     provider   VARCHAR(20) NOT NULL DEFAULT '',
     code_challenge TEXT NOT NULL DEFAULT '',
     nonce      TEXT NOT NULL DEFAULT '',
-    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    last_used_at TIMESTAMPTZ NOT NULL DEFAULT now()
 );
 
 -- Named to match model.AuthToken's own `index:` tags exactly, so the
@@ -19,3 +22,4 @@ CREATE TABLE user_svc.auth_tokens (
 CREATE INDEX idx_auth_tokens_user_kind ON user_svc.auth_tokens (user_id, kind);
 CREATE INDEX idx_auth_tokens_expires_at ON user_svc.auth_tokens (expires_at);
 CREATE INDEX idx_auth_tokens_absolute_expires_at ON user_svc.auth_tokens (absolute_expires_at);
+CREATE INDEX idx_auth_tokens_user_session ON user_svc.auth_tokens (user_id, session_id, last_used_at);

package/templates/add/auth/migrations/create_mfa.up.sql.hbs

@@ -12,6 +12,8 @@ CREATE TABLE user_svc.mfa_enrollments (
 CREATE TABLE user_svc.mfa_challenges (
     challenge_hash TEXT PRIMARY KEY,
     user_id        UUID NOT NULL REFERENCES user_svc.users(id) ON DELETE CASCADE,
+    session_id     UUID NOT NULL DEFAULT '00000000-0000-0000-0000-000000000000',
+    user_agent     TEXT NOT NULL DEFAULT '',
     expires_at     TIMESTAMPTZ NOT NULL,
     created_at     TIMESTAMPTZ NOT NULL DEFAULT now()
 );

package/templates/create/base/.claude/skills/go-scaffold/SKILL.md.hbs

@@ -260,6 +260,15 @@ boundary. For browser OAuth, preserve this client-owned callback contract:
   `Pragma: no-cache`.
   Never accept a request-supplied redirect destination or place an access token,
   refresh token, authorization code, or state in a URI.
+- Authenticated identity management is a separate account flow, not another
+  login endpoint: list safe metadata at `GET /users/me/identities`, start and
+  finish linking at `POST /users/me/identities/:provider/link` and
+  `POST /users/me/identities/:provider/link/exchange`, and unlink with
+  `DELETE /users/me/identities/:provider`. Bind the server-side transaction to
+  the caller's user ID, never issue or replace a session during link exchange,
+  keep one identity per provider per user, and reject unlinking the last login
+  method. Provider subjects and password hashes must never cross the HTTP
+  boundary.
 - Map provider and validation failures to controlled public codes only:
   `oauth_denied`, `oauth_state_invalid`, `oauth_provider_unavailable`, and
   `oauth_failed`. Do not expose raw provider descriptions or technical causes.