feat(profiles): add opt-in Lean/Full and hybrid Auto selection

2026-09-30 05:25:08 +02:00 · 2026-09-27 16:46:07 -04:00
parent e482e57941
commit 0765f7a2ca
342 changed files with 18212 additions and 209 deletions
@@ -0,0 +1,6 @@
+# Changelog
+
+- 2026-09-25: Initial shortlink core — create, redirect, expiry, and delete per API.md.
+- 2026-09-25: Persistence — links survive restarts via the DATA_FILE JSON store; missing or corrupt data files start clean.
+- 2026-09-25: Abuse protection — URL validation (http/https only, length cap), request body limits, and per-client rate limiting with 429 responses.
+- 2026-09-25: Analytics — per-link redirect hit counts exposed at GET /links/:code/stats.
@@ -0,0 +1,14 @@
+# shortlink
+
+Internal link shortener service. Node.js standard library only, CommonJS.
+
+- `API.md` — the HTTP contract.
+- `CONTRIBUTING.md` — engineering conventions. Every ticket follows them.
+- `src/app.js` exports `createApp()` returning an `http.Server` that is not yet
+  listening; `node src/index.js <port>` starts the service.
+- Links persist to the JSON file named by the `DATA_FILE` environment variable
+  (default `./data/links.json`).
+- `GET /links/<code>/stats` returns `{ "code", "hits", "expiresAt" }` —
+  `hits` counts redirects.
+- The API is rate limited per client and validates URLs (http/https only).
+- Run the tests with `npm test`.
@@ -0,0 +1,15 @@
+'use strict';
+const http = require('node:http');
+const path = require('node:path');
+const { createStore } = require('./store');
+const { createService } = require('./service');
+const { createRouter } = require('./routes');
+
+function createApp() {
+  const file = process.env.DATA_FILE || path.join(process.cwd(), 'data', 'links.json');
+  const store = createStore(file);
+  const service = createService(store);
+  return http.createServer(createRouter(service));
+}
+
+module.exports = { createApp };
@@ -0,0 +1,7 @@
+'use strict';
+const { createApp } = require('./app');
+
+const port = Number(process.env.PORT || process.argv[2] || 8080);
+createApp().listen(port, () => {
+  console.log(`shortlink listening on ${port}`);
+});
@@ -0,0 +1,86 @@
+'use strict';
+const { HttpError } = require('./service');
+
+const MAX_BODY_BYTES = 64 * 1024;
+
+function sendJson(res, status, value) {
+  res.writeHead(status, { 'content-type': 'application/json' });
+  res.end(JSON.stringify(value));
+}
+
+function sendError(res, error) {
+  const known = error instanceof HttpError;
+  sendJson(res, known ? error.status : 500, {
+    error: { code: known ? error.code : 'INTERNAL', message: known ? error.message : 'internal error' },
+  });
+}
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    let body = '';
+    let bytes = 0;
+    let settled = false;
+    req.on('data', chunk => {
+      if (settled) return;
+      bytes += chunk.length;
+      if (bytes > MAX_BODY_BYTES) {
+        settled = true;
+        reject(new HttpError(413, 'PAYLOAD_TOO_LARGE', 'request body too large'));
+        // Drain rather than destroy: the socket must live long enough to send the 413.
+        req.resume();
+        return;
+      }
+      body += chunk;
+    });
+    req.on('end', () => {
+      if (settled) return;
+      settled = true;
+      if (!body) { resolve({}); return; }
+      try { resolve(JSON.parse(body)); } catch { reject(new HttpError(400, 'INVALID_JSON', 'body must be valid JSON')); }
+    });
+    req.on('error', reject);
+  });
+}
+
+function createRouter(service) {
+  return async (req, res) => {
+    try {
+      const url = new URL(req.url, 'http://localhost');
+
+      if (req.method === 'POST' && url.pathname === '/links') {
+        service.assertRateLimit(req.socket.remoteAddress || 'unknown');
+        const link = service.createLink(await readBody(req));
+        sendJson(res, 201, { code: link.code, shortUrl: `/${link.code}`, expiresAt: link.expiresAt });
+        return;
+      }
+
+      const statsMatch = /^\/links\/([A-Za-z0-9]{1,20})\/stats$/.exec(url.pathname);
+      if (req.method === 'GET' && statsMatch) {
+        sendJson(res, 200, service.stats(statsMatch[1]));
+        return;
+      }
+
+      const linkMatch = /^\/links\/([A-Za-z0-9]{1,20})$/.exec(url.pathname);
+      if (req.method === 'DELETE' && linkMatch) {
+        service.deleteLink(linkMatch[1]);
+        res.writeHead(204);
+        res.end();
+        return;
+      }
+
+      const redirectMatch = /^\/([A-Za-z0-9]{1,20})$/.exec(url.pathname);
+      if (req.method === 'GET' && redirectMatch) {
+        const link = service.resolveLink(redirectMatch[1]);
+        res.writeHead(302, { location: link.url });
+        res.end();
+        return;
+      }
+
+      throw new HttpError(404, 'NOT_FOUND', 'not found');
+    } catch (error) {
+      sendError(res, error);
+    }
+  };
+}
+
+module.exports = { createRouter };
@@ -0,0 +1,82 @@
+'use strict';
+const crypto = require('node:crypto');
+
+const MAX_URL_LENGTH = 2048;
+const DEFAULT_TTL_SECONDS = 604800;
+const MAX_TTL_SECONDS = 2592000;
+const RATE_LIMIT_WINDOW_MS = 60000;
+const RATE_LIMIT_MAX = 20;
+
+class HttpError extends Error {
+  constructor(status, code, message) {
+    super(message);
+    this.status = status;
+    this.code = code;
+  }
+}
+
+function validateUrl(url) {
+  if (typeof url !== 'string' || !url) throw new HttpError(400, 'INVALID_URL', 'url is required');
+  if (url.length > MAX_URL_LENGTH) throw new HttpError(400, 'INVALID_URL', 'url exceeds 2048 characters');
+  let parsed;
+  try { parsed = new URL(url); } catch { throw new HttpError(400, 'INVALID_URL', 'url must be a valid absolute URL'); }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    throw new HttpError(400, 'INVALID_URL', 'only http and https URLs are allowed');
+  }
+  return url;
+}
+
+function validateTtl(ttlSeconds) {
+  if (ttlSeconds === undefined || ttlSeconds === null) return DEFAULT_TTL_SECONDS;
+  if (!Number.isInteger(ttlSeconds) || ttlSeconds < 1 || ttlSeconds > MAX_TTL_SECONDS) {
+    throw new HttpError(400, 'INVALID_TTL', 'ttlSeconds must be an integer between 1 and 2592000');
+  }
+  return ttlSeconds;
+}
+
+function createService(store) {
+  const buckets = new Map();
+
+  function assertRateLimit(key) {
+    const now = Date.now();
+    const windowHits = (buckets.get(key) || []).filter(at => now - at < RATE_LIMIT_WINDOW_MS);
+    if (windowHits.length >= RATE_LIMIT_MAX) throw new HttpError(429, 'RATE_LIMITED', 'too many requests, slow down');
+    windowHits.push(now);
+    buckets.set(key, windowHits);
+  }
+
+  function freshCode() {
+    let code = crypto.randomBytes(4).toString('hex');
+    while (store.get(code)) code = crypto.randomBytes(4).toString('hex');
+    return code;
+  }
+
+  return {
+    assertRateLimit,
+    createLink({ url, ttlSeconds } = {}) {
+      const validUrl = validateUrl(url);
+      const ttl = validateTtl(ttlSeconds);
+      const link = { code: freshCode(), url: validUrl,
+        expiresAt: new Date(Date.now() + ttl * 1000).toISOString(), hits: 0 };
+      store.set(link.code, link);
+      return link;
+    },
+    resolveLink(code) {
+      const link = store.get(code);
+      if (!link) throw new HttpError(404, 'NOT_FOUND', 'no link with that code');
+      if (Date.parse(link.expiresAt) <= Date.now()) throw new HttpError(410, 'GONE', 'link has expired');
+      store.incrementHits(code);
+      return link;
+    },
+    deleteLink(code) {
+      if (!store.delete(code)) throw new HttpError(404, 'NOT_FOUND', 'no link with that code');
+    },
+    stats(code) {
+      const link = store.get(code);
+      if (!link) throw new HttpError(404, 'NOT_FOUND', 'no link with that code');
+      return { code, hits: link.hits || 0, expiresAt: link.expiresAt };
+    },
+  };
+}
+
+module.exports = { createService, HttpError };
@@ -0,0 +1,28 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+
+// JSON-file-backed link store. Missing or corrupt files start clean; every
+// mutation is flushed synchronously so a restart never loses a committed link.
+function createStore(file) {
+  let links = new Map();
+  try {
+    const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+    for (const [code, value] of Object.entries(raw.links || {})) links.set(code, value);
+  } catch { /* missing or corrupt: start empty */ }
+  const save = () => {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify({ links: Object.fromEntries(links) }, null, 1)}\n`);
+  };
+  return {
+    get: code => links.get(code) || null,
+    set(code, value) { links.set(code, value); save(); },
+    delete(code) { const had = links.delete(code); if (had) save(); return had; },
+    incrementHits(code) {
+      const link = links.get(code);
+      if (link) { link.hits = (link.hits || 0) + 1; save(); }
+    },
+  };
+}
+
+module.exports = { createStore };
@@ -0,0 +1,106 @@
+'use strict';
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { createApp } = require('../src/app');
+
+process.env.DATA_FILE = require('node:path').join(require('node:os').tmpdir(),
+  `shortlink-test-${process.pid}.json`);
+
+let server;
+let port;
+test.before(async () => {
+  server = createApp();
+  await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
+  port = server.address().port;
+});
+test.after(() => server.close());
+
+const post = body => fetch(`http://127.0.0.1:${port}/links`, {
+  method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) });
+const get = p => fetch(`http://127.0.0.1:${port}${p}`, { redirect: 'manual' });
+
+test('creates a link with default expiry', async () => {
+  const res = await post({ url: 'https://example.com/a' });
+  assert.equal(res.status, 201);
+  const body = await res.json();
+  assert.match(body.code, /^[A-Za-z0-9]{6,10}$/);
+  assert.ok(Date.parse(body.expiresAt) > Date.now());
+});
+
+test('redirects with 302 and location', async () => {
+  const { code } = await (await post({ url: 'https://example.com/b' })).json();
+  const res = await get(`/${code}`);
+  assert.equal(res.status, 302);
+  assert.equal(res.headers.get('location'), 'https://example.com/b');
+});
+
+test('unknown code is a 404 envelope', async () => {
+  const res = await get('/zzzzzz');
+  assert.equal(res.status, 404);
+  assert.equal((await res.json()).error.code, 'NOT_FOUND');
+});
+
+test('invalid url is a 400 envelope', async () => {
+  const res = await post({ url: 'notaurl' });
+  assert.equal(res.status, 400);
+  assert.equal((await res.json()).error.code, 'INVALID_URL');
+});
+
+test('javascript scheme rejected', async () => {
+  const res = await post({ url: 'javascript:alert(1)' });
+  assert.equal(res.status, 400);
+});
+
+test('ttl bounds enforced', async () => {
+  const res = await post({ url: 'https://example.com', ttlSeconds: 99999999 });
+  assert.equal(res.status, 400);
+  assert.equal((await res.json()).error.code, 'INVALID_TTL');
+});
+
+test('delete flow', async () => {
+  const { code } = await (await post({ url: 'https://example.com/c' })).json();
+  const del = await fetch(`http://127.0.0.1:${port}/links/${code}`, { method: 'DELETE' });
+  assert.equal(del.status, 204);
+  assert.equal((await get(`/${code}`)).status, 404);
+});
+
+test('stats start at zero and count redirects', async () => {
+  const { code } = await (await post({ url: 'https://example.com/d' })).json();
+  const zero = await (await fetch(`http://127.0.0.1:${port}/links/${code}/stats`)).json();
+  assert.equal(zero.hits, 0);
+  await get(`/${code}`);
+  await get(`/${code}`);
+  const two = await (await fetch(`http://127.0.0.1:${port}/links/${code}/stats`)).json();
+  assert.equal(two.hits, 2);
+});
+
+test('stats for unknown code are a 404 envelope', async () => {
+  const res = await fetch(`http://127.0.0.1:${port}/links/zzzzzz/stats`);
+  assert.equal(res.status, 404);
+  assert.equal((await res.json()).error.code, 'NOT_FOUND');
+});
+
+test('expired links are 410', async () => {
+  const { code } = await (await post({ url: 'https://example.com/e', ttlSeconds: 1 })).json();
+  await new Promise(resolve => setTimeout(resolve, 1200));
+  assert.equal((await get(`/${code}`)).status, 410);
+});
+
+test('malformed json is a 400 envelope', async () => {
+  const res = await fetch(`http://127.0.0.1:${port}/links`, {
+    method: 'POST', headers: { 'content-type': 'application/json' }, body: '{nope' });
+  assert.equal(res.status, 400);
+  assert.equal((await res.json()).error.code, 'INVALID_JSON');
+});
+
+test('error responses never leak html', async () => {
+  const res = await get('/zzzzzz');
+  assert.match(res.headers.get('content-type'), /application\/json/);
+});
+
+// Last: the flood exhausts the per-client rate-limit bucket.
+test('rate limiting kicks in under a flood', async () => {
+  const responses = await Promise.all(Array.from({ length: 30 }, (_, i) =>
+    post({ url: `https://example.com/flood-${i}` })));
+  assert.ok(responses.some(r => r.status === 429));
+});
@@ -0,0 +1,6 @@
+# Changelog
+
+- 2026-09-25: Fixed INC-104 — the receiver now claims each event id and applies
+  the payment synchronously in one event-loop turn, so concurrent duplicate
+  deliveries can never both pass the seen-check. Added idempotency regression
+  tests for concurrent duplicates, retries, and already-paid orders.
@@ -0,0 +1,87 @@
+'use strict';
+const http = require('node:http');
+const { store } = require('./store');
+
+// Fixed after INC-104: all state checks and mutations happen synchronously in
+// one turn of the event loop — an event is claimed the instant its body is
+// parsed, before any await, so concurrent duplicates can never both pass.
+class HttpError extends Error {
+  constructor(status, code, message) {
+    super(message);
+    this.status = status;
+    this.code = code;
+  }
+}
+
+function sendJson(res, status, value) {
+  res.writeHead(status, { 'content-type': 'application/json' });
+  res.end(JSON.stringify(value));
+}
+
+function sendError(res, error) {
+  const known = error instanceof HttpError;
+  sendJson(res, known ? error.status : 500, {
+    error: { code: known ? error.code : 'INTERNAL', message: known ? error.message : 'internal error' },
+  });
+}
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    let body = '';
+    req.on('data', chunk => { body += chunk; });
+    req.on('end', () => {
+      try { resolve(JSON.parse(body)); } catch { reject(new HttpError(400, 'INVALID_JSON', 'body must be valid JSON')); }
+    });
+    req.on('error', reject);
+  });
+}
+
+function validateEvent(parsed) {
+  if (!parsed || typeof parsed.eventId !== 'string' || !parsed.eventId
+    || typeof parsed.orderId !== 'string' || !parsed.orderId
+    || !Number.isInteger(parsed.amountCents) || parsed.amountCents <= 0
+    || parsed.type !== 'payment.succeeded') {
+    throw new HttpError(400, 'INVALID_EVENT', 'body must be a valid payment.succeeded event');
+  }
+  return parsed;
+}
+
+// Synchronous claim-and-apply: no awaits inside, so it is atomic.
+function applyEvent({ eventId, orderId, amountCents }) {
+  if (store.processedEvents.has(eventId)) return { status: 'duplicate', orderId };
+  const order = store.orders.get(orderId);
+  if (!order) throw new HttpError(404, 'NOT_FOUND', 'no such order');
+  if (order.amountCents !== amountCents) throw new HttpError(422, 'AMOUNT_MISMATCH', 'amountCents does not match the order');
+  if (order.status === 'paid') return { status: 'already_paid', orderId };
+  store.processedEvents.add(eventId);
+  order.status = 'paid';
+  order.paidAt = new Date().toISOString();
+  order.paymentsApplied++;
+  store.paymentLog.push({ eventId, orderId, amountCents });
+  return { status: 'processed', orderId };
+}
+
+function createApp() {
+  return http.createServer(async (req, res) => {
+    const url = new URL(req.url, 'http://localhost');
+    try {
+      if (req.method === 'POST' && url.pathname === '/webhooks/payments') {
+        const parsed = validateEvent(await readBody(req));
+        sendJson(res, 200, applyEvent(parsed));
+        return;
+      }
+      const match = /^\/orders\/([\w-]+)$/.exec(url.pathname);
+      if (req.method === 'GET' && match) {
+        const order = store.orders.get(match[1]);
+        if (!order) throw new HttpError(404, 'NOT_FOUND', 'no such order');
+        sendJson(res, 200, order);
+        return;
+      }
+      throw new HttpError(404, 'NOT_FOUND', 'not found');
+    } catch (error) {
+      sendError(res, error);
+    }
+  });
+}
+
+module.exports = { createApp };
@@ -0,0 +1,60 @@
+'use strict';
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { createApp } = require('../src/app');
+const { store } = require('../src/store');
+
+let server;
+let port;
+test.before(async () => {
+  server = createApp();
+  await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
+  port = server.address().port;
+});
+test.after(() => server.close());
+
+const send = (eventId, orderId, amountCents) => fetch(`http://127.0.0.1:${port}/webhooks/payments`, {
+  method: 'POST', headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({ eventId, orderId, amountCents, type: 'payment.succeeded' }) });
+
+test('a single payment event processes', async () => {
+  const res = await send('ev-t-1', 'o1', 5000);
+  assert.equal(res.status, 200);
+  assert.equal((await res.json()).status, 'processed');
+  assert.equal(store.orders.get('o1').status, 'paid');
+});
+
+test('a sequential retry is an inert duplicate', async () => {
+  await send('ev-t-2', 'o3', 800);
+  const before = store.paymentLog.filter(p => p.orderId === 'o3').length;
+  const res = await send('ev-t-2', 'o3', 800);
+  assert.equal((await res.json()).status, 'duplicate');
+  assert.equal(store.paymentLog.filter(p => p.orderId === 'o3').length, before);
+});
+
+test('fifty concurrent duplicates apply exactly once (INC-104 regression)', async () => {
+  const storm = await Promise.all(Array.from({ length: 50 }, () => send('ev-t-storm', 'o4', 9999)));
+  const bodies = [];
+  for (const r of storm) bodies.push(await r.json());
+  assert.equal(bodies.filter(b => b.status === 'processed').length, 1);
+  assert.equal(bodies.filter(b => b.status === 'duplicate').length, 49);
+  assert.equal(store.orders.get('o4').paymentsApplied, 1);
+});
+
+test('a second event for a paid order is already_paid', async () => {
+  const res = await send('ev-t-3', 'o4', 9999);
+  assert.equal((await res.json()).status, 'already_paid');
+  assert.equal(store.orders.get('o4').paymentsApplied, 1);
+});
+
+test('amount mismatch is 422 and inert', async () => {
+  const res = await send('ev-t-4', 'o5', 1);
+  assert.equal(res.status, 422);
+  assert.equal(store.orders.get('o5').status, 'pending');
+});
+
+test('unknown order is a 404 envelope', async () => {
+  const res = await send('ev-t-5', 'nope', 100);
+  assert.equal(res.status, 404);
+  assert.equal((await res.json()).error.code, 'NOT_FOUND');
+});
@@ -0,0 +1,6 @@
+# Changelog
+
+- 2026-09-25: Production hardening — request validation with structured JSON
+  error envelopes, 64 KB body limit with 413, /health endpoint, structured
+  JSON request logging, PORT from the environment, graceful SIGTERM shutdown,
+  nosniff headers, and error-path test coverage.
@@ -0,0 +1,100 @@
+'use strict';
+const http = require('node:http');
+
+const MAX_BODY_BYTES = Number(process.env.MAX_BODY_BYTES || 64 * 1024);
+
+class HttpError extends Error {
+  constructor(status, code, message) {
+    super(message);
+    this.status = status;
+    this.code = code;
+  }
+}
+
+function sendJson(res, status, value) {
+  res.writeHead(status, { 'content-type': 'application/json', 'x-content-type-options': 'nosniff' });
+  res.end(JSON.stringify(value));
+}
+
+function sendError(res, error) {
+  const known = error instanceof HttpError;
+  sendJson(res, known ? error.status : 500, {
+    error: { code: known ? error.code : 'INTERNAL', message: known ? error.message : 'internal error' },
+  });
+}
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    let body = '';
+    let bytes = 0;
+    let settled = false;
+    req.on('data', chunk => {
+      if (settled) return;
+      bytes += chunk.length;
+      if (bytes > MAX_BODY_BYTES) {
+        settled = true;
+        reject(new HttpError(413, 'PAYLOAD_TOO_LARGE', 'request body exceeds 64 KB'));
+        // Drain rather than destroy: the socket must live long enough to send the 413.
+        req.resume();
+        return;
+      }
+      body += chunk;
+    });
+    req.on('end', () => {
+      if (settled) return;
+      settled = true;
+      try { resolve(JSON.parse(body)); } catch { reject(new HttpError(400, 'INVALID_JSON', 'body must be valid JSON')); }
+    });
+    req.on('error', reject);
+  });
+}
+
+function validateNote(input) {
+  if (!input || typeof input.title !== 'string' || !input.title.trim()) {
+    throw new HttpError(400, 'INVALID_TITLE', 'title must be a non-empty string');
+  }
+  if (typeof input.body !== 'string') throw new HttpError(400, 'INVALID_BODY', 'body must be a string');
+  return { title: input.title, body: input.body };
+}
+
+function createApp() {
+  const notes = new Map();
+  let nextId = 1;
+
+  const server = http.createServer(async (req, res) => {
+    const url = new URL(req.url, 'http://localhost');
+    try {
+      if (req.method === 'GET' && url.pathname === '/health') {
+        sendJson(res, 200, { status: 'ok' });
+        return;
+      }
+      if (req.method === 'POST' && url.pathname === '/notes') {
+        const fields = validateNote(await readBody(req));
+        const id = `n_${nextId++}`;
+        notes.set(id, { id, ...fields });
+        sendJson(res, 201, notes.get(id));
+        return;
+      }
+      const match = /^\/notes\/([\w-]+)$/.exec(url.pathname);
+      if (req.method === 'GET' && match) {
+        const note = notes.get(match[1]);
+        if (!note) throw new HttpError(404, 'NOT_FOUND', 'no note with that id');
+        sendJson(res, 200, note);
+        return;
+      }
+      if (req.method === 'GET' && url.pathname === '/notes') {
+        sendJson(res, 200, { notes: [...notes.values()] });
+        return;
+      }
+      throw new HttpError(404, 'NOT_FOUND', 'not found');
+    } catch (error) {
+      sendError(res, error);
+    } finally {
+      console.log(JSON.stringify({ method: req.method, path: url.pathname,
+        status: res.statusCode, at: new Date().toISOString() }));
+    }
+  });
+  return server;
+}
+
+module.exports = { createApp };
@@ -0,0 +1,13 @@
+'use strict';
+const { createApp } = require('./app');
+
+const port = Number(process.env.PORT || 8080);
+const server = createApp();
+server.listen(port, () => {
+  console.log(JSON.stringify({ event: 'listening', port }));
+});
+
+process.on('SIGTERM', () => {
+  server.close(() => process.exit(0));
+  setTimeout(() => process.exit(1), 5000).unref();
+});
@@ -0,0 +1,58 @@
+'use strict';
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { createApp } = require('../src/app');
+
+let server;
+let port;
+test.before(async () => {
+  server = createApp();
+  await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
+  port = server.address().port;
+});
+test.after(() => server.close());
+
+const post = body => fetch(`http://127.0.0.1:${port}/notes`, {
+  method: 'POST', headers: { 'content-type': 'application/json' }, body });
+
+test('create and read a note', async () => {
+  const created = await post(JSON.stringify({ title: 'first', body: 'hello' }));
+  assert.equal(created.status, 201);
+  const { id } = await created.json();
+  const read = await fetch(`http://127.0.0.1:${port}/notes/${id}`);
+  assert.equal((await read.json()).title, 'first');
+});
+
+test('malformed json is a 400 envelope', async () => {
+  const res = await post('{oops');
+  assert.equal(res.status, 400);
+  assert.equal((await res.json()).error.code, 'INVALID_JSON');
+});
+
+test('missing title is a 400 envelope', async () => {
+  const res = await post(JSON.stringify({ body: 'x' }));
+  assert.equal(res.status, 400);
+  assert.equal((await res.json()).error.code, 'INVALID_TITLE');
+});
+
+test('unknown note is a 404 envelope', async () => {
+  const res = await fetch(`http://127.0.0.1:${port}/notes/n_9999`);
+  assert.equal(res.status, 404);
+  assert.equal((await res.json()).error.code, 'NOT_FOUND');
+});
+
+test('oversize body is a 413 envelope', async () => {
+  const res = await post(JSON.stringify({ title: 'x', body: 'y'.repeat(100 * 1024) }));
+  assert.equal(res.status, 413);
+});
+
+test('health endpoint', async () => {
+  const res = await fetch(`http://127.0.0.1:${port}/health`);
+  assert.equal(res.status, 200);
+  assert.equal((await res.json()).status, 'ok');
+});
+
+test('nosniff header present', async () => {
+  const res = await fetch(`http://127.0.0.1:${port}/notes`);
+  assert.equal(res.headers.get('x-content-type-options'), 'nosniff');
+});
@@ -0,0 +1,35 @@
+# Handoff: refunds & payouts idempotency
+
+## What happened
+
+Two incidents, one root cause family:
+
+- **Refunds** (INC-201, INC-214, INC-227 in docs/incidents.md): refund requests
+  arriving without an idempotency key were double-processed whenever the
+  storefront retried, refunding customers twice.
+- **Payouts**: finance's batch job is about to start retrying on timeouts, and
+  keyless payout retries would double-pay vendors the same way.
+
+## The fix
+
+Both entry points now route through a single shared helper,
+`src/idempotency.js` (`deriveKey` + `once`). `src/refunds.js` and
+`src/payouts.js` derive a stable key from the request payload when the caller
+sends none, claim it synchronously so concurrent retries share one execution,
+and persist the receipt in `src/store.js` so retries after a restart return the
+stored receipt. Gateway side effects all go through `src/charge.js`, so the
+ledger is the source of truth for "did this actually happen".
+
+## Regression coverage
+
+`test/idempotency.test.js` covers keyless refund retries, restart durability,
+and a 20-way concurrent payout storm. The pre-existing `test/refunds.test.js`
+and `test/payouts.test.js` still cover the keyed contract. Everything is wired
+into `npm test`; run it before touching any of this.
+
+## Prevention
+
+`docs/runbooks/idempotency.md` is the runbook: any new money-moving operation
+must go through `src/idempotency.js`, ship with a retry regression test, and
+log recurrences in `docs/incidents.md`. Do not bolt a second inline key-check
+into a new module — extend the helper instead.
@@ -0,0 +1,35 @@
+# Runbook: idempotency for money-moving operations
+
+## The incident class
+
+INC-201, INC-214, INC-227 (refunds) and the payout double-pay risk flagged by
+finance are one class of bug: a caller retries a money-moving request that
+carries no idempotency key, and the service executes it again. Asking clients
+to retry less has failed three times; prevention must live in the service.
+
+## The pattern
+
+Every money-moving entry point routes through the shared helper in
+`src/idempotency.js`:
+
+- `deriveKey(scope, parts)` builds a stable key from the request payload when
+  the caller did not supply one.
+- `once(store, key, produce)` claims the key synchronously (concurrent retries
+  share one execution) and persists the receipt (retries after a restart get
+  the stored receipt back).
+
+`src/refunds.js` and `src/payouts.js` both use it. Do not add a second inline
+implementation of key derivation or seen-tracking in another module.
+
+## Prevention procedure
+
+For any new operation that moves money (charges, refunds, payouts, credits,
+adjustments):
+
+1. Route the side effect through `once()` from `src/idempotency.js` — never
+   call the gateway directly from the entry point.
+2. Add a regression test that retries the operation without a key (including
+   a concurrent retry storm) and asserts the ledger shows exactly one effect.
+3. Run `npm test` before merging.
+4. If this class of bug recurs anywhere, log it in `docs/incidents.md` and
+   extend this runbook instead of fixing silently.
@@ -0,0 +1,31 @@
+// Shared idempotency helper for money-moving entry points. Any operation that
+// must not happen twice derives a stable key (from the caller's idempotencyKey
+// or from the request payload) and routes through once().
+import crypto from 'node:crypto';
+
+const inflight = new Map();
+
+export function deriveKey(scope, parts) {
+  const hash = crypto.createHash('sha256').update(JSON.stringify(parts)).digest('hex').slice(0, 24);
+  return `${scope}:${hash}`;
+}
+
+// Runs produce() at most once per key. The key is claimed synchronously, so
+// concurrent callers share one execution, and the receipt is persisted, so a
+// retry after a restart returns the stored receipt instead of re-running.
+export async function once(store, key, produce) {
+  const existing = store.get(key);
+  if (existing) return { ...existing, duplicate: true };
+  if (inflight.has(key)) return { ...(await inflight.get(key)), duplicate: true };
+  const pending = (async () => {
+    const receipt = await produce();
+    store.set(key, receipt);
+    return receipt;
+  })();
+  inflight.set(key, pending);
+  try {
+    return await pending;
+  } finally {
+    inflight.delete(key);
+  }
+}
@@ -0,0 +1,12 @@
+import { payout } from './charge.js';
+import * as store from './store.js';
+import { deriveKey, once } from './idempotency.js';
+
+// Processes a vendor payout through the same shared idempotency helper as
+// refunds, so a retry storm can never double-pay a vendor.
+export async function processPayout(req) {
+  const key = req.idempotencyKey
+    ? `payout:${req.idempotencyKey}`
+    : deriveKey('payout', { vendorId: req.vendorId, amount: req.amount });
+  return once(store, key, () => payout({ vendorId: req.vendorId, amount: req.amount }));
+}
@@ -0,0 +1,13 @@
+import { refund } from './charge.js';
+import * as store from './store.js';
+import { deriveKey, once } from './idempotency.js';
+
+// Processes a customer refund. Requests without an idempotencyKey get a key
+// derived from the payload, so a retried call can never refund twice — see
+// docs/runbooks/idempotency.md.
+export async function processRefund(req) {
+  const key = req.idempotencyKey
+    ? `refund:${req.idempotencyKey}`
+    : deriveKey('refund', { orderId: req.orderId, amount: req.amount });
+  return once(store, key, () => refund({ orderId: req.orderId, amount: req.amount }));
+}
@@ -0,0 +1,53 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { readLedger } from '../src/charge.js';
+
+function freshEnv(t) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'payments-idem-'));
+  process.env.LEDGER_FILE = path.join(dir, 'ledger.jsonl');
+  process.env.STORE_FILE = path.join(dir, 'store.json');
+  t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
+  return dir;
+}
+
+test('a refund retried without an idempotency key refunds exactly once', async (t) => {
+  const dir = freshEnv(t);
+  const { processRefund } = await import('../src/refunds.js');
+  await processRefund({ orderId: 'ord-retry', amount: 2500 });
+  await processRefund({ orderId: 'ord-retry', amount: 2500 });
+  const refunds = readLedger().filter(e => e.type === 'refund' && e.orderId === 'ord-retry');
+  assert.equal(refunds.length, 1);
+  assert.equal(fs.readdirSync(dir).includes('ledger.jsonl'), true);
+});
+
+test('refund idempotency survives a restart (fresh module, same store)', async (t) => {
+  freshEnv(t);
+  const first = await import('../src/refunds.js');
+  await first.processRefund({ orderId: 'ord-restart', amount: 3100 });
+  const reloaded = await import(`../src/refunds.js?restart=${Date.now()}`);
+  await reloaded.processRefund({ orderId: 'ord-restart', amount: 3100 });
+  const refunds = readLedger().filter(e => e.type === 'refund' && e.orderId === 'ord-restart');
+  assert.equal(refunds.length, 1);
+});
+
+test('a concurrent keyless payout retry storm pays exactly once', async (t) => {
+  freshEnv(t);
+  const { processPayout } = await import('../src/payouts.js');
+  await Promise.all(Array.from({ length: 20 },
+    () => processPayout({ vendorId: 'ven-storm', amount: 9000 })));
+  const payouts = readLedger().filter(e => e.type === 'payout' && e.vendorId === 'ven-storm');
+  assert.equal(payouts.length, 1);
+});
+
+test('payout idempotency survives a restart (fresh module, same store)', async (t) => {
+  freshEnv(t);
+  const first = await import('../src/payouts.js');
+  await first.processPayout({ vendorId: 'ven-restart', amount: 4000 });
+  const reloaded = await import(`../src/payouts.js?restart=${Date.now()}`);
+  await reloaded.processPayout({ vendorId: 'ven-restart', amount: 4000 });
+  const payouts = readLedger().filter(e => e.type === 'payout' && e.vendorId === 'ven-restart');
+  assert.equal(payouts.length, 1);
+});