auth-plugin.ts

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

// [#25083] `isCloudManaged`: the ONE accessor the cloud-managed doors below ask.
import { Plugin, PluginContext, IHttpServer, isCloudManaged, resolveRequestExecutionContext, type RequestAuthService } from '@objectstack/core';
import type { BetterAuthOptions } from 'better-auth';
import {
  AuthConfig,
  type AudienceConfig,
  AUDIENCE_POSTURES,
  audiencePermitsSelfRegistration,
  isAudiencePosture,
  type SocialProviderConfig,
  type SettingsChangeHandler,
  type SettingsUnsubscribe,
  SystemObjectName,
} from '@objectstack/spec/system';
// [#11767] The shared bootstrap population predicate — the audience gate's
// bootstrap bypass and plugin-security's first-user detection must answer the
// same question. [#14157] The dev-admin seed no longer GATES on it (a
// directory row is not a login); it still reads it to find the seed account
// among existing users when re-arming the credential hint.
import { isHumanUserRow, OPEN_POSTURE_VERIFICATION_OFF_WARNING } from './audience-posture.js';
// [#14157] The dev-admin seed's own precondition — "does a login exist?".
import { decideDevAdminSeedGate } from './dev-admin-seed-gate.js';
import {
  // ADR-0048 — the Setup/Studio/Account apps moved to their own packages
  // (@objectstack/{setup,studio,account}); plugin-auth no longer registers them.
  SystemOverviewDashboard,
  SystemOverviewDatasets,
} from '@objectstack/platform-objects/apps';
import { SysOrganizationDetailPage, SysUserDetailPage } from '@objectstack/platform-objects/pages';
import { PLATFORM_OWNER_EMAIL_ENV, resolvePlatformOwnerEmail, resolveTenancyPosture } from '@objectstack/types';
import { inProcessSessionReadInput, resolveThrownHttpError } from '@objectstack/types';
import { postureEnforcesWall, type OrgScopingEntitlement } from '@objectstack/spec/security';
import type { AuthSessionApi, IDataEngine, IEmailService, II18nService, IObjectQLEngine, ISmsService } from '@objectstack/spec/contracts';
import {
  AuthManager,
  resolveOidcProviderEnabled,
  readMcpServerEnabledEnv,
  isOAuthEligibleBaseUrl,
  ipMatchesRange,
  // [#16384] The one place `'/api/v1/auth'` is written — see its docblock in
  // auth-manager.ts. This file no longer carries an independent copy.
  DEFAULT_AUTH_BASE_PATH,
  type AuthManagerOptions,
} from './auth-manager.js';
import { isDefaultOrganizationBootstrapTrigger } from './ensure-default-organization.js';
import { ensureDefaultOrganizationExists } from './default-organization-invariant.js';
import { recoverInternalFieldsForSystemRead } from './internal-field-readback.js';
import { runAttributedToUser } from './auth-actor-attribution.js';
import { withSystemContext } from './objectql-adapter.js';
import type { AuthEventAuditSurface } from './auth-session-audit.js';
import { createTenancyService, type TenancyService } from './tenancy-service.js';
import {
  isMembershipPolicy,
  MEMBERSHIP_POLICIES,
  type MembershipPolicy,
} from './reconcile-membership.js';
import { runOneTimeMembershipBackfill } from './membership-backfill-ledger.js';
import { createEnsureDefaultOrganizationOnce } from './default-org-bootstrap-once.js';
import {
  registerIdentityWriteGuard,
  registerManagedUpdateWhitelist,
  type SecondaryStorageLike,
} from './identity-write-guard.js';
import { registerLastAdminGuard } from './last-admin-guard.js';
import { registerApiKeyRestoreGuard } from './api-key-restore-guard.js';
import { registerMembershipEndedSessionTrigger } from './membership-ended-session.js';
import { registerMemberRoleCanonicalization } from './member-role-canonical.js';
import { registerExternalMembershipGuard } from './external-membership.js';
import { SYS_USER_PROFILE_EDIT_FIELDS } from './sys-user-writable-fields.js';
import { MANAGED_EXTENSION_EDITABLE_FIELDS } from './managed-extension-fields.js';
import { runSetInitialPassword } from './set-initial-password.js';
import { runRegisterSsoProviderFromForm, runRegisterSamlProviderFromForm, runRequestDomainVerification, runVerifyDomain, type AuthRequestHandler } from './register-sso-provider.js';
import { runResendVerificationEmail } from './send-verification-email.js';
import { runSysSessionRevoke, sysSessionRevokeDepsFor } from './sys-session-revoke.js';
import { readJsonRequestBody } from './request-json-body.js';
import {
  seedDevWorkspaceCurrency,
  withOrganizationDefaultCurrency,
  type CurrencySettingsDoor,
} from './organization-default-currency.js';
import type { CounterStore } from './rate-limit-storage.js';
import { authIdentityManifest } from './manifest.js';
import { scheduleLegacySsoSecretMigration } from './sso-client-secret.js';
import {
  devSeedAdminEmail,
  isDevAdminSeedArmed,
  probeWalledOwnerAccountState,
  warnIfWalledOwnerCannotVerify,
  type WalledOwnerAccountState,
} from './walled-owner-verification-path.js';
import {
  probeSignInPathWiring,
  probeSignInReachability,
  reportIfNoSignInAccountExists,
  type SignInPathConfigView,
} from './boot-sign-in-reachability.js';
import { judgePlatformAdmin, isPlatformAdminUser, type PlatformAdminActor } from './platform-admin-gate.js';
import { cloudManagedRefusal } from './cloud-managed.js';
import {
  runAdminBanUser,
  runAdminUnbanUser,
  type AdminBanEndpointDeps,
} from './admin-ban-endpoints.js';


/**
 * The `settings` slot, as this plugin reads it.
 *
 * [#4251] `service-settings` registers its `SettingsService` here and the slot
 * carries no `packages/spec` contract, so this declares the two resolver methods
 * this plugin calls. Structural on purpose — plugin-auth must not depend on
 * service-settings, which is optional (both readers below already return early
 * when the slot is empty or the method is missing).
 */
interface SettingsReadSurface {
  /** Resolve one key; `source` distinguishes a stored/env value from a manifest default. */
  get(
    namespace: string,
    key: string,
    ctx?: Record<string, unknown>,
  ): Promise<{ value?: unknown; source?: string } | undefined>;
  /** Resolve a whole namespace as `key → { value, source }`. */
  getNamespace(
    namespace: string,
    ctx?: Record<string, unknown>,
  ): Promise<{ values: Record<string, { value?: unknown; source?: string } | undefined> }>;
  /**
   * Re-run a binding when the namespace changes — how the brand name, SMS
   * locale and auth namespace stay live without a redeploy. Optional: an
   * implementation without a change bus leaves the initial read in place, which
   * is what the `typeof … === 'function'` guards at each call site already say.
   *
   * The handler and unsubscribe types are the SPEC's
   * (`@objectstack/spec/system`), not re-declared here — the change bus has a
   * published contract even though the slot does not.
   */
  subscribe?(
    namespace: string | undefined,
    handler: SettingsChangeHandler,
  ): SettingsUnsubscribe;
  /**
   * [#23367] Persist one key — used ONCE, to record when this deployment
   * started enforcing the API-key lifecycle policy
   * ({@link AuthPlugin.recordApiKeyPolicyStart}). Optional, like `subscribe`.
   */
  set?(
    namespace: string,
    key: string,
    value: unknown,
    ctx?: Record<string, unknown>,
  ): Promise<unknown>;
}

/** [#23367] The auth setting that records when the API-key lifecycle policy took effect. */
const API_KEY_POLICY_STARTED_AT_KEY = 'api_key_policy_started_at';

/**
 * [#24222] What the in-process session read answers, as `AuthSessionApi` declares
 * it. better-auth's own handle answers `null` for no session, hence the
 * `| null` at each read.
 */
type SessionRead = Awaited<ReturnType<NonNullable<AuthSessionApi['getSession']>>>;

/**
 * The `protocol` slot's metadata reader, as the user-import route uses it.
 *
 * [#4251] `protocol` is a deliberately UNCONTRACTED slot (see
 * `UNCONTRACTED_SLOTS` in `eslint.config.mjs`), so the one method this route
 * needs is declared here rather than erased. It reads `sys_user`'s field
 * definitions so imported values are coerced to their declared types —
 * best-effort by contract: without it the import still runs, uncoerced.
 */
interface MetaItemReaderSurface {
  getMetaItem(ref: { type: string; name: string }): Promise<any>;
}

/**
 * Auth Plugin Options
 * Extends AuthConfig from spec with additional runtime options
 */
export interface AuthPluginOptions extends Partial<AuthConfig> {
  /**
   * ADR-0093 D1 — deployment membership policy. `'auto'` (default) auto-binds
   * every new user to the single-org default org via the reconciler; invite-only
   * deployments set `'invite-only'` to grant membership solely through explicit
   * flows (invite / add-member / SSO JIT / host hooks).
   * @default 'auto'
   */
  membershipPolicy?: MembershipPolicy;

  /**
   * Whether to automatically register auth routes
   * @default true
   */
  registerRoutes?: boolean;
  
  /**
   * Base path for auth routes
   * @default '/api/v1/auth'
   */
  basePath?: string;

  /**
   * Override the datasource that owns the identity tables (sys_user,
   * sys_session, …) when AuthPlugin's manifest is registered.
   *
   * Defaults to `'cloud'` (control-plane DB) so the historical
   * single-tenant control-plane behaviour is preserved. Per-project
   * kernels in objectos pass `'default'` so identity tables live in the
   * project's own database — each project owns its own users.
   */
  manifestDatasource?: string;

  /**
   * `additionalOrgRoles` was REMOVED in ADR-0108 (#3723) — see
   * {@link AuthManagerOptions} for the FROM → TO migration. The membership-role
   * vocabulary is closed (`owner` / `admin` / `delegated_admin` / `member`);
   * an app's own business roles are POSITIONS, assigned through
   * `sys_user_position` or an invitation carrying placement (ADR-0105 D8).
   */

  /**
   * The single-org default-organization OWNER BIND (a pre-repo decision whose
   * old label collides with this repo's ADR series — see the citation note
   * under ADR-0093 D9; the membership guarantee it backs is D9). When enabled
   * (default), the plugin binds the platform admin as `owner` of the
   * `Default Organization` (slug `default`) — or promotes the `member` row the
   * membership reconciler gave them there — on `kernel:ready` and after every
   * write matched by `isDefaultOrganizationBootstrapTrigger` (a `sys_user`
   * insert or email/email_verified update — the config-anchor trigger set —
   * plus the legacy `sys_user_permission_set` insert that `single`-posture
   * first-user promotion still writes), recreating the organization if it went
   * missing. Inert in multi-org mode — the enterprise organizations package
   * owns the bootstrap there.
   *
   * ⚠️ BREAKING (ADR-0131 D3): `false` no longer means "no organization".
   * Under the `single` posture the Default Organization is a boot invariant —
   * created in `start()` whatever this option says, before the application
   * seeds load, and a failure to create it fails the boot — because every row
   * has an owner and `single` derives it from that organization. `false` now
   * turns off only the owner bind.
   * @default true
   */
  autoDefaultOrganization?: boolean;

  /**
   * Pass-through to better-auth's `databaseHooks` option. Used by
   * platform consumers (objectos kernel) to attach a
   * `user.create.after` hook that auto-provisions a personal
   * organization for JIT-created SSO users.
   *
   * This is the seam to use because it is the ONE hook point every user
   * creation path flows through (email signup, social/OIDC sign-in,
   * admin-created accounts, SSO JIT) and ADR-0093 D2 gives such invariants a
   * single owner there. It is NOT because better-auth's adapter escapes the
   * data layer: it writes through the same ObjectQL instance and its
   * middleware/lifecycle-hook chain does run — see
   * `AuthManagerOptions.databaseHooks` for the hop-by-hop correction (#4802).
   */
  databaseHooks?: BetterAuthOptions['databaseHooks'];

  /**
   * [#20861] The HOST declares that it signs humans into this deployment
   * through a handoff route of its OWN — a sign-in path that is not a
   * login-page provider, and that mints the session without writing a
   * `sys_account` row. A hosted kernel whose owner enters through the control
   * plane's handoff is the case this exists for: that owner signs in whether or
   * not the login page shows any platform sign-in button.
   *
   * It has ONE reader, the `no_sign_in_account_at_boot` boot report
   * (`boot-sign-in-reachability.ts`): with it declared, "human `sys_user` rows,
   * zero `sys_account` rows" is this deployment's healthy state rather than an
   * unrecoverable dead end, and the shape is recorded at `debug`, naming this
   * declaration, instead of at `error`.
   *
   * ⛔ A declaration, never an inference and never a silencer. Set it only where
   * the host really mounts such a route; declared without one, it turns the loud
   * report of a deployment nobody can sign in to into a quiet one. It changes
   * nothing the login page is told — `getPublicConfig()` returns the same with
   * or without it, and no provider is registered. It is read from this option
   * alone (no env var, no setting), so the code that wires the handoff is the
   * one place it can be stated.
   * @default false
   */
  hostSignInHandoff?: boolean;

  /**
   * Whether this plugin registers the platform's default record page for
   * `sys_organization`: `sys_organization_detail`, the Members / Invitations /
   * Teams tab strip (`SysOrganizationDetailPage`, `@objectstack/platform-objects`).
   *
   * A deployment holds at most ONE `isDefault: true` record page per object; a
   * second is refused at registration with `DEFAULT_RECORD_PAGE_CONFLICT`
   * (maintainer ruling A on objectstack#23015, record 6134056653). A host that
   * ships its OWN default record page for `sys_organization` passes `false`, so
   * its page is the single default by composition. Neither registration order
   * nor a precedence rule decides it: ruling A takes neither.
   *
   * `false` removes exactly one registration, `sys_organization_detail`.
   * Everything else stays: the `sys_organization` object and every other
   * identity object, the `sys_user_detail` record page, the System Overview
   * dashboard, and the auth routes and services. The host's page then owns what
   * the platform page gave. Set `false` with no default record page of the
   * host's own, and `sys_organization`'s record view opens the synthesized
   * default layout, without the Members / Invitations / Teams tabs.
   *
   * Only an explicit `false` removes the page; `true` and an absent key keep
   * it. Read from this option alone (no env var, no setting), so the code that
   * composes the host's own page is the one place the choice is stated.
   * @default true
   */
  registerOrganizationRecordPage?: boolean;
}

/**
 * Is this plain-HTTP issuer on a LOOPBACK host (#22073)? Asked only of an issuer
 * the transport rule has already accepted (`isOAuthEligibleBaseUrl`), to pick
 * the plain-HTTP notice's level: loopback ⇒ `info`, private / link-local ⇒
 * `warn`.
 *
 * The loopback half of that rule's own allow-list, in its own terms: the
 * `localhost` / `*.localhost` names it accepts, its `127.0.0.0/8` block judged
 * by the same ADR-0069 D5 matcher (`ipMatchesRange`), and `::1`. The hostname
 * is WHATWG-canonical, as the rule reads it — `127.1`, `0x7f.1` and
 * `[0:0:0:0:0:0:0:1]` arrive here as `127.0.0.1` and `[::1]`. Every other
 * accepted host — RFC 1918, link-local, unique-local — is not loopback and
 * keeps the warning. `mcp-oauth-plaintext-notice.test.ts` pins both sides.
 */
function isLoopbackIssuer(issuer: string): boolean {
  let host: string;
  try {
    host = new URL(issuer).hostname.toLowerCase();
  } catch {
    return false;
  }
  if (host === 'localhost' || host.endsWith('.localhost')) return true;
  if (host === '[::1]') return true;
  return ipMatchesRange(host, '127.0.0.0/8');
}

/**
 * The transport's peer address for a Hono context, when the runtime exposes
 * one: the value `IHttpRequest.remoteAddress` carries on every request the
 * transport's own seams build.
 *
 * This plugin's auth routes are raw-app mounts (`getRawApp()`), which receive
 * the Hono context rather than an `IHttpRequest`, so the peer is read here the
 * way the transport reads it (`@objectstack/plugin-hono-server` `adapter.ts`
 * `readRemoteAddress`: `@hono/node-server` puts the Node `IncomingMessage` on
 * `c.env.incoming`). Every access is guarded: a runtime that exposes nothing
 * yields `undefined`, which the client-address trust rule reads as "no peer",
 * never as a value to fabricate.
 */
function readTransportPeerAddress(c: any): string | undefined {
  try {
    const incoming = c?.env?.incoming;
    const address = incoming?.socket?.remoteAddress ?? incoming?.connection?.remoteAddress;
    return typeof address === 'string' && address.length > 0 ? address : undefined;
  } catch {
    return undefined;
  }
}

/** What the transport knows about a raw-app request that its Fetch `Request` does not carry. */
function transportOf(c: any): { remoteAddress?: string } {
  const remoteAddress = readTransportPeerAddress(c);
  return remoteAddress ? { remoteAddress } : {};
}

/**
 * Authentication Plugin
 *
 * Provides authentication and identity services for ObjectStack applications.
 * 
 * **Dual-Mode Operation:**
 * - **Server mode** (HonoServerPlugin active): Registers HTTP routes at basePath,
 *   forwarding all auth requests to better-auth's universal handler.
 * - **MSW/Mock mode** (no HTTP server): Gracefully skips route registration but
 *   still registers the `auth` service, allowing HttpDispatcher.handleAuth() to
 *   simulate auth flows (sign-up, sign-in, etc.) for development and testing.
 * 
 * Features:
 * - Session management
 * - User registration/login
 * - OAuth providers (Google, GitHub, etc.)
 * - Organization/team support
 * - 2FA, passkeys, magic links
 * 
 * This plugin registers:
 * - `auth` service (auth manager instance) — always
 * - `app.com.objectstack.system` service (system object definitions) — always
 * - HTTP routes for authentication endpoints — only when HTTP server is available
 * 
 * Integrates with better-auth library to provide comprehensive
 * authentication capabilities including email/password, OAuth, 2FA,
 * magic links, passkeys, and organization support.
 */
export class AuthPlugin implements Plugin {
  name = 'com.objectstack.auth';
  /**
   * Services init() registers on every path (ADR-0116, #4131) — lets the
   * kernel name this plugin when a consumer requires one before it inits.
   */
  providesServices = ['auth', 'tenancy'];
  type = 'standard' as const;
  version = '1.0.0';
  dependencies: string[] = ['com.objectstack.engine.objectql'];
  /**
   * What that dependency is FOR, stated so the kernel can check it (#4187).
   * `init()` resolves both synchronously with no fallback: `data` builds the
   * AuthManager config, `manifest` registers the auth objects. ObjectQL
   * registers both unconditionally and the hard dependency above hoists it
   * ahead, so this never changes whether the boot succeeds — it changes what
   * a broken composition SAYS, and replaces the trailing `// manifest service
   * required` comment with the machine-checked form of the same claim.
   */
  requiresServices = ['data', 'manifest'];
  /**
   * `com.objectstack.service.settings` — order-if-present (ADR-0116, #10250).
   *
   * `start()` registers `kernel:ready` hooks that reach
   * {@link ensureAuthSettingsBound} → {@link bindAuthSettings}, which resolves
   * the `settings` service and reads `getNamespace('auth')`.
   * `SettingsServicePlugin` binds its data engine from ITS `kernel:ready`
   * hook, registered in ITS `start()`, so the plugin that starts first
   * registers the earlier hook and the earlier hook runs first. Start order is
   * the topological order over these declarations (`resolvePluginOrder`, used
   * for BOTH phases in `ObjectKernel.bootstrap`), so declaring the edge is
   * what puts the bind ahead of the read.
   *
   * Without it the order was WRONG on the shipped composition, not merely
   * incidental: `os serve` does `kernel.use(new AuthPlugin(...))` before the
   * capability loop registers `SettingsServicePlugin`, and `resolvePluginOrder`
   * preserves insertion order for plugins with no edge between them — so auth
   * started first and its reads landed in the pre-bind window, where
   * `SettingsService`'s empty in-memory fallback answers with the manifest
   * DEFAULTS and `source: 'default'` while the workspace's saved `sys_setting`
   * rows sit unread. Everything `applySettings()` derives was therefore
   * computed from defaults at boot — the ADR-0093 membership policy the D6
   * backfill runs under, and the `google_*` social-provider config — and
   * `settings.subscribe('auth', …)` only re-applies on a LATER change, so a
   * workspace that configured auth in Setup and never touched it again kept
   * booting with the wrong values.
   *
   * SOFT, not hard: a kernel with no settings service must still boot auth —
   * `bindAuthSettings` returns early when the service is absent and the
   * deployment's env / options config stands. ADR-0049 — declared is enforced:
   * `auth-settings-ordering.pin.test.ts` resolves a hostile registry that uses
   * auth BEFORE settings and proves the DECLARATION is what moves the order.
   *
   * `com.objectstack.organization-ownership-boot-guard` — the v18 boot guard
   * (`@objectstack/runtime`'s `ORGANIZATION_OWNERSHIP_BOOT_GUARD_PLUGIN_NAME`,
   * spelled here because this package does not depend on the runtime;
   * ADR-0131 D10 item 5), order-if-present: `start()` creates the Default
   * Organization, and on a kernel that composes the guard (`os serve`) a
   * database the guard refuses must be left as the guard found it, so the
   * organization is created only once the guard has judged.
   */
  optionalDependencies = ['com.objectstack.service.settings', 'com.objectstack.organization-ownership-boot-guard'];


  private options: AuthPluginOptions;
  private authManager: AuthManager | null = null;
  /** ADR-0093 D4 — the tenancy service registered in init(); reused at kernel:ready. */
  private tenancy: TenancyService | null = null;
  /** [ADR-0131 D3] Whether `start()` created the Default Organization (a fresh install). */
  private defaultOrganizationCreatedAtBoot = false;
  /**
   * ADR-0069 D5 — each operator-facing allow-list refusal explanation is logged
   * once per process: the first refusal of an undetermined address, and the
   * first refusal that judged the peer while an untrusted forwarded header was
   * present.
   */
  private allowListUndeterminedWarned = false;
  private allowListUntrustedHeaderWarned = false;
  private configuredSocialProviders: SocialProviderConfig | undefined;
  // ADR-0092 D6 — the EFFECTIVE better-auth secondaryStorage (host-supplied or
  // the kernel-cache adapter wired in init). The identity write guard's
  // session-snapshot refresh reads through this; undefined = refresh no-ops.
  private effectiveSecondaryStorage: AuthManagerOptions['secondaryStorage'];

  /**
   * Memoized `bindAuthSettings()` run — see {@link ensureAuthSettingsBound}.
   */
  private authSettingsBinding: Promise<void> | null = null;

  constructor(options: AuthPluginOptions = {}) {
    this.options = {
      registerRoutes: true,
      basePath: DEFAULT_AUTH_BASE_PATH,
      ...options
    };
  }

  /**
   * Open-source provider fallback: enable Google sign-in from conventional
   * provider env vars when the application did not configure Google itself.
   * Enterprise / product packages can contribute richer provider sets through
   * the `auth:configure` hook below.
   */
  private applyEnvSocialProviderFallbacks(config: AuthManagerOptions & AuthPluginOptions): void {
    const env = (globalThis as any)?.process?.env as Record<string, string | undefined> | undefined;
    if (String(env?.OS_AUTH_GOOGLE_ENABLED ?? 'true').toLowerCase() === 'false') return;
    const googleClientId = env?.GOOGLE_CLIENT_ID;
    const googleClientSecret = env?.GOOGLE_CLIENT_SECRET;
    if (!googleClientId || !googleClientSecret) return;

    const socialProviders = {
      ...(config.socialProviders ?? {}),
    } as NonNullable<AuthPluginOptions['socialProviders']>;

    if (!socialProviders.google) {
      socialProviders.google = {
        clientId: googleClientId,
        clientSecret: googleClientSecret,
        enabled: true,
      };
      config.socialProviders = socialProviders;
    }
  }

