@friendlycaptcha/server-sdk 0.1.0

package/docs/server-sdk.verifyresult.wasabletoverify.md

@@ -0,0 +1,17 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@friendlycaptcha/server-sdk](./server-sdk.md) &gt; [VerifyResult](./server-sdk.verifyresult.md) &gt; [wasAbleToVerify](./server-sdk.verifyresult.wasabletoverify.md)
+
+## VerifyResult.wasAbleToVerify() method
+
+Whether the request to verify the captcha was completed. In other words: the API responded with status 200.' If this is false, you should notify yourself and use `getErrorCode()` and `getResponseError()` to see what is wrong.
+
+**Signature:**
+
+```typescript
+wasAbleToVerify(): boolean;
+```
+**Returns:**
+
+boolean
+

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@friendlycaptcha/server-sdk",
+  "version": "0.1.0",
+  "description": "Serverside client SDK for the Friendly Captcha V2 API",
+  "main": "dist/index.js",
+  "type": "module",
+  "scripts": {
+    "build": "npm run build:tsc",
+    "build:dist": "rm -rf dist/ build/ && node scripts/updateVersion.mjs && npm run build:tsc && cp -r build/src/ dist/ && npm run build:apiextractor && npm run build:docs",
+    "build:tsc": "tsc",
+    "build:apiextractor": "api-extractor run --local --verbose",
+    "build:docs": "rm -rf build/docs && api-documenter markdown --output-folder docs --input temp/",
+    "test": "ava test/**/*.ts --timeout=1m",
+    "api-extractor": "api-extractor",
+    "fmt": "prettier src/**/*.ts test/**/*.ts package.json --write"
+  },
+  "author": "Friendly Captcha GmbH",
+  "license": "MIT",
+  "devDependencies": {
+    "@ava/typescript": "^3.0.1",
+    "@babel/cli": "^7.19.3",
+    "@babel/core": "^7.19.3",
+    "@babel/preset-env": "^7.19.3",
+    "@microsoft/api-documenter": "^7.22.27",
+    "@microsoft/api-extractor": "^7.36.2",
+    "ava": "^4.3.1",
+    "esbuild": "^0.16.9",
+    "prettier": "^3.0.0",
+    "sync-request": "^6.1.0",
+    "typescript": "^4.7.4"
+  },
+  "ava": {
+    "files": [
+      "test/**/*"
+    ],
+    "typescript": {
+      "rewritePaths": {
+        "src/": "build/src/",
+        "test/": "build/test/"
+      },
+      "compile": "tsc"
+    }
+  }
+}

package/src/api/errors.ts

@@ -0,0 +1,77 @@
+export type SiteverifyErrorCode =
+  | typeof SITEKEY_INVALID
+  | typeof AUTH_INVALID
+  | typeof AUTH_REQUIRED
+  | typeof BAD_REQUEST
+  | typeof RESPONSE_TIMEOUT
+  | typeof RESPONSE_DUPLICATE
+  | typeof RESPONSE_INVALID
+  | typeof RESPONSE_MISSING
+  | typeof INTERNAL_SERVER_ERROR;
+
+/**
+ * The API key you provided was invalid.
+ *
+ * HTTP status 401.
+ */
+export const AUTH_INVALID = "auth_invalid";
+/**
+ * You forgot to set the `X-API-Key` header.
+ *
+ * HTTP status 401.
+ */
+export const AUTH_REQUIRED = "auth_required";
+
+/**
+ * The sitekey in your request is invalid.
+ *
+ * HTTP status 400.
+ */
+export const SITEKEY_INVALID = "sitekey_invalid";
+
+/**
+ * Something else is wrong with your request, e.g. your request body is empty.
+ */
+export const BAD_REQUEST = "bad_request";
+/**
+ * The response has expired.
+ *
+ * HTTP status 200.
+ */
+export const RESPONSE_TIMEOUT = "response_timeout";
+/**
+ * The response has already been used.
+ *
+ * HTTP status 200.
+ */
+export const RESPONSE_DUPLICATE = "response_duplicate";
+/**
+ * The response you provided was invalid (perhaps the user tried to work around the captcha).
+ *
+ * HTTP status 200.
+ */
+export const RESPONSE_INVALID = "response_invalid";
+/**
+ * You forgot to add the response parameter.
+ *
+ * HTTP status 400.
+ */
+export const RESPONSE_MISSING = "response_missing";
+/**
+ * Something went wrong within the server. (Should never happen).
+ *
+ * HTTP status 500.
+ */
+export const INTERNAL_SERVER_ERROR = "internal_server_error";
+
+export const ERROR_CODE_TO_STATUS: Record<SiteverifyErrorCode, number> = {
+  [SITEKEY_INVALID]: 400,
+  [AUTH_INVALID]: 401,
+  [AUTH_REQUIRED]: 401,
+  [BAD_REQUEST]: 400,
+  [RESPONSE_TIMEOUT]: 200,
+  [RESPONSE_DUPLICATE]: 200,
+  [RESPONSE_INVALID]: 200,
+  [RESPONSE_MISSING]: 400,
+  [INTERNAL_SERVER_ERROR]: 500,
+};

