ByteBind ties public management access to a fresh exchange through an authorized private-network device. The first post covers the motivation. Here I am following the requests and checks required by draft 0.7.
The protocol involves a browser, the public application (the relying party, or RP), and a private Authority. The Authority owns the transaction state and uses an overlay-specific provider to identify and authorize the connecting device.
The paths below are illustrative for RP-defined endpoints. The reference implementation uses /v1/begin and /v1/redeem for control requests and /attest for browser attestation.
1. Create a transaction
The browser sends a POST to the application's authentication endpoint. The RP checks that the request's origin matches its public origin, then asks the Authority to create a transaction over an authenticated private control channel.
The Authority binds the transaction to the registered RP, its allowed browser origin, audience, policy, and profile. It generates:
| Value |
Length |
Purpose |
cid |
16 bytes |
Transaction identifier |
C |
32 bytes |
Challenge secret passed to the browser |
S |
32 bytes |
Secret released through successful private attestation |
The RP returns the browser's portion:
{
"cid": "<base64url>",
"C": "<base64url>",
"authority": "https://authority.example.ts.net:8443"
}
It can also set a secure, HttpOnly state cookie and store its hash against the attempt. The reference implementation uses this to check that the later proof belongs to the initiating browser attempt.
The Authority stores C and S, the transaction bindings, a deadline, and an initial pending status. The RP maintains its own attempt records; it reaches the Authority's state through the control API.
For RPs on separate hosts, draft 0.7 uses HTTPS over the overlay, with the Authority checking the calling node's registered identity. On the same host it uses a Unix socket and kernel-reported peer credentials. In both cases, RP identity comes from the connection's authentication, rather than a caller-supplied identifier alone.
2. Attest over the private path
The browser generates a 32-byte nonce, N, and computes the session profile's initial proof:
H1 = HMAC-SHA256(
C,
ASCII("bytebind/v1/h1") || cid || N
)
It sends:
POST /attest
Content-Type: application/json
Origin: https://app.example.com
{"cid":"<base64url>","N":"<base64url>","H1":"<base64url>"}
The Authority validates the expected private host and registered origin before accessing transaction state. It then checks the content type, transaction status and deadline, and the origin stored for this particular cid. It verifies H1 against its stored C, identifies the socket peer through the overlay provider, and applies policy.
When several RPs share an Authority, each transaction retains its expected origin. A page on RP A's origin cannot attest a challenge issued for RP B, even though both origins are registered.
Origin validation addresses malicious browser pages. Non-browser software can choose its own Origin header, so the Authority still checks device identity and authorization. Explicit CORS origins and a JSON request body cause ordinary cross-origin browser requests to be preflighted.
The provider obtains the peer address from the accepted socket and maps it to authenticated overlay identity. A proxy that replaces every client's source address with its own can destroy that mapping. The deployment must preserve the identity of the device being attested.
3. Return the attestation secret
After authorization, the Authority derives a key and encrypts the observed address together with S:
K = HKDF-SHA256(
ikm = C,
salt = H1,
info = ASCII("bytebind/v1/h2"),
length = 32
)
P = IP || S
AAD = ASCII("bytebind/v1/h2") || cid || N || H1
H2 = IV || AES-256-GCM(K, IV, P, AAD)
IP is a 16-byte address, using IPv4-mapped IPv6 where necessary. IV is a fresh 12-byte nonce. The encrypted result includes its 16-byte authentication tag, making decoded H2 76 bytes.
The Authority returns {"H2":"<base64url>"}. The browser derives K, authenticates the response against the same associated data, and extracts IP and S.
The associated data binds the private response to the initial proof and transaction. Encryption protects S from an intermediary that lacks C. Anyone with C and the corresponding transcript can derive the key, so the trust model includes protection of the challenge and browser code.
All transcript inputs are decoded bytes. JSON uses unpadded canonical base64url. Parsers reject malformed encodings, incorrect lengths, and unexpected protocol fields. The labels separate each cryptographic use. The document is draft 0.7; those labels identify protocol v1.
4. Redeem through the application
The browser computes:
R = HMAC-SHA256(
S,
ASCII("bytebind/v1/redeem") || cid || C || IP
)
It posts cid and R to the RP. The RP checks its own origin and attempt binding, then submits the proof to the Authority's redemption endpoint over the private control channel.
The Authority checks the authenticated RP, audience, attested status, redemption deadline, and expected MAC. It uses its stored peer address when reconstructing the transcript. Successful redemption consumes the transaction and returns a scoped grant.
The RP then issues a management lease or executes the stored request. Its own resource authorization, CSRF protection, session handling, and operation recovery still apply.
The proofs are symmetric MACs, and the private reply uses authenticated encryption. The grant is an authorization response on the control channel. ByteBind does not produce a publicly verifiable signed attestation.
Make the state transitions atomic
The Authority progresses through:
pending → attested → redeemed
│ │
└─→ burned ←┘
redeemed and burned are terminal. Deadlines determine whether a transaction is still eligible for a transition.
Attestation performs the identity and proof checks, then makes a conditional database update:
UPDATE challenges
SET status = 'attested',
attested_ip = :peer_ip,
attested_peer_id = :peer_id,
attested_at = :now,
redeem_expires_at = :redeem_deadline
WHERE cid = :cid
AND status = 'pending'
AND challenge_expires_at > :now;
One changed row means success. If two requests race, one of them can transition the record. Redemption uses the same pattern from attested to redeemed.
The provider lookup runs without holding a database write lock; the final update rechecks state and deadline. Failure burns are conditional on the expected state too, so a losing request cannot burn the winner's newer state. Burns must be committed even when the handler returns an error.
The initial host and unregistered-origin failures leave transaction state untouched. Later failures follow the draft's state-specific burn rules.
Bind a grant to one request
The transaction-bound profile adds a request digest:
Q = SHA-256(
ASCII("bytebind/v1/tx/request")
|| len(method) || method
|| len(target) || target
|| len(headers) || headers
|| len(body) || body
)
Lengths are unsigned 64-bit big-endian byte counts. The method is uppercase ASCII; the target contains the path and query; selected headers are normalized and sorted as specified; the body is the transmitted byte sequence. Length prefixes preserve field boundaries.
The browser computes Q from its request. The RP computes the corresponding digest, sends it when creating the transaction, and stores the request for later execution.
The proof transcripts become:
H1 = HMAC-SHA256(C, ASCII("bytebind/v1/tx/h1") || cid || N || Q)
K = HKDF-SHA256(C, H1, ASCII("bytebind/v1/tx/h2"), 32)
AAD = ASCII("bytebind/v1/tx/h2") || cid || N || H1
R = HMAC-SHA256(S, ASCII("bytebind/v1/tx/redeem") || cid || C || IP || Q)
H1 carries the request commitment into the key derivation and associated data. The final MAC binds redemption to it as well.
Browser and server must agree on the encoding before framework normalization. Reformatting a JSON body or rewriting a query can change its digest. Headers excluded from the profile's selection remain outside the commitment. After redemption, the RP executes the stored request covered by that digest.
Handle the gap between authorization and execution
Consuming a proof once and executing an operation at most once are separate responsibilities.
If the RP crashes after redemption, the operation may never run. If it runs and the response is lost, the browser may not know the result. Starting another ceremony produces another transaction and can authorize a duplicate business action.
An integration may need a durable operation record and a business-level idempotency key. It may also need an endpoint that reports the result. External side effects depend on the downstream system's idempotency behavior. ByteBind's transcript definitions do not provide these recovery mechanisms.
Enforce the lease on the server
The session profile recommends a 30-second attestation window, a 10-second redemption window beginning at attestation, a 180-second lease, and renewal every 60 seconds.
The Authority returns a relative grant lifetime. The RP sets its deadline no later than:
grant_received_at + min(local_lease_duration, grant.expires_in)
Each host enforces its own deadlines. Relative durations avoid requiring agreement on absolute timestamps; local clock changes and restart behavior still need careful handling.
The browser renews on a fixed schedule without receiving the expiry. The RP checks the lease on protected requests even if the browser still holds the cookie. Leaving the network stops renewals, and the last accepted lease bounds the remaining access. Policy propagation can introduce additional delay before fresh attestations begin failing.
What needs review
The ceremony establishes continuity through possession of C, receipt of S on an authorized private connection, and successful redemption. Those secrets are transferable. The mechanism assumes trusted browser code and an uncompromised authorized device; it does not uniquely identify a browser process or prevent an authorized participant from relaying secrets. A copied session cookie also remains usable until the RP expires it.
The downloadable test vectors cover both profiles and request-encoding boundaries. I reproduced their MACs, derived keys, and encrypted responses against the reference implementation while preparing this article.
Review should also exercise cross-RP origin substitution, concurrent attestation and redemption, durable failure burns, changed request fields, and lost responses around application side effects.
The roadmap snapshot records the remaining deployment tests: real Tailscale identity responses and certificates, cross-node control traffic, macOS/BSD peer credentials, and browser local-network permissions. Independent security review remains outstanding.
The review needs to determine whether these bindings and deployment assumptions connect a public authorization decision to the intended private device. The specification contains the details.
