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

package/dist/testing.cjs

@@ -0,0 +1,221 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_auth_errors = require("./auth-errors-DmiKl0L_.cjs");
+const require_decorate = require("./decorate-Cr4Q7bNE.cjs");
+const require_auth_scope_interceptor = require("./auth-scope-interceptor-BjxAL1-S.cjs");
+const require_bridge_protocol = require("./bridge-protocol-BDw8opAG.cjs");
+const require_principal_readings = require("./principal-readings-Chmt6rQV.cjs");
+let rxjs = require("rxjs");
+//#region src/testing.ts
+const TEST_APP = Symbol.for("@nestjs-kit/better-auth:test-app");
+const TEST_APP_CLOSE = Symbol.for("@nestjs-kit/better-auth:test-app-close");
+const TEST_OVERRIDES = Symbol.for("@nestjs-kit/better-auth:test-overrides");
+const PLUGIN_ID = "@nestjs-kit/better-auth";
+const TEST_PRINCIPAL_SOURCE = "@nestjs-kit/better-auth:test-principal";
+/**
+* TestingModuleBuilder keys overrides by token, so repeated helper calls share one provider and its configuration.
+* The configuration lives on the builder under a global symbol, so the ESM and CommonJS copies of this entry compose.
+*/
+function overridesOf(builder) {
+	let overrides = Reflect.get(builder, TEST_OVERRIDES);
+	if (!overrides) {
+		overrides = {
+			principals: /* @__PURE__ */ new Map(),
+			deciders: []
+		};
+		Object.defineProperty(builder, TEST_OVERRIDES, { value: overrides });
+	}
+	return overrides;
+}
+/** Make app.close() run Nest's shutdown once, whoever calls it: initTestApp, a registered hook or the test. */
+function closeOnce(app) {
+	const existing = Reflect.get(app, TEST_APP_CLOSE);
+	if (existing) return existing;
+	const close = app.close.bind(app);
+	let pending;
+	const once = () => {
+		pending ??= close();
+		return pending;
+	};
+	Object.defineProperty(app, TEST_APP_CLOSE, { value: once });
+	app.close = once;
+	return once;
+}
+async function bridgeOf(auth) {
+	const plugin = (await auth.$context).getPlugin?.(PLUGIN_ID);
+	return plugin && typeof plugin === "object" ? Reflect.get(plugin, require_bridge_protocol.BRIDGE_HANDLE) : void 0;
+}
+function registryOf(app) {
+	try {
+		return app.get(require_decorate.INSTANCE_REGISTRY, { strict: false });
+	} catch {
+		return;
+	}
+}
+/**
+* init() plus Fastify ready() when the adapter exposes it. Before init, closes the previous application that
+* initTestApp initialized for the same Better Auth instance and that is still bound to it: an instance binds
+* exclusively to one application (B06). A failed init() leaves its binding for the next application, which takes it
+* over with W_INSTANCE_TAKEN_OVER. app.close() becomes idempotent, and `closeWith` receives it: a per-test cleanup such as
+* Vitest's onTestFinished or node:test's t.after, or a list that a suite-level afterEach drains (Jest registers no hooks
+* while a test runs). Without `closeWith`, close the last application yourself. On Express, compile one TestingModule per application: a
+* second application of one container fails init() with APP_ADAPTER_CHANGED.
+*/
+async function initTestApp(app, options = {}) {
+	const close = closeOnce(app);
+	const bridges = [];
+	for (const registration of registryOf(app)?.registrations() ?? []) {
+		const bridge = registration.instance ? await bridgeOf(registration.instance) : void 0;
+		if (!bridge) continue;
+		const previous = Reflect.get(bridge, TEST_APP);
+		if (previous && previous !== app && bridge.state === "bound") await previous.close();
+		Object.defineProperty(bridge, TEST_APP, {
+			value: void 0,
+			configurable: true,
+			writable: true
+		});
+		bridges.push(bridge);
+	}
+	await app.init();
+	const server = (app.getHttpAdapter?.())?.getInstance?.();
+	if (typeof server?.ready === "function") await server.ready();
+	for (const bridge of bridges) Object.defineProperty(bridge, TEST_APP, {
+		value: app,
+		configurable: true,
+		writable: true
+	});
+	options.closeWith?.(close);
+	return app;
+}
+/** Real session headers for `userId` through Better Auth's testUtils() plugin, which the instance must include. */
+async function authHeadersFor(auth, userId) {
+	const context = await auth.$context;
+	if (typeof context.test?.getAuthHeaders !== "function") throw new require_auth_errors.BetterAuthConfigurationError("TEST_UTILS_MISSING", "authHeadersFor requires Better Auth's testUtils() plugin on the instance.", "Add testUtils() from better-auth/plugins to the test instance.");
+	return context.test.getAuthHeaders({ userId });
+}
+/**
+* Replace principal resolution for one instance (default: 'default') without Better Auth I/O. Acceptance, the
+* origin check and policies still run. A policy's re-classification read of a generic 401 answers absent,
+* because the request carries no session; other instances keep the real resolver.
+*/
+function overridePrincipal(builder, principal, options = {}) {
+	const configured = overridesOf(builder).principals;
+	configured.set(options.instance || "default", principal);
+	builder.overrideProvider(require_decorate.PRINCIPAL_RESOLVER).useFactory({
+		inject: [
+			require_decorate.INSTANCE_REGISTRY,
+			require_decorate.REQUEST_SCOPE,
+			require_decorate.TRANSPORT_REGISTRY
+		],
+		factory: (instances, scope, transports) => {
+			const real = new require_auth_scope_interceptor.ChainPrincipalResolver(instances, scope, transports);
+			return { resolve(call, request) {
+				if (!configured.has(request.auth.name)) return real.resolve(call, request);
+				if (request.reclassify) return Promise.resolve(require_auth_scope_interceptor.absent());
+				const fixed = configured.get(request.auth.name);
+				const value = typeof fixed === "function" ? fixed(call) : fixed;
+				return Promise.resolve(value ? require_auth_scope_interceptor.authenticated(value) : require_auth_scope_interceptor.absent());
+			} };
+		}
+	});
+	return builder;
+}
+/**
+* Replace the policy invoker: `decide` answers per requirement, and undefined runs the real policy. Acceptance,
+* the delegation gate, the origin check and the decision memo still run. Later calls are consulted after earlier ones.
+*/
+function overrideDecisions(builder, decide) {
+	const configured = overridesOf(builder).deciders;
+	configured.push(decide);
+	builder.overrideProvider(require_decorate.POLICY_INVOKER).useValue({ async invoke(policy, params, context) {
+		for (const decider of configured) {
+			const decision = await decider(policy.id, params, context.principal);
+			if (decision !== void 0) return decision;
+		}
+		return policy.evaluate(params, context);
+	} });
+	return builder;
+}
+/** A principal source that answers a fixed principal (or null for absent), for test module composition. */
+function testPrincipal(principal, options = {}) {
+	const fixed = typeof principal === "function" ? void 0 : principal;
+	const id = fixed?.source ?? TEST_PRINCIPAL_SOURCE;
+	return {
+		id,
+		kinds: options.kinds ?? (fixed ? [fixed.kind] : ["session"]),
+		acceptance: options.acceptance ?? "default",
+		delegates: options.delegates ?? Boolean(fixed?.delegation),
+		async resolve(request) {
+			const value = typeof principal === "function" ? principal(request) : principal;
+			return value ? require_auth_scope_interceptor.authenticated({
+				...value,
+				source: id
+			}) : require_auth_scope_interceptor.absent();
+		}
+	};
+}
+/**
+* Publish a principal for this invocation from a hand-written guard. The stamp lives on ctx.getArgs() and its
+* object elements. Readers accept it from the same args array (WS, RPC and GraphQL share it between guards and
+* interceptors) or from another array with the same elements when at least two elements are objects (an HTTP request
+* and its response); a lone shared element such as a socket never identifies an invocation. Pass `instance` for
+* handlers of a named instance.
+*/
+function stampPrincipal(context, principal, options = {}) {
+	require_principal_readings.stampResult(context.getArgs(), options.instance || "default", principal ? require_auth_scope_interceptor.authenticated(principal) : require_auth_scope_interceptor.absent());
+}
+var StampFirstReadings = class extends require_principal_readings.PrincipalReadings {
+	read(input) {
+		return (input.plan && input.plan.access !== "public" ? require_principal_readings.stampedReading(input.args, input.plan.instance) : void 0) ?? super.read(input);
+	}
+};
+function planInstance(planner, context) {
+	try {
+		return planner.forContext(context).instance;
+	} catch {
+		return "default";
+	}
+}
+/**
+* Replace the guard and scope bodies everywhere with one override each of GUARD_CORE and SCOPE_CORE: the APP_GUARD
+* alias and every @UseBetterAuth()/@UseGuards(BetterAuthGuard) site delegate to the same collaborator, which
+* overrideProvider(BetterAuthGuard) plus overrideGuard(BetterAuthGuard) cannot achieve. With `{ principal }` the
+* stand-in stamps the principal (for the handler's instance) and allows; with a CanActivate, that guard runs as the
+* whole guard body and may call stampPrincipal(); an object with a canActivate method is always treated as a guard,
+* even when it also has a `principal` property. The stand-in interceptor opens the same transport-described scope
+* as the real one, reading the test stamp first, so readers and BetterAuthService perform no Better Auth I/O.
+*/
+function overrideAuthGuard(builder, impl) {
+	builder.overrideProvider(require_decorate.GUARD_CORE).useFactory({
+		inject: [require_decorate.ROUTE_PLANNER],
+		factory: (planner) => ({ async canActivate(context) {
+			if (typeof impl.canActivate === "function") {
+				const result = impl.canActivate(context);
+				return (0, rxjs.isObservable)(result) ? (0, rxjs.lastValueFrom)(result) : result;
+			}
+			const { principal } = impl;
+			const value = typeof principal === "function" ? principal(context) : principal;
+			require_principal_readings.stampResult(context.getArgs(), planInstance(planner, context), value ? require_auth_scope_interceptor.authenticated(value) : require_auth_scope_interceptor.absent());
+			return true;
+		} })
+	});
+	builder.overrideProvider(require_decorate.SCOPE_CORE).useFactory({
+		inject: [
+			require_decorate.INSTANCE_REGISTRY,
+			require_decorate.ROUTE_PLANNER,
+			require_decorate.TRANSPORT_REGISTRY,
+			require_decorate.REQUEST_SCOPE
+		],
+		factory: (instances, planner, transports, scope) => new require_auth_scope_interceptor.ScopeCore(instances, planner, transports, scope, new StampFirstReadings(scope))
+	});
+	return builder;
+}
+//#endregion
+exports.authHeadersFor = authHeadersFor;
+exports.initTestApp = initTestApp;
+exports.overrideAuthGuard = overrideAuthGuard;
+exports.overrideDecisions = overrideDecisions;
+exports.overridePrincipal = overridePrincipal;
+exports.stampPrincipal = stampPrincipal;
+exports.testPrincipal = testPrincipal;
+
+//# sourceMappingURL=testing.cjs.map

