Munchable scans barcodes. When you scan something the catalogue does not have yet, you can photograph the label and add it, which is described on the licenses page and earns the contributor credit against their next bill. I wrote about the billing side of that credit earlier today.
This post is about the sentence I wrote down while building it, which ruined my afternoon:
A contributor reward keyed on client-sent values is earnable with a plain JSON POST and zero photos.
The hole
The capture flow is: the app sends a photo to an OCR endpoint, gets back the text of the label, and then posts a contribution containing that text plus some metadata, including which method produced it and how confident the extraction was.
Every single one of those fields arrives from the client. source: 'ocr-llm' is a string the client chose. ocrConfidence: 0.93 is a number the client chose. Nothing in the submission is evidence that a photo ever existed. And there is money on the other end of it.
Worse than the money: a catalogue that any JSON client can write to is a catalogue where two hand-typed submissions with similar text can agree with each other and become the truth for every later scanner.
The fix: the server signs for its own work
The endpoint that did the reading is the only party that knows the reading happened. So it issues a receipt:
export function issueOcrReceipt(
args: ReceiptText & { userId: string; confidence: number },
opts: { now?: number; env?: EnvLike } = {},
): string | null {
const secret = secretFromEnv(opts.env ?? process.env);
if (!secret) return null;
const conf = Math.max(0, Math.min(1, args.confidence)).toFixed(3);
const exp = Math.floor((opts.now ?? Date.now()) / 1000) + OCR_RECEIPT_TTL_S;
const sig = signature(secret, args.userId, textHash(args), conf, exp);
return `${VERSION}.${exp}.${conf}.${sig}`;
}
An HMAC-SHA256 over four things: the account, a hash of the text that was read, the confidence, and an expiry. The whole receipt is a string like v3.1763500000.0.930.<sig>, handed to the app, and handed back with the contribution. The contribution endpoint recomputes the text hash from the text it was given and checks the signature.
Three properties fall out of that, and each one is the answer to a question I had to think about properly.
Why bind it to the text? Because a receipt that only says "this account made an OCR call" is a licence to fabricate. One real photo would buy an unlimited number of invented submissions. Binding the signature to a hash of the words means a receipt vouches for this read and nothing else.
What happens when a contributor edits the text? The hash stops matching, so the receipt does not verify. The submission is still accepted and still saved. It is just not credited. That is the whole policy: an edit is allowed, an edit is not paid for, and nobody is called a liar.
Why is the confidence inside the signature? From the comment on the issuing function: "it travels in the receipt so the verifier cannot be handed a better number than the model gave". If confidence arrived alongside the receipt instead of inside it, the client could keep a genuine receipt and upgrade its own grade.
The confidence is clamped to 0 to 1 and formatted with toFixed(3) before it is signed, because a signature is over a string, and a float has more than one textual form. Canonicalise anything you sign.
The bug in the first version of the hash
This is the part I would most want someone else to read, because the first version looked fine and was not.
A label read is not one string. It is several: the ingredients, the "contains" statement, the precautionary "may contain" statement, and any claim printed on the pack. The original hash concatenated them with a separator.
/**
* Hash the read as a set of named, length-prefixed fields.
*
* The naming and the length are both load-bearing. Concatenating the lines with
* a separator says only that these three strings were read, not which field
* each came from, so a receipt issued for a precautionary "May contain nuts"
* also verified when the same words came back as the "Contains" line, which is
* the difference between warning a scanner and forcing them off the product,
* in whichever direction suited the sender. The length prefix closes the same
* hole from the other side: no separator can be smuggled inside a value to
* fake a field boundary.
*/
function textHash(text: ReceiptText): string {
const h = createHash('sha256');
const field = (name: string, value: string | null | undefined) => {
const v = typeof value === 'string' ? value.trim() : '';
h.update(`${name}:${Buffer.byteLength(v, 'utf8')}:`, 'utf8');
h.update(v, 'utf8');
};
field('ingredientsText', text.ingredientsText);
field('allergenStatement', text.allergenStatement);
field('precautionaryStatement', text.precautionaryStatement);
field('claimStatement', text.claimStatement);
return h.digest('hex');
}
Two separate lessons in one eight line function.
Hash fields by name, not by position in a joined string. "May contain nuts" in the precautionary field and "May contain nuts" in the contains field are different statements about a food, and a receipt that cannot tell them apart lets a sender move text between fields after the server signed it. Prefixing each value with its field name makes the hash a statement about a structure, not about a bag of strings.
Prefix every value with its byte length. Otherwise your separator is part of your attack surface: a value containing the separator can forge a field boundary. Length prefixing is the standard fix and it costs one Buffer.byteLength call.
There is a fourth field in that list that matters more than the others. A claim printed on a pack is the one kind of label text that can make a product acceptable rather than merely flagged, which means a forged claim is the most damaging thing anything in this file could permit. It would not affect the forger, who is reading the pack in their hand. It would affect everybody who scans that product afterwards. So it is hashed like the rest, and the format carries a version:
const VERSION = 'v3';
Bumping the version is what makes a hash change safe. Receipts issued by the previous deploy hash a different set of fields and simply fail to verify, instead of verifying against a hash that no longer means what it meant. The cost of the bump is one day of reward eligibility for captures in flight. The cost of not bumping it is a format confusion bug you will never be told about.
Four small things in the verifier
const m = /^v3\.(\d+)\.([01]\.\d{3})\.([A-Za-z0-9_-]+)$/.exec(receipt);
if (!m) return { ok: false, reason: 'malformed' };
Parse the whole shape at once. My first version did receipt.split('.'), which breaks immediately, because the confidence field is a decimal that contains a dot. One regex describes the format exactly and rejects everything else.
if (exp <= nowS || exp > nowS + OCR_RECEIPT_TTL_S + 60) return { ok: false, reason: 'expired' };
Check the expiry in both directions. Too old is obvious. Too far in the future is the check people skip: an expiry beyond one TTL plus a minute of clock tolerance cannot have been issued by this code, so whatever produced it should not be trusted even if the signature maths works out.
const a = Buffer.from(sig, 'utf8');
const b = Buffer.from(expected, 'utf8');
if (a.length !== b.length || !timingSafeEqual(a, b)) return { ok: false, reason: 'mismatch' };
Compare in constant time, and check the lengths first, because timingSafeEqual throws on buffers of different lengths. A truncated receipt would otherwise be a 500 instead of a refusal.
Nothing is stored. No receipts table, no nonces, no cleanup job. The signature is the state, and the only thing that outlives the request is a boolean on the saved row saying whether this capture was eligible. Stateless verification is the reason a feature like this can be 155 lines.
Failing closed, in a codebase that mostly fails open
Most of the guards in this app fail open on purpose. The rate limiter lets requests through when it cannot be reached. The inbound mail filter treats its own failure as "not spam", because a missed message costs a customer. I have written approvingly about both.
This one fails closed, and in production it refuses the whole submission rather than just the credit:
// ...and in production that has to fail CLOSED: the alternative is a catalog
// any JSON client can write to, where two hand-written POSTs with similar text
// reach consensus with no photo behind them. Development keeps working without
// the secret, with the gap said once in the logs.
The default is not a personality trait, it is arithmetic about the two failure modes. A broken spam filter costs me a second of attention per message. A broken receipt check costs the integrity of the data every user relies on, plus money. Write the asymmetry down next to the code, because the next person to touch it will be deciding whether to "simplify" your early return.
The bug that taught me to separate authentication from policy
There is a minimum confidence for paying for a read. It used to live inside the verifier, and that was wrong in a way that only showed up in the product:
* Below this the OCR read is not trustworthy enough to PAY for. It is a reward
* floor, not a save floor: a receipt verifies at any confidence, and
* /api/contribute saves the read either way. It used to be enforced inside
* `verifyOcrReceipt` as well, which meant a capture at 0.7 was refused as
* "unverified" even though the receipt was perfectly genuine, and the app told
* a user who had done everything right that their read could not be trusted.
*/
The verifier answers one question: did this server sign this text for this account, recently? That is authentication. Whether a genuine read is good enough to credit is policy, and policy belongs to the caller. Merging them produced an error message that accused an honest user of something that had not happened, which is the worst class of bug in a product people are trusting with something personal.
Now the verifier returns the confidence and declines to have an opinion about it:
export type ReceiptCheck =
| { ok: true; confidence: number }
| { ok: false; reason: 'no_secret' | 'malformed' | 'expired' | 'mismatch' };
Four distinct refusal reasons, none of which are shown to the user, all of which are the difference between a two minute diagnosis and an afternoon.
The shape to take away
If your client reports that it did some work, and that report is worth anything (money, reputation, trust in your data), have the server that did the work sign for it:
- HMAC over the account, a canonical hash of the payload, the metric you care about, and an expiry.
- Hash structured input as named, length-prefixed fields, never as a joined string.
- Put a version in the format so a change invalidates rather than confuses.
- Return the facts from the verifier and let the caller apply the policy.
- Store nothing.
The photos themselves, incidentally, are read and then discarded, which is stated on the licenses page and in the privacy policy. The receipt is the only thing that survives a capture, and it survives for a day.
Top comments (0)