Email Code認証

概要

Email Code認証は、ユーザーのメールアドレスにワンタイム検証コードを送信します。ユーザーがコードを入力すると認証が完了します — パスワードは不要です。

これは2ステップのフローです：

送信 — アプリがメールアドレスへのコード送信をリクエスト
検証 — ユーザーが受信したコードを入力し、SDKがサーバーで検証

コード送信

検証コードをリクエストします：

const { data, error } = await auth.emailCode.send('[email protected]');

if (error) {
  console.error('コード送信失敗:', error.message);
  return;
}

console.log('コード送信成功');
// data: { attemptId, expiresIn, maskedEmail, isNewUser? }

送信オプション

interface EmailCodeSendOptions {
  /** メール本文の locale */
  locale?: string;
  /** コード長 */
  codeLength?: 6 | 8;
}

レート制限

サーバーはコード送信にレート制限を適用します。同じメールに最近コードが送信された場合、SDKはヘルパーメソッドを提供します：

// コードが保留中か確認
if (auth.emailCode.hasPendingVerification('[email protected]')) {
  const remaining = auth.emailCode.getRemainingTime('[email protected]');
  console.log(`コード送信済み。再送信まであと${remaining}秒お待ちください。`);
}

コード検証

ユーザーがコードを受信したら検証します：

const { data, error } = await auth.emailCode.verify(
  '[email protected]',
  '123456'
);

if (error) {
  console.error('検証失敗:', error.message);
  return;
}

console.log('認証完了:', data.user);
console.log('セッション:', data.session);

検証オプション

interface EmailCodeVerifyOptions {
  /** メールが存在しない場合にアカウントを作成する */
  createAccountIfNotExists?: boolean;
}

保留中の検証ヘルパー

SDKはメモリ内で保留中の検証状態を追跡します：

// メールの検証が保留中か確認
auth.emailCode.hasPendingVerification('[email protected]'); // boolean

// コード有効期限までの残り時間（秒）
auth.emailCode.getRemainingTime('[email protected]'); // number

// 保留状態をクリア（例：ユーザーがメールを変更したい場合）
auth.emailCode.clearPendingVerification('[email protected]');

これらのヘルパーは、カウントダウンタイマーを表示したり、早すぎる再送信を防止するUIの構築に役立ちます。

エラーハンドリング

よくあるEmail Codeエラー：

エラーコード	意味	ユーザーへのアクション
`AR002001`	無効なメール形式	バリデーションメッセージを表示
`AR002002`	レート制限超過	カウントダウンタイマーを表示
`AR002003`	コード期限切れ	再送信を提案
`AR002004`	無効なコード	リトライを許可（回数制限あり）
`AR002005`	失敗回数超過	しばらく待ってから再試行

const { data, error } = await auth.emailCode.verify(email, code);

if (error) {
  switch (error.code) {
    case 'AR002003':
      showMessage('コードの有効期限が切れました。新しいコードを送信しています...');
      await auth.emailCode.send(email);
      break;
    case 'AR002004':
      showMessage('コードが間違っています。もう一度お試しください。');
      break;
    case 'AR002005':
      showMessage('試行回数が多すぎます。しばらくお待ちください。');
      break;
    default:
      showMessage(error.message);
  }
}

完全な例

2ステップのEmail Codeログインフローの全体：

import { createAuthrim } from '@authrim/web';

const auth = await createAuthrim({
  issuer: 'https://auth.example.com',
  clientId: 'my-app',
});

let currentEmail = '';

// ステップ1: コード送信
document.getElementById('send-btn').addEventListener('click', async () => {
  const email = document.getElementById('email-input').value;

  const { data, error } = await auth.emailCode.send(email);
  if (error) {
    alert(error.message);
    return;
  }

  currentEmail = email;
  // UIをコード入力に切り替え
  document.getElementById('email-form').style.display = 'none';
  document.getElementById('code-form').style.display = 'block';
});

// ステップ2: コード検証
document.getElementById('verify-btn').addEventListener('click', async () => {
  const code = document.getElementById('code-input').value;

  const { data, error } = await auth.emailCode.verify(currentEmail, code);
  if (error) {
    alert(error.message);
    return;
  }

  // 認証完了
  window.location.href = '/dashboard';
});

// 戻るボタン（メール変更）
document.getElementById('back-btn').addEventListener('click', () => {
  auth.emailCode.clearPendingVerification(currentEmail);
  document.getElementById('code-form').style.display = 'none';
  document.getElementById('email-form').style.display = 'block';
});

カウントダウンタイマー付き

async function sendCode(email) {
  const { data, error } = await auth.emailCode.send(email);
  if (error) return;

  // カウントダウン開始
  const timer = setInterval(() => {
    const remaining = auth.emailCode.getRemainingTime(email);
    if (remaining <= 0) {
      clearInterval(timer);
      document.getElementById('resend-btn').disabled = false;
      document.getElementById('countdown').textContent = '';
    } else {
      document.getElementById('countdown').textContent = `再送信まで ${remaining}秒`;
      document.getElementById('resend-btn').disabled = true;
    }
  }, 1000);
}

次のステップ

Passkey認証 — WebAuthnベースのパスワードレスログイン
ソーシャルログイン — サードパーティIDプロバイダー
セッション管理 — ログイン後のセッション操作
エラーハンドリング — 包括的なエラーハンドリングガイド