auth-bundle-1 Phase 2: RBAC service layer + Authorizer primitive

Bundle 1 / Phase 2: ships PermissionService, RoleService, ActorRoleService, and the Authorizer primitive that Phase 3 RequirePermission middleware calls on every gated request.

Authorizer.CheckPermission semantics: a grant matches when (a) the permission name equals the requested permission AND (b) the grant is global-scoped OR the grant scope_type+scope_id exactly match the request. Global beats specific; per-resource grants widen the effective set rather than shadowing global. Hot-path query is one ActorRoleRepository.EffectivePermissions JOIN call (already shipped in Phase 1) plus an in-memory walk; Phase 12 will add benchmarks + caching if the JOIN cost shows up at scale.

Privilege-escalation guard: ActorRoleService.Grant and Revoke require the caller to hold auth.role.assign globally. Without it, ErrSelfRoleAssignment. System callers (AsSystemCaller()) bypass the check; bootstrap, migrations, scheduler-initiated grants use this path. Reserved actor actor-demo-anon is rejected on Grant + Revoke so the demo path stays alive even after a misclick (ErrAuthReservedActor).

Caller abstraction: every service entry point takes *Caller (ActorID, ActorType, TenantID, IsSystem). CallerFromContext is a stub returning ErrUnauthenticated; Phase 3 wires the middleware-context bridge that fills the Caller from request context. The contract is pinned by TestCallerFromContext_Phase2ReturnsUnauthenticated so the Phase 3 upgrade is observable.

Audit recording: every mutating service operation calls AuditService.RecordEvent. Bundle 1 Phase 8 adds the event_category column + parameter and back-fills 'auth' for these calls; until then the rows go in with the default category.

Test coverage: in-memory fakeRoleRepo / fakePermissionRepo / fakeActorRoleRepo / fakeAudit pin the privilege-escalation invariants (ErrUnauthenticated for nil caller, ErrForbidden for missing perm, ErrInvalidPermission for non-canonical permission name, ErrSelfRoleAssignment for Grant without auth.role.assign, ErrAuthReservedActor for actor-demo-anon mutations, system-caller bypass) without requiring testcontainers. Phase 12 will add live-Postgres integration coverage.

Branch: dev/auth-bundle-1. Phase 1 was 19497ee (RBAC schema + repo). Phase 3 (middleware integration) is the next commit on this branch.

internal/service/auth/auth.go

@@ -0,0 +1,103 @@
+// Package auth holds the RBAC service layer: PermissionService,
+// RoleService, ActorRoleService, and the Authorizer primitive that
+// Phase 3 middleware (auth.RequirePermission) calls on every gated
+// request.
+//
+// All mutating operations record an audit event via the existing
+// AuditService.RecordEvent path. Bundle 1 Phase 8 introduces an
+// `event_category` parameter and back-fills the existing callers; until
+// then auth-related events go in with the default category.
+//
+// Privilege-escalation guard: every mutation that affects role
+// assignment requires the caller to hold `auth.role.assign` (or the
+// equivalent role-level permission) on the target role. The system
+// pathway (bootstrap, migrations, scheduler) bypasses this check via
+// AsSystemCaller(), which records `actor=system, actorType=System` in
+// the audit row so the bypass is observable.
+package auth
+
+import (
+	"context"
+	"errors"
+
+	"github.com/certctl-io/certctl/internal/domain"
+	authdomain "github.com/certctl-io/certctl/internal/domain/auth"
+)
+
+// Sentinel errors for the service layer. Handler / middleware code
+// branches via errors.Is and maps to HTTP status codes.
+var (
+	// ErrForbidden is returned when the caller lacks the required
+	// permission for the operation. Maps to HTTP 403.
+	ErrForbidden = errors.New("auth: caller lacks required permission")
+
+	// ErrUnauthenticated is returned when the request has no actor in
+	// context (no Bearer, no session). Phase 3 RequirePermission emits
+	// this; handler code typically returns 401.
+	ErrUnauthenticated = errors.New("auth: no actor in context")
+
+	// ErrInvalidPermission is returned when a Create / AddPermission
+	// references a permission name not in the canonical catalogue.
+	// Maps to HTTP 400.
+	ErrInvalidPermission = errors.New("auth: permission not in canonical catalogue")
+
+	// ErrSelfRoleAssignment guards privilege escalation: a caller
+	// without `auth.role.assign` on a role cannot grant that role
+	// (including to themselves). Maps to HTTP 403.
+	ErrSelfRoleAssignment = errors.New("auth: caller lacks auth.role.assign on target role")
+)
+
+// AuditService is the audit-recording dependency the service layer
+// expects. Mirrors the existing service.AuditService interface so
+// Bundle 1 doesn't introduce a parallel concept.
+type AuditService interface {
+	RecordEvent(
+		ctx context.Context,
+		actor string,
+		actorType domain.ActorType,
+		action, resourceType, resourceID string,
+		details map[string]interface{},
+	) error
+}
+
+// Caller describes the actor performing a service operation. Bundle 1
+// Phase 3 populates this from the auth-middleware context (ActorIDKey,
+// ActorTypeKey). Bootstrap, migrations, and scheduler-initiated work
+// pass AsSystemCaller() to bypass the permission check while still
+// recording an audit row.
+type Caller struct {
+	ActorID   string
+	ActorType domain.ActorType
+	TenantID  string
+
+	// IsSystem skips the privilege-escalation guard. Reserved for
+	// bootstrap / migration / scheduler paths.
+	IsSystem bool
+}
+
+// AsSystemCaller returns a Caller that bypasses RBAC checks. Used by
+// the migration backfill, bootstrap path, scheduler-initiated grants,
+// and tests that need to seed state without simulating an admin.
+func AsSystemCaller() *Caller {
+	return &Caller{
+		ActorID:   "system",
+		ActorType: domain.ActorTypeSystem,
+		TenantID:  authdomain.DefaultTenantID,
+		IsSystem:  true,
+	}
+}
+
+// CallerFromContext is a helper that builds a Caller from auth context
+// values. Phase 3 middleware populates the keys; tests can use the
+// internal/auth.WithActor / WithAdmin helpers to build contexts.
+//
+// Returns nil + ErrUnauthenticated when no actor is present.
+func CallerFromContext(ctx context.Context) (*Caller, error) {
+	// Avoid coupling internal/service/auth to internal/auth at the
+	// type level: read the keys via package-public helpers exposed by
+	// internal/auth (ActorID, ActorType, TenantID). Phase 3 wires
+	// these up. For Phase 2, rely on the explicit Caller arg passed
+	// by handler / test code instead — direct context-key reads can
+	// land in Phase 3 alongside the middleware.
+	return nil, ErrUnauthenticated
+}