feat: add licensing and access controls

internal/handler/admin.go

@@ -2,10 +2,14 @@
 package handler
 
 import (
+	"context"
+	"errors"
 	"net/http"
+	"strings"
 
 	"github.com/gin-gonic/gin"
 
+	"github.com/ShukeBta/MediaStationGo/internal/model"
 	"github.com/ShukeBta/MediaStationGo/internal/service"
 )
 
@@ -16,12 +20,110 @@ func listUsersHandler(svc *service.Container) gin.HandlerFunc {
 			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 			return
 		}
+		if err := annotateProtectedUsers(c.Request.Context(), svc, users); err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
 		c.JSON(http.StatusOK, users)
 	}
 }
 
+type adminCreateUserReq struct {
+	Username string `json:"username" binding:"required"`
+	Password string `json:"password" binding:"required"`
+}
+
+func createUserHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		var req adminCreateUserReq
+		if err := c.ShouldBindJSON(&req); err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+			return
+		}
+		u, _, err := svc.Auth.Register(c.Request.Context(), req.Username, req.Password)
+		if err != nil {
+			writeUserMutationError(c, err)
+			return
+		}
+		// Admin-created users are intentionally normal viewers by default.
+		// They can log in from Web/Emby-compatible clients and play media, but
+		// cannot scrape, scan, download, delete, export NFO, or manage files.
+		if u.Role != "user" {
+			u, err = svc.Profile.AdminUpdateRole(c.Request.Context(), u.ID, "user")
+			if err != nil {
+				c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+				return
+			}
+		}
+		c.JSON(http.StatusCreated, u)
+	}
+}
+
+type adminUpdateUserReq struct {
+	Username string `json:"username" binding:"required"`
+}
+
+func updateUserHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		var req adminUpdateUserReq
+		if err := c.ShouldBindJSON(&req); err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+			return
+		}
+		nextUsername := strings.TrimSpace(req.Username)
+		if nextUsername == "" {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "username required"})
+			return
+		}
+		userID := c.Param("id")
+		user, err := svc.Repo.User.FindByID(c.Request.Context(), userID)
+		if err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		if user == nil {
+			c.JSON(http.StatusNotFound, gin.H{"error": "user not found"})
+			return
+		}
+		if existing, err := svc.Repo.User.FindByUsername(c.Request.Context(), nextUsername); err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		} else if existing != nil && existing.ID != userID {
+			writeUserMutationError(c, service.ErrUsernameTaken)
+			return
+		}
+		updates := map[string]any{"username": nextUsername}
+		if firstAdmin, err := svc.Repo.User.FirstAdmin(c.Request.Context()); err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		} else if firstAdmin != nil && firstAdmin.ID == userID {
+			updates["role"] = "admin"
+			updates["tier"] = "plus"
+		}
+		if err := svc.Repo.User.UpdateFields(c.Request.Context(), userID, updates); err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		updated, err := svc.Repo.User.FindByID(c.Request.Context(), userID)
+		if err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusOK, updated)
+	}
+}
+
 func deleteUserHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
+		firstAdmin, err := svc.Repo.User.FirstAdmin(c.Request.Context())
+		if err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		if firstAdmin != nil && firstAdmin.ID == c.Param("id") {
+			c.JSON(http.StatusForbidden, gin.H{"error": "default admin cannot be deleted"})
+			return
+		}
 		if err := svc.Repo.User.Delete(c.Request.Context(), c.Param("id")); err != nil {
 			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 			return
@@ -30,6 +132,33 @@ func deleteUserHandler(svc *service.Container) gin.HandlerFunc {
 	}
 }
 
