paste.es/README.md

# paste.es — Compartición de secretos cifrados

Servicio de compartición de secretos efímeros y cifrados para el público hispanohablante, alojado y patrocinado por [cloudhost.es](https://cloudhost.es).

> Basado en [Hemmelig](https://github.com/HemmeligOrg/Hemmelig.app) v7 — arquitectura de cifrado de conocimiento cero.

---

## Cómo funciona

1. Escribe tu secreto en [paste.es](https://paste.es)
2. Configura la expiración, límite de vistas y contraseña opcional
3. Comparte el enlace generado con el destinatario
4. El secreto se elimina automáticamente tras ser leído o al expirar

**Arquitectura de conocimiento cero:** Todo el cifrado ocurre en tu navegador. El servidor solo almacena datos cifrados y nunca ve tus secretos ni las claves de descifrado. Los datos son completamente efímeros.

---

## Características

- **Cifrado AES-256-GCM del lado del cliente** — tus datos se cifran antes de salir del navegador
- **Secretos autodestructivos** — expiración configurable y límite de vistas
- **Sin recopilación de datos** — sin analíticas, sin registros de IP, sin rastreo
- **Protección por contraseña** — capa de seguridad adicional opcional
- **Restricción por IP** — limita el acceso a rangos de IP específicos
- **Subida de archivos** — comparte archivos cifrados (usuarios autenticados)
- **Editor de texto enriquecido** — da formato a tus secretos
- **Códigos QR** — compartición fácil desde móvil
- **Soporte multiidioma** — interfaz disponible en 10 idiomas (español por defecto)
- **Notificaciones webhook** — recibe notificaciones cuando se ven o eliminan secretos

---

## Inicio rápido

### Docker Compose — imagen desde el registro (recomendado en producción)

Cada push a `main` construye y publica automáticamente la imagen en el registro de contenedores de Gitea. En el servidor de producción solo necesitas hacer pull:

```bash
git clone https://devops.cloudhost.es/Malin/paste.es.git
cd paste.es

# Autentícate en el registro de Gitea
docker login devops.cloudhost.es

# Copia y edita el fichero de entorno
cp .env.example .env

# Descarga la imagen y arranca
docker compose pull
docker compose up -d
```

Para actualizar a la última versión:

```bash
docker compose pull && docker compose up -d
```

### Docker Compose — compilación local (desarrollo)

```bash
git clone https://devops.cloudhost.es/Malin/paste.es.git
cd paste.es
cp .env.example .env

docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build
```

El servicio quedará disponible en `http://localhost:3000`.

---

## Configuración

Copia `.env.example` a `.env` y ajusta los valores:

```bash
cp .env.example .env
```

### Variables requeridas

| Variable             | Descripción                                          |
|----------------------|------------------------------------------------------|
| `DATABASE_URL`       | Ruta a la base de datos SQLite                       |
| `BETTER_AUTH_SECRET` | Clave secreta para las sesiones (mín. 32 caracteres) |
| `BETTER_AUTH_URL`    | URL pública de tu instancia                          |

### Generar secretos seguros

```bash
openssl rand -base64 32
```

Consulta [docs/env.md](docs/env.md) para la referencia completa de variables de entorno.

---

## Desarrollo local

```bash
# Instalar dependencias
npm install

# Iniciar el servidor de desarrollo (API + cliente en terminales separadas)
npm run dev:api   # Terminal 1 — API en :3000
npm run dev       # Terminal 2 — cliente Vite con HMR
```

---

## CI/CD — Gitea Actions + registro de contenedores

El repositorio incluye un pipeline en `.gitea/workflows/docker.yml` que:

1. Se activa en cada push a `main` (o manualmente desde la UI de Gitea)
2. Construye la imagen Docker con caché de capas
3. La publica en el registro de contenedores de Gitea como `devops.cloudhost.es/malin/paste.es:latest` y `devops.cloudhost.es/malin/paste.es:<sha>`

### Requisitos previos

**1. Habilitar Gitea Actions** en el repositorio:
> Settings → Actions → Enable repository actions

**2. Arrancar un act_runner** (ejecutor del pipeline). Obtén el token en:
> Settings → Actions → Runners → Create Runner Token

Añádelo a `.env` y arranca el runner:

```bash
# En .env:
RUNNER_REGISTRATION_TOKEN=<token>

docker compose -f docker-compose.runner.yml up -d
```

El runner se registra automáticamente y queda disponible para ejecutar workflows.

**3. El siguiente push a `main`** disparará la build automáticamente. Puedes seguirla en:
> Gitea → Actions → Workflows

---

## Despliegue en producción

### Detrás de un proxy inverso (Nginx / Caddy)

El servicio escucha en el puerto `3000`. Configura tu proxy para que apunte a él:

**Nginx:**
```nginx
server {
    listen 443 ssl;
    server_name paste.es;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

**Caddy:**
```caddyfile
paste.es {
    reverse_proxy localhost:3000
}
```

### Primer uso — crear cuenta de administrador

Tras el primer arranque, visita `https://paste.es/setup` para crear la cuenta de administrador y configurar la instancia.

---

## Documentación

- [Variables de entorno](docs/env.md) — referencia completa de configuración
- [Docker](docs/docker.md) — guía de despliegue con Docker
- [Helm / Kubernetes](docs/helm.md) — despliegue con Helm
- [Cifrado](docs/encryption.md) — cómo funciona el cifrado del lado del cliente
- [Login social](docs/social-login.md) — configuración de OAuth (GitHub, Google, etc.)
- [Peticiones de secretos](docs/secret-request.md) — solicita secretos a otros de forma segura
- [Webhooks](docs/webhook.md) — notificaciones de eventos
- [Health checks](docs/health.md) — sondas de disponibilidad para orquestación
- [Métricas Prometheus](docs/metrics.md) — monitorización con Prometheus
- [API REST](docs/api.md) — referencia de la API y especificación OpenAPI
- [CLI](docs/cli.md) — interfaz de línea de comandos para automatización
- [Tests E2E](docs/e2e.md) — pruebas end-to-end con Playwright

---

## Alojamiento y patrocinio

paste.es está alojado y patrocinado por **[CloudHost.es](https://cloudhost.es)**, empresa española de alojamiento web comprometida con la privacidad y la seguridad de los datos.

---

## Créditos

paste.es está basado en [Hemmelig](https://github.com/HemmeligOrg/Hemmelig.app) por Bjarne Øverli, publicado bajo la O'Saasy License Agreement. Consulta [LICENSE](LICENSE) para más detalles.