Licence rules, quarantine and the audit log

Which licences may be published, hiding a bad version, signing keys, the audit log

Chapter 32 of 34Current for Gritpack 1.2.63Source: docs/guide/32-licence-rules-quarantine-and-audit.md

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:

SubjectCovers
hubevery 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.