package/src/api/index.ts

@@ -0,0 +1 @@
+export * from "./types";

package/src/api/types.ts

@@ -0,0 +1,66 @@
+import { SiteverifyErrorCode } from "./errors";
+
+/**
+ * The request we make to the Frienldy Captcha API.
+ * @internal
+ */
+export interface SiteverifyRequest {
+  /**
+   * The response value that the user submitted in the frc-captcha-response field
+   */
+  response: string;
+  /**
+   * Optional: the sitekey that you want to make sure the puzzle was generated from.
+   */
+  sitekey?: string;
+}
+
+/**
+ * @public
+ */
+export interface SiteverifyResponseData {
+  challenge: SiteverifyResponseChallengeData;
+}
+
+/**
+ * @public
+ */
+export interface SiteverifyResponseChallengeData {
+  /**
+   * Timestamp when the captcha challenge was completed (RFC3339).
+   */
+  timestamp: string;
+  /**
+   * The origin of the site where the captcha was solved (if known, can be empty string if not known).
+   */
+  origin: string;
+}
+
+/**
+ * @public
+ */
+export interface SiteverifySuccessResponse {
+  success: true;
+  data: SiteverifyResponseData;
+}
+
+/**
+ * @public
+ */
+export interface SiteverifyErrorResponseErrorData {
+  error_code: SiteverifyErrorCode;
+  detail: string;
+}
+
+/**
+ * @public
+ */
+export interface SiteverifyErrorResponse {
+  success: false;
+  error: SiteverifyErrorResponseErrorData;
+}
+
+/**
+ * @public
+ */
+export type SiteverifyResponse = SiteverifySuccessResponse | SiteverifyErrorResponse;

package/src/client/client.ts

