Skip to content

Join a cloud with a code; start at login - #4

Merged
itrycodinganditsbad merged 12 commits into
mainfrom
join-codes
Oct 18, 2026
Merged

itrycodinganditsbad merged 12 commits into
mainfrom
join-codes

Conversation

@itrycodinganditsbad

@itrycodinganditsbad itrycodinganditsbad commented Oct 18, 2026 •

Copy link
Copy Markdown
Owner

A machine now joins a Craft Cloud with a code instead of a password. The first one uses an invite from the admin. Every later one uses an add-a-computer code from a machine that's already signed in. After that, the agent starts at every login by itself. Everything works from the command line; the desktop app will be a front end on the same calls.

Server

  • Migration 0004 adds invites and pairings. Codes are stored only as BLAKE3 hashes. An add-a-computer code has 8 characters, lasts 10 minutes and works once. An invite has 16 characters, lasts 7 days and works once. Both use Crockford base32, so a typed O counts as 0 and I or L as 1.
  • POST/GET/DELETE /api/v1/pairings require a device token. POST /api/v1/join needs no sign-in; it redeems the code and creates the device in one transaction, so two machines entering the same code at once get one device between them, not two.
  • A wrong, expired or used code all get the same invalid_code answer. Failed attempts are limited to 10 a minute per address, and each attempt is counted before the database is touched.
  • craft-cloud-server user invite <name> prints the join string and link; --revoke cancels the invite. An invite to a new account asks for its password while joining. An invite to an existing account asks for none.
  • GET /join/{code} is a plain page for anyone who opens the link in a browser.

Agent

  • New local API routes: join, pairings, devices, pause/resume/quit and autostart. They use the same Host, Origin and token checks as the existing routes.
  • Before spending a code, the agent checks the folder, the device name and the server. If setup still fails after the code is redeemed, it revokes the new device.
  • A pause survives a restart. Quit lets the pass in progress finish.
  • Start at login:
    • Windows: a Run value pointing at the new craft-cloud-agent-bg.exe, which opens no console and logs to run.log.
    • macOS: a LaunchAgent.
    • Linux: a systemd user unit, or an XDG autostart entry where systemd isn't running. An existing unit of the same name is adopted.
    • Only an agent using the default data folder may add, change or remove the entry.
  • New CLI commands: join, add-computer, devices, pause, resume, quit, autostart on|off.
  • craft-cloud-app gets the matching calls.

Dependencies

windows-registry 0.6.1 (MIT OR Apache-2.0), Windows only. Its dependencies were already in the lock file.

Testing

  • cargo xtask ci passes with Postgres and S3, 767 tests. The sync simulation passes for seeds 0–15999 with and without crashes, the network simulation for 0–4999, and the recents simulation for 0–9999.
  • On a Windows machine, clippy on the agent, app and proto crates passes with no warnings. The agent's unit tests and all its start-at-login tests pass there, including writing and removing the Run value under a throwaway registry key.
  • CI passes on Linux, Windows and the Postgres/S3 job. CI has no macOS runner, so the macOS start-at-login code has never been compiled; its plist is checked by a golden test that runs on every OS.

Left for later

  • The Windows background build loses what the agent prints with eprintln!, such as recents connection notes and lock warnings.
  • An agent that exits because another one already holds the data folder is restarted in a loop by launchd. Under systemd the unit gives up after a few quick restarts.
  • A failed attempt can be given back when a slow redeem crosses a limit window. That is at most one extra guess per window.

🤖 Generated with Claude Code

https://claude.ai/code/session_01RC1oqfy9kZznj94RjMojyz

itrycodinganditsbad and others added 12 commits October 18, 2026 20:54
Codes are Crockford base32: 8 characters for an add-a-computer code
(10 minutes), 16 for an invite (7 days). Input forgives case, O for 0,
I and L for 1, dashes and spaces; codes show in groups of four and are
hashed with BLAKE3. A join string is the server's address plus the code,
in the short form or the /join/ link form, with https:// assumed.

Adds the pairing and join bodies of the HTTP API and the invalid_code,
password_required and weak_password codes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RC1oqfy9kZznj94RjMojyz
Migration 0004 adds invites (one per account) and pairings (one per
device), keyed by the BLAKE3 hash of their code. A redeem works in one
transaction: a conditional DELETE ... RETURNING for an invite, or an
UPDATE ... WHERE used_by IS NULL ... RETURNING for a pairing, then the
new device, so two redeems of one code at once give one device. An
invite can create an account with no password, set when the invite is
redeemed. Revoking a device deletes the pairing it made.

