From 8fa3f37baa935ee6c025318b160743c01d68df85 Mon Sep 17 00:00:00 2001 From: Philipp Metzner Date: Mon, 27 Jan 2025 17:35:15 +0100 Subject: [PATCH] Add ADR about link-sharing storage back-end --- docs/adr/adr_link-sharing-backend.md | 95 +++++++++++++++++++++++ docs/auth/public_sharing_of_statistics.md | 48 +----------- 2 files changed, 96 insertions(+), 47 deletions(-) create mode 100644 docs/adr/adr_link-sharing-backend.md diff --git a/docs/adr/adr_link-sharing-backend.md b/docs/adr/adr_link-sharing-backend.md new file mode 100644 index 0000000000..02ccf0f75e --- /dev/null +++ b/docs/adr/adr_link-sharing-backend.md @@ -0,0 +1,95 @@ +# ADR: Back-end for shareable links + +[Trello-card](https://trello.com/c/TVTCaM47/1628-20-draft-concept-for-public-link-sharing-of-statviz) + +Decision Deadline: Jan 27, 2025 + +Discussion Participants: Philipp (@pylipp), Hans (@haguesto), James (@jamescrowley) + +## Status + +Accepted. + +## Context + +Users shall be enabled to publicly share certain views, e.g. the statviz dashboard, via a generate URL. The storage back-end for this functionality can either be implemented in-house, i.e. in the boxtribute MySQL database, or with a third-party service (here: PasswordPusher). + +For more context, refer to the section "Draft for prototypical implementation" in [this document](../auth/public_sharing_of_statistics.md). + +## Decision Drivers + +1. Development speed +1. Maintenance overhead +1. Data control +1. Data insight +1. Third-party lock-in +1. Effect on UX +1. Security + +## Considered Options + +### In-house database table + +We extend the boxtribute database by adding a `shareable_link` table. The v2-back-end business logic operates on the database. + +### PasswordPusher (PP) + +PP is a popular service for sharing secrets over the web: when provided with a secret, PP creates a URL that can be shared with others in order for them to view the secret. The URL can be configured to expire after a certain time or a certain number of views. Also at link creation one can set a passphrase that must be provided when viewing the secret. PP in its basic form can be used for free via [pwpush.com](https://pwpush.com/). + +PP provides a [REST API](https://pwpush.com/api/1.1/pushes/show.en.html) for programmatic interaction with the service. + +#### Usage as link-sharing back-end + +It's possible to use PP as a back-end for the link-sharing feature: +1. When the user requests a link in v2, the parameters of the to-be-shared view are pushed to PP including appropriate configuration of link expiration and a passphrase. The unique URL code generated by PP is present to the user as the shareable link `shared.boxtribute.org/` +1. When entering a shared link, the public FE fetches the view parameters stored for the given code (using the passphrase), and then redirects to this view (e.g. `//bases/1/statviz`) +1. The view requests data from the public back-end (e.g. the statviz GraphQL requests), sending the code along +1. The BE validates the code and returns the data + +Second, favored option: +1. FE sends request to v2 BE to generate link for public sharing. BE generates code by sending a request to the PP REST API. We would need an admin user + password for this and possibly a passphrase if we think we have to secure the data stored in the PP. BE returns code as link URL +1. When resolving a link, the FE sends request to the public BE. BE validates code and retrieves information from PP. +1. BE returns information about view along with data, public FE redirects and shows view + +Eventually PP can also be self-hosted (to keep take control, and to be independent of an external service) but this would come with increased DevOps effort, and the inconvenience of introducing a second database to store shared links. + +### PP Alternatives + +According to [this list](https://alternativeto.net/software/passwordpusher/), [onetimesecret](https://docs.onetimesecret.com/docs/rest-api) can be considered an alternative but it has the immense drawback that a secret can only be viewed once. + +Other services in the list like [vanish.so](https://www.vanish.so/) are either fairly unpopular and/or don't provide any API. + +The following uses PP as exemplary service. + +## Discussion + +### Advantages of PP + +- development speed: we can save the database logic around storing shared links (incl. not having to take care of link expiration; plus having the passphrase as extra security mechanism (albeit it can be inspected easily when the public FE sends a request to the public BE)) +- maintenance: PP provides unlimited creation of links, however with rate-limit +- security: PP is open-source and [trusted by many organisations and considered secure](https://docs.pwpush.com/docs/faq/#trust-is-a-concern--why-should-i-trust-and-use-password-pusher) +- data insight: Using a PP user account enables introspection of generated links + +### Disadvantages of PP + +- data control: we don't own the raw data of shared links +- increased complexity: we add a second interface that FE has to communicate with; and we have to define a data structure to store information on PP ("hacky" encoding of link metadata into string) +- increased complexity: we add an external service for the BE to communicate with. This complicates testing and test data generation since the service needs to be mocked +- effect on UX: communicating with an external service adds a latency, likely to be larger than a simple database query +- maintenance overhead: we have to create at least one PP user profile and share access in the team, and in CI and the production env +- dependency: using PP as storage, we become depend and have to update boxtribute (FE or BE or both) if the service becomes unavailable (PP has one core maintainer). + +### Advantages of in-house DB table + +- development speed: very little uncertainty working with the familiar DB and v2 business-logic +- data control and security: we own the raw data (...on GCloud) and can directly query it through SQL +- effect on UX: rapid communication with DB + +### Disadvantages of in-house DB table + +- data insight: no dashboard with immediate statistics about shared links +- complexity: we have to implement basic rate-limiting ourselves + +## Conclusion + +Implement the data storage ourselves. Using an external service only shifts development and maintenance work while bearing the risk of becoming unavailable diff --git a/docs/auth/public_sharing_of_statistics.md b/docs/auth/public_sharing_of_statistics.md index 495a91e0a4..ed10923905 100644 --- a/docs/auth/public_sharing_of_statistics.md +++ b/docs/auth/public_sharing_of_statistics.md @@ -208,50 +208,4 @@ union ShareableLinkResult = ShareableLink | ExpiredLinkError | UnknownLinkError ### Alternative back-end -This section discusses the use of an external password-storage service like [PasswordPusher](https://github.com/pglombardo/PasswordPusher?tab=readme-ov-file) as a replacement for an in-house link-sharing back-end implementation. - -#### PasswordPusher (PP) - -PP is a popular service for sharing secrets over the web: when provided with a secret, PP creates a URL that can be shared with others in order for them to view the secret. The URL can be configured to expire after a certain time or a certain number of views. Also at link creation one can set a passphrase that must be provided when viewing the secret. PP in its basic form can be used for free via pwpush.com. - -PP provides a [REST API](https://pwpush.com/api/1.1/pushes/show.en.html) for programmatic interaction with the service. - -#### PP Alternatives - -According to [this list](https://alternativeto.net/software/passwordpusher/), [onetimesecret](https://docs.onetimesecret.com/docs/rest-api) can be considered an alternative but it has the immense drawback that a secret can only be viewed once. - -Other services in the list like vanish.so are either fairly unpopular and/or dont' provide any API. - -The following uses PP as exemplatory service. - -#### Usage as link-sharing back-end - -It's possible to use PP as a back-end for the link-sharing feature: -1. When the user requests a link in v2, the parameters of the to-be-shared view are pushed to PP including appropriate configuration of link expiration and a passphrase. The unique URL code generated by PP is present to the user as the shareable link `shared.boxtribute.org/` -1. When entering a shared link, the public FE fetches the view parameters stored for the given code (using the passphrase), and then redirects to this view (e.g. `//bases/1/statviz`) -1. The view requests data from the public back-end (e.g. the statviz GraphQL requests), sending the code along -1. The BE validates the code and returns the data - -Second option: -1. FE sends request to v2 BE to generate link for public sharing. BE generates code by sending a request to the PP REST API. We would need an admin user + password for this and possibly a passphrase if we think we have to secure the data stored in the PP. BE returns code as link URL -1. When resolving a link, the FE sends request to the public BE. BE validates code and retrieves information from PP. -1. BE returns information about view along with data, public FE redirects and shows view - -Eventually PP can also be self-hosted (to keep take control, and to be independent of an external service) but this would come with increased DevOps effort, and the inconvenience of introducing a second database to store shared links. - -#### Advantages - -- we can save the entire BE business and database logic around creating and storing shared links (incl. not having to take care of link expiration; plus having the passphrase as extra security mechanism (albeit it can be inspected easily when the public FE sends a request to the public BE)) -- PP provides unlimited creation of links, however with rate-limit -- PP is open-source and [trusted by many organisations and considered secure](https://docs.pwpush.com/docs/faq/#trust-is-a-concern--why-should-i-trust-and-use-password-pusher) - -#### Disadvantages - -- ~less data insight: we don't have control over created links (no information about amount or which views are being shared; at least not without further tracking)~ Using a PP user account enables introspection of generated links -- increased complexity: we add a second interface that FE has to communicate with; and we have to define a data structure to store information on PP ("hacky" encoding of link metadata into string) -- increased complexity: we add an external service for the BE to communicate with. This complicates testing since the service needs to be mocked, and adds a latency -- dependency: using PP as storage, we become depend and have to update boxtribute (FE or BE or both) if the service becomes unavailable - -#### Conclusion - -Implement the data storage ourselves. Using an external service only shifts development and maintenance work while bearing the risk of becoming unavailable +This section discusses the use of an external password-storage service like [PasswordPusher](https://github.com/pglombardo/PasswordPusher?tab=readme-ov-file) as a replacement for an in-house link-sharing back-end implementation. Please refer to [this ADR](../adr/adr_link-sharing-backend.md).