> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Variables de entorno
> Variables de entorno de despliegue de Lerian SISBAJUD: KMS y almacén de secretos, almacenamiento S3, ciclo cripto, workers de dominio y conector Midaz.
Lerian SISBAJUD es el rail propiedad de Lerian que cumple las órdenes judiciales de bloqueo de activos y protege los datos personales que estas contienen. Defines estas variables en el momento del despliegue. Solo surten efecto tras reiniciar el servicio. La [referencia de configuración BYOC](/es/reference/byoc-configuration) documenta el backbone universal que comparte cada servicio Go de Lerian: servidor, almacenes de datos, multi-tenancy, telemetría, autenticación de plugins y licenciamiento. Esta página cubre solo las variables distintivas de Lerian SISBAJUD.
En las tablas siguientes, la columna **Valor por defecto / Requerida** muestra el valor por defecto. Un calificador en negrita (por ejemplo **Requerida** o **Requerida si está habilitada**) marca las variables que debes definir. `—` significa que no hay valor por defecto. Cualquier variable marcada como **Sensible** contiene material de credenciales o claves. Inyéctala desde tu gestor de secretos en el momento del despliegue. Nunca guardes un valor en el repositorio.
## Servicio y runtime
| Variable | Valor por defecto / Requerida | Descripción |
| --------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SERVER_ADDRESS` | — | Dirección de escucha HTTP principal; sin valor por defecto en el código, así que defínela explícitamente (el despliegue de referencia usa `:4029`). Las sondas de liveness, readiness, métricas y versión se enlazan a este mismo puerto. |
| `ENVIRONMENT_NAME` | — | Entorno de runtime: `local`, `development`, `staging`, `e2e`, `test` o `production`. `ENV_NAME` se acepta como nombre alternativo. Si no se define queda vacío y se trata como si fuera producción, así que los controles de seguridad más estrictos se activan de forma cerrada. |
| `SYSTEMPLANE_ENABLED` | `false` | Habilita la API de administración de configuración en tiempo de ejecución de [Systemplane](/es/reference/systemplane/overview) bajo el prefijo `/system` en el puerto principal. Desactivada por defecto (modo solo variables de entorno). |
| `DEFAULT_TENANT_ID` | **Requerida en modo single-tenant** | UUID del tenant usado en modo single-tenant. No hay un valor por defecto de cadena efectivo: define explícitamente un UUID válido para una operación single-tenant utilizable. El tenant es la frontera de aislamiento de base de datos y puede contener varias instituciones; cada institución se enruta por su propio identificador dentro del tenant. Con la autenticación desactivada, el riel también usa este UUID como respaldo de su única institución configurada. |
Lerian SISBAJUD expone `/health` (liveness), `/readyz` (readiness), `/version` y `/metrics` en el puerto principal. Cuando habilitas la multi-tenancy, también expone `GET /readyz/tenant/{id}`. Consulta [Salud y readiness](/es/reference/health-and-readiness) para el contrato de las sondas.
## Backends de seguridad
El servicio valida ambos selectores al arrancar. Eligen los backends que protegen los datos de embargo ordenados por la justicia. En producción, un valor sin definir o no soportado falla el arranque de forma cerrada. Fuera de producción, los selectores tienen `vault` y `local` como valores por defecto.
| Variable | Valor por defecto / Requerida | Descripción |
| ------------------------ | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `KMS_PROVIDER` | `vault` (fuera de producción) · **Requerida en producción** | Gestor de claves de cifrado de sobre: `vault` (HashiCorp Vault Transit) o `aws` (KMS en la nube). Se lee una vez al arrancar; no es recargable en caliente. No hay proveedor en memoria. |
| `SECRET_STORE_PROVIDER` | `local` (fuera de producción) · **Requerida en producción** | De dónde se leen los secretos del servicio: `vault` o `local`. `local` es solo para desarrollo — un arranque en producción lo rechaza, así que producción significa `vault`. `aws-secrets-manager` pasa la validación pero su backend aún no está cableado; seleccionarlo falla el arranque de forma cerrada. |
| `CONNECTOR_CREDS_SOURCE` | `env` | De dónde resuelve y registra el conector las credenciales de Midaz por institución: `env` mantiene el comportamiento heredado de credenciales de entorno; `kek-db` enruta la resolución y el registro por el almacén de sobre KEK por institución en Postgres. Sin definir se resuelve a `env`; cualquier otro valor falla el arranque de forma cerrada. `kek-db` requiere el backend de cifrado de sobre (KMS), o el arranque falla de forma cerrada. |
`KMS_PROVIDER` y `SECRET_STORE_PROVIDER` arrastran cada uno un bloque de acompañamiento, y el servicio valida cada bloque al arrancar. `CONNECTOR_CREDS_SOURCE` no tiene un bloque propio — `kek-db` se apoya en el backend KMS que seleccione `KMS_PROVIDER`. El valor `vault`, para cualquiera de los selectores, requiere las variables de Vault de abajo. `KMS_PROVIDER=aws` requiere la `AWS_REGION` compartida. `SECRET_STORE_PROVIDER=local` lee los secretos del entorno y no necesita ningún backend externo. El backend `aws-secrets-manager` aún no está cableado; seleccionarlo falla el arranque de forma cerrada. Las credenciales de conector por institución ya no pasan por el almacén de secretos: `CONNECTOR_CREDS_SOURCE=kek-db` las resuelve y registra en el almacén de sobre KEK en Postgres, bajo el backend KMS. `KMS_PROVIDER` es `vault` por defecto cuando no se define fuera de producción. En producción, debes definirlo explícitamente o el arranque falla de forma cerrada. `SECRET_STORE_PROVIDER` es `local` por defecto del mismo modo. En producción, también debes definirlo explícitamente.
### Vault (cuando `KMS_PROVIDER=vault` o `SECRET_STORE_PROVIDER=vault`)
| Variable | Valor por defecto / Requerida | Descripción |
| ------------------------------------ | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `VAULT_ADDR` | **Requerida para el proveedor Vault** | Dirección del Vault del cliente. |
| `VAULT_AUTH_METHOD` | `token` | Método de autenticación: `token` (`VAULT_TOKEN` estático) o `approle` (role id y secret id de AppRole). |
| `VAULT_TOKEN` | **Requerida si `token`, en producción** | Token de servicio para Vault. Sensible. Fuera de producción recurre a un token de desarrollo. |
| `VAULT_APPROLE_ROLE_ID` | **Requerida si `approle`** | Role id de AppRole. Sensible. |
| `VAULT_APPROLE_SECRET_ID` | **Requerida si `approle`** | Secret id de AppRole. Sensible. |
| `VAULT_TRANSIT_MOUNT_PATH` | `transit` | Ruta de montaje del motor Transit usado para el cifrado de sobre. |
| `VAULT_KV_MOUNT` | `sisbajud-secrets` | Ruta de montaje del motor KV v2 que respalda el almacén de secretos genérico cuando `SECRET_STORE_PROVIDER=vault`. Las credenciales de conector por institución ya no se leen de él — siguen `CONNECTOR_CREDS_SOURCE`. |
| `VAULT_TOKEN_RENEW_ENABLED` | `true` | Ejecuta un renovador en segundo plano que refresca el token de Vault antes de que caduque su lease. |
| `VAULT_TOKEN_RENEW_MIN_INTERVAL_SEC` | `60` | Piso, en segundos, entre intentos de renovación. |
| `VAULT_TIMEOUT_SEC` | `15` | Tiempo de espera por petición, en segundos, para cada ida y vuelta a Vault. |
### AWS (cuando `KMS_PROVIDER=aws` o `SECRET_STORE_PROVIDER=aws-secrets-manager`)
| Variable | Valor por defecto / Requerida | Descripción |
| ------------------ | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AWS_REGION` | **Requerida con `KMS_PROVIDER=aws`** | Región compartida para los adaptadores de AWS: AWS KMS hoy, y el almacén de secretos de AWS cuando esté cableado. El arranque falla de forma cerrada cuando `KMS_PROVIDER=aws` y está en blanco. Las credenciales se resuelven a través de la cadena por defecto del AWS SDK. |
| `AWS_ENDPOINT_URL` | — | Sobrescritura de endpoint compatible con AWS. Déjala sin definir en entornos AWS reales para que el SDK use sus endpoints por defecto. |
## Ciclo de vida criptográfico
El cifrado de sobre usa una clave de datos por registro sellada bajo la clave maestra de la institución, más un índice ciego para la búsqueda de coincidencia exacta sobre los identificadores fiscales.
| Variable | Valor por defecto / Requerida | Descripción |
| ---------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `SISBAJUD_DEK_CACHE_TTL` | `5m` | Duración de una clave de cifrado de datos desenvuelta en la caché en memoria antes de volver a pedir al KMS que la desenvuelva. Cadena de duración de Go. |
| `SISBAJUD_DEK_CACHE_MAX_ENTRIES` | `50000` | Techo de las primitivas de clave de datos en caché; acota el heap durante un descifrado por lotes grande. |
| `SISBAJUD_HMAC_COEXISTENCE_WINDOW` | `720h` | Ventana durante la cual los hashes de índice ciego de la versión anterior de clave HMAC siguen siendo consultables tras una rotación de clave. Cadena de duración de Go. |
| `KEK_REWRAP_BACKFILL_ENABLED` | `false` | Habilita el barrido en segundo plano que avanza las filas de clave de datos rezagadas a la versión de clave maestra activa tras una rotación. |
| `REHASH_BACKFILL_ENABLED` | `false` | Habilita el barrido en segundo plano que rehashea las filas de índice ciego rezagadas a la nueva versión de clave HMAC primaria. |
## Workers de dominio
El procesamiento de órdenes judiciales se ejecuta como un conjunto de crons en segundo plano por institución. Todos están desactivados por defecto excepto el recolector de locks de procesamiento, que se ejecuta por defecto. Los workers usan los ajustes de cadencia `*_SCAN_INTERVAL` (segundos) y `*_BATCH_SIZE` cuando corresponde.
| Variable | Valor por defecto / Requerida | Descripción |
| -------------------------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `EXECUTION_ENABLED` | `false` | Interruptor maestro del motor de ejecución de órdenes. Cuando está desactivado, el orquestador FIFO y el despacho posterior permanecen inactivos. |
| `ORCHESTRATOR_LOCK_TTL` | `30` | Lease del lock de ejecución por sujeto, en segundos. |
| `ORCHESTRATOR_RENEW_INTERVAL` | `10` | Cadencia, en segundos, a la que el worker propietario renueva el lock. Debe mantenerse estrictamente por debajo de `ORCHESTRATOR_LOCK_TTL` o el arranque falla de forma cerrada. |
| `PROCESSING_LOCK_REAPER_ENABLED` | `true` | Activa el recolector en segundo plano que elimina las filas de locks de procesamiento vencidos de cada tenant. |
| `PROCESSING_LOCK_REAPER_INTERVAL_SEC` | `300` | Cadencia, en segundos, del barrido del recolector. Si esta variable no se define o no es positiva, el servicio usa 300 segundos. |
| `UNBLOCK_EXECUTION_SCAN_INTERVAL` | `60` | Cadencia del barrido de desbloqueos pendientes en segundos. Comparte el control `EXECUTION_ENABLED`. |
| `UNBLOCK_EXECUTION_BATCH_SIZE` | `500` | Órdenes de desbloqueo pendientes procesadas por pasada de tenant. |
| `PERMANENT_BLOCK_EXPIRY_ENABLED` | `false` | Habilita el escaneo diario que expira los bloqueos permanentes vencidos. |
| `RECONCILIATION_ENABLED` | `false` | Habilita el escaneo que reconcilia las órdenes de monitoreo contra el ledger y persiste las brechas detectadas. |
| `RETURN_FILE_GENERATION_ENABLED` | `false` | Habilita la generación de archivos de devolución SISBAJUD para las órdenes terminales no devueltas. |
| `INFORMATION_RETURN_FILE_GENERATION_ENABLED` | `false` | Habilita la generación de archivos de respuesta de información AJUD309. |
| `SLA_ALERT_ENABLED` | `false` | Habilita el evaluador que clasifica las órdenes activas por banda de riesgo de SLA y emite las bandas como métricas. |
| `RETURN_FILE_ENVIRONMENT` | `HOMOLOGATION` | Entorno regulatorio estampado en los archivos de devolución generados. |
## Almacenamiento de objetos
Lerian SISBAJUD escribe los artefactos de embargo ordenados por la justicia en un almacén de objetos compatible con S3, ya cifrados. La capa de blobs nunca ve texto en claro.
| Variable | Valor por defecto / Requerida | Descripción |
| ----------------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SEAWEEDFS_S3_ENDPOINT` | `http://localhost:8333` | Endpoint del almacén de objetos compatible con S3. Las fallas de cableado del almacenamiento no son fatales: el servicio arranca y la sonda de readiness reporta el almacén como no disponible. |
| `SEAWEEDFS_BUCKET` | `sisbajud` | Bucket para los artefactos de remesa y devolución (ya cifrados). |
| `SEAWEEDFS_REGION` | `us-east-1` | Etiqueta de región S3 requerida por el AWS SDK. |
| `SEAWEEDFS_ACCESS_KEY` | — | Clave de acceso del almacén de objetos. Sensible. Déjala en blanco cuando el almacén no necesite autenticación. |
| `SEAWEEDFS_SECRET_KEY` | — | Clave secreta del almacén de objetos. Sensible. Déjala en blanco cuando el almacén no necesite autenticación. |
| `STA_INBOUND_BUCKET` | `sta-files` | Bucket que contiene los objetos de remesa en bruto a los que apunta una notificación de recepción. |
| `STA_FILE_LOCK_TTL` | `5` | TTL del lock de procesamiento por archivo, en minutos. |
## Conector del ledger Midaz
Lerian SISBAJUD lee saldos y bloqueos a través del ledger Midaz. `MIDAZ_BASE_URL` es un fallback opcional para todo el servicio; los metadatos del conector por institución tienen precedencia.
| Variable | Valor por defecto / Requerida | Descripción |
| --------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MIDAZ_BASE_URL` | — (fallback opcional) | URL base del ledger Midaz. Se usa solo cuando los metadatos por institución no proporcionan una URL. La resolución del conector falla de forma cerrada solo si ninguno proporciona una URL. |
| `MIDAZ_AUTH_ENABLED` | `false` | Habilita la autenticación máquina a máquina hacia Midaz. |
| `MIDAZ_AUTH_ADDRESS` | **Requerida si está habilitada** | Dirección del servicio de autenticación para acuñar tokens de Midaz. |
| `MIDAZ_CLIENT_ID` | **Requerida si está habilitada** | Client id de OAuth para Midaz. Se ignora en modo multi-tenant (se resuelve por tenant). |
| `MIDAZ_CLIENT_SECRET` | **Requerida si está habilitada** | Client secret de OAuth para Midaz. Sensible. Se ignora en modo multi-tenant (se resuelve por tenant). |