Google reCAPTCHA: トークン, 検証

// GraalJS Script (engine type: 2)

//////// START "main()" /////////////////////////////////////////////////////////////////

main();
function main(){ 

////// == Config Retrieving / 工程コンフィグの参照 ==
const strAuthzSetting     = configs.get      ( "AuthzConfU" );   /// REQUIRED
  engine.log( " AutomatedTask Config: Authz Setting: " + strAuthzSetting );
  const strRecSecretKey   = httpClient.getOAuth2Token( strAuthzSetting );
    // https://questetra.zendesk.com/hc/en-us/articles/360024574471-R2300#HttpClientWrapper
    // https://questetra.zendesk.com/hc/ja/articles/360024574471-R2300#HttpClientWrapper
const strRecToken         = configs.get      ( "StrConfA1" );    /// REQUIRED
  if( strRecToken       === "" ){
    throw new Error( "\n AutomatedTask ConfigError:" +
                     " Config {A1: RecToken} must be non-empty \n" );
  }
const strPocketBoolean    = configs.getObject( "SelectConfB1" ); // NotRequired
const numstrPocketScore   = configs.getObject( "SelectConfB2" ); // NotRequired
const strPocketAction     = configs.getObject( "SelectConfB3" ); // NotRequired
const strPocketHostname   = configs.getObject( "SelectConfB4" ); // NotRequired


////// == Data Retrieving / ワークフローデータの参照 ==
// (Nothing. Retrieved via Expression Language in Config Retrieving)


////// == Calculating / 演算 ==
//// request1, prepare
// Google Developer Products > reCAPTCHA > Guides
// https://developers.google.com/recaptcha/docs/v3#site_verify_response
// https://developers.google.com/recaptcha/docs/verify#api_request
let request1Uri = "https://www.google.com/recaptcha/api/siteverify";
let request1    = httpClient.begin(); // HttpRequestWrapper
    request1    = request1.formParam( "secret",   strRecSecretKey );
    request1    = request1.formParam( "response", strRecToken     );

//// request1, try
const response1     = request1.post( request1Uri ); // HttpResponseWrapper
engine.log( " AutomatedTask ApiRequest1 Start: " + request1Uri );
const response1Code = response1.getStatusCode() + "";
const response1Body = response1.getResponseAsString() + "";
engine.log( " AutomatedTask ApiResponse Status: " + response1Code );
if( response1Code !== "200"){
  throw new Error( "\n AutomatedTask UnexpectedResponseError: " +
                    response1Code + "\n" + response1Body + "\n" );
}

//// response1, parse
const response1Obj = JSON.parse( response1Body );

/* engine.log( response1Body ); // debug
{
  "success": true,
  "challenge_ts": "2022-11-09T08:45:57Z",
  "hostname": "support.questetra.com",
  "score": 0.9,
  "action": "DemoInquiry"
}
*/



////// == Data Updating / ワークフローデータへの代入 ==

if( strPocketBoolean !== null ){
  engine.setData( strPocketBoolean, ( response1Obj.success + "" ) );
} // java.lang.Boolean ⇒ string
if( numstrPocketScore !== null ){
  let numTmp = response1Obj?.score; // reCAPTCHA v2
  if( numTmp !== undefined ){
    if( numstrPocketScore.matchDataType( "STRING" ) ){
      engine.setData( numstrPocketScore, ( numTmp + "" ) );
    }else{
      engine.setData( numstrPocketScore, new java.math.BigDecimal( numTmp ) );
    }
  }
}
if( strPocketAction !== null ){
  engine.setData( strPocketAction, ( response1Obj?.action ?? "" ) ); // No set, reCAPTCHA v2, 
}
if( strPocketHostname !== null ){
  engine.setData( strPocketHostname, response1Obj.hostname );
}
// "?.": Optional chaining (ES11)
// https://developer.mozilla.org/docs/Web/JavaScript/Reference/Operators/Optional_chaining
// "??": Nullish coalescing operator (ES11)
// https://developer.mozilla.org/docs/Web/JavaScript/Reference/Operators/Nullish_coalescing
// オプショナルチェーン演算子とNull合体演算子の組み合わせ

} //////// END "main()" /////////////////////////////////////////////////////////////////



