@autorix/express 0.1.0 → 0.1.1

package/README.md

@@ -34,21 +34,47 @@ yarn add @autorix/express @autorix/core @autorix/storage
 
 ```typescript
 import express from 'express';
-import { autorixExpress, authorize } from '@autorix/express';
-import { Autorix } from '@autorix/core';
+import { autorixExpress, authorize, autorixErrorHandler } from '@autorix/express';
+import { evaluateAll } from '@autorix/core';
 import { MemoryPolicyProvider } from '@autorix/storage';
 
 const app = express();
+app.use(express.json());
 
-// Initialize Autorix
+// Initialize policy provider
 const policyProvider = new MemoryPolicyProvider();
-const autorix = new Autorix(policyProvider);
 
-// Add the Autorix middleware
+// Create enforcer
+const enforcer = {
+  can: async (input: { action: string; context: any; resource?: unknown }) => {
+    // ✅ IMPORTANT: If your app allows unauthenticated requests, guard here
+    // to avoid storage/providers crashing when principal is null.
+    if (!input.context?.principal) {
+      return { allowed: false, reason: 'Unauthenticated' };
+    }
+
+    const policies = await policyProvider.getPolicies({
+      scope: input.context.tenantId || 'default',
+      principal: input.context.principal,
+      roleIds: input.context.principal?.roles,
+    });
+
+    const result = evaluateAll({
+      policies: policies.map(p => p.document),
+      action: input.action,
+      resource: input.resource,
+      context: input.context,
+    });
+
+    return { allowed: result.allowed, reason: result.reason };
+  }
+};
+
+// Add the Autorix middleware (must be registered before routes)
 app.use(autorixExpress({
-  enforcer: autorix,
+  enforcer,
   getPrincipal: async (req) => {
-    // Extract user from your auth middleware
+    // Extract user from your auth middleware (e.g., JWT/Passport/session)
     return req.user ? { id: req.user.id, roles: req.user.roles } : null;
   },
   getTenant: async (req) => {
@@ -58,20 +84,23 @@ app.use(autorixExpress({
 }));
 
 // Protect routes with authorize middleware
-app.get('/admin/users',
-  authorize('user:list'),
+app.get(
+  '/admin/users',
+  authorize('user:list', { requireAuth: true }),
   (req, res) => {
     res.json({ message: 'Authorized!' });
   }
 );
 
-app.delete('/posts/:id',
+app.delete(
+  '/posts/:id',
   authorize({
     action: 'post:delete',
+    requireAuth: true,
     resource: {
       type: 'post',
       idFrom: (req) => req.params.id,
-      loader: async (id) => await db.posts.findById(id)
+      loader: async (id) => await db.posts.findById(id),
     }
   }),
   (req, res) => {
@@ -79,6 +108,10 @@ app.delete('/posts/:id',
   }
 );
 
+// ✅ IMPORTANT: Register Autorix error handler at the end
+// so authorization errors return clean HTTP responses (401/403) instead of stack traces.
+app.use(autorixErrorHandler());
+
 app.listen(3000);
 ```
 
@@ -359,31 +392,71 @@ app.use(autorixExpress({
 }));
 ```
 
+---
+
 ## 🔧 Error Handling
 
-The package provides custom error classes:
+`@autorix/express` provides an official error handler middleware to ensure authorization errors
+are returned as clean HTTP responses (`401`, `403`) instead of unhandled stack traces.
 
-```typescript
-import {
-  AutorixForbiddenError,
-  AutorixUnauthenticatedError,
-  AutorixMissingMiddlewareError
-} from '@autorix/express';
+### ✅ Recommended (default)
+
+```ts
+import { autorixErrorHandler } from '@autorix/express';
+
+// Register at the end (after routes)
+app.use(autorixErrorHandler());
+```
+
+This middleware automatically handles all `AutorixHttpError` instances and formats them as JSON responses.
+
+**Always register this middleware after all routes.**
+
+---
+
+### 🧩 Custom error handling (optional)
+
+If you want full control over the error response format or logging, you can implement
+your own handler using the exported error classes.
+
+```ts
+import { AutorixHttpError } from '@autorix/express';
 
 app.use((err, req, res, next) => {
-  if (err instanceof AutorixForbiddenError) {
-    return res.status(403).json({ error: 'Forbidden' });
-  }
-  if (err instanceof AutorixUnauthenticatedError) {
-    return res.status(401).json({ error: 'Authentication required' });
-  }
-  if (err instanceof AutorixMissingMiddlewareError) {
-    return res.status(500).json({ error: 'Autorix middleware not configured' });
+  if (err instanceof AutorixHttpError) {
+    return res.status(err.statusCode).json({
+      error: {
+        code: err.code,
+        message: err.message
+      }
+    });
   }
+
   next(err);
 });
 ```
 
