From e299dcf35885528307c6b09369047fea4ed2503b Mon Sep 17 00:00:00 2001 From: Michael J <37635304+buttercat1791@users.noreply.github.com> Date: Sun, 7 Jan 2024 21:14:33 -0600 Subject: [PATCH 1/8] Define basic Nostr event kind for commit notes --- GPRS-1.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 GPRS-1.md diff --git a/GPRS-1.md b/GPRS-1.md new file mode 100644 index 0000000..b5a5e0d --- /dev/null +++ b/GPRS-1.md @@ -0,0 +1,57 @@ +# GitRepublic Protocol Specification 1: Signed Third-Party Objects + +This specification defines a protocol by which Nostr events may be used to sign third-party objects. With Nostr, the cryptographic identity afforded by an npub/nsec keypair can be used to verify the authenticity of an object accessible via some third-party server or protocol. Such objects may include, but certainly are not limited to, Git commits, files, and images. The level of trust a user gives to a given npub may, by extension, be given to third-party objects signed by that npub. + +## Nostr Event Kinds + +Nostr parameterized replaceable events of kinds in the range `32000 <= n < 32099` MAY be used in relation to third-party object signing. Where possible, these events adhere to standards proposed by existing Nostr Improvement Possibilities (NIPs). Nostr clients uninterested in signed third-party objects can simply ignore this kind range to avoid cluttering up their event feeds. + +### Kind `32001`: Third-Party Object Authentication + +### Event Specification + +An event of kind `32001` SHALL serve to authenticate an 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 `a` tag MAY be used to refer to the kind `32001` event that authenticated the immediately previous version of the object. +- 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. + +### Event Format + +```json +{ + ..., + "kind": 32001, + "tags": [ + ["d", ], + ["r", ], + ["a", , ], + ["m", ], + ["client", ,
, ] + ], + "content": , + ... +} +``` + +### Example Usage + +One possible usage of this specification is to use a Nostr note to digitally sign a Git commit in a hosted repository. In this case, the `d` identifier can be the unique SHA-1 hash of the Git commit object, and the `r` tag can be used to indicate one or more URLs that have a copy of the repository containing that commit. The `a` tag can point to the kind `32001` note that authenticated the previous commit. The `content` field may contain the commit message itself, information about the commit, branch, or repository; or it may be left blank. + +```json +{ + ..., + "kind": 32001, + "tags": [ + ["d", "1636e6a2cc7e77cefd8c74719b27bdc59c937c0e"], + ["a", "32001:npub1s3ht77dq4zqnya8vjun5jp3p44pr794ru36d0ltxu65chljw8xjqd975wz:6bec40bf5ec866b81faf5336579e38b0ad75e167", "wss://relay.damus.io"], + ["r", "https://github.com/ShadowySupercode/GitRepublic.git"] + ], + "content": "Update README.md with Nostr note links", + ... +} +``` + +When this event is signed and published, anyone who trusts the publishing npub will have all the information they need to find and fetch the commit, and to use Git to reconstruct the repository history up to the point of that commit. From fd77af73aa29ffafa2ecd49dc985446d99ce32be Mon Sep 17 00:00:00 2001 From: Michael J <37635304+buttercat1791@users.noreply.github.com> Date: Mon, 8 Jan 2024 08:09:04 -0600 Subject: [PATCH 2/8] Define two basic event kinds for 3rd-party objects --- GPRS-1.md | 42 +++++++++++++++++++++++++++--------------- 1 file changed, 27 insertions(+), 15 deletions(-) diff --git a/GPRS-1.md b/GPRS-1.md index b5a5e0d..907272b 100644 --- a/GPRS-1.md +++ b/GPRS-1.md @@ -2,19 +2,16 @@ This specification defines a protocol by which Nostr events may be used to sign third-party objects. With Nostr, the cryptographic identity afforded by an npub/nsec keypair can be used to verify the authenticity of an object accessible via some third-party server or protocol. Such objects may include, but certainly are not limited to, Git commits, files, and images. The level of trust a user gives to a given npub may, by extension, be given to third-party objects signed by that npub. -## Nostr Event Kinds +## Nostr Event Kind Reservation Nostr parameterized replaceable events of kinds in the range `32000 <= n < 32099` MAY be used in relation to third-party object signing. Where possible, these events adhere to standards proposed by existing Nostr Improvement Possibilities (NIPs). Nostr clients uninterested in signed third-party objects can simply ignore this kind range to avoid cluttering up their event feeds. -### Kind `32001`: Third-Party Object Authentication +## Kind `32000`: Simple Third-Party Object -### Event Specification - -An event of kind `32001` SHALL serve to authenticate an 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: +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 `a` tag MAY be used to refer to the kind `32001` event that authenticated the immediately previous version of the object. - 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. @@ -23,11 +20,10 @@ An event of kind `32001` SHALL serve to authenticate an object hosted by a thir ```json { ..., - "kind": 32001, + "kind": 32000, "tags": [ ["d", ], ["r", ], - ["a", , ], ["m", ], ["client", ,
, ] ], @@ -36,22 +32,38 @@ An event of kind `32001` SHALL serve to authenticate an object hosted by a thir } ``` -### Example Usage +## 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`. Such events SHALL observe the following rules for version management: -One possible usage of this specification is to use a Nostr note to digitally sign a Git commit in a hosted repository. In this case, the `d` identifier can be the unique SHA-1 hash of the Git commit object, and the `r` tag can be used to indicate one or more URLs that have a copy of the repository containing that commit. The `a` tag can point to the kind `32001` note that authenticated the previous commit. The `content` field may contain the commit message itself, information about the commit, branch, or repository; or it may be left blank. +- The `a` tag MUST reference the kind `32000` or `32001` event that represents the immediately previous version of the object. +- The `d` tag MUST give as an identifier a hash of the versioned object, so that each version has a unique hash. +- The initial version of an object SHOULD be represented by a kind `32000` event, and all subsequent versions SHOULD by represented by events of kind `32001`. + +### Event Format ```json { ..., "kind": 32001, "tags": [ - ["d", "1636e6a2cc7e77cefd8c74719b27bdc59c937c0e"], - ["a", "32001:npub1s3ht77dq4zqnya8vjun5jp3p44pr794ru36d0ltxu65chljw8xjqd975wz:6bec40bf5ec866b81faf5336579e38b0ad75e167", "wss://relay.damus.io"], - ["r", "https://github.com/ShadowySupercode/GitRepublic.git"] + ["d", ], + ["r", ], + ["a", , ], + ["m", ], + ["client", ,
, ] ], - "content": "Update README.md with Nostr note links", + "content": , ... } ``` -When this event is signed and published, anyone who trusts the publishing npub will have all the information they need to find and fetch the commit, and to use Git to reconstruct the repository history up to the point of that commit. +## 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`. For a fully version-controlled 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 representing the previous change. A complete file history may be constructed from such an event sequence. From 5da02eacb191d41f6d706d24edb3604e1edb1e31 Mon Sep 17 00:00:00 2001 From: Michael J <37635304+buttercat1791@users.noreply.github.com> Date: Tue, 9 Jan 2024 07:31:50 -0600 Subject: [PATCH 3/8] Require that hash method be specified for hash-based IDs --- GPRS-1.md | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/GPRS-1.md b/GPRS-1.md index 907272b..9f4a21c 100644 --- a/GPRS-1.md +++ b/GPRS-1.md @@ -1,6 +1,6 @@ -# GitRepublic Protocol Specification 1: Signed Third-Party Objects +# GitRepublic Protocol Specification 1: Signed and Versioned Third-Party Objects -This specification defines a protocol by which Nostr events may be used to sign third-party objects. With Nostr, the cryptographic identity afforded by an npub/nsec keypair can be used to verify the authenticity of an object accessible via some third-party server or protocol. Such objects may include, but certainly are not limited to, Git commits, files, and images. The level of trust a user gives to a given npub may, by extension, be given to third-party objects signed by that npub. +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, files, and images. ## Nostr Event Kind Reservation @@ -14,6 +14,7 @@ An event of kind `32000` SHALL serve to authenticate an unversioned object host - 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 @@ -25,7 +26,8 @@ An event of kind `32000` SHALL serve to authenticate an unversioned object host ["d", ], ["r", ], ["m", ], - ["client", ,
, ] + ["client", ,
, ], + ["hash", ] ], "content": , ... @@ -34,11 +36,12 @@ An event of kind `32000` SHALL serve to authenticate an unversioned object host ## 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`. Such events SHALL observe the following rules for version management: +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 give as an identifier a hash of the versioned object, so that each version has a unique hash. -- The initial version of an object SHOULD be represented by a kind `32000` event, and all subsequent versions SHOULD by represented by events of kind `32001`. +- 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 @@ -51,7 +54,8 @@ An event of kind `32001` SHALL serve to authenticate a versioned object hosted b ["r", ], ["a", , ], ["m", ], - ["client", ,
, ] + ["client", ,
, ], + ["hash", ] ], "content": , ... @@ -66,4 +70,4 @@ The first instance of any third-party object authenticated with Nostr should be 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`. For a fully version-controlled 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 representing the previous change. A complete file history may be constructed from such an event sequence. +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. From 11d1746fc8a1a9e57f014ecca05b8bc3af612752 Mon Sep 17 00:00:00 2001 From: Michael J <37635304+buttercat1791@users.noreply.github.com> Date: Tue, 9 Jan 2024 08:34:23 -0600 Subject: [PATCH 4/8] Remove event kind range reservation --- GPRS-1.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/GPRS-1.md b/GPRS-1.md index 9f4a21c..6391277 100644 --- a/GPRS-1.md +++ b/GPRS-1.md @@ -2,10 +2,6 @@ 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, files, and images. -## Nostr Event Kind Reservation - -Nostr parameterized replaceable events of kinds in the range `32000 <= n < 32099` MAY be used in relation to third-party object signing. Where possible, these events adhere to standards proposed by existing Nostr Improvement Possibilities (NIPs). Nostr clients uninterested in signed third-party objects can simply ignore this kind range to avoid cluttering up their event feeds. - ## 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: From d4357f918b67d73dd55899338495290de2be8337 Mon Sep 17 00:00:00 2001 From: Michael J <37635304+buttercat1791@users.noreply.github.com> Date: Tue, 9 Jan 2024 08:35:28 -0600 Subject: [PATCH 5/8] Add specification for third-party object discussions --- GPRS-2.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 GPRS-2.md diff --git a/GPRS-2.md b/GPRS-2.md new file mode 100644 index 0000000..b436af0 --- /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 `a` tag MAY reference a kind `12001` event as a preceding comment in a thread. + +## 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). From f085e2ace1be46fd49653f8ce5f38ad9e3479b46 Mon Sep 17 00:00:00 2001 From: Michael J <37635304+buttercat1791@users.noreply.github.com> Date: Tue, 9 Jan 2024 08:51:39 -0600 Subject: [PATCH 6/8] Use relative link to GPRS-1 --- GPRS-2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/GPRS-2.md b/GPRS-2.md index b436af0..e39f29f 100644 --- a/GPRS-2.md +++ b/GPRS-2.md @@ -1,6 +1,6 @@ # 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. +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](./GPRS-1.md). Existing NIP standards are used insofar as possible, but new event kinds are defined to avoid cluttering social media feeds. ## Kind `12001`: Simple Comment From 42a521c19a3cda6e31a44eccbd126646d5859283 Mon Sep 17 00:00:00 2001 From: Michael J <37635304+buttercat1791@users.noreply.github.com> Date: Wed, 10 Jan 2024 17:10:04 -0600 Subject: [PATCH 7/8] Suggest file versioning as possible use case --- GPRS-1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/GPRS-1.md b/GPRS-1.md index 6391277..bc7444a 100644 --- a/GPRS-1.md +++ b/GPRS-1.md @@ -1,6 +1,6 @@ # 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, files, and images. +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 From 925c513da651de6bb0ebda1afb1e9c52bb833aee Mon Sep 17 00:00:00 2001 From: Michael J <37635304+buttercat1791@users.noreply.github.com> Date: Wed, 10 Jan 2024 17:10:33 -0600 Subject: [PATCH 8/8] Use NIP-10 for replies in thread --- GPRS-2.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/GPRS-2.md b/GPRS-2.md index e39f29f..1b38f38 100644 --- a/GPRS-2.md +++ b/GPRS-2.md @@ -1,6 +1,6 @@ # 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](./GPRS-1.md). Existing NIP standards are used insofar as possible, but new event kinds are defined to avoid cluttering social media feeds. +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 @@ -9,7 +9,7 @@ An event of kind `12001` SHALL be used to broadcast a comment related to a signe - 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 `a` tag MAY reference a kind `12001` event as a preceding comment in a thread. +- 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