O formato de arquivo .ensobre

Resumo

Um arquivo de orçamento do Ensobre (.ensobre; as versões antigas usavam .arca) é um banco de dados SQLite completo envolvido por um cabeçalho de 8 bytes. Se o arquivo tem senha, o banco é criptografado com AES-256-GCM, usando uma chave derivada com Argon2id.

• Sem senha: tire os primeiros 8 bytes e você tem um arquivo SQLite normal, que abre em qualquer ferramenta comum (sqlite3, DB Browser for SQLite, Python, Excel via ODBC…).
• Com senha: derive a chave (Argon2id), descriptografe (AES-256-GCM) e você obtém o mesmo arquivo SQLite.

O contêiner

Todos os inteiros são little-endian.

Cabeçalho (primeiros 8 bytes, sempre presente)

Sem criptografia (bit 0 = 0)

Da posição 8 até o fim do arquivo está o banco SQLite como ele é — começa com SQLite format 3\0.

Criptografado (bit 0 = 1)

• Chave = Argon2id(senha em UTF-8, salt, m_cost, t_cost, p_cost), com saída de 32 bytes.
• O cabeçalho completo de 49 bytes é usado como dado associado (AAD) do AES-GCM: se alguém mexer nos parâmetros, a descriptografia falha de vez em vez de enfraquecer a segurança em silêncio.

Exemplo em Python

É literalmente só isto que você precisa para tirar um arquivo SQLite comum de dentro de um arquivo de orçamento do Ensobre (.ensobre, ou o antigo .arca), com ou sem senha:

from argon2.low_level import hash_secret_raw, Type   # pip install argon2-cffi
from cryptography.hazmat.primitives.ciphers.aead import AESGCM  # pip install cryptography
import struct, sqlite3

data = open("meu orcamento.ensobre", "rb").read()
assert data[:4] == b"ARCA"  # bytes mágicos históricos, mantidos por compatibilidade
flags = struct.unpack_from("<H", data, 6)[0]
if flags & 1:
    m, t, p = struct.unpack_from("<III", data, 9)
    salt, nonce = data[21:37], data[37:49]
    key = hash_secret_raw(b"minha senha", salt, t, m, p, 32, Type.ID)
    db = AESGCM(key).decrypt(nonce, data[49:], data[:49])
else:
    db = data[8:]
open("orcamento.sqlite", "wb").write(db)
print(sqlite3.connect("orcamento.sqlite").execute("select count(*) from transactions").fetchone())

Como é gravado no disco

O Ensobre nunca modifica o arquivo «ao vivo». Ele mantém o banco na memória e, a cada salvamento:

1. grava o contêiner completo em arquivo.ensobre.tmp (arquivo.arca.tmp nos orçamentos antigos) e força a gravação no disco;
2. renomeia o arquivo atual para arquivo.ensobre.bak;
3. renomeia o arquivo .tmp de volta para arquivo.ensobre.

Isso significa que sempre existe pelo menos uma cópia completa no disco, e as pastas sincronizadas (Dropbox, OneDrive, iCloud Drive, Syncthing) nunca veem um arquivo gravado pela metade. Enquanto um orçamento está aberto, também existe um arquivo arquivo.ensobre.lock — um bloqueio para que duas janelas não gravem ao mesmo tempo — que é removido ao fechar.

Se o Ensobre perceber, ao salvar, que o arquivo no disco mudou desde que foi aberto (outro computador, o cliente do Dropbox se atualizando), ele não o sobrescreve: pergunta se você quer manter a sua versão, carregar a que está no disco ou salvar como um novo arquivo.

Esquema SQLite (versão 6)

A tabela meta guarda schema_version, budget_name, base_currency, mode (simple/full), locale e created_at. Ela pode conter outras chaves internas além dessas — pode ignorá-las com segurança. Três são opcionais e informativas, e só existem se o orçamento foi criado mudando a moeda principal: rebased_from (a moeda principal anterior), rebased_rate (quantas unidades da moeda nova valia 1 unidade da antiga: a taxa única usada) e rebased_at (data, YYYY-MM-DD). Outra chave opcional, scheduled_paused:<id do agendamento>, existe enquanto aquela transação agendada está pausada; o valor dela é a data da pausa (YYYY-MM-DD). Uma série pausada mantém a sua frequência e a próxima data, mas não aparece como próxima nem como atrasada e fica de fora das projeções e da exportação para o calendário. Uma chave com valor ilegível, ou de um agendamento que não existe mais, é ignorada. As versões antigas do app não conhecem essa chave, então mostram o agendamento como ativo.

Convenções

• Valores: inteiros na menor unidade da moeda (1234 = 12,34 USD; 1500 = 1.500 CLP). O número de casas decimais de cada moeda está em currencies.exponent.
• Datas: texto ISO YYYY-MM-DD. Meses: YYYY-MM.
• Ids: UUID v7 como texto.
• Taxas: texto decimal exato, «unidades da moeda principal por 1 unidade da moeda».

Transações

• amount: na moeda da própria conta, com sinal (negativo = saída de dinheiro).
• amount_base: o mesmo movimento na moeda principal, congelado na fx_rate vigente quando foi registrado. Mudar as taxas depois não reescreve a história.
• kind:
  • normal — um gasto ou um estorno; afeta o envelope de category_id (ou fica «sem envelope» se for NULL).
  • income — receita; vai para «A distribuir».
  • starting — o saldo inicial de uma conta; vai para «A distribuir».
  • transfer — uma das duas pontas de uma transferência entre contas; as duas pontas compartilham transfer_id e têm valores de amount_base exatamente opostos, então nenhum dinheiro é criado nem destruído.
• split_group (v6): as partes de um gasto dividido entre vários envelopes compartilham este id. Cada parte é uma transação normal ou income completa, com o próprio envelope e valor, então a matemática acima não muda. Todas as partes têm a mesma conta, data, estabelecimento, nota, taxa e estado de conciliação, e o total do gasto é a soma das partes. Só a primeira (a mais antiga) guarda o fitid do banco.

Como funciona a matemática do orçamento

Para cada envelope e mês: available = carryover + assigned + activity, em que activity é a soma de amount_base das transações normal dele naquele mês. Um saldo positivo passa para o mês seguinte; um negativo (gasto a mais) volta a zero e é descontado do «A distribuir» do mês seguinte.

Envelopes de dívida (v4): o saldo inicial de um cartão de crédito (starting) pode ter um category_id apontando para o envelope da dívida dele. Aí ele conta como transação desse envelope, em vez de receita de «A distribuir», e o saldo negativo do envelope passa de um mês para o outro (é dívida anterior sendo paga, não gasto a mais).

A distribuir(mês) = receitas até o mês − distribuído até o mês − distribuído em meses futuros − gasto a mais de meses anteriores + transações sem envelope até o mês.

Isso garante que: A distribuir + Σ disponível = saldo total das contas (nas taxas congeladas) − valor distribuído para meses futuros.

Compatibilidade

• Os arquivos .arca antigos continuam abrindo normalmente no Ensobre; os orçamentos novos são salvos como .ensobre.
• Um Ensobre mais novo sempre abre arquivos de versões mais antigas (ele migra o esquema ao salvar).
• Um Ensobre mais antigo se recusa a abrir um arquivo com schema_version maior do que o que conhece, em vez de arriscar corrompê-lo.