Files
HealthLog/src/lib/recovery/__tests__/kit-rules.test.ts
T
Marc-André Bombeck d3c672cc3f feat(admin): replace the key backup step with a recovery kit
The step confirmed one key, the active application key. A restore needs
more: off-host copies are sealed under BACKUP_ENCRYPTION_KEY, a copy
written before a rotation needs the retired application key it was
written under, and every session, token and share link hangs off
API_TOKEN_HMAC_KEY. An operator could do everything the step asked and
still be unable to read a single backup.

The recovery kit lists every key a restore of this server needs, by id
and fingerprint, never key material:

- each id in ENCRYPTION_KEYS, plus any retired id a stored copy
  (innerKeyIds) or an off-host object inside the bucket's retention
  (OffhostBackupKeyUse) still lists, also once the server dropped it;
- BACKUP_ENCRYPTION_KEY and each BACKUP_ENCRYPTION_PREVIOUS_KEYS entry,
  named by the id their objects record;
- API_TOKEN_HMAC_KEY.

Confirming records the set the admin was shown and refuses a stale one
with 409 recovery.kit.stale. The kit is due again as soon as a key it
lists is not in that set (a rotation, a new backup key, a re-keyed
install); a key that merely drops out does not make it due. "Check my
copy" now checks any key in the kit.

Migration 0487 carries a confirmation given under the old step forward
as a kit holding that key, so that part stays confirmed, and drops the
four app_settings columns. It also creates the two tables the readiness
evaluation uses (restore_drill_outcomes, recovery_readiness_notices).

The routes move to /api/admin/recovery-kit; the reader of the keys the
backups still need moves out of the encryption status route into
src/lib/recovery/backup-key-needs.ts so the kit and the status view
share one definition.
2026-10-25 13:32:29 +01:00

232 lines
7.5 KiB
TypeScript