  async init(ctx: PluginContext): Promise<void> {
    ctx.logger.info('Initializing Auth Plugin...');

    // Validate required configuration
    if (!this.options.secret) {
      throw new Error('AuthPlugin: secret is required');
    }

    // Get data engine service for database operations. This plugin declares a
    // hard dependency on ObjectQL (which registers `data` unconditionally), so
    // the service is always present here.
    //
    // There used to be an `if (!dataEngine) warn('…auth will use in-memory
    // storage')` guard under this line. It could never fire and the fallback it
    // named did not exist: `getService` THROWS for an unregistered service, it
    // does not return undefined, and the hard dependency means a kernel without
    // the engine fails earlier still with "Dependency … not found". A branch
    // that advertises a tolerance the composition forbids is worse than no
    // branch — it reads as a supported degraded mode (#4187). AuthManager keeps
    // its own `dataEngine?` guards because it is usable outside this plugin.
    const dataEngine = ctx.getService<IDataEngine>('data');

    const authConfig: AuthManagerOptions & AuthPluginOptions = {
      ...this.options,
      dataEngine,
      logger: ctx.logger,
      // ADR-0093 D2/D3 — the membership reconciler consults the tenancy service
      // (lazily, at hook-fire time — the service is registered below, after the
      // `auth` service) to resolve the target org. membershipPolicy defaults to
      // 'auto' in the reconciler.
      getTenancy: () => {
        try {
          return ctx.getService<TenancyService>('tenancy');
        } catch {
          return undefined;
        }
      },
      // [#8144] The compliance ledger's non-CRUD ingress, resolved LAZILY at
      // session-hook fire time (i.e. per request, long after boot). AuditPlugin
      // is an optional pair in the CLI, so a miss is the ordinary case, not a
      // degradation to report: no audit plugin means no `login`/`logout` rows,
      // which is exactly the behaviour before this card. Deliberately NOT an
      // `optionalDependencies` entry — nothing in `init()` consumes it, so
      // there is no boot ordering to constrain.
      getAuditSink: () => {
        try {
          return ctx.getService<AuthEventAuditSurface>('audit');
        } catch {
          return undefined;
        }
      },
      // [#24154] The `i18n` service, resolved LAZILY at send time: the
      // invitation mail names the membership role by the option label the
      // console reads through this same service. `getService` throws for an
      // unregistered service; the mail then names the authored label.
      getI18n: () => {
        try {
          return ctx.getService<II18nService>('i18n');
        } catch {
          return undefined;
        }
      },
    };

    // ADR-0069 D2 — cross-node rate-limit counters, backed by the kernel
    // `cache` service and resolved LAZILY (#4772).
    //
    // This used to be an eager `getServiceAsync('cache')` probe right here,
    // whose answer was frozen for the life of the process. `init()` runs before
    // CacheServicePlugin registers the service (21ms earlier in a showcase cold
    // start), so the probe resolved `undefined` in deployments that HAVE a cache
    // configured, and the warning it printed sent operators to provision Redis
    // for a problem they did not have. Worse than the misdiagnosis: the
    // degradation was real and permanent — the counters never reached the shared
    // store even once it came up, so a multi-node deployment's limits were never
    // enforced globally. `createLazyCacheRateLimitStorage` resolves the service
    // at the moment a counter is consumed, which is strictly after `kernel:ready`
    // and therefore after ANY plugin ordering, and warns only when a counter
    // genuinely has nowhere shared to count.
    //
    // Deliberately `rateLimit.customStorage`, NOT `secondaryStorage`: a
    // `secondaryStorage` also relocates the SESSION of record into the cache
    // (better-auth's `createSession` skips the `sys_session` row and
    // `findSession` answers from the snapshot without reading the database),
    // which would silently disable the ADR-0069 D4 session controls — idle
    // timeout, absolute max and concurrent cap all revoke by writing that row.
    // Whether the session of record should live in the cache at all is #4785.
    // A host that supplies `secondaryStorage` itself still wins and keeps
    // better-auth's own `storage: 'secondary-storage'` counters.
    //
    // The SAME resolution carries ObjectStack's own per-number OTP send budget
    // (#2780) below — that counter had the identical hole (#4790): it counted
    // in `secondaryStorage` when a host supplied one and per-process otherwise,
    // which under the standard `serve` composition (nobody supplies one) meant
    // every node granted the same phone number its own cooldown + hourly cap.
    // The currency there is paid SMS, so an N-node deployment was billed for up
    // to N× the declared budget.
    //
    // The `cache` service is registered ASYNC — `getService` throws for it, so
    // resolve via `getServiceAsync` and treat any failure (not registered, or
    // not yet ready) as "no shared cache, ask again later".
    const resolveCache = async (): Promise<CounterStore | undefined> => {
      let cache: any;
      try {
        cache = await (ctx as { getServiceAsync?: (n: string) => Promise<unknown> })
          .getServiceAsync?.('cache');
      } catch {
        return undefined;
      }
      if (cache && typeof cache.get === 'function' && typeof cache.set === 'function') return cache;
      return undefined;
    };

    {
      const { createLazyCacheRateLimitStorage, createLazyCounterStore } = await import(
        './rate-limit-storage.js'
      );
      if (!authConfig.secondaryStorage) {
        authConfig.rateLimitStorage = createLazyCacheRateLimitStorage({
          resolveCache,
          logger: ctx.logger,
        });
      }
      // #4790 — ObjectStack's own counters. Wired even when the host supplied a
      // `secondaryStorage` (AuthManager prefers that store for the budget and
      // then never calls this resolver), so the two decisions stay independent.
      authConfig.sharedCounterStore = createLazyCounterStore({
        resolveCache,
        logger: ctx.logger,
        subject: 'per-number OTP send budget',
        degradedImpact:
          'The budget is still enforced, but PER NODE: every node grants the same phone number its own ' +
          'cooldown and hourly cap, so an N-node deployment can send up to N× the configured number of ' +
          'PAID SMS to one number',
      });
    }

    this.applyEnvSocialProviderFallbacks(authConfig);

    // Open extension point for packages that contribute auth providers
    // (enterprise SSO, hosted control-plane SSO, etc.) without forking
    // framework's AuthPlugin. Handlers mutate the draft config in place.
    await ctx.trigger('auth:configure', authConfig, ctx);
    this.configuredSocialProviders = authConfig.socialProviders
      ? { ...authConfig.socialProviders }
      : undefined;

    // [ADR-0105 D8] Lazy handle to plugin-security's `invitation-placement`
    // service. LAZY on purpose: plugin-security starts after plugin-auth, so
    // an eager lookup here would always miss and silently disable scoped
    // invitations. Resolved per hook invocation instead; `undefined` (no
    // plugin-security) makes a placement-carrying invitation fail closed.
    authConfig.invitationPlacement = async () => {
      try {
        const svc =
          (await (ctx as { getServiceAsync?: (n: string) => Promise<unknown> }).getServiceAsync?.(
            'invitation-placement',
          )) ?? ctx.getService?.('invitation-placement');
        return svc as never;
      } catch {
        return undefined;
      }
    };

    // [#25495] A new organization takes its creator's default currency
    // (`localization.currency`), derived from their stored language or the
    // creating request's `Accept-Language`; nothing derivable ⇒ nothing
    // written, a value already set ⇒ left alone. Wrapped AFTER
    // `auth:configure` so a host's own `onOrganizationCreated`, from the
    // plugin options or from a configure handler, still runs, and runs first.
    // The settings service is resolved when an organization is created, not
    // here: it starts after this plugin.
    authConfig.onOrganizationCreated = withOrganizationDefaultCurrency(authConfig.onOrganizationCreated, {
      dataEngine,
      getSettings: () => {
        try {
          return ctx.getService<CurrencySettingsDoor>('settings');
        } catch {
          return undefined;
        }
      },
      logger: ctx.logger,
    });

    // Initialize auth manager with data engine
    this.authManager = new AuthManager(authConfig);
    // ADR-0092 D6 — remember the storage better-auth will actually use so the
    // identity write guard can keep cached session snapshots coherent.
    this.effectiveSecondaryStorage = authConfig.secondaryStorage;

    // Register auth service
    ctx.registerService('auth', this.authManager);

    // ADR-0093 D4 / ADR-0105 D1 — register the `tenancy` service (single source
    // of truth for the tenancy POSTURE). Registered AFTER `auth` so `auth` stays
    // the plugin's first service registration (consumers and tests rely on that
    // ordering). The `isolated` posture derives `isolationActive` from the
    // presence of the `org-scoping` service (registered by
    // @objectstack/organizations when installed), so that package needs no
    // change to light it up; `group` is enforced by the open engine and
    // never probes. `getService` is a cheap registry lookup and org-scoping
    // registers AFTER plugin-auth, so the probe is deferred to first read
    // (start()/request time).
    const requestedPosture = resolveTenancyPosture();
    // [#11184 / cloud#1509] Fail-closed clause of the 2026-08-23 ruling
    // (「1509 选择 env 指定 owner 邮箱」): a WALLED posture must declare its
    // platform owner. Under `group`/`isolated` the "first registrant becomes
    // platform admin" bootstrap path is removed (plugin-security's
    // `bootstrapPlatformAdmin` grants the cross-tenant `admin_full_access`
    // only to the account matching the declared owner email), so a walled
    // deployment with no owner declared would otherwise boot into a state
    // with NO way to ever mint a platform admin — or, worse, tempt a silent
    // fallback to first-registrant elevation, the exact hole cloud#1509
    // measured. Refuse startup instead, naming the variable — the same
    // fail-fast direction as `resolveTenancyPosture`'s own throw and the
    // ADR-0093 D5 degraded-tenancy guard. A throw here aborts kernel boot
    // (Phase 1 `init()` failures propagate). The `single` posture never
    // consults the variable: "first user is owner" stays as ruled.
    if (postureEnforcesWall(requestedPosture) && !resolvePlatformOwnerEmail()) {
      throw new Error(
        `[auth] tenancy posture '${requestedPosture}' requires ${PLATFORM_OWNER_EMAIL_ENV} to be set. ` +
          'Under walled postures the first self-registrant is NOT promoted to platform admin; ' +
          'the platform-admin grant goes only to the account whose email matches the declared ' +
          'owner. Refusing to boot rather than silently reverting to first-registrant elevation. ' +
          `Set ${PLATFORM_OWNER_EMAIL_ENV} to the operator's email address, or set ` +
          "OS_TENANCY_POSTURE=single to run single-org.",
      );
    }
    const tenancy: TenancyService = createTenancyService({
      requested: requestedPosture,
      probeIsolation: () => {
        try {
          return !!ctx.getService('org-scoping');
        } catch {
          return false;
        }
      },
      // [ADR-0105 D12] Which walled postures the installed multi-org runtime
      // entitles. The open side ASKS rather than assuming "package present ⇒
      // every posture": whether `group` and `isolated` are one commercial tier
      // or two is packaging policy, and that belongs to the commercial runtime.
      // A runtime that declares nothing keeps today's behavior (both).
      probeEntitledPostures: () => {
        try {
          return ctx.getService<OrgScopingEntitlement>('org-scoping')?.supportedPostures;
        } catch {
          return undefined;
        }
      },
      getEngine: () => {
        try {
          return ctx.getService('objectql');
        } catch {
          return undefined;
        }
      },
      logger: ctx.logger,
    });
    ctx.registerService('tenancy', tenancy);
    this.tenancy = tenancy;

    // Only an explicit `false` leaves the organization page out — see
    // `AuthPluginOptions.registerOrganizationRecordPage`.
    const registerOrganizationRecordPage = this.options.registerOrganizationRecordPage !== false;

    ctx.getService<{ register(m: any): void }>('manifest').register({
      // The header, `objects` and `objectExtensions`, from the ONE builder
      // `IdentityObjectsPlugin` registers on its own in a reduced kernel, so the
      // two paths cannot carry different lists. In it:
      // - [ADR-0108 / #3723] `objects` registered as authored: nothing widens
      //   the `sys_invitation.role` / `sys_member.role` selects at boot. The
      //   closed four-name vocabulary those objects declare statically
      //   (`BUILTIN_MEMBERSHIP_ROLE_OPTIONS`) is the whole list, and it is the
      //   write-side guardrail that keeps an ungoverned capability grant
      //   unrepresentable.
      // - [#8009] `objectExtensions` carries
      //   `sys_sso_provider.oidc_client_secret`, the encrypted home of the OIDC
      //   client secret that used to sit in cleartext inside `oidc_config`. See
      //   `manifest.ts` for why the field is declared there and not on the
      //   object file.
      ...authIdentityManifest({ datasource: this.options.manifestDatasource }),
      // ADR-0048 — Setup/Studio/Account apps (and the Setup nav contributions)
      // moved to their own one-app packages (@objectstack/{setup,studio,account}),
      // each registering under its own package id so /apps/<packageId> resolves
      // unambiguously. plugin-auth keeps only the auth objects + their pages.
      // Slotted record-detail pages for system objects — currently
      // sys_organization gets a Members / Invitations / Teams tab strip
      // (see SysOrganizationDetailPage for the rationale and the
      // intentionally-omitted OAuth / SSO tabs).
      //
      // `registerOrganizationRecordPage: false` leaves the organization page
      // out, for a host that ships its own `sys_organization` default record
      // page: one default per object per deployment, kept by composition
      // (ruling A on objectstack#23015). `SysUserDetailPage` is registered
      // either way.
      pages: [...(registerOrganizationRecordPage ? [SysOrganizationDetailPage] : []), SysUserDetailPage],
      // List views for each Setup-nav object are defined on the schema
      // itself via the canonical `listViews` map (e.g.
      // sys_user.listViews.{all_users,unverified,two_factor}). Registering
      // top-level views here is the legacy pre-M10.30c pattern — it caused
      // duplicate "Users"/"Roles"/"Sessions" tabs to appear alongside the
      // schema-derived ones, sometimes referencing nonexistent fields
      // (e.g. legacy `users.view` had phone/status/active columns that do
      // not exist on sys_user). Schema-embedded listViews is the single
      // source of truth.
      dashboards: [SystemOverviewDashboard],
      // ADR-0021 — datasets backing the System Overview dashboard's widgets.
      datasets: SystemOverviewDatasets,
      // ADR-0135 D6 / cloud#551 — surface "SSO Providers" (sys_sso_provider) in the
      // Setup app's Access Control group, but ONLY when the external-IdP RP is
      // wired (self-host `OS_SSO_ENABLED`, or the cloud per-env `planAllowsSso`
      // arriving via `plugins.sso`). Without the gate the entry would render an
      // empty list + a "Register" button whose endpoint 404s when SSO is off.
      // Owning-plugin-contributes pattern (ADR-0029 K2), mirroring plugin-security.
      ...(this.authManager.isSsoWired()
        ? {
            navigationContributions: [
              {
                app: 'setup',
                group: 'group_access_control',
                // After Roles/Permission-Sets (100) and Sharing (200), near API Keys (300).
                priority: 250,
                items: [
                  {
                    id: 'nav_sso_providers',
                    type: 'object',
                    label: 'SSO Providers',
                    objectName: 'sys_sso_provider',
                    icon: 'log-in',
                    requiredPermissions: ['manage_platform_settings'],
                  },
                ],
              },
            ],
          }
        : {}),
    });
    if (!registerOrganizationRecordPage) {
      // A deliberate composition, said once at boot so a missing tab strip is
      // never left to be diagnosed from its absence.
      ctx.logger.info(
        '[auth] sys_organization_detail is not registered (registerOrganizationRecordPage: false): the host ' +
          'composes its own default record page for sys_organization. Without one, the organization record ' +
          'view opens the synthesized default layout, with no Members / Invitations / Teams tabs.',
      );
    }

    // [ADR-0108 / #3723] There is no organization-role derivation any more.
    //
    // A `kernel:ready` hook used to walk the registered `position` /
    // `permission` metadata and widen both the better-auth role map and the two
    // `role` selects, so every host got app-declared roles with no wiring. That
    // made an UNGOVERNED capability channel automatic in every deployment: a
    // name stored in `sys_member.role` is projected into
    // `current_user.positions` with none of ADR-0090 D12's controls. Positions
    // are the governed channel, and an invitation carrying placement
    // (ADR-0105 D8) is the one-step admission flow that replaces it.
    ctx.logger.info('Auth Plugin initialized successfully');
  }

