qa360 2.2.1 → 2.2.13

package/cli/dist/core/proof/schema.js

@@ -0,0 +1,263 @@
+/**
+ * JSON Schema Validation for Proof Bundles
+ *
+ * Validates proof bundles against the v1 schema using AJV.
+ *
+ * @see docs/rfc/proof-bundle-v1.md#7-json-schema
+ */
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+/**
+ * Proof Bundle v1 JSON Schema (Draft 2020-12)
+ *
+ * Uses AJV 2020-12 for full JSON Schema 2020-12 support.
+ * This ensures compatibility with the RFC Proof Bundle v1 specification.
+ */
+const PROOF_BUNDLE_SCHEMA = {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    $id: 'https://qa360.dev/schemas/proof-bundle-v1.json',
+    title: 'QA360 Proof Bundle v1',
+    type: 'object',
+    required: ['spec', 'run', 'artifacts', 'results', 'signing', 'signature'],
+    additionalProperties: false,
+    properties: {
+        spec: {
+            type: 'string',
+            const: 'qa360.proof.v1',
+        },
+        run: {
+            type: 'object',
+            required: ['id', 'startedAt', 'finishedAt', 'environment', 'packHash'],
+            additionalProperties: false,
+            properties: {
+                id: {
+                    type: 'string',
+                    format: 'uuid',
+                },
+                startedAt: {
+                    type: 'string',
+                    format: 'date-time',
+                },
+                finishedAt: {
+                    type: 'string',
+                    format: 'date-time',
+                },
+                environment: {
+                    type: 'object',
+                    required: ['os', 'node', 'arch', 'ci'],
+                    additionalProperties: false,
+                    properties: {
+                        os: {
+                            type: 'string',
+                            enum: ['windows', 'linux', 'darwin'],
+                        },
+                        node: {
+                            type: 'string',
+                            pattern: '^\\d+\\.\\d+\\.\\d+$',
+                        },
+                        arch: {
+                            type: 'string',
+                            enum: ['x64', 'arm64'],
+                        },
+                        ci: {
+                            type: 'boolean',
+                        },
+                    },
+                },
+                packHash: {
+                    type: 'string',
+                    pattern: '^sha256-[0-9a-f]{64}$',
+                },
+                ciContext: {
+                    type: 'object',
+                    properties: {
+                        provider: {
+                            type: ['string', 'null'],
+                        },
+                    },
+                },
+            },
+        },
+        artifacts: {
+            type: 'array',
+            items: {
+                type: 'object',
+                required: ['name', 'sha256', 'size'],
+                additionalProperties: false,
+                properties: {
+                    name: {
+                        type: 'string',
+                        minLength: 1,
+                    },
+                    sha256: {
+                        type: 'string',
+                        pattern: '^sha256-[0-9a-f]{64}$',
+                    },
+                    size: {
+                        type: 'integer',
+                        minimum: 0,
+                    },
+                    path: {
+                        type: 'string',
+                    },
+                },
+            },
+        },
+        results: {
+            type: 'object',
+            required: ['trustScore', 'gates'],
+            additionalProperties: false,
+            properties: {
+                trustScore: {
+                    type: 'integer',
+                    minimum: 0,
+                    maximum: 100,
+                },
+                gates: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        required: ['name', 'status'],
+                        additionalProperties: false,
+                        properties: {
+                            name: {
+                                type: 'string',
+                                minLength: 1,
+                            },
+                            status: {
+                                type: 'string',
+                                enum: ['pass', 'fail', 'skip'],
+                            },
+                            metrics: {
+                                type: 'object',
+                            },
+                        },
+                    },
+                },
+            },
+        },
+        signing: {
+            type: 'object',
+            required: ['algo', 'signerId', 'timestamp', 'identity'],
+            additionalProperties: false,
+            properties: {
+                algo: {
+                    type: 'string',
+                    const: 'ed25519',
+                },
+                signerId: {
+                    type: 'string',
+                    minLength: 1,
+                },
+                timestamp: {
+                    type: 'object',
+                    required: ['type'],
+                    properties: {
+                        type: {
+                            type: 'string',
+                            enum: ['none', 'rfc3161'],
+                        },
+                        token: {
+                            type: ['string', 'null'],
+                        },
+                    },
+                },
+                identity: {
+                    type: 'object',
+                    required: ['type'],
+                    properties: {
+                        type: {
+                            type: 'string',
+                            enum: ['none', 'did', 'sigstore'],
+                        },
+                        evidence: {
+                            type: ['string', 'object', 'null'],
+                        },
+                    },
+                },
+            },
+        },
+        signature: {
+            type: 'string',
+            pattern: '^[A-Za-z0-9+/]{86}==$',
+        },
+    },
+};
+/**
+ * Create AJV 2020-12 validator instance
+ *
+ * Configured with:
+ * - strict: true (enforce strict schema validation)
+ * - allErrors: true (collect all validation errors)
+ * - allowUnionTypes: true (support type unions like ['string', 'null'])
+ * - strictTypes: false (allow flexible type checking for edge cases)
+ */
+let validator = null;
+function getValidator() {
+    if (!validator) {
+        const ajv = new Ajv2020({
+            strict: true,
+            allErrors: true,
+            allowUnionTypes: true,
+            strictTypes: false,
+        });
+        addFormats(ajv);
+        validator = ajv.compile(PROOF_BUNDLE_SCHEMA);
+    }
+    return validator;
+}
+/**
+ * Validate proof bundle against schema
+ *
+ * @param bundle - Proof bundle to validate
+ * @returns Validation result with errors if invalid
+ */
+export function validateProofBundle(bundle) {
+    const validate = getValidator();
+    const valid = validate(bundle);
+    if (valid) {
+        return { valid: true };
+    }
+    const errors = validate.errors?.map(err => {
+        const path = err.instancePath || 'root';
+        return `${path}: ${err.message}`;
+    }) || ['Unknown validation error'];
+    return { valid: false, errors };
+}
+/**
+ * Get the JSON Schema object
+ *
+ * @returns Proof Bundle v1 schema
+ */
+export function getSchema() {
+    return PROOF_BUNDLE_SCHEMA;
+}
+/**
+ * Validate specific field patterns
+ */
+export const patterns = {
+    /**
+     * Validate SHA-256 hash format
+     */
+    sha256: (hash) => {
+        return /^sha256-[0-9a-f]{64}$/.test(hash);
+    },
+    /**
+     * Validate UUID v4 format
+     */
+    uuid: (id) => {
+        return /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(id);
+    },
+    /**
+     * Validate Ed25519 signature format (base64, 88 chars)
+     */
+    signature: (sig) => {
+        return /^[A-Za-z0-9+/]{86}==$/.test(sig);
+    },
+    /**
+     * Validate Node.js version format
+     */
+    nodeVersion: (version) => {
+        return /^\d+\.\d+\.\d+$/.test(version);
+    },
+};

