@iflow-mcp/jkheadley-instar 0.26.2

package/dist/core/PairingProtocol.js

@@ -0,0 +1,265 @@
+/**
+ * Pairing protocol for multi-machine coordination.
+ *
+ * Handles the secure pairing flow:
+ * 1. Pairing code generation (WORD-WORD-NNNN)
+ * 2. Key exchange (ephemeral X25519 ECDH, code-bound via HKDF)
+ * 3. Short Authentication String (SAS) derivation
+ * 4. Encrypted secret transfer (XChaCha20-Poly1305)
+ *
+ * Security properties:
+ * - Online brute-force: 3-attempt rate limit + 2-minute expiry
+ * - MITM: SAS verification (24-bit, 6 symbols)
+ * - Forward secrecy: ephemeral keys per pairing session
+ * - Offline brute-force: rate limiting + SAS prevents practical exploitation
+ *   (SPAKE2 can be substituted via PairingKeyExchange interface for paranoid mode)
+ *
+ * Phase 2 of the multi-machine spec.
+ */
+import crypto from 'node:crypto';
+// ── Pairing Code ─────────────────────────────────────────────────────
+/**
+ * 256 common, easy-to-pronounce English nouns.
+ * Chosen for: no homophones, no ambiguity, no offensive words,
+ * easy to say aloud, easy to type.
+ */
+const WORDLIST = [
+    'APPLE', 'ARROW', 'BADGE', 'BAKER', 'BEACH', 'BELL', 'BIRD', 'BLADE',
+    'BLOOM', 'BOARD', 'BONE', 'BOOK', 'BRAIN', 'BREAD', 'BRICK', 'BRIDGE',
+    'BROOK', 'BRUSH', 'CABIN', 'CAKE', 'CAMP', 'CANDLE', 'CAPE', 'CARD',
+    'CASTLE', 'CEDAR', 'CHAIN', 'CHALK', 'CHEST', 'CHIEF', 'CHILD', 'CLAW',
+    'CLIFF', 'CLOCK', 'CLOUD', 'COBRA', 'CORAL', 'CRANE', 'CREEK', 'CROWN',
+    'DANCE', 'DAWN', 'DEER', 'DELTA', 'DEPTH', 'DIVER', 'DOCK', 'DOVE',
+    'DRAFT', 'DREAM', 'DRIFT', 'DRUM', 'EAGLE', 'EARTH', 'ELDER', 'ELM',
+    'EMBER', 'FABLE', 'FALCON', 'FARM', 'FEAST', 'FIELD', 'FINCH', 'FLAME',
+    'FLASK', 'FLINT', 'FLOOD', 'FLUTE', 'FORGE', 'FROST', 'FRUIT', 'GATE',
+    'GHOST', 'GLASS', 'GLOBE', 'GOAT', 'GRAIN', 'GRAPE', 'GRASS', 'GROVE',
+    'GUARD', 'GUILD', 'GULL', 'HAVEN', 'HAWK', 'HEART', 'HEDGE', 'HERON',
+    'HILL', 'HIVE', 'HOLLY', 'HORN', 'HORSE', 'HOUSE', 'IVORY', 'JADE',
+    'JEWEL', 'JUDGE', 'KAYAK', 'KELP', 'KING', 'KITE', 'KNOT', 'LAKE',
+    'LANCE', 'LARK', 'LATCH', 'LEAF', 'LEVER', 'LIGHT', 'LILY', 'LION',
+    'LOFT', 'LOTUS', 'LUNAR', 'MAPLE', 'MARSH', 'MASON', 'MAST', 'MEDAL',
+    'MESA', 'MILL', 'MINT', 'MOAT', 'MOLE', 'MOON', 'MOSS', 'MOTH',
+    'MOUND', 'NAIL', 'NEST', 'NOBLE', 'NORTH', 'NURSE', 'OAK', 'OCEAN',
+    'OLIVE', 'ORBIT', 'OTTER', 'OWL', 'PALM', 'PATCH', 'PATH', 'PEARL',
+    'PEAK', 'PETAL', 'PILOT', 'PINE', 'PLAIN', 'PLANT', 'PLUM', 'POND',
+    'PORCH', 'PRESS', 'PRISM', 'PULSE', 'QUAIL', 'QUARTZ', 'QUEEN', 'QUEST',
+    'RAVEN', 'REALM', 'REED', 'REEF', 'RIDGE', 'RING', 'RIVER', 'ROBIN',
+    'ROCK', 'ROPE', 'ROSE', 'RUBY', 'SAGE', 'SAND', 'SCOUT', 'SEAL',
+    'SHADE', 'SHELL', 'SHIELD', 'SHORE', 'SILK', 'SKULL', 'SLATE', 'SLOPE',
+    'SNAKE', 'SOLAR', 'SPARK', 'SPEAR', 'SPINE', 'SPOKE', 'SPRAY', 'SPRING',
+    'STAFF', 'STAMP', 'STAR', 'STEEL', 'STEM', 'STONE', 'STORM', 'STOVE',
+    'SURGE', 'SWAN', 'SWORD', 'TABLE', 'THORN', 'TIDE', 'TIGER', 'TORCH',
+    'TOWER', 'TRAIL', 'TREE', 'TRIBE', 'TROUT', 'TRUNK', 'TULIP', 'VALE',
+    'VAULT', 'VEIL', 'VINE', 'VIOLA', 'VIPER', 'VOICE', 'WAGON', 'WALNUT',
+    'WATCH', 'WATER', 'WAVE', 'WHEAT', 'WHEEL', 'WIND', 'WING', 'WOLF',
+    'WOOD', 'WREN', 'YACHT', 'YARN', 'YOKE', 'ZEBRA', 'ZENITH', 'ZINC',
+    'BLAZE', 'CANYON', 'CREST', 'DUSK', 'FLARE', 'GLEN', 'HARBOR', 'IRIS',
+    'JADE', 'LANTERN', 'MEADOW', 'OPAL', 'PIXEL', 'QUILL', 'SABER', 'TALON',
+];
+/**
+ * Generate a pairing code: WORD-WORD-NNNN
+ * ~29.3 bits of entropy (256 * 256 * 10000 = 655,360,000 combinations).
+ */
+export function generatePairingCode() {
+    const word1 = WORDLIST[crypto.randomInt(WORDLIST.length)];
+    const word2 = WORDLIST[crypto.randomInt(WORDLIST.length)];
+    const digits = crypto.randomInt(10000).toString().padStart(4, '0');
+    return `${word1}-${word2}-${digits}`;
+}
+/**
+ * Constant-time comparison of pairing codes.
+ * Prevents timing side-channel attacks.
+ */
+export function comparePairingCodes(a, b) {
+    const bufA = Buffer.from(a.toUpperCase());
+    const bufB = Buffer.from(b.toUpperCase());
+    if (bufA.length !== bufB.length)
+        return false;
+    return crypto.timingSafeEqual(bufA, bufB);
+}
+// ── SAS (Short Authentication String) ────────────────────────────────
+/**
+ * 16 symbols for SAS display. Each represents 4 bits.
+ * Chosen for visual distinctness and terminal compatibility.
+ */
+const SAS_SYMBOLS = [
+    { word: 'wolf', emoji: '🐺' },
+    { word: 'wave', emoji: '🌊' },
+    { word: 'fire', emoji: '🔥' },
+    { word: 'music', emoji: '🎵' },
+    { word: 'moon', emoji: '🌙' },
+    { word: 'butterfly', emoji: '🦋' },
+    { word: 'star', emoji: '⭐' },
+    { word: 'tree', emoji: '🌲' },
+    { word: 'diamond', emoji: '💎' },
+    { word: 'sun', emoji: '☀️' },
+    { word: 'heart', emoji: '❤️' },
+    { word: 'bird', emoji: '🐦' },
+    { word: 'fish', emoji: '🐟' },
+    { word: 'leaf', emoji: '🍃' },
+    { word: 'key', emoji: '🔑' },
+    { word: 'bell', emoji: '🔔' },
+];
+/**
+ * Derive a Short Authentication String from a shared key and both public keys.
+ *
+ * SAS = first 24 bits of SHA-256(sharedKey || sort(pubKeyA, pubKeyB))
+ * Mapped to 6 symbols from a set of 16 (4 bits each).
+ *
+ * @param sharedKey - The ECDH shared secret or SPAKE2 session key
+ * @param publicKeyA - Public key of machine A (base64 or PEM)
+ * @param publicKeyB - Public key of machine B (base64 or PEM)
+ */
+export function deriveSAS(sharedKey, publicKeyA, publicKeyB) {
+    // Sort public keys for deterministic ordering (both machines get same SAS)
+    const sorted = [publicKeyA, publicKeyB].sort();
+    const input = Buffer.concat([
+        sharedKey,
+        Buffer.from(sorted[0]),
+        Buffer.from(sorted[1]),
+    ]);
+    const hash = crypto.createHash('sha256').update(input).digest();
+    // Extract 24 bits (6 nibbles) → 6 symbols
+    const symbols = [];
+    for (let i = 0; i < 3; i++) {
+        const byte = hash[i];
+        symbols.push(SAS_SYMBOLS[(byte >> 4) & 0x0F]);
+        symbols.push(SAS_SYMBOLS[byte & 0x0F]);
+    }
+    const display = symbols.map(s => `${s.word} ${s.emoji}`).join(' - ');
+    return { symbols, display };
+}
+/**
+ * Generate an ephemeral X25519 key pair for a single pairing session.
+ */
+export function generateEphemeralKeyPair() {
+    const { publicKey, privateKey } = crypto.generateKeyPairSync('x25519');
+    return {
+        publicKey: publicKey.export({ type: 'spki', format: 'der' }),
+        privateKey,
+    };
+}
+/**
+ * Perform X25519 ECDH key agreement, then derive a session key using HKDF
+ * bound to the pairing code. This ensures the session key is tied to both
+ * the ECDH exchange AND the pairing code.
+ *
+ * @param myPrivateKey - This machine's ephemeral private key
+ * @param theirPublicKeyDer - The other machine's ephemeral public key (DER format)
+ * @param pairingCode - The shared pairing code (used as HKDF salt)
+ * @param info - HKDF info string (identifies the purpose)
+ */
+export function deriveSessionKey(myPrivateKey, theirPublicKeyDer, pairingCode, info = 'instar-pairing-v1') {
+    const theirPublicKey = crypto.createPublicKey({
+        key: theirPublicKeyDer,
+        type: 'spki',
+        format: 'der',
+    });
+    // X25519 ECDH → raw shared secret
+    const rawShared = crypto.diffieHellman({
+        publicKey: theirPublicKey,
+        privateKey: myPrivateKey,
+    });
+    // HKDF: derive a proper session key from the ECDH output + pairing code
+    // The pairing code as salt binds this session to the code
+    const sessionKey = crypto.hkdfSync('sha256', rawShared, Buffer.from(pairingCode.toUpperCase()), Buffer.from(info), 32);
+    return Buffer.from(sessionKey);
+}
+// ── Authenticated Encryption ─────────────────────────────────────────
+const XCHACHA20_NONCE_SIZE = 24;
+const XCHACHA20_TAG_SIZE = 16;
+/**
+ * Encrypt data with XChaCha20-Poly1305 (or chacha20-poly1305 with 12-byte nonce).
+ * Node.js doesn't natively support XChaCha20, so we use chacha20-poly1305.
+ *
+ * @param plaintext - Data to encrypt
+ * @param key - 32-byte encryption key
+ * @param aad - Additional authenticated data (optional)
+ * @returns { nonce, ciphertext, tag } all as Buffers
+ */
+export function encrypt(plaintext, key, aad) {
+    const nonce = crypto.randomBytes(12); // chacha20-poly1305 uses 12-byte nonce
+    const cipher = crypto.createCipheriv('chacha20-poly1305', key, nonce, {
+        authTagLength: XCHACHA20_TAG_SIZE,
+    });
+    if (aad)
+        cipher.setAAD(aad, { plaintextLength: plaintext.length });
+    const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return { nonce, ciphertext, tag };
+}
+/**
+ * Decrypt data with ChaCha20-Poly1305.
+ *
+ * @param ciphertext - Encrypted data
+ * @param key - 32-byte decryption key
+ * @param nonce - 12-byte nonce
+ * @param tag - 16-byte authentication tag
+ * @param aad - Additional authenticated data (must match encryption)
+ * @returns Decrypted plaintext
+ * @throws If authentication fails (tampered data or wrong key)
+ */
+export function decrypt(ciphertext, key, nonce, tag, aad) {
+    const decipher = crypto.createDecipheriv('chacha20-poly1305', key, nonce, {
+        authTagLength: XCHACHA20_TAG_SIZE,
+    });
+    decipher.setAuthTag(tag);
+    if (aad)
+        decipher.setAAD(aad, { plaintextLength: ciphertext.length });
+    return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+}
+/**
+ * Create a new pairing session.
+ */
+export function createPairingSession(options) {
+    return {
+        code: options?.code ?? generatePairingCode(),
+        createdAt: Date.now(),
+        failedAttempts: 0,
+        maxAttempts: options?.maxAttempts ?? 3,
+        expiryMs: options?.expiryMs ?? 2 * 60 * 1000, // 2 minutes
+        ephemeralKeys: generateEphemeralKeyPair(),
+        consumed: false,
+    };
+}
+/**
+ * Check if a pairing session is still valid.
+ */
+export function isPairingSessionValid(session) {
+    if (session.consumed)
+        return false;
+    if (session.failedAttempts >= session.maxAttempts)
+        return false;
+    if (Date.now() - session.createdAt > session.expiryMs)
+        return false;
+    return true;
+}
+/**
+ * Validate a pairing code against a session.
+ * Returns true if the code matches and the session is valid.
+ * Increments failedAttempts on mismatch.
+ */
+export function validatePairingCode(session, code) {
+    if (session.consumed) {
+        return { valid: false, reason: 'Code already used' };
+    }
+    if (session.failedAttempts >= session.maxAttempts) {
+        return { valid: false, reason: 'Too many attempts' };
+    }
+    if (Date.now() - session.createdAt > session.expiryMs) {
+        return { valid: false, reason: 'Code expired' };
+    }
+    if (!comparePairingCodes(session.code, code)) {
+        session.failedAttempts++;
+        const remaining = session.maxAttempts - session.failedAttempts;
+        return {
+            valid: false,
+            reason: remaining > 0
+                ? `Wrong code. ${remaining} attempt${remaining === 1 ? '' : 's'} remaining.`
+                : 'Too many attempts. Generate a new code.',
+        };
+    }
+    return { valid: true };
+}
+//# sourceMappingURL=PairingProtocol.js.map

