Merge remote-tracking branch 'origin/add-missing-readme-info' into centralize-docs

dobby-coder[bot] · dobby-coder[bot] · commit e559eef7b3e4 · 2026-04-15T07:38:47.000Z
# Conflicts:
#	docs/repos/postguard.md
diff --git a/docs/repos/cryptify.md b/docs/repos/cryptify.md
@@ -13,6 +13,36 @@ Cryptify has two parts:
 - **Backend** (Rust, Rocket framework): Handles file storage, chunked uploads, email notifications, and serves the API.
 - **Frontend** (TypeScript): Web UI for uploading and downloading encrypted files.
 
+## Configuration
+
+The backend reads its configuration from a TOML file. Example configuration files are in `conf/`. Set the `ROCKET_CONFIG` environment variable to point to the configuration file.
+
+Configuration parameters:
+
+| Parameter | Description | Example |
+|---|---|---|
+| `server_url` | Public URL of the frontend (via nginx) | `http://localhost:8080/` |
+| `address` | Bind address | `0.0.0.0` |
+| `port` | Backend listen port | `8000` |
+| `data_dir` | Directory for storing uploaded files | `/tmp/data` |
+| `email_from` | Sender address for notification emails | `noreply@postguard.local` |
+| `smtp_url` | SMTP server hostname | `mailcrab` |
+| `smtp_port` | SMTP server port | `1025` |
+| `smtp_tls` | Enable TLS for SMTP | `false` |
+| `smtp_username` | Optional SMTP username | `user` |
+| `smtp_password` | Optional SMTP password | `pw` |
+| `allowed_origins` | Regex pattern for CORS allowed origins | `^https?://(localhost\|127\\.0\\.0\\.1)(:[0-9]+)?$` |
+| `pkg_url` | URL of the PostGuard PKG server | `http://postguard-pkg:8087` |
+
+## API
+
+The backend exposes a file upload/download API. An OpenAPI 3.0 specification is available in `api-description.yaml` in the repository root. The main endpoints:
+
+- `POST /fileupload/init` — Initialize a multipart file upload (takes sender email, recipient email, file size, mail content, and language).
+- `PUT /fileupload/{uuid}` — Upload a file chunk (use `Content-Range` header for chunked uploads).
+- `POST /fileupload/finalize/{uuid}` — Finalize the upload and send the notification email.
+- `GET /filedownload/{uuid}` — Download a file.
+
 ## Development
 
 ### Docker (recommended)
