@gravito/satellite-membership 0.1.1

package/docs/EXTENDING.md

@@ -0,0 +1,99 @@
+# 🛠️ Membership Satellite 擴充與自定義指南
+
+歡迎使用 Gravito 會員系統！本模組設計之初就考慮到了極高的靈活性。您可以透過以下幾種方式，在不修改原始碼的情況下，將此模組轉化為您專屬的服務。
+
+## 1. 視覺與品牌 (Branding)
+
+這是最簡單的自定義方式。
+
+### 更改顏色與名稱
+在您的 `PlanetCore` 配置中：
+```typescript
+core.configure({
+  membership: {
+    branding: {
+      name: '您的專案名稱',
+      primary_color: '#FF5733' // 您的品牌主色調
+    }
+  }
+})
+```
+
+### 覆寫郵件模板
+本模組使用 Prism 模板引擎。如果您想更換郵件設計，**不需要**更動本模組。
+只需在您的專案根目錄下建立對應檔案：
+- `views/emails/welcome.html`
+- `views/emails/reset_password.html`
+
+系統會自動優先讀取您的檔案。您可以在模板中使用 `{{ branding.name }}` 等變數來保持同步。
+
+---
+
+## 2. 業務邏輯擴充 (Hooks)
+
+如果您想在特定動作發生時「順便」做些什麼，請使用 Hook。
+
+### 範例：註冊成功後發送 Slack 通知
+在您的 `ServiceProvider` 中：
+```typescript
+core.hooks.addAction('membership:registered', async ({ member }) => {
+  // 調用您的 Slack API
+  await mySlackService.notify(`新用戶註冊: ${member.email}`);
+});
+```
+
+---
+
+## 3. 深度行為替換 (Container Override)
+
+如果您覺得預設的登入邏輯不符合需求（例如：您想增加圖形驗證碼檢查），您可以直接替換 UseCase。
+
+### 步驟 A：繼承並擴充
+```typescript
+import { LoginMember } from '@gravito/satellite-membership'
+
+export class MyCustomLogin extends LoginMember {
+  async execute(input) {
+    // 1. 執行您的自定義驗證
+    if (!await checkCaptcha(input.captcha)) {
+      throw new Error('驗證碼錯誤');
+    }
+    // 2. 調用父類別完成標準登入
+    return super.execute(input);
+  }
+}
+```
+
+### 步驟 B：重新註冊
+在您的 `bootstrap` 過程中：
+```typescript
+core.container.singleton('membership.login', () => new MyCustomLogin(core));
+```
+
+---
+
+## 4. 數據擴充 (Metadata)
+
+您不需要為會員資料表增加欄位（如：電話、地址）。
+
+### 存入自定義資料
+```typescript
+const update = container.make('membership.update-settings')
+await update.execute({
+  memberId: '...',
+  metadata: {
+    phone: '0912345678',
+    address: '台北市...',
+    preferences: { theme: 'dark' }
+  }
+})
+```
+這些資料會以 JSON 格式存儲於 `metadata` 欄位中，並隨時可以透過 `member.metadata.phone` 讀取。
+
+---
+
+## 🎯 DX 小貼士
+- **本地預覽**: 啟動 `devMode: true`，所有發出的郵件都會在 Console 印出，並可在 `/__mail` 介面預覽。
+- **類型安全**: 建議始終使用 `MemberDTO` 來進行前端數據交換，確保敏感資料（如 Password Hash）不會洩漏。
+
+希望這份指南能幫助您快速打造出完美的會員系統！🚀

package/docs/PASSKEYS.md

