spider-weave

スパイダーウェーブ

クモは急ぎません。糸を一本ずつ張り、次に進む前にそれぞれを慎重に固定します。巣は自然に広がっていきます。まず放射状の糸を張り、次に螺旋を描き、つなぎ目の強度を一つずつ確かめます。完成した巣は、大切なものを捕らえながら、風を通します。このように織り上げた認証は、強く、しなやかで、美しい構造を備えています。

有効にするタイミング

• ユーザーが「認証を追加して」や「認証を設定して」と依頼したとき
• 「このルートを保護して」や「ログイン機能を追加して」と言われたとき
• /spider-weave を呼び出したとき、または spider/auth に言及したとき
• OAuth（Google、GitHub など）を統合するとき
• セッション管理を設定するとき
• API ルートを保護するとき
• ロールベースのアクセス制御（RBAC）を追加するとき
• PKCE フローを実装するとき
• Heartwood（GroveAuth）に接続するとき

併用: セキュリティレビューには raccoon-audit、認証テストには beaver-build

---

織り方

SPIN --> CONNECT --> SECURE --> TEST --> BIND
  |         |          |          |        |
Create    Link       Harden    Verify   Lock In
Threads  Strands     Knots      Web    Security

フェーズ 1：SPIN

クモは最初の糸を張り、枠の隅に慎重に固定します……

認証の基盤となる構造を作成します。パターンを選び、ファイルをひな形から作成し、スキーマを定義して、ロジックを一行も書く前に環境変数を接続します。

• アプリの種類とユーザーのニーズに基づいて、認証パターン（セッション、JWT、OAuth 2.0、PKCE、API キー）を選択します
• src/lib/auth/ に index.ts、types.ts、session.ts、middleware.ts、pkce.ts、client.ts を用意します
• データベーススキーマに users テーブルと sessions テーブルを定義します
• 必要な環境変数を設定します：クライアント ID、シークレット、authorize/token/userinfo URL、リダイレクト URI、セッションシークレット

参考: PKCE のセットアップコード、データベーススキーマ、環境変数一覧、完全なファイル構成については、references/oauth-pkce-flow.md を読み込みます

---

フェーズ 2：CONNECT

糸と糸がつながり、枠いっぱいに巣が形作られていきます……

認証システムを連携させます。OAuth ログインリダイレクト、コールバックハンドラー、ユーザーのアップサート、セッション作成を実装します。次に、クライアント側の認証ストアを接続します。

• ログインルートを実装します：PKCE ベリファイアとチャレンジを生成し、Cookie を設定して、プロバイダーにリダイレクトします
• コールバックルートを実装します：state を検証し、コードをトークンと交換し、userinfo を取得し、ユーザーをアップサートして、セッションを作成し、PKCE Cookie を削除します
• セッション作成（createSession）、検証（validateSession）、無効化（invalidateSession）を実装します
• Svelte で認証状態をリアクティブに管理するため、loadUser() を備えたクライアント側の auth ストアを設定します

参考: ログインルートとコールバックルートの完全な実装については references/oauth-pkce-flow.md を、セッション関数と認証ストアについては references/session-management.md を読み込みます

---

フェーズ 3：SECURE

クモは一つひとつの結び目を確かめ、緩い部分を締め、不要な部分を切り離します……

ユーザーに信頼して使ってもらう前に、認証システムを強化します。ルート保護、セキュリティヘッダー、CSRF 検証、レート制限を追加します。

• hooks.server.ts でセッションを検証する requireAuth() ミドルウェアを実装します
• RBAC 用の requireRole(allowedRoles) を実装し、未許可のアクセスには 403 を返します
• すべてのレスポンスにセキュリティヘッダーを設定します：X-Frame-Options、X-Content-Type-Options、Referrer-Policy、Content-Security-Policy
• 状態を変更するエンドポイントに CSRF オリジン検証を追加します
• レート制限を追加します：認証エンドポイントで、IP ごとに 15 分あたり 5 回まで

参考: ミドルウェアコードと RBAC パターンについては references/route-protection.md を、ヘッダー、CSRF、レート制限、Cloudflare エッジルールについては references/security-headers.md を読み込みます

---

フェーズ 4：TEST

クモが糸をつま弾き、それぞれが適切な周波数で正しく振動することを確かめます……

正常系、安全性に関するエッジケース、障害モードを網羅して、認証を徹底的にテストします。自動テストでリグレッションを検出し、セキュリティテストで結び目がしっかり保たれていることを確認します。

• OAuth フロー全体をテストします：PKCE チャレンジを伴うリダイレクト、コールバック処理、セッション作成
• ルート保護をテストします：未認証時のリダイレクト、認証済みのアクセス、ロールの適用
• セキュリティ特性をテストします：CSRF state の拒否、安全な Cookie 属性、セッション固定攻撃の防止
• 障害モードを網羅します：期限切れのセッション、無効なコード、拒否された OAuth 権限

参照： OAuth フローテストについては references/oauth-pkce-flow.md を読み込み、ルート保護テストスイートについては references/route-protection.md を読み込んでください

---

