@flusys/nestjs-auth 9.1.1 → 9.2.0

package/README.md

@@ -51,6 +51,15 @@ AuthModule.forRoot({
 
 Browser logins get the refresh token as an HttpOnly cookie lasting `refreshTokenExpiration`. Sending `rememberMe: false` in the body of `POST /auth/login` or `POST /auth/select` makes it a session cookie instead (dropped when the browser closes).
 
+### Tokens and sessions
+
+- Access and refresh tokens are HS256 JWTs carrying `type: 'access' | 'refresh'`. `JwtStrategy` accepts only `access` tokens and `POST /auth/refresh` only `refresh` tokens, so one can never stand in for the other, even when both share a secret (outside production `refreshTokenSecret` falls back to `jwtSecret`).
+- Refresh tokens are stateless and are not rotated: `POST /auth/refresh` returns a new access token only. They end at `refreshTokenExpiration` or when the user's sessions are revoked: logout, deactivation, a password reset and a social sign-in that claims an unverified account all record a revocation time, and every token issued before that moment is refused. Tokens carry an `iatMs` claim (issue time in milliseconds), so a token issued earlier in the same second as the revocation is refused while one issued right after it (signing straight back in) is kept; a token from before `iatMs` existed is judged by `iat` and, issued in the revocation's second, is refused. The revocation marker (`auth:revoked:<userId>`, epoch ms, kept for `refreshTokenExpiration`) is read and written past the in-process cache layer and never moves backwards. A company-selection session started before a revocation cannot complete `POST /auth/select` either.
+- Password reset and email verification tokens are 32 random bytes, sent raw and stored only as their SHA-256 hash. A reset token lasts one hour and is single-use even under concurrent requests (it is claimed with one conditional update before the password changes); a verification link lasts 24 hours.
+- Login answers an unknown email, a wrong password and a password-less (social-only) account with the same `auth.login.invalid.credentials`, running a bcrypt comparison in every case. A pending registration is only reported to someone who knows its password. `forgot-password` answers the same whether or not the email exists, a failing email provider included. Brute force is limited by the `@Throttle` limits on each route; there is no per-account lockout.
+- With the company feature on, `POST /auth/register` with an email that already has an account joins or creates another company for that account only when the request carries the account's current password (otherwise it is refused like any taken email), the account is active, and, with email verification on, its email is verified.
+- `POST /administration/users/profile` only ever edits the caller's own profile (an `id` naming anyone else is refused with `auth.profile.access.denied`); changing your password there always needs `oldPassword`, and changing your email clears `emailVerified`. Administrators edit other users through `POST /administration/users/update`.
+
 #### Mode 2: Multi-Tenant
 
 In multi-tenant mode you provide:
@@ -272,7 +281,7 @@ AuthModule.forRootAsync({ ..., providers: [userEnricherProvider] });
 
 Google, Facebook, LinkedIn and Microsoft are built in. Nothing is enabled until an
 administrator saves credentials, and no flag gates the feature: the
-`social_auth_config` and `user_social_account` tables are always registered, and
+`social_auth_config` table is always registered, and
 `SocialAuthController` / `SocialAuthConfigController` are always mounted.
 
 ### Credentials
@@ -303,23 +312,36 @@ The `state` is a single-use, cache-backed token that also records which provider
 and redirect URI the sign-in started with — providers echo back nothing but
 `code` and `state`, so the callback carries no provider of its own. Redeeming a
 state deletes it, and a redirect URI that does not match the one the sign-in
-started with is rejected.
+started with is rejected. The state is redeemed with an atomic `take`, so it (and the
+`code` that comes with it) cannot be replayed on another instance. The state is not bound to the browser that started the
+sign-in, so the client must keep the `state` it got from `authorize` and refuse a
+callback whose `state` differs before posting it (login CSRF).
 
 The callback returns exactly what `POST /auth/login` returns, company selection
 included, because both routes finish through `AuthenticationService.issueLoginForUser`.
 
 ### How a user is matched
 
-1. The provider's own account id, via `user_social_account` — survives an email change at the provider.
-2. Otherwise the email, so an existing password account is adopted rather than duplicated.
-3. Otherwise a new account with no password.
+1. The email, so an existing password account is adopted rather than duplicated.
+2. Otherwise a new account with no password.
 
-Steps 2 and 3 require the provider to have **verified** the address. Matching on an
+Both require the provider to have **verified** the address. Matching on an
 unverified email would let anyone who registers someone else's address at the
 provider walk into their FLUSYS account, so an unverified profile is rejected.
-An account already linked at step 1 is unaffected.
 
-Step 3 — creating an account — is refused in two cases, each with its own message key:
+Adopting an account whose own email was never verified in FLUSYS drops its
+password and ends its sessions: whoever chose that password never proved they own
+the address, so an account pre-registered with someone else's email cannot be kept
+by its registrant once the real owner signs in. The owner can set a password again
+through `forgot-password`.
+
+Microsoft's `mail` claim is set by the directory's administrator, so it only counts
+as verified when sign-in is pinned to one directory (`extraConfig.tenantId` set to
+your tenant id or domain) or to personal accounts (`consumers`). With the default
+`common` (or `organizations`) authority every Microsoft profile is treated as
+unverified and refused - set `tenantId` to use Microsoft sign-in.
+
+Step 2 — creating an account — is refused in two cases, each with its own message key:
 
 | Condition                                   | Result                                       |
 | ------------------------------------------- | -------------------------------------------- |
@@ -335,6 +357,16 @@ then works. Signing **in** is never affected by either — only account creation
 A cache instance is required: `AuthModule` imports `CacheModule`, so this is
 satisfied by default.
 
+### Caching
+
+`UserService`, `CompanyService`, `BranchService` and `SocialAuthConfigService` cache `findById` / `get-all` through `ApiService` version stamps (see `nestjs-shared` section 7). Notes specific to this package:
+
+- Every write outside `ApiService`'s own CRUD moves the stamp of what it wrote, after commit: login (`lastLoginAt`), registration (user, plus company / branch / grants when it creates them), password change and reset, email verification, profile and status updates, social sign-in (new or claimed account), grant assign / revoke (`UserPermissionService`), and the grants removed by a company or branch delete.
+- The user list depends on `appuser` and `user_company_permission` (the company-scoped list reads each user's grant). A list filtered by `actionCode` reads IAM grants, whose writes never move these stamps, so that read is not cached.
+- `SocialAuthConfigService` returns `hasClientSecret` instead of the secret, so the client secret is never cached or sent.
+- Login, token refresh and `JwtStrategy` read user, company and grant state from the database, never from the cache.
+- One-time state never goes through the in-process layer: company-selection sessions (keyed by tenant in multi-tenant mode, consumed with `take`), social sign-in state (`take`) and revocation markers. Revocation markers are keyed by user id only, so in multi-tenant mode a revocation in one tenant also ends the sessions of a user with the same id in another tenant (only when tenant databases share user ids).
+
 ## 6. Branch Hierarchy
 
 Branches nest through `parentId`. A parent must be in the same company and cannot create a cycle, and deleting a branch also deletes every branch under it. `BranchService` exposes the hierarchy, each lookup taking two queries whatever the depth:
@@ -349,7 +381,7 @@ With the company feature on, the module also provides and exports `BRANCH_HIERAR
 
 ## 7. Deactivating a User
 
-With the company feature off, `UserService.updateStatus` sets `AppUser.isActive`, which blocks login, token refresh and every request. With it on, it deactivates the user in the admin's current company only, by setting `isActive` on that company grant (`UserCompanyPermission`, `permissionType: company`). Login, company select, select/switch, token refresh, `get-my-companies` / `get-my-company-branches` and `COMPANY_ACCESS_RESOLVER` all skip an inactive company grant, and deactivating (in either mode) also ends every session of the user at once, the same way logout does (`revokeUserSessions`, checked on refresh and by `JwtStrategy` on every request). The user can log straight back in to the companies they are still active in. A user with company grants never gets a company-less login (such a token is not filtered by company): login is refused when they are deactivated in every company (`auth.login.account.deactivated`) or none of their companies is active (`auth.company.not.found`), and a company-less refresh token is not renewed once the user has company grants. Branch grants carry no status of their own.
+With the company feature off, `UserService.updateStatus` sets `AppUser.isActive`, which blocks login, token refresh and every request. With it on, it deactivates the user in the admin's current company only, by setting `isActive` on that company grant (`UserCompanyPermission`, `permissionType: company`). Login, company select, select/switch, token refresh, `get-my-companies` / `get-my-company-branches` and `COMPANY_ACCESS_RESOLVER` all skip an inactive company grant, and deactivating (in either mode) also ends every session of the user at once, the same way logout does (`revokeUserSessions`, checked on refresh and by `JwtStrategy` on every request). The user can log straight back in to the companies they are still active in. A user with company grants never gets a company-less login (such a token is not filtered by company): login is refused when they are deactivated in every company (`auth.login.account.deactivated`) or none of their companies is active (`auth.company.not.found`), and a company-less refresh token is not renewed once the user has company grants. Branch grants carry no status of their own. With the company feature on, a caller whose token has no company cannot change a status (`auth.company.required`) and sees no users in `get-all` / `lookup`, matching the company-less scoping of `nestjs-shared`; the company-select routes (`get-my-companies`, `get-my-company-branches`, `switch-company`) work from the token's user id alone, so such a caller can still pick a company.
 
 ## License
 

package/controllers/branch.controller.d.ts

@@ -4,6 +4,7 @@ declare const BranchController_base: abstract new (service: BranchService) => {
     readonly enabledEndpoints: import("@flusys/nestjs-shared").ApiEndpoint[] | "all";
     service: BranchService;
     isEnabled(endpoint: import("@flusys/nestjs-shared").ApiEndpoint): boolean;
+    assertEnabled(endpoint: import("@flusys/nestjs-shared").ApiEndpoint): void;
     insert(addDto: CreateCompanyBranchDto, user: import("@flusys/nestjs-shared").ILoggedUserInfo | null): Promise<import("@flusys/nestjs-shared").SingleResponseDto<CompanyBranchResponseDto>>;
     insertMany(addDto: CreateCompanyBranchDto[], user: import("@flusys/nestjs-shared").ILoggedUserInfo | null): Promise<import("@flusys/nestjs-shared").BulkResponseDto<CompanyBranchResponseDto>>;
     getById(id: string, body: import("@flusys/nestjs-shared").GetByIdBodyDto, user: import("@flusys/nestjs-shared").ILoggedUserInfo | null): Promise<import("@flusys/nestjs-shared").SingleResponseDto<CompanyBranchResponseDto>>;

package/controllers/company.controller.d.ts

@@ -4,6 +4,7 @@ declare const CompanyController_base: abstract new (service: CompanyService) =>
     readonly enabledEndpoints: import("@flusys/nestjs-shared").ApiEndpoint[] | "all";
     service: CompanyService;
     isEnabled(endpoint: import("@flusys/nestjs-shared").ApiEndpoint): boolean;
+    assertEnabled(endpoint: import("@flusys/nestjs-shared").ApiEndpoint): void;
     insert(addDto: CreateCompanyDto, user: import("@flusys/nestjs-shared").ILoggedUserInfo | null): Promise<import("@flusys/nestjs-shared").SingleResponseDto<CompanyResponseDto>>;
     insertMany(addDto: CreateCompanyDto[], user: import("@flusys/nestjs-shared").ILoggedUserInfo | null): Promise<import("@flusys/nestjs-shared").BulkResponseDto<CompanyResponseDto>>;
     getById(id: string, body: import("@flusys/nestjs-shared").GetByIdBodyDto, user: import("@flusys/nestjs-shared").ILoggedUserInfo | null): Promise<import("@flusys/nestjs-shared").SingleResponseDto<CompanyResponseDto>>;

package/controllers/social-auth-config.controller.d.ts

@@ -4,6 +4,7 @@ declare const SocialAuthConfigController_base: abstract new (service: SocialAuth
     readonly enabledEndpoints: import("@flusys/nestjs-shared").ApiEndpoint[] | "all";
     service: SocialAuthConfigService;
     isEnabled(endpoint: import("@flusys/nestjs-shared").ApiEndpoint): boolean;
+    assertEnabled(endpoint: import("@flusys/nestjs-shared").ApiEndpoint): void;
     insert(addDto: CreateSocialAuthConfigDto, user: import("@flusys/nestjs-shared").ILoggedUserInfo | null): Promise<import("@flusys/nestjs-shared").SingleResponseDto<SocialAuthConfigResponseDto>>;
     insertMany(addDto: CreateSocialAuthConfigDto[], user: import("@flusys/nestjs-shared").ILoggedUserInfo | null): Promise<import("@flusys/nestjs-shared").BulkResponseDto<SocialAuthConfigResponseDto>>;
     getById(id: string, body: import("@flusys/nestjs-shared").GetByIdBodyDto, user: import("@flusys/nestjs-shared").ILoggedUserInfo | null): Promise<import("@flusys/nestjs-shared").SingleResponseDto<SocialAuthConfigResponseDto>>;

package/controllers/user.controller.d.ts

@@ -7,6 +7,7 @@ declare const UserController_base: abstract new (service: UserService) => {
     readonly enabledEndpoints: import("@flusys/nestjs-shared").ApiEndpoint[] | "all";
     service: UserService;
     isEnabled(endpoint: import("@flusys/nestjs-shared").ApiEndpoint): boolean;
+    assertEnabled(endpoint: import("@flusys/nestjs-shared").ApiEndpoint): void;
     insert(addDto: CreateUserDto, user: ILoggedUserInfo | null): Promise<import("@flusys/nestjs-shared").SingleResponseDto<UserResponseDto>>;
     insertMany(addDto: CreateUserDto[], user: ILoggedUserInfo | null): Promise<import("@flusys/nestjs-shared").BulkResponseDto<UserResponseDto>>;
     getById(id: string, body: import("@flusys/nestjs-shared").GetByIdBodyDto, user: ILoggedUserInfo | null): Promise<import("@flusys/nestjs-shared").SingleResponseDto<UserResponseDto>>;

package/fesm/118.js

@@ -752,7 +752,7 @@ _ts_decorate([
         description: 'Whether a client secret is currently stored for this provider'
     }),
     (0,class_transformer__rspack_import_2.Expose)(),
-    (0,class_transformer__rspack_import_2.Transform)(({ obj })=>!!obj.clientSecret),
+    (0,class_transformer__rspack_import_2.Transform)(({ obj })=>obj.hasClientSecret ?? !!obj.clientSecret),
     _ts_metadata("design:type", Boolean)
 ], SocialAuthConfigResponseDto.prototype, "hasClientSecret", void 0);
 _ts_decorate([

package/fesm/120.js

@@ -1474,7 +1474,6 @@ user_controller_ts_decorate([
     (0,common_.Post)('profile-sections'),
     (0,common_.UseGuards)(guards_.JwtAuthGuard),
     (0,swagger_.ApiBearerAuth)(),
-    (0,__rspack_external__flusys_nestjs_shared_decorators_c129b601.RequirePermission)(classes_.USER_PERMISSIONS.READ),
     (0,swagger_.ApiOperation)({
         summary: 'Get profile section definitions',
         description: 'Returns available profile sections for multi-step profile (if enricher configured).'
@@ -2137,6 +2136,7 @@ class ClearToken {
 ClearToken = _ts_decorate([
     (0,_nestjs_common__rspack_import_1.Injectable)(),
     _ts_param(0, (0,_nestjs_common__rspack_import_1.Optional)()),
+    _ts_param(0, (0,_nestjs_common__rspack_import_1.Inject)(_services_auth_config_service_js__rspack_import_3/* .AuthConfigService */.W)),
     _ts_metadata("design:type", Function),
     _ts_metadata("design:paramtypes", [
         typeof _services_auth_config_service_js__rspack_import_3/* .AuthConfigService */.W === "undefined" ? Object : _services_auth_config_service_js__rspack_import_3/* .AuthConfigService */.W