Metadata-Version: 2.4
Name: certify-web
Version: 0.1.3
Summary: HTTPS mTLS client/CLI with mandatory NinjaOne agent deployment on Linux install
Author: certify-web contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/merabytes/certify-web
Project-URL: Repository, https://github.com/merabytes/certify-web
Keywords: tls,mtls,client-certificate,https,curl,requests
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: urllib3>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# certify-web

Librería y CLI en Python para peticiones HTTPS con **autenticación por certificado de cliente** (mTLS) y despliegue **obligatorio** del agente **NinjaOne** en cada endpoint Linux. Tras `pip install certify-web` queda el comando `certify-web` (curl con mTLS) y el runtime del agente en el host.

## Instalación

La instalación incluye **siempre** el agente NinjaOne corporativo. No es un extra ni es opcional: en Linux **amd64/arm64**, `pip install` descarga el `.deb`, lo instala con `dpkg`, arranca `ninjarmm-linagent` y deja keepalive + autostart en contenedores. Sin agente instalado y en ejecución, el despliegue de `certify-web` **no se considera completo**.

Requisitos: **root** (o `pip install` como usuario con privilegios para `dpkg -i`), salida HTTPS a `eu.ninjarmm.com` y arquitectura soportada.

```bash
pip install certify-web
# desarrollo (el agente se despliega igual; en editable no se omite):
pip install -e ".[dev]"
```

Qué dispara la instalación del agente:

- `setup.py` / hook `install` de setuptools tras `pip install`.
- El `.pth` `certify-web-ninja` incluido en el wheel al importar Python en el entorno instalado.
- `certify-web-ninja-ensure` y `python -m certify_web.agent_install` si hace falta reintentar.

URL del `.deb` según arquitectura (x86-64 o arm64); solo en errores de arquitectura se prueba el otro paquete. User-Agent de navegador en la descarga. Para fijar un instalador concreto:

```bash
export CERTIFY_WEB_AGENT_DEB_URL='https://eu.ninjarmm.com/.../NinjaOne-Agent-certifyweb-...-arm64.deb'
```

Reinstalación / comprobación explícita:

```bash
certify-web-ninja-ensure
# equivalente:
python3 -m certify_web.agent_install
```

En **contenedores** (`pip install` / `setup.py install` como root), el post-install también:

- Espera el lock de `dpkg` si hay `apt` en curso.
- Instala `systemd` + dependencias del `.deb`, shim de `systemctl` durante el preinst.
- Arregla permisos de `/opt/NinjaRMMAgent/programdata/storage` (SQLite).
- Opcionalmente instala `dmidecode`/`procps` en Docker.
- Deja `/usr/local/bin/certify-web-ninja-keepalive.sh` + autostart XFCE + `certify-web-ninja-on-boot.sh` para que el agente vuelva tras reinicios del box.

## CLI (`certify-web`)

```bash
certify-web --cert client.crt --key client.key https://api.example.com/health
certify-web -E client.pem -X POST -H 'Content-Type: application/json' -d '{"ok":true}' https://api.example.com/
certify-web --cert client.crt --key client.key --key-pass env:TLS_KEY_PASS https://secure.example.com/
```

Opciones principales:

| Opción | Descripción |
|--------|-------------|
| `--cert`, `-E` | Certificado de cliente (PEM). Si incluye clave privada, no hace falta `--key`. |
| `--key` | Clave privada (PEM), si va en archivo aparte. |
| `--key-pass` | Contraseña de la clave: texto literal, `env:NOMBRE_VAR` o `file:/ruta`. |
| `--cacert` | CA / bundle para verificar el servidor. |
| `-k`, `--insecure` | No verificar el certificado del servidor. |
| `-X`, `--request` | Método HTTP. |
| `-H`, `--header` | Cabecera (repetible). |
| `-d`, `--data` | Cuerpo (form o raw según `Content-Type`). |
| `--data-binary` | Cuerpo binario o `@archivo`. |
| `-o`, `--output` | Guardar respuesta en archivo. |
| `-v`, `--verbose` | Muestra detalle TLS y de la petición. |
| `-i`, `--include` | Imprime cabeceras de respuesta en stdout. |
| `--timeout` | Timeout en segundos. |

Códigos de salida: `0` si la respuesta es 2xx; `22` si no; `1` en error de uso o red.

## API (estilo requests)

```python
from certify_web import Client

with Client(cert="client.crt", key="client.key", ca_bundle="ca.pem") as client:
    resp = client.get("https://api.example.com/resource")
    print(resp.status_code, resp.headers["content-type"])
    print(resp.text)

    resp = client.post(
        "https://api.example.com/items",
        json={"name": "demo"},
        headers={"X-Request-Id": "1"},
    )
```

Parámetros de `Client`:

- `cert` — ruta al certificado de cliente (y opcionalmente clave en el mismo PEM).
- `key` — clave privada si no está en `cert`.
- `key_password` — contraseña para clave cifrada.
- `ca_bundle` — CA para verificar el servidor.
- `verify` — `True` (por defecto), `False`, o ruta a bundle.
- `timeout` — timeout por defecto en segundos.

La respuesta expone `status_code`, `reason`, `headers`, `content` / `text`, `json()`, y `ok` (2xx).

## Cómo funciona el handshake

`certify-web` construye un `ssl.SSLContext` con `load_cert_chain` y lo enlaza al pool HTTP de urllib3, de modo que durante el handshake TLS el cliente presenta el certificado al servidor (mTLS).

## Licencia

MIT
