Code tutorials

'use strict';
// One payment attempt as a small state machine.
// The provider is a fake that lives in memory. No money, no network, no real checkout.
//
// States of the saved record: awaiting -> confirmed | failed | held
// Everything the page must remember lives in `store`, which stands for storage
// that survives a reload. Nothing important is kept in a plain variable.

const usd = (cents) => 'USD ' + (cents / 100).toFixed(2);

function fakeProvider(answers) {
  const attempts = new Map(); // attempt id -> amount in cents
  let polls = 0;
  return {
    create(id, cents) { if (!attempts.has(id)) attempts.set(id, cents); },
    status(id) {
      if (!attempts.has(id)) return 'none';
      return answers[Math.min(polls++, answers.length - 1)];
    },
    attemptCount: () => attempts.size,
  };
}

// What runs every time the page loads or reloads.
function loadPage({ provider, store, limitCents }) {
  return {
    pay(cents) {
      if (store.stop) return 'refused: stopped';                 // the stop is read first
      const rec = store.record;
      if (rec && (rec.state === 'awaiting' || rec.state === 'held')) {
        return 'refused: already ' + rec.state;                  // a reload never starts a second attempt
      }
      if (store.confirmed + cents > limitCents) return 'refused: limit ' + usd(limitCents);
      const id = 'attempt-' + (++store.seq);
      store.record = { id, cents, state: 'awaiting' };
      provider.create(id, cents);
      return 'started ' + usd(cents);
    },
    poll() {
      const rec = store.record;
      if (!rec || rec.state !== 'awaiting') return rec ? rec.state : 'idle';
      const answer = provider.status(rec.id);
      if (answer === 'pending') return 'pending';
      if (answer === 'confirmed') { rec.state = 'confirmed'; store.confirmed += rec.cents; }
      else if (answer === 'failed') rec.state = 'failed';
      else rec.state = 'held';                                   // any other answer is unknown: hold
      return rec.state;
    },
    resolveHeld(didHappen) {                                     // only a person calls this, after checking
      const rec = store.record;
      if (!rec || rec.state !== 'held') return false;
      rec.state = didHappen ? 'confirmed' : 'failed';
      if (didHappen) store.confirmed += rec.cents;
      return true;
    },
  };
}

const newStore = () => ({ record: null, confirmed: 0, seq: 0, stop: false });
const say = (label, value) => console.log(label.padEnd(24) + ': ' + value);

// The fault: a page that starts a fresh attempt every time it loads.
{
  const provider = fakeProvider(['pending']);
  let seq = 0;
  const naiveLoad = () => provider.create('naive-' + (++seq), 500);
  naiveLoad();   // first load
  naiveLoad();   // the bank page returns and the page reloads
  say('naive page, 1 click', provider.attemptCount() + ' attempts at the provider');
}

// The fix: the record is saved, and a reload resumes waiting.
{
  const provider = fakeProvider(['pending', 'confirmed']);
  const store = newStore();
  let page = loadPage({ provider, store, limitCents: 800 });
  say('pay USD 5.00', page.pay(500));
  page = loadPage({ provider, store, limitCents: 800 });           // the reload
  say('pay again after reload', page.pay(500));
  say('attempts at provider', provider.attemptCount());
  say('poll 1', page.poll());
  say('poll 2', page.poll());
  say('confirmed so far', usd(store.confirmed));
  say('pay USD 5.00 again', page.pay(500));                      // 5 + 5 would pass the limit of 8
  store.stop = true;
  say('pay USD 1.00 after stop', page.pay(100));
}

// An unknown answer is never repeated. It waits for a person.
{
  const provider = fakeProvider(['timeout']);
  const store = newStore();
  const page = loadPage({ provider, store, limitCents: 800 });
  page.pay(300);
  say('poll, odd answer', page.poll());
  say('pay while held', page.pay(300));
  page.resolveHeld(false);                                       // the person checked: nothing was taken
  say('after checking', store.record.state + ', counted ' + usd(store.confirmed));
}

"""The server decides the price, the total and who is who. The client only asks.

Everything here is in memory and fake: there is no payment provider, no network and no real key.
Amounts are whole cents so that no rounding surprise can hide in them.
"""
import hashlib
import hmac

CATALOGUE = {"small-gift": 500, "medium-gift": 1000}   # the only place a price exists
LIMIT_CENTS = 1500                                       # set by the person who pays, in advance
DEMO_KEY = b"made-up-demo-key"                         # a real key would never sit in source