@@ -0,0 +1,78 @@
+# Passkeys (WebAuthn) Integration
+
+This document shows how to integrate **Passkeys** (WebAuthn) with the [Membership Satellite](../../README.md) using the APIs that were added under `/api/membership/passkeys`.
+
+## Dependencies
+- Install `@simplewebauthn/browser` on the client.
+- Make sure your site is served over HTTPS (or `localhost` during development).
+
+```bash
+bun add @simplewebauthn/browser
+```
+
+## Registration flow
+
+```ts
+import { startRegistration } from '@simplewebauthn/browser'
+
+const baseUrl = '/api/membership/passkeys'
+
+async function beginPasskeyRegistration() {
+  const opts = await fetch(`${baseUrl}/register/options`, {
+    method: 'POST',
+    credentials: 'include',
+  }).then((res) => res.json())
+
+  const credential = await startRegistration(opts)
+
+  await fetch(`${baseUrl}/register/verify`, {
+    method: 'POST',
+    credentials: 'include',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      credential,
+      displayName: 'My iPhone',
+    }),
+  })
+}
+```
+
+1. POST to `/register/options` after the user is authenticated (call `auth()` route guard from the backend) to receive the registration challenge.
+2. Call `startRegistration` from `@simplewebauthn/browser` and send the resulting credential to `/register/verify`.
+3. The server will verify the attestation, store the credential, and keep the session logged in.
+
+## Authentication flow
+
+```ts
+import { startAuthentication } from '@simplewebauthn/browser'
+
+async function beginPasskeyLogin(email: string) {
+  const opts = await fetch(`${baseUrl}/login/options`, {
+    method: 'POST',
+    credentials: 'include',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ email }),
+  }).then((res) => res.json())
+
+  const assertion = await startAuthentication(opts)
+
+  await fetch(`${baseUrl}/login/verify`, {
+    method: 'POST',
+    credentials: 'include',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      email,
+      assertion,
+    }),
+  })
+}
+```
+
+1. Send the member's email to `/login/options` to receive challenge data; this endpoint does not require authentication but expects a valid email.
+2. Run `startAuthentication` and POST the assertion to `/login/verify`.
+3. On success the backend logs the member in via the existing `AuthManager`.
+
+## Notes
+- These endpoints rely on session storage (`core.adapter` session provider). Ensure your client includes `credentials: 'include'`.
+- You can show UI feedback when registration/authentication fails by catching the thrown errors.
+- Store `credential.id` locally if you want to list registered devices; the backend already saves `displayName` and `transports`.

package/locales/en.json

@@ -0,0 +1,30 @@
+{
+  "errors": {
+    "member_exists": "Member with this email already exists",
+    "invalid_credentials": "Invalid credentials",
+    "account_suspended": "Account is suspended",
+    "member_not_found": "Member not found",
+    "current_password_required": "Current password is required to set a new password",
+    "invalid_current_password": "Invalid current password",
+    "invalid_token": "Invalid or expired token",
+    "session_expired_other_device": "Your account has been logged in on another device. This session is now invalid."
+  },
+  "notifications": {
+    "operational": "Satellite Membership is operational"
+  },
+  "emails": {
+    "welcome_subject": "Welcome to Gravito!",
+    "welcome_title": "Welcome Aboard",
+    "welcome_body": "Please click the button below to verify your email address:",
+    "verify_button": "Verify Email",
+    "reset_password_subject": "Reset Your Password",
+    "reset_password_title": "Reset Password Request",
+    "reset_password_body": "We received a request to reset your password. If you didn't make this request, just ignore this email.",
+    "reset_password_button": "Reset Password",
+    "reset_password_warning": "If you did not request a password reset, no further action is required.",
+    "level_changed_subject": "Your membership level has been updated!",
+    "level_changed_badge": "Level Up",
+    "level_changed_title": "Congratulations!",
+    "level_changed_body": "Your membership level has been successfully upgraded. You can now enjoy more exclusive benefits."
+  }
+}

package/locales/zh-TW.json

@@ -0,0 +1,30 @@
+{
+  "errors": {
+    "member_exists": "使用此電子郵件的會員已存在",
+    "invalid_credentials": "認證資料無效",
+    "account_suspended": "帳號已被停權",
+    "member_not_found": "找不到會員",
+    "current_password_required": "設定新密碼需要輸入目前密碼",
+    "invalid_current_password": "目前密碼錯誤",
+    "invalid_token": "無效或已過期的權杖",
+    "session_expired_other_device": "您的帳號已在其他裝置登入，目前的連線已失效。"
+  },
+  "notifications": {
+    "operational": "會員衛星模組已啟動"
+  },
+  "emails": {
+    "welcome_subject": "歡迎加入 Gravito！",
+    "welcome_title": "歡迎您的加入",
+    "welcome_body": "請點擊下方按鈕驗證您的電子郵件地址：",
+    "verify_button": "驗證電子郵件",
+    "reset_password_subject": "重設您的密碼",
+    "reset_password_title": "重設密碼請求",
+    "reset_password_body": "我們收到了重設您密碼的請求。如果您沒有提出此請求，請忽略此郵件。",
+    "reset_password_button": "重設密碼",
+    "reset_password_warning": "如果您沒有要求重設密碼，請忽略此封郵件。",
+    "level_changed_subject": "您的會員等級已更新！",
+    "level_changed_badge": "晉級通知",
+    "level_changed_title": "恭喜晉級！",
+    "level_changed_body": "您的會員帳號已成功升級。現在您可以享受更多專屬權益與服務。"
+  }
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@gravito/satellite-membership",
+  "version": "0.1.1",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean --external @gravito/atlas --external @gravito/cosmos --external @gravito/enterprise --external @gravito/sentinel --external @gravito/signal --external @gravito/stasis --external @simplewebauthn/server --external @gravito/core",
+    "test": "bun test",
+    "typecheck": "bun tsc -p tsconfig.json --noEmit --skipLibCheck"
+  },
+  "dependencies": {
+    "@gravito/atlas": "workspace:*",
+    "@gravito/cosmos": "workspace:*",
+    "@gravito/enterprise": "workspace:*",
+    "@gravito/sentinel": "workspace:*",
+    "@gravito/signal": "workspace:*",
+    "@gravito/stasis": "workspace:*",
+    "@simplewebauthn/server": "^13.2.2",
+    "@gravito/core": "workspace:*"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gravito-framework/gravito.git",
+    "directory": "satellites/membership"
+  }
+}

