privatae-bastion/docs/ship-plans.md

# Ship plans: one approval for a whole ship

A ship is several action ops on several machines, in order: build and push
on one, move a tree and restart on another, roll a workload on a third. Your
device signs **one plan** listing every step, and each machine runs only its
own lines of it.

**What your device signs:**
- the pipeline, a version that only goes up, the commit being shipped, a
  nonce, and an expiry of at most four hours;
- each step: its machine, its op and that op's sha256, its params, the verbs
  it will run, the params it takes from an earlier step's receipt, and whether
  it may be undone;
- the key of every machine in it. The device fills these in from its own pins
  (`pin-machine`), never from your host. When you pin your device on a
  machine, the machine prints the exact `pin-machine` line to run on the
  device.

**Before signing, the device:**
- refuses a plan naming a machine it has not pinned;
- asks for your code when a plan runs root work, checks it against the
  factor enrolled on the device's own pairing (never one the ask names), and
  says in the plan that it did;
- keeps such a plan out of "approve all shown";
- shows every field as plain text: a plan whose params, inputs or verbs hold a
  control character, a line break or a Unicode direction mark is refused, so
  nothing in it can redraw or hide what you read.

**Each machine, before it runs a line, checks that:**
- the plan is signed by a device pinned there;
- it has not expired, and it is not older than a plan it already ran for that
  pipeline;
- it names this machine's own key for this machine;
- the line is for this machine, and has run fewer times than the plan
  allows (once, unless you approved retries). Its attempts run one at a
  time: the next only after the last one failed, never after one passed, and
  never after the step was undone. The machine keeps this record itself, and
  an attempt the bastion died in counts as failed. A tree or workload
  something else moved since the line's changes were read — while its
  program ran, or between two attempts — is left alone: the verb refuses
  it, so an undo can never take that other change back. Changes this
  bastion makes to one tree or workload, forward or undo, take turns;
  a change from outside is caught one command before the write;
- every line before it succeeded, shown by their signed receipts, so a check
  never runs before the step it checks;
- a root line comes with your code;
- the op it holds declares exactly the verbs the line showed you.

**Values that don't exist when you approve,** like the digest a build
produces, come from receipts. Each line ends in a receipt signed with the key
your device pinned for that machine, and the machine keeps it for your host
to read back (`op_plan_status`). A roll takes its digest only from a
successful earlier step of the same plan, at the plan's commit: the image the
plan's own build step reported, never one from another run. That rests on the
build op reporting truly, and that op is one you approved in the plan. The first roll on a machine with no
record of its live image says so on the device, and takes that image as its
starting point.

**Undo.** A step marked undoable is taken back once, to the state that
machine recorded before the step's first attempt. The machine records each
change before it makes it, so a retry, or a change the bastion died in the
middle of, is taken back too. An undo takes one of two signed receipts:
- a later step of the same plan failed its check (its apply ran, its verify
  or log check did not pass) on the last attempt the plan allows it, so no
  retry of it can still pass;
- the step's own latest attempt failed, and none of its attempts passed.

The tree or image goes back first; a unit the step restarted is restarted
after, on what was put back. A tree or workload that moved since is left
alone, and a file the machine keeps is never overwritten. Once undone, the
step never runs again.