Approval Plugin

npm install @frontmcp/plugin-approval

import { FrontMcp, App } from '@frontmcp/sdk';
import { ApprovalPlugin } from '@frontmcp/plugin-approval';

@App({
  id: 'my-app',
  name: 'My App',
  plugins: [ApprovalPlugin.init()], // Uses memory store by default
  tools: [
    /* your tools */
  ],
})
class MyApp {}

@FrontMcp({
  info: { name: 'My Server', version: '1.0.0' },
  apps: [MyApp],
})
export default class Server {}

import { ApprovalScope } from '@frontmcp/plugin-approval';
import { Tool, ToolContext } from '@frontmcp/sdk';
import { z } from '@frontmcp/sdk';

@Tool({
  name: 'file_write',
  description: 'Write to file system',
  inputSchema: { path: z.string(), content: z.string() },
  approval: {
    required: true,
    defaultScope: ApprovalScope.SESSION,
    category: 'write',
    riskLevel: 'medium',
    approvalMessage: 'Allow writing to file system for this session?',
  },
})
export default class FileWriteTool extends ToolContext {
  async execute(input: { path: string; content: string }) {
    // Tool only executes if approved
    return await this.writeFile(input.path, input.content);
  }
}

@Tool({ name: 'dangerous_tool' })
class DangerousTool extends ToolContext {
  async execute(input) {
    // Check if approved
    const isApproved = await this.approval.isApproved('dangerous_tool');

    if (!isApproved) {
      // Request approval from client
      return { needsApproval: true, message: 'Please approve this action' };
    }

    // Proceed with dangerous operation
    return await this.performDangerousAction(input);
  }
}

{
  "isError": true,
  "content": [{ "type": "text", "text": "Tool \"my-app:file_write\" requires approval to execute. Allow?" }],
  "_meta": { "code": "APPROVAL_REQUIRED", "errorId": "err_…", "timestamp": "…" }
}

ApprovalPlugin.init({
  // Storage configuration
  storage: { type: 'auto' }, // 'auto', 'memory', 'redis', 'vercel-kv'

  // Namespace for approval keys
  namespace: 'approval', // default

  // Approval workflow mode
  mode: 'recheck', // or 'webhook'

  // Enable audit logging
  enableAudit: true, // default

  // Maximum delegation depth
  maxDelegationDepth: 3, // default

  // Cleanup interval for expired approvals
  cleanupIntervalSeconds: 60, // default
});

ApprovalPlugin.init({
  mode: 'recheck',
  recheck: {
    url: 'https://api.example.com/approval/status',
    auth: 'jwt', // 'jwt', 'bearer', 'none', 'custom'
    interval: 5000, // ms between checks
    maxAttempts: 10,
  },
});

ApprovalPlugin.init({
  mode: 'webhook',
  webhook: {
    url: 'https://approval.example.com/webhook',
    includeJwt: false, // Security: don't expose JWT by default
    challengeTtl: 300, // 5 minutes
    callbackPath: '/approval/callback',
  },
});

interface ApprovalRecord {
  toolId: string;
  state: 'pending' | 'approved' | 'denied' | 'expired';
  scope: ApprovalScope;
  grantedAt: number;
  grantedBy: {
    source: 'user' | 'policy' | 'admin' | 'system' | 'agent' | 'api' | 'oauth';
    identifier?: string;
    displayName?: string;
    method?: 'interactive' | 'implicit' | 'delegation' | 'batch' | 'api';
    delegatedFrom?: DelegationContext;
  };
  reason?: string;
  expiresAt?: number;
  revokedAt?: number;
  revokedBy?: ApprovalRevoker;
}

import { userGrantor, adminGrantor, policyGrantor, systemGrantor } from '@frontmcp/plugin-approval';

// User-initiated approval
await this.approval.grantSessionApproval('tool', {
  grantedBy: userGrantor('user-123', 'John Doe', { method: 'interactive' }),
});

// Admin approval
await this.approval.grantUserApproval('tool', {
  grantedBy: adminGrantor('admin-456', 'Admin User'),
});

// Policy-based auto-approval
await this.approval.grantSessionApproval('tool', {
  grantedBy: policyGrantor('policy:read-only-safe'),
});

// System auto-approval
await this.approval.grantSessionApproval('tool', {
  grantedBy: systemGrantor('initialization'),
});

