graphql-shield-node23 7.6.5

package/src/rules.ts

@@ -0,0 +1,521 @@
+import * as Yup from 'yup'
+import {
+  IRuleFunction,
+  IRule,
+  IRuleOptions,
+  ICache,
+  IFragment,
+  ICacheContructorOptions,
+  IRuleConstructorOptions,
+  ILogicRule,
+  ShieldRule,
+  IRuleResult,
+  IOptions,
+  IShieldContext,
+} from './types.js'
+import { isLogicRule } from './utils.js'
+import { GraphQLResolveInfo } from 'graphql'
+
+export class Rule implements IRule {
+  readonly name: string
+
+  private cache: ICache
+  private fragment?: IFragment
+  private func: IRuleFunction
+
+  constructor(
+    name: string,
+    func: IRuleFunction,
+    constructorOptions: IRuleConstructorOptions,
+  ) {
+    const options = this.normalizeOptions(constructorOptions)
+
+    this.name = name
+    this.func = func
+    this.cache = options.cache
+    this.fragment = options.fragment
+  }
+
+  /**
+   *
+   * @param parent
+   * @param args
+   * @param ctx
+   * @param info
+   *
+   * Resolves rule and writes to cache its result.
+   *
+   */
+  async resolve(
+    parent: object,
+    args: object,
+    ctx: IShieldContext,
+    info: GraphQLResolveInfo,
+    options: IOptions,
+  ): Promise<IRuleResult> {
+    try {
+      /* Resolve */
+      const res = await this.executeRule(parent, args, ctx, info, options)
+
+      if (res instanceof Error) {
+        return res
+      } else if (typeof res === 'string') {
+        return new Error(res)
+      } else if (res === true) {
+        return true
+      } else {
+        return false
+      }
+    } catch (err) {
+      if (options.debug) {
+        throw err
+      } else {
+        return false
+      }
+    }
+  }
+
+  /**
+   *
+   * @param rule
+   *
+   * Compares a given rule with the current one
+   * and checks whether their functions are equal.
+   *
+   */
+  equals(rule: Rule): boolean {
+    return this.func === rule.func
+  }
+
+  /**
+   *
+   * Extracts fragment from the rule.
+   *
+   */
+  extractFragment(): IFragment | undefined {
+    return this.fragment
+  }
+
+  /**
+   *
+   * @param options
+   *
+   * Sets default values for options.
+   *
+   */
+  private normalizeOptions(options: IRuleConstructorOptions): IRuleOptions {
+    return {
+      cache:
+        options.cache !== undefined
+          ? this.normalizeCacheOption(options.cache)
+          : 'no_cache',
+      fragment: options.fragment !== undefined ? options.fragment : undefined,
+    }
+  }
+
+  /**
+   *
+   * @param cache
+   *
+   * This ensures backward capability of shield.
+   *
+   */
+  private normalizeCacheOption(cache: ICacheContructorOptions): ICache {
+    switch (cache) {
+      case true: {
+        return 'strict'
+      }
+      case false: {
+        return 'no_cache'
+      }
+      default: {
+        return cache
+      }
+    }
+  }
+
+  /**
+   * Executes a rule and writes to cache if needed.
+   *
+   * @param parent
+   * @param args
+   * @param ctx
+   * @param info
+   */
+  private executeRule(
+    parent: object,
+    args: object,
+    ctx: IShieldContext,
+    info: GraphQLResolveInfo,
+    options: IOptions,
+  ): string | boolean | Error | Promise<IRuleResult> {
+    switch (typeof this.cache) {
+      case 'function': {
+        /* User defined cache function. */
+        const key = `${this.name}-${this.cache(parent, args, ctx, info)}`
+        return this.writeToCache(key)(parent, args, ctx, info)
+      }
+      case 'string': {
+        /* Standard cache option. */
+        switch (this.cache) {
+          case 'strict': {
+            const key = options.hashFunction({ parent, args })
+
+            return this.writeToCache(`${this.name}-${key}`)(
+              parent,
+              args,
+              ctx,
+              info,
+            )
+          }
+          case 'contextual': {
+            return this.writeToCache(this.name)(parent, args, ctx, info)
+          }
+          case 'no_cache': {
+            return this.func(parent, args, ctx, info)
+          }
+        }
+      }
+      /* istanbul ignore next */
+      default: {
+        throw new Error(`Unsupported cache format: ${typeof this.cache}`)
+      }
+    }
+  }
+
+  /**
+   * Writes or reads result from cache.
+   *
+   * @param key
+   */
+
+  private writeToCache(
+    key: string,
+  ): (
+    parent: object,
+    args: object,
+    ctx: IShieldContext,
+    info: GraphQLResolveInfo,
+  ) => string | boolean | Error | Promise<IRuleResult> {
+    return (parent, args, ctx, info) => {
+      if (!ctx._shield.cache[key]) {
+        ctx._shield.cache[key] = this.func(parent, args, ctx, info)
+      }
+      return ctx._shield.cache[key]
+    }
+  }
+}
+
+export class InputRule<T> extends Rule {
+  constructor(
+    name: string,
+    schema: (yup: typeof Yup, ctx: IShieldContext) => Yup.BaseSchema<T>,
+    options?: Parameters<Yup.BaseSchema<T>['validate']>[1],
+  ) {
+    const validationFunction: IRuleFunction = (
+      parent: object,
+      args: object,
+      ctx: IShieldContext,
+    ) =>
+      schema(Yup, ctx)
+        .validate(args, options)
+        .then(() => true)
+        .catch((err) => err)
+
+    super(name, validationFunction, { cache: 'strict', fragment: undefined })
+  }
+}
+
+export class LogicRule implements ILogicRule {
+  private rules: ShieldRule[]
+
+  constructor(rules: ShieldRule[]) {
+    this.rules = rules
+  }
+
+  /**
+   * By default logic rule resolves to false.
+   */
+  async resolve(
+    parent: object,
+    args: object,
+    ctx: IShieldContext,
+    info: GraphQLResolveInfo,
+    options: IOptions,
+  ): Promise<IRuleResult> {
+    return false
+  }
+
+  /**
+   * Evaluates all the rules.
+   */
+  async evaluate(
+    parent: object,
+    args: object,
+    ctx: IShieldContext,
+    info: GraphQLResolveInfo,
+    options: IOptions,
+  ): Promise<IRuleResult[]> {
+    const rules = this.getRules()
+    const tasks = rules.map((rule) =>
+      rule.resolve(parent, args, ctx, info, options),
+    )
+
+    return Promise.all(tasks)
+  }
+
+  /**
+   * Returns rules in a logic rule.
+   */
+  getRules() {
+    return this.rules
+  }
+
+  /**
+   * Extracts fragments from the defined rules.
+   */
+  extractFragments(): IFragment[] {
+    const fragments = this.rules.reduce<IFragment[]>((fragments, rule) => {
+      if (isLogicRule(rule)) {
+        return fragments.concat(...rule.extractFragments())
+      }
+
+      const fragment = rule.extractFragment()
+      if (fragment) return fragments.concat(fragment)
+
+      return fragments
+    }, [])
+
+    return fragments
+  }
+}
+
+// Extended Types
+
+export class RuleOr extends LogicRule {
+  constructor(rules: ShieldRule[]) {
+    super(rules)
+  }
+
+  /**
+   * Makes sure that at least one of them has evaluated to true.
+   */
+  async resolve(
+    parent: object,
+    args: object,
+    ctx: IShieldContext,
+    info: GraphQLResolveInfo,
+    options: IOptions,
+  ): Promise<IRuleResult> {
+    const result = await this.evaluate(parent, args, ctx, info, options)
+
+    if (result.every((res) => res !== true)) {
+      const customError = result.find((res) => res instanceof Error)
+      return customError || false
+    } else {
+      return true
+    }
+  }
+}
+
+export class RuleAnd extends LogicRule {
+  constructor(rules: ShieldRule[]) {
+    super(rules)
+  }
+
+  /**
+   * Makes sure that all of them have resolved to true.
+   */
+  async resolve(
+    parent: object,
+    args: object,
+    ctx: IShieldContext,
+    info: GraphQLResolveInfo,
+    options: IOptions,
+  ): Promise<IRuleResult> {
+    const result = await this.evaluate(parent, args, ctx, info, options)
+
+    if (result.some((res) => res !== true)) {
+      const customError = result.find((res) => res instanceof Error)
+      return customError || false
+    } else {
+      return true
+    }
+  }
+}
+
+export class RuleChain extends LogicRule {
+  constructor(rules: ShieldRule[]) {
+    super(rules)
+  }
+
+  /**
+   * Makes sure that all of them have resolved to true.
+   */
+  async resolve(
+    parent: object,
+    args: object,
+    ctx: IShieldContext,
+    info: GraphQLResolveInfo,
+    options: IOptions,
+  ): Promise<IRuleResult> {
+    const result = await this.evaluate(parent, args, ctx, info, options)
+
+    if (result.some((res) => res !== true)) {
+      const customError = result.find((res) => res instanceof Error)
+      return customError || false
+    } else {
+      return true
+    }
+  }
+
+  /**
+   * Evaluates all the rules.
+   */
+  async evaluate(
+    parent: object,
+    args: object,
+    ctx: IShieldContext,
+    info: GraphQLResolveInfo,
+    options: IOptions,
+  ): Promise<IRuleResult[]> {
+    const rules = this.getRules()
+
+    return iterate(rules)
+
+    async function iterate([rule, ...otherRules]: ShieldRule[]): Promise<
+      IRuleResult[]
+    > {
+      if (rule === undefined) return []
+      return rule.resolve(parent, args, ctx, info, options).then((res) => {
+        if (res !== true) {
+          return [res]
+        } else {
+          return iterate(otherRules).then((ress) => ress.concat(res))
+        }
+      })
+    }
+  }
+}
+
+export class RuleRace extends LogicRule {
+  constructor(rules: ShieldRule[]) {
+    super(rules)
+  }
+
+  /**
+   * Makes sure that at least one of them resolved to true.
+   */
+  async resolve(
+    parent: object,
+    args: object,
+    ctx: IShieldContext,
+    info: GraphQLResolveInfo,
+    options: IOptions,
+  ): Promise<IRuleResult> {
+    const result = await this.evaluate(parent, args, ctx, info, options)
+
+    if (result.some((res) => res === true)) {
+      return true
+    } else {
+      const customError = result.find((res) => res instanceof Error)
+      return customError || false
+    }
+  }
+
+  /**
+   * Evaluates all the rules.
+   */
+  async evaluate(
+    parent: object,
+    args: object,
+    ctx: IShieldContext,
+    info: GraphQLResolveInfo,
+    options: IOptions,
+  ): Promise<IRuleResult[]> {
+    const rules = this.getRules()
+
+    return iterate(rules)
+
+    async function iterate([rule, ...otherRules]: ShieldRule[]): Promise<
+      IRuleResult[]
+    > {
+      if (rule === undefined) return []
+      return rule.resolve(parent, args, ctx, info, options).then((res) => {
+        if (res === true) {
+          return [res]
+        } else {
+          return iterate(otherRules).then((ress) => ress.concat(res))
+        }
+      })
+    }
+  }
+}
+
+export class RuleNot extends LogicRule {
+  error?: Error
+
+  constructor(rule: ShieldRule, error?: Error) {
+    super([rule])
+    this.error = error
+  }
+
+  /**
+   *
+   * @param parent
+   * @param args
+   * @param ctx
+   * @param info
+   *
+   * Negates the result.
+   *
+   */
+  async resolve(
+    parent: object,
+    args: object,
+    ctx: IShieldContext,
+    info: GraphQLResolveInfo,
+    options: IOptions,
+  ): Promise<IRuleResult> {
+    const [res] = await this.evaluate(parent, args, ctx, info, options)
+
+    if (res instanceof Error) {
+      return true
+    } else if (res !== true) {
+      return true
+    } else {
+      if (this.error) return this.error
+      return false
+    }
+  }
+}
+
+export class RuleTrue extends LogicRule {
+  constructor() {
+    super([])
+  }
+
+  /**
+   *
+   * Always true.
+   *
+   */
+  async resolve(): Promise<IRuleResult> {
+    return true
+  }
+}
+
+export class RuleFalse extends LogicRule {
+  constructor() {
+    super([])
+  }
+
+  /**
+   *
+   * Always false.
+   *
+   */
+  async resolve(): Promise<IRuleResult> {
+    return false
+  }
+}

