@lenne.tech/nest-server 11.41.2 → 11.41.4

package/src/core/common/interfaces/server-options.interface.ts

@@ -1473,6 +1473,86 @@ export interface IMultiTenancy {
   cacheTtlMs?: number;
 }
 
+/**
+ * Configuration of API tokens (`apiTokens`).
+ *
+ * Two kinds share one model and one policy:
+ * - USER tokens act as their user with the user's CURRENT rights (never global roles), optionally
+ *   narrowed to scopes, one tenant and a maximum tenant role. Work with and without multi-tenancy.
+ * - TENANT tokens belong to a tenant, are managed by its administrators and act with the lowest tenant
+ *   role inside that tenant only. Available while multi-tenancy is active.
+ *
+ * Both are denied on every route that does not declare `@ApiTokenScopes(...)`.
+ *
+ * @since 11.41.4
+ */
+export interface IApiTokens {
+  /**
+   * Pre-configure without enabling.
+   * @default true (when the object is present)
+   */
+  enabled?: boolean;
+
+  /**
+   * Pass-phrase for the AES-256-GCM encryption of each token's signing key (used for signed
+   * assertions). Falls back to the `SECRETS_ENCRYPTION_KEY` environment variable. REQUIRED in
+   * `production` / `staging` — the boot fails without it; elsewhere an insecure development default
+   * is used with a warning. Rotating it invalidates the signing keys of all existing tokens.
+   */
+  encryptionKey?: string;
+
+  /**
+   * Tenant role required to create, list, change, revoke and delete TENANT tokens. Hierarchy roles
+   * compare by level, so higher roles qualify too. Must be a declared tenant role that the lowest
+   * hierarchy role (the role a tenant token acts with) does not reach. Platform admins qualify while
+   * `multiTenancy.adminBypass` is on.
+   * @default the highest role of `multiTenancy.roleHierarchy`
+   */
+  manageRole?: string;
+
+  /**
+   * Maximum lifetime of a signed assertion, measured from the moment it is presented. A longer-lived
+   * assertion is refused (401). An invalid value falls back to the default — never to "unbounded".
+   * @default 900 (15 minutes)
+   */
+  maxAssertionLifetimeSeconds?: number;
+
+  /**
+   * Recognisable token prefix: 2-16 characters, lowercase letters and digits, starting with a letter.
+   * Tokens read `<prefix>_<publicId>_<secret>`, assertions `<prefix>s_<payload>.<signature>`.
+   * @default 'ltt'
+   */
+  prefix?: string;
+
+  /**
+   * Per-token request limit (fixed window, shared across replicas when `redis` is configured).
+   * An exceeded limit answers 429 with `Retry-After`. `false` switches it off.
+   * @default { max: 600, windowSeconds: 60 }
+   */
+  rateLimit?: boolean | { enabled?: boolean; max?: number; windowSeconds?: number };
+
+  /**
+   * Vocabulary of scopes a token may carry (e.g. `['upload', 'read', 'export']`). Creating or updating
+   * a token with any other scope fails with 400; with an empty vocabulary no token can be created.
+   * A user token created without scopes receives the whole vocabulary.
+   * Scopes: 1-64 characters of letters, digits, `:`, `.`, `_`, `-`.
+   * @default []
+   */
+  scopes?: string[];
+
+  /**
+   * Allow tenant tokens. Only takes effect while multi-tenancy is active.
+   * @default true
+   */
+  tenantTokens?: boolean;
+
+  /**
+   * Allow user tokens.
+   * @default true
+   */
+  userTokens?: boolean;
+}
+
 /**
  * Cookie configuration for authentication handling.
  *
@@ -2020,6 +2100,20 @@ export interface IServerOptions {
    */
   appUrl?: string;
 
