Document hardware token signing, login config corrections (#120)

Author: Frooodle

docs/Configuration/File Sharing and Storage.md

@@ -264,6 +264,8 @@ Your folders are private to you. Folders themselves are not shared; you share in
 
 ## Sharing Files
 
+You can share a file from the **My Files** page, or from the **Share** button in the top bar of the editor workbench while a file is open.
+
 ### Share with a Specific User
 
 From the file manager, select a file and share it with another user by their username or email address. You can choose the access role when sharing.

docs/Configuration/OAuth SSO Configuration.md

@@ -361,7 +361,7 @@ Once you've verified OAuth works and promoted an OAuth user to admin, you can di
 | Property | Description | Default | Example |
 |----------|-------------|---------|---------|
 | `security.oauth2.issuer` | OIDC issuer URL (required for generic providers, must support `/.well-known/openid-configuration`) | - | `https://keycloak.example.com/realms/myrealm` |
-| `security.oauth2.autoCreateUser` | Auto-create users on first login | `false` | `true` |
+| `security.oauth2.autoCreateUser` | Auto-create users on first login | `true` | `false` |
 | `security.oauth2.blockRegistration` | Block new user registration, only allow pre-registered users | `false` | `true` |
 | `security.oauth2.scopes` | Space or comma-separated list of OAuth scopes | Provider-specific | `openid, profile, email` |
 | `security.oauth2.useAsUsername` | Claim to use as username (options depend on provider) | Provider-specific | `email`, `preferred_username`, `login` |

docs/Configuration/Other Customisations.md

@@ -19,12 +19,12 @@ This means you can replace any static resource by placing a file with the matchi
 
 ### Finding File Paths to Override
 
-Most static files in the application come from the `frontend/editor/public/` folder in the source code. To override a file, place it under `customFiles/static/` matching the same path it is served at. The mapping is direct:
+Most static files in the application come from the `frontend/editor/public/` folder in the source code (brand logos live in `frontend/shared/assets/brand/`). To override a file, place it under `customFiles/static/` matching the same path it is served at. The mapping is direct:
 
 **Frontend source → Your override path:**
 - `frontend/editor/public/manifest.json` → `customFiles/static/manifest.json`
-- `frontend/editor/public/modern-logo/StirlingPDFLogoBlackText.svg` → `customFiles/static/modern-logo/StirlingPDFLogoBlackText.svg`
-- `frontend/editor/public/classic-logo/StirlingPDFLogoBlackText.svg` → `customFiles/static/classic-logo/StirlingPDFLogoBlackText.svg`
+- `frontend/shared/assets/brand/modern-logo/StirlingPDFLogoBlackText.svg` → `customFiles/static/modern-logo/StirlingPDFLogoBlackText.svg`
+- `frontend/shared/assets/brand/classic-logo/StirlingPDFLogoBlackText.svg` → `customFiles/static/classic-logo/StirlingPDFLogoBlackText.svg`
 
 **To see what files you can override:**
 1. Browse the [frontend/editor/public folder on GitHub](https://github.com/Stirling-Tools/Stirling-PDF/tree/main/frontend/editor/public)

docs/Configuration/Process-Limits.md

@@ -36,7 +36,6 @@ Controls how many concurrent instances of each process are allowed. Extra reques
 | `sessionLimit.ocrMyPdfSessionLimit` | `2` | Add OCR overlay to existing PDFs |
 | `sessionLimit.weasyPrintSessionLimit` | `16` | HTML/CSS → PDF (WeasyPrint) |
 | `sessionLimit.calibreSessionLimit` | `1` | E-book conversions |
-| `sessionLimit.ffmpegSessionLimit` | `2` | Video/audio processing |
 | `sessionLimit.installAppSessionLimit` | `1` | Internal install tasks |
 
 **Increase** limits on a beefy server with concurrent users. **Decrease** them on low-RAM servers - LibreOffice in particular is memory-hungry.
@@ -64,7 +63,6 @@ How long (in minutes) a process can run before it's forcibly killed and an error
 | `timeoutMinutes.ocrMyPdfTimeoutMinutes` | `30` |
 | `timeoutMinutes.weasyPrintTimeoutMinutes` | `30` |
 | `timeoutMinutes.calibreTimeoutMinutes` | `30` |
-| `timeoutMinutes.ffmpegTimeoutMinutes` | `30` |
 | `timeoutMinutes.pdfToHtmlTimeoutMinutes` | `20` |
 | `timeoutMinutes.installAppTimeoutMinutes` | `60` |
 

docs/Configuration/SAML SSO Configuration/SAML SSO Configuration.md

@@ -262,7 +262,7 @@ Restart Stirling PDF.
 
 | Property | Default | Description |
 |----------|---------|-------------|
-| `security.saml2.autoCreateUser` | `false` | Auto-create users on first SAML login |
+| `security.saml2.autoCreateUser` | `true` | Auto-create users on first SAML login |
 | `security.saml2.blockRegistration` | `false` | Block new users (only allow pre-registered) |
 | `security.saml2.registrationId` | `stirling` | Registration ID (must match ACS URL path) |
 | `security.saml2.provider` | `null` | Optional provider name for logging |

docs/Configuration/System and Security.md

@@ -133,6 +133,33 @@ java -jar Stirling-PDF.jar
 
 ---
 
+## Login Agreement / Disclaimer
+
+Show a disclaimer that users must accept before they can use the app. It appears as a blocking dialog after a successful login (or on launch when login is disabled), and works on every edition.
+
+```yaml
+legal:
+  loginAgreement:
+    enabled: false              # Master on/off switch
+    showInAnonymousMode: true   # When login is disabled, set false to hide the dialog
+    fallbackText: ""            # Markdown shown when no per-language file is found
+```
+
+**Environment Variables:**
+```bash
+LEGAL_LOGINAGREEMENT_ENABLED=true
+LEGAL_LOGINAGREEMENT_SHOWINANONYMOUSMODE=true
+LEGAL_LOGINAGREEMENT_FALLBACKTEXT="By signing in you agree to the terms..."
+```
+
+The disclaimer is written in **Markdown**. Provide per-language versions as files at `customFiles/disclaimer/<locale>.md` (for example `en-US.md` or `de-DE.md`); the text shown follows each user's interface language and falls back to `fallbackText` when no matching file exists. If no text resolves at all (no files and no `fallbackText`), the dialog is not shown even when `enabled` is `true`. For a single-language or headless install, set `fallbackText` (env `LEGAL_LOGINAGREEMENT_FALLBACKTEXT`) and skip the per-language files. Editing the text takes effect on the next login with no restart; turning `enabled` on or off requires a restart.
+
+Admins can also edit the text in-app from **Admin Settings → Legal**, which writes the same per-language files.
+
+In the desktop app, the dialog can be enabled per machine through MDM - see [Managed Desktop Deployment](../Installation/Managed%20Deployment.md).
+
+---
+
 ## Server Certificates
 
 Stirling PDF can auto-generate certificates for the "Sign with Stirling PDF" feature.

docs/Configuration/UI Customisation.md

@@ -11,9 +11,9 @@ Stirling PDF allows straightforward customization of the application name and ap
 
 ## Application Name Settings
 These settings control the visible application name:
-- `appName` - Defines the visible application name shown in the window name and navbar if navbar is not defined separately
-- `homeDescription` - The description displayed on the homepage under the navbar that first greets the user
-- `appNameNavbar` - The app name shown within the navbar for all pages
+- `appName` - The visible application name for your instance
+- `homeDescription` - The description displayed on the homepage that first greets the user
+- `appNameNavbar` - Used as the browser tab title and as the issuer name shown in authenticator apps for two-factor (TOTP) login. Despite its name it is not shown in the navigation bar (which displays the logo), so do not leave it blank if you use TOTP. Empty falls back to "Stirling PDF".
 
 ## Show update notifications
 These settings (in Settings.yml) control system behavior and customization capabilities:
@@ -153,7 +153,7 @@ This approach requires maintaining your fork and manually merging updates.
     ui:
       appName: exampleAppName # Application's visible name
       homeDescription: I am a description # Short description or tagline shown on homepage
-      appNameNavbar: navbarName # Name displayed on the navigation bar
+      appNameNavbar: navbarName # Browser tab title and TOTP issuer label (not the navbar)
 
     system:
       showUpdate: false # Control update notification visibility

docs/Functionality/Read-and-Annotate.md

@@ -46,6 +46,10 @@ For adding signatures (typed, drawn, or uploaded), use the dedicated [Sign PDFs]
 - Comments sidebar listing all comments grouped by page; within each page, comments appear in visual reading order (top-to-bottom, left-to-right)
 - Click to navigate to the source annotation
 
+### Side Panels
+- Dedicated side panels for **comments**, **annotations**, and **attachments**, each with quick controls for adding items
+- A **clear all** button removes every comment or annotation in one action
+
 ---
 
 ## Viewer Features

docs/Functionality/Security/Certificate-Signing.md

@@ -21,7 +21,7 @@ Digitally sign PDFs with X.509 certificates and validate existing signatures aga
 
     1. Go to **Certificate Sign** tool
     2. Upload PDF
-    3. In the **Sign Mode** step, choose **Auto (server)** (shown only when the server certificate feature is enabled)
+    3. In the **Certificate source** step, choose **Server** (shown only when the server certificate feature is enabled)
     4. Configure signature appearance (optional)
     5. Sign and download
 
@@ -52,7 +52,7 @@ Digitally sign PDFs with X.509 certificates and validate existing signatures aga
 
     1. Go to **Certificate Sign** tool
     2. Upload PDF
-    3. In the **Sign Mode** step, choose **Manual**, then pick your certificate format
+    3. In the **Certificate source** step, choose **Upload**, then pick your certificate format
     4. Upload your certificate file(s) and enter the password (if any)
     5. Configure signature appearance
     6. Sign and download
@@ -77,7 +77,29 @@ Digitally sign PDFs with X.509 certificates and validate existing signatures aga
         organizationName: Acme Corp
     ```
 
-    Once configured, users can choose **Auto (server)** in the **Sign Mode** step to sign with the shared certificate.
+    Once configured, users can choose **Server** in the **Certificate source** step to sign with the shared certificate.
+  </TabItem>
+  <TabItem value="device" label="This Device (Desktop)">
+    Sign with a certificate held on your own machine - a USB token or smart card (PKCS#11), or the Windows certificate store. The private key never leaves the device: Stirling PDF asks the token or operating system to perform the signing. This option appears only in the **desktop app** and works on every edition.
+
+    1. Go to **Certificate Sign** tool
+    2. Upload PDF
+    3. In the **Certificate source** step, choose **This device**
+    4. Pick the hardware type:
+       - **Windows certificate store** (Windows only) - available certificates are listed automatically; pick one. Windows prompts for the card or token PIN when you sign.
+       - **USB token** (PKCS#11, Windows/macOS/Linux) - choose the PKCS#11 driver (common drivers such as OpenSC, YubiKey, SafeNet eToken, and Thales IDPrime are detected automatically, or enter a custom driver path), enter the token PIN, then **List certificates** and pick one.
+    5. Configure signature appearance
+    6. Sign and download
+
+    For security, you can only sign with a PKCS#11 driver that Stirling PDF auto-detects or one you explicitly allow. Add extra driver libraries with the `STIRLING_PKCS11_LIBRARIES` environment variable - absolute paths to the driver files, separated by your platform's path separator:
+
+    ```bash
+    STIRLING_PKCS11_LIBRARIES=/usr/lib/opensc-pkcs11.so
+    ```
+
+    :::note macOS and Linux
+    The macOS Keychain is not a direct signing source. On macOS and Linux, reach a smart card or token through a PKCS#11 driver such as OpenSC.
+    :::
   </TabItem>
 </Tabs>
 
@@ -243,7 +265,7 @@ curl -X POST http://stirling-pdf:8080/api/v1/security/timestamp-pdf \
 </Tabs>
 
 :::note
-The `system.serverCertificate.*` keys are honoured only on Pro/Enterprise editions. On the free self-hosted edition, setting `enabled: true` has no effect and the **Auto (server)** sign mode stays hidden; use a custom certificate (Manual mode) instead. All `security.validation.*` and `security.timestamp.*` settings apply to every edition.
+The `system.serverCertificate.*` keys are honoured only on Pro/Enterprise editions. On the free self-hosted edition, setting `enabled: true` has no effect and the **Server** certificate source stays hidden; use a custom certificate (**Upload**), or **This device** in the desktop app, instead. All `security.validation.*` and `security.timestamp.*` settings apply to every edition.
 :::
 
 ---
@@ -253,7 +275,7 @@ The `system.serverCertificate.*` keys are honoured only on Pro/Enterprise editio
 <Tabs>
   <TabItem value="sign-server" label="Sign (Server Cert)">
     ```bash
-    # certType must be one of PEM, PKCS12, PFX, JKS, SERVER (uppercase)
+    # certType must be one of PEM, PKCS12, PFX, JKS, SERVER, WINDOWS_STORE, PKCS11 (uppercase)
     # certType=SERVER requires the Pro/Enterprise server certificate feature to be enabled
     curl -X POST http://stirling-pdf:8080/api/v1/security/cert-sign \
       -F "fileInput=@document.pdf" \
@@ -276,6 +298,19 @@ The `system.serverCertificate.*` keys are honoured only on Pro/Enterprise editio
       -o signed.pdf
     ```
   </TabItem>
+  <TabItem value="sign-device" label="Sign (Device)">
+    ```bash
+    # Desktop app only; the request must come from the local machine.
+    # WINDOWS_STORE selects a cert by alias; PKCS11 uses pkcs11LibraryPath (+ optional pkcs11Slot),
+    # with password as the token PIN.
+    curl -X POST http://localhost:8080/api/v1/security/cert-sign \
+      -F "fileInput=@document.pdf" \
+      -F "certType=PKCS11" \
+      -F "pkcs11LibraryPath=/usr/lib/opensc-pkcs11.so" \
+      -F "password=token-pin" \
+      -o signed.pdf
+    ```
+  </TabItem>
   <TabItem value="validate" label="Validate">
     ```bash
     curl -X POST http://stirling-pdf:8080/api/v1/security/validate-signature \

docs/Installation/Managed Deployment.md

@@ -46,10 +46,17 @@ You can write this file yourself (it is only a few lines), or on Windows let the
 |-------|------|--------------|
 | `serverUrl` | string | The server the app connects to on launch (your self-hosted instance, or a Stirling Cloud URL). Include the protocol (`http://` or `https://`); a trailing slash is optional. |
 | `lockConnectionMode` | boolean | `true` stops users changing the server or connection mode in Settings. Only takes effect when `serverUrl` is also set. |
+| `loginAgreementEnabled` | boolean | `true` enables the login agreement/disclaimer dialog. It only turns the feature on - the text is supplied separately (see note below), and with no text nothing is shown. Can be set on its own (no `serverUrl` needed), so it also applies to local, no-login desktop installs. |
 | `updateMode` | string | How the built-in updater behaves: `prompt` (default - ask the user), `auto` (download and install silently on startup), or `disabled` (never check or show update UI). |
 
 A file with none of these fields is ignored.
 
+:::note The login agreement flag only enables it
+`loginAgreementEnabled` / `STIRLING_LOGIN_AGREEMENT` switches the feature on; it does not carry the disclaimer text. The dialog stays hidden until text is available - from the server the desktop connects to, or for a local bundled backend from a `customFiles/disclaimer/<locale>.md` file or the `LEGAL_LOGINAGREEMENT_FALLBACKTEXT` setting. With no text configured, nothing is shown. See [Login Agreement](../Configuration/System%20and%20Security.md).
+
+Passing the disclaimer text directly as an install parameter is planned for a future update.
+:::
+
 ---
 
 ## File locations
@@ -72,6 +79,7 @@ On Windows you do not have to write the JSON by hand. The MSI installer (and `wi
 |-----------|-------------|---------|
 | `STIRLING_SERVER_URL` | Server URL the app connects to | `http://192.168.1.53:8080` |
 | `STIRLING_LOCK_CONNECTION` | Lock the connection so users cannot change it (`1` = locked) | `1` |
+| `STIRLING_LOGIN_AGREEMENT` | Enable the login agreement/disclaimer dialog (`1` = enabled). The text is supplied separately; the flag alone shows nothing. | `1` |
 | `STIRLING_UPDATE_MODE` | Set and lock the update mode (`prompt`, `auto`, or `disabled`) | `disabled` |
 | `INSTALLDIR` | Custom install directory (MSI only) | `C:\CustomPath\Stirling-PDF` |
 | `ALLUSERS` | Install for all users (requires admin; `1`) | `1` |