package/cli/dist/core/proof/signer.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Ed25519 Signature Operations
+ *
+ * Provides key generation, signing, and verification using Ed25519.
+ * Uses tweetnacl for cryptographic operations.
+ *
+ * @see docs/rfc/proof-bundle-v1.md#5-signature-procedure
+ */
+/**
+ * Ed25519 key pair
+ */
+export interface KeyPair {
+    publicKey: Uint8Array;
+    secretKey: Uint8Array;
+}
+/**
+ * Key storage paths
+ */
+export interface KeyPaths {
+    privateKey: string;
+    publicKey: string;
+}
+/**
+ * Get default key storage directory
+ */
+export declare function getKeyDirectory(): string;
+/**
+ * Get key file paths
+ */
+export declare function getKeyPaths(): KeyPaths;
+/**
+ * Generate new Ed25519 key pair
+ *
+ * @returns Key pair (public + secret)
+ */
+export declare function generateKeys(): KeyPair;
+/**
+ * Save key pair to disk
+ *
+ * @param keyPair - Key pair to save
+ * @param paths - Optional custom paths (defaults to ~/.qa360/keys/)
+ */
+export declare function saveKeys(keyPair: KeyPair, paths?: KeyPaths): Promise<void>;
+/**
+ * Load key pair from disk
+ *
+ * @param paths - Optional custom paths (defaults to ~/.qa360/keys/)
+ * @returns Key pair
+ * @throws Error if keys don't exist
+ */
+export declare function loadKeys(paths?: KeyPaths): Promise<KeyPair>;
+/**
+ * Check if keys exist
+ *
+ * @param paths - Optional custom paths
+ * @returns true if both keys exist
+ */
+export declare function keysExist(paths?: KeyPaths): Promise<boolean>;
+/**
+ * Initialize keys (generate if they don't exist)
+ *
+ * @param paths - Optional custom paths
+ * @returns Key pair (existing or newly generated)
+ */
+export declare function initializeKeys(paths?: KeyPaths): Promise<KeyPair>;
+/**
+ * Ensure proof keys exist (generate if missing)
+ *
+ * @param homeDir - QA360 home directory
+ * @returns Result with creation status, paths, and optional keys
+ */
+export declare function ensureProofKeys(homeDir: string): Promise<{
+    created: boolean;
+    paths: {
+        pub: string;
+        priv: string;
+    };
+    keys?: KeyPair;
+}>;
+/**
+ * Compute SHA-256 hash of data
+ *
+ * @param data - Data to hash (UTF-8 string)
+ * @returns SHA-256 hash as Buffer
+ */
+export declare function sha256(data: string): Buffer;
+/**
+ * Sign data with Ed25519
+ *
+ * @param data - Data to sign (canonical JSON string)
+ * @param secretKey - Ed25519 secret key (64 bytes)
+ * @returns Base64-encoded signature (88 chars)
+ */
+export declare function sign(data: string, secretKey: Uint8Array): string;
+/**
+ * Verify Ed25519 signature
+ *
+ * @param data - Original data (canonical JSON string)
+ * @param signatureB64 - Base64-encoded signature
+ * @param publicKey - Ed25519 public key (32 bytes)
+ * @returns true if signature is valid
+ */
+export declare function verify(data: string, signatureB64: string, publicKey: Uint8Array): boolean;
+/**
+ * Sign and verify roundtrip test
+ *
+ * @param data - Test data
+ * @param keyPair - Key pair to test
+ * @returns true if roundtrip succeeds
+ */
+export declare function testRoundtrip(data: string, keyPair: KeyPair): boolean;

