@autorix/express 0.1.0 → 0.1.2

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; resource: string; context: any }) => {
+    // ✅ 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,  // ← String for matching (e.g., 'post/123')
+      ctx: input.context,        // ← Contains resource object in ctx.resource
+    });
+
+    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);
 ```
 
@@ -176,6 +209,49 @@ authorize({
 })
 ```
 
+## 🔑 Understanding Resources
+
+Autorix uses **two separate concepts** for resources:
+
+1. **Resource String** (for pattern matching in policies)
+   - Format: `type/id` or `type/*`
+   - Used in policy `Resource` field
+   - Example: `'post/123'`, `'document/*'`
+
+2. **Resource Object** (for attribute-based conditions)
+   - Contains resource properties/attributes
+   - Used in policy `Condition` blocks
+   - Example: `{ type: 'post', id: '123', authorId: 'u1' }`
+
+**How they work together:**
+
+```typescript
+// Policy matches by string pattern
+Statement: [{
+  Effect: 'Allow',
+  Action: ['post:delete'],
+  Resource: 'post/*',  // ← Matches 'post/123'
+  Condition: {
+    StringEquals: {
+      'resource.authorId': '${principal.id}'  // ← Uses resource object
+    }
+  }
+}]
+
+// Middleware automatically handles both
+authorize({
+  action: 'post:delete',
+  resource: {
+    type: 'post',
+    idFrom: (req) => req.params.id,  // → Builds string: 'post/123'
+    loader: async (id) => {
+      const post = await db.posts.findById(id);
+      return { authorId: post.authorId };  // → Object for conditions
+    }
+  }
+})
+```
+
 ## 🎯 Usage Examples
 
 ### Role-Based Access Control (RBAC)
