@nestjs-kit/better-auth 0.0.0-stage → 2.0.0

package/dist/auth-contracts-Brh_Qko9.d.cts

@@ -0,0 +1,1654 @@
+import { IncomingHttpHeaders, IncomingMessage } from "node:http";
+import { CallHandler, CanActivate, DynamicModule, ExecutionContext, InjectionToken, IntrinsicException, Logger, LoggerService, ModuleMetadata, NestInterceptor, OptionalFactoryDependency, Provider, Type } from "@nestjs/common";
+import { AbstractHttpAdapter, DiscoveryService, HttpAdapterHost, ModuleRef, Reflector } from "@nestjs/core";
+import { HookEndpointContext } from "better-auth";
+import { Observable } from "rxjs";
+//#region src/auth-errors.d.ts
+type AuthErrorCode = "UNAUTHENTICATED" | "FORBIDDEN" | "RATE_LIMITED";
+/** A transport-neutral denial. Only transports make it throwable. */
+interface AuthFailure {
+  readonly status: 401 | 403 | 429;
+  readonly code: AuthErrorCode;
+  readonly reason?: string;
+  readonly message: string;
+  readonly challenge?: string;
+  readonly headers?: Headers;
+}
+interface AuthErrorBody {
+  statusCode: 401 | 403 | 429;
+  error: string;
+  code: AuthErrorCode;
+  reason?: string;
+  message: string;
+}
+interface AuthGraphqlExtensions {
+  code: AuthErrorCode | "INTERNAL_SERVER_ERROR";
+  reason?: string;
+  statusCode: number;
+}
+interface AuthTransportErrorPayload {
+  status: "error";
+  statusCode: number;
+  code: AuthErrorCode;
+  reason?: string;
+  message: string;
+}
+interface ErrorMappingOptions {
+  map?: (failure: AuthFailure, context: ExecutionContext, transport: string) => unknown;
+  exposeRawCause?: boolean;
+}
+declare function isAuthFailure(value: unknown): value is AuthFailure;
+declare function isInfrastructureError(value: unknown): value is BetterAuthInfrastructureError;
+declare function isConfigurationError(value: unknown): value is BetterAuthConfigurationError;
+declare function rejection(input: {
+  status: 401 | 403 | 429;
+  reason?: string;
+  message?: string;
+  challenge?: string;
+  retryAfterSeconds?: number;
+}): AuthFailure;
+declare const AuthFailures: {
+  unauthenticated(message?: string): AuthFailure;
+  rejected: typeof rejection;
+  forbidden(reason: string, message?: string): AuthFailure;
+  fromAPIError(error: unknown): AuthFailure | null;
+};
+declare class BetterAuthConfigurationError extends Error {
+  readonly code: string;
+  readonly detail: string;
+  readonly site?: string;
+  readonly hint?: string;
+  readonly phase: "boot" | "request";
+  readonly extensions: {
+    readonly code: "INTERNAL_SERVER_ERROR";
+    readonly reason: "AUTH_MISCONFIGURED";
+    readonly statusCode: 500;
+  };
+  readonly issues?: readonly BetterAuthConfigurationError[];
+  constructor(code: string, detail: string, hint?: string);
+  static atRequest(code: string, detail: string, options?: {
+    site?: string;
+    hint?: string;
+  }): BetterAuthConfigurationError;
+}
+declare class BetterAuthInfrastructureError extends Error {
+  readonly cause: Error;
+  readonly extensions: {
+    readonly code: "INTERNAL_SERVER_ERROR";
+    readonly reason: "AUTH_UNAVAILABLE";
+    readonly statusCode: 500;
+  };
+  constructor(cause: unknown, options?: {
+    secrets?: readonly string[];
+  });
+}
+declare function getRawCause(error: BetterAuthInfrastructureError): unknown;
+//#endregion
+//#region src/auth-tokens.d.ts
+declare function getBetterAuthInstanceToken(alias?: string): string;
+declare function getBetterAuthOptionsToken(alias?: string): string;
+declare function getBetterAuthServiceToken(alias?: string): string;
+declare function getBetterAuthHandleToken(alias?: string): string;
+declare const GUARD_CORE: unique symbol;
+declare const SCOPE_CORE: unique symbol;
+declare const PRINCIPAL_RESOLVER: unique symbol;
+declare const POLICY_INVOKER: unique symbol;
+declare const ACCESS_METADATA: unique symbol;
+declare const ACCEPT_PRINCIPALS_METADATA: unique symbol;
+declare const SKIP_DEFAULT_REQUIREMENTS_METADATA: unique symbol;
+declare const AUTH_INSTANCE_METADATA: unique symbol;
+declare const FORWARD_COOKIES_METADATA: unique symbol;
+declare const SKIP_ORIGIN_CHECK_METADATA: unique symbol;
+declare const AUTH_ENHANCER: unique symbol;
+/** Connection-time WebSocket authentication, provided by the socket.io and ws transport definitions. */
+declare const WS_CONNECTION_AUTH: unique symbol;
+//#endregion
+//#region src/auth-module.d.ts
+declare class BetterAuthModule {
+  static forRoot<A extends AuthLike = RegisteredAuth>(options: BetterAuthModuleOptions<A> & BetterAuthAppOptions & {
+    name?: "default";
+  } & DefaultInstanceCheck<A>): DynamicModule;
+  static forRoot<A extends AuthLike>(options: BetterAuthModuleOptions<A> & {
+    name: string;
+  } & NoAppOptions): DynamicModule;
+  static forRootAsync<A extends AuthLike = RegisteredAuth>(options: BetterAuthModuleAsyncOptions<A> & BetterAuthAppOptions & {
+    name?: "default";
+  }): DynamicModule;
+  static forRootAsync<A extends AuthLike>(options: BetterAuthModuleAsyncOptions<A> & {
+    name: string;
+  } & NoAppOptions): DynamicModule;
+}
+//#endregion
+//#region src/bridge-protocol.d.ts
+declare const EXTENSION_DEFINITION: unique symbol;
+declare const UPGRADE_REQUEST: unique symbol;
+interface BridgeHandle {
+  readonly protocol: 4;
+  readonly clientIpHeader: string | null;
+  /** 'unbound' until the first bind(); 'bound' while an application's hooks are registered; 'closed' after its shutdown, hooks still registered. */
+  readonly state: "unbound" | "bound" | "closed";
+  /** Endpoint dispatches and database-hook dispatches (writes) seen before the first binding, reset by every bind() (B26). */
+  readonly unboundDispatches: number;
+  /**
+   * Registers the application's hooks and returns close(), which the kernel calls in onApplicationShutdown: a closed binding keeps
+   * dispatching until another application binds (§10.6). A second bind() from the same owner for the same instance is a no-op that
+   * returns the existing registration (NestMicroservice.init() runs lifecycle hooks twice); from the same owner for another instance it
+   * throws PLUGIN_SHARED_BETWEEN_INSTANCES (B03). Throws INSTANCE_ALREADY_BOUND if another bootstrapped application is bound; takes over
+   * a never-bootstrapped one (reported, B06) and a closed one (silently). A never-bootstrapped binding it takes over becomes
+   * 'displaced': an application whose init() was still running when another bound fails in onApplicationBootstrap (B06).
+   */
+  bind(binding: BridgeBinding): {
+    close(): void;
+    tookOverFrom?: string;
+  };
+  /** true when an endpoint returned `value` (an object) in a non-router dispatch observed while bound; false for before-hook short-circuits (LEAD-V37). */
+  producedByEndpoint(value: unknown): boolean;
+}
+interface BridgeBinding {
+  /** The application: compared by identity for the same-owner no-op; `description` goes into the B06 message. */
+  readonly owner: {
+    readonly description: string;
+  };
+  /** The instance this plugin object serves; one plugin object serves one instance (B03). */
+  readonly instance: string;
+  /**
+   * 'initialized' at bind; the kernel sets 'bootstrapped' in onApplicationBootstrap; close() sets 'closed'; bind() of another
+   * application sets 'displaced' on an 'initialized' binding it takes over.
+   */
+  state: "initialized" | "bootstrapped" | "closed" | "displaced";
+  /** View of the kernel's RequestScope; the plugin never owns an AsyncLocalStorage. [C] */
+  current(): ScopeView | undefined;
+  /** Credential header names declared by the instance's principal sources (credential matching, §7.5). */
+  readonly credentialHeaders: readonly string[];
+  readonly before: readonly CompiledHook[];
+  readonly after: readonly CompiledHook[];
+  readonly database: Readonly<{ [E in DatabaseHookTarget]: {
+    readonly before: readonly DatabaseHookMethod<E, "before">[];
+    readonly after: readonly DatabaseHookMethod<E, "after">[];
+  }; }>;
+  /** Debug log when the bridge drops a direct call's cookies because its credential is foreign. */
+  onDropped(path: string): void;
+}
+interface ScopeView {
+  /** Cookie-capable forwarding handlers have already passed the enforcing form check on every method/operation (§7.10). */
+  readonly cookies: CookieSink | null;
+  readonly forward: "none" | "same-credential" | "any";
+  readonly inbound: (() => Headers) | undefined;
+  readonly internal: boolean;
+  /**
+   * Present in EVERY handler scope whose transport exposes a browser leg, unless the plan's origin check is 'off' — enforcing or not,
+   * so safe methods and GraphQL queries are covered too (§7.5). Returns when this leg has a passing origin verdict for `instance`, or
+   * the single kernel disable predicate (§7.10 item 4) holds; a guard run without a passing verdict is insufficient. Otherwise throws the kernel's
+   * BetterAuthConfigurationError PUBLIC_HANDLER_USED_CALLER_SESSION.
+   */
+  readonly checkCallerSession?: (path: string, instance: string) => void;
+  /** The browser leg's OWN headers (TransportCall.browser.headers()), before any transport credential mapping replaced them; undefined
+   * when the transport exposes no browser leg. Entry 2 recognizes an ambiently carried session cookie with it. */
+  readonly browserHeaders: (() => Headers) | undefined;
+}
+interface CompiledHook {
+  /**
+   * Evaluate the user predicate once and let it throw. The dispatcher logs and
+   * converts before-hook matcher failures to APIError 500; after-hook matcher
+   * failures cross the next fixed SDK matcher boundary unchanged, so the SDK
+   * cannot recover them as handler APIErrors. Never swallow a failure as a
+   * non-match or evaluate the predicate again in run().
+   */
+  matches(ctx: HookEndpointContext, scope: ScopeView | undefined): boolean;
+  run(ctx: HookEndpointContext): Promise<unknown>;
+}
+//#endregion
+//#region src/request-scope.d.ts
+interface ScopeState {
+  readonly view: ScopeView;
+  readonly call?: TransportCall;
+  readonly plan?: RoutePlan;
+  readonly reading?: () => PrincipalReading;
+}
+/** A requirement's decision and the invocation values of the policy runs that produced an allow. */
+interface DecisionOutcome {
+  readonly decision: AuthorizationDecision;
+  readonly published: readonly ReadonlyMap<symbol, unknown>[];
+}
+interface RequestState {
+  readonly principal: Map<string, Promise<PrincipalResult>>;
+  readonly policyIo: Map<string, Promise<unknown>>;
+  readonly decisions: Map<string, Promise<DecisionOutcome>>;
+  readonly values: Map<symbol, unknown>;
+  readonly authorizationCalls: Set<string>;
+  readonly origins: Map<string, Promise<AuthFailure | null>>;
+  readonly surfaced: Set<string>;
+  readonly connections: Map<string, {
+    value: Extract<PrincipalResult, {
+      outcome: "authenticated" | "absent";
+    }>;
+    expiresAt: number;
+  }>;
+}
+declare class RequestScope {
+  #private;
+  run<T>(state: ScopeState, fn: () => T): T;
+  exit<T>(fn: () => T): T;
+  current(): ScopeState | undefined;
+  stateFor(key: object): RequestState;
+  memoPrincipal(call: Pick<TransportCall, "key" | "connection" | "principalTtlMs">, input: {
+    instance: string;
+    freshness: "default" | "authoritative";
+    sourceSet: string;
+  }, compute: () => Promise<PrincipalResult>): Promise<PrincipalResult>;
+  memoPolicyIo<T>(request: object, instance: string, concreteKey: string, compute: () => Promise<T>, limit?: number | false): Promise<T>;
+  memoDecision(invocation: object, instance: string, concreteKey: string, compute: () => Promise<DecisionOutcome>): Promise<DecisionOutcome>;
+  valueKey(instance: string, key: symbol): symbol;
+  surfaced(key: object, error: object, context: {
+    instance: string;
+    site: string;
+    lineage?: InvocationLineage;
+  }): boolean;
+}
+//#endregion
+//#region src/origin-check.d.ts
+/** Bounded, per-application diagnostics; the next denial rolls the window without timers. */
+declare class OriginDiagnostics {
+  #private;
+  private readonly logger;
+  constructor(logger: {
+    warn(message: string): void;
+    debug(message: string): void;
+  });
+  record(instance: string, failure: AuthFailure, headers: Headers, trustedCount: number): void;
+  advisoryFailure(instance: string, headers: Headers, trustedCount: number): void;
+}
+interface OriginCheckInit {
+  readonly instance: string;
+  readonly context: AuthContextView;
+  readonly options?: OriginCheckOptions;
+  readonly diagnostics?: OriginDiagnostics;
+  readonly credentialHeaders?: readonly string[];
+  readonly exposeRawCause?: boolean;
+}
+declare class OriginCheck {
+  #private;
+  private readonly scope;
+  private readonly init;
+  constructor(scope: RequestScope, init: OriginCheckInit);
+  check(browser: BrowserExposure, mode: "cookie" | "form"): Promise<AuthFailure | null>;
+  advisory(browser: BrowserExposure): Promise<void>;
+  assertCallerSession(browser: BrowserExposure, path: string, instance: string): void;
+  private calculationFailures;
+  private verdict;
+}
+//#endregion
+//#region src/instance-registry.d.ts
+interface InstanceEntry {
+  readonly name: string;
+  readonly instance: AuthLike;
+  readonly options: BetterAuthRuntimeOptions<AuthLike>;
+  readonly staticOptions: BetterAuthStaticOptions;
+  readonly sources: readonly PrincipalSource[];
+  readonly handle: AuthHandle;
+  readonly context: AuthContextView;
+  readonly origin: OriginCheck;
+  readonly bridge: BridgeHandle;
+  readonly credentialHeaders: readonly string[];
+}
+interface InstanceLookup {
+  get(name: string): InstanceEntry;
+  list(): readonly InstanceEntry[];
+}
+interface InstanceRegistration {
+  readonly name: string;
+  readonly instance: AuthLike;
+  readonly options: BetterAuthRuntimeOptions<AuthLike>;
+  readonly staticOptions: BetterAuthStaticOptions;
+  readonly appOptions: BetterAuthAppOptions;
+  readonly sources: readonly PrincipalSource[];
+  readonly handle: AuthHandle;
+}
+declare class InstanceRegistry implements InstanceLookup {
+  #private;
+  private readonly scope;
+  readonly logger: Logger;
+  readonly diagnostics: OriginDiagnostics;
+  state: "new" | "initialized" | "bootstrapped";
+  adapter: AbstractHttpAdapter | null;
+  owner: {
+    description: string;
+  };
+  constructor(scope: RequestScope);
+  register(options: BetterAuthRuntimeOptions<AuthLike>, staticOptions: BetterAuthStaticOptions, sources: readonly PrincipalSource[], appOptions: BetterAuthAppOptions): InstanceRegistration;
+  registrations(): readonly InstanceRegistration[];
+  get(name: string): InstanceEntry;
+  list(): readonly InstanceEntry[];
+  begin(adapter: AbstractHttpAdapter | null): boolean;
+  initialize(issues: BetterAuthConfigurationError[]): Promise<void>;
+  reset(): void;
+}
+//#endregion
+//#region src/mount-coordinator.d.ts
+declare class MountCoordinator {
+  #private;
+  readonly host: HttpAdapterHost;
+  private readonly registry;
+  readonly logger: Logger;
+  constructor(host: HttpAdapterHost, registry: InstanceRegistry, scope: RequestScope);
+  registerPlatforms(platforms: readonly HttpPlatform[]): void;
+  get platform(): HttpPlatform | undefined;
+  get adapter(): AbstractHttpAdapter | null;
+  private tryPrepare;
+  prepareAtInit(issues: BetterAuthConfigurationError[]): void;
+  resolve(issues: BetterAuthConfigurationError[]): void;
+  route(pathname: string): AuthRouteBinding | undefined;
+  binding(name: string): AuthRouteBinding | undefined;
+  bindings(): readonly AuthRouteBinding[];
+  normalizeApplicationRoute(path: string): string;
+  registerApplicationRoutes(routes: readonly ApplicationRouteDescriptor[], issues: BetterAuthConfigurationError[]): void;
+  mount(): Promise<void>;
+  reset(): void;
+}
+//#endregion
+//#region src/principal-readings.d.ts
+interface ReadingInput {
+  readonly args: readonly unknown[];
+  readonly call?: TransportCall;
+  readonly lineage?: InvocationLineage;
+  readonly plan?: Pick<RoutePlan, "access" | "instance" | "site">;
+  readonly beforeGuard?: boolean;
+  readonly site?: string;
+}
+/** The intrinsic twin suppresses Nest's repeated log, while retaining the safe wire shape. */
+declare class RepeatedReaderError extends IntrinsicException {
+  constructor(error: BetterAuthConfigurationError);
+}
+declare class PrincipalReadings {
+  private readonly scope;
+  constructor(scope: RequestScope);
+  record(call: Pick<TransportCall, "invocation" | "lineage">, reading: PrincipalReading): void;
+  recordLineage(lineage: InvocationLineage, reading: PrincipalReading): void;
+  enclosing(lineage: InvocationLineage, args: readonly unknown[]): PrincipalReading | undefined;
+  read(input: ReadingInput): PrincipalReading;
+  current(): PrincipalReading;
+  project<T>(reading: PrincipalReading, spec: {
+    kind?: string;
+    reason?: string;
+    site: string;
+    project: (principal: AuthPrincipal) => T;
+  }, input?: ReadingInput): T | null;
+  deliver(error: BetterAuthConfigurationError, input?: ReadingInput, instance?: string): BetterAuthConfigurationError | RepeatedReaderError;
+  stamp(args: readonly unknown[], instance: string, result: PrincipalResult): void;
+}
+//#endregion
+//#region src/policy-resolver.d.ts
+declare class PolicyResolver {
+  private readonly moduleRef;
+  private readonly cache;
+  constructor(moduleRef: ModuleRef);
+  resolve<P>(reference: PolicyRef<P>): AuthorizationPolicy<P, any>;
+}
+//#endregion
+//#region src/transport-registry.d.ts
+declare class TransportRegistry {
+  private transports;
+  private readonly owners;
+  private kit;
+  register(transports: readonly AuthTransport[]): void;
+  setKit(kit: TransportKit): void;
+  list(): readonly AuthTransport[];
+  defaultAccessFor(target: Function, method: string): "inherit" | undefined;
+  find(context: ExecutionContext): AuthTransport | undefined;
+  select(context: ExecutionContext): AuthTransport;
+  idOf(call: TransportCall): string;
+  describe(context: ExecutionContext, transport?: AuthTransport): TransportCall;
+}
+//#endregion
+//#region src/route-planner.d.ts
+declare class RoutePlanner {
+  private readonly instances;
+  private readonly policies;
+  private readonly transports;
+  private readonly cache;
+  constructor(instances: InstanceLookup, policies: PolicyResolver, transports: TransportRegistry);
+  private prepare;
+  requirementsOf(target: Type, method: string): readonly RequirementExpr[];
+  forContext(context: ExecutionContext): RoutePlan;
+  plan(target: Type, method: string): RoutePlan;
+}
+//#endregion
+//#region src/auth-service.d.ts
+declare class BetterAuthService<A extends AuthLike = RegisteredAuth> {
+  #private;
+  private readonly registry;
+  private readonly scope;
+  private readonly readings;
+  private readonly planner;
+  private readonly transports;
+  private readonly coordinator;
+  readonly name: string;
+  readonly instance: A;
+  readonly api: A["api"];
+  constructor(options: BetterAuthRuntimeOptions<A>, registry: InstanceRegistry, scope: RequestScope, readings: PrincipalReadings, planner: RoutePlanner, transports: TransportRegistry, coordinator: MountCoordinator);
+  context(): Promise<Awaited<A["$context"]>>;
+  mount(): {
+    readonly basePath: string;
+    readonly bodyLimit: number;
+    readonly platform: string;
+  } | undefined;
+  getPrincipal(): Promise<AuthPrincipal | null>;
+  getSession(): Promise<SessionOf<A> | null>;
+  principalFor(context: ExecutionContext): PrincipalReading;
+  headersFrom(platformRequest: unknown): Headers;
+  forwardForeignCookies<T>(fn: () => Promise<T>): Promise<T>;
+  withoutCookies<T>(fn: () => Promise<T>): Promise<T>;
+  runOutsideScope<T>(fn: () => Promise<T>): Promise<T>;
+}
+//#endregion
+//#region src/authorization-evaluator.d.ts
+declare const allow: () => AuthorizationDecision;
+declare const deny: (input: {
+  reason: string;
+  status?: 401 | 403;
+  message?: string;
+  challenge?: string;
+}) => AuthorizationDecision;
+declare function definePolicy<P, K extends PrincipalKind = PrincipalKind>(policy: AuthorizationPolicy<P, PrincipalOfKind<K>>): (params: P, options?: RequirementOptions) => Requirement<P>;
+declare class AuthorizationEvaluator {
+  private readonly policies;
+  private readonly invoker;
+  private readonly resolver;
+  private readonly scope;
+  private readonly keys;
+  constructor(policies: PolicyResolver, invoker: PolicyInvoker, resolver: PrincipalResolver, scope: RequestScope);
+  evaluate(plan: RoutePlan, principal: AuthPrincipal, call: TransportCall, entry: InstanceEntry, execution: ExecutionContext, transport: string): Promise<AuthorizationDecision>;
+}
+//#endregion
+//#region src/auth-guard.d.ts
+declare class BetterAuthGuard implements CanActivate {
+  private readonly core;
+  static readonly [AUTH_ENHANCER] = "guard";
+  readonly [AUTH_ENHANCER] = "guard";
+  constructor(core: Pick<GuardCore, "canActivate">);
+  canActivate(context: ExecutionContext): Promise<boolean>;
+}
+declare class GuardCore implements CanActivate {
+  private readonly instances;
+  private readonly planner;
+  private readonly transports;
+  private readonly resolver;
+  private readonly evaluator;
+  private readonly scope;
+  private readonly readings;
+  constructor(instances: InstanceLookup, planner: RoutePlanner, transports: TransportRegistry, resolver: PrincipalResolver, evaluator: AuthorizationEvaluator, scope: RequestScope, readings: PrincipalReadings);
+  canActivate(context: ExecutionContext): Promise<boolean>;
+}
+//#endregion
+//#region src/auth-scope-interceptor.d.ts
+declare class BetterAuthScopeInterceptor implements NestInterceptor {
+  private readonly core;
+  static readonly [AUTH_ENHANCER] = "scope";
+  readonly [AUTH_ENHANCER] = "scope";
+  constructor(core: Pick<ScopeCore, "intercept">);
+  intercept(context: ExecutionContext, next: CallHandler): Observable<unknown>;
+}
+declare class ScopeCore implements NestInterceptor {
+  private readonly instances;
+  private readonly planner;
+  private readonly transports;
+  private readonly scope;
+  private readonly readings;
+  constructor(instances: InstanceLookup, planner: RoutePlanner, transports: TransportRegistry, scope: RequestScope, readings: PrincipalReadings);
+  intercept(context: ExecutionContext, next: CallHandler): Observable<unknown>;
+}
+//#endregion
+//#region src/auth-module-definition.d.ts
+declare function defineExtension<T>(definition: Omit<ExtensionDefinition<T>, typeof EXTENSION_DEFINITION>): ExtensionDefinition<T>;
+declare function defineHttpPlatform<P extends HttpPlatform>(platform: P): P;
+declare function defineTransport<T extends AuthTransport>(transport: T): T;
+//#endregion
+//#region src/auth-decorators.d.ts
+declare const Public: () => import("@nestjs/common").CustomDecorator<typeof ACCESS_METADATA>;
+declare const OptionalAuth: () => import("@nestjs/common").CustomDecorator<typeof ACCESS_METADATA>;
+declare const RequireAuth: (options?: {
+  authoritative?: boolean;
+}) => <TFunction extends Function, Y>(target: TFunction | object, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;
+declare const UseAuthInstance: (name: string) => import("@nestjs/common").CustomDecorator<typeof AUTH_INSTANCE_METADATA>;
+declare const AcceptPrincipals: (...kinds: readonly [PrincipalKind, ...PrincipalKind[]]) => import("@nestjs/common").CustomDecorator<typeof ACCEPT_PRINCIPALS_METADATA>;
+declare const SkipDefaultRequirements: () => import("@nestjs/common").CustomDecorator<typeof SKIP_DEFAULT_REQUIREMENTS_METADATA>;
+declare const ForwardAuthCookies: (enabled?: boolean) => import("@nestjs/common").CustomDecorator<typeof FORWARD_COOKIES_METADATA>;
+declare const SkipOriginCheck: () => import("@nestjs/common").CustomDecorator<typeof SKIP_ORIGIN_CHECK_METADATA>;
+declare const UseBetterAuth: () => <TFunction extends Function, Y>(target: TFunction | object, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;
+declare function Require(...requirements: readonly RequirementExpr[]): ClassDecorator & MethodDecorator;
+declare const anyOf: (...requirements: readonly RequirementExpr[]) => RequirementExpr;
+declare const allOf: (...requirements: readonly RequirementExpr[]) => RequirementExpr;
+declare const requirement: <P>(policy: PolicyRef<P>, params: P, options?: RequirementOptions) => Requirement<P>;
+declare const CurrentPrincipal: () => ParameterDecorator;
+declare function definePrincipalParam<K extends PrincipalKind, R>(spec: {
+  readonly kind: K;
+  readonly reason: string;
+  readonly project: (principal: PrincipalOfKind<K>) => R;
+}): () => ParameterDecorator;
+declare function defineInvocationParam(slot: symbol, spec: {
+  readonly missing: string;
+}): () => ParameterDecorator;
+declare const BeforeAuth: <const P extends EndpointPath | (string & {})>(match?: P | readonly P[] | HookPredicate, options?: HookOptions) => HookMethodDecorator<P>;
+declare const AfterAuth: <const P extends EndpointPath | (string & {})>(match?: P | readonly P[] | HookPredicate, options?: HookOptions) => HookMethodDecorator<P>;
+declare const BeforeDatabase: <E extends DatabaseHookTarget>(target: E, options?: DbHookOptions) => DbHookMethodDecorator<E, "before">;
+declare const AfterDatabase: <E extends DatabaseHookTarget>(target: E, options?: DbHookOptions) => DbHookMethodDecorator<E, "after">;
+//#endregion
+//#region src/session-principal.d.ts
+declare const SESSION_PRINCIPAL_KIND: "session";
+declare const CurrentSession: () => ParameterDecorator;
+declare const CurrentUser: () => ParameterDecorator;
+declare function sessionPrincipal<S = AuthSession>(options?: SessionPrincipalOptions<S>): PrincipalSource<SessionPrincipal<S>>;
+declare const freshSession: (options?: {
+  maxAgeSeconds?: number;
+}) => Requirement<{
+  maxAgeSeconds?: number;
+}>;
+declare const RequireFreshSession: (options?: {
+  maxAgeSeconds?: number;
+}) => ClassDecorator & MethodDecorator;
+//#endregion
+//#region src/principal-resolver.d.ts
+declare const definePrincipalSource: <P extends AuthPrincipalBase>(source: PrincipalSource<P>) => PrincipalSource<P>;
+declare const authenticated: <P extends AuthPrincipalBase>(principal: P) => PrincipalResult<P>;
+declare const absent: () => PrincipalResult<never>;
+declare const rejected: (failure: AuthFailure) => PrincipalResult<never>;
+//#endregion
+//#region src/auth-exchange.d.ts
+/** Credentialed CORS for the auth mount, using the initialized SDK trusted origins. */
+declare function betterAuthCorsOrigin(auth: AuthLike, options?: CorsOriginOptions): (origin: string | undefined, cb: (err: Error | null, allow?: boolean) => void) => void;
+//#endregion
+//#region src/http-transport.d.ts
+declare function httpTransport(): ExtensionRef<AuthTransport>;
+//#endregion
+//#region src/index.d.ts
+/** Augment this public interface to register an optional principal kind. */
+interface PrincipalKinds {
+  session: SessionPrincipal;
+}
+//#endregion
+//#region src/auth-types.d.ts
+/** Structural minimum; accepts any betterAuth() result incl. plugins and customSession (EXP-C2, EXP-A:types/). */
+interface AuthLike {
+  handler(request: Request): Promise<Response>;
+  api: {
+    getSession(ctx: {
+      headers: Headers;
+      query?: {
+        disableCookieCache?: boolean;
+        disableRefresh?: boolean;
+      };
+      returnHeaders?: boolean;
+    }): Promise<unknown>;
+  };
+  $context: Promise<unknown>;
+}
+/** What getSession({ returnHeaders: true }) resolves to. `headers` is undefined when a before-hook short-circuited the call (LEAD-V37). */
+interface GetSessionWithHeaders {
+  readonly headers?: Headers | null;
+  readonly response: unknown;
+}
+/** Augment this interface with the application auth instance and named instances. */
+interface Register {}
+type IsRegistered = Register extends {
+  auth: AuthLike;
+} ? true : false;
+type RegisteredAuth = Register extends {
+  auth: infer A extends AuthLike;
+} ? A : AuthLike;
+type RegisteredInstances = Register extends {
+  instances: infer I extends Record<string, AuthLike>;
+} ? I : Record<never, never>;
+type AuthOf<N extends string = "default"> = N extends "default" ? RegisteredAuth : N extends keyof RegisteredInstances ? RegisteredInstances[N] : AuthLike;
+/** Unregistered fallback = better-auth's default core shape (Session/User are exported by better-auth, EXP-C11). */
+type DefaultSession = {
+  session: import("better-auth").Session;
+  user: import("better-auth").User;
+};
+type SessionOf<A> = A extends {
+  $Infer: {
+    Session: infer S;
+  };
+} ? NonNullable<S> : DefaultSession;
+type UserOf<A> = SessionOf<A> extends {
+  user: infer U;
+} ? U : never;
+type AuthSession<N extends string = "default"> = SessionOf<AuthOf<N>>;
+type AuthUser<N extends string = "default"> = UserOf<AuthOf<N>>;
+type HasUserId<S> = S extends {
+  user: {
+    id: string;
+  };
+} ? true : false;
+type BodyOf<F> = F extends ((ctx: infer C) => unknown) ? [NonNullable<C>] extends [{
+  body?: infer B;
+}] ? NonNullable<B> : never : never;
+type PermissionsOf<A, K extends string> = A extends {
+  api: { [k in K]: infer F; };
+} ? BodyOf<F> extends {
+  permissions?: infer P;
+} ? NonNullable<P> : never : never;
+type AdminPermissions<N extends string = "default"> = IsRegistered extends true ? PermissionsOf<AuthOf<N>, "userHasPermission"> : Record<string, readonly string[]>;
+type OrgPermissions<N extends string = "default"> = IsRegistered extends true ? PermissionsOf<AuthOf<N>, "hasPermission"> : Record<string, readonly string[]>;
+type ApiOf<A> = A extends {
+  api: infer Api;
+} ? Api : never;
+type EndpointPath<A = RegisteredAuth> = { [K in keyof ApiOf<A>]: ApiOf<A>[K] extends {
+  path: infer P extends string;
+} ? P : never; }[keyof ApiOf<A>];
+type EndpointAt<P extends string, A = RegisteredAuth> = { [K in keyof ApiOf<A>]: ApiOf<A>[K] extends {
+  path: P;
+} ? ApiOf<A>[K] : never; }[keyof ApiOf<A>];
+type BodyAt<P extends string> = [EndpointAt<P>] extends [never] ? unknown : BodyOf<EndpointAt<P>>;
+/**
+ * The RAW body a hook sees: the endpoint's schema has not run yet (before-hooks) or ran on the same raw input (after-hooks).
+ * Known keys autocomplete; every value is `unknown` until the hook checks it.
+ */
+type UnvalidatedBody<B> = [B] extends [never] ? unknown : B extends object ? { readonly [K in keyof B]?: unknown; } & Readonly<Record<string, unknown>> : unknown;
+type AuthHookContext<P extends string = string> = Omit<import("better-auth").HookEndpointContext, "path" | "body"> & {
+  path: P;
+  body: string extends P ? unknown : UnvalidatedBody<BodyAt<P>>;
+};
+type AuthAfterHookContext<P extends string = string> = AuthHookContext<P>;
+type DbHooks = NonNullable<import("better-auth").BetterAuthOptions["databaseHooks"]>;
+/** The SDK's own hook signature for a target, independent of the registered instance. Internal to the dispatcher. */
+type DbHookFn<E extends DatabaseHookTarget, Ph extends "before" | "after"> = E extends `${infer M extends keyof DbHooks & string}.${infer O extends "create" | "update" | "delete"}` ? NonNullable<NonNullable<NonNullable<DbHooks[M]>[O]>[Ph]> : never;
+/** Best effort: the registered instance's additional user/session fields, Partial for updates; nothing when not derivable. */
+type RegisteredRow<M> = M extends "user" ? UserOf<RegisteredAuth> : M extends "session" ? SessionOf<RegisteredAuth> extends {
+  session: infer S;
+} ? S : never : never;
+type ExtraFields<E extends DatabaseHookTarget> = E extends `${infer M}.${infer O}` ? [RegisteredRow<M>] extends [never] ? Record<never, never> : O extends "update" ? Partial<RegisteredRow<M>> : RegisteredRow<M> : Record<never, never>;
+/** The payload better-auth passes: e.g. update.before → Partial<User> & Record<string, unknown>. */
+type DatabaseHookData<E extends DatabaseHookTarget, Ph extends "before" | "after" = "before"> = Parameters<DbHookFn<E, Ph>>[0] & ExtraFields<E>;
+/** What better-auth accepts back: create/update.before → boolean | void | { data }; delete.before → boolean | void; after → void. */
+type DatabaseHookResult<E extends DatabaseHookTarget, Ph extends "before" | "after"> = Awaited<ReturnType<DbHookFn<E, Ph>>>;
+type DatabaseHookMethod<E extends DatabaseHookTarget, Ph extends "before" | "after"> = (data: DatabaseHookData<E, Ph>, ctx: import("better-auth").GenericEndpointContext | null | undefined) => DatabaseHookResult<E, Ph> | Promise<DatabaseHookResult<E, Ph>>;
+/** Guard-established invariant helper (reference #163). Prefer @ActiveOrganizationId() (§8.3). */
+type WithActiveOrganization<S> = S & {
+  session: {
+    activeOrganizationId: string;
+  };
+};
+type PrincipalKind = keyof PrincipalKinds & string;
+type AuthPrincipal = PrincipalKinds[PrincipalKind];
+type PrincipalOfKind<K extends PrincipalKind> = PrincipalKinds[K];
+interface SessionPrincipal<S = AuthSession> extends AuthPrincipalBase {
+  readonly kind: "session";
+  readonly session: S;
+}
+//#endregion
+//#region src/auth-contracts.d.ts
+interface BetterAuthAppOptions {
+  /** HTTP platforms. Exactly one must support the running HTTP adapter when the app has one. Default []. */
+  platforms?: readonly ExtensionRef<HttpPlatform>[];
+  /** Transports, consulted in order BEFORE the built-in httpTransport(). Default []. */
+  transports?: readonly ExtensionRef<AuthTransport>[];
+}
+type NoAppOptions = {
+  readonly platforms?: never;
+  readonly transports?: never;
+};
+/** Instance-shape options: they decide which providers exist, so they are fixed at definition time. [A][B][C] */
+interface BetterAuthStaticOptions {
+  /** Instance name. Default 'default'. Named instances get their own tokens and mount (§5.5). */
+  name?: string;
+  /** Register the module as global. Default true. */
+  global?: boolean;
+  /**
+   * Register BetterAuthGuard as APP_GUARD (via useExisting). Default true for the default instance, false for named instances.
+   * Since v6 this no longer controls APP_INTERCEPTOR: see globalScope.
+   */
+  globalGuard?: boolean;
+  /**
+   * Register BetterAuthScopeInterceptor as APP_INTERCEPTOR (via useExisting). Default true for the DEFAULT instance, whatever
+   * globalGuard says; named instances never register it (one scope opener per app). The interceptor denies nothing: it opens the
+   * scope that carries the cookie sink, refresh suppression and the caller-session check (§7.5, ADR-70). Setting it false is an
+   * explicit opt-out, printed in the boot summary and warned about (W_NO_GLOBAL_SCOPE, §5.4 B31). [§17 Q38]
+   */
+  globalScope?: boolean;
+  /** Principal sources of this instance, tried in order BEFORE the built-in session source, filtered per route by the kinds it accepts (§7.6). Default []. */
+  principals?: readonly ExtensionRef<PrincipalSource>[];
+}
+/** Runtime options: read by providers after DI resolution, so they may come from useFactory. */
+type BetterAuthRuntimeOptions<A extends AuthLike = RegisteredAuth> = {
+  /** The object returned by betterAuth(). Never wrapped, cloned or mutated. */
+  auth: A;
+  /** Access for handlers without an access decorator, unless a transport supplies the default (field resolvers inherit, §7.6). Default 'authenticated'. [C] */
+  defaultAccess?: "authenticated" | "public";
+  /**
+   * Requirements every 'required' plan of this instance carries, ahead of its class and method requirements: a company-wide
+   * rule such as orgMember(). Compiled into the plan, so boot validation, coverage, the guard and the decorators see one plan.
+   * Replaces v2's protected BetterAuthGuard.planFor seam (§7.6). A handler or controller opts out visibly with
+   * @SkipDefaultRequirements() (counted in the boot summary), and a plan whose AND-ed requirements admit no common principal kind
+   * fails boot (B15 UNSATISFIABLE_PRINCIPAL_KINDS). Default [].
+   */
+  defaultRequirements?: readonly RequirementExpr[];
+  /** HTTP mount options for this instance. */
+  http?: HttpMountOptions;
+  /** Set-Cookie forwarding for application-level direct auth.api calls (§7.5). */
+  cookies?: CookieForwardingOptions;
+  /** better-auth's origin rule on cookie-carrying app operations, and its form-CSRF rule on handlers that forward auth cookies (§7.10). */
+  originCheck?: OriginCheckOptions;
+  /** Per-instance override of transport error objects for this instance's plans, and error logging (§13.5). */
+  errors?: ErrorMappingOptions;
+  /** Bounds on the authorization work one logical request can cause (§8.1). */
+  limits?: AuthorizationLimits;
+  /** Log the one-line boot summary. Default true. */
+  logSummary?: boolean;
+} & SessionOption<A>;
+interface AuthorizationLimits {
+  /**
+   * Distinct better-auth calls that policies may make through AuthorizationContext.memo for one logical request (memo hits do
+   * not count). Past it, a requirement denies 429 TOO_MANY_AUTHORIZATION_CHECKS instead of calling better-auth, so N aliased
+   * GraphQL fields with N different organizations cannot exhaust the connection pool. false disables the bound. Default 100.
+   */
+  maxAuthorizationCallsPerRequest?: number | false;
+}
+interface CookieForwardingOptions {
+  /**
+   * Forward Set-Cookie produced by direct auth.api.* calls that application code makes inside a handler, when the call
+   * carries the caller's own credential or none. Default false, which is better-auth's server-call semantics
+   * (a server call never touches the browser unless you ask). Per handler: @ForwardAuthCookies(). The library's own calls
+   * (principal sources and policies) always forward. Handlers with forwarding on enforce better-auth's form-CSRF origin rule on EVERY
+   * method and operation kind, including safe cookie-free GET/query calls (§7.10), so turning this on instance-wide applies it everywhere. v3's per-call-site opt-in is gone: it forwarded
+   * without the form check (§7.5).
+   */
+  forwardDirectCalls?: boolean;
+}
+interface OriginCheckOptions {
+  /**
+   * 'cookie' (default): an unsafe operation whose browser leg carries a cookie must come from a trusted origin, whatever credential
+   * authenticated it, exactly as on better-auth's routes (§7.10). 'off': disabled (B19 warns in production).
+   */
+  mode?: "cookie" | "off";
+  /**
+   * A cookie-authenticated unsafe operation without Origin or Referer.
+   * 'reject' (default): 403 MISSING_OR_NULL_ORIGIN, exactly as better-auth's own routes answer (LEAD-V16).
+   * 'allow-non-browser': allowed when Origin, Referer and Sec-Fetch-Site are all absent (no browser sends such a request cross-site).
+   * Native clients that send the session cookie themselves (better-auth's Expo client on your own routes, SSR servers) send none of
+   * them; under 'reject' they need an Origin header. See §17 Q15.
+   */
+  missingOrigin?: "reject" | "allow-non-browser";
+}
+/** `session` is REQUIRED (with userId) when the session shape lacks user.id, i.e. customSession (§11.5). [C] */
+type SessionOption<A extends AuthLike> = HasUserId<SessionOf<A>> extends true ? {
+  session?: SessionPrincipalOptions<SessionOf<A>> | false;
+} : {
+  session: (SessionPrincipalOptions<SessionOf<A>> & {
+    userId: (s: SessionOf<A>) => string | null;
+  }) | false;
+};
+interface SessionPrincipalOptions<S> {
+  /** Map a (possibly customSession-shaped) session to its user id. Default s => s.user?.id ?? null. */
+  userId?: (session: S) => string | null;
+  /** Default freshness of identity reads; per route: @RequireAuth({ authoritative: true }). Default 'default'. */
+  freshness?: "default" | "authoritative";
+  /**
+   * Does any apiKey() configuration of this instance set enableSessionForAPIKeys? The api-key plugin object does not expose
+   * its configuration, so no unit can read it (§8.3.1). Unset (default): when the api-key plugin is present, the session
+   * unit's boot advice W_API_KEY_FULL_SESSION / W_API_KEY_SESSION_MULTIPLIER is worded conditionally. false: you assert
+   * that none does, and the advice is dropped. true: the advice is worded as a fact.
+   */
+  apiKeySessions?: boolean;
+}
+interface HttpMountOptions {
+  /** Mount better-auth routes on the platform. Default true. false = guard-only service. */
+  mount?: boolean;
+  /** Maximum auth-route request body. Default 1_048_576 (1 MiB). 413 above. */
+  bodyLimit?: number | `${number}${"b" | "kb" | "mb"}`;
+  /** Wrap every auth-route exchange (ORM request context, tracing). Outermost first. [A][C] */
+  around?: readonly AuthHandlerInterceptor[];
+  /** Allow a mount path of '/'. Default false (a root mount captures every unmatched route). [A] */
+  allowRootMount?: boolean;
+  /**
+   * Allow an unset baseURL in production (production = NODE_ENV is not development, dev or test, §5.4). better-auth then derives
+   * the base URL, token links and a trusted origin from each request's Host header. Default false: boot fails with UNSAFE_BASE_URL
+   * (B23).
+   */
+  allowRequestDerivedBaseURL?: boolean;
+  /** Log each auth path better-auth answers 404 for once, with a "did you mean" (capped at 100 paths). Default: true outside production. */
+  diagnostics?: boolean;
+}
+type AuthHandlerInterceptor = (call: {
+  readonly request: Request;
+  readonly platformRequest: unknown;
+  readonly instance: string;
+}, next: (request?: Request) => Promise<Response>) => Promise<Response>;
+type BetterAuthModuleOptions<A extends AuthLike> = BetterAuthStaticOptions & BetterAuthRuntimeOptions<A>;
+interface BetterAuthModuleAsyncOptions<A extends AuthLike> extends BetterAuthStaticOptions {
+  imports?: ModuleMetadata["imports"];
+  inject?: readonly (InjectionToken | OptionalFactoryDependency)[];
+  useFactory: (...args: any[]) => BetterAuthFactoryResult<A> | Promise<BetterAuthFactoryResult<A>>;
+}
+/** A static or app-level key returned from useFactory is a compile error with a readable message (EXP-C9). [C] */
+type BetterAuthFactoryResult<A extends AuthLike> = BetterAuthRuntimeOptions<A> & { [K in keyof (BetterAuthStaticOptions & BetterAuthAppOptions)]?: StaticOptionMustBePassedToForRootAsync<K>; };
+interface StaticOptionMustBePassedToForRootAsync<K extends string> {
+  readonly __error: `'${K}' is a static option: pass it to forRootAsync() next to useFactory, not in its result`;
+}
+/** Rejects a different instance than the registered one for the default instance (EXP-C2). [C] */
+type DefaultInstanceCheck<A> = IsRegistered extends true ? A extends RegisteredAuth ? unknown : {
+  auth: RegisteredAuth;
+} : unknown;
+/** A class (DI-constructed), a ready instance, or a definition that brings its own providers. */
+type ExtensionRef<T> = Type<T> | T | ExtensionDefinition<T>;
+interface ExtensionDefinition<T> {
+  readonly [EXTENSION_DEFINITION]: true;
+  readonly use: {
+    readonly useClass: Type<T>;
+  } | {
+    readonly useFactory: (...deps: any[]) => T | Promise<T>;
+    readonly inject?: readonly InjectionToken[];
+  } | {
+    readonly useExisting: InjectionToken<T>;
+  };
+  readonly providers?: readonly Provider[];
+  readonly imports?: ModuleMetadata["imports"];
+  /** Tokens (from `providers`) the forRoot module re-exports, globally unless `global` is false: helper services for users. */
+  readonly exports?: readonly InjectionToken[];
+}
+interface RoutePlan {
+  readonly instance: string;
+  /**
+   * 'inherit': a handler a transport declares as reached only through an already authorized operation (GraphQL field resolvers
+   * without method-level access, acceptance or requirement metadata; class-level metadata never applies to them, §7.6 step 3). The
+   * guard performs no principal I/O: it checks the enclosing reading and also enforces form mode when forwarding is declared; readers take the nearest
+   * enclosing invocation's reading (§7.8).
+   */
+  readonly access: "public" | "optional" | "required" | "inherit";
+  /** A transport's defaultAccessFor answered 'inherit' for the handler (a nested handler, §7.6 step 3), whatever its effective access. */
+  readonly nested: boolean;
+  /**
+   * defaultRequirements first (unless @SkipDefaultRequirements() applies), then class requirements (base first; not for handlers a
+   * transport nests), then method requirements; empty unless access is 'required'.
+   */
+  readonly requirements: readonly RequirementExpr[];
+  /** @SkipDefaultRequirements() removed the instance's defaultRequirements from this plan (counted in the boot summary, B22). */
+  readonly skipsDefaultRequirements: boolean;
+  /**
+   * The handler declares something in B16's sense (§5.4), computed with the same scoping as the plan: method-level metadata, class-level
+   * metadata unless a transport nests the handler, and direct-call forwarding (@ForwardAuthCookies() or cookies.forwardDirectCalls).
+   * The other instance-wide defaults (defaultAccess, the default kinds, defaultRequirements) never count.
+   */
+  readonly declares: boolean;
+  /** 'authoritative' when the route asks for it, session.freshness says so, or a requirement demands fresh identity. */
+  readonly freshness: "default" | "authoritative";
+  /** Principal kinds admitted on the route (§7.6): @AcceptPrincipals or the instance's default kinds, plus kinds requirements name. */
+  readonly accepts: ReadonlySet<string>;
+  /** Kind constraints contributed by param decorators (e.g. @CurrentSession() → { kind: 'session', reason: 'SESSION_REQUIRED' }); checked at boot (B15). */
+  readonly principalParams: readonly {
+    readonly kind: string;
+    readonly reason: string;
+  }[];
+  /**
+   * The origin check (§7.10). 'cookie': better-auth's rule when the browser leg carries a cookie. 'form': better-auth's
+   * form-CSRF rule, enforcing on every method/operation even without an inbound cookie (handlers declaring cookie forwarding).
+   * 'off': @SkipOriginCheck() or originCheck.mode 'off'.
+   */
+  readonly originCheck: "cookie" | "form" | "off";
+  /** Content key of the sources this plan consults (ordered source indexes, interned per instance); part of the principal memo key (§7.2). */
+  readonly sourceSet: string;
+  /** Set-Cookie of application direct calls is forwarded (§7.5). */
+  readonly forwardDirectCalls: boolean;
+  readonly site: string;
+}
+type PrincipalReading = (PrincipalResult | {
+  readonly outcome: "no-identity";
+}) & {
+  readonly instance: string;
+};
+/**
+ * The resolver port the guard uses. Default: ChainPrincipalResolver. Readers never call it: they read the results the guard
+ * recorded (§7.8), so v3's peek() is gone. [B]
+ */
+interface PrincipalResolver {
+  resolve(call: TransportCall, request: ResolutionRequest): Promise<PrincipalResult>;
+}
+interface ResolutionRequest {
+  readonly auth: AuthHandle;
+  readonly freshness: "default" | "authoritative";
+  /** Kinds the route accepts; sources producing none of them are not consulted (§7.6). */
+  readonly accepts: ReadonlySet<string>;
+  /** The plan's content key of those sources (RoutePlan.sourceSet). */
+  readonly sourceSet: string;
+  /**
+   * The re-classification read of a generic 401 a policy call met (§8.1): resolve again through the one source that produced the
+   * principal (its id), which must declare sessionBacked, bypassing the principal memo. The evaluator shares one such read per logical
+   * request (§7.2).
+   */
+  readonly reclassify?: {
+    readonly sourceId: string;
+  };
+}
+/** The port the evaluator calls a policy through. Default: policy.evaluate(params, context). Tests substitute it (overrideDecisions, §14.8). */
+interface PolicyInvoker {
+  invoke<P>(policy: AuthorizationPolicy<P, any>, params: P, context: AuthorizationContext): Promise<AuthorizationDecision>;
+}
+interface RequirementOptions {
+  readonly label?: string;
+  /** Overrides policy.requires.principals for this requirement. */
+  readonly principals?: readonly PrincipalKind[];
+  /** Overrides policy.requires.freshIdentity for this requirement. */
+  readonly freshIdentity?: boolean;
+}
+interface HookOptions {
+  /** 'http' = requests routed by auth.handler; 'server' = direct auth.api calls. Default 'all'. */
+  calls?: "all" | "http" | "server";
+  /** Skip calls this library makes (guard getSession, policy checks). Default false (better-auth semantics). */
+  skipInternal?: boolean;
+  /** Ascending order among Nest hooks; ties keep discovery order. Default 0. */
+  order?: number;
+  /** Named instance the hook binds to. Default 'default'. */
+  instance?: string;
+}
+interface DbHookOptions {
+  order?: number;
+  instance?: string;
+}
+type HookPredicate = (ctx: AuthHookContext) => boolean;
+/**
+ * The decorated method type M is inferred and constrained rather than fixed: TypedPropertyDescriptor is invariant, so a fixed
+ * descriptor type would reject sound methods that declare fewer parameters or return a narrower result.
+ */
+type HookMethodDecorator<P extends string> = <M extends (ctx: AuthHookContext<P>) => unknown>(target: object, key: string | symbol, descriptor: TypedPropertyDescriptor<M>) => void;
+/** Constrains the decorated method like HookMethodDecorator; the SDK's payload, context and result types still apply. */
+type DbHookMethodDecorator<E extends DatabaseHookTarget, Ph extends "before" | "after"> = <M extends DatabaseHookMethod<E, Ph>>(target: object, key: string | symbol, descriptor: TypedPropertyDescriptor<M>) => void;
+type DatabaseHookTarget = `${"user" | "session" | "account" | "verification"}.${"create" | "update" | "delete"}`;
+interface CorsOriginOptions {
+  /** Also honor wildcard (`https://*.vercel.app`) and custom-scheme trusted origins for credentialed CORS. Default false: exact origins only. */
+  allowPatterns?: boolean;
+}
+interface ExpressPlatformOptions {
+  /** Client IP for better-auth's rate limiter. Default req.ip (honors Express `trust proxy`). */
+  clientIp?: (req: IncomingMessage & {
+    ip?: string;
+  }) => string | null;
+}
+interface FastifyPlatformOptions {
+  /** Default request.ip (honors Fastify `trustProxy`). */
+  clientIp?: (request: {
+    ip?: string;
+    raw: IncomingMessage;
+  }) => string | null;
+}
+interface ConformanceCase {
+  readonly id: string;
+  readonly title: string;
+  /** Why the case does not apply, when that is known before it runs. */
+  readonly skip?: string;
+  /**
+   * Runs the case. It resolves with a ConformanceSkip when the case finds at run time that it does not apply, for
+   * example because a unit registered through defineExtension() lacks an optional capability.
+   */
+  run(): Promise<ConformanceOutcome>;
+}
+/** A case that found at run time that it does not apply. */
+interface ConformanceSkip {
+  readonly skipped: string;
+}
+/** What a case's run() resolves with: nothing when it passed, a ConformanceSkip when it does not apply. */
+type ConformanceOutcome = void | ConformanceSkip;
+interface ConformanceRunner {
+  describe(name: string, fn: () => void): void;
+  /**
+   * Registers a test. runConformance passes a function without declared parameters; when the runner hands it a test
+   * context with skip(note) (Vitest, node:test), a case that skips at run time is reported as skipped.
+   */
+  it(name: string, fn: (context?: unknown) => Promise<void>): void;
+}
+interface BootAdvice {
+  readonly level: "warn" | "info";
+  /** Stable code, e.g. 'W_API_KEY_SESSION_MULTIPLIER'. */
+  readonly code: string;
+  readonly message: string;
+  readonly hint?: string;
+}
+interface BootAdviceContext {
+  readonly instance: string;
+  readonly auth: AuthHandle;
+  /** Awaited $context (post-init options, plugins, sessionConfig, authCookies). */
+  readonly context: AuthContextView;
+  /** true unless NODE_ENV is 'development', 'dev' or 'test' (an unset NODE_ENV counts as production, §5.4). */
+  readonly production: boolean;
+  readonly hasHttpAdapter: boolean;
+  /** The instance's effective origin-check options (the session unit's W_ORIGIN_CHECK_NATIVE_CLIENTS reads missingOrigin). */
+  readonly originCheck: {
+    readonly mode: "cookie" | "off";
+    readonly missingOrigin: "reject" | "allow-non-browser";
+  };
+  /** Every compiled handler of this instance (controllers, resolvers, gateways, message handlers) with what transports claimed for it. */
+  readonly handlers: readonly AdvisedHandler[];
+  readonly transports: readonly {
+    readonly id: string;
+    readonly connectionTtlMs?: number;
+  }[];
+  readonly sources: readonly Pick<PrincipalSource, "id" | "kinds" | "acceptance" | "effects">[];
+  /** Policies referenced by any plan (resolved instances, §4.4.3), with their declared requirements. */
+  readonly policies: readonly Pick<AuthorizationPolicy, "id" | "requires">[];
+}
+interface AdvisedHandler {
+  readonly plan: RoutePlan;
+  /** Ids of the transports that claimed the handler; empty when none did. */
+  readonly transports: readonly string[];
+  /** Named inputs the claiming transports reported (ClaimOptions.inputs): HTTP route params, GraphQL @Args names. Empty when unknown. */
+  readonly inputs: readonly string[];
+}
+interface HttpPlatform {
+  /** Diagnostic id ('express', 'fastify', 'hono'…). Core prints it and never compares it. */
+  readonly id: string;
+  /**
+   * Capabilities. http2: the conformance kit exercises HTTP/2. prepareAtInit: prepare() may also run from the core module's
+   * onModuleInit, because nothing it installs has to precede Nest's init(); core then prepares a second application's adapter on the
+   * same container instead of failing with APP_ADAPTER_CHANGED (§5.7).
+   */
+  readonly capabilities?: {
+    readonly http2?: boolean;
+    readonly prepareAtInit?: boolean;
+  };
+  /** Does this platform drive the running Nest HTTP adapter? Adapter-owned predicate. Never called with a null adapter. */
+  supports(adapter: AbstractHttpAdapter): boolean;
+  /**
+   * Phase 1, optional, synchronous. Called once, as soon as BOTH the running adapter (HttpAdapterHost.init$) and the app's
+   * platform list are known, whichever arrives last (§5.7, LEAD-EXP-3):
+   *   NestFactory     → inside NestFactory.create(), before it resolves: before main.ts code and before init() registers parsers;
+   *   @nestjs/testing → inside createNestApplication(), before it returns.
+   * Use it only for work that must precede body parsing (Express raw capture) or per-request bookkeeping
+   * (Fastify request→reply map). Mount paths are not resolved yet: call ctx.route(pathname) per request.
+   */
+  prepare?(ctx: PlatformPrepareContext): void;
+  /**
+   * Phase 2, required. Called once per auth instance from onModuleInit, after parsers, main.ts middleware/CORS,
+   * MiddlewareConsumer middleware and controller routes are registered, and before Nest's 404/error handlers.
+   * Route every method for binding.basePath and binding.basePath/* to binding.handle(). May be async. Failures of
+   * handle() must reach the host's error pipeline at REQUEST time (H8), even if routes are registered eagerly.
+   */
+  mount(ctx: PlatformMountContext): void | Promise<void>;
+  /** Per-request access for transports running on this platform (HTTP controllers, GraphQL over HTTP). */
+  readonly requests: HttpRequestAccessor;
+  /** How the platform resolves the client IP behind proxies (boot summary, W_PROXY_* warnings; §6.8). */
+  proxyTrust?(adapter: AbstractHttpAdapter): ProxyTrust;
+  /** Optional boot-time checks (throw BetterAuthConfigurationError to fail fast). */
+  validate?(adapter: AbstractHttpAdapter): void;
+  /**
+   * Native controller routes and resolved auth bindings. Called after Nest has registered routes and auth mounts are resolved,
+   * before the application starts accepting requests. Platforms own route-grammar matching for controller precedence.
+   */
+  applicationRoutes?(routes: readonly ApplicationRouteDescriptor[], bindings: readonly AuthRouteBinding[]): void;
+  /** Optional boot advice (§4). */
+  advise?(ctx: BootAdviceContext): readonly BootAdvice[] | Promise<readonly BootAdvice[]>;
+}
+interface ApplicationRouteDescriptor {
+  /** Nest RequestMethod name (GET, POST, ALL, ...). */
+  readonly method: string;
+  /** Paths resolved by Nest's RoutePathFactory, including module/global prefixes and URI versions. */
+  readonly paths: readonly string[];
+  /** Conditions evaluated inside the selected controller route after Express body parsing. */
+  readonly conditions: readonly ("host" | "version")[];
+  /** Controller and method name for boot diagnostics. */
+  readonly source: string;
+}
+interface ProxyTrust {
+  /**
+   * 'none': the socket address is the client IP (behind a proxy, every client shares the proxy's IP);
+   * 'all': every forwarded hop is trusted (clients can choose their IP); 'partial': hop count, subnet list or function;
+   * 'unknown': the platform cannot tell.
+   */
+  readonly mode: "none" | "all" | "partial" | "unknown";
+  readonly detail: string;
+}
+interface PlatformPrepareContext {
+  readonly adapter: AbstractHttpAdapter;
+  readonly logger: LoggerService;
+  /** The binding whose base path matches this raw (undecoded, query-less) pathname; undefined before mount or if none. */
+  route(pathname: string): AuthRouteBinding | undefined;
+}
+interface PlatformMountContext {
+  readonly adapter: AbstractHttpAdapter;
+  readonly logger: LoggerService;
+  readonly binding: AuthRouteBinding;
+}
+interface AuthRouteBinding {
+  readonly instance: string;
+  /** Normalized mount path: no trailing slash; never '/' unless allowRootMount. */
+  readonly basePath: string;
+  readonly bodyLimit: number;
+  /** Static baseURL origin (e.g. 'https://api.example.com'), or undefined for unset/dynamic baseURL. */
+  readonly staticOrigin: string | undefined;
+  /** pathname === basePath || pathname.startsWith(basePath + '/'), on the raw pathname. */
+  matches(pathname: string): boolean;
+  /**
+   * Core exchange (§6.3). Resolves a Response for every better-auth outcome; rejects with BetterAuthInfrastructureError,
+   * or with the original APIError when the instance sets onAPIError.throw (§6.10).
+   */
+  handle(inbound: InboundAuthRequest): Promise<Response>;
+  /** Canonical 413: better-auth's error shape { code: 'PAYLOAD_TOO_LARGE', message }. */
+  payloadTooLarge(): Response;
+}
+interface InboundAuthRequest {
+  readonly method: string;
+  /** Absolute URL: platform trust-proxy-aware origin + the ORIGINAL path and query (never a rewritten req.url). */
+  readonly url: string;
+  /** Original headers as Web Headers (toWebHeaders drops pseudo-headers); never rewritten by the platform. */
+  readonly headers: Headers;
+  /** Exact bytes (<= bodyLimit), or a stream core buffers up to bodyLimit, or null when there is no body. */
+  readonly body: Uint8Array | ReadableStream<Uint8Array> | null;
+  /** Client IP from the platform's own trust-proxy resolution; never read from a raw header by core. */
+  readonly clientIp: string | null;
+  /** Opaque; passed to AuthHandlerInterceptor. */
+  readonly platformRequest: unknown;
+  /** Aborted on client disconnect. */
+  readonly signal?: AbortSignal;
+}
+interface HttpRequestAccessor {
+  /**
+   * Is `value` this platform's request object, as frameworks layered on HTTP hand it on (Express: an IncomingMessage carrying `res`;
+   * Fastify: a request whose `raw` is an IncomingMessage)? A WebSocket upgrade request, or an object a user's GraphQL context built,
+   * is not. GraphQL transports take the HTTP branch only on a positive answer (§9.2).
+   */
+  isRequest(value: unknown): boolean;
+  /**
+   * REQUIRED since v6: is the response to this request still unsent (Express: !req.res.writableEnded; Fastify: the reply of request.raw
+   * is not sent; a Web-native platform: !c.finalized)? GraphQL transports refuse a context whose request already finished, which a context
+   * object or a caching context function shared across requests carries (§9.2). It was optional in v5, so a third-party platform silently
+   * lost the runtime half of that defense with no boot or runtime signal — including this document's own Hono sketch, which omitted it.
+   * It is a security defense, not a convenience, and two lines on every platform.
+   */
+  isLive(req: unknown): boolean;
+  /** Stable identity of one request for guards, pipes, interceptors and GraphQL (Fastify: request.raw). */
+  key(req: unknown): object;
+  /** Request headers as Web Headers (pseudo-headers dropped). */
+  headers(req: unknown): Headers;
+  /** Method and absolute URL (trust-proxy-aware origin, original path). DPoP-bound tokens and the origin check need both. */
+  request(req: unknown): {
+    readonly method: string;
+    readonly url: string;
+  };
+  /** Trust-proxy-aware client IP, or null. */
+  clientIp(req: unknown): string | null;
+  /** Route param. */
+  param(req: unknown, name: string): string | undefined;
+  /** Sink writing Set-Cookie onto the native response; null if unreachable. */
+  cookieSink(req: unknown, res: unknown): CookieSink | null;
+  /** Locate the native response for a request when a framework dropped it (Apollo on Fastify, LEAD-V8). */
+  responseFor?(req: unknown): unknown | undefined;
+}
+interface CookieSink {
+  /** Append each value as its own Set-Cookie header. Returns false (and writes nothing) if headers were already sent. */
+  append(setCookies: readonly string[]): boolean;
+}
+interface AuthTransport {
+  /** Diagnostics only. */
+  readonly id: string;
+  /**
+   * Adapter-owned, side-effect free predicate (e.g. ctx.getType() === 'graphql' plus shape probes). It must not depend on the
+   * presence of credentials: a context without credentials is still this transport's (T1).
+   */
+  handles(context: ExecutionContext): boolean;
+  /**
+   * Build a synchronous, side-effect-free envelope whenever handles() accepted the context; never throw merely because credentials,
+   * an upgrade request or a live platform request cannot be extracted. key/invocation/lineage are structural. Deferred request-dependent
+   * getters (headers, browser, cookies, request, clientIp) throw the original configuration error only when consumed.
+   */
+  describe(context: ExecutionContext, kit: TransportKit): TransportCall;
+  /** Turn a denial into what this transport's runtime delivers correctly (thrown by the guard). */
+  toException(failure: AuthFailure, context: ExecutionContext): unknown;
+  /**
+   * Optional: what to throw for a request-time infrastructure or configuration error. Default: the error itself (HTTP, WS
+   * and RPC runtimes already answer a generic 500 / "Internal server error"). GraphQL returns a generic error with
+   * extensions, because drivers expose error messages to clients. `repeated` is true when an earlier invocation of the same logical
+   * request already surfaced this error: return something the runtime delivers identically but does not log (an IntrinsicException),
+   * so one outage costs one ERROR line per request, not one per aliased field (§13.4).
+   */
+  toInternalException?(error: BetterAuthInfrastructureError | BetterAuthConfigurationError, context: ExecutionContext, info: {
+    readonly repeated: boolean;
+  }): unknown;
+  /**
+   * Optional boot step: claim every handler this transport serves, with how BetterAuthGuard reaches it (ctx.claim). Core applies
+   * one coverage rule to the claims (§5.4 B16). A transport may also throw BetterAuthConfigurationError for its own prerequisites.
+   */
+  validate?(ctx: TransportValidationContext): void | Promise<void>;
+  /**
+   * Optional: 'inherit' marks a NESTED handler, one that runs only inside an operation this transport already authorized (GraphQL field
+   * resolvers). For a nested handler the planner ignores class-level access, acceptance and requirement metadata; method-level metadata
+   * gives it a real plan, and without any it inherits (§7.6 step 3). An entry point of an operation (a GraphQL root field, a federation
+   * reference resolver) is never nested. The planner asks every registered transport; the first answer wins.
+   *
+   */
+  defaultAccessFor?(target: Function, method: string): "inherit" | undefined;
+  /**
+   * Optional, synchronous, side-effect free: the lineage of this invocation (TransportCall.lineage) without building the whole call.
+   * The guard asks for it on public plans, which select no transport otherwise, to record "no identity" for the invocations nested in
+   * a public operation, and on inherit plans, to check that an enclosing invocation recorded a reading (§7.1, §7.8). Transports without
+   * nesting omit it.
+   */
+  lineage?(context: ExecutionContext): InvocationLineage | undefined;
+  /** better-auth prerequisites. hostlessCalls: this transport's calls carry no Host header (RPC), so a dynamic baseURL needs a fallback (B20). */
+  readonly requires?: {
+    readonly hostlessCalls?: boolean;
+  };
+  /** Optional boot advice (§4). */
+  advise?(ctx: BootAdviceContext): readonly BootAdvice[] | Promise<readonly BootAdvice[]>;
+}
+interface TransportCall {
+  /**
+   * Identity of ONE logical request: the HTTP request (GraphQL queries and mutations over HTTP share it), a GraphQL operation carried by a WebSocket,
+   * a WS message, an RPC message. Scope of the principal memo and of policies' I/O memo.
+   */
+  readonly key: object;
+  /**
+   * Identity of ONE handler invocation, chosen by the transport: the finest object that is distinct for each invocation of the
+   * handler, including invocations the transport reaches in parallel from one entry point, for which an operation-level object
+   * would be shared. Built-in choices: HTTP = the request; GraphQL = the field's `info` object (distinct per root field, alias
+   * and batched operation), except where one `info` serves several parallel invocations, where it is the per-invocation input
+   * the transport passes instead (the GraphQL units use the representation, gql.getRoot(), for federation reference resolvers,
+   * §9.2, T7); WS = the per-message args array; RPC = the message context. Scope of authorization decisions and per-invocation
+   * values. Never a connection.
+   */
+  readonly invocation: object;
+  /** Connection identity for principal reuse (WS socket, subscription connection); used only when principalTtlMs > 0. */
+  readonly connection?: object;
+  /** Reuse an authenticated/absent principal on `connection` for this long, for plans whose freshness is not 'authoritative' (§7.2). Default 0. */
+  readonly principalTtlMs?: number;
+  /**
+   * Where this invocation sits inside an enclosing operation (GraphQL fields), so that readers of a nested invocation take the reading of
+   * the nearest enclosing invocation whose guard decided (§7.8). Replaces v3's carrier, whose map by memo key let a field read a
+   * sibling root field's principal. Absent for transports whose invocations do not nest (HTTP, WS, RPC).
+   */
+  readonly lineage?: InvocationLineage;
+  /**
+   * Credentials as Web Headers, plus the leg's `host`, `x-forwarded-host` and `x-forwarded-proto` when the transport has a request or an
+   * upgrade request (better-auth resolves a dynamic base URL from them, even where a user mapping replaced the credentials). Core then
+   * strips any inbound client-IP header and sets it from clientIp. Throws a request-time configuration error when extraction is unavailable; public scope creation never calls it.
+   */
+  headers(): Headers;
+  /** Trust-proxy-aware client IP when the transport knows it (HTTP); null otherwise. */
+  readonly clientIp: string | null;
+  /** null = this transport cannot deliver Set-Cookie: core suppresses session refresh (§7.4). */
+  readonly cookies: CookieSink | null;
+  /** Method and URL when the transport has them (DPoP-bound tokens need both). */
+  readonly request?: {
+    readonly method: string;
+    readonly url: string;
+  };
+  /** Named input for policies: route param, GraphQL arg, WS/RPC payload field. */
+  param(name: string): unknown;
+  /** The browser leg of this operation, for the origin check (§7.10). Absent when no browser can reach it (RPC). */
+  readonly browser?: BrowserExposure;
+}
+interface BrowserExposure {
+  /**
+   * Cookie-mode enforcement classification only (form mode always enforces, regardless of this value). The operation is unsafe: HTTP methods other than GET/HEAD/OPTIONS, GraphQL mutations over HTTP, and EVERY
+   * operation carried by a WebSocket (messages; GraphQL subscriptions, queries and mutations over graphql-ws), because a cross-site
+   * socket can read replies.
+   */
+  readonly enforce: boolean;
+  /**
+   * The headers the browser itself sent on this leg: the request, or the WebSocket upgrade / handshake request. Never values a
+   * transport copied from handshake.auth, connectionParams, _connectionInit, payloads or query strings.
+   */
+  headers(): Headers;
+  /** Absolute URL of the leg (scheme://host/path; WebSocket transports use upgradeRequestUrl). */
+  readonly url: string;
+  /** Identity of the leg (the HTTP request, the socket, the upgrade request): the origin verdict is computed once per leg. */
+  readonly key: object;
+}
+/** Where an invocation sits inside an operation, for readers of nested invocations (§7.8). */
+interface InvocationLineage {
+  /** One of ctx.getArgs(), shared by every invocation of the operation (the GraphQL context). Readings are recorded on it under a Symbol.for slot. */
+  readonly carrier: object;
+  /**
+   * This invocation's position, a string the transport derives from the invocation's own args. GraphQL: an id of `info.operation`
+   * (batched operations can share a context) plus the serialized response path of `info.path`, list indexes included, e.g.
+   * `'1:reports.0.owner'`. Aliases give distinct paths. Federation reference resolvers, whose representations share the `_entities`
+   * field's `info`, take `'<op>:_entities#<__typename>'`: invocations of one handler plan in one request, whose readings are identical
+   * (§9.2).
+   */
+  readonly position: string;
+  /**
+   * Positions of the invocations that enclose the invocation whose args are given, nearest first (GraphQL: walking `info.path.prev`).
+   * It is a function of the args alone, so the guard can record it on the carrier and param factories, which have no DI access, can
+   * walk the lineage too. Every enclosing invocation completes its guard run before a nested one starts: GraphQL resolves a field
+   * before it executes the field's selections.
+   */
+  readonly enclosing: (args: readonly unknown[]) => Iterable<string>;
+  /**
+   * Optional transport-owned validation before exposing an authenticated reading from this lineage. Structural lineage() never
+   * runs it. GraphQL units provide the current invocation's request-liveness check; readers without DI obtain the callback from
+   * the recorded carrier metadata, supplying their own args (never a closure over a sibling/finished request).
+   */
+  readonly assertReadable?: (args: readonly unknown[]) => void;
+}
+interface TransportKit {
+  /** Accessor of the running app's HTTP platform (for transports layered on HTTP, e.g. GraphQL); null without one. */
+  readonly http: HttpRequestAccessor | null;
+}
+interface TransportValidationContext {
+  readonly discovery: DiscoveryService;
+  readonly reflector: Reflector;
+  readonly moduleRef: ModuleRef;
+  readonly hasHttpAdapter: boolean;
+  /** Compiled plan of a handler (class + method). */
+  readonly planOf: (target: Function, method: string) => RoutePlan;
+  /**
+   * Declare a handler this transport serves and how BetterAuthGuard reaches it. `method` undefined claims a class whose handlers the
+   * transport could not enumerate (a class-level decorator is then required). Core decides coverage (§5.4 B16).
+   */
+  claim(target: Function, method: string | undefined, reach: GuardReach, options: ClaimOptions): void;
+  readonly logger: LoggerService;
+}
+/**
+ * 'global': the app's global guards reach the handler: covered when they include BetterAuthGuard, however registered or overridden.
+ * BetterAuthScopeInterceptor is not part of global coverage; absence is B31's warning, including globalScope: false. (§5.4 B16)
+ *
+ * 'explicit': @UseBetterAuth(), or BOTH @UseGuards(BetterAuthGuard) and @UseInterceptors(BetterAuthScopeInterceptor), must apply locally.
+ * 'none': no guard ever runs for it (GraphQL field resolvers without fieldResolverEnhancers: ['guards']).
+ */
+type GuardReach = "global" | "explicit" | "none";
+interface ClaimOptions {
+  /** Stable code of the coverage report, e.g. 'GATEWAY_UNGUARDED'. */
+  readonly code: string;
+  /** Copy-paste fix, e.g. 'Add @UseBetterAuth() (or @Public() to opt out); global guards do not reach gateways on NestJS 11.' */
+  readonly hint: string;
+  /** Severity when the handler is not covered. Default 'error'. */
+  readonly coverage?: "error" | "warn" | "off";
+  /** true: every handler needs coverage, even one without library metadata (gateways, hybrid message handlers). false: only handlers that declare something (§5.4 B16). Default false. */
+  readonly everyHandler?: boolean;
+  /**
+   * Names of the handler's inputs that ctx.param(name) can read, as far as the transport knows them statically: HTTP route params,
+   * GraphQL @Args names. Core passes them to boot advice (AdvisedHandler.inputs) and never interprets them. Default [].
+   */
+  readonly inputs?: readonly string[];
+}
+interface AuthPrincipalBase {
+  readonly kind: string;
+  /** PrincipalSource.id that produced it. */
+  readonly source: string;
+  /** The better-auth user this principal acts for; null for machine or organization principals. */
+  readonly userId: string | null;
+  /**
+   * Present when the principal acts with a NARROWER grant than its owner's rights (API key, OAuth token). Built-in policies
+   * AND it with the owner's rights (Z5); a policy that does not name the principal's kind never receives it.
+   */
+  readonly delegation?: PrincipalDelegation;
+}
+interface PrincipalDelegation {
+  /** Does the credential's own grant include these permissions? (api-key: role(key.permissions).authorize) */
+  allows(permissions: Readonly<Record<string, readonly string[]>>): boolean;
+  /** Diagnostics, e.g. 'api-key permissions', 'oauth scopes'. */
+  readonly description: string;
+}
+interface PrincipalSource<P extends AuthPrincipalBase = AuthPrincipal> {
+  readonly id: string;
+  /** The principal kinds this source produces. Data: core compares them with the route's accepted kinds (§7.6). */
+  readonly kinds: readonly P["kind"][];
+  /**
+   * 'default': accepted on every authenticated route of the instance. 'explicit': only where a route (@AcceptPrincipals) or a
+   * requirement's policy names one of its kinds. Default 'explicit', so a new source never widens existing routes.
+   */
+  readonly acceptance?: "default" | "explicit";
+  /**
+   * Request headers this source reads credentials from (e.g. ['x-api-key']). The cookie bridge compares them (§7.5), and their
+   * values are redacted from error causes (§13.4). They play no part in the origin check (§7.10).
+   */
+  readonly credentialHeaders?: readonly string[];
+  /** Side effects of one resolution (drive boot advice, e.g. quota consumption per WS message). */
+  readonly effects?: {
+    readonly consumesQuota?: boolean;
+    readonly writes?: boolean;
+  };
+  /**
+   * The principal IS better-auth's session read of the request's headers (auth.api.getSession). Only then does a generic "no session"
+   * 401 that a policy's later better-auth call meets contradict the principal, and only then does the evaluator re-read through this
+   * source to tell a lost session from a swallowed storage failure (§8.1). The built-in session source sets it; a source that
+   * authenticates by other means (API keys, OAuth tokens) must not. Default false.
+   */
+  readonly sessionBacked?: boolean;
+  /**
+   * The principals this source produces carry `delegation` (API keys, OAuth tokens). Data for B15: a requirement whose policy names no kinds
+   * judges only non-delegated principals (§8.1), so at boot it admits exactly the kinds of the instance's sources that do not delegate.
+   * S-delegation checks the declaration against the principals the source produces. Default false.
+   */
+  readonly delegates?: boolean;
+  /**
+   * better-auth plugins this source needs, checked at boot with $context.hasPlugin (B13); hostlessCalls: some of its auth.api calls
+   * carry no Host header whatever the transport, so a dynamic baseURL needs a fallback (B20).
+   */
+  readonly requires?: {
+    readonly plugins?: readonly string[];
+    readonly hostlessCalls?: boolean;
+  };
+  /** Cheap synchronous sniffing (e.g. a header is present). false = skip without I/O. Default: true. */
+  appliesTo?(request: PrincipalRequest): boolean;
+  /**
+   * Denials are values: return authenticated(p), absent() (no credential this source understands) or
+   * rejected(failure) (a credential was presented and is invalid). A throw means infrastructure (5xx).
+   */
+  resolve(request: PrincipalRequest): Promise<PrincipalResult<P>>;
+  /** Optional boot advice (§4). */
+  advise?(ctx: BootAdviceContext): readonly BootAdvice[] | Promise<readonly BootAdvice[]>;
+}
+type PrincipalResult<P extends AuthPrincipalBase = AuthPrincipal> = {
+  readonly outcome: "authenticated";
+  readonly principal: P;
+} | {
+  readonly outcome: "absent";
+} | {
+  readonly outcome: "rejected";
+  readonly failure: AuthFailure;
+};
+interface PrincipalRequest {
+  readonly headers: Headers;
+  readonly cookies: CookieSink | null;
+  readonly transport: string;
+  readonly request?: {
+    readonly method: string;
+    readonly url: string;
+  };
+  readonly freshness: "default" | "authoritative";
+  readonly auth: AuthHandle;
+  /** Memo per logical request (e.g. one verifyApiKey per request: it consumes quota). */
+  memo<T>(key: string | object | symbol, compute: () => Promise<T>): Promise<T>;
+}
+/** What extensions receive instead of the raw instance. [A][C] */
+interface AuthHandle<A extends AuthLike = AuthLike> {
+  readonly name: string;
+  readonly instance: A;
+  readonly api: A["api"];
+  context(): Promise<AuthContextView>;
+  hasPlugin(id: string): Promise<boolean>;
+  /** Run auth.api calls inside a scope: cookie capability, forwarding mode, internal flag (§7.4, §7.5, §10.4). */
+  run<T>(init: ScopeInit, fn: () => Promise<T>): Promise<T>;
+  /** Origin/form rule for a browser leg (§7.10): null on pass/nonapplication, else denial; memoized per leg. browser.enforce gates cookie mode only; false never bypasses form mode. */
+  checkOrigin(browser: BrowserExposure, mode: "cookie" | "form"): Promise<AuthFailure | null>;
+  /**
+   * Did a better-auth endpoint itself produce `value` in a dispatch the plugin observed while bound, as opposed to a before-hook
+   * short-circuit (LEAD-V37, LEAD-EXP-8)? Authoritative identity reads accept only such sessions (§7.3).
+   */
+  producedByEndpoint(value: unknown): boolean;
+  /** Is `origin` trusted by this instance (post-init set; function-valued trustedOrigins get `request`)? (§6.9) */
+  isTrustedOrigin(origin: string, request?: Request): Promise<boolean>;
+}
+interface ScopeInit {
+  /** null = cannot write cookies → the plugin suppresses session refresh for every call in fn. */
+  readonly cookies: CookieSink | null;
+  /**
+   * Set-Cookie forwarding through the plugin's bridge for calls in fn. 'same-credential' (default): only calls that carry the
+   * scope's credential (see `inbound`) or none; 'any': every call; 'none': no forwarding.
+   */
+  readonly forward?: "none" | "same-credential" | "any";
+  /** The inbound request's headers, the credential 'same-credential' compares against. */
+  readonly inbound?: () => Headers;
+  /** Mark calls as library-internal (HookOptions.skipInternal). Default false. */
+  readonly internal?: boolean;
+}
+/** The subset of better-auth's AuthContext the library reads (structural: any version in range fits). [C] */
+interface AuthContextView {
+  readonly baseURL: string;
+  readonly trustedOrigins: readonly string[];
+  readonly skipCSRFCheck: boolean;
+  readonly skipOriginCheck: boolean | readonly string[];
+  /** The resolved signing secret; B29 compares it with better-auth's public default (LEAD-V48). */
+  readonly secret: string;
+  /** better-auth's resolved rate limiter; B30 reports it off in production (LEAD-V52). */
+  readonly rateLimit: {
+    readonly enabled: boolean;
+  };
+  readonly options: {
+    readonly baseURL?: unknown;
+    readonly basePath?: string;
+    readonly database?: unknown;
+    readonly secondaryStorage?: unknown;
+    /** `enabled` is undefined unless the user set it (B30 tells an explicit false from better-auth's NODE_ENV default). */
+    readonly rateLimit?: {
+      readonly enabled?: boolean;
+    };
+    readonly trustedOrigins?: readonly string[] | ((request?: Request) => unknown);
+    readonly plugins?: readonly {
+      readonly id: string;
+      readonly hooks?: {
+        readonly after?: readonly unknown[];
+      };
+    }[];
+    readonly onAPIError?: {
+      readonly throw?: boolean;
+    };
+    readonly advanced?: {
+      readonly ipAddress?: {
+        readonly ipAddressHeaders?: readonly string[];
+        readonly trustedProxies?: readonly string[];
+      };
+      readonly disableOriginCheck?: boolean;
+      readonly disableCSRFCheck?: boolean;
+      readonly cookiePrefix?: string;
+    };
+  };
+  /** The admin policy's owner-row read for delegated principals (the ban rule), the call userHasPermission itself makes (LEAD-V45). */
+  readonly internalAdapter: {
+    findUserById(userId: string): Promise<{
+      readonly id: string;
+      readonly role?: string | null;
+      readonly banned?: boolean | null;
+      readonly banExpires?: Date | string | null;
+    } | null>;
+  };
+  readonly authCookies: Readonly<Record<"sessionToken" | "sessionData" | "dontRememberToken" | "accountData", {
+    readonly name: string;
+    readonly attributes: {
+      readonly domain?: string;
+      readonly path?: string;
+    };
+  }>>;
+  readonly sessionConfig: {
+    readonly freshAge: number;
+    readonly updateAge: number;
+    readonly expiresIn: number;
+  };
+  readonly adapter: {
+    findOne(input: {
+      model: string;
+      where: readonly {
+        field: string;
+        value: unknown;
+      }[];
+    }): Promise<unknown>;
+    updateMany(input: {
+      model: string;
+      where: readonly {
+        field: string;
+        value: unknown;
+      }[];
+      update: Record<string, unknown>;
+    }): Promise<number>;
+  };
+  hasPlugin(id: string): boolean;
+  getPlugin(id: string): unknown;
+  isTrustedOrigin(url: string, settings?: {
+    allowRelativePaths: boolean;
+  }): boolean;
+}
+interface AuthorizationPolicy<Params = unknown, P extends AuthPrincipalBase = AuthPrincipal> {
+  /** Diagnostic id ('better-auth:admin/permission'); never used for dispatch. */
+  readonly id: string;
+  readonly requires?: {
+    /** better-auth plugin ids validated at boot through $context.hasPlugin (B13). */
+    readonly plugins?: readonly string[];
+    /**
+     * Principal kinds this policy can judge; others are denied 403 PRINCIPAL_NOT_SUPPORTED (data-driven, no core branch).
+     * Naming a kind also ADMITS it on routes that use the policy (§7.6). Omitted: any kind WITHOUT `delegation`; delegated
+     * principals are denied 403 PRINCIPAL_NOT_SUPPORTED, so a policy must opt in to judging them (Z5). At boot such a policy admits
+     * exactly the kinds of the instance's sources that do not declare `delegates` (B15).
+     */
+    readonly principals?: readonly P["kind"][];
+    /** The decision needs an identity read that bypasses the cookie cache (admin-grade decisions): raises the route's freshness (§8.4). */
+    readonly freshIdentity?: boolean;
+    /** The policy calls better-auth with the request's credential headers, so credential hooks re-run per call (api-key quota). Boot advice only. */
+    readonly presentsCredentials?: boolean;
+    /** Some of the policy's auth.api calls carry no Host header (e.g. userHasPermission without headers), so a dynamic baseURL needs a fallback (B20). */
+    readonly hostlessCalls?: boolean;
+  };
+  /** Denials are values. Throw only for infrastructure faults (they become 5xx, never 403). */
+  evaluate(params: Params, context: AuthorizationContext<P>): AuthorizationDecision | Promise<AuthorizationDecision>;
+  /** Optional boot validation of params (e.g. empty permission maps). Throw BetterAuthConfigurationError. */
+  validate?(params: Params, boot: PolicyBootContext): void | Promise<void>;
+  /** Optional boot advice (§4). */
+  advise?(ctx: BootAdviceContext): readonly BootAdvice[] | Promise<readonly BootAdvice[]>;
+}
+/**
+ * A policy value, or a provider class/token resolved through ModuleRef (for DI-backed policies). Whatever the ref, the planner, the
+ * evaluator and B14 see the same resolved instance (U19), so `requires` declared as an instance field reaches the plan.
+ */
+type PolicyRef<Params> = AuthorizationPolicy<Params, any> | Type<AuthorizationPolicy<Params, any>> | InjectionToken;
+interface Requirement<Params = unknown> {
+  readonly policy: PolicyRef<Params>;
+  readonly params: Params;
+  readonly label?: string;
+  /** Overrides policy.requires.principals for this requirement (e.g. permission(p, { principals })). */
+  readonly principals?: readonly string[];
+  /** Overrides policy.requires.freshIdentity for this requirement. */
+  readonly freshIdentity?: boolean;
+}
+type RequirementExpr = Requirement | {
+  readonly anyOf: readonly RequirementExpr[];
+} | {
+  readonly allOf: readonly RequirementExpr[];
+};
+type AuthorizationDecision = {
+  readonly effect: "allow";
+} | {
+  readonly effect: "deny";
+  readonly status?: 401 | 403;
+  readonly reason: string;
+  readonly message?: string;
+  readonly challenge?: string;
+};
+interface AuthorizationContext<P extends AuthPrincipalBase = AuthPrincipal> {
+  readonly principal: P;
+  readonly instance: string;
+  readonly transport: string;
+  readonly headers: Headers;
+  readonly cookies: CookieSink | null;
+  readonly request?: {
+    readonly method: string;
+    readonly url: string;
+  };
+  param(name: string): unknown;
+  readonly handler: {
+    readonly class: Type;
+    readonly method: string;
+  };
+  readonly auth: AuthHandle;
+  /**
+   * Memo per LOGICAL REQUEST (HTTP request, WS message, …), never per connection: dedupe better-auth I/O by concrete inputs,
+   * serialized as a tuple, e.g. `JSON.stringify(['org:hasPermission', orgId, stablePermissions])`, so no input can collide with another key's sentinel. Decisions themselves are never shared across invocations.
+   */
+  memo<T>(key: string | object | symbol, compute: () => Promise<T>): Promise<T>;
+  /** Publish a per-invocation value for defineInvocationParam decorators (e.g. the resolved organization id). */
+  provide(slot: symbol, value: unknown): void;
+  readonly execution: ExecutionContext;
+}
+interface PolicyBootContext {
+  readonly auth: AuthHandle;
+  readonly context: AuthContextView;
+  readonly site: string;
+}
+//#endregion
+export { PrincipalDelegation as $, ErrorMappingOptions as $n, SESSION_PRINCIPAL_KIND as $t, DatabaseHookTarget as A, BetterAuthService as An, GetSessionWithHeaders as At, HookOptions as B, WS_CONNECTION_AUTH as Bn, UnvalidatedBody as Bt, ConformanceCase as C, defineHttpPlatform as Cn, AuthPrincipal as Ct, CookieForwardingOptions as D, allow as Dn, DatabaseHookMethod as Dt, ConformanceSkip as E, BetterAuthGuard as En, DatabaseHookData as Et, ExtensionDefinition as F, BetterAuthModule as Fn, Register as Ft, InboundAuthRequest as G, AuthErrorBody as Gn, betterAuthCorsOrigin as Gt, HttpMountOptions as H, getBetterAuthInstanceToken as Hn, WithActiveOrganization as Ht, ExtensionRef as I, GUARD_CORE as In, RegisteredAuth as It, PlatformMountContext as J, AuthFailures as Jn, definePrincipalSource as Jt, InvocationLineage as K, AuthErrorCode as Kn, absent as Kt, FastifyPlatformOptions as L, POLICY_INVOKER as Ln, RegisteredInstances as Lt, DbHookOptions as M, InstanceLookup as Mn, OrgPermissions as Mt, DefaultInstanceCheck as N, EXTENSION_DEFINITION as Nn, PrincipalKind as Nt, CookieSink as O, definePolicy as On, DatabaseHookResult as Ot, ExpressPlatformOptions as P, UPGRADE_REQUEST as Pn, PrincipalOfKind as Pt, PolicyRef as Q, BetterAuthInfrastructureError as Qn, RequireFreshSession as Qt, GuardReach as R, PRINCIPAL_RESOLVER as Rn, SessionOf as Rt, ClaimOptions as S, defineExtension as Sn, AuthOf as St, ConformanceRunner as T, BetterAuthScopeInterceptor as Tn, AuthUser as Tt, HttpPlatform as U, getBetterAuthOptionsToken as Un, PrincipalKinds as Ut, HookPredicate as V, getBetterAuthHandleToken as Vn, UserOf as Vt, HttpRequestAccessor as W, getBetterAuthServiceToken as Wn, httpTransport as Wt, PolicyBootContext as X, AuthTransportErrorPayload as Xn, CurrentSession as Xt, PlatformPrepareContext as Y, AuthGraphqlExtensions as Yn, rejected as Yt, PolicyInvoker as Z, BetterAuthConfigurationError as Zn, CurrentUser as Zt, BetterAuthRuntimeOptions as _, allOf as _n, TransportValidationContext as _t, AuthHandlerInterceptor as a, BeforeAuth as an, ProxyTrust as at, BootAdviceContext as b, definePrincipalParam as bn, AuthHookContext as bt, AuthTransport as c, ForwardAuthCookies as cn, RequirementOptions as ct, AuthorizationLimits as d, Require as dn, ScopeInit as dt, freshSession as en, getRawCause as er, PrincipalReading as et, AuthorizationPolicy as f, RequireAuth as fn, SessionOption as ft, BetterAuthModuleOptions as g, UseBetterAuth as gn, TransportKit as gt, BetterAuthModuleAsyncOptions as h, UseAuthInstance as hn, TransportCall as ht, AuthHandle as i, AfterDatabase as in, PrincipalSource as it, DbHookMethodDecorator as j, TransportRegistry as jn, IsRegistered as jt, CorsOriginOptions as k, deny as kn, EndpointPath as kt, AuthorizationContext as l, OptionalAuth as ln, ResolutionRequest as lt, BetterAuthFactoryResult as m, SkipOriginCheck as mn, StaticOptionMustBePassedToForRootAsync as mt, ApplicationRouteDescriptor as n, AcceptPrincipals as nn, isConfigurationError as nr, PrincipalResolver as nt, AuthPrincipalBase as o, BeforeDatabase as on, Requirement as ot, BetterAuthAppOptions as p, SkipDefaultRequirements as pn, SessionPrincipalOptions as pt, OriginCheckOptions as q, AuthFailure as qn, authenticated as qt, AuthContextView as r, AfterAuth as rn, isInfrastructureError as rr, PrincipalResult as rt, AuthRouteBinding as s, CurrentPrincipal as sn, RequirementExpr as st, AdvisedHandler as t, sessionPrincipal as tn, isAuthFailure as tr, PrincipalRequest as tt, AuthorizationDecision as u, Public as un, RoutePlan as ut, BetterAuthStaticOptions as v, anyOf as vn, AdminPermissions as vt, ConformanceOutcome as w, defineTransport as wn, AuthSession as wt, BrowserExposure as x, requirement as xn, AuthLike as xt, BootAdvice as y, defineInvocationParam as yn, AuthAfterHookContext as yt, HookMethodDecorator as z, SCOPE_CORE as zn, SessionPrincipal as zt };
+//# sourceMappingURL=auth-contracts-Brh_Qko9.d.cts.map