@lenne.tech/nest-server 11.41.3 → 11.41.5

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

@@ -0,0 +1,57 @@
+import { HttpException, HttpStatus, Injectable, NestMiddleware, Optional, UnauthorizedException } from '@nestjs/common';
+import { NextFunction, Request, Response } from 'express';
+
+import { ErrorCode } from '../error-code/error-codes';
+import { getApiTokenConfig, getApiTokenContext, readApiTokenCredentialFromHeaders } from './core-api-token.helpers';
+import { CoreApiTokenService } from './core-api-token.service';
+
+/**
+ * Authenticates requests that carry an API token or a signed assertion — `Authorization: Bearer …` or
+ * `x-api-key: …` — and sets `request.user` (a tenant-token principal, or the owning user of a user
+ * token, both carrying the token context).
+ *
+ * Only credentials with the configured prefix are claimed; Better-Auth sessions, JWTs and legacy tokens
+ * pass through untouched (and `CoreBetterAuthMiddleware` in turn leaves prefixed credentials alone).
+ *
+ * A prefixed credential that does not authenticate is answered with 401 on EVERY route, public ones
+ * included — never silently downgraded to anonymous: an integration whose token was revoked must learn
+ * that at once, not by missing data. Whether an authenticated token may call a route is decided later by
+ * the guards (`@ApiTokenScopes`).
+ */
+@Injectable()
+export class CoreApiTokenMiddleware implements NestMiddleware {
+  constructor(@Optional() protected readonly apiTokenService?: CoreApiTokenService) {}
+
+  async use(req: Request & { user?: unknown }, res: Response, next: NextFunction): Promise<void> {
+    const config = getApiTokenConfig();
+    if (!config.enabled) {
+      return next();
+    }
+
+    const credential = readApiTokenCredentialFromHeaders(req.headers, config.prefix);
+    if (!credential) {
+      return next();
+    }
+    if (credential === 'conflict' || !this.apiTokenService) {
+      throw new UnauthorizedException(ErrorCode.UNAUTHORIZED);
+    }
+
+    const user = await this.apiTokenService.authenticate(credential);
+    const context = getApiTokenContext(user);
+    if (!user || !context) {
+      throw new UnauthorizedException(ErrorCode.UNAUTHORIZED);
+    }
+
+    const limited = await this.apiTokenService.consumeRateLimit(context.tokenId);
+    if (limited) {
+      res.setHeader('Retry-After', String(limited.retryAfter));
+      throw new HttpException(ErrorCode.RATE_LIMIT_EXCEEDED, HttpStatus.TOO_MANY_REQUESTS);
+    }
+
+    this.apiTokenService.touchLastUsed(context.tokenId);
+    // An explicit credential header wins over anything implicit (a cookie) — the same priority
+    // Better-Auth applies between its Authorization header and its session cookie.
+    req.user = user;
+    next();
+  }
+}

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

