nostr/nips
1
0
Fork 0
mirror of https://github.com/nostr-protocol/nips.git synced 2024-12-26 18:25:51 -05:00
Code Issues Actions Packages Projects Releases Wiki Activity

update proposal - remove f, add nip97 field

Browse Source
This commit is contained in:
Ondřej Novák 2023-08-14 12:10:07 +02:00
parent 3c88fa0fb0
commit 3ca4f98763
1 changed files with 17 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
97.md
View File

@ -10,7 +10,6 @@ Key Takeaways
* Builds on NIP-94 * Builds on NIP-94
* Defines how binary content (images, media, files) is managed by NOSTR network * Defines how binary content (images, media, files) is managed by NOSTR network
* Allows sending private binary content in direct messages (encrypted)
* Defines new commands at the protocol level ("FILE","RETRIEVE") * Defines new commands at the protocol level ("FILE","RETRIEVE")
* Uses the binary messages in the websocket connection * Uses the binary messages in the websocket connection
@ -25,7 +24,6 @@ Changes in File header (NIP-94)
"created_at": <unix timestamp in seconds>, "created_at": <unix timestamp in seconds>,
"kind": 1063, "kind": 1063,
"tags": [ "tags": [
["f","file"],
["m", <MIME type>], ["m", <MIME type>],
["x",<Hash SHA-256>], ["x",<Hash SHA-256>],
["size", <size of file in bytes>], ["size", <size of file in bytes>],
@ -35,20 +33,22 @@ Changes in File header (NIP-94)
["blurhash", <value>] ["blurhash", <value>]
], ],
"content": <description>, "content": <description>,
"sig": <64-bytes hex of the signature of the sha256 hash of the serialized event data, which is the same as the "id" field> "sig": <64-bytes hex of the signature of the sha256 hash of the serialized event data, which is the same as the "id" field>,
"nip97":true,
"file_url":"<url>
} }
``` ```
* **url is optional** - This item can be still filled with a link to an external server. This may help during the transition period when the client is uploading the file to third party servers for relays that don't support this NIP. * **url is optional** - This item can be still filled with a link to an external server. This may help during the transition period when the client is uploading the file to third party servers for relays that don't support this NIP.
* **field "nip97"** appears only when event is sent from the relay to a client. This field is added by the relay to indicate, that event also contains a binary content. The value is always `true`. This also indicates, that binary content can be received by the command `RETRIEVE` (see below). *This field SHOULD NOT be set by a client *`*`
* **field "file_url"** (optional) appears only when event is sent from the relay to a client. Its presence indicates, that the binary content can be downloaded at a given URL which is set as a value of this field. If this field is missing, then the binary connent cannot be downloaded using the http protocol, and the only way to retrieve the content is by using the command `RETRIEVE`. This field, cannot appear without the field `"nip97":true`. The client must not assume that given url is permanent and canonical. The relay can generate urls dynamically for the clients (each client can receive a different URL for the same event) *This field SHOULT NOT be set by a client*`*`
`*` - *It is allowed to publish events with these fields by using the command* `FILE`*(see below) . The relay should remove these fields during the processing of the event. It is not allowed for the command* `EVENT` * as it is currently undefined, how the relay is handling these new fields.*
* new tag **f** - it means *indexed flag*. Currently NOSTR protocol doesn't have a way to assign arbitrary flags to events. In this case, the flag has the value `file`. This field is mandatory and it's purpose is to indicate presence of a binary content associated with this event. **NOTE** - when copying events from one relay to another, the service must check for the presence of a field `"nip97":true`. If such a fields exists on the event, it must be posted using the `FILE` command with its binary content. (see below)
**NOTE** - when copying events from one relay to another, the service must check for the presence of a tag `["f":"file"]`. If such a tag exists on the event, it must also ensure that the binary content is copied as well
**Compatibility note** - Since there are probably many relays and proxies that do not support this NIP, it may happen that the event will be copied without the binary content. If a client discovers, that the relay does not have that content, or it doesn't even support this NIP, the client is not required to look for that content elsewhere, instead it can indicate to the user the unavailability of that content.
Upload Upload
------ ------
@ -64,12 +64,11 @@ client: <binary message - content of the file>
relay: ["OK",<event-id>, true, ""] relay: ["OK",<event-id>, true, ""]
``` ```
The client MUST notify the relay that it is about to send a binary file. This is just implemented by the new 'FILE' command. The command "allocates" the binary channel of the websocket connection for file transfer. This will allow this binary channel to be used for other purposes in the future. The client MUST notify the relay that it is about to send a binary file. This is just implemented by the new 'FILE' command. The command "allocates" the binary channel of the websocket connection for file transfer. This will allow this binary channel to be used for other purposes in the future.
The command parameter is a modified `file header event`(see above) which must contain the tags `x`,`m`,`f` and `size`. The command parameter is a modified `file header event`(see above) which must contain the tags `x`,`m` and `size`.
* **f** - MUST be presented with value `file`
* **x** - MUST contain SHA256 of the binary content stored as HEX * **x** - MUST contain SHA256 of the binary content stored as HEX
* **m** - MUST contain content type as mime specification. If the content type is unknown, use `application/octet-stream` * **m** - MUST contain content type as mime specification. If the content type is unknown, use `application/octet-stream`
* **size** - MUST contain size of the binary content. * **size** - MUST contain size of the binary content.
@ -78,7 +77,7 @@ The command parameter is a modified `file header event`(see above) which must co
The standard binary message is used as defined in the websocket specification. The message can be fragmented (continuation frames can be used) The standard binary message is used as defined in the websocket specification. The message can be fragmented (continuation frames can be used)
### Responses ### Responses
The relay MUST always respond with a NIP-20 response to both the command and the binary message. The relay MUST always respond with a NIP-20 response to both the command and the binary message.
@ -109,7 +108,7 @@ This proposal doesn't define response for binary messages sent without the annou
### Possible implementation - clients ### Possible implementation - clients
1. calculates SHA256 hash of the binary content 1. calculates SHA256 hash of the binary content
2. prepares the file header event, fills mandatory tags (hash, size, mime type, and flag `s:relay`) 2. prepares the file header event, fills mandatory tags (hash, size, mime type)
3. signs the file header event 3. signs the file header event
4. sends the command FILE with the event to the relay 4. sends the command FILE with the event to the relay
5. reads a response received from the relay 5. reads a response received from the relay
@ -136,14 +135,6 @@ This proposal doesn't define response for binary messages sent without the annou
9. responds with success state otherwise (on text channel), stores the binary content and publishes the event 9. responds with success state otherwise (on text channel), stores the binary content and publishes the event
**Recommendation**: A relay that supports this NIP SHOULD check if a 1063 si event is published by the `EVENT` command with the `f` flag set and reject the request.
```
client: ["EVENT",{"id","abc123","kind":1063,"tags":[["f","file"],....],....}]
relay: ["OK","abc123",false,"invalid: use command FILE"]
```
Download Download
-------- --------
@ -184,10 +175,7 @@ In this case, the relay MUST NOT generate a binary message
Retrieve the content by URL (optional) Retrieve the content by URL (optional)
-------------------------------------- --------------------------------------
If the relay caches files, for example, on CDN servers, it can announce availablity of the contnet using the "file_url" field inserted directly to the event
This part of the proposal uses the option to insert additional information into the event that is not part of the signature.
If the relay caches files, for example, on CDN servers, it can announce availablity of the contnet using the "file_url" field inserted directly to the event (do not mix with tag "url", as this information inserted by the relay and so it is not signed)
``` ```
{ {
@ -195,11 +183,12 @@ If the relay caches files, for example, on CDN servers, it can announce availabl
"kind": 1063, "kind": 1063,
"pubkey":"....", "pubkey":"....",
... ...
"nip97":true,
"file_url":"https://cdn.myrelay.example.com/file/abc123acfa7e1256a.jpg" "file_url":"https://cdn.myrelay.example.com/file/abc123acfa7e1256a.jpg"
} }
``` ```
This is optional extension, the client still can use "RETRIEVE" to download the file. This is optional extension, the client still can use "RETRIEVE" to download the file.
Changes in relay information document (NIP-11) Changes in relay information document (NIP-11)
@ -213,5 +202,5 @@ New item is added to the "limitation" section
} }
``` ```
* **max_file_size** - maximum size of binary content in bytes. This value can be greater than the value **max_message_size**. This value is mandatory for the relay supporting this NIP. The relay MUST NOT assume that **max_message_size** defines maximum size of a fragment as there are many websocket clients that are unable to control size of fragments from their API. This includes all majority browsers. * **max_file_size** - maximum size of binary content in bytes. This value can be greater than the value **max_message_size**. This value is mandatory for the relay supporting this NIP. The relay MUST NOT assume that **max_message_size** defines maximum size of a fragment as there are many websocket clients that are unable to control size of fragments from their API. This includes all majority browsers.