parsav  Check-in [0814075eff]

* **%**_rank_: matches users of *rank* or higher (e.g. `%3` matches users of rank 3, 2, and 1). as a special case, `%0` matches ordinary users
* **#**_room_**%**_rank_: matches users who hold *rank* in *room*
* **<**_title_**>**: matches peers of the net who have been created *title* by the sovereign
* **#**_room_**<**_title_**>**: matches peers of the chat who have been created *title* by *room* staff

to evaluate an ACL expression, `parsav` reads each term from start to finish. for each term, it considers whether it describes the user who is attempting to access the content. if the term matches, its policy is applied and the expression completes. if the term doesn't match, the server proceeds on to the next term and the process repeats until it finds a matching term or runs out of terms, applying the fallback policy.

**policy** is whether a term grants or denies access. the default term policy is **allow**, but you can control the policy with the keywords `allow` and `deny`. if a term finishes evaluating without any match being found, a fallback policy is applied; this fallback is the opposite of whatever the current policy is. this sounds confusing but makes ACL expressions much more intuitive; `allow @bob` and `deny trent` do exactly what you'd expect — the former allows bob and only bob in; the latter denies access only to trent, but grants access to the rest of the world.

expressions must contain at least one term to be valid. if they consist only of policy keywords, they will be rejected.

in effect, this all means that an ACL expression can be treated as a simple list of who is allowed to view your post. for instance, an expression of `local` means only local users can view it. however, much more complex expressions are possible.

