メインコンテンツまでスキップ
バージョン: 0.9.0 (最新)

🔐 認証ユーティリティ

Nodeblocks SDKは、トークン管理、バリデーション、セキュリティのための包括的な認証ユーティリティを提供します。これらのユーティリティは、ベアラートークン、クッキーベースの認証、およびさまざまなユースケース用のさまざまなトークンタイプを処理します。

🎯 概要​

認証ユーティリティは、ユーザーとアプリケーションの両方の認証のための安全なトークン生成、バリデーション、管理を提供します。複数のトークンタイプとセキュリティバリデーションメカニズムをサポートします。

主な機能​

  • 複数のトークンタイプ: ユーザーアクセス、アプリアクセス、リフレッシュ、ワンタイムトークン
  • セキュリティバリデーション: フィンガープリント、IP、ユーザーエージェントバリデーション
  • 柔軟な認証: ベアラートークンとクッキーベースの認証
  • JWT統合: JSON Web Token署名と検証

🔑 トークン生成​

generateUserAccessToken​

セキュリティバリデーションメタデータを持つ暗号化されたユーザーアクセストークンを作成します。

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

const { generateUserAccessToken } = utils;

const token = generateUserAccessToken(
  authSecrets,
  { jwtSignOptions: { expiresIn: '24h' }, stateful: true },
  identityId,
  {
    fingerprint: 'device-fingerprint',
    ip: '192.168.1.1',
    domain: 'example.com',
    userAgent: 'Mozilla/5.0...'
  }
);

パラメータ:

  • authSecrets: 暗号化/署名用の認証シークレット
  • opts: JWTオプションとステートフル設定
  • identityId: アイデンティティ識別子
  • tokenVerification: バリデーション用のセキュリティコンテキスト

generateAppAccessToken​

サービス間通信用の暗号化されたアプリアクセストークンを作成します。

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

const { generateAppAccessToken } = utils;

const token = generateAppAccessToken(authSecrets, 'app-service-id');

パラメータ:

  • authSecrets: 認証シークレット
  • appId: アプリケーション識別子

generateRefreshToken​

セッション管理用の暗号化されたリフレッシュトークンを作成します。

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

const { generateRefreshToken } = utils;

const token = generateRefreshToken(
  authSecrets,
  'jwt-token-id',
  identityId,
  {
    fingerprint: 'device-fingerprint',
    ip: '192.168.1.1',
    domain: 'example.com',
    userAgent: 'Mozilla/5.0...'
  },
  { jwtSignOptions: { expiresIn: '7d' } }
);

generateOnetimeToken​

一時的なアクセス用のワンタイムトークンを作成します。

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

const { generateOnetimeToken } = utils;

const token = generateOnetimeToken(
  authSecrets,
  { identityId: 'id-123', action: 'password-reset' },
  {
    fingerprint: 'device-fingerprint',
    ip: '192.168.1.1',
    domain: 'example.com',
    userAgent: 'Mozilla/5.0...'
  },
  { expiresIn: '1h' }
);

🔍 トークンバリデーション​

getBearerTokenInfo​

リクエスト認証ヘッダーからトークン情報を抽出します。ベアラートークンのデフォルト認証関数。

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

const { getBearerTokenInfo } = utils;

const tokenInfo = await getBearerTokenInfo(payload);

プロセス:

  1. Authorization: Bearer <token>ヘッダーからトークンを抽出
  2. JWT署名を復号化して検証
  3. トークンタイプ（ユーザーまたはアプリ）をバリデート
  4. ユーザートークンのセキュリティチェックを実行
  5. トークン情報を返す

getCookieTokenInfo​

クッキーからトークン情報を抽出します。クッキーベースのトークン用の認証関数。

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

const { getCookieTokenInfo } = utils;

const tokenInfo = await getCookieTokenInfo(payload);

ユースケース:

  • クッキーベースの認証を持つWebアプリケーション
  • 異なるセキュリティバリデーションルール（IPチェック無効）
  • サーバーサイドセッション管理

defaultRefreshTokenBodyAuth​