package/dist/testing.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.cjs","names":["BRIDGE_HANDLE","INSTANCE_REGISTRY","BetterAuthConfigurationError","PRINCIPAL_RESOLVER","REQUEST_SCOPE","TRANSPORT_REGISTRY","ChainPrincipalResolver","absent","authenticated","POLICY_INVOKER","PrincipalReadings","stampedReading","GUARD_CORE","ROUTE_PLANNER","isObservable","lastValueFrom","SCOPE_CORE","ScopeCore"],"sources":["../src/testing.ts"],"sourcesContent":["import type {\n  CanActivate,\n  ExecutionContext,\n  INestApplication,\n} from \"@nestjs/common\";\nimport type { TestingModuleBuilder } from \"@nestjs/testing\";\nimport { isObservable, lastValueFrom } from \"rxjs\";\nimport type {\n  AuthorizationDecision,\n  PolicyInvoker,\n  PrincipalRequest,\n  PrincipalResolver,\n  PrincipalResult,\n  PrincipalSource,\n  TransportCall,\n} from \"./auth-contracts.js\";\nimport { BetterAuthConfigurationError } from \"./auth-errors.js\";\nimport { ScopeCore } from \"./auth-scope-interceptor.js\";\nimport {\n  GUARD_CORE,\n  INSTANCE_REGISTRY,\n  POLICY_INVOKER,\n  PRINCIPAL_RESOLVER,\n  REQUEST_SCOPE,\n  ROUTE_PLANNER,\n  SCOPE_CORE,\n  TRANSPORT_REGISTRY,\n} from \"./auth-tokens.js\";\nimport type { AuthLike, AuthPrincipal } from \"./auth-types.js\";\nimport { BRIDGE_HANDLE, type BridgeHandle } from \"./bridge-protocol.js\";\nimport type { InstanceRegistry } from \"./instance-registry.js\";\nimport {\n  PrincipalReadings,\n  stampedReading,\n  stampResult,\n  type ReadingInput,\n} from \"./principal-readings.js\";\nimport {\n  absent,\n  authenticated,\n  ChainPrincipalResolver,\n} from \"./principal-resolver.js\";\nimport type { RequestScope } from \"./request-scope.js\";\nimport type { RoutePlanner } from \"./route-planner.js\";\nimport type { TransportRegistry } from \"./transport-registry.js\";\n\nconst TEST_APP = Symbol.for(\"@nestjs-kit/better-auth:test-app\");\nconst TEST_APP_CLOSE = Symbol.for(\"@nestjs-kit/better-auth:test-app-close\");\nconst TEST_OVERRIDES = Symbol.for(\"@nestjs-kit/better-auth:test-overrides\");\nconst PLUGIN_ID = \"@nestjs-kit/better-auth\";\nconst TEST_PRINCIPAL_SOURCE = \"@nestjs-kit/better-auth:test-principal\";\n\ntype FixedPrincipal =\n  | AuthPrincipal\n  | null\n  | ((call: TransportCall) => AuthPrincipal | null);\ntype Decide = (\n  policyId: string,\n  params: unknown,\n  principal: AuthPrincipal,\n) =>\n  | AuthorizationDecision\n  | undefined\n  | Promise<AuthorizationDecision | undefined>;\n\ninterface TestOverrides {\n  readonly principals: Map<string, FixedPrincipal>;\n  readonly deciders: Decide[];\n}\n\n/**\n * TestingModuleBuilder keys overrides by token, so repeated helper calls share one provider and its configuration.\n * The configuration lives on the builder under a global symbol, so the ESM and CommonJS copies of this entry compose.\n */\nfunction overridesOf(builder: TestingModuleBuilder): TestOverrides {\n  let overrides = Reflect.get(builder, TEST_OVERRIDES) as\n    | TestOverrides\n    | undefined;\n  if (!overrides) {\n    overrides = { principals: new Map(), deciders: [] };\n    Object.defineProperty(builder, TEST_OVERRIDES, { value: overrides });\n  }\n  return overrides;\n}\n\n/** Make app.close() run Nest's shutdown once, whoever calls it: initTestApp, a registered hook or the test. */\nfunction closeOnce(app: INestApplication): () => Promise<void> {\n  const existing = Reflect.get(app, TEST_APP_CLOSE) as\n    | (() => Promise<void>)\n    | undefined;\n  if (existing) {\n    return existing;\n  }\n  const close = app.close.bind(app);\n  let pending: Promise<void> | undefined;\n  const once = () => {\n    pending ??= close();\n    return pending;\n  };\n  Object.defineProperty(app, TEST_APP_CLOSE, { value: once });\n  app.close = once;\n  return once;\n}\n\nasync function bridgeOf(auth: AuthLike): Promise<BridgeHandle | undefined> {\n  const context = (await auth.$context) as {\n    getPlugin?(id: string): unknown;\n  };\n  const plugin = context.getPlugin?.(PLUGIN_ID);\n  return plugin && typeof plugin === \"object\"\n    ? (Reflect.get(plugin, BRIDGE_HANDLE) as BridgeHandle | undefined)\n    : undefined;\n}\n\nfunction registryOf(app: INestApplication): InstanceRegistry | undefined {\n  try {\n    return app.get<InstanceRegistry>(INSTANCE_REGISTRY, { strict: false });\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * init() plus Fastify ready() when the adapter exposes it. Before init, closes the previous application that\n * initTestApp initialized for the same Better Auth instance and that is still bound to it: an instance binds\n * exclusively to one application (B06). A failed init() leaves its binding for the next application, which takes it\n * over with W_INSTANCE_TAKEN_OVER. app.close() becomes idempotent, and `closeWith` receives it: a per-test cleanup such as\n * Vitest's onTestFinished or node:test's t.after, or a list that a suite-level afterEach drains (Jest registers no hooks\n * while a test runs). Without `closeWith`, close the last application yourself. On Express, compile one TestingModule per application: a\n * second application of one container fails init() with APP_ADAPTER_CHANGED.\n */\nexport async function initTestApp<T extends INestApplication>(\n  app: T,\n  options: { closeWith?: (close: () => Promise<void>) => void } = {},\n): Promise<T> {\n  const close = closeOnce(app);\n  const bridges: BridgeHandle[] = [];\n  for (const registration of registryOf(app)?.registrations() ?? []) {\n    const bridge = registration.instance\n      ? await bridgeOf(registration.instance)\n      : undefined;\n    if (!bridge) {\n      continue;\n    }\n    const previous = Reflect.get(bridge, TEST_APP) as\n      | INestApplication\n      | undefined;\n    if (previous && previous !== app && bridge.state === \"bound\") {\n      // initTestApp made previous.close() idempotent, so a registered close of the same app does nothing later.\n      await previous.close();\n    }\n    Object.defineProperty(bridge, TEST_APP, {\n      value: undefined,\n      configurable: true,\n      writable: true,\n    });\n    bridges.push(bridge);\n  }\n  await app.init();\n  const server = (\n    app.getHttpAdapter?.() as { getInstance?(): unknown } | undefined\n  )?.getInstance?.() as { ready?: () => unknown } | undefined;\n  if (typeof server?.ready === \"function\") {\n    await server.ready();\n  }\n  for (const bridge of bridges) {\n    Object.defineProperty(bridge, TEST_APP, {\n      value: app,\n      configurable: true,\n      writable: true,\n    });\n  }\n  options.closeWith?.(close);\n  return app;\n}\n\n/** Real session headers for `userId` through Better Auth's testUtils() plugin, which the instance must include. */\nexport async function authHeadersFor(\n  auth: AuthLike,\n  userId: string,\n): Promise<Headers> {\n  const context = (await auth.$context) as {\n    test?: { getAuthHeaders?(options: { userId: string }): Promise<Headers> };\n  };\n  if (typeof context.test?.getAuthHeaders !== \"function\") {\n    throw new BetterAuthConfigurationError(\n      \"TEST_UTILS_MISSING\",\n      \"authHeadersFor requires Better Auth's testUtils() plugin on the instance.\",\n      \"Add testUtils() from better-auth/plugins to the test instance.\",\n    );\n  }\n  return context.test.getAuthHeaders({ userId });\n}\n\n/**\n * Replace principal resolution for one instance (default: 'default') without Better Auth I/O. Acceptance, the\n * origin check and policies still run. A policy's re-classification read of a generic 401 answers absent,\n * because the request carries no session; other instances keep the real resolver.\n */\nexport function overridePrincipal(\n  builder: TestingModuleBuilder,\n  principal: FixedPrincipal,\n  options: { instance?: string } = {},\n): TestingModuleBuilder {\n  const configured = overridesOf(builder).principals;\n  configured.set(options.instance || \"default\", principal);\n  builder.overrideProvider(PRINCIPAL_RESOLVER).useFactory({\n    inject: [INSTANCE_REGISTRY, REQUEST_SCOPE, TRANSPORT_REGISTRY],\n    factory: (\n      instances: InstanceRegistry,\n      scope: RequestScope,\n      transports: TransportRegistry,\n    ): PrincipalResolver => {\n      const real = new ChainPrincipalResolver(instances, scope, transports);\n      return {\n        resolve(call, request): Promise<PrincipalResult> {\n          if (!configured.has(request.auth.name)) {\n            return real.resolve(call, request);\n          }\n          if (request.reclassify) {\n            return Promise.resolve(absent());\n          }\n          const fixed = configured.get(request.auth.name);\n          const value = typeof fixed === \"function\" ? fixed(call) : fixed;\n          return Promise.resolve(value ? authenticated(value) : absent());\n        },\n      };\n    },\n  });\n  return builder;\n}\n\n/**\n * Replace the policy invoker: `decide` answers per requirement, and undefined runs the real policy. Acceptance,\n * the delegation gate, the origin check and the decision memo still run. Later calls are consulted after earlier ones.\n */\nexport function overrideDecisions(\n  builder: TestingModuleBuilder,\n  decide: Decide,\n): TestingModuleBuilder {\n  const configured = overridesOf(builder).deciders;\n  configured.push(decide);\n  const invoker: PolicyInvoker = {\n    async invoke(policy, params, context) {\n      for (const decider of configured) {\n        const decision = await decider(policy.id, params, context.principal);\n        if (decision !== undefined) {\n          return decision;\n        }\n      }\n      return policy.evaluate(params, context);\n    },\n  };\n  builder.overrideProvider(POLICY_INVOKER).useValue(invoker);\n  return builder;\n}\n\n/** A principal source that answers a fixed principal (or null for absent), for test module composition. */\nexport function testPrincipal(\n  principal: AuthPrincipal | ((req: PrincipalRequest) => AuthPrincipal | null),\n  options: {\n    kinds?: readonly string[];\n    acceptance?: \"default\" | \"explicit\";\n    delegates?: boolean;\n  } = {},\n): PrincipalSource {\n  const fixed = typeof principal === \"function\" ? undefined : principal;\n  const id = fixed?.source ?? TEST_PRINCIPAL_SOURCE;\n  const kinds = options.kinds ?? (fixed ? [fixed.kind] : [\"session\"]);\n  return {\n    id,\n    kinds: kinds as PrincipalSource[\"kinds\"],\n    acceptance: options.acceptance ?? \"default\",\n    delegates: options.delegates ?? Boolean(fixed?.delegation),\n    async resolve(request) {\n      const value =\n        typeof principal === \"function\" ? principal(request) : principal;\n      return value\n        ? authenticated({ ...value, source: id } as AuthPrincipal)\n        : absent();\n    },\n  };\n}\n\n/**\n * Publish a principal for this invocation from a hand-written guard. The stamp lives on ctx.getArgs() and its\n * object elements. Readers accept it from the same args array (WS, RPC and GraphQL share it between guards and\n * interceptors) or from another array with the same elements when at least two elements are objects (an HTTP request\n * and its response); a lone shared element such as a socket never identifies an invocation. Pass `instance` for\n * handlers of a named instance.\n */\nexport function stampPrincipal(\n  context: ExecutionContext,\n  principal: AuthPrincipal | null,\n  options: { instance?: string } = {},\n): void {\n  stampResult(\n    context.getArgs(),\n    options.instance || \"default\",\n    principal ? authenticated(principal) : absent(),\n  );\n}\n\nclass StampFirstReadings extends PrincipalReadings {\n  override read(input: ReadingInput) {\n    const stamped =\n      input.plan && input.plan.access !== \"public\"\n        ? stampedReading(input.args, input.plan.instance)\n        : undefined;\n    return stamped ?? super.read(input);\n  }\n}\n\nfunction planInstance(planner: RoutePlanner, context: ExecutionContext) {\n  try {\n    return planner.forContext(context).instance;\n  } catch {\n    return \"default\";\n  }\n}\n\n/**\n * Replace the guard and scope bodies everywhere with one override each of GUARD_CORE and SCOPE_CORE: the APP_GUARD\n * alias and every @UseBetterAuth()/@UseGuards(BetterAuthGuard) site delegate to the same collaborator, which\n * overrideProvider(BetterAuthGuard) plus overrideGuard(BetterAuthGuard) cannot achieve. With `{ principal }` the\n * stand-in stamps the principal (for the handler's instance) and allows; with a CanActivate, that guard runs as the\n * whole guard body and may call stampPrincipal(); an object with a canActivate method is always treated as a guard,\n * even when it also has a `principal` property. The stand-in interceptor opens the same transport-described scope\n * as the real one, reading the test stamp first, so readers and BetterAuthService perform no Better Auth I/O.\n */\nexport function overrideAuthGuard(\n  builder: TestingModuleBuilder,\n  impl:\n    | CanActivate\n    | {\n        principal:\n          | AuthPrincipal\n          | null\n          | ((ctx: ExecutionContext) => AuthPrincipal | null);\n      },\n): TestingModuleBuilder {\n  builder.overrideProvider(GUARD_CORE).useFactory({\n    inject: [ROUTE_PLANNER],\n    factory: (planner: RoutePlanner) => ({\n      async canActivate(context: ExecutionContext): Promise<boolean> {\n        // A CanActivate may hold its own `principal` field; its canActivate always runs.\n        if (typeof (impl as Partial<CanActivate>).canActivate === \"function\") {\n          const result = (impl as CanActivate).canActivate(context);\n          return isObservable(result) ? lastValueFrom(result) : result;\n        }\n        const { principal } = impl as {\n          principal:\n            | AuthPrincipal\n            | null\n            | ((ctx: ExecutionContext) => AuthPrincipal | null);\n        };\n        const value =\n          typeof principal === \"function\" ? principal(context) : principal;\n        stampResult(\n          context.getArgs(),\n          planInstance(planner, context),\n          value ? authenticated(value) : absent(),\n        );\n        return true;\n      },\n    }),\n  });\n  builder.overrideProvider(SCOPE_CORE).useFactory({\n    inject: [\n      INSTANCE_REGISTRY,\n      ROUTE_PLANNER,\n      TRANSPORT_REGISTRY,\n      REQUEST_SCOPE,\n    ],\n    factory: (\n      instances: InstanceRegistry,\n      planner: RoutePlanner,\n      transports: TransportRegistry,\n      scope: RequestScope,\n    ) =>\n      new ScopeCore(\n        instances,\n        planner,\n        transports,\n        scope,\n        new StampFirstReadings(scope),\n      ),\n  });\n  return builder;\n}\n"],"mappings":"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"}

