nestjs-slightly-better-auth 1.0.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2025 thilllon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,57 @@
+# nestjs-slightly-better-auth
+
+[![npm version](https://img.shields.io/npm/v/nestjs-slightly-better-auth)](https://www.npmjs.com/package/nestjs-slightly-better-auth)
+[![Monthly downloads](https://img.shields.io/npm/dm/nestjs-slightly-better-auth)](https://www.npmjs.com/package/nestjs-slightly-better-auth)
+[![CI](https://img.shields.io/github/actions/workflow/status/thilllon/nestjs-kit/ci.yml?branch=main&label=CI)](https://github.com/thilllon/nestjs-kit/actions/workflows/ci.yml)
+
+A NestJS integration for [Better Auth](https://www.better-auth.com), built on an independently reviewed specification.
+
+> **Scope of 1.0.0.** This release covers HTTP: the Nest authentication kernel, the Better Auth construction plugin, the Express and Fastify platforms, and the admin, organization and API-key authorization units. GraphQL, WebSocket and RPC transports and the conformance testing kit are not included; they arrive in later minor versions behind their own entry points.
+
+## Install
+
+```sh
+pnpm add nestjs-slightly-better-auth better-auth
+```
+
+Peer dependencies: `@nestjs/common` and `@nestjs/core` 12, `better-auth` 1.7.5 or newer, `reflect-metadata` and `rxjs`. Node.js 24.11 or newer.
+
+## What this release covers
+
+The library separates a Better Auth construction plugin, a NestJS integration kernel and optional transports. The `./plugin` entry installs the hook and cookie bridge before Better Auth creates its pipeline. The `./platform` entry provides Node/Web request and response helpers. Neither entry requires Express, Fastify, GraphQL or WebSocket packages.
+
+The root entry provides synchronous and asynchronous module registration, default and named instances, service readers, guards, scoped execution and compositional authorization. Tests exercise actual Nest dependency injection and Better Auth sessions, including isolation between instances, caller-origin enforcement and application shutdown. Built ESM and CommonJS consumers verify the same registration and type contracts.
+
+The `./express` and `./fastify` entries connect native Nest applications to Better Auth. Their end-to-end tests cover raw bodies, size limits, cookies, CORS, request cancellation, exception filters and real authentication. Fastify also supports HTTP/2. The platform entries have no runtime imports of Express or Fastify; install the Nest platform adapter used by your application.
+
+Express preserves native controller parsing for unconditional routes that overlap the auth mount. Body-capable controller routes that also depend on host or non-URI version conditions are rejected at startup with `CONDITIONAL_ROUTE_SHADOW`; move them outside the auth mount. The integration checks the effective Express router flags because changing application settings after router creation does not change existing route matching. This is a tested Express 5 compatibility boundary, not an inspection of the router stack.
+
+Fastify does not expose its configured `trustProxy` value through a public inspection API. The boot summary therefore reports proxy trust as `unknown`, and diagnostics that depend on the setting are unavailable. Client IP resolution still uses the native Fastify request. Configure proxy trust on your Nest Fastify adapter and verify it against your deployment topology.
+
+GraphQL, WebSocket and microservice integrations have separate implementation and end-to-end acceptance gates. They will use optional entry points so applications can install the transports they use. HTTP platform tests do not establish that those integrations are ready.
+
+Start with the [design workspace](docs/design/README.md), [reviewed specification](docs/design/design-v7.md), [review ledger](docs/design/ledger.md) and [implementation plan](../../docs/superpowers/plans/2026-09-21-better-auth.md). Independent Better Auth, NestJS and security reviews approved the final v7 snapshot after resolving the round-6 and round-7 findings. The remaining entry points are tracked in [issue #534](https://github.com/thilllon/nestjs-kit/issues/534).
+
+## Develop in this monorepo
+
+From the repository root:
+
+```sh
+mise install
+mise exec -- pnpm install
+mise exec -- pnpm --filter nestjs-slightly-better-auth typecheck
+mise exec -- pnpm --filter nestjs-slightly-better-auth build
+mise exec -- pnpm test:packaging
+```
+
+The shared toolchain uses Node.js LTS, pnpm, tsdown, TypeScript and Vitest. Builds produce ESM and CommonJS artifacts with declarations. The `module-sync` export makes supported Node `import` and `require()` consumers share the same ESM module identity.
+
+[Contributing](../../CONTRIBUTING.md) explains repository checks and PRs. See [package instructions](AGENTS.md) and [import provenance](docs/provenance.md) before working with the historical material.
+
+## Releases
+
+Versions come from Changesets, and publication runs from the monorepo's release workflow with npm trusted publishing and provenance; see [release automation](../../docs/releases.md). New entry points are additive, so they ship as minor versions.
+
+## License
+
+[MIT](LICENSE). The archived upstream adapter retains its [original MIT notice](legacy/LICENSE).

package/dist/admin.cjs

@@ -0,0 +1,88 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_auth_errors = require("./auth-errors-CsERBNWI.cjs");
+const require_auth_decorators = require("./auth-decorators-CwW5JY4y.cjs");
+let better_auth_api = require("better-auth/api");
+//#region src/admin.ts
+const adminPermissionPolicy = {
+	id: "better-auth:admin/permission",
+	requires: {
+		plugins: ["admin"],
+		principals: ["session"],
+		freshIdentity: true,
+		hostlessCalls: true
+	},
+	validate({ permissions }) {
+		if (!Object.keys(permissions).length || Object.values(permissions).some((actions) => !Array.isArray(actions) || !actions.length)) throw new require_auth_errors.BetterAuthConfigurationError("EMPTY_PERMISSIONS", "Admin permissions must contain a resource and actions.");
+	},
+	async evaluate({ permissions }, context) {
+		const { principal } = context;
+		if (!principal.userId) return {
+			effect: "deny",
+			reason: "USER_REQUIRED"
+		};
+		const userId = principal.userId;
+		let role;
+		if (principal.delegation) {
+			const owner = await context.memo(JSON.stringify(["admin:owner", userId]), async () => (await context.auth.context()).internalAdapter.findUserById(userId));
+			if (!owner) return {
+				effect: "deny",
+				status: 401,
+				reason: "USER_NOT_FOUND"
+			};
+			if (owner.banned && (!owner.banExpires || new Date(owner.banExpires).getTime() > Date.now())) return {
+				effect: "deny",
+				status: 401,
+				reason: "USER_BANNED"
+			};
+			if (typeof owner.role === "string" && owner.role.length) role = owner.role;
+		}
+		const stablePermissions = Object.entries(permissions).sort(([a], [b]) => a.localeCompare(b)).map(([resource, actions]) => [resource, [...actions].sort()]);
+		try {
+			if (!(await context.memo(JSON.stringify([
+				"admin:userHasPermission",
+				userId,
+				role ?? null,
+				stablePermissions
+			]), () => context.auth.run({
+				cookies: context.cookies,
+				inbound: () => context.headers,
+				internal: true
+			}, () => context.auth.api.userHasPermission({ body: {
+				userId,
+				permissions,
+				...role === void 0 ? {} : { role }
+			} })))).success) return {
+				effect: "deny",
+				reason: "MISSING_PERMISSION"
+			};
+		} catch (error) {
+			if ((0, better_auth_api.isAPIError)(error) && error.statusCode === 400 && error.body?.message === "user not found") return {
+				effect: "deny",
+				status: 401,
+				reason: "USER_NOT_FOUND"
+			};
+			throw error;
+		}
+		if (principal.delegation && !principal.delegation.allows(permissions)) return {
+			effect: "deny",
+			reason: "INSUFFICIENT_SCOPE"
+		};
+		return { effect: "allow" };
+	}
+};
+function permission(permissions, options = {}) {
+	return {
+		policy: adminPermissionPolicy,
+		params: { permissions },
+		...options.principals ? { principals: options.principals } : {}
+	};
+}
+function RequirePermission(permissions, options) {
+	return require_auth_decorators.Require(permission(permissions, options));
+}
+//#endregion
+exports.RequirePermission = RequirePermission;
+exports.adminPermissionPolicy = adminPermissionPolicy;
+exports.permission = permission;
+
+//# sourceMappingURL=admin.cjs.map

package/dist/admin.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin.cjs","names":["BetterAuthConfigurationError","isAPIError","Require"],"sources":["../src/admin.ts"],"sourcesContent":["import { isAPIError } from \"better-auth/api\";\nimport type { AuthorizationPolicy, Requirement } from \"./auth-contracts.js\";\nimport { Require } from \"./auth-decorators.js\";\nimport { BetterAuthConfigurationError } from \"./auth-errors.js\";\nimport type {\n  AdminPermissions,\n  AuthPrincipal,\n  PrincipalKind,\n} from \"./auth-types.js\";\nexport type { AdminPermissions } from \"./auth-types.js\";\nexport interface PermissionOptions {\n  principals?: readonly PrincipalKind[];\n}\nexport interface AdminPermissionParams {\n  readonly permissions: AdminPermissions;\n}\ninterface AdminApi {\n  userHasPermission(input: {\n    body: {\n      userId: string;\n      role?: string;\n      permissions: Readonly<Record<string, readonly string[]>>;\n    };\n  }): Promise<{ success: boolean }>;\n}\nexport const adminPermissionPolicy: AuthorizationPolicy<\n  AdminPermissionParams,\n  AuthPrincipal\n> = {\n  id: \"better-auth:admin/permission\",\n  requires: {\n    plugins: [\"admin\"],\n    principals: [\"session\"],\n    freshIdentity: true,\n    hostlessCalls: true,\n  },\n  validate({ permissions }) {\n    if (\n      !Object.keys(permissions).length ||\n      Object.values(permissions).some(\n        (actions) => !Array.isArray(actions) || !actions.length,\n      )\n    ) {\n      throw new BetterAuthConfigurationError(\n        \"EMPTY_PERMISSIONS\",\n        \"Admin permissions must contain a resource and actions.\",\n      );\n    }\n  },\n  async evaluate({ permissions }, context) {\n    const { principal } = context;\n    if (!principal.userId) {\n      return { effect: \"deny\", reason: \"USER_REQUIRED\" };\n    }\n    const userId = principal.userId;\n    let role: string | undefined;\n    if (principal.delegation) {\n      const owner = await context.memo(\n        JSON.stringify([\"admin:owner\", userId]),\n        async () =>\n          (await context.auth.context()).internalAdapter.findUserById(userId),\n      );\n      if (!owner) {\n        return { effect: \"deny\", status: 401, reason: \"USER_NOT_FOUND\" };\n      }\n      if (\n        owner.banned &&\n        (!owner.banExpires || new Date(owner.banExpires).getTime() > Date.now())\n      ) {\n        return { effect: \"deny\", status: 401, reason: \"USER_BANNED\" };\n      }\n      if (typeof owner.role === \"string\" && owner.role.length) {\n        role = owner.role;\n      }\n    }\n    const stablePermissions = Object.entries(permissions)\n      .sort(([a], [b]) => a.localeCompare(b))\n      .map(([resource, actions]) => [resource, [...actions].sort()]);\n    try {\n      const result = await context.memo(\n        JSON.stringify([\n          \"admin:userHasPermission\",\n          userId,\n          role ?? null,\n          stablePermissions,\n        ]),\n        () =>\n          context.auth.run(\n            {\n              cookies: context.cookies,\n              inbound: () => context.headers,\n              internal: true,\n            },\n            () =>\n              (context.auth.api as unknown as AdminApi).userHasPermission({\n                body: {\n                  userId,\n                  permissions,\n                  ...(role === undefined ? {} : { role }),\n                },\n              }),\n          ),\n      );\n      if (!result.success) {\n        return { effect: \"deny\", reason: \"MISSING_PERMISSION\" };\n      }\n    } catch (error) {\n      if (\n        isAPIError(error) &&\n        error.statusCode === 400 &&\n        error.body?.message === \"user not found\"\n      ) {\n        return { effect: \"deny\", status: 401, reason: \"USER_NOT_FOUND\" };\n      }\n      throw error;\n    }\n    if (principal.delegation && !principal.delegation.allows(permissions)) {\n      return { effect: \"deny\", reason: \"INSUFFICIENT_SCOPE\" };\n    }\n    return { effect: \"allow\" };\n  },\n};\nexport function permission<N extends string = \"default\">(\n  permissions: AdminPermissions<N>,\n  options: PermissionOptions = {},\n): Requirement<AdminPermissionParams> {\n  return {\n    policy: adminPermissionPolicy,\n    params: { permissions: permissions as AdminPermissions },\n    ...(options.principals ? { principals: options.principals } : {}),\n  };\n}\nexport function RequirePermission<N extends string = \"default\">(\n  permissions: AdminPermissions<N>,\n  options?: PermissionOptions,\n): ClassDecorator & MethodDecorator {\n  return Require(permission<N>(permissions, options));\n}\n"],"mappings":";;;;;AAyBA,MAAa,wBAGT;CACF,IAAI;CACJ,UAAU;EACR,SAAS,CAAC,OAAO;EACjB,YAAY,CAAC,SAAS;EACtB,eAAe;EACf,eAAe;CACjB;CACA,SAAS,EAAE,eAAe;EACxB,IACE,CAAC,OAAO,KAAK,WAAW,CAAC,CAAC,UAC1B,OAAO,OAAO,WAAW,CAAC,CAAC,MACxB,YAAY,CAAC,MAAM,QAAQ,OAAO,KAAK,CAAC,QAAQ,MACnD,GAEA,MAAM,IAAIA,oBAAAA,6BACR,qBACA,wDACF;CAEJ;CACA,MAAM,SAAS,EAAE,eAAe,SAAS;EACvC,MAAM,EAAE,cAAc;EACtB,IAAI,CAAC,UAAU,QACb,OAAO;GAAE,QAAQ;GAAQ,QAAQ;EAAgB;EAEnD,MAAM,SAAS,UAAU;EACzB,IAAI;EACJ,IAAI,UAAU,YAAY;GACxB,MAAM,QAAQ,MAAM,QAAQ,KAC1B,KAAK,UAAU,CAAC,eAAe,MAAM,CAAC,GACtC,aACG,MAAM,QAAQ,KAAK,QAAQ,EAAA,CAAG,gBAAgB,aAAa,MAAM,CACtE;GACA,IAAI,CAAC,OACH,OAAO;IAAE,QAAQ;IAAQ,QAAQ;IAAK,QAAQ;GAAiB;GAEjE,IACE,MAAM,WACL,CAAC,MAAM,cAAc,IAAI,KAAK,MAAM,UAAU,CAAC,CAAC,QAAQ,IAAI,KAAK,IAAI,IAEtE,OAAO;IAAE,QAAQ;IAAQ,QAAQ;IAAK,QAAQ;GAAc;GAE9D,IAAI,OAAO,MAAM,SAAS,YAAY,MAAM,KAAK,QAC/C,OAAO,MAAM;EAEjB;EACA,MAAM,oBAAoB,OAAO,QAAQ,WAAW,CAAC,CAClD,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,CACtC,KAAK,CAAC,UAAU,aAAa,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC;EAC/D,IAAI;GAyBF,IAAI,EAAC,MAxBgB,QAAQ,KAC3B,KAAK,UAAU;IACb;IACA;IACA,QAAQ;IACR;GACF,CAAC,SAEC,QAAQ,KAAK,IACX;IACE,SAAS,QAAQ;IACjB,eAAe,QAAQ;IACvB,UAAU;GACZ,SAEG,QAAQ,KAAK,IAA4B,kBAAkB,EAC1D,MAAM;IACJ;IACA;IACA,GAAI,SAAS,KAAA,IAAY,CAAC,IAAI,EAAE,KAAK;GACvC,EACF,CAAC,CACL,CACJ,EAAA,CACY,SACV,OAAO;IAAE,QAAQ;IAAQ,QAAQ;GAAqB;EAE1D,SAAS,OAAO;GACd,KAAA,GACEC,gBAAAA,WAAAA,CAAW,KAAK,KAChB,MAAM,eAAe,OACrB,MAAM,MAAM,YAAY,kBAExB,OAAO;IAAE,QAAQ;IAAQ,QAAQ;IAAK,QAAQ;GAAiB;GAEjE,MAAM;EACR;EACA,IAAI,UAAU,cAAc,CAAC,UAAU,WAAW,OAAO,WAAW,GAClE,OAAO;GAAE,QAAQ;GAAQ,QAAQ;EAAqB;EAExD,OAAO,EAAE,QAAQ,QAAQ;CAC3B;AACF;AACA,SAAgB,WACd,aACA,UAA6B,CAAC,GACM;CACpC,OAAO;EACL,QAAQ;EACR,QAAQ,EAAe,YAAgC;EACvD,GAAI,QAAQ,aAAa,EAAE,YAAY,QAAQ,WAAW,IAAI,CAAC;CACjE;AACF;AACA,SAAgB,kBACd,aACA,SACkC;CAClC,OAAOC,wBAAAA,QAAQ,WAAc,aAAa,OAAO,CAAC;AACpD"}

package/dist/admin.d.cts

@@ -0,0 +1,14 @@
+import { f as AuthorizationPolicy, kt as PrincipalKind, mt as AdminPermissions, nt as Requirement, yt as AuthPrincipal } from "./auth-contracts-BBA1C1gj.cjs";
+//#region src/admin.d.ts
+export interface PermissionOptions {
+  principals?: readonly PrincipalKind[];
+}
+export interface AdminPermissionParams {
+  readonly permissions: AdminPermissions;
+}
+export declare const adminPermissionPolicy: AuthorizationPolicy<AdminPermissionParams, AuthPrincipal>;
+export declare function permission<N extends string = "default">(permissions: AdminPermissions<N>, options?: PermissionOptions): Requirement<AdminPermissionParams>;
+export declare function RequirePermission<N extends string = "default">(permissions: AdminPermissions<N>, options?: PermissionOptions): ClassDecorator & MethodDecorator;
+//#endregion
+export type { AdminPermissions };
+//# sourceMappingURL=admin.d.cts.map

package/dist/admin.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin.d.cts","names":[],"sources":["../src/admin.ts"],"mappings":";;iBAUiB;EACf,sBAAsB;;iBAEP;WACN,aAAa;;qBAWX,uBAAuB,oBAClC,uBACA;wBA+Fc,WAAW,8BACzB,aAAa,iBAAiB,IAC9B,UAAS,oBACR,YAAY;wBAOC,kBAAkB,8BAChC,aAAa,iBAAiB,IAC9B,UAAU,oBACT,iBAAiB"}

package/dist/admin.d.mts

@@ -0,0 +1,14 @@
+import { f as AuthorizationPolicy, kt as PrincipalKind, mt as AdminPermissions, nt as Requirement, yt as AuthPrincipal } from "./auth-contracts-tqsfBZ8B.mjs";
+//#region src/admin.d.ts
+export interface PermissionOptions {
+  principals?: readonly PrincipalKind[];
+}
+export interface AdminPermissionParams {
+  readonly permissions: AdminPermissions;
+}
+export declare const adminPermissionPolicy: AuthorizationPolicy<AdminPermissionParams, AuthPrincipal>;
+export declare function permission<N extends string = "default">(permissions: AdminPermissions<N>, options?: PermissionOptions): Requirement<AdminPermissionParams>;
+export declare function RequirePermission<N extends string = "default">(permissions: AdminPermissions<N>, options?: PermissionOptions): ClassDecorator & MethodDecorator;
+//#endregion
+export type { AdminPermissions };
+//# sourceMappingURL=admin.d.mts.map

package/dist/admin.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin.d.mts","names":[],"sources":["../src/admin.ts"],"mappings":";;iBAUiB;EACf,sBAAsB;;iBAEP;WACN,aAAa;;qBAWX,uBAAuB,oBAClC,uBACA;wBA+Fc,WAAW,8BACzB,aAAa,iBAAiB,IAC9B,UAAS,oBACR,YAAY;wBAOC,kBAAkB,8BAChC,aAAa,iBAAiB,IAC9B,UAAU,oBACT,iBAAiB"}

package/dist/admin.mjs

@@ -0,0 +1,85 @@
+import { n as BetterAuthConfigurationError } from "./auth-errors-CQjfgjaO.mjs";
+import { u as Require } from "./auth-decorators-DfAJbHar.mjs";
+import { isAPIError } from "better-auth/api";
+//#region src/admin.ts
+const adminPermissionPolicy = {
+	id: "better-auth:admin/permission",
+	requires: {
+		plugins: ["admin"],
+		principals: ["session"],
+		freshIdentity: true,
+		hostlessCalls: true
+	},
+	validate({ permissions }) {
+		if (!Object.keys(permissions).length || Object.values(permissions).some((actions) => !Array.isArray(actions) || !actions.length)) throw new BetterAuthConfigurationError("EMPTY_PERMISSIONS", "Admin permissions must contain a resource and actions.");
+	},
+	async evaluate({ permissions }, context) {
+		const { principal } = context;
+		if (!principal.userId) return {
+			effect: "deny",
+			reason: "USER_REQUIRED"
+		};
+		const userId = principal.userId;
+		let role;
+		if (principal.delegation) {
+			const owner = await context.memo(JSON.stringify(["admin:owner", userId]), async () => (await context.auth.context()).internalAdapter.findUserById(userId));
+			if (!owner) return {
+				effect: "deny",
+				status: 401,
+				reason: "USER_NOT_FOUND"
+			};
+			if (owner.banned && (!owner.banExpires || new Date(owner.banExpires).getTime() > Date.now())) return {
+				effect: "deny",
+				status: 401,
+				reason: "USER_BANNED"
+			};
+			if (typeof owner.role === "string" && owner.role.length) role = owner.role;
+		}
+		const stablePermissions = Object.entries(permissions).sort(([a], [b]) => a.localeCompare(b)).map(([resource, actions]) => [resource, [...actions].sort()]);
+		try {
+			if (!(await context.memo(JSON.stringify([
+				"admin:userHasPermission",
+				userId,
+				role ?? null,
+				stablePermissions
+			]), () => context.auth.run({
+				cookies: context.cookies,
+				inbound: () => context.headers,
+				internal: true
+			}, () => context.auth.api.userHasPermission({ body: {
+				userId,
+				permissions,
+				...role === void 0 ? {} : { role }
+			} })))).success) return {
+				effect: "deny",
+				reason: "MISSING_PERMISSION"
+			};
+		} catch (error) {
+			if (isAPIError(error) && error.statusCode === 400 && error.body?.message === "user not found") return {
+				effect: "deny",
+				status: 401,
+				reason: "USER_NOT_FOUND"
+			};
+			throw error;
+		}
+		if (principal.delegation && !principal.delegation.allows(permissions)) return {
+			effect: "deny",
+			reason: "INSUFFICIENT_SCOPE"
+		};
+		return { effect: "allow" };
+	}
+};
+function permission(permissions, options = {}) {
+	return {
+		policy: adminPermissionPolicy,
+		params: { permissions },
+		...options.principals ? { principals: options.principals } : {}
+	};
+}
+function RequirePermission(permissions, options) {
+	return Require(permission(permissions, options));
+}
+//#endregion
+export { RequirePermission, adminPermissionPolicy, permission };
+
+//# sourceMappingURL=admin.mjs.map

package/dist/admin.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin.mjs","names":[],"sources":["../src/admin.ts"],"sourcesContent":["import { isAPIError } from \"better-auth/api\";\nimport type { AuthorizationPolicy, Requirement } from \"./auth-contracts.js\";\nimport { Require } from \"./auth-decorators.js\";\nimport { BetterAuthConfigurationError } from \"./auth-errors.js\";\nimport type {\n  AdminPermissions,\n  AuthPrincipal,\n  PrincipalKind,\n} from \"./auth-types.js\";\nexport type { AdminPermissions } from \"./auth-types.js\";\nexport interface PermissionOptions {\n  principals?: readonly PrincipalKind[];\n}\nexport interface AdminPermissionParams {\n  readonly permissions: AdminPermissions;\n}\ninterface AdminApi {\n  userHasPermission(input: {\n    body: {\n      userId: string;\n      role?: string;\n      permissions: Readonly<Record<string, readonly string[]>>;\n    };\n  }): Promise<{ success: boolean }>;\n}\nexport const adminPermissionPolicy: AuthorizationPolicy<\n  AdminPermissionParams,\n  AuthPrincipal\n> = {\n  id: \"better-auth:admin/permission\",\n  requires: {\n    plugins: [\"admin\"],\n    principals: [\"session\"],\n    freshIdentity: true,\n    hostlessCalls: true,\n  },\n  validate({ permissions }) {\n    if (\n      !Object.keys(permissions).length ||\n      Object.values(permissions).some(\n        (actions) => !Array.isArray(actions) || !actions.length,\n      )\n    ) {\n      throw new BetterAuthConfigurationError(\n        \"EMPTY_PERMISSIONS\",\n        \"Admin permissions must contain a resource and actions.\",\n      );\n    }\n  },\n  async evaluate({ permissions }, context) {\n    const { principal } = context;\n    if (!principal.userId) {\n      return { effect: \"deny\", reason: \"USER_REQUIRED\" };\n    }\n    const userId = principal.userId;\n    let role: string | undefined;\n    if (principal.delegation) {\n      const owner = await context.memo(\n        JSON.stringify([\"admin:owner\", userId]),\n        async () =>\n          (await context.auth.context()).internalAdapter.findUserById(userId),\n      );\n      if (!owner) {\n        return { effect: \"deny\", status: 401, reason: \"USER_NOT_FOUND\" };\n      }\n      if (\n        owner.banned &&\n        (!owner.banExpires || new Date(owner.banExpires).getTime() > Date.now())\n      ) {\n        return { effect: \"deny\", status: 401, reason: \"USER_BANNED\" };\n      }\n      if (typeof owner.role === \"string\" && owner.role.length) {\n        role = owner.role;\n      }\n    }\n    const stablePermissions = Object.entries(permissions)\n      .sort(([a], [b]) => a.localeCompare(b))\n      .map(([resource, actions]) => [resource, [...actions].sort()]);\n    try {\n      const result = await context.memo(\n        JSON.stringify([\n          \"admin:userHasPermission\",\n          userId,\n          role ?? null,\n          stablePermissions,\n        ]),\n        () =>\n          context.auth.run(\n            {\n              cookies: context.cookies,\n              inbound: () => context.headers,\n              internal: true,\n            },\n            () =>\n              (context.auth.api as unknown as AdminApi).userHasPermission({\n                body: {\n                  userId,\n                  permissions,\n                  ...(role === undefined ? {} : { role }),\n                },\n              }),\n          ),\n      );\n      if (!result.success) {\n        return { effect: \"deny\", reason: \"MISSING_PERMISSION\" };\n      }\n    } catch (error) {\n      if (\n        isAPIError(error) &&\n        error.statusCode === 400 &&\n        error.body?.message === \"user not found\"\n      ) {\n        return { effect: \"deny\", status: 401, reason: \"USER_NOT_FOUND\" };\n      }\n      throw error;\n    }\n    if (principal.delegation && !principal.delegation.allows(permissions)) {\n      return { effect: \"deny\", reason: \"INSUFFICIENT_SCOPE\" };\n    }\n    return { effect: \"allow\" };\n  },\n};\nexport function permission<N extends string = \"default\">(\n  permissions: AdminPermissions<N>,\n  options: PermissionOptions = {},\n): Requirement<AdminPermissionParams> {\n  return {\n    policy: adminPermissionPolicy,\n    params: { permissions: permissions as AdminPermissions },\n    ...(options.principals ? { principals: options.principals } : {}),\n  };\n}\nexport function RequirePermission<N extends string = \"default\">(\n  permissions: AdminPermissions<N>,\n  options?: PermissionOptions,\n): ClassDecorator & MethodDecorator {\n  return Require(permission<N>(permissions, options));\n}\n"],"mappings":";;;;AAyBA,MAAa,wBAGT;CACF,IAAI;CACJ,UAAU;EACR,SAAS,CAAC,OAAO;EACjB,YAAY,CAAC,SAAS;EACtB,eAAe;EACf,eAAe;CACjB;CACA,SAAS,EAAE,eAAe;EACxB,IACE,CAAC,OAAO,KAAK,WAAW,CAAC,CAAC,UAC1B,OAAO,OAAO,WAAW,CAAC,CAAC,MACxB,YAAY,CAAC,MAAM,QAAQ,OAAO,KAAK,CAAC,QAAQ,MACnD,GAEA,MAAM,IAAI,6BACR,qBACA,wDACF;CAEJ;CACA,MAAM,SAAS,EAAE,eAAe,SAAS;EACvC,MAAM,EAAE,cAAc;EACtB,IAAI,CAAC,UAAU,QACb,OAAO;GAAE,QAAQ;GAAQ,QAAQ;EAAgB;EAEnD,MAAM,SAAS,UAAU;EACzB,IAAI;EACJ,IAAI,UAAU,YAAY;GACxB,MAAM,QAAQ,MAAM,QAAQ,KAC1B,KAAK,UAAU,CAAC,eAAe,MAAM,CAAC,GACtC,aACG,MAAM,QAAQ,KAAK,QAAQ,EAAA,CAAG,gBAAgB,aAAa,MAAM,CACtE;GACA,IAAI,CAAC,OACH,OAAO;IAAE,QAAQ;IAAQ,QAAQ;IAAK,QAAQ;GAAiB;GAEjE,IACE,MAAM,WACL,CAAC,MAAM,cAAc,IAAI,KAAK,MAAM,UAAU,CAAC,CAAC,QAAQ,IAAI,KAAK,IAAI,IAEtE,OAAO;IAAE,QAAQ;IAAQ,QAAQ;IAAK,QAAQ;GAAc;GAE9D,IAAI,OAAO,MAAM,SAAS,YAAY,MAAM,KAAK,QAC/C,OAAO,MAAM;EAEjB;EACA,MAAM,oBAAoB,OAAO,QAAQ,WAAW,CAAC,CAClD,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,CACtC,KAAK,CAAC,UAAU,aAAa,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC;EAC/D,IAAI;GAyBF,IAAI,EAAC,MAxBgB,QAAQ,KAC3B,KAAK,UAAU;IACb;IACA;IACA,QAAQ;IACR;GACF,CAAC,SAEC,QAAQ,KAAK,IACX;IACE,SAAS,QAAQ;IACjB,eAAe,QAAQ;IACvB,UAAU;GACZ,SAEG,QAAQ,KAAK,IAA4B,kBAAkB,EAC1D,MAAM;IACJ;IACA;IACA,GAAI,SAAS,KAAA,IAAY,CAAC,IAAI,EAAE,KAAK;GACvC,EACF,CAAC,CACL,CACJ,EAAA,CACY,SACV,OAAO;IAAE,QAAQ;IAAQ,QAAQ;GAAqB;EAE1D,SAAS,OAAO;GACd,IACE,WAAW,KAAK,KAChB,MAAM,eAAe,OACrB,MAAM,MAAM,YAAY,kBAExB,OAAO;IAAE,QAAQ;IAAQ,QAAQ;IAAK,QAAQ;GAAiB;GAEjE,MAAM;EACR;EACA,IAAI,UAAU,cAAc,CAAC,UAAU,WAAW,OAAO,WAAW,GAClE,OAAO;GAAE,QAAQ;GAAQ,QAAQ;EAAqB;EAExD,OAAO,EAAE,QAAQ,QAAQ;CAC3B;AACF;AACA,SAAgB,WACd,aACA,UAA6B,CAAC,GACM;CACpC,OAAO;EACL,QAAQ;EACR,QAAQ,EAAe,YAAgC;EACvD,GAAI,QAAQ,aAAa,EAAE,YAAY,QAAQ,WAAW,IAAI,CAAC;CACjE;AACF;AACA,SAAgB,kBACd,aACA,SACkC;CAClC,OAAO,QAAQ,WAAc,aAAa,OAAO,CAAC;AACpD"}

package/dist/api-key.cjs

@@ -0,0 +1,163 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_auth_errors = require("./auth-errors-CsERBNWI.cjs");
+const require_auth_decorators = require("./auth-decorators-CwW5JY4y.cjs");
+let better_auth_plugins_access = require("better-auth/plugins/access");
+//#region src/api-key.ts
+const API_KEY_PRINCIPAL_KIND = "api-key";
+function apiKeyPrincipal(options = {}) {
+	const header = options.header ?? "x-api-key";
+	const slowMs = typeof options.outageProbe === "object" ? options.outageProbe.slowMs ?? 500 : 500;
+	if (!header.trim() || slowMs !== false && (!Number.isFinite(slowMs) || slowMs < 0)) throw new require_auth_errors.BetterAuthConfigurationError("INVALID_API_KEY_OPTIONS", "API-key header must be nonempty and slowMs must be finite and nonnegative.");
+	const verificationMemo = Symbol("api-key-verification");
+	const probes = /* @__PURE__ */ new WeakMap();
+	async function probe(auth) {
+		const previous = probes.get(auth.instance);
+		if (previous && (previous.pending || Date.now() - previous.at < 1e3)) return previous.result;
+		const result = (async () => {
+			const context = await auth.context();
+			const where = [{
+				field: "key",
+				value: crypto.randomUUID()
+			}];
+			await context.adapter.findOne({
+				model: "apikey",
+				where
+			});
+			await context.adapter.updateMany({
+				model: "apikey",
+				where,
+				update: { updatedAt: /* @__PURE__ */ new Date() }
+			});
+		})();
+		const state = {
+			at: Date.now(),
+			pending: true,
+			result
+		};
+		probes.set(auth.instance, state);
+		result.then(() => {
+			state.pending = false;
+		}, () => {
+			state.pending = false;
+		});
+		return result;
+	}
+	return {
+		id: "better-auth:api-key",
+		kinds: [API_KEY_PRINCIPAL_KIND],
+		acceptance: options.acceptance ?? "explicit",
+		delegates: true,
+		credentialHeaders: [header],
+		effects: {
+			consumesQuota: true,
+			writes: true
+		},
+		requires: { plugins: ["api-key"] },
+		appliesTo: (request) => request.headers.has(header),
+		async resolve(request) {
+			if (!request.headers.has(header)) return require_auth_decorators.absent();
+			return request.memo(verificationMemo, async () => {
+				const key = request.headers.get(header);
+				const headers = new Headers();
+				for (const name of [
+					"host",
+					"x-forwarded-host",
+					"x-forwarded-proto"
+				]) {
+					const value = request.headers.get(name);
+					if (value !== null) headers.set(name, value);
+				}
+				const started = performance.now();
+				try {
+					const result = await request.auth.run({
+						cookies: request.cookies,
+						inbound: () => request.headers,
+						internal: true
+					}, () => request.auth.api.verifyApiKey({
+						body: {
+							key,
+							...options.configId === void 0 ? {} : { configId: options.configId }
+						},
+						headers
+					}));
+					if (result.valid) {
+						const verified = result.key;
+						if (!verified || typeof verified.id !== "string" || typeof verified.referenceId !== "string") throw new require_auth_errors.BetterAuthInfrastructureError(/* @__PURE__ */ new Error("Malformed API-key verification result"));
+						const configId = verified.configId ?? null;
+						const references = typeof options.references === "function" ? options.references({ configId }) : options.references ?? "user";
+						const permissions = verified.permissions ?? null;
+						const grant = (0, better_auth_plugins_access.role)(permissions ?? {});
+						return require_auth_decorators.authenticated({
+							kind: API_KEY_PRINCIPAL_KIND,
+							source: "better-auth:api-key",
+							keyId: verified.id,
+							configId,
+							referenceId: verified.referenceId,
+							userId: references === "user" ? verified.referenceId : null,
+							organizationId: references === "organization" ? verified.referenceId : null,
+							permissions,
+							delegation: {
+								description: "api-key permissions",
+								allows: (requested) => grant.authorize(requested).success
+							}
+						});
+					}
+					const code = result.error?.code;
+					if (code === "RATE_LIMITED" || code === "USAGE_EXCEEDED") {
+						const retry = result.error?.details?.tryAgainIn;
+						return require_auth_decorators.rejected(require_auth_errors.AuthFailures.rejected({
+							status: 429,
+							reason: code,
+							...code === "RATE_LIMITED" && typeof retry === "number" ? { retryAfterSeconds: retry / 1e3 } : {}
+						}));
+					}
+					if (code === "INVALID_API_KEY" && options.outageProbe !== false) {
+						if (slowMs !== false && performance.now() - started > slowMs) throw new require_auth_errors.BetterAuthInfrastructureError(/* @__PURE__ */ new Error("API-key verification exceeded the outage threshold"));
+						await probe(request.auth);
+					}
+					if (code === "INVALID_API_KEY" || code === "KEY_NOT_FOUND" || code === "KEY_DISABLED" || code === "KEY_EXPIRED") return require_auth_decorators.rejected(require_auth_errors.AuthFailures.rejected({
+						status: 401,
+						reason: code
+					}));
+					throw new require_auth_errors.BetterAuthInfrastructureError(/* @__PURE__ */ new Error(`Unexpected API-key verification error: ${code ?? "missing code"}`));
+				} catch (error) {
+					const failure = require_auth_errors.normalizeThrown(error, "source", "better-auth:api-key", [key]);
+					if ("sessionLoss" in failure) throw new require_auth_errors.BetterAuthInfrastructureError(error, { secrets: [key] });
+					return require_auth_decorators.rejected(failure);
+				}
+			});
+		}
+	};
+}
+const apiKeyPermissionPolicy = {
+	id: "better-auth:api-key/permission",
+	requires: {
+		plugins: ["api-key"],
+		principals: [API_KEY_PRINCIPAL_KIND]
+	},
+	validate(permissions) {
+		if (!Object.keys(permissions).length || Object.values(permissions).some((actions) => !Array.isArray(actions) || !actions.length)) throw new require_auth_errors.BetterAuthConfigurationError("EMPTY_PERMISSIONS", "API-key permissions must contain a resource and actions.");
+	},
+	evaluate(permissions, context) {
+		return context.principal.delegation.allows(permissions) ? { effect: "allow" } : {
+			effect: "deny",
+			reason: "MISSING_PERMISSION"
+		};
+	}
+};
+function apiKeyPermission(permissions) {
+	return {
+		policy: apiKeyPermissionPolicy,
+		params: permissions
+	};
+}
+function RequireApiKeyPermission(permissions) {
+	return require_auth_decorators.Require(apiKeyPermission(permissions));
+}
+//#endregion
+exports.API_KEY_PRINCIPAL_KIND = API_KEY_PRINCIPAL_KIND;
+exports.RequireApiKeyPermission = RequireApiKeyPermission;
+exports.apiKeyPermission = apiKeyPermission;
+exports.apiKeyPrincipal = apiKeyPrincipal;
+
+//# sourceMappingURL=api-key.cjs.map

package/dist/api-key.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-key.cjs","names":["BetterAuthConfigurationError","absent","BetterAuthInfrastructureError","role","authenticated","rejected","AuthFailures","normalizeThrown","Require"],"sources":["../src/api-key.ts"],"sourcesContent":["import { role } from \"better-auth/plugins/access\";\nimport type {\n  AuthHandle,\n  AuthPrincipalBase,\n  AuthorizationPolicy,\n  PrincipalDelegation,\n  PrincipalSource,\n  Requirement,\n} from \"./auth-contracts.js\";\nimport { Require } from \"./auth-decorators.js\";\nimport {\n  AuthFailures,\n  BetterAuthConfigurationError,\n  BetterAuthInfrastructureError,\n  normalizeThrown,\n} from \"./auth-errors.js\";\nimport { absent, authenticated, rejected } from \"./principal-resolver.js\";\n\nexport const API_KEY_PRINCIPAL_KIND = \"api-key\" as const;\nexport interface ApiKeyPrincipal extends AuthPrincipalBase {\n  readonly kind: \"api-key\";\n  readonly keyId: string;\n  readonly configId: string | null;\n  readonly referenceId: string;\n  readonly userId: string | null;\n  readonly organizationId: string | null;\n  readonly permissions: Readonly<Record<string, readonly string[]>> | null;\n  readonly delegation: PrincipalDelegation;\n}\n// The public module identity survives declaration bundling in both output formats.\ndeclare module \"nestjs-slightly-better-auth\" {\n  interface PrincipalKinds {\n    \"api-key\": ApiKeyPrincipal;\n  }\n}\nexport interface ApiKeyPrincipalOptions {\n  header?: string;\n  configId?: string;\n  references?:\n    | \"user\"\n    | \"organization\"\n    | ((key: { readonly configId: string | null }) => \"user\" | \"organization\");\n  /**\n   * Default true: slow INVALID_API_KEY results (>500 ms) throw infrastructure errors,\n   * then fast failures share one read/no-op-write probe per second per instance.\n   * false disables both checks; { slowMs: false } keeps only the probe.\n   * Set slowMs below pool lock/statement timeouts and above custom hashing costs.\n   * Fast failures confined to one row, or secondary storage without database fallback,\n   * may still look like invalid keys. A statement-level trigger can observe the zero-row write.\n   */\n  outageProbe?: boolean | { readonly slowMs?: number | false };\n  acceptance?: \"default\" | \"explicit\";\n}\ninterface VerifiedKey {\n  id: string;\n  configId?: string | null;\n  referenceId: string;\n  permissions?: Record<string, readonly string[]> | null;\n}\ninterface Verification {\n  valid: boolean;\n  key?: VerifiedKey | null;\n  error?: { code?: string; details?: { tryAgainIn?: number } } | null;\n}\ninterface KeyApi {\n  verifyApiKey(input: {\n    body: { key: string; configId?: string };\n    headers: Headers;\n  }): Promise<Verification>;\n}\nexport function apiKeyPrincipal(\n  options: ApiKeyPrincipalOptions = {},\n): PrincipalSource<ApiKeyPrincipal> {\n  const header = options.header ?? \"x-api-key\";\n  const slowMs =\n    typeof options.outageProbe === \"object\"\n      ? (options.outageProbe.slowMs ?? 500)\n      : 500;\n  if (\n    !header.trim() ||\n    (slowMs !== false && (!Number.isFinite(slowMs) || slowMs < 0))\n  ) {\n    throw new BetterAuthConfigurationError(\n      \"INVALID_API_KEY_OPTIONS\",\n      \"API-key header must be nonempty and slowMs must be finite and nonnegative.\",\n    );\n  }\n  const verificationMemo = Symbol(\"api-key-verification\");\n  const probes = new WeakMap<\n    object,\n    { at: number; pending: boolean; result: Promise<void> }\n  >();\n  async function probe(auth: AuthHandle): Promise<void> {\n    const previous = probes.get(auth.instance);\n    if (previous && (previous.pending || Date.now() - previous.at < 1000)) {\n      return previous.result;\n    }\n    const result = (async () => {\n      const context = await auth.context();\n      // The logical key column is string-valued for default, UUID and serial IDs.\n      const where = [{ field: \"key\", value: crypto.randomUUID() }];\n      await context.adapter.findOne({ model: \"apikey\", where });\n      await context.adapter.updateMany({\n        model: \"apikey\",\n        where,\n        update: { updatedAt: new Date() },\n      });\n    })();\n    const state = { at: Date.now(), pending: true, result };\n    probes.set(auth.instance, state);\n    void result.then(\n      () => {\n        state.pending = false;\n      },\n      () => {\n        state.pending = false;\n      },\n    );\n    return result;\n  }\n  return {\n    id: \"better-auth:api-key\",\n    kinds: [API_KEY_PRINCIPAL_KIND],\n    acceptance: options.acceptance ?? \"explicit\",\n    delegates: true,\n    credentialHeaders: [header],\n    effects: { consumesQuota: true, writes: true },\n    requires: { plugins: [\"api-key\"] },\n    appliesTo: (request) => request.headers.has(header),\n    async resolve(request) {\n      if (!request.headers.has(header)) {\n        return absent();\n      }\n      return request.memo(verificationMemo, async () => {\n        const key = request.headers.get(header)!;\n        const headers = new Headers();\n        for (const name of [\"host\", \"x-forwarded-host\", \"x-forwarded-proto\"]) {\n          const value = request.headers.get(name);\n          if (value !== null) {\n            headers.set(name, value);\n          }\n        }\n        const started = performance.now();\n        try {\n          const result = await request.auth.run(\n            {\n              cookies: request.cookies,\n              inbound: () => request.headers,\n              internal: true,\n            },\n            () =>\n              (request.auth.api as unknown as KeyApi).verifyApiKey({\n                body: {\n                  key,\n                  ...(options.configId === undefined\n                    ? {}\n                    : { configId: options.configId }),\n                },\n                headers,\n              }),\n          );\n          if (result.valid) {\n            const verified = result.key;\n            if (\n              !verified ||\n              typeof verified.id !== \"string\" ||\n              typeof verified.referenceId !== \"string\"\n            ) {\n              throw new BetterAuthInfrastructureError(\n                new Error(\"Malformed API-key verification result\"),\n              );\n            }\n            const configId = verified.configId ?? null;\n            const references =\n              typeof options.references === \"function\"\n                ? options.references({ configId })\n                : (options.references ?? \"user\");\n            const permissions = verified.permissions ?? null;\n            const grant = role(permissions ?? {});\n            return authenticated({\n              kind: API_KEY_PRINCIPAL_KIND,\n              source: \"better-auth:api-key\",\n              keyId: verified.id,\n              configId,\n              referenceId: verified.referenceId,\n              userId: references === \"user\" ? verified.referenceId : null,\n              organizationId:\n                references === \"organization\" ? verified.referenceId : null,\n              permissions,\n              delegation: {\n                description: \"api-key permissions\",\n                allows: (requested) => grant.authorize(requested).success,\n              },\n            });\n          }\n          const code = result.error?.code;\n          if (code === \"RATE_LIMITED\" || code === \"USAGE_EXCEEDED\") {\n            const retry = result.error?.details?.tryAgainIn;\n            return rejected(\n              AuthFailures.rejected({\n                status: 429,\n                reason: code,\n                ...(code === \"RATE_LIMITED\" && typeof retry === \"number\"\n                  ? { retryAfterSeconds: retry / 1000 }\n                  : {}),\n              }),\n            );\n          }\n          if (code === \"INVALID_API_KEY\" && options.outageProbe !== false) {\n            if (slowMs !== false && performance.now() - started > slowMs) {\n              throw new BetterAuthInfrastructureError(\n                new Error(\"API-key verification exceeded the outage threshold\"),\n              );\n            }\n            await probe(request.auth);\n          }\n          if (\n            code === \"INVALID_API_KEY\" ||\n            code === \"KEY_NOT_FOUND\" ||\n            code === \"KEY_DISABLED\" ||\n            code === \"KEY_EXPIRED\"\n          ) {\n            return rejected(\n              AuthFailures.rejected({ status: 401, reason: code }),\n            );\n          }\n          throw new BetterAuthInfrastructureError(\n            new Error(\n              `Unexpected API-key verification error: ${code ?? \"missing code\"}`,\n            ),\n          );\n        } catch (error) {\n          const failure = normalizeThrown(\n            error,\n            \"source\",\n            \"better-auth:api-key\",\n            [key],\n          );\n          if (\"sessionLoss\" in failure) {\n            throw new BetterAuthInfrastructureError(error, { secrets: [key] });\n          }\n          return rejected(failure);\n        }\n      });\n    },\n  };\n}\nconst apiKeyPermissionPolicy: AuthorizationPolicy<\n  Record<string, string[]>,\n  ApiKeyPrincipal\n> = {\n  id: \"better-auth:api-key/permission\",\n  requires: { plugins: [\"api-key\"], principals: [API_KEY_PRINCIPAL_KIND] },\n  validate(permissions) {\n    if (\n      !Object.keys(permissions).length ||\n      Object.values(permissions).some(\n        (actions) => !Array.isArray(actions) || !actions.length,\n      )\n    ) {\n      throw new BetterAuthConfigurationError(\n        \"EMPTY_PERMISSIONS\",\n        \"API-key permissions must contain a resource and actions.\",\n      );\n    }\n  },\n  evaluate(permissions, context) {\n    return context.principal.delegation.allows(permissions)\n      ? { effect: \"allow\" }\n      : { effect: \"deny\", reason: \"MISSING_PERMISSION\" };\n  },\n};\nexport function apiKeyPermission(\n  permissions: Record<string, string[]>,\n): Requirement<Record<string, string[]>> {\n  return { policy: apiKeyPermissionPolicy, params: permissions };\n}\nexport function RequireApiKeyPermission(\n  permissions: Record<string, string[]>,\n): ClassDecorator & MethodDecorator {\n  return Require(apiKeyPermission(permissions));\n}\n"],"mappings":"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"}

package/dist/api-key.d.cts

@@ -0,0 +1,42 @@
+import { Y as PrincipalDelegation, et as PrincipalSource, nt as Requirement, o as AuthPrincipalBase } from "./auth-contracts-BBA1C1gj.cjs";
+//#region src/api-key.d.ts
+export declare const API_KEY_PRINCIPAL_KIND: "api-key";
+export interface ApiKeyPrincipal extends AuthPrincipalBase {
+  readonly kind: "api-key";
+  readonly keyId: string;
+  readonly configId: string | null;
+  readonly referenceId: string;
+  readonly userId: string | null;
+  readonly organizationId: string | null;
+  readonly permissions: Readonly<Record<string, readonly string[]>> | null;
+  readonly delegation: PrincipalDelegation;
+}
+declare module "nestjs-slightly-better-auth" {
+  interface PrincipalKinds {
+    "api-key": ApiKeyPrincipal;
+  }
+}
+export interface ApiKeyPrincipalOptions {
+  header?: string;
+  configId?: string;
+  references?: "user" | "organization" | ((key: {
+    readonly configId: string | null;
+  }) => "user" | "organization");
+  /**
+   * Default true: slow INVALID_API_KEY results (>500 ms) throw infrastructure errors,
+   * then fast failures share one read/no-op-write probe per second per instance.
+   * false disables both checks; { slowMs: false } keeps only the probe.
+   * Set slowMs below pool lock/statement timeouts and above custom hashing costs.
+   * Fast failures confined to one row, or secondary storage without database fallback,
+   * may still look like invalid keys. A statement-level trigger can observe the zero-row write.
+   */
+  outageProbe?: boolean | {
+    readonly slowMs?: number | false;
+  };
+  acceptance?: "default" | "explicit";
+}
+export declare function apiKeyPrincipal(options?: ApiKeyPrincipalOptions): PrincipalSource<ApiKeyPrincipal>;
+export declare function apiKeyPermission(permissions: Record<string, string[]>): Requirement<Record<string, string[]>>;
+export declare function RequireApiKeyPermission(permissions: Record<string, string[]>): ClassDecorator & MethodDecorator;
+//#endregion
+//# sourceMappingURL=api-key.d.cts.map

package/dist/api-key.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-key.d.cts","names":[],"sources":["../src/api-key.ts"],"mappings":";;qBAkBa;iBACI,wBAAwB;WAC9B;WACA;WACA;WACA;WACA;WACA;WACA,aAAa,SAAS;WACtB,YAAY;;;YAIX;IACR,WAAW;;;iBAGE;EACf;EACA;EACA,yCAGM;aAAgB;;;;;;;;;;EAStB;aAAmC;;EACnC;;wBAmBc,gBACd,UAAS,yBACR,gBAAgB;wBAwMH,iBACd,aAAa,2BACZ,YAAY;wBAGC,wBACd,aAAa,2BACZ,iBAAiB"}

package/dist/api-key.d.mts

@@ -0,0 +1,42 @@
+import { Y as PrincipalDelegation, et as PrincipalSource, nt as Requirement, o as AuthPrincipalBase } from "./auth-contracts-tqsfBZ8B.mjs";
+//#region src/api-key.d.ts
+export declare const API_KEY_PRINCIPAL_KIND: "api-key";
+export interface ApiKeyPrincipal extends AuthPrincipalBase {
+  readonly kind: "api-key";
+  readonly keyId: string;
+  readonly configId: string | null;
+  readonly referenceId: string;
+  readonly userId: string | null;
+  readonly organizationId: string | null;
+  readonly permissions: Readonly<Record<string, readonly string[]>> | null;
+  readonly delegation: PrincipalDelegation;
+}
+declare module "nestjs-slightly-better-auth" {
+  interface PrincipalKinds {
+    "api-key": ApiKeyPrincipal;
+  }
+}
+export interface ApiKeyPrincipalOptions {
+  header?: string;
+  configId?: string;
+  references?: "user" | "organization" | ((key: {
+    readonly configId: string | null;
+  }) => "user" | "organization");
+  /**
+   * Default true: slow INVALID_API_KEY results (>500 ms) throw infrastructure errors,
+   * then fast failures share one read/no-op-write probe per second per instance.
+   * false disables both checks; { slowMs: false } keeps only the probe.
+   * Set slowMs below pool lock/statement timeouts and above custom hashing costs.
+   * Fast failures confined to one row, or secondary storage without database fallback,
+   * may still look like invalid keys. A statement-level trigger can observe the zero-row write.
+   */
+  outageProbe?: boolean | {
+    readonly slowMs?: number | false;
+  };
+  acceptance?: "default" | "explicit";
+}
+export declare function apiKeyPrincipal(options?: ApiKeyPrincipalOptions): PrincipalSource<ApiKeyPrincipal>;
+export declare function apiKeyPermission(permissions: Record<string, string[]>): Requirement<Record<string, string[]>>;
+export declare function RequireApiKeyPermission(permissions: Record<string, string[]>): ClassDecorator & MethodDecorator;
+//#endregion
+//# sourceMappingURL=api-key.d.mts.map

package/dist/api-key.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-key.d.mts","names":[],"sources":["../src/api-key.ts"],"mappings":";;qBAkBa;iBACI,wBAAwB;WAC9B;WACA;WACA;WACA;WACA;WACA;WACA,aAAa,SAAS;WACtB,YAAY;;;YAIX;IACR,WAAW;;;iBAGE;EACf;EACA;EACA,yCAGM;aAAgB;;;;;;;;;;EAStB;aAAmC;;EACnC;;wBAmBc,gBACd,UAAS,yBACR,gBAAgB;wBAwMH,iBACd,aAAa,2BACZ,YAAY;wBAGC,wBACd,aAAa,2BACZ,iBAAiB"}