🔧 認証ブロック

認証ブロックは、安全なユーザー認証および認可操作のための純粋なビジネスロジック関数を提供します。これらのブロックは、トークン管理、メール認証、アイデンティティ検証、包括的なエラー処理を扱います。

---

🎯 概要

認証ブロックは次のことを目的として設計されています:

• ユーザーアイデンティティを検証し、認証トークンを管理する
• 安全なワンタイムトークンによるメール認証を処理する
• トークン検証によるパスワードリセット機能をサポートする
• 認証失敗に対する包括的なエラー処理を提供する
• 生成・検証・失効を含むトークンライフサイクルを管理する
• フィンガープリント追跡とリクエスト検証でセキュリティを確保する

---

📋 利用可能な認証ブロック

アイデンティティ管理ブロック

assertIdentityExists

認証データベースにアイデンティティが存在することを検証します。

目的: データベースにユーザーアイデンティティが存在することを検証します

パラメータ:

• db: AuthenticationServiceDataStore['identities'] - 認証サービスのデータベース接続
• identityId: string - 検証対象のアイデンティティの一意な識別子

戻り値: Promise<Result<boolean, AuthenticationNotFoundError | AuthenticationUnexpectedDbError>>

ハンドラープロセス:

• 入力: Identities コレクションと identityId
• 処理: 指定された ID で identities コレクションを照会し、存在を判定します
• 出力: アイデンティティが存在する場合は ok(true)、存在しない場合は適切なエラー
• エラー: 見つからない場合は AuthenticationNotFoundError、DB 障害時は AuthenticationUnexpectedDbError

使用例:

import { blocks } from '@nodeblocks/backend-sdk';

const result = await blocks.assertIdentityExists(database, "identity123");
if (result.isOk()) {
  // アイデンティティが存在するため、認証を続行
}

---

checkEmailIsUniqueInIdentities

メールアドレスが identities コレクションに既に登録されていないことを検証します。

目的: 登録およびメール変更操作のためにメールの一意性を検証します

パラメータ:

• db: AuthenticationServiceDataStore['identities'] - 認証サービスのデータベース接続
• email: string - 一意性を確認するメールアドレス

戻り値: Promise<Result<boolean, AuthenticationConflictError | AuthenticationUnexpectedDbError>>

ハンドラープロセス:

• 入力: Identities コレクションと email
• 処理: 同一メールを持つ既存のアイデンティティを確認します
• 出力: メールが一意なら ok(true)、既に使用されていれば競合エラー
• エラー: メールが存在する場合は AuthenticationConflictError、DB 障害時は AuthenticationUnexpectedDbError

使用例:

import { blocks } from '@nodeblocks/backend-sdk';

const result = await blocks.checkEmailIsUniqueInIdentities(database, "identity@example.com");
if (result.isOk()) {
  // メールは利用可能、登録を続行
}

---

getIdentityIdByEmail

関連付けられたメールアドレスを検索してアイデンティティ ID を取得します。

目的: メールアドレスを用いてアイデンティティ ID を検索します

パラメータ:

• db: AuthenticationServiceDataStore['identities'] - 認証サービスのデータベース接続
• email: string - 検索対象のメールアドレス

戻り値: Promise<Result<string, AuthenticationNotFoundError | AuthenticationUnexpectedError | AuthenticationUnexpectedDbError>>

ハンドラープロセス:

• 入力: Identities コレクションと email
• 処理: メールでアイデンティティを検索し、その ID を抽出します
• 出力: 成功時は ok(identityId)、見つからない場合や失敗時はエラー
• エラー: 見つからない場合は AuthenticationNotFoundError、失敗時は AuthenticationUnexpectedError または AuthenticationUnexpectedDbError

使用例:

import { blocks } from '@nodeblocks/backend-sdk';

const result = await blocks.getIdentityIdByEmail(database.identities, "identity@example.com");
if (result.isOk()) {
  const identityId = result.value;
  // さらなる処理にアイデンティティ ID を使用
}

---

isEmail

文字列が基本的なメールアドレス形式に準拠しているかを検証します。

目的: 正規表現パターンを用いてメール形式を検証します

パラメータ:

• maybeEmail: string - 検証対象のメールアドレス文字列

戻り値: Result<boolean, AuthenticationInvalidInputError>

ハンドラープロセス:

