@simtlix/simfinity-core 3.5.1 → 3.5.3

package/src/auth/rules.js

@@ -1,8 +1,10 @@
 import { UnauthenticatedError, ForbiddenError } from './errors.js';
 import { normalizeObjectId } from './object-id.js';
+import { isThenable, discardThenable } from './thenable.js';
 
 /**
  * Resolves a value from an object using a dotted path string or function.
+ * A function's result is returned as is, including a promise; the built-in rules deny such results.
  * @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
@@ -26,6 +28,48 @@ export const resolvePath = (obj, pathOrFn) => {
   return undefined;
 };
 
+// Built-in rules also have a check that returns true, false or a factory for the denial error.
+// anyRule uses it so a denial that a later rule overrides never builds and throws an error.
+// Checks are keyed by the rule function itself: a property would be copied by Object.assign or
+// read through a Proxy, and anyRule would then skip the checks of a wrapping function.
+const checks = new WeakMap();
+
+const ruleFromCheck = (check) => {
+  const rule = (parent, args, ctx, info) => {
+    const result = check(parent, args, ctx, info);
+    if (typeof result === 'function') throw result();
+    return result;
+  };
+  checks.set(rule, check);
+  return rule;
+};
+
+const unauthenticated = () => new UnauthenticatedError('You must be logged in to access this resource');
+
+// Built-in checks are synchronous, so they cannot wait for a path that yields a promise or another
+// thenable. Such a value is never truthy evidence of a user or claim: it denies with this error.
+const pendingValue = () => new TypeError(
+  'Authorization paths must return values synchronously; resolve asynchronous data in the GraphQL context or use an async rule',
+);
+const pending = Symbol('pending authorization value');
+
+const isAsyncFunction = value => ['[object AsyncFunction]', '[object AsyncGeneratorFunction]']
+  .includes(Object.prototype.toString.call(value));
+
+const validatePath = (name, pathOrFn) => {
+  if (isAsyncFunction(pathOrFn)) {
+    throw new TypeError(`${name} must be a dotted path or a synchronous extractor function`);
+  }
+};
+
+/** Resolve a path for a built-in check; a thenable result is discarded and reported as pending. */
+const readPath = (obj, pathOrFn) => {
+  const value = resolvePath(obj, pathOrFn);
+  if (!isThenable(value)) return value;
+  discardThenable(value);
+  return pending;
+};
+
 /**
  * Rule that requires the user to be authenticated
  * Checks for user existence at the specified path in context
@@ -37,16 +81,13 @@ export const resolvePath = (obj, pathOrFn) => {
  * 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;
-  };
+  validatePath('userPath', userPath);
+  return ruleFromCheck((_parent, _args, ctx) => {
+    if (!ctx) return unauthenticated;
+    const user = readPath(ctx, userPath);
+    if (user === pending) return pendingValue;
+    return user ? true : unauthenticated;
+  });
 };
 
 /**
@@ -62,29 +103,44 @@ export const requireAuth = (userPath = 'user') => {
  * requireRole('ADMIN', { userPath: 'auth.user', rolePath: 'roles.primary' })
  */
 export const requireRole = (role, options = {}) => {
-  const roles = Array.isArray(role) ? role : [role];
+  // Copy the list, so changing the caller's array later cannot bypass this validation.
+  const roles = Object.freeze(Array.isArray(role) ? Array.from(role) : [role]);
   if (roles.length === 0 || Array.from(roles).some(value => typeof value !== 'string' || value.length === 0)) {
     throw new TypeError('Required roles must be a nonempty string or array of nonempty strings');
   }
   const { userPath = 'user', rolePath = 'role' } = options;
+  validatePath('userPath', userPath);
+  validatePath('rolePath', rolePath);
+  const forbidden = () => new ForbiddenError(`Requires role: ${roles.join(' or ')}`);
 
-  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);
+  return ruleFromCheck((_parent, _args, ctx) => {
+    if (!ctx) return unauthenticated;
+    const user = readPath(ctx, userPath);
+    if (user === pending) return pendingValue;
+    if (!user) return unauthenticated;
 
-    if (!roles.includes(userRole)) {
-      throw new ForbiddenError(`Requires role: ${roles.join(' or ')}`);
-    }
+    const userRole = readPath(user, rolePath);
+    if (userRole === pending) return pendingValue;
+    return roles.includes(userRole) ? true : forbidden;
+  });
+};
 
