> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orquena.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Autenticação e identidade

> Uso do Better Auth, separação entre identidade, tenancy e permissions e requisitos de segurança.

# Autenticação e identidade

A Nuvexa utilizará **Better Auth** como framework inicial para credenciais, providers e sessões.

<Note>
  Better Auth resolve autenticação. Organizações, memberships, roles, permissions e billing continuam sendo domínios próprios da Nuvexa.
</Note>

## 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

```text theme={null}
Better Auth
├── Credential
├── Provider account
├── Verification
└── Session

Nuvexa
├── User mapping
├── Organization
├── Membership
├── Location
├── Role
├── Permission
└── Entitlement
```

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

```text theme={null}
Authenticated session
    ↓
Current membership validation
    ↓
Permission evaluation
    ↓
Trusted organization context
```

## Tipos de identidade

### Usuário humano

* Email e senha inicialmente.
* Verificação de email.
* Recuperação de conta.
* Social login posteriormente.
* MFA e passkeys 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, nunca compartilhamento improvisado de cookies.

## Segurança

* Rate limits e abuse protection.
* OAuth state e callback validation.
* Secret rollover.
* Audit de login, MFA, recovery e API keys.
* Redução de account enumeration.
* Requisitos reforçados para Platform Admin.
* Security advisories revisadas antes de upgrades.

## 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 Nuvexa precisa de regras próprias para locations, 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.

## Links oficiais

<CardGroup cols={2}>
  <Card title="Better Auth" icon="book-open" href="https://better-auth.com/docs/introduction">
    Visão geral e funcionalidades.
  </Card>

  <Card title="Plugins" icon="puzzle" href="https://better-auth.com/docs/plugins">
    MFA, passkeys, API keys, OAuth e outros.
  </Card>

  <Card title="Passkeys" icon="fingerprint" href="https://better-auth.com/docs/plugins/passkey">
    Autenticação WebAuthn.
  </Card>

  <Card title="GitHub" icon="github" href="https://github.com/better-auth/better-auth">
    Código, releases e licença MIT.
  </Card>
</CardGroup>