Tiered Entity Trust Model, Entity DIDs, DID Document declarations, Repo Migration, Package-claiming by Publishers, Terminology, Misc Cleanup

[toderash]

• Files Changed:
  • specification.md — amended
  • terminology.md — added (first version; replaces inline Definitions section in spec)

Sorry in advance for the size of this thing - it closes #76 and updates anything that got in the way, closing other issues fully or partially as summarized in the table at the end. Full change summary shown here with line numbers to view the actual verbiage. Here's what it does:

---

Changes to specification.md

Definitions

Terminology: inline glossary replaced with pointer to (new) terminology.md; RFC 2119 key words are stated, along with retirement of "vendor" in favour of "Publisher". Vendor → Publisher changed 9x in this file (only). ("Vendor" implies remuneration, where "Publisher" is neutral and should translate more accurately.)

DID Document section

Lines 158–160: replace existing multiple services rule to remove double-negative to permitted ambiguously. Now explicitly permitted with a unique id per service, allowing discretion to select among available services.

Line 162: verificationMethod requirement now conditioned to support Trust Tiers (see below). Also corrects fragment parts of "URL" to "URI".

Line 195: explicitly state that a Repository MAY host any number of Packages, each with a distinct Package DID processed independently.

New sections (lines 198–395)

New sections have been inserted between the DID Document section and the Metadata Document section. These all have to do with introducing a Trust Model that can source verification either to a Repo or a Publisher, which is then used to establish the technical processes for Package/Repo portability, claiming legacy Packages (migrate to FAIR), and multi-Repo service for the same Package.

Trust Tiers defines 2 tiers & rules for determining which applies based on DID entry formats alone. Repository-Trust or Publisher-Trust is ultimately determined by who signs the Package. Both entities MAY issue a DID Document for the Package, with Repo using capabilityDelegation to point to the Publisher's DID for signature verification. New requirement to surface the trust tier to Users & notify when the tier changes.

Alias Acknowledgment with alsoKnownAs defines bidirectional confirmation requirement before following any capabilityDelegation directive & defines fallbacks.

Multiple Repositories for a Package Publisher's DID MAY reference multiple Repositories via alsoKnownAs; defines behaviour for Clients & Aggregators, including impact of a checksum failure upon other Repos for same Package.

Package Portability and Repository Migration define Publisher's migration process between Repos & Client behaviour on stale Repository-Issued DID post-migration. Defines install by Publisher DID as a first-class resolution path (not previusly explicit). Publishers can migrate without any action by the outgoing Repo.

Package Claiming Process FAIR migration; process for a Publisher to claim ownership of a Package distributed under Repository-Trust. Repo verifies identity out of band based on its own policy; action is required by both parties to complete the transfer. Repositories MUST emit a Package.trust-transferred event to Aggregators on completion.

Key Revocation for Installed Packages specify Clients MUST re-verify installed Packages against current signing keys following a key rotation. MUST warn the user & block updates on failure, and MUST NOT auto-uninstall a Package if a historical signature can't be verified against current keys.

Metadata Document — id property

id property description added to address resolution beginning from a Publisher DID rather than a Package DID: id check performed against the Package DID obtained from the Publisher DID's alsoKnownAs entries, not against the Publisher DID itself. A mismatch is not a validation failure, provided the id matches the expected Package DID from alsoKnownAs.

---

Corrections to pre-existing text

With numerous changes in scope, specification.md was reviewed for language, logic, & internal consistency to check the language being inserted. The following changes were also caught to correct minor errors or unclear language in the original text.

Meaningful corrections:

• Line 119 (Common Elements): "all HTTP protocols MUST use Transport Layer Security" changed to "all HTTP connections MUST use TLS." (constraint applies to connection, not protocol)
• Line 126 (HTTP reference): Link updated from RFC 7230 (2014) to current RFC 9110, with a "or later versions" annotation on the link title.
• Line 640 (version property): [semver] reference used inline without definition; added [semver]: https://semver.org/
• Lines 834–882 (auth / sbom structural displacement): slight paragraph shuffle after inserting the sbom paragraph incorrectly in previous PR
• Line 814 (auth property): auth is a Release Document property governing artifact access, not package-level access: changed to "authentication requirements to access the release's artifacts."
• Line 958 (Repository Document, security property): corrected to "Publishers" to "Repositories" based on context

Typos & grammar:

• Line 5 (opening sentence): smoothed verbiage
• Line 44 (Protocol Flow): "focusses" corrected to "focuses."
• Line 139 (Resolving DIDs): lowercase must corrected to MUST
• Line 629 (version property): added missing period
• Line 631 (version property): correct misplaced hyphen
• Line 678 (artifacts property): extraneous comma removed
• Line 710 (release-asset property): correct H3 to H4
• Line 752 (url property): reworded to smoothen
• Line 766 (checksum property): correct link syntax
• Line 832 (auth property): lowercase must corrected to MUST
• Line 1045 (Schema Evolution): fix grammatical error
• Line 1058 (Link Relationships): fix unbalanced parentheses

---

Introduction of terminology.md

terminology.md new file replacing the brief inline definitions in specification.md. Keeps all terms with fuller definitions & adds terms to support the trust model and some pre-existing content. Defined terms have HTML anchor IDs (#def-[term]) for cross-document linking.

---

Issues Resolved

Issue	Resolution	Extent
Closes #59	Multiple FairPackageManagementRepo services explicitly permitted, with selection rules	Full
Closes #61	Multiple Packages per Repo support explicit, with process rules	Full
fair-plugin #345	Adds multi-service support; plugin implementation unblocked	Partial
fair-plugin #430	discretionary selection criteria across multiple Repos	Partial
fair-beacon #7	Install by Publisher DID defined as a first-class resolution path	Full
fair-protocol #49	Entity DID types codified in terminology; improves alignment with Moderation/Labelling spec and Trust Model draft	Partial
fair-protocol #45	Protocol-supported claiming process defined; Repository-level identity verification policy remains out of scope	Partial

---