torb login

torb login reads a token of a registry from standard input, asks the registry whether it holds, and stores it in the user's credentials.trb, where torb publish and the other commands that speak to the registry find it.

login stores a token of a registry for the machine's user, so that torb publish, torb owner and torb yank send it without a TORB_TOKEN in every shell. The token is one the registry gave - an account's first token, or one made with POST /api/1/tokens (tools/registry) - and login makes none itself.

Synopsis#

torb login                   Read a token from standard input, check it with the registry, store it
  --registry <url>           The registry, instead of the public one (packages.torb.dev)

What it does#

The registry is --registry <url>, read the way a registry line of project.trb reads a URL, else the public registry. A file: registry is a directory without accounts, and login refuses it in a sentence; an http: registry is refused too unless it is on this machine's loopback address, because a token never crosses a network in clear text.
The token is one line of standard input. On a terminal login asks for it first; a pipe works the same, which is how a script or a CI job logs in. There is no flag and no argument for it: a command line is visible to every user of the machine and lands in the shell's history.
The check. The token is sent to the registry with GET <registry>/api/1/tokens, in a header curl (or wget) reads from a file. A token the registry refuses - unknown, revoked, expired - is reported with the registry's words, and nothing is stored.
The file. The token is written into credentials.trb in the torb home - ~/.torb/credentials.trb, or %LOCALAPPDATA%\torb\credentials.trb on Windows - or into the file TORB_CREDENTIALS names. A second login to the same registry replaces its line; the other registries keep theirs.

$ torb login --registry https://packages.acme.test < token.txt
logged in to https://packages.acme.test/: the token is stored in /home/ada/.torb/credentials.trb

The file `credentials.trb`#

One token line a registry, the registry's URL as a registry line writes it and the token as value::

// The registry tokens of `torb login`, one line a registry: keep this file to yourself.

token "https://packages.torb.dev/", value: "torb_..."

Like config.trb, the file is a receiver script of literal lines that is read from its syntax tree and never evaluated, and it is strict: any other line, and a registry with two lines, is an error at its line - a message that never repeats a token. It is created empty with the mode 0600 (read and write for its owner alone) before the token goes into it. It is a file apart from config.trb so that config.trb can be shared, and it belongs to the user: a project never holds a token.

Which token a request sends#

TORB_TOKEN where it is set, else the stored token of the registry the request goes to, else - for torb publish in a CI job - trusted publishing. A stored token only goes to an https: registry, or to an http: one on the loopback address, and never to a mirror of config.trb: a mirror is asked for files and is never sent a token.

Pitfalls#

TORB_TOKEN wins. A stored token is not used where TORB_TOKEN is set and not blank, so a shell that exports an old one keeps sending it.

The token is shown as it is typed on a terminal: paste it where nobody looks over the shoulder, or pipe it from a file or a password manager.

Examples#

A token the registry does not know stores nothing:

$ echo torb_expired | torb login
error: https://packages.torb.dev/ refused the token (401): the token is unknown, expired or revoked. Nothing was stored

torb logout - removes the stored token again.
torb publish - sends it with a release.
torb owner and torb yank - send it to change an owner's members and to yank.
config.trb - the user's other file, which holds no secret.