def usd(cents):
    return "USD %d.%02d" % divmod(cents, 100)


def pseudonym(identifier):
    """A keyed hash: the ledger can match a person to a past send without storing who they are."""
    return hmac.new(DEMO_KEY, identifier.encode(), hashlib.sha256).hexdigest()[:12]


class Ledger:
    def __init__(self):
        self.confirmed = {}   # pseudonym -> cents the provider confirmed
        self.pending = {}     # order id -> (pseudonym, cents) still waiting
        self.next_id = 1

    def counted(self, who):
        """What counts against the limit: confirmed money plus every order still in doubt."""
        waiting = sum(c for p, c in self.pending.values() if p == who)
        return self.confirmed.get(who, 0) + waiting

    def order(self, identifier, request):
        who = pseudonym(identifier)
        item = request.get("item")
        if item not in CATALOGUE:
            return "refused: unknown item"
        price = CATALOGUE[item]                       # the client's own "amount" field is never read
        if self.counted(who) + price > LIMIT_CENTS:
            return "refused: limit %s" % usd(LIMIT_CENTS)
        order_id = "order-%d" % self.next_id
        self.next_id += 1
        self.pending[order_id] = (who, price)
        return "%s created for %s" % (order_id, usd(price))

    def provider_event(self, order_id, status, received_cents):
        """The fake provider reports what really happened. Only this event can add to the total."""
        if order_id not in self.pending:
            return "ignored: unknown order"
        who, expected = self.pending[order_id]
        if status != "paid":
            del self.pending[order_id]
            return "%s closed, nothing counted" % order_id
        if received_cents != expected:
            return "%s held: expected %s, provider says %s" % (order_id, usd(expected), usd(received_cents))
        del self.pending[order_id]
        self.confirmed[who] = self.confirmed.get(who, 0) + received_cents
        return "%s counted %s" % (order_id, usd(received_cents))


ledger = Ledger()
who = "person@example.invalid"

print("client claims 1 cent  :", ledger.order(who, {"item": "small-gift", "amount": 1}))
print("unknown item          :", ledger.order(who, {"item": "gold-gift"}))
print("count before the event:", usd(ledger.counted(pseudonym(who))))
print("provider, wrong sum   :", ledger.provider_event("order-1", "paid", 100))
print("provider, right sum   :", ledger.provider_event("order-1", "paid", 500))
print("order 2               :", ledger.order(who, {"item": "medium-gift"}))
print("order 3 over the limit  :", ledger.order(who, {"item": "medium-gift"}))
print("provider, cancelled   :", ledger.provider_event("order-2", "cancelled", 0))
print("order 3 after cancel  :", ledger.order(who, {"item": "medium-gift"}))
print("confirmed total       :", usd(ledger.confirmed[pseudonym(who)]))
print("raw identifier stored :", any(who in str(k) for k in ledger.confirmed))
print("same person, same tag :", pseudonym(who) == pseudonym("person@example.invalid"))

'use strict';
// A draw whose odds match the table shown to the player, with fictional chips only.
// Three habits: check the table, draw without bias, and measure the draw against the table.
const { webcrypto } = require('node:crypto');

const SHOWN = [
  ['5 chips', 25], ['10 chips', 25], ['20 chips', 20], ['50 chips', 12],
  ['100 chips', 9], ['250 chips', 6], ['1000 chips', 3],
];
const TICKETS = 10000; // one ticket is 0.01 of a percentage point

function checkTable(table) {
  const total = table.reduce((sum, [, percent]) => sum + percent, 0);
  if (total !== 100) throw new Error('table adds up to ' + total + ', not 100');
  return true;
}

// Habit 1. Mapping a random number with % gives some outcomes one more chance than others.
function showModuloBias() {
  const counts = new Array(10).fill(0);
  for (let value = 0; value < 256; value++) counts[value % 10]++;
  console.log('bytes 0..255 mapped with % 10 land on 0..9 this many times:');
  console.log('  ' + counts.join(' '));
}

// Habit 2. Throw away the top of the range that would favour small tickets.
const LIMIT = 2 ** 32 - (2 ** 32 % TICKETS);
function randomTicket() {
  const buffer = new Uint32Array(1);
  do { webcrypto.getRandomValues(buffer); } while (buffer[0] >= LIMIT);
  return buffer[0] % TICKETS;
}

