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

package/README.md

@@ -11,12 +11,20 @@ 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. Fixtures do not use real credentials, models, network services or destructive operations.
+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.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.
 
+Each malicious or benign variant has a five-second asynchronous timeout. Override it with `caseTimeoutMs`, a positive integer up to `2147483647`. A timed-out variant receives a failed result and the runner continues with the next variant. The timer cannot interrupt blocking JavaScript or cancel unfinished adapter work; an adapter may retain resources or continue running after its result is reported. Use process isolation if the implementation under test needs a hard execution limit.
+
 A passing report applies to these fixtures in one process. It is not a security certification, injection-detector benchmark, MCP transport test or proof that a production agent cannot bypass its integration. Errors after actual handler invocation are tested separately from denials that must prevent invocation.
 
 Apache-2.0. Copyright 2026 ShieldaAI contributors.

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.0.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;
@@ -9,5 +9,5 @@ export interface ScenarioDefinition {
     readonly benign: string;
     readonly limitations: readonly string[];
 }
-/** Immutable descriptive catalog. Execution is opt-in through runConformance(). */
+/** Read-only scenario descriptions. Call runConformance() to run the fixtures. */
 export declare const scenarioCatalog: readonly ScenarioDefinition[];

package/dist/catalog.js

@@ -1,5 +1,5 @@
 /** Version of the synthetic acceptance cases, independent of package releases. */
-export const SCENARIO_CATALOG_VERSION = '1.0.0';
+export const SCENARIO_CATALOG_VERSION = '1.2.0';
 const definitions = [
     {
         id: 'S01', title: 'Deny unknown tools and unauthorized resources',
@@ -71,8 +71,22 @@ 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.'],
+    },
 ];
