Logging in
gritpack login, invitations, where the credential is kept, renewing before it expires
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
runsecret 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:
accountis your account on the hub;credentialis the certificate just issued to this computer;profileis the name Gritpack saved the login under:defaultunless you choose another with--profile. The newest login becomes the default;provideris where the credential is kept (see below);cais 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.
--store | Where | Use it for |
|---|---|---|
auto | the Keychain on macOS, a file elsewhere | everyday use |
keychain | the macOS Keychain | a Mac you sit at |
file | ~/.frogfish/gritpack/credentials/<credential>/, the key readable only by you | Linux, Windows, servers, CI |
run | a 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 withgritpack 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
--storeuses up the invitation and then stops. Always pass--store fileor--store runin 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.
logintakes--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 loginmade 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 renewreplaces 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
- Logins and profiles: several hubs, switching between logins, checking, moving and removing them.
- Optional: Names, scopes and owners, to claim the scope you will publish under.