@sendinel/mcp-server 1.0.143 → 1.0.144

package/README.md

@@ -18,7 +18,7 @@ preserves REST outcomes, and redacts failures. See the
 [event-triggered campaign guide](../../docs/event-triggered-campaigns.md) for
 inputs, idempotency, subscription requirements, and conditional step examples.
 
-Sendinel currently exposes 35 tool groups and 344 tools (gateway mode exposes 4 meta-tools, sharing how_to with full mode). These counts are checked against the tool registry in CI, so this table matches what ships.
+Sendinel currently exposes 35 tool groups and 346 tools (gateway mode exposes 4 meta-tools, sharing how_to with full mode). These counts are checked against the tool registry in CI, so this table matches what ships.
 
 | Group | Count | Purpose |
 |-------|-------|---------|
@@ -27,7 +27,7 @@ Sendinel currently exposes 35 tool groups and 344 tools (gateway mode exposes 4
 | `advisor` | 6 | Campaign advisor: recommendations, benchmarks, subject/content/send-time guidance |
 | `ai-work` | 9 | AI work items, recommended segments, context events, agent proposals |
 | `analytics` | 15 | Stats, portfolio analytics, project switching, domain health, engagement, deliverability, revenue analytics |
-| `approvals` | 3 | Poll and list risk-tiered action approvals |
+| `approvals` | 5 | Poll/list approvals, person OAuth approval, write-scoped cancellation, opted-in chat confirmation |
 | `automations` | 7 | Automation triggers, previews, and response-gated escalation ladders |
 | `brand_kit` | 6 | Brand Core text import, media library upload/URL ingest, asset-context reads, project logo selection |
 | `campaigns` | 44 | Full campaign lifecycle: create, edit, approve, launch, enroll, schedule, sequence templates, convert imported campaigns |
@@ -58,6 +58,14 @@ Sendinel currently exposes 35 tool groups and 344 tools (gateway mode exposes 4
 | `warmup` | 4 | IP/domain warmup schedule control |
 | `webhooks` | 5 | Webhook subscription management |
 
+`cancel_approval({approval_id})` rejects an unexpired, unused pending/approved
+request in the current project for any write-scoped credential.
+`approve_approval({approval_id})` requires the person's own live OAuth connection
+(`connection_role: NULL`) and its own pending request in that project. Tester,
+agent, API key, service-token and scoped-JWT credentials cannot approve. Sends
+and deletes still need approval; the user may answer through their AI without
+another verification prompt. See [approval tools](../../docs/mcp-tools.md#approve_approval).
+
 ## Install / run
 
 ```bash

package/build/lib/action-approvals.js

@@ -405,10 +405,10 @@ export async function checkApproval(approvalId, options = {}) {
     }
     if (data.used_at || data.status === 'used')
         return { approved: false, status: 'consumed' };
-    // Chat decisions stay bound to the same live human grant at consumption, for every action.
-    if (data.status === 'approved' && data.decided_via === 'chat_confirm' &&
+    // Tool decisions stay bound to the same live human grant at consumption, for every action.
+    if (data.status === 'approved' && ['chat_confirm', 'mcp_person'].includes(data.decided_via) &&
         (requestContext()?.oauthTokenId !== data.oauth_token_id || requestContext()?.actorId !== data.decided_by ||
-            !await humanApprovalEligible(data.action, getProjectId(), requestContext(), true))) {
+            !await humanApprovalEligible(data.action, getProjectId(), requestContext(), data.decided_via === 'chat_confirm'))) {
         return { approved: false, status: 'human_decision_required' };
     }
     const sandboxDecision = data.decided_via === 'sandbox';
@@ -418,7 +418,7 @@ export async function checkApproval(approvalId, options = {}) {
     }
     if (data.status === 'approved' && !sandboxDecision && (!isHumanApprovalChannel(data.decided_via) ||
         (isHumanRequestableAdminTool(data.action) && data.decided_via !== 'dashboard' &&
-            (!['mcp_app', 'mcp_elicitation', 'chat_confirm'].includes(data.decided_via) ||
+            (!['mcp_app', 'mcp_elicitation', 'chat_confirm', 'mcp_person'].includes(data.decided_via) ||
                 !await humanApprovalEligible(data.action, getProjectId(), { projectId: getProjectId(),
                     actorId: data.decided_by, oauthTokenId: data.oauth_token_id, authKind: 'oauth', channelVerified: true }))))) {
         return { approved: false, status: 'human_decision_required' };
@@ -459,7 +459,7 @@ export async function checkApproval(approvalId, options = {}) {
         .eq('decided_via', data.decided_via)
         .eq('params', JSON.stringify(data.params))
         .gt('requested_at', new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString());
-    if (data.decided_via === 'chat_confirm')
+    if (['chat_confirm', 'mcp_person'].includes(data.decided_via))
         claimQuery.eq('oauth_token_id', requestContext().oauthTokenId).eq('decided_by', requestContext().actorId);
     const boundClaim = data.payload_hash ? claimQuery.eq('payload_hash', data.payload_hash) : claimQuery.is('payload_hash', null);
     const { data: claimed, error: claimError } = await boundClaim.select('decided_by').maybeSingle();

package/build/lib/approval-exempt.js

@@ -20,8 +20,10 @@ export const APPROVAL_EXEMPT = {
     add_suppression: "only stops mail to an address; reduces sending",
     add_synced_folder: "starts syncing a Drive folder into the project own media library; inbound only",
     add_white_label_domain: "adds a pending branding domain record; reversible and sends nothing",
+    approve_approval: "is the approval step itself: only a person-role OAuth connection can decide its own pending request, bound to that token and project, audited; sends nothing",
     approve_data_proposal: "turns a proposal into an AI draft for review; sends nothing",
     approve_draft: "marks a draft ready; sending still requires a gated send or activation",
+    cancel_approval: "only moves an unused approval to rejected (never grants anything); reduces what can run",
     cancel_send_queue_rows: "cancels queued mail before it sends; reduces sending",
     clone_campaign: "creates a draft copy of a campaign; nothing sends until activated (gated)",
     clone_sequence_template: "creates a draft campaign from a template; nothing sends until activated (gated)",

package/build/lib/approval-tool-decisions.d.ts

@@ -0,0 +1,15 @@
+export declare function cancelApproval(approvalId: string, transportClientName?: string): Promise<{
+    code: string;
+    error: string;
+} | {
+    approval_id: string;
+    status: 'rejected';
+}>;
+export declare function approveApproval(approvalId: string, transportClientName?: string): Promise<{
+    code: string;
+    error: string;
+} | {
+    approval_id: string;
+    decision_status: 'approved';
+    next: string;
+}>;

package/build/lib/approval-tool-decisions.js

@@ -0,0 +1,103 @@
+import { requestContext } from '../db.js';
+import { getProjectId } from '../project.js';
+import { humanApprovalEligible } from './approval-human-eligibility.js';
+import { approvalStore } from './tester-requests-store.js';
+const refuse = (code, error) => ({ code, error });
+const store = () => approvalStore().schema('email');
+/** OAuth names come from the registered client, never a model-supplied argument. */
+async function clientName(fallback) {
+    const actor = requestContext();
+    if (!actor?.oauthTokenId)
+        return fallback ?? actor?.agentLabel ?? null;
+    const client = store();
+    const { data: grant, error: grantError } = await client.from('mcp_oauth_tokens')
+        .select('client_id').eq('id', actor.oauthTokenId).maybeSingle();
+    if (grantError || !grant?.client_id)
+        throw new Error('Unable to identify the OAuth client');
+    const { data, error } = await client.from('mcp_oauth_clients')
+        .select('client_name').eq('client_id', grant.client_id).maybeSingle();
+    if (error || typeof data?.client_name !== 'string')
+        throw new Error('Unable to identify the OAuth client');
+    return data.client_name;
+}
+export async function cancelApproval(approvalId, transportClientName) {
+    const actor = requestContext();
+    if (!actor?.scopes?.some(scope => scope === 'write' || scope === 'admin')) {
+        return refuse('approval_forbidden', 'Cancelling an approval requires write scope.');
+    }
+    try {
+        const projectId = getProjectId();
+        const name = await clientName(transportClientName);
+        const now = new Date().toISOString();
+        // A single conditional write arbitrates cancellation versus approval/consumption.
+        // Preserve the original decision provenance; cancellation never grants authority.
+        const { data, error } = await store().from('action_approvals')
+            .update({ status: 'rejected' })
+            .eq('id', approvalId).eq('project_id', projectId)
+            .in('status', ['pending', 'approved']).is('used_at', null).gt('expires_at', now)
+            .select('id').maybeSingle();
+        if (error)
+            return refuse('approval_update_failed', 'Unable to cancel the approval. Check its status before retrying.');
+        if (!data)
+            return refuse('approval_not_cancellable', 'No unexpired, unused pending or approved approval found in this project.');
+        const { error: auditError } = await store().from('audit_log').insert({
+            project_id: projectId, actor_type: actor.actorType ?? actor.authKind ?? 'api_key',
+            actor_id: actor.actorId ?? actor.keyId ?? actor.oauthTokenId ?? null,
+            action: 'approval.cancelled', resource_type: 'approval', resource_id: approvalId,
+            details: { status: 'rejected', client_name: name, auth_kind: actor.authKind ?? null,
+                oauth_token_id: actor.oauthTokenId ?? null, api_key_id: actor.keyId ?? null },
+        });
+        if (auditError)
+            return refuse('approval_audit_failed', 'Approval cancelled, but audit failed. Check its status before retrying.');
+        return { approval_id: approvalId, status: 'rejected' };
+    }
+    catch {
+        return refuse('approval_failed', 'Cancellation failed. Check approval status before retrying.');
+    }
+}
+export async function approveApproval(approvalId, transportClientName) {
+    const actor = requestContext();
+    const projectId = getProjectId();
+    // Reuse the same live-grant identification as the app/elicitation path (#4312).
+    if (!await humanApprovalEligible('approve_approval', projectId, actor)) {
+        return refuse('approval_forbidden', 'Approval requires your own verified person-role OAuth connection in this project.');
+    }
+    try {
+        const client = store();
+        const { data: approval, error: loadError } = await client.from('action_approvals')
+            .select('action, params, payload_hash')
+            .eq('id', approvalId).eq('project_id', projectId).eq('oauth_token_id', actor.oauthTokenId)
+            .eq('status', 'pending').is('used_at', null).gt('expires_at', new Date().toISOString()).maybeSingle();
+        if (loadError)
+            return refuse('approval_lookup_failed', 'Unable to verify the approval. Nothing was recorded.');
+        if (!approval)
+            return refuse('approval_not_pending', 'No unexpired, unused pending approval found for this connection and project.');
+        if (!await humanApprovalEligible(approval.action, projectId, actor)) {
+            return refuse('approval_forbidden', 'This approval requires a person with the required project role.');
+        }
+        const name = await clientName(transportClientName);
+        const now = new Date().toISOString();
+        const decision = client.from('action_approvals')
+            .update({ status: 'approved', decided_via: 'mcp_person', decided_by: actor.actorId, decided_at: now })
+            .eq('id', approvalId).eq('project_id', projectId).eq('oauth_token_id', actor.oauthTokenId)
+            .eq('action', approval.action).eq('status', 'pending').is('used_at', null).gt('expires_at', now)
+            .eq('params', JSON.stringify(approval.params));
+        const bound = approval.payload_hash == null ? decision.is('payload_hash', null) : decision.eq('payload_hash', approval.payload_hash);
+        const { data, error } = await bound.select('id, payload_hash').maybeSingle();
+        if (error || !data)
+            return refuse('approval_not_pending', 'Approval is already decided, used or no longer valid. Request a new approval.');
+        const { error: auditError } = await client.from('audit_log').insert({
+            project_id: projectId, actor_type: 'user', actor_id: actor.actorId,
+            action: 'approval.submitted', resource_type: 'approval', resource_id: approvalId,
+            details: { status: 'approved', channel: 'mcp_person', client_name: name,
+                connection_id: `oauth:${actor.oauthTokenId}`, payload_hash: data.payload_hash },
+        });
+        if (auditError)
+            return refuse('approval_audit_failed', 'Approval recorded, but audit failed. Check its status before retrying.');
+        return { approval_id: approvalId, decision_status: 'approved',
+            next: `Call ${approval.action} again with the same arguments plus approval_id.` };
+    }
+    catch {
+        return refuse('approval_failed', 'Approval failed. Check approval status before retrying.');
+    }
+}

package/build/server.js

@@ -87,6 +87,7 @@ export const ALL_TOOL_GROUPS = Object.keys(GROUP_REGISTRY);
 // ── Scope enforcement ─────────────────────────────────────────────────────
 // Maps tool names to required scope. Mirrors dashboard's WRITE_TOOLS/ADMIN_TOOLS.
 const WRITE_TOOLS = new Set([
+    'cancel_approval', 'approve_approval',
     'recheck_domain_dns',
     'mark_agent_message', 'draft_agent_reply', 'create_agent_mailbox',
     'add_subscriber', 'identify_subscriber', 'emit_contact_event', 'import_subscribers', 'update_subscriber', 'bulk_update_subscribers',
@@ -172,7 +173,7 @@ export function isAgentConnection(scopes) {
     return !!scopes?.includes(AGENT_CONNECTION_SCOPE);
 }
 export function agentConnectionAllowsTool(name) {
-    return ['list_agent_inbox', 'read_agent_message', 'get_agent_thread', 'mark_agent_message',
+    return ['cancel_approval', 'list_agent_inbox', 'read_agent_message', 'get_agent_thread', 'mark_agent_message',
         'draft_agent_reply', 'search_tools', 'describe_tool', 'invoke_tool'].includes(name);
 }
 export function agentConnectionRefusal(name) {
@@ -186,6 +187,7 @@ export function testerConnectionAllowsTool(name) {
     // Retain the existing campaign activation path. A globally gated tool is not by itself
     // permission for a tester: sends, deletes and access/infrastructure writes stay refused.
     return getRequiredScope(name) === 'read'
+        || name === 'cancel_approval'
         || TESTER_REQUEST_TOOLS.has(name)
         || name === 'activate_campaigns'
         || name === 'update_campaign_status';
@@ -321,7 +323,7 @@ function createScopeProxy(server, scopes, toolGroup, allowedTools) {
                         const required = getRequiredScope(name);
                         const tester = isTesterConnection(scopes);
                         const agent = isAgentConnection(scopes);
-                        const allowed = () => agent ? agentConnectionAllowsTool(name) : tester
+                        const allowed = () => name === 'cancel_approval' ? scopeAllows(scopes, 'write') : agent ? agentConnectionAllowsTool(name) : tester
                             ? testerConnectionAllowsTool(name)
                             : scopeAllows(scopes, required) || (scopeAllows(scopes, 'read') && isHumanRequestableAdminTool(name));
                         if (!allowed()) {

package/build/tools/approvals.js

@@ -4,9 +4,29 @@ import { getProjectId } from '../project.js';
 import { dbToolError, toolError } from '../lib/db-error.js';
 import { checkApproval } from '../lib/action-approvals.js';
 import { confirmApproval, confirmApprovalInput } from '../lib/approval-chat-confirm.js';
+import { approveApproval, cancelApproval } from '../lib/approval-tool-decisions.js';
+import { approvalClientName } from '../lib/approval-capabilities.js';
 const txt = (text) => ({ content: [{ type: 'text', text }] });
 const j = (data) => txt(JSON.stringify(data, null, 2));
 export function registerApprovalTools(server, options) {
+    server.registerTool('cancel_approval', {
+        title: 'Cancel Approval',
+        description: 'Cancel an unexpired, unused pending or approved action approval in this project. Requires write scope. Sets it to rejected; cannot approve or undo cancellation.',
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+        inputSchema: { approval_id: z.string().uuid() },
+    }, async ({ approval_id }) => {
+        const result = await cancelApproval(approval_id, server.server && approvalClientName(server.server));
+        return { ...j(result), ...('code' in result ? { isError: true } : {}) };
+    });
+    server.registerTool('approve_approval', {
+        title: 'Approve Approval',
+        description: "Record the person's approval through their own OAuth connection for this project. Only person-role OAuth connections may approve their own pending, unexpired, unused requests. Tester, agent, API key, service token and scoped JWT credentials cannot approve. Call only when the person asks to approve; then retry the original action with approval_id.",
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+        inputSchema: { approval_id: z.string().uuid() },
+    }, async ({ approval_id }) => {
+        const result = await approveApproval(approval_id, server.server && approvalClientName(server.server));
+        return { ...j(result), ...('code' in result ? { isError: true } : {}) };
+    });
     if (options?.chatConfirmEnabled !== false && (!options?.scopes || options.chatConfirmEnabled === true) &&
         !options?.scopes?.some(scope => scope === 'tester' || scope === 'agent')) {
         server.registerTool('confirm_approval', {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sendinel/mcp-server",
-  "version": "1.0.143",
+  "version": "1.0.144",
   "description": "AI-controlled email operations control plane for campaigns, contacts, segments, analytics, and multi-provider sending via MCP.",
   "mcpName": "ai.sendinel/mcp-server",
   "type": "module",