From a0c72f5b94e7eab50c997bfa9d2e8f2c04067bb0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mike=20Schw=C3=B6rer?= Date: Sat, 27 May 2023 18:16:32 +0200 Subject: [PATCH] Add keytoken explanation to api_more.html --- scnserver/TODO.md | 2 -- scnserver/models/keytoken.go | 8 ++--- scnserver/website/api_more.html | 57 +++++++++++++++++++++++++++++++-- scnserver/website/css/style.css | 17 ++++++---- 4 files changed, 68 insertions(+), 16 deletions(-) diff --git a/scnserver/TODO.md b/scnserver/TODO.md index 73e3ed0..5fde951 100644 --- a/scnserver/TODO.md +++ b/scnserver/TODO.md @@ -62,8 +62,6 @@ - We no longer have a route to reshuffle all keys (previously in updateUser), add a /user/:uid/keys/reset ? Would delete all existing keys and create 3 new ones? - - the explanation of user_id and key in ./website is now wrong (was already wrong and is even wronger now that there are multiple KeyToken's with permissions etc) - #### PERSONAL - in my script: use `srvname` for sendername diff --git a/scnserver/models/keytoken.go b/scnserver/models/keytoken.go index 121d7ad..cc477fa 100644 --- a/scnserver/models/keytoken.go +++ b/scnserver/models/keytoken.go @@ -11,10 +11,10 @@ import ( type TokenPerm string //@enum:type const ( - PermAdmin TokenPerm = "A" - PermChannelRead TokenPerm = "CR" - PermChannelSend TokenPerm = "CS" - PermUserRead TokenPerm = "UR" + PermAdmin TokenPerm = "A" // Edit userdata (+ includes all othe permissions) + PermChannelRead TokenPerm = "CR" // Read messages + PermChannelSend TokenPerm = "CS" // Send messages + PermUserRead TokenPerm = "UR" // Read userdata ) type TokenPermissionList []TokenPerm diff --git a/scnserver/website/api_more.html b/scnserver/website/api_more.html index a2c0d43..e3bc7bc 100644 --- a/scnserver/website/api_more.html +++ b/scnserver/website/api_more.html @@ -30,7 +30,7 @@ These two values are used to identify and authenticate your device so that send messages can be routed to your phone.

- You can at any time generate a new key in the app and invalidate the old one. + You can at any time generate new keys in the app with different permissions.

There is also a web interface for this API to manually send notifications to your phone or to test your setup. @@ -90,7 +90,7 @@ 401 (Unauthorized) - The user_id was not found or the key is wrong + The user_id was not found, the key is wrong or the [user_id, key] combination does not have the SEND permissions on the specified channel 403 (Forbidden) @@ -165,10 +165,61 @@ {{config|baseURL}}/ +

Permissions

+
+

+ A user account can have multiple keys with different permissions. + A Key has one or more permissions assigned: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PermissionIdentifierExplanation
ADMINAAllows modification of the current user, creating/editing keys, channels, subsriptions, etc. and includes all other permissions
CHANNEL READCRAllows reading and listing messages
CHANNEL SENDCSAllows sending messages
USER READURAllows querying the current user
+ +

+ Keys can also be scoped to specific channels. + A Key can either have access to all channels the user has access to, or only to a subset. + The permitted channels can either be channels of the user or foreign channels with an active subscription. +

+ +

+ A common use case is to create a key with only the CS (Channel Send) permission and only a single channel. + This key can then be used to send messages without having full access to the account. +

+
+

Message Uniqueness (Idempotency)

- Sometimes your script can run in an environment with an unstable connection and you want to implement an automatic re-try mechanism to send a message again if the last try failed due to bad connectivity. + Sometimes your script can run in an environment with an unstable connection, and you want to implement an automatic re-try mechanism to send a message again if the last try failed due to bad connectivity.

To ensure that a message is only send once you can generate a unique id for your message (I would recommend a simple uuidgen or head /dev/urandom | tr -dc A-Za-z0-9 | head -c 32). diff --git a/scnserver/website/css/style.css b/scnserver/website/css/style.css index 4e6d1d8..1ce010e 100644 --- a/scnserver/website/css/style.css +++ b/scnserver/website/css/style.css @@ -270,16 +270,19 @@ a.card:hover table.scode_table { max-height: none; - overflow: hidden; + overflow: hidden !important; } +table.scode_table td:nth-child(2), +table.scode_table th:nth-child(2){flex-grow: 3;} -table.scode_table td:nth-child(2) { - flex-grow: 3; -} - -table.scode_table th:nth-child(2) { - flex-grow: 3; +table.permlist_table { + max-height: none; + overflow: hidden !important; } +table.permlist_table td:nth-child(2), +table.permlist_table th:nth-child(2) {flex-grow: 0; min-width:80px;} +table.permlist_table td:nth-child(3), +table.permlist_table th:nth-child(3) {flex-grow: 3;} #mainpnl h2 { margin-top: 1.75rem;