@simtlix/simfinity-js 2.3.4 → 2.4.1

package/README.md

@@ -20,6 +20,13 @@ A powerful Node.js framework that automatically generates GraphQL schemas from y
   - [Adding Middlewares](#adding-middlewares)
   - [Middleware Parameters](#middleware-parameters)
   - [Common Use Cases](#common-use-cases)
+- [Authorization](#-authorization)
+  - [Quick Start](#quick-start-1)
+  - [Permission Schema](#permission-schema)
+  - [Rule Helpers](#rule-helpers)
+  - [Policy Expressions (JSON AST)](#policy-expressions-json-ast)
+  - [Integration with GraphQL Yoga / Envelop](#integration-with-graphql-yoga--envelop)
+  - [Legacy: Integration with graphql-middleware](#legacy-integration-with-graphql-middleware)
 - [Relationships](#-relationships)
   - [Defining Relationships](#defining-relationships)
   - [Auto-Generated Resolve Methods](#auto-generated-resolve-methods)
@@ -69,6 +76,7 @@ A powerful Node.js framework that automatically generates GraphQL schemas from y
 - **Lifecycle Hooks**: Controller methods for granular control over operations
 - **Custom Validation**: Field-level and type-level custom validations
 - **Relationship Management**: Support for embedded and referenced relationships
+- **Authorization**: Production-grade GraphQL authorization with RBAC/ABAC, function-based rules, declarative policy expressions, and native Envelop/Yoga plugin support
 
 ## 📦 Installation
 
@@ -622,6 +630,392 @@ simfinity.use((params, next) => {
 5. **Performance consideration**: Middlewares run on every operation, keep them lightweight
 6. **Use context wisely**: Store request-specific data in the GraphQL context object
 
+## 🔐 Authorization
+
+Simfinity.js provides production-grade centralized GraphQL authorization supporting RBAC/ABAC, function-based rules, declarative policy expressions (JSON AST), wildcard permissions, and configurable default policies. It ships as a native Envelop plugin for GraphQL Yoga (recommended) and also supports the legacy graphql-middleware approach.
+
+### Quick Start
+
+```javascript
+const { auth } = require('@simtlix/simfinity-js');
+const { createYoga } = require('graphql-yoga');
+
+const { createAuthPlugin, requireAuth, requireRole } = auth;
+
+// Define your permission schema
+const permissions = {
+  Query: {
+    users: requireAuth(),
+    adminDashboard: requireRole('ADMIN'),
+  },
+  Mutation: {
+    publishPost: requireRole('EDITOR'),
+  },
+  User: {
+    '*': requireAuth(),           // Wildcard: all fields require auth
+    email: requireRole('ADMIN'),  // Override: email requires ADMIN role
+  },
+  Post: {
+    '*': requireAuth(),
+    content: async (post, _args, ctx) => {
+      // Custom logic: allow if published OR if author
+      if (post.published) return true;
+      if (post.authorId === ctx.user?.id) return true;
+      return false;
+    },
+  },
+};
+
+// Create the Envelop auth plugin and pass it to your server
+const authPlugin = createAuthPlugin(permissions, { defaultPolicy: 'DENY' });
+const yoga = createYoga({ schema, plugins: [authPlugin] });
+```
+
+### Permission Schema
+
+The permission schema defines authorization rules per type and field:
+
+```javascript
+const permissions = {
+  // Operation types (Query, Mutation, Subscription)
+  Query: {
+    fieldName: ruleOrRules,
+  },
+  
+  // Object types
+  TypeName: {
+    '*': wildcardRule,      // Applies to all fields unless overridden
+    fieldName: specificRule, // Overrides wildcard for this field
+  },
+};
+```
+
+**Resolution Order:**
+1. Check exact field rule: `permissions[TypeName][fieldName]`
+2. Fallback to wildcard: `permissions[TypeName]['*']`
+3. Apply default policy (ALLOW or DENY)
+
+**Rule Types:**
+- **Function**: `(parent, args, ctx, info) => boolean | void | Promise<boolean | void>`
+- **Array of functions**: All rules must pass (AND logic)
+- **Policy expression**: JSON AST object (see below)
+
+**Rule Semantics:**
+- `return true` or `return void` → allow
+- `return false` → deny
+- `throw Error` → deny with error
+
+### Rule Helpers
+
+Simfinity.js provides reusable rule builders:
+
+```javascript
+const { auth } = require('@simtlix/simfinity-js');
+
+const {
+  resolvePath,       // Utility to resolve dotted paths in objects
+  requireAuth,       // Requires ctx.user to exist
+  requireRole,       // Requires specific role(s)
+  requirePermission, // Requires specific permission(s)
+  composeRules,      // Combine rules (AND logic)
+  anyRule,           // Combine rules (OR logic)
+  isOwner,           // Check resource ownership
+  allow,             // Always allow
+  deny,              // Always deny
+  createRule,        // Create custom rule
+} = auth;
+```
+
+#### requireAuth(userPath?)
+
+Requires the user to be authenticated. Supports custom user paths in context:
+
+```javascript
+const permissions = {
+  Query: {
+    // Default: checks ctx.user
+    me: requireAuth(),
+    
+    // Custom path: checks ctx.auth.currentUser
+    profile: requireAuth('auth.currentUser'),
+    
+    // Deep path: checks ctx.session.data.user
+    settings: requireAuth('session.data.user'),
+  },
+};
+```
+
+#### requireRole(role, options?)
+
+Requires the user to have a specific role. Supports custom paths:
+
+```javascript
+const permissions = {
+  Query: {
+    // Default: checks ctx.user.role
+    adminDashboard: requireRole('ADMIN'),
+    modTools: requireRole(['ADMIN', 'MODERATOR']), // Any of these roles
+    
+    // Custom paths: checks ctx.auth.user.profile.role
+    superAdmin: requireRole('SUPER_ADMIN', { 
+      userPath: 'auth.user', 
+      rolePath: 'profile.role',
+    }),
+  },
+};
+```
+
+#### requirePermission(permission, options?)
+
+Requires the user to have specific permission(s). Supports custom paths:
+
+```javascript
+const permissions = {
+  Mutation: {
+    // Default: checks ctx.user.permissions
+    deletePost: requirePermission('posts:delete'),
+    manageUsers: requirePermission(['users:read', 'users:write']), // All required
+    
+    // Custom paths: checks ctx.session.user.access.grants
+    admin: requirePermission('admin:all', {
+      userPath: 'session.user',
+      permissionsPath: 'access.grants',
+    }),
+  },
+};
+```
+
+#### composeRules(...rules)
+
+Combines multiple rules with AND logic (all must pass):
+
+```javascript
+const permissions = {
+  Mutation: {
+    updatePost: composeRules(
+      requireAuth(),
+      requireRole('EDITOR'),
+      async (post, args, ctx) => post.authorId === ctx.user.id,
+    ),
+  },
+};
+```
+
+#### anyRule(...rules)
+
+Combines multiple rules with OR logic (any must pass):
+
+```javascript
+const permissions = {
+  Post: {
+    content: anyRule(
+      requireRole('ADMIN'),
+      async (post, args, ctx) => post.authorId === ctx.user.id,
+    ),
+  },
+};
+```
+
+#### isOwner(ownerField, userIdField)
+
+Checks if the authenticated user owns the resource:
+
+```javascript
+const permissions = {
+  Post: {
+    '*': composeRules(
+      requireAuth(),
+      isOwner('authorId', 'id'), // Compares post.authorId with ctx.user.id
+    ),
+  },
+};
+```
+
+### Policy Expressions (JSON AST)
+
+For declarative rules, use JSON AST policy expressions:
+
+```javascript
+const permissions = {
+  Post: {
+    content: {
+      anyOf: [
+        { eq: [{ ref: 'parent.published' }, true] },
+        { eq: [{ ref: 'parent.authorId' }, { ref: 'ctx.user.id' }] },
+      ],
+    },
+  },
+};
+```
+
+**Supported Operators:**
+
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `eq` | Equals | `{ eq: [{ ref: 'parent.status' }, 'active'] }` |
+| `in` | Value in array | `{ in: [{ ref: 'ctx.user.role' }, ['ADMIN', 'MOD']] }` |
+| `allOf` | All must be true (AND) | `{ allOf: [expr1, expr2] }` |
+| `anyOf` | Any must be true (OR) | `{ anyOf: [expr1, expr2] }` |
+| `not` | Negation | `{ not: { eq: [{ ref: 'parent.deleted' }, true] } }` |
+
+**References:**
+
+Use `{ ref: 'path' }` to reference values:
+- `parent.*` - Parent resolver result (the object being resolved)
+- `args.*` - GraphQL arguments
+- `ctx.*` - GraphQL context
+
+**Security:**
+- Only `parent`, `args`, and `ctx` roots are allowed
+- Unknown operators fail closed (deny)
+- No `eval()` or `Function()` - pure object traversal
+
+### Integration with GraphQL Yoga / Envelop
+
+The recommended way to use the auth system is via the Envelop plugin, which works natively with GraphQL Yoga and any Envelop-based server. The plugin wraps resolvers in-place without rebuilding the schema, avoiding compatibility issues.
+
+```javascript
+const { createYoga } = require('graphql-yoga');
+const { createServer } = require('http');
+const simfinity = require('@simtlix/simfinity-js');
+
+const { auth } = simfinity;
+const { createAuthPlugin, requireAuth, requireRole, requirePermission } = auth;
+
+// Define your types and connect them
+simfinity.connect(null, UserType, 'user', 'users');
+simfinity.connect(null, PostType, 'post', 'posts');
+
+// Create base schema
+const schema = simfinity.createSchema();
+
+// Define permissions
+const permissions = {
+  Query: {
+    users: requireAuth(),
+    user: requireAuth(),
+    posts: requireAuth(),
+    post: requireAuth(),
+  },
+  Mutation: {
+    adduser: requireRole('ADMIN'),
+    updateuser: requireRole('ADMIN'),
+    deleteuser: requireRole('ADMIN'),
+    addpost: requireAuth(),
+    updatepost: composeRules(requireAuth(), isOwner('authorId')),
+    deletepost: requireRole('ADMIN'),
+  },
+  User: {
+    '*': requireAuth(),
+    email: requireRole('ADMIN'),
+    password: deny('Password field is not accessible'),
+  },
+  Post: {
+    '*': requireAuth(),
+    content: {
+      anyOf: [
+        { eq: [{ ref: 'parent.published' }, true] },
+        { eq: [{ ref: 'parent.authorId' }, { ref: 'ctx.user.id' }] },
+      ],
+    },
+  },
+};
+
+// Create auth plugin
+const authPlugin = createAuthPlugin(permissions, {
+  defaultPolicy: 'DENY',
+  debug: false,
+});
+
+// Setup Yoga with the auth plugin
+const yoga = createYoga({
+  schema,
+  plugins: [authPlugin],
+  context: (req) => ({
+    user: req.user,  // Set by your authentication layer
+  }),
+});
+
+const server = createServer(yoga);
+server.listen(4000);
+```
+
+### Legacy: Integration with graphql-middleware
+
+> **Deprecated:** `applyMiddleware` from `graphql-middleware` rebuilds the schema via `mapSchema`,
+> which can cause `"Schema must contain uniquely named types"` errors with Simfinity schemas.
+> Use `createAuthPlugin` with GraphQL Yoga / Envelop instead.
+
+```javascript
+const { applyMiddleware } = require('graphql-middleware');
+const simfinity = require('@simtlix/simfinity-js');
+
+const { auth } = simfinity;
+const { createAuthMiddleware, requireAuth, requireRole } = auth;
+
+const baseSchema = simfinity.createSchema();
+
+const authMiddleware = createAuthMiddleware(permissions, {
+  defaultPolicy: 'DENY',
+});
+
+const schema = applyMiddleware(baseSchema, authMiddleware);
+```
+
+### Plugin / Middleware Options
+
+```javascript
+const plugin = createAuthPlugin(permissions, {
+  defaultPolicy: 'DENY',  // 'ALLOW' or 'DENY' (default: 'DENY')
+  debug: false,           // Enable debug logging
+});
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `defaultPolicy` | `'ALLOW' \| 'DENY'` | `'DENY'` | Policy when no rule matches |
+| `debug` | `boolean` | `false` | Log authorization decisions |
+
+### Error Handling
+
+The auth middleware uses Simfinity error classes:
+
+```javascript
+const { auth } = require('@simtlix/simfinity-js');
+
+const { UnauthenticatedError, ForbiddenError } = auth;
+
+// UnauthenticatedError: code 'UNAUTHENTICATED', status 401
+// ForbiddenError: code 'FORBIDDEN', status 403
+```
+
+Custom error handling in rules:
+
+```javascript
+const permissions = {
+  Mutation: {
+    deleteAccount: async (parent, args, ctx) => {
+      if (!ctx.user) {
+        throw new auth.UnauthenticatedError('Please log in');
+      }
+      if (ctx.user.role !== 'ADMIN' && ctx.user.id !== args.id) {
+        throw new auth.ForbiddenError('Cannot delete other users');
+      }
+      return true;
+    },
+  },
+};
+```
+
+### Best Practices
+
+1. **Default to DENY**: Use `defaultPolicy: 'DENY'` for security
+2. **Use wildcards wisely**: `'*'` rules provide baseline security per type
+3. **Prefer helper rules**: Use `requireAuth()`, `requireRole()` over custom functions
+4. **Fail closed**: Custom rules should deny on unexpected conditions
+5. **Keep rules simple**: Complex logic belongs in controllers, not auth rules
+6. **Test thoroughly**: Auth rules are critical - test all scenarios
+
 ## 🔗 Relationships
 
 ### Defining Relationships

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simtlix/simfinity-js",
-  "version": "2.3.4",
+  "version": "2.4.1",
   "description": "",
   "main": "src/index.js",
   "type": "module",
@@ -35,6 +35,7 @@
   },
   "optionalDependencies": {
     "graphql": "^16.11.0",
+    "graphql-middleware": "^6.1.35",
     "mongoose": "^8.16.2"
   }
 }

package/src/auth/errors.js

@@ -0,0 +1,44 @@
+import SimfinityError from '../errors/simfinity.error.js';
+
+/**
+ * Authentication error - thrown when user is not authenticated
+ * Uses code: UNAUTHENTICATED, status: 401
+ */
+export class UnauthenticatedError extends SimfinityError {
+  constructor(message = 'Authentication required') {
+    super(message, 'UNAUTHENTICATED', 401);
+    this.name = 'UnauthenticatedError';
+  }
+}
+
+/**
+ * Authorization error - thrown when user lacks permission
+ * Uses code: FORBIDDEN, status: 403
+ */
+export class ForbiddenError extends SimfinityError {
+  constructor(message = 'Access denied') {
+    super(message, 'FORBIDDEN', 403);
+    this.name = 'ForbiddenError';
+  }
+}
+
+/**
+ * Generic auth error factory for custom auth failures
+ * @param {string} message - Error message
+ * @param {string} code - Error code (UNAUTHENTICATED or FORBIDDEN)
+ * @returns {SimfinityError}
+ */
+export const createAuthError = (message, code = 'FORBIDDEN') => {
+  const status = code === 'UNAUTHENTICATED' ? 401 : 403;
+  return new SimfinityError(message, code, status);
+};
+
+// Export all errors as an object for convenience
+const errors = {
+  UnauthenticatedError,
+  ForbiddenError,
+  createAuthError,
+};
+
+export default errors;
+