@@ -220,16 +296,16 @@ app.get('/admin/settings',
 ### Attribute-Based Access Control (ABAC)
 
 ```typescript
-// Policy with conditions
+// Policy with conditions - checks resource attributes
 await provider.setPolicy('owner-only', {
   Version: '2024-01-01',
   Statement: [{
     Effect: 'Allow',
     Action: ['post:update', 'post:delete'],
-    Resource: ['post/*'],
+    Resource: ['post/*'],  // ← Matches 'post/123' string pattern
     Condition: {
       StringEquals: {
-        'principal.id': '${resource.ownerId}'
+        'resource.authorId': '${principal.id}'  // ← Checks resource object property
       }
     }
   }]
@@ -244,12 +320,16 @@ app.put('/posts/:id',
       idFrom: (req) => req.params.id,
       loader: async (id) => {
         const post = await db.posts.findById(id);
-        return { ...post, ownerId: post.userId };
+        // Return object with properties for conditions
+        return { 
+          authorId: post.authorId,  // ← This becomes resource.authorId in conditions
+          status: post.status 
+        };
       }
     }
   }),
   (req, res) => {
-    // Only post owner can update
+    // Only post author can update
     res.json({ message: 'Post updated!' });
   }
 );
@@ -359,31 +439,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,
@@ -124,17 +125,31 @@ function autorixExpress(opts) {
       const context = await buildRequestContext(req, opts);
       req.autorix = {
         context,
-        can: /* @__PURE__ */ __name(async (action, resource, ctxExtra) => {
+        can: /* @__PURE__ */ __name(async (action, resourceObj, ctxExtra) => {
+          let resourceString = "*";
+          if (typeof resourceObj === "object" && resourceObj && "type" in resourceObj) {
+            const resType = resourceObj.type;
+            const resId = resourceObj.id;
+            resourceString = resId ? `${resType}/${resId}` : `${resType}/*`;
+          } else if (typeof resourceObj === "string") {
+            resourceString = resourceObj;
+          } else if (resourceObj === void 0) {
+            const parts = action.split(":");
+            if (parts.length > 1) {
+              resourceString = `${parts[0]}/*`;
+            }
+          }
           const decision = await opts.enforcer.can({
             action,
+            resource: resourceString,
             context: {
               ...context,
+              resource: resourceObj,
               attributes: {
                 ...context.attributes ?? {},
                 ...ctxExtra ?? {}
               }
-            },
-            resource
+            }
           });
           opts.onDecision?.({
             ...decision,
@@ -160,9 +175,16 @@ async function resolveResource(spec, req) {
   if (typeof spec === "string") return {
     type: spec
   };
-  if ("loader" in spec) {
+  if ("loader" in spec && typeof spec.loader === "function" && typeof spec.idFrom === "function") {
     const id = spec.idFrom(req);
     const data = await spec.loader(id, req);
+    if (data && typeof data === "object" && !Array.isArray(data)) {
+      return {
+        type: spec.type,
+        id,
+        ...data
+      };
+    }
     return {
       type: spec.type,
       id,
@@ -199,6 +221,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 +264,7 @@ __name(authorize, "authorize");
   AutorixMissingMiddlewareError,
   AutorixUnauthenticatedError,
   authorize,
+  autorixErrorHandler,
   autorixExpress,
   buildRequestContext,
   resolvePrincipal,

package/dist/index.d.cts

@@ -17,19 +17,19 @@ type AutorixRequestContext = {
 type ResourceSpec = string | {
     type: string;
     id?: string;
-    data?: unknown;
+    [key: string]: unknown;
 } | {
     type: string;
     idFrom: (req: Request) => string;
-    loader: (id: string, req: Request) => Promise<unknown>;
+    loader: (id: string, req: Request) => Promise<Record<string, unknown>>;
 };
 type GetContextFn = (req: Request) => Partial<AutorixRequestContext> | Promise<Partial<AutorixRequestContext>>;
 type AutorixExpressOptions = {
     enforcer: {
         can: (input: {
             action: string;
+            resource: string;
             context: AutorixRequestContext;
-            resource?: unknown;
         }) => Promise<{
             allowed: boolean;
             reason?: string;
@@ -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

@@ -17,19 +17,19 @@ type AutorixRequestContext = {
 type ResourceSpec = string | {
     type: string;
     id?: string;
-    data?: unknown;
+    [key: string]: unknown;
 } | {
     type: string;
     idFrom: (req: Request) => string;
-    loader: (id: string, req: Request) => Promise<unknown>;
+    loader: (id: string, req: Request) => Promise<Record<string, unknown>>;
 };
 type GetContextFn = (req: Request) => Partial<AutorixRequestContext> | Promise<Partial<AutorixRequestContext>>;
 type AutorixExpressOptions = {
     enforcer: {
         can: (input: {
             action: string;
+            resource: string;
             context: AutorixRequestContext;
-            resource?: unknown;
         }) => Promise<{
             allowed: boolean;
             reason?: string;
@@ -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

@@ -92,17 +92,31 @@ function autorixExpress(opts) {
       const context = await buildRequestContext(req, opts);
       req.autorix = {
         context,
-        can: /* @__PURE__ */ __name(async (action, resource, ctxExtra) => {
+        can: /* @__PURE__ */ __name(async (action, resourceObj, ctxExtra) => {
+          let resourceString = "*";
+          if (typeof resourceObj === "object" && resourceObj && "type" in resourceObj) {
+            const resType = resourceObj.type;
+            const resId = resourceObj.id;
+            resourceString = resId ? `${resType}/${resId}` : `${resType}/*`;
+          } else if (typeof resourceObj === "string") {
+            resourceString = resourceObj;
+          } else if (resourceObj === void 0) {
+            const parts = action.split(":");
+            if (parts.length > 1) {
+              resourceString = `${parts[0]}/*`;
+            }
+          }
           const decision = await opts.enforcer.can({
             action,
+            resource: resourceString,
             context: {
               ...context,
+              resource: resourceObj,
               attributes: {
                 ...context.attributes ?? {},
                 ...ctxExtra ?? {}
               }
-            },
-            resource
+            }
           });
           opts.onDecision?.({
             ...decision,
@@ -128,9 +142,16 @@ async function resolveResource(spec, req) {
   if (typeof spec === "string") return {
     type: spec
   };
-  if ("loader" in spec) {
+  if ("loader" in spec && typeof spec.loader === "function" && typeof spec.idFrom === "function") {
     const id = spec.idFrom(req);
     const data = await spec.loader(id, req);
+    if (data && typeof data === "object" && !Array.isArray(data)) {
+      return {
+        type: spec.type,
+        id,
+        ...data
+      };
+    }
     return {
       type: spec.type,
       id,
@@ -167,12 +188,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.2",
   "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"
@@ -55,7 +55,8 @@
     "@types/express": "^5.0.6",
     "@types/supertest": "^6.0.3",
     "express": "^5.2.1",
-    "supertest": "^7.2.2"
+    "supertest": "^7.2.2",
+    "@autorix/storage": "^0.1.0"
   },
   "engines": {
     "node": ">=18"