diff --git a/98.md b/98.md new file mode 100644 index 00000000..ecbebc08 --- /dev/null +++ b/98.md @@ -0,0 +1,68 @@ +NIP-98 +====== + +HTTP Auth +------------------------- + +`draft` `optional` `author:kieran` `author:melvincarvalho` + +This NIP defines an ephemerial event used to authorize requests to HTTP servers using nostr events. + +This is useful for HTTP services which are build for Nostr and deal with Nostr user accounts. + +## 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. + +The following tags are defined as REQUIRED. + +* `u` - absolute URL +* `method` - HTTP Request Method + +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" +} +``` + +Servers MUST perform the following checks in order to validate the event: +1. The `kind` MUST be `27235`. +2. The `created_at` MUST be within a reasonable time window (suggestion 60 seconds). +3. The `u` tag MUST be exactly the same as the absolute request URL (including query parameters). +4. The `method` tag MUST be the same HTTP method used for the requested resource. + +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", ""]`), 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. + +All other checks which server MAY do are OPTIONAL, and implementation specific. + +## Request Flow + +Using the `Authorization` header, the `kind 27235` event MUST be `base64` encoded and use the Authorization scheme `Nostr` + +Example HTTP Authorization header: +``` +Authorization: Nostr eyJpZCI6ImZlOTY0ZTc1ODkwMzM2MGYyOGQ4NDI0ZDA5MmRhODQ5NGVkMjA3Y2JhODIzMTEwYmUzYTU3ZGZlNGI1Nzg3MzQiLCJwdWJrZXkiOiI2M2ZlNjMxOGRjNTg1ODNjZmUxNjgxMGY4NmRkMDllMThiZmQ3NmFhYmMyNGEwMDgxY2UyODU2ZjMzMDUwNGVkIiwiY29udGVudCI6IiIsImtpbmQiOjI3MjM1LCJjcmVhdGVkX2F0IjoxNjgyMzI3ODUyLCJ0YWdzIjpbWyJ1cmwiLCJodHRwczovL2FwaS5zbm9ydC5zb2NpYWwvYXBpL3YxL241c3AvbGlzdCJdLFsibWV0aG9kIiwiR0VUIl1dLCJzaWciOiI1ZWQ5ZDhlYzk1OGJjODU0Zjk5N2JkYzI0YWMzMzdkMDA1YWYzNzIzMjQ3NDdlZmU0YTAwZTI0ZjRjMzA0MzdmZjRkZDgzMDg2ODRiZWQ0NjdkOWQ2YmUzZTVhNTE3YmI0M2IxNzMyY2M3ZDMzOTQ5YTNhYWY4NjcwNWMyMjE4NCJ9 +``` + +## Reference Implementations +- C# ASP.NET `AuthenticationHandler` [NostrAuth.cs](https://gist.github.com/v0l/74346ae530896115bfe2504c8cd018d3) \ No newline at end of file diff --git a/README.md b/README.md index a940ba60..ca2e6881 100644 --- a/README.md +++ b/README.md @@ -64,6 +64,7 @@ They exist to document what may be implemented by [Nostr](https://github.com/nos - [NIP-78: Application-specific data](78.md) - [NIP-89: Recommended Application Handlers](89.md) - [NIP-94: File Metadata](94.md) +- [NIP-98: HTTP Auth](98.md) ## Event Kinds @@ -95,6 +96,7 @@ They exist to document what may be implemented by [Nostr](https://github.com/nos | `23194` | Wallet Request | [47](47.md) | | `23195` | Wallet Response | [47](47.md) | | `24133` | Nostr Connect | [46](46.md) | +| `27235` | HTTP Auth | [98](98.md) | | `30000` | Categorized People List | [51](51.md) | | `30001` | Categorized Bookmark List | [51](51.md) | | `30008` | Profile Badges | [58](58.md) |