fix(ingest): hold the stability floor for identities no request schema sees

The dedup key on the medication intake surfaces is not only `externalId`.
`MedicationIntakeEvent.idempotency_key` is a `@unique` column persisted
with the dose row forever, with no TTL and no sweep, matched by plain
equality on the per-medication POST, the bulk drain and the external
ingest bridge. That makes it an identity, not a replay token, and it
carries the same failure mode: a key that rotates per client launch never
matches its own earlier post, so every retry logs the dose again. The
blank case is sharper still — the column is unique table-wide, so an
empty key resolves to whichever unrelated row stored it first. Refuse
both shapes at the schema on the single-entry paths and per entry on the
bulk drain.

The MCP write path hashes a host-supplied key into the `externalId` half
of its dedup key, so the shape is laundered before anything downstream
could see it and the check has to run on the input. That closes a live
one: every tool handler falls back to `""` when the host omits the
argument, and `""` digests to a constant, so each keyless write after the
first reported `already_logged` and was silently dropped.

The HTTP `Idempotency-Key` header stays out, and now says why in the
guard: `IdempotencyKey.expiresAt` bounds it and the cleanup job sweeps
it, so it is a windowed replay token and rotation is its design.

Extend the structural guard with a provenance rule for identities that
never pass a Zod request schema — a spreadsheet column, an MCP tool
argument. Inside the import and MCP trees, a module handling an identity
must apply the floor itself or import a module that does. That is a real
chain rather than a list of known offenders: a new importer that mints an
`externalId` from file input and imports nothing checked fails it, with
no allowlist to escape into.
This commit is contained in:
Marc-André Bombeck committed 2026-07-25 18:07:13 +02:00
1 parent 6e4bcffadf
commit 15b5f6f92f
19 files changed
+1574 -43

No files matched your search