package/dist/core/PairingProtocol.js.map

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

package/dist/core/PatternAnalyzer.d.ts

@@ -0,0 +1,128 @@
+/**
+ * PatternAnalyzer — Cross-execution pattern detection for Living Skills (PROP-229).
+ *
+ * Reads execution journals across runs and detects:
+ * - Consistent additions: steps appearing in ≥60% of runs but not in definition
+ * - Consistent omissions: defined steps skipped in ≥50% of runs
+ * - Novel additions: steps appearing for the first time
+ * - Duration drift: execution time trending significantly up/down
+ * - Gate effectiveness: whether gate commands consistently pass or fail
+ *
+ * Outputs a PatternReport with scored findings and optional EvolutionManager proposals.
+ */
+import type { EvolutionType } from './types.js';
+import { ExecutionJournal } from './ExecutionJournal.js';
+export type PatternType = 'consistent-addition' | 'consistent-omission' | 'novel-addition' | 'duration-drift' | 'gate-ineffective';
+export type PatternConfidence = 'high' | 'medium' | 'low';
+export interface DetectedPattern {
+    /** What kind of pattern */
+    type: PatternType;
+    /** Human-readable description */
+    description: string;
+    /** How confident we are (based on sample size and consistency) */
+    confidence: PatternConfidence;
+    /** The step name involved (null for duration-drift) */
+    step: string | null;
+    /** How many runs showed this pattern */
+    occurrences: number;
+    /** Total runs in the analysis window */
+    totalRuns: number;
+    /** Occurrence rate (0–1) */
+    rate: number;
+    /** Suggested action */
+    suggestion: string;
+    /** Data supporting this pattern (e.g., duration values) */
+    evidence?: Record<string, unknown>;
+}
+export interface PatternReport {
+    /** Job slug analyzed */
+    jobSlug: string;
+    /** Agent ID */
+    agentId: string;
+    /** How many execution records were analyzed */
+    runsAnalyzed: number;
+    /** Time window (days) */
+    days: number;
+    /** Detected patterns, sorted by confidence then rate */
+    patterns: DetectedPattern[];
+    /** Summary statistics */
+    summary: {
+        /** Total unique steps seen across all runs */
+        uniqueSteps: number;
+        /** Defined steps in the job */
+        definedSteps: number;
+        /** Average duration across runs (null if no data) */
+        avgDurationMinutes: number | null;
+        /** Duration trend: 'increasing', 'decreasing', 'stable', 'insufficient-data' */
+        durationTrend: 'increasing' | 'decreasing' | 'stable' | 'insufficient-data';
+        /** Overall success rate */
+        successRate: number;
+    };
+    /** ISO timestamp when this analysis was generated */
+    analyzedAt: string;
+}
+export interface PatternAnalyzerOptions {
+    /** Minimum runs required for pattern detection (default: 3) */
+    minRuns?: number;
+    /** Threshold for consistent additions (default: 0.6 = 60%) */
+    additionThreshold?: number;
+    /** Threshold for consistent omissions (default: 0.5 = 50%) */
+    omissionThreshold?: number;
+    /** Duration drift multiplier (default: 2.0 = 2x expected) */
+    durationDriftMultiplier?: number;
+    /** Days to analyze (default: 30) */
+    days?: number;
+    /** Agent ID (default: 'default') */
+    agentId?: string;
+}
+export declare class PatternAnalyzer {
+    private journal;
+    constructor(journal: ExecutionJournal);
+    /**
+     * Analyze execution records for a job and detect patterns.
+     */
+    analyze(jobSlug: string, opts?: PatternAnalyzerOptions): PatternReport;
+    /**
+     * Analyze all jobs and return reports.
+     */
+    analyzeAll(opts?: PatternAnalyzerOptions): PatternReport[];
+    /**
+     * Generate evolution proposals from a pattern report.
+     * Returns proposal-ready objects (caller is responsible for submitting to EvolutionManager).
+     */
+    toProposals(report: PatternReport): Array<{
+        title: string;
+        source: string;
+        description: string;
+        type: EvolutionType;
+        impact: 'high' | 'medium' | 'low';
+        effort: 'high' | 'medium' | 'low';
+        proposedBy: string;
+        tags: string[];
+    }>;
+    /**
+     * Steps appearing in ≥threshold of runs but not in the job definition.
+     */
+    private detectConsistentAdditions;
+    /**
+     * Defined steps that are skipped in ≥threshold of runs.
+     */
+    private detectConsistentOmissions;
+    /**
+     * Steps appearing for the first time (only in the most recent run).
+     */
+    private detectNovelAdditions;
+    /**
+     * Duration trending significantly above historical average.
+     * Uses linear regression on the last N runs to detect trend direction.
+     */
+    private detectDurationDrift;
+    /**
+     * Detect if gate commands are consistently finding nothing to do.
+     * If a job consistently runs but has 0 actual steps, the gate may be ineffective.
+     */
+    private detectGateIneffective;
+    private computeDurationTrend;
+    private patternToProposal;
+}
+//# sourceMappingURL=PatternAnalyzer.d.ts.map

package/dist/core/PatternAnalyzer.d.ts.map

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