バージョン: 0.14.0 (最新)

🍪 Cookie ユーティリティ

Nodeblocks SDK は、Cookie ベース認証と Set-Cookie オプション解決のヘルパーを提供します。これらのユーティリティは、authMode が 'cookie' の場合に認証サービスと統合されます。

🎯 概要

Cookie ユーティリティは utils 名前空間にあり、Cookie 設定時（ログイン、リフレッシュ、ログアウト）と、合成／リクエスト時（Cookie と Bearer の認証ハンドラーの分岐）の両方で使用されます。

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

const {
  DEFAULT_COOKIE_OPTS,
  withCookieOptDefaults,
  isCookieMode,
  whenCookieAuth,
} = utils;

このモジュールは CookieOptions、DEFAULT_COOKIE_OPTS、withCookieOptDefaults、isCookieMode、whenCookieAuth の 5 つのシンボルをエクスポートします。

サービスレベルの構成（authMode、トークン署名オプション）は、Authentication サービスを参照してください。

📋 型とデフォルト

`CookieOptions`

Cookie 構成用の TypeScript インターフェースです。

interface CookieOptions {
  domain?: string;
  httpOnly?: boolean;
  maxAge?: number;
  path?: string;
  sameSite?: 'strict' | 'lax' | 'none';
  secure?: boolean;
}

`DEFAULT_COOKIE_OPTS`

ユーザーオーバーライドの前に適用される安全なデフォルトです。

const DEFAULT_COOKIE_OPTS: CookieOptions = {
  httpOnly: true,
  path: '/',
  sameSite: 'strict',
  secure: true,
};

`withCookieOptDefaults`

アクセスまたはリフレッシュトークン Cookie の最終 Set-Cookie オプションを解決します。

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

const { withCookieOptDefaults } = utils;

const accessCookieOpts = withCookieOptDefaults(context, 'access');
const refreshCookieOpts = withCookieOptDefaults(context, 'refresh');

パラメーター:

context: ServiceContext — 構成を含むリクエスト／サービスコンテキスト
tokenType: 'access' | 'refresh' — maxAge に読み取るトークン署名オプションを選択

マージ順（低 → 高優先度）:

DEFAULT_COOKIE_OPTS
context.cookieOpts または context.configuration.cookieOpts のユーザー cookieOpts
対応するトークンの expiresIn（accessTokenSignOptions または refreshTokenSignOptions）から deriveCookieMaxAge で変換した計算済み maxAge

トークンの expiresIn が構成される場合、計算済み maxAge は、ユーザーが cookieOpts に設定したすべての maxAge を上書きします。

重要: このヘルパーは Cookie 設定時（例: setResponseCookie、ログアウト）にのみ呼び出してください。合成時の述語は、未加工の authMode／cookieOpts 構成を読む必要があります。このヘルパーを通過した値を使用してはいけません。

🔀 認証モード分岐

`isCookieMode`

合成時／リクエスト時の検査用述語です。

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

const { isCookieMode } = utils;

isCookieMode('cookie');  // true
isCookieMode('bearer');  // false

value === 'cookie' と同等です。

`whenCookieAuth`

Cookie 認証が有効な場合は Cookie ハンドラーを、そうでなければ Bearer ハンドラーを実行します（デフォルトはパススルー）。

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

const { getBearerTokenInfo, getCookieTokenInfo, whenCookieAuth } = utils;

const authenticate = whenCookieAuth(
  getCookieTokenInfo,
  getBearerTokenInfo
);

// `authenticate` を非同期ルートハンドラーとして使用するか、
// 後続のハンドラーステップと合成します。
const handler = authenticate;

Cookie モード検出: リクエスト時に context.authMode または context.configuration.authMode を読み取ります。

デフォルト Bearer ハンドラー: Bearer ハンドラーが指定されない場合、デフォルトのパススルーは変更されない ok(payload) を返します。

パラメーター:

cookieFn: Cookie 認証が有効な場合に実行するハンドラー
bearerFn: Bearer モード用の省略可能なハンドラー（デフォルト: パススルー）

📐 ベストプラクティス

// ✅ 良い例: Cookie を設定するときに解決
response.cookie('accessToken', token, withCookieOptDefaults(context, 'access'));

// ❌ 避ける: 認証モードの述語に withCookieOptDefaults を使用
const isCookie = withCookieOptDefaults(context, 'access'); // 不適切なヘルパー

2. whenCookieAuth で認証ハンドラーを分岐する

// ✅ 良い例: モード対応の単一パイプライン認証
const authHandler = whenCookieAuth(getCookieTokenInfo, getBearerTokenInfo);

Cookie と Bearer のパスで使われるトークン検証ヘルパーについては、Authentication ユーティリティを参照してください。

🔗 関連項目

Authentication ユーティリティ — getCookieTokenInfo、deriveCookieMaxAge
Authentication サービス — authMode、cookieOpts の構成
Composition ユーティリティ — whenCookieAuth は ifElse、either、match を使用

🎯 概要​

📋 型とデフォルト​

CookieOptions​

DEFAULT_COOKIE_OPTS​

🔧 Set-Cookie オプション解決​

withCookieOptDefaults​

🔀 認証モード分岐​

isCookieMode​

whenCookieAuth​

📐 ベストプラクティス​

1. Cookie オプションは設定時にのみ解決する​

2. whenCookieAuth で認証ハンドラーを分岐する​

🔗 関連項目​