Welcart 2.12 カスタマイズ移行ガイド（開発者向け）

本ガイドは、Welcart のテーマや独自プラグインを実装・保守されている開発者の方を対象とした技術資料です。

Welcart e-Commerce 2.12 では、セキュリティ強化のため uscesid の仕組みを廃止します。
この仕組みを利用しているテーマ・独自プラグインは、更新前に修正が必要です。

本ガイドの修正はすべて後方互換です。現行の Welcart 2.11.x でも従来どおり動作する形で修正できますので、2.12 のリリースを待たず、先に適用・本番反映しておくことを推奨します。

何が変わるのか

uscesid は、難読化したセッションIDを URL やフォームで受け渡し、uscesdc() で復号して session_id() にセットし直す仕組みでした。2.12 ではこの機構を廃止し、次の方式に置き換えます。

用途	2.11.x まで	2.12 以降
ブラウザからの AJAX・3Dセキュア戻り	URL / POST の uscesid を復号してセッションを切り替え	同一オリジンのセッションクッキー（USCES_KEY）でセッションを再開
サーバー間の決済通知	uscesid ブリッジ	取引キーを用いた DB ストアからの復元
会員フォームの nonce キー	$action . $usces->get_uscesid( false )	$action . session_id()（新ヘルパ member_nonce_key() 等）

【2.12 で廃止される供給元】

以下は 2.12 で出力・処理されなくなります。
カスタマイズがこれらに依存している場合、値が取れない／セッションが切り替わらない状態になります。

• usces_session_start() における GET パラメータ uscesid の処理
• JavaScript のローカライズ変数 uscesL10n.uscesid の出力
• 会員・カート・ログイン・ログアウト・新規会員登録・パスワード再発行・お問い合わせ 各 URL への &uscesid= 付与
• 購入フォームの hidden フィールド uscesid
• 会員本人確認メール（メールアドレス認証）URL の uscesid
• 会員フォーム nonce の旧キー方式の受理（2.12 は新方式のみ受理）

【関数定義は 2.12 限りの暫定残置です（あてにしないでください）】

get_uscesid() / uscesdc() / uscescv() の関数定義自体は 2.12 では残しています（@deprecated）。
ただしこれは未移行のコードが即座に致命的エラーにならないようにするための暫定措置で、ごく近い将来のリリースで削除します。2.12 は猶予期間ではありません。これらの関数の存在を前提にしたコードは、今回の更新に合わせて必ず移行してください。

本体はこれらを一切使わなくなり、本体が uscesid を出力する経路も、受け取って処理する経路も無くなります。

• 本体が出力していた値（uscesL10n.uscesid / hidden フィールド / URL の &uscesid=）を前提にしたコードは、2.12 で値が取れなくなります
• 本体に uscesid を渡していたコードは、渡しても無視されます
• 生成（get_uscesid() / uscescv()）と復号（uscesdc()）をカスタマイズ側だけで完結させているコードは、2.12 では動作してしまいます。壊れないため見落とされやすいですが、これは本体が廃止したセッション固定の経路を自前で再現している状態です。関数削除と同時に停止するため、症状が出ていない今のうちに移行してください（「C4：uscescv() の直接呼び出し」参照）

いずれの場合も、本ガイドに従って移行してください。  

影響の有無を判定する

使用中のテーマ・独自プラグインの PHP と JS を対象に、以下のトークンで全文検索してください。

uscesid
uscesdc
uscescv
get_uscesid
uscesL10n.uscesid

ヒットした箇所を、次の分類に振り分けます。

分類	コードの特徴	更新後の症状
C1 セッション復元	$_POST[‘uscesid’] / $_GET[‘uscesid’] → $usces->uscesdc() → session_id() → session_start() の並び（wp_ajax_nopriv_* ハンドラ内が典型）	該当機能が停止（PDF が出ない、候補日が取得できない等）／致命的エラー
C2 生成側（nonce 作成）	$noncekey = ‘post_member’ . $usces->get_uscesid( false ); → wp_nonce_field( … )	フォーム送信が nonce 検証で弾かれる
C2 検証側（nonce 検証）	wp_verify_nonce( $nonce, ‘post_member’ . $usces->get_uscesid( false ) )	正しい送信を不正と判定して弾く
C3 管理URL付与	管理画面の帳票リンク等に ‘&uscesid=’ . $usces->get_uscesid() を連結	パラメータが無意味化（実害は小）
JS 供給	uscesL10n.uscesid の参照、AJAX data への uscesid: 、URL への ?uscesid= 連結	送信値が undefined になる
C4 uscesid 相当値の自前生成	$usces->uscescv( session_id(), … ) を直接呼び、URL・hidden・JS・独自 AJAX に載せている	渡し先が本体なら無視される／自前で uscesdc() 復号している場合は2.12 では動作してしまうが、関数削除で停止

