Formalize entity types & repo-assigned DIDs for zero-infrastructure authors; Define Repo migration & Package-claiming mechanisms for Publishers

[toderash]

Preamble

This issue covers a set of gaps in the core spec that define how Publishers control Package identity, how trust is established and transferred, how multiple Repositories are handled, and how legacy Packages migrate to Publisher-controlled DIDs. These are combined to address as one issue because the design decisions interlock, so resolving them separately risks inconsistency or incompatibility if amended separately.

FAIR's Labelling (Moderation) Specification and Trust Model both anticipate having Publishers, Repositories, and Aggregators having DIDs to identify each of these entities. This is a requirement to support the ability to assign Trust Labels or other Labels to the entity itself. This issue adds explicit support for the use of DIDs which identify an entity rather than a Package into the FAIR Protocol itself.

---

Background: Terminology

The following terms are used with specific meaning throughout this issue. The spec should adopt these definitions, replacing the existing use of "vendor" with "Publisher", which allows but does not imply a payment transaction.

Publisher — The entity releasing a Package for distribution. Publishers hold the copyright or have permission from the copyright holder to publish the Package. A Publisher is accountable for its releases, and may be an individual or an organization.

Repository — Hosts Package assets and MAY resolve DIDs to serve DID documents for supported DID methods (e.g., DID:web), and MAY hold signing keys in the Repository-Trust model. To ensure Portability, Publishers MAY move Packages between Repositories.

Author / Contributor / Maintainer — No normative assumptions are made about these roles beyond what is defined in applicable third-party schemas or specs. An author may or may not hold the copyright, and a software firm employing an author would typically the Publisher.

DID Holder — An entity that controls a DID with its registrar. For some DID methods such as DID:web, the DID registrar and the DID Holder may be the same entity.

Publisher DID — A DID which does not identify a specific Package, but identifies a Publisher, being the entity that publishes Packages.

Repository DID — A DID which does not identify a specific Package, but identifies a Repository, being the entity that operates the Repository.

Aggregator DID — A DID which does not identify a specific Package, but identifies an Aggregator, being the entity that operates the Aggregator.

Repository-Issued-DID — A DID held by a Repository on behalf of the Publisher to identify a specific Package. For some DID methods such as DID:web, the Repository may also be the resolver for the DID.

Publisher-Issued-DID — A DID held by a Publisher to identify a specific Package for which it is the Publisher.

Repository-Trust — The Package is signed by the Repository, so trust in the artifact flows from trust in the Repository.

Publisher-Trust — The Package is signed by the Publisher using their own keys, so trust in the artifact flows directly from the Publisher.

Trust Tier — One of two specified trust types, in the Trust Model, Repository Trust or Publisher Trust.

Vendor — The term "vendor" is retired from normative use, and "Publisher" should be read into its place if encountered in the documentation.

---

Section 1: Trust Tiers

Two distinct tiers are identified in the FAIR Trust Model, distinguished by the structure of the Package's DID document. Clients determine the applicable tier from the DID document alone, without a specific metadata field for this purpose.

Repository-Trust

The DID document lists verification methods (signing keys) directly. The Package is signed by the Repository, so trust in the artifact flows from trust in the Repository. This is the baseline model and applies to:

• Legacy Packages redistributed by a Repository when the original Publisher has no involvement in DID creation or signing; and
• Packages where the Publisher chooses to delegate signing entirely to their Repository.

Publisher-Trust

A Repository's DID document may contain a capabilityDelegation entry referencing the Publisher's DID. The Package is signed by the Publisher using keys they alone control, so trust in the artifact flows directly from the Publisher's DID, independent of the Repository.

Example Repository DID document structure for this scenario:

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/multikey/v1"
  ],
  "id": "did:web:repo.example.com:Packages:my-plugin",
  "alsoKnownAs": [
    "did:plc:Publisher123abc..."
  ],
  "service": [
    {
      "id": "#fairpm_repo",
      "type": "FairPackageManagementRepo",
      "serviceEndpoint": "https://repo.example.com/Packages/my-plugin"
    }
  ],
  "capabilityDelegation": [
    "did:plc:Publisher123abc...#fair_signing"
  ]
}

