diff --git a/docs/protocol/agent-protocols.md b/docs/protocol/agent-protocols.md new file mode 100644 index 0000000000..d4e828d677 --- /dev/null +++ b/docs/protocol/agent-protocols.md @@ -0,0 +1,472 @@ +Revision 1, 2026-10-19, draft for comments + +Evgeny Poberezkin + +# Agent protocols over SimpleX + +## Table of contents + +- [Abstract](#abstract) +- [Conventions](#conventions) +- [Overview](#overview) +- [Addresses in llms.txt](#addresses-in-llmstxt) +- [Profile declarations](#profile-declarations) + - [protocols](#protocols) + - [Public group audience and update frequency](#public-group-audience-and-update-frequency) + - [Contact address peers](#contact-address-peers) + - [Protocol names](#protocol-names) +- [Chat transport](#chat-transport) + - [Commands](#commands) + - [Replies](#replies) + - [Message size](#message-size) +- [Service RPC transport](#service-rpc-transport) + - [Exchange](#exchange) + - [Request](#request) + - [Response](#response) + - [Signed requests](#signed-requests) +- [MCP binding](#mcp-binding) + - [Messages](#messages) + - [Versions and capabilities](#versions-and-capabilities) + - [Examples](#examples) +- [Security considerations](#security-considerations) +- [Privacy considerations](#privacy-considerations) +- [Implementations](#implementations) +- [References](#references) + +## Abstract + +This document defines how software agents find SimpleX addresses and call the tools of other agents and bots over SimpleX: + +- an `llms.txt` section with communication addresses, beside the link relation type and the well-known document of [Publishing SimpleX addresses on websites](./web-discovery.md); +- declarations: the protocols a profile serves and their transports, the peer types a channel or a contact address is made for, and the update frequency of a channel; +- the chat transport: the command `/_call` in a conversation; +- the Service RPC transport: one request and one response, without a conversation, in a generic envelope; +- the binding of the Model Context Protocol (MCP) [MCP] to both transports. + +## Conventions + +The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT" and "MAY" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals. + +JSON schemas use JSON Type Definition [RFC8927]. Whitespace in JSON examples is for readability. + +**Bot**: a SimpleX profile operated by software: a bot of the bot library, or an AI agent through `@simplex-chat/mcp`. + +## Overview + +A website owner publishes channels for updates and contact addresses for requests [WEB]. An agent: + +1. reads the addresses from the website: link relations, `/.well-known/simplex.json` or `llms.txt`; +2. retrieves the link data with the link, without connecting; +3. reads the declarations; +4. subscribes to a channel, connects to a contact address, or sends a Service RPC request to it. + +```mermaid +sequenceDiagram + participant A as Agent + participant W as Website + participant R as SMP router + participant B as Bot + + A->>W: GET /.well-known/simplex.json + W-->>A: channels and contacts + A->>R: retrieve link data + R-->>A: link data with declarations + alt chat transport + A->>B: connect, then /_call messages + B-->>A: replies + else Service RPC transport + A->>B: request in the connection request + B-->>A: response to the reply queue + end +``` + +Two transports carry protocol messages: + +- **chat**: a conversation in a direct chat or a group. The caller connects once and sends commands as messages. The conversation persists between calls. +- **rpc**: Service RPC. The request is sent in the connection request to a contact address, and the response to the reply queue of that request. Both sides then delete the connection. A call needs one round trip, and each call uses a new connection. + +## Addresses in llms.txt + +An `llms.txt` file [LLMSTXT] lists communication addresses in a section with the heading `## Communications`. The section is a file list: each item is a Markdown link, then a colon and notes. + +The notes begin with the network and the type of the address, then the audience and, for updates, the update frequency or, for contacts, the protocols. Free text follows: + +``` + updates for [, ]. + group for . + [business ]contact for [, ]*. +``` + +- ``: the name of the network, `SimpleX` for SimpleX links. +- `updates`: an address that publishes updates. `group`: an address of a group, where members converse. `contact`: an address that accepts conversations and requests. `business contact`: a business address [BUSINESS]. +- ``: `people`, `agents`, or `people and agents`. +- ``: a `changefreq` value of the Sitemaps protocol [SITEMAPS]. +- ``: the name of a protocol the address serves ([protocol names](#protocol-names)), in any letter case. +- ``: what the address is about. + +The network is named in the notes because the host in a SimpleX link is the router that hosts the address, and that router can have any domain name. + +For SimpleX entries, the type `updates` requires a channel link, the type `group` a group link, and the types `contact` and `business contact` a contact address link [WEB]. The link text is the title of the address. + +``` +## Communications + +- [Acme news](https://smp12.simplex.im/c#…): SimpleX updates for people and agents, weekly. Product news and offers. +- [Acme customers](https://smp12.simplex.im/g#…): SimpleX group for people. Questions and tips from customers. +- [Ask Acme](https://smp12.simplex.im/a#…): SimpleX business contact for agents, MCP. Orders and availability. +- [Acme support](mailto:support@acme.example): Email contact for people. +``` + +## Profile declarations + +A profile or a group declares the protocols it serves in its preferences. A channel or a public group declares its audience in its public group record, and a channel also its update frequency. A contact address declares the peers it serves in its link data. + +### protocols + +`protocols` is a key of the preferences: `preferences` of a user or contact profile, and `groupPreferences` of a group profile [CHAT]. Clients store the preferences of other profiles as received, so a client that does not know the key decodes it after an upgrade. + +JSON Type Definition schema [RFC8927] of the `protocols` key: + +```json +{ + "values": { + "properties": { + "versions": {"elements": {"type": "string"}}, + "transports": { + "optionalProperties": { + "chat": {"type": "boolean"}, + "rpc": {"type": "boolean"} + }, + "additionalProperties": true + } + }, + "additionalProperties": true + } +} +``` + +- Keys: protocol names. +- `versions`: required. The protocol versions the bot serves, in the bot's order of preference. +- `transports`: required. The transports on which the bot serves the protocol. +- `transports.chat`: the bot answers `/_call` for the protocol in a conversation. +- `transports.rpc`: the bot answers Service RPC requests for the protocol on its contact address. It is valid in `preferences` only. +- An absent transport is false. +- Clients MUST ignore unknown keys. + +A declaration in `preferences` applies to direct chats with the profile and to Service RPC requests to its contact address. A declaration in `groupPreferences` states that the group's owners serve the protocol in the group chat. Other members can serve a protocol in a group without a declaration, because the core removes preferences from member profiles in groups. In a business chat, `protocols` of the business profile MUST be copied into the chat's `groupPreferences`, as `commands` are. + +`commands` remains the command menu for people. `/_call` is not added to it. The underscore marks a command for software, as in the API of the core, and leaves `/call` free for bots' commands for people. + +Example, the `preferences` of a contact profile: + +```json +{ + "protocols": { + "mcp": { + "versions": ["2026-07-28"], + "transports": {"chat": true, "rpc": true} + } + } +} +``` + +### Public group audience and update frequency + +Two fields of the public group record, `publicGroup` of the group profile of a channel or a public group [CHAT]. JSON Type Definition schema [RFC8927]: + +```json +{ + "optionalProperties": { + "audience": {"elements": {"type": "string"}}, + "changeFrequency": {"enum": ["always", "hourly", "daily", "weekly", "monthly", "yearly", "never"]} + } +} +``` + +- `audience`: the peer types the channel or the group is made for. The values are the values of a profile's `peerType`: `human`, `bot`, `business`, `agent`. An absent `audience` is `["human"]`. Agents also read content made for people, so a channel or a group declares `agent` when it is made for agents, or has dedicated support for them. +- `changeFrequency`: in a channel only, how often the channel is updated. The values are the `changefreq` values of the Sitemaps protocol [SITEMAPS]: `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, `never`. + +### Contact address peers + +One field of the data published with a contact address link, beside `business`, which marks a business address [BUSINESS]. JSON Type Definition schema [RFC8927]: + +```json +{ + "optionalProperties": { + "serves": {"elements": {"type": "string"}} + } +} +``` + +- `serves`: the peer types the address is made for, with the values and the default of `audience`. + +Clients MUST ignore unknown values of `audience` and `serves`. The values in the public group record and in the address link data take precedence over the values on a website [WEB]. + +### Protocol names + +A protocol name consists of lowercase ASCII letters, digits and hyphens. + +A binding defines the protocol's request and response messages, including how, and whether, a peer discovers the protocol's capabilities. Both transports carry these messages unchanged. + +| Name | Binding | +|---|---| +| `mcp` | [MCP binding](#mcp-binding) | + +## Chat transport + +### Commands + +``` +/_call +/_call @ +``` + +- ``: the name of a protocol the recipient serves. +- ``: the protocol's request message, a JSON object. +- `@`: optional, in a group: a mention of the called member [CHAT]. +- In a group, a command with a mention is answered by the mentioned member. A command without a mention is a broadcast: each member that serves the protocol answers it. +- A command is the text of a text message. One space separates its parts. +- A bot that declares `transports.chat` for a protocol MUST answer each `/_call` for it that mentions the bot or mentions nobody. + +### Replies + +- A bot sends one reply to each command it answers. The reply quotes the command, with a truncated quote. Its text is the protocol's response message, a JSON object. +- A caller matches each reply to its command by the quoted message. Replies can arrive in any order. +- In a group, a broadcast can receive several replies, one from each member that serves the protocol. A caller collects them all, each with its sender. +- In a direct chat, a caller accepts replies only from the recipient. In a group, a caller of a command with a mention accepts only the mentioned member's reply. +- Commands and replies are ordinary messages: people see them in the conversation. + +### Message size + +A command and a reply are one message each. The core refuses a message whose encoded JSON exceeds 15,602 bytes [CHAT]. The command or the reply is a string inside that JSON, so its escape characters count towards the limit. A bot whose reply exceeds the limit replies with the binding's error instead. + +## Service RPC transport + +### Exchange + +The requester's core sends the request with: + +``` +/_service_request [timeout=] [sign_key=] +``` + +- ``: a contact address link, or the SimpleX name of a contact address [NAMES]. +- `timeout`: how long the requester waits for the response. The default is 30 seconds. +- `sign_key`: the requester's Ed25519 private key, for a [signed request](#signed-requests). +- ``: the [request](#request), a JSON object. +- The command returns `serviceResponse` with `responseData`, the [response](#response). + +The responder's core reports the request as the event `serviceRequest`, with `requestId`, `signerKey` and `requestData`. The responder sends the response with: + +``` +/_service_response +``` + +Requirements: + +- The responder's core MUST run with service requests enabled, the option `service_requests=on` of `/_start`. Otherwise the core drops each request, and the requester waits until its timeout. +- The responder's contact address MUST have ratchet keys. The core adds them to an address created or updated with the option `pq_ratchet=on` or `pq_ratchet=off` (`/_address`, `/_short_link_address`, `/_address_settings`). A request to an address without ratchet keys fails at once. +- The core accepts a response within 180 seconds of receiving the request. A requester that expects a slow response sets `timeout` accordingly. +- Before encryption, the agent pads a request or a response, its own framing included, to 11,106 bytes, and a longer one fails. A request and a response SHOULD NOT exceed 10,000 bytes of JSON. + +### Request + +JSON Type Definition schema [RFC8927] of the request: + +```json +{ + "properties": { + "protocol": {"type": "string"}, + "request": {} + }, + "optionalProperties": { + "version": {}, + "requestKey": {"type": "string"} + }, + "additionalProperties": true +} +``` + +- `protocol`: the protocol name. +- `version`: the protocol version, for a protocol whose messages do not include one. Its type is defined by the binding. +- `requestKey`: the requester's Ed25519 public key, in the encoding of the core's `signerKey`: base64url of the X.509 DER encoding of the key. A request with `requestKey` MUST be signed with that key. +- `request`: the protocol's request message, the same as after `/_call ` in a conversation. The fields of the envelope are never added to it. + +### Response + +JSON Type Definition schema [RFC8927] of the response: + +```json +{ + "optionalProperties": { + "response": {}, + "error": { + "properties": { + "code": {"type": "string"} + }, + "optionalProperties": { + "message": {"type": "string"}, + "retryAfter": {"type": "uint32"} + }, + "additionalProperties": true + } + }, + "additionalProperties": true +} +``` + +- A response has exactly one of `response` and `error`. +- `response`: the protocol's response message, the same as the reply in a conversation. +- `error`: the request was not passed to the protocol. +- `message`: a description for the requester's logs. +- `retryAfter`: the number of seconds after which a repeated request can succeed. + +Error codes: + +- `unsupported_protocol`: the responder does not serve the protocol over Service RPC. +- `unsupported_version`: the responder does not serve the requested version. +- `bad_request`: the envelope is invalid, or `requestKey` differs from the verified signer key. +- `conversation_required`: the request needs a conversation. The requester connects to the address and uses the chat transport. +- `too_large`: the response exceeds the size limit. +- `rate_limited`: the requester repeats the request after `retryAfter`. +- `internal`: the responder failed. + +A requester treats an unknown code as final, unless the error has `retryAfter`. + +### Signed requests + +- A signed request has the requester's Ed25519 signature over the request payload, bound to the request's ratchet session: the agent signs `SHA3-256("SimpleXService" ‖ AD) ‖ payload`, where AD is the ratchet's associated data. The responder's agent verifies the signature, and the core reports the key as `signerKey`. A signature copied into another session fails verification. +- A responder MUST answer `bad_request` to a request whose `requestKey` differs from `signerKey`, and to an unsigned request with `requestKey`. +- A requester signs when the responder needs a persistent identity, for example an account or a purchase. All requests signed with one key are linkable to each other. A requester SHOULD use a separate key for each responder. +- An unsigned request has only the payload: the responder cannot link it to other requests by a key. + +## MCP binding + +Protocol name: `mcp`. + +### Messages + +- The request is one JSON-RPC request of MCP revision 2026-07-28 or later, with its `_meta` envelope [MCP]. In a conversation, it follows `/_call mcp`. Over Service RPC, it is the envelope's `request`. +- The response is the JSON-RPC response to the request: a result or a JSON-RPC error. In a conversation, it is the text of the reply. Over Service RPC, it is the envelope's `response`. +- In a conversation, a caller matches a reply to its request by the quoted message. The response has the request's `id`, as JSON-RPC requires. +- A bot serves the methods answered with one response, for example `server/discover`, `tools/list` and `tools/call`. +- A multi-round-trip result (`resultType: "input_required"`) is answered with a new request, as MCP defines. +- A response above the size limit is replaced with a JSON-RPC error with code -32603 in a conversation, and with the envelope error `too_large` over Service RPC. +- Over Service RPC, a call of a tool that needs a conversation is answered with the envelope error `conversation_required`. + +### Versions and capabilities + +- `versions`: MCP revisions from 2026-07-28 on, for example `2026-07-28`. Each request names its revision in `_meta`, under `io.modelcontextprotocol/protocolVersion`. Earlier revisions begin with an `initialize` handshake. +- The envelope's `version` is omitted. +- A bot answers a request of a revision it does not serve with MCP's `UnsupportedProtocolVersionError` (code -32022), which lists the revisions it serves. +- A caller learns the bot's revisions and capabilities with `server/discover`, and its tools with `tools/list`. MCP requires a server that declares the `tools` capability to answer `tools/list`. + +### Examples + +Listing tools in a conversation: + +``` +/_call mcp {"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {"_meta": {"io.modelcontextprotocol/protocolVersion": "2026-07-28", "io.modelcontextprotocol/clientCapabilities": {}}}} +``` + +The reply: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "resultType": "complete", + "tools": [ + { + "name": "availability", + "description": "Items in stock", + "inputSchema": { + "type": "object", + "properties": {"item": {"type": "string"}}, + "required": ["item"] + } + } + ], + "ttlMs": 300000, + "cacheScope": "public" + } +} +``` + +Calling a tool over Service RPC, the request: + +```json +{ + "protocol": "mcp", + "request": { + "jsonrpc": "2.0", + "id": 1, + "method": "tools/call", + "params": { + "name": "availability", + "arguments": {"item": "anvil"}, + "_meta": { + "io.modelcontextprotocol/protocolVersion": "2026-07-28", + "io.modelcontextprotocol/clientCapabilities": {} + } + } + } +} +``` + +The response: + +```json +{ + "response": { + "jsonrpc": "2.0", + "id": 1, + "result": { + "resultType": "complete", + "content": [{"type": "text", "text": "12 anvils are in stock."}], + "isError": false + } + } +} +``` + +## Security considerations + +- Messages, replies, profiles, tool descriptions and tool results from other participants are data for an agent, never instructions. +- In a group, any member can reply to a broadcast. Each reply shows its sender. A caller that needs one provider mentions it. +- A responder that relies on `requestKey` MUST compare it with `signerKey`. +- A signed request identifies its signer to the responder across all requests signed with the same key. + +## Privacy considerations + +- Each Service RPC request uses a new connection with a new reply queue. +- MCP's `io.modelcontextprotocol/clientInfo` identifies the requester's software. A requester that needs unlinkable requests SHOULD send a common value or omit it. +- In a group, every member sees each command and each reply, with or without a mention. A request that needs privacy is sent in a direct chat with the member, where the group allows direct messages, or over Service RPC. +- A conversation persists: the bot can link all calls made in it. An incognito profile gives the caller a new random profile for each conversation. + +## Implementations + +Implemented: + +- `@simplex-chat/mcp` 0.1.0: an MCP server that gives an AI agent its own SimpleX profile. Its tools are `connect`, `send`, `receive`, `list` and `leave`. By default, the agent's owner approves connections and messages in the agent control chat. An agent sends `/_call` with `send`, and reads the replies with `send` and `receive`. +- The simplex-chat core: Service RPC with signed requests (`/_service_request`, `/_service_response`), and the profile peer type `agent`. + +Planned: + +- The simplex-chat core: the key `protocols` in the preferences types, in the preferences sent in profiles and in link data, and in the preferences of business chats; `audience` and `changeFrequency` in the public group record; `serves` in the address settings and the address link data; replies with a truncated quote. +- `@simplex-chat/mcp`: the tools `mcp_tools` and `mcp_call`. They use Service RPC when the address declares `transports.rpc`, and the agent's conversation otherwise. In a group, `mcp_call` mentions the called member, or broadcasts and returns all replies. Each call is an action, approved by the agent's owner as a message is. +- The bot library: a helper that serves MCP tools over both transports. + +## References + +- [BUSINESS] Using SimpleX Chat in business: [BUSINESS.md](../BUSINESS.md) +- [CHAT] SimpleX Chat protocol: [simplex-chat.md](./simplex-chat.md) +- [LLMSTXT] The /llms.txt file: https://llmstxt.org +- [MCP] Model Context Protocol specification, revision 2026-07-28: https://modelcontextprotocol.io/specification/2026-07-28 +- [NAMES] SimpleX public names for channels and businesses: [names-overview.md](./names-overview.md) +- [RFC2119] Key words for use in RFCs to Indicate Requirement Levels: https://www.rfc-editor.org/rfc/rfc2119 +- [RFC8174] Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words: https://www.rfc-editor.org/rfc/rfc8174 +- [RFC8927] JSON Type Definition: https://www.rfc-editor.org/rfc/rfc8927 +- [SITEMAPS] Sitemaps XML format: https://www.sitemaps.org/protocol.html +- [WEB] Publishing SimpleX addresses on websites: [web-discovery.md](./web-discovery.md) diff --git a/docs/protocol/web-discovery.md b/docs/protocol/web-discovery.md new file mode 100644 index 0000000000..cc35a73ddc --- /dev/null +++ b/docs/protocol/web-discovery.md @@ -0,0 +1,251 @@ +Revision 1, 2026-10-19, draft + +Evgeny Poberezkin + +# Publishing SimpleX addresses on websites + +## Table of contents + +- [Abstract](#abstract) +- [Conventions](#conventions) +- [Terms](#terms) +- [Link relation type](#link-relation-type) + - [simplex](#simplex) + - [Owner's and described addresses](#owners-and-described-addresses) + - [Target attributes](#target-attributes) + - [HTML](#html) + - [HTTP](#http) +- [Well-known URI](#well-known-uri) + - [Retrieval](#retrieval) + - [Format](#format) + - [Example](#example) +- [Processing](#processing) +- [Security considerations](#security-considerations) +- [Privacy considerations](#privacy-considerations) +- [IANA considerations](#iana-considerations) + - [Link relation type registration](#link-relation-type-registration) + - [Well-known URI registration](#well-known-uri-registration) +- [HTML link type extensions](#html-link-type-extensions) +- [References](#references) + +## Abstract + +This document defines how a website publishes SimpleX channels, groups and contact addresses: + +- the link relation type `simplex`, for the HTML elements `link`, `a` and `area`, and for the HTTP `Link` header field. Its targets are the addresses of the website's owner, or the addresses a page describes, such as the entries of a directory; +- the well-known URI `simplex.json`: a JSON document with the owner's channels, groups and contact addresses, their audience, the update frequency of each channel, and the kind and the protocols of each contact address. + +People and software agents subscribe to a channel to receive updates, join a group to take part in its conversations, and connect to a contact address to send requests. [Agent protocols over SimpleX](./agent-protocols.md) defines the requests an agent sends to a contact address, and an `llms.txt` section with the same addresses. + +## Conventions + +The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT" and "MAY" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals. + +JSON schemas use JSON Type Definition [RFC8927]. + +## Terms + +- **SimpleX link**: a short connection link of the SimpleX Agent protocol, with the `https` or the `simplex` scheme [AGENT]. The type in the link is the kind of the address. +- **Channel link**: a SimpleX link of type `c`, for example `https://smp12.simplex.im/c#`. +- **Group link**: a SimpleX link of type `g`, for example `https://smp12.simplex.im/g#`. +- **Contact address link**: a SimpleX link of type `a`, for example `https://smp12.simplex.im/a#`. +- **SimpleX name**: a name in the SimpleX name service [NAMES]. `#example.simplex` is the name of a channel, `@example.simplex` the name of a contact address. +- **Owner**: the person or organization that publishes the website. + +## Link relation type + +### simplex + +The target of a `simplex` link is a SimpleX channel, group or contact address of the owner of the link context, or described by the link context. The target MUST be a channel link, a group link or a contact address link. The type in the link tells which. + +### Owner's and described addresses + +A page that describes the addresses of others, such as a directory or a catalogue, uses the relation type on its entries. The owner's own addresses are listed in the [well-known document](#well-known-uri). + +### Target attributes + +- `title`: the name of the channel, the group or the address, for display. In HTTP, a title with non-ASCII characters is sent as `title*` [RFC8187]. +- `hreflang`: the language of the channel's posts, or of the conversations [BCP47]. + +A link context MAY have several `simplex` links of one kind. Their order is the owner's order of preference: document order in HTML, and the order of link values in HTTP. + +### HTML + +In the document head: + +```html + + +``` + +In the document body, the relation type is used on visible links, for example on the entries of a directory: + +```html +Chat with us +Acme customers +``` + +### HTTP + +``` +Link: ; rel="simplex"; hreflang="en"; title="Acme news" +Link: ; rel="simplex"; hreflang="en"; title="Ask Acme" +``` + +## Well-known URI + +### Retrieval + +The document is located at the path `/.well-known/simplex.json` of an origin [RFC8615]. A client retrieves it with an HTTPS `GET` request. A server responds with status 200, and SHOULD send the media type `application/json`. A client parses the response body as JSON, whatever media type the server sends. + +The entries of the document are the channels, groups and contact addresses of the origin's owner. A site that controls only a path of its origin publishes link relations instead. + +### Format + +The document MUST conform to this JSON Type Definition schema [RFC8927]: + +```json +{ + "optionalProperties": { + "channels": {"elements": {"ref": "address"}}, + "groups": {"elements": {"ref": "address"}}, + "contacts": {"elements": {"ref": "address"}} + }, + "additionalProperties": true, + "definitions": { + "address": { + "properties": { + "link": {"type": "string"} + }, + "optionalProperties": { + "name": {"type": "string"}, + "title": {"type": "string"}, + "lang": {"type": "string"}, + "audience": {"elements": {"type": "string"}}, + "changeFrequency": {"enum": ["always", "hourly", "daily", "weekly", "monthly", "yearly", "never"]}, + "business": {"type": "boolean"}, + "protocols": {"elements": {"type": "string"}} + }, + "additionalProperties": true + } + } +} +``` + +- `channels`: the owner's channels, in the owner's order of preference. +- `groups`: the owner's groups, in the owner's order of preference. +- `contacts`: the owner's contact addresses, in the owner's order of preference. +- `link`: required. A channel link in `channels`, a group link in `groups`, a contact address link in `contacts`. +- `name`: the SimpleX name of the channel, the group or the contact address of `link`. +- `title`: the name of the channel, the group or the address, for display. +- `lang`: the language of the channel's posts, or of the conversations [BCP47]. +- `audience`: who the channel, the group or the address serves: `people`, `agents`, or both. +- `changeFrequency`: in `channels` only, how often the channel is updated. The values are the `changefreq` values of the Sitemaps protocol [SITEMAPS]: `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, `never`. +- `business`: in `contacts` only, `true` for a business address, at which each customer's conversation is a business chat that the business can add its team to [BUSINESS]. +- `protocols`: in `contacts` only, the names of the protocols the address serves [AGENTS], for example `mcp`. + +A site omits the lists it does not use. + +### Example + +```json +{ + "channels": [ + { + "link": "https://smp12.simplex.im/c#…", + "name": "#acme.simplex", + "title": "Acme news", + "lang": "en", + "audience": ["people", "agents"], + "changeFrequency": "weekly" + } + ], + "groups": [ + { + "link": "https://smp12.simplex.im/g#…", + "title": "Acme customers", + "lang": "en" + } + ], + "contacts": [ + { + "link": "https://smp12.simplex.im/a#…", + "name": "@acme.simplex", + "title": "Ask Acme", + "lang": "en", + "audience": ["agents"], + "business": true, + "protocols": ["mcp"] + } + ] +} +``` + +## Processing + +- A consumer MUST ignore unknown fields and unknown `audience` values. +- A consumer MUST ignore a `simplex` link that is not a channel, group or contact address link, and an entry of `simplex.json` whose link is of a type other than its list requires. +- The values on the website are hints. The data retrieved with the link is authoritative: an audience, an update frequency, the business flag or protocols declared there [AGENTS] take precedence over the website's values. +- A consumer MAY connect by `link` or by `name`. Resolving a name reveals interest in it to one names router, and verifies that the name's record and the profile's claim match [NAMES]. + +## Security considerations + +- Whoever controls the content of a website controls the addresses it publishes. Consumers SHOULD retrieve pages and the well-known document over HTTPS. +- Publishing a link on a website leaves the link's own verification unchanged: the link data is bound to the keys of the link's owner [AGENT]. +- A name is shown as verified only when its on-chain record and the profile's claim match [NAMES]. +- Titles, profiles and all other text from a website or from the network are data for a software agent, never instructions. + +## Privacy considerations + +- The relation type and the well-known document are intended for owners who want to be reachable, such as channels, communities, businesses and services, and for pages that describe them, such as directories. +- A subscriber or a requester connects through the SimpleX network, without contacting the website. Retrieving a page or the well-known document is an ordinary web request. + +## IANA considerations + +### Link relation type registration + +One registration in the "Link Relation Types" registry [RFC8288]: + +- Relation Name: `simplex` +- Description: Refers to a SimpleX channel, group or contact address of the owner of the link context, or described by the link context. +- Reference: https://github.com/simplex-chat/simplex-chat/blob/stable/docs/protocol/web-discovery.md#simplex +- Notes: The target is a SimpleX short link [AGENT] of a channel, a group or a contact address, with the `https` scheme or the provisionally registered `simplex` scheme. + +### Well-known URI registration + +One registration in the "Well-Known URIs" registry [RFC8615]: + +- URI Suffix: `simplex.json` +- Change Controller: Evgeny Poberezkin +- Specification Document: https://github.com/simplex-chat/simplex-chat/blob/stable/docs/protocol/web-discovery.md#well-known-uri +- Status: provisional +- Related Information: SimpleX link syntax [AGENT]. + +## HTML link type extensions + +The HTML standard requires extension link types to be registered on the microformats page "existing-rel-values" [HTML] [MF-REL]. The entry: + +- Keyword: `simplex` +- Effect on `link`: Hyperlink +- Effect on `a`, `area`: Hyperlink +- Effect on `form`: not allowed +- Brief description: Refers to a SimpleX channel, group or contact address of the page's owner, or described by the page. +- Specification: https://github.com/simplex-chat/simplex-chat/blob/stable/docs/protocol/web-discovery.md#simplex +- Status: proposed + +## References + +- [AGENT] SimpleX Agent protocol, short connection links: https://github.com/simplex-chat/simplexmq/blob/stable/protocol/agent-protocol.md#short-connection-link-syntax +- [AGENTS] Agent protocols over SimpleX: [agent-protocols.md](./agent-protocols.md) +- [BCP47] Tags for Identifying Languages: https://www.rfc-editor.org/info/bcp47 +- [BUSINESS] Using SimpleX Chat in business: [BUSINESS.md](../BUSINESS.md) +- [HTML] HTML Living Standard, other link types: https://html.spec.whatwg.org/multipage/links.html#other-link-types +- [MF-REL] Microformats, existing rel values: https://microformats.org/wiki/existing-rel-values +- [NAMES] SimpleX public names for channels and businesses: [names-overview.md](./names-overview.md) +- [RFC2119] Key words for use in RFCs to Indicate Requirement Levels: https://www.rfc-editor.org/rfc/rfc2119 +- [RFC8174] Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words: https://www.rfc-editor.org/rfc/rfc8174 +- [RFC8187] Indicating Character Encoding and Language for HTTP Header Field Parameters: https://www.rfc-editor.org/rfc/rfc8187 +- [RFC8288] Web Linking: https://www.rfc-editor.org/rfc/rfc8288 +- [RFC8615] Well-Known Uniform Resource Identifiers (URIs): https://www.rfc-editor.org/rfc/rfc8615 +- [RFC8927] JSON Type Definition: https://www.rfc-editor.org/rfc/rfc8927 +- [SITEMAPS] Sitemaps XML format: https://www.sitemaps.org/protocol.html diff --git a/packages/simplex-chat-nodejs/package.json b/packages/simplex-chat-nodejs/package.json index eaf9de68fb..4771a480ea 100644 --- a/packages/simplex-chat-nodejs/package.json +++ b/packages/simplex-chat-nodejs/package.json @@ -1,6 +1,6 @@ { "name": "simplex-chat", - "version": "7.1.0-beta.6.4", + "version": "7.1.0-beta.6.5", "main": "dist/index.js", "types": "dist/index.d.ts", "gypfile": false, @@ -24,7 +24,7 @@ "docs": "typedoc" }, "dependencies": { - "@simplex-chat/types": "^7.1.0-beta.6.1", + "@simplex-chat/types": "^7.1.0-beta.6.2", "extract-zip": "^2.0.1", "fast-deep-equal": "^3.1.3" }, diff --git a/packages/simplex-chat-nodejs/src/release.ts b/packages/simplex-chat-nodejs/src/release.ts index ad9dfa4c78..cc96e5b9f6 100644 --- a/packages/simplex-chat-nodejs/src/release.ts +++ b/packages/simplex-chat-nodejs/src/release.ts @@ -1,16 +1,16 @@ // Written by scripts/ci/packages_release.py from the simplex-chat-libs releases. -export const LIBS_RELEASE = "core-7.1.0.12" +export const LIBS_RELEASE = "core-7.1.0.14" export const ADDON_RELEASE: string | undefined = "nodejs-addon-308c0960c707" export const SHA256: {readonly [asset: string]: string} = { - "simplex-chat-libs-linux-aarch64.zip": "924b8e14eaba5e309fa584c4bfe598421cf64983d63790c1c45247f592f60055", - "simplex-chat-libs-linux-x86_64-postgres.zip": "323f908b45dde751d6082f8885d07d81fba8a5ab8b2df7d3b8ab3a87e56299e5", - "simplex-chat-libs-linux-x86_64.zip": "995409e963db408bcf896361b669944484f845b6744fefe479aebb0ca2e7c5cd", - "simplex-chat-libs-macos-aarch64.zip": "64464aa48b996e5a96b4aa651bc57bc69e412d3c3804b589c67bd9dc52faddbf", - "simplex-chat-libs-macos-x86_64.zip": "94664f96ff7a2cd5a419096e7e843928faa31cb3addb8869fa1e4b5a0d0b3629", - "simplex-chat-libs-windows-x86_64.zip": "2e10844e5c119921139c373ee2971341aceef7dc4198429d3be6b1570a009d15", + "simplex-chat-libs-linux-aarch64.zip": "375a6021f0c2e5d79b2cd192e17c6c22c8eae73f46e3758fba24ee5c26a671aa", + "simplex-chat-libs-linux-x86_64-postgres.zip": "c3e8a54d37801e685c6361c4e7e53e1f5163d3aa9195dcfe686b6cf90e668ef3", + "simplex-chat-libs-linux-x86_64.zip": "cc41ab9049d61be3b386d799fa9394f2870e8ae3b2b9b8745dd3f53ba99f211e", + "simplex-chat-libs-macos-aarch64.zip": "ac3a46004f25976f71b3ead8a20b9a01c170fe12f125a0a6799ae97ea990f234", + "simplex-chat-libs-macos-x86_64.zip": "0d85ffcccc3a6dfe3e0da18d0b7be9ef36ad27381f047ef66cfde67ee4a7e882", + "simplex-chat-libs-windows-x86_64.zip": "f1d1c7efc333a5ec5328a5843c9d3c9ef038fb2886c0b60ac12e87a5c1e85bbd", "simplex-chat-nodejs-linux-aarch64.node": "3636a82c56c48229e0326fa03d6ceb5c16dd3afbcc1e86337783dc53a7328d67", "simplex-chat-nodejs-linux-x86_64.node": "55f3479b03fdb57591179ed730da744f1aa362e7529df55221b60028415746e9", "simplex-chat-nodejs-macos-aarch64.node": "a3472872fb0816f435f52ee5471088e6545ebffb95e89fbf8e1ab82275f2d56e", diff --git a/packages/simplex-chat-python/src/simplex_chat/_version.py b/packages/simplex-chat-python/src/simplex_chat/_version.py index e5075096d4..0c2e45a340 100644 --- a/packages/simplex-chat-python/src/simplex_chat/_version.py +++ b/packages/simplex-chat-python/src/simplex_chat/_version.py @@ -4,13 +4,13 @@ Written by scripts/ci/packages_release.py prepare: it bumps the version and pins new library releases with the SHA-256 of their assets. """ -__version__ = "7.1.0b6.post1" # PEP 440 — read by hatchling for wheel metadata -LIBS_RELEASE = "core-7.1.0.12" # simplex-chat-libs release tag +__version__ = "7.1.0b6.post2" # PEP 440 — read by hatchling for wheel metadata +LIBS_RELEASE = "core-7.1.0.14" # simplex-chat-libs release tag LIBS_SHA256 = { - "simplex-chat-libs-linux-aarch64.zip": "924b8e14eaba5e309fa584c4bfe598421cf64983d63790c1c45247f592f60055", - "simplex-chat-libs-linux-x86_64-postgres.zip": "323f908b45dde751d6082f8885d07d81fba8a5ab8b2df7d3b8ab3a87e56299e5", - "simplex-chat-libs-linux-x86_64.zip": "995409e963db408bcf896361b669944484f845b6744fefe479aebb0ca2e7c5cd", - "simplex-chat-libs-macos-aarch64.zip": "64464aa48b996e5a96b4aa651bc57bc69e412d3c3804b589c67bd9dc52faddbf", - "simplex-chat-libs-macos-x86_64.zip": "94664f96ff7a2cd5a419096e7e843928faa31cb3addb8869fa1e4b5a0d0b3629", - "simplex-chat-libs-windows-x86_64.zip": "2e10844e5c119921139c373ee2971341aceef7dc4198429d3be6b1570a009d15", + "simplex-chat-libs-linux-aarch64.zip": "375a6021f0c2e5d79b2cd192e17c6c22c8eae73f46e3758fba24ee5c26a671aa", + "simplex-chat-libs-linux-x86_64-postgres.zip": "c3e8a54d37801e685c6361c4e7e53e1f5163d3aa9195dcfe686b6cf90e668ef3", + "simplex-chat-libs-linux-x86_64.zip": "cc41ab9049d61be3b386d799fa9394f2870e8ae3b2b9b8745dd3f53ba99f211e", + "simplex-chat-libs-macos-aarch64.zip": "ac3a46004f25976f71b3ead8a20b9a01c170fe12f125a0a6799ae97ea990f234", + "simplex-chat-libs-macos-x86_64.zip": "0d85ffcccc3a6dfe3e0da18d0b7be9ef36ad27381f047ef66cfde67ee4a7e882", + "simplex-chat-libs-windows-x86_64.zip": "f1d1c7efc333a5ec5328a5843c9d3c9ef038fb2886c0b60ac12e87a5c1e85bbd", } diff --git a/scripts/flatpak/chat.simplex.simplex.metainfo.xml b/scripts/flatpak/chat.simplex.simplex.metainfo.xml index 71192f34e2..51bd7b33ae 100644 --- a/scripts/flatpak/chat.simplex.simplex.metainfo.xml +++ b/scripts/flatpak/chat.simplex.simplex.metainfo.xml @@ -38,6 +38,23 @@ + + https://simplex.chat/blog/20260722-simplex-public-names.html + +

