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

変更履歴

ドキュメントサイト (2026-08-20)​

ドキュメントを SDK 0.14.0 に合わせて更新しました。リフレッシュトークンは専用の refreshtokens コレクションに保存され、ホストの例ではそのストアを authService に渡します。

🔄 変更​

バージョン指定​

認証データストア​

認証リファレンス​

  • softDeleteRefreshTokens は refreshtokens に対して文書化され、jti / email でのフィルタは不要になりました。
  • 認証ルート は、リフレッシュトークン削除、パスワードリセット完了、パスワード変更、非アクティブ化で softDeleteRefreshTokens を db.refreshtokens に接続します。
  • 認証ハンドラ: logout と refreshToken のインベントリは identities の代わりに refreshtokens を使用します。

アイデンティティ​

  • getIdentityById は { id } のみで検索します。jti: { $exists: false } フィルタは文書化されなくなりました。

SDK 0.14.0 (2026-08-19)​

✨ 追加機能​

認証​

  • AuthenticationServiceDataStore に専用の refreshtokens コレクションが必須になりました。ログイン、ログアウト、リフレッシュローテーション、管理者によるトークン削除、一括取り消し（softDeleteRefreshTokens）はすべて、identities ではなくそこにリフレッシュトークンを永続化します。

🔄 変更​

認証​

  • createRefreshToken、logout、refreshToken、deleteToken は db.refreshtokens を読み書きします。
  • softDeleteRefreshTokens はパスワードリセット、パスワード変更、非アクティブ化、リフレッシュトークン削除のルートから refreshtokens に接続され、email / jti でのフィルタは行いません（これらの識別子はトークンが identities コレクションを共有していた間のみ必要でした）。

アイデンティティ​

  • getIdentityById はアイデンティティ検索時に jti: { $exists: false } を適用しなくなりました。

📦 マイグレーション​

  • 認証ホスト: authService（および以前にリフレッシュトークンに db.identities を使っていたカスタム合成）に refreshtokens MongoDB コレクションを渡してください。このフィールドは必須です — 配線が欠けるとコンパイル時に失敗します。
  • 既存セッション: アップグレード後、リフレッシュ / ログアウト / 一括取り消しは refreshtokens のみを参照します。identities に残っている行（{ jti: { $exists: true } }）はリフレッシュも取り消しもしません。セッションを維持したい場合はそれらを refreshtokens にコピーし、いずれにせよ identities から削除して、アイデンティティ検索が残存トークンドキュメントに当たらないようにしてください。
  • インデックス: ホストデータベースで refreshtokens.jti にユニークインデックスを作成してください。SDK はインデックスを作成しません。

⚠️ 破壊的変更​

  • 認証: AuthenticationServiceDataStore.refreshtokens は必須です。省略すると型チェックに失敗し、実行時のトークン書き込みも失敗します。
  • 認証: リフレッシュトークンはもはや identities に保存されません。そのコレクション内の既存トークンドキュメントは、マイグレーションされるまで無視されます（マイグレーションを参照）。

SDK 0.13.0 (2026-07-14)​

✨ 追加機能​

サービス​

  • 保護されたCRUD/ドメインサービス設定に authMode?: 'bearer' | 'cookie' をオプションで追加（属性、プロフィール、製品、カテゴリ、組織、場所、注文、チャット、アイデンティティ、通知、住所）。authMode が 'cookie' の場合、各サービスは getCookieTokenInfo を context.authenticate に接続; それ以外の場合は getBearerTokenInfo を使用。認証サービス およびマウント可能ドメイン統合ガイドを参照。

認証​

  • checkIp?: boolean（デフォルト true）を AuthenticationServiceConfiguration に追加; getBearerTokenInfo と getCookieTokenInfo の両方がこのオプションを取得。認証サービス を参照。
  • whenCookieAuth ユーティリティは authMode に基づいてハンドラを cookie モードと bearer モードの実装間で分岐します。
  • context.authenticate の型付きフィールドが ServiceContext / ServiceDefinition に追加され、authMode に応じて getCookieTokenInfo または getBearerTokenInfo で設定されます。
  • スタンドアロンの logoutFeature。authMode に応じて logoutCookieSchema または logoutBearerSchema をコンパイル時に選択。
  • refreshTokenBearerSchema と refreshTokenCookieSchema; refreshTokenSchema は refreshTokenBearerSchema の非推奨エイリアスとして残る。
  • cookieOpts.httpOnly と cookieOpts.secure が設定可能に（従来はハードコード true）。

🔄 変更​

