This repository has been archived on 2022-07-19. You can view files and clone it, but cannot push or open issues or pull requests.
dotplan-online/README.md

102 lines
5.0 KiB
Markdown
Raw Permalink Normal View History

# Dotplan
2020-07-16 20:48:53 -05:00
A modern, decentralized re-imagining of the Unix [plan](https://unix.stackexchange.com/questions/122782/what-is-plan-for-users) file.
2020-07-16 20:48:53 -05:00
- User-provided content tied to an email address.
- Text only.
2022-04-15 08:16:01 -05:00
- No re-tweets, shares, `@s`, likes, or boosting of any kind.
2021-06-20 18:58:49 -05:00
- Authenticity optionally verified by clients using [minisign](https://jedisct1.github.io/minisign/).
2020-07-16 20:48:53 -05:00
- Accessed via public APIs.
2020-07-16 23:55:59 -05:00
- Open source.
- Self-hostable, discovery via domain [SRV records](https://en.wikipedia.org/wiki/SRV_record).
2020-07-16 20:48:53 -05:00
## Client Implementations and Tools
2022-04-15 08:16:01 -05:00
- [dotplan-cli](https://code.sitosis.com/rudism/dotplan-cli) is a script for interacting with dotplan providers from the linux shell
2020-07-16 20:48:53 -05:00
## API
Any Dotplan implementation should expose at least the following endpoint and behavior:
2020-07-19 09:28:37 -05:00
- `GET /plan/{email}` - retrieve a plan
- `Accept: text/plain` request header - return raw plan content
- `Accept: application/json` request header - return json plan details:
2020-07-19 09:28:37 -05:00
- `plan` - raw plan content
- `timestamp` - when this plan was created
- `signature` - optional signature if this plan was signed
- `Last-Modified` response header should indicate when the plan was created
- `X-Dotplan-Pubkey: {base64 signify pubkey}` request header - perform signature verification
- append `X-Dotplan-Verified: true` response header if verification succeeded
- `403` if verification failed or is not supported by the server
- client-side signature verification using the json response should be favored since the server may not be trusted
2020-07-19 09:28:37 -05:00
- `404` if no plan found
- `301` redirect if domain SRV record indicates plan is on a different dotplan provider
- this is optional for servers to act as relays, client-side SRV lookups should be favored since the server may not be trusted
2020-07-19 09:28:37 -05:00
2020-07-16 23:55:59 -05:00
### Authentication
2020-07-19 09:28:37 -05:00
The reference dotplan implementation also exposes these endpoints for account management and authentication. Other implementations may differ and offer other authentication mechanisms (OAuth2 for example, or supporting the creation and invalidation of multiple authentication tokens).
2020-07-16 23:55:59 -05:00
- `POST /users/{email}` - request new account
2020-07-19 09:28:37 -05:00
- request json data:
- `password` - the password for the new account
- an email with a validation link will be sent
- `PUT /users/{email}` - validate new account
- request json data:
- `token` - the validation token from the email
2020-07-17 21:36:12 -05:00
- `GET /token` - retrieve auth token
2020-07-16 23:55:59 -05:00
- http basic auth
2020-07-17 21:36:12 -05:00
- `?expires={minutes}` sets an explicit expiration, default is 5 minutes from creation
2020-07-19 09:28:37 -05:00
- response json data:
- `token` - the authentication token
2020-07-17 21:36:12 -05:00
- `DELETE /token` - invalidate current auth token
2020-07-16 23:55:59 -05:00
- http basic auth
2020-07-19 09:28:37 -05:00
- `GET /users/{email}/pwchange` - get password change token
- an email with a password change token will be sent
2020-07-16 23:55:59 -05:00
- token expires 600 seconds from creation
2020-07-19 09:28:37 -05:00
- `PUT /users/{email}/pwchange` - update password
- request json data:
- `password` - the new password
- `token` - the password change token from the email
### Updating a Plan
2020-07-16 23:55:59 -05:00
2020-07-19 09:28:37 -05:00
The reference dotplan implementation exposes this endpoint to update a plan using a given authentication token. Other implementations may differ and offer other mechanisms to update a plan (by email or text message for example, or integration with other services).
2020-07-16 23:55:59 -05:00
- `PUT /plan/{email}` - update a plan
2020-07-19 09:28:37 -05:00
- request json data:
- `plan` - optional new plan content
- `signature` - optional ascii encoded PGP signature
- `auth` - the authentication token
2020-07-17 21:36:12 -05:00
- omitting `plan` from the payload will delete the existing plan
### Experimental
If experimental features are enabled in this reference implementation, `GET /js/{email}` with an optional `callback` parameter will return a [JSONP](https://en.wikipedia.org/wiki/JSONP) script that calls your function (`handle_dotplan` by default), passing the plan in json format. You can also optionally specify a `pubkey` parameter (if verification fails it will return an `{"error":"..."}` object).
## Discovery via Domain SRV
To facilitate service discovery by Dotplan clients and relays, add a [SRV record](https://en.wikipedia.org/wiki/SRV_record) to your email domain with the name `_dotplan._tcp`. For example, to use `dotplan.online` as the service provider for email addresses at `example.com`, the record would look like this:
```
_dotplan._tcp.example.com. 86400 IN SRV 0 1 443 dotplan.online.
```
## Docker Quick Run
```
git clone https://code.sitosis.com/rudism/dotplan-online.git
cd dotplan-online
cp data/msmtprc.example data/msmtprc
```
Edit the `Dockerfile` if you want to run as a user other than PID 1000, edit the `ENVIRONMENT` section of the `docker-compose.yaml` and make any other customizations for your setup, and edit the example provided `data/msmtprc` with your real SMTP server details (only used to send email verifications for new signups and password reset links).
```
cat schema.sql | sqlite3 data/users.db
docker-compose build
docker-compose up -d
```
You should now be able to make requests at `http://localhost:4227`, which is where you should point your reverse proxy for SSL configuration, etc.