Skip to main content
Purpose: modify this repository without breaking protocol fau/1 or user custody guarantees. Audience: contributors who already ran Developer getting started.

Read first

  1. Concepts — goals, non-goals, invariants
  2. Protocol overview — ownership and flows
  3. Wire specification — if you touch wire formats
  4. Security model — if you touch auth, store, or relay trust

Where code lives

Extension map

Invariants (must survive a rewrite)

From Concepts — abbreviated:
  1. No inbox token to agents
  2. Relay never decrypts node-SNI TLS
  3. Phone decisions require device signatures (or explicit local dashboard decide)
  4. Push is content-free
  5. Resolve shapes match for known and unknown emails
  6. Device signatures cover full targets including query strings
  7. Agent nonces are single-use inside expiry

How to test

If you change device canonicalization, update Device signing vectors and fixtures/device-vectors.json (generator: apps/phone/scripts/gen-device-vectors.ts). If you change tunnel frames or relay HTTP, update Wire specification and fixtures/test-vectors.json, then run relay↔node interop tests.

Design decision discipline

When you choose a new boundary, document in the PR:
  • Decision
  • Why
  • Alternatives
  • Tradeoff
Or the next engineer will rediscover it the hard way. Product-shaped seams (channels, local indexes/classifiers, Computer Use) are sketched in Product architecture — non-normative, not fau/1.

Open questions (product / protocol)

Labeled so they are not mistaken for law — see also protocol overview:
  • Per-app push filtering when multiple approval apps pair to one node
  • Phone-initiated device deregister API

Next

Return to For protocol developers or deepen in Protocol overview.