@@ -0,0 +1,193 @@
+import { ObjectType } from '@nestjs/graphql';
+import { Schema } from '@nestjs/mongoose';
+
+import { Restricted } from '../../common/decorators/restricted.decorator';
+import { UnifiedField } from '../../common/decorators/unified-field.decorator';
+import { RoleEnum } from '../../common/enums/role.enum';
+import { accessDeniedException } from '../../common/exceptions/access-denied.exception';
+import { CorePersistenceModel } from '../../common/models/core-persistence.model';
+import { ConfigService } from '../../common/services/config.service';
+import { RequestContext } from '../../common/services/request-context.service';
+import { checkRoleAccess } from '../tenant/core-tenant.helpers';
+import { ApiTokenKind } from './core-api-token.constants';
+import { getApiTokenContext, getApiTokenManageRole } from './core-api-token.helpers';
+
+/**
+ * API token (`apiTokens` config): a USER token or a TENANT token, see {@link ApiTokenKind}.
+ *
+ * The secret itself is never stored — only its SHA-256 hash (`secretHash`) and the AES-GCM encrypted
+ * signing key for assertions (`signingKeyEncrypted`). Both are `select: false` and `@Restricted(S_NO_ONE)`,
+ * so neither a plain query nor a response carries them.
+ *
+ * The tenant field is `tenant`, not `tenantId` — like `CoreTenantMemberModel` — so the tenant plugin
+ * does not filter this collection: authentication has to find a token before any tenant is known, and
+ * the service scopes every management query explicitly.
+ *
+ * Projects extend this model to bind a token to their own data (an upload target, an export setting)
+ * and pass the subclass to `CoreApiTokenModule.forRoot({ model })` / `CoreModule` overrides.
+ */
+@ObjectType({ description: 'API token', isAbstract: true })
+@Restricted(RoleEnum.S_USER)
+@Schema({ timestamps: true })
+export class CoreApiTokenModel extends CorePersistenceModel {
+  /** ID of the user who created the token */
+  @UnifiedField({
+    description: 'ID of the creating user',
+    isOptional: true,
+    mongoose: { type: String },
+    roles: RoleEnum.S_USER,
+  })
+  createdBy: string = undefined;
+
+  /** Free-text description */
+  @UnifiedField({ description: 'Description', isOptional: true, mongoose: { type: String }, roles: RoleEnum.S_USER })
+  description: string = undefined;
+
+  /** Expiry; `null` = no expiry */
+  @UnifiedField({
+    description: 'Expiry date',
+    isOptional: true,
+    mongoose: { default: null, type: Date },
+    roles: RoleEnum.S_USER,
+    type: Date,
+  })
+  expiresAt: Date = undefined;
+
+  /** USER or TENANT */
+  @UnifiedField({
+    description: 'Token kind',
+    mongoose: { enum: Object.values(ApiTokenKind), required: true, type: String },
+    roles: RoleEnum.S_USER,
+    type: () => String,
+  })
+  kind: ApiTokenKind = undefined;
+
+  /** Last successful use (updated at most once per minute and process) */
+  @UnifiedField({
+    description: 'Last use',
+    isOptional: true,
+    mongoose: { default: null, type: Date },
+    roles: RoleEnum.S_USER,
+    type: Date,
+  })
+  lastUsedAt: Date = undefined;
+
+  /** USER tokens: the highest tenant role the token may act with (a cap, never a grant) */
+  @UnifiedField({
+    description: 'Maximum tenant role',
+    isOptional: true,
+    mongoose: { type: String },
+    roles: RoleEnum.S_USER,
+  })
+  maxTenantRole: string = undefined;
+
+  /** Display name */
+  @UnifiedField({ description: 'Name', mongoose: { required: true, type: String }, roles: RoleEnum.S_USER })
+  name: string = undefined;
+
+  /** Public part of the token, used for the lookup (not a secret) */
+  @UnifiedField({
+    description: 'Public token id',
+    mongoose: { required: true, type: String, unique: true },
+    roles: RoleEnum.S_USER,
+  })
+  publicId: string = undefined;
+
+  /** Revocation date; a revoked token is refused */
+  @UnifiedField({
+    description: 'Revocation date',
+    isOptional: true,
+    mongoose: { default: null, type: Date },
+    roles: RoleEnum.S_USER,
+    type: Date,
+  })
+  revokedAt: Date = undefined;
+
+  /** Scopes (subset of `apiTokens.scopes`) */
+  @UnifiedField({
+    description: 'Scopes',
+    isArray: true,
+    mongoose: { default: [], type: [String] },
+    roles: RoleEnum.S_USER,
+    type: () => String,
+  })
+  scopes: string[] = undefined;
+
+  /** SHA-256 of the token secret — never returned */
+  @Restricted(RoleEnum.S_NO_ONE)
+  @UnifiedField({
+    description: 'Secret hash',
+    isOptional: true,
+    mongoose: { select: false, type: String },
+    roles: RoleEnum.S_NO_ONE,
+  })
+  secretHash: string = undefined;
+
+  /** AES-256-GCM encrypted signing key for assertions — never returned */
+  @Restricted(RoleEnum.S_NO_ONE)
+  @UnifiedField({
+    description: 'Encrypted signing key',
+    isOptional: true,
+    mongoose: { select: false, type: String },
+    roles: RoleEnum.S_NO_ONE,
+  })
+  signingKeyEncrypted: string = undefined;
+
+  /** TENANT tokens: the owning tenant. USER tokens: the one tenant the token is restricted to, if any */
+  @UnifiedField({
+    description: 'Tenant ID',
+    isOptional: true,
+    mongoose: { index: true, type: String },
+    roles: RoleEnum.S_USER,
+  })
+  tenant: string = undefined;
+
+  /** ID of the user who last changed the token */
+  @UnifiedField({
+    description: 'ID of the last updating user',
+    isOptional: true,
+    mongoose: { type: String },
+    roles: RoleEnum.S_USER,
+  })
+  updatedBy: string = undefined;
+
+  /** USER tokens: the owning user */
+  @UnifiedField({
+    description: 'Owning user ID',
+    isOptional: true,
+    mongoose: { index: true, type: String },
+    roles: RoleEnum.S_USER,
+  })
+  user: string = undefined;
+
+  /**
+   * Who may see a token object:
+   * - its owner (USER tokens),
+   * - a platform admin (while `multiTenancy.adminBypass` is on, or without multi-tenancy),
+   * - a person holding the manage role in the token's tenant (TENANT tokens).
+   *
+   * A request authenticated WITH a token never sees token objects — tokens do not manage tokens.
+   */
+  override securityCheck(user: any, force?: boolean): this {
+    if (force) return this;
+    if (!user) throw accessDeniedException(user);
+    if (getApiTokenContext(user)) throw accessDeniedException(user);
+
+    if (this.kind === ApiTokenKind.USER && user.id === this.user) return this;
+
+    const adminBypass = ConfigService.configFastButReadOnly?.multiTenancy?.adminBypass !== false;
+    if (adminBypass && user.hasRole?.([RoleEnum.ADMIN])) return this;
+
+    const context = RequestContext.get();
+    if (
+      this.kind === ApiTokenKind.TENANT &&
+      context?.tenantId === this.tenant &&
+      context?.tenantRole &&
+      checkRoleAccess([getApiTokenManageRole()], undefined, context.tenantRole)
+    ) {
+      return this;
+    }
+
+    throw accessDeniedException(user);
+  }
+}

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

