@sendinel/mcp-server 1.0.109 → 1.0.111

package/build/db.d.ts

@@ -32,6 +32,7 @@ export declare function setProjectClient(client: any): void;
  * @param fn     - Async function to run within this client's context.
  */
 export declare function runWithClient<T>(client: any, fn: () => Promise<T>, request?: {
+    scopes?: readonly string[];
     projectId?: string;
     approvalMode?: string;
     channel?: string;
@@ -48,12 +49,16 @@ export declare function runWithClient<T>(client: any, fn: () => Promise<T>, requ
     kid?: string | null;
     v1Caller?: V1Caller;
 }): Promise<T>;
-export declare function runWithToolContext<T>(toolGroup: string, toolName: string, fn: () => Promise<T> | T): Promise<T>;
+export declare function runWithToolContext<T>(toolGroup: string, toolName: string, fn: () => Promise<T> | T, scopes?: readonly string[] | null): Promise<T>;
+/** Keep the consumed-approval marker inside this async call; model input cannot set it. */
+export declare function runWithApprovedTesterRequest<T>(action: string, fn: () => Promise<T> | T): Promise<T>;
 /**
  * Request-scoped identity set via runWithClient() (HTTP transport).
  * Undefined under stdio, where the process env is the single-project source of truth.
  */
 export declare function requestContext(): {
+    scopes?: readonly string[];
+    approvedTesterAction?: string;
     projectId?: string;
     approvalMode?: string;
     channel?: string;

package/build/db.js

@@ -48,11 +48,18 @@ export async function runWithClient(
 client, fn, request) {
     return _requestStore.run({ client, ...request }, fn);
 }
-export async function runWithToolContext(toolGroup, toolName, fn) {
+export async function runWithToolContext(toolGroup, toolName, fn, scopes) {
     const current = _requestStore.getStore();
     if (!current)
-        return await _requestStore.run({ client: _processClient, toolGroup, toolName }, fn);
-    return await _requestStore.run({ ...current, toolGroup, toolName }, fn);
+        return await _requestStore.run({ client: _processClient, toolGroup, toolName, scopes: scopes ?? undefined }, fn);
+    return await _requestStore.run({ ...current, toolGroup, toolName, scopes: scopes ?? current.scopes }, fn);
+}
+/** Keep the consumed-approval marker inside this async call; model input cannot set it. */
+export async function runWithApprovedTesterRequest(action, fn) {
+    const current = _requestStore.getStore();
+    if (!current)
+        throw new Error('Tester application requires request context');
+    return _requestStore.run({ ...current, approvedTesterAction: action }, fn);
 }
 /**
  * Request-scoped identity set via runWithClient() (HTTP transport).
@@ -62,6 +69,8 @@ export function requestContext() {
     const ctx = _requestStore.getStore();
     return ctx
         ? {
+            scopes: ctx.scopes,
+            approvedTesterAction: ctx.approvedTesterAction,
             projectId: ctx.projectId,
             approvalMode: ctx.approvalMode,
             channel: ctx.channel,

package/build/lib/action-approvals.js

@@ -1,6 +1,9 @@
+import { isTesterRequest, isApplyingTesterRequest } from './tester-policy.js';
+import { logTesterRequestAudit } from './tester-request-audit.js';
+import { approvalStore } from './tester-requests-store.js';
 import { createHash } from 'node:crypto';
-import { buildApprovalPreview, isHumanApprovalChannel, triggerChangeSummary, decodeHtmlEntities, stripHtmlComments } from '@sendinel/domain';
-import { db, requestContext } from '../db.js';
+import { approvalSetupSummary, buildApprovalPreview, isHumanApprovalChannel, triggerChangeSummary, decodeHtmlEntities, stripHtmlComments } from '@sendinel/domain';
+import { requestContext } from '../db.js';
 import { getProjectId } from '../project.js';
 import { captureApprovalSnapshot, withoutApprovalSnapshot } from './approval-snapshot.js';
 import { fireWebhookEvent } from './webhook-events.js';
@@ -97,6 +100,8 @@ export function isApprovalGatedAction(action) {
     return GATED_ACTIONS.has(action) || PROTECTED_ACTIONS.has(action);
 }
 export function getApprovalTier(action, params) {
+    if (isTesterRequest(action))
+        return isApplyingTesterRequest(action) ? 'autonomous' : 'gated';
     // CRITICAL: Protected actions ALWAYS require approval, even in autonomous mode.
     // These are irreversible (GDPR delete, merge, etc.) — no opt-out.
     if (PROTECTED_ACTIONS.has(action)) {
@@ -235,6 +240,9 @@ function launchSummary(p, d) {
 }
 /** Build a human-readable summary of the action for the approval screen */
 export function buildApprovalSummary(action, params, display = {}) {
+    const setup = approvalSetupSummary(action, params);
+    if (setup)
+        return setup;
     if ((action === 'update_campaign' || action === 'set_campaign_trigger') && params.previous_campaign && params.updates)
         return triggerChangeSummary(String(params.previous_campaign.name ?? params.campaign_id), params.previous_campaign, params.updates);
     const summaries = {
@@ -325,7 +333,6 @@ function approvalParamsEqual(expected, actual) {
  */
 export async function requestApproval(action, params, apiKeyId, channelContext, display) {
     const tier = getApprovalTier(action, params);
-    const summary = buildApprovalSummary(action, params, display);
     const expiresAt = new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString();
     const { channel, verified } = channelContext ?? currentChannelContext();
     const actor = requestContext();
@@ -338,7 +345,8 @@ export async function requestApproval(action, params, apiKeyId, channelContext,
         throw new Error('Approval audience changed while preparing the preview. Request a new approval.');
     }
     const frozenParams = { ...cleanParams, __approval_snapshot: snapshot };
-    const { data, error } = await db()
+    const summary = buildApprovalSummary(action, frozenParams, display);
+    const { data, error } = await approvalStore()
         .from('action_approvals')
         .insert({
         project_id: getProjectId(),
@@ -358,6 +366,8 @@ export async function requestApproval(action, params, apiKeyId, channelContext,
         .single();
     if (error)
         throw new Error(`Failed to create approval request: ${error.message}`);
+    if (isTesterRequest(action))
+        await logTesterRequestAudit('tester_request', action, data.id, null);
     fireWebhookEvent('approval.requested', {
         approval_id: data.id,
         kind: action,
@@ -366,8 +376,8 @@ export async function requestApproval(action, params, apiKeyId, channelContext,
     }, getProjectId()).catch(() => { });
     return elicitApproval({
         requires_approval: true,
-        ...offerApprovalApp({ id: data.id, action, params: frozenParams, summary, tier, expires_at: expiresAt,
-            payload_hash: approvalPayloadHash(action, frozenParams) }),
+        ...(await offerApprovalApp({ id: data.id, action, params: frozenParams, summary, tier, expires_at: expiresAt,
+            payload_hash: approvalPayloadHash(action, frozenParams) })),
         approval_id: data.id,
         tier,
         action,
@@ -384,7 +394,7 @@ export async function requestApproval(action, params, apiKeyId, channelContext,
  * Returns the approval if approved, null if still pending, throws if rejected/expired.
  */
 export async function checkApproval(approvalId, options = {}) {
-    const { data, error } = await db()
+    const { data, error } = await approvalStore()
         .from('action_approvals')
         .select('action, status, decided_by, decided_via, expires_at, used_at, params, payload_hash, requested_at')
         .eq('id', approvalId)
@@ -440,7 +450,7 @@ export async function checkApproval(approvalId, options = {}) {
     }
     if (expiry <= Date.now())
         return { approved: false, status: 'expired' };
-    const claimQuery = db()
+    const claimQuery = approvalStore()
         .from('action_approvals')
         .update({ status: 'used', used_at: new Date().toISOString() })
         .eq('id', approvalId)

package/build/lib/approval-app-store.d.ts

@@ -0,0 +1,62 @@
+import { type ApprovalChannelAvailable } from './approval-capabilities.js';
+/**
+ * #4285: connection-scoped persistence for the MCP Apps approval tier on stateless transports.
+ * The hosted route builds a fresh SDK server per POST, so neither declared capabilities nor
+ * app sessions may live in process memory. Both live in service-role-only `email` tables.
+ * This module never writes approval decisions: only approval-app.ts may reach the human callback.
+ */
+export declare const CLIENT_CAPABILITIES_TABLE = "mcp_client_capabilities";
+export declare const APP_SESSIONS_TABLE = "approval_app_sessions";
+/** A declaration not refreshed by a new initialize within this window is ignored and purged. */
+export declare const CLIENT_CAPABILITIES_TTL_MS: number;
+export type ConnectionCredential = {
+    column: 'oauth_token_id' | 'api_key_id';
+    id: string;
+};
+/** OAuth connections are keyed by token id; API keys (including service keys) by key id. */
+export declare function connectionCredential(context: {
+    authKind?: string | null;
+    oauthTokenId?: string | null;
+    keyId?: string | null;
+} | undefined): ConnectionCredential | null;
+/**
+ * Called by the hosted route for the POST that carries `initialize`. Overwrites the previous
+ * declaration for the credential. Returns false on any failure; callers then keep the fallback.
+ */
+export declare function recordClientCapabilities(credential: ConnectionCredential, initializeParams: unknown): Promise<boolean>;
+/**
+ * Channel for this session, with the #4285 rollout gate applied. The in-process declaration
+ * wins when it selects a tier. Otherwise (the hosted bridge pair declares nothing) the stored
+ * initialize declaration for this request's credential is read once per server instance.
+ * Only the Apps tier is honored from storage: elicitation needs the live connection that
+ * sent initialize, which a stateless route does not retain. No row means the fallback tier.
+ */
+export declare function resolveApprovalChannel(session: object): Promise<ApprovalChannelAvailable>;
+export type AppIdentity = {
+    userId: string;
+    projectId: string;
+    oauthTokenId: string;
+};
+export type OwnedApproval = {
+    id: string;
+    action: string;
+    params: Record<string, any>;
+    summary?: string;
+    tier: string;
+    expires_at: string;
+    payload_hash: string;
+};
+/** The approval row is the offer: same project and same OAuth token, still pending, gated, frozen. */
+export declare function loadOwnedPendingApproval(approvalId: unknown, identity: AppIdentity): Promise<OwnedApproval | null>;
+export declare function hashAppSession(token: string): string;
+/**
+ * Mints the one outstanding 256-bit app_session for an owned approval. A re-render deletes the
+ * previous unclaimed token first; a partial unique index rejects a concurrent second insert.
+ * Only the SHA-256 hash is stored. The plaintext is returned once, for resource `_meta` only.
+ */
+export declare function mintApprovalAppSession(approval: OwnedApproval, identity: AppIdentity): Promise<string | null>;
+/**
+ * Single guarded UPDATE: succeeds once, only for the unclaimed, unexpired token bound to this
+ * approval, project, OAuth token, user and frozen payload hash. Wrong bindings do not burn it.
+ */
+export declare function claimApprovalAppSession(token: unknown, approval: OwnedApproval, identity: AppIdentity): Promise<boolean>;

package/build/lib/approval-app-store.js

@@ -0,0 +1,174 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { db, requestContext } from '../db.js';
+import { approvalAppClientAllowed, approvalAppEnabled, approvalClientName, approval_channel_available, declaredAppMimeTypes, probeApprovalCapabilities, } from './approval-capabilities.js';
+/**
+ * #4285: connection-scoped persistence for the MCP Apps approval tier on stateless transports.
+ * The hosted route builds a fresh SDK server per POST, so neither declared capabilities nor
+ * app sessions may live in process memory. Both live in service-role-only `email` tables.
+ * This module never writes approval decisions: only approval-app.ts may reach the human callback.
+ */
+export const CLIENT_CAPABILITIES_TABLE = 'mcp_client_capabilities';
+export const APP_SESSIONS_TABLE = 'approval_app_sessions';
+/** A declaration not refreshed by a new initialize within this window is ignored and purged. */
+export const CLIENT_CAPABILITIES_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const APP_SESSION = /^[A-Za-z0-9_-]{43}$/;
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value) ? value : null;
+// Over-long or non-string values are unknown (NULL), never truncated into a different name.
+const bounded = (value, max) => typeof value === 'string' && value.length > 0 && value.length <= max ? value : null;
+const nowIso = () => new Date(Date.now()).toISOString();
+function email() {
+    const source = db();
+    return typeof source.schema === 'function' ? source.schema('email') : source;
+}
+/** OAuth connections are keyed by token id; API keys (including service keys) by key id. */
+export function connectionCredential(context) {
+    if (context?.authKind === 'oauth') {
+        return context.oauthTokenId && UUID.test(context.oauthTokenId) ? { column: 'oauth_token_id', id: context.oauthTokenId } : null;
+    }
+    return context?.keyId && UUID.test(context.keyId) ? { column: 'api_key_id', id: context.keyId } : null;
+}
+/**
+ * Called by the hosted route for the POST that carries `initialize`. Overwrites the previous
+ * declaration for the credential. Returns false on any failure; callers then keep the fallback.
+ */
+export async function recordClientCapabilities(credential, initializeParams) {
+    const params = object(initializeParams);
+    const info = object(params?.clientInfo);
+    const capabilities = probeApprovalCapabilities(params?.capabilities);
+    const now = Date.now();
+    const client = email();
+    try {
+        // Lazy purge (#4285 item 6): expired declarations never select a tier and are removed here.
+        await client.from(CLIENT_CAPABILITIES_TABLE).delete().lt('expires_at', new Date(now).toISOString());
+        const { error } = await client.from(CLIENT_CAPABILITIES_TABLE).upsert({
+            [credential.column]: credential.id,
+            elicitation_form: capabilities.elicitation_form,
+            elicitation_url: capabilities.elicitation_url,
+            mcp_app: capabilities.mcp_app,
+            app_mime_types: declaredAppMimeTypes(params?.capabilities),
+            client_name: bounded(info?.name, 200),
+            client_version: bounded(info?.version, 100),
+            updated_at: new Date(now).toISOString(),
+            expires_at: new Date(now + CLIENT_CAPABILITIES_TTL_MS).toISOString(),
+        }, { onConflict: credential.column });
+        return !error;
+    }
+    catch {
+        return false;
+    }
+}
+const storedCache = new WeakMap();
+async function loadStoredCapabilities(credential) {
+    try {
+        const { data, error } = await email().from(CLIENT_CAPABILITIES_TABLE).select('mcp_app, client_name')
+            .eq(credential.column, credential.id).gt('expires_at', nowIso()).maybeSingle();
+        return error || !data ? null : { mcp_app: data.mcp_app === true, client_name: typeof data.client_name === 'string' ? data.client_name : null };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Channel for this session, with the #4285 rollout gate applied. The in-process declaration
+ * wins when it selects a tier. Otherwise (the hosted bridge pair declares nothing) the stored
+ * initialize declaration for this request's credential is read once per server instance.
+ * Only the Apps tier is honored from storage: elicitation needs the live connection that
+ * sent initialize, which a stateless route does not retain. No row means the fallback tier.
+ */
+export async function resolveApprovalChannel(session) {
+    const local = approval_channel_available(session, { appsAllowed: approvalAppClientAllowed(approvalClientName(session)) });
+    if (local !== 'plain_text' || !approvalAppEnabled())
+        return local;
+    const credential = connectionCredential(requestContext());
+    if (!credential)
+        return local;
+    let perSession = storedCache.get(session);
+    if (!perSession)
+        storedCache.set(session, perSession = new Map());
+    const key = `${credential.column}:${credential.id}`;
+    let pending = perSession.get(key);
+    if (!pending)
+        perSession.set(key, pending = loadStoredCapabilities(credential));
+    const stored = await pending;
+    return stored?.mcp_app && approvalAppClientAllowed(stored.client_name) ? 'mcp_app' : local;
+}
+/** The approval row is the offer: same project and same OAuth token, still pending, gated, frozen. */
+export async function loadOwnedPendingApproval(approvalId, identity) {
+    if (typeof approvalId !== 'string' || !UUID.test(approvalId))
+        return null;
+    const now = nowIso();
+    try {
+        const { data, error } = await email().from('action_approvals')
+            .select('id, project_id, oauth_token_id, action, params, summary, tier, status, used_at, expires_at, payload_hash')
+            .eq('id', approvalId).eq('project_id', identity.projectId).eq('oauth_token_id', identity.oauthTokenId)
+            .eq('status', 'pending').is('used_at', null).gt('expires_at', now).maybeSingle();
+        if (error || !data || data.id !== approvalId || data.project_id !== identity.projectId ||
+            data.oauth_token_id !== identity.oauthTokenId || data.status !== 'pending' || data.used_at)
+            return null;
+        if (data.tier === 'protected' || typeof data.payload_hash !== 'string' || !data.payload_hash)
+            return null;
+        if (!(Date.parse(data.expires_at) > Date.now()) || !object(data.params))
+            return null;
+        return { id: data.id, action: data.action, params: data.params, summary: data.summary ?? undefined,
+            tier: data.tier, expires_at: data.expires_at, payload_hash: data.payload_hash };
+    }
+    catch {
+        return null;
+    }
+}
+export function hashAppSession(token) {
+    return createHash('sha256').update(token).digest('hex');
+}
+/**
+ * Mints the one outstanding 256-bit app_session for an owned approval. A re-render deletes the
+ * previous unclaimed token first; a partial unique index rejects a concurrent second insert.
+ * Only the SHA-256 hash is stored. The plaintext is returned once, for resource `_meta` only.
+ */
+export async function mintApprovalAppSession(approval, identity) {
+    const client = email();
+    try {
+        // Lazy purge (#4285 item 6). A failed purge does not block the render.
+        await client.from(APP_SESSIONS_TABLE).delete().lt('expires_at', nowIso());
+        const { error: rotateError } = await client.from(APP_SESSIONS_TABLE).delete()
+            .eq('approval_id', approval.id).is('claimed_at', null);
+        if (rotateError)
+            return null;
+        const token = randomBytes(32).toString('base64url');
+        const { error } = await client.from(APP_SESSIONS_TABLE).insert({
+            approval_id: approval.id,
+            token_hash: hashAppSession(token),
+            oauth_token_id: identity.oauthTokenId,
+            user_id: identity.userId,
+            project_id: identity.projectId,
+            payload_hash: approval.payload_hash,
+            // Never outlives the approval it decides.
+            expires_at: approval.expires_at,
+        });
+        return error ? null : token;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Single guarded UPDATE: succeeds once, only for the unclaimed, unexpired token bound to this
+ * approval, project, OAuth token, user and frozen payload hash. Wrong bindings do not burn it.
+ */
+export async function claimApprovalAppSession(token, approval, identity) {
+    if (typeof token !== 'string' || !APP_SESSION.test(token))
+        return false;
+    const now = nowIso();
+    try {
+        const { data, error } = await email().from(APP_SESSIONS_TABLE)
+            .update({ claimed_at: now })
+            .eq('token_hash', hashAppSession(token)).eq('approval_id', approval.id).eq('project_id', identity.projectId)
+            .eq('oauth_token_id', identity.oauthTokenId).eq('user_id', identity.userId).eq('payload_hash', approval.payload_hash)
+            .is('claimed_at', null).gt('expires_at', now)
+            .select('id').maybeSingle();
+        return !error && !!data;
+    }
+    catch {
+        return false;
+    }
+}

package/build/lib/approval-app.d.ts

@@ -25,19 +25,26 @@ export declare function renderApprovalApp(approval?: AppApproval): string;
 export declare function registerApprovalAppResources(server: McpServer, read: (id: string) => Promise<{
     html: string;
     appSession: string;
-}>): void;
-/** Called only after the core has persisted its frozen payload. Tokens never enter tool results. */
-export declare function offerApprovalApp(approval: AppApproval): {
+}>, guard?: () => void): void;
+/**
+ * Called only after the core has persisted its frozen payload. Tokens never enter tool results.
+ * The persisted approval row (project, OAuth token, pending, expiry, payload_hash) is the offer:
+ * there is no in-memory offer state, so the resource read may land on another server instance.
+ */
+export declare function offerApprovalApp(approval: AppApproval): Promise<{
     _meta?: {
         ui: {
             resourceUri: string;
         };
     };
-};
+}>;
 /** Transport boundary, outside the model catalog and gateway catalog. Apps hosts MUST
  * honor visibility. Even a raw model tools/call cannot decide without the resource-only token.
- * The SDK Server instance is the connection boundary; no cross-request/global token cache.
+ * #4285: sessions live hashed in email.approval_app_sessions, bound to approval, project, OAuth
+ * token, user and payload hash, so no cross-request in-memory state exists. `hostedDecision`
+ * is set only by the hosted route's dedicated decision bridge (never by catalogs/gateways).
  */
 export declare function installApprovalApp(server: McpServer, options?: {
     scopes?: string[];
+    hostedDecision?: boolean;
 }, approvalTool?: (name: string) => boolean): McpServer;

package/build/lib/approval-app.js

@@ -8,8 +8,9 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 import { z } from 'zod';
 import { requestContext } from '../db.js';
 import { getProjectId } from '../project.js';
-import { approval_channel_available } from './approval-capabilities.js';
+import { approvalAppClientAllowed, approvalAppEnabled, approvalClientName, approval_channel_available } from './approval-capabilities.js';
 import { createHumanApprovalCallback } from './approval-human-callback.js';
+import { claimApprovalAppSession, loadOwnedPendingApproval, mintApprovalAppSession, resolveApprovalChannel } from './approval-app-store.js';
 /** Only frozen facts enter this view. No live reads or model-supplied display overrides. */
 export function approvalAppView(approval) {
     const preview = buildApprovalPreview(approval);
@@ -33,53 +34,48 @@ export function renderApprovalApp(approval) {
     const json = JSON.stringify(data).replace(/</g, '\\u003c').replace(/>/g, '\\u003e').replace(/&/g, '\\u0026');
     return APPROVAL_APP_HTML.replaceAll('__NONCE__', nonce).replace('__APP_DATA__', () => json);
 }
-export function registerApprovalAppResources(server, read) {
+export function registerApprovalAppResources(server, read, guard = () => { }) {
     const config = { mimeType: APPROVAL_APP.mimeType, _meta: approvalAppResourceMeta };
     const result = (uri, text, appSession) => ({ contents: [{ uri: uri.href,
                 mimeType: APPROVAL_APP.mimeType, text, _meta: { ...approvalAppResourceMeta,
                     ...(appSession ? { [APPROVAL_APP_SESSION_META]: appSession } : {}) } }] });
-    server.registerResource('approval-app', APPROVAL_APP.uri, config, async (uri) => result(uri, renderApprovalApp()));
+    server.registerResource('approval-app', APPROVAL_APP.uri, config, async (uri) => { guard(); return result(uri, renderApprovalApp()); });
     server.registerResource('approval-preview', new ResourceTemplate(APPROVAL_APP.template, { list: undefined }), config, async (uri, variables) => { const view = await read(String(variables.approval_id)); return result(uri, view.html, view.appSession); });
 }
 const runtimes = new WeakMap();
 const calls = new AsyncLocalStorage();
 const resourceUri = (id) => `${APPROVAL_APP.uri}/${encodeURIComponent(id)}`;
+const unavailable = () => new Error('Approval app unavailable on this connection; use approve_url.');
+/**
+ * #4285: a clicking human on an authenticated OAuth connection. Sessions are bound to the OAuth
+ * token id, so an API key owner, agent, tester or scoped JWT is never attributed a click.
+ */
 function identity() {
     const context = requestContext();
-    // Do not attribute an API key owner, agent or tester's click to a human.
-    return context?.channelVerified === true && context.actorId && context.authKind !== 'scoped_jwt'
-        ? { userId: context.actorId, projectId: getProjectId() } : null;
-}
-function matches(offer) {
-    const actor = identity();
-    return !!actor && actor.projectId === offer.projectId && actor.userId === offer.userId;
+    return context?.channelVerified === true && context.actorId && context.authKind === 'oauth' && context.oauthTokenId
+        ? { userId: context.actorId, projectId: getProjectId(), oauthTokenId: context.oauthTokenId } : null;
 }
 function live(approval) {
     return Number.isFinite(Date.parse(approval.expires_at)) && Date.parse(approval.expires_at) > Date.now();
 }
-function prune(runtime) {
-    for (const [id, offer] of runtime.offers)
-        if (!live(offer.approval))
-            runtime.offers.delete(id);
-    for (const [token, session] of runtime.sessions)
-        if (!live(session.offer.approval))
-            runtime.sessions.delete(token);
-}
-/** Called only after the core has persisted its frozen payload. Tokens never enter tool results. */
-export function offerApprovalApp(approval) {
+/**
+ * Called only after the core has persisted its frozen payload. Tokens never enter tool results.
+ * The persisted approval row (project, OAuth token, pending, expiry, payload_hash) is the offer:
+ * there is no in-memory offer state, so the resource read may land on another server instance.
+ */
+export async function offerApprovalApp(approval) {
     const runtime = calls.getStore(), actor = identity();
-    if (!runtime || !runtime.canDecide || !actor || approval.tier === 'protected' ||
-        approval_channel_available(runtime.server.server) !== 'mcp_app')
+    if (!runtime || !runtime.canDecide || !actor || !approvalAppEnabled() || approval.tier === 'protected' || !live(approval))
         return {};
-    prune(runtime);
-    if (runtime.offers.size >= 128 || !live(approval))
+    if (await resolveApprovalChannel(runtime.server.server) !== 'mcp_app')
         return {};
-    runtime.offers.set(approval.id, { approval: structuredClone(approval), ...actor });
     return { _meta: { ui: { [APPROVAL_APP.resultUriKey]: resourceUri(approval.id) } } };
 }
 /** Transport boundary, outside the model catalog and gateway catalog. Apps hosts MUST
  * honor visibility. Even a raw model tools/call cannot decide without the resource-only token.
- * The SDK Server instance is the connection boundary; no cross-request/global token cache.
+ * #4285: sessions live hashed in email.approval_app_sessions, bound to approval, project, OAuth
+ * token, user and payload hash, so no cross-request in-memory state exists. `hostedDecision`
+ * is set only by the hosted route's dedicated decision bridge (never by catalogs/gateways).
  */
 export function installApprovalApp(server, options = {}, approvalTool = () => false) {
     // Catalog collectors have no transport/resource API; never expose this tool through them.
@@ -87,60 +83,68 @@ export function installApprovalApp(server, options = {}, approvalTool = () => fa
         return server;
     let runtime = runtimes.get(server.server);
     if (!runtime) {
-        runtime = { server, connectionId: randomBytes(32).toString('hex'), offers: new Map(), sessions: new Map(),
+        runtime = { server, decideRegistered: false,
             canDecide: !options.scopes?.some(scope => scope === 'tester' || scope === 'agent') };
         runtimes.set(server.server, runtime);
         const bound = runtime;
         registerApprovalAppResources(server, async (id) => {
-            prune(bound);
-            const offer = bound.offers.get(id);
-            if (!offer || !matches(offer) || approval_channel_available(server.server) !== 'mcp_app')
-                throw new Error('Approval app unavailable on this connection; use approve_url.');
+            const actor = identity();
+            if (!bound.canDecide || !actor || !approvalAppEnabled() || await resolveApprovalChannel(server.server) !== 'mcp_app')
+                throw unavailable();
+            const approval = await loadOwnedPendingApproval(id, actor);
+            if (!approval)
+                throw unavailable();
             // One outstanding render session per approval. Re-render invalidates the old view.
-            for (const [token, session] of bound.sessions)
-                if (session.offer === offer)
-                    bound.sessions.delete(token);
-            const callback = createHumanApprovalCallback({ approvalId: id, projectId: offer.projectId,
-                userId: offer.userId, connectionId: bound.connectionId, channel: 'mcp_app' });
-            const token = randomBytes(32).toString('base64url');
-            bound.sessions.set(token, { offer, callback });
+            const token = await mintApprovalAppSession(approval, actor);
+            if (!token)
+                throw unavailable();
             // Resource text can be shown to the model; the bearer belongs exclusively
             // in host/app metadata, never HTML, a tool result, a URL or an audit entry.
-            return { html: renderApprovalApp(offer.approval), appSession: token };
-        });
-        const registerDecide = () => server.registerTool(APPROVAL_APP.tool, {
-            description: 'Record the human decision from this connection’s rendered approval app.',
-            _meta: { ui: { visibility: ['app'] } },
-            annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
-            inputSchema: z.object({ approval_id: z.string(), decision: z.enum(['approve', 'reject']), app_session: z.string().min(1) }).strict(),
-        }, async ({ approval_id, decision, app_session }) => {
-            prune(bound);
-            const session = bound.sessions.get(app_session);
-            const refused = () => ({ isError: true, content: [{ type: 'text', text: 'Decision refused; use the dashboard approval link.' }] });
-            if (!bound.canDecide || !session || session.offer.approval.id !== approval_id || !matches(session.offer) ||
-                !live(session.offer.approval) || approval_channel_available(server.server) !== 'mcp_app')
-                return refused();
-            // Claim before awaiting the callback, so concurrent clicks cannot reuse a session.
-            bound.sessions.delete(app_session);
-            bound.offers.delete(approval_id);
-            const accepted = await session.callback.complete({ interactionId: session.callback.interactionId,
-                connectionId: bound.connectionId, decision });
-            return accepted ? { content: [{ type: 'text', text: 'Decision recorded.' }] } : refused();
-        });
+            return { html: renderApprovalApp(approval), appSession: token };
+        }, () => { if (!approvalAppEnabled())
+            throw unavailable(); });
+        const registerDecide = () => {
+            if (bound.decideRegistered)
+                return;
+            bound.decideRegistered = true;
+            server.registerTool(APPROVAL_APP.tool, {
+                description: 'Record the human decision from this connection’s rendered approval app.',
+                _meta: { ui: { visibility: ['app'] } },
+                annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+                inputSchema: z.object({ approval_id: z.string(), decision: z.enum(['approve', 'reject']), app_session: z.string().min(1) }).strict(),
+            }, async ({ approval_id, decision, app_session }) => {
+                const refused = () => ({ isError: true, content: [{ type: 'text', text: 'Decision refused; use the dashboard approval link.' }] });
+                const actor = identity();
+                if (!bound.canDecide || !approvalAppEnabled() || !actor)
+                    return refused();
+                if (await resolveApprovalChannel(server.server) !== 'mcp_app')
+                    return refused();
+                const approval = await loadOwnedPendingApproval(approval_id, actor);
+                // Single guarded claim before the callback, so concurrent clicks cannot reuse a session.
+                if (!approval || !await claimApprovalAppSession(app_session, approval, actor))
+                    return refused();
+                const connectionId = `oauth:${actor.oauthTokenId}`;
+                const callback = createHumanApprovalCallback({ approvalId: approval.id, projectId: actor.projectId,
+                    userId: actor.userId, connectionId, channel: 'mcp_app' });
+                const accepted = await callback.complete({ interactionId: callback.interactionId, connectionId, decision });
+                return accepted ? { content: [{ type: 'text', text: 'Decision recorded.' }] } : refused();
+            });
+        };
+        if (options.hostedDecision && bound.canDecide && approvalAppEnabled())
+            registerDecide();
         const previousInitialized = server.server.oninitialized;
         server.server.oninitialized = () => {
             previousInitialized?.();
-            if (bound.canDecide && approval_channel_available(server.server) === 'mcp_app')
+            if (bound.canDecide && approvalAppEnabled() && approval_channel_available(server.server, { appsAllowed: approvalAppClientAllowed(approvalClientName(server.server)) }) === 'mcp_app')
                 registerDecide();
         };
-        const previousClose = server.server.onclose;
-        server.server.onclose = () => { bound.offers.clear(); bound.sessions.clear(); previousClose?.(); };
     }
     const bound = runtime;
     return new Proxy(server, { get(target, prop, receiver) {
             if (prop !== 'registerTool')
                 return Reflect.get(target, prop, receiver);
-            return (name, config, handler) => target.registerTool(name, approvalTool(name) || name === 'invoke_tool' ? { ...config, _meta: { ...config._meta, ui: { resourceUri: APPROVAL_APP.uri } } } : config, async (...args) => calls.run(calls.getStore() ?? bound, async () => {
+            return (name, config, handler) => target.registerTool(name, approvalAppEnabled() && (approvalTool(name) || name === 'invoke_tool')
+                ? { ...config, _meta: { ...config._meta, ui: { resourceUri: APPROVAL_APP.uri } } } : config, async (...args) => calls.run(calls.getStore() ?? bound, async () => {
                 const result = await handler(...args);
                 // Existing tools serialize ApprovalResult into content; promote ONLY its UI
                 // reference to MCP result metadata. The resource token is never in that object.

package/build/lib/approval-capabilities.d.ts

@@ -8,10 +8,30 @@ export type ApprovalClientCapabilities = Readonly<{
 export type ApprovalChannelAvailable = 'mcp_app' | 'mcp_elicitation_form' | 'mcp_elicitation_url' | 'plain_text';
 /** Reads only declared initialize capabilities. No user agent or client-name guessing. */
 export declare function probeApprovalCapabilities(declared: unknown): ApprovalClientCapabilities;
-export declare function rememberApprovalCapabilities(session: object, declared: unknown): ApprovalClientCapabilities;
-export declare function approval_channel_available(session: object): ApprovalChannelAvailable;
+/** Declared Apps mime types, bounded for storage. Never used to decide Apps support on its own. */
+export declare function declaredAppMimeTypes(declared: unknown): string[];
+/**
+ * #4285 rollout gate. The Apps tier is OFF unless MCP_APPROVAL_APP_ENABLED is exactly "true"
+ * or "1". When on, only clients whose initialize clientInfo.name appears in the comma-separated
+ * MCP_APPROVAL_APP_CLIENTS allowlist get it. An empty allowlist allows no client. The name is
+ * client-declared: this is a rollout control for hosts verified to keep resource metadata and
+ * app-only tools out of model context, not authentication.
+ */
+export declare function approvalAppEnabled(env?: NodeJS.ProcessEnv): boolean;
+export declare function approvalAppClientAllowed(clientName: unknown, env?: NodeJS.ProcessEnv): boolean;
+export declare function rememberApprovalCapabilities(session: object, declared: unknown, clientName?: unknown): ApprovalClientCapabilities;
+/** Name from this in-process session's initialize clientInfo; undefined when none was declared. */
+export declare function approvalClientName(session: object): string | undefined;
+/**
+ * Declared-capability probe for this in-process session. `appsAllowed: false` removes the Apps
+ * tier from the choice (flag off / client not allowlisted), so a lower tier can still be used.
+ */
+export declare function approval_channel_available(session: object, options?: {
+    appsAllowed?: boolean;
+}): ApprovalChannelAvailable;
 /** Each SDK Server is a session boundary, including stateless HTTP request instances. */
 export declare function installApprovalCapabilityProbe(session: {
     oninitialized?: () => void;
     getClientCapabilities(): unknown;
+    getClientVersion?(): unknown;
 }): void;

package/build/lib/approval-capabilities.js

@@ -1,6 +1,7 @@
 export const MCP_APP_EXTENSION = 'io.modelcontextprotocol/ui';
 export const MCP_APP_MIME_TYPE = 'text/html;profile=mcp-app';
 const sessions = new WeakMap();
+const clientNames = new WeakMap();
 const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value) ? value : null;
 /** Reads only declared initialize capabilities. No user agent or client-name guessing. */
 export function probeApprovalCapabilities(declared) {
@@ -15,14 +16,50 @@ export function probeApprovalCapabilities(declared) {
         mcp_app: !!app && Array.isArray(app.mimeTypes) && app.mimeTypes.includes(MCP_APP_MIME_TYPE),
     });
 }
-export function rememberApprovalCapabilities(session, declared) {
+/** Declared Apps mime types, bounded for storage. Never used to decide Apps support on its own. */
+export function declaredAppMimeTypes(declared) {
+    const app = object(object(object(declared)?.extensions)?.[MCP_APP_EXTENSION]);
+    if (!Array.isArray(app?.mimeTypes))
+        return [];
+    return app.mimeTypes.filter((value) => typeof value === 'string' && value.length <= 200).slice(0, 16);
+}
+/**
+ * #4285 rollout gate. The Apps tier is OFF unless MCP_APPROVAL_APP_ENABLED is exactly "true"
+ * or "1". When on, only clients whose initialize clientInfo.name appears in the comma-separated
+ * MCP_APPROVAL_APP_CLIENTS allowlist get it. An empty allowlist allows no client. The name is
+ * client-declared: this is a rollout control for hosts verified to keep resource metadata and
+ * app-only tools out of model context, not authentication.
+ */
+export function approvalAppEnabled(env = process.env) {
+    const value = env.MCP_APPROVAL_APP_ENABLED?.trim();
+    return value === 'true' || value === '1';
+}
+export function approvalAppClientAllowed(clientName, env = process.env) {
+    if (!approvalAppEnabled(env) || typeof clientName !== 'string' || !clientName.trim())
+        return false;
+    const allowed = (env.MCP_APPROVAL_APP_CLIENTS ?? '').split(',').map(name => name.trim()).filter(Boolean);
+    return allowed.includes(clientName.trim());
+}
+export function rememberApprovalCapabilities(session, declared, clientName) {
     const capabilities = probeApprovalCapabilities(declared);
     sessions.set(session, capabilities);
+    if (typeof clientName === 'string')
+        clientNames.set(session, clientName);
+    else
+        clientNames.delete(session);
     return capabilities;
 }
-export function approval_channel_available(session) {
+/** Name from this in-process session's initialize clientInfo; undefined when none was declared. */
+export function approvalClientName(session) {
+    return clientNames.get(session);
+}
+/**
+ * Declared-capability probe for this in-process session. `appsAllowed: false` removes the Apps
+ * tier from the choice (flag off / client not allowlisted), so a lower tier can still be used.
+ */
+export function approval_channel_available(session, options = {}) {
     const capabilities = sessions.get(session);
-    if (capabilities?.mcp_app)
+    if (capabilities?.mcp_app && options.appsAllowed !== false)
         return 'mcp_app';
     if (capabilities?.elicitation_form)
         return 'mcp_elicitation_form';
@@ -34,7 +71,8 @@ export function approval_channel_available(session) {
 export function installApprovalCapabilityProbe(session) {
     const previous = session.oninitialized;
     session.oninitialized = () => {
-        rememberApprovalCapabilities(session, session.getClientCapabilities());
+        const info = object(session.getClientVersion?.());
+        rememberApprovalCapabilities(session, session.getClientCapabilities(), info?.name);
         previous?.call(session);
     };
 }

package/build/lib/approval-elicitation.js

@@ -1,8 +1,8 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { randomUUID } from 'node:crypto';
 import { buildApprovalPreview, isHumanApprovalChannel } from '@sendinel/domain';
-import { db } from '../db.js';
-import { approval_channel_available, probeApprovalCapabilities } from './approval-capabilities.js';
+import { approvalStore } from './tester-requests-store.js';
+import { approvalAppClientAllowed, approvalClientName, approval_channel_available, probeApprovalCapabilities } from './approval-capabilities.js';
 // Keyed by the SDK Server, not the McpServer wrapper: other installers (the Apps tier) wrap
 // McpServer in a Proxy, which changes the wrapper's identity but never the connection's Server.
 const sessions = new WeakMap();
@@ -26,7 +26,8 @@ export async function elicitApproval(result, frozen, projectId) {
     const context = requests.getStore();
     if (!context || context.projectId !== projectId || result.tier !== 'gated')
         return pending;
-    let channel = approval_channel_available(context.server.server);
+    // #4285: with the Apps tier off for this client (default), a declared lower tier still applies.
+    let channel = approval_channel_available(context.server.server, { appsAllowed: approvalAppClientAllowed(approvalClientName(context.server.server)) });
     if (channel === 'mcp_elicitation_form' && !context.userId &&
         probeApprovalCapabilities(context.server.server.getClientCapabilities()).elicitation_url)
         channel = 'mcp_elicitation_url';
@@ -86,7 +87,7 @@ export async function elicitApproval(result, frozen, projectId) {
         // URL accept only means the page may open. Only its authenticated decision counts.
         // Observe while this request is alive; do not retain a background poller after timeout.
         while (!controller.signal.aborted) {
-            const source = db();
+            const source = approvalStore();
             const client = typeof source.schema === 'function' ? source.schema('email') : source;
             const { data, error } = await Promise.race([client.from('action_approvals')
                     .select('status, decided_via').eq('id', result.approval_id).eq('project_id', projectId).maybeSingle(), stopped]);

package/build/lib/approval-human-callback.js

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { db } from '../db.js';
+import { approvalStore } from './tester-requests-store.js';
 /**
  * Server integration only. The transport creates this closure for one authenticated human
  * interaction and retains it outside the tool registry. Neither its id nor decision is a tool
@@ -16,7 +16,7 @@ export function createHumanApprovalCallback(binding) {
             if (response.decision !== 'approve' && response.decision !== 'reject')
                 return false;
             completed = true;
-            const source = db();
+            const source = approvalStore();
             const client = typeof source.schema === 'function' ? source.schema('email') : source;
             const now = new Date().toISOString();
             const { data, error } = await client.from('action_approvals')

package/build/lib/approval-snapshot.js

@@ -1,3 +1,5 @@
+import { isTesterRequest } from './tester-policy.js';
+import { captureTesterRequestSnapshot } from './tester-request-snapshot.js';
 import { readAllRows, chunkIds, scopeSegmentRulesToSite } from '@sendinel/domain';
 import { db } from '../db.js';
 import { resolveSendAudience, resolveSegmentContactIds } from './send-audience.js';
@@ -6,9 +8,10 @@ const TARGET_ACTIONS = new Set(['send_broadcast', 'broadcast_to_segment', 'launc
     'send_transactional', 'send_awaiting_reply', 'send_test_email', 'send_newsletter_issue', 'schedule_newsletter_issue']);
 /** Server-owned display facts, saved inside the hash-bound params. Never supplied by a tool. */
 export async function captureApprovalSnapshot(action, params, projectId) {
+    const setup = isTesterRequest(action) ? await captureTesterRequestSnapshot(action, params, projectId) : null;
     const snapshot = { version: 1, campaigns: [], steps: [], sites: [], recipient_count: null };
     if (!TARGET_ACTIONS.has(action))
-        return snapshot;
+        return setup ?? snapshot;
     const source = db();
     const client = typeof source.schema === 'function' ? source.schema('email') : source;
     const body = params.payload ?? params;
@@ -98,7 +101,7 @@ export async function captureApprovalSnapshot(action, params, projectId) {
     }
     snapshot.campaigns.sort((a, b) => String(a.id).localeCompare(String(b.id)));
     snapshot.steps.sort((a, b) => String(a.id).localeCompare(String(b.id)));
-    return snapshot;
+    return setup ? { ...snapshot, ...setup, recipient_count: snapshot.recipient_count, audience_snapshot: snapshot } : snapshot;
 }
 export function withoutApprovalSnapshot(params) {
     const { __approval_snapshot: _snapshot, ...rest } = (params ?? {});

package/build/lib/campaign-trigger-approval.js

@@ -1,3 +1,4 @@
+import { isApplyingTesterRequest } from './tester-policy.js';
 import { isDeepStrictEqual } from 'node:util';
 import { campaignTriggerChanges, campaignTriggerRevision, triggerChangeNeedsApproval } from '@sendinel/domain';
 import { db } from '../db.js';
@@ -22,7 +23,7 @@ export async function finishCampaignEdit(action, input, existing, updates, reque
     if (campaignTriggerChanges(existing, updates) && !['draft', 'active', 'paused'].includes(existing.status)) {
         return campaignEditError(`Cannot change a ${existing.status} campaign trigger`, 'INVALID_STATUS');
     }
-    if (!triggerChangeNeedsApproval(existing, updates))
+    if (isApplyingTesterRequest(action) || !triggerChangeNeedsApproval(existing, updates))
         return writeEdit(input.campaign_id, existing, updates);
     const params = { campaign_id: input.campaign_id, input, previous_campaign: existing, updates };
     const context = currentChannelContext();

package/build/lib/how-to-recipes.js

@@ -23,7 +23,7 @@ export const HOW_TO_RECIPES = [
         id: 'send-one-off-email', title: 'Send a one-off email to my list',
         when_to_use: 'Send an announcement or email blast to an audience with human approval.',
         synonyms: TOOL_ALIASES.send_broadcast,
-        requires: { scopes: ['write'], tester_ok: true },
+        requires: { scopes: ['write'], tester_ok: false },
         steps: [
             { n: 1, tool: 'send_broadcast', args_example: { audience: 'subscribers to the intended sender', subject: 'A quick update', html: '<p>Here is the update you requested.</p>' }, approval, note: 'Specify site_id if there is more than one sender. Show the subject, recipient_count, sender, finished email and approve_url; wait for a person to approve.' },
             { n: 2, tool: 'send_broadcast', args_example: { approval_id: from(1, 'approval_id') }, approval, note: 'Only after human approval. Pass ONLY approval_id; changed content needs a new request.' },

package/build/lib/tester-policy.d.ts

@@ -0,0 +1,6 @@
+/** Campaign setup only. Never infer this permission from a prefix or model arguments. */
+export declare const TESTER_REQUEST_TOOLS: ReadonlySet<string>;
+export declare const TESTER_SITE_FIELDS: ReadonlySet<string>;
+export declare function isTesterRequest(action: string): boolean;
+/** Server-only context set after the shared core has consumed a human-approved payload. */
+export declare function isApplyingTesterRequest(action: string): boolean;

package/build/lib/tester-policy.js

@@ -0,0 +1,18 @@
+import { requestContext } from '../db.js';
+/** Campaign setup only. Never infer this permission from a prefix or model arguments. */
+export const TESTER_REQUEST_TOOLS = new Set([
+    'update_site', 'update_campaign', 'set_campaign_trigger', 'create_campaign',
+    'create_campaign_with_content', 'add_campaign_step', 'update_campaign_step',
+]);
+export const TESTER_SITE_FIELDS = new Set([
+    'unsub_link_enabled', 'unsub_one_click_enabled', 'unsub_custom_url',
+    'unsub_footer_template', 'unsub_custom_message', 'unsub_brand_logo_url', 'unsub_brand_color',
+]);
+export function isTesterRequest(action) {
+    const ctx = requestContext();
+    return !!ctx?.scopes?.includes('tester') && !ctx.scopes.includes('agent') && TESTER_REQUEST_TOOLS.has(action);
+}
+/** Server-only context set after the shared core has consumed a human-approved payload. */
+export function isApplyingTesterRequest(action) {
+    return isTesterRequest(action) && requestContext()?.approvedTesterAction === action;
+}

package/build/lib/tester-request-audit.d.ts

@@ -0,0 +1,2 @@
+/** Central audit infrastructure, including when the edited site belongs to a BYOD project. */
+export declare function logTesterRequestAudit(event: 'tester_request' | 'tester_applied', action: string, approvalId: string, approver: string | null): Promise<void>;

package/build/lib/tester-request-audit.js

@@ -0,0 +1,15 @@
+import { requestContext } from '../db.js';
+import { getProjectId } from '../project.js';
+import { approvalStore } from './tester-requests-store.js';
+/** Central audit infrastructure, including when the edited site belongs to a BYOD project. */
+export async function logTesterRequestAudit(event, action, approvalId, approver) {
+    const ctx = requestContext();
+    const { error } = await approvalStore().from('audit_log').insert({
+        project_id: getProjectId(), actor_type: ctx?.actorType ?? 'mcp', actor_id: ctx?.actorId ?? null,
+        action: `mcp_connection.${event}`, resource_type: 'mcp_connection', resource_id: ctx?.oauthTokenId,
+        channel: ctx?.channel ?? 'mcp',
+        details: { connection_id: ctx?.oauthTokenId, approval_id: approvalId, tool: action, approver },
+    });
+    if (error)
+        throw new Error(`Failed to audit tester ${event}: ${error.message}`);
+}

package/build/lib/tester-request-snapshot.d.ts

@@ -0,0 +1,4 @@
+type Row = Record<string, any>;
+/** Setup targets and before values, frozen by the same hash and revalidation as sending approvals. */
+export declare function captureTesterRequestSnapshot(action: string, params: Row, projectId: string): Promise<Row>;
+export {};

package/build/lib/tester-request-snapshot.js

@@ -0,0 +1,46 @@
+import { readAllRows } from '@sendinel/domain';
+import { db, requestContext } from '../db.js';
+/** Setup targets and before values, frozen by the same hash and revalidation as sending approvals. */
+export async function captureTesterRequestSnapshot(action, params, projectId) {
+    const source = db();
+    const client = typeof source.schema === 'function' ? source.schema('email') : source;
+    const snapshot = { version: 1, tester_connection_id: requestContext()?.oauthTokenId,
+        campaigns: [], steps: [], sites: [], recipient_count: null };
+    let campaignId = params.campaign_id;
+    if (action === 'update_campaign_step') {
+        const { data, error } = await client.from('campaign_steps').select('*').eq('id', params.step_id).maybeSingle();
+        if (error || !data)
+            throw new Error('Approval step unavailable');
+        campaignId = data.campaign_id;
+    }
+    if (campaignId) {
+        const { data, error } = await client.from('campaigns')
+            .select('id, name, description, site_id, segment_id, type, status, topic, send_at, sends_per_hour, send_in_contact_timezone, send_class, requires_approval, unsub_footer_template, trigger_type, trigger_event_name, trigger_tag, trigger_config, updated_at')
+            .eq('id', campaignId).eq('project_id', projectId).maybeSingle();
+        if (error || !data)
+            throw new Error('Approval campaign unavailable');
+        snapshot.campaigns = [data];
+        snapshot.steps = await readAllRows(client.from('campaign_steps').select('*').eq('campaign_id', campaignId));
+        snapshot.steps.sort((a, b) => String(a.id).localeCompare(String(b.id)));
+        if (params.step_id && !snapshot.steps.some((step) => step.id === params.step_id))
+            throw new Error('Approval step unavailable');
+    }
+    const siteIds = [...new Set([params.site_id, ...snapshot.campaigns.map((campaign) => campaign.site_id)]
+            .filter((id) => typeof id === 'string'))].sort();
+    for (const siteId of siteIds) {
+        const { data, error } = await client.from('sites')
+            .select('id, name, from_name, from_email, sending_domain, physical_address, unsub_link_enabled, unsub_one_click_enabled, unsub_custom_url, unsub_footer_template, unsub_custom_message, unsub_brand_logo_url, unsub_brand_color, updated_at')
+            .eq('id', siteId).eq('project_id', projectId).maybeSingle();
+        if (error || !data)
+            throw new Error('Approval site unavailable');
+        snapshot.sites.push(data);
+    }
+    if (params.segment_id) {
+        const { data, error } = await client.from('segments').select('id, name, rules, site_id')
+            .eq('id', params.segment_id).eq('project_id', projectId).maybeSingle();
+        if (error || !data)
+            throw new Error('Approval segment unavailable');
+        snapshot.segment = data;
+    }
+    return snapshot;
+}

package/build/lib/tester-requests-store.d.ts

@@ -0,0 +1,2 @@
+/** Approval infrastructure stays central, including when update_site uses a BYOD client. */
+export declare function approvalStore(): any;

package/build/lib/tester-requests-store.js

@@ -0,0 +1,8 @@
+import { adminDb, db, requestContext } from '../db.js';
+/** Approval infrastructure stays central, including when update_site uses a BYOD client. */
+export function approvalStore() {
+    if (!requestContext()?.scopes?.includes('tester'))
+        return db();
+    const source = adminDb();
+    return typeof source.schema === 'function' ? source.schema('email') : source;
+}

package/build/lib/tester-requests.d.ts

@@ -0,0 +1,5 @@
+/** Only installed for an authenticated tester connection, never selected by tool arguments. */
+export declare function testerRequestTool(action: string, config: any, handler: (...args: any[]) => any): {
+    config: any;
+    handler: (input: Record<string, unknown>, extra?: unknown) => Promise<any>;
+};

package/build/lib/tester-requests.js

@@ -0,0 +1,71 @@
+import { isDeepStrictEqual } from 'node:util';
+import { z } from 'zod';
+import { requestContext, runWithApprovedTesterRequest } from '../db.js';
+import { getProjectId } from '../project.js';
+import { withApproval } from './action-approvals.js';
+import { withoutApprovalSnapshot } from './approval-snapshot.js';
+import { approvalStore } from './tester-requests-store.js';
+import { logTesterRequestAudit } from './tester-request-audit.js';
+import { TESTER_SITE_FIELDS } from './tester-policy.js';
+const text = (message) => ({ content: [{ type: 'text', text: message }] });
+/** Only installed for an authenticated tester connection, never selected by tool arguments. */
+export function testerRequestTool(action, config, handler) {
+    const original = z.object(config.inputSchema);
+    // Wrapping before optional prevents Zod defaults from populating an approval-id-only retry.
+    const inputSchema = Object.fromEntries(Object.entries(config.inputSchema).map(([key, schema]) => [key, z.preprocess(value => value, schema).optional()]));
+    inputSchema.approval_id = z.string().uuid().optional();
+    return {
+        config: { ...config, inputSchema },
+        handler: async (input, extra) => {
+            if (!requestContext()?.oauthTokenId)
+                return text('Tester setup requires an authenticated connection id.');
+            const { approval_id, ...supplied } = input;
+            let params;
+            if (approval_id) {
+                const { data, error } = await approvalStore().from('action_approvals').select('*')
+                    .eq('id', approval_id).eq('project_id', getProjectId()).maybeSingle();
+                if (error || !data || data.action !== action || data.oauth_token_id !== requestContext()?.oauthTokenId) {
+                    return text('Approval not found for this action and tester connection.');
+                }
+                params = withoutApprovalSnapshot(data.params);
+                for (const [key, value] of Object.entries(supplied)) {
+                    if (value !== undefined && !isDeepStrictEqual(value, params[key]))
+                        return text('params_mismatch: request differs from the frozen payload.');
+                }
+            }
+            else {
+                const parsed = original.safeParse(supplied);
+                if (!parsed.success)
+                    return text(`Invalid request: ${parsed.error.message}`);
+                params = parsed.data;
+                delete params.approval_id;
+                // This human approval replaces the compound tool's model confirmation preview.
+                if (action === 'create_campaign_with_content')
+                    params.confirmed = true;
+            }
+            if (action === 'update_site' && Object.keys(params).some(key => key !== 'site_id' && params[key] !== undefined && !TESTER_SITE_FIELDS.has(key))) {
+                return text('Tester connections may request only site footer and unsubscribe settings.');
+            }
+            return withApproval(action, async (frozen) => {
+                const result = await runWithApprovedTesterRequest(action, () => handler(frozen, extra));
+                // All seven setup tools report a successful apply as a resource id or an explicit ok.
+                let value;
+                try {
+                    value = JSON.parse(result.content.filter((block) => block.type === 'text')
+                        .map((block) => block.text).join('\n'));
+                }
+                catch {
+                    return result;
+                }
+                if (!result.isError && !value.error && (value.id || value.campaign_id || value.ok === true)) {
+                    const { data, error } = await approvalStore().from('action_approvals').select('decided_by')
+                        .eq('id', approval_id).eq('project_id', getProjectId()).maybeSingle();
+                    if (error || !data?.decided_by)
+                        throw new Error('Applied tester request has no recorded approver');
+                    await logTesterRequestAudit('tester_applied', action, String(approval_id), data.decided_by);
+                }
+                return result;
+            })({ ...params, approval_id: approval_id }, extra);
+        },
+    };
+}

package/build/server.d.ts

@@ -1,4 +1,5 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export { TESTER_REQUEST_TOOLS } from './lib/tester-policy.js';
 export interface ToolRegistrationOptions {
     scopes?: string[];
     toolGroups?: string[];
@@ -19,7 +20,7 @@ export declare function isAgentConnection(scopes: readonly string[] | null | und
 export declare function agentConnectionAllowsTool(name: string): boolean;
 export declare function agentConnectionRefusal(name: string): string;
 export declare function isTesterConnection(scopes: readonly string[] | null | undefined): boolean;
-/** Tools a tester connection may see and call: reads, plus anything that goes through a person's approval. */
+/** Tester reads, explicit setup requests and the existing campaign activation paths. */
 export declare function testerConnectionAllowsTool(name: string): boolean;
 /**
  * Tools whose own input already has a top-level `project_id` that means something other than "the project
@@ -31,7 +32,7 @@ export declare const PROJECT_ID_NATIVE_TOOLS: ReadonlySet<string>;
  * Tools that need a stated project when the connection is switched away from its home project (#4033):
  * anything that goes through a person's approval, plus the two always-gated actions.
  */
-export declare function isProjectPinnedWriteTool(name: string): boolean;
+export declare function isProjectPinnedWriteTool(name: string, scopes?: readonly string[]): boolean;
 export declare function testerConnectionRefusal(name: string): string;
 export declare const GATEWAY_TOOL_NAMES: string[];
 /**
@@ -46,4 +47,3 @@ export declare function getRegisteredToolGroups(options?: ToolRegistrationOption
  */
 export declare const SENDINEL_SERVER_INSTRUCTIONS: string;
 export declare function registerAllTools(server: McpServer, options?: ToolRegistrationOptions): void;
-export {};

package/build/server.js

@@ -2,6 +2,9 @@ import { installApprovalCapabilityProbe } from './lib/approval-capabilities.js';
 import { installApprovalApp } from './lib/approval-app.js';
 import { runWithApprovalElicitation } from './lib/approval-elicitation.js';
 import { runWithToolContext } from './db.js';
+import { TESTER_REQUEST_TOOLS } from './lib/tester-policy.js';
+import { testerRequestTool } from './lib/tester-requests.js';
+export { TESTER_REQUEST_TOOLS } from './lib/tester-policy.js';
 import { isApprovalGatedAction } from './lib/action-approvals.js';
 import { registerAgentMailboxTools } from './tools/agent-mailboxes.js';
 import { registerAnalyticsTools } from './tools/analytics.js';
@@ -203,14 +206,14 @@ export function agentConnectionRefusal(name) {
 export function isTesterConnection(scopes) {
     return !!scopes?.includes(TESTER_CONNECTION_SCOPE);
 }
-/** Tools a tester connection may see and call: reads, plus anything that goes through a person's approval. */
+/** Tester reads, explicit setup requests and the existing campaign activation paths. */
 export function testerConnectionAllowsTool(name) {
-    if (name === 'create_agent_mailbox')
-        return false;
+    // 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 === 'send_broadcast'
+        || TESTER_REQUEST_TOOLS.has(name)
         || name === 'activate_campaigns'
-        || isApprovalGatedAction(name);
+        || name === 'update_campaign_status';
 }
 /**
  * Tools whose own input already has a top-level `project_id` that means something other than "the project
@@ -222,11 +225,11 @@ export const PROJECT_ID_NATIVE_TOOLS = new Set(['set_active_project', 'get_outbo
  * Tools that need a stated project when the connection is switched away from its home project (#4033):
  * anything that goes through a person's approval, plus the two always-gated actions.
  */
-export function isProjectPinnedWriteTool(name) {
-    return name === 'send_broadcast' || name === 'activate_campaigns' || isApprovalGatedAction(name);
+export function isProjectPinnedWriteTool(name, scopes) {
+    return (isTesterConnection(scopes) && TESTER_REQUEST_TOOLS.has(name)) || name === 'send_broadcast' || name === 'activate_campaigns' || isApprovalGatedAction(name);
 }
 export function testerConnectionRefusal(name) {
-    return `"${name}" is not available to a tester connection. A tester connection can read, and can ask a person to approve outward actions: call an approval-gated tool (for example send_broadcast) and a person approves it from the approve_url it returns. To change this tool directly, ask the workspace owner to promote the connection in Dashboard > Agent Connect.`;
+    return `"${name}" is not available to a tester connection. Testers can read and request human approval for campaign setup: ${[...TESTER_REQUEST_TOOLS].join(', ')}. update_site is limited to footer/unsubscribe fields. Every setup call returns approval_id, approve_url and preview_text; after a person approves, retry with only approval_id. Deletes, sends, access/role/key/team tools, provider credentials, imports and create_agent_mailbox are refused. Ask the workspace owner to promote the connection in Dashboard > Agent Connect for direct writes.`;
 }
 // Names of the meta-tools gateway mode registers in place of the real catalog
 // (see tools/gateway.ts). Grouped as 'gateway' rather than any real tool
@@ -350,13 +353,18 @@ function createScopeProxy(server, scopes, toolGroup, allowedTools) {
                             // Don't register tools the key can't access — they won't appear in tool list
                             return;
                         }
+                        if (tester && !agent && TESTER_REQUEST_TOOLS.has(name)) {
+                            const wrapped = testerRequestTool(name, config, handler);
+                            config = wrapped.config;
+                            handler = wrapped.handler;
+                        }
                         // Wrap handler with runtime scope check (defense in depth)
                         const guardedHandler = (...args) => {
                             if (!allowed()) {
                                 const text = agent ? agentConnectionRefusal(name) : tester ? testerConnectionRefusal(name) : `Forbidden: this action requires "${required}" scope.`;
                                 return { content: [{ type: 'text', text }] };
                             }
-                            return runWithToolContext(toolGroup, name, () => runWithApprovalElicitation(target, args[1], () => handler(...args)));
+                            return runWithToolContext(toolGroup, name, () => runWithApprovalElicitation(target, args[1], () => handler(...args)), scopes);
                         };
                         return target.registerTool(name, config, guardedHandler);
                     }
@@ -382,7 +390,8 @@ export const SENDINEL_SERVER_INSTRUCTIONS = [
 export function registerAllTools(server, options) {
     if (server.server)
         installApprovalCapabilityProbe(server.server);
-    server = installApprovalApp(server, options, isApprovalGatedAction);
+    // Registry callers pass scopes only: the hosted decision bridge is never enabled from a catalog.
+    server = installApprovalApp(server, { scopes: options?.scopes }, isApprovalGatedAction);
     const rawScopes = options?.scopes ?? [];
     if (rawScopes.includes('gateway')) {
         const permissionScopes = rawScopes.filter((scope) => scope !== 'gateway');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sendinel/mcp-server",
-  "version": "1.0.109",
+  "version": "1.0.111",
   "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",