mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-18 16:12:11 +00:00
Merge branch 'feat/vault-w4-qa' into release/v1.27.17
This commit is contained in:
commit
03058b0210
81 files changed
+10544
-3246
No files matched your search
Binary file not shown.
@@ -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);
|
||||
}
|
||||
});
|
||||
});
|
||||
@@ -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
|
||||
|
||||
@@ -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);
|
||||
});
|
||||
});
|
||||
@@ -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,
|
||||
});
|
||||
}
|
||||
}
|
||||
@@ -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),
|
||||
};
|
||||
}
|
||||
@@ -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;
|
||||
}
|
||||
@@ -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 },
|
||||
|
||||
@@ -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);
|
||||
});
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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,
|
||||
};
|
||||
@@ -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
|
||||
|
||||
@@ -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[];
|
||||
}
|
||||
Reference in new issue
Block a user