Tether API

• [*]LanguagesTypeScript
• [*]FrameworksBun.serve (hand-written router, no framework)
• [*]StoresSQLite (bun:sqlite, WAL)
• [*]AsyncsetInterval settlement sweep (30s) · Server-sent events with replay buffer
• [*]InfraBun single-binary build (bun build --compile) · Local host only (no deploy config)
• [*]Third partiesGoogle OAuth JWKS (ID-token verification) · Open Library Books API · UPCitemdb

How it holds up

Auth

Opaque 40-character bearer session tokens stored in a sessions table with a 30-day TTL; sign-in by phone or email with argon2id password hashes and a dummy-hash verify so a missing account and a wrong password take the same time; Google sign-in verifies the RS256 ID token's signature, issuer, audience and expiry itself; SMS one-time codes are a fixed dev code because no SMS provider is wired, and the API says so in its response.

Data

14 tables across 8 migrations in apps/api/src/db/schema.ts: devices holds denormalised current holder, custody_events is an append-only log with a UNIQUE idempotency_key, plus users, sessions, oauth_identities, trust, pending_transfers, disputes, guest_loans, nudges, preferences, identifiers (unit vs model scope, with a partial unique index so only unit-scoped codes like IMEIs are globally unique), catalog_cache and tac_models.

Consistency

Custody moves are compare-and-swap UPDATEs checked on changes === 1, with idempotency keys enforced by UNIQUE columns on custody_events and pending_transfers (settlement and dispute writes use derived keys such as settle:<id>). The atomic() helper is a type-level guard that refuses an async callback so no await can split a read-modify-write; it is not a SQLite transaction, so the holder UPDATE and the log INSERT are two autocommit statements kept together only by bun:sqlite being synchronous in a single process.

Failure

Catalogue lookups have 6s timeouts and a provider outage is reported to the user and deliberately not cached as a miss; the JWKS fetch has a 10s timeout and honours Cache-Control max-age; the router turns any unhandled error into a problem-style JSON body with a request id; SSE uses a 25s heartbeat under a 120s idle timeout and drops dead connections without stopping fan-out; /metrics exposes event-loop lag and live SSE connection counts. There is no retry or dead-letter path because nothing is queued.

Testing

None committed: no test files exist under apps/api despite a bun test script (git ls-files finds no *.test.* or spec files). The README's 20-concurrent-claims load result has no script in the repo.

Techniques

1. Compare-and-swap custody claimA claim is a single UPDATE guarded by the holder the client saw, accepted only when exactly one row changed; the loser gets a 409 with the current holder. No lock and no read-modify-write window.apps/api/src/routes/devices.ts:149 apps/api/src/routes/devices.ts:169 apps/api/src/routes/devices.ts:183
2. Append-only custody log with idempotency keyscustody_events is never updated and carries a UNIQUE idempotency_key, so a replayed scan returns replayed: true instead of creating a second loan; timer- and dispute-driven writes derive their own keys (settle:<id>, dispute:<id>).apps/api/src/db/schema.ts:57 apps/api/src/routes/devices.ts:164 apps/api/src/routes/lending.ts:45
3. Veto window as a pending transferPass-on writes a pending_transfers row that settles after 10 minutes unless the owner vetoes; settlement runs lazily on read and on a 30s timer, and re-uses the same CAS so a holder change underneath makes the transfer moot instead of retrying forever.apps/api/src/routes/lending.ts:18 apps/api/src/routes/lending.ts:33 apps/api/src/routes/lending.ts:153 apps/api/src/server.ts:47
4. Type-level guard against await in critical sectionsatomic() is typed so an async callback fails to compile, which stops an await from opening a gap inside a read-modify-write; KeyedMutex serialises per key for cases that must await.apps/api/src/core/atomic.ts:28
5. SSE with Last-Event-ID replay and id-only payloadsEach user gets a 64-event backlog with monotonic ids; a reconnecting phone sends Last-Event-ID and receives what it missed. Events carry ids and a reason, never rows, so there is one authorisation path.apps/api/src/core/events.ts:56 apps/api/src/core/events.ts:116 apps/api/src/routes/events.ts:20
6. Zero-dependency migrations and Google token verificationA 25-line migration runner applies each SQL migration in its own transaction, toggles foreign keys around table rebuilds and fails startup on PRAGMA foreign_key_check; Google ID tokens are verified with crypto.subtle against a JWKS cache that honours max-age.apps/api/src/db/schema.ts:296 apps/api/src/db/schema.ts:314 apps/api/src/core/google.ts:17 apps/api/src/core/google.ts:55

Counted

• 21Commits (whole repo)
  git rev-list --count HEAD
• 0npm dependencies in apps/api
  apps/api/package.json "dependencies": {}
• 37Routes
  grep -hE '^\s*(r|router)\.(get|post|patch|delete)\("' src/routes/*.ts src/server.ts | wc -l
• 8Migrations
  grep -c 'id: "00' apps/api/src/db/schema.ts
• 14 (+ _migrations)Tables
  CREATE TABLE in apps/api/src/db/schema.ts (16 statements incl. users_new rebuild and _migrations)
• 2,991API TypeScript LOC
  git ls-files 'apps/api/*.ts' | xargs wc -l | tail -1
• 0Test files
  git ls-files | grep -iE 'test|spec' (only icon SVGs match)
• 10 minVeto window
  apps/api/src/routes/lending.ts:18
• 64 events per userSSE replay buffer
  apps/api/src/core/events.ts:56