From f9c48b38c0e58119fb9b1cdc38a9179586826414 Mon Sep 17 00:00:00 2001 From: hzrd149 <8001706+hzrd149@users.noreply.github.com> Date: Wed, 25 Mar 2026 11:07:23 -0500 Subject: NIP-5A: Static Websites (#1538) --- 5A.md | 163 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 163 insertions(+) create mode 100644 5A.md 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", ""]`, where `` 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: `.nsite-host.com` +- Named site: `.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>.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": [] } + +// For named site (kind 35128, with d tag) +{ "kinds": [35128], "authors": [], "#d": [] } +``` + +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. -- cgit v1.2.3