feat(spaces): support email invites

.env.sample.json

@@ -1397,6 +1397,24 @@
     "defaultValue": 50,
     "required": false
   },
+  {
+    "name": "SPACES_INVITE_EXPIRY_SECONDS",
+    "description": "Time until a Space invite expires, in seconds",
+    "defaultValue": 604800,
+    "required": false
+  },
+  {
+    "name": "SPACES_RESEND_INVITE_RATE_LIMIT_MAX",
+    "description": "Maximum resend invite requests per time window",
+    "defaultValue": 50,
+    "required": false
+  },
+  {
+    "name": "SPACES_RESEND_INVITE_RATE_LIMIT_WINDOW_SECONDS",
+    "description": "Time window for resend invite rate limiting",
+    "defaultValue": 600,
+    "required": false
+  },
   {
     "name": "SPACES_MAX_SAFES_PER_SPACE",
     "description": "Maximum number of Safes per Space",

migrations/1777000000000-add-member-invite-expires-at.ts

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: FSL-1.1-MIT
+import type { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class AddMemberInviteExpiresAt1777000000000
+  implements MigrationInterface
+{
+  name = 'AddMemberInviteExpiresAt1777000000000';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `ALTER TABLE "members" ADD COLUMN "invite_expires_at" timestamp with time zone`,
+    );
+    await queryRunner.query(
+      // MemberStatus enum values at migration time: 0 = INVITED, 2 = DECLINED.
+      `UPDATE "members" SET "invite_expires_at" = "created_at" + interval '7 days' WHERE "status" IN (0, 2)`,
+    );
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `ALTER TABLE "members" DROP COLUMN "invite_expires_at"`,
+    );
+  }
+}

src/config/entities/__tests__/configuration.ts

