feat(audit): write login/logout rows to sys_audit_log and attribute the last_login_at update

[os-zhuang]

Fixes #8144

Sub-issue A of #7675, carrying the maintainer ruling of 2026-08-12 (comment 5261744983 on #7675), quoted verbatim and untranslated:

补 writer(3 个):login / logout(auth 事件已有钩点,顺带解决那条 user_id null 的未归因 last_login_at diff 行)…

The defect

sys_audit_log.action declares login and logout, the shipped auth_events list view filters on them, and two System Overview widgets chart them — but nothing in the platform ever wrote either row. The audit writers subscribe to the ObjectQL CRUD lifecycle, so create/update/delete/restore were the only actions that could materialize. The whole trace a sign-in left behind was one unattributed update sys_user row (user_id null) diffing last_login_at: a compliance ledger recording that somebody, unknown, had signed in.

What changed

plugin-audit registers the audit service — the ledger's write ingress for events that are not CRUD (src/auth-event-audit.ts). The row shape stays owned by plugin-audit, which is where packages/spec/src/system/index.ts records that it belongs ("the LIVE audit path (plugin-audit) … defines its own sys_audit_log row shape"). The caller hands over an event, not a row, and action is a closed login | logout union — the only structural protection available on an object where every field is readonly and validateRecord skips readonly/system fields on both branches (#8203), so the declared enum validates nothing in either direction.

plugin-auth emits from better-auth's session lifecycle hooks (src/auth-session-audit.ts), resolving the sink lazily through a locally-declared structural surface — the mirror of the MessagingEmitSurface pattern plugin-audit already uses. Neither package depends on the other; a stack without the audit plugin writes no auth rows, exactly as before.

• session.create.after ⇒ login. Wired to the session hook rather than the /sign-in/email middleware, so it covers every way a session is minted: email sign-in, sign-up auto-sign-in, SSO, OAuth callback, magic link, email OTP, passkey. On a real deployment most sign-ins are federated, and an endpoint-scoped writer would have audited the minority.
• session.delete.after under /sign-out ⇒ logout. Scoped deliberately: revokes, bans, user erasure and better-auth's own collection of expired rows all reach the same hook, and recording those as logout would name an action the subject never took. Those revocations already carry their cause on the ADR-0069 D4 tombstone — session-tombstone.ts left this exact question to audit-log-browser: 4 of 10 declared sys_audit_log actions have no writer anywhere (login/logout/permission_change/config_change/export/import never materialize) #7675.
• The endpoint path comes from the hook's captured ctx argument, not from currentAuthEndpointPath(): delete.after runs inside queueAfterTransactionHook, so the ambient AsyncLocalStorage may no longer answer by then.
• An impersonation session keeps the subject on user_id and names the admin on actor, so it cannot be misread as a self-service login.

stampLastLogin now carries attributedUserId (#4586), so the last_login_at diff row names the person who signed in. Attribution only — the write still authorizes as the system. Attributed rather than excluded (the ruling allowed either): suppressing it would mean adding last_login_at/last_login_ip to the CRUD writer's repo-wide NOISE_FIELDS, deleting the last_login_ip trail for every object and deployment, and a login from a new address is exactly what a compliance ledger is read for.

Verification

Every assertion reads the row back. On this object "no error was thrown" is evidence of nothing — a misspelled action is accepted silently and a writer that never ran throws nothing either.

• packages/qa/dogfood/test/auth-session-audit-trail.dogfood.test.ts — audit-log-browser: 4 of 10 declared sys_audit_log actions have no writer anywhere (login/logout/permission_change/config_change/export/import never materialize) #7675's own reproduction, inverted: real sign-up + sign-in through better-auth, then GET /api/v1/data/sys_audit_log?$filter={"action":"login"} as admin returns the event with actor and tenant (the tenant checked against the sys_member row the platform wrote, not against anything the writer passed in). Plus: the auth_events view stops being empty (its filter read from the running registry, so refactor(plugin-audit)!: retire export / permission_change from the sys_audit_log action enum (#8147) #8200's narrowing cannot silently strand it), sign-out writes logout, a revoke does not, and the last_login_at row is attributed. 5/5.
• Unit: 6 sink cases in plugin-audit (read back through a real ObjectQL engine), 20 composition cases in plugin-auth.
• Ablation (predict-then-mutate): removing the login writer turned exactly the 6 predicted plugin-auth cases and the 2 predicted dogfood cases red — the login query reporting total 0, literally audit-log-browser: 4 of 10 declared sys_audit_log actions have no writer anywhere (login/logout/permission_change/config_change/export/import never materialize) #7675's symptom — with logout, revoke-is-not-logout and the last_login_at attribution staying green. Plain red, no inversion.

scripts/check-durability-degradation-log-level.mjs gains persistAuthEventAuditRow, so the new seam's failure report cannot be walked back down to warn.

Generated by Claude Code

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 13, 2026 3:46am

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/plugin-audit, @objectstack/plugin-auth.

8 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/deployment/cli.mdx (via @objectstack/plugin-audit, @objectstack/plugin-auth)
• content/docs/deployment/production-readiness.mdx (via @objectstack/plugin-audit, @objectstack/plugin-auth)
• content/docs/kernel/contracts/cache-service.mdx (via @objectstack/plugin-auth)
• content/docs/kernel/services-checklist.mdx (via @objectstack/plugin-auth)
• content/docs/permissions/authentication.mdx (via @objectstack/plugin-auth)
• content/docs/permissions/sso.mdx (via @objectstack/plugin-auth)
• content/docs/plugins/index.mdx (via @objectstack/plugin-auth)
• content/docs/plugins/packages.mdx (via @objectstack/plugin-audit, @objectstack/plugin-auth)

⛔ 2 release-owned page(s) also reference the affected code. These are read-only:

• content/docs/releases/implementation-status.mdx (via @objectstack/plugin-audit, @objectstack/plugin-auth)
• content/docs/releases/v9.mdx (via @objectstack/plugin-auth)

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.