package/src/shield.ts

@@ -0,0 +1,53 @@
+import hash from 'object-hash'
+import { middleware, IMiddlewareGenerator } from 'graphql-middleware'
+import { ValidationError, validateRuleTree } from './validation.js'
+import { IRules, IOptions, IOptionsConstructor, ShieldRule, IHashFunction, IFallbackErrorType } from './types.js'
+import { generateMiddlewareGeneratorFromRuleTree } from './generator.js'
+import { allow } from './constructors.js'
+import { withDefault } from './utils.js'
+
+/**
+ *
+ * @param options
+ *
+ * Makes sure all of defined rules are in accord with the options
+ * shield can process.
+ *
+ */
+function normalizeOptions(options: IOptionsConstructor): IOptions {
+  if (typeof options.fallbackError === 'string') {
+    options.fallbackError = new Error(options.fallbackError)
+  }
+
+  return {
+    debug: options.debug !== undefined ? options.debug : false,
+    allowExternalErrors: withDefault(false)(options.allowExternalErrors),
+    fallbackRule: withDefault<ShieldRule>(allow)(options.fallbackRule),
+    fallbackError: withDefault<IFallbackErrorType>(new Error('Not Authorised!'))(options.fallbackError),
+    hashFunction: withDefault<IHashFunction>(hash)(options.hashFunction),
+  }
+}
+
+/**
+ *
+ * @param ruleTree
+ * @param options
+ *
+ * Validates rules and generates middleware from defined rule tree.
+ *
+ */
+export function shield<TSource = any, TContext = any, TArgs = any>(
+  ruleTree: IRules,
+  options: IOptionsConstructor = {},
+): IMiddlewareGenerator<TSource, TContext, TArgs> {
+  const normalizedOptions = normalizeOptions(options)
+  const ruleTreeValidity = validateRuleTree(ruleTree)
+
+  if (ruleTreeValidity.status === 'ok') {
+    const generatorFunction = generateMiddlewareGeneratorFromRuleTree<TSource, TContext, TArgs>(ruleTree, normalizedOptions)
+
+    return middleware(generatorFunction)
+  } else {
+    throw new ValidationError(ruleTreeValidity.message)
+  }
+}

