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

package/dist/testing/conformance.d.cts

@@ -0,0 +1,528 @@
+import { An as BetterAuthService, C as ConformanceCase, Ct as AuthPrincipal, E as ConformanceSkip, I as ExtensionRef, T as ConformanceRunner, U as HttpPlatform, c as AuthTransport, it as PrincipalSource, st as RequirementExpr, w as ConformanceOutcome, xt as AuthLike } from "../auth-contracts-Brh_Qko9.cjs";
+import { IncomingHttpHeaders } from "node:http";
+import { INestApplication, LoggerService, Provider } from "@nestjs/common";
+import { AbstractHttpAdapter, NestFactory } from "@nestjs/core";
+import { BetterAuthOptions, BetterAuthPlugin } from "better-auth";
+import { TestingModuleBuilder } from "@nestjs/testing";
+//#region src/conformance-fixtures.d.ts
+/** The trusted origin the probe plugin contributes through init(), so origin cases see the post-init set. */
+export declare const PROBE_TRUSTED_ORIGIN = "https://probe-plugin.example";
+/**
+ * The conformance kits' Better Auth probe: byte-exact echo, multi-cookie, redirect, stream, HTML, method, URL
+ * and IP endpoints under /probe, a before hook that counts dispatches and injects faults, an after hook that
+ * records refresh suppression and the Set-Cookie lines each call produced, database write counters, a storage
+ * instrument that counts and faults every database adapter operation, and https://probe-plugin.example as a trusted
+ * origin contributed through init(). Put it before nestjs() in the plugin list.
+ */
+export declare function conformanceProbePlugin(): BetterAuthPlugin;
+/**
+ * Better Auth's origin-check flags of a conformance instance. Both default to false, so every origin check is on; a
+ * caller's `options.advanced` cannot change them, only this argument can.
+ */
+interface ConformanceAuthSettings {
+  /**
+   * Better Auth's advanced.disableOriginCheck. true skips Better Auth's own origin validation of its routes; with
+   * disableCSRFCheck false the library's application-route checks stay on (BA-r6-01, T-csrf-http-unsafe).
+   */
+  readonly disableOriginCheck?: boolean;
+  /** Better Auth's advanced.disableCSRFCheck. true switches every origin check off, the library's included. */
+  readonly disableCSRFCheck?: boolean;
+}
+/**
+ * A memory-adapter Better Auth instance with the settings the kits assume: origin checks explicitly on
+ * (advanced.disableOriginCheck: false, which vitest's TEST=true would otherwise switch off, and
+ * advanced.disableCSRFCheck: false, which would otherwise switch every origin check off), session.updateAge 0 so
+ * every session read refreshes, testUtils(), bearer(), conformanceProbePlugin() and nestjs() last. The kit settings
+ * win over the same options in `options`; `settings` switches the origin checks off explicitly.
+ */
+export declare function createConformanceAuth(options?: Omit<BetterAuthOptions, "database">, settings?: ConformanceAuthSettings): AuthLike;
+/**
+ * Register cases with a runner that has describe/it (vitest, jest, node:test). Cases are grouped by id. A case with
+ * `skip` registers a passing test whose name states the reason, so every unsupported capability stays visible. A case
+ * that skips at run time calls the runner's context.skip(reason) when the runner passes a context (Vitest, node:test);
+ * under Jest it passes.
+ */
+export declare function runConformance(cases: readonly ConformanceCase[], runner: ConformanceRunner): void;
+//#endregion
+//#region src/conformance-http.d.ts
+interface HttpConformanceOptions {
+  platform: ExtensionRef<HttpPlatform>;
+  /** Fresh Nest HTTP adapter per app, e.g. () => new ExpressAdapter(). */
+  createHttpAdapter(): AbstractHttpAdapter;
+  /** Bootstraps to exercise. Default both. */
+  bootstrap?: readonly ("factory" | "testing")[];
+  /** Enable host CORS the platform's usual way. Default: app.enableCors({ origin, credentials: true }). */
+  enableHostCors?(app: INestApplication, origin: string): void | Promise<void>;
+  /**
+   * Configure trust in one forwarding hop on a created application the platform's usual way, e.g. app.set('trust proxy',
+   * 1). The trusted-hop rows (H-ip-platform, H-proxy-trust, H-url-trust-proxy, H-proxy-untrusted-warning) need this or
+   * createTrustingHttpAdapter; without either they are skipped with the reason.
+   */
+  trustOneProxy?(app: INestApplication): void | Promise<void>;
+  /**
+   * A fresh adapter that already trusts one forwarding hop, for platforms whose proxy trust is fixed when the adapter is
+   * constructed, e.g. () => new FastifyAdapter({ trustProxy: 'loopback' }). The kit's requests come from loopback, so
+   * trusting loopback is trusting one hop. Trusted-hop boots use it when given, instead of createHttpAdapter plus
+   * trustOneProxy.
+   */
+  createTrustingHttpAdapter?(): AbstractHttpAdapter;
+  /**
+   * HTTP/2 variant, required when the platform declares capabilities.http2. Its createTrustingHttpAdapter serves the
+   * HTTP/2 trusted-hop rows as createTrustingHttpAdapter serves the HTTP/1.1 ones.
+   */
+  http2?: {
+    createHttpAdapter(): AbstractHttpAdapter;
+    createTrustingHttpAdapter?(): AbstractHttpAdapter;
+  };
+  /** How to obtain a base URL. Default: app.listen(0) + getUrl(). */
+  listen?(app: INestApplication): Promise<string>;
+  /**
+   * Transport options for the H-no-adapter microservice rows, e.g. () => ({ transport: Transport.TCP, options: { host:
+   * '127.0.0.1', port: 0 } }). The kit does not load the optional @nestjs/microservices peer itself; without this option
+   * those rows are skipped with the reason.
+   */
+  microservice?(): MicroserviceOptions;
+}
+/** The options NestFactory.createMicroservice() and TestingModule.createNestMicroservice() accept. */
+type MicroserviceOptions = NonNullable<Parameters<typeof NestFactory.createMicroservice>[1]>;
+/**
+ * The HTTP platform kit (invariants H1–H14). Each case boots a real Nest application per bootstrap with a real Better
+ * Auth instance that includes conformanceProbePlugin(), an app controller, a @BeforeAuth() hook provider, a recording
+ * global filter and an `around` recorder. HTTP/2 is required when the platform declares capabilities.http2. A platform
+ * without the capability or the optional proxyTrust(), and a harness with neither trustOneProxy nor
+ * createTrustingHttpAdapter for the trusted-hop rows, get a skip with the reason: before the run for platform objects,
+ * at run time for classes and definitions. The microservice rows of H-no-adapter need the
+ * `microservice` option. Production-mode rows set process.env.NODE_ENV to 'production' while they run and restore it,
+ * so run the cases sequentially.
+ */
+export declare function httpPlatformConformance(options: HttpConformanceOptions): ConformanceCase[];
+//#endregion
+//#region src/conformance-transport.d.ts
+type InvocationShape = "aliases" | "batched" | "messages" | "subscriptions";
+/** One fixture handler the kit supplies; the harness exposes it as a controller route, resolver field, gateway message or message pattern. */
+interface FixtureHandler {
+  /** Method decorators to apply, in order (access, acceptance, requirements). */
+  readonly decorators: readonly MethodDecorator[];
+  /** Parameter decorators by parameter index, e.g. [CurrentSession()]. */
+  readonly params: readonly ParameterDecorator[];
+  /** 'read': HTTP GET, GraphQL query, RPC request. 'unsafe': HTTP POST, GraphQL mutation. WS messages are always enforced. */
+  readonly operation: "read" | "unsafe";
+  /** Handler body: receives the decorated parameter values, the invocation input and the harness context; its result is the response. */
+  handle(params: readonly unknown[], input: Record<string, unknown>, context: FixtureContext): unknown;
+}
+/** What the harness hands every fixture handler. */
+interface FixtureContext {
+  /** The default instance's service (BETTER_AUTH_SERVICE). */
+  readonly service: BetterAuthService;
+}
+/**
+ * One method of an abstract base class, exposed through two subclasses that carry `subclasses.public` and
+ * `subclasses.denied` as class decorators (T-inherited-handler). A harness without invokeInherited exposes it as a
+ * plain handler.
+ */
+interface InheritedFixture extends FixtureHandler {
+  readonly subclasses: {
+    readonly public: readonly ClassDecorator[];
+    readonly denied: readonly ClassDecorator[];
+  };
+}
+/**
+ * GraphQL shapes only: one object type FixtureNode, returned by the root fields and carrying the field resolvers
+ * below. invokeGraph selects `publicNested` as `publicNested { id reader }` and `guarded` as
+ * `guarded { id principal nestedReader }`, so `reader` and `nestedReader` read the reading of their enclosing field.
+ */
+interface GraphFixtures {
+  readonly roots: {
+    readonly public: FixtureHandler;
+    readonly sessionOnly: FixtureHandler;
+    readonly mixed: FixtureHandler;
+    /**
+     * A list root: its handler returns 20 FixtureNode items, so serve it as a list of FixtureNode (`[FixtureNode]`).
+     * Given only to the reader rows of T-internal-error-logged-once.
+     */
+    readonly items?: FixtureHandler;
+  };
+  readonly fields: {
+    readonly plain: FixtureHandler;
+    readonly publicNested: FixtureHandler;
+    readonly reader: FixtureHandler;
+    readonly guarded?: FixtureHandler;
+    readonly nestedReader?: FixtureHandler;
+    readonly sessionReader: FixtureHandler;
+    /** @ForwardAuthCookies() without access metadata: an inheriting form-mode field that signs a kit user in (T-csrf-login-proxy). */
+    readonly forwarding?: FixtureHandler;
+    /** A String field reading @ActiveOrganizationId() without a requirement that provides it (T-internal-error-logged-once). */
+    readonly organizationReader?: FixtureHandler;
+    /** A String field returning the user id of the zero-argument service.getSession() (T-internal-error-logged-once). */
+    readonly serviceSession?: FixtureHandler;
+  };
+  /** Federation shapes only: @ResolveReference() of FixtureNode, with the kit's per-representation requirement on `orgId`. */
+  readonly reference?: FixtureHandler;
+  /** Class decorators of the resolver class that serves the roots, the fields and the reference resolver. */
+  readonly classDecorators?: readonly ClassDecorator[];
+}
+interface GraphSelection {
+  readonly root: keyof GraphFixtures["roots"];
+  readonly fields: readonly (keyof GraphFixtures["fields"])[];
+}
+/**
+ * The fixture handlers of transportConformance, by name (the `handler` argument of invoke()). Harnesses expose each
+ * input field as the transport's named input, so ctx.param(name) reads input[name] (HTTP: route param or query).
+ * `triple` and `tripleMixed` are three distinct handler methods; invoke() runs all three in one logical request when
+ * the transport can, otherwise the first one.
+ */
+interface TransportFixtures {
+  readonly required: FixtureHandler;
+  readonly optional: FixtureHandler;
+  readonly public: FixtureHandler;
+  readonly forbidden: FixtureHandler;
+  readonly triple: readonly [FixtureHandler, FixtureHandler, FixtureHandler];
+  readonly tripleMixed: readonly [FixtureHandler, FixtureHandler, FixtureHandler];
+  readonly readsSession: FixtureHandler;
+  /** @AcceptPrincipals('session', 'api-key'), returns service.getSession() (T-reads-session). */
+  readonly readsSessionService: FixtureHandler;
+  readonly unsafe: FixtureHandler;
+  readonly loginProxy: FixtureHandler;
+  /** @Public() @ForwardAuthCookies(), operation 'read' (HTTP GET), calls service.api.signInEmail (T-csrf-login-proxy, T-csrf-safe-methods). */
+  readonly loginProxyRead: FixtureHandler;
+  readonly loginProxyService: FixtureHandler;
+  readonly publicService: FixtureHandler;
+  readonly acceptsApiKey: FixtureHandler;
+  readonly org: FixtureHandler;
+  readonly inherited: InheritedFixture;
+  readonly unguarded: FixtureHandler;
+  /**
+   * Default access, operation 'read': a direct auth.api.getSession() call presenting the invocation's `cookie` input,
+   * the caller's own session cookie (T-csrf-safe-methods).
+   */
+  readonly callerSession: FixtureHandler;
+  /** Like callerSession, with @Public(). */
+  readonly publicCallerSession: FixtureHandler;
+  /** GraphQL shapes only; other harnesses ignore it. */
+  readonly graph: GraphFixtures;
+}
+interface TransportInvocationResult {
+  ok: boolean;
+  body?: unknown;
+  error?: {
+    code?: string;
+    statusCode?: number;
+    reason?: string;
+    message?: string;
+  };
+  setCookies: string[];
+}
+interface GraphResult {
+  /** The operation's data, keyed like the selection: data[root][field]. */
+  data: unknown;
+  errors: readonly {
+    path: readonly (string | number)[];
+    code?: string;
+    reason?: string;
+    message?: string;
+  }[];
+}
+interface TransportConformanceOptions {
+  transport: ExtensionRef<AuthTransport>;
+  /**
+   * Boots an app exposing the kit's fixture handlers in the transport's shape, with BetterAuthModule's globalGuard as
+   * given. Pass `principals` to BetterAuthModule (the kit's API-key source), and `defaultRequirements` and
+   * `globalScope` when set. With `override`, boot through Test.createTestingModule() and pass the builder through it
+   * before compile(). Apply every fixture decorator the kit supplies, including its SetMetadata() marker. The app is
+   * closed by the kit.
+   */
+  createApp(fixtures: TransportFixtures, auth: AuthLike, options: {
+    globalGuard: boolean;
+    override?: (builder: TestingModuleBuilder) => TestingModuleBuilder;
+    defaultRequirements?: readonly RequirementExpr[];
+    /**
+     * GraphQL shapes: the fieldResolverEnhancers to serve 'graph' with. The kit boots GraphQL cases with [] and
+     * ['guards', 'interceptors'], and the reader rows of T-internal-error-logged-once with ['guards', 'interceptors',
+     * 'filters'] and ['guards', 'filters'].
+     */
+    fieldResolverEnhancers?: readonly ("guards" | "interceptors" | "filters")[];
+    /** GraphQL shapes: serve 'graph' from a federation subgraph (FixtureNode an entity keyed by id, with GraphFixtures.reference when given). */
+    federation?: boolean;
+    /** Principal sources for BetterAuthModule's `principals`: the kit's API-key source. */
+    principals?: readonly ExtensionRef<PrincipalSource>[];
+    /** BetterAuthModule's globalScope; unset keeps the module default (T-coverage-claims). */
+    globalScope?: boolean;
+    /** Register BetterAuthGuard as APP_GUARD and BetterAuthScopeInterceptor as APP_INTERCEPTOR yourself (with globalGuard: false; T-coverage-claims). */
+    appEnhancers?: boolean;
+    /** The logger the app uses from boot on (e.g. createNestApplication(adapter, { logger }) or moduleRef.useLogger(logger)): cases assert boot warnings. */
+    logger?: LoggerService;
+    /** BetterAuthModule's cookies.forwardDirectCalls (T-stamp-per-plan). */
+    forwardDirectCalls?: boolean;
+    /**
+     * BetterAuthModule's logSummary. The kit passes true where it asserts the boot summary (T-coverage-claims); unset
+     * leaves the harness's choice, such as false to keep other boots quiet.
+     */
+    logSummary?: boolean;
+    /** GraphQL shapes: the fieldResolverCoverage of the transport this boot registers (T-stamp-per-plan). */
+    fieldResolverCoverage?: "warn";
+    /** GraphQL shapes: the GraphQL module's `context` option, one of `graphqlContexts` (T-stale-context, T-subscription-origin). */
+    graphqlContext?: GraphqlContextShape;
+  }): Promise<INestApplication>;
+  /** Invokes a fixture handler with given credentials and browser headers; returns the transport-native outcome. */
+  invoke(app: INestApplication, handler: Exclude<keyof TransportFixtures, "graph">, headers: HeadersInit, input?: Record<string, unknown>): Promise<TransportInvocationResult>;
+  /**
+   * Two invocations of the 'org' fixture in ONE logical request or connection, with different inputs. Required when
+   * the transport has a lineage: the multiple-invocation cases then fail without it, and are skipped with a reason
+   * for other transports.
+   */
+  invokeTwice?(app: INestApplication, shape: InvocationShape, inputs: [Record<string, unknown>, Record<string, unknown>], headers: HeadersInit): Promise<[{
+    ok: boolean;
+    error?: {
+      reason?: string;
+    };
+  }, {
+    ok: boolean;
+    error?: {
+      reason?: string;
+    };
+  }]>;
+  /** Shapes invokeTwice can produce; required with it. */
+  invocationShapes?: readonly InvocationShape[];
+  /**
+   * GraphQL shapes: one operation over HTTP selecting the given root fields of fixtures.graph, each with the given
+   * FixtureNode fields. `delays` states the order in which the kit's session and API-key sources settle; the kit
+   * applies it to its own sources, so a harness may ignore it. Required when the transport nests handlers
+   * (defaultAccessFor): the GraphQL cases then fail without it, and are skipped with a reason for other transports.
+   */
+  invokeGraph?(app: INestApplication, selection: readonly GraphSelection[], headers: HeadersInit, options?: {
+    delays?: {
+      readonly session: number;
+      readonly apiKey: number;
+    };
+  }): Promise<GraphResult>;
+  /**
+   * Federation shapes only: one `_entities` query for the given representations of FixtureNode. Required when the
+   * transport claims the kit's reference resolver in a federation boot: T-reference-resolver then fails without it,
+   * and is skipped with a reason for other transports.
+   */
+  invokeEntities?(app: INestApplication, representations: readonly Record<string, unknown>[], fields: readonly (keyof GraphFixtures["fields"])[], headers: HeadersInit): Promise<GraphResult>;
+  /**
+   * Connection shapes (WebSocket gateways): opens ONE connection whose handshake carries `headers`, sends one message to
+   * each given fixture handler on it in order, each after the previous one answered, closes the connection and returns
+   * every outcome once the server has observed the close (T-stale-context runs a later caller after it). Required when
+   * the transport's browser leg is its connection's handshake: the T-ws-origin-* cases then fail without it, and are
+   * skipped with a reason for other transports.
+   */
+  invokeConnection?(app: INestApplication, handlers: readonly Exclude<keyof TransportFixtures, "graph">[], headers: HeadersInit, options?: {
+    /**
+     * Values the connection sends in its init payload (graphql-ws connection_init) instead of the handshake's credential
+     * headers; given only when `invocationShapes` includes 'subscriptions'.
+     */
+    readonly connectionParams?: Readonly<Record<string, string>>;
+  }): Promise<TransportInvocationResult[]>;
+  /**
+   * Invokes `fixtures.inherited` through the subclass that carries `subclasses[subclass]`. Without it T-inherited-handler
+   * is skipped with a reason: a transport that addresses handlers by a name that one inherited method shares across
+   * subclasses (an RPC pattern, a GraphQL root field) cannot expose it twice.
+   */
+  invokeInherited?(app: INestApplication, subclass: "public" | "denied", headers: HeadersInit): Promise<TransportInvocationResult>;
+  /**
+   * GraphQL shapes: the `graphqlContext` values createApp honours. T-stale-context needs 'static' and 'cached' and fails
+   * without them when the transport nests handlers; the custom-context rows of T-subscription-origin run for 'fresh' and
+   * 'plain-request' when listed.
+   */
+  graphqlContexts?: readonly GraphqlContextShape[];
+  /**
+   * Connection shapes: authenticates one connection whose handshake carries `headers` through the app's connection-time
+   * authentication (WS_CONNECTION_AUTH), requiring a principal: `ok` when one authenticates, otherwise the failure
+   * (401 without credentials). Required when the app provides WS_CONNECTION_AUTH: the T-ws-origin-* cases then fail
+   * without it.
+   */
+  authenticateConnection?(app: INestApplication, headers: HeadersInit): Promise<ConnectionAuthenticationResult>;
+  expectCookieCapable: boolean;
+  /**
+   * Whether the transport describes a browser leg (false for RPC; T-selection fails a false claim). A leg that follows each
+   * operation enables the T-csrf-* cases; a leg that is the connection's handshake, shared by the connection's messages and
+   * enforced on every one, enables the T-ws-origin-* cases instead. The kit reads which from the transport.
+   */
+  expectBrowserLeg: boolean;
+}
+/**
+ * The GraphQL module's `context` option of a boot: 'fresh' is a function returning a new object that keeps what the driver
+ * passes it (the native request, the graphql-ws context); 'plain-request' a function returning a new object whose `req` is a
+ * plain object holding only the native request's cookie header; 'cached' a function returning the object it built on its
+ * first call; 'static' an object.
+ */
+type GraphqlContextShape = "fresh" | "plain-request" | "cached" | "static";
+/** The outcome of connection-time authentication (authenticateConnection). */
+interface ConnectionAuthenticationResult {
+  ok: boolean;
+  error?: TransportInvocationResult["error"];
+}
+/**
+ * The transport kit (invariants T1–T11 and the core behavior every transport exposes). The kit owns the Better Auth
+ * instance, a kit API-key source (passed as `principals`), kit policies and the fixture handlers; the harness exposes
+ * the fixtures in its transport's shape. Applicability comes from the transport, not from the helpers a harness
+ * passes: a transport with a lineage needs invokeTwice, one that nests handlers (defaultAccessFor) needs invokeGraph,
+ * and one that claims the kit's federation reference resolver needs invokeEntities. The kit reads those members from
+ * a transport object directly and boots once for a class or a definition.
+ */
+export declare function transportConformance(options: TransportConformanceOptions): ConformanceCase[];
+//#endregion
+//#region src/conformance-policy-harness.d.ts
+interface PolicyConformanceOptions {
+  /**
+   * The requirement to judge. Its policies must be policy objects: the kit boots no application providers, so a class
+   * or token reference cannot resolve. For a DI policy, pass an instance built with its dependencies (new MyPolicy(deps)).
+   */
+  requirement: RequirementExpr;
+  /**
+   * The Better Auth instance the principals belong to. It must include conformanceProbePlugin(), testUtils(), the
+   * policy's plugins and nestjs(): createConformanceAuth({ plugins }) builds one. Session principals are judged with
+   * real session headers for their user (testUtils().getAuthHeaders). Unit-specific cases use the instance's plugins
+   * when present: session.cookieCache for the warm-cache variants, apiKey({ enableSessionForAPIKeys: true }) for the
+   * API-key session and quota cases; each states the reason when it skips.
+   */
+  auth: AuthLike;
+  allowingPrincipal(): Promise<AuthPrincipal>;
+  denyingPrincipal(): Promise<AuthPrincipal>;
+  delegatedPrincipal?(): Promise<AuthPrincipal>;
+  /**
+   * Principal sources the kit registers besides the built-in session source, for the requirement's other principal kinds
+   * (e.g. apiKeyPrincipal()). Cases that send a request through the guard resolve those kinds with them; without them
+   * the kit registers placeholder sources that resolve nothing.
+   */
+  sources?: readonly ExtensionRef<PrincipalSource>[];
+  /**
+   * Transports to deliver the transport-specific rows through, besides the kit's in-process request: each delivery adds
+   * its own variants of Z-admin-banned (connection deliveries with a principal TTL), Z-admin-rejects-api-key-session,
+   * Z-apikey-quota-per-request and Z-org-ref-types, titled with its name.
+   */
+  deliveries?: readonly PolicyDelivery[];
+  /**
+   * Builds the instances the kit needs in another configuration (adminUserIds, customSession shapes, a dynamic baseURL,
+   * an instance without apiKey()) with exactly the given overrides, on the storage under test. It must add what
+   * createConformanceAuth() adds (testUtils(), bearer(), conformanceProbePlugin(), nestjs(), an explicit
+   * advanced.disableOriginCheck: false and session.updateAge 0) and have its schema migrated. Default:
+   * createConformanceAuth(overrides), on the memory adapter.
+   */
+  variant?(overrides: Omit<BetterAuthOptions, "database">): AuthLike | Promise<AuthLike>;
+}
+/**
+ * A transport the policy kit delivers its transport-specific rows through (design v7 §14.1). Build it from the harness
+ * of a transportConformance run: it exposes the kit's handlers the way that harness exposes the transport kit's fixtures.
+ */
+interface PolicyDelivery {
+  /** The transport's name in case titles, e.g. 'Socket.IO'. */
+  readonly name: string;
+  /**
+   * Boots an app with BetterAuthModule's globalGuard that exposes each handler under its name in the transport's shape:
+   * a gateway message with explicit coverage, a message pattern or a GraphQL query field, plus the subscription field
+   * that connect()'s operations select on a GraphQL socket. Apply the handler's decorators like transportConformance's
+   * createApp does. The kit's only named input is `orgId`: pass its value through with its JSON type (a GraphQL
+   * harness declares a JSON scalar argument), so ctx.param('orgId') reads it unchanged. Pass `principals` to
+   * BetterAuthModule and use `logger` from boot on. The kit closes the app.
+   */
+  createApp(handlers: Readonly<Record<string, FixtureHandler>>, auth: AuthLike, options: {
+    readonly principals: readonly ExtensionRef<PrincipalSource>[];
+    readonly logger: LoggerService;
+  }): Promise<INestApplication>;
+  /**
+   * One logical request to a handler with the given headers: a message on its own connection, an RPC request, an
+   * operation. The kit's headers carry the probe plugin's trusted Origin, as a browser on a trusted page sends it.
+   */
+  invoke(app: INestApplication, handler: string, headers: HeadersInit, input?: Record<string, unknown>): Promise<TransportInvocationResult>;
+  /**
+   * Connection deliveries (WebSocket gateways, graphql-ws): opens one connection whose handshake carries `headers`.
+   * Its invoke() sends one message, or one subscription operation for GraphQL, after the previous one answered.
+   */
+  connect?(app: INestApplication, headers: HeadersInit): Promise<PolicyDeliveryConnection>;
+  /**
+   * The principal TTL of connect()'s connections: the transport's principalTtlMs or subscriptionPrincipalTtlMs. The
+   * connection variant of Z-admin-banned runs when it is positive, and checks that the connection reuses its principal.
+   */
+  readonly connectionPrincipalTtlMs?: number;
+}
+/** One connection of a PolicyDelivery. */
+interface PolicyDeliveryConnection {
+  invoke(handler: string, input?: Record<string, unknown>): Promise<TransportInvocationResult>;
+  close(): Promise<void>;
+}
+//#endregion
+//#region src/conformance-policy.d.ts
+/**
+ * The authorization-policy kit (invariants Z1–Z6 and the unit-specific rows of design §14.1). Each principal is judged
+ * through the real AuthorizationEvaluator, so the delegation gate, error normalization and the per-invocation
+ * decision memo apply exactly as in the guard; an infrastructure error thrown here is the guard's 5xx. Cases that
+ * need route planning, acceptance or principal resolution send an in-process request through the real
+ * BetterAuthGuard. Storage outages are injected into the instance's database adapter, so an endpoint that swallows a
+ * storage error into a 401 is exercised; APIError mapping uses the probe plugin's before hook. Requirements must name
+ * policy objects (see PolicyConformanceOptions.requirement). Unit-specific cases run when the requirement contains
+ * the built-in admin, organization or API-key policy and skip with the reason otherwise.
+ */
+export declare function policyConformance(options: PolicyConformanceOptions): ConformanceCase[];
+//#endregion
+//#region src/conformance-principal.d.ts
+/** An API key the kit's S-apikey-* cases created, and the request headers that present it. */
+interface ConformanceApiKey {
+  /** The key's record id, which the kit uses to disable or expire the key through the database adapter. */
+  readonly id: string;
+  readonly headers: Headers;
+}
+/** Real HTTP delivery for the HTTP-route rows of S-cookie-forwarded and S-infra-throws and the cookie-bridge cases (S-bridge-*). */
+interface PrincipalHttpConformanceOptions {
+  platform: ExtensionRef<HttpPlatform>;
+  /** Fresh Nest HTTP adapter per app, e.g. () => new ExpressAdapter(). */
+  createHttpAdapter(): AbstractHttpAdapter;
+  /** How to obtain a base URL. Default: app.listen(0, '127.0.0.1') + getUrl(). */
+  listen?(app: INestApplication): Promise<string>;
+}
+interface PrincipalSourceConformanceOptions {
+  /**
+   * The source under test. Pass a factory reference (defineExtension({ use: { useFactory } })) when the source keeps
+   * per-instance state across requests, such as the API-key outage probe or a JWT key cache: every case boots its
+   * own module, and a factory gives each case a fresh source.
+   */
+  source: ExtensionRef<PrincipalSource>;
+  /**
+   * The Better Auth instance the credentials belong to. It must include conformanceProbePlugin(), testUtils() and
+   * nestjs(), with session.updateAge 0 and session refresh enabled, so every session read produces a refresh
+   * Set-Cookie: createConformanceAuth({ plugins }) builds one. The kit fails with CONFORMANCE_SESSION_REFRESH otherwise.
+   */
+  auth: AuthLike;
+  credentials: {
+    /**
+     * A fresh valid credential of `auth`: the options' instance, or a variant() instance (S-dynamic-base-url). Variant
+     * instances have a dynamic baseURL without fallback that allows localhost:3000 (the kit base URL's host) and
+     * public.example, so an auth.api call that creates the credential must pass headers with one of those hosts.
+     */
+    valid(auth: AuthLike): Promise<Headers>;
+    invalid(): Headers;
+    rateLimited?(auth: AuthLike): Promise<Headers>;
+    /**
+     * S-apikey-*: creates a key with these extra createApiKey body fields (remaining, rateLimitEnabled, ...).
+     * Default: a key of a new kit user through auth.api.createApiKey, presented in the source's first credential header.
+     */
+    apiKey?(auth: AuthLike, fields: Readonly<Record<string, unknown>>): Promise<ConformanceApiKey>;
+    /** S-apikey-org-key: an organization-owned key (references: 'organization'). The case skips without it. */
+    organizationKey?(auth: AuthLike): Promise<Headers>;
+  };
+  /**
+   * S-dynamic-base-url: another instance of the same configuration with the kit's overrides (a dynamic baseURL,
+   * trusted proxy headers). Default: createConformanceAuth({ ...overrides, plugins }) with the plugins of `auth`
+   * other than the kit's own; pass variant() when those plugin objects keep per-instance state.
+   */
+  variant?(overrides: Omit<BetterAuthOptions, "database">): AuthLike;
+  /**
+   * Boots a guarded route and the cookie-bridge routes on this HTTP platform for the HTTP-route rows of
+   * S-cookie-forwarded and S-infra-throws and for S-bridge-*. Those cases skip without it.
+   */
+  http?: PrincipalHttpConformanceOptions;
+}
+/**
+ * The principal-source kit (invariants P1–P7 and the unit-specific rows of design v7 §14.1). It resolves the source
+ * directly inside the resolver's chain scope, so a source that throws for invalid credentials fails
+ * S-rejected-not-thrown although core would normalize the throw at runtime; S-log-redaction resolves through the real
+ * principal resolver. Storage faults are injected into the instance's database adapter, below every endpoint and
+ * every direct adapter read, so endpoints that swallow storage errors are exercised too. A case that does not apply to
+ * the source (an API-key row for a session source, say) skips with the reason.
+ */
+export declare function principalSourceConformance(options: PrincipalSourceConformanceOptions): ConformanceCase[];
+//#endregion
+export type { ConformanceApiKey, ConformanceAuthSettings, ConformanceCase, ConformanceOutcome, ConformanceRunner, ConformanceSkip, ConnectionAuthenticationResult, FixtureContext, FixtureHandler, GraphFixtures, GraphResult, GraphSelection, GraphqlContextShape, HttpConformanceOptions, InheritedFixture, InvocationShape, PolicyConformanceOptions, PolicyDelivery, PolicyDeliveryConnection, PrincipalHttpConformanceOptions, PrincipalSourceConformanceOptions, TransportConformanceOptions, TransportFixtures, TransportInvocationResult };
+//# sourceMappingURL=conformance.d.cts.map

package/dist/testing/conformance.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.d.cts","names":[],"sources":["../../src/conformance-fixtures.ts","../../src/conformance-http.ts","../../src/conformance-transport.ts","../../src/conformance-policy-harness.ts","../../src/conformance-policy.ts","../../src/conformance-principal.ts"],"mappings":"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"}