auth-manager.test.ts

// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.

import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import { AuthManager, ipMatchesRange } from './auth-manager';
import { vendorClientAddressOptions } from './client-address-vendor';
import { assertEngineDeleteDispatch, assertEngineUpdateDispatch, assertEngineFindOnePredicate, type EngineFindOneQueryInput } from '@objectstack/objectql';

// Mock better-auth so we can control the handler behaviour
vi.mock('better-auth', () => ({
  betterAuth: vi.fn(() => ({
    handler: vi.fn(),
    api: {},
  })),
}));

// Mock plugin imports — we only need to verify they are called with the
// correct schema options; the actual plugin logic is tested by better-auth.
vi.mock('better-auth/plugins/organization', () => ({
  organization: vi.fn((opts: any) => ({ id: 'organization', _opts: opts })),
}));

vi.mock('better-auth/plugins/two-factor', () => ({
  twoFactor: vi.fn((opts: any) => ({ id: 'two-factor', _opts: opts })),
}));

vi.mock('better-auth/plugins/magic-link', () => ({
  magicLink: vi.fn((_opts?: any) => ({ id: 'magic-link' })),
}));

vi.mock('better-auth/plugins/custom-session', () => ({
  customSession: vi.fn((fn: any) => ({ id: 'custom-session', _fn: fn })),
}));

vi.mock('better-auth/plugins/haveibeenpwned', () => ({
  haveIBeenPwned: vi.fn((opts: any) => ({ id: 'have-i-been-pwned', _opts: opts })),
}));

import { betterAuth } from 'better-auth';
import { bindTestSecurityCatalog } from './__tests__/security-catalog.testkit';
import { ADMIN_FULL_ACCESS, ADMIN_FULL_ACCESS_CAPABILITIES } from '@objectstack/spec';
import { AuthzStoreUnavailableError, resetCloudManagedForTesting } from '@objectstack/core';

