Licence rules, quarantine and the audit log
Which licences may be published, hiding a bad version, signing keys, the audit log
The previous chapter was about people and names. This one is about what gets published and what you can do when something goes wrong. You will set rules for which licences packages on your hub may declare, so your company's own code is not published as open source by accident. You will hide a published version at once when it must not be used, and bring it back. You will register publishers' signing keys, for hubs that require signatures. And you will read the audit log, where every one of these changes is recorded.
All the commands here are gritpack admin commands and need the
administrator connection from Administering a hub.
What you will be able to do
- Limit the licences new versions may declare, for the whole hub, one account, one scope or one name, with narrower exceptions.
- List the published versions that today's rules would refuse.
- Quarantine a published version, and restore it.
- Register, list and revoke publishers' signing keys.
- Read and filter the audit log.
Licence rules
Why they exist
Copying a manifest from a template, or letting a coding agent fill one in,
can easily give a private package license = "MIT". Once published, that
version is immutable and already in other people's lock files. A licence rule
is a safety net against that mistake: the hub refuses a new version whose
declared licence is not on the list, before anything is stored.
A rule is not access control and does not judge licences. Each hub lists the licences it allows, and Gritpack compares the version's declared SPDX expression with the list. It never reads licence files or scans code, and it never touches versions already published.
Who a rule covers
A rule has a subject:
| Subject | Covers |
|---|---|
hub | every name that no other rule covers |
account:<email or ID> | everything that account publishes, unscoped names and its scopes |
@<scope> | every name in that scope |
name:<package name> | that one name, in every ecosystem |
The most specific rule decides: a name's own rule first, then its scope's, then the publishing account's, then the hub's. No rule at all means no restriction, which is how every hub starts.
That order lets the broad rule be the default and open source the named
exception. A company might set a hub rule allowing only its internal source
licence, so every new scope and every new publisher is covered from day one,
and then a name: rule for a fork of an open-source project that must keep
its upstream licence.
Setting, listing and clearing
admin license-rule set takes the subject and then each allowed licence as a
separate argument. Each must be one SPDX licence identifier (or a
LicenseRef-...), optionally with + or WITH <exception>, never an
expression with AND or OR:
$ gritpack admin license-rule set @ada Apache-2.0 LicenseRef-Ada-Internal-1.0
@ada allows Apache-2.0, LicenseRef-Ada-Internal-1.0
$ gritpack admin license-rule list
@ada allows Apache-2.0, LicenseRef-Ada-Internal-1.0
Setting a rule for the same subject again replaces it. An identifier the SPDX list does not know is refused when you set the rule, so a typo cannot create a rule that refuses everything:
$ gritpack admin license-rule set @ada MITT
the hub answered HTTP 400: `MITT` is not an SPDX licence: MITT
^^^^ unknown term
An account rule may name the account by email; the list shows its ID:
$ gritpack admin license-rule set account:ada@example.com MIT
account:01a1e865-dd2b-7f10-9340-1658dbafa174 allows MIT
clear removes a rule:
$ gritpack admin license-rule clear name:@ada/textkit
name:@ada/textkit has no licence rule now
Only administrators can set or clear rules. A publishing credential cannot, so neither a person nor an agent that trips a rule can switch it off.
What publishers see
A version passes when every licence term in its expression is on the list,
whatever the operators between them. X OR MIT is refused when MIT is not
allowed, because everyone could then choose MIT; X AND MIT is refused
because part of the code would be under MIT. A version with no SPDX
expression (only licence files, or a --without-license waiver) is refused by
any rule, because the hub cannot check it. Go modules have no licence field,
so a Go module cannot be published where a rule applies to it.
The check runs when the plan is verified, before anything is uploaded, so a
publisher finds out at publish --dry-run:
$ gritpack publish --dry-run
...
native:@ada/textkit@1.0.2:c/c23:-:-: Blocked
PUBLICATION_AUTHORITY_VERIFIED: Passed: publisher owns the package authority
PUBLICATION_LICENSE_NOT_ALLOWED: Failed: @ada/textkit 1.0.2 declares the licence `MIT`, but the hub's licence rule for @ada allows only Apache-2.0, LicenseRef-Ada-Internal-1.0. Not allowed: MIT. Correct the licence in the package manifest; only the hub's operator can change the rule
publication verification blocked
The command exits with status 6. The message tells the publisher to fix the
manifest, not to ask for the rule to change, so a script or coding agent that
hits it corrects the right thing. The hub applies the same check again on
every publishing path, including plain cargo publish and npm publish
through the hub's registries, so nothing slips past.
README and licence covers this from the publisher's side.
Exceptions
To let one package keep a different licence, give its name a rule. The name rule wins over the scope rule:
$ gritpack admin license-rule set name:@ada/textkit MIT
name:@ada/textkit allows MIT
$ gritpack admin license-rule list
@ada allows Apache-2.0, LicenseRef-Ada-Internal-1.0
name:@ada/textkit allows MIT
Now the same dry run passes. Cargo crates and Go modules have no scopes, so a
name: rule is also how a single crate keeps its own licence.
Versions already published
Rules apply only to versions published after they are set. Published versions are never yanked, hidden or relabelled because of a rule. To find the ones that would be refused today, so their owners can fix the next version:
$ gritpack admin license-rule list --refused
native @ada/textkit 1.0.0 declares MIT: not allowed: MIT (rule @ada)
native @ada/textkit 1.0.1 declares MIT: not allowed: MIT (rule @ada)
2 published versions the rules would refuse now
In 1.2.63 this lists native packages and Cargo crates; npm and Go versions are not listed yet.
Quarantine
Sometimes a published version must stop being used at once: it contains a secret, a file the publisher had no right to publish, or something harmful. Yanking (see After publishing) is the publisher's tool and only stops new projects choosing a version. Quarantine is the administrator's: it hides the version from everyone, completely.
Careful. Quarantine takes effect immediately for every account on the hub, including projects whose lock files already name that version. Their next install from the hub fails until you restore it.
$ gritpack admin package quarantine @ada/textkit@1.0.1 "Reported to contain a file we may not publish; under review" --yes
quarantined @ada/textkit 1.0.1 storage_id=01M7M6EESKFTR9V7FAMYJ6CPXB
The version is named as name@version (or by its storage ID). The reason, up
to 512 bytes, is recorded in the audit log.
While it is quarantined, the version does not exist as far as anyone using the
hub can tell. It disappears from search and info, cannot be downloaded, and
a project locked to it cannot install it:
$ gritpack info @ada/textkit
package @ada/textkit was not found
$ gritpack sync
cannot resolve @ada/textkit: root requires @ada/textkit ^1.0.1
(In this example the only other version had been yanked, so the whole package appears missing.) A quarantined name is still owned: when someone has both a private hub and the public hub configured, Gritpack does not fall back to a public package with the same name.
What quarantine cannot reach is a copy already on someone's machine. A project
that installed the version earlier keeps its files, and sync --offline can
still install it from the local download cache. If the problem is serious,
tell your users to remove it, and publish a fixed version they can move to.
When the review is done, restore it:
$ gritpack admin package unquarantine @ada/textkit@1.0.1
unquarantined @ada/textkit 1.0.1 storage_id=01M7M6EESKFTR9V7FAMYJ6CPXB
$ gritpack sync
synchronized 1 packages into ./packages status=unchanged
Nothing about the version changed while it was hidden; it is the same bytes, with the same digest, as before.
Signing keys
Every version on a hub is published by an authenticated account, and its receipt records which one. Some organisations want more: a signature from a key the publisher holds, so anyone can check later which publisher key vouched for those exact bytes, without trusting the hub's word for it. A hub can be set to require such signatures on new versions; ask Frogfish if you want that for yours. Most hubs do not require them.
When signatures are required, the administrator says which keys count. The
publisher makes a key pair and gives you only the public half. From a 32-byte
seed file the publisher keeps secret, evidence public-key writes the public
key:
$ gritpack evidence public-key --signing-seed ada-signing.seed --output ada-signing.pub
public key=17fb1f8467d08fc313ddeb8f38a57bdca05a7eaa26f73d2c716251a85456276c output=ada-signing.pub
You register it for the account, and for the publisher it signs for: the account itself, or one of its scopes:
$ gritpack admin signing-key add --account ada@example.com --publisher @ada --public-key ada-signing.pub
registered publisher=@ada key=17fb1f8467d08fc313ddeb8f38a57bdca05a7eaa26f73d2c716251a85456276c evidence=19a41c27adbb067f3f22232fc1c48925ae89277e2655caa1714d5b09cc1032f3
$ gritpack admin signing-key list --publisher @ada
1 signing keys
key=17fb1f8467d08fc313ddeb8f38a57bdca05a7eaa26f73d2c716251a85456276c evidence=19a41c27adbb067f3f22232fc1c48925ae89277e2655caa1714d5b09cc1032f3 recorded_at=1794900548
--valid-from and --valid-until (Unix times) limit when the key's
signatures count. The hub never sees the private key.
Retire a key with revoke and a reason (superseded, compromised,
retired or administrative):
$ gritpack admin signing-key revoke 17fb1f8467d08fc313ddeb8f38a57bdca05a7eaa26f73d2c716251a85456276c --reason retired
revoked key=17fb1f8467d08fc313ddeb8f38a57bdca05a7eaa26f73d2c716251a85456276c evidence=cdfc829d6581fdb789cafa548f5ee65bb8223a0b9ca8d41078c7d0ddb7b69c09
Signatures made before the revocation still count unless you say otherwise.
For a stolen key, use --reason compromised with --compromise-at <time> --invalidates-prior, which also refuses signatures made after the moment of
compromise, or --invalidates-prior alone to refuse every signature the key
ever made. To rotate, register the new key first, let publishers start using
it, then revoke the old one.
In 1.2.63, signing-key list still shows a revoked key without marking it;
keep the evidence= value that revoke printed as your record.
Integration pending. Gritpack 1.2.63 has no command that makes a publisher signature. Signatures are made by tools built on Gritpack's library and attached at publication (
publish --attestation). Evidence and receipts shows how anyone checks the signatures and receipts a hub keeps.
The audit log
Every administrative change is recorded in the hub's audit log, which can only grow: accounts added, invitations issued and revoked, suspensions, deletions, scopes assigned and unassigned, licence rules set and cleared, quarantines, signing keys. Each entry names the change, what it was made to, and the SHA-256 of the administrator certificate that made it:
$ gritpack admin audit-log --limit 3
01a1e860-95ea-7f31-936f-7c178648573a account.create_or_get account=01a1e860-95df-7c60-bbe1-5db0fd349f05 actor=d5529c69b47506f3e9cfdbd7e4e68cb583508f928c831d96cbae53195bc00b06
01a1e860-9652-7023-b11b-94057ea93e14 enrollment_invitation.create enrollment_invitation=01a1e860-9650-7170-97ac-31740e33c7c0 actor=d5529c69...
01a1e865-dbac-74b3-8daf-379bdb7c8b33 account.create_or_get account=01a1e865-dba3-7352-9217-40bfb4ff47cb actor=d5529c69...
next_cursor=01a1e865-dbac-74b3-8daf-379bdb7c8b33
The log starts with the oldest entry. Each page holds at most 100
(--limit); pass the printed next_cursor to --cursor for the next page.
On a terminal it opens in the pager.
The JSON form adds the state before and after each change, which is what you want when you need to know exactly what a change did:
$ gritpack admin audit-log --limit 1 --json
{
"items": [
{
"action": "account.create_or_get",
"actor_certificate_sha256": "d5529c69b47506f3e9cfdbd7e4e68cb583508f928c831d96cbae53195bc00b06",
"after": {
"account_id": "01a1e860-95df-7c60-bbe1-5db0fd349f05",
"canonical_email": "ada@example.com",
"created_at": 1794900006,
...
"status": "active"
},
"before": null,
"event_id": "01a1e860-95ea-7f31-936f-7c178648573a",
"occurred_at": 1794900006,
"target_id": "01a1e860-95df-7c60-bbe1-5db0fd349f05",
"target_kind": "account"
}
],
...
}
With --jq you can count or filter without other tools:
$ gritpack admin audit-log --jq '.items[] | .action' | sort | uniq -c
10 account.create_or_get
1 account.reactivate
2 account.suspend
1 account.tombstone
12 enrollment_invitation.create
2 enrollment_invitation.revoke
1 evidence.signing_key.bind
1 evidence.signing_key.revoke
3 license_rule.clear
4 license_rule.set
1 package.quarantine
1 package.unquarantine
1 scope.assign
1 scope.unassign
That counts one page (the first 100 entries); loop over next_cursor for the
whole log. The log records administrative changes. Publications are recorded
separately, in each publication's signed receipt.
What just happened
You set licence rules from broad to narrow and saw a publication refused at the dry run, before anything was uploaded. You listed the published versions a rule would refuse, without changing them. You hid a version from everyone and restored it unchanged. You registered and revoked a publisher's signing key, and you read the audit log that recorded every step.
You can stop here
Hub administrators now have the whole administrative toolkit.
Next
When something does not work, go to Troubleshooting by symptom. For how consumers check what a hub signed, read Evidence and receipts.