From dfd39021fd4e076dba15b69e967ee8a1dac6ed15 Mon Sep 17 00:00:00 2001 From: rodrigopavezi Date: Tue, 17 Nov 2026 07:39:27 -0300 Subject: [PATCH] fix: keep a per-member floor so pruned removals stay removed recovery.json moves to version 2 with floors: pruning a tombstone records its gen for the member. When the holder merges the file into memory, a row only the file holds is dropped when its gen is at or under memory's floor for that member, so an older copy of the file no longer brings back a removed passkey or recovery code. The file's floor never drops a row memory holds. Version 1 is still read and becomes version 2 on the next changing write. Also pins the androidx.credentials guard in a test and documents the backup and restore procedure for recovery.json. Part of #444 --- README.md | 2 +- apps/app/test/passkeyPrfAndroid.test.js | 44 ++++ apps/cli/lib/account/recovery-store.js | 102 ++++++-- apps/cli/test/recovery-store.test.js | 236 ++++++++++++++++++ docs/app.md | 2 +- docs/changelog/fix-recovery-store-floor.md | 4 + docs/design.md | 2 +- docs/protocol.md | 4 +- docs/verification.md | 6 +- docs/verification/fix-recovery-store-floor.md | 47 ++++ 10 files changed, 424 insertions(+), 25 deletions(-) create mode 100644 apps/app/test/passkeyPrfAndroid.test.js create mode 100644 docs/changelog/fix-recovery-store-floor.md create mode 100644 docs/verification/fix-recovery-store-floor.md diff --git a/README.md b/README.md index 354dd41ba..07a6f73c8 100644 --- a/README.md +++ b/README.md @@ -671,7 +671,7 @@ Criar a primeira página é uma migração de mão única do diretório de conta Os aceites dos Termos de Uso e da Política de Privacidade ficam num arquivo à parte no mesmo volume, `terms.json` (modo `0600`): para cada chave de membro, a versão aceita, a data (do relógio do serviço), o nonce e a assinatura que provaram o aceite; nunca o e-mail. Só um membro já vinculado registra aceite (`POST /account/terms/start` e `/account/terms/finish`, com uma prova da chave do diário) e lê de volta se o serviço guarda a versão atual (`POST /account/terms/held/start` e `/account/terms/held/finish`, com a prova `summary` da chave do diário; uma leitura por membro, no máximo 30 a cada 10 minutos). `GET /account/status` não traz a versão aceita. Inclua `terms.json` no backup do volume `account-data`, junto do diretório de contas. Restaurar uma cópia mais antiga perde os aceites feitos depois dela, e os aparelhos que já sincronizaram o aceite não o reenviam. `account export` traz em cada linha o campo `terms`, a lista `[{ "version", "acceptedAt" }]` dos aceites daquele membro (`[]` sem aceite; nunca o nonce nem a assinatura), e sai com `terms.json inválido` (código 1) se o arquivo estiver corrompido; `account status` mostra `aceites dos termos: ` ou `aceites dos termos: indisponível (terms.json inválido)`. Com o arquivo inválido o serviço continua no ar, registra `terms indisponivel` e responde "indisponível" (HTTP 503) só nessas rotas. Uma versão anterior a esta ignora o `terms.json` e responde 404 nas duas rotas: voltar a ela não perde os aceites gravados, que reaparecem quando esta versão volta. -As passkeys extras e o código de recuperação de cada membro (Ajustes › Passkeys e recuperação) ficam noutro arquivo à parte no mesmo volume, `recovery.json` (modo `0600`): por identificador derivado, a chave do membro, o tipo (`passkey` ou `code`), a data e a raiz embrulhada, um texto cifrado que o serviço não consegue abrir. As rotas são `POST /account/recovery/start`, `/put`, `/remove`, `/list` (com uma prova da chave do diário, só para membro vinculado) e `/fetch` (o identificador vai só no corpo do POST). São até 4 passkeys extras e 1 código por membro (`limite-recuperacao`, HTTP 409). O `/start` não guarda nada (o nonce leva a validade e uma assinatura do próprio serviço) e não tem cota por membro, então ninguém bloqueia outro membro pedindo nonces em nome dele; o nonce só é gasto depois de uma prova válida. Remover ou trocar uma entrada só impede novas entradas com ela: quem já entrou com aquela passkey ou aquele código continua com acesso, porque a chave da conta não pode ser trocada, e o único caminho seguro depois de um vazamento é criar uma conta nova. Inclua `recovery.json` no backup do volume `account-data`; se ele se perder, cada membro entra com a passkey original ou num aparelho ainda conectado e cadastra as entradas de novo. Com o arquivo corrompido o serviço continua no ar, registra `recovery indisponivel`, nunca regrava o arquivo e responde "indisponível" (HTTP 503) só nas rotas `/account/recovery/*`. O arquivo não entra em `account export` nem em `account status`, e os registros do serviço nunca trazem o identificador, o texto cifrado nem a chave. Detalhes em `docs/protocol.md` ("Files and replicas"). +As passkeys extras e o código de recuperação de cada membro (Ajustes › Passkeys e recuperação) ficam noutro arquivo à parte no mesmo volume, `recovery.json` (modo `0600`): por identificador derivado, a chave do membro, o tipo (`passkey` ou `code`), a data e a raiz embrulhada, um texto cifrado que o serviço não consegue abrir. As rotas são `POST /account/recovery/start`, `/put`, `/remove`, `/list` (com uma prova da chave do diário, só para membro vinculado) e `/fetch` (o identificador vai só no corpo do POST). São até 4 passkeys extras e 1 código por membro (`limite-recuperacao`, HTTP 409). O `/start` não guarda nada (o nonce leva a validade e uma assinatura do próprio serviço) e não tem cota por membro, então ninguém bloqueia outro membro pedindo nonces em nome dele; o nonce só é gasto depois de uma prova válida. Remover ou trocar uma entrada só impede novas entradas com ela: quem já entrou com aquela passkey ou aquele código continua com acesso, porque a chave da conta não pode ser trocada, e o único caminho seguro depois de um vazamento é criar uma conta nova. Inclua `recovery.json` no backup do volume `account-data`; copiar com o serviço no ar não tem problema, porque o arquivo é sempre trocado inteiro de uma vez. Para restaurar, com o serviço parado, ponha de volta só a cópia mais nova: ela não tem as entradas cadastradas depois da cópia e volta a ter as removidas depois dela, então avise os membros para conferirem Ajustes › Passkeys e recuperação. Sem cópia, suba o serviço sem o arquivo: cada membro entra com a passkey original ou num aparelho ainda conectado e cadastra as entradas de novo. A primeira gravação que muda o arquivo o deixa na versão 2, que uma versão mais antiga do serviço não lê: se voltar para ela, as rotas `/account/recovery/*` respondem 503 até a versão nova voltar. Com o arquivo corrompido o serviço continua no ar, registra `recovery indisponivel`, nunca regrava o arquivo e responde "indisponível" (HTTP 503) só nas rotas `/account/recovery/*`. O arquivo não entra em `account export` nem em `account status`, e os registros do serviço nunca trazem o identificador, o texto cifrado nem a chave. Detalhes em `docs/protocol.md` ("Files and replicas"). Se houver um `directory.journal.*` antes de voltar (um diário órfão), suba esta versão de novo, espere mais de 40 segundos para que a limpeza de órfãos o remova, pare-a com a parada limpa e confira de novo. O `deploy.sh` desfaz o deploy sozinho recriando o contêiner `account` com um fechamento por SIGTERM, que deixa a versão 1 só se esse fechamento der certo; se o contêiner `account` estava parado ou reiniciando naquele momento, o diretório continua na versão 2 e a imagem anterior o recusa até que os passos manuais acima sejam seguidos. diff --git a/apps/app/test/passkeyPrfAndroid.test.js b/apps/app/test/passkeyPrfAndroid.test.js new file mode 100644 index 000000000..96f00d3c4 --- /dev/null +++ b/apps/app/test/passkeyPrfAndroid.test.js @@ -0,0 +1,44 @@ +'use strict' + +// The Android passkey module (modules/passkey-prf/android) pins Credential +// Manager. Releases before 1.5.0 lack the passkey cleanup the app relies on, +// and a range or a variable would let a build pick one. The file is read as +// text. +const fs = require('node:fs') +const path = require('node:path') +const test = require('brittle') + +const GRADLE = path.join(__dirname, '..', 'modules/passkey-prf/android/build.gradle') +const MIN = [1, 5, 0] +const ARTIFACTS = ['androidx.credentials:credentials', 'androidx.credentials:credentials-play-services-auth'] + +const uncommented = (gradle) => gradle.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/[^\n]*/g, '') + +function atLeast (version, min) { + const parts = version.split('.').map(Number) + for (let i = 0; i < min.length; i++) { + if (parts[i] !== min[i]) return parts[i] > min[i] + } + return true +} + +test('atLeast compares versions numerically', (t) => { + t.ok(atLeast('1.5.0', MIN)) + t.ok(atLeast('1.10.0', MIN), 'not a string compare') + t.ok(atLeast('2.0.0', MIN)) + t.absent(atLeast('1.4.9', MIN)) + t.absent(atLeast('0.9.0', MIN)) +}) + +test('both Credential Manager dependencies are pinned to an exact version at or above 1.5.0', (t) => { + const gradle = uncommented(fs.readFileSync(GRADLE, 'utf8')) + for (const artifact of ARTIFACTS) { + const lines = [...gradle.matchAll(/^\s*implementation\s+(['"])([^'"]*)\1\s*$/gm)] + .map((m) => m[2]) + .filter((coord) => coord.startsWith(artifact + ':')) + t.is(lines.length, 1, artifact + ' is declared once, as a plain string') + const version = lines.length === 1 ? lines[0].slice(artifact.length + 1) : '' + t.ok(/^\d+\.\d+\.\d+$/.test(version), artifact + ' has an exact version: ' + version) + t.ok(atLeast(version, MIN), artifact + ' is at least ' + MIN.join('.') + ': ' + version) + } +}) diff --git a/apps/cli/lib/account/recovery-store.js b/apps/cli/lib/account/recovery-store.js index 56c125b87..f351755c7 100644 --- a/apps/cli/lib/account/recovery-store.js +++ b/apps/cli/lib/account/recovery-store.js @@ -13,10 +13,19 @@ // nothing from this file is logged or put in an error: a lookupId finds a // blob, a blob is the member's wrapped root. // +// The file is { v: 2, seq, entries, removed, floors }: entries maps lookupId +// to its row, removed maps lookupId to its tombstone and floors maps a member +// key to a gen (both below). A version 1 file (the same without floors) is +// still read; the next write that changes anything writes version 2, and +// nothing is rewritten only to change the version. An older build of the +// service refuses a version 2 file as malformed and never rewrites it, so +// after a rollback /account/recovery/* answers 503 until the newer build +// returns. +// // Opening never creates, mkdirs or chmods anything (a missing file means no // entry yet; the first put writes it), and a readOnly store never writes at // all. Validation is total: a file this module would not have written (bad -// JSON, unknown keys, a bad id, row or tombstone, an id both live and +// JSON, unknown keys, a bad id, row, tombstone or floor, an id both live and // removed) is never rewritten, and every method then throws // { code: 'indisponivel' } until an operator repairs it. Errors carry only a // token in `code`; bad argument shapes throw TypeError with a fixed message. @@ -50,11 +59,35 @@ // (one just written, or one whose removedAt is ahead of this clock) nor the // member's newest tombstone, so a member may briefly hold more than the cap; // the TTL is far longer than that window, so it never drops a fresh one. -// Residual: a copy of the file older than a pruned tombstone may still -// resurrect that row. Accepted, since a stale writer's rename lands within -// one lock period (30 s) and is healed within one heal interval, far inside -// STALE_WINDOW_MS; a holder whose clock runs more than the TTL behind may -// also see its fresh tombstones pruned by another holder. +// +// Each pruned tombstone, by the TTL or by the cap, raises its member's floor +// (`floors`) to its gen; floors only go up, a merge takes the max per +// member, and a floor never passes seq. When this holder merges the file +// into its memory, a row only the file holds is dropped when its gen is at +// or under memory's floor for that member: memory had the row, removed it +// and pruned the tombstone. So a copy on disk older than memory that still +// holds a removed row (a stale writer's rename) cannot bring it back through +// heal(), a read after an uncertain write or the merge before a write, +// however long ago the tombstone went. The file's floor never drops a row +// memory holds: the service takes the lock before it opens the store and +// fails the store for good when it loses the lock (../commands/account.js), +// so memory is never behind the file on their shared history, and a file +// whose floor passes a row in memory comes from another history (a copy put +// back after the service started from an older copy or from no file), whose +// floors say nothing about memory's rows. A row put later takes a gen above +// every floor, since put() merges first. A floor keeps the member key after +// the member's last tombstone is pruned, Excluir conta included. Tombstones +// pruned by a version 1 build left no floor. +// +// Residual: a merge needs two copies. A copy put back while no holder runs +// is read as it is: it lacks every row written after it and holds again the +// rows removed after it, with nothing left to bury them. A copy from another +// history put back while a holder runs is a union apart from memory's floor: +// its rows removed in that history may come back, and those at or under +// memory's floor for their member go. A holder whose clock runs behind +// another's by more than STALE_WINDOW_MS (or the TTL) may see its fresh +// tombstones pruned by the cap (or the TTL) on that other holder; the rows +// they buried stay buried under the floor. // // Reads (list, fetch) after an uncertain write (a failed write, or guard() // refusing after the rename) first re-read the file and adopt the merge, or @@ -78,7 +111,7 @@ const { writeJsonAtomic } = require('@varanda/core/lib/store') const { isLowerHex, isCanonicalIso, isPlainObject, refuseSymlinkDir } = require('@varanda/core/lib/cert') const FILE = 'recovery.json' -const VERSION = 1 +const VERSION = 2 const MAX_PASSKEYS = 4 const TOMBSTONE_MAX_PER_MEMBER = 32 const TOMBSTONE_TTL_MS = 30 * 24 * 3600 * 1000 @@ -87,7 +120,10 @@ const KINDS = ['passkey', 'code'] const BLOB_KEYS = ['v', 'kind', 'nonce', 'ciphertext'] const ENTRY_KEYS = ['member', 'kind', 'nonce', 'ciphertext', 'createdAt', 'gen'] const TOMB_KEYS = ['member', 'removedAt', 'gen'] -const FILE_KEYS = ['v', 'seq', 'entries', 'removed'] +const FILE_KEYS = ['v', 'seq', 'entries', 'removed', 'floors'] +// Version 1 had no floors; it is still read, and the next write that changes +// anything is version 2. +const FILE_KEYS_V1 = ['v', 'seq', 'entries', 'removed'] // 24-byte secretbox nonce; 66-byte plaintext + 16-byte MAC. const NONCE_BYTES = 24 const CIPHERTEXT_BYTES = 82 @@ -166,13 +202,16 @@ function invalidFile () { } function emptyState () { - return { v: VERSION, seq: 0, entries: Object.create(null), removed: Object.create(null) } + return { v: VERSION, seq: 0, entries: Object.create(null), removed: Object.create(null), floors: Object.create(null) } } function fromJson (obj) { - if (!isPlainObject(obj) || !exactKeys(obj, FILE_KEYS) || obj.v !== VERSION) throw invalidFile() + if (!isPlainObject(obj)) throw invalidFile() + const v1 = obj.v === 1 && exactKeys(obj, FILE_KEYS_V1) + if (!v1 && (obj.v !== VERSION || !exactKeys(obj, FILE_KEYS))) throw invalidFile() if (!Number.isSafeInteger(obj.seq) || obj.seq < 0) throw invalidFile() if (!isPlainObject(obj.entries) || !isPlainObject(obj.removed)) throw invalidFile() + if (!v1 && !isPlainObject(obj.floors)) throw invalidFile() // No per-member row ceiling here: a merge of two holders' copies may pass // MAX_PASSKEYS, and a load-time ceiling would make this store refuse a file // it wrote itself. @@ -186,6 +225,12 @@ function fromJson (obj) { if (!validId(id) || !validTomb(r) || r.gen > obj.seq || has(state.entries, id)) throw invalidFile() state.removed[id] = copyTomb(r) } + if (!v1) { + for (const [member, gen] of Object.entries(obj.floors)) { + if (!validMember(member) || !validGen(gen) || gen > obj.seq) throw invalidFile() + state.floors[member] = gen + } + } return state } @@ -226,13 +271,25 @@ function toJson (state) { for (const id of Object.keys(state.entries).sort()) entries[id] = copyEntry(state.entries[id]) const removed = {} for (const id of Object.keys(state.removed).sort()) removed[id] = copyTomb(state.removed[id]) - return { v: VERSION, seq: state.seq, entries, removed } + const floors = {} + for (const m of Object.keys(state.floors).sort()) floors[m] = state.floors[m] + return { v: VERSION, seq: state.seq, entries, removed, floors } } function canonical (state) { return JSON.stringify(toJson(state)) } +function floorOf (state, member) { + return has(state.floors, member) ? state.floors[member] : 0 +} + +// A pruned tombstone leaves its gen behind as the member's floor, so a copy +// that still holds the row it buried cannot bring it back (merge()). +function raiseFloor (state, member, gen) { + if (gen > floorOf(state, member)) state.floors[member] = gen +} + function genOf (state, id) { if (!state) return 0 if (has(state.entries, id)) return state.entries[id].gen @@ -273,8 +330,9 @@ function nextGen (state) { // then tombstones older than the TTL go, then each // member keeps its TOMBSTONE_MAX_PER_MEMBER highest-gen tombstones; that cap // never drops a tombstone younger than STALE_WINDOW_MS or the member's -// newest one. put(), remove() and merge() all end here, so every copy this -// holder writes agrees on what is kept. +// newest one. Each pruned tombstone raises its member's floor. put(), remove() +// and merge() all end here, so every copy this holder writes agrees on what +// is kept. function normalize (state, nowMs) { const codes = new Map() for (const [id, e] of Object.entries(state.entries)) { @@ -307,6 +365,7 @@ function normalize (state, nowMs) { for (const r of list) { if (Date.parse(r.removedAt) < cutoff) { delete state.removed[r.id] + raiseFloor(state, r.member, r.gen) kept-- } } @@ -314,6 +373,7 @@ function normalize (state, nowMs) { if (kept <= TOMBSTONE_MAX_PER_MEMBER) break if (!has(state.removed, r.id) || r === newest || Date.parse(r.removedAt) >= young) continue delete state.removed[r.id] + raiseFloor(state, r.member, r.gen) kept-- } } @@ -321,16 +381,26 @@ function normalize (state, nowMs) { } // Per lookupId the record (row or tombstone) with the higher gen; ties keep -// memory. +// memory. A row only the disk holds is dropped when its gen is at or under +// memory's floor for its member: memory removed it and pruned the tombstone. +// Never the other way (see the top of the file), and a copy's own floor never +// drops its rows, since a member may keep an older row it never removed +// under it. Floors merge as max. function merge (mem, disk, nowMs) { const out = emptyState() out.seq = Math.max(mem.seq, disk ? disk.seq : 0) + for (const src of disk ? [mem, disk] : [mem]) { + for (const [member, gen] of Object.entries(src.floors)) raiseFloor(out, member, gen) + } const ids = new Set([...Object.keys(mem.entries), ...Object.keys(mem.removed)]) if (disk) for (const id of [...Object.keys(disk.entries), ...Object.keys(disk.removed)]) ids.add(id) for (const id of ids) { const src = disk && genOf(disk, id) > genOf(mem, id) ? disk : mem - if (has(src.entries, id)) out.entries[id] = copyEntry(src.entries[id]) - else out.removed[id] = copyTomb(src.removed[id]) + if (has(src.entries, id)) { + const e = src.entries[id] + if (src === disk && genOf(mem, id) === 0 && e.gen <= floorOf(mem, e.member)) continue + out.entries[id] = copyEntry(e) + } else out.removed[id] = copyTomb(src.removed[id]) } return normalize(out, nowMs) } diff --git a/apps/cli/test/recovery-store.test.js b/apps/cli/test/recovery-store.test.js index 587489a67..0acccf5c0 100644 --- a/apps/cli/test/recovery-store.test.js +++ b/apps/cli/test/recovery-store.test.js @@ -664,3 +664,239 @@ test('put over another member\'s tombstone is refused; the same member may re-pu t.is((await store.put(r)).changed, true, 'the same member re-puts') t.is(store.fetch(r.lookupId).member, a) }) + +function fileRow (member, gen, kind = 'passkey') { + return { member, kind, nonce: '0'.repeat(48), ciphertext: '1'.repeat(164), createdAt: new Date(T0).toISOString(), gen } +} + +test('a tombstone pruned by the TTL leaves a floor: an older copy never brings its row back', async (t) => { + const { store, file, c } = setup(t) + const m = hex32() + const r = req(m) + await store.put(r) + const old = fs.readFileSync(file, 'utf8') + c.t += 1000 + await store.remove({ member: m, lookupId: r.lookupId }) + c.t += TOMBSTONE_TTL_MS + DAY + await store.put(req(m)) + let disk = readFile(file) + t.absent(disk.removed[r.lookupId], 'tombstone pruned') + t.is(disk.v, 2) + t.alike(disk.floors, { [m]: 2 }, 'the floor is the pruned tombstone\'s gen') + + // heal(): a stalled writer renames the copy that still holds the row. + fs.writeFileSync(file, old) + t.is(await store.heal(), true, 'heal rewrites') + t.is(store.fetch(r.lookupId), null, 'not back in memory') + disk = readFile(file) + t.absent(disk.entries[r.lookupId], 'not back on disk') + t.alike(disk.floors, { [m]: 2 }, 'the floor survives the merge') + + // The merge before a write. + fs.writeFileSync(file, old) + t.is((await store.put(req(m))).changed, true) + t.absent(readFile(file).entries[r.lookupId], 'not back after a put over the old copy') + t.is(store.fetch(r.lookupId), null) +}) + +test('the file\'s floor never drops a row memory holds: a copy from another history is merged', async (t) => { + const { store, file, c } = setup(t) + const m = hex32() + const kept = hex32() + // The service started with no file, and the member registered again. + const r = req(m) + await store.put(r) + t.is(readFile(file).entries[r.lookupId].gen, 1) + // A copy of the earlier file, whose floor for m passes that row, is put back. + fs.writeFileSync(file, JSON.stringify({ v: 2, seq: 8, entries: { [kept]: fileRow(m, 8) }, removed: {}, floors: { [m]: 7 } })) + c.t += 1000 + t.is(await store.heal(), true, 'heal rewrites') + t.ok(store.fetch(r.lookupId), 'the row memory holds stays') + t.ok(store.fetch(kept), 'the copy\'s row comes in') + const disk = readFile(file) + t.alike(Object.keys(disk.entries).sort(), [r.lookupId, kept].sort()) + t.is(disk.seq, 8) + t.alike(disk.floors, { [m]: 7 }) + const next = req(m) + await store.put(next) + t.ok(readFile(file).entries[next.lookupId].gen > 8, 'a later put takes a gen above the floor') +}) + +test('removeMember, then the TTL: an older copy never brings the member\'s rows back', async (t) => { + const { store, file, c } = setup(t) + const m = hex32() + const other = hex32() + const rows = [req(m), req(m, 'code')] + for (const r of rows) await store.put(r) + const old = fs.readFileSync(file, 'utf8') + c.t += 1000 + t.is((await store.removeMember(m)).changed, true) + c.t += TOMBSTONE_TTL_MS + DAY + await store.put(req(other)) + let disk = readFile(file) + for (const r of rows) t.absent(disk.removed[r.lookupId], 'tombstone pruned') + t.ok(disk.floors[m] >= 3, 'the member keeps a floor') + + fs.writeFileSync(file, old) + t.is(await store.heal(), true, 'heal rewrites') + for (const r of rows) t.is(store.fetch(r.lookupId), null, 'not back in memory') + disk = readFile(file) + for (const r of rows) t.absent(disk.entries[r.lookupId], 'not back on disk') + t.alike(store.list(m), []) +}) + +test('a read after an uncertain write never brings back a row under the floor', async (t) => { + let calls = 0 + let refuseAt = -1 + const { store, file, c } = setup(t, { guard: () => ++calls !== refuseAt }) + const m = hex32() + const r = req(m) + await store.put(r) + const old = fs.readFileSync(file, 'utf8') + c.t += 1000 + await store.remove({ member: m, lookupId: r.lookupId }) + c.t += TOMBSTONE_TTL_MS + DAY + await store.put(req(m)) + t.ok(readFile(file).floors[m], 'the floor is on disk') + refuseAt = calls + 2 // before = +1, after the rename = +2 + await rejects(t, store.put(req(m)), 'indisponivel', 'put refused after the rename') + fs.writeFileSync(file, old) + t.is(store.fetch(r.lookupId), null, 'fetch merges the old copy and keeps the row gone') + t.absent(store.list(m).some((x) => x.lookupId === r.lookupId), 'list too') +}) + +test('a tombstone pruned by the per-member cap leaves a floor: an older copy never brings its row back', async (t) => { + const { store, file, c } = setup(t) + const m = hex32() + const r = req(m) + await store.put(r) + const old = fs.readFileSync(file, 'utf8') + c.t += 1000 + await store.remove({ member: m, lookupId: r.lookupId }) + // Each new code buries the previous one, well inside the TTL. + for (let i = 0; i < TOMBSTONE_MAX_PER_MEMBER + 2; i++) { + c.t += STALE_WINDOW_MS + 1000 + await store.put(req(m, 'code')) + } + t.ok(c.t - T0 < TOMBSTONE_TTL_MS, 'no tombstone reached the TTL') + let disk = readFile(file) + t.absent(disk.removed[r.lookupId], 'the cap pruned the oldest tombstone') + t.ok(disk.floors[m] >= 2, 'and left a floor at or above its gen') + + fs.writeFileSync(file, old) + t.is(await store.heal(), true, 'heal rewrites') + t.is(store.fetch(r.lookupId), null, 'not back in memory') + disk = readFile(file) + t.absent(disk.entries[r.lookupId], 'not back on disk') + t.is(store.list(m).filter((x) => x.kind === 'passkey').length, 0) +}) + +test('a version 1 file is read, and the next write that changes it is version 2', async (t) => { + const { file, open, c } = setup(t) + const m = hex32() + const id = hex32() + const v1 = JSON.stringify({ v: 1, seq: 1, entries: { [id]: fileRow(m, 1) }, removed: {} }) + fs.writeFileSync(file, v1) + const store = open() + t.ok(store.available()) + t.is(store.fetch(id).member, m) + c.t += 1000 + t.is(await store.heal(), false, 'nothing rewritten only for the version') + t.is(fs.readFileSync(file, 'utf8'), v1) + const r = req(m) + await store.put(r) + const disk = readFile(file) + t.alike(Object.keys(disk), ['v', 'seq', 'entries', 'removed', 'floors']) + t.is(disk.v, 2) + t.alike(disk.floors, {}) + t.alike(disk.entries[id], fileRow(m, 1), 'the version 1 row is kept') + t.ok(disk.entries[r.lookupId]) + t.ok(open().available(), 'the version 2 file opens') +}) + +test('a version 1 file whose tombstone expired is rewritten as version 2 with the floor', async (t) => { + const { file, open, c } = setup(t) + const m = hex32() + const id = hex32() + fs.writeFileSync(file, JSON.stringify({ v: 1, seq: 4, entries: {}, removed: { [id]: { member: m, removedAt: new Date(T0).toISOString(), gen: 4 } } })) + const store = open() + c.t += TOMBSTONE_TTL_MS + DAY + t.is(await store.heal(), true, 'the prune is written') + const disk = readFile(file) + t.is(disk.v, 2) + t.alike(disk.removed, {}) + t.alike(disk.floors, { [m]: 4 }) +}) + +test('a malformed floor makes the file malformed', async (t) => { + const m = hex32() + const cases = [ + JSON.stringify({ v: 2, seq: 9, entries: {}, removed: {} }), + JSON.stringify({ v: 1, seq: 9, entries: {}, removed: {}, floors: {} }), + JSON.stringify({ v: 2, seq: 9, entries: {}, removed: {}, floors: {}, extra: 1 }), + JSON.stringify({ v: 3, seq: 9, entries: {}, removed: {}, floors: {} }), + JSON.stringify({ v: 2, seq: 9, entries: {}, removed: {}, floors: null }), + JSON.stringify({ v: 2, seq: 9, entries: {}, removed: {}, floors: [] }), + JSON.stringify({ v: 2, seq: 9, entries: {}, removed: {}, floors: { [m.toUpperCase()]: 1 } }), + JSON.stringify({ v: 2, seq: 9, entries: {}, removed: {}, floors: { [m.slice(2)]: 1 } }), + JSON.stringify({ v: 2, seq: 9, entries: {}, removed: {}, floors: { [m]: 0 } }), + JSON.stringify({ v: 2, seq: 9, entries: {}, removed: {}, floors: { [m]: -1 } }), + JSON.stringify({ v: 2, seq: 9, entries: {}, removed: {}, floors: { [m]: 1.5 } }), + JSON.stringify({ v: 2, seq: 9, entries: {}, removed: {}, floors: { [m]: '3' } }), + JSON.stringify({ v: 2, seq: 9, entries: {}, removed: {}, floors: { [m]: 10 } }) + ] + for (const bytes of cases) { + const { file, open } = setup(t) + fs.writeFileSync(file, bytes) + const store = open() + t.absent(store.available(), 'unavailable: ' + bytes.slice(0, 60)) + await rejects(t, store.put(req(m)), 'indisponivel', 'put refused') + t.is(await store.heal(), false) + t.is(fs.readFileSync(file, 'utf8'), bytes, 'bytes untouched') + } + const { file, open } = setup(t) + fs.writeFileSync(file, JSON.stringify({ v: 2, seq: 9, entries: {}, removed: {}, floors: { [m]: 9 } })) + t.ok(open().available(), 'a floor equal to seq is fine') +}) + +test('floors merge as the max per member', async (t) => { + const { file, open, c } = setup(t) + const [a, b, d] = [hex32(), hex32(), hex32()] + fs.writeFileSync(file, JSON.stringify({ v: 2, seq: 10, entries: {}, removed: {}, floors: { [a]: 5, [b]: 9 } })) + const store = open() + fs.writeFileSync(file, JSON.stringify({ v: 2, seq: 12, entries: {}, removed: {}, floors: { [a]: 8, [d]: 4 } })) + c.t += 1000 + t.is(await store.heal(), true, 'the copy lacks a floor memory has') + const disk = readFile(file) + t.is(disk.seq, 12) + t.alike(disk.floors, { [a]: 8, [b]: 9, [d]: 4 }) + fs.writeFileSync(file, JSON.stringify({ v: 2, seq: 12, entries: {}, removed: {}, floors: { [a]: 3 } })) + await store.heal() + t.alike(readFile(file).floors, { [a]: 8, [b]: 9, [d]: 4 }, 'a lower floor never wins') +}) + +test('the floor drops only rows at or under it, of its member, that its own copy lacks', async (t) => { + const { file, open, c } = setup(t) + const m = hex32() + const m2 = hex32() + const [own, low, high, otherMember] = [hex32(), hex32(), hex32(), hex32()] + // Memory: a floor of 5 for m, and an older row of m it never removed. + fs.writeFileSync(file, JSON.stringify({ v: 2, seq: 10, entries: { [own]: fileRow(m, 3) }, removed: {}, floors: { [m]: 5 } })) + const store = open() + fs.writeFileSync(file, JSON.stringify({ + v: 2, + seq: 10, + entries: { [low]: fileRow(m, 5), [high]: fileRow(m, 6), [otherMember]: fileRow(m2, 4) }, + removed: {}, + floors: {} + })) + c.t += 1000 + t.is(await store.heal(), true) + t.ok(store.fetch(own), 'a row under its own copy\'s floor stays') + t.is(store.fetch(low), null, 'a row at the other copy\'s floor goes') + t.ok(store.fetch(high), 'a row above the floor stays') + t.ok(store.fetch(otherMember), 'another member\'s row stays') + const disk = readFile(file) + t.alike(Object.keys(disk.entries).sort(), [own, high, otherMember].sort()) + t.alike(disk.floors, { [m]: 5 }) +}) diff --git a/docs/app.md b/docs/app.md index 03938282f..6da856fdb 100644 --- a/docs/app.md +++ b/docs/app.md @@ -80,7 +80,7 @@ A última associação válida fica no `localStorage` (`varanda-web-discovered`) **Entrar com a passkey.** A identidade não é guardada: é derivada de uma passkey (WebAuthn com a extensão PRF). Uma passkey nova só é aceita se for guardada num gerenciador que sincroniza entre os aparelhos da mesma conta, como o do Google, o da Apple, o 1Password ou o Bitwarden. Essa regra vale só para criar: uma passkey que já existe sempre entra, mesmo que não sincronize. Num computador sem um gerenciador que sincronize, a página oferece o caminho pelo celular: a pessoa lê o QR code com a câmera do celular, e a passkey é criada ou usada no gerenciador dele. Se a página mostrar que a passkey do Varanda não está num gerenciador que sincroniza, a recuperação é esta: salvar a passkey num gerenciador que sincroniza, para que a conta do Google ou da Apple a devolva num aparelho novo. Quem perdeu a passkey conhecida pode sair do cartão sem apagar o diário deste aparelho; ninguém precisa apagar passkey à mão. Na primeira vez, "Criar minha conta" cria a passkey (rotulada `Varanda xxxxxx`, sem e-mail nem identificador do Google) e deriva a chave; nas seguintes, "Entrar" pede biometria ou PIN e deriva a mesma chave. Depois de entrar, a pessoa continua conectada neste aparelho até tocar "Sair" (abaixo). Algumas passkeys só entregam o resultado PRF num segundo passo, e então a página pede "Concluir e entrar". A passkey com que a conta foi criada continua abrindo a conta, inclusive sem internet, enquanto existir no gerenciador. Além dela, a pessoa pode cadastrar outras passkeys e um código de recuperação para a MESMA conta (veja "Passkeys e recuperação", abaixo): sem nenhuma passkey da conta e sem o código, a conta não volta. O caminho pelo celular, outra passkey e o código de recuperação ficam em "Outras formas de entrar" na tela Entrar. -**Passkeys e recuperação.** Ajustes › Passkeys e recuperação aparece na web hospedada e no app ligado à instalação, com a passkey conhecida, a conta desbloqueada e o vínculo Google (o serviço de conta só guarda entradas de quem tem vínculo). A tela lista as entradas cadastradas só com o tipo e a data, e tem: +**Passkeys e recuperação.** Ajustes › Passkeys e recuperação aparece na web hospedada e no app ligado à instalação, com a passkey conhecida, a conta desbloqueada e vinculada (o serviço de conta só guarda entradas de contas vinculadas). A tela lista as entradas cadastradas só com o tipo e a data, e tem: - **Adicionar passkey**: cria uma passkey nova, de preferência em outro gerenciador (por exemplo, um gerenciador de senhas além do Google ou da Apple), e cadastra no serviço de conta a chave da conta embrulhada para ela. São até quatro passkeys extras por conta. A passkey nova não cria outra identidade: ela só desembrulha a raiz da passkey original, e as chaves continuam as mesmas. - **Trocar a passkey deste aparelho**: primeiro explica a troca (adicionar a nova, conferir que ela entra e depois apagar a antiga no gerenciador de senhas; a passkey original continua abrindo a conta onde existir, e o Varanda não consegue invalidá-la). Depois adiciona e cadastra a nova, e liga este aparelho a ela. - **Criar código de recuperação**: um código de 36 letras e números em 9 grupos de 4, mostrado uma vez só, com copiar e a caixa "Anotei o código". Um código novo substitui o anterior no serviço de conta: o anterior deixa de entrar num aparelho que ainda não o usou, mas quem já entrou com ele continua com acesso. O código fica no cartão da tela Passkeys, também depois de sair da tela e voltar, até a pessoa marcar "Anotei o código" e tocar "pronto"; o cartão não tem "cancelar". diff --git a/docs/changelog/fix-recovery-store-floor.md b/docs/changelog/fix-recovery-store-floor.md new file mode 100644 index 000000000..66dfd6d71 --- /dev/null +++ b/docs/changelog/fix-recovery-store-floor.md @@ -0,0 +1,4 @@ +### Corrigido + +- Recuperação de conta, parte da #444 (PR `fix/recovery-store-floor`): ao descartar registros antigos de remoção, o `recovery.json` passa a guardar, por membro, uma marca da última remoção descartada, e uma cópia mais antiga do arquivo não traz mais de volta uma passkey extra ou um código de recuperação já removido. Verificação em `docs/verification/fix-recovery-store-floor.md`. +- Operação: o `recovery.json` passa à versão 2, escrita na primeira gravação que muda algo. Uma versão anterior do serviço de conta não lê esse arquivo e responde 503 nas rotas `/account/recovery/*` até a versão nova voltar; o arquivo fica como está. diff --git a/docs/design.md b/docs/design.md index 04e0d5469..a26584762 100644 --- a/docs/design.md +++ b/docs/design.md @@ -314,7 +314,7 @@ A proposta é que a associação que publica o app e mantém os serviços compar | Marcas da triagem e leituras verificadas em cache (no máximo 2000) | Serviço de conta, no Brasil (`triage.json` e o registro `triage-marks.jsonl`, modo 0600, volume `account-data`) | Dado derivado da moderação (a base legal ainda precisa de parecer) | Se corrompido, os dois são postos de lado como `.corrupt-` e recriados | | Contagens agregadas de uso (membros, diários, ativos, conexões, armazenamento, cadastros por semana/mês) | Serviço de conta (usage.json, 0600, volume account-data); ativos só na memória do semeador | Não são dados pessoais: só contagens, sem chave, e-mail ou @nome; a data de cadastro já é pública no certificado (confirmar no parecer) | Até 400 dias, rotativo; ativos zeram ao reiniciar o semeador | | Registro de aceite dos Termos de Uso e da Política de Privacidade (versão e data; no serviço de conta também chave do membro, nonce e assinatura) | Aparelho (sincronizado entre os aparelhos da mesma passkey na instalação hospedada (web e app instalado), que o confirmam com uma leitura assinada no serviço de conta depois de Entrar, antes do aceite; também antes dos Termos vem a leitura pública do status pela chave do membro (`GET /account/status`, a mesma de quem abre um perfil), para uma conta excluída ver o aviso primeiro; e, ao Entrar com uma passkey extra de recuperação, a leitura do texto cifrado que abre a conta (`POST /account/recovery/fetch`, só o identificador derivado dela), sem a qual a passkey não abre a conta); serviço de conta, no Brasil (`terms.json`, modo 0600, volume `account-data`), só para membros com vínculo Google | Execução de contrato (a confirmar em parecer) | Apagado na exclusão da conta; fora isso, em aberto (issue #38) | -| Entradas de recuperação: chave do membro, identificador derivado da passkey extra ou do código (o serviço não consegue ligá-lo a uma passkey), texto cifrado que o serviço não consegue abrir, tipo (`passkey` ou `code`) e data | Serviço de conta, no Brasil (`recovery.json`, modo 0600, volume `account-data`), só para membros com vínculo Google | Execução de contrato (a confirmar em parecer); finalidade: abrir a mesma conta com outra passkey ou com o código de recuperação | Até o membro remover a entrada ou excluir a conta (fica por 30 dias só a chave pública e a data da remoção); a retenção depois disso está em aberto (issue #38). Dado cifrado continua sendo dado pessoal | +| Entradas de recuperação: chave do membro, identificador derivado da passkey extra ou do código (o serviço não consegue ligá-lo a uma passkey), texto cifrado que o serviço não consegue abrir, tipo (`passkey` ou `code`) e data | Serviço de conta, no Brasil (`recovery.json`, modo 0600, volume `account-data`), só para membros vinculados | Execução de contrato (a confirmar em parecer); finalidade: abrir a mesma conta com outra passkey ou com o código de recuperação | Até o membro remover a entrada ou excluir a conta (fica por 30 dias só a chave pública e a data da remoção; depois, só a chave pública e um número de ordem, para que uma cópia antiga do arquivo não traga a entrada de volta); a retenção depois disso está em aberto (issue #38). Dado cifrado continua sendo dado pessoal | | Convites de entrada (`invites.json`: chave de quem criou o convite, identificador aleatório, hash do código só enquanto não usado, data de criação, usado sim ou não; nada de quem recebeu nem de quem usou) | Serviço de conta, no Brasil (`invites.json`, modo 0600, volume `account-data`), só quando `VARANDA_INVITES_PER_WEEK` está definido | Execução de contrato (a confirmar em parecer); finalidade: entrada por convite | A semana atual e os convites ainda dentro dos 7 dias de validade (até 14 dias no total); o resto é apagado na próxima criação de convite; os de quem exclui a conta, na hora | | Cartão do convite de entrada (nome de quem recebe, mensagem, desenho, chave de quem convidou e assinatura) | No fragmento do link, que o navegador não envia a servidor; na aba de quem abre o link (`sessionStorage`, 24 h) ou na memória do processo do app instalado. O serviço de conta nunca recebe o cartão, e o link nunca vira prévia; para mostrar quem escreveu, o aparelho de quem abre o link consulta o status público da conta pela chave de quem convidou (só a chave), antes de qualquer cadastro. Quem tem o link pode ler o cartão | Execução de contrato (a confirmar em parecer); finalidade: um convite com recado pessoal | Até 24 h na aba ou até fechar o app; some quando o convite é trocado. Nenhum registro novo de quem convidou quem e nenhum aviso de cadastro; o diretório já guarda o hash do convite usado, como antes | | Convites de surpresa: `invite-drops-key.json` (segredo do sorteio e data de ativação, nenhum dado pessoal) e `invite-drops.json` (chave do membro, semana e índices dos convites já avisados, nenhum horário) | Serviço de conta, no Brasil (`invite-drops-key.json` e `invite-drops.json`, modo 0600, volume `account-data`), só quando `VARANDA_INVITE_DROPS` está ligado | Execução de contrato (a confirmar em parecer); finalidade: espalhar os convites ao longo da semana | O segredo enquanto o recurso existir; o `invite-drops.json` é podado no fim da semana de Brasília | diff --git a/docs/protocol.md b/docs/protocol.md index c1ffec4d0..d5d15e1bb 100644 --- a/docs/protocol.md +++ b/docs/protocol.md @@ -107,7 +107,7 @@ Member recovery: extra passkeys and the recovery code (`packages/web-member/lib/ - The account service's directory (`apps/cli/lib/account/store.js`, data dir mode `0o700`) is three kinds of file. `directory.json` is the snapshot `{ v, seq, journal, links, bySub, byUsername, usedNames }` (a file without `seq` is seq 0; `journal` only in `v` 2; `deleted`, a map from a deleted member key to `{ at }`, only once an account was deleted, see "Account deletion"), written through `writeJsonAtomic` with mode `0o600`; every link record must be whole (`sub`, `username` and `email` strings, `usernameChangedAt` and `linkedAt` parseable dates, `cert` and `usernameRecord` objects) or the open fails closed. `directory.journal.` is the journal (never named `*.log`, so log rotation does not match it; `` a random 16-byte hex id): NDJSON whose first line is the header `{ "journal": "" }` (written and fsynced before any change line) and whose later lines are one change each `{ seq, op: 'link' | 'email' | 'rename' | 'delete', member, ... }` (`delete` carries only `at`: the link leaves `links` and `bySub`, the key enters `deleted`, and every name it held stays in `usedNames` held by the deleted key, which a build without `deleted` refuses, so it is a one-way migration like the first page; the hwm counts links plus deleted rows, so a deletion never reads as a restored copy); it is created `O_EXCL|O_NOFOLLOW` and every read-write open calls `fchmod(0o600)` on it. `directory.hwm` is the high-water mark `{ seq, journal, links, names }` (`writeJsonAtomic`, mode `0o600`): the highest committed `seq` with the link and `usedNames` counts at that mark, written under the writer guard after every compaction and at close, and never lowered (a stored mark above the new one makes the store unavailable instead). Each change is one `write` and one `fsync`, and the fsynced append is the commit point; a failed journal `fsync` (or a write that may have put bytes in the file) makes the store unavailable (`indisponivel`) and the line is never adopted. `v` is `2` while the journal may hold lines and `1` after a clean close (`close()`: compaction, the hwm, a complete `v` 1 snapshot without `journal`, then the journal unlinked; a close that fails leaves the store open for a retry and the service logs `close falhou` and exits 1); a build that knows only `v` 1 refuses `v` 2 (`diretório de contas inválido`). A `v` 2 snapshot is bound to its journal: a missing or empty journal, one without a header, or one whose header carries another id fails closed at every open (read-write and read-only), so a deleted, rotated or truncated journal never makes names or Google accounts reusable. A journal file the snapshot does not name is an orphan (a crash between two steps below); readers ignore it, a read-write open removes it after its own snapshot write, only once its mtime is older than `ORPHAN_GRACE_MS` = 40000 ms (the lock's staleness plus a heartbeat) and after reading `directory.json` again (an id it names is skipped) under the writer guard; an orphan with a line past the snapshot's `seq` fails closed unless the named journal holds the identical line at that `seq` (a crash after the fold and before the unlink of a retired journal). A journal file is never truncated or rewritten once another process may hold it: the journal's start and every compaction (after `COMPACT_EVERY` = 256 lines, past `COMPACT_BYTES` = 1048576 bytes, and at every read-write open, which always publishes a fresh journal and a new snapshot naming it, also over a header-only journal) create a NEW file with a new id (header fsynced, data dir fsynced), rewrite the snapshot as `v` 2 naming it at the current `seq`, and only then unlink the previous file; lines a stalled writer landed in the previous file meanwhile are folded into the new one before and right after the unlink (through a read fd kept open across it). Before every append and every snapshot write, and again after each append's `fsync` before the line is acknowledged, the writer checks (`fstat` of its fd, `lstat` of the paths) that the journal is the same file (device, inode, link count above 0) with exactly the size it expects and that `directory.json` is the file (device, inode) it last read or wrote; any difference makes the store unavailable without writing (or without acknowledging the line just written), so another writer's open fences a stalled one and the unlink of its journal (nlink 0) ends it; the `account` service also marks the store unavailable as soon as its lock is lost. The guard and the write stay separate syscalls (no OS file locks): a write landing in the retired file after the new writer's last fold is refused to its client, never acknowledged. A snapshot rename whose data dir `fsync` failed is fsynced again before the next change is acknowledged. Readers resolve the journal by the id the snapshot names, replay the lines with `seq` above the snapshot's, ignore a torn trailing line, and read again (up to `OPEN_RETRIES` = 3 retries) when the snapshot's `v`, `seq` or journal id changed while they read; a gap in `seq` or a line that breaks an invariant fails closed. A read-write open whose snapshot+journal end below the hwm refuses with `diretório de contas restaurado de uma cópia antiga; confira o backup` (code `RESTAURADO`): by `seq` for a snapshot with `seq`, by the link and `usedNames` counts alone for a snapshot without it (written by an older build, whose `seq` restarted; one that passes continues the numbering from the mark's `seq`); a read-only open reports it (`restored`) and still reads. Read-only opens never write, unlink, chmod or create anything. Never rotate or delete a `directory.journal.*`; back up the three files together with the service stopped, but restore only `directory.json` and its `directory.journal.*` from the latest backup and KEEP the volume's existing `directory.hwm` (restore the backup's hwm only if the volume lost it), since overwriting the live mark with the backup's would lower it and the restored-copy refusal could never fire (an operator who deliberately restores an older copy deletes `directory.hwm`, README). A phone link is a link record with `sub` `'telefone:'` plus the member key (lowercase hex64, `phoneSub` in `apps/cli/lib/account/store.js`) and `email` `''`, written only by a phone finish (`store.finish` with `phone: true`). The label passes `SUB_RE` (`packages/core/lib/account-link.js`), `validLink` and `indexes()`, so it needs no new journal op, field or migration: an older build reads the record as an ordinary link. `bySub` stays one sub to one member, including an earlier member's Google sub. Nothing erases that sub or its e-mail. The number is not stored in the directory. `POST /account/finish` (`apps/cli/lib/account/server.js`) is in phone mode when phone verification is on and the pending row is still phase `'reserve'` with no `sub`, on the cookie path and on the app `V` path (`x-varanda-link`). `V` (`x-varanda-link`) is the bearer proof of an app row. The member Google sign-in is retired, so the redeem code `R` (`x-varanda-redeem`) is never minted. `POST /account/authorize` answers 410 `versao-antiga` before any configuration, proof, store check or outbound request, and builds no Google URL: an installed old build reads that 4xx as a definite refusal and does not retry. `GET /account/callback` reads no query, makes no code exchange and no outbound request, logs `{ event: 'callback', reason: 'aposentado' }` and redirects to `/?conta=erro`. `POST /account/authorize`, `GET /account/callback`, `GET /account/pending` and `GET /account/app/conta` answer the same way when the issuer is missing: they never call `configured()`. The `google` option of `createAccountServer` is ignored. The moderator panel (`/account/mod/*`) keeps its own Google login (`googleMod`, redirect `origin + '/account/mod/callback'`). `VARANDA_GOOGLE_CLIENT_ID` and `VARANDA_GOOGLE_CLIENT_SECRET` stay required because only that panel uses them. With phone verification off the service logs one line, event `cadastro`, which the human line prints as `cadastro de novas contas desligado: verificação de celular não configurada`. The finish statement is verified with `sub` = `phoneSub(member)`. Order after that proof: the finish limit, the age check, the phone check (403 `telefone-pendente` until the member holds a live sealed row), the member added to the server-local linking set (`linking`, a map from member to a count of phone finishes in flight), `await phoneRoutes.settled(member)` (every phone-store call queued before that wait commits or fails; `phones.settled`), the phone check again, then `store.finish({ signature, phone: true })`. The count is dropped in a `finally` (a count above 1 is only decremented). The linked check the phone routes read, on each request, is `store.status(m).linked || linking.has(m)`. A record of the same number for another member queued before this member entered `linking` can still end the row: `settled` lets it land and the second phone check answers `telefone-pendente` with no link. A record queued after the member is in `linking` sees the member as linked and answers `telefone-em-uso`. While the member is in `linking`, `POST /account/start` for that member answers 400 `pedido-invalido` before it touches the store, an invite hold or an app row, and with invites on the row is marked as finishing before the wait. With invites on, `finishInvited` resolves the subject with `memberForSub(row.sub ?? phoneSub(row.member))`, because a phone row has no `sub` yet. An invite code is spent only when the link commits; an unverified member keeps the pending row and the code (403 `telefone-pendente`). `GET /account/pending` answers 404 `expirado` for every caller (a cookie, an app `V`, a redeem code or none) and reads and writes nothing. `GET /account/app/conta` answers 404 `expirado` with or without a query, never echoes the query and never logs it. A finish that is not a phone finish answers 404 `expirado` once the body has a signature and a pending row, and before that signature is verified: phone verification off, a row past phase `'reserve'`, or a row that already holds a `sub` (a subject left by the retired Google callback, which is never finished). A finish with no issuer still answers 503 `indisponivel`. `store.finish` with `phone: true` accepts only a live row in phase `'reserve'` with no `sub`. `account phone --username ` (`lookupPhone` in `apps/cli/lib/commands/account.js`) is read-only and prints at most one JSON line for the name's single holder (`nameHolder`, current or past; a leading `@` is stripped). `kind` is `membro`, `excluido` or `pagina`. A member line is `{ username, key, kind, current, deletedAt, phone }`, and `phone` is the rows `--member` would print (an empty list when there are none). A page prints `owner` and no number, and reads no phone key; a moved page also prints `movedTo`. A page with no `pages.json` row fails with `página sem registro em pages.json`. An unknown name fails with `nome não encontrado`. - `/usage.json` (`apps/cli/lib/account/usage-stats.js`) = `{ v: 1, days: [{ day, members, admitted, activeDay, activeWeek, blocks, bytes, mediaBytes, topicPosts, connections, external }] }`. `day` is the Brasília calendar day (fixed UTC−3; no DST since 2019) of the sample. The account service passes `localDay` from `packages/core/lib/activity.js` (`DAY_OFFSET_MS`, `dayStart`, `localDay`) as `dayOf`, so a history row and the seeder's `activeDay` start the day at the same instant. Each count is a non-negative safe integer or `null` (unknown). Rows are strictly increasing by `day`, one per day, and only the newest `MAX_DAYS` = 400 are kept. The file is replaced whole through `writeJsonAtomic` with mode `0o600`, and only while the account store still allows writes. A path that is not a regular file, or a file whose JSON is not exactly that shape (a day out of order included), is never replaced: it is logged once as `{ event: 'usage', reason: 'invalido' }`, `history` in the stats view is `null`, and the operator can inspect it. A failed write is logged once as `{ event: 'usage', reason: 'falhou' }` until a later write succeeds. `PEAK_FIELDS` = `activeDay`, `activeWeek`, `connections`, `external` keep the day's maximum; `members`, `admitted`, `blocks`, `bytes`, `mediaBytes` and `topicPosts` keep the latest value; a `null` sample never erases a stored count. A sample whose day is earlier than the last row (the clock stepped back) is ignored. The background sample runs `FIRST_SAMPLE_MS` = 60000 ms after start and then every `SAMPLE_MS` = 900000 ms (15 min). Deleting the file only loses the history (the next sample starts a new one). The account service logs `{ event: 'usage', reason: 'ligada' }` when `VARANDA_STATS_EMAILS` turns the feature on and `{ event: 'usage', reason: 'desligada' }` when it is off. Those lines carry no e-mail, key, username or address. - `GET /account/mod/api/stats` (`apps/cli/lib/account/mod-routes.js`) needs a panel session whose e-mail is in `VARANDA_STATS_EMAILS`, and that list must be a subset of `VARANDA_MODERATOR_EMAILS`: `deploy.sh` refuses a list that is not, and so does the account service at start (`VARANDA_STATS_EMAILS inválido`, exit 1); the route also keeps only addresses that are moderators. Anyone else with a session gets 403 `{ "error": "nao-autorizado" }`; a request with no session stays the existing 401 `{ "error": "nao-autorizado" }`. The body is exactly `{ at, members: { total, max }, seeder, signups: { weeks, months }, history }`. `at` is the view time as a canonical ISO string. `members.total` is the number of linked accounts and `members.max` is the member cap or `null`. `seeder` is `null` until a read of `GET /health` succeeds (default `http://127.0.0.1:8788`; loopback `http` with an explicit port only, and the URL is read only while stats are on); otherwise `{ at, uptimeSeconds, admitted, activeDay, activeWeek, blocks, bytes, mediaBytes, topicPosts, connections, external }`, each count a non-negative safe integer or `null` (an older seeder without `activeDay` / `activeWeek` yields `null` for those two). A panel view triggers at most one such read per `FRESH_MS` = 300000 ms (5 min), and concurrent views share the in-flight sample. `signups.weeks` is 12 `{ start, count }` buckets, the weeks ending with the one that contains today, `start` the Monday of that week as `YYYY-MM-DD`; `signups.months` is 12 `{ month, count, total }` buckets, the calendar months ending with the current one, `month` as `YYYY-MM` and `total` the cumulative sign-ups through that month. Both bucket by the Brasília calendar day (fixed UTC−3; no DST since 2019) of `linkedAt` (`localDay`). The sign-up counts are exact: there is no small-cell suppression, because `linkedAt` is the `date` on the member's public certificate. `history` is the `usage.json` rows, oldest first, or `null` when the file is invalid. The body has no report, pending or blocked counts, and never a key, an e-mail, a sub, a username or an address. `GET /account/mod/api/me` carries `stats: true` only for a stats admin; the key is omitted for everyone else, so the unauthenticated body `deploy.sh` probes (`{"error":"nao-autorizado"}\n`, HTTP 401) is unchanged. -- `/recovery.json` (`apps/cli/lib/account/recovery-store.js`) holds the member recovery entries (section 1, "Web member storage (B2)"). It is ONE sidecar file like `terms.json`, mode `0o600`, replaced whole through `writeJsonAtomic`, and never part of `directory.json`, `directory.journal.*` or `directory.hwm`, so older and newer builds keep opening the same data dir. The shape is exactly `{ v: 1, seq, entries, removed }`: `seq` is a non-negative safe integer, the store-wide generation counter; `entries` maps a `lookupId` (hex64) to `{ member, kind, nonce, ciphertext, createdAt, gen }` and `removed` maps a `lookupId` to the tombstone `{ member, removedAt, gen }`; an id is never both, and a `gen` above `seq` makes the file malformed. Opening never creates, mkdirs or chmods anything (a missing file means no entry yet). Validation is total: a file the module would not have written is never rewritten and every recovery call then fails with `indisponivel` until an operator repairs it, while every other route of the service stays up. Every write first re-reads the file and asks the service lock before and after it. Generations are ONE store-wide monotonic sequence, never per id: every put, every remove and every tombstone the normalisation writes takes `gen` = ++`seq`, and a merge takes `seq` = max(memory, disk) and keeps, per id, whichever of row or tombstone has the higher `gen` (ties keep memory), so a remove beats the stale row it buried and a later re-put beats the tombstone, whatever the clocks say. Of two live `'code'` rows of one member after a merge, only the strictly higher `gen` stays and the others become tombstones under fresh gens. Rows tied at the highest `gen` (a stale writer that lost its lock and its replacement both took `seq` + 1) are all kept live: neither write is newer, and choosing by `lookupId` could delete the code that was acknowledged; the next code put buries them all. Tombstone pruning: a tombstone whose `removedAt` is older than 30 days goes; then each member keeps at most 32, dropping the lowest gens first, but the cap never drops a tombstone younger than 10 minutes (`STALE_WINDOW_MS`, which also covers a `removedAt` ahead of this clock) nor the member's newest one, so a member may briefly hold more than 32. A copy of the file older than a pruned tombstone may resurrect that row (accepted: a stale writer's rename lands within one lock period, far inside that window). Reads: after an uncertain write (a failed write, or the lock refused after the rename) `list` and `fetch` first re-read and merge the file, or answer `indisponivel`, never from stale memory. Caps per member: 4 live `'passkey'` rows (a 5th answers 409 `{ "error": "limite-recuperacao" }`) and 1 live `'code'` row (a new code replaces the previous one, whose id becomes a tombstone, so the old code stops opening the account on any device that has not already used it; see "Web member storage (B2)" for why it never revokes past use); tombstones never count. A `lookupId` owned by another member answers `pedido-invalido`. `account export` and `account status` do not include the file. Logs carry only `{ event: 'recovery', reason }`, never a `lookupId`, a blob, a member key or an address. +- `/recovery.json` (`apps/cli/lib/account/recovery-store.js`) holds the member recovery entries (section 1, "Web member storage (B2)"). It is ONE sidecar file like `terms.json`, mode `0o600`, replaced whole through `writeJsonAtomic`, and never part of `directory.json`, `directory.journal.*` or `directory.hwm`, so older and newer builds keep opening the same data dir. The shape is exactly `{ v: 2, seq, entries, removed, floors }`: `seq` is a non-negative safe integer, the store-wide generation counter; `entries` maps a `lookupId` (hex64) to `{ member, kind, nonce, ciphertext, createdAt, gen }` and `removed` maps a `lookupId` to the tombstone `{ member, removedAt, gen }`; an id is never both, and a `gen` above `seq` makes the file malformed. `floors` maps a member key (hex64) to a positive safe integer never above `seq`: the highest `gen` among that member's pruned tombstones. A version 1 file (exactly `{ v: 1, seq, entries, removed }`, no `floors`) is still read as if `floors` were empty; the first write that changes it writes version 2, which an older build refuses as malformed (its recovery routes answer `indisponivel` until the newer build returns). Opening never creates, mkdirs or chmods anything (a missing file means no entry yet). Validation is total: a file the module would not have written is never rewritten and every recovery call then fails with `indisponivel` until an operator repairs it, while every other route of the service stays up. Every write first re-reads the file and asks the service lock before and after it. Generations are ONE store-wide monotonic sequence, never per id: every put, every remove and every tombstone the normalisation writes takes `gen` = ++`seq`, and a merge takes `seq` = max(memory, disk) and keeps, per id, whichever of row or tombstone has the higher `gen` (ties keep memory), so a remove beats the stale row it buried and a later re-put beats the tombstone, whatever the clocks say. Of two live `'code'` rows of one member after a merge, only the strictly higher `gen` stays and the others become tombstones under fresh gens. Rows tied at the highest `gen` (a stale writer that lost its lock and its replacement both took `seq` + 1) are all kept live: neither write is newer, and choosing by `lookupId` could delete the code that was acknowledged; the next code put buries them all. Tombstone pruning: a tombstone whose `removedAt` is older than 30 days goes; then each member keeps at most 32, dropping the lowest gens first, but the cap never drops a tombstone younger than 10 minutes (`STALE_WINDOW_MS`, which also covers a `removedAt` ahead of this clock) nor the member's newest one, so a member may briefly hold more than 32. Pruning a tombstone raises its member's floor to the tombstone's `gen`. A merge takes each member's floor as the max of both copies, and when the holder merges the file into its memory it drops a row only the file holds whose `gen` is at or under memory's floor for that member (memory removed the row and pruned its tombstone), so a stale writer's older copy never resurrects a row whose tombstone a version 2 build pruned. The file's floor never drops a row memory holds: the service takes the lock before it opens the store and fails the store for good when it loses the lock, so memory is never behind the file on their shared history, and a file whose floor passes a row in memory comes from another history (a copy put back after the service started from an older copy or from no file). Such a copy, put back while the service runs, is merged as a union apart from memory's floor. A copy put back while no holder runs is read as it is: with nothing to merge, it lacks the rows written after it and holds again the rows removed after it (README.md, "Vínculo de conta Google e @nome", describes the backup and the restore). Reads: after an uncertain write (a failed write, or the lock refused after the rename) `list` and `fetch` first re-read and merge the file, or answer `indisponivel`, never from stale memory. Caps per member: 4 live `'passkey'` rows (a 5th answers 409 `{ "error": "limite-recuperacao" }`) and 1 live `'code'` row (a new code replaces the previous one, whose id becomes a tombstone, so the old code stops opening the account on any device that has not already used it; see "Web member storage (B2)" for why it never revokes past use); tombstones never count. A `lookupId` owned by another member answers `pedido-invalido`. `account export` and `account status` do not include the file. Logs carry only `{ event: 'recovery', reason }`, never a `lookupId`, a blob, a member key or an address. - Recovery routes (`apps/cli/lib/account/recovery-routes.js`), HTTPS from the app to the account service, never from the swarm; POST only, same origin check and 4096-byte body cap as the other account POSTs; without a usable store every one answers 503 `indisponivel`: - `POST /account/recovery/start` `{ member }` -> `{ nonce }` for a linked member (single use, 10 minutes). The nonce is stateless, like the report nonces: base64url (54 characters) of an 8-byte expiry, 16 random bytes and a 16-byte HMAC-SHA256 under a per-process secret over `'varanda-recovery-nonce-v1'` and the member, so start stores nothing and a restart expires every outstanding nonce. Only the canonical spelling is accepted. Expiry and pruning read a clock that never steps back (the highest wall-clock value seen), so a wall clock corrected backwards cannot revive a spent nonce. A step back of more than one TTL instead draws a new secret, which voids every outstanding nonce, clears the spent set and lets TTLs follow the wall clock again. There is no per-member quota on start (anyone may name any public key, so such a quota would let a stranger lock a member out of removing a leaked code); only the global bucket bounds it. - `POST /account/recovery/put` `{ member, nonce, signature, kind, lookupId, blob }`, `POST /account/recovery/remove` `{ member, nonce, signature, kind, lookupId }` and `POST /account/recovery/list` `{ member, nonce, signature }`. Bodies: put -> `{ createdAt, changed }`, remove -> `{ changed }` (`changed` false for a no-op: the entry was already there, or already gone), list -> `{ entries: [{ lookupId, kind, createdAt }] }` (never the nonce or ciphertext). For each: the nonce must be one this process minted for that member, live and not yet spent; then the statement is verified with the service's association and, for put, `blobHash` recomputed from the validated blob; a per-member window (10 per 600 s) is charged only after the proof, then the nonce is recorded as spent until its own expiry (a refused proof spends nothing, so the spent set grows only with validly signed requests), then the link is checked, then the store. A put or remove that fails after a possible write (answered 503 `resultado-incerto`: a lost lock or a failed write) is an unknown outcome: the app keeps its unknown-outcome handling and never retries by itself; listing settles it. @@ -854,7 +854,7 @@ A member deletes the account from the app (`apps/cli/lib/account/delete-routes.j - Passkey enrolment (`apps/cli/lib/account/passkey-routes.js`): right after the account link, the app sends the creation's attestation object of the passkey that created the identity. `POST /account/passkey/start` `{ member }` -> `{ nonce }` (a linked member; single-use, in memory, 600 s) and `POST /account/passkey/add` `{ member, nonce, signature, credentialId, attestationObject }` -> `{ added }`: `signature` is the account-link statement at phase `'passkey'` over the nonce and the current @nome, with `sub` = the lowercase hex SHA-256 of the attestation object's bytes; it is charged per member after it verified. The key is read from the attestation object (`keyFromAttestation`: a CBOR map of exactly `fmt`, `attStmt` and `authData`, at most 2048 bytes; the authenticator data's rpIdHash, the attested credential id equal to `credentialId`, UP, and a COSE key that is EC2 P-256 with ES256 or RSA of 2048 to 4096 bits with RS256, imported by node:crypto); the attestation statement is not checked (creations use attestation `'none'`). It is accepted only while the member has no stored key AND `linkedAt` is at most 1 hour old (`LINK_WINDOW_MS`): that is the only moment a key is trusted on first use. Refusals: 403 `passkey-invalida` (the attestation does not parse or match), 409 `passkey-registrada` (another key is stored; a stored key is never replaced), 409 `vinculo-antigo` (the window passed). The same credential again answers `{ added: false }`. - `/passkeys.json` (`apps/cli/lib/account/passkey-store.js`) holds the stored keys and the waiting deletions. One sidecar like `recovery.json`, mode `0o600`, replaced whole through `writeJsonAtomic`, never part of `directory.json` or its journal. The shape is exactly `{ v: 1, seq, members, removed }`: `members` maps a member key to `{ keys: [{ credentialId, alg, spki, signCount, addedAt }], hold: null | { at, runAt }, gen }` (at most 4 keys, `alg` -7 or -257, `spki` the lowercase hex DER SubjectPublicKeyInfo); `removed` maps a deleted member to `{ removedAt, gen }`, pruned after 30 days. Every change to a member takes `gen = ++seq` for the whole record, and a merge keeps, per member, the record or tombstone with the higher gen (ties keep memory), so a stale copy can never bring back a cancelled deletion. Validation is total, as for `recovery.json`; an unusable file makes Excluir conta and the enrolment answer 503 `indisponivel`. - The panel shows a `titular` change as asked by the person. `POST pending//cancel` of it, or of any other change of a deleted key, answers 409 `conta-excluida`, and so does `POST unblock` of a deleted key or of a key with an owner block pending (the store refuses that too, also in the window where the directory write failed). Only the operator's own `mod unblock`, at a terminal, can undo it. `mod apply` prints such a block as `bloquear (exclusão pedida pela pessoa)`, and `--yes` signs it like any human block. -- What the service deletes: the link (sub, e-mail, certificate, records, invite id), `terms.json`, `age.json`, `push.json`, `recovery.json` (each entry leaves the store's usual tombstone with the public key, 30 days), the invites the member issued (`invites.json`), the surprise-invite marks (`invite-drops.json`), the encrypted seen blob (`seen/`, through the store's compare-and-swap; a conflict waits for the next sweep) and the stored passkey keys with any waiting deletion (`passkeys.json`, a 30-day tombstone with the public key). What stays: the deleted row (public key and date) and every @nome the key held, burned (`usedNames`); reports and decisions in `moderation.json` (retention open, issue #38); the access logs, if they apply. The deletion sweep runs after every request, at every start and every hour, so a store that could not be purged at once (unavailable, a failed write, or rows a stale writer's union merge brought back) is purged later; logs carry counts only. +- What the service deletes: the link (sub, e-mail, certificate, records, invite id), `terms.json`, `age.json`, `push.json`, `recovery.json` (each entry leaves the store's usual tombstone with the public key for 30 days, then the member's floor, the public key and a `gen`, with no time limit), the invites the member issued (`invites.json`), the surprise-invite marks (`invite-drops.json`), the encrypted seen blob (`seen/`, through the store's compare-and-swap; a conflict waits for the next sweep) and the stored passkey keys with any waiting deletion (`passkeys.json`, a 30-day tombstone with the public key). What stays: the deleted row (public key and date) and every @nome the key held, burned (`usedNames`); reports and decisions in `moderation.json` (retention open, issue #38); the access logs, if they apply. The deletion sweep runs after every request, at every start and every hour, so a store that could not be purged at once (unavailable, a failed write, or rows a stale writer's union merge brought back) is purged later; logs carry counts only. - A page delegate (section 12) whose diary was deleted is refused (`nao-vinculado`) before the block reaches it. The age routes refuse a deleted key (`POST /account/age/session` and `/result` answer 409 `conta-excluida`; a provider session opened before the deletion is closed there), so it never pays for, nor shows anything to, the provider and never gets a band again. Pages where the member was only an admin keep the key in their roster until the owner removes it (that needs the owner's signed roster); the service refuses every action of the deleted key at once. - On the device, after a deletion that ran now, the app wipes the account as `identity.reset()` does and keeps only `{ v: 1, member, at }` (public key and date) to show, at Entrar, when the deletion completed. A scheduled deletion wipes nothing: every signed-in device shows the date with a way to cancel, and once it runs each device meets the notice below. Another device still signed in with the same passkey meets a notice when it reads `/account/status`, and erases the account there. A diary key cannot be revoked (the passkey derives it again), so the account service refuses that key for good: `start` answers `conta-excluida` and the directory never links it, reserves it or makes it a page. - Limits: a key is trusted on first use, at sign-up: someone who controls the person's device during the hour after the link could enrol a forged authenticator instead. An unlocked session holds the diary key, so it can always schedule a deletion; the person then sees it on every signed-in device (and in a push, when notices are on) and can cancel it for 7 days, but a person who opens no device in that time loses the account. Extra passkeys are not enrolled, so a person whose only stored passkey is gone waits the 7 days. iOS may give no attestation object at creation (`rawAttestationObject` is optional), and the iOS origin is expected to be `https://`: both are device checks (`docs/verification.md` section 116). The list holds at most 4096 keys (`MAX_BLOCKED`), and every deletion keeps one; copies on modified apps and devices that ignore the list are not reached; `directoryFloor` (`apps/cli/lib/account/age-check-state.js`) is read from the live links only, so after a restart it no longer counts a deleted member who had no age band, which matters only until the block reaches that diary. diff --git a/docs/verification.md b/docs/verification.md index f28b171d7..dc490a78e 100644 --- a/docs/verification.md +++ b/docs/verification.md @@ -5416,7 +5416,7 @@ Nenhuma verificação foi feita ainda. Marcar só o que for de fato executado, c - A flag BE é autodeclarada pelo autenticador quando a atestação é `none`; o app não consegue provar que o gerenciador sincroniza. - Dados de autenticação ilegíveis são aceitos, então um autenticador que não informa a flag passa na criação. - As dicas (`client-device`, `hybrid`) são só orientação: não forçam a tela do QR code. -- No Android, a limpeza de passkeys é só exclusão, e só com androidx.credentials 1.5.0. +- No Android, a limpeza de passkeys é só exclusão, e depende de androidx.credentials 1.5.0 ou mais novo, fixado em versão exata no `build.gradle` do módulo; `apps/app/test/passkeyPrfAndroid.test.js` falha se a versão cair ou deixar de ser exata (#444). - No iOS nativo, o domínio associado já está no projeto (`Varanda.entitlements`); entrar com passkey numa instalação de produção depende da conta Apple Developer. - O build de debug do Android (`app.varanda.debug`) não usa passkeys de produção. - Entrar com uma passkey do Varanda antiga, num aparelho sem diário, ainda abre um diário vazio. @@ -5482,9 +5482,7 @@ Nenhuma verificação foi feita ainda. Marcar só o que for de fato executado, c - Remover ou trocar uma entrada não troca a raiz: quem buscou aquele blob enquanto a entrada valia e tem o segredo dela ainda abre a conta. Isso vem do desenho da raiz embrulhada. Remover a entrada ou criar um código novo só impede novas entradas num aparelho que ainda não a usou; quem já entrou com ela, ou um aparelho ainda aberto com ela, continua com acesso, porque a chave da conta não pode ser trocada. Se uma passkey adicionada ou o código vazar, o único caminho seguro é criar uma conta nova. O cartão do código, a confirmação de código novo e as duas confirmações de remover dizem isso, e os Termos e a Política também (a versão continua 17). - Cancelar a recuperação não desfaz o que já terminou: uma instalação que concluiu antes do cancelamento continua (a conta fica aberta e presa à passkey nova), uma passkey criada durante a cerimônia continua no gerenciador (o Varanda não consegue apagá-la; no navegador ela fica recusada como `SUPERSEDED` e fora das próximas criações) e um put já enviado ao serviço pode ter sido gravado (a lista confirma). - Remover uma entrada não desconecta um aparelho que já desembrulhou a raiz com ela. -- Se o disco do serviço se perder, as entradas somem: o membro entra com a passkey original ou num aparelho ainda conectado e cadastra de novo. -- Uma cópia de `recovery.json` mais antiga que uma lápide já podada pode trazer de volta aquela linha. -- Só membros com vínculo Google cadastram entradas. +- Se o disco do serviço se perder sem cópia, as entradas somem: o membro entra com a passkey original ou num aparelho ainda conectado e cadastra de novo. Uma cópia restaurada não tem as entradas cadastradas depois dela e volta a ter as removidas depois dela; o README descreve a restauração e o aviso aos membros (#444). ## 111. Busca de GIFs pelo serviço de conta (PR feat/gif-search) diff --git a/docs/verification/fix-recovery-store-floor.md b/docs/verification/fix-recovery-store-floor.md new file mode 100644 index 000000000..464e7cae8 --- /dev/null +++ b/docs/verification/fix-recovery-store-floor.md @@ -0,0 +1,47 @@ +# Marca por membro no recovery.json (branch fix/recovery-store-floor) + +Parte da #444. O `recovery.json` (`apps/cli/lib/account/recovery-store.js`) apaga registros de remoção com mais de 30 dias (`TOMBSTONE_TTL_MS`) e guarda no máximo 32 por membro. Antes, apagado o registro, uma cópia mais antiga do arquivo unida à atual (`heal()`, a leitura depois de uma gravação incerta, a união antes de cada gravação, ou um backup restaurado com o serviço no ar) trazia de volta a entrada removida. + +## O que muda + +- Formato versão 2: `{ v: 2, seq, entries, removed, floors }`. `floors` liga a chave do membro (64 hex) a um `gen` (inteiro positivo, no máximo `seq`). +- Todo registro de remoção apagado, pelo prazo ou pelo teto por membro, sobe a marca do membro até o `gen` dele. A marca só sobe; a união fica com o maior valor por membro. +- Quando o serviço une o arquivo à memória, uma entrada que só o arquivo tem sai quando o `gen` dela é menor ou igual à marca da memória para aquele membro. A marca do arquivo nunca tira uma entrada da memória: o serviço pega a trava antes de abrir o arquivo e para de vez ao perdê-la, então a memória nunca está atrás do arquivo na mesma história, e um arquivo com marca acima de uma entrada da memória vem de outra história (uma cópia posta de volta depois de o serviço começar de uma cópia mais antiga ou sem arquivo). A marca da própria cópia também não conta. +- Arquivo versão 1 continua sendo lido (sem marcas); a próxima gravação que muda algo escreve a versão 2. Nada é regravado só para trocar a versão. +- Validação total: `floors` ausente na versão 2, presente na versão 1, membro fora do formato, `gen` não inteiro, zero, negativo ou acima de `seq`, ou chave a mais tornam o arquivo inválido, como os demais casos (o serviço não o regrava e responde `indisponivel`). + +## Comandos e resultados + +Da raiz, um arquivo por vez: + +- `node apps/cli/test/recovery-store.test.js`: 39 testes, 390 asserções, todos passam (antes 29 testes). Novos: + - "a tombstone pruned by the TTL leaves a floor: an older copy never brings its row back" (por `heal()` e pela união antes de um `put`); + - "the file's floor never drops a row memory holds: a copy from another history is merged" (o serviço começou sem arquivo, o membro cadastrou de novo e uma cópia anterior, com marca acima dessa entrada, volta com o serviço no ar); + - "removeMember, then the TTL: an older copy never brings the member's rows back" (Excluir conta seguida do prazo de 30 dias); + - "a read after an uncertain write never brings back a row under the floor" (`fetch` e `list` depois de uma gravação recusada após o rename); + - "a tombstone pruned by the per-member cap leaves a floor: an older copy never brings its row back"; + - "a version 1 file is read, and the next write that changes it is version 2"; + - "a version 1 file whose tombstone expired is rewritten as version 2 with the floor"; + - "a malformed floor makes the file malformed"; + - "floors merge as the max per member"; + - "the floor drops only rows at or under it, of its member, that its own copy lacks". +- `node apps/app/test/passkeyPrfAndroid.test.js`: 2 testes, 11 asserções, passam. Confere que `androidx.credentials:credentials` e `androidx.credentials:credentials-play-services-auth` em `apps/app/modules/passkey-prf/android/build.gradle` aparecem uma vez cada, com versão exata (sem `+`, intervalo nem variável) e no mínimo 1.5.0, comparando os números. +- `npx standard` nos arquivos alterados: sem apontamentos. + +## Falha sem a correção + +Conferido em 17/11/2026, com o código restaurado depois: + +- Com `raiseFloor` sem efeito (nenhuma marca é criada): 31/39 testes, 366/390 asserções. Falham os testes de regressão (por exemplo "not back in memory", "not back on disk"), o de Excluir conta e os de marca e de versão 1. +- Com a regra nos dois sentidos (a marca do arquivo também tirando entradas da memória): 38/39 testes, 387/390 asserções; falha "the row memory holds stays". +- Com `credentials-play-services-auth:1.4.0`: "is at least 1.5.0: 1.4.0" falha. Com `credentials:1.5.+`: "has an exact version: 1.5.+" falha. O `build.gradle` voltou ao original (`git diff apps/app/modules` vazio). + +## Limites + +- Só servidor e um teste de texto do app: nenhuma conferência em aparelho é necessária. +- O procedimento de restauração de backup do operador está no README, no mesmo PR. +- A marca só age numa união de duas cópias. Uma cópia antiga posta no lugar com o serviço parado é lida como está: perde o que foi escrito depois dela e volta a ter o que foi removido depois dela. +- Voltar a uma versão anterior do serviço depois que o arquivo virou versão 2 deixa `/account/recovery/*` em 503 até a versão nova voltar. +- Uma cópia de outra história posta de volta com o serviço no ar entra como união, só com a marca da memória: as entradas que aquela história removeu podem voltar. +- Registros de remoção apagados por uma versão anterior do serviço, antes da versão 2, não deixaram marca. +- A frase da Política de Privacidade sobre o que fica das entradas de recuperação depois da exclusão ("por 30 dias") passa a citar a marca no PR das passkeys extras, que muda a versão dos Termos.