+  /**
+   * API tokens: bearer credentials for machine clients and embedded pages that cannot carry a session
+   * cookie. USER tokens act as their user (without global roles); TENANT tokens belong to a tenant
+   * (multi-tenancy only). Both are denied on every route that does not declare `@ApiTokenScopes(...)`,
+   * and both respect tenant boundaries whenever multi-tenancy is active.
+   *
+   * Boolean shorthand: `true` / `{}` enable with defaults, `{ enabled: false }` pre-configures,
+   * absent = off (no behaviour change). See `src/core/modules/api-token/README.md`.
+   *
+   * @default undefined (disabled)
+   * @since 11.41.4
+   */
+  apiTokens?: boolean | IApiTokens;
+
   /**
    * Authentication system configuration
    *
@@ -4322,6 +4416,22 @@ interface IBetterAuthWithPasskey extends IBetterAuthBase {
  * @since 11.22.0
  */
 export interface ICoreModuleOverrides {
+  /**
+   * Override API token collaborators with project-specific subclasses (`apiTokens` config).
+   *
+   * - `model` must extend `CoreApiTokenModel` (e.g. to bind a token to project data)
+   * - `service` must extend `CoreApiTokenService`
+   *
+   * @example
+   * ```typescript
+   * { apiToken: { model: ApiToken, service: ApiTokenService } }
+   * ```
+   */
+  apiToken?: {
+    model?: Type<any>;
+    service?: Type<any>;
+  };
+
   /**
    * Override AI module collaborators with project-specific subclasses.
    *

package/src/core/modules/ai/INTEGRATION-CHECKLIST.md

@@ -209,9 +209,15 @@ The response body carries the stable `#LTNS_0901` code, never the raw error.
 
 ```typescript
 import { mountAiMcpOAuth } from '@lenne.tech/nest-server';
-await mountAiMcpOAuth(app, { baseUrl: process.env.BASE_URL });
+await mountAiMcpOAuth(app);
 ```
 
+**WHY no `baseUrl` argument:** the issuer is every URL in the discovery metadata, and MCP clients
+follow them. The helper takes it from the server's `baseUrl` (`NSC__BASE_URL` when deployed) and
+fails the boot in a deployed environment that has none, rather than advertising `localhost` —
+which sends clients to the user's own machine. Pass `{ baseUrl }` only for an issuer that must
+differ from the server's `baseUrl`; never add a `localhost` fallback of your own.
+
 Override `CoreAiMcpOAuthService.authorizeConsent()` with your login/consent UI (the only
 browser-interactive step). All other OAuth pieces (tokens, PKCE, stores) are built in.
 
@@ -231,12 +237,13 @@ browser-interactive step). All other OAuth pieces (tokens, PKCE, stores) are bui
 
 ## Common Mistakes
 
-| Mistake                                       | Symptom                                                       | Fix                                                       |
-| --------------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------- |
-| No `ai` config block                          | Module not loaded, `aiPrompt` missing from schema             | Add an `ai` block (presence implies enabled)              |
-| No encryption secret in prod                  | **App refuses to boot** (throws); dev/local only warns        | Set `NSC__AI__ENCRYPTION_SECRET` (32+ chars)              |
-| Encryption secret changed after keys stored   | Boot logs "key(s) could not be decrypted"; those prompts fail | Re-enter the API key for the listed connections           |
-| Tool returns `.lean()`/aggregate data         | `@Restricted` fields leak into the LLM context                | Route through `CrudService` with `context.serviceOptions` |
-| Tool not registered                           | Tool never offered to the LLM                                 | Declare it as a provider in a module (extends `AiTool`)   |
-| Overridden resolver method missing decorators | Method absent from GraphQL schema                             | Re-declare `@Mutation`/`@Query`/`@Roles` in the override  |
-| Storing a real API key in `config.env.ts`     | Secret committed to the repo                                  | Use `apiKeyEnv` or the runtime connection CRUD            |
+| Mistake                                          | Symptom                                                                                | Fix                                                                |
+| ------------------------------------------------ | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| No `ai` config block                             | Module not loaded, `aiPrompt` missing from schema                                      | Add an `ai` block (presence implies enabled)                       |
+| No encryption secret in prod                     | **App refuses to boot** (throws); dev/local only warns                                 | Set `NSC__AI__ENCRYPTION_SECRET` (32+ chars)                       |
+| Encryption secret changed after keys stored      | Boot logs "key(s) could not be decrypted"; those prompts fail                          | Re-enter the API key for the listed connections                    |
+| Tool returns `.lean()`/aggregate data            | `@Restricted` fields leak into the LLM context                                         | Route through `CrudService` with `context.serviceOptions`          |
+| Tool not registered                              | Tool never offered to the LLM                                                          | Declare it as a provider in a module (extends `AiTool`)            |
+| Overridden resolver method missing decorators    | Method absent from GraphQL schema                                                      | Re-declare `@Mutation`/`@Query`/`@Roles` in the override           |
+| Storing a real API key in `config.env.ts`        | Secret committed to the repo                                                           | Use `apiKeyEnv` or the runtime connection CRUD                     |
+| `localhost` fallback for the MCP OAuth `baseUrl` | MCP client fails to register with `ECONNREFUSED`; discovery metadata names `localhost` | Call `mountAiMcpOAuth(app)` without `baseUrl`, set `NSC__BASE_URL` |

package/src/core/modules/ai/README.md

@@ -657,9 +657,17 @@ also accepts OAuth access tokens. Mount the discovery/token endpoints in `main.t
 ```typescript
 // main.ts, after app.init()
 import { mountAiMcpOAuth } from '@lenne.tech/nest-server';
-await mountAiMcpOAuth(app, { baseUrl: process.env.BASE_URL });
+await mountAiMcpOAuth(app);
 ```
 
+The issuer — and with it every endpoint URL in the discovery metadata, which MCP clients follow —
+is the server's `baseUrl` (`NSC__BASE_URL` when deployed), resolved the same way BetterAuth and
+CORS resolve it. `local` / `ci` / `e2e` fall back to `http://localhost:3000`; any other environment
+without a `baseUrl` fails the call instead of guessing, because a deployed API that advertised
+`http://localhost:3000` sent Claude Code off to register the client on the user's own machine.
+Pass `{ baseUrl }` only when the issuer must differ from the server's `baseUrl`, and do not add a
+`localhost` fallback of your own. The resolved issuer is logged once at boot.
+
 Override `CoreAiMcpOAuthService.authorizeConsent()` to wire your login/consent UI.
 Set `ai.mcp.oauthSecret` (or reuse `ai.encryptionSecret`) to a random 32+ char value.
 

package/src/core/modules/ai/helpers/ai-mcp-oauth.helper.ts

@@ -1,3 +1,7 @@
+import { Logger } from '@nestjs/common';
+
+import { resolveServerUrls } from '../../../common/helpers/cookies.helper';
+import { ConfigService } from '../../../common/services/config.service';
 import { CoreAiMcpOAuthService } from '../services/core-ai-mcp-oauth.service';
 
 /**
@@ -11,25 +15,88 @@ import { CoreAiMcpOAuthService } from '../services/core-ai-mcp-oauth.service';
  * The interactive consent step requires `CoreAiMcpOAuthService.authorizeConsent`
  * to be overridden with your login/consent UI (see INTEGRATION-CHECKLIST).
  *
+ * The base URL must be the server's public URL: it becomes the OAuth issuer and
+ * every endpoint in the discovery metadata, and MCP clients follow those URLs.
+ * Resolution order:
+ *
+ * 1. `options.baseUrl`, when non-blank — for an issuer that differs from `baseUrl`
+ * 2. `baseUrl` from the server config (`NSC__BASE_URL` in deployed environments)
+ * 3. `http://localhost:3000` in `local` / `ci` / `e2e` only
+ * 4. otherwise the call throws — it never guesses
+ *
+ * Steps 2 and 3 are `resolveServerUrls()`, the resolver BetterAuth and CORS use, so
+ * the issuer agrees with the URL the rest of the server believes it has. Step 4 is
+ * the point: a deployed API that advertised `http://localhost:3000` made Claude Code
+ * try to register the client on the user's own machine (`ECONNREFUSED`).
+ *
  * @example
  * ```typescript
  * // main.ts, after app.init()
- * await mountAiMcpOAuth(app, { baseUrl: process.env.BASE_URL });
+ * await mountAiMcpOAuth(app);
  * ```
  */
 export async function mountAiMcpOAuth(
   app: { get: (token: any) => any; use: (...args: any[]) => any },
-  options: { baseUrl: string; mcpPath?: string },
+  options: { baseUrl?: string; mcpPath?: string } = {},
 ): Promise<void> {
+  const { baseUrl, source } = resolveMcpOAuthBaseUrl(options.baseUrl);
+  const issuerUrl = parseAbsoluteUrl(baseUrl, source);
   const { mcpAuthRouter } = await import('@modelcontextprotocol/sdk/server/auth/router.js');
   const oauthService: CoreAiMcpOAuthService = app.get(CoreAiMcpOAuthService);
   const mcpPath = options.mcpPath ?? '/ai/mcp';
 
-  const router = mcpAuthRouter({
-    issuerUrl: new URL(options.baseUrl),
-    provider: oauthService.buildOAuthProvider() as any,
-    resourceServerUrl: new URL(`${options.baseUrl.replace(/\/$/, '')}${mcpPath}`),
-  });
+  let router: unknown;
+  try {
+    router = mcpAuthRouter({
+      issuerUrl,
+      provider: oauthService.buildOAuthProvider() as any,
+      resourceServerUrl: new URL(`${baseUrl.replace(/\/$/, '')}${mcpPath}`),
+    });
+  } catch (error) {
+    // The SDK's refusals ("Issuer URL must be HTTPS") do not say which URL they refused. Now
+    // that the URL can come from config rather than from the call site, that is the one thing
+    // an operator needs to know.
+    const reason = (error as Error).message;
+    throw new Error(`mountAiMcpOAuth: OAuth issuer "${baseUrl}" (from ${source}) rejected: ${reason}`, {
+      cause: error,
+    });
+  }
 
   app.use(router);
+  new Logger('mountAiMcpOAuth').log(`MCP OAuth issuer: ${issuerUrl.href} (from ${source})`);
+}
+
+/**
+ * Resolves the issuer base URL. A blank `explicit` value counts as absent, because
+ * `BASE_URL=` in an env file yields `''`, not `undefined`.
+ */
+function resolveMcpOAuthBaseUrl(explicit: string | undefined): { baseUrl: string; source: string } {
+  const given = explicit?.trim();
+  if (given) {
+    return { baseUrl: given, source: 'options.baseUrl' };
+  }
+
+  const config = ConfigService.configFastButReadOnly;
+  const resolved = resolveServerUrls({ baseUrl: config?.baseUrl, env: config?.env });
+  if (resolved.baseUrl) {
+    return {
+      baseUrl: resolved.baseUrl,
+      source:
+        resolved.baseUrlSource === 'localhost-default' ? `localhost default (env: ${config?.env})` : 'config.baseUrl',
+    };
+  }
+
+  throw new Error(
+    `mountAiMcpOAuth: no public server URL for the OAuth issuer (env: ${config?.env ?? 'unset'}). ` +
+      'Set `baseUrl` in the server config (NSC__BASE_URL) or pass `options.baseUrl`. ' +
+      'A guessed localhost URL would send MCP clients to their own machine.',
+  );
+}
+
+function parseAbsoluteUrl(value: string, source: string): URL {
+  try {
+    return new URL(value);
+  } catch {
+    throw new Error(`mountAiMcpOAuth: "${value}" (from ${source}) is not an absolute URL`);
+  }
 }

package/src/core/modules/ai/services/core-ai-mcp-oauth.service.ts

@@ -5,6 +5,7 @@ import { Connection } from 'mongoose';
 
 import { isProductionLikeEnv } from '../../../common/helpers/cookies.helper';
 import { ConfigService } from '../../../common/services/config.service';
+import { getApiTokenContext } from '../../api-token/core-api-token.helpers';
 
 /**
  * Stored OAuth client (dynamically registered).
@@ -309,7 +310,18 @@ export class CoreAiMcpOAuthService implements OnModuleInit {
    */
   buildOAuthProvider(accessTtlSeconds = 3600): Record<string, any> {
     return {
-      authorize: (client: any, params: any, res: any) => this.authorizeConsent(client, params, res),
+      authorize: async (client: any, params: any, res: any) => {
+        // An API token (or its signed assertion) must never approve an OAuth consent. The consent mints
+        // an MCP access token with the FULL rights of its user, which would lift a scope-limited user
+        // token out of every restriction it carries — and a tenant token has no user to consent for at
+        // all. This route is an Express router outside the Nest guards, so the deny-by-default of
+        // @ApiTokenScopes() does not reach it; the check sits here rather than in authorizeConsent()
+        // so an override of that method cannot drop it.
+        if (getApiTokenContext(res?.req?.user)) {
+          throw new Error('access_denied: an API token cannot authorize an OAuth client');
+        }
+        return this.authorizeConsent(client, params, res);
+      },
       challengeForAuthorizationCode: async (_client: any, authorizationCode: string) => {
         const stored = await this.getAuthorizationCode(authorizationCode);
         return stored?.codeChallenge ?? '';

package/src/core/modules/api-token/INTEGRATION-CHECKLIST.md

@@ -0,0 +1,121 @@
+# API Tokens Integration Checklist
+
+## Reference Implementation
+
+- Module: `node_modules/@lenne.tech/nest-server/src/core/modules/api-token/` (README.md explains the model)
+- Management controller as a project writes it: `tests/api-token.e2e-spec.ts` → `ApiTokenAdminController`
+  (in the GitHub repository; not shipped in the npm package)
+
+## Required Steps
+
+### 1. Enable the feature
+
+**Edit:** `src/config.env.ts`
+
+```typescript
+apiTokens: {
+  scopes: ['upload', 'read', 'export'],
+  encryptionKey: process.env.API_TOKEN_ENCRYPTION_KEY, // or SECRETS_ENCRYPTION_KEY
+},
+```
+
+**WHY the key:** the signing key of every token (for signed assertions) is stored encrypted with it.
+The boot fails in production/staging without one. Rotating it invalidates all signing keys.
+
+**WHY the scopes:** a token can only carry scopes from this list, and a route can only be opened for
+them. With an empty list no token can be created (a boot warning says so).
+
+### 2. Open the routes a token may call
+
+```typescript
+@ApiTokenScopes('upload')
+@Roles(RoleEnum.S_USER)
+@Post('documents')
+```
+
+**WHY explicitly:** tokens are denied on every route without `@ApiTokenScopes()`, public ones
+included. Open only what a machine needs; never the routes that change credentials, email, roles or
+memberships.
+
+### 3. Add management endpoints
+
+The core ships the service, the project owns the routes (same split as tenant members):
+
+```typescript
+@Controller('api-tokens')
+@Roles(RoleEnum.S_USER)
+export class ApiTokenController {
+  constructor(private readonly apiTokens: CoreApiTokenService) {}
+
+  @Post('tenant') // X-Tenant-Id header selects the tenant
+  createTenantToken(@CurrentTenant() tenantId: string, @Body() input: any, @CurrentUser() user: any) {
+    return this.apiTokens.createTenantToken(tenantId, input, user);
+  }
+
+  @Post('mine')
+  createUserToken(@Body() input: any, @CurrentUser() user: any) {
+    return this.apiTokens.createUserToken(input, user);
+  }
+  // find…/update…/revoke…/delete… analogously
+}
+```
+
+**WHY no rights logic here:** the service checks who may act (owner, `manageRole`, platform admin)
+and refuses token-authenticated callers. Forward `@CurrentUser()` unchanged.
+
+**WHY `@HttpCode(200)` on revoke routes:** Nest answers a `POST` with 201 by default.
+
+### 4. Clean up with your own entities
+
+```typescript
+await this.apiTokenService.deleteAllForTenant(tenantId); // when deleting a tenant
+await this.apiTokenService.deleteAllForUser(userId); // when deleting a user
+await this.apiTokenService.revokeAllForUser(userId); // after an account compromise
+```
+
+**WHY:** the core has no tenant model to hook into, so nothing calls these for you.
+
+- **For TENANT tokens `deleteAllForTenant()` is what ends access.** A tenant token belongs to the
+  tenant, not to a person: removing members does not touch it (that is the point — it survives staff
+  changes), and the core cannot see a tenant being deleted. Until you call it (or `revokeTenantToken()`),
+  a deleted or off-boarded tenant's tokens keep authenticating with the lowest tenant role.
+- **For USER tokens** access already ends when the user or the membership disappears; the call only
+  removes the rows.
+
+### 5. Optional: bind tokens to project data
+
+Extend the model and register it:
+
+```typescript
+@Schema({ timestamps: true })
+export class ApiToken extends CoreApiTokenModel {
+  @UnifiedField({ isOptional: true, mongoose: { type: String } })
+  exportConfigId: string = undefined;
+}
+
+CoreModule.forRoot(envConfig, { apiToken: { model: ApiToken } });
+```
+
+Extra fields of a create/update input are stored as given (protected fields excepted). Read them from
+`getApiTokenContext(user).tokenId` + your own lookup.
+
+## Verification Checklist
+
+- [ ] Build succeeds (`pnpm run build`), tests pass (`pnpm test`)
+- [ ] A created token's plaintext appears in the create response only — never in a list
+- [ ] `GET` on a route WITHOUT `@ApiTokenScopes()` with a token → 403 (also for a public route)
+- [ ] A revoked token → 401 on every route
+- [ ] A tenant token with a foreign `X-Tenant-Id` → 403
+- [ ] A user token of an admin cannot call an ADMIN route
+- [ ] Production config sets `apiTokens.encryptionKey` (or `SECRETS_ENCRYPTION_KEY`)
+
+## Common Mistakes
+
+| Mistake                                                   | Symptom                          | Fix                                                                   |
+| --------------------------------------------------------- | -------------------------------- | --------------------------------------------------------------------- |
+| Route not opened                                          | Token gets 403 everywhere        | `@ApiTokenScopes('<scope>')` on method or class                       |
+| Scope missing from `apiTokens.scopes`                     | 400 "Unknown scope(s)" on create | Add it to the vocabulary                                              |
+| `manageRole` not a tenant role / hierarchy with one level | Boot error                       | Declare a tenant role; keep a role below it, or `tenantTokens: false` |
+| No encryption key in production                           | Boot error                       | Set `apiTokens.encryptionKey`                                         |
+| Shipping the token to a browser for an embedded page      | Long-lived credential exposed    | Mint a signed assertion server-side (README → "Signed assertions")    |
+| Expecting a token on a GraphQL subscription               | 401 / anonymous                  | Tokens are HTTP-only                                                  |

package/src/core/modules/api-token/README.md

@@ -0,0 +1,212 @@
+# API Tokens
+
+Bearer credentials for machine clients, scripts and embedded pages that cannot carry a session cookie
+(an iframe inside a third-party application gets no `SameSite=Lax` cookie). Opt-in via `apiTokens`;
+without it nothing changes.
+
+|                     | USER token                                                                         | TENANT token                                            |
+| ------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------- |
+| Belongs to          | one user                                                                           | one tenant — survives staff changes                     |
+| Managed by          | its owner                                                                          | members holding `apiTokens.manageRole`, platform admins |
+| Acts with           | its user's **current** rights, **without global roles** (ADMIN, `globalOnlyRoles`) | the **lowest** tenant role, never a global role         |
+| Tenants             | the user's active memberships — optionally restricted to ONE                       | its own tenant only                                     |
+| Optional limits     | scopes, one tenant, `maxTenantRole`, expiry                                        | scopes, expiry                                          |
+| Needs multi-tenancy | no                                                                                 | yes                                                     |
+
+Both kinds are **denied on every route** that does not declare `@ApiTokenScopes(...)`, public
+routes included. Tokens never manage tokens.
+
+## Configuration
+
+```typescript
+// config.env.ts
+apiTokens: {
+  scopes: ['upload', 'read', 'export'],   // the vocabulary routes and tokens use
+  encryptionKey: process.env.API_TOKEN_ENCRYPTION_KEY, // required in production/staging
+  // prefix: 'ltt',                       // tokens read ltt_…, assertions ltts_…
+  // manageRole: 'owner',                 // default: highest role of multiTenancy.roleHierarchy
+  // maxAssertionLifetimeSeconds: 900,
+  // rateLimit: { max: 600, windowSeconds: 60 },   // per token; false switches it off
+  // userTokens: true,
+  // tenantTokens: true,                  // only takes effect with multiTenancy
+}
+```
+
+`true` / `{}` enable with defaults, `{ enabled: false }` pre-configures. Full reference: `IApiTokens`
+in `server-options.interface.ts`. The boot fails on an invalid prefix or scope, on a `manageRole` that
+is not a declared tenant role, on a hierarchy in which the lowest role (a tenant token's role) reaches
+the manage role, and in production/staging without an encryption key.
+
+## Opening a route
+
+```typescript
+@ApiTokenScopes('upload')              // any ONE of the listed scopes; method replaces class
+@Roles(RoleEnum.S_USER)
+@Post('documents')
+async upload(@CurrentUser() caller: any) {
+  const token = getApiTokenContext(caller); // undefined for a session / JWT
+}
+```
+
+What an opened route means per kind:
+
+- **TENANT token** — `S_EVERYONE` / `S_USER` / `S_VERIFIED` count as satisfied (the decorator is the
+  explicit permission for a machine); tenant roles resolve against the LOWEST hierarchy role; global
+  roles never match; `S_NO_ONE` refuses, and so does a route guarded ONLY by `S_SELF` / `S_CREATOR` —
+  those compare a person with a record, and a tenant token is no person. `X-Tenant-Id` is optional — it may only name the token's own
+  tenant. `@SkipTenantCheck()` does not unbind it.
+- **USER token** — the ordinary checks run as its user. A tenant-restricted token is bound to that
+  tenant (a foreign header refuses, `@SkipTenantCheck()` does not unbind it); `maxTenantRole` caps the
+  membership role. Losing a membership removes the token's access at once — rights are read per
+  request, never copied into the token.
+
+`request.user`:
+
+- TENANT token: `{ id: <token id>, name, scopes, tenantId, roles: [], hasRole: () => false }`
+- USER token: the user document (secrets never loaded, global roles removed) with `id` / `hasRole()`
+
+`getApiTokenContext(user)` → `{ kind, tokenId, publicId, name, scopes, tenantId?, userId?, maxTenantRole?, assertion? }`
+works for both. It is recognised by a module-private symbol, so a document carrying the same fields is
+never mistaken for a token. `createdBy` / `updatedBy` written by a TENANT token hold the token id.
+
+## Using a token
+
+```http
+GET /documents
+Authorization: Bearer ltt_5f3c0a9e2b41d7c86e0f1a2b_9b1e…      # or:  x-api-key: ltt_…
+X-Tenant-Id: <tenant>                                          # optional for tenant tokens
+```
+
+Token: `<prefix>_<publicId: 24 hex>_<secret: 64 hex>` (32 random bytes). Shown **once** at creation;
+stored only as SHA-256 of the secret and compared in constant time.
+
+| Situation                                                                                                                                         | Status                                            |
+| ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| Unknown, revoked, expired, tampered token or assertion; owner deleted (user tokens); two different credentials in `Authorization` and `x-api-key` | **401 on every route** (never silently anonymous) |
+| Route not opened, scope missing, role too low, foreign tenant                                                                                     | 403                                               |
+| Rate limit exceeded (per token, Redis-shared when configured)                                                                                     | 429 + `Retry-After`                               |
+
+## Signed assertions (embedding)
+
+An embedding application must not ship the long-lived token to a browser. It keeps the token's
+**signing key** (returned once at creation, 64 hex characters) on its server and mints a short-lived
+assertion per page load. The assertion acts with the token's scopes and limits, carries an optional
+`sub` / `claims` for the audit trail, and dies with the token (revocation takes effect immediately).
+
+```
+payload   = base64url( UTF-8 JSON { "claims"?: {...}, "exp": <unix seconds>, "nonce"?: "...", "sub"?: "...", "tid": "<publicId>" } )
+signature = base64url( HMAC-SHA256( key  = UTF-8 bytes of the signing key as issued,
+                                    data = ASCII bytes of the payload string ) )
+assertion = "<prefix>s_" + payload + "." + signature          # base64url WITHOUT padding
+```
+
+`publicId` is the middle part of the token. `exp` may lie at most `maxAssertionLifetimeSeconds`
+(default 900) in the future; 30 s of clock skew are tolerated on both edges. The server verifies the
+signature over the payload string as received — key order and whitespace do not matter. `nonce` is
+recorded, not enforced as single-use: an embedded page makes many requests with one assertion.
+
+Node:
+
+```typescript
+import { signApiTokenAssertion } from '@lenne.tech/nest-server';
+
+const assertion = signApiTokenAssertion({ publicId, signingKey, expiresInSeconds: 300, subject: 'b7user' });
+```
+
+C#:
+
+```csharp
+using System.Security.Cryptography;
+using System.Text;
+using System.Text.Json;
+
+static string B64Url(byte[] b) => Convert.ToBase64String(b).TrimEnd('=').Replace('+', '-').Replace('/', '_');
+
+var json = JsonSerializer.Serialize(new Dictionary<string, object> {
+    ["exp"] = DateTimeOffset.UtcNow.AddMinutes(5).ToUnixTimeSeconds(),
+    ["sub"] = "b7user",
+    ["tid"] = publicId,
+});
+var payload = B64Url(Encoding.UTF8.GetBytes(json));
+using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(signingKey));
+var assertion = $"ltts_{payload}.{B64Url(hmac.ComputeHash(Encoding.ASCII.GetBytes(payload)))}";
+```
+
+PowerShell (5.1 and 7):
+
+```powershell
+function ConvertTo-B64Url([byte[]]$b) { [Convert]::ToBase64String($b).TrimEnd('=').Replace('+','-').Replace('/','_') }
+$json = @{ exp = [DateTimeOffset]::UtcNow.AddMinutes(5).ToUnixTimeSeconds(); sub = 'b7user'; tid = $publicId } | ConvertTo-Json -Compress
+$payload = ConvertTo-B64Url ([Text.Encoding]::UTF8.GetBytes($json))
+$hmac = New-Object System.Security.Cryptography.HMACSHA256 (,[Text.Encoding]::UTF8.GetBytes($signingKey))
+$assertion = "ltts_$payload." + (ConvertTo-B64Url ($hmac.ComputeHash([Text.Encoding]::ASCII.GetBytes($payload))))
+```
+
+The signing key is stored AES-256-GCM encrypted (`apiTokens.encryptionKey`, fallback
+`SECRETS_ENCRYPTION_KEY`). Rotating that key invalidates the signing keys — not the tokens — of all
+existing tokens.
+
+## Management — `CoreApiTokenService`
+
+Every method takes the acting user and checks the right itself; a project controller only forwards
+`@CurrentUser()` / `@CurrentTenant()`. See `INTEGRATION-CHECKLIST.md` for a controller.
+
+| Method                                                                                | Who                                                                              |
+| ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `createUserToken(input, currentUser)` → `{ apiToken, token, signingKey }`             | the user (for themselves)                                                        |
+| `findUserTokens` / `updateUserToken` / `revokeUserToken` / `deleteUserToken`          | the owner                                                                        |
+| `createTenantToken(tenantId, input, currentUser)` → `{ apiToken, token, signingKey }` | `manageRole` in the tenant, platform admin                                       |
+| `findTenantTokens` / `updateTenantToken` / `revokeTenantToken` / `deleteTenantToken`  | same                                                                             |
+| `deleteAllForTenant(tenantId)`                                                        | system — call when deleting a tenant (also removes user tokens restricted to it) |
+| `revokeAllForUser(userId)` / `deleteAllForUser(userId)`                               | system — account compromise / user deletion                                      |
+
+Inputs: `name` (required), `description`, `scopes` (subset of the vocabulary; a user token without
+scopes gets the whole vocabulary), `expiresAt` (future, or `null`), for user tokens `tenantId` (an
+active membership of the owner) and `maxTenantRole` (a hierarchy role). Any other field is stored as
+given — that is how a project binds a token to its own data (after extending the model) — except the
+protected ones (`kind`, `tenant`, `user`, `publicId`, hashes, audit fields, `revokedAt`, `lastUsedAt`).
+Returned objects never contain the hash or the signing key.
+
+## Better-Auth
+
+Runs alongside Better-Auth without changing it and also works without it (legacy mode):
+`CoreBetterAuthMiddleware` leaves prefixed credentials alone, user tokens resolve the same `users`
+document Better-Auth does, and `x-api-key` follows the header convention of Better-Auth's API-key
+plugin. The official `@better-auth/api-key` plugin is deliberately not used: organisation-owned keys
+there are authorised through Better-Auth's organization plugin rather than `CoreTenant`, its request
+integration turns a key into a full session of its user on every route, it requires Better-Auth, and
+it has no signed assertions.
+
+## Security notes for projects
+
+- **Routes outside the Nest guards do not see `@ApiTokenScopes()`.** Anything mounted with `app.use()`
+  (an Express router, a static handler) runs after `CoreApiTokenMiddleware` but before no guard, so
+  `req.user` may be a token there. Treat `getApiTokenContext(req.user)` as "not a person" in such code.
+  The framework's own case — the MCP OAuth consent step — refuses token requests, because a consent
+  would mint an access token with the user's FULL rights.
+- **A tenant token is not a user.** `@CurrentUser()` then has no `email`, no `verified`; code that
+  mails or notifies "the current user" must check `getApiTokenContext()` first. Field-level
+  `@Restricted(S_VERIFIED)` stays hidden from tenant tokens (fail-closed).
+- **Open routes deliberately.** Never release routes that change credentials, e-mail, roles,
+  memberships or tokens. The management service refuses tokens anyway.
+- **Password resets.** A reset that ends the user's sessions ends their user tokens too: the legacy
+  reset (`CoreUserService.resetPassword()`) always, the IAM reset while
+  `betterAuth.emailAndPassword.revokeSessionsOnPasswordReset` is on. With it off — and on a password
+  CHANGE — user tokens survive, like personal access tokens elsewhere; after a suspected compromise
+  call `revokeAllForUser(userId)`. Tenant tokens are never touched by a user's reset.
+- **Deleting a tenant.** Call `deleteAllForTenant(tenantId)` — nothing does it for you, and until you
+  do, the tenant's tokens keep authenticating (the core has no tenant model to notice the deletion).
+- **Banned users.** If you add Better-Auth's admin plugin, override `loadTokenUser()` so a banned
+  user's tokens are refused as well — the framework does not know that flag.
+- **Brute force.** Failed attempts are not limited per IP (guessing 256 bits is not the risk); add an
+  IP limit in front of an exposed API if you want one.
+- **Secret scanning:** the fixed shape `<prefix>_<24 hex>_<64 hex>` can be registered as a custom
+  pattern in your repository's secret scanning.
+
+## Limitations
+
+- HTTP only: GraphQL over WebSocket (subscriptions) does not accept API tokens.
+- Better-Auth's native `/iam/*` handlers do not recognise tokens — a token cannot sign in, change a
+  password or read a session.
+- A 401/429 from the middleware on `/graphql` has the REST error shape, not the GraphQL one.
+- `lastUsedAt` is accurate to one minute per replica.