Bloat: message encodings
Messages in native bivouac are represented as XML documents. For bridged AP discussions they will probably have a JSON-LD format equivalent that is then interpreted into an unsigned/unencrypted copy in memory, for use by further layers of the software.
Bivouac's subsystems have their own dialects and syntaxes, the file extension clues you
into that, for example alice.phish
is a Phish identity document.
Private Sqlite, Public XML
State in bivouac is represented as static files left on static HTTP servers. Anything that's meant to be private should be kept in sqlite, for example users' emails on an editor, their passwords (in argon2id) or API keys to an Action.
Emails and keys and such should never be synced across instances, and any state in XML is assumed to be possibly accidentally made public. Any state in sqlite is assumed to be private and needs to be guarded as such. This means that there is only one copy of the sqlite data, if that host is offline or unrecoverable that data is gone.
Message Wrapping
Messages on bivouac are XML, which is then signed with Minisign, a small and simple verification program. This is then encrypted for the Crew recipients with Age - a similarly simple program built by professionals. Phish identities correspond to a pair of these keys (your Minisign and Age public key). XML signatures do exist but... so do XML schemas and I hardly understand those, either.
Documents should be password encoded, and then the list of documents' passwords can be encrypted to a Crew of Age recipients. That way adding or removing a member of a group does not mean re-uploading every single file, but instead providing that member with the passwords to the files.
Server Addresses
Once the files have been rendered, the folders you've generated should be published on a static HTTP server (like Caddy). Bivouac's editor needs permission to upload files (for example, FTP or SSH creds).
Bivouac content does not need to be at the root level (/
) of the website. You could, for
example, publish on /cool/beans/
. Bivouac discovery and hints are covered in Phish.
If you own a clearnet domain, you may use that. You can also publish to a hidden .onion Tor website (Bivouac helps generate the configuration for you). Given how Phish identities work, it's okay for it to be on a random website.
Documents and folders may be configured to be behind HTTP basic authentication. Bivouac will help you generate configuration files to enforce it, and editors can be configured to enter the HTTP credentials when needed.
Servers should not block connections from Tor, as bivouac is configured to optionally download content via proxy (recommended). Bivouac is not meant to be directly peer-to- peer and instead recommends publishing content on public servers or via Tor.
Running in ActivityPub mode does require that you have a domain on the clearnet, with the bivouac editor itself receiving connections. This does expose it to more risk compared to the static file uploads model.
Webmention Introductions
Bivouac can discover new servers by reading peer's content, but others can also introduce their blog to yours.
This functionality requires the ability for you to read your server's logs. Some cheap static site hosts do not let you do this. It's similar to webmention, an indiweb standard for notifying a blog author that their page was linked to.
It's a base64 encoded bloat document, in a query string, introducing your Phish identity. It's then up to you to decide whether your blog should network with theirs.
The Editor
Edits (prior to uploading to a static site) are conducted via a server-side JS-free program for simplicity sake. A nicer editor (perhaps a native one) could be built with auto-complete and other features (like WYSIWYG).
In the current model, browsing documents in the editor can open up new tabs for complicated interactions. For example, delegating a vote might open up an HTML form with menus, buttons, and other information.
You may choose to self-host your editor and thus edit from http://localhost. You might also choose to keep it on a site behind a VPN for your users, or you might make a public site anybody can sign up to. Or, keep it on your own box, that also works.
Your private keys are stored on your editor (if you don't want a website to have your keys, run it on your laptop and then upload the results). Bivouac does not store the passwords to your Age or Minisign keys at rest, but does temporarily use them to do work on your behalf.
I would be fond of being able to use Age and Minisign keys in bivouac from hardware yubikeys (e.g. age-plugin-yubikey and minisign-fido).
Rendering
Documents in bivouac exist as XML, however wiki documents may use markdown inside text boxes, for human readable references. Bivouac tries to resolve any referenced handles (this is discussed more in Phish) - but can also create stub articles for you to finish in a new tab.
Bivouac also renders content to a public representation in static HTML. These HTML renderings present content from the perspective of the mirror host, in contrast to the XML documents which present things like petnames from their first-person author perspective.
The HTML documents can be extended through templates, and can link to ways for users to participate either on your groups' editor, or on their local laptop. Even without bivouac you can still browse the decisions being made (so long as they're addressed to a public Crew as an observer).
Carriers
A server that a Phish identity controls is called a "Carrier". These are, for example, personal blogs.
A special kind of carrier is a custodian, someone who has the responsibility of the group to maintain documents (where other people are off the hook). You are also the custodian of your own content. (this is different from a curator, which is discussed later in Decal)
Venues
A server someone is comfortable having their content mirrored on is called a "Venue". These could be group-run servers, or other friends.
Your direct friends and collaborators are probably okay with being venues for your blog content, but you can ask!
Mirroring
Messages, identities, groups and decisions can exist on many servers at once (just like torrented files).
If a person's venues or carriers go down, so long as they get back in touch with their buddies (with webmention or just on the grapevine), it's like they hardly left. This is in contrast to a mastodon server dying and taking identities with it. Just like those ants, home is where your friends are (this is more apparent in the next section on Phish).
Sites decide what content they mirror. A key difference between this and "free speech"- ish systems is that the encryption should not be blind to the site host. It's recommended that you not mirror that which you are not able to decrypt.