feat(api): add admin endpoint to issue keys for masters

Add `POST /admin/masters/{id}/keys` allowing admins to issue child keys
on behalf of a master. Introduce an `issued_by` field in the Key model
to audit whether a key was issued by the master or an admin.

Refactor master service to use typed errors for consistent HTTP status
mapping and ensure validation logic (active status, group check) is
shared.

internal/api/admin_handler.go

@@ -1,7 +1,10 @@
 package api
 
 import (
+	"errors"
 	"net/http"
+	"strconv"
+	"strings"
 
 	"github.com/ez-api/ez-api/internal/service"
 	"github.com/gin-gonic/gin"
@@ -70,3 +73,68 @@ func (h *AdminHandler) CreateMaster(c *gin.Context) {
 		"global_qps":     master.GlobalQPS,
 	})
 }
+
+// IssueChildKeyForMaster godoc
+// @Summary      Issue a child key on behalf of a master
+// @Description  Issue a new access token (child key) for a specified master. The key still belongs to the master; issuer is recorded as admin for audit.
+// @Tags         admin
+// @Accept       json
+// @Produce      json
+// @Security     AdminAuth
+// @Param        id         path      int                  true  "Master ID"
+// @Param        request    body      IssueChildKeyRequest  true  "Key Request"
+// @Success      201        {object}  gin.H
+// @Failure      400        {object}  gin.H
+// @Failure      403        {object}  gin.H
+// @Failure      404        {object}  gin.H
+// @Failure      500        {object}  gin.H
+// @Router       /admin/masters/{id}/keys [post]
+func (h *AdminHandler) IssueChildKeyForMaster(c *gin.Context) {
+	idRaw := strings.TrimSpace(c.Param("id"))
+	if idRaw == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "master id required"})
+		return
+	}
+	idU64, err := strconv.ParseUint(idRaw, 10, 64)
+	if err != nil || idU64 == 0 {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "invalid master id"})
+		return
+	}
+	masterID := uint(idU64)
+
+	var req IssueChildKeyRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	key, rawChildKey, err := h.masterService.IssueChildKeyAsAdmin(masterID, req.Group, req.Scopes)
+	if err != nil {
+		switch {
+		case errors.Is(err, service.ErrMasterNotFound):
+			c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+		case errors.Is(err, service.ErrMasterNotActive):
+			c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
+		case errors.Is(err, service.ErrChildKeyGroupForbidden):
+			c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
+		case errors.Is(err, service.ErrChildKeyLimitReached):
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		default:
+			c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to issue child key", "details": err.Error()})
+		}
+		return
+	}
+
+	if err := h.syncService.SyncKey(key); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to sync child key", "details": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusCreated, gin.H{
+		"id":         key.ID,
+		"key_secret": rawChildKey,
+		"group":      key.Group,
+		"scopes":     key.Scopes,
+		"issued_by":  key.IssuedBy,
+	})
+}

internal/api/admin_issue_key_test.go

@@ -0,0 +1,85 @@
+package api
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/alicebob/miniredis/v2"
+	"github.com/ez-api/ez-api/internal/model"
+	"github.com/ez-api/ez-api/internal/service"
+	"github.com/ez-api/foundation/tokenhash"
+	"github.com/gin-gonic/gin"
+	"github.com/redis/go-redis/v9"
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+)
+
+func TestAdmin_IssueChildKeyForMaster_IssuedByAdminAndSynced(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	db, err := gorm.Open(sqlite.Open("file::memory:?cache=shared"), &gorm.Config{})
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+	if err := db.AutoMigrate(&model.Master{}, &model.Key{}); err != nil {
+		t.Fatalf("migrate: %v", err)
+	}
+
+	mr := miniredis.RunT(t)
+	rdb := redis.NewClient(&redis.Options{Addr: mr.Addr()})
+
+	syncService := service.NewSyncService(rdb)
+	masterService := service.NewMasterService(db)
+	adminHandler := NewAdminHandler(masterService, syncService)
+
+	m, _, err := masterService.CreateMaster("m1", "default", 5, 10)
+	if err != nil {
+		t.Fatalf("CreateMaster: %v", err)
+	}
+
+	r := gin.New()
+	r.POST("/admin/masters/:id/keys", adminHandler.IssueChildKeyForMaster)
+
+	body := []byte(`{"scopes":"chat:write"}`)
+	req := httptest.NewRequest(http.MethodPost, fmt.Sprintf("/admin/masters/%d/keys", m.ID), bytes.NewReader(body))
+	rr := httptest.NewRecorder()
+	r.ServeHTTP(rr, req)
+
+	if rr.Code != http.StatusCreated {
+		t.Fatalf("unexpected status: got=%d body=%s", rr.Code, rr.Body.String())
+	}
+
+	var resp map[string]any
+	if err := json.Unmarshal(rr.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if resp["issued_by"] != "admin" {
+		t.Fatalf("expected issued_by=admin, got=%v", resp["issued_by"])
+	}
+	rawKey, _ := resp["key_secret"].(string)
+	if rawKey == "" {
+		t.Fatalf("expected key_secret in response")
+	}
+
+	// DB audit
+	var keys []model.Key
+	if err := db.Where("master_id = ?", m.ID).Find(&keys).Error; err != nil {
+		t.Fatalf("load keys: %v", err)
+	}
+	if len(keys) != 1 {
+		t.Fatalf("expected 1 key row, got %d", len(keys))
+	}
+	if keys[0].IssuedBy != "admin" {
+		t.Fatalf("expected IssuedBy=admin, got %q", keys[0].IssuedBy)
+	}
+
+	// Redis sync: auth:token:{hash} exists
+	hash := tokenhash.HashToken(rawKey)
+	if !mr.Exists("auth:token:" + hash) {
+		t.Fatalf("expected auth token hash key to exist in redis")
+	}
+}

internal/api/master_handler.go

@@ -1,6 +1,7 @@
 package api
 
 import (
+	"errors"
 	"net/http"
 	"strings"
 
@@ -66,7 +67,18 @@ func (h *MasterHandler) IssueChildKey(c *gin.Context) {
 
 	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()})
+		switch {
+		case errors.Is(err, service.ErrMasterNotFound):
+			c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+		case errors.Is(err, service.ErrMasterNotActive):
+			c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
+		case errors.Is(err, service.ErrChildKeyGroupForbidden):
+			c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
+		case errors.Is(err, service.ErrChildKeyLimitReached):
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		default:
+			c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to issue child key", "details": err.Error()})
+		}
 		return
 	}