@@ -432,6 +432,7 @@ export default (): ReturnType<typeof configuration> => ({
     maxSafesPerSpace: faker.number.int({ min: 5, max: 10 }),
     maxSpaceCreationsPerUser: faker.number.int({ min: 100, max: 200 }),
     maxInvites: faker.number.int({ min: 5, max: 10 }),
+    inviteExpirySeconds: faker.number.int({ min: 100, max: 200 }),
     rateLimit: {
       creation: {
         max: faker.number.int({ min: 100, max: 200 }),
@@ -441,6 +442,10 @@ export default (): ReturnType<typeof configuration> => ({
         max: faker.number.int({ min: 100, max: 200 }),
         windowSeconds: faker.number.int({ min: 100, max: 200 }),
       },
+      resendInvite: {
+        max: faker.number.int({ min: 100, max: 200 }),
+        windowSeconds: faker.number.int({ min: 100, max: 200 }),
+      },
     },
   },
   staking: {

src/config/entities/configuration.ts

@@ -755,6 +755,10 @@ export default () => ({
       10,
     ),
     maxInvites: Number.parseInt(process.env.SPACES_MAX_INVITES ?? `${50}`, 10),
+    inviteExpirySeconds: Number.parseInt(
+      process.env.SPACES_INVITE_EXPIRY_SECONDS ?? `${7 * 24 * 60 * 60}`,
+      10,
+    ),
     rateLimit: {
       creation: {
         max: Number.parseInt(process.env.SPACES_RATE_LIMIT_MAX ?? `${10}`, 10),
@@ -773,6 +777,17 @@ export default () => ({
           10,
         ),
       },
+      resendInvite: {
+        max: Number.parseInt(
+          process.env.SPACES_RESEND_INVITE_RATE_LIMIT_MAX ?? `${50}`,
+          10,
+        ),
+        windowSeconds: Number.parseInt(
+          process.env.SPACES_RESEND_INVITE_RATE_LIMIT_WINDOW_SECONDS ??
+            `${600}`,
+          10,
+        ),
+      },
     },
   },
   staking: {

src/config/entities/schemas/configuration.schema.ts

@@ -61,6 +61,7 @@ export const RootConfigurationSchema = z
       .optional(),
     AUTH0_JWKS_COOLDOWN_MILLISECONDS: z.coerce.number().int().min(1).optional(),
     AUTH_STATE_TTL_MILLISECONDS: z.coerce.number().int().min(1).optional(),
+    SPACES_INVITE_EXPIRY_SECONDS: z.coerce.number().int().min(1).optional(),
     AWS_ACCESS_KEY_ID: z.string().optional(),
     AWS_KMS_ENCRYPTION_KEY_ID: z.string().optional(),
     AWS_SECRET_ACCESS_KEY: z.string().optional(),

src/modules/spaces/domain/spaces.repository.integration.spec.ts

@@ -235,6 +235,7 @@ describe('SpacesRepository', () => {
         name: expect.any(String),
         alias: null,
         invitedBy: null,
+        inviteExpiresAt: null,
         createdAt: expect.any(Date),
         updatedAt: expect.any(Date),
         user: {
@@ -327,6 +328,7 @@ describe('SpacesRepository', () => {
         name: `${spaceName} creator`,
         alias: null,
         invitedBy: null,
+        inviteExpiresAt: null,
         createdAt: expect.any(Date),
         updatedAt: expect.any(Date),
         user: {

src/modules/spaces/routes/entities/__tests__/resend-invite.dto.entity.spec.ts

@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: FSL-1.1-MIT
+import { faker } from '@faker-js/faker';
+import { getAddress } from 'viem';
+import { ResendInviteDtoSchema } from '@/modules/spaces/routes/entities/resend-invite.dto.entity';
+
+describe('ResendInviteDtoSchema', () => {
+  it('should accept an address-only payload', () => {
+    const result = ResendInviteDtoSchema.safeParse({
+      address: getAddress(faker.finance.ethereumAddress()),
+    });
+
+    expect(result.success).toBe(true);
+  });
+
+  it('should accept an email-only payload', () => {
+    const result = ResendInviteDtoSchema.safeParse({
+      email: faker.internet.email().toLowerCase(),
+    });
+
+    expect(result.success).toBe(true);
+  });
+
+  it('should reject a payload that has both address and email', () => {
+    const result = ResendInviteDtoSchema.safeParse({
+      address: getAddress(faker.finance.ethereumAddress()),
+      email: faker.internet.email().toLowerCase(),
+    });
+
+    expect(result.success).toBe(false);
+  });
+
+  it('should reject an empty payload', () => {
+    const result = ResendInviteDtoSchema.safeParse({});
+
+    expect(result.success).toBe(false);
+  });
+
+  it('should reject a non-address string in the address branch', () => {
+    const result = ResendInviteDtoSchema.safeParse({
+      address: 'not-an-address',
+    });
+
+    expect(result.success).toBe(false);
+  });
+
+  it('should reject a malformed email', () => {
+    const result = ResendInviteDtoSchema.safeParse({ email: 'not-an-email' });
+
+    expect(result.success).toBe(false);
+  });
+
+  it('should reject an email longer than 255 characters', () => {
+    const localPart = 'a'.repeat(250);
+    const result = ResendInviteDtoSchema.safeParse({
+      email: `${localPart}@example.com`,
+    });
+
+    expect(result.success).toBe(false);
+  });
+});

src/modules/spaces/routes/entities/get-space.dto.entity.ts

@@ -31,6 +31,9 @@ class SpaceMemberDto {
   })
   public status!: Member['status'];
 
+  @ApiProperty({ type: Date, nullable: true })
+  public inviteExpiresAt!: Member['inviteExpiresAt'];
+
   @ApiProperty({ type: UserDto })
   public user!: Partial<UserDto>;
 }

src/modules/spaces/routes/entities/invitation.entity.ts

@@ -10,8 +10,8 @@ import {
 import type { User } from '@/modules/users/domain/entities/user.entity';
 
 export class Invitation {
-  @ApiProperty({ type: Number })
-  userId!: User['id'];
+  @ApiPropertyOptional({ type: Number })
+  userId?: User['id'];
 
   @ApiProperty({ type: String })
   name!: Member['name'];
@@ -27,4 +27,7 @@ export class Invitation {
 
   @ApiPropertyOptional({ type: String, nullable: true })
   invitedBy!: Member['invitedBy'];
+
+  @ApiProperty({ type: Date })
+  inviteExpiresAt!: Member['inviteExpiresAt'];
 }

src/modules/spaces/routes/entities/invite-users.dto.entity.ts

@@ -1,32 +1,44 @@
 // SPDX-License-Identifier: FSL-1.1-MIT
-import { ApiProperty } from '@nestjs/swagger';
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
 import type { Address } from 'viem';
 import { z } from 'zod';
 import {
   NAME_MAX_LENGTH,
   NAME_MIN_LENGTH,
+  NameSchema,
 } from '@/domain/common/schemas/name.schema';
 import { getStringEnumKeys } from '@/domain/common/utils/enum';
 import { MemberRole } from '@/modules/users/domain/entities/member.entity';
 import { AddressSchema } from '@/validation/entities/schemas/address.schema';
 
-const InviteUserDtoSchema = z
-  .array(
-    z.object({
-      address: AddressSchema,
-      role: z.enum(getStringEnumKeys(MemberRole)),
-      name: z.string().max(255),
-    }),
-  )
-  .min(1);
+const SharedInviteFields = {
+  role: z.enum(getStringEnumKeys(MemberRole)),
+  name: NameSchema,
+};
+
+const InviteUserSchema = z.union([
+  z.object({ address: AddressSchema, ...SharedInviteFields }).strict(),
+  z.object({ email: z.email().max(255), ...SharedInviteFields }).strict(),
+]);
+
+const InviteUserDtoSchema = z.array(InviteUserSchema).min(1);
 
 export const InviteUsersDtoSchema = z.object({
   users: InviteUserDtoSchema,
 });
 
 export class InviteUserDto {
-  @ApiProperty()
-  public readonly address!: Address;
+  @ApiPropertyOptional({
+    description:
+      'Wallet address to invite. Provide either address or email, but not both.',
+  })
+  public readonly address?: Address;
+
+  @ApiPropertyOptional({
+    description:
+      'Email address to invite. Provide either email or address, but not both.',
+  })
+  public readonly email?: string;
 
   @ApiProperty({
     type: String,
@@ -41,7 +53,7 @@ export class InviteUserDto {
   public readonly role!: keyof typeof MemberRole;
 }
 
-export class InviteUsersDto implements z.infer<typeof InviteUsersDtoSchema> {
+export class InviteUsersDto {
   @ApiProperty({
     type: InviteUserDto,
     isArray: true,

src/modules/spaces/routes/entities/members.dto.entity.ts

@@ -48,6 +48,9 @@ export class MemberDto {
   @ApiProperty()
   updatedAt!: Date;
 
+  @ApiProperty({ type: Date, nullable: true })
+  inviteExpiresAt!: DomainMember['inviteExpiresAt'];
+
   @ApiProperty({ type: MemberUser })
   user!: MemberUser;
 }

src/modules/spaces/routes/entities/resend-invite.dto.entity.ts

@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: FSL-1.1-MIT
+import { ApiPropertyOptional } from '@nestjs/swagger';
+import type { Address } from 'viem';
+import { z } from 'zod';
+import { AddressSchema } from '@/validation/entities/schemas/address.schema';
+
+export const ResendInviteDtoSchema = z.union([
+  z.object({ address: AddressSchema }).strict(),
+  z.object({ email: z.email().max(255) }).strict(),
+]);
+
+export class ResendInviteDto {
+  @ApiPropertyOptional()
+  public readonly address?: Address;
+
+  @ApiPropertyOptional()
+  public readonly email?: string;
+}

src/modules/spaces/routes/guards/spaces-resend-invite-rate-limit.guard.ts

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: FSL-1.1-MIT
+import { Inject, Injectable } from '@nestjs/common';
+import { IConfigurationService } from '@/config/configuration.service.interface';
+import {
+  CacheService,
+  type ICacheService,
+} from '@/datasources/cache/cache.service.interface';
+import {
+  type ILoggingService,
+  LoggingService,
+} from '@/logging/logging.interface';
+import { RateLimitGuard } from '@/routes/common/guards/rate-limit.guard';
+
+@Injectable()
+export class SpacesResendInviteRateLimitGuard extends RateLimitGuard {
+  constructor(
+    @Inject(IConfigurationService)
+    readonly configurationService: IConfigurationService,
+    @Inject(CacheService) cacheService: ICacheService,
+    @Inject(LoggingService) loggingService: ILoggingService,
+  ) {
+    const rateLimits = {
+      max: configurationService.getOrThrow<number>(
+        'spaces.rateLimit.resendInvite.max',
+      ),
+      windowSeconds: configurationService.getOrThrow<number>(
+        'spaces.rateLimit.resendInvite.windowSeconds',
+      ),
+    };
+    super(cacheService, loggingService, rateLimits);
+  }
+}