diff --git a/GPRS-1.md b/GPRS-1.md new file mode 100644 index 0000000..bc7444a --- /dev/null +++ b/GPRS-1.md @@ -0,0 +1,69 @@ +# GitRepublic Protocol Specification 1: Signed and Versioned Third-Party Objects + +This specification defines a protocol by which Nostr events may be used to authenticate third-party objects, which may be versioned. With Nostr, the cryptographic identity afforded by an npub/nsec keypair can be used to attest to the authenticity of an object outside of the Nostr network. Thus, the level of trust a user gives to a specific npub may be assigned to third-party objects that npub is willing to attest to. Such objects may include, but certainly are not limited to, Git commits, documents, and images. + +## Kind `32000`: Simple Third-Party Object + +An event of kind `32000` SHALL serve to authenticate an unversioned object hosted by a third-party service (i.e., not a Nostr client or relay). The `content` field MAY contain a description of the object or its contents. The following tags SHALL be used: + +- The `d` tag MUST contain a unique identifier for the object. This identifier SHOULD be a hash of the object itself to provide an additional means of validating its authenticity. +- The `r` tag MUST indicate one or more URLs at which the object can be found. +- The `m` tag MAY be included to indicate the MIME type of the object. +- The `client` tag, as defined in [NIP-89](https://github.com/nostr-protocol/nips/blob/master/89.md), MAY be included to indicate a preferred client for handling the Nostr event and its associated object. +- The `hash` tag MUST be used when the object's unique identifier is a hash to indicate the hash method used. + +### Event Format + +```json +{ + ..., + "kind": 32000, + "tags": [ + ["d", ], + ["r", ], + ["m", ], + ["client", ,
, ], + ["hash", ] + ], + "content": , + ... +} +``` + +## Kind `32001`: Versioned Third-Party Object + +An event of kind `32001` SHALL serve to authenticate a versioned object hosted by a third-party service (i.e., not a Nostr client or relay). Events of this kind MUST implement the specification for kind `32000`, along with the following rules: + +- The `a` tag MUST reference the kind `32000` or `32001` event that represents the immediately previous version of the object. +- The `d` tag MUST use as an identifier a hash of the versioned object, so that each version is uniquely identified. +- The `hash` tag MUST be included to specify the hash method used to produce the object's unique identifier. +- The initial version of an object SHOULD be represented by a kind `32000` event, and all subsequent versions MUST by represented by events of kind `32001`. + +### Event Format + +```json +{ + ..., + "kind": 32001, + "tags": [ + ["d", ], + ["r", ], + ["a", , ], + ["m", ], + ["client", ,
, ], + ["hash", ] + ], + "content": , + ... +} +``` + +## Usage Notes + +This specification is designed to provide the foundations by which file hosting and version control, akin to GitHub or SharePoint, may be implemented on Nostr. + +The first instance of any third-party object authenticated with Nostr should be a kind `32000` event, since that kind has no `a` tag antecedent. If the third-party object or its host location is changed, the changes may be versioned or unversioned. + +When the host location of an object changes, the event can simply be replaced with a new event with the same `d` tag, but updated `r` tags. Likewise, when an object with a simple ID (i.e., not a hash) is updated in-place, the change may be indicated by replacing the kind `32000` event with a new one that has the same `d` tag but a different `content`. + +Version control, such as Git or SVN, may be represented on Nostr using kinds `32000` and `32001`. In such cases, the `d` tag may be the commit or change ID, and commit details may be included in the `content`, though other schemes are certainly conceivable. For a fully versioned object, the start of that objects history would be represented by a kind `32000` event, and subsequent changes by a series of kind `32001` events, each referring to the previous change. A complete file history may be constructed from such a sequence. diff --git a/GPRS-2.md b/GPRS-2.md new file mode 100644 index 0000000..1b38f38 --- /dev/null +++ b/GPRS-2.md @@ -0,0 +1,31 @@ +# GitRepublic Protocol Specification 2: Proposing and Discussing Changes to Third-Party Objects + +This specification defines how Nostr events are to be used to propose and discuss changes to signed and versioned third-party objects described by [[GRPS-1]]. Existing NIP standards are used insofar as possible, but new event kinds are defined to avoid cluttering social media feeds. + +## Kind `12001`: Simple Comment + +An event of kind `12001` SHALL be used to broadcast a comment related to a signed (and possibly versioned) third-party object represented by kinds `32000` and `32001`. This event kind SHALL adhere to the standards for kind `1` text notes defined by [NIP-01](https://github.com/nostr-protocol/nips/blob/master/01.md), with the following modifications: + +- Kind `12001` comments SHOULD only be used as responses to existing events related to authenticating third-party objects. +- Since kind `12001` is a replaceable event, clients SHOULD support content editing of kind `12001` comments. +- An `a` tag MUST reference an event of kind `32000`, `32001`, `32023`, or `32084`. +- An `e` tag MAY reference a kind `12001` event as a preceding comment in a thread, as defined in [NIP-10](https://github.com/nostr-protocol/nips/blob/master/10.md). + +## Kind `32023`: Change Request + +An event of kind `32023` SHALL be used to propose changes to a versioned third-party object authenticated by kind `32001` events. Kind `32024` SHALL be used to store drafts of change requests. Both event kinds SHALL adhere to the [NIP-23](https://github.com/nostr-protocol/nips/blob/master/23.md) specification for long-form content. + +## Kind `32084`: Content Highlights + +An event of kind `32084` SHALL be used to comment on a specific part of a third-party object signed by a kind `32000` or `32001` event. The event SHALL adhere to the [NIP-84](https://github.com/nostr-protocol/nips/blob/master/84.md) specification for highlights, with the following particularities: + +- The `content` field MUST include the highlighted content. +- The `r` tag MUST be used to indicated one or more locations at which the highlighted content can be found. When possible, the URL given in the tag SHOULD include a content section or line number for greater specificity. +- An `a` tag MUST point to a kind `32000` or `32001` event authenticating the highlighted content. +- An `a` tag MAY point to a kind `32023` event. In such a case, the client SHOULD represent the kind `32084` highlight in a thread associated with the kind `32023` change request. +- An `a` tag MAY point to a kind `12001` event. The referenced event SHOULD be represented by the client as a comment on the highlighted content. Clients SHOULD interpret a referenced kind `12001` event that contains a diff representation as a suggested change to the highlighted content. +- The `p` tag MUST be used to tag the npub that signed the referenced kind `32000` or `32001` event. Other `p` tags MAY be included to tag other relevant npubs. + +## Usage Notes + +The standards outlined in this specification are intended to form the basis of a GitHub-like system for discussing changes to versioned objects. In such a scheme, kind `32023` would represent a pull request (and kind `32024` a draft PR). Kind `32084` would be used to comment on specific lines of code in a PR, with the `r` tag pointing to the lines of interest on a file blob. Kind `12001` would be used to add comments or responses to change requests or highlights, or even to individual commits (represented by kind `32000` and `32001` events).