@gravito/satellite-membership 0.1.1

package/.dockerignore

@@ -0,0 +1,8 @@
+node_modules
+dist
+.git
+.env
+*.log
+.vscode
+.idea
+tests

package/.env.example

@@ -0,0 +1,19 @@
+# Application
+APP_NAME="membership"
+APP_ENV=development
+APP_KEY=
+APP_DEBUG=true
+APP_URL=http://localhost:3000
+
+# Server
+PORT=3000
+
+# Database
+DB_CONNECTION=sqlite
+DB_DATABASE=database/database.sqlite
+
+# Cache
+CACHE_DRIVER=memory
+
+# Logging
+LOG_LEVEL=debug

package/ARCHITECTURE.md

@@ -0,0 +1,14 @@
+# membership Satellite Architecture
+
+This satellite follows the Gravito Satellite Specification v1.0.
+
+## Design
+- **DDD**: Domain logic is separated from framework concerns.
+- **Dogfooding**: Uses official Gravito modules (@gravito/atlas, @gravito/stasis).
+- **Decoupled**: Inter-satellite communication happens via Contracts and Events.
+
+## Layers
+- **Domain**: Pure business rules.
+- **Application**: Orchestration of domain tasks.
+- **Infrastructure**: Implementation of persistence and external services.
+- **Interface**: HTTP and Event entry points.

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# @gravito/satellite-membership
+
+## 0.1.1
+
+### Patch Changes
+
+- Updated dependencies
+  - @gravito/atlas@1.0.1
+  - @gravito/core@1.0.0
+  - @gravito/cosmos@1.0.0
+  - @gravito/enterprise@1.0.0
+  - @gravito/sentinel@1.0.0
+  - @gravito/signal@1.0.0
+  - @gravito/stasis@1.0.0

package/Dockerfile

@@ -0,0 +1,25 @@
+FROM oven/bun:1.0 AS base
+WORKDIR /usr/src/app
+
+# Install dependencies
+FROM base AS install
+RUN mkdir -p /temp/dev
+COPY package.json bun.lockb /temp/dev/
+RUN cd /temp/dev && bun install --frozen-lockfile
+
+# Build application
+FROM base AS build
+COPY --from=install /temp/dev/node_modules node_modules
+COPY . .
+ENV NODE_ENV=production
+RUN bun run build
+
+# Final production image
+FROM base AS release
+COPY --from=build /usr/src/app/dist/bootstrap.js index.js
+COPY --from=build /usr/src/app/package.json .
+
+# Create a non-root user for security
+USER bun
+EXPOSE 3000/tcp
+ENTRYPOINT [ "bun", "run", "index.js" ]

package/README.md