* `deny groupies allow +illuminati`: permits access to the illuminati, but excluding those members who are groupies
* `+illuminati deny groupies`: allows access to everyone but groupies (unless they're in the illuminati)
* `@eve @alice@nowhere.tld deny @bob @trent@witches.live`: grants access to eve and alice, but locks out bob and trent
* `<grand duke> #4th-intl<comrade>`: restricts the post to the eyes of the Fourth International's secret cabal of anointed comrades and the grand dukes of the Empire
* `deny ~%3`: blocks a post from being seen by anyone with a staff rank level below 3

**limitations:** to inhibit potential denial-of-service attacks, ACL expressions can be a maximum of 256 characters, can contain at most 16 words, and cannot trigger queries against other servers. all information needed to evaluate an ACL expression must be known locally. this is particularly relevant with respect to rooms.

* **%**_rank_: matches users of *rank* or higher (e.g. `%3` matches users of rank 3, 2, and 1). as a special case, `%0` matches ordinary users
* **#**_room_**%**_rank_: matches users who hold *rank* in *room*
* **<**_title_**>**: matches peers of the net who have been created *title* by the sovereign
* **#**_room_**<**_title_**>**: matches peers of the chat who have been created *title* by *room* staff

to evaluate an ACL expression, `parsav` reads each term from start to finish. for each term, it considers whether it describes the user who is attempting to access the content. if the term matches, its policy is applied and the expression completes. if the term doesn't match, the server proceeds on to the next term and the process repeats until it finds a matching term or runs out of terms, applying the fallback policy.

**policy** is whether a term grants or denies access. the default term policy is **allow**, but you can control the policy with the keywords `allow` and `deny`. if a term finishes evaluating without any match being found, a fallback policy is applied; this fallback is the opposite of whatever the current policy is. this sounds confusing but makes ACL expressions much more intuitive; `allow @bob` and `deny @trent` do exactly what you'd expect — the former allows bob and only bob in; the latter denies access only to trent, but grants access to the rest of the world.

expressions must contain at least one term to be valid. if they consist only of policy keywords, they will be rejected.

in effect, this all means that an ACL expression can be treated as a simple list of who is allowed to view your post. for instance, an expression of `local` means only local users can view it. however, much more complex expressions are possible.

* `deny groupies allow +illuminati`: permits access to the illuminati, but excluding those members who are groupies
* `+illuminati deny groupies`: allows access to everyone but groupies (unless they're in the illuminati)
* `@eve @alice@nowhere.tld deny @bob @trent@witches.live`: grants access to eve and alice, but locks out bob and trent
* `<grand duke> #4th-intl<comrade>`: restricts the post to the eyes of the Fourth International's secret cabal of anointed comrades and the grand dukes of the Empire
* `deny ~%3`: blocks a post from being seen by anyone with a staff rank level below 3

**limitations:** to inhibit potential denial-of-service attacks, ACL expressions can be a maximum of 256 characters, can contain at most 16 words, and cannot trigger queries against other servers. all information needed to evaluate an ACL expression must be known locally. this is particularly relevant with respect to rooms.

# credentials & authentication

parsav features a highly flexibly authentication system, and provides alternatives to simple per-user passwords to help users keep their accounts secure. you can create as many credentials for you account as you wish, and tie them to specific IP addresses or regions. you can even restrict the capabilities of a given credential -- for instance, you could have one password that allows full access and one that only allows posting new tweets when logged in with it.

## mechanisms

you're not limited to passwords, however. parsav intends to support a very wide range of authentication mechanisms; this page lists all the mechanisms that have been implemented so far.

### password auth

................................................................................

of course, if you have a static IP address, you can get around some of the insecurity by setting a netmask on the password -- it won't do mongolian bitcoin scammers much good if only IPs from mecklenburg-vorpommern are allowed to use it. netmasks are however best used on VPNs, LANs, and similar arrangements where you have an absolute guarantee of a static IP address. for other circumstances, *challenge auth* may be a worthwhile means of improving your security.

### challenge auth

parsav also supports *challenge auth,* which is a form of authentication where are presented with a *challenge token* at login and have to provide with a response digest based on the token to authenticate yourself. this mechanism has the very useful property that the same digest can only be used for a very short period of time, after which they are permanently deactivated, giving you a bit of protection even if your HTTP session is exposed to a man-in-the-middle. due to the way they're implemented, they're effectively immune to shouldersurfing. challenge auth is generally based on cryptographic keys.

right now, the only form of challenge authentication supported is RSA asymmetric keypairs, though other methods based on elliptic curve cryptography and shared secrets are planned. an RSA keypair is a pair of very long numbers -- called the *public key* and the *private key* -- with special mathematical properties: anyone who holds the public key can encrypt data such that only the person with the private key can read it, and whoever holds the public key can place a digital signature on a piece of data such that anyone with the public key can confirm the data was endorsed by the holder of the private key. (private keys can of course be encrypted with a password; the advantage this has over normal passwords is that the password never leaves your computer's memory.) so when you log in with RSA challenge auth, you'll be given a short string to sign with your private key. all you have to do is paste the signature into the "digest" box and you'll be logged in.

keypairs are bit more complex to use than passwords, however. you have to use a special tool to create them. on linux and other unix-like systems, you can do this with the `openssl` command:

	$ openssl genrsa 2048 -out private.pem
	  # creates a reasonably secure 2048-bit private key

	$ openssl genrsa 4096 -out private.pem
	  # creates an *extremely secure 4096-bit key

	$ openssl genrsa 2048 -aes256 -out private.pem
	  # pass -aes256 to encrypt your key

once you've created your private key with a command like one of the above, you'll need to separate out a public key. if you used the `-aes256` flag, you'll be prompted for your password. (keep in mind, this password *cannot* be recovered if it is forgotten!)

	$ openssl rsa -in private.pem -pubout -out public.pem

`public.pem` is the file you'll want to copy and paste into the text box when you add this keypair as a credential to your parsav account. do *not* ever upload `private.pem` anywhere! if you ever do so by accident, delete the keypair credential from every account that uses it immediately, as you have irreversibly compromised their security.

finally, you'll need to use this key to actually sign things:

................................................................................
if you later want to change the password on your private key, you can use this command to do so:

    $ openssl rsa -in private.pem -aes256 -out private.pem
	  # omit the -aes256 to remove the encryption

## managing credentials

you can use the "security" panel in the configuration menu to manage your credentials. this panel has a wide range of options. firstly, if you suspect someone may have unwanted access to your account, you can press the "invalidate other sessions" button to instantly log out every computer but your own. of course, this will only briefly inconvenience evildoers if they have your password -- it's mainly useful for instances where you forgot to log out of a public computer, or one that belongs to someone else.

you can manage existing credentials with the "revoke" button, which wipes out a selected credential so it can no longer be used to log in (and logs out every device logged in under it!), or `reset`, which lets you change the credentials without affecting their privilege sets.

finally, you can create new credentials by picking the desired properties (what privileges and netmask they are restricted to, if any) and pressing the relevant button.

# credentials & authentication

parsav features a highly flexibly authentication system, and provides alternatives to simple per-user passwords to help users keep their accounts secure. you can create as many credentials for your account as you wish, and tie them to specific IP addresses or regions. you can even restrict the capabilities of a given credential -- for instance, you could have one password that allows full access and one that only allows posting new tweets when logged in with it.

## mechanisms

you're not limited to passwords, however. parsav intends to support a very wide range of authentication mechanisms; this page lists all the mechanisms that have been implemented so far.

### password auth

................................................................................

of course, if you have a static IP address, you can get around some of the insecurity by setting a netmask on the password -- it won't do mongolian bitcoin scammers much good if only IPs from mecklenburg-vorpommern are allowed to use it. netmasks are however best used on VPNs, LANs, and similar arrangements where you have an absolute guarantee of a static IP address. for other circumstances, *challenge auth* may be a worthwhile means of improving your security.

### challenge auth

parsav also supports *challenge auth,* which is a form of authentication where are presented with a *challenge token* at login and have to provide with a response digest based on the token to authenticate yourself. this mechanism has the very useful property that the same digest can only be used for a very short period of time, after which they are permanently deactivated, giving you a bit of protection even if your HTTP session is exposed to a man-in-the-middle. due to the way they're implemented, they're effectively immune to shouldersurfing. challenge auth is generally based on cryptographic keys.

right now, the only form of challenge authentication supported is RSA asymmetric keypairs, though other methods based on elliptic curve cryptography and shared secrets are planned. an RSA keypair is a pair of very long numbers -- called the *public key* and the *private key* -- with special mathematical properties: anyone who holds the public key can encrypt data such that only the person with the private key can read it, and whoever holds the private key can place a digital signature on a piece of data such that anyone with the public key can confirm the data was endorsed by the holder of the private key. (private keys can of course be encrypted with a password; the advantage this has over normal passwords is that the password never leaves your computer's memory.) so when you log in with RSA challenge auth, you'll be given a short string to sign with your private key. all you have to do is paste the signature into the "digest" box and you'll be logged in.

keypairs are bit more complex to use than passwords, however. you have to use a special tool to create them. on linux and other unix-like systems, you can do this with the `openssl` command:

	$ openssl genrsa 2048 -out private.pem
	  # creates a reasonably secure 2048-bit private key

	$ openssl genrsa 4096 -out private.pem
	  # creates an *extremely* secure 4096-bit key

	$ openssl genrsa 2048 -aes256 -out private.pem
	  # pass -aes256 to encrypt your key

once you've created your private key with a command like one of the above, you'll need to separate out a public key. if you used the `-aes256` flag, you'll be prompted for your password. (keep in mind, absent major progress in quantum computing, this password *cannot* be recovered if it is forgotten!)

	$ openssl rsa -in private.pem -pubout -out public.pem

`public.pem` is the file you'll want to copy and paste into the text box when you add this keypair as a credential to your parsav account. do *not* ever upload `private.pem` anywhere! if you ever do so by accident, delete the keypair credential from every account that uses it immediately, as you have irreversibly compromised their security.

finally, you'll need to use this key to actually sign things:

................................................................................
if you later want to change the password on your private key, you can use this command to do so:

    $ openssl rsa -in private.pem -aes256 -out private.pem
	  # omit the -aes256 to remove the encryption

## managing credentials

you can use the "security" panel in the configuration menu to manage your credentials. this panel has a wide range of options. firstly, if you suspect someone may have unwanted access to your account, you can press the "invalidate other sessions" button to instantly log out every computer but your own. of course, this will only briefly inconvenience evildoers if they hold a valid credential for your account -- it's mainly useful for instances where you forgot to log out of a public computer, or one that belongs to someone else.

you can manage existing credentials with the "revoke" button, which wipes out a selected credential so it can no longer be used to log in (and logs out every device logged in under it!), or `reset`, which lets you change the credentials without affecting their privilege sets.

finally, you can create new credentials by picking the desired properties (what privileges and netmask they are restricted to, if any) and pressing the relevant button.

powers can be granted and revoked through the online interface, in the `users` section. they can also be controlled using the command line tool, with the commands `parsav user <handle> grant <power>…` and `revoke <power>…` (`all` can be used instead of a list of powers to grant or strip all powers simultaneously)

### recommendations
on smaller servers, it is highly recommended that the `config`, `rebrand`, `purge`, `elevate`, and `demote` powers all rest with a single user. other administrators and moderators should be given `censor`, `discipline`, `vacate`, and possibly `invite` and `herald` depending on your intentions for the site. you should be the only rank-1 user, and other staff should be given rank 2. rank 3 might be useful to limit the damage new staff can do during a "probation period." `herald` and `crier` are useful powers to combine, as they create a "moderator" with powers related mostly to promotion of users and their work.

on larger servers, it may be necessary to have more levels of administrative abstraction, or even to increase the maximum number of ranks from its default of 10. in this case, certain exceptional powers such as `rebrand` and `purge` should still remain exclusively with the founder, but it may be necessary to (carefully!) apportion out access to powers like `elevate` and `demote`. it may also be desirable to have a broader class of less-trusted moderators who can take minimally destructive measures on their own (say, `censor` and `herald`) to filter through the bulk of reports, with a smaller corps of highly trusted commissars who have powers like `discipline` and `vacate` to handle the small number of reports that censors believe deserve their attention.

in both cases, it's very, very important to keep in mind that 99% of community management is social. parsav tries to provide you with effective tools for when use of force becomes unavoidable, but most of the time a good community leader can accomplish his goals with words alone (remember, IRC has none of this fancy shit, and they manage just fine most of the time!). apart from those relatively rare cases where you are faced with true bad-faith actors (in which cases immediate brutality is the only solution), a community can be handled effectively with just with judicious use of symbolic measures like rank, badges, and epithets. a gentle indication that a high-status user disapproves of her conduct is often all it takes to convince a lower-status user who truly cares about her community to shape up. all the power in the world won't give you a drop of authority, and if you're new to running communities, you may be surprised how much authority you can endow other members with without giving them anything besides maybe a fancy title (though even that is just a convenience) so long as the people in your community like, trust, and respect you.

and if your users don't respect you, you might as well pack up right now.

## emergencies
shit happens. sometimes this shit results in getting locked out of your own instance. if so, don't panic quite yet. as long as you can get shell access to the host to run the `parsav` utility, you can resolve the situation. (note that `parsavd` does not need to be running to use commands that control the database, and for some backends such as sqlite `parsavd` may need to be shut down first.)

### locked out
if you are locked out of your administrator account, the fix is simple, as long as you can modify the underlying database: the `parsav` utility does not use instance credentials, but rather directly modifies the DB and sends IPC signals through the kernel. if you're locked out because you've forgotten your password or all your credentials have been deleted somehow, just issue yourself a new temporary password like you would for any other user, with the `parsav user <handle> auth pw reset` command. 

### missing privileges
if you've been stripped of the `login` privilege by a bug or a rogue admin, you can restore it with `parsav user <handle> grant login`, and it may be worthwhile to issue a `revoke demote` to keep that rogue admin from immediately locking you out again. keep in mind that this won't affect sanctions that have been issued against your account; see below for these.

### sanctions
users with the `discipline` privilege cannot change user powers outright, but can issue sanctions that temporarily limit these powers in various ways, for instance preventing a user from posting for a few hours until they've cooled down. users with `discipline` can only affect users of lower rank unless they're rank 1, in which case they can affect all users. if you've fallen afoul of one of these users and need to get your instance back, you'll need to vacate all the sanctions against your account. this can be done with the `parsav actor <xid> sanction all vacate` command. alternately, you can list individual sanctions with `sanction`, and then delete them individually with `sanction <sid> vacate`.

### lost account
if your account has been completely deleted, rather than just suspended, things are decidedly more serious. everything associated with your account — posts, media, circles, relationships, all of it — is gone, irreversibly, unless you have a database backup around somewhere. (the `purge` power is so named because it is *serious business,* to be treated as the equivalent of a concealed carry permit — you should give it out to other users only out of specific justified need in exceptional circumstances, and revoke it proactively when it is no longer absolutely necessary, rather than as punishment for misuse. hopefully you have now learned this lesson.)

powers can be granted and revoked through the online interface, in the `users` section. they can also be controlled using the command line tool, with the commands `parsav user <handle> grant <power>…` and `revoke <power>…` (`all` can be used instead of a list of powers to grant or strip all powers simultaneously)

### recommendations
on smaller servers, it is highly recommended that the `config`, `rebrand`, `purge`, `elevate`, and `demote` powers all rest with a single user. other administrators and moderators should be given `censor`, `discipline`, `vacate`, and possibly `invite` and `herald` depending on your intentions for the site. you should be the only rank-1 user, and other staff should be given rank 2. rank 3 might be useful to limit the damage new staff can do during a "probation period." `herald` and `crier` are useful powers to combine, as they create a "moderator" with powers related mostly to promotion of users and their work.

on larger servers, it may be necessary to have more levels of administrative abstraction, or even to increase the maximum number of ranks from its default of 10. in this case, certain exceptional powers such as `rebrand` and `purge` should still remain exclusively with the founder, but it may be necessary to (carefully!) apportion out access to powers like `elevate` and `demote`. it may also be desirable to have a broader class of less-trusted moderators who can take minimally destructive measures on their own (say, `censor` and `herald`) to filter through the bulk of reports, with a smaller corps of highly trusted commissars who have powers like `discipline` and `vacate` to handle the small number of reports that censors believe deserve their attention.

in both cases, it's very, very important to keep in mind that 99% of community management is social. parsav tries to provide you with effective tools for when use of force becomes unavoidable, but most of the time a good community leader can accomplish his goals with words alone (remember, IRC has none of this fancy shit, and they manage just fine most of the time!). apart from those relatively rare cases where you are faced with true bad-faith actors (in which cases immediate and uncompromising brutality is the only solution), a community can be handled effectively with just with judicious use of symbolic measures like rank, badges, and epithets. a gentle indication that a high-status user disapproves of her conduct is often all it takes to convince a lower-status user who truly cares about her community to shape up. all the power in the world won't give you a drop of authority, and if you're new to running communities, you may be surprised how much authority you can endow other members with without giving them anything besides maybe a fancy title (though even that is just a convenience) so long as the people in your community like, trust, and respect you.

and if your users don't respect you, you might as well pack up right now.

## emergencies
shit happens. sometimes this shit results in getting locked out of your own instance. if so, don't panic quite yet. as long as you can get shell access to the host to run the `parsav` utility, you can resolve the situation. (note that `parsavd` does not need to be running to use commands that control the database, and for some backends `parsavd` may need to be shut down first.)

### locked out
if you are locked out of your administrator account, the fix is simple, as long as you can modify the underlying database: the `parsav` utility does not use instance credentials, but rather directly modifies the DB and sends IPC signals through the kernel. if you're locked out because you've forgotten your password or all your credentials have been deleted somehow, just issue yourself a new temporary password like you would for any other user, with the `parsav user <handle> auth pw reset` command. 

### missing privileges
if you've been stripped of the `login` privilege by a bug or a rogue admin, you can restore it with `parsav user <handle> grant login`, and it may be worthwhile to issue a `revoke demote` to keep that rogue admin from immediately locking you out again. keep in mind that this won't affect sanctions that have been issued against your account; see below for these.

### sanctions
users with the `discipline` privilege cannot change user powers outright, but can issue sanctions that temporarily limit these powers in various ways, for instance preventing a user from posting for a few hours until they've cooled down. users with `discipline` can only affect users of lower rank unless they're rank 1, in which case they can affect all users. if you've fallen afoul of one of these users and need to get your instance back, you'll need to vacate all the sanctions against your account. this can be done with the `parsav actor <xid> sanction all vacate` command. alternately, you can list individual sanctions with `sanction`, and then delete them individually with `sanction <sid> vacate`.

### lost account
if your account has been completely deleted, rather than just suspended, things are decidedly more serious. everything associated with your account — posts, media, circles, relationships, all of it — is gone, irreversibly, unless you have a database backup around somewhere. (the `purge` power is so named because it is *serious business,* to be treated as the equivalent of a concealed carry permit — you should give it out to other users only out of specific justified need in exceptional circumstances, and revoke it proactively when it is no longer absolutely necessary, rather than as punishment for misuse. hopefully you have now learned this lesson.)

* postgresql (backend `pgsql`)

## dependencies

* runtime
  * mongoose
  * json-c
  * mbedtls
  * **postgresql backend:**
     * postgresql-libs 
* compile-time
  * cmark (commonmark implementation), for transformation of the help files, whose source is in commonmark. online documentation transforms these into html and embeds them in the binary; cmark is also used to to produce the troff source which is used to build the offline documentation. disable with `parsav_online_documentation=no parsav_offline_documentation=no`
  * troff implementation (tested with groff but as far as i know we don't need any groff-specific extensions) to produce PDFs and manpages from the cmark-generated intermediate forms. disable with `parsav_offline_documentation=no`

* postgresql (backend `pgsql`)

## dependencies

* runtime
  * mongoose
  * mjson
  * mbedtls
  * **postgresql backend:**
     * postgresql-libs 
* compile-time
  * cmark (commonmark implementation), for transformation of the help files, whose source is in commonmark. online documentation transforms these into html and embeds them in the binary; cmark is also used to to produce the troff source which is used to build the offline documentation. disable with `parsav_online_documentation=no parsav_offline_documentation=no`
  * troff implementation (tested with groff but as far as i know we don't need any groff-specific extensions) to produce PDFs and manpages from the cmark-generated intermediate forms. disable with `parsav_offline_documentation=no`