@rigour-labs/core 5.5.4 → 6.0.0

package/dist/firewall/adversarial.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Adversarial replay — deterministic corpus against the firewall kernel.
+ * Successful unexpected allows emit suggested deny regressions (not LLM verdicts).
+ */
+import type { AdversarialCase, AdversarialCaseResult } from './types.js';
+export declare const DEFAULT_ADVERSARIAL_CORPUS: AdversarialCase[];
+export declare function runAdversarialCase(c: AdversarialCase): AdversarialCaseResult;
+export declare function runAdversarialCorpus(cases?: AdversarialCase[]): {
+    passed: number;
+    failed: number;
+    results: AdversarialCaseResult[];
+};
+export declare function persistAdversarialReport(cwd: string, report: ReturnType<typeof runAdversarialCorpus>): Promise<string>;

package/dist/firewall/adversarial.js

@@ -0,0 +1,125 @@
+/**
+ * Adversarial replay — deterministic corpus against the firewall kernel.
+ * Successful unexpected allows emit suggested deny regressions (not LLM verdicts).
+ */
+import fs from 'fs-extra';
+import path from 'path';
+import { evaluateActionDeterministic } from './capability-broker.js';
+export const DEFAULT_ADVERSARIAL_CORPUS = [
+    {
+        id: 'deny-shell-meta',
+        description: 'Shell metacharacters must be denied',
+        proposedAction: {
+            action: 'shell.exec',
+            resource: 'shell',
+            command: 'ls; rm -rf /',
+        },
+        expectedDecision: 'deny',
+    },
+    {
+        id: 'deny-undeclared-mcp',
+        description: 'Undeclared MCP tool must be denied',
+        proposedAction: {
+            action: 'mcp.call',
+            resource: 'github.merge_pull_request',
+        },
+        expectedDecision: 'deny',
+        allowlist: ['rigour_check'],
+    },
+    {
+        id: 'deny-out-of-scope-write',
+        description: 'Write outside agent scope must be scope-violation',
+        proposedAction: {
+            action: 'filesystem.write',
+            resource: '.github/workflows/deploy.yml',
+        },
+        expectedDecision: 'scope-violation',
+        agentScope: ['packages/rigour-core/**'],
+    },
+    {
+        id: 'deny-git-force-push',
+        description: 'git push --force must be denied',
+        proposedAction: {
+            action: 'shell.exec',
+            resource: 'shell',
+            command: 'git push --force origin main',
+        },
+        expectedDecision: 'deny',
+    },
+    {
+        id: 'allow-scoped-write',
+        description: 'In-scope write is allowed',
+        proposedAction: {
+            action: 'filesystem.write',
+            resource: 'packages/rigour-core/src/firewall/types.ts',
+        },
+        expectedDecision: 'allow',
+        agentScope: ['packages/rigour-core/**'],
+    },
+    {
+        id: 'allow-typed-test',
+        description: 'Allowlisted vitest command is allowed',
+        proposedAction: {
+            action: 'shell.exec',
+            resource: 'shell',
+            command: 'vitest run packages/rigour-core/src/firewall',
+        },
+        expectedDecision: 'allow',
+    },
+];
+function normalizeDecision(d) {
+    return d;
+}
+export function runAdversarialCase(c) {
+    const agentScopes = c.agentScope
+        ? [{ agentId: 'adversarial-agent', taskScope: c.agentScope }]
+        : [];
+    const evaluation = evaluateActionDeterministic({
+        action: c.proposedAction.action,
+        resource: c.proposedAction.resource,
+        command: c.proposedAction.command,
+        toolAllowlist: c.allowlist ?? [],
+        agentScopes,
+        agentId: c.agentScope ? 'adversarial-agent' : undefined,
+    });
+    const actual = normalizeDecision(evaluation.decision);
+    const passed = actual === c.expectedDecision;
+    let suggestedRule;
+    if (!passed && (actual === 'allow')) {
+        suggestedRule = [
+            'deny:',
+            `  - tool: ${c.proposedAction.action}`,
+            `    resource: ${JSON.stringify(c.proposedAction.resource)}`,
+            c.proposedAction.command ? `    command_matches: ${JSON.stringify(c.proposedAction.command)}` : null,
+        ].filter(Boolean).join('\n');
+    }
+    return {
+        caseId: c.id,
+        expected: c.expectedDecision,
+        actual,
+        passed,
+        reason: evaluation.reason,
+        suggestedRule,
+    };
+}
+export function runAdversarialCorpus(cases = DEFAULT_ADVERSARIAL_CORPUS) {
+    const results = cases.map(runAdversarialCase);
+    return {
+        passed: results.filter(r => r.passed).length,
+        failed: results.filter(r => !r.passed).length,
+        results,
+    };
+}
+export async function persistAdversarialReport(cwd, report) {
+    const dir = path.join(cwd, '.rigour');
+    await fs.ensureDir(dir);
+    const out = path.join(dir, 'adversarial-report.json');
+    await fs.writeJson(out, { ...report, generatedAt: new Date().toISOString() }, { spaces: 2 });
+    const regressions = report.results.filter(r => !r.passed && r.suggestedRule);
+    if (regressions.length > 0) {
+        const fixturePath = path.join(dir, 'adversarial-regressions.yml');
+        const body = regressions.map(r => `# from ${r.caseId}\n${r.suggestedRule}`).join('\n\n');
+        await fs.writeFile(fixturePath, body + '\n');
+    }
+    return out;
+}

