feat: reorganise link docs and add proton mail

docs/link/channels/e2e_channels/index.md

@@ -0,0 +1,11 @@
+---
+sidebar_position: 50
+sidebar_label: E2EE Channels
+---
+
+import DocCardList from '@theme/DocCardList';
+import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
+
+# End-to-End Encrypted Channels
+
+<DocCardList items={useCurrentSidebarCategory().items} />

docs/link/channels/e2e_channels/setup.md

@@ -0,0 +1,142 @@
+---
+sidebar_label: Initial Setup
+sidebar_position: 10
+description: Setting up E2E channels (Signal and WhatsApp)
+---
+
+# Initial setup
+
+:::info
+If you have requested a Signal and/or WhatsApp channel as part of your helpdesk setup, or you have a fully-managed
+handset provided by us, these steps will already have been completed by our support team.
+:::
+
+1. Log in to your CDR Link helpdesk admin panel using either ‘Sign in with Google button’ or Sign in with Zammad credentials’:
+
+![Untitled](/docs/link/admin/Untitled.png)
+
+1. Using the left side menu go to Admin → **WhatsApp** (or **Signal**):
+
+![Untitled](/docs/link/admin/d33b0fb2-d2e4-4130-9dfc-4e5e26ab2fad.png)
+
+1. Create the **WhatsApp** (or **Signal**) connection by using the blue ‘Create’ button in top right corner of the screen:
+
+![Untitled](/docs/link/admin/Untitled%201.png)
+
+You will see a pop-up window like the one below:
+
+- Fill the ‘Name’ field with some recognisable name (it can be useful to name it like ‘Signal handset 1’ in case if you are planning to use more numbers) of the channel
+- Fill ‘Phone Number’ field with your handsets phone number containing the relevant country code.
+
+![Untitled](/docs/link/admin/Untitled%202.png)
+
+- Click ‘Save’.
+1. You will see next window with QR code similar to the following:
+    
+    <aside>
+    💡
+    
+    You might need to wait up to one minute for the QR code to fully load (you initially will see a similar code as on the screenshot but when it loads it will have a lot more and smaller ‘squares’).
+    
+    </aside>
+    
+
+![Untitled](/docs/link/admin/Untitled%203.png)
+
+- Copy the Token and save it in a safe place.
+- Now you need to scan the code. Depending on which channel you are configuring you have to follow the instructions below (they may vary slightly depending on what kind of device you are using, in example we are using Android device):
+    - For **WhatsApp**:
+        - Go to main screen (screen with all chats visible).
+        - On the top right corner tap the ‘three dots’ icon.
+        - From the drop down menu tap on the ‘Linked devices’.
+        - Tap the green ‘Link a device’ button.
+        - Scan the code from your computers screen.
+    - For **Signal**:
+        - Go to the main screen (screen with all chats visible).
+        - On the top right corner tap the ‘three dots’ icon.
+        - From the drop down menu tap on the ‘Settings’.
+        - Tap on the ‘Linked devices’.
+        - Tap the blue ‘Link a device’ button.
+        - Scan the code from your computers screen.
+    - In both cases after scanning the code you should see your newly linked channel connection under the ‘Linked devices’ list of your WhatsApp/Signal communicator.
+- You can press the blue ‘Done’ button on your connection screen.
+1. Now you need to create a bot. Using the left side menu go to Admin → Zammad Settings → Channels → **WhatsApp** (or **Signal**):
+
+![Untitled](/docs/link/admin/Untitled%204.png)
+
+1. Create the **WhatsApp** (or **Signal)** bot by using the green ‘Add WhatsApp bot’ (or ‘Add Signal bot’) button in top right corner of the screen:
+
+![Untitled](/docs/link/admin/Untitled%205.png)
+
+You will see a pop up window like the one below:
+
+- Fill the ‘Phone Number’ field with same phone number as you used in point 3.
+- Paste the bot token from point 4 into the ‘Bot Token’ field (in case if you lost it you can always come back to the admin and click on the previously created connection in order to retrieve the token.
+- In ‘Bot Endpoint’ field paste:
+    - For **WhatsApp:**
+    
+    ```json
+    
+    http://link:3000/link/api/whatsapp
+    ```
+    
+    - For **Signal**:
+    
+    ```json
+    
+    http://link:3000/link/api/signal
+    ```
+    
+- You can leave the ‘Users’ and ‘Organization’ fields as they are or pick the relevant values.
+
+![Untitled](/docs/link/admin/7e1319ba-5c17-4eae-8226-44bbae0f7e54.png)
+
+- Click the ‘Submit’ button.
+- You will see your newly created bot on the list - click the ‘Edit’ button on the right side of the bot:
+
+![Untitled](/docs/link/admin/Untitled%206.png)
+
+- You will see the same form as previously but with one additional field: ‘Endpoint URL’ - copy the part after **https://your-helpdesk.cdr.link/api/v1/channels_cdr_whatsapp_webhook/** or **https://your-helpdesk.cdr.link/api/v1/channels_cdr_signal_webhook/** - make sure to copy all of it as it is a very long code as you can see in the example below:
+
+![Untitled](/docs/link/admin/Untitled%207.png)
+
+![Untitled](/docs/link/admin/Untitled%208.png)
+
+- Paste the code in the safe temporary place and click on the ‘Cancel & Go Back’ link on the left bottom corner of the form.
+1. The last part is to create a Webhook. Go back to the Admin panel, select Admin → Webhooks:
+
+![Untitled](/docs/link/admin/Untitled%209.png)
+
+- Click the blue ‘Create’ button in top right corner:
+
+![Untitled](/docs/link/admin/Untitled%2010.png)
+
+- You will see a webhook creation form like the one below:
+
+![Untitled](/docs/link/admin/Untitled%2011.png)
+
+- In the ‘Name’ field type some name that is relating to the channel name and handset.
+- The method drop down menu should be left with ‘Post’.
+- In the ‘Endpoint’ field paste:
+    - For **WhatsApp**:
+    
+    ```text
+    http://zammad-nginx:8080/api/v1/channels_cdr_whatsapp_webhook/xxxxxxx
+    ```
+    
+    `where ‘xxxxxx’ should be replaced with the code copied from ‘Endpoint URL’ from point 6`
+    
+    - For **Signal**:
+    
+    ```text
+    http://zammad-nginx:8080/api/v1/channels_cdr_signal_webhook/xxxxxxx
+    ```
+    
+    `where ‘xxxxxx’ should be replaced with the code copied from ‘Endpoint URL’ from point 6`
+    
+- Below there are two drop down menus:
+    - In the left one pick the relevant channel.
+    - In the right one pick the bot name that you created in step 3.
+- Click the blue ‘Save’ button.
+
+🎉 Congrats! Your connection is ready!

docs/link/channels/e2e_channels/supported_handsets.md

@@ -0,0 +1,77 @@
+---
+title: Mobile Devices
+sidebar_position: 50
+description: E2EE channels require a physical mobile device for operation
+---
+
+Signal and WhatsApp channels require a physical mobile device to be set up to create the related accounts, and this
+device must be monitored and maintained to ensure the integrity of the end-to-end encryption and the availability of
+the channel.
+
+## Fully Managed Devices
+
+We will provide a fully managed Android device to support your use of one Signal and one WhatsApp channel, if desired,
+per Link Helpdesk.
+Our devices are provisioned with UK mobile numbers (+44 country code) however you can choose your own username and
+provide any branding you would like to have set up.
+Additional channels will be subject to a fee to cover the additional cost of each required mobile device.
+
+If for any reason you choose to move away from our hosted platform in the future, see [Moving Away](../moving_away) for
+details on porting your number to your new provider.
+
+## Self-Managed Devices
+
+If due to your organisational policies you require to be in posession of the device, it is possible for you to manage
+your own devices.
+If you require support for these devices, an additional fee will be charged.
+As of May 2026 this will be the same fee as is charged for an additional fully managed device. 
+
+:::info
+There are no discounts available for self-managing your device as, in our experience, the increased support costs
+outweigh the hardware and mobile service costs.
+Support provided to self-managed device users is on a best-effort basis. We make no claims regarding expected
+response times, time between failures, or time to recovery for any issues.
+:::
+
+### Hardware and Configuration
+
+* We only support OEM Google Pixel devices and these must be in current security support
+  ([end of life dates](https://endoflife.date/pixel)).
+* The device must have a mobile service contract that:
+  * has a sufficient monthly allowance for data for operating system and application updates, as well as the messaging
+    data which may include audio and video content;
+  * allows inbound and outbound calls and SMS; and
+  * has a permanently assigned mobile number.
+* The device must not be in use for any other purpose and interactions with the device should only be performed for the
+  purpose of monitoring and maintenance.
+* The device should be managed with a Mobile Device Management (MDM) solution to:
+  * automatically install operating system and application updates;
+  * restrict the installed apps, which may only be installed when signed with a valid certificate from a trusted app
+    store;
+  * enforce lock timeouts and strong unlock credential requirements;
+  * disable unnecessary features that would otherwise provide attack surface (e.g., WiFi and Bluetooth); and
+  * provide remote wipe capability.
+
+### Procedures
+
+* The device:
+  * must be continuously connected to the mobile network with data access enabled;
+  * must be kept turned on and charged, **using a charging system that does not keep the device connected to power 24 hours a day as this will lead to battery failure and risk of fire**;
+  * must have sufficient physical security considerations taken (e.g. kept in locked room when unattended);
+  * must not have mobile signal blocked from operation (e.g. do not store it in a metal safe);
+  * must have well-documented access control policies in place; and
+  * must be restarted once a week.
+* Monitor the logs of the MDM to ensure updates are applied.
+* Subscribe to security advisories for Android, Signal, WhatsApp and your MDM solution to endure critical and high
+  impact vulnerabilities are patched promptly.
+* Check channel operation regularly and relink the device if needed.
+* Regularly audit the device configuration and procedures, and who can access it.
+
+
+:::warning
+While we can advise you on a configuration for the device, security is a combination of applied configuration,
+physical security and formal processes such as regular internal or external audits.
+Only your organisation is able to ensure these recommendations are followed when self-managing your device.
+For this reason, we do not accept any responsibility related to any security incidents related to your self-management
+of the device.
+:::

docs/link/channels/google_channel.md

@@ -0,0 +1,25 @@
+---
+title: Setting up a Google channel
+sidebar_position: 102
+---
+# Setting up a Google channel
+
+1. Create a new project called "Zammad" under the desired Google account from [https://console.cloud.google.com/apis/dashboard](https://console.cloud.google.com/apis/dashboard) (a new project is required to create the secure Google App that is linked to the helpdesk).
+2. Enable the Gmail API for this project by going to [https://console.cloud.google.com/apis/library/browse](https://console.cloud.google.com/apis/library/browse), selecting Gmail API and then enabling it. This is the API needed for communication between the helpdesk and Google.
+3. Create a Google Application called "Zammad", by going to [https://console.cloud.google.com/apis/credentials/consent](https://console.cloud.google.com/apis/credentials/consent).
+Give this application permissions to read, write and modify (but not delete) emails in the inbox for the Google account that needs to be linked to the helpdesk, by granting it the Gmail API "modify" scope. We created this application as it will be used by the helpdesk to receive and send emails.
+4. Create OAuth credentials by going to [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials). Here configure the permitted callback url to be [https://\<instance-name\>/api/v1/external_credentials/google/callback](https://demo.cdr.link/api/v1/external_credentials/google/callback). This will create a Google client ID and secret.
+5. Finally, link the helpdesk (Zammad) to the Google application by configuring a Google channel in [https://\<instance-name\>/#channels/google](https://cchub.cdr.link/#channels/google). Select "Configure App", where you can introduce the OAuth credentials (client ID and secret) created in the previous step.
+6. Select "Add account" from [https://\<instance-name\>/#channels/google](https://demo.cdr.link/#channels/google)
+ from a browser session where you are logged into Google with the same email address that will be linked to the helpdesk. When prompted, opt to keep all messages on the server; otherwise Zammad will try to delete them.
+
+## Troubleshooting
+
+1. If the final step fails with a ‘403 forbidden’ error, it may be necessary to log into the helpdesk as the user, go to ‘Profile’:
+    
+    ![profile](/docs/link/admin/google_channel/zammad_profile.png)
+    
+
+From there, navigate to ‘linked accounts’, and select ‘remove’:
+
+![linked_accounts](/docs/link/admin/google_channel/linked_accounts.png)

docs/link/channels/index.mdx

@@ -0,0 +1,11 @@
+---
+sidebar_position: 20
+sidebar_label: Channels Guide
+---
+
+import DocCardList from '@theme/DocCardList';
+import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
+
+# Channels Guide
+
+<DocCardList items={useCurrentSidebarCategory().items} />

docs/link/channels/proton.md

@@ -0,0 +1,65 @@
+---
+title: Proton Mail Channel
+sidebar_label: Proton Mail Channel
+sidebar_position: 55
+description: Using a ProtonMail email account
+---
+
+[Proton Mail](https://proton.me/mail) is the largest end-to-end encrypted email hosting service.
+It was launched in 2014 and is headquartered in Geneva, Switzerland.
+It is owned by the non-profit Proton Foundation through its subsidiary Proton AG.
+Proton Mail uses client-side encryption to protect email content and user data before they are sent to Proton Mail
+servers, unlike other common email providers.
+
+The source code for the back end of Proton Mail remains closed-source, but Proton Mail released the source code for the
+web interface, iOS and Android apps, and the [Proton Mail Bridge app](https://github.com/ProtonMail/proton-bridge)
+under an open-source licence.
+
+Although Proton Mail's encryption uses the open standard OpenPGP, and the Link platform support OpenPGP when used with
+other email providers, it is not possible to directly interact with the encryption from the Link platform.
+This is because Proton Mail does not provide the traditional IMAP and SMTP server endpoints to send and receive emails
+and only allows connection via the Proton Mail bridge app which handles all encryption and decryption of messages.
+
+## Requirements
+
+* You must have a paid plan to use the Proton Mail channel as the use of the Proton Mail Bridge app is not possible on
+a free account.
+* Additionally, a user must be dedicated for the use of the helpdesk, it is not sufficient to create an alias on an
+existing user.
+
+## Encryption & Key Management
+
+OpenPGP private keys are created automatically for each Proton Mail account, although these are stored in a way that
+they are not generally available other than when successfully authenticated to the platform.
+In the case of Link, this means that the Proton Mail Bridge app is authenticated and then has access to the OpenPGP
+private key.
+
+It is not currently possible to import public keys of 3rd-party (i.e. non-Proton Mail) email addresses, and so only
+emails between Proton Mail users will be end-to-end encrypted.
+The service also
+[does not support the Autocrypt standard](https://protonmail.uservoice.com/forums/945460-general-ideas/suggestions/32845105-autocrypt-support),
+which allows other clients to import discovered public keys automatically on new conversations.
+The Proton Mail documentation [has more on this topic](https://proton.me/support/proton-mail-encryption-explained).
+
+We will provide you with your public OpenPGP key when the channel is set up, and you can make this discoverable via your
+website, but for conversations with 3rd-party accounts we expect the conversations will only be encrypted in one
+direction and your replies will not be encrypted.
+
+The helpdesk is unaware of the encryption happening in Protonmail, and cannot inform agents when an email that was sent
+or received by the helpdesk was encrypted or not.
+
+## Setting up
+
+If you do not have an organisational account, we can fully manage the Proton Mail account setup including billing.
+Please [contact us](https://www.sr2.uk/contact) to discuss this.
+
+If you have an organisational account,
+[send an invite for the new user](https://proton.me/support/add-users-organization#create-a-new-user) (the new helpdesk
+channel address) to contact@sr2.uk, and email the same address to let us know you are doing this and that you would
+like the channel added to your helpdesk.
+
+Once the setup is complete we will provide you with OpenPGP public key and will also upload it to
+[keys.openpgp.org](https://keys.openpgp.org/) to aid in its discovery by users.
+We can also provide support on setting up Web Key Discovery (WKD) on your custom email domain if desired to further
+increase the chances that inbound emails will be automatically encrypted, although this still cannot help to encrypt
+replies to 3rd-party email services.