Add linkTrustedDomains view property

docs/migrate_from_openai_apps.md

@@ -53,13 +53,13 @@ The server-side changes involve updating metadata structure and using helper fun
 
 ### CSP Field Mapping
 
-| OpenAI | MCP Apps | Notes |
-| ------------------ | ----------------- | ---------------------------------------------------------- |
-| `resource_domains` | `resourceDomains` | Origins for static assets (images, fonts, styles, scripts) |
-| `connect_domains` | `connectDomains` | Origins for fetch/XHR/WebSocket requests |
-| `frame_domains` | `frameDomains` | Origins for nested iframes |
-| `redirect_domains` | — | OpenAI-only: origins for `openExternal` redirects  |
-| — | `baseUriDomains` | MCP-only: `base-uri` CSP directive |
+| OpenAI | MCP Apps | Notes |
+| ------------------ | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `resource_domains` | `resourceDomains` | Origins for static assets (images, fonts, styles, scripts) |
+| `connect_domains` | `connectDomains` | Origins for fetch/XHR/WebSocket requests |
+| `frame_domains` | `frameDomains` | Origins for nested iframes |
+| `redirect_domains` | `_meta.ui.linkTrustedDomains` | Origins `ui/open-link` may skip confirmation for. Note: this lives on `_meta.ui`, a sibling of `_meta.ui.csp`, not inside the CSP object. |
+| — | `baseUriDomains` | MCP-only: `base-uri` CSP directive |
 
 ### Server-Side Migration Example
 
@@ -255,9 +255,10 @@ Client-side migration involves replacing the implicit `window.openai` global wit
 
 ### External Links
 
-| OpenAI | MCP Apps | Notes |
-| -------------------------------------------- | ----------------------------------- | ------------------------------------ |
-| `await window.openai.openExternal({ href })` | `await app.openLink({ url: href })` | Different param name: `href` → `url` |
+| OpenAI | MCP Apps | Notes |
+| -------------------------------------------- | ----------------------------------- | ---------------------------------------------------------------------------- |
+| `await window.openai.openExternal({ href })` | `await app.openLink({ url: href })` | Different param name: `href` → `url` |
+| `_meta["openai/widgetCSP"].redirect_domains` | `_meta.ui.linkTrustedDomains` | Origins that skip the host's link confirmation. Declared on the UI resource. |
 
 ### Display Mode
 

examples/basic-host/package.json

