> ## 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.

# Environment variables

> Deploy-time environment variables distinctive to Lerian SISBAJUD — the KMS and secret-store backends, S3-compatible object storage, the crypto lifecycle, the domain workers, and the Midaz ledger connector.

Lerian SISBAJUD is the Lerian-owned rail that fulfils judicial asset-blocking orders and protects the personal data they carry. These variables are set at deploy time and require a service restart to take effect. The universal backbone that every Lerian Go service shares — server, datastores, multi-tenancy, telemetry, plugin authentication, and licensing — is documented once in [BYOC configuration essentials](/en/reference/byoc-configuration); this page covers only the variables distinctive to Lerian SISBAJUD.

In the tables below, the **Default / Required** column shows the default value; a bold qualifier (e.g. **Required**, **Required if enabled**) marks variables that must be set. `—` means no default. Any variable flagged **Sensitive** carries credential or key material — inject it from your secret manager at deploy time and never commit a value.

## Service and runtime

| Variable              | Default / Required                     | Description                                                                                                                                                                                |
| --------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `SERVER_ADDRESS`      | `:4029`                                | Main HTTP listen address. The liveness, readiness, metrics, and version probes bind this same port.                                                                                        |
| `ENVIRONMENT_NAME`    | `staging`                              | Runtime environment: `staging` or `production`. Arms stricter security gates in `production`. `ENV_NAME` is accepted as an alternative name.                                               |
| `SYSTEMPLANE_ENABLED` | `false`                                | Enable the [Systemplane](/en/reference/systemplane/overview) runtime-configuration admin API under the `/system` prefix on the main port. Off by default (environment-variable-only mode). |
| `DEFAULT_TENANT_ID`   | `11111111-1111-1111-1111-111111111111` | Tenant UUID used in single-tenant mode. Here the tenant equals the institution. Must be a valid UUID.                                                                                      |

<Note>
  Lerian SISBAJUD exposes `/health` (liveness) and `/readyz` (readiness) on the main port, plus `/version` and `/metrics`, and — when multi-tenancy is enabled — `GET /readyz/tenant/{id}`. See [Health and readiness](/en/reference/health-and-readiness) for the probe contract.
</Note>

## Security backends

Both selectors are validated at boot; an unset or unsupported value fails the boot closed. They choose the backends that protect court-ordered seizure data.

| Variable                           | Default / Required     | Description                                                                                                                                                                                                                                                     |
| ---------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `KMS_PROVIDER`                     | `vault` · **Required** | Envelope-encryption key manager: `vault` (HashiCorp Vault Transit) or `aws` (cloud KMS). Read once at boot; not hot-reloadable. There is no in-memory provider.                                                                                                 |
| `SECRET_STORE_PROVIDER`            | `local` · **Required** | Where service secrets are read from: `vault` or `local`. `aws-secrets-manager` is a recognized value but a deferred (Phase-4) adapter that is not yet wired — selecting it fails the boot closed; use `vault` or `local` today.                                 |
| `CONNECTOR_CREDS_USE_SECRET_STORE` | `false`                | Resolve per-institution connector credentials from the secret store rather than from environment credentials. Only `vault` or `local` are wired for connector credentials today; enabling this with `SECRET_STORE_PROVIDER=aws-secrets-manager` fails the boot. |

<Note>
  Each selector pulls in its own companion block, all validated at boot: `vault` (for either selector) requires the Vault variables below; `KMS_PROVIDER=aws` uses the shared `AWS_REGION` (default `us-east-1`); `SECRET_STORE_PROVIDER=local` reads secrets from the environment and needs no external backend. The `aws-secrets-manager` adapter is deferred and not yet wired — selecting it (for ordinary service secrets or for connector credentials) fails the boot closed; use `vault` or `local`. `SECRET_STORE_PROVIDER` defaults to `local` when unset in non-production.
</Note>