認証​

  • セッションクッキーの maxAge は各トークンの expiresIn（accessTokenSignOptions / refreshTokenSignOptions）から自動的に算出される。
  • loginWithCredentialsRoute: cookie モードはレスポンス本文に { id } のみを返す; トークンは Set-Cookie で配信。bearer モードは変更なし（{ accessToken, id, refreshToken }）。
  • refreshTokenRoute: cookie モードは更新されたクッキーを設定し 204 と空の本文を返す; bearer モードは変更なし（200 { accessToken, refreshToken }）。
  • setResponseCookie は accessTokenSignOptions.expiresIn / refreshTokenSignOptions.expiresIn からアクセストークンおよびリフレッシュトークンのクッキーオプションを算出。

🐞 修正​

認証​

  • logoutRoute: accessToken と refreshToken クッキーを無条件に消去; 呼び出し者を context.authenticate（cookieまたはbearer対応）経由で解決; すでに取り消されたリフレッシュトークンを成功として扱う; リゾルブできないリフレッシュトークンの場合も成功として扱う。
  • deactivateRoute: cookie モードでアクセストークンを Authorization ヘッダーではなく accessToken クッキーから読み取る。

組織​

  • createChangeRequestRoute: cookie モードでアクセストークンを Authorization ヘッダーではなく accessToken クッキーから読み取る。

🔒 セキュリティ​

  • getCookieTokenInfo の undocumented バイパスを削除し、appタイプの Authorization: Bearer トークンがcookie/セッション検証を完全にスキップできるようにした。
  • getCookieTokenInfo はもはや checkIp: false をハードコードしません; cookie認証されたユーザートークンはbearerトークンと同様にIPチェックがデフォルトで有効。

⚠️ 破壊的変更​

  • AuthenticationServiceConfiguration.cookieOpts.maxAge が削除されました。クッキーの生存期間は一致するトークンの expiresIn に従います。cookieOpts.maxAge 設定を削除してください。
  • デフォルト accessTokenSignOptions.expiresIn が 2時間 から 15分 に変更。
  • loginWithCredentialsFeature はもはや logoutRoute を合成しません。authService 外で loginWithCredentialsFeature に直接構築されたカスタム合成は、logoutFeature を個別に追加する必要があります。
  • Cookieモードのログインとリフレッシュはレスポンス本文にトークンを返さなくなりました。
  • getCookieTokenInfo はcookie認証へのバイパスパスとして Authorization: Bearer を受け付けなくなります。
  • 共通バリデーター から未使用のlegacyバリデーターエクスポートを削除: validateResourceAccess、validateOrganizationAccess、validateOrderAccess、validateMessageAccess、validateChannelAccess、verifyAuthentication、requireParam、isUUID、および isNumber。

SDK 0.12.0 (2026-07-07)​

🐞 修正​

認証​

  • completePasswordResetRoute: ユーザーがパスワードをリセットしたときに、すべてのアクティブなリフレッシュトークンを撤销し、すべてのデバイスで既存のセッションを終了。
  • changePasswordRoute: ユーザーがパスワードを変更したときに、すべてのアクティブなリフレッシュトークンを撤销。
  • 指紋セキュリティチェック: tokenPassesSecurityCheck は undefined と '' を同等として扱います; トークン生成は生成時点で指紋を '' に正規化。
  • logoutRoute: リフレッシュトークンの撤销が成功した場合のみ、認証トークンクッキーを消去。

🔄 変更​

認証​

  • softDeleteRefreshTokens は delFlg の代わりに deletedAt を設定し、リフレッシュトークンの撤销チェックと整合。
  • refreshTokenRoute: 各使用時にリフレッシュトークンを回転（新しい jti + DB行）; 取り消されたリフレッシュトークンの再利用に対して 401 を返す（他のデバイスのセッションを取り消さず）; cookie/本文解決のために resolveRefreshTokenFromRequest を使用。
  • logoutRoute: 認証されたアイデンティティに属することを確認した後、提示されたリフレッシュトークン（cookieまたは本文）を取り消す。
  • cookieベースのリフレッシュは指紋を x-nb-fingerprint ヘッダーから読み取る（本文パスと同じ）し、IP/UAチェックを実行。cookie ユーティリティ を参照。

⚠️ 破壊的変更​

  • cookieベースのリフレッシュ (refreshTokenRoute) および cookieベースのlogout (logoutRoute) は x-nb-fingerprint ヘッダーを必要とする。cookieパス上では request.body.fingerprint はもはや読み取られない。

SDK 0.11.0 (2026-05-26)​

✨ 追加機能​

コンビネーター​

  • mapMatchingErrorToFalse: 特定のエラークラスを ok(false) にマッピングする（従来の mapErrorToFalse はすべてのエラーを変換）。