@@ -0,0 +1,154 @@
+import type { SiteverifyRequest } from "../api/index.js";
+import {
+  FAILED_DUE_TO_CLIENT_ERROR_CODE,
+  FAILED_TO_DECODE_RESPONSE_ERROR_CODE,
+  FAILED_TO_ENCODE_ERROR_CODE,
+  REQUEST_FAILED_ERROR_CODE,
+  REQUEST_FAILED_TIMEOUT_ERROR_CODE,
+} from "./errors.js";
+import { VerifyResult } from "./result.js";
+import { SDK_VERSION } from "./version.gen.js";
+
+/**
+ * Configuration options when creating a new `FriendlyCaptchaClient`.
+ * @public
+ */
+export interface FriendlyCaptchaOptions {
+  sitekey?: string;
+  /**
+   * Friendly Captcha API Key.
+   */
+  apiKey: string;
+
+  /**
+   * The endpoint to use for the API. Can be "eu", "global", or a custom URL.
+   *
+   * Defaults to `"global"`.
+   */
+  siteverifyEndpoint?: string;
+
+  /**
+   * Whether to use strict mode, which rejects all captcha responses which were not strictly verified.
+   *
+   * This is not recommended. Defaults to `false`.
+   */
+  strict?: boolean;
+
+  /**
+   * The fetch implementation to use. Defaults to `globalThis.fetch`.
+   */
+  fetch?: typeof globalThis.fetch;
+}
+
+const GLOBAL_SITEVERIFY_ENDPOINT = "https://global.frcapi.com/api/v2/captcha/siteverify";
+const EU_SITEVERIFY_ENDPOINT = "https://eu.frcapi.com/api/v2/captcha/siteverify";
+
+/**
+ * A client for the Friendly Captcha API.
+ * @public
+ */
+export class FriendlyCaptchaClient {
+  private sitekey?: string;
+  private apiKey: string;
+  private siteverifyEndpoint: string;
+  private strict: boolean;
+
+  private fetch: typeof globalThis.fetch;
+
+  constructor(opts: FriendlyCaptchaOptions) {
+    this.sitekey = opts.sitekey;
+
+    if (!opts.apiKey) {
+      throw new Error("api key is required");
+    }
+    this.apiKey = opts.apiKey;
+
+    let siteverifyEndpoint = opts.siteverifyEndpoint || "global";
+    if (siteverifyEndpoint === "global") {
+      siteverifyEndpoint = GLOBAL_SITEVERIFY_ENDPOINT;
+    } else if (siteverifyEndpoint === "eu") {
+      siteverifyEndpoint = EU_SITEVERIFY_ENDPOINT;
+    }
+    this.siteverifyEndpoint = siteverifyEndpoint;
+
+    this.strict = !!opts.strict;
+    this.fetch = opts.fetch || globalThis.fetch;
+  }
+
+  /**
+   * Verify a captcha response.
+   *
+   * @param response - The response token from the captcha.
+   * @param opts - Optional options object:
+   *   * `timeout`: The timeout in milliseconds. Defaults to 20 seconds.
+   *   * `sitekey`: The sitekey to use for this request. Defaults to the sitekey passed to the constructor (if any).
+   * @returns A promise that always resolves to a `VerifyResult` object, which contains the fields `shouldAccept()` and `wasAbleToVerify()`. This promise never rejects.
+   */
+  public verifyCaptchaResponse(response: string, opts: { timeout?: number, sitekey?: string } = {}): Promise<VerifyResult> {
+    const siteverifyRequest: SiteverifyRequest = {
+      response,
+    };
+    if (this.sitekey || opts.sitekey) {
+      siteverifyRequest.sitekey = this.sitekey || opts.sitekey;
+    }
+
+    const result = new VerifyResult(this.strict);
+    let body: string;
+
+    try {
+      body = JSON.stringify(siteverifyRequest);
+    } catch (e) {
+      result.clientErrorType = FAILED_TO_ENCODE_ERROR_CODE;
+      return Promise.resolve(result);
+    }
+
+    const headers = {
+      "Content-Type": "application/json",
+      Accept: "application/json",
+      "X-Frc-Sdk": "friendly-captcha-javascript-sdk@" + SDK_VERSION,
+      "X-Api-Key": this.apiKey,
+    };
+
+    const timeout = opts?.timeout || 20_000;
+
+    return new Promise((resolve) => {
+      const controller = new AbortController();
+      const signal = controller.signal;
+      setTimeout(() => {
+        controller.abort();
+        result.clientErrorType = REQUEST_FAILED_TIMEOUT_ERROR_CODE;
+        resolve(result);
+      }, timeout);
+
+      this.fetch(this.siteverifyEndpoint, {
+        method: "POST",
+        headers,
+        body,
+        signal,
+      })
+        .then((response) => {
+          result.status = response.status;
+          if (response.status >= 400 && response.status < 500) {
+            result.clientErrorType = FAILED_DUE_TO_CLIENT_ERROR_CODE;
+          }
+          return response.json().catch(() => {
+            result.clientErrorType = FAILED_TO_DECODE_RESPONSE_ERROR_CODE;
+            resolve(result);
+          });
+        })
+        .then((json) => {
+          if (typeof json !== "object" || json === null) {
+            result.clientErrorType = FAILED_TO_DECODE_RESPONSE_ERROR_CODE;
+            resolve(result);
+            return;
+          }
+          result.response = json;
+          resolve(result);
+        })
+        .catch((e) => {
+          result.clientErrorType = REQUEST_FAILED_ERROR_CODE;
+          resolve(result);
+        });
+    });
+  }
+}