package/src/Application/DTOs/MemberDTO.ts

@@ -0,0 +1,34 @@
+/**
+ * Data Transfer Object for Member information
+ */
+export interface MemberDTO {
+  id: string
+  name: string
+  email: string
+  status: string
+  level: string
+  roles: string[]
+  createdAt: string
+  metadata?: Record<string, any>
+}
+
+/**
+ * Mapper to convert Domain Entities to DTOs
+ */
+export class MemberMapper {
+  /**
+   * Convert a member entity to a serializable DTO
+   */
+  static toDTO(member: any): MemberDTO {
+    return {
+      id: member.id,
+      name: member.name,
+      email: member.email,
+      status: member.status,
+      level: member.level || 'standard',
+      roles: member.roles || [],
+      createdAt: member.createdAt.toISOString(),
+      metadata: member.metadata,
+    }
+  }
+}

package/src/Application/Mail/ForgotPasswordMail.ts

@@ -0,0 +1,42 @@
+import { app } from '@gravito/core'
+import { Mailable } from '@gravito/signal'
+
+export class ForgotPasswordMail extends Mailable {
+  constructor(
+    private email: string,
+    private token: string
+  ) {
+    super()
+  }
+
+  build(): this {
+    const branding = {
+      name: 'Gravito App',
+      color: '#f43f5e',
+    }
+    let baseUrl = 'http://localhost:3000'
+
+    try {
+      const core = app()
+      if (core) {
+        branding.name = core.config.get('membership.branding.name', branding.name)
+        branding.color = core.config.get('membership.branding.primary_color', branding.color)
+        baseUrl = core.config.get('app.url', baseUrl)
+      }
+    } catch (_e) {}
+
+    return this.to(this.email)
+      .subject(this.t('membership.emails.reset_password_subject'))
+      .view('emails/reset_password', {
+        resetUrl: `${baseUrl}/reset-password?token=${this.token}`,
+        branding,
+        currentYear: new Date().getFullYear(),
+        lang: {
+          reset_password_title: this.t('membership.emails.reset_password_title'),
+          reset_password_body: this.t('membership.emails.reset_password_body'),
+          reset_password_button: this.t('membership.emails.reset_password_button'),
+          reset_password_warning: this.t('membership.emails.reset_password_warning'),
+        },
+      })
+  }
+}

package/src/Application/Mail/MemberLevelChangedMail.ts

@@ -0,0 +1,41 @@
+import { app } from '@gravito/core'
+import { Mailable } from '@gravito/signal'
+
+export class MemberLevelChangedMail extends Mailable {
+  constructor(
+    private email: string,
+    private oldLevel: string,
+    private newLevel: string
+  ) {
+    super()
+  }
+
+  build(): this {
+    const branding = {
+      name: 'Gravito App',
+      color: '#f59e0b',
+    }
+
+    try {
+      const core = app()
+      if (core) {
+        branding.name = core.config.get('membership.branding.name', branding.name)
+        branding.color = core.config.get('membership.branding.primary_color', branding.color)
+      }
+    } catch (_e) {}
+
+    return this.to(this.email)
+      .subject(this.t('membership.emails.level_changed_subject'))
+      .view('emails/level_changed', {
+        oldLevel: this.oldLevel,
+        newLevel: this.newLevel,
+        branding,
+        currentYear: new Date().getFullYear(),
+        lang: {
+          badge_text: this.t('membership.emails.level_changed_badge'),
+          title: this.t('membership.emails.level_changed_title'),
+          body: this.t('membership.emails.level_changed_body'),
+        },
+      })
+  }
+}

package/src/Application/Mail/WelcomeMail.ts