diff --git a/docs/repos/pdf-signature.md b/docs/repos/pdf-signature.md
@@ -2,30 +2,96 @@
 
 [GitHub](https://github.com/encryption4all/pdf-signature) · Rust + TypeScript · PDF Signing
 
-PDF signing and signature verification utility. Used within the PostGuard ecosystem for signing PDF documents with identity-based signatures.
+PDF signing and signature verification utility forked from [Cryptify](/repos/cryptify). It encrypts and decrypts files based on IRMA/Yivi attributes, allowing only people with the right attributes to view the contents.
 
 ## Architecture
 
 The repository is structured similarly to [Cryptify](/repos/cryptify), with a Rust backend and TypeScript frontend:
 
-- **Backend** (`cryptify-back-end/`): Rust service handling PDF operations
-- **Frontend** (`cryptify-front-end/`): TypeScript web interface
+- **Backend** (`cryptify-back-end/`): Rust (Rocket) service handling file storage, chunked uploads, email notifications, and the HTTP API.
+- **Frontend** (`cryptify-front-end/`): TypeScript/React web interface with optional Electron packaging.
+
+## Configuration
+
+The backend reads its configuration from a TOML file. Example configuration files are in `conf/`. Set the `ROCKET_CONFIG` environment variable to point to the configuration file.
+
+Configuration parameters:
+
+| Parameter | Description | Example |
+|---|---|---|
+| `server_url` | Public URL of the frontend | `http://localhost:8080/` |
+| `address` | Bind address | `0.0.0.0` |
+| `data_dir` | Directory for storing uploaded files | `/tmp/data` |
+| `email_from` | Sender address for notification emails | `noreply@postguard.local` |
+| `smtp_url` | SMTP server hostname | `mailcrab` |
+| `smtp_port` | SMTP server port | `1025` |
+| `smtp_credentials` | Optional SMTP credentials | `["user", "pw"]` |
+| `allowed_origins` | Regex pattern for CORS allowed origins | `^http://localhost:8080$` |
+| `pkg_url` | URL of the PostGuard PKG server | `https://postguard-main.cs.ru.nl/pkg` |
 
 ## Development
 
 ### Docker (recommended)
 
 ```bash
-# Development setup
+# Development setup (with hot reload via cargo watch)
 docker-compose -f docker-compose.dev.yml up
 
 # Production-like setup
 docker-compose up
 ```
 
+The development Docker Compose setup includes a Mailcrab instance for testing emails (web UI at `http://localhost:1080`, SMTP at port 1025).
+
 ### Manual Setup
 
-See the Cryptify development instructions for the general pattern. The backend requires Rust and the frontend requires Node.js.
+#### Frontend
+
+Requires Node.js 14 and Rust:
+
+```bash
+cd cryptify-front-end
+npm install
+npm run start    # development server
+npm run build    # production build
+```
+
+When developing locally, change the `baseurl` constant in `FileProvider.ts` to `http://localhost:3000` so the frontend uses the local backend.
+
+#### Backend
+
+Requires Rust:
+
+```bash
+# Development (with auto-reload)
+env ROCKET_ENV=development ROCKET_CONFIG=conf/config.dev.toml cargo watch -x run
+
+# Production build
+env ROCKET_ENV=production cargo build --release
+
+# Run the production binary
+env ROCKET_CONFIG=conf/config.toml ./target/release/cryptify-backend
+```
+
+The backend needs the `ROCKET_CONFIG` environment variable pointing to a configuration file so it can send emails and store files.
+
+### Electron Packaging
+
+The frontend can also be packaged as a desktop app:
+
+```bash
+cd cryptify-front-end
+npm run dist-electron
+```
+
+## API
+
+The backend exposes a file upload/download API. An OpenAPI 3.0 specification is available in `api-description.yaml` in the repository root. The main endpoints:
+
+- `POST /fileupload/init` — Initialize a multipart file upload (takes sender email, recipient email, file size, mail content, and language).
+- `PUT /fileupload/{uuid}` — Upload a file chunk (use `Content-Range` header for chunked uploads).
+- `POST /fileupload/finalize/{uuid}` — Finalize the upload and send the notification email.
+- `GET /filedownload/{uuid}` — Download a file.
 
 ## Releasing
 
diff --git a/docs/repos/postguard-examples.md b/docs/repos/postguard-examples.md
@@ -18,25 +18,38 @@ npm run dev
 
 ### .NET Console App (`pg-dotnet/`)
 
-A .NET console application demonstrating the [postguard-dotnet](/repos/postguard-dotnet) SDK for server-side encryption and Cryptify upload.
+A .NET console application demonstrating the [postguard-dotnet](/repos/postguard-dotnet) SDK for the "Informatierijk notificeren" use case. It shows two patterns:
+
+1. **Encrypt and Upload** — Encrypts sample files for a citizen (exact email) and an organisation (email domain), uploads to Cryptify, and returns a UUID for custom distribution.
+2. **Encrypt and Deliver** — Same as above, but also sends an email notification to the recipient via Cryptify.
 
 **Prerequisites:**
 
 - .NET 8.0+ SDK
-- Rust toolchain (for building the native crypto library)
+- Rust toolchain via [rustup](https://rustup.rs/) (for building the native crypto library)
 - A PostGuard API key
 
 **Setup:**
 
+Clone postguard-dotnet alongside this repo:
+
+```
+Repos/
+├── postguard-examples/   (this repo)
+│   └── pg-dotnet/
+└── postguard-dotnet/     (SDK)
+```
+
+Build the native library (one-time):
+
 ```bash
-# Clone postguard-dotnet alongside this repo
-# Build the native library (one-time)
 cd ../postguard/pg-ffi && ./build.sh
+```
 
-# Set your API key
-export PG_API_KEY="PG-API-your-key-here"
+Set your API key and run:
 
-# Run
+```bash
+export PG_API_KEY="PG-API-your-key-here"
 cd pg-dotnet
 dotnet run
 ```
@@ -49,6 +62,35 @@ export PG_CRYPTIFY_URL="https://fileshare.postguard.eu"
 dotnet run
 ```
 
+**Usage example:**
+
+```csharp
+var pg = new PostGuard(new PostGuardConfig
+{
+    PkgUrl = "https://pkg.staging.postguard.eu",
+    CryptifyUrl = "https://fileshare.staging.postguard.eu"
+});
+
+var sealed = pg.Encrypt(new EncryptInput
+{
+    Files = [new PgFile("report.txt", stream)],
+    Recipients = [
+        pg.Recipient.Email("citizen@example.com"),
+        pg.Recipient.EmailDomain("info@org.nl")
+    ],
+    Sign = pg.Sign.ApiKey(apiKey)
+});
+
+// Upload only — returns UUID for custom delivery
+var result = await sealed.UploadAsync();
+
+// Or upload + send email notification
+var result = await sealed.UploadAsync(new UploadOptions
+{
+    Notify = new NotifyOptions { Message = "Your documents", Language = "EN" }
+});
+```
+
 ## Code Snippets
 
 The examples in this repo are used as the source for code snippets in the [PostGuard documentation](https://docs.postguard.eu). When updating examples, keep in mind that documentation snippets reference specific commit hashes.
diff --git a/docs/repos/postguard-fallback.md b/docs/repos/postguard-fallback.md
@@ -2,7 +2,7 @@
 
 [GitHub](https://github.com/encryption4all/postguard-fallback) · Rust · Web Decryption Service
 
-Also known as **TGuard**. A self-contained web service for sending and decrypting PostGuard-encrypted messages, designed as a fallback for users who don't have a PostGuard client installed. Users can decrypt messages directly in their browser after proving their identity via [Yivi](https://yivi.app) (formerly IRMA).
+Also known as **TGuard**. A self-contained web service for sending and decrypting [irmaseal](https://github.com/encryption4all/irmaseal)-encrypted messages. Users encrypt messages client-side, and recipients can decrypt them in their browser after proving they own the required attributes (e.g., email address, name, or identifying number) via [Yivi](https://yivi.app) (formerly [IRMA](https://irma.app/docs/what-is-irma/)).
 
 ## Architecture
 
@@ -13,23 +13,26 @@ Both the backend and frontend are written in Rust:
 
 Supporting services: NGINX (reverse proxy), PostgreSQL (database), Mailhog (email testing).
 
+The frontend is compiled and bundled using [Trunk](https://trunkrs.dev/) and uses the [Yew](https://yew.rs/) framework. Additional Rust library dependencies can be found in `Cargo.toml` in both the frontend and backend directories.
+
+For a technical overview of IRMA Seal, see the [design document](https://github.com/Wassasin/irmaseal/blob/master/docs/design.md).
+
 ## Development
 
 ### Docker (recommended)
 
 ```bash
-# Development setup
-docker-compose -f docker-compose.dev.yml up
-
-# Production-like setup
-docker-compose up
-
 # Initialize the database
 ./setup.sh
+
+# Development setup
+docker-compose up
 ```
 
 The application is available at `http://tguard.localhost`.
 
+The Docker setup includes the following software versions: Rust 1.57 (rust:bullseye), NGINX 1.21, PostgreSQL 12, and Mailhog 1.0.
+
 ### Manual Setup
 
 Requires:
diff --git a/docs/repos/postguard-js.md b/docs/repos/postguard-js.md
@@ -84,7 +84,7 @@ const sealed = pg.encrypt({
 });
 
 const encrypted = await sealed.toBytes();
-// encrypted is a Uint8Array
+// encrypted is a Uint8Array — attach it, send it, store it however you want
 ```
 
 ## Decryption
@@ -134,16 +134,17 @@ pg.sign.apiKey('your-api-key')
 pg.sign.yivi({
   element: '#yivi-popup',
   senderEmail: 'alice@example.com',
-  attributes: [
+  attributes: [                    // optional: request extra attributes
     { t: 'pbdf.gemeente.personalData.fullname', optional: true },
     { t: 'pbdf.sidn-pbdf.mobilenumber.mobilenumber', optional: true },
   ],
-  includeSender: true,
+  includeSender: true,             // optional: also encrypt for the sender
 })
 
 // Custom session callback (email addons, mobile apps, etc.)
 pg.sign.session(
   async ({ con, sort }) => {
+    // Show your own Yivi UI, return the JWT
     return await myCustomYiviFlow(con, sort);
   },
   { senderEmail: 'alice@example.com' }
@@ -189,16 +190,27 @@ const sealed = pg.encrypt({
 });
 
 const envelope = await pg.email.createEnvelope({ sealed, from: 'alice@example.com' });
-// envelope.subject, envelope.htmlBody, envelope.plainTextBody, envelope.attachment
+// envelope.subject → "PostGuard Encrypted Email"
+// envelope.htmlBody → Placeholder HTML with PostGuard branding
+// envelope.plainTextBody → Plain text fallback
+// envelope.attachment → File("postguard.encrypted")
 
-// On the receiving side: extract and decrypt
+// --- On the receiving side ---
 const ciphertext = extractCiphertext({
   htmlBody: emailBodyHtml,
   attachments: [{ name: 'postguard.encrypted', data: attachmentBuffer }],
 });
 
 const opened = pg.open({ data: ciphertext });
 const result = await opened.decrypt({ element: '#yivi-popup', recipient: 'bob@example.com' });
+// result.plaintext → decrypted MIME content
+// result.sender → verified sender identity
+```
+
+Standalone email helpers (`buildMime`, `extractCiphertext`, `injectMimeHeaders`) can be imported directly without creating a PostGuard instance:
+
+```ts
+import { buildMime, extractCiphertext, injectMimeHeaders } from '@e4a/pg-js';
 ```
 
 ## Error Handling
diff --git a/docs/repos/postguard-tb-addon.md b/docs/repos/postguard-tb-addon.md
@@ -27,8 +27,8 @@ cp .env.example .env   # adjust if needed
 ### Build and Run
 
 ```bash
-npm run build          # production build → dist/
-npm run build:dev      # development build (no minification, keeps console.log)
+npm run build          # production build, output in dist/
+npm run build:dev      # development build (no minification, preserves console.log)
 npm run watch          # dev build with file watching
 ```
 
diff --git a/docs/repos/postguard-website.md b/docs/repos/postguard-website.md
@@ -8,7 +8,7 @@ The PostGuard web frontend for encrypting and sending files. Users pick files, c
 
 ### Quick Start with Docker Compose (recommended)
 
-Docker Compose sets up everything: the PostGuard website, Cryptify backend, IRMA server, PKG server, and a mail testing UI.
+Docker Compose sets up everything: the PostGuard website, Cryptify file share server, IRMA server, PKG server, and a Mailcrab mail testing UI.
 
 ```bash
 # Initialize submodules (Cryptify, etc.)
@@ -30,6 +30,25 @@ docker-compose -f docker-compose.prod.yml up
 # Access at http://localhost
 ```
 
+### Stopping Services
+
+```bash
+# Development
+docker-compose down
+
+# Production
+docker-compose -f docker-compose.prod.yml down
+```
+
+### Building
+
+Building is done automatically through GitHub Actions. You can also build manually:
+
+```bash
+docker-compose build      # Build via Docker
+npm run build             # Build only the PostGuard website
+```
+
 ### Manual (without Docker)
 
 ```bash
@@ -50,10 +69,10 @@ npm run test      # Playwright tests
 
 ### Mobile Debugging
 
-To test on a physical Android device over USB (Yivi must be in [developer mode](https://docs.yivi.app/yivi-app/#developer-mode)):
+To test on a physical Android device, connect the phone with USB debugging enabled and make sure Yivi is in [developer mode](https://docs.yivi.app/yivi-app/#developer-mode):
 
 ```bash
-adb reverse tcp:8088 tcp:8088   # Yivi / IRMA server
+adb reverse tcp:8088 tcp:8088   # Yivi / IRMA server (for scanning QR codes)
 adb reverse tcp:8080 tcp:8080   # PostGuard website
 ```
 
diff --git a/docs/repos/postguard.md b/docs/repos/postguard.md