package/dist/testing.d.cts

@@ -0,0 +1,64 @@
+import { Ct as AuthPrincipal, ht as TransportCall, it as PrincipalSource, tt as PrincipalRequest, u as AuthorizationDecision, xt as AuthLike } from "./auth-contracts-Brh_Qko9.cjs";
+import { CanActivate, ExecutionContext, INestApplication } from "@nestjs/common";
+import { TestingModuleBuilder } from "@nestjs/testing";
+//#region src/testing.d.ts
+type FixedPrincipal = AuthPrincipal | null | ((call: TransportCall) => AuthPrincipal | null);
+type Decide = (policyId: string, params: unknown, principal: AuthPrincipal) => AuthorizationDecision | undefined | Promise<AuthorizationDecision | undefined>;
+/**
+ * init() plus Fastify ready() when the adapter exposes it. Before init, closes the previous application that
+ * initTestApp initialized for the same Better Auth instance and that is still bound to it: an instance binds
+ * exclusively to one application (B06). A failed init() leaves its binding for the next application, which takes it
+ * over with W_INSTANCE_TAKEN_OVER. app.close() becomes idempotent, and `closeWith` receives it: a per-test cleanup such as
+ * Vitest's onTestFinished or node:test's t.after, or a list that a suite-level afterEach drains (Jest registers no hooks
+ * while a test runs). Without `closeWith`, close the last application yourself. On Express, compile one TestingModule per application: a
+ * second application of one container fails init() with APP_ADAPTER_CHANGED.
+ */
+export declare function initTestApp<T extends INestApplication>(app: T, options?: {
+  closeWith?: (close: () => Promise<void>) => void;
+}): Promise<T>;
+/** Real session headers for `userId` through Better Auth's testUtils() plugin, which the instance must include. */
+export declare function authHeadersFor(auth: AuthLike, userId: string): Promise<Headers>;
+/**
+ * Replace principal resolution for one instance (default: 'default') without Better Auth I/O. Acceptance, the
+ * origin check and policies still run. A policy's re-classification read of a generic 401 answers absent,
+ * because the request carries no session; other instances keep the real resolver.
+ */
+export declare function overridePrincipal(builder: TestingModuleBuilder, principal: FixedPrincipal, options?: {
+  instance?: string;
+}): TestingModuleBuilder;
+/**
+ * Replace the policy invoker: `decide` answers per requirement, and undefined runs the real policy. Acceptance,
+ * the delegation gate, the origin check and the decision memo still run. Later calls are consulted after earlier ones.
+ */
+export declare function overrideDecisions(builder: TestingModuleBuilder, decide: Decide): TestingModuleBuilder;
+/** A principal source that answers a fixed principal (or null for absent), for test module composition. */
+export declare function testPrincipal(principal: AuthPrincipal | ((req: PrincipalRequest) => AuthPrincipal | null), options?: {
+  kinds?: readonly string[];
+  acceptance?: "default" | "explicit";
+  delegates?: boolean;
+}): PrincipalSource;
+/**
+ * Publish a principal for this invocation from a hand-written guard. The stamp lives on ctx.getArgs() and its
+ * object elements. Readers accept it from the same args array (WS, RPC and GraphQL share it between guards and
+ * interceptors) or from another array with the same elements when at least two elements are objects (an HTTP request
+ * and its response); a lone shared element such as a socket never identifies an invocation. Pass `instance` for
+ * handlers of a named instance.
+ */
+export declare function stampPrincipal(context: ExecutionContext, principal: AuthPrincipal | null, options?: {
+  instance?: string;
+}): void;
+/**
+ * Replace the guard and scope bodies everywhere with one override each of GUARD_CORE and SCOPE_CORE: the APP_GUARD
+ * alias and every @UseBetterAuth()/@UseGuards(BetterAuthGuard) site delegate to the same collaborator, which
+ * overrideProvider(BetterAuthGuard) plus overrideGuard(BetterAuthGuard) cannot achieve. With `{ principal }` the
+ * stand-in stamps the principal (for the handler's instance) and allows; with a CanActivate, that guard runs as the
+ * whole guard body and may call stampPrincipal(); an object with a canActivate method is always treated as a guard,
+ * even when it also has a `principal` property. The stand-in interceptor opens the same transport-described scope
+ * as the real one, reading the test stamp first, so readers and BetterAuthService perform no Better Auth I/O.
+ */
+export declare function overrideAuthGuard(builder: TestingModuleBuilder, impl: CanActivate | {
+  principal: AuthPrincipal | null | ((ctx: ExecutionContext) => AuthPrincipal | null);
+}): TestingModuleBuilder;
+//#endregion
+export {};
+//# sourceMappingURL=testing.d.cts.map