+func annotateProtectedUsers(ctx context.Context, svc *service.Container, users []model.User) error {
+	firstAdmin, err := svc.Repo.User.FirstAdmin(ctx)
+	if err != nil || firstAdmin == nil {
+		return err
+	}
+	for i := range users {
+		if users[i].ID == firstAdmin.ID {
+			users[i].IsDefaultAdmin = true
+			users[i].IsProtected = true
+			users[i].Role = "admin"
+			users[i].Tier = "plus"
+		}
+	}
+	return nil
+}
+
+func writeUserMutationError(c *gin.Context, err error) {
+	switch {
+	case errors.Is(err, service.ErrUsernameTaken):
+		c.JSON(http.StatusConflict, gin.H{"error": "username already taken"})
+	case errors.Is(err, service.ErrUserLimitReached):
+		c.JSON(http.StatusBadRequest, gin.H{"error": "user limit reached: maximum 20 users"})
+	default:
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+	}
+}
+
 type settingReq struct {
 	Key   string `json:"key" binding:"required"`
 	Value string `json:"value"`

internal/handler/ai.go

@@ -39,6 +39,7 @@ func smartSearchHandler(svc *service.Container) gin.HandlerFunc {
 			svc.Douban,
 			svc.Bangumi,
 		)
+		service.EnrichExternalMediaAvailability(c.Request.Context(), svc.Repo, external)
 		c.JSON(http.StatusOK, gin.H{
 			"intent":         intent,
 			"items":          items,

internal/handler/handler.go

@@ -47,6 +47,11 @@ func Register(r *gin.Engine, cfg *config.Config, log *zap.Logger, svc *service.C
 			// Permissions.
 			authed.GET("/auth/permissions", getMyPermissionsHandler(svc))
 
+			// License activation bridge (admin only; talks to MediaStationLicenseServer).
+			authed.GET("/license/status", middleware.AdminRequired(), licenseStatusHandler(svc))
+			authed.POST("/license/activate", middleware.AdminRequired(), licenseActivateHandler(svc))
+			authed.POST("/license/heartbeat", middleware.AdminRequired(), licenseHeartbeatHandler(svc))
+
 			// Libraries.
 			authed.GET("/libraries", listLibrariesHandler(svc))
 			authed.POST("/libraries", middleware.AdminRequired(), createLibraryHandler(svc))
@@ -95,35 +100,35 @@ func Register(r *gin.Engine, cfg *config.Config, log *zap.Logger, svc *service.C
 			authed.DELETE("/playlists/:id", deletePlaylistHandler(svc))
 
 			// Downloads.
-			authed.GET("/downloads", listDownloadsHandler(svc))
-			authed.POST("/downloads", addDownloadHandler(svc))
-			authed.DELETE("/downloads/:hash", middleware.AdminRequired(), deleteDownloadHandler(svc))
-			authed.POST("/downloads/reload", middleware.AdminRequired(), reloadDownloadConfigHandler(svc))
+			authed.GET("/downloads", requirePermission(svc, "can_manage_downloads"), listDownloadsHandler(svc))
+			authed.POST("/downloads", requirePermission(svc, "can_manage_downloads"), addDownloadHandler(svc))
+			authed.DELETE("/downloads/:hash", requirePermission(svc, "can_manage_downloads"), deleteDownloadHandler(svc))
+			authed.POST("/downloads/reload", requirePermission(svc, "can_manage_downloads"), reloadDownloadConfigHandler(svc))
 
 			// Subscriptions.
-			authed.GET("/subscriptions", listSubscriptionsHandler(svc))
-			authed.POST("/subscriptions", createSubscriptionHandler(svc))
-			authed.DELETE("/subscriptions/:id", deleteSubscriptionHandler(svc))
-			authed.POST("/subscriptions/:id/run", runSubscriptionHandler(svc))
+			authed.GET("/subscriptions", requirePermission(svc, "can_manage_subscriptions"), listSubscriptionsHandler(svc))
+			authed.POST("/subscriptions", requirePermission(svc, "can_manage_subscriptions"), createSubscriptionHandler(svc))
+			authed.DELETE("/subscriptions/:id", requirePermission(svc, "can_manage_subscriptions"), deleteSubscriptionHandler(svc))
+			authed.POST("/subscriptions/:id/run", requirePermission(svc, "can_manage_subscriptions"), runSubscriptionHandler(svc))
 
 			// Stats / dashboard.
 			authed.GET("/stats", statsHandler(svc))
-			authed.GET("/tasks", tasksHandler(svc))
+			authed.GET("/tasks", middleware.AdminRequired(), tasksHandler(svc))
 
 			// Discover (TMDb trending / popular).
-			authed.GET("/discover/trending", trendingHandler(svc))
-			authed.GET("/discover/popular", popularHandler(svc))
+			authed.GET("/discover/trending", requirePermission(svc, "can_view_discover"), trendingHandler(svc))
+			authed.GET("/discover/popular", requirePermission(svc, "can_view_discover"), popularHandler(svc))
 
 			// AI.
-			authed.GET("/ai/status", aiStatusHandler(svc))
-			authed.POST("/ai/search", smartSearchHandler(svc))
-			authed.GET("/ai/recommend", aiRecommendHandler(svc))
+			authed.GET("/ai/status", requirePermission(svc, "can_use_ai"), aiStatusHandler(svc))
+			authed.POST("/ai/search", requirePermission(svc, "can_use_ai"), smartSearchHandler(svc))
+			authed.GET("/ai/recommend", requirePermission(svc, "can_use_ai"), aiRecommendHandler(svc))
 
 			// File browser (used by the library-path picker).
-			authed.GET("/files", browseFilesHandler(svc))
+			authed.GET("/files", middleware.AdminRequired(), browseFilesHandler(svc))
 
 			// Disk usage breakdown.
-			authed.GET("/storage", storageHandler(svc))
+			authed.GET("/storage", middleware.AdminRequired(), storageHandler(svc))
 
 			// DLNA discovery + cast.
 			authed.GET("/dlna/devices", dlnaListHandler(svc))
@@ -141,15 +146,15 @@ func Register(r *gin.Engine, cfg *config.Config, log *zap.Logger, svc *service.C
 
 			// Site management + cross-site torrent search (via SiteHandler).
 			siteHandler := NewSiteHandler(svc)
-			authed.GET("/sites", siteHandler.ListSites)
-			authed.GET("/sites/types", siteHandler.GetSiteTypes)
-			authed.GET("/sites/auth-types", siteHandler.GetAuthTypes)
-			authed.POST("/sites", middleware.AdminRequired(), siteHandler.CreateSite)
-			authed.GET("/sites/:id", siteHandler.GetSite)
-			authed.PUT("/sites/:id", middleware.AdminRequired(), siteHandler.UpdateSite)
-			authed.DELETE("/sites/:id", middleware.AdminRequired(), siteHandler.DeleteSite)
-			authed.POST("/sites/:id/test", middleware.AdminRequired(), siteHandler.TestSite)
-			authed.GET("/sites/search", siteSearchHandler(svc))
+			authed.GET("/sites", requirePermission(svc, "can_manage_sites"), siteHandler.ListSites)
+			authed.GET("/sites/types", requirePermission(svc, "can_manage_sites"), siteHandler.GetSiteTypes)
+			authed.GET("/sites/auth-types", requirePermission(svc, "can_manage_sites"), siteHandler.GetAuthTypes)
+			authed.POST("/sites", requirePermission(svc, "can_manage_sites"), siteHandler.CreateSite)
+			authed.GET("/sites/:id", requirePermission(svc, "can_manage_sites"), siteHandler.GetSite)
+			authed.PUT("/sites/:id", requirePermission(svc, "can_manage_sites"), siteHandler.UpdateSite)
+			authed.DELETE("/sites/:id", requirePermission(svc, "can_manage_sites"), siteHandler.DeleteSite)
+			authed.POST("/sites/:id/test", requirePermission(svc, "can_manage_sites"), siteHandler.TestSite)
+			authed.GET("/sites/search", requirePermission(svc, "can_manage_sites"), siteSearchHandler(svc))
 
 			// Recycle bin.
 			authed.GET("/recycle", middleware.AdminRequired(), listRecycleHandler(svc))
@@ -176,8 +181,8 @@ func Register(r *gin.Engine, cfg *config.Config, log *zap.Logger, svc *service.C
 			authed.DELETE("/watch-history/:id", historyDeleteOneHandler(svc))
 
 			// Multi-section TMDb feed used by DiscoverPage.
-			authed.GET("/discover/sections", discoverSectionsHandler(svc))
-			authed.GET("/discover/feed", discoverFeedHandler(svc))
+			authed.GET("/discover/sections", requirePermission(svc, "can_view_discover"), discoverSectionsHandler(svc))
+			authed.GET("/discover/feed", requirePermission(svc, "can_view_discover"), discoverFeedHandler(svc))
 
 			// System metadata + read-only scheduler view.
 			authed.GET("/system/info", systemInfoHandler(svc))
@@ -214,12 +219,12 @@ func Register(r *gin.Engine, cfg *config.Config, log *zap.Logger, svc *service.C
 			authed.POST("/stats/play", statsPlayHandler(svc))
 
 			// ── Sites extras ──
-			authed.GET("/sites/:id/resource", siteResourceHandler(svc))
-			authed.GET("/sites/:id/userdata", siteUserdataHandler(svc))
+			authed.GET("/sites/:id/resource", requirePermission(svc, "can_manage_sites"), siteResourceHandler(svc))
+			authed.GET("/sites/:id/userdata", requirePermission(svc, "can_manage_sites"), siteUserdataHandler(svc))
 
 			// ── Subscription extras ──
-			authed.PUT("/subscriptions/:id", updateSubscriptionHandler(svc))
-			authed.POST("/subscriptions/:id/search", searchSubscriptionHandler(svc))
+			authed.PUT("/subscriptions/:id", requirePermission(svc, "can_manage_subscriptions"), updateSubscriptionHandler(svc))
+			authed.POST("/subscriptions/:id/search", requirePermission(svc, "can_manage_subscriptions"), searchSubscriptionHandler(svc))
 
 			// ── Playlist extras ──
 			authed.POST("/playlists/:id/reorder", reorderPlaylistHandler(svc))
@@ -236,9 +241,9 @@ func Register(r *gin.Engine, cfg *config.Config, log *zap.Logger, svc *service.C
 			authed.POST("/media/:id/favorite", addMediaFavoriteHandler(svc))
 			authed.DELETE("/media/:id/favorite", removeMediaFavoriteHandler(svc))
 			authed.GET("/media/:id/favorite/status", getMediaFavoriteStatusHandler(svc))
-			authed.POST("/media/:id/ai-scrape", aiScrapeMediaHandler(svc))
-			authed.POST("/media/scrape/test", scrapeTestHandler(svc))
-			authed.POST("/media/organize", middleware.AdminRequired(), organizeBulkHandler(svc))
+			authed.POST("/media/:id/ai-scrape", requirePermission(svc, "can_rescrape"), aiScrapeMediaHandler(svc))
+			authed.POST("/media/scrape/test", requirePermission(svc, "can_rescrape"), scrapeTestHandler(svc))
+			authed.POST("/media/organize", requirePermission(svc, "can_manage_files"), organizeBulkHandler(svc))
 
 			// ── Playback metadata + external player handoff ──
 			authed.GET("/playback/:id/info", playbackInfoHandler(svc))
@@ -248,13 +253,13 @@ func Register(r *gin.Engine, cfg *config.Config, log *zap.Logger, svc *service.C
 			authed.GET("/playback/transcode/:job_id/status", transcodeStatusHandler(svc))
 
 			// ── Download task ops + sync triggers ──
-			authed.POST("/download/:id/pause", downloadPauseHandler(svc))
-			authed.POST("/download/:id/resume", downloadResumeHandler(svc))
-			authed.POST("/download/:id/organize", middleware.AdminRequired(), downloadOrganizeOneHandler(svc))
-			authed.POST("/download/organize", middleware.AdminRequired(), downloadOrganizeAllHandler(svc))
-			authed.POST("/download/sync", middleware.AdminRequired(), downloadSyncHandler(svc))
-			authed.POST("/download/start-auto-sync", middleware.AdminRequired(), downloadAutoSyncHandler(svc))
-			authed.GET("/download/tasks", downloadTasksAliasHandler(svc))
+			authed.POST("/download/:id/pause", requirePermission(svc, "can_manage_downloads"), downloadPauseHandler(svc))
+			authed.POST("/download/:id/resume", requirePermission(svc, "can_manage_downloads"), downloadResumeHandler(svc))
+			authed.POST("/download/:id/organize", requirePermission(svc, "can_manage_files"), downloadOrganizeOneHandler(svc))
+			authed.POST("/download/organize", requirePermission(svc, "can_manage_files"), downloadOrganizeAllHandler(svc))
+			authed.POST("/download/sync", requirePermission(svc, "can_manage_downloads"), downloadSyncHandler(svc))
+			authed.POST("/download/start-auto-sync", requirePermission(svc, "can_manage_downloads"), downloadAutoSyncHandler(svc))
+			authed.GET("/download/tasks", requirePermission(svc, "can_manage_downloads"), downloadTasksAliasHandler(svc))
 
 			// ── Assistant (multi-turn AI chat) ──
 			authed.GET("/admin/assistant/sessions", listAssistantSessionsHandler(svc))
@@ -272,6 +277,8 @@ func Register(r *gin.Engine, cfg *config.Config, log *zap.Logger, svc *service.C
 		admin.Use(middleware.AuthRequired(cfg.Secrets.JWTSecret), middleware.AdminRequired())
 		{
 			admin.GET("/users", listUsersHandler(svc))
+			admin.POST("/users", createUserHandler(svc))
+			admin.PATCH("/users/:id", updateUserHandler(svc))
 			admin.PATCH("/users/:id/role", adminUpdateRoleHandler(svc))
 			admin.DELETE("/users/:id", deleteUserHandler(svc))
 			admin.GET("/settings", listSettingsHandler(svc))

internal/handler/license.go

@@ -0,0 +1,394 @@
+package handler
+
+import (
+	"bytes"
+	"context"
+	"crypto/hmac"
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"os"
+	"strings"
+	"time"
+
+	"github.com/gin-gonic/gin"
+
+	"github.com/ShukeBta/MediaStationGo/internal/service"
+)
+
+const (
+	licenseServerURLSetting  = "license.server_url"
+	licenseHMACSecretSetting = "license.hmac_secret"
+	licenseDeviceIDSetting   = "license.device_id"
+	licenseDeviceNameSetting = "license.device_name"
+)
+
+type licenseActivateReq struct {
+	Key        string `json:"key" binding:"required"`
+	DeviceID   string `json:"device_id"`
+	DeviceName string `json:"device_name"`
+}
+
+type licenseServerSignedResp struct {
+	Valid         bool    `json:"valid"`
+	LicenseType   string  `json:"license_type"`
+	ExpiryDate    *string `json:"expiry_date"`
+	MaxDevices    int     `json:"max_devices"`
+	DaysRemaining *int    `json:"days_remaining"`
+	NextHeartbeat string  `json:"next_heartbeat"`
+	Signature     string  `json:"signature"`
+}
+
+type licenseServerStatusResp struct {
+	Valid         bool    `json:"valid"`
+	LicenseType   *string `json:"license_type"`
+	ExpiryDate    *string `json:"expiry_date"`
+	DaysRemaining *int    `json:"days_remaining"`
+	DeviceName    string  `json:"device_name"`
+	IsActive      bool    `json:"is_active"`
+}
+
+func licenseActivateHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		var req licenseActivateReq
+		if err := c.ShouldBindJSON(&req); err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+			return
+		}
+		client, err := newLicenseClient(c.Request.Context(), svc)
+		if err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+			return
+		}
+		deviceID, err := ensureLicenseDeviceID(c.Request.Context(), svc, req.DeviceID)
+		if err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		deviceName := strings.TrimSpace(req.DeviceName)
+		if deviceName == "" {
+			deviceName = defaultLicenseDeviceName()
+		}
+		_ = svc.Repo.Setting.Set(c.Request.Context(), licenseDeviceNameSetting, deviceName)
+
+		payload := map[string]any{
+			"key":         strings.TrimSpace(req.Key),
+			"fingerprint": deviceID,
+			"device_name": deviceName,
+			"instance_id": deviceID,
+		}
+		var upstream licenseServerSignedResp
+		if err := client.post(c.Request.Context(), "/api/v1/activate", payload, &upstream); err != nil {
+			c.JSON(http.StatusBadGateway, gin.H{"error": err.Error()})
+			return
+		}
+		if err := client.verifySigned(upstream); err != nil {
+			c.JSON(http.StatusBadGateway, gin.H{"error": err.Error()})
+			return
+		}
+		state := licenseStateFromSigned(upstream, deviceID, deviceName)
+		if err := persistLicenseState(c.Request.Context(), svc, state); err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusOK, licenseActivationView(state))
+	}
+}
+
+func licenseStatusHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		state, _ := loadLicenseState(c.Request.Context(), svc)
+		client, err := newLicenseClient(c.Request.Context(), svc)
+		if err == nil {
+			deviceID, idErr := ensureLicenseDeviceID(c.Request.Context(), svc, "")
+			if idErr == nil {
+				var upstream licenseServerStatusResp
+				if getErr := client.get(c.Request.Context(), "/api/v1/status/"+url.PathEscape(deviceID), &upstream); getErr == nil && upstream.Valid {
+					state.Valid = upstream.Valid
+					if upstream.LicenseType != nil {
+						state.LicenseType = *upstream.LicenseType
+					}
+					if upstream.ExpiryDate != nil {
+						state.ExpiryDate = *upstream.ExpiryDate
+					}
+					state.DaysRemaining = upstream.DaysRemaining
+					if upstream.DeviceName != "" {
+						state.DeviceName = upstream.DeviceName
+					}
+					state.DeviceID = deviceID
+					state.UpdatedAt = time.Now().Format(time.RFC3339)
+					_ = persistLicenseState(c.Request.Context(), svc, state)
+				} else if getErr == nil && !upstream.Valid {
+					state.Valid = false
+					_ = persistLicenseState(c.Request.Context(), svc, state)
+				}
+			}
+		}
+		active := state.Valid && !licenseStateExpired(state.ExpiryDate)
+		c.JSON(http.StatusOK, gin.H{
+			"active":     active,
+			"message":    licenseStatusMessage(active, err),
+			"max_users":  service.LicensedMaxUsers(c.Request.Context(), svc.Repo),
+			"activation": licenseActivationView(state),
+		})
+	}
+}
+
+func licenseHeartbeatHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		client, err := newLicenseClient(c.Request.Context(), svc)
+		if err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+			return
+		}
+		deviceID, err := ensureLicenseDeviceID(c.Request.Context(), svc, "")
+		if err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		var upstream licenseServerSignedResp
+		if err := client.post(c.Request.Context(), "/api/v1/heartbeat", map[string]any{
+			"fingerprint": deviceID,
+			"instance_id": deviceID,
+		}, &upstream); err != nil {
+			c.JSON(http.StatusBadGateway, gin.H{"error": err.Error()})
+			return
+		}
+		if err := client.verifySigned(upstream); err != nil {
+			c.JSON(http.StatusBadGateway, gin.H{"error": err.Error()})
+			return
+		}
+		deviceName, _ := svc.Repo.Setting.Get(c.Request.Context(), licenseDeviceNameSetting)
+		state := licenseStateFromSigned(upstream, deviceID, deviceName)
+		if err := persistLicenseState(c.Request.Context(), svc, state); err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusOK, licenseActivationView(state))
+	}
+}
+
+type licenseClient struct {
+	baseURL    string
+	hmacSecret string
+	httpClient *http.Client
+}
+
+func newLicenseClient(ctx context.Context, svc *service.Container) (*licenseClient, error) {
+	baseURL, _ := svc.Repo.Setting.Get(ctx, licenseServerURLSetting)
+	if strings.TrimSpace(baseURL) == "" {
+		baseURL = svc.Cfg.License.ServerURL
+	}
+	secret, _ := svc.Repo.Setting.Get(ctx, licenseHMACSecretSetting)
+	if strings.TrimSpace(secret) == "" {
+		secret = svc.Cfg.License.HMACSecret
+	}
+	baseURL = strings.TrimRight(strings.TrimSpace(baseURL), "/")
+	if baseURL == "" {
+		return nil, errors.New("license server url not configured")
+	}
+	return &licenseClient{
+		baseURL:    baseURL,
+		hmacSecret: strings.TrimSpace(secret),
+		httpClient: &http.Client{Timeout: 15 * time.Second},
+	}, nil
+}
+
+func (c *licenseClient) post(ctx context.Context, path string, payload any, out any) error {
+	body, err := json.Marshal(payload)
+	if err != nil {
+		return err
+	}
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.baseURL+path, bytes.NewReader(body))
+	if err != nil {
+		return err
+	}
+	req.Header.Set("Content-Type", "application/json")
+	return c.do(req, out)
+}
+
+func (c *licenseClient) get(ctx context.Context, path string, out any) error {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, c.baseURL+path, nil)
+	if err != nil {
+		return err
+	}
+	return c.do(req, out)
+}
+
+func (c *licenseClient) do(req *http.Request, out any) error {
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+	data, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return err
+	}
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		var er struct {
+			Error   string `json:"error"`
+			Message string `json:"message"`
+		}
+		_ = json.Unmarshal(data, &er)
+		if er.Message != "" {
+			return fmt.Errorf("license server: %s", er.Message)
+		}
+		if er.Error != "" {
+			return fmt.Errorf("license server: %s", er.Error)
+		}
+		return fmt.Errorf("license server http %d", resp.StatusCode)
+	}
+	return json.Unmarshal(data, out)
+}
+
+func (c *licenseClient) verifySigned(resp licenseServerSignedResp) error {
+	if c.hmacSecret == "" {
+		return nil
+	}
+	unsigned := struct {
+		Valid         bool    `json:"valid"`
+		LicenseType   string  `json:"license_type"`
+		ExpiryDate    *string `json:"expiry_date"`
+		MaxDevices    int     `json:"max_devices"`
+		DaysRemaining *int    `json:"days_remaining"`
+		NextHeartbeat string  `json:"next_heartbeat"`
+	}{
+		Valid:         resp.Valid,
+		LicenseType:   resp.LicenseType,
+		ExpiryDate:    resp.ExpiryDate,
+		MaxDevices:    resp.MaxDevices,
+		DaysRemaining: resp.DaysRemaining,
+		NextHeartbeat: resp.NextHeartbeat,
+	}
+	payload, err := json.Marshal(unsigned)
+	if err != nil {
+		return err
+	}
+	mac := hmac.New(sha256.New, []byte(c.hmacSecret))
+	_, _ = mac.Write(payload)
+	expected := hex.EncodeToString(mac.Sum(nil))
+	if !hmac.Equal([]byte(expected), []byte(resp.Signature)) {
+		return errors.New("license server signature verification failed")
+	}
+	return nil
+}
+
+func ensureLicenseDeviceID(ctx context.Context, svc *service.Container, candidate string) (string, error) {
+	if strings.TrimSpace(candidate) != "" {
+		return strings.TrimSpace(candidate), svc.Repo.Setting.Set(ctx, licenseDeviceIDSetting, strings.TrimSpace(candidate))
+	}
+	existing, err := svc.Repo.Setting.Get(ctx, licenseDeviceIDSetting)
+	if err != nil {
+		return "", err
+	}
+	if strings.TrimSpace(existing) != "" {
+		return strings.TrimSpace(existing), nil
+	}
+	var buf [16]byte
+	if _, err := rand.Read(buf[:]); err != nil {
+		return "", err
+	}
+	id := "msgo-" + hex.EncodeToString(buf[:])
+	return id, svc.Repo.Setting.Set(ctx, licenseDeviceIDSetting, id)
+}
+
+func defaultLicenseDeviceName() string {
+	host, _ := os.Hostname()
+	if strings.TrimSpace(host) == "" {
+		return "MediaStationGo Server"
+	}
+	return "MediaStationGo - " + host
+}
+
+func licenseStateFromSigned(resp licenseServerSignedResp, deviceID, deviceName string) service.LicenseActivationState {
+	expiry := ""
+	if resp.ExpiryDate != nil {
+		expiry = *resp.ExpiryDate
+	}
+	return service.LicenseActivationState{
+		Valid:         resp.Valid,
+		LicenseType:   resp.LicenseType,
+		ExpiryDate:    expiry,
+		MaxDevices:    resp.MaxDevices,
+		DaysRemaining: resp.DaysRemaining,
+		NextHeartbeat: resp.NextHeartbeat,
+		DeviceID:      deviceID,
+		DeviceName:    deviceName,
+		UpdatedAt:     time.Now().Format(time.RFC3339),
+	}
+}
+
+func persistLicenseState(ctx context.Context, svc *service.Container, state service.LicenseActivationState) error {
+	data, err := json.Marshal(state)
+	if err != nil {
+		return err
+	}
+	return svc.Repo.Setting.Set(ctx, service.LicenseSettingActivation, string(data))
+}
+
+func loadLicenseState(ctx context.Context, svc *service.Container) (service.LicenseActivationState, error) {
+	raw, err := svc.Repo.Setting.Get(ctx, service.LicenseSettingActivation)
+	if err != nil || raw == "" {
+		return service.LicenseActivationState{}, err
+	}
+	var state service.LicenseActivationState
+	if err := json.Unmarshal([]byte(raw), &state); err != nil {
+		return service.LicenseActivationState{}, err
+	}
+	return state, nil
+}
+
+func licenseActivationView(state service.LicenseActivationState) gin.H {
+	updatedAt := state.UpdatedAt
+	if strings.TrimSpace(updatedAt) == "" {
+		updatedAt = time.Now().Format(time.RFC3339)
+	}
+	return gin.H{
+		"id":              state.DeviceID,
+		"key_id":          state.LicenseType,
+		"device_id":       state.DeviceID,
+		"device_name":     state.DeviceName,
+		"plan":            state.LicenseType,
+		"max_activations": state.MaxDevices,
+		"expires_at":      emptyAsNil(state.ExpiryDate),
+		"valid":           state.Valid && !licenseStateExpired(state.ExpiryDate),
+		"heartbeat_at":    updatedAt,
+		"created_at":      updatedAt,
+	}
+}
+
+func licenseStatusMessage(active bool, clientErr error) string {
+	if active {
+		return "已激活"
+	}
+	if clientErr != nil && !strings.Contains(clientErr.Error(), "not configured") {
+		return clientErr.Error()
+	}
+	return "开源版：最多 20 个用户"
+}
+
+func licenseStateExpired(expiry string) bool {
+	if expiry == "" {
+		return false
+	}
+	for _, layout := range []string{time.RFC3339, "2006-01-02 15:04:05", "2006-01-02"} {
+		if t, err := time.Parse(layout, expiry); err == nil {
+			return time.Now().After(t)
+		}
+	}
+	return false
+}
+
+func emptyAsNil(v string) any {
+	if strings.TrimSpace(v) == "" {
+		return nil
+	}
+	return v
+}

