[Node] Let Extensions Request Sensitive Environment Variables (#2348)

* [Node] Let Extensions Request Sensitive Environment Variables

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* - Add E2E coverage for the extension environment request
- Fix the factory join-path assertion broken by the new argument
- Pass extension join options only when an extension asks for variables

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* - Treat an empty env list as no environment request
- Apply only approved names from a grant
- Match the docs heading style in the extensions guide

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* Keep the client type imports in order

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* Rename the extension join option to requestedEnvironmentVariables

`env` means a map of values to supply to a process everywhere else in
this SDK, so a list of names the extension asks for needs its own name.
The new name also matches the wire field exactly.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: MRayermannMSFT

CHANGELOG.md

@@ -7,6 +7,21 @@ See [GitHub Releases](https://github.com/github/copilot-sdk/releases) for the fu
 
 ## [Unreleased]
 
+### Feature: extensions can request sensitive environment variables
+
+Copilot CLI extensions can now ask for named sensitive environment variables when they join a session. `joinSession()` accepts a `requestedEnvironmentVariables` option listing the variable names the extension needs. The CLI shows a permission prompt naming the extension and the exact variables requested. On approval, only those variables reach that extension and their values are written into the extension process's `process.env` before `joinSession()` resolves. On denial, `joinSession()` rejects, the extension does not load, and its tools never reach the model.
+
+An approval is remembered against the exact set of names the user saw, so an extension that later asks for one more variable prompts again. Names that are unset, or that the CLI does not filter from extensions, are not prompted for. This is the client half of the feature; it requires a Copilot CLI that supports extension environment access, and older CLIs ignore the request and grant nothing.
+
+```ts
+import { joinSession } from "@github/copilot-sdk/extension";
+
+const session = await joinSession({
+    requestedEnvironmentVariables: ["GITHUB_TOKEN"],
+});
+const token = process.env.GITHUB_TOKEN;
+```
+
 ### Feature: host-injected managed settings permissions
 
 Session create and resume accept a new optional `managedSettings` option that injects an enterprise permissions policy at session startup, alongside the existing `enableManagedSettings` self-fetch flag. The current contract is permissions-only: `disableBypassPermissionsMode` (the literal `"disable"`), plus `deny`, `ask`, and `allow` rule lists. The layer composes restrictively with any server- or device-level managed settings (deny/ask are unioned, every present allow list must admit a tool, and `disableBypassPermissionsMode` is deny-wins).

nodejs/docs/extensions.md

@@ -53,6 +53,27 @@ const session = await joinSession({
 
 The `session` object provides methods for sending messages, logging to the timeline, listening to events, and accessing the RPC API. See the `.d.ts` files in the SDK package for full type information.
 
+## Requesting Sensitive Environment Variables
+
+The CLI strips sensitive environment variables (for example `GITHUB_TOKEN`) from every extension process before it starts. An extension that needs one asks for it by name:
+
+```js
+import { joinSession } from "@github/copilot-sdk/extension";
+
+const session = await joinSession({
+    requestedEnvironmentVariables: ["GITHUB_TOKEN"],
+});
+
+// Granted values are in process.env once joinSession resolves.
+const token = process.env.GITHUB_TOKEN;
+```
+
+The CLI prompts the user with the extension's name and the exact list of variables requested. If the user approves, only those variables reach this extension and their values are written into `process.env` before `joinSession()` resolves. If the user denies, `joinSession()` rejects, the extension does not load, and its tools never reach the model.
+
+An approval is remembered against the exact set of names the user saw, so an extension that later asks for an additional variable prompts again. Names that are unset, or that the CLI does not filter from extensions, are not prompted for.
+
+An approved extension can pass a granted value to anything it starts, so ask only for what the extension genuinely needs.
+
 ## Further Reading
 
 - `examples.md` — Practical code examples for tools, hooks, events, and complete extensions

nodejs/src/client.ts

@@ -54,6 +54,7 @@ import type {
     CustomAgentConfig,
     ExitPlanModeRequest,
     ExitPlanModeResult,
+    ExtensionJoinOptions,
     ForegroundSessionInfo,
     GetAuthStatusResponse,
     BearerTokenProvider,
@@ -1711,15 +1712,17 @@ export class CopilotClient {
     async resumeSessionForExtension(
         sessionId: string,
         config: ResumeSessionConfig,
-        factories?: FactoryHandle[]
+        factories?: FactoryHandle[],
+        extensionOptions?: ExtensionJoinOptions
     ): Promise<CopilotSession> {
-        return this.resumeSessionInternal(sessionId, config, factories);
+        return this.resumeSessionInternal(sessionId, config, factories, extensionOptions);
     }
 
     private async resumeSessionInternal(
         sessionId: string,
         config: ResumeSessionConfig,
-        factories?: FactoryHandle[]
+        factories?: FactoryHandle[],
+        extensionOptions?: ExtensionJoinOptions
     ): Promise<CopilotSession> {
         if (!this.connection) {
             await this.start();
@@ -1884,8 +1887,31 @@ export class CopilotClient {
                 expAssignments: config.expAssignments,
                 enableManagedSettings: config.enableManagedSettings,
                 managedSettings: config.managedSettings,
+                ...(extensionOptions?.requestedEnvironmentVariables
+                    ? {
+                          requestedEnvironmentVariables:
+                              extensionOptions.requestedEnvironmentVariables,
+                      }
+                    : {}),
             });
 
+            // The host answers an approved environment request with the resolved
+            // values, and this method consumes the response, so the grant has to be
+            // applied here — no caller ever sees it. Only the names the user
+            // approved may reach the extension, so a host that answers with
+            // anything extra cannot widen the grant.
+            if (extensionOptions?.requestedEnvironmentVariables) {
+                const requested = new Set(extensionOptions.requestedEnvironmentVariables);
+                const { grantedEnvironmentVariables } = response as {
+                    grantedEnvironmentVariables?: Record<string, string>;
+                };
+                for (const [name, value] of Object.entries(grantedEnvironmentVariables ?? {})) {
+                    if (requested.has(name)) {
+                        process.env[name] = value;
+                    }
+                }
+            }
+
             const { workspacePath, capabilities, openCanvases } = response as {
                 sessionId: string;
                 workspacePath?: string;

nodejs/src/extension.ts

@@ -27,6 +27,35 @@ export type JoinSessionConfig = Omit<
     "onPermissionRequest" | "extensionSdkPath"
 > & {
     onPermissionRequest?: PermissionHandler;
+    /**
+     * Names of sensitive environment variables this extension needs, such as
+     * `"GITHUB_TOKEN"`.
+     *
+     * The Copilot CLI strips sensitive variables from every extension process
+     * before it starts, so an extension that needs one must ask for it by name.
+     * The CLI prompts the user with the extension's name and the exact list of
+     * variables requested. On approval the granted values are written into this
+     * process's `process.env` before {@link joinSession} resolves, so they are
+     * readable afterwards. On denial the join rejects and the extension does not
+     * load, so its tools never reach the model.
+     *
+     * An approval is remembered against the exact set of names the user saw, so
+     * asking for an additional variable later prompts again. Names that are unset
+     * or that the CLI does not filter from extensions are not prompted for. An
+     * empty list means the same as omitting the option: nothing is requested.
+     *
+     * Requires a Copilot CLI that supports extension environment access; older
+     * CLIs ignore the request and grant nothing.
+     *
+     * @example
+     * ```typescript
+     * const session = await joinSession({
+     *     requestedEnvironmentVariables: ["GITHUB_TOKEN"],
+     * });
+     * const token = process.env.GITHUB_TOKEN;
+     * ```
+     */
+    requestedEnvironmentVariables?: string[];
     /**
      * Factory handles to register when the extension joins the session.
      *
@@ -94,6 +123,7 @@ export async function joinSession(config: JoinSessionConfig = {}): Promise<Copil
     const {
         extensionSdkPath: _stripped,
         factories,
+        requestedEnvironmentVariables,
         ...rest
     } = config as JoinSessionConfig & {
         extensionSdkPath?: string;
@@ -107,6 +137,7 @@ export async function joinSession(config: JoinSessionConfig = {}): Promise<Copil
             onPermissionRequest: config.onPermissionRequest ?? defaultJoinSessionPermissionHandler,
             suppressResumeEvent: config.suppressResumeEvent ?? true,
         },
-        factories
+        factories,
+        requestedEnvironmentVariables?.length ? { requestedEnvironmentVariables } : undefined
     );
 }

nodejs/src/types.ts

@@ -2879,6 +2879,20 @@ export interface ResumeSessionConfig extends SessionConfigBase {
     openCanvases?: OpenCanvasInstance[];
 }
 
+/**
+ * Options that only an extension join may supply, kept off {@link ResumeSessionConfig}
+ * because the runtime ignores them for every other kind of connection.
+ *
+ * @internal
+ */
+export interface ExtensionJoinOptions {
+    /**
+     * Names of sensitive environment variables the extension asks the host to grant.
+     * Sent on the `session.resume` wire payload as `requestedEnvironmentVariables`.
+     */
+    requestedEnvironmentVariables?: string[];
+}
+
 /**
  * Arguments passed to a {@link BearerTokenProvider} callback when the runtime needs a
  * fresh bearer token for a BYOK provider.

nodejs/test/client.test.ts

@@ -622,6 +622,99 @@ describe("CopilotClient", () => {
         expect(payload.openCanvasInstances).toBeUndefined();
     });
 
+    it("forwards an extension environment request and applies the grant to process.env", async () => {
+        const client = new CopilotClient();
+        await client.start();
+        onTestFinished(() => stopClient(client));
+        onTestFinished(() => {
+            delete process.env.SDK_TEST_GRANTED_TOKEN;
+        });
+
+        const spy = vi
+            .spyOn((client as any).connection!, "sendRequest")
+            .mockImplementation(async (method: string, params: any) => {
+                if (method === "session.resume") {
+                    return {
+                        sessionId: params.sessionId,
+                        grantedEnvironmentVariables: { SDK_TEST_GRANTED_TOKEN: "granted-value" },
+                    };
+                }
+                throw new Error(`Unexpected method: ${method}`);
+            });
+
+        await client.resumeSessionForExtension(
+            "session-env",
+            { onPermissionRequest: defaultJoinSessionPermissionHandler },
+            undefined,
+            { requestedEnvironmentVariables: ["SDK_TEST_GRANTED_TOKEN"] }
+        );
+
+        const payload = spy.mock.calls.find(([method]) => method === "session.resume")![1] as any;
+        expect(payload.requestedEnvironmentVariables).toEqual(["SDK_TEST_GRANTED_TOKEN"]);
+        expect(process.env.SDK_TEST_GRANTED_TOKEN).toBe("granted-value");
+    });
+
+    it("ignores granted variables the extension never requested", async () => {
+        const client = new CopilotClient();
+        await client.start();
+        onTestFinished(() => stopClient(client));
+        onTestFinished(() => {
+            delete process.env.SDK_TEST_GRANTED_TOKEN;
+        });
+
+        vi.spyOn((client as any).connection!, "sendRequest").mockImplementation(
+            async (method: string, params: any) => {
+                if (method === "session.resume") {
+                    return {
+                        sessionId: params.sessionId,
+                        grantedEnvironmentVariables: {
+                            SDK_TEST_GRANTED_TOKEN: "granted-value",
+                            SDK_TEST_SMUGGLED: "not-approved",
+                        },
+                    };
+                }
+                throw new Error(`Unexpected method: ${method}`);
+            }
+        );
+
+        await client.resumeSessionForExtension(
+            "session-env-extra",
+            { onPermissionRequest: defaultJoinSessionPermissionHandler },
+            undefined,
+            { requestedEnvironmentVariables: ["SDK_TEST_GRANTED_TOKEN"] }
+        );
+
+        expect(process.env.SDK_TEST_GRANTED_TOKEN).toBe("granted-value");
+        // The user approved one name, so a host answering with a second one
+        // cannot widen the grant.
+        expect(process.env.SDK_TEST_SMUGGLED).toBeUndefined();
+    });
+
+    it("omits the environment request when a resume does not ask for one", async () => {
+        const client = new CopilotClient();
+        await client.start();
+        onTestFinished(() => stopClient(client));
+
+        const spy = vi
+            .spyOn((client as any).connection!, "sendRequest")
+            .mockImplementation(async (method: string, params: any) => {
+                if (method === "session.resume") {
+                    return {
+                        sessionId: params.sessionId,
+                        grantedEnvironmentVariables: { SDK_TEST_UNREQUESTED: "leaked" },
+                    };
+                }
+                throw new Error(`Unexpected method: ${method}`);
+            });
+
+        await client.resumeSession("session-no-env", { onPermissionRequest: approveAll });
+
+        const payload = spy.mock.calls.find(([method]) => method === "session.resume")![1] as any;
+        expect(payload).not.toHaveProperty("requestedEnvironmentVariables");
+        // A grant is only honored for a request this client actually made.
+        expect(process.env.SDK_TEST_UNREQUESTED).toBeUndefined();
+    });
+
     it("forwards reasoningSummary in session.create and session.resume", async () => {
         const client = new CopilotClient();
         await client.start();