/**
* The recovery kit rules: which keys the kit lists, what a confirmation
* covers, and when the kit is due again.
*
* Mutation check: compare fingerprints out of the covered test (id only) and
* the re-keyed-install case goes red; drop the backup needs from the
* application list and the retired-key case goes red.
*/
import { createHash } from "node:crypto";
import { describe, expect, it } from "vitest";
import { offhostKeyId } from "@/lib/jobs/offhost-key";
import type { BackupKeyNeeds } from "@/lib/recovery/backup-key-needs";
import {
applicationKitKeys,
assessRecoveryKit,
backupKitKeys,
fingerprintText,
neededKeyIds,
parseKitEntries,
resolvePlatformHint,
sameKit,
tokenKitKeys,
type KitEntry,
} from "@/lib/recovery/kit-rules";
const NOW = new Date("2026-10-25T12:00:00Z");
const DAY = 86_400_000;
const NO_NEEDS: BackupKeyNeeds = {
stored: [],
unrecorded: { copies: 0, oldestAt: null },
offhost: [],
offhostExpirationDays: null,
retiredKeysStillNeeded: [],
};
const FINGERPRINTS: Record<string, string> = {
v1: "111111111111",
v2: "222222222222",
};
function appKeys(configured: string[], active: string, needs = NO_NEEDS) {
return applicationKitKeys({
activeKeyId: active,
configuredKeyIds: configured,
fingerprintOf: (id) => (configured.includes(id) ? FINGERPRINTS[id] : null),
needs,
now: NOW,
});
}
const BACKUP_HEX = "ab".repeat(32);
const BACKUP_OLD_HEX = "cd".repeat(32);
describe("which keys the kit lists", () => {
it("lists every configured application key, the active one marked", () => {
const keys = appKeys(["v1", "v2"], "v2");
expect(keys.map((k) => [k.id, k.need.active, k.fingerprint])).toEqual([
["v1", false, "111111111111"],
["v2", true, "222222222222"],
]);
});
it("keeps a retired key a stored copy lists, even once the server dropped it", () => {
const needs: BackupKeyNeeds = {
...NO_NEEDS,
stored: [{ keyId: "v1", copies: 3, oldestAt: NOW.toISOString() }],
};
const [v1] = appKeys(["v2"], "v2", needs);
expect(v1).toMatchObject({
id: "v1",
fingerprint: null,
problem: "not_configured",
need: { configured: false, storedCopies: 3 },
});
});
it("keeps an off-host key while objects inside the retention need it", () => {
const row = (neededUntil: string | null) => ({
...NO_NEEDS,
offhost: [
{
keyId: "v1",
firstWrittenAt: NOW.toISOString(),
lastWrittenAt: NOW.toISOString(),
neededUntil,
},
],
});
const until = new Date(NOW.getTime() + 10 * DAY).toISOString();
expect(appKeys(["v2"], "v2", row(until))[0].need.offhostUntil).toBe(until);
expect(appKeys(["v2"], "v2", row(null))[0].need.offhostUntil).toBe(
"unknown",
);
// Past the retention the objects are gone, so the key drops out.
const past = new Date(NOW.getTime() - DAY).toISOString();
expect(appKeys(["v2"], "v2", row(past)).map((k) => k.id)).toEqual(["v2"]);
expect([...neededKeyIds(row(past), NOW)]).toEqual([]);
});
it("names the off-host keys by the id their objects record", () => {
const keys = backupKitKeys(BACKUP_HEX, ` ${BACKUP_OLD_HEX} ,`);
expect(keys.map((k) => [k.id, k.need.active, k.source])).toEqual([
[
offhostKeyId(Buffer.from(BACKUP_HEX, "hex")),
true,
"BACKUP_ENCRYPTION_KEY",
],
[
offhostKeyId(Buffer.from(BACKUP_OLD_HEX, "hex")),
false,
"BACKUP_ENCRYPTION_PREVIOUS_KEYS",
],
]);
expect(keys.every((k) => k.fingerprint === k.id)).toBe(true);
expect(backupKitKeys(undefined, undefined)).toEqual([]);
});
it("flags an off-host key that does not decode instead of hiding it", () => {
const [bad] = backupKitKeys("not-a-key", undefined);
expect(bad).toMatchObject({ fingerprint: null, problem: "unreadable" });
});
it("fingerprints the token key as the text the operator set", () => {
const value = "x".repeat(40);
const [token] = tokenKitKeys(value);
expect(token.fingerprint).toBe(
createHash("sha256").update(value).digest("hex").slice(0, 12),
);
expect(token.fingerprint).toBe(fingerprintText(value));
expect(JSON.stringify(token)).not.toContain(value);
});
});
describe("what a confirmation covers", () => {
const listed = [...appKeys(["v1"], "v1"), ...tokenKitKeys("t".repeat(40))];
const entries = (keys: typeof listed): KitEntry[] =>
keys.map(({ kind, id, fingerprint }) => ({ kind, id, fingerprint }));
it("is due without any confirmation, and done for the exact set", () => {
expect(assessRecoveryKit(listed, null).due).toBe(true);
expect(assessRecoveryKit(listed, entries(listed)).due).toBe(false);
});
it("keeps a confirmation of the active key only, from the old step, for that key", () => {
const legacy: KitEntry[] = [
{ kind: "application", id: "v1", fingerprint: "111111111111" },
];
const verdict = assessRecoveryKit(listed, legacy);
expect(verdict.due).toBe(true);
expect(verdict.keys.find((k) => k.id === "v1")?.confirmed).toBe(true);
expect(verdict.unconfirmed.map((k) => k.id)).toEqual([
"API_TOKEN_HMAC_KEY",
]);
});
it("is due again after a rotation, a re-keyed install or a new backup key", () => {
const confirmed = entries(listed);
// Rotation: a new active id.
const rotated = [
...appKeys(["v1", "v2"], "v2"),
...tokenKitKeys("t".repeat(40)),
];
expect(
assessRecoveryKit(rotated, confirmed).unconfirmed.map((k) => k.id),
).toEqual(["v2"]);
// Same id, other key.
const rekeyed = listed.map((k) =>
k.id === "v1" ? { ...k, fingerprint: "999999999999" } : k,
);
expect(assessRecoveryKit(rekeyed, confirmed).due).toBe(true);
// A backup key appears.
const withBackup = [...listed, ...backupKitKeys(BACKUP_HEX, undefined)];
expect(assessRecoveryKit(withBackup, confirmed).unconfirmed).toHaveLength(
1,
);
});
it("is not due when a key merely drops out of the kit", () => {
const wider = [
...appKeys(["v1", "v2"], "v2"),
...tokenKitKeys("t".repeat(40)),
];
const narrower = [
...appKeys(["v2"], "v2"),
...tokenKitKeys("t".repeat(40)),
];
expect(assessRecoveryKit(narrower, entries(wider)).due).toBe(false);
});
it("covers a key this server does not hold by its id", () => {
const needs: BackupKeyNeeds = {
...NO_NEEDS,
stored: [{ keyId: "v0", copies: 1, oldestAt: NOW.toISOString() }],
};
const kit = appKeys(["v1"], "v1", needs);
const confirmed = entries(kit);
expect(confirmed.find((e) => e.id === "v0")?.fingerprint).toBeNull();
expect(assessRecoveryKit(kit, confirmed).due).toBe(false);
});
it("matches the shown kit against the current one as a set", () => {
const a = entries(listed);
expect(sameKit([...a].reverse(), a)).toBe(true);
expect(sameKit(a.slice(1), a)).toBe(false);
expect(
sameKit(
a.map((e) =>
e.id === "v1" ? { ...e, fingerprint: "000000000000" } : e,
),
a,
),
).toBe(false);
});
it("reads a stored confirmation it cannot parse as none", () => {
expect(parseKitEntries({ not: "a list" })).toEqual([]);
expect(
parseKitEntries([{ kind: "nope", id: "v1", fingerprint: null }]),
).toEqual([]);
});
});
describe("platform hint", () => {
it("opens on a known platform and falls back to compose", () => {
expect(resolvePlatformHint("TrueNAS")).toBe("truenas");
expect(resolvePlatformHint("kubernetes")).toBe("compose");
expect(resolvePlatformHint(undefined)).toBe("compose");
});
});