package/src/types.ts

@@ -0,0 +1,94 @@
+import { GraphQLResolveInfo } from 'graphql'
+import { IMiddlewareGenerator } from 'graphql-middleware'
+
+// Rule
+
+export type ShieldRule = IRule | ILogicRule
+
+export interface IRule {
+  readonly name: string
+
+  equals(rule: IRule): boolean
+  extractFragment(): IFragment | undefined
+  resolve(parent: object, args: object, ctx: IShieldContext, info: GraphQLResolveInfo, options: IOptions): Promise<IRuleResult>
+}
+
+export interface IRuleOptions {
+  cache: ICache
+  fragment?: IFragment
+}
+
+export interface ILogicRule {
+  getRules(): ShieldRule[]
+  extractFragments(): IFragment[]
+  evaluate(parent: object, args: object, ctx: IShieldContext, info: GraphQLResolveInfo, options: IOptions): Promise<IRuleResult[]>
+  resolve(parent: object, args: object, ctx: IShieldContext, info: GraphQLResolveInfo, options: IOptions): Promise<IRuleResult>
+}
+
+export type IFragment = string
+export type ICache = 'strict' | 'contextual' | 'no_cache' | ICacheKeyFn
+export type ICacheKeyFn = (parent: any, args: any, ctx: any, info: GraphQLResolveInfo) => string
+export type IRuleResult = boolean | string | Error
+export type IRuleFunction = (parent: any, args: any, ctx: any, info: GraphQLResolveInfo) => IRuleResult | Promise<IRuleResult>
+
+// Rule Constructor Options
+
+export type ICacheContructorOptions = ICache | boolean
+
+export interface IRuleConstructorOptions {
+  cache?: ICacheContructorOptions
+  fragment?: IFragment
+}
+
+// Rules Definition Tree
+
+export interface IRuleTypeMap {
+  [key: string]: ShieldRule | IRuleFieldMap
+}
+
+export interface IRuleFieldMap {
+  [key: string]: ShieldRule
+}
+
+export type IRules = ShieldRule | IRuleTypeMap
+
+export type IHashFunction = (arg: { parent: any; args: any }) => string
+
+export type IFallbackErrorMapperType = (
+  err: unknown,
+  parent: object,
+  args: object,
+  ctx: IShieldContext,
+  info: GraphQLResolveInfo,
+) => Promise<Error> | Error
+
+export type IFallbackErrorType = Error | IFallbackErrorMapperType
+
+// Generator Options
+
+export interface IOptions {
+  debug: boolean
+  allowExternalErrors: boolean
+  fallbackRule: ShieldRule
+  fallbackError?: IFallbackErrorType
+  hashFunction: IHashFunction
+}
+
+export interface IOptionsConstructor {
+  debug?: boolean
+  allowExternalErrors?: boolean
+  fallbackRule?: ShieldRule
+  fallbackError?: string | IFallbackErrorType
+  hashFunction?: IHashFunction
+}
+
+export declare function shield<TSource = any, TContext = any, TArgs = any>(
+  ruleTree: IRules,
+  options: IOptions,
+): IMiddlewareGenerator<TSource, TContext, TArgs>
+
+export interface IShieldContext {
+  _shield: {
+    cache: { [key: string]: IRuleResult | Promise<IRuleResult> }
+  }
+}