describe('AuthManager', () => {
  let consoleSpy: ReturnType<typeof vi.spyOn>;
  const prevMcpEnv = process.env.OS_MCP_SERVER_ENABLED;

  beforeEach(() => {
    vi.clearAllMocks();
    consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
    // This suite exercises the config-driven plugin list / public config in
    // isolation. The MCP surface is default-ON and would append jwt +
    // oauth-provider everywhere; pin it off here — the default-on behaviour
    // has its own coverage in auth-manager.mcp-oauth.test.ts.
    process.env.OS_MCP_SERVER_ENABLED = 'false';
  });

  afterEach(() => {
    consoleSpy.mockRestore();
    if (prevMcpEnv === undefined) delete process.env.OS_MCP_SERVER_ENABLED;
    else process.env.OS_MCP_SERVER_ENABLED = prevMcpEnv;
  });

  describe('handleRequest – error response logging', () => {
    it('should log when better-auth returns a 500 response', async () => {
      const errorResponse = new Response(
        JSON.stringify({ error: 'Internal database error' }),
        { status: 500, headers: { 'Content-Type': 'application/json' } },
      );

      const mockHandler = vi.fn().mockResolvedValue(errorResponse);
      (betterAuth as any).mockReturnValue({ handler: mockHandler, api: {} });

      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
      });

      const request = new Request('http://localhost:3000/sign-up/email', {
        method: 'POST',
        body: JSON.stringify({ email: 'a@b.com', password: 'pass' }),
        headers: { 'Content-Type': 'application/json' },
      });

      const response = await manager.handleRequest(request);

      expect(response.status).toBe(500);
      expect(consoleSpy).toHaveBeenCalledWith(
        '[AuthManager] better-auth returned error:',
        500,
        expect.stringContaining('Internal database error'),
      );
    });

    it('should NOT log for successful (2xx) responses', async () => {
      const okResponse = new Response(JSON.stringify({ user: {} }), {
        status: 200,
      });

      const mockHandler = vi.fn().mockResolvedValue(okResponse);
      (betterAuth as any).mockReturnValue({ handler: mockHandler, api: {} });

      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
      });

      const request = new Request('http://localhost:3000/sign-in/email', {
        method: 'POST',
        body: JSON.stringify({ email: 'a@b.com', password: 'pass' }),
        headers: { 'Content-Type': 'application/json' },
      });

      const response = await manager.handleRequest(request);

      expect(response.status).toBe(200);
      expect(consoleSpy).not.toHaveBeenCalled();
    });

    it('should NOT log for 4xx responses', async () => {
      const badRequestResponse = new Response(
        JSON.stringify({ error: 'Bad request' }),
        { status: 400 },
      );

      const mockHandler = vi.fn().mockResolvedValue(badRequestResponse);
      (betterAuth as any).mockReturnValue({ handler: mockHandler, api: {} });

      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
      });

      const request = new Request('http://localhost:3000/sign-in/email', {
        method: 'POST',
      });

      const response = await manager.handleRequest(request);

      expect(response.status).toBe(400);
      expect(consoleSpy).not.toHaveBeenCalled();
    });
  });

  describe('handleRequest – dev Origin injection (CSRF DX)', () => {
    const ORIGINAL_NODE_ENV = process.env.NODE_ENV;

    afterEach(() => {
      if (ORIGINAL_NODE_ENV === undefined) delete process.env.NODE_ENV;
      else process.env.NODE_ENV = ORIGINAL_NODE_ENV;
    });

    const makeManager = () => {
      const captured: { request?: Request } = {};
      const mockHandler = vi.fn().mockImplementation((req: Request) => {
        captured.request = req;
        return new Response(null, { status: 200 });
      });
      (betterAuth as any).mockReturnValue({ handler: mockHandler, api: {} });
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
      });
      return { manager, captured };
    };

    it('injects a same-origin Origin header in dev when none is present', async () => {
      process.env.NODE_ENV = 'development';
      const { manager, captured } = makeManager();

      await manager.handleRequest(new Request('http://localhost:3000/sign-in/email', {
        method: 'POST',
        body: JSON.stringify({ email: 'a@b.com', password: 'pass' }),
        headers: { 'Content-Type': 'application/json' },
      }));

      expect(captured.request?.headers.get('origin')).toBe('http://localhost:3000');
    });

    it('does NOT inject an Origin header in production', async () => {
      process.env.NODE_ENV = 'production';
      const { manager, captured } = makeManager();

      await manager.handleRequest(new Request('http://localhost:3000/sign-in/email', {
        method: 'POST',
        body: JSON.stringify({ email: 'a@b.com', password: 'pass' }),
        headers: { 'Content-Type': 'application/json' },
      }));

      expect(captured.request?.headers.get('origin')).toBeNull();
    });

    it('preserves a caller-supplied Origin header in dev', async () => {
      process.env.NODE_ENV = 'development';
      const { manager, captured } = makeManager();

      await manager.handleRequest(new Request('http://localhost:3000/sign-in/email', {
        method: 'POST',
        body: JSON.stringify({ email: 'a@b.com', password: 'pass' }),
        headers: { 'Content-Type': 'application/json', origin: 'http://example.test' },
      }));

      expect(captured.request?.headers.get('origin')).toBe('http://example.test');
    });

    it('does not inject when a Referer is already present in dev', async () => {
      process.env.NODE_ENV = 'development';
      const { manager, captured } = makeManager();

      await manager.handleRequest(new Request('http://localhost:3000/sign-in/email', {
        method: 'POST',
        headers: { referer: 'http://localhost:3000/login' },
      }));

      expect(captured.request?.headers.get('origin')).toBeNull();
    });
  });

  describe('createDatabaseConfig – adapter wrapping', () => {
    it('should pass a function (AdapterFactory) to betterAuth when dataEngine is provided', () => {
      const mockDataEngine = {
        insert: vi.fn(),
        findOne: vi.fn(),
        find: vi.fn(),
        count: vi.fn(),
        update: vi.fn(),
        delete: vi.fn(),
      };

      new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
        dataEngine: mockDataEngine as any,
      });

      // Trigger lazy initialization by calling getAuthInstance()
      // betterAuth should have been called with a database value that is a function
      // We need to trigger the lazy init first
    });

    it('should provide a factory function as database config', async () => {
      const mockDataEngine = {
        insert: vi.fn().mockResolvedValue({ id: '1' }),
        findOne: vi.fn().mockResolvedValue({ id: '1' }),
        find: vi.fn().mockResolvedValue([]),
        count: vi.fn().mockResolvedValue(0),
        update: vi.fn().mockResolvedValue({ id: '1' }),
        delete: vi.fn().mockResolvedValue(undefined),
      };

      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });

      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
        dataEngine: mockDataEngine as any,
      });

      // Trigger lazy initialisation
      await manager.getAuthInstance();

      // The database config should be a function (AdapterFactory)
      expect(typeof capturedConfig.database).toBe('function');
    });

    it('should include modelName and fields mapping for user, session, account, verification', async () => {
      const mockDataEngine = {
        insert: vi.fn().mockResolvedValue({ id: '1' }),
        findOne: vi.fn().mockResolvedValue({ id: '1' }),
        find: vi.fn().mockResolvedValue([]),
        count: vi.fn().mockResolvedValue(0),
        update: vi.fn().mockResolvedValue({ id: '1' }),
        delete: vi.fn().mockResolvedValue(undefined),
      };

      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });

      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
        dataEngine: mockDataEngine as any,
      });

      await manager.getAuthInstance();

      // Verify user model config
      expect(capturedConfig.user).toBeDefined();
      expect(capturedConfig.user.modelName).toBe('sys_user');
      expect(capturedConfig.user.fields).toEqual(expect.objectContaining({
        emailVerified: 'email_verified',
        createdAt: 'created_at',
        updatedAt: 'updated_at',
      }));

      // Verify session model config (merged with session timing config)
      expect(capturedConfig.session).toBeDefined();
      expect(capturedConfig.session.modelName).toBe('sys_session');
      expect(capturedConfig.session.fields).toEqual(expect.objectContaining({
        userId: 'user_id',
        expiresAt: 'expires_at',
        ipAddress: 'ip_address',
        userAgent: 'user_agent',
      }));

      // Verify account model config
      expect(capturedConfig.account).toBeDefined();
      expect(capturedConfig.account.modelName).toBe('sys_account');
      expect(capturedConfig.account.fields).toEqual(expect.objectContaining({
        userId: 'user_id',
        providerId: 'provider_id',
        // [#17440] Identity key: (providerId, accountId) — 1.7.3 rolled the
        // issuer-scoped key back. The id field kept the `account_id` column
        // across the rc.2 `providerAccountId` detour and the stable 1.7
        // rename back (#3002).
        accountId: 'account_id',
        accessToken: 'access_token',
        refreshToken: 'refresh_token',
        idToken: 'id_token',
        accessTokenExpiresAt: 'access_token_expires_at',
        refreshTokenExpiresAt: 'refresh_token_expires_at',
      }));

      // Verify verification model config
      expect(capturedConfig.verification).toBeDefined();
      expect(capturedConfig.verification.modelName).toBe('sys_verification');
      expect(capturedConfig.verification.fields).toEqual(expect.objectContaining({
        expiresAt: 'expires_at',
        createdAt: 'created_at',
        updatedAt: 'updated_at',
      }));
    });

    // ⛔ This used to assert `database === undefined` — "let better-auth build
    // its own in-memory store". That store is keyed by the schema KEY while
    // every read resolves by `modelName`, so on better-auth 1.7.2 EVERY model
    // this package renames (`user`/`sys_user`, `oauthResource`/
    // `sys_oauth_resource`, …) was unreachable on that path with
    // "Model <name> not found". The old assertion could not see that: it read
    // the value we passed, never what the value does. This one drives the
    // factory and asks the adapter for a renamed model.
    it('the no-dataEngine fallback yields an adapter that can resolve a RENAMED model', async () => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });

      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});

      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
      });

      await manager.getAuthInstance();
      warnSpy.mockRestore();

      // An AdapterFactory, not `undefined`.
      expect(typeof capturedConfig.database).toBe('function');

      const adapter = capturedConfig.database(capturedConfig);
      // `sys_user` is `user` renamed via `modelName`; a store keyed by the
      // schema key answers "Model sys_user not found" here instead of `null`.
      await expect(
        adapter.findOne({ model: 'sys_user', where: [{ field: 'id', value: 'nobody' }] }),
      ).resolves.toBeNull();
    });
  });

  describe('basePath configuration', () => {
    it('should default basePath to /api/v1/auth when not specified', async () => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });

      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
      });
      await manager.getAuthInstance();
      warnSpy.mockRestore();

      expect(capturedConfig.basePath).toBe('/api/v1/auth');
    });

    it('should use custom basePath when provided', async () => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });

      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
        basePath: '/custom/auth',
      });
      await manager.getAuthInstance();
      warnSpy.mockRestore();

      expect(capturedConfig.basePath).toBe('/custom/auth');
    });
  });

  describe('plugin registration', () => {
    it('should always register the bearer plugin even with no plugin config', async () => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });

      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
      });
      await manager.getAuthInstance();
      warnSpy.mockRestore();

      // [#28367] The agent forward view rides right after bearer(), on every instance.
      expect(capturedConfig.plugins.map((p: any) => p.id)).toEqual(['bearer', 'objectstack-agent-forward-identity-view', 'organization']);
    });

    it('should register organization plugin with schema mapping when enabled', async () => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });

      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
        plugins: { organization: true },
      });
      await manager.getAuthInstance();
      warnSpy.mockRestore();

      const orgPlugin = capturedConfig.plugins.find((p: any) => p.id === 'organization');
      expect(orgPlugin).toBeDefined();
      // Verify schema was passed to organization() call
      expect(orgPlugin._opts.schema.organization.modelName).toBe('sys_organization');
      expect(orgPlugin._opts.schema.member.modelName).toBe('sys_member');
      expect(orgPlugin._opts.schema.invitation.modelName).toBe('sys_invitation');
      expect(orgPlugin._opts.schema.team.modelName).toBe('sys_team');
      expect(orgPlugin._opts.schema.teamMember.modelName).toBe('sys_team_member');
      expect(orgPlugin._opts.schema.session.fields.activeOrganizationId).toBe('active_organization_id');
    });

    // @better-auth/scim mounts the SCIM 2.0 Service Provider so an external IdP
    // can auto-provision/deprovision this env's users (ADR-0134). It is opt-in
    // via `plugins.scim` (explicit value wins, #13439) or OS_SCIM_ENABLED
    // (decides where the config leaves it unset), and effective SCIM FORCES
    // the admin plugin on (active:false → ban runs through admin).
    it('should NOT register the scim plugin by default', async () => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });
      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
      });
      await manager.getAuthInstance();
      warnSpy.mockRestore();

      expect(capturedConfig.plugins.map((p: any) => p.id)).not.toContain('scim');
    });

    it('should register the scim plugin (and force admin on) when OS_SCIM_ENABLED is set', async () => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });
      const prev = process.env.OS_SCIM_ENABLED;
      process.env.OS_SCIM_ENABLED = 'true';
      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      try {
        const manager = new AuthManager({
          secret: 'test-secret-at-least-32-chars-long',
          baseUrl: 'http://localhost:3000',
        });
        await manager.getAuthInstance();
        const ids = capturedConfig.plugins.map((p: any) => p.id);
        expect(ids).toContain('scim');
        // active:false → ban needs the admin plugin; SCIM forces it on.
        expect(ids).toContain('admin');
      } finally {
        if (prev === undefined) delete process.env.OS_SCIM_ENABLED;
        else process.env.OS_SCIM_ENABLED = prev;
        warnSpy.mockRestore();
      }
    });

    // #13439 (maintainer ruling 2026-08-31) — an EXPLICIT `plugins.scim`
    // value wins over `OS_SCIM_ENABLED`; the env var decides only where the
    // config leaves the key unset. This is the cloud control plane's case:
    // its plan-derived `plugins.scim: false` must be authoritative even in a
    // deployment env that carries an ambient OS_SCIM_ENABLED (cloud#1265).
    // The forced-admin coupling (ADR-0134) follows the EFFECTIVE scim value,
    // so declining scim also declines the admin plugin it would have dragged
    // in (unless `admin` is set explicitly).
    it('should NOT register the scim plugin (nor force admin on) when plugins.scim=false despite OS_SCIM_ENABLED', async () => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });
      const prev = process.env.OS_SCIM_ENABLED;
      process.env.OS_SCIM_ENABLED = 'true';
      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      try {
        const manager = new AuthManager({
          secret: 'test-secret-at-least-32-chars-long',
          baseUrl: 'http://localhost:3000',
          plugins: { scim: false },
        });
        await manager.getAuthInstance();
        const ids = capturedConfig.plugins.map((p: any) => p.id);
        expect(ids).not.toContain('scim');
        expect(ids).not.toContain('admin');
        // The /auth/config features block recomputes the admin default from
        // the same flipped chain (its own inline scim resolution) — it must
        // agree with the wired plugin list.
        expect(manager.getPublicConfig().features.admin).toBe(false);
      } finally {
        if (prev === undefined) delete process.env.OS_SCIM_ENABLED;
        else process.env.OS_SCIM_ENABLED = prev;
        warnSpy.mockRestore();
      }
    });

    it('should register the scim plugin (and force admin on) when plugins.scim=true with no env set', async () => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });
      const prev = process.env.OS_SCIM_ENABLED;
      delete process.env.OS_SCIM_ENABLED;
      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      try {
        const manager = new AuthManager({
          secret: 'test-secret-at-least-32-chars-long',
          baseUrl: 'http://localhost:3000',
          plugins: { scim: true },
        });
        await manager.getAuthInstance();
        const ids = capturedConfig.plugins.map((p: any) => p.id);
        expect(ids).toContain('scim');
        // ADR-0134 — the forced-admin coupling is unchanged: effective SCIM
        // still drags the admin plugin in when `admin` is left unset.
        expect(ids).toContain('admin');
        expect(manager.getPublicConfig().features.admin).toBe(true);
      } finally {
        if (prev === undefined) delete process.env.OS_SCIM_ENABLED;
        else process.env.OS_SCIM_ENABLED = prev;
        warnSpy.mockRestore();
      }
    });

    // #13816 (maintainer ruling 2026-09-01) — `admin` is tri-state, and the
    // one incoherent corner is REFUSED at construction: effective SCIM with an
    // explicit `plugins.admin: false` contradicts ADR-0134 (SCIM's
    // active:false deprovisioning runs through the admin plugin), so the
    // manager throws a documented conflict instead of silently honouring the
    // decline and mounting SCIM with a broken deprovisioning path.
    it('REFUSES construction when plugins.scim=true and plugins.admin=false (documented ADR-0134 conflict)', () => {
      const prev = process.env.OS_SCIM_ENABLED;
      delete process.env.OS_SCIM_ENABLED;
      try {
        expect(() => new AuthManager({
          secret: 'test-secret-at-least-32-chars-long',
          baseUrl: 'http://localhost:3000',
          plugins: { scim: true, admin: false },
        })).toThrow(/plugins\.admin[\s\S]*ADR-0134[\s\S]*plugins\.scim: false/);
      } finally {
        if (prev === undefined) delete process.env.OS_SCIM_ENABLED;
        else process.env.OS_SCIM_ENABLED = prev;
      }
    });

    it('REFUSES construction when OS_SCIM_ENABLED makes SCIM effective beside plugins.admin=false', () => {
      const prev = process.env.OS_SCIM_ENABLED;
      process.env.OS_SCIM_ENABLED = 'true';
      try {
        expect(() => new AuthManager({
          secret: 'test-secret-at-least-32-chars-long',
          baseUrl: 'http://localhost:3000',
          plugins: { admin: false },
        })).toThrow(/OS_SCIM_ENABLED[\s\S]*ADR-0134/);
      } finally {
        if (prev === undefined) delete process.env.OS_SCIM_ENABLED;
        else process.env.OS_SCIM_ENABLED = prev;
      }
    });

    it('accepts plugins.admin=false beside plugins.scim=false despite OS_SCIM_ENABLED (declining both is coherent)', async () => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });
      const prev = process.env.OS_SCIM_ENABLED;
      process.env.OS_SCIM_ENABLED = 'true';
      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      try {
        const manager = new AuthManager({
          secret: 'test-secret-at-least-32-chars-long',
          baseUrl: 'http://localhost:3000',
          plugins: { scim: false, admin: false },
        });
        await manager.getAuthInstance();
        const ids = capturedConfig.plugins.map((p: any) => p.id);
        expect(ids).not.toContain('scim');
        expect(ids).not.toContain('admin');
        expect(manager.getPublicConfig().features.admin).toBe(false);
      } finally {
        if (prev === undefined) delete process.env.OS_SCIM_ENABLED;
        else process.env.OS_SCIM_ENABLED = prev;
        warnSpy.mockRestore();
      }
    });

    it('honours an explicit plugins.admin=false when SCIM is not effective (tri-state decline)', async () => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });
      const prev = process.env.OS_SCIM_ENABLED;
      delete process.env.OS_SCIM_ENABLED;
      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      try {
        const manager = new AuthManager({
          secret: 'test-secret-at-least-32-chars-long',
          baseUrl: 'http://localhost:3000',
          plugins: { admin: false },
        });
        await manager.getAuthInstance();
        expect(capturedConfig.plugins.map((p: any) => p.id)).not.toContain('admin');
        expect(manager.getPublicConfig().features.admin).toBe(false);
      } finally {
        if (prev === undefined) delete process.env.OS_SCIM_ENABLED;
        else process.env.OS_SCIM_ENABLED = prev;
        warnSpy.mockRestore();
      }
    });

    it('honours an explicit plugins.admin=true without SCIM (tri-state enable)', async () => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });
      const prev = process.env.OS_SCIM_ENABLED;
      delete process.env.OS_SCIM_ENABLED;
      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      try {
        const manager = new AuthManager({
          secret: 'test-secret-at-least-32-chars-long',
          baseUrl: 'http://localhost:3000',
          plugins: { admin: true },
        });
        await manager.getAuthInstance();
        expect(capturedConfig.plugins.map((p: any) => p.id)).toContain('admin');
        expect(manager.getPublicConfig().features.admin).toBe(true);
      } finally {
        if (prev === undefined) delete process.env.OS_SCIM_ENABLED;
        else process.env.OS_SCIM_ENABLED = prev;
        warnSpy.mockRestore();
      }
    });

    it('REFUSES an applyConfigPatch that smuggles admin=false into a SCIM-enabled config — the standing config keeps ruling', () => {
      const prev = process.env.OS_SCIM_ENABLED;
      delete process.env.OS_SCIM_ENABLED;
      try {
        const manager = new AuthManager({
          secret: 'test-secret-at-least-32-chars-long',
          baseUrl: 'http://localhost:3000',
          plugins: { scim: true },
        });
        expect(() => manager.applyConfigPatch({ plugins: { admin: false } }))
          .toThrow(/ADR-0134/);
        // The refused patch never became current: the advertised admin flag
        // still reflects the SCIM-forced coupling.
        expect(manager.getPublicConfig().features.admin).toBe(true);
      } finally {
        if (prev === undefined) delete process.env.OS_SCIM_ENABLED;
        else process.env.OS_SCIM_ENABLED = prev;
      }
    });

    it('REFUSES the lazy better-auth build when OS_SCIM_ENABLED appears only after construction', async () => {
      const prev = process.env.OS_SCIM_ENABLED;
      delete process.env.OS_SCIM_ENABLED;
      try {
        // Coherent at boot: no SCIM anywhere, admin declined.
        const manager = new AuthManager({
          secret: 'test-secret-at-least-32-chars-long',
          baseUrl: 'http://localhost:3000',
          plugins: { admin: false },
        });
        // The env var is actually read at buildPluginList() time — a value
        // appearing between construction and the lazy build must not mount
        // SCIM with its deprovisioning path silently declined.
        process.env.OS_SCIM_ENABLED = 'true';
        await expect(manager.getAuthInstance()).rejects.toThrow(/ADR-0134/);
      } finally {
        if (prev === undefined) delete process.env.OS_SCIM_ENABLED;
        else process.env.OS_SCIM_ENABLED = prev;
      }
    });

    it('blocks slug change when the org has active environments', async () => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });

      const dataEngine = {
        findOne: vi.fn(async (object: string) => {
          if (object === 'sys_organization') return { id: 'org-42', slug: 'acme-old' };
          return null;
        }),
        find: vi.fn(async (object: string) => {
          if (object === 'sys_environment') {
            return [
              { id: 'e1', status: 'active' },
              { id: 'e2', status: 'archived' },
            ];
          }
          return [];
        }),
      };

      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
        plugins: { organization: true },
        dataEngine: dataEngine as any,
      });
      await manager.getAuthInstance();
      warnSpy.mockRestore();

      const orgPlugin = capturedConfig.plugins.find((p: any) => p.id === 'organization');
      const beforeUpdate = orgPlugin._opts.organizationHooks?.beforeUpdateOrganization;
      expect(typeof beforeUpdate).toBe('function');

      // Slug change to "acme-new" while 1 active env exists must throw.
      await expect(
        beforeUpdate({
          organization: { slug: 'acme-new' },
          member: { organizationId: 'org-42' },
        }),
      ).rejects.toThrowError(/active.*environment/i);
    });

    it('allows slug change when no active environments reference the org', async () => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });

      const dataEngine = {
        findOne: vi.fn(async () => ({ id: 'org-42', slug: 'acme-old' })),
        find: vi.fn(async () => [{ id: 'e1', status: 'archived' }]),
      };

      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
        plugins: { organization: true },
        dataEngine: dataEngine as any,
      });
      await manager.getAuthInstance();
      warnSpy.mockRestore();

      const orgPlugin = capturedConfig.plugins.find((p: any) => p.id === 'organization');
      const beforeUpdate = orgPlugin._opts.organizationHooks.beforeUpdateOrganization;

      await expect(
        beforeUpdate({
          organization: { slug: 'acme-new' },
          member: { organizationId: 'org-42' },
        }),
      ).resolves.toBeUndefined();
    });

    it('allows non-slug updates (e.g. name only) without env checks', async () => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });

      const dataEngine = {
        findOne: vi.fn(),
        find: vi.fn(),
      };

      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
        plugins: { organization: true },
        dataEngine: dataEngine as any,
      });
      await manager.getAuthInstance();
      warnSpy.mockRestore();

      const orgPlugin = capturedConfig.plugins.find((p: any) => p.id === 'organization');
      const beforeUpdate = orgPlugin._opts.organizationHooks.beforeUpdateOrganization;

      // Updating only `name` — no slug — must short-circuit before any DB read.
      await expect(
        beforeUpdate({
          organization: { name: 'New Name' },
          member: { organizationId: 'org-42' },
        }),
      ).resolves.toBeUndefined();
      expect(dataEngine.findOne).not.toHaveBeenCalled();
      expect(dataEngine.find).not.toHaveBeenCalled();
    });

    // [ADR-0105 D8] afterAcceptInvitation → onInvitationAccepted host seam.
    it('forwards afterAcceptInvitation to onInvitationAccepted with the mapped payload + raw rows', async () => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });

      const onInvitationAccepted = vi.fn();
      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
        plugins: { organization: true },
        onInvitationAccepted,
      });
      await manager.getAuthInstance();
      warnSpy.mockRestore();

      const orgPlugin = capturedConfig.plugins.find((p: any) => p.id === 'organization');
      const afterAccept = orgPlugin._opts.organizationHooks?.afterAcceptInvitation;
      expect(typeof afterAccept).toBe('function');

      // The invitation row carries D8 placement intent as extension fields —
      // the seam hands the RAW row through so the host reads them directly.
      const invitation = { id: 'inv-1', organizationId: 'org-42', email: 'p@x.test', role: 'member', business_unit_id: 'bu-7' };
      const member = { id: 'mem-9', userId: 'u-3', organizationId: 'org-42', role: 'member' };
      await afterAccept({
        invitation,
        member,
        user: { id: 'u-3' },
        organization: { id: 'org-42' },
      });

      expect(onInvitationAccepted).toHaveBeenCalledTimes(1);
      expect(onInvitationAccepted).toHaveBeenCalledWith({
        invitationId: 'inv-1',
        organizationId: 'org-42',
        userId: 'u-3',
        memberId: 'mem-9',
        role: 'member',
        email: 'p@x.test',
        invitation,
        member,
      });
    });

    it('onInvitationAccepted failures are isolated — acceptance never rolls back', async () => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });

      const onInvitationAccepted = vi.fn(async () => {
        throw new Error('placement service down');
      });
      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
        plugins: { organization: true },
        onInvitationAccepted,
      });
      await manager.getAuthInstance();

      const orgPlugin = capturedConfig.plugins.find((p: any) => p.id === 'organization');
      const afterAccept = orgPlugin._opts.organizationHooks.afterAcceptInvitation;

      await expect(
        afterAccept({
          invitation: { id: 'inv-1' },
          member: { id: 'mem-9', userId: 'u-3' },
          user: { id: 'u-3' },
          organization: { id: 'org-42' },
        }),
      ).resolves.toBeUndefined();
      expect(onInvitationAccepted).toHaveBeenCalledTimes(1);
      expect(
        warnSpy.mock.calls.some((c) => String(c[0]).includes('onInvitationAccepted callback failed')),
      ).toBe(true);
      warnSpy.mockRestore();
    });

    it('no onInvitationAccepted configured — the hook is a no-op', async () => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });

      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
        plugins: { organization: true },
      });
      await manager.getAuthInstance();
      warnSpy.mockRestore();

      const orgPlugin = capturedConfig.plugins.find((p: any) => p.id === 'organization');
      const afterAccept = orgPlugin._opts.organizationHooks.afterAcceptInvitation;
      await expect(
        afterAccept({ invitation: { id: 'i' }, member: {}, user: {}, organization: {} }),
      ).resolves.toBeUndefined();
    });

    // ── [ADR-0105 D8] Scoped invitations: issuance gate + accept-time apply ──
    //
    // The security property: authority is judged at ISSUANCE (actor = the
    // inviter) and only the already-approved placement is applied at
    // acceptance (actor = the invitee, who holds no RBAC-write authority).
    const bootWithPlacement = async (placement?: any) => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });
      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
        plugins: { organization: true },
        ...(placement !== undefined ? { invitationPlacement: async () => placement } : {}),
      });
      await manager.getAuthInstance();
      const orgPlugin = capturedConfig.plugins.find((p: any) => p.id === 'organization');
      return { hooks: orgPlugin._opts.organizationHooks, warnSpy };
    };

    const PLACEMENT_INVITE = {
      id: 'inv-1',
      organizationId: 'org-42',
      email: 'p@x.test',
      role: 'member',
      businessUnitId: 'bu_plant_a',
      positions: ['qc_inspector'],
    };

    it('issuance: authorizes placement intent against the ISSUER, not the invitee', async () => {
      const assertIssuable = vi.fn(async () => {});
      const { hooks, warnSpy } = await bootWithPlacement({ assertIssuable, apply: vi.fn() });
      warnSpy.mockRestore();

      await hooks.beforeCreateInvitation({
        invitation: PLACEMENT_INVITE,
        inviter: { id: 'u_issuer' },
        organization: { id: 'org-42' },
      });

      expect(assertIssuable).toHaveBeenCalledTimes(1);
      // WHO issued, not a context: the service resolves the issuer's real
      // grants through the shared authz resolver. Handing it a hand-built
      // context was the #3663 defect — it carried no positions, so the gate
      // refused every delegate.
      expect(assertIssuable).toHaveBeenCalledWith({
        intent: { businessUnitId: 'bu_plant_a', positions: ['qc_inspector'] },
        actorUserId: 'u_issuer',
        organizationId: 'org-42',
      });
    });

    /**
     * [#24243] A placement answer asserted on its envelope (ADR-0112): the
     * status and the `code` better-auth serialises into the body.
     */
    const placementAnswer = async (attempt: Promise<unknown>) => {
      const err = (await attempt.then(
        () => undefined,
        (e: unknown) => e,
      )) as
        | { status?: unknown; statusCode?: unknown; body?: { code?: unknown; message?: unknown }; cause?: unknown }
        | undefined;
      expect(err, 'the invitation was admitted').toBeTruthy();
      return err;
    };

    it('issuance: a refused placement REJECTS the whole invitation (no row is created)', async () => {
      // The gate's own refusal, in the shape `invitation-placement.ts` throws
      // it: plugin-security's `PermissionDeniedError`, read by its ADR-0112
      // code. A structural stand-in, because importing plugin-security here
      // measured roughly 1–2 s more import time on this file; the real class
      // reaches this catch on the wire in the dogfood `delegated-admin-invite`
      // file.
      const assertIssuable = vi.fn(async () => {
        throw Object.assign(new Error("business unit 'bu_plant_b' is outside the delegated subtree"), {
          name: 'PermissionDeniedError',
          code: 'PERMISSION_DENIED',
          status: 403,
          statusCode: 403,
        });
      });
      const { hooks, warnSpy } = await bootWithPlacement({ assertIssuable, apply: vi.fn() });
      warnSpy.mockRestore();

      const err = await placementAnswer(
        hooks.beforeCreateInvitation({
          invitation: PLACEMENT_INVITE,
          inviter: { id: 'u_issuer' },
          organization: { id: 'org-42' },
        }),
      );
      expect(err?.statusCode).toBe(403);
      expect(err?.status).toBe('FORBIDDEN');
      expect(err?.body?.code).toBe('INVITE_PLACEMENT_OUTSIDE_ISSUER_SCOPE');
      // The gate's verdict is relayed as its message.
      expect(String(err?.body?.message)).toMatch(/outside the delegated subtree/);
    });

    it('issuance: the gate\'s scope-violation refusal (DELEGATION_SCOPE_VIOLATION) is the same verdict — 403 INVITE_PLACEMENT_OUTSIDE_ISSUER_SCOPE, not an outage', async () => {
      // [#26189] A refusal that describes the issuer's own delegated scope (a
      // unit outside the subtree, a set off the allowlist) now carries its own
      // code. It is still the gate's verdict, so the invitation answers what
      // it answered before. Structural stand-in, as above.
      const assertIssuable = vi.fn(async () => {
        throw Object.assign(new Error("[Security] Outside your delegated scope: business unit 'bu_plant_b' is outside the delegated subtree"), {
          name: 'DelegationScopeViolationError',
          code: 'DELEGATION_SCOPE_VIOLATION',
          status: 403,
          statusCode: 403,
        });
      });
      const { hooks, warnSpy } = await bootWithPlacement({ assertIssuable, apply: vi.fn() });
      warnSpy.mockRestore();

      const err = await placementAnswer(
        hooks.beforeCreateInvitation({
          invitation: PLACEMENT_INVITE,
          inviter: { id: 'u_issuer' },
          organization: { id: 'org-42' },
        }),
      );
      expect(err?.statusCode).toBe(403);
      expect(err?.body?.code).toBe('INVITE_PLACEMENT_OUTSIDE_ISSUER_SCOPE');
      expect(String(err?.body?.message)).toMatch(/outside the delegated subtree/);
    });

    it('issuance: a store fault out of the placement check is an outage (503 SERVICE_UNAVAILABLE), not a scope refusal', async () => {
      // [#24243] `assertIssuable` resolves the issuer's grants from the store
      // BEFORE the gate runs; a store that cannot answer throws there, as the
      // shared resolver's loud failure. Pinned at the unit level: on a booted
      // stack the store answers, so no request reaches this arm on demand.
      const fault = new AuthzStoreUnavailableError('sys_user_position', new Error('connection refused'));
      const assertIssuable = vi.fn(async () => {
        throw fault;
      });
      const { hooks, warnSpy } = await bootWithPlacement({ assertIssuable, apply: vi.fn() });
      warnSpy.mockRestore();

      const err = await placementAnswer(
        hooks.beforeCreateInvitation({
          invitation: PLACEMENT_INVITE,
          inviter: { id: 'u_issuer' },
          organization: { id: 'org-42' },
        }),
      );
      expect(err?.statusCode).toBe(503);
      expect(err?.status).toBe('SERVICE_UNAVAILABLE');
      expect(err?.body?.code).toBe('SERVICE_UNAVAILABLE');
      // Not the refusal's code, and the store's own text does not ride the body.
      expect(err?.body?.code).not.toBe('INVITE_PLACEMENT_OUTSIDE_ISSUER_SCOPE');
      expect(String(err?.body?.message)).not.toContain('connection refused');
      // The failure is kept for the operator.
      expect(err?.cause).toBe(fault);
    });

    it('issuance: NO placement runtime ⇒ a placement-carrying invitation is refused (fail closed)', async () => {
      // Without plugin-security there is no gate; honouring the request would
      // hand org_admin the RBAC-write authority it is deliberately denied.
      // [#24243] Pinned at the unit level: the dogfood harness (`bootStack`)
      // always boots plugin-security, which registers the placement service,
      // so no door on a stock dogfood boot reaches this refusal.
      const { hooks, warnSpy } = await bootWithPlacement(undefined);
      warnSpy.mockRestore();

      const err = await placementAnswer(
        hooks.beforeCreateInvitation({
          invitation: PLACEMENT_INVITE,
          inviter: { id: 'u_issuer' },
          organization: { id: 'org-42' },
        }),
      );
      expect(err?.statusCode).toBe(403);
      expect(err?.body?.code).toBe('INVITE_PLACEMENT_UNSUPPORTED');
      expect(String(err?.body?.message)).toMatch(/requires the delegated-administration runtime/);
    });

    it('issuance: an ordinary invitation (no placement) never consults the gate', async () => {
      const assertIssuable = vi.fn(async () => {});
      const { hooks, warnSpy } = await bootWithPlacement({ assertIssuable, apply: vi.fn() });
      warnSpy.mockRestore();

      await expect(
        hooks.beforeCreateInvitation({
          invitation: { id: 'inv-2', organizationId: 'org-42', email: 'e@x.test', role: 'member' },
          inviter: { id: 'u_issuer' },
          organization: { id: 'org-42' },
        }),
      ).resolves.toBeUndefined();
      expect(assertIssuable).not.toHaveBeenCalled();
    });

    it('acceptance: applies the approved placement, stamping the issuer as grantor', async () => {
      const apply = vi.fn(async () => ({ created: 1, skipped: 0 }));
      const { hooks, warnSpy } = await bootWithPlacement({ assertIssuable: vi.fn(), apply });
      warnSpy.mockRestore();

      await hooks.afterAcceptInvitation({
        invitation: { ...PLACEMENT_INVITE, inviterId: 'u_issuer' },
        member: { id: 'mem-9', userId: 'u-3', organizationId: 'org-42' },
        user: { id: 'u-3' },
        organization: { id: 'org-42' },
      });

      expect(apply).toHaveBeenCalledWith({
        intent: { businessUnitId: 'bu_plant_a', positions: ['qc_inspector'] },
        userId: 'u-3',
        organizationId: 'org-42',
        grantedBy: 'u_issuer',
      });
    });

    it('acceptance: a placement failure keeps the membership and still fires the host seam', async () => {
      const apply = vi.fn(async () => {
        throw new Error('bu vanished');
      });
      const onInvitationAccepted = vi.fn();
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });
      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
        plugins: { organization: true },
        invitationPlacement: async () => ({ assertIssuable: vi.fn(), apply }) as never,
        onInvitationAccepted,
      });
      await manager.getAuthInstance();
      const orgPlugin = capturedConfig.plugins.find((p: any) => p.id === 'organization');

      await expect(
        orgPlugin._opts.organizationHooks.afterAcceptInvitation({
          invitation: PLACEMENT_INVITE,
          member: { id: 'mem-9', userId: 'u-3' },
          user: { id: 'u-3' },
          organization: { id: 'org-42' },
        }),
      ).resolves.toBeUndefined();

      expect(
        warnSpy.mock.calls.some((c) => String(c[0]).includes('invitation placement failed')),
      ).toBe(true);
      warnSpy.mockRestore();
      // The host seam is independent of placement — it still runs.
      expect(onInvitationAccepted).toHaveBeenCalledTimes(1);
    });

    // ── [ADR-0105 D8 / #3697] The scope-bounded issuance path gets a caller ──
    //
    // Two halves, and they only make sense together: `delegated_admin` is the
    // one org role that may reach `/organization/invite-member` WITHOUT being
    // an org admin (giving the D8 gate a caller at last), and the role cap
    // stops that role from being a ladder to tenant admin.
    const bootOrgPlugin = async (opts: Record<string, unknown> = {}) => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });
      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
        plugins: { organization: true },
        ...opts,
      });
      await manager.getAuthInstance();
      warnSpy.mockRestore();
      return capturedConfig.plugins.find((p: any) => p.id === 'organization');
    };

    /** A `sys_member` reader stand-in — the shape `resolveMembershipRole` uses.
     *  `role: null` = no membership row, i.e. an issuer whose grade cannot be
     *  established. */
    const engineWithMemberRole = (role: string | null) => ({
      find: vi.fn(async (object: string) =>
        object === 'sys_member' && role !== null ? [{ role }] : [],
      ),
      findOne: vi.fn(async (object: string, query?: EngineFindOneQueryInput) => { assertEngineFindOnePredicate(object, query); return null; }),
      count: vi.fn(async () => 0),
      insert: vi.fn(async () => ({})),
      update: vi.fn(async (_o: string, data: any, options?: any) => {
        assertEngineUpdateDispatch(data, options);
        return {};
      }),
      delete: vi.fn(async (_o: string, options?: any) => {
        assertEngineDeleteDispatch(options);
        return undefined;
      }),
    });

    it('registers `delegated_admin` with invitation:create — the gate finally has a caller', async () => {
      const orgPlugin = await bootOrgPlugin();

      const roles = orgPlugin._opts.roles;
      expect(roles).toBeDefined();
      // The whole point: a role that can invite without being owner/admin.
      expect(roles.delegated_admin.statements.invitation).toEqual(['create']);
      // …and NOT `cancel`: better-auth's cancel route checks only the
      // permission, with no inviterId attribution, so it would mean "cancel
      // anyone's pending invitation in the org".
      expect(roles.delegated_admin.statements.invitation).not.toContain('cancel');
      // Otherwise it is a plain member — no org/member/team/ac authority.
      expect(roles.delegated_admin.statements.member).toEqual([]);
      expect(roles.delegated_admin.statements.organization).toEqual([]);
      expect(roles.delegated_admin.statements.team).toEqual([]);
    });

    it('the custom map keeps the built-in owner/admin/member intact', async () => {
      // better-auth's `hasPermission` does `{...options.roles || defaultRoles}`,
      // so a custom map that omits the defaults silently strips `owner`'s
      // `invitation:create` and 403s every mutation.
      const orgPlugin = await bootOrgPlugin();

      const roles = orgPlugin._opts.roles;
      expect(Object.keys(roles)).toEqual(
        expect.arrayContaining(['owner', 'admin', 'member', 'delegated_admin']),
      );
      expect(roles.owner.statements.invitation).toContain('create');
      expect(roles.admin.statements.invitation).toContain('create');
      expect(roles.member.statements.invitation).toEqual([]);
    });

    it('[ADR-0108] the vocabulary is closed — no app-declared role is registered', async () => {
      // The retired channel, asserted as retired. `additionalOrgRoles` is gone
      // from the options; passing the name anyway (an unmigrated host, or a
      // stack whose `position` metadata declares it) must not put it in the
      // map. If it did, the name would be storable in `sys_member.role`, and
      // `resolve-authz-context` projects that column into
      // `current_user.positions` — capability with no `granted_by`, no
      // validity window and no subtree/allowlist check (ADR-0090 D12).
      const orgPlugin = await bootOrgPlugin({ additionalOrgRoles: ['sales_rep'] } as never);

      const roles = orgPlugin._opts.roles;
      expect(Object.keys(roles).sort()).toEqual(['admin', 'delegated_admin', 'external', 'member', 'owner']);
      expect(roles.sales_rep).toBeUndefined();
      // [Ruling 6355206139] `external` holds no organization statement at all.
      for (const [resource, actions] of Object.entries(roles.external.statements)) {
        expect(actions, resource).toEqual([]);
      }
    });

    /**
     * [#23945] A cap refusal asserted on its envelope (ADR-0112): the status
     * and the `code` better-auth serialises into the body — never the bare
     * throw, which a codeless `FORBIDDEN` passes just as well.
     */
    const capAnswer = async (attempt: Promise<unknown>) => {
      const err = (await attempt.then(
        () => undefined,
        (e: unknown) => e,
      )) as
        | { status?: unknown; statusCode?: unknown; body?: { code?: unknown; message?: unknown }; cause?: unknown }
        | undefined;
      expect(err, 'the invitation was admitted').toBeTruthy();
      return err;
    };
    const inviteAs = (orgPlugin: any, role: string, inviterId = 'u_delegate') =>
      orgPlugin._opts.organizationHooks.beforeCreateInvitation({
        invitation: { organizationId: 'org-42', email: 'e@x.test', role },
        inviter: { id: inviterId },
        organization: { id: 'org-42' },
      });

    it('role cap: a delegate inviting an `admin` is REFUSED (the escalation chain)', async () => {
      // delegate invites admin → sys_member(role='admin') → auto-org-admin-grant
      // → organization_admin → wildcard modifyAllRecords → isTenantAdmin().
      const orgPlugin = await bootOrgPlugin({
        dataEngine: engineWithMemberRole('delegated_admin') as never,
      });

      const err = await capAnswer(inviteAs(orgPlugin, 'admin'));
      expect(err?.statusCode).toBe(403);
      expect(err?.status).toBe('FORBIDDEN');
      expect(err?.body?.code).toBe('INVITE_ROLE_ABOVE_ISSUER');
    });

    it('role cap: a delegate minting another delegate is REFUSED as member-only, not as outranked', async () => {
      const orgPlugin = await bootOrgPlugin({
        dataEngine: engineWithMemberRole('delegated_admin') as never,
      });

      const err = await capAnswer(inviteAs(orgPlugin, 'delegated_admin'));
      expect(err?.statusCode).toBe(403);
      expect(err?.body?.code).toBe('INVITE_ISSUER_MEMBER_ONLY');
    });

    it('role cap: a delegate inviting a plain `member` passes — and costs no lookup', async () => {
      const engine = engineWithMemberRole('delegated_admin');
      const orgPlugin = await bootOrgPlugin({ dataEngine: engine as never });
      engine.find.mockClear();

      await expect(
        orgPlugin._opts.organizationHooks.beforeCreateInvitation({
          invitation: { organizationId: 'org-42', email: 'e@x.test', role: 'member' },
          inviter: { id: 'u_delegate' },
          organization: { id: 'org-42' },
        }),
      ).resolves.toBeUndefined();
      expect(engine.find).not.toHaveBeenCalled();
    });

    it('role cap: an org owner inviting an `admin` is unaffected', async () => {
      const orgPlugin = await bootOrgPlugin({
        dataEngine: engineWithMemberRole('owner') as never,
      });

      await expect(
        orgPlugin._opts.organizationHooks.beforeCreateInvitation({
          invitation: { organizationId: 'org-42', email: 'e@x.test', role: 'admin' },
          inviter: { id: 'u_owner' },
          organization: { id: 'org-42' },
        }),
      ).resolves.toBeUndefined();
    });

    it('role cap: an unresolvable issuer membership fails CLOSED', async () => {
      // Pinned HERE, not on the wire: through `POST /organization/invite-member`
      // this input is not reachable. better-auth reads the inviter's membership
      // before the hook runs and refuses a non-member (`MEMBER_NOT_FOUND`, 400)
      // or a role without `invitation:create` (403) first, and the cap re-reads
      // the same `sys_member` rows in system context — so a read that answers
      // "no usable row" needs the row to vanish between the two reads.
      const orgPlugin = await bootOrgPlugin({
        dataEngine: engineWithMemberRole(null) as never,
      });

      const err = await capAnswer(inviteAs(orgPlugin, 'admin', 'u_ghost'));
      expect(err?.statusCode).toBe(403);
      expect(err?.body?.code).toBe('INVITE_ISSUER_UNVERIFIED');
    });

    it('role cap: NO data engine to read fails CLOSED too — "cannot check" is never "does not apply"', async () => {
      // Not reachable through `AuthPlugin`, which hard-depends on ObjectQL and
      // always passes its `data` service; only a bare `AuthManager` built
      // without `dataEngine` (better-auth then runs on its in-memory adapter)
      // reaches the hook with nothing to read.
      const orgPlugin = await bootOrgPlugin();

      const err = await capAnswer(inviteAs(orgPlugin, 'admin', 'u_any'));
      expect(err?.statusCode).toBe(403);
      expect(err?.body?.code).toBe('INVITE_ISSUER_UNVERIFIED');
    });

    it('role cap: a membership read that THROWS is an outage (503 SERVICE_UNAVAILABLE), not a refusal', async () => {
      // An owner's invitation, so the only thing between it and admission is
      // the read: the verdict the store would have given is "admitted".
      const engine = engineWithMemberRole('owner');
      engine.find.mockImplementation(async () => {
        throw new Error('store unavailable');
      });
      const orgPlugin = await bootOrgPlugin({ dataEngine: engine as never });

      const err = await capAnswer(inviteAs(orgPlugin, 'admin', 'u_owner'));
      expect(err?.statusCode).toBe(503);
      expect(err?.status).toBe('SERVICE_UNAVAILABLE');
      expect(err?.body?.code).toBe('SERVICE_UNAVAILABLE');
      expect(err?.body?.code).not.toBe('INVITE_ISSUER_UNVERIFIED');
      // The driver's own failure is kept for the operator.
      expect((err?.cause as Error | undefined)?.message).toBe('store unavailable');
      expect(engine.find).toHaveBeenCalledTimes(1);
    });

    it('role cap: it runs BEFORE the placement gate and applies without placement intent', async () => {
      // The escalation is independent of placement — a role-capped invitation
      // must be refused whether or not it carries a business unit.
      const assertIssuable = vi.fn(async () => {});
      const orgPlugin = await bootOrgPlugin({
        dataEngine: engineWithMemberRole('delegated_admin') as never,
        invitationPlacement: async () => ({ assertIssuable, apply: vi.fn() }) as never,
      });

      await expect(
        orgPlugin._opts.organizationHooks.beforeCreateInvitation({
          invitation: {
            organizationId: 'org-42',
            email: 'e@x.test',
            role: 'admin',
            businessUnitId: 'bu_plant_a',
            positions: ['qc_inspector'],
          },
          inviter: { id: 'u_delegate' },
          organization: { id: 'org-42' },
        }),
      ).rejects.toMatchObject({ statusCode: 403, body: { code: 'INVITE_ROLE_ABOVE_ISSUER' } });
      // Refused before the placement gate was ever consulted.
      expect(assertIssuable).not.toHaveBeenCalled();
    });

    // ── [ADR-0120 D3] `'__global__'` is reserved at the org-minting seam ──
    //
    // The token names the NULL-organization ("platform") bucket in every
    // organization-scoped unique index (`COALESCE(organization_id,
    // '__global__')`) and in the autonumber sequence table. An organization
    // minted with it as id or slug would collide with that bucket.
    describe("'__global__' organization id/slug reservation (ADR-0120 D3)", () => {
      const OLD_MULTI = process.env.OS_MULTI_ORG_ENABLED;
      beforeEach(() => {
        process.env.OS_MULTI_ORG_ENABLED = 'true';
      });
      afterEach(() => {
        if (OLD_MULTI === undefined) delete process.env.OS_MULTI_ORG_ENABLED;
        else process.env.OS_MULTI_ORG_ENABLED = OLD_MULTI;
      });

      /**
       * [#24243] The reservation's envelope (ADR-0112): 400 with the standard
       * `VALIDATION_ERROR`, a value the request may not carry.
       */
      const RESERVED_IDENTIFIER_ANSWER = { statusCode: 400, status: 'BAD_REQUEST', body: { code: 'VALIDATION_ERROR' } };

      it("rejects an organization whose slug is '__global__'", async () => {
        const orgPlugin = await bootOrgPlugin();
        const attempt = orgPlugin._opts.organizationHooks.beforeCreateOrganization({
          organization: { name: 'Global Inc', slug: '__global__' },
          user: { id: 'u1' },
        });
        await expect(attempt).rejects.toThrow(/'__global__' is reserved .* \(ADR-0120 D3\)/);
        await expect(attempt).rejects.toMatchObject(RESERVED_IDENTIFIER_ANSWER);
      });

      it("rejects an organization whose id is '__global__'", async () => {
        const orgPlugin = await bootOrgPlugin();
        const attempt = orgPlugin._opts.organizationHooks.beforeCreateOrganization({
          organization: { id: '__global__', name: 'Global Inc', slug: 'global-inc' },
          user: { id: 'u1' },
        });
        await expect(attempt).rejects.toThrow(/'__global__' is reserved .* \(ADR-0120 D3\)/);
        await expect(attempt).rejects.toMatchObject(RESERVED_IDENTIFIER_ANSWER);
      });

      it('an ordinary organization passes the reservation guard', async () => {
        const orgPlugin = await bootOrgPlugin();
        await expect(
          orgPlugin._opts.organizationHooks.beforeCreateOrganization({
            organization: { name: 'Acme', slug: 'acme' },
            user: { id: 'u1' },
          }),
        ).resolves.toBeUndefined();
      });

      it('the reservation is judged before the multi-org gate (precise error in single-org mode too)', async () => {
        delete process.env.OS_MULTI_ORG_ENABLED; // default: single-org
        const orgPlugin = await bootOrgPlugin();
        const attempt = orgPlugin._opts.organizationHooks.beforeCreateOrganization({
          organization: { name: 'Global Inc', slug: '__global__' },
          user: { id: 'u1' },
        });
        await expect(attempt).rejects.toThrow(/'__global__' is reserved/);
        // [#24243] …and its code, not the posture gate's `ORGANIZATION_CREATION_DISABLED`.
        await expect(attempt).rejects.toMatchObject(RESERVED_IDENTIFIER_ANSWER);
      });
    });

    it('should register twoFactor plugin with schema mapping when enabled', async () => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });

      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
        plugins: { twoFactor: true },
      });
      await manager.getAuthInstance();
      warnSpy.mockRestore();

      const tfPlugin = capturedConfig.plugins.find((p: any) => p.id === 'two-factor');
      expect(tfPlugin).toBeDefined();
      expect(tfPlugin._opts.schema.twoFactor.modelName).toBe('sys_two_factor');
      expect(tfPlugin._opts.schema.twoFactor.fields.backupCodes).toBe('backup_codes');
      expect(tfPlugin._opts.schema.twoFactor.fields.userId).toBe('user_id');
      expect(tfPlugin._opts.schema.user.fields.twoFactorEnabled).toBe('two_factor_enabled');
    });

    // #3690 — the operator's lockout policy has to reach the SECOND factor too.
    // Before this, `twoFactor()` got only a schema, so the second factor sat on
    // better-auth's built-in 10/900s no matter how the admin tuned sign-in:
    // tightening the threshold to 3 left the last door before a session at 10.
    describe('two-factor account lockout follows the operator settings (#3690)', () => {
      const buildTwoFactor = async (extra: Record<string, unknown>) => {
        let capturedConfig: any;
        (betterAuth as any).mockImplementation((config: any) => {
          capturedConfig = config;
          return { handler: vi.fn(), api: {} };
        });
        const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
        const manager = new AuthManager({
          secret: 'test-secret-at-least-32-chars-long',
          baseUrl: 'http://localhost:3000',
          plugins: { twoFactor: true },
          ...extra,
        });
        await manager.getAuthInstance();
        warnSpy.mockRestore();
        return capturedConfig.plugins.find((p: any) => p.id === 'two-factor')._opts.accountLockout;
      };

      it('projects lockoutThreshold / lockoutDurationMinutes onto better-auth\'s contract', async () => {
        // Minutes → seconds is the whole reason this needs a test: the two
        // sides use different units for the same policy.
        expect(await buildTwoFactor({ lockoutThreshold: 3, lockoutDurationMinutes: 30 })).toEqual({
          enabled: true,
          maxFailedAttempts: 3,
          durationSeconds: 1800,
        });
      });

      it('falls back to the password stage\'s 15-minute default when only a threshold is set', async () => {
        expect(await buildTwoFactor({ lockoutThreshold: 5 })).toEqual({
          enabled: true,
          maxFailedAttempts: 5,
          durationSeconds: 900,
        });
      });

      // Threshold 0 is the password stage's "off". It is NOT forwarded as
      // `enabled: false`: a deployment may leave the password stage unlocked
      // because rate limiting or an IdP covers it, while the second factor —
      // the last check before a session — keeps better-auth's default. Leaving
      // the option unset is what hands that default back.
      for (const [label, extra] of [
        ['threshold 0 (lockout explicitly off)', { lockoutThreshold: 0 }],
        ['no lockout settings at all', {}],
      ] as Array<[string, Record<string, unknown>]>) {
        it(`leaves better-auth's own default in place with ${label}`, async () => {
          expect(await buildTwoFactor(extra)).toBeUndefined();
        });
      }
    });

    it('should register magicLink plugin when enabled', async () => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });

      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
        plugins: { magicLink: true },
      });
      await manager.getAuthInstance();
      warnSpy.mockRestore();

      const mlPlugin = capturedConfig.plugins.find((p: any) => p.id === 'magic-link');
      expect(mlPlugin).toBeDefined();
    });

    it('should register multiple plugins when multiple flags are enabled', async () => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });

      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
        plugins: { organization: true, twoFactor: true, magicLink: true },
      });
      await manager.getAuthInstance();
      warnSpy.mockRestore();

      expect(capturedConfig.plugins).toHaveLength(5);
      expect(capturedConfig.plugins.map((p: any) => p.id).sort()).toEqual(
        ['bearer', 'magic-link', 'objectstack-agent-forward-identity-view', 'organization', 'two-factor'],
      );
    });
  });

  describe('bearer plugin (cross-origin / mobile token auth)', () => {
    it('should always register the bearer plugin regardless of other flags', async () => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });

      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
        plugins: { organization: true },
      });
      await manager.getAuthInstance();
      warnSpy.mockRestore();

      const bearerPlugin = capturedConfig.plugins.find((p: any) => p.id === 'bearer');
      expect(bearerPlugin).toBeDefined();
    });
  });

  describe('trustedOrigins passthrough', () => {
    it('should forward trustedOrigins to betterAuth when provided', async () => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });

      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
        trustedOrigins: ['https://*.objectos.app', 'http://localhost:*'],
      });
      await manager.getAuthInstance();
      warnSpy.mockRestore();

      expect(capturedConfig.trustedOrigins).toEqual([
        'https://*.objectos.app',
        'http://localhost:*',
      ]);
    });

    it('should default to localhost wildcard when trustedOrigins not provided', async () => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });

      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
      });
      await manager.getAuthInstance();
      warnSpy.mockRestore();

      expect(capturedConfig.trustedOrigins).toEqual([
        'http://localhost:*',
        'http://*.localhost:*',
        'https://*.localhost:*',
      ]);
    });

    it('should default to localhost wildcard when trustedOrigins array is empty', async () => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });

      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
        trustedOrigins: [],
      });
      await manager.getAuthInstance();
      warnSpy.mockRestore();

      expect(capturedConfig.trustedOrigins).toEqual([
        'http://localhost:*',
        'http://*.localhost:*',
        'https://*.localhost:*',
      ]);
    });
  });

  // commit bbe643c08 — the localhost-wildcard trio is a DEVELOPMENT convenience and is
  // gated on `NODE_ENV !== 'production'`. Before the gate the condition tested
  // only emptiness, so a production deployment whose trusted-origin list
  // resolved empty silently CSRF-trusted every `localhost` / `*.localhost`
  // origin. These pins enforce the boundary in BOTH directions: production
  // must not substitute, and non-production must still substitute.
  describe('trustedOrigins localhost substitution is non-production only (#10366)', () => {
    const TRIO = ['http://localhost:*', 'http://*.localhost:*', 'https://*.localhost:*'];

    const ENV_KEYS = ['NODE_ENV', 'OS_CORS_ORIGIN', 'CORS_ORIGIN', 'OS_SSO_ENABLED'] as const;
    let saved: Record<string, string | undefined>;

    beforeEach(() => {
      saved = Object.fromEntries(ENV_KEYS.map(k => [k, process.env[k]]));
      for (const k of ENV_KEYS) delete process.env[k];
    });

    afterEach(() => {
      for (const k of ENV_KEYS) {
        if (saved[k] === undefined) delete process.env[k];
        else process.env[k] = saved[k]!;
      }
    });

    async function captureConfig(config: Record<string, unknown>): Promise<any> {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((c: any) => {
        capturedConfig = c;
        return { handler: vi.fn(), api: {} };
      });
      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'https://app.example.com',
        ...config,
      } as any);
      await manager.getAuthInstance();
      warnSpy.mockRestore();
      return capturedConfig;
    }

    describe('production does not substitute', () => {
      it('omits the trustedOrigins key entirely when none is provided', async () => {
        process.env.NODE_ENV = 'production';
        const cfg = await captureConfig({});

        expect(cfg.trustedOrigins).toBeUndefined();
        // Absent, not merely empty — the key must not appear at all, which is
        // the shape better-auth receives.
        expect('trustedOrigins' in cfg).toBe(false);
      });

      it('omits the trustedOrigins key entirely when an empty array is provided', async () => {
        process.env.NODE_ENV = 'production';
        const cfg = await captureConfig({ trustedOrigins: [] });

        expect(cfg.trustedOrigins).toBeUndefined();
        expect('trustedOrigins' in cfg).toBe(false);
      });
    });

    describe('non-production still substitutes', () => {
      it("substitutes the trio under NODE_ENV='development'", async () => {
        process.env.NODE_ENV = 'development';
        const cfg = await captureConfig({});

        expect(cfg.trustedOrigins).toEqual(TRIO);
      });

      // Guards against "hardening" the predicate to `=== 'development'`, which
      // would be a STRICTER boundary than ruled and would break `test` and
      // unset-NODE_ENV development flows.
      it("substitutes the trio under NODE_ENV='test'", async () => {
        process.env.NODE_ENV = 'test';
        const cfg = await captureConfig({});

        expect(cfg.trustedOrigins).toEqual(TRIO);
      });

      it('substitutes the trio when NODE_ENV is unset', async () => {
        delete process.env.NODE_ENV;
        const cfg = await captureConfig({});

        expect(cfg.trustedOrigins).toEqual(TRIO);
      });
    });

    // LOAD-BEARING: without these two legs, a change that broke ALL origin
    // trust in production would still pass a substitution-only suite.
    describe('production leaves real configured trust intact', () => {
      it('forwards an explicitly configured trustedOrigins list unchanged', async () => {
        process.env.NODE_ENV = 'production';
        const cfg = await captureConfig({
          trustedOrigins: ['https://app.example.com', 'https://*.example.com'],
        });

        expect(cfg.trustedOrigins).toEqual([
          'https://app.example.com',
          'https://*.example.com',
        ]);
      });

      it('forwards an OS_CORS_ORIGIN-derived list unchanged', async () => {
        process.env.NODE_ENV = 'production';
        process.env.OS_CORS_ORIGIN = 'https://app.example.com,https://admin.example.com';
        const cfg = await captureConfig({});

        expect(cfg.trustedOrigins).toEqual([
          'https://app.example.com',
          'https://admin.example.com',
        ]);
      });
    });

    // The SSO branch returns `trustedOrigins` as a per-request FUNCTION built
    // from a copy of the same `origins` array, so gating the push at the source
    // covers this shape too. That is true today and is exactly the kind of
    // coupling a future refactor breaks silently — pin it.
    describe('SSO per-request function shape', () => {
      it('production: the resolved list contains no localhost wildcard', async () => {
        process.env.NODE_ENV = 'production';
        const cfg = await captureConfig({ plugins: { sso: true } });

        expect(typeof cfg.trustedOrigins).toBe('function');
        const resolved: string[] = await cfg.trustedOrigins(undefined);
        for (const entry of TRIO) expect(resolved).not.toContain(entry);
        expect(resolved.some(o => o.includes('localhost'))).toBe(false);
      });

      it('non-production: the resolved list still contains the trio', async () => {
        process.env.NODE_ENV = 'development';
        const cfg = await captureConfig({ plugins: { sso: true } });

        expect(typeof cfg.trustedOrigins).toBe('function');
        const resolved: string[] = await cfg.trustedOrigins(undefined);
        for (const entry of TRIO) expect(resolved).toContain(entry);
      });
    });
  });

  describe('setRuntimeBaseUrl', () => {
    it('should update baseURL before auth instance is created', async () => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });

      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
      });

      manager.setRuntimeBaseUrl('http://localhost:3002');
      await manager.getAuthInstance();
      warnSpy.mockRestore();

      expect(capturedConfig.baseURL).toBe('http://localhost:3002');
    });

    it('should be a no-op and warn when called after auth instance is created', async () => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });

      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
      });

      // Force auth instance creation
      await manager.getAuthInstance();
      expect(capturedConfig.baseURL).toBe('http://localhost:3000');

      // Now try to change — should warn and not affect the already-created instance
      manager.setRuntimeBaseUrl('http://localhost:4000');

      expect(warnSpy).toHaveBeenCalledWith(
        expect.stringContaining('setRuntimeBaseUrl() called after the auth instance was already created'),
      );
      warnSpy.mockRestore();
    });

    it('passes an absolute https:// baseURL to better-auth when baseUrl is a bare host', async () => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });

      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'cloud.objectos.ai',
      });
      await manager.getAuthInstance();
      warnSpy.mockRestore();

      // reset-password / verify-email / magic-link email links are derived
      // from this baseURL — it must carry a scheme or they are unclickable.
      expect(capturedConfig.baseURL).toBe('https://cloud.objectos.ai');
    });

    it('should override the default fallback (localhost:3000) when no baseUrl was configured', async () => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });

      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
      });

      manager.setRuntimeBaseUrl('http://localhost:3002');
      await manager.getAuthInstance();
      warnSpy.mockRestore();

      expect(capturedConfig.baseURL).toBe('http://localhost:3002');
    });
  });

  describe('socialProviders passthrough', () => {
    it('should forward socialProviders to betterAuth when provided', async () => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });

      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
        socialProviders: {
          google: { clientId: 'gid', clientSecret: 'gsecret' },
          github: { clientId: 'ghid', clientSecret: 'ghsecret' },
        },
      });
      await manager.getAuthInstance();
      warnSpy.mockRestore();

      expect(capturedConfig.socialProviders).toEqual({
        google: { clientId: 'gid', clientSecret: 'gsecret' },
        github: { clientId: 'ghid', clientSecret: 'ghsecret' },
      });
    });

    it('should NOT include socialProviders when not provided', async () => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });

      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
      });
      await manager.getAuthInstance();
      warnSpy.mockRestore();

      expect(capturedConfig).not.toHaveProperty('socialProviders');
    });
  });

  describe('onAPIError.errorURL (objectui#2458 item 1)', () => {
    it('points browser-flow errors at the console login page so ?error= is surfaced', async () => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });

      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
      });
      await manager.getAuthInstance();
      warnSpy.mockRestore();

      // Default error redirect (`${baseURL}/error` → `/?error=…`) loses the
      // query on the root→console bounce; the login page renders it instead.
      expect(capturedConfig.onAPIError).toEqual({
        errorURL: 'http://localhost:3000/_console/login',
      });
    });
  });

  describe('emailAndPassword passthrough', () => {
    it('should default emailAndPassword to enabled: true', async () => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });

      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
      });
      await manager.getAuthInstance();
      warnSpy.mockRestore();

      expect(capturedConfig.emailAndPassword.enabled).toBe(true);
    });

    it('should forward extended emailAndPassword options', async () => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });

      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
        emailAndPassword: {
          enabled: true,
          minPasswordLength: 12,
          maxPasswordLength: 64,
          requireEmailVerification: true,
          autoSignIn: false,
        },
      });
      await manager.getAuthInstance();
      warnSpy.mockRestore();

      expect(capturedConfig.emailAndPassword).toMatchObject({
        enabled: true,
        minPasswordLength: 12,
        maxPasswordLength: 64,
        requireEmailVerification: true,
        autoSignIn: false,
      });
      // better-auth's own option, set by the auth instance whatever the host
      // passes (the spec key of that name is retired; the manager refuses it).
      expect(capturedConfig.emailAndPassword.revokeSessionsOnPasswordReset).toBe(true);
      expect(typeof capturedConfig.emailAndPassword.sendResetPassword).toBe('function');
    });
  });

  describe('emailVerification passthrough', () => {
    it('should forward emailVerification when provided', async () => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });

      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
        emailVerification: {
          sendOnSignUp: true,
          expiresIn: 1800,
        },
      });
      await manager.getAuthInstance();
      warnSpy.mockRestore();

      expect(capturedConfig.emailVerification).toMatchObject({
        sendOnSignUp: true,
        expiresIn: 1800,
      });
      expect(typeof capturedConfig.emailVerification.sendVerificationEmail).toBe('function');
    });

    it('should NOT include emailVerification when not provided', async () => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });

      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
      });
      await manager.getAuthInstance();
      warnSpy.mockRestore();

      expect(capturedConfig).not.toHaveProperty('emailVerification');
    });
  });

  describe('advanced options passthrough', () => {
    it('should forward crossSubDomainCookies when provided', async () => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });

      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
        advanced: {
          crossSubDomainCookies: {
            enabled: true,
            domain: '.objectos.app',
          },
          useSecureCookies: true,
        },
      });
      await manager.getAuthInstance();
      warnSpy.mockRestore();

      expect(capturedConfig.advanced).toEqual({
        crossSubDomainCookies: {
          enabled: true,
          domain: '.objectos.app',
        },
        useSecureCookies: true,
        ipAddress: vendorClientAddressOptions(),
      });
    });

    it('should forward cookiePrefix and disableCSRFCheck', async () => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });

      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
        advanced: {
          disableCSRFCheck: true,
          cookiePrefix: 'objectos',
        },
      });
      await manager.getAuthInstance();
      warnSpy.mockRestore();

      expect(capturedConfig.advanced.disableCSRFCheck).toBe(true);
      expect(capturedConfig.advanced.cookiePrefix).toBe('objectos');
    });

    it('carries only the library client-address source when no advanced option is provided', async () => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });

      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
      });
      await manager.getAuthInstance();
      warnSpy.mockRestore();

      expect(capturedConfig.advanced).toEqual({ ipAddress: vendorClientAddressOptions() });
    });
  });

  // #2766 V1.5 — phone+password sign-in via better-auth's phone-number plugin.
  describe('phone-number plugin (#2766 V1.5)', () => {
    const boot = async (plugins?: any) => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });
      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
        ...(plugins ? { plugins } : {}),
      });
      await manager.getAuthInstance();
      warnSpy.mockRestore();
      return { manager, capturedConfig };
    };

    it('is NOT registered by default', async () => {
      const { capturedConfig } = await boot();
      expect(capturedConfig.plugins.find((p: any) => p.id === 'phone-number')).toBeUndefined();
    });

    it('registers with snake_case schema mapping when enabled', async () => {
      const { capturedConfig } = await boot({ phoneNumber: true });
      const plugin = capturedConfig.plugins.find((p: any) => p.id === 'phone-number');
      expect(plugin).toBeDefined();
    });

    it('features.phoneNumber mirrors the plugin switch', async () => {
      const { manager } = await boot({ phoneNumber: true });
      expect((manager.getPublicConfig() as any).features.phoneNumber).toBe(true);
      expect(manager.isPhoneNumberEnabled()).toBe(true);
      const { manager: off } = await boot();
      expect((off.getPublicConfig() as any).features.phoneNumber).toBe(false);
      expect(off.isPhoneNumberEnabled()).toBe(false);
    });
  });

  // #2780 — phone-number OTP delivered over the SMS service.
  describe('phone-number OTP over SMS (#2780)', () => {
    const PHONE = '+8613800000000';

    const fakeSms = (opts: { failed?: boolean; error?: string } = {}) => {
      const sent: any[] = [];
      return {
        sent,
        service: {
          async send(input: any) {
            sent.push(input);
            return opts.failed
              ? { id: 'sms_1', status: 'failed', error: opts.error ?? 'provider down' }
              : { id: 'sms_1', status: 'sent', messageId: 'prov_1' };
          },
          isConfigured: () => true,
        } as any,
      };
    };

    const bootOtp = async (config: any = {}) => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((cfg: any) => {
        capturedConfig = cfg;
        return { handler: vi.fn(), api: {} };
      });
      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
        plugins: { phoneNumber: true },
        ...config,
      });
      await manager.getAuthInstance();
      warnSpy.mockRestore();
      const plugin = capturedConfig.plugins.find((p: any) => p.id === 'phone-number');
      return { manager, plugin, opts: plugin.options };
    };

    it('passes allowedAttempts explicitly (default 3) and a phone-shape validator', async () => {
      const { opts } = await bootOtp();
      expect(opts.allowedAttempts).toBe(3);
      expect(opts.phoneNumberValidator('+86 138-0000-0000')).toBe(true);
      expect(opts.phoneNumberValidator('bob@example.com')).toBe(false);
    });

    // No deliverable SMS service ⇒ a typed refusal the router can map: an
    // `APIError` carrying 400 + `SMS_SERVICE_REQUIRED`. A plain `Error` here
    // reached the caller as a 500 with a null body (better-call maps only
    // `APIError`); the wire answer is pinned in
    // `phone-otp-no-sms-service-refusal.test.ts`.
    describe('no deliverable SMS service refuses with 400 SMS_SERVICE_REQUIRED', () => {
      const refusalOf = async (run: () => Promise<unknown>): Promise<any> => {
        try {
          await run();
        } catch (e) {
          return e;
        }
        throw new Error('expected the call to reject, but it resolved');
      };

      it('no SMS service wired', async () => {
        const { opts } = await bootOtp();
        const err = await refusalOf(() => opts.sendOTP({ phoneNumber: PHONE, code: '123456' }));
        const { isAPIError } = await import('better-auth/api');
        expect(isAPIError(err)).toBe(true);
        expect(err.status).toBe('BAD_REQUEST');
        expect(err.statusCode).toBe(400);
        expect(err.body?.code).toBe('SMS_SERVICE_REQUIRED');
        expect(String(err.message)).not.toContain('123456');
      });

      it('a log-only SMS transport in production', async () => {
        vi.stubEnv('NODE_ENV', 'production');
        try {
          const { manager, opts } = await bootOtp();
          const sent: unknown[] = [];
          manager.setSmsService({
            async send(input: unknown) {
              sent.push(input);
              return { id: 'sms_log', status: 'sent' };
            },
            isConfigured: () => false,
          } as any);
          const err = await refusalOf(() => opts.sendOTP({ phoneNumber: PHONE, code: '654321' }));
          expect(err.statusCode).toBe(400);
          expect(err.body?.code).toBe('SMS_SERVICE_REQUIRED');
          expect(String(err.message)).not.toContain('654321');
          expect(sent).toHaveLength(0);
        } finally {
          vi.unstubAllEnvs();
        }
      });
    });

    it('sendOTP delivers the code in the SMS body (and only there)', async () => {
      const { manager, opts } = await bootOtp();
      const sms = fakeSms();
      manager.setSmsService(sms.service);

      await opts.sendOTP({ phoneNumber: PHONE, code: '123456' });
      expect(sms.sent).toHaveLength(1);
      expect(sms.sent[0].to).toBe(PHONE);
      expect(sms.sent[0].body).toContain('123456');
      expect(sms.sent[0].templateParams).toEqual({ code: '123456' });
    });

    it('enforces the per-number cooldown at ADMISSION (before-hook), not in sendOTP', async () => {
      const { manager, opts } = await bootOtp();
      const sms = fakeSms();
      manager.setSmsService(sms.service);

      // Admission guard: first request per number passes, immediate second 429s.
      await manager.assertPhoneOtpSendAllowed(PHONE);
      await expect(manager.assertPhoneOtpSendAllowed(PHONE))
        .rejects.toThrow(/Too many verification codes/);

      // The sendOTP callback itself must NOT re-guard: better-auth stores the
      // fresh code BEFORE invoking it, so a rejection at that point would
      // still rotate (void) the previously delivered code. Delivery always
      // proceeds once a request was admitted.
      await opts.sendOTP({ phoneNumber: PHONE, code: '111111' });
      await opts.sendOTP({ phoneNumber: PHONE, code: '222222' });
      expect(sms.sent).toHaveLength(2);
    });

    it('the admission budget spans both flows (send-otp + request-password-reset)', async () => {
      const { manager } = await bootOtp();
      manager.setSmsService(fakeSms().service);

      // One admitted send (whatever the flow) blocks an immediate second one.
      await manager.assertPhoneOtpSendAllowed(PHONE);
      await expect(manager.assertPhoneOtpSendAllowed(PHONE))
        .rejects.toThrow(/Too many verification codes/);
    });

    it('admission is a no-op while OTP is undeliverable (sendOTP fails loudly instead)', async () => {
      const { manager } = await bootOtp();
      // No SMS service wired — the guard must not consume budget or throw.
      await manager.assertPhoneOtpSendAllowed(PHONE);
      await manager.assertPhoneOtpSendAllowed(PHONE);
    });

    it('surfaces a failed SMS delivery WITHOUT the code in the error', async () => {
      const { manager, opts } = await bootOtp();
      const sms = fakeSms({ failed: true });
      manager.setSmsService(sms.service);

      await expect(opts.sendOTP({ phoneNumber: PHONE, code: '555555' }))
        .rejects.toSatisfy((e: Error) => /provider down/.test(e.message) && !e.message.includes('555555'));
    });

    // ── #6039 / #2814 — the deployment-wide daily SMS quota wall ───────────
    //
    // `SmsService.send()` refuses a send past the deployment's daily cost
    // ceiling by RETURNING a failed result whose `error` carries the
    // `TOO_MANY_REQUESTS:` code prefix (#2814) — it cannot throw an HTTP-shaped
    // error, because it is a kernel service with no idea who is calling.
    // Rethrowing that envelope as a plain `Error` made better-call answer
    // **500 with a null body**: its router maps only `APIError`
    // (`isAPIError = err instanceof APIError || err?.name === 'APIError'`,
    // better-call@1.4.0 `dist/utils.mjs:55-56`, consumed at `dist/router.mjs:92`;
    // re-measured 2026-08-23 against the installed copy), and everything
    // else takes the `console.error` + 500 branch (`:93-97`). Meanwhile the
    // per-number wall on the SAME endpoint (`assertPhoneOtpSendAllowed`, in the
    // admission hook) throws a real `APIError('TOO_MANY_REQUESTS')` and answers
    // 429 — so one endpoint spoke with two voices, which is the reverse of what
    // #2814 asked for.
    describe('daily SMS quota refusal reaches the caller as 429 (#6039)', () => {
      /**
       * The refusal envelope an `SmsService` hands back on a quota refusal.
       * Written out here rather than imported: `@objectstack/service-sms`
       * already depends on THIS package (its day counter imports
       * `InProcessCounterStore` / `incrementFixedWindow` from plugin-auth), so
       * importing its `SMS_QUOTA_EXCEEDED_ERROR` back would close a dependency
       * cycle. Source of truth: `SMS_QUOTA_EXCEEDED_CODE` /
       * `SMS_QUOTA_EXCEEDED_ERROR` in
       * `packages/services/service-sms/src/sms-daily-quota.ts`.
       */
      const QUOTA_REFUSAL = 'TOO_MANY_REQUESTS: daily SMS quota exhausted';

      /**
       * The outward shape a client — and better-call's router — actually
       * branches on. Message text is deliberately NOT part of it: the two walls
       * must be indistinguishable in code and status, while each may still say
       * something true (only the per-number wall can name a retry window).
       */
      const outwardShape = (e: any) => ({
        name: e?.name,
        status: e?.status,
        statusCode: e?.statusCode,
        bodyCode: e?.body?.code,
      });

      const rejection = async (run: () => Promise<unknown>): Promise<any> => {
        try {
          await run();
        } catch (e) {
          return e;
        }
        throw new Error('expected the call to reject, but it resolved');
      };

      it('OTP send: rejects with an APIError carrying 429 / TOO_MANY_REQUESTS', async () => {
        const { manager, opts } = await bootOtp();
        manager.setSmsService(fakeSms({ failed: true, error: QUOTA_REFUSAL }).service);

        const err = await rejection(() => opts.sendOTP({ phoneNumber: PHONE, code: '424242' }));
        // Exactly what better-call reads to choose 429 over 500.
        const { isAPIError } = await import('better-auth/api');
        expect(isAPIError(err)).toBe(true);
        expect(err.name).toBe('APIError');
        expect(err.status).toBe('TOO_MANY_REQUESTS');
        expect(err.statusCode).toBe(429);
        // [#24243] The standard ADR-0112 code a client branches on.
        expect(err.body?.code).toBe('RATE_LIMIT_EXCEEDED');
        // #2780 standing requirement: the code never travels in an error.
        expect(String(err.message)).not.toContain('424242');
      });

      it('invitation SMS: same APIError / 429 at the AuthManager boundary', async () => {
        const { manager } = await bootOtp();
        manager.setSmsService(fakeSms({ failed: true, error: QUOTA_REFUSAL }).service);

        const err = await rejection(() => manager.sendPhoneInviteSms(PHONE));
        const { isAPIError } = await import('better-auth/api');
        expect(isAPIError(err)).toBe(true);
        expect(err.status).toBe('TOO_MANY_REQUESTS');
        expect(err.statusCode).toBe(429);
        expect(err.body?.code).toBe('RATE_LIMIT_EXCEEDED');
      });

      it('both walls on the endpoint present the SAME outward shape', async () => {
        const { manager, opts } = await bootOtp();
        manager.setSmsService(fakeSms({ failed: true, error: QUOTA_REFUSAL }).service);

        // Wall A — the per-number cooldown, refused in the admission hook (#2780).
        await manager.assertPhoneOtpSendAllowed(PHONE);
        const perNumber = await rejection(() => manager.assertPhoneOtpSendAllowed(PHONE));
        // Wall B — the deployment's daily quota, refused inside the send (#2814).
        const quota = await rejection(() => opts.sendOTP({ phoneNumber: PHONE, code: '111111' }));

        expect(outwardShape(quota)).toEqual(outwardShape(perNumber));
        // [#24243] One code for both walls: a code per wall would tell them apart.
        // Pinned at the unit level: the dogfood harness mounts no phone-number
        // plugin (`bootStack` builds `AuthPlugin` from its secret alone, and
        // `OS_AUTH_PHONE_NUMBER_ENABLED` is read only by `objectstack serve`),
        // so neither wall has a door on a stock dogfood boot.
        expect(outwardShape(quota)).toEqual({
          name: 'APIError',
          status: 'TOO_MANY_REQUESTS',
          statusCode: 429,
          bodyCode: 'RATE_LIMIT_EXCEEDED',
        });
      });

      it('matches the CODE prefix, so the service may reword the message half', async () => {
        const { manager, opts } = await bootOtp();
        // Only the envelope's `TOO_MANY_REQUESTS` token (the service's spelling,
        // better-call's status name, not an ADR-0112 code) is restated across
        // the package boundary; the prose after the colon is service-owned and
        // free to change without breaking this mapping.
        manager.setSmsService(
          fakeSms({ failed: true, error: 'TOO_MANY_REQUESTS: budget spent for today' }).service,
        );
        const err = await rejection(() => opts.sendOTP({ phoneNumber: PHONE, code: '333333' }));
        expect(err.statusCode).toBe(429);
      });

      it('does NOT over-tighten: a transport failure keeps its 500 semantics', async () => {
        const { manager, opts } = await bootOtp();
        manager.setSmsService(fakeSms({ failed: true }).service); // 'provider down'
        const { isAPIError } = await import('better-auth/api');

        const otpErr = await rejection(() => opts.sendOTP({ phoneNumber: PHONE, code: '555555' }));
        expect(isAPIError(otpErr)).toBe(false);
        expect(otpErr.name).toBe('Error');
        expect(String(otpErr.message)).toContain('provider down');

        const inviteErr = await rejection(() => manager.sendPhoneInviteSms(PHONE));
        expect(isAPIError(inviteErr)).toBe(false);
        expect(inviteErr.name).toBe('Error');
        expect(String(inviteErr.message)).toContain('provider down');
      });

      it('the code must PREFIX the envelope — a provider merely mentioning it stays 500', async () => {
        const { manager, opts } = await bootOtp();
        manager.setSmsService(
          fakeSms({ failed: true, error: 'upstream rejected: TOO_MANY_REQUESTS at carrier' }).service,
        );
        const { isAPIError } = await import('better-auth/api');
        const err = await rejection(() => opts.sendOTP({ phoneNumber: PHONE, code: '777777' }));
        expect(isAPIError(err)).toBe(false);
        expect(err.name).toBe('Error');
      });

      it('the 429 message carries no quota ceiling, remaining count or reset clock', async () => {
        const { manager, opts } = await bootOtp();
        manager.setSmsService(fakeSms({ failed: true, error: QUOTA_REFUSAL }).service);

        for (const run of [
          () => opts.sendOTP({ phoneNumber: PHONE, code: '999999' }),
          () => manager.sendPhoneInviteSms(PHONE),
        ]) {
          const message = String((await rejection(run)).message);
          // No digits at all ⇒ no ceiling, no remaining count, no reset clock.
          expect(message).not.toMatch(/\d/);
          // …and not the raw service envelope, which names the budget that was hit.
          expect(message).not.toContain(QUOTA_REFUSAL);
          expect(message.toLowerCase()).not.toContain('quota');
        }
      });
    });

    it('honours phoneOtp knobs (cooldown off ⇒ back-to-back admissions allowed)', async () => {
      const { manager } = await bootOtp({ phoneOtp: { cooldownSeconds: 0, maxPerHour: 0 } });
      manager.setSmsService(fakeSms().service);
      await manager.assertPhoneOtpSendAllowed(PHONE);
      await manager.assertPhoneOtpSendAllowed(PHONE);
    });

    // ── #4808 — a cooldown above one hour is enforced, or rejected ─────────
    it('accepts a cooldown above one hour and enforces it (#4808)', async () => {
      // Used to be accepted and then served as 1h, because the send history
      // was pruned at a flat hour. The retention now follows the cooldown —
      // the past-the-hour proof lives in otp-send-guard.test.ts, where the
      // clock is injectable; here the point is that the config boots at all.
      const { manager } = await bootOtp({ phoneOtp: { cooldownSeconds: 7_200 } });
      manager.setSmsService(fakeSms().service);
      await manager.assertPhoneOtpSendAllowed(PHONE);
      await expect(manager.assertPhoneOtpSendAllowed(PHONE))
        .rejects.toThrow(/Too many verification codes/);
    });

    it('rejects an unenforceable cooldown at BOOT, not at the first send (#4808)', () => {
      // The guard is built lazily on first send, so validating only there
      // would report a config error as a 500 on /phone-number/send-otp.
      expect(() => new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
        plugins: { phoneNumber: true },
        phoneOtp: { cooldownSeconds: 90_000 },
      } as any)).toThrow(/exceeds the supported maximum of 86400 seconds/);
    });

    // ── #4790 — the budget is only global if its STORE is ─────────────────
    describe('where the per-number budget is counted (#4790)', () => {
      const makeCache = () => {
        const store = new Map<string, unknown>();
        return {
          store,
          get: vi.fn(async (k: string) => (store.has(k) ? store.get(k) : undefined)),
          set: vi.fn(async (k: string, v: unknown, _ttl?: number) => { store.set(k, v); }),
        };
      };
      const bootNode = async (sharedCounterStore: any) => {
        const { manager } = await bootOtp({ sharedCounterStore });
        manager.setSmsService(fakeSms().service);
        return manager;
      };

      it('spends ONE budget across nodes when a shared counter store is wired', async () => {
        const { createLazyCounterStore } = await import('./rate-limit-storage.js');
        const cache = makeCache();
        // Two nodes: separate managers, separate resolvers, one cache.
        const nodeStore = () =>
          createLazyCounterStore({ resolveCache: async () => cache as any, subject: 'otp-budget' });
        const nodeA = await bootNode(nodeStore());
        const nodeB = await bootNode(nodeStore());

        await nodeA.assertPhoneOtpSendAllowed(PHONE);
        // Rotating nodes no longer buys a fresh cooldown.
        await expect(nodeB.assertPhoneOtpSendAllowed(PHONE))
          .rejects.toThrow(/Too many verification codes/);
        expect(cache.store.size).toBe(1);
        expect([...cache.store.keys()][0]).toContain(PHONE);
      });

      it('resolves the store per check, so a cache registered after boot still binds', async () => {
        const { createLazyCounterStore } = await import('./rate-limit-storage.js');
        const cache = makeCache();
        let registered = false;
        const manager = await bootNode(
          createLazyCounterStore({
            resolveCache: async () => (registered ? (cache as any) : undefined),
            subject: 'otp-budget',
          }),
        );
        registered = true; // CacheServicePlugin comes up after plugin-auth.
        await manager.assertPhoneOtpSendAllowed(PHONE);
        expect(cache.store.size).toBe(1);
      });

      it('a host-supplied secondaryStorage keeps owning the budget', async () => {
        const kv = new Map<string, string>();
        const secondaryStorage = {
          get: async (k: string) => kv.get(k) ?? null,
          set: async (k: string, v: string) => { kv.set(k, v); },
          delete: async (k: string) => { kv.delete(k); },
        };
        const cache = makeCache();
        const { manager } = await bootOtp({
          secondaryStorage,
          sharedCounterStore: async () => cache as any,
        });
        manager.setSmsService(fakeSms().service);
        await manager.assertPhoneOtpSendAllowed(PHONE);
        expect(kv.size).toBe(1);
        expect(cache.store.size).toBe(0);
      });

      it('without any shared store the budget is per-manager — degraded, still enforced', async () => {
        const { manager: nodeA } = await bootOtp();
        const { manager: nodeB } = await bootOtp();
        nodeA.setSmsService(fakeSms().service);
        nodeB.setSmsService(fakeSms().service);

        await nodeA.assertPhoneOtpSendAllowed(PHONE);
        // Enforced on its own node…
        await expect(nodeA.assertPhoneOtpSendAllowed(PHONE))
          .rejects.toThrow(/Too many verification codes/);
        // …and not on the other one: exactly the N× multiplication #4790 is
        // about, which is why AuthPlugin warns loudly when it has to do this.
        await nodeB.assertPhoneOtpSendAllowed(PHONE);
      });
    });

    it('features.phoneNumberOtp requires plugin + deliverable SMS', async () => {
      const { manager } = await bootOtp();
      expect((manager.getPublicConfig() as any).features.phoneNumberOtp).toBe(false);
      expect(manager.isSmsServiceAvailable()).toBe(false);

      manager.setSmsService(fakeSms().service);
      expect(manager.isSmsServiceAvailable()).toBe(true);
      expect(manager.isPhoneOtpDeliverable()).toBe(true);
      expect((manager.getPublicConfig() as any).features.phoneNumberOtp).toBe(true);
    });

    it('an unconfigured (log-only) SMS service does not advertise OTP in production', async () => {
      const { manager } = await bootOtp();
      manager.setSmsService({ async send() { return { id: 'x', status: 'sent' }; }, isConfigured: () => false } as any);
      const prev = process.env.NODE_ENV;
      process.env.NODE_ENV = 'production';
      try {
        expect(manager.isPhoneOtpDeliverable()).toBe(false);
        expect((manager.getPublicConfig() as any).features.phoneNumberOtp).toBe(false);
      } finally {
        process.env.NODE_ENV = prev;
      }
      // Outside production the dev log transport keeps OTP testable.
      expect(manager.isPhoneOtpDeliverable()).toBe(true);
    });

    it('sendPhoneInviteSms sends a credential-free invite and throws without a service', async () => {
      const { manager } = await bootOtp();
      await expect(manager.sendPhoneInviteSms(PHONE)).rejects.toThrow(/SMS_SERVICE_REQUIRED/);

      const sms = fakeSms();
      manager.setSmsService(sms.service);
      await manager.sendPhoneInviteSms(PHONE);
      expect(sms.sent).toHaveLength(1);
      expect(sms.sent[0].to).toBe(PHONE);
      expect(sms.sent[0].body).toMatch(/verification code/);
      // Links to the actual Console sign-in page, not the bare origin.
      expect(sms.sent[0].body).toContain('http://localhost:3000/_console/login');
    });

    // #2815 — localised, tenant-customisable SMS bodies.
    it('renders the built-in Chinese OTP text for a zh-CN deployment locale', async () => {
      const { manager, opts } = await bootOtp();
      const sms = fakeSms();
      manager.setSmsService(sms.service);
      manager.setDefaultSmsLocale('zh-CN');

      await opts.sendOTP({ phoneNumber: PHONE, code: '123456' });
      expect(sms.sent[0].body).toContain('验证码');
      expect(sms.sent[0].body).toContain('123456');
      expect(sms.sent[0].templateParams).toEqual({ code: '123456' });

      await manager.sendPhoneInviteSms(PHONE);
      expect(sms.sent[1].body).toContain('账号已开通');
      expect(sms.sent[1].body).toContain('http://localhost:3000/_console/login');
    });

    it('a tenant sys_notification_template row overrides the built-in text', async () => {
      // The row is read in the organization the send resolves to,
      // `tenancy.defaultOrgId()` — the Default Organization under `single`
      // (phone-sms-texts.ts, "Which organization's row").
      const { manager, opts } = await bootOtp({
        getTenancy: () => ({ defaultOrgId: async () => 'org_default' }),
        dataEngine: {
          async find(object: string, q: any) {
            if (
              object === 'sys_notification_template' &&
              q?.where?.organization_id === 'org_default' &&
              q?.where?.topic === 'auth.phone_otp' &&
              q?.where?.channel === 'sms' &&
              q?.where?.locale === 'zh-CN'
            ) {
              return [{ body: '【定制】验证码 {{code}}（{{minutes}} 分钟）' }];
            }
            return [];
          },
        },
      });
      const sms = fakeSms();
      manager.setSmsService(sms.service);
      manager.setDefaultSmsLocale('zh-CN');

      await opts.sendOTP({ phoneNumber: PHONE, code: '654321' });
      expect(sms.sent[0].body).toBe('【定制】验证码 654321（5 分钟）');
    });

    it('a broken template lookup falls back to the built-in text (never blocks the send)', async () => {
      const { manager, opts } = await bootOtp({
        dataEngine: { async find() { throw new Error('no such table'); } },
      });
      const sms = fakeSms();
      manager.setSmsService(sms.service);

      await opts.sendOTP({ phoneNumber: PHONE, code: '111222' });
      expect(sms.sent[0].body).toContain('111222');
      expect(sms.sent[0].body).toContain('verification code');
    });

    // ── commit 35e94c96b — the recipient's own `sys_user.locale` as the top rung
    //
    // #14788 was ruled option D on 2026-09-03: `sys_user.locale` when set →
    // the request's `Accept-Language` → the deployment default. There is no
    // request rung on this surface (better-auth's send-OTP callbacks receive
    // `{ phoneNumber, code }` and nothing else), so the ruled chain collapses
    // to stored → deployment here.
    //
    // ⚠️ Every case below asserts a body that DIFFERS between the two locales
    // in both directions. `验证码` appears only in the zh row and
    // `verification code` only in the en row, so a pin cannot pass on a
    // template that reads the same either way.
    describe('#14762 — the recipient locale outranks the deployment default', () => {
      /** A data engine that answers the `sys_user` locale read and nothing else. */
      const engineWithUserLocale = (locale: unknown, calls?: any[]) => ({
        async find() { return []; },                     // no tenant template row
        async findOne(object: string, query: any) {
          calls?.push({ object, query });
          if (object !== 'sys_user') return null;
          return { locale };
        },
      });

      it('renders a zh-CN user in Chinese even on an en-US deployment', async () => {
        const { manager, opts } = await bootOtp({ dataEngine: engineWithUserLocale('zh-CN') });
        const sms = fakeSms();
        manager.setSmsService(sms.service);
        manager.setDefaultSmsLocale('en-US');

        await opts.sendOTP({ phoneNumber: PHONE, code: '246810' });
        expect(sms.sent[0].body).toContain('验证码');
        expect(sms.sent[0].body).toContain('246810');
        // The direction that makes the pin real: the deployment's own row is
        // NOT what went out.
        expect(sms.sent[0].body).not.toContain('verification code');
      });

      it('and the reverse: an en-US user on a zh-CN deployment gets English', async () => {
        const { manager, opts } = await bootOtp({ dataEngine: engineWithUserLocale('en-US') });
        const sms = fakeSms();
        manager.setSmsService(sms.service);
        manager.setDefaultSmsLocale('zh-CN');

        await opts.sendOTP({ phoneNumber: PHONE, code: '135791' });
        expect(sms.sent[0].body).toContain('verification code');
        expect(sms.sent[0].body).not.toContain('验证码');
      });

      it('reads the column off the recipient row, projected, by phone number', async () => {
        // Establishes WHICH rung produced the value above: a pin that only
        // looked at the rendered body could be satisfied by any resolution
        // step that happened to reach the same locale.
        const calls: any[] = [];
        const { manager, opts } = await bootOtp({
          dataEngine: engineWithUserLocale('zh-CN', calls),
        });
        manager.setSmsService(fakeSms().service);
        manager.setDefaultSmsLocale('en-US');

        await opts.sendOTP({ phoneNumber: PHONE, code: '111111' });
        const userRead = calls.find((c) => c.object === 'sys_user');
        expect(userRead, 'no sys_user read happened').toBeTruthy();
        expect(userRead.query.where).toEqual({ phone_number: PHONE });
        expect(userRead.query.fields).toEqual(['locale']);
        expect(userRead.query.context?.isSystem).toBe(true);
      });

      it('a user with NO stored locale still falls to the deployment default', async () => {
        // The floor the ruling preserves: an unset column is not a choice.
        const { manager, opts } = await bootOtp({ dataEngine: engineWithUserLocale(null) });
        const sms = fakeSms();
        manager.setSmsService(sms.service);
        manager.setDefaultSmsLocale('zh-CN');

        await opts.sendOTP({ phoneNumber: PHONE, code: '222222' });
        expect(sms.sent[0].body).toContain('验证码');
      });

      it('and with neither rung answering, the built-in en floor still holds', async () => {
        const { manager, opts } = await bootOtp({ dataEngine: engineWithUserLocale(undefined) });
        const sms = fakeSms();
        manager.setSmsService(sms.service);
        // No setDefaultSmsLocale at all.

        await opts.sendOTP({ phoneNumber: PHONE, code: '333333' });
        expect(sms.sent[0].body).toContain('verification code');
        expect(sms.sent[0].body).toContain('333333');
      });

      it('refuses the stringified-nothing literal rather than naming it a locale', async () => {
        // The shape hotcrm measured dead-lettering every delivery. Reusing
        // `normalizeRecipientLocale` is what refuses it — a second normalizer
        // here would be a second place for that refusal to rot.
        const { manager, opts } = await bootOtp({ dataEngine: engineWithUserLocale('undefined') });
        const sms = fakeSms();
        manager.setSmsService(sms.service);
        manager.setDefaultSmsLocale('zh-CN');

        await opts.sendOTP({ phoneNumber: PHONE, code: '444444' });
        expect(sms.sent[0].body).toContain('验证码');
      });

      it('a failing recipient read never blocks the OTP', async () => {
        const { manager, opts } = await bootOtp({
          dataEngine: {
            async find() { return []; },
            async findOne() { throw new Error('sys_user unavailable'); },
          },
        });
        const sms = fakeSms();
        manager.setSmsService(sms.service);
        manager.setDefaultSmsLocale('zh-CN');

        await opts.sendOTP({ phoneNumber: PHONE, code: '555555' });
        expect(sms.sent[0].body).toContain('验证码');
        expect(sms.sent[0].body).toContain('555555');
      });
    });

    // ── #14641 — the SMS INVITE path gets the same rung ──────────────────
    //
    // Its OWN describe, sibling to commit 35e94c96b's above, not nested inside it:
    // the reporter path is what the next reader greps, and these pins answer
    // for #14641, not for the card that gave the OTP send its rung.
    describe("#14641 — the invitation SMS reads the invitee's own locale", () => {
      // Was a scope fence ("untouched — its rung is #14641's") until #14641
      // landed. The existing-row branch is reachable by construction: the one
      // in-repo caller (the identity import endpoint's `invite` policy) CREATES
      // the account before sending. ⚠️ It does NOT populate `locale`, and the
      // column has no default, so that caller still lands on the deployment
      // rung today — these pins drive the engine directly, which is what lets
      // them measure the rung the in-repo flow does not yet exercise.
      //
      // ⚠️ The two built-in invite bodies genuinely differ, so each assertion
      // names one locale in BOTH directions: the marker for the locale that
      // should have won is present, and the marker for the other is absent.
      // A phone-keyed engine drives both branches so "no row" is provably a
      // live lookup that found nothing.
      const phoneKeyedEngine = (rows: Record<string, unknown>, calls?: any[]) => ({
        async find() { return []; },                     // no tenant template row
        async findOne(object: string, query: any) {
          calls?.push({ object, query });
          if (object !== 'sys_user') return null;
          const phone = (query?.where ?? {}).phone_number as string;
          return Object.prototype.hasOwnProperty.call(rows, phone)
            ? { locale: rows[phone] }
            : null;
        },
      });
      const OTHER_PHONE = '+8613900000001';

      it('BRANCH 1 — an invitee whose row says zh-CN is texted in Chinese', async () => {
        const { manager } = await bootOtp({
          dataEngine: phoneKeyedEngine({ [PHONE]: 'zh-CN' }),
        });
        const sms = fakeSms();
        manager.setSmsService(sms.service);
        manager.setDefaultSmsLocale('en-US');

        await manager.sendPhoneInviteSms(PHONE);
        expect(sms.sent[0].body).toContain('账号已开通');
        expect(sms.sent[0].body).not.toContain('Sign in with this phone number');
      });

      it('and the reverse — an en-US row on a zh-CN deployment is texted in English', async () => {
        const { manager } = await bootOtp({
          dataEngine: phoneKeyedEngine({ [PHONE]: 'en-US' }),
        });
        const sms = fakeSms();
        manager.setSmsService(sms.service);
        manager.setDefaultSmsLocale('zh-CN');

        await manager.sendPhoneInviteSms(PHONE);
        expect(sms.sent[0].body).toContain('Sign in with this phone number');
        expect(sms.sent[0].body).not.toContain('账号已开通');
      });

      it('BRANCH 2 — a number with NO row still takes the deployment default', async () => {
        // ⚠️ Positive control for the zero: ONE engine, one table, two numbers.
        // It answers zh-CN for the number that carries a row and nothing for
        // the one that does not — which is what separates "the read ran and
        // found nothing" from "the read never ran", since both would land on
        // the deployment default and render identically.
        const calls: any[] = [];
        const engine = phoneKeyedEngine({ [PHONE]: 'zh-CN' }, calls);

        const known = await bootOtp({ dataEngine: engine });
        const knownSms = fakeSms();
        known.manager.setSmsService(knownSms.service);
        known.manager.setDefaultSmsLocale('en-US');
        await known.manager.sendPhoneInviteSms(PHONE);
        expect(knownSms.sent[0].body).toContain('账号已开通');

        const fresh = await bootOtp({ dataEngine: engine });
        const freshSms = fakeSms();
        fresh.manager.setSmsService(freshSms.service);
        fresh.manager.setDefaultSmsLocale('en-US');
        await fresh.manager.sendPhoneInviteSms(OTHER_PHONE);
        expect(freshSms.sent[0].body).toContain('Sign in with this phone number');
        expect(freshSms.sent[0].body).not.toContain('账号已开通');

        // ...and the second send's read really was attempted, on its number.
        expect(calls.filter((c) => c.object === 'sys_user').map((c) => c.query.where)).toEqual([
          { phone_number: PHONE },
          { phone_number: OTHER_PHONE },
        ]);
      });

      it('reads the column projected, by phone number, under a system context', async () => {
        const calls: any[] = [];
        const { manager } = await bootOtp({
          dataEngine: phoneKeyedEngine({ [PHONE]: 'zh-CN' }, calls),
        });
        manager.setSmsService(fakeSms().service);
        manager.setDefaultSmsLocale('en-US');

        await manager.sendPhoneInviteSms(PHONE);
        const userRead = calls.find((c) => c.object === 'sys_user');
        expect(userRead, 'no sys_user read happened').toBeTruthy();
        expect(userRead.query.where).toEqual({ phone_number: PHONE });
        expect(userRead.query.fields).toEqual(['locale']);
        expect(userRead.query.context?.isSystem).toBe(true);
      });

      it('a failing recipient read never blocks the invitation SMS', async () => {
        const { manager } = await bootOtp({
          dataEngine: {
            async find() { return []; },
            async findOne() { throw new Error('sys_user unavailable'); },
          },
        });
        const sms = fakeSms();
        manager.setSmsService(sms.service);
        manager.setDefaultSmsLocale('zh-CN');

        await manager.sendPhoneInviteSms(PHONE);
        expect(sms.sent).toHaveLength(1);
        expect(sms.sent[0].body).toContain('账号已开通');
      });
    });
  });

  // #2766 V1.5 — placeholder addresses must never become real recipients.
  describe('placeholder-email interception (#2766 V1.5)', () => {
    const PLACEHOLDER = 'u-abcdefghijklmnopqrst@placeholder.invalid';
    const boot = async (extra: any = {}) => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });
      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
        emailAndPassword: { enabled: true },
        ...extra,
      });
      const emailService = { sendTemplate: vi.fn(async () => ({ status: 'sent' })) };
      manager.setEmailService(emailService as any);
      await manager.getAuthInstance();
      warnSpy.mockRestore();
      return { manager, capturedConfig, emailService };
    };

    it('sendResetPassword refuses a placeholder recipient without touching the transport', async () => {
      const { capturedConfig, emailService } = await boot();
      const sendResetPassword = capturedConfig.emailAndPassword.sendResetPassword;
      await expect(
        sendResetPassword({ user: { id: 'u1', email: PLACEHOLDER }, url: 'http://x/reset', token: 't' }),
      ).rejects.toThrow(/PLACEHOLDER_EMAIL/);
      expect(emailService.sendTemplate).not.toHaveBeenCalled();
    });

    it('sendInvitationEmail refuses a placeholder recipient', async () => {
      const { capturedConfig, emailService } = await boot();
      const orgPlugin = capturedConfig.plugins.find((p: any) => p.id === 'organization');
      await expect(
        orgPlugin._opts.sendInvitationEmail({
          email: PLACEHOLDER,
          invitation: { id: 'inv1', organizationId: 'o1', role: 'member' },
          organization: { name: 'Org' },
          inviter: { user: { email: 'admin@example.com' } },
        }),
      ).rejects.toThrow(/PLACEHOLDER_EMAIL/);
      expect(emailService.sendTemplate).not.toHaveBeenCalled();
    });

    // NOTE: the magic-link guard is the same isPlaceholderEmail() branch, but
    // unlike organization the magic-link plugin doesn't expose its options
    // (`_opts`), so it can't be invoked directly here. Covered by the two
    // tests above plus the placeholder-email unit tests.
    it('magic-link plugin registers when enabled (guard shares the tested code path)', async () => {
      const { capturedConfig } = await boot({ plugins: { magicLink: true } });
      expect(capturedConfig.plugins.find((p: any) => p.id === 'magic-link')).toBeDefined();
    });

    // The emailed accept URL must be an absolute link pointing at the Console
    // SPA route, which is mounted under `uiBasePath` (default `/_console`) —
    // the same basename as /login. A bare host in baseUrl (no scheme) also
    // produced relative-looking links email clients wouldn't open.
    it('sendInvitationEmail builds an absolute https:// accept URL under the Console base', async () => {
      const { capturedConfig, emailService } = await boot({ baseUrl: 'cloud.objectos.ai' });
      const orgPlugin = capturedConfig.plugins.find((p: any) => p.id === 'organization');
      await orgPlugin._opts.sendInvitationEmail({
        email: 'invitee@example.com',
        invitation: { id: 'tok123', organizationId: 'o1', role: 'member' },
        organization: { name: 'Org' },
        inviter: { user: { email: 'admin@example.com' } },
      });
      expect(emailService.sendTemplate).toHaveBeenCalledTimes(1);
      const { data } = emailService.sendTemplate.mock.calls[0][0];
      expect(data.acceptUrl).toBe('https://cloud.objectos.ai/_console/accept-invitation/tok123');
    });

    it('sendInvitationEmail preserves an explicit scheme in baseUrl', async () => {
      const { capturedConfig, emailService } = await boot({ baseUrl: 'http://localhost:3000/' });
      const orgPlugin = capturedConfig.plugins.find((p: any) => p.id === 'organization');
      await orgPlugin._opts.sendInvitationEmail({
        email: 'invitee@example.com',
        invitation: { id: 'tok456', organizationId: 'o1', role: 'member' },
        organization: { name: 'Org' },
        inviter: { user: { email: 'admin@example.com' } },
      });
      const { data } = emailService.sendTemplate.mock.calls[0][0];
      expect(data.acceptUrl).toBe('http://localhost:3000/_console/accept-invitation/tok456');
    });

    // commit b706af987 — the invitation producer HOLDS an organization (the invitation
    // row's own organizationId), so it threads that exact value into
    // SendTemplateInput for the sys_email.organization_id stamp. Auth mail
    // that genuinely has no organization (password reset / verification /
    // magic link) stays unstamped AND un-refused — the over-denial control.
    it('sendInvitationEmail threads the invitation organizationId into sendTemplate (#11741)', async () => {
      const { capturedConfig, emailService } = await boot();
      const orgPlugin = capturedConfig.plugins.find((p: any) => p.id === 'organization');
      await orgPlugin._opts.sendInvitationEmail({
        email: 'invitee@example.com',
        invitation: { id: 'inv42', organizationId: 'org_apex', role: 'member' },
        organization: { name: 'Apex' },
        inviter: { user: { email: 'admin@example.com' } },
      });
      expect(emailService.sendTemplate).toHaveBeenCalledTimes(1);
      const invitationInput = (emailService.sendTemplate.mock.calls as unknown as Array<[Record<string, unknown>]>)[0]?.[0];
      expect(invitationInput?.organizationId).toBe('org_apex');
    });

    it('sendResetPassword carries NO organizationId and is not refused — auth mail is genuinely org-less (#11741)', async () => {
      const { capturedConfig, emailService } = await boot();
      const sendResetPassword = capturedConfig.emailAndPassword.sendResetPassword;
      await sendResetPassword({ user: { id: 'u1', email: 'real@example.com' }, url: 'http://x/reset', token: 't' });
      expect(emailService.sendTemplate).toHaveBeenCalledTimes(1);
      const resetInput = (emailService.sendTemplate.mock.calls as unknown as Array<[Record<string, unknown>]>)[0]?.[0];
      expect(resetInput).not.toHaveProperty('organizationId');
    });

    it('sendInvitationEmail honours a custom uiBasePath (Console mounted elsewhere)', async () => {
      const { capturedConfig, emailService } = await boot({
        baseUrl: 'https://acme.example.com',
        uiBasePath: '/console/',
      });
      const orgPlugin = capturedConfig.plugins.find((p: any) => p.id === 'organization');
      await orgPlugin._opts.sendInvitationEmail({
        email: 'invitee@example.com',
        invitation: { id: 'tok789', organizationId: 'o1', role: 'member' },
        organization: { name: 'Org' },
        inviter: { user: { email: 'admin@example.com' } },
      });
      const { data } = emailService.sendTemplate.mock.calls[0][0];
      expect(data.acceptUrl).toBe('https://acme.example.com/console/accept-invitation/tok789');
    });
  });

  describe('getPublicConfig', () => {
    it('should return safe public configuration', () => {
      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
        socialProviders: {
          google: {
            clientId: 'google-client-id',
            clientSecret: 'google-client-secret',
            enabled: true,
          },
          github: {
            clientId: 'github-client-id',
            clientSecret: 'github-client-secret',
          },
        },
        emailAndPassword: {
          enabled: true,
          disableSignUp: false,
          requireEmailVerification: true,
        },
        plugins: {
          twoFactor: true,
          organization: true,
        },
      });
      warnSpy.mockRestore();

      const config = manager.getPublicConfig();

      // Should include social providers without secrets
      expect(config.socialProviders).toHaveLength(2);
      expect(config.socialProviders[0]).toEqual({
        id: 'google',
        name: 'Google',
        enabled: true,
        type: 'social',
      });
      expect(config.socialProviders[1]).toEqual({
        id: 'github',
        name: 'GitHub',
        enabled: true,
        type: 'social',
      });

      // Should NOT include sensitive data
      expect(config).not.toHaveProperty('secret');
      expect(config.socialProviders[0]).not.toHaveProperty('clientSecret');
      expect(config.socialProviders[0]).not.toHaveProperty('clientId');

      // Should include email/password config
      expect(config.emailPassword).toEqual({
        enabled: true,
        disableSignUp: false,
        requireEmailVerification: true,
      });

      // Should include features
      expect(config.features).toEqual({
        twoFactor: true,
        // [#7481] `passkeys` / `magicLink` are deliberately absent — withdrawn
        // from the payload by the maintainer ruling of 2026-08-11 until
        // objectui#4179 ships a login UI that reads them. `toEqual` is an exact
        // match, so this asserts their absence rather than merely omitting them.
        organization: true,
        oidcProvider: false,
        sso: false,
        ssoEnforced: false,
        deviceAuthorization: false,
        admin: false,
        phoneNumber: false,
        phoneNumberOtp: false,
        multiOrgEnabled: false,
        // [ADR-0105 D1] Which of `single` | `group` | `isolated` is in force.
        // A vanilla deployment (no tenancy service wired, no env override) is
        // `single`, matching `multiOrgEnabled: false`.
        tenancyPosture: 'single',
        // [#11739] Which audience posture is in force. Undeclared ⇒ the safe
        // default, `invite_only` — no legacy limbo.
        audiencePosture: 'invite_only',
        degradedTenancy: false,
        // [#25292] `OS_CLOUD_MANAGED` is unset here, so not managed.
        cloudManaged: false,
        privacyUrl: 'https://objectstack.ai/privacy',
        termsUrl: 'https://objectstack.ai/terms',
      });
    });

    // [#25292] `features.cloudManaged` is served from `isCloudManaged()`, the
    // one accessor every managed-mode judgement reads, so the console's
    // hide-when-on gate and the server agree on the mode.
    it('serves features.cloudManaged from OS_CLOUD_MANAGED', () => {
      const prev = process.env.OS_CLOUD_MANAGED;
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
      });
      try {
        process.env.OS_CLOUD_MANAGED = '1';
        resetCloudManagedForTesting();
        expect((manager.getPublicConfig() as any).features.cloudManaged).toBe(true);
      } finally {
        if (prev === undefined) delete process.env.OS_CLOUD_MANAGED;
        else process.env.OS_CLOUD_MANAGED = prev;
        resetCloudManagedForTesting();
      }
      expect((manager.getPublicConfig() as any).features.cloudManaged).toBe(false);
    });

    // Enterprise SSO (@better-auth/sso) is opt-in: the plugin is only wired
    // when `plugins.sso` / `OS_SSO_ENABLED` is on. The public config MUST
    // report the same value so the login UI can hide the "Sign in with SSO"
    // button when the `/sign-in/sso` route isn't mounted (otherwise the
    // button only fails at click time with "No SSO provider is configured").
    it('should report features.sso=false by default', () => {
      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
      });
      warnSpy.mockRestore();

      expect(manager.getPublicConfig().features.sso).toBe(false);
    });

    it('should report features.sso=true when enabled via plugins config', () => {
      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        plugins: { sso: true },
      });
      warnSpy.mockRestore();

      expect(manager.getPublicConfig().features.sso).toBe(true);
    });

    it('should let OS_SSO_ENABLED decide when the config leaves sso unset (matches buildPlugins wiring)', () => {
      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const prev = process.env.OS_SSO_ENABLED;
      process.env.OS_SSO_ENABLED = 'true';
      try {
        const manager = new AuthManager({
          secret: 'test-secret-at-least-32-chars-long',
        });
        expect(manager.getPublicConfig().features.sso).toBe(true);
      } finally {
        if (prev === undefined) delete process.env.OS_SSO_ENABLED;
        else process.env.OS_SSO_ENABLED = prev;
        warnSpy.mockRestore();
      }
    });

    // ADR-0135 D6 / cloud#551 — OS_SSO_ENABLED uses the shared `readBooleanEnv`
    // parser, so the platform-standard truthy/falsy set works (not only the
    // literal `'true'`). Operators kept setting `OS_SSO_ENABLED=1` and getting
    // a silently-disabled RP.
    it.each(['1', 'true', 'TRUE', 'yes', 'on'])(
      'should treat OS_SSO_ENABLED=%s as enabled',
      (val) => {
        const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
        const prev = process.env.OS_SSO_ENABLED;
        process.env.OS_SSO_ENABLED = val;
        try {
          const manager = new AuthManager({ secret: 'test-secret-at-least-32-chars-long' });
          expect(manager.getPublicConfig().features.sso).toBe(true);
        } finally {
          if (prev === undefined) delete process.env.OS_SSO_ENABLED;
          else process.env.OS_SSO_ENABLED = prev;
          warnSpy.mockRestore();
        }
      },
    );

    it.each(['0', 'false', 'off', 'no'])(
      'should treat OS_SSO_ENABLED=%s as disabled when the config leaves sso unset',
      (val) => {
        const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
        const prev = process.env.OS_SSO_ENABLED;
        process.env.OS_SSO_ENABLED = val;
        try {
          const manager = new AuthManager({
            secret: 'test-secret-at-least-32-chars-long',
          });
          expect(manager.getPublicConfig().features.sso).toBe(false);
        } finally {
          if (prev === undefined) delete process.env.OS_SSO_ENABLED;
          else process.env.OS_SSO_ENABLED = prev;
          warnSpy.mockRestore();
        }
      },
    );

    // #13439 (maintainer ruling 2026-08-31) — an EXPLICIT `plugins.sso`
    // value wins over `OS_SSO_ENABLED`; the env var decides only where the
    // config leaves the key unset. Before the flip, a host that wrote
    // `plugins: { sso: false }` got no effect whenever the env var was set —
    // a line that read as a security control and did nothing.
    it.each(['0', 'false', 'off', 'no'])(
      'should keep sso ENABLED when plugins.sso=true despite OS_SSO_ENABLED=%s (explicit config wins)',
      (val) => {
        const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
        const prev = process.env.OS_SSO_ENABLED;
        process.env.OS_SSO_ENABLED = val;
        try {
          const manager = new AuthManager({
            secret: 'test-secret-at-least-32-chars-long',
            plugins: { sso: true },
          });
          expect(manager.getPublicConfig().features.sso).toBe(true);
        } finally {
          if (prev === undefined) delete process.env.OS_SSO_ENABLED;
          else process.env.OS_SSO_ENABLED = prev;
          warnSpy.mockRestore();
        }
      },
    );

    // The empty string is a PRESENT env value (readBooleanEnv resolves it to
    // a boolean — it only returns undefined for an ABSENT variable), so it
    // must lose to an explicit config value like any other present value.
    it.each(['1', 'true', 'yes', 'on', ''])(
      'should keep sso DISABLED when plugins.sso=false despite OS_SSO_ENABLED=%j (explicit config wins)',
      (val) => {
        const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
        const prev = process.env.OS_SSO_ENABLED;
        process.env.OS_SSO_ENABLED = val;
        try {
          const manager = new AuthManager({
            secret: 'test-secret-at-least-32-chars-long',
            plugins: { sso: false },
          });
          expect(manager.getPublicConfig().features.sso).toBe(false);
          expect(manager.isSsoWired()).toBe(false);
        } finally {
          if (prev === undefined) delete process.env.OS_SSO_ENABLED;
          else process.env.OS_SSO_ENABLED = prev;
          warnSpy.mockRestore();
        }
      },
    );

    // #13439 — ssoDomainVerification follows the same explicit-config-wins
    // order (and still requires sso to be wired at all).
    it('should let plugins.ssoDomainVerification=false win over OS_SSO_DOMAIN_VERIFICATION', () => {
      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const prevSso = process.env.OS_SSO_ENABLED;
      const prevDv = process.env.OS_SSO_DOMAIN_VERIFICATION;
      process.env.OS_SSO_DOMAIN_VERIFICATION = 'true';
      delete process.env.OS_SSO_ENABLED;
      try {
        const manager = new AuthManager({
          secret: 'test-secret-at-least-32-chars-long',
          plugins: { sso: true, ssoDomainVerification: false },
        });
        expect(manager.isSsoDomainVerificationEnabled()).toBe(false);
      } finally {
        if (prevSso === undefined) delete process.env.OS_SSO_ENABLED;
        else process.env.OS_SSO_ENABLED = prevSso;
        if (prevDv === undefined) delete process.env.OS_SSO_DOMAIN_VERIFICATION;
        else process.env.OS_SSO_DOMAIN_VERIFICATION = prevDv;
        warnSpy.mockRestore();
      }
    });

    it('should let OS_SSO_DOMAIN_VERIFICATION decide when the config leaves it unset', () => {
      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const prevSso = process.env.OS_SSO_ENABLED;
      const prevDv = process.env.OS_SSO_DOMAIN_VERIFICATION;
      process.env.OS_SSO_DOMAIN_VERIFICATION = 'true';
      delete process.env.OS_SSO_ENABLED;
      try {
        const manager = new AuthManager({
          secret: 'test-secret-at-least-32-chars-long',
          plugins: { sso: true },
        });
        expect(manager.isSsoDomainVerificationEnabled()).toBe(true);
      } finally {
        if (prevSso === undefined) delete process.env.OS_SSO_ENABLED;
        else process.env.OS_SSO_ENABLED = prevSso;
        if (prevDv === undefined) delete process.env.OS_SSO_DOMAIN_VERIFICATION;
        else process.env.OS_SSO_DOMAIN_VERIFICATION = prevDv;
        warnSpy.mockRestore();
      }
    });

    it('should filter out disabled providers', () => {
      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        socialProviders: {
          google: {
            clientId: 'google-client-id',
            clientSecret: 'google-client-secret',
            enabled: true,
          },
          github: {
            clientId: 'github-client-id',
            clientSecret: 'github-client-secret',
            enabled: false,
          },
        },
      });
      warnSpy.mockRestore();

      const config = manager.getPublicConfig();

      expect(config.socialProviders).toHaveLength(1);
      expect(config.socialProviders[0].id).toBe('google');
    });

    it('should default email/password to enabled', () => {
      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
      });
      warnSpy.mockRestore();

      const config = manager.getPublicConfig();

      expect(config.emailPassword.enabled).toBe(true);
    });

    it('should handle unknown provider names', () => {
      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        socialProviders: {
          customProvider: {
            clientId: 'custom-client-id',
            clientSecret: 'custom-client-secret',
          },
        },
      });
      warnSpy.mockRestore();

      const config = manager.getPublicConfig();

      expect(config.socialProviders[0]).toEqual({
        id: 'customProvider',
        name: 'CustomProvider',
        enabled: true,
        type: 'social',
      });
    });
  });

  // The `/auth/config` route refines the coarse `features.sso` ("wired") flag
  // to "usable" via isSsoUsable() so the login UI hides the "Sign in with SSO"
  // button BOTH when SSO is off and when it's on but no IdP is configured yet.
  describe('isSsoUsable – refines features.sso to "≥1 provider configured"', () => {
    const makeEngine = (countImpl: () => Promise<number> | number) =>
      ({
        insert: vi.fn(),
        findOne: vi.fn(),
        find: vi.fn(),
        count: vi.fn().mockImplementation(countImpl),
        update: vi.fn(),
        delete: vi.fn(),
      });

    it('returns false when SSO is not wired (skips the provider query entirely)', async () => {
      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const engine = makeEngine(() => 5);
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        dataEngine: engine as any,
      });
      warnSpy.mockRestore();

      expect(await manager.isSsoUsable()).toBe(false);
      expect(engine.count).not.toHaveBeenCalled();
    });

    it('returns false when wired but zero providers are configured', async () => {
      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const engine = makeEngine(() => 0);
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        plugins: { sso: true } as any,
        dataEngine: engine as any,
      });
      warnSpy.mockRestore();

      expect(await manager.isSsoUsable()).toBe(false);
      // Reads sys_sso_provider under a system context (RLS would otherwise zero it out).
      expect(engine.count.mock.calls[0][0]).toBe('sys_sso_provider');
      expect(engine.count.mock.calls[0][1]?.context?.isSystem).toBe(true);
    });

    it('returns true when wired and at least one provider exists', async () => {
      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        plugins: { sso: true } as any,
        dataEngine: makeEngine(() => 1) as any,
      });
      warnSpy.mockRestore();

      expect(await manager.isSsoUsable()).toBe(true);
    });

    it('fails open to wired when there is no data engine to consult', async () => {
      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        plugins: { sso: true } as any,
      });
      warnSpy.mockRestore();

      expect(await manager.isSsoUsable()).toBe(true);
    });

    it('fails open to wired when the provider-count query throws', async () => {
      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        plugins: { sso: true } as any,
        dataEngine: makeEngine(() => {
          throw new Error('db down');
        }) as any,
      });
      warnSpy.mockRestore();

      expect(await manager.isSsoUsable()).toBe(true);
    });
  });

  describe('WebContainer request-state polyfill', () => {
    const sym = Symbol.for('better-auth:global');

    beforeEach(() => {
      // Reset better-auth global between tests so installation logic re-runs.
      delete (globalThis as any)[sym];
    });

    afterEach(() => {
      delete (globalThis as any)[sym];
      delete (globalThis as any).process?.env?.STACKBLITZ;
    });

    it('does NOT install a polyfill outside WebContainer', () => {
      // Default test env (Node + Vitest) is not WebContainer.
      delete (globalThis as any).process?.env?.STACKBLITZ;
      const proc = (globalThis as any).process;
      const prevShell = proc?.env?.SHELL;
      const prevWc = proc?.versions?.webcontainer;
      if (proc?.env) delete proc.env.SHELL;
      if (proc?.versions) delete proc.versions.webcontainer;

      try {
        new AuthManager({
          secret: 'test-secret-at-least-32-chars-long',
          baseUrl: 'http://localhost:3000',
        });
        expect((globalThis as any)[sym]?.context?.requestStateAsyncStorage).toBeUndefined();
      } finally {
        if (proc?.env && prevShell !== undefined) proc.env.SHELL = prevShell;
        if (proc?.versions && prevWc !== undefined) proc.versions.webcontainer = prevWc;
      }
    });

    it('installs a synchronous polyfill when WebContainer is detected', () => {
      (globalThis as any).process = (globalThis as any).process || {};
      (globalThis as any).process.env = (globalThis as any).process.env || {};
      (globalThis as any).process.env.STACKBLITZ = '1';

      new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
      });

      const als = (globalThis as any)[sym]?.context?.requestStateAsyncStorage;
      expect(als).toBeDefined();
      expect(typeof als.run).toBe('function');
      expect(typeof als.getStore).toBe('function');
    });

    it('polyfill propagates store across awaits within a single run() call', async () => {
      (globalThis as any).process = (globalThis as any).process || {};
      (globalThis as any).process.env = (globalThis as any).process.env || {};
      (globalThis as any).process.env.STACKBLITZ = '1';

      new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
      });

      const als = (globalThis as any)[sym].context.requestStateAsyncStorage;
      const store = new WeakMap();

      const inner = async () => {
        await Promise.resolve();
        await Promise.resolve();
        return als.getStore();
      };

      const result = await als.run(store, () => inner());
      expect(result).toBe(store);
    });

    it('polyfill restores previous store after run() settles, even on error', async () => {
      (globalThis as any).process = (globalThis as any).process || {};
      (globalThis as any).process.env = (globalThis as any).process.env || {};
      (globalThis as any).process.env.STACKBLITZ = '1';

      new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
      });

      const als = (globalThis as any)[sym].context.requestStateAsyncStorage;
      expect(als.getStore()).toBeUndefined();

      const outer = new WeakMap();
      const inner = new WeakMap();
      await als.run(outer, async () => {
        expect(als.getStore()).toBe(outer);
        await als.run(inner, async () => {
          await Promise.resolve();
          expect(als.getStore()).toBe(inner);
        });
        expect(als.getStore()).toBe(outer);
      });
      expect(als.getStore()).toBeUndefined();

      await expect(
        als.run(outer, async () => {
          await Promise.resolve();
          throw new Error('boom');
        }),
      ).rejects.toThrow('boom');
      expect(als.getStore()).toBeUndefined();
    });
  });

  describe('generateSecret – production secret guard (P0-1)', () => {
    const ENV_KEYS = ['NODE_ENV', 'OS_AUTH_SECRET', 'AUTH_SECRET', 'BETTER_AUTH_SECRET'] as const;
    let saved: Record<string, string | undefined>;

    beforeEach(() => {
      saved = Object.fromEntries(ENV_KEYS.map((k) => [k, process.env[k]]));
      for (const k of ['OS_AUTH_SECRET', 'AUTH_SECRET', 'BETTER_AUTH_SECRET']) delete process.env[k];
    });
    afterEach(() => {
      for (const k of ENV_KEYS) {
        if (saved[k] === undefined) delete process.env[k];
        else process.env[k] = saved[k];
      }
    });

    it('throws (fails boot) in production when no secret is configured', () => {
      process.env.NODE_ENV = 'production';
      const m = new AuthManager({ baseUrl: 'http://localhost:3000' } as any);
      expect(() => (m as any).generateSecret()).toThrow(/OS_AUTH_SECRET is required outside development/);
    });

    // The fallback is fail-closed: only a development boot (`isDevelopmentBoot`,
    // `@objectstack/core`) or NODE_ENV=test admits it. An embedder that never
    // exported NODE_ENV, or exported a custom value, is a real deployment.
    it('throws when NODE_ENV is unset and no secret is configured', () => {
      delete process.env.NODE_ENV;
      const m = new AuthManager({ baseUrl: 'http://localhost:3000' } as any);
      expect(() => (m as any).generateSecret()).toThrow(/OS_AUTH_SECRET is required outside development/);
    });

    it.each(['staging', 'Production', 'dev', ''])('throws when NODE_ENV is %j and no secret is configured', (value) => {
      process.env.NODE_ENV = value;
      const m = new AuthManager({ baseUrl: 'http://localhost:3000' } as any);
      expect(() => (m as any).generateSecret()).toThrow(/OS_AUTH_SECRET is required outside development/);
    });

    it('falls back to an ephemeral secret under NODE_ENV=test', () => {
      process.env.NODE_ENV = 'test';
      const m = new AuthManager({ baseUrl: 'http://localhost:3000' } as any);
      expect((m as any).generateSecret()).toMatch(/^dev-secret-/);
    });

    it('falls back to an ephemeral dev secret outside production', () => {
      process.env.NODE_ENV = 'development';
      const m = new AuthManager({ baseUrl: 'http://localhost:3000' } as any);
      expect((m as any).generateSecret()).toMatch(/^dev-secret-/);
    });

    it('uses OS_AUTH_SECRET when set, even in production', () => {
      process.env.NODE_ENV = 'production';
      process.env.OS_AUTH_SECRET = 'a-strong-production-secret-value';
      const m = new AuthManager({ baseUrl: 'http://localhost:3000' } as any);
      expect((m as any).generateSecret()).toBe('a-strong-production-secret-value');
    });
  });

  describe('customSession – derived identity and positions array', () => {
    // dataEngine stub: `platformAdmin` controls whether the user resolves as a
    // platform admin (a sys_user_permission_set row pointing at the
    // admin_full_access permission set, owned by the Default Organization —
    // the `sys_organization` row slugged `default` the stub serves).
    const makeDataEngine = (opts: { platformAdmin: boolean }) => bindTestSecurityCatalog({
      // Two parameters because the seam has two: `IDataEngine.find(objectName,
      // query?, options?)`, and every production read reaching this double goes
      // through `resolve-authz-context.ts` `tryFind`, which always calls
      // `ql.find(object, { where, limit, context })`. Declaring one parameter
      // would force a delegating override to drop an argument the seam passes.
      find: vi.fn(async (object: string, _query?: any) => {
        if (object === 'sys_user_permission_set') {
          return opts.platformAdmin
            ? [{ user_id: 'u-1', permission_set_id: 'ps-admin', permission_set: 'admin_full_access', organization_id: 'org_default' }]
            : [];
        }
        if (object === 'sys_permission_set') {
          return [{ id: 'ps-admin', name: 'admin_full_access' }];
        }
        if (object === 'sys_organization') {
          return [{ id: 'org_default', slug: 'default' }];
        }
        return [];
      }),
      findOne: vi.fn(),
    }, { permissions: [{ name: ADMIN_FULL_ACCESS, ...ADMIN_FULL_ACCESS_CAPABILITIES }] });

    const getSessionCallback = async (dataEngine: any, extra: Record<string, unknown> = {}) => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });

      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
        dataEngine,
        ...extra,
      });
      await manager.getAuthInstance();
      warnSpy.mockRestore();

      const plugin = capturedConfig.plugins.find((p: any) => p.id === 'custom-session');
      expect(plugin).toBeDefined();
      return plugin._fn as (input: { user: any; session: any }) => Promise<any>;
    };

    // [#15136 — maintainer ruling 2026-09-05, option A] These four cases used to
    // pin the OPPOSITE contract: that the better-auth `sys_user.role` scalar,
    // split on commas, WAS `positions[]`. That is the derivation the ruling
    // removed — `positions[]` is the security axis on every surface — so they
    // are migrated fixtures, not evidence against it. Each one now asserts the
    // scalar is ABSENT from the array while remaining untouched on the payload,
    // which is the half of ADR-0068 D2 that did not change.
    it('carries the ADR-0090 D5 `everyone` anchor for a regular user with no stored role', async () => {
      const callback = await getSessionCallback(makeDataEngine({ platformAdmin: false }));
      const result = await callback({
        user: { id: 'u-1', email: 'a@b.com' },
        session: {},
      });
      expect(result.user.role).toBeUndefined();
      expect(result.user.positions).toEqual(['everyone']);
    });

    it('does NOT project the stored role scalar into positions[]', async () => {
      const callback = await getSessionCallback(makeDataEngine({ platformAdmin: false }));
      const result = await callback({
        user: { id: 'u-1', email: 'a@b.com', role: 'manager' },
        session: {},
      });
      // The scalar keeps its stored value — it is simply not an authorization
      // axis, so it no longer appears in the array authored predicates read.
      expect(result.user.role).toBe('manager');
      expect(result.user.positions).not.toContain('manager');
      expect(result.user.positions).toEqual(['everyone']);
    });

    it('derives platform_admin without overwriting role and without the scalar', async () => {
      const callback = await getSessionCallback(makeDataEngine({ platformAdmin: true }));
      const result = await callback({
        user: { id: 'u-1', email: 'a@b.com', role: 'manager' },
        session: {},
      });
      // ADR-0068: NO `role:'admin'` overwrite footgun. The deprecated scalar
      // keeps its stored value; the canonical platform_admin identity is on
      // positions[], and isPlatformAdmin is a derived alias of it.
      expect(result.user.role).toBe('manager');
      expect(result.user.positions).toContain('platform_admin');
      expect(result.user.positions).not.toContain('manager');
      expect(result.user.isPlatformAdmin).toBe(true);
    });

    it('ignores a multi-token stored role entirely while still deriving platform_admin', async () => {
      const callback = await getSessionCallback(makeDataEngine({ platformAdmin: true }));
      const result = await callback({
        user: { id: 'u-1', email: 'a@b.com', role: 'admin,manager' },
        session: {},
      });
      expect(result.user.role).toBe('admin,manager');
      expect(result.user.positions).toContain('platform_admin');
      for (const token of ['admin', 'manager']) {
        expect(result.user.positions).not.toContain(token);
      }
      expect(result.user.isPlatformAdmin).toBe(true);
    });

    it('carries an ADR-0057 D4 `sys_user_position` assignment — the axis the payload was missing', async () => {
      const engine = makeDataEngine({ platformAdmin: false });
      const inner = engine.find;
      engine.find = vi.fn(async (object: string, q?: any) => {
        if (object === 'sys_user_position') {
          return [{ user_id: 'u-1', position: 'demo_reviewer', organization_id: 'o1' }];
        }
        return inner(object, q);
      }) as any;

      // The assignment applies in its own organization, so the session acts in it.
      const callback = await getSessionCallback(engine);
      const result = await callback({
        user: { id: 'u-1', email: 'a@b.com', role: 'manager' },
        session: { activeOrganizationId: 'o1' },
      });
      expect(result.user.positions).toContain('demo_reviewer');
      // Still not the scalar — the two axes do not blend.
      expect(result.user.positions).not.toContain('manager');
    });

    it('returns the payload untouched when the user has no id', async () => {
      const callback = await getSessionCallback(makeDataEngine({ platformAdmin: false }));
      const user = { email: 'anon@b.com' };
      const result = await callback({ user, session: {} });
      expect(result.user).toBe(user);
      expect(result.user.positions).toBeUndefined();
    });

    // [#24762, ruling 6288774214 items 1–3] What `user.authGate` the producer
    // stamps on an impersonation session (`session.impersonatedBy` set) of a
    // held user: only an `account`-scope posture (`AUTH_GATE_SCOPES`) holds
    // it, the first one the user's list reports. The user's own session keeps
    // the list's first entry. The same cases on a real boot, through the
    // transport seams' 403 envelope, are `@objectstack/verify`'s
    // `held-session-impersonation-target.pin.test.ts`.
    describe('the posture stamped on an impersonation session (ADR-0069, AUTH_GATE_SCOPES)', () => {
      const LAPSED = () => new Date(Date.now() - 30 * 86_400_000).toISOString();
      const IMPERSONATION = { impersonatedBy: 'u-admin' };
      // Every posture computable at once: enforced MFA with no grace, and a
      // one-day expiry. Each row below decides which postures its user holds.
      // [#30201] Two-factor on: the gate holds a user for MFA only while they can enroll.
      const POLICY = { mfaRequired: true, mfaGracePeriodDays: 0, passwordExpiryDays: 1, plugins: { twoFactor: true } };
      const sessionGateFor = async (row: Record<string, unknown>, session: Record<string, unknown>) => {
        const engine = makeDataEngine({ platformAdmin: false });
        // The block's double, its `findOne` answering the posture read of the user row.
        engine.findOne = vi.fn(async (object: string, q?: any) => {
          assertEngineFindOnePredicate(object, q);
          return object === 'sys_user' && q?.where?.id === 'u-1' ? { id: 'u-1', ...row } : null;
        }) as any;
        const callback = await getSessionCallback(engine, POLICY);
        const result = await callback({ user: { id: 'u-1', email: 'a@b.com' }, session });
        return result.user.authGate?.code;
      };
      const RESET = { must_change_password: true, two_factor_enabled: true, password_changed_at: new Date().toISOString() };
      const EXPIRED = { must_change_password: false, two_factor_enabled: true, password_changed_at: LAPSED() };
      const MFA = { must_change_password: false, two_factor_enabled: false, mfa_required_at: LAPSED(), password_changed_at: new Date().toISOString() };
      const RESET_AND_MFA = { ...MFA, must_change_password: true };

      it('a forced-reset user: their own session is held, an impersonation session of them is not', async () => {
        expect(await sessionGateFor(RESET, {})).toBe('PASSWORD_RESET_REQUIRED');
        expect(await sessionGateFor(RESET, IMPERSONATION)).toBeUndefined();
      });

      it('an expired-password user: the same, the other credential-scope posture', async () => {
        expect(await sessionGateFor(EXPIRED, {})).toBe('PASSWORD_EXPIRED');
        expect(await sessionGateFor(EXPIRED, IMPERSONATION)).toBeUndefined();
      });

      it('an MFA-held user: the account-scope posture holds the impersonation session too', async () => {
        expect(await sessionGateFor(MFA, {})).toBe('MFA_REQUIRED');
        expect(await sessionGateFor(MFA, IMPERSONATION)).toBe('MFA_REQUIRED');
      });

      it('a user held by both: their own session shows the reset, the impersonation session MFA_REQUIRED', async () => {
        expect(await sessionGateFor(RESET_AND_MFA, {})).toBe('PASSWORD_RESET_REQUIRED');
        expect(await sessionGateFor(RESET_AND_MFA, IMPERSONATION)).toBe('MFA_REQUIRED');
      });
    });
  });

  // ADR-0069 D1: breached-password rejection enables better-auth's native
  // `haveibeenpwned` plugin. Default OFF (no false surface, ADR-0049); the
  // settings toggle (`password_reject_breached`) and the
  // `OS_AUTH_PASSWORD_REJECT_BREACHED` env override both gate it, with env
  // winning over config — mirroring the twoFactor / scim gating pattern.
  describe('haveibeenpwned plugin (ADR-0069 breached-password rejection)', () => {
    const captureConfig = () => {
      let capturedConfig: any;
      (betterAuth as any).mockImplementation((config: any) => {
        capturedConfig = config;
        return { handler: vi.fn(), api: {} };
      });
      return () => capturedConfig;
    };

    it('does NOT register the plugin by default (off by default)', async () => {
      const get = captureConfig();
      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
      });
      await manager.getAuthInstance();
      warnSpy.mockRestore();

      expect(get().plugins.map((p: any) => p.id)).not.toContain('have-i-been-pwned');
    });

    it('registers the plugin when plugins.passwordRejectBreached is true', async () => {
      const get = captureConfig();
      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
        plugins: { passwordRejectBreached: true } as any,
      });
      await manager.getAuthInstance();
      warnSpy.mockRestore();

      const hibp = get().plugins.find((p: any) => p.id === 'have-i-been-pwned');
      expect(hibp).toBeDefined();
      // A custom user-facing message is passed (the default error is generic).
      expect(typeof hibp._opts.customPasswordCompromisedMessage).toBe('string');
    });

    it('lets OS_AUTH_PASSWORD_REJECT_BREACHED env override the config (env wins)', async () => {
      const get = captureConfig();
      const prev = process.env.OS_AUTH_PASSWORD_REJECT_BREACHED;
      process.env.OS_AUTH_PASSWORD_REJECT_BREACHED = 'true';
      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      try {
        const manager = new AuthManager({
          secret: 'test-secret-at-least-32-chars-long',
          baseUrl: 'http://localhost:3000',
          plugins: { passwordRejectBreached: false } as any,
        });
        await manager.getAuthInstance();
        expect(get().plugins.map((p: any) => p.id)).toContain('have-i-been-pwned');
      } finally {
        if (prev === undefined) delete process.env.OS_AUTH_PASSWORD_REJECT_BREACHED;
        else process.env.OS_AUTH_PASSWORD_REJECT_BREACHED = prev;
        warnSpy.mockRestore();
      }
    });
  });

  // ADR-0069 D2: per-identity account lockout + native rate-limit passthrough.
  // The lockout state machine is exercised directly via the AuthManager helpers
  // with a mocked data engine (deterministic; the live multi-failure path is
  // covered by the dogfood smoke).
  describe('account lockout + rate limiting (ADR-0069 D2)', () => {
    const SECRET = 'test-secret-at-least-32-chars-long';
    // findOne honours the `where` clause (the ObjectQL engine key) — so a
    // regression to the wrong key (`filter`, silently ignored → returns the
    // first/arbitrary row) makes these tests fail, not pass. Caught a real bug
    // in dogfood that a query-agnostic mock had masked.
    const makeEngine = (user: any) => ({
      findOne: vi.fn(async (_obj: string, q: any) => {
        assertEngineFindOnePredicate(_obj, q);
        const w = q?.where ?? {};
        if (!user) return null;
        const matches = Object.entries(w).every(([k, v]) => (user as any)[k] === v);
        return matches ? user : null;
      }),
      update: vi.fn(async () => ({ ...(user ?? {}) })),
      count: vi.fn(),
    });
    const mgr = (engine: any, extra: any = {}) => {
      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const m = new AuthManager({ secret: SECRET, baseUrl: 'http://localhost:3000', dataEngine: engine, ...extra });
      warn.mockRestore();
      return m;
    };

    it('assertAccountNotLocked is a no-op when lockout is disabled (threshold 0)', async () => {
      const engine = makeEngine({ id: 'u1', email: 'a@b.com', locked_until: new Date(Date.now() + 60_000).toISOString() });
      const m = mgr(engine, { lockoutThreshold: 0 });
      await expect((m as any).assertAccountNotLocked('a@b.com')).resolves.toBeUndefined();
      expect(engine.findOne).not.toHaveBeenCalled();
    });

    it('assertAccountNotLocked throws ACCOUNT_LOCKED while locked_until is in the future', async () => {
      const engine = makeEngine({ id: 'u1', email: 'a@b.com', locked_until: new Date(Date.now() + 60_000).toISOString() });
      const m = mgr(engine, { lockoutThreshold: 3 });
      await expect((m as any).assertAccountNotLocked('a@b.com')).rejects.toMatchObject({
        body: { code: 'ACCOUNT_LOCKED' },
      });
    });

    it('assertAccountNotLocked allows sign-in once the lock has expired', async () => {
      const engine = makeEngine({ id: 'u1', email: 'a@b.com', locked_until: new Date(Date.now() - 60_000).toISOString() });
      const m = mgr(engine, { lockoutThreshold: 3 });
      await expect((m as any).assertAccountNotLocked('a@b.com')).resolves.toBeUndefined();
    });

    it('recordSignInOutcome increments below threshold without locking', async () => {
      const engine = makeEngine({ id: 'u1', email: 'a@b.com', failed_login_count: 0, locked_until: null });
      const m = mgr(engine, { lockoutThreshold: 3 });
      await (m as any).recordSignInOutcome('a@b.com', false);
      const patch = engine.update.mock.calls[0][1];
      expect(patch.failed_login_count).toBe(1);
      expect(patch.locked_until).toBeUndefined();
    });

    it('recordSignInOutcome stamps locked_until (a Date) once the threshold is reached', async () => {
      const engine = makeEngine({ id: 'u1', email: 'a@b.com', failed_login_count: 2, locked_until: null });
      const m = mgr(engine, { lockoutThreshold: 3, lockoutDurationMinutes: 15 });
      await (m as any).recordSignInOutcome('a@b.com', false);
      const patch = engine.update.mock.calls[0][1];
      expect(patch.failed_login_count).toBe(3);
      expect(patch.locked_until instanceof Date).toBe(true);
      // ~15 minutes out (datetime stored as a Date, never epoch-ms — see ADR-0074).
      expect((patch.locked_until as Date).getTime()).toBeGreaterThan(Date.now() + 14 * 60_000);
    });

    it('recordSignInOutcome resets counter + lock on success when there is state to clear', async () => {
      const engine = makeEngine({ id: 'u1', email: 'a@b.com', failed_login_count: 2, locked_until: null });
      const m = mgr(engine, { lockoutThreshold: 3 });
      await (m as any).recordSignInOutcome('a@b.com', true);
      expect(engine.update).toHaveBeenCalledWith(
        'sys_user',
        { id: 'u1', failed_login_count: 0, locked_until: null },
        expect.anything(),
      );
    });

    it('recordSignInOutcome skips the write on success when nothing needs clearing', async () => {
      const engine = makeEngine({ id: 'u1', email: 'a@b.com', failed_login_count: 0, locked_until: null });
      const m = mgr(engine, { lockoutThreshold: 3 });
      await (m as any).recordSignInOutcome('a@b.com', true);
      expect(engine.update).not.toHaveBeenCalled();
    });

    it('recordSignInOutcome is a no-op when lockout is disabled', async () => {
      const engine = makeEngine({ id: 'u1', email: 'a@b.com', failed_login_count: 5 });
      const m = mgr(engine, { lockoutThreshold: 0 });
      await (m as any).recordSignInOutcome('a@b.com', false);
      expect(engine.update).not.toHaveBeenCalled();
    });

    it('unlockUser clears failed_login_count and locked_until', async () => {
      const engine = makeEngine({ id: 'u1' });
      const m = mgr(engine);
      await expect(m.unlockUser('u1')).resolves.toBe(true);
      expect(engine.update).toHaveBeenCalledWith(
        'sys_user',
        { id: 'u1', failed_login_count: 0, locked_until: null },
        expect.anything(),
      );
    });

    // #3690 — sign-in can lock at either stage, and the counters are
    // independent. Unlocking only `sys_user` left a 2FA-locked user with no
    // admin escape hatch, which the now-configurable threshold makes routine.
    it('unlockUser also clears the second factor\'s lock', async () => {
      const engine = {
        ...makeEngine({ id: 'u1' }),
        find: vi.fn(async () => [{ id: 'tf1' }, { id: 'tf2' }]),
      };
      const m = mgr(engine);
      await expect(m.unlockUser('u1')).resolves.toBe(true);
      expect(engine.find).toHaveBeenCalledWith(
        'sys_two_factor',
        expect.objectContaining({ where: { user_id: 'u1' } }),
      );
      for (const id of ['tf1', 'tf2']) {
        expect(engine.update).toHaveBeenCalledWith(
          'sys_two_factor',
          { id, failed_verification_count: 0, locked_until: null },
          expect.anything(),
        );
      }
    });

    it('unlockUser still succeeds when the second-factor clear fails', async () => {
      // No enrolment, a store that cannot serve the lookup, 2FA never switched
      // on — none of that may turn the password-stage unlock the admin asked
      // for into a failure.
      const engine = {
        ...makeEngine({ id: 'u1' }),
        find: vi.fn(async () => { throw new Error('no such object: sys_two_factor'); }),
      };
      const m = mgr(engine);
      await expect(m.unlockUser('u1')).resolves.toBe(true);
      expect(engine.update).toHaveBeenCalledWith(
        'sys_user',
        { id: 'u1', failed_login_count: 0, locked_until: null },
        expect.anything(),
      );
    });

    it('unlockUser returns false for an unknown user', async () => {
      const engine = makeEngine(null);
      const m = mgr(engine);
      await expect(m.unlockUser('nope')).resolves.toBe(false);
      expect(engine.update).not.toHaveBeenCalled();
    });

    // ── ADR-0069 D7 — last-login audit stamping ──────────────────────────
    it('stampLastLogin writes last_login_at (a Date) + last_login_ip on success', async () => {
      const engine = makeEngine({ id: 'u1' });
      const m = mgr(engine);
      await (m as any).stampLastLogin('u1', '203.0.113.7');
      const patch = engine.update.mock.calls[0][1];
      expect(patch.id).toBe('u1');
      expect(patch.last_login_at instanceof Date).toBe(true); // Date, never epoch-ms (ADR-0074)
      expect(patch.last_login_ip).toBe('203.0.113.7');
    });

    it('stampLastLogin runs even when lockout is disabled (independent of threshold)', async () => {
      const engine = makeEngine({ id: 'u1' });
      const m = mgr(engine, { lockoutThreshold: 0 });
      await (m as any).stampLastLogin('u1', undefined);
      expect(engine.update).toHaveBeenCalledTimes(1);
      const patch = engine.update.mock.calls[0][1];
      expect(patch.last_login_at instanceof Date).toBe(true);
      // IP omitted (undetermined) rather than written as null/empty
      expect('last_login_ip' in patch).toBe(false);
    });

    it('stampLastLogin caps an oversized IP header to the column width (45)', async () => {
      const engine = makeEngine({ id: 'u1' });
      const m = mgr(engine);
      await (m as any).stampLastLogin('u1', 'x'.repeat(200));
      expect(engine.update.mock.calls[0][1].last_login_ip).toHaveLength(45);
    });

    it('stampLastLogin never throws when the engine write fails', async () => {
      const engine = { ...makeEngine({ id: 'u1' }), update: vi.fn(async () => { throw new Error('db down'); }) };
      const m = mgr(engine);
      await expect((m as any).stampLastLogin('u1', '203.0.113.7')).resolves.toBeUndefined();
    });

    it('passes a configured rateLimit through to betterAuth', async () => {
      let captured: any;
      (betterAuth as any).mockImplementation((cfg: any) => { captured = cfg; return { handler: vi.fn(), api: {} }; });
      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const m = new AuthManager({
        secret: SECRET,
        baseUrl: 'http://localhost:3000',
        rateLimit: { enabled: true, window: 60, max: 10, customRules: { '/sign-in/email': { window: 60, max: 10 } } } as any,
      });
      await m.getAuthInstance();
      warn.mockRestore();
      expect(captured.rateLimit).toMatchObject({ enabled: true, max: 10, window: 60 });
      expect(captured.rateLimit.customRules['/sign-in/email']).toEqual({ window: 60, max: 10 });
    });

    it('omits rateLimit from the betterAuth config when unset (keeps library defaults)', async () => {
      let captured: any;
      (betterAuth as any).mockImplementation((cfg: any) => { captured = cfg; return { handler: vi.fn(), api: {} }; });
      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const m = new AuthManager({ secret: SECRET, baseUrl: 'http://localhost:3000' });
      await m.getAuthInstance();
      warn.mockRestore();
      expect(captured).not.toHaveProperty('rateLimit');
    });

    // ── ADR-0069 D2 — shared secondaryStorage → cross-node rate limiting ──
    it('wires secondaryStorage and flips rateLimit.storage to "secondary-storage"', async () => {
      let captured: any;
      (betterAuth as any).mockImplementation((cfg: any) => { captured = cfg; return { handler: vi.fn(), api: {} }; });
      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const ss = { get: vi.fn(), set: vi.fn(), delete: vi.fn() };
      const m = new AuthManager({
        secret: SECRET, baseUrl: 'http://localhost:3000',
        rateLimit: { enabled: true, window: 60, max: 10 } as any,
        secondaryStorage: ss as any,
      });
      await m.getAuthInstance();
      warn.mockRestore();
      expect(captured.secondaryStorage).toBe(ss);
      expect(captured.rateLimit.storage).toBe('secondary-storage');
      expect(captured.rateLimit).toMatchObject({ enabled: true, max: 10, window: 60 });
    });

    it('flips rateLimit.storage even when no explicit rateLimit config is given (secondaryStorage alone)', async () => {
      let captured: any;
      (betterAuth as any).mockImplementation((cfg: any) => { captured = cfg; return { handler: vi.fn(), api: {} }; });
      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const ss = { get: vi.fn(), set: vi.fn(), delete: vi.fn() };
      const m = new AuthManager({ secret: SECRET, baseUrl: 'http://localhost:3000', secondaryStorage: ss as any });
      await m.getAuthInstance();
      warn.mockRestore();
      expect(captured.secondaryStorage).toBe(ss);
      expect(captured.rateLimit.storage).toBe('secondary-storage');
    });

    // ── #4772 — counters-only store, no session relocation ────────────────
    it('passes rateLimitStorage through as rateLimit.customStorage, without a secondaryStorage', async () => {
      let captured: any;
      (betterAuth as any).mockImplementation((cfg: any) => { captured = cfg; return { handler: vi.fn(), api: {} }; });
      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const rls = { consume: vi.fn(async () => ({ allowed: true, retryAfter: null })) };
      const m = new AuthManager({
        secret: SECRET,
        baseUrl: 'http://localhost:3000',
        rateLimitStorage: rls as any,
      });
      await m.getAuthInstance();
      warn.mockRestore();
      expect(captured.rateLimit.customStorage).toBe(rls);
      // The session store is untouched: ADR-0069 D4 revokes by writing the
      // `sys_session` row, which better-auth stops reading once it has a
      // secondaryStorage snapshot to answer from.
      expect(captured).not.toHaveProperty('secondaryStorage');
    });

    it('keeps the operator-tuned rateLimit rules alongside the custom storage', async () => {
      let captured: any;
      (betterAuth as any).mockImplementation((cfg: any) => { captured = cfg; return { handler: vi.fn(), api: {} }; });
      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const rls = { consume: vi.fn(async () => ({ allowed: true, retryAfter: null })) };
      const m = new AuthManager({
        secret: SECRET,
        baseUrl: 'http://localhost:3000',
        rateLimit: { enabled: true, window: 60, max: 10 } as any,
        rateLimitStorage: rls as any,
      });
      await m.getAuthInstance();
      warn.mockRestore();
      expect(captured.rateLimit).toMatchObject({ enabled: true, window: 60, max: 10 });
      expect(captured.rateLimit.customStorage).toBe(rls);
    });

    it('a host-supplied secondaryStorage wins — no customStorage is added', async () => {
      let captured: any;
      (betterAuth as any).mockImplementation((cfg: any) => { captured = cfg; return { handler: vi.fn(), api: {} }; });
      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const ss2 = { get: vi.fn(), set: vi.fn(), delete: vi.fn() };
      const rls = { consume: vi.fn(async () => ({ allowed: true, retryAfter: null })) };
      const m = new AuthManager({
        secret: SECRET,
        baseUrl: 'http://localhost:3000',
        secondaryStorage: ss2 as any,
        rateLimitStorage: rls as any,
      });
      await m.getAuthInstance();
      warn.mockRestore();
      expect(captured.rateLimit.storage).toBe('secondary-storage');
      expect(captured.rateLimit.customStorage).toBeUndefined();
    });

    // A settings patch replaces `rateLimit` wholesale (bindAuthSettings builds
    // a fresh object); the counter store must survive that, or tuning the
    // limits in Setup would silently un-share them again.
    it('survives an applyConfigPatch that replaces rateLimit wholesale', async () => {
      let captured: any;
      (betterAuth as any).mockImplementation((cfg: any) => { captured = cfg; return { handler: vi.fn(), api: {} }; });
      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const rls = { consume: vi.fn(async () => ({ allowed: true, retryAfter: null })) };
      const m = new AuthManager({
        secret: SECRET,
        baseUrl: 'http://localhost:3000',
        rateLimitStorage: rls as any,
      });
      await m.getAuthInstance();
      m.applyConfigPatch({ rateLimit: { enabled: true, window: 30, max: 5 } as any });
      await m.getAuthInstance();
      warn.mockRestore();
      expect(captured.rateLimit).toMatchObject({ enabled: true, window: 30, max: 5 });
      expect(captured.rateLimit.customStorage).toBe(rls);
    });
  });

  // ADR-0069 D1: password complexity validator (custom; better-auth only does
  // length). Exercised directly via the AuthManager helper.
  describe('password complexity (ADR-0069 D1)', () => {
    const SECRET = 'test-secret-at-least-32-chars-long';
    const mgr = (extra: any = {}) => {
      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const m = new AuthManager({ secret: SECRET, baseUrl: 'http://localhost:3000', ...extra });
      warn.mockRestore();
      return m;
    };

    it('is a no-op when complexity is not required (any password passes)', async () => {
      const m = mgr({ passwordRequireComplexity: false });
      await expect((m as any).assertPasswordComplexity('password')).resolves.toBeUndefined();
    });

    it('rejects a password with too few character classes', async () => {
      const m = mgr({ passwordRequireComplexity: true, passwordMinClasses: 3 });
      // only lowercase → 1 class < 3
      await expect((m as any).assertPasswordComplexity('alllowercase')).rejects.toMatchObject({
        body: { code: 'PASSWORD_POLICY_VIOLATION' },
      });
    });

    it('accepts a password meeting the required class count', async () => {
      const m = mgr({ passwordRequireComplexity: true, passwordMinClasses: 3 });
      // upper + lower + digit = 3 classes
      await expect((m as any).assertPasswordComplexity('Abcdef12')).resolves.toBeUndefined();
    });

    it('counts symbols as a class and honours a min of 4', async () => {
      const m = mgr({ passwordRequireComplexity: true, passwordMinClasses: 4 });
      await expect((m as any).assertPasswordComplexity('Abcd1234')).rejects.toMatchObject({
        body: { code: 'PASSWORD_POLICY_VIOLATION' },
      }); // 3 classes < 4
      await expect((m as any).assertPasswordComplexity('Abcd123!')).resolves.toBeUndefined(); // 4 classes
    });

    it('clamps an out-of-range min_classes into [1,4] (defaults to 3 when unset)', async () => {
      const m = mgr({ passwordRequireComplexity: true, passwordMinClasses: 99 });
      // clamped to 4 → needs all four classes
      await expect((m as any).assertPasswordComplexity('Abcd1234')).rejects.toMatchObject({
        body: { code: 'PASSWORD_POLICY_VIOLATION' },
      });
    });
  });

  // ADR-0069 D1: password history (reject reuse). Custom logic, but reuses
  // better-auth's native hash/verify — tested here with a stub verify + a
  // where-aware sys_account mock.
  describe('password history / reuse prevention (ADR-0069 D1)', () => {
    const SECRET = 'test-secret-at-least-32-chars-long';
    // verify() returns true when the candidate equals the plaintext that a hash
    // encodes — we model hashes as `hash:<plaintext>` for the stub.
    const stubVerify = async ({ password, hash }: { password: string; hash: string }) =>
      hash === `hash:${password}`;
    const makeEngine = (account: any) => ({
      findOne: vi.fn(async (_o: string, q: any) => {
        const w = q?.where ?? {};
        if (!account) return null;
        const ok = Object.entries(w).every(([k, v]) => (account as any)[k] === v);
        return ok ? account : null;
      }),
      update: vi.fn(async () => ({})),
    });
    const mgr = (engine: any, extra: any = {}) => {
      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const m = new AuthManager({ secret: SECRET, baseUrl: 'http://localhost:3000', dataEngine: engine, ...extra });
      warn.mockRestore();
      return m;
    };
    const acct = (over: any = {}) => ({
      id: 'a1', user_id: 'u1', provider_id: 'credential',
      password: 'hash:current', previous_password_hashes: JSON.stringify(['hash:old1', 'hash:old2']),
      ...over,
    });

    it('parseHashes tolerates null/garbage', () => {
      const m = mgr(makeEngine(null));
      expect((m as any).parseHashes(undefined)).toEqual([]);
      expect((m as any).parseHashes('not json')).toEqual([]);
      expect((m as any).parseHashes('["a","b"]')).toEqual(['a', 'b']);
    });

    it('is a no-op when history depth is 0 and no forced change is outstanding', async () => {
      const engine = makeEngine(acct());
      const m = mgr(engine, { passwordHistoryCount: 0 });
      await expect((m as any).assertPasswordNotReused('u1', 'current', stubVerify)).resolves.toBeUndefined();
      // The one read is the forced-change flag on `sys_user`; with none
      // outstanding the credential row is never read.
      expect(engine.findOne.mock.calls.map((c: any[]) => c[0])).toEqual(['sys_user']);
    });

    it('reports a failed forced-change flag read through the durability channel and fails open', async () => {
      const engine = makeEngine(acct());
      engine.findOne.mockImplementation(async (o: string) => {
        if (o === 'sys_user') throw new Error('sys_user read refused');
        return null;
      });
      const logger = { warn: vi.fn(), info: vi.fn() };
      const m = mgr(engine, { passwordHistoryCount: 0, logger });
      logger.warn.mockClear();
      // Fail open: treated as no forced change, so depth 0 accepts.
      await expect((m as any).assertPasswordNotReused('u1', 'current', stubVerify)).resolves.toBeUndefined();
      // ...but never silently: exactly one report naming the unread flag.
      expect(logger.warn).toHaveBeenCalledTimes(1);
      expect(logger.warn.mock.calls[0][1]).toMatchObject({
        object: 'sys_user',
        fields: ['must_change_password'],
        error: 'sys_user read refused',
      });
    });

    it('rejects reuse of the CURRENT password', async () => {
      const m = mgr(makeEngine(acct()), { passwordHistoryCount: 5 });
      await expect((m as any).assertPasswordNotReused('u1', 'current', stubVerify)).rejects.toMatchObject({
        body: { code: 'PASSWORD_REUSE' },
      });
    });

    it('rejects reuse of a HISTORICAL password', async () => {
      const m = mgr(makeEngine(acct()), { passwordHistoryCount: 5 });
      await expect((m as any).assertPasswordNotReused('u1', 'old2', stubVerify)).rejects.toMatchObject({
        body: { code: 'PASSWORD_REUSE' },
      });
    });

    it('accepts a fresh password and returns the current hash for the after-hook', async () => {
      const m = mgr(makeEngine(acct()), { passwordHistoryCount: 5 });
      await expect((m as any).assertPasswordNotReused('u1', 'brandnew', stubVerify)).resolves.toBe('hash:current');
    });

    it('recordPasswordHistory prepends the old hash, dedupes, and trims to the depth', async () => {
      const engine = makeEngine(acct({ previous_password_hashes: JSON.stringify(['hash:old1', 'hash:old2']) }));
      const m = mgr(engine, { passwordHistoryCount: 2 });
      await (m as any).recordPasswordHistory('u1', 'hash:current');
      const written = JSON.parse(engine.update.mock.calls[0][1].previous_password_hashes);
      expect(written).toEqual(['hash:current', 'hash:old1']); // prepend + trim to 2
    });

    // ---- commit d6e80b28b: the same control, against an engine that actually STRIPS ----
    //
    // ⚠️ Every test above uses `makeEngine`, which hands back the stored object
    // untouched. That is a faithful model of a strip-less engine — and it is
    // precisely why those tests carry NO information about commit d6e80b28b: once
    // `sys_account.password` and `previous_password_hashes` are `internal:
    // true`, the REAL engine omits both from this read, with no `isSystem`
    // carve-out and in spite of the explicit projection (#7728's design;
    // measured against a real ObjectQL engine + stub driver for commit d6e80b28b, which
    // returned `{"id":"a1"}` for the exact query at `assertPasswordNotReused`).
    // `compareList` then empties, the loop never runs, `PASSWORD_REUSE` is
    // never thrown, and the method's own `catch { return undefined }` means
    // nothing announces it. The suite above stays GREEN through all of that.
    //
    // So the strip is modelled explicitly here, together with the privileged
    // accessor that recovers it — this block is the canary that block is not.
    describe('under the `internal: true` strip (#8676)', () => {
      /** Mimics the real engine: omit the flagged columns, offer the accessor. */
      const INTERNAL = ['password', 'previous_password_hashes'] as const;
      const makeStrippingEngine = (account: any, opts: { accessor?: boolean } = {}) => {
        const strip = (row: any) => {
          if (!row) return row;
          const out = { ...row };
          for (const f of INTERNAL) delete out[f];
          return out;
        };
        // What the engine handed back, snapshotted AT RETURN TIME — the seam
        // repairs rows in place, so re-reading the row afterwards shows the
        // recovered copy and could never witness the strip.
        const returned: any[] = [];
        const engine: any = {
          returned,
          findOne: vi.fn(async (_o: string, q: any) => {
            const w = q?.where ?? {};
            if (!account) return null;
            const ok = Object.entries(w).every(([k, v]) => (account as any)[k] === v);
            if (!ok) return null;
            const row = strip(account);
            returned.push({ ...row });
            return row;
          }),
          update: vi.fn(async () => ({})),
        };
        if (opts.accessor !== false) {
          engine.resolveInternalField = vi.fn(
            async (_object: string, ids: readonly string[], field: string) => {
              const out = new Map<string, unknown>();
              for (const id of ids) if (account && account.id === id) out.set(id, account[field] ?? null);
              return out;
            },
          );
        }
        return engine;
      };

      it('still rejects reuse of the CURRENT password — the row arrives without it', async () => {
        const engine = makeStrippingEngine(acct());
        const m = mgr(engine, { passwordHistoryCount: 5 });
        await expect((m as any).assertPasswordNotReused('u1', 'current', stubVerify)).rejects.toMatchObject({
          body: { code: 'PASSWORD_REUSE' },
        });
        // The row really did arrive stripped — this is not the un-stripped
        // path in disguise, which would make the rejection above vacuous.
        expect(engine.returned).toHaveLength(1);
        expect('password' in engine.returned[0]).toBe(false);
        expect('previous_password_hashes' in engine.returned[0]).toBe(false);
        // …and the rest of the row survived, so it is a real row, not an empty one.
        expect(engine.returned[0].id).toBe('a1');
        expect(engine.returned[0].provider_id).toBe('credential');
      });

      it('still rejects reuse of a HISTORICAL password — the ring is recovered too', async () => {
        const m = mgr(makeStrippingEngine(acct()), { passwordHistoryCount: 5 });
        await expect((m as any).assertPasswordNotReused('u1', 'old2', stubVerify)).rejects.toMatchObject({
          body: { code: 'PASSWORD_REUSE' },
        });
      });

      it('still accepts a fresh password and returns the CURRENT hash for the after-hook', async () => {
        // Discriminating positive control for the two refusals above: the
        // recovery is selective, not a blanket throw — a genuinely new password
        // passes, and the hash it returns is the recovered one (empty string
        // here would be the silent-no-op signature, and would also make
        // `recordPasswordHistory` return early on `!oldHash`).
        const m = mgr(makeStrippingEngine(acct()), { passwordHistoryCount: 5 });
        await expect((m as any).assertPasswordNotReused('u1', 'brandnew', stubVerify)).resolves.toBe('hash:current');
      });

      it('recordPasswordHistory still grows the ring — it is rebuilt from the recovered column', async () => {
        const engine = makeStrippingEngine(acct({ previous_password_hashes: JSON.stringify(['hash:old1', 'hash:old2']) }));
        const m = mgr(engine, { passwordHistoryCount: 2 });
        await (m as any).recordPasswordHistory('u1', 'hash:current');
        const written = JSON.parse(engine.update.mock.calls[0][1].previous_password_hashes);
        // Without the recovery this would be `['hash:current']` — a ring that
        // silently never grows past one entry, forgetting every older password.
        expect(written).toEqual(['hash:current', 'hash:old1']);
        expect(engine.resolveInternalField).toHaveBeenCalledWith('sys_account', ['a1'], 'previous_password_hashes');
        // …and it does NOT dereference `password`, which this path never reads.
        expect(engine.resolveInternalField.mock.calls.map((c: any[]) => c[2])).not.toContain('password');
      });

      it('⛔ the recovery is LOAD-BEARING: drop the accessor and the control provably dies', async () => {
        // The falsification arm. This is the shape before commit d6e80b28b — a stripping
        // engine with no privileged accessor — and it is what every assertion
        // in this block would look like if the recovery were removed. Pinned so
        // the four tests above can never pass vacuously: if the strip stopped
        // mattering, THIS test goes red first.
        const engine = makeStrippingEngine(acct(), { accessor: false });
        const m = mgr(engine, { passwordHistoryCount: 5 });
        // Reusing the CURRENT password sails straight through — no throw at all.
        await expect(
          (m as any).assertPasswordNotReused('u1', 'current', stubVerify),
        ).resolves.toBe('');
        expect(engine.resolveInternalField).toBeUndefined();
      });
    });
  });

  // ADR-0069 D1: password expiry posture + stamping (the session-gate infra).
  describe('password expiry gate (ADR-0069 D1)', () => {
    const SECRET = 'test-secret-at-least-32-chars-long';
    const makeEngine = (user: any) => ({
      findOne: vi.fn(async (_o: string, q: any) => {
        const w = q?.where ?? {};
        if (!user) return null;
        return Object.entries(w).every(([k, v]) => (user as any)[k] === v) ? user : null;
      }),
      update: vi.fn(async () => ({})),
    });
    const mgr = (engine: any, extra: any = {}) => {
      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const m = new AuthManager({ secret: SECRET, baseUrl: 'http://localhost:3000', dataEngine: engine, ...extra });
      warn.mockRestore();
      return m;
    };

    it('isAuthGateActive reflects passwordExpiryDays', () => {
      expect(mgr(makeEngine(null), { passwordExpiryDays: 0 }).isAuthGateActive()).toBe(false);
      expect(mgr(makeEngine(null), { passwordExpiryDays: 90 }).isAuthGateActive()).toBe(true);
    });

    it('computeAuthGate is a no-op (no DB read) when expiry is off', async () => {
      const engine = makeEngine({ id: 'u1', password_changed_at: new Date(0).toISOString() });
      const m = mgr(engine, { passwordExpiryDays: 0 });
      await expect((m as any).computeAuthGate('u1', undefined, false)).resolves.toBeUndefined();
      expect(engine.findOne).not.toHaveBeenCalled();
    });

    it('returns PASSWORD_EXPIRED when password_changed_at is older than the window', async () => {
      const old = new Date(Date.now() - 100 * 86_400_000).toISOString();
      const m = mgr(makeEngine({ id: 'u1', password_changed_at: old }), { passwordExpiryDays: 90 });
      const gate = await (m as any).computeAuthGate('u1', undefined, false);
      expect(gate?.code).toBe('PASSWORD_EXPIRED');
    });

    it('does NOT expire when the password is within the window', async () => {
      const recent = new Date(Date.now() - 10 * 86_400_000).toISOString();
      const m = mgr(makeEngine({ id: 'u1', password_changed_at: recent }), { passwordExpiryDays: 90 });
      await expect((m as any).computeAuthGate('u1', undefined, false)).resolves.toBeUndefined();
    });

    it('treats a null password_changed_at as never-expired (upgrade-safe)', async () => {
      const m = mgr(makeEngine({ id: 'u1', password_changed_at: null }), { passwordExpiryDays: 1 });
      await expect((m as any).computeAuthGate('u1', undefined, false)).resolves.toBeUndefined();
    });

    it('stampPasswordChangedAt writes a Date (never epoch-ms) to sys_user', async () => {
      const engine = makeEngine({ id: 'u1' });
      const m = mgr(engine);
      await (m as any).stampPasswordChangedAt('u1');
      const arg = engine.update.mock.calls[0][1];
      expect(arg.id).toBe('u1');
      expect(arg.password_changed_at instanceof Date).toBe(true);
    });

    it('stampPasswordChangedAt clears must_change_password in the same write (#2766 V1)', async () => {
      const engine = makeEngine({ id: 'u1' });
      const m = mgr(engine);
      await (m as any).stampPasswordChangedAt('u1');
      const arg = engine.update.mock.calls[0][1];
      expect(arg.must_change_password).toBe(false);
    });
  });

  // #2766 V1: admin-issued force password change — reuses the auth-gate seam.
  describe('must-change-password gate (#2766 V1)', () => {
    const SECRET = 'test-secret-at-least-32-chars-long';
    const makeEngine = (user: any) => ({
      findOne: vi.fn(async (_o: string, q: any) => {
        assertEngineFindOnePredicate(_o, q);
        const w = q?.where ?? {};
        if (!user) return null;
        return Object.entries(w).every(([k, v]) => (user as any)[k] === v) ? user : null;
      }),
      update: vi.fn(async () => ({})),
      count: vi.fn(async () => 0),
    });
    const mgr = (engine: any, extra: any = {}) => {
      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const m = new AuthManager({ secret: SECRET, baseUrl: 'http://localhost:3000', dataEngine: engine, ...extra });
      warn.mockRestore();
      return m;
    };

    it('noteMustChangePasswordIssued activates the gate immediately (all config off)', () => {
      const m = mgr(makeEngine(null), {});
      expect(m.isAuthGateActive()).toBe(false);
      m.noteMustChangePasswordIssued();
      expect(m.isAuthGateActive()).toBe(true);
    });

    // [#23287, ruling C′ item 2] The forced change has its OWN code now (scope
    // `credential`); it used to reuse PASSWORD_EXPIRED.
    it('returns PASSWORD_RESET_REQUIRED for a flagged user with every config feature off', async () => {
      const m = mgr(makeEngine({ id: 'u1', must_change_password: true }), {});
      m.noteMustChangePasswordIssued(); // as the admin route does
      const gate = await (m as any).computeAuthGate('u1', undefined, false);
      expect(gate).toEqual({
        code: 'PASSWORD_RESET_REQUIRED',
        message: 'You must change your password before continuing.',
      });
    });

    it('does NOT gate an unflagged user even when the cache is hot', async () => {
      const m = mgr(makeEngine({ id: 'u1', must_change_password: false }), {});
      m.noteMustChangePasswordIssued();
      await expect((m as any).computeAuthGate('u1', undefined, false)).resolves.toBeUndefined();
    });

    it('stays a no-op (no DB read) when nothing is flagged and config is off', async () => {
      const engine = makeEngine({ id: 'u1', must_change_password: true });
      const m = mgr(engine, {});
      await expect((m as any).computeAuthGate('u1', undefined, false)).resolves.toBeUndefined();
      expect(engine.findOne).not.toHaveBeenCalled();
    });

    it('fails open when the user lookup throws', async () => {
      const engine = { findOne: vi.fn(async () => { throw new Error('db down'); }), update: vi.fn(), count: vi.fn(async () => 1) };
      const m = mgr(engine, {});
      m.noteMustChangePasswordIssued();
      await expect((m as any).computeAuthGate('u1', undefined, false)).resolves.toBeUndefined();
    });
  });

  // ADR-0069 D3: enforced MFA — reuses the auth-gate seam (same computeAuthGate).
  describe('enforced MFA gate (ADR-0069 D3)', () => {
    const SECRET = 'test-secret-at-least-32-chars-long';
    const makeEngine = (user: any) => ({
      findOne: vi.fn(async (_o: string, q: any) => {
        const w = q?.where ?? {};
        if (!user) return null;
        return Object.entries(w).every(([k, v]) => (user as any)[k] === v) ? user : null;
      }),
      update: vi.fn(async () => ({})),
    });
    // [#30201] Two-factor on by default here: the gate holds a user for MFA only
    // while they can enroll. The cases that turn it off say so (`plugins: {}`).
    const mgr = (engine: any, extra: any = {}) => {
      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const m = new AuthManager({
        secret: SECRET, baseUrl: 'http://localhost:3000', dataEngine: engine, plugins: { twoFactor: true }, ...extra,
      });
      warn.mockRestore();
      return m;
    };

    it('isAuthGateActive is true when mfaRequired (even with expiry off)', () => {
      expect(mgr(makeEngine(null), { mfaRequired: true }).isAuthGateActive()).toBe(true);
      expect(mgr(makeEngine(null), {}).isAuthGateActive()).toBe(false);
    });

    it('blocks MFA_REQUIRED for an un-enrolled user past the grace window', async () => {
      const old = new Date(Date.now() - 30 * 86_400_000).toISOString();
      const m = mgr(makeEngine({ id: 'u1', two_factor_enabled: false, mfa_required_at: old }), {
        mfaRequired: true, mfaGracePeriodDays: 7,
      });
      const g = await (m as any).computeAuthGate('u1', undefined, false);
      expect(g?.code).toBe('MFA_REQUIRED');
    });

    it('does NOT block within the grace window', async () => {
      const recent = new Date(Date.now() - 1 * 86_400_000).toISOString();
      const m = mgr(makeEngine({ id: 'u1', two_factor_enabled: false, mfa_required_at: recent }), {
        mfaRequired: true, mfaGracePeriodDays: 7,
      });
      await expect((m as any).computeAuthGate('u1', undefined, false)).resolves.toBeUndefined();
    });

    it('stamps mfa_required_at the first time (null) and does not block yet', async () => {
      const engine = makeEngine({ id: 'u1', two_factor_enabled: false, mfa_required_at: null });
      const m = mgr(engine, { mfaRequired: true, mfaGracePeriodDays: 7 });
      await expect((m as any).computeAuthGate('u1', undefined, false)).resolves.toBeUndefined();
      const wrote = engine.update.mock.calls.find((c: any[]) => 'mfa_required_at' in (c[1] ?? {}));
      expect(wrote).toBeTruthy();
      expect(wrote[1].mfa_required_at instanceof Date).toBe(true);
    });

    it('does NOT block an enrolled user (two_factor_enabled)', async () => {
      const old = new Date(Date.now() - 30 * 86_400_000).toISOString();
      const m = mgr(makeEngine({ id: 'u1', two_factor_enabled: true, mfa_required_at: old }), {
        mfaRequired: true, mfaGracePeriodDays: 7,
      });
      await expect((m as any).computeAuthGate('u1', undefined, false)).resolves.toBeUndefined();
    });

    it('grace 0 blocks an un-enrolled user immediately (after the clock is set)', async () => {
      const past = new Date(Date.now() - 1000).toISOString();
      const m = mgr(makeEngine({ id: 'u1', two_factor_enabled: false, mfa_required_at: past }), {
        mfaRequired: true, mfaGracePeriodDays: 0,
      });
      const g = await (m as any).computeAuthGate('u1', undefined, false);
      expect(g?.code).toBe('MFA_REQUIRED');
    });

    // [#30201] The twoFactor plugin's endpoints are the only enrollment path.
    // A hold while it is off answers MFA_REQUIRED to a user whose remediation
    // endpoint answers 404 — the whole-tenant lockout the card measured.
    describe('only a user who can enroll is held (#30201)', () => {
      const OLD = () => new Date(Date.now() - 30 * 86_400_000).toISOString();
      const logger = () => ({ warn: vi.fn(), info: vi.fn() });

      it('two-factor off: no hold and no grace clock started, said once with the remedy', async () => {
        const log = logger();
        const lapsed = makeEngine({ id: 'u1', two_factor_enabled: false, mfa_required_at: OLD() });
        const m = mgr(lapsed, { mfaRequired: true, mfaGracePeriodDays: 0, plugins: {}, logger: log });
        expect(m.isTwoFactorEnabled()).toBe(false);
        await expect((m as any).computeAuthGate('u1', undefined, false)).resolves.toBeUndefined();
        expect(await m.resolveUserAuthGates('u1')).toEqual([]);
        const fresh = makeEngine({ id: 'u2', two_factor_enabled: false, mfa_required_at: null });
        const m2 = mgr(fresh, { mfaRequired: true, plugins: {}, logger: log });
        expect(await m2.resolveUserAuthGates('u2')).toEqual([]);
        // The window opens when enrollment does, not before.
        expect(fresh.update).not.toHaveBeenCalled();
        // Once per manager, however many requests ask.
        expect(log.warn).toHaveBeenCalledTimes(2);
        expect(String(log.warn.mock.calls[0][0])).toMatch(/NOT enforced/);
        expect(String(log.warn.mock.calls[0][0])).toMatch(/OS_AUTH_TWO_FACTOR=true/);
        // The settings remedy is conditional: the env var outranks it.
        expect(String(log.warn.mock.calls[0][0])).toMatch(/unless OS_AUTH_TWO_FACTOR is set to false/);
      });

      it('an OS_AUTH_TWO_FACTOR=false pin outranks plugins.twoFactor, so the requirement is not enforced', async () => {
        const prior = process.env.OS_AUTH_TWO_FACTOR;
        process.env.OS_AUTH_TWO_FACTOR = 'false';
        try {
          const m = mgr(makeEngine({ id: 'u1', two_factor_enabled: false, mfa_required_at: OLD() }), {
            mfaRequired: true, mfaGracePeriodDays: 0, logger: logger(),
          });
          expect(m.isTwoFactorEnabled()).toBe(false);
          // The one answer: what is wired, what is advertised, what the gate asks.
          expect(m.getPublicConfig().features.twoFactor).toBe(false);
          expect(await m.resolveUserAuthGates('u1')).toEqual([]);
        } finally {
          if (prior === undefined) delete process.env.OS_AUTH_TWO_FACTOR;
          else process.env.OS_AUTH_TWO_FACTOR = prior;
        }
      });

      it('control: the same user is held once two-factor is on, and an enrolled user never is', async () => {
        const m = mgr(makeEngine({ id: 'u1', two_factor_enabled: false, mfa_required_at: OLD() }), {
          mfaRequired: true, mfaGracePeriodDays: 0,
        });
        expect(m.isTwoFactorEnabled()).toBe(true);
        expect((await m.resolveUserAuthGates('u1')).map((g) => g.code)).toEqual(['MFA_REQUIRED']);
        const enrolled = mgr(makeEngine({ id: 'u1', two_factor_enabled: true, mfa_required_at: OLD() }), {
          mfaRequired: true, mfaGracePeriodDays: 0, plugins: {},
        });
        expect(await enrolled.resolveUserAuthGates('u1')).toEqual([]);
      });
    });
  });

  // ADR-0069 D3 — per-org MFA tightening (an org may require MFA above the
  // global floor). Uses an object-aware engine mock (sys_user + sys_organization).
  describe('per-org enforced MFA (ADR-0069 D3)', () => {
    const SECRET = 'test-secret-at-least-32-chars-long';
    const makeEngine = (user: any, org: any) => ({
      findOne: vi.fn(async (obj: string, q: any) => {
        assertEngineFindOnePredicate(obj, q);
        const row = obj === 'sys_organization' ? org : user;
        if (!row) return null;
        const w = q?.where ?? {};
        return Object.entries(w).every(([k, v]) => (row as any)[k] === v) ? row : null;
      }),
      update: vi.fn(async () => ({})),
      count: vi.fn(async () => 1),
    });
    // [#30201] Two-factor on by default, as in the block above.
    const mgr = (engine: any, extra: any = {}) => {
      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const m = new AuthManager({
        secret: SECRET, baseUrl: 'http://localhost:3000', dataEngine: engine, plugins: { twoFactor: true }, ...extra,
      });
      warn.mockRestore();
      return m;
    };

    it('isAuthGateActive trips on the cached org-MFA flag even with global MFA off', () => {
      const m = mgr(makeEngine(null, null), {});
      // Prime the cache as if an org requires MFA.
      (m as any)._orgMfaCache = { value: true, at: Date.now() };
      expect(m.isAuthGateActive()).toBe(true);
    });

    it('blocks MFA_REQUIRED when the ACTIVE ORG requires MFA (global off) and grace elapsed', async () => {
      const old = new Date(Date.now() - 30 * 86_400_000).toISOString();
      const engine = makeEngine(
        { id: 'u1', two_factor_enabled: false, mfa_required_at: old },
        { id: 'org1', require_mfa: true },
      );
      const m = mgr(engine, { mfaRequired: false, mfaGracePeriodDays: 7 });
      (m as any)._orgMfaCache = { value: true, at: Date.now() }; // org-requires cache primed
      const g = await (m as any).computeAuthGate('u1', 'org1', false);
      expect(g?.code).toBe('MFA_REQUIRED');
    });

    it('does NOT block when the active org does not require MFA (global off)', async () => {
      const old = new Date(Date.now() - 30 * 86_400_000).toISOString();
      const engine = makeEngine(
        { id: 'u1', two_factor_enabled: false, mfa_required_at: old },
        { id: 'org1', require_mfa: false },
      );
      const m = mgr(engine, { mfaRequired: false });
      (m as any)._orgMfaCache = { value: true, at: Date.now() };
      await expect((m as any).computeAuthGate('u1', 'org1', false)).resolves.toBeUndefined();
    });

    it('[#30201] does NOT block for the active org\'s require_mfa while two-factor is off, nor start the clock', async () => {
      const engine = makeEngine(
        { id: 'u1', two_factor_enabled: false, mfa_required_at: null },
        { id: 'org1', require_mfa: true },
      );
      const m = mgr(engine, { mfaRequired: false, mfaGracePeriodDays: 0, plugins: {}, logger: { warn: vi.fn() } });
      (m as any)._orgMfaCache = { value: true, at: Date.now() };
      await expect((m as any).computeAuthGate('u1', 'org1', false)).resolves.toBeUndefined();
      expect(engine.update).not.toHaveBeenCalled();
    });

    it('is a no-op when no org requires MFA and there is no active org', async () => {
      const engine = makeEngine({ id: 'u1', two_factor_enabled: false }, null);
      const m = mgr(engine, { mfaRequired: false });
      // cache says no org requires MFA
      (m as any)._orgMfaCache = { value: false, at: Date.now() };
      await expect((m as any).computeAuthGate('u1', undefined, false)).resolves.toBeUndefined();
      expect(engine.findOne).not.toHaveBeenCalled();
    });

    // [#23287 — ruling C′ item 3] ONE per-user posture computation: the session
    // gate takes its first entry, and the API-key admission seam asks the whole
    // list for a key's owner and holds the key on an `account`-scope entry.
    // Keyed by user id, so a caller outside both seams asks the same oracle.
    // Driven over this block's engine double (sys_user + sys_organization).
    describe('resolveUserAuthGates — the per-user posture computation (#23287)', () => {
      const OLD = () => new Date(Date.now() - 400 * 86_400_000).toISOString();

      it('lists every held posture, most urgent first, so a credential-scope entry cannot hide an account one', async () => {
        const m = mgr(
          makeEngine(
            { id: 'u1', must_change_password: true, password_changed_at: OLD(), two_factor_enabled: false, mfa_required_at: OLD() },
            null,
          ),
          { passwordExpiryDays: 90, mfaRequired: true, mfaGracePeriodDays: 7 },
        );
        m.noteMustChangePasswordIssued();
        const gates = await m.resolveUserAuthGates('u1');
        expect(gates.map((g) => g.code)).toEqual(['PASSWORD_RESET_REQUIRED', 'PASSWORD_EXPIRED', 'MFA_REQUIRED']);
        // The session shows the first; the list does not change what it shows.
        expect(await (m as any).computeAuthGate('u1', undefined, false)).toEqual(gates[0]);
      });

      it('answers [] for a user no policy holds, and reads nothing when no policy is enabled', async () => {
        const enrolled = makeEngine({ id: 'u1', two_factor_enabled: true }, null);
        expect(await mgr(enrolled, { mfaRequired: true }).resolveUserAuthGates('u1')).toEqual([]);
        const idle = makeEngine({ id: 'u1' }, null);
        const m = mgr(idle, {});
        (m as any)._orgMfaCache = { value: false, at: Date.now() };
        (m as any)._mustChangeCache = { value: false, at: Date.now() };
        expect(await m.resolveUserAuthGates('u1')).toEqual([]);
        expect(idle.findOne).not.toHaveBeenCalled();
      });

      it('asks the organization the credential operates in for a per-org MFA requirement', async () => {
        const engine = makeEngine(
          { id: 'u1', two_factor_enabled: false, mfa_required_at: OLD() },
          { id: 'org_key', require_mfa: true },
        );
        const m = mgr(engine, { mfaGracePeriodDays: 7 });
        (m as any)._orgMfaCache = { value: true, at: Date.now() };
        expect((await m.resolveUserAuthGates('u1', { organizationId: 'org_key' })).map((g) => g.code))
          .toEqual(['MFA_REQUIRED']);
        // No organization: the global floor alone, which is off.
        expect(await m.resolveUserAuthGates('u1')).toEqual([]);
      });

      it('fails open on a lookup error, as the session gate does', async () => {
        const engine = makeEngine(null, null);
        engine.findOne.mockImplementation(async () => { throw new Error('db down'); });
        const m = mgr(engine, { mfaRequired: true });
        expect(await m.resolveUserAuthGates('u1')).toEqual([]);
      });
    });
  });

  // ADR-0069 D4 — session controls (idle / absolute / concurrent).
  describe('session controls (ADR-0069 D4)', () => {
    const SECRET = 'test-secret-at-least-32-chars-long';
    const mgr = (engine: any, extra: any = {}) => {
      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const m = new AuthManager({ secret: SECRET, baseUrl: 'http://localhost:3000', dataEngine: engine, ...extra });
      warn.mockRestore();
      return m;
    };
    const oneEngine = (row: any) => ({
      findOne: vi.fn(async () => row),
      update: vi.fn(async () => ({})),
      find: vi.fn(async () => []),
    });

    // [#25343] Both off no longer means no-op: the `last_activity_at`
    // heartbeat runs on every deployment (ruling 6358844136, letter A); its
    // memo and throttle are pinned in session-heartbeat-default-config.test.ts.
    it('with idle + absolute both off it revokes nothing but still writes the heartbeat', async () => {
      const engine = oneEngine({ id: 's1', created_at: new Date(0).toISOString() });
      const m = mgr(engine, {});
      await (m as any).enforceSessionControls('s1', undefined);
      expect(engine.findOne).toHaveBeenCalledTimes(1);
      expect(engine.update).toHaveBeenCalledTimes(1);
      const [, patch] = engine.update.mock.calls[0] as unknown as [string, Record<string, unknown>];
      expect(patch.last_activity_at instanceof Date).toBe(true);
      expect(patch.revoke_reason).toBeUndefined();
    });

    it('revokes (absolute_max) when the session is older than the absolute cap', async () => {
      const old = new Date(Date.now() - 100 * 3_600_000).toISOString();
      const engine = oneEngine({ id: 's1', created_at: old, last_activity_at: null, revoked_at: null });
      const m = mgr(engine, { sessionAbsoluteMaxHours: 24 });
      await (m as any).enforceSessionControls('s1', undefined);
      const patch = engine.update.mock.calls[0][1];
      expect(patch.revoke_reason).toBe('absolute_max');
      expect(patch.revoked_at instanceof Date).toBe(true);
      expect(patch.expires_at instanceof Date).toBe(true);
    });

    it('revokes (idle_timeout) when last activity is older than the idle window', async () => {
      const recentCreate = new Date(Date.now() - 60 * 60_000).toISOString();
      const staleActivity = new Date(Date.now() - 30 * 60_000).toISOString();
      const engine = oneEngine({ id: 's1', created_at: recentCreate, last_activity_at: staleActivity, revoked_at: null });
      const m = mgr(engine, { sessionIdleTimeoutMinutes: 15 });
      await (m as any).enforceSessionControls('s1', undefined);
      expect(engine.update.mock.calls[0][1].revoke_reason).toBe('idle_timeout');
    });

    it('touches last_activity_at (not revoke) when within the idle window but stale > 60s', async () => {
      const recentCreate = new Date(Date.now() - 5 * 60_000).toISOString();
      const activity2minAgo = new Date(Date.now() - 2 * 60_000).toISOString();
      const engine = oneEngine({ id: 's1', created_at: recentCreate, last_activity_at: activity2minAgo, revoked_at: null });
      const m = mgr(engine, { sessionIdleTimeoutMinutes: 15 });
      await (m as any).enforceSessionControls('s1', undefined);
      const patch = engine.update.mock.calls[0][1];
      expect(patch.last_activity_at instanceof Date).toBe(true);
      expect(patch.revoke_reason).toBeUndefined();
    });

    it('does not touch when already revoked', async () => {
      const engine = oneEngine({ id: 's1', created_at: new Date().toISOString(), revoked_at: new Date().toISOString() });
      const m = mgr(engine, { sessionIdleTimeoutMinutes: 15 });
      await (m as any).enforceSessionControls('s1', undefined);
      expect(engine.update).not.toHaveBeenCalled();
    });

    it('enforceConcurrentCap revokes the oldest sessions past the cap', async () => {
      const now = Date.now();
      const sess = [
        { id: 'a', created_at: new Date(now - 4000).toISOString(), revoked_at: null },
        { id: 'b', created_at: new Date(now - 3000).toISOString(), revoked_at: null },
        { id: 'c', created_at: new Date(now - 2000).toISOString(), revoked_at: null },
        { id: 'd', created_at: new Date(now - 1000).toISOString(), revoked_at: null },
      ];
      const engine = { findOne: vi.fn(), update: vi.fn(async () => ({})), find: vi.fn(async () => sess) };
      const m = mgr(engine, { maxConcurrentSessions: 2 });
      await (m as any).enforceConcurrentCap('u1');
      // keeps newest 2 (d, c) → revokes oldest 2 (b, a)
      const revokedIds = engine.update.mock.calls.map((c: any[]) => c[1].id).sort();
      expect(revokedIds).toEqual(['a', 'b']);
      expect(engine.update.mock.calls[0][1].revoke_reason).toBe('concurrent_cap');
    });

    it('enforceConcurrentCap is a no-op when the cap is 0', async () => {
      const engine = { findOne: vi.fn(), update: vi.fn(), find: vi.fn(async () => []) };
      const m = mgr(engine, { maxConcurrentSessions: 0 });
      await (m as any).enforceConcurrentCap('u1');
      expect(engine.find).not.toHaveBeenCalled();
    });
  });

  // ADR-0069 D5 — IP allow-list (network gating).
  describe('IP allow-list (ADR-0069 D5)', () => {
    const SECRET = 'test-secret-at-least-32-chars-long';
    const mgr = (extra: any = {}) => {
      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
      const m = new AuthManager({ secret: SECRET, baseUrl: 'http://localhost:3000', ...extra });
      warn.mockRestore();
      return m;
    };

    it('ipMatchesRange handles IPv4 CIDR + exact', () => {
      expect(ipMatchesRange('203.0.113.5', '203.0.113.0/24')).toBe(true);
      expect(ipMatchesRange('203.0.114.5', '203.0.113.0/24')).toBe(false);
      expect(ipMatchesRange('10.0.0.1', '10.0.0.1')).toBe(true);
      expect(ipMatchesRange('10.0.0.2', '10.0.0.1')).toBe(false);
      expect(ipMatchesRange('192.168.1.42', '192.168.1.42/32')).toBe(true);
      expect(ipMatchesRange('1.2.3.4', '0.0.0.0/0')).toBe(true);
    });

    it('allows any IP when no ranges are configured', () => {
      const m = mgr({});
      expect(m.isClientIpAllowed('8.8.8.8')).toBe(true);
      expect(m.isClientIpAllowed(undefined)).toBe(true);
    });

    it('allows an IP inside a configured range, blocks one outside', () => {
      const m = mgr({ allowedIpRanges: ['203.0.113.0/24', '10.0.0.5'] });
      expect(m.isClientIpAllowed('203.0.113.99')).toBe(true);
      expect(m.isClientIpAllowed('10.0.0.5')).toBe(true);
      expect(m.isClientIpAllowed('8.8.8.8')).toBe(false);
    });

    it('refuses an address the server could not establish once ranges are configured', () => {
      const m = mgr({ allowedIpRanges: ['203.0.113.0/24'] });
      expect(m.isClientIpAllowed(undefined)).toBe(false);
      expect(m.isClientIpAllowed('')).toBe(false);
    });

    it('ipMatchesRange reads an IPv4-mapped IPv6 address as the IPv4 address it denotes', () => {
      expect(ipMatchesRange('::ffff:203.0.113.5', '203.0.113.0/24')).toBe(true);
      expect(ipMatchesRange('::FFFF:203.0.114.5', '203.0.113.0/24')).toBe(false);
      expect(ipMatchesRange('::ffff:10.0.0.1', '10.0.0.1')).toBe(true);
      expect(ipMatchesRange('10.0.0.1', '::ffff:10.0.0.1')).toBe(true);
      expect(ipMatchesRange('2001:db8::1', '2001:db8::1')).toBe(true);
    });

    it('ipMatchesRange reads an IPv6 CIDR as the 128-bit prefix it names', () => {
      expect(ipMatchesRange('2001:db8::5', '2001:db8::/32')).toBe(true);
      expect(ipMatchesRange('2001:db8:ffff:ffff:ffff:ffff:ffff:ffff', '2001:db8::/32')).toBe(true);
      expect(ipMatchesRange('2001:db9::5', '2001:db8::/32')).toBe(false);
      expect(ipMatchesRange('2001:0DB8:0:0::5', '2001:db8::/32')).toBe(true);
      expect(ipMatchesRange('2001:db8:1234:5600::1', '2001:db8:1234:5600::/56')).toBe(true);
      expect(ipMatchesRange('2001:db8:1234:5700::1', '2001:db8:1234:5600::/56')).toBe(false);
      expect(ipMatchesRange('2001:db8::1', '2001:db8::1/128')).toBe(true);
      expect(ipMatchesRange('2001:db8::2', '2001:db8::1/128')).toBe(false);
      expect(ipMatchesRange('2001:db8::5', '::/0')).toBe(true);
      expect(ipMatchesRange('::1', '::1/128')).toBe(true);
      expect(ipMatchesRange('::2', '::1/128')).toBe(false);
      // A zone identifier names an interface, not an address: the address is judged.
      expect(ipMatchesRange('fe80::1%eth0', 'fe80::/10')).toBe(true);
    });

    it('ipMatchesRange compares an exact IPv6 entry by the address it denotes, not by its spelling', () => {
      expect(ipMatchesRange('2001:db8::1', '2001:DB8:0:0:0:0:0:1')).toBe(true);
      expect(ipMatchesRange('::1', '0:0:0:0:0:0:0:1')).toBe(true);
      expect(ipMatchesRange('2001:db8::2', '2001:db8::1')).toBe(false);
    });

    it('ipMatchesRange never matches across address families', () => {
      // An IPv4 range never admits a pure IPv6 address, an IPv6 range never an IPv4 one.
      expect(ipMatchesRange('::1', '0.0.0.0/0')).toBe(false);
      expect(ipMatchesRange('2001:db8::5', '0.0.0.0/0')).toBe(false);
      expect(ipMatchesRange('203.0.113.5', '::/0')).toBe(false);
      expect(ipMatchesRange('::ffff:203.0.113.5', '::/0')).toBe(false);
      // The IPv4-mapped form, dotted or hex, is still the IPv4 address it maps.
      expect(ipMatchesRange('::ffff:cb00:7105', '203.0.113.0/24')).toBe(true);
      expect(ipMatchesRange('203.0.113.5', '::ffff:203.0.113.0/24')).toBe(true);
      expect(ipMatchesRange('203.0.114.5', '::ffff:203.0.113.0/24')).toBe(false);
    });

    it('ipMatchesRange never widens a malformed IPv6 range past its base address', () => {
      expect(ipMatchesRange('2001:db8::5', '2001:db8::/129')).toBe(false);
      expect(ipMatchesRange('2001:db8::5', '2001:db8::/')).toBe(false);
      expect(ipMatchesRange('2001:db8::5', '2001:db8::/3x')).toBe(false);
      expect(ipMatchesRange('2001:db8::5', '2001:db8:::/32')).toBe(false);
      expect(ipMatchesRange('2001:db8::5', 'zz01:db8::/32')).toBe(false);
      // A prefix the family does not read leaves the base address alone, as before.
      expect(ipMatchesRange('2001:db8::', '2001:db8::/129')).toBe(true);
    });

    it('isClientIpAllowed admits an IPv6 client inside an allowed IPv6 range', () => {
      const m = mgr({ allowedIpRanges: ['2001:db8::/32', '::1'] });
      expect(m.isClientIpAllowed('2001:db8:abcd::1')).toBe(true);
      expect(m.isClientIpAllowed('::1')).toBe(true);
      expect(m.isClientIpAllowed('2001:db9::1')).toBe(false);
      expect(m.isClientIpAllowed('203.0.113.5')).toBe(false);
    });

    it('resolveClientAddress believes forwarded headers only under trustProxy', () => {
      const headers = { 'x-forwarded-for': '203.0.113.9, 10.0.0.2' };
      expect(mgr({}).resolveClientAddress({ headers, remoteAddress: '10.0.0.2' })).toBe('10.0.0.2');
      expect(mgr({ trustProxy: true }).resolveClientAddress({ headers, remoteAddress: '10.0.0.2' }))
        .toBe('203.0.113.9');
      expect(mgr({}).resolveClientAddress({ headers })).toBeUndefined();
    });
  });

  // ADR-0093 D9 — default active-org stamp on session create.
  describe('composeDatabaseHooks – session.create.before active-org default', () => {
    const OWNER_ROW = { id: 'm1', organization_id: 'org_owner', user_id: 'u1', role: 'owner' };
    const MEMBER_ROW = { id: 'm2', organization_id: 'org_member', user_id: 'u1', role: 'member' };

    function makeEngine(rows: any[]) {
      return {
        findOne: vi.fn(async (_model: string, q: any) => {
          const where = q?.where ?? {};
          return (
            rows.find(
              (r) =>
                (!where.user_id || r.user_id === where.user_id) &&
                (!where.role || r.role === where.role),
            ) ?? null
          );
        }),
      } as any;
    }

    function hooksFor(config: any) {
      const manager = new AuthManager({
        secret: 'test-secret-at-least-32-chars-long',
        baseUrl: 'http://localhost:3000',
        ...config,
      });
      return (manager as any).composeDatabaseHooks(config.databaseHooks) as any;
    }

    it('stamps activeOrganizationId from the owner membership (owner preferred)', async () => {
      const hooks = hooksFor({ dataEngine: makeEngine([MEMBER_ROW, OWNER_ROW]) });
      const result = await hooks.session.create.before({ userId: 'u1' });
      expect(result?.data?.activeOrganizationId).toBe('org_owner');
    });

    it('falls back to any membership when the user owns nothing', async () => {
      const hooks = hooksFor({ dataEngine: makeEngine([MEMBER_ROW]) });
      const result = await hooks.session.create.before({ userId: 'u1' });
      expect(result?.data?.activeOrganizationId).toBe('org_member');
    });

    it('leaves a pre-set activeOrganizationId alone', async () => {
      const engine = makeEngine([OWNER_ROW]);
      const hooks = hooksFor({ dataEngine: engine });
      const result = await hooks.session.create.before({
        userId: 'u1',
        activeOrganizationId: 'org_explicit',
      });
      // Draft already carries an org — no stamp, no lookup needed.
      expect(result?.data?.activeOrganizationId ?? 'org_explicit').toBe('org_explicit');
      expect(engine.findOne).not.toHaveBeenCalled();
    });

    it('no-ops (org-less session) when the user has no memberships', async () => {
      const hooks = hooksFor({ dataEngine: makeEngine([]) });
      const result = await hooks.session.create.before({ userId: 'u1' });
      expect(result?.data?.activeOrganizationId).toBeUndefined();
    });

    it('chains the HOST session hook first and keeps its choice', async () => {
      const hostHook = vi.fn(async (session: any) => ({
        data: { ...session, activeOrganizationId: 'org_host' },
      }));
      const hooks = hooksFor({
        dataEngine: makeEngine([OWNER_ROW]),
        databaseHooks: { session: { create: { before: hostHook } } },
      });
      const result = await hooks.session.create.before({ userId: 'u1' });
      expect(hostHook).toHaveBeenCalledTimes(1);
      expect(result?.data?.activeOrganizationId).toBe('org_host');
    });

    it('fills the field when the host hook declines (returns undefined)', async () => {
      const hostHook = vi.fn(async () => undefined);
      const hooks = hooksFor({
        dataEngine: makeEngine([OWNER_ROW]),
        databaseHooks: { session: { create: { before: hostHook } } },
      });
      const result = await hooks.session.create.before({ userId: 'u1' });
      expect(result?.data?.activeOrganizationId).toBe('org_owner');
    });

    it('autoActiveOrganization: false restores the raw host behaviour', async () => {
      const hooks = hooksFor({
        dataEngine: makeEngine([OWNER_ROW]),
        autoActiveOrganization: false,
      });
      // [#26638] `create.before` is always installed (it stamps the session's
      // client address); with the default off it fills no organization.
      const result = await hooks.session.create.before({ userId: 'u1' });
      expect(result?.data?.activeOrganizationId).toBeUndefined();
    });

    it('never breaks session create on engine errors', async () => {
      const engine = { findOne: vi.fn(async () => { throw new Error('db down'); }) } as any;
      const hooks = hooksFor({ dataEngine: engine });
      const result = await hooks.session.create.before({ userId: 'u1' });
      expect(result?.data?.activeOrganizationId).toBeUndefined();
    });

    it('keeps the account.create.after identity stamp intact', async () => {
      const hooks = hooksFor({ dataEngine: makeEngine([]) });
      expect(typeof hooks.account?.create?.after).toBe('function');
    });
  });
});

