Service: Captcha Service - EyevinnOSC/community GitHub Wiki

Captcha Service

Captcha Service (serviceId birme-captcha-svc) is a lightweight, self-hosted CAPTCHA API that generates challenge images and verifies user responses. In Eyevinn Open Source Cloud (OSC) it is a long-running service instance. License: MIT. Source: birme/captcha-svc.

What it can do

  • Generate a CAPTCHA challenge (token plus base64-encoded image) through /generate.
  • Verify a user's answer against a token through /verify.
  • Protect web forms and endpoints from automated bots without sending user data to a third-party provider.

Creating an instance

Call create-service-instance with serviceId: "birme-captcha-svc". The service has no dependencies on other OSC services and no options besides the name.

{ "name": "mycaptcha" }

Verify with wait-for-service-ready or get-instance-status, then describe-service-instance for the instance URL.

Options

Option Required Type Meaning
name Yes string Name of the instance. Alphanumeric/underscore only (^\w+$), at most 20 characters.

Using the instance

Generate a challenge:

curl https://<instance-url>/generate
{ "token": "abc123", "image": "data:image/png;base64,..." }

Render image in an <img> tag on your form and send the token as a hidden field. On submit, verify:

curl -X POST https://<instance-url>/verify \
  -H "Content-Type: application/json" \
  -d '{"token": "abc123", "answer": "XK9Q2"}'

A correct answer returns { "valid": true }; a wrong answer or expired token returns { "valid": false }, and the form submission should be rejected.

// Generate challenge (server-side)
const genRes = await fetch(`${captchaUrl}/generate`);
const { token, image } = await genRes.json();

// After form submission, verify on the server
const verifyRes = await fetch(`${captchaUrl}/verify`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ token, answer: req.body.captchaAnswer }),
});
const { valid } = await verifyRes.json();
if (!valid) throw new Error('CAPTCHA verification failed');

OSC CLI equivalent of creating the instance:

osc create birme-captcha-svc mycaptcha

Note that OSC puts an authentication gate in front of instance URLs other than /, so server-to-server calls to /generate and /verify may need to authenticate as described for OSC service instances.

Resources

⚠️ **GitHub.com Fallback** ⚠️