The server maps the two new errors to invalid_code and
password_required.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RC1oqfy9kZznj94RjMojyz
A signed-in device makes, polls and cancels add-a-computer codes under
/api/v1/pairings. POST /api/v1/join redeems a code (or an invite) for a
new device and answers as a sign-in does. Every code that doesn't work
gets the same 404 invalid_code; an invite to a new account needs a
password (password_required, weak_password), hashed in the sign-in
slots. Failed redeems are limited to 10 a minute per client address;
successes don't count. GET /join/{code} is a fixed plain page that
never looks the code up.

The admin CLI gets user invite and user invite --revoke, and the config
an optional public_url for the join string it prints.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RC1oqfy9kZznj94RjMojyz
POST /v1/pause holds the sync passes, the long-poll, the folder watcher
and the live connection; the local API and apps' recents keep working,
and adds reach the server after POST /v1/resume, which runs a full pass
at once. The pause is kept in state.json, so a paused agent starts
paused, and shows as its own run state (paused_by_user), apart from a
pause that needs someone. POST /v1/quit lets the pass under way finish
and ends run; the local API now stops gracefully, so the answer to quit
still goes out.

Status gains an optional autostart field for later.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RC1oqfy9kZznj94RjMojyz
POST /v1/join parses a join string, checks everything it can here
first (the folder, the device name, what the server speaks), then
redeems the code and sets up the folder as a sign-in does; login and
join now share those steps. A failure after the code is spent removes
the new device again and says to make a new code. An untrusted server
certificate is told apart from an unreachable server, which names the
address tried.

The local API also makes, polls and cancels add-a-computer codes
(/v1/pairings) and lists and removes the account's computers
(/v1/devices), refusing to remove this one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RC1oqfy9kZznj94RjMojyz
craft-cloud-app gets the matching calls of the local API: join,
pairing, pairing_state, cancel_pairing, devices, remove_device, pause,
resume, quit and set_autostart, each documented as safe or not on a
UI thread.

The agent's CLI gets join (asking for a new account's password twice
only when the server needs one), add-computer (prints the join string,
waits for the other computer, cancels the code on Ctrl-C), pause,
resume, quit, devices and devices remove. join works with or without a
running agent, as login does.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RC1oqfy9kZznj94RjMojyz
The agent registers its own start-at-login entry: a Run value on
Windows that starts the new craft-cloud-agent-bg build (no console
window; it logs to run.log in the data folder, rotated at 10 MiB), a
launch agent on macOS, and on Linux a systemd user unit when the
session runs systemd (a hand-made unit of that name is rewritten) or an
XDG autostart entry otherwise. Paths are quoted and escaped per format.

POST /v1/autostart turns it on or off and Status.autostart says which;
signing out turns it off. The CLI gets autostart on|off and
join --autostart. Windows uses the windows-registry crate (MIT OR
Apache-2.0), Windows-only.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RC1oqfy9kZznj94RjMojyz
The local API's new calls and codes in live.md; join codes, the new
server calls, their error codes, migration 0004 and user invite in
sync.md; inviting someone and public_url in the README's server
section; the workspace map in AGENTS.md; the autostart golden files in
ATTRIBUTION.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RC1oqfy9kZznj94RjMojyz
Failed joins were counted only after the redeem, so tries sent at the
same moment all passed the check first: forty wrong codes in flight
from one address all reached the database. Now each try is counted up
front with allow() and given back with the new Limiter::refund() unless
it ended in invalid_code. Limiter::full() is gone, and with it a
limiter that never swept once it was full.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RC1oqfy9kZznj94RjMojyz
There is one start-at-login entry per user, but any agent could set,
replace or remove it: signing out of a spare data folder removed the
main agent's entry. Now only the agent whose data folder is the default
one (Roots::owns) touches it. Another one reports no autostart status,
is refused by /v1/autostart and `autostart on|off`, passes over
`join --autostart`, and leaves the entry alone when it signs out.
Entries therefore never carry --data-dir any more.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RC1oqfy9kZznj94RjMojyz
The hub closed its live connection without a time limit, on pause, on
stop and after a bad frame, and the run loop waited for the hub's
answer to a pause without one. On a half-open connection with a full
send buffer that could hold the loop (stops, quit, heartbeats) for as
long as the kernel's TCP timeout. The close now gives up after 5 s and
drops the connection, and the loop waits at most 10 s for the hub.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RC1oqfy9kZznj94RjMojyz
launchd threw away everything the agent printed, so a Mac had no log
to point a user at. The launch agent now names run.log in the data
folder as StandardOutPath and StandardErrorPath.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RC1oqfy9kZznj94RjMojyz
@itrycodinganditsbad
itrycodinganditsbad merged commit ba70f40 into main Oct 18, 2026
3 checks passed
@itrycodinganditsbad
itrycodinganditsbad deleted the join-codes branch October 21, 2026 00:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant