@gravito/satellite-membership 0.1.1

package/src/Application/UseCases/LoginMember.ts

@@ -0,0 +1,64 @@
+import type { PlanetCore } from '@gravito/core'
+import { UseCase } from '@gravito/enterprise'
+import type { IMemberRepository } from '../../Domain/Contracts/IMemberRepository'
+import type { MemberDTO } from '../DTOs/MemberDTO'
+import { MemberMapper } from '../DTOs/MemberDTO'
+
+export interface LoginMemberInput {
+  email: string
+  passwordPlain: string
+  remember?: boolean
+}
+
+/**
+ * Login Member Use Case
+ *
+ * Uses Gravito Sentinel for robust authentication.
+ * Supports multi-device login restriction toggle via config.
+ */
+export class LoginMember extends UseCase<LoginMemberInput, MemberDTO> {
+  constructor(
+    private repository: IMemberRepository,
+    private core: PlanetCore
+  ) {
+    super()
+  }
+
+  async execute(input: LoginMemberInput): Promise<MemberDTO> {
+    // 使用核心的 auth 管理器 (Sentinel) 進行驗證
+    const auth = this.core.container.make<any>('auth')
+
+    const result = await auth.guard('web').attempt(
+      {
+        email: input.email,
+        password: input.passwordPlain,
+      },
+      input.remember || false
+    )
+
+    if (!result) {
+      throw new Error('Invalid credentials')
+    }
+
+    const user = await auth.guard('web').user()
+
+    // 多設備限制邏輯
+    const singleDevice = this.core.config.get('membership.auth.single_device', false)
+    if (singleDevice) {
+      const session = this.core.container.make<any>('session')
+      if (session) {
+        // 獲取目前生成的 Session ID
+        const sessionId = session.id()
+
+        // 更新會員實體中的 Session ID
+        const member = await this.repository.findById(user.id)
+        if (member) {
+          member.bindSession(sessionId)
+          await this.repository.save(member)
+        }
+      }
+    }
+
+    return MemberMapper.toDTO(user)
+  }
+}

package/src/Application/UseCases/RegisterMember.ts

@@ -0,0 +1,65 @@
+import type { PlanetCore } from '@gravito/core'
+import { UseCase } from '@gravito/enterprise'
+import type { IMemberRepository } from '../../Domain/Contracts/IMemberRepository'
+import { Member } from '../../Domain/Entities/Member'
+import type { MemberDTO } from '../DTOs/MemberDTO'
+import { MemberMapper } from '../DTOs/MemberDTO'
+
+/**
+ * Input for the member registration process
+ */
+export interface RegisterMemberInput {
+  name: string
+  email: string
+  passwordPlain: string
+}
+
+/**
+ * Register Member Use Case
+ *
+ * Coordinates the registration of a new member including validation,
+ * password hashing, and domain event triggering.
+ */
+export class RegisterMember extends UseCase<RegisterMemberInput, MemberDTO> {
+  constructor(
+    private repository: IMemberRepository,
+    private core: PlanetCore
+  ) {
+    super()
+  }
+
+  /**
+   * Execute the registration flow
+   */
+  async execute(input: RegisterMemberInput): Promise<MemberDTO> {
+    // 1. Check if email already exists
+    const existing = await this.repository.findByEmail(input.email)
+    if (existing) {
+      // Use i18n from core services
+      const i18n = this.core.container.make<any>('i18n')
+      throw new Error(i18n?.t('membership.errors.member_exists') || 'Member already exists')
+    }
+
+    // 2. Hash password using the core hasher
+    const passwordHash = await this.core.hasher.make(input.passwordPlain)
+
+    // 3. Create domain entity
+    const member = Member.create(crypto.randomUUID(), input.name, input.email, passwordHash)
+
+    // 4. Save to persistence
+    await this.repository.save(member)
+
+    // 5. Send Verification Email (via Signal hook)
+    await this.core.hooks.doAction('membership:send-verification', {
+      email: member.email,
+      token: member.verificationToken,
+    })
+
+    // 6. Trigger hooks for general extensions
+    await this.core.hooks.doAction('membership:registered', {
+      member: MemberMapper.toDTO(member),
+    })
+
+    return MemberMapper.toDTO(member)
+  }
+}

