@arcblock/did-connect-react 3.1.40 → 3.1.42

package/docs/core-components-session-provider.ja.md

@@ -0,0 +1,239 @@
+# セッション管理 (SessionProvider)
+
+`SessionProvider`は`@arcblock/did-connect-react`ライブラリの礎です。これは、セッション関連のすべてのロジック、状態、アクションをカプセル化するReact Context Providerです。アプリケーションを`SessionProvider`でラップすることにより、propsを手動で下に渡すことなく、アプリケーションツリー内のどのコンポーネントでもユーザーのセッション情報と認証メソッドを利用できるようになります。
+
+このコンポーネントは、セッショントークンの保存やユーザーデータの管理から、ログイン/ログアウトフローの調整、セッションの自動更新まで、すべてを処理します。
+
+## 仕組み
+
+`SessionProvider`は、現在のユーザーの状態（`user`オブジェクト、`loading`ステータスなど）を保持するセッションコンテキストを作成し、その状態を変更する関数（例：`login`、`logout`）を提供します。`SessionProvider`内にネストされたどのコンポーネントも、このコンテキストを購読してこのデータにアクセスし、認証アクションをトリガーできます。
+
+以下は、基本的なアーキテクチャを示す図です。
+
+```d2 SessionProvider Architecture icon=mdi:react
+direction: down
+
+SessionProvider: {
+  label: "SessionProvider"
+  shape: rectangle
+  style: {
+    fill: "#f0f9ff"
+    stroke: "#0284c7"
+  }
+
+  Session-Context: {
+    label: "セッションコンテキスト\n{ user, login(), logout() ... }"
+    shape: cylinder
+    style.fill: "#ecfdf5"
+  }
+
+  Your-App: {
+    label: "あなたのアプリケーション"
+    shape: rectangle
+
+    Header: {
+      label: "ヘッダーコンポーネント"
+    }
+
+    ProfilePage: {
+      label: "プロフィールページ"
+    }
+
+    LoginButton: {
+      label: "ログインボタン"
+    }
+  }
+
+  Session-Context -> Your-App: 提供
+}
+
+Your-App.Header: 利用
+Your-App.ProfilePage: 利用
+Your-App.LoginButton: 利用とアクション
+
+Your-App.Header -> Session-Context
+Your-App.ProfilePage -> Session-Context
+Your-App.LoginButton -> Session-Context
+```
+
+## はじめに
+
+セッション管理機能を使用するには、まず`SessionProvider`をインポートしてアプリケーションをラップする必要があります。このライブラリは、設定済みのプロバイダーを作成するためのファクトリー関数をエクスポートします。
+
+### 基本的なセットアップ
+
+プロバイダーをセットアップする最も一般的な方法は、`createAuthServiceSessionContext`を使用することです。これは、ArcBlockエコシステム（Blocklets）内で実行されるアプリケーション向けに事前設定されています。
+
+```javascript App.js icon=logos:javascript
+import React from 'react';
+import { createAuthServiceSessionContext } from '@arcblock/did-connect-react/lib/Session';
+import AuthButton from './AuthButton';
+
+// SessionProviderとコンテキストにアクセスするためのフックを作成
+const { SessionProvider, SessionContext } = createAuthServiceSessionContext();
+
+export const useSession = () => React.useContext(SessionContext);
+
+export default function App() {
+  return (
+    <SessionProvider>
+      <div className="App">
+        <h1>Welcome to DID Connect</h1>
+        <AuthButton />
+      </div>
+    </SessionProvider>
+  );
+}
+```
+
+```javascript AuthButton.js icon=logos:javascript
+import React from 'react';
+import { useSession } from './App';
+
+export default function AuthButton() {
+  const { session } = useSession();
+
+  if (session.loading) {
+    return <div>Loading...</div>;
+  }
+
+  if (session.user) {
+    return (
+      <div>
+        <p>Welcome, {session.user.fullName || session.user.did}</p>
+        <button onClick={() => session.logout()}>Logout</button>
+      </div>
+    );
+  }
+
+  return <button onClick={() => session.login()}>Login</button>;
+}
+```
+
+この例では、`createAuthServiceSessionContext`が`SessionProvider`を生成します。`App`をそれでラップすると、`AuthButton`のような子コンポーネントは、`useSession`フックを使用してセッションデータと関数にアクセスできるようになります。
+
+## SessionProviderのProps
+
+`SessionProvider`の動作は、さまざまなpropsを渡すことで設定できます。
+
+<x-field-group>
+  <x-field data-name="serviceHost" data-type="string" data-desc="認証サービスバックエンドのベースURL。デフォルトは現在のBlockletのプレフィックスまたは'/'です。"></x-field>
+  <x-field data-name="autoConnect" data-type="boolean" data-default="false" data-desc="trueの場合、ページロード時にユーザーセッションが見つからないと、DID Connectダイアログが自動的に開きます。"></x-field>
+  <x-field data-name="autoDisconnect" data-type="boolean" data-default="true" data-desc="trueの場合、アプリケーションIDがセッションクッキーに保存されているものと一致しない場合、セッションは自動的にクリアされます。"></x-field>
+  <x-field data-name="protectedRoutes" data-type="string[]" data-default='["*"]' data-desc="保護するルートパターンの配列。未認証のユーザーがこれらのルートにアクセスしようとすると、セッションが解決されるまで読み込みスピナーが表示されます。ワイルドカード（*）がサポートされています。"></x-field>
+  <x-field data-name="locale" data-type="string" data-desc="DID Connect UIの表示言語を設定します。デフォルトはブラウザの言語です。"></x-field>
+  <x-field data-name="webWalletUrl" data-type="string" data-desc="接続プロセスで使用するウェブベースのDID WalletのURL。"></x-field>
+  <x-field data-name="timeout" data-type="number" data-default="120000" data-desc="接続プロセス中にDID Walletからの応答を待つためのタイムアウト（ミリ秒単位）。"></x-field>
+  <x-field data-name="useSocket" data-type="boolean" data-default="true" data-desc="ウォレットとのリアルタイム通信にWebSocketを使用するかどうかを決定し、より高速なユーザーエクスペリエンスを提供します。"></x-field>
+  <x-field data-name="extraParams" data-type="object" data-desc="バックエンドへのすべての認証リクエストとともに送信される追加パラメーターのオブジェクト。"></x-field>
+</x-field-group>
+
+## セッションコンテキストオブジェクト
+
+`SessionContext`を利用すると、セッションの状態とAPIを含むオブジェクトを取得できます。主要なプロパティは`session`で、これには対話するすべてのデータとメソッドが含まれています。
+
+### 状態プロパティ
+
+これらは、ユーザーセッションの現在の状態を記述する読み取り専用のプロパティです。
+
+<x-field-group>
+  <x-field data-name="user" data-type="User | null" data-desc="セッションが存在する場合、認証されたユーザーオブジェクト。それ以外の場合はnull。DID、名前、メール、アバターなどの詳細が含まれます。"></x-field>
+  <x-field data-name="loading" data-type="boolean" data-desc="セッションが初期化中、更新中、またはログイン/ログアウトプロセス中である場合はtrue。"></x-field>
+  <x-field data-name="initialized" data-type="boolean" data-desc="ページロード時に最初のセッションチェックが完了するとtrueになります。"></x-field>
+  <x-field data-name="open" data-type="boolean" data-desc="DID Connectダイアログが現在開いている場合はtrue。"></x-field>
+  <x-field data-name="error" data-type="string" data-desc="最後のセッション操作が失敗した場合、エラーメッセージが含まれます。"></x-field>
+  <x-field data-name="provider" data-type="string" data-desc="最後のログインに使用されたプロバイダー（例：'wallet'、'github'、'google'）。"></x-field>
+  <x-field data-name="walletOS" data-type="string" data-desc="接続されたDID Walletのオペレーティングシステム（例：'ios'、'android'、'web'）。"></x-field>
+  <x-field data-name="unReadCount" data-type="number" data-desc="現在のユーザーの未読通知の数。"></x-field>
+</x-field-group>
+
+### アクションメソッド
+
+これらは、認証フローを開始したり、セッションを管理したりするために呼び出すことができる関数です。
+
+<x-field-group>
+  <x-field data-name="login()" data-type="function">
+    <x-field-desc markdown>DID Connect UIを開いてユーザーのログインプロセスを開始します。オプションのコールバックとパラメーターを受け入れます。</x-field-desc>
+  </x-field>
+  <x-field data-name="logout()" data-type="function">
+    <x-field-desc markdown>現在のユーザーをログアウトさせ、ストレージからセッションをクリアします。完了時に実行されるオプションのコールバック関数を受け入れます。</x-field-desc>
+  </x-field>
+  <x-field data-name="switchDid()" data-type="function">
+    <x-field-desc markdown>ログイン中のユーザーが別のアカウントに切り替えることを許可します。アカウント切り替え用のコンテキストでDID Connect UIを再度開きます。</x-field-desc>
+  </x-field>
+  <x-field data-name="bindWallet()" data-type="function">
+    <x-field-desc markdown>ソーシャルプロバイダー（OAuth）またはパスキー経由でログインしたユーザーのために、この関数は既存のアカウントにDID Walletを接続するフローを開始します。</x-field-desc>
+  </x-field>
+  <x-field data-name="refresh()" data-type="function">
+    <x-field-desc markdown>サーバーからユーザーのセッションデータを手動で更新します。更新されたプロフィール情報や権限を取得するのに便利です。</x-field-desc>
+  </x-field>
+  <x-field data-name="switchProfile()" data-type="function">
+    <x-field-desc markdown>DID Connect UIを開き、ユーザーが同じDIDアカウント内の異なるプロフィール（例：個人用、仕事用）を切り替えられるようにします。</x-field-desc>
+  </x-field>
+  <x-field data-name="switchPassport()" data-type="function">
+    <x-field-desc markdown>DID Connect UIを開き、ユーザーが異なるパスポート（異なる資格情報や役割のセットを表す場合がある）を切り替えられるようにします。</x-field-desc>
+  </x-field>
+  <x-field data-name="connectToDidSpaceForFullAccess()" data-type="function">
+    <x-field-desc markdown>ユーザーのDID Spaceへの接続を開始し、フルアクセス権限を要求します。これは、ユーザーの個人データストアにデータを読み書きする必要があるアプリケーションでしばしば必要とされます。</x-field-desc>
+  </x-field>
+  <x-field data-name="withSecondaryAuth()" data-type="function">
+    <x-field-desc markdown>別の関数をラップする高階関数で、ラップされた関数が実行される前に、ユーザーが二次認証ステップ（例：パスワードの再入力、パスキーの使用）を完了する必要があります。これは機密性の高いアクションを保護するのに理想的です。</x-field-desc>
+  </x-field>
+</x-field-group>
+
+### イベントの購読
+
+コンテキストは`events`オブジェクトも提供します。これは`EventEmitter3`のインスタンスです。これを使用して、セッションのさまざまなライフサイクルイベントを購読できます。
+
+```javascript EventListener.js icon=logos:javascript
+import React, { useEffect } from 'react';
+import { useSession } from './App';
+
+function EventListener() {
+  const { events } = useSession();
+
+  useEffect(() => {
+    const handleLogin = (result) => {
+      console.log('User logged in:', result.user.did);
+    };
+
+    const handleLogout = () => {
+      console.log('User logged out');
+    };
+
+    events.on('login', handleLogin);
+    events.on('logout', handleLogout);
+
+    // コンポーネントのアンマウント時にリスナーをクリーンアップ
+    return () => {
+      events.off('login', handleLogin);
+      events.off('logout', handleLogout);
+    };
+  }, [events]);
+
+  return null; // このコンポーネントは何もレンダリングしません
+}
+```
+
+利用可能なイベントには、`login`、`login-failed`、`logout`、`change`、`bind-wallet`、`switch-passport`などがあります。
+
+## 高度なカスタマイズ
+
+異なるストレージメカニズムやより詳細な制御が必要なシナリオでは、汎用の`createSessionContext`ファクトリーを使用できます。
+
+```javascript customSession.js icon=logos:javascript
+import { createSessionContext } from '@arcblock/did-connect-react/lib/Session';
+
+const { SessionProvider, SessionContext } = createSessionContext(
+  'my_app_session_token', // カスタムストレージキー
+  'ls',                   // cookieの代わりにlocalStorageを使用
+  {},
+  {
+    rolling: false,         // 自動トークン更新を無効化
+  }
+);
+
+// ... 必要に応じてエクスポートして使用
+```
+
+これにより、ストレージエンジンを`localStorage`（'ls'）や`cookie`に変更したり、トークン更新ポリシーを調整したりするなど、セッションの動作を微調整できます。

