# 二要素認証

Pocket Alert は、Web ダッシュボードとモバイルアプリの両方で TOTP による二要素認証に対応しています。一度有効にすると、パスワードだけではアカウントにログインできなくなります。

設定は [アカウント → セキュリティ](https://pocketalert.app/account/security) から行えます。

## 設定方法

1. **アカウント → セキュリティ** を開き、設定を開始します。QR コードとシークレットが表示されます。
2. Google Authenticator、1Password、Authy、Bitwarden など、任意の TOTP 認証アプリで QR コードを読み取ります。
3. 6 桁のコードを入力して確定します。正しいコードを入力した後に初めて二要素認証が有効になります。
4. 表示されたリカバリーコードを保存してください。各コードは 1 回だけ使用できます。

> **Tip: 設定が途中で中断されても安全です**
>
> 新しく設定を開始しても、既存の二要素認証には影響しません。新しいシークレットは保留スロットに保存され、コードを確定した後にのみ有効なものと置き換わります。そのため、途中でタブを閉じてもアカウントからロックアウトされることはありません。

## ログインの流れの変更点

二要素認証を有効にすると、`POST /v1/auth/login` は JWT を返さなくなります。代わりに、有効期限の短いチャレンジを返します。

```json
{
  "two_factor_required": true,
  "challenge": "eyJhbGciOiJIUzI1NiIs…"
}
```

チャレンジとコードを送信して、本来のトークンと交換します。

```
POST https://api.pocketalert.app/v1/auth/2fa/login
```

```bash
curl -X POST "https://api.pocketalert.app/v1/auth/2fa/login" \
  -H "Content-Type: application/json" \
  -d '{
    "challenge": "eyJhbGciOiJIUzI1NiIs…",
    "code": "482913"
  }'
```

交換に成功すると、通常のログインと同じペイロード（`token`、`name`、`email`、`avatar`）が返されます。`code` フィールドには、6 桁の TOTP コードまたはリカバリーコードのいずれかを指定できます。

チャレンジの有効期間は **5 分**です。

## API キーには影響しません

> **Info: スクリプトは引き続き動作します**
>
> 二要素認証は対話的なログインに適用されます。[API キー](https://pocketalert.app/account/apikeys) は `Token` ヘッダーで認証され、チャレンジは求められません。cron ジョブ、CI パイプライン、監視フックは、これまでと同じようにアラートを送信し続けます。
>
> このため、API キーはサービスごとに範囲を絞って発行することをおすすめします。1 つのキーを無効化しても、ほかのキーには影響しません。

## リカバリーコード

リカバリーコードは 1 回限りの使用で、アトミックに消費されます。同時に 2 つのログインを行っても、同じコードを二重に使うことはできません。**アカウント → セキュリティ** からいつでも新しいセットを発行できます。新しいコードを発行すると、以前のコードは無効になります。

認証アプリとリカバリーコードの両方を失った場合は、サポートまでお問い合わせください。セルフサービスでの回避手段はありません。これは意図的な仕様です。

## ブルートフォース対策

6 桁のコードを 5 回連続で間違えると、アカウントは **15 分間**ロックされ、それ以降の試行には `429` が返されます。カウンターは、ログインが成功したとき、および二要素認証を有効化または無効化したときにリセットされます。チャレンジは 5 分間の有効期間をすべて使えるため、6 桁のコードを推測することを現実的に困難にしているのは、チャレンジの有効期間ではなくこの試行回数の制限です。

## メール通知

アカウントで二要素認証が有効化または無効化されるたびに、メールが届きます。心当たりのないメールが届いた場合は、直ちにパスワードを変更してください。

## エンドポイント

| メソッド | エンドポイント | 用途 |
|--------|----------|---------|
| `GET` | `/v1/auth/2fa/status` | 二要素認証が有効かどうか、残りのリカバリーコードの数 |
| `POST` | `/v1/auth/2fa/setup` | 登録を開始します。シークレットと QR コード用のペイロードを返します |
| `POST` | `/v1/auth/2fa/enable` | コードを確認し、二要素認証を有効にします |
| `POST` | `/v1/auth/2fa/disable` | 二要素認証を無効にします。コードとパスワードが必要です |
| `POST` | `/v1/auth/2fa/recovery-codes` | 新しいリカバリーコードのセットを発行します |
| `POST` | `/v1/auth/2fa/login` | チャレンジとコードを JWT と交換します（認証ヘッダーは不要） |

`/auth/2fa/login` 以外のすべてのエンドポイントには、認証済みのセッションが必要です。

## 関連情報

- [ログイン](https://info.pocketalert.app/api/user/login.md) — ログインフローの最初のステップ
- [はじめに](https://info.pocketalert.app/intro.md) — 認証の概要
