Names, scopes and owners

Global names, @scope/name, claiming a scope, who may publish what

Chapter 22 of 34Current for Gritpack 1.2.63Source: docs/guide/22-names-scopes-and-owners.md

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/name shape 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.