package/docs/core-components-session-provider.md

@@ -0,0 +1,239 @@
+# Session Management (SessionProvider)
+
+The `SessionProvider` is the cornerstone of the `@arcblock/did-connect-react` library. It's a React Context Provider that encapsulates all session-related logic, state, and actions. By wrapping your application with `SessionProvider`, you make the user's session information and authentication methods available to any component in your application tree, without having to pass props down manually.
+
+This component handles everything from storing session tokens and managing user data to orchestrating login/logout flows and refreshing sessions automatically.
+
+## How It Works
+
+`SessionProvider` creates a session context that holds the current user's state (`user` object, `loading` status, etc.) and provides functions to modify that state (e.g., `login`, `logout`). Any component nested within `SessionProvider` can subscribe to this context to access this data and trigger authentication actions.
+
+Here is a diagram illustrating the basic architecture:
+
+```d2 SessionProvider Architecture icon=mdi:react
+direction: down
+
+SessionProvider: {
+  label: "SessionProvider"
+  shape: rectangle
+  style: {
+    fill: "#f0f9ff"
+    stroke: "#0284c7"
+  }
+
+  Session-Context: {
+    label: "Session Context\n{ user, login(), logout() ... }"
+    shape: cylinder
+    style.fill: "#ecfdf5"
+  }
+
+  Your-App: {
+    label: "Your Application"
+    shape: rectangle
+
+    Header: {
+      label: "Header Component"
+    }
+
+    ProfilePage: {
+      label: "Profile Page"
+    }
+
+    LoginButton: {
+      label: "Login Button"
+    }
+  }
+
+  Session-Context -> Your-App: Provides
+}
+
+Your-App.Header: Consumes
+Your-App.ProfilePage: Consumes
+Your-App.LoginButton: Consumes & Actions
+
+Your-App.Header -> Session-Context
+Your-App.ProfilePage -> Session-Context
+Your-App.LoginButton -> Session-Context
+```
+
+## Getting Started
+
+To use the session management features, you first need to import and wrap your application with `SessionProvider`. The library exports factory functions to create a configured provider.
+
+### Basic Setup
+
+The most common way to set up the provider is by using `createAuthServiceSessionContext`, which is pre-configured for applications running within the ArcBlock ecosystem (Blocklets).
+
+```javascript App.js icon=logos:javascript
+import React from 'react';
+import { createAuthServiceSessionContext } from '@arcblock/did-connect-react/lib/Session';
+import AuthButton from './AuthButton';
+
+// Create the SessionProvider and a hook to access the context
+const { SessionProvider, SessionContext } = createAuthServiceSessionContext();
+
+export const useSession = () => React.useContext(SessionContext);
+
+export default function App() {
+  return (
+    <SessionProvider>
+      <div className="App">
+        <h1>Welcome to DID Connect</h1>
+        <AuthButton />
+      </div>
+    </SessionProvider>
+  );
+}
+```
+
+```javascript AuthButton.js icon=logos:javascript
+import React from 'react';
+import { useSession } from './App';
+
+export default function AuthButton() {
+  const { session } = useSession();
+
+  if (session.loading) {
+    return <div>Loading...</div>;
+  }
+
+  if (session.user) {
+    return (
+      <div>
+        <p>Welcome, {session.user.fullName || session.user.did}</p>
+        <button onClick={() => session.logout()}>Logout</button>
+      </div>
+    );
+  }
+
+  return <button onClick={() => session.login()}>Login</button>;
+}
+```
+
+In this example, `createAuthServiceSessionContext` generates a `SessionProvider`. We wrap our `App` with it, and now any child component, like `AuthButton`, can use the `useSession` hook to access session data and functions.
+
+## SessionProvider Props
+
+You can configure the `SessionProvider`'s behavior by passing it various props.
+
+<x-field-group>
+  <x-field data-name="serviceHost" data-type="string" data-desc="The base URL for the authentication service backend. Defaults to the current Blocklet's prefix or '/'."></x-field>
+  <x-field data-name="autoConnect" data-type="boolean" data-default="false" data-desc="If true, the DID Connect dialog will automatically open if no user session is found on page load."></x-field>
+  <x-field data-name="autoDisconnect" data-type="boolean" data-default="true" data-desc="If true, the session will be automatically cleared if the application ID mismatches the one stored in the session cookie."></x-field>
+  <x-field data-name="protectedRoutes" data-type="string[]" data-default='["*"]' data-desc="An array of route patterns to protect. If a non-authenticated user tries to access these routes, they will see a loading spinner until the session is resolved. Wildcards (*) are supported."></x-field>
+  <x-field data-name="locale" data-type="string" data-desc="Sets the display language for the DID Connect UI. Defaults to the browser's language."></x-field>
+  <x-field data-name="webWalletUrl" data-type="string" data-desc="The URL of the web-based DID Wallet to use for the connection process."></x-field>
+  <x-field data-name="timeout" data-type="number" data-default="120000" data-desc="The timeout in milliseconds for waiting for a response from DID Wallet during the connection process."></x-field>
+  <x-field data-name="useSocket" data-type="boolean" data-default="true" data-desc="Determines whether to use WebSockets for real-time communication with the wallet, providing a faster user experience."></x-field>
+  <x-field data-name="extraParams" data-type="object" data-desc="An object of extra parameters to be sent with every authentication request to the backend."></x-field>
+</x-field-group>
+
+## The Session Context Object
+
+When you consume the `SessionContext`, you get an object containing the session state and API. The primary property is `session`, which holds all the data and methods you'll interact with.
+
+### State Properties
+
+These are read-only properties that describe the current state of the user session.
+
+<x-field-group>
+  <x-field data-name="user" data-type="User | null" data-desc="The authenticated user object if a session exists, otherwise null. Contains details like DID, name, email, avatar, etc."></x-field>
+  <x-field data-name="loading" data-type="boolean" data-desc="True when the session is being initialized, refreshed, or during a login/logout process."></x-field>
+  <x-field data-name="initialized" data-type="boolean" data-desc="True once the initial session check has completed on page load."></x-field>
+  <x-field data-name="open" data-type="boolean" data-desc="True if the DID Connect dialog is currently open."></x-field>
+  <x-field data-name="error" data-type="string" data-desc="Contains an error message if the last session operation failed."></x-field>
+  <x-field data-name="provider" data-type="string" data-desc="The provider used for the last login (e.g., 'wallet', 'github', 'google')."></x-field>
+  <x-field data-name="walletOS" data-type="string" data-desc="The operating system of the connected DID Wallet (e.g., 'ios', 'android', 'web')."></x-field>
+  <x-field data-name="unReadCount" data-type="number" data-desc="The number of unread notifications for the current user."></x-field>
+</x-field-group>
+
+### Action Methods
+
+These are functions you can call to initiate authentication flows or manage the session.
+
+<x-field-group>
+  <x-field data-name="login()" data-type="function">
+    <x-field-desc markdown>Initiates the user login process by opening the DID Connect UI. It accepts optional callbacks and parameters.</x-field-desc>
+  </x-field>
+  <x-field data-name="logout()" data-type="function">
+    <x-field-desc markdown>Logs the current user out, clearing the session from storage. It accepts an optional callback function to be executed upon completion.</x-field-desc>
+  </x-field>
+  <x-field data-name="switchDid()" data-type="function">
+    <x-field-desc markdown>Allows a logged-in user to switch to a different DID account. It re-opens the DID Connect UI with a context for switching accounts.</x-field-desc>
+  </x-field>
+  <x-field data-name="bindWallet()" data-type="function">
+    <x-field-desc markdown>For users logged in via social providers (OAuth) or Passkeys, this function initiates a flow to connect a DID Wallet to their existing account.</x-field-desc>
+  </x-field>
+  <x-field data-name="refresh()" data-type="function">
+    <x-field-desc markdown>Manually triggers a refresh of the user's session data from the server. Useful for fetching updated profile information or permissions.</x-field-desc>
+  </x-field>
+  <x-field data-name="switchProfile()" data-type="function">
+    <x-field-desc markdown>Opens the DID Connect UI to allow the user to switch between different profiles within the same DID account (e.g., personal, work).</x-field-desc>
+  </x-field>
+  <x-field data-name="switchPassport()" data-type="function">
+    <x-field-desc markdown>Opens the DID Connect UI to allow the user to switch between different passports, which may represent different sets of credentials or roles.</x-field-desc>
+  </x-field>
+  <x-field data-name="connectToDidSpaceForFullAccess()" data-type="function">
+    <x-field-desc markdown>Initiates a connection to the user's DID Space, requesting full access permissions. This is often required for applications that need to read and write data to the user's personal data store.</x-field-desc>
+  </x-field>
+  <x-field data-name="withSecondaryAuth()" data-type="function">
+    <x-field-desc markdown>A higher-order function that wraps another function, requiring the user to complete a secondary authentication step (e.g., re-enter password, use passkey) before the wrapped function is executed. This is ideal for protecting sensitive actions.</x-field-desc>
+  </x-field>
+</x-field-group>
+
+### Event Subscription
+
+The context also provides an `events` object, which is an instance of `EventEmitter3`. You can use it to subscribe to various lifecycle events of the session.
+
+```javascript EventListener.js icon=logos:javascript
+import React, { useEffect } from 'react';
+import { useSession } from './App';
+
+function EventListener() {
+  const { events } = useSession();
+
+  useEffect(() => {
+    const handleLogin = (result) => {
+      console.log('User logged in:', result.user.did);
+    };
+
+    const handleLogout = () => {
+      console.log('User logged out');
+    };
+
+    events.on('login', handleLogin);
+    events.on('logout', handleLogout);
+
+    // Cleanup listeners on component unmount
+    return () => {
+      events.off('login', handleLogin);
+      events.off('logout', handleLogout);
+    };
+  }, [events]);
+
+  return null; // This component doesn't render anything
+}
+```
+
+Available events include `login`, `login-failed`, `logout`, `change`, `bind-wallet`, `switch-passport`, and more.
+
+## Advanced Customization
+
+For scenarios that require different storage mechanisms or more granular control, you can use the generic `createSessionContext` factory.
+
+```javascript customSession.js icon=logos:javascript
+import { createSessionContext } from '@arcblock/did-connect-react/lib/Session';
+
+const { SessionProvider, SessionContext } = createSessionContext(
+  'my_app_session_token', // Custom storage key
+  'ls',                   // Use localStorage instead of cookies
+  {},
+  {
+    rolling: false,         // Disable automatic token refresh
+  }
+);
+
+// ... export and use as needed
+```
+
+This allows you to fine-tune session behavior, such as changing the storage engine to `localStorage` ('ls') or `cookie`, or adjusting token refresh policies.