mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-17 15:42:24 +00:00
A read-failure primitive decided from the status alone, so a 401 from a step-up or re-proof gate would have read as an ended session and sent the reader to sign-in. The code now decides first and the status is the fallback for codes it does not know. The two invitation routes answer an unknown name or e-mail with sharing.invite.no_account. Both have a second 404 with a different next step, and since every error now carries a code the clients match on it instead of on the status. The status defaults move into a module the client can import, and the contract text no longer says these arms carry no code.
327 lines
14 KiB
TypeScript
327 lines
14 KiB
TypeScript
/**
|
|
* `/api/account/grants` — the owner's side of account sharing.
|
|
*
|
|
* `GET` lists both directions at once: the grants this account has given, and
|
|
* the grants it has received. One endpoint rather than two because they are
|
|
* one question — "who can see my record, and whose can I see" — and because a
|
|
* client that has to call twice will eventually render half an answer.
|
|
*
|
|
* `POST` offers a grant to somebody already registered on this instance, at
|
|
* the level the owner chose and over the sections they chose. There is no
|
|
* route that raises a live grant: both are settled when the invitation is
|
|
* written and the only way to a wider one is a fresh invitation the delegate
|
|
* accepts again.
|
|
*
|
|
* v1.37.0 — offering MANAGE is the one act on this surface with friction on
|
|
* it. It asks for a fresh second factor when the account has one, which makes
|
|
* it cookie-only by construction: the step-up gate resolves through the
|
|
* session cookie and a token transport carries nothing that could satisfy it.
|
|
* That consequence is deliberate rather than an oversight — the native client
|
|
* cannot offer management of a health record, and the refusal below says so in
|
|
* a code rather than leaving a token caller with an authentication error on a
|
|
* request that authenticated fine.
|
|
*
|
|
* v1.39.3 — offering any level also asks for a fresh proof
|
|
* (`requireRecentProof`), and "sign out everywhere" withdraws the invitations
|
|
* nobody has accepted yet. An invitation outlives the session that sent it, so
|
|
* one offered from a stolen session would otherwise stay live after the owner
|
|
* signed everything else out.
|
|
*
|
|
* **Neither is delegable, and that is structural.** Both resolve through
|
|
* `requireAuth()` (the invitation through `requireRecentProof`, which calls
|
|
* it), which refuses outright while the caller is acting on another account. So a delegate cannot invite anybody into the record they
|
|
* were given access to, cannot widen their own grant, and cannot pass it on:
|
|
* the route does not have a re-delegation check that somebody could soften, it
|
|
* has no code path that runs under a switch at all. The grantor is then taken
|
|
* from the session on top of that — never from the body — so even if the mode
|
|
* changed, the grant it wrote would be the caller's own record.
|
|
*
|
|
* On the enumeration question, stated plainly rather than left implicit: an
|
|
* invitation to an unknown identifier is refused with "no such account", which
|
|
* tells the inviter whether that person exists here. That is a disclosure, it
|
|
* is deliberate, and the alternative is worse — an invite that silently goes
|
|
* nowhere for a mistyped username leaves the owner staring at a pending row
|
|
* that will never be accepted. The instance is a household, the caller is
|
|
* already authenticated, and the rate limit below bounds how fast the surface
|
|
* can be walked.
|
|
*/
|
|
import { NextRequest } from "next/server";
|
|
|
|
import {
|
|
apiHandler,
|
|
requireAuth,
|
|
requireFreshMfaIfEnrolled,
|
|
requireRecentProof,
|
|
MFA_STEP_UP_MAX_AGE_SECONDS,
|
|
} from "@/lib/api-handler";
|
|
import {
|
|
apiError,
|
|
apiSuccess,
|
|
getClientIp,
|
|
returnAllZodIssues,
|
|
safeJson,
|
|
} from "@/lib/api-response";
|
|
import { auditLog } from "@/lib/auth/audit";
|
|
import { prisma } from "@/lib/db";
|
|
import { getAuditLogRetentionDays } from "@/lib/jobs/audit-log-cleanup";
|
|
import { annotate } from "@/lib/logging/context";
|
|
import { checkRateLimit } from "@/lib/rate-limit";
|
|
import {
|
|
GRANT_PARTY_SELECT,
|
|
INVITE_NO_ACCOUNT_CODE,
|
|
toGrantView,
|
|
} from "@/lib/sharing/grant-view";
|
|
import { GrantError, inviteGrant } from "@/lib/sharing/grants";
|
|
import { inviteGrantSchema } from "@/lib/validations/account-sharing";
|
|
import { apiListSuccess, capRows, overfetch } from "@/lib/api/list-cap";
|
|
|
|
/**
|
|
* Ten invitations an hour, per account.
|
|
*
|
|
* Generous for the household case (nobody invites their third family member
|
|
* twice a minute) and tight enough that the account-existence disclosure above
|
|
* cannot be turned into a user-directory dump.
|
|
*/
|
|
const INVITE_LIMIT = 10;
|
|
const INVITE_WINDOW_MS = 60 * 60 * 1000;
|
|
|
|
/** How much history a list call returns per direction. */
|
|
const MAX_GRANTS_PER_DIRECTION = 100;
|
|
|
|
export const GET = apiHandler(async () => {
|
|
const { user } = await requireAuth();
|
|
annotate({ action: { name: "sharing.grants.list" } });
|
|
|
|
const [givenFound, receivedFound] = await Promise.all([
|
|
prisma.accountGrant.findMany({
|
|
where: { grantorId: user.id },
|
|
orderBy: { createdAt: "desc" },
|
|
take: overfetch(MAX_GRANTS_PER_DIRECTION),
|
|
include: { grantee: { select: GRANT_PARTY_SELECT } },
|
|
}),
|
|
prisma.accountGrant.findMany({
|
|
where: { granteeId: user.id },
|
|
orderBy: { createdAt: "desc" },
|
|
take: overfetch(MAX_GRANTS_PER_DIRECTION),
|
|
include: { grantor: { select: GRANT_PARTY_SELECT } },
|
|
}),
|
|
]);
|
|
const { rows: given, cap: givenCap } = capRows(
|
|
givenFound,
|
|
MAX_GRANTS_PER_DIRECTION,
|
|
);
|
|
const { rows: received, cap: receivedCap } = capRows(
|
|
receivedFound,
|
|
MAX_GRANTS_PER_DIRECTION,
|
|
);
|
|
|
|
// Revoked and expired rows come back too. They are the consent record — "who
|
|
// had access, from when to when, and who ended it" is the question the table
|
|
// exists to answer, and a list that quietly dropped the ended rows would
|
|
// leave the panel unable to answer it. `state` says which are live.
|
|
const now = new Date();
|
|
// One cap per direction, one signal: either list cut short is a partial
|
|
// answer.
|
|
const cap = {
|
|
truncated: givenCap.truncated || receivedCap.truncated,
|
|
limit: MAX_GRANTS_PER_DIRECTION,
|
|
};
|
|
return apiListSuccess(
|
|
{
|
|
given: given.map((g) => toGrantView(g, g.grantee, now)),
|
|
received: received.map((g) => toGrantView(g, g.grantor, now)),
|
|
// v1.37.0 — the audit window, on the payload that carries the rows.
|
|
//
|
|
// The revoke dialog tells the owner how long "who entered what" stays
|
|
// answerable after the access ends, and it can only say that with the
|
|
// number the operator configured. It used to read that number off the
|
|
// activity feed, a second and independent request, so whether the sentence
|
|
// appeared depended on which of two reads finished first — and an owner
|
|
// who clicked quickly ended a manage grant having been told less than one
|
|
// who clicked slowly, with nothing on screen to say a sentence was
|
|
// missing. Riding it here removes the race by construction: a client
|
|
// holding a grant to revoke is holding the window it must disclose.
|
|
//
|
|
// Same resolver as `/api/account/activity` and as the purge job, so the
|
|
// two surfaces cannot state different numbers.
|
|
retentionDays: getAuditLogRetentionDays(),
|
|
},
|
|
cap,
|
|
);
|
|
});
|
|
|
|
export const POST = apiHandler(async (request: NextRequest) => {
|
|
// Offering access leaves a standing way into the record in somebody else's
|
|
// hands, one that outlives the session that offered it. So a live session is
|
|
// not enough: a sign-in or re-proof within five minutes on the browser, with
|
|
// the second factor on an account that has one, or a step-up elevation on a
|
|
// token. No shipped client offers access with a token.
|
|
const auth = await requireRecentProof({ bearer: "elevation" });
|
|
const user = auth.user;
|
|
|
|
const rl = await checkRateLimit(
|
|
`sharing:invite:${user.id}`,
|
|
INVITE_LIMIT,
|
|
INVITE_WINDOW_MS,
|
|
);
|
|
if (!rl.allowed) {
|
|
return apiError("Too many invitations, try again later", 429);
|
|
}
|
|
|
|
const { data: rawBody, error: jsonError } = await safeJson(request, {
|
|
maxBytes: 8 * 1024,
|
|
});
|
|
if (jsonError) return jsonError;
|
|
|
|
const parsed = inviteGrantSchema.safeParse(rawBody);
|
|
if (!parsed.success) {
|
|
return returnAllZodIssues(parsed.error, 422, {
|
|
errorCode: "sharing.invite.invalid",
|
|
});
|
|
}
|
|
|
|
const { identifier, expiresAt, access, scope } = parsed.data;
|
|
|
|
// ── The step-up, and only on the level that needs one ───────────────────
|
|
//
|
|
// MANAGE is the level that can rewrite and delete somebody's health record,
|
|
// so offering it is gated on a fresh second factor the way account deletion
|
|
// and the encrypted export are. READ and WRITE are untouched: an owner
|
|
// sharing a reading with their partner should not have to re-prove anything.
|
|
//
|
|
// It runs BEFORE the invitee lookup on purpose. That lookup answers 404 for
|
|
// an identifier nobody carries, which is a deliberate disclosure to an
|
|
// authenticated caller — but there is no reason to hand it out on a request
|
|
// that is about to be refused anyway.
|
|
//
|
|
// The transport is checked first and separately. `requireFreshMfaIfEnrolled`
|
|
// escalates to `requireFreshMfa`, which resolves through the session cookie
|
|
// and has no Bearer fall-through; a token caller would therefore be told
|
|
// "Not authenticated" by a route that had just authenticated them, which is
|
|
// the obscure failure this branch exists to prevent. The consequence is
|
|
// deliberate and documented (the native client cannot mint MANAGE): it is
|
|
// said here in a code a client can branch on, so the app can send the person
|
|
// to a browser instead of showing them a login error.
|
|
if (access === "MANAGE") {
|
|
if (auth.authMethod !== "cookie") {
|
|
return apiError(
|
|
"Manage access can only be offered from a browser session",
|
|
403,
|
|
{ errorCode: "sharing.invite.manage_browser_only" },
|
|
);
|
|
}
|
|
await requireFreshMfaIfEnrolled(MFA_STEP_UP_MAX_AGE_SECONDS);
|
|
}
|
|
|
|
// Either column, case-insensitively — the same lookup the login form does,
|
|
// so the name somebody signs in with is the name they can be invited by.
|
|
const invitee = await prisma.user.findFirst({
|
|
where: {
|
|
OR: [
|
|
{ email: { equals: identifier, mode: "insensitive" } },
|
|
{ username: { equals: identifier, mode: "insensitive" } },
|
|
],
|
|
},
|
|
select: GRANT_PARTY_SELECT,
|
|
});
|
|
if (!invitee) {
|
|
return apiError("No account with that name or e-mail", 404, {
|
|
errorCode: INVITE_NO_ACCOUNT_CODE,
|
|
});
|
|
}
|
|
|
|
await auth.commitElevation();
|
|
|
|
try {
|
|
// `inviteGrant` decides everything about the row except the level: the
|
|
// self-grant refusal, and the one-live-grant-per-pair rule the partial
|
|
// unique index backs. Neither is re-decided here. The level travels from
|
|
// the parsed body, where the schema is the one place an omitted field
|
|
// becomes READ, and it is fixed for the life of the row — the domain
|
|
// module has no transition that raises it.
|
|
const grant = await inviteGrant({
|
|
grantorId: user.id,
|
|
granteeId: invitee.id,
|
|
access,
|
|
// The sections the owner ticked, or null for the entire record. The
|
|
// schema is where an absent field becomes null, the same way it is where
|
|
// an absent level becomes READ; the domain module takes both as required
|
|
// arguments so neither is decided twice. It re-refuses an empty set, an
|
|
// unknown key and a scope beside MANAGE underneath this line — the
|
|
// schema is the legible refusal, that one is the floor.
|
|
scope: scope ?? null,
|
|
expiresAt: expiresAt ? new Date(expiresAt) : null,
|
|
});
|
|
|
|
// The level AND the sections are on the audit row, not only in the
|
|
// response: "who was given what, and by whom" is the question this row
|
|
// exists to answer, and an entry that recorded the invitation without
|
|
// either would answer half of it. `null` is written as null rather than
|
|
// omitted, because "the entire record" is an answer and a missing key
|
|
// would read as a row from before the question was asked.
|
|
await auditLog("sharing.grant.invited", {
|
|
userId: user.id,
|
|
details: {
|
|
grantId: grant.id,
|
|
granteeId: invitee.id,
|
|
access: grant.access,
|
|
scope: scope ?? null,
|
|
},
|
|
ipAddress: getClientIp(request),
|
|
}).catch(() => {});
|
|
|
|
annotate({
|
|
action: { name: "sharing.grant.invited" },
|
|
meta: {
|
|
grant_id: grant.id,
|
|
access: grant.access,
|
|
// The count rather than the keys: a dashboard wants to know how often
|
|
// owners narrow, and which sections one household shares is not a
|
|
// thing to spread across the observability pipeline. Zero means the
|
|
// entire record.
|
|
scope_sections: scope?.length ?? 0,
|
|
expires: expiresAt !== null && expiresAt !== undefined,
|
|
},
|
|
});
|
|
|
|
return apiSuccess(toGrantView(grant, invitee), 201);
|
|
} catch (err) {
|
|
if (err instanceof GrantError) return grantErrorResponse(err);
|
|
throw err;
|
|
}
|
|
});
|
|
|
|
/**
|
|
* A refused transition, as an HTTP answer.
|
|
*
|
|
* The mapping lives here rather than inside the domain module because status
|
|
* codes are a transport concern and the state machine is not — it hands back a
|
|
* stable code and lets each consumer say what that means on its own wire.
|
|
*/
|
|
function grantErrorResponse(err: GrantError): Response {
|
|
switch (err.code) {
|
|
case "self_grant":
|
|
return apiError("An account cannot be shared with itself", 422, {
|
|
errorCode: "sharing.invite.self",
|
|
});
|
|
case "duplicate_live_grant":
|
|
return apiError("That account already has access", 409, {
|
|
errorCode: "sharing.invite.duplicate",
|
|
});
|
|
// The request shape refuses the same three cases earlier and more
|
|
// legibly (a 422 naming the `scope` field). Reaching this arm means a
|
|
// caller got past the schema with a scope the domain module will not
|
|
// store — an empty set, a key outside the vocabulary, or any scope beside
|
|
// MANAGE. Same status, its own code, so a client can tell "your sections
|
|
// are wrong" from "that is your own account".
|
|
case "invalid_scope":
|
|
return apiError("Those sections cannot be shared", 422, {
|
|
errorCode: "sharing.invite.invalid_scope",
|
|
});
|
|
default:
|
|
return apiError("Invitation refused", 422, {
|
|
errorCode: "sharing.invite.refused",
|
|
});
|
|
}
|
|
}
|