package/src/Application/UseCases/ResetPassword.ts

@@ -0,0 +1,30 @@
+import type { PlanetCore } from '@gravito/core'
+import { UseCase } from '@gravito/enterprise'
+import type { IMemberRepository } from '../../Domain/Contracts/IMemberRepository'
+
+export interface ResetPasswordInput {
+  token: string
+  newPasswordPlain: string
+}
+
+export class ResetPassword extends UseCase<ResetPasswordInput, void> {
+  constructor(
+    private repository: IMemberRepository,
+    private core: PlanetCore
+  ) {
+    super()
+  }
+
+  async execute(input: ResetPasswordInput): Promise<void> {
+    const member = await this.repository.findByResetToken(input.token)
+
+    if (!member || !member.passwordResetExpiresAt || member.passwordResetExpiresAt < new Date()) {
+      throw new Error('Invalid or expired reset token')
+    }
+
+    const newHash = await this.core.hasher.make(input.newPasswordPlain)
+    member.resetPassword(newHash)
+
+    await this.repository.save(member)
+  }
+}

package/src/Application/UseCases/UpdateMemberLevel.ts

@@ -0,0 +1,47 @@
+import type { PlanetCore } from '@gravito/core'
+import { UseCase } from '@gravito/enterprise'
+import type { IMemberRepository } from '../../Domain/Contracts/IMemberRepository'
+import type { MemberDTO } from '../DTOs/MemberDTO'
+import { MemberMapper } from '../DTOs/MemberDTO'
+
+export interface UpdateLevelInput {
+  memberId: string
+  newLevel: string
+}
+
+/**
+ * Update Member Level Use Case
+ *
+ * Typically used by administrative systems or loyalty programs to promote members.
+ */
+export class UpdateMemberLevel extends UseCase<UpdateLevelInput, MemberDTO> {
+  constructor(
+    private repository: IMemberRepository,
+    private core: PlanetCore
+  ) {
+    super()
+  }
+
+  async execute(input: UpdateLevelInput): Promise<MemberDTO> {
+    const member = await this.repository.findById(input.memberId)
+
+    if (!member) {
+      throw new Error('Member not found')
+    }
+
+    const oldLevel = member.level
+    member.changeLevel(input.newLevel)
+
+    await this.repository.save(member)
+
+    // Trigger hook for tier change (e.g., to send congratulations or update discounts)
+    await this.core.hooks.doAction('membership:level-changed', {
+      memberId: member.id,
+      email: member.email,
+      oldLevel,
+      newLevel: input.newLevel,
+    })
+
+    return MemberMapper.toDTO(member)
+  }
+}

package/src/Application/UseCases/UpdateSettings.ts

@@ -0,0 +1,81 @@
+import type { PlanetCore } from '@gravito/core'
+import { UseCase } from '@gravito/enterprise'
+import type { IMemberRepository } from '../../Domain/Contracts/IMemberRepository'
+import type { MemberDTO } from '../DTOs/MemberDTO'
+import { MemberMapper } from '../DTOs/MemberDTO'
+
+/**
+ * Input for updating member settings
+ */
+export interface UpdateSettingsInput {
+  memberId: string
+  name?: string
+  currentPassword?: string
+  newPassword?: string
+  /** Custom metadata fields provided by extensions or specific apps */
+  metadata?: Record<string, any>
+}
+
+/**
+ * Update Settings Use Case
+ *
+ * Handles profile updates, password changes, and dynamic metadata enrichment.
+ */
+export class UpdateSettings extends UseCase<UpdateSettingsInput, MemberDTO> {
+  constructor(
+    private repository: IMemberRepository,
+    private core: PlanetCore
+  ) {
+    super()
+  }
+
+  /**
+   * Execute the update flow
+   */
+  async execute(input: UpdateSettingsInput): Promise<MemberDTO> {
+    const member = await this.repository.findById(input.memberId)
+
+    if (!member) {
+      throw new Error('Member not found')
+    }
+
+    // 1. Handle Profile Update
+    if (input.name) {
+      member.updateProfile(input.name)
+    }
+
+    // 2. Handle Password Change (Secure Flow)
+    if (input.newPassword) {
+      if (!input.currentPassword) {
+        throw new Error('Current password is required to set a new password')
+      }
+
+      const isCurrentValid = await this.core.hasher.check(
+        input.currentPassword,
+        member.passwordHash
+      )
+      if (!isCurrentValid) {
+        throw new Error('Invalid current password')
+      }
+
+      const newHash = await this.core.hasher.make(input.newPassword)
+      member.changePassword(newHash)
+    }
+
+    // 3. Handle Dynamic Metadata (Custom Fields)
+    if (input.metadata) {
+      member.updateMetadata(input.metadata)
+    }
+
+    // 4. Persist changes
+    await this.repository.save(member)
+
+    // 5. Trigger update hook
+    await this.core.hooks.doAction('membership:updated', {
+      member: MemberMapper.toDTO(member),
+      updatedFields: Object.keys(input).filter((k) => k !== 'memberId' && k !== 'currentPassword'),
+    })
+
+    return MemberMapper.toDTO(member)
+  }
+}