function pickByTable(table) {
  return (ticket) => {
    let edge = 0;
    for (const [name, percent] of table) {
      edge += percent * 100;
      if (ticket < edge) return name;
    }
    throw new Error('ticket out of range');
  };
}

// Habit 3. Run the real draw many times and compare each share with the shown table.
function matchesShown(pick, shown, rounds) {
  const counts = new Map(shown.map(([name]) => [name, 0]));
  for (let i = 0; i < rounds; i++) {
    const name = pick(randomTicket());
    counts.set(name, counts.get(name) + 1);
  }
  return shown.every(([name, percent]) => Math.abs(counts.get(name) / rounds - percent / 100) < 0.005);
}

checkTable(SHOWN);
console.log('shown table adds up to 100:', true);
try {
  checkTable([['5 chips', 50], ['10 chips', 49]]);
} catch (error) {
  console.log('wrong table refused:', error.message);
}

showModuloBias();

const draw = pickByTable(SHOWN);
const edges = [0, 2499, 2500, 4999, 5000, 7000, 8200, 9100, 9700, 9999];
console.log('edge tickets give:', edges.map(draw).join(' | '));

const ROUNDS = 200000;
console.log('draw matches the shown odds over ' + ROUNDS + ' rounds:', matchesShown(draw, SHOWN, ROUNDS));

// A build step that resets every weight to an equal share. The source was fine, the shipped draw is not.
const drawEqual = (ticket) => SHOWN[Math.floor(ticket / (TICKETS / SHOWN.length))][0];
console.log('equal-weights build matches the shown odds:', matchesShown(drawEqual, SHOWN, ROUNDS));

"""Check the file that ships, not the file you wrote.

Three small files are built in a temporary folder, so nothing outside it is touched.
The checker compares the shipped file with the one that was tested, the odds with the table shown
to the player, the amount shown with the amount charged, and looks for a leftover test switch.
"""
import hashlib
import json
import pathlib
import tempfile

TESTED = {
    "version": "1.4",
    "odds": {"5 chips": 25, "10 chips": 25, "20 chips": 20, "50 chips": 12,
             "100 chips": 9, "250 chips": 6, "1000 chips": 3},
    "options": [{"label": "small", "shown_cents": 500, "charged_cents": 500},
                {"label": "large", "shown_cents": 1000, "charged_cents": 1000}],
    "switches": {"skip_payment": False},
}

# What three different builds might produce from that source.
BUILDS = {"build-a.json": json.loads(json.dumps(TESTED))}

reset = json.loads(json.dumps(TESTED))                 # a build step that flattened the odds
reset["odds"] = {name: 14 for name in reset["odds"]}
BUILDS["build-b.json"] = reset

leftover = json.loads(json.dumps(TESTED))              # a wrong amount and a test switch left on
leftover["options"][1]["charged_cents"] = 100
leftover["switches"]["skip_payment"] = True
BUILDS["build-c.json"] = leftover


def sha256(path):
    return hashlib.sha256(path.read_bytes()).hexdigest()


def usd(cents):
    return "USD %d.%02d" % divmod(cents, 100)


def check(shipped_path, tested_hash, shown_odds):
    problems = []
    if sha256(shipped_path) == tested_hash:
        return problems                                # the same bytes as the tested file: nothing else to prove
    data = json.loads(shipped_path.read_text(encoding="utf-8"))
    if data["odds"] != shown_odds:
        problems.append("odds differ from the table shown")
    if sum(data["odds"].values()) != 100:
        problems.append("odds add up to %d, not 100" % sum(data["odds"].values()))
    for option in data["options"]:
        if option["shown_cents"] != option["charged_cents"]:
            problems.append("%s shows %s but charges %s" % (
                option["label"], usd(option["shown_cents"]), usd(option["charged_cents"])))
    for name, value in data["switches"].items():
        if value:
            problems.append("test switch %s is on" % name)
    return problems


with tempfile.TemporaryDirectory() as folder:
    root = pathlib.Path(folder)
    for name, content in BUILDS.items():
        (root / name).write_text(json.dumps(content, indent=1, sort_keys=True), encoding="utf-8")
    tested_hash = sha256(root / "build-a.json")
    print("tested file hash starts with", tested_hash[:12])
    for name in BUILDS:
        path = root / name
        found = check(path, tested_hash, TESTED["odds"])
        print("%s hash %s" % (name, sha256(path)[:12]))
        if found:
            print("  REFUSED")
            for line in found:
                print("  - " + line)
        else:
            print("  accepted")