### Vault (when `KMS_PROVIDER=vault` or `SECRET_STORE_PROVIDER=vault`)

| Variable                             | Default / Required                  | Description                                                                                       |
| ------------------------------------ | ----------------------------------- | ------------------------------------------------------------------------------------------------- |
| `VAULT_ADDR`                         | **Required for the Vault provider** | Address of the client's Vault.                                                                    |
| `VAULT_AUTH_METHOD`                  | `token`                             | Authentication method: `token` (static `VAULT_TOKEN`) or `approle` (AppRole role and secret ids). |
| `VAULT_TOKEN`                        | **Required if `token`**             | Service token for Vault. Sensitive.                                                               |
| `VAULT_APPROLE_ROLE_ID`              | **Required if `approle`**           | AppRole role id. Sensitive.                                                                       |
| `VAULT_APPROLE_SECRET_ID`            | **Required if `approle`**           | AppRole secret id. Sensitive.                                                                     |
| `VAULT_TRANSIT_MOUNT_PATH`           | `transit`                           | Mount path of the Transit engine used for envelope encryption.                                    |
| `VAULT_KV_MOUNT`                     | `sisbajud-secrets`                  | Mount path of the KV engine holding per-institution connector credentials.                        |
| `VAULT_TOKEN_RENEW_ENABLED`          | `true`                              | Run a background renewer that refreshes the Vault token before its lease lapses.                  |
| `VAULT_TOKEN_RENEW_MIN_INTERVAL_SEC` | `60`                                | Floor, in seconds, between renewal attempts.                                                      |
| `VAULT_TIMEOUT_SEC`                  | `15`                                | Per-request timeout, in seconds, for each Vault round-trip.                                       |

### AWS (when `KMS_PROVIDER=aws` or `SECRET_STORE_PROVIDER=aws-secrets-manager`)

