@vess-id/vess 0.2.0-alpha.1

package/dist/core/execution-engine.js

@@ -0,0 +1,1291 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExecutionEngine = void 0;
+/**
+ * Execution Control Runtime — the core of agentd.
+ *
+ * All execution control logic lives here:
+ * - Action normalization
+ * - Resource canonicalization
+ * - Policy evaluation (local + org)
+ * - VC acquisition (4-step flow, spec §6.1)
+ * - VP creation + Gateway verification (spec §7.4)
+ * - Execution routing (local vs gateway)
+ * - Offline fallback (spec §7.6)
+ * - Audit logging
+ *
+ * This module is adapter-independent. MCP, IDE plugins, or SDK clients
+ * all call ExecutionEngine.execute() through their respective thin adapters.
+ */
+const ai_identity_1 = require("@vess-id/ai-identity");
+const os_1 = require("os");
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const wallet_1 = require("../wallet/wallet");
+const gateway_client_1 = require("../gateway/gateway-client");
+const resource_canonicalizer_1 = require("../utils/resource-canonicalizer");
+const vc_utils_1 = require("../utils/vc-utils");
+const credential_errors_1 = require("../utils/credential-errors");
+const executor_registry_1 = require("../executor/executor-registry");
+const env_resolver_1 = require("../env/env-resolver");
+/** Policy cache staleness TTL (spec §7.6: 30 minutes) */
+const POLICY_SYNC_TTL_MS = 30 * 60 * 1000;
+/** OOB approval request expiration (seconds) */
+const OOB_APPROVAL_EXPIRES_IN_SECONDS = 300;
+/** Default TTL for OOB-approved credentials (10 minutes) */
+const OOB_CREDENTIAL_DEFAULT_TTL_MS = 10 * 60 * 1000;
+class ExecutionEngine {
+    policyEvaluator;
+    wallet;
+    vpBuilder;
+    auditLogger;
+    gatewayClient;
+    context;
+    tokenService;
+    secretBackend;
+    lastPolicySyncTime = null;
+    clientInfo;
+    agentRegistered = false;
+    recentOOBRequests = new Map();
+    static OOB_COOLDOWN_MS = 60_000;
+    static OOB_MAP_MAX_SIZE = 1000;
+    constructor(policyEvaluator, wallet, vpBuilder, auditLogger, gatewayClient, context, tokenService, secretBackend) {
+        this.policyEvaluator = policyEvaluator;
+        this.wallet = wallet;
+        this.vpBuilder = vpBuilder;
+        this.auditLogger = auditLogger;
+        this.gatewayClient = gatewayClient;
+        this.context = context;
+        this.tokenService = tokenService;
+        this.secretBackend = secretBackend;
+    }
+    /**
+     * Record a successful policy sync timestamp (called by SyncScheduler).
+     */
+    setLastPolicySyncTime(time) {
+        this.lastPolicySyncTime = time;
+    }
+    /**
+     * Set MCP client info (from oninitialized callback).
+     * Used to derive a meaningful agent name for deferred registration.
+     */
+    setClientInfo(info) {
+        this.clientInfo = info;
+    }
+    /**
+     * Ensure the agent is registered in the API.
+     * Called lazily on first tool execution (fire-and-forget).
+     * Uses clientInfo from MCP initialize handshake if available.
+     */
+    ensureAgentRegistered() {
+        if (this.agentRegistered)
+            return;
+        this.agentRegistered = true;
+        const publicKey = this.context.agentPublicKey;
+        if (!publicKey || !this.context.projectId)
+            return;
+        const agentName = this.clientInfo
+            ? `${this.clientInfo.name}-agent`
+            : 'vess-agentd';
+        this.gatewayClient.registerAgent({
+            agentDid: this.context.agentDid,
+            name: agentName,
+            type: 'assistant',
+            publicKey,
+            projectId: this.context.projectId,
+            deviceInfo: {
+                platform: process.platform,
+                hostname: (0, os_1.hostname)(),
+                runtime: this.clientInfo?.name || 'unknown',
+            },
+        }).catch((err) => {
+            process.stderr.write(`[vess] Agent registration failed (non-fatal): ${err instanceof Error ? err.message : String(err)}\n`);
+        });
+    }
+    /**
+     * Execute an action request.
+     * This is the single entry point for all adapters (MCP, future IDE, SDK).
+     */
+    async execute(request) {
+        // Deferred agent registration: fire-and-forget on first tool execution
+        this.ensureAgentRegistered();
+        // Mutual exclusion: pendingRequestId and approval are incompatible
+        if (request.pendingRequestId && request.approval) {
+            return { success: false, error: 'Cannot provide both pendingRequestId and approval in the same request' };
+        }
+        const { action, input } = request;
+        // 1. Extract provider from action (e.g., 'os' from 'os.secret.read')
+        const provider = action.split('.')[0];
+        // 2. Resource canonicalization
+        const requestedResource = input.file_path || (action === 'os.process.run' ? input.command?.join(' ') : undefined);
+        let normalizedResource;
+        let resourceFingerprint;
+        if ((0, executor_registry_1.isLocalAction)(action) && input.file_path) {
+            normalizedResource = (0, resource_canonicalizer_1.canonicalizePath)(input.file_path);
+            resourceFingerprint = (0, resource_canonicalizer_1.computeFingerprint)(normalizedResource, this.context.rootDid);
+        }
+        // 3. Policy evaluation (local + org deny check)
+        const policyResult = this.policyEvaluator.evaluate(provider, action.replace(`${provider}.`, ''), {
+            type: this.getResourceType(action),
+            pattern: normalizedResource || input.file_path,
+        });
+        if (!policyResult.allowed) {
+            this.logAudit({
+                action, provider,
+                decision: 'deny',
+                enforcementType: 'local',
+                decisionSource: 'local_policy',
+                decisionReason: policyResult.reason,
+                requestedResource,
+                normalizedResource,
+                resourceFingerprint,
+                executionType: (0, executor_registry_1.isLocalAction)(action) ? 'local' : 'gateway',
+            });
+            return { success: false, error: `Action denied by policy: ${policyResult.reason}` };
+        }
+        // Handle OOB approval polling (pendingRequestId)
+        if (request.pendingRequestId) {
+            return this.handlePendingApproval(request);
+        }
+        // Handle 2nd call with approval decision
+        if (request.approval) {
+            // Security guard: block in-band approval for high/critical risk actions
+            const riskLevel = this.getActionRiskLevel(request.action);
+            if (riskLevel === 'high' || riskLevel === 'critical') {
+                return {
+                    success: false,
+                    error: `High-risk action "${request.action}" requires browser approval (Out-of-Band). In-band approval tokens are not accepted.`,
+                };
+            }
+            return this.handleApprovalResponse(request, provider, normalizedResource, resourceFingerprint, requestedResource);
+        }
+        // 4. Determine execution routing
+        const routing = (0, executor_registry_1.determineRouting)(provider, action);
+        // 5. Execute based on routing
+        if (routing.executor === 'local') {
+            return this.executeLocal(action, input, provider, normalizedResource, resourceFingerprint, requestedResource);
+        }
+        else {
+            return this.executeViaGateway(provider, action, input);
+        }
+    }
+    // ===========================================================================
+    // 4-step VC acquisition (spec §6.1)
+    // ===========================================================================
+    /**
+     * Ensure a valid VC exists for the requested action.
+     * Follows the 4-step acquisition flow from spec §6.1:
+     *
+     * Step 1: Check wallet for valid VC (verify revocation via Gateway using VC jti)
+     * Step 2: Check Gateway for approved requests
+     * Step 3: Try auto-issue via Gateway
+     * Step 4: Terminal approval prompt -> quick-approve via Gateway
+     */
+    async ensureVC(action, provider, resourceInfo, input = {}, canonicalResourceId) {
+        let approvedRequests = null;
+        // Step 1: Check wallet for existing valid VC
+        if (canonicalResourceId) {
+            // Step 1a: Exact resource match
+            const scopedVC = this.wallet.findCredential(this.context.agentDid, action, this.context.projectId, canonicalResourceId);
+            if (scopedVC) {
+                const verified = await this.verifyWalletVC(scopedVC);
+                if (verified)
+                    return { credential: verified, decisionSource: 'cached_vc' };
+            }
+            // Step 1b: Legacy VC without resource scope (Gateway will validate)
+            const unscopedVC = this.wallet.findUnscopedCredential(this.context.agentDid, action, this.context.projectId);
+            if (unscopedVC) {
+                const verified = await this.verifyWalletVC(unscopedVC);
+                if (verified)
+                    return { credential: verified, decisionSource: 'cached_vc' };
+            }
+            // No matching VC — fall through to Step 2-4
+        }
+        else {
+            // No resource context — use original findCredential
+            const walletVC = this.wallet.findCredential(this.context.agentDid, action, this.context.projectId);
+            if (walletVC) {
+                const verified = await this.verifyWalletVC(walletVC);
+                if (verified)
+                    return { credential: verified, decisionSource: 'cached_vc' };
+            }
+        }
+        // Step 2: Check Gateway for approved requests
+        try {
+            approvedRequests = await this.gatewayClient.findApprovedRequests(this.context.agentDid);
+            const matching = approvedRequests.find(r => r.actions?.includes(action) && r.credential);
+            if (matching && matching.credential) {
+                const stored = this.wallet.storeCredential({
+                    holderDid: this.context.agentDid,
+                    projectId: this.context.projectId,
+                    credentialJwt: matching.credential.jwt,
+                    actions: matching.actions,
+                    provider,
+                    expiresAt: matching.credential.expiresAt,
+                    normalizedResourceKey: resourceInfo?.normalizedResource,
+                    resourceFingerprint: resourceInfo?.fingerprint,
+                    resources: (0, wallet_1.validateResources)(matching.resources),
+                });
+                return { credential: stored, decisionSource: 'cached_vc' };
+            }
+        }
+        catch {
+            // Gateway unreachable for step 2 — continue to step 3
+        }
+        // Step 3: Try auto-issue via Gateway
+        try {
+            const autoResult = await this.gatewayClient.autoIssueVC({
+                subjectDid: this.context.agentDid,
+                projectId: this.context.projectId,
+                actions: [action],
+            });
+            if (autoResult?.autoIssued && autoResult.credential) {
+                const stored = this.wallet.storeCredential({
+                    holderDid: this.context.agentDid,
+                    projectId: this.context.projectId,
+                    credentialJwt: autoResult.credential.jwt,
+                    actions: autoResult.actions || [action],
+                    provider,
+                    expiresAt: autoResult.credential.expiresAt,
+                    normalizedResourceKey: resourceInfo?.normalizedResource,
+                    resourceFingerprint: resourceInfo?.fingerprint,
+                    resources: (0, wallet_1.validateResources)(autoResult.resources),
+                    metadata: autoResult.metadata,
+                });
+                return { credential: stored, decisionSource: 'cached_vc' };
+            }
+        }
+        catch {
+            // Gateway unreachable for step 3 — continue to step 4
+        }
+        // Step 4: Risk-based approval routing
+        const riskLevel = this.getActionRiskLevel(action);
+        if (riskLevel === 'high' || riskLevel === 'critical') {
+            try {
+                return await this.createOOBApprovalRequest(action, provider, riskLevel, resourceInfo, input);
+            }
+            catch (err) {
+                return {
+                    denied: true,
+                    reason: `Failed to create out-of-band approval request: ${err instanceof Error ? err.message : String(err)}`,
+                };
+            }
+        }
+        else {
+            return this.createInBandApprovalResponse(action, provider, riskLevel, approvedRequests, resourceInfo, input);
+        }
+    }
+    // ===========================================================================
+    // Local execution with VP verification (spec §7.4)
+    // ===========================================================================
+    async executeLocal(action, params, provider, normalizedResource, resourceFingerprint, requestedResource) {
+        const resourceInfo = normalizedResource && resourceFingerprint
+            ? { normalizedResource, fingerprint: resourceFingerprint }
+            : undefined;
+        // 1. Ensure VC (4-step acquisition)
+        const vcResult = await this.ensureVC(action, provider, resourceInfo, params);
+        if ('approvalRequired' in vcResult) {
+            return { success: false, approvalRequired: vcResult.approvalRequired };
+        }
+        if ('waitingForApproval' in vcResult) {
+            return { success: false, waitingForApproval: vcResult.waitingForApproval };
+        }
+        if ('denied' in vcResult) {
+            this.logAudit({
+                action, provider,
+                decision: 'deny',
+                enforcementType: 'local',
+                decisionSource: 'local_policy',
+                decisionReason: vcResult.reason,
+                requestedResource,
+                normalizedResource,
+                resourceFingerprint,
+                executionType: 'local',
+            });
+            return { success: false, error: `Permission denied: ${vcResult.reason}` };
+        }
+        // 2. Execute with the acquired VC
+        return this.executeLocalWithVC(action, params, provider, vcResult, normalizedResource, resourceFingerprint, requestedResource);
+    }
+    /**
+     * Execute locally with an already-acquired VC (skips ensureVC).
+     * Used by both the normal path (after ensureVC) and handleApprovalResponse (after quickApprove).
+     */
+    async executeLocalWithVC(action, params, provider, vcResult, normalizedResource, resourceFingerprint, requestedResource, retryCount = 0) {
+        const executor = (0, executor_registry_1.getLocalExecutor)(action);
+        if (!executor) {
+            return { success: false, error: `No local executor for action: ${action}` };
+        }
+        // Try Gateway VP verification (online path)
+        let gatewayReachable = true;
+        try {
+            const { nonce } = await this.gatewayClient.issueNonce(this.context.agentDid);
+            const vpJwt = await this.vpBuilder.buildVP({
+                credentialJwt: vcResult.credential.credentialJwt,
+                signerDid: this.context.agentDid,
+                signerPrivateKeyJwk: this.context.agentPrivateKeyJwk,
+                nonce,
+                domain: this.context.gatewayUrl,
+            });
+            const authResult = await this.gatewayClient.verifyAndAuthorize(vpJwt, nonce, this.context.gatewayUrl, action, this.context.agentDid);
+            if (!authResult.authorized) {
+                // Check if the failure is due to credential expiration — attempt reissuance (max 1 retry)
+                if ((0, credential_errors_1.isCredentialInvalidError)(authResult.reason) && retryCount < 1) {
+                    this.wallet.revokeCredential(vcResult.credential.id);
+                    const resourceInfo = normalizedResource && resourceFingerprint
+                        ? { normalizedResource, fingerprint: resourceFingerprint }
+                        : undefined;
+                    const newVCResult = await this.ensureVC(action, provider, resourceInfo, params);
+                    if ('credential' in newVCResult) {
+                        return this.executeLocalWithVC(action, params, provider, newVCResult, normalizedResource, resourceFingerprint, requestedResource, retryCount + 1);
+                    }
+                    // ensureVC returned approval flow — pass through to caller
+                    if ('waitingForApproval' in newVCResult) {
+                        return { success: false, waitingForApproval: newVCResult.waitingForApproval };
+                    }
+                    if ('approvalRequired' in newVCResult) {
+                        return { success: false, approvalRequired: newVCResult.approvalRequired };
+                    }
+                    // ensureVC denied — return denial reason instead of original auth error
+                    if ('denied' in newVCResult) {
+                        return { success: false, error: `VC reissuance denied: ${newVCResult.reason}` };
+                    }
+                }
+                this.logAudit({
+                    action, provider,
+                    decision: 'deny',
+                    enforcementType: 'gateway_verified_local',
+                    decisionSource: vcResult.decisionSource,
+                    decisionReason: authResult.reason,
+                    requestedResource,
+                    normalizedResource,
+                    resourceFingerprint,
+                    executionType: 'local',
+                    grantId: authResult.grantId,
+                });
+                return { success: false, error: `Authorization denied: ${authResult.reason}` };
+            }
+            // Consume one-time grant BEFORE execution
+            const effectiveGrantId = authResult.grantId || vcResult.grantId;
+            if (effectiveGrantId && authResult.approvalMode === 'one_time') {
+                const consumeResult = await this.gatewayClient.consumeGrant(effectiveGrantId);
+                if (!consumeResult.consumed) {
+                    this.logAudit({
+                        action, provider,
+                        decision: 'deny',
+                        enforcementType: 'gateway_verified_local',
+                        decisionSource: vcResult.decisionSource,
+                        decisionReason: `Grant consumption failed: ${consumeResult.reason}`,
+                        requestedResource,
+                        normalizedResource,
+                        resourceFingerprint,
+                        executionType: 'local',
+                        grantId: effectiveGrantId,
+                    });
+                    return { success: false, error: `Grant consumption failed: ${consumeResult.reason}` };
+                }
+            }
+            // Execute locally — build context based on action type
+            let result;
+            if (action === 'os.process.run') {
+                const resolvedEnv = await this.resolveProcessEnv(params);
+                result = executor(params, { resolvedEnv });
+            }
+            else {
+                result = executor(params, {
+                    rootDid: this.context.rootDid,
+                    approvedResource: vcResult.credential.normalizedResourceKey,
+                    approvedFingerprint: vcResult.credential.resourceFingerprint,
+                });
+            }
+            this.logAudit({
+                action, provider,
+                decision: result.success ? 'allow' : 'deny',
+                enforcementType: 'gateway_verified_local',
+                decisionSource: vcResult.decisionSource,
+                requestedResource,
+                normalizedResource,
+                resourceFingerprint: result.resourceFingerprint || resourceFingerprint,
+                executionType: 'local',
+                grantId: effectiveGrantId || authResult.grantId,
+                credentialId: vcResult.credential.id,
+                approvalMode: vcResult.approvalMode,
+                approvalNonce: vcResult.approvalNonce,
+            });
+            return { success: result.success, data: result.data, error: result.error };
+        }
+        catch (err) {
+            if (!(err instanceof gateway_client_1.GatewayNetworkError))
+                throw err;
+            gatewayReachable = false;
+        }
+        if (!gatewayReachable) {
+            return this.executeLocalOffline(action, params, provider, vcResult, normalizedResource, resourceFingerprint, requestedResource);
+        }
+        return { success: false, error: `Unexpected execution state for ${action}` };
+    }
+    // ===========================================================================
+    // Offline fallback (spec §7.6)
+    // ===========================================================================
+    /**
+     * Execute locally when Gateway is unreachable.
+     * All 4 conditions from spec §7.6 must be true:
+     * 1. Valid cached VC exists
+     * 2. VC not expired
+     * 3. Synced org policy not stale (30 min TTL)
+     * 4. Local policy does not deny
+     */
+    async executeLocalOffline(action, params, provider, vcResult, normalizedResource, resourceFingerprint, requestedResource) {
+        // Condition 1: Valid cached VC exists (already guaranteed by ensureVC)
+        if (!vcResult.credential) {
+            return { success: false, error: 'Cannot execute offline: no cached VC' };
+        }
+        // Condition 2: VC not expired
+        if (vcResult.credential.expiresAt && vcResult.credential.expiresAt < Date.now()) {
+            this.logAudit({
+                action, provider,
+                decision: 'deny',
+                enforcementType: 'cached_verified_local',
+                decisionSource: 'cached_vc',
+                decisionReason: 'VC expired during offline execution',
+                requestedResource,
+                normalizedResource,
+                resourceFingerprint,
+                executionType: 'local',
+            });
+            return { success: false, error: 'Cannot execute offline: cached VC expired' };
+        }
+        // Condition 3: Synced org policy not stale (30 min TTL)
+        if (!this.lastPolicySyncTime || (Date.now() - this.lastPolicySyncTime) > POLICY_SYNC_TTL_MS) {
+            this.logAudit({
+                action, provider,
+                decision: 'deny',
+                enforcementType: 'cached_verified_local',
+                decisionSource: 'org_policy',
+                decisionReason: 'Org policy cache is stale or missing for offline execution',
+                requestedResource,
+                normalizedResource,
+                resourceFingerprint,
+                executionType: 'local',
+            });
+            return { success: false, error: 'Cannot execute offline: org policy cache is stale or has never been synced' };
+        }
+        // Condition 4: Local policy does not deny
+        const offlinePolicyCheck = this.policyEvaluator.evaluate(provider, action.replace(`${provider}.`, ''), {
+            type: this.getResourceType(action),
+            pattern: normalizedResource,
+        });
+        if (!offlinePolicyCheck.allowed) {
+            this.logAudit({
+                action, provider,
+                decision: 'deny',
+                enforcementType: 'cached_verified_local',
+                decisionSource: 'local_policy',
+                decisionReason: offlinePolicyCheck.reason,
+                requestedResource,
+                normalizedResource,
+                resourceFingerprint,
+                executionType: 'local',
+            });
+            return { success: false, error: `Cannot execute offline: local policy denies: ${offlinePolicyCheck.reason}` };
+        }
+        // All conditions met — execute with cached_verified_local enforcement
+        const executor = (0, executor_registry_1.getLocalExecutor)(action);
+        if (!executor) {
+            return { success: false, error: `No local executor for action: ${action}` };
+        }
+        let result;
+        if (action === 'os.process.run') {
+            const resolvedEnv = await this.resolveProcessEnv(params);
+            result = executor(params, { resolvedEnv });
+        }
+        else {
+            result = executor(params, {
+                rootDid: this.context.rootDid,
+                approvedResource: vcResult.credential.normalizedResourceKey,
+                approvedFingerprint: vcResult.credential.resourceFingerprint,
+            });
+        }
+        this.logAudit({
+            action, provider,
+            decision: result.success ? 'allow' : 'deny',
+            enforcementType: 'cached_verified_local',
+            decisionSource: 'cached_vc',
+            requestedResource,
+            normalizedResource,
+            resourceFingerprint: result.resourceFingerprint || resourceFingerprint,
+            executionType: 'local',
+            credentialId: vcResult.credential.id,
+        });
+        return { success: result.success, data: result.data, error: result.error };
+    }
+    // ===========================================================================
+    // SaaS execution via Gateway (spec §7.4)
+    // ===========================================================================
+    async executeViaGateway(provider, action, params) {
+        // NEW: Resolve resource identifier to canonical ID
+        const extractedId = this.extractResourceIdFromInput(action, params);
+        let canonicalResourceId = extractedId;
+        if (extractedId) {
+            try {
+                const resolved = await this.gatewayClient.resolveResource({
+                    provider,
+                    resourceType: this.getResourceType(action),
+                    input: extractedId,
+                    projectId: this.context.projectId,
+                });
+                if (resolved.resolved) {
+                    canonicalResourceId = resolved.canonicalId;
+                }
+            }
+            catch {
+                // Resolution failed — continue with original input (best-effort)
+            }
+        }
+        // 1. Ensure VC (4-step acquisition) with resource context
+        const vcResult = await this.ensureVC(action, provider, undefined, params, canonicalResourceId);
+        if ('approvalRequired' in vcResult) {
+            return { success: false, approvalRequired: vcResult.approvalRequired };
+        }
+        if ('waitingForApproval' in vcResult) {
+            return { success: false, waitingForApproval: vcResult.waitingForApproval };
+        }
+        if ('denied' in vcResult) {
+            this.logAudit({
+                action, provider,
+                decision: 'deny',
+                enforcementType: 'gateway',
+                decisionSource: 'local_policy',
+                decisionReason: vcResult.reason,
+                executionType: 'gateway',
+            });
+            return { success: false, error: `Permission denied: ${vcResult.reason}` };
+        }
+        // 2. Execute with the acquired VC
+        return this.executeViaGatewayWithVC(provider, action, params, vcResult, 0, canonicalResourceId);
+    }
+    async executeViaGatewayWithVC(provider, action, params, vcResult, retryCount = 0, canonicalResourceId) {
+        try {
+            const { nonce } = await this.gatewayClient.issueNonce(this.context.agentDid);
+            const vpJwt = await this.vpBuilder.buildVP({
+                credentialJwt: vcResult.credential.credentialJwt,
+                signerDid: this.context.agentDid,
+                signerPrivateKeyJwk: this.context.agentPrivateKeyJwk,
+                nonce,
+                domain: this.context.gatewayUrl,
+            });
+            const result = await this.gatewayClient.invokeTool({
+                action,
+                parameters: params,
+                holderDid: this.context.agentDid,
+                vpJwt,
+                vpChallenge: nonce,
+                vpDomain: this.context.gatewayUrl,
+            });
+            // Detect resource mismatch from structured error code
+            if (!result.success && result.errorCode === 'RESOURCE_MISMATCH') {
+                return this.handleResourceMismatch(action, provider, params, vcResult);
+            }
+            // Detect credential-invalid errors and attempt VC reissuance (max 1 retry)
+            if (!result.success && result.errorCode === 'CREDENTIAL_INVALID' && retryCount < 1) {
+                this.wallet.revokeCredential(vcResult.credential.id);
+                const newVCResult = await this.ensureVC(action, provider, undefined, params, canonicalResourceId);
+                if ('credential' in newVCResult) {
+                    return this.executeViaGatewayWithVC(provider, action, params, newVCResult, retryCount + 1, canonicalResourceId);
+                }
+                // ensureVC returned approval flow — pass through to caller
+                if ('waitingForApproval' in newVCResult) {
+                    return { success: false, waitingForApproval: newVCResult.waitingForApproval };
+                }
+                if ('approvalRequired' in newVCResult) {
+                    return { success: false, approvalRequired: newVCResult.approvalRequired };
+                }
+                // ensureVC denied — return denial reason
+                if ('denied' in newVCResult) {
+                    return { success: false, error: `VC reissuance denied: ${newVCResult.reason}` };
+                }
+                // Could not re-acquire VC — return the original error
+                return { success: false, error: result.error };
+            }
+            this.logAudit({
+                action, provider,
+                decision: result.success ? 'allow' : 'deny',
+                enforcementType: 'gateway',
+                decisionSource: vcResult.decisionSource,
+                decisionReason: result.error,
+                executionType: 'gateway',
+                credentialId: vcResult.credential.id,
+                grantId: vcResult.grantId,
+                approvalMode: vcResult.approvalMode,
+                approvalNonce: vcResult.approvalNonce,
+            });
+            return { success: result.success, data: result.data, error: result.error };
+        }
+        catch (err) {
+            this.logAudit({
+                action, provider,
+                decision: 'deny',
+                enforcementType: 'gateway',
+                decisionSource: 'gateway_execution',
+                decisionReason: `Gateway unreachable: ${err instanceof Error ? err.message : String(err)}`,
+                executionType: 'gateway',
+            });
+            return {
+                success: false,
+                error: `Gateway required for SaaS operations but unreachable: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    }
+    // ===========================================================================
+    // OOB approval methods
+    // ===========================================================================
+    /**
+     * Handle a re-invocation with pendingRequestId (OOB approval polling).
+     */
+    async handlePendingApproval(request) {
+        const { action, pendingRequestId } = request;
+        if (!pendingRequestId) {
+            return { success: false, error: 'No pendingRequestId provided' };
+        }
+        let statusResult;
+        try {
+            statusResult = await this.gatewayClient.getApprovalStatus(pendingRequestId);
+        }
+        catch (err) {
+            return { success: false, error: `Failed to check approval status: ${err instanceof Error ? err.message : String(err)}` };
+        }
+        // Security: verify that the re-invoked action matches what was originally approved
+        if (statusResult.actions && !statusResult.actions.includes(action)) {
+            return {
+                success: false,
+                error: `Action mismatch: approval was for [${statusResult.actions.join(', ')}], but re-invoked with "${action}"`,
+            };
+        }
+        // Security: verify that the re-invoked resource matches what was originally approved
+        if (statusResult.resources?.length) {
+            const extractedId = this.extractResourceIdFromInput(action, request.input);
+            if (extractedId) {
+                // For local actions, the approval stores canonicalized paths — canonicalize the input too
+                const normalizedId = (0, executor_registry_1.isLocalAction)(action) && request.input.file_path
+                    ? (0, resource_canonicalizer_1.canonicalizePath)(request.input.file_path)
+                    : extractedId;
+                const approvedResources = statusResult.resources;
+                const resourceMatch = approvedResources.some((r) => r.id === extractedId || r.id === normalizedId ||
+                    r.pattern === extractedId || r.pattern === normalizedId);
+                if (!resourceMatch) {
+                    return {
+                        success: false,
+                        error: `Resource mismatch: approval was for [${approvedResources.map((r) => r.id || r.pattern).join(', ')}], but re-invoked with "${extractedId}"`,
+                    };
+                }
+            }
+        }
+        if (statusResult.status === 'denied') {
+            const provider = action.split('.')[0];
+            this.logAudit({
+                action, provider,
+                decision: 'deny',
+                enforcementType: 'gateway',
+                decisionSource: 'org_policy',
+                decisionReason: 'User denied the OOB approval request',
+                executionType: (0, executor_registry_1.isLocalAction)(action) ? 'local' : 'gateway',
+            });
+            return { success: false, error: 'Approval request was denied by the user' };
+        }
+        if (statusResult.status === 'expired') {
+            return { success: false, error: 'Approval request has expired. Please try again.' };
+        }
+        if (statusResult.status === 'pending') {
+            return {
+                success: false,
+                waitingForApproval: {
+                    status: 'waiting_for_approval',
+                    approvalUrl: statusResult.approvalUrl || 'Use the URL from your initial request',
+                    requestId: pendingRequestId,
+                    action,
+                    riskLevel: this.getActionRiskLevel(action),
+                    expiresIn: OOB_APPROVAL_EXPIRES_IN_SECONDS,
+                    message: 'Still waiting for approval. Please approve in your browser.',
+                },
+            };
+        }
+        // approved — store credential and execute directly (no wallet round-trip)
+        if (statusResult.status === 'approved' && statusResult.credential) {
+            const provider = action.split('.')[0];
+            const stored = this.wallet.storeCredential({
+                holderDid: this.context.agentDid,
+                projectId: this.context.projectId,
+                credentialJwt: statusResult.credential,
+                actions: [action],
+                provider,
+                expiresAt: statusResult.expiresAt
+                    ? new Date(statusResult.expiresAt).getTime()
+                    : Date.now() + OOB_CREDENTIAL_DEFAULT_TTL_MS,
+                resources: (0, wallet_1.validateResources)(statusResult.resources),
+            });
+            // Build VCAcquired and execute directly (skip re-enter via this.execute)
+            const vcAcquired = {
+                credential: stored,
+                approvalMode: 'one_time',
+                decisionSource: 'new_vc_from_quick_approve',
+            };
+            const routing = (0, executor_registry_1.determineRouting)(provider, action);
+            let executeResult;
+            const normalizedResource = (0, executor_registry_1.isLocalAction)(action) && request.input.file_path
+                ? (0, resource_canonicalizer_1.canonicalizePath)(request.input.file_path)
+                : undefined;
+            const resourceFingerprint = normalizedResource
+                ? (0, resource_canonicalizer_1.computeFingerprint)(normalizedResource, this.context.rootDid)
+                : undefined;
+            try {
+                if (routing.executor === 'local') {
+                    executeResult = await this.executeLocalWithVC(action, request.input, provider, vcAcquired, normalizedResource, resourceFingerprint, request.input.file_path);
+                }
+                else {
+                    executeResult = await this.executeViaGatewayWithVC(provider, action, request.input, vcAcquired);
+                }
+            }
+            finally {
+                // Wallet cleanup for OOB one-time credentials
+                if (stored?.id) {
+                    this.wallet.revokeCredential(stored.id);
+                }
+            }
+            return executeResult;
+        }
+        return { success: false, error: `Unexpected approval status: ${statusResult.status}` };
+    }
+    /**
+     * Create an OOB approval request for high/critical risk actions.
+     * Returns a URL for the user to approve in their browser.
+     */
+    async createOOBApprovalRequest(action, provider, riskLevel, resourceInfo, input) {
+        const resourceType = this.getResourceType(action);
+        const extractedId = this.extractResourceIdFromInput(action, input);
+        const resources = resourceInfo
+            ? [{ provider, type: resourceType, pattern: resourceInfo.normalizedResource }]
+            : extractedId
+                ? [{ provider, type: resourceType, id: extractedId }]
+                : [{ provider, type: resourceType }];
+        try {
+            const result = await this.gatewayClient.createApprovalRequest({
+                subjectDid: this.context.agentDid,
+                projectId: this.context.projectId,
+                actions: [action],
+                resources,
+            });
+            return {
+                waitingForApproval: {
+                    status: 'waiting_for_approval',
+                    approvalUrl: result.approvalUrl,
+                    requestId: result.requestId,
+                    action,
+                    resource: resourceInfo?.normalizedResource ?? extractedId,
+                    riskLevel,
+                    expiresIn: OOB_APPROVAL_EXPIRES_IN_SECONDS,
+                    message: `This ${riskLevel}-risk action requires browser approval (login required). Open the URL to approve.`,
+                },
+            };
+        }
+        catch (err) {
+            throw new Error(`Failed to create OOB approval request: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /**
+     * Create an in-band approval response for low/medium risk actions.
+     * Generates an approval token for the MCP client to present back.
+     */
+    createInBandApprovalResponse(action, _provider, riskLevel, approvedRequests, resourceInfo, input = {}) {
+        const defaultTTL = this.getDefaultVCTTL(riskLevel);
+        // Determine context using cached result from Step 2
+        let approvalContext = 'new_approval';
+        if (approvedRequests && approvedRequests.some(r => r.actions?.includes(action))) {
+            approvalContext = 'reconfirmation';
+        }
+        // Narrow resource: use normalized path for local actions, or extract resource ID for SaaS actions
+        const extractedResource = this.extractResourceIdFromInput(action, input);
+        const tokenResource = resourceInfo?.normalizedResource ?? extractedResource;
+        const approvalToken = this.tokenService.generate({
+            action,
+            scope: action,
+            resource: tokenResource,
+            context: approvalContext,
+        });
+        return {
+            approvalRequired: {
+                status: 'approval_required',
+                action,
+                description: `Execute ${action}`,
+                scope: action,
+                resource: tokenResource,
+                riskLevel,
+                options: ['one_time', 'persistent', 'deny_once', 'deny_persistent'],
+                suggestedTTL: defaultTTL,
+                maxTTL: { minutes: 1440, label: '24 hours' },
+                approvalToken,
+                context: approvalContext,
+            },
+        };
+    }
+    // ===========================================================================
+    // Utility methods
+    // ===========================================================================
+    /**
+     * Pre-request permissions for multiple actions (batch).
+     * Triggers VC acquisition for each action without executing.
+     * This allows the user to approve multiple actions at once.
+     */
+    async requestPermissions(actions) {
+        const approved = [];
+        const denied = [];
+        const pending = [];
+        for (const action of actions) {
+            const provider = action.split('.')[0];
+            // Policy check
+            const policyResult = this.policyEvaluator.evaluate(provider, action.replace(`${provider}.`, ''), { type: this.getResourceType(action) });
+            if (!policyResult.allowed) {
+                denied.push(action);
+                continue;
+            }
+            // Try VC acquisition (steps 1-3 only, no terminal prompt for batch)
+            try {
+                const walletVC = this.wallet.findCredential(this.context.agentDid, action, this.context.projectId);
+                if (walletVC) {
+                    approved.push(action);
+                    continue;
+                }
+                // Try auto-issue
+                const autoResult = await this.gatewayClient.autoIssueVC({
+                    subjectDid: this.context.agentDid,
+                    projectId: this.context.projectId,
+                    actions: [action],
+                });
+                if (autoResult?.autoIssued && autoResult.credential) {
+                    this.wallet.storeCredential({
+                        holderDid: this.context.agentDid,
+                        projectId: this.context.projectId,
+                        credentialJwt: autoResult.credential.jwt,
+                        actions: autoResult.actions || [action],
+                        provider,
+                        expiresAt: autoResult.credential.expiresAt,
+                        resources: (0, wallet_1.validateResources)(autoResult.resources),
+                        metadata: autoResult.metadata,
+                    });
+                    approved.push(action);
+                    continue;
+                }
+                pending.push(action);
+            }
+            catch {
+                pending.push(action);
+            }
+        }
+        const allApproved = denied.length === 0 && pending.length === 0;
+        // Create approval URL for pending actions (matches remote-mcp behavior)
+        if (pending.length > 0) {
+            try {
+                const approvalResult = await this.gatewayClient.createApprovalRequest({
+                    subjectDid: this.context.agentDid,
+                    projectId: this.context.projectId,
+                    actions: pending,
+                });
+                if (!approvalResult.approvalUrl) {
+                    throw new Error('Gateway returned empty approval URL');
+                }
+                return {
+                    success: true,
+                    data: {
+                        approved,
+                        denied,
+                        pending,
+                        requestId: approvalResult.requestId,
+                        approvalUrl: approvalResult.approvalUrl,
+                        expiresAt: approvalResult.expiresAt,
+                        status: 'pending',
+                        message: approved.length > 0
+                            ? `Approved: [${approved.join(', ')}]. Approval required for: [${pending.join(', ')}]. See approvalUrl field.`
+                            : `Permission required for: [${pending.join(', ')}]. See approvalUrl field.`,
+                    },
+                };
+            }
+            catch (err) {
+                // Fallback: return pending without URL if approval request creation fails
+                return {
+                    success: true,
+                    data: {
+                        approved,
+                        denied,
+                        pending,
+                        status: 'partial',
+                        message: `Approved: [${approved.join(', ')}]. Pending: [${pending.join(', ')}]. Denied: [${denied.join(', ')}]. Failed to create approval URL: ${err instanceof Error ? err.message : String(err)}. Use aidentity_call_tool for pending actions — you will be prompted to approve.`,
+                    },
+                };
+            }
+        }
+        return {
+            success: true,
+            data: {
+                approved,
+                denied,
+                pending,
+                status: allApproved ? 'approved' : 'partial',
+                message: allApproved
+                    ? 'All requested permissions have been granted. You can now use aidentity_call_tool.'
+                    : `Approved: [${approved.join(', ')}]. Denied: [${denied.join(', ')}].`,
+            },
+        };
+    }
+    async listAvailableTools() {
+        const tools = ai_identity_1.ACTION_REGISTRY.actions.map(a => ({
+            action: a.action,
+            resource_type: a.resource_type,
+            risk: a.risk,
+            input_schema: a.input_schema,
+        }));
+        return { success: true, data: { tools, count: tools.length } };
+    }
+    /**
+     * Resolve env vars for os.process.run from .env file.
+     * Returns empty record if no env_profile specified or .env not found.
+     */
+    async resolveProcessEnv(params) {
+        if (!this.secretBackend || !params.env_profile) {
+            return {};
+        }
+        const envPath = path.join(params.working_directory || process.cwd(), '.env');
+        try {
+            const content = fs.readFileSync(envPath, 'utf-8');
+            const envResolver = new env_resolver_1.EnvResolver(this.secretBackend);
+            const { env, warnings } = await envResolver.resolveEnvContentWithWarnings(content);
+            for (const w of warnings) {
+                process.stderr.write(`[vess] Warning: ${w}\n`);
+            }
+            return env;
+        }
+        catch (err) {
+            if (err?.code === 'ENOENT') {
+                process.stderr.write(`[vess] Warning: env_profile "${params.env_profile}" requested but .env not found at ${envPath}\n`);
+                return {};
+            }
+            // Resolution errors (keychain failures, etc.) should propagate
+            throw err;
+        }
+    }
+    getActionRiskLevel(action) {
+        const actionDef = ai_identity_1.ACTION_REGISTRY.actions.find(a => a.action === action);
+        if (!actionDef) {
+            process.stderr.write(`[vess] WARNING: action "${action}" not found in ACTION_REGISTRY, defaulting to high risk\n`);
+            return 'high';
+        }
+        return actionDef.risk || 'high';
+    }
+    getDefaultVCTTL(riskLevel) {
+        const defaults = {
+            low: { minutes: 60, label: '1 hour (low risk default)' },
+            medium: { minutes: 30, label: '30 minutes (medium risk default)' },
+            high: { minutes: 10, label: '10 minutes (high risk default)' },
+            critical: { minutes: 5, label: '5 minutes (critical risk default)' },
+        };
+        return defaults[riskLevel];
+    }
+    async handleApprovalResponse(request, provider, normalizedResource, resourceFingerprint, requestedResource) {
+        const { action, approval } = request;
+        if (!approval)
+            return { success: false, error: 'No approval provided' };
+        // Verify token (with resource binding for both local and SaaS actions)
+        const extractedResource = this.extractResourceIdFromInput(action, request.input);
+        const expectedResource = normalizedResource ?? extractedResource;
+        const tokenResult = this.tokenService.verify(approval.token, action, expectedResource);
+        if (!tokenResult.valid) {
+            return { success: false, error: `Invalid approval token: ${tokenResult.error}` };
+        }
+        // Validate choice
+        const validChoices = ['one_time', 'persistent', 'deny_once', 'deny_persistent'];
+        if (!validChoices.includes(approval.choice)) {
+            return { success: false, error: `Invalid approval choice: ${approval.choice}` };
+        }
+        // Handle deny choices
+        if (approval.choice === 'deny_once') {
+            this.logAudit({
+                action, provider,
+                decision: 'deny',
+                enforcementType: 'local',
+                decisionSource: 'local_policy',
+                decisionReason: 'User denied the action (deny_once)',
+                requestedResource, normalizedResource, resourceFingerprint,
+                executionType: (0, executor_registry_1.isLocalAction)(action) ? 'local' : 'gateway',
+                approvalNonce: tokenResult.nonce,
+            });
+            return { success: false, error: 'User denied the action (this time only)' };
+        }
+        if (approval.choice === 'deny_persistent') {
+            this.policyEvaluator.addDenyRule({
+                actions: [action],
+                effect: 'deny',
+                source: 'user',
+            });
+            this.logAudit({
+                action, provider,
+                decision: 'deny',
+                enforcementType: 'local',
+                decisionSource: 'local_policy',
+                decisionReason: 'User denied the action (deny_persistent)',
+                requestedResource, normalizedResource, resourceFingerprint,
+                executionType: (0, executor_registry_1.isLocalAction)(action) ? 'local' : 'gateway',
+                approvalNonce: tokenResult.nonce,
+            });
+            return { success: false, error: 'User denied the action (persistent deny rule added)' };
+        }
+        // Approved (one_time or persistent) — call quickApprove
+        const approvalMode = approval.choice === 'one_time' ? 'one_time' : 'persistent';
+        const resourceInfo = normalizedResource && resourceFingerprint
+            ? { normalizedResource, fingerprint: resourceFingerprint }
+            : undefined;
+        // Determine VC TTL
+        const riskLevel = this.getActionRiskLevel(action);
+        const defaultTTL = this.getDefaultVCTTL(riskLevel);
+        const vcTTLMinutes = approval.vcTTLMinutes
+            ? Math.max(5, Math.min(1440, approval.vcTTLMinutes))
+            : defaultTTL.minutes;
+        const expiresInHours = vcTTLMinutes / 60;
+        // Build resources: for local actions use pattern, for gateway actions extract resource ID from parameters
+        const resourceType = this.getResourceType(action);
+        let resources;
+        if (resourceInfo) {
+            resources = [{ type: resourceType, pattern: resourceInfo.normalizedResource }];
+        }
+        else {
+            const extractedId = this.extractResourceIdFromInput(action, request.input);
+            if (!extractedId && this.getActionRiskLevel(action) === 'high') {
+                const actionDef = ai_identity_1.ACTION_REGISTRY.actions.find(a => a.action === action);
+                const paramName = actionDef?.target_bindings?.resource_id?.param || 'resource ID';
+                return {
+                    success: false,
+                    error: `High-risk action "${action}" requires a specific ${paramName}. Cannot approve with wildcard resource scope.`,
+                };
+            }
+            resources = extractedId
+                ? [{ type: resourceType, id: extractedId }]
+                : [{ type: resourceType }];
+        }
+        try {
+            const quickResult = await this.gatewayClient.quickApprove({
+                actions: [action],
+                resources,
+                normalizedResource: resourceInfo?.normalizedResource,
+                resourceFingerprint: resourceInfo?.fingerprint,
+                subjectDid: this.context.agentDid,
+                projectId: this.context.projectId,
+                issueVC: true,
+                approvalMode,
+                approvalNonce: tokenResult.nonce,
+                expiresInHours,
+            });
+            const stored = this.wallet.storeCredential({
+                holderDid: this.context.agentDid,
+                projectId: this.context.projectId,
+                credentialJwt: quickResult.credential,
+                actions: quickResult.grant.actions,
+                provider,
+                expiresAt: new Date(quickResult.expiresAt).getTime(),
+                normalizedResourceKey: resourceInfo?.normalizedResource,
+                resourceFingerprint: resourceInfo?.fingerprint,
+                resources: (0, wallet_1.validateResources)(quickResult.resources),
+            });
+            // Build VCAcquired from quickApprove result
+            const vcAcquired = {
+                credential: stored,
+                grantId: quickResult.grant.id,
+                approvalMode: approvalMode,
+                approvalNonce: tokenResult.nonce,
+                decisionSource: 'new_vc_from_quick_approve',
+            };
+            // Now execute with the freshly acquired VC (skips double ensureVC)
+            const routing = (0, executor_registry_1.determineRouting)(provider, action);
+            let executeResult;
+            try {
+                if (routing.executor === 'local') {
+                    executeResult = await this.executeLocalWithVC(action, request.input, provider, vcAcquired, normalizedResource, resourceFingerprint, requestedResource);
+                }
+                else {
+                    executeResult = await this.executeViaGatewayWithVC(provider, action, request.input, vcAcquired);
+                }
+            }
+            finally {
+                // Wallet cleanup for one-time grants (regardless of execution success — spec requirement)
+                if (approvalMode === 'one_time' && stored.id) {
+                    this.wallet.revokeCredential(stored.id);
+                }
+            }
+            return executeResult;
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: `Quick-approve failed: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    }
+    getResourceType(action) {
+        const actionDef = ai_identity_1.ACTION_REGISTRY.actions.find(a => a.action === action);
+        if (actionDef) {
+            const parts = actionDef.resource_type.split(':');
+            return parts.length > 1 ? parts[1] : parts[0];
+        }
+        return '*';
+    }
+    /**
+     * Extract specific resource ID from action input using ACTION_REGISTRY target_bindings.
+     * For gateway (SaaS) actions, the resource ID (e.g., channel ID) is in the input parameters.
+     * Returns undefined for actions without param-sourced bindings or when the param is absent
+     * (e.g., target_bindings with required: false).
+     */
+    extractResourceIdFromInput(action, input) {
+        const actionDef = ai_identity_1.ACTION_REGISTRY.actions.find(a => a.action === action);
+        if (!actionDef?.target_bindings?.resource_id)
+            return undefined;
+        const binding = actionDef.target_bindings.resource_id;
+        if (binding.source !== 'param')
+            return undefined;
+        const value = input[binding.param];
+        if (!value || typeof value !== 'string')
+            return undefined;
+        // Defense-in-depth: reject control characters and excessively long values
+        const MAX_RESOURCE_ID_LENGTH = 500;
+        if (value.length > MAX_RESOURCE_ID_LENGTH || /[\x00-\x1f]/.test(value))
+            return undefined;
+        return value;
+    }
+    isRecentOOBRequest(action, resourceId) {
+        const key = `${action}:${resourceId || '*'}`;
+        const lastTime = this.recentOOBRequests.get(key);
+        return !!lastTime && (Date.now() - lastTime) < ExecutionEngine.OOB_COOLDOWN_MS;
+    }
+    trackOOBRequest(action, resourceId) {
+        const key = `${action}:${resourceId || '*'}`;
+        this.recentOOBRequests.set(key, Date.now());
+        if (this.recentOOBRequests.size > ExecutionEngine.OOB_MAP_MAX_SIZE) {
+            const now = Date.now();
+            for (const [k, t] of this.recentOOBRequests) {
+                if (now - t > ExecutionEngine.OOB_COOLDOWN_MS) {
+                    this.recentOOBRequests.delete(k);
+                }
+            }
+        }
+    }
+    /** Verify a wallet VC: check revocation via Gateway, handle expiry. Returns the VC if valid, null if invalid. */
+    async verifyWalletVC(vc) {
+        // Check local expiration first — avoids sending expired VCs to the API
+        // Check both wallet expiresAt and JWT exp claim (JWT exp is in seconds, convert to ms)
+        const jwtExp = (0, vc_utils_1.extractExpFromVC)(vc.credentialJwt);
+        const effectiveExpiresAt = vc.expiresAt ?? (jwtExp !== null ? jwtExp * 1000 : null);
+        if (effectiveExpiresAt && effectiveExpiresAt <= Date.now()) {
+            this.wallet.revokeCredential(vc.id);
+            return null;
+        }
+        const jti = (0, vc_utils_1.extractJtiFromVC)(vc.credentialJwt);
+        if (jti) {
+            try {
+                const status = await this.gatewayClient.checkVCStatus(jti);
+                if (!status.valid) {
+                    this.wallet.revokeCredential(vc.id);
+                    return null;
+                }
+                return vc;
+            }
+            catch {
+                // Gateway unreachable — use cached VC if not expired (already checked above)
+                return vc;
+            }
+        }
+        // No jti extractable — backward compat
+        return vc;
+    }
+    async handleResourceMismatch(action, provider, params, vcResult) {
+        const extractedId = this.extractResourceIdFromInput(action, params);
+        if (this.isRecentOOBRequest(action, extractedId)) {
+            return {
+                success: false,
+                error: 'Resource access denied. An approval request was recently created. Please approve it or wait before retrying.',
+            };
+        }
+        this.logAudit({
+            action, provider,
+            decision: 'deny',
+            enforcementType: 'gateway',
+            decisionSource: 'gateway_execution',
+            decisionReason: 'Resource mismatch — VC scope does not cover target resource',
+            executionType: 'gateway',
+            credentialId: vcResult.credential.id,
+        });
+        try {
+            const riskLevel = this.getActionRiskLevel(action);
+            const oobResult = await this.createOOBApprovalRequest(action, provider, riskLevel, undefined, params);
+            this.trackOOBRequest(action, extractedId);
+            return { success: false, waitingForApproval: oobResult.waitingForApproval };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: `Resource mismatch detected but failed to create approval request: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    }
+    logAudit(params) {
+        this.auditLogger?.logEvent({
+            action: params.action,
+            provider: params.provider,
+            executionType: params.executionType,
+            decision: params.decision,
+            enforcementType: params.enforcementType,
+            decisionSource: params.decisionSource,
+            decisionReason: params.decisionReason,
+            rootDid: this.context.rootDid,
+            agentDid: this.context.agentDid,
+            presenterDid: this.context.agentDid,
+            projectId: this.context.projectId,
+            requestedResource: params.requestedResource,
+            normalizedResource: params.normalizedResource,
+            resourceFingerprint: params.resourceFingerprint,
+            grantId: params.grantId,
+            credentialId: params.credentialId,
+            approvalMode: params.approvalMode,
+            approvalNonce: params.approvalNonce,
+        });
+    }
+}
+exports.ExecutionEngine = ExecutionEngine;
+//# sourceMappingURL=execution-engine.js.map