@sendinel/mcp-server 1.0.108 → 1.0.110

package/build/lib/action-approvals.js

@@ -366,8 +366,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,

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

@@ -2,7 +2,7 @@ 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 { 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';

package/build/server.js

@@ -382,7 +382,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/build/tools/sites.js

@@ -1,4 +1,6 @@
 import { z } from 'zod';
+import { validateSiteUnsubscribeSettings } from '@sendinel/domain';
+import { logAudit } from '../audit.js';
 import { db } from '../db.js';
 import { getProjectId } from '../project.js';
 import { checkPlanLimit } from '../plan-limits.js';
@@ -112,14 +114,14 @@ export function registerSiteTools(server) {
             idempotentHint: true,
             openWorldHint: false,
         },
-        description: 'Read the brand voice configuration for a sender/site.',
+        description: 'Read the brand voice configuration and current site-wide footer, unsubscribe link settings, unsubscribe text, and physical mailing address for a sender/site.',
         inputSchema: {
             site_id: z.string().uuid(),
         },
     }, async ({ site_id }) => {
         const { data, error } = await db()
             .from('sites')
-            .select('id, name, brand_voice')
+            .select('id, name, brand_voice, 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')
             .eq('project_id', getProjectId())
             .eq('id', site_id)
             .maybeSingle();
@@ -184,15 +186,23 @@ export function registerSiteTools(server) {
             idempotentHint: true,
             openWorldHint: false,
         },
-        description: 'Update a site name, from address, or other settings',
+        description: 'Update site-wide email footer, unsubscribe text, unsubscribe link, one-click unsubscribe, unsubscribe page branding, sender name/from address, active status, or physical mailing address. unsub_footer_template must be non-empty and include <unsubscribe>link text</unsubscribe>. Omitted settings and physical_address stay unchanged. Returns stored settings and previous_unsub_footer_template when the footer changes, so callers can undo.',
         inputSchema: {
             site_id: z.string().uuid(),
             name: z.string().optional(),
             from_email: z.string().email().optional(),
             from_name: z.string().optional(),
             active: z.boolean().optional(),
+            physical_address: z.string().trim().min(1).optional().describe('Physical mailing address; unchanged unless explicitly supplied.'),
+            unsub_link_enabled: z.boolean().optional().describe('Enable the unsubscribe link in the email footer.'),
+            unsub_one_click_enabled: z.boolean().optional().describe('Enable one-click unsubscribe headers.'),
+            unsub_custom_url: z.string().nullable().optional().describe('HTTP(S) unsubscribe URL; null or blank clears it.'),
+            unsub_footer_template: z.string().nullable().optional().describe('Non-empty site-wide footer including <unsubscribe>link text</unsubscribe>.'),
+            unsub_custom_message: z.string().nullable().optional().describe('Unsubscribe page message, up to 280 characters; null or blank clears it.'),
+            unsub_brand_logo_url: z.string().nullable().optional().describe('HTTP(S) unsubscribe page logo URL; null or blank clears it.'),
+            unsub_brand_color: z.string().nullable().optional().describe('Six-digit hex unsubscribe page color; null or blank clears it.'),
         },
-    }, async ({ site_id, name, from_email, from_name, active }) => {
+    }, async ({ site_id, name, from_email, from_name, active, physical_address, ...unsubscribeInput }) => {
         const updates = {};
         if (name)
             updates.name = name;
@@ -202,18 +212,54 @@ export function registerSiteTools(server) {
             updates.from_name = from_name;
         if (active !== undefined)
             updates.active = active;
+        if (physical_address !== undefined)
+            updates.physical_address = physical_address.trim().slice(0, 500);
+        const unsubscribe = validateSiteUnsubscribeSettings(unsubscribeInput);
+        if (!unsubscribe.ok)
+            return txt(`Error: ${unsubscribe.error}`);
+        Object.assign(updates, unsubscribe.value);
         if (!Object.keys(updates).length)
             return txt('No fields to update.');
+        // Read only when a footer is supplied, and guard the write so the undo value is exact.
+        const sb = db();
+        const projectId = getProjectId();
+        let previousTemplate;
+        if (updates.unsub_footer_template !== undefined) {
+            const { data: current, error } = await sb
+                .from('sites')
+                .select('unsub_footer_template')
+                .eq('id', site_id)
+                .eq('project_id', projectId)
+                .maybeSingle();
+            if (error)
+                return txt(`Error: ${error.message}`);
+            if (!current)
+                return j({ error: 'Site not found', code: 'NOT_FOUND' });
+            previousTemplate = current.unsub_footer_template;
+        }
         updates.updated_at = new Date().toISOString();
-        const { data, error } = await db()
+        let query = sb
             .from('sites')
             .update(updates)
             .eq('id', site_id)
-            .eq('project_id', getProjectId())
-            .select()
-            .single();
+            .eq('project_id', projectId);
+        if (previousTemplate === null)
+            query = query.is('unsub_footer_template', null);
+        else if (previousTemplate !== undefined)
+            query = query.eq('unsub_footer_template', previousTemplate);
+        const { data, error } = await query.select().maybeSingle();
         if (error)
             return txt(`Error: ${error.message}`);
-        return j(data);
+        if (!data)
+            return j({ error: 'Site not found or footer changed during update. Read the site and retry.', code: 'SITE_CHANGED_OR_NOT_FOUND' });
+        await logAudit({
+            action: 'site.updated', resourceType: 'site', resourceId: site_id,
+            details: { fields: Object.keys(updates).filter((field) => field !== 'updated_at') },
+        });
+        return j({
+            ...data,
+            ...(previousTemplate !== undefined && previousTemplate !== data.unsub_footer_template
+                ? { previous_unsub_footer_template: previousTemplate } : {}),
+        });
     });
 }

package/build/tools/tool-search.js

@@ -12,6 +12,7 @@ export const STOPWORDS = new Set([
  * Only tools that exist in the registry belong here.
  */
 export const TOOL_ALIASES = {
+    update_site: ['footer', 'email footer', 'unsubscribe text', 'unsubscribe link', 'site footer', 'unsubscribe settings'],
     set_campaign_trigger: ['trigger', 'event', 'fires on', 'fires-on', 'dunning', 'set campaign trigger event name', 'invoice payment failed', 'trial ending'],
     send_broadcast: [
         'send email', 'send an email', 'email blast', 'blast', 'newsletter', 'announce', 'announcement', 'one-off email',

package/package.json

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