-/** Immutable descriptive catalog. Execution is opt-in through runConformance(). */
+/** Read-only scenario descriptions. Call runConformance() to run the fixtures. */
 export const scenarioCatalog = Object.freeze(definitions.map((entry) => Object.freeze({
     ...entry,
     malicious: Object.freeze([...entry.malicious]),

package/dist/index.d.ts

@@ -2,14 +2,16 @@ import { AgentGuard, type GuardOptions } from '@shieldaai/agent-guard';
 import { SCENARIO_CATALOG_VERSION, type ScenarioId } from './catalog.js';
 export { SCENARIO_CATALOG_VERSION, scenarioCatalog } from './catalog.js';
 export type { ScenarioDefinition, ScenarioId } from './catalog.js';
-/** Structural surface required from a compatible guard adapter. */
+/** Methods an adapter must provide to run the conformance suite. */
 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;
     /**
-     * Supply a fresh isolated guard per call; defaults to the public AgentGuard implementation.
+     * Return a new guard for each call. Defaults to the public AgentGuard implementation.
      * Compatible adapters must preserve these APIs and throw this core package's GuardError
      * with the documented reason codes. The provided clock and secret configuration must be honored.
      */
@@ -35,8 +37,8 @@ export interface ConformanceReport {
     readonly results: readonly ConformanceCaseResult[];
 }
 /**
- * Run synthetic effects against this installation's public core API.
- * This validates the listed local fixtures, not a deployment, transport, or universal injection defense.
- * No network, credentials, filesystem writes, model calls, or external effects are used.
+ * Run the catalog fixtures against AgentGuard or the supplied adapter.
+ * The default implementation uses in-memory effects only. A custom adapter is
+ * responsible for its own I/O; the runner cannot isolate or cancel it.
  */
 export declare function runConformance(options?: ConformanceOptions): Promise<ConformanceReport>;

package/dist/index.js

@@ -28,11 +28,11 @@ function deferred() {
     const promise = new Promise((done) => { resolve = done; });
     return { promise, resolve };
 }
-async function bounded(promise, label) {
+async function bounded(promise, label, timeoutMs = 1500) {
     let timer;
     try {
         return await Promise.race([promise, new Promise((_, reject) => {
-                timer = setTimeout(() => reject(new CheckFailure(label)), 1500);
+                timer = setTimeout(() => reject(new CheckFailure(label)), timeoutMs);
             })]);
     }
     finally {
@@ -341,20 +341,23 @@ const cases = {
                 const prepared = await f.guard.prepare(task, { tool: 'delete_record', args: { resource: RECORD_A } });
                 const approvalId = f.approve(prepared);
                 wait = true;
-                const pending = f.guard.execute(prepared, { approvalId });
-                // Observe early settlement immediately, including when testing a broken implementation.
-                const observed = pending.then(() => undefined, () => undefined);
-                try {
-                    await bounded(Promise.race([entered.promise, observed.then(() => { throw new CheckFailure('execution settled before policy barrier'); })]), 'policy barrier not reached');
-                    if (change === 'revoke')
-                        f.guard.revokeTask(task);
-                    else
-                        f.guard.setPolicy(() => 'allow');
-                }
-                finally {
-                    release.resolve();
-                }
-                await c.denied(() => pending, `${change} during asynchronous policy`, change === 'revoke' ? 'TASK_REVOKED' : 'POLICY_CHANGED');
+                await c.denied(async () => {
+                    const pending = f.guard.execute(prepared, { approvalId });
+                    // Observe early settlement immediately, including when testing a broken implementation.
+                    const observed = pending.then(() => undefined, () => undefined);
+                    try {
+                        await bounded(Promise.race([entered.promise, observed.then(() => { throw new CheckFailure('execution settled before policy barrier'); })]), 'policy barrier not reached');
+                        if (change === 'revoke')
+                            f.guard.revokeTask(task);
+                        else
+                            f.guard.setPolicy(() => 'allow');
+                    }
+                    finally {
+                        release.resolve();
+                    }
+                    return pending;
+                }, `${change} during asynchronous policy`, change === 'revoke' ? 'TASK_REVOKED' : 'POLICY_CHANGED');
+                c.assert(f.ledger.length === 0, `${change} during asynchronous policy leaves the ledger empty`);
             }
             const f = fixture(c);
             f.remove();
@@ -485,6 +488,13 @@ const cases = {
             await f.invoke(task, 'read_document', { resource: GUIDE });
             const snapshot = f.guard.snapshot(task);
             c.assert(snapshot.calls === 2 && snapshot.concurrent === 0 && snapshot.spent === 2 && snapshot.reserved === 0, 'completed work reconciles usage and releases slots');
+            const omitted = fixture(c);
+            omitted.read({ maxCost: 3 });
+            const omittedTask = omitted.task(readGrant(), { budget: omitted.budget({ maxCost: 6 }) });
+            await omitted.invoke(omittedTask, 'read_document', { resource: GUIDE });
+            await omitted.invoke(omittedTask, 'read_document', { resource: GUIDE });
+            const omittedSnapshot = omitted.guard.snapshot(omittedTask);
+            c.assert(omittedSnapshot.calls === 2 && omittedSnapshot.spent === 6 && omittedSnapshot.reserved === 0 && omittedSnapshot.concurrent === 0, 'omitted actual cost charges the full declared maximum');
             const cancel = fixture(c);
             const entered = deferred();
             let observed = false;
@@ -532,11 +542,11 @@ const cases = {
             c.assert(deadlineObserved && deadline.guard.snapshot(deadlineTask).concurrent === 0, 'deadline signals cooperative cancellation and releases slot');
             const failed = fixture(c);
             let first = true;
-            failed.read({ execute: () => { c.handlerInvocations += 1; if (first) {
+            failed.read({ maxCost: 3, execute: () => { c.handlerInvocations += 1; if (first) {
                     first = false;
                     throw new Error('synthetic failure');
                 } return { value: 'recovered' }; } });
-            const failedTask = failed.task(readGrant(), { budget: failed.budget({ maxConcurrent: 1 }) });
+            const failedTask = failed.task(readGrant(), { budget: failed.budget({ maxConcurrent: 1, maxCost: 9 }) });
             let rejected = false;
             try {
                 await failed.invoke(failedTask, 'read_document', { resource: GUIDE });
@@ -545,16 +555,151 @@ const cases = {
                 rejected = true;
             }
             c.assert(rejected && failed.guard.snapshot(failedTask).calls === 1 && failed.guard.snapshot(failedTask).concurrent === 0, 'failed handler counts attempt and releases concurrency');
+            c.assert(failed.guard.snapshot(failedTask).spent === 3 && failed.guard.snapshot(failedTask).reserved === 0, 'failed handler retains the full declared charge');
             c.assert(await failed.invoke(failedTask, 'read_document', { resource: GUIDE }) === 'recovered', 'next authorized call can use released slot');
+            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 synthetic effects against this installation's public core API.
- * This validates the listed local fixtures, not a deployment, transport, or universal injection defense.
- * No network, credentials, filesystem writes, model calls, or external effects are used.
+ * Run the catalog fixtures against AgentGuard or the supplied adapter.
+ * The default implementation uses in-memory effects only. A custom adapter is
+ * responsible for its own I/O; the runner cannot isolate or cancel it.
  */
 export async function runConformance(options = {}) {
+    const caseTimeoutMs = options.caseTimeoutMs === undefined ? 5000 : options.caseTimeoutMs;
+    if (!Number.isSafeInteger(caseTimeoutMs) || caseTimeoutMs < 1 || caseTimeoutMs > 2_147_483_647) {
+        throw new TypeError('caseTimeoutMs must be an integer from 1 through 2147483647');
+    }
     const selected = options.scenarioIds ?? scenarioCatalog.map((scenario) => scenario.id);
     if (selected.length === 0 || new Set(selected).size !== selected.length || selected.some((id) => !Object.hasOwn(cases, id))) {
         throw new TypeError('scenarioIds must be a nonempty list of distinct catalog identifiers');
@@ -565,7 +710,7 @@ export async function runConformance(options = {}) {
             const checks = new Checks(options.createGuard);
             let failure;
             try {
-                await cases[scenarioId][variant](checks);
+                await bounded(cases[scenarioId][variant](checks), 'case exceeded its asynchronous timeout', caseTimeoutMs);
             }
             catch (error) {
                 failure = error instanceof CheckFailure ? error.message

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shieldaai/agent-guard-scenarios",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.2",
   "description": "Executable protective scenarios and conformance fixtures for agent tool executors.",
   "license": "Apache-2.0",
   "type": "module",
@@ -43,9 +43,10 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "prepack": "node ../../scripts/build.mjs",
     "prepublishOnly": "node ../../scripts/release-check.mjs"
   },
   "dependencies": {
-    "@shieldaai/agent-guard": "0.1.0-alpha.0"
+    "@shieldaai/agent-guard": "0.1.0-alpha.2"
   }
 }