plugin

type AfterCheck ¶

type AfterCheck interface {
	OnAfterCheck(ctx context.Context, req, result any) error
}

AfterCheck is called after an authorization check completes. The req parameter is *warden.CheckRequest; result is *warden.CheckResult.

type Audit ¶ added in v1.7.0

type Audit interface {
	OnAudit(ctx context.Context, ev Event) error
}

Audit is called for every mutation, in addition to whichever typed hook above also fires for it.

type BeforeCheck ¶

type BeforeCheck interface {
	OnBeforeCheck(ctx context.Context, req any) error
}

BeforeCheck is called before an authorization check is evaluated. The req parameter is *warden.CheckRequest (passed as any to avoid import cycle).

type Event ¶ added in v1.7.0

type Event struct {
	Actor     any
	RequestID string
	TraceID   string
	At        time.Time
	// Action is one of: "role.created", "role.updated", "role.deleted",
	// "permission.created", "permission.deleted", "permission.attached",
	// "permission.detached", "assignment.created", "assignment.deleted",
	// "relation.written", "relation.deleted", "policy.created",
	// "policy.updated", "policy.deleted", "resourcetype.created",
	// "resourcetype.updated", "resourcetype.deleted", "declarative.applied",
	// "permission.updated", "role.permissions_set", "maintenance.run",
	// "maintenance.cache_invalidated".
	Action   string
	TenantID string
	EntityID string
	Entity   any
	Before   any
}

Event describes a single mutation for the audit trail. It is fired for every mutation in addition to the typed hooks above, so a plugin that wants a complete audit stream can implement just Audit instead of every typed hook individually.

Actor is warden.Actor, passed as `any` to avoid an import cycle (plugin cannot import the root warden package); it carries Kind, ID and Via. Entity is the entity after the change, or nil on delete. Before is the entity as it stood before an update or a delete (role, policy, permission, assignment, resource type and relation deletes all set it). It is nil on a create, and on an update or delete whose read of the old entity failed.

type MetricsRecorder ¶ added in v1.7.0

type MetricsRecorder interface {
	HookError(hook, plugin string)
}

MetricsRecorder is the minimal metrics surface the registry needs. It mirrors (and is satisfied by) warden.Metrics' HookError method without importing the root package, which would create an import cycle.

type PermissionAttached ¶

type PermissionAttached interface {
	OnPermissionAttached(ctx context.Context, roleID id.RoleID, permID id.PermissionID) error
}

PermissionAttached is called after a permission is attached to a role.

type PermissionCreated ¶

type PermissionCreated interface {
	OnPermissionCreated(ctx context.Context, p *permission.Permission) error
}

PermissionCreated is called after a permission is created.

type PermissionDeleted ¶

type PermissionDeleted interface {
	OnPermissionDeleted(ctx context.Context, permID id.PermissionID) error
}

PermissionDeleted is called after a permission is deleted.

type PermissionDetached ¶

type PermissionDetached interface {
	OnPermissionDetached(ctx context.Context, roleID id.RoleID, permID id.PermissionID) error
}

PermissionDetached is called after a permission is detached from a role.

type Plugin ¶

type Plugin interface {
	// Name returns a unique human-readable name for the plugin.
	Name() string
}

Plugin is the base interface all plugins must implement.

type PolicyCreated ¶

type PolicyCreated interface {
	OnPolicyCreated(ctx context.Context, p *policy.Policy) error
}

PolicyCreated is called after a policy is created.

type PolicyDeleted ¶

type PolicyDeleted interface {
	OnPolicyDeleted(ctx context.Context, polID id.PolicyID) error
}

PolicyDeleted is called after a policy is deleted.

type PolicyObligationFired ¶

type PolicyObligationFired interface {
	OnPolicyObligationFired(ctx context.Context, polID id.PolicyID, obligation string, req, result any) error
}

PolicyObligationFired is called for every obligation emitted during a Check evaluation — once per (policy, obligation_name) pair. Plugins implementing this hook can react to side-effect signals like "audit-log", "require-mfa", or "notify-security" without having to scan CheckResult.Obligations themselves.

Fired after the engine has merged decisions across RBAC / ReBAC / ABAC, so the obligation list is already deduplicated. policyID identifies the matched policy that produced the obligation; obligation is the named action to perform.

type PolicyUpdated ¶

type PolicyUpdated interface {
	OnPolicyUpdated(ctx context.Context, p *policy.Policy) error
}

PolicyUpdated is called after a policy is updated.