🔄 変更​

プロフィール（旧ユーザー）​

  • ユーザーハンドラ、ブロック、ルート、スキーマ、フィーチャ、およびサービス名をプロフィールに変更。プロフィールサービス および プロフィールブロック を参照。
  • 組織および製品ルートおよびサービスで users コレクション参照を profiles に更新。
  • 非推奨 validateUserProfileAccess バリデーターを削除。
  • getProfileById の戻り型を更新。

🔒 セキュリティ​

メール変更​

  • changeEmailRoute: リクエストされたメールアドレスが既に使用されている場合に、エラーの代わりに 204 を返し、メールの列挙を防ぐ。
  • 競合エラーのみを ok(false) に変換するために mapMatchingErrorToFalse を使用。

⚠️ 破壊的変更​

  • プロフィールリネーム: user サービス、ルート、ブロック、スキーマ、およびフィーチャは profile にリネームされました。すべてのインポートを user* から profile* に更新してください。
  • バリデーター: validateUserProfileAccess が削除されました。代わりに更新された プロフィールバリデーター を使用してください。
  • コンビネーター: mapErrorToFalse は mapMatchingErrorToFalse にリネームされ、第一引数としてエラークラスを必要とします。

SDK 0.10.0 (2026-03-17)​

✨ 追加機能​

通知管理​

  • 新サービス: 通知サービス。
  • 新規エンドポイント:
    • GET /notifications/identities/:identityId — ページネーション付きで通知を検索。通知ルート を参照。
    • POST /notifications/:notificationId/read — 単一通知を読としてマーク。
    • POST /notifications/identities/:identityId/read — アンカー通知までバッチで読としてマーク。
  • 作成、バッチ作成、検索、取得、単一更新、およびバッチ更新操作のための通知ブロック。

住所検索​

組織メンバー保護​

  • 組織から最後のオーナーを削除できないようにするバリデーター。
  • メンバーが自身の階層より上の役割を割り当てられないようにする役割割り当て検証。
  • 組織メンバーを削除する前に同以上役割の検証。組織バリデーター を参照。

🐞 修正​

アイデンティティ​

  • getIdentityRoute: identities コレクションに保存されたトークン記録を除外し、一致するトークンレコードを防ぐ（jti のドキュメントを除く）。

住所検索​

  • Japan Post 郵便番号処理は検索時に完全な7桁のコードを必要とする。
  • 複数の町が同じ郵便番号を共有する場合、推測するのではなく null を返す。

🔄 変更​

認証設定​

  • ストリングベースの有効期限設定を accessTokenSignOptions、refreshTokenSignOptions、および onetimeTokenSignOptions に置き換え。認証サービス および auth ユーティリティ を参照。
  • パスワードリセット、メール変更、MFA、およびOAuthフロー全体で共有のワンタイムトークン署名オプションを適用。

認可ルール​

  • 組織メンバーのアップsert および削除ルートに追加の役割階層チェックを追加。

SDK 0.9.1 (2026-01-22)​

✨ 追加機能​

認証​

  • 新しいパスワードが現在のパスワードと同じでないかを確認するパスワード検証。
  • 個別のbcrypt比較と一致ロジックを2つのブロックに分割; password-must-not-matchフローのための新しい assertDoesNotMatch ブロック。

スキーマ検証​

  • applySchemaDefaults でオブジェクト関連キーワードを含むタイプなしスキーマの処理。
  • スキーマ検証でのオブジェクトを含むユニオンタイプのサポート。

🔄 変更​

  • タグ伝播と Nullable スキーマサポートを改善したOpenAPIスキーマ生成を強化。

🔒 セキュリティ​

SDK 0.9.0 (2025-11-04)​

✨ 追加機能​

場所管理​

  • 新サービス: 場所サービス。
  • 新規エンドポイント: POST /locations、GET /locations/:locationId、PATCH /locations/:locationId、DELETE /locations/:locationId、GET /locations。場所ルート を参照。
  • 自動祖先計算による親子関係の処理。

プロフィールフォローシステム​

  • 新規エンドポイント:
    • PUT /profiles/:profileId/profile-follows/:followProfileId — プロフィールフォローを作成。プロフィールルート を参照。
    • DELETE /profiles/:profileId/profile-follows/:followProfileId — プロフィールフォローを削除。
    • GET /profiles/:profileId/followers — ページネーション付きでプロフィールのフォロワーを取得。

組織フォローシステム​

  • 新規エンドポイント:
    • PUT /profiles/:profileId/organization-follows/:followOrganizationId — 組織フォローを作成。
    • DELETE /profiles/:profileId/organization-follows/:followOrganizationId — 組織フォローを削除。
    • GET /organizations/:organizationId/followers — 組織のフォロワーを取得。組織ルート を参照。

