Website of https://litepub.social/ git clone https://hacktivis.me/git/litepub.social.git

intro.md (11532B)

  1. ---
  2. title: "LitePub (Introduction)"
  3. status: "Living Standard"
  4. last_updated: "June 26, 2019"
  5. ---
  6. ### Where does this specification fit?
  7. This specification defines a significant part of the Social Web Platform. The
  8. Social Web Platform is a platform which is built on top of a set of federated
  9. protocols. LitePub is one of the most commonly used protocols in the Social
  10. Web Platform.
  11. ### Is this ActivityPub?
  12. *This section is non-normative.*
  13. In short: Yes.
  14. In more length: ActivityPub is a less rigid specification of the same basic
  15. protocol. It is maintained by the [W3C Social Web Community Incubator Group][w3c-swicg].
  16. LitePub is maintained by the LitePub community, which primarily consists of
  17. developers who are shipping LitePub implementations. Accordingly, the LitePub
  18. specification presents the same basic technology in a context that does not
  19. depend on an understanding of other W3C technologies, such as the Linked Data
  20. Platform.
  21. [w3c-swicg]: https://www.w3.org/wiki/SocialCG
  22. ### Background
  23. *This section is non-normative.*
  24. LitePub is a more rigid, vendor-oriented specification of ActivityPub.
  25. In this way, LitePub defines a specific profile of ActivityPub.
  26. ActivityPub is the Social Web's core federation protocol. Originally,
  27. ActivityPub was created as a formal specification of the pump.io
  28. federation protocol reworked to leverage [ActivityStreams 2.0][as2] for
  29. the purpose of federated microblogging. However, it's generic design
  30. has enabled it to be leveraged for many different kinds of applications.
  31. [as2]: https://www.w3.org/TR/activitystreams-core/
  32. ### Audience
  33. *This section is non-normative.*
  34. This specification is targeted at developers who intend to write software
  35. which federates using the LitePub or ActivityPub protocol.
  36. This document is probably not suited for readers who do not already have
  37. a passing familiarity with the underlying concepts of federated protocols,
  38. as it sacrifices clarity for precision and strives for completeness.
  39. There are better guides and tutorials that demonstrate how to build a
  40. federated service using the protocol described by this document.
  41. ### Scope
  42. *This section is non-normative.*
  43. This specification is limited to describing the core federation protocol
  44. used for LitePub implementations to federate with other LitePub
  45. implementations. Many use-cases are more appropriately solved by using
  46. the [LitePub extension process](/litepub/lep/index.html).
  47. ### Compatibility with other specifications
  48. *This section is non-normative.*
  49. This specification interacts with other specifications, namely:
  50. * [ActivityPub][ap]
  51. * [ActivityStreams 2.0][as2]
  52. * [Activity Vocabulary][as2-vocab]
  53. * [WebFinger][webfinger]
  54. * [W3C Web Payments Security Vocabulary][security-vocab]
  55. In certain cases, unfortunately, due to conflicting requirements, this
  56. specification violates certain requirements of these other specifications.
  57. We have attempted to mark these violations as **willful violations** and
  58. note the reason why our specified behaviour differs.
  59. [ap]: https://www.w3.org/TR/activitypub
  60. [as2-vocab]: https://www.w3.org/TR/activitystreams-vocabulary
  61. [webfinger]: https://tools.ietf.org/html/rfc7033
  62. [security-vocab]: https://web-payments.org/vocabs/security
  63. ### Extensibility
  64. *This section is non-normative.*
  65. ActivityPub treats extensibility as a function of JSON-LD, by extending the
  66. JSON-LD `@context` in a given ActivityPub message.
  67. LitePub treats extensibility by requiring that extensions namespace their
  68. keywords and enumerable values in an IRI namespace. This is functionally
  69. equivalent to the JSON-LD way when processed by a JSON-LD implementation.
  70. A full discussion of this is available in the [extensions](extensions.html)
  71. section.
  72. ### Security
  73. *This section is non-normative.*
  74. ActivityPub does not define a security model. In this absence, the community
  75. has built a security model based on signature-based authentication. This
  76. security model is highly inefficient and there are significant concerns with
  77. it's usage of signature-based authentication as a substitute for authorization.
  78. LitePub defines two security models:
  79. * the [legacy security model](security-legacy.html), which is a formal
  80. description of the defacto ActivityPub security model
  81. * the [OCAP security model](security-ocap.html), which is a new security
  82. model we intend to replace the legacy security model with.
  83. ### Privacy Concerns
  84. *This section is non-normative.*
  85. All messages in LitePub are associated with a given actor. This means that
  86. messages are always linkable to their actor. Additionally, when the legacy
  87. security model is used, messages may contain either [LDS signatures][lds] or
  88. [HTTP signatures][httpsigs]. The presence of these signatures may be used
  89. to cryptographically link the message to the actor, creating secondary
  90. metadata leakage. [Blind Key Rotation][bkr] has been created as a partial
  91. mitigation for this problem.
  92. Because of the actor-oriented protocol design, LitePub should not be used
  93. in environments where anonymity is required.
  94. [lds]: https://w3c-dvcg.github.io/ld-signatures/
  95. [httpsigs]: https://tools.ietf.org/html/draft-cavage-http-signatures-10
  96. [bkr]: https://blog.dereferenced.org/the-case-for-blind-key-rotation
  97. ### A Quick Introduction To LitePub
  98. *This section is non-normative.*
  99. LitePub is a server to server federation protocol, which enables websites
  100. to exchange messages. In LitePub, a user account is represented by an
  101. "[actor](actors.html)". Accounts on different servers correspond to
  102. different actors.
  103. An actor is required to have:
  104. * an `inbox`: an endpoint for receiving messages
  105. * an `outbox`: an endpoint which enumerates messages that have been sent
  106. These are endpoints (URLs) that are listed in the actor's ActivityStreams
  107. description.
  108. Here's an example actor object representing a person named Alyssa P. Hacker:
  109. <figure>
  110. <figcaption>Example: Actor object for Alyssa P. Hacker</figcaption>
  111. <pre>{
  112. "@context": "https://litepub.social/litepub/litepub-v0.1.jsonld",
  113. "type": "Person",
  114. "id": "https://social.example/~alyssa",
  115. "name": "Alyssa P. Hacker",
  116. "preferredUsername": "alyssa",
  117. "summary": "Lisp enthusiast hailing from MIT",
  118. "inbox": "https://social.example/~alyssa/inbox",
  119. "outbox": "https://social.example/~alyssa/outbox",
  120. "followers": "https://social.example/~alyssa/followers",
  121. "following": "https://social.example/~alyssa/following",
  122. "liked": "https://social.example/~alyssa/liked"
  123. }</pre>
  124. </figure>
  125. LitePub uses [ActivityStreams 2.0][as2] for it's core vocabulary, which
  126. describes almost everything you would ever need for any social networking
  127. application. LitePub can also be extended, read about it in the
  128. [extensions section](extensions.html).
  129. Alyssa can talk to her friends by using the `inbox` and `outbox` endpoints
  130. associated with her profile:
  131. * Messages are *sent* to other actors by *POST*-ing to the other actor's
  132. inbox.
  133. * Messages are *fetched* from other users by *GET*-ing the other actor's
  134. outbox.
  135. Typically federation happens by pushing messages to actor inboxes, however.
  136. There are other methods beyond using HTTP POST and GETs to federate as well,
  137. but these aren't considered part of the core protocol.
  138. So, let's say that Alyssa wants to say hello to her friend Bob. To accomplish
  139. this, her LitePub implementation would push a `Create` message to Bob's inbox:
  140. <figure>
  141. <figcaption>Example: Create message used to send a note</figcaption>
  142. <pre>{
  143. "@context": "https://litepub.social/litepub/litepub-v0.1.jsonld",
  144. "type": "Create",
  145. "id": "https://social.example/~alyssa/posts/a29a6843-9feb-4c74-a7f7-081b9c9201d3",
  146. "to": ["https://other.example/~bob"],
  147. "actor": "https://social.example/~alyssa",
  148. "object": {
  149. "type": "Note",
  150. "attributedTo": "https://social.example/~alyssa",
  151. "id": "https://social.example/~alyssa/posts/49e2d03d-b53a-4c4c-a95c-94a6abf45a19",
  152. "to": ["https://other.example/~bob"],
  153. "content": "hey bob!"
  154. }
  155. }
  156. </pre>
  157. </figure>
  158. In order to push this `Create` message, however, Alyssa's server must first
  159. find Bob. To facilitate this, we use [WebFinger][webfinger] to look up his
  160. ActivityStreams actor. Leveraging WebFinger, Alyssa can find Bob simply by
  161. looking up `bob@other.example`, fetch his actor object and then find the
  162. inbox to push the message to.
  163. Later on, Bob replies back to Alyssa and she receives the reply in her inbox:
  164. <figure>
  165. <figcaption>Example: Create message used to send a note in reply to another note</figcaption>
  166. <pre>{
  167. "@context": "https://litepub.social/litepub/litepub-v0.1.jsonld",
  168. "type": "Create",
  169. "id": "https://other.example/~bob/p/56783",
  170. "to": ["https://social.example/~alyssa"],
  171. "actor": "https://other.example/~bob",
  172. "object": {
  173. "type": "Note",
  174. "attributedTo": "https://other.example/~bob",
  175. "id": "https://other.example/~bob/p/56784",
  176. "inReplyTo": "https://social.example/~alyssa/posts/49e2d03d-b53a-4c4c-a95c-94a6abf45a19",
  177. "to": ["https://social.example/~alyssa"],
  178. "content": "hi alyssa!"
  179. }
  180. }</pre>
  181. </figure>
  182. Finally, Alyssa publishes a public note to her followers collection and
  183. the general public. The special `https://www.w3.org/ns/activitystreams#Public`
  184. (`as:Public`) security label is used to grant access to the public.
  185. <figure>
  186. <figcaption>Example: Create message addressed to followers + <code>as:Public</code></figcaption>
  187. <pre>{
  188. "@context": "https://litepub.social/litepub/litepub-v0.1.jsonld",
  189. "type": "Create",
  190. "id": "https://social.example/~alyssa/posts/9282e9cc-14d0-42b3-a758-d6aeca6c876b",
  191. "to": ["https://social.example/~alyssa/followers",
  192. "https://www.w3.org/ns/activitystreams#Public"],
  193. "actor": "https://social.example/~alyssa",
  194. "object": {
  195. "type": "Note",
  196. "attributedTo": "https://social.example/~alyssa",
  197. "id": "https://social.example/~alyssa/posts/d18c55d4-8a63-4181-9745-4e6cf7938fa1",
  198. "to": ["https://social.example/~alyssa/followers",
  199. "https://www.w3.org/ns/activitystreams#Public"],
  200. "content": "federated social networking is so much fun!"
  201. }
  202. }</pre>
  203. </figure>
  204. ### Conformance
  205. Sections that are explicitly marked non-normative, as well as diagrams, examples and
  206. notes in this specification are non-normative. Everything else in this specification
  207. is normative.
  208. The keywords MAY, MUST, MUST NOT, SHOULD and SHOULD NOT are to be interpreted as
  209. described in [RFC2119][rfc2119].
  210. [rfc2119]: https://tools.ietf.org/html/rfc2119
  211. ### Suggested Reading
  212. *This section is non-normative.*
  213. The following documents may be of interest to readers of this specification:
  214. <cite>Unicode Security Considerations</cite> ([UTR36][utr36])
  215. > LitePub is based on UTF-8, an encoding of Unicode. There are several security
  216. > concerns involved with handling Unicode input. This document describes those
  217. > security concerns as well as suggests mitigations.
  218. [utr36]: https://www.unicode.org/reports/tr36/
  219. <cite>ActivityStreams 2.0</cite> ([AS2][as2]), <cite>Activity Vocabulary</cite> ([AS2-VOCAB][as2-vocab])
  220. > LitePub is built ontop of ActivityStreams 2.0 and the Activity Vocabulary.
  221. <cite>WebFinger</cite> ([RFC7033][webfinger])
  222. > LitePub implementations typically use WebFinger for mapping user@domain
  223. > identifiers to actors.
  224. <cite>HTTP Signatures</cite> ([HTTPSIGS][httpsigs])
  225. > LitePub implementations sign and verify messages using HTTP signatures
  226. > when implementing the legacy security model, as well as when establishing
  227. > a new connection in the OCAP security model.