commit: 0ec4083628cbff4541855bd69c4b66b3491ca2be
parent 2e21c8e51e9ec602d7b175edeb229996951940ee
Author: William Pitcock <nenolod@dereferenced.org>
Date: Wed, 26 Jun 2019 17:43:22 -0500
litepub spec chapter 1
Diffstat:
5 files changed, 341 insertions(+), 8 deletions(-)
diff --git a/_includes/nav.html b/_includes/nav.html
@@ -6,17 +6,14 @@
<li><a href="{{ site.baseurl }}/ap-compat.html">LitePub and ActivityPub</a></li>
</ul>
-<h2>Profiles</h2>
+<h2>Core Specification</h2>
<ul>
- <li><a href="{{ site.baseurl }}/profiles.html">Profiles Overview</a></li>
- <li><a href="{{ site.baseurl }}/profile/agent.html">LitePub Agent</a></li>
- <li><a href="{{ site.baseurl }}/profile/relay.html">LitePub Relay</a></li>
- <li><a href="{{ site.baseurl }}/profile/forwarder.html">LitePub Forwarder</a></li>
+ <li><a href="{{ site.baseurl }}/spec/index.html">LitePub Living Standard</a></li>
</ul>
-<h2>Vocabulary</h2>
+<h2>Extensions</h2>
<ul>
- <li><a href="{{ site.baseurl }}/vocabulary.html">Vocabulary Overview</a></li>
+ <li><a href="{{ site.baseurl }}/lep/index.html">Index of proposed LitePub extensions</a></li>
</ul>
diff --git a/_layouts/default.html b/_layouts/default.html
@@ -2,7 +2,7 @@
<html lang="en">
<head>
<meta charset="utf-8">
- <title>{{ page_title | strip }}</title>
+ <title>LitePub: {{ page.title | strip }}</title>
<link href="{{ site.baseurl }}/assets/css/main.css" rel="stylesheet">
</head>
<body>
@@ -15,6 +15,10 @@
<h1>{{ page.title }}</h1>
{% endif %}
+ {% if page.status %}
+ <h2>{{ page.status }} — {{ page.last_updated }}</h2>
+ {% endif %}
+
{{ content }}
</div>
</body>
diff --git a/assets/css/main.css b/assets/css/main.css
@@ -16,3 +16,11 @@ nav {
.content {
flex: 2;
}
+
+.full-width {
+ width: 100%;
+}
+
+th {
+ text-align: left;
+}
diff --git a/spec/index.md b/spec/index.md
@@ -0,0 +1,9 @@
+---
+title: "LitePub"
+status: "Living Standard"
+last_updated: "June 26, 2019"
+---
+
+### Table of Contents
+
+1. [Introduction](intro.html)
diff --git a/spec/intro.md b/spec/intro.md
@@ -0,0 +1,315 @@
+---
+title: "LitePub (Introduction)"
+status: "Living Standard"
+last_updated: "June 26, 2019"
+---
+
+### Where does this specification fit?
+
+This specification defines a significant part of the Social Web Platform. The
+Social Web Platform is a platform which is built on top of a set of federated
+protocols. LitePub is one of the most commonly used protocols in the Social
+Web Platform.
+
+
+### Is this ActivityPub?
+
+*This section is non-normative.*
+
+In short: Yes.
+
+In more length: ActivityPub is a less rigid specification of the same basic
+protocol. It is maintained by the [W3C Social Web Community Incubator Group][w3c-swicg].
+LitePub is maintained by the LitePub community, which primarily consists of
+developers who are shipping LitePub implementations. Accordingly, the LitePub
+specification presents the same basic technology in a context that does not
+depend on an understanding of other W3C technologies, such as the Linked Data
+Platform.
+
+ [w3c-swicg]: https://www.w3.org/wiki/SocialCG
+
+
+### Background
+
+*This section is non-normative.*
+
+LitePub is a more rigid, vendor-oriented specification of ActivityPub.
+In this way, LitePub defines a specific profile of ActivityPub.
+
+ActivityPub is the Social Web's core federation protocol. Originally,
+ActivityPub was created as a formal specification of the pump.io
+federation protocol reworked to leverage [ActivityStreams 2.0][as2] for
+the purpose of federated microblogging. However, it's generic design
+has enabled it to be leveraged for many different kinds of applications.
+
+ [as2]: https://www.w3.org/TR/activitystreams-core/
+
+
+### Audience
+
+*This section is non-normative.*
+
+This specification is targeted at developers who intend to write software
+which federates using the LitePub or ActivityPub protocol.
+
+This document is probably not suited for readers who do not already have
+a passing familiarity with the underlying concepts of federated protocols,
+as it sacrifices clarity for precision and strives for completeness.
+
+There are better guides and tutorials that demonstrate how to build a
+federated service using the protocol described by this document.
+
+
+### Scope
+
+*This section is non-normative.*
+
+This specification is limited to describing the core federation protocol
+used for LitePub implementations to federate with other LitePub
+implementations. Many use-cases are more appropriately solved by using
+the [LitePub extension process](/litepub/lep/index.html).
+
+
+### Compatibility with other specifications
+
+*This section is non-normative.*
+
+This specification interacts with other specifications, namely:
+
+ * [ActivityPub][ap]
+ * [ActivityStreams 2.0][as2]
+ * [Activity Vocabulary][as2-vocab]
+ * [WebFinger][webfinger]
+ * [W3C Web Payments Security Vocabulary][security-vocab]
+
+In certain cases, unfortunately, due to conflicting requirements, this
+specification violates certain requirements of these other specifications.
+We have attempted to mark these violations as **willful violations** and
+note the reason why our specified behaviour differs.
+
+ [ap]: https://www.w3.org/TR/activitypub
+ [as2-vocab]: https://www.w3.org/TR/activitystreams-vocabulary
+ [webfinger]: https://tools.ietf.org/html/rfc7033
+ [security-vocab]: https://web-payments.org/vocabs/security
+
+
+### Extensibility
+
+*This section is non-normative.*
+
+ActivityPub treats extensibility as a function of JSON-LD, by extending the
+JSON-LD `@context` in a given ActivityPub message.
+
+LitePub treats extensibility by requiring that extensions namespace their
+keywords and enumerable values in an IRI namespace. This is functionally
+equivalent to the JSON-LD way when processed by a JSON-LD implementation.
+A full discussion of this is available in the [extensions](extensions.html)
+section.
+
+
+### Security
+
+*This section is non-normative.*
+
+ActivityPub does not define a security model. In this absence, the community
+has built a security model based on signature-based authentication. This
+security model is highly inefficient and there are significant concerns with
+it's usage of signature-based authentication as a substitute for authorization.
+
+LitePub defines two security models:
+
+ * the [legacy security model](security-legacy.html), which is a formal
+ description of the defacto ActivityPub security model
+
+ * the [OCAP security model](security-ocap.html), which is a new security
+ model we intend to replace the legacy security model with.
+
+
+### Privacy Concerns
+
+*This section is non-normative.*
+
+All messages in LitePub are associated with a given actor. This means that
+messages are always linkable to their actor. Additionally, when the legacy
+security model is used, messages may contain either [LDS signatures][lds] or
+[HTTP signatures][httpsigs]. The presence of these signatures may be used
+to cryptographically link the message to the actor, creating secondary
+metadata leakage. [Blind Key Rotation][bkr] has been created as a partial
+mitigation for this problem.
+
+Because of the actor-oriented protocol design, LitePub should not be used
+in environments where anonymity is required.
+
+ [lds]: https://w3c-dvcg.github.io/ld-signatures/
+ [httpsigs]: https://tools.ietf.org/html/draft-cavage-http-signatures-10
+ [bkr]: https://blog.dereferenced.org/the-case-for-blind-key-rotation
+
+
+### A Quick Introduction To LitePub
+
+*This section is non-normative.*
+
+LitePub is a server to server federation protocol, which enables websites
+to exchange messages. In LitePub, a user account is represented by an
+"[actor](actors.html)". Accounts on different servers correspond to
+different actors.
+
+An actor is required to have:
+
+ * an `inbox`: an endpoint for receiving messages
+ * an `outbox`: an endpoint which enumerates messages that have been sent
+
+These are endpoints (URLs) that are listed in the actor's ActivityStreams
+description.
+
+Here's an example actor object representing a person named Alyssa P. Hacker:
+
+<figure>
+<figcaption>Example: Actor object for Alyssa P. Hacker</figcaption>
+<pre>{
+ "@context": "https://litepub.social/litepub/litepub-v0.1.jsonld",
+ "type": "Person",
+ "id": "https://social.example/~alyssa",
+ "name": "Alyssa P. Hacker",
+ "preferredUsername": "alyssa",
+ "summary": "Lisp enthusiast hailing from MIT",
+ "inbox": "https://social.example/~alyssa/inbox",
+ "outbox": "https://social.example/~alyssa/outbox",
+ "followers": "https://social.example/~alyssa/followers",
+ "following": "https://social.example/~alyssa/following",
+ "liked": "https://social.example/~alyssa/liked"
+}</pre>
+</figure>
+
+LitePub uses [ActivityStreams 2.0][as2] for it's core vocabulary, which
+describes almost everything you would ever need for any social networking
+application. LitePub can also be extended, read about it in the
+[extensions section](extensions.html).
+
+Alyssa can talk to her friends by using the `inbox` and `outbox` endpoints
+associated with her profile:
+
+ * Messages are *sent* to other actors by *POST*-ing to the other actor's
+ inbox.
+
+ * Messages are *fetched* from other users by *GET*-ing the other actor's
+ outbox.
+
+Typically federation happens by pushing messages to actor inboxes, however.
+There are other methods beyond using HTTP POST and GETs to federate as well,
+but these aren't considered part of the core protocol.
+
+So, let's say that Alyssa wants to say hello to her friend Bob. To accomplish
+this, her LitePub implementation would push a `Create` message to Bob's inbox:
+
+<figure>
+<figcaption>Example: Create message used to send a note</figcaption>
+<pre>{
+ "@context": "https://litepub.social/litepub/litepub-v0.1.jsonld",
+ "type": "Create",
+ "id": "https://social.example/~alyssa/posts/a29a6843-9feb-4c74-a7f7-081b9c9201d3",
+ "to": ["https://other.example/~bob"],
+ "actor": "https://social.example/~alyssa",
+ "object": {
+ "type": "Note",
+ "attributedTo": "https://social.example/~alyssa",
+ "id": "https://social.example/~alyssa/posts/49e2d03d-b53a-4c4c-a95c-94a6abf45a19",
+ "to": ["https://other.example/~bob"],
+ "content": "hey bob!"
+ }
+}
+</pre>
+</figure>
+
+In order to push this `Create` message, however, Alyssa's server must first
+find Bob. To facilitate this, we use [WebFinger][webfinger] to look up his
+ActivityStreams actor. Leveraging WebFinger, Alyssa can find Bob simply by
+looking up `bob@other.example`, fetch his actor object and then find the
+inbox to push the message to.
+
+Later on, Bob replies back to Alyssa and she receives the reply in her inbox:
+
+<figure>
+<figcaption>Example: Create message used to send a note in reply to another note</figcaption>
+<pre>{
+ "@context": "https://litepub.social/litepub/litepub-v0.1.jsonld",
+ "type": "Create",
+ "id": "https://other.example/~bob/p/56783",
+ "to": ["https://social.example/~alyssa"],
+ "actor": "https://other.example/~bob",
+ "object": {
+ "type": "Note",
+ "attributedTo": "https://other.example/~bob",
+ "id": "https://other.example/~bob/p/56784",
+ "inReplyTo": "https://social.example/~alyssa/posts/49e2d03d-b53a-4c4c-a95c-94a6abf45a19",
+ "to": ["https://social.example/~alyssa"],
+ "content": "hi alyssa!"
+ }
+}</pre>
+</figure>
+
+Finally, Alyssa publishes a public note to her followers collection and
+the general public. The special `https://www.w3.org/ns/activitystreams#Public`
+(`as:Public`) security label is used to grant access to the public.
+
+<figure>
+<figcaption>Example: Create message addressed to followers + <code>as:Public</code></figcaption>
+<pre>{
+ "@context": "https://litepub.social/litepub/litepub-v0.1.jsonld",
+ "type": "Create",
+ "id": "https://social.example/~alyssa/posts/9282e9cc-14d0-42b3-a758-d6aeca6c876b",
+ "to": ["https://social.example/~alyssa/followers",
+ "https://www.w3.org/ns/activitystreams#Public"],
+ "actor": "https://social.example/~alyssa",
+ "object": {
+ "type": "Note",
+ "attributedTo": "https://social.example/~alyssa",
+ "id": "https://social.example/~alyssa/posts/d18c55d4-8a63-4181-9745-4e6cf7938fa1",
+ "to": ["https://social.example/~alyssa/followers",
+ "https://www.w3.org/ns/activitystreams#Public"],
+ "content": "federated social networking is so much fun!"
+ }
+}</pre>
+</figure>
+
+
+### Conformance
+
+Sections that are explicitly marked non-normative, as well as diagrams, examples and
+notes in this specification are non-normative. Everything else in this specification
+is normative.
+
+The keywords MAY, MUST, MUST NOT, SHOULD and SHOULD NOT are to be interpreted as
+described in [RFC2119][rfc2119].
+
+ [rfc2119]: https://tools.ietf.org/html/rfc2119
+
+
+### Suggested Reading
+
+*This section is non-normative.*
+
+The following documents may be of interest to readers of this specification:
+
+<cite>Unicode Security Considerations</cite> ([UTR36][utr36])
+
+> LitePub is based on UTF-8, an encoding of Unicode. There are several security
+> concerns involved with handling Unicode input. This document describes those
+> security concerns as well as suggests mitigations.
+
+ [utr36]: https://www.unicode.org/reports/tr36/
+
+<cite>ActivityStreams 2.0</cite> ([AS2][as2]), <cite>Activity Vocabulary</cite> ([AS2-VOCAB][as2-vocab])
+
+> LitePub is built ontop of ActivityStreams 2.0 and the Activity Vocabulary.
+
+<cite>WebFinger</cite> ([RFC7033][webfinger])
+
+> LitePub implementations typically use WebFinger for mapping user@domain
+> identifiers to actors.
+
+<cite>HTTP Signatures</cite> ([HTTPSIGS][httpsigs])
+
+> LitePub implementations sign and verify messages using HTTP signatures
+> when implementing the legacy security model, as well as when establishing
+> a new connection in the OCAP security model.