フェーズ 5：BIND

ウェブが完成し、すべての糸がしっかり結ばれ、全体は糸の総和よりも強くなります……

認証を仕上げて、確実に定着させます。ユーザー体験を磨き、監視を設定し、完了レポートを作成します。

• 統合チェックリストを確認します：ログイン、ログアウト、保護されたルート、セッションの有効期限、エラー処理、レート制限、CSRF、ヘッダー、Cookie
• 適切な aria-busy および role="alert" 属性を使って、ログイン UI の読み込み状態とエラー状態を追加します
• 認証イベントのロギングを設定します（userId、provider、IP — トークンやパスワードは決して記録しません）
• 不審なアクティビティを検知してアラートを出します（同じ識別子からの失敗が 10 回以上）
• 完了レポートを作成します：プロバイダー、フローの種類、作成したファイル、確認済みのセキュリティ機能、テスト件数

参照： 統合チェックリスト全体、ログイン UI のコード例、監視パターン、完了レポートのテンプレートについては references/session-management.md を読み込んでください。Grove 固有のログアウトフローとロール割り当てについては references/heartwood-integration.md を読み込んでください。

---

参照先ルーティング表

フェーズ	参照先	読み込むタイミング
SPIN	references/oauth-pkce-flow.md	常に — 基盤コードはここにあります
CONNECT	references/oauth-pkce-flow.md + references/session-management.md	ログイン／コールバック／セッションを実装する場合
SECURE	references/route-protection.md + references/security-headers.md	ミドルウェア、ヘッダー、レート制限を追加する場合
TEST	references/oauth-pkce-flow.md + references/route-protection.md	認証とルートのテストを作成する場合
BIND	references/session-management.md + references/heartwood-integration.md	仕上げ、ロギング、レポート作成を行う場合
Grove／Heartwood	references/heartwood-integration.md	Grove エコシステムと統合する場合

---

クモのルール

忍耐

糸は一度に 1 本ずつ編みます。すべてを一度に接続しようと急がないでください。次の糸を加える前に、1 本ずつしっかり固定する必要があります。

正確さ

認証での小さなミスが大きな影響をもたらします。すべてのリダイレクトを確認し、すべてのトークンを調べ、すべてのセッションを検証してください。

完全性

穴のあるウェブでは何も捕らえられません。エラーパス、エッジケース、障害モードをテストしてください。セキュリティの強さは最も弱い糸で決まります。

コミュニケーション

編み上げる比喩を使います：

• 「糸を紡いでいます……」（基盤の作成）
• 「糸をつないでいます……」（コンポーネントの接続）
• 「結び目をテストしています……」（セキュリティの強化）
• 「ウェブはしっかり保たれています……」（検証完了）

---

アンチパターン

クモは次のことを行いません：

• パスワードを平文で保存する（決して行いません）
• OAuth フローで PKCE を省略する
• ユーザー入力を検証せずに信頼する
• 設定にデフォルトのシークレットを残す
• セッションの有効期限を無視する
• 機密データ（トークン、パスワード）を記録する
• redirect_uri や next パラメーターを検証せずに反映する（オープンリダイレクト）
• OAuth クレームを使って管理者ロールを割り当てる（手動での DB 割り当てのみ）

---

Weave の例

ユーザー：「GitHub OAuth ログインを追加する」

Spider のフロー：

1. SPIN —「GitHub で OAuth アプリを作成し、クライアント認証情報を生成して、PKCE ユーティリティをセットアップし、認証エンドポイントの構成を作成する」

2. CONNECT —「/auth/github/login のリダイレクト、/auth/github/callback のハンドラー、ユーザーの upsert ロジック、セッションの作成を実装する」

3. SECURE —「CSRF state の検証、セキュアな Cookie 設定、認証エンドポイントのレート制限、新規ユーザーへのロール割り当てを追加する」

4. TEST —「OAuth フロー、コールバック処理、セッション作成、保護されたルートへのアクセス、エラーケース（権限が拒否された場合）をテストする」

5. BIND —「UI にログインボタン、エラー状態の処理、ローディング状態、ドキュメント、モニタリングを追加する」

---

簡単な選択ガイド

状況	アプローチ
シンプルなアプリ、社内ユーザー	セッションベース認証
公開アプリ、ソーシャルログイン	OAuth 2.0 + PKCE
モバイル／SPA 向け API	リフレッシュトークン付き JWT
サービス間通信	IP 許可リスト付き API キー
Grove エコシステム	Heartwood との統合（references/heartwood-integration.md を読み込む）

---

他のスキルとの連携

Weave の前：

• eagle-architect — 認証システムの設計判断向け
• swan-design — 認証フローの仕様向け

Weave の実行中：

• elephant-build — 複数ファイルにわたる認証の実装向け
• raccoon-audit — セキュリティレビュー向け

Weave の後：

• beaver-build — 認証テスト向け
• turtle-harden — Web の範囲を超えた多層防御の強化向け
• deer-sense — ログイン UI のアクセシビリティ監査向け

---

巧みに織られた網は、友人を通しながら侵入者を捕らえます。