Remove unused response bodies from a number of API endpoints.

This removes the response body from the following methods:

* `POST /api/setup`
* `POST /api/auth/login`
* `POST /api/invite/:id`
* `POST /api/password`

The bodies returned from these methods were something of a rough guess as to what might be useful. Actual client development has shown that we don't use _any_ of the data from any of these API responses, so let's not tie ourselves to future compatibility by continuing to send them. We can add a body to a bodyless method a _lot_ more easily than we can change the body of a method that already returns one, after all.

These changes are not backwards compatible for clients which care about the existing bodies. To my knowledge, there are no such clients; the included client definitely doesn't care.

## Internals

Not only does this change stop returning bodies at the API surface, but it also stops retrieving and returning values used internally to construct those responses, simplifying the code a bit in the process.

One side effect of this is that tests that need to log in a user now need to manually verify the returned token secret, to convert it back into a user, whereas the previous versions returned both a token secret and a user during password login. I don't love the increase in the size of the tests, but I think it's the right tradeoff (and this change is code net-negative anyways).

Merges no-content into main.

3 files changed, 21 insertions, 98 deletions

diff --git a/docs/api/authentication.md b/docs/api/authentication.md
index fbd5959..189103e 100644
--- a/docs/api/authentication.md
+++ b/docs/api/authentication.md
@@ -71,32 +71,15 @@ The request must have the following fields:
 
 <!-- This prose is duplicated by 03-initial-setup.md and in 04-invitations.md, with small changes for context. If you edit it here, edit it there, too. -->
 
-This endpoint will respond with a status of
-`200 Okay` when successful. The body of the response will be a JSON object describing the authenticated user:
-
-```json
-{
-  "id": "Uabcd1234",
-  "name": "Andrea"
-}
-```
-
-The response will include the following fields:
-
-| Field  | Type   | Description                    |
-| :----- | :----- | :----------------------------- |
-| `id`   | string | The authenticated user's ID.   |
-| `name` | string | The authenticated user's name. |
+This endpoint will respond with a status of `204 No Content` when successful.
 
-The response will include a `Set-Cookie` header for the
-`identity` cookie, providing the client with a newly-minted identity token associated with the user identified in the request. This token's value must be kept confidential.
+The response will include a `Set-Cookie` header for the `identity` cookie, providing the client with a newly-minted identity token associated with the user identified in the request. This token's value must be kept confidential.
 
 The cookie will expire if it is not used regularly.
 
 ### Authentication failure
 
-This endpoint will respond with a status of
-`401 Unauthorized` if the login name and password do not correspond to an existing user.
+This endpoint will respond with a status of `401 Unauthorized` if the login name and password do not correspond to an existing user.
 
 ## `POST /api/auth/logout`
 
@@ -114,13 +97,16 @@ The request must be an empty JSON object.
 
 This endpoint will respond with a status of `204 No Content` when successful.
 
-The response will include a `Set-Cookie` header that clears the
-`identity` cookie. Regardless of whether the client clears the cookie, the service also invalidates the token.
+The response will include a `Set-Cookie` header that clears the `identity` cookie. Regardless of whether the client clears the cookie, the service also invalidates the token.
 
 ## `POST /api/password`
 
 Changes the current user's password, and invalidates all outstanding identity tokens.
 
