commit 00e21104d538f7cb50858212dbd121cd3739de7d
parent 625b293709e343ae2c44b3796f55fd5a1c541ce2
Author: Florian Dold <florian@dold.me>
Date: Thu, 31 Jul 2025 17:33:39 +0200
new DDs
Diffstat:
3 files changed, 271 insertions(+), 0 deletions(-)
diff --git a/design-documents/067-merchant-self-provisioning.rst b/design-documents/067-merchant-self-provisioning.rst
@@ -0,0 +1,161 @@
+DD 67: Merchant Self Provisioning
+#################################
+
+*Status*: incomplete draft (2025-07-31)
+
+Summary
+=======
+
+The self-provisioning feature allows merchants sign up for their own Taler
+Merchant Backend instance.
+
+Motivation
+==========
+
+It's not feasible for non-technical merchants that want to use Taler to
+set up their own server with a merchant backend instance running.
+
+Requirements
+============
+
+* The self-provisioning should be completely automatic,
+ manual actions of the the service provider must be kept at a minimum.
+
+Proposed Solution
+=================
+
+Implementation tasks:
+
+* Merchant backend
+
+ * New public endpoint for self-provisioned instance creation
+ * New (private) endpoints for 2FA channel confirmation
+ * New public endpoints for password reset
+ * Changed endpoint for instance details (must include email/phone)
+ * Database schema changes / migration
+
+ * Ideally with migration test
+
+* Merchant SPA:
+
+ * onboarding page
+ * password reset flow
+ * new email/phone field in instance details
+
+Documentation tasks:
+
+* New options for self-provisioning documented in man page
+* API changes documented in API docs
+* Setup of 2FA providers (via helper scripts) documented in merchant operator manual
+
+Deployment tasks:
+
+* Integrated self-provisioning in sandcastle-ng
+
+Testing tasks:
+
+* taler-harness tests for self provisioning
+* test steps added to docs.taler.net
+* test steps run as part of final QC
+
+Flows
+=====
+
+Signup:
+
+* User goes to the merchant SPA in their browser
+* User selects sign-up option
+* User enters details, incl. phone number and e-mail
+* Backend sends 2FA confirmation codes to user
+* User enters 2FA codes on website
+
+ * User can re-request 2FA codes after cooldown, limited attempts
+
+* Once 2FA channels are confirmed by the backend, user has full
+ access to the merchant backend instance.
+
+ * While 2FA confirmation is pending, password login works,
+ but only limited actions are available.
+
+Password reset:
+
+* User selects "Reset Password" option on the login screen
+* User enters their username
+* Backend sends E-Mail and SMS verification codes to the user
+* User enters 2FA codes on website
+* On successful validation of 2FA codes, user can enter new password
+
+ * User can re-request 2FA codes after cooldown, limited attempts
+
+* User can log in with their new password
+
+UI Structure Mocks
+==================
+
+New login page:
+
+::
+
+ Login required
+
+ Username: [ ... ]
+ Password: [ ... ]
+
+ [Confirm]
+ ---
+ [Sign up] [Forgot Password]
+
+Signup page:
+
+::
+
+ Please enter your information to create a new merchant instance:
+
+ Username: [ ... ]
+ Password: [ ... ]
+ E-Mail*: [ ... ]
+ Phone number*: [ ... ]
+
+ * This information is used to restore access to your account
+
+Definition of Done
+==================
+
+* Children of tracking bug (https://bugs.taler.net/n/10224) all closed
+
+
+Drawbacks and Alternatives
+==========================
+
+* The name might be too technical. Maybe call it "self onboarding" or "self sign-up"?
+* Merchants need to fully trust the provider.
+* Multi-tenancy always has some negative security implementations
+
+ * Alternative: Deploy *separate* merchant backends per user instead of deploying an instance, in
+ order to avoid multi-tenancy drawbacks.
+
+Scope
+=====
+
+Explicitly out of scope *for now* are:
+
+* Invitation links (i.e. closed self sign-ups)
+* Manual approval of sign-ups. For now, sign-ups are automatically
+ approved/active.
+* 2FA for login
+* 2FA for particular operations (e.g. changing bank account)
+
+Related Efforts
+===============
+
+The corebank API also has 2FA. We should keep the API design as aligned as
+possible.
+
+Discussion / Q&A
+================
+
+* Can the merchant delete their own instance? Or is it some support request via e-mail?
+* How does the instance user known the admin/support contact? Is there some page for that in the side-bar?
+ Or is this external to the feature?
+* What happens while the 2FA channels aren't confirmed yet?
+
diff --git a/design-documents/068-tokens-roadmap.rst b/design-documents/068-tokens-roadmap.rst
@@ -0,0 +1,108 @@
+DD 68: Token Feature Roadmap
+############################
+
+*Status*: incomplete draft (2025-07-31)
+
+Summary
+=======
+
+This design document documents the roadmap for token types
+supported by Taler.
+
+Motivation
+==========
+
+Plan for Wallet
+===============
+
+Types of tokens:
+
+* donations tokens (hard deadline: End of November)
+
+ * onboarding (1st donation)
+
+ * ask for tax payer id, add taxOfficeBaseUrl (only one per wallet)
+ * can be changed, but new donations will have a different tax payer ID
+ * store date with tax payer ID for merge
+
+ * reporting: per year, one QR code per: (taxPayerId, walletSalt, year)
+
+ * meta data per QR code: taxPayerId, walletSalt, year, taxOfficeBaseUrl
+ * out of scope: generate PDF
+ * listing: just show sum (per tax payer ID and year and salt), not individual tokens
+
+ * listing: there is separate listing for tokens
+ * delete: out of scope for now / future work
+
+* subscription
+
+ * listing
+
+ * Expired tokens are deleted automatically after grace period (30 days).
+ * Consider not deleting the last token of a particular slug.
+ Maybe in the future, subscription tokens will have a link
+ to re-purchase them.
+ * No counter
+ * Show expiration date
+ * delete (with big fat warning)
+
+* discount tokens
+
+ * listing (type and number, description)
+ * group by expiration date (if it exists)
+ * delete
+
+* asset tokens (deadlines: end of March)
+
+ * listing (with number, no fractions possible, no expiration)
+ * background task: poll for share action, automatically execute the share action
+
+ * share action dividend: not supported for now
+ * share action voting: multiple in parallel possible, maybe show vote weight, have expiration date
+ * votes are grouped under the respective asset tokens
+
+ * voting action
+
+ * normally grouped under asset token ("history" for corporate actions)
+ * in notificiation state: vote directly or dismiss
+ * eventually, result is fetched and shown
+
+ * divident (initially out of scope)
+
+ * normally grouped under asset token ("history" for corporate actions)
+ * in notificiation state: dismiss, auto-dismiss after some time
+
+Plan for Merchant Backend
+=========================
+
+TBD.
+
+Plan for Donau
+==============
+
+* Service exists
+* Needs to packaged
+
+
+Test Plan
+=========
+
+* Subscription/discount: blog.demo.taler.net
+* Donations: donations.demo.taler.net
+
+ * Receipt validation: TBD
+
+* Asset tokenization: TBD / will be deployed on demo via merchant
+
+
+Definition of Done
+==================
+
+* Donau deployed in sandcastle
+* donations in demo must use donau / contracttermsv1
+* use separate app (prototype exists?) for verification of receipts
+
+Discussion / Q&A
+================
+
+(This should be filled in with results from discussions on mailing lists / personal communication.)
diff --git a/design-documents/index.rst b/design-documents/index.rst
@@ -78,4 +78,6 @@ Design documents that start with "XX" are considered deprecated.
064-kyc-operation-algo
065-exchange-base-url-migration
066-wallet-color-scheme
+ 067-merchant-self-provisioning
+ 068-tokens-roadmap
999-template
