What happens when you tap a card

Every change Tealhand makes to a computer starts as a card on your phone and ends as a line in that computer’s journal. This page follows one action, step by step, and says where each safety rule applies. The example is “Shut down Studio PC”.

1. The action list

There is one list of actions, in the tealhand-actions crate: show status, add a rule, sleep, shut down, rename, list a folder, download a link, and so on (Actions). Each has a fixed risk (read, change, lower protection or destructive), a rule for whether it needs your fingerprint, and a rule for where it may start. The risk comes from the list, never from a model.

You start an action by tapping a button, or by asking in the ask box. In the ask box, your sentence is turned into one action from the list, either by matching your words on the phone or by the optional planner. Whichever way, only an action from the list can come out, the phone checks its parameters again, and an action that chat may not start (a destructive one, or one that only the computer itself may run) is refused. The app’s screens cannot pick where an action came from: the code that makes the card sets that itself.

2. The card

The phone builds a confirmation card from the checked action. The words on the card are written by code from the action, never by a model: a title, one plain sentence that says what will happen and on which computer, and one button. A later time shows only when the action doesn’t happen now, and an undo line only when it matters: removing a device, forgetting a phone, shutting down, and deleting or replacing a file. The card has no “What”, “When”, “On” or “Undo” labels. For shutdown it reads “Shut down Studio PC”, one sentence, “In 60 seconds”, and how to cancel during the notice. Putting a computer to sleep happens now and needs no undo line, so its card is only the title, the sentence and the button.

A card is the only way to send an action that changes something. Nothing is signed or sent before you tap its button. A card works once, and it expires after 5 minutes.

A card also shows the part of the action an attacker would want to hide. A download card shows the link’s scheme and host in plain ASCII letters first, so a look-alike domain looks different. A file card names the computer, the shared folder, the file and its size.

3. Two keys sign

You tap the button. The phone asks its secure hardware to sign:

• The device key signs every command, without a prompt.
• The presence key signs only for actions that need you there, and only after your fingerprint or PIN. The key itself refuses to sign without it, so no app can skip the prompt. Shut down needs it. A status request doesn’t.

The signed command holds who sent it, which computer it is for, the action, 16 random bytes (a nonce), and a start and end time. The phone gives it a lifetime of 60 seconds.

4. It travels on ctl/1

The command goes to the computer in one message on the tealhand/ctl/1 connection. The connection is direct on your network, or through your relay when there is no direct path. The connection itself is encrypted to the computer’s key, and the phone refuses to talk to any other key. The relay only sees bytes it can’t read.

5. The computer decides

Tealhand Host does not trust the connection, the card or the phone’s app. It checks, in this order, and stops at the first failure:

1. The connection’s sender is a phone on the signed device list, and not expired.
2. The signatures are valid, checked before the command is read, with the key the connection proved.
3. The command is well formed, and was issued by this phone for this computer.
4. It is inside its time window and was issued after this Host started.
5. Its nonce has not been seen before, so a copied command can’t run twice.

Only then does it read the action and check it again: the parameters, where it may come from, whether it needed a fingerprint and had one, and whether remote control is on. With remote control off, a phone can only read status and cancel; everything else is refused. The exact order and the errors are on How commands are signed.

For shutdown, the Host also asks the power helper whether another user is signed in, and starts a 60-second notice that can be cancelled from the phone or at the computer. (The helper is not built yet, so today a shutdown is refused.)

6. The answer, and the journal

The Host sends one answer: done, or one error code. The phone turns the code into a sentence with the computer’s name in it, such as “Someone else is signed in on Studio PC, so it did nothing.” Error codes lists them all.

The Host also writes one plain line to its journal: when, who (a device name, “this computer”, or “rule”), what, and how it was allowed (signed command, fingerprint, or refused and why). The journal never holds file contents, keys, program names or file names. It is kept 30 days, and a flood of the same refusal stays one line with a count.

Where each safety rule applies

Step	Rule
The action list and the card	1: the AI only proposes from the list, and a card always comes first
The presence key	2: risky actions need your fingerprint, and destructive ones never come from chat
The computer’s checks	4: only commands signed by a device on your list run (your phone’s key, or one of your computers)
Texts from the computer, such as program names	3: shown as data, cleaned, and never a command

The planner, and the relay, are not in this path at all except as a place to turn a sentence into an action and as a place bytes pass through. Neither holds a key.