ヒットが 0 件なら、今回の変更によるカスタマイズ側の修正は不要です（バックアップファイルやコメント内のヒットは除外して判断してください）。  

修正パターン

上記で振り分けた分類に応じて、以下の同名の見出し（C1／C2 生成側／C2 検証側／C3／JS 供給／C4）の手順で修正してください。  

C1：セッションクッキーによるセッション再開

uscesdc() によるセッション再構成ブロックを、以下に置換します。USCES_KEY は従来から存在する PHP セッションのクッキー名で、同一オリジンの XHR には 2.11.x でも常に送信されます。そのためこの修正は本体のバージョンを問わず動作します。

// uscesid 廃止対応:
// 受け取った uscesid を uscesdc() で復号する代わりに、
// 同一オリジンのセッションクッキー(USCES_KEY)で買い物客セッションを再開する。
if ( PHP_SESSION_NONE === session_status() ) {
    $usces_options = get_option( 'usces' );
    $sess_name = defined( 'USCES_KEY' ) ? USCES_KEY :
        ( isset( $usces_options['usces_key'] ) ? $usces_options['usces_key'] : '' );
    if ( '' !== $sess_name && ! empty( $_COOKIE[ $sess_name ] ) ) {
        $sess_id = preg_replace( '/[^A-Za-z0-9,-]/', '',
            wp_unslash( $_COOKIE[ $sess_name ] ) );
        session_id( $sess_id );
        @session_start(); // phpcs:ignore
    }
}

【あわせて行うこと】

• $uscesid の取得と、if ( ! $uscesid ) / && $uscesid のような必須チェックを撤去する（uscesid はもう送られてきません）。
• 呼び出し元の JavaScript から uscesid の送信を除去する（「JS 供給」の項参照）。

【絶対に残すこと】

• check_ajax_referer() による nonce 検証
• usces_is_login() / $usces->get_current_member() / $usces->is_order() などの所有者検証

セッションの受け渡し方式を変えるだけの修正です。所有者検証を削除すると、他人の注文書類を取得できる脆弱性（水平権限昇格）になります。  

C2 生成側：method_exists() ガードで分岐

新ヘルパ member_nonce_key() は 2.12 にのみ存在します。
直接呼ぶと 2.11.x で「未定義メソッド」の致命的エラーになるため、必ずガードを付けてください。

$noncekey = method_exists( $usces, 'member_nonce_key' )
    ? $usces->member_nonce_key( 'post_member' )
    : 'post_member' . $usces->get_uscesid( false );
wp_nonce_field( $noncekey, 'wel_nonce' ); // 第2引数のフィールド名は既存値のまま

nonce のフィールド名（第2引数）は変更しないでください。
既存が wel_nonce なら wel_nonce、wc_nonce なら wc_nonce のままにします。変更すると本体側の検証と噛み合わなくなります。 アクション名（’post_member’ など）も既存値を維持してください。  

C2 検証側：method_exists() ガードで分岐

$nonce = isset( $_POST['wc_nonce'] ) ?
    sanitize_text_field( wp_unslash( $_POST['wc_nonce'] ) ) : '';
$ok = method_exists( $usces, 'verify_member_nonce' )
    ? $usces->verify_member_nonce( $nonce, 'post_member' )
    : wp_verify_nonce( $nonce, 'post_member' . $usces->get_uscesid( false ) );
if ( '' === $nonce || ! $ok ) {
    return $mes; // 既存の失敗時処理を維持
}

POST キー名（wc_nonce / wel_nonce 等）と失敗時の戻り値は、既存コードに合わせてください。  

C3：管理画面 URL の uscesid 付与を削除

URL 連結から ‘&uscesid=’ . $usces->get_uscesid() の部分を削除するだけです。他のパラメータはそのまま維持します。

