Problem

SHM "Subscriptions" are complicated, confusing, and broken. Our goal is to make them only complicated.

Solution

With a lot of new features and complexity, we can support all of the user workflows.

Definition Side Notes

The "subscriptions" in this document are unrelated to the daemon's concept of subscriptions which are considered "Sync Subscriptions". Already the user has no awareness of Sync Subscriptions- they are defined purely a function of the local accounts + their contacts.

Standalone Subscriptions

When not logged in and you click "Subscribe", we will allow an email address to subscribe directly to the site.

The site will choose the notification server.

The notify server sends a welcome email. The email is not validated, but the welcome email includes a "manage subscription" link for managing all subscriptions on that notification server.

If there is an existing Account Email within that notification server, the standalone subscription will fail and the user will be prompted to log in.

Vault Connection to Notify Server

We will introduce a new optional field to the encrypted vault data. This specifies the notify server.

If the field is empty, the vault server will specify the notification server - this is specified with an env var.

The user can choose which notification server will be used for all their accounts. In theory this can change, and the client will be responsible for deleting the Account Email and Account Subscriptions from the previous server and move them over to the new one.

Account Emails

The notification server keeps an association between Accounts and Email addresses.

The account email process begins when the account key signs a request to the notification server, with a SetEmail payload. The vault client will send this to the notify server when the user wants to start receiving mentions and replies for a given account. Maybe this is

The notification server will verify this email before setting the account email.

If standalone subscriptions exist for this email address, they will be converted to Account Subscriptions with email=true

Account Email Pre-Validation

The vault server has already validated the user's email address. And we don't want the user to have to click again.

This can be made possible by allowing the notify server to select a list of vault servers who it will trust to perform email validation, bypassing the need for the notify server to validate the email when creating an "Account Email"

The vault server does not know which accounts are in each vault, and it doesn't know which notification server the user has selected (this information is encrypted in the vault).

So the vault server will sign a payload using a server-side key, whose public key will be exposed in /hm/api/config as the signingId.

The email pre-validation payload will contain the email address, email validation time, signingId, and vault hostname.

When the vault authentication (passkey or magic link) is complete, this payload is delivered to the client alongside the encrypted vault data.

Then, the client sends the SetEmail payload and includes the pre-validation payload.

The notify server will then check if the vault host is on its list of trusted pre-validators. If so, it will fetch the signing key of the vault server, validate the signature, and automatically trust the email, skipping the email validation step.

Account Subscriptions

When redirecting the user back to the site, the vault will send the notification server that has been configured. The site also has access to the agent capability for the site's session key. This allows the site client to interface directly with the notify server for various workflows.

For one, the user can see their notifications and update read/unread status, because the client will use the notify server API.

Also, when the user wants to subscribe to a site, we will send a SetAccountSubscription to the notify server. The account subscription has some options. Each one of these can be set to 0 - Do Not Notify , 1 - App Notifications or 2 - Email + App Notifications

Document Changes - 0/1/2

New Discussions - 0/1/2

All Comments - 0/1/2

Account Mentions - 0/1/2

Some events are considered lower priority and they are not yet supported, such as per-document events, and document mentions.

UX Notes

While this project isn't specifically about the UX, we will be implementing some UX during the development.

A user may start with an email subscription but no site account.

There exist many possible relationships between two accounts:

Following - A contact exists

Joined - A contact exists with subscribe.site=true

Account Subscription - The notify server has saved the subscription and it will be used to populate the app notifications

Email Subscription - An account subscription will have an internal toggle for sending emails or not. Its possible that a user wants to see notifications about an account, but does not want to receive emails for that