sites/wiki.trwnh.com
1
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

as2/ap requirements and recommendations

Browse source
This commit is contained in:
a 2023-04-02 07:04:31 -05:00
parent 1f5950bc39
commit 5e8d05c57b
6 changed files with 302 additions and 4 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
assets/styles/components/table-of-contents.scss
View file

@ -21,4 +21,10 @@
li > ul, li > ol { /* indent subheadings */
margin-inline-start: 1em;
}
}
.toc details {
max-width: 45ch;
background: rgba(0,0,0,0.2);
padding: 1em;
border-radius: 0.5em;
}

18
assets/styles/features/headings.scss
View file

@ -65,14 +65,30 @@ article[autonumbering] {
}
#TableOfContents :is(ol, ul) {
/*
each list gets a new counter
*/
counter-reset: item;
margin-inline-start: 0;
}
#TableOfContents li:before {
/*
the counter is added as a pseudo-element,
and nested counters are joined by a dot
*/
content: counters(item, ".") " ";
counter-increment: item;
/* ensure the counters align visually */
font-family: monospace;
font-weight: bold;
margin-inline-end: 0.5em;
margin-inline-end: 1em;
}
#TableOfContents > ul > li {
/*
top-level items wrap after the number,
in order to add some visual separation
*/
display: flex;
flex-flow: column;
}
}

2
content/_dump/_index.md Normal file
View file

@ -0,0 +1,2 @@
+++
+++

272
content/tech/spec/activitypub/!requirements.md Normal file
View file

