cognitive-modules-cli 2.2.5 → 2.2.8

package/dist/modules/runner.js

@@ -5,7 +5,10 @@
  */
 import _Ajv from 'ajv';
 const Ajv = _Ajv.default || _Ajv;
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
 import { aggregateRisk, isV22Envelope } from '../types.js';
+import { readModuleProvenance, verifyModuleIntegrity } from '../provenance.js';
 // =============================================================================
 // Schema Validation
 // =============================================================================
@@ -1046,12 +1049,113 @@ function convertLegacyToEnvelope(data, isError = false) {
         };
     }
 }
+async function enforcePolicyGates(module, policy) {
+    if (!policy)
+        return null;
+    if (policy.requireV22) {
+        const fv = module.formatVersion ?? 'unknown';
+        if (fv !== 'v2.2') {
+            return makeErrorResponse({
+                code: 'E4007', // PERMISSION_DENIED
+                message: `Certified policy requires v2.2 modules; got: ${fv} (${module.format})`,
+                explain: 'Refused by execution policy.',
+                confidence: 1.0,
+                risk: 'none',
+                suggestion: 'Migrate the module to v2.2, or run with --profile strict/default.',
+            });
+        }
+    }
+    if (policy.profile !== 'certified')
+        return null;
+    const loc = module.location;
+    if (typeof loc !== 'string' || loc.trim().length === 0) {
+        return makeErrorResponse({
+            code: 'E4007', // PERMISSION_DENIED
+            message: 'Certified policy requires an installed module with provenance; module location is missing.',
+            explain: 'Refused by execution policy.',
+            confidence: 1.0,
+            risk: 'none',
+            suggestion: 'Reinstall the module from a registry tarball that writes provenance.json.',
+        });
+    }
+    // Single-file modules (5-minute path) are intentionally not allowed in certified flows.
+    try {
+        const st = await fs.stat(loc);
+        if (!st.isDirectory()) {
+            return makeErrorResponse({
+                code: 'E4007', // PERMISSION_DENIED
+                message: `Certified policy requires module directory provenance; got a non-directory location: ${loc}`,
+                explain: 'Refused by execution policy.',
+                confidence: 1.0,
+                risk: 'none',
+                suggestion: 'Install the module via `cog add <name>` (registry tarball) or use --profile strict/default.',
+            });
+        }
+    }
+    catch {
+        return makeErrorResponse({
+            code: 'E4007',
+            message: `Certified policy requires module directory provenance, but location does not exist: ${loc}`,
+            explain: 'Refused by execution policy.',
+            confidence: 1.0,
+            risk: 'none',
+            suggestion: 'Reinstall the module from a registry tarball and retry.',
+        });
+    }
+    const prov = await readModuleProvenance(loc);
+    if (!prov) {
+        return makeErrorResponse({
+            code: 'E4007', // PERMISSION_DENIED
+            message: `Certified policy requires provenance.json in the module directory: ${loc}`,
+            explain: 'Refused by execution policy.',
+            confidence: 1.0,
+            risk: 'none',
+            suggestion: 'Reinstall the module from a registry tarball (distribution.tarball + checksum), then retry.',
+        });
+    }
+    if (prov.source.type !== 'registry') {
+        return makeErrorResponse({
+            code: 'E4007', // PERMISSION_DENIED
+            message: `Certified policy requires registry provenance; module provenance is type=${prov.source.type}`,
+            explain: 'Refused by execution policy.',
+            confidence: 1.0,
+            risk: 'none',
+            suggestion: 'Reinstall the module from a registry tarball and retry, or use --profile strict/default.',
+        });
+    }
+    // Integrity check (tamper detection).
+    const ok = await verifyModuleIntegrity(loc, prov);
+    if (!ok.ok) {
+        return makeErrorResponse({
+            code: 'E4007', // PERMISSION_DENIED
+            message: `Certified policy integrity check failed: ${ok.reason}`,
+            explain: 'Module contents appear to have been modified after install.',
+            confidence: 1.0,
+            risk: 'none',
+            suggestion: 'Reinstall the module from the registry tarball to restore integrity.',
+            details: { location: loc, reason: ok.reason },
+        });
+    }
+    // Optional: enforce that the module directory remains within itself (defense-in-depth for weird paths).
+    const resolved = path.resolve(loc);
+    if (!resolved)
+        return null;
+    return null;
+}
 // =============================================================================
 // Main Runner
 // =============================================================================
 export async function runModule(module, provider, options = {}) {
-    const { args, input, verbose = false, validateInput = true, validateOutput = true, useEnvelope, useV22, enableRepair = true, traceId, model: modelOverride } = options;
+    const { args, input, verbose = false, validateInput = true, validateOutput = true, useEnvelope, useV22, enableRepair = true, traceId, model: modelOverride, policy } = options;
     const startTime = Date.now();
+    const gate = await enforcePolicyGates(module, policy);
+    if (gate) {
+        const msg = gate.ok === false && 'error' in gate && gate.error?.message
+            ? String(gate.error.message)
+            : 'Refused by execution policy';
+        _invokeErrorHooks(module.name, new Error(msg), null);
+        return gate;
+    }
     // Determine if we should use envelope format
     const shouldUseEnvelope = useEnvelope ?? (module.output?.envelope === true || module.format === 'v2');
     // Determine if we should use v2.2 format
@@ -1324,9 +1428,9 @@ export async function runModule(module, provider, options = {}) {
  *
  * Yields StreamEvent objects as the module executes:
  * - type="start": Module execution started
- * - type="chunk": Incremental data chunk (if LLM supports streaming)
+ * - type="delta": Incremental output delta (provider streaming chunk)
  * - type="meta": Meta information available early
- * - type="complete": Final complete result
+ * - type="end": Final result envelope (always emitted)
  * - type="error": Error occurred
  *
  * @example
@@ -1339,20 +1443,30 @@ export async function runModule(module, provider, options = {}) {
  * }
  */
 export async function* runModuleStream(module, provider, options = {}) {
-    const { input, args, validateInput = true, validateOutput = true, useV22 = true, enableRepair = true, traceId, model } = options;
+    const { input, args, validateInput = true, validateOutput = true, useV22 = true, enableRepair = true, traceId, model, policy } = options;
     const startTime = Date.now();
     const moduleName = module.name;
+    const providerName = provider?.name;
     function makeEvent(type, extra = {}) {
         return {
             type,
+            version: ENVELOPE_VERSION,
             timestamp_ms: Date.now() - startTime,
-            module_name: moduleName,
+            module: moduleName,
+            ...(providerName ? { provider: providerName } : {}),
             ...extra,
         };
     }
     try {
         // Emit start event
         yield makeEvent('start');
+        const gate = await enforcePolicyGates(module, policy);
+        if (gate) {
+            const errorObj = gate?.error ?? { code: 'E4007', message: 'Refused by execution policy' };
+            yield makeEvent('error', { error: { code: errorObj.code, message: errorObj.message } });
+            yield makeEvent('end', { result: gate });
+            return;
+        }
         // Build input data
         const inputData = input || {};
         if (args && !inputData.code && !inputData.query) {
@@ -1378,7 +1492,7 @@ export async function* runModuleStream(module, provider, options = {}) {
                 _invokeErrorHooks(module.name, new Error(inputErrors.join('; ')), null);
                 const errorObj = errorResult.error;
                 yield makeEvent('error', { error: errorObj });
-                yield makeEvent('complete', { result: errorResult });
+                yield makeEvent('end', { result: errorResult });
                 return;
             }
         }
@@ -1415,7 +1529,7 @@ export async function* runModuleStream(module, provider, options = {}) {
             let streamResult;
             while (!(streamResult = await stream.next()).done) {
                 const chunk = streamResult.value;
-                yield makeEvent('chunk', { chunk });
+                yield makeEvent('delta', { delta: chunk });
             }
             // Get the final result (returned from the generator)
             fullContent = streamResult.value.content;
@@ -1429,7 +1543,7 @@ export async function* runModuleStream(module, provider, options = {}) {
             });
             fullContent = result.content;
             // Emit chunk event with full response
-            yield makeEvent('chunk', { chunk: result.content });
+            yield makeEvent('delta', { delta: result.content });
         }
         // Parse response
         let parsed;
@@ -1448,7 +1562,7 @@ export async function* runModuleStream(module, provider, options = {}) {
             // errorResult is always an error response from makeErrorResponse
             const errorObj = errorResult.error;
             yield makeEvent('error', { error: errorObj });
-            yield makeEvent('complete', { result: errorResult });
+            yield makeEvent('end', { result: errorResult });
             return;
         }
         // Convert to v2.2 envelope
@@ -1502,7 +1616,7 @@ export async function* runModuleStream(module, provider, options = {}) {
                     _invokeErrorHooks(module.name, new Error(dataErrors.join('; ')), response.data);
                     const errorObj = errorResult.error;
                     yield makeEvent('error', { error: errorObj });
-                    yield makeEvent('complete', { result: errorResult });
+                    yield makeEvent('end', { result: errorResult });
                     return;
                 }
                 const overflowErrors = validateOverflowLimits(dataToValidate, module);
@@ -1517,7 +1631,7 @@ export async function* runModuleStream(module, provider, options = {}) {
                     _invokeErrorHooks(module.name, new Error(overflowErrors.join('; ')), dataToValidate);
                     const errorObj = errorResult.error;
                     yield makeEvent('error', { error: errorObj });
-                    yield makeEvent('complete', { result: errorResult });
+                    yield makeEvent('end', { result: errorResult });
                     return;
                 }
                 const enumErrors = validateEnumStrategy(dataToValidate, module);
@@ -1532,7 +1646,7 @@ export async function* runModuleStream(module, provider, options = {}) {
                     _invokeErrorHooks(module.name, new Error(enumErrors.join('; ')), dataToValidate);
                     const errorObj = errorResult.error;
                     yield makeEvent('error', { error: errorObj });
-                    yield makeEvent('complete', { result: errorResult });
+                    yield makeEvent('end', { result: errorResult });
                     return;
                 }
             }
@@ -1554,7 +1668,7 @@ export async function* runModuleStream(module, provider, options = {}) {
                         _invokeErrorHooks(module.name, new Error(metaErrors.join('; ')), response.data);
                         const errorObj = errorResult.error;
                         yield makeEvent('error', { error: errorObj });
-                        yield makeEvent('complete', { result: errorResult });
+                        yield makeEvent('end', { result: errorResult });
                         return;
                     }
                 }
@@ -1566,8 +1680,8 @@ export async function* runModuleStream(module, provider, options = {}) {
         }
         const finalLatencyMs = Date.now() - startTime;
         _invokeAfterHooks(module.name, response, finalLatencyMs);
-        // Emit complete event
-        yield makeEvent('complete', { result: response });
+        // Emit end event
+        yield makeEvent('end', { result: response });
     }
     catch (e) {
         _invokeErrorHooks(module.name, e, null);
@@ -1579,7 +1693,7 @@ export async function* runModuleStream(module, provider, options = {}) {
         // errorResult is always an error response from makeErrorResponse
         const errorObj = errorResult.error;
         yield makeEvent('error', { error: errorObj });
-        yield makeEvent('complete', { result: errorResult });
+        yield makeEvent('end', { result: errorResult });
     }
 }
 // =============================================================================

