# Phase 9: Cert Manager Module - Pattern Map

**Mapped:** 2026-07-01
**Files analyzed:** 11 new/modified files
**Analogs found:** 10 / 11

---

## File Classification

| New/Modified File | Role | Data Flow | Closest Analog | Match Quality |
|-------------------|------|-----------|----------------|---------------|
| `apps/api/src/cert-manager/cert-manager.module.ts` | module | request-response | `apps/api/src/domaincheck/domaincheck.module.ts` | exact |
| `apps/api/src/cert-manager/cert-manager.seed.ts` | utility | — | `apps/api/src/domaincheck/domaincheck.seed.ts` | exact |
| `apps/api/src/cert-manager/cert-manager.controller.ts` | controller | file-I/O | `apps/api/src/dkv/dkv.controller.ts` | role-match |
| `apps/api/src/cert-manager/cert-manager.service.ts` | service | transform | `apps/api/src/domaincheck/domaincheck.service.ts` | role-match |
| `apps/api/src/cert-manager/dto/parse-cert.dto.ts` | dto | — | `apps/api/src/domaincheck/dto/check-domain.dto.ts` | role-match |
| `apps/api/src/app.module.ts` (modify) | config | — | current file | exact |
| `apps/web/src/app/(portal)/modules/cert-manager/page.tsx` | component | request-response | `apps/web/src/app/(portal)/modules/domaincheck/page.tsx` | exact |
| `apps/web/src/app/(portal)/modules/cert-manager/actions.ts` | utility | request-response | `apps/web/src/app/(portal)/modules/domaincheck/actions.ts` | exact |
| `apps/web/src/app/(portal)/modules/cert-manager/components/DropZone.tsx` | component | file-I/O | `apps/web/src/app/(portal)/modules/dkv-fleet/settings/components/CsvImportButton.tsx` | role-match |
| `apps/web/src/messages/de.json` (modify) | config | — | existing `domaincheck` namespace | exact |
| `apps/web/src/messages/en.json` (modify) | config | — | existing `domaincheck` namespace | exact |

---

## Pattern Assignments

### `apps/api/src/cert-manager/cert-manager.module.ts` (module, OnModuleInit)

**Analog:** `apps/api/src/domaincheck/domaincheck.module.ts`

**Full pattern** (lines 1-38):
```typescript
import { Logger, Module, OnModuleInit } from '@nestjs/common';
import { ModuleRegistryModule } from '../module-registry/module-registry.module';
import { ModuleRegistryService } from '../module-registry/module-registry.service';
import { CertManagerController } from './cert-manager.controller';
import { seedCertManagerModule } from './cert-manager.seed';
import { CertManagerService } from './cert-manager.service';

@Module({
  imports: [ModuleRegistryModule],
  controllers: [CertManagerController],
  providers: [CertManagerService],
})
export class CertManagerModule implements OnModuleInit {
  private readonly logger = new Logger(CertManagerModule.name);

  constructor(
    private readonly moduleRegistryService: ModuleRegistryService,
  ) {}

  async onModuleInit(): Promise<void> {
    try {
      await seedCertManagerModule(this.moduleRegistryService);
      this.logger.log('Cert-Manager module seeded in registry');
    } catch (error) {
      this.logger.error('Failed to seed cert-manager module', error);
    }
  }
}
```

---

### `apps/api/src/cert-manager/cert-manager.seed.ts` (utility, seed)

**Analog:** `apps/api/src/domaincheck/domaincheck.seed.ts`

**Full pattern** (lines 1-25):
```typescript
import { ModuleRegistryService } from '../module-registry/module-registry.service';

export async function seedCertManagerModule(
  moduleRegistryService: ModuleRegistryService,
): Promise<void> {
  await moduleRegistryService.seedModule({
    slug: 'cert-manager',
    name: 'Cert Manager',
    version: '1.0.0',
    category: 'security-tools',
    description: {
      de: 'Zertifikate analysieren, konvertieren und verwalten',
      en: 'Inspect, convert and manage certificates',
    },
    isSystem: true,
  });
}
```

**Critical note:** `isSystem: true` registers the module in the `Module` table but does NOT auto-activate it per tenant. The `TenantModuleActivation` record must be created manually via the marketplace UI before any API endpoint responds (otherwise `ModuleGuard` returns 403).

---

### `apps/api/src/cert-manager/cert-manager.controller.ts` (controller, file-I/O)

**Analog:** `apps/api/src/dkv/dkv.controller.ts`

**Imports pattern** (lines 1-17 of dkv.controller.ts):
```typescript
import {
  BadRequestException,
  Body,
  Controller,
  Post,
  Req,
  UploadedFile,
  UploadedFiles,
  UseInterceptors,
} from '@nestjs/common';
import { FileInterceptor, FilesInterceptor } from '@nestjs/platform-express';
import { UseModule } from '../module-registry/module.guard';
import { CertManagerService } from './cert-manager.service';
```

**Module guard pattern** (from `apps/api/src/domaincheck/domaincheck.controller.ts` lines 6-8):
```typescript
@Controller('modules/cert-manager')
@UseModule('cert-manager')
export class CertManagerController {
  constructor(private readonly certManagerService: CertManagerService) {}
```

**Single file upload pattern** (from `apps/api/src/dkv/dkv.controller.ts` lines 210-229):
```typescript
@Post('parse')
@UseInterceptors(FileInterceptor('file', {
  limits: { fileSize: 5 * 1024 * 1024 }, // 5 MB
}))
async parseCert(
  @Req() req: any,
  @UploadedFile() file: any,
  @Body('password') password?: string,
  @Body('pemText') pemText?: string,
) {
  if (!file && !pemText) {
    throw new BadRequestException('No file or PEM text provided');
  }
  return this.certManagerService.parseCert({ file, pemText, password });
}
```

**Multi-file upload pattern for merge** (FilesInterceptor — plural):
```typescript
@Post('merge')
@UseInterceptors(FilesInterceptor('files', 20, {
  limits: { fileSize: 5 * 1024 * 1024 },
}))
async mergeCerts(
  @UploadedFiles() files: any[],
  @Body('outputFormat') outputFormat: string,
  @Body('password') password?: string,
) {
  if (!files || files.length < 2) {
    throw new BadRequestException('At least 2 files required for merge');
  }
  return this.certManagerService.mergeCerts({ files, outputFormat, password });
}
```

**Tenant extraction helper** (from `apps/api/src/dkv/dkv.controller.ts` lines 233-240):
```typescript
private _requireTenant(req: any): string {
  const tenantId = req.tenantId as string | undefined;
  if (!tenantId) {
    throw new BadRequestException('No tenant context');
  }
  return tenantId;
}
```

**Binary download pattern** (from `apps/api/src/dkv/dkv.controller.ts` lines 143-160) — NOTE: cert-manager uses JSON base64 response instead of `res.send(buffer)` because endpoints are POST-only and cannot use GET anchors for authenticated downloads:
```typescript
// cert-manager variant: return base64 JSON (not res.send)
return {
  filename: 'certificate.pem',
  content: Buffer.from(pemString, 'utf-8').toString('base64'),
  mimeType: 'application/x-pem-file',
};
```

---

### `apps/api/src/cert-manager/cert-manager.service.ts` (service, transform)

**Analog:** `apps/api/src/domaincheck/domaincheck.service.ts`

**Service structure pattern** (lines 1-16 of domaincheck.service.ts):
```typescript
import { BadRequestException, Injectable, Logger } from '@nestjs/common';
import * as forge from 'node-forge';

@Injectable()
export class CertManagerService {
  private readonly logger = new Logger(CertManagerService.name);

  async parseCert(input: { file?: any; pemText?: string; password?: string }) {
    try {
      // ... node-forge operations
    } catch (error) {
      this.logger.warn(`parseCert failed: ${error}`);
      throw new BadRequestException(
        'Invalid certificate. Check the file format or password.',
      );
    }
  }
}
```

**Error handling pattern:** All node-forge operations throw synchronously on malformed input. Wrap every service method in `try/catch` → `throw new BadRequestException(...)`. Never log the `password` parameter.

**Binary encoding rule:** For DER/PFX/P7B buffers, use `buffer.toString('binary')` (never `'utf-8'`) when passing to `forge.util.createBuffer()`.

---

### `apps/api/src/cert-manager/dto/parse-cert.dto.ts` (dto)

**Analog:** `apps/api/src/domaincheck/dto/check-domain.dto.ts`

```typescript
// parse-cert.dto.ts — for JSON body (text paste path only)
export class ParseCertDto {
  pemText!: string;
  password?: string;
}

// merge-certs.dto.ts — body fields alongside FilesInterceptor
export class MergeCertsDto {
  outputFormat!: 'pem' | 'pfx';
  password?: string;
}

// convert-cert.dto.ts — body fields alongside FileInterceptor
export class ConvertCertDto {
  targetFormat!: 'pem' | 'der' | 'pfx' | 'p7b';
  password?: string;
}
```

---

### `apps/api/src/app.module.ts` (modify — add CertManagerModule)

**Analog:** Current file, lines 14-41

**Pattern:** Add import + add to imports array, following domaincheck:
```typescript
// Add to imports at top:
import { CertManagerModule } from './cert-manager/cert-manager.module';

// Add to @Module({ imports: [...] }) array (after DomaincheckModule):
CertManagerModule,
```

---

### `apps/web/src/app/(portal)/modules/cert-manager/page.tsx` (component, request-response)

**Analog:** `apps/web/src/app/(portal)/modules/domaincheck/page.tsx`

**Header + layout pattern** (lines 1-64 of domaincheck/page.tsx):
```typescript
'use client';

import { useTranslations } from 'next-intl';
import { useState } from 'react';

export default function CertManagerPage() {
  const t = useTranslations('certManager');
  const [activeTab, setActiveTab] = useState<'inspect' | 'split' | 'merge' | 'convert'>('inspect');
  const [isLoading, setIsLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);

  return (
    <div className="mx-auto max-w-4xl space-y-6 p-6">
      {/* Header */}
      <div>
        <h1 className="text-2xl font-bold tracking-tight">{t('title')}</h1>
        <p className="text-sm text-muted-foreground mt-1">{t('description')}</p>
      </div>

      {/* Shared Input Card */}
      <div className="rounded-lg border border-border bg-card p-6 shadow-sm space-y-4">
        {/* DropZone + OR divider + Textarea + conditional Password field */}
      </div>

      {/* Tab Navigation */}
      <div className="border-b border-border flex gap-6">
        {(['inspect', 'split', 'merge', 'convert'] as const).map((tab) => (
          <button
            key={tab}
            type="button"
            onClick={() => setActiveTab(tab)}
            className={`pb-2 text-sm font-medium transition-colors ${
              activeTab === tab
                ? 'border-b-2 border-primary text-foreground'
                : 'text-muted-foreground hover:text-foreground'
            }`}
          >
            {t(`tabs.${tab}`)}
          </button>
        ))}
      </div>

      {/* Tab Content Card */}
      <div className="rounded-lg border border-border bg-card p-6 shadow-sm">
        {error && <p className="text-sm text-destructive mb-4">{error}</p>}
        {/* Tab-specific content */}
      </div>
    </div>
  );
}
```

**Layout differences from domaincheck:** Use `max-w-4xl` (not `max-w-2xl`) per UI-SPEC. Tab navigation is manually rendered (no shadcn Tabs component — UI-SPEC confirms no shadcn).

---

### `apps/web/src/app/(portal)/modules/cert-manager/actions.ts` (utility, request-response)

**Analog:** `apps/web/src/app/(portal)/modules/domaincheck/actions.ts`

**Full pattern** (lines 1-33 of domaincheck/actions.ts):
```typescript
const API_URL = process.env.NEXT_PUBLIC_API_URL || 'http://localhost:3001';

// JSON body endpoint (PEM text paste)
export async function parseCertAction(pemText: string, password?: string) {
  const response = await fetch(`${API_URL}/modules/cert-manager/parse`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ pemText, password }),
    credentials: 'include',
  });
  if (!response.ok) {
    const errorBody = await response.text().catch(() => '');
    throw new Error(`${response.status} ${errorBody}`.trim());
  }
  return response.json();
}

// Multipart endpoint (file upload)
export async function parseCertFileAction(file: File, password?: string) {
  const form = new FormData();
  form.append('file', file);
  if (password) form.append('password', password);

  const response = await fetch(`${API_URL}/modules/cert-manager/parse`, {
    method: 'POST',
    // Do NOT set Content-Type — fetch sets multipart/form-data + boundary
    body: form,
    credentials: 'include',
  });
  if (!response.ok) {
    const errorBody = await response.text().catch(() => '');
    throw new Error(`${response.status} ${errorBody}`.trim());
  }
  return response.json();
}

// Multi-file upload (merge)
export async function mergeCertsAction(files: File[], outputFormat: string, password?: string) {
  const form = new FormData();
  files.forEach(file => form.append('files', file)); // same field name, multiple values
  form.append('outputFormat', outputFormat);
  if (password) form.append('password', password);

  const response = await fetch(`${API_URL}/modules/cert-manager/merge`, {
    method: 'POST',
    body: form,
    credentials: 'include',
  });
  if (!response.ok) {
    const errorBody = await response.text().catch(() => '');
    throw new Error(`${response.status} ${errorBody}`.trim());
  }
  return response.json(); // { filename, content (base64), mimeType }
}
```

**Base64 download helper** (no analog exists — new pattern):
```typescript
export function downloadBase64(filename: string, content: string, mimeType: string) {
  const bytes = Uint8Array.from(atob(content), c => c.charCodeAt(0));
  const blob = new Blob([bytes], { type: mimeType });
  const url = URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.href = url;
  a.download = filename;
  a.click();
  URL.revokeObjectURL(url);
}
```

---

### `apps/web/src/app/(portal)/modules/cert-manager/components/DropZone.tsx` (component, file-I/O)

**Analog:** `apps/web/src/app/(portal)/modules/dkv-fleet/settings/components/CsvImportButton.tsx`

**Hidden file input + click-to-browse pattern** (lines 92-109 of CsvImportButton.tsx):
```typescript
'use client';
import { useRef, useState } from 'react';

export function DropZone({ onFile, accept }: { onFile: (file: File) => void; accept: string }) {
  const fileInputRef = useRef<HTMLInputElement>(null);
  const [isDragOver, setIsDragOver] = useState(false);
  const [currentFile, setCurrentFile] = useState<File | null>(null);

  return (
    <div
      onDragOver={(e) => { e.preventDefault(); setIsDragOver(true); }}
      onDragLeave={() => setIsDragOver(false)}
      onDrop={(e) => {
        e.preventDefault();
        setIsDragOver(false);
        const file = e.dataTransfer.files[0];
        if (file) { setCurrentFile(file); onFile(file); }
      }}
      onClick={() => fileInputRef.current?.click()}
      className={`cursor-pointer rounded-lg border-2 border-dashed p-8 text-center transition-colors ${
        isDragOver ? 'border-primary bg-primary/5' : 'border-border'
      }`}
    >
      <input
        ref={fileInputRef}
        type="file"
        accept={accept}
        className="hidden"
        onChange={(e) => {
          const file = e.target.files?.[0];
          if (file) { setCurrentFile(file); onFile(file); }
          e.target.value = ''; // allow re-selecting same file
        }}
      />
      {currentFile ? (
        <p className="text-sm text-foreground">{currentFile.name}</p>
      ) : (
        <p className="text-sm text-muted-foreground">Datei hierher ziehen oder klicken</p>
      )}
    </div>
  );
}
```

**Error display pattern** (from CsvImportButton.tsx lines 178-180):
```typescript
{importError && (
  <p className="mb-3 text-sm text-destructive">{importError}</p>
)}
```

