fix: label credential-gated template validation

Signed-off-by: zebbern <185730623+zebbern@users.noreply.github.com>

Author: zebbern

backend/src/templates/__tests__/template-validation-ledger.service.spec.ts

@@ -99,4 +99,35 @@ describe('TemplateValidationLedgerService', () => {
       rmSync(dir, { recursive: true, force: true });
     }
   });
+
+  it('returns requires-secrets metadata for credential-gated templates without a live ledger entry', () => {
+    const dir = writeLedger({});
+
+    try {
+      const result = new TemplateValidationLedgerService().getValidationForTemplate({
+        name: 'Security Scan Discord Report',
+        updatedAt: '2026-06-22T04:45:00.000Z',
+        requiredSecrets: [
+          {
+            name: 'DISCORD_WEBHOOK_URL',
+            type: 'string',
+            description: 'Discord Incoming Webhook URL for scan notifications',
+          },
+        ],
+      });
+
+      expect(result).toEqual({
+        status: 'requires-secrets',
+        recommendation: 'review',
+        terminalStatus: null,
+        artifactsCount: null,
+        verifiedAt: null,
+        rationale:
+          'Template is credential-gated and requires live secrets before execution: DISCORD_WEBHOOK_URL.',
+        isCurrent: true,
+      });
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
 });

backend/src/templates/template-validation-ledger.service.ts

@@ -2,7 +2,12 @@ import { Injectable } from '@nestjs/common';
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 
-export type TemplateValidationStatus = 'live-verified' | 'needs-fix' | 'needs-review' | 'unknown';
+export type TemplateValidationStatus =
+  | 'live-verified'
+  | 'requires-secrets'
+  | 'needs-fix'
+  | 'needs-review'
+  | 'unknown';
 
 export interface TemplateValidationSummary {
   status: TemplateValidationStatus;
@@ -27,9 +32,18 @@ interface TemplateValidationLedger {
   entries?: Record<string, TemplateValidationLedgerEntry>;
 }
 
+interface TemplateRequiredSecretTarget {
+  name?: string | null;
+  type?: string | null;
+  description?: string | null;
+  placeholder?: string | null;
+}
+
 interface TemplateValidationTarget {
   name: string;
   updatedAt?: Date | string | null;
+  requiredSecrets?: TemplateRequiredSecretTarget[] | null;
+  manifest?: { requiredSecrets?: TemplateRequiredSecretTarget[] | null } | null;
 }
 
 const VALID_RECOMMENDATIONS = new Set(['keep', 'fix', 'consolidate', 'delete', 'review']);
@@ -40,6 +54,19 @@ export class TemplateValidationLedgerService {
     const entry = this.findLedgerEntry(template.name);
 
     if (!entry) {
+      const requiredSecretNames = this.getRequiredSecretNames(template);
+      if (requiredSecretNames.length > 0) {
+        return {
+          status: 'requires-secrets',
+          recommendation: 'review',
+          terminalStatus: null,
+          artifactsCount: null,
+          verifiedAt: null,
+          rationale: `Template is credential-gated and requires live secrets before execution: ${requiredSecretNames.join(', ')}.`,
+          isCurrent: true,
+        };
+      }
+
       return {
         status: 'unknown',
         recommendation: 'unknown',
@@ -103,6 +130,18 @@ export class TemplateValidationLedgerService {
     return null;
   }
 
+  private getRequiredSecretNames(template: TemplateValidationTarget): string[] {
+    const requiredSecrets = Array.isArray(template.requiredSecrets)
+      ? template.requiredSecrets
+      : Array.isArray(template.manifest?.requiredSecrets)
+        ? template.manifest.requiredSecrets
+        : [];
+
+    return requiredSecrets
+      .map((secret) => secret?.name?.trim())
+      .filter((name): name is string => Boolean(name));
+  }
+
   private normalizeRecommendation(value: unknown): TemplateValidationSummary['recommendation'] {
     const recommendation = String(value || '').toLowerCase();
     return VALID_RECOMMENDATIONS.has(recommendation)

frontend/src/pages/TemplateLibraryPage.tsx

@@ -64,6 +64,7 @@ function matchesValidationFilter(template: Template, filter: TemplateValidationF
 const VALIDATION_FILTERS: TemplateValidationFilter[] = [
   'all',
   'live-verified',
+  'requires-secrets',
   'stale',
   'needs-fix',
   'needs-review',

frontend/src/pages/__tests__/TemplateLibraryPage.test.tsx

@@ -892,6 +892,57 @@ describe('TemplateLibraryPage', () => {
     expect(mockRevalidateMutate.mock.calls[0]?.[0]).toBe('tmpl-001');
   });
 
+  it('shows credential-gated templates separately from unknown validation', () => {
+    setupStore({
+      templates: [
+        {
+          ...templateA,
+          validation: {
+            status: 'requires-secrets',
+            recommendation: 'review',
+            terminalStatus: null,
+            artifactsCount: null,
+            verifiedAt: null,
+            rationale:
+              'Template is credential-gated and requires live secrets before execution: DISCORD_WEBHOOK_URL.',
+            isCurrent: true,
+          },
+          requiredSecrets: [
+            {
+              name: 'DISCORD_WEBHOOK_URL',
+              type: 'string',
+              description: 'Discord Incoming Webhook URL for scan notifications',
+            },
+          ],
+        } as Template,
+        {
+          ...templateB,
+          id: 'tmpl-unknown',
+          name: 'unknown validation template',
+          validation: {
+            status: 'unknown',
+            recommendation: 'unknown',
+            artifactsCount: null,
+            verifiedAt: null,
+            rationale: 'No validation found.',
+            isCurrent: false,
+          },
+        } as Template,
+      ],
+    });
+
+    renderPage();
+
+    expect(screen.getByText('Requires secrets')).toBeInTheDocument();
+    expect(screen.getByRole('option', { name: 'Requires secrets (1)' })).toBeInTheDocument();
+    expect(screen.getByRole('option', { name: 'Unknown validation (1)' })).toBeInTheDocument();
+
+    fireEvent.click(screen.getByRole('option', { name: 'Requires secrets (1)' }));
+
+    expect(screen.getByText('Network Recon Scan')).toBeInTheDocument();
+    expect(screen.queryByText('Unknown Validation Template')).not.toBeInTheDocument();
+  });
+
   it('does not render live-audit guidance for current live-verified templates', () => {
     setupStore({
       templates: [

frontend/src/pages/template-library/TemplateCard.tsx

@@ -52,6 +52,14 @@ function getValidationBadge(template: Template) {
     };
   }
 
+  if (validation.status === 'requires-secrets') {
+    return {
+      label: 'Requires secrets',
+      Icon: KeyRound,
+      className: 'border-sky-500/30 bg-sky-500/10 text-sky-700 dark:text-sky-300',
+    };
+  }
+
   if (validation.status === 'needs-fix' || validation.status === 'needs-review') {
     return {
       label: validation.status === 'needs-fix' ? 'Needs fix' : 'Needs review',
@@ -79,6 +87,7 @@ function getValidationAction(template: Template) {
   const shouldRevalidate =
     validation.status === 'unknown' ||
     !validation.isCurrent ||
+    validation.status === 'requires-secrets' ||
     validation.status === 'needs-fix' ||
     validation.status === 'needs-review';
 

frontend/src/pages/template-library/TemplateFilters.tsx

@@ -111,6 +111,9 @@ export function TemplateFilters({
             <SelectItem value="live-verified">
               Live verified ({validationCounts['live-verified']})
             </SelectItem>
+            <SelectItem value="requires-secrets">
+              Requires secrets ({validationCounts['requires-secrets']})
+            </SelectItem>
             <SelectItem value="stale">Validation stale ({validationCounts.stale})</SelectItem>
             <SelectItem value="needs-fix">Needs fix ({validationCounts['needs-fix']})</SelectItem>
             <SelectItem value="needs-review">

frontend/src/types/templates.ts

@@ -1,4 +1,9 @@
-export type TemplateValidationStatus = 'live-verified' | 'needs-fix' | 'needs-review' | 'unknown';
+export type TemplateValidationStatus =
+  | 'live-verified'
+  | 'requires-secrets'
+  | 'needs-fix'
+  | 'needs-review'
+  | 'unknown';
 
 export type TemplateValidationFilter = 'all' | TemplateValidationStatus | 'stale';