feat(auth): implement master key authentication system with child key issuance

Add admin and master authentication layers with JWT support. Replace direct
key creation with hierarchical master/child key system. Update database
schema to support master accounts with configurable limits and epoch-based
key revocation. Add health check endpoint with system status monitoring.

BREAKING CHANGE: Removed direct POST /keys endpoint in favor of master-based
key issuance through /v1/tokens. Database migration requires dropping old User
table and creating Master table with new relationships.

internal/api/admin_handler.go

@@ -0,0 +1,54 @@
+package api
+
+import (
+	"net/http"
+
+	"github.com/ez-api/ez-api/internal/service"
+	"github.com/gin-gonic/gin"
+)
+
+type AdminHandler struct {
+	masterService *service.MasterService
+}
+
+func NewAdminHandler(masterService *service.MasterService) *AdminHandler {
+	return &AdminHandler{masterService: masterService}
+}
+
+type CreateMasterRequest struct {
+	Name         string `json:"name" binding:"required"`
+	Group        string `json:"group" binding:"required"`
+	MaxChildKeys int    `json:"max_child_keys"`
+	GlobalQPS    int    `json:"global_qps"`
+}
+
+func (h *AdminHandler) CreateMaster(c *gin.Context) {
+	var req CreateMasterRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	// Use defaults if not provided
+	if req.MaxChildKeys == 0 {
+		req.MaxChildKeys = 5
+	}
+	if req.GlobalQPS == 0 {
+		req.GlobalQPS = 3
+	}
+
+	master, rawMasterKey, err := h.masterService.CreateMaster(req.Name, req.Group, req.MaxChildKeys, req.GlobalQPS)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to create master key", "details": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusCreated, gin.H{
+		"id":             master.ID,
+		"name":           master.Name,
+		"group":          master.Group,
+		"master_key":     rawMasterKey, // Only show this on creation
+		"max_child_keys": master.MaxChildKeys,
+		"global_qps":     master.GlobalQPS,
+	})
+}

internal/api/handler.go

@@ -22,39 +22,7 @@ func NewHandler(db *gorm.DB, sync *service.SyncService, logger *service.LogWrite
 	return &Handler{db: db, sync: sync, logger: logger}
 }
 
-func (h *Handler) CreateKey(c *gin.Context) {
-	var req dto.KeyDTO
-	if err := c.ShouldBindJSON(&req); err != nil {
-		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
-		return
-	}
-
-	group := strings.TrimSpace(req.Group)
-	if group == "" {
-		group = "default"
-	}
-
-	key := model.Key{
-		KeySecret: req.KeySecret,
-		Group:     group,
-		Balance:   req.Balance,
-		Status:    req.Status,
-		Weight:    req.Weight,
-	}
-
-	if err := h.db.Create(&key).Error; err != nil {
-		c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to create key", "details": err.Error()})
-		return
-	}
-
-	// Write auth hash and refresh snapshots
-	if err := h.sync.SyncKey(&key); err != nil {
-		c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to sync key to Redis", "details": err.Error()})
-		return
-	}
-
-	c.JSON(http.StatusCreated, key)
-}
+// CreateKey is now handled by MasterHandler
 
 func (h *Handler) CreateProvider(c *gin.Context) {
 	var req dto.ProviderDTO

internal/api/master_handler.go

@@ -0,0 +1,64 @@
+package api
+
+import (
+	"net/http"
+	"strings"
+
+	"github.com/ez-api/ez-api/internal/model"
+	"github.com/ez-api/ez-api/internal/service"
+	"github.com/gin-gonic/gin"
+)
+
+type MasterHandler struct {
+	masterService *service.MasterService
+}
+
+func NewMasterHandler(masterService *service.MasterService) *MasterHandler {
+	return &MasterHandler{masterService: masterService}
+}
+
+type IssueChildKeyRequest struct {
+	Group  string `json:"group"`
+	Scopes string `json:"scopes"`
+}
+
+func (h *MasterHandler) IssueChildKey(c *gin.Context) {
+	master, exists := c.Get("master")
+	if !exists {
+		c.JSON(http.StatusUnauthorized, gin.H{"error": "master key not found in context"})
+		return
+	}
+	masterModel := master.(*model.Master)
+
+	var req IssueChildKeyRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	// If group is not specified, inherit from master
+	group := req.Group
+	if strings.TrimSpace(group) == "" {
+		group = masterModel.Group
+	}
+
+	// Security: Ensure the requested group is allowed for this master.
+	// For now, we'll just enforce it's the same group.
+	if group != masterModel.Group {
+		c.JSON(http.StatusForbidden, gin.H{"error": "cannot issue key for a different group"})
+		return
+	}
+
+	key, rawChildKey, err := h.masterService.IssueChildKey(masterModel.ID, group, req.Scopes)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to issue child key", "details": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusCreated, gin.H{
+		"id":         key.ID,
+		"key_secret": rawChildKey,
+		"group":      key.Group,
+		"scopes":     key.Scopes,
+	})
+}