feat(api): add config verification endpoint

Author: rafiki270

API/src/routes/root/config-docs.ts

@@ -0,0 +1,210 @@
+export const configExample = {
+  domain: 'client.example.com',
+  redirect_urls: ['https://client.example.com/oauth/callback'],
+  enabled_auth_methods: ['email_password', 'google'],
+  ui_theme: {
+    colors: {
+      bg: '#f8fafc',
+      surface: '#ffffff',
+      text: '#0f172a',
+      muted: '#475569',
+      primary: '#2563eb',
+      primary_text: '#ffffff',
+      border: '#e2e8f0',
+      danger: '#dc2626',
+      danger_text: '#ffffff',
+    },
+    radii: {
+      card: '16px',
+      button: '12px',
+      input: '12px',
+    },
+    density: 'comfortable',
+    typography: {
+      font_family: 'sans',
+      base_text_size: 'md',
+    },
+    button: {
+      style: 'solid',
+    },
+    card: {
+      style: 'bordered',
+    },
+    logo: {
+      url: '',
+      alt: 'Client logo',
+      text: 'Client',
+      font_size: '24px',
+      color: '#0f172a',
+      style: {
+        'font-weight': '800',
+        'letter-spacing': '-0.02em',
+      },
+    },
+  },
+  language_config: 'en',
+  debug_enabled: true,
+  allow_registration: true,
+  registration_mode: 'password_required',
+  user_scope: 'global',
+};
+
+export const configJwtDocumentation = {
+  description:
+    'The config JWT is a signed JWT containing all client-specific settings. The payload is the config. The signature must be created with the shared secret and the JWT aud must match AUTH_SERVICE_IDENTIFIER.',
+  signing: {
+    algorithms: ['HS256', 'HS384', 'HS512'],
+    audience:
+      'The JWT aud claim must match the auth service identifier configured in AUTH_SERVICE_IDENTIFIER.',
+  },
+  required_fields: {
+    domain:
+      'string — client domain. This must exactly match the hostname of config_url when the auth service fetches the JWT.',
+    redirect_urls:
+      'string[] — non-empty list of absolute HTTP/HTTPS callback URLs. redirect_url matching is exact.',
+    enabled_auth_methods:
+      'string[] — non-empty list. Supported values are email_password, google, facebook, github, linkedin, apple.',
+    language_config:
+      'string | string[] — either one language code or a non-empty array of language codes.',
+    ui_theme: {
+      description:
+        'object — every auth page style comes from ui_theme. This object is required and the main source of integration mistakes.',
+      required_sections: {
+        colors: {
+          required_keys: [
+            'bg',
+            'surface',
+            'text',
+            'muted',
+            'primary',
+            'primary_text',
+            'border',
+            'danger',
+            'danger_text',
+          ],
+          value_format:
+            'hex color only (#RGB, #RGBA, #RRGGBB, #RRGGBBAA) or transparent',
+        },
+        radii: {
+          required_keys: ['card', 'button', 'input'],
+          value_format: 'CSS length string: px, rem, em, %, or 0',
+        },
+        density: 'compact | comfortable | spacious',
+        typography: {
+          required_keys: ['font_family', 'base_text_size'],
+          font_family:
+            'Preset values like sans, serif, mono are valid. Custom CSS font-family names are also valid.',
+          base_text_size: 'sm | md | lg',
+          font_import_url:
+            'optional HTTP/HTTPS stylesheet URL. Use this when font_family depends on a remote font import.',
+        },
+        button: {
+          required_keys: ['style'],
+          style: 'solid | outline | ghost',
+        },
+        card: {
+          required_keys: ['style'],
+          style: 'plain | bordered | shadow',
+        },
+        logo: {
+          required_keys: ['url', 'alt'],
+          url: 'HTTP/HTTPS URL or empty string',
+          alt: 'required non-empty string',
+          text: 'optional text logo, max 100 chars, used when url is empty',
+          font_size: 'optional CSS length string',
+          color: 'optional hex color',
+          style:
+            'optional flat object of CSS property -> safe CSS value. Do not include semicolons, braces, url(), or expression().',
+        },
+      },
+      optional_sections: {
+        css_vars:
+          'Record<string, string> — optional advanced CSS variable overrides.',
+      },
+      common_failures: [
+        'Missing one of the required ui_theme sections such as colors, radii, button, card, typography, or logo.',
+        'Using non-hex colors like rgb(...), hsl(...), or named colors.',
+        'Using bare numbers for radii/font sizes instead of CSS length strings like 12px or 1rem.',
+        'Providing a text logo without logo.alt.',
+        'Forgetting button.style or card.style.',
+      ],
+      example: configExample.ui_theme,
+    },
+  },
+  optional_fields: {
+    '2fa_enabled': 'boolean (default false)',
+    debug_enabled: 'boolean (default false)',
+    allowed_social_providers: 'string[] — subset of enabled social providers',
+    user_scope: '"global" | "per_domain" (default "global")',
+    allow_registration: 'boolean (default true)',
+    registration_mode:
+      '"password_required" | "passwordless" (default "password_required")',
+    allowed_registration_domains:
+      'string[] — lowercase email domains allowed to register',
+    registration_domain_mapping:
+      'array of { email_domain, org_id, team_id? } — email-domain-based org/team placement',
+    language: 'string — currently selected language override',
+    session: {
+      remember_me_enabled: 'boolean (default true)',
+      remember_me_default: 'boolean (default true)',
+      short_refresh_token_ttl_hours: 'number (1-168, default 1)',
+      long_refresh_token_ttl_days: 'number (1-90, default 30)',
+      access_token_ttl_minutes: 'number (15-60)',
+    },
+    org_features: {
+      enabled: 'boolean (default false)',
+      groups_enabled: 'boolean (default false)',
+      user_needs_team: 'boolean (default false)',
+      max_teams_per_org: 'number (default 100, max 1000)',
+      max_groups_per_org: 'number (default 20, max 200)',
+      max_members_per_org: 'number (default 1000, max 10000)',
+      max_members_per_team: 'number (default 200, max 5000)',
+      max_members_per_group: 'number (default 500, max 5000)',
+      max_team_memberships_per_user: 'number (default 50, max 200)',
+      org_roles:
+        'string[] (default ["owner", "admin", "member"]). Must include "owner".',
+    },
+    access_requests: {
+      enabled: 'boolean (default false)',
+      target_org_id: 'string (required when enabled=true)',
+      target_team_id: 'string (required when enabled=true)',
+      auto_grant_domains: 'string[]',
+      notify_org_roles: 'string[] (default ["owner", "admin"])',
+      admin_review_url: 'absolute URL',
+    },
+  },
+  example_payload: configExample,
+};
+
+export const configVerificationEndpointDocumentation = {
+  path: '/config/verify',
+  method: 'POST',
+  description:
+    'Debug endpoint that validates raw config JSON, a signed config JWT, or a config_url fetch target. It reports schema problems separately from signature, audience, and config_url/domain issues.',
+  body: {
+    config:
+      'object (optional) — raw config payload to schema-validate directly. This skips JWT signature checking unless config_jwt or config_url is also supplied instead.',
+    config_jwt:
+      'string (optional) — signed config JWT to decode, inspect, schema-validate, and optionally verify with shared_secret.',
+    config_url:
+      'string (optional) — URL that should return the signed config JWT. The endpoint fetches it and then runs the same checks.',
+    shared_secret:
+      'string (optional) — candidate secret used to verify config_jwt or the JWT fetched from config_url. If it is wrong, the response explicitly reports the shared secret/signature check failure.',
+    auth_service_identifier:
+      'string (optional) — expected JWT aud. Defaults to this auth service environment when omitted.',
+  },
+  source_priority: ['config', 'config_jwt', 'config_url'],
+  response: {
+    ok: 'boolean — true when every executed check passed',
+    schema_valid: 'boolean',
+    jwt_signature_valid:
+      'boolean | null — null when signature checking was skipped',
+    audience_valid: 'boolean | null — null when no audience check was possible',
+    domain_match: 'boolean | null — null when config_url was not part of the request or schema parsing failed',
+    checks:
+      'object — per-stage results for source, fetch, decode, signature, audience, schema, and domain_match',
+    issues: 'array — structured stage-specific failures and warnings',
+    config_summary:
+      'object | null — safe summary of the parsed config when schema validation succeeds',
+  },
+};