  async start(ctx: PluginContext): Promise<void> {
    ctx.logger.info('Starting Auth Plugin...');

    if (!this.authManager) {
      throw new Error('Auth manager not initialized');
    }

    // [ADR-0131 D3] The Default Organization is a BOOT INVARIANT under the
    // `single` posture: it owns every row, so it exists before the application
    // seeds load (every `AppPlugin` declares this plugin in its
    // `optionalDependencies`, so the kernel starts it first) and before the
    // server accepts a request (`kernel:listening` follows every `start()`).
    // A failure THROWS and fails the boot — never warn-only.
    //
    // Judged on the posture IN FORCE (`tenancy.posture`), the same judge
    // `AppPlugin` uses to decide on its inline seed: a degraded walled request
    // behaves as `single` and seeds inline, so it needs the owner too.
    //
    // ⛔ Not gated on `autoDefaultOrganization`. That option governs the
    // platform admin's OWNER BIND (below, on `kernel:ready`); whether the
    // organization exists is not an onboarding convenience any more — under
    // `single` no row is org-less (ADR-0131 D11).
    if (this.tenancy?.posture === 'single') {
      let ql: IDataEngine | undefined;
      try { ql = ctx.getService<IDataEngine>('objectql'); } catch { ql = undefined; }
      // An engine that can neither read nor write (mock mode — the same guard
      // `ensureDefaultOrganization` opens with) writes no row that needs an
      // owner. A real composition always has one: `objectql` is this plugin's
      // hard dependency.
      if (ql && typeof ql.find === 'function' && typeof ql.insert === 'function') {
        const invariant = await ensureDefaultOrganizationExists(ql, { logger: ctx.logger });
        if (invariant.created) this.defaultOrganizationCreatedAtBoot = true;
        if (invariant.ambiguous) {
          ctx.logger.warn(
            `[auth] the 'single' tenancy posture holds ${invariant.ambiguous.organizationCount} organizations and none `
              + 'is the Default Organization (slug \'default\'), so no owner is derivable: system writes and seed rows '
              + 'that need one are refused (ADR-0131 D9). The tenancy organization census names the remedies.',
          );
        }
      }
    }

    // [#8009] Move any provider row still holding a CLEARTEXT OIDC client
    // secret in `oidc_config` into the encrypted column. Registered
    // unconditionally (not under `registerRoutes`) because the disposition of
    // an already-stored secret does not depend on whether this process serves
    // the auth routes. The returned unsubscribe is deliberately dropped: the
    // engine outlives the plugin and there is no `stop()` to unwind it in.
    ctx.hook('kernel:ready', async () => {
      let ql: IDataEngine | undefined;
      try { ql = ctx.getService<IDataEngine>('objectql'); } catch { ql = undefined; }
      if (!ql) {
        try { ql = ctx.getService<IDataEngine>('data'); } catch { ql = undefined; }
      }
      if (!ql) return;
      scheduleLegacySsoSecretMigration(ql, ctx.logger);
    });

    // [#23367, ruling A] Record when this deployment started enforcing the
    // API-key lifecycle policy — ONCE, in the `auth` settings, so the anchor
    // survives restarts and every node reads the same instant (⛔ never the
    // process start). On `kernel:bootstrapped`, strictly after every
    // `kernel:ready` handler, because the settings engine binds from one of
    // them and a write inside that window is refused
    // (`SETTINGS_ENGINE_NOT_BOUND`). Registered independently of
    // `registerRoutes`: the policy is judged wherever keys are admitted.
    ctx.hook('kernel:bootstrapped', async () => {
      await this.recordApiKeyPolicyStart(ctx);
    });

    // Setup App translations are now loaded by `PlatformObjectsPlugin`
    // (in @objectstack/platform-objects). Translation bundles belong with
    // the package that defines them; auth-plugin no longer piggy-backs on
    // its kernel:ready hook for this.

    // Bind the auth manager's live SERVICE COMPOSITION on `kernel:ready`: the
    // outbound mail transport, the SMS transport, the deployment email locale,
    // the brand name and the SMS locale.
    //
    // Registered independently of `registerRoutes`, the shape the sibling
    // hooks below already use and already name ("Registered independently of
    // `registerRoutes` so an embedding that serves no auth routes still gets
    // the diagnosis"). `registerRoutes` answers "should this plugin mount its
    // own `/api/v1/auth/*` routes on the kernel's `http-server`" — a
    // TRANSPORT-MOUNTING question. Everything bound here is SERVICE
    // COMPOSITION, true of an embedding regardless of who serves the routes.
    //
    // Gating the two together left every routes-less embedding with no mail
    // transport, no locale on either channel and no brand binding — and
    // silently, because the `logger.info` lines that would have reported the
    // wiring sat inside the same skipped block. The population is not an edge
    // case: every cloud tenant environment kernel constructs this plugin with
    // `registerRoutes: false` by design, since the per-env kernel has no
    // `http-server` and the host worker proxies the auth routes to it. The
    // consequence was that the `localization.locale` precedence rung below
    // could not reach a tenant environment at all — not degraded, absent.
    //
    // Registered BEFORE the route hook so that, when routes ARE mounted, the
    // composition still completes ahead of them: the ordering the single
    // combined hook used to give for free.
    ctx.hook('kernel:ready', async () => {
      // Inject the email service if available so better-auth callbacks
      // (sendResetPassword / sendVerificationEmail / sendInvitationEmail
      // / sendMagicLink) can actually deliver mail. Resolved here on
      // kernel:ready so EmailServicePlugin has had a chance to register.
      if (this.authManager) {
        await this.ensureAuthSettingsBound(ctx);

        // [#20389] The `open` posture's verification opt-out is LOUD: once per
        // boot, after the settings namespace (which carries the
        // OS_AUTH_REQUIRE_EMAIL_VERIFICATION env override) has been applied,
        // read from the same advertisement the login UI reads.
        if (
          this.authManager.getAudience().posture === 'open' &&
          this.authManager.getPublicConfig?.()?.emailPassword?.requireEmailVerification === false
        ) {
          ctx.logger.warn(OPEN_POSTURE_VERIFICATION_OFF_WARNING);
        }

        let emailSvc: IEmailService | undefined;
        try { emailSvc = ctx.getService<IEmailService>('email'); } catch { emailSvc = undefined; }
        if (emailSvc) {
          this.authManager.setEmailService(emailSvc);
          ctx.logger.info('Auth: email service wired (transactional mail enabled)');
        } else {
          // No email service. The verification / password-reset callbacks now
          // THROW when invoked without a transport (so an explicit resend
          // reports a real error rather than faking success). If verification
          // is REQUIRED, that means every signup would be stuck — surface the
          // misconfiguration loudly at boot instead of one failure per signup.
          const requiresEmail = !!this.authManager.getPublicConfig?.()?.emailPassword?.requireEmailVerification;
          if (requiresEmail) {
            // [#20389] The second remedy is only real where the posture lets the
            // deployment turn verification off: `email_domain` refuses it.
            const disableRemedy = this.authManager.getAudience().posture === 'email_domain'
              ? "; verification cannot be turned off under the 'email_domain' audience posture."
              : ' or disable verification (OS_AUTH_REQUIRE_EMAIL_VERIFICATION=false).';
            ctx.logger.error(
              'Auth: email verification is REQUIRED but NO email service is registered — '
              + 'verification & password-reset emails will FAIL and new users will be locked '
              + 'out at sign-in. Register an email service (e.g. EmailServicePlugin + OS_EMAIL_*)'
              + disableRemedy,
            );
          } else {
            ctx.logger.info('Auth: no email service registered — transactional mail disabled');
          }
        }

        // #2780 — inject the SMS service so the phoneNumber plugin's OTP
        // callbacks (send-otp / password-reset OTP) and the import
        // SMS-invite path can deliver. Same lazy-resolution contract as
        // the email service: absent ⇒ OTP endpoints keep failing loudly
        // (NOT_SUPPORTED) while phone+password sign-in still works.
        let smsSvc: ISmsService | undefined;
        try { smsSvc = ctx.getService<ISmsService>('sms'); } catch { smsSvc = undefined; }
        if (smsSvc) {
          this.authManager.setSmsService(smsSvc);
          if (this.authManager.isPhoneNumberEnabled()) {
            ctx.logger.info(
              this.authManager.isPhoneOtpDeliverable()
                ? 'Auth: sms service wired (phone-number OTP sign-in / reset enabled)'
                : 'Auth: sms service present but NOT configured with a real provider — phone-number OTP stays disabled in production',
            );
          }
        } else if (this.authManager.isPhoneNumberEnabled()) {
          ctx.logger.info('Auth: no sms service registered — phone-number OTP disabled (password sign-in only)');
        }

        // #8195 / #14319 — the locale named on every auth EMAIL, so the
        // localized `sys_email_template` rows are reachable through the
        // platform's own send path instead of sitting dormant.
        //
        // This binds the DEPLOYMENT rung, resolved here at the plugin
        // layer. Since the 2026-09-02 ruling (#14319) it is the SECOND rung:
        // a request-triggered send whose recipient IS the requester takes
        // that caller's own `Accept-Language` first, resolved at send time in
        // `AuthManager` (`authEmailLocaleFromRequest`, which carries the
        // ruling text). What is bound here answers when the request named no
        // locale this platform ships a row for, or when there is no request
        // at all — invitations, scheduled and admin-initiated mail.
        //
        // ⚠️ The superseded 2026-08-13 ruling made this rung the WHOLE answer
        // and rejected `Accept-Language` outright. Do not restore that
        // reading here; the single place the history is recorded is
        // `AuthManager.setDefaultEmailLocale`.
        //
        // #14319 measured that "the deployment default" has TWO producers,
        // and that auth email was reading the weaker one:
        //
        //  - `II18nService.getDefaultLocale()` is the app artifact's
        //    BUILD-TIME `i18n.defaultLocale` (`AppPlugin` pushes it through
        //    `setDefaultLocale`; the CLI passes `config.i18n.defaultLocale`),
        //    and is the bare `en` when the app declares nothing.
        //  - `localization.locale` (ADR-0053) is the workspace's RUNTIME
        //    language — Setup, Localization, tenant-scoped — whose four
        //    options are exactly `AUTH_EMAIL_TEMPLATE_LOCALES`. It is
        //    already the authority for auth SMS (#2815) and for audit
        //    activity summaries (framework#3039).
        //
        // A workspace that declared Chinese therefore received Chinese SMS
        // and ENGLISH mail. The workspace setting now outranks the
        // build-time default, and only when it is EXPLICIT
        // (`source !== 'default'`) — the same precedence the `appName`
        // binding below uses, because `get` answers the manifest default
        // (`en-US`) for an untouched workspace and taking it unconditionally
        // would demote every deployment that declared `i18n.defaultLocale`.
        //
        // Both i18n hops are probed rather than assumed: `getService` THROWS
        // for an unregistered service (i18n is not a required dependency of
        // auth) and `getDefaultLocale` is OPTIONAL on the contract. Nothing
        // resolvable ⇒ nothing is named, which is precisely the pre-#8195
        // behaviour — `EmailService` resolves its documented `en-US` default.
        let i18nDefaultEmailLocale: string | undefined;
        try {
          const i18n = ctx.getService<II18nService>('i18n');
          const locale =
            typeof i18n?.getDefaultLocale === 'function' ? i18n.getDefaultLocale() : undefined;
          i18nDefaultEmailLocale = typeof locale === 'string' ? locale : undefined;
        } catch {
          // i18n service is optional — leave the build-time default unset.
        }
        const applyEmailLocale = (workspaceLocale: string | undefined): void => {
          this.authManager?.setDefaultEmailLocale(workspaceLocale ?? i18nDefaultEmailLocale);
        };
        // Baseline = the build-time default. Superseded below when a settings
        // service answers with an explicit workspace language, and left
        // standing when there is no settings service or its read fails.
        applyEmailLocale(undefined);
        if (typeof i18nDefaultEmailLocale === 'string' && i18nDefaultEmailLocale.trim()) {
          ctx.logger.info(
            `Auth: bound auth email locale to i18n default=${i18nDefaultEmailLocale}`,
          );
        }

        // Bind the email brand name (`{{appName}}`) to the live
        // `branding.workspace_name` setting so the admin UI can rename the
        // product without a redeploy. Only an *explicitly set* value
        // overrides the configured `appName` — when the operator hasn't
        // customised it (resolver returns the manifest default), we clear
        // the override so the deployment's `appName` (e.g. `OS_APP_NAME`)
        // keeps precedence. Mirrors EmailServicePlugin's settings binding.
        try {
          const settings = ctx.getService<SettingsReadSurface>('settings');
          if (settings && typeof settings.get === 'function') {
            const applyBrand = async () => {
              try {
                const resolved = await settings.get('branding', 'workspace_name', {});
                const explicit = resolved && resolved.source !== 'default'
                  ? resolved.value
                  : undefined;
                this.authManager?.setAppName(
                  typeof explicit === 'string' ? explicit : undefined,
                );
              } catch (err: any) {
                ctx.logger.warn(
                  'Auth: failed to apply branding.workspace_name: ' + (err?.message ?? err),
                );
              }
            };
            // [#24766] Bound only where the settings service LISTS the
            // `branding` namespace — the test the runtime-config door makes.
            // Under a walled tenancy posture service-settings withholds it
            // (`UNWALLED_ONLY_NAMESPACES`): there is no value to bind, and
            // the read would fail into the warn above on every correct walled
            // boot. The configured `appName` (e.g. `OS_APP_NAME`) stays in
            // force, which is all a walled read of organization-less rows
            // ever produced. A service with no listing is treated the same.
            let brandingOffered = false;
            try {
              const listManifests = (settings as {
                listManifests?: () => ReadonlyArray<{ namespace?: unknown } | undefined>;
              }).listManifests;
              brandingOffered = typeof listManifests === 'function'
                && listManifests.call(settings).some((m) => m?.namespace === 'branding');
            } catch (err: any) {
              // Kept local so the locale bindings below still run.
              ctx.logger.warn(
                'Auth: could not list settings namespaces, branding.workspace_name not bound: ' +
                  (err?.message ?? err),
              );
            }
            if (brandingOffered) {
              await applyBrand();
              if (typeof settings.subscribe === 'function') {
                settings.subscribe('branding', () => {
                  void applyBrand();
                });
                ctx.logger.info('Auth: bound appName to settings namespace=branding');
              }
            }

            // #2815 — bind the auth SMS locale to the deployment default
            // (`localization.locale`) so OTP/invitation texts render in the
            // workspace language. #14319 binds the auth EMAIL locale from
            // the very same read, so the two auth channels can no longer
            // disagree about what language this workspace speaks.
            // Live-rebinds on settings changes.
            const applyLocalizationLocale = async () => {
              try {
                const resolved = await settings.get('localization', 'locale', {});
                const value = resolved?.value;
                this.authManager?.setDefaultSmsLocale(
                  typeof value === 'string' ? value : undefined,
                );
                // Email takes the workspace language only when it was
                // EXPLICITLY set; a manifest default leaves the app's
                // build-time `i18n.defaultLocale` standing (block above).
                const explicit =
                  resolved && resolved.source !== 'default' && typeof value === 'string'
                    ? value
                    : undefined;
                applyEmailLocale(explicit);
                if (explicit) {
                  ctx.logger.info(
                    `Auth: bound auth email locale to localization.locale=${explicit}`,
                  );
                }
              } catch (err: any) {
                ctx.logger.warn(
                  'Auth: failed to apply localization.locale: ' + (err?.message ?? err),
                );
              }
            };
            await applyLocalizationLocale();
            if (typeof settings.subscribe === 'function') {
              settings.subscribe('localization', () => {
                void applyLocalizationLocale();
              });
            }
          }
        } catch {
          // settings service is optional — keep the configured appName.
        }

        // The built-in auth SMS texts are NOT seeded into
        // sys_notification_template: a rung with no row there renders the
        // built-in text itself (`resolvePhoneSmsTemplateBody`), and a row an
        // operator authored still wins (ADR-0131 — a row exists only when an
        // organization authored it).
      }
    });

    // Defer HTTP route registration to kernel:ready hook.
    // This ensures all plugins (including HonoServerPlugin) have completed
    // their init and start phases before we attempt to look up the
    // http-server service — making AuthPlugin resilient to plugin
    // loading order.
    if (this.options.registerRoutes) {
      ctx.hook('kernel:ready', async () => {
        let httpServer: IHttpServer | null = null;
        try {
          httpServer = ctx.getService<IHttpServer>('http-server');
        } catch {
          // Service not found — expected in MSW/mock mode
        }

        if (httpServer) {
          // Auto-detect the actual server URL when no explicit baseUrl was
          // configured, or when the configured baseUrl uses a different port
          // than the running server (e.g. port 3000 configured but 3002 bound).
          // getPort() is optional on IHttpServer; duck-type check for it.
          const serverWithPort = httpServer as IHttpServer & { getPort?: () => number };
          if (this.authManager && typeof serverWithPort.getPort === 'function') {
            const actualPort = serverWithPort.getPort();
            if (actualPort) {
              const configuredUrl = this.options.baseUrl || 'http://localhost:3000';
              const configuredOrigin = new URL(configuredUrl).origin;
              const actualUrl = `http://localhost:${actualPort}`;

              // Only auto-correct the port when the configured URL is already a
              // localhost URL (development mode). In production (Vercel/cloud) the
              // configured baseUrl is the real public hostname — never overwrite it
              // with a localhost URL, which would break OAuth callback URLs.
              const configuredIsLocalhost = configuredOrigin.startsWith('http://localhost');
              if (configuredIsLocalhost && configuredOrigin !== actualUrl) {
                this.authManager.setRuntimeBaseUrl(actualUrl);
                ctx.logger.info(
                  `Auth baseUrl auto-updated to ${actualUrl} (configured: ${configuredUrl})`,
                );
              }
            }
          }

          // Route registration errors should propagate (server misconfiguration)
          this.registerAuthRoutes(httpServer, ctx);
          ctx.logger.info(`Auth routes registered at ${this.options.basePath}`);
        } else {
          ctx.logger.warn(
            'No HTTP server available — auth routes not registered. ' +
            'Auth service is still available for MSW/mock environments via HttpDispatcher.'
          );
        }
      });
    }

    // [commit bf8d129b5] The walled deployment that declares an owner it can never
    // verify — maintainer ruling 2026-08-25 (option A): warn loudly, by name,
    // at boot; NEVER refuse. The whole decision (and why it must run here
    // rather than in `init()`, where no email transport is resolvable yet)
    // lives in `walled-owner-verification-path.ts`; this hook only supplies
    // the two live wiring facts. Registered independently of `registerRoutes`
    // so an embedding that serves no auth routes still gets the diagnosis.
    //
    // ⚠️ #11663's re-anchor legs (L2 #11970 / L4 #11974) will rewrite this
    // elevation surface: move THIS call, not the predicate — the message and
    // its controls travel with the module.
    ctx.hook('kernel:ready', async () => {
      let emailSvc: IEmailService | undefined;
      try { emailSvc = ctx.getService<IEmailService>('email'); } catch { emailSvc = undefined; }
      // The auth manager's own view: a host can hand a transport straight to
      // `AuthManager` without ever registering the kernel `email` service, and
      // the sibling hook below injects the service into it. Reading BOTH makes
      // this hook's answer independent of hook registration order.
      let pub: SignInPathConfigView | undefined;
      try { pub = this.authManager?.getPublicConfig(); } catch { pub = undefined; }
      const hasEmailTransport = !!emailSvc || !!this.authManager?.hasEmailTransport();
      const hasFederatedSignIn =
        (pub?.socialProviders?.length ?? 0) > 0 || pub?.features?.sso === true;
      // [#12751] The third wiring fact: what the store says about the declared
      // owner's account. Probed only when the answer can matter (walled +
      // owner declared + neither transport nor federated sign-in wired), so
      // every other boot pays nothing. This hook runs BEFORE the dev-seed
      // hook below (registration order), so the probe reads the pre-seed
      // store — the predicate's dev-seed clauses are written for exactly
      // that reading.
      let ql: IDataEngine | undefined;
      try { ql = ctx.getService<IDataEngine>('objectql'); } catch { ql = undefined; }

      // [#14353] "Can ANYONE sign in?" — asked UNCONDITIONALLY, because it is
      // independent of all four preconditions below: a deployment that is
      // unwalled, or declares no owner, or wires an email transport is just as
      // unrecoverable when it has human rows and no `sys_account` row. This is
      // the family's ONE store read: the human-population page is paged here
      // and the answer handed to the walled-owner probe, so no boot pages
      // `sys_user` twice. Cost on a fresh store is a single bounded page.
      const reachability = await probeSignInReachability(ql);
      // [#15074] …and the fact that decides whether "humans, zero accounts" is
      // a dead end AT ALL on this deployment: does it sign people in through an
      // identity provider, which needs no `sys_account` row of its own? On a
      // platform-SSO tenant kernel that population is the HEALTHY one, and the
      // report's "NOBODY CAN SIGN IN" was false on every boot. The resolver
      // pays for its bounded provider read only when the answer can change what
      // is reported; a deployment with no delegated path is untouched and still
      // reports at `error`.
      // [#20861] The plugin's own options ride along as the fourth fact: a
      // handoff route the HOST owns never appears in `pub`, so the host's
      // `hostSignInHandoff` declaration is the only place the gate can read it.
      const signInPath = await probeSignInPathWiring(reachability, pub, ql, this.options);
      const deadEnd = reportIfNoSignInAccountExists(reachability, ctx.logger, signInPath);

      let ownerAccountState: WalledOwnerAccountState = 'unknown';
      if (
        !hasEmailTransport &&
        !hasFederatedSignIn &&
        postureEnforcesWall(resolveTenancyPosture()) &&
        resolvePlatformOwnerEmail()
      ) {
        ownerAccountState = await probeWalledOwnerAccountState(ql, {
          humanUsers: reachability.humanUsers,
        });
      }
      // [#14353] ONE report per boot. A deployment can match both shapes at
      // once (no accounts AND a declared owner that cannot verify); the
      // no-sign-in error strictly subsumes the walled-owner warning there —
      // an owner who cannot reach platform-admin standing is moot when nobody
      // can sign in at all — so the warning is suppressed rather than stacked
      // on top of it. When the error did not fire, the warning is untouched.
      if (!deadEnd) {
        warnIfWalledOwnerCannotVerify(
          { hasEmailTransport, hasFederatedSignIn, ownerAccountState },
          ctx.logger,
        );
      }
    });

    // Dev-only: provision a known, loginable platform admin on an empty DB.
    // Registered as its own kernel:ready hook (independent of registerRoutes)
    // so it runs whenever the runtime boots in development.
    ctx.hook('kernel:ready', async () => {
      await this.maybeSeedDevAdmin(ctx);
    });

    // [#8317] The one-off half of the ruling: rows written BEFORE the
    // canonicalisation hook above — or written outside ObjectQL entirely by an
    // operator SQL fix-up, an import or a SCIM group remap — still carry a
    // non-canonical `sys_member.role`, and each one is a live authorization
    // inversion (owner to us, plain member to better-auth). The pass is
    // convergent, idempotent and reports a census of every distinct spelling it
    // found, so a database already canonical costs one query.
    ctx.hook('kernel:ready', async () => {
      try {
        const ql = ctx.getService<IDataEngine>('objectql');
        if (!ql) return;
        const { canonicalizeStoredMemberRoles } = await import('./member-role-canonical.js');
        await canonicalizeStoredMemberRoles(ql, { logger: ctx.logger });
      } catch (e) {
        ctx.logger.warn?.('[auth] sys_member.role canonicalisation pass failed', {
          error: (e as Error).message,
        });
      }
    });

    // The single-org default-organization bootstrap (pre-repo decision; label
    // collision documented under ADR-0093 D9). Every WALLED
    // posture (`group` and `isolated`) keeps its existing owner: the enterprise
    // organizations package, which runs the same idempotent helper with the
    // seed-ownership step injected. One crisp owner per posture, and the open
    // package never bootstraps an organization for a deployment whose
    // multi-organization runtime it does not provide.
    // The one-time ADR-0093 D6 backfill (below) is handed to the bootstrap so
    // the moment the default organization first EXISTS is a moment it runs:
    // until then the pass has no target and records nothing, and deferring it
    // to the next boot would let it judge users created during this uptime,
    // whose membership was already decided at their creation.
    let runBackfillOnDefaultOrg: ((source: string) => Promise<void>) | undefined;
    if (this.options.autoDefaultOrganization !== false && !postureEnforcesWall(resolveTenancyPosture())) {
      // ADR-0093 D7 — the platform admin's owner bind is decided ONCE
      // (`default-org-bootstrap-once.ts`, the gate the walled wiring in
      // `@objectstack/organizations` calls too): recorded in the
      // `sys_migration` ledger and latched in-process, after which this hook
      // still recreates a missing default organization but binds nobody.
      const ensureOnce = createEnsureDefaultOrganizationOnce({
        logger: ctx.logger,
        // [ADR-0131 D3] The organization `start()` created is this install's
        // fresh one; a ledger-less kernel may bind its owner (see the option).
        organizationCreatedByThisProcess: () => this.defaultOrganizationCreatedAtBoot,
      });
      const runEnsure = async () => {
        try {
          const ql = ctx.getService<IDataEngine>('objectql');
          if (!ql) return;
          const res = await ensureOnce(ql);
          if (res.defaultOrgCreated) {
            ctx.logger.info(
              `[auth] created Default Organization ${res.defaultOrgId} for the platform admin (single-org)`,
            );
            // Not awaited: this can run inside the `sys_user` insert that
            // created the platform admin, and the pass is serialized on its
            // own chain, which never rejects.
            void runBackfillOnDefaultOrg?.('default-org-created');
          }
        } catch (e) {
          ctx.logger.warn?.('[auth] ensureDefaultOrganization failed', {
            error: (e as Error).message,
          });
        }
      };
      ctx.hook('kernel:ready', runEnsure);
      // [#11973 / #11663 L3] Re-run after every write that can move the
      // population answer, judged by the ONE exported trigger predicate: a
      // `sys_user` insert or email/email_verified update (commit c0714eb5d's trigger
      // set — how a CONFIG-anchored admin comes into standing), and the
      // legacy `sys_user_permission_set` insert (how `single`-posture
      // first-user promotion lands standing, Choice 4A — retired with the
      // legacy-grant removal leg). The organizations package's walled
      // wiring should consume the same predicate.
      try {
        const ql = ctx.getService<IObjectQLEngine>('objectql');
        if (ql && typeof ql.registerMiddleware === 'function') {
          ql.registerMiddleware(async (opCtx: any, next: () => Promise<void>) => {
            await next();
            if (isDefaultOrganizationBootstrapTrigger(opCtx)) {
              await runEnsure();
            }
          });
        }
      } catch {
        /* objectql optional in mock mode — the kernel:ready pass still runs */
      }
    }

    // ADR-0093 D6 — backfill memberships for pre-existing member-less users
    // (historical create-user / import rows from before the reconciler existed),
    // ONCE per deployment (`membership-backfill-ledger.ts`, ADR-0093 D7).
    // Registered AFTER the default-org bootstrap hook so a target org exists by
    // the time it runs. `backfillMemberships` self-guards: it no-ops under
    // `invite-only` policy and in multi-org (tenancy.defaultOrgId() → null),
    // where a wrong org guess would be a data-exposure bug, not a convenience.
    // Opt out entirely via OS_SKIP_MEMBERSHIP_BACKFILL=1 (operators who curate
    // memberships by hand).
    if (String(process.env.OS_SKIP_MEMBERSHIP_BACKFILL ?? '').trim() !== '1') {
      // Serialize runs so overlapping triggers (kernel:ready + one or more
      // `app:seeded` from multiple app bundles) don't race the same scan and
      // trip the (organization_id, user_id) unique index into warn noise.
      let backfillChain: Promise<void> = Promise.resolve();
      // Latched once the one-time pass has decided in this process — read
      // from the ledger, or carried out now. A record that failed to land
      // ('ran-unrecorded') does not unlatch it: a second trigger in this
      // process must not run the pass again (ADR-0093 D7).
      let backfillDecided = false;
      // [#22257] Armed by this pass's own `kernel:ready` hook below; every
      // trigger before it is a no-op. The pass's policy is a SETTING, and the
      // settings data engine binds in `SettingsServicePlugin`'s `kernel:ready`
      // hook. The `optionalDependencies` edge orders that hook ahead of this
      // plugin's hooks, and orders nothing else: an event fired during Phase 2
      // reaches this pass before the bind. `app:seeded` is one —
      // `AppPlugin.start()` emits it when its inline seed lands, after this
      // plugin started — and on a seeded boot it bound the `auth` namespace
      // from the manifest defaults (the `Pre-bind READ` warning), so the
      // one-time pass could decide under a policy the deployment never chose.
      // A pre-ready trigger loses nothing: the `kernel:ready` pass is still
      // ahead, and it scans every row such a trigger was about.
      let backfillArmed = false;
      const runBackfill = (source: string): Promise<void> => {
        if (!backfillArmed) return backfillChain;
        backfillChain = backfillChain.then(async () => {
          if (backfillDecided) return;
          try {
            // #5152 — the policy this pass runs under is a SETTING, so bind the
            // namespace before reading it. The composition `kernel:ready` hook
            // registered earlier in `start()` has normally bound it by the time
            // the pass is armed; awaiting it here keeps the policy independent
            // of hook order. Idempotent and shared with that hook.
            await this.ensureAuthSettingsBound(ctx);
            const ql = ctx.getService<IDataEngine>('objectql');
            const tenancy = this.tenancy;
            // #5152 — the policy is read off the AuthManager, the same object
            // the sign-up reconciler reads and the same one `applyConfigPatch`
            // targets. It used to be `this.options.membershipPolicy`, a
            // constructor option that no settings change can reach: an admin
            // switching to `invite-only` stopped sign-up auto-binds while this
            // pass kept bulk-binding every member-less user. No `??` fallback
            // to the options here on purpose — a second reading of the policy
            // is exactly the defect. The manager exists from `init()`, so the
            // guard is a precondition, not a degraded mode.
            const manager = this.authManager;
            if (!ql || !tenancy || !manager) return;
            // ADR-0093 D7 — membership is decided at creation, so this pass is
            // ONE-TIME per deployment: it runs until it reaches a verdict, the
            // verdict is recorded in the `sys_migration` ledger, and every later
            // trigger reads the record and binds nobody.
            const outcome = await runOneTimeMembershipBackfill(
              ql,
              {
                policy: manager.getMembershipPolicy(),
                resolveTargetOrg: () => tenancy.defaultOrgId(),
                logger: ctx.logger,
              },
              ctx.logger,
            );
            if (outcome.status === 'ran' || outcome.status === 'ran-unrecorded' || outcome.status === 'already-run') {
              backfillDecided = true;
            }
            const res = outcome.backfill;
            if (res && res.bound > 0) {
              ctx.logger.info(
                `[auth] membership backfill (${source}) bound ${res.bound} member-less user(s) to the default organization (ADR-0093 D6)`,
                res,
              );
            }
          } catch (e) {
            ctx.logger.warn?.('[auth] membership backfill failed', {
              source,
              error: (e as Error).message,
            });
          }
        });
        return backfillChain;
      };
      runBackfillOnDefaultOrg = runBackfill;
      ctx.hook('kernel:ready', () => {
        backfillArmed = true;
        // #2996: app seeds insert `sys_user` via raw engine.insert, bypassing
        // better-auth's `user.create.after` reconciler. A seed that overruns
        // OS_INLINE_SEED_BUDGET_MS finishes in the background AFTER kernel:ready,
        // so its users would miss a kernel:ready pass that had no target yet.
        // The trigger stays; the ledger makes it a no-op once the one-time pass
        // has been recorded. An in-budget seed settles during Phase 2, before the
        // pass is armed, and the `kernel:ready` pass covers its rows.
        //
        // [#22257] Registered HERE, in the same synchronous step that arms the
        // pass, never from `start()`: a handler that does not exist before the
        // bind cannot run before it. Every `app:seeded` that fires before this
        // point was already a no-op through `backfillArmed`, and every one after
        // it reaches this handler — the kernel's hook map is read at dispatch
        // time, so an emit still in flight picks it up too. The structure is
        // what `check:settings-bind-window` can see; a flag is not.
        // `backfillArmed` stays: the `default-org-created` trigger
        // (`runBackfillOnDefaultOrg`) can still reach `runBackfill` from the
        // `objectql` middleware during Phase 2 and from the bootstrap's own
        // `kernel:ready` hook, which runs before this one.
        ctx.hook('app:seeded', () => runBackfill('app:seeded'));
        return runBackfill('kernel:ready');
      });
    }

    // Identity-source provenance for accounts created OUTSIDE better-auth's
    // `databaseHooks` — @better-auth/scim creates `sys_account` at the adapter
    // level, which BYPASSES `account.create.after` / `stampIdentitySource`. This
    // ObjectQL `afterInsert` hook stamps `source=idp_provisioned` regardless of
    // the creation path, so SCIM-provisioned users are correctly marked as the
    // managed mirror (cloud ADR-0024 D4 / cloud ADR-0071 verification #1). It mirrors the
    // federated branch of `stampIdentitySource`, is idempotent, and never breaks
    // the insert. Complementary to (not a replacement for) the OAuth-path stamp.
    ctx.hook('kernel:ready', async () => {
      try {
        // Use the kernel's ObjectQL engine (available + hookable at kernel:ready);
        // the auth manager's getDataEngine() is not yet wired this early.
        const engine = ctx.getService<IObjectQLEngine>('objectql');
        if (!engine || typeof engine.registerHook !== 'function') return;
        const SYSTEM_CTX = { isSystem: true, roles: [], permissions: [] };
        engine.registerHook('afterInsert', async (hookCtx: any) => {
          try {
            if (hookCtx?.object !== 'sys_account') return;
            const acct: any = hookCtx.result ?? {};
            const providerId = acct.provider_id ?? acct.providerId;
            const userId = acct.user_id ?? acct.userId;
            // Only federated/SCIM accounts mark the user managed; a local
            // password (`credential`) keeps the user env-native.
            if (!userId || !providerId || providerId === 'credential') return;
            // QueryAST options use `where` (not `filter`); a wrong key is silently
            // ignored and counts every row — the bug that shipped env_native.
            const credCount = await engine.count('sys_account', {
              where: { user_id: userId, provider_id: 'credential' }, context: SYSTEM_CTX,
            });
            if (typeof credCount === 'number' && credCount > 0) return;
            const u = await engine.findOne('sys_user', {
              where: { id: userId }, fields: ['id', 'source'], context: SYSTEM_CTX,
            });
            if (u && u.source !== 'idp_provisioned') {
              await engine.update('sys_user', { id: userId, source: 'idp_provisioned' }, { context: SYSTEM_CTX });
            }
          } catch (e) {
            // Provenance must never break account creation — the sys_account
            // insert still stands. [#12981] It must not be SILENT either: this
            // hook is the only stamp on the SCIM path, so nothing re-runs it.
            ctx.logger.error(
              '[auth] the SCIM identity-source stamp was NOT written — the sys_account row was '
                + 'created and provisioning reports success, so nothing looks wrong. The user '
                + 'keeps their previous `source`, so a SCIM-provisioned identity still reading '
                + '`env_native` is offered the password / identity-edit actions that are supposed '
                + 'to hide for a managed identity (cloud ADR-0024 D4) — the path by which a '
                + 'managed user self-mints a local password that bypasses enforced SSO. '
                + 'better-auth\'s `account.create.after` is bypassed by adapter-level creates, so '
                + 'this hook is the ONLY stamp on that path and nothing retries it: the row stays '
                + 'mis-stamped until the user is re-provisioned. Remedy: make the sys_user update '
                + 'land (write permission on `source`, driver connectivity), then re-run the SCIM '
                + 'sync for this user.',
              e instanceof Error ? e : undefined,
              { object: 'sys_user', field: 'source' },
            );
          }
        }, { packageId: 'com.objectstack.plugin-auth' });
        ctx.logger.info('Identity-source afterInsert stamp registered on sys_account (SCIM-safe)');
      } catch (e) {
        // [#12981] Was: "Engine not available — skip". That is one of the two
        // things this catch actually sees, and the quiet one; `registerHook`
        // refusing is the other, and it silently un-arms the SCIM stamp for the
        // whole process while the boot goes on looking healthy.
        ctx.logger.error(
          '[auth] the SCIM identity-source stamp was NOT registered — boot continues and every '
            + 'other auth surface works, so nothing looks wrong. For the rest of this process no '
            + 'adapter-level `sys_account` insert stamps `source=idp_provisioned`, so every '
            + 'SCIM-provisioned user is left reading `env_native` and is offered the password / '
            + 'identity-edit actions that are supposed to hide for a managed identity (cloud '
            + 'ADR-0135 D4). The OAuth path still stamps via better-auth databaseHooks, which is '
            + 'why this is invisible on a deployment that also uses OAuth. This line is the only '
            + 'notice; it is registered once per boot and does NOT retry. Remedy: check that the '
            + '`objectql` service is registered by kernel:ready and that registerHook is '
            + 'available, then restart.',
          e instanceof Error ? e : undefined,
          { hook: 'afterInsert', object: 'sys_account' },
        );
      }
    });

    // ADR-0092 D2/D6 — generic identity write guard. Every object whose
    // schema declares `managedBy: 'better-auth'` gets fail-closed protection
    // against USER-CONTEXT writes through the generic data path; the only
    // opening is the per-object update whitelist (sys_user → profile fields).
    // Internal writes (better-auth adapter, isSystem plugin/system contexts)
    // bypass — see identity-write-guard.ts for the full contract.
    ctx.hook('kernel:ready', async () => {
      try {
        const engine = ctx.getService<IObjectQLEngine>('objectql');
        if (!engine || typeof engine.registerHook !== 'function') return;
        registerManagedUpdateWhitelist(SystemObjectName.USER, SYS_USER_PROFILE_EDIT_FIELDS);
        // [ADR-0105 D7] Extension fields ObjectStack adds to better-auth-managed
        // tables ride the SAME whitelist — no second mechanism. better-auth
        // neither reads nor writes them, so they are editable through the
        // ordinary path under normal FLS / requiredPermissions; its own protocol
        // fields stay rejected. `managed-extension-fields.test.ts` proves the two
        // populations are disjoint at the pinned better-auth version.
        for (const [object, fields] of Object.entries(MANAGED_EXTENSION_EDITABLE_FIELDS)) {
          // `sys_user` is registered ABOVE, from the tiered constant, and is
          // skipped here rather than merged: this map has one tier and that
          // table has two (form vs. admin bulk import). Its entry there is a
          // declaration that must stay a SUBSET of what was registered above —
          // pinned in `managed-extension-fields.test.ts`, because a name that
          // reaches this map but never the whitelist is a write the platform
          // advertises and the guard refuses (ADR-0049).
          if (object === SystemObjectName.USER) continue;
          registerManagedUpdateWhitelist(object, fields);
        }
        // [#8317] Canonicalise `sys_member.role` on every ObjectQL write, at
        // priority 5 — AHEAD of both guards below. better-auth reads that
        // column with a raw `split(',')` (no trim, no lower-case), so a stored
        // `Owner` / `' owner'` is an owner to our grade ladder and a plain
        // member to the vendor, and its "only an owner may remove an owner"
        // branch never fires: an org admin could remove an owner. Normalising
        // at the write makes that disagreement unrepresentable instead of
        // adjudicated per-reader (maintainer ruling 2026-08-13, option A), and
        // it runs first so both guards judge the value's normal form.
        registerMemberRoleCanonicalization(engine, {
          packageId: 'com.objectstack.plugin-auth.member-role-canonical',
          logger: ctx.logger,
        });
        // [Ruling 6355206139 E5/E6] The `external` role is held alone, and its
        // holder is never placed in the organization's business units — at
        // priority 6, judging the canonical spelling the hook above wrote.
        registerExternalMembershipGuard(engine, {
          packageId: 'com.objectstack.plugin-auth.external-membership',
        });
        registerIdentityWriteGuard(engine, {
          packageId: 'com.objectstack.plugin-auth.identity-write-guard',
          logger: ctx.logger,
          getSecondaryStorage: () =>
            this.effectiveSecondaryStorage as SecondaryStorageLike | undefined,
        });
        // A key an administrator's forced password reset revoked is restored
        // by a platform administrator only, and `revoked_reason` is kept in
        // step with `revoked` in that one hook. It runs AFTER the D2 guard
        // above, which would otherwise strip the reason it clears. See
        // api-key-restore-guard.ts.
        registerApiKeyRestoreGuard(engine, {
          packageId: 'com.objectstack.plugin-auth.api-key-restore-guard',
          logger: ctx.logger,
        });
        // [cloud ADR-0024 D5.2] Break-glass — the same identity write
        // chokepoints, guarding a different question: not "may this caller
        // write identity tables" (above, and system writes bypass it by
        // design) but "may this WRITE happen at all". A `banned = true` (#5892)
        // or a row DELETE (#5941) on `sys_user`, and — since #5978 — any write
        // to `sys_member` / `sys_user_permission_set` that revokes the last
        // administrator's STANDING while leaving their user row untouched, is
        // refused for EVERY context, `isSystem` included: the paths that
        // actually lock an org out are the system ones (better-auth's admin
        // ban, remove-user and updateMemberRole, driven by a SCIM
        // `active: false` / `DELETE /Users/{id}` / group remap). Since #6084 it
        // also covers switching `admin_full_access` off — in the activation
        // ledger since ADR-0131 D3 — which un-makes every grant-anchored
        // platform admin at once, and the zero-admin bootstrap exemption would
        // then switch the guard off for all of the above. Every hook registers
        // at priority 20 so the ADR-0092 checks above (10) still answer first
        // for user-context callers. See last-admin-guard.ts.
        const lastAdminGuard = registerLastAdminGuard(engine, {
          packageId: 'com.objectstack.plugin-auth.last-admin-guard',
          logger: ctx.logger,
        });
        // [#24948] The same question, asked before an organization delete's
        // first write (`AuthManager.assertOrganizationDeletable`).
        this.authManager?.setOrganizationDeleteStandingJudge(lastAdminGuard.judgeOrganizationDelete);
        // [#15784] The COURTESY half of #15409's ruling: when a membership
        // ends, the session's claim on THAT organization ends with it —
        // re-pointed if the user still belongs somewhere, revoked if not.
        // Registered on `sys_member` for the same reason the guard above is:
        // the census (posted on #15784) measured that better-auth's
        // remove-member endpoint, a direct delete, a bulk delete, the cascade
        // from a sys_user delete and an organization re-point ALL reach this
        // seam, while an endpoint hook would have reached one of them.
        // ⛔ This is never the enforcement — see the module header, and
        // `resolve-authz-context.ts`, which stays untouched.
        registerMembershipEndedSessionTrigger(engine, {
          packageId: 'com.objectstack.plugin-auth.membership-ended-session',
          logger: ctx.logger,
        });
      } catch {
        // Engine not available (mock mode) — permission-set defaults remain
        // the only gate, exactly the pre-guard status quo.
      }
    });

    // Register auth middleware on ObjectQL engine (if available)
    try {
      const ql = ctx.getService<IObjectQLEngine>('objectql');
      if (ql && typeof ql.registerMiddleware === 'function') {
        ql.registerMiddleware(async (opCtx: any, next: () => Promise<void>) => {
          // If context already has userId or isSystem, skip auth resolution
          if (opCtx.context?.userId || opCtx.context?.isSystem) {
            return next();
          }
          // Future: resolve session from AsyncLocalStorage or request context
          await next();
        });
        ctx.logger.info('Auth middleware registered on ObjectQL engine');
      }
    } catch (_e) {
      ctx.logger.debug('ObjectQL engine not available, skipping auth middleware registration');
    }

    ctx.logger.info('Auth Plugin started successfully');
  }