type Registry ¶

type Registry struct {
	// contains filtered or unexported fields
}

Registry holds registered plugins and dispatches lifecycle events. It type-caches plugins at registration time so emit calls iterate only over plugins implementing the relevant hook.

Every dispatch is panic-recovered per hook: one misbehaving plugin can neither crash the calling goroutine nor stop other plugins in the same Emit call from running.

It is safe for concurrent use. Engine.Plugins() hands the registry to any caller, so a Register can arrive while checks are emitting. Register only ever appends, so an Emit reads the hook slice's header under the read lock and iterates outside it: a later append writes past that header's length or into a new array, and the plugins it adds are notified from the next Emit on.

func NewRegistry(logger log.Logger) *Registry

func (r *Registry) EmitAfterCheck(ctx context.Context, req, result any)

func (r *Registry) EmitAudit(ctx context.Context, ev Event)

func (r *Registry) EmitBeforeCheck(ctx context.Context, req any)

func (r *Registry) EmitPermissionAttached(ctx context.Context, roleID id.RoleID, permID id.PermissionID)

func (r *Registry) EmitPermissionCreated(ctx context.Context, p *permission.Permission)

func (r *Registry) EmitPermissionDeleted(ctx context.Context, permID id.PermissionID)

func (r *Registry) EmitPermissionDetached(ctx context.Context, roleID id.RoleID, permID id.PermissionID)

func (r *Registry) EmitPolicyCreated(ctx context.Context, p *policy.Policy)

func (r *Registry) EmitPolicyDeleted(ctx context.Context, polID id.PolicyID)

func (r *Registry) EmitPolicyObligationFired(ctx context.Context, polID id.PolicyID, obligation string, req, result any)

func (r *Registry) EmitPolicyUpdated(ctx context.Context, p *policy.Policy)

func (r *Registry) EmitRelationDeleted(ctx context.Context, relID id.RelationID)

func (r *Registry) EmitRelationWritten(ctx context.Context, t *relation.Tuple)

func (r *Registry) EmitRoleAssigned(ctx context.Context, a *assignment.Assignment)

func (r *Registry) EmitRoleCreated(ctx context.Context, rl *role.Role)

func (r *Registry) EmitRoleDeleted(ctx context.Context, roleID id.RoleID)

func (r *Registry) EmitRoleUnassigned(ctx context.Context, a *assignment.Assignment)

func (r *Registry) EmitRoleUpdated(ctx context.Context, rl *role.Role)

func (r *Registry) EmitShutdown(ctx context.Context)

func (r *Registry) Plugins() []Plugin

func (r *Registry) Register(p Plugin)

func (r *Registry) SetMetrics(m MetricsRecorder)

func (r *Registry) Validate(p Plugin) []string

type RelationDeleted ¶

type RelationDeleted interface {
	OnRelationDeleted(ctx context.Context, relID id.RelationID) error
}

RelationDeleted is called after a relation tuple is deleted, once per tuple, with that tuple's ID (never the zero ID). A REST delete by key whose read of the matching tuples named none (it failed, or found nothing) fires no RelationDeleted; it clears the engine's cache for its tenant itself, and when the read failed its one audit event names the key instead of a tuple.

type RelationWritten ¶

type RelationWritten interface {
	OnRelationWritten(ctx context.Context, t *relation.Tuple) error
}

RelationWritten is called after a relation tuple is written.

type RoleAssigned ¶

type RoleAssigned interface {
	OnRoleAssigned(ctx context.Context, a *assignment.Assignment) error
}

RoleAssigned is called after a role is assigned to a subject.

type RoleCreated ¶

type RoleCreated interface {
	OnRoleCreated(ctx context.Context, r *role.Role) error
}

RoleCreated is called after a role is created.

type RoleDeleted ¶

type RoleDeleted interface {
	OnRoleDeleted(ctx context.Context, roleID id.RoleID) error
}

RoleDeleted is called after a role is deleted.

type RoleUnassigned ¶

type RoleUnassigned interface {
	OnRoleUnassigned(ctx context.Context, a *assignment.Assignment) error
}

RoleUnassigned is called after a role is unassigned from a subject.

type RoleUpdated ¶

type RoleUpdated interface {
	OnRoleUpdated(ctx context.Context, r *role.Role) error
}

RoleUpdated is called after a role is updated.

type Shutdown ¶

type Shutdown interface {
	OnShutdown(ctx context.Context) error
}

Shutdown is called during graceful shutdown.