vaspera 2.5.0

package/dist/certification/store.d.ts

@@ -0,0 +1,255 @@
+/**
+ * Enterprise Certification System - File-based Storage
+ *
+ * This module handles persistent storage of certification data using the filesystem.
+ * All certification data is stored in `.vaspera/certifications/{cert-id}/` within
+ * the project directory.
+ *
+ * Security features:
+ * - Path traversal prevention via validateCertId() and validateProjectPath()
+ * - Cryptographically secure IDs using crypto.randomUUID()
+ * - Input length constraints to prevent DoS
+ *
+ * Storage structure:
+ * ```
+ * .vaspera/certifications/{cert-id}/
+ * ├── metadata.json           # Certification metadata
+ * ├── agents/                  # Per-agent findings
+ * │   ├── security.json
+ * │   ├── reliability.json
+ * │   └── ...
+ * ├── cross-verifications.json
+ * ├── red-team-challenges.json
+ * ├── consensus.json          # Final scoring results
+ * └── evidence/               # Additional evidence files
+ * ```
+ *
+ * @module certification/store
+ */
+import { Certification, CertificationMetadata, AgentFindings, Finding, CrossVerification, RedTeamChallenge, AgentType } from "./types.js";
+/**
+ * Generate a unique certification ID from a project path.
+ *
+ * The ID format is: `cert-{sanitized-project-name}-{timestamp}`
+ * - Project name is lowercased and non-alphanumeric chars replaced with hyphens
+ * - Timestamp is milliseconds since epoch for uniqueness
+ *
+ * @param projectPath - Absolute path to the project directory
+ * @returns Certification ID in format `cert-{name}-{timestamp}`
+ *
+ * @example
+ * ```typescript
+ * const certId = generateCertificationId("/path/to/MyProject");
+ * // Returns: "cert-myproject-1712345678901"
+ * ```
+ */
+export declare function generateCertificationId(projectPath: string): string;
+/**
+ * Initialize a new certification for a project.
+ *
+ * Creates the certification directory structure and initial metadata.
+ * The certification starts in "in_progress" status with no agents completed.
+ *
+ * @param projectPath - Absolute path to the project directory
+ * @param certId - Unique certification ID (must match pattern `cert-{name}-{timestamp}`)
+ * @param agents - Array of agent types to run for this certification
+ * @returns The initialized certification metadata
+ * @throws Error if projectPath is not absolute or certId is invalid
+ *
+ * @example
+ * ```typescript
+ * const certId = generateCertificationId(projectPath);
+ * const metadata = await initializeCertification(
+ *   projectPath,
+ *   certId,
+ *   ["security", "reliability", "typesafety"]
+ * );
+ * ```
+ */
+export declare function initializeCertification(projectPath: string, certId: string, agents: AgentType[]): Promise<CertificationMetadata>;
+/**
+ * Get certification metadata
+ */
+export declare function getCertificationMetadata(projectPath: string, certId: string): Promise<CertificationMetadata | null>;
+/**
+ * Update certification metadata
+ */
+export declare function updateCertificationMetadata(projectPath: string, certId: string, updates: Partial<CertificationMetadata>): Promise<CertificationMetadata | null>;
+/**
+ * Start an agent run
+ */
+export declare function startAgent(projectPath: string, certId: string, agent: AgentType): Promise<AgentFindings>;
+/**
+ * Get agent findings
+ */
+export declare function getAgentFindings(projectPath: string, certId: string, agent: AgentType): Promise<AgentFindings | null>;
+/**
+ * Submit a finding from an agent during its audit run.
+ *
+ * The finding is automatically timestamped and initialized with an empty
+ * verifications array. The agent must have been started before submitting findings.
+ *
+ * @param projectPath - Absolute path to the project directory
+ * @param certId - Certification ID
+ * @param agent - The agent type submitting the finding
+ * @param finding - Finding data (verifications and created_at are added automatically)
+ * @returns The complete finding with added metadata
+ * @throws Error if the agent hasn't been started for this certification
+ *
+ * @example
+ * ```typescript
+ * const finding = await submitFinding(projectPath, certId, "security", {
+ *   id: "sec-001",
+ *   severity: "high",
+ *   category: "authentication",
+ *   description: "Missing authentication check on admin endpoint",
+ *   evidence: "File: src/routes/admin.ts lacks auth middleware",
+ *   confidence: 95,
+ * });
+ * ```
+ */
+/**
+ * Result of submitting a finding, includes whether it was merged with an existing finding
+ */
+export interface SubmitFindingResult extends Finding {
+    /** True if this finding was merged with an existing finding with the same ID */
+    merged?: boolean;
+    /** Number of instances if merged */
+    totalInstances?: number;
+}
+export declare function submitFinding(projectPath: string, certId: string, agent: AgentType, finding: Omit<Finding, "verifications" | "created_at">): Promise<SubmitFindingResult>;
+/**
+ * Complete an agent run
+ */
+export declare function completeAgent(projectPath: string, certId: string, agent: AgentType, summary: AgentFindings["summary"]): Promise<AgentFindings>;
+/**
+ * Add a cross-verification
+ */
+export declare function addCrossVerification(projectPath: string, certId: string, verification: Omit<CrossVerification, "created_at">): Promise<CrossVerification>;
+/**
+ * Get all cross-verifications
+ */
+export declare function getCrossVerifications(projectPath: string, certId: string): Promise<CrossVerification[]>;
+/**
+ * Add a red team challenge
+ */
+export declare function addRedTeamChallenge(projectPath: string, certId: string, challenge: Omit<RedTeamChallenge, "created_at" | "id">): Promise<RedTeamChallenge>;
+/**
+ * Get all red team challenges
+ */
+export declare function getRedTeamChallenges(projectPath: string, certId: string): Promise<RedTeamChallenge[]>;
+/**
+ * Get complete certification data including all agent findings.
+ *
+ * Assembles the full certification by reading metadata, all agent findings,
+ * cross-verifications, red team challenges, and consensus results.
+ *
+ * @param projectPath - Absolute path to the project directory
+ * @param certId - Certification ID to retrieve
+ * @returns Full Certification object or null if not found
+ *
+ * @example
+ * ```typescript
+ * const certification = await getCertification(projectPath, certId);
+ * if (certification) {
+ *   console.log(`Status: ${certification.metadata.status}`);
+ *   console.log(`Agents: ${Object.keys(certification.agents).length}`);
+ * }
+ * ```
+ */
+export declare function getCertification(projectPath: string, certId: string): Promise<Certification | null>;
+/**
+ * Save consensus result
+ */
+export declare function saveConsensus(projectPath: string, certId: string, consensus: Certification["consensus"]): Promise<void>;
+/**
+ * List all certifications for a project
+ */
+export declare function listCertifications(projectPath: string): Promise<CertificationMetadata[]>;
+/**
+ * Get the latest certification for a project
+ */
+export declare function getLatestCertification(projectPath: string): Promise<Certification | null>;
+/**
+ * Validation result for a certification
+ */
+export interface CertificationValidationResult {
+    /** Whether the certification is currently valid */
+    valid: boolean;
+    /** Reason for invalidity, if applicable */
+    reason?: "not_completed" | "expired" | "code_changed" | "no_expiry";
+}
+/**
+ * Check if a certification is still valid.
+ *
+ * A certification is invalid if:
+ * - It's not in "completed" status
+ * - The expiration date has passed
+ * - The project files have changed since certification (hash mismatch)
+ *
+ * @param projectPath - Absolute path to the project directory
+ * @param metadata - Certification metadata to check
+ * @returns Validation result with reason if invalid
+ */
+export declare function isCertificationValid(projectPath: string, metadata: CertificationMetadata): Promise<CertificationValidationResult>;
+/**
+ * Result of auto cross-verification
+ */
+export interface AutoCrossVerifyResult {
+    /** Total critical findings that needed verification */
+    criticalFindingsCount: number;
+    /** Number of findings that were auto-verified */
+    verificationsCreated: number;
+    /** Findings that were verified */
+    verifiedFindingIds: string[];
+    /** Whether all critical findings are now verified */
+    allCriticalVerified: boolean;
+}
+/**
+ * Automatically cross-verify critical findings based on agent domain overlap.
+ *
+ * This function should be called after all agents complete. It:
+ * 1. Finds all critical findings without cross-verification
+ * 2. Assigns verifying agents based on domain overlap
+ * 3. Auto-confirms findings if verifying agent found related issues
+ * 4. Creates cross-verification records
+ *
+ * @param projectPath - Absolute path to the project directory
+ * @param certId - Certification ID
+ * @param mode - "auto" for automatic verification, "manual" for explicit control
+ * @param findingIds - Optional list of specific finding IDs to verify (manual mode)
+ * @returns Result of the auto-verification process
+ */
+export declare function autoCrossVerify(projectPath: string, certId: string, mode?: "auto" | "manual", findingIds?: string[]): Promise<AutoCrossVerifyResult>;
+/**
+ * Check if all agents have completed for a certification
+ */
+export declare function allAgentsCompleted(projectPath: string, certId: string): Promise<boolean>;
+/**
+ * Finalize a certification with its final score and level.
+ *
+ * Marks the certification as completed, sets the final score and level,
+ * calculates the expiration date (30 days from now), and stores a hash
+ * of the project files to detect code changes that invalidate the cert.
+ *
+ * @param projectPath - Absolute path to the project directory
+ * @param certId - Certification ID to finalize
+ * @param level - Final certification level (CERTIFIED, APPROVED, etc.)
+ * @param score - Final overall score (0-100)
+ * @returns Updated certification metadata
+ * @throws Error if certification doesn't exist or finalization fails
+ *
+ * @example
+ * ```typescript
+ * const consensus = calculateConsensus(certification);
+ * const metadata = await finalizeCertification(
+ *   projectPath,
+ *   certId,
+ *   consensus.certification_level,
+ *   consensus.overall_score
+ * );
+ * console.log(`Expires: ${metadata.expires_at}`);
+ * ```
+ */
+export declare function finalizeCertification(projectPath: string, certId: string, level: CertificationMetadata["certification_level"], score: number): Promise<CertificationMetadata>;
+//# sourceMappingURL=store.d.ts.map

package/dist/certification/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/certification/store.ts"],"names":[],"mappings":"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"}