@@ -0,0 +1,12 @@
+---
+'@objectstack/plugin-auth': patch
+---
+
+fix(plugin-auth): a sign-in that enforced MFA holds records the hold on its own `login` row
+
+Clause-②: no
+Metadata-protocol: none
+
+A sign-in held by the ADR-0069 D3 enforced-MFA requirement (the requirement is on, the account never enrolled, its grace window has lapsed) used to leave the compliance ledger nothing to say about the hold: the sign-in succeeds, a session is minted and its `login` row is written exactly like any other, while every request on that session is answered `MFA_REQUIRED`. The `login` row of such a sign-in now carries `reason: "MFA_REQUIRED"` and `rule: "mfa_required"` in its `metadata`, beside `endpoint`, so an enforcement report can list who was held by the MFA policy, from which address and when.
+
+The hold is asked once, when the session is created, of the same posture computation the session gate asks. It is not asked on every session read, so a held sign-in has exactly one row, and no `login_failed` row is written for it: the session exists. A posture read that fails records no hold, which is the gate's own fail-open direction. A deployment without the audit plugin makes no extra read. Every other `login`, `logout`, `login_failed` and `account_locked` row is unchanged, and no row carries the attempted credential.
@@ -268,3 +268,90 @@ describe('a successful sign-in is recorded as before', () => {
     expectNoPasswordMaterial(events);
   });
 });
+
+describe('[#30924] an MFA-held sign-in records the hold on its own login row', () => {
+  // ADR-0069 D3: a global MFA requirement, a lapsed grace window, an account
+  // that never enrolled. The sign-in itself succeeds (a session is minted and
+  // the user can still reach `/two-factor/*` to enroll); the session is held.
+  const MFA_POLICY = { mfaRequired: true, mfaGracePeriodDays: 0, plugins: { twoFactor: true } };
+
+  /** Start the account's grace clock a day ago, so the hold applies now. */
+  function lapseGrace(engine: any): void {
+    const row = ((engine.tables.get('sys_user') ?? []) as any[]).find((r) => r.email === EMAIL);
+    if (!row) throw new Error(`no sys_user row for ${EMAIL}`);
+    row.two_factor_enabled = false;
+    row.mfa_required_at = new Date(Date.now() - 86_400_000).toISOString();
+  }
+
+  const getSession = (manager: AuthManager, token: string) =>
+    manager.handleRequest(
+      new Request(`${BASE}/get-session`, {
+        method: 'GET',
+        headers: { authorization: `Bearer ${token}`, 'user-agent': CLIENT_UA },
+      }),
+      { remoteAddress: CLIENT_IP },
+    );
+
+  it('one login event carries reason MFA_REQUIRED and rule mfa_required; no login_failed, no credential', async () => {
+    const { engine, manager, events } = deployment(MFA_POLICY);
+    await signUp(manager);
+    lapseGrace(engine);
+    events.length = 0;
+
+    const res = await signIn(manager, EMAIL, PASSWORD);
+    expect(res.status, await res.clone().text()).toBe(200);
+
+    expect(accountEvents(events), 'a held sign-in is not a refused one').toEqual([]);
+    const logins = events.filter((e) => e.action === 'login');
+    expect(logins).toHaveLength(1);
+    expect(logins[0]!.userId).toBe(userIdFor(engine));
+    expect(logins[0]!.ipAddress).toBe(CLIENT_IP);
+    expect(logins[0]!.context).toEqual({ endpoint: '/sign-in/email', reason: 'MFA_REQUIRED', rule: 'mfa_required' });
+    expectNoPasswordMaterial(events);
+  });
+
+  it('the hold is recorded once per sign-in, never once per session read', async () => {
+    const { engine, manager, events } = deployment(MFA_POLICY);
+    await signUp(manager);
+    lapseGrace(engine);
+    events.length = 0;
+
+    const res = await signIn(manager, EMAIL, PASSWORD);
+    expect(res.status).toBe(200);
+    const { token } = (await res.json()) as { token: string };
+
+    // The gate is computed on every read, and holds every one of them…
+    for (let i = 0; i < 3; i++) {
+      const read = await getSession(manager, token);
+      expect(read.status).toBe(200);
+      expect(((await read.json()) as any)?.user?.authGate?.code).toBe('MFA_REQUIRED');
+    }
+    // …and the sign-in still has exactly the one row.
+    expect(events.map((e) => e.action)).toEqual(['login']);
+  });
+
+  it('control: inside the grace window the session is not held, and the login row is as before', async () => {
+    const { manager, events } = deployment({ ...MFA_POLICY, mfaGracePeriodDays: 7 });
+    await signUp(manager);
+    events.length = 0;
+
+    expect((await signIn(manager, EMAIL, PASSWORD)).status).toBe(200);
+
+    const logins = events.filter((e) => e.action === 'login');
+    expect(logins).toHaveLength(1);
+    expect(logins[0]!.context).toEqual({ endpoint: '/sign-in/email' });
+  });
+
+  it('control: a refused password on a held account is still one login_failed with its own code, and no hold', async () => {
+    const { engine, manager, events } = deployment({ ...MFA_POLICY, lockoutThreshold: 5 });
+    await signUp(manager);
+    lapseGrace(engine);
+    events.length = 0;
+
+    expect((await signIn(manager, EMAIL, WRONG_PASSWORD)).status).not.toBe(200);
+
+    expect(events.map((e) => e.action)).toEqual(['login_failed']);
+    expect(events[0]!.context).toEqual({ endpoint: '/sign-in/email', reason: 'INVALID_EMAIL_OR_PASSWORD' });
+    expectNoPasswordMaterial(events);
+  });
+});
@@ -55,6 +55,7 @@ import {
 } from './implicit-account-linking.js';
 import { withSystemReadContext } from './objectql-adapter.js';
 import { emitAuthSessionAuditEvent, loginEventFor, logoutEventFor } from './auth-session-audit.js';