package/dist/testing.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.cts","names":[],"sources":["../src/testing.ts"],"mappings":";;;;KAoDK,iBACD,yBAEE,MAAM,kBAAkB;KACzB,UACH,kBACA,iBACA,WAAW,kBAET,oCAEA,QAAQ;;;;;;;;;;wBAoEU,YAAY,UAAU,kBAC1C,KAAK,GACL;EAAW,aAAa,aAAa;IACpC,QAAQ;;wBA2CW,eACpB,MAAM,UACN,iBACC,QAAQ;;;;;;wBAmBK,kBACd,SAAS,sBACT,WAAW,gBACX;EAAW;IACV;;;;;wBAiCa,kBACd,SAAS,sBACT,QAAQ,SACP;;wBAmBa,cACd,WAAW,kBAAkB,KAAK,qBAAqB,uBACvD;EACE;EACA;EACA;IAED;;;;;;;;wBA0Ba,eACd,SAAS,kBACT,WAAW,sBACX;EAAW;;;;;;;;;;;wBAoCG,kBACd,SAAS,sBACT,MACI;EAEE,WACI,yBAEE,KAAK,qBAAqB;IAErC"}

package/dist/testing.d.mts

@@ -0,0 +1,64 @@
+import { Ct as AuthPrincipal, ht as TransportCall, it as PrincipalSource, tt as PrincipalRequest, u as AuthorizationDecision, xt as AuthLike } from "./auth-contracts-Cz7C4_Ch.mjs";
+import { CanActivate, ExecutionContext, INestApplication } from "@nestjs/common";
+import { TestingModuleBuilder } from "@nestjs/testing";
+//#region src/testing.d.ts
+type FixedPrincipal = AuthPrincipal | null | ((call: TransportCall) => AuthPrincipal | null);
+type Decide = (policyId: string, params: unknown, principal: AuthPrincipal) => AuthorizationDecision | undefined | Promise<AuthorizationDecision | undefined>;
+/**
+ * init() plus Fastify ready() when the adapter exposes it. Before init, closes the previous application that
+ * initTestApp initialized for the same Better Auth instance and that is still bound to it: an instance binds
+ * exclusively to one application (B06). A failed init() leaves its binding for the next application, which takes it
+ * over with W_INSTANCE_TAKEN_OVER. app.close() becomes idempotent, and `closeWith` receives it: a per-test cleanup such as
+ * Vitest's onTestFinished or node:test's t.after, or a list that a suite-level afterEach drains (Jest registers no hooks
+ * while a test runs). Without `closeWith`, close the last application yourself. On Express, compile one TestingModule per application: a
+ * second application of one container fails init() with APP_ADAPTER_CHANGED.
+ */
+export declare function initTestApp<T extends INestApplication>(app: T, options?: {
+  closeWith?: (close: () => Promise<void>) => void;
+}): Promise<T>;
+/** Real session headers for `userId` through Better Auth's testUtils() plugin, which the instance must include. */
+export declare function authHeadersFor(auth: AuthLike, userId: string): Promise<Headers>;
+/**
+ * Replace principal resolution for one instance (default: 'default') without Better Auth I/O. Acceptance, the
+ * origin check and policies still run. A policy's re-classification read of a generic 401 answers absent,
+ * because the request carries no session; other instances keep the real resolver.
+ */
+export declare function overridePrincipal(builder: TestingModuleBuilder, principal: FixedPrincipal, options?: {
+  instance?: string;
+}): TestingModuleBuilder;
+/**
+ * Replace the policy invoker: `decide` answers per requirement, and undefined runs the real policy. Acceptance,
+ * the delegation gate, the origin check and the decision memo still run. Later calls are consulted after earlier ones.
+ */
+export declare function overrideDecisions(builder: TestingModuleBuilder, decide: Decide): TestingModuleBuilder;
+/** A principal source that answers a fixed principal (or null for absent), for test module composition. */
+export declare function testPrincipal(principal: AuthPrincipal | ((req: PrincipalRequest) => AuthPrincipal | null), options?: {
+  kinds?: readonly string[];
+  acceptance?: "default" | "explicit";
+  delegates?: boolean;
+}): PrincipalSource;
+/**
+ * Publish a principal for this invocation from a hand-written guard. The stamp lives on ctx.getArgs() and its
+ * object elements. Readers accept it from the same args array (WS, RPC and GraphQL share it between guards and
+ * interceptors) or from another array with the same elements when at least two elements are objects (an HTTP request
+ * and its response); a lone shared element such as a socket never identifies an invocation. Pass `instance` for
+ * handlers of a named instance.
+ */
+export declare function stampPrincipal(context: ExecutionContext, principal: AuthPrincipal | null, options?: {
+  instance?: string;
+}): void;
+/**
+ * Replace the guard and scope bodies everywhere with one override each of GUARD_CORE and SCOPE_CORE: the APP_GUARD
+ * alias and every @UseBetterAuth()/@UseGuards(BetterAuthGuard) site delegate to the same collaborator, which
+ * overrideProvider(BetterAuthGuard) plus overrideGuard(BetterAuthGuard) cannot achieve. With `{ principal }` the
+ * stand-in stamps the principal (for the handler's instance) and allows; with a CanActivate, that guard runs as the
+ * whole guard body and may call stampPrincipal(); an object with a canActivate method is always treated as a guard,
+ * even when it also has a `principal` property. The stand-in interceptor opens the same transport-described scope
+ * as the real one, reading the test stamp first, so readers and BetterAuthService perform no Better Auth I/O.
+ */
+export declare function overrideAuthGuard(builder: TestingModuleBuilder, impl: CanActivate | {
+  principal: AuthPrincipal | null | ((ctx: ExecutionContext) => AuthPrincipal | null);
+}): TestingModuleBuilder;
+//#endregion
+export {};
+//# sourceMappingURL=testing.d.mts.map

