From 07715b00caa891bda098b9002d96fceb46a4b34c Mon Sep 17 00:00:00 2001 From: Rudis Muiznieks Date: Sun, 20 Jun 2021 18:20:35 -0500 Subject: [PATCH] documentation and email content updates --- README.md | 12 ++++++++++-- server.pl | 15 +++++++++++---- static/index.html | 31 +++++++++++++++++++++++++------ static/style.css | 42 +++++++++++++++++++++++++++++++++++++++--- 4 files changed, 85 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 2547e11..8a143fa 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Dotplan -## The un-social network. +A modern, decentralized re-imagining of the Unix [plan](https://unix.stackexchange.com/questions/122782/what-is-plan-for-users) file. - User-provided content tied to an email address. - Text only. @@ -8,7 +8,7 @@ - Authenticity optionally verified by clients using OpenBSD signify/[Minisign](https://jedisct1.github.io/minisign/). - Accessed via public APIs. - Open source. -- Self-hostable, discovery via domain SRV records. +- Self-hostable, discovery via domain [SRV records](https://en.wikipedia.org/wiki/SRV_record). ## API @@ -65,3 +65,11 @@ The reference dotplan implementation exposes this endpoint to update a plan usin - `signature` - optional ascii encoded PGP signature - `auth` - the authentication token - omitting `plan` from the payload will delete the existing plan + +## 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. +``` diff --git a/server.pl b/server.pl index f512254..452f3c5 100644 --- a/server.pl +++ b/server.pl @@ -293,8 +293,11 @@ EOF die $sth->errstr if $sth->err; util_sendmail($cgi, $email, '[DOTPLAN] Verify your email', "Please verify your email address.\n" . - "Click the following link or copy it into your browser:\n" . - "https://$hostname/verify.html?token=$token"); + "Your verification token is: $token\n" . + "Run this (or equivalent) in a terminal:\n\n" . + " curl -H 'Content-Type: application/json' \\\n" . + " -XPUT -d '{\"token\",\"$token\"}' \\\n" . + " https://$hostname/users/$email"); print_json_response($cgi, 200, {email => $email}); } @@ -377,8 +380,12 @@ EOF util_sendmail($cgi, $email, '[DOTPLAN] Password reset request', "Someone (hopefully you) has requested to change your password.\n" . "If it wasn't you, you can ignore and delete this email.\n\n" . - "Otherwise, click the following link or copy it into your browser:\n" . - "https://$hostname/change-password.html?token=$token"); + "Your password change token is: $token\n\n" . + "Run this (or equivalent) in a terminal after adding your desired\n" . + "password to the appropriate field in the JSON payload:\n\n" . + " curl -H 'Content-Type: application/json' \\\n" . + " -XPUT -d '{\"password\":\"\",\"token\",\"$token\"}' \\\n" . + " https://$hostname/users/$email/pwchange"); print_json_response($cgi, 200, {success => 1}); } diff --git a/static/index.html b/static/index.html index 4c5542d..3ef6ff9 100644 --- a/static/index.html +++ b/static/index.html @@ -9,13 +9,32 @@

Dotplan Online

What is Dotplan?

-

Dotplan is a modern re-imagining of the Plan file from the days of yesteryear. Well, I mean technically it's still around today, but when was the last time you fingered someone?

-

On second thought, never mind. Don't answer that...

-

Essentially it's a loosey-goosey API specification through which the technically elite can express their personalities (or lack thereof) with one another.

+

Dotplan is an API specification through which the technically capable can express their personalities (or lack thereof) with one another. A modern, decentralized re-imagining of the Unix plan file. It uses minisign to verify authenticity.

What is Dotplan Online?

-

This site is a free Dotplan provider and relay running the Dotplan reference implementation. If you're some kind of simpleton who is incapable of hosting your own, you can point your email domain here via a SRV record and use it as your Dotplan provider.

-

How does it all work?

-

+

This site is a free Dotplan provider and relay running the Dotplan reference implementation. If you're incapable of hosting your own (or too lazy), you can point your email domain here via a SRV record and use it as your Dotplan provider.

+

How does it work?

+

Dotplan API

+

Fetch the plan for example@dotplan.online as plain text:

+ 
    curl https://dotplan.online/example@dotplan.online
+

Fetch the plan for example@dotplan.online as JSON:

+ 
    curl -H 'Accept: application/json' \
+      https://dotplan.online/example@dotplan.online
+

See the GitHub for more details, such as how to verify signed plans.

+

Dotplan Online

+

Register the email address test@example.com with password my-password-123 (an email with further instructions will be sent):

+ 
    curl -H 'Content-Type: application/json' \
+      -XPUT -d '{"password":"my-password-123"}' \
+      https://dotplan.online/test@example.com
+

Retrieve an authentication token for the account created above:

+ 
    curl -H 'Accept: application/json' \
+      -u 'test@example.com:my-password-123' \
+      https://dotplan.online/token
+

Update the plan for test@example.com with the authentication token retrieved above:

+ 
    curl -H 'Content-Type: application/json' \
+      -XPUT -d '{"auth":"AUTH_TOKEN","plan":"This is my first plan!"}' \
+      https://dotplan.online/plan/test@example.com
+

See the GitHub for more details, such as how to sign plans for authenticity and how to support service discovery via domain SRV records.

+ diff --git a/static/style.css b/static/style.css index c3d0b65..1fbdc5d 100644 --- a/static/style.css +++ b/static/style.css @@ -50,8 +50,8 @@ table { /* site styling */ html, body { - font-size: 125%; - line-height: 130%; + font-size: 1.25em; + line-height: 1.5em; font-family: monospace; color: #e3e0d7; background-color: #080808; @@ -68,16 +68,29 @@ p { margin: 1em 0 0.5em 0; } -h1 { +h1, h2, h3 { font-weight: 900; color: #cae982; margin: 1em 0 0.5em 0; } +h1 { + padding-bottom: 0.5em; + border-bottom: 2px dashed #cae982; +} + h1::before { content: '# '; } +h2::before { + content: '## '; +} + +h3::before { + content: '### '; +} + a { color: #88b8f6; text-decoration: underline; @@ -88,3 +101,26 @@ a { a:hover { color: #eadead; } + +pre { + overflow-x: auto; +} + +p > code { + color: #e5786d; +} + +p > code::before, p > code::after { + content: "`"; +} + +pre > code { + color: #eadead; +} + +hr { + margin: 1em 0 0.5em 0; + border: 0; + height: 0; + border-bottom: 2px dashed #88b8f6; +}