  /**
   * Bind the auth settings namespace once, whoever asks first.
   *
   * Two `kernel:ready` hooks need the settings applied, and they fire in
   * REGISTRATION order, which is the opposite of the order they need
   * (#5152): the ADR-0093 D6 membership backfill is registered in `init()`,
   * the settings binding in `start()`. Left alone, the very first backfill of
   * a fresh boot would read the pre-settings policy and bulk-bind every
   * pre-existing member-less user on a deployment whose stored setting says
   * `invite-only` — the exact failure the setting exists to prevent, on the
   * one pass nobody gets to observe before it has happened.
   *
   * So neither hook owns the binding: both await this, the first one through
   * performs it, and the memoized promise keeps `settings.subscribe` from
   * being registered twice.
   */
  private ensureAuthSettingsBound(ctx: PluginContext): Promise<void> {
    this.authSettingsBinding ??= this.bindAuthSettings(ctx);
    return this.authSettingsBinding;
  }

  /**
   * [#23367, ruling A] Record the API-key lifecycle policy's landing — the
   * anchor of the inactivity clock for keys with no recorded use, and of the
   * one-year grace for keys signed with no expiry — when no value is stored
   * yet. One place: the `auth` setting `api_key_policy_started_at`, which
   * `bindAuthSettings` binds into the manager (the write's change event
   * re-runs that pass, so the anchor is live as soon as it lands).
   *
   * ⛔ Never overwrites a stored value: the anchor is written once, by the
   * first boot that runs the policy, and only an operator moves it.
   *
   * A deployment with no settings service has nowhere to keep the anchor, so
   * the policy runs without one: keys signed with no expiry get no grace date
   * and keys with no recorded use are not judged idle until they record one.
   * Functional, and said once at `warn`. A write that FAILS is the durability
   * half — the deployment believes the policy is armed while the anchor never
   * landed — so it is said at `error`, with the remedy.
   */
  private async recordApiKeyPolicyStart(ctx: PluginContext): Promise<void> {
    if (!this.authManager) return;
    let settings: SettingsReadSurface | undefined;
    try {
      settings = ctx.getService<SettingsReadSurface>('settings');
    } catch {
      settings = undefined;
    }
    if (!settings || typeof settings.get !== 'function' || typeof settings.set !== 'function') {
      ctx.logger.warn(
        '[auth] API-key lifecycle policy: no settings service, so the date the policy took effect cannot be '
          + 'recorded. Keys created with no expiry get no one-year grace date, and keys with no recorded use are '
          + 'not judged inactive until they record one. Register the settings service to record it.',
      );
      return;
    }
    try {
      await this.ensureAuthSettingsBound(ctx);
      const stored = await settings.get('auth', API_KEY_POLICY_STARTED_AT_KEY, {});
      const explicit = stored && (stored.source ?? 'default') !== 'default';
      if (explicit && typeof stored?.value === 'string' && stored.value.trim()) return;
      await settings.set('auth', API_KEY_POLICY_STARTED_AT_KEY, new Date().toISOString(), {});
    } catch (err: any) {
      ctx.logger.error(
        '[auth] API-key lifecycle policy: the date the policy took effect was NOT recorded '
          + `(auth.${API_KEY_POLICY_STARTED_AT_KEY}: ${String(err?.message ?? err)}). Keys created with no expiry `
          + 'stay without their one-year grace date, and keys with no recorded use are not judged inactive, while '
          + 'the rest of the policy runs as configured. Fix: restore the settings store and restart, or set '
          + `auth.${API_KEY_POLICY_STARTED_AT_KEY} (UTC, ISO 8601) in the settings console.`,
      );
    }
  }

  /**
   * Bind the small open-source auth settings namespace to better-auth config.
   *
   * Only explicit settings values (stored or OS_AUTH_* env overrides) affect
   * runtime config. Manifest defaults are UI defaults and do not mask code or
   * deployment configuration.
   *
   * Call through {@link ensureAuthSettingsBound}, never directly.
   */
  private async bindAuthSettings(ctx: PluginContext): Promise<void> {
    if (!this.authManager) return;

    let settings: SettingsReadSurface | undefined;
    try {
      settings = ctx.getService<SettingsReadSurface>('settings');
    } catch {
      return;
    }
    if (!settings || typeof settings.getNamespace !== 'function') return;

    const applySettings = async (): Promise<void> => {
      if (!this.authManager) return;
      const authManager = this.authManager;
      try {
        const payload = await settings.getNamespace('auth');
        const values: Record<string, unknown> = {};
        const sources: Record<string, string | undefined> = {};
        for (const [key, entry] of Object.entries(payload.values as Record<string, any>)) {
          values[key] = entry?.value;
          sources[key] = entry?.source;
        }

        const isExplicit = (key: string) => (sources[key] ?? 'default') !== 'default';
        const asBoolean = (value: unknown, fallback: boolean): boolean => {
          if (typeof value === 'boolean') return value;
          if (typeof value === 'string') return value.toLowerCase() !== 'false';
          if (typeof value === 'number') return value !== 0;
          return fallback;
        };
        const asTrimmedString = (value: unknown): string | undefined => {
          if (typeof value !== 'string') return undefined;
          const trimmed = value.trim();
          return trimmed ? trimmed : undefined;
        };
        const asPositiveInt = (value: unknown): number | undefined => {
          const n = Math.floor(Number(value));
          return Number.isFinite(n) && n > 0 ? n : undefined;
        };

        // [#20412] The pass is applied in pieces, split along the lines where
        // the manager can REFUSE. `applyConfigPatch` validates a patch on entry
        // wherever it carries a block the manager judges: `emailAndPassword`
        // (`assertAudienceConfig`, against the standing audience posture) and
        // `plugins` (`assertScimAdminCoherence`). A key that lands in one of
        // those blocks is applied ALONE (`refusable`), so a refusal names that
        // key and takes nothing else with it; every other key rides `patch`,
        // one application the manager does not validate. When the whole pass
        // went out as one patch, one refused key dropped password policy, MFA,
        // rate limits, session lifetime and social providers with it, while
        // the settings console showed all of them as saved.
        //
        // The plugin decides nothing here: the manager's own verdict on each
        // piece is the verdict, and the piece carries the settings key its
        // refusal is reported under.
        const patch: Partial<AuthManagerOptions> = {};
        type ApplyOptions = Parameters<AuthManager['applyConfigPatch']>[1];
        const refusable: Array<{
          key: string;
          patch: Partial<AuthManagerOptions>;
          options?: ApplyOptions;
        }> = [];
        const emailAndPasswordField = (
          key: string,
          fields: Partial<NonNullable<AuthConfig['emailAndPassword']>>,
          options?: ApplyOptions,
        ): void => {
          refusable.push({
            key,
            patch: { emailAndPassword: fields as AuthManagerOptions['emailAndPassword'] },
            options,
          });
        };
        if (isExplicit('email_password_enabled')) {
          emailAndPasswordField('email_password_enabled', {
            enabled: asBoolean(values.email_password_enabled, true),
          });
        }
        if (isExplicit('signup_enabled')) {
          emailAndPasswordField('signup_enabled', {
            disableSignUp: !asBoolean(values.signup_enabled, true),
          });
        }
        if (isExplicit('require_email_verification')) {
          emailAndPasswordField(
            'require_email_verification',
            { requireEmailVerification: asBoolean(values.require_email_verification, false) },
            {
              // [#20389] An `OS_AUTH_REQUIRE_EMAIL_VERIFICATION` env override is
              // the DEPLOYMENT's declaration (the settings service reports it as
              // source `env`, locked); anything else explicit was stored through
              // the console. Under posture `open` only the former may turn
              // verification off — `assertAudienceConfig` owns that verdict.
              requireEmailVerificationFrom:
                sources.require_email_verification === 'env' ? 'deployment' : 'console',
            },
          );
        }

        // ADR-0093 D1 / #5152 — membership policy. `signup_enabled` says whether
        // people may self-register; this says what they join when they do, and
        // the two are halves of one platform posture, so it rides the same
        // settings seam. Only an EXPLICIT value applies: the manifest default
        // (`auto`) is a UI default and must not mask a deployment that set the
        // policy at construction.
        //
        // An unrecognised value is REJECTED, never coerced to `auto`. The
        // settings service enforces the option table on `setMany`, but an
        // `OS_AUTH_MEMBERSHIP_POLICY` env value bypasses that path entirely, and
        // silently reading a typo'd `invite_only` as `auto` would leave an
        // operator believing the wall is up while every sign-up is auto-bound —
        // invisible until someone finds a stranger in their org. `error`, not
        // `warn`: nothing looks broken afterwards.
        if (isExplicit('membership_policy')) {
          const raw = values.membership_policy;
          if (isMembershipPolicy(raw)) {
            patch.membershipPolicy = raw;
          } else {
            ctx.logger.error(
              `[auth] membership_policy '${String(raw)}' is not a valid policy — IGNORED, the deployment keeps its current policy ` +
                `('${this.authManager.getMembershipPolicy()}') and new sign-ups will continue to follow it. ` +
                `Set auth.membership_policy (or OS_AUTH_MEMBERSHIP_POLICY) to one of: ${MEMBERSHIP_POLICIES.join(', ')}.`,
            );
          }
        }
        // Password policy — better-auth enforces these bounds on sign-up and
        // password reset. Ignore malformed/non-positive values (keep the default).
        if (isExplicit('password_min_length')) {
          const n = asPositiveInt(values.password_min_length);
          if (n !== undefined) emailAndPasswordField('password_min_length', { minPasswordLength: n });
        }
        if (isExplicit('password_max_length')) {
          const n = asPositiveInt(values.password_max_length);
          if (n !== undefined) emailAndPasswordField('password_max_length', { maxPasswordLength: n });
        }

        // Breached-password rejection (ADR-0069 D1) — enables better-auth's
        // native `haveibeenpwned` plugin via the plugin-config gate. Default
        // off; only an explicit toggle applies (manifest defaults must not
        // mask the deployment env var). See buildPluginList() for the seam.
        if (isExplicit('password_reject_breached')) {
          refusable.push({
            key: 'password_reject_breached',
            patch: {
              plugins: {
                passwordRejectBreached: asBoolean(values.password_reject_breached, false),
              } as AuthManagerOptions['plugins'],
            },
          });
        }

        // Password complexity (ADR-0069 D1) — custom validator in the before
        // hook (better-auth only enforces length). Only explicit values apply.
        if (isExplicit('password_require_complexity')) {
          patch.passwordRequireComplexity = asBoolean(values.password_require_complexity, false);
        }
        if (isExplicit('password_min_classes')) {
          const n = asPositiveInt(values.password_min_classes);
          if (n !== undefined) patch.passwordMinClasses = Math.min(4, Math.max(1, n));
        }
        if (isExplicit('password_history_count')) {
          // 0 disables → use a non-negative reader (asPositiveInt rejects 0).
          const n = Math.floor(Number(values.password_history_count));
          if (Number.isFinite(n) && n >= 0) patch.passwordHistoryCount = Math.min(24, n);
        }
        if (isExplicit('password_expiry_days')) {
          // 0 disables expiry → non-negative reader.
          const n = Math.floor(Number(values.password_expiry_days));
          if (Number.isFinite(n) && n >= 0) patch.passwordExpiryDays = Math.min(3650, n);
        }

        // Enforced MFA (ADR-0069 D3). Enabling it also turns the twoFactor
        // plugin on so the /two-factor/* enrollment endpoints exist — otherwise
        // gated users would have no way to comply. [#20412] So the enforcement
        // and the plugin are ONE piece: a refused plugins block leaves MFA at
        // its standing value too, never enforced without its enrollment path.
        if (isExplicit('mfa_required')) {
          const on = asBoolean(values.mfa_required, false);
          if (on) {
            refusable.push({
              key: 'mfa_required',
              patch: { mfaRequired: true, plugins: { twoFactor: true } as AuthManagerOptions['plugins'] },
            });
          } else {
            patch.mfaRequired = false;
          }
        }
        if (isExplicit('mfa_grace_period_days')) {
          const n = Math.floor(Number(values.mfa_grace_period_days));
          if (Number.isFinite(n) && n >= 0) patch.mfaGracePeriodDays = Math.min(90, n);
        }

        // [#23367, ruling A] The API-key lifecycle policy. Only explicit values
        // apply, as for every key here: an unset key leaves the manager's own
        // default, which is the same number the manifest shows (90 / 365 / 90).
        // The inactivity window takes 0 (off), so it uses a non-negative reader.
        if (isExplicit('api_key_default_expiry_days')) {
          const n = asPositiveInt(values.api_key_default_expiry_days);
          if (n !== undefined) patch.apiKeyDefaultExpiryDays = Math.min(3650, n);
        }
        if (isExplicit('api_key_max_expiry_days')) {
          const n = asPositiveInt(values.api_key_max_expiry_days);
          if (n !== undefined) patch.apiKeyMaxExpiryDays = Math.min(3650, n);
        }
        if (isExplicit('api_key_inactivity_days')) {
          const n = Math.floor(Number(values.api_key_inactivity_days));
          if (Number.isFinite(n) && n >= 0) patch.apiKeyInactivityDays = Math.min(3650, n);
        }
        // The landing anchor, once recorded (`recordApiKeyPolicyStart` writes it
        // on the first boot that runs the policy). A value that does not parse
        // as an instant is ignored: the anchor keeps its standing value rather
        // than moving every legacy key's grace to a date nobody wrote.
        if (isExplicit(API_KEY_POLICY_STARTED_AT_KEY)) {
          const raw = asTrimmedString(values[API_KEY_POLICY_STARTED_AT_KEY]);
          const ms = raw ? Date.parse(raw) : Number.NaN;
          if (!Number.isNaN(ms)) patch.apiKeyPolicyStartedAt = new Date(ms).toISOString();
        }

        // Session lifetime — days → seconds for better-auth's `session`
        // (`expiresIn` = absolute lifetime; `updateAge` = refresh threshold).
        const session: { expiresIn?: number; updateAge?: number } = {};
        if (isExplicit('session_expiry_days')) {
          const d = asPositiveInt(values.session_expiry_days);
          if (d !== undefined) session.expiresIn = d * 86_400;
        }
        if (isExplicit('session_refresh_days')) {
          const d = asPositiveInt(values.session_refresh_days);
          if (d !== undefined) session.updateAge = d * 86_400;
        }
        if (Object.keys(session).length > 0) {
          patch.session = session as AuthManagerOptions['session'];
        }

        // Session controls (ADR-0069 D4) — idle / absolute / concurrent. 0 = off;
        // non-negative reader so an explicit 0 disables.
        const asNonNeg = (v: unknown): number | undefined => {
          const n = Math.floor(Number(v));
          return Number.isFinite(n) && n >= 0 ? n : undefined;
        };
        if (isExplicit('session_idle_timeout_minutes')) {
          const n = asNonNeg(values.session_idle_timeout_minutes);
          if (n !== undefined) patch.sessionIdleTimeoutMinutes = n;
        }
        if (isExplicit('session_absolute_max_hours')) {
          const n = asNonNeg(values.session_absolute_max_hours);
          if (n !== undefined) patch.sessionAbsoluteMaxHours = n;
        }
        if (isExplicit('max_concurrent_sessions_per_user')) {
          const n = asNonNeg(values.max_concurrent_sessions_per_user);
          if (n !== undefined) patch.maxConcurrentSessions = n;
        }

        // Network gating (ADR-0069 D5) — parse the CIDR/IP textarea into a list.
        if (isExplicit('allowed_ip_ranges')) {
          const raw = asTrimmedString(values.allowed_ip_ranges) ?? '';
          patch.allowedIpRanges = raw
            .split(/[\n,]+/)
            .map((r) => r.trim())
            .filter(Boolean);
        }

        // Anti-abuse (ADR-0069 D2) — account lockout (custom, per-identity)
        // and rate-limit tuning (better-auth-native, per-IP). `asPositiveInt`
        // rejects 0/malformed; lockout_threshold uses a non-negative reader so
        // an explicit 0 can turn the feature off.
        const asNonNegativeInt = (value: unknown): number | undefined => {
          const n = Math.floor(Number(value));
          return Number.isFinite(n) && n >= 0 ? n : undefined;
        };
        if (isExplicit('lockout_threshold')) {
          const n = asNonNegativeInt(values.lockout_threshold);
          if (n !== undefined) patch.lockoutThreshold = n;
        }
        if (isExplicit('lockout_duration_minutes')) {
          const n = asPositiveInt(values.lockout_duration_minutes);
          if (n !== undefined) patch.lockoutDurationMinutes = n;
        }
        if (isExplicit('rate_limit_max') || isExplicit('rate_limit_window_seconds')) {
          const max = asPositiveInt(values.rate_limit_max) ?? 10;
          const window = asPositiveInt(values.rate_limit_window_seconds) ?? 60;
          // Tighten the auth-mutating endpoints; better-auth keeps its own
          // defaults for everything else. customRules support `*` wildcards.
          patch.rateLimit = {
            enabled: true,
            window,
            max,
            customRules: {
              '/sign-in/email': { window, max },
              '/sign-up/email': { window, max },
              '/request-password-reset': { window, max },
              '/reset-password': { window, max },
              // #2780 — OTP endpoints cost an SMS per hit (pumping abuse);
              // the per-number cooldown (otp-send-guard.ts) is always on,
              // this adds the operator-tuned per-IP dimension. The plugin
              // also ships its own /phone-number* default (10/min).
              '/phone-number/send-otp': { window, max },
              '/phone-number/request-password-reset': { window, max },
              '/phone-number/verify': { window, max },
              '/phone-number/reset-password': { window, max },
            },
          } as AuthManagerOptions['rateLimit'];
        }

        if (
          isExplicit('google_enabled') ||
          isExplicit('google_client_id') ||
          isExplicit('google_client_secret')
        ) {
          const socialProviders = {
            ...(this.configuredSocialProviders ?? {}),
          } as NonNullable<SocialProviderConfig>;
          const env = (globalThis as any)?.process?.env as Record<string, string | undefined> | undefined;
          const googleEnabledFromEnv = env?.OS_AUTH_GOOGLE_ENABLED != null
            ? asBoolean(env.OS_AUTH_GOOGLE_ENABLED, true)
            : undefined;
          const googleClientId = asTrimmedString(values.google_client_id) ?? env?.GOOGLE_CLIENT_ID;
          const googleClientSecret = asTrimmedString(values.google_client_secret) ?? env?.GOOGLE_CLIENT_SECRET;
          if (googleEnabledFromEnv ?? (isExplicit('google_enabled') ? asBoolean(values.google_enabled, true) : true)) {
            if (!socialProviders.google && googleClientId && googleClientSecret) {
              socialProviders.google = {
                clientId: googleClientId,
                clientSecret: googleClientSecret,
                enabled: true,
              };
            }
          } else {
            delete socialProviders.google;
          }
          patch.socialProviders = Object.keys(socialProviders).length > 0
            ? socialProviders
            : undefined;
        }

        const audienceKeys = [
          'audience_posture',
          'audience_allowed_email_domains',
          'audience_self_registration_permission_set',
        ];

        // [#20412] Each piece is applied in its own `try`, so a refusal is
        // contained to the piece it names. `error`, not `warn` (AGENTS.md,
        // degradation log levels): the settings console shows the refused
        // value as saved while the runtime keeps the standing one, and nothing
        // else looks broken afterwards. The manager's message carries the
        // remedy, as in the audience block below.
        const applyPiece = (
          keys: readonly string[],
          piece: Partial<AuthManagerOptions>,
          options?: ApplyOptions,
        ): void => {
          try {
            authManager.applyConfigPatch(piece, options);
          } catch (refusal: any) {
            const named = keys.map((key) => `auth.${key}`).join(', ');
            ctx.logger.error(
              `[auth] auth settings REFUSED (${named}) — the standing runtime value keeps ruling while the settings ` +
                'console shows the stored value as saved; the other auth settings in this pass still apply. ' +
                String(refusal?.message ?? refusal),
            );
          }
        };
        if (Object.keys(patch).length > 0) {
          const pieceKeys = new Set(refusable.map((piece) => piece.key));
          applyPiece(
            Object.keys(values).filter(
              (key) => isExplicit(key) && !pieceKeys.has(key) && !audienceKeys.includes(key),
            ),
            patch,
          );
        }
        for (const piece of refusable) {
          applyPiece([piece.key], piece.patch, piece.options);
        }

        // [#11768] Audience posture (#11739) — the console switch for
        // `invite_only | email_domain | open`. The three `audience_*` keys are
        // ONE atomic declaration mapped to ONE `applyConfigPatch({ audience })`
        // (the #11767 contract: the patch replaces the WHOLE audience object
        // and validates the MERGED result), applied AFTER the pieces above so
        // that validation judges the audience against the `emailAndPassword`
        // state this same pass just applied — an explicit
        // `require_email_verification: false` beside `email_domain`, or beside
        // `open` when only the console stored it (#20389), is a contradiction
        // `assertAudienceConfig` refuses.
        //
        // #5152's rules, exactly as `membership_policy` above:
        //   - EXPLICIT-only. The manifest default (`invite_only`) is a UI
        //     default and must not mask a deployment that declared its
        //     audience in stack config at boot.
        //   - An off-vocabulary posture is REFUSED loudly, never coerced —
        //     a coerced value on this setting fails OPEN (an operator who
        //     typed `invite-only` believing the wall is up while sign-ups
        //     ride whatever posture the coercion picked).
        //
        // Composition rule: the declaration carries only the keys the
        // explicitly selected posture READS (the spec marks the siblings
        // "only read under" their postures). In particular, switching BACK to
        // `invite_only` sends `{ posture: 'invite_only' }` alone — leftover
        // text in the (hidden) domain-list field must never make CLOSING the
        // wall refusable, because that refusal would leave the previous, more
        // open posture ruling: the one direction that must not fail.
        // Missing required siblings are NOT guessed: the patch goes out
        // without them and `applyConfigPatch` refuses the merged result
        // (standing config keeps ruling — refusing to OPEN fails closed).
        if (audienceKeys.some((key) => isExplicit(key))) {
          const rawPosture = values.audience_posture;
          if (!isExplicit('audience_posture')) {
            ctx.logger.error(
              '[auth] audience settings IGNORED — a domain list or permission set is declared without a posture. ' +
                `The standing posture ('${this.authManager.getAudience().posture}') keeps ruling. ` +
                `Set auth.audience_posture (or OS_AUTH_AUDIENCE_POSTURE) to one of: ${AUDIENCE_POSTURES.join(', ')}.`,
            );
          } else if (!isAudiencePosture(rawPosture)) {
            ctx.logger.error(
              `[auth] audience_posture '${String(rawPosture)}' is not a recognized audience posture — IGNORED, the deployment keeps its ` +
                `current posture ('${this.authManager.getAudience().posture}') and self-registration continues to follow it. ` +
                `Set auth.audience_posture (or OS_AUTH_AUDIENCE_POSTURE) to one of: ${AUDIENCE_POSTURES.join(', ')}.`,
            );
          } else {
            const audience: AudienceConfig = { posture: rawPosture };
            if (rawPosture === 'email_domain' && isExplicit('audience_allowed_email_domains')) {
              const rawDomains = typeof values.audience_allowed_email_domains === 'string'
                ? values.audience_allowed_email_domains
                : '';
              // Same textarea convention as `allowed_ip_ranges`: newline- or
              // comma-separated. Entries are NOT filtered for shape here —
              // a malformed domain must be refused loudly by the validator,
              // never silently dropped from the allowlist it was typed into.
              audience.allowedEmailDomains = rawDomains
                .split(/[\n,]+/)
                .map((d) => d.trim())
                .filter(Boolean);
            }
            if (
              audiencePermitsSelfRegistration(rawPosture) &&
              isExplicit('audience_self_registration_permission_set')
            ) {
              const set = asTrimmedString(values.audience_self_registration_permission_set);
              if (set !== undefined) audience.selfRegistrationPermissionSet = set;
            }
            try {
              this.authManager.applyConfigPatch({ audience });
            } catch (audienceErr: any) {
              // The merged-result validation refused the declaration (empty
              // domain list, missing/forbidden permission set, verification
              // contradiction, …). The standing config keeps ruling — report
              // with the validator's own remedy-bearing message. `error`, not
              // `warn`, for the #5152 reason: the console shows the saved
              // values while the runtime refused them, so nothing else looks
              // broken afterwards.
              ctx.logger.error(
                `[auth] audience settings REFUSED — the standing posture ('${this.authManager.getAudience().posture}') keeps ruling. ` +
                  String(audienceErr?.message ?? audienceErr),
              );
            }
          }
        }
      } catch (err: any) {
        // [#20412] A refusal no longer reaches here — each piece above
        // contains its own. What does is a pass that failed as a whole, the
        // namespace read first among them: the stored auth settings it had not
        // applied keep their standing runtime values while the console shows
        // them as saved, so `error`, for the same reason as a refusal.
        ctx.logger.error(
          `[auth] auth settings NOT APPLIED — the auth settings pass failed (${String(err?.message ?? err)}), ` +
            'so the stored auth settings it had not yet applied keep their standing runtime values while the settings ' +
            'console shows them as saved. The pass re-runs on the next auth settings change: restore the settings ' +
            'store, then save any auth setting (or restart) to apply them.',
        );
      }
    };

    await applySettings();
    if (typeof settings.subscribe === 'function') {
      settings.subscribe('auth', () => {
        void applySettings();
      });
      ctx.logger.info('Auth: bound to settings namespace=auth');
    }
  }

