mirror of
https://github.com/nostr-protocol/nips.git
synced 2024-12-23 00:45:53 -05:00
148 lines
9.0 KiB
Markdown
148 lines
9.0 KiB
Markdown
# NIP-101 - Forms On Nostr
|
|
|
|
`draft` `optional` `author:abhay-raizada`
|
|
|
|
The nip provides a way for users to create form templates on nostr, and for other users to be able to fill them.
|
|
|
|
## Form Template - Public
|
|
|
|
Event `30168` describes a form as a parametrized replaceable event, with `field` tags that contain the description of each form field, with optional settings
|
|
|
|
```js
|
|
{
|
|
"kind": 30168,
|
|
"content" : ""
|
|
"tags": [
|
|
["d", "<form identifier>"],
|
|
["name", "Name of the form"],
|
|
["settings", JSON.stringify({description: "<description of the form."})],
|
|
["field", "<fieldId>","<input-type>","<label for the field>","<Options (for option type)>", "<stringified JSON settings>"],
|
|
["field", "<fieldId>", "option", "label for options field",
|
|
JSON.stringify([["<optionId1>", "option label", "<optionId2>", "option label"]]),
|
|
"<stringified JSON settings>"
|
|
]
|
|
],
|
|
"pubkey": "<Author of the form>"
|
|
}
|
|
```
|
|
|
|
The different tags used to detail the form are described as:
|
|
|
|
| Tags | Description |
|
|
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
| d | The unique identifier of a form, for a user |
|
|
| name | A text serving as the name of the form |
|
|
| settings | An optional global config for the form. |
|
|
| field | Contains the following values<table><tr><th>index</th><th>name</th><th>description</th></tr><tbody><tr><td>1</td><td>FieldId</td><td>an id that uniqely identifies a field in the forn</td></tr><tr><td>2</td><td>input-type</td><td>A field that describes the type of value that can be expected as a response to this field, values can be: `text`, `option` or `label`</td></tr><tr><td>3</td><td>label</td><td>A label for the field</td></tr><tr><td>4</td><td>options</td> <td>Only used for input-type option, is a Json stringified array of option Tags. |
|
|
| Option Tags | Option Tags are defined as: [`<OptionId`>, <`label`>, `<optional config>`], optionId can be any alphanumeric string </td> </tr><tr><td>5</td><td>fieldSettings</td><td>An optional JSON stringified object that contains settings specific to the field, for example `renderElement`, a setting which indicates what UI element to render to the client </td></tr> |
|
|
|
|
</tbody></table>
|
|
|
|
## Responses - Public
|
|
|
|
Response events are also parametrized replaceable events that are attached to a form(3068 kind event), and the event data is stored in a `kind: 30169` event
|
|
|
|
Response structure:
|
|
|
|
```json
|
|
{
|
|
"kind": 30169,
|
|
"content": "",
|
|
"tags": [
|
|
["d", "<pubkey of the form author>:<form identifier>"],
|
|
["a", "30168:<pubkey of the author>:<form identifier>"],
|
|
[
|
|
"response",
|
|
"<FieldId>",
|
|
"<response as string>",
|
|
"<stringified metadata object>"
|
|
]
|
|
],
|
|
"pubkey": "Author of Response"
|
|
}
|
|
```
|
|
|
|
The Response tag contains a "response" tag identifier "fieldId" the Id of the field as mentioned in the `kind:30168` event, response for the field as a string value, and a stringified metadata object.
|
|
|
|
for option fields, the response is the id of the option selected. In case of multiple-choice fields these id's maybe delimited by a semi-colon, ";", For example:
|
|
|
|
```json
|
|
{
|
|
"kind": 30169,
|
|
"content": "",
|
|
"tags": [
|
|
["a", "30168:<pubkey of the author>:<form identifier>"],
|
|
[
|
|
"response",
|
|
"<FieldId>",
|
|
"ZCZC;XCZXCZ;Z34Z",
|
|
"<stringified metadata object>"
|
|
]
|
|
],
|
|
"pubkey": "Response author"
|
|
}
|
|
```
|
|
|
|
## Access Control
|
|
|
|
In general access is granted by signing the event and encrypting the content with different keys.
|
|
the mechanism to share the keys is by encrypting the keys and adding it as key-tags in the event, as well as adding p-tags to notify users.
|
|
The key tag for `kind:30168` events, should look like.
|
|
|
|
`["key","<pubkey for the user>", "<optional relays>", "<Encrypted-View-Key>", "<Encrypted-Signing-key>"]`
|
|
|
|
`View-key` : generated during form-creation, this key should used to encrypt/decrypt the `".content"` string in the form template.
|
|
`Edit-key/Signing-Key`: Is the key which is used to sign the 30168 event.
|
|
|
|
Encryption should be via [nip-44](./44.md) using the conversation key derived from the p-tags pubkey and the signing-key.
|
|
|
|
`Encrypted View Key`: The view key should be encrypted as `nip44.encrypt(<View Key>, <Coversation Key derived from users public key and the signing key>)`
|
|
|
|
`Encrypted Signing Key`: The view key should be encrypted as `nip44.encrypt(<Signing Key>, <Coversation Key derived from users public key and the signing key>)`
|
|
|
|
In case a participant is a viewer and an editor, both the keys should be added in their "key" tag.
|
|
In case participant is only a viewer the editor key maybe left blank.
|
|
|
|
### Public Forms Public Responses
|
|
|
|
Both the form and the responses are kept unencrypted in the `tags` array and signed by the respective users. Useful for cases like polls.
|
|
|
|
### Encrypted Responses.
|
|
|
|
Response tags are added to the `.content` field of the event and encrypted as per the spec in [nip-44](./44.md) by the responders private key and the form authors public key.
|
|
|
|
### Private Forms only viewable by a group.
|
|
|
|
Form fields should be placed in the `.content` key, nip-44 encrypted by the corresponding public key of the view-key, and the signing key. The selected responders can decrypt the form using the view key. The `tags` array is used to keep track of the allowed-responders identities.
|
|
|
|
```js
|
|
let encryptionKey = nip44.v2.utils.getConversationKey(
|
|
bytesToHex(signingKey),
|
|
getPublicKey(viewKey)
|
|
);
|
|
content = nip44.v2.encrypt(JSON.stringify(form), encryptionKey);
|
|
```
|
|
|
|
### Public forms editable by a group.
|
|
|
|
A signing key is generated for the group.
|
|
Form fields are in the tag array, and the signing-key is encrypted in the key tag like:
|
|
`["key", "<pub-key with edit access>", "<relays>","","<encrypted signing key>"]`.
|
|
The key should be the same that the `30168` event is signed with.
|
|
The pubkeys with edit access, will also be able to view the form responses.
|
|
|
|
Encrypted signing key can be calculated as:
|
|
|
|
```js
|
|
let conversationKey = nip44.v2.utils.getConversationKey(
|
|
bytesToHex(signingKey),
|
|
npubHex
|
|
);
|
|
let encyptedKey = nip44.v2.encrypt(bytesToHex(signingKey), conversationKey);
|
|
```
|
|
|
|
### Private forms editable by a group.
|
|
|
|
The rest of the mechanism remains same as in public forms editable by a group except that the
|
|
form fields should be placed in the `.content` key, encrypted by a `view-key`, which is shared in the 3rd index of the key tag for the viewers.
|