Note the format for capabilityDelegation is the DID to which authority is delegated with the capability appended, in this case #fair_signing.

Example of corresponding Publisher's DID document structure for this scenario:

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/multikey/v1"
  ],
  "id": "did:plc:Publisher123abc...",
  "alsoKnownAs": [
    "did:web:repo.example.com:Packages:my-plugin"
  ],
  "service": [
    {
      "id": "#fairpm_repo",
      "type": "FairPackageManagementRepo",
      "serviceEndpoint": "https://repo.example.com/Packages/my-plugin"
    }
  ],
  "verificationMethod": [
    {
      "id": "did:plc:Publisher123abc...#fair_signing",
      "type": "Multikey",
      "controller": "did:plc:Publisher123abc...",
      "publicKeyMultibase": "zQ3shwa7usQaHQqiUMCRweiWD2Njb8sZBynkqxD3VXMSzSorc"
    }
  ],
  "assertionMethod": [
    "did:plc:Publisher123abc...#fair_signing"
  ]
}

This model requires two DID resolutions:

1. Resolve the Package DID → obtain the DID document → find the capabilityDelegation reference to the Publisher's DID and the FairPackageManagementRepo service endpoint(s).
2. Resolve the Publisher's DID → obtain current verification methods → use those keys to verify the artifact signature.

Clients MUST perform both resolutions when capabilityDelegation is present. Clients MUST NOT accept a signature as Publisher-verified if only the Package DID has been resolved.

Publisher DID takes precedence

The Publisher DID is the higher Trust Tier and is the authoritative source for Repository location. When a Package DID document contains capabilityDelegation referencing a Publisher DID, and the Publisher DID has a FairPackageManagementRepo service endpoint, Clients MUST prefer the Publisher DID's service endpoint(s) over any endpoint listed in the Repository's Package DID document.

Determination of precedence is by DID Holder and not by DID method, which may be any DID method supported by the FAIR protocol.

Client presentation of Trust Tier

To enable end-user discretion concerning Trust Tiers, Clients MUST surface the applicable Trust Tier to users when displaying Package details:

• Repository-Trust indicates that the Package is signed by the Repository, attesting that it contains a true bit-for-bit copy of the original Package. Trust flows from the Repository.
• Publisher-Trust indicates that the Package is signed directly by the Publisher. Trust flows from the Publisher.

Trust Tier change notification

If a Client detects that the Trust Tier of an installed Package has changed since last install or update, or detects that capabilityDelegation references a different Publisher DID, the Client MUST notify the user before installing any update. The update MUST NOT proceed silently.

---

Section 2: alsoKnownAs — Alias Acknowledgment

The alsoKnownAs property in the DID document declares a mutual acknowledgment that two identifiers refer to the same subject. It does not convey authorization of any type.

For Publisher-Trust Packages, the Publisher's DID SHOULD include alsoKnownAs entries referencing any DID document for the Package issued by a Repository. The Package's DID SHOULD include alsoKnownAs referencing the Publisher's DID. Bidirectional confirmation indicates an active, mutually acknowledged relationship between a Package hosted by a Repository and a Publisher.

Clients MUST verify bidirectional confirmation by alsoKnownAs entries before following any capabilityDelegation directives. When capabilityDelegation is present in a web DID document, Clients MUST resolve the trust root as follows

Case 1 — confirmation broken, Publisher DID has a FairPackageManagementRepo service endpoint: The Publisher has moved on, either by initiating migration away from this Repository, or because the Repository has removed the capabilityDelegation to disavow the relationship. In both cases, Clients MUST follow the Publisher DID's service endpoint and MUST NOT fall back to the Repository DID document. This applies for both Publisher-initiated and Repository-initiated separation. The Publisher's DID MUST remain authoritative.

