smp-server: support namespaces

protocol/simplex-messaging.md

@@ -1,4 +1,4 @@
-Version 19, 2025-01-24
+Version 20, 2026-05-25
 
 # Simplex Messaging Protocol (SMP)
 
@@ -67,6 +67,9 @@ Version 19, 2025-01-24
     - [Queue deleted notification](#queue-deleted-notification)
     - [Error responses](#error-responses)
     - [OK response](#ok-response)
+  - [Resolver commands](#resolver-commands)
+    - [Resolve name command](#resolve-name-command)
+    - [Name record response](#name-record-response)
 - [Transport connection with the SMP router](#transport-connection-with-the-SMP-router)
   - [General transport protocol considerations](#general-transport-protocol-considerations)
   - [TLS transport encryption](#tls-transport-encryption)
@@ -83,7 +86,7 @@ It's designed with the focus on communication security and integrity, under the
 
 It is designed as a low level protocol for other application protocols to solve the problem of secure and private message transmission, making [MITM attack][1] very difficult at any part of the message transmission system.
 
-This document describes SMP protocol version 19. Versions 1-5 are discontinued. The version history:
+This document describes SMP protocol version 20. Versions 1-5 are discontinued. The version history:
 
 - v1: binary protocol encoding
 - v2: message flags (used to control notifications)
@@ -103,6 +106,7 @@ This document describes SMP protocol version 19. Versions 1-5 are discontinued.
 - v17: create notification credentials with NEW command
 - v18: support client notices in BLOCKED error
 - v19: service subscriptions to messages (SUBS, NSUBS, SOKS, ENDS, ALLS commands)
+- v20: public namespaces resolver (RSLV command, NAME response) — forwarded-only via PFWD
 
 ## Introduction
 
@@ -424,6 +428,8 @@ Simplex messaging router implementations MUST NOT create, store or send to any o
 
 - Any other information that may compromise privacy or [forward secrecy][4] of communication between clients using simplex messaging routers (the routers cannot compromise forward secrecy of any application layer protocol, such as double ratchet).
 
+Routers with the names role make outbound HTTP calls to a backing resolver service (the reference implementation is `scripts/resolver/snrc-resolve.py`, which in turn makes JSON-RPC calls to an Ethereum endpoint) to read `NameRecord` data; the lookup key reaches that resolver and its upstream RPC endpoint. Operators MUST run both the resolver process and its upstream RPC endpoint themselves (loopback Reth + Nimbus, or a self-hosted central deployment) — sharing them across multiple operators collapses the two-server privacy property because the resolver / RPC operator would see every lookup key across all of them. The names role and the SMP-proxy role MUST NOT be enabled on the same router by default; a slow `RSLV` cache miss can serialise other forwarded commands on the same proxy-relay session.
+
 ## Message delivery notifications
 
 Supporting message delivery while the client mobile app is not running requires sending push notifications with the device token. All alternative mechanisms for background message delivery are unreliable, particularly on iOS platform.
@@ -1422,6 +1428,119 @@ When the command is successfully executed by the router, it should respond with
 ok = %s"OK"
 ```
 
+### Resolver commands
+
+Resolver commands implement public-namespace name resolution on the names-role
+router. A names router translates an opaque lookup key (such as `alice` or
+`alice.simplex.eth`) into a `NameRecord` carrying the channel and contact links
+the named party publishes.
+
+**Forwarded-only.** RSLV is only valid when delivered inside a `PFWD` block via
+the SMP proxy. A direct `RSLV` from a transport client is rejected with
+`ERR CMD PROHIBITED`. This preserves the two-server privacy property of the
+resolver design: the names router sees the lookup key but never the client IP,
+session, or identity; the proxy router sees the client connection but cannot
+read the encrypted lookup key inside the forwarded transmission.
+
+**Backing store.** This protocol does not prescribe where the names router
+reads `NameRecord` from. The reference implementation forwards each RSLV to a
+companion REST resolver process (`scripts/resolver/snrc-resolve.py`) that
+queries the SNRC contract on Ethereum; alternative backings (different chains,
+DHT, etc.) are valid as long as they expose the documented HTTP shape (`GET
+/resolve/<name>` returning a `NameRecord` on 200, 404 / 400 for unknown names
+or TLDs, 502 for upstream RPC failures) or substitute a different transport
+while still returning a `NameRecord` matching the encoding below.
+
+#### Resolve name command
+
+The `RSLV` command carries a JSON-encoded request as the payload:
+
+```abnf
+rslv = %s"RSLV" SP json-bytes   ; json-bytes consumes the remainder of the transmission
+```
+
+`json-bytes` MUST be a UTF-8 JSON object with the following schema:
+
+| Field | JSON type | Constraints |
+|---|---|---|
+| `name` | string | the canonical fully-qualified name (TLD always explicit, e.g. `"privacy.simplex"`, `"test.testing"`, `"example.com"`); UTF-8 bytes only |
+| `contract` | string | `"0x"` followed by 40 lowercase hex characters (20 raw bytes); currently ignored by the server, reserved for future eth-backed implementations that may use it to constrain which on-chain registry the client expects the server to query |
+
+**Server-side validation.** The names router parses `name` as a fully-qualified
+domain (TLD required — bare labels are rejected) and forwards it to the
+configured backing resolver. The `contract` field is parsed for forward
+compatibility but ignored by the reference implementation: the backing
+resolver is the source of truth for which on-chain registry maps to each TLD.
+
+The names router responds with either a `NAME` response carrying the resolved
+record, or one of three error responses that a client iterating across several
+configured servers can act on distinctly:
+
+| Response | Condition | Client action |
+|---|---|---|
+| `NAME` | record resolved | use it |
+| `ERR AUTH` | name not registered, or malformed name | authoritative "no such name" — stop |
+| `ERR CMD PROHIBITED` | this router has no resolver (names role not enabled) | skip this server, try the next |
+| `ERR INTERNAL` | backing resolver failure (404/400/5xx upstream, transport failure, timeout, decode error) | transient — retry or surface, do not treat as "not found" |
+
+A client SHOULD NOT broadcast a `name` to further servers after a name-capable
+router has answered (`AUTH` or `INTERNAL`), since that router has already seen
+the lookup key; `CMD PROHIBITED` discloses nothing about the name beyond the
+fact that this router cannot resolve, so iterating past it is safe. Stats
+counters MAY be exposed out-of-band for operator observability (`bad_name` is
+incremented for validation failures, distinct from `not_found` for valid
+lookups with no backing record).
+
+#### Name record response
+
+The `NAME` response carries a JSON-encoded record as the payload:
+
+```abnf
+name = %s"NAME" SP json-bytes   ; json-bytes consumes the remainder of the transmission
+```
+
+`json-bytes` MUST be a UTF-8 JSON object with the following schema:
+
+| Field | JSON type | Constraints |
+|---|---|---|
+| `name` | string | ≤ 255 bytes UTF-8 |
+| `nickname` | string | ≤ 255 bytes UTF-8; senders MUST emit the empty string `""` when unset |
+| `website` | string | ≤ 255 bytes UTF-8; same empty-string-when-unset rule |
+| `location` | string | ≤ 255 bytes UTF-8; same empty-string-when-unset rule |
+| `simplexContact` | string | ≤ 1024 bytes UTF-8; same empty-string-when-unset rule |
+| `simplexChannel` | string | ≤ 1024 bytes UTF-8; same empty-string-when-unset rule |
+| `eth` | string or null | ≤ 255 bytes UTF-8; senders MUST emit `null` when unset; receivers MUST also accept absent keys as unset |
+| `btc` | string or null | ≤ 255 bytes UTF-8; same null / absent rules |
+| `xmr` | string or null | ≤ 255 bytes UTF-8; same null / absent rules |
+| `dot` | string or null | ≤ 255 bytes UTF-8; same null / absent rules |
+| `owner` | string | `"0x"` followed by 40 lowercase hex characters (20 raw bytes) |
+| `resolver` | string | `"0x"` followed by 40 lowercase hex characters; the resolver contract address that produced the record |
+
+Text fields (`nickname`, `website`, `location`, `simplexContact`,
+`simplexChannel`) use the empty string `""` as the "unset" sentinel: a
+backing resolver with no value for the field MUST emit an empty string, not
+JSON `null` and not an absent key. Coin fields (`eth`, `btc`, `xmr`, `dot`)
+use JSON `null` as the "unset" sentinel and MAY also be absent from the
+object entirely.
+
+The server MUST filter records its backing resolver indicates are expired
+or otherwise unavailable (returning `ERR AUTH` to the client), so the wire
+format carries no expiry field. Testnet-vs-mainnet status is derived from
+the queried TLD rather than an in-record flag.
+
+Receivers MUST tolerate extra unknown fields (forward-compatibility for future
+field additions). Adding a required field is a breaking change requiring an
+SMP version bump.
+
+**Canonical encoding.** Two names routers reading the same backing state and
+producing the same `NameRecord` MUST emit byte-identical JSON: emit object
+keys in the order listed above, integers without decimal points, no
+insignificant whitespace.
+
+**Wire-size budget.** A maximal `nameRecord` (two 1024-byte SimpleX links
+plus the other capped strings) JSON-encodes to roughly 4 KB, well under the
+SMP proxied transmission budget of 16224 bytes.
+
 ## Transport connection with the SMP router
 
 ### General transport protocol considerations

simplexmq.cabal

@@ -130,6 +130,8 @@ library
       Simplex.Messaging.Crypto.ShortLink
       Simplex.Messaging.Encoding
       Simplex.Messaging.Encoding.String
+      Simplex.Messaging.Names.Owner
+      Simplex.Messaging.Names.Record
       Simplex.Messaging.Notifications.Client
       Simplex.Messaging.Notifications.Protocol
       Simplex.Messaging.Notifications.Transport
@@ -141,6 +143,7 @@ library
       Simplex.Messaging.Server.QueueStore.Postgres.Config
       Simplex.Messaging.Server.QueueStore.QueueInfo
       Simplex.Messaging.ServiceScheme
+      Simplex.Messaging.SimplexName
       Simplex.Messaging.Session
       Simplex.Messaging.SystemTime
       Simplex.Messaging.TMap
@@ -261,6 +264,8 @@ library
           Simplex.Messaging.Server.MsgStore.Journal.SharedLock
           Simplex.Messaging.Server.MsgStore.STM
           Simplex.Messaging.Server.MsgStore.Types
+          Simplex.Messaging.Server.Names
+          Simplex.Messaging.Server.Names.HttpResolver
           Simplex.Messaging.Server.NtfStore
           Simplex.Messaging.Server.Prometheus
           Simplex.Messaging.Server.QueueStore
@@ -355,7 +360,10 @@ library
     build-depends:
         case-insensitive ==1.2.*
       , hashable ==1.4.*
+      , http-client >=0.7 && <0.8
+      , http-client-tls >=0.3 && <0.4
       , ini ==0.4.1
+      , network-uri >=2.6 && <2.7
       , optparse-applicative >=0.15 && <0.17
       , process ==1.6.*
       , temporary ==1.3.*
@@ -489,10 +497,12 @@ test-suite simplexmq-test
       AgentTests.EqInstances
       AgentTests.FunctionalAPITests
       AgentTests.MigrationTests
+      AgentTests.ResolveNameTests
       AgentTests.ServerChoice
       AgentTests.ShortLinkTests
       CLITests
       CoreTests.BatchingTests
+      CoreTests.ConnectTargetTests
       CoreTests.CryptoFileTests
       CoreTests.CryptoTests
       CoreTests.EncodingTests
@@ -505,9 +515,11 @@ test-suite simplexmq-test
       CoreTests.VersionRangeTests
       FileDescriptionTests
       RemoteControl
+      RSLVTests
       ServerTests
       SMPAgentClient
       SMPClient
+      SMPNamesTests
       SMPProxyTests
       Util
       XFTPAgent

src/Simplex/Messaging/Agent.hs

@@ -65,6 +65,7 @@ module Simplex.Messaging.Agent
     setConnShortLink,
     deleteConnShortLink,
     getConnShortLink,
+    resolveSimplexName,
     getConnLinkPrivKey,
     deleteLocalInvShortLink,
     changeConnectionUser,
@@ -216,6 +217,7 @@ import Simplex.Messaging.Protocol
     ErrorType (AUTH),
     MsgBody,
     MsgFlags (..),
+    NameRecord,
     NtfServer,
     ProtoServerWithAuth (..),
     ProtocolServer (..),
@@ -440,6 +442,13 @@ getConnShortLink :: AgentClient -> NetworkRequestMode -> UserId -> ConnShortLink
 getConnShortLink c = withAgentEnv c .:. getConnShortLink' c
 {-# INLINE getConnShortLink #-}
 
+-- | Resolve a SimpleX name via the configured resolver SMP server (PFWD RSLV).
+-- The TLD->contract whitelist lives in the agent so chat clients only need to
+-- pass the resolver address and the parsed domain.
+resolveSimplexName :: AgentClient -> NetworkRequestMode -> UserId -> SMPServer -> SimplexNameDomain -> AE NameRecord
+resolveSimplexName c = withAgentEnv c .:: resolveSimplexName' c
+{-# INLINE resolveSimplexName #-}
+
 getConnLinkPrivKey :: AgentClient -> ConnId -> AE (Maybe C.PrivateKeyEd25519)
 getConnLinkPrivKey c = withAgentEnv c . getConnLinkPrivKey' c
 {-# INLINE getConnLinkPrivKey #-}
@@ -1182,6 +1191,16 @@ getConnShortLink' c nm userId = \case
 deleteLocalInvShortLink' :: AgentClient -> ConnShortLink 'CMInvitation -> AM ()
 deleteLocalInvShortLink' c (CSLInvitation _ srv linkId _) = withStore' c $ \db -> deleteInvShortLink db srv linkId
 
+resolveSimplexName' :: AgentClient -> NetworkRequestMode -> UserId -> SMPServer -> SimplexNameDomain -> AM NameRecord
+resolveSimplexName' c nm userId resolverSrv domain =
+  resolveName c nm userId resolverSrv placeholderContract (fullDomainName domain)
+  where
+    -- The wire format still carries a 20-byte `contract` field on RslvRequest
+    -- (no SMP version bump), but the server-side resolver ignores it: the
+    -- backing Python REST resolver is the source of truth for which on-chain
+    -- registry maps to each TLD. The agent sends the all-zero placeholder.
+    placeholderContract = either error id (SMP.mkNameOwner (B.replicate 20 '\NUL'))
+
 changeConnectionUser' :: AgentClient -> UserId -> ConnId -> UserId -> AM ()
 changeConnectionUser' c oldUserId connId newUserId = do
   SomeConn _ conn <- withStore c (`getConn` connId)

src/Simplex/Messaging/Agent/Client.hs

@@ -68,6 +68,7 @@ module Simplex.Messaging.Agent.Client
     deleteQueueLink,
     secureGetQueueLink,
     getQueueLink,
+    resolveName,
     enableQueueNotifications,
     EnableQueueNtfReq (..),
     enableQueuesNtfs,
@@ -267,6 +268,8 @@ import Simplex.Messaging.Protocol
     NetworkError (..),
     MsgFlags (..),
     MsgId,
+    NameOwner,
+    NameRecord,
     NtfServer,
     NtfServerWithAuth,
     ProtoServer,
@@ -1990,6 +1993,17 @@ getQueueLink c nm userId server lnkId =
     getViaProxy smp proxySess = proxyGetSMPQueueLink smp nm proxySess lnkId
     getDirectly smp = getSMPQueueLink smp nm lnkId
 
+-- | Resolve a public-namespace name. Prefers PFWD (hides client IP from the
+-- resolver) and falls back to a direct send when the proxy is unavailable
+-- (faster but exposes the client IP). Mode selection is delegated to
+-- `sendOrProxySMPCommand`, which honours the network config (SPMNever etc.).
+resolveName :: AgentClient -> NetworkRequestMode -> UserId -> SMPServer -> NameOwner -> Text -> AM NameRecord
+resolveName c nm userId server contract name =
+  snd <$> sendOrProxySMPCommand c nm userId server "" "RSLV" NoEntity resolveViaProxy resolveDirectly
+  where
+    resolveViaProxy smp proxySess = proxyResolveName smp nm proxySess contract name
+    resolveDirectly smp = directResolveName smp nm contract name
+
 enableQueueNotifications :: AgentClient -> RcvQueue -> SMP.NtfPublicAuthKey -> SMP.RcvNtfPublicDhKey -> AM (SMP.NotifierId, SMP.RcvNtfPublicDhKey)
 enableQueueNotifications c rq@RcvQueue {rcvId, rcvPrivateKey} notifierKey rcvNtfPublicDhKey =
   withSMPClient c NRMBackground rq "NKEY <nkey>" $ \smp ->