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.
@@ -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,7 @@
1
+ include LICENSE README.md SECURITY.md
2
+ recursive-include docs *.md
3
+ recursive-include examples *.example
4
+ recursive-include tests *.py
5
+ exclude LICENSE.txt
6
+ global-exclude *.py[cod]
7
+ global-exclude __pycache__
@@ -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
+