Initial Protocol Specification

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", <unique identifier>],
+    ["r", <comma-separated urls>],
+    ["m", <MIME type>],
+    ["client", <name>, <address>, <relay hint>],
+    ["hash", <hash method>]
+  ],
+  "content": <arbitrary string>,
+  ...
+}
+```
+
+## 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", <unique identifier>],
+    ["r", <comma-separated urls>],
+    ["a", <event id>, <relay hint>],
+    ["m", <MIME type>],
+    ["client", <name>, <address>, <relay hint>],
+    ["hash", <hash method>]
+  ],
+  "content": <arbitrary string>,
+  ...
+}
+```
+
+## 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.

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).