Audit Logging (org-scoped)

Linear: FIT-20 Status: Shipped. Capture is always-on, and so is the owner-facing viewer — the audit-logging PostHog flag that used to gate the read surface was merged permanently ON and deleted on 2026-08-22. Last reviewed: 2026-08-22

What

An append-only trail of every consequential change inside one gym: who did it, what changed, to which record, and from where. Written by a single service, read by the gym owner through a filterable table with CSV export, and aged out to R2 after 24 months.

The trail spans six categories:

Why

Three separate pressures converge on the same table:

1. Disputes. “I cancelled last month” / “I never changed her price” are the two most common member-versus-owner arguments in a gym, and neither is settleable today. The subscription row shows the current state, never who moved it.
2. Staff accountability. An owner with admins and coaches has no way to answer “who archived that plan?” A gym is a small business where the owner’s trust in staff is the operating model, and a trail is what makes delegation safe.
3. Compliance. Israeli privacy law and the GDPR both expect a record of who accessed and changed personal data. The lead-consent ledger (ADR-0013) already established the append-only pattern for one narrow slice; this generalizes it.

Who (personas)

Two audit tables, on purpose

There were already audit_logs rows before this feature. They are not the same thing and were deliberately not merged:

Member erasure writes to both: the platform ledger keeps the operational record, the org trail keeps the owner’s record.

Capabilities (current)

• Always-on capture. AuditService.record() is the only writer, and no feature flag guards it — which is why the viewer, unflagged since 2026-08-22, shows the full history rather than starting the trail from the rollout.
• Every charge attempt, from every path, exactly once. Nine code paths move money; all nine resolve through PaymentTransactionService, which is where payment.charge_succeeded / payment.charge_failed are emitted. Declines are recorded too — they answer the owner’s “why wasn’t this member billed” and a run of them is a reg. 11 signal. Failures carry a bounded errorClass, never the gateway’s own text.
• Every refund, from every path. Automatic, manual (both halves), provider-portal and platform-admin refunds all write payment.refund_issued, distinguished by capability and metadata.stage.
• Staff destruction is on the record. Cancelling and deleting sessions, cancelling someone else’s booking, and deleting workouts, programs, templates, class types, forms, leads and announcements all land in operations. Member self-service does not.
• Bulk destruction is one row, not N. A 300-session sweep or a 100-id lead erase writes a single row carrying the count, the ids and the filter.
• Never breaks a request. record() swallows its own failures into Sentry plus a warn. A member’s role change succeeding while the audit write 500s would be strictly worse than a gap in the log.
• Actor resolution without plumbing. A native AsyncLocalStorage request context (no nestjs-cls dependency) carries IP, user-agent, request id and — once AuthGuard has verified the token — the actor. Service code deep in the call stack records without any method growing an actor parameter.
• Honest system attribution. No request context, or a context with no authenticated actor, yields actor_type = 'system'. Crons, provider webhooks and queue workers land there rather than being credited to whoever happened to trigger them.
• Before/after diffs. Every instrumented site that already holds the prior row records only the fields that actually moved. A plan edit that leaves the price alone does not read like a repricing.
• Owner-only read. requireMembership → PermissionsService.enforce(orgId, role, 'audit', 'view'). Unconditional for every org since the audit-logging flag was merged ON (2026-08-22).
• CSV export, same filters as the list, capped at 50,000 rows, with spreadsheet-formula cells neutralized so a member-chosen name can’t execute when the owner opens the file.
• 24-month retention with archive-before-delete to the R2 compliance bucket as NDJSON, one object per (org, month).
• The trail audits itself. Every export writes audit.exported; list access writes audit.viewed (coalesced per reader per 15 minutes); a refused request writes audit.access_denied.
• No secrets, by construction. Credentials, ciphertext, card tokens and join tokens never reach a row. The one free-form bag the API accepts — config on a payment provider — is redacted key-by-key: names kept, values masked.

Capabilities (gaps + tracking)

Code map

Compliance

This is engineering’s mapping, not legal advice. It records how the implementation lines up with the duties we believe apply, so that counsel can confirm or correct it. Every item under “Requires counsel confirmation” is an open question, not a settled position. Nobody on this side is a lawyer.