-    return true;
-  };
+/**
+ * Validate the claims and find the required permissions they hold in one pass, without copying
+ * them. Returns null for malformed claims (including holes) and true for a standalone '*' entry.
+ * Nothing is cached: a context can outlive a request, and claims can change in place.
+ */
+const findHeldPermissions = (claims, requiredPermissions) => {
+  if (!Array.isArray(claims)) return null;
+  let wildcard = false;
+  const held = new Set();
+  for (let index = 0; index < claims.length; index++) {
+    const claim = claims[index];
+    if (typeof claim !== 'string' || claim.length === 0) return null;
+    if (claim === '*') wildcard = true;
+    else if (requiredPermissions.includes(claim)) held.add(claim);
+  }
+  return wildcard || held;
 };
 
 /**
@@ -100,42 +156,38 @@ export const requireRole = (role, options = {}) => {
  * requirePermission('posts:read', { userPath: 'auth.user', permissionsPath: 'grants' })
  */
 export const requirePermission = (permission, options = {}) => {
-  const requiredPermissions = Array.isArray(permission) ? permission : [permission];
+  // Copy the list, so changing the caller's array later cannot bypass this validation.
+  const requiredPermissions = Object.freeze(Array.isArray(permission) ? Array.from(permission) : [permission]);
   if (requiredPermissions.length === 0
     || Array.from(requiredPermissions).some(perm => typeof perm !== 'string' || perm.length === 0)) {
     throw new TypeError('Required permissions must be a nonempty string or array of nonempty strings');
   }
   const { userPath = 'user', permissionsPath = 'permissions' } = options;
+  validatePath('userPath', userPath);
+  validatePath('permissionsPath', permissionsPath);
 
-  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 ruleFromCheck((_parent, _args, ctx) => {
+    if (!ctx) return unauthenticated;
+    const user = readPath(ctx, userPath);
+    if (user === pending) return pendingValue;
+    if (!user) return unauthenticated;
 
-    const userPermissions = resolvePath(user, permissionsPath);
-    if (!Array.isArray(userPermissions)
-      || Array.from(userPermissions).some(perm => typeof perm !== 'string' || perm.length === 0)) {
-      throw new ForbiddenError('User permissions must be an array of nonempty strings');
+    const claims = readPath(user, permissionsPath);
+    if (claims === pending) return pendingValue;
+    const held = findHeldPermissions(claims, requiredPermissions);
+    if (held === null) {
+      return () => new ForbiddenError('User permissions must be an array of nonempty strings');
     }
 
-    // Check if user has wildcard permission
-    if (userPermissions.includes('*')) {
+    // A wildcard entry grants every permission
+    if (held === true) {
       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;
-  };
+    const missing = requiredPermissions.find(perm => !held.has(perm));
+    return missing === undefined ? true : () => new ForbiddenError(`Missing permission: ${missing}`);
+  });
 };
 
 /**
@@ -144,6 +196,10 @@ export const requirePermission = (permission, options = {}) => {
  * @returns {Function} Composed rule function
  */
 export const composeRules = (...rules) => {
+  // With no rules the composition would grant everything; use allow() for an intentional grant.
+  if (rules.length === 0) {
+    throw new TypeError('composeRules requires at least one rule');
+  }
   if (rules.some(rule => typeof rule !== 'function')) {
     throw new TypeError('composeRules requires rule functions');
   }
@@ -166,25 +222,38 @@ export const composeRules = (...rules) => {
  * @returns {Function} Combined rule function
  */
 export const anyRule = (...rules) => {
+  if (rules.length === 0) {
+    throw new TypeError('anyRule requires at least one rule');
+  }
   if (rules.some(rule => typeof rule !== 'function')) {
     throw new TypeError('anyRule requires rule functions');
   }
   return async (parent, args, ctx, info) => {
     let lastError = null;
+    // A built-in rule's denial is kept as a factory and only built if it is the error thrown.
+    let lastErrorIsFactory = false;
 
     for (const rule of rules) {
       try {
-        const result = await rule(parent, args, ctx, info);
-        if (result === true || result === undefined) {
+        const check = checks.get(rule);
+        const result = check ? check(parent, args, ctx, info) : await rule(parent, args, ctx, info);
+        if (check && typeof result === 'function') {
+          lastError = result;
+          lastErrorIsFactory = true;
+        } else if (result === true || result === undefined) {
           return true; // At least one rule passed
         }
       } catch (error) {
         lastError = error;
+        lastErrorIsFactory = false;
         // Continue to next rule
       }
     }
 
     // No rule passed - throw the last error or return false
+    if (lastErrorIsFactory) {
+      throw lastError();
+    }
     if (lastError) {
       throw lastError;
     }
@@ -213,28 +282,30 @@ const normalizeOwnerId = (value) => {
  */
 export const isOwner = (ownerField = 'userId', userIdField = 'id', options = {}) => {
   const { userPath = 'user' } = options;
+  validatePath('ownerField', ownerField);
+  validatePath('userIdField', userIdField);
+  validatePath('userPath', userPath);
 
-  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 ruleFromCheck((parent, _args, ctx) => {
+    if (!ctx) return unauthenticated;
+    const user = readPath(ctx, userPath);
+    if (user === pending) return pendingValue;
+    if (!user) return unauthenticated;
 
     // Get ownerId from parent (using path or function)
-    const ownerId = normalizeOwnerId(resolvePath(parent, ownerField));
-
+    const owner = readPath(parent, ownerField);
     // Get userId from user object (using path or function)
-    const userId = normalizeOwnerId(resolvePath(user, userIdField));
+    const id = readPath(user, userIdField);
+    if (owner === pending || id === pending) return pendingValue;
+    const ownerId = normalizeOwnerId(owner);
+    const userId = normalizeOwnerId(id);
 
     if (ownerId === undefined || userId === undefined) {
       return false;
     }
 
     return ownerId === userId;
-  };
+  });
 };
 
 /**
@@ -276,9 +347,8 @@ export const allow = () => {
  * @returns {Function} Rule function that always throws ForbiddenError
  */
 export const deny = (message = 'Access denied') => {
-  return () => {
-    throw new ForbiddenError(message);
-  };
+  const forbidden = () => new ForbiddenError(message);
+  return ruleFromCheck(() => forbidden);
 };
 
 // Export all rules as an object for convenience

package/src/auth/thenable.js

@@ -0,0 +1,17 @@
+/** Internal: true for promises and other values that `await` would wait for. */
+export const isThenable = value => value !== null && (typeof value === 'object' || typeof value === 'function')
+  && typeof value.then === 'function';
+
+/**
+ * Internal: handle a native promise from any realm whose result is never used, so its rejection
+ * cannot crash the process. The built-in then() is called directly: it throws for anything that is
+ * not a native promise without running its code, and skips an overriding then(). Other thenables are
+ * left untouched, because calling their then() can start work, such as a lazy query builder.
+ */
+export const discardThenable = (value) => {
+  try {
+    Promise.prototype.then.call(value, undefined, () => {});
+  } catch {
+    // Not a native promise: there is no rejection to handle without running its own then().
+  }
+};

package/src/index.js

@@ -11,6 +11,7 @@ export { default as QLOperator } from './const/QLOperator.js';
 export { default as QLSort } from './const/QLSort.js';
 export { default as QLValue } from './const/QLValue.js';
 export { configureQueryLimits, paginationStages } from './query-limits.js';
+export { configureMutationLimits } from './mutation-limits.js';
 export { default as auth } from './auth/index.js';
 export { default as plugins } from './plugins.js';
 export { default as scalars } from './scalars.js';

package/src/mutation-limits.js

@@ -0,0 +1,24 @@
+import SimfinityError from './errors/simfinity.error.js';
+
+// Process-wide, like the query limits. null leaves nested collection operations unlimited.
+let maxNestedOperations = null;
+
+export const configureMutationLimits = (options = {}) => {
+  if (!options || typeof options !== 'object' || Array.isArray(options)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(options))) {
+    throw new SimfinityError('Mutation limit options must be a plain object', 'INVALID_MUTATION_LIMITS', 400);
+  }
+  // A misspelled option must not silently reset the limit to unlimited.
+  const unknown = Reflect.ownKeys(options).find((key) => key !== 'maxNestedOperations');
+  if (unknown !== undefined) {
+    throw new SimfinityError(`Unknown mutation limit option ${String(unknown)}; use maxNestedOperations`,
+      'INVALID_MUTATION_LIMITS', 400);
+  }
+  const { maxNestedOperations: value = null } = options;
+  if (value !== null && (!Number.isSafeInteger(value) || value < 0)) {
+    throw new SimfinityError('maxNestedOperations must be null or a non-negative safe integer', 'INVALID_MUTATION_LIMITS', 400);
+  }
+  maxNestedOperations = value;
+};
+
+export const getMaxNestedOperations = () => maxNestedOperations;

package/src/relation-owners.js

@@ -0,0 +1,5 @@
+// Internal: generated relation resolvers, the extensions object given to each field that holds one,
+// and Simfinity's own wrappers of those resolvers, mapped to the runtime that generated them.
+// toConfig() copies and field spreads keep the resolver or the extensions object, so a field copied
+// from a bound type still shows whose adapter, registrations and middleware it reads through.
+export const relationFieldOwners = new WeakMap();