@crvouga/mockingbird-service-recaptcha 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog — @crvouga/mockingbird-service-recaptcha
+
+## 0.1.0 (2026-10-05)
+
+Initial release.

package/DISCOVERY.md

@@ -0,0 +1,55 @@
+# @crvouga/mockingbird-service-recaptcha discovery
+
+This is the installed-package index for coding agents and tooling. All relative links resolve
+inside `node_modules/@crvouga/mockingbird-service-recaptcha/`; no repository checkout is needed to discover the mock's
+supported surface or documented behavior.
+
+## Capability and behavior sources
+
+| Question | Authoritative file | What it contains |
+| --- | --- | --- |
+| Behaviour and integration | [`README.md`](README.md) | Routes, state transitions, auth, webhooks, controls, presets and deliberate omissions. |
+| Exact capabilities | [`SUPPORT.md`](SUPPORT.md) | Supported, unsupported and parity-covered operations or commands, including reasons for gaps. |
+| Wire contract | [`openapi.yaml`](openapi.yaml) | Machine-readable paths, methods, schemas, responses and parity annotations. |
+| Public API | [`dist/index.d.ts`](dist/index.d.ts) | The installed package's exact TypeScript exports and signatures. |
+| Package metadata | [`package.json`](package.json) | Runtime/entry-point claims, vendor links, parity scope/tier and `mockingbird.discovery`. |
+
+Read these together: the contract/capability matrix says *what* is available, while the README
+defines stateful behavior, lifecycle rules, test controls, and intentional oracle differences.
+If prose and an executable surface disagree, report a parity mismatch instead of adding a
+consumer-side workaround.
+
+## Parity and oracle
+
+- Declared parity surface: **v3 browser API and token verification**.
+- Parity tier: **cold** (the repository controls when live checks run).
+- Oracle: **Live vendor API or sandbox**.
+- Repository command: `bun run parity:service -- recaptcha`.
+- Evidence model: Run from a Mockingbird checkout; credentials come only from .env.local or GitHub Actions secrets. Missing credentials exit 2.
+
+The npm package contains evidence summaries and the exact contract, not credentials or the
+repository-only parity harness. Self-parity/property and acceptance tests run in the Mockingbird
+repository; live parity is an additional oracle check, not a substitute for the packaged matrix.
+
+## Runtime introspection
+
+- `GET /__admin/health`
+- `GET /__admin`
+- `GET /__admin/state`
+- `GET /__admin/requests`
+- `GET /__admin/metrics`
+- `GET /__admin/faults/presets`
+- `GET /__admin/ui`
+
+For HTTP services, use `x-mockingbird-namespace` (or the documented credential/path carrier) so
+parallel tests do not share state. Admin state, journal, metrics and fault-preset endpoints are
+designed for assertions and diagnosis by consuming test suites.
+
+## Report a mismatch or missing capability
+
+Follow the [agent reporting contract](https://github.com/crvouga/mockingbird/blob/main/docs/REPORTING_ISSUES.md). Include package version,
+operation/command, a minimal redacted request, actual mock result, expected oracle result or vendor
+documentation, and whether the mismatch appears in the matrix. Never include keys, tokens,
+customer data, prompts, PHI, card data, or unredacted recordings.
+
+Service key: `recaptcha`.

package/README.md

@@ -0,0 +1,67 @@
+# @crvouga/mockingbird-service-recaptcha
+
+> Familiar calls. Faithful echoes. Part of [Mockingbird](https://github.com/crvouga/mockingbird).
+
+A WIP reCAPTCHA v3 mock: browser `grecaptcha.ready`/`execute`, deterministic single-use tokens,
+and form-encoded Siteverify. The contract follows Google's [verification](https://developers.google.com/recaptcha/docs/verify)
+and [v3](https://developers.google.com/recaptcha/docs/v3) references. It does not contact Google.
+
+## Install
+
+```sh
+bun add @crvouga/mockingbird-service-recaptcha
+```
+
+## Usage
+
+```ts
+import { createRuntime } from "@crvouga/mockingbird-service-recaptcha"
+
+const runtime = createRuntime()
+const issued = await runtime.fetch(new Request("http://mock.test/__admin/issue", {
+  method: "POST",
+  headers: { "content-type": "application/json" },
+  body: JSON.stringify({ siteKey: "mock_site", action: "login", hostname: "app.example" }),
+}))
+const { token } = await issued.json()
+const verified = await runtime.fetch(new Request("http://mock.test/recaptcha/api/siteverify", {
+  method: "POST",
+  body: new URLSearchParams({ secret: "mock_secret", response: token }),
+}))
+```
+
+For HTTP, use `createServer` from the `/server` entry or `mockingbird-recaptcha serve`.
+Override the browser script URL to `/recaptcha/api.js?render=mock_site` and the server
+verification URL to `/recaptcha/api/siteverify` on the local origin. The browser shim
+uses a local `/__admin/issue` request to obtain tokens; an admin-key-protected runtime
+requires tokens to be provisioned by the test harness. No admin key is embedded in script.
+
+Tokens bind a site key, hostname, action, score, and issue time. Verification consumes
+them once and expires them after two minutes. A low score is still a successful vendor
+verification: the application checks its score threshold, expected action, and hostname.
+
+`PUT /__admin/settings` accepts `sites`, `score`, per-action `scores`, response `action`/
+`hostname` overrides, `executeError`, `expired`, `replayed`, and `errorCodes`.
+`GET /__admin/attempts` returns only time/result/error metadata, without tokens or secrets.
+Shared admin routes provide clock control, reset, Timeline history, namespaces, and faults.
+Namespace selection uses `x-mockingbird-namespace` or `/__admin/ns/<name>/…`.
+Custom `adminPrefix` relocates issuance and the shim's local target together.
+
+Presets: `human`, `bot`, `threshold_boundary`, `expired`, `replayed`, `script_failure`,
+`rate_limited`, and `server_error`. Pass `count: 1` for a one-shot failure. Generic faults
+also support deterministic latency and connection drops. No webhook or pagination exists
+in this vendor surface.
+
+## API
+
+The main entry exports `RecaptchaAPI`, `RecaptchaState`, `createRuntime`,
+`RECAPTCHA_NAMESPACE`, `RECAPTCHA_PRESETS`, `DEFAULT_SETTINGS`, `document`,
+`operationIds`, and `supportedOperationIds`, plus public types.
+The `/server` entry exports `createServer`, `serveTarget`, and `DEFAULT_PORT`.
+
+## Deliberately not modelled
+
+- Google's risk model, device fingerprinting, interactive v2 challenges, or Enterprise API.
+- The private Geviti client's implementation: acceptance uses the documented Google flow.
+- Live successful challenges. The cold parity command probes only missing-response rejection
+  and exits 2 without `RECAPTCHA_SECRET_KEY`; never use production credentials in fixtures.

package/SUPPORT.md

@@ -0,0 +1,12 @@
+# reCAPTCHA v3 — operation support
+
+Generated from `openapi.yaml`; do not edit by hand.
+
+- operations in spec: **2**
+- supported by the mock: **2**
+- parity enabled: **1**
+
+| operationId | route | mock | parity | notes |
+| --- | --- | --- | --- | --- |
+| `BrowserScript` | `GET /recaptcha/api.js` | ✅ supported | ❌ disabled | Semantic shim |
+| `Siteverify` | `POST /recaptcha/api/siteverify` | ✅ supported | ✅ |  |