@eduzz/miau-client 1.4.3 → 1.4.4-rc.16

package/.turbo/turbo-build$colon$types.log

@@ -1,4 +1,4 @@
 
-> @eduzz/miau-client@1.4.3 build:types /home/runner/work/eduzz-miau/eduzz-miau/clients/node-client
+> @eduzz/miau-client@1.4.4 build:types /home/runner/work/eduzz-miau/eduzz-miau/clients/node-client
 > tsc --emitDeclarationOnly --outDir dist
 

package/README.md

@@ -1,14 +1,18 @@
 # @eduzz/miau-client
 
-Node.js client for the Eduzz Miau authentication and authorization service. Includes Express and Fastify middleware for automatic request validation.
+Client Node.js para o serviço de autenticação e autorização Eduzz Miau. Inclui middleware para Express e Fastify com validação automática de requisições.
 
-## Installation
+## Instalação
 
 ```bash
 npm install @eduzz/miau-client
 ```
 
-## Usage
+## Requisitos
+
+- Node.js >= 18
+
+## Uso
 
 ```typescript
 import { MiauClient } from '@eduzz/miau-client';
@@ -21,7 +25,7 @@ const client = new MiauClient({
 const token = await client.getToken();
 ```
 
-## Example
+## Exemplo
 
 ```typescript
 import { MiauClient } from '@eduzz/miau-client';
@@ -41,9 +45,9 @@ const data = await response.json();
 console.log(JSON.stringify(data, null, 2));
 ```
 
-## Express Middleware
+## Middleware Express
 
-Validates incoming requests using Miau tokens and checks permissions automatically.
+O client inclui um middleware Express que autentica requisições usando tokens Miau e verifica permissões automaticamente.
 
 ```typescript
 import express from 'express';
@@ -55,89 +59,103 @@ const miau = new MiauClient({ apiUrl: MIAU_API_URL, appSecret: MIAU_APP_SECRET }
 app.use(miau.middleware());
 
 app.get('/your/endpoint', (req, res) => {
-  // req.miauApplication - the authenticated application
-  // req.miauMetadata - permission metadata
+  // req.miauApplication - { id: '...', name: '...' }
+  // req.miauMetadata - metadata de permissão
   res.json({ app: req.miauApplication });
 });
 ```
 
-With custom request augmentation:
+### Handler de fallback
 
-```typescript
-app.use(
-  miau.middleware({
-    requestAugmentation: ({ req, app, meta }) => {
-      // Attach custom data to the request
-    },
-    fallbackMiddleware: (req, res, next) => {
-      // Called when token is missing/malformed (400 errors)
-      next();
-    },
-  })
-);
-```
-
-## Fastify Hook
+O middleware aciona o fallback quando o token está ausente ou não é um token Miau válido (erros HTTP 400). Isso permite lidar com esquemas de autenticação alternativos nas mesmas rotas -- por exemplo, aceitar Basic Auth para clients legados enquanto ainda suporta tokens Miau.
 
 ```typescript
-import Fastify from 'fastify';
+import express, { type Request, type Response, type NextFunction } from 'express';
 import { MiauClient } from '@eduzz/miau-client';
 
-const app = Fastify();
+const app = express();
 const miau = new MiauClient({ apiUrl: MIAU_API_URL, appSecret: MIAU_APP_SECRET });
 
-app.addHook('preHandler', miau.hook());
-
-app.get('/your/endpoint', async (request, reply) => {
-  // request.miauApplication - the authenticated application
-  // request.miauMetadata - permission metadata
-  return { app: request.miauApplication };
-});
-```
+const basicAuthFallback = (req: Request, res: Response, next: NextFunction) => {
+  const authHeader = req.headers.authorization || '';
 
-## API
+  if (!authHeader.startsWith('Basic ')) {
+    res.status(401).json({ error: 'Unauthorized', message: 'Credenciais não fornecidas' });
+    return;
+  }
 
-### `new MiauClient({ apiUrl, appSecret })`
+  const [username, password] = Buffer.from(authHeader.slice(6), 'base64').toString().split(':');
 
-Creates a new client instance.
+  // Valide as credenciais com sua própria lógica
+  if (!validateCredentials(username, password)) {
+    res.status(401).json({ error: 'Unauthorized', message: 'Credenciais inválidas' });
+    return;
+  }
 
-| Parameter   | Type     | Description                  |
-|------------|----------|------------------------------|
-| `apiUrl`   | `string` | Miau API base URL            |
-| `appSecret`| `string` | Application secret from Miau |
+  req.username = username;
+  next();
+};
 