New in v7.0-v7.0.4.

+

SimpleX public names for channels and businesses (BETA).

+

Better channels:

+
    +
  • Promote subscribers to contributors.
    • +
  • Publish your channel on your website.
    • +
  • Verify security code with contributors.
    • +
  • Wider messages, easier to read.
    • +
  • Host your own chat relays.
    • +
+

Add a longer description to your profile.

+

Simplified app settings.

+ + https://simplex.chat/blog/20260722-simplex-public-names.html diff --git a/website/src/.well-known/simplex.json b/website/src/.well-known/simplex.json new file mode 100644 index 0000000000..b7a1ba102b --- /dev/null +++ b/website/src/.well-known/simplex.json @@ -0,0 +1,33 @@ +{ + "channels": [ + { + "link": "https://smp18.simplex.im/c#grcfG3ulVI4Sh6ow33qBsmSk7uEy3gRSl2KkJ5ER6tA", + "title": "SimpleX Network News", + "changeFrequency": "weekly" + }, + { + "link": "https://smp10.simplex.im/c#q09nMBmWFGz1m2TvgfZFaEOG5D2a7Ma9mSkl6pHXEsg", + "title": "SimpleX Crowdfunding News", + "changeFrequency": "weekly" + } + ], + "groups": [ + { + "link": "https://smp4.simplex.im/g#hr4lvFeBmndWMKTwqiodPz3VBo_6UmdGWocXd1SupsM", + "title": "SimpleX users group" + } + ], + "contacts": [ + { + "link": "https://smp6.simplex.im/a#lrdvu2d8A1GumSmoKb2krQmtKhWXq-tyGpHuM7aMwsw", + "title": "Ask SimpleX Team", + "audience": ["people", "agents"], + "business": true + }, + { + "link": "https://smp4.simplex.im/a#lXUjJW5vHYQzoLYgmi8GbxkGP41_kjefFvBrdwg-0Ok", + "title": "SimpleX Directory", + "audience": ["people", "agents"] + } + ] +} diff --git a/website/src/_includes/markdown-alternate.html b/website/src/_includes/markdown-alternate.html index ad8301359c..f8367dd2ac 100644 --- a/website/src/_includes/markdown-alternate.html +++ b/website/src/_includes/markdown-alternate.html @@ -1,3 +1,8 @@ {% set markdownAlternateUrl = page | markdownAlternate %} {% if markdownAlternateUrl %}{% endif %} + + + +{% if active_directory %} +{% endif %} diff --git a/website/src/crowdfunding-news.html b/website/src/crowdfunding-news.html index 40294ee881..dffcc9c5b3 100644 --- a/website/src/crowdfunding-news.html +++ b/website/src/crowdfunding-news.html @@ -11,4 +11,4 @@ channel: - relay3.simplex.chat --- -