製品いいねシステム​

  • 新規エンドポイント:
    • PUT /profiles/:profileId/product-likes/:likeProductId — 製品いいねを作成。
    • DELETE /profiles/:profileId/product-likes/:likeProductId — 製品いいねを削除。
    • GET /products/:productId/likers — 製品のいいねをするユーザーを取得。製品ルート を参照。

チャットメッセージテンプレート管理​

製品バリエーション一括操作​

  • 新規エンドポイント:
    • POST /products/:productId/variants/bulk、PATCH /products/:productId/variants/bulk、DELETE /products/:productId/variants/bulk、GET /products/:productId/variants。製品ルート を参照。

検索エンドポイント​

  • GET /profiles/identities/:identityId — アイデンティティIDでプロフィールを検索。
  • GET /organizations/:organizationId/orders — 組織IDで注文を検索。
  • GET /organizations/:organizationId/products — 組織IDで製品を検索。

アイデンティティロック/アンロック​

チャットチャンネルアイコン管理​

ソフト削除​

  • MongoDBコレクションの withSoftDelete コンビネーター（自動フィルタリングと監査証跡付き）。

🐞 修正​

  • すべての作成および更新操作に updatedAt/createdAt タイムスタンプを追加。
  • セキュリティのためにすべてのデータベースクエリでIDを文字列にキャスト。

🔄 変更​

  • チャットメッセージの更新はメッセージ所有者のみ（管理者オーバーライドを削除）。updateChatMessageRoute を参照。
  • エンティティ作成を簡素化: メッセージと製品は添付ファイル/画像なしで作成; 添付ファイルは専用エンドポイント経由で管理。

SDK 0.8.0 (2025-09-24)​

✨ 追加機能​

製品バリエーション管理​

  • 新規エンドポイント:
    • POST /products/:productId/variants — 製品バリエーションを作成。
    • GET /products/:productId/variants/:productVariantId — IDで製品バリエーションを取得。
    • PATCH /products/:productId/variants/:productVariantId — 製品バリエーションを更新。
    • DELETE /products/:productId/variants/:productVariantId — 製品バリエーションを削除。
  • 製品フィーチャ および 製品ルート を参照。

組織変更リクエストシステム​

組織管理​

  • updateOrganizationAsAdminRoute: PATCH /admin/organizations/:organizationId/。
  • 認証画像URLが正規化された組織レスポンスに追加。

マルチファクター認証（MFA）​

ワンタイムトークン（OTT）認証​

  • loginWithOnetimeTokenRoute: POST /auth/ott/login。
  • OAuthコールバックフローはワンタイムトークンを返す; フロントエンドはOTTログインエンドポイント経由で交換。

ページネーションシステム​

  • PaginationResult<T> をデータとメタデータに分離するように再構造化。
  • リストエンドポイントは { data, metadata: { pagination } } を返す（従来の { count, total, value } に置き換え）。
  • 標準クエリパラメータとメタデータの paginationQueryParametersSchema と paginationSchema。
  • findOrganizationMembersRoute: withPaginatedProperty 経由で埋め込みページネーション。

🐞 修正​

  • WebSocketリクエストのWebSocket IPアドレスの可用性。
  • ページネーションメタデータの戻り問題。

SDK 0.7.0 (2025-09-12)​

✨ 追加機能​

チャットメッセージ添付ファイル​

チャットチャンネルメッセージ​

チャット既読受信​

チャットWebSocket購読​

  • streamChatMessagesRoute: リアルタイムメッセージストリーミングのための WebSocket /messages/listen。

LINE OAuth認証​

製品画像管理​

  • 新規エンドポイント:
    • POST /products/:productId/images — 製品画像を作成。
    • DELETE /products/:productId/images/:imageId — 製品画像を削除。
  • 製品ルート を参照。

ブロック​

  • チャット状態ブロック: createChatChannelReadState、updateChatChannelReadState、findChatChannelReadStates、およびクエリ/ペイロードビルダー。
  • チャットメッセージブロック: createChatMessage、getChatMessageById、添付ファイルCRUD、および正規化ヘルパー。
  • 製品ブロック: getProductById、findProducts、画像正規化ヘルパー。
  • OAuthブロック: requestLineOAuth、authenticateLineOAuth、verifyLineOAuth。
  • normalizeFile: 集中ファイル正規化ユーティリティ。

🔄 変更​

  • チャットと製品の正規化は集中的な normalizeFile ユーティリティを使用するようにリファクタリング。
  • エンティティ作成を簡素化: コアメッセージと製品は添付ファイル/画像なしで作成; 添付ファイルは専用エンドポイント経由で管理。

