@vorionsys/security 1.0.0

package/dist/proof/index.d.ts

@@ -0,0 +1,203 @@
+/**
+ * PROOF - Immutable Evidence System
+ *
+ * Creates and maintains cryptographically sealed records of all governance decisions.
+ * Supports multiple signing algorithms:
+ * - Ed25519 (default, classical)
+ * - ECDSA P-256 (fallback)
+ * - Hybrid Ed25519 + Dilithium3 (post-quantum resistant)
+ *
+ * Persists to PostgreSQL for durability.
+ *
+ * CRITICAL: Uses distributed locking (Redis) and database row locking (SELECT FOR UPDATE)
+ * to prevent hash chain corruption in multi-instance deployments.
+ *
+ * @packageDocumentation
+ */
+import type { Proof, Decision, Intent, ID } from '../common/types.js';
+/**
+ * Proof creation request
+ */
+export interface ProofRequest {
+    intent: Intent;
+    decision: Decision;
+    inputs: Record<string, unknown>;
+    outputs: Record<string, unknown>;
+    /** Tenant ID for scoped locking (REQUIRED for multi-tenant isolation) */
+    tenantId: string;
+}
+/**
+ * Proof verification result
+ */
+export interface VerificationResult {
+    valid: boolean;
+    proofId: ID;
+    chainPosition: number;
+    issues: string[];
+    verifiedAt: string;
+}
+/**
+ * Proof query options
+ */
+export interface ProofQuery {
+    entityId?: ID;
+    intentId?: ID;
+    startDate?: string;
+    endDate?: string;
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Extended proof with signature metadata
+ */
+export interface SignedProof extends Proof {
+    signatureData?: {
+        publicKey: string;
+        algorithm: string;
+        signedAt: string;
+    };
+}
+/**
+ * Chain statistics
+ */
+export interface ChainStats {
+    totalProofs: number;
+    chainLength: number;
+    lastProofAt: string | null;
+}
+/**
+ * Chain verification options for paginated verification
+ */
+export interface ChainVerificationOptions {
+    /** Number of proofs to verify per batch (default: 100) */
+    batchSize?: number;
+    /** Callback for progress updates */
+    onProgress?: (verified: number, total: number) => void;
+}
+/**
+ * Chain verification result with streaming support
+ */
+export interface ChainVerificationResult {
+    valid: boolean;
+    lastValidPosition: number;
+    issues: string[];
+    totalVerified: number;
+}
+/**
+ * Signing algorithm for proof records
+ */
+export type ProofSigningAlgorithm = 'ed25519' | 'ecdsa-p256' | 'hybrid-ed25519-dilithium3';
+/**
+ * PROOF service for evidence management with PostgreSQL persistence
+ *
+ * CRITICAL FIX (PA-C1/PA-C2/DS-C1): This service now uses:
+ * 1. Redis distributed locks to serialize proof creation across instances
+ * 2. PostgreSQL row-level locking (SELECT FOR UPDATE) for chain state
+ * 3. All state updates happen inside the transaction
+ *
+ * This prevents hash chain corruption in multi-instance deployments.
+ */
+export declare class ProofService {
+    private db;
+    private lockService;
+    private chainId;
+    private initialized;
+    private signingAlgorithm;
+    /**
+     * Configure the signing algorithm for proof records.
+     *
+     * - 'ed25519' (default): Classical Ed25519 via WebCrypto
+     * - 'ecdsa-p256': Classical ECDSA P-256 via WebCrypto
+     * - 'hybrid-ed25519-dilithium3': Ed25519 + post-quantum Dilithium3 (ML-DSA-65)
+     */
+    setSigningAlgorithm(algorithm: ProofSigningAlgorithm): void;
+    /**
+     * Initialize the service - ensures database and lock service are ready
+     *
+     * NOTE: Chain state (lastHash, chainLength) is NO LONGER cached in memory.
+     * It is always read from the database inside a transaction to prevent
+     * race conditions in multi-instance deployments.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Ensure service is initialized
+     */
+    private ensureInitialized;
+    /**
+     * Create a new proof record with cryptographic signature
+     *
+     * CRITICAL FIX (PA-C1/PA-C2/DS-C1): This method now uses:
+     * 1. Redis distributed lock to serialize across multiple service instances
+     * 2. PostgreSQL SELECT FOR UPDATE to lock the chain metadata row
+     * 3. All state reads and writes happen inside the transaction
+     *
+     * SECURITY FIX: Uses per-tenant lock keys to prevent cross-tenant DoS attacks.
+     * Each tenant has their own lock scope, so heavy proof creation by one tenant
+     * cannot block proof creation for other tenants.
+     *
+     * This ensures hash chain integrity in multi-instance deployments.
+     */
+    create(request: ProofRequest): Promise<SignedProof>;
+    /**
+     * Internal method to create proof with database row locking
+     * Called only after distributed lock is acquired
+     */
+    private createProofWithLock;
+    /**
+     * Get a proof by ID
+     */
+    get(id: ID): Promise<SignedProof | undefined>;
+    /**
+     * Query proofs
+     */
+    query(query: ProofQuery): Promise<SignedProof[]>;
+    /**
+     * Verify a proof's integrity (hash, chain linkage, and signature)
+     */
+    verify(id: ID): Promise<VerificationResult>;
+    /**
+     * Verify the entire chain integrity using streaming pagination
+     *
+     * Instead of loading all proofs into memory at once, this method
+     * processes proofs in batches to handle large chains efficiently.
+     *
+     * @param options - Verification options including batch size and progress callback
+     * @returns Chain verification result
+     */
+    verifyChain(options?: ChainVerificationOptions): Promise<ChainVerificationResult>;
+    /**
+     * Calculate hash for a proof record using canonical JSON
+     *
+     * IMPORTANT: Uses canonical JSON serialization to ensure deterministic
+     * hash calculation across different environments. Standard JSON.stringify
+     * does NOT guarantee key order, which can cause hash mismatches.
+     */
+    private calculateHash;
+    /**
+     * Convert database row to SignedProof
+     */
+    private toSignedProof;
+    /**
+     * Get chain statistics
+     *
+     * NOTE: Chain stats are now always read from the database to ensure
+     * accuracy in multi-instance deployments.
+     */
+    getStats(): Promise<ChainStats>;
+    /**
+     * Get the current chain position (for testing/debugging)
+     * Reads directly from database to ensure accuracy.
+     */
+    getChainPosition(): Promise<{
+        lastHash: string;
+        chainLength: number;
+    }>;
+}
+/**
+ * Create a new PROOF service instance
+ */
+export declare function createProofService(): ProofService;
+export * from './merkle.js';
+export { getMerkleService, MerkleService, type MerkleRootInfo } from './merkle-service.js';
+export { initializeHybridSigning, signHybrid, verifyHybrid, isHybridAlgorithm, type HybridSignatureResult, type HybridVerifyResult, } from './hybrid-signing.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/proof/index.d.ts.map

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