# HG changeset patch
# User Goffi <goffi@goffi.org>
# Date 1428573958 -7200
# Node ID cfef30b6477787955b65c20e52c6a14c83a370a4
# Parent  9cf5a22e30a1f3bb5acb8d926ce1fafb4dd4a785
added page for mod_privilege

diff -r 9cf5a22e30a1 -r cfef30b64777 mod_privilege.wiki
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mod_privilege.wiki	Thu Apr 09 12:05:58 2015 +0200
@@ -0,0 +1,72 @@
+#summary XEP-0356 (Privileged Entity) implementation
+#labels Stage-Alpha
+
+= Introduction =
+
+Privileged Entity is an extension which allows entity/component to have privileged access to server (set/get roster, send message on behalf of server, access presence informations). It can be used to build services independenlty of server (e.g.: PEP service).
+
+= Details =
+
+You can have all the details by reading the [http://xmpp.org/extensions/xep-0356.html XEP-0356]. If you use if with a component, you need to patch core/mod_component.lua to fire a new signal. To do it, copy the following patch in a, for example, /tmp/component.patch file:
+{{{
+diff --git a/plugins/mod_component.lua b/plugins/mod_component.lua
+--- a/plugins/mod_component.lua
++++ b/plugins/mod_component.lua
+@@ -85,6 +85,7 @@
+                session.type = "component";
+                module:log("info", "External component successfully authenticated");
+                session.send(st.stanza("handshake"));
++               module:fire_event("component-authenticated", { session = session });
+ 
+                return true;
+        end
+}}}
+
+Then, at the root of prosody, enter:
+
+{{{patch -p1 < /tmp/component.patch}}}
+
+= Usage =
+
+To use the module, like usual add *"privilege"* to your modules_enabled, then specify privileged entities like that:
+
+{{{
+privileged_entities = {
+    ["romeo@montaigu.lit"] = {
+        roster = "get";
+        presence = "managed_entity";
+    },
+    ["juliet@capulet.lit"] = {
+        roster = "both";
+        message = "outgoing";
+        presence = "roster";
+    },
+}
+}}}
+
+Here _romeo@montaigu.lit_ can *get* roster of anybody on the server, and will *have presence for any user* of the server, while _juliet@capulet.lit_ can *get* and *set* a roster, *send messages* on the behalf of the server, and *access presence of anybody* (not only people on the server, but also people in rosters of users of the server).
+
+*/!\ Be extra careful when you give a permission to an entity/component, it's a powerful access, only do it if you absoly trust the component/entity, and you know where the software is coming from*
+
+= Configuration =
+All the permissions give access to all accounts of the servers.
+== roster ==
+||none _(default)_||No access to rosters||
+||get||Allow *read* access to rosters||
+||set||Allow *write* access to rosters||
+||both||Allow "*read* and *write* access to rosters||
+
+== message ==
+||none _(default)_||Can't send message from server||
+||outgoing||Allow to send message on behalf of server (from bare jids)||
+
+== presence ==
+||none _(default)_||Do not have extra presence information||
+||managed_entity||Receive presence stanzas (except subscriptions) from server users||
+||roster||Receive all presence stanzas (except subsciptions) from server users and people in their rosters||
+
+= Compatibility =
+||0.9||Need a patched core/mod_component.lua (see above)||
+
+= Note =
+This module is often used with (TODO) mod_delegation (c.f. XEP for more details)