buro26-strapi-graphql 0.0.26 → 0.2.0

package/dist/server/utils/registry/global-registry.d.ts

@@ -0,0 +1,63 @@
+import type { ResolverFunction } from '../../types';
+import type { Middleware } from '../../nexus';
+/**
+ * Information about a field, passed to matchers of global middleware/authorization.
+ *
+ * Matchers are evaluated when the GraphQL schema is built (not when a field builder is built), so
+ * registration order no longer matters.
+ */
+export type FieldMatcherInfo = {
+    /** GraphQL parent type name, e.g. `Query` or `Customer` */
+    type: string;
+    fieldName: string;
+    /** Tags set via the field builder (`.tag()`); empty for fields not created by the builder */
+    tags: string[];
+    /** Content type UID when the parent type is a Strapi content type, e.g. `api::customer.customer` */
+    contentType?: string;
+    /** True when the field was created with `createGraphQLFieldBuilder()` */
+    isBuilderField: boolean;
+};
+/**
+ * Decides whether a global middleware/authorization applies to a field. Called once per field when the
+ * schema is built, not per request.
+ */
+export type FieldMatcher = (info: FieldMatcherInfo) => boolean;
+/**
+ * Options for {@link registerGlobalAuthorize} and {@link registerGlobalMiddleware}.
+ */
+export type GlobalRegistrationOptions = {
+    /**
+     * Also apply to fields not created by the field builder: Strapi's generated fields, `overrideField`
+     * and plain Nexus fields. Matchers then run for **every** field in the schema, so keep them cheap and
+     * specific (use `contentType`, `type` or `fieldName`).
+     *
+     * @default false
+     */
+    includeNonBuilderFields?: boolean;
+};
+/**
+ * Register a middleware for all fields that match. Global middlewares wrap field middlewares (they run
+ * first). Matched when the schema is built, so registration order relative to fields does not matter;
+ * register before Strapi's bootstrap (i.e. at module level in a `graphql` folder).
+ *
+ * @param matcher - Decides per field; see {@link FieldMatcherInfo}.
+ * @param middleware - `(next) => resolver`, as in `.middleware()`.
+ * @param options - See {@link GlobalRegistrationOptions}.
+ *
+ * @example
+ * registerGlobalMiddleware(({ tags }) => tags.includes('audit'), auditLog)
+ */
+export declare function registerGlobalMiddleware(matcher: FieldMatcher, middleware: Middleware, options?: GlobalRegistrationOptions): void;
+/**
+ * Register an authorization check for all fields that match. Global checks run before the field's own
+ * checks; all must return `true`. Matched when the schema is built, so registration order does not matter.
+ *
+ * @param matcher - Decides per field; see {@link FieldMatcherInfo}.
+ * @param authorize - Return `true` to allow, `false` or an `Error` to deny.
+ * @param options - See {@link GlobalRegistrationOptions}.
+ *
+ * @example
+ * // Rate limit every field, including Strapi's generated ones
+ * registerGlobalAuthorize(() => true, rateLimit, { includeNonBuilderFields: true })
+ */
+export declare function registerGlobalAuthorize(matcher: FieldMatcher, authorize: ResolverFunction, options?: GlobalRegistrationOptions): void;

