Names, scopes and owners
Global names, @scope/name, claiming a scope, who may publish what
Before you publish, you need a name you are allowed to use. On a hub shared by many people, that matters: nobody else should be able to publish a new version of your library, and you should not be able to publish one of theirs by accident. This chapter explains the two kinds of package name, how a scope gives you a whole family of names, and the one rule about privacy that surprises people coming from npm.
What you will be able to do
- choose between a plain name and a scoped name;
- claim a scope of your own and confirm you own it;
- understand each refusal the hub gives when a name is not yours;
- explain why there is no "private package" switch.
Two kinds of name
notes a plain name: one per hub, owned by its first publisher
@bea/notes a scoped name: "notes" inside the scope @bea
A plain name (also called a global or unscoped name) belongs to the account that publishes it first on that hub. From then on, only that account can publish more versions under it.
A scoped name belongs to whoever owns the scope. Own @bea, and every
@bea/... name is yours to publish, now and later, without claiming each one.
The two forms are different packages. notes and @bea/notes are unrelated;
neither is an alias for the other, and owning one says nothing about the other.
Names are lowercase. Each part starts with a letter and may contain lowercase
letters, digits, ., _ and -, up to 128 bytes. An application package
cannot use _, because its installer's file name uses _ in place of the /
of a scope (see Installers and download links).
From npm. The
@scope/nameshape is the one you know, and it means the same thing for publishing: the scope's owner decides. What it does not mean is privacy; see Privacy is the hub, not the package.
From Cargo. Crates have no scopes, so every crate name is a plain name, first come, first served, on each hub. A hub is its own namespace: a crate name taken on crates.io is still free on your private hub, and the other way round.
Plain names: the first publisher owns them
Publishing a new plain name claims it. The publication report says so:
PUBLICATION_AUTHORITY_VERIFIED: Passed: global package name is unclaimed and claimable
When a different account later tries to publish a version of the same name, the hub stops it before anything is uploaded:
$ gritpack publish --yes --profile cal
...
native:p4-notes@1.1.0:text/plain:-:-: Blocked
PUBLICATION_AUTHORITY_DENIED: Failed: account does not own package name
publication verification blocked
The command exits with code 6, "conflict". Nothing was published, and the original owner's versions are untouched.
Plain names are convenient for tools that everyone on a hub knows by one word. For a library a team owns, a scope is usually better: it reserves every name under it at once, and nobody can take the next one before you.
Claiming a scope
On most hubs you claim a free scope yourself. Give the scope without the @:
$ gritpack scope claim bea
claimed @bea owner=01a1e865-dba3-7352-9217-40bfb4ff47cb
Confirm it with auth status, which lists the scopes your account may publish
under:
$ gritpack auth status
account=01a1e865-dba3-7352-9217-40bfb4ff47cb email=bea@example.com status=Active
credential=01a1e865-fa11-7663-8550-8c4d87a45daa status=Active expires_at=1797492359
writable_scope=@bea
Claiming a scope you already own does no harm; it prints the same line again.
When a claim is refused
A scope someone else owns cannot be claimed:
$ gritpack scope claim bea --profile cal
the hub answered HTTP 409: resource already exists
That is exit code 6, "conflict". The message is short because the hub does not tell other accounts who owns a scope; your administrator can.
A malformed scope is refused as a usage error, exit code 2. This includes
writing the @, which scope claim does not accept in 1.2.63:
$ gritpack scope claim @cal
the hub answered HTTP 400: invalid or unavailable package scope
Scopes an administrator assigns
Some hubs are run centrally: the administrator decides who owns which scope,
for example giving @acme to the account a team publishes from. They do it with
gritpack admin scope assign (Administering a hub).
The result is the same as a claim: the scope appears in your auth status, and
you publish under it. An administrator can also take a scope away again
(admin scope unassign); packages already published under it stay as they are.
Publishing into a scope that is not yours
The hub checks ownership for every package in every publication, before any file
is uploaded. Publishing @bea/notes from another account fails that check:
native:@bea/notes@1.1.0:text/plain:-:-: Blocked
PUBLICATION_AUTHORITY_DENIED: Failed: account does not own package scope
Publishing into a scope nobody has claimed fails too, with a different reason, so you know to claim it first:
PUBLICATION_AUTHORITY_DENIED: Failed: scope is not registered
A dry run (gritpack publish --dry-run) runs the same check, so you can find
out before you mean to publish. Publish your first package
walks through the whole report.
Where ownership comes from
Not from your files. Nothing in gritpack.toml, Cargo.toml or package.json
can say who the owner is. The hub works it out from the login that makes the
request and from its own records. That is why copying someone's manifest does
not let you publish as them, and why moving a project to another repository
does not change who owns its name.
It also means the owner is an account, not a person or a computer. One account can have several credentials: your laptop, your desktop, a CI job. Each publishes with the same authority, and each can be revoked on its own (Logins and profiles) without touching the names the account owns.
For automation. Give a CI job its own account if it publishes, rather than a copy of a person's credential. The administrator can then give that account the scope, and suspend it without locking anybody out.
Privacy is the hub, not the package
Gritpack has no "private package" setting. Every package on a hub can be read by everyone that hub lets in. A scope decides who may publish under it; it never decides who may read what is published.
So privacy comes from choosing the hub:
- On the public hub,
get.gritpack.org, everything published is readable by anyone, without an account. - On a private hub, only accounts its administrator has invited can read anything at all. Everything your team publishes there stays among the people the hub admits.
- To give a partner or customer a curated part of your packages, and nothing else, you hand them a signed bundle or a separate repository made from one (Offline bundles and slices).
There is deliberately no per-package permission list to get wrong. If a package must not be seen by everyone on a hub, it does not belong on that hub.
When people leave
An administrator can suspend an account at once, which stops all its credentials, and can delete it. Deleting an account keeps its identity on record, so the history of who published what stays intact; the hub refuses to delete an account that still owns a scope until the scope has been given to someone else or unassigned. Versions already published stay published, under their original owner. The details are in Administering a hub.
What just happened
- A plain name belongs to the account that publishes it first on that hub.
- A scope gives its owner every name beneath it; you claim a free one with
gritpack scope claim, or an administrator assigns it. - The hub decides ownership from your login, never from your files, and checks it for every package before uploading anything.
- Privacy is a property of the hub you publish to, not of the package.
You can stop here
If you own the scope you need and know why a publish might be refused, you are ready to publish on a shared hub. Individual publishers and small teams are done with this part of the guide.
Next
- Workspaces: several packages developed together in one repository.
- Optional: README and licence, the documentation every new version needs before the hub accepts it.