Update Cloudflare as-a-library docs (#133)

Author: bsurmanski

README.md

@@ -1,4 +1,4 @@
-# reCAPTCHA WAF (Edge Compute) Library
+# reCAPTCHA Edge Compute Library
 
 [![Build and Test Core Library](https://github.com/GoogleCloudPlatform/recaptcha-edge/actions/workflows/build_core.yml/badge.svg)](https://github.com/GoogleCloudPlatform/recaptcha-edge/actions/workflows/build_core.yml)
 [![Build and Test Akamai Binding](https://github.com/GoogleCloudPlatform/recaptcha-edge/actions/workflows/build_akamai.yml/badge.svg)](https://github.com/GoogleCloudPlatform/recaptcha-edge/actions/workflows/build_akamai.yml)
@@ -29,9 +29,14 @@ Typically, this involves:
 Please see the [reCAPTCHA Google Cloud Documentation](https://cloud.google.com/recaptcha/docs) for more details on each step.
 
 ### As a Library
-This package has not yet been added to the NPM package repository, and must be manually imported.
+Each platform has their own NPM package. Bindings that are hosted on NPM include:
+* [@google-cloud/recaptcha-cloudflare](https://www.npmjs.com/package/@google-cloud/recaptcha-cloudflare?activeTab=readme)
 
-Please see the examples for each binding in the [bindings](https://github.com/GoogleCloudPlatform/recaptcha-edge/tree/main/bindings) directory of choice.
+Bindings that are not yet hosted on NPM should be [downloaded and installed locally](https://docs.npmjs.com/downloading-and-installing-packages-locally).
+
+The base package is available on NPM as [@google-cloud/recaptcha-edge](https://www.npmjs.com/package/@google-cloud/recaptcha-edge) and is intended as an abstraction layer for implementing additional platforms. Platform-specific packages should be used if possible.
+
+Please see the examples and documentation for each binding in the [bindings](https://github.com/GoogleCloudPlatform/recaptcha-edge/tree/main/bindings) directory of choice.
 
 ## Contribution
 

bindings/akamai/src/index.ts

@@ -25,7 +25,7 @@ import {
   EdgeRequestInit,
   Assessment,
   ListFirewallPoliciesResponse,
-  CHALLENGE_PAGE_URL
+  CHALLENGE_PAGE_URL,
 } from "@google-cloud/recaptcha-edge";
 import { httpRequest, HttpResponse } from "http-request";
 import { TextDecoder, TextEncoder } from "encoding";
@@ -102,7 +102,7 @@ async function readStream(stream: ReadableStream<Uint8Array>): Promise<string> {
 
 const RECAPTCHA_JS = "https://www.google.com/recaptcha/enterprise.js";
 // Firewall Policies API is currently only available in the public preview.
-const DEFAULT_RECAPTCHA_ENDPOINT = "https://public-preview-recaptchaenterprise.googleapis.com";
+const POLICY_RECAPTCHA_ENDPOINT = "https://public-preview-recaptchaenterprise.googleapis.com";
 
 // Some headers aren't safe to forward from the origin response through an
 // EdgeWorker on to the client For more information see the tech doc on
@@ -433,14 +433,19 @@ export class AkamaiContext extends RecaptchaContext {
 }
 
 export function recaptchaConfigFromRequest(request: EW.ResponseProviderRequest): RecaptchaConfig {
+  const has_policy_keys =
+    request.getVariable("PMUSER_RECAPTCHAACTIONSITEKEY") ||
+    request.getVariable("PMUSER_RECAPTCHASESSIONSITEKEY") ||
+    request.getVariable("PMUSER_RECAPTCHACHALLENGESITEKEY");
   return {
     projectNumber: parseInt(request.getVariable("PMUSER_GCPPROJECTNUMBER") || "0", 10),
     apiKey: request.getVariable("PMUSER_GCPAPIKEY") || "",
     actionSiteKey: request.getVariable("PMUSER_RECAPTCHAACTIONSITEKEY") || "",
     expressSiteKey: request.getVariable("PMUSER_RECAPTCHAEXPRESSSITEKEY") || "",
     sessionSiteKey: request.getVariable("PMUSER_RECAPTCHASESSIONSITEKEY") || "",
     challengePageSiteKey: request.getVariable("PMUSER_RECAPTCHACHALLENGESITEKEY") || "",
-    recaptchaEndpoint: request.getVariable("PMUSER_RECAPTCHAENDPOINT") || DEFAULT_RECAPTCHA_ENDPOINT,
+    recaptchaEndpoint:
+      request.getVariable("PMUSER_RECAPTCHAENDPOINT") || (has_policy_keys ? POLICY_RECAPTCHA_ENDPOINT : undefined),
     debug: request.getVariable("PMUSER_DEBUG") === "true",
     unsafe_debug_dump_logs: request.getVariable("PMUSER_UNSAFE_DEBUG_DUMP_LOGS") === "true",
     sessionJsInjectPath: request.getVariable("PMUSER_SESSION_JS_INSTALL_PATH"),

bindings/cloudflare/README.md

@@ -64,9 +64,91 @@ To integrate this package with an existing Cloudflare account:
 Please see the [reCAPTCHA Google Cloud Documentation](https://cloud.google.com/recaptcha/docs) for more details on each step.
 
 ### As a Library
-This package has not yet been added to the NPM package repository, and must be manually imported.
+This package has been added to the NPM package repo as [@google-cloud/recaptcha-cloudflare](https://www.npmjs.com/package/@google-cloud/recaptcha-cloudflare?activeTab=readme).
+
+This library supports a standard reCAPTCHA v2 or v3 workflow, and is intended to be used on the [Cloudflare Worker](https://developers.cloudflare.com/workers/) edge compute platform. To use this library, first create a `CloudflareContext` object. This object
+can be initialized with [Cloudflare Environment Variables](https://developers.cloudflare.com/workers/configuration/environment-variables/) or
+inline constants:
+```js
+import {
+  CloudflareContext,
+  recaptchaConfigFromEnv,
+  createAssessment
+} from "@google-cloud/recaptcha-cloudflare";
+
+export default {
+  async fetch(request, env, ctx): Promise<Response> {
+    // initialized from Cloudflare Environment
+    const rcctx = new CloudflareContext(env, ctx, recaptchaConfigFromEnv(env));
+    // OR: initialized inline
+    const rcctx = new CloudflareContext(env, ctx, {projectNumber: 12345, apiKey: "abcd", enterpriseSiteKey: "6Labcdefg"});
+
+    ... // do further processing
+  },
+} satisfies ExportedHandler<Env>;
+```
+
+This context can then be used to call reCAPTCHA's `CreateAssessment` on the incoming Request:
+```js
+    ...
+    const assessment = await createAssessment(rcctx, request);
+    ...
+```
+
+Most common request data expected in [`CreateAssessment`](https://cloud.google.com/recaptcha/docs/reference/rest/v1/projects.assessments/create) will be automatically populated when calling the `createAssessment` function, including:
+* userAgent
+* userIpAddress
+* requestedUri
+* ja3 or ja4
+* headers
+
+The Project number and API Key set when creating the `CloudflareContext` will be used to form the correct `CreateAssessment` endpoint URL. The following URL format will be used: `https://recaptchaenterprise.googleapis.com/v1/projects/{projectNumber}/assessments??key={apikey}`.
+The `enterpriseSiteKey` set when creating the `CloudflareContext` will be used to populate the Assessment event. 
+
+The user's reCAPTCHA token may be automatically extracted from the incoming request body under the following conditions:
+* The incoming requests uses a POST HTTP method
+* The content type is `application/json` or `application/x-www-form-urlencoded` or `multipart/form-data`
+* The token is expected to reside in the `g-recaptcha-response` field.
+
+If all of these cases are true, simply call createAssessment:
+```js
+  ...
+  const assessment = await createAssessment(rcctx, request);
+  ...
+```
+
+If one or more of the token format cases are false, the token must be manually extracted and passed as an additional parameter:
+```js
+  ...
+  const token = manuallyExtractToken(request); // You must define this function.
+  const assessment = await createAssessment(rcctx, request, {token});
+  ...
+```
+
+The `expectedAction` parameter is not automatically populated, and should be populated if applicable.
+```js
+    const assessment = await createAssessment(rcctx, request, {expectedAction: "login"});
+```
+See the official documentation on [action names](https://cloud.google.com/recaptcha/docs/actions-website).
+
+It is important that createAssessment is only called on paths where you expect a user to pass a token. 
+```js
+  import {
+    CloudflareContext,
+    createAssessment,
+    pathMatch,
+  } from "@google-cloud/recaptcha-cloudflare";
+
+  ...
+  if (pathMatch(request, "/login", "POST")) {
+    const assessment = await createAssessment(rcctx, request, {expectedAction: "login"});
+    ... // check assessment results, such as score.
+  }
+    ...
+```
+This will avoid the added latency from the CreateAssessment RPC, and reduce billing events.
 
-Please see the examples in the [examples](https://github.com/GoogleCloudPlatform/recaptcha-edge/tree/main/bindings/cloudflare/examples) directory.
+For complete end-to-end examples, see the [examples](https://github.com/GoogleCloudPlatform/recaptcha-edge/tree/main/bindings/cloudflare/examples) directory.
 
 ## Contribution
 

bindings/cloudflare/examples/account-defender/src/index.ts

@@ -55,7 +55,7 @@ async function recaptchaLoginAccountVerdict(rcctx: CloudflareContext, request: R
     if (!token || !username) {
       return "block";
     }
-    const assessment = await createAssessment(rcctx, request, undefined, {userInfo: {accountId: username}});
+    const assessment = await createAssessment(rcctx, request, {userInfo: {accountId: username}});
     // Block all requests that Account Defender identifies as 'suspicious login activity'.
     if ((assessment.accountDefenderAssessment?.labels ?? []).includes("SUSPICIOUS_LOGIN_ACTIVITY")) {
       return "block";

bindings/cloudflare/examples/simple-block/src/index.ts

@@ -18,7 +18,7 @@
  * A simple example on how to use the reCAPTCHA Cloudflare library to
  * make decisions based on score.
  *
- * This example calls Create assessment based on configuration context from CloudFlare's Env, 
+ * This example calls Create assessment based on configuration context from CloudFlare's Env,
  * and automatically extracted information from the incoming request.
  */
 

bindings/cloudflare/src/cloudflare_worker.test.ts

@@ -49,14 +49,14 @@ test("nomatch-ok", async () => {
         parsedBody.assessmentEnvironment.version = undefined;
         let expected = {
           event: {
+            firewallPolicyEvaluation: true,
             token: "action-token",
             siteKey: "action-site-key",
             wafTokenAssessment: true,
             userIpAddress: "1.2.3.4",
             headers: ["cf-connecting-ip:1.2.3.4", "user-agent:test-user-agent", "x-recaptcha-token:action-token"],
             requestedUri: "http://example.com/condition/blockifscorelow",
             userAgent: "test-user-agent",
-            firewallPolicyEvaluation: true,
           },
           assessmentEnvironment: {
             client: "@google-cloud/recaptcha-cloudflare",

bindings/cloudflare/src/context.ts

@@ -18,7 +18,7 @@ type Env = any;
 
 const RECAPTCHA_JS = "https://www.google.com/recaptcha/enterprise.js";
 // Firewall Policies API is currently only available in the public preview.
-const DEFAULT_RECAPTCHA_ENDPOINT = "https://public-preview-recaptchaenterprise.googleapis.com";
+const POLICY_RECAPTCHA_ENDPOINT = "https://public-preview-recaptchaenterprise.googleapis.com";
 
 // eslint-disable-next-line  @typescript-eslint/no-unused-vars
 import {
@@ -127,6 +127,7 @@ export class CloudflareContext extends RecaptchaContext {
   }
 
   export function recaptchaConfigFromEnv(env: Env): RecaptchaConfig {
+    const has_policy_keys = env.ACTION_SITE_KEY || env.SESSION_SITE_KEY || env.CHALLENGE_PAGE_SITE_KEY;
     return {
       projectNumber: env.PROJECT_NUMBER,
       apiKey: env.API_KEY,
@@ -135,7 +136,7 @@ export class CloudflareContext extends RecaptchaContext {
       sessionSiteKey: env.SESSION_SITE_KEY,
       challengePageSiteKey: env.CHALLENGE_PAGE_SITE_KEY,
       enterpriseSiteKey: env.ENTERPRISE_SITE_KEY,
-      recaptchaEndpoint: env.RECAPTCHA_ENDPOINT ?? DEFAULT_RECAPTCHA_ENDPOINT,
+      recaptchaEndpoint: env.RECAPTCHA_ENDPOINT ?? (has_policy_keys ? POLICY_RECAPTCHA_ENDPOINT : undefined),
       sessionJsInjectPath: env.SESSION_JS_INSTALL_PATH,
       credentialPath: env.CREDENTIAL_PATH,
       accountId: env.USER_ACCOUNT_ID,

bindings/cloudflare/src/wrappers.ts

@@ -46,10 +46,10 @@ export function pathMatch(req: Request, patterns: string | [string], method?: st
 export function createAssessment(
   ctx: CloudflareContext,
   r: Request,
-  environment?: [string, string],
   additionalParams?: Event,
+  environment?: [string, string],
 ): Promise<Assessment> {
-  return callCreateAssessment(ctx, new FetchApiRequest(r), environment, additionalParams);
+  return callCreateAssessment(ctx, new FetchApiRequest(r), additionalParams, environment);
 }
 
 export function listFirewallPolicies(ctx: CloudflareContext): Promise<ListFirewallPoliciesResponse> {

bindings/cloudflare/wrangler.test.toml

@@ -10,5 +10,4 @@ ACTION_SITE_KEY = "action-site-key"
 EXPRESS_SITE_KEY = "express-site-key"
 SESSION_SITE_KEY = "session-site-key"
 CHALLENGE_PAGE_SITE_KEY = "challenge-page-site-key"
-ENTERPRISE_SITE_KEY = "enterprise-site-key"
 RECAPTCHA_ENDPOINT = "https://recaptchaenterprise.googleapis.com"

bindings/fastly/src/context.ts

@@ -20,7 +20,7 @@ import { Dictionary } from "fastly:dictionary";
 
 const RECAPTCHA_JS = "https://www.google.com/recaptcha/enterprise.js";
 // Firewall Policies API is currently only available in the public preview.
-const DEFAULT_RECAPTCHA_ENDPOINT = "https://public-preview-recaptchaenterprise.googleapis.com";
+const POLICY_RECAPTCHA_ENDPOINT = "https://public-preview-recaptchaenterprise.googleapis.com";
 
 import {
   RecaptchaConfig,
@@ -222,6 +222,8 @@ export function recaptchaConfigFromConfigStore(name: string): RecaptchaConfig {
       throw new InitError('Failed to open Fastly config store: "' + name + '". ' + JSON.stringify(e));
     }
   }
+  const has_policy_keys =
+    cfg.get("action_site_key") || cfg.get("session_site_key") || cfg.get("challengepage_site_key");
   return {
     projectNumber: Number(cfg.get("project_number")),
     apiKey: cfg.get("api_key") ?? "",
@@ -230,7 +232,7 @@ export function recaptchaConfigFromConfigStore(name: string): RecaptchaConfig {
     sessionSiteKey: cfg.get("session_site_key") ?? undefined,
     challengePageSiteKey: cfg.get("challengepage_site_key") ?? undefined,
     enterpriseSiteKey: cfg.get("enterprise_site_key") ?? undefined,
-    recaptchaEndpoint: cfg.get("recaptcha_endpoint") ?? DEFAULT_RECAPTCHA_ENDPOINT,
+    recaptchaEndpoint: cfg.get("recaptcha_endpoint") ?? (has_policy_keys ? POLICY_RECAPTCHA_ENDPOINT : undefined),
     sessionJsInjectPath: cfg.get("session_js_install_path") ?? undefined,
     debug: (cfg.get("debug") ?? "false") == "true",
     unsafe_debug_dump_logs: (cfg.get("unsafe_debug_dump_logs") ?? "false") == "true",

bindings/fastly/src/wrappers.ts

@@ -46,10 +46,10 @@ export async function processRequest(ctx: FastlyContext, r: Request): Promise<Re
 export function createAssessment(
   ctx: FastlyContext,
   r: Request,
-  environment?: [string, string],
   additionalParams?: Event,
+  environment?: [string, string],
 ): Promise<Assessment> {
-  return callCreateAssessment(ctx, new FetchApiRequest(r), environment, additionalParams);
+  return callCreateAssessment(ctx, new FetchApiRequest(r), additionalParams, environment);
 }
 
 export function listFirewallPolicies(ctx: FastlyContext): Promise<ListFirewallPoliciesResponse> {

bindings/xlb/src/server.ts

@@ -26,7 +26,7 @@ function getConfig(): RecaptchaConfig {
         sessionSiteKey: process.env.SESSION_SITE_KEY || undefined,
         challengePageSiteKey: process.env.CHALLENGE_PAGE_SITE_KEY || undefined,
         enterpriseSiteKey: process.env.ENTERPRISE_SITE_KEY || undefined,
-        recaptchaEndpoint: process.env.RECAPTCHA_ENDPOINT || "",
+        recaptchaEndpoint: process.env.RECAPTCHA_ENDPOINT || undefined,
         sessionJsInjectPath: process.env.SESSION_JS_INSTALL_PATH || undefined,
         debug: (process.env.DEBUG ?? "false") == "true",
         unsafe_debug_dump_logs: false,

src/createAssessment.ts

@@ -124,8 +124,8 @@ async function getUserInfo(req: EdgeRequest, accountIdField?: string, usernameFi
  * Adds reCAPTCHA specific values to an Event strucutre.
  * This includes, the siteKey, the token, cookies, and flags like express.
  */
-export async function createPartialEventWithSiteInfo(context: RecaptchaContext, req: EdgeRequest): Promise<Event> {
-  const event: Event = {};
+export async function addTokenAndSiteKeyToEvent(context: RecaptchaContext, req: EdgeRequest, base?: Event): Promise<Event> {
+  const event: Event = base ?? {};
   const actionToken = req.getHeader("X-Recaptcha-Token");
   if (context.config.actionSiteKey && actionToken) {
     // WAF action token in the header.
@@ -178,7 +178,7 @@ export async function createPartialEventWithSiteInfo(context: RecaptchaContext,
   }
 
   if (context.config.enterpriseSiteKey && req.method === "POST") {
-    const recaptchaToken = await getTokenFromBody(context, req);
+    const recaptchaToken = event.token ?? await getTokenFromBody(context, req);
     if (recaptchaToken) {
       event.token = recaptchaToken;
       event.siteKey = context.config.enterpriseSiteKey;
@@ -222,20 +222,19 @@ export async function createPartialEventWithSiteInfo(context: RecaptchaContext,
 export async function callCreateAssessment(
   context: RecaptchaContext,
   req: EdgeRequest,
-  environment?: [string, string],
   additionalParams?: Event,
+  environment?: [string, string],
 ): Promise<Assessment> {
   // TODO: this should use a builder pattern. with a CreateAssessmentRequest type.
-  const site_info = await createPartialEventWithSiteInfo(context, req);
+  const site_info = await addTokenAndSiteKeyToEvent(context, req, additionalParams);
   const site_features = await context.buildEvent(req);
   if (req.method === "POST" && new URL(req.url).pathname === context.config.credentialPath) {
     site_features.userInfo = await getUserInfo(req, context.config.accountId, context.config.username);
   }
 
   const event = {
     ...site_info,
-    ...site_features,
-    ...additionalParams,
+    ...site_features
   };
   const assessment: Assessment = { event };
   assessment.assessmentEnvironment = {