  async destroy(): Promise<void> {
    // Cleanup if needed
    this.authManager = null;
  }

  /**
   * Dev-only admin bootstrap.
   *
   * On an EMPTY database (zero users), provision a well-known, loginable
   * admin (admin@objectos.ai / admin123 by default) so backend debugging
   * never blocks on a first-run sign-up wizard. The account is created
   * through better-auth's real server-side `signUpEmail` pipeline (hashed
   * credential + the same hooks the HTTP endpoint runs), so it is fully
   * loginable; plugin-security's first-user middleware then promotes it to
   * platform admin automatically.
   *
   * This replaces two earlier, divergent seeds:
   *   • the CLI-side HTTP seed (`os dev`), which POSTed the public sign-up
   *     endpoint from the parent process — racing server readiness and
   *     targeting a hard-coded port that broke under dev port auto-shift; and
   *   • plugin-dev's raw `sys_user` insert, which produced a credential-less,
   *     un-loginable row.
   * Running it in-process needs no port and no readiness polling.
   *
   * Idempotent and non-destructive: [#14157] it only ever acts on a database
   * with NO LOGIN — no account on the configured address, and no local
   * password login anywhere — and never touches an existing account, so a
   * custom password is never overwritten. The predicate used to be "no human
   * `sys_user` row", which is the same question only while every user row
   * carries a credential: an app declaring people in `defineStack({ data })`
   * made the database non-zero-user before this hook ran, and the admin was
   * never minted — on that boot or any later one. `dev-admin-seed-gate.ts`
   * owns the predicate and the argument.
   *
   * HARD-GATED to development (NODE_ENV==='development'): a known-credential
   * admin can never be provisioned in production. Opt out within dev via
   * OS_SEED_ADMIN=0 (or false/off/no).
   */
  private async maybeSeedDevAdmin(ctx: PluginContext): Promise<void> {
    // [commit bf8d129b5] Both clauses (and the seeded address below) are resolved by
    // `walled-owner-verification-path.ts`, because the boot check there treats
    // this seed as a verification path — it stamps the seeded account
    // `email_verified` (commit c0714eb5d). That is only true while the two agree on when
    // the seed is armed and which address it provisions, so they read one
    // resolution rather than two copies of the same env parsing.
    if (!isDevAdminSeedArmed()) return;

    const email = devSeedAdminEmail();
    const password = process.env.OS_SEED_ADMIN_PASSWORD?.trim() || 'admin123';
    const name = process.env.OS_SEED_ADMIN_NAME?.trim() || 'Dev Admin';

    let ql: IDataEngine | undefined;
    try { ql = ctx.getService<IDataEngine>('objectql'); } catch { /* unavailable */ }
    if (!ql || typeof ql.find !== 'function') return;

    try {
      // The human page is read for the REPORT path below, which looks the
      // seed account up among the existing users. [#11767] `isHumanUserRow`
      // is the shared population predicate; it is no longer the seed's GATE.
      const rows = await ql
        .find(SystemObjectName.USER, { where: {}, limit: 50 }, { context: { isSystem: true } })
        .catch(() => []);
      const humans = (Array.isArray(rows) ? rows : []).filter(isHumanUserRow);

      // [#14157] THE GATE: a LOGIN, not a directory row. See
      // `dev-admin-seed-gate.ts` for why the predicate moved off the user
      // table and why an unanswerable probe is its own verdict.
      const verdict = await decideDevAdminSeedGate(ql, email);
      if (!verdict.act) {
        if (verdict.reason === 'unanswerable') {
          // Functional degradation, and the operator has to be told: the DB
          // could not be read, so the seed declined rather than minting a
          // known-credential admin into an environment it cannot see. Nothing
          // claims to have been persisted, so `warn` is the level (AGENTS.md
          // → Degradation log levels).
          ctx.logger.warn(
            '[auth] dev admin seed skipped — the credential store could not be read, so whether a ' +
              'login already exists is unknown. No admin was provisioned; re-run once the data engine ' +
              `is reachable, or provision ${email} yourself.`,
          );
          return;
        }
        ctx.logger.debug(`[auth] dev admin seed skipped — ${verdict.reason}`);
        // `os dev` defaults to a persistent DB, so the seed fires exactly
        // once — but the startup banner and the Console login hint read
        // `devSeedResult`, which used to be set only on the seeding boot.
        // Re-arm it on every later dev boot for as long as the credentials
        // actually still work (account exists AND still carries the default
        // password), so returning users keep seeing how to sign in.
        await this.maybeReportExistingSeedAdmin(ctx, ql, humans, email, password);
        return;
      }

      if (!this.authManager) return;
      const api: any = await this.authManager.getApi();
      if (typeof api?.signUpEmail !== 'function') {
        ctx.logger.warn('[auth] dev admin seed skipped — signUpEmail unavailable');
        return;
      }

      // Real auth pipeline: creates sys_user + a hashed `credential` account
      // and runs the sign-up hooks.
      //
      // [#14157] Admission for THIS call is declared, not inferred. Both
      // gates on the way in — the audience posture and the `disableSignUp`
      // bypass — used to let the seed through only via the zero-human
      // bootstrap probe, which an app's own `defineStack({ data })` people
      // seed answers "populated" long before this hook runs: measured, the
      // seed's `signUpEmail` comes back `SELF_REGISTRATION_CLOSED` under the
      // default `invite_only` posture with 13 seeded people and zero
      // accounts. The ticket says what this creation IS (the deployment's own
      // boot command provisioning its admin — the operator class) for exactly
      // this address, and is cleared whatever happens.
      //
      // [#14373] The address alone is not the ticket — it is the documented
      // default and the boot banner prints it, so it does not narrow a
      // concurrent stranger's guess. `stageOperatorProvisioning` also returns
      // a random value that exists only in this process's memory; threading
      // it into THIS SAME call's body (under `AuthManager
      // .OPERATOR_PROVISIONING_TICKET_FIELD`) is what a stranger's own
      // concurrent sign-up for this address cannot replay, however it times
      // the window — see that method's doc for the full argument.
      const provisioningTicket = this.authManager.stageOperatorProvisioning(email);
      try {
        await api.signUpEmail({
          body: {
            email,
            password,
            name,
            [AuthManager.OPERATOR_PROVISIONING_TICKET_FIELD]: provisioningTicket,
          },
        });
      } finally {
        this.authManager.clearOperatorProvisioning(email);
      }
      // [commit c0714eb5d] Stamp the seeded admin's address VERIFIED. This account is
      // provisioned by the deployment's own boot command with operator-known
      // credentials — it is not an unknown self-registrant, which is the class
      // the verified-elevation invariant exists to refuse. Under walled
      // postures elevation now requires the declared owner's email match to be
      // VERIFIED, and in a dev/harness walled boot the declared owner is this
      // very account (the verify harness exports it as
      // OS_PLATFORM_OWNER_EMAIL) — without the stamp a walled dev boot would
      // seed an admin that can never be elevated, since no real mailbox exists
      // for the verification link. Same trust shape as a trusted-SSO insert
      // (`emailVerified: true` at creation). Dev-only by the NODE_ENV gate
      // above; real sign-ups never pass through here. `isSystem` exempts the
      // statically-readonly `email_verified` column, the same doorway the
      // better-auth adapter's own verification write uses.
      let seededId: string | undefined;
      try {
        const seededRows = await ql.find(
          SystemObjectName.USER,
          { where: { email }, limit: 1 },
          { context: { isSystem: true } },
        );
        seededId = (Array.isArray(seededRows) ? seededRows[0] : undefined)?.id;
        if (seededId) {
          await ql.update(
            SystemObjectName.USER,
            { id: seededId, email_verified: true },
            { context: { isSystem: true } },
          );
        } else {
          ctx.logger.warn('[auth] dev admin seeded but no row resolved for the email_verified stamp');
        }
      } catch (stampErr: any) {
        // Fail-open on the stamp, fail-closed on elevation: an unstamped admin
        // stays unverified and walled elevation refuses it loudly.
        ctx.logger.warn(`[auth] dev admin email_verified stamp failed: ${stampErr?.message ?? stampErr}`);
      }
      // [#23175] Complete the workspace this admin lands in with the host's
      // zone, as the console's own workspace-creation paths do with the
      // creator's — see the method. Only on the seeding boot: a later boot
      // takes the database as it finds it.
      if (seededId) await this.seedDevWorkspaceTimezone(ctx, ql, seededId);
      // [#25495] And with the host's currency, by the rule a new
      // organization's creator gets (`organization-default-currency.ts`).
      if (seededId) {
        let settings: CurrencySettingsDoor | undefined;
        try {
          settings = ctx.getService<CurrencySettingsDoor>('settings');
        } catch {
          settings = undefined;
        }
        await seedDevWorkspaceCurrency({ settings, ql, userId: seededId, logger: ctx.logger });
      }
      ctx.logger.info(`🔑 Dev admin seeded: ${email} / ${password}`);
      // Surface the credentials in the `serve` startup banner. The
      // ctx.logger line above is swallowed by serve's boot-quiet window
      // (the seed runs during runtime.start(), before stdout is restored),
      // so the CLI reads this off the `auth` service and prints it after
      // the banner instead.
      this.authManager.devSeedResult = { email, password };
    } catch (err: any) {
      // Best-effort. The common benign case is a race where a real sign-up
      // landed first (unique-email violation) — treat as "already seeded".
      ctx.logger.warn(`[auth] dev admin seed skipped: ${err?.message ?? err}`);
    }
  }

  /**
   * [#23175] Give the workspace the dev seed's admin lands in the HOST's time
   * zone, so a fresh `os dev` database opens on the shell and not on the
   * console's "Set the workspace timezone" dialog.
   *
   * The dialog asks an administrator once while the workspace's
   * `localization.timezone` still resolves from the manifest default — the
   * `source: 'default'` the console reads off `GET /api/settings/localization`
   * — and the console's own workspace-creation paths send the creator's
   * browser zone so a workspace they create is never asked about. This seed
   * mints its admin outside those paths, so it completes the workspace the
   * same way. The creator here is the machine running `os dev`, which is
   * where the browser opening the console usually runs too.
   *
   * - **The value** is the host's resolved zone,
   *   `Intl.DateTimeFormat().resolvedOptions().timeZone` (`TZ` included).
   *   `UTC` is written like any other answer: it IS the host's zone, and the
   *   console's creation path sends whatever the browser reports. A host that
   *   reports NO zone gets nothing written, so the dialog still asks — it is
   *   right whenever no zone is set.
   * - **The door** is the settings service's own write (`set`), the one the
   *   dialog's confirm reaches through `PUT /api/settings/localization`: one
   *   `tenant` row per organization, the key's `iana_time_zone` domain judged
   *   there, audited there. A zone the door refuses leaves the default, and
   *   the dialog asks. ⛔ Not `sys_organization.timezone`: that column is a
   *   different key, which the dialog does not read.
   * - **The workspace** is each organization the seeded admin is a member of,
   *   read from `sys_member` — the organization the admin's session opens in,
   *   without this method re-deciding which one that is. Under `single` (the
   *   posture `os dev` boots by default) that is the Default Organization the
   *   boot created, which the default-organization bootstrap binds the admin
   *   to during the sign-up above. An admin holding no membership yet gets
   *   nothing written.
   * - **Never over a set zone:** only where the key still resolves from the
   *   default. A value on any rung (this organization's, the global one, an
   *   env override) is left as it is.
   *
   * Best-effort, like the rest of the seed: the admin is seeded whether or not
   * this lands, and a miss costs the dialog, nothing else.
   */
  private async seedDevWorkspaceTimezone(
    ctx: PluginContext,
    ql: IDataEngine,
    userId: string,
  ): Promise<void> {
    let zone: string | undefined;
    try {
      const reported = Intl.DateTimeFormat().resolvedOptions().timeZone;
      zone = typeof reported === 'string' && reported.length > 0 ? reported : undefined;
    } catch {
      zone = undefined;
    }
    if (!zone) {
      ctx.logger.debug(
        '[auth] dev seed: this host reports no time zone, so the workspace keeps the default and the console asks for one',
      );
      return;
    }

    // Structural, as `SettingsReadSurface` above is: the slot carries no
    // `packages/spec` contract and plugin-auth does not depend on
    // service-settings. Absent, there is no store to write and no dialog to
    // spare (the dialog reads the same service).
    type SettingsWriteDoor = {
      get(
        namespace: string,
        key: string,
        ctx?: Record<string, unknown>,
      ): Promise<{ source?: string } | undefined>;
      set(namespace: string, key: string, value: unknown, ctx?: Record<string, unknown>): Promise<unknown>;
    };
    let settings: SettingsWriteDoor | undefined;
    try {
      settings = ctx.getService<SettingsWriteDoor>('settings');
    } catch {
      settings = undefined;
    }
    if (!settings || typeof settings.get !== 'function' || typeof settings.set !== 'function') return;

    let organizationIds: string[] = [];
    try {
      const memberships = await ql.find(
        SystemObjectName.MEMBER,
        { where: { user_id: userId }, limit: 50 },
        { context: { isSystem: true } },
      );
      organizationIds = [
        ...new Set(
          (Array.isArray(memberships) ? memberships : [])
            .map((m: any) => m?.organization_id)
            .filter((id: unknown): id is string => typeof id === 'string' && id !== ''),
        ),
      ];
    } catch (err: any) {
      ctx.logger.warn(
        `[auth] dev seed: the seeded admin's workspace could not be read (${err?.message ?? err}), so its ` +
          "time zone was not set to this host's zone. The console will ask an administrator for one on first " +
          'sign-in; it can also be set under Setup → Localization.',
      );
      return;
    }
    if (organizationIds.length === 0) {
      ctx.logger.debug(
        "[auth] dev seed: the seeded admin holds no organization membership yet, so no workspace time zone was set",
      );
      return;
    }

    for (const organizationId of organizationIds) {
      const scope = { tenantId: organizationId };
      try {
        const current = await settings.get('localization', 'timezone', scope);
        if (current?.source !== 'default') continue;
        await settings.set('localization', 'timezone', zone, scope);
        ctx.logger.info(
          `[auth] dev seed: workspace ${organizationId} takes this host's time zone, ${zone} ` +
            '(Setup → Localization changes it)',
        );
      } catch (err: any) {
        ctx.logger.warn(
          `[auth] dev seed: workspace ${organizationId} was not given this host's time zone (${zone}): ` +
            `${err?.message ?? err}. The console will ask an administrator for one on first sign-in; it ` +
            'can also be set under Setup → Localization.',
        );
      }
    }
  }

  /**
   * Boots after the seeding one: surface the dev credentials again if (and
   * only if) the seed account still exists with the DEFAULT password —
   * verified against the stored credential hash with better-auth's native
   * `password.verify`, so the hint disappears the boot after an admin
   * changes the password. Only reachable from `maybeSeedDevAdmin`'s
   * NODE_ENV==='development' gate; `devSeedResult` therefore never exists in
   * production, which is what keeps `getPublicConfig().devSeedAdmin` (the
   * login-page hint) dev-only by construction. Best-effort: any lookup or
   * verify failure just leaves the hint off.
   */
  private async maybeReportExistingSeedAdmin(
    ctx: PluginContext,
    ql: any,
    humans: any[],
    email: string,
    password: string,
  ): Promise<void> {
    try {
      if (!this.authManager) return;
      const seedUser = humans.find(
        (u: any) => typeof u?.email === 'string' && u.email.toLowerCase() === email.toLowerCase(),
      );
      if (!seedUser?.id) return;

      const accounts = await ql
        .find(
          'sys_account',
          { where: { user_id: seedUser.id, provider_id: 'credential' }, limit: 1 },
          { context: { isSystem: true } },
        )
        .catch(() => []);
      // [commit d6e80b28b] `sys_account.password` is `internal: true`, so the row above
      // arrives without it — the engine's strip has no `isSystem` carve-out.
      // Recover it through the privileged accessor; otherwise this probe reads
      // `undefined` on every boot and the dev credential hint silently stops
      // appearing (fails soft, which is why it would never be noticed).
      await recoverInternalFieldsForSystemRead(ql, 'sys_account', accounts, ['password']);
      const hash = Array.isArray(accounts) ? accounts[0]?.password : undefined;
      if (typeof hash !== 'string' || hash.length === 0) return;

      const authCtx: any = await this.authManager.getAuthContext();
      const verify = authCtx?.password?.verify;
      if (typeof verify !== 'function') return;
      const stillDefault = await verify.call(authCtx.password, { password, hash });
      if (stillDefault === true) {
        this.authManager.devSeedResult = { email, password };
        ctx.logger.debug('[auth] dev admin still on default credentials — surfacing the hint');
      }
    } catch (err: any) {
      ctx.logger.debug(`[auth] dev seed-admin probe skipped: ${err?.message ?? err}`);
    }
  }

  /**
   * ADR-0069 D5 — the operator-facing explanation of an allow-list refusal,
   * for the two cases where the reason is not simply "an address outside the
   * ranges". Logged at `warn` (a refusal the requester was told about, not a
   * durability loss) and ONCE per process per case, so a refused flood does not
   * repeat the same sentence per request.
   *
   *  - the address could not be established at all, so the request was refused
   *    as undetermined;
   *  - the allow-list judged the transport's peer address while the request
   *    carried a forwarded header that was not believed because
   *    `server.trustProxy` is not declared: the shape a deployment behind a
   *    proxy takes before it declares the proxy trusted.
   */
  private explainAllowListRefusal(
    ctx: PluginContext,
    mgr: AuthManager,
    ip: string | undefined,
    headers: Record<string, string>,
  ): void {
    const trustProxy = mgr.trustsForwardedHeaders();
    if (!ip) {
      if (this.allowListUndeterminedWarned) return;
      this.allowListUndeterminedWarned = true;
      ctx.logger.warn(
        '[auth] auth request refused (403 IP_NOT_ALLOWED): the `allowed_ip_ranges` setting (ADR-0069 D5) is set, '
          + 'but the server could not establish this request\'s client address. '
          + (trustProxy
            ? '`server.trustProxy` is declared, yet the request carried no X-Forwarded-For / X-Real-IP header '
              + 'and the transport reported no peer address. '
            : 'The transport reported no peer address, and forwarded headers are not believed because '
              + '`server.trustProxy` is not declared. ')
          + 'While the allow-list is set, every request whose address cannot be established is refused. Fix: '
          + 'serve through a transport that reports the socket address, or terminate on a reverse proxy you '
          + 'control that sets X-Forwarded-For and declare `server.trustProxy: true`; or clear `allowed_ip_ranges`.',
      );
      return;
    }
    if (trustProxy || this.allowListUntrustedHeaderWarned) return;
    if (!headers['x-forwarded-for'] && !headers['x-real-ip']) return;
    this.allowListUntrustedHeaderWarned = true;
    ctx.logger.warn(
      '[auth] auth request refused (403 IP_NOT_ALLOWED) by the `allowed_ip_ranges` setting (ADR-0069 D5): the '
        + 'allow-list judged the connection\'s peer address, because `server.trustProxy` is not declared and so the '
        + 'request\'s X-Forwarded-For / X-Real-IP header was not believed. If this deployment sits behind a reverse '
        + 'proxy you control, declare `server.trustProxy: true`; until then the allow-list judges the proxy\'s own '
        + 'address.',
      { judgedAddress: ip },
    );
  }

