authz

type Action string

type AppRoleSyncer interface {
	// AddAppRole records that the principal holds role in application for
	// the organization. Called when an application role is assigned or
	// changed.
	AddAppRole(ctx context.Context, principalID, orgID uuid.UUID, application, role string) error

	// RemoveAppRole removes the principal's role in application for the
	// organization. Called when an application role is removed or changed.
	RemoveAppRole(ctx context.Context, principalID, orgID uuid.UUID, application, role string) error
}

type AppVocabulary interface {
	// App returns the application identifier (e.g. "actionforge").
	App() string
	// Roles maps each role name to its granted dotted permissions.
	Roles() RolePermissions
	// Hierarchy orders the app's roles; every role in Roles() must appear.
	Hierarchy() RoleHierarchy
	// Scopes lists every OAuth scope the app defines.
	Scopes() []string
	// SpiceDBSchema returns the app's ReBAC schema fragment, or "" if the app
	// only supports the role-based (rbac) provider.
	SpiceDBSchema() 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 Engine string

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 Grant struct {
	PrincipalID uuid.UUID
	Resource    ResourceRef
	// Role is a resource role.
	Role string
	// GrantedBy is the principal who made the grant, when known.
	GrantedBy *uuid.UUID
}

type ManagerRoleGetter func(ctx context.Context, managerID, managedID uuid.UUID) ([]string, error)

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

type Mode string

type ModeConfig struct {
	// Mode is "rbac" (the default) or "rebac".
	Mode Mode `` /* 201-byte string literal not displayed */

	// Engine selects the relationship engine for mode rebac; default
	// "spicedb". It must be empty for mode rbac.
	Engine Engine `` /* 138-byte string literal not displayed */

	// SpiceDB configures the spicedb engine. Nil means an embedded
	// in-memory instance, for development and tests.
	SpiceDB *SpiceDBConfig `json:"spicedb,omitempty" yaml:"spicedb,omitempty" jsonschema:"description=SpiceDB engine settings for mode rebac"`
}

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 Provider interface {
	PlatformAuthorizer
	ResourceGranter
}

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

	// AddPrincipalManager records that managerID manages managedID with a
	// manager role such as guardian or educator (ADR-005).
	AddPrincipalManager(ctx context.Context, managedID, managerID uuid.UUID, role string) error

	// RemovePrincipalManager removes a manager relation.
	RemovePrincipalManager(ctx context.Context, managedID, managerID uuid.UUID, role string) 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 ResourceGrantReader interface {
	// ResourceRole returns the resource role the principal holds on the
	// resource through an active membership, or "".
	ResourceRole(ctx context.Context, principalID uuid.UUID, resource ResourceRef) (string, error)

	// OrganizationRoles returns the principal's role in each organization
	// where it has an active membership.
	OrganizationRoles(ctx context.Context, principalID uuid.UUID) (map[uuid.UUID]string, error)
}

type ResourceGrantSyncer interface {
	// SetResourceGrant records that the principal holds role on the
	// resource, replacing any other role it held there in one write.
	SetResourceGrant(ctx context.Context, principalID uuid.UUID, resource ResourceRef, role string) error

	// RemoveResourceGrant removes every role the principal holds on the
	// resource.
	RemoveResourceGrant(ctx context.Context, principalID uuid.UUID, resource ResourceRef) error
}

type ResourceGranter interface {
	// GrantResourceRole gives the principal a role on the resource,
	// replacing any role it held there. grantedBy is the principal making
	// the grant; the zero UUID records none.
	GrantResourceRole(ctx context.Context, principalID uuid.UUID, resource ResourceRef, role string, grantedBy uuid.UUID) error

	// RevokeResourceRole removes the principal's grant on the resource.
	// It returns ErrGrantNotFound when there is none.
	RevokeResourceRole(ctx context.Context, principalID uuid.UUID, resource ResourceRef) error

	// ListResourceGrants lists the grants on one resource, highest role
	// first.
	ListResourceGrants(ctx context.Context, resource ResourceRef) ([]Grant, error)

	// ListResources returns the resources of resourceType on which the
	// principal holds permission (view, edit or manage). An application
	// uses the result to constrain queries and row-level security, in
	// addition to checking each request.
	ListResources(ctx context.Context, principalID uuid.UUID, resourceType string, permission Action) (ResourceSet, error)
}

type ResourceRef struct {
	// Type is the definition name, "{app}_{type}", as declared in the
	// application's vocabulary.
	Type string
	// ID is the application's identifier of the resource.
	ID string
	// OrganizationID is the organization that owns the resource. Reads may
	// leave it zero to mean the organization the grant was made in.
	OrganizationID uuid.UUID
}

type ResourceSet struct {
	// IDs are resources the principal holds the permission on directly,
	// through a grant, or, in the relationship-based mode, through any
	// relationship the schema expresses.
	IDs []string
	// OrganizationIDs are organizations in which the principal's
	// organization role grants the permission on every resource of the
	// type. The relationship-based provider leaves it empty: its lookup
	// already returns each resource in IDs.
	OrganizationIDs []uuid.UUID
}

type ResourceType string

type RoleHierarchy map[string]int

type RolePermissions map[string][]string

type SpiceDBConfig struct {
	// Mode is how SpiceDB runs: "embedded" (in this process, the default)
	// or "remote" (a service reached over gRPC).
	Mode string `` /* 158-byte string literal not displayed */

	// DatastoreEngine is the embedded datastore: "memory" (default) or
	// "postgres".
	DatastoreEngine string `` /* 152-byte string literal not displayed */

	// DatastoreURI is the connection string of the embedded postgres
	// datastore.
	DatastoreURI string `` /* 168-byte string literal not displayed */

	// Endpoint is the gRPC address of a remote SpiceDB, "host:port".
	Endpoint string `json:"endpoint,omitempty" yaml:"endpoint,omitempty" jsonschema:"description=gRPC address of a remote SpiceDB"`

	// Token is the preshared key of a remote SpiceDB.
	Token string `` //nolint:gosec // G117: a configured credential, injected from the environment
	/* 133-byte string literal not displayed */

	// Insecure skips TLS to a remote SpiceDB. Development only.
	Insecure bool `` /* 148-byte string literal not displayed */

	// WriteSchema writes the composed schema (the base schema and every
	// registered vocabulary's fragment) to the engine at startup. An
	// embedded instance always gets it, since it starts empty; for a remote
	// one it is off by default, because a shared service's schema is an
	// operational decision.
	WriteSchema bool `` /* 155-byte string literal not displayed */
}

type SyncMode string

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