internal/handler/permissions.go

@@ -16,6 +16,32 @@ import (
 	"github.com/ShukeBta/MediaStationGo/internal/service"
 )
 
+func requirePermission(svc *service.Container, key string) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		role, _ := c.Get(middleware.CtxUserRole)
+		if role == "admin" {
+			c.Next()
+			return
+		}
+		uid, _ := c.Get(middleware.CtxUserID)
+		userID, _ := uid.(string)
+		if userID == "" {
+			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "authentication required"})
+			return
+		}
+		row, err := svc.Permissions.Effective(c.Request.Context(), userID)
+		if err != nil {
+			c.AbortWithStatusJSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		if row == nil || !row.PermissionMap()[key] {
+			c.AbortWithStatusJSON(http.StatusForbidden, gin.H{"error": "permission denied"})
+			return
+		}
+		c.Next()
+	}
+}
+
 func myPermissionsHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
 		uid, _ := c.Get(middleware.CtxUserID)

internal/handler/playback_extra.go

@@ -9,6 +9,8 @@ package handler
 
 import (
 	"net/http"
+	"net/url"
+	"strings"
 
 	"github.com/gin-gonic/gin"
 
@@ -27,9 +29,9 @@ func playbackInfoHandler(svc *service.Container) gin.HandlerFunc {
 			return
 		}
 		c.JSON(http.StatusOK, gin.H{
-			"media":       m,
-			"stream_url":  "/api/stream/" + m.ID,
-			"hls_url":     "/api/hls/" + m.ID + "/index.m3u8",
+			"media":      m,
+			"stream_url": "/api/stream/" + m.ID,
+			"hls_url":    "/api/hls/" + m.ID + "/index.m3u8",
 		})
 	}
 }