package/dist/server/utils/registry/global-registry.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resetGlobalRegistry = exports.getGlobalAuthorizes = exports.getGlobalMiddlewares = exports.registerGlobalAuthorize = exports.registerGlobalMiddleware = void 0;
+const globalMiddlewares = [];
+const globalAuthorizes = [];
+/**
+ * Register a middleware for all fields that match. Global middlewares wrap field middlewares (they run
+ * first). Matched when the schema is built, so registration order relative to fields does not matter;
+ * register before Strapi's bootstrap (i.e. at module level in a `graphql` folder).
+ *
+ * @param matcher - Decides per field; see {@link FieldMatcherInfo}.
+ * @param middleware - `(next) => resolver`, as in `.middleware()`.
+ * @param options - See {@link GlobalRegistrationOptions}.
+ *
+ * @example
+ * registerGlobalMiddleware(({ tags }) => tags.includes('audit'), auditLog)
+ */
+function registerGlobalMiddleware(matcher, middleware, options = {}) {
+    globalMiddlewares.push({ matcher, value: middleware, options });
+}
+exports.registerGlobalMiddleware = registerGlobalMiddleware;
+/**
+ * Register an authorization check for all fields that match. Global checks run before the field's own
+ * checks; all must return `true`. Matched when the schema is built, so registration order does not matter.
+ *
+ * @param matcher - Decides per field; see {@link FieldMatcherInfo}.
+ * @param authorize - Return `true` to allow, `false` or an `Error` to deny.
+ * @param options - See {@link GlobalRegistrationOptions}.
+ *
+ * @example
+ * // Rate limit every field, including Strapi's generated ones
+ * registerGlobalAuthorize(() => true, rateLimit, { includeNonBuilderFields: true })
+ */
+function registerGlobalAuthorize(matcher, authorize, options = {}) {
+    globalAuthorizes.push({ matcher, value: authorize, options });
+}
+exports.registerGlobalAuthorize = registerGlobalAuthorize;
+const matching = (entries, info) => entries
+    .filter(({ matcher, options }) => (info.isBuilderField || options.includeNonBuilderFields) && matcher(info))
+    .map(({ value }) => value);
+/** @internal Used by the Nexus plugins. */
+function getGlobalMiddlewares(info) {
+    return matching(globalMiddlewares, info);
+}
+exports.getGlobalMiddlewares = getGlobalMiddlewares;
+/** @internal Used by the Nexus plugins. */
+function getGlobalAuthorizes(info) {
+    return matching(globalAuthorizes, info);
+}
+exports.getGlobalAuthorizes = getGlobalAuthorizes;
+/** @internal Only for tests. */
+function resetGlobalRegistry() {
+    globalMiddlewares.length = 0;
+    globalAuthorizes.length = 0;
+}
+exports.resetGlobalRegistry = resetGlobalRegistry;

package/dist/server/utils/registry/index.d.ts

@@ -0,0 +1,3 @@
+export * from './global-registry';
+export * from './field-protection';
+export * from './resolve-field';

package/dist/server/utils/registry/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./global-registry"), exports);
+__exportStar(require("./field-protection"), exports);
+__exportStar(require("./resolve-field"), exports);

