permission

type ListFilter struct {
	TenantID        string  `json:"tenant_id,omitempty"`
	NamespacePath   *string `json:"namespace_path,omitempty"`
	NamespacePrefix string  `json:"namespace_prefix,omitempty"`
	Resource        string  `json:"resource,omitempty"`
	Action          string  `json:"action,omitempty"`
	IsSystem        *bool   `json:"is_system,omitempty"`
	Search          string  `json:"search,omitempty"`
	Limit           int     `json:"limit,omitempty"`
	Offset          int     `json:"offset,omitempty"`
}

type Permission struct {
	ID            id.PermissionID `json:"id" db:"id"`
	TenantID      string          `json:"tenant_id" db:"tenant_id"`
	NamespacePath string          `json:"namespace_path,omitempty" db:"namespace_path"`
	AppID         string          `json:"app_id" db:"app_id"`
	Name          string          `json:"name" db:"name"`
	Description   string          `json:"description,omitempty" db:"description"`
	Resource      string          `json:"resource" db:"resource"`
	Action        string          `json:"action" db:"action"`
	IsSystem      bool            `json:"is_system" db:"is_system"`
	Metadata      map[string]any  `json:"metadata,omitempty" db:"metadata"`
	CreatedAt     time.Time       `json:"created_at" db:"created_at"`
	UpdatedAt     time.Time       `json:"updated_at" db:"updated_at"`
}

type Ref struct {
	NamespacePath string
	Name          string
}

type Store interface {
	// CreatePermission persists a new permission.
	CreatePermission(ctx context.Context, p *Permission) error

	// GetPermission retrieves a permission by ID.
	GetPermission(ctx context.Context, permID id.PermissionID) (*Permission, error)

	// GetPermissionByName retrieves a permission by tenant, namespace, and name.
	// Names are unique per (tenant_id, namespace_path); the namespace argument
	// disambiguates permissions sharing a name across different namespaces.
	GetPermissionByName(ctx context.Context, tenantID, namespacePath, name string) (*Permission, error)

	// UpdatePermission persists changes to a permission.
	UpdatePermission(ctx context.Context, p *Permission) error

	// DeletePermission removes a permission by ID.
	DeletePermission(ctx context.Context, permID id.PermissionID) error

	// ListPermissions returns permissions matching the filter.
	ListPermissions(ctx context.Context, filter *ListFilter) ([]*Permission, error)

	// CountPermissions returns the number of permissions matching the filter.
	CountPermissions(ctx context.Context, filter *ListFilter) (int64, error)

	// ListPermissionsByRole returns all permissions attached to a role.
	ListPermissionsByRole(ctx context.Context, roleID id.RoleID) ([]*Permission, error)

	// ListPermissionsBySubject returns all permissions granted to a subject
	// through their assigned roles.
	ListPermissionsBySubject(ctx context.Context, tenantID, subjectKind, subjectID string) ([]*Permission, error)

	// DeletePermissionsByTenant removes all permissions for a tenant.
	DeletePermissionsByTenant(ctx context.Context, tenantID string) error
}