documentation and email content updates

This commit is contained in:
Rudis Muiznieks 2021-06-20 18:20:35 -05:00
parent 554bbcec2e
commit 07715b00ca
4 changed files with 85 additions and 15 deletions

View File

@ -1,6 +1,6 @@
# Dotplan # 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. - User-provided content tied to an email address.
- Text only. - Text only.
@ -8,7 +8,7 @@
- Authenticity optionally verified by clients using OpenBSD signify/[Minisign](https://jedisct1.github.io/minisign/). - Authenticity optionally verified by clients using OpenBSD signify/[Minisign](https://jedisct1.github.io/minisign/).
- Accessed via public APIs. - Accessed via public APIs.
- Open source. - Open source.
- Self-hostable, discovery via domain SRV records. - Self-hostable, discovery via domain [SRV records](https://en.wikipedia.org/wiki/SRV_record).
## API ## API
@ -65,3 +65,11 @@ The reference dotplan implementation exposes this endpoint to update a plan usin
- `signature` - optional ascii encoded PGP signature - `signature` - optional ascii encoded PGP signature
- `auth` - the authentication token - `auth` - the authentication token
- omitting `plan` from the payload will delete the existing plan - 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.
```

View File

@ -293,8 +293,11 @@ EOF
die $sth->errstr if $sth->err; die $sth->errstr if $sth->err;
util_sendmail($cgi, $email, '[DOTPLAN] Verify your email', util_sendmail($cgi, $email, '[DOTPLAN] Verify your email',
"Please verify your email address.\n" . "Please verify your email address.\n" .
"Click the following link or copy it into your browser:\n" . "Your verification token is: $token\n" .
"https://$hostname/verify.html?token=$token"); "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}); print_json_response($cgi, 200, {email => $email});
} }
@ -377,8 +380,12 @@ EOF
util_sendmail($cgi, $email, '[DOTPLAN] Password reset request', util_sendmail($cgi, $email, '[DOTPLAN] Password reset request',
"Someone (hopefully you) has requested to change your password.\n" . "Someone (hopefully you) has requested to change your password.\n" .
"If it wasn't you, you can ignore and delete this email.\n\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" . "Your password change token is: $token\n\n" .
"https://$hostname/change-password.html?token=$token"); "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}); print_json_response($cgi, 200, {success => 1});
} }

View File

@ -9,13 +9,32 @@
<main> <main>
<h1>Dotplan Online</h1> <h1>Dotplan Online</h1>
<h2>What is Dotplan?</h2> <h2>What is Dotplan?</h2>
<p>Dotplan is a modern re-imagining of the <a href='https://unix.stackexchange.com/questions/122782/what-is-plan-for-users'>Plan</a> file from the days of yesteryear. Well, I mean technically it's still around today, but when was the last time you <code>finger</code>ed someone?</p> <p>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 <a href='https://unix.stackexchange.com/questions/122782/what-is-plan-for-users'>plan</a> file. It uses <a href='https://jedisct1.github.io/minisign/'>minisign</a> to verify authenticity.</p>
<p>On second thought, never mind. Don't answer that...</p>
<p>Essentially it's a loosey-goosey API specification through which the technically elite can express their personalities (or lack thereof) with one another.</p>
<h2>What is Dotplan Online?</h2> <h2>What is Dotplan Online?</h2>
<p>This site is a free Dotplan provider and relay running the <a href='https://github.com/rudism/dotplan-online'>Dotplan reference implementation</a>. If you're some kind of simpleton who is incapable of hosting your own, you can point your email domain here via a <code>SRV</code> record and use it as your Dotplan provider.</p> <p>This site is a free Dotplan provider and relay running the <a href='https://github.com/rudism/dotplan-online'>Dotplan reference implementation</a>. If you're incapable of hosting your own (or too lazy), you can point your email domain here via a <code>SRV</code> record and use it as your Dotplan provider.</p>
<h2>How does it all work?</h2> <h2>How does it work?</h2>
<p></p> <h3>Dotplan API</h3>
<p>Fetch the plan for <code>example@dotplan.online</code> as plain text:</p>
<pre><code> curl https://dotplan.online/example@dotplan.online</pre>
<p>Fetch the plan for <code>example@dotplan.online</code> as JSON:</p>
<pre><code> curl -H 'Accept: application/json' \
https://dotplan.online/example@dotplan.online</code></pre>
<p>See the <a href='https://github.com/rudism/dotplan-online'>GitHub</a> for more details, such as how to verify signed plans.</p>
<h3>Dotplan Online</h3>
<p>Register the email address <code>test@example.com</code> with password <code>my-password-123</code> (an email with further instructions will be sent):</p>
<pre><code> curl -H 'Content-Type: application/json' \
-XPUT -d '{"password":"my-password-123"}' \
https://dotplan.online/test@example.com</code></pre>
<p>Retrieve an authentication token for the account created above:</p>
<pre><code> curl -H 'Accept: application/json' \
-u 'test@example.com:my-password-123' \
https://dotplan.online/token</code></pre>
<p>Update the plan for <code>test@example.com</code> with the authentication token retrieved above:</p>
<pre><code> curl -H 'Content-Type: application/json' \
-XPUT -d '{"auth":"AUTH_TOKEN","plan":"This is my first plan!"}' \
https://dotplan.online/plan/test@example.com</code></pre>
<p>See the <a href='https://github.com/rudism/dotplan-online'>GitHub</a> for more details, such as how to sign plans for authenticity and how to support service discovery via domain <a href='https://en.wikipedia.org/wiki/SRV_record'>SRV records</a>.</p>
</main> </main>
<a href="https://github.com/rudism/dotplan-online" class="github-corner" aria-label="View source on GitHub"><svg width="80" height="80" viewBox="0 0 250 250" style="fill:#88b8f6; color:#151513; position: absolute; top: 0; border: 0; right: 0;" aria-hidden="true"><path d="M0,0 L115,115 L130,115 L142,142 L250,250 L250,0 Z"></path><path d="M128.3,109.0 C113.8,99.7 119.0,89.6 119.0,89.6 C122.0,82.7 120.5,78.6 120.5,78.6 C119.2,72.0 123.4,76.3 123.4,76.3 C127.3,80.9 125.5,87.3 125.5,87.3 C122.9,97.6 130.6,101.9 134.4,103.2" fill="currentColor" style="transform-origin: 130px 106px;" class="octo-arm"></path><path d="M115.0,115.0 C114.9,115.1 118.7,116.5 119.8,115.4 L133.7,101.6 C136.9,99.2 139.9,98.4 142.2,98.6 C133.8,88.0 127.5,74.4 143.8,58.0 C148.5,53.4 154.0,51.2 159.7,51.0 C160.3,49.4 163.2,43.6 171.4,40.1 C171.4,40.1 176.1,42.5 178.8,56.2 C183.1,58.6 187.2,61.8 190.9,65.4 C194.5,69.0 197.7,73.2 200.1,77.6 C213.8,80.2 216.3,84.9 216.3,84.9 C212.7,93.1 206.9,96.0 205.4,96.6 C205.1,102.4 203.0,107.8 198.3,112.5 C181.9,128.9 168.3,122.5 157.7,114.1 C157.9,116.9 156.7,120.9 152.7,124.9 L141.0,136.5 C139.8,137.7 141.6,141.9 141.8,141.8 Z" fill="currentColor" class="octo-body"></path></svg></a><style>.github-corner:hover .octo-arm{animation:octocat-wave 560ms ease-in-out}@keyframes octocat-wave{0%,100%{transform:rotate(0)}20%,60%{transform:rotate(-25deg)}40%,80%{transform:rotate(10deg)}}@media (max-width:500px){.github-corner:hover .octo-arm{animation:none}.github-corner .octo-arm{animation:octocat-wave 560ms ease-in-out}}</style>
</body> </body>
</html> </html>

View File

@ -50,8 +50,8 @@ table {
/* site styling */ /* site styling */
html, body { html, body {
font-size: 125%; font-size: 1.25em;
line-height: 130%; line-height: 1.5em;
font-family: monospace; font-family: monospace;
color: #e3e0d7; color: #e3e0d7;
background-color: #080808; background-color: #080808;
@ -68,16 +68,29 @@ p {
margin: 1em 0 0.5em 0; margin: 1em 0 0.5em 0;
} }
h1 { h1, h2, h3 {
font-weight: 900; font-weight: 900;
color: #cae982; color: #cae982;
margin: 1em 0 0.5em 0; margin: 1em 0 0.5em 0;
} }
h1 {
padding-bottom: 0.5em;
border-bottom: 2px dashed #cae982;
}
h1::before { h1::before {
content: '# '; content: '# ';
} }
h2::before {
content: '## ';
}
h3::before {
content: '### ';
}
a { a {
color: #88b8f6; color: #88b8f6;
text-decoration: underline; text-decoration: underline;
@ -88,3 +101,26 @@ a {
a:hover { a:hover {
color: #eadead; 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;
}