Important concepts

A signed-in user creates a named dmt_… ticket. The CLI presents it with a public endpoint key and proof from the matching private key. The server atomically consumes the ticket, binds the machine entry to that endpoint, and returns a revocable dsm_… machine ticket. Machine scopes such as service_grants:issue originate on this enrollment ticket.

dmt_… currently has no automatic expiry. Create it when needed and use it promptly. A leak can enroll one endpoint until the ticket is used or revoked, but the ticket cannot be used again after successful enrollment.

An authorised browser creates a two-minute dst_… for one viewer and service. devsite connect generates an in-memory client endpoint and redeems that ticket for an eight-hour dss_… session bound to the client key. Each local TCP connection then exchanges the session for a fresh, three-minute, one-use stream ticket bound to both the client and daemon endpoints.

dst_… → dss_… → stream ticket → encrypted service stream

A dss_… is a reusable ticket. It can mint one stream ticket per TCP connection until it expires, is deleted, or loses current authorisation.

A requester creates a signed request containing an agr_… id, service keyword, temporary public endpoint, and expiry. A human or automated granting party resolves that keyword only among services its account may access. The server returns a dsp_… plan signed over the exact request, issuer credential, selected resource, endpoint, and expiries.

The plan is an approval ticket. It cannot open a stream. It binds the request id, service, issuer ticket, resource, requester endpoint, and expiries. The control plane verifies the request proof again. Applying the ticket returns a requester-bound dss_… lasting at most 15 minutes. The request id permits one grant. The resulting ticket can serve multiple TCP connections during that window.

Treat complete dmt_…, dsm_…, dst_…, and dss_… values, browser cookies, and live capabilities as secrets. The control plane stores hashes rather than plaintext bearer values. A dsp_… is decodable and cannot connect by itself, but should stay inside the approval workflow.

acct_…, res_…, machine_…, agr_…, handles, and endpoint ids are identifiers rather than tickets. Current access is rechecked when tickets are redeemed and capabilities are requested. Resource, sharing, session, and machine-ticket revocation narrow or terminate later use.

The CLI creates devsite-endpoint.key in the resolved dev.site config directory and preserves it across restarts. On Unix, private files are created with mode 0600. Its public half is written to devsite-endpoint.pub, registered with the control plane, and used as the daemon's Iroh endpoint id.

Version 0.6.0 uses devsite-endpoint.key and devsite-endpoint.pub. It does not read or move identity.key or identity.pub. Start version 0.5.1 once before the upgrade if these legacy files remain. Version 0.5.1 checks only the dev.site config directory. It does not scan another directory or the filesystem.

An ordinary connector's key exists only in memory, so copying its bound session to a different process is insufficient. Delegated access persists a temporary key at the requested --key path. The CLI creates it without overwriting an existing file and keeps it private on Unix. Share request.json, never requester.key. Delete the key after the request and granted connection finish.

The server uses one signing key for dsp_… plans and one-stream capabilities. Production can provide it through DEVSITE_SIGNING_KEY. A local server otherwise keeps capability_signing.key in its state directory. Login pins only its public half. The daemon refuses to start without that pin and rejects artifacts signed by another key.

devsite doctor reports when the server's published public key differs from the pinned value. Losing the private signing key prevents existing daemons from trusting new capabilities. Compromise permits forged authorization. Rotation therefore requires an explicit trust migration rather than a silent file change.

A machine endpoint key cannot make authenticated API calls without its dsm_…. The bearer ticket cannot satisfy endpoint proofs without the key. Possession of both grants the enrolled machine's full authority and scopes, so revoke the named machine entry and enroll a new endpoint if either pair may be compromised. A temporary client key matters only while a matching session or capability remains live.

1. The client opens a bidirectional stream on an authenticated QUIC connection.
2. It sends a Postcard Connect request containing one signed capability.
3. The daemon verifies signature, audience, authenticated client key, expiry, permission, resource, and one-use nonce.
4. The daemon connects to the resource's fixed loopback target.
5. It returns Connected or a deliberately coarse error.
6. After Connected, the remainder is the service's raw TCP byte stream.

Request and response frames start with a four-byte little-endian length followed by a Postcard payload. Length is checked before allocation and is capped at 4 MiB. Authorization failures collapse to Denied so a peer cannot distinguish a bad signature from an unknown or unshared resource.

Iroh QUIC encrypts the network and authenticates endpoint keys. ALPN separates and versions the application protocol. It does not grant service access: every stream still requires a server-signed capability addressed to the daemon and bound to the authenticated client. Relays carry encrypted QUIC traffic and do not terminate the dev.site application stream. The local daemon-to-service TCP hop uses whatever encryption the service protocol provides.

The /1 suffix is the compatibility boundary. An incompatible framing or semantic change should use a new ALPN. Today the client requests one dev.site ALPN and the daemon advertises one. There is no protocol fallback or multi-version negotiation. devsite doctor compares the server's reported daemon protocol with the CLI's compiled value.