package/dist/testing.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.mts","names":[],"sources":["../src/testing.ts"],"mappings":";;;;KAoDK,iBACD,yBAEE,MAAM,kBAAkB;KACzB,UACH,kBACA,iBACA,WAAW,kBAET,oCAEA,QAAQ;;;;;;;;;;wBAoEU,YAAY,UAAU,kBAC1C,KAAK,GACL;EAAW,aAAa,aAAa;IACpC,QAAQ;;wBA2CW,eACpB,MAAM,UACN,iBACC,QAAQ;;;;;;wBAmBK,kBACd,SAAS,sBACT,WAAW,gBACX;EAAW;IACV;;;;;wBAiCa,kBACd,SAAS,sBACT,QAAQ,SACP;;wBAmBa,cACd,WAAW,kBAAkB,KAAK,qBAAqB,uBACvD;EACE;EACA;EACA;IAED;;;;;;;;wBA0Ba,eACd,SAAS,kBACT,WAAW,sBACX;EAAW;;;;;;;;;;;wBAoCG,kBACd,SAAS,sBACT,MACI;EAEE,WACI,yBAEE,KAAK,qBAAqB;IAErC"}

package/dist/testing.mjs

@@ -0,0 +1,214 @@
+import { n as BetterAuthConfigurationError } from "./auth-errors-C3rbTV9p.mjs";
+import { C as PRINCIPAL_RESOLVER, D as ROUTE_PLANNER, M as TRANSPORT_REGISTRY, O as SCOPE_CORE, T as REQUEST_SCOPE, f as GUARD_CORE, m as INSTANCE_REGISTRY, y as POLICY_INVOKER } from "./decorate-Dt0e9K6R.mjs";
+import { a as absent, n as ScopeCore, o as authenticated, r as ChainPrincipalResolver } from "./auth-scope-interceptor-DYPn3b8M.mjs";
+import { t as BRIDGE_HANDLE } from "./bridge-protocol-c66aEkr5.mjs";
+import { n as stampResult, r as stampedReading, t as PrincipalReadings } from "./principal-readings-Ied2staw.mjs";
+import { isObservable, lastValueFrom } from "rxjs";
+//#region src/testing.ts
+const TEST_APP = Symbol.for("@nestjs-kit/better-auth:test-app");
+const TEST_APP_CLOSE = Symbol.for("@nestjs-kit/better-auth:test-app-close");
+const TEST_OVERRIDES = Symbol.for("@nestjs-kit/better-auth:test-overrides");
+const PLUGIN_ID = "@nestjs-kit/better-auth";
+const TEST_PRINCIPAL_SOURCE = "@nestjs-kit/better-auth:test-principal";
+/**
+* TestingModuleBuilder keys overrides by token, so repeated helper calls share one provider and its configuration.
+* The configuration lives on the builder under a global symbol, so the ESM and CommonJS copies of this entry compose.
+*/
+function overridesOf(builder) {
+	let overrides = Reflect.get(builder, TEST_OVERRIDES);
+	if (!overrides) {
+		overrides = {
+			principals: /* @__PURE__ */ new Map(),
+			deciders: []
+		};
+		Object.defineProperty(builder, TEST_OVERRIDES, { value: overrides });
+	}
+	return overrides;
+}
+/** Make app.close() run Nest's shutdown once, whoever calls it: initTestApp, a registered hook or the test. */
+function closeOnce(app) {
+	const existing = Reflect.get(app, TEST_APP_CLOSE);
+	if (existing) return existing;
+	const close = app.close.bind(app);
+	let pending;
+	const once = () => {
+		pending ??= close();
+		return pending;
+	};
+	Object.defineProperty(app, TEST_APP_CLOSE, { value: once });
+	app.close = once;
+	return once;
+}
+async function bridgeOf(auth) {
+	const plugin = (await auth.$context).getPlugin?.(PLUGIN_ID);
+	return plugin && typeof plugin === "object" ? Reflect.get(plugin, BRIDGE_HANDLE) : void 0;
+}
+function registryOf(app) {
+	try {
+		return app.get(INSTANCE_REGISTRY, { strict: false });
+	} catch {
+		return;
+	}
+}
+/**
+* init() plus Fastify ready() when the adapter exposes it. Before init, closes the previous application that
+* initTestApp initialized for the same Better Auth instance and that is still bound to it: an instance binds
+* exclusively to one application (B06). A failed init() leaves its binding for the next application, which takes it
+* over with W_INSTANCE_TAKEN_OVER. app.close() becomes idempotent, and `closeWith` receives it: a per-test cleanup such as
+* Vitest's onTestFinished or node:test's t.after, or a list that a suite-level afterEach drains (Jest registers no hooks
+* while a test runs). Without `closeWith`, close the last application yourself. On Express, compile one TestingModule per application: a
+* second application of one container fails init() with APP_ADAPTER_CHANGED.
+*/
+async function initTestApp(app, options = {}) {
+	const close = closeOnce(app);
+	const bridges = [];
+	for (const registration of registryOf(app)?.registrations() ?? []) {
+		const bridge = registration.instance ? await bridgeOf(registration.instance) : void 0;
+		if (!bridge) continue;
+		const previous = Reflect.get(bridge, TEST_APP);
+		if (previous && previous !== app && bridge.state === "bound") await previous.close();
+		Object.defineProperty(bridge, TEST_APP, {
+			value: void 0,
+			configurable: true,
+			writable: true
+		});
+		bridges.push(bridge);
+	}
+	await app.init();
+	const server = (app.getHttpAdapter?.())?.getInstance?.();
+	if (typeof server?.ready === "function") await server.ready();
+	for (const bridge of bridges) Object.defineProperty(bridge, TEST_APP, {
+		value: app,
+		configurable: true,
+		writable: true
+	});
+	options.closeWith?.(close);
+	return app;
+}
+/** Real session headers for `userId` through Better Auth's testUtils() plugin, which the instance must include. */
+async function authHeadersFor(auth, userId) {
+	const context = await auth.$context;
+	if (typeof context.test?.getAuthHeaders !== "function") throw new BetterAuthConfigurationError("TEST_UTILS_MISSING", "authHeadersFor requires Better Auth's testUtils() plugin on the instance.", "Add testUtils() from better-auth/plugins to the test instance.");
+	return context.test.getAuthHeaders({ userId });
+}
+/**
+* Replace principal resolution for one instance (default: 'default') without Better Auth I/O. Acceptance, the
+* origin check and policies still run. A policy's re-classification read of a generic 401 answers absent,
+* because the request carries no session; other instances keep the real resolver.
+*/
+function overridePrincipal(builder, principal, options = {}) {
+	const configured = overridesOf(builder).principals;
+	configured.set(options.instance || "default", principal);
+	builder.overrideProvider(PRINCIPAL_RESOLVER).useFactory({
+		inject: [
+			INSTANCE_REGISTRY,
+			REQUEST_SCOPE,
+			TRANSPORT_REGISTRY
+		],
+		factory: (instances, scope, transports) => {
+			const real = new ChainPrincipalResolver(instances, scope, transports);
+			return { resolve(call, request) {
+				if (!configured.has(request.auth.name)) return real.resolve(call, request);
+				if (request.reclassify) return Promise.resolve(absent());
+				const fixed = configured.get(request.auth.name);
+				const value = typeof fixed === "function" ? fixed(call) : fixed;
+				return Promise.resolve(value ? authenticated(value) : absent());
+			} };
+		}
+	});
+	return builder;
+}
+/**
+* Replace the policy invoker: `decide` answers per requirement, and undefined runs the real policy. Acceptance,
+* the delegation gate, the origin check and the decision memo still run. Later calls are consulted after earlier ones.
+*/
+function overrideDecisions(builder, decide) {
+	const configured = overridesOf(builder).deciders;
+	configured.push(decide);
+	builder.overrideProvider(POLICY_INVOKER).useValue({ async invoke(policy, params, context) {
+		for (const decider of configured) {
+			const decision = await decider(policy.id, params, context.principal);
+			if (decision !== void 0) return decision;
+		}
+		return policy.evaluate(params, context);
+	} });
+	return builder;
+}
+/** A principal source that answers a fixed principal (or null for absent), for test module composition. */
+function testPrincipal(principal, options = {}) {
+	const fixed = typeof principal === "function" ? void 0 : principal;
+	const id = fixed?.source ?? TEST_PRINCIPAL_SOURCE;
+	return {
+		id,
+		kinds: options.kinds ?? (fixed ? [fixed.kind] : ["session"]),
+		acceptance: options.acceptance ?? "default",
+		delegates: options.delegates ?? Boolean(fixed?.delegation),
+		async resolve(request) {
+			const value = typeof principal === "function" ? principal(request) : principal;
+			return value ? authenticated({
+				...value,
+				source: id
+			}) : absent();
+		}
+	};
+}
+/**
+* Publish a principal for this invocation from a hand-written guard. The stamp lives on ctx.getArgs() and its
+* object elements. Readers accept it from the same args array (WS, RPC and GraphQL share it between guards and
+* interceptors) or from another array with the same elements when at least two elements are objects (an HTTP request
+* and its response); a lone shared element such as a socket never identifies an invocation. Pass `instance` for
+* handlers of a named instance.
+*/
+function stampPrincipal(context, principal, options = {}) {
+	stampResult(context.getArgs(), options.instance || "default", principal ? authenticated(principal) : absent());
+}
+var StampFirstReadings = class extends PrincipalReadings {
+	read(input) {
+		return (input.plan && input.plan.access !== "public" ? stampedReading(input.args, input.plan.instance) : void 0) ?? super.read(input);
+	}
+};
+function planInstance(planner, context) {
+	try {
+		return planner.forContext(context).instance;
+	} catch {
+		return "default";
+	}
+}
+/**
+* Replace the guard and scope bodies everywhere with one override each of GUARD_CORE and SCOPE_CORE: the APP_GUARD
+* alias and every @UseBetterAuth()/@UseGuards(BetterAuthGuard) site delegate to the same collaborator, which
+* overrideProvider(BetterAuthGuard) plus overrideGuard(BetterAuthGuard) cannot achieve. With `{ principal }` the
+* stand-in stamps the principal (for the handler's instance) and allows; with a CanActivate, that guard runs as the
+* whole guard body and may call stampPrincipal(); an object with a canActivate method is always treated as a guard,
+* even when it also has a `principal` property. The stand-in interceptor opens the same transport-described scope
+* as the real one, reading the test stamp first, so readers and BetterAuthService perform no Better Auth I/O.
+*/
+function overrideAuthGuard(builder, impl) {
+	builder.overrideProvider(GUARD_CORE).useFactory({
+		inject: [ROUTE_PLANNER],
+		factory: (planner) => ({ async canActivate(context) {
+			if (typeof impl.canActivate === "function") {
+				const result = impl.canActivate(context);
+				return isObservable(result) ? lastValueFrom(result) : result;
+			}
+			const { principal } = impl;
+			const value = typeof principal === "function" ? principal(context) : principal;
+			stampResult(context.getArgs(), planInstance(planner, context), value ? authenticated(value) : absent());
+			return true;
+		} })
+	});
+	builder.overrideProvider(SCOPE_CORE).useFactory({
+		inject: [
+			INSTANCE_REGISTRY,
+			ROUTE_PLANNER,
+			TRANSPORT_REGISTRY,
+			REQUEST_SCOPE
+		],
+		factory: (instances, planner, transports, scope) => new ScopeCore(instances, planner, transports, scope, new StampFirstReadings(scope))
+	});
+	return builder;
+}
+//#endregion
+export { authHeadersFor, initTestApp, overrideAuthGuard, overrideDecisions, overridePrincipal, stampPrincipal, testPrincipal };
+
+//# sourceMappingURL=testing.mjs.map