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

# Operating Lerian STA

> Operating Lerian STA: optional database-per-tenant isolation, BACEN operator credentials, three-phase password rotation, and protocol reconciliation.

Three realities of BACEN's file hub shape Lerian STA. Per-institution credentials expire, each outbound protocol has a bounded lifetime, and BACEN does not make the protocol-create step idempotent. Lerian STA manages each one under its selected tenancy mode. It reconciles at the grain of the BACEN protocol number.

## Multi-tenancy and pollers

***

Lerian STA supports two tenancy modes. When multi-tenancy is enabled, each tenant's data lives in its own physically isolated database, with no shared tenant column on rows, and STA provisions per-tenant **pollers** on a roughly one-minute resync. In single-tenant mode, it uses the default database/pool with no tenant context. Outbound status polling **self-enqueues** with a state-keyed backoff.

Traffic to BACEN respects per-credential ceilings. Command operations reach roughly 10 per minute per credential, a budget shared with rotation. Status polling scales dynamically up to roughly 100 per minute.

## Credentials

***

Each credential is a BACEN **operator password**. Lerian STA identifies it by **institution code and operator ID**. Lerian STA stores it **encrypted** with envelope encryption, and never returns or logs it. Operators can **create**, **test connectivity for**, **rotate**, and **revoke** a credential.

## Password rotation

***

Rotation is a **three-phase** protocol, so a mid-flight failure never loses authentication:

1. **Stage** the new password locally.
2. **Change** it at BACEN.
3. **Promote** it locally.

A **recovery worker** resolves in-flight rotations. If BACEN accepts neither the old nor the new password, Lerian STA locks the credential in an error state for a manual credential reset.

## Password-expiry monitoring

***

BACEN enforces periodic password changes. Lerian STA tracks each credential's **BACEN-reported expiry** through a read-through cache. It projects a **health band** (healthy, warning, critical, or expired) with the days remaining. An operator can then rotate the password before BACEN locks the operator out.

## Retention and protocol TTL

***

* **Outbound protocol TTL.** Each outbound protocol has a bounded wall-clock lifetime to finish the upload before BACEN expires it. The default is 44 hours.
* **Inbound retention.** Each inbound source configuration sets how long Lerian STA keeps its downloaded files. The default is 365 days, tunable from 1 to 3,650 days.

## Reconciliation and contingency

***

Lerian STA reconciles at the grain of **one transfer per BACEN protocol number**. On discovery, the protocol number is the **idempotency key**, so Lerian STA never processes a file twice.

BACEN offers **no idempotent protocol-create**. A second create would duplicate the file at BACEN. So Lerian STA can fail after it creates a protocol at BACEN but before it persists the protocol locally. If this happens, Lerian STA parks the transfer in a **local-only state**, and an operator must resolve it. Lerian STA never retries it silently.