package/dist/profile.d.ts

@@ -0,0 +1,8 @@
+import type { ExecutionPolicy } from './types.js';
+export interface ResolvePolicyInput {
+    profile?: string | null;
+    validate?: string | null;
+    noValidate?: boolean;
+    audit?: boolean;
+}
+export declare function resolveExecutionPolicy(input: ResolvePolicyInput): ExecutionPolicy;

package/dist/profile.js

@@ -0,0 +1,59 @@
+function normalizeProfile(raw) {
+    const v = (raw ?? '').trim().toLowerCase();
+    if (v === 'core')
+        return 'core';
+    if (v === 'default' || v === '')
+        return 'default';
+    if (v === 'strict')
+        return 'strict';
+    if (v === 'certified' || v === 'cert')
+        return 'certified';
+    throw new Error(`Invalid --profile: ${raw}. Expected one of: core|default|strict|certified`);
+}
+function normalizeValidate(raw) {
+    const v = (raw ?? '').trim().toLowerCase();
+    if (v === '' || v === 'auto')
+        return 'auto';
+    if (v === 'on' || v === 'true' || v === '1')
+        return 'on';
+    if (v === 'off' || v === 'false' || v === '0')
+        return 'off';
+    throw new Error(`Invalid --validate: ${raw}. Expected one of: auto|on|off`);
+}
+export function resolveExecutionPolicy(input) {
+    const profile = normalizeProfile(input.profile);
+    // Base defaults per profile.
+    let validate = profile === 'core' ? 'off' : 'on';
+    let audit = false;
+    let enableRepair = true;
+    let requireV22 = false;
+    if (profile === 'strict') {
+        validate = 'on';
+        audit = false;
+        enableRepair = true;
+        requireV22 = false;
+    }
+    if (profile === 'certified') {
+        validate = 'on';
+        audit = true;
+        enableRepair = false; // certification prefers fail-fast over runtime repair
+        requireV22 = true;
+    }
+    // CLI overrides.
+    const validateExplicit = input.validate != null || Boolean(input.noValidate);
+    if (input.validate != null) {
+        validate = normalizeValidate(input.validate);
+    }
+    if (input.noValidate) {
+        validate = 'off';
+    }
+    if (typeof input.audit === 'boolean') {
+        audit = input.audit;
+    }
+    // Trigger rule: if audit is enabled and validate wasn't explicitly turned off,
+    // force validation on (auditing without validation is usually not meaningful).
+    if (audit && !(validateExplicit && validate === 'off')) {
+        validate = 'on';
+    }
+    return { profile, validate, audit, enableRepair, requireV22 };
+}

