@lenne.tech/nest-server 11.41.2 → 11.41.4

package/src/core/modules/api-token/core-api-token.constants.ts

@@ -0,0 +1,27 @@
+// Import-free leaf on purpose: guards of three modules (auth, better-auth, tenant) read these values,
+// and a leaf can never be mid-evaluation when one of them imports it (see .claude/rules/architecture.md
+// → "DI Token Placement (SWC-Safe)").
+
+/**
+ * Injection token / Mongoose model name for API tokens.
+ */
+export const API_TOKEN_MODEL_TOKEN = 'ApiToken';
+
+/**
+ * Metadata key for the `@ApiTokenScopes()` decorator.
+ */
+export const API_TOKEN_SCOPES_KEY = 'apiTokenScopes';
+
+/**
+ * Who an API token belongs to.
+ *
+ * - `USER`: owned by a user; acts with that user's CURRENT rights (never global roles such as ADMIN),
+ *   optionally narrowed to scopes, one tenant and a maximum tenant role. Works with and without
+ *   multi-tenancy.
+ * - `TENANT`: owned by a tenant, independent of any person; managed by the tenant's administrators,
+ *   acts with the lowest tenant role and only inside its own tenant. Requires multi-tenancy.
+ */
+export enum ApiTokenKind {
+  TENANT = 'tenant',
+  USER = 'user',
+}

package/src/core/modules/api-token/core-api-token.decorators.ts

@@ -0,0 +1,29 @@
+import { SetMetadata } from '@nestjs/common';
+
+import { API_TOKEN_SCOPES_KEY } from './core-api-token.constants';
+
+/**
+ * Method/class decorator that opens an endpoint to API tokens (`apiTokens` config).
+ *
+ * Tokens are DENIED on every route by default — user tokens and tenant tokens alike. A route accepts
+ * one only when it names the scopes that may call it; a token holding ANY one of them passes. A
+ * method-level declaration replaces the class-level one rather than adding to it, so a class can open
+ * itself for `'read'` while a single method narrows to `'export'`.
+ *
+ * Opening a route does not widen what a token may do there, it only stops the blanket refusal:
+ * - a USER token then acts as its user (without global roles), bounded by the token's own limits;
+ * - a TENANT token acts as a member of its tenant with the LOWEST role of the hierarchy, and
+ *   `S_EVERYONE` / `S_USER` / `S_VERIFIED` count as satisfied for it.
+ *
+ * @example
+ * ```typescript
+ * @ApiTokenScopes('upload')
+ * @Roles(RoleEnum.S_USER)
+ * @Post('documents')
+ * async upload(@CurrentUser() caller: any) {
+ *   const token = getApiTokenContext(caller); // undefined for a session, set for a token
+ * }
+ * ```
+ */
+export const ApiTokenScopes = (scope: string, ...moreScopes: string[]) =>
+  SetMetadata(API_TOKEN_SCOPES_KEY, [scope, ...moreScopes]);