From 0a262dbc966c6748a3a6691cfd2578495e3fff09 Mon Sep 17 00:00:00 2001 From: Ted Unangst Date: Sat, 19 Oct 2019 22:59:28 -0400 Subject: [PATCH] cleanup the old documentation --- docs/admin.txt | 54 ---------------------- docs/changelog.txt | 2 +- docs/honk.1 | 2 +- docs/honk.8 | 5 +++ docs/manual.txt | 110 --------------------------------------------- docs/security.txt | 25 ----------- docs/spec.txt | 75 ------------------------------- views/header.html | 2 +- views/hfcs.html | 2 +- 9 files changed, 9 insertions(+), 268 deletions(-) delete mode 100644 docs/admin.txt delete mode 100644 docs/manual.txt delete mode 100644 docs/security.txt delete mode 100644 docs/spec.txt diff --git a/docs/admin.txt b/docs/admin.txt deleted file mode 100644 index 4f4a758..0000000 --- a/docs/admin.txt +++ /dev/null @@ -1,54 +0,0 @@ - -Honk administration guide. - -This is the admin manual. Please refer to manual.txt for user documentation. - --- css - -Custom CSS may be provided by creating a views/local.css file. - --- message - -A custom server message may be set adding a ('servermsg', 'message') entry to -the config table using sqlite3. - --- emus and memes - -Custom emus may be provided by creating and populating the emus directory. -emus may be referenced when composing a honk via colon wrapping. How pleasant. -This :example: will be replaced by emus/example.png. - -To save disk space and avoid repeated uploads, the memes directory may be -prepopulated with bandwidth wasting reactions and referenced by meme: filename. - -A list of available emus and memes appears in the funzone. - --- cleanup - -One should occasionally run `honk cleanup` to free up internal space in the -database. This deletes honks older than 30 days, but not those posted by a -user. `honk cleanup [days]` may be used to adjust the timeframe. - -One may also run `honk cleanup [honker]` to delete honks older than 3 days. -This is useful to reduce the space requirements from following image bots. - -(Neither command runs vacuum, so the file size will not immediately shrink.) - --- add user - -Running `honk adduser` can add additional users. This is discouraged. - --- proxy - -honk requires a TLS terminating reverse proxy be configured. It communicates -with other servers via https URLs. - -If the proxy is configured to support caching, be mindful of the fact that -ActivityPub requests vary based on the Accept and Content-Type headers. - -ActivityPub in practice uses HTTP signatures to verify requests. In order for -this to work, the backend server must receive certain header fields -unmodified. In particular, the Host header and the message content cannot be -altered. - -Specifically, for nginx: `proxy_set_header Host $http_host;` diff --git a/docs/changelog.txt b/docs/changelog.txt index a4d8b81..447404d 100644 --- a/docs/changelog.txt +++ b/docs/changelog.txt @@ -10,7 +10,7 @@ changelog + Better markdown output. -+++ Add Honk Filtering and Censoring System (HFCS). ++++ Add Honk Filtering and Censorship System (HFCS). + Inline images in received posts. diff --git a/docs/honk.1 b/docs/honk.1 index 7a8047c..66692d2 100644 --- a/docs/honk.1 +++ b/docs/honk.1 @@ -97,7 +97,7 @@ Alas, Update activities do not federate reliably. .Ss Honking Refer to the .Xr honk 5 -section of the manual. +section of the manual for details of honk composition. .Ss HFCS Sometimes other users of the federation can get unruly. The honk filtering and censorship system, diff --git a/docs/honk.8 b/docs/honk.8 index 4d45fde..92b8ca7 100644 --- a/docs/honk.8 +++ b/docs/honk.8 @@ -120,6 +120,11 @@ Restart. There's also a .Pa blob.db file which is important to backup and restore. +.Sh SECURITY +.Nm +is not currently hardened against SSRF, server side request forgery. +Be mindful of what other services may be exposed via localhost or the +local network. .Sh ENVIRONMENT Image processing and scaling requires considerable memory. It is recommended to adjust the datasize ulimit to at least 1GB. diff --git a/docs/manual.txt b/docs/manual.txt deleted file mode 100644 index ca855ad..0000000 --- a/docs/manual.txt +++ /dev/null @@ -1,110 +0,0 @@ - -Instructions for using honk. - -This is the user manual. Please refer to admin.txt for administration. - --- posting - -Should work as expected. - -Limited markdown support: - **bold** and *italics* - `code` and ```code block``` - > quote - -Large images are rescaled and reduced. - -The honk back button will prefill the forms for replies. - --- sensitive honks - -A honk that begins with the danger zone indication, DZ:, will be marked -sensitive, using the first line as a summary (spoiler text). - --- following - -In order to follow somebody, you need to enter one of two identifiers. - -The easiest is probably their handle, the thing that resembles an email. -@name@example.com for example. - -Alternatively, one may directly enter the actor ID, which is a URL that looks -like https://example.com/users/name. - -Followed honkers may be assigned to combos, listing all their honks together. - -Followed honkers will appear on the main feedtube unless silenced. Honkers may -be silenced by adding them to a combo named "-". (One dash.) - -Selecting just peeping won't actually follow them. (Incomplete feature.) -Can be useful for managing as part of a combo, however. - --- xzone - -Individual honks may be manually fetched via the xzone. - -Additionally, entering a honker URL will fetch all their recent honks. - -A list of recently known honkers will appear as well. - --- zonking - -You can zonk anything you like (or dislike), either your own honk or -those of others that you're tired of seeing. Be advised that deletion -works poorly in a federated environment. It's more like please disregard. - --- privacy - -Posted honks are public. The federated environment lacks robust privacy -controls. - -Received messages are only visible when logged in, regardless of addressing. -Content from outside is not publicly rehosted, unless bonked. - -Received messages that are less than public are tagged with a red border. -As a special exception to the public honking rule, replies to limited messages -will be restricted as much as possible. Note that ActivityPub leaks. Do -not use honk for posting truly private information. - --- emus and memes - -A list of available emus and memes appears in the funzone. - -Emus such as :example: will be inlined into posts. - -Memes such as `meme: example.mp4` will be appended to posts. - --- hoots - -Link and inline a hoot and replies from that other bird site. -hoot: https://twitter.com/tedunangst/status/839169710675611658 - --- cleanup - -One should occasionally run `honk cleanup` to free up internal space in the -database. This deletes honks older than 30 days, but not those posted by a -user. - -One may also run `honk reduce [honker]` to delete honks older than 3 days. -This is useful to reduce the space requirements from following image bots. - -(Neither command runs vacuum, so the file size will not immediately shrink.) - --- add user - -Running `honk adduser` can add additional users. This is discouraged. - --- proxy - -honk requires a TLS terminating reverse proxy be configured. It communicates -with other servers via https URLs. - -If the proxy is configured to support caching, be mindful of the fact that -ActivityPub requests vary based on the Accept and Content-Type headers. - -ActivityPub in practice uses HTTP signatures to verify requests. In order for -this to work, the backend server must receive certain header fields -unmodified. In particular, the Host header and the message content cannot be -altered. - -Specifically, for nginx: `proxy_set_header Host $http_host;` diff --git a/docs/security.txt b/docs/security.txt deleted file mode 100644 index 56d82c4..0000000 --- a/docs/security.txt +++ /dev/null @@ -1,25 +0,0 @@ - -Some notes about security. - -honk is not currently hardened against SSRF, server side request forgery. Be -mindful of what else may be reachable on localhost or the local network if -it's not generally accessible. - -Key and signature verification is best effort, but some forgeries may sneak -past. In particular, tying together key name, key owner, actor, object, etc. -is incomplete. - -How are user keys supposed to be rotated? Expired? Revoked? - -The current answer is never, never, never. - -If the key is only used for signing http requests, it can be be changed -basically at will. Change the key in the actor, give it a new name (to avoid -conflict with any cached keys), carry on. - -Since keynames in practice don't change, honk will simply discard a key after -a signature failure and attempt to get a fresh key. - -Using keys to sign json is more complicated. The current practice is to name -keys with URL fragments. example.com/user#key. If the keyname is changed to -#newkey, how does one fetch the old key to verify existing data? diff --git a/docs/spec.txt b/docs/spec.txt deleted file mode 100644 index 4eb1125..0000000 --- a/docs/spec.txt +++ /dev/null @@ -1,75 +0,0 @@ -honk spec - --- references - -See security.txt for some notes on security. - -See ping.txt for a proposed Ping extension to ActivityPub. - --- retries - -If a message can't be delivered, we backoff and retry. - -1 - five minutes later in case the servce restarted -2 - one hour later in case the server rebooted -3 - 12 more hours later in case the server was upgraded -4 - 24 more hours later in case there was a catastrophe -5 - it's dead. - -A random drift of up to 10% is added to each delay to avoid swarming. - --- federating - -Messages are transformed for federation and display. Some transformations -occur send side and some occur receive side because it's more exciting that -way. @mentions and *markdown* are converted to HTML before transmission. -Message :emoji: are converted to inline images after receiving. - -Up to four parents of a reply will be fetched. - -Attachments for received messages are rescaled before saving. - --- schema - -Some notes on the database schema. Mostly for development, but maybe useful -for administration as well. - -The config table contains settings, some of which may not be editable via the -normal interface. - -For development purposes, adding a config value ('debug', 1) to the database -will disable caching and hot reload the templates. It's not meant to be -harmful in production, just less efficient. - -We don't use null, only empty strings. This is easier to work with on the go -side. - -The main table is honks. This stores both locally created honks and incoming -ActivityPub notes converted to honks. It is important to differentiate the two -cases so that we don't accidentally publish external honks in the public web -view. The whofore column value of 2 indiciates a public honk. - -The what column further refines the type of honk. - -Attachments are physically saved as files, and logically joined to honks via -the donks table. Emus are saved as donks as well. - -The honkers table is used to manage follows and followers. The flavor column -describes what. 'sub' is a follow. We have subscribed to their newsletter. -'dub' is a follower. They get dubbed whenever we honk. - -The xonkers table stores info about external accounts that we may interact -with. Their keys, their inboxes, etc. Not user visible. - -The zonkers table stores things we do not wish to see, per the wherefore -column. Also used for tombstones for deleted honks to prevent refetching. - -The xid column generally corresponds to ActivityPub id. - -Note that some logical seeming joins won't work. The honker column of honks -may not have a corresponding entry in the honkers table, since we frequently -receive messages from people we don't follow. Should we track everybody whose -identity crosses our path? This seems unnecessary. The honkers table is more -like a mapping of active relationships, not a directory of all peoples. - -Some deduping of honks is performed. This may not be perfect. diff --git a/views/header.html b/views/header.html index 0260e9d..998cb2f 100644 --- a/views/header.html +++ b/views/header.html @@ -35,7 +35,7 @@
  • events
  • saved
  • honkers -
  • hfcs +
  • filters
  • my honks
  • xzone
  • account diff --git a/views/hfcs.html b/views/hfcs.html index c86be82..d840fad 100644 --- a/views/hfcs.html +++ b/views/hfcs.html @@ -2,7 +2,7 @@

    -Honk Filtering and Censoring System +Honk Filtering and Censorship System