authz

type Action string

type Authorizer interface {
	// Can checks if a principal can perform an action on a resource.
	// This is the primary authorization method.
	Can(ctx context.Context, principal Principal, action Action, resource Resource) (bool, error)

	// CanAll checks if a principal can perform all specified actions on a resource.
	CanAll(ctx context.Context, principal Principal, actions []Action, resource Resource) (bool, error)

	// CanAny checks if a principal can perform any of the specified actions on a resource.
	CanAny(ctx context.Context, principal Principal, actions []Action, resource Resource) (bool, error)

	// Filter returns only the resources the principal can access with the given action.
	Filter(ctx context.Context, principal Principal, action Action, resources []Resource) ([]Resource, error)
}

type Decision struct {
	// Allowed indicates whether the action is permitted.
	Allowed bool

	// Reason provides context for the decision (useful for debugging/auditing).
	Reason string

	// PolicyID identifies which policy made the decision (if applicable).
	PolicyID string
}

type DecisionAuthorizer interface {
	Authorizer

	// Decide returns a detailed authorization decision.
	Decide(ctx context.Context, principal Principal, action Action, resource Resource) (Decision, error)
}

type ErrorResponse struct {
	Error   string `json:"error"`
	Message string `json:"message,omitempty"`
}

type FeatureAuthorizer interface {
	Authorizer

	// CanWithFeature checks both permission and feature flag.
	CanWithFeature(ctx context.Context, principal Principal, action Action, resource Resource, feature string) (bool, error)
}

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

type OrgAuthorizer interface {
	Authorizer

	// CanForOrg checks permission scoped to a specific organization.
	CanForOrg(ctx context.Context, principal Principal, orgID uuid.UUID, action Action, resource Resource) (bool, error)

	// GetRole returns the principal's role in an organization.
	GetRole(ctx context.Context, principal Principal, orgID uuid.UUID) (string, error)

	// IsMember checks if a principal is a member of an organization.
	IsMember(ctx context.Context, principal Principal, orgID uuid.UUID) (bool, error)
}

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

type PlatformAuthorizer interface {
	OrgAuthorizer

	// IsPlatformAdmin checks if a principal has platform-wide admin access.
	IsPlatformAdmin(ctx context.Context, principal Principal) (bool, error)
}

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

type Principal struct {
	// ID is the unique identifier of the principal.
	ID uuid.UUID

	// Type identifies the kind of principal (user, service, api_key, etc.).
	Type PrincipalType

	// Attributes contains additional principal attributes for ABAC.
	Attributes map[string]any
}

type PrincipalType string

type Resource struct {
	// Type identifies the kind of resource (course, organization, etc.).
	Type ResourceType

	// ID is the unique identifier of the resource (nil for type-level checks).
	ID *uuid.UUID

	// OwnerID is the owner of the resource (for ownership-based access).
	OwnerID *uuid.UUID

	// OrgID is the organization this resource belongs to.
	OrgID *uuid.UUID

	// Attributes contains additional resource attributes for ABAC.
	Attributes map[string]any
}

type ResourceExtractor func(r *http.Request) (Resource, error)

type ResourceType string

type RoleHierarchy map[string]int

type RolePermissions map[string][]string