principal

type Group interface {
	// Id returns the group id.
	Gid() string
	// Name returns the group name.
	Name() string
	// Users returns the users that are members of this group.
	Users() []User
	// Validate returns an error if the group is not valid.
	Validate() error
}

type Manager interface {
	// UserExistsByName provided the username returns true if it exists else false.
	UserExistsByName(userName string) bool
	// GroupExistsByName provided the group name returns true if it exists else false.
	GroupExistsByName(groupName string) bool
	// CreateUser creates a user with the given username.  The UID will be automatically generated.
	CreateUser(userName string) (User, error)
	// CreateUserWithId creates a user with the given username, predefined UID, and home directory.
	// Pass homeDir="" or "/" for service accounts that do not need a dedicated home directory.
	// On windows, the uid parameter is ignored; therefore, this method would be synonymous with the CreateUser method.
	CreateUserWithId(userName string, uid int, homeDir string) (User, error)
	// CreateGroup creates a group with the given group name.  The GID will be automatically generated.
	CreateGroup(groupName string) (Group, error)
	// CreateGroupWithId creates a group with the given group name and predefined GID.
	// On windows, the gid parameter is ignored; therefore, this method would be synonymous with the CreateGroup method.
	CreateGroupWithId(groupName string, gid int) (Group, error)
	// LookupUserByName provided the username returns the user object or an error. If the user does not exist, an error is returned.
	LookupUserByName(userName string) (User, error)
	// LookupUserById provided the user id returns the user object or an error. If the user does not exist, an error is returned.
	LookupUserById(uid string) (User, error)
	// LookupGroupByName provided the group name returns the group object or an error. If the group does not exist, an error is returned.
	LookupGroupByName(groupName string) (Group, error)
	// LookupGroupById provided the group id returns the group object or an error. If the group does not exist, an error is returned.
	LookupGroupById(gid string) (Group, error)
	// AddUserToGroup adds userName as a supplementary member of groupName.
	// Idempotent: returns nil if the user is already a member.
	AddUserToGroup(userName, groupName string) error
	// Refresh refreshes the user and group cache.
	Refresh() error
}

type Provider interface {
	// EnumerateUsers queries the underlying operating system registry for all users.
	EnumerateUsers(m Manager) ([]User, error)
	// EnumerateGroups queries the underlying operating system registry for all groups.
	EnumerateGroups(m Manager) ([]Group, error)
	// WriteGroupEntry appends a new group entry to the OS group database.
	WriteGroupEntry(name string, gid int) error
	// WriteGroupShadowEntry appends a new group shadow entry to the OS group shadow database.
	// This is a best-effort operation; implementations may return nil on platforms that do not support shadow files.
	WriteGroupShadowEntry(name string) error
	// WriteUserEntry appends a new user entry to the OS user database.
	// For system users, the primary GID is expected to equal the UID; the caller must create the group first.
	// homeDir specifies the user's home directory field in /etc/passwd (use "/" for pure service accounts).
	WriteUserEntry(name string, uid int, homeDir string) error
	// WriteUserShadowEntry appends a new user shadow entry to the OS user shadow database.
	// This is a best-effort operation; implementations may return nil on platforms that do not support shadow files.
	WriteUserShadowEntry(name string) error
	// AddMemberToGroup appends memberName to the comma-separated members field of groupName
	// in the OS group database, using an exclusive flock for atomicity.
	// Idempotent: if memberName is already listed, returns nil.
	AddMemberToGroup(groupName, memberName string) error
}

type User interface {
	// Id returns the user id.
	Uid() string
	// Name returns the username. This is the name that the user logs in with.
	Name() string
	// DisplayName returns the user's display name. On windows, this is the user's full name.
	DisplayName() string
	// HomeDir returns the user's home directory.
	HomeDir() string
	// PrimaryGroup returns the user's primary group.
	PrimaryGroup() Group
	// Groups returns the user's groups.
	Groups() []Group
	// Validate returns an error if the user is not valid.
	Validate() error
}