package/src/client/errors.ts

@@ -0,0 +1,42 @@
+/**
+ * Failed to encode the captcha response. This means the captcha response was invalid and should never be accepted.
+ * 
+ * @public
+ */
+export const FAILED_TO_ENCODE_ERROR_CODE = "failed_to_encode_request";
+/**
+ * 
+ * The request couldn't be made, perhaps there is a network outage, DNS issue, or the API is unreachable.
+ * 
+ * @public
+ */
+export const REQUEST_FAILED_ERROR_CODE = "request_failed";
+/**
+ * 
+ * The request couldn't be made, perhaps there is a network outage, DNS issue, or the API is unreachable.
+ * 
+ * @public
+ */
+export const REQUEST_FAILED_TIMEOUT_ERROR_CODE = "request_failed_due_to_timeout";
+/**
+ * An error occured on the client side that could've been prevented. This generally means your configuration is wrong.
+ * 
+ * Check your API key and sitekey.
+ * @public
+ */
+export const FAILED_DUE_TO_CLIENT_ERROR_CODE = "request_failed_due_to_client_error";
+/**
+ * The response from the Friendly Captcha API could not be decoded.
+ * 
+ * @public
+ */
+export const FAILED_TO_DECODE_RESPONSE_ERROR_CODE = "verification_response_could_not_be_decoded";
+/**
+ * @public
+ */
+export type VerifyClientErrorCode =
+  | typeof FAILED_TO_ENCODE_ERROR_CODE
+  | typeof REQUEST_FAILED_ERROR_CODE
+  | typeof REQUEST_FAILED_TIMEOUT_ERROR_CODE
+  | typeof FAILED_DUE_TO_CLIENT_ERROR_CODE
+  | typeof FAILED_TO_DECODE_RESPONSE_ERROR_CODE;

package/src/client/index.ts

@@ -0,0 +1,3 @@
+export * from "./client.js";
+export * from "./result.js";
+export * from "./errors.js";

package/src/client/result.ts

