Files
HealthLog/src/__tests__/acting-account-boundary-guard.test.ts
T
Marc-André Bombeck c7960d726d Scope the idempotency replay cell to the record a request claims
A delegate retrying with one `Idempotency-Key` across two people's records met
itself in one cell. The cache tuple was `(caller, key, method, path)`, so the
second record's request replayed the first record's cached 201: the handler
never ran, no row was written for the second person, and the caller was told it
had been — with the other person's id in the body. Nothing errored and nothing
logged a conflict, and five of the write verbs about to become delegable are
wrapped here.

Fold the claimed record into the `key` component, centrally, once. Not into
`userId`: that column is a foreign key to `users` with a cascade behind it and
cannot hold a composite. It keeps naming the caller, which is what makes two
delegates on one record two cells for free. The separator is a byte the key
validator refuses, so a caller cannot hand-craft a key into a cell belonging to
a request they are not making.

A request with no acting account keys byte-for-byte as it did before, so a
client that never heard of sharing cannot be affected.

Accepted and pinned by test: the fold uses the CLAIM, before the grant check,
so within the 24h window a delegate whose access has ended can still replay a
key they had already completed. They receive bytes they already had, nothing
new is written, and a fresh key from them is refused because that request
reaches the handler.

Both frozen surfaces move in this diff. The claim reader gains a guard leg
freezing its consumers, since an unchecked claim is exactly the value a future
caller must not mistake for permission.
2026-08-03 10:18:27 +02:00

286 lines
12 KiB
TypeScript

