@rigour-labs/core 6.1.0 → 6.2.0

package/dist/firewall/action-ir.d.ts

@@ -0,0 +1,8 @@
+import type { AgentAction } from './types.js';
+export declare function normalizeMcpAction(input: {
+    actorId: string;
+    taskId: string;
+    server: string;
+    tool: string;
+    args?: Record<string, unknown>;
+}): AgentAction;

package/dist/firewall/action-ir.js

@@ -0,0 +1,44 @@
+const DESTRUCTIVE_WORDS = /(?:^|[_./-])(delete|destroy|drop|purge|remove|terminate|merge)(?:$|[_./-])/i;
+const WRITE_WORDS = /(?:^|[_./-])(create|update|write|post|put|patch|send|deploy|restart|apply)(?:$|[_./-])/i;
+const READ_WORDS = /(?:^|[_./-])(get|list|read|search|find|fetch|view|status)(?:$|[_./-])/i;
+function classifyEnvironment(resource, args) {
+    const text = `${resource} ${JSON.stringify(args)}`.toLowerCase();
+    if (/\b(prod|production)\b/.test(text))
+        return 'production';
+    if (/\b(stage|staging|preprod)\b/.test(text))
+        return 'staging';
+    if (/\b(dev|development)\b/.test(text))
+        return 'development';
+    if (/\b(local|localhost|127\.0\.0\.1)\b/.test(text))
+        return 'local';
+    return 'unknown';
+}
+function classifySideEffect(tool) {
+    if (DESTRUCTIVE_WORDS.test(tool))
+        return 'destructive';
+    if (WRITE_WORDS.test(tool))
+        return 'external-write';
+    if (READ_WORDS.test(tool))
+        return 'read';
+    return 'external-write';
+}
+export function normalizeMcpAction(input) {
+    const args = input.args ?? {};
+    const resource = `mcp://${input.server}/${input.tool}`;
+    const sideEffect = classifySideEffect(input.tool);
+    return {
+        version: 1,
+        actorId: input.actorId,
+        taskId: input.taskId,
+        channel: 'mcp',
+        operation: input.tool,
+        resource,
+        environment: classifyEnvironment(resource, args),
+        sideEffect,
+        reversibility: sideEffect === 'read' ? 'high' : sideEffect === 'destructive' ? 'low' : 'unknown',
+        sensitivity: /secret|credential|token|password|private/i.test(`${input.tool} ${JSON.stringify(args)}`)
+            ? 'restricted'
+            : 'normal',
+        blastRadius: sideEffect === 'read' ? 'single-resource' : sideEffect === 'destructive' ? 'broad' : 'unknown',
+    };
+}

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

