Merge pull request #1135 from MBombeck/fix/cycle-backup-and-med-put

fix(backup): carry encrypted free text readable in portable backups
This commit is contained in:
Marc-André Bombeck authored and GitHub committed 2026-10-04 12:23:35 +02:00
commit 32de7ecf37
31 files changed
+2336 -612

No files matched your search

@@ -138,6 +138,30 @@ describe("assessBackupKeys", () => {
).toEqual([]);
});
it("leaves the cycle sections to the restore, which opens each value itself", () => {
// A same-id impostor in a cycle note must neither refuse the file nor be
// picked as the sample that proves the key for the sections that need it.
const fine = encrypt("a measurement note under the real key");
useKeys({ old: K3, cur: K2 }, "old");
const impostor = encrypt("x");
useKeys({ old: K1, cur: K2 }, "cur");
const file = {
measurements: [{ notesEncrypted: fine }],
cycleDayLogs: [
{ notesEncrypted: impostor },
{ notesEncrypted: `gone.${Buffer.alloc(40).toString("base64")}` },
],
customSymptoms: [
{ labelEncrypted: `gone.${Buffer.alloc(40).toString("base64")}` },
],
};
const collector = new BackupKeyIdCollector();
collector.visit(file);
const verdict = assessBackupKeys(collector);
expect(verdict.missing).toEqual([]);
expect(verdict.unreadable).toEqual([]);
});
it("catches an id that is configured with different key material", () => {
const file = fileWrittenUnderOld();
useKeys({ old: K3, cur: K2 }, "cur");
+40 -2
View File
@@ -97,6 +97,32 @@ export function isEncryptedMember(name: string): boolean {
return name.endsWith("Encrypted") && name.length > "Encrypted".length;
}
/**
* Sections whose restore opens every inner value with this host's keys itself,
* and keeps out (and names in the skip report) any value it cannot open.
*
* The cycle day-logs, custom cycle symptoms, custom mood tags and mood
* categories, practitioners, visits and vaccinations are here because a
* portable file written before v1.40 carried their free text as the stored
* ciphertext,
* not as readable text. Such a file is still restorable onto another host:
* what that host can open comes back, what it cannot stays out of the row and
* is reported. Refusing the whole file over a note would cost every other
* part of the account. The trade, stated: a disaster-recovery copy whose ONLY
* missing key sits in these sections restores with those values reported as
* skipped instead of being refused; any other section needing the key still
* refuses it, which in practice is every real copy.
*/
export const RESTORE_SELF_VERIFIED_SECTIONS: ReadonlySet<string> = new Set([
"cycleDayLogs",
"customSymptoms",
"customMoodTags",
"customMoodTagCategories",
"practitioners",
"encounters",
"vaccinations",
]);
interface KeyUse {
/** How many values need this key. */
count: number;
@@ -127,7 +153,10 @@ export class BackupKeyIdCollector {
}
use.count += 1;
use.sections.add(section);
// A sample from a self-verified section proves nothing the restore needs:
// a value there that does not open is skipped, not fatal.
if (
!RESTORE_SELF_VERIFIED_SECTIONS.has(section) &&
value.length <= MAX_SAMPLE_CHARS &&
(!use.sample || value.length < use.sample.value.length)
) {
@@ -257,7 +286,9 @@ function openSample(sample: { value: string; form: InnerCiphertextForm }) {
* key to prove the key under that id is the right one.
*
* `ignoreSections` leaves out sections the caller will not write: the
* instance settings, when the operator has not asked for them back.
* instance settings, when the operator has not asked for them back. The
* sections in {@link RESTORE_SELF_VERIFIED_SECTIONS} are always left out,
* because their restore checks each value itself.
*/
export function assessBackupKeys(
collector: BackupKeyIdCollector,
@@ -274,7 +305,14 @@ export function assessBackupKeys(
for (const [keyId, use] of [...collector.entries()].sort(([a], [b]) =>
a.localeCompare(b),
)) {
if ([...use.sections].every((section) => ignore.has(section))) continue;
if (
[...use.sections].every(
(section) =>
ignore.has(section) || RESTORE_SELF_VERIFIED_SECTIONS.has(section),
)
) {
continue;
}
keyIds.push(keyId);
configured ??= new Set(getConfiguredKeyIds());
if (!configured.has(keyId)) {
+22 -5
View File
@@ -25,6 +25,7 @@ import { dayKeyOfDate } from "@/lib/medications/course-window";
import { Buffer } from "node:buffer";
import type { Prisma, PrismaClient } from "@/generated/prisma/client";
import { readNote } from "@/lib/crypto/note-cipher";
import { openSealedForExport } from "@/lib/export/sealed-text";
import { iterateMeasurementPages } from "@/lib/export/paged-measurements";
import { BACKUP_SCHEMA_VERSION } from "@/lib/validations/backup";
import {
@@ -1284,8 +1285,18 @@ export async function buildFullBackupPayload(
icon: category.icon,
sortOrder: category.sortOrder,
isActive: category.isActive,
// Ciphertext verbatim, like the tag label beside it.
labelEncrypted: category.labelEncrypted,
// The person's own words: ciphertext in a disaster-recovery payload,
// readable in a portable one (see `sealed-text.ts`).
...(disasterRecovery
? { labelEncrypted: category.labelEncrypted }
: {
label: category.labelEncrypted
? openSealedForExport(
category.labelEncrypted,
"mood category label",
)
: null,
}),
})),
hiddenMoodTags: hiddenMoodTags.map((hidden) => ({
key: hidden.moodTag.key,
@@ -1300,9 +1311,15 @@ export async function buildFullBackupPayload(
isActive: tag.isActive,
icon: tag.icon,
sortOrder: tag.sortOrder,
// Ciphertext verbatim, like every other *Encrypted column in a DR
// payload: the same instance's key reads it back unchanged.
labelEncrypted: tag.labelEncrypted,
// Ciphertext in a disaster-recovery payload (the same instance's key
// reads it back), readable in a portable one (see `sealed-text.ts`).
...(disasterRecovery
? { labelEncrypted: tag.labelEncrypted }
: {
label: tag.labelEncrypted
? openSealedForExport(tag.labelEncrypted, "mood tag label")
: null,
}),
scaleMin: tag.scaleMin,
scaleMax: tag.scaleMax,
inverse: tag.inverse,
+125 -102
View File
@@ -66,6 +66,7 @@ import {
listTenantEdges,
} from "@/lib/export/tenant-boundary";
import { encryptNote } from "@/lib/crypto/note-cipher";
import { sealForRestore } from "@/lib/export/sealed-text";
import { encryptToBytes } from "@/lib/ai/coach/bytes-codec";
import { encryptContextToBytes } from "@/lib/labs/biomarker-store";
import { encryptNoteToBytes } from "@/lib/labs/store";
@@ -1514,6 +1515,130 @@ export async function restoreBackup(
}
reportSection("mood");
// The account's own categories, tags and hidden set are written
// whether or not the file carries a mood entry: an account that set
// up its mood vocabulary before logging a single entry has them too,
// and they used to be written only inside the entries branch.
// The account's own CATEGORIES go in before its tags. A custom
// tag's `categoryId` is a real foreign key, so writing the tag
// first threw `mood_tags_category_id_fkey` and rolled the entire
// restore back — an account that had grouped its own mood factors
// could not be restored at all, and the failure named a constraint
// rather than the thing that was missing.
//
// Upserted by key for the same reason the tags below are: `key` is
// globally unique, so a seeded category that later claims the key
// must be left alone rather than overwritten by a restore.
// Labels this host's keys do not open, by file path.
const unopenedMoodLabels: string[] = [];
for (const category of payload.customMoodTagCategories) {
await tx.moodTagCategory.upsert({
where: { key: category.key },
create: {
id: category.id,
userId: ownerId,
key: category.key,
labelKey: category.labelKey,
icon: category.icon ?? null,
sortOrder: category.sortOrder ?? 0,
isActive: category.isActive ?? true,
labelEncrypted: sealForRestore(
category.labelEncrypted,
category.label,
`customMoodTagCategories.${category.key}.labelEncrypted`,
unopenedMoodLabels,
),
},
update: {},
});
}
// Re-create the account's own tag definitions first. The lookup
// below used to ask only for the seeded catalogue (`userId: null`),
// so a single custom rated tag made the whole restore throw
// "Unknown mood factor keys" — the file was complete and unusable.
for (const tag of payload.customMoodTags) {
await tx.moodTag.upsert({
where: { key: tag.key },
create: {
...(tag.id ? { id: tag.id } : {}),
userId: ownerId,
key: tag.key,
labelKey: tag.labelKey,
categoryId: tag.categoryId,
kind: tag.kind,
isActive: tag.isActive,
icon: tag.icon ?? null,
sortOrder: tag.sortOrder,
labelEncrypted: sealForRestore(
tag.labelEncrypted,
tag.label,
`customMoodTags.${tag.key}.labelEncrypted`,
unopenedMoodLabels,
),
scaleMin: tag.scaleMin,
scaleMax: tag.scaleMax,
inverse: tag.inverse,
},
// `key` is globally unique, so a seeded key would collide.
// Leave the catalogue row alone; the links resolve either way.
update: {},
});
}
recordUnknownKeys(
skips,
"moodLabelCiphertext",
unopenedMoodLabels,
unopenedMoodLabels,
);
// Which tags the account hid. Delete-then-recreate like every
// other section, and resolved by KEY: what people hide is almost
// always a seeded tag, whose id differs on every instance.
//
// A key this instance no longer knows costs one hidden row and is
// REPORTED. Dropping it silently would un-hide a factor the person
// had deliberately taken out of their mood editor, and they would
// have no way to know why it came back.
await tx.moodTagHidden.deleteMany({ where: { userId: ownerId } });
if (payload.hiddenMoodTags.length > 0) {
const hiddenKeys = payload.hiddenMoodTags.map((h) => h.key);
const hiddenRows = await tx.moodTag.findMany({
where: {
key: { in: [...new Set(hiddenKeys)] },
OR: [{ userId: null }, { userId: ownerId }],
},
select: { id: true, key: true },
});
const hiddenByKey = new Map(
hiddenRows.map((row) => [row.key, row.id]),
);
const unresolvedHidden: string[] = [];
const writableHidden = payload.hiddenMoodTags.filter((entry) => {
if (hiddenByKey.has(entry.key)) return true;
unresolvedHidden.push(entry.key);
return false;
});
if (writableHidden.length > 0) {
await tx.moodTagHidden.createMany({
data: writableHidden.map((entry) => ({
userId: ownerId,
moodTagId: hiddenByKey.get(entry.key)!,
...(entry.createdAt
? { createdAt: new Date(entry.createdAt) }
: {}),
})),
skipDuplicates: true,
});
}
recordUnknownKeys(
skips,
"moodTag",
[...new Set(unresolvedHidden)],
unresolvedHidden,
);
}
if (payload.moodEntries.length > 0) {
const referencedFactorKeys = payload.moodEntries.flatMap((entry) =>
entry.factors.map((factor) => factor.key),
@@ -1523,108 +1648,6 @@ export async function restoreBackup(
(entry) => entry.structuredTags,
);
const tagKeys = [...new Set(referencedTagKeys)];
// The account's own CATEGORIES go in before its tags. A custom
// tag's `categoryId` is a real foreign key, so writing the tag
// first threw `mood_tags_category_id_fkey` and rolled the entire
// restore back — an account that had grouped its own mood factors
// could not be restored at all, and the failure named a constraint
// rather than the thing that was missing.
//
// Upserted by key for the same reason the tags below are: `key` is
// globally unique, so a seeded category that later claims the key
// must be left alone rather than overwritten by a restore.
for (const category of payload.customMoodTagCategories) {
await tx.moodTagCategory.upsert({
where: { key: category.key },
create: {
id: category.id,
userId: ownerId,
key: category.key,
labelKey: category.labelKey,
icon: category.icon ?? null,
sortOrder: category.sortOrder ?? 0,
isActive: category.isActive ?? true,
labelEncrypted: category.labelEncrypted ?? null,
},
update: {},
});
}
// Re-create the account's own tag definitions first. The lookup
// below used to ask only for the seeded catalogue (`userId: null`),
// so a single custom rated tag made the whole restore throw
// "Unknown mood factor keys" — the file was complete and unusable.
for (const tag of payload.customMoodTags) {
await tx.moodTag.upsert({
where: { key: tag.key },
create: {
...(tag.id ? { id: tag.id } : {}),
userId: ownerId,
key: tag.key,
labelKey: tag.labelKey,
categoryId: tag.categoryId,
kind: tag.kind,
isActive: tag.isActive,
icon: tag.icon ?? null,
sortOrder: tag.sortOrder,
labelEncrypted: tag.labelEncrypted ?? null,
scaleMin: tag.scaleMin,
scaleMax: tag.scaleMax,
inverse: tag.inverse,
},
// `key` is globally unique, so a seeded key would collide.
// Leave the catalogue row alone; the links resolve either way.
update: {},
});
}
// Which tags the account hid. Delete-then-recreate like every
// other section, and resolved by KEY: what people hide is almost
// always a seeded tag, whose id differs on every instance.
//
// A key this instance no longer knows costs one hidden row and is
// REPORTED. Dropping it silently would un-hide a factor the person
// had deliberately taken out of their mood editor, and they would
// have no way to know why it came back.
await tx.moodTagHidden.deleteMany({ where: { userId: ownerId } });
if (payload.hiddenMoodTags.length > 0) {
const hiddenKeys = payload.hiddenMoodTags.map((h) => h.key);
const hiddenRows = await tx.moodTag.findMany({
where: {
key: { in: [...new Set(hiddenKeys)] },
OR: [{ userId: null }, { userId: ownerId }],
},
select: { id: true, key: true },
});
const hiddenByKey = new Map(
hiddenRows.map((row) => [row.key, row.id]),
);
const unresolvedHidden: string[] = [];
const writableHidden = payload.hiddenMoodTags.filter((entry) => {
if (hiddenByKey.has(entry.key)) return true;
unresolvedHidden.push(entry.key);
return false;
});
if (writableHidden.length > 0) {
await tx.moodTagHidden.createMany({
data: writableHidden.map((entry) => ({
userId: ownerId,
moodTagId: hiddenByKey.get(entry.key)!,
...(entry.createdAt
? { createdAt: new Date(entry.createdAt) }
: {}),
})),
skipDuplicates: true,
});
}
recordUnknownKeys(
skips,
"moodTag",
[...new Set(unresolvedHidden)],
unresolvedHidden,
);
}
const factorRows =
factorKeys.length === 0
? []
+24 -1
View File
@@ -152,6 +152,25 @@
* real foreign key, so the POINTER is dropped and the occurrence restores
* unlinked. A portable export omits soft-deleted episodes, which is the
* ordinary way an occurrence ends up naming one the file does not carry.
*
* The sixteenth, `cycleCiphertext`, is not a reference at all. It names a
* sealed cycle value (a day-log note, the sensitive-category envelope, a
* custom symptom's label) the file carried as ciphertext this host's keys do
* not open — a portable file written before v1.40 on a host with another key.
* Writing it back would store a value no reader can open, so the FIELD is kept
* out and the day or the symptom restores without it. Its key is the path in
* the file (`cycleDayLogs.<date>.notesEncrypted`), never the value.
*
* The seventeenth, `moodLabelCiphertext`, is the same for the label of a mood
* tag or mood category the account created
* (`customMoodTags.<key>.labelEncrypted`): the tag or category restores, under
* its key, without the person's own name for it.
*
* The eighteenth and nineteenth, `visitCiphertext` and `vaccinationCiphertext`,
* are the same again for the free text of the visits record (a practitioner's
* note, address and phone; a visit's reason, outcome and body site) and of a
* vaccination's note (`vaccinations.<id>.noteEncrypted`). The row restores
* without the field.
*/
export type SkippedCatalogue =
| "cycleSymptom"
@@ -172,7 +191,11 @@ export type SkippedCatalogue =
| "scheduleRevisionLink"
| "checkupClosure"
| "accountSetting"
| "symptomEpisodeReference";
| "symptomEpisodeReference"
| "cycleCiphertext"
| "moodLabelCiphertext"
| "visitCiphertext"
| "vaccinationCiphertext";
/** One key this instance does not know, and the links it cost. */
export interface SkippedCatalogueKey {
+134
View File
@@ -0,0 +1,134 @@
/**
* Both ends of a sealed free-text column in a backup section: the string
* codec (`<keyId>.<base64>` in a text column — the cycle day-log note and
* sensitive envelope, custom cycle symptom and mood labels) and the shared
* bytes codec (the practitioner note, the visit's reason, outcome and body
* site, the vaccination note).
*
* The split is the one every other section uses. A disaster-recovery file
* carries the stored ciphertext, which the same instance's key reads back. A
* portable file carries the readable value (or the unreadable marker when
* the writing host could not open it), and the restore seals it under the
* receiving host's active key, because ciphertext from one host is noise on
* another.
*
* Portable files written before v1.40 carried these columns as ciphertext.
* They still restore: a ciphertext value is written back only when this
* host's keys open it. One that does not open is kept out of the row and its
* file path is recorded, so the caller can name it in the skip report rather
* than store a value nobody can read. That per-value check is why the key
* preflight leaves these sections out (`RESTORE_SELF_VERIFIED_SECTIONS`).
*/
import { Buffer } from "node:buffer";
import { decryptFromBytes, encryptToBytes } from "@/lib/ai/coach/bytes-codec";
import { decrypt, encrypt } from "@/lib/crypto";
import { UNREADABLE_EXPORT_MARKER } from "@/lib/export/unreadable-marker";
import { getEvent } from "@/lib/logging/context";
/** Open a sealed value for a portable file, or the unreadable marker. */
export function openSealedForExport(sealed: string, field: string): string {
try {
return decrypt(sealed);
} catch (err) {
getEvent()?.addWarning(
`${field} decrypt failed: ${
err instanceof Error ? err.message : String(err)
}`,
);
return UNREADABLE_EXPORT_MARKER;
}
}
/** A readable value the file could not supply: the writer could not open it. */
export const UNOPENED: unique symbol = Symbol("unopened");
/**
* The sealed column value for one free-text field from the file.
*
* Ciphertext is written back only when this host opens it — a value sealed
* under a key this host does not hold (or the same key id over other key
* material) would be a row nobody can read. A readable value is sealed under
* this host's active key. Anything kept out is recorded under `path`.
*/
export function sealForRestore(
sealed: string | null | undefined,
readable: string | null | undefined | typeof UNOPENED,
path: string,
unopened: string[],
): string | null {
if (sealed) {
try {
decrypt(sealed);
return sealed;
} catch {
unopened.push(path);
return null;
}
}
if (readable === UNOPENED) {
unopened.push(path);
return null;
}
return readable ? encrypt(readable) : null;
}
/**
* The `Bytes` twin of {@link openSealedForExport}, for columns written with
* the shared bytes codec (`encryptToBytes`): the practitioner note, the
* visit's reason, outcome and body site, the vaccination note.
*/
export function openSealedBytesForExport(
sealed: Uint8Array | null,
field: string,
): string | null {
if (!sealed || sealed.byteLength === 0) return null;
try {
return decryptFromBytes(sealed);
} catch (err) {
getEvent()?.addWarning(
`${field} decrypt failed: ${
err instanceof Error ? err.message : String(err)
}`,
);
return UNREADABLE_EXPORT_MARKER;
}
}
/** The stored `Bytes` ciphertext as a disaster-recovery file carries it. */
export function encodeSealedBytes(value: Uint8Array | null): string | null {
if (!value || value.byteLength === 0) return null;
return Buffer.from(value).toString("base64");
}
function decodeBase64(encoded: string): Uint8Array<ArrayBuffer> {
const decoded = Buffer.from(encoded, "base64");
const bytes = new Uint8Array(new ArrayBuffer(decoded.byteLength));
bytes.set(decoded);
return bytes;
}
/**
* The `Bytes` twin of {@link sealForRestore}. `sealed` is the base64 a
* disaster-recovery (or pre-v1.40 portable) file carries; it is written back
* only when this host opens it. A readable value is sealed under this host's
* active key.
*/
export function sealBytesForRestore(
sealed: string | null | undefined,
readable: string | null | undefined,
path: string,
unopened: string[],
): Uint8Array<ArrayBuffer> | null {
if (sealed) {
const bytes = decodeBase64(sealed);
try {
decryptFromBytes(bytes);
return bytes;
} catch {
unopened.push(path);
return null;
}
}
return readable ? encryptToBytes(readable) : null;
}
+27 -21
View File
@@ -35,7 +35,11 @@
* guarantee `src/lib/vaccinations/__tests__/catalog-integrity.test.ts`
* holds.
*/
import { Buffer } from "node:buffer";
import {
encodeSealedBytes,
openSealedBytesForExport,
sealBytesForRestore,
} from "@/lib/export/sealed-text";
import type { Prisma, PrismaClient } from "@/generated/prisma/client";
import type { VaccinationSite } from "@/generated/prisma/client";
@@ -72,8 +76,10 @@ export interface VaccinationBackupEntry {
* lacks the reminder.
*/
reminderId: string | null;
/** Base64 ciphertext, carried verbatim — never decrypted into the file. */
noteEncrypted: string | null;
/** Base64 ciphertext; disaster-recovery payloads only. */
noteEncrypted?: string | null;
/** The note readable; portable payloads only. */
note?: string | null;
createdAt: string;
updatedAt: string;
deletedAt?: string | null;
@@ -96,12 +102,6 @@ export interface VaccinationsBackupCounts {
vaccinationLinks: number;
}
/** Base64 for a `Bytes` ciphertext column, or null when the column is empty. */
function encodeCiphertext(value: Uint8Array | null): string | null {
if (!value || value.byteLength === 0) return null;
return Buffer.from(value).toString("base64");
}
/**
* Named select constants, one per model — a structural matcher binds a model
* to the literal beside its delegate call, and an inline object inside a
@@ -172,7 +172,14 @@ export async function buildVaccinationsBackupSection(
practitionerId: row.practitionerId,
encounterId: row.encounterId,
reminderId: row.reminderId,
noteEncrypted: encodeCiphertext(row.noteEncrypted),
...(disasterRecovery
? { noteEncrypted: encodeSealedBytes(row.noteEncrypted) }
: {
note: openSealedBytesForExport(
row.noteEncrypted,
"vaccination note",
),
}),
createdAt: row.createdAt.toISOString(),
updatedAt: row.updatedAt.toISOString(),
...(disasterRecovery
@@ -240,16 +247,10 @@ export type RestoredVaccination = Pick<
| "encounterId"
| "reminderId"
| "noteEncrypted"
| "note"
>
> & { deletedAt?: string | null };
function decodeCiphertext(encoded: string): Uint8Array<ArrayBuffer> {
const decoded = Buffer.from(encoded, "base64");
const bytes = new Uint8Array(new ArrayBuffer(decoded.byteLength));
bytes.set(decoded);
return bytes;
}
/**
* Re-create the account's immunization log and its document links.
*
@@ -307,6 +308,8 @@ export async function restoreVaccinationsData(
const droppedPractitioners: string[] = [];
const droppedEncounters: string[] = [];
const droppedReminders: string[] = [];
// Sealed notes this host's keys do not open, by file path.
const unopened: string[] = [];
if (payload.vaccinations.length > 0) {
await tx.vaccinationRecord.createMany({
@@ -349,10 +352,12 @@ export async function restoreVaccinationsData(
practitionerId,
encounterId,
reminderId,
noteEncrypted:
entry.noteEncrypted == null
? null
: decodeCiphertext(entry.noteEncrypted),
noteEncrypted: sealBytesForRestore(
entry.noteEncrypted,
entry.note,
`vaccinations.${entry.id}.noteEncrypted`,
unopened,
),
createdAt: new Date(entry.createdAt),
updatedAt: new Date(entry.updatedAt),
deletedAt: entry.deletedAt ? new Date(entry.deletedAt) : null,
@@ -379,6 +384,7 @@ export async function restoreVaccinationsData(
[...new Set(droppedReminders)],
droppedReminders,
);
recordUnknownKeys(skips, "vaccinationCiphertext", unopened, unopened);
const restoredVaccinations = new Set(
payload.vaccinations.map((entry) => entry.id),
+91 -49
View File
@@ -33,7 +33,6 @@
* result ids, so a lab link in one cannot resolve; a disaster-recovery
* payload carries every id and they all do.
*/
import { Buffer } from "node:buffer";
import type { Prisma, PrismaClient } from "@/generated/prisma/client";
import type {
EncounterKind,
@@ -42,6 +41,11 @@ import type {
} from "@/generated/prisma/client";
import { encryptNote } from "@/lib/crypto/note-cipher";
import {
encodeSealedBytes,
openSealedBytesForExport,
sealBytesForRestore,
} from "@/lib/export/sealed-text";
import { readPractitionerContact } from "@/lib/practitioners/dto";
import {
recordUnknownKeys,
@@ -71,8 +75,10 @@ export interface PractitionerBackupEntry {
locationEncrypted?: string | null;
/** Base64 ciphertext of the phone number, disaster-recovery payloads only. */
phoneEncrypted?: string | null;
/** Base64 ciphertext, carried verbatim — never decrypted into the file. */
noteEncrypted: string | null;
/** Base64 ciphertext; disaster-recovery payloads only. */
noteEncrypted?: string | null;
/** The note readable; portable payloads only. */
note?: string | null;
createdAt: string;
updatedAt: string;
deletedAt?: string | null;
@@ -87,10 +93,15 @@ export interface EncounterBackupEntry {
status: EncounterStatus;
kind: EncounterKind;
practitionerId: string | null;
reasonEncrypted: string | null;
outcomeEncrypted: string | null;
/** Base64 ciphertext; disaster-recovery payloads only. */
reasonEncrypted?: string | null;
outcomeEncrypted?: string | null;
/** The procedure's body site, ciphertext like the two above (v1.39.1). */
bodySiteEncrypted: string | null;
bodySiteEncrypted?: string | null;
/** The three readable; portable payloads only. */
reason?: string | null;
outcome?: string | null;
bodySite?: string | null;
laterality: Laterality | null;
/**
* The appointment's reminder row, which restores in the same run since
@@ -124,12 +135,6 @@ export interface VisitsBackupCounts {
encounterLinks: number;
}
/** Base64 for a `Bytes` ciphertext column, or null when the column is empty. */
function encodeCiphertext(value: Uint8Array | null): string | null {
if (!value || value.byteLength === 0) return null;
return Buffer.from(value).toString("base64");
}
/**
* Named select constants, one per model.
*
@@ -256,10 +261,10 @@ export async function buildVisitsBackupSection(
? {
location: null,
phone: null,
locationEncrypted: encodeCiphertext(
locationEncrypted: encodeSealedBytes(
row.locationEncrypted ?? encryptNote(row.location),
),
phoneEncrypted: encodeCiphertext(
phoneEncrypted: encodeSealedBytes(
row.phoneEncrypted ?? encryptNote(row.phone),
),
}
@@ -275,7 +280,14 @@ export async function buildVisitsBackupSection(
"phone",
),
}),
noteEncrypted: encodeCiphertext(row.noteEncrypted),
...(disasterRecovery
? { noteEncrypted: encodeSealedBytes(row.noteEncrypted) }
: {
note: openSealedBytesForExport(
row.noteEncrypted,
"practitioner note",
),
}),
createdAt: row.createdAt.toISOString(),
updatedAt: row.updatedAt.toISOString(),
...(disasterRecovery
@@ -288,9 +300,26 @@ export async function buildVisitsBackupSection(
status: row.status,
kind: row.kind,
practitionerId: row.practitionerId,
reasonEncrypted: encodeCiphertext(row.reasonEncrypted),
outcomeEncrypted: encodeCiphertext(row.outcomeEncrypted),
bodySiteEncrypted: encodeCiphertext(row.bodySiteEncrypted),
...(disasterRecovery
? {
reasonEncrypted: encodeSealedBytes(row.reasonEncrypted),
outcomeEncrypted: encodeSealedBytes(row.outcomeEncrypted),
bodySiteEncrypted: encodeSealedBytes(row.bodySiteEncrypted),
}
: {
reason: openSealedBytesForExport(
row.reasonEncrypted,
"visit reason",
),
outcome: openSealedBytesForExport(
row.outcomeEncrypted,
"visit outcome",
),
bodySite: openSealedBytesForExport(
row.bodySiteEncrypted,
"visit body site",
),
}),
laterality: row.laterality,
reminderId: row.reminderId,
createdAt: row.createdAt.toISOString(),
@@ -380,6 +409,7 @@ export type RestoredPractitioner = Pick<
| "locationEncrypted"
| "phoneEncrypted"
| "noteEncrypted"
| "note"
>
> & { deletedAt?: string | null };
@@ -394,18 +424,14 @@ export type RestoredEncounter = Pick<
| "reasonEncrypted"
| "outcomeEncrypted"
| "bodySiteEncrypted"
| "reason"
| "outcome"
| "bodySite"
| "laterality"
| "reminderId"
>
> & { deletedAt?: string | null };
function decodeCiphertext(encoded: string): Uint8Array<ArrayBuffer> {
const decoded = Buffer.from(encoded, "base64");
const bytes = new Uint8Array(new ArrayBuffer(decoded.byteLength));
bytes.set(decoded);
return bytes;
}
/**
* Re-create the account's visits, address book and link rows.
*
@@ -440,6 +466,9 @@ export async function restoreVisitsData(
where: { userId: ownerId },
});
// Sealed values this host's keys do not open, by file path.
const unopened: string[] = [];
if (payload.practitioners.length > 0) {
await tx.practitioner.createMany({
data: payload.practitioners.map((entry) => ({
@@ -451,18 +480,24 @@ export async function restoreVisitsData(
// v1.39.4 — ciphertext wins when a disaster-recovery file carried it;
// a portable file's (or an older file's) readable value is sealed
// under this instance's key. The readable columns are never written.
locationEncrypted:
entry.locationEncrypted != null
? decodeCiphertext(entry.locationEncrypted)
: encryptNote(entry.location),
phoneEncrypted:
entry.phoneEncrypted != null
? decodeCiphertext(entry.phoneEncrypted)
: encryptNote(entry.phone),
noteEncrypted:
entry.noteEncrypted == null
? null
: decodeCiphertext(entry.noteEncrypted),
locationEncrypted: sealBytesForRestore(
entry.locationEncrypted,
entry.location,
`practitioners.${entry.id}.locationEncrypted`,
unopened,
),
phoneEncrypted: sealBytesForRestore(
entry.phoneEncrypted,
entry.phone,
`practitioners.${entry.id}.phoneEncrypted`,
unopened,
),
noteEncrypted: sealBytesForRestore(
entry.noteEncrypted,
entry.note,
`practitioners.${entry.id}.noteEncrypted`,
unopened,
),
createdAt: new Date(entry.createdAt),
updatedAt: new Date(entry.updatedAt),
deletedAt: entry.deletedAt ? new Date(entry.deletedAt) : null,
@@ -517,20 +552,26 @@ export async function restoreVisitsData(
status: entry.status,
kind: entry.kind,
practitionerId,
reasonEncrypted:
entry.reasonEncrypted == null
? null
: decodeCiphertext(entry.reasonEncrypted),
outcomeEncrypted:
entry.outcomeEncrypted == null
? null
: decodeCiphertext(entry.outcomeEncrypted),
reasonEncrypted: sealBytesForRestore(
entry.reasonEncrypted,
entry.reason,
`encounters.${entry.id}.reasonEncrypted`,
unopened,
),
outcomeEncrypted: sealBytesForRestore(
entry.outcomeEncrypted,
entry.outcome,
`encounters.${entry.id}.outcomeEncrypted`,
unopened,
),
// Absent in a file written before v1.39.1: the visit comes back
// with no site, which is what it had.
bodySiteEncrypted:
entry.bodySiteEncrypted == null
? null
: decodeCiphertext(entry.bodySiteEncrypted),
bodySiteEncrypted: sealBytesForRestore(
entry.bodySiteEncrypted,
entry.bodySite,
`encounters.${entry.id}.bodySiteEncrypted`,
unopened,
),
laterality: entry.laterality ?? null,
reminderId,
createdAt: new Date(entry.createdAt),
@@ -553,6 +594,7 @@ export async function restoreVisitsData(
[...new Set(droppedReminders)],
droppedReminders,
);
recordUnknownKeys(skips, "visitCiphertext", unopened, unopened);
const restoredEncounters = new Set(payload.encounters.map((e) => e.id));