/**
* Structural guards on the acting-account boundary.
*
* The behavioural tests in `src/lib/__tests__/acting-account-resolver.test.ts`
* prove what today's code does. These prove what tomorrow's may not do, and
* they exist because the boundary has one shape that keeps it safe: the acting
* account is a value ONE function is allowed to act on, and the helpers that
* decide role and step-up never see it.
*
* Tripwires, not proofs. They cannot show the resolver is correct — only that
* the boundary has not moved without somebody editing this file. Every leg
* below asserts a non-zero match count first, because a guard whose matcher
* finds nothing reports success, and this repository has shipped several of
* those.
*/
import { describe, it, expect } from "vitest";
import { readFileSync } from "node:fs";
import { join } from "node:path";
import { walkSourceFiles } from "./helpers/source-files";
const SRC = join(process.cwd(), "src");
function sourceFiles(): string[] {
return walkSourceFiles(SRC, { floor: 3000 })
.filter((p) => !p.startsWith("generated/"))
.filter((p) => !p.includes("__tests__"))
.filter((p) => !p.endsWith(".test.ts") && !p.endsWith(".test.tsx"))
.sort();
}
function read(rel: string): string {
return readFileSync(join(SRC, rel), "utf8");
}
function filesMatching(re: RegExp): string[] {
return sourceFiles().filter((rel) => re.test(read(rel)));
}
/** The source text of a top-level exported function, braces included. */
function functionBody(src: string, name: string): string {
const start = src.indexOf(`export async function ${name}(`);
if (start === -1) return "";
const open = src.indexOf("{", src.indexOf(")", start));
let depth = 0;
for (let i = open; i < src.length; i++) {
if (src[i] === "{") depth++;
else if (src[i] === "}") {
depth -= 1;
if (depth === 0) return src.slice(open, i + 1);
}
}
return "";
}
describe("the acting-account carrier is read in one place", () => {
/**
* Files allowed to touch `Session.actingAsUserId`.
*
* The column is a selector — it names an account, it does not authorise one.
* Anything that reads it and acts on the value without going through the
* resolver has invented a second answer to "whose record is this", and the
* copy that drifts is always the one nobody reads.
*
* Later items in this feature will extend this list, and that is the point:
* the switch endpoint (which writes it) and revocation cleanup (which clears
* it) arrive as a visible diff here rather than as a quiet new reader.
*
* The matcher reads source text and does not exempt comments, so a file that
* merely NAMES the column in prose trips it. Left that way deliberately: a
* guard over an authorization carrier that shouts at a mention is the right
* direction to be wrong in.
*/
const CARRIER_ALLOWLIST = [
// Projects it off the session row it already loaded.
"lib/auth/session.ts",
// Reads it. The one statement of "what does this request say it is acting
// as", for both transports and for every caller that has to ask.
"lib/auth/acting-carrier.ts",
// The resolver. The only thing that acts on the value.
"lib/api-handler.ts",
// v1.36.0 — the only thing that WRITES it: the switch endpoint sets it
// through here, ending a grant clears it through here. The routes
// themselves call these two functions and never name the column, which is
// what keeps this list from growing one entry per surface.
"lib/sharing/acting-session.ts",
// v1.36.0 — the only thing that PUBLISHES it, and it publishes the stamp
// only after re-deciding it. The account payload has to say which record
// the browser is inside so the banner can name a person, but the value it
// prints is not the column: an entry reaches `active` solely by surviving
// the same live-grant pass that builds the switcher list, so a stamp left
// behind by a lapsed grant reads as "not switched" — the same answer the
// resolver will independently give the next delegated request. Takes the
// whole auth context for exactly this reason: had it taken the id, the
// route would name the column too, and the list would grow per surface.
"lib/sharing/account-access.ts",
].sort();
it("no other file reads or writes the carrier column", () => {
const readers = filesMatching(/actingAsUserId|acting_as_user_id/);
// Non-zero proof: an emptied allowlist must fail rather than agree with an
// emptied match set.
expect(readers.length).toBeGreaterThan(0);
expect(readers).toEqual(CARRIER_ALLOWLIST);
});
it("the selector header is named in one place", () => {
// A route that read the header itself would be deciding an authorisation
// question the resolver exists to answer once.
//
// The OpenAPI table is the one other file allowed to say the name, and it
// is not a reader: it publishes the header to the clients that have to
// send it. Listed explicitly rather than exempted by pattern, so a route
// that starts parsing the header cannot hide behind a rule about which
// directories are documentation.
const namers = filesMatching(/x-healthlog-account/i);
expect(namers.length).toBeGreaterThan(0);
expect(namers).toEqual([
"lib/auth/acting-carrier.ts",
"lib/openapi/routes/account-sharing.ts",
]);
});
/**
* Who may ask "which record does this request claim" without an auth
* context in hand.
*
* `readClaimedActingAccount()` answers before any grant check has run, so a
* caller that treats its answer as permission has skipped the only thing
* that grants any. Exactly one caller exists, beside the file that declares
* it: the idempotency wrapper, which uses the claim to pick a cache cell and
* leaves the check to the handler it wraps. Everything else that needs the
* acting account has an auth context by then and goes through
* `requireRecordAuth`, which checks a live grant before returning. A second
* caller here is a design question, not a patch.
*/
it("the unchecked claim has exactly two consumers", () => {
const consumers = filesMatching(/readClaimedActingAccount/);
expect(consumers.length).toBeGreaterThan(0);
expect(consumers).toEqual([
"lib/auth/acting-carrier.ts",
"lib/idempotency.ts",
]);
});
});
describe("the cookie-only helpers cannot see the acting account", () => {
/**
* `requireAdmin`, `requireCookieAuth` and `requireFreshMfa` are safe under a
* switch for one reason: they resolve through `getSession()`, which answers
* who is CALLING, and they never consult the carrier. That is the property
* that keeps role checks and step-up gates structurally out of a delegate's
* reach, and it is one careless line away from being untrue.
*/
const COOKIE_ONLY = ["requireAdmin", "requireCookieAuth", "requireFreshMfa"];
it.each(COOKIE_ONLY)("%s resolves the actor and nothing else", (name) => {
const body = functionBody(read("lib/api-handler.ts"), name);
// Non-zero proof, twice over: the slice found a function, and the slice is
// the function it claims to be. A renamed helper must fail here rather
// than silently assert against an empty string.
expect(body.length).toBeGreaterThan(0);
expect(body).toContain("getSession()");
expect(body).not.toContain("actingAsUserId");
expect(body).not.toContain("requireRecordAuth");
expect(body).not.toContain("readActingCarrier");
});
it("substitutes a data-scope user in exactly one function", () => {
const src = read("lib/api-handler.ts");
const record = functionBody(src, "requireRecordAuth");
expect(record).toContain("readActingCarrier");
// `readActingCarrier` is what turns a request into "acting as somebody
// else". Two callers: the bare path, which refuses on it, and the record
// path, which acts on it. A third would be a mode nobody declared.
const callers = (src.match(/await readActingCarrier\(/g) ?? []).length;
expect(callers).toBe(2);
});
});
describe("grant management is not delegable by construction", () => {
/**
* A delegate must never grant, widen, or transfer access. The way that is
* true here is not a re-delegation check inside the handlers — a check is a
* line somebody can move — but the mode the handlers resolve in: bare
* `requireAuth()` refuses outright while a switch is active, so there is no
* code path through these routes that runs as somebody else at all.
*
* The switch endpoint is the deliberate exception and lives elsewhere: it is
* an actor surface because it is the way back out of a switch, and it grants
* nothing.
*/
const GRANT_ROUTES = [
"app/api/account/grants/route.ts",
"app/api/account/grants/[id]/route.ts",
"app/api/account/grants/[id]/accept/route.ts",
"app/api/account/grants/[id]/renounce/route.ts",
];
it("every grant route exists and resolves through bare requireAuth", () => {
// Non-zero proof: a renamed or moved route must fail here rather than
// leave the loop below with nothing to check.
const found = sourceFiles().filter((p) => GRANT_ROUTES.includes(p));
expect(found.sort()).toEqual([...GRANT_ROUTES].sort());
for (const rel of GRANT_ROUTES) {
const src = read(rel);
expect(src, `${rel} must resolve auth`).toMatch(/await requireAuth\(\)/);
expect(src, `${rel} must not honour a switch`).not.toContain(
"requireRecordAuth",
);
expect(src, `${rel} must not declare an actor surface`).not.toContain(
"requireActorAuth",
);
}
});
it("no grant route takes a party to the grant from the request body", () => {
// Both ends of a grant come from the session and from the row. A body
// field naming either would be the caller deciding an authorisation
// question, which is the one thing no route here is allowed to do.
for (const rel of GRANT_ROUTES) {
const src = read(rel);
expect(src).not.toMatch(/parsed\.data\.(grantorId|granteeId|userId)/);
}
});
});
describe("ending a grant and clearing the switch are one act", () => {
/**
* Two statements of the same fact. Split apart, a revocation that stamped
* the row but not the sessions leaves a delegate's browser inside a record
* it can no longer read — every request refused, the banner still naming the
* owner, nothing on screen able to explain it.
*
* The behavioural half of this is
* `tests/integration/sharing-lifecycle.test.ts`, which asserts the session
* row after a revoke. This half holds the atomicity, which no test can
* observe from outside.
*/
function privateFunctionBody(src: string, name: string): string {
const start = src.indexOf(`async function ${name}(`);
if (start === -1) return "";
const open = src.indexOf("{", src.indexOf(")", start));
let depth = 0;
for (let i = open; i < src.length; i++) {
if (src[i] === "{") depth++;
else if (src[i] === "}") {
depth -= 1;
if (depth === 0) return src.slice(open, i + 1);
}
}
return "";
}
it("runs the transition and the cleanup in one transaction", () => {
const body = privateFunctionBody(
read("lib/sharing/grants.ts"),
"endAndClear",
);
// Non-zero proof: a renamed helper fails here rather than asserting
// against an empty string, which would pass every `not.toContain` below
// and most of what a reader assumes this test covers.
expect(body.length).toBeGreaterThan(0);
expect(body).toContain("$transaction");
expect(body).toContain("clearActingSessions");
});
it("routes an ending through the cleanup, never through the bare transition", () => {
for (const rel of [
"app/api/account/grants/[id]/route.ts",
"app/api/account/grants/[id]/renounce/route.ts",
]) {
const src = read(rel);
expect(src).toMatch(/(revoke|renounce)GrantAndClearSwitch/);
// The bare transitions leave sessions behind on purpose — they exist so
// they can run inside somebody else's transaction. A route reaching for
// one has skipped the cleanup.
expect(src).not.toMatch(/\b(revokeGrant|renounceGrant)\(/);
}
});
});