  /**
   * Register authentication routes with HTTP server
   *
   * Uses better-auth's universal handler for all authentication requests.
   * This forwards all requests under basePath to better-auth, which handles:
   * - Email/password authentication
   * - OAuth providers (Google, GitHub, etc.)
   * - Session management
   * - Password reset
   * - Email verification
   * - 2FA, passkeys, magic links (if enabled)
   */
  private registerAuthRoutes(httpServer: IHttpServer, ctx: PluginContext): void {
    if (!this.authManager) return;

    const basePath = this.options.basePath || DEFAULT_AUTH_BASE_PATH;

    // Get raw Hono app to use native wildcard routing
    // Type assertion is safe here because we explicitly require Hono server as a dependency
    if (!('getRawApp' in httpServer) || typeof (httpServer as any).getRawApp !== 'function') {
      ctx.logger.error('HTTP server does not support getRawApp() - wildcard routing requires Hono server');
      throw new Error(
        'AuthPlugin requires HonoServerPlugin for wildcard routing support. ' +
        'Please ensure HonoServerPlugin is loaded before AuthPlugin.'
      );
    }

    const rawApp = (httpServer as any).getRawApp();

    // ── ADR-0069 D5 — network gating (IP allow-list) ──────────────────────
    // Reject auth requests from a client address outside the configured
    // ranges, BEFORE they reach better-auth. Registered first so it runs ahead
    // of the routes below. The public render helpers (/config,
    // /bootstrap-status) are exempt so a blocked client still gets a clean
    // login page + error. Nothing is judged when no ranges are configured.
    //
    // The address judged is the one the server ESTABLISHED, by the platform's
    // client-address trust rule (`AuthManager.resolveClientAddress`, shared
    // with the runtime's inbound rate limiter): forwarded headers only when
    // `server.trustProxy` is declared, the transport's peer address otherwise.
    // An address that cannot be established is refused like one outside the
    // ranges (`isClientIpAllowed`), with an operator log line naming both
    // settings. The wildcard route below hands the same peer to
    // `handleRequest`, so the D7 login audit stamps this same address.
    if (typeof rawApp.use === 'function') rawApp.use(`${basePath}/*`, async (c: any, next: any) => {
      const mgr = this.authManager;
      if (
        !mgr ||
        typeof mgr.isClientIpAllowed !== 'function' ||
        typeof mgr.resolveClientAddress !== 'function'
      ) {
        return next();
      }
      const path: string = c.req.path || '';
      if (path.endsWith('/config') || path.endsWith('/bootstrap-status')) return next();
      const headers = (c.req.header() ?? {}) as Record<string, string>;
      const ip = mgr.resolveClientAddress({ headers, ...transportOf(c) });
      if (!mgr.isClientIpAllowed(ip)) {
        this.explainAllowListRefusal(ctx, mgr, ip, headers);
        return c.json(
          { success: false, error: { code: 'IP_NOT_ALLOWED', message: 'Sign-in is not allowed from your network.' } },
          403,
        );
      }
      return next();
    });

    // Register /config before the wildcard so it takes precedence.
    // better-auth has no /config endpoint, so without this explicit route
    // the wildcard below forwards the request and better-auth returns 404.
    rawApp.get(`${basePath}/config`, async (c: any) => {
      try {
        const config = this.authManager!.getPublicConfig();
        // Refine the coarse "SSO wired" flag to "SSO usable" (≥1 provider
        // configured) so the login UI also hides the "Sign in with SSO" button
        // when SSO is enabled but no IdP exists yet — not just when it's off.
        // Only queries when wired; falls open on any error (see isSsoUsable).
        if (config.features?.sso) {
          config.features.sso = await this.authManager!.isSsoUsable();
        }
        return c.json({ success: true, data: config });
      } catch (error) {
        const err = error instanceof Error ? error : new Error(String(error));
        return c.json({ success: false, error: { code: 'AUTH_CONFIG_ERROR', message: err.message } }, 500);
      }
    });

    // Bootstrap status — does an owner exist yet? Used by the Account SPA's
    // root route to decide between rendering /login (normal flow) and
    // /setup (first-run owner creation). Public, unauthenticated; only
    // returns a boolean so it can be polled before the user has any
    // credentials.
    //
    // [#14157] It asks `AuthManager.hasBootstrapWindow()` — the SAME question
    // the audience gate's bootstrap bypass answers, so the console can never
    // offer a first-run creation the platform would refuse, nor withhold one
    // it would admit and promote. It used to count `sys_user` rows with no
    // filter at all, which made it the one call site disagreeing with the
    // three `isHumanUserRow` consumers: on a database still carrying the
    // legacy `usr_system` service row it answered `hasOwner: true` while the
    // admission gate and plugin-security's first-user detection both said the
    // first human was still ahead. A no-engine composition (MSW/mock mode)
    // still reads as bootstrapped — the probe answers "no window" without an
    // engine — so the SPA falls through to its normal login flow as before.
    rawApp.get(`${basePath}/bootstrap-status`, async (c: any) => {
      try {
        return c.json({ hasOwner: !(await this.authManager!.hasBootstrapWindow()) });
      } catch (error) {
        ctx.logger.warn('[AuthPlugin] bootstrap-status check failed; assuming bootstrapped', error as Error);
        return c.json({ hasOwner: true });
      }
    });

    // Device Authorization Grant (RFC 8628) endpoints — `/device/code`,
    // `/device/token`, `/device/approve`, `/device/deny`, `/device` — are
    // provided by better-auth's `device-authorization` plugin and reach
    // the wildcard handler below. Enable via
    // `AuthPluginConfig.deviceAuthorization`.

    // Set an INITIAL local password for users who signed in via SSO and
    // have no `credential` account yet. This is the "Set local password"
    // affordance on a per-environment kernel — it lets a user that the
    // platform onboarded via the objectstack-cloud OAuth provider sign in
    // with email/password against this environment going forward without
    // needing the SSO round-trip. Requires a valid session (so we know
    // which user is asking) and refuses if a credential already exists
    // (the user should use better-auth's /change-password endpoint in
    // that case so the current password is verified).
    //
    // The body is `runSetInitialPassword` (shared with the cloud
    // AuthProxyPlugin) so both mount points wrap better-auth's server-only
    // `auth.api.setPassword` identically — see set-initial-password.ts.
    rawApp.post(`${basePath}/set-initial-password`, async (c: any) => {
      try {
        const authApi = await this.authManager!.getApi();
        // [#25083] On a cloud-managed environment the door narrows to a caller
        // with platform-admin standing: everyone else signs in through the
        // hosting organisation's identity provider, while an administrator can
        // still give themselves the local password break-glass needs (ADR-0135
        // D5.2 splits by population, never wholesale). A caller with no
        // session falls through to the body, which answers it as before.
        if (isCloudManaged()) {
          // [#24222] Read as `AuthSessionApi` declares the answer (see `SessionRead`).
          const session: SessionRead | null = await authApi.getSession(inProcessSessionReadInput(c.req.raw.headers));
          if (session?.user?.id && !isPlatformAdminUser(session.user)) {
            const refusal = cloudManagedRefusal('setInitialPassword');
            return c.json(refusal.body, refusal.status);
          }
        }
        const { status, body } = await runSetInitialPassword(authApi as any, c.req.raw);
        return c.json(body, status);
      } catch (error) {
        const err = error instanceof Error ? error : new Error(String(error));
        ctx.logger.error('[AuthPlugin] set-initial-password failed', err);
        return c.json({ success: false, error: { code: 'INTERNAL_ERROR', message: err.message } }, 500);
      }
    });

    // ────────────────────────────────────────────────────────────────────
    // OAuth admin: toggle the `disabled` flag on a registered OAuth client.
    //
    // Why this lives here (and not as a plain data-layer UPDATE on
    // sys_oauth_application): the stock admin update endpoint
    // (`/admin/oauth2/update-client`) does NOT accept `disabled` in its
    // Zod body schema, so the field gets silently stripped before it
    // reaches `updateClientEndpoint`. Re-measured 2026-08-23 against the
    // installed @better-auth/oauth-provider 1.7.1 (the package that
    // carries the endpoint at 1.7.x): `adminUpdateOAuthClient`
    // (`dist/authorize-Crqw4_bR.mjs:2860`) declares its body schema at
    // `:2862-2889`, and `disabled` occurs zero times in that block —
    // while matching 35 other lines of the same file (`grep -c`), so the
    // search reaches the text. The column exists, the runtime honours it
    // everywhere (introspect, token, authorize, public-client lookup),
    // but no client-facing API can flip it.
    //
    // We close the gap by writing through better-auth's own adapter under
    // the `/api/v1/auth/*` namespace so all OAuth-application mutations
    // remain auth-routed (no generic data-layer bypass for the `oauth_client`
    // model). When upstream adds `disabled` to `adminUpdateOAuthClient`'s
    // schema, this route can be deleted and the sys_oauth_application
    // action retargeted to the stock endpoint.
    //
    // Upstream tracking: https://github.com/better-auth/better-auth
    rawApp.post(`${basePath}/admin/oauth2/toggle-disabled`, async (c: any) => {
      try {
        // [#24032] A declared-JSON body that does not parse is refused, never
        // read as `{}` (which answered "client_id is required" for a body that
        // carried it); see request-json-body.ts.
        const reading = await readJsonRequestBody(c.req.raw);
        if (!reading.ok) {
          return c.json({ success: false, error: { code: 'INVALID_REQUEST', message: reading.message } }, 400);
        }
        const body: any = reading.body;
        const clientId: unknown = body?.client_id;
        const disabled: unknown = body?.disabled;
        if (typeof clientId !== 'string' || clientId.length === 0) {
          return c.json({ success: false, error: { code: 'INVALID_REQUEST', message: 'client_id is required' } }, 400);
        }
        if (typeof disabled !== 'boolean') {
          return c.json({ success: false, error: { code: 'INVALID_REQUEST', message: 'disabled must be a boolean' } }, 400);
        }

        // Platform-admin gate (ADR-0068 D2) — one shared judge for every
        // ObjectStack `/admin/*` mount; see platform-admin-gate.ts.
        const authApi = await this.authManager!.getApi();
        // [#24222] Read as `AuthSessionApi` declares the answer (see `SessionRead`).
        const session: SessionRead | null = await authApi.getSession(inProcessSessionReadInput(c.req.raw.headers));
        const verdict = judgePlatformAdmin(session);
        if (!verdict.ok) return c.json(verdict.refusal.body, verdict.refusal.status);

        // Write through the same ObjectQL data engine that better-auth's
        // adapter uses. We target the snake_case table name (`sys_oauth_application`,
        // mapped from better-auth's internal `oauthClient` model via
        // `auth-schema-config.ts`) because `$context.adapter`'s model-lookup
        // helper does not see plugin-provided model names from outside
        // better-auth's own endpoint invocation context. This is the same
        // physical row the better-auth runtime reads at introspect / token
        // / authorize time, so the toggle is fully honoured.
        //
        // And through the same WRAPPER: `withSystemContext`, so the read and
        // the write both carry the explicit system opt-in (`isSystem: true`).
        // The platform-admin judge above is this route's authorization; the
        // raw engine would have handed the security middleware a context with
        // no principal and no opt-in — the principal-less hand-off it no longer
        // makes (ADR-0096 D5 refuses that context), and never an authorization.
        const rawEngine = this.authManager!.getDataEngine();
        if (!rawEngine) {
          return c.json({ success: false, error: { code: 'SERVICE_UNAVAILABLE', message: 'Data engine unavailable' } }, 503);
        }
        const dataEngine: any = withSystemContext(rawEngine);

        const existing = await dataEngine.findOne('sys_oauth_application', {
          where: { client_id: clientId },
        });
        if (!existing) {
          return c.json({ success: false, error: { code: 'RESOURCE_NOT_FOUND', message: 'OAuth client not found' } }, 404);
        }

        const updated = await dataEngine.update('sys_oauth_application', {
          id: existing.id,
          disabled,
          updated_at: new Date(Math.floor(Date.now() / 1000) * 1000),
        });
        if (!updated) {
          return c.json({ success: false, error: { code: 'INTERNAL_ERROR', message: 'Unable to update OAuth client' } }, 500);
        }

        return c.json({
          success: true,
          data: {
            client_id: clientId,
            disabled,
          },
        });
      } catch (error) {
        const err = error instanceof Error ? error : new Error(String(error));
        ctx.logger.error('[AuthPlugin] toggle-disabled failed', err);
        return c.json({ success: false, error: { code: 'INTERNAL_ERROR', message: err.message } }, 500);
      }
    });

    // ── ADR-0068 D2/D4 — the ONE platform-admin gate helper for every raw
    // `/admin/*` mount below (see platform-admin-gate.ts for the judge and
    // its unit-tested posture matrix). Returns the admitted actor, or the
    // refusal Response to hand straight back. Hoisted here (#9653) so the
    // four `/admin/sso/*` bridges and the #2766 admin-user block share one
    // spelling instead of accreting per-mount copies.
    const gateAdmin = async (c: any): Promise<PlatformAdminActor | Response> => {
      const authApi = await this.authManager!.getApi();
      // [#24222] Read as `AuthSessionApi` declares the answer (see `SessionRead`), not through `any`.
      const session: SessionRead | null = await authApi.getSession(inProcessSessionReadInput(c.req.raw.headers));
      const verdict = judgePlatformAdmin(session);
      if (!verdict.ok) return c.json(verdict.refusal.body, verdict.refusal.status);
      return verdict.actor;
    };

    // ── [#24877] ADR-0069 D5/D7 — better-auth's universal handler for the
    // request a raw mount below serves, WITH that request's transport. Every
    // in-process bridge re-dispatches through `AuthManager.handleRequest` with
    // the transport of the request it serves — a bridge that hands a helper a
    // handler takes it from here; one that delegates the request itself passes
    // `transportOf(c)` inline, as the catch-all at the end of this method
    // does — so `handleRequest` establishes the re-dispatched request's client
    // address by the platform's trust rule (`resolveClientAddress`): forwarded
    // headers only when the deployment declares `server.trustProxy`, the
    // connection peer otherwise. `handleRequest(req)` alone leaves the rule no
    // peer to judge on. Pinned per bridge by
    // `bridge-redispatch-transport.pin.test.ts`.
    const handleWithTransportOf = (c: any): AuthRequestHandler => (request) =>
      this.authManager!.handleRequest(request, transportOf(c));

    // ────────────────────────────────────────────────────────────────────
    // SSO admin: register an external OIDC IdP from the flat metadata form
    // (ADR-0135 D6). `@better-auth/sso`'s POST /sso/register expects the protocol
    // fields NESTED under `oidcConfig` ({ clientId, clientSecret,
    // discoveryEndpoint, scopes, mapping }). The `sys_sso_provider`
    // `register_sso_provider` action collects FLAT form fields (the action
    // param schema has no nested-path support), so posting them straight to
    // /sso/register lands them at the top level where better-auth's Zod schema
    // strips them → a provider with `oidc_config = null` that can never
    // complete a login. This thin bridge reshapes the flat form body into the
    // nested shape and RE-DISPATCHES it through the real /sso/register endpoint
    // (via the better-auth handler) so the public-routable trustedOrigins
    // allowance, discovery hydration, and secret handling all still run. No
    // bespoke persistence. Retire when the action framework gains nested-param
    // support.
    //
    // #9653 — ADR-0068 D4: the platform-admin gate runs HERE, before the
    // bridge delegates. Registering an identity provider is a platform-
    // operator action, and the delegated authorization is NOT a substitute:
    // measured on the then-installed @better-auth/sso 1.7.1, the vendor's
    // /sso/register admits ANY authenticated user when no organizationId is
    // supplied (the org-admin check is inside `if (ctx.body.organizationId)`),
    // and the auth-manager before-hook that narrows this admits org
    // owners/admins, who are not platform admins (ADR-0068). Gating first
    // also un-masks the refusal labels: an anonymous caller used to get the
    // capability error (404 SSO_REGISTER_FAILED), never a 401. Anonymous-
    // first ordering — identity error before capability error — so the gate
    // runs ahead of the bridge's own body validation.
    rawApp.post(`${basePath}/admin/sso/register`, async (c: any) => {
      try {
        const gated = await gateAdmin(c);
        if (gated instanceof Response) return gated;
        const { status, body } = await runRegisterSsoProviderFromForm(
          handleWithTransportOf(c),
          c.req.raw,
        );
        return c.json(body, status as any);
      } catch (error) {
        const err = error instanceof Error ? error : new Error(String(error));
        ctx.logger.error('[AuthPlugin] sso/register bridge failed', err);
        return c.json({ success: false, error: { code: 'INTERNAL_ERROR', message: err.message } }, 500);
      }
    });

    // ────────────────────────────────────────────────────────────────────
    // ADR-0069 D2 — admin: clear a brute-force lockout on an account.
    // Lockout (`sys_user.locked_until` / `failed_login_count`) is a custom,
    // per-identity mechanism with no better-auth endpoint, so this route owns
    // the "Unlock" affordance (sys_user `unlock_user` action). Admin-guarded
    // server-side; mirrors the toggle-disabled route's session+role check.
    rawApp.post(`${basePath}/admin/unlock-user`, async (c: any) => {
      try {
        // [#24032] Same read as toggle-disabled above: a truncated body used to
        // answer "userId is required" for a body that carried `userId`.
        const reading = await readJsonRequestBody(c.req.raw);
        if (!reading.ok) {
          return c.json({ success: false, error: { code: 'INVALID_REQUEST', message: reading.message } }, 400);
        }
        const body: any = reading.body;
        const userId: unknown = body?.userId ?? body?.user_id;
        if (typeof userId !== 'string' || userId.length === 0) {
          return c.json({ success: false, error: { code: 'INVALID_REQUEST', message: 'userId is required' } }, 400);
        }

        // Platform-admin gate (ADR-0068 D2) — see platform-admin-gate.ts.
        const authApi = await this.authManager!.getApi();
        // [#24222] Read as `AuthSessionApi` declares the answer (see `SessionRead`).
        const session: SessionRead | null = await authApi.getSession(inProcessSessionReadInput(c.req.raw.headers));
        const verdict = judgePlatformAdmin(session);
        if (!verdict.ok) return c.json(verdict.refusal.body, verdict.refusal.status);

        const ok = await this.authManager!.unlockUser(userId);
        if (!ok) {
          return c.json({ success: false, error: { code: 'RESOURCE_NOT_FOUND', message: 'User not found or data engine unavailable' } }, 404);
        }
        return c.json({ success: true, data: { userId } });
      } catch (error) {
        const err = error instanceof Error ? error : new Error(String(error));
        ctx.logger.error('[AuthPlugin] unlock-user failed', err);
        return c.json({ success: false, error: { code: 'INTERNAL_ERROR', message: err.message } }, 500);
      }
    });

    // ────────────────────────────────────────────────────────────────────
    // #16678 — admin: set (or clear) a user's manager.
    //
    // `sys_user.manager_id` drives the approvals `{ type: 'manager' }` rung
    // and the `own_and_reports` read scope, and had no product write surface
    // at all: the generic data path refuses it (ADR-0092 D2's managed-update
    // whitelist is `{name, image, locale}`), the bulk import does not carry
    // it, and the Console renders it read-only. So the rung expanded to
    // nobody on every record in any install without a directory sync.
    //
    // Same family as `unlock-user` above: an ObjectStack mount on the raw app
    // ahead of the catch-all, platform-admin gated (ADR-0068), ledgered in
    // `auth-route-ledger.ts`. The handler runs under a SYSTEM context, so it
    // reaches the column by context rather than by whitelist — exactly how
    // `admin-import-users` already reaches `phone_number` and `role` — which
    // is why no Tier-1 list moves and the column keeps `readonly: true`.
    // Every refusal (self-assignment, cycle, depth, cross-organization,
    // directory-owned identity) is enforced in the handler; see
    // `admin-set-user-manager.ts` for why each one has to live at the write.
    rawApp.post(`${basePath}/admin/set-user-manager`, async (c: any) => {
      try {
        const actor = await gateAdmin(c);
        if (actor instanceof Response) return actor;
        const { runSetUserManager } = await import('./admin-set-user-manager.js');
        // Attribution only — the route's own authorization already happened
        // in `gateAdmin`. Opening the actor seam here credits the `sys_user`
        // row to the admin instead of recording it as the system.
        const { status, body } = await runAttributedToUser(actor.id, () =>
          runSetUserManager(
            {
              getDataEngine: () => this.authManager!.getDataEngine() as any,
              logger: ctx.logger,
            },
            actor,
            c.req.raw,
          ),
        );
        return c.json(body, status as any);
      } catch (error) {
        const err = error instanceof Error ? error : new Error(String(error));
        ctx.logger.error('[AuthPlugin] set-user-manager failed', err);
        return c.json({ success: false, error: { code: 'INTERNAL_ERROR', message: err.message } }, 500);
      }
    });

    // ────────────────────────────────────────────────────────────────────
    // #2766 V1 — admin direct user management. `sys_user` CRUD is suppressed
    // (managedBy better-auth), and until now the only add-a-teammate path was
    // the email-dependent invite flow. These routes let a platform admin
    // create a login-capable account (better-auth pipeline: scrypt hash +
    // credential sys_account) and (re)set passwords, with an optional
    // generated temporary password + a must-change-on-first-login flag.
    //
    // Both routes run the same ADR-0068 platform-admin gate as unlock-user
    // above, then call trusted server-side better-auth surfaces — see
    // admin-user-endpoints.ts for why the stock role check doesn't fit.
    //
    // NOTE: /admin/set-user-password intentionally SHADOWS better-auth's
    // native route (registered before the catch-all below). The native
    // handler only accepts the legacy `role === 'admin'` scalar, which
    // ADR-0068 platform admins may not carry; this wrapper accepts the
    // canonical platform-admin signals and adds the force-change stamp.
    {
      const adminUserDeps = (): import('./admin-user-endpoints.js').AdminUserEndpointDeps => ({
        getAuthApi: () => this.authManager!.getApi() as any,
        getAuthContext: () => this.authManager!.getAuthContext(),
        getDataEngine: () => this.authManager!.getDataEngine(),
        assertPasswordComplexity: (pw: string) => this.authManager!.checkPasswordComplexity(pw),
        noteMustChangePasswordIssued: () => this.authManager!.noteMustChangePasswordIssued(),
        phoneNumberEnabled: () => this.authManager!.isPhoneNumberEnabled(),
        // ADR-0093 D3 — mode-aware create-user bind: multi-org resolves NO
        // target org (never grab the bootstrap default org in a multi-tenant
        // deployment); single-org resolves the default org.
        getTenancy: () => this.tenancy ?? undefined,
        // ADR-0093 D1 — the LIVE membership policy, read through the accessor
        // per call (the deps factory itself runs per request). A captured
        // value would keep the endpoint auto-binding after an admin switched
        // the deployment to `invite-only`, which is the exact defect the
        // accessor exists to prevent.
        getMembershipPolicy: () => this.authManager!.getMembershipPolicy(),
        logger: ctx.logger,
      });
      // Gate: the shared `gateAdmin` hoisted above the SSO mounts (#9653).

      // [#25338] create-user's optional permission set. The grant is judged
      // under the CALLER's own execution context — resolved by the platform's
      // one composition, as the data door resolves it for Setup's grant form —
      // so the security middleware and the ADR-0090 D12 gate decide it there,
      // never `gateAdmin`. The parameters are the `/auth/me` endpoints'
      // (session only, no localization, no gate carried): this route admits a
      // browser session and needs the caller's grants, nothing else. The
      // account and the grant are one engine transaction (ADR-0034), with the
      // engine's declared limit: a datasource without `beginTransaction` runs
      // it unatomically (ADR-0119 D1, warned once per driver).
      const createGrantFor = (c: any): import('./admin-user-endpoints.js').AdminCreateGrantSeam => ({
        resolveActorContext: async () => {
          const context = await resolveRequestExecutionContext({
            headers: c.req.raw.headers,
            ql: this.authManager!.getDataEngine(),
            authService: this.authManager as unknown as RequestAuthService,
            tenancy: () => this.tenancy ?? undefined,
            anonymous: 'fail-closed',
            authGate: 'withhold',
            credentials: 'session-only',
            sessionApi: 'required',
            session: 'request',
            localization: 'withhold',
            requestLocale: undefined,
            accessToken: 'withhold',
            oauth: undefined,
            onAdmission: undefined,
          });
          return context as Record<string, unknown> | undefined;
        },
        runAtomically: async <T,>(work: () => Promise<T>): Promise<T> => {
          const engine = this.authManager!.getDataEngine() as
            | { transaction?: <R>(callback: (trxCtx: any, info: any) => Promise<R>) => Promise<R> }
            | undefined;
          if (typeof engine?.transaction !== 'function') return work();
          return engine.transaction(async () => work());
        },
      });

      rawApp.post(`${basePath}/admin/create-user`, async (c: any) => {
        try {
          const actor = await gateAdmin(c);
          if (actor instanceof Response) return actor;
          // [#25083] After the identity and admin checks, before any write: a
          // cloud-managed environment's users are invited in the cloud.
          if (isCloudManaged()) {
            const refusal = cloudManagedRefusal('createUser');
            return c.json(refusal.body, refusal.status);
          }
          const authApi: any = await this.authManager!.getApi();
          if (typeof authApi.createUser !== 'function') {
            return c.json(
              { success: false, error: { code: 'NOT_IMPLEMENTED', message: 'The better-auth admin plugin is not enabled (auth.plugins.admin)' } },
              501,
            );
          }
          const { runAdminCreateUser } = await import('./admin-user-endpoints.js');
          // [#4586] This route authorized the admin itself (`gateAdmin`) and
          // then drives better-auth SERVER-SIDE, so it never passes through
          // `AuthManager.handleRequest` and the request-scoped actor seam is
          // not open. Open it here with the actor already in hand, so the
          // identity rows this creates — and the membership the reconciler
          // binds in `user.create.after` — are credited to the admin instead
          // of recorded as the system. Attribution only: the route's own
          // authorization already happened above, and the writes stay system.
          const { status, body } = await runAttributedToUser(actor.id, () =>
            runAdminCreateUser({ ...adminUserDeps(), createGrant: createGrantFor(c) }, c.req.raw, actor),
          );
          return c.json(body, status as any);
        } catch (error) {
          const err = error instanceof Error ? error : new Error(String(error));
          ctx.logger.error('[AuthPlugin] admin/create-user failed', err);
          return c.json({ success: false, error: { code: 'INTERNAL_ERROR', message: err.message } }, 500);
        }
      });

      // ── #9652: ban / unban, re-mounted with the ADR-0068 gate ────────────
      //
      // These SHADOW better-auth's native `/admin/ban-user` and
      // `/admin/unban-user`. The vendor's `admin` plugin authorizes on the
      // legacy `user.role === 'admin'` scalar that ADR-0068 D2 stopped
      // synthesizing, and it exposes no option that can be pointed at
      // ObjectStack's predicate — a MEASURED property of the installed
      // version, written up in admin-ban-endpoints.ts. The result was that the
      // `sys_user` Ban / Unban buttons 403'd for every platform admin on any
      // deployment with the admin plugin on (SCIM forces it, ADR-0134).
      //
      // ⚠️ Shadowing detaches better-auth hooks keyed on the path: the
      // break-glass last-local-credential guard used to fire on
      // `/admin/ban-user` from `auth-manager.ts`. `runAdminBanUser` re-runs it
      // from the shared module.
      const adminBanDeps = (): AdminBanEndpointDeps => ({
        getAuthContext: () => this.authManager!.getAuthContext(),
      });

      /**
       * Refuse when the admin plugin is off, exactly as create-user does.
       *
       * Without this the shadowing mounts would answer 200 on a deployment
       * that has no admin plugin — writing `banned: true` while the vendor's
       * session hook that ENFORCES a ban is not loaded. That is a
       * declared-but-not-enforced ban: the console reports success and the
       * banned user signs straight back in. `banUser` on the api surface is
       * the same seam create-user tests for.
       */
      const adminPluginMissing = async (c: any): Promise<Response | undefined> => {
        const authApi: any = await this.authManager!.getApi();
        if (typeof authApi.banUser === 'function') return undefined;
        return c.json(
          { success: false, error: { code: 'NOT_IMPLEMENTED', message: 'The better-auth admin plugin is not enabled (auth.plugins.admin)' } },
          501,
        );
      };

      rawApp.post(`${basePath}/admin/ban-user`, async (c: any) => {
        try {
          const actor = await gateAdmin(c);
          if (actor instanceof Response) return actor;
          const unavailable = await adminPluginMissing(c);
          if (unavailable) return unavailable;
          // Attributed to the admin for the same reason create-user is: the
          // write is driven server-side and never passes through
          // `AuthManager.handleRequest`, so the request-scoped actor seam is
          // not open unless we open it here.
          const { status, body } = await runAttributedToUser(actor.id, () =>
            runAdminBanUser(adminBanDeps(), actor, c.req.raw),
          );
          return c.json(body, status as any);
        } catch (error) {
          const err = error instanceof Error ? error : new Error(String(error));
          ctx.logger.error('[AuthPlugin] admin/ban-user failed', err);
          return c.json({ success: false, error: { code: 'INTERNAL_ERROR', message: err.message } }, 500);
        }
      });

      rawApp.post(`${basePath}/admin/unban-user`, async (c: any) => {
        try {
          const actor = await gateAdmin(c);
          if (actor instanceof Response) return actor;
          const unavailable = await adminPluginMissing(c);
          if (unavailable) return unavailable;
          const { status, body } = await runAttributedToUser(actor.id, () =>
            runAdminUnbanUser(adminBanDeps(), actor, c.req.raw),
          );
          return c.json(body, status as any);
        } catch (error) {
          const err = error instanceof Error ? error : new Error(String(error));
          ctx.logger.error('[AuthPlugin] admin/unban-user failed', err);
          return c.json({ success: false, error: { code: 'INTERNAL_ERROR', message: err.message } }, 500);
        }
      });

      // ── commit 6dd3e6968: /admin/remove-user — AUTHORIZATION BEFORE THE GUARD ──
      //
      // The break-glass last-local-credential guard is a global
      // `hooks.before` in auth-manager.ts keyed on `ctx.path`. A better-auth
      // `before` hook runs ahead of the endpoint's own `use: [adminMiddleware]`
      // — and on this route that middleware is only a SESSION check, with the
      // role decision landing later still, inside the vendor's handler. So on
      // the unshaded route the guard's lookup and its distinctive refusal were
      // reached by any AUTHENTICATED caller, admin or not, before either
      // authorization layer had run.
      //
      // MEASURED on the then-installed better-auth 1.7.1 before this mount existed,
      // one authenticated non-admin, two targets: naming the break-glass
      // holder answered `409 LAST_LOCAL_CREDENTIAL` while naming an ordinary
      // user answered `403 YOU_ARE_NOT_ALLOWED_TO_DELETE_USERS`. Two different
      // answers to the same caller IS the finding — the refusal itself carried
      // a per-record fact about a user the caller was never entitled to ask
      // about. The same measurement on `/admin/ban-user` answered
      // `403 PERMISSION_DENIED` for BOTH targets, because #9652 already shades
      // that path and `gateAdmin` runs first there.
      //
      // Maintainer ruling 2026-08-25 (decision-inbox batch 5, accepted
      // verbatim 「全部同意」): option A — give this route the same raw-mount
      // shading `/admin/ban-user` has, converging the whole `/admin/*` family
      // on authorization before the guard. No new mechanism.
      //
      // ⚠️ This mount DELEGATES; it does not re-implement. That is the whole
      // difference from the ban/unban mounts above, and it is deliberate:
      //
      //   • #9969 (closed `not_planned`) ruled that the consumer-less vendor
      //     routes — this one included — are NOT re-implemented; their 403 to
      //     a platform admin is a recorded, intended state. Re-implementing
      //     removal here would quietly overturn that ruling.
      //   • Delegating keeps the request inside better-auth's router, so the
      //     path-keyed `hooks.before` still fires and the guard KEEPS working.
      //     Shadowing normally DETACHES such hooks (the trap written up in
      //     last-local-credential.ts, which is why ban-user must re-run the
      //     guard by hand); re-dispatching through `handleRequest` is what
      //     avoids paying that cost twice. The `/admin/sso/*` bridges use this
      //     exact gate-then-delegate shape (#9653).
      //
      // ⇒ WHAT CHANGES is only WHEN the guard decides, never WHAT it decides:
      //   anonymous            → 401 UNAUTHENTICATED   (unchanged)
      //   authenticated member → 403 PERMISSION_DENIED for EVERY target — the
      //                          guard is now unreachable before authorization
      //   platform admin       → unchanged in every respect, including the
      //                          vendor's own 403 (#9969) and the guard's 409
      //                          when the target really is the last holder
      //
      // The vendor Response is returned VERBATIM so the delegated answer —
      // status, body and the #10349 ADR-0112 envelope `handleRequest` applies
      // to vendor `/admin/` refusals — is byte-identical to the unshaded route.
      //
      // Pinned by `admin-remove-user-gate-ordering.test.ts`, which fails if
      // this mount is removed.
      rawApp.post(`${basePath}/admin/remove-user`, async (c: any) => {
        try {
          const gated = await gateAdmin(c);
          if (gated instanceof Response) return gated;
          return await this.authManager!.handleRequest(c.req.raw, transportOf(c));
        } catch (error) {
          const err = error instanceof Error ? error : new Error(String(error));
          ctx.logger.error('[AuthPlugin] admin/remove-user failed', err);
          return c.json({ success: false, error: { code: 'INTERNAL_ERROR', message: err.message } }, 500);
        }
      });

      // ── #11900: /admin/has-permission — a QUERY answered from the ADR-0068
      // predicate, everything else delegated byte-for-byte ────────────────
      //
      // The vendor evaluates this permission QUERY on the legacy
      // `user.role === 'admin'` scalar ADR-0068 D2 stopped synthesizing, so a
      // genuine platform admin was told `200 {"success":false}` —
      // byte-identical to a plain member's answer. Not a refusal like the
      // #9652 family: a confident WRONG ANSWER on a published
      // authorization-answer surface. Maintainer ruling 2026-08-25 (option B
      // per the card body's lettering): shade it, answering from the
      // ADR-0068 predicate.
      //
      // ⚠️ Unlike `remove-user` above, gate-then-delegate CANNOT carry this
      // fix: delegation preserves the vendor's answer, and here the vendor's
      // answer to the admitted caller IS the defect. And unlike `ban-user`,
      // gate-then-reimplement cannot either: `gateAdmin`'s 403 would replace
      // the plain member's own `200 {"error":null,"success":false}` — the
      // correct negative ANSWER to a permission question, pinned by the
      // non-admin dogfood sweep (a `true` there would be the leak, but so
      // would turning the answer into a refusal). So this mount branches on
      // the predicate WITHOUT refusing anyone:
      //
      //   platform admin + a body the vendor would evaluate
      //     → answered here, from the vendor's own access-control statements
      //       with only the identity signal replaced (an ungranted or unknown
      //       permission still answers `false` — see
      //       admin-has-permission-endpoint.ts for why unconditional `true`
      //       would be a new wrong-200);
      //   everyone and everything else — anonymous (enveloped 401), plain
      //   member (its own negative), any body the vendor refuses (vendor
      //   400, vendor ordering)
      //     → delegated through `handleRequest`, native bytes standing.
      //
      // Ledger: `POST /api/v1/auth/admin/has-permission` stays a
      // `BETTER_AUTH_MOUNTED_SURFACE` row; `check:auth-mount-ledger` accounts
      // for this mount as "shadowing a vendor-declared path" (as it read commit
      // 6dd3e6968's remove-user mount — a shadow is accounted for, not a new row).
      //
      // Pinned by `admin-has-permission-endpoint.test.ts` (both directions,
      // full table) and the two dogfood sweeps (admin standing + non-admin
      // negative).
      rawApp.post(`${basePath}/admin/has-permission`, async (c: any) => {
        try {
          const authApi = await this.authManager!.getApi();
          // [#24222] Read as `AuthSessionApi` declares the answer (see `SessionRead`), not through `any`.
          const session: SessionRead | null = await authApi.getSession(inProcessSessionReadInput(c.req.raw.headers));
          const user = session?.user;
          if (user?.id && isPlatformAdminUser(user)) {
            const { readEvaluatedPermissionQuery, answerPermissionQueryAsAdmin } = await import(
              './admin-has-permission-endpoint.js'
            );
            // Parse from a CLONE: on the delegate path below the original
            // request body must reach the vendor undisturbed.
            let body: unknown;
            try {
              body = await c.req.raw.clone().json();
            } catch {
              body = undefined; // unreadable → the vendor's own 400, below
            }
            const query = readEvaluatedPermissionQuery(body);
            if (query) {
              const answer = await answerPermissionQueryAsAdmin(
                { getAuthContext: () => this.authManager!.getAuthContext() },
                String(user.id),
                query,
              );
              return c.json(answer, 200);
            }
          }
          return await this.authManager!.handleRequest(c.req.raw, transportOf(c));
        } catch (error) {
          const err = error instanceof Error ? error : new Error(String(error));
          ctx.logger.error('[AuthPlugin] admin/has-permission failed', err);
          return c.json({ success: false, error: { code: 'INTERNAL_ERROR', message: err.message } }, 500);
        }
      });

      rawApp.post(`${basePath}/admin/set-user-password`, async (c: any) => {
        try {
          const actor = await gateAdmin(c);
          if (actor instanceof Response) return actor;
          const { runAdminSetUserPassword } = await import('./admin-user-endpoints.js');
          const { status, body } = await runAdminSetUserPassword(adminUserDeps(), c.req.raw, actor);
          return c.json(body, status as any);
        } catch (error) {
          const err = error instanceof Error ? error : new Error(String(error));
          ctx.logger.error('[AuthPlugin] admin/set-user-password failed', err);
          return c.json({ success: false, error: { code: 'INTERNAL_ERROR', message: err.message } }, 500);
        }
      });

      // #2766 V2 — identity bulk import (re-scoped #2758). Reuses the generic
      // import framework's parsing + row engine but writes every row through
      // better-auth (hash + credential account) — see admin-import-users.ts
      // for the password policies (invite / temporary) and deliberate limits
      // (sync ≤500 rows, no undo, profile-only upsert updates).
      rawApp.post(`${basePath}/admin/import-users`, async (c: any) => {
        try {
          const actor = await gateAdmin(c);
          if (actor instanceof Response) return actor;
          // [#25083] Same placement and reason as create-user's refusal.
          if (isCloudManaged()) {
            const refusal = cloudManagedRefusal('importUsers');
            return c.json(refusal.body, refusal.status);
          }
          const { runAdminImportUsers } = await import('./admin-import-users.js');
          // [#4251] Resolved from `protocol`, not `metadata`. `getMetaItem` is a
          // PROTOCOL method (`ObjectStackProtocolImplementation`, registered by
          // MetadataProtocolPlugin); the `metadata` slot holds MetadataManager,
          // which has never had it. So `metadataService?.getMetaItem` was always
          // falsy and the field-coercion dep was never passed — an import row's
          // values reached `sys_user` uncoerced, with the branch that says
          // otherwise sitting right here. Invisible while the lookup was `any`:
          // typing it to the slot's contract is what turned the dead probe into
          // a compile error.
          const metaReader = (() => {
            try { return ctx.getService?.<MetaItemReaderSurface>('protocol'); } catch { return undefined; }
          })();
          // [#4586] Same seam as create-user: server-side better-auth calls,
          // credited to the admin who ran the import.
          const { status, body } = await runAttributedToUser(actor.id, () =>
            runAdminImportUsers(
            {
              getAuthApi: () => this.authManager!.getApi() as any,
              getDataEngine: () => this.authManager!.getDataEngine(),
              ...(typeof metaReader?.getMetaItem === 'function'
                ? { getMetaItem: (ref: { type: string; name: string }) => metaReader.getMetaItem(ref) }
                : {}),
              phoneNumberEnabled: () => this.authManager!.isPhoneNumberEnabled(),
              emailServiceAvailable: () => this.authManager!.isEmailServiceAvailable(),
              // #2780 — SMS invites need the phone plugin (the invitee's
              // first sign-in is a phone OTP) plus deliverable SMS.
              smsInviteAvailable: () =>
                this.authManager!.isPhoneNumberEnabled() && this.authManager!.isPhoneOtpDeliverable(),
              sendInviteSms: (phone: string) => this.authManager!.sendPhoneInviteSms(phone),
              consoleResetPasswordUrl: () => this.authManager!.getConsoleUrl('/reset-password'),
              noteMustChangePasswordIssued: () => this.authManager!.noteMustChangePasswordIssued(),
              logger: ctx.logger,
            },
            c.req.raw,
            actor,
            ),
          );
          return c.json(body, status as any);
        } catch (error) {
          const err = error instanceof Error ? error : new Error(String(error));
          ctx.logger.error('[AuthPlugin] admin/import-users failed', err);
          return c.json({ success: false, error: { code: 'INTERNAL_ERROR', message: err.message } }, 500);
        }
      });
    }

    // ────────────────────────────────────────────────────────────────────
    // #9941 — organization/add-member. better-auth declares `addMember`
    // WITHOUT an HTTP path (server-only `auth.api.addMember`; measured on the
    // then-installed 1.7.1), so the catch-all never mounts it — yet the
    // `sys_member` `add_member` toolbar action has always targeted this URL,
    // and on a multi-org posture it is the only UI path that can attach an
    // existing user to an organization. This mount restores that declared
    // surface behind the shared ADR-0068 platform-admin gate (attaching a
    // user without their consent is a platform-operator action, and the
    // vendor endpoint does no authorization of its own). Ledgered as
    // `server-only` in auth-route-ledger.ts; logic in
    // organization-add-member.ts.
    rawApp.post(`${basePath}/organization/add-member`, async (c: any) => {
      try {
        const actor = await gateAdmin(c);
        if (actor instanceof Response) return actor;
        const { runOrganizationAddMember } = await import('./organization-add-member.js');
        // [#4586] Same seam as create-user: the write is driven server-side
        // and never passes through `AuthManager.handleRequest`, so open the
        // attribution seam here — the `sys_member` row this creates is
        // credited to the admin instead of recorded as the system.
        const { status, body } = await runAttributedToUser(actor.id, () =>
          runOrganizationAddMember({ getAuthApi: () => this.authManager!.getApi() as any }, c.req.raw),
        );
        return c.json(body, status as any);
      } catch (error) {
        const err = error instanceof Error ? error : new Error(String(error));
        ctx.logger.error('[AuthPlugin] organization/add-member failed', err);
        return c.json({ success: false, error: { code: 'INTERNAL_ERROR', message: err.message } }, 500);
      }
    });

    // ────────────────────────────────────────────────────────────────────
    // ADR-0069 P3 — register a SAML 2.0 IdP. Mirrors the OIDC bridge above:
    // the metadata `register_saml_provider` action posts FLAT fields; the shared
    // helper reshapes them into better-auth's nested `samlConfig` (deriving the
    // per-provider ACS URL) and re-dispatches through /sso/register so the
    // admin gate + provisioning all run. Returns SP ACS + metadata URLs.
    rawApp.post(`${basePath}/admin/sso/register-saml`, async (c: any) => {
      try {
        // #9653 — same ADR-0068 D4 platform-admin gate as /admin/sso/register
        // above, judged before the bridge delegates.
        const gated = await gateAdmin(c);
        if (gated instanceof Response) return gated;
        const { status, body } = await runRegisterSamlProviderFromForm(
          handleWithTransportOf(c),
          c.req.raw,
        );
        return c.json(body, status as any);
      } catch (error) {
        const err = error instanceof Error ? error : new Error(String(error));
        ctx.logger.error('[AuthPlugin] sso/register-saml bridge failed', err);
        return c.json({ success: false, error: { code: 'INTERNAL_ERROR', message: err.message } }, 500);
      }
    });

    // ────────────────────────────────────────────────────────────────────
    // SSO domain verification (ADR-0135 D6, opt-in OS_SSO_DOMAIN_VERIFICATION).
    // Re-dispatch through @better-auth/sso's /sso/{request-domain-verification,
    // verify-domain} (so the per-provider admin gate runs) and reshape into the
    // `{ success, data }` envelope the action `resultDialog` / toast reads:
    // request returns the ready-to-paste DNS TXT record, verify returns a clear
    // success/error. [#22463] Each hands the bridge this environment's own
    // setting, so a feature-off answer and an unknown provider's are told apart
    // (the vendor answers both with a code-less 404).
    rawApp.post(`${basePath}/admin/sso/request-domain-verification`, async (c: any) => {
      try {
        // #9653 — same ADR-0068 D4 platform-admin gate as /admin/sso/register
        // above; the identity answer comes before the capability answer, so an
        // anonymous caller gets 401 even while OS_SSO_DOMAIN_VERIFICATION is off.
        const gated = await gateAdmin(c);
        if (gated instanceof Response) return gated;
        const { status, body } = await runRequestDomainVerification(
          handleWithTransportOf(c),
          c.req.raw,
          { domainVerificationEnabled: this.authManager!.isSsoDomainVerificationEnabled() },
        );
        return c.json(body, status as any);
      } catch (error) {
        const err = error instanceof Error ? error : new Error(String(error));
        ctx.logger.error('[AuthPlugin] sso/request-domain-verification bridge failed', err);
        return c.json({ success: false, error: { code: 'INTERNAL_ERROR', message: err.message } }, 500);
      }
    });

    rawApp.post(`${basePath}/admin/sso/verify-domain`, async (c: any) => {
      try {
        // #9653 — same ADR-0068 D4 platform-admin gate as /admin/sso/register.
        const gated = await gateAdmin(c);
        if (gated instanceof Response) return gated;
        const { status, body } = await runVerifyDomain(
          handleWithTransportOf(c),
          c.req.raw,
          { domainVerificationEnabled: this.authManager!.isSsoDomainVerificationEnabled() },
        );
        return c.json(body, status as any);
      } catch (error) {
        const err = error instanceof Error ? error : new Error(String(error));
        ctx.logger.error('[AuthPlugin] sso/verify-domain bridge failed', err);
        return c.json({ success: false, error: { code: 'INTERNAL_ERROR', message: err.message } }, 500);
      }
    });

    // ────────────────────────────────────────────────────────────────────
    // OAuth self-service: register an OAuth application for the signed-in
    // user. Thin wrapper over better-auth's `/oauth2/create-client`
    // endpoint (session-required, auto-stamps `user_id` from the session).
    //
    // Why this wrapper exists: the Account-app action surfaces a
    // user-friendly textarea for "Redirect URLs" (one per line), but
    // better-auth's Zod body schema requires `redirect_uris: string[]`.
    // The metadata-driven action runner POSTs param values verbatim, so
    // without a translation layer the upstream call fails validation with
    // `Invalid input: expected array, received string`. We split the
    // textarea on newlines, trim, drop empties, and forward to
    // `createOAuthClient` so the row gets persisted with the caller's
    // user_id and shows up in the `mine` listView.
    //
    // Upstream alternative would be enabling `allowDynamicClientRegistration`
    // on `/oauth2/register`, but DCR has additional security implications
    // (rate limiting, scope restriction) we don't want to enable broadly
    // just to fix UX. Keeping the wrapper scoped to the self-service flow.
    rawApp.post(`${basePath}/sys-oauth-application/register`, async (c: any) => {
      try {
        // [#24032] Same read as toggle-disabled: refused, never read as `{}`.
        const reading = await readJsonRequestBody(c.req.raw);
        if (!reading.ok) {
          return c.json({ success: false, error: { code: 'INVALID_REQUEST', message: reading.message } }, 400);
        }
        const body: any = reading.body;

        const name: unknown = body?.name;
        const redirectUrlsInput: unknown = body?.redirectURLs;
        const type: unknown = body?.type;

        if (typeof name !== 'string' || name.trim().length === 0) {
          return c.json({ success: false, error: { code: 'INVALID_REQUEST', message: 'name is required' } }, 400);
        }
        if (typeof redirectUrlsInput !== 'string' || redirectUrlsInput.trim().length === 0) {
          return c.json({ success: false, error: { code: 'INVALID_REQUEST', message: 'redirectURLs is required' } }, 400);
        }

        const redirectUris = redirectUrlsInput
          .split(/[\r\n]+/)
          .map((line) => line.trim())
          .filter((line) => line.length > 0);
        if (redirectUris.length === 0) {
          return c.json({ success: false, error: { code: 'INVALID_REQUEST', message: 'redirectURLs must contain at least one URL' } }, 400);
        }

        // [#24773] The form's Application Type reaches the provider as the OIDC
        // `application_type` its `/oauth2/create-client` body declares (`web` |
        // `native`). It was forwarded as `type`, a member that body does not
        // declare, so the provider stripped it and judged and stored every
        // client as `web`: a `native` client could not register the RFC 8252
        // loopback redirect URI the provider grants native clients. The
        // provider's own rule is the one authority — `web` needs https on a
        // non-loopback host, `native` may use http only on exactly `localhost`,
        // `127.0.0.1` or `[::1]` — and nothing here re-judges a URI.
        //
        // The door accepts exactly those two types. Any other value present in
        // the body — the form's former `user-agent-based` and `public`, which
        // have no `application_type`, an empty string, a non-string, anything
        // else — is refused here with the route's own 400 `INVALID_REQUEST`,
        // before the provider is called, so nothing is stored. It is never
        // registered as `web` and never mapped to another type: that silent
        // substitution issued a confidential web client, with a secret, for a
        // request that asked for something else. The refusal ships in 18.x as
        // a breaking minor (the standing post-GA rule as amended, #6015
        // `6303865025`). No type at all — absent, or JSON `null` — is the
        // provider's own default, `web`, and is unchanged.
        let applicationType: 'web' | 'native' = 'web';
        if (type === 'web' || type === 'native') {
          applicationType = type;
        } else if (type !== undefined && type !== null) {
          const shown =
            typeof type === 'string'
              ? JSON.stringify(type.length > 64 ? `${type.slice(0, 64)}…` : type)
              : `(${typeof type})`;
          return c.json({
            success: false,
            error: {
              code: 'INVALID_REQUEST',
              message:
                `type ${shown} is not an application type the OAuth provider judges: send 'web' or 'native', ` +
                "or no type for 'web'. Choose 'native' for an http://localhost, http://127.0.0.1 or http://[::1] " +
                "redirect URI; 'web' needs https on a host that is not a loopback address.",
            },
          }, 400);
        }

        const authApi: any = await this.authManager!.getApi();
        if (!authApi?.createOAuthClient) {
          return c.json({ success: false, error: { code: 'SERVICE_UNAVAILABLE', message: 'OIDC provider is not enabled' } }, 503);
        }

        // Forward request headers so better-auth can resolve the caller's
        // session (sessionMiddleware on /oauth2/create-client). Without
        // the session the row would lack `user_id` and never appear in
        // the My Applications view. [#22398] That read is in-process, so it
        // takes the `getSession` reader's input: a cookie request reads
        // without renewal (its cookie would be staged on a response nobody
        // sends); a bearer-only one renews as before.
        let result: any;
        try {
          result = await authApi.createOAuthClient({
            body: {
              client_name: name.trim(),
              redirect_uris: redirectUris,
              application_type: applicationType,
            },
            ...inProcessSessionReadInput(c.req.raw.headers),
          });
        } catch (err: any) {
          // [#24773] Answer the status the refusal DECLARED, by the repo's one
          // rule for a thrown error's status (`resolveThrownHttpError`).
          // better-call's `APIError` — every refusal better-auth raises —
          // carries its status twice: as the NUMBER `statusCode` (400) and as
          // the NAME `status` ('BAD_REQUEST'). This door used to read only a
          // numeric `status`, so each named refusal answered 500 — an
          // `invalid_redirect_uri` redirect URI, a request with no session
          // (`UNAUTHORIZED`) — while the body-schema `ValidationError`, whose
          // `status` is the number 400, answered 400 from the same door. A
          // throw that declares no status is a server fault and stays 500.
          const { status } = resolveThrownHttpError(err, 500);
          // better-auth's `body.error` is an arbitrary upstream string, so it
          // cannot be `error.code` — that field is a closed set (ADR-0112) and
          // an unbounded source defeats it. Keep the code ours and carry the
          // upstream discriminator in `details` where it stays inspectable.
          const upstream = typeof err?.body?.error === 'string' ? err.body.error : undefined;
          const message = err?.body?.error_description ?? err?.message ?? 'Unable to register OAuth client';
          return c.json({
            success: false,
            error: {
              code: 'OAUTH_REGISTER_FAILED',
              message,
              ...(upstream ? { details: { upstreamError: upstream } } : {}),
            },
          }, status);
        }

        // Mirror the response shape consumed by the action's resultDialog
        // (`client.client_id`, `client.client_secret`).
        return c.json({ success: true, data: { client: result } });
      } catch (error) {
        const err = error instanceof Error ? error : new Error(String(error));
        ctx.logger.error('[AuthPlugin] sys-oauth-application/register failed', err);
        return c.json({ success: false, error: { code: 'INTERNAL_ERROR', message: err.message } }, 500);
      }
    });

    // ────────────────────────────────────────────────────────────────────
    // Revoke ONE session, named by its `sys_session.id` — the door behind the
    // `sys_session` Revoke Session row action (Setup → Sessions, Account →
    // Active Sessions). The server resolves the session from the id, so the
    // session token never travels to or from the console. The owner lane
    // re-dispatches to better-auth's own `/revoke-session`; another user's
    // session is revocable by a platform administrator only (ADR-0068 D2
    // judge). Same family as `sys-oauth-application/register` above: an
    // object-scoped mount outside `/admin/`, because it admits the owner.
    // See `sys-session-revoke.ts` for the lanes and refusals.
    //
    // [#24877] The owner lane's re-dispatch goes through the manager slice's
    // `handleRequest`, so the slice handed over is the manager's own seams
    // with `handleRequest` bound to this request's transport
    // (`handleWithTransportOf` above) — the same handler every other bridge
    // re-dispatches through.
    rawApp.post(`${basePath}/sys-session/revoke`, async (c: any) => {
      try {
        const manager = this.authManager!;
        const { status, body } = await runSysSessionRevoke(
          sysSessionRevokeDepsFor(
            {
              getApi: () => manager.getApi(),
              getAuthContext: () => manager.getAuthContext(),
              getDataEngine: () => manager.getDataEngine(),
              handleRequest: handleWithTransportOf(c),
            },
            basePath,
          ),
          c.req.raw,
        );
        return c.json(body, status as any);
      } catch (error) {
        const err = error instanceof Error ? error : new Error(String(error));
        ctx.logger.error('[AuthPlugin] sys-session/revoke failed', err);
        return c.json({ success: false, error: { code: 'INTERNAL_ERROR', message: err.message } }, 500);
      }
    });

    // ────────────────────────────────────────────────────────────────────
    // Self-service resend of the email-verification link. SHADOWS better-auth's
    // native `/send-verification-email` (registered before the catch-all below).
    //
    // The stock route REQUIRES `{ email }` in the body, but the `sys_user`
    // `resend_verification_email` action — the record-header button, the
    // "email unverified" record alert, and the record-section quick action —
    // fires with an EMPTY body (no dialog, and the alert `action` reference
    // can't carry params). That bounced with `[body.email] ... received
    // undefined`, breaking every resend affordance. This wrapper defaults the
    // address to the caller's own session email when the body omits it, then
    // re-dispatches through the real route (via handleRequest, which bypasses
    // this wrapper — no recursion). An explicit `email` passes through
    // untouched, so the admin / verify-screen path is unchanged.
    rawApp.post(`${basePath}/send-verification-email`, async (c: any) => {
      try {
        const { status, body } = await runResendVerificationEmail(
          handleWithTransportOf(c),
          c.req.raw,
        );
        return c.json(body, status);
      } catch (error) {
        const err = error instanceof Error ? error : new Error(String(error));
        ctx.logger.error('[AuthPlugin] send-verification-email failed', err);
        return c.json({ success: false, error: { code: 'INTERNAL_ERROR', message: err.message } }, 500);
      }
    });

    // Register wildcard route to forward all auth requests to better-auth.
    // better-auth is configured with basePath matching our route prefix, so we
    // forward the original request directly — no path rewriting needed.
    //
    // [#4088] This catch-all owns the whole auth namespace, and it used to be
    // TERMINAL: it returned better-auth's response unconditionally, including
    // the 404 better-auth produces for a path it does not implement. Any OTHER
    // plugin's route under `${basePath}/*` was therefore reachable only if it
    // happened to register FIRST — Hono runs handlers matching a path in
    // registration order and the first to return a Response wins. That made a
    // load-bearing surface depend on `kernel.use()` order:
    // `plugin-hono-server` mounts `/auth/me/permissions` and
    // `/auth/me/localization` from its own `kernel:ready` hook, the console's
    // entire permission layer reads the former, and `core`'s auth gate
    // allow-lists the latter — all of it silently 404s if AuthPlugin is used
    // before HonoServerPlugin. Same class as #2567 and #4018: an invariant held
    // by ordering luck rather than enforced.
    //
    // So a 404 now means "better-auth does not own this path" and we yield to
    // whatever else matched, in either registration order. Deliberately narrow:
    // 401/403 are real better-auth answers, not disclaimers of ownership, and
    // when nothing downstream answers we return better-auth's own 404 verbatim
    // so the wire shape for a genuinely unclaimed auth path is unchanged.
    // Precedence still favours the namespace owner — better-auth wins every
    // path it implements, and only its leftovers are up for grabs.
    rawApp.all(`${basePath}/*`, async (c: any, next: any) => {
      try {
        // Forward the original request to better-auth handler, with the
        // transport's peer address: `handleRequest` establishes the client
        // address from it by the same trust rule the D5 gate above judged
        // with, and the D7 login audit stamps that address.
        const response = await this.authManager!.handleRequest(c.req.raw, transportOf(c));

        // [#15417] Yield only a 404 that DISCLAIMS OWNERSHIP. `ownsRoute` asks
        // better-auth's live `auth.api` — the same seam the route ledger and the
        // `/admin/` dogfood sweep read — whether its own router serves this
        // path; see `better-auth-route-ownership.ts` for the mechanism and the
        // measurement. A 404 from a path it DOES serve is its answer (a
        // switched-off capability such as `delete-user`, a bad token, an
        // unknown id) and must reach the caller, exactly like the
        // 401/403 the block below already refuses to yield. Measured with the
        // shipped handler on a real Hono app: with one broad downstream mount
        // in the chain — the shape a composition adds — such an answer used to
        // come back `200 {}`, which is the silent-success shape #15417 is
        // about. ⛔ The mount is untouched and still claims `${basePath}/*`;
        // what narrowed is which 404 may be handed on.
        if (response.status === 404 && !(await this.authManager!.ownsRoute(c.req.raw))) {
          await next();
          // A non-404 downstream means something else answered — hand that back.
          // NOT `c.finalized`: reaching the end of the chain with nothing
          // matched runs Hono's notFound handler, which sets a response and
          // flips `finalized` to true, so it cannot tell "someone answered"
          // from "nobody did". Status can. The one thing this trades away is a
          // downstream route's own 404 BODY (better-auth's 404 is returned in
          // its place); the status is identical either way, and no route under
          // this prefix answers 404 today — `/auth/me/*` answer 200 with an
          // `authenticated: false` payload for an anonymous caller.
          if (c.res && c.res.status !== 404) return;
          // Assign, don't `return`: the IP-gate `rawApp.use()` above puts a
          // middleware in this chain, and Hono's compose only assigns a
          // handler's returned Response while `c.finalized` is false. The
          // notFound above already flipped it, so a `return response` here is
          // silently dropped and the caller gets Hono's "404 Not Found" text
          // instead of better-auth's JSON. Setting `c.res` is not subject to
          // that condition.
          c.res = response;
          return;
        }

        // better-auth catches internal errors and returns error Responses
        // without throwing, so the catch block below would never trigger.
        // We proactively log server errors here for observability.
        if (response.status >= 500) {
          try {
            const body = await response.clone().text();
            ctx.logger.error('[AuthPlugin] better-auth returned server error', new Error(`HTTP ${response.status}: ${body}`));
          } catch {
            ctx.logger.error('[AuthPlugin] better-auth returned server error', new Error(`HTTP ${response.status}: (unable to read body)`));
          }
        }

        // Public-cache JWKS: it's static JSON that only changes when the
        // signing key rotates (default ~30 days). better-auth doesn't set
        // any Cache-Control header, so every relying party currently
        // re-fetches it on every JWT verification (≈700 ms warm against a
        // Container DO + Neon). Add a conservative public cache so CF's
        // edge can short-circuit repeated fetches. The 5-min freshness +
        // 24 h SWR window is well inside better-auth's default rotation
        // and matches what most IdPs publish (Auth0, Cognito, Google).
        try {
          const url = c.req.url as string;
          if (response.ok && /\/jwks(\?|$)/.test(url)) {
            const existing = response.headers.get('cache-control');
            if (!existing) {
              response.headers.set(
                'cache-control',
                'public, max-age=300, stale-while-revalidate=86400',
              );
            }
          }
        } catch { /* best-effort header annotation */ }

        return response;
      } catch (error) {
        const err = error instanceof Error ? error : new Error(String(error));
        ctx.logger.error('Auth request error:', err);
        
        // Return error response
        return new Response(
          JSON.stringify({
            success: false,
            error: err.message,
          }),
          {
            status: 500,
            headers: { 'Content-Type': 'application/json' },
          }
        );
      }
    });

    // OIDC / OAuth 2.0 Authorization Server Metadata (RFC 8414) and
    // OpenID Connect Discovery 1.0 require the well-known documents to be
    // served from the **root** of the issuer URL — not under our auth
    // basePath. `@better-auth/oauth-provider` ships dedicated helpers for
    // this case (`oauthProviderAuthServerMetadata` /
    // `oauthProviderOpenIdConfigMetadata`) which we mount here so external
    // OIDC clients can discover the IdP at the canonical paths.
    //
    // Shared decision point with `AuthManager.buildPluginList()`
    // (`resolveOidcProviderEnabled`: env override → config → follows
    // OS_MCP_SERVER_ENABLED) — without this the discovery routes would not
    // mount when an operator flipped the env var on without editing the
    // config file, leaving external OIDC/MCP clients unable to discover
    // the authorization server.
    //
    // [#21078] Called SYNCHRONOUSLY, like every route above: the discovery
    // routes are on the router before this `kernel:ready` hook returns, so
    // they land ahead of `kernel:listening` (the phase that opens the socket)
    // and ahead of the first request. A throw here — a route that cannot
    // mount — propagates out of the hook and fails the boot, the same as the
    // routes above; ⛔ never `void` it, and ⛔ never catch-and-log it.
    const oidcEnabled = resolveOidcProviderEnabled(this.options.plugins);
    if (oidcEnabled) {
      this.registerOidcDiscoveryRoutes(rawApp, ctx);
    }

    ctx.logger.info(`Auth routes registered: All requests under ${basePath}/* forwarded to better-auth`);
  }