+70 -18
View File
@@ -96,19 +96,43 @@ export function isStableExternalId(value: string): boolean {
return classifyExternalId(value) === null;
}
const SHAPE_MESSAGES: Record<UnstableExternalIdShape, string> = {
blank: "external identifier must not be empty",
pointer_address:
"external identifier must be stable across app restarts; received a memory address (0x…), which is a new value on every launch and mints a duplicate record on every sync",
object_description:
"external identifier must be stable across app restarts; received an object description (<Class: 0x…>), which embeds a memory address and is a new value on every launch — serialise the identity itself, not the object's description",
};
/**
* How the offending field is named back to the caller. The rule is about
* the VALUE, so it applies to every client-supplied string this system
* later matches on as an identity — not only `externalId`.
*/
export const EXTERNAL_ID_LABEL = "external identifier";
export const IDEMPOTENCY_KEY_LABEL = "idempotency key";
/** The 422 message a client developer reads. Names the shape received. */
export function unstableExternalIdMessage(
shape: UnstableExternalIdShape,
label: string = EXTERNAL_ID_LABEL,
): string {
return SHAPE_MESSAGES[shape];
switch (shape) {
case "blank":
return `${label} must not be empty`;
case "pointer_address":
return `${label} must be stable across app restarts; received a memory address (0x…), which is a new value on every launch and mints a duplicate record on every sync`;
case "object_description":
return `${label} must be stable across app restarts; received an object description (<Class: 0x…>), which embeds a memory address and is a new value on every launch — serialise the identity itself, not the object's description`;
}
}
function assertStableIdentityField(
raw: unknown,
ctx: z.RefinementCtx,
field: string,
label: string,
): void {
if (typeof raw !== "string") return;
const shape = classifyExternalId(raw);
if (shape === null) return;
ctx.addIssue({
code: "custom",
path: [field],
message: unstableExternalIdMessage(shape, label),
});
}
/**
@@ -127,15 +151,42 @@ export function assertStableExternalId(
value: { externalId?: string | null },
ctx: z.RefinementCtx,
): void {
const raw = value.externalId;
if (typeof raw !== "string") return;
const shape = classifyExternalId(raw);
if (shape === null) return;
ctx.addIssue({
code: "custom",
path: ["externalId"],
message: unstableExternalIdMessage(shape),
});
assertStableIdentityField(
value.externalId,
ctx,
"externalId",
EXTERNAL_ID_LABEL,
);
}
/**
* The same floor for a client-supplied `idempotencyKey`.
*
* The HTTP `Idempotency-Key` header is a replay token inside a TTL and is
* deliberately out of scope — `IdempotencyKey.expiresAt` bounds it and a
* cron sweeps it. `MedicationIntakeEvent.idempotency_key` is NOT that: it
* is a `@unique` column persisted with the dose row forever, with no TTL
* and no sweep, matched by plain equality on the per-medication intake
* POST, the bulk intake ingest and the external ingest surface. That makes
* it an identity, and it carries the same failure mode — a value that
* rotates per client launch never matches its own earlier row, so every
* re-sync logs the dose again.
*
* The blank arm matters more here than anywhere else: the column is
* `@unique` across the table, so a second row carrying "" cannot exist,
* and an empty key would otherwise resolve to whichever unrelated row got
* there first.
*/
export function assertStableIdempotencyKey(
value: { idempotencyKey?: string | null },
ctx: z.RefinementCtx,
): void {
assertStableIdentityField(
value.idempotencyKey,
ctx,
"idempotencyKey",
IDEMPOTENCY_KEY_LABEL,
);
}
/**
@@ -146,9 +197,10 @@ export function assertStableExternalId(
*/
export function unstableExternalIdShape(
body: unknown,
field: "externalId" | "idempotencyKey" = "externalId",
): UnstableExternalIdShape | null {
if (typeof body !== "object" || body === null) return null;
const raw = (body as { externalId?: unknown }).externalId;
const raw = (body as Record<string, unknown>)[field];
if (typeof raw !== "string") return null;
return classifyExternalId(raw);
}
+18 -6
View File
@@ -1,6 +1,7 @@
import { z } from "zod/v4";
import { boundedTakenAtSchema, injectionSiteEnum } from "./base";
import { assertStableIdempotencyKey } from "@/lib/validations/external-id";
export const intakeSchema = z
.object({
@@ -82,18 +83,29 @@ export const intakeSchema = z
"Dose actually consumed for THIS intake when it deviates from (or documents) the medication's configured dose, e.g. a half tablet or a titration step. Free text, max 50 characters. Omit to record the take under the medication's configured dose.",
),
})
// `MedicationIntakeEvent.idempotency_key` is a `@unique` column persisted
// with the dose row forever and matched by equality — an identity, not a
// windowed replay token. A key that rotates per client launch never
// matches its own earlier row, so every re-sync logs the dose again.
.superRefine(assertStableIdempotencyKey)
.meta({
id: "MedicationIntakeRequest",
description:
"Per-medication intake log body. Idempotent via `idempotencyKey`; the server also dedupes by a 60-second sliding window when the key is absent. Non-skipped intakes auto-decrement pen inventory (best-effort), refresh the per-day compliance rollup, and — for one-shot medications — flip `active` to false. The optional `injectionSite` is persisted only for an INJECTION medication with site-tracking enabled and is validated against the medication's effective allowed set (422 on a disallowed value).",
});
export const externalIntakeSchema = z.object({
medicationName: z.string().min(1).max(200),
// v1.16.9 — same plausibility bounds as the interactive create paths.
takenAt: boundedTakenAtSchema.optional(),
idempotencyKey: z.string().max(128),
});
export const externalIntakeSchema = z
.object({
medicationName: z.string().min(1).max(200),
// v1.16.9 — same plausibility bounds as the interactive create paths.
takenAt: boundedTakenAtSchema.optional(),
idempotencyKey: z.string().max(128),
})
// Same identity floor as the interactive twin. The blank arm carries real
// weight on this surface: the column is `@unique` table-wide, so an empty
// key resolves to whichever unrelated row happened to store "" first
// instead of to this caller's own earlier post.
.superRefine(assertStableIdempotencyKey);
export const listIntakeEventsSchema = z.object({
limit: z.coerce.number().int().min(1).max(500).optional().default(25),