+### Authentication failure
+
+This endpoint will respond with a status of `401 Unauthorized` if the provided identity token is not valid.
+
 ### Request
 
 ```json
@@ -139,29 +125,12 @@ The request must have the following fields:
 
 ### Success
 
-This endpoint will respond with a status of
-`200 Okay` when successful. The body of the response will be a JSON object describing the authenticated user:
-
-```json
-{
-  "id": "Uabcd1234",
-  "name": "Andrea"
-}
-```
-
-The response will include the following fields:
-
-| Field  | Type   | Description                    |
-| :----- | :----- | :----------------------------- |
-| `id`   | string | The authenticated user's ID.   |
-| `name` | string | The authenticated user's name. |
+This endpoint will respond with a status of `204 No Content` when successful.
 
-The response will include a `Set-Cookie` header for the
-`identity` cookie, providing the client with a newly-minted identity token associated with the login identified in the request. This token's value must be kept confidential. All previously-created identity cookies will cease to be valid.
+The response will include a `Set-Cookie` header for the `identity` cookie, providing the client with a newly-minted identity token associated with the login identified in the request. This token's value must be kept confidential. All previously-created identity cookies will cease to be valid.
 
 The cookie will expire if it is not used regularly.
 
 ### Authentication failure
 
-This endpoint will respond with a status of `400 Bad Request` if the
-`password` does not match the login's current password.
+This endpoint will respond with a status of `400 Bad Request` if the `password` does not match the login's current password.
diff --git a/docs/api/initial-setup.md b/docs/api/initial-setup.md
index a3f6506..b52771f 100644
--- a/docs/api/initial-setup.md
+++ b/docs/api/initial-setup.md
@@ -17,8 +17,7 @@ New instances of this service require an initial setup step before they can full
 
 ## Requests before setup completed
 
-Before the service is set up, all API endpoints, other than those specifically documented as exceptions, will return a status of
-`503 Service Unavailable` to all requests.
+Before the service is set up, all API endpoints, other than those specifically documented as exceptions, will return a status of `503 Service Unavailable` to all requests.
 
 Initial setup can be completed only once.
 
@@ -64,29 +63,9 @@ The proposed `name` must be valid. The precise definition of valid is still up i
 
 <!-- This prose is duplicated from authentication.md, with small changes for context. If you edit it here, edit it there, too. -->
 
-This endpoint will respond with a status of
-`200 Okay` when successful. The body of the response will be a JSON object describing the newly-created user:
+This endpoint will respond with a status of `204 No Content` when successful.
 
-```json
-{
-  "id": "Uabcd1234",
-  "name": "Andrea"
-}
-```
-
-The response will include the following fields:
-
-| Field  | Type   | Description                                                                                                                                        |
-| :----- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `id`   | string | A unique identifier for the newly-created user. This can be used to associate the user with other events, or to make API calls targeting the user. |
-| `name` | string | The user's name.                                                                                                                                   |
-
-The returned name may not be identical to the name requested, as the name will be converted to [normalization form C](http://www.unicode.org/reports/tr15/) automatically. The returned name will include this normalization; the service will use the normalized name elsewhere, and does not store the originally requested name.
-
-The provided password will also be converted to normalization form C. However, the normalized password is not returned to the client.
-
-The response will include a `Set-Cookie` header for the
-`identity` cookie, providing the client with a newly-minted identity token associated with the initial user created for this request. See the [authentication](./authentication) section for details on how this cookie may be used.
+The response will include a `Set-Cookie` header for the `identity` cookie, providing the client with a newly-minted identity token associated with the initial user created for this request. See the [authentication](./authentication) section for details on how this cookie may be used.
 
 The cookie will expire if it is not used regularly.
 
diff --git a/docs/api/invitations.md b/docs/api/invitations.md
index 04e92c8..9b86b9e 100644
--- a/docs/api/invitations.md
+++ b/docs/api/invitations.md
@@ -39,8 +39,7 @@ The request must be an empty JSON object.
 
 ### Success
 
-This endpoint will respond with a status of
-`200 Okay` when successful. The body of the response will be a JSON object describing the new invitation:
+This endpoint will respond with a status of `200 Okay` when successful. The body of the response will be a JSON object describing the new invitation:
 
 ```json
 {
@@ -58,8 +57,7 @@ The response will include the following fields:
 | `issuer`    | string | The user ID of the invitation's issuer.                                       |
 | `issued_at` | string | The timestamp from which the invitation will expire.                          |
 
-Clients and their operators are responsible for delivering the invitation to the invitee. Clients are strongly recommended to construct a URL for the invitation so that the invitee can take action on it easily. The included client supports URLs of the format
-`https://example.net/invite/:id` (with the `:id` placeholder substituted with the invitation's ID).
+Clients and their operators are responsible for delivering the invitation to the invitee. Clients are strongly recommended to construct a URL for the invitation so that the invitee can take action on it easily. The included client supports URLs of the format `https://example.net/invite/:id` (with the `:id` placeholder substituted with the invitation's ID).
 
 ## `GET /api/invite/:id`
 
@@ -75,8 +73,7 @@ This endpoint requires the following path parameter:
 
 ### On success
 
-This endpoint will respond with a status of
-`200 Okay` when successful. The body of the response will be a JSON object describing the invitation:
+This endpoint will respond with a status of `200 Okay` when successful. The body of the response will be a JSON object describing the invitation:
 
 ```json
 {
@@ -96,13 +93,11 @@ The response will include the following fields:
 | `issuer`    | string | The name of the invitation's issuer.                 |
 | `issued_at` | string | The timestamp from which the invitation will expire. |
 
-Clients should present the
-`issuer` to the user when presenting an invitation, so as to personalize the invitation and help them understand their connection with the service.
+Clients should present the `issuer` to the user when presenting an invitation, so as to personalize the invitation and help them understand their connection with the service.
 
 ### Invitation not found
 
-This endpoint will respond with a status of
-`404 Not Found` when the invitation ID either does not exist, or has already been accepted.
+This endpoint will respond with a status of `404 Not Found` when the invitation ID either does not exist, or has already been accepted.
 
 ## `POST /api/invite/:id`
 
@@ -146,29 +141,9 @@ The proposed `name` must be valid. The precise definition of valid is still up i
 
 <!-- This prose is duplicated from authentication.md, with small changes for context. If you edit it here, edit it there, too. -->
 
-This endpoint will respond with a status of
-`200 Okay` when successful. The body of the response will be a JSON object describing the newly-created user:
-
-```json
-{
-  "id": "Uabcd1234",
-  "name": "Andrea"
-}
-```
-
-The response will include the following fields:
-
-| Field  | Type   | Description                                                                                                                                        |
-| :----- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `id`   | string | A unique identifier for the newly-created user. This can be used to associate the user with other events, or to make API calls targeting the user. |
-| `name` | string | The user's name.                                                                                                                                   |
-
-The returned name may not be identical to the name requested, as the name will be converted to [normalization form C](http://www.unicode.org/reports/tr15/) automatically. The returned name will include this normalization; the service will use the normalized name elsewhere, and does not store the originally requested name.
-
-The provided password will also be converted to normalization form C. However, the normalized password is not returned to the client.
+This endpoint will respond with a status of `204 No Content` when successful.
 
-The response will include a `Set-Cookie` header for the
-`identity` cookie, providing the client with a newly-minted identity token associated with the login created for this request. See the [authentication](./authentication.md) section for details on how this cookie may be used.
+The response will include a `Set-Cookie` header for the `identity` cookie, providing the client with a newly-minted identity token associated with the login created for this request. See the [authentication](./authentication.md) section for details on how this cookie may be used.
 
 The cookie will expire if it is not used regularly.