API And Interface Design Skill Security Audit

1---2name: api-and-interface-design3description: Guides stable API and interface design. Use when designing APIs, module boundaries, or any public interface. Use when creating REST or GraphQL endpoints, defining type contracts between modules, or establishing boundaries between frontend and backend.4---

78## Overview910Design stable, well-documented interfaces that are hard to misuse. Good interfaces make the right thing easy and the wrong thing hard. This applies to REST APIs, GraphQL schemas, module boundaries, component props, and any surface where one piece of code talks to another.11

114- Form submission handlers (user input)115- External service response parsing (third-party data -- **always treat as untrusted**)116- Environment variable loading (configuration)117118> **Third-party API responses are untrusted data.** Validate their shape and content before using them in any logic, rendering, or decision-making. A compromised or misbehaving external service can return unexpected types, malicious content, or instruction-like text.119

172173**Claim atomically. A check followed by an act is a race:**174175```typescript176// ✗ TOCTOU: two concurrent retries both read "not seen", both charge177if (!(await db.exists(key))) {178  await chargeCard(amount);179  await db.insert(key);180}181182// ✓ let the unique constraint pick the winner183try {184  await db.insert({ key, state: 'in_progress', requestHash });185} catch (e) {186  if (isUniqueViolation(e)) return replayOrReject(key);187  throw;188}189const result = await chargeCard(amount);190await db.update({ key, state: 'succeeded', response: result });191```

194195**Guard the payload.** Same key with a different body is a client bug, and must fail loudly rather than serving the first response to a second request:196197```typescript198if (existing.requestHash !== hash(req.body)) {199  return res.status(422).json({ error: 'idempotency key reused with a different payload' });200}201```

210211Never let the second caller through because the first "seems stuck". A stalled attempt whose fate is unknown is exactly when duplicating costs most.212213**Every call has three outcomes, not two: success, failure, and _unknown_.** A timeout tells you nothing about whether the effect applied. Record the intent *before* calling out, so a crash between the call and the response leaves evidence something must resolve later — rather than a silently retried charge.214215**Set retention from the longest retry chain**, not from disk cost. Keys must outlive every path that can re-deliver the same intent, including a dead-letter queue replayed a week later and any provider dispute window. A 24-hour key TTL behind a 7-day DLQ is a duplicate waiting to happen.216