package/dist/server/utils/registry/resolve-field.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/server/utils/registry/resolve-field.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveFieldPipeline = void 0;
+const strapi_compat_1 = require("../strapi-compat");
+const global_registry_1 = require("./global-registry");
+const field_protection_1 = require("./field-protection");
+/**
+ * `authorize`/`middlewares` can be set in `extensions` or as top-level Nexus field options
+ * (`t.field('x', { authorize })`, as declared in the plugins' typegen). Both are honoured.
+ */
+const ownAuthorize = (extensions) => {
+    var _a, _b, _c;
+    const candidate = (_a = extensions === null || extensions === void 0 ? void 0 : extensions.authorize) !== null && _a !== void 0 ? _a : (_c = (_b = extensions === null || extensions === void 0 ? void 0 : extensions.nexus) === null || _b === void 0 ? void 0 : _b.config) === null || _c === void 0 ? void 0 : _c.authorize;
+    return typeof candidate === 'function' ? candidate : undefined;
+};
+const ownMiddlewares = (extensions) => {
+    var _a, _b, _c;
+    const candidate = (_a = extensions === null || extensions === void 0 ? void 0 : extensions.middlewares) !== null && _a !== void 0 ? _a : (_c = (_b = extensions === null || extensions === void 0 ? void 0 : extensions.nexus) === null || _b === void 0 ? void 0 : _b.config) === null || _c === void 0 ? void 0 : _c.middlewares;
+    return Array.isArray(candidate) ? candidate : [];
+};
+const contentTypeOf = (typeName) => {
+    try {
+        return (0, strapi_compat_1.uidOfTypeName)(typeName);
+    }
+    catch {
+        // Strapi/graphql plugin not available (e.g. in unit tests)
+        return undefined;
+    }
+};
+/**
+ * Everything that must run around a field resolver, in order:
+ *
+ * 1. authentication (`withAuth(true)` on builder fields)
+ * 2. authorization: global authorizes → the field's own `authorize` → `protectFields` authorizes
+ * 3. middlewares: global middlewares (outermost) → the field's own → `protectFields` middlewares
+ *
+ * Evaluated once per field when the schema is built.
+ *
+ * @internal Used by the Nexus plugins and `.test()`.
+ */
+function resolveFieldPipeline(typeName, fieldName, extensions) {
+    var _a, _b, _c;
+    const contentType = contentTypeOf(typeName);
+    const info = {
+        type: typeName,
+        fieldName,
+        tags: (_b = (_a = extensions === null || extensions === void 0 ? void 0 : extensions.builder) === null || _a === void 0 ? void 0 : _a.tags) !== null && _b !== void 0 ? _b : [],
+        contentType,
+        isBuilderField: Boolean(extensions === null || extensions === void 0 ? void 0 : extensions.builder),
+    };
+    const protections = (0, field_protection_1.getFieldProtections)(contentType, fieldName);
+    return {
+        requireAuth: Boolean((_c = extensions === null || extensions === void 0 ? void 0 : extensions.builder) === null || _c === void 0 ? void 0 : _c.requireAuth),
+        isProtected: protections.length > 0,
+        authorizes: [
+            ...(0, global_registry_1.getGlobalAuthorizes)(info),
+            ...(ownAuthorize(extensions) ? [ownAuthorize(extensions)] : []),
+            ...protections.flatMap((p) => p.authorizes),
+        ],
+        middlewares: [
+            ...(0, global_registry_1.getGlobalMiddlewares)(info),
+            ...ownMiddlewares(extensions),
+            ...protections.flatMap((p) => p.middlewares),
+        ],
+    };
+}
+exports.resolveFieldPipeline = resolveFieldPipeline;

package/dist/server/utils/shadow-crud.d.ts

