@shieldaai/agent-guard-scenarios 0.1.0-alpha.1 → 0.1.0-alpha.2

package/README.md

@@ -11,11 +11,15 @@ console.table(report.results);
 console.log(scenarioCatalog);
 ```
 
-Run selected scenarios with `runConformance({ scenarioIds: ['S05', 'S08'] })`. The default suite executes malicious and benign variants of all ten scenarios. It checks handler invocations and synthetic effects, not merely decision objects. The built-in fixtures use no credentials, model calls, network services or destructive operations. A custom adapter is responsible for its own I/O.
+Run selected scenarios with `runConformance({ scenarioIds: ['S05', 'S08'] })`. The default suite executes malicious and benign variants of all twelve scenarios. It checks handler invocations and synthetic effects, not merely decision objects. The built-in fixtures use no credentials, model calls, network services or destructive operations. A custom adapter is responsible for its own I/O.
 
-The scenarios cover unauthorized tools/resources, delegation, protected administration, sensitive export, action-bound approval, metadata drift, outbound secrets/canaries, revocation/control failures, tenants and budgets. The [scenario specification](https://github.com/ShieldaAI/agent-guard/blob/main/docs/scenarios.md) explains each boundary.
+The scenarios cover unauthorized tools/resources, delegation, protected administration, sensitive export, action-bound approval, metadata drift, outbound secrets/canaries, revocation/control failures, tenants, budgets, normalized typed arguments and resource-version checks. The [scenario specification](https://github.com/ShieldaAI/agent-guard/blob/main/docs/scenarios.md) explains each boundary.
 
-The catalog version identifies the executed acceptance checks independently of the package version; compare reports using their `catalogVersion`. Version `1.1.0` strengthens the existing S08 race assertions and S10 charging checks and adds the per-variant timeout. It retains ten scenario identifiers and twenty paired cases. A pass from an older catalog does not establish coverage of newly added assertions.
+The catalog version identifies the executed acceptance checks independently of the package version; compare reports using their `catalogVersion`. Version `1.2.0` retains S01–S10 and adds S11 and S12, for twelve scenario identifiers and twenty-four paired cases. A pass from an older catalog does not establish coverage of newly added assertions.
+
+S11 checks that the trusted `ToolDefinition.parse` rejects wrong types, unknown or missing fields, invalid ranges and invalid or asynchronous parser results before resource resolution. The benign case verifies that normalized arguments reach resolution, both policy evaluations, approval and execution; later mutations of caller or parser-owned objects cannot change the approved effect. The core does not interpret `inputSchema` automatically: the host must supply a suitable synchronous parser.
+
+S12 binds the resolver's `resourceVersion` to the immutable prepared action and approval. A synthetic trusted handler compares the approved version with current state immediately before its write. Version forgery and approval transfer must fail before dispatch; a genuine stale version enters the handler, consumes its attempt and produces no write. The benign pair approves and writes two successive versions separately. Real services must implement the comparison atomically with their side effect. This scenario does not claim the core locks or refreshes external resources.
 
 To exercise a compatible implementation, supply `createGuard(options)` in the options object. The factory must honor the provided clock and secret configuration and return the structural `GuardLike` API. Denials use the exported `GuardError` and its documented reason codes. Each fixture receives an isolated instance; no shared factory state is required.
 

package/dist/catalog.d.ts

@@ -1,6 +1,6 @@
 /** Version of the synthetic acceptance cases, independent of package releases. */
-export declare const SCENARIO_CATALOG_VERSION: '1.1.0';
-export type ScenarioId = 'S01' | 'S02' | 'S03' | 'S04' | 'S05' | 'S06' | 'S07' | 'S08' | 'S09' | 'S10';
+export declare const SCENARIO_CATALOG_VERSION: '1.2.0';
+export type ScenarioId = 'S01' | 'S02' | 'S03' | 'S04' | 'S05' | 'S06' | 'S07' | 'S08' | 'S09' | 'S10' | 'S11' | 'S12';
 export interface ScenarioDefinition {
     readonly id: ScenarioId;
     readonly title: string;

package/dist/catalog.js

@@ -1,5 +1,5 @@
 /** Version of the synthetic acceptance cases, independent of package releases. */
-export const SCENARIO_CATALOG_VERSION = '1.1.0';
+export const SCENARIO_CATALOG_VERSION = '1.2.0';
 const definitions = [
     {
         id: 'S01', title: 'Deny unknown tools and unauthorized resources',
@@ -71,6 +71,20 @@ const definitions = [
         benign: 'Authorized work releases concurrency, reconciles cost and cooperates with cancellation.',
         limitations: ['Quotas are local and nondurable; the provider must enforce declared upper costs and handlers must honor cancellation.'],
     },
+    {
+        id: 'S11', title: 'Validate and bind normalized typed arguments',
+        boundary: 'A trusted synchronous parser runs before resolution; its immutable normalized output reaches policy, approval and the handler.',
+        malicious: ['Wrong field types', 'Unknown fields', 'Missing required fields', 'Out-of-range values', 'Invalid parser output', 'Asynchronous parser'],
+        benign: 'One approved write uses the normalized arguments even after caller and parser-owned objects change.',
+        limitations: ['The host supplies the parser; descriptive inputSchema metadata alone does not validate core arguments.'],
+    },
+    {
+        id: 'S12', title: 'Bind approvals to resource versions and compare at use time',
+        boundary: 'The immutable action includes the resolved version; a trusted handler atomically compares it before applying the effect.',
+        malicious: ['Forged prepared resource version', 'Approval transferred to a new version', 'Resource changed after approval', 'Replay of a stale admitted attempt'],
+        benign: 'An unchanged approved version is written once; a subsequent version requires a fresh preparation and approval.',
+        limitations: ['The core does not fetch or lock external state. A stale attempt enters the handler, which must enforce the comparison atomically with the real effect.'],
+    },
 ];
 /** Read-only scenario descriptions. Call runConformance() to run the fixtures. */
 export const scenarioCatalog = Object.freeze(definitions.map((entry) => Object.freeze({

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export type { ScenarioDefinition, ScenarioId } from './catalog.js';
 export type GuardLike = Pick<AgentGuard, 'registerTool' | 'approveTool' | 'createTask' | 'delegateTask' | 'revokeTask' | 'setPolicy' | 'prepare' | 'approve' | 'execute' | 'snapshot'>;
 export type ConformanceGuardFactory = (options: GuardOptions) => GuardLike;
 export interface ConformanceOptions {
-    /** Omit to execute all ten scenarios. Each selected scenario runs both variants. */
+    /** Omit to execute all twelve scenarios. Each selected scenario runs both variants. */
     readonly scenarioIds?: readonly ScenarioId[];
     /** Time limit per variant in milliseconds; defaults to 5000. Timeout does not cancel adapter work. */
     readonly caseTimeoutMs?: number;

package/dist/index.js

@@ -560,6 +560,135 @@ const cases = {
             c.assert(failed.guard.snapshot(failedTask).spent === 6 && failed.guard.snapshot(failedTask).concurrent === 0, 'recovery retains both admitted charges and releases concurrency');
         },
     },
+    S11: {
+        async malicious(c) {
+            const f = fixture(c);
+            let resolutions = 0;
+            f.register({ name: 'typed_write', description: 'Write a typed synthetic record',
+                parse(input) {
+                    const value = fields(input);
+                    if (Object.keys(value).some(key => !['resource', 'quantity'].includes(key)) ||
+                        typeof value.resource !== 'string' || !value.resource.trim() ||
+                        typeof value.quantity !== 'number' || !Number.isSafeInteger(value.quantity) || value.quantity < 1 || value.quantity > 10) {
+                        throw new Error(SECRET);
+                    }
+                    return { resource: value.resource.trim(), quantity: value.quantity };
+                },
+                resolve(args) { resolutions++; return { resourceId: stringField(args, 'resource'), tenantId: 'alpha' }; },
+                execute: args => c.effect(args),
+            });
+            const task = f.task([{ tool: 'typed_write', resources: [RECORD_A] }]);
+            for (const args of [
+                { resource: RECORD_A, quantity: '1' }, { resource: RECORD_A, quantity: 1, command: 'unexpected' },
+                { quantity: 1 }, { resource: RECORD_A, quantity: 0 }, { resource: RECORD_A, quantity: 1.5 },
+            ])
+                await c.denied(() => f.invoke(task, 'typed_write', args), 'invalid typed arguments', 'ARGUMENT_INVALID');
+            c.assert(resolutions === 0, 'invalid typed arguments never reach resource resolution');
+            for (const parse of [() => ({ unsafe: undefined }), () => Promise.resolve(null)]) {
+                f.register({ name: 'invalid_parser', description: 'Invalid trusted parser fixture', parse,
+                    resolve: () => { resolutions++; return { resourceId: RECORD_A, tenantId: 'alpha' }; }, execute: args => c.effect(args) });
+                const parserTask = f.task([{ tool: 'invalid_parser', resources: [RECORD_A] }]);
+                await c.denied(() => f.invoke(parserTask, 'invalid_parser', null), 'invalid parser result', 'ARGUMENT_INVALID');
+            }
+            c.assert(resolutions === 0 && c.handlerInvocations === 0, 'parser failures prevent resolution and effects');
+        },
+        async benign(c) {
+            const observed = [];
+            const f = fixture(c, { policy: action => { observed.push(action.args); return 'allow'; } });
+            let parses = 0;
+            let normalized;
+            f.register({ name: 'typed_write', description: 'Write a normalized synthetic record', requiresApproval: true,
+                parse(input) {
+                    parses++;
+                    const value = fields(input);
+                    if (typeof value.resource !== 'string' || !Number.isSafeInteger(value.quantity))
+                        throw new Error('invalid fixture');
+                    normalized = { resource: value.resource.trim(), quantity: Number(value.quantity) };
+                    return normalized;
+                },
+                resolve(args) { return { resourceId: stringField(args, 'resource'), tenantId: 'alpha' }; },
+                execute(args, { action }) {
+                    c.assert(args === action.args && Object.isFrozen(args), 'handler receives the immutable approved arguments');
+                    f.ledger.push(`${action.resourceId}:${fields(args).quantity}`);
+                    return c.effect(args);
+                },
+            });
+            const task = f.task([{ tool: 'typed_write', resources: [RECORD_A] }]);
+            const input = { resource: ` ${RECORD_A} `, quantity: 3 };
+            const prepared = await f.guard.prepare(task, { tool: 'typed_write', args: input });
+            c.assert(prepared.action.resourceId === RECORD_A && fields(prepared.action.args).resource === RECORD_A, 'normalized resource is resolved and bound');
+            const approvalId = f.approve(prepared);
+            input.resource = RECORD_B;
+            input.quantity = 9;
+            normalized.resource = RECORD_B;
+            normalized.quantity = 8;
+            const value = await f.guard.execute(prepared, { approvalId });
+            c.assert(fields(value).resource === RECORD_A && fields(value).quantity === 3, 'caller and parser mutations do not alter the approved write');
+            c.assert(observed.length === 2 && observed.every(args => fields(args).resource === RECORD_A && fields(args).quantity === 3), 'preparation and execution policy see normalized arguments');
+            c.assert(parses === 1 && c.handlerInvocations === 1 && f.ledger[0] === `${RECORD_A}:3`, 'one parser pass and one normalized approved effect');
+        },
+    },
+    S12: {
+        async malicious(c) {
+            const f = fixture(c);
+            let version = 'v1';
+            f.register({ name: 'versioned_write', description: 'Compare and write one synthetic record', requiresApproval: true,
+                resolve: () => ({ resourceId: RECORD_A, tenantId: 'alpha', resourceVersion: version }),
+                execute(_args, { action }) {
+                    c.handlerInvocations++;
+                    if (action.resourceVersion !== version)
+                        throw new Error('synthetic version conflict');
+                    f.ledger.push(`write:${version}`);
+                    return { value: version };
+                },
+            });
+            const task = f.task([{ tool: 'versioned_write', resources: [RECORD_A] }]);
+            const old = await f.guard.prepare(task, { tool: 'versioned_write', args: null });
+            const approvalId = f.approve(old);
+            c.assert(old.action.resourceVersion === 'v1' && Object.isFrozen(old.action), 'resolved version is immutable approved action data');
+            await c.denied(() => f.guard.execute({ ...old, action: { ...old.action, resourceVersion: 'v2' } }, { approvalId }), 'forged resource version', 'INVALID_PREPARED');
+            version = 'v2';
+            const fresh = await f.guard.prepare(task, { tool: 'versioned_write', args: null });
+            c.assert(fresh.action.resourceVersion === 'v2' && fresh.digest !== old.digest, 'new resource version receives a distinct prepared invocation');
+            await c.denied(() => f.guard.execute(fresh, { approvalId }), 'approval transfer to new version', 'APPROVAL_INVALID');
+            let error;
+            try {
+                await f.guard.execute(old, { approvalId });
+            }
+            catch (caught) {
+                error = caught;
+            }
+            c.assert(error instanceof GuardError && error.code === 'TOOL_FAILED', 'stale resource compare fails with a sanitized handler error');
+            c.denialCodes.push('TOOL_FAILED');
+            c.assert(c.handlerInvocations === 1 && f.ledger.length === 0, 'stale attempt enters the handler but produces no effect');
+            await c.denied(() => f.guard.execute(old, { approvalId }), 'stale attempt cannot replay', 'ACTION_USED');
+            c.assert(f.guard.snapshot(task).calls === 1, 'stale admitted attempt still consumes one call');
+        },
+        async benign(c) {
+            const f = fixture(c);
+            let version = 'v1';
+            f.register({ name: 'versioned_write', description: 'Compare and write one synthetic record', requiresApproval: true,
+                resolve: () => ({ resourceId: RECORD_A, tenantId: 'alpha', resourceVersion: version }),
+                execute(_args, { action }) {
+                    c.handlerInvocations++;
+                    if (action.resourceVersion !== version)
+                        throw new Error('synthetic version conflict');
+                    f.ledger.push(`write:${version}`);
+                    version = version === 'v1' ? 'v2' : 'v3';
+                    return { value: { version } };
+                },
+            });
+            const task = f.task([{ tool: 'versioned_write', resources: [RECORD_A] }]);
+            for (const expected of ['v1', 'v2']) {
+                const prepared = await f.guard.prepare(task, { tool: 'versioned_write', args: null });
+                c.assert(prepared.action.resourceVersion === expected, 'preparation binds the current resource version');
+                const approvalId = f.approve(prepared);
+                await f.guard.execute(prepared, { approvalId });
+            }
+            c.assert(c.handlerInvocations === 2 && f.ledger.join(',') === 'write:v1,write:v2', 'each reviewed version produces exactly one intended effect');
+            c.assert(version === 'v3' && f.guard.snapshot(task).calls === 2, 'two independent approvals advance the synthetic resource twice');
+        },
+    },
 };
 /**
  * Run the catalog fixtures against AgentGuard or the supplied adapter.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shieldaai/agent-guard-scenarios",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.2",
   "description": "Executable protective scenarios and conformance fixtures for agent tool executors.",
   "license": "Apache-2.0",
   "type": "module",
@@ -47,6 +47,6 @@
     "prepublishOnly": "node ../../scripts/release-check.mjs"
   },
   "dependencies": {
-    "@shieldaai/agent-guard": "0.1.0-alpha.1"
+    "@shieldaai/agent-guard": "0.1.0-alpha.2"
   }
 }