@nxgt/shared-graphql 2.0.0 → 2.1.0

package/dist/index.js

@@ -5,31 +5,28 @@ export * from "graphql-subscriptions";
 
 // src/directives/check.ts
 import { getDirective } from "@graphql-tools/utils";
-import {
-  assertRequirement
-} from "@nxgt/ory-sdk";
-var CHECK_DIRECTIVE_NAME = "check";
-function readChecks(schema, node, where) {
-  const found = getDirective(schema, node, CHECK_DIRECTIVE_NAME) ?? [];
-  return found.map((raw) => {
-    const permissions = raw.permissions ?? [];
-    assertRequirement(permissions, `@check on ${where}`);
-    for (const group of permissions) {
-      for (const term of group)
-        assertReadablePath(term, where);
-    }
-    return {
-      permissions,
-      onDeny: raw.onDeny ?? "NOT_FOUND",
-      message: raw.message
-    };
-  });
+
+// src/directives/deprecation.ts
+import { logger } from "@nxgt/shared-logging";
+function warnCheckMistake(message) {
+  logger.warn(`${message} — @check still boots with this; the next major refuses it, as @permission does`);
 }
+
+// src/directives/paths.ts
+var PATH = /^(args|parent|source)(\.[A-Za-z0-9_]+)+$/;
+var DEFAULT_ID_PATH = "args.id";
 function assertReadablePath(term, where) {
-  if (!/^(args|source)(\.[A-Za-z0-9_]+)+$/.test(term.id)) {
-    throw new Error(`@check on ${where}: \`id\` must be "args.<path>" or "source.<path>", got ${JSON.stringify(term.id)}`);
+  if (!PATH.test(term.id)) {
+    throw new TypeError(`${where}: \`id\` must be "args.<path>", "parent.<path>" or "source.<path>", got ${JSON.stringify(term.id)}`);
   }
 }
+function assertDeclaredArgument(term, argumentNames, where) {
+  const [root, name] = term.id.split(".");
+  if (root !== "args" || !name || argumentNames.includes(name))
+    return;
+  const declared = argumentNames.length ? argumentNames.join(", ") : "no arguments";
+  throw new TypeError(`${where}: \`id\` reads "${term.id}", but the field declares ${declared}`);
+}
 function readPath(path, source, args) {
   const [root, ...rest] = path.split(".");
   let value = root === "args" ? args : source;
@@ -42,6 +39,78 @@ function objectIds(value) {
   const values = Array.isArray(value) ? value : [value];
   return values.filter((item) => typeof item === "string" && item.length > 0);
 }
+
+// src/directives/scope.ts
+function scopeOf(node, where, options) {
+  return {
+    where,
+    argumentNames: argumentNamesOf(node),
+    namespaces: options.namespaces
+  };
+}
+function argumentNamesOf(node) {
+  const field = node;
+  if (Array.isArray(field.args))
+    return field.args.map((arg) => arg.name);
+  if (field.args)
+    return Object.keys(field.args);
+  return field.arguments?.map((arg) => arg.name.value) ?? [];
+}
+
+// src/directives/validate.ts
+import { assertRequirement } from "@nxgt/ory-sdk";
+function assertRequirementShape(permissions, scope) {
+  const { where, argumentNames, namespaces } = scope;
+  try {
+    assertRequirement(permissions, where);
+  } catch (error) {
+    throw new TypeError(error.message);
+  }
+  for (const group of permissions) {
+    for (const term of group) {
+      assertReadablePath(term, where);
+      declaredOrReported(term, argumentNames, scope);
+      if (namespaces && !namespaces.includes(term.namespace)) {
+        throw new TypeError(`${where}: unknown namespace ${JSON.stringify(term.namespace)} — known: ${namespaces.join(", ")}`);
+      }
+    }
+  }
+}
+function declaredOrReported(term, argumentNames, scope) {
+  if (!scope.lenient) {
+    assertDeclaredArgument(term, argumentNames, scope.where);
+    return;
+  }
+  try {
+    assertDeclaredArgument(term, argumentNames, scope.where);
+  } catch (error) {
+    scope.lenient(error.message);
+  }
+}
+
+// src/directives/check.ts
+var CHECK_DIRECTIVE_NAME = "check";
+function readChecks(schema, node, where, options = {}) {
+  const found = getDirective(schema, node, CHECK_DIRECTIVE_NAME) ?? [];
+  const scope = {
+    ...scopeOf(node, `@check on ${where}`, options),
+    lenient: warnCheckMistake
+  };
+  return found.map((raw) => {
+    const permissions = withDefaultIds(raw.permissions);
+    assertRequirementShape(permissions, scope);
+    return {
+      permissions,
+      onDeny: raw.onDeny ?? "NOT_FOUND",
+      message: raw.message ?? undefined
+    };
+  });
+}
+function withDefaultIds(raw) {
+  if (!Array.isArray(raw))
+    return raw;
+  return raw.map((group) => Array.isArray(group) ? group.map((term) => term && typeof term === "object" ? { ...term, id: term.id ?? DEFAULT_ID_PATH } : term) : group);
+}
 // src/directives/federation.ts
 var FEDERATION_DIRECTIVES = `
 directive @external on FIELD_DEFINITION | OBJECT
@@ -56,6 +125,204 @@ directive @composeDirective(name: String!) repeatable on SCHEMA
 directive @interfaceObject on OBJECT
 directive @authenticated on FIELD_DEFINITION | OBJECT | INTERFACE | SCALAR | ENUM
 `;
+// src/directives/permission.ts
+import { getDirective as getDirective2 } from "@graphql-tools/utils";
+var PERMISSION_DIRECTIVE_NAME = "permission";
+function readPermissions(schema, node, where, options = {}) {
+  if (!isOurs(schema))
+    return [];
+  const found = getDirective2(schema, node, PERMISSION_DIRECTIVE_NAME) ?? [];
+  const scope = scopeOf(node, `@permission on ${where}`, options);
+  return found.map((raw) => {
+    const args = permissionArgs(raw);
+    const permissions = [
+      [{ namespace: args.type, permit: args.name, id: args.id }]
+    ];
+    assertRequirementShape(permissions, scope);
+    return { permissions, onDeny: args.onDeny, message: args.message };
+  });
+}
+function permissionArgs(raw) {
+  return {
+    name: raw.name,
+    type: raw.type,
+    id: raw.id ?? DEFAULT_ID_PATH,
+    onDeny: raw.onDeny ?? "NOT_FOUND",
+    message: raw.message ?? undefined
+  };
+}
+function isOurs(schema) {
+  const declared = schema.getDirective(PERMISSION_DIRECTIVE_NAME);
+  const names = declared?.args.map((arg) => arg.name) ?? [];
+  return names.includes("name") && names.includes("type");
+}
+// src/directives/requirements.ts
+function readRequirements(schema, node, where, options = {}) {
+  const queues = {
+    [CHECK_DIRECTIVE_NAME]: readChecks(schema, node, where, options),
+    [PERMISSION_DIRECTIVE_NAME]: readPermissions(schema, node, where, options)
+  };
+  const ordered = [];
+  for (const directive of directivesOf(node)) {
+    const next = queues[directive.name.value]?.shift();
+    if (next)
+      ordered.push(next);
+  }
+  return [
+    ...ordered,
+    ...queues[CHECK_DIRECTIVE_NAME] ?? [],
+    ...queues[PERMISSION_DIRECTIVE_NAME] ?? []
+  ];
+}
+function directivesOf(node) {
+  const field = node;
+  return field.astNode?.directives ?? field.directives ?? [];
+}
+// src/directives/sdl.ts
+var CHECK_DIRECTIVE_SDL = `"""
+One question, with the object left as a path instead of a value.
+"""
+input CheckPermission {
+	"""
+	The Keto namespace, e.g. "Note" — from the stack's OPL document.
+	"""
+	namespace: String!
+
+	"""
+	The permit asked of it, e.g. "view". A plain relation works too; Keto
+	answers \`false\`, not an error, for a name it does not know.
+	"""
+	permit: String!
+
+	"""
+	Where the object id is read: \`args.<path>\`, or \`parent.<path>\` /
+	\`source.<path>\` (the same root under two names), dotted paths allowed. A value that turns out to be a LIST requires the permit on every
+	element — that is what a mutation taking \`ids: [ID!]!\` means.
+	"""
+	id: String = "args.id"
+}
+
+"""
+What a denial looks like from outside.
+"""
+enum CheckDenial {
+	"""
+	The same answer as for an id that never existed, so ids cannot be probed.
+	The default, and the one to keep unless the caller already knows the object
+	is there.
+	"""
+	NOT_FOUND
+
+	"""
+	For a second check on an object the caller can already see: a viewer asked
+	to edit already knows it exists, and "you may not change it" is honest.
+	"""
+	FORBIDDEN
+}
+
+"""
+Deprecated: write \`@permission(name:, type:)\` in a new schema — one Keto
+question per directive, repeated for AND, with OR kept in the Keto model. This
+form keeps working and is evaluated in declaration order with @permission.
+
+The permission a field requires, in disjunctive normal form: the OUTER list is
+OR, the INNER list is AND. \`[[A, B], [C]]\` reads "(A and B) or C" — the same
+shape \`@policy(policies: [["ADMIN"]])\` uses.
+
+Repeatable, and evaluated in declaration order, each with its own \`onDeny\`.
+That is how the 404-then-403 ladder is written:
+
+    updateNote(id: ID!, input: UpdateNoteInput!): Note!
+      @check(permissions: [[{ namespace: "Note", permit: "view" }]])
+      @check(permissions: [[{ namespace: "Note", permit: "edit" }]], onDeny: FORBIDDEN)
+
+NOT for a field that answers a LIST the caller is entitled to. "Which notes may
+I see" is not a check, it is a Keto query folded into the database filter
+before the read. A directive there would have to fetch everything and filter
+after, which makes \`totalCount\` and the cursors lie.
+"""
+directive @check(
+	permissions: [[CheckPermission!]!]!
+	onDeny: CheckDenial! = NOT_FOUND
+
+	"""
+	The i18n key the denial carries, e.g. "notes.errors.not-found". Defaults to
+	\`errors.not-found\` / \`errors.insufficient-permissions\`, the shared keys.
+
+	Set it whenever the API's own service layer answers the same refusal with a
+	domain message. Two layers guard these fields — the directive, and the
+	\`require<M>Access\` the service calls — and if they word the same 404
+	differently, the wording tells a caller WHICH one refused: a generic message
+	means "you may not", a domain one means "it is gone". That is precisely the
+	distinction NOT_FOUND exists to hide.
+	"""
+	message: String
+) repeatable on FIELD_DEFINITION
+`;
+var PERMISSION_DIRECTIVE_SDL = `"""
+What a refused @permission looks like from outside.
+"""
+enum PermissionDenial {
+	"""
+	The same answer as for an id that never existed, so ids cannot be probed.
+	The default.
+	"""
+	NOT_FOUND
+
+	"""
+	For a permission asked of an object the caller can already see: a viewer
+	asked to edit already knows it exists, and "you may not change it" is
+	honest.
+	"""
+	FORBIDDEN
+}
+
+"""
+The permission a field requires: the caller must hold the permit \`name\` on the
+\`type\` object whose id \`id\` points at.
+
+Repeatable, and repeated ones are AND, evaluated in declaration order — the
+404-then-403 ladder:
+
+    updateNote(id: ID!, input: UpdateNoteInput!): Note!
+      @permission(name: "view", type: "Note")
+      @permission(name: "edit", type: "Note", onDeny: FORBIDDEN)
+
+NOT for a field that answers a LIST the caller is entitled to: fold a Keto
+query into the database filter before the read instead.
+"""
+directive @permission(
+	"""
+	The permit asked of Keto, e.g. "view". A plain relation works too; Keto
+	answers \`false\`, not an error, for a name it does not know.
+	"""
+	name: String!
+
+	"""
+	The Keto namespace, e.g. "Note" — from the stack's OPL document.
+	"""
+	type: String!
+
+	"""
+	Where the object id is read: \`args.<path>\` or \`parent.<path>\`, dotted
+	paths allowed, \`args.id\` when omitted. A value that turns out to be a LIST
+	requires the permit on every element.
+	"""
+	id: String
+
+	onDeny: PermissionDenial! = NOT_FOUND
+
+	"""
+	The i18n key the denial carries, e.g. "notes.errors.not-found". Defaults to
+	\`errors.not-found\` / \`errors.insufficient-permissions\`, the shared keys.
+	Set it when the service layer words the same refusal with a domain message,
+	so the wording does not tell a caller which layer refused.
+	"""
+	message: String
+) repeatable on FIELD_DEFINITION
+`;
+var KETO_DIRECTIVES_SDL = `${CHECK_DIRECTIVE_SDL}
+${PERMISSION_DIRECTIVE_SDL}`;
 // src/integrations/hono.ts
 import { Hono } from "hono";
 import { contextStorage } from "hono/context-storage";
@@ -251,7 +518,12 @@ function createEntitiesReferenceLoader(model) {
     return ids.map((id) => map.get(id) ?? null);
   });
 }
-// src/utils/errors.utils.ts
+// src/utils/errors/create-error.ts
+import { GraphQLError } from "graphql";
+function createGraphQLError(message, options) {
+  return new GraphQLError(message, options);
+}
+// src/utils/errors/format-error.ts
 import {
   ApolloServerErrorCode,
   unwrapResolverError
@@ -259,25 +531,49 @@ import {
 import {
   translate as translateBase
 } from "@nxgt/i18n";
-import { OryUnavailable } from "@nxgt/ory-sdk";
-import { CustomException, ErrorCode } from "@nxgt/shared-exceptions";
+import { CustomException, ErrorCode as ErrorCode2 } from "@nxgt/shared-exceptions";
 import { MONGO_UTILS, mongoose } from "@nxgt/shared-mongo";
-import { GraphQLError } from "graphql";
 import { kebabCase } from "lodash";
-function createGraphQLError(message, options) {
-  return new GraphQLError(message, options);
+
+// src/utils/errors/ory-unavailable.ts
+import { ErrorCode } from "@nxgt/shared-exceptions";
+import { GraphQLError as GraphQLError2 } from "graphql";
+function isOryUnavailable(error) {
+  if (!(error instanceof Error))
+    return false;
+  const service = error.service;
+  return error.name === "OryUnavailable" && typeof service === "string";
+}
+function serviceUnavailableError(error) {
+  return new GraphQLError2(`ory: ${error.service} is unavailable`, {
+    extensions: {
+      code: ErrorCode.ServiceUnavailable,
+      http: { status: 503 },
+      debugMessage: error.message
+    }
+  });
 }
+
+// src/utils/errors/format-error.ts
 function createFormatError(translate = translateBase, production) {
   return (formattedError, graphQLError) => {
     if (production && formattedError.extensions?.stacktrace) {
       formattedError.extensions.stacktrace = undefined;
     }
     const error = unwrapResolverError(graphQLError);
+    if (isOryUnavailable(error)) {
+      const unavailable = serviceUnavailableError(error);
+      return {
+        ...formattedError,
+        message: unavailable.message,
+        extensions: { ...formattedError.extensions, ...unavailable.extensions }
+      };
+    }
     if (error instanceof CustomException || error instanceof mongoose.MongooseError) {
       const exception = error instanceof mongoose.MongooseError ? MONGO_UTILS.castError(error) : error;
       return {
         ...formattedError,
-        message: exception.errorCode === ErrorCode.ValidationError ? exception.message : translate(exception.message, exception.options),
+        message: exception.errorCode === ErrorCode2.ValidationError ? exception.message : translate(exception.message, exception.options),
         extensions: {
           ...formattedError.extensions,
           code: exception.errorCode,
@@ -306,45 +602,58 @@ function createFormatError(translate = translateBase, production) {
     return formattedError;
   };
 }
-var HTTP_STATUS_BY_CODE = {
-  [ErrorCode.BadRequest]: 400,
-  [ErrorCode.ValidationError]: 400,
-  [ErrorCode.Unauthenticated]: 401,
-  [ErrorCode.Forbidden]: 403,
-  [ErrorCode.NotFound]: 404,
-  [ErrorCode.Conflict]: 409,
-  [ErrorCode.ServiceUnavailable]: 503
-};
-function createMaskError(translate = translateBase) {
+// src/utils/errors/mask-error.ts
+import {
+  translate as translateBase2
+} from "@nxgt/i18n";
+import { CustomException as CustomException2, ErrorCode as ErrorCode3 } from "@nxgt/shared-exceptions";
+import { MONGO_UTILS as MONGO_UTILS2, mongoose as mongoose2 } from "@nxgt/shared-mongo";
+import { GraphQLError as GraphQLError3 } from "graphql";
+function createMaskError(translate = translateBase2) {
   return (error, message, isDev) => {
-    const original = error instanceof GraphQLError && error.originalError ? error.originalError : error;
-    if (original instanceof OryUnavailable) {
-      return new GraphQLError(`ory: ${original.service} is unavailable`, {
-        extensions: {
-          code: ErrorCode.ServiceUnavailable,
-          http: { status: 503 },
-          debugMessage: original.message
-        }
-      });
+    const original = error instanceof GraphQLError3 && error.originalError ? error.originalError : error;
+    if (isOryUnavailable(original))
+      return serviceUnavailableError(original);
+    if (original instanceof CustomException2 || original instanceof mongoose2.MongooseError) {
+      return exceptionError(original, translate);
     }
-    if (original instanceof CustomException || original instanceof mongoose.MongooseError) {
-      const exception = original instanceof mongoose.MongooseError ? MONGO_UTILS.castError(original) : original;
-      const status = exception.code;
-      return new GraphQLError(exception.errorCode === ErrorCode.ValidationError ? exception.message : translate(exception.message, exception.options), {
-        extensions: {
-          code: exception.errorCode,
-          ...status ? { http: { status } } : {},
-          ...exception.debugMessage ? { debugMessage: exception.debugMessage } : {}
-        }
-      });
-    }
-    if (error instanceof GraphQLError)
+    if (isOriginalGraphQLError(error))
       return error;
-    return new GraphQLError(message, {
-      extensions: isDev ? { code: ErrorCode.InternalServerError, debugMessage: String(error) } : { code: ErrorCode.InternalServerError }
+    return new GraphQLError3(message, {
+      ...locationOf(error),
+      extensions: isDev ? {
+        code: ErrorCode3.InternalServerError,
+        debugMessage: String(original)
+      } : { code: ErrorCode3.InternalServerError }
     });
   };
 }
+function exceptionError(original, translate) {
+  const exception = original instanceof mongoose2.MongooseError ? MONGO_UTILS2.castError(original) : original;
+  const status = exception.code;
+  return new GraphQLError3(exception.errorCode === ErrorCode3.ValidationError ? exception.message : translate(exception.message, exception.options), {
+    extensions: {
+      code: exception.errorCode,
+      ...status ? { http: { status } } : {},
+      ...exception.debugMessage ? { debugMessage: exception.debugMessage } : {}
+    }
+  });
+}
+function isOriginalGraphQLError(error) {
+  if (!(error instanceof GraphQLError3))
+    return false;
+  return error.originalError == null ? true : isOriginalGraphQLError(error.originalError);
+}
+function locationOf(error) {
+  if (!(error instanceof GraphQLError3))
+    return {};
+  return {
+    nodes: error.nodes,
+    source: error.source,
+    positions: error.positions,
+    path: error.path
+  };
+}
 // src/utils/publish.ts
 import { createRedisEventTarget } from "@graphql-yoga/redis-event-target";
 import { createPubSub } from "graphql-yoga";
@@ -506,6 +815,74 @@ function createYogaHono(yoga, options) {
   app.use(yoga.graphqlEndpoint, honoYoga(yoga));
   return app;
 }
+// src/plugins/apply-keto-checks.ts
+import { getDirective as getDirective3, MapperKind, mapSchema } from "@graphql-tools/utils";
+import { evaluateRequirement } from "@nxgt/ory-sdk";
+import { CustomException as CustomException3 } from "@nxgt/shared-exceptions";
+import {
+  defaultFieldResolver
+} from "graphql";
+function applyKetoChecks(schema, options = {}) {
+  return mapSchema(schema, {
+    [MapperKind.INTERFACE_FIELD]: (fieldConfig, fieldName, typeName) => {
+      refuseOnInterface(schema, fieldConfig, `${typeName}.${fieldName}`);
+      return fieldConfig;
+    },
+    [MapperKind.OBJECT_FIELD]: (fieldConfig, fieldName, typeName) => {
+      const where = `${typeName}.${fieldName}`;
+      const requirements = readRequirements(schema, fieldConfig, where, options);
+      if (requirements.length === 0)
+        return fieldConfig;
+      return guarded(fieldConfig, requirements, where);
+    }
+  });
+}
+function refuseOnInterface(schema, fieldConfig, where) {
+  const message = `${where}: @check / @permission on an interface field guards nothing — no resolver runs there. Put it on each implementing type's field`;
+  if (readPermissions(schema, fieldConfig, where).length > 0) {
+    throw new TypeError(message);
+  }
+  if (getDirective3(schema, fieldConfig, CHECK_DIRECTIVE_NAME)?.length) {
+    warnCheckMistake(message);
+  }
+}
+function guarded(fieldConfig, requirements, where) {
+  const resolve = fieldConfig.resolve ?? defaultFieldResolver;
+  return {
+    ...fieldConfig,
+    resolve: async (source, args, context, info) => {
+      const ctx = context;
+      const subject = ctx.ory?.subject;
+      if (!subject) {
+        throw CustomException3.unauthenticated({
+          message: "errors.unauthenticated"
+        });
+      }
+      const check = ctx.ketoChecks;
+      if (!check) {
+        throw new Error(`${where}: no checker on the context — useKetoChecks(ory) is not registered`);
+      }
+      for (const { permissions, onDeny, message } of requirements) {
+        const allowed = await evaluateRequirement(permissions, (term) => objectsOf(term, source, args, where), check, subject);
+        if (!allowed)
+          throw denial(onDeny, message);
+      }
+      return resolve(source, args, context, info);
+    }
+  };
+}
+function objectsOf(term, source, args, where) {
+  const ids = objectIds(readPath(term.id, source, args));
+  if (ids.length === 0) {
+    throw new Error(`${where}: "${term.id}" resolved no object id`);
+  }
+  return ids;
+}
+function denial(onDeny, message) {
+  return onDeny === "FORBIDDEN" ? CustomException3.forbidden({
+    message: message ?? "errors.insufficient-permissions"
+  }) : CustomException3.notFound({ message: message ?? "errors.not-found" });
+}
 // src/plugins/auth.ts
 function useAuth() {
   return {
@@ -518,82 +895,32 @@ function useAuth() {
   };
 }
 // src/plugins/extract-jwt.ts
-import { logger } from "@nxgt/shared-logging";
+import { logger as logger2 } from "@nxgt/shared-logging";
 var extractJwtPlugin = {
   async requestDidStart({ request, contextValue }) {
-    logger.info(`[${request.extensions?.subgraphName}] Extracting JWT from request extensions: ${request.extensions?.payload?.sub}`, request.extensions);
+    logger2.info(`[${request.extensions?.subgraphName}] Extracting JWT from request extensions: ${request.extensions?.payload?.sub}`, request.extensions);
     contextValue.jwt = {
       payload: request.extensions?.payload
     };
   }
 };
-// src/plugins/keto-checks.ts
-import { MapperKind, mapSchema } from "@graphql-tools/utils";
-import {
-  evaluateRequirement,
-  tuple
-} from "@nxgt/ory-sdk";
-import { CustomException as CustomException2 } from "@nxgt/shared-exceptions";
+// src/plugins/keto-checker.ts
+import { tuple } from "@nxgt/ory-sdk";
 import DataLoader2 from "dataloader";
-import { defaultFieldResolver } from "graphql";
 function createKetoChecks(ory) {
   const loader = new DataLoader2((questions) => ory.checkMany([...questions]), {
     cacheKeyFn: ({ permission, subject }) => tuple(permission, subject)
   });
   return (permission, subject) => loader.load({ permission, subject });
 }
-function applyKetoChecks(schema) {
-  return mapSchema(schema, {
-    [MapperKind.OBJECT_FIELD]: (fieldConfig, fieldName, typeName) => {
-      const where = `${typeName}.${fieldName}`;
-      const checks = readChecks(schema, fieldConfig, where);
-      if (checks.length === 0)
-        return fieldConfig;
-      const resolve = fieldConfig.resolve ?? defaultFieldResolver;
-      return {
-        ...fieldConfig,
-        resolve: async (source, args, context, info) => {
-          const ctx = context;
-          const subject = ctx.ory?.subject;
-          if (!subject) {
-            throw CustomException2.unauthenticated({
-              message: "errors.unauthenticated"
-            });
-          }
-          const check = ctx.ketoChecks;
-          if (!check) {
-            throw new Error(`@check on ${where}: no checker on the context — useKetoChecks(ory) is not registered`);
-          }
-          for (const { permissions, onDeny, message } of checks) {
-            const allowed = await evaluateRequirement(permissions, (term) => objectsOf(term, source, args, where), check, subject);
-            if (!allowed)
-              throw denial(onDeny, message);
-          }
-          return resolve(source, args, context, info);
-        }
-      };
-    }
-  });
-}
-function objectsOf(term, source, args, where) {
-  const ids = objectIds(readPath(term.id, source, args));
-  if (ids.length === 0) {
-    throw new Error(`@check on ${where}: "${term.id}" resolved no object id`);
-  }
-  return ids;
-}
-function denial(onDeny, message) {
-  return onDeny === "FORBIDDEN" ? CustomException2.forbidden({
-    message: message ?? "errors.insufficient-permissions"
-  }) : CustomException2.notFound({ message: message ?? "errors.not-found" });
-}
-function useKetoChecks(ory) {
+// src/plugins/keto-checks.ts
+function useKetoChecks(ory, options = {}) {
   const transformed = new WeakSet;
   return {
     onSchemaChange: ({ schema, replaceSchema }) => {
       if (transformed.has(schema))
         return;
-      const next = applyKetoChecks(schema);
+      const next = applyKetoChecks(schema, options);
       transformed.add(next);
       replaceSchema(next);
     },
@@ -602,13 +929,38 @@ function useKetoChecks(ory) {
     }
   };
 }
+// src/plugins/keto-helpers.ts
+import { CustomException as CustomException4 } from "@nxgt/shared-exceptions";
+function requireUser(context) {
+  if (!context.user) {
+    throw CustomException4.unauthenticated({
+      message: "errors.unauthenticated"
+    });
+  }
+  return context.user;
+}
+async function can(context, question) {
+  const subject = context.ory?.subject;
+  if (!subject) {
+    throw CustomException4.unauthenticated({
+      message: "errors.unauthenticated"
+    });
+  }
+  if (!context.ketoChecks) {
+    throw new Error("can(): no checker on the context — useKetoChecks(ory) is not registered");
+  }
+  const permission = {
+    namespace: question.type,
+    object: question.id,
+    relation: question.name
+  };
+  return context.ketoChecks(permission, subject);
+}
 // src/plugins/ory-auth.ts
 import {
-  bearerOf,
-  OryUnavailable as OryUnavailable2
+  bearerOf
 } from "@nxgt/ory-sdk";
 import { claimsFromOryPrincipal } from "@nxgt/security/integrations/ory";
-import { GraphQLError as GraphQLError2 } from "graphql";
 function toPrincipal(ory) {
   const email = ory.identity?.email;
   return {
@@ -625,20 +977,14 @@ function toPrincipal(ory) {
   };
 }
 function oryUnavailableError(error) {
-  return new GraphQLError2(`ory: ${error.service} is unavailable`, {
-    extensions: {
-      code: "SERVICE_UNAVAILABLE",
-      http: { status: 503 },
-      debugMessage: error.message
-    }
-  });
+  return serviceUnavailableError(error);
 }
 async function resolveOryPrincipal(ory, headers) {
   let principal;
   try {
     principal = await ory.resolve(headers);
   } catch (error) {
-    if (error instanceof OryUnavailable2)
+    if (isOryUnavailable(error))
       throw oryUnavailableError(error);
     throw error;
   }
@@ -747,15 +1093,15 @@ import {
 } from "graphql-scalars";
 
 // src/scalars/custom/utils.ts
-import { CustomException as CustomException3 } from "@nxgt/shared-exceptions";
-import { logger as logger2 } from "@nxgt/shared-logging";
+import { CustomException as CustomException5 } from "@nxgt/shared-exceptions";
+import { logger as logger3 } from "@nxgt/shared-logging";
 import { GraphQLScalarType as GraphQLScalarType2 } from "graphql";
 function createScalarFrom(scalar, {
   name,
   description,
   errorMessage
 }) {
-  const exception = CustomException3.badRequest({
+  const exception = CustomException5.badRequest({
     message: errorMessage
   });
   return new GraphQLScalarType2({
@@ -769,7 +1115,7 @@ function createScalarFrom(scalar, {
       try {
         return scalar.serialize(value);
       } catch (e) {
-        logger2.error(e);
+        logger3.error(e);
         throw exception;
       }
     },
@@ -780,18 +1126,18 @@ function createScalarFrom(scalar, {
       try {
         return scalar.parseValue(value);
       } catch (e) {
-        logger2.error(e);
+        logger3.error(e);
         throw exception;
       }
     },
-    parseLiteral(ast) {
+    parseLiteral(ast, variables) {
       if (!errorMessage) {
-        return scalar.parseLiteral(ast);
+        return scalar.parseLiteral(ast, variables);
       }
       try {
-        return scalar.parseLiteral(ast);
+        return scalar.parseLiteral(ast, variables);
       } catch (e) {
-        logger2.error(e);
+        logger3.error(e);
         throw exception;
       }
     }
@@ -995,8 +1341,12 @@ directive @link(url: String!, import: [String!]) on SCHEMA
 import graphqlUploadExpress from "graphql-upload/graphqlUploadExpress.mjs";
 export {
   CHECK_DIRECTIVE_NAME,
+  CHECK_DIRECTIVE_SDL,
   DataLoader3 as DataLoader,
   FEDERATION_DIRECTIVES,
+  KETO_DIRECTIVES_SDL,
+  PERMISSION_DIRECTIVE_NAME,
+  PERMISSION_DIRECTIVE_SDL,
   SCALARS_MAPPING,
   SCALAR_RESOLVERS,
   SHARED_SCHEMA_PATH,
@@ -1004,6 +1354,7 @@ export {
   applyKetoChecks,
   assertReadablePath,
   buildSubgraphSchema,
+  can,
   createChangeResolvers,
   createChildrenConnectionDataLoader,
   createChildrenListDataLoader,
@@ -1022,15 +1373,20 @@ export {
   generateSchema,
   graphqlUploadExpress,
   honoYoga,
+  isOryUnavailable,
   loadTypeDefs,
   objectIds,
   oryUnavailableError,
   readChecks,
   readPath,
+  readPermissions,
+  readRequirements,
   renderSandbox,
+  requireUser,
   resolveOryPrincipal,
   resolveWsUser,
   sandboxExpolorer,
+  serviceUnavailableError,
   setupYogaWebSocketServer,
   toPrincipal,
   useAuth,
@@ -1038,5 +1394,5 @@ export {
   useOryAuth
 };
 
-//# debugId=6FBEA5C770B5605F64756E2164756E21
+//# debugId=E72214B01404888264756E2164756E21
 //# sourceMappingURL=index.js.map