@openchildsafety/provider-harness

Independent OCSS conformance harness. A verifying-agency — the reference one is named Touchstone (did:ocss:touchstone) — runs it against a provider enclave, then signs the resulting conformance_attestation with its own Ed25519 key. This project is the tooling; Touchstone is the agency that runs it, and is intentionally independent of Phosra (the CA model: a verifier cannot accredit a service it operates). The OCSS crypto it uses (JCS canon + Ed25519 + the closed vocab) is inlined under src/crypto/ behind the single src/crypto-adapter.ts seam, so the package has zero runtime dependencies; a dev-only parity test keeps the inlined copies byte-identical to the OCSS reference implementation (@openchildsafety/ocss).

Assertions

• A1 closed-enum fail-closed · A2 content-free signal lane · A5 minimization attestation (salted-HMAC Merkle) · A7 attestation-fail → suspend — passable today.
• A3 / A4 / A6 — declared pending (consent infra / capability endpoint / advocate lane).

Install

npm install @openchildsafety/provider-harness
npx provider-harness run --enclave ref                 # probe the bundled reference enclave
npx provider-harness run --enclave-url https://enclave.example.com   # probe a REAL enclave (live-target)

CLI name

The canonical bin is provider-harness. ocss-harness is kept as a back-compat alias (both resolve to the same entrypoint), reconciling the name Phosra's accreditation docs use (npx -p @openchildsafety/provider-harness provider-harness) with the published package.

Target modes

• --enclave ref (default) — the bundled reference enclave; makes A1/A2/A5/A7 pass. Used to self-test the harness and demo the report.

• --enclave-url <https url> — the live-target mode: run the same A1–A7 suite against a real provider enclave over HTTP. This is the independent-assessor tool of OCSS §5.9 ("the verifier tool" that ship-gates v1.0), operated under the open assessor market of §5.4 — the harness aims at a provider's own endpoint, not a mock it also authored. HTTPS is required for any non-loopback host; plain http is tolerated only for localhost/127.0.0.1 (local fixtures).

  The target enclave MUST implement:

  GET  {url}/buildinfo  -> { "build_hash": string, "suite_version": string }
  POST {url}/classify   (JSON ClassifyInput + { "upstream_attestation": <state> })
                        -> ClassifyOutput  ({ "kind": "signal" | "rejected" | "suspended", ... })

Develop (from a clone)

npm install
npx vitest run                              # full test suite
npm run harness -- run    --enclave ref     # probe + report (bin: provider-harness / ocss-harness)
npm run harness -- attest --enclave ref --attested-by did:ocss:va \
  --liability-scope-ref https://ocss.example/liability#v0 --passed-at 2026-06-30T00:00:00Z > att.json
npm run harness -- sign   --key va.pem --key-id va-2026-06 att.json > signed.json
npm run harness -- verify --trust-list trust-list.json --root-x <rootKeyX> signed.json

v0 scope & limitations

• The reference enclave emits a structural/mock OCSS envelope (a plain object), not yet produced via @ocss/ts seal/signSender; A2 inspects structure rather than calling @ocss/ts validate/open.
• verify checks attestations against the harness's own fixture Trust-List shape ({document, sig, key_id} with a role field on entries), NOT yet the live @ocss/ts SignedDocument/Entry wire form — because the verifying-agency role does not exist in the OCSS census yet, so there is no real VA Trust-List entry to test against.
• Real-Trust-List and real-envelope interop are deliberate follow-on work.

Refreshing the vendored crypto

scripts/refresh-ocss-ts.sh re-packs @ocss/ts from the monorepo when its crypto changes.