fix(auth/rbac): scope-aware ActorRole revoke (A-4)

HIGH-10's UNIQUE (actor, role, scope_type, scope_id, tenant) uniqueness
extension lets an operator grant the same role to the same actor at
multiple scopes (e.g. r-operator on profile=p-acme AND profile=p-globex).
But ActorRoleRepository.Revoke's WHERE clause omitted (scope_type,
scope_id) — a single call deleted every variant. Selective revoke was
unrepresentable; operators had to drop all and re-grant N-1, opening
a race window where the actor's access was briefly different.

Closure across all layers (handler → service → repo → MCP → GUI client),
preserving the legacy "revoke all variants" contract for unmodified
callers:

  internal/repository/auth.go
    - New ActorRoleRevokeOptions struct. Zero value = legacy semantic;
      non-empty ScopeType narrows to one variant.
    - New ErrActorRoleNotFound sentinel for scoped no-match (HTTP 404).

  internal/repository/postgres/auth.go
    - Revoke signature extended with opts. Empty opts.ScopeType uses
      the legacy SQL (no scope WHERE), zero-row delete = no error.
    - Non-empty narrows with `scope_type = $5 AND scope_id IS NOT
      DISTINCT FROM $6` — the IS-NOT-DISTINCT-FROM is load-bearing,
      vanilla `=` would silently miss the (global, NULL) case because
      NULL ≠ NULL in standard SQL.
    - Selective revoke with zero matching rows returns
      ErrActorRoleNotFound; operators get feedback on typos.

  internal/service/auth/actor_role_service.go
    - Revoke takes opts. Audit row's details map records the scope so
      SIEMs can distinguish wide-vs-selective revokes:
      `scope: "all_variants"` for the legacy path, or
      `scope_type` + `scope_id` for selective. Privilege check
      (auth.role.assign) and reserved-actor guard unchanged.

  internal/api/handler/auth.go
    - RevokeRoleFromKey parses optional `?scope_type=` / `?scope_id=`
      query params via new parseRevokeScope helper.
    - Validation mirrors AssignRoleToKey: scope_id forbidden with
      scope_type=global, required with profile/issuer, invalid
      scope_type → 400. scope_id without scope_type also → 400.
    - writeAuthError maps ErrActorRoleNotFound to 404.

  internal/mcp/tools_auth.go + types.go
    - AuthRevokeKeyRoleInput gains optional ScopeType + ScopeID with
      jsonschema descriptions explaining the dual-mode contract.
    - Tool call site appends URL-encoded query params when ScopeType
      is set; legacy callers (no scope_type) emit the bare DELETE
      path unchanged.

  web/src/api/client.ts
    - authRevokeKeyRole signature: optional 3rd argument
      `{ scope_type?, scope_id? }`. Pre-A-4 call sites (no opts arg)
      keep firing the bare DELETE — fully backward compatible. The
      GUI KeysPage's per-row revoke button (still one row per role,
      pre-Fix-12) continues to use the legacy shape; future GUI work
      can pass scope params for per-variant rows.

  docs/operator/rbac.md
    - New "Revoke: legacy 'all variants' vs scope-selective" subsection
      under "From the HTTP API" with curl examples for both modes plus
      the audit-row payload shape that lets SOC/SIEM tell them apart.

