@authyon/server 0.2.0-beta.0 → 0.2.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MutualPay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,6 +2,56 @@
 
 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.1
+```
+
+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.
+
+## 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
@@ -35,7 +85,7 @@ const { active, sub } = await authyon.introspect(token); // leve
 const { user, organization } = await authyon.validate(token); // recomendado — cross-checa revogação
 ```
 
-Veja [`examples/token-verification.ts`](./examples/token-verification.ts) para um middleware completo.
+Veja [`examples/tokenVerification.ts`](./examples/tokenVerification.ts) para um middleware completo.
 
 ## Administração de ambiente (`environment.*`)
 
@@ -52,10 +102,79 @@ await authyon.environment.roles.create({ name: "support", permissions: ["tickets
 await authyon.environment.audit.list({ take: 50 });
 ```
 
-Veja [`examples/organization-membership.ts`](./examples/organization-membership.ts) para o fluxo completo, incluindo as rotas de backend que o `@authyon/auth` chamaria.
+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`.
 
+## 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" });
+```
+
 ## 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`:

package/dist/browser.cjs

@@ -0,0 +1,21 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/browser.ts
+var browser_exports = {};
+module.exports = __toCommonJS(browser_exports);
+throw new Error(
+  "@authyon/server cannot run in a browser. Use @authyon/auth in frontend code and keep client secrets on the server."
+);

package/dist/browser.d.cts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/browser.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/browser.js

@@ -0,0 +1,4 @@
+// src/browser.ts
+throw new Error(
+  "@authyon/server cannot run in a browser. Use @authyon/auth in frontend code and keep client secrets on the server."
+);