Case 2 — confirmation broken, Publisher DID has no FairPackageManagementRepo service endpoint: The delegation cannot be confirmed and there is no authoritative Publisher endpoint to follow. Clients MUST NOT install or update the Package and MUST surface a warning to the user. Clients MUST NOT fall back to Repository-Trust. The presence of an unconfirmed capabilityDelegation is a signal that the trust model for this Package is in an indeterminate state.

Case 3 — no capabilityDelegation present: Repository-Trust baseline applies. The Package has not entered the Publisher-Trust model from the standpoint of this DID document.

Falling back to Repository-Trust MUST only occur in Case 3. A capabilityDelegation that exists but is unconfirmed is not equivalent to the absence of capabilityDelegation. This distinction is required to ensure Package portability is directed solely by the Publisher.

---

Section 3: Multiple Repositories

Spec amendment — remove double-negative

Concerning DID Documents, the FAIR Protocol specification currently states:

"Valid documents SHOULD NOT contain multiple services without the FairPackageManagementRepo type unless specified by an extension to this specification."

This should be replaced with:

"Valid documents MAY contain multiple services of the FairPackageManagementRepo type. Each service MUST have a unique id value, and Clients MAY select any available service from the list. Clients SHOULD attempt an alternative service if the selected one is unavailable or returns an invalid response."

The restriction on services of other types is unchanged: services of types other than FairPackageManagementRepo SHOULD NOT be present unless specified by an extension.

This resolves fair-protocol #59 and provides the Protocol foundation for fair-plugin #345.

Multiple alsoKnownAs entries as multiple repos

In the Publisher-Trust model, the Publisher's DID MAY list multiple DIDs in alsoKnownAs entries. Each DID MAY point to a different Repository to support configurations for redundancy, geographic distribution, and phased release strategies at the Publisher's discretion. Clients and Aggregators MUST NOT assume release parity across Repositories.

Clients MAY use any criteria to select among Repositories, including availability, latency, or locally configured preference. This provides the Protocol foundation for fair-plugin #430.

Aggregator behavior for multi-repo Packages

Aggregators resolve the Publisher's DID to obtain the list of valid Repositories. The Aggregator MAY use any criteria to select which Repository to index. Aggregators MUST NOT merge release lists across Repositories.

Sync failure handling

If a Client fetches a release artifact and the checksum does not match the value in the release record, the Client MUST treat this as a transient failure, and MUST NOT install the Package. The Client SHOULD attempt an alternative Repository if one is available. A checksum failure against a single Repository MUST NOT permanently invalidate other Repository DIDs for the same Package. The Client SHOULD surface a warning to the user.

---

Section 4: Portability and Migration

Publisher-initiated Repository migration

Publishers and Repositories control their own DIDs, and portability is derived from this separation.

To migrate to a new Repository:

1. The Publisher adds a FairPackageManagementRepo service endpoint to their DID pointing to the new Repository.
2. The Publisher removes the old Repository DID from alsoKnownAs in their DID, or adds the new Repository DID alongside it for a transition period.
3. The old Repository retains its DID document unchanged.

Client behavior after migration:

A Client resolving the old Repository-Isseud DID resolves the capabilityDelegation to the Publisher's DID and determines that the old Repository-Issued DID is no longer listed in alsoKnownAs. The bidirectional confirmation check fails, and the Client follows the Publisher DID's FairPackageManagementRepo service endpoint to the new Repository.

The old Repository MAY continue to serve its last copy of any release.

The Publisher MAY retain the old web DID in alsoKnownAs indefinitely for failover if they continue to update the old Repository's releases, or remove it at their sole discretion.

Install by Publisher DID (first-class resolution path)

Clients MUST support resolution beginning from a Publisher DID. The resolution path is:

1. Resolve Publisher DID → find alsoKnownAs entries referencing Repository DIDs, and/or find FairPackageManagementRepo service endpoint(s).
2. Resolve any Repository-Issued DID found and obtain the Metadata Document from the Repository.
3. Proceed with normal installation for the selected Package.

This enables tooling to support "install all Packages from this Publisher" and allows users who know a Publisher's DID to discover their Packages without knowing individual Repository-Issued DIDs. This process fully resolves fair-beacon #7.

---

