@upbond/sdk — Login 3.0 外部 SDK

RP 開発者が UPBOND ID（OIDC）+ 埋め込みウォレット（MPC/TSS）+ リカバリを数行で組み込むための SDK（docs/00-BUILD-SPEC.md §1）。auth0-spa-js や @web3auth/* を直接使わずに済ませることが目的。

ドキュメント

• EXAMPLES.md — シナリオ別のサンプル集（認証専用 / リダイレクトウォレット / 埋め込みウィジェット / 低レベル OIDC）。型チェック済みの examples/*.ts を embedme で埋め込み。
• docs/api/ — 生成 API リファレンス（TypeDoc → Markdown、pnpm --filter @upbond/sdk docs:api で再生成）。
• docs/24-sdk-design.md — 設計記録（決定事項 D1–、変更記録）。
• docs/27-sdk-release.md — 初回外部リリース Runbook（準備済み・未実行）。

使い方

最小構成

RP が設定するのは clientId の 1 つだけ（+ staging に繋ぐ場合の environment）。environment のデフォルトは 'production' で、issuer（auth.upbond.io）からウォレットまで全部が埋まる。認証は常に RP 自身の client の OIDC redirect（login() → issuer → callback → RP ページが id_token を保持、docs/24 D20）。ウォレットのデフォルトは embedded（ウィジェット）モード: 鍵・パスキー・儀式・リカバリ通信はすべて wallet.upbond.io のウィジェット内で動き、RP ページには EIP-1193 provider だけが渡る。redirectUri は window.location.origin がデフォルト（issuer 側にその値を登録しておくこと）。

import { createUpbond } from '@upbond/sdk';

const upbond = createUpbond({
  clientId: 'your-client-id',
  // environment: 'staging',  // staging に繋ぐ場合のみ。省略 = production
});

await upbond.init();                       // callback 消費 or セッション復元
loginBtn.onclick = () => upbond.login();   // issuer へ redirect（PKCE は内部）
logoutBtn.onclick = () => upbond.logout(); // issuer サインアウト

認証専用の RP もこの形のまま — ウォレット系メソッドを呼ばなければウォレットには触れない。

ウォレットを使う（embedded = デフォルト）

追加設定は不要。フローは login() → connect(): まず RP 自身の client で issuer にログインし（id_token は RP ページに残る）、その後 connect() で開くウィジェットの popup は既存の issuer セッションを無音の SSO で消費する（popup にログイン UI は出ない）。connect() はサインイン済みセッションを必須とし、未ログインなら何も開かずに not_signed_in を投げる（docs/24 D20 A-3 — ウォレットレッグは認証しない。RP の origin を client の redirect_uris に登録しておくこと）。getEthereumProvider() の EIP-1193 provider を ethers.js / viem からそのまま使える。署名要求は必ずウィジェットの確認 UI（origin バッジ + 生体）に落ちる — RP ページからのサイレント署名は不能。

const upbond = createUpbond({ clientId: 'your-client-id' });

await upbond.init();
loginBtn.onclick = () => upbond.login();          // ① issuer へ redirect（RP 自身の client）
connectBtn.onclick = async () => {                // ② ログイン後・ユーザージェスチャー内で（未ログインは not_signed_in）
  await upbond.connect();                         //    popup: 無音 SSO + パスキー（初回のみ登録）
  const provider = await upbond.getEthereumProvider(); // EIP-1193
  const [address] = await provider.request({ method: 'eth_accounts' });
};
sendBtn.onclick = async () => {
  const provider = await upbond.getEthereumProvider();
  await provider.request({
    method: 'eth_sendTransaction',
    params: [{ to, value }],                    // 承認はウィジェット側の確認 UI
  });
};
openBtn.onclick = () => upbond.openWallet();    // フルウォレット UI をオーバーレイ表示

対応 RPC は eth_accounts / eth_requestAccounts / eth_chainId / personal_sign / eth_sendTransaction（ネイティブ送金）。data 付き tx（ERC-20 / コントラクト呼び出し）と読み取り系（eth_call 等）は未対応 — 読み取りは公開 RPC の JsonRpcProvider を併用する（docs/25-widget.md）。詳細は EXAMPLES.md §3。

redirect モード（ページ内 MPC、advanced — wallet.* 自身・内部デモ向け）

wallet: { mode: 'redirect' } で MPC 儀式を RP ページ内で実行する形に切り替わる（connectWallet() / setupWallet() / signTransaction() 系 API）。鍵・パスキー（rpId = そのページのドメイン）・リカバリ通信がその origin から出るため、origin ごとに Web3Auth ダッシュボードの allowed origins と recovery-service の CORS / aud 登録が必要になる — 外部 RP の既定にはしない（docs/24 D20）。旧設定との互換のため、mode 省略でもローカル MPC 系フィールド（web3authClientId / network / verifier / rpId / recovery / promptPasscode / sealerPolicy）を明示した設定は redirect と解釈される。walletConnectProjectId は mode に関与しない。詳細は EXAMPLES.md §2。

注意点:

• ウォレット操作（connect() / redirect モードの setupWallet 等）はユーザージェスチャー（クリックハンドラ）内で呼ぶ — popup / パスキー / 生体プロンプトが開くため。
• MPC スタック（redirect モード）は動的 import。embedded / 認証専用の RP はバンドルにも実行時にも @web3auth を含まない。
• redirect モードで MPC チャンクを実際にロードする RP は、@web3auth/mpc-core-kit 系が参照する Node グローバル（Buffer / process / global）をバンドラ側で用意する（Vite の例: define: { global: 'globalThis' } + process の alias + エントリ先頭で buffer / process を globalThis に載せる polyfill — packages/sdk-demo/src/polyfills.ts と同梱の vite.config.ts を参照）。
• 低レベル API（beginAuthorization / completeAuthorization / buildLogoutUrl）は advanced 用途向けに公開継続。

設計ルール

• src/index.ts が公開面のすべて。それ以外の import はサポート外。
• 内部は src/core/（プラットフォーム非依存 — 将来 @upbond/sdk-core として抽出可能）と src/web/（ブラウザアダプタ）に分離。境界は scripts/check-deps.mjs が CI で強制する: core はブラウザグローバル禁止・import は @upbond/shared / jose / core 内相対のみ。
• @web3auth/* の直接依存は禁止（wallet-core 抽象経由のみ、.claude/rules/wallet.md）。
• エラーはすべて UpbondError { code }。内部実装のエラー型は公開面に漏らさない。

契約ポリシー（憲章 §6）

公開 API（型・メソッド・エラー code）は外部顧客との契約であり、破壊的変更はバージョニング + docs/ の移行ガイドなしに行わない。契約の凍結は初の外部リリースから適用。それまでは 0.x として docs/24-sdk-design.md（設計記録）に変更を記録しながら開発する。