feat(documents): add a document upload token for imports from other systems

A narrow `documents:write` token, minted cookie-only at
`POST /api/tokens/documents` and accepted by the vault upload route alone.
A scoped caller draws on its own hourly bucket per token
(`DOCUMENT_UPLOAD_LIMIT_PER_HOUR`, default 120) and gets a receipt
`{ id, duplicate }` instead of the stored row.

Uploads take optional `sourceSystem` / `sourceId` fields. The source key is
unique per account across live and deleted documents, and the tombstone
purge carries it to a small ledger, so re-sending a document the owner
deleted answers 200 `deleted: true` and stores nothing. `aiRead=defer`
indexes locally and skips the summary and lab staging.

The detail sheet shows where an imported document came from; backup and
restore carry both fields; Delete All Data clears the ledger.

Refs #1038, #938
This commit is contained in:
Marc-André Bombeck committed 2026-09-25 21:48:04 +02:00
1 parent af65f01fec
commit 55a32ff7d1
45 files changed
+2261 -96

No files matched your search

@@ -149,6 +149,9 @@ describe("T3 — the mint sites are frozen", () => {
// body cannot express a scope. Reaches two write routes on the holder's
// own record and nothing else, the mint included.
"app/api/tokens/measurements/route.ts": "[MEASUREMENTS_WRITE_SCOPE]",
// Document upload from another system (#1038). Same shape as the
// measurement mint: a literal, one scope, one route that accepts it.
"app/api/tokens/documents/route.ts": "[DOCUMENTS_WRITE_SCOPE]",
// MCP, audience-bound to `/mcp`. `health:write` requires explicit consent.
"app/api/mcp/tokens/route.ts": "SCOPE_HEALTH_READ / SCOPE_HEALTH_WRITE",
"app/api/mcp/oauth/token/route.ts":
@@ -175,6 +178,7 @@ describe("T3 — the mint sites are frozen", () => {
const userFacing = [
"app/api/medications/[id]/api-endpoint/route.ts",
"app/api/tokens/measurements/route.ts",
"app/api/tokens/documents/route.ts",
"app/api/mcp/tokens/route.ts",
"app/api/mcp/oauth/token/route.ts",
];
@@ -226,7 +230,11 @@ describe("T4 — declared scopes are exported constants, never string literals",
// `scope` option, a route can widen itself without the word `requireAuth`
// appearing anywhere in it. A vocabulary that watched only the first form
// would have gone on passing while the surface it describes grew.
const DECLARED_SCOPES = ["FHIR_READ_SCOPE", "MEASUREMENTS_WRITE_SCOPE"];
const DECLARED_SCOPES = [
"DOCUMENTS_WRITE_SCOPE",
"FHIR_READ_SCOPE",
"MEASUREMENTS_WRITE_SCOPE",
];
const used = new Set<string>();
for (const rel of sourceFiles()) {
const src = read(rel);
@@ -245,6 +253,24 @@ describe("T4 — declared scopes are exported constants, never string literals",
});
});
describe("T4b — `documents:write` opens exactly one door", () => {
it("only the vault upload route declares the scope", () => {
// The scope admits a narrow token wherever it is named, so the set of
// files naming it IS its reach. The upload, and nothing else: not the
// list or detail beside it, not the original or thumbnail, not bulk, not
// the AI legs. A second route here is a widening and belongs in review.
const declaring = filesMatching(
/requireAuth\(\s*DOCUMENTS_WRITE_SCOPE\s*\)|requireRecordAuth\([^)]*\bscope:\s*DOCUMENTS_WRITE_SCOPE\b/,
);
expect(declaring).toEqual(["app/api/documents/inbound/route.ts"]);
// And within that file, once: the GET beside the POST must not name it.
const src = read("app/api/documents/inbound/route.ts");
expect(
src.match(/requireAuth\(\s*DOCUMENTS_WRITE_SCOPE\s*\)/g),
).toHaveLength(1);
});
});
describe("T5 — a delegable route naming a Bearer scope is frozen", () => {
/**
* Routes that admit a narrow token on a DELEGABLE surface, and the scope each