@cubos/auth Module

About   |   Features   |   Usage   |   Endpoints   |   SignIn Explanation   |   Technologies   |  

🎯 About

Module to be used as authentication library

✨ Features

• Password authentication
• SignIn (SCRAM) & (PLAIN)
• Create and maintain session

❔ Usage

const realm = {
  name: "realm_name"
  authMethods: {
    type: "password",
    minLength: 3,
    maxLength: 15,
    checkPwned: true
  },
  session: {
    idleTimeout: 2592000,
    timeout: 2592000
  }
}

const configInstance = new ConfigClass([realm])
AuthModuleConfig.init(configInstance)

const authService = container.resolver(Auth)

✅ Endpoints

• signUpWithPassword

1. Validates the auth method configuration will be used in authentication process
2. Validates the password
3. Save user credentials
4. Create user with corresponding entity configuration
5. Return user

• signInWithPasswordPlain

  PLAIN As the name already says, a simple way to create session with less rules of cryptography

1. Verify if user exist by realm and username
2. Get the encrypt options that will be used to hash the password
3. Generate hashed password
4. Validates if password is compatible
5. Create session

• signInWithPasswordScram

  SCRAM Salted Challenge Response Authentication Mechanism its a family of mechanisms to ensure password security, uses series of validations client-server to grant authentication

1. Verify if user exist by realm and username
2. Creates temporary sign in
   • If user don't exist return false credentials
3. Get the auth credentials
4. Return the credentials

• signInWithPasswordScramContinue

1. Check if temporary sign in is valid
2. Validates client proof
3. Creates session
4. Return server proof and token

• recoverSession

1. Validates token
2. Get session
3. Validates session timeout
4. Validates session idle timeout
5. Return session

• updatePassword

1. Fin user
2. Validates the password
3. Update password
4. Return row affected

:green_check_mark: SignIn Explanation

• SCRAM

  1. Cliente normaliza o username e a senha utilizando o algoritmo SASLprep (RFC 4013).
  2. Cliente escolhe um ClientNonce aleatório composto por 32 bytes.
  3. Cliente envia para o servidor UserName e ClientNonce, solicitando o início do processo de autenticação.
  4. Servidor escolhe um ServerNonce aleatório composto por 32 bytes.
  5. Servidor armazena no banco de dados um login em andamento com os dados UserName, ClientNonce e ServerNonce , com validade de 1 minuto.
  6. Servidor responde com Salt, ServerNonce, ArgonMemory, ArgonIterations, ArgonParalelism, ArgonLength.
  7. Cliente computa HashedPassword = Argon2id(Password, Salt) (custoso).
  8. Cliente computa ClientKey = HMAC-SHA3-512(HashedPassword, "Client Key").
  9. Cliente computa HashedClientKey = SHA3-512(ClientKey).
  10. Cliente computa Auth = ClientNonce || ServerNonce || Salt.
  11. Cliente computa ClientProof = ClientKey XOR HMAC-SHA3-512(HashedClientKey, Auth).
  12. Cliente envia para o servidor UserName , ClientNonce, ServerNonce e ClientProof .
  13. Servidor busca registro no banco de dados para confirmar que os primeiros 3 parâmetros corresponde a um processo de autenticação válido, iniciado a pouco tempo. Deleta esta linha do banco de dados (uso único).
  14. Servidor computa Auth = ClientNonce || ServerNonce || Salt.
  15. Servidor computa ClientKey = ClientProof XOR HMAC-SHA3-512(HashedClientKey, Auth).
  16. Servidor verifica se SHA3-512(ClientKey) === HashedClientKey. Se essa igualdade for falsa, rejeitar autenticação.
  17. Servidor computa ServerProof = HMAC-SHA3-512(ServerKey, Auth).
  18. Servidor cria sessão para o usuário e produz um token bearer.
  19. Servidor envia para o cliente o ServerProof, junto com o token de sessão
  20. Cliente computa ServerKey = HMAC-SHA3-512(HashedPassword, "Server Key").
  21. Cliente computa RefServerProof = HMAC-SHA3-512(ServerKey, Auth).
  22. Cliente verifica se RefServerProof === ServerProof. Se essa igualdade for falsa, rejeitar autenticação.

• PLAIN

  1. Cliente envia UserName e Password para o servidor.
  2. Servidor normaliza o username e a senha utilizando o algoritmo SASLprep (RFC 4013).
  3. Servidor computa HashedPassword = Argon2id(Password, Salt) (custoso).
  4. Servidor computa ClientKey = HMAC-SHA3-512(HashedPassword, "Client Key").
  5. Servidor computa HashedClientKey = SHA3-512(ClientKey).
  6. Servidor verifica se HashedClientKey é o mesmo salvo em banco de dados. Se for, aceitar a autenticação e responder com token de sessão.

🚀 Technologies

The following tools were used in this project:

• Node.js
• TypeScript
• Kysely

Back to top