@ -0,0 +1,272 @@
+++
title = "understanding activitypub as a set of normative requirements and recommendations"
toc = true
autonumbering = true
+++
## what is activitypub
in the simplest terms? "email for websites". you POST to inbox or outbox. the serialization of messages is activitystreams 2.0 (as2), and certain activities have defined side-effects when received in the inbox or outbox. client-to-server (c2s) uses the outbox, and server-to-server (s2s) uses the inbox.
### theoretical foundation for activitypub
- actor model. an actor is something that is programmed to behave in a certain way.
- message passing. the way actors communicate is to pass messages around, which are handled according to local procedures programmed into the actor.
- ontology. the nature of being. this is done with a resource description framework (RDF) where you have a set of statements (facts) about each resource.
- open world assumption. in logic systems, facts are not necessarily known by everyone.
## activitystreams 2.0 as a foundation for activitypub
AS2 documents represent resources and are described with properties. JSON-LD is used as a serialization of RDF.
### requirements
technical:
- 2: empty arrays are explicitly set to `null` or excluded entirely
- 2: use UTF-8
- 2.1: equivalent to JSON-LD compaction against `{"@context": "https://www.w3.org/ns/activitystreams"}`
- 2.1: do not override definitions from `https://www.w3.org/ns/activitystreams`
- 2.1: if `@context` is missing, assume or inject `https://www.w3.org/ns/activitystreams`
- 2.2: any international links (IRIs) should be converted to ascii (URIs) unless used as an `id`
- 2.3: datetimes use RFC3339, and use a "Z" if there is no timezone offset
- 4.1, 4.3, 4.4: if you use an extension type that overlaps with a core vocab type, do not exclude the core type from the `type` array [e.g. a vcard `Individual` should also explicitly be an as2 `Person`]
- 4.1: prefer as2 vocab when properties overlap [e.g. use as2 `name` instead of schema.org `name`]
- 4.2: Link `rel` must be valid in both RFC5988 and in HTML5 (registered or unregistered)
- 4.7: for language maps (`nameMap` /`summaryMap` / `contentMap`), every key is a well-formed BCP47 language tag, and every value is a string
- 4.7.2: properly handle bidirectional text
- 5: if you encounter something you don't understand, ignore it and continue processing as normal. do not stop or error.
- 5.1: if you want to support extensions, support compact iri expansion [i.e. `prefix:term` should be expanded according to the definition for `prefix`] for properties and `@id` values.
- 8.1: if using `application/activity+json; profile=""` then the list of profiles must be quoted [inside the double quotes]. `application/json` also still applies.
- 9.1: do not use deprecated as1 vocab. use as2 vocab. if you use other vocabs then also use as2 still. do not use json-ld algorithms other than compaction. use json-ld for extensions.
non-technical / restatements:
- 6, 7: tell your users when and why their personal info is needed/published. do not re-emit malicious input you consume [xss, etc]
- 9.2.1: conforming publishers make as2 documents following as2 serialization. consider privacy. consider security.
- 9.2.2: conforming consumers tolerate deprecated or obsolete as1 props. ignore props or types that aren't applicable to you. faithfully translate info when presenting on screen, in print, in audio, etc. consider privacy and security.
- B.2: `application/stream+json` or generic `application/json` is processed with old as1 rules. as2 only applies when using `application/activity+json`
### recommendations
technical:
- 1.2: do not use `displayName`, `verb`, `title`, or `objectType`. if encountered, process them using the deprecated AS1 syntax
- 2.1: include a `@context` property even if you don't process JSON-LD
- 2.2: do not use relative IRIs; plain json parsers have trouble with this
- 4.1, 4.3, 4.4: take care not to overlap or duplicate existing types
- 4.1.1: `name` is derived from user input. if not present, then `summary` should be plaintext and derived from user input, as well as being short enough to use as a reasonable text representation of the object
- 4.1.1: have a fallback strategy in case `name` and `summary` are missing or not available in your user's language or are too long
- 4.3: use vcard for describing Person, Group, Organization
- 4.6: if you wanna reconstruct a paged OrderedCollection, go to the first/last page and follow the next/prev links until all pages have been processed
- 4.6: OrderedCollection should use OrderedCollectionPage to maintain relative ordering
- 4.7.2: publishing bidirectional text should use explicit unicode control character or HTML
- 4.7.2: consumers should identify base direction of text
- 4.8: explicitly mark the language for natural language properties if the language is known (using either maps or default `@language` tag)
- 5: if you want to support extensions, use JSON-LD. define all extension term in `@context`
- 5.1: avoid compact IRIs except for property names and for types
- 5.2: if you use LD and reserialize an as2 document, preserve any properties/extensions you don't understand (by compacting against the original `@context` instead of your own)
- 8: consider `application/ld+json; profile="https://www.w3.org/ns/activitystreams"` as being equivalent to `application/activity+json`
non-technical:
- 6: limit sensitive personal info unless users "opt in"
- 6: do not store or share personal info unless users "opt in"
- 7: prevent spam and malicious content
- 7: do not publish malicious input from users
- 7: use rel=nofollow or convert links to plaintext to avoid SEO loopholes
- 7: be aware of spoofing attacks
- B: don't output AS1 unless you want to remain back-compatible
- B.9: avoid using `upstreamDuplicates` and `downstreamDuplicates` from AS1
- B.10: if converting as1 to as2, treat `post` as `Create`, or if `target` is used, then treat it as `Add`
### optional
- 2.1: @context extensions are allowed before compacting
- 2.1: using properties and values not defined in @context is fine but will likely be ignored by LD consumers
- 2.1: using http instead of https for the activitystreams uri
- 2.2: using uris instead of iris (since uris are valid iris)
- 2.3: omitting seconds from datetimes
- 4.1.1: not including `name` and `summary`, or having no explicit value in your current language, or being longer than appropriate for text representations
- 4.2: using Link `rel` that is not registered
- 4.6: using `OrderedCollection` to identify Collections whose items are ordered (since Collections may or may not be ordered)
- 4.6.1: using `OrderedCollectionPage` for collection pages whose items are ordered. using `startIndex` on these.
- 4.7.1: using `@language` inside `@context` to define default language. (this might not be understood by non-LD-aware consumers)
- 4.7.2: using bidirectional text. having the base direction change. wrapping additional control characters before display.
- 7: consider spam and malicious content
- 7: convert untrusted links to plaintext or add `rel=nofollow`
- 9.2.2: republish or present any consumed document in another format or presentation mechanism
- B.9: using `upstreamDuplicates` and `downstreamDuplicates` from AS1
## as2 vocab
### requirements
- 1: be able to serialize and deserialize all extended properties even if you don't understand them
- 1.1: all `xsd:datetime` MUST conform to rules in AS2 (RFC3339)
- 3: avoid using extensions that heavily overlap with or duplicate the as2 vocab
- Question: MUST NOT have both `anyOf` and `oneOf`
- name: MUST NOT include HTML markup
- duration: MUST be xsd:duration as defined by xmlschema (e.g. `P15D`, `PT2H`, etc)
- hreflang: MUST be a BCP47 language tag
- rel: MUST conform to both RFC5988 and HTML5 (cannot contain space, tab, LF, FF, CR, or comma)
- 5.1: remove `bto` and `bcc` before redistributing. they are part of the primary/secondary audience, but not disclosed to anyone else.
- Place: (non-normative) MUST support `name` `longitude` `latitude` `radius` `altitude` `accuracy` even if other mechanisms are used. [you don't have to use all of them but you have to support all of them]
### recommendations
- icon: has a square (1:1) aspect ratio and is suitable for presentation at small sizes
- 5.1: leave `to` and `cc` intact if redistributing an object
- 5.6: (non-normative) don't require parsing `name`/`summary`/`content` to determine notification, categorization, or linking. use vocab explicitly for this purpose [e.g. use `to` or `tag` instead of depending on text containing `@sally` or `#givingthanks`]
- 5.6: the primary audience in `to` receives notifications
### optional
- Question: use `anyOf` or `oneOf` to express possible answers
- type: multiple values can be specified
- actor: could be an indirect Link, could have multiple values
- content, name, summary: can use multiple language-tagged values in a map (`contentMap`, etc)
- 5.1: use `to`, `cc`, `bto`, `bcc` as explicit primary and secondary audiences. use `bto` and `bcc` for privately targeting.
- 5.2: reuse existing vocabularies for describing relationships, such as FOAF or Relationship vocabs, or create your own
- 5.3: (non-normative) using other mechanisms for describing locations other than `Place`
- 5.6: (non-normative) using microsyntaxes within `content`, `name`, `summary`
- 5.2.1: (non-normative) using `result` to include side effects of `Accept`
- 5.2.1: (non-normative) using `context` to relate activities back to a common reference point and efficiently group related activities together for display or analysis
## activitypub
2.1 describes profiles for c2s "social API" and s2s "federation protocol". a conformant Client does all c2s, a conformant Server does all c2s, a conformant Federated Server does s2s
activitypub follows as2-core and as2-vocab "core classes" of Object/Link/Activity/Collection/etc
### requirements
- 3.1: persistent distributed objects have unique global `id`
- 3.1: use `id` in s2s for persistent distributed objects
- 3.2: c2s Servers present AS2 in response to `application/ld+json; profile="https://www.w3.org/ns/activitystreams"`
- 3.3: Clients specify `Accept: application/ld+json; profile="https://www.w3.org/ns/activitystreams"`
- 4.1: actors have `inbox` and `outbox`
- 4.1: dereferencing `sharedInbox` only includes Public activities
- 5: OrderedCollection is reverse chronological (newer items first)
- 5.1: `outbox` is an `OrderedCollection`
- 5.2: `inbox` is an `OrderedCollection`
- 5.2: Server deduplicates activities in inbox. (duplication might happen when an activity is addressed to a follower both implicitly via collection and explicitly via direct id.) dedupe by `id` and drop any existing activities
- 5.3: `followers` is `OrderedCollection` or `Collection` (if present)
- 5.4: `following` is `OrderedCollection` or `Collection` (if present)
- 5.5: `liked` is `OrderedCollection` or `Collection` (if present)
- 5.6: do not attempt to POST to `Public`
- 5.7: `likes` is `OrderedCollection` or `Collection` (if present)
- 5.8: `shares` is `OrderedCollection` or `Collection` (if present)
- 6: Clients discover your `outbox` and HTTP POST with `Content-Type: application/ld+json; profile="https://www.w3.org/ns/activitystreams"` using authentication with your credentials. the body is a single Activity or a single non-Activity object that will be wrapped in a Create
- 6: c2s Servers ignore any Client-provided `id` and generate their own
- 6: c2s Servers return 201 Created with `Location: <id>` header
- 6: c2s Servers remove `bto`/`bcc` before delivery but after calculating recipients for delivery
- 6: c2s Servers must add this Activity to the `outbox` collection [at least until side effects are processed]
- 6.1, 7.1.1: Clients be aware that Servers will only deliver to `to`, `cc`, `bto`, `bcc`, `audience`
- 6.1: Clients provide `object` for Create, Update, Delete, Follow, Add, Remove, Like, Block, Undo. provide `target` for Add, Remove.
- 6.2.1: wrap valid objects that aren't Activities in a Create. assign `id` to both the Object and the Create (unless transient). copy over `to`, `cc`, `bto`, `bcc`, `audience` from the wrapped object into the wrapping Create. return the id of the Create, not the object. [the object id is available via `object.id`]
- 6.3: c2s Update modifies the `object` if the actor has permission
- 6.10: c2s Undo has `Undo.actor` == `Undo.object.actor`
- 6.11: c2s Server that is also s2s Federated Server follows 7.1.1 outbox delivery
- 7: POST inbox has `Content-Type: application/ld+json; profile="https://www.w3.org/ns/activitystreams"`
- 7: GET has `Accept: application/ld+json; profile="https://www.w3.org/ns/activitystreams"`
- 7: s2s Servers provide `object` for Create, Update, Delete, Follow, Add, Remove, Like, Block, Undo. provide `target` for Add, Remove.
- 7.1: s2s Servers that deliver to Collection MUST dereference the collection with the user's credentials [[how do they have this???]] and discover inboxes for each item in the collection. limit layers of indirection through additional Collections inside Collections
- 7.1: dedupe the final recipient list
- 7.1: exclude `actor` from the final list (i.e. don't deliver to yourself)
- 7.1.2: inbox forward to `to`, `cc`, `audience` iff first time seeing + value of `to`, `cc`, `audience` is a Collection owned by the server + `inReplyTo`, `object`, `target`, `tag` are owned by the server. don't pick up any new addressees outside of `to`, `cc`, `audience`
- 7.1.3: delivery to `sharedInbox` still delivers to `inbox` for actors that don't have a `sharedInbox`
- 7.3: ensure s2s Update is authorized to modify `object` (at minimum by applying same-origin check)
- 7.5, 7.7: Reject Follow MUST NOT add actor to followers collection
### recommendations
- 3: include activitystreams @context
- 3: validate anything you receive to avoid spoofing (exact mechanism is out-of-scope, but if it is resolvable then you can fetch the `id`)
- 3.1: use HTTPS `id` for public content
- 3.1: allocate `id` in actor's namespace
- 3.2: present AS2 in response to `application/activity+json`
- 3.2: authorization checks fail with an appropriate HTTP error code (at least 403 if private)
- 3.3: Clients warn users if editing will overwrite `source`
- 4: normalize `id` when entered in ui or login form. URIs are used directly, and if normalization fails, consider it invalid. dereference the actor URI once identified
- 4.1, 5.3, 5.4: actors have `following`, `followers`
- 4.1: `sharedInbox` is a publicly readable `OrderedCollection` containing Public addressed activities
- 5: don't use "last updated" timestamp to order items in an OrderedCollection (bc it changes too much)
- 5.1: unauthenticated requests to `outbox` return all Public posts
- 5.2: filter `inbox` according to requester permissions
- 5.2: if you don't support s2s Federated Server profile, then respond to POST inbox with 405 Not Allowed
- 5.6: plain JSON consumers, be aware of equivalence of Public, as:Public, etc
- 6: POST to outbox which doesn't support c2s Server should respond with 405 Not Allowed
- 6: respect HTTP caching for Clients and Servers
- 6.1: consider `actor`/`attributedTo` of `object`/`target`/`inReplyTo`/`tag[*]` for additional recipients. if you recurse through these, set a limit for recursion (without necessarily unpacking collections)
- 6.2: Create should copy `actor` to `object.attributedTo`
- 6.2: reconcile audiences on object and Create for initial distribution [although the object can be updated to have a different audience later]
- 6.2.1: return `Location: <id of Create>` instead of id of object
- 6.3.1: c2s partial Update removes any property set to `null`. s2s Update is complete.
- 6.4: respond with 410 Gone if a Tombstone is presented, otherwise 404
- 6.5: c2s Follow adds `Follow.object` to `Follow.actor.following` iff/when an Accept Follow is received
- 6.6, 6.7: c2s Add/Remove inserts/removes `object` to/from `target` unless `target` is not owned/authorized, or unless `object` is not allowed to be added/removed to `target` (at discretion of the c2s Server)
- 6.8: c2s Like adds `object` to `actor.liked` if present
- 6.9: c2s Block prevents `object` from interacting with any `object.attributedTo == Block.actor` or `actor == Block.actor`
- 6.9: c2s Block is not delivered to `object`
- 6.10: c2s Undo will undo any side effects (e.g. Like, Follow, Block) to the extent possible [e.g. Undo Like will remove the Like from the `likes` collection and decrement the `totalItems` counter]
- 6.10: don't use c2s Undo where an "inverse activity" exists, e.g. Create->Delete or Add->Remove
- 7: any persistent distributed activity SHOULD have an `id`
- 7: s2s Federated Servers interpret a `Content-Type` or `Accept` header of `application/activity+json` as equivalent to `application/ld+json; profile="https://www.w3.org/ns/activitystreams"`
- 7: respect HTTP caching for Federated Servers
- 7.1: s2s POST to inbox returns 405 Not Allowed if not an s2s Federated Server
- 7.1: use async for delivery
- 7.1: retry delivery after network failure
- 7.1: in inbox forwarding, recurse through `inReplyTo`, `object`, `target`, `tag` (with a max recursion limit) to look for "linked objects owned by the server" [this is presented in context of "getting updates that ... involve the recipient", but i can't see this being useful when we have explicit audience/addressing, except maybe for notification policies?]
- 7.2: s2s Create appears in `inbox`
- 7.3: s2s Update replaces copy of `id == object.id` with new repr
- 7.4: s2s Delete removes copy of `id == object.id`
- 7.5: s2s Follow generates either Accept/Reject Follow delivered to `actor`. upon [sending] Accept, add the `Follow.actor` to `actor.followers` collection
- 7.6: s2s Accept Follow (where the `Follow` is one you previously sent) adds `Accept.actor` to `Follow.actor.following`
- 7.8, 7.9: s2s Add/Remove adds/removes the `object` to/from `target` unless `target` isn't owned by you(r server) or unless `object` cannot be added/removed to `target` for some other reason (at receiver's discretion)
- 7.10: s2s Like gets added to `object.likes` if present
- 7.11: s2s Announce gets added to `object.shares` if present
- A: use internationalization tooling whenever possible [i.e. setting `@language` or using map properties if a language is defined or detected]
- B.2: (non-normative) Servers do not trust Client content, and Federated Servers do not trust other Federated Servers without verification or same-origin policy. be careful to verify attribution and write permissions.
- B.4: (non-normative) check how your URI handling library handles things like `file://` and consider whitelisting only `http`/`https`/etc as needed
- B.5: (non-normative) set a limit on recursion to avoid DoS
- B.7: (non-normative) implement protections against DoS from other Federated Servers, such as rate limiting. be especially careful whenever there are side effects to activities. do not overload other Federates Servers with activities (e.g. use exponential backoff strategy)
- B.8: (non-normative) rate limit Client submissions in order to prevent DoS of Server and also to ensure it does not propagate a DoS to Federated Servers
- B.9: (non-normative) limit the size of Collection pages when requested by Clients. Clients should also prepare to self-limit by e.g. timing out or erroring if they connect to a malicious Server that serves oversized collections
- B.11: (non-normative) omit `bto` and `bcc` when displaying objects even if not delivered
### optional
- 2.1: servers may implement either c2s or s2s individually
- 3: include additional `@context` other than activitystreams
- 3.1: omit `id` from transient objects
- 3.2: dereference `id` with HTTP GET
- 3.2: servers MAY use content negotiation
- 3.2: support other behaviors such as additional protocols or HTML response
- 3.2: require authorization, and implement your own rules on top of B.1
- 3.2: use 404 Not Found to not leak existence of private objects without authorization
- 4: clients normalize provided `id` by assuming a default scheme, preferably `https`
- 4.1, 5.5: actors have `liked`
- 4.1: actors have `streams`, `preferredUsername`, `endpoints`, `endpoints.proxyUrl`, `endpoints.oauthAuthorizationEndpoint`, `endpoints.oauthTokenEndpoint`, `endpoints.provideClientKey`, `endpoints.signClientKey`, `endpoints.sharedInbox`
- 5.3, 5.4, 5.5, 5.7: filter `followers`, `following`, `liked`, `likes`, `shares` based on authenticated user or unauthenticated request
- 5.6: `sharedInbox` is for public and followers-only posts
- 5.7: objects have `likes`
- 5.8: objects have `shares`
- 6: interpret C2S `application/activity+json` as equivalent to C2S `application/ld+json; profile="https://www.w3.org/ns/activitystreams"` when used as `Accept` or `Content-Type`
- 6: activities POSTed to c2s outbox can contain embedded objects
- 6: c2s Servers carry out side effects, and the activity might appear later or disappear at any time from outbox
- 6.1: Clients MAY get inbox from additional recipients, MAY recurse through attached objects, MAY allow users to amend their addressing to include these recipients
- 6.4: c2s Server MAY take a `Delete` and replace the `object` with a `Tombstone`
- 6.12: (non-normative) support uploading media using some out-of-scope mechanism
- 7: s2s transient activities can omit `id`
- 7.1: limit indirection of Collection -> Actor to one layer
- 7.1.2: filter inbox forwarding delivery targets according to impl-specific rules like spam filtering
- 7.1.3: use `sharedInbox` to dedupe deliveries of Public activities or activities whose delivery will be determined by the receiving server
- 7.1.3: deliver Public activities to all known `sharedInbox` endpoints
- 7.3: apply same-origin check to `Update.id` and `Update.object.id`
- 7.4: replace `Delete.object` repr with a `Tombstone`
- 7.5: auto-generate Accept/Reject Follow, or require user input
- 7.5: do not send Reject Follow (though this might leave the server in an intermediate state)

6
layouts/_default/single.html
View file

@ -11,8 +11,10 @@
{{ if .Params.toc }}
<aside class="toc section">
<div class="container">
<p class="toc-title">Page outline</p>
{{ .TableOfContents }}
<details open>
<summary class="toc-title">Contents</summary>
{{ .TableOfContents }}
</details>
</div>
</aside>
{{ end }}

2
layouts/shortcodes/toc.html
View file

@ -1,6 +1,6 @@
<aside class="toc section">
<details open>
<summary class="toc-title">Contents</summary>
{{ .Page.TableOfContents }}
{{ .Page.TableOfContents }}
</details>
</aside>