package/dist/firewall/arbitration-token.d.ts

@@ -0,0 +1,8 @@
+/**
+ * One-time arbitration tokens — bind Studio approve/reject to the requesting MCP process.
+ */
+export declare function issueArbitrationToken(cwd: string, requestId: string, ttlMs?: number): Promise<string>;
+/**
+ * Consume a one-time token. Returns false if missing, expired, or mismatched.
+ */
+export declare function consumeArbitrationToken(cwd: string, requestId: string, token: string | undefined): Promise<boolean>;

package/dist/firewall/arbitration-token.js

@@ -0,0 +1,58 @@
+/**
+ * One-time arbitration tokens — bind Studio approve/reject to the requesting MCP process.
+ */
+import { randomBytes, timingSafeEqual } from 'crypto';
+import fs from 'fs-extra';
+import path from 'path';
+function storePath(cwd) {
+    return path.join(cwd, '.rigour', 'arbitration-tokens.json');
+}
+async function readStore(cwd) {
+    const p = storePath(cwd);
+    if (!(await fs.pathExists(p)))
+        return {};
+    try {
+        return await fs.readJson(p);
+    }
+    catch {
+        return {};
+    }
+}
+async function writeStore(cwd, store) {
+    await fs.ensureDir(path.join(cwd, '.rigour'));
+    await fs.writeJson(storePath(cwd), store, { spaces: 2 });
+}
+export async function issueArbitrationToken(cwd, requestId, ttlMs = 60_000) {
+    const token = randomBytes(24).toString('hex');
+    const store = await readStore(cwd);
+    const now = Date.now();
+    for (const [k, v] of Object.entries(store)) {
+        if (v.expiresAt < now)
+            delete store[k];
+    }
+    store[requestId] = { token, expiresAt: now + ttlMs };
+    await writeStore(cwd, store);
+    return token;
+}
+/**
+ * Consume a one-time token. Returns false if missing, expired, or mismatched.
+ */
+export async function consumeArbitrationToken(cwd, requestId, token) {
+    if (!token || !requestId)
+        return false;
+    const store = await readStore(cwd);
+    const entry = store[requestId];
+    if (!entry)
+        return false;
+    if (Date.now() > entry.expiresAt) {
+        delete store[requestId];
+        await writeStore(cwd, store);
+        return false;
+    }
+    const a = Buffer.from(entry.token);
+    const b = Buffer.from(token);
+    const ok = a.length === b.length && timingSafeEqual(a, b);
+    delete store[requestId];
+    await writeStore(cwd, store);
+    return ok;
+}

