On the Relay

The credentials a relay takes beside access tokens: a visitor's pass, an operator token, the passwords of tunnels and share links, and a share link's address.

A visitor's pass

What a visitor's browser holds once the relay has let them in to a tunnel that lets in only some people (lnk tunnel open --account).

  • Proves: this browser signed in as an account, at this tunnel's host.
  • Made by: the relay, from a visit access token: the visitor signs in to the account service, whose page posts the token to the relay in a form, never in a URL. The token is made for that relay and lasts a minute.
  • Held by: the visitor's browser, as the cookie __Host-link_signin of that host alone, HttpOnly, Secure, SameSite=Lax, holding the account's id and verified email and when it ends. The relay signs it with an HMAC key it makes at each start, and strips it from requests before they reach the app.
  • Travels: with each request to that tunnel's host.
  • Lasts: a day, and until the relay restarts. The relay reads no spec, so its [visitors] pass_life doesn't change it (Relay Spec).
  • Revoked: by taking the visitor off the tunnel's list: the relay checks the list again at every request.
  • May: visit that tunnel, as long as the visitor is on its list.

How the relay lets them in

The relay checks the token as it checks every access token, and that its nonce is the state of the sign-in it started, then lets them in if the token's acc, or its verified email, is on the tunnel's list. A one-time code carries the sign-in from the bare domain to the tunnel's host, in the browser that started it.

An operator token

A relay's own users, for a relay that runs without an account service, or beside one.

  • Proves: its holder is that user of that relay.
  • Made by: the relay's operator (link-relay admin), who gives it to the user.
  • Held by: the user, as LNK_TOKEN, never a flag; the relay keeps only its SHA-256, in its users file. A relay run without a users file takes its one local user's from LINK_TOKEN, never --token.
  • Travels: to that relay alone, in the connection's Hello.
  • Lasts: while it's in the users file.
  • Revoked: by the operator, taking it out of the file, or at once with link-relay admin user block <user>.
  • May: open tunnels and share links as that user, on that relay.

Not an identity: a secret its owner shares with whoever they choose, for one tunnel (lnk tunnel open --auth) or one share link (lnk bucket link create --auth).

  • Made by: the tunnel's or the link's owner.
  • Held by: the owner, and everyone they give it to. The relay keeps a share link's as a salted PBKDF2 hash, and a tunnel's for as long as the tunnel is open.
  • Travels: from the owner to lnk: --auth asks for it, or it's read from LNK_AUTH, never the command line. Then from lnk to the relay with the tunnel or the link; from a visitor as HTTP Basic.
  • Lasts: while the tunnel is open, or the link lives.
  • Revoked: by opening the tunnel again without it, or ending the link.
  • May: visit that tunnel, or open that link.

A share link's address is itself a credential: whoever has https://<user>.<domain>/b/<id>, and its password if it has one, gets its files. Its id is 24 random letters and digits. Its files are URLs your machine signs with your cloud's keys, which the relay keeps and hands to whoever opens the link, and which work until they expire, whatever happens to the link. A link lasts at most the relay's spec's [shares] max_life, 7 days unless its operator says less, S3's longest; lnk bucket link delete ends it at the relay (Share links).