Finnest Power

Appearance

Glossary — Finnest Power ​

Brazilian regulatory + Finnest internal terminology. Sorted alphabetically.

Regulators ​

  • BCB — Banco Central do Brasil. Regulator for Open Finance Brasil (OFB). Owns the participant directory, issues normative resolutions, operates the certification pipeline.
  • SUSEP — Superintendência de Seguros Privados. Regulator for Open Insurance Brasil (OPIN). Owns the OPIN participant directory and publishes per-family API specs.

Programs ​

  • OFB / Open Finance Brasil — the Central Bank's open data + open services program. Phases 1 (open data), 2 (customer/account data), 3 (transactional data), 4 (payment initiation). Use OFB as the canonical internal acronym in code, docs, routes, commands, and admin surfaces. OPF and internal OPB names are terminology drift unless they refer to a specific external source or legacy "Open Banking Brasil" artifact. See packages/banking/ARCHITECTURE.md.
  • OPIN / Open Insurance Brasil — the SUSEP equivalent for insurance. Phases 1 (open data), 2 (consent + holder reads), 3 (service initiation). No payment phase. See packages/insurance/ARCHITECTURE.md.

Roles in the regulator ecosystem ​

  • Holder (provider) — the institution that owns the customer relationship and exposes the customer's data and command APIs to other participants. Finnest plays this role for insurer / bank customers.
  • Receiver / TPP — Third-Party Provider. The institution that calls upstream providers on behalf of an end customer to read data or drive consents. Finnest plays this role for fintech customers.
  • Initiator / PISP — Payment Initiation Service Provider. OFB-only role: the institution that originates payments on the customer's behalf against an upstream bank. OPIN has no PISP because OPIN has no payment phase.
  • Authorisation Server — the regulator-registered identity/auth endpoint at a participant institution. Each participant has one. Finnest receivers dial a specific authorisation server when opening a connection.
  • Participant Directory — the regulator-published catalogue of every registered institution, with mTLS metadata, JWKS, organisation IDs. Finnest mirrors it locally (@finnest/participant-directory).

Security / FAPI vocabulary ​

  • FAPI — Financial-grade API. OAuth 2.0 / OIDC profile that adds signed-request, mTLS-bound tokens, JARM, PAR, PKCE-S256, JWE for ID tokens.
  • FAPI 1.0 Advanced — the OFB / OPIN baseline (2025). Mandates PS256.
  • FAPI 2.0 — the higher bar; OFB Phase 4 (payments) effectively requires it (PAR + PKCE-S256 + cert-bound tokens).
  • FAPI-BR v2 — the Brazil-specific FAPI profile that OFB and OPIN participants must implement. Specifies private_key_jwt, encrypted ID tokens, hybrid flow, no DPoP mandate.
  • PS256 — RSA-PSS signature with SHA-256. The mandated FAPI-BR signing algorithm. No RS256 anywhere. Enforced by lint.
  • mTLS — Mutual TLS. Both client and server present X.509 certs; binding pins access tokens to the certificate so a stolen token is useless without the cert. Required for OFB / OPIN.
  • ICP-Brasil — Brazil's PKI. mTLS certs in production are issued by ICP-Brasil chains.
  • PAR — Pushed Authorization Request. Client posts the authorisation parameters to a server endpoint up-front; receives a reference (request_uri) the user-agent then carries. Required for payment initiation.
  • PKCE — Proof Key for Code Exchange. The client generates a high-entropy code_verifier, sends code_challenge = SHA256(verifier) in the auth request, then proves possession at the token endpoint. FAPI-BR mandates PKCE-S256.
  • DPoP — Demonstrating Proof of Possession. Token-binding alternative to mTLS; the client signs a JWT proving it holds a key. Not mandated by OFB but supported.
  • CIBA — Client-Initiated Backchannel Authentication. Decoupled flow where the user's mobile app authorises out-of-band. OFB / OPIN support it for high-value flows.
  • DCR — Dynamic Client Registration. The receiver registers a client with an upstream authorisation server programmatically using a Software Statement (SSA).
  • SSA — Software Statement Assertion. A signed JWT issued by the regulator's directory, asserting that a TPP is registered.
  • JARM — JWT-secured Authorization Response Mode. The auth-server returns the authorisation response as a signed JWT instead of raw query parameters.
  • JWE — JSON Web Encryption. ID tokens are encrypted to the receiver under FAPI-BR.

