Concorde

Appearance

@shutter-network/concorde/password-auth ​

The HTTP routes this component serves: 4 on the Public server.

Every path is relative. Each one is printed as the plugin declares it, under whatever prefix the component's constructor registers that plugin at. This page states no mount point, because the constructor is where the mount point is decided.

Generated from what the route plugins in src/password-auth/routes.ts declare, which is what a running Gateway serves at GET /openapi.json. Never edited by hand.

Public server ​

The Public server is what a User's client calls. Which credential each route wants, and which wants none, is in that route's own description below.

PUT /password ​

Replace the authenticated User's password

A User rotating their own credential by proving they hold the current one. There is no user field: the User is the one the Gateway authenticated. So no request can change another User's password, and there is no check to get wrong. There is no recovery path either. Proving identity without the credential is what this framework declined to build. A forgotten password is replaced by the Operator's own trusted code, or not at all.

A User who holds no password cannot get one here, having nothing to prove, and is refused with the same 401 a wrong one gets. A changed password revokes nothing: a User who changed theirs out of fear is served by DELETE /auth/tokens, which is one request away. Requires a bearer Token, presented as Authorization: Bearer <token> and obtained from POST /auth/tokens. The User acted on is the one the Gateway authenticated, and no parameter anywhere names another. These routes take no query parameters at all. A credential travels in the body or in the Authorization header, never in a URL. An unknown query parameter is a 400, not a filter that did nothing and a request answered with everything.

Tagged Authentication.

Request body

application/json, required.

  • currentPassword string, required, 1 to 1024 characters
  • newPassword string, required, 1 to 1024 characters

Responses

204 with no body

The password is replaced. Every Token issued before it, the presented one included, still works.

400 application/json

A password is missing, empty or longer than 1024 characters, or a query parameter was written. A user field in the body is not refused: it is stripped before the handler and reaches nothing.

  • statusCode integer, required
  • error string, required
  • message string, required

401 application/json

Authentication failed, which is the whole of what is said: a wrong password, an id nobody holds, a User with no password, and a Token that is missing, malformed, unknown or expired are one status and one message, so nothing here answers who exists.

  • statusCode integer, required
  • error string, required
  • message string, required

DELETE /tokens ​

Revoke every Token of the authenticated User

The answer to "I think I have been compromised", and the only one there is. Nothing removes a User, so every credential of this scheme that stops working before it expires stops working here. Every Token of the authenticated User goes, including the one presented, so the caller is logged out too. It is the only compaction a User has over their own row count, because nothing reaps an expired Token.

It drops no password and no credential of any other scheme, so a User who is also reached another way keeps that way. Requires a bearer Token, presented as Authorization: Bearer <token> and obtained from POST /auth/tokens. The User acted on is the one the Gateway authenticated, and no parameter anywhere names another. These routes take no query parameters at all. A credential travels in the body or in the Authorization header, never in a URL. An unknown query parameter is a 400, not a filter that did nothing and a request answered with everything.

Tagged Authentication.

Responses

204 with no body

Every Token that User held, including the presented one, has stopped working.

400 application/json

A query parameter was written, and these routes take none.

  • statusCode integer, required
  • error string, required
  • message string, required

401 application/json

Authentication failed, which is the whole of what is said: a wrong password, an id nobody holds, a User with no password, and a Token that is missing, malformed, unknown or expired are one status and one message, so nothing here answers who exists.

  • statusCode integer, required
  • error string, required
  • message string, required

POST /tokens ​

Trade a password for a Token

A User's own opaque id and their password, for a bearer Token to present on everything else. This response is the only place the Token's plaintext ever exists. It is stored as a digest and cannot be read back. A client that loses it logs in again rather than recovering it.

This is the one route here that requires no Token, and the one a client calls first. These routes take no query parameters at all. A credential travels in the body or in the Authorization header, never in a URL. An unknown query parameter is a 400, not a filter that did nothing and a request answered with everything.

Tagged Authentication.

Request body

application/json, required.

  • user string, required, matching ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
  • password string, required, 1 to 1024 characters

Responses

201 application/json

The Token, when it stops working, and the User it belongs to, so that a client needs no second request to know who it is.

  • token string, required

  • expiresAt string, required

    When the Token stops working, ISO 8601. Always present: a Token that never expires is unrepresentable, and the lifetime is the Gateway's rather than the client's to choose. Nothing renews a Token and nothing reaps an expired one: it simply stops being accepted, and a client past this time logs in again.

  • user object, required

    • id string, required

    • attributes any JSON, required

      Arbitrary JSON, defined by the deployment and interpreted by nothing in the Gateway. This is where grouping and therefore authorization live. Nothing on this surface can write them: a password names a User who already exists.

    • createdAt string, required

400 application/json

The user is not a uuid, or the password is missing, empty or longer than 1024 characters. A well-formed id nobody holds is a 401 and not a 400, since a 400 would answer who exists.

  • statusCode integer, required
  • error string, required
  • message string, required

401 application/json

Authentication failed, which is the whole of what is said: a wrong password, an id nobody holds, a User with no password, and a Token that is missing, malformed, unknown or expired are one status and one message, so nothing here answers who exists.

  • statusCode integer, required
  • error string, required
  • message string, required

DELETE /tokens/current ​

Revoke the presented Token

Logging out. The presented Token stops working, and no other Token of this User's does. So a Token on a device they no longer trust is droppable from a device they still use. Idempotent: the row is gone afterwards, whether or not this call removed it.

It acts on the Token in the Authorization header and on nothing else, so a request the Gateway authenticated by some other scheme answers 204 and drops nothing. Requires a bearer Token, presented as Authorization: Bearer <token> and obtained from POST /auth/tokens. The User acted on is the one the Gateway authenticated, and no parameter anywhere names another. These routes take no query parameters at all. A credential travels in the body or in the Authorization header, never in a URL. An unknown query parameter is a 400, not a filter that did nothing and a request answered with everything.

Tagged Authentication.

Responses

204 with no body

The Token no longer works. Nothing is answered, including how many Tokens there were: a count is a number about Tokens the caller does not hold.

400 application/json

A query parameter was written, and these routes take none.

  • statusCode integer, required
  • error string, required
  • message string, required

401 application/json

Authentication failed, which is the whole of what is said: a wrong password, an id nobody holds, a User with no password, and a Token that is missing, malformed, unknown or expired are one status and one message, so nothing here answers who exists.

  • statusCode integer, required
  • error string, required
  • message string, required