Regression coverage:

  Repository (testcontainers, skipped under -short — 6 tests in
  internal/repository/postgres/auth_revoke_scope_test.go):
    TestRevokeActorRole_NoOpts_RemovesAllVariants
    TestRevokeActorRole_WithScope_RemovesOnlyMatching
    TestRevokeActorRole_WithGlobalScope_RemovesOnlyGlobal — pins the
      IS-NOT-DISTINCT-FROM branch (global, NULL)
    TestRevokeActorRole_NoMatch_ReturnsNotFound — pins the new sentinel
    TestRevokeActorRole_NoOpts_NoMatch_IsNoOp — pins the legacy
      idempotence contract
    TestRevokeActorRole_IssuerScope_RemovesOnlyMatching — pin the
      issuer-scope half (profile + issuer are symmetric scope types)

  Handler (7 new tests in auth_test.go):
    TestAuthHandler_RevokeRoleFromKey — extended to assert no scope
      filter is forwarded when query string is empty (legacy behaviour)
    TestAuthHandler_RevokeRoleFromKey_A4_ScopedProfile
    TestAuthHandler_RevokeRoleFromKey_A4_ScopedGlobal
    TestAuthHandler_RevokeRoleFromKey_A4_RejectsScopeIDWithGlobal
    TestAuthHandler_RevokeRoleFromKey_A4_RejectsMissingScopeID
    TestAuthHandler_RevokeRoleFromKey_A4_RejectsScopeIDWithoutScopeType
    TestAuthHandler_RevokeRoleFromKey_A4_RejectsInvalidScopeType
    TestAuthHandler_RevokeRoleFromKey_A4_ScopedNotFoundReturns404

  MCP (2 new table rows in tools_per_tool_test.go):
    Scoped revoke with scope_type=profile + scope_id=p-acme →
      `?scope_type=profile&scope_id=p-acme`
    Scoped revoke with scope_type=global (no scope_id) →
      `?scope_type=global`

Service-layer test plumbing (service_test.go) updated for new opts
arg: 4 existing call sites pass repository.ActorRoleRevokeOptions{}
to keep their pre-A-4 semantics; the fakeActorRoleRepo.Revoke
implementation now mirrors the postgres scope-aware behaviour
(legacy zero-value vs scoped narrowing + ErrActorRoleNotFound on
no-match).

Verify gate green: gofmt clean, go vet clean, go test -short across
repository/postgres, service/auth, api/handler, and mcp. The
pre-existing KeysPage.test.tsx failure observed on the baseline
commit (reproduced via `git stash` earlier in Fix 03) is unrelated;
my client.ts change adds an optional third argument and is fully
backward-compatible.

Spec at cowork/auth-bundles-fixes-2026-05-11/04-high-actor-role-revoke-scope.md.
Audit doc updated: new row A-4 (2026-05-11) CLOSED appended to the
status table at the bottom of cowork/auth-bundles-audit-2026-05-10.md.
Operator-visible advisory in CHANGELOG.md v2.1.0 release notes under
Security (non-BREAKING — legacy callers are unchanged).

Depends on Fix 01 (the scope-aware EffectivePermissions read path on
branch fix/audit-2026-05-11/crit-actor-role-scope-reads). This fix
makes the inverse op selectively reversible; without Fix 01 the read
side would mis-evaluate scoped grants anyway, making selective revoke
moot at runtime.

internal/service/auth/actor_role_service.go

