Principal
link-principal is who acts, or may, as one type: user:<id> or
service:<id>, as the account service's API names it. An access
token's subject (link-api, whose generated types are these), a role's
holder and a teammate's sender all name a principal with it, so they
can't disagree; link-api's test holds its grammar to the API's.
Its kinds
PrincipalKind is what comes before the first :, one of KINDS, and
there are two. A user is one person: you, or someone a connection
vouches for. A service is a program acting on its own: an agent, the
workload agent:<its ID>, acts as a service, which holds its roles.
Why only these two has the reasons.
What isn't one
Nothing else is a principal. A machine is where things run: its signer signs for its user, so a machine's access token names the user as its subject and the machine in a field of its own. A chat a connection keeps is a group that may message an agent, never one who acts. A webhook's caller acts as a service of its own, and a guest who holds a tunnel's password holds a capability, not a principal.
Its id
After the kind, an id of 1 to ID_MAX, 128, bytes: ASCII letters,
digits and ID_PUNCTUATION, ._:/-. It's opaque: a : or / in it
is its own, and Principal::id gives it back whole.
On the generic
A Principal is link-id's Id<PrincipalKind>, the generic every
stable ID rides
(Stable IDs): made
only by parsing or from a kind and an id, so every one is well formed,
and what isn't one, or isn't a kind, is NotOne, saying why.