@quenty/permissionprovider 14.43.0 → 14.44.1

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [14.44.1](https://github.com/Quenty/NevermoreEngine/compare/@quenty/permissionprovider@14.44.0...@quenty/permissionprovider@14.44.1) (2026-07-23)
+
+**Note:** Version bump only for package @quenty/permissionprovider
+
+# [14.44.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/permissionprovider@14.43.0...@quenty/permissionprovider@14.44.0) (2026-07-23)
+
+### Features
+
+- Add baseline player-mock and support across Nevermore for mocked players. ([567d121](https://github.com/Quenty/NevermoreEngine/commit/567d121ffc014b42391554088189a1a6296dda83))
+
 # [14.43.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/permissionprovider@14.42.0...@quenty/permissionprovider@14.43.0) (2026-07-22)
 
 **Note:** Version bump only for package @quenty/permissionprovider

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/permissionprovider",
-  "version": "14.43.0",
+  "version": "14.44.1",
   "description": "Permission provider for Roblox, including authenticating against group membership",
   "keywords": [
     "Roblox",
@@ -28,23 +28,24 @@
     "Quenty"
   ],
   "dependencies": {
-    "@quenty/baseobject": "10.14.0",
-    "@quenty/brio": "14.32.0",
+    "@quenty/baseobject": "10.15.0",
+    "@quenty/brio": "14.33.0",
     "@quenty/enums": "1.3.0",
-    "@quenty/grouputils": "10.22.0",
+    "@quenty/grouputils": "10.23.1",
     "@quenty/loader": "10.11.0",
-    "@quenty/maid": "3.10.0",
-    "@quenty/nevermore-test-runner": "1.4.0",
-    "@quenty/playerutils": "8.35.0",
-    "@quenty/promise": "10.20.0",
-    "@quenty/remoting": "12.35.0",
-    "@quenty/rx": "13.30.0",
-    "@quenty/servicebag": "11.19.0",
+    "@quenty/maid": "3.11.0",
+    "@quenty/nevermore-test-runner": "1.5.0",
+    "@quenty/playermock": "1.1.1",
+    "@quenty/playerutils": "8.36.1",
+    "@quenty/promise": "10.21.0",
+    "@quenty/remoting": "12.36.1",
+    "@quenty/rx": "13.31.0",
+    "@quenty/servicebag": "11.20.0",
     "@quenty/table": "3.9.2",
     "@quentystudios/jest-lua": "3.10.0-quenty.2"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "93f15b200c0f465a0b5304fcf05f5cfe7fdcbd1d"
+  "gitHead": "5ea0583dedebba6492f9ac6d719d32b45c5543fa"
 }

package/src/Client/PermissionServiceClient.lua

@@ -15,6 +15,7 @@ local require = require(script.Parent.loader).load(script)
 local Maid = require("Maid")
 local PermissionProviderClient = require("PermissionProviderClient")
 local PermissionProviderConstants = require("PermissionProviderConstants")
+local PlayerMock = require("PlayerMock")
 local Promise = require("Promise")
 local ServiceBag = require("ServiceBag")
 
@@ -53,7 +54,10 @@ function PermissionServiceClient.PromiseIsAdmin(
 	self: PermissionServiceClient,
 	player: Player?
 ): Promise.Promise<boolean>
-	assert((typeof(player) == "Instance" and player:IsA("Player")) or player == nil, "Bad player")
+	assert(
+		(typeof(player) == "Instance" and (player:IsA("Player") or PlayerMock.isMock(player))) or player == nil,
+		"Bad player"
+	)
 
 	return self:PromisePermissionProvider():Then(function(permissionProvider)
 		return permissionProvider:PromiseIsAdmin(player)

package/src/Client/PermissionServiceClient.spec.lua

@@ -0,0 +1,176 @@
+--!strict
+--[[
+	Coverage for PermissionServiceClient booted headless in a client ServiceBag against a
+	pre-designated mock local player (designation precedes Init -- production parity, where
+	Players.LocalPlayer exists before any service runs). Real remotes can never reach a server
+	realm headless, so server answers are driven by stubbing the remote promise cached by the
+	resolved PermissionProviderClient. The deny case assumes RunService:IsStudio() == false (true
+	in the cloud test runner); in Studio the provider short-circuits every answer to true.
+
+	Bad-player failures surface as synchronous throws, not rejections: the provider promise is
+	already fulfilled, so the Then handler (and the provider's asserts) run inline at call time.
+
+	@class PermissionServiceClient.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Workspace = game:GetService("Workspace")
+
+local Jest = require("Jest")
+local Maid = require("Maid")
+local PermissionServiceClient = require("PermissionServiceClient")
+local PlayerMock = require("PlayerMock")
+local Promise = require("Promise")
+local PromiseTestUtils = require("PromiseTestUtils")
+local ServiceBag = require("ServiceBag")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+local LOCAL_USER_ID = 88772001
+
+local function setup()
+	local maid = Maid.new()
+
+	local localPlayer = maid:Add(PlayerMock.new({ UserId = LOCAL_USER_ID }))
+	localPlayer.Parent = Workspace
+	PlayerMock.setMockedLocalPlayer(localPlayer)
+
+	local serviceBag = maid:Add(ServiceBag.new())
+	local service: PermissionServiceClient.PermissionServiceClient =
+		serviceBag:GetService(PermissionServiceClient) :: any
+	serviceBag:Init()
+	serviceBag:Start()
+
+	return {
+		localPlayer = localPlayer,
+		serviceBag = serviceBag,
+		service = service,
+		stubServerAnswer = function(invokeServer: () -> any)
+			local ok, provider = service:PromisePermissionProvider():Yield()
+			assert(ok, "No provider resolved")
+
+			local anyProvider: any = provider
+			anyProvider._remoteFunctionPromise = Promise.resolved({
+				InvokeServer = function(_self)
+					return invokeServer()
+				end,
+			})
+		end,
+		fakePlayer = function(userId: number): Player
+			return maid:Add(PlayerMock.new({ UserId = userId }))
+		end,
+		awaitBool = function(promise: any): boolean
+			expect(PromiseTestUtils.awaitSettled(promise, 5)).toEqual(true)
+			local ok, value = promise:Yield()
+			expect(ok).toEqual(true)
+			return value
+		end,
+		destroy = function(_self)
+			PlayerMock.setMockedLocalPlayer(nil)
+			maid:DoCleaning()
+		end,
+	}
+end
+
+describe("PermissionServiceClient initialization", function()
+	it("resolves the permission provider immediately after init", function()
+		local controller = setup()
+
+		local promise = controller.service:PromisePermissionProvider()
+		expect(promise:IsPending()).toEqual(false)
+
+		local ok, provider = promise:Yield()
+		expect(ok).toEqual(true)
+		expect((provider :: any).ClassName).toEqual("PermissionProviderClient")
+
+		controller:destroy()
+	end)
+
+	it("rejects double initialization", function()
+		local controller = setup()
+
+		local bare: any = setmetatable({}, { __index = PermissionServiceClient })
+		bare:Init(controller.serviceBag)
+
+		expect(function()
+			bare:Init(controller.serviceBag)
+		end).toThrow("Already initialized")
+
+		bare:Destroy()
+		controller:destroy()
+	end)
+end)
+
+describe("PermissionServiceClient.PromiseIsAdmin", function()
+	it("rejects a non-player value", function()
+		local controller = setup()
+
+		expect(function()
+			controller.service:PromiseIsAdmin(5 :: any)
+		end).toThrow("Bad player")
+
+		controller:destroy()
+	end)
+
+	it("resolves the server's answer for the designated local player", function()
+		local controller = setup()
+		controller.stubServerAnswer(function()
+			return true
+		end)
+
+		expect(controller.awaitBool(controller.service:PromiseIsAdmin(controller.localPlayer))).toEqual(true)
+
+		controller:destroy()
+	end)
+
+	it("resolves the server's answer for a nil player", function()
+		local controller = setup()
+		controller.stubServerAnswer(function()
+			return true
+		end)
+
+		expect(controller.awaitBool(controller.service:PromiseIsAdmin(nil))).toEqual(true)
+
+		controller:destroy()
+	end)
+
+	it("denies the designated local player when the server answers false", function()
+		local controller = setup()
+		controller.stubServerAnswer(function()
+			return false
+		end)
+
+		expect(controller.awaitBool(controller.service:PromiseIsAdmin(controller.localPlayer))).toEqual(false)
+
+		controller:destroy()
+	end)
+
+	it("throws for a mock that is not the designated local player", function()
+		local controller = setup()
+		local otherPlayer = controller.fakePlayer(LOCAL_USER_ID + 1)
+
+		expect(function()
+			controller.service:PromiseIsAdmin(otherPlayer)
+		end).toThrow("We only support local player")
+
+		controller:destroy()
+	end)
+
+	it("caches the server answer across calls", function()
+		local controller = setup()
+		local invokeCount = 0
+		controller.stubServerAnswer(function()
+			invokeCount += 1
+			return true
+		end)
+
+		expect(controller.awaitBool(controller.service:PromiseIsAdmin(controller.localPlayer))).toEqual(true)
+		expect(controller.awaitBool(controller.service:PromiseIsAdmin(controller.localPlayer))).toEqual(true)
+		expect(invokeCount).toEqual(1)
+
+		controller:destroy()
+	end)
+end)

package/src/Client/Providers/PermissionProviderClient.lua

@@ -12,6 +12,7 @@ local Players = game:GetService("Players")
 local RunService = game:GetService("RunService")
 
 local PermissionProviderConstants = require("PermissionProviderConstants")
+local PlayerMock = require("PlayerMock")
 local Promise = require("Promise")
 local PromiseGetRemoteFunction = require("PromiseGetRemoteFunction")
 
@@ -46,10 +47,15 @@ function PermissionProviderClient.PromiseIsAdmin(
 	self: PermissionProviderClient,
 	player: Player?
 ): Promise.Promise<boolean>
-	assert(typeof(player) == "Instance" and player:IsA("Player") or player == nil, "Bad player")
+	assert(
+		typeof(player) == "Instance" and (player:IsA("Player") or PlayerMock.isMock(player)) or player == nil,
+		"Bad player"
+	)
 
 	if player ~= nil then
-		assert(player == Players.LocalPlayer, "We only support local player for now")
+		-- Headless (test) sessions have no Players.LocalPlayer; the designated PlayerMock stands in.
+		local localPlayer = Players.LocalPlayer or PlayerMock.getMockedLocalPlayer()
+		assert(player == localPlayer, "We only support local player for now")
 	end
 
 	if player == nil then

package/src/Client/Providers/PermissionProviderClient.spec.lua

@@ -0,0 +1,186 @@
+--!strict
+--[[
+	Coverage for PermissionProviderClient against a stubbed server remote. Headless sessions
+	(RunService:IsRunning() == false) hand out detached mock RemoteFunctions that can never reach a
+	server realm, so tests inject the remote promise the provider caches and answer InvokeServer
+	directly. The deny case assumes RunService:IsStudio() == false (true in the cloud test runner);
+	in Studio the provider short-circuits every answer to true.
+
+	@class PermissionProviderClient.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Workspace = game:GetService("Workspace")
+
+local Jest = require("Jest")
+local Maid = require("Maid")
+local PermissionProviderClient = require("PermissionProviderClient")
+local PermissionProviderConstants = require("PermissionProviderConstants")
+local PlayerMock = require("PlayerMock")
+local Promise = require("Promise")
+local PromiseTestUtils = require("PromiseTestUtils")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+local LOCAL_USER_ID = 88771001
+
+local function setup()
+	local maid = Maid.new()
+
+	local localPlayer = maid:Add(PlayerMock.new({ UserId = LOCAL_USER_ID }))
+	localPlayer.Parent = Workspace
+	PlayerMock.setMockedLocalPlayer(localPlayer)
+
+	return {
+		localPlayer = localPlayer,
+		makeProvider = function(invokeServer: (() -> any)?): any
+			local provider: any = PermissionProviderClient.new("PermissionProviderClientSpecRemote")
+			if invokeServer then
+				provider._remoteFunctionPromise = Promise.resolved({
+					InvokeServer = function(_self)
+						return invokeServer()
+					end,
+				})
+			end
+			return provider
+		end,
+		fakePlayer = function(userId: number): Player
+			return maid:Add(PlayerMock.new({ UserId = userId }))
+		end,
+		awaitBool = function(promise: any): boolean
+			expect(PromiseTestUtils.awaitSettled(promise, 5)).toEqual(true)
+			local ok, value = promise:Yield()
+			expect(ok).toEqual(true)
+			return value
+		end,
+		awaitError = function(promise: any): string
+			expect(PromiseTestUtils.awaitSettled(promise, 5)).toEqual(true)
+			local ok, err = promise:Yield()
+			expect(ok).toEqual(false)
+			return tostring(err)
+		end,
+		destroy = function(_self)
+			PlayerMock.setMockedLocalPlayer(nil)
+			maid:DoCleaning()
+		end,
+	}
+end
+
+describe("PermissionProviderClient construction", function()
+	it("defaults the remote function name when none is given", function()
+		local provider: any = PermissionProviderClient.new(nil :: any)
+
+		expect(provider._remoteFunctionName).toEqual(PermissionProviderConstants.DEFAULT_REMOTE_FUNCTION_NAME)
+	end)
+
+	it("uses the provided remote function name", function()
+		local provider: any = PermissionProviderClient.new("PermissionProviderClientSpecRemote")
+
+		expect(provider._remoteFunctionName).toEqual("PermissionProviderClientSpecRemote")
+	end)
+end)
+
+describe("PermissionProviderClient.PromiseIsAdmin argument validation", function()
+	it("rejects a non-player value", function()
+		local controller = setup()
+		local provider = controller.makeProvider()
+
+		expect(function()
+			provider:PromiseIsAdmin(5 :: any)
+		end).toThrow("Bad player")
+
+		controller:destroy()
+	end)
+
+	it("rejects a player other than the designated local player", function()
+		local controller = setup()
+		local provider = controller.makeProvider()
+		local otherPlayer = controller.fakePlayer(LOCAL_USER_ID + 1)
+
+		expect(function()
+			provider:PromiseIsAdmin(otherPlayer)
+		end).toThrow("We only support local player")
+
+		controller:destroy()
+	end)
+end)
+
+describe("PermissionProviderClient.PromiseIsAdmin", function()
+	it("resolves the server's answer for the designated local player", function()
+		local controller = setup()
+		local provider = controller.makeProvider(function()
+			return true
+		end)
+
+		expect(controller.awaitBool(provider:PromiseIsAdmin(controller.localPlayer))).toEqual(true)
+
+		controller:destroy()
+	end)
+
+	it("resolves the server's answer for a nil player", function()
+		local controller = setup()
+		local provider = controller.makeProvider(function()
+			return true
+		end)
+
+		expect(controller.awaitBool(provider:PromiseIsAdmin(nil))).toEqual(true)
+
+		controller:destroy()
+	end)
+
+	it("denies when the server answers false", function()
+		local controller = setup()
+		local provider = controller.makeProvider(function()
+			return false
+		end)
+
+		expect(controller.awaitBool(provider:PromiseIsAdmin(controller.localPlayer))).toEqual(false)
+
+		controller:destroy()
+	end)
+
+	it("rejects a non-boolean server answer", function()
+		local controller = setup()
+		local provider = controller.makeProvider(function()
+			return "yes"
+		end)
+
+		local message = controller.awaitError(provider:PromiseIsAdmin(controller.localPlayer))
+		expect(message).toContain("Got non-boolean from server")
+
+		controller:destroy()
+	end)
+
+	it("rejects when the server invoke throws", function()
+		local controller = setup()
+		local provider = controller.makeProvider(function()
+			error("Server invoke failed")
+		end)
+
+		local message = controller.awaitError(provider:PromiseIsAdmin(controller.localPlayer))
+		expect(message).toContain("Server invoke failed")
+
+		controller:destroy()
+	end)
+
+	it("caches the admin answer across calls", function()
+		local controller = setup()
+		local invokeCount = 0
+		local provider = controller.makeProvider(function()
+			invokeCount += 1
+			return true
+		end)
+
+		local first = provider:PromiseIsAdmin(controller.localPlayer)
+		local second = provider:PromiseIsAdmin(controller.localPlayer)
+
+		expect(second).toBe(first)
+		expect(controller.awaitBool(first)).toEqual(true)
+		expect(invokeCount).toEqual(1)
+
+		controller:destroy()
+	end)
+end)

package/src/Server/PermissionProviderUtils.spec.lua

@@ -0,0 +1,118 @@
+--!strict
+--[[
+	@class PermissionProviderUtils.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Jest = require("Jest")
+local PermissionProviderConstants = require("PermissionProviderConstants")
+local PermissionProviderUtils = require("PermissionProviderUtils")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+describe("PermissionProviderUtils.createGroupRankConfig", function()
+	it("should create a group rank config with the given ranks", function()
+		local config = PermissionProviderUtils.createGroupRankConfig({
+			groupId = 12345,
+			minAdminRequiredRank = 250,
+			minCreatorRequiredRank = 254,
+		})
+
+		expect(config.type).toEqual(PermissionProviderConstants.GROUP_RANK_CONFIG_TYPE)
+		expect(config.groupId).toEqual(12345)
+		expect(config.minAdminRequiredRank).toEqual(250)
+		expect(config.minCreatorRequiredRank).toEqual(254)
+	end)
+
+	it("should default the remote function name", function()
+		local config = PermissionProviderUtils.createGroupRankConfig({
+			groupId = 12345,
+			minAdminRequiredRank = 250,
+			minCreatorRequiredRank = 254,
+		})
+
+		expect(config.remoteFunctionName).toEqual(PermissionProviderConstants.DEFAULT_REMOTE_FUNCTION_NAME)
+	end)
+
+	it("should honor a custom remote function name", function()
+		local config = PermissionProviderUtils.createGroupRankConfig({
+			groupId = 12345,
+			minAdminRequiredRank = 250,
+			minCreatorRequiredRank = 254,
+			remoteFunctionName = "CustomRemoteFunction",
+		})
+
+		expect(config.remoteFunctionName).toEqual("CustomRemoteFunction")
+	end)
+
+	it("should reject a missing groupId", function()
+		expect(function()
+			PermissionProviderUtils.createGroupRankConfig({
+				minAdminRequiredRank = 250,
+				minCreatorRequiredRank = 254,
+			} :: any)
+		end).toThrow("Bad groupId")
+	end)
+
+	it("should reject a missing minCreatorRequiredRank", function()
+		expect(function()
+			PermissionProviderUtils.createGroupRankConfig({
+				groupId = 12345,
+				minAdminRequiredRank = 250,
+			} :: any)
+		end).toThrow("Bad minCreatorRequiredRank")
+	end)
+
+	it("should reject a missing minAdminRequiredRank", function()
+		expect(function()
+			PermissionProviderUtils.createGroupRankConfig({
+				groupId = 12345,
+				minCreatorRequiredRank = 254,
+			} :: any)
+		end).toThrow("Bad minAdminRequiredRank")
+	end)
+end)
+
+describe("PermissionProviderUtils.createSingleUserConfig", function()
+	it("should create a single user config", function()
+		local config = PermissionProviderUtils.createSingleUserConfig({
+			userId = 12345,
+		})
+
+		expect(config.type).toEqual(PermissionProviderConstants.SINGLE_USER_CONFIG_TYPE)
+		expect(config.userId).toEqual(12345)
+		expect(config.remoteFunctionName).toEqual(PermissionProviderConstants.DEFAULT_REMOTE_FUNCTION_NAME)
+	end)
+
+	it("should honor a custom remote function name", function()
+		local config = PermissionProviderUtils.createSingleUserConfig({
+			userId = 12345,
+			remoteFunctionName = "CustomRemoteFunction",
+		})
+
+		expect(config.remoteFunctionName).toEqual("CustomRemoteFunction")
+	end)
+
+	it("should reject a missing userId", function()
+		expect(function()
+			PermissionProviderUtils.createSingleUserConfig({} :: any)
+		end).toThrow("Bad userId")
+	end)
+end)
+
+describe("PermissionProviderUtils.createConfigFromGame", function()
+	it("should create a config matching the game's creator type", function()
+		local config = PermissionProviderUtils.createConfigFromGame()
+
+		if game.CreatorType == Enum.CreatorType.Group then
+			expect(config.type).toEqual(PermissionProviderConstants.GROUP_RANK_CONFIG_TYPE)
+			expect((config :: any).groupId).toEqual(game.CreatorId)
+		else
+			expect(config.type).toEqual(PermissionProviderConstants.SINGLE_USER_CONFIG_TYPE)
+			expect((config :: any).userId).toEqual(game.CreatorId)
+		end
+	end)
+end)

package/src/Server/PermissionService.lua

@@ -22,6 +22,7 @@ local Observable = require("Observable")
 local PermissionLevel = require("PermissionLevel")
 local PermissionProviderConstants = require("PermissionProviderConstants")
 local PermissionProviderUtils = require("PermissionProviderUtils")
+local PlayerMock = require("PlayerMock")
 local Promise = require("Promise")
 local Rx = require("Rx")
 local RxBrioUtils = require("RxBrioUtils")
@@ -67,9 +68,9 @@ function PermissionService.SetProviderFromConfig(
 	assert(not self._provider, "Already have provider set")
 
 	if config.type == PermissionProviderConstants.GROUP_RANK_CONFIG_TYPE then
-		self._provider = GroupPermissionProvider.new(config)
+		self._provider = self._maid:Add(GroupPermissionProvider.new(config))
 	elseif config.type == PermissionProviderConstants.SINGLE_USER_CONFIG_TYPE then
-		self._provider = CreatorPermissionProvider.new(config)
+		self._provider = self._maid:Add(CreatorPermissionProvider.new(config))
 	else
 		error("Bad provider")
 	end
@@ -106,7 +107,7 @@ end
 	@return Promise<boolean>
 ]=]
 function PermissionService.PromiseIsAdmin(self: PermissionService, player: Player): Promise.Promise<boolean>
-	assert(typeof(player) == "Instance" and player:IsA("Player"), "bad player")
+	assert((typeof(player) == "Instance" and player:IsA("Player")) or PlayerMock.isMock(player), "bad player")
 
 	return self:PromiseIsPermissionLevel(player, PermissionLevel.ADMIN)
 end
@@ -117,7 +118,7 @@ end
 	@return Promise<boolean>
 ]=]
 function PermissionService.PromiseIsCreator(self: PermissionService, player: Player): Promise.Promise<boolean>
-	assert(typeof(player) == "Instance" and player:IsA("Player"), "bad player")
+	assert((typeof(player) == "Instance" and player:IsA("Player")) or PlayerMock.isMock(player), "bad player")
 
 	return self:PromiseIsPermissionLevel(player, PermissionLevel.CREATOR)
 end
@@ -133,7 +134,7 @@ function PermissionService.PromiseIsPermissionLevel(
 	player: Player,
 	permissionLevel: PermissionLevel.PermissionLevel
 ): Promise.Promise<boolean>
-	assert(typeof(player) == "Instance" and player:IsA("Player"), "bad player")
+	assert((typeof(player) == "Instance" and player:IsA("Player")) or PlayerMock.isMock(player), "bad player")
 	assert(PermissionLevel:IsValue(permissionLevel), "Bad permissionLevel")
 
 	if RunService:IsStudio() then