振込1件を追跡する

金融更新を戻す範囲と、失敗後に残す記録

金融更新の仕訳・transfers・残高cache・成功audit（TRANSFER_COMPLETEDと内側の変更trigger）は、confirm_transfer_otpの内側の例外blockでまとめてrollbackします。先に保存済みのrequestは消えません。transfer_auth.consumeによる認可済みintentの消費（consumed_at）、request=failed、TRANSFER_FAILEDは内側のrollbackの対象外で、外側のDB transactionがcommitすると残ります。

TOTPコードの正誤はDBではなくSupabase Authが判定します。DBはNext.jsのtransfer_mfa_broker経由で検証前に試行を予約し、その時点でintentのattemptsを加算します（累積5回まで、間隔30秒以上）。認証に失敗しても変わるのはintentとAuth側の状態だけで、requestはpending_otpのまま、金融データも変わりません。新しい認可がないままconfirmすると、transfer_auth.consumeが42501で拒否し、その呼出し全体がrollbackします。request=failedは金融更新の例外を捕捉した経路です。未捕捉例外・deferred constraint・commit自体の失敗なら、その呼出し全体の変更がrollbackするため、失敗記録の永続化を無条件には保証しません。

振込intentに束縛した認証アプリTOTPと、再試行・上限契約

v7（migration 20260920074653と20260920083426）の振込認可は、Supabase Authの認証アプリTOTPを振込intentへ束縛する方式です。request_transferは確認コードを生成・返却せず（otp_plaintext列は応答互換のため残り、常にnull）、reissue_transfer_otpは常に42501で拒否します。prepare_transfer_mfaは所有者・Auth session・送金元・送金先・金額・memo・依頼人名・idempotency key・期限のhashをintentへ固定します。ブラウザはコードをSupabase Authへ直接送り、Next.jsとDBはコードも、そのhashも受け取らず保存もしません。DBはAuth所有のchallenge検証時刻、AAL2 session、同じsessionのTOTP AMRを読んで認可し、confirmは60秒以内の認可を1回だけ消費します。DEMO_OTP_DISPLAY_ENABLEDでDBのコード生成は復活しません。TOTPは時刻ごとの値で、振込先や金額への署名ではなく、フィッシング耐性も主張しません。稼働DBへの適用はこの教材ではUNKNOWNです。

Java経路の実装と稼働確認を分ける

request/confirmはPAYMENT_BACKENDで選択します。未設定・空文字・legacyはNext.js→PostgREST RPC、javaはNext.js→Java Payment Service→PostgREST RPCです。不正な値はエラー、Javaのtimeout・5xx・通信断でもlegacyへ自動fallbackしません。旧OTP再発行はこの切替の対象外で、v7のRPCは常に42501で拒否します。TOTPの認可準備はNext.jsの/api/v1/transfers/mfaが担います。コードの存在は確認済みですが、本番・PreviewでJavaが選択されているかはUNKNOWNです。

1. 01Next.jsがPAYMENT_BACKENDを読む
2. 02legacy：呼出者tokenでPostgRESTへ / java：Java Payment ServiceへHTTP
3. 03request_transfer / confirm_transfer_otpでDB処理
4. 04Javaの@TransactionalではHTTP先のcommitを取り消せない
5. 05応答消失時は結果不明。別backendへ自動fallbackしない

現在の振込フロー：依頼と実行を分ける

1. 01振込情報入力：振込先口座・金額・依頼人名・メモ
2. 02POST /api/v1/transfers/request：Bearer token、入力、Idempotency-Keyを検証
3. 03request_transfer()：振込依頼を作成。確認コードは作らず、この時点ではお金を動かさない
4. 04確認画面：DBが解決した銀行・支店・預金種目・口座名義を表示
5. 05POST /api/v1/transfers/mfa：prepare_transfer_mfa()が内容とAuth sessionをintentへ固定
6. 06ブラウザがSupabase AuthでTOTP challengeを作り、serverがbrokerでintentへ束縛
7. 07serverが検証試行を予約した後、ブラウザがTOTPコードをSupabase Authへ直接送る
8. 08serverがbrokerで認可を完了。DBがAuth所有の検証記録・AAL2・同じsessionのTOTP AMRを確認
9. 09POST /api/v1/transfers/otp/confirm → confirm_transfer_otp()：owner・依頼状態・期限を確認し、transfer_auth.consumeで認可を1回だけ消費
10. 10execute_transfer()を内部実行し、2口座をlockしてLedger・transfer・残高cache・Auditを確定
11. 11入出金明細へ振込情報を表示し、管理者の振込監視から状態を確認

第1段階：request_transfer()は、依頼を固定する

このRPCは資金移動を行いません。callerをauth.uid()から特定し、KYC、送金元、送金先、自己送金、入力、1回500,000円の上限、利用者ごと直近1分5件の頻度を検査したうえで、transfer_requestsだけを作ります。v7では確認コードもtransfer_otp_challengesの行も作らず、応答のotp_plaintextは互換用で常にnullです。

