antagonismorg/tahoe-lafs — comment on commit 903e33711e351a923d9d771f5a7016d8cb53ebf4
File:  line 0
By warner:

Nice!

We should probably add a leading paragraph explaining what this whole thing
is about. And we should explain how to format the inbound data (using
multipart/form-data is not the most obvious of encoding schemes). Also, the
"will send the credentials, email address and password" phrasing makes it
sound like there are "credentials" that are separate from the password. So
maybe something like this?:

```
The accounts.url directive allows access requests to be controlled by an
HTTP-based login service, useful for centralized deployments. This was
used by AllMyData to provide web-based file access, where the service
used a simple PHP script and database lookups to map an account email
address and password into a tahoe rootcap. The service will receive a
multipart/form-data POST, just like one created with a

and
fields, with three parameters:

* action: "authenticate" (this is a static string, for backwards
compatibility with the old AllMyData authentication service)
* email: USERNAME (Tahoe has no notion of email addresses, but the
authentication service uses them as account names, so the interface
presents this argument as "email" rather than "username").
* passwd: PASSWORD

And should return a single string that either contains a Tahoe rootcap
(URI:DIR2:...), or "0" to indicate a login failure.
```

Also, where the second paragraph says things like "the server will return"..
this document is explaining what Tahoe does when it sees `accounts.url`, so
it can make strong claims about what Tahoe does, but merely describes
hopes/expectations/requirements about how the server needs to operate to be
compatible. So I'd lean towards verbs like "the server is expected to return
a rootcap string", or "the server must return". The server's actual behavior
is out of Tahoe's control, and "the server will return" subtly implies that
this server is part of Tahoe, which is confusing at first glance.