// 15.1 third-party eval — dev-only login hint for the auto-seeded admin.
// `devSeedAdmin` may only ever leave the process in development: the field
// is derived from `devSeedResult`, which the auth plugin sets exclusively
// under NODE_ENV==='development', and getPublicConfig re-checks the env as
// defense in depth. These tests pin the gate from the manager's side.
describe('getPublicConfig devSeedAdmin (dev-only login hint)', () => {
  const prevNodeEnv = process.env.NODE_ENV;
  afterEach(() => {
    process.env.NODE_ENV = prevNodeEnv;
  });

  const makeManager = () =>
    new AuthManager({
      secret: 'test-secret-at-least-32-chars-long',
      baseUrl: 'http://localhost:3000',
    });

  it('is absent when devSeedResult is unset', () => {
    process.env.NODE_ENV = 'development';
    const manager = makeManager();
    expect((manager.getPublicConfig() as any).devSeedAdmin).toBeUndefined();
  });

  it('surfaces the seeded credentials in development', () => {
    process.env.NODE_ENV = 'development';
    const manager = makeManager();
    manager.devSeedResult = { email: 'admin@objectos.ai', password: 'admin123' };
    expect((manager.getPublicConfig() as any).devSeedAdmin).toEqual({
      email: 'admin@objectos.ai',
      password: 'admin123',
    });
  });

  it('never appears outside development even if devSeedResult leaked', () => {
    process.env.NODE_ENV = 'production';
    const manager = makeManager();
    manager.devSeedResult = { email: 'admin@objectos.ai', password: 'admin123' };
    expect((manager.getPublicConfig() as any).devSeedAdmin).toBeUndefined();
  });
});

