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

> Multi-tenant isolation and per-tenant pollers, BACEN credential management and three-phase password rotation, password-expiry and trust-store health monitoring, protocol TTL and inbound retention, and the reconciliation grain behind Lerian STA.

Lerian STA runs against the operational realities of BACEN's file hub: per-institution credentials that expire, a trust chain that must stay valid, and a protocol-create step that BACEN does not make idempotent. It manages each under multi-tenant isolation and reconciles at the grain of the BACEN protocol number.

## Multi-tenancy and pollers

***

Lerian STA is multi-tenant with **physical database-per-tenant isolation** — each tenant's data lives in its own database, with no shared tenant column on rows. Per-tenant **pollers** are provisioned on a roughly one-minute resync. Outbound status polling **self-enqueues** with a state-keyed backoff, and traffic to BACEN respects per-credential ceilings: command operations are capped at roughly 10 per minute per credential (shared with rotation), while status polling scales dynamically up to roughly 100 per minute.

## Credentials

***

Each credential is a BACEN **operator password**, identified by **institution code and operator ID**. It is stored **encrypted** (envelope encryption) and is never returned or logged. 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, the credential is **locked in an error state** for a manual reset.

## Password-expiry monitoring

***

BACEN enforces periodic password changes. Lerian STA tracks each credential's **BACEN-reported expiry** through a read-through cache and projects a **health band** — healthy, warning, critical, or expired — with the days remaining, so an operator rotates before the operator is locked out at BACEN.

## Trust store

***

Each tenant uploads the **X.509 root certificates** Lerian STA trusts when establishing mutual TLS to BACEN. Lerian STA parses the PEM, records each certificate's **fingerprint and validity window**, and reports a per-certificate expiry status plus a **pool summary** — total, expiring-soon, and expired. The **expiring-soon window** defaults to **30 days** and is operator-tunable with hot reload, so roots are renewed before the TLS trust chain breaks.

## Retention and protocol TTL

***

* **Outbound protocol TTL** — each outbound protocol has a bounded wall-clock lifetime (44 hours by default) to finish uploading before BACEN expires it.
* **Inbound retention** — each inbound source configuration sets how long its downloaded artefacts are retained: 365 days by default, configurable from 1 to 3,650 days.

## Reconciliation and contingency

***

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

BACEN offers **no idempotent protocol-create**: re-creating a protocol would duplicate the file at BACEN. So if Lerian STA fails between creating a protocol at BACEN and persisting it locally, the transfer is parked in a **local-only state that requires an operator to resolve it** — never silently retried.