@@ -0,0 +1,48 @@
+import { DynamicModule, Global, MiddlewareConsumer, Module, NestModule, Type } from '@nestjs/common';
+import { MongooseModule, SchemaFactory } from '@nestjs/mongoose';
+
+import { API_TOKEN_MODEL_TOKEN } from './core-api-token.constants';
+import { CoreApiTokenMiddleware } from './core-api-token.middleware';
+import { CoreApiTokenModel } from './core-api-token.model';
+import { CoreApiTokenService } from './core-api-token.service';
+
+/**
+ * Options for `CoreApiTokenModule.forRoot()`.
+ */
+export interface CoreApiTokenModuleOptions {
+  /** Custom token model (must extend CoreApiTokenModel) — e.g. to bind a token to project data */
+  model?: Type<CoreApiTokenModel>;
+  /** Custom service (must extend CoreApiTokenService) */
+  service?: Type<CoreApiTokenService>;
+}
+
+/**
+ * API tokens (`apiTokens` config): USER tokens and — with multi-tenancy — TENANT tokens.
+ *
+ * Registered automatically by `CoreModule.forRoot()` when `apiTokens` is configured. Provides the
+ * token model, `CoreApiTokenService` (authentication + management) and `CoreApiTokenMiddleware` on all
+ * routes. Route access is enforced by the framework's guards (RolesGuard / BetterAuthRolesGuard, plus
+ * CoreTenantGuard with multi-tenancy) via `@ApiTokenScopes()`.
+ */
+@Global()
+@Module({})
+export class CoreApiTokenModule implements NestModule {
+  static forRoot(options: CoreApiTokenModuleOptions = {}): DynamicModule {
+    const schema = SchemaFactory.createForClass(options.model || CoreApiTokenModel);
+    // Compound indexes for the two management listings; single-field indexes live on the properties.
+    schema.index({ kind: 1, tenant: 1 });
+    schema.index({ kind: 1, user: 1 });
+
+    return {
+      exports: [CoreApiTokenService],
+      global: true,
+      imports: [MongooseModule.forFeature([{ name: API_TOKEN_MODEL_TOKEN, schema }])],
+      module: CoreApiTokenModule,
+      providers: [{ provide: CoreApiTokenService, useClass: options.service || CoreApiTokenService }],
+    };
+  }
+
+  configure(consumer: MiddlewareConsumer): void {
+    consumer.apply(CoreApiTokenMiddleware).forRoutes('*');
+  }
+}

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

@@ -0,0 +1,53 @@
+/**
+ * Lets the password-reset paths revoke a user's API tokens WITHOUT importing the optional token
+ * module.
+ *
+ * Two places end a user's sessions on a reset — Better-Auth's `onPasswordReset` hook (IAM, when
+ * `betterAuth.emailAndPassword.revokeSessionsOnPasswordReset` is on) and
+ * `CoreUserService.resetPassword()` (legacy, always) — and a user token is a session in all but
+ * lifetime: left alive, the credential a reset was meant to retire keeps working through it. Both
+ * callers live in modules that load whether or not `apiTokens` is configured, so they reach the
+ * service through this registry instead of DI: `CoreApiTokenService` fills it while it runs, and
+ * without it every call is a no-op.
+ *
+ * A true leaf: no imports, so it can never be mid-evaluation when a cycle-adjacent file reads it
+ * (see `.claude/rules/architecture.md` → "DI Token Placement (SWC-Safe)").
+ *
+ * @internal Not public API, but required by the shipped better-auth and user modules.
+ */
+
+/** Who a reset belongs to — any one field is enough; `userId` is the `users` document id. */
+export interface ApiTokenOwnerIdentity {
+  email?: string;
+  iamId?: string;
+  userId?: string;
+}
+
+type ApiTokenRevoker = (identity: ApiTokenOwnerIdentity) => Promise<number>;
+
+let revoker: ApiTokenRevoker | undefined;
+
+/**
+ * Register (or, with `undefined`, clear) the function that revokes a user's tokens.
+ * Returns a disposer that clears it again only if it is still the registered one.
+ *
+ * @internal
+ */
+export function setApiTokenRevoker(fn: ApiTokenRevoker | undefined): () => void {
+  revoker = fn;
+  return () => {
+    if (revoker === fn) {
+      revoker = undefined;
+    }
+  };
+}
+
+/**
+ * Revoke every token of a user. Resolves to the number revoked — `0` when the token module is not
+ * running, so callers never need to know whether it is.
+ *
+ * @internal
+ */
+export async function revokeApiTokensOfUser(identity: ApiTokenOwnerIdentity): Promise<number> {
+  return revoker ? revoker(identity) : 0;
+}