@@ -19,7 +19,7 @@
  },
  "devDependencies": {
  "@types/express": "^5.0.0",
- "@types/node": "22.10.0",
+ "@types/node": "24.13.2",
  "@types/react": "^19.2.2",
  "@types/react-dom": "^19.2.2",
  "@vitejs/plugin-react": "^4.3.4",

examples/basic-host/src/implementation.ts

@@ -72,6 +72,7 @@ interface UiResourceData {
  html: string;
  csp?: McpUiResourceCsp;
  permissions?: McpUiResourcePermissions;
+ linkTrustedDomains?: string[];
 }
 
 export interface ToolCallInfo {
@@ -151,8 +152,9 @@ async function getUiResource(serverInfo: ServerInfo, uri: string): Promise<UiRes
  const uiMeta = contentMeta?.ui ?? listingMeta?.ui;
  const csp = uiMeta?.csp;
  const permissions = uiMeta?.permissions;
+ const linkTrustedDomains = uiMeta?.linkTrustedDomains;
 
- return { html, csp, permissions };
+ return { html, csp, permissions, linkTrustedDomains };
 }
 
 
@@ -271,6 +273,7 @@ export interface AppBridgeCallbacks {
 export interface AppBridgeOptions {
  containerDimensions?: { maxHeight?: number; width?: number } | { height: number; width?: number };
  displayMode?: "inline" | "fullscreen";
+ linkTrustedDomains?: string[];
 }
 
 export function newAppBridge(
@@ -340,8 +343,32 @@ export function newAppBridge(
 
  appBridge.onopenlink = async (params, _extra) => {
  log.info("Open link request:", params);
- window.open(params.url, "_blank", "noopener,noreferrer");
- return {};
+
+ let url: URL;
+ try {
+ url = new URL(params.url);
+ } catch {
+ log.warn("Invalid URL:", params.url);
+ return { isError: true };
+ }
+
+ const HOST_OPENLINK_DENYLIST = [new URL("https://malicious.com")];
+ if (HOST_OPENLINK_DENYLIST.some(({ origin }) => origin === url.origin)) {
+ log.info("Blocked link by host denylist:", params.url);
+ return { isError: true };
+ }
+
+ const isTrustedByApp = options?.linkTrustedDomains?.some((trustedDomain) =>
+ new URLPattern(trustedDomain).test(url)
+ );
+ const shouldOpen = isTrustedByApp || window.confirm(`Open external link?\n${url}`);
+ if (shouldOpen) {
+ window.open(url, "_blank", "noopener,noreferrer");
+ return {};
+ }
+
+ log.info("User declined to open link:", url);
+ return { isError: true };
  };
 
  appBridge.onloggingmessage = (params) => {

examples/basic-host/src/index.tsx

@@ -434,7 +434,7 @@ function AppIFramePanel({ toolCallInfo, isDestroying, onTeardownComplete }: AppI
 
  // First get CSP and permissions from resource, then load sandbox
  // CSP is set via HTTP headers (tamper-proof), permissions via iframe allow attribute
- toolCallInfo.appResourcePromise.then(({ csp, permissions }) => {
+ toolCallInfo.appResourcePromise.then(({ csp, permissions, linkTrustedDomains }) => {
  loadSandboxProxy(iframe, csp, permissions).then((firstTime) => {
  // The `firstTime` check guards against React Strict Mode's double
  // invocation (mount → unmount → remount simulation in development).
@@ -449,6 +449,7 @@ function AppIFramePanel({ toolCallInfo, isDestroying, onTeardownComplete }: AppI
  // Provide container dimensions - maxHeight for flexible sizing
  containerDimensions: { maxHeight: 6000 },
  displayMode: "inline",
+ linkTrustedDomains,
  });
  appBridgeRef.current = appBridge;
  initializeApp(iframe, appBridge, toolCallInfo);

package.json

@@ -124,8 +124,7 @@
  "overrides": {
  "seroval": "1.4.1",
  "seroval-plugins": "1.4.2",
- "solid-js": "1.9.10",
- "@types/node": "20.19.27"
+ "solid-js": "1.9.10"
  },
  "dependencies": {
  "@standard-schema/spec": "^1.1.0"

specification/draft/apps.mdx

@@ -225,6 +225,26 @@ interface UIResourceMeta {
  * - omitted: host decides border
  */
  prefersBorder?: boolean,
+ /**
+ * Origins the view is expecting to open via `ui/open-link`
+ *
+ * Servers declare external destinations the view legitimately links to (for
+ * example its own marketing site). Hosts MAY use this list to skip the link
+ * confirmation prompt for matching destinations.
+ *
+ * - Each entry is an origin (scheme + host[:port]); a leading `*.` is a
+ * subdomain wildcard, matching the rules used for `csp` domain fields.
+ * - Empty or omitted = every `ui/open-link` is subject to the host's
+ * default policy (typically a confirmation prompt).
+ *
+ * This is a UX hint, NOT an authorization mechanism. Hosts retain full
+ * authority, MUST still apply their own allowlist/blocklist, and SHOULD NOT
+ * treat a declared origin as proof that a destination is safe.
+ *
+ * @example
+ * ["https://example.com", "https://*.example.com"]
+ */
+ linkTrustedDomains?: string[],
 }
 ```
 
@@ -254,6 +274,7 @@ The resource content is returned via `resources/read`:
  };
  domain?: string;
  prefersBorder?: boolean;
+ linkTrustedDomains?: string[]; // Origins ui/open-link may skip confirmation for.
  };
  };
  }];
@@ -262,7 +283,7 @@ The resource content is returned via `resources/read`:
 
 #### Metadata Location
 
-`UIResourceMeta` (CSP, permissions, domain, prefersBorder) may be provided on either or both:
+`UIResourceMeta` (CSP, permissions, domain, prefersBorder, linkTrustedDomains) may be provided on either or both:
 
 - **`resources/list`:** On the resource entry's `_meta.ui` field. Useful as a static default that hosts can review at connection time.
 - **`resources/read`:** On each content item's `_meta.ui` field. Useful for per-response overrides or dynamic metadata that is only known at read time.
@@ -1039,6 +1060,23 @@ MCP Apps introduces additional JSON-RPC methods for UI-specific functionality:
 
 Host SHOULD open the URL in the user's default browser or a new tab.
 
+By default, hosts SHOULD guard `ui/open-link` against unexpected navigation —
+for example by showing a confirmation prompt — since the URL originates from
+sandboxed UI content.
+
+**Trusted destinations (`linkTrustedDomains`).** A server MAY declare origins it
+legitimately links to via the resource's `_meta.ui.linkTrustedDomains` (see
+[UI Resource Format](#ui-resource-format)). For a `ui/open-link` whose URL
+matches one of those origins, the host MAY **skip the confirmation prompt** and
+open the link directly.
+
+Matching uses the same origin rules as `csp` domain fields: an entry is an
+origin (scheme + host[:port]) and a leading `*.` is a subdomain wildcard.
+
+> **Security:** `linkTrustedDomains` is a UX hint, not an authorization
+> mechanism. Because the value comes from the (untrusted) server, hosts MUST
+> still enforce their own allowlist/blocklist and MAY confirm regardless.
+
 `ui/download-file` - Request host to download a file
 
 ```typescript

src/app-bridge.examples.ts

@@ -159,6 +159,12 @@ declare const chatManager: {
 // Stub for example code - represents a hypothetical URL validator
 declare function isAllowedDomain(url: string): boolean;
 
+// Stub for example code - represents the URL Pattern tester
+declare function matchesLinkTrustedDomains(
+ url: string,
+ linkTrustedDomains: string[] | undefined,
+): boolean;
+
 // Stub for example code - represents a hypothetical dialog API
 declare function showDialog(options: {
  message: string;
@@ -173,14 +179,25 @@ declare const modelContextManager: {
 /**
  * Example: Handle external link requests from the View.
  */
-function AppBridge_onopenlink_handleRequest(bridge: AppBridge) {
+function AppBridge_onopenlink_handleRequest(
+ bridge: AppBridge,
+ // Origins declared by the resource via `_meta.ui.linkTrustedDomains`.
+ linkTrustedDomains: string[] | undefined,
+) {
  //#region AppBridge_onopenlink_handleRequest
  bridge.onopenlink = async ({ url }, extra) => {
+ // The host's own policy always wins, regardless of server-declared trust.
  if (!isAllowedDomain(url)) {
  console.warn("Blocked external link:", url);
  return { isError: true };
  }
 
+ // Destinations the server declared as trusted skip the confirmation prompt.
+ if (matchesLinkTrustedDomains(url, linkTrustedDomains)) {
+ window.open(url, "_blank", "noopener,noreferrer");
+ return {};
+ }
+
  const confirmed = await showDialog({
  message: `Open external link?\n${url}`,
  buttons: ["Open", "Cancel"],

src/app-bridge.ts

@@ -670,6 +670,7 @@ export class AppBridge extends ProtocolWithEvents<
  *
  * The host MAY:
  * - Show a confirmation dialog before opening
+ * - Consider skipping user confirmation
  * - Block URLs based on a security policy or allowlist
  * - Log the request for audit purposes
  * - Reject the request entirely
@@ -682,11 +683,18 @@ export class AppBridge extends ProtocolWithEvents<
  * @example
  * ```ts source="./app-bridge.examples.ts#AppBridge_onopenlink_handleRequest"
  * bridge.onopenlink = async ({ url }, extra) => {
+ * // The host's own policy always wins, regardless of server-declared trust.
  * if (!isAllowedDomain(url)) {
  * console.warn("Blocked external link:", url);
  * return { isError: true };
  * }
  *
+ * // Destinations the server declared as trusted skip the confirmation prompt.
+ * if (matchesLinkTrustedDomains(url, linkTrustedDomains)) {
+ * window.open(url, "_blank", "noopener,noreferrer");
+ * return {};
+ * }
+ *
  * const confirmed = await showDialog({
  * message: `Open external link?\n${url}`,
  * buttons: ["Open", "Cancel"],

src/spec.types.ts

@@ -728,6 +728,35 @@ export interface McpUiResourceMeta {
  * - omitted: host decides border
  */
  prefersBorder?: boolean;
+ /**
+ * @description Origins the view is expecting to open via `ui/open-link`.
+ *
+ * Servers declare external destinations the view legitimately links to (for
+ * example its own marketing site). Hosts MAY use this list to **skip the link
+ * confirmation prompt** for matching destinations, instead of confirming every
+ * `ui/open-link`.
+ *
+ * Matching follows the same origin rules as {@link McpUiResourceCsp} fields:
+ * an entry is an origin (scheme + host[:port]) and wildcard subdomains are
+ * supported (e.g. `https://*.example.com`).
+ *
+ * > [!IMPORTANT]
+ * > This is a **UX hint, not an authorization mechanism.** It only relaxes
+ * > confirmation for the declared origins; it does not grant the view any
+ * > capability. Hosts retain full authority and MUST still apply their own
+ * > global allowlist/blocklist and MAY confirm regardless. Because the value
+ * > comes from the server, hosts SHOULD NOT treat it as proof that a
+ * > destination is safe.
+ *
+ * - Empty or omitted → every `ui/open-link` is subject to the host's default
+ * policy (typically a confirmation prompt).
+ *
+ * @example
+ * ```ts
+ * ["https://example.com", "https://*.example.com"]
+ * ```
+ */
+ linkTrustedDomains?: string[];
 }
 
 /**