The news about SimpleX Chat equity crowdfunding on Wefunder, published as a SimpleX channel. Join it in the SimpleX Chat app: SimpleX Crowdfunding News. The crowdfunding memo: simplex.chat/wefunder.md.

+

The news about SimpleX Chat equity crowdfunding on Wefunder, published as a SimpleX channel. Join it in the SimpleX Chat app: SimpleX Crowdfunding News. The crowdfunding memo: simplex.chat/wefunder.md.

diff --git a/website/src/directory.html b/website/src/directory.html index 41dea04862..8ab3166dcd 100644 --- a/website/src/directory.html +++ b/website/src/directory.html @@ -318,7 +318,7 @@ active_directory: true

SimpleX Directory

Welcome to the selected users' communities that you can join via SimpleX Chat app.

-

SimpleX Directory is also available as a SimpleX chat bot.

+

SimpleX Directory is also available as a SimpleX chat bot.

Read about how to add your community.

diff --git a/website/src/index.html b/website/src/index.html index 31e6e086f8..2925915a64 100644 --- a/website/src/index.html +++ b/website/src/index.html @@ -273,7 +273,7 @@ active_home: true - + diff --git a/website/src/js/directory.jsc b/website/src/js/directory.jsc index dd07735260..f12f1108d9 100644 --- a/website/src/js/directory.jsc +++ b/website/src/js/directory.jsc @@ -339,7 +339,7 @@ function displayEntries(entries) { imgLinkElement.href = groupLinkUri; } imgLinkElement.target = "_blank"; - imgLinkElement.rel = "noopener"; + imgLinkElement.rel = groupLink.connShortLink ? "noopener simplex" : "noopener"; imgLinkElement.title = `Join ${displayName}`; const imgElement = document.createElement('img'); diff --git a/website/src/llms/llms-txt.njk b/website/src/llms/llms-txt.njk index 9004a88675..acb87df202 100644 --- a/website/src/llms/llms-txt.njk +++ b/website/src/llms/llms-txt.njk @@ -57,6 +57,14 @@ Every page of simplex.chat is also available as Markdown: replace `.html` with ` - [SimpleX for business](https://simplex.chat/docs/business.md) - [Host your own messaging server](https://simplex.chat/docs/server.md) and [file server](https://simplex.chat/docs/xftp-server.md) +## Communications + +- [SimpleX Network News](https://smp18.simplex.im/c#grcfG3ulVI4Sh6ow33qBsmSk7uEy3gRSl2KkJ5ER6tA): SimpleX updates for people, weekly. Network technology, governance and development. +- [SimpleX Crowdfunding News](https://smp10.simplex.im/c#q09nMBmWFGz1m2TvgfZFaEOG5D2a7Ma9mSkl6pHXEsg): SimpleX updates for people, weekly. The equity crowdfunding on Wefunder. +- [SimpleX users group](https://smp4.simplex.im/g#hr4lvFeBmndWMKTwqiodPz3VBo_6UmdGWocXd1SupsM): SimpleX group for people. Users of SimpleX Chat. +- [Ask SimpleX Team](https://smp6.simplex.im/a#lrdvu2d8A1GumSmoKb2krQmtKhWXq-tyGpHuM7aMwsw): SimpleX business contact for people and agents. Questions to the SimpleX Chat team. +- [SimpleX Directory](https://smp4.simplex.im/a#lXUjJW5vHYQzoLYgmi8GbxkGP41_kjefFvBrdwg-0Ok): SimpleX contact for people and agents. Search for public groups and channels. + ## For AI agents and developers - [SimpleX for AI agents and developers](https://simplex.chat/llms/agents.md): a bot in five minutes, the API, building from source, OpenClaw, asking the team diff --git a/website/src/news.html b/website/src/news.html index 1c0558ff81..3c5bd5fdfb 100644 --- a/website/src/news.html +++ b/website/src/news.html @@ -12,4 +12,4 @@ channel: - relay3.simplex.chat --- -

The news about SimpleX Network technology, governance and anything related to its development, published as a SimpleX channel. Join it in the SimpleX Chat app: SimpleX Network News.

+

The news about SimpleX Network technology, governance and anything related to its development, published as a SimpleX channel. Join it in the SimpleX Chat app: SimpleX Network News.