@@ -9,6 +9,8 @@ export interface BrokerConfig {
     agentScopes: AgentScopeRecord[];
     agentId?: string;
     taskId?: string;
+    /** Legacy preserves the pre-6.2 auto-issue behaviour for existing callers. */
+    authorizationMode?: 'legacy' | 'observe' | 'enforce';
 }
 export declare class CapabilityBroker {
     private readonly config;

package/dist/firewall/capability-broker.js

@@ -53,6 +53,25 @@ export class CapabilityBroker {
         if (input.capabilityId) {
             return this.evaluateWithCapability(input.capabilityId, input.action, input.resource, timestamp);
         }
+        if (this.config.authorizationMode === 'enforce') {
+            return this.record({
+                decision: 'deny',
+                reason: `Explicit capability required for ${input.action}:${input.resource}`,
+                ruleId: 'capability.required',
+                policyHash: this.policyHash,
+                timestamp,
+            });
+        }
+        if (this.config.authorizationMode === 'observe') {
+            return this.record({
+                decision: 'allow',
+                simulatedDecision: 'deny',
+                reason: `Observe mode: explicit capability would be required for ${input.action}:${input.resource}`,
+                ruleId: 'capability.observe-required',
+                policyHash: this.policyHash,
+                timestamp,
+            });
+        }
         const grant = this.issue(input.action, input.resource, input.args);
         return this.record({
             decision: 'allow',

package/dist/firewall/execution-receipt.d.ts

@@ -0,0 +1,8 @@
+import type { ExecutionReceipt } from './types.js';
+export declare function appendExecutionReceipt(cwd: string, input: Omit<ExecutionReceipt, 'version' | 'id' | 'repositoryId' | 'createdAt' | 'previousReceipt' | 'digest' | 'signature'>, controlRoot?: string): Promise<ExecutionReceipt>;
+export declare function listExecutionReceipts(cwd: string, limit?: number, controlRoot?: string): Promise<ExecutionReceipt[]>;
+export declare function verifyExecutionReceiptChain(cwd: string, controlRoot?: string): Promise<{
+    valid: boolean;
+    count: number;
+    reason?: string;
+}>;

package/dist/firewall/execution-receipt.js

@@ -0,0 +1,107 @@
+import { createHash, createHmac, randomBytes, randomUUID } from 'crypto';
+import fs from 'fs-extra';
+import { setTimeout as delay } from 'node:timers/promises';
+import path from 'path';
+import { getRepositoryControlId, getTrustedControlDir } from './trusted-control.js';
+async function receiptKey(cwd, controlRoot) {
+    const dir = getTrustedControlDir(cwd, controlRoot);
+    const keyPath = path.join(dir, 'receipt.key');
+    await fs.ensureDir(dir, 0o700);
+    if (await fs.pathExists(keyPath)) {
+        const existing = await fs.readFile(keyPath);
+        if (existing.length !== 32)
+            throw new Error('Receipt signing key is invalid');
+        return existing;
+    }
+    const key = randomBytes(32);
+    await fs.writeFile(keyPath, key, { mode: 0o600 });
+    return key;
+}
+async function acquireReceiptLock(logPath) {
+    const lockPath = `${logPath}.append-lock`;
+    for (let attempt = 0; attempt < 100; attempt += 1) {
+        try {
+            return await fs.promises.open(lockPath, 'wx', 0o600);
+        }
+        catch (error) {
+            if (error?.code !== 'EEXIST')
+                throw error;
+            await delay(10);
+        }
+    }
+    throw new Error('Timed out waiting to append execution receipt');
+}
+export async function appendExecutionReceipt(cwd, input, controlRoot) {
+    const dir = getTrustedControlDir(cwd, controlRoot);
+    const logPath = path.join(dir, 'receipts.jsonl');
+    await fs.ensureDir(dir, 0o700);
+    const lock = await acquireReceiptLock(logPath);
+    try {
+        let previousReceipt;
+        if (await fs.pathExists(logPath)) {
+            const lines = (await fs.readFile(logPath, 'utf8')).trim().split('\n').filter(Boolean);
+            const previous = lines.at(-1);
+            if (previous)
+                previousReceipt = JSON.parse(previous).digest;
+        }
+        const unsigned = {
+            version: 1,
+            id: randomUUID(),
+            repositoryId: getRepositoryControlId(cwd),
+            ...input,
+            createdAt: new Date().toISOString(),
+            previousReceipt,
+        };
+        const serialized = JSON.stringify(unsigned);
+        const digest = createHash('sha256').update(serialized).digest('hex');
+        const signature = createHmac('sha256', await receiptKey(cwd, controlRoot)).update(digest).digest('hex');
+        const receipt = { ...unsigned, digest, signature };
+        await fs.appendFile(logPath, `${JSON.stringify(receipt)}\n`, { mode: 0o600 });
+        // Studio consumes this untrusted projection. Enforcement always reads the
+        // signed log outside the repository, never this workspace-owned copy.
+        const projectionDir = path.join(cwd, '.rigour');
+        try {
+            await fs.ensureDir(projectionDir);
+            await fs.appendFile(path.join(projectionDir, 'execution-receipts.jsonl'), `${JSON.stringify(receipt)}\n`);
+        }
+        catch {
+            // A read-only agent sandbox may block the optional Studio projection.
+            // The canonical trusted receipt is already durable and remains valid.
+        }
+        return receipt;
+    }
+    finally {
+        await lock.close();
+        await fs.remove(`${logPath}.append-lock`);
+    }
+}
+export async function listExecutionReceipts(cwd, limit = 50, controlRoot) {
+    const source = path.join(getTrustedControlDir(cwd, controlRoot), 'receipts.jsonl');
+    if (!await fs.pathExists(source))
+        return [];
+    return (await fs.readFile(source, 'utf8')).trim().split('\n').filter(Boolean)
+        .slice(-Math.max(1, limit)).map((line) => JSON.parse(line));
+}
+export async function verifyExecutionReceiptChain(cwd, controlRoot) {
+    try {
+        const receipts = await listExecutionReceipts(cwd, Number.MAX_SAFE_INTEGER, controlRoot);
+        const key = receipts.length > 0 ? await receiptKey(cwd, controlRoot) : null;
+        let previous;
+        for (const receipt of receipts) {
+            const { digest, signature, ...unsigned } = receipt;
+            if (unsigned.previousReceipt !== previous) {
+                return { valid: false, count: receipts.length, reason: `Broken chain at receipt ${receipt.id}` };
+            }
+            const expectedDigest = createHash('sha256').update(JSON.stringify(unsigned)).digest('hex');
+            const expectedSignature = createHmac('sha256', key).update(expectedDigest).digest('hex');
+            if (digest !== expectedDigest || signature !== expectedSignature) {
+                return { valid: false, count: receipts.length, reason: `Invalid signature at receipt ${receipt.id}` };
+            }
+            previous = digest;
+        }
+        return { valid: true, count: receipts.length };
+    }
+    catch (error) {
+        return { valid: false, count: 0, reason: error?.message ?? String(error) };
+    }
+}

package/dist/firewall/firewall.test.js

@@ -49,6 +49,17 @@ describe('scope enforcement', () => {
     });
 });
 describe('capability broker', () => {
+    it('requires explicit authority in enforce mode and reports shadow decisions in observe mode', () => {
+        const base = { defaultTtlMs: 1000, toolAllowlist: ['*'], agentScopes: [] };
+        const enforced = new CapabilityBroker({ ...base, authorizationMode: 'enforce' });
+        expect(enforced.evaluateProposal({ action: 'mcp.call', resource: 'github__get_issue' })).toMatchObject({
+            decision: 'deny', ruleId: 'capability.required',
+        });
+        const observed = new CapabilityBroker({ ...base, authorizationMode: 'observe' });
+        expect(observed.evaluateProposal({ action: 'mcp.call', resource: 'github__get_issue' })).toMatchObject({
+            decision: 'allow', simulatedDecision: 'deny', ruleId: 'capability.observe-required',
+        });
+    });
     it('denies undeclared MCP tools', () => {
         const broker = new CapabilityBroker({
             defaultTtlMs: 1000,

package/dist/firewall/index.d.ts

@@ -8,3 +8,6 @@ export * from './attestation.js';
 export * from './adversarial.js';
 export * from './mcp-gateway.js';
 export * from './arbitration-token.js';
+export * from './action-ir.js';
+export * from './trusted-control.js';
+export * from './execution-receipt.js';

package/dist/firewall/index.js

@@ -8,3 +8,6 @@ export * from './attestation.js';
 export * from './adversarial.js';
 export * from './mcp-gateway.js';
 export * from './arbitration-token.js';
+export * from './action-ir.js';
+export * from './trusted-control.js';
+export * from './execution-receipt.js';

package/dist/firewall/trusted-control.d.ts

@@ -0,0 +1,44 @@
+import type { CapabilityAction, CapabilityGrant, EnforcementMode } from './types.js';
+export interface GatewayServerConfig {
+    command: string;
+    args?: string[];
+    allow: string[];
+    env?: Record<string, string>;
+}
+export interface GatewayControlConfig {
+    version: 1;
+    mode: EnforcementMode;
+    principalId: string;
+    agentId: string;
+    taskId: string;
+    servers: Record<string, GatewayServerConfig>;
+}
+export declare function getRepositoryControlId(cwd: string): string;
+export declare function getTrustedControlDir(cwd: string, controlRoot?: string): string;
+export declare function getGatewayPolicyHash(cwd: string, config: GatewayControlConfig | null): string;
+export declare function validateGatewayConfig(value: unknown): GatewayControlConfig;
+export declare function saveGatewayConfig(cwd: string, config: GatewayControlConfig, controlRoot?: string): Promise<string>;
+export declare function loadGatewayConfig(cwd: string, controlRoot?: string): Promise<GatewayControlConfig | null>;
+interface GrantInput {
+    issuerId: string;
+    subjectId: string;
+    taskId: string;
+    action: CapabilityAction;
+    resource: string;
+    ttlMs: number;
+    parentCapabilityId?: string;
+}
+export declare function loadTrustedGrant(cwd: string, id: string, controlRoot?: string): Promise<CapabilityGrant | null>;
+export declare function issueTrustedGrant(cwd: string, input: GrantInput, controlRoot?: string): Promise<CapabilityGrant>;
+export declare function consumeTrustedGrant(cwd: string, input: {
+    id: string;
+    subjectId: string;
+    taskId: string;
+    action: CapabilityAction;
+    resource: string;
+}, controlRoot?: string): Promise<{
+    ok: boolean;
+    reason: string;
+    grant?: CapabilityGrant;
+}>;
+export {};

package/dist/firewall/trusted-control.js

@@ -0,0 +1,236 @@
+import { createHash, randomUUID } from 'crypto';
+import fs from 'fs-extra';
+import os from 'os';
+import path from 'path';
+import { hashPolicy } from './policy-hash.js';
+function canonicalRepository(cwd) {
+    try {
+        return fs.realpathSync(cwd);
+    }
+    catch {
+        return path.resolve(cwd);
+    }
+}
+export function getRepositoryControlId(cwd) {
+    return createHash('sha256').update(canonicalRepository(cwd)).digest('hex').slice(0, 24);
+}
+export function getTrustedControlDir(cwd, controlRoot = path.join(os.homedir(), '.rigour', 'control')) {
+    return path.join(controlRoot, getRepositoryControlId(cwd));
+}
+export function getGatewayPolicyHash(cwd, config) {
+    return hashPolicy({ repositoryId: getRepositoryControlId(cwd), ...(config ?? {}) });
+}
+function requiredString(input, key) {
+    if (typeof input[key] !== 'string' || !String(input[key]).trim())
+        throw new Error(`${key} is required`);
+}
+function validateStringArray(value, label, required) {
+    if (value === undefined && !required)
+        return;
+    if (!Array.isArray(value) || value.some((item) => typeof item !== 'string' || !item.trim())) {
+        throw new Error(`${label} must contain only non-empty strings`);
+    }
+}
+function validateEnvironment(value, serverName) {
+    if (value === undefined)
+        return;
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`Server ${serverName} env must be a string map`);
+    }
+    if (Object.values(value).some((item) => typeof item !== 'string')) {
+        throw new Error(`Server ${serverName} env must be a string map`);
+    }
+}
+function validateServer(name, server) {
+    if (!/^[a-z0-9_-]+$/i.test(name))
+        throw new Error(`Invalid server name: ${name}`);
+    if (!server || typeof server.command !== 'string' || !server.command.trim()) {
+        throw new Error(`Server ${name} command is required`);
+    }
+    validateStringArray(server.args, `Server ${name} args`, false);
+    validateStringArray(server.allow, `Server ${name} allow`, true);
+    validateEnvironment(server.env, name);
+}
+function validateConfigHeader(input) {
+    if (input.version !== 1)
+        throw new Error('Gateway config version must be 1');
+    if (input.mode !== 'observe' && input.mode !== 'enforce')
+        throw new Error('Gateway mode must be observe or enforce');
+}
+function validateConfigIdentities(input) {
+    for (const key of ['principalId', 'agentId', 'taskId'])
+        requiredString(input, key);
+}
+function validateServers(input) {
+    if (!input.servers || typeof input.servers !== 'object')
+        throw new Error('At least one downstream server is required');
+    const servers = input.servers;
+    if (Object.keys(servers).length === 0)
+        throw new Error('At least one downstream server is required');
+    for (const [name, server] of Object.entries(servers))
+        validateServer(name, server);
+}
+async function ensureTrustedDir(cwd, controlRoot) {
+    const dir = getTrustedControlDir(cwd, controlRoot);
+    await fs.ensureDir(dir, 0o700);
+    await fs.chmod(dir, 0o700).catch(() => undefined);
+    return dir;
+}
+export function validateGatewayConfig(value) {
+    if (!value || typeof value !== 'object')
+        throw new Error('Gateway config must be an object');
+    const input = value;
+    validateConfigHeader(input);
+    validateConfigIdentities(input);
+    validateServers(input);
+    return input;
+}
+export async function saveGatewayConfig(cwd, config, controlRoot) {
+    const trusted = validateGatewayConfig(config);
+    const dir = await ensureTrustedDir(cwd, controlRoot);
+    const destination = path.join(dir, 'gateway.json');
+    await fs.writeJson(destination, trusted, { spaces: 2, mode: 0o600 });
+    await fs.chmod(destination, 0o600).catch(() => undefined);
+    return destination;
+}
+export async function loadGatewayConfig(cwd, controlRoot) {
+    const source = path.join(getTrustedControlDir(cwd, controlRoot), 'gateway.json');
+    if (!await fs.pathExists(source))
+        return null;
+    return validateGatewayConfig(await fs.readJson(source));
+}
+function grantPath(cwd, id, controlRoot) {
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(id)) {
+        throw new Error('Invalid capability id');
+    }
+    return path.join(getTrustedControlDir(cwd, controlRoot), 'capabilities', `${id}.json`);
+}
+export async function loadTrustedGrant(cwd, id, controlRoot) {
+    let source;
+    try {
+        source = grantPath(cwd, id, controlRoot);
+    }
+    catch {
+        return null;
+    }
+    if (!await fs.pathExists(source))
+        return null;
+    return fs.readJson(source);
+}
+function assertDelegationSubset(parent, input) {
+    if (parent.used)
+        throw new Error('Parent capability is already consumed');
+    if (Date.now() > parent.expiresAt)
+        throw new Error('Parent capability is expired');
+    if (parent.subjectId !== input.issuerId)
+        throw new Error('Delegating issuer is not the parent subject');
+    if (parent.taskId !== input.taskId)
+        throw new Error('Child capability must preserve parent task');
+    if (parent.action !== input.action || parent.resource !== input.resource) {
+        throw new Error('Child capability must preserve parent action and resource');
+    }
+    if (Date.now() + input.ttlMs > parent.expiresAt)
+        throw new Error('Child capability cannot outlive parent capability');
+}
+function validateGrantInput(input) {
+    if (!input.issuerId || !input.subjectId || !input.taskId || !input.resource) {
+        throw new Error('Grant identity, task, and resource are required');
+    }
+    if (!Number.isFinite(input.ttlMs) || input.ttlMs < 1_000 || input.ttlMs > 3_600_000) {
+        throw new Error('Grant TTL must be between 1 second and 1 hour');
+    }
+}
+async function consumeParentGrant(cwd, input, controlRoot) {
+    if (!input.parentCapabilityId)
+        return;
+    const parent = await loadTrustedGrant(cwd, input.parentCapabilityId, controlRoot);
+    if (!parent)
+        throw new Error('Parent capability not found');
+    assertDelegationSubset(parent, input);
+    const consumed = await consumeTrustedGrant(cwd, {
+        id: parent.id,
+        subjectId: input.issuerId,
+        taskId: input.taskId,
+        action: input.action,
+        resource: input.resource,
+    }, controlRoot);
+    if (!consumed.ok)
+        throw new Error(`Parent capability could not be consumed: ${consumed.reason}`);
+}
+function validateGrantAgainstConfig(input, config) {
+    if (!config)
+        return;
+    if (input.subjectId !== config.agentId || input.taskId !== config.taskId) {
+        throw new Error('Grant subject and task must match the trusted gateway configuration');
+    }
+    if (!input.parentCapabilityId && input.issuerId !== config.principalId) {
+        throw new Error('Root capability issuer must match the trusted gateway principal');
+    }
+}
+export async function issueTrustedGrant(cwd, input, controlRoot) {
+    validateGrantInput(input);
+    const config = await loadGatewayConfig(cwd, controlRoot);
+    validateGrantAgainstConfig(input, config);
+    await consumeParentGrant(cwd, input, controlRoot);
+    const policyHash = getGatewayPolicyHash(cwd, config);
+    const grant = {
+        id: randomUUID(),
+        action: input.action,
+        resource: input.resource,
+        expiresAt: Date.now() + input.ttlMs,
+        taskId: input.taskId,
+        agentId: input.subjectId,
+        issuerId: input.issuerId,
+        subjectId: input.subjectId,
+        parentCapabilityId: input.parentCapabilityId,
+        policyHash,
+        used: false,
+    };
+    const dir = path.dirname(grantPath(cwd, grant.id, controlRoot));
+    await fs.ensureDir(dir, 0o700);
+    await fs.writeJson(grantPath(cwd, grant.id, controlRoot), grant, { spaces: 2, mode: 0o600 });
+    return grant;
+}
+export async function consumeTrustedGrant(cwd, input, controlRoot) {
+    let source;
+    try {
+        source = grantPath(cwd, input.id, controlRoot);
+    }
+    catch {
+        return { ok: false, reason: 'Invalid capability id' };
+    }
+    const lock = `${source}.consume-lock`;
+    let handle;
+    try {
+        await fs.ensureDir(path.dirname(source), 0o700);
+        handle = await fs.promises.open(lock, 'wx', 0o600);
+    }
+    catch (error) {
+        if (error?.code === 'EEXIST')
+            return { ok: false, reason: 'Capability consumption already in progress' };
+        throw error;
+    }
+    try {
+        const grant = await loadTrustedGrant(cwd, input.id, controlRoot);
+        if (!grant)
+            return { ok: false, reason: 'Unknown capability id' };
+        if (grant.used)
+            return { ok: false, reason: 'Capability already consumed' };
+        if (Date.now() > grant.expiresAt)
+            return { ok: false, reason: 'Capability expired' };
+        if (grant.subjectId !== input.subjectId || grant.taskId !== input.taskId)
+            return { ok: false, reason: 'Capability identity or task mismatch' };
+        if (grant.action !== input.action || grant.resource !== input.resource)
+            return { ok: false, reason: 'Capability action or resource mismatch' };
+        const config = await loadGatewayConfig(cwd, controlRoot);
+        if (grant.policyHash !== getGatewayPolicyHash(cwd, config))
+            return { ok: false, reason: 'Capability policy is stale' };
+        grant.used = true;
+        await fs.writeJson(source, grant, { spaces: 2, mode: 0o600 });
+        return { ok: true, reason: 'Capability consumed', grant };
+    }
+    finally {
+        await handle.close();
+        await fs.remove(lock);
+    }
+}

package/dist/firewall/trusted-control.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/firewall/trusted-control.test.js

@@ -0,0 +1,165 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import fs from 'fs-extra';
+import os from 'os';
+import path from 'path';
+import { appendExecutionReceipt, consumeTrustedGrant, getTrustedControlDir, issueTrustedGrant, normalizeMcpAction, saveGatewayConfig, verifyExecutionReceiptChain, } from './index.js';
+const repositories = [];
+const controlRoots = [];
+async function repository() {
+    const cwd = await fs.mkdtemp(path.join(os.tmpdir(), 'rigour-gateway-test-'));
+    repositories.push(cwd);
+    return cwd;
+}
+async function controlRoot() {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), 'rigour-control-test-'));
+    controlRoots.push(root);
+    return root;
+}
+afterEach(async () => {
+    for (const cwd of repositories.splice(0)) {
+        await fs.remove(cwd);
+    }
+    for (const root of controlRoots.splice(0))
+        await fs.remove(root);
+});
+describe('trusted gateway control', () => {
+    it('stores configuration outside the repository', async () => {
+        const cwd = await repository();
+        const root = await controlRoot();
+        const location = await saveGatewayConfig(cwd, {
+            version: 1,
+            mode: 'observe',
+            principalId: 'owner',
+            agentId: 'agent-1',
+            taskId: 'task-1',
+            servers: { github: { command: 'github-mcp', allow: ['get_issue'] } },
+        }, root);
+        expect(location.startsWith(cwd)).toBe(false);
+        expect(await fs.pathExists(location)).toBe(true);
+    });
+    it('consumes a capability exactly once', async () => {
+        const cwd = await repository();
+        const root = await controlRoot();
+        const grant = await issueTrustedGrant(cwd, {
+            issuerId: 'owner', subjectId: 'agent-1', taskId: 'task-1',
+            action: 'mcp.call', resource: 'mcp://github/create_issue', ttlMs: 60_000,
+        }, root);
+        const proposal = {
+            id: grant.id, subjectId: 'agent-1', taskId: 'task-1',
+            action: 'mcp.call', resource: 'mcp://github/create_issue',
+        };
+        expect((await consumeTrustedGrant(cwd, proposal, root)).ok).toBe(true);
+        expect((await consumeTrustedGrant(cwd, proposal, root)).ok).toBe(false);
+    });
+    it('rejects path traversal in a capability id', async () => {
+        const cwd = await repository();
+        const root = await controlRoot();
+        const result = await consumeTrustedGrant(cwd, {
+            id: '../../gateway', subjectId: 'agent-1', taskId: 'task-1',
+            action: 'mcp.call', resource: 'mcp://github/create_issue',
+        }, root);
+        expect(result).toMatchObject({ ok: false, reason: 'Invalid capability id' });
+    });
+    it('rejects delegated authority that expands its parent', async () => {
+        const cwd = await repository();
+        const root = await controlRoot();
+        const parent = await issueTrustedGrant(cwd, {
+            issuerId: 'owner', subjectId: 'lead-agent', taskId: 'task-1',
+            action: 'mcp.call', resource: 'mcp://github/get_issue', ttlMs: 60_000,
+        }, root);
+        await expect(issueTrustedGrant(cwd, {
+            issuerId: 'lead-agent', subjectId: 'worker-agent', taskId: 'task-1',
+            action: 'mcp.call', resource: 'mcp://github/delete_repo', ttlMs: 30_000,
+            parentCapabilityId: parent.id,
+        }, root)).rejects.toThrow('preserve parent action and resource');
+    });
+    it('consumes the parent when delegated authority is issued', async () => {
+        const cwd = await repository();
+        const root = await controlRoot();
+        const parent = await issueTrustedGrant(cwd, {
+            issuerId: 'owner', subjectId: 'lead-agent', taskId: 'task-1',
+            action: 'mcp.call', resource: 'mcp://github/get_issue', ttlMs: 60_000,
+        }, root);
+        const child = await issueTrustedGrant(cwd, {
+            issuerId: 'lead-agent', subjectId: 'worker-agent', taskId: 'task-1',
+            action: 'mcp.call', resource: 'mcp://github/get_issue', ttlMs: 30_000,
+            parentCapabilityId: parent.id,
+        }, root);
+        expect(child.parentCapabilityId).toBe(parent.id);
+        const parentResult = await consumeTrustedGrant(cwd, {
+            id: parent.id, subjectId: 'lead-agent', taskId: 'task-1',
+            action: 'mcp.call', resource: 'mcp://github/get_issue',
+        }, root);
+        expect(parentResult).toMatchObject({ ok: false, reason: 'Capability already consumed' });
+    });
+    it('invalidates grants when the trusted policy changes', async () => {
+        const cwd = await repository();
+        const root = await controlRoot();
+        const base = {
+            version: 1, principalId: 'owner', agentId: 'agent-1', taskId: 'task-1',
+            servers: { github: { command: 'github-mcp', allow: ['get_issue'] } },
+        };
+        await saveGatewayConfig(cwd, { ...base, mode: 'observe' }, root);
+        const grant = await issueTrustedGrant(cwd, {
+            issuerId: 'owner', subjectId: 'agent-1', taskId: 'task-1',
+            action: 'mcp.call', resource: 'mcp://github/get_issue', ttlMs: 60_000,
+        }, root);
+        await saveGatewayConfig(cwd, { ...base, mode: 'enforce' }, root);
+        const result = await consumeTrustedGrant(cwd, {
+            id: grant.id, subjectId: 'agent-1', taskId: 'task-1',
+            action: 'mcp.call', resource: 'mcp://github/get_issue',
+        }, root);
+        expect(result).toMatchObject({ ok: false, reason: 'Capability policy is stale' });
+    });
+});
+describe('action normalization and receipts', () => {
+    it('defaults unknown tools to external writes instead of assuming read-only', () => {
+        const action = normalizeMcpAction({
+            actorId: 'agent-1', taskId: 'task-1', server: 'custom', tool: 'execute', args: {},
+        });
+        expect(action.sideEffect).toBe('external-write');
+        expect(action.blastRadius).toBe('unknown');
+    });
+    it('detects receipt tampering', async () => {
+        const cwd = await repository();
+        const root = await controlRoot();
+        const action = normalizeMcpAction({
+            actorId: 'agent-1', taskId: 'task-1', server: 'github', tool: 'get_issue', args: {},
+        });
+        await appendExecutionReceipt(cwd, {
+            action, mode: 'observe', decision: 'allow', simulatedDecision: 'deny',
+            reason: 'Observed', policyHash: 'policy', outcome: 'forwarded',
+        }, root);
+        expect(await verifyExecutionReceiptChain(cwd, root)).toMatchObject({ valid: true, count: 1 });
+        const log = path.join(getTrustedControlDir(cwd, root), 'receipts.jsonl');
+        const receipt = JSON.parse((await fs.readFile(log, 'utf8')).trim());
+        receipt.reason = 'tampered';
+        await fs.writeFile(log, `${JSON.stringify(receipt)}\n`);
+        expect((await verifyExecutionReceiptChain(cwd, root)).valid).toBe(false);
+    });
+    it('serializes concurrent receipt appends into one valid chain', async () => {
+        const cwd = await repository();
+        const root = await controlRoot();
+        const action = normalizeMcpAction({
+            actorId: 'agent-1', taskId: 'task-1', server: 'github', tool: 'get_issue', args: {},
+        });
+        await Promise.all(Array.from({ length: 8 }, () => appendExecutionReceipt(cwd, {
+            action, mode: 'observe', decision: 'allow', reason: 'Concurrent call',
+            policyHash: 'policy', outcome: 'forwarded',
+        }, root)));
+        expect(await verifyExecutionReceiptChain(cwd, root)).toMatchObject({ valid: true, count: 8 });
+    });
+    it('keeps the trusted receipt when the Studio projection is blocked', async () => {
+        const cwd = await repository();
+        const root = await controlRoot();
+        await fs.writeFile(path.join(cwd, '.rigour'), 'sandbox blocks this projection');
+        const action = normalizeMcpAction({
+            actorId: 'agent-1', taskId: 'task-1', server: 'github', tool: 'get_issue', args: {},
+        });
+        await expect(appendExecutionReceipt(cwd, {
+            action, mode: 'observe', decision: 'allow', reason: 'Projection optional',
+            policyHash: 'policy', outcome: 'forwarded',
+        }, root)).resolves.toMatchObject({ outcome: 'forwarded' });
+        expect(await verifyExecutionReceiptChain(cwd, root)).toMatchObject({ valid: true, count: 1 });
+    });
+});

package/dist/firewall/types.d.ts

@@ -14,6 +14,9 @@ export interface CapabilityGrant {
     taskId?: string;
     policyHash: string;
     used: boolean;
+    issuerId?: string;
+    subjectId?: string;
+    parentCapabilityId?: string;
 }
 export interface PolicyEvaluation {
     decision: FirewallDecision;
@@ -22,6 +25,38 @@ export interface PolicyEvaluation {
     capabilityId?: string;
     policyHash: string;
     timestamp: string;
+    simulatedDecision?: Exclude<FirewallDecision, 'allow'>;
+}
+export type EnforcementMode = 'observe' | 'enforce';
+export interface AgentAction {
+    version: 1;
+    actorId: string;
+    taskId: string;
+    channel: 'mcp' | 'shell';
+    operation: string;
+    resource: string;
+    environment: 'local' | 'development' | 'staging' | 'production' | 'unknown';
+    sideEffect: 'read' | 'local-write' | 'external-write' | 'destructive';
+    reversibility: 'high' | 'medium' | 'low' | 'unknown';
+    sensitivity: 'normal' | 'sensitive' | 'restricted';
+    blastRadius: 'single-resource' | 'bounded' | 'broad' | 'unknown';
+}
+export interface ExecutionReceipt {
+    version: 1;
+    id: string;
+    repositoryId: string;
+    action: AgentAction;
+    mode: EnforcementMode;
+    decision: FirewallDecision;
+    simulatedDecision?: Exclude<FirewallDecision, 'allow'>;
+    reason: string;
+    capabilityId?: string;
+    policyHash: string;
+    outcome: 'forwarded' | 'denied' | 'failed';
+    createdAt: string;
+    previousReceipt?: string;
+    digest: string;
+    signature: string;
 }
 export interface TypedCommand {
     bin: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rigour-labs/core",
-  "version": "6.1.0",
+  "version": "6.2.0",
   "description": "AI-native quality gate engine with local Bayesian learning. AST analysis, drift detection, Fix Packet generation, and agent self-healing across TypeScript, JavaScript, Python, Go, Ruby, and C#.",
   "license": "MIT",
   "homepage": "https://rigour.run",
@@ -67,11 +67,11 @@
     "pg": "^8.16.3",
     "sqlite3": "^5.1.7",
     "openai": "^4.104.0",
-    "@rigour-labs/brain-darwin-arm64": "6.1.0",
-    "@rigour-labs/brain-darwin-x64": "6.1.0",
-    "@rigour-labs/brain-linux-x64": "6.1.0",
-    "@rigour-labs/brain-win-x64": "6.1.0",
-    "@rigour-labs/brain-linux-arm64": "6.1.0"
+    "@rigour-labs/brain-darwin-arm64": "6.2.0",
+    "@rigour-labs/brain-linux-arm64": "6.2.0",
+    "@rigour-labs/brain-darwin-x64": "6.2.0",
+    "@rigour-labs/brain-win-x64": "6.2.0",
+    "@rigour-labs/brain-linux-x64": "6.2.0"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",