prosody
9061f9621330
teal-src/module.d.tl

Find changesets by keywords by author, files, the commit message, revision number or hash, or revset expression.

Software / code / prosody

File

teal-src/module.d.tl @ 12642:9061f9621330

Switch to a new role-based authorization framework, removing is_admin() We began moving away from simple "is this user an admin?" permission checks before 0.12, with the introduction of mod_authz_internal and the ability to dynamically change the roles of individual users. The approach in 0.12 still had various limitations however, and apart from the introduction of roles other than "admin" and the ability to pull that info from storage, not much actually changed. This new framework shakes things up a lot, though aims to maintain the same functionality and behaviour on the surface for a default Prosody configuration. That is, if you don't take advantage of any of the new features, you shouldn't notice any change. The biggest change visible to developers is that usermanager.is_admin() (and the auth provider is_admin() method) have been removed. Gone. Completely. Permission checks should now be performed using a new module API method: module:may(action_name, context) This method accepts an action name, followed by either a JID (string) or (preferably) a table containing 'origin'/'session' and 'stanza' fields (e.g. the standard object passed to most events). It will return true if the action should be permitted, or false/nil otherwise. Modules should no longer perform permission checks based on the role name. E.g. a lot of code previously checked if the user's role was prosody:admin before permitting some action. Since many roles might now exist with similar permissions, and the permissions of prosody:admin may be redefined dynamically, it is no longer suitable to use this method for permission checks. Use module:may(). If you start an action name with ':' (recommended) then the current module's name will automatically be used as a prefix. To define a new permission, use the new module API: module:default_permission(role_name, action_name) module:default_permissions(role_name, { action_name[, action_name...] }) This grants the specified role permission to execute the named action(s) by default. This may be overridden via other mechanisms external to your module. The built-in roles that developers should use are: - prosody:user (normal user) - prosody:admin (host admin) - prosody:operator (global admin) The new prosody:operator role is intended for server-wide actions (such as shutting down Prosody). Finally, all usage of is_admin() in modules has been fixed by this commit. Some of these changes were trickier than others, but no change is expected to break existing deployments. EXCEPT: mod_auth_ldap no longer supports the ldap_admin_filter option. It's very possible nobody is using this, but if someone is then we can later update it to pull roles from LDAP somehow.
author Matthew Wild <mwild1@gmail.com>
date Wed, 15 Jun 2022 12:15:01 +0100
parent 12502:5862ddf71e3c
child 12643:9fa749cbd376
line wrap: on
line source

local st = require"util.stanza"

global record moduleapi
	get_name : function (moduleapi) : string
	get_host : function (moduleapi) : string
	enum host_type
		"global"
		"local"
		"component"
	end
	get_host_type : function (moduleapi) : host_type
	set_global : function (moduleapi)
	add_feature : function (moduleapi, string)
	add_identity : function (moduleapi, string, string, string) -- TODO enum?
	add_extension : function (moduleapi, st.stanza_t)
	fire_event : function (moduleapi, string, any) : any
	type handler = function (any) : any
	record util_events
		-- TODO import def
	end
	hook_object_event : function (moduleapi, util_events, string, handler, number)
	unhook_object_event : function (moduleapi, util_events, string, handler)
	hook : function (moduleapi, string, handler, number)
	hook_global : function (moduleapi, string, handler, number)
	hook_tag : function (moduleapi, string, string, handler, number)
	unhook : function (moduleapi, string, handler)
	wrap_object_event : function (moduleapi, util_events, string, handler)
	wrap_event : function (moduleapi, string, handler)
	wrap_global : function (moduleapi, string, handler)
	require : function (moduleapi, string) : table
	depends : function (moduleapi, string) : table
	shared : function (moduleapi, string) : table
	type config_getter = function<A> (moduleapi, string, A) : A
	get_option : config_getter<any>
	get_option_scalar : config_getter<nil | boolean | number | string>
	get_option_string : config_getter<string>
	get_option_number : config_getter<number>
	get_option_boolean : config_getter<boolean>
	record util_array
		-- TODO import def
		{ any }
	end
	get_option_array : config_getter<util_array>
	record util_set
		-- TODO import def
		_items : { any : boolean }
	end
	get_option_set : function (moduleapi, string, { any }) : util_set
	get_option_inherited_set : function (moduleapi, string, { any }) : util_set
	get_option_path : function (moduleapi, string, string, string) : string
	context : function (moduleapi, string) : moduleapi
	add_item : function (moduleapi, string, any)
	remove_item : function (moduleapi, string, any)
	get_host_items : function (moduleapi, string) : { any }
	handle_items : function (moduleapi, string, handler, handler, boolean)
	provides : function (moduleapi, string, table)
	record util_session
		-- TODO import def
		send : function ( st.stanza_t | string )
	end
	send : function (moduleapi, st.stanza_t, util_session)
	send_iq : function (moduleapi, st.stanza_t, util_session, number)
	broadcast : function (moduleapi, { string }, st.stanza_t, function)
	type timer_callback = function (number, ... : any) : number
	record timer_wrapper
		stop : function (timer_wrapper)
		disarm : function (timer_wrapper)
		reschedule : function (timer_wrapper, number)
	end
	add_timer : function (moduleapi, number, timer_callback, ... : any) : timer_wrapper
	get_directory : function (moduleapi) : string
	enum file_mode
		"r" "w" "a" "r+" "w+" "a+"
	end
	load_resource : function (moduleapi, string, file_mode) : FILE
	enum store_type
		"keyval"
		"map"
		"archive"
	end
	open_store : function (moduleapi, string, store_type)
	enum stat_type
		"amount"
		"counter"
		"rate"
		"distribution"
		"sizes"
		"times"
	end
	record stats_conf
		initial : number
		units : string
		type : string
	end
	measure : function (moduleapi, string, stat_type, stats_conf)
	measure_object_event : function (moduleapi, util_events, string, string)
	measure_event : function (moduleapi, string, string)
	measure_global_event : function (moduleapi, string, string)
	enum status_type
		"error"
		"warn"
		"info"
		"core"
	end
	set_status : function (moduleapi, status_type, string, boolean)
	enum log_level
		"debug"
		"info"
		"warn"
		"error"
	end
	log_status : function (moduleapi, log_level, string, ... : any)
	get_status : function (moduleapi) : status_type, string, number

	-- added by modulemanager
	name : string
	host : string
	_log : function (log_level, string, ... : any)
	log : function (moduleapi, log_level, string, ... : any)
	reloading : boolean
	saved_state : any
	record module_environment
		module : moduleapi
	end
	environment : module_environment
	path : string
	resource_path : string

	-- methods the module can add
	load : function ()
	add_host : function (moduleapi)
	save : function () : any
	restore : function (any)
	unload : function ()
end

global module : moduleapi

global record common_event
	stanza : st.stanza_t
	record origin
		send : function (st.stanza_t)
	end
end

global record prosody
	version : string
end

return module