• 入力: メールとして検証する文字列
• 処理: メール正規表現パターンで文字列を検証
• 出力: 有効な場合は ok(true)、無効な場合はエラー結果
• エラー: 形式が一致しない場合は AuthenticationInvalidInputError

使用例:

import { blocks } from '@nodeblocks/backend-sdk';

const result = blocks.isEmail("identity@example.com");
if (result.isOk()) {
  // メール形式は有効、処理を続行
}

---

buildUpdateIdentityPasswordPayload

アイデンティティのパスワード更新用の型安全なペイロードを構築します。

目的: パスワード更新操作のための型安全なペイロードオブジェクトを作成します

パラメータ:

• password: string - アイデンティティに設定する新しいパスワード文字列

戻り値: Result<{ password: string }, never>

ハンドラープロセス:

• 入力: 文字列としてのパスワード
• 処理: パスワードをオブジェクトに包み、Result として返します
• 出力: パスワード文字列を含むオブジェクトの Result
• エラー: エラーは返しません（常に ok）

使用例:

import { blocks } from '@nodeblocks/backend-sdk';

const result = blocks.buildUpdateIdentityPasswordPayload('newSecret123');
if (result.isOk()) {
  // result.value = { password: 'newSecret123' }
  // データベース更新処理にペイロードを使用
}

---

hash

安全なパスワード保存のために、bcrypt のソルトラウンドを用いて文字列をハッシュ化します。

目的: bcrypt を用いてパスワードや機微な文字列を安全にハッシュ化します

パラメータ:

• s: string - ハッシュ化する文字列（通常はパスワード）

戻り値: Promise<Result<string, AuthenticationUnexpectedError>>

ハンドラープロセス:

• 入力: ハッシュ化する文字列（通常はパスワード）
• 処理: ソルトラウンド 10 で bcrypt ハッシュを適用
• 出力: ハッシュ化された文字列、失敗時はエラー
• エラー: bcrypt のハッシュ処理が失敗した場合は AuthenticationUnexpectedError

使用例:

import { blocks } from '@nodeblocks/backend-sdk';

// パスワードハッシュ処理で使用:
const hashResult = await blocks.hash("password123");
if (hashResult.isOk()) {
  const hashedPassword = hashResult.value;
  // ハッシュ済みパスワードをデータベースに保存
}

---

normalizeIdentityWithoutPassword

API 公開の安全性のため、アイデンティティオブジェクトから機微なフィールドを除去します。

目的: API レスポンス前に機微なフィールドを削除してアイデンティティオブジェクトをサニタイズします

パラメータ:

• identity: { password?: string; _id?: string; [key: string]: unknown } - password、_id、その他のプロパティを含む可能性のあるオブジェクト

戻り値: object - password と _id 以外のすべてのプロパティを持つオブジェクト

ハンドラープロセス:

• 入力: password と _id フィールド、その他のプロパティを含む可能性のあるアイデンティティオブジェクト
• 処理: 存在する場合、返却オブジェクトから password と _id を省略
• 出力: password と _id 以外のすべての元のプロパティを持つオブジェクト
• エラー: なし（存在すれば省略）

使用例:

import { blocks } from '@nodeblocks/backend-sdk';

const user = { _id: 'abc', password: 'secret', email: 'a@b.com', name: 'Alice' };
const safeUser = blocks.normalizeIdentityWithoutPassword(user);
// safeUser = { email: 'a@b.com', name: 'Alice' }

const partialUser = { email: 'a@b.com', name: 'Alice' };
const safePartial = blocks.normalizeIdentityWithoutPassword(partialUser);
// safePartial = { email: 'a@b.com', name: 'Alice' }

---

buildUpdateIdentityDeactivatedPayload

非アクティブ化日時とロック状態を含め、アイデンティティを無効化するためのペイロードを構築します。

目的: アイデンティティ無効化操作のための型安全なペイロードオブジェクトを作成します

パラメータ: なし

戻り値: Result<{ deactivatedAt: Date; locked: boolean }, never> - 無効化ペイロードを含む Result

ハンドラープロセス:

• 入力: なし（パラメータ不要）
• 処理: 現在日時を deactivatedAt に設定し、locked を true に設定したペイロードを生成
• 出力: { deactivatedAt: Date; locked: boolean } を含む Result オブジェクト
• エラー: エラーは返しません（常に ok）

使用例:

import { blocks } from '@nodeblocks/backend-sdk';

// Use to generate a deactivation payload for identity update:
const result = blocks.buildUpdateIdentityDeactivatedPayload();
if (result.isOk()) {
  // result.value: { deactivatedAt: Date; locked: true }
  // データベース更新処理にペイロードを使用
}

---

buildUpdateIdentityActivatedPayload

無効化状態の解除とロック解除により、アイデンティティを有効化するためのペイロードを構築します。

目的: アイデンティティ有効化操作のための型安全なペイロードオブジェクトを作成します

パラメータ: なし

戻り値: Result<{ deactivatedAt: null; locked: boolean }, never> - 有効化ペイロードを含む Result

ハンドラープロセス:

• 入力: なし（パラメータ不要）
• 処理: deactivatedAt を null に設定し、locked を false に設定したペイロードを生成
• 出力: { deactivatedAt: null; locked: boolean } を含む Result オブジェクト
• エラー: エラーは返しません（常に ok）

使用例:

import { blocks } from '@nodeblocks/backend-sdk';

// Use to generate an activation payload for identity update:
const result = blocks.buildUpdateIdentityActivatedPayload();
if (result.isOk()) {
  // result.value: { deactivatedAt: null; locked: false }
  // データベース更新処理にペイロードを使用
}

---

isEmailVerified

認証目的で、ユーザーのメールが認証済みかどうかを確認します。

目的: 認証フローのためにメール認証状態を検証します

パラメータ:

• emailVerified: boolean - ユーザーのメールが認証済みかを示すブール値

戻り値: Result<boolean, AuthenticationForbiddenError> - 認証済みなら true、未認証なら AuthenticationForbiddenError

ハンドラープロセス:

• 入力: ユーザーのメールが認証済みかを示す emailVerified ブール値
• 処理: 認証済みであれば ok(true) を返し、そうでなければ AuthenticationForbiddenError を返します
• 出力: 検証状態またはエラーを示す Result<boolean, AuthenticationForbiddenError>
• エラー: メールが未認証の場合は AuthenticationForbiddenError

使用例:

import { blocks } from '@nodeblocks/backend-sdk';

const result = blocks.isEmailVerified(user.emailVerified);
if (result.isOk()) {
  // 認証済みのアクションを続行
} else {
  // 禁止エラーを処理（メール未認証）
}

---

compareStringAgainstHash

認証検証のため、平文文字列をハッシュ文字列と比較します。

目的: bcrypt の比較を用いてパスワードやその他の機微データを検証します

パラメータ:

• hashedString: string - 比較対象の bcrypt ハッシュ
• stringToCompare: string - 検証する平文文字列

戻り値: Promise<Result<boolean, AuthenticationInvalidInputError | AuthenticationUnexpectedError>>

ハンドラープロセス:

• 入力: hashedString（bcrypt ハッシュ）、stringToCompare（平文文字列）
• 処理: bcrypt を使用して平文文字列とハッシュを比較
• 出力: 文字列が一致すれば ok(true)、一致しなければ err(AuthenticationInvalidInputError)、失敗時は err(AuthenticationUnexpectedError)
• エラー: 入力が一致しない場合は AuthenticationInvalidInputError、比較失敗時は AuthenticationUnexpectedError

使用例:

import { blocks } from '@nodeblocks/backend-sdk';

// 認証フローでの使用:
const result = await blocks.compareStringAgainstHash(identity.hashedPassword, inputPassword);
if (result.isOk()) {
  // パスワードが一致
} else {
  // エラーまたは無効な入力を処理
}

---

トークン管理ブロック

generateOneTimeToken

セキュリティコンテキスト付きで、メール認証のためのワンタイムトークンを生成します。

目的: メール認証のための暗号化されたワンタイムトークンを作成します

パラメータ:

• authSecrets: { authEncSecret: string; authSignSecret: string } - 暗号化と署名のための認証シークレット
• jwtSignOptions: SignOptions - JWT 署名の設定オプション
• tokenVerification: TokenVerification - トークン検証のためのセキュリティコンテキスト
• identityId: string - ユーザーアイデンティティの一意な識別子
• email?: string - トークンデータに含める任意のメールアドレス

戻り値: Promise<Result<string, AuthenticationUnexpectedError>>

ハンドラープロセス:

• 入力: 認証シークレット、JWT 署名オプション、トークン検証コンテキスト、identityId、任意の email
• 処理: ペイロードを構築し、提供されたシークレットでワンタイムトークンを署名・暗号化
• 出力: 成功時は暗号化されたトークン文字列
• エラー: 構築/署名/暗号化に失敗した場合は AuthenticationUnexpectedError

使用例:

import { blocks } from '@nodeblocks/backend-sdk';

const result = await blocks.generateOneTimeToken(
  authSecrets,
  jwtOptions,
  verification,
  "identity123",
  "identity@example.com"
);
if (result.isOk()) {
  const token = result.value;
  // メール認証のためにトークンを保存・送信
}

---

checkOneTimeToken

メールの認証または変更操作のため、ワンタイムトークンを検証・復号します。

目的: 認証のためにワンタイムトークンを検証・復号します

パラメータ:

• authSecrets: { authEncSecret: string; authSignSecret: string } - 暗号鍵と署名鍵を含む認証シークレット
• target: TargetType - 期待されるトークンのターゲット種別（confirm-email, change-email, reset_password）
• token: string - 検証対象の暗号化ワンタイムトークン文字列

戻り値: Promise<Result<JwtPayload, AuthenticationInvalidInputError | AuthenticationUnauthorizedError>>

ハンドラープロセス:

• 入力: 認証シークレット、ターゲット種別、暗号化トークン文字列
• 処理: 認証シークレットの検証、トークンの復号、JWT 署名検証、トークン構造の検証を実施
• 出力: トークン情報を含む復号済み JWT ペイロード、またはエラー
• エラー: シークレットが無効/構造が不正なら AuthenticationInvalidInputError、検証失敗なら AuthenticationUnauthorizedError

使用例:

import { blocks } from '@nodeblocks/backend-sdk';

// Used in email verification flows:
const tokenResult = await blocks.checkOneTimeToken(
  authSecrets,
  'confirm-email',
  encryptedToken
);
if (tokenResult.isOk()) {
  const tokenInfo = tokenResult.value;
  // 検証済みトークン情報を処理
}

---

storeOneTimeToken

後続の検証のため、ワンタイムトークンをデータベースに保存します。

目的: 検証のために暗号化トークンをデータベースに保存します

パラメータ:

• db: Collection - onetimetokens コレクションへアクセス可能なデータベース接続
• oneTimeToken: string - 保存する暗号化トークン文字列

戻り値: Promise<Result<boolean, AuthenticationInvalidInputError | AuthenticationUnexpectedDbError>>

ハンドラープロセス:

• 入力: トークンコレクションと暗号化トークン文字列
• 処理: 後続の検証のためメタデータ付きでトークンを永続化
• 出力: 正常保存時は ok(true)
• エラー: DB 障害時は AuthenticationUnexpectedDbError、入力不正時は AuthenticationInvalidInputError

使用例:

import { blocks } from '@nodeblocks/backend-sdk';

const result = await blocks.storeOneTimeToken(database, encryptedToken);
if (result.isOk()) {
  // トークンの保存に成功、メール送信を続行
}

---

assertValidOneTimeTokenExists

データベースにワンタイムトークンが存在し、なお有効であることを検証します。

目的: データベースにおけるトークンの存在と有効性を検証します

パラメータ:

• db: Collection - ワンタイムトークンを含むデータベースコレクション
• token: string - データベースで検証するトークン文字列

戻り値: Promise<Result<boolean, AuthenticationForbiddenError | AuthenticationUnexpectedDbError>>

ハンドラープロセス:

• 入力: トークンコレクションとトークン文字列
• 処理: 一致するトークンが存在し、失効/期限切れでないことを確認
• 出力: 有効なトークンが存在すれば ok(true)
• エラー: 欠如/無効なら AuthenticationForbiddenError、DB 障害時は AuthenticationUnexpectedDbError

使用例:

import { blocks } from '@nodeblocks/backend-sdk';

const result = await blocks.assertValidOneTimeTokenExists(
  database.onetimetokens,
  "encrypted-token-string"
);
if (result.isOk()) {
  // トークンが有効かつ存在、検証を続行
}

---

invalidateOneTimeToken

再利用を防ぐため、データベース上でワンタイムトークンを無効化します。

目的: 消費後の再利用を防ぐためにトークンを無効化します

パラメータ:

• db: Collection - ワンタイムトークンを含むデータベースコレクション
• token: string - データベースで無効としてマークするトークン文字列

戻り値: Promise<Result<boolean, AuthenticationInvalidInputError | AuthenticationUnexpectedDbError>>

ハンドラープロセス:

• 入力: トークンコレクションとトークン文字列
• 処理: データストアでトークンを無効/使用済みにマークし再利用を防止
• 出力: 正常に無効化できれば ok(true)
• エラー: DB 障害時は AuthenticationUnexpectedDbError、入力不正時は AuthenticationInvalidInputError

使用例:

import { blocks } from '@nodeblocks/backend-sdk';

const result = await blocks.invalidateOneTimeToken(
  database.onetimetokens,
  "encrypted-token-string"
);
if (result.isOk()) {
  // トークンの無効化に成功、再利用を防止
}

---

softDeleteRefreshTokens

指定されたアイデンティティのリフレッシュトークンを、データベース上で論理削除します。

目的: 削除フラグを設定して、アイデンティティのすべてのリフレッシュトークンを無効化します

パラメータ:

• db: Collection - リフレッシュトークンを含む MongoDB コレクション（現在は identities コレクション）
• identityId: string - 論理削除対象のアイデンティティ ID

戻り値: Promise<Result<boolean, AuthenticationInvalidInputError | AuthenticationUnexpectedDbError>> - 成否を示す結果

ハンドラープロセス:

• 入力: MongoDB コレクションとアイデンティティ ID
• 処理: 既に削除されていない、該当アイデンティティのすべてのリフレッシュトークンに delFlg を 1 に設定
• 出力: 成功（true）またはエラーを示す結果オブジェクト
• エラー: データベース障害時は AuthenticationUnexpectedDbError を返します

使用例:

import { blocks } from '@nodeblocks/backend-sdk';

// Used in the deactivation flow to invalidate all refresh tokens for an identity:
const result = await blocks.softDeleteRefreshTokens(db, identityId);
if (result.isOk()) {
  // リフレッシュトークンが論理削除されました
}

---

checkToken

セキュリティチェックとデータベース検証により、認証トークンを検証・処理します。

目的: セキュリティチェックを伴う包括的なトークン検証

パラメータ:

• db: Collection - トークンの保存と検証のための MongoDB コレクション
• authSecrets: AuthSecrets - JWT 検証のための認証シークレット
• request: Request - ヘッダーとメタデータを含む HTTP リクエストオブジェクト
• token: string - 検証する JWT トークン文字列
• target?: string - トークン検証の任意のターゲットコンテキスト

戻り値: Promise<Result<string | object, AuthenticationBlockError>>

ハンドラープロセス:

• 入力: ロガー、データベースコレクション、認証シークレット、リクエストオブジェクト、トークン文字列、任意のターゲット
• 処理: リクエスト情報の抽出、JWT トークンの検証、セキュリティチェックの実施、トークン種別ごとの処理
• 出力: アクセストークンは identityId、ワンタイムトークンはトークンデータ、または適切なステータスのエラー
• エラー: InvalidToken（検証失敗）、UnexpectedDBError（DB 問題）

手順:

1. リクエスト情報（host、ip、fingerprint、userAgent）を抽出
2. セキュリティコンテキストで tokenVerification オブジェクトを構築
3. 認証シークレットで JWT トークンを復号・検証
4. トークンがユーザーアクセストークンか確認:
   • 該当する場合、tokenVerification に対してセキュリティチェックを実施
   • チェックに合格したら identityId を返却
   • 不合格なら AuthenticationInvalidTokenError を返却
5. トークンがワンタイムトークンか確認:
   • 該当する場合、target が期待値と一致するか検証
   • データベースでトークンの有効性（存在し無効でないこと）を確認
   • 有効ならデータベースでトークンを無効化し、トークンデータを返却
   • 無効/未発見なら AuthenticationInvalidTokenError を返却
6. アクセスでもワンタイムでもない場合は AuthenticationUnauthorizedError を返却

使用例:

import { blocks } from '@nodeblocks/backend-sdk';

// Used in authentication handlers:
const result = await blocks.checkToken(
  db.tokens,
  authSecrets,
  request,
  'jwt-token-string',
  'user-session'
);
if (result.isOk()) {
  const tokenData = result.value;
  // 検証済みのトークンデータを処理
}

---

メール認証ブロック