@@ -0,0 +1,151 @@
+import type { SiteverifyErrorResponseErrorData, SiteverifyResponse } from "../api";
+import {
+  FAILED_DUE_TO_CLIENT_ERROR_CODE,
+  FAILED_TO_DECODE_RESPONSE_ERROR_CODE,
+  FAILED_TO_ENCODE_ERROR_CODE,
+  REQUEST_FAILED_ERROR_CODE,
+  REQUEST_FAILED_TIMEOUT_ERROR_CODE,
+  VerifyClientErrorCode,
+} from "./errors.js";
+
+/**
+ * The result of a captcha siteverify request.
+ * 
+ * @public
+ */
+export class VerifyResult {
+
+  private strict: boolean;
+  /**
+   * The HTTP status code of the response.  
+   * `-1` if there was no response.
+   */
+  public status: number = -1;
+
+  /**
+   * The response from the Friendly Captcha API, or null if the request was not made at all.
+   */
+  public response: SiteverifyResponse | null = null;
+  public clientErrorType: VerifyClientErrorCode | null = null;
+
+  constructor(strict: boolean) {
+    this.strict = strict;
+  }
+
+  /**
+   * @returns Whether strict mode was enabled for this verification.
+   */
+  public isStrict(): boolean {
+    return this.strict;
+  }
+
+  /**
+   * @returns Whether the captcha should be accepted.   
+   * Note that this does not necessarily mean it was verified.
+   */
+  public shouldAccept(): boolean {
+    if (this.wasAbleToVerify()) {
+      // We want to reject in case we were not able to encode the captcha response sent by the client.
+      // This is because an attacker could send malformed data that can not be encoded, and if we would accept that
+      // they could circumvent the captcha.
+      if (this.isEncodeError()) {
+        return false;
+      }
+
+      return this.response!.success === true;
+    }
+    if (this.clientErrorType !== null) {
+      if (this.strict) {
+        // In strict mode we reject on any error.
+        return false;
+      } else if (
+        this.clientErrorType === REQUEST_FAILED_ERROR_CODE ||
+        this.clientErrorType === REQUEST_FAILED_TIMEOUT_ERROR_CODE ||
+        this.clientErrorType === FAILED_DUE_TO_CLIENT_ERROR_CODE ||
+        this.clientErrorType === FAILED_TO_DECODE_RESPONSE_ERROR_CODE
+      ) {
+        // In case of failures that are not the captcha response being invalid or rejected, we accept.
+        // This is because we don't want to lock out all users in case of a temporary network outage or a misconfiguration.
+        return true;
+      } else {
+        return false;
+      }
+    }
+
+    throw new Error(
+      "Implementation error in @friendlycaptcha/server-sdk shouldAccept: errorCode should never be undefined if success is false. " +
+        JSON.stringify(this),
+    );
+  }
+
+  /**
+   * @returns The reverse of `shouldAccept()`.
+   */
+  public shouldReject(): boolean {
+    return !this.shouldAccept();
+  }
+
+  /**
+   * Was unable to encode the captcha response. This means the captcha response was invalid and should never be accepted.
+   */
+  public isEncodeError(): boolean {
+    return this.clientErrorType === FAILED_TO_ENCODE_ERROR_CODE;
+  }
+
+  /**
+   * Something went wrong making the request to the Friendly Captcha API, perhaps there is a network connection issue?
+   */
+  public isRequestOrTimeoutError(): boolean {
+    return this.clientErrorType === REQUEST_FAILED_ERROR_CODE || this.clientErrorType === REQUEST_FAILED_TIMEOUT_ERROR_CODE;
+  }
+
+  /**
+   * Something went wrong decoding the response from the Friendly Captcha API.
+   */
+  public isDecodeError(): boolean {
+    return this.clientErrorType === FAILED_TO_DECODE_RESPONSE_ERROR_CODE;
+  }
+
+  /**
+   * Something went wrong on the client side, this generally means your configuration is wrong.
+   * Check your secrets (API key) and sitekey.
+   *
+   * See `getResponseError()` for more information.
+   */
+  public isClientError(): boolean {
+    return this.clientErrorType === FAILED_DUE_TO_CLIENT_ERROR_CODE;
+  }
+  /**
+   * @returns The response from the Friendly Captcha API, or null if the request was not made at all.
+   */
+  public getResponse(): SiteverifyResponse | null {
+    return this.response;
+  }
+
+  /**
+   * @returns The `error` field form the response, or null if it is not present.
+   */
+  public getResponseError(): SiteverifyErrorResponseErrorData | null {
+    if (!this.response || this.response.success) return null;
+    return this.response.error;
+  }
+
+  public getErrorCode(): VerifyClientErrorCode | null {
+    return this.clientErrorType;
+  }
+
+  /**
+   * Whether the request to verify the captcha was completed. In other words: the API responded with status 200.'
+   * If this is false, you should notify yourself and use `getErrorCode()` and `getResponseError()` to see what is wrong.
+   */
+  public wasAbleToVerify(): boolean {
+    // If we failed to encode, we actually consider `wasAbleToVerify` to be true. This is because we don't want to 
+    // alert on failed encoding: an attacker could send such malformed data that it fails to encode.
+    if (this.isEncodeError()) {
+      return true;
+    }
+
+    // We got a status 200, and we were able to actually make the request and decode its response.
+    return this.status === 200 && !this.isRequestOrTimeoutError() && !this.isDecodeError();
+  }
+}

package/src/client/version.gen.ts

