{"id":28396164,"url":"https://github.com/ssbc/ssb-uri-spec","last_synced_at":"2026-01-27T12:37:17.427Z","repository":{"id":37000231,"uuid":"346348221","full_name":"ssbc/ssb-uri-spec","owner":"ssbc","description":"Specification of SSB URIs","archived":false,"fork":false,"pushed_at":"2022-10-27T11:19:42.000Z","size":48,"stargazers_count":16,"open_issues_count":1,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-10-14T18:22:30.749Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ssbc.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSES/CC-BY-4.0.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-03-10T12:26:49.000Z","updated_at":"2023-06-27T14:35:55.000Z","dependencies_parsed_at":"2023-01-17T12:16:44.619Z","dependency_job_id":null,"html_url":"https://github.com/ssbc/ssb-uri-spec","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ssbc/ssb-uri-spec","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ssbc%2Fssb-uri-spec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ssbc%2Fssb-uri-spec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ssbc%2Fssb-uri-spec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ssbc%2Fssb-uri-spec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ssbc","download_url":"https://codeload.github.com/ssbc/ssb-uri-spec/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ssbc%2Fssb-uri-spec/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28813215,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-27T12:25:15.069Z","status":"ssl_error","status_checked_at":"2026-01-27T12:25:05.297Z","response_time":168,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-31T21:37:06.289Z","updated_at":"2026-01-27T12:37:17.421Z","avatar_url":"https://github.com/ssbc.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--\nSPDX-FileCopyrightText: 2021-2022 Andre 'Staltz' Medeiros\n\nSPDX-License-Identifier: CC-BY-4.0\n--\u003e\n\n# SSB URI Specification\n\nVersion: 1.3\n\nAuthor: Andre 'Staltz' Medeiros \u003ccontact@staltz.com\u003e\n\nLicense: This work is licensed under a Creative Commons Attribution 4.0 International License.\n\n## Abstract\n\nThe `ssb` scheme is registered as [provisional under the IANA](https://www.iana.org/assignments/uri-schemes/prov/ssb), but its format is not yet specified accessibly and clearly. This documents aims at providing the first specification of SSB URIs, as they are used in existing applications and will be adopted increasingly in more use cases.\n\n## Terminology\n\nThe key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"MAY\", and \"OPTIONAL\" in this document are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119).\n\n## Prior work\n\nThere is a thread on SSB, `%g3hPVPDEO1Aj/uPl0+J2NlhFB2bbFLIHlty+YuqFZ3w=.sha256`, where several participants gave their thoughts on the design of the SSB URI format, with several proposals put into consideration. The format of Query-only URIs were inspired by [Magnet URIs](https://www.iana.org/assignments/uri-schemes/prov/magnet).\n\n[ssb-uri](https://github.com/fraction/ssb-uri) is one outcome of that discussion, and is referred to in the IANA page. The `ssb-uri` library is depended on in [Patchwork](https://github.com/ssbc/patchwork/). As an alternative library, [ssb-custom-uri](https://git.sr.ht/~soapdog/ssb-custom-uri) is used in [Patchfox](https://github.com/soapdog/patchfox/). [Patchfoo](https://git.scuttlebot.io/%25YAg1hicat%2B2GELjE2QJzDwlAWcx0ML%2B1sXEdsWwvdt8%3D.sha256) supports both `ssb-uri` and `ssb-custom-uri`. [Manyverse](https://manyver.se) supports the URIs in this specification via the library [ssb-uri2](https://github.com/staltz/ssb-uri2).\n\nThe specification in this document is compatible with `ssb-uri` while adding support for expressing more resources.\n\n## List\n\n- **Canonical SSB URIs**\n  - `ssb:message/classic/\u003cMSGID\u003e`\n  - `ssb:message/bendybutt-v1/\u003cMSGID\u003e`\n  - `ssb:message/gabbygrove-v1/\u003cMSGID\u003e`\n  - `ssb:message/buttwoo-v1/\u003cMSGID\u003e`\n  - `ssb:message/indexed-v1/\u003cMSGID\u003e`\n  - `ssb:message/cloaked/\u003cKEY\u003e`\n  - `ssb:feed/classic/\u003cFEEDID\u003e`\n  - `ssb:feed/bendybutt-v1/\u003cFEEDID\u003e`\n  - `ssb:feed/gabbygrove-v1/\u003cFEEDID\u003e`\n  - `ssb:feed/buttwoo-v1/\u003cFEEDID\u003e`\n  - `ssb:feed/buttwoo-v1/\u003cFEEDID\u003e/\u003cPARENTMSGID\u003e`\n  - `ssb:feed/indexed-v1/\u003cFEEDID\u003e`\n  - `ssb:blob/classic/\u003cBLOBID\u003e`\n  - `ssb:address/multiserver?multiserverAddress=\u003cMSADDR\u003e`\n  - `ssb:encryption-key/box2-dm-dh/\u003cKEY\u003e`\n  - `ssb:identity/po-box/\u003cKEY\u003e`\n  - `ssb:identity/group/\u003cKEY\u003e`\n  - `ssb:identity/fusion/\u003cKEY\u003e`\n- **Experimental SSB URIs**\n  - `ssb:experimental?action=claim-http-invite\u0026invite=\u003cCODE\u003e\u0026multiserverAddress=\u003cMSADDR\u003e`\n  - `ssb:experimental?action=consume-alias\u0026alias=\u003cA\u003e\u0026userId=\u003cUID\u003e\u0026signature=\u003cSIG\u003e\u0026roomId=\u003cRID\u003e\u0026multiserverAddress=\u003cMSADDR\u003e`\n  - `ssb:experimental?action=start-http-auth\u0026sid=\u003cSID\u003e\u0026sc=\u003cSC\u003e`\n- **Deprecated SSB URIs**\n  - `ssb:message/sha256/\u003cMSGID\u003e`\n  - `ssb:feed/ed25519/\u003cFEEDID\u003e`\n  - `ssb:blob/sha256/\u003cBLOBID\u003e`\n\n## Overview\n\nThere are two main categories of SSB URIs: **Canonical** and **Experimental**. The conceptual difference between these two is that canonical SSB URIs make use of the **path component** in the URI to specify the resource, while experimental SSB URIs use _only_ the **query component** to specify the resource.\n\nThe third category, **Deprecated**, is used to denote canonical SSB URIs that MUST still be supported by application, but SHOULD be avoided whenever possible.\n\n### Canonical SSB URIs\n\nThese SSB URIs are to be considered stable and universally acceptable by all SSB applications that support SSB URIs. They utilize the path component to specify \"refs\", i.e. identifiers for resources. SSB messages, feeds, and blobs **SHOULD** follow the respective syntaxes:\n\n```\nssb:message/classic/\u003cMSGID\u003e\nssb:message/bendybutt-v1/\u003cMSGID\u003e\nssb:message/gabbygrove-v1/\u003cMSGID\u003e\nssb:message/buttwoo-v1/\u003cMSGID\u003e\nssb:message/indexed-v1/\u003cMSGID\u003e\nssb:feed/classic/\u003cFEEDID\u003e\nssb:feed/bendybutt-v1/\u003cFEEDID\u003e\nssb:feed/gabbygrove-v1/\u003cFEEDID\u003e\nssb:feed/buttwoo-v1/\u003cFEEDID\u003e\nssb:feed/buttwoo-v1/\u003cFEEDID\u003e/\u003cPARENTMSGID\u003e\nssb:feed/indexed-v1/\u003cFEEDID\u003e\nssb:blob/classic/\u003cBLOBID\u003e\n```\n\nWhere `\u003cMSGID\u003e`, `\u003cFEEDID\u003e`, `\u003cBLOBID\u003e` are _URI-safe Base64 encoded_ strings that identify those refs. URI-safe Base64 is equivalent to Base64 where `+` characters are replaced with `-`, and `/` characters are replaced with `_`.\n\nIn the special case of `ssb:feed/buttwoo-v1/\u003cFEEDID\u003e/\u003cPARENTMSGID\u003e`, the `\u003cPARENTMSGID\u003e` is the URI-safe Base64 encoded data of a buttwoo-v1 message URI (i.e. `\u003cMSGID\u003e` from `ssb:message/buttwoo-v1/\u003cMSGID\u003e`).\n\n**Examples:**\n\n```\nssb:message/classic/g3hPVPDEO1Aj_uPl0-J2NlhFB2bbFLIHlty-YuqFZ3w=\nssb:message/bendybutt-v1/PR2-btDEO1AjXuPl0TJ2N_hFB2bbFLIHlty0VF1ncty=\nssb:feed/classic/-oaWWDs8g73EZFUMfW37R_ULtFEjwKN_DczvdYihjbU=\nssb:feed/bendybutt-v1/APaWWDs8g73EZFUMfW37RBULtFEjwKNbDczvdYiRXtA=\nssb:feed/gabbygrove-v1/FY5OG311W4j_KPh8H9B2MZt4WSziy_p-ABkKERJdujQ=\nssb:blob/classic/sbBmsB7XWvmIzkBzreYcuzPpLtpeCMDIs6n_OJGSC1U=\n```\n\nThere are also new concepts related to [Private Groups](https://github.com/ssbc/private-group-spec) which need identifiers, such as:\n\n- `ssb:encryption-key/box2-dm-dh/\u003cKEY\u003e`\n- `ssb:identity/po-box/\u003cKEY\u003e`\n\nWhere `\u003cKEY\u003e` are _URI-safe Base64 encoded_ strings, similar to the previous canonical SSB URIs.\n\n**Multiserver address:**\n\n```\nssb:address/multiserver?multiserverAddress=\u003cMSADDR\u003e\n```\n\nWhere `\u003cMSADDR\u003e` is a [multiserver address](https://github.com/ssbc/multiserver-address) string, but [percent-encoded according to RFC3986 2.1](https://tools.ietf.org/html/rfc3986#section-2.1), for example:\n\n```\nssb:address/multiserver?multiserverAddress=net%3Awx.larpa.net%3A8008~shs%3ADTNmX%2B4SjsgZ7xyDh5xxmNtFqa6pWi5Qtw7cE8aR9TQ%3D\n```\n\n### Colon-separated canonical SSB URIs\n\nCanonical SSB URIs **SHOULD** use `/` to separate the parts of the path component, but they **MAY** also use `:` to separate the parts. The following syntax is acceptable (and is currently what `ssb-uri` utilizes, exclusively):\n\n```\nssb:message:classic:\u003cMSGID\u003e\nssb:message:bendybutt-v1:\u003cMSGID\u003e\nssb:feed:classic:\u003cFEEDID\u003e\nssb:feed:bendybutt-v1:\u003cFEEDID\u003e\nssb:blob:classic:\u003cBLOBID\u003e\nssb:address:multiserver?multiserverAddress=\u003cMSADDR\u003e\n```\n\n### Experimental SSB URIs\n\nThese SSB URIs are free-form and allow developers to pass any parameters to SSB applications without requiring consensus among the SSB applications. These URIs have an _empty authority_ component and path component always matching `experimental` (this is to support Firefox's handling of custom schemes) but have a _non-empty query_ component. The query parameters are the only mechanism through which information is conveyed. They satisfy the syntax below (any number of parameters allowed, but we show two, for illustration):\n\n```\nssb:experimental?\u003ckey1\u003e=\u003cvalue1\u003e\nssb:experimental?\u003ckey1\u003e=\u003cvalue1\u003e\u0026\u003ckey2\u003e=\u003cvalue2\u003e\n```\n\n#### Known experimental SSB URIs\n\nExperimental SSB URIs do not need to be included in this specification before they can be used, but we encourage developers to submit all known experimental SSB URIs depended by applications. This facilitates the future canonicalization of new SSB URIs. Please feel free to submit new entries here, as long as you know they are used in applications:\n\n**Action to join a room:**\n\nSome experimental SSB URIs have the query `action` to describe intents to perform certain tasks in the SSB application.\n\nA `action=claim-http-invite` experimental URI is used to refer to the consumption of a [Rooms 2](https://github.com/ssb-ngi-pointer/rooms2) invite code, syntax as follows, which includes a `multiserverAddress` query like the canonical multiserver address URI has too:\n\n```\nssb:experimental?action=claim-http-invite\u0026invite=\u003cCODE\u003e\u0026multiserverAddress=\u003cMSADDR\u003e`\n```\n\n**Action to consume an alias:**\n\nA URI with query `action=consume-alias` allows us to refer to the processing [consuming a room alias](https://github.com/ssb-ngi-pointer/rooms2/blob/573cc4b3afc08a4eccaea530104524aa7f60af9f/docs/Alias/Alias%20consumption.md), syntax as follows:\n\n```\nssb:experimental?action=consume-alias\u0026alias=\u003cA\u003e\u0026userId=\u003cUID\u003e\u0026signature=\u003cSIG\u003e\u0026multiserverAddress=\u003cMSADDR\u003e\u0026roomId=\u003cRID\u003e\n```\n\n**Action to start HTTP authentication:**\n\nA URI with query `action=start-http-auth` is for initiating [Sign-in with SSB](https://github.com/ssb-ngi-pointer/rooms2/blob/573cc4b3afc08a4eccaea530104524aa7f60af9f/docs/Setup/Sign-in%20with%20SSB.md) (HTTP Authentication) with an SSB remote server. The syntax is as follows:\n\n```\nssb:experimental?action=start-http-auth\u0026sid=\u003cSID\u003e\u0026sc=\u003cSC\u003e\n```\n\n### Process to canonicalize SSB URIs\n\nWhen experimental SSB URIs are adopted by SSB applications, if they are deemed useful and long-term URIs, there should be discussion among stakeholders (SSB application developers, and protocol developers) to specify a canonical SSB URI format (using path component) to replace the experimental SSB URI. Then, the new canonical SSB URI should be specified in this document.\n\n## Grammar\n\nThe following grammar specifies all SSB URIs (both canonical and any experimental) using [Nearley](https://nearley.js.org):\n\n```nearley\nuri -\u003e scheme delimiter body\n\nscheme -\u003e \"ssb\"\n\ndelimiter -\u003e \":\"\n\nseparator -\u003e [:/]\n\nbody -\u003e parts1 (queries):? | parts3 (queries):? | parts4 (queries):?\n\nparts1 -\u003e type1\nparts3 -\u003e type3 separator alg3 separator value\nparts4 -\u003e type4 separator alg4 separator value separator value\n\nqueries -\u003e \"?\" (query):+\nquery -\u003e queryKey \"=\" queryVal\nqueryKey -\u003e [a-zA-Z] ([^=]):*\nqueryVal -\u003e [a-zA-Z0-9] ([^\u0026]):*\n\ntype1 -\u003e \"experimental\"\ntype3 -\u003e \"message\" | \"feed\" | \"blob\" | \"address\" | \"encryption-key\" | \"identity\"\ntype4 -\u003e \"feed\"\n\nalg3 -\u003e \"classic\" | \"multiserver\" | \"bendybutt-v1\" | \"gabbygrove-v1\" | \"buttwoo-v1\" | \"indexed-v1\" | \"cloaked\" | \"box2-dm-dh\" | \"po-box\" | \"group\" | \"fusion\"\nalg4 -\u003e \"buttwoo-v1\"\n\nvalue -\u003e ([0-9a-zA-Z\\-\\_\\=]):+\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fssbc%2Fssb-uri-spec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fssbc%2Fssb-uri-spec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fssbc%2Fssb-uri-spec/lists"}