バージョン: 0.5.0 (最新)

🔐 認証ユーティリティ

NodeBlocks SDKは、トークン管理、検証、セキュリティのための包括的な認証ユーティリティを提供します。これらのユーティリティは、Bearerトークン、Cookieベース認証、およびさまざまなユースケースのためのさまざまなトークンタイプを処理します。

🎯 Overview

Authentication utilities provide secure token generation, validation, and management for both user and application authentication. They support multiple token types and security validation mechanisms.

Key Features

Multiple Token Types: User access, app access, refresh, and one-time tokens
Security Validation: Fingerprint, IP, and user agent validation
Flexible Authentication: Bearer token and cookie-based authentication
JWT Integration: JSON Web Token signing and verification

🔑 Token Generation

`generateUserAccessToken`

Creates encrypted user access tokens with security validation metadata.

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`

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

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

const { getBearerTokenInfo } = utils;

const tokenInfo = await getBearerTokenInfo(payload);

プロセス：

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

`getCookieTokenInfo`

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

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

const { getCookieTokenInfo } = utils;

const tokenInfo = await getCookieTokenInfo(payload);

ユースケース：

Cookieベース認証を使用した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: セキュリティチェックロギングのためのオプションのロガー

プロセス：

request.body.refreshTokenからリフレッシュトークンを抽出
トークン検証コンテキストを取得（フィンガープリント、IP、ユーザーエージェント）
トークン形式と存在を検証
JWT署名を復号化および検証（decryptTokenがtrueの場合）
トークンタイプがリフレッシュトークンであることを検証
IP検証が有効な状態でセキュリティチェックを実行
トークンとトークン情報を返す

`defaultRefreshTokenCookieAuth`

Cookieから取得したリフレッシュトークンのデフォルト認証関数。フィンガープリント検証とともにCookieに保存されたリフレッシュトークンを検証します。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: Cookieにリフレッシュトークンを含むHTTPリクエストオブジェクト
decryptToken: トークンを復号化および検証するかどうか（デフォルト: false）
logger: セキュリティチェックロギングのためのオプションのロガー

プロセス：

request.cookies.refreshTokenからリフレッシュトークンを抽出
トークン検証コンテキストを取得（フィンガープリント、IP、ユーザーエージェント）
トークン形式と存在を検証
JWT署名を復号化および検証（decryptTokenがtrueの場合）
トークンタイプがリフレッシュトークンであることを検証
IP検証が無効な状態でセキュリティチェックを実行
トークンとトークン情報を返す（decryptTokenがtrueの場合）

Body認証との主な違い：

ソース: リクエストボディではなくCookieから読み取る
IP検証: Cookieベースのトークンに対して無効（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 }
);

検証チェック：

Fingerprint: デバイスのフィンガープリントマッチング
IP Address: IPアドレス検証（オプション）
User Agent: ブラウザ/クライアント識別

`decryptAndVerifyJWT`

JWTトークンを復号化および検証します。

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

const { decryptAndVerifyJWT } = utils;

const tokenInfo = decryptAndVerifyJWT(authSecrets, encryptedToken);

🔧 ヘルパー関数

`getBearerToken`

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

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); // throws on invalid configuration

`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;
}

🎯 Overview​

Key Features​

🔑 Token Generation​

generateUserAccessToken​

generateAppAccessToken​

generateRefreshToken​

generateOnetimeToken​

🔍 トークン検証​

getBearerTokenInfo​

getCookieTokenInfo​

defaultRefreshTokenBodyAuth​

defaultRefreshTokenCookieAuth​

🛡️ セキュリティ関数​

tokenPassesSecurityCheck​

decryptAndVerifyJWT​

🔧 ヘルパー関数​

getBearerToken​

getFingerprint​

getUserAgent​

getRequestInfo​

getExpiresIn​

getExpirationDate​

isAccessToken​

isUserAccessToken​

isAppAccessToken​

isRefreshToken​

isOnetimeToken​

isValidAppAccessToken​

isValidUserAccessToken​

retrieveTokenVerification​

validateAuthSecrets​

generateMailBody​

authSecretsValidationErrorMessage​

🔐 暗号化関数​

encrypt​

decrypt​

🔑 パスワード関数​

hash​

compareHash​

📊 トークンタイプ​

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

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

リフレッシュトークン​

ワンタイムトークン​

🎯 Overview

Key Features

🔑 Token Generation

`generateUserAccessToken`

`generateAppAccessToken`

`generateRefreshToken`

`generateOnetimeToken`

🔍 トークン検証

`getBearerTokenInfo`

`getCookieTokenInfo`

`defaultRefreshTokenBodyAuth`

`defaultRefreshTokenCookieAuth`

🛡️ セキュリティ関数

`tokenPassesSecurityCheck`

`decryptAndVerifyJWT`

🔧 ヘルパー関数

`getBearerToken`

`getFingerprint`

`getUserAgent`

`getRequestInfo`

`getExpiresIn`

`getExpirationDate`

`isAccessToken`

`isUserAccessToken`

`isAppAccessToken`

`isRefreshToken`

`isOnetimeToken`

`isValidAppAccessToken`

`isValidUserAccessToken`

`retrieveTokenVerification`

`validateAuthSecrets`

`generateMailBody`

`authSecretsValidationErrorMessage`

🔐 暗号化関数

`encrypt`

`decrypt`

🔑 パスワード関数

`hash`

`compareHash`

📊 トークンタイプ

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

アプリアクセストークン

リフレッシュトークン

ワンタイムトークン