feat(audit): attributable JSONL audit line at every authorization and tool-call funnel (Spec 107 PR-D)

[Dumbris]

Summary

Adds an attributable, edition-neutral JSONL audit line at every authorization
decision and tool-call funnel, plus a login/logout auth_event line for the
server edition's OAuth front door (Spec 107 PR-D, US3, FR-012–FR-019,
FR-039 part 4, FR-043(b,j), SC-003, SC-009).

• internal/audit: JCS (RFC 8785) canonicalisation over sanitised args →
  args_sha256; three typed constructors (NewAuthz, NewToolCall,
  NewAuthEvent) so a forbidden field per event type doesn't compile; a
  synchronous, mutex-guarded sink (file via lumberjack, or raw stdout)
  with an always-on write-failure counter; per-field sanitisation of every
  caller/operator-controlled string (fixed-prefix credential patterns only —
  never the generic high-entropy rule, which would mask args_sha256/
  email_hash themselves) plus a whole-line defence-in-depth pass that is
  asserted to be the identity on every constructor's output.
• internal/server: authz + tool_call lines at the call_tool_*
  variants, direct dispatch, the REST direct path, and the nested
  code_execution wrapper (parent_id + surface:code_execution); caller
  identity derived for every kind (API key, socket, anonymous, agent token
  owned/ownerless, session_admin, internal, and native stdio, which
  needed a new transport.ConnectionSourceStdio tag since stdio installs an
  admin context with no connection source today).
• internal/serveredition/auth: one auth_event line per terminal login
  attempt (every FR-013 reason) and one per logout, with stage-dependent
  identity (user_id once the store is reached, email_hash for a
  verified-but-unresolved email, neither pre-identity).
• internal/config: AuditLogConfig + EffectiveAuditLog(cfg, transport)
  encoding the stdio rule (FR-014: stdout can never double as the sink when
  stdout carries JSON-RPC — absent block under stdio → disabled + WARN,
  explicit stdout-only under stdio → StartupError exit 4), validation
  reachable from boot/PATCH/apply alike, hot-reload restart-pinning, a
  mcpproxy_audit_write_failures_total counter and a doctor finding.
• Docs: docs/features/audit-log.md, docs/schemas/audit-line-v1.schema.json,
  docs/operations/deploying-for-a-team.md, release notice bullets.

Stacked on #1293 → #1292 → #1287 — merge in order.

Example lines

{"event":"authz","decision":"allow","server":"a","tool":"echo","reason":"none","operation":"read","caller":{"kind":"agent_token","user_id":"01M...","user_email":"alice@example.com","token_name":"t1","token_prefix":"mcp_agt_9f6b"},"request_id":"...-a-echo-1","schema_version":1}
{"event":"tool_call","outcome":"success","server":"a","tool":"echo","args_sha256":"7804fe...","args_bytes":52,"caller":{"kind":"agent_token","user_id":"01M...","user_email":"alice@example.com"},"request_id":"...-a-echo-1","schema_version":1}
{"event":"authz","decision":"deny","server":"b","tool":"echo","reason":"token_scope","disclosed":false,"caller":{"kind":"agent_token","...":"..."},"request_id":"...-b-echo-3","schema_version":1}
{"event":"auth_event","surface":"login","reason":"ok","caller":{"kind":"session_user","user_id":"01M...","role":"user","provider":"oidc"},"schema_version":1}

Config keys

{
  "audit_log": {
    "enabled": true,
    "stdout": false,
    "path": "/var/log/mcpproxy/audit.jsonl",
    "max_size_mb": 50,
    "max_backups": 10,
    "max_age_days": 90,
    "compress": true
  }
}

Defaults: personal edition {enabled:false}; server edition with the block
absent {enabled:true, stdout:true} — except under the native stdio
transport, where stdout carries JSON-RPC and the default resolves to
{enabled:false} with one startup WARN naming audit_log.path instead. An
explicit stdout:true under stdio is refused at boot (StartupError,
exit code 4), never silently disabled. An unwritable path is also exit
code 4, caught by a pre-flight open/close probe before the rotating writer
installs (lumberjack opens lazily and would otherwise swallow it).

Verification gate table (full detail in verification.md)