package/src/Application/UseCases/VerifyEmail.ts

@@ -0,0 +1,23 @@
+import { UseCase } from '@gravito/enterprise'
+import type { IMemberRepository } from '../../Domain/Contracts/IMemberRepository'
+
+export interface VerifyEmailInput {
+  token: string
+}
+
+export class VerifyEmail extends UseCase<VerifyEmailInput, void> {
+  constructor(private repository: IMemberRepository) {
+    super()
+  }
+
+  async execute(input: VerifyEmailInput): Promise<void> {
+    const member = await this.repository.findByVerificationToken(input.token)
+
+    if (!member) {
+      throw new Error('Invalid verification token')
+    }
+
+    member.verifyEmail()
+    await this.repository.save(member)
+  }
+}

package/src/Domain/Contracts/IMemberPasskeyRepository.ts

@@ -0,0 +1,8 @@
+import type { Repository } from '@gravito/enterprise'
+import type { MemberPasskey } from '../Entities/MemberPasskey'
+
+export interface IMemberPasskeyRepository extends Repository<MemberPasskey, string> {
+  findByMemberId(memberId: string): Promise<MemberPasskey[]>
+  findByCredentialId(credentialId: string): Promise<MemberPasskey | null>
+  deleteByCredentialId(credentialId: string): Promise<void>
+}

package/src/Domain/Contracts/IMemberRepository.ts

@@ -0,0 +1,11 @@
+import type { Repository } from '@gravito/enterprise'
+import type { Member } from '../Entities/Member'
+
+/**
+ * Member Repository Contract
+ */
+export interface IMemberRepository extends Repository<Member, string> {
+  findByEmail(email: string): Promise<Member | null>
+  findByVerificationToken(token: string): Promise<Member | null>
+  findByResetToken(token: string): Promise<Member | null>
+}

package/src/Domain/Entities/Member.ts