1. Generate PKCE pair: code_verifier (64 chars) + code_challenge = SHA256(verifier)
2. Store challenge: challenge:{code_challenge} → {toolId, sessionId, scope, expiresAt}
3. Send to webhook: {code_challenge, toolId, requestInfo, callbackUrl} (NO sessionId!)
4. External system calls back: POST /approval/callback {code_verifier, approved}
5. Plugin validates: SHA256(code_verifier) === stored code_challenge
6. Grant approval if valid

{
  "code_challenge": "sha256-hash-of-verifier",
  "toolId": "file_write",
  "requestInfo": {
    "toolName": "file_write",
    "category": "write",
    "riskLevel": "medium",
    "customMessage": "Allow writing to file system?"
  },
  "callbackUrl": "https://your-server.com/approval/callback"
}

{
  "code_verifier": "original-verifier-string",
  "approved": true,
  "scope": "session",
  "ttlMs": 3600000,
  "grantedBy": {
    "source": "user",
    "identifier": "user-123",
    "displayName": "John Doe"
  }
}

ApprovalPlugin.init({
  storage: { type: 'auto' }, // Detects from env vars (Redis, Vercel KV, Upstash, or memory)
});

ApprovalPlugin.init({
  storage: { type: 'memory' },
});

ApprovalPlugin.init({
  storage: {
    type: 'redis',
    redis: {
      config: {
        host: 'localhost',
        port: 6379,
        password: process.env.REDIS_PASSWORD,
      },
      // Or, alternatively: url: 'redis://user:pass@host:6379/0'
      // Or, alternatively: client: existingIoRedisClient
    },
  },
});

import { createStorage } from '@frontmcp/utils';

const storage = await createStorage({ type: 'redis', redis: { url: 'redis://localhost' } });

ApprovalPlugin.init({
  storageInstance: storage,
});

import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
import { ApprovalPlugin, userGrantor } from '@frontmcp/plugin-approval';
import { z } from '@frontmcp/sdk';

// Configure approval plugin with webhook mode
const approvalPlugin = ApprovalPlugin.init({
  mode: 'webhook',
  webhook: {
    url: 'https://approval.example.com/webhook',
    challengeTtl: 300,
  },
  storage: {
    type: 'redis',
    redis: {
      config: {
        host: process.env.REDIS_HOST || 'localhost',
        port: parseInt(process.env.REDIS_PORT || '6379'),
      },
    },
  },
});

// Tool requiring approval
@Tool({
  name: 'delete-account',
  description: 'Permanently delete user account',
  inputSchema: { confirm: z.boolean() },
  approval: {
    required: true,
    riskLevel: 'critical',
    category: 'delete',
    approvalMessage: 'This will permanently delete your account. Are you sure?',
    alwaysPrompt: true,
  },
})
class DeleteAccountTool extends ToolContext {
  async execute(input: { confirm: boolean }) {
    if (!input.confirm) {
      return { success: false, message: 'Deletion not confirmed' };
    }

    // Perform account deletion
    await this.deleteAccount();

    return { success: true, message: 'Account deleted' };
  }
}

// Tool for granting approvals (admin only)
@Tool({
  name: 'grant-tool-access',
  description: 'Grant access to a tool for a user',
  inputSchema: {
    toolId: z.string(),
    scope: z.enum(['session', 'user']),
  },
})
class GrantToolAccessTool extends ToolContext {
  async execute(input: { toolId: string; scope: 'session' | 'user' }) {
    const userId = this.context.authInfo?.extra?.['userId'] as string;

    if (input.scope === 'session') {
      await this.approval.grantSessionApproval(input.toolId, {
        grantedBy: userGrantor(userId, 'Admin', { method: 'interactive' }),
        reason: 'Admin granted access',
      });
    } else {
      await this.approval.grantUserApproval(input.toolId, {
        grantedBy: userGrantor(userId, 'Admin', { method: 'interactive' }),
        reason: 'Admin granted persistent access',
      });
    }

    return { success: true, message: `Access granted for ${input.toolId}` };
  }
}

@App({
  id: 'secure-app',
  name: 'Secure App',
  plugins: [approvalPlugin],
  tools: [DeleteAccountTool, GrantToolAccessTool],
})
class SecureApp {}

@FrontMcp({
  info: { name: 'Secure Server', version: '1.0.0' },
  apps: [SecureApp],
  http: { port: 3000 },
})
export default class Server {}