# ⚛️ Next.js での OIDC (BFF) の実装例
[OAuth の資料](README.md) の OIDC のシーケンス (1〜5) を、Next.js (App Router) の Route Handler 2 つで書いた例です。Next.js のサーバーが機密クライアント (BFF) になり、トークンはブラウザに渡しません。

流れがつかめるよう、エラーの扱い・IdP を増やす仕組み・セキュリティの細かい確認は省いています。このアプリで実際に気をつけていることは [identity の README](https://github.com/theindiehacker/app.fastship.jp/blob/main/frontend/src/features/identity/README.md) にあります。

使うライブラリ:
- [openid-client](https://github.com/panva/openid-client): OP との通信 (認可リクエストの URL・トークンの交換・ID トークンの検証)
- [iron-session](https://github.com/vvo/iron-session): Cookie に置く値の暗号化

## 🗺️ シーケンス図

```mermaid
sequenceDiagram
    actor User as 🥸 エンドユーザー
    participant Start as 🖥️ /oauth/google
    participant Callback as 🖥️ /oauth/google/callback
    participant Google as 🛡️ Google (OP)

    rect rgb(150, 150, 150)
        Note over User,Start: 1. フロー開始
        User->>Start: GET /oauth/google
        Start->>Start: 🎲 state・🧷 nonce・🧩 code_verifier を作り、<br/>暗号化した Cookie に覚える
        Start-->>User: 302 Google の認可エンドポイント<br/>(state・nonce・code_challenge 付き)
    end

    rect rgb(150, 150, 150)
        Note over User,Google: 2. 🎫 認可コード取得
        User->>Google: ログイン・同意
        Google-->>User: 302 /oauth/google/callback?code=🎫&state=🎲
    end

    rect rgb(150, 100, 100)
        Note over User,Google: 3. 🔑 トークン取得
        User->>Callback: GET /oauth/google/callback?code=🎫&state=🎲
        Callback->>Callback: 🎲 state が Cookie の値と同じか確かめる
        Callback->>Google: 🎫 認可コード・🧩 code_verifier・client_secret を送る
        Google-->>Callback: 🔑 アクセストークン・🆔 ID トークン
    end

    rect rgb(100, 120, 150)
        Note over Callback,Google: 4. 🆔 ID トークンの検証
        Callback->>Google: 🔐 公開鍵 (JWKS) を取る
        Callback->>Callback: 署名・iss・aud・exp・🧷 nonce を確かめる
    end

    rect rgb(150, 150, 150)
        Note over User,Callback: 5. ✅ ログイン
        Callback->>Callback: iss と sub で利用者を探し (初めてなら登録)、<br/>ログイン前の Cookie を消してセッションを作る
        Callback-->>User: 302 ログインした後の画面<br/>Set-Cookie: 🍪 セッション
    end
```

上の 1〜5 は、下のコードのコメントの番号と対応しています。openid-client が受け持つのは、3 と 4 の大部分です。

## 📄 コード

### OP の設定

OP のエンドポイントと公開鍵の URL は、`/.well-known/openid-configuration` から取ります (discovery)。

`lib/google.ts`

```ts
import * as client from "openid-client";

// Google の OP の設定と、このアプリの client_id・client_secret
export async function google(): Promise<client.Configuration> {
  const config = await client.discovery(
    new URL("https://accounts.google.com"),
    process.env.GOOGLE_CLIENT_ID!,
    process.env.GOOGLE_CLIENT_SECRET!,
  );
  // 4. ID トークンの署名を、公開鍵 (jwks_uri) で確かめるようにする
  client.enableNonRepudiationChecks(config);
  return config;
}

// 認可コードを受け取るコールバックの URL。Google の OAuth クライアントの「承認済みのリダイレクト URI」に登録する
export const redirectUri = `${process.env.APP_URL}/oauth/google/callback`;
```

### 1. フロー開始

`app/oauth/google/route.ts`

```ts
import { sealData } from "iron-session";
import { cookies } from "next/headers";
import { NextResponse } from "next/server";
import * as client from "openid-client";
import { google, redirectUri } from "@/lib/google";

const password = process.env.SESSION_SECRET!;

export async function GET() {
  // 1. 🎲 state・🧷 nonce・🧩 code_verifier を作る (ログインを始めるたびに作り直す)
  const state = client.randomState();
  const nonce = client.randomNonce();
  const codeVerifier = client.randomPKCECodeVerifier();

  // コールバックで確かめるまで、暗号化した Cookie に覚えておく (10 分)
  (await cookies()).set(
    "login",
    await sealData({ state, nonce, codeVerifier }, { password, ttl: 600 }),
    // Google から戻ってきたときにも送られるよう、SameSite は Lax にする
    { httpOnly: true, secure: true, sameSite: "lax", path: "/", maxAge: 600 },
  );

  // 認可エンドポイントへ送る。code_challenge は code_verifier の SHA-256
  const url = client.buildAuthorizationUrl(await google(), {
    redirect_uri: redirectUri,
    scope: "openid email profile",
    state,
    nonce,
    code_challenge: await client.calculatePKCECodeChallenge(codeVerifier),
    code_challenge_method: "S256",
  });
  return NextResponse.redirect(url);
}
```

### 2. 🎫 認可コード取得

Google の画面でのことなので、コードはありません。Google が `redirect_uri` に認可コードと state を付けて、利用者を戻します。

### 3〜5. コールバック

`app/oauth/google/callback/route.ts`

```ts
import { sealData, unsealData } from "iron-session";
import { cookies } from "next/headers";
import { type NextRequest, NextResponse } from "next/server";
import * as client from "openid-client";
import { google, redirectUri } from "@/lib/google";
import { findOrCreateUser } from "@/lib/users";

const password = process.env.SESSION_SECRET!;

export async function GET(request: NextRequest) {
  const cookieStore = await cookies();
  // 1. で覚えた値 (Cookie が無い・改ざんされているときは、ログインし直してもらう)
  const login = await unsealData<{
    state: string;
    nonce: string;
    codeVerifier: string;
  }>(cookieStore.get("login")?.value ?? "", { password });

  // 3. 🎲 state を確かめ、🎫 認可コードと 🧩 code_verifier を送って、トークンに交換する。
  // 4. ID トークンの署名・iss・aud・exp・🧷 nonce も、openid-client がここで確かめる
  const tokens = await client.authorizationCodeGrant(
    await google(),
    new URL(`${redirectUri}${request.nextUrl.search}`),
    {
      expectedState: login.state,
      expectedNonce: login.nonce,
      pkceCodeVerifier: login.codeVerifier,
      idTokenExpected: true,
    },
  );
  const claims = tokens.claims()!;

  // 5. iss と sub の組で利用者を探す (初めてなら登録する)。
  // メールアドレスで既存の利用者と紐付けるなら、email_verified が true のときだけにする
  const user = await findOrCreateUser({
    iss: claims.iss,
    sub: claims.sub,
    email: claims.email,
    emailVerified: claims.email_verified === true,
  });

  // ログイン前の Cookie を消し、新しい Cookie でセッションを作る (セッション固定攻撃の対策)。
  // トークンはブラウザに渡さない (API を呼ぶなら、サーバー側のセッションストアに置く)
  cookieStore.delete("login");
  cookieStore.set(
    "session",
    await sealData({ userId: user.id }, { password, ttl: 14 * 24 * 60 * 60 }),
    { httpOnly: true, secure: true, sameSite: "lax", path: "/" },
  );
  return NextResponse.redirect(new URL("/", process.env.APP_URL));
}
```

## 🔍 README の手順との対応

| README の OIDC | コード | 誰が確かめるか |
| :-- | :-- | :-- |
| 1. 🎲 state・🧩 code_verifier・🧷 nonce を作って覚える | `route.ts` の `randomState`・`randomPKCECodeVerifier`・`randomNonce` と Cookie | — |
| 1. 認可リクエスト (`response_type=code`・`scope=openid ...`) | `route.ts` の `buildAuthorizationUrl` | — |
| 3. 🎲 state が覚えた値と同じか | `callback/route.ts` の `expectedState` | クライアント (openid-client) |
| 3. 🎫 認可コードを 🔑・🆔 に交換する | `callback/route.ts` の `authorizationCodeGrant` | — |
| 3. 🧩 code_verifier のハッシュが code_challenge と同じか | `pkceCodeVerifier` を送る | OP (Google) |
| 4. 🔐 署名を公開鍵で確かめる | `google.ts` の `enableNonRepudiationChecks` | クライアント (openid-client) |
| 4. iss・aud・exp・🧷 nonce を確かめる | `callback/route.ts` の `expectedNonce` | クライアント (openid-client) |
| 5. iss と sub で利用者を探す・セッションを作り直す | `callback/route.ts` の `findOrCreateUser` と Cookie | — |

## ➕ 実際のアプリで足すもの

この例に、実際のアプリでは次のものを足します。どれも [identity の README](https://github.com/theindiehacker/app.fastship.jp/blob/main/frontend/src/features/identity/README.md) の「実装で気をつけること」に理由があります。

- ログインした後の戻り先 (`?returnTo=`) と、それが自サイトのパスかの確認 (オープンリダイレクトの対策)
- ログインを始める URL を、別のサイトから開かせない (`Sec-Fetch-Site`)
- IdP ごとにコールバックの URL を分け、ログインを始めた IdP と同じかを確かめる (mix-up 攻撃の対策)
- 失敗したとき (同意画面での拒否・state の不一致・認可コードの使い回し) に、ログイン画面に理由を出す
- 302 の応答をキャッシュさせない (`Cache-Control: no-store`)、本番の Cookie の名前に `__Host-` を付ける

このアプリの以前の実装 (この例を、上のものまで含めて書いたもの) は、コミット [`1b44fc7`](https://github.com/theindiehacker/app.fastship.jp/tree/1b44fc7/frontend/src) の `lib/oauth/` と `app/(identity)/oauth/` にあります。