@@ -0,0 +1,45 @@
+import { app } from '@gravito/core'
+import { Mailable } from '@gravito/signal'
+
+export class WelcomeMail extends Mailable {
+  constructor(
+    private email: string,
+    private token: string
+  ) {
+    super()
+  }
+
+  build(): this {
+    // 品牌配置抽象化 (提供安全回退值)
+    const branding = {
+      name: 'Gravito App',
+      color: '#6366f1',
+    }
+    let baseUrl = 'http://localhost:3000'
+
+    try {
+      // 嘗試從全域獲取 (僅在 PlanetCore 運行時有效)
+      const core = app()
+      if (core) {
+        branding.name = core.config.get('membership.branding.name', branding.name)
+        branding.color = core.config.get('membership.branding.primary_color', branding.color)
+        baseUrl = core.config.get('app.url', baseUrl)
+      }
+    } catch (_e) {
+      // 忽略錯誤，使用預設值
+    }
+
+    return this.to(this.email)
+      .subject(this.t('membership.emails.welcome_subject'))
+      .view('emails/welcome', {
+        verificationUrl: `${baseUrl}/verify?token=${this.token}`,
+        branding,
+        currentYear: new Date().getFullYear(),
+        lang: {
+          welcome_title: this.t('membership.emails.welcome_title'),
+          welcome_body: this.t('membership.emails.welcome_body'),
+          verify_button: this.t('membership.emails.verify_button'),
+        },
+      })
+  }
+}

package/src/Application/Services/PasskeysService.ts

