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

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

@@ -8,6 +8,10 @@ Node.js client for the Eduzz Miau authentication and authorization service. Incl
 npm install @eduzz/miau-client
 ```
 
+## Requirements
+
+- Node.js >= 18
+
 ## Usage
 
 ```typescript
@@ -43,7 +47,7 @@ console.log(JSON.stringify(data, null, 2));
 
 ## Express Middleware
 
-Validates incoming requests using Miau tokens and checks permissions automatically.
+The client includes an Express middleware that authenticates incoming requests using Miau tokens and checks permissions automatically.
 
 ```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.miauApplication - { id: '...', name: '...' }
   // req.miauMetadata - permission metadata
   res.json({ app: req.miauApplication });
 });
 ```
 
-With custom request augmentation:
-
-```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();
-    },
-  })
-);
-```
+### Fallback handler
 
-## Fastify Hook
+The middleware triggers the fallback when the incoming token is missing or not a valid Miau token (HTTP 400 errors). This lets you handle alternative authentication schemes on the same routes -- for example, accepting Basic Auth for legacy clients while still supporting Miau tokens.
 
 ```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: 'No credentials provided' });
+    return;
+  }
 
-### `new MiauClient({ apiUrl, appSecret })`
+  const [username, password] = Buffer.from(authHeader.slice(6), 'base64').toString().split(':');
 
-Creates a new client instance.
+  // Validate credentials against your own logic
+  if (!validateCredentials(username, password)) {
+    res.status(401).json({ error: 'Unauthorized', message: 'Invalid credentials' });
+    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) {
+    // Authenticated via Miau token
+    res.json({ auth: 'miau', application: req.miauApplication });
+    return;
+  }
 
-### `client.getTokenData(): Promise<MiauClientToken>`
+  // Authenticated via Basic Auth fallback
+  res.json({ auth: 'basic', username: req.username });
+});
+```
 
-Returns the decoded token payload.
+## Fastify Hook
 
-### `client.getEnvironment(): SecretEnv`
+The client also provides a Fastify `preHandler` hook with the same authentication flow.
 
-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 - permission metadata
+  return { app: request.miauApplication };
+});
+```
 
-Verifies a JWT token using the provided public key (RS256).
+### Fallback handler
 
-### `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: 'No credentials provided' });
+    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: 'Invalid credentials' });
+    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.15",
   "description": "Eduzz Miau Client",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",