リクエストボディから取得したリフレッシュトークンのデフォルト認証関数。リクエストボディで送信されたリフレッシュトークンをフィンガープリントバリデーションとともにバリデートします。

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

const { defaultRefreshTokenBodyAuth } = utils;

const { token, tokenInfo } = await defaultRefreshTokenBodyAuth(
  authSecrets,
  request,
  true, // decryptToken
  logger
);

パラメータ:

  • authSecrets: トークン復号化用の認証シークレット
  • request: リフレッシュトークンを含むHTTPリクエストオブジェクト
  • decryptToken: トークンを復号化してバリデートするかどうか（デフォルト: false）
  • logger: セキュリティチェックロギング用のオプションロガー

プロセス:

  1. request.body.refreshTokenからリフレッシュトークンを抽出
  2. トークン検証コンテキスト（フィンガープリント、IP、ユーザーエージェント）を取得
  3. トークンフォーマットと存在をバリデート
  4. JWT署名を復号化して検証（decryptTokenがtrueの場合）
  5. トークンタイプがリフレッシュトークンであることをバリデート
  6. IPバリデーションを有効にしてセキュリティチェックを実行
  7. トークンとトークン情報を返す

defaultRefreshTokenCookieAuth​

クッキーから取得したリフレッシュトークンのデフォルト認証関数。クッキーに保存されたリフレッシュトークンをフィンガープリントバリデーションとともにバリデートします。decryptToken=trueの場合、関数はtokenとtokenInfoの両方を返すことに注意してください。

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

const { defaultRefreshTokenCookieAuth } = utils;

const { token, tokenInfo } = await defaultRefreshTokenCookieAuth(
  authSecrets,
  request,
  true, // decryptToken
  logger
);

パラメータ:

  • authSecrets: トークン復号化用の認証シークレット
  • request: クッキーにリフレッシュトークンを含むHTTPリクエストオブジェクト
  • decryptToken: トークンを復号化してバリデートするかどうか（デフォルト: false）
  • logger: セキュリティチェックロギング用のオプションロガー

プロセス:

  1. request.cookies.refreshTokenからリフレッシュトークンを抽出
  2. トークン検証コンテキスト（フィンガープリント、IP、ユーザーエージェント）を取得
  3. トークンフォーマットと存在をバリデート
  4. JWT署名を復号化して検証（decryptTokenがtrueの場合）
  5. トークンタイプがリフレッシュトークンであることをバリデート
  6. IPバリデーションを無効にしてセキュリティチェックを実行
  7. トークンとトークン情報を返す（decryptTokenがtrueの場合）

ボディ認証との主な違い:

  • ソース: リクエストボディではなくクッキーから読み取り
  • IPバリデーション: クッキーベースのトークンでは無効（checkIp: false）
  • 戻り値: decryptToken=trueの場合、追加処理のために{token, tokenInfo}を返す

🛡️ セキュリティ関数​

tokenPassesSecurityCheck​

トークンのセキュリティコンテキストをバリデートします。

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

const { tokenPassesSecurityCheck } = utils;

const isValid = tokenPassesSecurityCheck(
  tokenInfo,
  {
    fingerprint: 'device-fingerprint',
    ip: '192.168.1.1',
    userAgent: 'Mozilla/5.0...'
  },
  logger,
  { checkIp: true }
);

バリデーションチェック:

  • フィンガープリント: デバイスフィンガープリントマッチング
  • IPアドレス: IPアドレスバリデーション（オプション）
  • ユーザーエージェント: ブラウザ/クライアント識別

decryptAndVerifyJWT​

JWTトークンを復号化して検証します。

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

const { decryptAndVerifyJWT } = utils;

const tokenInfo = decryptAndVerifyJWT(authSecrets, encryptedToken);

🔧 ヘルパー関数​

getBearerToken​

リクエストヘッダーからベアラートークンを抽出します。

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

const { getBearerToken } = utils;

const token = getBearerToken(request.headers);
// 戻り値: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

getFingerprint​

ヘッダーからデバイスフィンガープリントを抽出します。

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