Which duties this feature is built against

Privacy Protection Regulations (Data Security) 5777-2017 — the operative Israeli instrument. Two regulations matter here, and they are easy to transpose:

• Reg. 10 — תיעוד גישה (access recording). Requires an automatic mechanism recording each access to the database, with a defined field set; retention of those records for at least 24 months; protection of the records against tampering; and a documented procedure for periodic review. Applies at the medium and high security levels.
• Reg. 11 — תיעוד אירועי אבטחה (security-event documentation). Requires documenting security incidents, discussing them, and (at the high level) notifying the Privacy Protection Authority.

Privacy Protection Law Amendment 13 (in force 2025-08-14) did not rewrite these duties; it changed the consequences — administrative fines, an expanded Authority, a DPO (ממונה על הגנת הפרטיות) requirement for some controllers, and breach-notification obligations. Its practical effect on this feature is that reg. 10 is now worth implementing properly rather than approximately.

Which security level applies to Taikan is the first question for counsel. A gym SaaS holds names, phones, emails and payment records for many data subjects; where an org collects health or medical information, that is מידע רגיש and pushes toward the high level. We have built to the medium/high bar on the assumption that at least some orgs land there. If Taikan were only ever at the basic level, reg. 10 would not bite at all.

Industry frameworks pointing the same way, used as the cross-check for the design: ISO/IEC 27001:2022 A.8.15 (logging: what to log, protect logs against tampering and unauthorized access) and A.8.17 (clock synchronization); SOC 2 CC6.1 / CC7.2; NIST SP 800-53 AU-2 / AU-3 / AU-9 / AU-11; OWASP Logging Cheat Sheet and ASVS V7 for what must never be logged.

Field mapping — reg. 10 required field → our column

Beyond the required set we also keep ip_address, user_agent and request_id — the last correlating a row with the pino request log line. NIST AU-3’s “where / source of the event” is covered by those.

Retention design vs the 24-month duty

24 months is a floor, so the boundary is deliberately conservative: the sweep uses a strict lt(created_at, cutoff), meaning a row exactly on the boundary survives, and computeRetentionCutoff is exported so that arithmetic is unit-tested rather than asserted in a comment. Beyond 24 months rows are archived to the R2 compliance bucket before deletion — upload first, delete only that bucket’s exact ids, and a failed upload aborts the delete. Records therefore remain available past the floor rather than being destroyed at it.

The opposite risk is now the live one: the archive has no expiry, so archived rows persist indefinitely. Under GDPR storage limitation that is its own problem, and it is on the counsel list below.

Erasure interplay — the lawful-basis position

Member erasure (MemberErasureService.eraseMember) does not delete audit_events rows, and this is deliberate:

• Audit rows survive erasure intact. actor_user_id is a plain FK with no cascade, and users are soft-deleted and scrubbed in place rather than hard-deleted — the row stays, the PII in it is replaced (email becomes a deleted+<uuid>@deleted.taikan.fit tombstone, names null). So the trail keeps referential integrity while the identity behind it is anonymized at source, which is close to the best available outcome: the record of what was done survives, the identifiability does not.
• The erasure event itself writes an audit row carrying no PII — erasure is the one action whose own audit record must not resurrect what it erased.

The position we believe applies, for counsel to confirm: retention of security/audit records against an erasure request rests on legal obligation (reg. 10 mandates the records and sets a 24-month floor — GDPR Art. 17(3)(b) is the analogous carve-out) and, secondarily, on legitimate interest in security documentation and in establishing or defending legal claims (Art. 17(3)(e)). In plain terms: a member cannot erase the evidence that their subscription was cancelled, because keeping that evidence is what the regulator requires of the gym.

Known gaps / requires counsel confirmation

Related

• behavior.md — invariants, actor resolution, the full capture catalog
• data-model.md — table, enums, indexes
• qa-plan.md — what to exercise before rollout
• ADR-0018 — why app-level capture, and the four other structural calls
• ADR-0004 — why every query is org-scoped in code
• ADR-0007 — why the archive goes to the compliance bucket
• ADR-0013 — the append-only ledger precedent