  /**
   * Mount the OIDC / OAuth 2.0 well-known discovery documents at the root
   * URL. Required by RFC 8414 §3 and OpenID Connect Discovery 1.0 §4 — the
   * documents must live at `/.well-known/{oauth-authorization-server,openid-configuration}`
   * relative to the issuer, not under the auth basePath.
   *
   * ## [#21078] Every route is mounted HERE, synchronously — never after an await
   *
   * Hono builds its route matcher on the first request it matches, and from
   * then on `app.get(...)` throws `Can not add a route since the matcher is
   * already built`. This method used to `await` the better-auth instance
   * first and mount after it, and its caller dispatched it with `void`, so the
   * mounts landed whenever that build finished — after `kernel:listening`
   * whenever the build outlasted the rest of the boot. A first request inside
   * that window (a readiness probe is the likely one) built the matcher, the
   * late mount threw, the throw was caught and logged, and both discovery
   * doors answered 404 for the life of the process.
   *
   * So the work is split by what is knowable WHEN:
   *
   *   - CONFIG-level — known at mount, decided here: whether discovery is on
   *     at all (the caller's `resolveOidcProviderEnabled`), the issuer and its
   *     transport posture, the base path the RFC 8414 §3.1 alias inserts, and
   *     whether the RFC 9728 protected-resource documents go up (the MCP
   *     surface env switch and `isMcpOAuthEnabled()`, both configuration
   *     reads). Every route is put on the router before this returns.
   *   - INSTANCE-level — known only once better-auth is built: whether the
   *     oauthProvider plugin actually initialised (`getDegradedAuthFeatures`),
   *     and the instance the vendor's document builders read. Each handler
   *     resolves that per request, through `getAuthInstance()` — single-flight
   *     and memoised in `AuthManager`, so a request costs a cached promise, and
   *     a rebuild after a settings patch is served from the live instance
   *     rather than the one that happened to exist at boot.
   *
   * ⛔ No `rawApp.get` after an `await`, in this method or anywhere it calls.
   */
  private registerOidcDiscoveryRoutes(rawApp: any, ctx: PluginContext): void {
    const manager = this.authManager!;

    // The oauthProvider plugin may have been skipped by the optional-plugin
    // isolation in AuthManager.buildPluginList (a failing optional plugin no
    // longer fails the whole instance — the 15.1.0 lesson). Advertising
    // .well-known discovery documents for an IdP whose endpoints are not
    // mounted would send every external client into 404s. That is an
    // INSTANCE-level fact, so it cannot decide whether a route is mounted
    // (the routes are mounted before the instance exists); it decides how a
    // mounted route ANSWERS — `next()`, which is exactly the answer the path
    // gave when it was not mounted at all: whatever else matches, else the
    // server's not-found response.
    const degradedOidc = () =>
      manager.getDegradedAuthFeatures().find((d) => d.feature === 'oidcProvider');

    // ── Plain-HTTP OAuth notices (maintainer ruling 2026-09-21; how the
    //    ruled sentence is carried: ruling batch #210 item 5) ───────────
    //
    // The ruled sentence, verbatim, is 「OAuth 未加密:仅限可信内网」 — item ④
    // of the #19489 ruling. Ruling batch #210 item 5 then settled HOW it is
    // carried: the emitted line is ENGLISH, the repository's convention for
    // code artefacts, and the maintainer's sentence is kept here in this
    // comment, cited — read as the line's MEANING, not as its literal
    // encoding. ⛔ No CJK executable string enters `packages/*/src`, and
    // ⛔ no bilingual line. Neither ruling amends the language convention.
    //
    // ⚠️ Eligibility decides WHICH sentence is emitted, never WHETHER one is
    // (ruling batch #210 item 5, D1). The two are different sentences with
    // opposite meanings, and neither may be reached for the other's case:
    //
    //   ACCEPTED origin (loopback / private / link-local) — an unencrypted
    //     authorization server is a SUPPORTED posture here (intranet
    //     installs, a dev bind on a LAN address) rather than an impossible
    //     one, so the line says the transport rule accepted this origin, and
    //     why.
    //   REFUSED origin (a PUBLIC host) — the OAuth track is dark, so a line
    //     saying the transport is accepted would be FALSE of that deployment.
    //     Silence is worse still: the three `.well-known` discovery documents
    //     mounted below go up regardless of transport, so a public plain-HTTP
    //     boot publishes its authorization-server metadata in the clear. That
    //     is the loudest-needed posture and it used to be the QUIETEST — the
    //     `OAuth track is NOT live` warning further down sits INSIDE the
    //     MCP-surface condition, so a public plain-HTTP boot with
    //     `OS_MCP_SERVER_ENABLED=false` emitted no line at all. Which is why
    //     this branch sits HERE, beside its sibling, and ⛔ not in there.
    //
    // ⛔ Whether those discovery routes should be mounted at all on a refused
    // origin is pre-existing behaviour that neither ruling touched, and it is
    // not decided at this call site.
    //
    // Neither line is gated by a configuration key or an environment
    // variable, each is emitted once at mount, and neither is emitted under
    // TLS. Both read off the PUBLISHED issuer — the authorization-server
    // identity these documents are about — so each names the exact URL a
    // client is sent to rather than a value only this method can see.
    //
    // [#21078] Both are CONFIG-level facts — the issuer is configuration — so
    // they are emitted here, at mount, before the instance exists. They used
    // to sit behind the degraded-oauthProvider early return; a deployment
    // with that plugin degraded now also gets its own boot-time ERROR line
    // below, which says the documents are NOT served, and that line is the
    // one that decides what a client meets.
    const authIssuer = manager.getAuthIssuer();
    const servedOverPlainHttp = /^http:\/\//i.test(authIssuer);
    if (servedOverPlainHttp && isOAuthEligibleBaseUrl(authIssuer)) {
      // [#22073] The LEVEL follows the host; the sentence does not. On a
      // loopback issuer — every `os dev` / `os start` on localhost — nothing
      // crosses a network at all, so the line is `info`: the same sentence,
      // still emitted on every accepted plain-HTTP boot (D1 above holds), and
      // no longer a warning about the expected local state on every boot. A
      // private or link-local issuer is reachable from its network and keeps
      // `warn`. Every OAuth origin this deployment publishes derives from the
      // one canonical origin the issuer carries, so the issuer's host is the
      // whole question.
      const notice =
        'OAuth is served UNENCRYPTED: this deployment publishes its ' +
        `authorization server over plain HTTP (${authIssuer}), so authorization codes, access tokens ` +
        'and bearer headers cross the network in the clear and anything that can observe it can ' +
        'replay them. The transport rule accepts this origin only because the host is loopback or a ' +
        'private / link-local address; put TLS in front of any deployment reachable from a public ' +
        'network, where the same origin is refused outright.';
      if (isLoopbackIssuer(authIssuer)) ctx.logger.info(notice);
      else ctx.logger.warn(notice);
    } else if (servedOverPlainHttp) {
      ctx.logger.warn(
        'OAuth discovery is served over PUBLIC plain HTTP: this deployment publishes its ' +
          'authorization-server metadata (/.well-known/oauth-authorization-server and ' +
          `/.well-known/openid-configuration, issuer ${authIssuer}) over an unencrypted public ` +
          'origin, where anything on the network path can read and rewrite it. The MCP OAuth track ' +
          'is DISABLED on this deployment — the transport rule refuses a public plain-HTTP origin, ' +
          'so /api/v1/mcp stays API-key-only and no protected-resource metadata is advertised — but ' +
          'the discovery documents above are mounted regardless of transport and are reachable now. ' +
          'TLS is the remedy: serve this deployment over https. No configuration key and no ' +
          'environment variable changes either half.',
      );
    }

    // INSTANCE-level: the vendor's document builders, bound to the live
    // instance. `null` = the oauthProvider plugin is degraded on that
    // instance, so the documents are not served (see `degradedOidc` above).
    // A rejection (the instance cannot be built) is NOT caught here: a
    // request meets it as the server's error response, and the next request
    // retries the build — `getOrCreateAuth` drops a failed build.
    type DocumentHandler = (req: Request) => Promise<Response>;
    const resolveDiscoveryDocuments = async (): Promise<
      { authServer: DocumentHandler; openidConfig: DocumentHandler } | null
    > => {
      const auth = await manager.getAuthInstance();
      if (degradedOidc()) return null;
      const { oauthProviderAuthServerMetadata, oauthProviderOpenIdConfigMetadata } = await import(
        '@better-auth/oauth-provider'
      );
      return {
        authServer: oauthProviderAuthServerMetadata(auth as any),
        openidConfig: oauthProviderOpenIdConfigMetadata(auth as any),
      };
    };

    // Cache-Control for OIDC discovery docs. These describe stable issuer
    // configuration (endpoints, supported scopes, signing algs); they
    // change only on app redeploy. CF edge can short-circuit repeated
    // fetches and dramatically cut SSO first-call latency.
    const DISCOVERY_CACHE = 'public, max-age=300, stale-while-revalidate=86400';
    const withDiscoveryCache = async (handler: (req: Request) => Promise<Response> | Response, req: Request): Promise<Response> => {
      const resp = await handler(req);
      try {
        if (resp.ok && !resp.headers.get('cache-control')) {
          resp.headers.set('cache-control', DISCOVERY_CACHE);
        }
      } catch { /* best-effort */ }
      return resp;
    };

    // One handler shape for every document route: resolve the instance-level
    // half for THIS request, then serve — or hand on exactly as an unmounted
    // path would when the provider is degraded.
    const serveDocument =
      (pick: (docs: { authServer: DocumentHandler; openidConfig: DocumentHandler }) => DocumentHandler) =>
      async (c: any, next: () => Promise<void>) => {
        const docs = await resolveDiscoveryDocuments();
        if (!docs) return next();
        return withDiscoveryCache(pick(docs), c.req.raw);
      };

    rawApp.get('/.well-known/oauth-authorization-server', serveDocument((d) => d.authServer));
    rawApp.get('/.well-known/openid-configuration', serveDocument((d) => d.openidConfig));

    // RFC 8414 §3.1 path-insertion variant. Our issuer identifier carries a
    // path component (`<origin>/api/v1/auth`), so spec-conforming clients
    // (including every MCP client bootstrapping from protected-resource
    // metadata) request `/.well-known/oauth-authorization-server/api/v1/auth`
    // — alias it to the same document.
    const basePath = (this.options.basePath ?? DEFAULT_AUTH_BASE_PATH).replace(/\/$/, '');
    rawApp.get(`/.well-known/oauth-authorization-server${basePath}`, serveDocument((d) => d.authServer));

    // ── MCP protected-resource metadata (RFC 9728, #2698) ──────────────
    // `/api/v1/mcp` is an OAuth 2.1 protected resource; its metadata points
    // clients at THIS deployment's embedded authorization server. Mounted
    // only when the MCP OAuth track is live (MCP surface on + AS on +
    // transport rule satisfied — TLS, or plain HTTP on a loopback / private
    // / link-local host): when it is off, nothing is advertised and the
    // endpoint stays API-key-only, fail-closed.
    //
    // [#21078] Mounted on the CONFIG-level decision (the env switch and
    // `isMcpOAuthEnabled()` are both configuration reads). The document points
    // clients at the authorization server above, so it carries the same
    // INSTANCE-level gate: a degraded oauthProvider hands the request on,
    // exactly as the unmounted path used to answer.
    if (readMcpServerEnabledEnv() && typeof manager.isMcpOAuthEnabled === 'function') {
      if (manager.isMcpOAuthEnabled()) {
        const prmHandler = async (_c: unknown, next: () => Promise<void>) => {
          await manager.getAuthInstance();
          if (degradedOidc()) return next();
          const body = JSON.stringify(manager.getMcpProtectedResourceMetadata());
          return new Response(body, {
            status: 200,
            headers: { 'content-type': 'application/json', 'cache-control': DISCOVERY_CACHE },
          });
        };
        const mcpPath = new URL(manager.getMcpResourceUrl()).pathname; // e.g. /api/v1/mcp
        rawApp.get('/.well-known/oauth-protected-resource', prmHandler);
        // RFC 9728 §3.1 path-insertion variant for the resource's own path.
        rawApp.get(`/.well-known/oauth-protected-resource${mcpPath}`, prmHandler);
        ctx.logger.info(
          `MCP protected-resource metadata mounted at /.well-known/oauth-protected-resource (resource: ${mcpPath})`,
        );
      } else {
        ctx.logger.warn(
          'MCP server is enabled but the OAuth track is NOT live (base URL fails the OAuth 2.1 transport ' +
            'rule — https is required on a PUBLIC host; plain HTTP is accepted only on a loopback or ' +
            'private / link-local address, and a non-IP hostname is not one). /api/v1/mcp stays ' +
            'API-key-only; no OAuth metadata is advertised.',
        );
      }
    }

    ctx.logger.info(
      'OIDC discovery endpoints mounted at /.well-known/{oauth-authorization-server,openid-configuration}',
    );

    // ── Boot-time preparation — mounts NOTHING ──────────────────────────
    //
    // Every route is already on the router above. This runs the SAME
    // instance-level resolution a request runs, once, at boot, for the three
    // things the old await-then-mount shape did at boot and that are kept:
    //
    //   1. the better-auth instance is built in the background at boot, not
    //      by whichever request first needs it — moving that build (and the
    //      vendor plugins' own `init` writes) into the serving window is a
    //      separate change, not this one;
    //   2. a degraded oauthProvider is reported at boot, once, at ERROR;
    //   3. documents that cannot be built from the instance are reported at
    //      boot, at ERROR, under the line's established opening words —
    //      `scripts/publish-smoke.sh` asserts them BY NAME in its boot window
    //      (SMOKE_BOOT_ERROR_PATTERN), so they are a grep anchor and are kept
    //      verbatim at the front of the line.
    //
    // Not awaited — nothing above depends on it and nothing here can add a
    // route — and not swallowed: both outcomes are logged, and a request that
    // meets the same failure gets the server's error response.
    void resolveDiscoveryDocuments().then(
      (docs) => {
        const degraded = docs ? undefined : degradedOidc();
        if (!degraded) return;
        ctx.logger.error(
          'OIDC provider is configured but its better-auth plugin failed to initialize, so the ' +
            '/.well-known discovery documents are NOT served: those paths answer as if they were not ' +
            'mounted. External SSO/MCP clients cannot use this deployment as an IdP until the ' +
            `underlying error is fixed: ${degraded.error}`,
        );
      },
      (error) => {
        ctx.logger.error(
          'Failed to register OIDC discovery routes: the /.well-known paths are mounted, but the auth ' +
            'instance their documents are built from could not be prepared, so every discovery request ' +
            'answers an error until it can be',
          error as Error,
        );
      },
    );
  }
}