Add configurable excluded options for unsupported query parameters

Author: FlorianKoerner

README.md

@@ -73,6 +73,7 @@ npm start
 | `AVIF_EXIF`                        | `1`         | Enable EXIF metadata for AVIF (1 = on, 0 = off).           |
 | `JSON`                             | `1`         | Enable the JSON endpoint (1 = on, 0 = off).                |
 | `QUERY_STRING_ARRAY_LIMIT_MIN`     | `20`        | Minimum number of values allowed per array parameter.      |
+| `EXCLUDED_OPTIONS`                 | `idRandomization,fontFamily,fontWeight,title` | Comma-separated list of option names to exclude.           |
 | `QUERY_STRING_PARAMETER_LIMIT_MIN` | `100`       | Minimum number of query string parameters allowed.         |
 
 > [!NOTE]

src/config.ts

@@ -28,6 +28,9 @@ export const config: Config = {
   cacheControl: {
     avatar: Number(process.env.CACHE_CONTROL_AVATARS ?? 60 * 60 * 24 * 365),
   },
+  excludedOptions: (
+    process.env.EXCLUDED_OPTIONS ?? 'idRandomization,fontFamily,fontWeight,title'
+  ).split(',').filter(Boolean),
   queryString: {
     arrayLimitMin: Number(process.env.QUERY_STRING_ARRAY_LIMIT_MIN ?? 20),
     parameterLimitMin: Number(

src/routes/style.ts

@@ -11,6 +11,10 @@ import { createRequire } from 'node:module';
 const require = createRequire(import.meta.url);
 const optionsSchema = require('@dicebear/schema/options.json');
 
+for (const key of config.excludedOptions) {
+  delete optionsSchema.properties[key];
+}
+
 const paramsSchema = {
   type: 'object' as const,
   properties: {

src/types.ts

@@ -46,6 +46,7 @@ export type Config = {
   logger: boolean;
   workers: number;
   versions: number[];
+  excludedOptions: string[];
   png: ImageFormatConfig;
   jpeg: ImageFormatConfig;
   webp: ImageFormatConfig;

tests/excluded-options.test.js

@@ -0,0 +1,44 @@
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+
+import { config } from '../dist/config.js';
+
+const require = createRequire(import.meta.url);
+
+describe('excludedOptions', () => {
+  test('default config excludes idRandomization, fontFamily, fontWeight, title', () => {
+    assert.deepEqual(config.excludedOptions, [
+      'idRandomization',
+      'fontFamily',
+      'fontWeight',
+      'title',
+    ]);
+  });
+
+  test('excluded options are removed from options schema', () => {
+    // Load a fresh copy of the schema to compare
+    const originalSchema = JSON.parse(
+      JSON.stringify(require('@dicebear/schema/options.json')),
+    );
+
+    for (const key of config.excludedOptions) {
+      assert.ok(
+        key in originalSchema.properties,
+        `"${key}" should exist in the original schema`,
+      );
+    }
+
+    // Simulate the filtering logic from routes/style.ts
+    for (const key of config.excludedOptions) {
+      delete originalSchema.properties[key];
+    }
+
+    for (const key of config.excludedOptions) {
+      assert.ok(
+        !(key in originalSchema.properties),
+        `"${key}" should be removed after filtering`,
+      );
+    }
+  });
+});