The OPIN Consents v3 and OFB Consents v3 surfaces share the same five-state FSM. Owned by @finnest/consent for the vocabulary; per-regulator BCs layer their scope catalogues on top.

mermaid
stateDiagram-v2
    [*] --> AWAITING_AUTHORISATION : POST /consents
    AWAITING_AUTHORISATION --> AUTHORISED : customer authorises
    AWAITING_AUTHORISATION --> REJECTED : timeout / user denies
    AUTHORISED --> CONSUMED : fully spent
    AUTHORISED --> REVOKED : customer or institution revokes
    REJECTED --> [*]
    CONSUMED --> [*]
    REVOKED --> [*]
  • AWAITING_AUTHORISATION — created; waiting for the customer to authenticate and confirm.
  • AUTHORISED — customer confirmed; consent is usable.
  • CONSUMED — terminal; consent fully spent (e.g. payment executed).
  • REJECTED — terminal; customer or institution rejected before authorisation.
  • REVOKED — terminal; customer or institution revoked after authorisation.

Architectural / Finnest internal ​

  • Tier 1 / Tier 2 / Tier 3 — the dependency-graph layering used in packages/:
    • Tier 1 = cross-cutting platform (regulator-agnostic);
    • Tier 2 = regulator BCs (banking + insurance, parallel shape);
    • Tier 3 = Power product layer.
  • Bounded Context (BC) — the DDD term for a self-contained subdomain. Each Tier-2 package owns one BC.
  • Composition root — the place where BCs are wired into a single OpenAPIHono<AppEnv> app. Lives in services/<name>/src/app.ts.
  • Result<T, AppError> — the error envelope used in service-layer code. Repositories return Result<T, InfrastructureError>. Tests use assertOk / assertErr from @finnest/testing — never unwrap().
  • AppError — Finnest's tagged error union (NotFoundError, ValidationError, ForbiddenError, …) defined in @finnest/core/result.
  • InfrastructureError — repository-layer error union (database failure, http failure, …). Lifted to AppError at the service boundary.
  • Outbox — the at-least-once delivery pattern for events: the BC writes a row to an outbox table inside the same transaction as the business write; a relay drains rows onto NATS JetStream. Avoids the dual-write problem.
  • Slice — the cohesive unit a generator emits: routes.ts, service.ts, repository.ts, schema.ts, contract.ts, mappers.ts, events.ts, index.ts. Generated via bun slice:new.
  • Drift — when a derived artefact (openapi.json, regulatory catalog artefacts, generated migrations, generated SDK types) diverges from the source it should be derived from. The drift-check commands fail CI on detection.
  • Refactor zero-diff invariant — refactor PRs (Phases 0–6 of the architecture refactor) keep services/insurance/openapi.json byte-identical to the Phase-0 baseline. See tools/dx/refactor-safety/README.md.
  • MockOPIN — local conformance / test harness simulating an upstream OPIN provider. Useful for receiver-journey testing without hitting real participants. See .agents/skills/mockopin/.
  • .finnest/ — runtime state directory written by the dev stack. Contains topology, per-service status, logs, last-test snapshots. Read it instead of running interactive commands when investigating.
  • bun <verb> canonical surface — every dev / CI / agent action is routed through a bun <verb> script defined in root package.json. Direct oxlint / tsgo / vitest / tsc invocations are forbidden (lint enforces).

Track names ​

Track A/B/C/D/E refer to the OPIN implementation track names used during the regulatory rollout. They are not part of any code or DB identifier — that anti-pattern was scrubbed in commits 5d751348 and aa6727e2.

  • Track E — the contracting + person + capitalization-title + withdrawal families landed in PR #172.

Common abbreviations ​

  • AppEnv — the Hono environment generic carrying requestId, tenantId, etc. across handlers.
  • PR — pull request.
  • BC — bounded context.
  • TPP — third-party provider (receiver role).
  • PISP — payment initiation service provider (initiator role).
  • CMN — Conselho Monetário Nacional (Brazil's monetary council; co-issues OFB resolutions with BCB).
  • PIX — Brazil's instant-payment rail; OFB Phase 4 pays via PIX.
  • CPF / CNPJ — Brazilian individual / company tax IDs. The two primary LoggedUser document types in OFB / OPIN consent flows.

When in doubt, check AGENTS.md for the canonical reference.

Finnest Power — Open Finance Brasil + Open Insurance Brasil platform.

Copyright © Finnest