| Variable           | Default / Required | Description                                                                                                                                                                                                                                 |
| ------------------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AWS_REGION`       | `us-east-1`        | Shared region for the AWS adapters — AWS KMS today, and the AWS secret-store once it is wired. Defaults to `us-east-1` when unset; set it explicitly to match your account's region. Credentials resolve through the default AWS SDK chain. |
| `AWS_ENDPOINT_URL` | —                  | AWS-compatible endpoint override. Leave unset in real AWS environments so the SDK uses its default endpoints.                                                                                                                               |

## Crypto lifecycle

Envelope encryption uses a per-record data key sealed under the institution's master key, plus a blind index for exact-match lookup on fiscal identifiers.

| Variable                           | Default / Required | Description                                                                                                                         |
| ---------------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `SISBAJUD_DEK_CACHE_TTL`           | `5m`               | Lifetime of an unwrapped data-encryption key in the in-memory cache before the KMS is asked to unwrap again. Go-duration string.    |
| `SISBAJUD_DEK_CACHE_MAX_ENTRIES`   | `50000`            | Ceiling on cached data-key primitives; bounds heap during a large batch decrypt.                                                    |
| `SISBAJUD_HMAC_COEXISTENCE_WINDOW` | `720h`             | Window during which blind-index hashes from the previous HMAC key version stay queryable across a key rotation. Go-duration string. |
| `KEK_REWRAP_BACKFILL_ENABLED`      | `false`            | Enable the background sweep that advances behind data-key rows to the active master-key version after a rotation.                   |
| `REHASH_BACKFILL_ENABLED`          | `false`            | Enable the background sweep that re-hashes trailing blind-index rows to the new primary HMAC key version.                           |

## Domain workers

Judicial-order processing runs as a set of per-institution background crons. Each is off by default and shares the `*_SCAN_INTERVAL` (seconds) and `*_BATCH_SIZE` cadence knobs.

| Variable                                     | Default / Required | Description                                                                                                                             |
| -------------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| `EXECUTION_ENABLED`                          | `false`            | Master switch for the order-execution engine. When off, the FIFO orchestrator and downstream dispatch stay dormant.                     |
| `ORCHESTRATOR_LOCK_TTL`                      | `30`               | Per-subject execution lock lease, in seconds.                                                                                           |
| `ORCHESTRATOR_RENEW_INTERVAL`                | `10`               | Cadence, in seconds, at which the owning worker renews the lock. Must stay strictly below `ORCHESTRATOR_LOCK_TTL` or boot fails closed. |
| `UNBLOCK_EXECUTION_SCAN_INTERVAL`            | `60`               | Pending-unblock sweep cadence in seconds. Shares the `EXECUTION_ENABLED` gate.                                                          |
| `UNBLOCK_EXECUTION_BATCH_SIZE`               | `500`              | Pending unblock orders processed per tenant pass.                                                                                       |
| `PERMANENT_BLOCK_EXPIRY_ENABLED`             | `false`            | Enable the daily scan that expires permanent blocks past their deadline.                                                                |
| `RECONCILIATION_ENABLED`                     | `false`            | Enable the scan that reconciles monitoring orders against the ledger and persists detected gaps.                                        |
| `RETURN_FILE_GENERATION_ENABLED`             | `false`            | Enable generation of SISBAJUD return files for unreturned terminal orders.                                                              |
| `INFORMATION_RETURN_FILE_GENERATION_ENABLED` | `false`            | Enable generation of AJUD309 information-response files.                                                                                |
| `SLA_ALERT_ENABLED`                          | `false`            | Enable the evaluator that classifies active orders by SLA-risk band and emits the bands as metrics.                                     |
| `RETURN_FILE_ENVIRONMENT`                    | `HOMOLOGATION`     | Regulatory environment stamped into generated return files.                                                                             |

## Object storage

Court-ordered seizure artifacts are written to an S3-compatible object store, already encrypted — the blob layer never sees plaintext.

| Variable                | Default / Required | Description                                                                   |
| ----------------------- | ------------------ | ----------------------------------------------------------------------------- |
| `SEAWEEDFS_S3_ENDPOINT` | **Required**       | Endpoint of the S3-compatible object store.                                   |
| `SEAWEEDFS_BUCKET`      | `sisbajud`         | Bucket for remittance and return artifacts (already encrypted).               |
| `SEAWEEDFS_REGION`      | `us-east-1`        | S3 region label required by the AWS SDK.                                      |
| `SEAWEEDFS_ACCESS_KEY`  | —                  | Object-store access key. Sensitive. Leave blank when the store needs no auth. |
| `SEAWEEDFS_SECRET_KEY`  | —                  | Object-store secret key. Sensitive. Leave blank when the store needs no auth. |
| `STA_INBOUND_BUCKET`    | `sta-files`        | Bucket holding the raw remittance objects a reception notification points at. |
| `STA_FILE_LOCK_TTL`     | `5`                | Per-file processing-lock TTL, in minutes.                                     |

## Midaz ledger connector

Lerian SISBAJUD reads balances and blocks through the Midaz ledger. `MIDAZ_BASE_URL` is required service-wide.

| Variable              | Default / Required      | Description                                                                                   |
| --------------------- | ----------------------- | --------------------------------------------------------------------------------------------- |
| `MIDAZ_BASE_URL`      | **Required**            | Base URL of the Midaz ledger. Boot fails closed without it.                                   |
| `MIDAZ_AUTH_ENABLED`  | `false`                 | Enable machine-to-machine authentication to Midaz.                                            |
| `MIDAZ_AUTH_ADDRESS`  | **Required if enabled** | Auth service address for minting Midaz tokens.                                                |
| `MIDAZ_CLIENT_ID`     | **Required if enabled** | OAuth client id for Midaz. Ignored in multi-tenant mode (resolved per tenant).                |
| `MIDAZ_CLIENT_SECRET` | **Required if enabled** | OAuth client secret for Midaz. Sensitive. Ignored in multi-tenant mode (resolved per tenant). |