diff --git a/development-plan-and-collaboration-workflow.md b/development-plan-and-collaboration-workflow.md new file mode 100644 index 0000000..7d1e4e8 --- /dev/null +++ b/development-plan-and-collaboration-workflow.md @@ -0,0 +1,211 @@ +# Dolphin ID Development Plan and Collaboration Workflow + +| Field | Value | +| ----------------- | ------------------------------------------------------------- | +| Product | Dolphin ID | +| Repository | `git@github-zen:DolphinsLab/dolphin-id.git` | +| Package scope | `@dolphin-id/*` | +| Development model | Issue-driven development with PR-based continuous integration | +| Default branch | `main` | +| Document version | v1.0 | +| Last updated | 2026-06-01 | + +## 1. Development Principles + +Dolphin ID uses issue-driven development. Every feature, bug fix, security task, release task, and documentation task should start with an issue, move to a branch, and land through a pull request. + +Work should be split as tracer bullets: each issue should deliver a verifiable end-to-end capability whenever possible, not only one isolated layer. For example, an "EVM login slice" should cover adapter behavior, React hooks, backend verification, examples, and tests rather than being split into unrelated type, UI, and backend-only tasks. + +## 2. Branch Strategy + +| Branch | Purpose | Rule | +| ---------------------------- | -------------------- | ---------------------------------------------------------------------- | +| `main` | Stable trunk | Merge through PRs; direct pushes are discouraged. | +| `feature/DID-xxx-short-name` | Feature development | Maps to one feature issue. | +| `fix/DID-xxx-short-name` | Bug fix | Maps to one bug issue. | +| `docs/DID-xxx-short-name` | Documentation update | Maps to one docs issue. | +| `release/vx.y.z` | Release preparation | Only release fixes, documentation, versioning, and validation changes. | + +Branch examples: + +```text +feature/DID-004-evm-siwe-login +docs/DID-010-api-docs +fix/DID-009-nonce-replay +release/v0.1.0 +release/v1.0.0 +``` + +## 3. Issue Lifecycle + +```text +Backlog -> Ready -> In Progress -> In Review -> QA -> Done +``` + +| Status | Entry criteria | Exit criteria | +| ----------- | -------------------------------------- | --------------------------------------------------------- | +| Backlog | Requirement or idea has been recorded. | Scope, acceptance criteria, and dependencies are clear. | +| Ready | Issue can be picked up. | Development branch exists and implementation has started. | +| In Progress | Implementation is underway. | Pull request is opened. | +| In Review | PR is waiting for review. | Review passes and CI passes. | +| QA | Change is ready for validation. | Acceptance criteria pass. | +| Done | Change is merged. | Release notes or docs are synchronized when needed. | + +## 4. Pull Request Workflow + +1. Pull the latest `main`. +2. Pick one Ready issue. +3. Create the matching branch. +4. Implement code, tests, and documentation updates. +5. Open a pull request and link the issue. +6. Wait for CI to pass. +7. Require at least one review. Security, public API, and authentication changes should receive two reviews. +8. Prefer squash merge for feature PRs. +9. Close the issue after merge and update milestone state. + +PR title format: + +```text +DID-004: Implement EVM SIWE login slice +``` + +Commit message examples: + +```text +DID-004 implement EVM SIWE login slice +DID-009 harden nonce replay checks +``` + +## 5. Label System + +| Label | Meaning | +| ---------------- | -------------------------------------------- | +| `type:feature` | New feature | +| `type:bug` | Bug fix | +| `type:docs` | Documentation | +| `type:security` | Security-related work | +| `type:release` | Release preparation | +| `area:core` | Core abstractions, types, errors, and events | +| `area:react` | React provider, hooks, and state | +| `area:ui` | Default UI components | +| `area:adapter` | Chain adapters | +| `area:server` | Backend SDK and auth service | +| `area:examples` | Example applications | +| `area:dx` | CLI, docs site, and developer experience | +| `area:hosted` | Hosted nonce/session service | +| `priority:p0` | Required for MVP | +| `priority:p1` | Required for beta or v1.0 | +| `priority:p2` | Later iteration | +| `status:ready` | Ready to start | +| `status:blocked` | Blocked by dependency or decision | +| `slice:afk` | Can be completed independently | +| `slice:hitl` | Requires human review or product decision | + +## 6. Milestones + +### v0.1 MVP + +Goal: complete a runnable EVM + Sui multi-chain login loop with a self-hosted backend. + +Completed scope: + +- Repository, CI, package management, and release skeleton. +- `@dolphin-id/core` adapter contracts. +- `@dolphin-id/server` Node.js nonce, verification, and JWT sessions. +- EVM SIWE login loop. +- Sui personal-message login loop. +- React provider, hooks, and default connect UI. +- Next.js example and baseline E2E verification. +- MVP security hardening. +- API documentation and getting-started guide. + +Release artifact: `v0.1.0`. + +### v1.0 Stable + +Goal: deliver a production-ready open-source core with clear value-added hosted service boundaries. + +Completed scope: + +- WalletConnect-compatible EVM support and mobile deep links. +- Solana SIWS login loop. +- Multi-wallet identity model. +- Refresh tokens and force logout. +- Theming, i18n, and responsive UI improvements. +- Express/Fastify middleware. +- Bitcoin and Aptos adapters. +- Go, Rust, and Python server SDKs. +- Optional hosted nonce/session service primitives. +- CLI scaffolder. +- Docs site and third-party adapter development specification. +- Security audit remediation and v1.0 release checks. + +Release artifact: `v1.0.0`. + +### v1.x Future + +Potential follow-up scope: + +- TON, Cosmos, NEAR, and additional ecosystem adapters. +- EIP-1271 contract wallet verification. +- Hardware wallet support. +- Debug panel. +- Auth.js, Clerk, and other integration packages. + +## 7. Release Process + +1. Create `release/vx.y.z`. +2. Freeze features and accept only release blockers. +3. Run the full test matrix. +4. Update changelog, migration notes, release notes, and documentation. +5. Version packages and SDKs consistently. +6. Push the release branch. +7. Create and push the release tag. +8. Create the GitHub Release. +9. Close release issues and move unfinished work to the next milestone. + +The v0.1.0 and v1.0.0 releases have already been published through this process. + +## 8. Quality Gates + +Every PR should satisfy: + +- Unit tests pass. +- Type checks pass. +- Lint and format checks pass. +- Login, security, and session changes include negative tests. +- UI changes include mobile and desktop validation or reproducible verification notes. +- Public API changes update documentation. + +Release branches should additionally satisfy: + +- `pnpm typecheck` +- `pnpm test` +- `pnpm lint` +- `pnpm format:check` +- `pnpm build` +- SDK parity checks where applicable: + - `go test ./...` + - `cargo test` + - Python `pytest` + +## 9. Issue Publishing + +Local issue drafts live in [`docs/issues/README.md`](docs/issues/README.md). + +If GitHub CLI is installed and authenticated, run: + +```bash +./scripts/create-github-issues.sh +``` + +The script creates GitHub issues in dependency order. If a team uses another tracker, import `docs/issues/*.md` into that tracker and keep the same PR workflow. + +## 10. Current Repository State + +- Default branch: `main`. +- Stable releases: `v0.1.0` and `v1.0.0`. +- Release branches: `release/v0.1.0` and `release/v1.0.0`. +- Product packages: `@dolphin-id/*`. +- Public docs: repository `docs/` and `apps/docs`. +- Open-source core remains self-hostable; hosted auth is optional. diff --git a/multi-chain-web3-login-plugin-product-doc.md b/multi-chain-web3-login-plugin-product-doc.md new file mode 100644 index 0000000..6b67f8f --- /dev/null +++ b/multi-chain-web3-login-plugin-product-doc.md @@ -0,0 +1,550 @@ +# Multi-Chain Web3 Login Plugin Product Document + +| Field | Value | +| ----------------- | ----------------------------------------------------------------------------------- | +| Product code name | Dolphin ID | +| Document version | v1.0 | +| Document status | Released | +| Last updated | 2026-06-01 | +| Applies to | Product scope, architecture review, implementation planning, and release validation | + +## 1. Product Positioning + +Dolphin ID is multi-chain Web3 login infrastructure for the React ecosystem. It gives dApps a unified React API, chain adapters, SIWX message abstraction, server verification SDKs, and optional hosted nonce/session primitives so teams can support wallet connection, signature-based login, session management, and multi-wallet identity binding across EVM, Sui, Solana, Bitcoin, and Aptos. + +Dolphin ID does not custody wallets, manage private keys, construct transactions, or replace chain-specific business SDKs such as wagmi, Sui dApp Kit, or Solana Wallet Adapter. It focuses on one product problem: helping users log in to dApps safely, quickly, and consistently across chains. + +**One-line value proposition:** dApps can integrate multi-chain wallet login in hours instead of maintaining several wallet connection and signature verification stacks for weeks. + +## 2. Background and Problem + +Web3 applications are increasingly multi-chain, but the login layer remains fragmented: + +- Wallet discovery, address formats, signing payloads, and verification rules differ across EVM, Sui, Solana, Bitcoin, Aptos, and other ecosystems. +- Existing tools are often optimized for one ecosystem, such as EVM-first wallet kits, Sui-specific app kits, or Solana-specific adapters. +- Cross-chain dApps repeatedly rebuild connection UI, login state, error handling, and backend verification. +- Sign-In With Ethereum, Sign-In With Solana, Sui personal messages, and SIWX-style flows do not share one application-facing model. +- Hosted authentication vendors may create lock-in and may not cover non-EVM chains, headless UI needs, or self-hosted backends well. +- The "one user, many wallets" identity model lacks a small open-source reference implementation. + +Dolphin ID isolates chain differences inside adapters and presents developers with one consistent login surface. + +## 3. Goals and Non-Goals + +### 3.1 Business Goals + +- Reduce engineering cost for cross-chain wallet login. +- Provide a consistent login experience for EVM and non-EVM ecosystems. +- Support both "address as user" and "one identity with many wallets" models. +- Create an adapter ecosystem that lets third parties add new chain support. +- Preserve a complete self-hosted path while offering optional hosted value-add services. + +### 3.2 Product Goals + +- Provide a unified React provider, hooks, and default UI components. +- Provide chain-neutral SIWX message construction and verification contracts. +- Provide Node.js, Go, Rust, and Python server SDK coverage for core verification flows. +- Support headless mode for fully custom product UI. +- Keep the core package small and load chain capabilities only when requested. + +### 3.3 Non-Goals + +- Do not generate, custody, recover, or manage user private keys. +- Do not provide transaction construction, contract calls, asset transfers, or portfolio data services. +- Do not provide KYC, compliance screening, or real-world identity verification. +- Do not ship a full user profile system, social graph, points system, or CRM. +- Do not add Passkey/WebAuthn as a non-wallet fallback in the primary login path. + +### 3.4 Business Model + +Dolphin ID follows an **open-source core plus value-added services** model. + +The open-source core includes frontend SDKs, chain adapters, default UI, headless hooks, server verification SDKs, examples, self-hosted auth routes, adapter specifications, and test fixtures. Value-added services include hosted nonce/session infrastructure, enterprise SLAs, team management, audit logs, advanced risk controls, private deployment support, and priority chain integration support. + +The open-source path must remain complete and usable without any centralized service. Hosted services exist to reduce operational load and add enterprise capabilities, not to block self-hosted adoption. + +## 4. Target Users and Core Scenarios + +| User type | Typical context | Core need | +| ---------------------------- | ----------------------------------------- | ------------------------------------------------------------ | +| DeFi frontend developers | Expanding an existing single-chain dApp | Reuse login code and state management across chains | +| Cross-chain aggregator teams | Must support three or more chains | Unify wallet connection, signature login, and error handling | +| Consumer Web3 product teams | Care about conversion and UX | Provide a stable mobile-friendly connection flow | +| Multi-chain protocol teams | Protocol exists on EVM and non-EVM chains | Bind several on-chain accounts to one product identity | +| Open-source SDK developers | Need to add chains or custom UI | Rely on stable adapter and headless APIs | + +Core scenarios: + +- Cross-chain DEX aggregator: users connect EVM and Sui wallets in one interface and authenticate with the active chain. +- Multi-chain NFT marketplace: one identity binds several wallets for unified collections, orders, and permissions. +- Cross-chain lending protocol: users log in with an EVM wallet and manage assets or claims on another chain. +- AI agent platform: users authenticate once and authorize agent access to wallet contexts across chains. +- GameFi product: players use one account across assets and progression on several chains. + +## 5. Product Scope + +### 5.1 v0.1 MVP Scope + +The MVP completed the first multi-chain login loop: + +- EVM and Sui support. +- Browser wallet discovery, connection, disconnection, and account-change handling. +- SIWE and Sui personal-message login. +- Backend nonce issuance, signature verification, and JWT sessions. +- "Address as user" identity model. +- React provider, hooks, connect-wallet button, and wallet selection UI. +- Next.js example and Node.js backend reference implementation. +- MVP security hardening and getting-started documentation. + +### 5.2 v1.0 Stable Scope + +The v1.0 release completes production-ready coverage: + +- EVM, Sui, Solana, Bitcoin, and Aptos adapters. +- WalletConnect-compatible EVM provider support and mobile deep-link helpers. +- Multi-wallet identity binding, unbinding, primary-account selection, and default sensitive-operation policy. +- Refresh token rotation, session refresh, logout, and server-side invalidation. +- Express and Fastify middleware. +- CLI scaffolder for Next.js integrations. +- Hosted nonce/session service primitives with project API keys, allowed domains, quotas, billing hooks, and audit logs. +- Go, Rust, and Python server SDK parity checks. +- Documentation site, adapter specification, third-party adapter fixtures, migration guidance, and security audit summary. + +### 5.3 Post-v1.x Candidates + +- TON, Cosmos, NEAR, and additional ecosystem adapters. +- EIP-1271 contract wallet verification. +- Hardware wallet support. +- Debug panel for development mode. +- Auth.js, Clerk, and other authentication-system integration packages. + +## 6. Core Concepts + +| Concept | Description | +| ---------------- | ------------------------------------------------------------------------------------------------------------------------------ | +| ChainAdapter | A chain capability adapter responsible for wallet discovery, connection, signing, address normalization, and lifecycle events. | +| Wallet | A connectable wallet instance such as MetaMask, Phantom, Slush, or another chain wallet. | +| Account | A connected wallet account, including chain type, address, public key, wallet source, and metadata. | +| SIWX | A Sign-In With X abstraction covering SIWE, SIWS, Sui personal messages, Bitcoin/Aptos SIWX flows, and future login formats. | +| Identity | A product-level user identity, either represented by one address or by multiple bound accounts. | +| Session | The authenticated application session, backed by JWT and optional refresh/invalidation controls. | +| Adapter Registry | The set of enabled chain adapters used for wallet listing, connection routing, and capability lookup. | +| Hosted Auth | Optional managed nonce/session infrastructure built on top of the same open-source server primitives. | + +## 7. Product Architecture + +```text +dApp + ├─ React Provider / Hooks + ├─ UI Components + ├─ Adapter Registry + │ ├─ EVM Adapter + │ ├─ Sui Adapter + │ ├─ Solana Adapter + │ ├─ Bitcoin Adapter + │ └─ Aptos Adapter + └─ Auth Client + +Backend + ├─ Nonce Service + ├─ SIWX Verify Service + ├─ Identity Repository + ├─ Session Service + ├─ Middleware + └─ Optional Hosted Service +``` + +Package map: + +| Package | Purpose | +| ------------------------------------- | ----------------------------------------------------------------------------------------------------- | +| `@dolphin-id/core` | Core types, adapter contracts, SIWX abstractions, errors, events, and state model. | +| `@dolphin-id/react` | React provider, headless hooks, connection/login/session state. | +| `@dolphin-id/ui` | Default connect button, wallet modal, account display, themes, and i18n. | +| `@dolphin-id/adapter-evm` | EVM wallet discovery, WalletConnect-compatible provider support, SIWE message flow. | +| `@dolphin-id/adapter-sui` | Sui wallet discovery, personal-message payloads, and address normalization. | +| `@dolphin-id/adapter-solana` | Solana SIWS connection and signing flow. | +| `@dolphin-id/adapter-bitcoin` | Bitcoin P2PKH/secp256k1 SIWX flow. | +| `@dolphin-id/adapter-aptos` | Aptos Ed25519 SIWX flow. | +| `@dolphin-id/server` | Node.js nonce, verification, sessions, identity repositories, refresh/logout, and middleware helpers. | +| `@dolphin-id/hosted` | Hosted nonce/session service primitives. | +| `@dolphin-id/cli` | App scaffolder for runnable Next.js integrations. | +| `sdks/go`, `sdks/rust`, `sdks/python` | Server verification parity SDKs. | +| `apps/docs` | Public docs site and adapter development specification. | +| `examples/*` | Runnable examples and contract-tested third-party adapter sample. | + +## 8. Key User Flows + +### 8.1 Developer Integration Flow + +1. Install the core package, React package, UI package, server package, and required chain adapters. +2. Configure `DolphinProvider` at the application root. +3. Register enabled adapters such as EVM, Sui, Solana, Bitcoin, or Aptos. +4. Configure auth endpoints such as `/auth/nonce`, `/auth/verify`, `/auth/me`, `/auth/refresh`, and `/auth/logout`. +5. Use the default `ConnectButton` or build custom UI with headless hooks. +6. Wire `@dolphin-id/server` or a parity SDK into the backend for nonce management, verification, sessions, and identity persistence. + +### 8.2 End-User Login Flow + +1. The user clicks Connect Wallet. +2. The frontend shows wallets grouped by chain. +3. The user selects a wallet and confirms connection. +4. The frontend requests a backend-issued nonce. +5. The frontend builds a SIWX message and asks the wallet to sign it. +6. The frontend submits chain type, address, message, and signature to the backend. +7. The backend verifies domain, address, chain ID, nonce, timestamps, and signature. +8. The backend consumes the nonce, creates or loads the identity, and issues a session. +9. The frontend stores the session according to configuration and updates login state. + +### 8.3 Refresh and Logout Flow + +1. The application stores a session token and, when configured, a refresh token. +2. The SDK can refresh the session inside the allowed refresh window. +3. The user or server can log out and invalidate the current session. +4. Server-side invalidation versions make previously issued sessions fail validation. +5. React state moves through refreshable, authenticated, unauthenticated, and logged-out states. + +### 8.4 Multi-Wallet Binding Flow + +1. The user signs in with a primary wallet. +2. The user chooses to bind another wallet. +3. The new wallet connects. +4. The backend issues a binding-purpose nonce. +5. The new wallet signs an ownership message. +6. The backend verifies the signature and confirms the account is not owned by another identity. +7. The backend binds the account to the current identity. + +By default, sensitive operations may be authorized by any wallet already bound to the identity. Applications that need stricter rules can require the primary wallet or a chain-specific wallet. + +## 9. Functional Requirements + +### 9.1 Chain Support + +| ID | Requirement | Priority | Acceptance criteria | +| ----- | ----------------------- | -------- | --------------------------------------------------------------------------------------------- | +| CS-01 | EVM login | P0 | Supports configurable EVM chain IDs such as Ethereum, Polygon, Base, and Arbitrum. | +| CS-02 | Sui login | P0 | Discovers Sui wallets, connects accounts, and completes personal-message signing. | +| CS-03 | Multi-chain registry | P0 | One app can enable several chains and distinguish accounts by chain type. | +| CS-04 | Adapter development API | P1 | Third parties can implement wallet discovery, connection, signing, and address normalization. | +| CS-05 | Solana login | P1 | Supports SIWS signing and server verification. | +| CS-06 | Bitcoin and Aptos login | P1 | Supports SIWX message creation and verification for both ecosystems. | +| CS-07 | Future chain expansion | P2 | New chains can be added without changing the core login flow. | + +### 9.2 Wallet Connection + +| ID | Requirement | Priority | Acceptance criteria | +| ----- | ------------------------------------- | -------- | ------------------------------------------------------------------------------------------------ | +| WC-01 | Browser wallet discovery | P0 | EVM supports injected/EIP-6963-style discovery and Sui supports Wallet Standard-style discovery. | +| WC-02 | Wallet list API | P0 | Wallets can be filtered by chain type, install state, name, and capabilities. | +| WC-03 | Connect and disconnect | P0 | Hooks expose connecting, connected, failed, and disconnected states. | +| WC-04 | Wallet event handling | P0 | Account changes, chain changes, and disconnect events are normalized. | +| WC-05 | Restore after refresh | P0 | The SDK restores wallet/session state after page reload when possible. | +| WC-06 | Custom RPC support | P0 | Chain adapters can be configured with application-specific RPC endpoints. | +| WC-07 | WalletConnect-compatible EVM provider | P1 | Mobile EVM login can be routed through compatible provider and deep-link helpers. | +| WC-08 | Missing wallet guidance | P1 | UI can show install guidance for unavailable wallets. | +| WC-09 | Mobile deep links | P1 | Mobile browser flows can return from wallet apps and restore session state. | +| WC-10 | Hardware wallets | P2 | Ledger/Trezor paths can be added later through adapter capabilities. | + +### 9.3 Authentication + +| ID | Requirement | Priority | Acceptance criteria | +| ----- | --------------------------- | -------- | ------------------------------------------------------------------------------------------------- | +| AU-01 | SIWX message builder | P0 | Same inputs produce a chain-adapted login message. | +| AU-02 | EIP-4361 SIWE compatibility | P0 | EVM login messages can be verified using SIWE-compatible semantics. | +| AU-03 | Sui personal messages | P0 | Sui wallets sign and backend verification confirms ownership. | +| AU-04 | Backend-issued nonce | P0 | The frontend cannot self-issue trusted nonces. | +| AU-05 | Complete message fields | P0 | Messages include domain, address, chain type, chain ID, nonce, URI, issuedAt, and expirationTime. | +| AU-06 | Server verification SDK | P0 | Node.js verifies EVM, Sui, Solana, Bitcoin, and Aptos login signatures. | +| AU-07 | Single-use nonce | P0 | A nonce cannot be reused after success, expiry, or invalidation. | +| AU-08 | Solana SIWS | P1 | Solana login uses the documented SIWS path. | +| AU-09 | EIP-1271 contract wallets | P2 | Contract wallet verification can be added with chain-level checks. | + +### 9.4 Identity + +| ID | Requirement | Priority | Acceptance criteria | +| ----- | -------------------------- | -------- | ------------------------------------------------------------------------------------------------------------ | +| ID-01 | Address as user | P0 | First login creates an identity from chain type and normalized address. | +| ID-02 | Global account uniqueness | P0 | One chain/account pair cannot belong to multiple identities. | +| ID-03 | Address normalization | P0 | EVM, Sui, Solana, Bitcoin, and Aptos addresses are normalized by their adapters and revalidated server-side. | +| ID-04 | One identity, many wallets | P1 | One identity can bind several accounts. | +| ID-05 | Signed binding | P1 | A newly bound wallet must prove ownership by signing. | +| ID-06 | Account unbinding | P1 | A user can unbind any non-final wallet. | +| ID-07 | Primary account | P1 | A multi-wallet identity can choose a primary account. | + +### 9.5 Session Management + +| ID | Requirement | Priority | Acceptance criteria | +| ----- | -------------------------- | -------- | --------------------------------------------------------------------------------------------- | +| SE-01 | JWT sessions | P0 | Successful verification issues a JWT session. | +| SE-02 | Configurable expiry | P0 | Default expiry is seven days and can be overridden. | +| SE-03 | Configurable token storage | P0 | Local storage, memory, and cookie-oriented flows are supported by examples and configuration. | +| SE-04 | Session hook | P0 | React hooks expose current user, session, loading, refresh, and logged-out states. | +| SE-05 | Refresh tokens | P1 | Sessions can be renewed within a configured refresh window. | +| SE-06 | Server-side invalidation | P1 | Tokens can be invalidated through per-subject versions or equivalent application storage. | +| SE-07 | Disconnect policy | P1 | Applications can decide whether wallet disconnect clears the session. | + +### 9.6 UI Components + +| ID | Requirement | Priority | Acceptance criteria | +| ----- | -------------------------- | -------- | ------------------------------------------------------------------------ | +| UI-01 | Connect wallet button | P0 | Shows disconnected, connecting, connected, and error states. | +| UI-02 | Wallet selection modal | P0 | Groups wallets by chain and shows install/connect state. | +| UI-03 | Account display | P0 | Shows shortened address, chain identity, and disconnect action. | +| UI-04 | Light and dark theme | P0 | Can follow system theme or be manually configured. | +| UI-05 | Headless mode | P0 | Hooks cover the full connection and login flow without default UI. | +| UI-06 | Responsive layout | P0 | Mobile modal and desktop surfaces avoid overflow and remain usable. | +| UI-07 | Theme customization | P1 | Supports theme variables such as color, typography, spacing, and radius. | +| UI-08 | English and Chinese i18n | P1 | Ships `en-US` and `zh-CN` copy sets. | +| UI-09 | Multi-wallet management UI | P2 | Future UI can expose bind, unbind, and primary-account controls. | + +### 9.7 Developer Experience + +| ID | Requirement | Priority | Acceptance criteria | +| ----- | ------------------------- | -------- | ---------------------------------------------------------------------------------------------- | +| DX-01 | Complete TypeScript types | P0 | Public APIs avoid implicit `any`. | +| DX-02 | API documentation | P0 | Provider, hooks, components, server SDK, hosted service, and adapter contracts are documented. | +| DX-03 | Examples | P0 | Next.js, basic integration, and third-party adapter examples are available. | +| DX-04 | Actionable errors | P0 | Errors include code, stage, recoverability, and context. | +| DX-05 | SSR support | P0 | Next.js App Router usage avoids hydration errors. | +| DX-06 | No centralized dependency | P0 | Self-hosted auth works without hosted services. | +| DX-07 | CLI scaffolder | P1 | Developers can generate runnable starter apps. | +| DX-08 | Debug panel | P2 | Development-mode diagnostics can be added later. | + +### 9.8 Backend SDKs + +| ID | Requirement | Priority | Acceptance criteria | +| ----- | ----------------------------- | -------- | ------------------------------------------------------------------------------------------------ | +| BE-01 | Node.js verification SDK | P0 | Supports EVM, Sui, Solana, Bitcoin, and Aptos verification helpers. | +| BE-02 | Nonce management | P0 | Provides in-memory primitives and production-oriented storage contracts. | +| BE-03 | Reference auth routes | P0 | Examples include `/auth/nonce`, `/auth/verify`, `/auth/me`, `/auth/refresh`, and `/auth/logout`. | +| BE-04 | Custom identity repository | P0 | Applications can connect their own database. | +| BE-05 | Next.js route handler example | P0 | Example can run end to end. | +| BE-06 | Express/Fastify middleware | P1 | Common Node web frameworks can protect routes quickly. | +| BE-07 | Go/Rust/Python SDKs | P1 | v1.0 SDKs pass shared fixture parity checks. | +| BE-08 | Hosted nonce/session service | P1 | Optional hosted primitives do not block self-hosted usage. | + +## 10. Core API Shape + +### 10.1 Frontend Provider + +```tsx + + + +``` + +### 10.2 React Hooks + +| Hook | Purpose | +| --------------------- | ---------------------------------- | +| `useWallets()` | Read available wallet list. | +| `useConnect()` | Connect a selected wallet. | +| `useDisconnect()` | Disconnect a wallet. | +| `useAccounts()` | Read connected accounts. | +| `useSignIn()` | Start a SIWX signature login. | +| `useSession()` | Read session and user identity. | +| `useChainAdapters()` | Read enabled chain capabilities. | +| `useRefreshSession()` | Refresh a session when configured. | + +### 10.3 Backend Endpoints + +| Endpoint | Method | Purpose | +| ------------------------ | -------- | ------------------------------------------------------------- | +| `/auth/nonce` | `POST` | Issue a single-use nonce for domain, chain type, and address. | +| `/auth/verify` | `POST` | Verify SIWX message/signature and issue a session. | +| `/auth/me` | `GET` | Return the current authenticated user. | +| `/auth/refresh` | `POST` | Rotate/refresh the current session when allowed. | +| `/auth/logout` | `POST` | Clear or invalidate the current session. | +| `/identity/accounts` | `GET` | List bound wallet accounts. | +| `/identity/accounts` | `POST` | Bind a new wallet account. | +| `/identity/accounts/:id` | `DELETE` | Unbind an account when allowed. | + +## 11. Data Model Draft + +### 11.1 Account + +```ts +type ChainType = "evm" | "sui" | "solana" | "bitcoin" | "aptos" | "ton"; + +type Account = { + id: string; + identityId: string; + chainType: ChainType; + chainId?: string | number; + address: string; + publicKey?: string; + walletName?: string; + isPrimary: boolean; + createdAt: string; + updatedAt: string; +}; +``` + +### 11.2 Identity + +```ts +type Identity = { + id: string; + primaryAccountId: string; + accounts: Account[]; + createdAt: string; + updatedAt: string; +}; +``` + +### 11.3 SIWX Message + +```ts +type SIWXMessage = { + domain: string; + address: string; + chainType: ChainType; + chainId?: string | number; + uri: string; + version: string; + nonce: string; + issuedAt: string; + expirationTime: string; + statement?: string; +}; +``` + +## 12. Security Requirements + +- Signed messages must include `domain`, and the backend must verify it against the current service. +- Nonces must be generated by the backend, be random, expire, and be single-use. +- Verification must check address, chain ID, domain, nonce, issuedAt, expirationTime, and signature validity. +- Nonces must be consumed immediately after successful verification. +- Failed verification attempts should be rate-limited by the application or hosting layer. +- JWT signing secrets must meet strength requirements; weak secrets should fail startup or produce a strong warning. +- Cookie mode must support HttpOnly, Secure, SameSite, and CSRF protection where needed. +- Local development may use HTTP; production defaults should require HTTPS. +- Address normalization must run server-side and must not rely only on frontend input. +- Authentication errors should avoid leaking sensitive details in production. +- The v1.0 security audit summary must be linked from release notes. + +## 13. Non-Functional Requirements + +| Category | Target | +| --------------------- | ------------------------------------------------------------------------------------ | +| Core bundle size | Keep core small and adapter-free. | +| Adapter bundle size | Keep chain adapters independently importable. | +| Wallet modal response | Show wallet selection within 300 ms after user click under normal conditions. | +| Login completion | Establish session within 1.5 s after user signature under normal network conditions. | +| React support | React 18+ and React 19. | +| Framework support | Next.js first, with Vite/Remix/TanStack Start support through headless APIs. | +| Browser support | Latest two major versions of Chrome, Safari, Firefox, and Edge. | +| Mobile support | iOS Safari 15+ and recent Android Chrome. | +| Node.js support | Node.js 18+. | +| Test coverage | Core security and login behavior must have negative tests. | +| Versioning | Public APIs follow SemVer and breaking changes require migration notes. | + +## 14. Release Acceptance + +### v0.1 MVP + +- Next.js example enables EVM and Sui. +- EVM wallet login completes connection, signing, verification, JWT issue, and refresh restore. +- Sui wallet login completes connection, signing, verification, JWT issue, and refresh restore. +- Backend nonces expire and are single-use. +- Frontend handles rejected signatures, missing wallets, account changes, wallet disconnect, and session expiry. +- Default UI works on desktop and mobile with light/dark themes. +- Headless hooks can complete the same flow without default UI. +- Documentation includes integration steps, API reference, security notes, and examples. + +### v1.0 Stable + +- EVM, Sui, Solana, Bitcoin, and Aptos adapters are available. +- Refresh/logout and server-side invalidation are implemented. +- Multi-wallet identity binding is implemented. +- Express/Fastify middleware is available. +- Hosted nonce/session primitives are available as optional value-add services. +- CLI scaffolder is available. +- Docs site and third-party adapter specification are available. +- Go, Rust, and Python SDK fixture parity tests pass. +- Security audit remediation and release notes are published. + +## 15. Roadmap + +### v0.1 MVP + +Completed by release `v0.1.0`. + +- Core adapter contracts. +- EVM and Sui adapters. +- SIWX message creation. +- Node.js verification SDK. +- React provider and headless hooks. +- Default connect UI. +- Address-as-user identity. +- JWT sessions. +- Next.js example and E2E verification. + +### v1.0 Stable + +Completed by release `v1.0.0`. + +- Solana, Bitcoin, and Aptos adapters. +- WalletConnect-compatible EVM support and mobile deep links. +- Multi-wallet identity model. +- Refresh tokens and force logout. +- Express/Fastify middleware. +- CLI scaffolder. +- Documentation site. +- Third-party adapter specification. +- Go, Rust, and Python server SDKs. +- Hosted nonce/session service primitives. +- Security audit remediation. +- Migration guidance and stable release notes. + +### v1.x Future + +- TON, Cosmos, and NEAR adapters. +- EIP-1271 contract wallet support. +- Hardware wallet support. +- Debug panel. +- Auth.js, Clerk, and other integration plugins. + +## 16. Success Metrics + +| Metric | Target | +| ----------------------- | ------------------------------------------------------------------------ | +| First integration time | Developers can complete example login within 30 minutes. | +| Example success rate | New users following docs succeed at least 90% of the time. | +| Login success rate | At least 95% in normal wallet environments. | +| Documentation coverage | P0 APIs and flows have examples. | +| Adapter extension cost | Adding a new chain does not require changes to the core login flow. | +| Hosted service adoption | Hosted nonce/session can be enabled, billed, and disabled independently. | +| Package discipline | Core remains small and chain capabilities remain separately importable. | + +## 17. Risks and Mitigations + +| Risk | Impact | Mitigation | +| ---------------------------------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------- | +| Wallet standards differ across chains | Adapter complexity rises | Keep core contracts minimal and isolate chain details in adapters. | +| WalletConnect or wallet standards change | Mobile connection instability | Pin major versions and maintain compatibility tests. | +| Browser wallet injection timing differs under SSR | Hydration issues or flickering state | Delay browser API access and document SSR usage. | +| Differentiation from hosted auth products is unclear | Developer adoption becomes harder | Focus on open-source core, self-hosting, non-EVM coverage, headless APIs, and optional hosted value-add. | +| Multi-wallet identity becomes too complex | Delivery risk | Keep defaults simple and allow application-specific policy overrides. | +| Verification details are easy to miss | Replay or phishing risks | Strong server defaults, negative tests, and security audit checklist. | + +## 18. Product Decisions + +| Question | Decision | Impact | +| ------------------------------------------------------------------- | ------------------------------------------ | ---------------------------------------------------------------------------- | +| Should v1.0 include Go, Rust, and Python server SDKs? | Yes | v1.0 includes multi-language backend parity SDKs. | +| Should Dolphin ID provide hosted nonce/session services? | Yes | Hosted auth is optional and does not block self-hosting. | +| How should sensitive operations be authorized in multi-wallet mode? | Any bound wallet by default | Applications can override with stricter policies. | +| Should Passkey/WebAuthn be added as a non-wallet fallback? | No | The primary login path remains wallet signature based. | +| What is the business model? | Open-source core plus value-added services | Core SDK remains complete; hosted/enterprise features can be commercialized. | +| Are product name and package scope final? | Yes | Product name is Dolphin ID and packages use `@dolphin-id/*`. | diff --git "a/\345\244\232\351\223\276Web3\347\224\250\346\210\267\347\231\273\345\275\225\346\217\222\344\273\266\344\272\247\345\223\201\346\226\207\346\241\243.md" "b/\345\244\232\351\223\276Web3\347\224\250\346\210\267\347\231\273\345\275\225\346\217\222\344\273\266\344\272\247\345\223\201\346\226\207\346\241\243.md" deleted file mode 100644 index ea04101..0000000 --- "a/\345\244\232\351\223\276Web3\347\224\250\346\210\267\347\231\273\345\275\225\346\217\222\344\273\266\344\272\247\345\223\201\346\226\207\346\241\243.md" +++ /dev/null @@ -1,515 +0,0 @@ -# 多链 Web3 用户登录插件产品文档 - -| 项目 | 内容 | -| -------- | ---------------------------- | -| 产品代号 | Dolphin ID | -| 文档版本 | v1.1 | -| 文档状态 | 待评审 | -| 最后更新 | 2026-05-30 | -| 适用阶段 | MVP 立项、研发排期、方案评审 | - -## 1. 产品定位 - -Dolphin ID 是面向 React 生态的多链 Web3 登录基础设施。它通过统一的前端 React API、链适配器、SIWX 登录消息抽象和后端验签 SDK，帮助 dApp 在同一套代码中支持 EVM、Sui、Solana 等多条链的钱包连接、签名登录、会话管理和多钱包身份绑定。 - -产品不做钱包托管、不管理私钥、不构造交易，也不替代 wagmi、Sui dApp Kit、Solana Wallet Adapter 等链上业务 SDK。它专注解决“用户如何安全、快速、跨链地登录 dApp”。 - -**一句话价值：让 dApp 用 30 分钟接入多链登录，而不是用数周维护多套钱包连接和验签逻辑。** - -## 2. 背景与问题 - -Web3 应用正在从单链走向多链，但登录层仍高度碎片化： - -- EVM、Sui、Solana、Bitcoin 等生态的钱包发现、地址格式、签名消息、验签方式差异明显。 -- 现有工具通常绑定单一生态，例如 RainbowKit/wagmi 偏 EVM，Sui dApp Kit 偏 Sui，Solana Wallet Adapter 偏 Solana。 -- 跨链 dApp 需要重复维护多套连接 UI、登录状态、错误处理和后端验签逻辑。 -- Sign-In With Ethereum、Sign-In With Solana、Sui Personal Message 等登录标准不统一，后端身份系统难以复用。 -- SaaS 化跨链登录方案可能带来供应商锁定，且对非 EVM 链覆盖、Headless 集成和自有后端接入不一定友好。 -- “一个用户绑定多个链上钱包”的身份模型缺乏轻量、开源、可落地的参考实现。 - -因此，市场需要一个轻量、可扩展、开源友好的多链登录层，把链差异隔离到 Adapter 中，把应用开发者面对的登录体验统一起来。 - -## 3. 产品目标 - -### 3.1 业务目标 - -- 降低跨链 dApp 接入钱包登录的研发成本。 -- 为 EVM 与非 EVM 链提供一致的登录体验。 -- 建立“地址即用户”和“一人多钱包”两种身份模型的标准实现。 -- 形成可扩展的 Adapter 生态，允许第三方贡献新链支持。 - -### 3.2 产品目标 - -- 提供统一的 React Provider、Hooks 和 UI 组件。 -- 提供链无关的 SIWX 登录消息构造与验签接口。 -- 提供 Node.js/TypeScript 后端 SDK，覆盖 nonce、验签、会话、用户绑定等关键链路。 -- 支持 Headless 模式，允许产品完全自定义 UI。 -- 核心包保持轻量，链能力按需引入。 - -### 3.3 非目标 - -- 不生成、托管或恢复用户私钥。 -- 不提供交易构造、合约调用、资产转账等链上业务能力。 -- 不提供 KYC、合规审查或真实身份认证。 -- 不做链上数据索引、余额聚合、NFT 聚合等数据服务。 -- 不内置完整用户资料系统，例如头像、社交关系、积分体系。 -- 不引入 Passkey/WebAuthn 作为非钱包兜底登录方式，产品登录主路径保持钱包签名。 - -### 3.4 商业模式 - -Dolphin ID 采用“开源核心 + 增值服务”的商业模式。 - -开源核心包括前端 SDK、链 Adapter、默认 UI、Headless Hooks、后端验签 SDK、基础示例和自托管认证参考实现。增值服务包括托管 nonce/session 服务、企业级 SLA、团队管理、审计日志、高级风控、私有化部署支持和优先链适配支持。 - -开源版本必须保持完整可用，开发者不接入任何中心化服务也能完成多链登录闭环；增值服务只用于降低运维成本、增强企业能力和提供托管便利。 - -## 4. 目标用户与核心场景 - -| 用户类型 | 典型特征 | 核心诉求 | -| ------------------- | ----------------------------- | -------------------------------------- | -| DeFi 协议前端开发者 | 已有单链 dApp，希望扩展到新链 | 尽量复用现有登录代码和状态管理 | -| 跨链聚合器开发者 | 必须同时支持 3 条以上链 | 统一钱包连接、签名登录与错误处理 | -| C 端 Web3 产品团队 | 重视登录转化率和用户体验 | 提供简单、稳定、移动端友好的连接流程 | -| 多链协议团队 | 协议部署在 EVM 与非 EVM 链 | 让一个用户身份关联多个链上账户 | -| 开源 SDK 开发者 | 需要扩展链支持或自定义 UI | 需要稳定的 Adapter 规范和 Headless API | - -核心使用场景： - -- 跨链 DEX 聚合器：用户在同一界面连接 EVM 与 Sui 钱包，并基于当前链完成登录。 -- 多链 NFT 市场：一个用户身份绑定多个链上钱包，统一管理收藏、订单和权限。 -- 跨链借贷协议：用户用 EVM 钱包登录和抵押，用 Sui 钱包接收或管理资产。 -- AI Agent 平台：用户登录后授权 Agent 管理不同链的钱包上下文。 -- GameFi 产品：玩家使用统一账号访问多条链上的资产和游戏进度。 - -## 5. 产品范围 - -### 5.1 MVP 范围 - -MVP 只解决“多链登录闭环”： - -- 支持 EVM 与 Sui。 -- 支持浏览器钱包发现、连接、断开、账户变化监听。 -- 支持 SIWE 与 Sui Personal Message 登录。 -- 支持后端 nonce 下发、验签、JWT 会话。 -- 支持“地址即用户”身份模型。 -- 提供 React Provider、Hooks、Connect Wallet 按钮和钱包选择弹窗。 -- 提供 Next.js 示例和 Node.js 后端参考实现。 - -### 5.2 MVP 暂不包含 - -- Solana、Bitcoin、Aptos、TON 等更多链。 -- 一人多钱包绑定管理 UI。 -- Refresh Token、Token 黑名单、强制注销。 -- 硬件钱包。 -- Debug Panel。 -- CLI 脚手架。 -- 托管认证服务。 - -## 6. 核心概念 - -| 概念 | 说明 | -| ---------------- | ------------------------------------------------------------------------------------- | -| ChainAdapter | 单条链的能力适配器，负责钱包发现、连接、签名、地址规范化和事件监听 | -| Wallet | 一个可连接的钱包实例，例如 MetaMask、Phantom、Slush | -| Account | 已连接的钱包账户，包含链类型、地址、公钥、钱包来源等信息 | -| SIWX | Sign-In With X 的通用抽象，用统一接口覆盖 SIWE、SIWS、Sui Personal Message 等登录消息 | -| Identity | 产品内的用户身份，可以是单地址身份，也可以绑定多个不同链上的账户 | -| Session | 登录会话，MVP 默认使用 JWT | -| Adapter Registry | 应用启用的链适配器集合，用于钱包列表展示、连接和能力路由 | - -## 7. 产品架构 - -产品由前端 SDK、链 Adapter、UI 组件、后端 SDK 和示例工程组成。 - -```text -dApp - ├─ React Provider / Hooks - ├─ UI Components - ├─ Adapter Registry - │ ├─ EVM Adapter - │ ├─ Sui Adapter - │ └─ Future Adapters - └─ Auth Client - -Backend - ├─ Nonce Service - ├─ SIWX Verify Service - ├─ User Repository - └─ Session Service -``` - -建议包结构： - -| 包名 | 说明 | -| ------------------------- | ------------------------------------------- | -| `@dolphin-id/core` | 核心类型、Adapter 接口、SIWX 抽象、错误模型 | -| `@dolphin-id/react` | React Provider、Hooks、状态管理 | -| `@dolphin-id/ui` | 默认按钮、钱包弹窗、账户状态组件 | -| `@dolphin-id/adapter-evm` | EVM 钱包发现、连接、SIWE 消息适配 | -| `@dolphin-id/adapter-sui` | Sui 钱包发现、连接、Personal Message 适配 | -| `@dolphin-id/server` | Node.js 验签、nonce、session、用户仓储接口 | -| `@dolphin-id/examples` | Next.js、Vite、多链示例 | - -## 8. 关键用户流程 - -### 8.1 开发者接入流程 - -1. 安装核心包、React 包、UI 包和所需链 Adapter。 -2. 在应用根节点配置 `DolphinProvider`。 -3. 注册启用的 Adapter，例如 EVM 与 Sui。 -4. 配置认证端点，例如 `/auth/nonce`、`/auth/verify`、`/auth/me`。 -5. 使用默认 `ConnectButton`，或通过 Hooks 自定义钱包连接 UI。 -6. 后端接入 `@dolphin-id/server` 完成 nonce 管理、验签和 session 签发。 - -### 8.2 用户登录流程 - -1. 用户点击 Connect Wallet。 -2. 前端展示按链分组的钱包列表。 -3. 用户选择钱包并确认连接。 -4. 前端向后端请求 nonce。 -5. 前端构造 SIWX 消息并调用钱包签名。 -6. 前端提交地址、链类型、消息和签名到后端。 -7. 后端校验 domain、address、chainId、nonce、过期时间和签名有效性。 -8. 后端销毁 nonce，创建或查询用户身份，签发 session。 -9. 前端保存 session 并更新登录状态。 - -### 8.3 断线重连流程 - -1. 页面刷新后，SDK 读取持久化的钱包连接状态和 session。 -2. SDK 尝试恢复钱包连接状态。 -3. SDK 调用 `/auth/me` 校验 session 是否仍有效。 -4. 若钱包仍连接且 session 有效，则恢复登录状态。 -5. 若钱包连接失败或 session 过期，则进入未登录状态，并给出可恢复的错误信息。 - -### 8.4 多钱包绑定流程 - -该流程属于 P1。 - -1. 用户已通过主钱包登录。 -2. 用户选择绑定新钱包。 -3. 新钱包完成连接。 -4. 后端下发绑定用途 nonce。 -5. 新钱包完成 SIWX 所有权签名。 -6. 后端校验签名，并确认该地址未绑定其他用户。 -7. 后端将新 Account 绑定到当前 Identity。 - -多钱包模式下，敏感操作默认允许当前 Identity 下任意已绑定钱包完成签名授权。业务方如需更高安全级别，可在应用层配置只允许主钱包签名或要求特定链钱包签名，但产品默认策略为任意绑定钱包签名。 - -## 9. 功能需求 - -### 9.1 链支持 - -| 编号 | 需求 | 优先级 | 验收标准 | -| ----- | ------------------------- | ------ | ------------------------------------------------------------------- | -| CS-01 | 支持 EVM 全系链登录 | P0 | 可通过配置 chainId 支持 Ethereum、Polygon、Base、Arbitrum 等 EVM 链 | -| CS-02 | 支持 Sui 主网和测试网登录 | P0 | 可发现 Sui 钱包、连接账户并完成 Personal Message 签名 | -| CS-03 | 同一应用可同时启用多条链 | P0 | 钱包弹窗能按链展示，Hooks 能区分链类型和账户 | -| CS-04 | 提供 Adapter 开发接口 | P1 | 第三方可按文档实现新链的钱包发现、连接、签名和地址规范化 | -| CS-05 | 支持 Solana | P1 | 可通过 Solana 钱包完成 SIWS 登录 | -| CS-06 | 支持 Bitcoin、Aptos、TON | P2 | 按 Adapter 规范逐步扩展 | - -### 9.2 钱包连接 - -| 编号 | 需求 | 优先级 | 验收标准 | -| ----- | ------------------ | ------ | -------------------------------------------- | -| WC-01 | 自动发现浏览器钱包 | P0 | EVM 支持 EIP-6963，Sui 支持 Wallet Standard | -| WC-02 | 钱包列表 API | P0 | 可按链类型、安装状态、钱包名称筛选 | -| WC-03 | 钱包连接与断开 | P0 | Hooks 能返回连接中、已连接、失败、断开等状态 | -| WC-04 | 钱包事件监听 | P0 | 能监听账户切换、链切换、断开连接 | -| WC-05 | 刷新页面后恢复状态 | P0 | 用户刷新后可恢复已连接钱包和有效 session | -| WC-06 | 支持自定义 RPC | P0 | EVM 和 Sui Adapter 均可配置 RPC 节点 | -| WC-07 | WalletConnect v2 | P0 | 移动端钱包可通过 WalletConnect 登录 EVM | -| WC-08 | 钱包未安装引导 | P1 | 未安装钱包时展示官方下载入口 | -| WC-09 | 移动端深链唤起 | P1 | 手机浏览器中可直接唤起钱包 App | -| WC-10 | 硬件钱包 | P2 | 支持 Ledger/Trezor 连接路径 | - -### 9.3 登录认证 - -| 编号 | 需求 | 优先级 | 验收标准 | -| ----- | ------------------------- | ------ | ------------------------------------------------------------------ | -| AU-01 | SIWX 消息构造器 | P0 | 相同输入可生成链适配后的标准登录消息 | -| AU-02 | 兼容 EIP-4361 SIWE | P0 | EVM 登录消息符合 SIWE 标准，并可通过标准验签 | -| AU-03 | 支持 Sui Personal Message | P0 | Sui 钱包可签名，后端可验证签名归属 | -| AU-04 | nonce 后端下发 | P0 | 前端不能自造 nonce，nonce 必须来自后端接口 | -| AU-05 | 消息字段完整 | P0 | 消息包含 domain、address、chainId、nonce、issuedAt、expirationTime | -| AU-06 | 后端验签 SDK | P0 | Node.js SDK 能验证 EVM 与 Sui 登录签名 | -| AU-07 | nonce 单次有效 | P0 | 验签成功或过期后 nonce 不可再次使用 | -| AU-08 | Solana SIWS | P1 | Solana 登录消息符合生态规范 | -| AU-09 | EIP-1271 合约钱包 | P1 | 合约钱包签名可通过链上 `isValidSignature` 校验 | - -### 9.4 用户身份 - -| 编号 | 需求 | 优先级 | 验收标准 | -| ----- | ---------------- | ------ | ------------------------------------------------ | -| ID-01 | 地址即用户 | P0 | 用户首次登录时基于链类型与地址创建身份 | -| ID-02 | 地址全局唯一 | P0 | 同一链同一地址不可属于多个用户 | -| ID-03 | 地址规范化 | P0 | EVM 地址小写化，Sui 地址补齐 `0x` 前缀并统一格式 | -| ID-04 | 一人多钱包 | P1 | 一个 Identity 可绑定多个 Account | -| ID-05 | 绑定新钱包需签名 | P1 | 新钱包必须完成所有权签名才能绑定 | -| ID-06 | 解绑钱包 | P1 | 用户可解绑非最后一个钱包 | -| ID-07 | 主钱包设置 | P1 | 多钱包身份可设置 Primary Account | - -### 9.5 会话管理 - -| 编号 | 需求 | 优先级 | 验收标准 | -| ----- | -------------------- | ------ | --------------------------------------------- | -| SE-01 | JWT 会话 | P0 | 验签成功后后端签发 JWT | -| SE-02 | Token 过期时间可配置 | P0 | 默认 7 天，可由应用配置覆盖 | -| SE-03 | Token 存储可配置 | P0 | 支持 localStorage 和 cookie 两种模式 | -| SE-04 | 登录状态 Hook | P0 | React Hook 能返回当前用户、session 和加载状态 | -| SE-05 | Refresh Token | P1 | session 可在有效刷新窗口内续期 | -| SE-06 | 服务端强制注销 | P1 | 后端可通过黑名单或版本号使 token 失效 | -| SE-07 | 钱包断开自动注销策略 | P1 | 应用可配置钱包断开后是否清理 session | - -### 9.6 UI 组件 - -| 编号 | 需求 | 优先级 | 验收标准 | -| ----- | ------------------- | ------ | -------------------------------------------- | -| UI-01 | Connect Wallet 按钮 | P0 | 显示未连接、连接中、已连接状态 | -| UI-02 | 钱包选择弹窗 | P0 | 钱包按链分组，展示安装状态和连接状态 | -| UI-03 | 账户状态组件 | P0 | 显示地址缩写、链标识、断开入口 | -| UI-04 | 深色与浅色主题 | P0 | 可跟随系统主题或手动指定 | -| UI-05 | Headless 模式 | P0 | 不使用 UI 包时，Hooks 能覆盖完整连接登录链路 | -| UI-06 | 响应式布局 | P0 | 移动端弹窗可用，不出现内容溢出 | -| UI-07 | 主题定制 | P1 | 支持主题色、字体、圆角等基础变量 | -| UI-08 | 中英文 i18n | P1 | 默认提供 `zh-CN` 与 `en-US` | -| UI-09 | 多钱包管理 UI | P2 | 支持绑定、解绑、设置主钱包 | - -### 9.7 开发者体验 - -| 编号 | 需求 | 优先级 | 验收标准 | -| ----- | -------------------- | ------ | ---------------------------------------------------- | -| DX-01 | 完整 TypeScript 类型 | P0 | 对外 API 无隐式 `any` | -| DX-02 | API 文档 | P0 | 覆盖 Provider、Hooks、组件、后端 SDK 和 Adapter 接口 | -| DX-03 | 示例工程 | P0 | 至少包含 Next.js、Vite、纯 EVM、纯 Sui、多链示例 | -| DX-04 | 可读错误信息 | P0 | 错误包含阶段、链类型、钱包名称和可行动建议 | -| DX-05 | SSR 支持 | P0 | Next.js App Router 下无 hydration 错误 | -| DX-06 | 不依赖中心化后端 | P0 | 用户可完全自托管认证后端；托管服务只是可选增值能力 | -| DX-07 | CLI 脚手架 | P1 | 可一键生成示例应用 | -| DX-08 | Debug Panel | P2 | 开发模式展示连接状态、事件日志和 session 信息 | - -### 9.8 后端 SDK - -| 编号 | 需求 | 优先级 | 验收标准 | -| ----- | -------------------------- | ------ | --------------------------------------------------- | -| BE-01 | Node.js 验签 SDK | P0 | 支持 EVM 与 Sui 验签 | -| BE-02 | nonce 管理工具 | P0 | 默认支持 Redis，同时提供内存实现用于开发 | -| BE-03 | 参考认证接口 | P0 | 提供 `/auth/nonce`、`/auth/verify`、`/auth/me` 示例 | -| BE-04 | 自定义 User Repository | P0 | 应用可接入自有数据库 | -| BE-05 | Next.js Route Handler 示例 | P0 | 可直接运行并完成登录闭环 | -| BE-06 | Express/Fastify 中间件 | P1 | 可快速接入常见 Node Web 框架 | -| BE-07 | Go/Rust/Python 后端 SDK | P1 | v1.0 前提供核心验签与 nonce 校验能力 | -| BE-08 | 托管 nonce/session 服务 | P1 | 作为可选增值服务提供，不影响自托管使用 | - -## 10. 核心 API 草案 - -### 10.1 前端 Provider - -```tsx - - - -``` - -### 10.2 React Hooks - -| Hook | 用途 | -| -------------------- | ----------------------- | -| `useWallets()` | 获取可用钱包列表 | -| `useConnect()` | 连接指定钱包 | -| `useDisconnect()` | 断开钱包 | -| `useAccounts()` | 获取当前连接账户 | -| `useSignIn()` | 发起 SIWX 签名登录 | -| `useSession()` | 读取 session 与用户身份 | -| `useChainAdapters()` | 读取当前启用的链能力 | - -### 10.3 后端接口 - -| 接口 | 方法 | 说明 | -| ------------------------ | -------- | ------------------------------------------------ | -| `/auth/nonce` | `POST` | 根据 domain、chainType、address 下发一次性 nonce | -| `/auth/verify` | `POST` | 校验 SIWX 消息和签名，签发 session | -| `/auth/me` | `GET` | 获取当前登录用户 | -| `/auth/logout` | `POST` | 注销当前 session | -| `/identity/accounts` | `GET` | P1，查询用户绑定的钱包账户 | -| `/identity/accounts` | `POST` | P1，绑定新钱包 | -| `/identity/accounts/:id` | `DELETE` | P1，解绑钱包 | - -## 11. 数据模型草案 - -### 11.1 Account - -```ts -type ChainType = "evm" | "sui" | "solana" | "bitcoin" | "aptos" | "ton"; - -type Account = { - id: string; - identityId: string; - chainType: ChainType; - chainId?: string | number; - address: string; - publicKey?: string; - walletName?: string; - isPrimary: boolean; - createdAt: string; - updatedAt: string; -}; -``` - -### 11.2 Identity - -```ts -type Identity = { - id: string; - primaryAccountId: string; - accounts: Account[]; - createdAt: string; - updatedAt: string; -}; -``` - -### 11.3 SIWX Message - -```ts -type SIWXMessage = { - domain: string; - address: string; - chainType: ChainType; - chainId?: string | number; - uri: string; - version: string; - nonce: string; - issuedAt: string; - expirationTime: string; - statement?: string; -}; -``` - -## 12. 安全要求 - -- 签名消息必须包含 domain，后端必须校验 domain 与当前服务一致。 -- nonce 必须由后端生成，具备随机性、过期时间和单次使用约束。 -- 验签必须校验 address、chainId、domain、nonce、issuedAt、expirationTime 和签名有效性。 -- nonce 验签成功后必须立即销毁，验签失败次数应可限制。 -- JWT 签名密钥必须满足强度要求，弱密钥在启动时抛出错误或强告警。 -- cookie 模式必须支持 HttpOnly、Secure、SameSite，并在需要时启用 CSRF 防护。 -- 本地开发可允许 HTTP，生产环境默认要求 HTTPS。 -- 地址规范化必须在服务端再次执行，不能只信任前端。 -- 所有认证错误默认不泄露敏感细节，但开发模式可提供调试信息。 -- 发布 v1.0 前应完成安全审计或至少完成第三方代码审查。 - -## 13. 非功能性要求 - -| 类别 | 指标 | -| --------------- | ---------------------------------------------------- | -| 核心包体积 | gzip 后不超过 30 KB，不包含任何 Adapter | -| 单 Adapter 体积 | gzip 后不超过 50 KB | -| 钱包弹窗响应 | 用户点击后 300ms 内展示弹窗 | -| 登录完成耗时 | 用户签名后 1.5s 内建立 session，正常网络条件下 | -| React 支持 | React 18+ 与 React 19 | -| 框架支持 | Next.js、Vite、Remix、TanStack Start | -| 浏览器支持 | Chrome、Safari、Firefox、Edge 最近 2 个大版本 | -| 移动端支持 | iOS Safari 15+，Android Chrome 最近 2 个大版本 | -| Node.js 支持 | Node.js 18+ | -| 测试覆盖率 | 核心包单元测试覆盖率不低于 80% | -| 版本兼容 | 公共 API 遵循 SemVer，Breaking Change 需提供迁移说明 | - -## 14. MVP 验收标准 - -MVP 完成时，应满足以下端到端验收： - -- Next.js 示例应用中可同时启用 EVM 与 Sui。 -- 用户可通过 EVM 钱包完成连接、签名、验签、JWT 登录和刷新恢复。 -- 用户可通过 Sui 钱包完成连接、签名、验签、JWT 登录和刷新恢复。 -- 后端 nonce 具备过期与单次使用能力。 -- 前端能处理用户拒签、钱包未安装、账户切换、钱包断开、session 过期等常见状态。 -- 默认 UI 在桌面端与移动端可用，支持深色和浅色主题。 -- Headless Hooks 能在不使用默认 UI 的情况下完成相同登录流程。 -- 文档中包含完整接入步骤、API 说明、安全注意事项和示例代码。 - -## 15. 版本规划 - -### v0.1 MVP，预计 4 周 - -- EVM Adapter。 -- Sui Adapter。 -- ChainAdapter 抽象。 -- SIWX 消息构造。 -- Node.js 后端验签 SDK。 -- React Provider 与核心 Hooks。 -- Connect Wallet 按钮与钱包选择弹窗。 -- 地址即用户身份模型。 -- JWT session。 -- Next.js 接入示例。 - -### v0.2 Beta，预计 8 周 - -- Solana Adapter。 -- WalletConnect v2 完整支持。 -- 移动端深链唤起。 -- 浅色主题与主题变量。 -- 一人多钱包身份模型。 -- Refresh Token。 -- Express/Fastify 中间件。 - -### v1.0 Stable，预计 16 周 - -- Bitcoin 与 Aptos Adapter。 -- 完整 i18n。 -- CLI 脚手架。 -- 文档站。 -- 第三方 Adapter 开发规范。 -- Go、Rust、Python 后端 SDK。 -- 可选托管 nonce/session 服务。 -- 安全审计。 -- 生产级错误码与迁移指南。 - -### v1.x 后续方向 - -- TON、Cosmos、NEAR Adapter。 -- EIP-1271 合约钱包支持。 -- 硬件钱包支持。 -- Debug Panel。 -- Auth.js、Clerk 等主流 Auth 系统集成插件。 - -## 16. 成功指标 - -| 指标 | 目标 | -| ---------------- | ----------------------------------------------------- | -| 首次接入时间 | 开发者 30 分钟内完成示例登录 | -| 示例运行成功率 | 新用户按文档操作成功率不低于 90% | -| 登录成功率 | 正常钱包环境下不低于 95% | -| 文档覆盖度 | P0 API 与流程 100% 有示例 | -| Adapter 扩展成本 | 新增一条链不需要改动核心包主流程 | -| 增值服务转化 | 托管 nonce/session 服务具备可独立开通、计费和关闭能力 | -| 包体积 | 达成非功能性体积要求 | - -## 17. 风险与应对 - -| 风险 | 影响 | 应对方案 | -| ---------------------------- | ----------------------------- | ------------------------------------------------------------------ | -| 各链钱包标准差异大 | Adapter 复杂度上升 | 核心层只定义最小能力接口，链细节隔离在 Adapter 内 | -| WalletConnect 或钱包标准变化 | 移动端连接不稳定 | 锁定大版本，维护兼容测试矩阵 | -| SSR 下钱包注入时序不一致 | 首屏状态闪烁或 hydration 问题 | Provider 默认延迟访问浏览器 API，文档提供 SSR 指南 | -| 与成熟 SaaS 方案差异化不足 | 获取开发者困难 | 聚焦开源核心、自托管、非 EVM 覆盖、Headless 能力和可选托管增值服务 | -| 多钱包身份模型过早复杂化 | MVP 交付延期 | MVP 只做地址即用户，多钱包绑定放入 v0.2 | -| 验签安全细节容易遗漏 | 可能造成重放或钓鱼风险 | 后端 SDK 默认强校验，提供安全测试用例和审计清单 | - -## 18. 已决策问题 - -| 问题 | 决策 | 影响 | -| -------------------------------------------------- | ------------------- | --------------------------------------------- | -| 是否在 v1.0 前提供 Go、Rust 或 Python 后端 SDK？ | 提供 | v1.0 范围增加多语言后端 SDK | -| 是否提供可选的托管 nonce/session 服务？ | 提供 | 作为增值服务，不影响自托管能力 | -| 多钱包模式下敏感操作如何签名？ | 任意已绑定钱包签名 | 默认授权策略为 Identity 下任意 Account 可签名 | -| 是否引入 Passkey/WebAuthn 作为非钱包兜底登录方式？ | 不引入 | 登录主路径保持钱包签名 | -| 商业模式采用哪种？ | 开源核心 + 增值服务 | 开源 SDK 保持完整可用，托管与企业能力商业化 | -| 产品名称与包名是否确定？ | 确定 | 产品名为 Dolphin ID，包名使用 `@dolphin-id/*` | diff --git "a/\345\274\200\345\217\221\350\256\241\345\210\222\344\270\216\345\215\217\344\275\234\346\265\201\347\250\213.md" "b/\345\274\200\345\217\221\350\256\241\345\210\222\344\270\216\345\215\217\344\275\234\346\265\201\347\250\213.md" deleted file mode 100644 index 08eed90..0000000 --- "a/\345\274\200\345\217\221\350\256\241\345\210\222\344\270\216\345\215\217\344\275\234\346\265\201\347\250\213.md" +++ /dev/null @@ -1,188 +0,0 @@ -# Dolphin ID 开发计划与协作流程 - -| 项目 | 内容 | -| -------- | ------------------------------------------- | -| 产品 | Dolphin ID | -| 仓库 | `git@github-zen:DolphinsLab/dolphin-id.git` | -| 包名 | `@dolphin-id/*` | -| 开发模式 | Issue 驱动 + MR/PR 持续集成 | -| 主干分支 | `main` | -| 文档版本 | v1.0 | -| 最后更新 | 2026-05-30 | - -## 1. 开发原则 - -Dolphin ID 使用 Issue 驱动开发。任何阶段、功能、缺陷、安全项、文档项都必须先有 Issue，再创建分支，再通过 MR/PR 合并。 - -开发拆分采用 tracer bullet 方式：每个 Issue 尽量交付一条可验证的端到端能力，而不是只完成某一层代码。例如“EVM 登录闭环”应同时覆盖 Adapter、React Hook、后端验签、示例和测试，而不是分别拆成“写类型”“写接口”“写 UI”。 - -## 2. 分支策略 - -| 分支 | 用途 | 规则 | -| ---------------------------- | -------- | --------------------------------- | -| `main` | 稳定主干 | 必须通过 MR/PR 合并，禁止直接推送 | -| `feature/DID-xxx-short-name` | 功能开发 | 对应一个功能 Issue | -| `fix/DID-xxx-short-name` | 缺陷修复 | 对应一个 Bug Issue | -| `docs/DID-xxx-short-name` | 文档更新 | 对应一个 Docs Issue | -| `release/vx.y.z` | 版本准备 | 只允许版本修复、文档和发布检查 | - -分支命名示例： - -```text -feature/DID-004-evm-siwe-login -docs/DID-010-api-docs -fix/DID-009-nonce-replay -release/v0.1.0 -``` - -## 3. Issue 生命周期 - -```text -Backlog -> Ready -> In Progress -> In Review -> QA -> Done -``` - -| 状态 | 进入条件 | 退出条件 | -| ----------- | ---------------- | ----------------------------- | -| Backlog | 已记录需求或想法 | Scope、验收标准、依赖关系明确 | -| Ready | 可被开发领取 | 已创建开发分支并开始编码 | -| In Progress | 正在开发 | MR/PR 已提交 | -| In Review | 等待代码评审 | Review 通过且 CI 通过 | -| QA | 等待验证 | 验收标准全部通过 | -| Done | 已合并主干 | 版本说明或文档已同步 | - -## 4. MR/PR 工作流 - -1. 从 `main` 拉取最新代码。 -2. 选择一个 Ready Issue。 -3. 创建对应分支。 -4. 完成实现、测试和文档更新。 -5. 提交 MR/PR，并在描述中关联 Issue。 -6. CI 必须通过。 -7. 至少 1 人 Review。安全相关、公共 API、认证流程相关 MR/PR 需要 2 人 Review。 -8. 合并方式使用 squash merge。 -9. 合并后关闭 Issue，并更新里程碑状态。 - -MR/PR 标题格式： - -```text -DID-004: Implement EVM SIWE login slice -``` - -提交信息格式： - -```text -DID-004 implement EVM SIWE login slice -DID-009 harden nonce replay checks -``` - -## 5. 标签体系 - -| 标签 | 说明 | -| ---------------- | --------------------------- | -| `type:feature` | 新功能 | -| `type:bug` | 缺陷修复 | -| `type:docs` | 文档 | -| `type:security` | 安全相关 | -| `type:release` | 发布准备 | -| `area:core` | 核心抽象、类型、错误模型 | -| `area:react` | React Provider、Hooks、状态 | -| `area:ui` | 默认 UI 组件 | -| `area:adapter` | 链 Adapter | -| `area:server` | 后端 SDK、认证服务 | -| `area:examples` | 示例工程 | -| `area:dx` | 脚手架、文档站、开发体验 | -| `area:hosted` | 托管 nonce/session 服务 | -| `priority:p0` | MVP 必须 | -| `priority:p1` | Beta/v1.0 必须 | -| `priority:p2` | 后续迭代 | -| `status:ready` | 可开始开发 | -| `status:blocked` | 被依赖或决策阻塞 | -| `slice:afk` | 可独立完成 | -| `slice:hitl` | 需要人工评审或决策 | - -## 6. 里程碑 - -### v0.1 MVP - -目标：完成 EVM + Sui 多链登录闭环，可运行示例，可自托管后端。 - -必须完成： - -- 仓库、CI、包管理和发布骨架。 -- `@dolphin-id/core` Adapter 合约。 -- `@dolphin-id/server` Node.js nonce、验签、JWT session。 -- EVM SIWE 登录闭环。 -- Sui Personal Message 登录闭环。 -- React Provider、Hooks、默认 Connect UI。 -- Next.js 示例和基础 E2E。 -- MVP 安全加固。 -- API 文档和接入指南。 - -### v0.2 Beta - -目标：扩展移动端、Solana、多钱包身份和更完整会话能力。 - -必须完成： - -- WalletConnect v2 和移动端深链。 -- Solana SIWS 登录闭环。 -- 一人多钱包身份模型，默认任意已绑定钱包可签名。 -- Refresh Token 和强制注销。 -- 主题、i18n 和移动端 UI 完善。 -- Express/Fastify 中间件。 - -### v1.0 Stable - -目标：达到生产稳定版，形成开源核心和增值服务边界。 - -必须完成： - -- Bitcoin 和 Aptos Adapter。 -- Go/Rust/Python 后端 SDK。 -- 可选托管 nonce/session 服务。 -- CLI 脚手架。 -- 文档站和第三方 Adapter 开发规范。 -- 安全审计和 v1.0 发布检查。 - -## 7. 发布流程 - -1. 创建 `release/vx.y.z` 分支。 -2. 冻结功能，只接受 release blocker。 -3. 跑完整测试矩阵。 -4. 更新 changelog、迁移指南和文档站。 -5. 创建 release MR/PR。 -6. 合并后打 tag。 -7. 发布 npm 包和 SDK 包。 -8. 创建 GitHub Release。 -9. 将该里程碑未完成 Issue 移到下一里程碑。 - -## 8. 质量门禁 - -每个 MR/PR 至少满足： - -- 单元测试通过。 -- 类型检查通过。 -- lint/format 通过。 -- 涉及登录、安全、session 的变更必须包含负向测试。 -- 涉及 UI 的变更必须包含移动端和桌面端截图或可复现说明。 -- 涉及公共 API 的变更必须更新文档。 - -v0.1 发布前必须满足： - -- EVM 与 Sui 登录端到端验证通过。 -- nonce 单次使用和过期测试通过。 -- session 刷新恢复测试通过。 -- 示例工程按文档可运行。 -- 核心包体积预算检查通过。 - -## 9. Issue 发布方式 - -当前仓库已准备本地 Issue 草稿，见 [docs/issues/README.md](/Users/bond/Code/github/dolp/dolphin-id/docs/issues/README.md)。 - -如果本机安装并登录了 GitHub CLI，可执行： - -```bash -./scripts/create-github-issues.sh -``` - -脚本会按依赖顺序创建远端 GitHub Issues。若团队使用 GitLab，可将 `docs/issues/*.md` 的内容导入 GitLab Issues，MR 流程保持不变。