🛣️ 認証ルート
ルートは Express ミドルウェアではなく SDK のコンポーザーです。共通タスクマップを使用してエンドポイントを選択し、authServiceでサポートされる API をマウントしてください。個々のルートを読む前に Bearer ワークフローを試してください。以下の各ルートはスキーマとフィーチャへのリンクを含み、リクエスト検証と合成が表示されたままになります。
一覧
共有ソースコンテキストを表示
import {ok} from 'neverthrow';
import {identity as noop, pick, tap} from 'ramda';
import {
assertDoesNotMatch,
assertIdentityExists,
assertMatches,
assertValidOneTimeTokenExists,
AuthenticationBadRequestError,
AuthenticationConflictError,
AuthenticationForbiddenError,
AuthenticationInvalidInputError,
AuthenticationInvalidTokenError,
AuthenticationNotFoundError,
AuthenticationUnauthorizedError,
AuthenticationUnexpectedDBError,
AuthenticationUnexpectedDbError,
AuthenticationUnexpectedError,
AuthenticationUnprocessableEntityError,
buildTokenVerification,
buildUpdateIdentityActivatedPayload,
buildUpdateIdentityDeactivatedPayload,
buildUpdateIdentityEmailAndEmailVerifiedPayload,
buildUpdateIdentityPasswordPayload,
checkEmailIsUniqueInIdentities,
checkOneTimeToken,
checkToken as checkTokenBlock,
compareStringAgainstHash,
createMfaCode,
createMfaToken,
extractTokenFromAuthorizationHeader,
generateOneTimeToken,
getChangeEmailTokenTarget,
getFingerprint,
getIdentityIdByEmail,
getMfaChallengeTokenTarget,
getResetPasswordTokenTarget,
hash,
invalidateOneTimeToken,
isEmail,
isEmailVerified,
MfaInvalidCodeError,
MfaUnexpectedError,
normalizeBearerLoginResponse,
normalizeBearerRefreshResponse,
normalizeCookieLoginResponse,
sendEmail,
sendMfaCode,
softDeleteRefreshTokens,
storeOneTimeToken,
verifyMfaCode,
} from '../blocks/authentication';
import {normalizeEmptyBody} from '../blocks/common';
import {getIdentityById, updateIdentity} from '../blocks/identity';
import {
buildAcceptInvitationPayload,
buildCheckConfirmEmailTokenPayload,
buildCheckInvitationTokenPayload,
checkToken,
confirmEmail,
confirmEmailTerminator,
createAccessToken,
createRefreshToken,
generateOnetimeToken,
getInvitationById,
getInvitationIdFromTokenInfo,
invalidateOnetimeToken,
isPendingInvitation,
loginWithCredentials,
loginWithOnetimeToken,
logout,
logoutTerminator,
refreshToken,
registerCredentials,
registerTerminator,
restoreOnetimeToken,
sendVerificationEmail,
sendVerificationEmailTerminator,
setResponseCookie,
updateInvitation,
} from '../handlers';
import {
applyPayloadArgs,
compose,
flatMapAsync,
ifElse,
lift,
mapMatchingErrorToFalse,
match,
orThrow,
RouteHandlerPayload,
withLogging,
withRoute,
} from '../primitives';
import {whenCookieAuth} from '../utils/cookie';
import {checkIdentityType, isAuthenticated, isSelf, some} from '../validators';
詳細
registerCredentialsRoute
実装
エンドポイント: POST /auth/register
資格情報を使用して登録します。
アクセス: パブリック。
リクエスト: registerCredentialsSchema が JSON の資格情報と任意の招待トークンを検証します。
パイプライン: 招待トークン付きのリクエストでは、checkToken と registerCredentials の前後で Invitation ハンドラーを実行します。通常のリクエストでは registerCredentials を直接実行し、続けて registerTerminator を実行します。
成功: {email, id} を含む 201 を返します。
失敗: 400 は不足または不正な入力、401 は無効な招待トークン、404 は存在しない招待、422 は重複するアイデンティティ、500 は永続化の失敗です。完全なソースを表示
loginWithCredentialsRoute
実装
エンドポイント: POST /auth/login
資格情報を使用してログインします。
アクセス: パブリック。
リクエスト: loginWithCredentialsSchema が JSON のメールアドレス、パスワード、および任意のフィンガープリントを検証します。
パイプライン: loginWithCredentials を実行します。MFA 分岐ではチャレンジを生成して送信し、セッション分岐では createAccessToken、createRefreshToken、任意の setResponseCookie、モード固有の正規化を実行します。
成功: MFA トークン、cookie モードの cookie 付き {id}、または Bearer の {accessToken, id, refreshToken} を含む 200 を返します。
失敗: ロック済みまたは誤った資格情報は 401、MFA の失敗は 400 または 500 です。完全なソースを表示
resendMfaCodeRoute
実装
エンドポイント: POST /auth/mfa/resend
代替の MFA チャレンジを発行します。
アクセス: 有効な MFA チャレンジトークンを持つ呼び出し元にはパブリックです。
リクエスト: resendMfaCodeSchema がトークンと任意のフィンガープリントを検証します。
パイプライン: getFingerprint、getMfaChallengeTokenTarget、checkToken、createMfaCode、createMfaToken、sendMfaCode、レスポンス選択の順に実行します。
成功: 置き換え用チャレンジトークンを含む 200 を返します。
失敗: 400 は無効なトークンまたはコード入力、401 はトークン検証失敗、500 はトークン、データベース、またはメールの失敗です。完全なソースを表示
verifyMfaCodeRoute
実装
エンドポイント: POST /auth/mfa/verify
MFA チャレンジを検証します。
アクセス: チャレンジトークンとコードを持つ呼び出し元にはパブリックです。
リクエスト: verifyMfaCodeSchema がトークン、コード、フィンガープリントを検証。
パイプライン: ターゲット、フィンガープリント、トークンを確認し、トークンを無効化して verifyMfaCode を実行します。その後アイデンティティを取得し、createAccessToken、createRefreshToken、任意の setResponseCookie、モード固有の正規化を実行します。
成功: cookie モードでは cookie 付き {id}、Bearer モードではセッショントークンを含む 200 を返します。
失敗: 400 は無効なコードまたは入力、401 は無効なトークン、403 は無効化済みトークン、404 は存在しないアイデンティティ、500 は永続化またはセッションの失敗です。完全なソースを表示
logoutRoute
実装
エンドポイント: POST /auth/logout — 現在のセッションを無効化します。認証済み（isAuthenticated()）。
リクエスト: logoutCookieSchema または logoutBearerSchema。
パイプライン: logout→logoutTerminator。
成功: 204。cookie がクリアされ、有効なリフレッシュレコードが取り消されます。失敗: 認証失敗、401 アイデンティティミスマッチ、または 500 取消失敗。完全なソースを表示
refreshTokenRoute
実装
エンドポイント: POST /auth/token/refresh
アクセス／リフレッシュトークンのペアをローテーションします。
アクセス: 有効なリフレッシュトークンを所持する呼び出し元。ルートバリデーターはありません。
リクエスト: refreshTokenCookieSchema または refreshTokenBearerSchema。
パイプライン: refreshToken、任意の setResponseCookie、cookie の空本文または Bearer トークンの正規化を順に実行します。
成功: cookie モードではローテーション済み cookie を含む 204、Bearer モードでは {accessToken, refreshToken} を含む 200 を返します。
失敗: 401 は無効または再利用済みトークン、422 はトークン不足、400 は失敗した取り消し、500 は永続化の失敗です。完全なソースを表示
checkTokenRoute
実装
エンドポイント: POST /auth/token/check
アクセスまたはワンタイムトークンを検証します。
アクセス: パブリック。本文のトークンから有効性を確立します。
リクエスト: checkTokenSchema が本文トークンを検証。
パイプライン: ハンドラーではなくブロックの checkToken を実行し、続けて orThrow を実行します。
成功: 検証済みの tokenInfo を含む 200 を返します。有効なワンタイムトークンは消費されます。
失敗: 400 は無効なトークンまたはセキュリティチェック失敗、401 は検証失敗、500 はワンタイムトークンのデータベース失敗です。完全なソースを表示
deleteRefreshTokensRoute
実装
エンドポイント: DELETE /auth/:identityId/refresh-tokens
アイデンティティのリフレッシュトークンレコードを取り消します。
アクセス: 認証済みの管理者または一致するアイデンティティです。
リクエスト: deleteRefreshTokensSchema がパス ID を検証。
パイプライン: softDeleteRefreshTokens、空本文の正規化、orThrow を順に実行します。
成功: アクティブなリフレッシュレコードが一致しない場合も含めて 204 を返します。
失敗: 認証または認可の失敗、あるいは 500 のデータベース失敗です。完全なソースを表示
loginWithOnetimeTokenRoute
実装
エンドポイント: POST /auth/ott/login
パスワードレスログインを完了します。
アクセス: アクティブでログイン用途のワンタイムトークンを持つ呼び出し元にはパブリックです。
リクエスト: loginWithOnetimeTokenSchema が本文のトークンとフィンガープリントを検証します。
パイプライン: loginWithOnetimeToken、トークン無効化、createAccessToken、createRefreshToken、任意の setResponseCookie、モード固有の正規化を順に実行します。
成功: cookie モードでは cookie 付き {id}、Bearer モードではセッション本文を含む 200 を返します。
失敗: 401 は検証失敗、403 は不正または無効なトークン、404 は存在しないアイデンティティ、またはセッション生成の失敗です。完全なソースを表示
generateOnetimeTokenRoute
実装
エンドポイント: POST /auth/ott/generate
カスタムフロー用のワンタイムトークンを生成します。
アクセス: 認証済み管理者です。
リクエスト: スキーマは合成されません。ランタイムはオブジェクトの JSON tokenData を要求し、target と fingerprint を受け入れます。
パイプライン: generateOnetimeToken を実行します。
成功: ハンドラーが成功した Result<RouteHandlerPayload> を含むデフォルトの 200 を返します。このレガシールートにはターミネーターがなく、authService によってマウントされません。
失敗: 400 は無効なデータまたは挿入結果、500 は生成またはデータベースの失敗です。完全なソースを表示
restoreOnetimeTokenRoute
実装
エンドポイント: POST /auth/ott/restore
無効化されたワンタイムトークンを復元します。
アクセス: 認証済み管理者です。
リクエスト: スキーマは合成されません。ランタイムは本文の token を読み取ります。
パイプライン: restoreOnetimeToken を実行します。
成功: ハンドラーが成功した Result<RouteHandlerPayload> を含むデフォルトの 200 を返します。一致するレコードが 0 件でも成功します。
失敗: 401 はデコード不能なトークン、422 はステートレスでないトークン、500 は更新の失敗です。完全なソースを表示
invalidateOnetimeTokenRoute
実装
エンドポイント: POST /auth/ott/invalidate
ワンタイムトークンを無効化します。
アクセス: 認証済み管理者です。
リクエスト: スキーマは合成されません。ランタイムはパイプラインコンテキストまたは本文から token と fingerprint を読み取ります。
パイプライン: invalidateOnetimeToken を実行します。
成功: ハンドラーが成功した Result<RouteHandlerPayload> を含むデフォルトの 200 を返します。一致するレコードが 0 件でも成功します。
失敗: 422 は不足、不正、またはステートレスでない入力、500 は更新の失敗です。完全なソースを表示
sendVerificationEmailRoute
実装
エンドポイント: POST /auth/:identityId/send-verification-email
確認メールを送信します。
アクセス: 認証済みの管理者または一致するアイデンティティです。
リクエスト: sendVerificationEmailSchema がパスIDと本文フィンガープリントを検証。
パイプライン: sendVerificationEmail、続けて sendVerificationEmailTerminator を実行します。
成功: トークンの保存とメール配信が成功すると 204 を返します。
失敗: 400 は無効または不足している構成もしくはメール、404 は存在しないアイデンティティ、501 はトークン生成失敗、500 は保存またはメールの失敗です。完全なソースを表示
confirmEmailRoute
実装
エンドポイント: POST /auth/confirm-email
メール確認トークンを確認します。
アクセス: 確認トークンを持つ呼び出し元にはパブリックです。
リクエスト: confirmEmailSchema が本文トークンを検証。
パイプライン: buildCheckConfirmEmailTokenPayload、ハンドラーの checkToken、confirmEmail、confirmEmailTerminator を順に実行します。
成功: 保存済みトークンを消費してアイデンティティを確認済みにし、204 を返します。
失敗: 400 は無効なトークン、401 は検証失敗、403 は不正なトークンデータ、404 は存在しないアイデンティティ、409 は既に確認済み、500 は永続化の失敗です。完全なソースを表示
changeEmailRoute
実装
エンドポイント: PATCH /auth/:identityId/change-email
メールアドレス変更フローを開始します。
アクセス: 認証済みの管理者または一致するアイデンティティです。
リクエスト: changeEmailSchema がパスのアイデンティティと新しいメールアドレスを検証。
パイプライン: アイデンティティと一意性の確認、ターゲットとリクエストセキュリティの構築、トークン生成と保存、sendEmail、空本文の正規化、orThrow を順に実行します。
成功: 確認トークンをメール送信した後に 204 を返します。
失敗: 400 から 500 までにマッピングされる Authentication エラーです。404 のアイデンティティ、409 のメール競合、422 のフィンガープリント形式を含みます。完全なソースを表示
confirmNewEmailRoute
実装
エンドポイント: POST /auth/confirm-new-email
新しいメールアドレスを確認します。
アクセス: メールアドレス変更トークンを持つ呼び出し元にはパブリックです。
リクエスト: confirmNewEmailSchema がトークンとフィンガープリントを検証。
パイプライン: トークンのターゲットとセキュリティ確認、ワンタイムトークンの検証と無効化、メールアドレスの一意性と形式確認、アイデンティティ更新、空本文の正規化、orThrow を順に実行します。
成功: 204 を返します。
失敗: 400 から 500 までにマッピングされる Authentication エラーです。特に 401 の検証、403 の無効なトークン、409 のメール競合、404 のアイデンティティを含みます。完全なソースを表示
sendResetPasswordLinkEmailRoute
実装
エンドポイント: POST /auth/send-reset-password-link-email
パスワードリセットリンクを送信します。
アクセス: パブリックです。
リクエスト: sendResetPasswordLinkEmailSchema が本文メールアドレスを検証。
パイプライン: アイデンティティ検索、リセット用ターゲット、フィンガープリント、セキュリティの構築、トークン生成と保存、sendEmail、空本文の正規化、orThrow を順に実行します。
成功: 204 を返します。
失敗: 404 の不明なメールアドレス、422 の不正なフィンガープリント、500 の生成、保存、メール失敗を含む Authentication エラーです。完全なソースを表示
completePasswordResetRoute
実装
エンドポイント: POST /auth/reset-password
トークンを使用してパスワードリセットを完了します。
アクセス: 有効なリセットトークンを持つ呼び出し元にはパブリックです。
リクエスト: completePasswordResetSchema が置換後のパスワードを検証します。ランタイムは Authorization ヘッダーからもリセットトークンを読み取りますが、そのソースパラメーターは現在スキーマでコメントアウトされています。
パイプライン: トークンの抽出と確認、アイデンティティとパスワードの比較、トークン無効化、パスワードのハッシュ化と更新、通知メール、空本文の正規化、orThrow を順に実行します。
成功: 204 を返します。
失敗: 400 から 500 までにマッピングされる Authentication エラーです。401 のトークン失敗、403 の無効なトークン、404 のアイデンティティを含みます。完全なソースを表示
changePasswordRoute
実装
エンドポイント: PATCH /auth/:identityId/change-password
認証済みアイデンティティのパスワードを変更します。
アクセス: 認証済みの管理者または一致するアイデンティティです。
リクエスト: changePasswordSchema がパスのアイデンティティ、現在のパスワード、新しいパスワードを検証。
パイプライン: アイデンティティ検索、現在と新しいパスワードの比較、ハッシュ化と更新、リフレッシュトークンの取り消し、sendEmail、空本文の正規化、orThrow を順に実行します。
成功: 204 を返します。
失敗: 現在のパスワードが無効または再利用済みである場合と、アイデンティティが存在しない場合を含む、400 から 500 までにマッピングされる Authentication エラーです。完全なソースを表示
deactivateRoute
実装
エンドポイント: POST /auth/deactivate
アイデンティティを非アクティブ化します。
アクセス: 認証済みの管理者、または本文の identityId です。
リクエスト: deactivateSchema が本文のアイデンティティ ID を検証。
パイプライン: アイデンティティ検索と確認済みメールのガード、非アクティブ化の更新、リフレッシュトークンの取り消し、モードに応じたアクセストークン検証、条件付きメール、空本文の正規化、orThrow を順に実行します。
成功: 204 を返します。
失敗: 認証または認可の失敗、あるいは 400 から 500 までにマッピングされる Authentication エラーです。完全なソースを表示
activateRoute
実装
エンドポイント: POST /auth/activate
アイデンティティを再アクティブ化します。
アクセス: 認証済み管理者です。
リクエスト: activateSchema が JSON アイデンティティ ID を検証。
パイプライン: アイデンティティ検索、確認済みメールのガード、アクティブ化の更新、空本文の正規化、orThrow を順に実行します。
成功: 204 を返します。
失敗: 認証または管理者の失敗、あるいは 400 から 500 までにマッピングされる Authentication エラーです。完全なソースを表示