docs: update README
Kim committed
Nov 7, 2025 at 13:53 UTC
c6f13b89e0ed0ee72e6dca55653a3c99614b8b54
2 files changed
+115
-110
README.md
+16
-110
@@ -4,30 +4,22 @@
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.
7
+Portal is an open hosting network that transforms your local project into a public web endpoint.
8
+[See more](https://gosuda.org/portal/)
9
10
## Table of Contents
11
12
- [Overview](#overview)
13
- [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)
14
+- [Quick Start](#quick-start)
15
- [Contributing](#contributing)
16
- [License](#license)
17
18
## Overview
19
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
20
+Portal connects local applications to web users through a secure relay layer.
21
+Each application is assigned a subdomain within Portal, and all traffic between endpoints is end-to-end encrypted.
22
+This enables developers to publish local services globally without managing servers or cloud infrastructure.
23
24
## Features
25
@@ -41,107 +33,21 @@ Portal implements a secure relay protocol that allows clients to register leases
33
- 🌍 **Browser E2EE Proxy**: WASM-based Service Worker for automatic browser encryption
34
- 📱 **Multi-Platform**: Go SDK for servers, WASM SDK for browsers
35
36
+## Quick Start
37
+
38
+WIP
39
+
40
## Architecture
41
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
-```
42
+For a detailed overview of system components and data flow, see the [architecture documentation](docs/architecture.md).
43
44
## Contributing
45
46
+We welcome contributions from the community!
47
+Before getting started, please check the [development guide](docs/development.md)
48
+ for setup instructions and best practices.
49
+
50
+### Steps to Contribute
51
1. Fork the repository
52
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
53
3. Commit your changes (`git commit -m 'Add amazing feature'`)
docs/architecture.md
new
+99
@@ -0,0 +1,99 @@
1
+
2
+# Architecture
3
+
4
+## System Architecture
5
+
6
+```mermaid
7
+graph TB
8
+ subgraph "Client A"
9
+ CA[Client A]
10
+ CA --> CA_ID[Identity: Ed25519]
11
+ CA --> CA_LEASE[Lease Manager]
12
+ end
13
+
14
+ subgraph "Client B"
15
+ CB[Client B]
16
+ CB --> CB_ID[Identity: Ed25519]
17
+ CB --> CB_LEASE[Lease Manager]
18
+ end
19
+
20
+ subgraph "Relay Server"
21
+ RS[Relay Server]
22
+ RS --> RS_ID[Server Identity]
23
+ RS --> LM[Lease Manager]
24
+ RS --> CM[Connection Manager]
25
+ RS --> FH[Forwarding Handler]
26
+ end
27
+
28
+ CA -.->|1. Register Lease| RS
29
+ CB -.->|2. Register Lease| RS
30
+ CB -.->|3. Request Connection| RS
31
+ RS -.->|4. Forward Request| CA
32
+ CA -.->|5. Accept Connection| RS
33
+ RS -.->|6. Establish E2EE| CB
34
+
35
+ CA <-->|7. Encrypted Data| CB
36
+```
37
+
38
+## Component Architecture
39
+
40
+```mermaid
41
+graph LR
42
+ subgraph "Client Components"
43
+ C[RelayClient]
44
+ C --> H[Handshaker]
45
+ C --> LM[LeaseManager]
46
+ C --> SC[SecureConnection]
47
+ end
48
+
49
+ subgraph "Server Components"
50
+ S[RelayServer]
51
+ S --> LH[LeaseHandler]
52
+ S --> CH[ConnectionHandler]
53
+ S --> FH[ForwardingHandler]
54
+ S --> LM2[LeaseManager]
55
+ end
56
+
57
+ subgraph "Crypto Operations"
58
+ CO[CryptoOps]
59
+ CO --> CRED[Credential]
60
+ CO --> SIG[Signature]
61
+ CO --> E2EE[End-to-End Encryption]
62
+ end
63
+
64
+ C <-->|Protocol Messages| S
65
+ H --> CO
66
+ SC --> CO
67
+ LH --> LM2
68
+ CH --> FH
69
+```
70
+
71
+## Connection Flow
72
+
73
+```mermaid
74
+sequenceDiagram
75
+ participant C1 as Client 1
76
+ participant RS as Relay Server
77
+ participant C2 as Client 2
78
+
79
+ Note over C1,C2: Lease Registration Phase
80
+ C1->>RS: Register Lease (Identity, ALPN)
81
+ RS->>C1: Lease Confirmation
82
+
83
+ C2->>RS: Register Lease (Identity, ALPN)
84
+ RS->>C2: Lease Confirmation
85
+
86
+ Note over C1,C2: Connection Establishment Phase
87
+ C2->>RS: Request Connection (to Client 1)
88
+ RS->>C1: Forward Connection Request
89
+ C1->>RS: Accept Connection
90
+ RS->>C2: Connection Accepted
91
+
92
+ Note over C1,C2: Secure Handshake Phase
93
+ C2->>C1: X25519 Handshake (via relay)
94
+ C1->>C2: X25519 Response (via relay)
95
+
96
+ Note over C1,C2: End-to-End Encrypted Communication
97
+ C2->>C1: Encrypted Data (ChaCha20-Poly1305)
98
+ C1->>C2: Encrypted Data (ChaCha20-Poly1305)
99
+```