From cc3649d4b85b26f565ce81270aec3d7831a97fe7 Mon Sep 17 00:00:00 2001
From: Leah Xia <107075081+Leah-Xia-Microsoft@users.noreply.github.com>
Date: Tue, 14 Jul 2026 15:40:41 -0700
Subject: [PATCH] Add ClipboardRead device permission foundations (P0)

Additive P0 groundwork for the updated clipboard-read architecture
(ADO Feature 11070811 / Task 12061800). No behavior change.

- interfaces.ts: add DevicePermission.ClipboardRead = 'clipboard-read'
  (value matches the browser Permissions-Policy token so hosts can use it
  verbatim in the app iframe allow attribute)
- telemetry.ts: add Clipboard_HasPermission / Clipboard_RequestPermission
- runtime.ts: add clipboard.native capability marker (v4) so old hosts fall
  back cleanly to the legacy proxied clipboard path

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: ee7bfe63-ba23-4db3-ba82-960182852055
---
 ...t-teams-js-clipboard-read-device-permission-p0.json |  7 +++++++
 packages/teams-js/src/internal/telemetry.ts            |  2 ++
 packages/teams-js/src/public/interfaces.ts             |  1 +
 packages/teams-js/src/public/runtime.ts                | 10 +++++++++-
 4 files changed, 19 insertions(+), 1 deletion(-)
 create mode 100644 change/@microsoft-teams-js-clipboard-read-device-permission-p0.json

diff --git a/change/@microsoft-teams-js-clipboard-read-device-permission-p0.json b/change/@microsoft-teams-js-clipboard-read-device-permission-p0.json
new file mode 100644
index 0000000000..99a7cbba9d
--- /dev/null
+++ b/change/@microsoft-teams-js-clipboard-read-device-permission-p0.json
@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "Add `DevicePermission.ClipboardRead` and clipboard permission telemetry/runtime foundations for the updated clipboard-read architecture (P0, additive; no behavior change)",
+  "packageName": "@microsoft/teams-js",
+  "email": "leahxia@microsoft.com",
+  "dependentChangeType": "patch"
+}
diff --git a/packages/teams-js/src/internal/telemetry.ts b/packages/teams-js/src/internal/telemetry.ts
index a8c21875dc..04f250fd93 100644
--- a/packages/teams-js/src/internal/telemetry.ts
+++ b/packages/teams-js/src/internal/telemetry.ts
@@ -105,6 +105,8 @@ export const enum ApiName {
   Chat_OpenGroupChat = 'chat.openGroupChat',
   Clipboard_Read = 'clipboard.read',
   Clipboard_Write = 'clipboard.write',
+  Clipboard_HasPermission = 'clipboard.hasPermission',
+  Clipboard_RequestPermission = 'clipboard.requestPermission',
   Conversations_CloseConversation = 'conversations.closeConversation',
   Conversations_GetChatMember = 'conversations.getChatMember',
   Conversations_OpenConversation = 'conversations.openConversation',
diff --git a/packages/teams-js/src/public/interfaces.ts b/packages/teams-js/src/public/interfaces.ts
index 0b87b13265..4b59caff99 100644
--- a/packages/teams-js/src/public/interfaces.ts
+++ b/packages/teams-js/src/public/interfaces.ts
@@ -1161,6 +1161,7 @@ export enum ErrorCode {
 export enum DevicePermission {
   GeoLocation = 'geolocation',
   Media = 'media',
+  ClipboardRead = 'clipboard-read',
 }
 
 /** @hidden */
diff --git a/packages/teams-js/src/public/runtime.ts b/packages/teams-js/src/public/runtime.ts
index b258e58619..eeee1efb51 100644
--- a/packages/teams-js/src/public/runtime.ts
+++ b/packages/teams-js/src/public/runtime.ts
@@ -235,7 +235,15 @@ interface IRuntimeV4 extends IBaseRuntime {
     readonly calendar?: {};
     readonly call?: {};
     readonly chat?: {};
-    readonly clipboard?: {};
+    readonly clipboard?: {
+      /**
+       * When present, the host supports reading the clipboard natively in the app
+       * frame (via `navigator.clipboard`) gated by the `clipboard-read` device
+       * permission, instead of the legacy host-proxied `clipboard.readFromClipboard`
+       * path. Absent on older hosts, which fall back to the proxied path.
+       */
+      readonly native?: {};
+    };
     readonly conversations?: {};
     readonly copilot?: {
       readonly customTelemetry?: {};