Add API key rotation: PUT /actors/{name}/rotate-key

The service generates a new random key, hashes it with SHA-256,
stores the hash, and returns the plaintext key (shown once). The old
key is immediately invalidated.

Key generation and hashing live in the service layer — the HTTP
handler just calls RotateActorKey(ctx, name) and gets the plaintext
back. No input required from the caller.

CLI: taskflow actor rotate_key <name>
MCP: actor_rotate_key tool

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: bricef

internal/cli/testdata/commands.golden.txt

@@ -1,6 +1,7 @@
 actor create                                       Create an actor
 actor get <name>                                   Get an actor by name
 actor list                                         List all actors
+actor rotate_key <name>                            Rotate an actor's API key
 actor update <name>                                Update an actor
 admin stats                                        System-wide statistics
 attachment create <slug> <num>                     Add an attachment

internal/http/handlers.go

@@ -59,6 +59,26 @@ func generateAPIKey() (string, error) {
 	return base64.RawURLEncoding.EncodeToString(b), nil
 }
 
+func (s *Server) rotateActorKey(ctx context.Context, r *http.Request) (any, error) {
+	name := urlParamStr(r, "name")
+
+	apiKey, err := s.svc.RotateActorKey(ctx, name)
+	if err != nil {
+		return nil, err
+	}
+
+	actor, err := s.svc.GetActor(ctx, name)
+	if err != nil {
+		return nil, err
+	}
+
+	type actorWithKey struct {
+		model.Actor
+		APIKey string `json:"api_key"`
+	}
+	return actorWithKey{Actor: actor, APIKey: apiKey}, nil
+}
+
 // --- Boards ---
 
 func (s *Server) listBoards(ctx context.Context, r *http.Request) (any, error) {

internal/http/routes.go

@@ -137,8 +137,9 @@ func (s *Server) resourceHandlers() map[string]handler {
 func (s *Server) operationHandlers() map[string]handler {
 	return map[string]handler{
 		// Actors
-		"actor_create": s.createActor,
-		"actor_update": s.updateActor,
+		"actor_create":     s.createActor,
+		"actor_rotate_key": s.rotateActorKey,
+		"actor_update":     s.updateActor,
 
 		// Boards
 		"board_create":   jsonBody(s.svc.CreateBoard),

internal/http/testdata/openapi.golden.json

@@ -1041,6 +1041,52 @@
         ]
       }
     },
+    "/actors/{name}/rotate-key": {
+      "put": {
+        "operationId": "actor_rotate_key",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "name",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Actor"
+                }
+              }
+            },
+            "description": "Success"
+          },
+          "4XX": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Client error"
+          }
+        },
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "summary": "Rotate an actor's API key",
+        "tags": [
+          "actors"
+        ]
+      }
+    },
     "/admin/stats": {
       "get": {
         "operationId": "admin_stats",

internal/model/operations.go

@@ -236,6 +236,9 @@ func Operations() []Operation {
 		// Actors
 		Create("/actors", "Create an actor").Name("actor_create").Role(RoleAdmin).
 			Input(CreateActorParams{}).Output(Actor{}).Build(),
+		CustomAction(ActionSet, "/actors/{name}/rotate-key", "Rotate an actor's API key").Name("actor_rotate_key").Role(RoleAdmin).
+			Desc("Generate a new API key for the actor. The old key is immediately invalidated. The new key is returned in the response (shown once).").
+			Output(Actor{}).Build(),
 		Update("/actors/{name}", "Update an actor").Name("actor_update").Role(RoleAdmin).
 			Desc("Update actor details. Set --active false to deactivate (revokes API key access, preserves audit history). Set --active true to reactivate.").
 			Input(UpdateActorParams{}).Output(Actor{}).Build(),

internal/model/operations_test.go

@@ -141,14 +141,14 @@ func TestResourcesCount(t *testing.T) {
 }
 
 func TestOperationsCount(t *testing.T) {
-	if got := len(Operations()); got != 23 {
-		t.Errorf("Operations() returned %d, want 23 — update this test if the change was intentional", got)
+	if got := len(Operations()); got != 24 {
+		t.Errorf("Operations() returned %d, want 24 — update this test if the change was intentional", got)
 	}
 }
 
 func TestTotalCount(t *testing.T) {
 	total := len(Resources()) + len(Operations())
-	if total != 42 {
-		t.Errorf("Resources() + Operations() = %d, want 42", total)
+	if total != 43 {
+		t.Errorf("Resources() + Operations() = %d, want 43", total)
 	}
 }

internal/model/registry.go

@@ -26,6 +26,7 @@ var (
 // Named operations — exported for direct use by httpclient consumers.
 var (
 	OpActorCreate    = mustOp("actor_create")
+	OpActorRotateKey = mustOp("actor_rotate_key")
 	OpActorUpdate    = mustOp("actor_update")
 	OpBoardCreate    = mustOp("board_create")
 	OpBoardUpdate    = mustOp("board_update")

internal/repo/repo.go

@@ -29,6 +29,7 @@ type ActorRepo interface {
 	ActorGetByAPIKeyHash(ctx context.Context, hash string) (model.Actor, error)
 	ActorList(ctx context.Context) ([]model.Actor, error)
 	ActorUpdate(ctx context.Context, tx Tx, params model.UpdateActorParams) (model.Actor, error)
+	ActorUpdateKeyHash(ctx context.Context, name, newHash string) error
 }
 
 type BoardRepo interface {

internal/service/actors.go

@@ -2,6 +2,11 @@ package service
 
 import (
 	"context"
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/hex"
+	"fmt"
 
 	"github.com/bricef/taskflow/internal/model"
 	"github.com/bricef/taskflow/internal/repo"
@@ -35,6 +40,26 @@ func (s *Service) GetActorByAPIKeyHash(ctx context.Context, hash string) (model.
 	return s.store.ActorGetByAPIKeyHash(ctx, hash)
 }
 
+// RotateActorKey generates a new API key for the actor, stores the hash,
+// and returns the plaintext key (shown once).
+func (s *Service) RotateActorKey(ctx context.Context, name string) (string, error) {
+	b := make([]byte, 32)
+	if _, err := rand.Read(b); err != nil {
+		return "", fmt.Errorf("generating API key: %w", err)
+	}
+	apiKey := base64.RawURLEncoding.EncodeToString(b)
+	hash := sha256Hex(apiKey)
+	if err := s.store.ActorUpdateKeyHash(ctx, name, hash); err != nil {
+		return "", err
+	}
+	return apiKey, nil
+}
+
+func sha256Hex(s string) string {
+	h := sha256.Sum256([]byte(s))
+	return hex.EncodeToString(h[:])
+}
+
 func (s *Service) ListActors(ctx context.Context) ([]model.Actor, error) {
 	return s.store.ActorList(ctx)
 }

internal/sqlite/actors.go

@@ -103,3 +103,14 @@ func (s *Store) ActorUpdate(ctx context.Context, tx repo.Tx, params model.Update
 	}
 	return s.actorGet(ctx, tx, params.Name)
 }
+
+func (s *Store) ActorUpdateKeyHash(ctx context.Context, name, newHash string) error {
+	result, err := s.db.ExecContext(ctx, "UPDATE actors SET api_key_hash = ? WHERE name = ?", newHash, name)
+	if err != nil {
+		return err
+	}
+	if n, _ := result.RowsAffected(); n == 0 {
+		return notFound("actor", name)
+	}
+	return nil
+}