-### `client.getToken(): Promise<string>`
+app.use('/legacy-route', miau.middleware({ fallbackMiddleware: basicAuthFallback }));
 
-Returns a valid JWT access token. Tokens are cached in memory and automatically refreshed when they are within 60 seconds of expiration.
+app.get('/legacy-route', (req, res) => {
+  if (req.miauApplication) {
+    // Autenticado via token Miau
+    res.json({ auth: 'miau', application: req.miauApplication });
+    return;
+  }
 
-### `client.getTokenData(): Promise<MiauClientToken>`
+  // Autenticado via fallback Basic Auth
+  res.json({ auth: 'basic', username: req.username });
+});
+```
 
-Returns the decoded token payload.
+## Hook Fastify
 
-### `client.getEnvironment(): SecretEnv`
+O client também oferece um hook `preHandler` para Fastify com o mesmo fluxo de autenticação.
 
-Returns the environment extracted from the app secret (e.g. `production`, `staging`).
+```typescript
+import Fastify from 'fastify';
+import { MiauClient } from '@eduzz/miau-client';
 
-### `client.getPublicKey(kid: string): Promise<string>`
+const app = Fastify();
+const miau = new MiauClient({ apiUrl: MIAU_API_URL, appSecret: MIAU_APP_SECRET });
 
-Fetches and caches the public key for the given key ID from the JWKS endpoint.
+app.addHook('preHandler', miau.hook());
 
-### `client.verify(token: string, publicKey: string): Promise<MiauClientToken>`
+app.get('/your/endpoint', async (request, reply) => {
+  // request.miauApplication - { id: '...', name: '...' }
+  // request.miauMetadata - metadata de permissão
+  return { app: request.miauApplication };
+});
+```
 
-Verifies a JWT token using the provided public key (RS256).
+### Handler de fallback
 
-### `client.hasPermission(sourceAppId: string, resource: Resource): Promise<HasPermissionResponse>`
+```typescript
+import Fastify from 'fastify';
+import { MiauClient } from '@eduzz/miau-client';
 
-Checks if a source application has permission to access a given resource.
+const app = Fastify();
+const miau = new MiauClient({ apiUrl: MIAU_API_URL, appSecret: MIAU_APP_SECRET });
 
-### `client.middleware(config?): RequestHandler`
+const basicAuthFallback = async (request: FastifyRequest, reply: FastifyReply) => {
+  const authHeader = request.headers.authorization || '';
 
-Returns an Express middleware that authenticates requests and checks permissions.
+  if (!authHeader.startsWith('Basic ')) {
+    reply.code(401).send({ error: 'Unauthorized', message: 'Credenciais não fornecidas' });
+    return;
+  }
 
-### `client.hook(config?): FastifyHook`
+  const [username, password] = Buffer.from(authHeader.slice(6), 'base64').toString().split(':');
 
-Returns a Fastify `preHandler` hook that authenticates requests and checks permissions.
+  if (!validateCredentials(username, password)) {
+    reply.code(401).send({ error: 'Unauthorized', message: 'Credenciais inválidas' });
+    return;
+  }
 
-## Requirements
+  request.username = username;
+};
 
-- Node.js >= 18
+app.addHook('preHandler', miau.hook({ fallbackMiddleware: basicAuthFallback }));
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eduzz/miau-client",
-  "version": "1.4.3",
+  "version": "1.4.4-rc.16",
   "description": "Eduzz Miau Client",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",