Add Service Authentication with OAuth2 Client Credentials Flow and User Impersonation

[dipesh-rumsan]

This feature enables external services (such as SMS Bridge or Payment Gateway) to authenticate with the platform using OAuth2 Client Credentials Flow. Services can register as clients and receive a unique client ID and secret. When authenticating, they exchange these credentials for a Service JWT containing the role "INTERNAL_SERVICE".

The key capability is user impersonation. Once authenticated, a service can make API calls on behalf of any user by including an X-Impersonate-Id header with the user's ID or UUID. The platform validates that the service is authorized to impersonate, optionally restricts which user roles can be impersonated, and then loads the full user context (roles) into the request. This allows services to perform actions as if they were the user, while maintaining a clear audit trail of which service initiated the request.

A hybrid authentication guard dynamically detects whether an incoming request is from a regular user or a service by inspecting the JWT payload. This means the same API endpoints can serve both users and services without requiring separate routes. When a service impersonates a user, the request includes metadata indicating it's a service request and which service is acting, enabling downstream logic to distinguish between direct user actions and service-initiated ones.

[Copilot]

Pull request overview

This pull request adds comprehensive authentication capabilities including OAuth2 Client Credentials Flow for service authentication, user impersonation, username/password authentication, and rate limiting with account lockout features.

Changes:

• Added ServiceClient and LoginAttempt database models for service authentication and rate limiting
• Implemented password-based authentication with bcrypt hashing, strength validation, and account lockout
• Added USERNAME service type with case-insensitive lookups
• Implemented HybridJwtGuard for detecting user vs. service requests and handling impersonation
• Added LocalStrategy for passport-local authentication
• Created rate limiting service with IP and identifier-based limits

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
package.json	Added bcrypt 6.0.0 and passport-local dependencies
prisma/schema.prisma	Added ServiceClient model, LoginAttempt model, USERNAME enum, and case-insensitive username fields
prisma/migrations/*.sql	Database migrations for new tables and fields
libs/user/src/lib/utils/password.utils.ts	Password hashing, verification, and strength validation utilities
libs/user/src/lib/utils/service.utils.ts	Updated service type detection to support USERNAME
libs/user/src/lib/users/users.service.ts	Added username support with case-insensitive lookups
libs/user/src/lib/signups/signups.service.ts	Added password signup flow with validation
libs/user/src/lib/auths/auths.service.ts	Implemented password auth, service auth, and password management
libs/user/src/lib/auths/strategy/local.strategy.ts	LocalStrategy for password authentication
libs/user/src/lib/auths/guard/hybrid-jwt.guard.ts	Guard for user/service detection and impersonation
libs/user/src/lib/auths/services/rate-limit.service.ts	Rate limiting for login attempts
libs/extensions/src/dtos/authDto/*.dto.ts	DTOs for password and service authentication
libs/extensions/src/decorators/validators/*.ts	Custom validators for username and phone

Comments suppressed due to low confidence (2)

libs/user/src/lib/auths/auths.service.ts:383

• The value assigned to failReason here is unused.

          failReason = 'Account is locked';

libs/user/src/lib/auths/auths.service.ts:417

• The value assigned to failReason here is unused.

        failReason = 'Account is locked';

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

@dipesh-rumsan I've opened a new pull request, #49, to work on those changes. Once the pull request is ready, I'll request review from you.