@@ -0,0 +1,112 @@
+# 🛰️ Gravito Membership Satellite
+
+這是 Gravito 生態系中的標準會員管理衛星模組（Satellite）。基於 **DDD (領域驅動設計)** 與 **Galaxy Architecture** 構建，專為高效能、高擴展性與 Bun 原生環境優化。
+
+## ✨ 核心功能
+
+- **身分驗證 (Auth)**: 整合 Sentinel 模組，支援 Session 登入與 **持久化 (Remember Me)**。
+- **註冊流程**: 包含自動生成驗證權杖與電子郵件發送 Hook。
+- **安全防護**:
+  - **多設備登入限制 (Single Device Login)**: 可開關功能，自動註冊並踢除舊裝置。
+  - **密碼安全**: 使用 Bun 原生加密，支援自動 Rehash。
+  - **Passkeys (WebAuthn)**: 內建 Passkeys 登錄 + 登入 API，可配合 `@simplewebauthn/browser` 與瀏覽器原生驗證器。
+- **美化郵件 (Beautiful Emails)**:
+  - 使用 Prism 模板引擎。
+  - 支援現代化 HTML 佈局。
+  - 完整多語系支持 (i18n)。
+- **動態 Metadata**: 會員實體支援無 Schema 的元數據擴展，適合電商、訂閱制等場景。
+
+## 🚀 快速開始
+
+... (內容省略) ...
+
+## 🛠️ 擴充與自定義 (DX Guide)
+
+想要自定義品牌、覆寫郵件樣式或增加業務邏輯？請參考我們的：
+👉 [**Membership 擴充與自定義指南 (EXTENDING.md)**](./docs/EXTENDING.md)
+
+想要使用 Passkeys？請參考：
+👉 [**Passkeys Integration Guide (PASSKEYS.md)**](./docs/PASSKEYS.md)
+
+## ⚙️ 配置選項
+
+在 `core` 配置中調整以下開關：
+
+```typescript
+{
+  membership: {
+    auth: {
+      // 是否限制帳號只能在單一裝置登入
+      single_device: true, 
+      // 是否啟用持久化登入 (Remember Me)
+      remember_me: true
+    },
+    branding: {
+      name: 'Your Project Name',
+      primary_color: '#3b82f6' // Tailwind Blue 500
+    }
+  },
+  app: {
+    url: 'https://yourapp.com'
+  }
+}
+```
+
+## 🎨 自定義模板
+
+本模組提供預設的郵件模板。如果您想更換設計，只需在您的專案中建立以下檔案，Prism 會優先使用您的檔案：
+
+- `views/emails/welcome.html`
+- `views/emails/reset_password.html`
+- `views/emails/level_changed.html`
+
+模板中可以使用 `{{ branding.name }}` 和 `{{ branding.color }}` 來保持一致性。
+
+本模組不強制綁定郵件驅動，而是透過 Hook 觸發動作。若您啟用了 `OrbitSignal`，本模組會自動處理以下 Hook：
+
+- `membership:send-verification`: 發送註冊驗證郵件。
+- `membership:send-reset-password`: 發送密碼重設郵件。
+- `membership:level-changed`: 當會員等級提升時發送慶祝郵件。
+
+## 📦 隊列整合 (Queue Integration)
+
+為了獲得最佳效能，建議掛載 `OrbitStream` 來啟用非同步發信。本模組已預設呼叫 `mail.queue()`。
+
+### 1. 安裝隊列軌道
+```typescript
+import { OrbitStream } from '@gravito/stream'
+
+await core.orbit(new OrbitStream({
+  default: 'redis',
+  connections: {
+    redis: { driver: 'redis', host: 'localhost' }
+  }
+}))
+```
+
+### 2. 運作原理
+- **有隊列時**: 郵件動作會被推入 `default` 隊列，API 請求會立即回傳。
+- **無隊列時**: 系統會自動降級為同步發送（Sync Send），確保功能不中斷。
+
+## 🛠️ API 使用範例
+
+### 會員註冊
+```typescript
+const register = container.make('membership.register')
+await register.execute({
+  name: 'Carl',
+  email: 'carl@example.com',
+  passwordPlain: 'secret123'
+})
+```
+
+### 多設備登入檢查 (Middleware)
+您可以將此中間件應用於敏感路由：
+```typescript
+import { verifySingleDevice } from '@gravito/satellite-membership/middleware'
+
+router.get('/profile', verifySingleDevice, (c) => { ... })
+```
+
+## 📄 授權
+MIT License

package/WHITEPAPER.md

@@ -0,0 +1,20 @@
+# Whitepaper: Gravito Membership Satellite (Identity Governance)
+**Version:** 1.0.0 | **Author:** Gravito Engineering Team
+
+## 1. Abstract
+Membership serves as the "Identity Anchor" managing the entire Customer Lifecycle.
+
+## 2. Deployment & Governance Scenarios
+
+### Case A: Tiered Marketing Synergy
+- **Scenario**: A user completes a purchase that pushes their lifetime spend over $10,000.
+- **Action**: Membership listens to the Commerce `commerce:order-placed` hook, upgrades the member to "Gold", and emits a `member:level-up` event.
+- **Outcome**: The Marketing satellite automatically unlocks a 20% discount for the next visit.
+
+### Case B: High-Security Compliance (Single Device)
+- **Scenario**: A fintech client requires that a user can only be logged in from one device at a time.
+- **Action**: Membership enables the `VerifySingleDevice` middleware, comparing the incoming session ID with the `current_session_id` stored in the domain entity.
+- **Outcome**: Fraudulent concurrent sessions are automatically terminated.
+
+---
+*Gravito Framework: Putting the Member at the Center of the Galaxy.*

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+import { ServiceProvider, Container } from '@gravito/core';
+
+/**
+ * Membership Satellite Service Provider
+ *
+ * Handles the registration and initialization of membership services.
+ * Optimized for Bun runtime with full i18n support.
+ */
+declare class MembershipServiceProvider extends ServiceProvider {
+    /**
+     * Register bindings in the container
+     */
+    register(container: Container): void;
+    /**
+     * Expose migration path using Bun-native __dirname
+     */
+    getMigrationsPath(): string;
+    /**
+     * Boot the satellite
+     * Loads local translations into the global i18n system.
+     */
+    boot(): Promise<void>;
+    private buildPasskeysConfig;
+}
+
+export { MembershipServiceProvider };