@@ -0,0 +1,3 @@
+// This file is auto-generated by scripts/updateVersion.mjs
+// Do not edit this file directly
+export const SDK_VERSION = "0.1.0";

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./api/index.js";
+export * from "./client/index.js";

package/test/client/client.test.ts

@@ -0,0 +1,48 @@
+import test from "ava";
+import { FriendlyCaptchaClient } from "../../src/client/index.js";
+
+// More of a test pre-assertion than anything else.
+test("globalThis.fetch is present", (t) => {
+  t.assert(globalThis.fetch);
+});
+
+test("client without API key throws", (t) => {
+  t.throws(() => {
+    const client = new FriendlyCaptchaClient({} as any);
+  });
+});
+
+test("client with API key does not throw", (t) => {
+  const client = new FriendlyCaptchaClient({ apiKey: "test" });
+  t.assert(client);
+});
+
+test("unencodable response gets rejected", async (t) => {
+  const circularReference = { self: undefined as any };
+  circularReference.self = circularReference;
+
+  const client = new FriendlyCaptchaClient({ apiKey: "my-api-key" });
+  const result = await client.verifyCaptchaResponse(circularReference as any);
+
+  t.true(result.isEncodeError());
+  t.false(result.isClientError());
+  t.false(result.isRequestOrTimeoutError());
+  t.false(result.isDecodeError());
+
+  t.false(result.shouldAccept());
+  t.true(result.shouldReject());
+});
+
+test("request failure gets accepted", async (t) => {
+    const client = new FriendlyCaptchaClient({ apiKey: "my-api-key", siteverifyEndpoint: "http://localhost:9999" }); // Assumes nothing is listening on port 9999
+    const result = await client.verifyCaptchaResponse("something");
+  
+    t.false(result.isEncodeError());
+    t.false(result.isClientError());
+    t.true(result.isRequestOrTimeoutError());
+    t.false(result.isDecodeError());
+  
+    t.true(result.shouldAccept());
+    t.false(result.shouldReject());
+  });
+  

package/test/client/mock.test.ts

@@ -0,0 +1,44 @@
+import test from "ava";
+import request from "sync-request";
+import { FriendlyCaptchaClient } from "../../src/client/index.js";
+
+// Tests served from the SDK test mock server
+const mockServerUrl = "http://localhost:1090";
+
+type TestCase = {
+  name: string;
+  response: string;
+  strict: boolean;
+
+  siteverify_response: any;
+  siteverify_status_code: number;
+
+  expectation: {
+    should_accept: boolean;
+    was_able_to_verify: boolean;
+    is_client_error: boolean;
+  };
+};
+
+type TestCasesFile = {
+  version: number;
+  tests: TestCase[];
+};
+
+const casesFile: TestCasesFile = JSON.parse(request("GET", `${mockServerUrl}/api/v1/tests`).getBody("utf8"));
+
+for (const testCase of casesFile.tests) {
+  test(testCase.name, async (t) => {
+    const client = new FriendlyCaptchaClient({
+      apiKey: "some-api-key",
+      siteverifyEndpoint: `${mockServerUrl}/api/v2/captcha/siteverify`,
+      strict: testCase.strict,
+    });
+
+    const result = await client.verifyCaptchaResponse(testCase.response);
+
+    t.is(result.shouldAccept(), testCase.expectation.should_accept);
+    t.is(result.wasAbleToVerify(), testCase.expectation.was_able_to_verify);
+    t.is(result.isClientError(), testCase.expectation.is_client_error);
+  });
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+    "compilerOptions": {
+      "moduleResolution": "node",
+      "target": "es6",
+      "module":"es2015",
+      "lib": ["es2015", "es2016", "es2017", "dom"],
+      "strict": true,
+      "sourceMap": true,
+      "declaration": true,
+      "allowSyntheticDefaultImports": true,
+      "outDir": "build/",
+      "typeRoots": [
+        "node_modules/@types"
+      ]
+    },
+    "include": [
+      "src",
+      "test"
+    ]
+  }