Metadata-Version: 2.4
Name: itvalleysecurity
Version: 0.1.0
Summary: SDK de segurança JWT plug-and-play (Header ou HttpOnly Cookie)
Home-page: https://github.com/itvalley/itvalleysecurity
Author: IT Valley School
Author-email: Carlos Viana <contato@itvalley.com.br>
Maintainer-email: IT Valley School <contato@itvalley.com.br>
License: MIT
Project-URL: Homepage, https://github.com/itvalley/itvalleysecurity
Project-URL: Documentation, https://github.com/itvalley/itvalleysecurity#readme
Project-URL: Repository, https://github.com/itvalley/itvalleysecurity.git
Project-URL: Bug Tracker, https://github.com/itvalley/itvalleysecurity/issues
Project-URL: Changelog, https://github.com/itvalley/itvalleysecurity/blob/main/CHANGELOG.md
Keywords: jwt,authentication,fastapi,security,token,oauth,bearer,cookie
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Framework :: FastAPI
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyJWT<3,>=2.9.0
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: fastapi>=0.111
Requires-Dist: pydantic[email]>=2.0
Provides-Extra: tests
Requires-Dist: pytest>=8; extra == "tests"
Requires-Dist: pytest-cov; extra == "tests"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Dynamic: license-file

'''
# ITValleySecurity – Documentação Rápida

Um SDK de autenticação JWT plug-and-play para APIs Python, projetado para ser **extremamente fácil de usar**. Funciona com Header Bearer ou Cookie HttpOnly, sem que você precise escrever a lógica de JWT.

O SDK carrega automaticamente as configurações de um arquivo `.env`, então você **não precisa** chamar `load_dotenv()` no seu código.

## 1. Instalação

Instalação super simples - tudo incluído:

```bash
pip install itvalleysecurity
```

Pronto! O FastAPI e todas as dependências já vêm junto automaticamente.

## 2. Configuração de Ambiente

Crie um arquivo `.env` na raiz do seu projeto. A única variável **obrigatória** é a `JWT_SECRET_KEY`.

```env
# OBRIGATÓRIO: Chave secreta com pelo menos 32 caracteres
JWT_SECRET_KEY=uma_chave_bem_grande_e_segura_com_mais_de_32_caracteres

# --- Opcionais (possuem valores padrão seguros) ---
JWT_ALGORITHM=HS256
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=15
JWT_REFRESH_TOKEN_EXPIRE_DAYS=7
JWT_ISSUER=ITValley

# Origem do token: auto (padrão), bearer, ou cookie
EV_TOKEN_SOURCE=auto

# Política de validação do 'sub': any (padrão), email, ou uuid
EV_SUB_POLICY=any
```

> **Importante**: Se a `JWT_SECRET_KEY` não for definida, o SDK lançará um erro `ValueError` imediatamente para garantir que a aplicação não rode com uma configuração insegura.

## 3. Exemplo de Uso (FastAPI)

Este é um exemplo realista para um endpoint de login. O SDK cuida da emissão dos tokens e cookies; você só precisa focar na lógica de negócio (validar o usuário).

```python
from fastapi import FastAPI, Response, HTTPException, status, Depends
from itvalleysecurity.fastapi import login_response, require_access
from itvalleysecurity.fastapi.payloads import LoginPayloadWithPassword

# --- Lógica da sua aplicação (exemplo) ---

def get_user_from_db(username: str):
    # Implemente a busca do usuário no seu banco de dados
    pass

def verify_password(plain_password: str, hashed_password: str) -> bool:
    # Implemente a validação da senha (ex: com passlib)
    return True

# --- Aplicação FastAPI ---

app = FastAPI()

@app.post("/login")
def login(body: LoginPayloadWithPassword, resp: Response):
    # 1. Buscar usuário no banco
    user = get_user_from_db(body.sub)
    if not user or not verify_password(body.password, user.password_hash):
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Usuário ou senha inválidos"
        )

    # 2. (Opcional) Validar regras de negócio
    if user.status != "active":
        raise HTTPException(status_code=403, detail="Usuário inativo")

    # 3. Emitir tokens (o SDK faz o resto)
    return login_response(
        resp,
        sub=user.id, # ou user.email
        email=user.email,
        set_cookies=True
    )

# Rota protegida: basta adicionar a dependência
@app.get("/profile")
def get_profile(current_user = Depends(require_access)):
    return {
        "message": f"Bem-vindo, {current_user['sub']}!",
        "user_details": current_user
    }

```

## 4. Funções do Core (Uso sem FastAPI)

Você também pode usar o núcleo do SDK para gerar e validar tokens em qualquer aplicação Python.

```python
from itvalleysecurity import issue_pair, verify_access

# Criar um par de tokens
pair = issue_pair(sub="user_id_123", email="user@example.com")
print("Access Token:", pair["access_token"])

# Validar um token de acesso
try:
    claims = verify_access(pair["access_token"])
    print("Token válido! Sub:", claims["sub"])
except InvalidToken as e:
    print("Token inválido:", e)
```

Com isso, a segurança da sua API se torna simples e robusta. Basta configurar o `.env` uma vez e usar `Depends(require_access)` nas suas rotas.
'''