@@ -1,3 +1,5 @@
+import type { ResolverFunction } from '../types';
+import type { Middleware } from '../nexus';
 type Action = 'create' | 'update' | 'delete' | 'findOne' | 'find';
 interface FieldOperations<T> {
     disable(): this;
@@ -9,6 +11,16 @@ interface FieldOperations<T> {
     hasInputEnabled(): boolean;
     hasOutputEnabled(): boolean;
     hasFiltersEnabled(): boolean;
+    /**
+     * Add an authorization check to the generated output field. Same as
+     * `protectFields(uid, [field]).authorize(fn)`; see {@link protectFields}.
+     */
+    authorize(fn: ResolverFunction<T>): this;
+    /**
+     * Add a middleware to the generated output field. Same as
+     * `protectFields(uid, [field]).middleware(fn)`; see {@link protectFields}.
+     */
+    middleware(fn: Middleware<T>): this;
 }
 interface ShadowCRUD<T> {
     disable(): this;
@@ -16,7 +28,8 @@ interface ShadowCRUD<T> {
     disableAction(action: Action): this;
     disableQueries(): this;
     disableMutations(): this;
-    field<K extends keyof T>(name: K): FieldOperations<T[K]>;
+    /** Configure one attribute; the returned object also supports `.authorize()` and `.middleware()`. */
+    field<K extends keyof T & string>(name: K): FieldOperations<T>;
     isEnabled(): boolean;
     isDisabled(): boolean;
     areQueriesEnabled(): boolean;
@@ -26,5 +39,19 @@ interface ShadowCRUD<T> {
     isActionEnabled(action: Action): boolean;
     isActionDisabled(action: Action): boolean;
 }
+/**
+ * Typed access to Strapi's shadow CRUD configuration: disable generated queries, mutations or fields.
+ * Call it in an extension's `init()` or a builder's `.init()`.
+ *
+ * @typeParam Type - Entity type, so `.field()` only accepts its keys.
+ * @param contentTypeUID - Content type UID.
+ *
+ * @example
+ * shadowCRUD<Customer>('api::customer.customer').disableActions(['create', 'update', 'delete'])
+ * shadowCRUD<Customer>('api::customer.customer').field('internalNotes').disableFilters()
+ * shadowCRUD<Customer>('api::customer.customer').field('iban').authorize(isSelf)
+ *
+ * @see https://docs.strapi.io/dev-docs/plugins/graphql#shadow-crud
+ */
 export declare const shadowCRUD: <Type extends unknown = null>(contentTypeUID: string) => ShadowCRUD<Type>;
 export {};

package/dist/server/utils/shadow-crud.js

@@ -1,8 +1,39 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.shadowCRUD = void 0;
+const field_protection_1 = require("./registry/field-protection");
+/**
+ * Typed access to Strapi's shadow CRUD configuration: disable generated queries, mutations or fields.
+ * Call it in an extension's `init()` or a builder's `.init()`.
+ *
+ * @typeParam Type - Entity type, so `.field()` only accepts its keys.
+ * @param contentTypeUID - Content type UID.
+ *
+ * @example
+ * shadowCRUD<Customer>('api::customer.customer').disableActions(['create', 'update', 'delete'])
+ * shadowCRUD<Customer>('api::customer.customer').field('internalNotes').disableFilters()
+ * shadowCRUD<Customer>('api::customer.customer').field('iban').authorize(isSelf)
+ *
+ * @see https://docs.strapi.io/dev-docs/plugins/graphql#shadow-crud
+ */
 const shadowCRUD = (contentTypeUID) => {
     const extensionService = strapi.plugin('graphql').service('extension');
-    return extensionService.shadowCRUD(contentTypeUID);
+    const crud = extensionService.shadowCRUD(contentTypeUID);
+    return Object.assign(Object.create(crud), {
+        field(name) {
+            const fieldOperations = crud.field(name);
+            const extended = Object.assign(Object.create(fieldOperations), {
+                authorize(fn) {
+                    (0, field_protection_1.protectFields)(contentTypeUID, [name]).authorize(fn);
+                    return extended;
+                },
+                middleware(fn) {
+                    (0, field_protection_1.protectFields)(contentTypeUID, [name]).middleware(fn);
+                    return extended;
+                },
+            });
+            return extended;
+        },
+    });
 };
 exports.shadowCRUD = shadowCRUD;

package/dist/server/utils/single-type.d.ts

@@ -7,10 +7,29 @@ import { Entity, ResolveArgs } from './types';
 type ResolveEntityArgs = Omit<ResolveArgs, 'args'> & {
     args: {
         id: string;
+    } | {
+        documentId: string;
     };
 };
+/**
+ * Resolve a single entity with Strapi's own `findOne` query resolver.
+ * On Strapi v5 `args` must contain `documentId` instead of `id`.
+ *
+ * @throws Error on Strapi v5 when `args.documentId` is missing.
+ */
 export declare function resolveEntity<T extends Object>(contentType: string, resolveArgs: ResolveEntityArgs): Promise<Entity<T> | null>;
-export declare const resolveEntityRelation: <T extends Object>(contentType: string, relationFieldName: keyof T, resolveArgs: ResolveArgs) => Promise<Entity<T>[]>;
+/**
+ * Resolve a relation with Strapi's own association resolver (validation, sanitizing and draft/publish
+ * handling included). Returns Strapi's response wrapper: `{ value, info }` for to-one relations and
+ * `{ nodes, info }` for to-many relations. Prefer `.relation()` on the field builder for relation fields.
+ */
+export declare const resolveEntityRelation: <T extends Object, R extends Object = any>(contentType: string, relationFieldName: keyof T, resolveArgs: ResolveArgs) => Promise<EntityResponse<R> | {
+    nodes: R[];
+    info: {
+        args: Record<string, any>;
+        resourceUID: string;
+    };
+}>;
 type EntityResponse<T extends Object> = {
     value: Entity<T> | null;
     info: {
@@ -18,6 +37,16 @@ type EntityResponse<T extends Object> = {
         resourceUID: string;
     };
 };
+/**
+ * Wrap an entity in Strapi's entity response (`{ value, info }`), the return shape of `XEntityResponse`
+ * fields such as single-entity queries.
+ *
+ * @param args - The field arguments, used by Strapi when resolving nested fields.
+ * @param resourceUID - Content type UID of `item`.
+ *
+ * @remarks Strapi v5 to-one relation fields expect the bare entity; use {@link toRelationValue} or
+ *   {@link FieldExtensionBuilder.relation} for relations.
+ */
 export declare function toEntityResponse<T extends Object>(item: T | null, { args, resourceUID }: {
     args: Record<string, any>;
     resourceUID: string;

package/dist/server/utils/single-type.js

@@ -6,10 +6,20 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toEntityResponse = exports.resolveEntityRelation = exports.resolveEntity = void 0;
+const strapi_compat_1 = require("./strapi-compat");
+/**
+ * Resolve a single entity with Strapi's own `findOne` query resolver.
+ * On Strapi v5 `args` must contain `documentId` instead of `id`.
+ *
+ * @throws Error on Strapi v5 when `args.documentId` is missing.
+ */
 async function resolveEntity(contentType, resolveArgs) {
     const { transformArgs } = strapi.plugin('graphql').service('builders').utils;
     const { toEntityResponse } = strapi.plugin('graphql').service('format').returnTypes;
     const { buildQueriesResolvers } = strapi.plugin('graphql').service('builders').get('content-api');
+    if ((0, strapi_compat_1.isStrapiV5)() && !('documentId' in resolveArgs.args)) {
+        throw new Error(`[buro26-strapi-graphql] resolveEntity("${contentType}") needs args.documentId on Strapi v5 (got args.id)`);
+    }
     const transformedArgs = transformArgs(resolveArgs.args, { contentType });
     const { findOne } = buildQueriesResolvers({ contentType });
     const item = await findOne(resolveArgs.parent, transformedArgs, resolveArgs.context);
@@ -19,6 +29,11 @@ async function resolveEntity(contentType, resolveArgs) {
     });
 }
 exports.resolveEntity = resolveEntity;
+/**
+ * Resolve a relation with Strapi's own association resolver (validation, sanitizing and draft/publish
+ * handling included). Returns Strapi's response wrapper: `{ value, info }` for to-one relations and
+ * `{ nodes, info }` for to-many relations. Prefer `.relation()` on the field builder for relation fields.
+ */
 const resolveEntityRelation = async (contentType, relationFieldName, resolveArgs) => {
     const { buildAssociationResolver } = strapi.plugin('graphql').service('builders').get('content-api');
     const find = buildAssociationResolver({
@@ -28,6 +43,16 @@ const resolveEntityRelation = async (contentType, relationFieldName, resolveArgs
     return find(resolveArgs.parent, resolveArgs.args, resolveArgs.context);
 };
 exports.resolveEntityRelation = resolveEntityRelation;
+/**
+ * Wrap an entity in Strapi's entity response (`{ value, info }`), the return shape of `XEntityResponse`
+ * fields such as single-entity queries.
+ *
+ * @param args - The field arguments, used by Strapi when resolving nested fields.
+ * @param resourceUID - Content type UID of `item`.
+ *
+ * @remarks Strapi v5 to-one relation fields expect the bare entity; use {@link toRelationValue} or
+ *   {@link FieldExtensionBuilder.relation} for relations.
+ */
 async function toEntityResponse(item, { args, resourceUID }) {
     const { toEntityResponse } = strapi.plugin('graphql').service('format').returnTypes;
     return toEntityResponse(item, {

package/dist/server/utils/strapi-compat.d.ts

@@ -0,0 +1,85 @@
+import type { GraphQLResolveInfo } from 'graphql';
+import type { ResolveContext } from './types';
+type AnyRecord = Record<string, any>;
+/**
+ * True when running on Strapi v5. The document service (`strapi.documents`) only exists in v5.
+ */
+export declare const isStrapiV5: () => boolean;
+/**
+ * Whether the GraphQL plugin runs in v4 compatibility mode (only relevant on v5).
+ */
+export declare const isV4CompatibilityMode: () => boolean;
+/**
+ * GraphQL object type name Strapi generates for a content type, e.g. `api::customer.customer` → `Customer`.
+ */
+export declare const typeNameOf: (uid: string) => string;
+/**
+ * Reverse lookup of {@link typeNameOf}: the content type UID behind a generated GraphQL type name.
+ * Built lazily (content types do not change at runtime).
+ */
+export declare const uidOfTypeName: (typeName: string) => string | undefined;
+/**
+ * One GraphQL field Strapi generates for a relation attribute.
+ *
+ * @see {@link relationFieldSpecs}
+ */
+export type RelationFieldSpec = {
+    /** Field name on the parent type */
+    name: string;
+    /** Nexus output type */
+    type: unknown;
+    args?: AnyRecord;
+    resolve: (parent: unknown, args: AnyRecord, context: ResolveContext, info: GraphQLResolveInfo) => unknown;
+    /** `Type.field` paths Strapi protects with the `<target>.find` permission scope */
+    resolverConfigPaths: string[];
+};
+/**
+ * Describes the GraphQL field(s) Strapi itself generates for a regular (non-morph) relation, so we can
+ * (re)define them with exactly the same type, arguments, resolver and permission scope.
+ *
+ * - v4: to-one → `XEntityResponse`, to-many → `XRelationResponseCollection` (with filters/pagination args).
+ * - v5: to-one → `X` (unwrapped), to-many → `[X]!` (unwrapped `nodes`) **and** `<field>_connection`
+ *   returning `XRelationResponseCollection`.
+ *
+ * All variants use Strapi's own `buildAssociationResolver`, so query validation, output sanitizing and
+ * draft/publish handling stay identical to the generated field.
+ *
+ * Low-level building block for {@link FieldExtensionBuilder.relation} and `overrideField`; prefer those.
+ *
+ * @param resolveOverride - Replaces Strapi's association resolver. It must return Strapi's response
+ *   wrapper (`{ value }` / `{ nodes }`); v5 unwrapping is applied on top.
+ * @throws Error when the content type is unknown or the attribute is not a regular relation.
+ */
+export declare const relationFieldSpecs: (contentTypeUID: string, attributeName: string, resolveOverride?: RelationFieldSpec['resolve']) => RelationFieldSpec[];
+/**
+ * Resolver config that applies Strapi's own permission scope (`<target>.find`) to relation fields,
+ * exactly like the generated relation fields do. Pass it to an extension's `resolversConfig` when you
+ * define relation fields yourself.
+ *
+ * @returns A map of `Type.field` paths to `{ auth: { scope } }`.
+ */
+export declare const relationResolversConfig: (contentTypeUID: string, attributeName: string) => {
+    [k: string]: {
+        auth: {
+            scope: string[];
+        };
+    };
+};
+/**
+ * Sanitize raw database output for the content API (removes private/password fields and fields the
+ * current auth may not read). v4: `@strapi/utils` sanitize, v5: `strapi.contentAPI.sanitize`.
+ *
+ * Use it on data from {@link loaders} or `strapi.db.query()` before returning it from a resolver.
+ *
+ * @param uid - Content type of `data`.
+ * @param context - The resolver context; its `state.auth` decides what may be read.
+ */
+export declare const sanitizeOutput: <T>(data: T, uid: string, context: ResolveContext) => Promise<T>;
+/**
+ * Wrap a single entity the way the given relation field expects: an entity response in v4, the bare
+ * entity in v5.
+ *
+ * @param targetUID - Content type of `entity`.
+ */
+export declare const toRelationValue: (entity: unknown, targetUID: string) => unknown;
+export {};