fix(auth): require explicit GraphQL authorization

api/.eslintrc.ts

@@ -4,7 +4,10 @@ import noRelativeImportPaths from 'eslint-plugin-no-relative-import-paths';
 import prettier from 'eslint-plugin-prettier';
 import tseslint from 'typescript-eslint';
 
+import { graphqlAuthorizationConfig } from './eslint/graphql-authorization.config.mjs';
+
 export default tseslint.config(
+    ...graphqlAuthorizationConfig,
     eslint.configs.recommended,
     ...tseslint.configs.recommended,
     {

api/eslint/graphql-authorization.config.mjs

@@ -0,0 +1,31 @@
+import tseslint from 'typescript-eslint';
+
+import requireGraphqlAuthorization from './require-graphql-authorization.mjs';
+
+export const graphqlAuthorizationConfig = [
+    {
+        files: ['**/*.ts'],
+        // Tests include deliberately unguarded fixtures; templates are not deployed handlers.
+        ignores: [
+            '**/*.spec.ts',
+            '**/*.test.ts',
+            '**/__test__/**',
+            '**/__tests__/**',
+            '**/templates/**',
+        ],
+        languageOptions: { parser: tseslint.parser },
+        plugins: {
+            'unraid-auth': { rules: { 'require-graphql-authorization': requireGraphqlAuthorization } },
+        },
+        rules: { 'unraid-auth/require-graphql-authorization': 'error' },
+    },
+];
+
+// This focused pass does not evaluate the existing style-rule suppressions.
+export default [
+    ...graphqlAuthorizationConfig,
+    {
+        plugins: { '@typescript-eslint': tseslint.plugin },
+        linterOptions: { reportUnusedDisableDirectives: 'off' },
+    },
+];

api/eslint/require-graphql-authorization.mjs

@@ -0,0 +1,96 @@
+const graphqlHandlers = new Set(['Query', 'Mutation', 'Subscription', 'ResolveField']);
+const permissionSources = new Set(['@unraid/shared/use-permissions.directive.js', 'nest-authz']);
+const accessMarkers = new Map([
+    ['@app/unraid-api/auth/public.decorator.js', 'Public'],
+    ['@app/unraid-api/auth/authenticated.decorator.js', 'Authenticated'],
+]);
+
+function importedDecorator(context, decorator) {
+    const call = decorator.expression;
+    if (call.type !== 'CallExpression') return;
+    const callee = call.callee;
+    const identifier = callee.type === 'Identifier' ? callee : callee.object;
+    if (identifier?.type !== 'Identifier') return;
+    let scope = context.sourceCode.getScope(decorator);
+    while (scope) {
+        const variable = scope.set.get(identifier.name);
+        if (variable) {
+            const definition = variable.defs.find((entry) => entry.type === 'ImportBinding');
+            if (!definition) return;
+            const specifier = definition.node;
+            const source = definition.parent.source.value;
+            if (callee.type === 'Identifier' && specifier.type === 'ImportSpecifier') {
+                return { source, name: specifier.imported.name ?? specifier.imported.value, call };
+            }
+            if (callee.type === 'MemberExpression' && specifier.type === 'ImportNamespaceSpecifier') {
+                const name = callee.computed ? callee.property.value : callee.property.name;
+                return { source, name, call };
+            }
+            return;
+        }
+        scope = scope.upper;
+    }
+}
+
+function hasPermissionArgument(call) {
+    return (
+        call.arguments.length > 0 &&
+        call.arguments.every((argument) => {
+            if (argument.type === 'ObjectExpression') {
+                const keys = new Set(
+                    argument.properties
+                        .filter((property) => property.type === 'Property')
+                        .map((property) => property.key.name ?? property.key.value)
+                );
+                return keys.has('action') && keys.has('resource');
+            }
+            return !['Literal', 'ArrayExpression'].includes(argument.type);
+        })
+    );
+}
+
+/** @type {import('eslint').Rule.RuleModule} */
+export default {
+    meta: {
+        type: 'problem',
+        docs: { description: 'Require an explicit access policy on each GraphQL handler' },
+        schema: [],
+        messages: {
+            missing:
+                'GraphQL handlers require @UsePermissions(...), @Public(), or @Authenticated() on the method. @UseGuards alone does not declare permissions.',
+            empty: '@UsePermissions must declare an action and resource; empty permission metadata is denied at runtime.',
+        },
+    },
+    create(context) {
+        return {
+            MethodDefinition(node) {
+                const decorators = (node.decorators ?? [])
+                    .map((decorator) => importedDecorator(context, decorator))
+                    .filter(Boolean);
+                if (
+                    !decorators.some(
+                        ({ source, name }) => source === '@nestjs/graphql' && graphqlHandlers.has(name)
+                    )
+                )
+                    return;
+                const permissions = decorators.filter(
+                    ({ source, name }) => permissionSources.has(source) && name === 'UsePermissions'
+                );
+                if (permissions.length) {
+                    if (permissions.some(({ call }) => !hasPermissionArgument(call))) {
+                        context.report({ node, messageId: 'empty' });
+                    }
+                    return;
+                }
+                if (
+                    !decorators.some(
+                        ({ source, name }) =>
+                            accessMarkers.has(source) && accessMarkers.get(source) === name
+                    )
+                ) {
+                    context.report({ node, messageId: 'missing' });
+                }
+            },
+        };
+    },
+};

api/eslint/require-graphql-authorization.spec.ts

@@ -0,0 +1,116 @@
+import { fileURLToPath } from 'node:url';
+
+import { ESLint, RuleTester } from 'eslint';
+import tseslint from 'typescript-eslint';
+import { describe, expect, it } from 'vitest';
+
+import rule from './require-graphql-authorization.mjs';
+
+RuleTester.describe = describe;
+RuleTester.it = it;
+const tester = new RuleTester({ languageOptions: { parser: tseslint.parser } });
+const handlerImports = "import { Query, Mutation, Subscription, ResolveField } from '@nestjs/graphql';";
+const permissionsImport =
+    "import { UsePermissions } from '@unraid/shared/use-permissions.directive.js';";
+const publicImport = "import { Public } from '@app/unraid-api/auth/public.decorator.js';";
+const authenticatedImport =
+    "import { Authenticated } from '@app/unraid-api/auth/authenticated.decorator.js';";
+const permission = "@UsePermissions({ action: 'READ_ANY', resource: 'CONFIG' })";
+
+const code = (decorators: string, imports = permissionsImport) => `${handlerImports} ${imports}
+class Resolver { ${decorators} arbitraryName() { return true; } }`;
+
+tester.run('require-graphql-authorization', rule, {
+    valid: [
+        ...['Query', 'Mutation', 'Subscription', 'ResolveField'].map((name) =>
+            code(`@${name}(() => Boolean) ${permission}`)
+        ),
+        code(`${permission} @Query(() => Boolean)`),
+        code('@Query(() => Boolean) @Public()', publicImport),
+        code('@Mutation(() => Boolean) @Authenticated()', authenticatedImport),
+        code('@Query(() => Boolean) @UsePermissions(permission)', permissionsImport),
+        code(`@Query(() => Boolean) ${permission}`, "import { UsePermissions } from 'nest-authz';"),
+        "import { Query as Read } from '@nestjs/graphql'; import { UsePermissions as Policy } from 'nest-authz'; class R { @Read(() => Boolean) @Policy({ action: 'READ_ANY', resource: 'CONFIG' }) value() {} }",
+        "import * as gql from '@nestjs/graphql'; import * as auth from 'nest-authz'; class R { @gql.Query(() => Boolean) @auth.UsePermissions({ action: 'READ_ANY', resource: 'CONFIG' }) value() {} }",
+        "import * as gql from '@nestjs/graphql'; import * as auth from 'nest-authz'; class R { @(gql['Query'])(() => Boolean) @(auth['UsePermissions'])({ action: 'READ_ANY', resource: 'CONFIG' }) value() {} }",
+        code(''),
+        "import { Query } from 'unrelated'; class R { @Query() value() {} }",
+    ],
+    invalid: [
+        ...['Query', 'Mutation', 'Subscription', 'ResolveField'].map((name) => ({
+            code: code(`@${name}(() => Boolean)`),
+            errors: [{ messageId: 'missing' }],
+        })),
+        {
+            code: "import { Query as Read } from '@nestjs/graphql'; class R { @Read(() => Boolean) renamed() {} }",
+            errors: [{ messageId: 'missing' }],
+        },
+        {
+            code: "import * as gql from '@nestjs/graphql'; class R { @gql.Mutation(() => Boolean) renamed() {} }",
+            errors: [{ messageId: 'missing' }],
+        },
+        {
+            code: code('@Query(() => Boolean) @UseGuards(AuthZGuard)'),
+            errors: [{ messageId: 'missing' }],
+        },
+        {
+            code: code('@Query(() => Boolean) @Public()', "import { Public } from 'unrelated';"),
+            errors: [{ messageId: 'missing' }],
+        },
+        {
+            code: `${handlerImports} ${publicImport} @Public() class R { @Query(() => Boolean) value() {} }`,
+            errors: [{ messageId: 'missing' }],
+        },
+        {
+            code: `${handlerImports} ${permissionsImport} function factory(UsePermissions) { return class { @Query(() => Boolean) ${permission} value() {} }; }`,
+            errors: [{ messageId: 'missing' }],
+        },
+        ...['', '{}', '[]', 'null', "{ action: 'READ_ANY' }"].map((args) => ({
+            code: code(`@Query(() => Boolean) @UsePermissions(${args})`),
+            errors: [{ messageId: 'empty' }],
+        })),
+        {
+            code: code(
+                '@Query(() => Boolean) @Public() @UsePermissions()',
+                `${publicImport} ${permissionsImport}`
+            ),
+            errors: [{ messageId: 'empty' }],
+        },
+    ],
+});
+
+// Loading the full ESLint config includes TypeScript transpilation and plugin startup.
+// Allow for that cold start while CI runs coverage across packages concurrently.
+describe('authorization lint configuration', { timeout: 30_000 }, () => {
+    const cwd = fileURLToPath(new URL('..', import.meta.url));
+    it.each([
+        ['.eslintrc.ts', 'src/new-handler.ts'],
+        ['eslint/graphql-authorization.config.mjs', 'api/src/new-handler.ts'],
+        [
+            'eslint/graphql-authorization.config.mjs',
+            'packages/unraid-api-plugin-connect/src/new-handler.ts',
+        ],
+    ])('rejects an unguarded endpoint using %s at %s', async (config, filePath) => {
+        const eslint = new ESLint({
+            cwd: config === '.eslintrc.ts' ? cwd : fileURLToPath(new URL('../..', import.meta.url)),
+            overrideConfigFile: fileURLToPath(new URL(`../${config}`, import.meta.url)),
+        });
+        const results = await eslint.lintText(code('@Mutation(() => Boolean)'), { filePath });
+        expect(
+            results
+                .flatMap((result) => result.messages)
+                .filter((message) => message.ruleId === 'unraid-auth/require-graphql-authorization')
+        ).toHaveLength(1);
+    });
+    it('keeps deliberate test fixtures outside the production policy', async () => {
+        const eslint = new ESLint({ cwd, overrideConfigFile: '.eslintrc.ts' });
+        const results = await eslint.lintText(code('@Query(() => Boolean)'), {
+            filePath: 'src/negative-fixture.spec.ts',
+        });
+        expect(
+            results
+                .flatMap((result) => result.messages)
+                .filter((message) => message.ruleId === 'unraid-auth/require-graphql-authorization')
+        ).toHaveLength(0);
+    });
+});

api/package.json

@@ -33,8 +33,9 @@
         "// Internationalization": "",
         "i18n:extract": "node ./scripts/extract-translations.mjs",
         "// Code Quality": "",
-        "lint": "eslint --config .eslintrc.ts src/",
-        "lint:fix": "eslint --fix --config .eslintrc.ts src/",
+        "lint": "eslint --config .eslintrc.ts src/ && pnpm lint:authorization",
+        "lint:authorization": "cd .. && eslint --config api/eslint/graphql-authorization.config.mjs api/src/ packages/unraid-api-plugin-*/src/",
+        "lint:fix": "eslint --fix --config .eslintrc.ts src/ && pnpm lint:authorization",
         "pretype-check": "pnpm --filter @unraid/shared build",
         "type-check": "tsc --noEmit",
         "// Testing": "",

api/src/unraid-api/app/__test__/app.module.integration.spec.ts

@@ -2,13 +2,13 @@ import { INestApplication } from '@nestjs/common';
 import { FastifyAdapter, NestFastifyApplication } from '@nestjs/platform-fastify';
 import { Test, TestingModule } from '@nestjs/testing';
 
-import { AuthZGuard } from 'nest-authz';
 import request from 'supertest';
 import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
 
 import { AppModule } from '@app/unraid-api/app/app.module.js';
 import { AuthService } from '@app/unraid-api/auth/auth.service.js';
 import { AuthenticationGuard } from '@app/unraid-api/auth/authentication.guard.js';
+import { AuthorizationGuard } from '@app/unraid-api/auth/authorization.guard.js';
 
 // Mock the store before importing it
 vi.mock('@app/store/index.js', () => ({
@@ -76,7 +76,7 @@ describe('AppModule Integration Tests', () => {
                 canActivate: () => true,
             })
             // Override authorization guard
-            .overrideGuard(AuthZGuard)
+            .overrideGuard(AuthorizationGuard)
             .useValue({
                 canActivate: () => true,
             })

api/src/unraid-api/app/app.module.ts

@@ -4,14 +4,14 @@ import { APP_GUARD } from '@nestjs/core';
 import { ScheduleModule } from '@nestjs/schedule';
 import { ThrottlerModule } from '@nestjs/throttler';
 
-import { AuthZGuard } from 'nest-authz';
 import { LoggerModule } from 'nestjs-pino';
 
 import { apiLogger } from '@app/core/log.js';
 import { LOG_LEVEL } from '@app/environment.js';
 import { PubSubModule } from '@app/unraid-api/app/pubsub.module.js';
 import { AuthModule } from '@app/unraid-api/auth/auth.module.js';
 import { AuthenticationGuard } from '@app/unraid-api/auth/authentication.guard.js';
+import { AuthorizationGuard } from '@app/unraid-api/auth/authorization.guard.js';
 import { LegacyConfigModule } from '@app/unraid-api/config/legacy-config.module.js';
 import { CronModule } from '@app/unraid-api/cron/cron.module.js';
 import { JobModule } from '@app/unraid-api/cron/job.module.js';
@@ -67,7 +67,7 @@ import { UnraidFileModifierModule } from '@app/unraid-api/unraid-file-modifier/u
         },
         {
             provide: APP_GUARD,
-            useClass: AuthZGuard,
+            useClass: AuthorizationGuard,
         },
     ],
 })

api/src/unraid-api/auth/authenticated.decorator.ts

@@ -0,0 +1,6 @@
+import { SetMetadata } from '@nestjs/common';
+
+export const IS_AUTHENTICATED_ENDPOINT_KEY = 'isAuthenticatedEndpoint';
+
+// For empty mutation namespaces; their child handlers enforce resource permissions.
+export const Authenticated = (): MethodDecorator => SetMetadata(IS_AUTHENTICATED_ENDPOINT_KEY, true);