Logging in

gritpack login, invitations, where the credential is kept, renewing before it expires

Chapter 20 of 34Current for Gritpack 1.2.63Source: docs/guide/20-logging-in.md

Until now you have used Gritpack anonymously. Searching the public hub and installing from it needs no account. Two things change that: your team works on a private hub, or you want to publish. Both need a login. This chapter takes you from an invitation in your inbox to a working login, shows where the login is kept, and explains how to keep it alive.

What you will be able to do

  • turn an invitation from a hub's administrator into a login with one command;
  • choose where your credential is kept: the macOS Keychain, a protected file, or the run secret store;
  • log in from a script or a CI job without a prompt;
  • renew a login before it expires, and recover when it has expired.

What a login is

A login is a certificate the hub issues to your computer. When you run gritpack login, Gritpack makes a new private key on your machine, sends the hub only a request to sign it, and saves the certificate the hub sends back. The private key never leaves your computer, and Gritpack never prints it.

Every later command that talks to that hub presents the certificate. The hub knows which account it belongs to, so it knows what you may read and publish. There is no password to type again and no token to paste.

A login lasts 30 days. That is short on purpose: a lost laptop holds a key that stops working within a month even if nobody notices it is gone. Renewing is one command, covered at the end of this chapter.

From npm. The nearest thing is npm login, which saves a token in ~/.npmrc. A Gritpack login saves a certificate instead, and the private half never travels over the network.

Getting an invitation

Accounts on a private hub are created by its administrator. When they add you, they send you an invitation. It comes in one of two forms:

  • An enrollment code, a short string of letters and digits in groups, such as 6404-FF08-185A-4D31-AE6A-8FF7, together with the hub's address.
  • A link such as https://get.gritpack.org/i/2WS1KDEXF3. Opening it gives you a download that installs Gritpack if you need it and logs you in, in one step. The ten characters at the end of the link are the code.

Either way, the code works once, for your email address only, and stops working when the invitation expires. An invitation the administrator made during this guide's test run was valid for 24 hours. If yours has expired or been used, ask for a new one; there is nothing you can do with an old code.

Log in with a code

The shortest form names the hub and lets Gritpack ask for the rest:

gritpack login packages.example.com

On a terminal, Gritpack asks for two things. The code is hidden as you type it:

Email: ada@example.com
Enrollment code:

Then it enrolls and saves the login. Here is the same login with everything given on the command line, saved under the profile name work:

$ gritpack login ada@example.com --hub packages.example.com --code 39F5-63FC-E750-4F34-9337-D2D0 --profile work --store file
logged in account=01a1e860-95df-7c60-bbe1-5db0fd349f05 credential=01a1e860-aa92-7b81-91d7-516d55ad4a94 profile=work provider=file ca=~/.frogfish/gritpack/credentials/01a1e860-aa92-7b81-91d7-516d55ad4a94/server-ca.pem

The line tells you everything that happened:

  • account is your account on the hub;
  • credential is the certificate just issued to this computer;
  • profile is the name Gritpack saved the login under: default unless you choose another with --profile. The newest login becomes the default;
  • provider is where the credential is kept (see below);
  • ca is the certificate authority Gritpack will use to recognise the hub.

The positional argument is either the hub or your email address, so gritpack login ada@example.com and gritpack login packages.example.com both work; the flags --hub and --email say which is which when you give both. With no hub at all, login uses GRITPACK_ENROLLMENT_SERVER if it is set, and otherwise the public hub, get.gritpack.org.

Check that it worked:

$ gritpack auth status
account=01a1e860-95df-7c60-bbe1-5db0fd349f05 email=ada@example.com status=Active
credential=01a1e860-aa92-7b81-91d7-516d55ad4a94 status=Active expires_at=1797492011
writable_scopes=none

expires_at is a Unix time: seconds since 1 January 1970. writable_scopes=none means you do not own a scope yet; Names, scopes and owners fixes that.

When the hub has unusual addresses

A hub answers on two addresses: one where you log in (enrollment) and one where packages are served. Gritpack infers both from the name you give it. For packages.example.com it uses port 7445 to log in and port 7443 for packages; the public hub serves packages on the standard HTTPS port. If your administrator gives you different addresses, pass them both:

gritpack login ada@example.com \
  --hub packages.example.com:9445 \
  --package-hub packages.example.com:9443

Gritpack refuses to guess a package address for a nonstandard login port, so it never sends your requests somewhere you did not mean.

When the hub uses its own certificate authority

Public hubs use ordinary web certificates that your computer already trusts. Some private hubs, often ones run on a company's own premises, use a certificate authority of their own. The administrator then gives you its certificate as a .pem file. Pass it once at login:

gritpack login ada@example.com --hub packages.example.com --ca company-ca.pem

Gritpack copies it next to your credential and uses it for every later command, so you never pass --ca again.

Where your credential is kept

--store chooses where the private key and certificate live. The default, auto, is the macOS Keychain on a Mac and a protected file elsewhere.

--storeWhereUse it for
autothe Keychain on macOS, a file elsewhereeveryday use
keychainthe macOS Keychaina Mac you sit at
file~/.frogfish/gritpack/credentials/<credential>/, the key readable only by youLinux, Windows, servers, CI
runa project and environment in the run secret store (--run-project, --run-environment)teams that already keep secrets in run

