Skip to main content

​
Autenticação e identidade

A Orquena utilizará Better Auth como framework inicial para credenciais, providers, account linking e sessões.
Autenticação responde quem está acessando. Organizações, memberships, roles, permissions, billing e conexões de calendário continuam sendo domínios próprios da Orquena.

​
Experiência do MVP

A tela inicial oferece:
O botão do Google serve tanto para cadastro quanto para login. No primeiro acesso, a Orquena cria o usuário, o CustomerAccount, a primeira Organization e as memberships de proprietário antes de iniciar o onboarding guiado.

​
Login com Google

O login inicial solicita somente identidade básica:
Esses dados permitem:
  • Identificar a conta Google.
  • Obter email verificado quando disponibilizado.
  • Preencher nome e imagem de perfil.
  • Criar ou localizar o usuário da Orquena.
O login não concede acesso automático ao Google Calendar, Gmail, Drive ou Contacts.

​
Login e Calendar são consentimentos separados

A autorização do Calendar acontece durante o onboarding ou nas configurações de integrações, quando o usuário entende por que o acesso é necessário. A pessoa pode entrar com uma conta Google e autorizar outro calendário operacional posteriormente, conforme as regras permitidas pelo Google e pela organização.

​
Primeiro acesso

Depois da autenticação inicial:
A organização inicia em SETUP_REQUIRED. Um usuário que já existe entra na sessão e acessa a organização ou retoma o setup incompleto.

​
Account linking

Quando permitido e validado, uma identidade Google pode ser vinculada a uma conta Orquena existente. Regras:
  • Não vincular apenas por email não verificado.
  • Exigir sessão autenticada ou fluxo seguro de confirmação quando existir risco de colisão.
  • Registrar provider account, subject externo e timestamps.
  • Permitir revogação sem apagar o usuário ou os dados da organização.
  • Impedir que a remoção do Google Login desconecte silenciosamente uma integração de Calendar separada.

​
Por que Better Auth

  • Framework TypeScript e agnóstico de frontend.
  • Licença MIT.
  • Email e senha.
  • Social providers.
  • Sessions e account linking.
  • MFA e passkeys.
  • Magic link e OTP.
  • API keys.
  • JWT, bearer e OAuth plugins.
  • Plugin ecosystem ativo.
A versão self-hosted do framework é gratuita; serviços gerenciados do fornecedor permanecem opcionais.

​
Fronteira arquitetural

O backend nunca autoriza uma organização apenas porque existe um claim antigo no token.

​
Tipos de identidade

​
Usuário humano

  • Google Login desde o MVP.
  • Email e senha.
  • Verificação de email.
  • Recuperação de conta.
  • MFA e passkeys posteriormente para funções elegíveis.
  • Gestão e revogação de sessões.

​
API client

  • API keys owned por organização.
  • Scopes explícitos.
  • Expiração e rotação.
  • Valor armazenado somente como hash.
  • Last-used e audit metadata.

​
Serviço interno

Workers, AI Runtime e plugins utilizam credenciais próprias e curtas. Eles não reutilizam cookies ou sessões de usuários humanos.

​
Sessões

  • Cookies HTTP-only e secure.
  • SameSite adequado ao fluxo.
  • Identificadores opacos.
  • Rotação e revogação server-side.
  • Invalidação em eventos de segurança.
  • Cross-domain auth somente através de desenho suportado.
  • Nenhum compartilhamento improvisado de cookies entre subdomínios.

​
Segurança OAuth

  • state e PKCE quando aplicável.
  • Redirect URIs exatas e allowlisted.
  • Validação de issuer, audience, nonce e assinatura.
  • Client secrets somente no backend.
  • Tokens nunca persistidos no browser como armazenamento durável.
  • Scopes mínimos.
  • Revogação e reconexão explícitas.
  • Eventos de login, linking e unlinking auditados.
  • Rate limits e proteção contra account enumeration.

​
Separação de credenciais Google

Mesmo quando usam a mesma conta Google, os propósitos e registros permanecem separados para permitir consentimento incremental, revogação e auditoria corretos.

​
Organization plugin

O plugin de organizations do Better Auth poderá ser estudado, mas não será adotado automaticamente como source of truth de tenancy. A Orquena precisa de regras próprias para organizations, billing, plugins, agents e data isolation.

​
Alternativas

  • Auth.js: relevante e maduro para Next.js, mas com plugin surface menor para o escopo atual.
  • Keycloak/ZITADEL: candidatos futuros para enterprise federation e external IdP.
  • Auth customizada: rejeitada.

Better Auth

Visão geral e funcionalidades.

Plugins

Providers, MFA, passkeys, API keys e OAuth.

Google OAuth

Conceitos de autorização e consentimento incremental.

GitHub

Código, releases e licença MIT.