nips/98.md

63 lines
2.6 KiB
Markdown
Raw Normal View History

2023-04-24 05:32:03 -04:00
NIP-98
======
HTTP Auth
---------
2023-04-24 05:32:03 -04:00
2023-11-15 19:42:51 -05:00
`draft` `optional`
2023-04-24 05:32:03 -04:00
2023-09-08 04:09:02 -04:00
This NIP defines an ephemeral event used to authorize requests to HTTP servers using nostr events.
2023-04-24 05:32:03 -04:00
2023-09-08 04:09:02 -04:00
This is useful for HTTP services which are built for Nostr and deal with Nostr user accounts.
2023-04-24 05:32:03 -04:00
## Nostr event
A `kind 27235` (In reference to [RFC 7235](https://www.rfc-editor.org/rfc/rfc7235)) event is used.
The `content` SHOULD be empty.
2023-09-08 04:09:02 -04:00
The following tags MUST be included.
2023-04-24 05:32:03 -04:00
2023-04-24 05:56:04 -04:00
* `u` - absolute URL
* `method` - HTTP Request Method
2023-04-24 05:32:03 -04:00
Example event:
```json
{
"id": "fe964e758903360f28d8424d092da8494ed207cba823110be3a57dfe4b578734",
"pubkey": "63fe6318dc58583cfe16810f86dd09e18bfd76aabc24a0081ce2856f330504ed",
"content": "",
"kind": 27235,
"created_at": 1682327852,
"tags": [
["u", "https://api.snort.social/api/v1/n5sp/list"],
["method", "GET"]
],
"sig": "5ed9d8ec958bc854f997bdc24ac337d005af372324747efe4a00e24f4c30437ff4dd8308684bed467d9d6be3e5a517bb43b1732cc7d33949a3aaf86705c22184"
2023-04-24 05:32:03 -04:00
}
```
Servers MUST perform the following checks in order to validate the event:
1. The `kind` MUST be `27235`.
2023-09-08 04:09:02 -04:00
2. The `created_at` timestamp MUST be within a reasonable time window (suggestion 60 seconds).
2023-06-17 13:49:02 -04:00
3. The `u` tag MUST be exactly the same as the absolute request URL (including query parameters).
2023-04-24 05:32:03 -04:00
4. The `method` tag MUST be the same HTTP method used for the requested resource.
2023-04-24 05:56:04 -04:00
When the request contains a body (as in POST/PUT/PATCH methods) clients SHOULD include a SHA256 hash of the request body in a `payload` tag as hex (`["payload", "<sha256-hex>"]`), servers MAY check this to validate that the requested payload is authorized.
If one of the checks was to fail the server SHOULD respond with a 401 Unauthorized response code.
2023-09-08 04:09:02 -04:00
Servers MAY perform additional implementation-specific validation checks.
2023-04-24 05:32:03 -04:00
## Request Flow
2023-09-08 04:09:02 -04:00
Using the `Authorization` HTTP header, the `kind 27235` event MUST be `base64` encoded and use the Authorization scheme `Nostr`
2023-04-24 05:32:03 -04:00
Example HTTP Authorization header:
```
Authorization: Nostr eyJpZCI6ImZlOTY0ZTc1ODkwMzM2MGYyOGQ4NDI0ZDA5MmRhODQ5NGVkMjA3Y2JhODIzMTEwYmUzYTU3ZGZlNGI1Nzg3MzQiLCJwdWJrZXkiOiI2M2ZlNjMxOGRjNTg1ODNjZmUxNjgxMGY4NmRkMDllMThiZmQ3NmFhYmMyNGEwMDgxY2UyODU2ZjMzMDUwNGVkIiwiY29udGVudCI6IiIsImtpbmQiOjI3MjM1LCJjcmVhdGVkX2F0IjoxNjgyMzI3ODUyLCJ0YWdzIjpbWyJ1cmwiLCJodHRwczovL2FwaS5zbm9ydC5zb2NpYWwvYXBpL3YxL241c3AvbGlzdCJdLFsibWV0aG9kIiwiR0VUIl1dLCJzaWciOiI1ZWQ5ZDhlYzk1OGJjODU0Zjk5N2JkYzI0YWMzMzdkMDA1YWYzNzIzMjQ3NDdlZmU0YTAwZTI0ZjRjMzA0MzdmZjRkZDgzMDg2ODRiZWQ0NjdkOWQ2YmUzZTVhNTE3YmI0M2IxNzMyY2M3ZDMzOTQ5YTNhYWY4NjcwNWMyMjE4NCJ9
```
2023-05-08 07:21:30 -04:00
## Reference Implementations
2023-09-08 04:09:02 -04:00
- C# ASP.NET `AuthenticationHandler` [NostrAuth.cs](https://gist.github.com/v0l/74346ae530896115bfe2504c8cd018d3)