Pairing · KalaReach

The first owner of a host is established locally, through the operating-system account you are logged in as. Subsequent devices are paired. You approve each new device with kr pair confirm on the machine that issued the invitation, and where the host already has an owner, an owner device confirms it in its own prompt too.

Two ways in

Paste a direct invitation: Add --direct to kr pair invite --owner (or --guest) and it draws a QR code in your terminal; with --json it prints the invitation as text instead of drawing it. The invitation contains the host’s endpoint and network configuration, a secret that can only be used once, and the grant that the host wants to give. It works on a local network with no lookup and no meeting service in the middle. On a computer the companion application reads the invitation from the clipboard. A phone can also scan the QR code with its camera or read it from a picture.
Type a ten-character code: It is shown as XXXX-XXX-XXX. The first four characters locate a temporary meeting record; the remaining six are the shared secret. You never type a full network address.

Issuing an invitation from the host

$ kr pair invite --owner
# A host that has an owner first waits for an owner device to confirm. A host with none asks "Type pair to issue the invitation:".
Invitation 0b8a1c3e-4d5f-4a6b-8c7d-9e0f1a2b3c4d, open for 4 minutes.
Code: QFM4-7KD-BNP  at https://reach.kala.to
To reserve a code at another rendezvous origin, cancel this invitation with kr pair cancel 0b8a1c3e-4d5f-4a6b-8c7d-9e0f1a2b3c4d, then run kr pair invite again with --origin <address>.
Enter the code on the new device, or scan this QR code with it:
# The QR code is drawn here.
When the new device shows its verification value, approve it with:
  kr pair confirm 0b8a1c3e-4d5f-4a6b-8c7d-9e0f1a2b3c4d

What the code is, and is not

These invitations expire five minutes after being issued and are not a permanent name for your computer. They are one-time use, and are consumed whether successfully used, denied, cancelled or expired. The Invitation line that kr pair invite prints says how long the invitation has left at that moment: whole minutes, rounded down (“open for 4 minutes”), and seconds in the last minute (“open for 45 seconds”), so an invitation issued a moment ago reads 4 minutes.
The six secret characters are drawn uniformly from the Base58 alphabet, giving about 35 bits. The host allows five failed confirmation tags per invitation, so guessing succeeds against one host with probability around 1.3 in 10 billion before you are asked to approve anything. That figure assumes the password exchange prevents guessing offline, and it bounds one host: reusing a code across several clients multiplies the attempts.
Malformed messages, abandoned attempts and local configuration failures consume rate and slot budgets, not that allowance, because they produce no confirmation result.
Those six characters never enter a service request, a URL, a log or an analytics event.
Entry accepts spaces and hyphens and preserves case. The input control turns off autocapitalisation and autocorrection, because the code is case-sensitive.

The meeting service sees very little

For code pairing, the client sends only the first four characters to the meeting origin, which returns an invitation identifier and an advertised expiry. Nothing from that service is trusted until the two devices have proved the shared secret to each other. The service never receives a readable host address or key bundle, and it cannot create a grant.

The meeting origin is always shown, the default included, both where you enter a code and on the machine that issued it, and you can change it before an attempt starts. If an invitation you paste names a different meeting origin from the one you are set to use, the application asks you to confirm that service, named in full, before it contacts it.

Owner approval

Proving the secret locks the invitation to one candidate and cancels the others. It does not grant anything. Both devices then display the same short verification value, so you can see you are approving the device in front of you. The host commits the device record and its grant only after you confirm on the issuing device, and the device cannot enlarge the grant it was offered. A denial, expiry, cancellation or five failed confirmations consumes the invitation; a new one needs another deliberate action from you.

What pairing gives a device

A paired device gets the grant you approved and nothing more. Adding a device to a KalaReach account does not pair it with any host and gives it no decryption keys. kr pair invite --owner pairs another computer of yours with every right over the host, until you revoke it.

You can pair a device as a guest using kr pair invite --guest. A guest pairing will by default expire after one day. You can specify the number of minutes to be valid (up to 30 days) as kr pair invite --guest 60. Guest devices will not have access to any of your sessions until you share a session with them using kr share invite, which takes the session and --to <device>. Shared sessions will be shared with the role viewer, which lets the device see the agent’s conversation and questions but not the terminal (you can name another role using --role), and will expire after one hour or when the pairing expires, whichever comes first (you can change the time using --for). Note that you can not give a right to someone that you don’t have yourself. A share made with --live includes the terminal, as it is when the device opens the session, and a phone that has accepted a share opens that session in its companion application.

Revoking

kr device list shows what is paired and kr device revoke removes it, under local owner authority. Revocation stops future access. Personal owner grants stay valid until you revoke them, so your own access never depends on a service being reachable.