[Goodyslim]

Closes #229

Summary

Closes the remaining support-access gap in issue #229: the scoped, time-bounded impersonation model from #80 now writes every session event into the canonical, tamper-evident core/audit trail, and the operational edge cases/failure modes/rollback steps are documented.

Problem

core/impersonation already provided time-bounded sessions, scopes, read-only defaults, dangerous-mutation blocking, elevated confirmation and a user-safe banner projection. However, its audit events were only written to a local in-memory array. They never reached core/audit, so a support session could not be reviewed alongside the rest of the sensitive-action trail, and there was no operational runbook for expiry, scope failures, audit availability or recovery.

Solution

• Declared five impersonation actions in SENSITIVE_ACTIONS:
  • impersonation.session_started
  • impersonation.session_ended
  • impersonation.session_expired
  • impersonation.action
  • impersonation.mutation_blocked
• Mirrored every local impersonation event into recordAudit with:
  • actor { kind: "maintainer", id }
  • scope maintainer
  • target { kind: "user", id }
  • reason support_access
  • correlation id equal to the impersonation session id
  • denied outcomes recorded with errorCode: "impersonation_denied"
• Kept the local append-only trail for tab-scoped diagnostics.
• Added core/impersonation/__tests__/audit-trail.test.ts covering session start, allowed action, blocked mutation, expiry and session end in the canonical trail.
• Added docs/SUPPORT_ACCESS.md covering scopes, expiry, audit mapping, edge cases, failure modes, rollback/recovery and verification.
• Updated the canonical action table in docs/AUDIT.md.

Validation

• npx vitest run core/impersonation core/audit ΓÇö 6 files, 82 tests passed.
• npx eslint core/audit/audit.ts core/impersonation/impersonation.ts core/impersonation/__tests__/audit-trail.test.ts ΓÇö 0 errors.
• Full npm run check is blocked by pre-existing failures on main (cce0053), including 25 unrelated lint errors and failing ownership/invariants/export/webhook/faucet tests, plus duplicate-import build errors in claimable-balances and testnet-faucet. Main CI is already red for the same reasons. None of the failures are in the touched files.

Parallel-work check

No PR referencing #229 existed when work began or immediately before pushing. The other assigned Savitools issue (#431) was skipped because it was already fixed incidentally by PR #434 on Oct 16. This branch is based on current main (cce0053).

[drips-wave]

@Goodyslim Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[Goodyslim]

CI is waiting for maintainer approval (action_required) because this PR comes from a fork.

Local checks:

• npx vitest run core/impersonation core/audit — 6 files, 82 tests passed
• npx eslint core/audit/audit.ts core/impersonation/impersonation.ts core/impersonation/__tests__/audit-trail.test.ts — 0 errors

The full npm run check remains blocked by pre-existing failures on main (cce0053): unrelated lint errors, failing ownership/invariants/export/webhook/faucet tests, and duplicate-import build errors in claimable-balances/testnet-faucet. Main CI is already red for the same reasons.