sendEmail

検証フローのために、提供されたメールサービスを使用してワンタイムトークン（任意）付きのメールを送信します。

目的: 認証や招待フローのため、トークンを埋め込んだ認証メールを送信します

パラメータ:

• mailService: MailService - メール送信用のメールサービスインスタンス
• sender: string - 送信者メールアドレス（from）
• emailConfig: { bodyTemplate: string; subject: string; urlTemplate: string } - 本文テンプレート、件名、URL テンプレートを含むメール設定
• email: string - 受信者のメールアドレス
• oneTimeToken?: string - メール本文に含める任意のワンタイムトークン

戻り値: Promise<Result<boolean, AuthenticationUnexpectedError>>

ハンドラープロセス:

• 入力: メールサービスインスタンス、送信者メール、メール設定（本文テンプレート、件名、URL テンプレート）、受信者メール、任意のワンタイムトークン
• 処理: 提供されたテンプレートとトークンでメール本文を生成し、メールサービス経由で送信
• 出力: 送信成功時は ok(true)、失敗時はエラー
• エラー: 送信失敗またはメールサービスが失敗を返した場合は AuthenticationUnexpectedError

使用例:

import { blocks } from '@nodeblocks/backend-sdk';

// Used in verification or invitation flows:
const result = await blocks.sendEmail(
  mailService,
  'no-reply@example.com',
  {
    bodyTemplate: 'Please verify your email: {{url}}',
    subject: 'Verify your email',
    urlTemplate: 'https://example.com/verify?token={{token}}',
  },
  'identity@example.com',
  'onetime-token-string'
);
if (result.isOk()) {
  // メールの送信に成功
}

---

getConfirmEmailTokenTarget

メール認証のための確認メールトークンターゲット定数を取得します。

目的: 確認メールのターゲット定数を返します

パラメータ: なし

戻り値: Result<TARGET_CONFIRM_EMAIL, never>

ハンドラープロセス:

• 入力: なし
• 処理: 確認メールフローで使用されるトークンターゲット定数を返します
• 出力: Result でラップされた TARGET_CONFIRM_EMAIL
• エラー: なし（ok を返します）

使用例:

import { blocks } from '@nodeblocks/backend-sdk';

const result = blocks.getConfirmEmailTokenTarget();
if (result.isOk()) {
  const target = result.value;
  // トークン検証にターゲットを使用
}

---

getChangeEmailTokenTarget

メール変更の検証のための変更メールトークンターゲット定数を取得します。

目的: 変更メールのターゲット定数を返します

パラメータ: なし

戻り値: Result<TARGET_CHANGE_EMAIL, never>

ハンドラープロセス:

• 入力: なし
• 処理: メール変更フローで使用されるトークンターゲット定数を返します
• 出力: Result でラップされた TARGET_CHANGE_EMAIL
• エラー: なし（ok を返します）

使用例:

import { blocks } from '@nodeblocks/backend-sdk';

const result = blocks.getChangeEmailTokenTarget();
if (result.isOk()) {
  const target = result.value;
  // メール変更フローのトークン検証にターゲットを使用
}

---

getResetPasswordTokenTarget

パスワードリセットの検証のためのリセットパスワードトークンターゲット定数を取得します。

目的: リセットパスワードのターゲット定数を返します

パラメータ: なし

戻り値: Result<TARGET_RESET_PASSWORD, never>

ハンドラープロセス:

• 入力: なし
• 処理: パスワードリセットフローで使用されるトークンターゲット定数を返します
• 出力: Result でラップされた TARGET_RESET_PASSWORD
• エラー: なし（ok を返します）

使用例:

import { blocks } from '@nodeblocks/backend-sdk';

const result = blocks.getResetPasswordTokenTarget();
if (result.isOk()) {
  const target = result.value;
  // パスワードリセットフローのトークン検証にターゲットを使用
}

---

セキュリティ検証ブロック

getFingerprint

セキュリティ追跡のため、リクエストヘッダーからフィンガープリントヘッダーを抽出・検証します。

目的: リクエストヘッダーからセキュリティフィンガープリントを抽出・検証します

パラメータ:

• headers: Request['headers'] - フィンガープリント情報を含む Express のリクエストヘッダー

戻り値: Result<string | undefined, AuthenticationUnprocessableEntityError>

ハンドラープロセス:

• 入力: HTTP ヘッダーオブジェクト
• 処理: フィンガープリントヘッダーを読み取り検証し、文字列または undefined を返します
• 出力: 抽出されたフィンガープリント、または形式不正時のエラー
• エラー: ヘッダー形式の不正/欠如時は AuthenticationUnprocessableEntityError

使用例:

import { blocks } from '@nodeblocks/backend-sdk';

const result = blocks.getFingerprint(request.headers);
if (result.isOk()) {
  const fingerprint = result.value;
  // トークン検証にフィンガープリントを使用
}

---

extractTokenFromAuthorizationHeader

認証のため、Authorization ヘッダーから Bearer トークンを抽出します。

目的: Authorization ヘッダーを解析・検証して Bearer トークンを抽出します

パラメータ:

• authorization: string - Authorization ヘッダー文字列（例: 'Bearer <token>'）

戻り値: Result<string, AuthenticationBadRequestError | AuthenticationUnauthorizedError> - 抽出したトークンまたはエラー詳細を含む結果

ハンドラープロセス:

• 入力: HTTP リクエストの Authorization ヘッダー文字列
• 処理: ヘッダーを分割して 'Bearer' スキームを確認し、トークンを抽出
• 出力: 有効な場合はトークン文字列、欠如時はエラー
• エラー: ヘッダー欠如/形式不正なら AuthenticationBadRequestError、トークンがない場合は AuthenticationUnauthorizedError

使用例:

import { blocks } from '@nodeblocks/backend-sdk';

// Used in authentication middleware:
const tokenResult = blocks.extractTokenFromAuthorizationHeader(request.headers.authorization || '');
if (tokenResult.isOk()) {
  const token = tokenResult.value;
  // さらなる認証にトークンを使用
}

---

buildTokenVerification

セキュリティ検証のため、リクエストデータからトークン検証オブジェクトを構築します。

目的: トークン検証のためのセキュリティコンテキストを構築します

パラメータ:

• request: Request - ヘッダーと IP 情報を含む Express のリクエストオブジェクト
• target: TargetType - トークンのターゲット種別（confirm-email、change-email、reset_password）
• fingerprint: string - 追跡用のセキュリティフィンガープリント文字列

戻り値: Result<TokenVerification, never>

ハンドラープロセス:

• 入力: HTTP リクエストオブジェクト、トークンターゲット種別、フィンガープリント
• 処理: リクエストのメタデータ（host、ip、userAgent）を抽出し、検証オブジェクトを構築
• 出力: 署名/検証フローのための TokenVerification オブジェクト
• エラー: なし（ok を返します）

使用例:

import { blocks } from '@nodeblocks/backend-sdk';

const result = blocks.buildTokenVerification(request, target, fingerprint);
if (result.isOk()) {
  const verification = result.value;
  // トークン生成に検証オブジェクトを使用
}

---

buildUpdateIdentityEmailAndEmailVerifiedPayload

アイデンティティのメールを更新し、emailVerified を true に設定するためのペイロードを構築します。

目的: メール認証のための更新ペイロードを作成します

パラメータ:

• email: string - アイデンティティに割り当てる新しいメールアドレス

戻り値: Result<{ email: string; emailVerified: boolean }, never>

ハンドラープロセス:

• 入力: メール文字列
• 処理: email と emailVerified: true を設定した更新ペイロードを生成
• 出力: Result でラップされたペイロードオブジェクト
• エラー: なし（ok を返します）

使用例:

import { blocks } from '@nodeblocks/backend-sdk';

const result = blocks.buildUpdateIdentityEmailAndEmailVerifiedPayload("user@example.com");
if (result.isOk()) {
  const updatePayload = result.value;
  // データベースでアイデンティティを更新するために updatePayload を使用
}

---

normalizeEmptyBody

API ハンドラーのための空レスポンスボディを正規化します。

目的: 空の API レスポンスを標準化します

パラメータ: なし

戻り値: object

ハンドラープロセス:

• 入力: なし
• 処理: 一貫した空レスポンスのために空オブジェクトを返します
• 出力: {}
• エラー: なし

使用例:

import { blocks } from '@nodeblocks/backend-sdk';

const emptyBody = blocks.normalizeEmptyBody();
// 一貫した空レスポンスのために {} を返します

---

🔗 関連ドキュメント

• 認証の概要 - 認証ドメインの概要