@@ -72,7 +72,15 @@ func (s *ActorRoleService) Grant(ctx context.Context, caller *Caller, ar *authdo
 // privilege guard as Grant: caller needs `auth.role.assign` to mutate
 // role membership. Reserved actor `actor-demo-anon` is rejected so the
 // demo path stays alive even after a misclick.
-func (s *ActorRoleService) Revoke(ctx context.Context, caller *Caller, actorID string, actorType domain.ActorType, roleID string) error {
+//
+// Audit 2026-05-11 A-4 — opts narrows the revoke to a specific
+// (scope_type, scope_id) variant. Zero value preserves the legacy
+// "revoke all variants" behaviour. When opts.ScopeType is set the
+// repository returns repository.ErrActorRoleNotFound if no row matches;
+// the handler maps it to HTTP 404. The audit row records the scope so
+// operators can distinguish "wide revoke" from "selective revoke" in
+// the SIEM.
+func (s *ActorRoleService) Revoke(ctx context.Context, caller *Caller, actorID string, actorType domain.ActorType, roleID string, opts repository.ActorRoleRevokeOptions) error {
 	if caller == nil {
 		return ErrUnauthenticated
 	}
@@ -89,14 +97,23 @@ func (s *ActorRoleService) Revoke(ctx context.Context, caller *Caller, actorID s
 		return fmt.Errorf("%w: actor-demo-anon is reserved", repository.ErrAuthReservedActor)
 	}
 	tenantID := s.tenantOf(caller)
-	if err := s.repo.Revoke(ctx, actorID, authdomain.ActorTypeValue(actorType), roleID, tenantID); err != nil {
+	if err := s.repo.Revoke(ctx, actorID, authdomain.ActorTypeValue(actorType), roleID, tenantID, opts); err != nil {
 		return err
 	}
-	s.recordAudit(ctx, caller, "actor_role.revoke", "actor_role", roleID, map[string]interface{}{
+	details := map[string]interface{}{
 		"actor_id":   actorID,
 		"actor_type": string(actorType),
 		"role_id":    roleID,
-	})
+	}
+	if opts.ScopeType != "" {
+		details["scope_type"] = string(opts.ScopeType)
+		if opts.ScopeID != nil {
+			details["scope_id"] = *opts.ScopeID
+		}
+	} else {
+		details["scope"] = "all_variants"
+	}
+	s.recordAudit(ctx, caller, "actor_role.revoke", "actor_role", roleID, details)
 	return nil
 }
 

internal/service/auth/service_test.go

@@ -159,15 +159,53 @@ func (f *fakeActorRoleRepo) Grant(_ context.Context, ar *authdomain.ActorRole) e
 	f.grants = append(f.grants, ar)
 	return nil
 }
-func (f *fakeActorRoleRepo) Revoke(_ context.Context, actorID string, actorType authdomain.ActorTypeValue, roleID, _ string) error {
+func (f *fakeActorRoleRepo) Revoke(_ context.Context, actorID string, actorType authdomain.ActorTypeValue, roleID, _ string, opts repository.ActorRoleRevokeOptions) error {
+	// Audit 2026-05-11 A-4 — mirror the postgres semantics: when
+	// opts.ScopeType is empty, remove every (actor,type,role) match
+	// regardless of scope (legacy). When set, narrow to the single
+	// matching scope variant; zero-match returns ErrActorRoleNotFound.
+	wantScopedSpecific := opts.ScopeType != ""
+	matched := 0
 	out := f.grants[:0]
 	for _, g := range f.grants {
 		if g.ActorID == actorID && g.ActorType == actorType && g.RoleID == roleID {
+			if wantScopedSpecific {
+				// Match by (scope_type, scope_id).
+				gScope := g.ScopeType
+				if gScope == "" {
+					gScope = authdomain.ScopeTypeGlobal
+				}
+				if gScope != opts.ScopeType {
+					out = append(out, g)
+					continue
+				}
+				// scope_id IS NOT DISTINCT FROM:
+				gSID := ""
+				if g.ScopeID != nil {
+					gSID = *g.ScopeID
+				}
+				wSID := ""
+				if opts.ScopeID != nil {
+					wSID = *opts.ScopeID
+				}
+				if gSID != wSID {
+					out = append(out, g)
+					continue
+				}
+				// Drop this row.
+				matched++
+				continue
+			}
+			// Legacy "revoke all variants" path.
+			matched++
 			continue
 		}
 		out = append(out, g)
 	}
 	f.grants = out
+	if wantScopedSpecific && matched == 0 {
+		return repository.ErrActorRoleNotFound
+	}
 	return nil
 }
 func (f *fakeActorRoleRepo) AdminExists(_ context.Context, _ string) (bool, error) {
@@ -439,7 +477,7 @@ func TestActorRoleService_GrantRejectsReservedDemoActor(t *testing.T) {
 
 func TestActorRoleService_RevokeRejectsReservedDemoActor(t *testing.T) {
 	svc, _, _ := newActorRoleServiceWithFakes()
-	err := svc.Revoke(context.Background(), AsSystemCaller(), authdomain.DemoAnonActorID, domain.ActorTypeAnonymous, "r-admin")
+	err := svc.Revoke(context.Background(), AsSystemCaller(), authdomain.DemoAnonActorID, domain.ActorTypeAnonymous, "r-admin", repository.ActorRoleRevokeOptions{})
 	if !errors.Is(err, repository.ErrAuthReservedActor) {
 		t.Errorf("Revoke against actor-demo-anon should be rejected; got %v", err)
 	}
@@ -848,19 +886,19 @@ func TestActorRoleService_ListKeysGates(t *testing.T) {
 func TestActorRoleService_RevokeGatesAndSucceeds(t *testing.T) {
 	svc, repo, audit := newActorRoleServiceWithFakes()
 	// nil caller
-	if err := svc.Revoke(context.Background(), nil, "alice", domain.ActorTypeAPIKey, "r-admin"); !errors.Is(err, ErrUnauthenticated) {
+	if err := svc.Revoke(context.Background(), nil, "alice", domain.ActorTypeAPIKey, "r-admin", repository.ActorRoleRevokeOptions{}); !errors.Is(err, ErrUnauthenticated) {
 		t.Errorf("Revoke(nil) err = %v; want ErrUnauthenticated", err)
 	}
 	// caller without auth.role.assign
 	caller := &Caller{ActorID: "bob", ActorType: domain.ActorTypeAPIKey}
-	if err := svc.Revoke(context.Background(), caller, "alice", domain.ActorTypeAPIKey, "r-admin"); !errors.Is(err, ErrSelfRoleAssignment) {
+	if err := svc.Revoke(context.Background(), caller, "alice", domain.ActorTypeAPIKey, "r-admin", repository.ActorRoleRevokeOptions{}); !errors.Is(err, ErrSelfRoleAssignment) {
 		t.Errorf("Revoke(no perm) err = %v; want ErrSelfRoleAssignment", err)
 	}
 	// system caller success
 	repo.grants = []*authdomain.ActorRole{
 		{ID: "ar-1", ActorID: "alice", ActorType: authdomain.ActorTypeValue(domain.ActorTypeAPIKey), RoleID: "r-admin", TenantID: authdomain.DefaultTenantID},
 	}
-	if err := svc.Revoke(context.Background(), AsSystemCaller(), "alice", domain.ActorTypeAPIKey, "r-admin"); err != nil {
+	if err := svc.Revoke(context.Background(), AsSystemCaller(), "alice", domain.ActorTypeAPIKey, "r-admin", repository.ActorRoleRevokeOptions{}); err != nil {
 		t.Fatalf("Revoke(system) err: %v", err)
 	}
 	if len(audit.calls) != 1 || audit.calls[0].Action != "actor_role.revoke" {
@@ -878,7 +916,7 @@ func TestActorRoleService_RevokeSucceedsWithAuthRoleAssign(t *testing.T) {
 		{ID: "ar-1", ActorID: "carol", ActorType: authdomain.ActorTypeValue(domain.ActorTypeAPIKey), RoleID: "r-viewer", TenantID: authdomain.DefaultTenantID},
 	}
 	caller := &Caller{ActorID: "alice", ActorType: domain.ActorTypeAPIKey}
-	if err := svc.Revoke(context.Background(), caller, "carol", domain.ActorTypeAPIKey, "r-viewer"); err != nil {
+	if err := svc.Revoke(context.Background(), caller, "carol", domain.ActorTypeAPIKey, "r-viewer", repository.ActorRoleRevokeOptions{}); err != nil {
 		t.Fatalf("Revoke(perm) err: %v", err)
 	}
 	if len(audit.calls) != 1 || audit.calls[0].Action != "actor_role.revoke" {