@@ -69,13 +71,16 @@ func externalPlayersHandler(svc *service.Container) gin.HandlerFunc {
 			c.JSON(http.StatusNotFound, gin.H{"error": "media not found"})
 			return
 		}
-		streamURL := "/api/stream/" + m.ID
+		token := externalPlaybackToken(c, svc)
+		streamURL := absoluteRequestURL(c, "/api/stream/"+m.ID+"?token="+url.QueryEscape(token))
+		escapedStream := url.QueryEscape(streamURL)
 		c.JSON(http.StatusOK, gin.H{
+			"url": streamURL,
 			"players": []gin.H{
 				{"name": "VLC", "scheme": "vlc://", "url": "vlc://" + streamURL},
 				{"name": "PotPlayer", "scheme": "potplayer://", "url": "potplayer://" + streamURL},
 				{"name": "MX Player", "scheme": "intent://", "url": "intent://" + streamURL + "#Intent;package=com.mxtech.videoplayer.ad;end"},
-				{"name": "IINA", "scheme": "iina://", "url": "iina://weblink?url=" + streamURL},
+				{"name": "IINA", "scheme": "iina://", "url": "iina://weblink?url=" + escapedStream},
 				{"name": "nPlayer", "scheme": "nplayer-", "url": "nplayer-" + streamURL},
 			},
 		})
