You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Add postguard repo website docs content to centralized docs
The postguard repo contains a Docusaurus docs website in website/
that was not accounted for during the initial documentation
centralization. This updates the repos/postguard.md page to
incorporate the content from that website, including:
- Mention of the existing Docusaurus site and its GitHub Pages URL
- Cryptographic primitives table and pg-core feature flags
- Full development setup: prerequisites, building each crate,
WASM build, docker-compose, environment variables
- PKG server setup: key generation, running, Docker deployment
- CLI usage examples for encrypt and decrypt
- PKG Server API endpoint reference
- WASM bindings overview with cross-references to the SDK docs
Relates to #8
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Copy file name to clipboardExpand all lines: docs/repos/postguard.md
+169-3Lines changed: 169 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,6 +4,8 @@
4
4
5
5
The main PostGuard repository. It contains the core encryption library, the Private Key Generator (PKG) server, WebAssembly bindings for browsers, a command-line client, and FFI bindings for native language integration.
6
6
7
+
The repo also includes a [Docusaurus documentation site](https://encryption4all.github.io/postguard/) in the `website/` directory, covering architecture, API reference, and Yivi integration. That content has been consolidated into this centralized docs site.
8
+
7
9
## Workspace Structure
8
10
9
11
The repository is a Rust workspace with five crates:
@@ -16,6 +18,8 @@ The repository is a Rust workspace with five crates:
16
18
|`pg-cli`| Command-line tool for encrypting and decrypting files |
17
19
|`pg-ffi`| FFI bindings for calling Rust code from other languages (used by [postguard-dotnet](/repos/postguard-dotnet)) |
18
20
21
+
The `website/` directory contains a Docusaurus site deployed to GitHub Pages via the `docs.yml` workflow.
22
+
19
23
## How It Works
20
24
21
25
PostGuard uses Identity-Based Encryption (IBE). Instead of public keys, the sender only needs the master public key and the recipient's identity (e.g. email address). To decrypt, the recipient proves their identity to the PKG via [Yivi](https://yivi.app) and receives a decryption key.
@@ -32,16 +36,62 @@ A typical session:
32
36
7. The PKG issues a decryption key for that identity.
33
37
8. The recipient's client decrypts the message.
34
38
39
+
For the full protocol details, see the [architecture overview](/guide/architecture) and [core concepts](/guide/concepts) in the guide.
| Symmetric | AES-128-GCM (128-bit security to match BLS12-381) |
48
+
| Hashing | SHA3-512 for identity derivation |
49
+
50
+
### pg-core Feature Flags
51
+
52
+
pg-core supports two backends:
53
+
54
+
-`rust` (default): uses RustCrypto crates for native Rust targets
55
+
-`web`: uses the Web Crypto API for WASM in browsers
56
+
57
+
Streaming mode is enabled with the `stream` feature flag. When active, encryption and decryption process data in 256 KiB chunks instead of loading everything into memory.
This starts a Yivi session (displays a QR code) to obtain signing keys, then encrypts `myfile.txt` into `myfile.txt.enc`.
175
+
176
+
Decrypt a file:
177
+
178
+
```bash
179
+
cargo run --bin pg-cli dec myfile.txt.enc
180
+
```
181
+
182
+
The CLI shows the recipient policies in the header, prompts you to select your identity, and starts a Yivi session to obtain your decryption key.
183
+
184
+
## PKG Server API
185
+
186
+
The PKG server (`pg-pkg`) exposes an HTTP API. By default it listens on `http://localhost:8080`.
187
+
188
+
### Public Parameters
189
+
190
+
| Method | Endpoint | Description |
191
+
|---|---|---|
192
+
|`GET`|`/v2/parameters`| Fetch the Master Public Key (MPK). Supports ETag/Cache-Control caching. |
193
+
|`GET`|`/v2/sign/parameters`| Fetch the public verification key for signature checking. |
194
+
195
+
### Yivi Sessions
196
+
197
+
| Method | Endpoint | Description |
198
+
|---|---|---|
199
+
|`POST`|`/v2/irma/start`| Start a Yivi identity verification session. |
200
+
|`GET`|`/v2/irma/jwt/{token}`| Retrieve the JWT result of a completed Yivi session. |
201
+
202
+
### Key Issuance
203
+
204
+
| Method | Endpoint | Description |
205
+
|---|---|---|
206
+
|`GET`|`/v2/irma/key/{timestamp}`| Retrieve a User Secret Key (USK). Requires `Authorization: Bearer <jwt>`. |
207
+
|`POST`|`/v2/irma/sign/key`| Retrieve signing keys. Authenticate with a Yivi JWT or API key (`PG-API-<key>`). |
208
+
209
+
### Health
210
+
211
+
| Method | Endpoint | Description |
212
+
|---|---|---|
213
+
|`GET`|`/health`| Health check. |
214
+
|`GET`|`/metrics`| Prometheus metrics. |
215
+
216
+
For the full API details with request/response examples, see the [architecture page](/guide/architecture#api-endpoints).
217
+
218
+
## WASM Bindings (pg-wasm)
219
+
220
+
The `@e4a/pg-wasm` package provides WebAssembly bindings for PostGuard in browser environments. Install via npm:
221
+
222
+
```bash
223
+
npm install @e4a/pg-wasm
224
+
```
225
+
226
+
The package exports:
227
+
228
+
-`seal()` and `sealStream()` for encryption (in-memory and streaming)
229
+
-`Unsealer` and `StreamUnsealer` for decryption (in-memory and streaming)
230
+
231
+
Both streaming variants use the Web Streams API (`ReadableStream`/`WritableStream`). For usage examples and the full JavaScript/TypeScript API, see the [SDK reference](/sdk/overview).
232
+
67
233
## Releasing
68
234
69
235
This repository uses [Release-plz](https://release-plz.ieni.dev/) for automated versioning and releases. When changes are merged to `main`, Release-plz creates a release PR. Merging that PR triggers:
@@ -80,4 +246,4 @@ This repository uses [Release-plz](https://release-plz.ieni.dev/) for automated
80
246
|---|---|---|
81
247
|`build.yml`| Push/PR | Formatting checks, tests for all workspace members |
82
248
|`delivery.yml`| Push to main | Release-plz, Docker build, FFI compilation, npm publish |
83
-
|`docs.yml`| Push to main |Deploys API docs to GitHub Pages |
249
+
|`docs.yml`| Push to main |Builds the Docusaurus site in `website/` and deploys to [GitHub Pages](https://encryption4all.github.io/postguard/)|
0 commit comments