A pluggable challenge provider protocol and toolkit for SmartProxy and edge gateways. It defines provider-family contracts, challenge type manifests, and optional HTTP server/client helpers so a gateway can register one provider such as smartchallenge while routes reference concrete challenge types such as wait or turnstile.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Install

pnpm add @push.rocks/smartchallenge

Route Intent

Route configs should store challenge intent only. Runtime wiring, endpoints, ports, provider secrets, and deployment information belong to the gateway that registers the provider.

const challenge = {
  providerId: 'smartchallenge',
  challengeType: 'wait',
  policyRef: 'default-browser',
  settings: {
    waitSeconds: 5,
  },
  clearance: {
    ttlSeconds: 1800,
  },
};

Provider Usage

import { SmartChallengeProvider, WaitChallengeType } from '@push.rocks/smartchallenge';

const provider = new SmartChallengeProvider();
provider.registerChallengeType(new WaitChallengeType());

const manifest = await provider.getManifest();
console.log(manifest.providerId); // smartchallenge
console.log(manifest.challengeTypes.map((type) => type.challengeType)); // ['wait']

SmartChallengeProvider is the provider family. Individual challenge implementations are challenge types advertised by the provider manifest.

HTTP Adapter

The HTTP adapter is optional. It is intended for gateways that want to call a provider over a local relay or service boundary.

import {
  SmartChallengeClient,
  SmartChallengeProvider,
  SmartChallengeServer,
  WaitChallengeType,
} from '@push.rocks/smartchallenge';

const provider = new SmartChallengeProvider({
  challengeTypes: [new WaitChallengeType()],
});

const server = new SmartChallengeServer({ provider, host: '127.0.0.1', port: 0 });
await server.start();

const client = new SmartChallengeClient({ baseUrl: server.url });
const manifest = await client.getManifest();

await server.stop();

The adapter exposes:

GET /manifest
POST /assess
POST /render
POST /verify

Current Challenge Types

wait is the initial deterministic challenge type. It creates an in-memory challenge state, renders a wait page, and verifies once the configured wait time has elapsed. SmartProxy or another gateway remains responsible for route matching, clearance-cookie signing, loop prevention, and final allow/challenge/deny enforcement.

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the repository license file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

readme.md

@push.rocks/smartchallenge