den-terminal 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- den_terminal-0.1.0/LICENSE +21 -0
- den_terminal-0.1.0/MANIFEST.in +7 -0
- den_terminal-0.1.0/PKG-INFO +294 -0
- den_terminal-0.1.0/README.md +260 -0
- den_terminal-0.1.0/SECURITY.md +106 -0
- den_terminal-0.1.0/den/__init__.py +4 -0
- den_terminal-0.1.0/den/__main__.py +4 -0
- den_terminal-0.1.0/den/cli.py +238 -0
- den_terminal-0.1.0/den/client.py +271 -0
- den_terminal-0.1.0/den/crypto.py +329 -0
- den_terminal-0.1.0/den/demo.py +61 -0
- den_terminal-0.1.0/den/relay.py +472 -0
- den_terminal-0.1.0/den/transport.py +197 -0
- den_terminal-0.1.0/den_terminal.egg-info/PKG-INFO +294 -0
- den_terminal-0.1.0/den_terminal.egg-info/SOURCES.txt +29 -0
- den_terminal-0.1.0/den_terminal.egg-info/dependency_links.txt +1 -0
- den_terminal-0.1.0/den_terminal.egg-info/entry_points.txt +3 -0
- den_terminal-0.1.0/den_terminal.egg-info/requires.txt +11 -0
- den_terminal-0.1.0/den_terminal.egg-info/top_level.txt +1 -0
- den_terminal-0.1.0/docs/PROTOCOL.md +100 -0
- den_terminal-0.1.0/docs/RELEASING.md +92 -0
- den_terminal-0.1.0/docs/VALIDATION.md +62 -0
- den_terminal-0.1.0/examples/torrc.client.example +5 -0
- den_terminal-0.1.0/examples/torrc.relay.example +12 -0
- den_terminal-0.1.0/pyproject.toml +48 -0
- den_terminal-0.1.0/setup.cfg +4 -0
- den_terminal-0.1.0/tests/test_cli.py +57 -0
- den_terminal-0.1.0/tests/test_integration.py +368 -0
- den_terminal-0.1.0/tests/test_relay.py +456 -0
- den_terminal-0.1.0/tests/test_security.py +305 -0
- den_terminal-0.1.0/tests/test_transport.py +257 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Dol0resH8ze
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,294 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: den-terminal
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Experimental private, live terminal rooms over Tor
|
|
5
|
+
Author: Dol0resH8ze
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/Dol0resH8ze/hush
|
|
8
|
+
Project-URL: Repository, https://github.com/Dol0resH8ze/hush
|
|
9
|
+
Project-URL: Issues, https://github.com/Dol0resH8ze/hush/issues
|
|
10
|
+
Project-URL: Security, https://github.com/Dol0resH8ze/hush/blob/main/SECURITY.md
|
|
11
|
+
Keywords: terminal,chat,tor,messaging
|
|
12
|
+
Classifier: Development Status :: 3 - Alpha
|
|
13
|
+
Classifier: Environment :: Console
|
|
14
|
+
Classifier: Operating System :: Microsoft :: Windows
|
|
15
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
20
|
+
Classifier: Topic :: Communications :: Chat
|
|
21
|
+
Requires-Python: >=3.12
|
|
22
|
+
Description-Content-Type: text/markdown
|
|
23
|
+
License-File: LICENSE
|
|
24
|
+
Requires-Dist: PyNaCl==1.6.2
|
|
25
|
+
Requires-Dist: python-socks[asyncio]==2.8.1
|
|
26
|
+
Requires-Dist: prompt-toolkit==3.0.52
|
|
27
|
+
Provides-Extra: dev
|
|
28
|
+
Requires-Dist: pytest==8.4.2; extra == "dev"
|
|
29
|
+
Requires-Dist: pytest-asyncio==1.2.0; extra == "dev"
|
|
30
|
+
Provides-Extra: release
|
|
31
|
+
Requires-Dist: build>=1.2; extra == "release"
|
|
32
|
+
Requires-Dist: twine>=6; extra == "release"
|
|
33
|
+
Dynamic: license-file
|
|
34
|
+
|
|
35
|
+
# Den
|
|
36
|
+
|
|
37
|
+
Previously named Hush. The `hush` command is
|
|
38
|
+
retained as an alias. Existing Tor configuration directories (such as `HushTor`)
|
|
39
|
+
and onion addresses do not need to change. New invites start with `den1.`;
|
|
40
|
+
Den also accepts legacy `hush1.` invites.
|
|
41
|
+
|
|
42
|
+
Private, live text rooms in a terminal. Pick a username, create a room, share a
|
|
43
|
+
secret invite, and approve the devices that can participate. No account, email,
|
|
44
|
+
phone number, or password is required.
|
|
45
|
+
|
|
46
|
+
**Status: working experimental prototype, not an independently audited secure
|
|
47
|
+
messenger.** Normal connections require Tor. A separate, explicitly named local
|
|
48
|
+
test mode makes it possible to try the app on one computer without Tor.
|
|
49
|
+
|
|
50
|
+
## Installation
|
|
51
|
+
|
|
52
|
+
Requires Python **3.12 or newer**. Tor is a separate prerequisite for networking
|
|
53
|
+
between devices; it is not bundled or installed by pip. The package name is
|
|
54
|
+
`den-terminal`, and its command is `den`.
|
|
55
|
+
|
|
56
|
+
Once the release is published to PyPI, install it into a virtual environment:
|
|
57
|
+
|
|
58
|
+
Windows PowerShell:
|
|
59
|
+
|
|
60
|
+
```powershell
|
|
61
|
+
py -3 -m venv .venv
|
|
62
|
+
.\.venv\Scripts\python.exe -m pip install den-terminal
|
|
63
|
+
.\.venv\Scripts\den.exe --help
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Linux:
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
python3 -m venv .venv
|
|
70
|
+
.venv/bin/python -m pip install den-terminal
|
|
71
|
+
.venv/bin/den --help
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Activate the environment if you want to use `den` without the executable's full
|
|
75
|
+
path. `python -m den` also works using the environment's Python. For development
|
|
76
|
+
or before the first publication, use the source installation instructions below.
|
|
77
|
+
|
|
78
|
+
## What this version does
|
|
79
|
+
|
|
80
|
+
- Supports up to **16 devices per room**, including the owner.
|
|
81
|
+
- Generates fresh signing and encryption keys for each room session. Your
|
|
82
|
+
username is a display name, not a globally reserved identity.
|
|
83
|
+
- Creates a long random invite containing the room address, secret, and pinned
|
|
84
|
+
owner keys. The room ID alone is not sufficient for approval.
|
|
85
|
+
- Prompts privately for the invite when joining, keeping it out of command-line
|
|
86
|
+
arguments and shell command history.
|
|
87
|
+
- Requires the room owner to approve each joining device. Names are unique
|
|
88
|
+
within a room, ignoring letter case.
|
|
89
|
+
- Encrypts usernames and message content on the clients. The relay forwards
|
|
90
|
+
encrypted data and cannot read these fields from protocol traffic.
|
|
91
|
+
- Authenticates message authors and the owner's membership updates using
|
|
92
|
+
signatures. Device fingerprints distinguish sessions.
|
|
93
|
+
- Lets the owner lock/unlock rooms, reject requests, and remove participants.
|
|
94
|
+
- Stops releasing new messages for removed participants. The owner validates
|
|
95
|
+
each message against current membership before its recipient ciphertext is
|
|
96
|
+
released, including when a sender has an outdated roster.
|
|
97
|
+
- Uses Tor SOCKS5 with remote hostname resolution. Normal mode accepts only
|
|
98
|
+
valid v3 onion addresses and has **no direct-network fallback**.
|
|
99
|
+
- Keeps rooms and identities in memory. Den writes no chat history, user
|
|
100
|
+
database, message logs, or invite files.
|
|
101
|
+
- Closes the entire room when its owner disconnects. There is no reconnection,
|
|
102
|
+
offline inbox, history recovery, file transfer, audio, or video in version 0.1.
|
|
103
|
+
|
|
104
|
+
## Try a local room
|
|
105
|
+
|
|
106
|
+
After installation, open Windows Terminal / PowerShell in the directory where
|
|
107
|
+
you created the virtual environment and run:
|
|
108
|
+
|
|
109
|
+
```powershell
|
|
110
|
+
.\.venv\Scripts\den.exe demo
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
The demo starts a temporary loopback relay and three clients using real
|
|
114
|
+
encryption. It exercises admission, chat, locking, removal, and room closure,
|
|
115
|
+
then stops all of them. **It does not use Tor or demonstrate network anonymity.**
|
|
116
|
+
|
|
117
|
+
For an interactive local test, keep each command running in a separate terminal
|
|
118
|
+
tab, with that same directory as its working directory. On Linux, replace
|
|
119
|
+
`.\.venv\Scripts\den.exe` with `.venv/bin/den`:
|
|
120
|
+
|
|
121
|
+
```powershell
|
|
122
|
+
# Tab 1: relay
|
|
123
|
+
.\.venv\Scripts\den.exe relay
|
|
124
|
+
|
|
125
|
+
# Tab 2: room owner
|
|
126
|
+
.\.venv\Scripts\den.exe create --server 127.0.0.1 --local-test --name Alice
|
|
127
|
+
|
|
128
|
+
# Tab 3: another participant; paste the invite at the hidden prompt
|
|
129
|
+
.\.venv\Scripts\den.exe join --local-test --name Bob
|
|
130
|
+
|
|
131
|
+
# Tab 4: third participant
|
|
132
|
+
.\.venv\Scripts\den.exe join --local-test --name Cara
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
In Alice's tab, type `/approve Bob` and `/approve Cara` after their requests
|
|
136
|
+
appear. All three can now type messages. Use `/quit` to leave; quitting the
|
|
137
|
+
owner's session ends the room. Local test invites only work on the same
|
|
138
|
+
computer and only with `--local-test`.
|
|
139
|
+
|
|
140
|
+
## Install from source
|
|
141
|
+
|
|
142
|
+
Clone the repository, then install from the checkout. Copy source rather than
|
|
143
|
+
an existing `.venv` when transferring the project between machines. Tor private
|
|
144
|
+
keys are not part of this project and should not be copied with it.
|
|
145
|
+
|
|
146
|
+
Windows PowerShell:
|
|
147
|
+
|
|
148
|
+
```powershell
|
|
149
|
+
git clone https://github.com/Dol0resH8ze/hush.git
|
|
150
|
+
cd hush
|
|
151
|
+
py -3 -m venv .venv
|
|
152
|
+
.\.venv\Scripts\python.exe -m pip install -e .
|
|
153
|
+
.\.venv\Scripts\den.exe --help
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
Linux:
|
|
157
|
+
|
|
158
|
+
```bash
|
|
159
|
+
git clone https://github.com/Dol0resH8ze/hush.git
|
|
160
|
+
cd hush
|
|
161
|
+
python3 -m venv .venv
|
|
162
|
+
.venv/bin/python -m pip install -e .
|
|
163
|
+
.venv/bin/den --help
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
You can activate the environment to use the short command `den`. Otherwise use
|
|
167
|
+
the full executable path above. The equivalent `python -m den` also works when
|
|
168
|
+
using this environment's Python.
|
|
169
|
+
|
|
170
|
+
## Connect Windows and Linux over Tor
|
|
171
|
+
|
|
172
|
+
One computer runs the relay, and each participant runs Tor locally. The relay
|
|
173
|
+
can be on the owner's computer or a separate machine. It must remain running
|
|
174
|
+
throughout the session. Den does not bundle, download, start, or configure Tor,
|
|
175
|
+
and no shared public relay is supplied.
|
|
176
|
+
|
|
177
|
+
1. Install and configure Tor using the
|
|
178
|
+
[Tor Project's installation guidance](https://support.torproject.org/little-t-tor/).
|
|
179
|
+
The [official Tor downloads](https://download.torproject.org/tor/) include
|
|
180
|
+
expert bundles for Windows and Linux. Verify downloads according to Tor's
|
|
181
|
+
instructions.
|
|
182
|
+
2. On the relay machine, run `den relay --port 8765`. It binds only to
|
|
183
|
+
`127.0.0.1`, so it is not exposed to the LAN or public internet.
|
|
184
|
+
3. Configure a Tor onion service to forward virtual port 8765 to
|
|
185
|
+
`127.0.0.1:8765`. See [the relay configuration example](https://github.com/Dol0resH8ze/hush/blob/main/examples/torrc.relay.example)
|
|
186
|
+
and the [official onion service guide](https://community.torproject.org/onion-services/setup/).
|
|
187
|
+
The directory Tor creates contains a `hostname` file with your onion address.
|
|
188
|
+
4. On each participant's computer, configure a local Tor SOCKS port, normally
|
|
189
|
+
`127.0.0.1:9050`. See [the client configuration example](https://github.com/Dol0resH8ze/hush/blob/main/examples/torrc.client.example).
|
|
190
|
+
`SafeSocks 1` blocks unsafe SOCKS requests; Tor also documents
|
|
191
|
+
[DNS leak checks](https://support.torproject.org/little-t-tor/troubleshooting/check-for-leaks/).
|
|
192
|
+
5. The owner creates a room, then shares the full invite privately:
|
|
193
|
+
|
|
194
|
+
```text
|
|
195
|
+
den create --server YOUR_REAL_V3_ADDRESS.onion --name Alice
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
Other participants run:
|
|
199
|
+
|
|
200
|
+
```text
|
|
201
|
+
den join --name Bob
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
They paste the invite at the hidden prompt and wait for approval. If their Tor
|
|
205
|
+
SOCKS listener uses another port, add `--proxy-port PORT` to `create` or `join`.
|
|
206
|
+
Do not add `--local-test` for connections between computers.
|
|
207
|
+
|
|
208
|
+
Initial manual cross-device use has been reported successful. Automated transport
|
|
209
|
+
checks use a local SOCKS5 server with DNS lookups disabled. Neither local tests
|
|
210
|
+
nor a successful connection establish a guarantee of anonymity.
|
|
211
|
+
|
|
212
|
+
## Commands inside a room
|
|
213
|
+
|
|
214
|
+
| Command | What it does |
|
|
215
|
+
| --- | --- |
|
|
216
|
+
| ordinary text + Enter | Sends a message, up to 4000 UTF-8 bytes |
|
|
217
|
+
| `/members` | Lists approved names and device fingerprints |
|
|
218
|
+
| `/pending` | Lists requests waiting for the owner |
|
|
219
|
+
| `/approve NAME_OR_ID` | Owner admits one pending device |
|
|
220
|
+
| `/reject NAME_OR_ID` | Owner declines one pending device |
|
|
221
|
+
| `/kick NAME_OR_ID` | Owner removes a participant |
|
|
222
|
+
| `/lock` | Owner closes admission and rejects current pending requests |
|
|
223
|
+
| `/unlock` | Owner reopens admission |
|
|
224
|
+
| `/invite` | Owner displays the secret invite again |
|
|
225
|
+
| `/help` | Shows command help |
|
|
226
|
+
| `/quit` or `/leave` | Leaves; the owner's departure closes the room |
|
|
227
|
+
| `//text` | Sends a message beginning with a literal slash |
|
|
228
|
+
|
|
229
|
+
A device ID is its displayed fingerprint; a unique prefix also works. Compare
|
|
230
|
+
fingerprints with your intended contacts through a trusted channel before
|
|
231
|
+
approval. A familiar username alone does not identify a real person.
|
|
232
|
+
|
|
233
|
+
Chat lines look like `<Alice#1575b149>Hello!`, with a consistent color for each
|
|
234
|
+
username and plain message text. Your own messages use the same format. The code
|
|
235
|
+
is the first eight characters of the device fingerprint; `/members` shows the
|
|
236
|
+
full fingerprint. Colors are derived from usernames consistently on every client.
|
|
237
|
+
|
|
238
|
+
Your own displayed message means it was submitted, not that every
|
|
239
|
+
participant received it. Messages racing a membership update can be dropped;
|
|
240
|
+
there are no delivery receipts or automatic retries. Check `/members` and resend
|
|
241
|
+
if a membership-change notice appears.
|
|
242
|
+
|
|
243
|
+
## Privacy boundaries
|
|
244
|
+
|
|
245
|
+
| Observer | Visible information |
|
|
246
|
+
| --- | --- |
|
|
247
|
+
| Approved room participants | Usernames, device fingerprints, membership and chat text |
|
|
248
|
+
| Room owner | The above, plus pending usernames and admission requests |
|
|
249
|
+
| Relay operator | Random room IDs, public device keys, room membership, connection timing, traffic sizes and encrypted payloads |
|
|
250
|
+
| Relay over normal Tor connections | Tor-side connections; no participant IP field is sent by Den |
|
|
251
|
+
| Someone with an invite | Relay onion address, room ID, admission secret, owner public keys; ability to request entry |
|
|
252
|
+
|
|
253
|
+
The invite is **encoded, not encrypted**. Treat it as a secret. Any admitted
|
|
254
|
+
participant can copy a message or share what they know. Reusing a recognizable
|
|
255
|
+
username or disclosing personal information can identify you. Tor cannot promise
|
|
256
|
+
perfect anonymity, and traffic correlation remains possible.
|
|
257
|
+
|
|
258
|
+
No app history does not mean no traces: terminal scrollback, clipboard tools,
|
|
259
|
+
screen recording, OS swap, crash dumps and compromised endpoints may retain
|
|
260
|
+
content. Session keys are not written by Den, but Python does not guarantee
|
|
261
|
+
secure memory erasure. The current protocol has no forward secrecy or
|
|
262
|
+
post-compromise recovery: stolen recipient keys can decrypt previously captured
|
|
263
|
+
ciphertext for that session. The owner is a trusted participant and controls
|
|
264
|
+
membership and release availability. See [SECURITY.md](https://github.com/Dol0resH8ze/hush/blob/main/SECURITY.md) for details.
|
|
265
|
+
|
|
266
|
+
Keep actual Tor identity keys outside source control and shared or synced
|
|
267
|
+
folders; the supplied Tor configuration is only an example.
|
|
268
|
+
|
|
269
|
+
## Development and verification
|
|
270
|
+
|
|
271
|
+
```text
|
|
272
|
+
python -m pip install -e ".[dev]"
|
|
273
|
+
python -m pytest -q
|
|
274
|
+
python -m den demo
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
Use the virtual environment's Python. Tests cover a real loopback relay with
|
|
278
|
+
three independent client identities, admission, lock/unlock, disconnect cleanup,
|
|
279
|
+
encryption, signatures, replay rejection, removal, malformed traffic, and SOCKS
|
|
280
|
+
transport failure behavior. A Windows/Linux CI matrix is supplied under
|
|
281
|
+
`.github/workflows/test.yml`; it has not been run on a remote CI service.
|
|
282
|
+
|
|
283
|
+
Architecture and the wire flow are documented in [the protocol notes](https://github.com/Dol0resH8ze/hush/blob/main/docs/PROTOCOL.md).
|
|
284
|
+
Maintainers can follow [the release guide](https://github.com/Dol0resH8ze/hush/blob/main/docs/RELEASING.md).
|
|
285
|
+
|
|
286
|
+
## Next milestones
|
|
287
|
+
|
|
288
|
+
1. Validate an actual onion deployment between independent Windows/Linux devices.
|
|
289
|
+
2. Review the protocol and implementation externally, and evaluate migrating
|
|
290
|
+
to an established group protocol such as MLS with suitable library support.
|
|
291
|
+
3. Add delivery acknowledgements and safer recovery around membership changes.
|
|
292
|
+
4. Package signed standalone executables after the protocol and dependency
|
|
293
|
+
choices are reviewed. Current installation uses Python, not an installer.
|
|
294
|
+
|
|
@@ -0,0 +1,260 @@
|
|
|
1
|
+
# Den
|
|
2
|
+
|
|
3
|
+
Previously named Hush. The `hush` command is
|
|
4
|
+
retained as an alias. Existing Tor configuration directories (such as `HushTor`)
|
|
5
|
+
and onion addresses do not need to change. New invites start with `den1.`;
|
|
6
|
+
Den also accepts legacy `hush1.` invites.
|
|
7
|
+
|
|
8
|
+
Private, live text rooms in a terminal. Pick a username, create a room, share a
|
|
9
|
+
secret invite, and approve the devices that can participate. No account, email,
|
|
10
|
+
phone number, or password is required.
|
|
11
|
+
|
|
12
|
+
**Status: working experimental prototype, not an independently audited secure
|
|
13
|
+
messenger.** Normal connections require Tor. A separate, explicitly named local
|
|
14
|
+
test mode makes it possible to try the app on one computer without Tor.
|
|
15
|
+
|
|
16
|
+
## Installation
|
|
17
|
+
|
|
18
|
+
Requires Python **3.12 or newer**. Tor is a separate prerequisite for networking
|
|
19
|
+
between devices; it is not bundled or installed by pip. The package name is
|
|
20
|
+
`den-terminal`, and its command is `den`.
|
|
21
|
+
|
|
22
|
+
Once the release is published to PyPI, install it into a virtual environment:
|
|
23
|
+
|
|
24
|
+
Windows PowerShell:
|
|
25
|
+
|
|
26
|
+
```powershell
|
|
27
|
+
py -3 -m venv .venv
|
|
28
|
+
.\.venv\Scripts\python.exe -m pip install den-terminal
|
|
29
|
+
.\.venv\Scripts\den.exe --help
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Linux:
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
python3 -m venv .venv
|
|
36
|
+
.venv/bin/python -m pip install den-terminal
|
|
37
|
+
.venv/bin/den --help
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Activate the environment if you want to use `den` without the executable's full
|
|
41
|
+
path. `python -m den` also works using the environment's Python. For development
|
|
42
|
+
or before the first publication, use the source installation instructions below.
|
|
43
|
+
|
|
44
|
+
## What this version does
|
|
45
|
+
|
|
46
|
+
- Supports up to **16 devices per room**, including the owner.
|
|
47
|
+
- Generates fresh signing and encryption keys for each room session. Your
|
|
48
|
+
username is a display name, not a globally reserved identity.
|
|
49
|
+
- Creates a long random invite containing the room address, secret, and pinned
|
|
50
|
+
owner keys. The room ID alone is not sufficient for approval.
|
|
51
|
+
- Prompts privately for the invite when joining, keeping it out of command-line
|
|
52
|
+
arguments and shell command history.
|
|
53
|
+
- Requires the room owner to approve each joining device. Names are unique
|
|
54
|
+
within a room, ignoring letter case.
|
|
55
|
+
- Encrypts usernames and message content on the clients. The relay forwards
|
|
56
|
+
encrypted data and cannot read these fields from protocol traffic.
|
|
57
|
+
- Authenticates message authors and the owner's membership updates using
|
|
58
|
+
signatures. Device fingerprints distinguish sessions.
|
|
59
|
+
- Lets the owner lock/unlock rooms, reject requests, and remove participants.
|
|
60
|
+
- Stops releasing new messages for removed participants. The owner validates
|
|
61
|
+
each message against current membership before its recipient ciphertext is
|
|
62
|
+
released, including when a sender has an outdated roster.
|
|
63
|
+
- Uses Tor SOCKS5 with remote hostname resolution. Normal mode accepts only
|
|
64
|
+
valid v3 onion addresses and has **no direct-network fallback**.
|
|
65
|
+
- Keeps rooms and identities in memory. Den writes no chat history, user
|
|
66
|
+
database, message logs, or invite files.
|
|
67
|
+
- Closes the entire room when its owner disconnects. There is no reconnection,
|
|
68
|
+
offline inbox, history recovery, file transfer, audio, or video in version 0.1.
|
|
69
|
+
|
|
70
|
+
## Try a local room
|
|
71
|
+
|
|
72
|
+
After installation, open Windows Terminal / PowerShell in the directory where
|
|
73
|
+
you created the virtual environment and run:
|
|
74
|
+
|
|
75
|
+
```powershell
|
|
76
|
+
.\.venv\Scripts\den.exe demo
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
The demo starts a temporary loopback relay and three clients using real
|
|
80
|
+
encryption. It exercises admission, chat, locking, removal, and room closure,
|
|
81
|
+
then stops all of them. **It does not use Tor or demonstrate network anonymity.**
|
|
82
|
+
|
|
83
|
+
For an interactive local test, keep each command running in a separate terminal
|
|
84
|
+
tab, with that same directory as its working directory. On Linux, replace
|
|
85
|
+
`.\.venv\Scripts\den.exe` with `.venv/bin/den`:
|
|
86
|
+
|
|
87
|
+
```powershell
|
|
88
|
+
# Tab 1: relay
|
|
89
|
+
.\.venv\Scripts\den.exe relay
|
|
90
|
+
|
|
91
|
+
# Tab 2: room owner
|
|
92
|
+
.\.venv\Scripts\den.exe create --server 127.0.0.1 --local-test --name Alice
|
|
93
|
+
|
|
94
|
+
# Tab 3: another participant; paste the invite at the hidden prompt
|
|
95
|
+
.\.venv\Scripts\den.exe join --local-test --name Bob
|
|
96
|
+
|
|
97
|
+
# Tab 4: third participant
|
|
98
|
+
.\.venv\Scripts\den.exe join --local-test --name Cara
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
In Alice's tab, type `/approve Bob` and `/approve Cara` after their requests
|
|
102
|
+
appear. All three can now type messages. Use `/quit` to leave; quitting the
|
|
103
|
+
owner's session ends the room. Local test invites only work on the same
|
|
104
|
+
computer and only with `--local-test`.
|
|
105
|
+
|
|
106
|
+
## Install from source
|
|
107
|
+
|
|
108
|
+
Clone the repository, then install from the checkout. Copy source rather than
|
|
109
|
+
an existing `.venv` when transferring the project between machines. Tor private
|
|
110
|
+
keys are not part of this project and should not be copied with it.
|
|
111
|
+
|
|
112
|
+
Windows PowerShell:
|
|
113
|
+
|
|
114
|
+
```powershell
|
|
115
|
+
git clone https://github.com/Dol0resH8ze/hush.git
|
|
116
|
+
cd hush
|
|
117
|
+
py -3 -m venv .venv
|
|
118
|
+
.\.venv\Scripts\python.exe -m pip install -e .
|
|
119
|
+
.\.venv\Scripts\den.exe --help
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
Linux:
|
|
123
|
+
|
|
124
|
+
```bash
|
|
125
|
+
git clone https://github.com/Dol0resH8ze/hush.git
|
|
126
|
+
cd hush
|
|
127
|
+
python3 -m venv .venv
|
|
128
|
+
.venv/bin/python -m pip install -e .
|
|
129
|
+
.venv/bin/den --help
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
You can activate the environment to use the short command `den`. Otherwise use
|
|
133
|
+
the full executable path above. The equivalent `python -m den` also works when
|
|
134
|
+
using this environment's Python.
|
|
135
|
+
|
|
136
|
+
## Connect Windows and Linux over Tor
|
|
137
|
+
|
|
138
|
+
One computer runs the relay, and each participant runs Tor locally. The relay
|
|
139
|
+
can be on the owner's computer or a separate machine. It must remain running
|
|
140
|
+
throughout the session. Den does not bundle, download, start, or configure Tor,
|
|
141
|
+
and no shared public relay is supplied.
|
|
142
|
+
|
|
143
|
+
1. Install and configure Tor using the
|
|
144
|
+
[Tor Project's installation guidance](https://support.torproject.org/little-t-tor/).
|
|
145
|
+
The [official Tor downloads](https://download.torproject.org/tor/) include
|
|
146
|
+
expert bundles for Windows and Linux. Verify downloads according to Tor's
|
|
147
|
+
instructions.
|
|
148
|
+
2. On the relay machine, run `den relay --port 8765`. It binds only to
|
|
149
|
+
`127.0.0.1`, so it is not exposed to the LAN or public internet.
|
|
150
|
+
3. Configure a Tor onion service to forward virtual port 8765 to
|
|
151
|
+
`127.0.0.1:8765`. See [the relay configuration example](https://github.com/Dol0resH8ze/hush/blob/main/examples/torrc.relay.example)
|
|
152
|
+
and the [official onion service guide](https://community.torproject.org/onion-services/setup/).
|
|
153
|
+
The directory Tor creates contains a `hostname` file with your onion address.
|
|
154
|
+
4. On each participant's computer, configure a local Tor SOCKS port, normally
|
|
155
|
+
`127.0.0.1:9050`. See [the client configuration example](https://github.com/Dol0resH8ze/hush/blob/main/examples/torrc.client.example).
|
|
156
|
+
`SafeSocks 1` blocks unsafe SOCKS requests; Tor also documents
|
|
157
|
+
[DNS leak checks](https://support.torproject.org/little-t-tor/troubleshooting/check-for-leaks/).
|
|
158
|
+
5. The owner creates a room, then shares the full invite privately:
|
|
159
|
+
|
|
160
|
+
```text
|
|
161
|
+
den create --server YOUR_REAL_V3_ADDRESS.onion --name Alice
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
Other participants run:
|
|
165
|
+
|
|
166
|
+
```text
|
|
167
|
+
den join --name Bob
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
They paste the invite at the hidden prompt and wait for approval. If their Tor
|
|
171
|
+
SOCKS listener uses another port, add `--proxy-port PORT` to `create` or `join`.
|
|
172
|
+
Do not add `--local-test` for connections between computers.
|
|
173
|
+
|
|
174
|
+
Initial manual cross-device use has been reported successful. Automated transport
|
|
175
|
+
checks use a local SOCKS5 server with DNS lookups disabled. Neither local tests
|
|
176
|
+
nor a successful connection establish a guarantee of anonymity.
|
|
177
|
+
|
|
178
|
+
## Commands inside a room
|
|
179
|
+
|
|
180
|
+
| Command | What it does |
|
|
181
|
+
| --- | --- |
|
|
182
|
+
| ordinary text + Enter | Sends a message, up to 4000 UTF-8 bytes |
|
|
183
|
+
| `/members` | Lists approved names and device fingerprints |
|
|
184
|
+
| `/pending` | Lists requests waiting for the owner |
|
|
185
|
+
| `/approve NAME_OR_ID` | Owner admits one pending device |
|
|
186
|
+
| `/reject NAME_OR_ID` | Owner declines one pending device |
|
|
187
|
+
| `/kick NAME_OR_ID` | Owner removes a participant |
|
|
188
|
+
| `/lock` | Owner closes admission and rejects current pending requests |
|
|
189
|
+
| `/unlock` | Owner reopens admission |
|
|
190
|
+
| `/invite` | Owner displays the secret invite again |
|
|
191
|
+
| `/help` | Shows command help |
|
|
192
|
+
| `/quit` or `/leave` | Leaves; the owner's departure closes the room |
|
|
193
|
+
| `//text` | Sends a message beginning with a literal slash |
|
|
194
|
+
|
|
195
|
+
A device ID is its displayed fingerprint; a unique prefix also works. Compare
|
|
196
|
+
fingerprints with your intended contacts through a trusted channel before
|
|
197
|
+
approval. A familiar username alone does not identify a real person.
|
|
198
|
+
|
|
199
|
+
Chat lines look like `<Alice#1575b149>Hello!`, with a consistent color for each
|
|
200
|
+
username and plain message text. Your own messages use the same format. The code
|
|
201
|
+
is the first eight characters of the device fingerprint; `/members` shows the
|
|
202
|
+
full fingerprint. Colors are derived from usernames consistently on every client.
|
|
203
|
+
|
|
204
|
+
Your own displayed message means it was submitted, not that every
|
|
205
|
+
participant received it. Messages racing a membership update can be dropped;
|
|
206
|
+
there are no delivery receipts or automatic retries. Check `/members` and resend
|
|
207
|
+
if a membership-change notice appears.
|
|
208
|
+
|
|
209
|
+
## Privacy boundaries
|
|
210
|
+
|
|
211
|
+
| Observer | Visible information |
|
|
212
|
+
| --- | --- |
|
|
213
|
+
| Approved room participants | Usernames, device fingerprints, membership and chat text |
|
|
214
|
+
| Room owner | The above, plus pending usernames and admission requests |
|
|
215
|
+
| Relay operator | Random room IDs, public device keys, room membership, connection timing, traffic sizes and encrypted payloads |
|
|
216
|
+
| Relay over normal Tor connections | Tor-side connections; no participant IP field is sent by Den |
|
|
217
|
+
| Someone with an invite | Relay onion address, room ID, admission secret, owner public keys; ability to request entry |
|
|
218
|
+
|
|
219
|
+
The invite is **encoded, not encrypted**. Treat it as a secret. Any admitted
|
|
220
|
+
participant can copy a message or share what they know. Reusing a recognizable
|
|
221
|
+
username or disclosing personal information can identify you. Tor cannot promise
|
|
222
|
+
perfect anonymity, and traffic correlation remains possible.
|
|
223
|
+
|
|
224
|
+
No app history does not mean no traces: terminal scrollback, clipboard tools,
|
|
225
|
+
screen recording, OS swap, crash dumps and compromised endpoints may retain
|
|
226
|
+
content. Session keys are not written by Den, but Python does not guarantee
|
|
227
|
+
secure memory erasure. The current protocol has no forward secrecy or
|
|
228
|
+
post-compromise recovery: stolen recipient keys can decrypt previously captured
|
|
229
|
+
ciphertext for that session. The owner is a trusted participant and controls
|
|
230
|
+
membership and release availability. See [SECURITY.md](https://github.com/Dol0resH8ze/hush/blob/main/SECURITY.md) for details.
|
|
231
|
+
|
|
232
|
+
Keep actual Tor identity keys outside source control and shared or synced
|
|
233
|
+
folders; the supplied Tor configuration is only an example.
|
|
234
|
+
|
|
235
|
+
## Development and verification
|
|
236
|
+
|
|
237
|
+
```text
|
|
238
|
+
python -m pip install -e ".[dev]"
|
|
239
|
+
python -m pytest -q
|
|
240
|
+
python -m den demo
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
Use the virtual environment's Python. Tests cover a real loopback relay with
|
|
244
|
+
three independent client identities, admission, lock/unlock, disconnect cleanup,
|
|
245
|
+
encryption, signatures, replay rejection, removal, malformed traffic, and SOCKS
|
|
246
|
+
transport failure behavior. A Windows/Linux CI matrix is supplied under
|
|
247
|
+
`.github/workflows/test.yml`; it has not been run on a remote CI service.
|
|
248
|
+
|
|
249
|
+
Architecture and the wire flow are documented in [the protocol notes](https://github.com/Dol0resH8ze/hush/blob/main/docs/PROTOCOL.md).
|
|
250
|
+
Maintainers can follow [the release guide](https://github.com/Dol0resH8ze/hush/blob/main/docs/RELEASING.md).
|
|
251
|
+
|
|
252
|
+
## Next milestones
|
|
253
|
+
|
|
254
|
+
1. Validate an actual onion deployment between independent Windows/Linux devices.
|
|
255
|
+
2. Review the protocol and implementation externally, and evaluate migrating
|
|
256
|
+
to an established group protocol such as MLS with suitable library support.
|
|
257
|
+
3. Add delivery acknowledgements and safer recovery around membership changes.
|
|
258
|
+
4. Package signed standalone executables after the protocol and dependency
|
|
259
|
+
choices are reviewed. Current installation uses Python, not an installer.
|
|
260
|
+
|