Functional Specifications

Part of General Document Zone (v0.1.0) last public on August 5, 2023 at 12:00 AM UTC. You may see previous version(s) of the zone.

These are collection of statements of formalized requirements. Each item may have multiple statements. The items may build introduce some jargon for the efficiency of communication between the developers.

Prerequisites

Readers are assumed to have the ability to create REST APIs to perform CRUD operations.

Specification Categories

Entity Specifications

This section specifies that attributes of every entity in the system. It also builds a vocabulary that is useful to understand other sections and different parts of the documentation.

  1. A user may have a multiple accounts on every target platform.
  2. Each target platform has zero or more credentials.
  3. A credential makeup an account on the target platform.
  4. A credential can be authenticated:
    • By same target platform (intraplatform authentication)
    • Through to other platforms (interplatform authentication).
  5. Intraplatform credentials must have:
    • Identifier (email, username, or other unique identifier)
    • Associated password for the identifier
    • Optional extra data.
  6. Interplatform credentials must have:
    • Delegating platform name
    • Delegating identifier
    • Optional extra data.
  7. Only password is encrypted by the server among other attributes of intraplatform credential.

Client Specifications

This section specifies the capabilities of clients in order to manage credentials.

  1. It must follow the REST API specification.
  2. At initial load, the client should check for stored server URL.
  3. If there are no stored server URL, the client should ask for the URL and store it.
  4. Once a server URL is present, the client should check if the server is available by asking for a CSRF token.
  5. If the server is available, the following steps must be done.
    • CSRF token responded by the server will be treated as guest CSRF token. This should be used to register or login.
    • Client should be able to show log in form and/or registration form, at the same page or on different pages.
  6. Should a user has been registered by the client, the access token would be included in registration response. Client should ask again for new CSRF token which would be treated as authenticated CSRF token. User is automatically logged in after registration.
  7. Should a user has been logged in by the client, the access token would be included in log in response. Client should ask again for new CSRF token which would be treated as authenticated CSRF token too.
  8. Should a user has been logged out by the client, the CSRF token from log out response would be treated as guest CSRF token. Access token should also be sent in Authorization header as Bearer token. For example, Authorization: Bearer <access token>.
  9. Client may show a list available platforms created by the user on previous sessions. Client must be able to handle CRUD operations for platforms.
  10. Client may show a list of available credentials for a given platform upon request. Client must be able to handle CRUD operations for intraplatform credentials and interplatform credentials.
  11. Client may only show a decrypted password of an intraplatform credential if requested one at a time. It must never show decrypted passwords if the user requested for a list.

Server Specifications

This section specifies the capabilities of servers in order to manage credentials.

  1. It must follow the REST API specification.
  2. Storing password of intraplatform credentials must be encrypted using the password (of currently logged-in user) as key
  3. Guest users and users who just logged out must be given a CSRF token treated as guest CSRF token.
  4. Newly-registered users and logged in should be given a CSRF token treated as authenticated CSRF token.
  5. CSRF token must be regenerated every time a user enters or exits from the authenticated state.

Notes

Should there be changes in one of the categories, REST API specification may be affected.

Origin

Some contents of this document came from the server variant A’s blueprint.

Previous versions

There are no previous versions yet. Check back in the future.