torb owner

owner manages who may publish under an owner of a registry - a person's own name or an organisation such as acme. A member is an owner, who may change the members, or a publisher, who may publish, yank and nothing more. The registry keeps the members; owner speaks to its API.

Synopsis#

torb owner list <owner>             The kind of the owner, where it publishes, and its members and their roles
torb owner add <owner> <account>    Add a member, or change its role
  --role <role>                     publisher (the default) or owner
torb owner remove <owner> <account> Remove a member
  --code <code>                     add and remove: a code of the account's second factor (or TORB_CODE)
  --step-up                         add and remove: approve the change with a passkey at the account page instead
  --registry <url>                  The registry, instead of the one the owner is bound to
  --project <directory>             The project whose registry lines bind the owner (default: the working directory's)

What it does#

1. The registry is --registry <url>, else the one the owner is bound to by a registry line of the project at or above the working directory (or --project), else the public registry. A file: registry is a directory without accounts, and owner refuses it in a sentence.

2. list asks GET <registry>/api/1/owners/<owner>, which anyone may, and sends no token. It prints the owner's kind - person or organisation - and the domains it proved (verified domains acme.com, acme.org where it proved several), a line with the registry it publishes at instead where it does (torb add), then its members:

   $ torb owner list acme
   acme (organisation, verified domain acme.com)
     publishes at https://packages.acme.com, not at this registry
     ada                     owner

3. add and remove send the token a request to the registry sends anyway - TORB_TOKEN, else the one torb login stored - with PUT or DELETE of /api/1/owners/<owner>/members/<account>. Only an owner of the owner may, and the registry never removes the last one. add of a member that is there already changes its role.

4. The second factor. Once the account has an authenticator app or a passkey, the registry asks for a code with each change: --code, else TORB_CODE, goes along in the Torb-Code header - an app code, a recovery code, or step-up:<secret> from a passkey's step-up, which --step-up gets (A passkey).

$ torb owner add acme bob
bob is a member of acme as publisher
acme (organisation)
  ada                     owner
  bob                     publisher

Every request goes through curl (or wget), which reads the headers - the token among them - from a file written for the user alone: the token is never an argument another user of the machine could list.

A passkey#

A passkey cannot sign a request from a terminal, so --step-up asks the registry for a step-up (POST /api/1/step-up), prints its user code and the account page, and waits for a line on standard input. The person opens the page, types the code and approves it with the passkey, then presses Enter; owner sends the grant as Torb-Code: step-up:<secret> with the one change, and the registry uses it up.

$ torb owner add acme bob --step-up
approve this change with a passkey: enter the code 7KQ2M9XD at https://packages.torb.dev/account
Press Enter once it is approved:
bob is a member of acme as publisher
acme (organisation)
  ada                     owner
  bob                     publisher

The prompt goes to standard error, and only on a terminal; the line may come from a pipe as well. The secret, the grant's id and its expiry are never printed, and the secret goes through the header file like the token; the registry keeps only its SHA-256. A grant lives five minutes - the registry times it, owner does not. Standard input that ends without a line sends nothing, exits with 1 and leaves the grant open until it expires. --step-up ignores TORB_CODE. --step-up with --code, or with list, is a usage error (exit 2).

Pitfalls#

A refusal is the registry's. <url> refused to add bob to acme (403): ... carries the registry's words: not an owner of acme, an account that does not exist, a code that is missing or wrong, a step-up that was not approved or has expired, an account without a passkey to approve one with. A refusal ends with the exit code 1, a command written wrong - a missing name, a role that is neither owner nor publisher - with 2.

Enter before the approval is too early. The change goes out with a grant that is not approved yet, the registry refuses it, and the change needs a new --step-up; the early grant stays open until it expires, and an account may have three of them waiting.

A code is used up. An app code, a recovery code or a step-up goes with one change; TORB_CODE exported in a shell is sent again with the next one, which the registry then refuses.

Examples#

Make a member an owner, with a code of the authenticator app:

$ torb owner add acme bob --role owner --code 123456
bob is a member of acme as owner
acme (organisation)
  ada                     owner
  bob                     owner

Related#

• torb login - stores the token add and remove send.
• torb yank - what a member may do to a published version.
• torb publish - what a member publishes.