logicsrc/docs/openswarm/ipname.md

ipname: Names for Publishers

Version: 0.1 (draft) Status: draft. A thin bridge between the OpenSwarm core (spec.md) and the Moshpit registry. Nothing below is implemented.

1. Scope

ipname answers one question: given a name a person can type, what publisher key and what catalogue does it mean? It defines:

1. An ipname.pin record a publisher signs, served from the name's host.
2. A Moshpit registry pin kind, openswarm, that anchors that record.
3. A DNS TXT form for ordinary domains.
4. The ip:// URL.

It does not define a naming system. Moshpit names exist (label.tld, registry at pit.moshcode.sh) and DNS exists. ipname maps both to keys.

2. Terminology

Term	Meaning
name	A Moshpit name (chovy.hacker) or a DNS host (example.com).
pin	In the Moshpit registry, base64(SHA-256(SubjectPublicKeyInfo)) of a key, with a kind.
openswarm pin	A registry pin of kind openswarm over the publisher's Ed25519 SPKI (RFC 8410).
name record	The ipname.pin record at /.well-known/openswarm.json.

3. The name record

{
  "openswarm": "0.1",
  "type": "ipname.pin",
  "name": "chovy.hacker",
  "publisher": "ed25519:5d292428e8a68946e5225136c8b10e8f33ab78a45e1663d0730996dd2b63d59e",
  "feeds": [
    "ed25519:5d292428e8a68946e5225136c8b10e8f33ab78a45e1663d0730996dd2b63d59e/default",
    "ed25519:5d292428e8a68946e5225136c8b10e8f33ab78a45e1663d0730996dd2b63d59e/podcasts"
  ],
  "gateway": "https://gw.c0mpute.com",
  "hubs": ["https://coinpayportal.com/api/openswarm"],
  "mtp": "sK8m2eLwG4l3iF5oT9uYQ6c1Vb0nZxA7hE2dR8pJkLw=",
  "createdAt": "2026-09-05T18:30:00.000Z",
  "sigs": [
    {
      "alg": "ed25519",
      "key": "ed25519:5d292428e8a68946e5225136c8b10e8f33ab78a45e1663d0730996dd2b63d59e",
      "sig": "RGRH7pDpXYcagULqj+8z05pLH99Lc6yLmfdbYgtGeRpjX5l0NcT3QSq9AWBtLw+5+JJiKoZ3s4ty74q/zBSE8w=="
    }
  ]
}

Field	Rule
name	The name this record is served for. A record served under a different host MUST be refused.
publisher	The key that signs the record and every feed it lists.
feeds	Feed references (ipdb §3.1). The first is the default.
gateway	An HTTP gateway that serves this publisher's swarms and POST /db/query. MAY be null.
hubs	Hubs the publisher sells passes through.
mtp	The publisher's MTP/1 pin, if it runs a Moshpit transport endpoint. MAY be null.

The record is also put in ipdb under name:<name> in the default feed, so a replica that has the feed can answer the reverse question: what names does this key claim.

4. Resolution

4.1 Moshpit names

A Moshpit name has exactly two labels of letters and digits. The registry holds a target host and a list of pins per name. ipname uses both:

1. GET https://pit.moshcode.sh/api/moshpit/pins?name=chovy.hacker returns { "name", "pins": [...], "target" }. Pins are objects or strings depending on the registry version; the resolver looks for entries of kind openswarm.
2. Fetch https://<target>/.well-known/openswarm.json (through moshpit-proxy when the target is itself a Moshpit name, plain HTTPS when it is a clearnet host).
3. Compute base64(SHA-256(SPKI(record.publisher))) and require it to equal an openswarm pin. Verify the record signature. Require record.name to equal the queried name.

The registry pin is the anchor. The registry is not trusted for the key itself; it is trusted to say which hash the name's owner registered, and the owner's key is whatever hashes to that. This is the same argument moshpit-proxy makes for TLS pins and qrypt.chat makes for mtp pins, and the pin format is byte-identical so one registry field carries all three kinds.