**Loading button pattern** (from CsvImportButton.tsx lines 192-208):
```typescript
<button
  type="button"
  onClick={handleAction}
  disabled={isLoading}
  className="rounded bg-primary px-4 py-2 text-sm font-medium text-primary-foreground transition-colors hover:bg-primary/90 disabled:cursor-not-allowed disabled:opacity-50"
>
  {isLoading ? t('certManager.actions.processing') : t('certManager.actions.inspect')}
</button>
```

---

### `apps/web/src/messages/de.json` and `en.json` (modify)

**Analog:** Existing `domaincheck` namespace at line 337 in de.json

**Pattern:** Add `certManager` namespace at the same level as `domaincheck`. The full namespace content is specified in `09-RESEARCH.md` under "i18n Namespace Structure". No structural changes — append only.

---

## Shared Patterns

### Module Guard (`@UseModule`)
**Source:** `apps/api/src/module-registry/module.guard.ts` lines 75-80
**Apply to:** `cert-manager.controller.ts` — decorate the controller class (not individual handlers)
```typescript
import { UseModule } from '../module-registry/module.guard';

@Controller('modules/cert-manager')
@UseModule('cert-manager')  // applies ModuleGuard to ALL routes in this controller
export class CertManagerController { ... }
```

### Error Handling (NestJS)
**Source:** `apps/api/src/dkv/dkv.controller.ts` lines 152-158 + domaincheck.service.ts lines 80-88
**Apply to:** `cert-manager.controller.ts` and `cert-manager.service.ts`
```typescript
// Controller: re-throw known exceptions, let unknown bubble
if (error instanceof NotFoundException || error instanceof BadRequestException) {
  throw error;
}
throw error;

// Service: wrap node-forge ops in try/catch → BadRequestException
try {
  const cert = forge.pki.certificateFromPem(pemString);
} catch (_err) {
  throw new BadRequestException('Invalid certificate format');
}
```

### Client State + Loading Pattern
**Source:** `apps/web/src/app/(portal)/modules/domaincheck/page.tsx` lines 20-36
**Apply to:** `cert-manager/page.tsx`
```typescript
const [isLoading, setIsLoading] = useState(false);
const [error, setError] = useState<string | null>(null);

const handleAction = async () => {
  setIsLoading(true);
  setError(null);
  try {
    const result = await someAction();
    setResult(result);
  } catch (err) {
    setError(err instanceof Error ? err.message : t('certManager.error.generic'));
  } finally {
    setIsLoading(false);
  }
};
```

### i18n String Pattern
**Source:** `apps/web/src/app/(portal)/modules/domaincheck/page.tsx` line 2, 20
**Apply to:** All frontend files in `cert-manager/`
```typescript
import { useTranslations } from 'next-intl';
const t = useTranslations('certManager');
// Usage: t('title'), t('tabs.inspect'), t('actions.processing')
```

### Fetch with Auth (Multipart)
**Source:** `apps/web/src/app/(portal)/modules/domaincheck/actions.ts` lines 18-23
**Apply to:** All fetch calls in `cert-manager/actions.ts`
- JSON body: set `Content-Type: application/json`
- Multipart (FormData): do NOT set `Content-Type` — let fetch set boundary automatically
- Always include `credentials: 'include'` for cookie auth

---

## No Analog Found

| File | Role | Data Flow | Reason |
|------|------|-----------|--------|
| `apps/api/src/cert-manager/cert-manager.service.ts` (node-forge internals) | service | transform | No crypto/binary-processing service exists in codebase — node-forge API patterns must follow RESEARCH.md Pattern 5 |

---

## Metadata

**Analog search scope:** `apps/api/src/domaincheck/`, `apps/api/src/dkv/`, `apps/api/src/module-registry/`, `apps/web/src/app/(portal)/modules/domaincheck/`, `apps/web/src/app/(portal)/modules/dkv-fleet/`
**Files scanned:** 10
**Pattern extraction date:** 2026-07-01