// 修正前
$url = admin_url( 'admin.php?page=usces_orderlist&order_action=pdfout&order_id=' .
    $order_id . &#039;&amp;uscesid=&#039; . $usces-&gt;get_uscesid() );</p>

<p>// 修正後
$url = admin_url( &#039;admin.php?page=usces_orderlist&amp;order_action=pdfout&amp;order_id=&#039; .
    $order_id );

 

JS 供給：JavaScript から uscesid の送信を除去

【削除する記述】

• AJAX データへの付与

  uscesid: uscesL10n.uscesid / formData.append( 'uscesid', ... )

• URL への連結

  "?uscesid=" + uscesL10n.uscesid / "&uscesid=" + ...

• PHP からインライン JS へ埋めている箇所

  uscesid: "<?php echo esc_js( $usces->get_uscesid() ); ?>"

【残す記述】

• action パラメータ、既存の nonce（wc_nonce 等）の送信
• fetch() の credentials: ‘same-origin’
  セッションクッキー送信に必須です。削除するとセッション再開に失敗します
• jQuery.ajax() は同一オリジンなら既定でクッキーを送るため、追加の指定は不要です

C4：uscescv() の直接呼び出し（uscesid 相当値の自前生成）

uscescv() は get_uscesid() が内部で使っている難読化エンコーダです。これを直接呼んでいる場合、uscesid 相当の値を自前で生成して受け渡していることになります。値の渡し先によって対応が分かれます。

(a) 渡し先が Welcart 本体の場合

URL の &uscesid=、購入フォームの hidden、usces_session_start() に解釈させる想定など

2.12 では本体がこの値を一切処理しません。生成と付与をまとめて削除してください（「C3」と同じ扱い）。セッションを引き継ぐことが目的だった場合は、「C1」のセッションクッキー方式に置き換えます。

(b) 渡し先がカスタマイズ自身の AJAX の場合

自前で uscesdc() して session_id() にセットしている

関数定義が 2.12 では残るため、この構成は 2.12 に更新してもそのまま動作します（＝症状が出ません）。ただし本体が廃止したセッション固定の経路をカスタマイズ側で再現している状態であり、関数定義はごく近い将来のリリースで削除されるため、その時点で停止します。動作しているからといって「まだ対応不要」と判断しないでください。症状が出ていない今のうちに、「C1」のクッキー方式へ移行してください。

usces_sessid_force / usces_sessid_flag フィルタを独自に使っている場合も、uscescv() / uscesdc() の挙動を変える目的のフックであり、移行後は不要になります。  

やってはいけないこと

1. 所有者検証（is_order() / get_current_member() 等）や check_ajax_referer() を削除する
   uscesid の除去とこれらは無関係です。削除すると脆弱性になります。
2. 新ヘルパ（member_nonce_key / create_member_nonce / verify_member_nonce）を method_exists() ガードなしで直接呼ぶ
   2.11.x で致命的エラーになります。
3. nonce のフィールド名・アクション名を変更する
   本体側の検証と一致しなくなります。
4. credentials: ‘same-origin’ を削除する
   セッションが再開できなくなります。
5. session_regenerate_id() を独自に呼ぶ／セッションを session_destroy() してから作り直す
   2.12 ではログイン直後に本体がセッションIDを再生成します。カスタマイズ側で重複して操作しないでください。

検証チェックリスト

• C1：対象の AJAX が uscesid を送らずに正しい結果を返す（セッションクッキーのみで会員／カートセッションに到達する）
• C1 negative：クッキーを持たないコンテキストからの同一リクエストが拒否される
• C1 所有者検証：別会員の注文ID・登録IDを指定して取得できないことを確認する（最重要）
• C2：対象フォームの送信が nonce 検証を通過する。nonce を改ざんすると拒否される
• C3：管理画面の帳票出力リンクが従来どおり動作する
• C4：uscescv() の呼び出しが残っていない（動作しているからといって放置しない）
• ページソースと JS に uscesid の痕跡が残っていない
• 現行 2.11.x 環境で正常動作する（先行反映の前提条件）
• 可能であれば 2.12 環境でも動作確認する

【特に入念な確認が必要なケース】

• 決済に絡む処理（決済直前の外部照会、不正検知サービス連携、3Dセキュア前後の処理）
  購入完了までの回帰テストを必ず実施してください
• カート途中で呼ばれる AJAX（お届け日候補の取得など）
  会員・ゲストの両方で、カートセッションに到達できることを実機で確認してください
• PC 用テーマとスマートフォン用テーマで同じコードを複製している場合
  片方だけの修正は不整合の原因になります。両方を同時に修正してください

 

更新タイミングに関する既知の挙動

Welcart 2.12 は会員フォームの nonce について新方式のみを受理します（旧方式との併用受理は行いません）。そのため、本体を更新した瞬間に、更新直前に描画されていたフォームを送信すると、その一回だけ nonce 検証に失敗します。

• 画面を再読み込みすれば回復します
• Welcart 本体自身のフォームでも同様に発生します
• 定常状態では発生しません

エンドユーザー向けには「更新直後にエラーが出た場合は再読み込みのうえ再送信」とご案内ください。  

お問い合わせ