const { getFingerprint } = utils;

const fingerprint = getFingerprint(request.headers, 'x-nb-fingerprint');

getUserAgent​

リクエストヘッダーからユーザーエージェントを抽出します。

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

const { getUserAgent } = utils;

const userAgent = getUserAgent(request.headers);

getRequestInfo​

トークンバリデーション用のリクエストメタデータを抽出します。

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

const { getRequestInfo } = utils;

const requestInfo = getRequestInfo(request);
// 戻り値: { host, ip, method, path, url }

getExpiresIn​

トークンの有効期限値を正規化します。さまざまな入力フォーマットを標準化された有効期限フォーマットに変換します。

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

const { getExpiresIn } = utils;

const expiresIn = getExpiresIn('24h');     // 戻り値: '24h'
const expiresIn2 = getExpiresIn(3600000);  // 戻り値: 3600000
const expiresIn3 = getExpiresIn();         // 戻り値: '48h' (デフォルト)

パラメータ:

  • expirationTime: 文字列または数値としてのオプションの有効期限

戻り値:

  • number | string: 正規化された有効期限（デフォルト: '48h'）

動作:

  • expirationTimeがnullまたはundefinedの場合: デフォルトの'48h'を返す
  • expirationTimeが有効な数値の場合: その数値を返す
  • expirationTimeが文字列の場合: そのまま文字列を返す

getExpirationDate​

期間文字列またはミリ秒に基づいて絶対有効期限日を計算します。

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

const { getExpirationDate } = utils;

const expirationDate = getExpirationDate('7d');     // 戻り値: 今から7日後のDateオブジェクト
const expirationDate2 = getExpirationDate(3600000); // 戻り値: 今から1時間後のDateオブジェクト
const expirationDate3 = getExpirationDate();        // 戻り値: 今から7日後のDateオブジェクト（デフォルト）

パラメータ:

  • expiresIn: 期間文字列（例：'7d'、'24h'、'30m'）またはミリ秒（デフォルト: '7d'）

戻り値:

  • Date: 絶対有効期限日時

サポートされる期間フォーマット:

  • '7d' - 7日
  • '24h' - 24時間
  • '30m' - 30分
  • '60s' - 60秒
  • ミリ秒単位の数値

isAccessToken​

トークンがアクセストークン（ユーザーまたはアプリ）かどうかをチェックし、シンプルな型ガードとして使用できます。

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

const { isAccessToken } = utils;

if (isAccessToken(tokenInfo)) {
  // tokenInfoはAccessTokenInfo（accessType: 'user' | 'app'）
}

パラメータ:

  • tokenInfo: チェックするトークン情報オブジェクト

戻り値:

  • boolean: トークンがアクセストークンの場合true、それ以外はfalse

isUserAccessToken​

トークンがユーザーアクセストークンかどうかをチェックします。

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

const { isUserAccessToken } = utils;

if (isUserAccessToken(tokenInfo)) {
  // tokenInfoはUserAccessTokenInfo
  console.log(tokenInfo.identityId);
}

パラメータ:

  • tokenInfo: チェックするトークン情報オブジェクト

戻り値:

  • boolean: トークンがユーザーアクセストークンの場合true、それ以外はfalse

isAppAccessToken​

トークンがアプリアクセストークンかどうかをチェックします。

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

const { isAppAccessToken } = utils;

if (isAppAccessToken(tokenInfo)) {
  // tokenInfoはAppAccessTokenInfo
  console.log(tokenInfo.appId);
}

パラメータ:

  • tokenInfo: チェックするトークン情報オブジェクト

戻り値:

  • boolean: トークンがアプリアクセストークンの場合true、それ以外はfalse

isRefreshToken​

トークンがリフレッシュトークンかどうかをチェックします。

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

const { isRefreshToken } = utils;

if (isRefreshToken(tokenInfo)) {
  // tokenInfoはRefreshTokenInfo
  console.log(tokenInfo.jti);
}

パラメータ:

  • tokenInfo: チェックするトークン情報オブジェクト