package/dist/provenance.d.ts

@@ -0,0 +1,50 @@
+export declare const PROVENANCE_FILENAME = "provenance.json";
+export declare const PROVENANCE_SPEC = "cognitive.module.provenance/v1";
+export type ProvenanceSource = {
+    type: 'registry';
+    registryUrl?: string | null;
+    moduleName: string;
+    requestedVersion?: string | null;
+    resolvedVersion?: string | null;
+    tarballUrl: string;
+    checksum: string;
+    sha256: string;
+    quality?: {
+        verified?: boolean;
+        conformance_level?: number;
+        spec_version?: string;
+    };
+} | {
+    type: 'github';
+    repoUrl: string;
+    ref?: string | null;
+    modulePath?: string | null;
+};
+export interface ModuleIntegrity {
+    algorithm: 'sha256';
+    maxFiles: number;
+    maxTotalBytes: number;
+    maxSingleFileBytes: number;
+    totalBytes: number;
+    files: Record<string, string>;
+}
+export interface ModuleProvenance {
+    spec: typeof PROVENANCE_SPEC;
+    createdAt: string;
+    source: ProvenanceSource;
+    integrity: ModuleIntegrity;
+}
+export interface IntegrityOptions {
+    maxFiles: number;
+    maxTotalBytes: number;
+    maxSingleFileBytes: number;
+}
+export declare function computeModuleIntegrity(moduleDir: string, options?: Partial<IntegrityOptions>): Promise<ModuleIntegrity>;
+export declare function writeModuleProvenance(moduleDir: string, prov: ModuleProvenance): Promise<void>;
+export declare function readModuleProvenance(moduleDir: string): Promise<ModuleProvenance | null>;
+export declare function verifyModuleIntegrity(moduleDir: string, prov: ModuleProvenance): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+}>;

