Server-Authoritative RBAC

-- Is the request even SHAPED like something a real client sends?
-- A false here means "no legitimate client produced this".
local function validateShape(req: AuthRequest): (boolean, string?)
	if typeof(req.actor) ~= "Instance" or not req.actor:IsA("Player") then
		return false, "actor is not a Player"
	end
	if type(req.capability) ~= "string" then
		return false, "capability is not a string"
	end
	if req.requiresTarget then
		if typeof(req.target) ~= "Instance" or not req.target:IsA("Player") then
			return false, "action requires a Player target but none was given"
		end
	end
	return true, nil
end

function PermissionService.authorize(req: AuthRequest): boolean
	-- Identity comes from the ENGINE-PROVIDED actor only, never the payload.

	-- 1) Shape validation -- forgery detection.
	local shapeOk, reason = validateShape(req)
	if not shapeOk then
		forgeryFlags[actorId] = (forgeryFlags[actorId] or 0) + 1
		AuditLog.record({
			severity = AuditLog.Severity.Alert,
			event    = "forged_payload",
			-- + actorId, capability, and a "forgery flag #N" detail
		})
		return false
	end

	-- 2) The actual permission check.
	local allowed = PermissionService.can(req.actor, req.capability)

	-- 3) Permitted -> INFO; denied-but-well-formed -> WARN (never punished).
	AuditLog.record({
		severity = allowed and AuditLog.Severity.Info or AuditLog.Severity.Warn,
		event    = allowed and "authorized" or "denied",
	})

	return allowed
end

-- Unions capabilities up the inheritsFrom chain. Resolved once and cached;
-- cycle-guarded; unknown role -> nil (you get nothing -- fail closed).
local function resolveRole(roleName: string): ResolvedRole?
	local cached = resolvedCache[roleName]
	if cached then return cached end

	local def = Roles.Definitions[roleName]
	if not def then
		return nil -- unknown role grants nothing
	end
	if resolving[roleName] then
		warn("cyclic inheritance at role '" .. roleName .. "'")
		return nil
	end
	resolving[roleName] = true

	local capabilities, perks = {}, {}
	if def.inheritsFrom then
		local parent = resolveRole(def.inheritsFrom)
		if parent then
			for cap in parent.capabilities do capabilities[cap] = true end
			for k, v in parent.perks do perks[k] = v end
		end
	end
	for cap, granted in def.capabilities do
		if granted then capabilities[cap] = true end
	end
	for k, v in def.perks do perks[k] = v end

	resolving[roleName] = nil
	resolvedCache[roleName] = { capabilities = capabilities, perks = perks }
	return resolvedCache[roleName]
end

-- A purchase is a CLAIM until the server confirms it. We never trust a client
-- saying "I bought MVP" -- we ask MarketplaceService, server-side.
-- Each check is pcall'd and fails CLOSED: a network error upgrades no one.
function PermissionService.syncPurchasedTier(player: Player)
	for passId, tierName in Roles.GamePassToTier do
		local ok, owns = pcall(function()
			return MarketplaceService:UserOwnsGamePassAsync(player.UserId, passId)
		end)
		if ok and owns then
			-- upgradeTierIfHigher: a purchase can never DOWNGRADE a player
			upgradeTierIfHigher(player, tierName)
		end
	end
end

-- One record() entry point. The destination can change with no caller knowing.
function AuditLog.record(entry: LogEntry)
	entry.timestamp   = os.time()
	entry.serverJobId = game.JobId

	-- 1) Structured stdout line -- the parseable surface (grep for "ALERT").
	local ok, encoded = pcall(function() return HttpService:JSONEncode(entry) end)
	if ok then print("[AUDIT] " .. encoded) end

	-- 2) Persist under a unique key, fire-and-forget so it never blocks.
	if store then
		local key = nextKey()
		task.spawn(function()
			pcall(function() store:SetAsync(key, entry) end)
		end)
	end

	-- 3) (Future) external DB: a single pcall'd HttpService:PostAsync here is
	--    the ONLY change needed. Nothing else would know.
end