create-forgeon 0.3.24 → 0.3.26

package/templates/module-presets/accounts/packages/accounts-api/src/auth.store.ts

@@ -19,10 +19,22 @@ export type RefreshTokenRecord = {
   createdAt: Date;
 };
 
+export type PendingOperationRecord = {
+  id: string;
+  userId: string;
+  type: string;
+  tokenHash: string;
+  metadata: JsonObject | null;
+  expiresAt: Date;
+  consumedAt: Date | null;
+  createdAt: Date;
+};
+
 export interface CreatePasswordAccountInput {
   email: string;
   passwordHash: string;
   status: string;
+  emailVerifiedAt: Date | null;
   userData: JsonObject | null;
   profile: {
     name: string | null;
@@ -45,6 +57,7 @@ export class AuthStore {
       const user = await tx.user.create({
         data: {
           status: input.status,
+          emailVerifiedAt: input.emailVerifiedAt,
           data: toPrismaJsonInput(input.userData),
           profile: {
             create: {
@@ -143,6 +156,79 @@ export class AuthStore {
     });
   }
 
+  async markEmailVerified(userId: string, verifiedAt: Date): Promise<void> {
+    await this.prisma.user.update({
+      where: { id: userId },
+      data: {
+        status: 'active',
+        emailVerifiedAt: verifiedAt,
+      },
+    });
+  }
+
+  async updatePrimaryEmail(userId: string, email: string, verifiedAt: Date): Promise<void> {
+    await this.prisma.$transaction([
+      this.prisma.authIdentity.updateMany({
+        where: { userId, provider: 'email' },
+        data: { providerId: email },
+      }),
+      this.prisma.user.update({
+        where: { id: userId },
+        data: {
+          emailVerifiedAt: verifiedAt,
+        },
+      }),
+    ]);
+  }
+
+  async createPendingOperation(input: {
+    id: string;
+    userId: string;
+    type: string;
+    tokenHash: string;
+    metadata: JsonObject | null;
+    expiresAt: Date;
+  }): Promise<void> {
+    await this.prisma.authPendingOperation.create({
+      data: {
+        id: input.id,
+        userId: input.userId,
+        type: input.type,
+        tokenHash: input.tokenHash,
+        metadata: toPrismaJsonInput(input.metadata),
+        expiresAt: input.expiresAt,
+      },
+    });
+  }
+
+  async findPendingOperationById(id: string): Promise<PendingOperationRecord | null> {
+    const operation = await this.prisma.authPendingOperation.findUnique({
+      where: { id },
+    });
+
+    if (!operation) {
+      return null;
+    }
+
+    return {
+      id: operation.id,
+      userId: operation.userId,
+      type: operation.type,
+      tokenHash: operation.tokenHash,
+      metadata: operation.metadata as JsonObject | null,
+      expiresAt: operation.expiresAt,
+      consumedAt: operation.consumedAt,
+      createdAt: operation.createdAt,
+    };
+  }
+
+  async consumePendingOperation(id: string, consumedAt: Date): Promise<void> {
+    await this.prisma.authPendingOperation.updateMany({
+      where: { id, consumedAt: null },
+      data: { consumedAt },
+    });
+  }
+
   async createRefreshToken(input: {
     id: string;
     userId: string;
@@ -190,6 +276,7 @@ export class AuthStore {
   private mapPasswordAccount(user: {
     id: string;
     status: string;
+    emailVerifiedAt: Date | null;
     data: unknown;
     createdAt: Date;
     updatedAt: Date;

package/templates/module-presets/accounts/packages/accounts-api/src/forgeon-accounts.module.ts

@@ -3,23 +3,31 @@ import {
   Module,
   ModuleMetadata,
   Provider,
+  Type,
 } from '@nestjs/common';
 import { JwtModule } from '@nestjs/jwt';
 import { PassportModule } from '@nestjs/passport';
-import { ForgeonCommunicationsModule } from '@forgeon/communications';
 import { DbPrismaModule } from '@forgeon/db-prisma';
 import {
   ACCOUNTS_AUTHZ_CLAIMS_RESOLVER,
   NoopAccountsAuthzClaimsResolver,
 } from './accounts-rbac.port';
+import { JwtAuthGuard } from './access-token.guard';
 import { AuthConfigModule } from './auth-config.module';
 import { AuthController } from './auth.controller';
 import { AuthCoreService } from './auth-core.service';
+import {
+  CHANGE_PASSWORD_HANDLER,
+  DefaultChangePasswordHandler,
+  DefaultRegisterHandler,
+  REGISTER_HANDLER,
+  type ChangePasswordHandler,
+  type RegisterHandler,
+} from './auth.handlers';
 import { AuthJwtService } from './auth-jwt.service';
 import { AuthPasswordService } from './auth-password.service';
 import { AuthService } from './auth.service';
 import { AuthStore } from './auth.store';
-import { JwtAuthGuard } from './access-token.guard';
 import { JwtStrategy } from './jwt.strategy';
 import { OwnerAccessGuard } from './owner-access.guard';
 import { UsersController } from './users.controller';
@@ -30,7 +38,12 @@ import { UsersStore } from './users.store';
 export interface ForgeonAccountsModuleOptions {
   imports?: ModuleMetadata['imports'];
   providers?: Provider[];
+  controllers?: Type<unknown>[];
   users?: UsersModuleOptions;
+  handlers?: {
+    register?: Type<RegisterHandler>;
+    changePassword?: Type<ChangePasswordHandler>;
+  };
 }
 
 @Module({})
@@ -41,12 +54,11 @@ export class ForgeonAccountsModule {
       imports: [
         AuthConfigModule,
         DbPrismaModule,
-        ForgeonCommunicationsModule.register(),
         PassportModule.register({ defaultStrategy: 'jwt' }),
         JwtModule.register({}),
         ...(options.imports ?? []),
       ],
-      controllers: [AuthController, UsersController],
+      controllers: [AuthController, UsersController, ...(options.controllers ?? [])],
       providers: [
         {
           provide: USERS_MODULE_OPTIONS,
@@ -59,6 +71,16 @@ export class ForgeonAccountsModule {
         AuthStore,
         UsersStore,
         AuthCoreService,
+        DefaultRegisterHandler,
+        DefaultChangePasswordHandler,
+        {
+          provide: REGISTER_HANDLER,
+          useExisting: options.handlers?.register ?? DefaultRegisterHandler,
+        },
+        {
+          provide: CHANGE_PASSWORD_HANDLER,
+          useExisting: options.handlers?.changePassword ?? DefaultChangePasswordHandler,
+        },
         AuthJwtService,
         AuthPasswordService,
         AuthService,
@@ -71,6 +93,8 @@ export class ForgeonAccountsModule {
       exports: [
         AuthConfigModule,
         AuthCoreService,
+        REGISTER_HANDLER,
+        CHANGE_PASSWORD_HANDLER,
         AuthJwtService,
         AuthPasswordService,
         AuthService,
@@ -81,4 +105,4 @@ export class ForgeonAccountsModule {
       ],
     };
   }
-}
+}

package/templates/module-presets/accounts/packages/accounts-api/src/index.ts

@@ -5,8 +5,10 @@ export * from './auth-config.service';
 export * from './auth.controller';
 export * from './auth-core.service';
 export * from './auth-env.schema';
+export * from './auth.handlers';
 export * from './auth-jwt.service';
 export * from './auth-password.service';
+export * from './auth-pending-operations';
 export * from './auth.service';
 export * from './auth.store';
 export * from './auth.types';

package/templates/module-presets/accounts/packages/accounts-contracts/src/index.ts

@@ -5,9 +5,12 @@ export const AUTH_API_ROUTES = {
   logout: '/api/auth/logout',
   me: '/api/auth/me',
   changePassword: '/api/auth/change-password',
+  changePasswordConfirm: '/api/auth/change-password/confirm',
   verifyEmail: '/api/auth/verify-email',
   passwordResetRequest: '/api/auth/password-reset/request',
   passwordResetConfirm: '/api/auth/password-reset/confirm',
+  changeEmailRequest: '/api/auth/change-email/request',
+  changeEmailConfirm: '/api/auth/change-email/confirm',
 } as const;
 
 export const USERS_API_ROUTES = {
@@ -99,6 +102,18 @@ export interface VerifyEmailRequest {
   token: string;
 }
 
+export interface ConfirmChangePasswordRequest {
+  token: string;
+}
+
+export interface RequestChangeEmailRequest {
+  email: string;
+}
+
+export interface ConfirmChangeEmailRequest {
+  token: string;
+}
+
 export interface UpdateUserRequest {
   data?: JsonObject;
 }
@@ -116,4 +131,25 @@ export interface TokenPair {
 
 export interface AuthSessionResponse extends TokenPair {
   user: UserRecordDto;
-}
+}
+
+export interface PendingVerificationResponse {
+  status: 'pending_verification';
+  message: string;
+}
+
+export interface CompletedChangePasswordResponse {
+  status: 'completed';
+  message?: string;
+}
+
+export interface PendingConfirmationChangePasswordResponse {
+  status: 'pending_confirmation';
+  message: string;
+}
+
+export type RegisterResult = AuthSessionResponse | PendingVerificationResponse;
+export type VerifyEmailResult = AuthSessionResponse;
+export type ChangePasswordResult =
+  | CompletedChangePasswordResponse
+  | PendingConfirmationChangePasswordResponse;

package/templates/module-presets/accounts-communications/packages/accounts-communications/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@forgeon/accounts-communications",
+  "version": "0.1.0",
+  "private": true,
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "@forgeon/accounts-api": "workspace:*",
+    "@forgeon/accounts-contracts": "workspace:*",
+    "@forgeon/communications": "workspace:*",
+    "@nestjs/common": "^11.0.1",
+    "class-transformer": "^0.5.1",
+    "class-validator": "^0.14.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.7",
+    "typescript": "^5.7.3"
+  }
+}

package/templates/module-presets/accounts-communications/packages/accounts-communications/src/auth-communications.controller.ts

@@ -0,0 +1,69 @@
+import {
+  Body,
+  Controller,
+  Post,
+  Req,
+  UseGuards,
+} from '@nestjs/common';
+import { JwtAuthGuard } from '@forgeon/accounts-api';
+import type { AuthAccessTokenPayload } from '@forgeon/accounts-api';
+import { AuthCommunicationsService } from './auth-communications.service';
+import {
+  ConfirmChangeEmailDto,
+  ConfirmChangePasswordDto,
+  ConfirmPasswordResetDto,
+  RequestChangeEmailDto,
+  RequestPasswordResetDto,
+  VerifyEmailDto,
+} from './dto';
+
+type RequestWithUser = { user?: AuthAccessTokenPayload };
+
+@Controller('auth')
+export class AuthCommunicationsController {
+  constructor(private readonly authCommunicationsService: AuthCommunicationsService) {}
+
+  @Post('verify-email')
+  verifyEmail(@Body() body: VerifyEmailDto) {
+    return this.authCommunicationsService.verifyEmail(body.token);
+  }
+
+  @Post('password-reset/request')
+  requestPasswordReset(@Body() body: RequestPasswordResetDto) {
+    return this.authCommunicationsService.requestPasswordReset(body.email);
+  }
+
+  @Post('password-reset/confirm')
+  confirmPasswordReset(@Body() body: ConfirmPasswordResetDto) {
+    return this.authCommunicationsService.confirmPasswordReset(body.token, body.newPassword);
+  }
+
+  @Post('change-password/confirm')
+  confirmChangePassword(@Body() body: ConfirmChangePasswordDto) {
+    return this.authCommunicationsService.confirmChangePassword(body.token);
+  }
+
+  @UseGuards(JwtAuthGuard)
+  @Post('change-email/request')
+  requestChangeEmail(@Body() body: RequestChangeEmailDto, @Req() request: RequestWithUser) {
+    const user = this.getRequestUser(request);
+    return this.authCommunicationsService.requestChangeEmail(user.sub, body);
+  }
+
+  @Post('change-email/confirm')
+  confirmChangeEmail(@Body() body: ConfirmChangeEmailDto) {
+    return this.authCommunicationsService.confirmChangeEmail(body.token);
+  }
+
+  private getRequestUser(request: RequestWithUser): AuthAccessTokenPayload {
+    const user = request.user;
+    if (!user?.sub) {
+      return {
+        sub: 'unknown',
+        email: 'unknown@invalid.local',
+        type: 'access',
+      };
+    }
+    return user;
+  }
+}

package/templates/module-presets/accounts-communications/packages/accounts-communications/src/auth-communications.service.ts

@@ -0,0 +1,221 @@
+import { Injectable } from '@nestjs/common';
+import type {
+  ChangePasswordRequest,
+  ChangePasswordResult,
+  PendingVerificationResponse,
+  RegisterRequest,
+  RequestChangeEmailRequest,
+  VerifyEmailResult,
+} from '@forgeon/accounts-contracts';
+import {
+  AUTH_PENDING_OPERATION_TYPES,
+  AuthCoreService,
+  AuthPasswordService,
+} from '@forgeon/accounts-api';
+import { CommunicationsService } from '@forgeon/communications';
+
+@Injectable()
+export class AuthCommunicationsService {
+  constructor(
+    private readonly authCoreService: AuthCoreService,
+    private readonly authPasswordService: AuthPasswordService,
+    private readonly communicationsService: CommunicationsService,
+  ) {}
+
+  async registerWithPendingVerification(input: RegisterRequest): Promise<PendingVerificationResponse> {
+    const account = await this.authCoreService.createPasswordAccount(input, {
+      status: 'pending_verification',
+      emailVerifiedAt: null,
+    });
+    const operation = await this.authCoreService.issuePendingOperation({
+      userId: account.id,
+      type: AUTH_PENDING_OPERATION_TYPES.emailVerification,
+    });
+
+    await this.communicationsService.send({
+      kind: 'email_verification_code',
+      channels: ['email'],
+      recipient: { email: account.providerId },
+      payload: {
+        NAME: account.profile?.name ?? 'there',
+        TOKEN: operation.token,
+      },
+      locale: account.settings?.locale ?? undefined,
+      metadata: {
+        USER_ID: account.id,
+        SOURCE: 'accounts-communications.register',
+      },
+    });
+
+    return {
+      status: 'pending_verification',
+      message: 'Verification email sent',
+    };
+  }
+
+  async verifyEmail(token: string): Promise<VerifyEmailResult> {
+    const operation = await this.authCoreService.readPendingOperation(
+      token,
+      AUTH_PENDING_OPERATION_TYPES.emailVerification,
+    );
+    const account = await this.authCoreService.markEmailVerified(operation.userId);
+    await this.authCoreService.consumePendingOperation(operation.id);
+    await this.sendWelcomeEmailPlaceholder(account.providerId);
+    return this.authCoreService.issueSessionForAccount(account);
+  }
+
+  async requestPasswordReset(email: string) {
+    const account = await this.authCoreService.findPasswordAccountByEmail(email);
+    if (account) {
+      const operation = await this.authCoreService.issuePendingOperation({
+        userId: account.id,
+        type: AUTH_PENDING_OPERATION_TYPES.passwordReset,
+      });
+
+      await this.communicationsService.send({
+        kind: 'password_reset',
+        channels: ['email'],
+        recipient: { email: account.providerId },
+        payload: {
+          NAME: account.profile?.name ?? 'there',
+          TOKEN: operation.token,
+        },
+        locale: account.settings?.locale ?? undefined,
+        metadata: {
+          USER_ID: account.id,
+          SOURCE: 'accounts-communications.password-reset',
+        },
+      });
+    }
+
+    return {
+      status: 'accepted',
+      message: 'If the account exists, a reset email was sent',
+    };
+  }
+
+  async confirmPasswordReset(token: string, newPassword: string) {
+    const operation = await this.authCoreService.readPendingOperation(
+      token,
+      AUTH_PENDING_OPERATION_TYPES.passwordReset,
+    );
+    const passwordHash = await this.authPasswordService.hash(newPassword);
+    await this.authCoreService.applyPasswordHash(operation.userId, passwordHash);
+    await this.authCoreService.consumePendingOperation(operation.id);
+    return {
+      status: 'completed',
+      message: 'Password reset confirmed',
+    };
+  }
+
+  async startConfirmedChangePassword(
+    userId: string,
+    input: ChangePasswordRequest,
+  ): Promise<ChangePasswordResult> {
+    const account = await this.authCoreService.findAccountByUserIdOrThrow(userId);
+    const passwordHash = await this.authPasswordService.hash(input.newPassword);
+    const operation = await this.authCoreService.issuePendingOperation({
+      userId,
+      type: AUTH_PENDING_OPERATION_TYPES.passwordChange,
+      metadata: {
+        passwordHash,
+      },
+    });
+
+    await this.communicationsService.send({
+      kind: 'password_change_confirmation',
+      channels: ['email'],
+      recipient: { email: account.providerId },
+      payload: {
+        NAME: account.profile?.name ?? 'there',
+        TOKEN: operation.token,
+      },
+      locale: account.settings?.locale ?? undefined,
+      metadata: {
+        USER_ID: account.id,
+        SOURCE: 'accounts-communications.change-password',
+      },
+    });
+
+    return {
+      status: 'pending_confirmation',
+      message: 'Password change confirmation sent',
+    };
+  }
+
+  async confirmChangePassword(token: string) {
+    const operation = await this.authCoreService.readPendingOperation(
+      token,
+      AUTH_PENDING_OPERATION_TYPES.passwordChange,
+    );
+    const passwordHash = this.readMetadataString(operation.metadata, 'passwordHash');
+    await this.authCoreService.applyPasswordHash(operation.userId, passwordHash);
+    await this.authCoreService.consumePendingOperation(operation.id);
+    return {
+      status: 'completed',
+      message: 'Password changed successfully',
+    };
+  }
+
+  async requestChangeEmail(userId: string, input: RequestChangeEmailRequest) {
+    const account = await this.authCoreService.findAccountByUserIdOrThrow(userId);
+    const nextEmail = input.email.trim().toLowerCase();
+    const operation = await this.authCoreService.issuePendingOperation({
+      userId,
+      type: AUTH_PENDING_OPERATION_TYPES.emailChange,
+      metadata: {
+        email: nextEmail,
+      },
+    });
+
+    await this.communicationsService.send({
+      kind: 'email_change_confirmation',
+      channels: ['email'],
+      recipient: { email: nextEmail },
+      payload: {
+        NAME: account.profile?.name ?? 'there',
+        TOKEN: operation.token,
+      },
+      locale: account.settings?.locale ?? undefined,
+      metadata: {
+        USER_ID: account.id,
+        SOURCE: 'accounts-communications.change-email',
+      },
+    });
+
+    return {
+      status: 'accepted',
+      message: 'Email change confirmation sent',
+    };
+  }
+
+  async confirmChangeEmail(token: string) {
+    const operation = await this.authCoreService.readPendingOperation(
+      token,
+      AUTH_PENDING_OPERATION_TYPES.emailChange,
+    );
+    const nextEmail = this.readMetadataString(operation.metadata, 'email');
+    await this.authCoreService.updatePrimaryEmail(operation.userId, nextEmail);
+    await this.authCoreService.consumePendingOperation(operation.id);
+    return {
+      status: 'completed',
+      message: 'Email changed successfully',
+    };
+  }
+
+  async sendWelcomeEmailPlaceholder(_email: string): Promise<void> {
+    return;
+  }
+
+  async sendAccountNotificationPlaceholder(_email: string): Promise<void> {
+    return;
+  }
+
+  private readMetadataString(metadata: Record<string, unknown> | null, key: string): string {
+    const value = metadata?.[key];
+    if (typeof value !== 'string' || value.trim().length === 0) {
+      throw new Error(`Missing pending operation metadata: ${key}`);
+    }
+    return value;
+  }
+}

package/templates/module-presets/accounts-communications/packages/accounts-communications/src/confirmed-change-password.handler.ts

@@ -0,0 +1,16 @@
+import { Injectable } from '@nestjs/common';
+import type {
+  ChangePasswordRequest,
+  ChangePasswordResult,
+} from '@forgeon/accounts-contracts';
+import type { ChangePasswordHandler } from '@forgeon/accounts-api';
+import { AuthCommunicationsService } from './auth-communications.service';
+
+@Injectable()
+export class ConfirmedChangePasswordHandler implements ChangePasswordHandler {
+  constructor(private readonly authCommunicationsService: AuthCommunicationsService) {}
+
+  execute(userId: string, input: ChangePasswordRequest): Promise<ChangePasswordResult> {
+    return this.authCommunicationsService.startConfirmedChangePassword(userId, input);
+  }
+}

package/templates/module-presets/accounts-communications/packages/accounts-communications/src/dto/confirm-change-email.dto.ts

@@ -0,0 +1,8 @@
+import type { ConfirmChangeEmailRequest } from '@forgeon/accounts-contracts';
+import { IsString, MinLength } from 'class-validator';
+
+export class ConfirmChangeEmailDto implements ConfirmChangeEmailRequest {
+  @IsString()
+  @MinLength(8)
+  token!: string;
+}

package/templates/module-presets/accounts-communications/packages/accounts-communications/src/dto/confirm-change-password.dto.ts

@@ -0,0 +1,8 @@
+import type { ConfirmChangePasswordRequest } from '@forgeon/accounts-contracts';
+import { IsString, MinLength } from 'class-validator';
+
+export class ConfirmChangePasswordDto implements ConfirmChangePasswordRequest {
+  @IsString()
+  @MinLength(8)
+  token!: string;
+}

package/templates/module-presets/accounts-communications/packages/accounts-communications/src/dto/confirm-password-reset.dto.ts

@@ -0,0 +1,12 @@
+import type { ConfirmPasswordResetRequest } from '@forgeon/accounts-contracts';
+import { IsString, MinLength } from 'class-validator';
+
+export class ConfirmPasswordResetDto implements ConfirmPasswordResetRequest {
+  @IsString()
+  @MinLength(8)
+  token!: string;
+
+  @IsString()
+  @MinLength(8)
+  newPassword!: string;
+}

package/templates/module-presets/accounts-communications/packages/accounts-communications/src/dto/index.ts

@@ -0,0 +1,6 @@
+export * from './confirm-change-email.dto';
+export * from './confirm-change-password.dto';
+export * from './confirm-password-reset.dto';
+export * from './request-change-email.dto';
+export * from './request-password-reset.dto';
+export * from './verify-email.dto';

package/templates/module-presets/accounts-communications/packages/accounts-communications/src/dto/request-change-email.dto.ts

@@ -0,0 +1,7 @@
+import type { RequestChangeEmailRequest } from '@forgeon/accounts-contracts';
+import { IsEmail } from 'class-validator';
+
+export class RequestChangeEmailDto implements RequestChangeEmailRequest {
+  @IsEmail()
+  email!: string;
+}

package/templates/module-presets/accounts-communications/packages/accounts-communications/src/dto/request-password-reset.dto.ts

@@ -0,0 +1,7 @@
+import type { RequestPasswordResetRequest } from '@forgeon/accounts-contracts';
+import { IsEmail } from 'class-validator';
+
+export class RequestPasswordResetDto implements RequestPasswordResetRequest {
+  @IsEmail()
+  email!: string;
+}

package/templates/module-presets/accounts-communications/packages/accounts-communications/src/dto/verify-email.dto.ts

@@ -0,0 +1,8 @@
+import type { VerifyEmailRequest } from '@forgeon/accounts-contracts';
+import { IsString, MinLength } from 'class-validator';
+
+export class VerifyEmailDto implements VerifyEmailRequest {
+  @IsString()
+  @MinLength(8)
+  token!: string;
+}

package/templates/module-presets/accounts-communications/packages/accounts-communications/src/index.ts

@@ -0,0 +1,5 @@
+export * from './auth-communications.controller';
+export * from './auth-communications.service';
+export * from './confirmed-change-password.handler';
+export * from './pending-verification-register.handler';
+export * from './dto';