+---
+
+### ⚠️ Important notes
+
+* If no error handler is registered, Express will print authorization errors as stack traces.
+* Using `autorixErrorHandler()` is strongly recommended to avoid this behavior.
+* For protected routes, use `requireAuth: true` in `authorize()` to return a clean `401 Unauthenticated`
+  response when no principal is present.
+
+---
+
+## 🧠 Why is this required?
+
+Express does not support automatic global error handling inside normal middleware.
+For this reason, error handlers must be registered explicitly at the application level.
+
+This design follows the same pattern used by mature Express libraries
+(e.g. `passport`, `express-rate-limit`, `celebrate`).
+
+---
+
 ## 🔗 Related Packages
 
 - [@autorix/core](../core) - Core policy evaluation engine

package/dist/index.cjs

@@ -26,6 +26,7 @@ __export(index_exports, {
   AutorixMissingMiddlewareError: () => AutorixMissingMiddlewareError,
   AutorixUnauthenticatedError: () => AutorixUnauthenticatedError,
   authorize: () => authorize,
+  autorixErrorHandler: () => autorixErrorHandler,
   autorixExpress: () => autorixExpress,
   buildRequestContext: () => buildRequestContext,
   resolvePrincipal: () => resolvePrincipal,
@@ -199,6 +200,42 @@ function authorize(actionOrConfig, cfg) {
   }, "authorizeMiddleware");
 }
 __name(authorize, "authorize");
+
+// src/middleware/autorixErrorHandler.ts
+function autorixErrorHandler(options = {}) {
+  const exposeStack = options.exposeStack ?? false;
+  const format = options.format ?? "json";
+  return (err, _req, res, next) => {
+    if (res.headersSent) return next(err);
+    if (err instanceof AutorixHttpError) {
+      if (format === "problem+json") {
+        return res.status(err.statusCode).type("application/problem+json").json({
+          type: `https://autorix.dev/errors/${err.code}`,
+          title: err.code,
+          status: err.statusCode,
+          detail: err.message
+        });
+      }
+      return res.status(err.statusCode).json({
+        error: {
+          code: err.code,
+          message: err.message
+        }
+      });
+    }
+    const status = err?.statusCode ?? err?.status ?? 500;
+    return res.status(status).json({
+      error: {
+        code: "INTERNAL_ERROR",
+        message: status === 500 ? "Internal Error" : err?.message ?? "Error",
+        ...exposeStack ? {
+          stack: String(err?.stack ?? "")
+        } : {}
+      }
+    });
+  };
+}
+__name(autorixErrorHandler, "autorixErrorHandler");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AutorixForbiddenError,
@@ -206,6 +243,7 @@ __name(authorize, "authorize");
   AutorixMissingMiddlewareError,
   AutorixUnauthenticatedError,
   authorize,
+  autorixErrorHandler,
   autorixExpress,
   buildRequestContext,
   resolvePrincipal,

package/dist/index.d.cts

@@ -95,4 +95,10 @@ declare class AutorixMissingMiddlewareError extends AutorixHttpError {
     constructor(details?: unknown);
 }
 