package/dist/provenance.js

@@ -0,0 +1,137 @@
+import * as fs from 'node:fs/promises';
+import { createReadStream } from 'node:fs';
+import { createHash } from 'node:crypto';
+import * as path from 'node:path';
+export const PROVENANCE_FILENAME = 'provenance.json';
+export const PROVENANCE_SPEC = 'cognitive.module.provenance/v1';
+const DEFAULT_INTEGRITY_LIMITS = {
+    maxFiles: 5_000,
+    maxTotalBytes: 50 * 1024 * 1024, // 50MB
+    maxSingleFileBytes: 20 * 1024 * 1024, // 20MB
+};
+async function hashFileSha256(filePath, size) {
+    const h = createHash('sha256');
+    await new Promise((resolve, reject) => {
+        const rs = createReadStream(filePath);
+        rs.on('data', (chunk) => h.update(chunk));
+        rs.on('error', reject);
+        rs.on('end', resolve);
+    });
+    // Include size in the hash domain separation to make accidental truncation obvious.
+    h.update(`\nsize:${size}\n`);
+    return h.digest('hex');
+}
+async function walkFiles(rootDir, relDir) {
+    const absDir = path.join(rootDir, relDir);
+    const entries = await fs.readdir(absDir, { withFileTypes: true });
+    const out = [];
+    for (const ent of entries) {
+        const rel = relDir ? path.posix.join(relDir.replace(/\\/g, '/'), ent.name) : ent.name;
+        const abs = path.join(rootDir, rel);
+        // Never hash our own provenance.
+        if (rel === PROVENANCE_FILENAME)
+            continue;
+        if (ent.name === '.DS_Store' || ent.name === '__MACOSX')
+            continue;
+        if (ent.isSymbolicLink()) {
+            // Refuse to hash symlinks. Tar extraction also rejects them.
+            continue;
+        }
+        if (ent.isDirectory()) {
+            out.push(...await walkFiles(rootDir, rel));
+            continue;
+        }
+        if (ent.isFile()) {
+            out.push(rel);
+        }
+    }
+    return out;
+}
+export async function computeModuleIntegrity(moduleDir, options = {}) {
+    const limits = {
+        ...DEFAULT_INTEGRITY_LIMITS,
+        ...options,
+    };
+    const relFiles = (await walkFiles(moduleDir, '')).sort((a, b) => a.localeCompare(b));
+    if (relFiles.length > limits.maxFiles) {
+        throw new Error(`Module has too many files to hash (max ${limits.maxFiles}): ${relFiles.length}`);
+    }
+    const files = {};
+    let totalBytes = 0;
+    for (const rel of relFiles) {
+        const abs = path.join(moduleDir, rel);
+        const st = await fs.stat(abs);
+        if (!st.isFile())
+            continue;
+        if (st.size > limits.maxSingleFileBytes) {
+            throw new Error(`Module file too large for integrity hashing (max ${limits.maxSingleFileBytes} bytes): ${rel}`);
+        }
+        totalBytes += st.size;
+        if (totalBytes > limits.maxTotalBytes) {
+            throw new Error(`Module too large for integrity hashing (max ${limits.maxTotalBytes} bytes)`);
+        }
+        const sha256 = await hashFileSha256(abs, st.size);
+        files[rel] = sha256;
+    }
+    return {
+        algorithm: 'sha256',
+        maxFiles: limits.maxFiles,
+        maxTotalBytes: limits.maxTotalBytes,
+        maxSingleFileBytes: limits.maxSingleFileBytes,
+        totalBytes,
+        files,
+    };
+}
+export async function writeModuleProvenance(moduleDir, prov) {
+    const filePath = path.join(moduleDir, PROVENANCE_FILENAME);
+    const json = JSON.stringify(prov, null, 2) + '\n';
+    await fs.writeFile(filePath, json, 'utf-8');
+}
+export async function readModuleProvenance(moduleDir) {
+    const filePath = path.join(moduleDir, PROVENANCE_FILENAME);
+    try {
+        const raw = await fs.readFile(filePath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object')
+            return null;
+        if (parsed.spec !== PROVENANCE_SPEC)
+            return null;
+        if (!parsed.source || typeof parsed.source !== 'object')
+            return null;
+        if (!parsed.integrity || typeof parsed.integrity !== 'object')
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export async function verifyModuleIntegrity(moduleDir, prov) {
+    const expected = prov.integrity?.files ?? {};
+    const expectedKeys = Object.keys(expected).sort();
+    if (expectedKeys.length === 0) {
+        return { ok: false, reason: 'Provenance integrity.files is empty' };
+    }
+    const computed = await computeModuleIntegrity(moduleDir, {
+        maxFiles: prov.integrity.maxFiles,
+        maxTotalBytes: prov.integrity.maxTotalBytes,
+        maxSingleFileBytes: prov.integrity.maxSingleFileBytes,
+    });
+    const computedKeys = Object.keys(computed.files).sort();
+    if (expectedKeys.length !== computedKeys.length) {
+        return { ok: false, reason: 'Integrity file list changed (file count mismatch)' };
+    }
+    for (let i = 0; i < expectedKeys.length; i++) {
+        if (expectedKeys[i] !== computedKeys[i]) {
+            return { ok: false, reason: `Integrity file list changed (mismatch at ${i}: ${expectedKeys[i]} vs ${computedKeys[i]})` };
+        }
+    }
+    for (const rel of expectedKeys) {
+        const a = expected[rel];
+        const b = computed.files[rel];
+        if (a !== b) {
+            return { ok: false, reason: `Integrity mismatch for ${rel}` };
+        }
+    }
+    return { ok: true };
+}

package/dist/registry/assets.d.ts

@@ -0,0 +1,48 @@
+export interface BuildRegistryOptions {
+    tag?: string | null;
+    tarballBaseUrl?: string | null;
+    modulesDir: string;
+    v1RegistryPath: string;
+    outDir: string;
+    registryOut: string;
+    namespace: string;
+    runtimeMin: string;
+    repository: string;
+    homepage: string;
+    license: string;
+    timestamp?: string | null;
+    only?: string[];
+}
+export interface VerifyRegistryOptions {
+    registryIndexPath: string;
+    assetsDir?: string;
+    maxTarballBytes?: number;
+    remote?: boolean;
+    fetchTimeoutMs?: number;
+    maxIndexBytes?: number;
+    concurrency?: number;
+}
+export interface RegistryBuildResult {
+    registryOut: string;
+    outDir: string;
+    updated: string;
+    modules: Array<{
+        name: string;
+        version: string;
+        file: string;
+        sha256: string;
+        size_bytes: number;
+    }>;
+}
+export interface RegistryVerifyResult {
+    ok: boolean;
+    checked: number;
+    passed: number;
+    failed: number;
+    failures: Array<{
+        module: string;
+        reason: string;
+    }>;
+}
+export declare function buildRegistryAssets(opts: BuildRegistryOptions): Promise<RegistryBuildResult>;
+export declare function verifyRegistryAssets(opts: VerifyRegistryOptions): Promise<RegistryVerifyResult>;