'use strict';
// Clean an image export and then check the result, using a tiny PNG-shaped file built in memory.
// The rule: name what a plain picture needs, drop every other chunk, re-read the result,
// and refuse the export if anything else is still there or if the file does not parse.

const SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
const KEEP = new Set(['IHDR', 'PLTE', 'tRNS', 'IDAT', 'IEND']);

const TABLE = Array.from({ length: 256 }, (_, n) => {
  let c = n;
  for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
  return c >>> 0;
});

function crc32(buffer) {
  let c = 0xffffffff;
  for (const byte of buffer) c = TABLE[(c ^ byte) & 255] ^ (c >>> 8);
  return (c ^ 0xffffffff) >>> 0;
}

function makeChunk(type, data) {
  const body = Buffer.concat([Buffer.from(type, 'latin1'), data]);
  const head = Buffer.alloc(4);
  head.writeUInt32BE(data.length);
  const tail = Buffer.alloc(4);
  tail.writeUInt32BE(crc32(body));
  return Buffer.concat([head, body, tail]);
}

function readChunks(buffer) {
  if (buffer.length < 12 || !buffer.subarray(0, 8).equals(SIGNATURE)) throw new Error('not a PNG file');
  const chunks = [];
  let at = 8;
  while (at < buffer.length) {
    if (at + 12 > buffer.length) throw new Error('truncated chunk');
    const length = buffer.readUInt32BE(at);
    const end = at + 12 + length;
    if (end > buffer.length) throw new Error('truncated chunk');
    const type = buffer.toString('latin1', at + 4, at + 8);
    if (crc32(buffer.subarray(at + 4, at + 8 + length)) !== buffer.readUInt32BE(end - 4)) {
      throw new Error('bad checksum in ' + type);
    }
    chunks.push({ type, start: at, end });
    at = end;
  }
  if (!chunks.length || chunks[0].type !== 'IHDR' || chunks.at(-1).type !== 'IEND') {
    throw new Error('missing header or end');
  }
  return chunks;
}

function strip(buffer) {
  const kept = [SIGNATURE];
  const dropped = [];
  for (const chunk of readChunks(buffer)) {
    if (KEEP.has(chunk.type)) kept.push(buffer.subarray(chunk.start, chunk.end));
    else dropped.push(chunk.type);
  }
  return { bytes: Buffer.concat(kept), dropped };
}

// The second look: read the cleaned file again and list anything that is not on the allow-list.
function leftovers(buffer) {
  return readChunks(buffer).map((c) => c.type).filter((type) => !KEEP.has(type));
}

function exportSafely(buffer) {
  const { bytes, dropped } = strip(buffer);
  const left = leftovers(bytes);
  if (left.length) throw new Error('refused, still holds ' + left.join(','));
  return { bytes, dropped };
}

const text = (keyword, value) => makeChunk('tEXt', Buffer.from(keyword + '\0' + value, 'latin1'));
const original = Buffer.concat([
  SIGNATURE,
  makeChunk('IHDR', Buffer.alloc(13)),
  text('Software', 'example editor 1.0'),
  makeChunk('tIME', Buffer.alloc(7)),
  makeChunk('eXIf', Buffer.from('placeholder camera and place data')),
  text('prompt', 'a long hidden prompt'),
  makeChunk('IDAT', Buffer.from([1, 2, 3])),
  makeChunk('IEND', Buffer.alloc(0)),
]);

console.log('before  :', readChunks(original).map((c) => c.type).join(','));
const result = exportSafely(original);
console.log('dropped :', result.dropped.join(','));
console.log('after   :', readChunks(result.bytes).map((c) => c.type).join(','));
console.log('bytes   :', original.length + ' -> ' + result.bytes.length);

try {
  exportSafely(original.subarray(0, original.length - 5));
} catch (error) {
  console.log('cut-off file:', 'refused, ' + error.message);
}

// Prove that the second look works: a strip that forgets one chunk type is caught by the re-read.
const careless = Buffer.concat([SIGNATURE, ...readChunks(original)
  .filter((c) => KEEP.has(c.type) || c.type === 'tEXt')
  .map((c) => original.subarray(c.start, c.end))]);
console.log('careless strip, second look:', leftovers(careless).join(','));