-export { type AutorixErrorCode, type AutorixExpressOptions, AutorixForbiddenError, AutorixHttpError, AutorixMissingMiddlewareError, type AutorixRequestContext, AutorixUnauthenticatedError, type GetContextFn, type GetPrincipalFn, type Principal, type ResourceSpec, authorize, autorixExpress, buildRequestContext, resolvePrincipal, resolveResource };
+type AutorixErrorHandlerOptions = {
+    exposeStack?: boolean;
+    format?: "json" | "problem+json";
+};
+declare function autorixErrorHandler(options?: AutorixErrorHandlerOptions): (err: any, _req: Request, res: Response, next: NextFunction) => void | Response<any, Record<string, any>>;
+
+export { type AutorixErrorCode, type AutorixErrorHandlerOptions, type AutorixExpressOptions, AutorixForbiddenError, AutorixHttpError, AutorixMissingMiddlewareError, type AutorixRequestContext, AutorixUnauthenticatedError, type GetContextFn, type GetPrincipalFn, type Principal, type ResourceSpec, authorize, autorixErrorHandler, autorixExpress, buildRequestContext, resolvePrincipal, resolveResource };

package/dist/index.d.ts

@@ -95,4 +95,10 @@ declare class AutorixMissingMiddlewareError extends AutorixHttpError {
     constructor(details?: unknown);
 }
 
-export { type AutorixErrorCode, type AutorixExpressOptions, AutorixForbiddenError, AutorixHttpError, AutorixMissingMiddlewareError, type AutorixRequestContext, AutorixUnauthenticatedError, type GetContextFn, type GetPrincipalFn, type Principal, type ResourceSpec, authorize, autorixExpress, buildRequestContext, resolvePrincipal, resolveResource };
+type AutorixErrorHandlerOptions = {
+    exposeStack?: boolean;
+    format?: "json" | "problem+json";
+};
+declare function autorixErrorHandler(options?: AutorixErrorHandlerOptions): (err: any, _req: Request, res: Response, next: NextFunction) => void | Response<any, Record<string, any>>;
+
+export { type AutorixErrorCode, type AutorixErrorHandlerOptions, type AutorixExpressOptions, AutorixForbiddenError, AutorixHttpError, AutorixMissingMiddlewareError, type AutorixRequestContext, AutorixUnauthenticatedError, type GetContextFn, type GetPrincipalFn, type Principal, type ResourceSpec, authorize, autorixErrorHandler, autorixExpress, buildRequestContext, resolvePrincipal, resolveResource };

package/dist/index.js

@@ -167,12 +167,49 @@ function authorize(actionOrConfig, cfg) {
   }, "authorizeMiddleware");
 }
 __name(authorize, "authorize");
+
+// src/middleware/autorixErrorHandler.ts
+function autorixErrorHandler(options = {}) {
+  const exposeStack = options.exposeStack ?? false;
+  const format = options.format ?? "json";
+  return (err, _req, res, next) => {
+    if (res.headersSent) return next(err);
+    if (err instanceof AutorixHttpError) {
+      if (format === "problem+json") {
+        return res.status(err.statusCode).type("application/problem+json").json({
+          type: `https://autorix.dev/errors/${err.code}`,
+          title: err.code,
+          status: err.statusCode,
+          detail: err.message
+        });
+      }
+      return res.status(err.statusCode).json({
+        error: {
+          code: err.code,
+          message: err.message
+        }
+      });
+    }
+    const status = err?.statusCode ?? err?.status ?? 500;
+    return res.status(status).json({
+      error: {
+        code: "INTERNAL_ERROR",
+        message: status === 500 ? "Internal Error" : err?.message ?? "Error",
+        ...exposeStack ? {
+          stack: String(err?.stack ?? "")
+        } : {}
+      }
+    });
+  };
+}
+__name(autorixErrorHandler, "autorixErrorHandler");
 export {
   AutorixForbiddenError,
   AutorixHttpError,
   AutorixMissingMiddlewareError,
   AutorixUnauthenticatedError,
   authorize,
+  autorixErrorHandler,
   autorixExpress,
   buildRequestContext,
   resolvePrincipal,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autorix/express",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Express.js integration for Autorix policy-based authorization (RBAC + ABAC)",
   "keywords": [
     "authorization",
@@ -17,7 +17,7 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/chechooxd/autorix.git",
-    "directory": "packages/autorix-express"
+    "directory": "packages/express"
   },
   "bugs": {
     "url": "https://github.com/chechooxd/autorix/issues"