With file, the directory holds the certificate, the private key (mode 0600), the hub's certificate authority and a small identity.json naming the account and credential. Your profile, in ~/.frogfish/gritpack/config.toml, records only where those files are, never their contents. The same is true for the Keychain and run: the profile holds a reference, and the secret stays in the store.

Careful. A Mac reached over SSH cannot open its Keychain from that session. If you log in to a Mac remotely, pass --store file, or move an existing login once from the Mac's own Terminal with gritpack auth migrate --store file.

You can move a login between stores later; Logins and profiles shows how.

Logging in from a script or CI

Gritpack never asks a question when there is no terminal to answer it. Without one, login needs everything on the command line or in the environment:

$ gritpack login ada@example.com --hub packages.example.com < /dev/null
login requires --code; provide the option or use an interactive terminal

The code can come from --code or from the GRITPACK_ENROLLMENT_CODE environment variable, which keeps it out of your shell history and process list. When the CI variable is set, Gritpack also insists that you choose the store yourself, because a build machine has no Keychain to fall back on:

$ CI=1 gritpack login ada@example.com --hub packages.example.com
invalid package connection: under CI, choose where to keep the credential: --store file or --store run

Careful. In Gritpack 1.2.63 that check happens after the hub has accepted the code, so a CI login without --store uses up the invitation and then stops. Always pass --store file or --store run in CI. If it has already happened, ask the administrator for a new invitation.

A complete non-interactive login looks like this:

$ CI=1 GRITPACK_ENROLLMENT_CODE=54D1-A83A-EB00-4385-A5CF-841D gritpack login ci-bot@example.com --hub packages.example.com --store file --profile ci
logged in account=01a1e86d-0916-75d1-9d8f-36bb89eeccfb credential=01a1e86d-4062-7bc1-80fa-070d59d6f01e profile=ci provider=file ca=~/.frogfish/gritpack/credentials/01a1e86d-4062-7bc1-80fa-070d59d6f01e/server-ca.pem

A CI job usually needs a long-lived identity rather than a person's login. Continuous integration covers how to give a job its own account and keep its credential in the job's secret store.

For automation. login takes --format json (or --json) and prints the same facts as a JSON object. A failed login exits with code 3 (authentication) when the hub refuses the code, and 2 (usage) when something is missing from the command line.

When a code is refused

A refused code always looks the same, on purpose: the hub does not tell a stranger whether a code was wrong, used, revoked or expired.

$ gritpack login ada@example.com --hub packages.example.com --code 6404-FF08-185A-4D31-AE6A-8FF7
enrollment server returned HTTP 401: invalid enrollment proof

Check, in this order: that you typed the email address the invitation was sent to; that the code is the newest one you were sent (a new invitation does not cancel the old one, but each code works only once); and that it has not expired. If all of that is right, ask for a new invitation.

Logging in from a link

An invitation link opens a page on get.gritpack.org that offers two ways in:

  • On a Mac, a download called Join followed by the hub's name. Open it and confirm. It installs Gritpack if it is missing and then logs you in. The code is part of the download's own file name, so do not rename it.

  • In a terminal on Linux or a Mac, a command of this shape, with your code at the end:

    curl -fsSL https://get.gritpack.org/install/gritpack | sh -s -- --code 2WS1KDEXF3

Both end in the same place as gritpack login: a login profile in your Gritpack home. When Gritpack is already installed, joining downloads nothing and only logs in. The installer itself is described in Installers and download links.

Renewing before a login expires

From a week before a login expires, every command that uses it prints a warning on standard error. It names the credential, the date and time it expires, how long is left, and what to do: renew it with an invitation from the hub's operator and gritpack auth renew.

Renewing needs a fresh invitation code, because only the administrator can let a computer enroll. Ask for one, then:

$ gritpack auth renew --profile work --hub packages.example.com --code FA53-6767-66E4-4E40-8880-568C
credential renewed profile=work old=01a1e866-621f-7293-8d9b-2cf27c02c019 new=01a1e867-377a-7c33-b918-33effaddbae4 provider=file old_revoked=true

auth renew enrolls the new credential first, switches the profile to it, and only then revokes the old one (old_revoked=true). There is no moment when you have no working login. It keeps the store the login already uses unless you pass --store, and it asks for your email and code on a terminal if you leave them out. For the public hub you can leave out --hub; for any other hub, give the same address you logged in with.

auth status afterwards shows both credentials, the old one revoked:

credential=01a1e866-621f-7293-8d9b-2cf27c02c019 status=Revoked expires_at=1797492386
credential=01a1e867-377a-7c33-b918-33effaddbae4 status=Active expires_at=1797492440

When it has already expired

An expired login cannot renew itself: the hub no longer accepts the certificate that would prove who is asking. Gritpack says so instead of showing a TLS error, and tells you to ask the hub's operator for an invitation and run gritpack login again. Log in with the same --profile name and the profile is refreshed in place; your projects and settings do not change.

What just happened

  • An administrator invited you; the invitation's code works once, for your email, for a limited time.
  • gritpack login made a private key on your computer, had the hub sign a certificate for it, and saved a profile pointing at both.
  • The credential lives in the Keychain, a protected file, or run, and the profile only says where.
  • Logins last 30 days. gritpack auth renew replaces one before it expires, with no gap.

You can stop here

If you work with one hub and one login, you are done: every package command now uses your login automatically. Come back when the expiry warning appears.

Next