🔧 fix(config-center): harden validation and fix multi-entry availability

- Add required field validation for config entries (POST + PUT routes)
  with merged-data check for partial updates
- Fix isAvailable() to check ANY entry, not just default — multi-entry
  services now correctly report availability
- Add proper configSchema structure validation (Zod schema for
  ConfigFieldDefinition with type enum, max lengths, options)
- Remove getApiKey() async auto-register race condition — tools register
  config requirements via registerToolConfigRequirements instead
- Add 4 new route tests for required field validation

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ersinkoc

packages/gateway/src/db/repositories/config-services.test.ts

@@ -1268,13 +1268,14 @@ describe('ConfigServicesRepository', () => {
       expect(repo.isAvailable('openai')).toBe(false);
     });
 
-    it('should return false when no default entry', async () => {
+    it('should return true when non-default entry has data', async () => {
       mockAdapter.query
         .mockResolvedValueOnce([makeServiceRow()])
         .mockResolvedValueOnce([makeEntryRow({ is_default: false })]);
       await repo.initialize();
 
-      expect(repo.isAvailable('openai')).toBe(false);
+      // isAvailable checks ANY entry with data, not just default
+      expect(repo.isAvailable('openai')).toBe(true);
     });
 
     it('should return false when service not found', () => {

packages/gateway/src/db/repositories/config-services.ts

@@ -685,21 +685,22 @@ export class ConfigServicesRepository extends BaseRepository {
   /**
    * Check whether a service is configured and available.
    *
-   * A service is available when it has a default entry whose data
-   * contains at least one non-empty value.
+   * A service is available when it is active and has ANY entry (default
+   * or otherwise) whose data contains at least one non-empty value.
    */
   isAvailable(serviceName: string): boolean {
     const svc = cache.services.get(serviceName);
     if (!svc || !svc.isActive) return false;
 
-    const defaultEntry = this.getDefaultEntry(serviceName);
-    if (!defaultEntry) return false;
+    const entries = cache.entries.get(serviceName);
+    if (!entries || entries.length === 0) return false;
 
-    // Check if any data field has a non-empty value
-    const data = defaultEntry.data;
-    for (const key of Object.keys(data)) {
-      const val = data[key];
-      if (val !== null && val !== undefined && val !== '') return true;
+    // Check if any entry has at least one non-empty data field
+    for (const entry of entries) {
+      for (const key of Object.keys(entry.data)) {
+        const val = entry.data[key];
+        if (val !== null && val !== undefined && val !== '') return true;
+      }
     }
 
     return false;

packages/gateway/src/middleware/validation.ts

@@ -761,7 +761,23 @@ export const createConfigServiceSchema = z.object({
   displayName: z.string().min(1).max(200),
   category: z.string().min(1).max(100),
   description: z.string().max(2000).optional(),
-  configSchema: z.array(z.record(z.string(), z.unknown())).optional(),
+  configSchema: z
+    .array(
+      z.object({
+        name: z.string().min(1).max(100),
+        label: z.string().max(200).optional(),
+        type: z.enum(['string', 'secret', 'url', 'number', 'boolean', 'select', 'json']),
+        description: z.string().max(1000).optional(),
+        required: z.boolean().optional(),
+        defaultValue: z.union([z.string(), z.number(), z.boolean(), z.null()]).optional(),
+        envVar: z.string().max(200).optional(),
+        placeholder: z.string().max(500).optional(),
+        options: z.array(z.object({ label: z.string(), value: z.string() })).optional(),
+        order: z.number().int().min(0).max(1000).optional(),
+      })
+    )
+    .max(50)
+    .optional(),
   requiredBy: z.array(z.string().max(200)).optional(),
   docsUrl: z.string().max(2000).optional(),
 });

packages/gateway/src/routes/config-services.test.ts

@@ -519,4 +519,78 @@ describe('Config Services Routes', () => {
       expect(res.status).toBe(404);
     });
   });
+
+  // ========================================================================
+  // Required field validation
+  // ========================================================================
+
+  describe('required field validation', () => {
+    const serviceWithRequired = {
+      ...sampleService,
+      configSchema: [
+        { name: 'api_key', type: 'secret', label: 'API Key', required: true },
+        { name: 'region', type: 'text', label: 'Region', required: false },
+      ],
+    };
+
+    it('POST entry returns 400 when required field missing', async () => {
+      mockConfigServicesRepo.getByName.mockReturnValue(serviceWithRequired);
+
+      const res = await app.request('/config-services/gmail/entries', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ data: { region: 'us-east-1' } }),
+      });
+
+      expect(res.status).toBe(400);
+      const json = await res.json();
+      expect(json.error.message).toContain('API Key');
+    });
+
+    it('POST entry allows when required field present', async () => {
+      mockConfigServicesRepo.getByName.mockReturnValue(serviceWithRequired);
+      mockConfigServicesRepo.createEntry.mockResolvedValue(sampleEntry);
+
+      const res = await app.request('/config-services/gmail/entries', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ data: { api_key: 'sk-test' } }),
+      });
+
+      expect(res.status).toBe(201);
+    });
+
+    it('PUT entry returns 400 when required field cleared', async () => {
+      mockConfigServicesRepo.getByName.mockReturnValue(serviceWithRequired);
+      mockConfigServicesRepo.getEntries.mockReturnValue([
+        { ...sampleEntry, data: { api_key: 'sk-old', region: 'us-east-1' } },
+      ]);
+
+      const res = await app.request('/config-services/gmail/entries/entry-1', {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ data: { api_key: '' } }),
+      });
+
+      expect(res.status).toBe(400);
+      const json = await res.json();
+      expect(json.error.message).toContain('API Key');
+    });
+
+    it('PUT entry allows partial update with required field intact', async () => {
+      mockConfigServicesRepo.getByName.mockReturnValue(serviceWithRequired);
+      mockConfigServicesRepo.getEntries.mockReturnValue([
+        { ...sampleEntry, data: { api_key: 'sk-old', region: 'us-east-1' } },
+      ]);
+      mockConfigServicesRepo.updateEntry.mockResolvedValue(sampleEntry);
+
+      const res = await app.request('/config-services/gmail/entries/entry-1', {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ data: { region: 'eu-west-1' } }),
+      });
+
+      expect(res.status).toBe(200);
+    });
+  });
 });

