@simtlix/simfinity-js 2.3.2 → 2.4.0

package/README.md

@@ -20,6 +20,12 @@ 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 Middleware](#-authorization-middleware)
+  - [Quick Start](#quick-start-1)
+  - [Permission Schema](#permission-schema)
+  - [Rule Helpers](#rule-helpers)
+  - [Policy Expressions (JSON AST)](#policy-expressions-json-ast)
+  - [Integration with graphql-middleware](#integration-with-graphql-middleware)
 - [Relationships](#-relationships)
   - [Defining Relationships](#defining-relationships)
   - [Auto-Generated Resolve Methods](#auto-generated-resolve-methods)
@@ -69,6 +75,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 Middleware**: Production-grade GraphQL authorization with RBAC/ABAC, function-based rules, and declarative policy expressions
 
 ## 📦 Installation
 
@@ -622,6 +629,378 @@ 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 Middleware
+
+Simfinity.js provides a production-grade centralized GraphQL authorization middleware supporting RBAC/ABAC, function-based rules, declarative policy expressions (JSON AST), wildcard permissions, and configurable default policies.
+
+### Quick Start
+
+```javascript
+const { auth } = require('@simtlix/simfinity-js');
+const { applyMiddleware } = require('graphql-middleware');
+
+const { createAuthMiddleware, 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 and apply the middleware
+const authMiddleware = createAuthMiddleware(permissions, { defaultPolicy: 'DENY' });
+const schemaWithAuth = applyMiddleware(schema, authMiddleware);
+```
+
+### 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-middleware
+
+The auth middleware integrates with the `graphql-middleware` package:
+
+```javascript
+const express = require('express');
+const { graphqlHTTP } = require('express-graphql');
+const { applyMiddleware } = require('graphql-middleware');
+const simfinity = require('@simtlix/simfinity-js');
+
+const { auth } = simfinity;
+const { createAuthMiddleware, 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 baseSchema = 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 middleware
+const authMiddleware = createAuthMiddleware(permissions, {
+  defaultPolicy: 'DENY',  // Deny access when no rule matches
+  debug: false,           // Enable for debugging
+});
+
+// Apply middleware to schema
+const schema = applyMiddleware(baseSchema, authMiddleware);
+
+// Setup Express with context
+const app = express();
+
+app.use('/graphql', graphqlHTTP((req) => ({
+  schema,
+  graphiql: true,
+  context: {
+    user: req.user,  // Set by your authentication middleware
+  },
+  formatError: simfinity.buildErrorFormatter((err) => {
+    console.error(err);
+  }),
+})));
+
+app.listen(4000);
+```
+
+### Middleware Options
+
+```javascript
+const middleware = createAuthMiddleware(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.2",
+  "version": "2.4.0",
   "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;
+

package/src/auth/expressions.js

@@ -0,0 +1,273 @@
+/**
+ * JSON AST Policy Expression Evaluator
+ * 
+ * Safely evaluates declarative policy expressions without using eval() or Function().
+ * Supports logical operators (allOf, anyOf, not), comparison operators (eq, in),
+ * boolean literals, and references to parent/args/ctx.
+ * 
+ * Unknown operators or invalid references fail closed (deny).
+ */
+
+/**
+ * Resolves a reference path like "parent.authorId" or "ctx.user.id"
+ * @param {string} refPath - The reference path (e.g., "ctx.user.id")
+ * @param {Object} context - The evaluation context { parent, args, ctx }
+ * @returns {*} The resolved value or undefined if not found
+ */
+const resolveRef = (refPath, context) => {
+  if (typeof refPath !== 'string') {
+    return undefined;
+  }
+
+  const parts = refPath.split('.');
+  const root = parts[0];
+
+  // Only allow parent, args, ctx as root references
+  if (!['parent', 'args', 'ctx'].includes(root)) {
+    return undefined;
+  }
+
+  let value = context[root];
+  
+  for (let i = 1; i < parts.length; i++) {
+    if (value === null || value === undefined) {
+      return undefined;
+    }
+    value = value[parts[i]];
+  }
+
+  return value;
+};
+
+/**
+ * Resolves a value which may be a literal or a reference
+ * @param {*} value - The value to resolve (could be { ref: "..." } or a literal)
+ * @param {Object} context - The evaluation context { parent, args, ctx }
+ * @returns {*} The resolved value
+ */
+const resolveValue = (value, context) => {
+  // Check if it's a reference object
+  if (value !== null && typeof value === 'object' && 'ref' in value) {
+    return resolveRef(value.ref, context);
+  }
+  // Return literal value
+  return value;
+};
+
+/**
+ * Evaluates an 'eq' expression: { eq: [left, right] }
+ * @param {Array} operands - Array of two operands to compare
+ * @param {Object} context - The evaluation context
+ * @returns {boolean}
+ */
+const evaluateEq = (operands, context) => {
+  if (!Array.isArray(operands) || operands.length !== 2) {
+    return false; // Fail closed
+  }
+  const left = resolveValue(operands[0], context);
+  const right = resolveValue(operands[1], context);
+  return left === right;
+};
+
+/**
+ * Evaluates an 'in' expression: { in: [value, array] }
+ * @param {Array} operands - [value, array] where value should be in array
+ * @param {Object} context - The evaluation context
+ * @returns {boolean}
+ */
+const evaluateIn = (operands, context) => {
+  if (!Array.isArray(operands) || operands.length !== 2) {
+    return false; // Fail closed
+  }
+  const value = resolveValue(operands[0], context);
+  const array = resolveValue(operands[1], context);
+  
+  if (!Array.isArray(array)) {
+    return false; // Fail closed
+  }
+  
+  return array.includes(value);
+};
+
+/**
+ * Evaluates an 'allOf' expression: { allOf: [...expressions] }
+ * All expressions must evaluate to true (logical AND)
+ * @param {Array} expressions - Array of expressions to evaluate
+ * @param {Object} context - The evaluation context
+ * @returns {boolean}
+ */
+const evaluateAllOf = (expressions, context) => {
+  if (!Array.isArray(expressions)) {
+    return false; // Fail closed
+  }
+  
+  for (const expr of expressions) {
+    if (!evaluateExpression(expr, context)) {
+      return false;
+    }
+  }
+  return true;
+};
+
+/**
+ * Evaluates an 'anyOf' expression: { anyOf: [...expressions] }
+ * At least one expression must evaluate to true (logical OR)
+ * @param {Array} expressions - Array of expressions to evaluate
+ * @param {Object} context - The evaluation context
+ * @returns {boolean}
+ */
+const evaluateAnyOf = (expressions, context) => {
+  if (!Array.isArray(expressions)) {
+    return false; // Fail closed
+  }
+  
+  for (const expr of expressions) {
+    if (evaluateExpression(expr, context)) {
+      return true;
+    }
+  }
+  return false;
+};
+
+/**
+ * Evaluates a 'not' expression: { not: expression }
+ * Negates the result of the inner expression
+ * @param {*} expression - Expression to negate
+ * @param {Object} context - The evaluation context
+ * @returns {boolean}
+ */
+const evaluateNot = (expression, context) => {
+  return !evaluateExpression(expression, context);
+};
+
+/**
+ * Main expression evaluator
+ * @param {*} expression - The expression to evaluate
+ * @param {Object} context - The evaluation context { parent, args, ctx }
+ * @returns {boolean} The result of the expression evaluation
+ */
+export const evaluateExpression = (expression, context) => {
+  // Handle boolean literals
+  if (typeof expression === 'boolean') {
+    return expression;
+  }
+
+  // Handle null/undefined - fail closed
+  if (expression === null || expression === undefined) {
+    return false;
+  }
+
+  // Expression must be an object with exactly one operator key
+  if (typeof expression !== 'object') {
+    return false; // Fail closed for non-object expressions
+  }
+
+  const keys = Object.keys(expression);
+  
+  // Empty object fails closed
+  if (keys.length === 0) {
+    return false;
+  }
+
+  // Handle single operator expressions
+  if (keys.length === 1) {
+    const operator = keys[0];
+    const operand = expression[operator];
+
+    switch (operator) {
+      case 'eq':
+        return evaluateEq(operand, context);
+      case 'in':
+        return evaluateIn(operand, context);
+      case 'allOf':
+        return evaluateAllOf(operand, context);
+      case 'anyOf':
+        return evaluateAnyOf(operand, context);
+      case 'not':
+        return evaluateNot(operand, context);
+      default:
+        // Unknown operator - fail closed
+        return false;
+    }
+  }
+
+  // Multiple keys - treat as implicit allOf
+  // This allows { eq: [...], in: [...] } to mean both must pass
+  for (const operator of keys) {
+    const operand = expression[operator];
+    let result;
+    
+    switch (operator) {
+      case 'eq':
+        result = evaluateEq(operand, context);
+        break;
+      case 'in':
+        result = evaluateIn(operand, context);
+        break;
+      case 'allOf':
+        result = evaluateAllOf(operand, context);
+        break;
+      case 'anyOf':
+        result = evaluateAnyOf(operand, context);
+        break;
+      case 'not':
+        result = evaluateNot(operand, context);
+        break;
+      default:
+        // Unknown operator - fail closed
+        return false;
+    }
+    
+    if (!result) {
+      return false;
+    }
+  }
+  
+  return true;
+};
+
+/**
+ * Checks if a value is a policy expression (object with operator keys)
+ * @param {*} value - The value to check
+ * @returns {boolean} True if the value appears to be a policy expression
+ */
+export const isPolicyExpression = (value) => {
+  if (value === null || typeof value !== 'object') {
+    return false;
+  }
+  
+  // Check if it's a function (not an expression)
+  if (typeof value === 'function') {
+    return false;
+  }
+  
+  // Check if it has any known operator keys
+  const operatorKeys = ['eq', 'in', 'allOf', 'anyOf', 'not'];
+  const keys = Object.keys(value);
+  
+  return keys.some(key => operatorKeys.includes(key));
+};
+
+/**
+ * Creates a rule function from a policy expression
+ * @param {Object} expression - The policy expression
+ * @returns {Function} A rule function (parent, args, ctx, info) => boolean
+ */
+export const createRuleFromExpression = (expression) => {
+  return (parent, args, ctx) => {
+    const context = { parent, args, ctx };
+    return evaluateExpression(expression, context);
+  };
+};
+
+// Export all expression utilities as an object for convenience
+const expressions = {
+  evaluateExpression,
+  isPolicyExpression,
+  createRuleFromExpression,
+  resolveRef,
+  resolveValue,
+};
+
+export default expressions;
+

package/src/auth/index.js

@@ -0,0 +1,312 @@
+/**
+ * Simfinity GraphQL Authorization Middleware
+ * 
+ * Production-grade centralized GraphQL authorization supporting:
+ * - RBAC / ABAC
+ * - Function-based rules
+ * - Declarative policy expressions (JSON AST)
+ * - Wildcard "*" permissions
+ * - Default allow/deny policies
+ * 
+ * @example
+ * import { auth } from '@simtlix/simfinity-js';
+ * import { applyMiddleware } from 'graphql-middleware';
+ * 
+ * const { createAuthMiddleware, requireAuth, requireRole } = auth;
+ * 
+ * const permissions = {
+ *   Query: {
+ *     users: requireAuth(),
+ *     adminDashboard: requireRole('ADMIN')
+ *   },
+ *   Mutation: {
+ *     publishPost: requireRole('EDITOR')
+ *   },
+ *   User: {
+ *     '*': requireAuth(),
+ *     email: requireRole('ADMIN')
+ *   }
+ * };
+ * 
+ * const authMiddleware = createAuthMiddleware(permissions, { defaultPolicy: 'DENY' });
+ * const schemaWithAuth = applyMiddleware(schema, authMiddleware);
+ */
+
+import { UnauthenticatedError, ForbiddenError, createAuthError } from './errors.js';
+import { isPolicyExpression, createRuleFromExpression, evaluateExpression } from './expressions.js';
+import {
+  resolvePath,
+  requireAuth,
+  requireRole,
+  requirePermission,
+  composeRules,
+  anyRule,
+  isOwner,
+  createRule,
+  allow,
+  deny,
+} from './rules.js';
+
+// Re-export errors
+export { UnauthenticatedError, ForbiddenError, createAuthError } from './errors.js';
+
+// Re-export expression utilities
+export { evaluateExpression, isPolicyExpression, createRuleFromExpression } from './expressions.js';
+
+// Re-export rule helpers and utilities
+export {
+  resolvePath,
+  requireAuth,
+  requireRole,
+  requirePermission,
+  composeRules,
+  anyRule,
+  isOwner,
+  createRule,
+  allow,
+  deny,
+} from './rules.js';
+
+/**
+ * @typedef {'ALLOW' | 'DENY'} DefaultPolicy
+ */
+
+/**
+ * @typedef {Object} AuthMiddlewareOptions
+ * @property {DefaultPolicy} [defaultPolicy='DENY'] - Default policy when no rule matches
+ * @property {boolean} [debug=false] - Enable debug logging
+ */
+
+/**
+ * @typedef {Function} RuleFunction
+ * @param {*} parent - Parent resolver result
+ * @param {Object} args - GraphQL arguments
+ * @param {Object} ctx - GraphQL context
+ * @param {Object} info - GraphQL resolve info
+ * @returns {boolean|void|Promise<boolean|void>} - true/void to allow, false to deny
+ */
+
+/**
+ * @typedef {Object|RuleFunction|Array<RuleFunction>} Rule
+ */
+
+/**
+ * @typedef {Object.<string, Rule>} TypePermissions
+ */
+
+/**
+ * @typedef {Object.<string, TypePermissions>} PermissionSchema
+ */
+
+/**
+ * Normalizes a rule to always be an array of functions
+ * @param {Rule} rule - The rule to normalize
+ * @returns {Function[]} Array of rule functions
+ */
+const normalizeRule = (rule) => {
+  if (typeof rule === 'function') {
+    return [rule];
+  }
+  
+  if (Array.isArray(rule)) {
+    return rule.flatMap(r => normalizeRule(r));
+  }
+  
+  if (isPolicyExpression(rule)) {
+    return [createRuleFromExpression(rule)];
+  }
+  
+  // Unknown rule type - return empty (will use default policy)
+  return [];
+};
+
+/**
+ * Gets the rule for a specific field, with wildcard fallback
+ * @param {PermissionSchema} permissions - The permission schema
+ * @param {string} typeName - The GraphQL type name
+ * @param {string} fieldName - The field name
+ * @returns {Function[]|null} Array of rule functions or null if no rule found
+ */
+const getFieldRules = (permissions, typeName, fieldName) => {
+  const typePerms = permissions[typeName];
+  
+  if (!typePerms) {
+    return null;
+  }
+  
+  // Check for exact field rule first
+  if (fieldName in typePerms) {
+    return normalizeRule(typePerms[fieldName]);
+  }
+  
+  // Fallback to wildcard
+  if ('*' in typePerms) {
+    return normalizeRule(typePerms['*']);
+  }
+  
+  return null;
+};
+
+/**
+ * Executes a single rule
+ * @param {Function} rule - The rule function to execute
+ * @param {*} parent - Parent resolver result
+ * @param {Object} args - GraphQL arguments
+ * @param {Object} ctx - GraphQL context
+ * @param {Object} info - GraphQL resolve info
+ * @returns {Promise<boolean>} True if allowed, false if denied
+ */
+const executeRule = async (rule, parent, args, ctx, info) => {
+  const result = await rule(parent, args, ctx, info);
+  
+  // void/undefined/true means allow
+  if (result === undefined || result === true) {
+    return true;
+  }
+  
+  // false means deny
+  return false;
+};
+
+/**
+ * Creates a graphql-middleware compatible authorization middleware
+ * 
+ * @param {PermissionSchema} permissions - The permission schema object
+ * @param {AuthMiddlewareOptions} [options={}] - Middleware options
+ * @returns {Function} A graphql-middleware compatible middleware function
+ * 
+ * @example
+ * const permissions = {
+ *   Query: {
+ *     users: requireAuth(),
+ *     adminDashboard: requireRole('ADMIN')
+ *   },
+ *   User: {
+ *     '*': requireAuth(),
+ *     email: requireRole('ADMIN')
+ *   },
+ *   Post: {
+ *     content: {
+ *       anyOf: [
+ *         { eq: [{ ref: 'parent.published' }, true] },
+ *         { eq: [{ ref: 'parent.authorId' }, { ref: 'ctx.user.id' }] }
+ *       ]
+ *     }
+ *   }
+ * };
+ * 
+ * const middleware = createAuthMiddleware(permissions, { defaultPolicy: 'DENY' });
+ */
+export const createAuthMiddleware = (permissions, options = {}) => {
+  const {
+    defaultPolicy = 'DENY',
+    debug = false,
+  } = options;
+
+  const log = debug ? console.log.bind(console, '[auth]') : () => {};
+
+  /**
+   * The middleware generator function
+   * Returns a middleware object keyed by type name, each containing field resolvers
+   */
+  return async (resolve, parent, args, ctx, info) => {
+    const typeName = info.parentType.name;
+    const fieldName = info.fieldName;
+
+    log(`Checking ${typeName}.${fieldName}`);
+
+    // Get rules for this field
+    const rules = getFieldRules(permissions, typeName, fieldName);
+
+    // If no rules found, apply default policy
+    if (rules === null || rules.length === 0) {
+      log(`No rules for ${typeName}.${fieldName}, applying default policy: ${defaultPolicy}`);
+      
+      if (defaultPolicy === 'DENY') {
+        throw new ForbiddenError(`Access denied to ${typeName}.${fieldName}`);
+      }
+      
+      // ALLOW - proceed to resolver
+      return resolve(parent, args, ctx, info);
+    }
+
+    // Execute all rules (AND logic - all must pass)
+    for (const rule of rules) {
+      log(`Executing rule for ${typeName}.${fieldName}`);
+      
+      const allowed = await executeRule(rule, parent, args, ctx, info);
+      
+      if (!allowed) {
+        log(`Rule denied access to ${typeName}.${fieldName}`);
+        throw new ForbiddenError(`Access denied to ${typeName}.${fieldName}`);
+      }
+    }
+
+    log(`Access granted to ${typeName}.${fieldName}`);
+    
+    // All rules passed - proceed to resolver
+    return resolve(parent, args, ctx, info);
+  };
+};
+
+/**
+ * Creates a field-level middleware object from a permission schema
+ * This can be used with graphql-middleware's applyMiddleware
+ * 
+ * @param {PermissionSchema} permissions - The permission schema
+ * @param {AuthMiddlewareOptions} [options={}] - Middleware options
+ * @returns {Object} Field middleware object compatible with graphql-middleware
+ */
+export const createFieldMiddleware = (permissions, options = {}) => {
+  const middleware = createAuthMiddleware(permissions, options);
+  const fieldMiddleware = {};
+
+  for (const typeName of Object.keys(permissions)) {
+    fieldMiddleware[typeName] = {};
+    
+    const typePerms = permissions[typeName];
+    for (const fieldName of Object.keys(typePerms)) {
+      if (fieldName === '*') {
+        // Wildcard rules are handled by the middleware internally
+        continue;
+      }
+      fieldMiddleware[typeName][fieldName] = middleware;
+    }
+  }
+
+  return fieldMiddleware;
+};
+
+// Default export with all auth utilities
+const auth = {
+  // Main factory
+  createAuthMiddleware,
+  createFieldMiddleware,
+  
+  // Utilities
+  resolvePath,
+  
+  // Rule helpers
+  requireAuth,
+  requireRole,
+  requirePermission,
+  composeRules,
+  anyRule,
+  isOwner,
+  createRule,
+  allow,
+  deny,
+  
+  // Expression utilities
+  evaluateExpression,
+  isPolicyExpression,
+  createRuleFromExpression,
+  
+  // Errors
+  UnauthenticatedError,
+  ForbiddenError,
+  createAuthError,
+};
+
+export default auth;
+

package/src/auth/rules.js

@@ -0,0 +1,274 @@
+import { UnauthenticatedError, ForbiddenError } from './errors.js';
+
+/**
+ * Resolves a value from an object using a dotted path string or function.
+ * @param {Object} obj - The object to resolve from
+ * @param {string|Function} pathOrFn - Dotted path (e.g., 'user.profile.id') or function to extract value
+ * @returns {*} The resolved value or undefined if not found
+ * @example
+ * resolvePath({ user: { id: '123' } }, 'user.id') // returns '123'
+ * resolvePath({ user: { id: '123' } }, (obj) => obj.user.id) // returns '123'
+ */
+export const resolvePath = (obj, pathOrFn) => {
+  if (typeof pathOrFn === 'function') {
+    return pathOrFn(obj);
+  }
+  if (typeof pathOrFn === 'string') {
+    const parts = pathOrFn.split('.');
+    let value = obj;
+    for (const part of parts) {
+      if (value == null) return undefined;
+      value = value[part];
+    }
+    return value;
+  }
+  return undefined;
+};
+
+/**
+ * Rule that requires the user to be authenticated
+ * Checks for user existence at the specified path in context
+ * @param {string|Function} [userPath='user'] - Path to user in context (e.g., 'user', 'auth.user', 'session.user')
+ * @returns {Function} Rule function (parent, args, ctx, info) => boolean | throws
+ * @example
+ * requireAuth()                    // checks ctx.user
+ * requireAuth('auth.user')         // checks ctx.auth.user
+ * requireAuth('session.currentUser') // checks ctx.session.currentUser
+ */
+export const requireAuth = (userPath = 'user') => {
+  return (_parent, _args, ctx) => {
+    if (!ctx) {
+      throw new UnauthenticatedError('You must be logged in to access this resource');
+    }
+    const user = resolvePath(ctx, userPath);
+    if (!user) {
+      throw new UnauthenticatedError('You must be logged in to access this resource');
+    }
+    return true;
+  };
+};
+
+/**
+ * Rule that requires the user to have a specific role
+ * @param {string|string[]} role - Required role or array of roles (any match)
+ * @param {Object} [options] - Configuration options
+ * @param {string|Function} [options.userPath='user'] - Path to user in context
+ * @param {string|Function} [options.rolePath='role'] - Path to role field in user object
+ * @returns {Function} Rule function (parent, args, ctx, info) => boolean | throws
+ * @example
+ * requireRole('ADMIN')
+ * requireRole(['ADMIN', 'EDITOR'])
+ * requireRole('ADMIN', { userPath: 'auth.user', rolePath: 'roles.primary' })
+ */
+export const requireRole = (role, options = {}) => {
+  const roles = Array.isArray(role) ? role : [role];
+  const { userPath = 'user', rolePath = 'role' } = options;
+  
+  return (_parent, _args, ctx) => {
+    if (!ctx) {
+      throw new UnauthenticatedError('You must be logged in to access this resource');
+    }
+    const user = resolvePath(ctx, userPath);
+    if (!user) {
+      throw new UnauthenticatedError('You must be logged in to access this resource');
+    }
+    
+    const userRole = resolvePath(user, rolePath);
+    
+    if (!roles.includes(userRole)) {
+      throw new ForbiddenError(`Requires role: ${roles.join(' or ')}`);
+    }
+    
+    return true;
+  };
+};
+
+/**
+ * Rule that requires the user to have a specific permission
+ * @param {string|string[]} permission - Required permission(s) (all must match if array)
+ * @param {Object} [options] - Configuration options
+ * @param {string|Function} [options.userPath='user'] - Path to user in context
+ * @param {string|Function} [options.permissionsPath='permissions'] - Path to permissions array in user object
+ * @returns {Function} Rule function (parent, args, ctx, info) => boolean | throws
+ * @example
+ * requirePermission('posts:read')
+ * requirePermission(['posts:read', 'posts:write'])
+ * requirePermission('posts:read', { userPath: 'auth.user', permissionsPath: 'grants' })
+ */
+export const requirePermission = (permission, options = {}) => {
+  const requiredPermissions = Array.isArray(permission) ? permission : [permission];
+  const { userPath = 'user', permissionsPath = 'permissions' } = options;
+  
+  return (_parent, _args, ctx) => {
+    if (!ctx) {
+      throw new UnauthenticatedError('You must be logged in to access this resource');
+    }
+    const user = resolvePath(ctx, userPath);
+    if (!user) {
+      throw new UnauthenticatedError('You must be logged in to access this resource');
+    }
+    
+    const userPermissions = resolvePath(user, permissionsPath) || [];
+    
+    // Check if user has wildcard permission
+    if (userPermissions.includes('*')) {
+      return true;
+    }
+    
+    // All required permissions must be present
+    for (const perm of requiredPermissions) {
+      if (!userPermissions.includes(perm)) {
+        throw new ForbiddenError(`Missing permission: ${perm}`);
+      }
+    }
+    
+    return true;
+  };
+};
+
+/**
+ * Composes multiple rules - all must pass (logical AND)
+ * @param  {...Function} rules - Rule functions to compose
+ * @returns {Function} Composed rule function
+ */
+export const composeRules = (...rules) => {
+  return async (parent, args, ctx, info) => {
+    for (const rule of rules) {
+      const result = await rule(parent, args, ctx, info);
+      // If rule returns false, deny access
+      if (result === false) {
+        return false;
+      }
+      // If rule throws, it will propagate
+    }
+    return true;
+  };
+};
+
+/**
+ * Creates a rule that allows access if ANY of the provided rules pass (logical OR)
+ * @param  {...Function} rules - Rule functions to check
+ * @returns {Function} Combined rule function
+ */
+export const anyRule = (...rules) => {
+  return async (parent, args, ctx, info) => {
+    let lastError = null;
+    
+    for (const rule of rules) {
+      try {
+        const result = await rule(parent, args, ctx, info);
+        if (result !== false) {
+          return true; // At least one rule passed
+        }
+      } catch (error) {
+        lastError = error;
+        // Continue to next rule
+      }
+    }
+    
+    // No rule passed - throw the last error or return false
+    if (lastError) {
+      throw lastError;
+    }
+    return false;
+  };
+};
+
+/**
+ * Creates a rule that checks if the authenticated user owns the resource
+ * @param {string|Function} [ownerField='userId'] - Path to owner ID in parent, or function to extract it
+ * @param {string|Function} [userIdField='id'] - Path to user ID in user object, or function to extract it
+ * @param {Object} [options] - Configuration options
+ * @param {string|Function} [options.userPath='user'] - Path to user in context
+ * @returns {Function} Rule function
+ * @example
+ * isOwner()                                    // compares parent.userId with ctx.user.id
+ * isOwner('authorId')                          // compares parent.authorId with ctx.user.id
+ * isOwner('author.id', 'profile.id')           // compares parent.author.id with ctx.user.profile.id
+ * isOwner('authorId', 'id', { userPath: 'auth.user' }) // uses ctx.auth.user instead of ctx.user
+ */
+export const isOwner = (ownerField = 'userId', userIdField = 'id', options = {}) => {
+  const { userPath = 'user' } = options;
+
+  return (parent, _args, ctx) => {
+    if (!ctx) {
+      throw new UnauthenticatedError('You must be logged in to access this resource');
+    }
+    const user = resolvePath(ctx, userPath);
+    if (!user) {
+      throw new UnauthenticatedError('You must be logged in to access this resource');
+    }
+
+    // Get ownerId from parent (using path or function)
+    const ownerId = resolvePath(parent, ownerField);
+
+    // Get userId from user object (using path or function)
+    const userId = resolvePath(user, userIdField);
+
+    if (ownerId === undefined || userId === undefined) {
+      return false;
+    }
+
+    return String(ownerId) === String(userId);
+  };
+};
+
+/**
+ * Creates a custom rule from a predicate function
+ * @param {Function} predicate - Function (parent, args, ctx, info) => boolean | Promise<boolean>
+ * @param {string} errorMessage - Error message if rule fails
+ * @param {string} errorCode - Error code (FORBIDDEN or UNAUTHENTICATED)
+ * @returns {Function} Rule function
+ */
+export const createRule = (predicate, errorMessage = 'Access denied', errorCode = 'FORBIDDEN') => {
+  return async (parent, args, ctx, info) => {
+    const result = await predicate(parent, args, ctx, info);
+    
+    if (result === false) {
+      if (errorCode === 'UNAUTHENTICATED') {
+        throw new UnauthenticatedError(errorMessage);
+      }
+      throw new ForbiddenError(errorMessage);
+    }
+    
+    return true;
+  };
+};
+
+/**
+ * Rule that always allows access (useful for public fields)
+ * @returns {Function} Rule function that always returns true
+ */
+export const allow = () => {
+  return () => true;
+};
+
+/**
+ * Rule that always denies access
+ * @param {string} message - Optional denial message
+ * @returns {Function} Rule function that always throws ForbiddenError
+ */
+export const deny = (message = 'Access denied') => {
+  return () => {
+    throw new ForbiddenError(message);
+  };
+};
+
+// Export all rules as an object for convenience
+const rules = {
+  // Utility
+  resolvePath,
+  // Rule helpers
+  requireAuth,
+  requireRole,
+  requirePermission,
+  composeRules,
+  anyRule,
+  isOwner,
+  createRule,
+  allow,
+  deny,
+};
+
+export default rules;
+

package/src/index.js

@@ -2144,6 +2144,7 @@ export { createValidatedScalar };
 export { default as validators } from './validators.js';
 export { default as scalars } from './scalars.js';
 export { default as plugins } from './plugins.js';
+export { default as auth } from './auth/index.js';
 
 const createArgsForQuery = (argTypes) => {
     const argsObject = {};

package/src/plugins.js

@@ -13,9 +13,9 @@ export const apolloCountPlugin = () => {
               count: contextValue.count,
             };
           }
-        }
+        },
       };
-    }
+    },
   };
 };
 
@@ -31,12 +31,12 @@ export const envelopCountPlugin = () => {
           if (args.contextValue?.count) {
             result.extensions = {
               ...result.extensions,
-              count: args.contextValue.count
+              count: args.contextValue.count,
             };
           }
-        }
+        },
       };
-    }
+    },
   };
 };