From a1869a5950c97042f7c2570c99a7d6a648758f80 Mon Sep 17 00:00:00 2001
From: Florian Dold <florian@dold.me>
Date: Wed, 20 Jan 2021 21:07:47 +0100
Subject: libeufin permissions and user management

---
 libeufin/api-nexus.rst      | 75 ++++++++++++++++++++++++++++++++++++++++++++-
 libeufin/nexus-tutorial.rst | 44 ++++++++++++++++++++++++++
 2 files changed, 118 insertions(+), 1 deletion(-)

diff --git a/libeufin/api-nexus.rst b/libeufin/api-nexus.rst
index 96cdbefb..ef1a3c00 100644
--- a/libeufin/api-nexus.rst
+++ b/libeufin/api-nexus.rst
@@ -102,11 +102,84 @@ User Management
 
   Return list of users.
 
+.. _nexus-permissions-api:
+
+Permissions API
+---------------
+
+The permissions API manages authorization of access of subjects (usually users)
+to resources.
+
+Permissions are modeled a set of ``(subject, resource, permission)`` triples.
+Subjects and resources consist of a type and an identifier.
+
+Superusers are not subject to further permission checks, they are allowed
+to do any operation.
+
+The following subject types are currently supported:
+
+* ``user``:  An authenticated user.  The subject ID
+  is interpreted as the user ID.
+
+The following permissions are currently defined:
+
+* ``facade.talerWireGateway.history``:  Allows querying the
+  transaction history through a Taler wire gateway facade.
+* ``facade.talerWireGateway.transfer``: Allows creating payment initiations
+  to transfer money via a Taler wire gateway facade.
+
+The following resource IDs are currently supported:
+
+* ``facade``: A LibEuFin facade.  The resource ID is interpreted as the
+  facade name.
+
+.. http:get:: {nexusbase}/permissions
+
+   List all permissions.
+
+   **Response**
+
+  .. ts:def:: QueryPermissionsResponse
+
+     interface QueryPermissionsResponse {
+       permissions: {
+         subjectType: string;
+         subjectId: string;
+         resourceType: string;
+         resourceId: string;
+         permissionName: string
+       }[];
+     }
+
+.. http:post:: {nexusbase}/permissions
+
+   Modify permissions.
+
+   **Request**
+
+  .. ts:def:: QueryPermissionsResponse
+
+     interface QueryPermissionsResponse {
+       action: "grant" | "revoke";
+       permission: {
+         subjectType: string;
+         subjectId: string;
+         resourceType: string;
+         resourceId: string;
+         permissionName: string
+       };
+     }
+
+   **Response**
+
+   The response is an empty JSON object.
+
+
 Test API
 --------
 
 
-.. http:post:: {nexusBase}/bank-accounts/{acctid}/test-camt-ingestion/{type}
+.. http:post:: {nexusbase}/bank-accounts/{acctid}/test-camt-ingestion/{type}
 
   This call allows tests to **directly** give Nexus a Camt document.  After
   the processing, all the payment(s) details should be ingested as if the
diff --git a/libeufin/nexus-tutorial.rst b/libeufin/nexus-tutorial.rst
index 8c0d941f..6ef78829 100644
--- a/libeufin/nexus-tutorial.rst
+++ b/libeufin/nexus-tutorial.rst
@@ -446,3 +446,47 @@ existing bank account / connection pair.
 At this point, the additional *taler-wire-gateway* (FIXME: link
 here to API here) API becomes offered by the Nexus.  The purpose
 is to let a Taler exchange to rely on Nexus to manage its bank account.
+
+
+Managing Permissions and Users
+==============================
+
+This guide has so far assumed that a superuser is accessing the LibEuFin Nexus.
+However, it is advisable that the Nexus is accessed with users that only have a
+minimal set of permissions.
+
+The Nexus currently only has support for giving non-superusers access to Taler
+wire gateway facades.
+
+To create a new user, use the ``users`` subcommand of the CLI:
+
+.. code-block:: console
+
+  $ libeufin-cli users list
+  # [ ... shows available users ... ]
+
+  $ libeufin-cli users create $USERNAME
+  # [ ... will prompt for password ... ]
+
+Permissions are managed with the ``permissions`` subcommand.
+The following commands grant permissions to view the transaction history
+and create payment initiations with a Taler wire gateway facade:
+
+
+.. code-block:: console
+
+  $ libeufin-cli permissions grant \
+     user $USERNAME \
+     facade $FACADENAME \
+     facade.talerWireGateway.history
+
+  $ libeufin-cli permissions grant \
+     user $USERNAME \
+     facade $FACADENAME \
+     facade.talerWireGateway.transfer
+
+The list of all granted permissions can be reviewed:
+
+.. code-block:: console
+
+  $ libeufin-cli permissions list
-- 
cgit v1.2.3