@nakedev/go-scaffold 0.5.0 → 0.5.2

package/dist/commands/auth.js

@@ -36,6 +36,8 @@ const AUTH_OPENAPI_PATHS = [
     { urlPath: "/users/me", file: "./auth/users-me.yaml" },
     { urlPath: "/users/me/resend-verification", file: "./auth/users-me-resend-verification.yaml" },
     { urlPath: "/users/me/logout-all", file: "./auth/users-me-logout-all.yaml" },
+    { urlPath: "/users/me/sessions", file: "./auth/users-me-sessions.yaml" },
+    { urlPath: "/users/me/sessions/{id}", file: "./auth/users-me-session.yaml" },
     { urlPath: "/users/me/mfa", file: "./auth/users-me-mfa.yaml" },
     { urlPath: "/users/me/mfa/setup", file: "./auth/users-me-mfa-setup.yaml" },
     { urlPath: "/users/me/mfa/confirm", file: "./auth/users-me-mfa-confirm.yaml" },
@@ -44,7 +46,8 @@ const AUTH_OPENAPI_PATHS = [
 ];
 // addAuth scaffolds email/password authentication: a users+identities model
 // pair, JWT access tokens, a selectable refresh token store with
-// rotation + reuse detection, and register/login/refresh/logout/me. No RBAC
+// rotation + reuse detection, register/login/refresh/logout/me, and
+// per-user session listing/revocation. No RBAC
 // (no roles/permissions) — that's a separate opt-in on top of this, since
 // most projects need "is this caller logged in" long before they need "can
 // this caller do X".
@@ -178,6 +181,7 @@ async function addAuth(store = "postgres", projectDir = process.cwd(), browserTo
     console.log("registered POST /auth/{register,login,refresh,logout,forgot-password,reset-password,verify-email}, " +
         "GET /auth/{provider}/login, POST /auth/{provider}/exchange, GET /users/me, and " +
         "POST /users/me/{resend-verification,logout-all,mfa/setup,mfa/confirm,mfa/disable}, " +
+        "GET /users/me/sessions, DELETE /users/me/sessions/{id}, " +
         "GET /users/me/mfa, and POST /auth/mfa/verify in cmd/api/wiring.go" +
         docsMessage);
     console.log(picocolors_1.default.dim("\nnext: go mod tidy, then apply the new migrations with `make migrate-up` before production\n" +

package/dist/index.js

@@ -494,7 +494,7 @@ async function resolveQueueBackend(opts) {
 }
 add
     .command("auth")
-    .description("add email/password auth: JWT access tokens, refresh token rotation, register/login/refresh/logout/me (no prerequisites — without `add worker` the verification/reset mail is sent inline)")
+    .description("add email/password auth: JWT access tokens, refresh rotation, device-session listing/revocation, register/login/refresh/logout/me (no prerequisites — without `add worker` the verification/reset mail is sent inline)")
     .option("--store <store>", 'where tokens and rate-limit counters live: "postgres" (default, no extra service) or "redis" (exact across replicas)')
     .option("--browser-topology <topology>", "browser deployment topology for cookie/CORS policy: same-origin, same-site (different origin), or cross-site (requires HTTPS deployment)")
     .option("--defaults", "skip store, browser-topology, and confirmation prompts; use Postgres plus local same-site defaults")

package/dist/templates/auth-manifest.js

@@ -7,6 +7,7 @@ exports.authFiles = authFiles;
 // must create one canonical implementation tree.
 const SHARED = [
     { template: "add/auth/internal/shared/middleware/auth.go.hbs", output: "internal/shared/middleware/auth.go" },
+    { template: "add/auth/internal/shared/middleware/auth_test.go.hbs", output: "internal/shared/middleware/auth_test.go" },
     { template: "add/auth/internal/shared/middleware/ratelimit.go.hbs", output: "internal/shared/middleware/ratelimit.go" },
     { template: "add/auth/internal/app/user/domain/entity.go.hbs", output: "internal/app/user/domain/entity.go" },
     { template: "add/auth/internal/app/user/domain/errors.go.hbs", output: "internal/app/user/domain/errors.go" },

package/dist/utils/rbac-patcher.js

@@ -61,7 +61,7 @@ function patchUserModelForRbac(userModelPath) {
 function patchMiddlewareAuthForRbac(middlewareAuthPath) {
     let content = fs_extra_1.default.readFileSync(middlewareAuthPath, "utf8");
     content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:middleware-auth-keys", 'const RoleKey = "role"', 'RoleKey = "role"');
-    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:middleware-auth-claims", 'Role string `json:"role,omitempty"`', "Role string");
+    content = insertGoLineBeforeMarkerOnce(content, "// go-scaffold:middleware-auth-claims", 'Role string `json:"role,omitempty"`', /^\s*Role\s+string\s+`json:"role,omitempty"`/m);
     content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:middleware-auth-context", "c.Set(RoleKey, claims.Role)", "c.Set(RoleKey");
     fs_extra_1.default.writeFileSync(middlewareAuthPath, content);
 }
@@ -72,11 +72,19 @@ function patchMiddlewareAuthForRbac(middlewareAuthPath) {
 // specifically so a marker patch can extend either without reformatting.
 function patchUserJWTForRbac(jwtGoPath) {
     let content = fs_extra_1.default.readFileSync(jwtGoPath, "utf8");
-    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:jwt-claims", 'Role string `json:"role,omitempty"`', "Role string");
-    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:issue-access-token-params", "role string,", "role string,");
-    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:jwt-claims-values", "Role: role,", "Role: role,");
+    content = insertGoLineBeforeMarkerOnce(content, "// go-scaffold:jwt-claims", 'Role string `json:"role,omitempty"`', /^\s*Role\s+string\s+`json:"role,omitempty"`/m);
+    content = insertGoLineBeforeMarkerOnce(content, "// go-scaffold:issue-access-token-params", "role string,", /^\s*role\s+string\s*,/m);
+    content = insertGoLineBeforeMarkerOnce(content, "// go-scaffold:jwt-claims-values", "Role: role,", /^\s*Role\s*:\s*role\s*,/m);
     fs_extra_1.default.writeFileSync(jwtGoPath, content);
 }
+// Go fmt aligns struct fields and can turn a literal sentinel such as
+// `Role string` into `Role       string`. Match the Go line semantically so a
+// subsequent `add rbac` cannot append a duplicate field after formatting.
+function insertGoLineBeforeMarkerOnce(content, marker, block, line) {
+    if (line.test(content))
+        return content;
+    return (0, marker_patch_1.insertBeforeMarker)(content, marker, block);
+}
 // patchUserServiceForRbac verifies the auth application already exposes the
 // optional role capability. The canonical auth template owns this shared user
 // behavior; `add rbac` only supplies the role catalog and authorizer.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nakedev/go-scaffold",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Scaffold Gin + GORM + Postgres Go backend projects with a consistent domain-module standard",
   "repository": {
     "type": "git",

package/templates/add/auth/docs/schemas.yaml.hbs

@@ -114,3 +114,22 @@ MeResponse:
     email_verified: { type: boolean }
     # go-scaffold:me-response-fields
     created_at: { type: string, format: date-time }
+
+SessionResponse:
+  type: object
+  required: [id, user_agent, created_at, last_used_at, expires_at, current]
+  properties:
+    id: { type: string, format: uuid }
+    user_agent: { type: string, description: browser or client User-Agent captured at sign-in }
+    created_at: { type: string, format: date-time }
+    last_used_at: { type: string, format: date-time }
+    expires_at: { type: string, format: date-time }
+    current: { type: boolean, description: true when this session issued the current access token }
+
+SessionsResponse:
+  type: object
+  required: [sessions]
+  properties:
+    sessions:
+      type: array
+      items: { $ref: '#/SessionResponse' }

package/templates/add/auth/docs/users-me-session.yaml.hbs

@@ -0,0 +1,14 @@
+delete:
+  summary: Revoke one session for the current user
+  operationId: revokeMySession
+  tags: [users]
+  security: [{ bearerAuth: [] }]
+  parameters:
+    - name: id
+      in: path
+      required: true
+      schema: { type: string, format: uuid }
+  responses:
+    "204": { description: session revoked }
+    "400": { $ref: '../common/responses.yaml#/ValidationError' }
+    "401": { $ref: '../common/responses.yaml#/UnauthorizedError' }

package/templates/add/auth/docs/users-me-sessions.yaml.hbs

@@ -0,0 +1,13 @@
+get:
+  summary: List active sessions for the current user
+  description: Returns active refresh-token sessions with safe device metadata. Raw refresh tokens and token hashes are never returned.
+  operationId: listMySessions
+  tags: [users]
+  security: [{ bearerAuth: [] }]
+  responses:
+    "200":
+      description: active sessions
+      content:
+        application/json:
+          schema: { $ref: './schemas.yaml#/SessionsResponse' }
+    "401": { $ref: '../common/responses.yaml#/UnauthorizedError' }

package/templates/add/auth/internal/app/user/adapters/inbound/http/dto.go.hbs

@@ -52,6 +52,10 @@ func toLoginExchangeInput(in loginExchangeInput) userapp.LoginExchangeInput {
 	return userapp.LoginExchangeInput{Code: in.Code, State: in.State, CodeVerifier: in.CodeVerifier}
 }
 
+func sessionContext(userAgent string) userapp.SessionContext {
+	return userapp.SessionContext{UserAgent: userAgent}
+}
+
 type forgotPasswordInput struct {
 	Email string `json:"email" binding:"required,email"`
 }
@@ -99,6 +103,26 @@ type mfaConfirmResponse struct {
 	RecoveryCodes []string `json:"recovery_codes"`
 }
 
+type sessionResponse struct {
+	ID         uuid.UUID `json:"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"`
+	Current    bool      `json:"current"`
+}
+
+type sessionsResponse struct {
+	Sessions []sessionResponse `json:"sessions"`
+}
+
+func toSessionResponse(session userapp.Session) sessionResponse {
+	return sessionResponse{
+		ID: session.ID, UserAgent: session.UserAgent, CreatedAt: session.CreatedAt,
+		LastUsedAt: session.LastUsedAt, ExpiresAt: session.ExpiresAt, Current: session.Current,
+	}
+}
+
 func toCookieResponse(auth *userapp.AuthResponse) authCookieResponse {
 	return authCookieResponse{AccessToken: auth.AccessToken, TokenType: auth.TokenType, ExpiresIn: auth.ExpiresIn}
 }

package/templates/add/auth/internal/app/user/adapters/inbound/http/handler.go.hbs

@@ -132,6 +132,8 @@ func (h *Handler) Register(rg gin.IRouter) {
 	usersGroup.GET("/me", h.me)
 	usersGroup.POST("/me/resend-verification", resendVerificationLimit, h.resendVerification)
 	usersGroup.POST("/me/logout-all", h.logoutAll)
+	usersGroup.GET("/me/sessions", h.sessions)
+	usersGroup.DELETE("/me/sessions/:id", h.revokeSession)
 	usersGroup.GET("/me/mfa", h.mfaStatus)
 	usersGroup.POST("/me/mfa/setup", mfaSetupLimit, h.setupMFA)
 	usersGroup.POST("/me/mfa/confirm", mfaConfirmLimit, h.confirmMFA)

package/templates/add/auth/internal/app/user/adapters/inbound/http/handler_local.go.hbs

@@ -19,7 +19,9 @@ func (h *Handler) register(c *gin.Context) {
 		c.Error(httpx.BindErr(err))
 		return
 	}
-	auth, err := h.svc.Register(c.Request.Context(), toRegisterInput(in))
+	input := toRegisterInput(in)
+	input.Session = sessionContext(c.GetHeader("User-Agent"))
+	auth, err := h.svc.Register(c.Request.Context(), input)
 	if err != nil {
 		c.Error(toHTTPError(err))
 		return
@@ -37,7 +39,9 @@ func (h *Handler) login(c *gin.Context) {
 		c.Error(httpx.BindErr(err))
 		return
 	}
-	auth, err := h.svc.Login(c.Request.Context(), toLoginInput(in))
+	input := toLoginInput(in)
+	input.Session = sessionContext(c.GetHeader("User-Agent"))
+	auth, err := h.svc.Login(c.Request.Context(), input)
 	if err != nil {
 		c.Error(toHTTPError(err))
 		return

package/templates/add/auth/internal/app/user/adapters/inbound/http/handler_mfa.go.hbs

@@ -81,3 +81,12 @@ func (h *Handler) disableMFA(c *gin.Context) {
 func currentUserID(c *gin.Context) uuid.UUID {
 	return c.MustGet(middleware.UserIDKey).(uuid.UUID)
 }
+
+func currentSessionID(c *gin.Context) uuid.UUID {
+	if value, ok := c.Get(middleware.SessionIDKey); ok {
+		if sessionID, ok := value.(uuid.UUID); ok {
+			return sessionID
+		}
+	}
+	return uuid.Nil
+}

package/templates/add/auth/internal/app/user/adapters/inbound/http/handler_oauth.go.hbs

@@ -34,7 +34,9 @@ func (h *Handler) providerExchange(c *gin.Context) {
 		c.Error(h.oauthAppError(c.Param("provider"), userapp.NewOAuthError(userapp.OAuthFailed, err)))
 		return
 	}
-	auth, err := h.svc.ExchangeLogin(c.Request.Context(), c.Param("provider"), toLoginExchangeInput(in))
+	input := toLoginExchangeInput(in)
+	input.Session = sessionContext(c.GetHeader("User-Agent"))
+	auth, err := h.svc.ExchangeLogin(c.Request.Context(), c.Param("provider"), input)
 	if err != nil {
 		c.Error(h.oauthAppError(c.Param("provider"), err))
 		return

package/templates/add/auth/internal/app/user/adapters/inbound/http/handler_test.go.hbs

@@ -151,6 +151,20 @@ func TestHandler_ProviderExchangeReturnsJSONAndSetsRefreshCookie(t *testing.T) {
 	}
 }
 
+func TestHandler_SessionRoutesAreProtected(t *testing.T) {
+	router := newOAuthTestRouter(t)
+	for _, route := range []struct{ method, path string }{
+		{http.MethodGet, "/users/me/sessions"},
+		{http.MethodDelete, "/users/me/sessions/00000000-0000-0000-0000-000000000001"},
+	} {
+		response := httptest.NewRecorder()
+		router.ServeHTTP(response, httptest.NewRequest(route.method, route.path, nil))
+		if response.Code != http.StatusUnauthorized {
+			t.Fatalf("%s %s status = %d, want 401", route.method, route.path, response.Code)
+		}
+	}
+}
+
 func TestHandler_ProviderCallbackIsFrontendOwnedAndErrorsDoNotRedirect(t *testing.T) {
 	router := newOAuthTestRouter(t)
 	callback := httptest.NewRequest(http.MethodGet, "/auth/fake/callback?error=access_denied&error_description=do-not-leak", nil)

package/templates/add/auth/internal/app/user/adapters/inbound/http/handler_user.go.hbs

@@ -3,6 +3,7 @@ package httpadapter
 import (
 	"net/http"
 
+	"{{goModule}}/internal/shared/httpx"
 	"{{goModule}}/internal/shared/middleware"
 
 	"github.com/gin-gonic/gin"
@@ -30,6 +31,35 @@ func (h *Handler) logoutAll(c *gin.Context) {
 	c.Status(http.StatusNoContent)
 }
 
+func (h *Handler) sessions(c *gin.Context) {
+	setNoStoreHeaders(c)
+	items, err := h.svc.ListSessions(c.Request.Context(), currentUserID(c), currentSessionID(c))
+	if err != nil {
+		c.Error(toHTTPError(err))
+		return
+	}
+	out := make([]sessionResponse, len(items))
+	for i := range items {
+		out[i] = toSessionResponse(items[i])
+	}
+	c.JSON(http.StatusOK, sessionsResponse{Sessions: out})
+}
+
+func (h *Handler) revokeSession(c *gin.Context) {
+	sessionID, ok := httpx.ParseID(c)
+	if !ok {
+		return
+	}
+	if err := h.svc.RevokeSession(c.Request.Context(), currentUserID(c), sessionID); err != nil {
+		c.Error(toHTTPError(err))
+		return
+	}
+	if sessionID == currentSessionID(c) {
+		h.clearRefreshCookie(c)
+	}
+	c.Status(http.StatusNoContent)
+}
+
 func (h *Handler) me(c *gin.Context) {
 	userID := c.MustGet(middleware.UserIDKey).(uuid.UUID)
 	u, err := h.svc.Get(c.Request.Context(), userID)

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/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)
 }

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,35 @@ 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
 }
 
 type AuthResponse struct {

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

@@ -86,7 +86,7 @@ func (s *Service) ExchangeLogin(ctx context.Context, providerName string, in Log
 	if err != nil {
 		return nil, NewOAuthError(OAuthFailed, fmt.Errorf("resolve external identity: %w", err))
 	}
-	return s.completeLogin(ctx, u)
+	return s.completeLogin(ctx, u, in.Session)
 }
 
 func validPKCEVerifier(verifier, challenge string) bool {

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

@@ -124,6 +124,8 @@ type ServicePort interface {
 	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()
@@ -552,8 +578,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 +604,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/ports/repository.go.hbs

@@ -36,16 +36,30 @@ 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)
 }
 
@@ -76,6 +90,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/AGENTS.md.hbs

@@ -180,6 +180,12 @@ approval before changing their contract.
   tombstone. Its inactivity expiry may move on rotation, but its persisted
   absolute expiry never moves. Never replace it with a read-then-delete
   sequence.
+- Authenticated users can inspect active refresh sessions through
+  `GET /users/me/sessions` and revoke one with
+  `DELETE /users/me/sessions/:id`. Session IDs remain stable through refresh
+  rotation; responses expose only User-Agent and lifecycle timestamps, never
+  refresh tokens or token hashes. The current access token carries the session
+  ID as `sid` so the adapter can mark the current device.
 - Password reset and email verification consume a one-time token in the same
   retry-safe transaction as the user/identity update. A failed post-commit
   session revocation must not make a successful reset impossible to retry.

package/templates/create/base/README.md.hbs

@@ -194,6 +194,10 @@ nonce; the frontend still owns the callback route and sends the code to the
 exchange endpoint. The provider redirect URI is separate from
 `CORS_ALLOWED_ORIGINS`; the latter remains an exact-origin credentialed API
 policy. Token responses use `Cache-Control: no-store` and `Pragma: no-cache`.
+Authenticated users can list active device sessions with
+`GET /users/me/sessions` and revoke an individual session with
+`DELETE /users/me/sessions/:id`; only User-Agent and session lifecycle
+timestamps are returned.
 For `cross-site`, configure HTTPS origins, `COOKIE_SAMESITE=none`,
 `COOKIE_SECURE=true`, and an exact allowed Origin; the API applies an Origin
 guard independently of CORS.