銀行名・コードは『ミニ銀行 / 0001』、支店名・コードは『本店営業部 / 001』へserver側で固定され、口座名義は送金先customerから解決されます。利用者が名義を偽装して保存する経路はありません。

TOTPコードをアプリとDBへ入れない：intentへの束縛

TOTPコードはブラウザからSupabase Authへ直接送られます。Next.jsのAPIとDBはコードもそのhashも受け取らず、保存もしません。代わりにDBは、Auth所有のchallengeの検証時刻、AAL2へ上がったsession、同じsessionのTOTP AMR（認証方法の記録）を読み取り専用で確認します。ブラウザからの『成功した』という申告やJWTのAAL2 claimだけでは認可になりません。

transfer_mfa_brokerはNext.jsのserverだけが呼べるよう、呼出者・sessionの一致に加え、環境ごとのserver secret（TRANSFER_MFA_SERVER_SECRET）のdigest照合を要求します。6桁のTOTPは総当たり可能な小さな空間なので、検証前にserverが試行を予約してattemptsを加算し（intentごと累積5回・間隔30秒以上）、challengeの束縛も最大4件・間隔30秒以上に制限します。新しいchallengeで試行回数はリセットしません。別intentの認可から90秒以内は、同じTOTPの時間枠を使い回せないよう拒否します。

旧デモOTP（salt付きhash保存、request/reissue RPCが平文を返しDEMO_OTP_DISPLAY_ENABLEDで画面表示）は#128以前の実装です。v7のDBはコードを生成せず、reissue_transfer_otpは常に42501を返します。

第2段階：confirm_transfer_otp()から資金移動する

confirm RPCはtransfer_requestsの行をFOR UPDATEして所有者を確認します。completedなら同じtransfer_idを返し、再度資金を動かしません。それ以外はpending_otpであることを確認し、依頼期限を過ぎていればrequest=expiredにしてrequest_expiredを返します。p_otp_code引数は互換のため残っていますが、v7の本体はコードを検証に使いません。

次にtransfer_auth.consume()が、同じ利用者・同じsession・認可から60秒以内・未消費・期限内・内容hash一致・AAL2のTOTP factorを確認してintentを消費します。その後requestをprocessingにして、例外block内でexecute_transfer()を呼びます。資金移動が失敗した場合、内側の実行変更はrollbackされますが、外側ではintentの消費とrequest=failed、TRANSFER_FAILEDを保存できます。

execute_transfer()が守る資金移動

• auth.uid()、金額、送金先、idempotency keyを確認
• 送金先と金額のfingerprintで、同じkeyの別内容を拒否
• 顧客、KYC、両口座のactive状態、自己送金を確認
• 2口座をUUID順にFOR UPDATEし、競合とdeadlock riskを抑える
• lock後に冪等性、Ledger残高、口座状態を再確認
• 送金元預金負債をdebit、送金先預金負債をcreditとして同額記帳
• transfersへ業務情報snapshotを追加
• Ledgerから両cached_balanceを再計算
• TRANSFER_COMPLETED business auditを追加

送金元 Customer Deposit Liability : debit  10,000
送金先 Customer Deposit Liability : credit 10,000
                       debit合計 = credit合計

振込先情報とお気に入り

transfer_beneficiariesは利用者ごとの振込先masterです。登録時に実口座の存在・active状態・自己口座でないことをDBが検査し、銀行・支店・名義をserver側で固定します。利用者が更新できるのはlabelとis_favoriteだけで、振込先口座自体の変更は削除と再登録です。

tableはRLS有効かつanon/authenticated/service_roleの直接権限がなく、list/create/update/deleteのSECURITY DEFINER RPCがauth.uid()でownerを確認します。別利用者のIDはnot foundへ畳み、存在列挙も抑えます。

履歴と管理者監視は、見る目的が違う

顧客履歴はLedgerへpostedされた取引だけを返すためstatusはcompletedです。認証待ち（pending_otp）や失敗も運用監視する管理者画面は、資金移動前を含むtransfer_requestsのlifecycleを読みます。admin wrapperはauth.uid()からactive operatorを確認し、検索とcursor paginationをprivate ops functionへ委譲します。

実際にテストが発見した3つのバグ

実際のMinibankでは

現在の振込はrequest/confirm経路を通ります。認証済みの旧POST /api/v1/transfersは409 OTP_REQUIREDを返します。execute_transferはPUBLIC・anon・authenticated・service_roleからEXECUTEを剥奪し、所有者権限のconfirm_transfer_otpから内部実行します。古いcreateTransferのコードが残っていても、顧客の直接実行権限を意味しません。振込先情報は業務recordへ保存し、Ledgerの形は従来どおり借貸2行のままです。