@gkcaptcha/m2m

Machine-to-machine verification for gkCAPTCHA. Solve proof-of-work challenges server-side and obtain short-lived verification tokens without any browser interaction.

Installation

npm install @gkcaptcha/m2m

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | GKCAPTCHA_API_URL | Yes (or pass apiUrl) | Base URL for the gkCAPTCHA API (e.g. https://api.gatekeeper.sa) |

Usage

import { verifyM2M } from '@gkcaptcha/m2m'

const result = await verifyM2M({
  siteKey: 'pk_live_your_site_key',
  secretKey: 'sk_live_your_secret_key',
  apiUrl: 'https://api.gatekeeper.sa', // or set GKCAPTCHA_API_URL
})

if (result.success) {
  console.log('Token:', result.token)
  console.log('Expires at:', result.expiresAt)
} else {
  console.error('Verification failed:', result.reasonCode)
}

Middleware

Express middleware that automatically verifies M2M tokens on incoming requests:

import express from 'express'
import { createM2MMiddleware } from '@gkcaptcha/m2m'

const app = express()

app.use(
  '/api/protected',
  createM2MMiddleware({
    siteKey: 'pk_live_your_site_key',
    secretKey: 'sk_live_your_secret_key',
    apiUrl: 'https://api.gatekeeper.sa',
  })
)

app.post('/api/protected/data', (req, res) => {
  res.json({ message: 'Authenticated via M2M' })
})

How It Works

The M2M SDK fetches a proof-of-work challenge, solves it server-side using SHA-256, and submits the solution for a short-lived token. The solve loop has a configurable iteration cap (default 10 million) to prevent infinite loops on unreasonable difficulty levels.

Token Caching

Tokens are cached by default. Pass cache: false to disable:

const result = await verifyM2M({
  siteKey: 'pk_live_your_site_key',
  secretKey: 'sk_live_your_secret_key',
  cache: false,
})