Skip to content
This repository was archived by the owner on Mar 11, 2026. It is now read-only.

Commit 8dfa589

Browse files
ESousa97ESousa97
authored
Revise README with project details and badges
Updated README with badges, project status, and enhanced descriptions.
1 parent f6a66cf commit 8dfa589

1 file changed

Lines changed: 216 additions & 69 deletions

File tree

‎README.MD‎

Lines changed: 216 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -1,121 +1,268 @@
1+
<div align="center">
2+
13
# cmd-chat
24

3-
> Um chat de linha de comando seguro usando RSA e Fernet (criptografia end-to-end), construído sobre Sanic e WebSockets.
5+
[![CI](https://img.shields.io/github/actions/workflow/status/ESousa97/cmd-chat/ci.yml?branch=main&style=flat&logo=github-actions&logoColor=white)](https://github.com/ESousa97/cmd-chat/actions/workflows/ci.yml)
6+
[![CodeFactor](https://img.shields.io/codefactor/grade/github/ESousa97/cmd-chat?style=flat&logo=codefactor&logoColor=white)](https://www.codefactor.io/repository/github/esousa97/cmd-chat)
7+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat&logo=opensourceinitiative&logoColor=white)](https://opensource.org/licenses/MIT)
8+
[![Status](https://img.shields.io/badge/Status-Archived-lightgrey.svg?style=flat&logo=archive&logoColor=white)](#)
49

5-
![CI](https://github.com/ESousa97/cmd-chat/actions/workflows/ci.yml/badge.svg)
6-
![License](https://img.shields.io/github/license/ESousa97/cmd-chat)
7-
![Python](https://img.shields.io/badge/python-%3E%3D3.10-blue)
8-
![Last Commit](https://img.shields.io/github/last-commit/ESousa97/cmd-chat)
9-
![CodeFactor](https://www.codefactor.io/repository/github/esousa97/cmd-chat/badge)
10+
**Chat de linha de comando com criptografia end-to-end — handshake RSA 512-bit para troca segura de chaves simétricas + Fernet para encriptação da sessão, servidor assíncrono Sanic com 3 endpoints WebSocket (`/talk` para mensagens, `/update` para sincronização de estado, `/get_key` para handshake RSA com PEM), validação de payloads via Pydantic, interface Rich/Colorama com cores por IP e username, geração automática de usernames aleatórios (ex.: `SmartFox52`, `BraveLion12`), autenticação por `ADMIN_PASSWORD`, instalável via `pip install -e .` com executável `cmd_chat` no PATH.**
1011

11-
O `cmd-chat` permite que desenvolvedores criem salas de chat através do terminal. Todas as mensagens são encriptadas usando criptografia híbrida: as chaves simétricas (Fernet) são negociadas com segurança através de chaves assimétricas (RSA 512-bit) e cada cliente exibe seu display usando a biblioteca Rich ou renderização padrão.
12+
</div>
1213

13-
## Funcionalidades
14-
- 🔒 **Comunicação Encriptada**: RSA para troca segura de chaves + Fernet para a sessão simétrica.
15-
- 🚀 **Asynchronous IO**: Servidor de alta performance construído com Sanic.
16-
- 🎨 **Rich UI**: Terminal limpo e colorido (IP e Username colors).
17-
- 🛠 **Validado e Checado**: Totalmente aderente ao padrão PEP8 moderno (Ruff) e Pydantic.
14+
---
15+
16+
> **⚠️ Projeto Arquivado**
17+
> Este projeto não recebe mais atualizações ou correções. O código permanece disponível como referência e pode ser utilizado livremente sob a licença MIT. Fique à vontade para fazer fork caso deseje continuar o desenvolvimento.
18+
19+
---
20+
21+
## Índice
22+
23+
- [Sobre o Projeto](#sobre-o-projeto)
24+
- [Demonstração](#demonstração)
25+
- [Funcionalidades](#funcionalidades)
26+
- [Tecnologias](#tecnologias)
27+
- [Arquitetura](#arquitetura)
28+
- [Começando](#começando)
29+
- [Pré-requisitos](#pré-requisitos)
30+
- [Instalação](#instalação)
31+
- [Uso](#uso)
32+
- [Endpoints WebSocket](#endpoints-websocket)
33+
- [Scripts Disponíveis](#scripts-disponíveis)
34+
- [FAQ](#faq)
35+
- [Licença](#licença)
36+
- [Contato](#contato)
37+
38+
---
39+
40+
## Sobre o Projeto
41+
42+
Chat de linha de comando que permite criar salas de chat criptografadas pelo terminal. Todas as mensagens são encriptadas usando criptografia híbrida: chaves simétricas Fernet negociadas com segurança via chaves assimétricas RSA 512-bit.
43+
44+
O repositório prioriza:
45+
46+
- **Criptografia híbrida end-to-end** — Handshake RSA 512-bit para troca segura de chave simétrica + Fernet (AES-128-CBC com HMAC) para encriptação de cada mensagem da sessão. O endpoint `/get_key` recebe a public key do cliente em formato PEM e retorna a chave Fernet encriptada com RSA
47+
- **Servidor assíncrono Sanic** — 3 endpoints WebSocket: `/talk` para envio de mensagens encriptadas em Fernet, `/update` para sincronização contínua de mensagens e lista de usuários online, `/get_key` para handshake RSA com PEM. Armazenamento in-memory do estado da sala
48+
- **Validação de contratos via Pydantic** — Payloads WebSocket validados com modelos Pydantic: `/talk` com formato `{"text": "<enc_msg>", "username": "...", "action": "..."}`, `/update` com `{"messages": [...], "users_in_chat": [...]}`
49+
- **Interface CLI com Rich/Colorama** — Terminal limpo e colorido com cores por IP e username, renderização Rich quando disponível com fallback para renderização padrão
50+
- **Username aleatório e autenticação** — Geração automática de nomes ao ingressar (ex.: `SmartFox52`, `BraveLion12`), autenticação do servidor via `ADMIN_PASSWORD` configurável
51+
- **Instalável como executável** — `pip install -e .` registra `cmd_chat` no PATH com subcomandos `serve` e `connect`
52+
53+
---
1854

1955
## Demonstração
2056

2157
![Example Usage](example.gif)
2258

23-
## Stack Tecnológico
59+
**Iniciando o servidor:**
60+
61+
```bash
62+
cmd_chat serve 127.0.0.1 5000 -p "senha_super_secreta"
63+
```
64+
65+
**Conectando um cliente** (em outro terminal):
2466

25-
| Tecnologia | Função no Projeto |
26-
|---|---|
27-
| **Python 3.10+** | Base Runtime |
28-
| **Sanic** | Servidor Assíncrono para rotas HTTP e WebSockets |
29-
| **Pydantic** | Validação rápida de contratos de payloads de WebSocket |
30-
| **RSA / Cryptography**| Implementação criptográfica |
31-
| **Rich / Colorama** | Interface CLI |
67+
```bash
68+
cmd_chat connect 127.0.0.1 5000 "senha_super_secreta"
69+
```
70+
71+
---
72+
73+
## Funcionalidades
74+
75+
- **Comunicação encriptada** — RSA 512-bit para troca segura de chaves + Fernet para sessão simétrica, criptografia end-to-end em todas as mensagens
76+
- **Servidor assíncrono** — Sanic com alta performance para rotas HTTP e WebSockets simultâneos
77+
- **Rich UI** — Terminal colorido com cores por IP e username, renderização Rich com fallback padrão
78+
- **Usernames aleatórios** — Geração automática ao ingressar no servidor (ex.: `SmartFox52`, `BraveLion12`)
79+
- **Sincronização de estado** — Endpoint `/update` com lista de mensagens e usuários online em tempo real
80+
- **Autenticação** — `ADMIN_PASSWORD` para controle de acesso ao servidor
81+
- **Validação de payloads** — Contratos Pydantic para todos os payloads WebSocket
82+
- **Instalável via pip** — `pip install -e .` com executável `cmd_chat` no PATH (`serve` e `connect`)
83+
84+
---
85+
86+
## Tecnologias
87+
88+
![Python](https://img.shields.io/badge/Python_3.10+-3776AB?style=flat&logo=python&logoColor=white)
89+
![Sanic](https://img.shields.io/badge/Sanic-FF0D68?style=flat&logoColor=white)
90+
![Pydantic](https://img.shields.io/badge/Pydantic-E92063?style=flat&logo=pydantic&logoColor=white)
91+
![Cryptography](https://img.shields.io/badge/RSA_+_Fernet-000000?style=flat&logo=letsencrypt&logoColor=white)
92+
![Rich](https://img.shields.io/badge/Rich-4E9A06?style=flat&logoColor=white)
93+
![Ruff](https://img.shields.io/badge/Ruff-D7FF64?style=flat&logoColor=black)
94+
![Pytest](https://img.shields.io/badge/Pytest-0A9EDC?style=flat&logo=pytest&logoColor=white)
95+
![GitHub Actions](https://img.shields.io/badge/GitHub_Actions-2088FF?style=flat&logo=github-actions&logoColor=white)
96+
97+
---
98+
99+
## Arquitetura
100+
101+
```mermaid
102+
sequenceDiagram
103+
participant Cliente
104+
participant Servidor as Servidor Sanic
105+
106+
Note over Cliente,Servidor: Handshake RSA
107+
Cliente->>Cliente: Gera par RSA 512-bit (pub/priv)
108+
Cliente->>Servidor: POST /get_key (public key PEM)
109+
Servidor->>Servidor: Gera chave Fernet
110+
Servidor->>Cliente: Chave Fernet encriptada com RSA pub
111+
112+
Note over Cliente,Servidor: Sessão encriptada
113+
Cliente->>Servidor: WS /talk {"text": "Fernet(msg)", "username": "...", "action": "..."}
114+
Servidor->>Cliente: WS /update {"messages": [...], "users_in_chat": [...]}
115+
```
116+
117+
### Fluxo Criptográfico
32118

33-
## Pré-requisitos
119+
1. Cliente gera par de chaves RSA 512-bit e envia public key em PEM via `/get_key`
120+
2. Servidor gera chave simétrica Fernet, encripta com a public key RSA do cliente e retorna
121+
3. Cliente decripta a chave Fernet com sua private key RSA
122+
4. Todas as mensagens subsequentes são encriptadas/decriptadas com Fernet (AES-128-CBC + HMAC)
34123

35-
- Python `>= 3.10`
36-
- `pip` e ambiente virtual
124+
### Componentes
37125

38-
## Instalação e Uso
126+
| Componente | Responsabilidade |
127+
| --- | --- |
128+
| **Servidor Sanic** | Rotas HTTP/WebSocket, gerenciamento de salas, armazenamento in-memory |
129+
| **Handshake RSA** | `/get_key` — troca segura de chave simétrica via RSA 512-bit PEM |
130+
| **Sessão Fernet** | `/talk` — encriptação simétrica de mensagens com chave negociada |
131+
| **Sincronização** | `/update` — broadcast de mensagens e lista de usuários online |
132+
| **Pydantic** | Validação de payloads WebSocket (text, username, action, messages, users) |
133+
| **Rich/Colorama** | Renderização CLI com cores por IP/username, fallback padrão |
134+
135+
---
136+
137+
## Começando
138+
139+
### Pré-requisitos
140+
141+
- Python 3.10+
142+
- pip e ambiente virtual
143+
144+
### Instalação
39145

40-
1. **Clone o repositório** e entre na pasta:
41146
```bash
42147
git clone https://github.com/ESousa97/cmd-chat.git
43148
cd cmd-chat
44-
```
45149

46-
2. **Crie e ative um ambiente virtual:**
47-
```bash
150+
# Ambiente virtual
48151
python -m venv venv
49-
# Linux/MacOS
152+
153+
# Linux/macOS
50154
source venv/bin/activate
155+
51156
# Windows
52157
.\venv\Scripts\activate
53-
```
54158

55-
3. **Instale os requisitos:**
56-
```bash
159+
# Instalar
57160
pip install -e .
58-
```
59161

60-
4. **Configuração inicial:**
61-
Crie o seu `.env`:
62-
```bash
162+
# Configuração
63163
cp .env.example .env
164+
# Edite .env e defina ADMIN_PASSWORD
64165
```
65-
Ou edite opcionalmente e defina seu `ADMIN_PASSWORD`.
66166

67-
## Como Usar o Chat
167+
### Uso
68168

69-
O `cmd-chat` instala um executável no seu PATH local. Você também pode rodá-lo utilizando `python cmd_chat.py`.
70-
71-
### Iniciando o Servidor
169+
**Servidor:**
72170

73171
```bash
74172
cmd_chat serve 127.0.0.1 5000 -p "senha_super_secreta"
75173
```
76174

77-
### Conectando um Cliente
78-
79-
Em um terminal separado (para o cliente), excute:
175+
**Cliente** (em outro terminal):
80176

81177
```bash
82178
cmd_chat connect 127.0.0.1 5000 "senha_super_secreta"
83179
```
84180

85-
O `cmd-chat` agora gera automaticamente um nome de usuário aleatório para você (ex: `SmartFox52`, `BraveLion12`, etc.) ao ingressar no servidor!
181+
Um username aleatório é gerado automaticamente ao conectar. Digite suas mensagens e inicie a conversa.
182+
183+
Também é possível executar via `python cmd_chat.py` diretamente.
184+
185+
---
86186

87-
Você agora está no chat! Digite suas mensagens e inicie a conversa.
187+
## Endpoints WebSocket
188+
189+
| Endpoint | Tipo | Payload | Descrição |
190+
| --- | --- | --- | --- |
191+
| `/talk` | WS | `{"text": "<enc_msg>", "username": "...", "action": "..."}` | Envio de mensagens encriptadas em Fernet |
192+
| `/update` | WS | `{"messages": [...], "users_in_chat": [...]}` | Sincronização contínua de mensagens e usuários online |
193+
| `/get_key` | POST/GET | Public key PEM → Fernet key encriptada com RSA | Handshake RSA para troca de chave simétrica |
194+
195+
---
88196

89197
## Scripts Disponíveis
90-
Se você está contribuindo para o repositório, use os scripts atrelados ao `Makefile` ou diretamente via pip:
91198

92-
| Comando | Descrição |
93-
|---|---|
94-
| `ruff check .` | Roda linting para código |
95-
| `ruff format .` | Formata o código do repositório inteiro |
96-
| `pytest tests/` | Executa a pipeline de testes do repositório |
199+
```bash
200+
# Lint
201+
ruff check .
202+
203+
# Formatação
204+
ruff format .
205+
206+
# Testes
207+
pytest tests/
208+
```
209+
210+
---
211+
212+
## FAQ
97213

98-
## API Documentada
99-
A API utiliza chamadas Websocket.
100-
- `/talk` (WS): Envio de mensagens codificadas em Fernet, no formato `{"text": "<enc_msg>", "username": "...", "action": "..."}`
101-
- `/update` (WS): Recebimento contínuo e sincronização da janela de mensagens e usuários logados no formato `{"messages": [...], "users_in_chat": [...]}`.
102-
- `/get_key` (POST/GET): Handshake RSA recebendo um `.pem` public key.
214+
<details>
215+
<summary><strong>A criptografia RSA 512-bit é segura para produção?</strong></summary>
103216

104-
## Roadmap
105-
- [ ] Integração com banco de dados real (MongoDB ou SQLite) ao invés de memória
106-
- [ ] Configuração de canais customizados
107-
- [ ] Webhook de notificação
108-
- [ ] Adicionar testes E2E com `pytest-asyncio`
217+
RSA 512-bit é considerado inseguro para uso em produção — chaves desse tamanho podem ser fatoradas com recursos computacionais modernos. No contexto deste projeto educacional/demonstrativo, serve para ilustrar o conceito de criptografia híbrida. Para produção, use RSA 2048-bit ou superior (ou curvas elípticas).
218+
</details>
109219

110-
## Contribuindo
111-
Esteja livre para melhorar o projeto. Veja o [CONTRIBUTING.md](CONTRIBUTING.md) para detalhes.
220+
<details>
221+
<summary><strong>O chat persiste mensagens?</strong></summary>
112222

113-
## Autor
223+
Não. O armazenamento é totalmente in-memory no servidor Sanic. Ao encerrar o servidor, todas as mensagens e sessões são perdidas.
224+
</details>
114225

115-
**ESousa97**
226+
<details>
227+
<summary><strong>Posso usar sem Rich instalado?</strong></summary>
116228

117-
* [Portfólio](https://enoquesousa.vercel.app)
118-
* [GitHub](https://github.com/ESousa97)
229+
Sim. O cliente possui fallback para renderização padrão quando Rich não está disponível. A experiência é melhor com Rich (cores, formatação), mas funciona sem ela.
230+
</details>
231+
232+
<details>
233+
<summary><strong>Como funciona a autenticação?</strong></summary>
234+
235+
O servidor aceita uma senha via flag `-p` no `cmd_chat serve`. Clientes devem fornecer a mesma senha no `cmd_chat connect`. A validação ocorre na conexão WebSocket.
236+
</details>
237+
238+
---
119239

120240
## Licença
121-
Este repositório é licenciado através de [MIT](LICENSE).
241+
242+
Este projeto está sob a licença MIT. Veja o arquivo [LICENSE](LICENSE) para mais detalhes.
243+
244+
```
245+
MIT License - você pode usar, copiar, modificar e distribuir este código.
246+
```
247+
248+
---
249+
250+
## Contato
251+
252+
**José Enoque Costa de Sousa**
253+
254+
[![LinkedIn](https://img.shields.io/badge/LinkedIn-0077B5?style=flat&logo=linkedin&logoColor=white)](https://www.linkedin.com/in/enoque-sousa-bb89aa168/)
255+
[![GitHub](https://img.shields.io/badge/GitHub-100000?style=flat&logo=github&logoColor=white)](https://github.com/ESousa97)
256+
[![Portfolio](https://img.shields.io/badge/Portfolio-FF5722?style=flat&logo=todoist&logoColor=white)](https://enoquesousa.vercel.app)
257+
258+
---
259+
260+
<div align="center">
261+
262+
**[⬆ Voltar ao topo](#cmd-chat)**
263+
264+
Feito com ❤️ por [José Enoque](https://github.com/ESousa97)
265+
266+
**Status do Projeto:** Archived — Sem novas atualizações
267+
268+
</div>

0 commit comments

Comments
 (0)