Writing the pin is one registry call by the name's owner:

POST https://app.moshcode.sh/api/moshpit/tlds/hacker/pins
Authorization: Bearer <MOSHPIT_API_KEY>
{ "label": "chovy", "pin": "base64...", "kind": "openswarm", "note": "OpenSwarm publisher key" }

kind: "openswarm" does not exist in the registry today; adding it is a one-line change to the accepted kinds and is listed as an open question.

4.2 House policy: clearnet first

Moshpit's prefer rule applies unchanged: a name that resolves on the public DNS root is a clearnet host by default, and the registry is consulted only in fallback or moshpit mode. ipname MUST use @moshcoder/moshpit-resolve's decideResolution (or an equivalent) before touching the registry, so that example.com is never redirected to a pit record because someone claimed .com as an ending.

4.3 DNS hosts

For a clearnet host, the anchor is a TXT record:

_openswarm.example.com.  IN TXT  "v=openswarm1; key=ed25519:5d292428e8a68946e5225136c8b10e8f33ab78a45e1663d0730996dd2b63d59e"

The resolver fetches https://example.com/.well-known/openswarm.json and requires record.publisher to equal the TXT key. Without the TXT record the resolver MAY accept the well-known record on the strength of TLS alone and MUST report the lower assurance to the caller ("anchor": "tls" rather than "anchor": "dns" or "anchor": "moshpit").

4.4 Caching

A resolved name is cached for the shorter of 300 seconds and the registry's own TTL, matching moshpit-proxy's pin cache. A negative result is cached for 5 seconds.

5. The ip URL

ip://<name or key>[/<feed>[/<key>]]

Example	Meaning
ip://chovy.hacker	The publisher's default feed.
ip://chovy.hacker/podcasts	A named feed.
ip://chovy.hacker/default/track:sha256:d6c3f8285b7871d6a400cba14408288a9acde679f12e1e7dc276f29ca7c493ff	One record by ipdb key.
ip://ed25519:5d292428e8a68946e5225136c8b10e8f33ab78a45e1663d0730996dd2b63d59e	The same publisher by key; no name resolution.
ip://ed25519:0d87e09c7fea3ad6ba6c2f3e027ea47f5b245452899910948470906704c5295d?file	A file by its file key: BEP 44 lookup, no feed.

A gateway maps ip:// to HTTPS: https://<gateway>/ip/<name or key>/... with the same path. A magnet: link with xs=urn:btpk:<file key>&s=ipfile is the BitTorrent-native equivalent of the last row and opens in any BEP 46 client, which then needs the ipfile extension to do anything with it.

6. Security notes

• Registry compromise can change a pin. A resolver that has seen a name before SHOULD keep the last verified publisher key and warn on change, the way moshpit-proxy handles a pin rotation with MOSHPIT_PROXY_TOFU.
• Host compromise can serve a different record, which fails the pin.
• Name squatting is the registry's problem, and only the ending owner can mint names under it.
• Privacy: resolving a name tells the registry which names a client asks about, as DNS does. A client that already holds a key never resolves.

7. Events

None. Name changes surface as ipdb.entry.appended for name:<name>.

8. Implementations

Piece	Exists	Where	What is new
Registry with per-name pins of kind tls and mtp	Yes	pit.moshcode.sh, moshpit_name_pins	The openswarm kind
Pin lookup, cache, TOFU handling	Yes	moshpit-proxy lib/pins.ts	Reuse as the resolver's registry client
Clearnet-first decision	Yes	@moshcoder/moshpit-resolve	Called before any registry lookup
Name record, TXT form, ip:// URL	No		All of it

9. Conformance

A resolver implements §4.1 to §4.4, refuses a record whose name or pin does not match, and reports the anchor kind. A publisher serves the record at the well-known path over HTTPS and keeps it in ipdb.

10. Version history

Version	Date	Change
0.1	2026-09-05	Initial draft.