Merge branch 'feat/vault-w4-qa' into release/v1.27.17

This commit is contained in:
Marc-André Bombeck committed 2026-07-07 15:10:45 +02:00
commit 03058b0210
81 files changed
+10544 -3246

No files matched your search

Binary file not shown.
+99
View File
@@ -264,6 +264,105 @@ export function reencryptToActive(encoded: string): string {
return encrypt(decrypt(encoded));
}
// ─── Binary codec ("binary2") ────────────────────────────────────────────────
//
// AES-256-GCM over raw bytes, skipping the base64 detour the string codec
// takes (−33 % at rest, one fewer full copy in memory). Written for large
// binary payloads (the document vault's `contentEncrypted`); the consumer
// records which codec a row uses in an explicit column — the layout is never
// header-sniffed against the string codec.
//
// Layout: [version 0x02][keyIdLen u8][keyId ascii][iv 12][tag 16][ciphertext]
//
// Same versioned-key discipline as the string codec: encrypt always writes
// the active key id, decrypt is fail-closed on an unknown version, a
// malformed header, or an unconfigured key id.
/** Version byte identifying the binary2 layout. */
const BYTES_CODEC_VERSION = 0x02;
/** Encrypt raw bytes with the active key into the binary2 layout. */
export function encryptBytes(plaintext: Buffer): Buffer {
const { id, key } = getActiveKey();
const keyId = Buffer.from(id, "ascii");
if (keyId.byteLength < 1 || keyId.byteLength > 32) {
// loadKeys() already constrains ids to [A-Za-z0-9_-]{1,32}; belt-and-braces.
throw new Error(`Encryption key id '${id}' is not header-encodable`);
}
const iv = randomBytes(IV_LENGTH);
const cipher = createCipheriv(ALGORITHM, key, iv);
const ct = Buffer.concat([cipher.update(plaintext), cipher.final()]);
const tag = cipher.getAuthTag();
const header = Buffer.from([BYTES_CODEC_VERSION, keyId.byteLength]);
return Buffer.concat([header, keyId, iv, tag, ct]);
}
/** Parse a binary2 header. Throws on any malformation (fail-closed). */
function parseBytesHeader(payload: Buffer): {
keyId: string;
iv: Buffer;
tag: Buffer;
ct: Buffer;
} {
if (payload.byteLength < 2) {
throw new Error("binary2 payload is truncated (no header)");
}
if (payload[0] !== BYTES_CODEC_VERSION) {
throw new Error(
`Unknown binary ciphertext version ${payload[0]} (expected ${BYTES_CODEC_VERSION})`,
);
}
const keyIdLen = payload[1];
if (keyIdLen < 1 || keyIdLen > 32) {
throw new Error("binary2 payload has an invalid key-id length");
}
const fixed = 2 + keyIdLen + IV_LENGTH + AUTH_TAG_LENGTH;
if (payload.byteLength < fixed) {
throw new Error("binary2 payload is truncated");
}
const keyId = payload.subarray(2, 2 + keyIdLen).toString("ascii");
if (!/^[A-Za-z0-9_-]{1,32}$/.test(keyId)) {
throw new Error("binary2 payload carries a malformed key id");
}
const iv = payload.subarray(2 + keyIdLen, 2 + keyIdLen + IV_LENGTH);
const tag = payload.subarray(2 + keyIdLen + IV_LENGTH, fixed);
const ct = payload.subarray(fixed);
return { keyId, iv, tag, ct };
}
/**
* Decrypt a binary2 payload back to its raw bytes. Fail-closed: an unknown
* version, a malformed header, or an unconfigured key id throws — the caller
* must treat a throw as "cannot serve", never fall back to the ciphertext.
*/
export function decryptBytes(payload: Buffer): Buffer {
const { keyId, iv, tag, ct } = parseBytesHeader(payload);
const key = getKeyById(keyId);
if (!key) {
throw new Error(
`Encryption key id '${keyId}' is not configured. Add it to ` +
`ENCRYPTION_KEYS before decrypting rows written under that key.`,
);
}
const dec = createDecipheriv(ALGORITHM, key, iv);
dec.setAuthTag(tag);
return Buffer.concat([dec.update(ct), dec.final()]);
}
/** The key id a binary2 payload was written under, or null when unparsable. */
export function extractKeyIdFromBytes(payload: Buffer): string | null {
try {
return parseBytesHeader(payload).keyId;
} catch {
return null;
}
}
/** Re-encrypt a binary2 payload with the active key. Used by rotation. */
export function reencryptBytesToActive(payload: Buffer): Buffer {
return encryptBytes(decryptBytes(payload));
}
/** Returns the key id portion of a versioned ciphertext, or null for legacy. */
export function extractKeyId(encoded: string): string | null {
const dot = encoded.indexOf(".");
@@ -0,0 +1,276 @@
import { describe, it, expect, beforeEach } from "vitest";
import { Buffer } from "node:buffer";
import {
encrypt,
encryptBytes,
extractKeyIdFromBytes,
getActiveKeyId,
_resetCryptoCacheForTests,
} from "@/lib/crypto";
import {
rotateColumn,
scanColumn,
BLOB_ROTATION_BATCH_SIZE,
type CorpusClient,
} from "@/lib/crypto/encryption-corpus";
import type { EncryptedColumn } from "@/lib/crypto/encrypted-columns";
/**
* Codec-dispatched blob rotation (the document vault's `contentEncrypted`):
* the walk is id-cursor paginated with a bounded batch size — never an
* unbounded blob `findMany` — re-encrypts each row under its OWN codec,
* fails closed per row on an unknown codec, and resumes cleanly after an
* interrupted run because already-active rows are skipped.
*/
const KEY_V1 =
"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
const KEY_V2 =
"fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210";
const DOC_COLUMN: EncryptedColumn = {
model: "InboundDocument",
field: "contentEncrypted",
kind: "bytes",
codecField: "contentCodec",
};
interface DocRow {
id: string;
contentEncrypted: Uint8Array;
contentCodec: string;
}
interface FindManyArgs {
select: Record<string, true>;
orderBy?: Record<string, "asc" | "desc">;
take?: number;
cursor?: Record<string, unknown>;
skip?: number;
}
/**
* Pagination-honouring fake delegate: applies orderBy(id) + cursor + skip +
* take exactly like Prisma keyset pagination, and records every findMany
* call so the test can assert the batch boundedness.
*/
function makeDocClient(rows: DocRow[]): {
client: CorpusClient;
store: DocRow[];
findManyCalls: FindManyArgs[];
failUpdatesFor: Set<string>;
} {
const store = [...rows];
const findManyCalls: FindManyArgs[] = [];
const failUpdatesFor = new Set<string>();
const client = {
inboundDocument: {
findMany: async (args: FindManyArgs) => {
findManyCalls.push(args);
let list = [...store].sort((a, b) => a.id.localeCompare(b.id));
if (args.cursor) {
const idx = list.findIndex((r) => r.id === args.cursor!.id);
list = list.slice(idx + (args.skip ?? 0));
}
if (args.take !== undefined) list = list.slice(0, args.take);
return list.map((row) => {
const out: Record<string, unknown> = {};
for (const f of Object.keys(args.select)) {
out[f] = row[f as keyof DocRow];
}
return out;
});
},
update: async ({
where,
data,
}: {
where: { id: string };
data: Record<string, unknown>;
}) => {
if (failUpdatesFor.has(where.id)) {
throw new Error("simulated interruption");
}
const row = store.find((r) => r.id === where.id);
if (row) Object.assign(row, data);
return row;
},
},
} as unknown as CorpusClient;
return { client, store, findManyCalls, failUpdatesFor };
}
function binaryUnder(keyId: "v1" | "v2", plaintext: Buffer): Uint8Array {
process.env.ENCRYPTION_ACTIVE_KEY_ID = keyId;
_resetCryptoCacheForTests();
const out = encryptBytes(plaintext);
process.env.ENCRYPTION_ACTIVE_KEY_ID = "v2";
_resetCryptoCacheForTests();
return new Uint8Array(out);
}
function legacyUnder(keyId: "v1" | "v2", plaintext: string): Uint8Array {
process.env.ENCRYPTION_ACTIVE_KEY_ID = keyId;
_resetCryptoCacheForTests();
const ct = encrypt(Buffer.from(plaintext).toString("base64"));
process.env.ENCRYPTION_ACTIVE_KEY_ID = "v2";
_resetCryptoCacheForTests();
return new Uint8Array(Buffer.from(ct, "utf8"));
}
function pad(i: number): string {
return `doc-${String(i).padStart(5, "0")}`;
}
beforeEach(() => {
process.env.ENCRYPTION_KEYS = JSON.stringify({ v1: KEY_V1, v2: KEY_V2 });
process.env.ENCRYPTION_ACTIVE_KEY_ID = "v2";
delete process.env.ENCRYPTION_KEY;
_resetCryptoCacheForTests();
});
describe("codec-dispatched blob rotation (bounded batches)", () => {
it("walks a 500-row corpus in bounded id-cursor batches and rotates both codecs", async () => {
const rows: DocRow[] = [];
// 200 binary2 under the stale v1, 150 legacy base64v1 under v1,
// 100 binary2 already on v2 (skipped), 50 legacy already on v2 (skipped).
for (let i = 0; i < 200; i++) {
rows.push({
id: pad(i),
contentEncrypted: binaryUnder("v1", Buffer.from(`bin-${i}`)),
contentCodec: "binary2",
});
}
for (let i = 200; i < 350; i++) {
rows.push({
id: pad(i),
contentEncrypted: legacyUnder("v1", `legacy-${i}`),
contentCodec: "base64v1",
});
}
for (let i = 350; i < 450; i++) {
rows.push({
id: pad(i),
contentEncrypted: binaryUnder("v2", Buffer.from(`bin-${i}`)),
contentCodec: "binary2",
});
}
for (let i = 450; i < 500; i++) {
rows.push({
id: pad(i),
contentEncrypted: legacyUnder("v2", `legacy-${i}`),
contentCodec: "base64v1",
});
}
const { client, store, findManyCalls } = makeDocClient(rows);
const result = await rotateColumn(client, DOC_COLUMN);
expect(result.scanned).toBe(500);
expect(result.rotated).toBe(350);
expect(result.errors).toBe(0);
// BOUNDED: every page requested at most the batch size, and the walk
// needed ceil(500 / batch) full pages (+1 terminating empty page, since
// 500 is an exact multiple) — never one unbounded findMany.
expect(findManyCalls.length).toBe(
Math.ceil(500 / BLOB_ROTATION_BATCH_SIZE) + 1,
);
for (const call of findManyCalls) {
expect(call.take).toBe(BLOB_ROTATION_BATCH_SIZE);
expect(call.orderBy).toEqual({ id: "asc" });
}
// Cursor advanced between pages.
expect(findManyCalls[0].cursor).toBeUndefined();
expect(findManyCalls[1].cursor).toEqual({ id: pad(24) });
// Every row now reads under the active key, each in its OWN codec.
for (const row of store) {
if (row.contentCodec === "binary2") {
expect(extractKeyIdFromBytes(Buffer.from(row.contentEncrypted))).toBe(
getActiveKeyId(),
);
} else {
expect(
Buffer.from(row.contentEncrypted).toString("utf8").startsWith("v2."),
).toBe(true);
}
}
// IDEMPOTENT: the second pass rotates nothing.
const second = await rotateColumn(client, DOC_COLUMN);
expect(second.rotated).toBe(0);
expect(second.errors).toBe(0);
});
it("resumes after an interrupted run (already-rotated rows are skipped)", async () => {
const rows: DocRow[] = [];
for (let i = 0; i < 60; i++) {
rows.push({
id: pad(i),
contentEncrypted: binaryUnder("v1", Buffer.from(`bin-${i}`)),
contentCodec: "binary2",
});
}
const { client, failUpdatesFor } = makeDocClient(rows);
// First run: the last 20 updates fail (simulated interruption) — they
// are counted, never dropped.
for (let i = 40; i < 60; i++) failUpdatesFor.add(pad(i));
const first = await rotateColumn(client, DOC_COLUMN);
expect(first.rotated).toBe(40);
expect(first.errors).toBe(20);
// Second run with the interruption cleared: exactly the remainder
// rotates — the 40 already-active rows are skipped.
failUpdatesFor.clear();
const second = await rotateColumn(client, DOC_COLUMN);
expect(second.rotated).toBe(20);
expect(second.errors).toBe(0);
});
it("fails closed per row on an unknown codec and leaves the row untouched", async () => {
const strange = new Uint8Array(Buffer.from("???strange???"));
const { client, store } = makeDocClient([
{
id: pad(0),
contentEncrypted: binaryUnder("v1", Buffer.from("fine")),
contentCodec: "binary2",
},
{ id: pad(1), contentEncrypted: strange, contentCodec: "codec9" },
]);
const result = await rotateColumn(client, DOC_COLUMN);
expect(result.rotated).toBe(1);
expect(result.errors).toBe(1);
expect(store.find((r) => r.id === pad(1))!.contentEncrypted).toBe(strange);
});
it("scanColumn buckets blob rows per codec-aware key id in bounded batches", async () => {
const { client, findManyCalls } = makeDocClient([
{
id: pad(0),
contentEncrypted: binaryUnder("v1", Buffer.from("a")),
contentCodec: "binary2",
},
{
id: pad(1),
contentEncrypted: legacyUnder("v1", "b"),
contentCodec: "base64v1",
},
{
id: pad(2),
contentEncrypted: binaryUnder("v2", Buffer.from("c")),
contentCodec: "binary2",
},
]);
const scan = await scanColumn(client, DOC_COLUMN);
expect(scan.total).toBe(3);
expect(scan.byKeyId.v1).toBe(2);
expect(scan.byKeyId.v2).toBe(1);
expect(scan.legacy).toBe(0);
for (const call of findManyCalls) {
expect(call.take).toBe(BLOB_ROTATION_BATCH_SIZE);
}
});
});
+22 -5
View File
@@ -34,6 +34,15 @@ export interface EncryptedColumn {
/** Prisma field name (camelCase, as declared in schema.prisma). */
readonly field: string;
readonly kind: EncryptedColumnKind;
/**
* Present when the column's ciphertext layout is dispatched by a sibling
* codec column (the document vault's `contentCodec`: "base64v1" = the
* `encrypt()`-string-as-UTF-8 shape every other Bytes column uses,
* "binary2" = the binary `encryptBytes()` layout). A codec-dispatched
* column also rotates in bounded id-cursor batches — its rows are
* multi-megabyte blobs, so an unbounded `findMany` would balloon memory.
*/
readonly codecField?: string;
}
/**
@@ -179,11 +188,19 @@ export const ENCRYPTED_COLUMNS: readonly EncryptedColumn[] = [
{ model: "Allergy", field: "notesEncrypted", kind: "bytes" },
{ model: "FamilyHistoryEntry", field: "notesEncrypted", kind: "bytes" },
// ───── v1.25 (W-DOCS-IN) inbound clinical document (Bytes column) ─────
// The raw uploaded doctor report / discharge letter, base64-of-binary →
// AES-256-GCM string → UTF-8 bytes. The most sensitive blob in the wave
// (a full clinical document); never logged, never in wide-event meta.
{ model: "InboundDocument", field: "contentEncrypted", kind: "bytes" },
// ───── Inbound clinical document (Bytes column, codec-dispatched) ─────
// The raw uploaded document (the most sensitive blob in the corpus; never
// logged, never in wide-event meta). Two layouts, recorded per row in
// `contentCodec`: "base64v1" (pre-vault rows — base64-of-binary →
// AES-256-GCM string → UTF-8 bytes) and "binary2" (vault uploads — the
// binary `encryptBytes()` layout). Rotation walks this column in bounded
// id-cursor batches and re-encrypts under the row's own codec.
{
model: "InboundDocument",
field: "contentEncrypted",
kind: "bytes",
codecField: "contentCodec",
},
// The staged extracted-fact payloads: the FHIR-staged clinical values
// (diagnosis text / lab values / medication names / stated codes) and the
// verbatim source-span provenance. Both are PHI transcribed from the source
+139 -14
View File
@@ -30,7 +30,14 @@
* protects against dropping a legacy key too early.
*/
import { Buffer } from "node:buffer";
import { decrypt, encrypt, extractKeyId, getActiveKeyId } from "@/lib/crypto";
import {
decrypt,
encrypt,
extractKeyId,
extractKeyIdFromBytes,
getActiveKeyId,
reencryptBytesToActive,
} from "@/lib/crypto";
import {
ENCRYPTED_COLUMNS,
encryptedColumnKey,
@@ -40,10 +47,21 @@ import {
/** Sentinel bucket for legacy (unversioned) ciphertext under `byKeyId`. */
export const LEGACY_BUCKET = "legacy";
/**
* Batch size for codec-dispatched blob columns (`codecField` present). The
* document vault's rows are up to cap-sized ciphertexts, so the walk is
* id-cursor paginated — at most this many blobs are in memory at once.
*/
export const BLOB_ROTATION_BATCH_SIZE = 25;
/** Minimal Prisma delegate shape this module needs. */
interface ColumnDelegate {
findMany: (args: {
select: Record<string, true>;
orderBy?: Record<string, "asc" | "desc">;
take?: number;
cursor?: Record<string, unknown>;
skip?: number;
}) => Promise<Array<Record<string, unknown>>>;
update: (args: {
where: { id: string };
@@ -98,6 +116,78 @@ function shouldRotate(ciphertext: string): boolean {
return extractKeyId(ciphertext) !== getActiveKeyId();
}
// ─── Codec-dispatched blob columns (document vault) ─────────────────────────
/**
* The key id a codec-dispatched blob row was written under, or null when
* legacy/unparsable. "binary2" parses the binary header; every other codec
* value (notably "base64v1") is the `encrypt()`-string-as-UTF-8 shape.
*/
function blobKeyId(value: Uint8Array, codec: string): string | null {
const buf = Buffer.from(value);
if (codec === "binary2") return extractKeyIdFromBytes(buf);
return extractKeyId(buf.toString("utf8"));
}
/** Re-encrypt one codec-dispatched blob under its OWN codec (never converts). */
function reencryptBlob(value: Uint8Array, codec: string): Uint8Array {
const buf = Buffer.from(value);
if (codec === "binary2") {
const rotated = reencryptBytesToActive(buf);
const next = new Uint8Array(new ArrayBuffer(rotated.byteLength));
next.set(rotated);
return next;
}
if (codec === "base64v1") {
const rotated = encrypt(decrypt(buf.toString("utf8")));
const encoded = Buffer.from(rotated, "utf8");
const next = new Uint8Array(new ArrayBuffer(encoded.byteLength));
next.set(encoded);
return next;
}
// FAIL-CLOSED: an unknown codec is counted as an error and left untouched.
throw new Error(`Unknown content codec '${codec}'`);
}
/**
* Walk a codec-dispatched blob column in bounded id-cursor batches, invoking
* `onRow` per non-empty row. At most `BLOB_ROTATION_BATCH_SIZE` blobs are in
* memory per step; an interrupted run resumes safely on re-invocation because
* processing is idempotent (already-active rows are skipped by the callers).
*/
async function walkBlobColumn(
delegate: ColumnDelegate,
col: EncryptedColumn,
onRow: (row: {
id: string;
value: Uint8Array;
codec: string;
}) => Promise<void> | void,
): Promise<void> {
const codecField = col.codecField!;
let cursor: string | null = null;
for (;;) {
const rows = await delegate.findMany({
select: { id: true, [col.field]: true, [codecField]: true },
orderBy: { id: "asc" },
take: BLOB_ROTATION_BATCH_SIZE,
...(cursor ? { cursor: { id: cursor }, skip: 1 } : {}),
});
if (rows.length === 0) break;
for (const row of rows) {
const value = row[col.field] as Uint8Array | null;
if (!value || value.byteLength === 0) continue;
await onRow({
id: row.id as string,
value,
codec: String(row[codecField] ?? ""),
});
}
cursor = rows[rows.length - 1]!.id as string;
if (rows.length < BLOB_ROTATION_BATCH_SIZE) break;
}
}
export interface ColumnScan {
model: string;
field: string;
@@ -116,17 +206,27 @@ export async function scanColumn(
col: EncryptedColumn,
): Promise<ColumnScan> {
const delegate = getDelegate(client, col.model);
const rows = await delegate.findMany({
select: { id: true, [col.field]: true },
});
const byKeyId: Record<string, number> = {};
let total = 0;
for (const row of rows) {
const ciphertext = toCiphertext(row[col.field], col.kind);
if (ciphertext == null) continue;
total += 1;
const id = extractKeyId(ciphertext) ?? LEGACY_BUCKET;
byKeyId[id] = (byKeyId[id] ?? 0) + 1;
if (col.codecField) {
// Codec-dispatched blob column: bounded batches, per-row codec.
await walkBlobColumn(delegate, col, ({ value, codec }) => {
total += 1;
const id = blobKeyId(value, codec) ?? LEGACY_BUCKET;
byKeyId[id] = (byKeyId[id] ?? 0) + 1;
});
} else {
const rows = await delegate.findMany({
select: { id: true, [col.field]: true },
});
for (const row of rows) {
const ciphertext = toCiphertext(row[col.field], col.kind);
if (ciphertext == null) continue;
total += 1;
const id = extractKeyId(ciphertext) ?? LEGACY_BUCKET;
byKeyId[id] = (byKeyId[id] ?? 0) + 1;
}
}
return {
model: col.model,
@@ -192,16 +292,41 @@ export async function rotateColumn(
col: EncryptedColumn,
): Promise<RotationResult> {
const delegate = getDelegate(client, col.model);
const rows = await delegate.findMany({
select: { id: true, [col.field]: true },
});
const result: RotationResult = {
model: col.model,
field: col.field,
scanned: rows.length,
scanned: 0,
rotated: 0,
errors: 0,
};
if (col.codecField) {
// Codec-dispatched blob column: bounded id-cursor batches (never an
// unbounded blob findMany), re-encrypted under each row's OWN codec.
// Idempotent — rows already on the active key are skipped, so an
// interrupted run resumes cleanly on the next invocation.
await walkBlobColumn(delegate, col, async ({ id, value, codec }) => {
result.scanned += 1;
if (blobKeyId(value, codec) === getActiveKeyId()) return;
try {
await delegate.update({
where: { id },
data: { [col.field]: reencryptBlob(value, codec) },
});
result.rotated += 1;
} catch {
// FAIL-CLOSED: unknown codec or a no-longer-configured key throws;
// count it and leave the row untouched rather than dropping data.
result.errors += 1;
}
});
return result;
}
const rows = await delegate.findMany({
select: { id: true, [col.field]: true },
});
result.scanned = rows.length;
for (const row of rows) {
const ciphertext = toCiphertext(row[col.field], col.kind);
if (ciphertext == null || !shouldRotate(ciphertext)) continue;
@@ -0,0 +1,84 @@
import { describe, it, expect, beforeEach, vi } from "vitest";
import { Buffer } from "node:buffer";
/**
* Document content codec dispatch: new uploads write "binary2", pre-vault
* rows keep decoding via the legacy "base64v1" string path, and an unknown
* codec value fails closed instead of guessing.
*/
vi.mock("@/lib/db", () => ({
prisma: {
appSettings: { findUnique: vi.fn() },
user: { findUnique: vi.fn() },
},
}));
import { _resetCryptoCacheForTests } from "@/lib/crypto";
import {
ACTIVE_DOCUMENT_CODEC,
decryptDocumentContent,
decryptDocumentFromBytes,
encryptDocumentContent,
encryptDocumentToBytes,
} from "../store";
const KEY_V1 =
"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
const SAMPLE = Buffer.concat([
Buffer.from("%PDF-1.7\n"),
Buffer.from([0x00, 0xff, 0x80, 0x7f]),
Buffer.alloc(2048, 0xab),
]);
beforeEach(() => {
vi.unstubAllEnvs();
vi.stubEnv("ENCRYPTION_KEYS", "");
vi.stubEnv("ENCRYPTION_ACTIVE_KEY_ID", "");
vi.stubEnv("ENCRYPTION_KEY", KEY_V1);
_resetCryptoCacheForTests();
});
describe("document content codecs", () => {
it("writes new uploads with the binary2 codec and round-trips them", () => {
const { content, codec } = encryptDocumentContent(SAMPLE);
expect(codec).toBe("binary2");
expect(codec).toBe(ACTIVE_DOCUMENT_CODEC);
expect(Buffer.from(content).equals(SAMPLE)).toBe(false);
expect(decryptDocumentContent(content, codec).equals(SAMPLE)).toBe(true);
});
it("still decodes legacy base64v1 rows byte-identically", () => {
// A pre-vault row: base64-of-binary → encrypt() string → UTF-8 bytes.
const legacy = encryptDocumentToBytes(SAMPLE);
expect(decryptDocumentContent(legacy, "base64v1").equals(SAMPLE)).toBe(
true,
);
// The legacy helper itself stays the exact inverse.
expect(decryptDocumentFromBytes(legacy).equals(SAMPLE)).toBe(true);
});
it("binary2 is ~25 % smaller at rest than the base64 detour", () => {
const legacy = encryptDocumentToBytes(SAMPLE);
const { content } = encryptDocumentContent(SAMPLE);
expect(content.byteLength).toBeLessThan(legacy.byteLength * 0.8);
});
it("fails closed on an unknown codec value", () => {
const { content } = encryptDocumentContent(SAMPLE);
expect(() => decryptDocumentContent(content, "codec9")).toThrow(
/unknown document content codec/i,
);
expect(() => decryptDocumentContent(content, "")).toThrow();
});
it("fails closed when codecs are crossed (no silent fallback)", () => {
const legacy = encryptDocumentToBytes(SAMPLE);
const { content: binary } = encryptDocumentContent(SAMPLE);
// Legacy bytes read as binary2 → header parse fails.
expect(() => decryptDocumentContent(legacy, "binary2")).toThrow();
// Binary bytes read as base64v1 → string decrypt fails.
expect(() => decryptDocumentContent(binary, "base64v1")).toThrow();
});
});
@@ -0,0 +1,326 @@
import { beforeEach, describe, expect, it, vi } from "vitest";
/**
* Document-vault policy layer: exhaustive accept-matrix coverage.
*
* Every Class A and Class B format is detected from real magic-byte
* fixtures, every deny case is denied, the wire Content-Type never plays a
* role (the detector does not even receive it), container ambiguity (ZIP →
* OOXML only under an Office extension) is pinned, adversarial polyglots
* behave as designed, and the limits resolver clamps to the hard ceiling.
*/
vi.mock("@/lib/db", () => ({
prisma: {
appSettings: { findUnique: vi.fn() },
user: { findUnique: vi.fn() },
},
}));
import { prisma } from "@/lib/db";
import {
DOCUMENT_DEFAULT_MAX_FILE_BYTES,
DOCUMENT_DEFAULT_QUOTA_BYTES,
DOCUMENT_HARD_MAX_FILE_BYTES,
detectDocumentType,
resolveDocumentLimits,
servingClassFor,
} from "../upload-policy";
// ─── Magic-byte fixtures ─────────────────────────────────────────────────────
const PDF = Buffer.from("%PDF-1.7\n%âãÏÓ\n1 0 obj\n", "latin1");
const JPEG = Buffer.concat([
Buffer.from([0xff, 0xd8, 0xff, 0xe0]),
Buffer.alloc(16, 0x11),
]);
const PNG = Buffer.concat([
Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
Buffer.alloc(16, 0x22),
]);
const WEBP = Buffer.concat([
Buffer.from("RIFF"),
Buffer.from([0x24, 0x00, 0x00, 0x00]),
Buffer.from("WEBPVP8 "),
Buffer.alloc(8, 0x33),
]);
const GIF87 = Buffer.concat([Buffer.from("GIF87a"), Buffer.alloc(16, 0x44)]);
const GIF89 = Buffer.concat([Buffer.from("GIF89a"), Buffer.alloc(16, 0x44)]);
const ZIP = Buffer.concat([
Buffer.from([0x50, 0x4b, 0x03, 0x04]),
Buffer.alloc(32, 0x55),
]);
const CFB = Buffer.concat([
Buffer.from([0xd0, 0xcf, 0x11, 0xe0, 0xa1, 0xb1, 0x1a, 0xe1]),
Buffer.alloc(32, 0x66),
]);
const RTF = Buffer.from("{\\rtf1\\ansi Hello}", "latin1");
const TIFF_LE = Buffer.concat([
Buffer.from([0x49, 0x49, 0x2a, 0x00]),
Buffer.alloc(16, 0x77),
]);
const TIFF_BE = Buffer.concat([
Buffer.from([0x4d, 0x4d, 0x00, 0x2a]),
Buffer.alloc(16, 0x77),
]);
/** ISO-BMFF ftyp box with the given major + compatible brands. */
function ftyp(major: string, compat: string[] = []): Buffer {
const brands = Buffer.from([major, "0000", ...compat].join(""), "ascii");
const len = Buffer.alloc(4);
len.writeUInt32BE(8 + brands.byteLength);
return Buffer.concat([len, Buffer.from("ftyp"), brands, Buffer.alloc(8)]);
}
const TEXT = Buffer.from("Befund: alles unauffällig.\nZeile 2\n", "utf8");
const MZ = Buffer.concat([Buffer.from("MZ"), Buffer.alloc(64, 0x90)]);
const ELF = Buffer.concat([
Buffer.from([0x7f, 0x45, 0x4c, 0x46]),
Buffer.alloc(32, 0),
]);
const MACHO = Buffer.concat([
Buffer.from([0xcf, 0xfa, 0xed, 0xfe]),
Buffer.alloc(32, 0),
]);
describe("detectDocumentType — Class A (inline; magic bytes only)", () => {
it.each([
["report.pdf", PDF, "application/pdf"],
["photo.jpg", JPEG, "image/jpeg"],
["scan.png", PNG, "image/png"],
["scan.webp", WEBP, "image/webp"],
["anim87.gif", GIF87, "image/gif"],
["anim89.gif", GIF89, "image/gif"],
])("%s → %s inline", (name, bytes, mime) => {
expect(detectDocumentType(bytes, name)).toEqual({
mimeType: mime,
servingClass: "inline",
});
});
it("classifies by bytes, not extension (JPEG named .dat is still a JPEG)", () => {
expect(detectDocumentType(JPEG, "export.dat")).toEqual({
mimeType: "image/jpeg",
servingClass: "inline",
});
});
});
describe("detectDocumentType — Class B (attachment-only)", () => {
it.each([
[
"letter.docx",
ZIP,
"application/vnd.openxmlformats-officedocument.wordprocessingml.document",
],
[
"values.xlsx",
ZIP,
"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
],
[
"slides.pptx",
ZIP,
"application/vnd.openxmlformats-officedocument.presentationml.presentation",
],
["letter.doc", CFB, "application/msword"],
["values.xls", CFB, "application/vnd.ms-excel"],
["slides.ppt", CFB, "application/vnd.ms-powerpoint"],
["note.rtf", RTF, "application/rtf"],
["scan.tif", TIFF_LE, "image/tiff"],
["scan.tiff", TIFF_BE, "image/tiff"],
["befund.txt", TEXT, "text/plain"],
["befund.md", TEXT, "text/plain"],
["werte.csv", TEXT, "text/csv"],
["export.xml", TEXT, "application/xml"],
["export.json", TEXT, "application/json"],
])("%s → %s attachment", (name, bytes, mime) => {
expect(detectDocumentType(bytes, name)).toEqual({
mimeType: mime,
servingClass: "attachment",
});
});
it.each([
["heic (major brand)", ftyp("heic")],
["heix (major brand)", ftyp("heix")],
["hevc (major brand)", ftyp("hevc")],
["mif1 (major brand)", ftyp("mif1")],
["msf1 (major brand)", ftyp("msf1")],
["compatible-brand heic", ftyp("isom", ["heic"])],
])("HEIC/HEIF %s → image/heic attachment", (_label, bytes) => {
expect(detectDocumentType(bytes, "photo.heic")).toEqual({
mimeType: "image/heic",
servingClass: "attachment",
});
});
});
describe("detectDocumentType — deny", () => {
it.each([
["MZ executable", MZ, "payload.pdf"],
["ELF executable", ELF, "scan.png"],
["Mach-O executable", MACHO, "report.txt"],
])("%s is denied regardless of a friendly extension", (_l, bytes, name) => {
expect(detectDocumentType(bytes, name)).toBeNull();
});
it.each([
".exe",
".dll",
".bat",
".cmd",
".sh",
".ps1",
".js",
".mjs",
".jar",
".apk",
".html",
".htm",
".xhtml",
".svg",
".zip",
".7z",
".rar",
".tar",
".gz",
".iso",
".img",
".dmg",
])("extension %s is denied even with harmless text bytes", (ext) => {
expect(detectDocumentType(TEXT, `file${ext}`)).toBeNull();
});
it("denies a ZIP container without an Office extension (incl. no name)", () => {
expect(detectDocumentType(ZIP, "archive.zip")).toBeNull();
expect(detectDocumentType(ZIP, "archive")).toBeNull();
expect(detectDocumentType(ZIP, null)).toBeNull();
// CFB without a legacy-Office extension is equally refused.
expect(detectDocumentType(CFB, "blob.bin")).toBeNull();
});
it("denies text-extension files smuggling NUL bytes", () => {
const binaryish = Buffer.concat([TEXT, Buffer.from([0x00]), TEXT]);
expect(detectDocumentType(binaryish, "befund.txt")).toBeNull();
});
it("denies unidentifiable bytes and empty files", () => {
expect(detectDocumentType(Buffer.from([1, 2, 3, 4, 5, 6]), "x.bin")).toBe(
null,
);
expect(detectDocumentType(Buffer.alloc(0), "empty.txt")).toBeNull();
// Text-like bytes under a non-text extension stay unidentifiable.
expect(detectDocumentType(TEXT, "notes.abc")).toBeNull();
});
it("adversarial: SVG content cannot sneak in under an image extension", () => {
const svg = Buffer.from('<svg xmlns="http://www.w3.org/2000/svg"/>');
expect(detectDocumentType(svg, "image.svg")).toBeNull(); // ext deny
expect(detectDocumentType(svg, "image.png")).toBeNull(); // no PNG magic, no text ext
});
it("adversarial: HTML under a text extension stays attachment-only", () => {
// Accepted as text/plain — but Class B never renders inline, so the
// markup can never execute in-origin.
const html = Buffer.from("<!doctype html><script>alert(1)</script>");
expect(detectDocumentType(html, "page.txt")).toEqual({
mimeType: "text/plain",
servingClass: "attachment",
});
expect(detectDocumentType(html, "page.html")).toBeNull();
});
it("adversarial: a PDF with an HTML head is still a PDF (sandboxed inline)", () => {
const polyglot = Buffer.concat([
Buffer.from("%PDF-1.4\n"),
Buffer.from("<script>alert(1)</script>"),
]);
expect(detectDocumentType(polyglot, "poly.pdf")).toEqual({
mimeType: "application/pdf",
servingClass: "inline",
});
});
});
describe("servingClassFor", () => {
it("marks exactly the browser-native passive set inline", () => {
for (const mime of [
"application/pdf",
"image/jpeg",
"image/png",
"image/webp",
"image/gif",
]) {
expect(servingClassFor(mime)).toBe("inline");
}
});
it("marks every other stored type attachment (incl. unknowns)", () => {
for (const mime of [
"image/heic",
"image/tiff",
"application/msword",
"application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"text/plain",
"text/csv",
"application/rtf",
"application/xml",
"application/json",
"text/html", // must never happen at rest, but even then: attachment
"image/svg+xml",
"application/octet-stream",
]) {
expect(servingClassFor(mime)).toBe("attachment");
}
});
});
describe("resolveDocumentLimits", () => {
beforeEach(() => {
vi.clearAllMocks();
});
it("falls back to the defaults with no settings row and no override", async () => {
vi.mocked(prisma.appSettings.findUnique).mockResolvedValue(null as never);
vi.mocked(prisma.user.findUnique).mockResolvedValue(null as never);
await expect(resolveDocumentLimits("u1")).resolves.toEqual({
maxFileBytes: DOCUMENT_DEFAULT_MAX_FILE_BYTES,
quotaBytes: DOCUMENT_DEFAULT_QUOTA_BYTES,
});
});
it("clamps the per-file cap to the hard 100 MiB ceiling", async () => {
vi.mocked(prisma.appSettings.findUnique).mockResolvedValue({
documentMaxFileBytes: 999_999_999_999,
documentQuotaBytes: BigInt(DOCUMENT_DEFAULT_QUOTA_BYTES),
} as never);
vi.mocked(prisma.user.findUnique).mockResolvedValue(null as never);
const limits = await resolveDocumentLimits("u1");
expect(limits.maxFileBytes).toBe(DOCUMENT_HARD_MAX_FILE_BYTES);
});
it("prefers the per-user quota override over the instance default", async () => {
vi.mocked(prisma.appSettings.findUnique).mockResolvedValue({
documentMaxFileBytes: 26_214_400,
documentQuotaBytes: BigInt(2_000_000_000),
} as never);
vi.mocked(prisma.user.findUnique).mockResolvedValue({
documentQuotaBytes: BigInt(50_000_000),
} as never);
const limits = await resolveDocumentLimits("u1");
expect(limits.quotaBytes).toBe(50_000_000);
});
it("uses the instance quota when the user carries no override", async () => {
vi.mocked(prisma.appSettings.findUnique).mockResolvedValue({
documentMaxFileBytes: 26_214_400,
documentQuotaBytes: BigInt(2_000_000_000),
} as never);
vi.mocked(prisma.user.findUnique).mockResolvedValue({
documentQuotaBytes: null,
} as never);
const limits = await resolveDocumentLimits("u1");
expect(limits.quotaBytes).toBe(2_000_000_000);
});
});
+83
View File
@@ -0,0 +1,83 @@
/**
* Document ⇄ condition link helpers shared by the vault routes.
*
* One grouped query per page (no N+1), owner-scoped everywhere: every episode
* id a client sends is re-narrowed against the caller's live episodes before
* it can land in `document_condition_links`.
*/
import { prisma } from "@/lib/db";
import type { DocumentConditionLinkDto } from "@/lib/validations/inbound-documents";
/**
* Load the condition links for a page of documents in ONE grouped query.
* Returns a map documentId → link DTOs (documents without links are absent).
*/
export async function loadConditionLinks(
userId: string,
documentIds: string[],
): Promise<Map<string, DocumentConditionLinkDto[]>> {
const map = new Map<string, DocumentConditionLinkDto[]>();
if (documentIds.length === 0) return map;
const links = await prisma.documentConditionLink.findMany({
where: { userId, documentId: { in: documentIds } },
select: {
documentId: true,
episodeId: true,
episode: { select: { label: true } },
},
orderBy: { createdAt: "asc" },
});
for (const link of links) {
const entry = map.get(link.documentId) ?? [];
entry.push({ episodeId: link.episodeId, name: link.episode.label });
map.set(link.documentId, entry);
}
return map;
}
/**
* Narrow a client-sent episode-id list to the caller's LIVE episodes.
* Returns the deduplicated owned ids, or null when any id is unknown /
* foreign / deleted — the caller answers with a 404-shaped refusal (an
* attacker probing another user's episode ids learns nothing beyond
* "not found").
*/
export async function narrowOwnedEpisodeIds(
userId: string,
episodeIds: string[],
): Promise<string[] | null> {
const unique = [...new Set(episodeIds)];
if (unique.length === 0) return [];
const owned = await prisma.illnessEpisode.findMany({
where: { id: { in: unique }, userId, deletedAt: null },
select: { id: true },
});
if (owned.length !== unique.length) return null;
return unique;
}
/**
* Replace-set a document's condition links inside the given transaction-ish
* client: delete links no longer in the set, insert the missing ones.
* `episodeIds` MUST already be owner-narrowed (`narrowOwnedEpisodeIds`).
*/
export async function replaceConditionLinks(
tx: Pick<typeof prisma, "documentConditionLink">,
userId: string,
documentId: string,
episodeIds: string[],
): Promise<void> {
await tx.documentConditionLink.deleteMany({
where: { userId, documentId, episodeId: { notIn: episodeIds } },
});
if (episodeIds.length > 0) {
await tx.documentConditionLink.createMany({
data: episodeIds.map((episodeId) => ({
documentId,
episodeId,
userId,
})),
skipDuplicates: true,
});
}
}
+59 -6
View File
@@ -9,14 +9,16 @@
import { Buffer } from "node:buffer";
import { decryptFromBytes, encryptToBytes } from "@/lib/ai/coach/bytes-codec";
import { decrypt, encrypt } from "@/lib/crypto";
import { decrypt, decryptBytes, encrypt, encryptBytes } from "@/lib/crypto";
import type {
ExtractedFact,
ExtractedFactStatus,
InboundDocument,
InboundDocumentStatus,
} from "@/generated/prisma/client";
import { servingClassFor } from "@/lib/documents/upload-policy";
import type {
DocumentConditionLinkDto,
ExtractedFactDto,
FactData,
FactProvenance,
@@ -26,6 +28,20 @@ import type {
InboundFactType,
} from "@/lib/validations/inbound-documents";
/**
* The two storage codecs `InboundDocument.contentEncrypted` may carry,
* recorded per row in the explicit `contentCodec` column (never sniffed):
* - "base64v1" — the legacy string path (base64-of-binary → `encrypt()`
* string → UTF-8 bytes). Pre-vault rows only; kept read-compatible.
* - "binary2" — the binary AES-256-GCM layout (`encryptBytes()`), no
* base64 detour. Every new upload writes this.
*/
export const DOCUMENT_CONTENT_CODECS = ["base64v1", "binary2"] as const;
export type DocumentContentCodec = (typeof DOCUMENT_CONTENT_CODECS)[number];
/** The codec every NEW upload is written with. */
export const ACTIVE_DOCUMENT_CODEC: DocumentContentCodec = "binary2";
/** Encrypt the raw document bytes into the `Bytes` payload the schema stores. */
export function encryptDocumentToBytes(bytes: Buffer): Uint8Array<ArrayBuffer> {
const ciphertext = encrypt(bytes.toString("base64"));
@@ -49,6 +65,31 @@ export function decryptDocumentFromBytes(buf: Uint8Array): Buffer {
return Buffer.from(base64, "base64");
}
/**
* Encrypt raw document bytes with the ACTIVE codec (binary2). Returns the
* `Bytes` payload plus the codec label the row must persist alongside it.
*/
export function encryptDocumentContent(bytes: Buffer): {
content: Uint8Array<ArrayBuffer>;
codec: DocumentContentCodec;
} {
const encrypted = encryptBytes(bytes);
const out = new Uint8Array(new ArrayBuffer(encrypted.byteLength));
out.set(encrypted);
return { content: out, codec: ACTIVE_DOCUMENT_CODEC };
}
/**
* Decrypt a stored document's payload, dispatching on the row's persisted
* codec. Fail-closed: an unknown codec value throws — a silent fallback to
* either codec would either return garbage or mask data corruption.
*/
export function decryptDocumentContent(buf: Uint8Array, codec: string): Buffer {
if (codec === "base64v1") return decryptDocumentFromBytes(buf);
if (codec === "binary2") return decryptBytes(Buffer.from(buf));
throw new Error(`Unknown document content codec '${codec}'`);
}
/**
* Encrypt a staged fact's FHIR-staged payload into the `Bytes` column the
* schema stores. The structured clinical values (diagnosis text, lab values,
@@ -80,10 +121,19 @@ export function decryptFactProvenance(buf: Uint8Array): FactProvenance {
return JSON.parse(decryptFromBytes(buf)) as FactProvenance;
}
/** Map a persisted document row (+ counts) to the list/detail DTO. */
/**
* The row fields the serialisers read. Deliberately WITHOUT
* `contentEncrypted`: the list path must never select the blob column
* (hardening — see the list route's `omit`), so the DTO mappers cannot
* require it either.
*/
export type SerialisableDocument = Omit<InboundDocument, "contentEncrypted">;
/** Map a persisted document row (+ counts + links) to the list/detail DTO. */
export function serialiseDocument(
doc: InboundDocument,
doc: SerialisableDocument,
counts: { factCount: number; pendingCount: number },
conditionLinks: DocumentConditionLinkDto[] = [],
): InboundDocumentDto {
return {
id: doc.id,
@@ -103,6 +153,8 @@ export function serialiseDocument(
errorReason: doc.errorReason,
factCount: counts.factCount,
pendingCount: counts.pendingCount,
conditionLinks,
servingClass: servingClassFor(doc.mimeType),
createdAt: doc.createdAt.toISOString(),
updatedAt: doc.updatedAt.toISOString(),
};
@@ -123,17 +175,18 @@ export function serialiseFact(fact: ExtractedFact): ExtractedFactDto {
};
}
/** Assemble the detail DTO (document + its staged facts). */
/** Assemble the detail DTO (document + its staged facts + links). */
export function serialiseDocumentDetail(
doc: InboundDocument,
doc: SerialisableDocument,
facts: ExtractedFact[],
conditionLinks: DocumentConditionLinkDto[] = [],
): InboundDocumentDetailDto {
const pendingCount = facts.filter((f) => f.status === "PENDING").length;
// `factCount` excludes REJECTED facts (a rejected fact is discarded, not part
// of the document's tally) so the badge matches the list query.
const factCount = facts.filter((f) => f.status !== "REJECTED").length;
return {
...serialiseDocument(doc, { factCount, pendingCount }),
...serialiseDocument(doc, { factCount, pendingCount }, conditionLinks),
facts: facts.map(serialiseFact),
};
}
+370
View File
@@ -0,0 +1,370 @@
/**
* Document-vault upload policy: the accept matrix, magic-byte sniffers, the
* serving-class function, and the admin-tunable limits resolver.
*
* Three classes, closed deny-list, serving posture as the security boundary:
*
* - Class A (inline): PDF, JPEG, PNG, WebP, GIF — browser-native passive
* formats the serve route renders `Content-Disposition: inline` (PDF
* additionally under a `Content-Security-Policy: sandbox` response
* header).
* - Class B (attachment-only): Office (OOXML + legacy CFB), text/CSV/RTF/
* Markdown, TIFF, HEIC/HEIF, XML/JSON — stored verbatim, served ONLY as
* `application/octet-stream` + `Content-Disposition: attachment` +
* `nosniff`. A misclassified Class B file therefore cannot execute in
* the app origin.
* - Deny: executables, scripts, HTML/XHTML/SVG (the only classes whose
* inline render executes script — zero medical-artefact value), generic
* archives / disk images, anything unidentifiable.
*
* The wire Content-Type is NEVER trusted anywhere — detection is magic-bytes
* first, extension only where a container format is ambiguous (ZIP → OOXML,
* CFB → legacy Office) or where no magic exists (plain-text formats). We
* never parse, rewrite, or "sanitise" stored documents: the original is the
* artefact; safety comes from what the serve route will and won't serve
* inline.
*
* The labs OCR path (`src/lib/labs/ocr-upload.ts`) keeps its own 12 MiB cap
* and narrow allowlist unchanged; this module only reuses its bounded-read
* primitive at the route layer.
*/
import { detectAvatarMimeType } from "@/lib/avatar";
import { prisma } from "@/lib/db";
// ─── Limits (§3.3) ──────────────────────────────────────────────────────────
/** Default per-file cap: 25 MiB (a ~50-page 300-dpi scan PDF, any phone photo). */
export const DOCUMENT_DEFAULT_MAX_FILE_BYTES = 26_214_400;
/**
* Hard server ceiling for the admin-tunable per-file cap: 100 MiB. Single-shot
* AES-256-GCM + bounded in-memory reads are load-bearing; past this the
* architecture (chunking, streaming crypto) would have to change, so the
* setting cannot be pushed there.
*/
export const DOCUMENT_HARD_MAX_FILE_BYTES = 104_857_600;
/** Default per-user quota: 1 GiB. */
export const DOCUMENT_DEFAULT_QUOTA_BYTES = 1_073_741_824;
export interface DocumentLimits {
/** Per-file upload cap in bytes (admin-tunable, clamped to the ceiling). */
maxFileBytes: number;
/** Per-user storage quota in bytes (user override ?? instance default). */
quotaBytes: number;
}
/**
* Resolve the effective limits for a user: `AppSettings.documentMaxFileBytes`
* clamped to the hard ceiling, and quota = `User.documentQuotaBytes` ??
* `AppSettings.documentQuotaBytes`. Missing rows fall back to the defaults.
*/
export async function resolveDocumentLimits(
userId: string,
): Promise<DocumentLimits> {
const [settings, user] = await Promise.all([
prisma.appSettings.findUnique({
where: { id: "singleton" },
select: { documentMaxFileBytes: true, documentQuotaBytes: true },
}),
prisma.user.findUnique({
where: { id: userId },
select: { documentQuotaBytes: true },
}),
]);
const rawMax =
settings?.documentMaxFileBytes ?? DOCUMENT_DEFAULT_MAX_FILE_BYTES;
const maxFileBytes = Math.min(
Math.max(rawMax, 1),
DOCUMENT_HARD_MAX_FILE_BYTES,
);
const quotaBytes = Number(
user?.documentQuotaBytes ??
settings?.documentQuotaBytes ??
DOCUMENT_DEFAULT_QUOTA_BYTES,
);
return { maxFileBytes, quotaBytes };
}
// ─── Accept matrix (§3.1) ───────────────────────────────────────────────────
export type DocumentServingClass = "inline" | "attachment";
/** Class A — browser-native passive formats served inline. */
const CLASS_A_MIMES: ReadonlySet<string> = new Set([
"application/pdf",
"image/jpeg",
"image/png",
"image/webp",
"image/gif",
]);
/**
* The one source of truth the serve route uses: Class A renders inline with
* its true Content-Type; EVERYTHING else stored leaves the origin only as an
* opaque attachment download.
*/
export function servingClassFor(mimeType: string): DocumentServingClass {
return CLASS_A_MIMES.has(mimeType) ? "inline" : "attachment";
}
/**
* Extensions the upload UI's `accept` attribute mirrors (Class A + B minus
* HEIC — its exclusion makes the iOS picker auto-transcode camera photos to
* JPEG so the common path stays inline-previewable). Server-side policy
* remains the enforcement; this list is advisory for pickers.
*/
export const DOCUMENT_ACCEPTED_EXTENSIONS: readonly string[] = [
".pdf",
".jpg",
".jpeg",
".png",
".webp",
".gif",
".docx",
".xlsx",
".pptx",
".doc",
".xls",
".ppt",
".txt",
".md",
".csv",
".rtf",
".tif",
".tiff",
".xml",
".json",
];
/**
* Extension deny-list: executables and scripts (regardless of content),
* HTML/XHTML/SVG (inline render executes script), generic archives and disk
* images. A ZIP container is allowed ONLY under an Office extension.
*/
const DENY_EXTENSIONS: ReadonlySet<string> = new Set([
".exe",
".dll",
".bat",
".cmd",
".sh",
".ps1",
".js",
".mjs",
".jar",
".apk",
".html",
".htm",
".xhtml",
".svg",
".zip",
".7z",
".rar",
".tar",
".gz",
".iso",
".img",
".dmg",
]);
/** OOXML extensions → stored MIME (ZIP magic + Office extension required). */
const OOXML_BY_EXTENSION: ReadonlyMap<string, string> = new Map([
[
".docx",
"application/vnd.openxmlformats-officedocument.wordprocessingml.document",
],
[
".xlsx",
"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
],
[
".pptx",
"application/vnd.openxmlformats-officedocument.presentationml.presentation",
],
]);
/** Legacy Office extensions → stored MIME (CFB magic + extension required). */
const CFB_BY_EXTENSION: ReadonlyMap<string, string> = new Map([
[".doc", "application/msword"],
[".xls", "application/vnd.ms-excel"],
[".ppt", "application/vnd.ms-powerpoint"],
]);
/** Text-format extensions → stored MIME (heuristic-gated, no magic bytes). */
const TEXT_BY_EXTENSION: ReadonlyMap<string, string> = new Map([
[".txt", "text/plain"],
[".md", "text/plain"],
[".csv", "text/csv"],
[".xml", "application/xml"],
[".json", "application/json"],
]);
/** Lower-cased extension (with dot) of a filename, or "" when absent. */
function extensionOf(filename: string | null | undefined): string {
if (!filename) return "";
const idx = filename.lastIndexOf(".");
if (idx <= 0 || idx === filename.length - 1) return "";
return filename.slice(idx).toLowerCase();
}
function startsWith(buffer: Buffer, bytes: readonly number[]): boolean {
if (buffer.length < bytes.length) return false;
for (let i = 0; i < bytes.length; i++) {
if (buffer[i] !== bytes[i]) return false;
}
return true;
}
/** `%PDF-` */
function isPdf(buffer: Buffer): boolean {
return startsWith(buffer, [0x25, 0x50, 0x44, 0x46, 0x2d]);
}
/** `GIF87a` / `GIF89a` */
function isGif(buffer: Buffer): boolean {
return (
startsWith(buffer, [0x47, 0x49, 0x46, 0x38, 0x37, 0x61]) ||
startsWith(buffer, [0x47, 0x49, 0x46, 0x38, 0x39, 0x61])
);
}
/** ZIP local-file header `PK\x03\x04` (OOXML containers; also generic ZIPs). */
function isZip(buffer: Buffer): boolean {
return startsWith(buffer, [0x50, 0x4b, 0x03, 0x04]);
}
/** Compound File Binary (legacy Office) `D0 CF 11 E0 A1 B1 1A E1`. */
function isCfb(buffer: Buffer): boolean {
return startsWith(buffer, [0xd0, 0xcf, 0x11, 0xe0, 0xa1, 0xb1, 0x1a, 0xe1]);
}
/** RTF `{\rtf` */
function isRtf(buffer: Buffer): boolean {
return startsWith(buffer, [0x7b, 0x5c, 0x72, 0x74, 0x66]);
}
/** TIFF `II*\0` (little-endian) or `MM\0*` (big-endian). */
function isTiff(buffer: Buffer): boolean {
return (
startsWith(buffer, [0x49, 0x49, 0x2a, 0x00]) ||
startsWith(buffer, [0x4d, 0x4d, 0x00, 0x2a])
);
}
/** HEIC/HEIF — ISO-BMFF `ftyp` box with a HEIF-family brand. */
const HEIF_BRANDS: ReadonlySet<string> = new Set([
"heic",
"heix",
"hevc",
"mif1",
"msf1",
]);
function isHeif(buffer: Buffer): boolean {
if (buffer.length < 12) return false;
if (buffer.toString("ascii", 4, 8) !== "ftyp") return false;
const major = buffer.toString("ascii", 8, 12).toLowerCase();
if (HEIF_BRANDS.has(major)) return true;
// Compatible-brand scan inside the ftyp box (bounded by the box length).
const boxLen = Math.min(buffer.readUInt32BE(0), buffer.length);
for (let off = 16; off + 4 <= boxLen; off += 4) {
const brand = buffer.toString("ascii", off, off + 4).toLowerCase();
if (HEIF_BRANDS.has(brand)) return true;
}
return false;
}
/** Executable magic: MZ (PE), ELF, Mach-O (32/64, both endians, fat). */
function isExecutable(buffer: Buffer): boolean {
if (startsWith(buffer, [0x4d, 0x5a])) return true; // MZ
if (startsWith(buffer, [0x7f, 0x45, 0x4c, 0x46])) return true; // ELF
const machO = [
[0xfe, 0xed, 0xfa, 0xce],
[0xfe, 0xed, 0xfa, 0xcf],
[0xce, 0xfa, 0xed, 0xfe],
[0xcf, 0xfa, 0xed, 0xfe],
[0xca, 0xfe, 0xba, 0xbe],
] as const;
return machO.some((m) => startsWith(buffer, m));
}
/**
* Plain-text heuristic for the extension-gated text formats: no NUL byte in
* the first 8 KiB and the sample decodes as UTF-8 or Latin-1 (any byte
* sequence is valid Latin-1, so the effective gate is "no NUL" — a binary
* payload smuggled under `.txt` almost always carries NULs; if one does not,
* it is still stored Class B and can only ever leave as an opaque download).
*/
function looksLikeText(buffer: Buffer): boolean {
if (buffer.length === 0) return false;
const sample = buffer.subarray(0, 8192);
return !sample.includes(0x00);
}
export interface DetectedDocumentType {
/** The MIME type the row stores (sniffed, never the wire Content-Type). */
mimeType: string;
/** Derived serving class (same as `servingClassFor(mimeType)`). */
servingClass: DocumentServingClass;
}
/**
* Classify an upload from its bytes (+ the claimed filename, used only where
* a container/text format needs an extension gate). Returns null for every
* deny case: executables, script/markup extensions, generic archives, ZIPs
* without an Office extension, and anything unidentifiable.
*/
export function detectDocumentType(
buffer: Buffer,
filename: string | null | undefined,
): DetectedDocumentType | null {
const ext = extensionOf(filename);
// Hard denies first: content-level executables, then the extension
// deny-list (an .exe named payload is refused even if its bytes look like
// text; HTML/SVG are refused regardless of content).
if (isExecutable(buffer)) return null;
if (DENY_EXTENSIONS.has(ext)) return null;
// ── Class A (magic bytes only — extension is irrelevant) ──
if (isPdf(buffer)) {
return { mimeType: "application/pdf", servingClass: "inline" };
}
if (isGif(buffer)) {
return { mimeType: "image/gif", servingClass: "inline" };
}
const image = detectAvatarMimeType(buffer);
if (image) {
return { mimeType: image, servingClass: "inline" };
}
// ── Class B (magic where it exists; containers need the extension) ──
if (isZip(buffer)) {
// A ZIP container is acceptable ONLY as an OOXML Office file; a generic
// archive (any other extension, incl. none) is denied.
const ooxml = OOXML_BY_EXTENSION.get(ext);
return ooxml ? { mimeType: ooxml, servingClass: "attachment" } : null;
}
if (isCfb(buffer)) {
const legacy = CFB_BY_EXTENSION.get(ext);
return legacy ? { mimeType: legacy, servingClass: "attachment" } : null;
}
if (isRtf(buffer)) {
return { mimeType: "application/rtf", servingClass: "attachment" };
}
if (isTiff(buffer)) {
return { mimeType: "image/tiff", servingClass: "attachment" };
}
if (isHeif(buffer)) {
return { mimeType: "image/heic", servingClass: "attachment" };
}
// ── Text formats (extension + heuristic; no magic bytes exist) ──
const text = TEXT_BY_EXTENSION.get(ext);
if (text && looksLikeText(buffer)) {
return { mimeType: text, servingClass: "attachment" };
}
// Unidentifiable → deny.
return null;
}
+58
View File
@@ -0,0 +1,58 @@
/**
* Daily physical purge for soft-deleted document-vault rows.
*
* Delete in the vault is undo-able: the DELETE route tombstones
* (`deletedAt`), the UI's undo toast and the restore endpoint clear the
* tombstone, and THIS job hard-deletes tombstones older than the 30-day
* grace window — returning the TOAST space the encrypted blob holds (a
* tombstoned document keeps counting against the quota until purged, so
* "deleted" bytes are never invisible backup weight). Staged facts cascade
* via the FK. Restore-after-purge answers 409 at the API.
*/
import { type Job } from "pg-boss";
import { withBackgroundEvent } from "@/lib/logging/background";
import { getWorkerPrisma } from "@/lib/jobs/reminder/shared";
import type { PrismaClient } from "@/generated/prisma/client";
export const DOCUMENT_PURGE_QUEUE = "document-tombstone-purge";
/** Daily at 04:10 Europe/Berlin — after the med-notes backfill tick (04:05). */
export const DOCUMENT_PURGE_CRON = "10 4 * * *";
/** Days a tombstoned document stays restorable before the purge claims it. */
export const DOCUMENT_PURGE_GRACE_DAYS = 30;
const DAY_MS = 86_400_000;
export interface DocumentPurgePayload {
triggeredAt?: string;
}
/**
* Hard-delete tombstoned `inbound_documents` rows whose `deletedAt` is older
* than the grace horizon. Returns the number of rows purged. Rows inside the
* grace window and live rows are never touched.
*/
export async function purgeExpiredDocumentTombstones(
prisma: PrismaClient,
now: Date = new Date(),
): Promise<number> {
const cutoff = new Date(now.getTime() - DOCUMENT_PURGE_GRACE_DAYS * DAY_MS);
const { count } = await prisma.inboundDocument.deleteMany({
where: { deletedAt: { not: null, lt: cutoff } },
});
return count;
}
export async function handleDocumentPurge(jobs: Job<DocumentPurgePayload>[]) {
void jobs;
await withBackgroundEvent("job.document_tombstone_purge", async (evt) => {
const prisma = getWorkerPrisma();
try {
const purged = await purgeExpiredDocumentTombstones(prisma);
evt.setAction({ name: "documents.vault.purge" });
evt.addMeta("document_purge_deleted", purged);
} catch (err) {
evt.addWarning(`document-tombstone-purge failed: ${err}`);
}
});
}
@@ -124,6 +124,12 @@ import {
handleMedicationInventoryExpire,
handleIntakeAutoSkip,
} from "./medication-maintenance";
import {
DOCUMENT_PURGE_QUEUE,
DOCUMENT_PURGE_CRON,
handleDocumentPurge,
type DocumentPurgePayload,
} from "@/lib/jobs/document-purge";
const DATA_BACKUP_QUEUE = "data-backup";
@@ -287,6 +293,11 @@ const allQueues = [
// plaintext medication note; without this entry pg-boss never provisions the
// queue and both the boot enqueue and the cron silently no-op.
MED_NOTES_ENCRYPTION_BACKFILL_QUEUE,
// Document vault — daily physical purge for tombstones past the 30-day
// undo grace (returns the encrypted blob's TOAST space). Without this entry
// the daily schedule silently no-ops and "deleted" documents hold backup
// weight forever.
DOCUMENT_PURGE_QUEUE,
];
const schedules: ScheduleEntry[] = [
@@ -352,6 +363,9 @@ const schedules: ScheduleEntry[] = [
// fan out one per-user job per account still holding a plaintext medication
// note.
[MED_NOTES_ENCRYPTION_BACKFILL_QUEUE, MED_NOTES_ENCRYPTION_BACKFILL_CRON],
// Document vault — daily 04:10 Europe/Berlin purge for tombstoned
// documents past the 30-day undo grace.
[DOCUMENT_PURGE_QUEUE, DOCUMENT_PURGE_CRON],
];
/**
@@ -448,6 +462,14 @@ export async function registerMaintenanceQueues(
{ localConcurrency: 1 },
handleMcpTokenCleanup,
);
// Document vault — daily purge of tombstoned documents past the 30-day
// undo grace. Single-flight like every other cleanup queue; the underlying
// deleteMany is idempotent so a duplicate tick is a no-op.
await boss.work<DocumentPurgePayload>(
DOCUMENT_PURGE_QUEUE,
{ localConcurrency: 1 },
handleDocumentPurge,
);
await boss.work<PrDetectionPayload>(
PR_DETECTION_QUEUE,
{ localConcurrency: PR_DETECTION_CONCURRENCY },
+11 -12
View File
@@ -374,22 +374,21 @@ describe("registry — opt-in marker", () => {
});
});
describe("resolveModuleEnabled — inboundDocuments module (disabled in code)", () => {
// v1.25.3 — `inboundDocuments` is switched off in code pending a rebuild
// (`CODE_DISABLED_MODULE_KEYS`). It is hard-off ahead of both the operator
// and the per-user layer: no stored preference or availability blob can
// re-surface it. The registry entry + `optIn` marker stay intact.
it("is flagged as code-disabled in the registry", () => {
expect(isCodeDisabledModule("inboundDocuments")).toBe(true);
describe("resolveModuleEnabled — inboundDocuments module (document vault)", () => {
// Parked in code from v1.25.3; the document vault re-enabled it. Normal
// two-layer opt-in resolution applies again: dark by default, ON only on
// an explicit per-user opt-in, and an operator `false` still wins.
it("is no longer flagged as code-disabled in the registry", () => {
expect(isCodeDisabledModule("inboundDocuments")).toBe(false);
});
it("is OFF when no preference is recorded", () => {
it("is OFF when no preference is recorded (opt-in ships dark)", () => {
expect(
resolveModuleEnabled("inboundDocuments", inputs(), false, ALL_AVAILABLE),
).toBe(false);
});
it("stays OFF even when the user opted in (the in-code switch wins)", () => {
it("is ON when the user opted in", () => {
expect(
resolveModuleEnabled(
"inboundDocuments",
@@ -397,16 +396,16 @@ describe("resolveModuleEnabled — inboundDocuments module (disabled in code)",
false,
ALL_AVAILABLE,
),
).toBe(false);
).toBe(true);
});
it("stays OFF when the user opted in and the operator left it available", () => {
it("stays OFF when the operator disabled it, even with a user opt-in", () => {
expect(
resolveModuleEnabled(
"inboundDocuments",
inputs({ modulePreferences: { inboundDocuments: true } }),
false,
operator({ inboundDocuments: true }),
operator({ inboundDocuments: false }),
),
).toBe(false);
});
+5 -5
View File
@@ -338,12 +338,12 @@ export function isModuleKey(key: string): key is ModuleKey {
* migration) stays intact — re-enabling the module is a one-line removal
* from this list once the rebuild lands.
*
* v1.25.3 — `inboundDocuments` is parked here: the inbound-documents surface
* is withdrawn from this release and returns later with more depth. Its
* registry entry, `optIn` marker, routes, view, and migration 0222 are all
* preserved; only the user-reachable switches are removed.
* Currently empty. `inboundDocuments` was parked here from v1.25.3 until the
* document vault re-enabled it (per-user opt-in + operator availability
* resume their normal two-layer resolution; the module still ships dark by
* default via `optIn`).
*/
export const CODE_DISABLED_MODULE_KEYS = ["inboundDocuments"] as const;
export const CODE_DISABLED_MODULE_KEYS = [] as const;
const CODE_DISABLED_MODULE_SET: ReadonlySet<string> = new Set(
CODE_DISABLED_MODULE_KEYS,
+190 -9
View File
@@ -18,6 +18,7 @@ import type { ZodOpenApiObject } from "zod-openapi";
import { z } from "zod/v4";
import {
documentBulkSchema,
documentUpdateSchema,
inboundConfirmSchema,
inboundFactEditSchema,
@@ -45,7 +46,13 @@ inboundFactEditSchema.meta({
documentUpdateSchema.meta({
id: "DocumentUpdateRequest",
description:
"Metadata edit for a stored document: `title` (user label; null clears it), `kind` (category), `documentDate` (user filing date, YYYY-MM-DD; null clears it). At least one field required. No `userId` field — narrowed from the session and fed to the Prisma `where` with the row id.",
"Metadata edit for a stored document: `title` (user label; null clears it), `kind` (category), `documentDate` (user filing date, YYYY-MM-DD; null clears it), `episodeIds` (REPLACE-SET of condition links — the document's links become exactly this set; an empty array unlinks everything; every id must be a live episode of the caller or the whole request answers 404). At least one field required. No `userId` field — narrowed from the session and fed to the Prisma `where` with the row id.",
});
documentBulkSchema.meta({
id: "DocumentBulkRequest",
description:
"One bulk action over up to 100 owner-scoped documents: `setKind` (requires `kind`), `linkEpisode` / `unlinkEpisode` (require `episodeId`), `delete` (tombstone, undo-able for 30 days), `restore` (clear tombstone). Partial failures never abort the batch — see the per-id result array.",
});
const factProvenance = z.object({
@@ -72,6 +79,17 @@ const extractedFact = z
"One STATED fact transcribed from the document, FHIR-staged (Condition / Observation / MedicationStatement) with per-field provenance + a confidence gate. STATED status only — codes (SNOMED/ICD-10/LOINC/RxNorm/ATC) are present only when the document wrote them; no range-flag, no inferred links. `needsReview` is true when the fact scored below the confidence floor (it cannot be approved until edited).",
});
const conditionLink = z
.object({
episodeId: z.string(),
name: z.string(),
})
.meta({
id: "DocumentConditionLink",
description:
"A link to one of the caller's illness/condition episodes. `name` is the episode's user-facing label.",
});
const inboundDocument = z
.object({
id: z.string(),
@@ -87,13 +105,15 @@ const inboundDocument = z
errorReason: z.string().nullable(),
factCount: z.number(),
pendingCount: z.number(),
conditionLinks: z.array(conditionLink),
servingClass: z.enum(["inline", "attachment"]),
createdAt: z.string(),
updatedAt: z.string(),
})
.meta({
id: "InboundDocument",
description:
"A stored document. The raw bytes are stored encrypted at rest and never returned; this is the metadata + staging summary. `status` is STORED for a freshly uploaded file (no extraction run). `title` is the user label (plaintext); `documentDate` is the user filing date; `reportDate` is the model-transcribed date (null until extraction runs).",
"A stored document. The raw bytes are stored encrypted at rest and never returned; this is the metadata + staging summary. `status` is STORED for a freshly uploaded file (no extraction run). `title` is the user label (plaintext); `documentDate` is the user filing date; `reportDate` is the model-transcribed date (null until extraction runs). `servingClass` says how `/original` delivers the file — render inline (`inline`) or download-only (`attachment`); render/download by it, never by MIME guess. Treat an unknown `kind` value as OTHER when decoding.",
});
const inboundDocumentDetail = inboundDocument
@@ -132,6 +152,13 @@ const confirmResponse = z
const kindValues = [...INBOUND_DOCUMENT_KINDS];
// Shared by the POST 200 (duplicate) and 201 (created) responses — the
// envelope id must be registered exactly once.
const inboundDocumentEnvelope = dataEnvelope(
inboundDocument,
"InboundDocumentEnvelope",
);
export const inboundDocumentPaths: NonNullable<ZodOpenApiObject["paths"]> = {
"/api/documents/inbound": {
get: {
@@ -151,8 +178,30 @@ export const inboundDocumentPaths: NonNullable<ZodOpenApiObject["paths"]> = {
name: "kind",
in: "query",
required: false,
schema: { type: "string", enum: kindValues },
description: "Category filter.",
style: "form",
explode: true,
schema: {
type: "array",
items: { type: "string", enum: kindValues },
},
description:
"Category filter — OR inside the facet. Repeat the parameter (or send a comma-separated value).",
},
{
name: "episodeId",
in: "query",
required: false,
schema: { type: "string" },
description:
"Only documents linked to this illness/condition episode.",
},
{
name: "year",
in: "query",
required: false,
schema: { type: "integer", minimum: 1900, maximum: 9999 },
description:
"Only documents whose filing date falls in this calendar year (UTC). Takes precedence over from/to.",
},
{
name: "from",
@@ -219,7 +268,7 @@ export const inboundDocumentPaths: NonNullable<ZodOpenApiObject["paths"]> = {
tags: ["Documents"],
summary: "Store a document (no extraction)",
description:
"STORE-ONLY upload. Stores the raw document ENCRYPTED at rest with `status: STORED` and runs NO extraction — provider-free, no AI consent / budget / egress. A file is always filable, even with no document-scan provider configured. `multipart/form-data`: a `file` (JPEG/PNG/WebP/PDF, validated by magic-byte MIME sniff, ≤ 12 MiB) plus optional `title`, `kind`, and `documentDate` (YYYY-MM-DD) form fields. AI extraction is a separate opt-in action — see `POST /api/documents/inbound/{id}/extract`.",
'STORE-ONLY upload. Stores the raw document ENCRYPTED at rest with `status: STORED` and runs NO extraction — provider-free, no AI consent / budget / egress. A file is always filable, even with no document-scan provider configured. `multipart/form-data`: a `file` plus optional `title`, `kind`, `documentDate` (YYYY-MM-DD), and repeated `episodeIds` form fields (pre-link to the caller\'s illness/condition episodes). Accepted types (magic-byte sniffed, never the wire Content-Type): PDF/JPEG/PNG/WebP/GIF render inline; Office (docx/xlsx/pptx/doc/xls/ppt), text/CSV/Markdown/RTF, TIFF, HEIC/HEIF, XML/JSON are stored verbatim and served download-only. HEIC is stored as-is but attachment-only — prefer transcoding to JPEG client-side for inline preview parity. Error contract: `413` with `meta.reason = "fileTooLarge"` (+ `maxFileBytes`) or `"quotaExceeded"` (+ `quotaBytes`, `usedBytes`); `415` with `meta.reason = "unsupportedType"`. A same-user duplicate (same bytes) returns 200 + `meta.duplicate: true` with the existing row — not an error. `Idempotency-Key` honoured. Read `GET /api/documents/inbound/usage` for the effective limits before offering an upload. AI extraction is a separate opt-in action — see `POST /api/documents/inbound/{id}/extract`.',
requestBody: {
required: true,
content: {
@@ -228,7 +277,7 @@ export const inboundDocumentPaths: NonNullable<ZodOpenApiObject["paths"]> = {
file: z.string().meta({
format: "binary",
description:
"The document image or PDF. Validated by magic-byte MIME sniff, not the wire Content-Type.",
"The document. Validated by magic-byte MIME sniff, not the wire Content-Type.",
}),
title: z
.string()
@@ -241,16 +290,110 @@ export const inboundDocumentPaths: NonNullable<ZodOpenApiObject["paths"]> = {
description:
"Optional user filing date (YYYY-MM-DD). Defaults to the upload day when omitted so the library sort/filter/display stay aligned.",
}),
episodeIds: z.array(z.string()).optional().meta({
description:
"Optional condition pre-links (repeat the field per id). Every id must be a live episode of the caller.",
}),
}),
},
},
},
responses: {
"200": {
description:
"Duplicate — the same bytes are already stored: the existing row, with `meta.duplicate: true` at the envelope level.",
content: {
"application/json": {
schema: inboundDocumentEnvelope,
},
},
},
"201": {
description: "The stored document.",
content: {
"application/json": {
schema: dataEnvelope(inboundDocument, "InboundDocumentEnvelope"),
schema: inboundDocumentEnvelope,
},
},
},
"413": {
description:
"Too large: `meta.reason` is `fileTooLarge` (with `maxFileBytes`) or `quotaExceeded` (with `quotaBytes` + `usedBytes`).",
content: { "application/json": { schema: errorEnvelope } },
},
"415": {
description:
'Unsupported or unidentifiable type (`meta.reason = "unsupportedType"`). Executables, HTML/SVG, and generic archives are always refused.',
content: { "application/json": { schema: errorEnvelope } },
},
...stdResponses,
},
},
},
"/api/documents/inbound/usage": {
get: {
tags: ["Documents"],
summary: "Storage usage + effective limits",
description:
"The caller's vault usage and effective limits: `usedBytes` (every non-purged row — tombstones inside the 30-day undo grace still count), `quotaBytes` (per-user override ?? instance default), `maxFileBytes` (admin-tunable per-file cap), `acceptedExtensions` for picker `accept` lists, and `linkedEpisodes` (episodes carrying at least one live document link — the condition-filter chips). Read this before offering an upload.",
responses: {
"200": {
description: "Usage + limits.",
content: {
"application/json": {
schema: dataEnvelope(
z
.object({
usedBytes: z.number(),
quotaBytes: z.number(),
maxFileBytes: z.number(),
acceptedExtensions: z.array(z.string()),
linkedEpisodes: z.array(
z.object({
episodeId: z.string(),
name: z.string(),
}),
),
})
.meta({ id: "DocumentUsage" }),
"DocumentUsageEnvelope",
),
},
},
},
...stdResponses,
},
},
},
"/api/documents/inbound/bulk": {
post: {
tags: ["Documents"],
summary: "Bulk action over documents",
description:
"Applies one action to up to 100 owner-scoped documents and returns a per-id result array — a partial failure never aborts the batch. `error` is `notFound` (unknown / foreign / tombstoned where liveness is required) or `conflict` (restore blocked by a live duplicate of the same bytes).",
requestBody: {
required: true,
content: { "application/json": { schema: documentBulkSchema } },
},
responses: {
"200": {
description: "Per-id outcomes.",
content: {
"application/json": {
schema: dataEnvelope(
z
.object({
results: z.array(
z.object({
id: z.string(),
ok: z.boolean(),
error: z.string().nullable(),
}),
),
})
.meta({ id: "DocumentBulkResponse" }),
"DocumentBulkEnvelope",
),
},
},
},
@@ -348,12 +491,47 @@ export const inboundDocumentPaths: NonNullable<ZodOpenApiObject["paths"]> = {
},
},
},
"/api/documents/inbound/{id}/restore": {
post: {
tags: ["Documents"],
summary: "Restore a discarded document",
description:
'Clears the soft-delete tombstone within the 30-day undo grace. 409 when the tombstone is already purged (the undo window is over) or when an identical live document blocks the restore (`meta.reason = "duplicateExists"`). Restoring an already-live document is a no-op success.',
parameters: [
{
name: "id",
in: "path",
required: true,
schema: { type: "string" },
},
],
responses: {
"200": {
description: "The restored document + its staged facts.",
content: {
"application/json": {
schema: dataEnvelope(
inboundDocumentDetail,
"InboundRestoreEnvelope",
),
},
},
},
"409": {
description:
"Not restorable: purged past the grace window, or an identical live document exists.",
content: { "application/json": { schema: errorEnvelope } },
},
...stdResponses,
},
},
},
"/api/documents/inbound/{id}/original": {
get: {
tags: ["Documents"],
summary: "View / download the original document",
description:
"Decrypts and serves the raw uploaded document (the bytes stored encrypted at rest under `InboundDocument.contentEncrypted`). Owner-scoped + gated on the opt-in `inboundDocuments` module. Uploads are constrained at the store path to the inline-safe set (JPEG / PNG / WebP / PDF), so the document is always served `Content-Disposition: inline` for in-tab rendering; a non-ASCII filename is carried via RFC 5987 `filename*`. Fails closed (500) on a decrypt error — it never returns the ciphertext.",
"Decrypts and serves the raw uploaded document (the bytes stored encrypted at rest under `InboundDocument.contentEncrypted`). Owner-scoped + gated on the opt-in `inboundDocuments` module. Serving posture follows the document's `servingClass`: inline types (PDF/JPEG/PNG/WebP/GIF) come with their true Content-Type, `Content-Disposition: inline`, `nosniff`, and a `Content-Security-Policy: sandbox` header; attachment types (Office/text/TIFF/HEIC/XML/JSON) ALWAYS come as `application/octet-stream` + `Content-Disposition: attachment` + `nosniff` — never inline. A non-ASCII filename is carried via RFC 5987 `filename*`. Fails closed (500) on a decrypt error — it never returns the ciphertext.",
parameters: [
{
name: "id",
@@ -365,7 +543,7 @@ export const inboundDocumentPaths: NonNullable<ZodOpenApiObject["paths"]> = {
responses: {
"200": {
description:
"The decrypted original document bytes with the stored MIME type.",
"The decrypted original document bytes. Inline types carry the stored MIME type; attachment types are served as application/octet-stream.",
content: {
"application/pdf": {
schema: { type: "string", format: "binary" },
@@ -373,6 +551,9 @@ export const inboundDocumentPaths: NonNullable<ZodOpenApiObject["paths"]> = {
"image/*": {
schema: { type: "string", format: "binary" },
},
"application/octet-stream": {
schema: { type: "string", format: "binary" },
},
},
},
...stdResponses,
+43 -24
View File
@@ -1,42 +1,61 @@
/**
* Query keys — clinical documents library (v1.25, W-DOCS-IN): the browsable
* document list (search / category filter / sort, keyset-paginated) and a
* single document's detail (document + staged facts). Part of the centralized
* factory; aggregated in `./index.ts`. Any document write (upload / edit /
* extract / confirm / discard) invalidates the `["documents"]` prefix so the
* list and the open detail repaint in lockstep.
* Query keys — the Dokumente vault: the filtered timeline list (keyset-
* paginated), a single document's detail, and the usage/limits read the
* upload path pre-flights against. Part of the centralized factory;
* aggregated in `./index.ts`. Any document write (upload / edit / link /
* delete / restore / bulk) invalidates the `["documents"]` prefix so the
* timeline, an open detail sheet, and the quota bar repaint in lockstep.
*/
import type {
DocumentListSort,
InboundDocumentKindValue,
} from "@/lib/validations/inbound-documents";
import type { InboundDocumentKindValue } from "@/lib/validations/inbound-documents";
/**
* The parameter set that distinguishes one library list view from another.
* Lives in the key so two different filter/sort combinations never share a
* cache bucket. `undefined` fields are dropped by TanStack's stable hash, so a
* bare `{ sort, order }` and `{ q: undefined, kind: undefined, sort, order }`
* resolve to the same key.
* The parameter set that distinguishes one vault timeline view from another —
* mirrors the URL facets (`?q&kind&episode&year`) one-to-one so a deep link
* and an in-page filter change resolve to the same cache bucket. `undefined`
* fields are dropped by TanStack's stable hash, so an all-defaults view and
* an explicit `{ q: undefined, … }` share a key. Sort is pinned server-side
* (filing date, newest first) and is deliberately NOT part of the key.
*/
export interface DocumentListParams {
export interface DocumentVaultFilters {
q?: string;
kind?: InboundDocumentKindValue;
from?: string;
to?: string;
sort: DocumentListSort;
order: "asc" | "desc";
/** Type facet — OR inside the facet, sorted before keying by the caller. */
kinds?: InboundDocumentKindValue[];
/** Only documents linked to this illness/condition episode. */
episodeId?: string;
/** Only documents whose filing date falls in this calendar year. */
year?: number;
}
export const documentKeys = {
documents: () => ["documents"] as const,
inboundDocuments: () => ["documents", "inbound"] as const,
/**
* The parameterised library list (keyset-paginated via `useInfiniteQuery`).
* The parameterised vault list (keyset-paginated via `useInfiniteQuery`).
* The literal `"list"` segment keeps it distinct from a single-document key
* (`inboundDocument(id)`); cuid ids never collide with it. Stays under the
* `["documents", "inbound"]` prefix so prefix invalidation still reaches it.
*/
inboundDocumentList: (params: DocumentListParams) =>
["documents", "inbound", "list", params] as const,
inboundDocumentList: (filters: DocumentVaultFilters) =>
["documents", "inbound", "list", filters] as const,
inboundDocument: (id: string) => ["documents", "inbound", id] as const,
/**
* The illness-episode detail's compact document preview (single page,
* small limit). Deliberately NOT `inboundDocumentList({ episodeId })` —
* that key belongs to the vault's `useInfiniteQuery` and a plain query
* under the same key would poison the cache with a different shape.
*/
inboundDocumentEpisodePreview: (episodeId: string) =>
["documents", "inbound", "episode-preview", episodeId] as const,
/**
* The link-existing-documents picker (searchable single page). Own key
* for the same shape-collision reason as the episode preview.
*/
inboundDocumentPicker: (q: string) =>
["documents", "inbound", "picker", q] as const,
/**
* Storage usage + effective limits (`GET /api/documents/inbound/usage`).
* Invalidated through the `["documents"]` prefix after every upload /
* delete so the quota bar tracks reality.
*/
inboundDocumentUsage: () => ["documents", "inbound", "usage"] as const,
};
+17
View File
@@ -67,6 +67,23 @@ export const adminSettingsSchema = z
reminderLateMinutes: z.number().int().min(15).max(480).optional(),
reminderMissedMinutes: z.number().int().min(30).max(720).optional(),
moodLogGlobal: z.boolean().optional(),
// Document vault — the two admin-tunable limits. The per-file cap is
// bounded by the hard 100 MiB ceiling (single-shot GCM + bounded
// in-memory reads are load-bearing past that; the runtime resolver
// clamps again as defence-in-depth). The quota accepts up to 1 TiB —
// BYTEA rides pg_dump, so anything larger is an operator error.
documentMaxFileBytes: z
.number()
.int()
.min(1_048_576)
.max(104_857_600)
.optional(),
documentQuotaBytes: z
.number()
.int()
.min(10_485_760)
.max(1_099_511_627_776)
.optional(),
// v1.4.25 W7 — server-wide default timezone for new signups
// that don't carry a browser-detected zone. The route validates
// against Intl.supportedValuesOf at runtime; this schema just
+110 -4
View File
@@ -52,6 +52,7 @@ export const INBOUND_DOCUMENT_KINDS = [
"LAB_RESULT",
"IMAGING",
"PRESCRIPTION",
"REFERRAL",
"INSURANCE",
"VACCINATION",
"OTHER",
@@ -196,6 +197,13 @@ export interface ExtractedFactDto {
committedRecordType: string | null;
}
/** One condition link on a document DTO (chip → `/illness/[id]`). */
export interface DocumentConditionLinkDto {
episodeId: string;
/** The episode's user-facing label. */
name: string;
}
/** The document DTO (list + detail). */
export interface InboundDocumentDto {
id: string;
@@ -216,6 +224,10 @@ export interface InboundDocumentDto {
factCount: number;
/** Count of staged facts still PENDING review. */
pendingCount: number;
/** Linked illness/condition episodes (empty when unlinked). */
conditionLinks: DocumentConditionLinkDto[];
/** How the serve route delivers the original: render inline or download. */
servingClass: "inline" | "attachment";
createdAt: string;
updatedAt: string;
}
@@ -343,16 +355,26 @@ const isoDateString = z
export const DOCUMENT_TITLE_MAX = 200;
/** Max condition links a single document may carry / receive per request. */
export const DOCUMENT_MAX_EPISODE_LINKS = 20;
const episodeIdList = z
.array(z.string().trim().min(1).max(40))
.max(DOCUMENT_MAX_EPISODE_LINKS);
/**
* The store-only upload metadata (the multipart form fields beside the file).
* Every field is optional — a bare file upload is valid and lands as a STORED
* document with no title / category / filing date. No `userId` field; it is
* always narrowed from the session.
* document with no title / category / filing date. `episodeIds` pre-links the
* document to the caller's illness/condition episodes (repeated `episodeIds`
* form fields; ownership is re-checked in the route). No `userId` field; it
* is always narrowed from the session.
*/
export const documentCreateSchema = z.object({
title: z.string().trim().min(1).max(DOCUMENT_TITLE_MAX).optional(),
kind: z.enum(INBOUND_DOCUMENT_KINDS).optional(),
documentDate: isoDateString.optional(),
episodeIds: episodeIdList.optional(),
});
export type DocumentCreateInput = z.infer<typeof documentCreateSchema>;
@@ -374,12 +396,19 @@ export const documentUpdateSchema = z
.transform((v) => (v === "" ? null : v)),
kind: z.enum(INBOUND_DOCUMENT_KINDS).optional(),
documentDate: isoDateString.nullable().optional(),
/**
* Replace-set condition links: the document's links become exactly this
* set (an empty array unlinks everything). Ownership of every episode id
* is re-checked in the route against the caller's episodes.
*/
episodeIds: episodeIdList.optional(),
})
.refine(
(d) =>
d.title !== undefined ||
d.kind !== undefined ||
d.documentDate !== undefined,
d.documentDate !== undefined ||
d.episodeIds !== undefined,
{ message: "Provide at least one field to update" },
);
@@ -403,7 +432,15 @@ export const DOCUMENT_LIST_DEFAULT_LIMIT = 50;
*/
export const documentListQuerySchema = z.object({
q: z.string().trim().max(100).optional(),
kind: z.enum(INBOUND_DOCUMENT_KINDS).optional(),
/**
* Category filter — OR inside the facet. Repeated `kind` params or a
* comma-separated value; the route normalises to an array before parsing.
*/
kind: z.array(z.enum(INBOUND_DOCUMENT_KINDS)).max(16).optional(),
/** Only documents linked to this illness/condition episode. */
episodeId: z.string().trim().min(1).max(40).optional(),
/** Only documents whose filing date falls in this calendar year (UTC). */
year: z.coerce.number().int().min(1900).max(9999).optional(),
from: isoDateString.optional(),
to: isoDateString.optional(),
sort: z.enum(DOCUMENT_LIST_SORTS).default("documentDate"),
@@ -418,3 +455,72 @@ export const documentListQuerySchema = z.object({
});
export type DocumentListQuery = z.infer<typeof documentListQuerySchema>;
// ─── Vault: bulk actions ───────────────────────────────────────────────────
/** Max document ids one bulk request may touch. */
export const DOCUMENT_BULK_MAX_IDS = 100;
export const DOCUMENT_BULK_ACTIONS = [
"setKind",
"linkEpisode",
"unlinkEpisode",
"delete",
"restore",
] as const;
export type DocumentBulkAction = (typeof DOCUMENT_BULK_ACTIONS)[number];
/**
* One bulk action over up to 100 owner-scoped documents. `setKind` requires
* `kind`; `linkEpisode` / `unlinkEpisode` require `episodeId` (ownership
* re-checked in the route). Per-id outcomes ride the response so a partial
* failure never aborts the batch. No `userId` field — narrowed from the
* session.
*/
export const documentBulkSchema = z
.object({
ids: z
.array(z.string().trim().min(1).max(40))
.min(1)
.max(DOCUMENT_BULK_MAX_IDS),
action: z.enum(DOCUMENT_BULK_ACTIONS),
kind: z.enum(INBOUND_DOCUMENT_KINDS).optional(),
episodeId: z.string().trim().min(1).max(40).optional(),
})
.refine((d) => d.action !== "setKind" || d.kind !== undefined, {
message: "Action 'setKind' requires a kind",
path: ["kind"],
})
.refine(
(d) =>
(d.action !== "linkEpisode" && d.action !== "unlinkEpisode") ||
d.episodeId !== undefined,
{
message: "Episode actions require an episodeId",
path: ["episodeId"],
},
);
export type DocumentBulkInput = z.infer<typeof documentBulkSchema>;
/** Per-id outcome in the bulk response. */
export interface DocumentBulkResultDto {
id: string;
ok: boolean;
/** Short machine reason when `ok` is false (e.g. "notFound", "conflict"). */
error: string | null;
}
/** The usage endpoint payload the UI reads before offering an upload. */
export interface DocumentUsageDto {
usedBytes: number;
quotaBytes: number;
maxFileBytes: number;
acceptedExtensions: string[];
/**
* Episodes carrying at least one LIVE document link — the vault filter
* bar's condition chips. Sourced server-side so a chip exists even when
* every linked document sits pages deep in the timeline.
*/
linkedEpisodes: DocumentConditionLinkDto[];
}