NIP-5A: Static Websites (#1538)

1 files changed, 163 insertions, 0 deletions

diff --git a/5A.md b/5A.md
new file mode 100644
index 0000000..7fe24b9
--- /dev/null
+++ b/5A.md
@@ -0,0 +1,163 @@
+NIP-5A
+======
+
+Pubkey Static Websites
+----------------------
+
+`draft` `optional`
+
+This nip describes a method by which static websites can be hosted under public keys using specialized host servers
+
+### Site Manifest Definition
+
+A site manifest event MUST be a replaceable or an addressable event as defined in [NIP-01](01.md). There are two types of site manifest event kinds:
+
+- **Root site**: Uses kind `15128` and MUST NOT include a `d` tag. This is a single replaceable event per pubkey and serves as the root site for the pubkey.
+- **Named sites**: Uses kind `35128` and MUST have a `d` tag containing the site identifier. These can be smaller websites under a pubkey and can be throught of as sub-domains.
+
+The event MUST include one or more `path` tags that map absolute paths to sha256 hashes. Each `path` tag MUST have the format `["path", "/absolute/path", "sha256hash"]` where:
+- The first element is the literal string `"path"`
+- The second element is an absolute path ending with a filename and extension
+- The third element is the sha256 hash of the file that will be served under this path
+
+The event MAY include `server` tags that hint at which blossom servers can be used to find the blobs associated with the hashes.
+
+The event MAY include `title` and `description` tags that provide simple site information.
+
+The event MAY include a `source` tag that links to the site's source code repository or source archive. The `source` tag MUST have the format `["source", "<url>"]`, where `<url>` is an absolute `http` or `https` URL.
+
+The site icon SHOULD be provided by setting the `/favicon.ico` path in the manifest.
+
+For example, a root site manifest:
+
+```jsonc
+{
+  "content": "",
+  "created_at": 1727373475,
+  "id": "5324d695ed7abf7cdd2a48deb881c93b7f4e43de702989bbfb55a1b97b35a3de",
+  "kind": 15128,
+  "pubkey": "266815e0c9210dfa324c6cba3573b14bee49da4209a9456f9484e5106cd408a5",
+  "sig": "f4e4a9e785f70e9fcaa855d769438fea10781e84cd889e3fcb823774f83d094cf2c05d5a3ac4aebc1227a4ebc3d56867286c15a6df92d55045658bb428fd5fb5",
+  "tags": [
+    // path mappings: absolute path -> sha256 hash
+    ["path", "/index.html", "186ea5fd14e88fd1ac49351759e7ab906fa94892002b60bf7f5a428f28ca1c99"],
+    ["path", "/about.html", "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456"],
+    ["path", "/favicon.ico", "fedcba0987654321fedcba0987654321fedcba0987654321fedcba0987654321"],
+    // optional: blossom server hints
+    ["server", "https://blossom.example.com"],
+    // optional: site metadata
+    ["title", "My Nostr Site"],
+    ["description", "A static website hosted on Nostr"],
+    // optional: source code location
+    ["source", "https://github.com/example/my-nostr-site"]
+  ]
+}
+```
+
+And a named site manifest:
+
+```jsonc
+{
+  "content": "",
+  "created_at": 1727373475,
+  "id": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456",
+  "kind": 35128,
+  "pubkey": "266815e0c9210dfa324c6cba3573b14bee49da4209a9456f9484e5106cd408a5",
+  "sig": "f4e4a9e785f70e9fcaa855d769438fea10781e84cd889e3fcb823774f83d094cf2c05d5a3ac4aebc1227a4ebc3d56867286c15a6df92d55045658bb428fd5fb5",
+  "tags": [
+    // site identifier
+    ["d", "blog"],
+    // path mappings: absolute path -> sha256 hash
+    ["path", "/index.html", "186ea5fd14e88fd1ac49351759e7ab906fa94892002b60bf7f5a428f28ca1c99"],
+    ["path", "/post.html", "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456"],
+    // optional: blossom server hints
+    ["server", "https://blossom.example.com"],
+    // optional: site metadata
+    ["title", "My Blog"],
+    ["description", "A blog hosted on Nostr"],
+    // optional: source code location
+    ["source", "https://github.com/example/my-nostr-blog"]
+  ]
+}
+```
+
+### Host server implementation
+
+A host server is a HTTP server that is responsible for serving pubkey static websites
+
+#### Resolving Pubkeys
+
+For interoperability, host servers SHOULD use the following canonical URL formats:
+
+- Root site: `<npub>.nsite-host.com`
+- Named site: `<pubkeyB36><dTag>.nsite-host.com`
+
+`pubkeyB36` is the author's raw 32-byte pubkey encoded with base36 (lowercase, digits `0-9` then letters `a-z`, no padding) and is always exactly 50 characters.
+
+`dTag` is the site identifier (`d` tag value) as plain text. It is appended directly after `pubkeyB36` with no separator.
+
+For canonical named-site URLs, `dTag` MUST match `^[a-z0-9-]{1,13}$` and MUST NOT end with `-`.
+
+Because DNS labels are limited to 63 characters and `pubkeyB36` uses 50 of them, `dTag` MUST be 1-13 characters.
+
+This single-label format avoids wildcard certificate limitations with multi-level subdomains.
+
+If the host server is using subdomain routing it MAY serve anything at its own root domain `nsite-host.com` (a landing page for example).
+
+Example subdomains:
+- Root site: `npub10phxfsms72rhafrklqdyhempujs9h67nye0p67qe424dyvcx0dkqgvap0e.nsite-host.com`
+- Named site: `<50-char-pubkeyB36><dTag>.nsite-host.com`
+
+#### Resolving Paths
+
+When the host server receives a request and is able to determine the pubkey and identifier, it should fetch the users `10002` [NIP-65](https://github.com/nostr-protocol/nips/blob/master/65.md) relay list and lookup the site manifest event for the pubkey and identifier.
+
+For canonical subdomain formats, the host server MUST parse the left-most DNS label as follows:
+
+1. If the label is a valid `npub`, decode it and query for the root site manifest.
+2. Otherwise, if the label matches `^[0-9a-z]{50}[a-z0-9-]{1,13}$` and does not end with `-`, treat it as a named-site label where:
+   - `pubkeyB36` is the first 50 characters
+   - `dTag` is the remaining 1-13 characters
+   - decode `pubkeyB36` to a 32-byte pubkey
+   - use `dTag` as the identifier (`d` tag value)
+
+If parsing fails, the host server MUST treat the site as not found.
+
+The host server should query for the site manifest event:
+
+```jsonc
+// For root site (kind 15128, no d tag)
+{ "kinds": [15128], "authors": [<pubkey>] }
+
+// For named site (kind 35128, with d tag)
+{ "kinds": [35128], "authors": [<pubkey>], "#d": [<identifier>] }
+```
+
+Once the site manifest event is found, the host server MUST extract the path-to-hash mappings from the `path` tags in the manifest. The host server should look for a `path` tag where the second element matches the requested path.
+
+If the request path does not end with a filename the host server MUST fallback to using the `index.html` filename
+
+For example: `/` -> `/index.html` or `/blog/` -> `/blog/index.html`
+
+#### Resolving Files
+
+Once the host server has found the site manifest event and located the matching `path` tag for the requested path, it should use the sha256 hash defined in the third element of the `path` tag to retrieve the file.
+
+The host server SHOULD prioritize using `server` tags from the site manifest event as hints for which blossom servers to query. If the manifest includes `server` tags, the host server SHOULD attempt to retrieve the file from those servers first.
+
+If the pubkey has a `10063` [BUD-03 user servers](https://github.com/hzrd149/blossom/blob/master/buds/03.md) event the server MUST attempt to retrieve the file from the listed servers using the path defined in [BUD-01](https://github.com/hzrd149/blossom/blob/master/buds/01.md#get-sha256---get-blob)
+If a pubkey does not have a `10063` event and no `server` tags are found in the manifest, the host server MUST respond with a status code 404
+
+The host server MUST forward the `Content-Type`, and `Content-Length` headers from the Blossom server. If none are defined the host server MAY set `Content-Type` from the file extension in the requested path
+
+#### Handling Not Found
+
+If a host server is unable to find a site manifest event or a matching `path` tag for the requested path, it MUST use `/404.html` as a fallback path
+
+### Legacy Support
+
+Kind `34128` is marked as legacy/deprecated. This kind was used for individual static file events where each file was represented by a separate event with a `d` tag for the path and an `x` tag for the sha256 hash.
+
+Host servers MAY still support kind `34128` for backward compatibility with existing sites, but new sites SHOULD use kind `15128` (root site manifest) or kind `35128` (named site manifest) instead.
+
+Read the [legacy version](https://github.com/hzrd149/nips/blob/41e77b45a1e8a8d170097e363f7d7254797cc5c5/nsite.md) for more details.