@@ -0,0 +1,219 @@
+import { Entity } from '@gravito/enterprise'
+
+/**
+ * Member status enumeration
+ */
+export enum MemberStatus {
+  ACTIVE = 'active',
+  PENDING = 'pending',
+  SUSPENDED = 'suspended',
+}
+
+/**
+ * Properties for the Member entity
+ */
+export interface MemberProps {
+  email: string
+  name: string
+  passwordHash: string
+  status: MemberStatus
+  roles: string[]
+  verificationToken?: string
+  emailVerifiedAt?: Date
+  passwordResetToken?: string
+  passwordResetExpiresAt?: Date
+  currentSessionId?: string
+  rememberToken?: string
+  createdAt: Date
+  updatedAt: Date
+  /** Flexible metadata for extensions */
+  metadata?: Record<string, any>
+}
+
+/**
+ * Member Domain Entity
+ */
+export class Member extends Entity<string> {
+  private constructor(
+    id: string,
+    private props: MemberProps
+  ) {
+    super(id)
+  }
+
+  static create(id: string, name: string, email: string, passwordHash: string): Member {
+    return new Member(id, {
+      name,
+      email,
+      passwordHash,
+      status: MemberStatus.PENDING,
+      roles: ['member'],
+      verificationToken: crypto.randomUUID(),
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    })
+  }
+
+  static reconstitute(id: string, props: MemberProps): Member {
+    return new Member(id, props)
+  }
+
+  // Getters
+  get name() {
+    return this.props.name
+  }
+  get email() {
+    return this.props.email
+  }
+  get status() {
+    return this.props.status
+  }
+  get roles() {
+    return this.props.roles
+  }
+  get passwordHash() {
+    return this.props.passwordHash
+  }
+  get createdAt() {
+    return this.props.createdAt
+  }
+  get emailVerifiedAt() {
+    return this.props.emailVerifiedAt
+  }
+  get verificationToken() {
+    return this.props.verificationToken
+  }
+  get passwordResetToken() {
+    return this.props.passwordResetToken
+  }
+  get passwordResetExpiresAt() {
+    return this.props.passwordResetExpiresAt
+  }
+  get currentSessionId() {
+    return this.props.currentSessionId
+  }
+  get rememberToken() {
+    return this.props.rememberToken
+  }
+  get metadata() {
+    return this.props.metadata || {}
+  }
+
+  // Authenticatable implementation
+  getAuthIdentifier(): string {
+    return this.id
+  }
+  getAuthPassword(): string {
+    return this.props.passwordHash
+  }
+  getRememberToken(): string | null {
+    return this.props.rememberToken || null
+  }
+  setRememberToken(token: string): void {
+    this.props.rememberToken = token
+    this.props.updatedAt = new Date()
+  }
+
+  /**
+   * Bind a session ID to this member to restrict multi-device login.
+   */
+  public bindSession(sessionId: string): void {
+    this.props.currentSessionId = sessionId
+    this.props.updatedAt = new Date()
+  }
+
+  /**
+   * Get current membership level (from metadata or default)
+   */
+  get level(): string {
+    return this.metadata.level || 'standard'
+  }
+
+  /**
+   * Check if member has a specific role
+   */
+  public hasRole(role: string): boolean {
+    return this.props.roles.includes(role)
+  }
+
+  /**
+   * Assign a new role
+   */
+  public addRole(role: string): void {
+    if (!this.hasRole(role)) {
+      this.props.roles.push(role)
+      this.props.updatedAt = new Date()
+    }
+  }
+
+  /**
+   * Remove a role
+   */
+  public removeRole(role: string): void {
+    this.props.roles = this.props.roles.filter((r) => r !== role)
+    this.props.updatedAt = new Date()
+  }
+
+  /**
+   * Update membership level
+   */
+  public changeLevel(newLevel: string): void {
+    this.updateMetadata({ level: newLevel })
+  }
+
+  /**
+   * Update core profile information
+   */
+  public updateProfile(name: string): void {
+    this.props.name = name
+    this.props.updatedAt = new Date()
+  }
+
+  /**
+   * Update member password
+   */
+  public changePassword(newPasswordHash: string): void {
+    this.props.passwordHash = newPasswordHash
+    this.props.updatedAt = new Date()
+  }
+
+  /**
+   * Merges new metadata into existing metadata
+   */
+  public updateMetadata(data: Record<string, any>): void {
+    this.props.metadata = {
+      ...(this.props.metadata || {}),
+      ...data,
+    }
+    this.props.updatedAt = new Date()
+  }
+
+  /**
+   * Mark email as verified
+   */
+  public verifyEmail(): void {
+    this.props.emailVerifiedAt = new Date()
+    this.props.status = MemberStatus.ACTIVE
+    this.props.verificationToken = undefined
+    this.props.updatedAt = new Date()
+  }
+
+  /**
+   * Generate a password reset token
+   */
+  public generatePasswordResetToken(): void {
+    this.props.passwordResetToken = crypto.randomUUID()
+    this.props.passwordResetExpiresAt = new Date(Date.now() + 3600000)
+    this.props.updatedAt = new Date()
+  }
+
+  /**
+   * Complete password reset
+   */
+  public resetPassword(newPasswordHash: string): void {
+    this.props.passwordHash = newPasswordHash
+    this.props.passwordResetToken = undefined
+    this.props.passwordResetExpiresAt = undefined
+    this.props.updatedAt = new Date()
+  }
+}

package/src/Domain/Entities/MemberPasskey.ts