+import { sessionPolicyHoldFor, withSessionPolicyHold } from './session-policy-hold.js';
 import { holdPrincipalSessionExpiry } from './principal-session-mint.js';
 import { canonicalClientAddress } from './client-address-canonical.js';
 import { readRequestClientAddress } from './request-client-address.js';
@@ -75,6 +76,7 @@ export interface DatabaseHooksHost {
   isCreatedInThisRequest: AuthManager['isCreatedInThisRequest'];
   linkingContext: AuthManager['linkingContext'];
   logDurabilityDegradation: AuthManager['logDurabilityDegradation'];
+  resolveUserAuthGates: AuthManager['resolveUserAuthGates'];
   settleMembership: AuthManager['settleMembership'];
   settleSelfRegistrationGrant: AuthManager['settleSelfRegistrationGrant'];
   stampIdentitySource: AuthManager['stampIdentitySource'];
@@ -83,7 +85,7 @@ export interface DatabaseHooksHost {
 
 /** The body of `AuthManager#composeDatabaseHooks`; the method's docblock there is its contract. */
 export function composeDatabaseHooks(
-  this: Pick<DatabaseHooksHost, 'audienceLogError' | 'config' | 'idpLocale' | 'isCreatedInThisRequest' | 'linkingContext' | 'settleMembership' | 'settleSelfRegistrationGrant' | 'stampIdentitySource' | 'takeOwnerVerifiedStamp'>,
+  this: Pick<DatabaseHooksHost, 'audienceLogError' | 'config' | 'idpLocale' | 'isCreatedInThisRequest' | 'linkingContext' | 'resolveUserAuthGates' | 'settleMembership' | 'settleSelfRegistrationGrant' | 'stampIdentitySource' | 'takeOwnerVerifiedStamp'>,
   host?: BetterAuthOptions['databaseHooks'],
 ): BetterAuthOptions['databaseHooks'] {
   // A landed link ends a standing unlink record (implicit-account-linking.ts,
@@ -319,13 +321,26 @@ export function composeDatabaseHooks(
   // better-auth decides. Both emitters are awaited but cannot throw
   // (`emitAuthSessionAuditEvent` swallows), so neither can turn a valid
   // sign-in or sign-out into an error.
+  //
+  // [#30924] A session an authentication policy holds (ADR-0069 D3 enforced
+  // MFA) records that hold on its own `login` row: `context.reason` +
+  // `context.rule` (`session-policy-hold.ts`; why the `login` row and why here
+  // is `auth-session-audit.ts`'s module note). Asked HERE, once per session
+  // created, because the gate itself is computed on every session read; and
+  // only when a sink is registered, so a deployment without the audit plugin
+  // pays no posture read for a row nobody writes. The posture read fails open
+  // (no hold recorded), never failing the sign-in.
   const hostSessionCreateAfter = (host as any)?.session?.create?.after;
   const sessionCreateAfter = async (session: any, ctx: any) => {
     const result = hostSessionCreateAfter ? await hostSessionCreateAfter(session, ctx) : undefined;
-    await emitAuthSessionAuditEvent(
-      this.config.getAuditSink?.(),
-      loginEventFor(session, typeof ctx?.path === 'string' ? ctx.path : undefined),
-    );
+    const sink = this.config.getAuditSink?.();
+    if (sink) {
+      const login = loginEventFor(session, typeof ctx?.path === 'string' ? ctx.path : undefined);
+      const hold = login
+        ? await sessionPolicyHoldFor(session, (userId, options) => this.resolveUserAuthGates(userId, options))
+        : undefined;
+      await emitAuthSessionAuditEvent(sink, withSessionPolicyHold(login, hold));
+    }
     // An external sign-in's staged `locale` claim lands on the user the
     // session names, new or returning (`idp-locale-claim.ts`). Never throws.
     await this.idpLocale.settle(session, ctx);
 
@@ -5306,12 +5306,13 @@ export class AuthManager {
     // [#25224 cut 4] The body moved to `auth-manager-database-hooks.ts` (see `DatabaseHooksHost`).
     const readConfig = () => this.config;
     const readIdpLocale = () => this.idpLocale;
-    const hookHost: Pick<DatabaseHooksHost, 'audienceLogError' | 'config' | 'idpLocale' | 'isCreatedInThisRequest' | 'linkingContext' | 'settleMembership' | 'settleSelfRegistrationGrant' | 'stampIdentitySource' | 'takeOwnerVerifiedStamp'> = {
+    const hookHost: Pick<DatabaseHooksHost, 'audienceLogError' | 'config' | 'idpLocale' | 'isCreatedInThisRequest' | 'linkingContext' | 'resolveUserAuthGates' | 'settleMembership' | 'settleSelfRegistrationGrant' | 'stampIdentitySource' | 'takeOwnerVerifiedStamp'> = {
       audienceLogError: (...a) => this.audienceLogError(...a),
       get config() { return readConfig(); },
       get idpLocale() { return readIdpLocale(); },
       isCreatedInThisRequest: (...a) => this.isCreatedInThisRequest(...a),
       linkingContext: (...a) => this.linkingContext(...a),
+      resolveUserAuthGates: (...a) => this.resolveUserAuthGates(...a),
       settleMembership: (...a) => this.settleMembership(...a),
       settleSelfRegistrationGrant: (...a) => this.settleSelfRegistrationGrant(...a),
       stampIdentitySource: (...a) => this.stampIdentitySource(...a),
 
@@ -287,3 +287,100 @@ describe('[#8144] the mapping refuses to invent an actor', () => {
     expect(event).toEqual({ action: 'login', userId: 'usr_1' });
   });
 });
+
+describe('[#30924] a session an authentication policy holds records the hold on its own login row', () => {
+  // The posture computation is the manager's own (`resolveUserAuthGates`, the
+  // one the session gate asks); these cases stub its ANSWER and read what the
+  // composed hook hands the sink, so what is pinned is the wiring and the
+  // mapping. The real computation over a real better-auth sign-in is pinned in
+  // `auth-account-event-audit.test.ts`.
+  const MFA = { code: 'MFA_REQUIRED', message: 'Set up an authenticator app.' };
+  const EXPIRED = { code: 'PASSWORD_EXPIRED', message: 'Change your password.' };
+  const RESET = { code: 'PASSWORD_RESET_REQUIRED', message: 'Change your temporary password.' };
+
+  function hooksWithGates(answer: (userId: string, options: unknown) => Promise<unknown[]>) {
+    const recordAuthEvent = vi.fn(async (_event: AuthSessionAuditEventInput) => undefined);
+    const manager = new AuthManager({
+      secret: SECRET,
+      baseUrl: 'http://localhost:3000',
+      getAuditSink: () => ({ recordAuthEvent }),
+    } as any);
+    const resolveUserAuthGates = vi.spyOn(manager, 'resolveUserAuthGates').mockImplementation(answer as any);
+    const hooks = (manager as any).composeDatabaseHooks(undefined) as any;
+    return { hooks, recordAuthEvent, resolveUserAuthGates };
+  }
+
+  it('an MFA-held session: the login row carries reason MFA_REQUIRED and rule mfa_required, asked once for its user in its organization', async () => {
+    const { hooks, recordAuthEvent, resolveUserAuthGates } = hooksWithGates(async () => [MFA]);
+
+    await hooks.session.create.after(SESSION, { path: '/sign-in/email' });
+
+    expect(resolveUserAuthGates).toHaveBeenCalledTimes(1);
+    expect(resolveUserAuthGates).toHaveBeenCalledWith('usr_1', { organizationId: 'org_1' });
+    expect(recordAuthEvent).toHaveBeenCalledTimes(1);
+    expect(firstEvent(recordAuthEvent)).toEqual({
+      action: 'login',
+      userId: 'usr_1',
+      sessionId: 'ses_1',
+      organizationId: 'org_1',
+      ipAddress: '203.0.113.7',
+      userAgent: 'Mozilla/5.0 (probe)',
+      context: { endpoint: '/sign-in/email', reason: 'MFA_REQUIRED', rule: 'mfa_required' },
+    });
+  });
+
+  it('control: no posture holds the session, so the login row is exactly as before', async () => {
+    const { hooks, recordAuthEvent } = hooksWithGates(async () => []);
+    await hooks.session.create.after(SESSION, { path: '/sign-in/email' });
+    expect(firstEvent(recordAuthEvent).context).toEqual({ endpoint: '/sign-in/email' });
+  });
+
+  it('control: a posture the table does not record (password expiry) leaves the row as before', async () => {
+    const { hooks, recordAuthEvent } = hooksWithGates(async () => [EXPIRED]);
+    await hooks.session.create.after(SESSION, { path: '/sign-in/email' });
+    expect(firstEvent(recordAuthEvent).context).toEqual({ endpoint: '/sign-in/email' });
+  });
+
+  it('a user held by the forced reset AND enforced MFA has the MFA hold recorded', async () => {
+    const { hooks, recordAuthEvent } = hooksWithGates(async () => [RESET, MFA]);
+    await hooks.session.create.after(SESSION, { path: '/sign-in/email' });
+    expect(firstEvent(recordAuthEvent).context).toMatchObject({ reason: 'MFA_REQUIRED', rule: 'mfa_required' });
+  });
+
+  it('an impersonation session is held by an account-scope posture, so enforced MFA is recorded there too', async () => {
+    const { hooks, recordAuthEvent } = hooksWithGates(async () => [RESET, MFA]);
+    await hooks.session.create.after({ ...SESSION, impersonatedBy: 'usr_admin' }, { path: '/admin/impersonate-user' });
+    const event = firstEvent(recordAuthEvent);
+    expect(event.actor).toBe('usr_admin');
+    expect(event.context).toEqual({
+      endpoint: '/admin/impersonate-user',
+      impersonated_by: 'usr_admin',
+      reason: 'MFA_REQUIRED',
+      rule: 'mfa_required',
+    });
+  });
+
+  it('a posture read that throws records no hold, and the login row is still written', async () => {
+    const { hooks, recordAuthEvent } = hooksWithGates(async () => {
+      throw new Error('sys_user unreachable');
+    });
+    await expect(hooks.session.create.after(SESSION, { path: '/sign-in/email' })).resolves.toBeUndefined();
+    expect(recordAuthEvent).toHaveBeenCalledTimes(1);
+    expect(firstEvent(recordAuthEvent).context).toEqual({ endpoint: '/sign-in/email' });
+  });
+
+  it('no audit plugin installed: no posture read at all', async () => {
+    const manager = new AuthManager({ secret: SECRET, baseUrl: 'http://localhost:3000' } as any);
+    const resolveUserAuthGates = vi.spyOn(manager, 'resolveUserAuthGates');
+    const hooks = (manager as any).composeDatabaseHooks(undefined) as any;
+    await hooks.session.create.after(SESSION, { path: '/sign-in/email' });
+    expect(resolveUserAuthGates).not.toHaveBeenCalled();
+  });
+
+  it('a session with no subject: no posture read and no row', async () => {
+    const { hooks, recordAuthEvent, resolveUserAuthGates } = hooksWithGates(async () => [MFA]);
+    await hooks.session.create.after({ id: 'ses_x' }, { path: '/sign-in/email' });
+    expect(resolveUserAuthGates).not.toHaveBeenCalled();
+    expect(recordAuthEvent).not.toHaveBeenCalled();
+  });
+});
@@ -78,6 +78,31 @@
  * names the RESOLVED account's id, and an identifier that resolves to no
  * account produces no row (an auth row without a subject is the shape this
  * module already refuses to write, above).
+ *
+ * ## A sign-in an authentication policy holds (#30924)
+ *
+ * An ADR-0069 D3 enforced-MFA hold is NOT a refused sign-in: the credential
+ * check passes, better-auth mints the session, and the hold is a posture of
+ * that session, computed per session read (`customSession` → `user.authGate`)
+ * and enforced at the transport seams, so a held user still reaches
+ * `/two-factor/*` to enroll. The sign-in therefore already has its row, the
+ * `login` above, and that row is where the hold is recorded:
+ * `context.reason` names the posture's machine code (`MFA_REQUIRED`, the same
+ * vocabulary a refused sign-in's `reason` uses) and `context.rule` the policy
+ * that holds it (`mfa_required`), from `AUDITED_SESSION_HOLD_RULES` in
+ * `session-policy-hold.ts`, a package-internal module so the published surface
+ * of this one does not move.
+ *
+ * Why the `login` row and not a `login_failed` beside it: the session exists,
+ * so a `login_failed` would contradict the `login` the same sign-in wrote, and
+ * anyone counting `login_failed` rows for brute-force detection would count
+ * users who are signed in. Why at session creation and not where the gate is
+ * computed: that computation runs on every session read, so a row written
+ * there would be one row per request instead of one per sign-in. The hook
+ * asks the same one posture computation the gate asks
+ * (`AuthManager.resolveUserAuthGates`), so the row records a posture the
+ * session is really held by, and fails open exactly where the gate does: no
+ * posture read, no hold recorded.
  */
 
 import { getIP } from '@better-auth/core/utils/ip';