docs: describe ai gateway auditing context

Author: nikolanovoselec

OPERATIONS.md

@@ -137,6 +137,7 @@ sequenceDiagram
 - [ ] Tools (`sendEmail`, `getEmails`, etc.) succeed via AI Gateway
 - [ ] AI Gateway dashboards contain traffic with metadata (`userId`, `mcpTool`, `userEmail`)
 - [ ] Access and Workers logs show consistent request IDs/correlation IDs
+- [ ] Durable Object logs include `aiGatewayLogId` entries that match AI Gateway analytics for each tool call
 - [ ] Durable Object state persists across tool calls
 
 ## 4. Maintenance Procedures

README.md

@@ -28,7 +28,11 @@ clear ingress controls, governed egress, and auditable operations.
 3. **Egress Governance** – Route all outbound API calls (Microsoft Graph, LLMs, webhooks)
    through Cloudflare AI Gateway with metadata for logging and policy enforcement.
 4. **Operational Guardrails** – Maintain reproducible deployment, observability, and
-   incident response checklists suitable for regulated environments.
+  incident response checklists suitable for regulated environments.
+5. **Auditable Graph Egress** – All Microsoft Graph calls run through Cloudflare AI
+  Gateway with enriched metadata (`userId`, `userEmail`, `mcpTool`, `requestId`) and
+  expose the gateway log identifier so investigations can pivot between Workers logs
+  and gateway analytics.
 
 ## Repository Map
 

TECHNICAL.md

@@ -137,6 +137,7 @@ This data can be injected into the AI Gateway metadata payload for end-to-end tr
 
 - **AI Gateway**: Primary location for monitoring outbound traffic, rate limiting, and DLP violations.
   - Dynamic routes expose provider/model decisions and quotas ([docs](https://developers.cloudflare.com/ai-gateway/features/dynamic-routing/)).
+- **Gateway Log Correlation**: Every Graph request attaches metadata (`userId`, `userEmail`, `mcpTool`, `requestId`) and records the resulting `env.AI.aiGatewayLogId`. Durable Object logs emit this identifier so operators can jump directly to the corresponding entry inside the AI Gateway dashboard.
 - **Workers Tail**: Use `wrangler tail --metadata` to surface request IDs and Access identity info.
 - **Access Audit Logs**: Provide authentication history, device posture evaluation, and policy results.
 - **Microsoft Entra ID**: Audit application sign-ins to confirm OAuth flows remain compliant.

src/index.ts

@@ -53,10 +53,10 @@ export interface Env {
    */
   OAUTH_KV: KVNamespace;
 
-  /** Cloudflare AI Gateway binding used for Microsoft Graph egress. */
+  /** Cloudflare AI Gateway binding used to route Microsoft Graph traffic through governed egress. */
   AI: Ai;
 
-  /** Optional Cloudflare Access headers for audit metadata. */
+  /** Optional Cloudflare Access headers surfaced when perimeter policies are enforced (best-effort). */
   CF_Access_Jwt_Assertion?: string;
   CF_Access_Authenticated_User_Email?: string;
   CF_Access_Authenticated_User_Id?: string;

src/microsoft-graph.ts

@@ -72,6 +72,10 @@ export interface GatewayMetadata {
   userId: string;
   mcpTool: string;
   requestId: string;
+  /**
+   * Optional identity fields enrich gateway logs so downstream analytics can correlate
+   * Access identities with Microsoft principals without exposing raw tokens.
+   */
   userEmail?: string;
   microsoftUserPrincipalName?: string;
   microsoftDisplayName?: string;
@@ -584,6 +588,10 @@ export class MicrosoftGraphClient {
     metadata?: GatewayMetadata,
   ): Promise<any> {
     const graphUrl = new URL(url);
+    /**
+     * AI Gateway expects an origin-relative path so that routing rules decide the upstream.
+     * Persist the original query string to avoid losing pagination or filter parameters.
+     */
     const requestPayload: {
       method: string;
       path: string;
@@ -602,6 +610,10 @@ export class MicrosoftGraphClient {
       requestPayload.headers["Content-Type"] = "application/json";
     }
 
+    /**
+     * Metadata drives AI Gateway analytics (user, tool invoked, correlation IDs).
+     * Only attach when upstream code supplies context to keep requests lightweight.
+     */
     const gatewayOptions = metadata
       ? {
           gateway: {
@@ -616,6 +628,10 @@ export class MicrosoftGraphClient {
       gatewayOptions,
     );
 
+    /**
+     * Cloudflare exposes the latest log ID via env.AI.aiGatewayLogId so operators can
+     * correlate Worker logs with Gateway dashboards. Cache it for the Durable Object.
+     */
     this.lastGatewayLogId = this.env.AI.aiGatewayLogId || undefined;
 
     if (!response.ok) {

src/microsoft-mcp-agent.ts

@@ -112,6 +112,11 @@ export class MicrosoftMCPAgent extends McpAgent<Env, State, Props> {
         ? crypto.randomUUID()
         : `req-${Date.now().toString(36)}`;
 
+    /**
+     * Gateway metadata forms the audit envelope that travels with every Graph call.
+     * Prefer stable identifiers (Access headers, Microsoft props) so operations teams
+     * can reconstruct who triggered a tool and how it propagated.
+     */
     const metadata: GatewayMetadata = {
       userId:
         this.props?.id ??
@@ -142,6 +147,10 @@ export class MicrosoftMCPAgent extends McpAgent<Env, State, Props> {
     toolName: string,
     metadata: GatewayMetadata,
   ): void {
+    /**
+     * Persist the AI Gateway log ID alongside the tool invocation. This enables
+     * real-time troubleshooting by pivoting from Durable Object logs to Gateway analytics.
+     */
     const logId = this.graphClient.getLastGatewayLogId();
     if (!logId) {
       return;