Use the uuBright relay

The uuBright relay is a hosted copy of the encrypted relay. If you have a uuBright account, you can reach your Mac or server from your phone without deploying a relay yourself. It carries the same end-to-end encrypted traffic as any other deployment of the relay: requests, events and files are encrypted between your phone and your computer, so by design the relay doesn't see your tasks, transcripts, model keys or Git credentials. The operator can see connection metadata and, for iPhone notifications, your phone's APNs token. Whoever controls the relay's address also serves the phone app's code, which handles plaintext on the phone. See the threat model.

Accounts are invitation-only for now. The operator creates them; there is no sign-up or password reset yet.

#On a Mac (desktop app)

  1. Open uuBright Console → Connect your phone… and choose Use uuBright relay.
  2. Enter your uuBright username and password and click Sign in. The app keeps a revocable host token in your macOS Keychain. Your password is not stored.
  3. The app restarts its local service. It shows **Connected as <username>** once the relay accepts this Mac. The app then restarts the service once more without the token, so tasks on this Mac can't read it from the service settings. The token stays in the Keychain, and the app hands it back to the service only if the relay asks this Mac to register again, for example after its host key changes.
  4. Choose Connect your phone and type the code on your phone under Add a computer (how).

Sign out revokes the token and disconnects this Mac from the relay. Choosing Use my own relay switches back to a self-hosted relay URL and registration secret. Manage sign-ins… asks for your password and lists every host signed in to your account, so you can revoke old ones.

#On a server

SHELL
npm run relay -- login --username alice    # prompts for the password
npm run relay -- status
npm run relay -- tokens                    # lists every sign-in; asks for the password
npm run relay -- tokens --revoke <id>      # revokes another host's sign-in
npm run relay -- logout                    # revokes the token

login writes relay-account.json (mode 0600) to the data directory. Restart uuBright Console afterwards; the relay turns on by itself, so CCR_CLOUD_RELAY_URL is not needed. For scripts, pipe the password with --password-stdin. Never pass it as an argument.

If CCR_CLOUD_RELAY_URL names a different relay, that relay is used with CCR_CLOUD_RELAY_REGISTRATION_SECRET, and the uuBright sign-in is ignored. GET /api/relay/status reports which relay is in use, whether the host is connected, the account state (ok, signed_out, refused or unreachable), and why the relay last closed the host (closeReason, for example suspended or maintenance).

#What your account controls

On first connection, a host binds to the account that signed it in. Only that account can bind it again, for example after the host key changes. Each account has a plan:

LimitDefaultApplies to
Hosts3Hosts bound to the account
Phones10 per hostEnrolled phones plus unexpired pairing codes; Connect your phone refuses once a host is full, and a code redeemed after the limit is reached fails. Until the relay has confirmed the plan after a host starts, it waits (503).
Connected clients16 per hostPhones and pairing sessions at once
Bandwidth2 MiB/s per connectionSame budget as a self-hosted relay
Data20 GiB per monthBytes relayed for all of the account's hosts and phones in a calendar month (UTC), plus each file a phone downloads through the relay. Once it is used up, open phone connections are closed and new ones and pairings are refused until the 1st; your hosts stay connected. GET /account/me reports usage. Direct access is never counted.
File storage5 GiB per dayEncrypted files your hosts uploaded in the last 24 hours, at most 500 (files over the relay). When it is full, opening another file says so until older uploads age out.

When a phone pairs, through the relay or directly, the host sends a Web Push notice to your other devices with notifications turned on: “New device paired”. If you didn't pair it, remove it under Server settings → Devices → Paired phones.

The phone app explains each refusal: the monthly data is used up, the account is paused by the operator, or the relay is down for maintenance. Sign-in shows the same messages. Signing out, or revoking the token another way, unbinds the hosts it bound and closes their relay connections at once. If the relay can't confirm that yet, the request fails with unbind_incomplete and the close is retried until it succeeds. If you remove a host from your account while it is still running and signed in, it binds again on its next connection. Sign out on that host to stop it.

A bound host reconnects with its own key, and only with the key the account bound most recently. It needs a registration proof only to bind for the first time or after a key change. If a proof request fails, the host reconnects without one. A relay that no longer holds the binding closes a host without a proof with 4412 (registration required); GET /api/relay/status then reports registered: false, and in bound mode account.state: "token_needed", so the app hands the token back.

When a host leaves an account (sign out, token revoked, host removed, password changed), its host ID stays reserved for that account for 30 days. Another account can bind it in that time only from the same machine: the host signs its proof request with its own key, which the desktop app and npm run relay -- login do automatically.

