Administering a hub

Administrator profiles, accounts, invitations and scopes

Chapter 31 of 34Current for Gritpack 1.2.63Source: docs/guide/31-administering-a-hub.md

Someone on a team has to decide who may log in to its private hub, and who may publish under which names. That person is the hub's administrator. This chapter is for them. It covers the administrator's connection, accounts, invitations and scopes. The hub itself (the server, its storage, its backups) is run for you by Frogfish, so none of that appears here: you look after the people and the names, not the machine.

What you will be able to do

  • Save your administrator connection once, and switch between hubs.
  • Add accounts and invite people, with a code or a download link.
  • Suspend, reactivate and delete accounts.
  • Give a scope to an account, look scopes up, and take them away.

Two kinds of credential

An ordinary login (from gritpack login) lets an account search, install and publish. It cannot manage the hub. Administration uses a separate administrator certificate, issued for the hub's management address, which is different from the address packages come from. The hub accepts the two from different authorities, so a publishing credential can never be used to administer, however it was obtained.

When your hub is set up, Frogfish gives the administrator:

ItemWhat it is
the management addresshost:port for administration, for example packages.example.com:7444
admin.pemthe administrator certificate; not secret by itself
admin-key.pemits private key; secret: keep it as you would a password
a CA filethe certificate authority that vouches for the hub

Every gritpack admin command takes these four as --hub, --cert, --key and --ca. Typing them each time is tedious, so save them as a profile.

Administrator profiles

gritpack admin profile add saves the four under a name:

$ gritpack admin profile add team --hub packages.example.com:7444 \
    --cert admin.pem --key admin-key.pem --ca server-ca.pem
saved administrator profile team (the default) in ~/.frogfish/gritpack/admin.toml

The first profile becomes the default, so from now on gritpack admin ... needs no connection flags at all. The profile records where the files are; it does not copy them. Keep admin-key.pem where it is, readable only by you.

With more than one hub, add a profile for each and choose between them:

$ gritpack admin profile list
  other  packages.example.com:7444  cert=.../admin.pem
* team   packages.example.com:7444  cert=.../admin.pem
$ gritpack admin profile use other
administrator commands now use other by default
$ gritpack admin user list --profile team
...
$ gritpack admin profile remove other
removed administrator profile other; its certificate and key files are untouched

The * marks the default. --profile on any admin command picks one for that command. A flag given on the command line wins over the profile, so --hub with a different address still works for a one-off.

If you remove the default profile, no profile is the default any more, and admin commands ask for connection flags until you run admin profile use again.

Administrator profiles live in ~/.frogfish/gritpack/admin.toml, apart from your logins in config.toml. GRITPACK_ADMIN_CONFIG points at another file, and GRITPACK_ADMIN_PROFILE chooses a profile. Without any profile, the variables GRITPACK_MANAGEMENT_SERVER, GRITPACK_ADMIN_CERT, GRITPACK_ADMIN_KEY and GRITPACK_CA supply the connection.

Careful. Anyone with your administrator key can add accounts, give away scopes and hide packages on your hub. Do not put it in a shared folder, a repository or a CI secret that pull requests can read. If it leaks, ask Frogfish to replace it.

Accounts

An account is an email address. It exists on the hub before its owner ever logs in:

$ gritpack admin user add sam@example.com
account=01a1e867-b1f6-7c20-a6ad-fd28f53e0615 email=sam@example.com

Adding an account does not let anyone in. For that, the person needs an invitation.

Inviting someone

$ gritpack admin user invite sam@example.com
invitation=01a1e867-b267-75b1-9444-c2ca310ec7dc account=01a1e867-b1f6-7c20-a6ad-fd28f53e0615 expires_at=1794986872 enrollment_code=E770-0DFB-80CB-4F19-A197-2417

Send the person the enrollment_code and your hub's address. They run:

gritpack login sam@example.com --hub packages.example.com --code E770-0DFB-80CB-4F19-A197-2417

Logging in walks through it from their side. The code:

  • works once, and only together with the invited email address;
  • expires after 24 hours (expires_at is a Unix time);
  • is not stored on the hub, only a digest of it, so even the hub cannot show it to you again. If it is lost, invite again.

Send it by a channel you trust. Inviting again does not cancel an earlier invitation; revoke one you no longer want (below).

People renew their login every 30 days with gritpack auth renew, and that also needs a fresh code. Expect to invite each person once a month. An account whose login has expired is invited the same way as a new one.

An invitation as a link

Instead of a code, an invitation can be a link to a download that installs Gritpack if needed and logs the person in with one click. Give the hub's public enrollment and package addresses:

$ gritpack admin user invite kim@example.com --download \
    --enrollment-hub packages.example.com:7445 --package-hub packages.example.com:443
invitation=01a1e868-2a81-7592-a3a5-05f43591beb1 account=01a1e868-2a01-7272-abd4-9bce784b9037 expires_at=1794986903 link=https://get.gritpack.org/i/1NP3Z0QZ7X

The link's last part is the code, ten characters long. The page it opens offers a Mac download and, for Linux and Mac terminals, a one-line install that carries the code. The person sees which hub and which email they are joining before anything happens. The link works once and expires with the invitation. --title names the download ("Join ..." by default), --invitee-profile names the login profile it creates, and --download-hub chooses the hub whose pages serve it (get.gritpack.org by default). Installers and download links explains the download itself.