@@ -91,25 +96,48 @@ func externalURLHandler(svc *service.Container) gin.HandlerFunc {
 			c.JSON(http.StatusNotFound, gin.H{"error": "media not found"})
 			return
 		}
-		// Re-issue a short-lived token for this stream.
-		uid, _ := c.Get(middleware.CtxUserID)
-		u, err := svc.Repo.User.FindByID(c.Request.Context(), toString(uid))
-		if err != nil || u == nil {
-			c.JSON(http.StatusUnauthorized, gin.H{"error": "user not found"})
-			return
-		}
-		token, err := svc.Auth.IssueToken(u)
-		if err != nil {
-			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
-			return
-		}
+		token := externalPlaybackToken(c, svc)
 		c.JSON(http.StatusOK, gin.H{
-			"url":   "/api/stream/" + m.ID + "?token=" + token,
+			"url":   absoluteRequestURL(c, "/api/stream/"+m.ID+"?token="+url.QueryEscape(token)),
 			"token": token,
 		})
 	}
 }
 
+func externalPlaybackToken(c *gin.Context, svc *service.Container) string {
+	uid, _ := c.Get(middleware.CtxUserID)
+	u, err := svc.Repo.User.FindByID(c.Request.Context(), toString(uid))
+	if err != nil || u == nil {
+		return ""
+	}
+	token, err := svc.Auth.IssueToken(u)
+	if err != nil {
+		return ""
+	}
+	return token
+}
+
+func absoluteRequestURL(c *gin.Context, path string) string {
+	if strings.HasPrefix(path, "http://") || strings.HasPrefix(path, "https://") {
+		return path
+	}
+	scheme := strings.TrimSpace(c.GetHeader("X-Forwarded-Proto"))
+	if scheme == "" {
+		scheme = "http"
+		if c.Request.TLS != nil {
+			scheme = "https"
+		}
+	}
+	host := strings.TrimSpace(c.GetHeader("X-Forwarded-Host"))
+	if host == "" {
+		host = c.Request.Host
+	}
+	if !strings.HasPrefix(path, "/") {
+		path = "/" + path
+	}
+	return scheme + "://" + host + path
+}
+
 // transcodeStatusHandler reports the live status of one transcode job.
 // We surface the active jobs the transcoder knows about.
 func transcodeStatusHandler(svc *service.Container) gin.HandlerFunc {

internal/handler/subscription_extra.go

@@ -30,6 +30,7 @@ type subscriptionPatchReq struct {
 	ExcludeWords  *string `json:"exclude_words"`
 	WashEnabled   *bool   `json:"wash_enabled"`
 	WashPriority  *string `json:"wash_priority"`
+	TotalEpisodes *int    `json:"total_episodes"`
 	Priority      *int    `json:"priority"`
 	Enabled       *bool   `json:"enabled"`
 }
@@ -117,6 +118,9 @@ func subscriptionPatchUpdates(patch subscriptionPatchReq) map[string]any {
 	if patch.WashPriority != nil {
 		updates["wash_priority"] = *patch.WashPriority
 	}
+	if patch.TotalEpisodes != nil {
+		updates["total_episodes"] = *patch.TotalEpisodes
+	}
 	if patch.Priority != nil {
 		updates["priority"] = *patch.Priority
 	}

internal/handler/subscriptions.go

@@ -31,6 +31,7 @@ type subscriptionReq struct {
 	ExcludeWords  string `json:"exclude_words"`
 	WashEnabled   bool   `json:"wash_enabled"`
 	WashPriority  string `json:"wash_priority"`
+	TotalEpisodes int    `json:"total_episodes"`
 	Priority      int    `json:"priority"`
 	Enabled       *bool  `json:"enabled"`
 }
@@ -68,6 +69,7 @@ func createSubscriptionHandler(svc *service.Container) gin.HandlerFunc {
 			ExcludeWords:  req.ExcludeWords,
 			WashEnabled:   req.WashEnabled,
 			WashPriority:  req.WashPriority,
+			TotalEpisodes: req.TotalEpisodes,
 			Priority:      req.Priority,
 			Enabled:       enabled,
 		}
@@ -76,6 +78,9 @@ func createSubscriptionHandler(svc *service.Container) gin.HandlerFunc {
 			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 			return
 		}
+		enriched := []model.Subscription{*s}
+		service.EnrichSubscriptionProgress(c.Request.Context(), svc.Repo, enriched)
+		*s = enriched[0]
 		c.JSON(http.StatusOK, s)
 	}
 }
@@ -88,6 +93,7 @@ func listSubscriptionsHandler(svc *service.Container) gin.HandlerFunc {
 			return
 		}
 		enrichAndPersistSubscriptions(c.Request.Context(), svc, items)
+		service.EnrichSubscriptionProgress(c.Request.Context(), svc.Repo, items)
 		c.JSON(http.StatusOK, gin.H{"items": items})
 	}
 }

internal/handler/system_extra.go

@@ -103,6 +103,14 @@ func schemaHandler(_ *service.Container) gin.HandlerFunc {
 						{"key": "qbittorrent.savepath", "type": "text"},
 					},
 				},
+				{
+					"key":   "license",
+					"label": "授权服务",
+					"items": []gin.H{
+						{"key": "license.server_url", "type": "text", "label": "License Server 地址"},
+						{"key": "license.hmac_secret", "type": "text", "label": "HMAC 签名密钥"},
+					},
+				},
 			},
 		})
 	}