docs: add comprehensive README with project overview and architecture
Introduce a detailed README.md file documenting the PORTAL project's features, security model, system architecture, and usage guidelines to provide clear onboarding for contributors and users.
lemon-mint committed
Nov 5, 2025 at 09:40 UTC
921d5fb5c7d9b0af9374ef94e2bb118fb7e201a9
1 file changed
+153
README.md
new
+153
@@ -0,0 +1,153 @@
1
+# PORTAL — Public Open Relay To Access Localhost
2
+
3
+<p align="center">
4
+ <img src="/portal.jpg" alt="Portal logo" width="540" />
5
+</p>
6
+
7
+Portal is a secure, encrypted relay service that enables end-to-end encrypted communication between clients through a central relay server. It provides mutual authentication, forward secrecy, and secure connection management with cryptographic identity verification.
8
+
9
+## Table of Contents
10
+
11
+- [Overview](#overview)
12
+- [Features](#features)
13
+- [Architecture](#architecture)
14
+- [Security](#security)
15
+- [Installation](#installation)
16
+- [Usage](#usage)
17
+- [API Reference](#api-reference)
18
+- [Protocol Specification](#protocol-specification)
19
+- [Development](#development)
20
+- [Contributing](#contributing)
21
+- [License](#license)
22
+
23
+## Overview
24
+
25
+Portal implements a secure relay protocol that allows clients to register leases and establish encrypted connections through a central server. The system uses modern cryptographic primitives to ensure:
26
+
27
+- **End-to-end encryption**: All communication is encrypted using ChaCha20-Poly1305 AEAD
28
+- **Mutual authentication**: Ed25519 signatures verify client identities
29
+- **Forward secrecy**: Ephemeral X25519 key exchange per connection
30
+- **Secure relay**: The relay server cannot decrypt client communications
31
+
32
+## Features
33
+
34
+- 🔐 **End-to-End Encryption**: Client-to-client communication is fully encrypted
35
+- 🔑 **Cryptographic Identity**: Ed25519-based identity system with verifiable signatures
36
+- 🔄 **Connection Relay**: Secure connection forwarding through central server
37
+- ⏰ **Lease Management**: Time-based lease system with automatic cleanup
38
+- 🌐 **Protocol Support**: Application-Layer Protocol Negotiation (ALPN)
39
+- 🚀 **High Performance**: Multiplexed connections using yamux
40
+- 🐳 **Docker Support**: Containerized deployment ready
41
+- 🌍 **Browser E2EE Proxy**: WASM-based Service Worker for automatic browser encryption
42
+- 📱 **Multi-Platform**: Go SDK for servers, WASM SDK for browsers
43
+
44
+## Architecture
45
+
46
+### System Architecture
47
+
48
+```mermaid
49
+graph TB
50
+ subgraph "Client A"
51
+ CA[Client A]
52
+ CA --> CA_ID[Identity: Ed25519]
53
+ CA --> CA_LEASE[Lease Manager]
54
+ end
55
+
56
+ subgraph "Client B"
57
+ CB[Client B]
58
+ CB --> CB_ID[Identity: Ed25519]
59
+ CB --> CB_LEASE[Lease Manager]
60
+ end
61
+
62
+ subgraph "Relay Server"
63
+ RS[Relay Server]
64
+ RS --> RS_ID[Server Identity]
65
+ RS --> LM[Lease Manager]
66
+ RS --> CM[Connection Manager]
67
+ RS --> FH[Forwarding Handler]
68
+ end
69
+
70
+ CA -.->|1. Register Lease| RS
71
+ CB -.->|2. Register Lease| RS
72
+ CB -.->|3. Request Connection| RS
73
+ RS -.->|4. Forward Request| CA
74
+ CA -.->|5. Accept Connection| RS
75
+ RS -.->|6. Establish E2EE| CB
76
+
77
+ CA <-->|7. Encrypted Data| CB
78
+```
79
+
80
+### Component Architecture
81
+
82
+```mermaid
83
+graph LR
84
+ subgraph "Client Components"
85
+ C[RelayClient]
86
+ C --> H[Handshaker]
87
+ C --> LM[LeaseManager]
88
+ C --> SC[SecureConnection]
89
+ end
90
+
91
+ subgraph "Server Components"
92
+ S[RelayServer]
93
+ S --> LH[LeaseHandler]
94
+ S --> CH[ConnectionHandler]
95
+ S --> FH[ForwardingHandler]
96
+ S --> LM2[LeaseManager]
97
+ end
98
+
99
+ subgraph "Crypto Operations"
100
+ CO[CryptoOps]
101
+ CO --> CRED[Credential]
102
+ CO --> SIG[Signature]
103
+ CO --> E2EE[End-to-End Encryption]
104
+ end
105
+
106
+ C <-->|Protocol Messages| S
107
+ H --> CO
108
+ SC --> CO
109
+ LH --> LM2
110
+ CH --> FH
111
+```
112
+
113
+### Connection Flow
114
+
115
+```mermaid
116
+sequenceDiagram
117
+ participant C1 as Client 1
118
+ participant RS as Relay Server
119
+ participant C2 as Client 2
120
+
121
+ Note over C1,C2: Lease Registration Phase
122
+ C1->>RS: Register Lease (Identity, ALPN)
123
+ RS->>C1: Lease Confirmation
124
+
125
+ C2->>RS: Register Lease (Identity, ALPN)
126
+ RS->>C2: Lease Confirmation
127
+
128
+ Note over C1,C2: Connection Establishment Phase
129
+ C2->>RS: Request Connection (to Client 1)
130
+ RS->>C1: Forward Connection Request
131
+ C1->>RS: Accept Connection
132
+ RS->>C2: Connection Accepted
133
+
134
+ Note over C1,C2: Secure Handshake Phase
135
+ C2->>C1: X25519 Handshake (via relay)
136
+ C1->>C2: X25519 Response (via relay)
137
+
138
+ Note over C1,C2: End-to-End Encrypted Communication
139
+ C2->>C1: Encrypted Data (ChaCha20-Poly1305)
140
+ C1->>C2: Encrypted Data (ChaCha20-Poly1305)
141
+```
142
+
143
+## Contributing
144
+
145
+1. Fork the repository
146
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
147
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
148
+4. Push to the branch (`git push origin feature/amazing-feature`)
149
+5. Open a Pull Request
150
+
151
+## License
152
+
153
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.