packages/gateway/src/routes/config-services.ts

@@ -32,6 +32,25 @@ export const configServicesRoutes = new Hono();
 // HELPERS
 // =============================================================================
 
+/**
+ * Validate entry data against service schema's required fields.
+ * Returns array of missing required field names (empty = valid).
+ */
+function validateRequiredFields(
+  data: Record<string, unknown>,
+  schema: ConfigFieldDefinition[]
+): string[] {
+  const missing: string[] = [];
+  for (const field of schema) {
+    if (!field.required) continue;
+    const val = data[field.name];
+    if (val === undefined || val === null || val === '') {
+      missing.push(field.label || field.name);
+    }
+  }
+  return missing;
+}
+
 /**
  * Detect if a value looks like it was masked by maskSecret().
  * Matches patterns like "abcd...wxyz" or "****".
@@ -256,6 +275,22 @@ configServicesRoutes.post('/:name/entries', async (c) => {
   }
 
   const body = await c.req.json<CreateConfigEntryInput>();
+
+  // Validate required fields
+  if (body.data && service.configSchema.length > 0) {
+    const missing = validateRequiredFields(body.data, service.configSchema);
+    if (missing.length > 0) {
+      return apiError(
+        c,
+        {
+          code: ERROR_CODES.VALIDATION_ERROR,
+          message: `Missing required fields: ${missing.join(', ')}`,
+        },
+        400
+      );
+    }
+  }
+
   const entry = await configServicesRepo.createEntry(name, body);
 
   wsGateway.broadcast('data:changed', { entity: 'config_service', action: 'updated', id: name });
@@ -296,6 +331,23 @@ configServicesRoutes.put('/:name/entries/:entryId', async (c) => {
     }
   }
 
+  // Validate required fields (merge with existing data to allow partial updates)
+  if (body.data && service.configSchema.length > 0) {
+    const existingData = configServicesRepo.getEntries(name).find((e) => e.id === entryId)?.data ?? {};
+    const mergedData = { ...existingData, ...body.data };
+    const missing = validateRequiredFields(mergedData, service.configSchema);
+    if (missing.length > 0) {
+      return apiError(
+        c,
+        {
+          code: ERROR_CODES.VALIDATION_ERROR,
+          message: `Missing required fields: ${missing.join(', ')}`,
+        },
+        400
+      );
+    }
+  }
+
   const updated = await configServicesRepo.updateEntry(entryId, body);
   if (!updated) {
     return notFoundError(c, 'Config entry', entryId);

packages/gateway/src/services/config-center-impl.test.ts

@@ -81,27 +81,15 @@ describe('GatewayConfigCenter', () => {
       expect(center.getApiKey('openai')).toBeUndefined();
     });
 
-    it('auto-registers unknown service via upsert', () => {
+    it('returns undefined for unregistered service without throwing', () => {
       mockConfigServicesRepo.getApiKey.mockReturnValue(undefined);
       mockConfigServicesRepo.getByName.mockReturnValue(null);
-      mockConfigServicesRepo.upsert.mockResolvedValue({});
 
-      center.getApiKey('new-service');
+      const key = center.getApiKey('unknown-service');
 
-      expect(mockConfigServicesRepo.upsert).toHaveBeenCalledWith({
-        name: 'new-service',
-        displayName: 'new-service',
-        category: 'general',
-        description: 'Auto-discovered service',
-      });
-    });
-
-    it('does not throw when upsert fails', () => {
-      mockConfigServicesRepo.getApiKey.mockReturnValue(undefined);
-      mockConfigServicesRepo.getByName.mockReturnValue(null);
-      mockConfigServicesRepo.upsert.mockRejectedValue(new Error('DB error'));
-
-      expect(() => center.getApiKey('failing-service')).not.toThrow();
+      expect(key).toBeUndefined();
+      // Should NOT auto-register — tools register via registerToolConfigRequirements
+      expect(mockConfigServicesRepo.upsert).not.toHaveBeenCalled();
     });
   });
 

packages/gateway/src/services/config-center-impl.ts

@@ -56,18 +56,9 @@ export class GatewayConfigCenter implements ConfigCenter {
   getApiKey(serviceName: string): string | undefined {
     const key = configServicesRepo.getApiKey(serviceName);
 
-    // Runtime auto-detection: if service doesn't exist at all, register it (fire-and-forget)
-    if (!configServicesRepo.getByName(serviceName)) {
-      configServicesRepo
-        .upsert({
-          name: serviceName,
-          displayName: serviceName,
-          category: 'general',
-          description: 'Auto-discovered service',
-        })
-        .catch((err) => {
-          log.warn(`Auto-register service "${serviceName}" failed`, { error: String(err) });
-        });
+    // Log when unknown service is accessed — tools should register via registerToolConfigRequirements
+    if (!key && !configServicesRepo.getByName(serviceName)) {
+      log.debug(`getApiKey called for unregistered service "${serviceName}"`);
     }
 
     return key;