@authyon/server 0.2.0-beta.20 → 0.2.0-beta.22

package/README.md

@@ -1,473 +1,541 @@
-# @authyon/server
-
-SDK server-side para o [Authyon](https://authyon.com) — administração de ambiente/tenants (OAuth client-credentials) e verificação de access token (publishable key). Nunca importe este pacote em código de browser.
-
-## Instalação da beta
-
-```bash
-npm install --save-exact @authyon/server@0.2.0-beta.4
-```
-
-Durante a beta, `npm install @authyon/server@beta` acompanha o prerelease mais recente. Fixar a versão exata é recomendado para builds reproduzíveis.
-
-O pacote possui uma condição de exportação `browser` que falha imediatamente se um bundler tentar incluí-lo no frontend. URLs remotas exigem HTTPS e cada request tem timeout padrão de 15 segundos, configurável por `timeoutMs`.
-
-O client aceita o mesmo contrato `HttpAdapter` de `@authyon/auth`, útil para tracing, mocks e stacks HTTP próprias:
-
-```ts
-import { createClient, FetchHttpAdapter } from "@authyon/server";
-
-const authyon = createClient({
-  envKey: process.env.AUTHYON_ENV_KEY,
-  httpAdapter: new FetchHttpAdapter(globalThis.fetch),
-});
-```
-
-Quando houver credenciais, adapter e observabilidade, o builder mantém cada etapa explícita:
-
-```ts
-const authyon = new AuthyonServerClientBuilder()
-  .withEnvironmentKey(process.env.AUTHYON_ENV_KEY)
-  .withEnvironmentCredentials(process.env.AUTHYON_CLIENT_ID, process.env.AUTHYON_CLIENT_SECRET)
-  .withHttpLogger(httpLogger)
-  .build();
-```
-
-O client também aceita `httpLogger: { enabled, logger? }`. A configuração é mutável, portanto `enabled` pode ser alterado em runtime. Os eventos não incluem headers, bodies nem valores de query string, e erros do logger nunca interrompem requests.
-
-`AuthyonError`, `ErrorCodes` e `error.interpret()` também são exportados por este pacote. Use `category`, `action`, `retryable`, `retryAfter` e `requestId` para implementar middleware e observabilidade sem comparar mensagens humanas.
-
-## Sessão web no BFF (código ainda não publicado)
-
-O novo entrypoint `@authyon/server/bff` oferece login, 2FA, sessão HttpOnly,
-renovação sob demanda, logout e troca de organização. Os tokens ficam no servidor,
-com adaptador Redis cifrado e compare-and-swap para concorrência entre instâncias.
-Reutiliza os endpoints existentes e o cliente de validação server-side.
-
-Veja [contrato e integração](../../docs/bff.md) e [análise/plano](../../docs/bff-session-plan.md).
-O entrypoint padrão e `@authyon/server/next` mantêm seu comportamento anterior;
-a adoção do transporte BFF pelo consumidor é explícita.
-
-## Validação local com JWKS
-
-Para APIs de alto volume, crie uma vez um verificador com discovery automático:
-
-```ts
-const verifier = await authyon.createJwksTokenVerifier({
-  audience: process.env.AUTHYON_AUDIENCE,
-  algorithms: ["RS256"],
-});
-
-const { claims } = await verifier.verifyAccessToken(token);
-```
-
-Ele valida assinatura, algoritmo, issuer, audience, tipo e claims temporais, com cache e rotação de chaves. Use `verification: "jwks"` em `authorizeRequest()` ou `createExpressAuthorizationMiddleware()`. Para ações sensíveis que precisam detectar revogação imediatamente, mantenha o padrão `validate`.
-
-## Instalação
-
-```bash
-npm install @authyon/server
-```
-
-## Chaves e credenciais
-
-| Credencial                             | Uso                                                                                                                                                                                                                                         |
-| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `envKey` (`pk_...`)                    | Selecionado em **toda** chamada via `X-Authyon-Environment` (Test/Live). Não é sensível — é a mesma chave do frontend, mas sozinha não autoriza nada.                                                                                       |
-| `clientId` / `clientSecret` (ambiente) | Credenciais OAuth client-credentials de nível ambiente, mintadas no console. O SDK troca por um access token (`POST /env/oauth/token`) e o renova sozinho, usado em todo `environment.*` / `permissions.*`. **Nunca** exponha ao navegador. |
-| `clientId` / `clientSecret` (tenant)   | Credenciais por-tenant, usadas via `authyon.tenant({ clientId, clientSecret })` para as chamadas `TenantManagement` (`/tenant/...`).                                                                                                        |
-
-```ts
-import { createClient } from "@authyon/server";
-
-const authyon = createClient({
-  envKey: process.env.AUTHYON_ENV_KEY, // pk_live_...
-  clientId: process.env.AUTHYON_CLIENT_ID, // ec_live_...
-  clientSecret: process.env.AUTHYON_CLIENT_SECRET,
-});
-```
-
-> `@authyon/auth` também exporta um `createClient`. Se algum dia precisar dos dois no mesmo arquivo, use um alias no import: `import { createClient as createServerClient } from "@authyon/server"`.
-
-## Verificação de token
-
-```ts
-const { active, sub } = await authyon.introspect(token); // leve
-const { user, organization } = await authyon.validate(token); // recomendado — cross-checa revogação
-```
-
-Veja [`examples/tokenVerification.ts`](./examples/tokenVerification.ts) para um middleware completo.
-
-## Administração de ambiente (`environment.*`)
-
-Usa as credenciais de ambiente (`clientId`/`clientSecret`) automaticamente — o SDK minta e renova o token sozinho.
-
-```ts
-const org = await authyon.environment.tenants.create({ name: "Acme", slug: "acme" });
-const tenants = await authyon.environment.tenants.list({
-  search: "acme",
-  skip: 0,
-  take: 20,
-});
-await authyon.environment.tenants.members.add(org.id, userId, ["owner"]);
-await authyon.environment.tenants.members.assignRole(org.id, userId, "billing-admin");
-await authyon.environment.tenants.members.remove(org.id, userId);
-
-await authyon.environment.users.list({ search: "acme.com" });
-await authyon.environment.roles.create({ name: "support", permissions: ["tickets:read"] });
-await authyon.environment.audit.list({ take: 50 });
-```
-
-Veja [`examples/organizationMembership.ts`](./examples/organizationMembership.ts) para o fluxo completo, incluindo as rotas de backend que o `@authyon/auth` chamaria.
-
-Namespaces disponíveis: `environment.users`, `environment.tenants` (com `.members` e `.roles` aninhados), `environment.roles`, `environment.permissions`, `environment.audit`. OTP e aprovações ficam em `security` (veja abaixo).
-
-## Autorização local
-
-`createAuthyonAbility()` transforma o resultado de `validate()`, `introspect()` ou qualquer objeto com `permissions`, `roles` e `scope` em verificações locais no estilo CASL:
-
-```ts
-import { createAuthyonAbility } from "@authyon/server";
-
-const identity = await authyon.validate(token);
-const ability = createAuthyonAbility(identity);
-
-if (!ability.can("read", "reports")) {
-  throw new Error("Forbidden");
-}
-```
-
-Regras condicionais e de domínio podem ser acrescentadas no segundo argumento. O mecanismo é deny-by-default e não substitui a validação do token nem a autorização aplicada pela API.
-
-### Next.js Server Side
-
-Em Route Handlers, Server Actions ou SSR, mantenha `@authyon/server` em um módulo marcado com `server-only`:
-
-```ts
-import "server-only";
-import { createAuthorizationErrorResponse, authorizeRequest, createClient } from "@authyon/server";
-
-const authyon = createClient({
-  envKey: process.env.AUTHYON_ENV_KEY,
-  clientId: process.env.AUTHYON_CLIENT_ID,
-  clientSecret: process.env.AUTHYON_CLIENT_SECRET,
-});
-
-export async function GET(request: Request) {
-  try {
-    const auth = await authorizeRequest(authyon, request, {
-      requirement: { action: "read", subject: "reports" },
-    });
-    return Response.json({ userId: auth.userId });
-  } catch (error) {
-    return createAuthorizationErrorResponse(error);
-  }
-}
-```
-
-### Express e frameworks Connect
-
-O middleware não adiciona Express como dependência e disponibiliza `request.authyon`:
-
-```ts
-import { createExpressAuthorizationMiddleware } from "@authyon/server";
-
-app.get(
-  "/reports",
-  createExpressAuthorizationMiddleware(authyon, {
-    requirement: { action: "read", subject: "reports" },
-  }),
-  (request, response) => response.json({ userId: request.authyon.userId }),
-);
-```
-
-Use `authorizeToken()` em NestJS, Fastify, Hono, tRPC ou integrações próprias. `passErrorsToNext: true` encaminha erros ao middleware de erros do Express.
-
-### IP real do cliente
-
-Chamadas server-side propagam `clientIp` em `X-Forwarded-For`. O middleware Express usa o IP do socket por padrão; atrás de um proxy confiável, configure o próprio Express e use `trustProxy: true`. Para Next.js, passe `resolveClientIp` ao `authorizeRequest()` lendo somente headers que sua infraestrutura sobrescreve. Não confie cegamente em `X-Forwarded-For` recebido da internet.
-
-```ts
-await authyon.validate(token, { clientIp: "203.0.113.10" });
-```
-
-## Segurança (`security.*`)
-
-OTP e aprovações ficam agrupados em `authyon.security`. Exige uma credencial de ambiente
-com o escopo `authyon:otp:verify` (para `security.otp`) e/ou `authyon:financial:authorize`
-(para `security.approvals`). Guia completo:
-[`docs/security-otp-approvals.md`](../../docs/security-otp-approvals.md).
-
-```ts
-// security.otp — só validar o código do app autenticador
-const result = await authyon.security.otp.check(customerId, code);
-if (!result.valid) console.log(result.attemptsRemaining, result.sessionsRevoked);
-
-// security.approvals — aprovação presa a um payload livre e de uso único
-const { id } = await authyon.security.approvals.create({
-  subjectId: customerId,
-  payload: { type: "pix", amount: 150.5, to: "maria@example.com" },
-});
-// ...cliente confirma com @authyon/auth → security.approvals.confirm
-const { payload } = await authyon.security.approvals.consume(id);
-```
-
-| Método                               | Endpoint                                |
-| ------------------------------------ | --------------------------------------- |
-| `security.otp.check(userId, code)`   | `POST /env/users/{userId}/otp/verify`   |
-| `security.approvals.create(input)`   | `POST /env/authorizations`              |
-| `security.approvals.get(id)`         | `GET /env/authorizations/{id}`          |
-| `security.approvals.consume(id, p?)` | `POST /env/authorizations/{id}/consume` |
-
-Cada código vale uma vez; 3 erros seguidos deslogam o usuário de todos os dispositivos e
-5 bloqueiam a verificação por 15 minutos. Se o seu servidor guarda o token do cliente
-(BFF), o lado do cliente está em `authyon.user(accessToken).security.approvals`.
-
-## Administração por tenant (`tenant()`)
-
-As credenciais de um tenant são próprias dele — use `authyon.tenant(credentials)` para obter um cliente escopado, que minta e cacheia seu próprio token via `POST /tenant/oauth/token`:
-
-```ts
-const acme = authyon.tenant({ clientId: acmeClientId, clientSecret: acmeClientSecret });
-
-const identity = await acme.validate(); // POST /tenant/auth/validate
-await acme.members.list();
-await acme.members.add(userId, ["member"]);
-await acme.roles.create({ name: "viewer", permissions: ["reports:read"] });
-```
-
-`validate()` confirma o bearer tenant-client atual e devolve `tenantId`,
-`credentialId`, `clientId` e as permissões vigentes da credencial. A resposta
-vem do backend depois da checagem de revogação, rotação de secret e tenant
-desabilitado; não confie só na claim `scope` quando precisar do estado atual.
-
-Em middleware, quando você já recebeu o bearer tenant-client na requisição, não
-use `clientId`/`clientSecret`; valide o token diretamente:
-
-```ts
-const validation = await authyon.tenantAuth.validate(tenantBearerToken, {
-  clientIp: "203.0.113.10",
-});
-
-if (!validation.valid) {
-  // responda 401
-}
-```
-
-## Descoberta
-
-```ts
-await authyon.discovery.jwks(); // GET /.well-known/jwks.json
-await authyon.discovery.openidConfiguration(); // GET /.well-known/openid-configuration
-```
-
-## Build
-
-```bash
-npm install
-npm run build      # dist/ (ESM + CJS + .d.ts via tsup)
-npm run typecheck
-```
-
-### Emitir uma credencial de integração do tenant
-
-Requer o endpoint `POST /env/tenants/{tenantId}/credentials` no backend Authyon
-e uma credencial de ambiente com `authyon:credentials:manage`.
-
-```ts
-const credential = await authyon.environment.tenants.credentials.create(tenantId, {
-  description: "ERP financeiro",
-  permissions: ["monkeypay:transactions:read"],
-});
-// Entregue clientId e clientSecret ao operador: o segredo só é retornado uma vez.
-```
-
-As permissões são explícitas e pertencem à integração; não há concessão automática de acesso total.
-
-## Credenciais: paginação, busca e detalhe
-
-```ts
-const page = await authyon.environment.tenants.credentials.listPage(tenantId, {
-  search: "transactions",
-  skip: 0,
-  take: 25,
-});
-const detail = await authyon.environment.tenants.credentials.get(tenantId, credentialId);
-```
-
-`page` contém `data`, `page` (a página atual, começando em 1), `perPage` (o
-limite por página), `total`, `pages`, `hasNext` e `hasPrev`. Até a API de
-2026-10-21 os dois campos se chamavam `perPage` (página) e `pageSize`
-(limite), nessa ordem trocada. `take` aceita 1–100 (padrão da API: 25),
-`skip` é um deslocamento a partir de zero e `search` aceita até 200 caracteres.
-A API pesquisa clientId, descrição e permissões antes de paginar.
-
-O método existente `credentials.list(tenantId)` continua retornando um array:
-aceita a resposta antiga e percorre todas as páginas da API atual. Prefira
-`listPage` para tabelas ou grandes volumes. A leitura completa detecta páginas
-sobrepostas/sem progresso e tem limite de 1.000 páginas; alterações concorrentes
-podem exigir reiniciar a leitura, pois a API usa paginação por deslocamento.
-
-O detalhe contém `permissions`, `createdBy` (`id`, `type`, `displayName`),
-`createdAt`, `updatedAt`, `lastUsedAt`, `secretRotatedAt`, `revokedAt`, `isActive`,
-`expiresAt`, `ageSeconds`, `lifetimeSeconds` e `accessTokenLifetimeSeconds`.
-Listagem e detalhe projetam somente campos permitidos, sem segredo ou hash.
-Registros antigos podem ter autor e atualização nulos. A credencial atual não
-expira automaticamente: `expiresAt` é nulo; `lifetimeSeconds` é nulo enquanto
-ativa e representa sua duração até a revogação quando revogada. A validade do
-access token é separada (atualmente 1.800 segundos).
-
-## Scopes e ciclo de vida das credenciais
-
-`scopes` é um alias de `permissions` na criação/atualização. Use somente um dos
-campos, com uma lista explícita no formato `namespace:resource:action`. O SDK
-normaliza espaços, caixa e duplicatas; não concede permissões automaticamente.
-A API continua responsável pela autorização. O contrato antigo
-`CreateTenantCredentialInput` e chamadas usando `permissions` são preservados.
-
-```ts
-const issued = await authyon.environment.tenants.credentials.create(tenantId, {
-  description: "ERP financeiro",
-  scopes: ["monkeypay:transactions:read"],
-});
-// Armazene issued.clientSecret no gerenciador de segredos. Não registre a resposta.
-
-await authyon.environment.tenants.credentials.listPage(tenantId, {
-  search: "ERP",
-  skip: 0,
-  take: 25,
-});
-await authyon.environment.tenants.credentials.get(tenantId, credentialId);
-await authyon.environment.tenants.credentials.create(tenantId, {
-  description: "Leitura",
-  permissions: ["monkeypay:transactions:read"],
-});
-await authyon.environment.tenants.credentials.updateScopes(tenantId, credentialId, [
-  "monkeypay:transactions:read",
-]);
-await authyon.environment.tenants.credentials.updatePermissions(tenantId, credentialId, {
-  permissions: ["monkeypay:transactions:read"],
-});
-const rotated = await authyon.environment.tenants.credentials.rotate(tenantId, credentialId);
-await authyon.environment.tenants.credentials.revoke(tenantId, credentialId);
-```
-
-Criação e rotação retornam o segredo uma única vez. Alterar permissões substitui a lista
-completa. A concessão OAuth continua recebendo apenas `clientId`/`clientSecret`;
-`scopes` não é um parâmetro de redução de acesso na troca de token.
-
-Todas as operações usam os endpoints externos `/env` com a credencial de
-ambiente configurada no cliente. O SDK não repete mutações automaticamente.
-
-## Membros do tenant
-
-```ts
-const user = authyon.user(() => getCurrentUserAccessToken());
-await user.tenants.members.invite(tenantId, {
-  email: "pessoa@example.com",
-  roles: ["reader"],
-});
-await user.tenants.members.list(tenantId, { skip: 0, take: 25 });
-await user.tenants.members.remove(tenantId, userId);
-
-// Pelo plano administrativo, a listagem vem no envelope paginado de sempre
-// (`data`, `total`, `hasNext`), com `take` 50 por padrão e teto 100.
-const { data: membros, total } = await authyon.environment.tenants.members.list(tenantId);
-
-// Administração por máquina: adicione uma conta existente por ID.
-await authyon.environment.tenants.members.add(tenantId, userId, ["reader"]);
-await authyon.environment.tenants.members.remove(tenantId, userId);
-// Os métodos tenant(credentials).members.add/remove existentes continuam disponíveis.
-```
-
-Configure `envKey` para `user()`. `members.invite` associa um usuário já
-cadastrado no ambiente pelo e-mail; não cria conta e não envia link por e-mail.
-Para isso, use os convites abaixo.
-A API exige associação/permissões do usuário chamador. No browser, os métodos
-existentes `@authyon/auth` → `organization.members.invite/remove` continuam
-atendendo esse fluxo. Nunca importe `@authyon/server` no browser.
-
-## Convites de tenant (e-mail ou link)
-
-Convide um e-mail que talvez ainda não tenha conta — aceitar cria a conta, já com o
-e-mail confirmado. A resposta sempre traz o `acceptUrl` completo; `sendEmail: false`
-só gera o link para você enviar pelo seu canal.
-
-```ts
-// Pelo ambiente (escopo authyon:users:write; listar exige authyon:tenants:read).
-const invite = await authyon.environment.tenants.invites.create(tenantId, {
-  email: "pessoa@example.com",
-  roles: ["reader"],
-  sendEmail: false, // padrão: true
-  // Opcional: para onde mandar a pessoa depois de aceitar. Precisa estar
-  // cadastrado (match exato) nos redirect URIs do ambiente.
-  redirectUri: "https://app.example.com/bem-vindo",
-});
-invite.acceptUrl; // só aparece aqui — a API guarda apenas o hash do token
-
-await authyon.environment.tenants.invites.list(tenantId);
-await authyon.environment.tenants.invites.resend(tenantId, invite.id, { sendEmail: true });
-await authyon.environment.tenants.invites.revoke(tenantId, invite.id);
-
-// Pela credencial do tenant, ou agindo como o usuário (permissão tenants:members:invite).
-await authyon.tenant(credentials).invites.create({ email: "pessoa@example.com" });
-await authyon.user(token).tenants.invites.create(tenantId, { email: "pessoa@example.com" });
-
-// Página de aceite no seu backend: públicas, usam só o envKey.
-const preview = await authyon.environment.tenants.invites.preview(token);
-const accepted = await authyon.environment.tenants.invites.accept({
-  token,
-  password: preview.accountExists ? undefined : password,
-  // Opcional. Com metadata, a chamada vai para /env/tenant-invites/accept usando
-  // clientId/clientSecret (escopo authyon:users:write) — só o backend pode definir.
-  publicMetadata: { plano: "pro" },
-  privateMetadata: { crmId: "42" },
-  // customFields: { ... } — obsoleto, prefira os metadata acima.
-});
-if (accepted.redirectUri) redirect(accepted.redirectUri); // o redirect fica por sua conta
-```
-
-O link vale 7 dias e uma única vez. `resend` gera um link novo e invalida o anterior.
-Por padrão o link aponta para a página do Authyon; configure a _URL do convite para
-tenant_ nas configurações do ambiente para usar a sua (ela recebe `token` e `env`).
-Aceitar não faz login.
-
-## Redefinição de senha pelo seu próprio e-mail
-
-Para a sua aplicação disparar o e-mail de redefinição em vez do Authyon, emita o token no
-backend (escopo `authyon:users:password`) e entregue você mesmo:
-
-```ts
-const reset = await authyon.environment.users.issuePasswordReset({
-  email: "pessoa@example.com",
-  // Opcional: para onde mandar a pessoa depois de trocar a senha. Precisa estar
-  // cadastrado (match exato) nos redirect URIs do ambiente.
-  redirectUri: "https://app.example.com/login",
-  // sendEmail: true faria o Authyon enviar também; o padrão é false.
-});
-reset.token; // só aparece aqui — a API guarda apenas o hash
-reset.resetUrl; // o link que o e-mail do Authyon levaria
-reset.expiresAt; // 30 minutos
-
-// Página de redefinição no seu backend: públicas, usam só o envKey.
-const preview = await authyon.environment.users.validatePasswordReset(token); // não gasta o token
-const done = await authyon.environment.users.confirmPasswordReset(token, newPassword);
-if (done.redirectUri) redirect(done.redirectUri); // o redirect fica por sua conta
-```
-
-Quem tem o token consegue definir a senha: envie somente para o endereço da própria conta e
-não registre em log. Emitir um token novo invalida o anterior da mesma conta. Um endereço
-sem conta responde `404 user.not_found`; token desconhecido, usado ou expirado responde
-`401 user.password_reset.invalid`.
-
-## Compatibilidade e segurança do transporte
-
-As chamadas exigem os endpoints externos atuais da API e a migração
-`ClientCredentialMetadata` para metadados
-persistidos. O SDK não altera o banco nem publica uma versão automaticamente.
-
-O adaptador Fetch agora rejeita redirects para evitar reenviar tokens/segredos;
-configure a URL final HTTPS da API. Adaptadores HTTP personalizados devem manter
-essa política. Os logs internos omitem corpos/headers e ocultam tokens de
-convite presentes no caminho. A auditoria de operações permanece na API; o SDK
-não gera eventos duplicados ao consultar listagens de auditoria.
+# @authyon/server
+
+SDK server-side para o [Authyon](https://authyon.com) — administração de ambiente/tenants (OAuth client-credentials) e verificação de access token (publishable key). Nunca importe este pacote em código de browser.
+
+## Instalação da beta
+
+```bash
+npm install --save-exact @authyon/server@0.2.0-beta.4
+```
+
+Durante a beta, `npm install @authyon/server@beta` acompanha o prerelease mais recente. Fixar a versão exata é recomendado para builds reproduzíveis.
+
+O pacote possui uma condição de exportação `browser` que falha imediatamente se um bundler tentar incluí-lo no frontend. URLs remotas exigem HTTPS e cada request tem timeout padrão de 15 segundos, configurável por `timeoutMs`.
+
+O client aceita o mesmo contrato `HttpAdapter` de `@authyon/auth`, útil para tracing, mocks e stacks HTTP próprias:
+
+```ts
+import { createClient, FetchHttpAdapter } from "@authyon/server";
+
+const authyon = createClient({
+  envKey: process.env.AUTHYON_ENV_KEY,
+  httpAdapter: new FetchHttpAdapter(globalThis.fetch),
+});
+```
+
+Quando houver credenciais, adapter e observabilidade, o builder mantém cada etapa explícita:
+
+```ts
+const authyon = new AuthyonServerClientBuilder()
+  .withEnvironmentKey(process.env.AUTHYON_ENV_KEY)
+  .withEnvironmentCredentials(process.env.AUTHYON_CLIENT_ID, process.env.AUTHYON_CLIENT_SECRET)
+  .withHttpLogger(httpLogger)
+  .build();
+```
+
+O client também aceita `httpLogger: { enabled, logger? }`. A configuração é mutável, portanto `enabled` pode ser alterado em runtime. Os eventos não incluem headers, bodies nem valores de query string, e erros do logger nunca interrompem requests.
+
+`AuthyonError`, `ErrorCodes` e `error.interpret()` também são exportados por este pacote. Use `category`, `action`, `retryable`, `retryAfter` e `requestId` para implementar middleware e observabilidade sem comparar mensagens humanas.
+
+## Sessão web no BFF (código ainda não publicado)
+
+O novo entrypoint `@authyon/server/bff` oferece login, 2FA, sessão HttpOnly,
+renovação sob demanda, logout e troca de organização. Os tokens ficam no servidor,
+com adaptador Redis cifrado e compare-and-swap para concorrência entre instâncias.
+Reutiliza os endpoints existentes e o cliente de validação server-side.
+
+Veja [contrato e integração](../../docs/bff.md) e [análise/plano](../../docs/bff-session-plan.md).
+O entrypoint padrão e `@authyon/server/next` mantêm seu comportamento anterior;
+a adoção do transporte BFF pelo consumidor é explícita.
+
+## Validação local com JWKS
+
+Para APIs de alto volume, crie uma vez um verificador com discovery automático:
+
+```ts
+const verifier = await authyon.createJwksTokenVerifier({
+  audience: process.env.AUTHYON_AUDIENCE,
+  algorithms: ["RS256"],
+});
+
+const { claims } = await verifier.verifyAccessToken(token);
+```
+
+Ele valida assinatura, algoritmo, issuer, audience, tipo e claims temporais, com cache e rotação de chaves. Use `verification: "jwks"` em `authorizeRequest()` ou `createExpressAuthorizationMiddleware()`. Para ações sensíveis que precisam detectar revogação imediatamente, mantenha o padrão `validate`.
+
+## Instalação
+
+```bash
+npm install @authyon/server
+```
+
+## Chaves e credenciais
+
+| Credencial                             | Uso                                                                                                                                                                                                                                         |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `envKey` (`pk_...`)                    | Selecionado em **toda** chamada via `X-Authyon-Environment` (Test/Live). Não é sensível — é a mesma chave do frontend, mas sozinha não autoriza nada.                                                                                       |
+| `clientId` / `clientSecret` (ambiente) | Credenciais OAuth client-credentials de nível ambiente, mintadas no console. O SDK troca por um access token (`POST /env/oauth/token`) e o renova sozinho, usado em todo `environment.*` / `permissions.*`. **Nunca** exponha ao navegador. |
+| `clientId` / `clientSecret` (tenant)   | Credenciais por-tenant, usadas via `authyon.tenant({ clientId, clientSecret })` para as chamadas `TenantManagement` (`/tenant/...`).                                                                                                        |
+
+```ts
+import { createClient } from "@authyon/server";
+
+const authyon = createClient({
+  envKey: process.env.AUTHYON_ENV_KEY, // pk_live_...
+  clientId: process.env.AUTHYON_CLIENT_ID, // ec_live_...
+  clientSecret: process.env.AUTHYON_CLIENT_SECRET,
+});
+```
+
+> `@authyon/auth` também exporta um `createClient`. Se algum dia precisar dos dois no mesmo arquivo, use um alias no import: `import { createClient as createServerClient } from "@authyon/server"`.
+
+## Verificação de token
+
+```ts
+const { active, sub } = await authyon.introspect(token); // leve
+const { user, organization } = await authyon.validate(token); // recomendado — cross-checa revogação
+```
+
+Veja [`examples/tokenVerification.ts`](./examples/tokenVerification.ts) para um middleware completo.
+
+## Administração de ambiente (`environment.*`)
+
+Usa as credenciais de ambiente (`clientId`/`clientSecret`) automaticamente — o SDK minta e renova o token sozinho.
+
+```ts
+const org = await authyon.environment.tenants.create({ name: "Acme", slug: "acme" });
+const tenants = await authyon.environment.tenants.list({
+  search: "acme",
+  skip: 0,
+  take: 20,
+});
+await authyon.environment.tenants.members.add(org.id, userId, ["owner"]);
+await authyon.environment.tenants.members.assignRole(org.id, userId, "billing-admin");
+await authyon.environment.tenants.members.remove(org.id, userId);
+
+await authyon.environment.users.list({ search: "acme.com" });
+await authyon.environment.roles.create({ name: "support", permissions: ["tickets:read"] });
+await authyon.environment.audit.list({ take: 50 });
+```
+
+Veja [`examples/organizationMembership.ts`](./examples/organizationMembership.ts) para o fluxo completo, incluindo as rotas de backend que o `@authyon/auth` chamaria.
+
+Namespaces disponíveis: `environment.users`, `environment.tenants` (com `.members` e `.roles` aninhados), `environment.roles`, `environment.permissions`, `environment.audit`. OTP e aprovações ficam em `security` (veja abaixo).
+
+## Autorização local
+
+`createAuthyonAbility()` transforma o resultado de `validate()`, `introspect()` ou qualquer objeto com `permissions`, `roles` e `scope` em verificações locais no estilo CASL:
+
+```ts
+import { createAuthyonAbility } from "@authyon/server";
+
+const identity = await authyon.validate(token);
+const ability = createAuthyonAbility(identity);
+
+if (!ability.can("read", "reports")) {
+  throw new Error("Forbidden");
+}
+```
+
+Regras condicionais e de domínio podem ser acrescentadas no segundo argumento. O mecanismo é deny-by-default e não substitui a validação do token nem a autorização aplicada pela API.
+
+### Next.js Server Side
+
+Em Route Handlers, Server Actions ou SSR, mantenha `@authyon/server` em um módulo marcado com `server-only`:
+
+```ts
+import "server-only";
+import { createAuthorizationErrorResponse, authorizeRequest, createClient } from "@authyon/server";
+
+const authyon = createClient({
+  envKey: process.env.AUTHYON_ENV_KEY,
+  clientId: process.env.AUTHYON_CLIENT_ID,
+  clientSecret: process.env.AUTHYON_CLIENT_SECRET,
+});
+
+export async function GET(request: Request) {
+  try {
+    const auth = await authorizeRequest(authyon, request, {
+      requirement: { action: "read", subject: "reports" },
+    });
+    return Response.json({ userId: auth.userId });
+  } catch (error) {
+    return createAuthorizationErrorResponse(error);
+  }
+}
+```
+
+### Express e frameworks Connect
+
+O middleware não adiciona Express como dependência e disponibiliza `request.authyon`:
+
+```ts
+import { createExpressAuthorizationMiddleware } from "@authyon/server";
+
+app.get(
+  "/reports",
+  createExpressAuthorizationMiddleware(authyon, {
+    requirement: { action: "read", subject: "reports" },
+  }),
+  (request, response) => response.json({ userId: request.authyon.userId }),
+);
+```
+
+Use `authorizeToken()` em NestJS, Fastify, Hono, tRPC ou integrações próprias. `passErrorsToNext: true` encaminha erros ao middleware de erros do Express.
+
+### IP real do cliente
+
+Chamadas server-side propagam `clientIp` em `X-Authyon-Client-Ip` (e em `X-Forwarded-For`, para o que estiver na frente do seu backend). A API resolve o endereço do chamador pelo primeiro header e acredita nele quando a chamada está autenticada por credencial de máquina — uma chamada servidor-a-servidor não tem navegador dentro dela, e sem isso toda linha de auditoria da sua integração nomeia o gateway do contêiner, que não identifica ninguém. Muda a trilha, nunca um portão: todo controle com chave de IP roda antes da autenticação e segue decidindo pelo peer real.
+
+O middleware Express usa o IP do socket por padrão; atrás de um proxy confiável, configure o próprio Express e use `trustProxy: true`. Para Next.js, passe `resolveClientIp` ao `authorizeRequest()` lendo somente headers que sua infraestrutura sobrescreve. Não confie cegamente em `X-Forwarded-For` recebido da internet.
+
+```ts
+await authyon.validate(token, { clientIp: "203.0.113.10" });
+```
+
+## Segurança (`security.*`)
+
+OTP e aprovações ficam agrupados em `authyon.security`. Exige uma credencial de ambiente
+com o escopo `authyon:otp:verify` (para `security.otp`) e/ou `authyon:financial:authorize`
+(para `security.approvals`). Guia completo:
+[`docs/security-otp-approvals.md`](../../docs/security-otp-approvals.md).
+
+```ts
+// security.otp — só validar o código do app autenticador
+const result = await authyon.security.otp.check(customerId, code);
+if (!result.valid) console.log(result.attemptsRemaining, result.sessionsRevoked);
+
+// security.approvals — aprovação presa a um payload livre e de uso único
+const { id } = await authyon.security.approvals.create({
+  subjectId: customerId,
+  payload: { type: "pix", amount: 150.5, to: "maria@example.com" },
+});
+// ...cliente confirma com @authyon/auth → security.approvals.confirm
+const { payload } = await authyon.security.approvals.consume(id);
+```
+
+| Método                               | Endpoint                                |
+| ------------------------------------ | --------------------------------------- |
+| `security.otp.check(userId, code)`   | `POST /env/users/{userId}/otp/verify`   |
+| `security.approvals.create(input)`   | `POST /env/authorizations`              |
+| `security.approvals.get(id)`         | `GET /env/authorizations/{id}`          |
+| `security.approvals.consume(id, p?)` | `POST /env/authorizations/{id}/consume` |
+
+Cada código vale uma vez; 3 erros seguidos deslogam o usuário de todos os dispositivos e
+5 bloqueiam a verificação por 15 minutos. Se o seu servidor guarda o token do cliente
+(BFF), o lado do cliente está em `authyon.user(accessToken).security.approvals`.
+
+## Administração por tenant (`tenant()`)
+
+As credenciais de um tenant são próprias dele — use `authyon.tenant(credentials)` para obter um cliente escopado, que minta e cacheia seu próprio token via `POST /tenant/oauth/token`:
+
+```ts
+const acme = authyon.tenant({ clientId: acmeClientId, clientSecret: acmeClientSecret });
+
+const identity = await acme.validate(); // POST /tenant/auth/validate
+await acme.members.list();
+await acme.members.add(userId, ["member"]);
+await acme.roles.create({ name: "viewer", permissions: ["reports:read"] });
+```
+
+`validate()` confirma o bearer tenant-client atual e devolve `tenantId`,
+`credentialId`, `clientId` e as permissões vigentes da credencial. A resposta
+vem do backend depois da checagem de revogação, rotação de secret e tenant
+desabilitado; não confie só na claim `scope` quando precisar do estado atual.
+
+Em middleware, quando você já recebeu o bearer tenant-client na requisição, não
+use `clientId`/`clientSecret`; valide o token diretamente:
+
+```ts
+const validation = await authyon.tenantAuth.validate(tenantBearerToken, {
+  clientIp: "203.0.113.10",
+});
+
+if (!validation.valid) {
+  // responda 401
+}
+```
+
+## Descoberta
+
+```ts
+await authyon.discovery.jwks(); // GET /.well-known/jwks.json
+await authyon.discovery.openidConfiguration(); // GET /.well-known/openid-configuration
+```
+
+## Build
+
+```bash
+npm install
+npm run build      # dist/ (ESM + CJS + .d.ts via tsup)
+npm run typecheck
+```
+
+### Emitir uma credencial de integração do tenant
+
+Requer o endpoint `POST /env/tenants/{tenantId}/credentials` no backend Authyon
+e uma credencial de ambiente com `authyon:credentials:manage`.
+
+```ts
+const credential = await authyon.environment.tenants.credentials.create(tenantId, {
+  description: "ERP financeiro",
+  permissions: ["monkeypay:transactions:read"],
+});
+// Entregue clientId e clientSecret ao operador: o segredo só é retornado uma vez.
+```
+
+As permissões são explícitas e pertencem à integração; não há concessão automática de acesso total.
+
+## Credenciais: paginação, busca e detalhe
+
+```ts
+const page = await authyon.environment.tenants.credentials.listPage(tenantId, {
+  search: "transactions",
+  skip: 0,
+  take: 25,
+});
+const detail = await authyon.environment.tenants.credentials.get(tenantId, credentialId);
+```
+
+`page` contém `data`, `page` (a página atual, começando em 1), `perPage` (o
+limite por página), `total`, `pages`, `hasNext` e `hasPrev`. Até a API de
+2026-10-21 os dois campos se chamavam `perPage` (página) e `pageSize`
+(limite), nessa ordem trocada. `take` aceita 1–100 (padrão da API: 25),
+`skip` é um deslocamento a partir de zero e `search` aceita até 200 caracteres.
+A API pesquisa clientId, descrição e permissões antes de paginar.
+
+O método existente `credentials.list(tenantId)` continua retornando um array:
+aceita a resposta antiga e percorre todas as páginas da API atual. Prefira
+`listPage` para tabelas ou grandes volumes. A leitura completa detecta páginas
+sobrepostas/sem progresso e tem limite de 1.000 páginas; alterações concorrentes
+podem exigir reiniciar a leitura, pois a API usa paginação por deslocamento.
+
+O detalhe contém `permissions`, `createdBy` (`id`, `type`, `displayName`),
+`createdAt`, `updatedAt`, `lastUsedAt`, `secretRotatedAt`, `revokedAt`, `isActive`,
+`expiresAt`, `ageSeconds`, `lifetimeSeconds` e `accessTokenLifetimeSeconds`.
+Listagem e detalhe projetam somente campos permitidos, sem segredo ou hash.
+Registros antigos podem ter autor e atualização nulos. A credencial atual não
+expira automaticamente: `expiresAt` é nulo; `lifetimeSeconds` é nulo enquanto
+ativa e representa sua duração até a revogação quando revogada. A validade do
+access token é separada (atualmente 1.800 segundos).
+
+## Scopes e ciclo de vida das credenciais
+
+`scopes` é um alias de `permissions` na criação/atualização. Use somente um dos
+campos, com uma lista explícita no formato `namespace:resource:action`. O SDK
+normaliza espaços, caixa e duplicatas; não concede permissões automaticamente.
+A API continua responsável pela autorização. O contrato antigo
+`CreateTenantCredentialInput` e chamadas usando `permissions` são preservados.
+
+```ts
+const issued = await authyon.environment.tenants.credentials.create(tenantId, {
+  description: "ERP financeiro",
+  scopes: ["monkeypay:transactions:read"],
+});
+// Armazene issued.clientSecret no gerenciador de segredos. Não registre a resposta.
+
+await authyon.environment.tenants.credentials.listPage(tenantId, {
+  search: "ERP",
+  skip: 0,
+  take: 25,
+});
+await authyon.environment.tenants.credentials.get(tenantId, credentialId);
+await authyon.environment.tenants.credentials.create(tenantId, {
+  description: "Leitura",
+  permissions: ["monkeypay:transactions:read"],
+});
+await authyon.environment.tenants.credentials.updateScopes(tenantId, credentialId, [
+  "monkeypay:transactions:read",
+]);
+await authyon.environment.tenants.credentials.updatePermissions(tenantId, credentialId, {
+  permissions: ["monkeypay:transactions:read"],
+});
+const rotated = await authyon.environment.tenants.credentials.rotate(tenantId, credentialId);
+await authyon.environment.tenants.credentials.revoke(tenantId, credentialId);
+```
+
+Criação e rotação retornam o segredo uma única vez. Alterar permissões substitui a lista
+completa. A concessão OAuth continua recebendo apenas `clientId`/`clientSecret`;
+`scopes` não é um parâmetro de redução de acesso na troca de token.
+
+Todas as operações usam os endpoints externos `/env` com a credencial de
+ambiente configurada no cliente. O SDK não repete mutações automaticamente.
+
+## Hierarquia de tenants
+
+Um tenant pode ficar embaixo de outro. A listagem pagina um nível por vez, que é o
+que permite desenhar o primeiro nível sem ler a subárvore inteira:
+
+```ts
+const { data: raizes } = await authyon.environment.tenants.roots({ take: 50 });
+
+// childCount já vem na página: expanda só onde há o que expandir.
+for (const t of raizes.filter((t) => (t.childCount ?? 0) > 0)) {
+  const { data: filhos } = await authyon.environment.tenants.children(t.id);
+}
+
+// Criar embaixo de outro.
+await authyon.environment.tenants.create({
+  name: "Filial Sul",
+  slug: "filial-sul",
+  parentTenantId: holdingId,
+});
+```
+
+`list()` continua devolvendo todos os tenants em qualquer profundidade — é o que um
+seletor plano quer. `get()` traz `ancestors`, a cadeia acima do tenant com a raiz
+primeiro, então um breadcrumb custa uma chamada e não uma por nível.
+
+O ambiente nasce com `maxTenantDepth: 1` (só raízes), então criar um sub-tenant
+responde `tenant.depth.not_allowed` até um operador aumentar o teto no console.
+Alcançar para baixo é opt-in: as permissões `subtenants:tree:read|create|manage|switch`
+são concedidas no nó a que o chamador pertence, e ter `tenants:settings:manage` no pai
+não concede nada no filho. `disable()` e `delete()` desativam a subárvore junto.
+
+Detalhes e erros no [guia de hierarquia](../../docs/tenantHierarchy.md).
+
+## Filtros do tenant
+
+`search` é um substring só, ORado entre nome, slug, descrição e os dois metadata.
+Quando mais de uma condição precisa valer — `kind IN (...) AND cnpj IN (...)` — use
+`filter`, que roda dentro da consulta e por isso continua paginando:
+
+```ts
+import { tenantFilter } from "@authyon/server";
+
+const page = await authyon.environment.tenants.list({
+  filter: [
+    tenantFilter.in("public.kind", ["reseller", "partner"]),
+    tenantFilter.in("custom.cnpj", ["00000000000100", "11111111000199"]),
+  ],
+  take: 100,
+});
+
+page.total; // quantos casam com o filtro, não quantos existem no ambiente
+```
+
+Cada entrada é uma condição; várias são ANDadas entre si e com o `search`, e a
+vírgula dentro de um `in` é o OR. Os escopos são `public` (publicMetadata),
+`private` (privateMetadata) e `custom` (customFields — este o `search` nunca
+cobriu). Operadores: `eq`, `in`, `like` (ILIKE, com os metacaracteres escapados)
+e `exists`. Caminho aninhado vale até três níveis: `private.billing.plan`.
+
+O construtor valida antes de sair: escopo desconhecido, chave com espaço, mais de
+25 valores num `in` ou vírgula dentro de um valor levantam `RangeError` em vez de
+virarem `400 tenant.filter.invalid`. No máximo 10 filtros por requisição.
+
+Precisa da API Authyon de 2026-10-22 ou mais nova; contra uma anterior o `filter`
+é ignorado, o que aparece como página larga demais e não como erro.
+
+## Membros do tenant
+
+```ts
+const user = authyon.user(() => getCurrentUserAccessToken());
+await user.tenants.members.invite(tenantId, {
+  email: "pessoa@example.com",
+  roles: ["reader"],
+});
+await user.tenants.members.list(tenantId, { skip: 0, take: 25 });
+await user.tenants.members.remove(tenantId, userId);
+
+// Pelo plano administrativo, a listagem vem no envelope paginado de sempre
+// (`data`, `total`, `hasNext`), com `take` 50 por padrão e teto 100.
+const { data: membros, total } = await authyon.environment.tenants.members.list(tenantId);
+
+// Administração por máquina: adicione uma conta existente por ID.
+await authyon.environment.tenants.members.add(tenantId, userId, ["reader"]);
+await authyon.environment.tenants.members.remove(tenantId, userId);
+// Os métodos tenant(credentials).members.add/remove existentes continuam disponíveis.
+```
+
+Configure `envKey` para `user()`. `members.invite` associa um usuário já
+cadastrado no ambiente pelo e-mail; não cria conta e não envia link por e-mail.
+Para isso, use os convites abaixo.
+A API exige associação/permissões do usuário chamador. No browser, os métodos
+existentes `@authyon/auth` → `organization.members.invite/remove` continuam
+atendendo esse fluxo. Nunca importe `@authyon/server` no browser.
+
+## Convites de tenant (e-mail ou link)
+
+Convide um e-mail que talvez ainda não tenha conta — aceitar cria a conta, já com o
+e-mail confirmado. A resposta sempre traz o `acceptUrl` completo; `sendEmail: false`
+só gera o link para você enviar pelo seu canal.
+
+```ts
+// Pelo ambiente (escopo authyon:users:write; listar exige authyon:tenants:read).
+const invite = await authyon.environment.tenants.invites.create(tenantId, {
+  email: "pessoa@example.com",
+  roles: ["reader"],
+  sendEmail: false, // padrão: true
+  // Opcional: para onde mandar a pessoa depois de aceitar. Precisa estar
+  // cadastrado (match exato) nos redirect URIs do ambiente.
+  redirectUri: "https://app.example.com/bem-vindo",
+});
+invite.acceptUrl; // só aparece aqui — a API guarda apenas o hash do token
+
+await authyon.environment.tenants.invites.list(tenantId);
+await authyon.environment.tenants.invites.resend(tenantId, invite.id, { sendEmail: true });
+await authyon.environment.tenants.invites.revoke(tenantId, invite.id);
+
+// Pela credencial do tenant, ou agindo como o usuário (permissão tenants:members:invite).
+await authyon.tenant(credentials).invites.create({ email: "pessoa@example.com" });
+await authyon.user(token).tenants.invites.create(tenantId, { email: "pessoa@example.com" });
+
+// Página de aceite no seu backend: públicas, usam só o envKey.
+const preview = await authyon.environment.tenants.invites.preview(token);
+const accepted = await authyon.environment.tenants.invites.accept({
+  token,
+  password: preview.accountExists ? undefined : password,
+  // Opcional. Com metadata, a chamada vai para /env/tenant-invites/accept usando
+  // clientId/clientSecret (escopo authyon:users:write) — só o backend pode definir.
+  publicMetadata: { plano: "pro" },
+  privateMetadata: { crmId: "42" },
+  // customFields: { ... } — obsoleto, prefira os metadata acima.
+});
+if (accepted.redirectUri) redirect(accepted.redirectUri); // o redirect fica por sua conta
+```
+
+O link vale 7 dias e uma única vez. `resend` gera um link novo e invalida o anterior.
+Por padrão o link aponta para a página do Authyon; configure a _URL do convite para
+tenant_ nas configurações do ambiente para usar a sua (ela recebe `token` e `env`).
+Aceitar não faz login.
+
+## Redefinição de senha pelo seu próprio e-mail
+
+Para a sua aplicação disparar o e-mail de redefinição em vez do Authyon, emita o token no
+backend (escopo `authyon:users:password`) e entregue você mesmo:
+
+```ts
+const reset = await authyon.environment.users.issuePasswordReset({
+  email: "pessoa@example.com",
+  // Opcional: para onde mandar a pessoa depois de trocar a senha. Precisa estar
+  // cadastrado (match exato) nos redirect URIs do ambiente.
+  redirectUri: "https://app.example.com/login",
+  // sendEmail: true faria o Authyon enviar também; o padrão é false.
+});
+reset.token; // só aparece aqui — a API guarda apenas o hash
+reset.resetUrl; // o link que o e-mail do Authyon levaria
+reset.expiresAt; // 30 minutos
+
+// Página de redefinição no seu backend: públicas, usam só o envKey.
+const preview = await authyon.environment.users.validatePasswordReset(token); // não gasta o token
+const done = await authyon.environment.users.confirmPasswordReset(token, newPassword);
+if (done.redirectUri) redirect(done.redirectUri); // o redirect fica por sua conta
+```
+
+Quem tem o token consegue definir a senha: envie somente para o endereço da própria conta e
+não registre em log. Emitir um token novo invalida o anterior da mesma conta. Um endereço
+sem conta responde `404 user.not_found`; token desconhecido, usado ou expirado responde
+`401 user.password_reset.invalid`.
+
+## Compatibilidade e segurança do transporte
+
+As chamadas exigem os endpoints externos atuais da API e a migração
+`ClientCredentialMetadata` para metadados
+persistidos. O SDK não altera o banco nem publica uma versão automaticamente.
+
+O adaptador Fetch agora rejeita redirects para evitar reenviar tokens/segredos;
+configure a URL final HTTPS da API. Adaptadores HTTP personalizados devem manter
+essa política. Os logs internos omitem corpos/headers e ocultam tokens de
+convite presentes no caminho. A auditoria de operações permanece na API; o SDK
+não gera eventos duplicados ao consultar listagens de auditoria.