package/dist/firewall/attestation.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Signed attestation bundles for completed transactions.
+ * Keys prefer env / home directory — not agent-writable workspace keys for CI admit.
+ */
+import type { AttestationBundle, TransactionRecord } from './types.js';
+export declare function resolveAttestationKey(cwd: string): Promise<{
+    key: Buffer;
+    source: 'env' | 'home' | 'workspace';
+}>;
+/** @deprecated use resolveAttestationKey */
+export declare function ensureAttestationKey(cwd: string): Promise<Buffer>;
+export declare function computeArtifactDigest(files: string[], contents: Map<string, string>): string;
+export declare function getGitCommitSha(dir: string): Promise<string | null>;
+export declare function getGitTreeDigest(dir: string): Promise<string | null>;
+export declare function createAttestation(cwd: string, input: {
+    transaction: TransactionRecord;
+    gateResults: {
+        status: string;
+        score?: number;
+        failedGates: string[];
+    };
+    toolsUsed?: string[];
+    overrides?: string[];
+    userId?: string;
+    fileContents?: Map<string, string>;
+    commitSha?: string;
+    treeDigest?: string;
+    verifyRoot?: string;
+}): Promise<AttestationBundle>;
+export declare function verifyAttestation(cwd: string, bundle: AttestationBundle): Promise<boolean>;
+export declare function loadLatestAttestation(cwd: string): Promise<AttestationBundle | null>;
+/**
+ * CI admission: valid signature, PASS gates, bound commit/tree, fresh, non-workspace-key unless allowed.
+ */
+export declare function admitForCi(cwd: string): Promise<{
+    admit: boolean;
+    reason: string;
+}>;

package/dist/firewall/attestation.js