Gate	Result
Both builds (personal / -tags server)	PASS
go vet ×2	PASS
golangci-lint v2, both tag sets	PASS — only pre-existing, out-of-scope findings
go test -race non-server (excl. internal/server)	PASS
internal/server, personal tags, CI-skip regex	PASS
Server-edition package list, -tags server -race	PASS
go test ./cmd/..., ./tests/oauthserver/...	PASS
make swagger-verify + TestContractsInSync	PASS
Frontend unit (vitest) + build	PASS — 130 files / 1312 tests
Frozen tool-surface goldens	PASS — unregenerated
python3 scripts/gen-roadmap.py --check	PASS
Isolated ./scripts/test-api-e2e.sh + new audit assertions (T113)	PASS — 5/5 audit assertions green
Real-instance verification (T116, dev-server-edition.sh --phase d + manual extensions)	PASS — allow/deny/tool_call lines, sentinel-absence (incl. a caller-supplied tool name), auth_event, schema validation via TestExternalJSONLValidates, stdio WARN/exit-4 rules, unwritable-path exit 4
SC-009 benchmark (audit-on vs audit-off, same-tree A/B)	PASS — all deltas well within the 10%/5ms bound

Two rig bugs found and fixed while running T116 (in scripts/dev-server-edition.sh,
not in the audited feature code): the scratch config left fixture servers
quarantined, and an isError assertion didn't accept the omitempty case.
One pre-existing, out-of-scope discrepancy documented but not fixed: --listen ""
does not actually reach native stdio through mcpproxy serve today
(Config.Validate() resets an empty Listen back to the HTTP default) —
--listen ":0" is the only path that works; flagged for separate follow-up.

Benchmark deltas (SC-009, same-tree audit-on vs audit-off, bound = max(10%, 5ms))

operation	delta	verdict
call_tool_read (admin)	+0.14ms	PASS
retrieve_tools (admin)	-0.05 to -0.10ms (audit ON measured faster)	PASS
tools/list (admin)	~0ms (no audit line fires on this path)	PASS
retrieve_tools scoped vs admin	scoped faster than admin in every arm	PASS (bound 20ms)

[cloudflare-workers-and-pages]

Deploying mcpproxy-docs with    Cloudflare Pages

Latest commit:	6af4400
Status:	✅  Deploy successful!
Preview URL:	https://0d538a74.mcpproxy-docs.pages.dev
Branch Preview URL:	https://107-d-audit-line.mcpproxy-docs.pages.dev

View logs

[github-actions]

📦 Build Artifacts

Workflow Run: View Run
Branch: 107-d-audit-line

Available Artifacts

• archive-darwin-amd64 (30 MB)
• archive-darwin-arm64 (27 MB)
• archive-linux-amd64 (18 MB)
• archive-linux-arm64 (16 MB)
• archive-windows-amd64 (30 MB)
• archive-windows-arm64 (26 MB)
• frontend-dist-pr (0 MB)
• installer-dmg-darwin-amd64 (24 MB)
• installer-dmg-darwin-arm64 (21 MB)
• smart-mcp-proxymcpproxy-goU3AHNJ.dockerbuild (0 MB)

How to Download

Option 1: GitHub Web UI (easiest)

1. Go to the workflow run page linked above
2. Scroll to the bottom "Artifacts" section
3. Click on the artifact you want to download

Option 2: GitHub CLI

gh run download 35371173901 --repo smart-mcp-proxy/mcpproxy-go

Note: Artifacts expire in 14 days.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 77.67355% with 238 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
internal/server/audit_funnel.go	82.18%	30 Missing and 14 partials ⚠️
internal/config/audit_log.go	41.66%	37 Missing and 5 partials ⚠️
cmd/mcpproxy/main.go	2.70%	35 Missing and 1 partial ⚠️
internal/audit/line.go	82.44%	15 Missing and 8 partials ⚠️
internal/server/server.go	66.17%	20 Missing and 3 partials ⚠️
internal/audit/canonical.go	80.70%	13 Missing and 9 partials ⚠️
internal/server/mcp.go	82.35%	17 Missing and 1 partial ⚠️
internal/config/loader.go	17.64%	11 Missing and 3 partials ⚠️
internal/server/mcp_code_execution.go	86.56%	9 Missing ⚠️
internal/audit/redact.go	90.47%	1 Missing and 1 partial ⚠️
... and 3 more

📢 Thoughts on this report? Let us know!