Carry custom mood labels readable in a portable backup

The labels of the mood tags and mood categories an account created
travelled as the stored ciphertext in a portable file, so a restore onto
a host with another key refused the file or wrote labels nobody could
open. They now follow the cycle note: readable in a portable file, sealed
under the receiving host's key on restore, ciphertext kept only where
this host opens it and otherwise reported as moodLabelCiphertext.

The sealing helpers move to one module both sections share.

src/components/admin/backups-section.tsx

@@ -464,6 +464,9 @@ function catalogueLabel(
   if (catalogue === "symptomEpisodeReference") {
     return t("admin.section.backups.restoreSkippedSymptomEpisodeReference");
   }
+  if (catalogue === "moodLabelCiphertext") {
+    return t("admin.section.backups.restoreSkippedMoodLabelCiphertext");
+  }
   if (catalogue === "cycleCiphertext") {
     return t("admin.section.backups.restoreSkippedCycleCiphertext");
   }

src/lib/cycle/backup.ts

@@ -40,9 +40,12 @@ import type {
   PrismaClient,
   SecondarySymptom,
 } from "@/generated/prisma/client";
-import { decrypt, encrypt } from "@/lib/crypto";
+import {
+  openSealedForExport,
+  sealForRestore,
+  UNOPENED,
+} from "@/lib/export/sealed-text";
 import { UNREADABLE_EXPORT_MARKER } from "@/lib/export/unreadable-marker";
-import { getEvent } from "@/lib/logging/context";
 import type { BackupPayload } from "@/lib/validations/backup";
 import {
   recordUnknownKeys,
@@ -189,26 +192,12 @@ export interface CycleSensitiveFields {
   contraceptive?: string | null;
 }
 
-/** Open a sealed value for a portable file, or the unreadable marker. */
-function openForExport(sealed: string, field: string): string {
-  try {
-    return decrypt(sealed);
-  } catch (err) {
-    getEvent()?.addWarning(
-      `cycle ${field} decrypt failed: ${
-        err instanceof Error ? err.message : String(err)
-      }`,
-    );
-    return UNREADABLE_EXPORT_MARKER;
-  }
-}
-
 /** The sensitive envelope opened for a portable file, or the marker. */
 function openSensitiveForExport(
   sealed: string | null,
 ): CycleSensitiveFields | string | null {
   if (!sealed) return null;
-  const opened = openForExport(sealed, "sensitive envelope");
+  const opened = openSealedForExport(sealed, "cycle sensitive envelope");
   if (opened === UNREADABLE_EXPORT_MARKER) return opened;
   try {
     return JSON.parse(opened) as CycleSensitiveFields;
@@ -330,7 +319,7 @@ export async function buildCycleBackupSection(
         : {
             sensitive: openSensitiveForExport(d.sensitiveEncrypted),
             note: d.notesEncrypted
-              ? openForExport(d.notesEncrypted, "day-log note")
+              ? openSealedForExport(d.notesEncrypted, "cycle day-log note")
               : null,
           }),
       source: d.source,
@@ -353,7 +342,7 @@ export async function buildCycleBackupSection(
         ? { labelEncrypted: sym.labelEncrypted }
         : {
             label: sym.labelEncrypted
-              ? openForExport(sym.labelEncrypted, "symptom label")
+              ? openSealedForExport(sym.labelEncrypted, "cycle symptom label")
               : null,
           }),
     })),
@@ -447,39 +436,6 @@ function severityOrNull(value: number | null | undefined): number | null {
     : null;
 }
 
-/** A readable value the file could not supply: the writer could not open it. */
-const UNOPENED = 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`.
- */
-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;
-}
-
 function enumOrNull<T extends string>(
   value: string | null | undefined,
   allow: ReadonlySet<T>,

src/lib/export/backup-key-ids.ts

@@ -101,8 +101,9 @@ export function isEncryptedMember(name: string): boolean {
  * 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 and custom cycle symptoms are here because a portable
- * file written before v1.40 carried their free text as the stored ciphertext,
+ * The cycle day-logs, custom cycle symptoms and custom mood tags and mood
+ * categories 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
@@ -114,6 +115,8 @@ export function isEncryptedMember(name: string): boolean {
 export const RESTORE_SELF_VERIFIED_SECTIONS: ReadonlySet<string> = new Set([
   "cycleDayLogs",
   "customSymptoms",
+  "customMoodTags",
+  "customMoodTagCategories",
 ]);
 
 interface KeyUse {

src/lib/export/full-backup-payload.ts

@@ -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,

src/lib/export/restore-backup.ts

@@ -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";
@@ -1533,6 +1534,8 @@ export async function restoreBackup(
           // 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 },
@@ -1544,7 +1547,12 @@ export async function restoreBackup(
                 icon: category.icon ?? null,
                 sortOrder: category.sortOrder ?? 0,
                 isActive: category.isActive ?? true,
-                labelEncrypted: category.labelEncrypted ?? null,
+                labelEncrypted: sealForRestore(
+                  category.labelEncrypted,
+                  category.label,
+                  `customMoodTagCategories.${category.key}.labelEncrypted`,
+                  unopenedMoodLabels,
+                ),
               },
               update: {},
             });
@@ -1567,7 +1575,12 @@ export async function restoreBackup(
                 isActive: tag.isActive,
                 icon: tag.icon ?? null,
                 sortOrder: tag.sortOrder,
-                labelEncrypted: tag.labelEncrypted ?? null,
+                labelEncrypted: sealForRestore(
+                  tag.labelEncrypted,
+                  tag.label,
+                  `customMoodTags.${tag.key}.labelEncrypted`,
+                  unopenedMoodLabels,
+                ),
                 scaleMin: tag.scaleMin,
                 scaleMax: tag.scaleMax,
                 inverse: tag.inverse,
@@ -1577,6 +1590,12 @@ export async function restoreBackup(
               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

src/lib/export/restore-skips.ts

@@ -160,6 +160,11 @@
  * 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.
  */
 export type SkippedCatalogue =
   | "cycleSymptom"
@@ -181,7 +186,8 @@ export type SkippedCatalogue =
   | "checkupClosure"
   | "accountSetting"
   | "symptomEpisodeReference"
-  | "cycleCiphertext";
+  | "cycleCiphertext"
+  | "moodLabelCiphertext";
 
 /** One key this instance does not know, and the links it cost. */
 export interface SkippedCatalogueKey {

src/lib/export/sealed-text.ts

@@ -0,0 +1,70 @@
+/**
+ * Both ends of a sealed text column stored with the string codec
+ * (`<keyId>.<base64>`), for the backup sections that carry one: the cycle
+ * day-log note and sensitive envelope, custom cycle symptom labels, and the
+ * custom mood tag and mood category labels.
+ *
+ * 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 { 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;
+}

src/lib/validations/backup.ts

@@ -717,10 +717,12 @@ const customMoodTagSchema = z
     isActive: z.boolean().default(true),
     icon: z.string().nullable().optional(),
     sortOrder: z.number().int().default(0),
-    // The user's own words for the tag, encrypted at rest and carried
-    // verbatim. Without it the tag comes back as a bare key and the person
-    // who named it "Migräne" gets `custom:cm3x9…` instead.
+    // The user's own words for the tag. Without it the tag comes back as a
+    // bare key and the person who named it "Migräne" gets `custom:cm3x9…`
+    // instead. Ciphertext on a disaster-recovery file, readable `label` on a
+    // portable one; the restore seals the readable value under its own key.
     labelEncrypted: z.string().nullable().optional(),
+    label: z.string().nullable().optional(),
     // The scale a RATED factor was recorded on. `inverse` marks a factor
     // where a HIGH value is bad (stress, conflict). Dropping it does not lose
     // a label, it silently reverses the meaning of every rating already
@@ -1642,7 +1644,9 @@ const customMoodTagCategorySchema = z
     icon: z.string().nullable().optional(),
     sortOrder: z.number().int().optional(),
     isActive: z.boolean().optional(),
+    // Same split as the custom tag's label.
     labelEncrypted: z.string().nullable().optional(),
+    label: z.string().nullable().optional(),
   })
   .passthrough();