@@ -0,0 +1,197 @@
+/**
+ * Signed attestation bundles for completed transactions.
+ * Keys prefer env / home directory — not agent-writable workspace keys for CI admit.
+ */
+import { createHash, createHmac, randomBytes } from 'crypto';
+import fs from 'fs-extra';
+import os from 'os';
+import path from 'path';
+import { execa } from 'execa';
+const KEY_FILE = 'attestation.key';
+export async function resolveAttestationKey(cwd) {
+    const envKey = process.env.RIGOUR_ATTESTATION_KEY;
+    if (envKey && envKey.length >= 32) {
+        return { key: Buffer.from(envKey, 'utf8'), source: 'env' };
+    }
+    const homeKeyPath = path.join(os.homedir(), '.rigour', KEY_FILE);
+    if (await fs.pathExists(homeKeyPath)) {
+        return { key: await fs.readFile(homeKeyPath), source: 'home' };
+    }
+    const workspaceKeyPath = path.join(cwd, '.rigour', KEY_FILE);
+    if (await fs.pathExists(workspaceKeyPath)) {
+        return { key: await fs.readFile(workspaceKeyPath), source: 'workspace' };
+    }
+    // Create home key by default (outside agent workspace)
+    await fs.ensureDir(path.join(os.homedir(), '.rigour'));
+    const key = randomBytes(32);
+    await fs.writeFile(homeKeyPath, key, { mode: 0o600 });
+    return { key, source: 'home' };
+}
+/** @deprecated use resolveAttestationKey */
+export async function ensureAttestationKey(cwd) {
+    const { key } = await resolveAttestationKey(cwd);
+    return key;
+}
+function payloadForSign(bundle) {
+    return JSON.stringify({
+        version: bundle.version,
+        transactionId: bundle.transactionId,
+        agentId: bundle.agentId,
+        userId: bundle.userId,
+        scope: bundle.scope,
+        policyHash: bundle.policyHash,
+        capabilities: bundle.capabilities,
+        filesUsed: bundle.filesUsed,
+        toolsUsed: bundle.toolsUsed,
+        gateResults: bundle.gateResults,
+        overrides: bundle.overrides,
+        artifactDigest: bundle.artifactDigest,
+        commitSha: bundle.commitSha,
+        treeDigest: bundle.treeDigest,
+    });
+}
+export function computeArtifactDigest(files, contents) {
+    const h = createHash('sha256');
+    for (const f of [...files].sort()) {
+        h.update(f);
+        h.update('\0');
+        h.update(contents.get(f) ?? '');
+        h.update('\0');
+    }
+    return h.digest('hex');
+}
+export async function getGitCommitSha(dir) {
+    try {
+        const { stdout } = await execa('git', ['rev-parse', 'HEAD'], { cwd: dir, shell: false });
+        return stdout.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function getGitTreeDigest(dir) {
+    try {
+        const { stdout } = await execa('git', ['rev-parse', 'HEAD^{tree}'], { cwd: dir, shell: false });
+        return stdout.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function createAttestation(cwd, input) {
+    const { key } = await resolveAttestationKey(cwd);
+    const verifyRoot = input.verifyRoot || input.transaction.worktreePath || cwd;
+    const commitSha = input.commitSha ?? (await getGitCommitSha(verifyRoot)) ?? undefined;
+    const treeDigest = input.treeDigest ?? (await getGitTreeDigest(verifyRoot)) ?? undefined;
+    const files = input.transaction.filesChanged;
+    const contents = input.fileContents ?? new Map();
+    if (files.length > 0 && contents.size === 0) {
+        for (const f of files) {
+            const abs = path.join(verifyRoot, f);
+            if (await fs.pathExists(abs)) {
+                contents.set(f, await fs.readFile(abs, 'utf-8'));
+            }
+        }
+    }
+    let artifactDigest = computeArtifactDigest(files, contents);
+    if (files.length === 0 && treeDigest) {
+        artifactDigest = createHash('sha256').update(`tree:${treeDigest}`).digest('hex');
+    }
+    if (!treeDigest && files.length === 0) {
+        throw new Error('Attestation requires treeDigest or non-empty filesChanged with contents');
+    }
+    const unsigned = {
+        version: 1,
+        transactionId: input.transaction.id,
+        agentId: input.transaction.agentId,
+        userId: input.userId,
+        scope: input.transaction.scope,
+        policyHash: input.transaction.policyHash,
+        capabilities: input.transaction.capabilitiesIssued,
+        filesUsed: files,
+        toolsUsed: input.toolsUsed ?? [],
+        gateResults: input.gateResults,
+        overrides: input.overrides ?? [],
+        artifactDigest,
+        commitSha,
+        treeDigest,
+    };
+    const signedAt = new Date().toISOString();
+    const signature = createHmac('sha256', key)
+        .update(payloadForSign(unsigned) + signedAt)
+        .digest('hex');
+    const bundle = { ...unsigned, signedAt, signature };
+    const outDir = path.join(cwd, '.rigour', 'attestations');
+    await fs.ensureDir(outDir);
+    await fs.writeJson(path.join(outDir, `${bundle.transactionId}.json`), bundle, { spaces: 2 });
+    await fs.writeJson(path.join(cwd, '.rigour', 'attestation-latest.json'), bundle, { spaces: 2 });
+    return bundle;
+}
+export async function verifyAttestation(cwd, bundle) {
+    const { key } = await resolveAttestationKey(cwd);
+    const { signature, signedAt, ...rest } = bundle;
+    const expected = createHmac('sha256', key)
+        .update(payloadForSign(rest) + signedAt)
+        .digest('hex');
+    return expected === signature;
+}
+export async function loadLatestAttestation(cwd) {
+    const p = path.join(cwd, '.rigour', 'attestation-latest.json');
+    if (!(await fs.pathExists(p)))
+        return null;
+    try {
+        return await fs.readJson(p);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * CI admission: valid signature, PASS gates, bound commit/tree, fresh, non-workspace-key unless allowed.
+ */
+export async function admitForCi(cwd) {
+    const { source } = await resolveAttestationKey(cwd);
+    if (source === 'workspace' && process.env.RIGOUR_ALLOW_WORKSPACE_ATTESTATION_KEY !== '1') {
+        return {
+            admit: false,
+            reason: 'Attestation key is workspace-local; set RIGOUR_ATTESTATION_KEY or ~/.rigour/attestation.key',
+        };
+    }
+    const bundle = await loadLatestAttestation(cwd);
+    if (!bundle) {
+        return { admit: false, reason: 'No attestation bundle found' };
+    }
+    const valid = await verifyAttestation(cwd, bundle);
+    if (!valid) {
+        return { admit: false, reason: 'Attestation signature invalid' };
+    }
+    if (bundle.gateResults.status !== 'PASS') {
+        return { admit: false, reason: `Gates not PASS (${bundle.gateResults.status})` };
+    }
+    if (!bundle.treeDigest && (!bundle.filesUsed || bundle.filesUsed.length === 0)) {
+        return { admit: false, reason: 'Attestation missing treeDigest and filesUsed' };
+    }
+    if (!bundle.artifactDigest || bundle.artifactDigest.length < 16) {
+        return { admit: false, reason: 'Attestation artifactDigest missing or trivial' };
+    }
+    const maxAgeMs = Number(process.env.RIGOUR_ATTESTATION_MAX_AGE_MS || 24 * 60 * 60 * 1000);
+    const age = Date.now() - Date.parse(bundle.signedAt);
+    if (!Number.isFinite(age) || age < 0 || age > maxAgeMs) {
+        return { admit: false, reason: 'Attestation expired or has invalid signedAt' };
+    }
+    const headSha = await getGitCommitSha(cwd);
+    if (bundle.commitSha && headSha && bundle.commitSha !== headSha) {
+        return {
+            admit: false,
+            reason: `Attestation commitSha ${bundle.commitSha.slice(0, 8)}≠ HEAD ${headSha.slice(0, 8)}`,
+        };
+    }
+    const headTree = await getGitTreeDigest(cwd);
+    if (bundle.treeDigest && headTree && bundle.treeDigest !== headTree) {
+        return {
+            admit: false,
+            reason: `Attestation treeDigest mismatch vs HEAD tree`,
+        };
+    }
+    return { admit: true, reason: 'Valid attestation with PASS gates and bound tree/commit' };
+}

package/dist/firewall/capability-broker.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Capability broker — issues one-use, short-lived capabilities.
+ */
+import type { CapabilityAction, CapabilityGrant, PolicyEvaluation } from './types.js';
+import { type AgentScopeRecord } from './scope-enforcement.js';
+export interface BrokerConfig {
+    defaultTtlMs: number;
+    toolAllowlist: string[];
+    agentScopes: AgentScopeRecord[];
+    agentId?: string;
+    taskId?: string;
+}
+export declare class CapabilityBroker {
+    private readonly config;
+    private grants;
+    private decisions;
+    private readonly policyHash;
+    constructor(config: BrokerConfig);
+    getPolicyHash(): string;
+    getDecisions(): PolicyEvaluation[];
+    listGrants(): CapabilityGrant[];
+    issue(action: CapabilityAction, resource: string, constraints?: Record<string, unknown>): CapabilityGrant;
+    evaluateProposal(input: {
+        action: CapabilityAction;
+        resource: string;
+        args?: Record<string, unknown>;
+        command?: string;
+        capabilityId?: string;
+    }): PolicyEvaluation;
+    private prechecks;
+    private denyUndeclaredMcp;
+    private denyOutOfScopeWrite;
+    private evaluateWithCapability;
+    private consumeCapability;
+    private denyCap;
+    private record;
+    persistDecisions(cwd: string): Promise<void>;
+}
+/** Pure evaluate for adversarial replay (fresh broker per call). */
+export declare function evaluateActionDeterministic(input: {
+    action: CapabilityAction;
+    resource: string;
+    command?: string;
+    toolAllowlist: string[];
+    agentScopes: AgentScopeRecord[];
+    agentId?: string;
+}): PolicyEvaluation;