3rd Party MCP - Audit Source Column + Request Context Propagation

[cstns]

Summary

Add a source column to the AuditLog model and propagate request source information through @fastify/request-context so audit loggers can record how an action was triggered.

Why

MCP platform tools use app.inject() to call existing HTTP routes. Audit logging happens inside those route handlers. From the route's perspective, an MCP-originated request looks identical to a regular API request. Without explicit signaling, administrators have no way to tell "user did this in the UI" from "3rd party agent did this via MCP" from "first-party expert agent did this."

A queryable database column (rather than burying it in the JSON body) lets administrators filter audit logs by source directly, which is the primary use case: "show me everything an MCP agent did in the last 24 hours."

@fastify/request-context is the carrier because it's already used for PAT metadata (#7411). The audit loggers can read from it without changing their function signatures or touching every route handler that calls them. The source is set once (during auth / header processing) and available everywhere downstream.

What to do

Database migration

• Add source column to AuditLogs table: STRING, nullable, default null
• Null represents the legacy/UI path (cookie session, no PAT, no MCP header)

Source detection and propagation

• After verifySession, detect the request source and store it in @fastify/request-context:
  • Cookie session (no PAT): source remains null (or ui if we want to be explicit)
  • PAT present, no MCP header: api
  • MCP custom header X-FF-Audit-Source: mcp: mcp (3rd party agent)
  • MCP custom header X-FF-Audit-Source: mcp:expert: mcp:expert (first-party agent)
• Also store the token identifier from X-FF-Audit-Token header when present, for traceability to the specific PAT/integration

Audit logger updates

• Update the centralized audit logging functions (platformLog, userLog, teamLog, projectLog, applicationLog, deviceLog in forge/db/controllers/AuditLog.js) to read source from @fastify/request-context and pass it to the model
• Update the AuditLog view formatter to include source in the output
• Update the triggerObject() in formatters.js to include the token identifier when available

Tests

• MCP-originated action (via app.inject() with custom headers) records source: 'mcp'
• First-party expert action records source: 'mcp:expert'
• Direct PAT API call records source: 'api'
• Cookie session action records source: null (or ui)
• Token identifier is included in the audit body when present
• Existing audit entries (before migration) have null source
• Audit log API returns the source field

References

• Audit log controller: forge/db/controllers/AuditLog.js
• Audit formatters: forge/auditLog/formatters.js
• @fastify/request-context setup: Add PAT (Personal Acces Tokens) scopes #7411 (T1, T2)
• Parent story: Story 4: MCP Audit Trail #7425

[HarperZ9]

This looks like the right audit column, but I would make the spoofing boundary explicit in the implementation/tests.

The source value should probably be derived only after the request has crossed the trusted auth/gateway layer, not copied directly from a user-controlled header into the audit row. Otherwise an ordinary API caller could potentially label itself as mcp or first-party-agent if it knows the header name.

Acceptance-test shape I would want:

• UI/cookie session -> source = ui or null, depending on the chosen legacy behavior
• PAT without validated MCP context -> source = api
• MCP request through the internal gateway -> source = mcp plus a stable request/admission id if available
• forged external X-FF-Source: mcp without gateway validation -> remains api or rejected, never mcp

The stable id is useful because source alone answers "where did this come from?" but not "which agent/tool admission caused this audited mutation?" Even an opaque request/admission id would let admins join auth, route handling, and audit output later without stuffing the whole MCP payload into the audit log row.