🐞 修正​

  • チャット添付ファイルの正規化（更新レスポンス内）; セキュリティIDのキャスト; 添付ファイル操作の管理者アクセス制限。
  • OAuth: GoogleとTwitterフローはemailワークアラウンドの代わりに provider/providerId を使用するように修正。

SDK 0.6.0 (2025-08-28)​

🎥 デモ動画​

📹 NodeBlocks Backend SDK v0.6.0 デモ — すべての新機能と機能の完全なウォークスルー。

✨ 追加機能​

チャットメッセージテンプレートシステム​

Twitter OAuth認証​

リフレッシュトークンシステム​

RxJSによるWebSocketサポート​

  • defService を強化し、WebSocketサーバー統合をサポート。
  • RxJS ブリッジによる WebSocket ルート処理。protocol: 'ws' ルートを HTTP ルートと並行して扱います。
  • notFromEmitter および markAsFromEmitter はエミッターベースのメッセージフィルター用です。

🔄 変更​

サービス​

  • 認証サービス: Twitter OAuthサポートとリフレッシュトークン機能を追加; データストアに chatMessageTemplates コレクションを含めるように更新。

🐞 修正​

  • 組織ブロックのエクスポート問題。
  • refreshTokenRoute: リフローフローから isAuthenticated バリデーターを削除。
  • 設定プロパティ名を修正（user.typeIds → identity.typeIds; user?: string → regular?: string）。

マイグレーションガイド（0.6.x ドキュメントからアップグレード）​

  1. @nodeblocks/backend-sdk@^0.14.0 をインストールし、クイックスタート に従う。
  2. userService、/users、および users コレクションの例を profileService、/profiles、および profiles に置き換え。
  3. フラットトークンの有効期限キーを accessTokenSignOptions、refreshTokenSignOptions、および onetimeTokenSignOptions に置き換え。2時間 のアクセストークンが必要な場合は accessTokenSignOptions: { expiresIn: '2h' } を明示的に設定。
  4. cookieセッションの場合、マウントするすべての保護されたサービスに authMode: 'cookie' を設定し、それらのルーターの前に cookie-parser を登録し、ログイン/リフレッシュ時にJSON本文ではなく Set-Cookie からトークンを読み取る。
  5. 削除されたバリデーターインポート（validateResourceAccess、verifyAuthentication、requireParam など）を 共通バリデーター とドメインバリデーターページに記載されている現在のエクスポートに置き換え。
  6. ブロックカタログ とドメイン Reference map テーブルを使用して、各エンドポイントの現在のルート、スキーマ、およびバリデーターコントラクトを見つける。
  7. cookieモードのリフレッシュとlogoutリクエストに x-nb-fingerprint ヘッダーを送信（SDK 0.12.0）。
  8. authService 外で loginWithCredentialsFeature に構築されたカスタム合成に logoutFeature を追加（SDK 0.13.0）。
  9. cookieOpts.maxAge を削除; クッキーの生存期間は一致するトークンの expiresIn に従う（SDK 0.13.0）。
  10. mapErrorToFalse を mapMatchingErrorToFalse(errorClass, [...]) に置き換え（SDK 0.11.0）; 合成ユーティリティ を参照。
  11. authService（および以前にリフレッシュトークンに db.identities を使っていたカスタム合成）に refreshtokens MongoDB コレクションを渡してください。このフィールドは必須です — 配線が欠けるとコンパイル時に失敗します。（SDK 0.14.0）。

破壊的ドキュメント変更​

  • バージョン指定スナップショットは backend_versioned_docs/version-0.6.0 および version-0.7.0 に歴史的参照として残ります。新しい統合では canary v2 ドキュメント /v2/backend/next を使用すべきです。
  • 例はもはやフラットSDKインポート、user* サービス名、または従来のページネーションエンベロープを表示しない。
  • cookieモードのログインとリフレッシュの例は、レスポンス本文にアクセスまたはリフレッシュトークンを返さなくなります; クライアントはセッションクッキーを使用する必要があります。

セキュリティドキュメント更新​

  • cookie認証はcookie保護ルートにundocumented Bearerバイパスを文書しなくなりました; IPチェックは有効デフォルトで checkIp が有効になっています。認証サービス を参照。
  • 変更メールレスポンスは列挙エラーの代わりに 204 を文書化してメールの列挙を減らします; 認証ルート を参照。
  • 組織メンバー保護、通知所有権、および住所検索検証は、それぞれの バリデーター および ルート ページに現在のアクセスルールとともに文書化。