戻り値:

  • boolean: トークンがリフレッシュトークンの場合true、それ以外はfalse

isOnetimeToken​

トークンがワンタイムトークンかどうかをチェックします。

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

const { isOnetimeToken } = utils;

if (isOnetimeToken(tokenInfo)) {
  // tokenInfoはOnetimeTokenInfo
  console.log(tokenInfo.data);
}

パラメータ:

  • tokenInfo: チェックするトークン情報オブジェクト

戻り値:

  • boolean: トークンがワンタイムトークンの場合true、それ以外はfalse

isValidAppAccessToken​

アプリアクセストークンにappIdが存在するかどうかをチェックします。

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

const { isValidAppAccessToken } = utils;

if (isValidAppAccessToken(tokenInfo)) {
  // tokenInfoはappIdが存在するAppAccessTokenInfo
}

パラメータ:

  • tokenInfo: チェックするトークン情報オブジェクト

戻り値:

  • boolean: トークンがappIdが存在するアプリアクセストークンの場合true、それ以外はfalse

isValidUserAccessToken​

ユーザーアクセストークンにidentityIdが存在するかどうかをチェックします。

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

const { isValidUserAccessToken } = utils;

if (isValidUserAccessToken(tokenInfo)) {
  // tokenInfoはidentityIdが存在するUserAccessTokenInfo
}

パラメータ:

  • tokenInfo: チェックするトークン情報オブジェクト

戻り値:

  • boolean: トークンがidentityIdが存在するユーザーアクセストークンの場合true、それ以外はfalse

retrieveTokenVerification​

Express Requestからトークン検証メタデータを作成します。

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

const { retrieveTokenVerification } = utils;

const verification = retrieveTokenVerification(request);
// { domain, fingerprint, ip, userAgent }

validateAuthSecrets​

必要な認証シークレットをバリデートし、欠落または短すぎる場合はスローします。

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

const { validateAuthSecrets } = utils;

validateAuthSecrets(authSecrets); // 無効な設定でスロー

generateMailBody​

URLとオプションをメールテンプレートに補間します。

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

const { generateMailBody } = utils;

const body = generateMailBody(
  'Click here: ${url}',
  'https://example.com/reset?token=${token}',
  { token: 'abc' }
);

authSecretsValidationErrorMessage​

無効な認証シークレットの人間が読めるエラーを返します（一時的なヘルパー）。

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

const { authSecretsValidationErrorMessage } = utils;

const msg = authSecretsValidationErrorMessage(authSecrets);
if (msg) throw new Error(msg);

🔐 暗号化関数​

encrypt​

データを暗号化します。

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

const { encrypt } = utils;

const encrypted = encrypt(secret, 'sensitive-data');

decrypt​

暗号化されたデータを復号化します。

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

const { decrypt } = utils;

const decrypted = decrypt(secret, encryptedData);

🔑 パスワード関数​

hash​

bcryptを使用してパスワードをハッシュ化します。

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

const { hash } = utils;

const hashedPassword = await hash('user-password');

compareHash​

パスワードとハッシュを比較します。

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

const { compareHash } = utils;

const isValid = await compareHash('user-password', hashedPassword);

📊 トークンタイプ​

ユーザーアクセストークン​

interface UserAccessTokenInfo {
  accessType: 'user';
  identityId: string;
  type: 'access';
  stateful: boolean;
  fingerprint?: string;
  ip?: string;
  domain?: string;
  target?: string;
  userAgent?: string;
}

アプリアクセストークン​

interface AppAccessTokenInfo {
  accessType: 'app';
  appId: string;
  type: 'access';
}

リフレッシュトークン​

interface RefreshTokenInfo {
  type: 'refresh';
  jti: string;
  identityId: string;
  stateful: true;
  fingerprint?: string;
  ip?: string;
  domain?: string;
  userAgent?: string;
}

ワンタイムトークン​

interface OnetimeTokenInfo {
  type: 'onetime';
  data: object;
  stateful: true;
  fingerprint?: string;
  ip?: string;
  domain?: string;
  target?: string;
  userAgent?: string;
}