qa360 2.1.7 → 2.2.1

package/docs/archive/LEGAL_READY_PLACEHOLDERS.md

@@ -0,0 +1,372 @@
+# 🔐 Legal-Ready Placeholders - Future Compatibility
+
+**Status**: Documented (Not Implemented)  
+**Purpose**: Ensure forward compatibility for legal/compliance features  
+**Timeline**: Phase 6 (After v1.1.0 stable)
+
+---
+
+## 📋 Overview
+
+This document defines placeholders in the Proof Bundle v1 schema to ensure backward compatibility when adding legal/compliance features in the future.
+
+**Philosophy**: Reserve the space now, implement later.
+
+---
+
+## 🎯 Placeholders Defined
+
+### 1. RFC 3161 Timestamp Authority
+
+**Field**: `signing.timestamp`
+
+**Current**: Optional, not implemented  
+**Future**: RFC 3161 TSA timestamp
+
+**Schema**:
+```json
+{
+  "signing": {
+    "signer": "local@qa360",
+    "algorithm": "Ed25519",
+    "timestamp": {
+      "value": "2025-10-26T12:34:56.789Z",
+      "tsa_url": "http://timestamp.digicert.com",
+      "tsa_cert": "sha256-abc123...",
+      "signature": "base64-encoded-tsa-signature"
+    },
+    "public_key": "base64-encoded-public-key"
+  }
+}
+```
+
+**Implementation Notes**:
+- TSA URL configurable via `QA360_TSA_URL` env var
+- Feature flag: `--tsa` or `signing.use_tsa: true` in config
+- Fallback to local timestamp if TSA unavailable
+- Validation: verify TSA signature chain
+
+**Cost**: ~$0.01 per timestamp (commercial TSAs)  
+**Free alternatives**: FreeTSA.org (limited rate)
+
+---
+
+### 2. Decentralized Identity (DID)
+
+**Field**: `signing.identity`
+
+**Current**: Optional, not implemented  
+**Future**: W3C DID or Sigstore identity
+
+**Schema**:
+```json
+{
+  "signing": {
+    "signer": "local@qa360",
+    "identity": {
+      "type": "did:key",
+      "value": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
+      "verified": true,
+      "verifier": "qa360-core"
+    },
+    "algorithm": "Ed25519",
+    "public_key": "base64-encoded-public-key"
+  }
+}
+```
+
+**Implementation Notes**:
+- Support DID methods: `did:key`, `did:web`, `did:github`
+- Sigstore integration for OIDC-based identity
+- Verification via DID resolver
+- Optional: Link to GitHub/GitLab identity
+
+**Cost**: $0 (decentralized)
+
+---
+
+### 3. Revocation List
+
+**Field**: `revocations` (root level)
+
+**Current**: Not implemented  
+**Future**: Proof bundle revocation mechanism
+
+**Schema**:
+```json
+{
+  "spec": "qa360.proof.v1",
+  "run": { ... },
+  "artifacts": [ ... ],
+  "results": { ... },
+  "signing": { ... },
+  "signature": "...",
+  "revocations": {
+    "check_url": "https://qa360.ai/revocations.json",
+    "status": "valid",
+    "checked_at": "2025-10-26T12:34:56Z"
+  }
+}
+```
+
+**Revocations File** (`revocations.json`):
+```json
+{
+  "version": "1.0",
+  "updated_at": "2025-10-26T12:34:56Z",
+  "revoked": [
+    {
+      "proof_id": "run-abc123",
+      "reason": "Compromised key",
+      "revoked_at": "2025-10-25T10:00:00Z"
+    }
+  ]
+}
+```
+
+**Implementation Notes**:
+- Optional revocation check during verification
+- Local cache of revocation list (24h TTL)
+- Offline mode: skip revocation check
+- Feature flag: `--check-revocations`
+
+**Cost**: $0 (static JSON file on GitHub/CDN)
+
+---
+
+### 4. Compliance Metadata
+
+**Field**: `compliance` (root level)
+
+**Current**: Not implemented  
+**Future**: Regulatory compliance markers
+
+**Schema**:
+```json
+{
+  "spec": "qa360.proof.v1",
+  "run": { ... },
+  "artifacts": [ ... ],
+  "results": { ... },
+  "signing": { ... },
+  "signature": "...",
+  "compliance": {
+    "standards": ["ISO-27001", "SOC2", "GDPR"],
+    "certifications": [
+      {
+        "name": "ISO-27001",
+        "issued_by": "BSI",
+        "valid_until": "2026-12-31"
+      }
+    ],
+    "audit_trail": "https://qa360.ai/audits/run-abc123.json"
+  }
+}
+```
+
+**Implementation Notes**:
+- Optional compliance markers
+- No validation by QA360 (user responsibility)
+- Useful for regulated industries (finance, healthcare)
+- Can link to external audit trails
+
+**Cost**: $0 (metadata only)
+
+---
+
+## 🔧 Implementation Strategy
+
+### Phase 6.1: RFC 3161 TSA (Optional)
+
+**Goal**: Add trusted timestamps to proof bundles
+
+**Steps**:
+1. Add `signing.timestamp` field to schema
+2. Implement TSA client (HTTP POST to TSA URL)
+3. Add `--tsa` flag to `qa360 report --sign`
+4. Validate TSA signature during verification
+5. Document TSA configuration
+
+**Effort**: 1-2 weeks  
+**Priority**: Medium (nice-to-have for legal compliance)
+
+---
+
+### Phase 6.2: DID Integration (Optional)
+
+**Goal**: Link proof bundles to verifiable identities
+
+**Steps**:
+1. Add `signing.identity` field to schema
+2. Implement DID resolver (did:key, did:web)
+3. Add `--identity` flag to `qa360 report --sign`
+4. Verify DID during proof verification
+5. Document identity configuration
+
+**Effort**: 2-3 weeks  
+**Priority**: Low (advanced use case)
+
+---
+
+### Phase 6.3: Revocation Mechanism (Optional)
+
+**Goal**: Enable proof bundle revocation
+
+**Steps**:
+1. Create `revocations.json` schema
+2. Add revocation check to verification
+3. Add `--check-revocations` flag
+4. Implement local cache (24h TTL)
+5. Document revocation process
+
+**Effort**: 1 week  
+**Priority**: Low (edge case)
+
+---
+
+### Phase 6.4: Compliance Metadata (Optional)
+
+**Goal**: Support regulatory compliance markers
+
+**Steps**:
+1. Add `compliance` field to schema
+2. Document compliance metadata format
+3. Add examples for ISO-27001, SOC2, GDPR
+4. No validation (user responsibility)
+
+**Effort**: 1 day  
+**Priority**: Very Low (metadata only)
+
+---
+
+## ✅ Backward Compatibility
+
+### Current Proof Bundles (v1.1.0-rc)
+
+```json
+{
+  "spec": "qa360.proof.v1",
+  "run": { ... },
+  "artifacts": [ ... ],
+  "results": { ... },
+  "signing": {
+    "signer": "local@qa360",
+    "algorithm": "Ed25519",
+    "timestamp": "2025-10-26T12:34:56Z",
+    "public_key": "..."
+  },
+  "signature": "..."
+}
+```
+
+**Status**: ✅ Valid
+
+---
+
+### Future Proof Bundles (v1.2.0+)
+
+```json
+{
+  "spec": "qa360.proof.v1",
+  "run": { ... },
+  "artifacts": [ ... ],
+  "results": { ... },
+  "signing": {
+    "signer": "local@qa360",
+    "algorithm": "Ed25519",
+    "timestamp": {
+      "value": "2025-10-26T12:34:56.789Z",
+      "tsa_url": "http://timestamp.digicert.com",
+      "tsa_cert": "sha256-abc123...",
+      "signature": "..."
+    },
+    "identity": {
+      "type": "did:key",
+      "value": "did:key:z6Mk...",
+      "verified": true
+    },
+    "public_key": "..."
+  },
+  "signature": "...",
+  "revocations": {
+    "check_url": "https://qa360.ai/revocations.json",
+    "status": "valid"
+  },
+  "compliance": {
+    "standards": ["ISO-27001"]
+  }
+}
+```
+
+**Status**: ✅ Valid (backward compatible)
+
+**Verification**:
+- v1.1.0 verifier: Ignores new fields, validates signature ✅
+- v1.2.0 verifier: Validates signature + TSA + DID + revocations ✅
+
+---
+
+## 📊 Cost Analysis
+
+| Feature | Implementation | Ongoing Cost | Priority |
+|---------|---------------|--------------|----------|
+| **RFC 3161 TSA** | 1-2 weeks | ~$0.01/proof | Medium |
+| **DID Integration** | 2-3 weeks | $0 | Low |
+| **Revocation List** | 1 week | $0 (static JSON) | Low |
+| **Compliance Metadata** | 1 day | $0 (metadata) | Very Low |
+
+**Total**: 4-6 weeks effort, ~$0.01/proof ongoing cost (TSA only)
+
+---
+
+## 🎯 Decision Criteria
+
+### When to Implement
+
+**RFC 3161 TSA**:
+- User requests legal timestamps
+- Regulated industry adoption (finance, healthcare)
+- Compliance requirements (SOC2, ISO-27001)
+
+**DID Integration**:
+- Multi-organization proof sharing
+- Decentralized identity adoption
+- Advanced security requirements
+
+**Revocation Mechanism**:
+- Compromised key incident
+- Proof invalidation needed
+- Enterprise security policy
+
+**Compliance Metadata**:
+- Regulatory audit requirements
+- Industry-specific standards
+- Customer requests
+
+---
+
+## ✅ Current Action
+
+**Phase 5 (Now)**: Document placeholders ✅  
+**Phase 6 (Later)**: Implement based on user feedback
+
+**No code changes needed now.**  
+**Schema is forward-compatible.**  
+**Users can start using v1.1.0-rc immediately.**
+
+---
+
+## 📚 References
+
+- **RFC 3161**: Time-Stamp Protocol (TSP)
+- **W3C DID**: Decentralized Identifiers
+- **Sigstore**: Software signing and verification
+- **ISO-27001**: Information security management
+- **SOC2**: Service organization controls
+
+---
+
+**Status**: ✅ Placeholders documented  
+**Next**: Wait for user feedback before implementing
+
+**Philosophy**: "Reserve the space, implement when needed."