Careful. Links are served by get.gritpack.org for every private hub that Frogfish runs. Check with Frogfish that yours is connected before you send one; a link the public hub cannot look up shows as not found.

Revoking an invitation

An invitation that has not been used can be cancelled by its ID, the invitation= value:

$ gritpack admin invitation revoke 01a1e867-d27b-71c1-8bea-7a07c9a7b53e
revoked invitation=01a1e867-d27b-71c1-8bea-7a07c9a7b53e account=01a1e867-b1f6-7c20-a6ad-fd28f53e0615 revoked_at=1794900487

Its code then fails at login with an authentication error (exit 3), exactly like a wrong code, so the person learns nothing about why.

Looking accounts up

$ gritpack admin user list
01a1e860-95df-7c60-bbe1-5db0fd349f05 ada@example.com status=Active
01a1e865-dba3-7352-9217-40bfb4ff47cb bea@example.com status=Active
01a1e865-dc86-7153-9bdf-ef2283d4dcab cal@example.com status=Active
...
01a1e867-b1f6-7c20-a6ad-fd28f53e0615 sam@example.com status=Active
$ gritpack admin user view sam@example.com
01a1e867-b1f6-7c20-a6ad-fd28f53e0615 sam@example.com status=Active
credential=01a1e867-d172-7a70-b11c-66473aaa9678 status=Active expires_at=1797492480

view takes the email or the account ID and lists the account's credentials: one per login, with when it expires. list shows up to 100 accounts per page (--limit); when there are more, it prints a next_cursor= line, and --cursor with that value gets the next page. Both take --json; the email field there is called canonical_email.

Suspending and reactivating

Suspension stops an account at once, without deleting anything. Every credential it has stops working on the next request:

$ gritpack admin user suspend sam@example.com --yes
account=01a1e867-b1f6-7c20-a6ad-fd28f53e0615 email=sam@example.com status=Suspended

From Sam's side, every command that talks to the hub now fails with an authorization error (exit 4):

$ gritpack search textkit
the hub answered HTTP 403: credential is not authorized

Reactivation undoes it, and the same credentials work again:

$ gritpack admin user reactivate sam@example.com
account=01a1e867-b1f6-7c20-a6ad-fd28f53e0615 email=sam@example.com status=Active

Suspend first when you are not sure: when someone leaves, while a lost laptop is found, or while you look into something odd.

Deleting

Careful. Deleting an account cannot be undone.

Deletion leaves a tombstone: the account's history and the packages it published stay, its credentials are revoked, and the account can never log in again. The hub refuses to delete an account that still owns a scope, so you first decide who should own its names:

$ gritpack admin user delete sam@example.com --yes
the hub answered HTTP 400: invalid administration operation
$ gritpack admin scope unassign samco --yes
unassigned @samco
$ gritpack admin user delete sam@example.com --yes
account=01a1e867-b1f6-7c20-a6ad-fd28f53e0615 email=sam@example.com status=Tombstoned

The first refusal is the scope rule. Its wording does not say so in 1.2.63; check admin scope list for the account's scopes when you see it.

suspend, delete, scope unassign and package quarantine ask for confirmation on a terminal. With no terminal they go ahead after a warning today, and will need --yes from 1.4.0, so always pass --yes in scripts.

Scopes

A scope is a family of names, @team/..., that only its owner may publish in. (Unscoped names belong to whoever publishes them first.) People can claim a scope nobody owns with gritpack scope claim; see Names, scopes and owners. An administrator can give any scope to any account, whether or not someone asked:

$ gritpack admin scope assign samco --owner sam@example.com
assigned @samco owner=01a1e867-b1f6-7c20-a6ad-fd28f53e0615
$ gritpack admin scope view samco
@samco owner=01a1e867-b1f6-7c20-a6ad-fd28f53e0615
$ gritpack admin scope list
@ada owner=01a1e860-95df-7c60-bbe1-5db0fd349f05
...
@samco owner=01a1e867-b1f6-7c20-a6ad-fd28f53e0615

Write the scope without its @ in these commands. In 1.2.63 admin scope view @samco is refused with "invalid administration operation".

A common pattern is to give the team's scope (@yourcompany) to a dedicated release account used by CI, and let people publish their experiments under scopes of their own. A scope has one owner; several people publish to it by sharing the work through that account in CI, or through workspaces released together.

scope unassign takes a scope away. It does not remove any package already published under it; the versions stay, and anyone who depends on them keeps working. It only means nobody may publish new versions there until the scope is assigned again.

What a scope does not do

A scope controls who may publish a name. It does not control who may see it. Every account that can log in to your hub can search for and install every package on it. If something must be hidden from some of your own people, it belongs on a different hub.

What the hub records

Every administrative change is written to the hub's audit log with the administrator certificate that made it and the state before and after. The next chapter shows how to read it, along with licence rules, quarantine and signing keys.

What just happened

You saved your administrator connection as a profile, added accounts and invited people with a code or a link, cancelled an invitation, suspended and reactivated an account, deleted one after handing over its scope, and gave scopes to accounts. None of this needed access to the hub's machine: the administrator certificate is all an administrator holds.

You can stop here

If you manage the people and names on your team's hub, you have the everyday tasks.

Next

Go on to Licence rules, quarantine and the audit log. For what the people you invite see, read Logging in.