package/cli/dist/core/proof/signer.js

@@ -0,0 +1,226 @@
+/**
+ * Ed25519 Signature Operations
+ *
+ * Provides key generation, signing, and verification using Ed25519.
+ * Uses tweetnacl for cryptographic operations.
+ *
+ * @see docs/rfc/proof-bundle-v1.md#5-signature-procedure
+ */
+import * as naclModule from 'tweetnacl';
+import { createHash } from 'crypto';
+import { promises as fs } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+// Handle both ESM and CJS imports
+const nacl = naclModule.default || naclModule;
+// Validate tweetnacl import
+if (!nacl?.sign?.keyPair) {
+    throw new Error('tweetnacl not loaded correctly - sign.keyPair is undefined');
+}
+/**
+ * Get default key storage directory
+ */
+export function getKeyDirectory() {
+    return join(homedir(), '.qa360', 'keys');
+}
+/**
+ * Get key file paths
+ */
+export function getKeyPaths() {
+    const keyDir = getKeyDirectory();
+    return {
+        privateKey: join(keyDir, 'ed25519.key'),
+        publicKey: join(keyDir, 'ed25519.pub'),
+    };
+}
+/**
+ * Generate new Ed25519 key pair
+ *
+ * @returns Key pair (public + secret)
+ */
+export function generateKeys() {
+    const keyPair = nacl.sign.keyPair();
+    return {
+        publicKey: keyPair.publicKey,
+        secretKey: keyPair.secretKey,
+    };
+}
+/**
+ * Save key pair to disk
+ *
+ * @param keyPair - Key pair to save
+ * @param paths - Optional custom paths (defaults to ~/.qa360/keys/)
+ */
+export async function saveKeys(keyPair, paths) {
+    const keyPaths = paths || getKeyPaths();
+    const keyDir = getKeyDirectory();
+    // Create directory if it doesn't exist
+    await fs.mkdir(keyDir, { recursive: true, mode: 0o700 });
+    // Save private key (chmod 600)
+    await fs.writeFile(keyPaths.privateKey, Buffer.from(keyPair.secretKey).toString('base64'), { mode: 0o600 });
+    // Save public key (chmod 644)
+    await fs.writeFile(keyPaths.publicKey, Buffer.from(keyPair.publicKey).toString('base64'), { mode: 0o644 });
+}
+/**
+ * Load key pair from disk
+ *
+ * @param paths - Optional custom paths (defaults to ~/.qa360/keys/)
+ * @returns Key pair
+ * @throws Error if keys don't exist
+ */
+export async function loadKeys(paths) {
+    const keyPaths = paths || getKeyPaths();
+    try {
+        const privateKeyB64 = await fs.readFile(keyPaths.privateKey, 'utf-8');
+        const publicKeyB64 = await fs.readFile(keyPaths.publicKey, 'utf-8');
+        return {
+            secretKey: new Uint8Array(Buffer.from(privateKeyB64.trim(), 'base64')),
+            publicKey: new Uint8Array(Buffer.from(publicKeyB64.trim(), 'base64')),
+        };
+    }
+    catch (error) {
+        throw new Error(`Failed to load keys: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}
+/**
+ * Check if keys exist
+ *
+ * @param paths - Optional custom paths
+ * @returns true if both keys exist
+ */
+export async function keysExist(paths) {
+    const keyPaths = paths || getKeyPaths();
+    try {
+        await fs.access(keyPaths.privateKey);
+        await fs.access(keyPaths.publicKey);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Initialize keys (generate if they don't exist)
+ *
+ * @param paths - Optional custom paths
+ * @returns Key pair (existing or newly generated)
+ */
+export async function initializeKeys(paths) {
+    if (await keysExist(paths)) {
+        return loadKeys(paths);
+    }
+    const keyPair = generateKeys();
+    await saveKeys(keyPair, paths);
+    return keyPair;
+}
+/**
+ * Ensure proof keys exist (generate if missing)
+ *
+ * @param homeDir - QA360 home directory
+ * @returns Result with creation status, paths, and optional keys
+ */
+export async function ensureProofKeys(homeDir) {
+    const keyDir = join(homeDir, 'keys');
+    const paths = {
+        pub: join(keyDir, 'ed25519.pub'),
+        priv: join(keyDir, 'ed25519.key'),
+    };
+    // Check if keys already exist
+    try {
+        await fs.access(paths.priv);
+        await fs.access(paths.pub);
+        // Keys exist, validate them
+        const privateKeyB64 = await fs.readFile(paths.priv, 'utf-8');
+        const publicKeyB64 = await fs.readFile(paths.pub, 'utf-8');
+        const secretKey = new Uint8Array(Buffer.from(privateKeyB64.trim(), 'base64'));
+        const publicKey = new Uint8Array(Buffer.from(publicKeyB64.trim(), 'base64'));
+        // Validate key sizes
+        if (publicKey.length !== 32) {
+            throw new Error(`Invalid public key size: ${publicKey.length} (expected 32)`);
+        }
+        if (secretKey.length !== 64) {
+            throw new Error(`Invalid secret key size: ${secretKey.length} (expected 64)`);
+        }
+        return {
+            created: false,
+            paths,
+            keys: { publicKey, secretKey },
+        };
+    }
+    catch {
+        // Keys don't exist or are invalid, generate new ones
+        await fs.mkdir(keyDir, { recursive: true, mode: 0o700 });
+        const keyPair = generateKeys();
+        // Validate generated keys
+        if (!keyPair.publicKey || keyPair.publicKey.length !== 32) {
+            throw new Error('Key generation failed: invalid public key');
+        }
+        if (!keyPair.secretKey || keyPair.secretKey.length !== 64) {
+            throw new Error('Key generation failed: invalid secret key');
+        }
+        // Save keys
+        await fs.writeFile(paths.priv, Buffer.from(keyPair.secretKey).toString('base64'), { mode: 0o600 });
+        await fs.writeFile(paths.pub, Buffer.from(keyPair.publicKey).toString('base64'), { mode: 0o644 });
+        return {
+            created: true,
+            paths,
+            keys: keyPair,
+        };
+    }
+}
+/**
+ * Compute SHA-256 hash of data
+ *
+ * @param data - Data to hash (UTF-8 string)
+ * @returns SHA-256 hash as Buffer
+ */
+export function sha256(data) {
+    return createHash('sha256').update(data, 'utf-8').digest();
+}
+/**
+ * Sign data with Ed25519
+ *
+ * @param data - Data to sign (canonical JSON string)
+ * @param secretKey - Ed25519 secret key (64 bytes)
+ * @returns Base64-encoded signature (88 chars)
+ */
+export function sign(data, secretKey) {
+    // Hash the data first (sign the hash, not the raw data)
+    const hash = sha256(data);
+    // Sign the hash
+    const signature = nacl.sign.detached(hash, secretKey);
+    // Return base64-encoded signature
+    return Buffer.from(signature).toString('base64');
+}
+/**
+ * Verify Ed25519 signature
+ *
+ * @param data - Original data (canonical JSON string)
+ * @param signatureB64 - Base64-encoded signature
+ * @param publicKey - Ed25519 public key (32 bytes)
+ * @returns true if signature is valid
+ */
+export function verify(data, signatureB64, publicKey) {
+    try {
+        // Hash the data
+        const hash = sha256(data);
+        // Decode signature
+        const signature = new Uint8Array(Buffer.from(signatureB64, 'base64'));
+        // Verify signature
+        return nacl.sign.detached.verify(hash, signature, publicKey);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Sign and verify roundtrip test
+ *
+ * @param data - Test data
+ * @param keyPair - Key pair to test
+ * @returns true if roundtrip succeeds
+ */
+export function testRoundtrip(data, keyPair) {
+    const signature = sign(data, keyPair.secretKey);
+    return verify(data, signature, keyPair.publicKey);
+}

package/cli/dist/core/proof/verifier.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Proof Bundle Verification
+ *
+ * Verifies cryptographic signatures and integrity of proof bundles.
+ *
+ * @see docs/rfc/proof-bundle-v1.md#6-verification-procedure
+ */
+import type { ProofBundle, Artifact } from './bundle.js';
+/**
+ * Verification result
+ */
+export interface VerificationResult {
+    valid: boolean;
+    code: VerificationCode;
+    message: string;
+    details?: VerificationDetails;
+}
+/**
+ * Verification error codes (matches RFC)
+ */
+export declare enum VerificationCode {
+    PROOF_OK = 0,
+    PROOF_INVALID_SIG = 1,
+    PROOF_INVALID_SCHEMA = 2,
+    PROOF_ARTIFACT_MISMATCH = 3,
+    PROOF_MISSING_KEY = 4,
+    PROOF_MALFORMED = 5
+}
+/**
+ * Verification details
+ */
+export interface VerificationDetails {
+    signerId?: string;
+    hash?: string;
+    artifactsVerified?: number;
+    artifactsTotal?: number;
+    trustScore?: number;
+    runId?: string;
+    startedAt?: string;
+    finishedAt?: string;
+}
+/**
+ * Artifact verification options
+ */
+export interface ArtifactVerificationOptions {
+    basePath?: string;
+    skipMissing?: boolean;
+}
+/**
+ * Verify proof bundle signature
+ *
+ * @param bundle - Proof bundle to verify
+ * @param publicKey - Optional public key (loads from ~/.qa360/keys if not provided)
+ * @returns Verification result
+ */
+export declare function verifyProofBundle(bundle: ProofBundle, publicKey?: Uint8Array): Promise<VerificationResult>;
+/**
+ * Verify artifact integrity
+ *
+ * @param artifact - Artifact metadata
+ * @param filePath - Path to artifact file
+ * @returns true if hash matches
+ */
+export declare function verifyArtifact(artifact: Artifact, filePath: string): Promise<boolean>;
+/**
+ * Verify all artifacts in proof bundle
+ *
+ * @param bundle - Proof bundle
+ * @param options - Verification options
+ * @returns Verification result with artifact details
+ */
+export declare function verifyArtifacts(bundle: ProofBundle, options?: ArtifactVerificationOptions): Promise<VerificationResult>;
+/**
+ * Verify proof bundle and artifacts (complete verification)
+ *
+ * @param bundle - Proof bundle
+ * @param options - Artifact verification options
+ * @param publicKey - Optional public key
+ * @returns Complete verification result
+ */
+export declare function verifyComplete(bundle: ProofBundle, options?: ArtifactVerificationOptions, publicKey?: Uint8Array): Promise<VerificationResult>;
+/**
+ * Load and verify proof bundle from file
+ *
+ * @param filePath - Path to proof bundle JSON file
+ * @param options - Artifact verification options
+ * @param publicKey - Optional public key
+ * @returns Verification result
+ */
+export declare function verifyProofFile(filePath: string, options?: ArtifactVerificationOptions, publicKey?: Uint8Array): Promise<VerificationResult>;
+/**
+ * Verify Phase3 proof format (simplified)
+ *
+ * @param filePath - Path to Phase3 proof JSON
+ * @returns Verification result
+ */
+export declare function verifyPhase3Proof(filePath: string): Promise<VerificationResult>;