@@ -0,0 +1,97 @@
+import { Entity } from '@gravito/enterprise'
+
+export interface MemberPasskeyProps {
+  memberId: string
+  credentialId: string
+  publicKey: string
+  counter: number
+  transports?: string[]
+  displayName?: string
+  createdAt: Date
+  updatedAt: Date
+}
+
+export class MemberPasskey extends Entity<string> {
+  private constructor(
+    id: string,
+    private props: MemberPasskeyProps
+  ) {
+    super(id)
+  }
+
+  static create(params: {
+    memberId: string
+    credentialId: string
+    publicKey: string
+    transports?: string[]
+    displayName?: string
+    counter?: number
+  }): MemberPasskey {
+    const now = new Date()
+    return new MemberPasskey(crypto.randomUUID(), {
+      memberId: params.memberId,
+      credentialId: params.credentialId,
+      publicKey: params.publicKey,
+      counter: params.counter ?? 0,
+      transports: params.transports,
+      displayName: params.displayName,
+      createdAt: now,
+      updatedAt: now,
+    })
+  }
+
+  static reconstitute(id: string, props: MemberPasskeyProps): MemberPasskey {
+    return new MemberPasskey(id, props)
+  }
+
+  get memberId(): string {
+    return this.props.memberId
+  }
+
+  get credentialId(): string {
+    return this.props.credentialId
+  }
+
+  get publicKey(): string {
+    return this.props.publicKey
+  }
+
+  get counter(): number {
+    return this.props.counter
+  }
+
+  get transports(): string[] | undefined {
+    return this.props.transports
+  }
+
+  get displayName(): string | undefined {
+    return this.props.displayName
+  }
+
+  get createdAt(): Date {
+    return this.props.createdAt
+  }
+
+  get updatedAt(): Date {
+    return this.props.updatedAt
+  }
+
+  public updateCounter(next: number): void {
+    this.props.counter = next
+    this.props.updatedAt = new Date()
+  }
+
+  toRecord(): Record<string, unknown> {
+    return {
+      id: this.id,
+      member_id: this.memberId,
+      credential_id: this.credentialId,
+      public_key: this.publicKey,
+      counter: this.counter,
+      transports: this.transports ? JSON.stringify(this.transports) : null,
+      display_name: this.displayName,
+      created_at: this.createdAt,
+      updated_at: this.updatedAt,
+    }
+  }
+}

package/src/Infrastructure/Auth/SentinelMemberProvider.ts

@@ -0,0 +1,52 @@
+import type { Authenticatable, UserProvider } from '@gravito/sentinel'
+import type { IMemberRepository } from '../../Domain/Contracts/IMemberRepository'
+import type { Member } from '../../Domain/Entities/Member'
+
+/**
+ * Sentinel Member Provider
+ *
+ * Adapts our Member Repository to Gravito Sentinel's Auth system.
+ */
+export class SentinelMemberProvider implements UserProvider {
+  constructor(private repository: IMemberRepository) {}
+
+  async retrieveById(id: string): Promise<Authenticatable | null> {
+    const member = await this.repository.findById(id)
+    return member ? this.toAuthenticatable(member) : null
+  }
+
+  async retrieveByToken(id: string, token: string): Promise<Authenticatable | null> {
+    const member = await this.repository.findById(id)
+    if (member && member.getRememberToken() === token) {
+      return member
+    }
+    return null
+  }
+
+  async updateRememberToken(user: Authenticatable, token: string): Promise<void> {
+    const member = await this.repository.findById(user.getAuthIdentifier() as string)
+    if (member) {
+      member.setRememberToken(token)
+      await this.repository.save(member)
+    }
+  }
+
+  async retrieveByCredentials(credentials: Record<string, any>): Promise<Authenticatable | null> {
+    if (!credentials.email) {
+      return null
+    }
+    return await this.repository.findByEmail(credentials.email)
+  }
+
+  async validateCredentials(
+    _user: Authenticatable,
+    _credentials: Record<string, any>
+  ): Promise<boolean> {
+    // Note: In a real app, you might check if account is active here
+    return true
+  }
+
+  private toAuthenticatable(member: Member): Authenticatable {
+    return member
+  }
+}