API/src/routes/root/config-verify.ts

@@ -0,0 +1,13 @@
+import type { FastifyInstance } from 'fastify';
+
+import {
+  parseVerifyConfigRequest,
+  verifyClientConfig,
+} from '../../services/config-debug.service.js';
+
+export function registerConfigVerifyRoute(app: FastifyInstance): void {
+  app.post('/config/verify', async (request) => {
+    const body = parseVerifyConfigRequest(request.body);
+    return await verifyClientConfig(body);
+  });
+}

API/src/routes/root/index.ts

@@ -4,6 +4,8 @@ import { fileURLToPath } from 'node:url';
 
 import type { FastifyInstance } from 'fastify';
 
+import { configJwtDocumentation, configVerificationEndpointDocumentation } from './config-docs.js';
+import { registerConfigVerifyRoute } from './config-verify.js';
 import { registerLlmRoute } from './llm.js';
 import { endpoints } from './schema.js';
 
@@ -21,6 +23,7 @@ try {
 
 export function registerRootRoute(app: FastifyInstance): void {
   registerLlmRoute(app);
+  registerConfigVerifyRoute(app);
 
   app.get('/', async () => {
     return {
@@ -30,6 +33,8 @@ export function registerRootRoute(app: FastifyInstance): void {
       version,
       repository: 'https://github.com/UnlikeOtherAI/UnlikeOtherAuthenticator',
       docs: '/llm',
+      config_jwt: configJwtDocumentation,
+      config_verification: configVerificationEndpointDocumentation,
       endpoints,
     };
   });