Touchstone
A conformance test harness for servers that implement the W3C Linked Web Storage (LWS) protocol.
Touchstone checks whether a server implements the W3C Linked Web Storage protocol correctly. It acts as the client. It sends HTTP requests to the server under test, checks each response against what the specification requires, and reports the result one requirement at a time.
A touchstone is the dark stone assayers once used to test gold against a known standard.
What it does
- Tests against the specification’s own text. Every normative clause (MUST, SHOULD or MAY) in the LWS drafts is in a requirements catalog. Each clause has a stable IRI and a hash that detects when the draft changes. Every test names the requirements it verifies.
- Tests are data. A test is a short YAML-LD definition: one request or a flow of steps, with declarative expectations on status codes, headers, links, challenges, JSON and JWTs. No test code is written in Java. The format mirrors and extends the LWS test group’s own JSON-LD suite, and exports to it without loss.
- Owns the identity providers. To check that a server rejects bad credentials, Touchstone mints its own: access tokens with one defect each, CID credentials for HTTPS and did:key subjects, ID Tokens from its own OpenID Provider, and signed SAML assertions. See authentication suites.
- Reports in standard formats. Each run writes W3C EARL for implementation reports, plus HTML, Markdown, PDF, JSON and JUnit XML. See reports and verdicts.
- One engine, three front ends. The same engine runs behind a command-line tool, a Docker image and GitHub Action for CI, and an MCP server. The MCP server lets an AI agent start runs, read failures and iterate on a server implementation, or drive a client through a session.
Where to start
| If you want to… | Read |
|---|---|
| Try Touchstone in five minutes against the bundled reference server | Getting started |
| Test your LWS client, from a browser or from its own CI | Testing a client |
| Test your own LWS server | Targets and credentials, then Command line |
| Run the suite against every known LWS server implementation | Every known LWS server |
| Get a conformance report on every push to your server’s repository | Distribution |
| Let an AI agent run the suite and fix your server | MCP server |
| Let an AI agent drive your client and fix it | Developing a client with an agent |
| Understand how Touchstone tests servers and clients, and what a result claims | Methodology |
| Understand how a run works | How it works |
| Write or review tests | Writing tests and Requirements catalog |
| Understand the YAML-LD test format, and how it relates to the LWS test group’s suite | YAML-LD definitions |
Status
As of October 2026:
- Implemented: the engine, the reporting, the reference servers, the CLI, the MCP server, the Docker image and the GitHub Action.
- Client testing: a service that tests LWS clients against sessions of their own, judged by 53 client rules, with EARL, JUnit XML and JSON reports, a proxy mode in front of a real server, and MCP tools for a coding agent. A client’s developers can also write a small adapter, from a starter kit in their language, and let Touchstone drive the client through a session unattended (
touchstone drive), or let an agent drive it through the MCP server run locally. See Testing a client and Developing a client with an agent. - Requirements catalog: 321 requirements (253 MUST, 29 SHOULD, 39 MAY) from the four current LWS 1.0 documents (the core protocol and the OpenID Connect, SAML 2.0 and Controlled Identifier authentication suites) and the editor’s drafts of the webhook notification suite and the search and type index services.
- Tests: 219 YAML-LD definitions (180 MUST, 28 SHOULD, 11 MAY), format 0.16.0, frozen. They follow the 9 November 2026 Working Draft and the editor’s drafts of the webhook notification suite and the search and type index services, cover all 27 tests of the LWS test group’s
lws-test-suite, and cover 243 of the 272 catalogued requirements that bind a server or an authorization server. Runtouchstone coveragefor the current figures. - Authentication: the access-token negative matrix, RFC 8693 token exchange, access grants, and the OpenID Connect, CID (HTTPS and did:key subjects) and SAML suites all run end to end. Against the reference deployment, 216 of the 219 definitions pass; the other three are inapplicable to it: the single-page pagination test, since the reference splits that container into pages, and two move tests for a storage that moves less than it does.
- Target servers: the seven LWS server implementations Touchstone is run against (Halcyon, lws-server, sparq-lws-core, the Community Solid Server, lws-drupal, lwsd and Factoidal), each built from source into a container. One script builds and tests them all on one machine with nothing but Docker, and another tests every lws-client library against every one of them; see Every known LWS server.
- Catalog baseline: the catalog and the definitions follow the drafts W3C published as of 9 November 2026: the 9 November core and SAML Working Drafts and the 15 October OpenID Connect and CID ones. A weekly CI job fails when W3C publishes a newer version (see Requirements catalog). The did:key suite, which W3C discontinued on 29 September 2026 in favour of the CID suite, is retired (D-0058).
LWS is a Working Draft and changes often. Touchstone tracks it deliberately: each catalog entry records the dated draft it was taken from. The drift check tells you when that draft has moved on.