#Files over the relay

When a phone opens a deliverable through the relay (an image, a video, a PDF, a document, or a slides deck with the files in its folder), files up to 2 MiB travel inside the end-to-end encrypted channel. They work without file storage. For larger files, the Mac encrypts the file and the phone downloads it from the relay's file storage (Cloudflare R2):

  1. The Mac seals the file with a new random AES-256-GCM key, in 1 MiB chunks (format). A deck is sealed as one bundle with every file in its own folder.
  2. It asks the relay for a one-time upload address under a random name, signing the request with its own relay key, and uploads only the ciphertext.
  3. It sends the key, the object name and a hash to the phone inside the end-to-end encrypted channel. The relay and R2 don't see the key.
  4. The phone downloads the ciphertext with an address that works for 10 minutes, decrypts it chunk by chunk, checks the hash and shows the file from memory. If the address has expired, the phone asks the Mac for a fresh one.

Opening the same unchanged file again within the day reuses the upload. Files are deleted from storage 24 hours after upload. A deck runs in a sandbox with no access to the phone app's storage or keys, as it does over direct access. Videos download completely before they play, and the phone holds the whole file in memory while it decrypts it, so the relay opens files up to 256 MiB (a deck with its folder counted together). Larger files say so and open over direct access. The Mac must be awake to send a small file or upload a larger one; once uploaded, the phone can download a larger file even if the Mac goes to sleep.

A self-hosted relay has no file storage. Its phones open files up to 2 MiB through the channel; larger files show their name and size and ask the owner to open them on the computer directly. Live screen view and browser takeover don't go through the relay yet.

#Threat model

Protected:

  • Content. Every request, response and event is end-to-end encrypted between the phone and the host (protocol). The relay, Cloudflare and uubright.com see routing metadata, not content. Not protected below lists what they can see and the trust you place in the phone app's code.
  • Files at rest. Files opened through the relay rest in R2 for up to 24 hours, encrypted with a key that exists only on the host and the phone. Each file has its own key, and the chunks are authenticated, so storage can't read, alter, reorder or cut short a file without the phone noticing. Object names are random under a per-account prefix keyed with a relay secret; they don't carry file or user names, and an account's objects can be read only through addresses its own hosts request.
  • Host takeover by another account. A host joins the relay only with a registration proof. The account API issues a proof only to the account that already holds that host ID, or for an unbound ID. Account B cannot get a proof for account A's host, cannot unbind it, and cannot see that it exists. Proofs are bound to one host ID and key, expire within five minutes, and cannot be replayed to rebind a host.
  • No shared secret on hosts. The registration secret stays in the Worker. Hosts hold only their own account's token, and send it only to the relay that issued it. Pointing CCR_CLOUD_RELAY_URL at another relay uses that relay's registration secret instead.
  • Password guessing. Passwords are stored as scrypt hashes (N=16384, r=8, p=1) with a per-user random salt and compared in constant time. Unknown usernames cost the same work as known ones and get the same answer. Attempts are reserved before the password check; a correct password refunds the username-wide reservation. Limits are 20 per IP prefix every 15 minutes and 5 per username from one IP prefix every 15 minutes, with that pair's window doubling after each lockout up to a day. A new prefix can make up to 200 wrong guesses per username in 24 hours across all networks; one IPv6 /48 is also limited to 100 guesses per username in 24 hours. IPv6 per-prefix limits use /64, so rotating addresses within one /64 does not help. Prefixes that signed in successfully within the last 90 days skip the username-wide and /48 ceilings. A live host token skips them too, but has its own 10-attempt hourly budget. The edge also allows 60 account API requests per IP prefix per minute.
  • Token theft from storage. Tokens are 256-bit random values. The relay stores only their SHA-256 hashes. uuBright Console is designed not to log tokens, put them in a URL or pass them on a command line. Session tokens last 10 minutes and can be exchanged once for a host token. Host tokens last a year, can be revoked, and become invalid when the operator changes the account's password or removes the account.

