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 RelationshipSyncer interface {
	// AddOrgMembership registers a principal's membership in an organization with a specific role.
	// Called when a user joins an organization or is invited.
	AddOrgMembership(ctx context.Context, principalID, orgID uuid.UUID, role string) error

	// RemoveOrgMembership removes a principal's membership from an organization.
	// Called when a user leaves or is removed from an organization.
	RemoveOrgMembership(ctx context.Context, principalID, orgID uuid.UUID, role string) error

	// UpdateOrgMembership changes a principal's role in an organization.
	// Implemented as remove old role + add new role atomically.
	UpdateOrgMembership(ctx context.Context, principalID, orgID uuid.UUID, oldRole, newRole string) error

	// RegisterPrincipal creates a principal entity in the authorization system.
	// Called when a new user, application, agent, or service principal is created.
	RegisterPrincipal(ctx context.Context, principalID uuid.UUID) error

	// UnregisterPrincipal removes a principal and all its relationships from the authorization system.
	// Called when a principal is deleted.
	UnregisterPrincipal(ctx context.Context, principalID uuid.UUID) error

	// RegisterOrganization creates an organization in the authorization system with an initial owner.
	// Called when a new organization is created.
	RegisterOrganization(ctx context.Context, orgID, ownerID uuid.UUID) error

	// UnregisterOrganization removes an organization and all its relationships from the authorization system.
	// Called when an organization is deleted.
	UnregisterOrganization(ctx context.Context, orgID uuid.UUID) error

	// SetPlatformAdmin grants or revokes platform admin privileges for a principal.
	SetPlatformAdmin(ctx context.Context, principalID uuid.UUID, isAdmin bool) error
}

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

type SyncMode string