NEAD Hub docs
Nesta página

Histórias do usuário · Identidade e acesso

US-IDENTIDADE-001 · Cadastrar Pessoa com conta de acesso

Ator: operador autorizado a administrar o Perfil de Acesso solicitado.

Necessidade: cadastrar uma Pessoa física e sua conta na mesma operação.

Critérios de aceitação

  • O cadastro conjunto aceita account quando a Pessoa tem papel USER ou ASSOCIATE.
  • A API valida o direito de conceder o perfil e a disponibilidade do e-mail.
  • A conta local é vinculada à Pessoa e à identidade Appwrite, sem hash de senha local.
  • Falha no provisionamento impede a confirmação local. Se a confirmação local falhar depois, a API tenta remover a identidade Appwrite.

US-IDENTIDADE-002 · Entrar com identidade Appwrite

Ator: titular de uma conta vinculada ao Appwrite.

Necessidade: acessar a API com o JWT Appwrite e o Perfil de Acesso da conta local.

Critérios de aceitação

  • A API resolve a conta pelo appwriteSubject e exige conta ativa com Perfil de Acesso.
  • Para conta legada ainda sem subject, pode usar o e-mail normalizado; uma conta já vinculada a outro subject não é aceita por esse caminho.
  • A conta Appwrite não entra por POST /v1/auth/login nem altera a senha por PATCH /v1/users/me/password.

US-IDENTIDADE-003 · Entrar com conta local

Ator: titular de uma conta com credencial local.

Necessidade: autenticar-se diretamente na API com e-mail e senha.

Critérios de aceitação

  • Conta ativa, sem appwriteSubject, com hash local e senha correta recebe JWT da API.
  • Conta inexistente, inativa, vinculada ao Appwrite ou com senha incorreta recebe 401.
  • A mudança da própria senha exige a senha atual; token de máquina e conta Appwrite são recusados.

US-IDENTIDADE-004 · Administrar token de integração

Ator: titular de uma conta pessoal.

Necessidade: criar, listar e revogar credenciais de integração.

Critérios de aceitação

  • A emissão exige Perfil de Acesso de Núcleo ou superior, systemKey de sistema habilitado e, quando informado, expiresAt futuro.
  • O segredo completo é devolvido apenas na criação; a API armazena seu hash.
  • O titular lista e revoga os próprios tokens. Token revogado, expirado, com segredo inválido ou dono inativo não autentica.

US-IDENTIDADE-005 · Acessar recursos no alcance autorizado

Ator: titular de uma conta autenticada.

Necessidade: executar operações permitidas pelo Perfil de Acesso e vínculos aplicáveis.

Critérios de aceitação

  • Uma rota com perfil mínimo recusa uma conta abaixo desse nível.
  • Operações que dependem de alcance resolvem a Pessoa vinculada à conta; ausência de vínculo vigente recusa a resolução.
  • O serviço aplica as condições do recurso solicitado após a verificação do perfil e do alcance.

Fluxos críticos

Cadastro conjunto de Pessoa e conta

História relacionada: US-IDENTIDADE-001.

O operador informa os dados da Pessoa física, o papel, o e-mail, a senha inicial e o Perfil de Acesso. A operação grava a Pessoa e a conta local, vincula o appwriteSubject ao ID local e provisiona a identidade Appwrite. Uma falha no provisionamento desfaz a transação local; se a confirmação local falhar depois, a operação tenta remover a identidade externa. A criação administrativa de conta para uma Pessoa já cadastrada segue uma operação separada.

Entrada e saída pelo front com Appwrite

História relacionada: US-IDENTIDADE-002.

  1. O servidor do front cria a sessão Appwrite e obtém um JWT vinculado a ela.
  2. Com esse JWT, consulta a conta local. A API resolve a conta ativa pelo appwriteSubject ou, para conta legada ainda sem vínculo, pelo e-mail normalizado.
  3. Após o reconhecimento, o front grava o cookie de sessão e abre a aplicação. Se a API recusar a identidade, o front tenta revogar a sessão criada e invalida o JWT em cache.
  4. Na saída ou expiração, o front tenta revogar a sessão Appwrite, remove o cookie e invalida o JWT em cache.

O front reutiliza um JWT válido em cache ou obtém outro da sessão Appwrite. A API avalia o Perfil de Acesso, os vínculos e o recurso a cada operação protegida.

Recuperação e troca de senha

Histórias relacionadas: US-IDENTIDADE-002 e US-IDENTIDADE-003.

O front solicita e conclui a recuperação de senha pelo Appwrite. A conta Appwrite autenticada também troca sua senha pelo Appwrite. A conta com credencial local troca a própria senha pela API, após informar a senha atual; esse caminho não aceita contas Appwrite nem tokens de máquina.

Camadas do domínio