Not protected:

  • Metadata. Cloudflare and the operator can see IP addresses, host IDs, connection times, traffic sizes and which account owns which host IDs. For files opened through the relay they also see each file's encrypted size (a deck's whole folder together) and when it was uploaded and downloaded.
  • The phone app's code. relay.uubright.com serves the phone app. Whoever controls that origin could serve malicious JavaScript that reads plaintext on the phone. If you need to remove that trust, use direct access through your own network or VPN.
  • A stolen host token. A host token works only for the one host it first registered. With it, someone can fetch registration proofs for that host ID and remove that host or the token itself. They can't bind other hosts, see or touch your other hosts, or list or revoke your other sign-ins: those need a fresh password sign-in. They still cannot read the host's traffic or pair phones to it. On a Mac, the token is removed from the service settings once the host is registered. Revoke a token with Sign out, Manage sign-ins…, npm run relay -- tokens --revoke <id>, or npm run relay -- logout.
  • Availability. The relay can refuse or drop connections. Five or fifty wrong logins elsewhere do not block a correct password from a new prefix; the higher 200-failure ceiling makes a username-wide lockout costly. A prefix you used successfully in the last 90 days, or a live host token with its own budget, still lets you sign in after strangers exhaust that ceiling. Guessing from your own prefix can temporarily block that prefix, with increasing backoff. A host ID squatted before its first registration can't be bound (host IDs are random 128-bit values that the relay only learns at registration). Hosts keep connecting for up to 10 minutes if the account service is overloaded or down.
  • Account change timing. If the operator removes or suspends an account or changes its password, sign-ins and API calls stop at once, and new relay connections stop within a minute. Uploading the change restarts the relay, so open connections drop and reconnect, and are then refused. An open host connection that survives ends within a minute of traffic when the account is suspended.

#Account API

All routes are HTTPS-only JSON under https://relay.uubright.com/account/. They send cache-control: no-store, accept bodies up to 4 KiB, and take tokens only in Authorization: Bearer.

RouteTokenResult
POST /account/login {username, password}none{username, token, expiresAt}, a 10-minute session token
POST /account/host-token {label?}session (consumed){token, id, label, expiresAt}
POST /account/register-proof {hostId, publicKey, possession?}host, for its own host{hostId, registration: {exp, proof}, plan}; binds an unbound host. possession is a host capability signed by publicKey with audience <origin>#register; it lets a released host ID move to another account during its cooldown
GET /account/mesession or host{username, plan, hosts, usage: {month, bytes}, token}; a host token counts only its own host
GET /account/hostssession or host{hosts: [{hostId, boundAt, lastProofAt, current}]}; a host token sees only its own host
DELETE /account/hosts/:hostIdsession, or host for its own hostUnbinds the host and closes it on the relay
GET /account/host-tokenssession{tokens: [{id, label, createdAt, expiresAt, hostId?}]}
DELETE /account/host-tokens/:idsession, or host for itselfRevokes the token and unbinds the hosts it bound
POST /account/logoutsession or hostRevokes the presented token the same way

Hosts ask for file storage addresses with two more routes, under /artifacts/. They take no bearer token: the body carries {hostId, publicKey, capability}, where the capability is signed by the host's relay key with audience <origin>#artifacts and lasts at most a minute. The relay accepts it only from the key the account bound to that host, so it works after a Mac removes its token, and it can't admit a relay socket or fetch a registration proof.

RouteBodyResult
POST /artifacts/uploadsize, the sealed size in bytes{object, url, urlExpiresAt, expiresAt}; url is a presigned R2 PUT for exactly size bytes, valid for an hour. 413 artifact_too_large above the 256 MiB file limit, 413 artifact_quota past the account's file storage, 403 data_cap once the month's data is used
POST /artifacts/downloadobject{url, urlExpiresAt, size, expiresAt}; url is a presigned GET, valid for 10 minutes. 404 for an object of another account or none, 410 expired after 24 hours. Counts size against the month's data

A relay without file storage answers 404 {error: "artifacts_unavailable"}.

Errors are {error} with 400, 401 (unauthorized, invalid_credentials), 403 (host_unavailable, host_limit, wrong_token, account_suspended, token_scope for a host token used on another host, session_required for account-wide actions with a host token), 404, 409 (too_many_host_tokens), 413, 415, 429 (with Retry-After), 502 or 503 (maintenance comes with a message). Plans include monthlyGB and artifactGB.

A revocation (logout, token revoke or host delete) returns 502 unbind_incomplete with pending: [hostId…] when the relay hasn't confirmed closing those hosts yet. The token and binding are already gone, so no new connection or proof is possible, but an open host connection lasts until the unbind lands. The account service retries every 30 seconds and on its next request. npm run relay -- logout then deletes the dead token, reports the pending disconnect and exits 1. The account list sits behind this API, so OAuth sign-in can replace the fixed list later without changing hosts.