/*
Notes:
- reCAPTCHA is a CAPTCHA system that enables web hosts to distinguish between human access and bot access.
    - reCAPTCHA v3 is a free service from Google that helps protect websites from spam and abuse.
    - CAPTCHA: Completely Automated Public Turing test to tell Computers and Humans Apart
- The reCAPTURE Token is generated on the website side.
    - HTML/JavaScript implementation is required. Example code:
        - https://support.questetra.com/tips/workflow-trigger-code-202211/send-inquiry-with-recaptcha-token/
    - Official Document
        - https://developers.google.com/recaptcha/docs/v3
- The reCAPTURE Token is validated on the backend side (the server side that received the Form data).
    - Verification results are output as "boolean" and "score".
        - If the boolean value is "true", it was very likely a human operation.
        - If the boolean value is "false", it was very likely a bot operation.
        - The closer the score is to "1.0", the higher the possibility of human operation.
- If you place this "Addon Automated Step" on the Workflow diagram, it will be automatically verified.
    - A verification request is sent to the Google reCAPTCHA v3 server. (API communication)
    - Automatically judge whether the person filling out the form on the website is robot or human.

APPENDIX
- Registration is required to use reCAPTCHA. (to get two types of keys)
    - https://www.google.com/recaptcha/admin/
        - reCAPTCHA type: `reCAPTCHA v3`
        - Site Key: (for Token generation)
        - Secret Key: (for Token verification)
- To place this "Add-on Automated Step" on the design screen of the workflow diagram
    - Import Addon-XML (definition file of this automated step) to Workflow App in advance.
    - The system admins can also make it available in all Workflow Apps. (App-shared Add-on)
    - Manual M415: Adding an Auto-Step to be Used in a Business Process Definition
        - https://questetra.zendesk.com/hc/en-us/articles/360002247792-M415
- To activate the Workflow App including this "Add-on automated Step", "HTTP Authorization Setting" is required.
    - Set the "Secret Key" obtained by reCAPTCHA in advance as an API communication token. "Token Fixed Value"
    - ("OAuth2 authorization" and "Basic authentication" are not used)

Notes-ja:
- "reCAPTCHA" は、スパムや不正利用からWebサイトを守る Google サービスです。
    - Webホスト側が人間アクセスとBotアクセスを区別するための CAPTCHA システムです。
    - "CAPTCHA" とは "Completely Automated Public Turing test to tell Computers and Humans Apart" の略です。
- reCAPTURE Token は、Webサイト側で生成されます。
    - HTML/JavaScript による実装が必要です。サンプルコード↓
        - https://support.questetra.com/tips/workflow-trigger-code-202211/send-inquiry-with-recaptcha-token/
    - オフィシャルDocument
        - https://developers.google.com/recaptcha/docs/v3
- reCAPTURE Token は、バックエンド側（Form データを受信したサーバ側）で検証されます。
    - 検証結果は「真偽値」および「スコア」として出力されます。
        - 真偽値が "true" の場合、人間操作だった可能性が非常に高いと言えます。
        - 真偽値が "false" の場合、ボット操作だった可能性が非常に高いと言えます。
        - スコアが "1.0" に近ければ近いほど人間操作の可能性が高いと言えます。
- この［アドオン自動工程］をワークフロー図に配置すれば、案件が工程に到達した際、自動的に検証されます。
    - Google reCAPTCHA v3 サーバに対して検証リクエストが送信されます。（API通信）
    - Webサイトのフォーム入力者が「ロボットだったか？人間だったか？」について自動判定されます。

APPENDIX-ja
- reCAPTCHA を利用するには、Webサイトの事前登録が必要です。（二種類のキーを取得できます）
    - https://www.google.com/recaptcha/admin/
        - reCAPTCHA type: `reCAPTCHA v3`
        - Site Key: (Token生成に必要です)
        - Secret Key: (Token検証に必要です)
- この［アドオン自動工程］を、ワークフロー図の設計画面で配置（利用）できるようにするには…、
    - 予め、アドオンXML（この自動工程の定義ファイル）を、［Workflowアプリ］に追加（アドオン）します。
    - システム管理者の場合、Workflow基盤の全アプリで配置できるようにする設定も可能です。（アプリ共有アドオン）
        - マニュアル M415: 業務プロセス定義で利用可能な自動工程を追加する (Professional edition)
        - https://questetra.zendesk.com/hc/ja/articles/360002247792-M415
- この［アドオン自動工程］を含むワークフローアプリを運用するには［HTTP 認証設定］が必要です。
    - 予め、reCAPTCHA で取得した "Secret Key" を通信トークンとしてセットします。［トークン直接指定］
    - （"OAuth2 認可" や "Basic 認証" といった管理者アカウントに紐づく権限管理は利用されません）
*/