package/docs/archive/NODE_UPGRADE_GUIDE.md

@@ -0,0 +1,188 @@
+# QA360 Node.js Upgrade Guide - v20.18.1+
+
+## 🎯 Objectif
+
+QA360 requiert maintenant **Node.js >=20.18.1** pour garantir la compatibilité avec pnpm@9.12.2 et éliminer définitivement les conflits de versions.
+
+## ⚠️ Changement Important
+
+**Avant**: Node 18, 20, 22 supportés  
+**Maintenant**: Node >=20.18.1 uniquement (20.18.1 LTS ou 22.x)
+
+## 🔍 Vérifier Votre Version Actuelle
+
+```bash
+node -v
+```
+
+Si vous voyez `v18.x.x`, vous devez upgrader.
+
+## 📦 Installation Node 20.18.1+
+
+### Option 1: Homebrew (macOS/Linux)
+
+```bash
+# Installer Node 20 LTS
+brew install node@20
+
+# Lier la version
+brew link node@20 --force --overwrite
+
+# Vérifier
+node -v  # doit afficher v20.18.1 ou supérieur
+```
+
+### Option 2: nvm (Recommandé pour multi-versions)
+
+```bash
+# Installer nvm si pas déjà fait
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
+
+# Installer Node 20.18.1
+nvm install 20.18.1
+
+# Utiliser cette version
+nvm use 20.18.1
+
+# Définir comme version par défaut
+nvm alias default 20.18.1
+
+# Vérifier
+node -v  # doit afficher v20.18.1
+```
+
+### Option 3: Téléchargement Direct
+
+Visitez https://nodejs.org/ et téléchargez Node.js 20.18.1 LTS ou supérieur.
+
+### Option 4: Windows (winget)
+
+```powershell
+winget install OpenJS.NodeJS.LTS
+```
+
+## 🔧 Configuration QA360 Après Upgrade
+
+Une fois Node 20.18.1+ installé:
+
+```bash
+# 1. Activer Corepack (gestionnaire de package managers)
+corepack enable
+
+# 2. Vérifier pnpm (doit être 9.12.2)
+pnpm -v
+
+# 3. Nettoyer et réinstaller les dépendances
+rm -rf node_modules
+rm -rf */node_modules
+rm -rf **/node_modules
+pnpm install
+
+# 4. Rebuild les modules natifs
+pnpm -r rebuild
+
+# 5. Build le projet
+pnpm -r build
+
+# 6. Vérifier que tout fonctionne
+node cli/dist/cli-minimal.js doctor --strict
+```
+
+## ✅ Validation
+
+Vérifiez que votre environnement est correct:
+
+```bash
+# Node version
+node -v
+# Attendu: v20.18.1 ou supérieur
+
+# pnpm version
+pnpm -v
+# Attendu: 9.12.2
+
+# Test QA360
+node cli/dist/cli-minimal.js --version
+# Doit afficher la version sans erreur
+```
+
+## 🚨 Erreurs Courantes
+
+### Erreur: `ERR_PNPM_UNSUPPORTED_ENGINE`
+
+```
+Your Node version is incompatible with "/Users/you/QA360".
+Expected version: >=20.18.1
+Got: v18.20.5
+```
+
+**Solution**: Upgrader Node à 20.18.1+ (voir instructions ci-dessus)
+
+### Erreur: `ERR_PNPM_BAD_PM_VERSION`
+
+```
+Multiple versions of pnpm specified
+```
+
+**Solution**: 
+```bash
+corepack enable
+corepack prepare pnpm@9.12.2 --activate
+```
+
+### Erreur: Module natif incompatible
+
+```
+Error: The module was compiled against a different Node.js version
+```
+
+**Solution**:
+```bash
+pnpm -r rebuild
+```
+
+## 📊 Matrice CI/CD
+
+Le CI QA360 exécute maintenant:
+- **OS**: Ubuntu, macOS, Windows
+- **Node**: 20.18.1, 22.x
+- **Total**: 6 combinaisons (vs 9 précédemment)
+
+Tous les jobs doivent être verts avant merge.
+
+## 🔒 Garanties
+
+- **engine-strict=true**: Node <20.18.1 est bloqué automatiquement
+- **packageManager**: pnpm@9.12.2 frozen (pas de drift possible)
+- **Reproductibilité**: Local = CI (même versions exactes)
+- **Zéro régression**: Aucun changement fonctionnel dans doctor/verify/pack
+
+## 📚 Ressources
+
+- [Node.js 20 LTS](https://nodejs.org/en/blog/release/v20.18.1)
+- [nvm Documentation](https://github.com/nvm-sh/nvm)
+- [Corepack Documentation](https://nodejs.org/api/corepack.html)
+- [pnpm Documentation](https://pnpm.io/)
+
+## 💬 Support
+
+Si vous rencontrez des problèmes:
+1. Vérifiez `node -v` et `pnpm -v`
+2. Consultez la section "Erreurs Courantes" ci-dessus
+3. Ouvrez une issue: https://github.com/xyqotech/qa360/issues
+
+## 🎯 Résumé
+
+```bash
+# Quick Start (après upgrade Node 20.18.1+)
+corepack enable
+pnpm install
+pnpm -r build
+node cli/dist/cli-minimal.js doctor --strict
+```
+
+**Stack de référence finale**:
+- Node: >=20.18.1
+- pnpm: 9.12.2
+- CI: 100% reproductible
+- Zéro conflit de versions 🎉