Section 5: Publishers claiming Legacy Packages (Repository-Trust → Publisher-Trust)

This process transfers a Package from Repository-Trust to Publisher-Trust. Publishers of Packages being redistributed without prior engagement with DID registration may claim ownership and take control of signing functions to prove Provenance at the Publisher-Trust level. The mechanism partially resolves fair-protocol #45 & #430

Cryptographic mechanism

1. The claimant Publisher creates or designates a DID they control as the Publisher DID.
2. The claimant adds the Package's Repository-Issued DID to alsoKnownAs in their Publisher DID. This step is the claimant's half of the handshake and can be performed without the Repository's involvement.
3. The Repository verifies the claimant's identity by out-of-band means.
4. The Repository updates its Package DID document to add alsoKnownAs referencing the claimant's Publisher DID and add a capabilityDelegation entry referencing the claimant's Publisher DID for the fair_signing capability.
5. Bidirectional confirmation is established, achieving Publisher-Trust for the Package from this point forward.
6. Future releases MUST be signed with the Publisher's keys. Existing releases signed with Repository keys remain valid.

The claimant's alsoKnownAs step MUST precede the Repository's DID update. This ensures the claimant has acknowledged the Package identity before the Repository asserts a trust relationship with them. A Repository MUST NOT update the DID document to add capabilityDelegation before the claimant's alsoKnownAs entry is confirmed.

Out-of-band identity verification

Verification of the claimant's identity is the Repository's responsibility, and is outside the scope of the Protocol. The Protocol guarantees a valid cryptographic chain, but guaranteeing that the claiming party is the legitimate Publisher is a policy claim governed by the Repository redistributing the Publisher's Package(s). Repositories SHOULD document their identity verification process for claimants.

Aggregator notification

Repositories MUST emit a Package.trust-transferred event to Aggregators on completion of a claiming process so downstream services are aware the Trust Model has changed. Based on their own policies, downstream services MAY apply additional scrutiny. Aggregators MUST surface this event in Package history.

---

Section 6: Key Revocation and Existing Installations

For Packages installed prior to a key rotation, Clients MUST re-verify installed Packages against the Publisher's current keys at the next update check. If an installed Package's artifact cannot be verified against any current key in the Publisher's DID document, the Client MUST surface a warning to the user and MUST NOT install updates until verification succeeds. Since uninstallation is an explicit user action, Clients MUST NOT automatically uninstall a Package solely because its historical signature cannot be verified against current keys.

---

Spec Amendments Summary

Location	Change
Definitions	Add Publisher, retire vendor, add new terms used herein
DID Document section	Add Trust Tier detection rules, capabilityDelegation requirement for Publisher-Trust, Publisher DID precedence rule
DID Document section	Replace SHOULD NOT double-negative with explicit permission for multiple FairPackageManagementRepo services
New section: Trust Tiers	Publisher-Trust and Repository-Trust definitions, Client behavior, tier change notification
New section: Multi-Repo	Client and Aggregator selection rules, sync failure handling
New section: Portability	Migration flow, install-by-Publisher-DID resolution path
New section: Legacy Claiming	Full claiming process, identity verification note, Aggregator notification
New section: Key Revocation	Re-verification requirement, no forced uninstall

Issues Resolved

Issue	Resolution	Extent
fair-protocol #59	Double-negative SHOULD NOT replaced; multiple FairPackageManagementRepo services explicitly permitted	Full
fair-plugin #345	Protocol-level multi-service support defined; plugin implementation unblocked	Partial
[fair-plugin #430(https://github.com/fairpm/fair-plugin/issues/430)	Client selection criteria left open; latency-based selection explicitly valid	Partial
fair-beacon #7	Install-by-Publisher-DID defined as a first-class resolution path; migration flow specified
fair-protocol #49	Improves alignment between the core Protocol with the Moderation/Labelling spec & Trust Model draft by codifying DIDs for entities	Partial
fair-protocol #45	Creates a Protocol-supported method for Publishers to claim a package, but does not describe repo-level identity verification policies.	Partial

[toderash]

See PR #85