// ---------------------------------------------------------------------------
// [#10009] `isPlatformAdminUserId` — the criterion the ADR-0135 D6
// `/sso/register` before-hook now judges on.
//
// This block replaces the #5942 `isOrgOrPlatformAdmin` block that stood here.
// That method asked TWO questions ("platform admin OR org owner/admin") because
// the `/sso/register` gate admitted both. The 2026-08-20 maintainer ruling on
// #10009 narrowed that gate to platform-admin-only (ADR-0068 D4: registering an
// identity provider is a platform-operator action, matching the `/admin/sso/*`
// bridges #9653 landed), which left the wider predicate with no caller — so it
// was removed and this block follows the criterion that survived.
//
// The org-grade half of #5942 is NOT lost coverage: the one grade ladder
// (`isOrgAdminGrade`, `invitation-role-cap.ts`) keeps its own direct pins in
// `member-role-canonical.test.ts` (case, comma and array spellings) and is
// still read by `last-admin-guard.ts`. What is deliberately gone is the claim
// that THIS seam asks the org question — it no longer does, and the cases below
// pin that as a refusal rather than leaving it unstated.
// ---------------------------------------------------------------------------
describe('isPlatformAdminUserId – the /sso/register criterion is platform-admin-only (#10009)', () => {
  const SECRET = 'test-secret-at-least-32-chars-long';

  /**
   * Read-only engine stub. `platformAdmin` controls the ADR-0068
   * `admin_full_access` link, owned by the Default Organization (`org-default`,
   * slugged `default`) unless `grantOrganization` names another owner — `null`
   * for an organization-less row; `members` are `sys_member` rows, which this
   * criterion must now ignore entirely. `find` honours the `where` the judge
   * passes, so any org-scoping is the product's, not the fixture's.
   */
  const makeEngine = (opts: { members?: any[]; platformAdmin?: boolean; throws?: boolean; grantOrganization?: string | null } = {}) => bindTestSecurityCatalog({
    find: vi.fn(async (object: string, query?: any) => {
      if (opts.throws) throw new Error('db down');
      const byWhere = (rows: any[]) => {
        const where = query?.where ?? {};
        return rows.filter((row) =>
          Object.entries(where).every(([k, v]) => { if (k.startsWith('$')) throw new Error(`fake driver: unsupported operator ${k}`); return row[k] === v; }),
        );
      };
      if (object === 'sys_user_permission_set') {
        const organization_id = opts.grantOrganization === undefined ? 'org-default' : opts.grantOrganization;
        return opts.platformAdmin
          ? [{ user_id: 'u-1', permission_set_id: 'ps-admin', permission_set: 'admin_full_access', organization_id }]
          : [];
      }
      if (object === 'sys_permission_set') return [{ id: 'ps-admin', name: 'admin_full_access' }];
      if (object === 'sys_organization') {
        return byWhere([{ id: 'org-default', slug: 'default' }, { id: 'org-1', slug: 'org-1' }]);
      }
      if (object === 'sys_member') return byWhere(opts.members ?? []);
      return [];
    }),
    findOne: vi.fn(),
  }, { permissions: [{ name: ADMIN_FULL_ACCESS, ...ADMIN_FULL_ACCESS_CAPABILITIES }] });

  /** The criterion, invoked exactly as the `/sso/register` hook invokes it. */
  const judge = async (engine: any, userId = 'u-1'): Promise<boolean> => {
    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
    const manager = new AuthManager({
      secret: SECRET,
      baseUrl: 'http://localhost:3000',
      dataEngine: engine,
    });
    warn.mockRestore();
    return (manager as any).isPlatformAdminUserId(userId);
  };

  const memberRow = (role: unknown) => ({
    id: 'm-1',
    user_id: 'u-1',
    organization_id: 'org-1',
    role,
  });

  // -- (1) the narrowing: administrative MEMBERSHIP is no longer a licence ---
  describe('org owners/admins are REFUSED (the #10009 narrowing)', () => {
    it.each([
      ['owner', 'the canonical org owner'],
      ['admin', 'the canonical org admin'],
      ['Owner', 'capitalized — the #5942 ladder graded this as administrative'],
      ['ADMIN', 'shout-cased'],
      ['owner,member', 'comma-joined'],
    ])('refuses sys_member.role %j (%s)', async (role) => {
      expect(await judge(makeEngine({ members: [memberRow(role)] }))).toBe(false);
    });

    it('refuses the ARRAY spelling ["owner"] too', async () => {
      expect(await judge(makeEngine({ members: [memberRow(['owner'])] }))).toBe(false);
    });

    it('refuses an administrative membership in ANY org (no active-org escape hatch)', async () => {
      const engine = makeEngine({
        members: [{ id: 'm-1', user_id: 'u-1', organization_id: 'org-other', role: 'owner' }],
      });
      expect(await judge(engine)).toBe(false);
    });
  });

  // -- (2) the other direction: a real platform admin is still admitted ------
  describe('the ADR-0068 platform admin is still ADMITTED', () => {
    it('admits the Default Organization\'s admin_full_access grant even when the membership is a plain member', async () => {
      expect(await judge(makeEngine({ platformAdmin: true, members: [memberRow('member')] }))).toBe(true);
    });

    it('admits a platform admin who has NO membership row at all', async () => {
      expect(await judge(makeEngine({ platformAdmin: true, members: [] }))).toBe(true);
    });
  });

  // -- (3) fail-closed floor -------------------------------------------------
  describe('fail-closed floor (ADR-0135 D6)', () => {
    it('refuses a plain member with no grant', async () => {
      expect(await judge(makeEngine({ members: [memberRow('member')] }))).toBe(false);
    });

    it('refuses when the admin_full_access grant is owned by ANOTHER organization, not the Default one', async () => {
      // Any organization's grant other than the Default Organization's is an
      // org-scoped assignment — it confers the set there, never platform standing.
      expect(await judge(makeEngine({ platformAdmin: true, grantOrganization: 'org-1' }))).toBe(false);
    });

    it('refuses an ORGANIZATION-LESS admin_full_access grant — it anchors nothing', async () => {
      // Invalid state since the ownership ceremony made the column NOT NULL; the
      // reading that took it as the platform-wide link retired. The Default
      // Organization's grant on the same engine is the control (admitted above).
      expect(await judge(makeEngine({ platformAdmin: true, grantOrganization: null }))).toBe(false);
      expect(await judge(makeEngine({ platformAdmin: true }))).toBe(true);
    });

    it('refuses when the engine read throws (fail CLOSED)', async () => {
      expect(await judge(makeEngine({ throws: true, platformAdmin: true }))).toBe(false);
    });

    it('refuses an empty user id without reading anything', async () => {
      const engine = makeEngine({ platformAdmin: true });
      expect(await judge(engine, '')).toBe(false);
      expect(engine.find).not.toHaveBeenCalled();
    });
  });
});