application_keys

Application keys: what the companion apps sign in with, and the built-in administrator's way into the web app.

A key is a secret a signed-in web user makes for the browser extension or the mobile app, ssk_<id>_<secret>@<host>:<port>, the server's address after the @, shown once; the app reads the address and the server ignores it. The shared store keeps the hash alone, in cluster/application_keys.yml, so a key works on every node of a cluster and the store holds no secret. The record of a key names its user, a name the user gave it, when it was made and when it expires, when and from which client it was last used. security.verify_token takes a key as a bearer on the plain lane; what a key may do is what its user may do.

What an administrator sets, through the users' and groups' settings (user_manager):

• application_keys, whether the user may make and use keys at all.
• application_key_clients, which of the companion apps may use them, by the name each client gives itself in CLIENT_HEADER: chrome, firefox, android, ios, or other for anything else. The apps say who they are and nothing checks them; it is a convenience, not a lock.
• The apps reach the server under /companion/: the same pages and API, a prefix a reverse proxy that signs users in lets through, where security.verify_token takes a key and nothing else, and where the web sign-in and handshake routes answer 404.
• application_key_days, the longest a key may live; -1 lets a key never expire, the default.
• application_key_dormant_hours and application_key_follow_sign_in, the dormancy rules: a key sleeps when its user's last web sign-in is older than the hours, or, with the switch, as soon as that sign-in has ended by the provider's or the proxy's clock. A dormant key answers dormant, and the app sends its user to the web app, whose sign-in wakes the keys (user_manager.note_web_sign_in).

The built-in administrator admin (user_manager.ADMIN), who has no identity provider, signs in to the web app with one of their own keys, the root key (web_sign_in): the first start generates one and writes it to root_key_path for the administrator to copy and delete, or SEALSKIN_ROOT_KEY names it. Wrong keys at the web, and wrong bearers of any shape but ssk_, which could be a guess at the environment's key, are counted per address, five a minute, which bounds guessing.