Preservation Approval Stamp

1'use strict';
2
3// A provenance stamp for invoice-preservation approvals.
4//
5// The writer that imports a third-party invoice document relies on `approval.merchantOptedIn`,
6// and that field is a plain boolean on a plain object. Review demonstrated the obvious consequence:
7// a caller could hand-build `{ documentUrl, action: 'offer-preservation', merchantOptedIn: true }`
8// and import a merchant's tax documents out of their provider's archive on nobody's authority --
9// the exact counterfeit-approval path the planner/writer split was supposed to close.
10//
11// So the planner STAMPS what it approves, and the writer believes an opt-in only when the stamp
12// verifies. The stamp is a hash over the fields the decision rests on, with a module constant, so
13// it survives the plan being written to disk and read back by another process. It is not a secret
14// and does not pretend to be: anyone who reads this file can forge it. What it prevents is the
15// realistic failure -- an approval assembled by hand, or by reaching into the plan's `refused`
16// list -- rather than a determined adversary with the source in front of them.
17
18const crypto = require('node:crypto');
19
20const STAMP_VERSION = 'rp-preservation-approval:v2';
21
22// JSON-encoded (no delimiter to inject) over the URL, the action, the opt-in AND the source order
23// the approval was issued for. Review demonstrated an approval for order A re-bound to order B by
24// editing `orderId` after stamping, with the stamp still verifying: the order is part of what the
25// planner decided, so it is part of what the stamp covers.
26function stampInput(approval) {
27  const text = (value) => (value === undefined || value === null ? '' : String(value));
28  return JSON.stringify([
29    STAMP_VERSION,
30    text(approval.documentUrl),
31    text(approval.action),
32    approval.merchantOptedIn === true ? 'opted-in' : 'not-opted-in',
33    text(approval.orderId),
34  ]);
35}
36
37function computeApprovalStamp(approval) {
38  return crypto.createHash('sha256').update(stampInput(approval)).digest('hex');
39}
40
41// Returns a COPY carrying the stamp; the planner's approvals go through this.
42function stampApproval(approval) {
43  if (!approval || typeof approval !== 'object') throw new Error('stampApproval needs an approval object');
44  return { ...approval, approvalStamp: computeApprovalStamp(approval) };
45}
46
47// True only when the stamp is present and matches the fields it was computed over. Changing the
48// URL, the action, the opt-in or the order after stamping invalidates it.
49function verifyApprovalStamp(approval) {
50  if (!approval || typeof approval !== 'object' || typeof approval.approvalStamp !== 'string') return false;
51  return approval.approvalStamp === computeApprovalStamp(approval);
52}
53
54module.exports = { STAMP_VERSION, computeApprovalStamp, stampApproval, verifyApprovalStamp };