@@ -0,0 +1,198 @@
+import { AuthenticationException } from '@gravito/core'
+import type {
+  AuthenticationResponseJSON,
+  AuthenticatorTransportFuture,
+  RegistrationResponseJSON,
+  WebAuthnCredential,
+} from '@simplewebauthn/server'
+import {
+  generateAuthenticationOptions,
+  generateRegistrationOptions,
+  verifyAuthenticationResponse,
+  verifyRegistrationResponse,
+} from '@simplewebauthn/server'
+import type { IMemberPasskeyRepository } from '../../Domain/Contracts/IMemberPasskeyRepository'
+import type { Member } from '../../Domain/Entities/Member'
+import { MemberPasskey } from '../../Domain/Entities/MemberPasskey'
+
+interface SessionLike {
+  get(key: string): string | null | undefined
+  put(key: string, value: unknown): void
+  forget?(key: string): void
+}
+
+const SESSION_KEYS = {
+  registration: 'membership.passkeys.registration.challenge',
+  authentication: 'membership.passkeys.authentication.challenge',
+}
+
+export interface PasskeysConfig {
+  rpName: string
+  rpID: string
+  origin: string
+  timeout?: number
+  userVerification?: 'required' | 'preferred' | 'discouraged'
+  attestationType?: 'direct' | 'enterprise' | 'none'
+}
+
+export class PasskeysService {
+  constructor(
+    private passkeyRepo: IMemberPasskeyRepository,
+    private config: PasskeysConfig
+  ) {}
+
+  public async generateRegistrationOptions(member: Member, session: SessionLike) {
+    const credentials = await this.passkeyRepo.findByMemberId(member.id)
+    const options = await generateRegistrationOptions({
+      rpName: this.config.rpName,
+      rpID: this.config.rpID,
+      userName: member.email,
+      userID: new TextEncoder().encode(member.id),
+      attestationType: this.config.attestationType ?? 'none',
+      timeout: this.config.timeout || 60000,
+      userDisplayName: member.name,
+      authenticatorSelection: {
+        userVerification: this.config.userVerification ?? 'preferred',
+      },
+      excludeCredentials: credentials.map((credential) => ({
+        id: credential.credentialId,
+        type: 'public-key',
+        transports: normalizeTransports(credential.transports),
+      })),
+    })
+
+    this.storeChallenge(session, SESSION_KEYS.registration, options.challenge)
+    return options
+  }
+
+  public async verifyRegistrationResponse(
+    member: Member,
+    response: RegistrationResponseJSON,
+    session: SessionLike,
+    displayName?: string
+  ) {
+    const challenge = this.requireChallenge(session, SESSION_KEYS.registration)
+
+    const verification = await verifyRegistrationResponse({
+      response,
+      expectedChallenge: challenge,
+      expectedOrigin: this.config.origin,
+      expectedRPID: this.config.rpID,
+      requireUserVerification: this.config.userVerification !== 'discouraged',
+    })
+
+    this.clearChallenge(session, SESSION_KEYS.registration)
+
+    if (!verification.verified || !verification.registrationInfo) {
+      throw new AuthenticationException('Passkey registration could not be verified.')
+    }
+
+    const { credential } = verification.registrationInfo
+
+    const passkey = MemberPasskey.create({
+      memberId: member.id,
+      credentialId: credential.id,
+      publicKey: Buffer.from(credential.publicKey).toString('base64'),
+      counter: credential.counter,
+      transports: credential.transports,
+      displayName,
+    })
+
+    await this.passkeyRepo.save(passkey)
+    return passkey
+  }
+
+  public async generateAuthenticationOptions(member: Member, session: SessionLike) {
+    const credentials = await this.passkeyRepo.findByMemberId(member.id)
+
+    const options = await generateAuthenticationOptions({
+      rpID: this.config.rpID,
+      timeout: this.config.timeout || 60000,
+      userVerification: this.config.userVerification ?? 'preferred',
+      allowCredentials: credentials.map((credential) => ({
+        id: credential.credentialId,
+        transports: normalizeTransports(credential.transports),
+      })),
+    })
+
+    this.storeChallenge(session, SESSION_KEYS.authentication, options.challenge)
+    return options
+  }
+
+  public async verifyAuthenticationResponse(
+    member: Member,
+    response: AuthenticationResponseJSON,
+    session: SessionLike
+  ) {
+    const challenge = this.requireChallenge(session, SESSION_KEYS.authentication)
+    const credential = await this.passkeyRepo.findByCredentialId(response.id)
+
+    if (!credential) {
+      throw new AuthenticationException('Passkey not registered.')
+    }
+
+    if (credential.memberId !== member.id) {
+      throw new AuthenticationException('Passkey does not belong to the member.')
+    }
+
+    const verification = await verifyAuthenticationResponse({
+      response,
+      expectedChallenge: challenge,
+      expectedOrigin: this.config.origin,
+      expectedRPID: this.config.rpID,
+      credential: buildWebAuthnCredential(credential),
+      requireUserVerification: this.config.userVerification !== 'discouraged',
+    })
+
+    this.clearChallenge(session, SESSION_KEYS.authentication)
+
+    if (!verification.verified) {
+      throw new AuthenticationException('Passkey authentication failed.')
+    }
+
+    credential.updateCounter(verification.authenticationInfo.newCounter)
+    await this.passkeyRepo.save(credential)
+    return credential
+  }
+
+  private storeChallenge(session: SessionLike, key: string, challenge: string) {
+    this.sessionGuard(session)
+    session.put(key, challenge)
+  }
+
+  private requireChallenge(session: SessionLike, key: string): string {
+    this.sessionGuard(session)
+    const challenge = session.get(key)
+    if (!challenge) {
+      throw new AuthenticationException('Passkey challenge is missing.')
+    }
+    return challenge
+  }
+
+  private clearChallenge(session: SessionLike, key: string) {
+    this.sessionGuard(session)
+    if (typeof session.forget === 'function') {
+      session.forget(key)
+    }
+  }
+
+  private sessionGuard(session: SessionLike) {
+    if (!session || typeof session.put !== 'function' || typeof session.get !== 'function') {
+      throw new AuthenticationException('Session store is required for Passkeys.')
+    }
+  }
+}
+
+function normalizeTransports(transports?: string[]): AuthenticatorTransportFuture[] | undefined {
+  return transports ? (transports as AuthenticatorTransportFuture[]) : undefined
+}
+
+function buildWebAuthnCredential(passkey: MemberPasskey): WebAuthnCredential {
+  const publicKey = Buffer.from(passkey.publicKey, 'base64')
+  return {
+    id: passkey.credentialId,
+    publicKey,
+    counter: passkey.counter,
+    transports: normalizeTransports(passkey.transports),
+  }
+}

package/src/Application/UseCases/ForgotPassword.ts

@@ -0,0 +1,34 @@
+import type { PlanetCore } from '@gravito/core'
+import { UseCase } from '@gravito/enterprise'
+import type { IMemberRepository } from '../../Domain/Contracts/IMemberRepository'
+
+export interface ForgotPasswordInput {
+  email: string
+}
+
+export class ForgotPassword extends UseCase<ForgotPasswordInput, void> {
+  constructor(
+    private repository: IMemberRepository,
+    private core: PlanetCore
+  ) {
+    super()
+  }
+
+  async execute(input: ForgotPasswordInput): Promise<void> {
+    const member = await this.repository.findByEmail(input.email)
+
+    if (!member) {
+      // Security: Don't reveal if user exists
+      return
+    }
+
+    member.generatePasswordResetToken()
+    await this.repository.save(member)
+
+    // Trigger hook to send reset email
+    await this.core.hooks.doAction('membership:send-reset-password', {
+      email: member.email,
+      token: member.passwordResetToken,
+    })
+  }
+}