Implementations¶
A specification with one implementation is a description of that implementation. The bar for taking a spec seriously is two independent implementations that pass the same conformance suite — because that is what demonstrates the document is complete enough for someone to build from, rather than a write-up of whatever the first codebase happened to do.
PPX v0.1 has two.
| Reference provider | PHP provider | |
|---|---|---|
| Language | Python | PHP 8.1 |
| Stack | FastAPI + PostgreSQL + Keycloak + Next.js | Front-controller PHP + SQLite |
| Identity | Keycloak (OIDC) | Self-issued RS256 grant tokens |
| Dependencies | Docker Compose, 4 services | None beyond stock PHP (openssl, pdo_sqlite, json) |
| Runs on | A machine you administer | Commodity shared hosting |
| Conformance | Run locally via scripts/run_conformance.sh; no public deployment to measure |
12/30 unauthenticated over public HTTPS; see below — the suite predates consent-v2 |
Both were written against the specification and both are checked by the same conformance suite. Neither shares a line of code with the other.
What those numbers mean¶
The suite is 39 tests, covering the consent-v2 protocol: PKCE (S256, with
plain refused), the back-channel request token, single-use authorization,
client binding, refresh-token rotation with reuse detection, and the
HTTP binding's profile-read routes.
| How you run it | Result |
|---|---|
pytest -m schema — no provider needed |
7 passed, 29 deselected |
| Against a live provider, no credentials | 12 passed, 27 skipped, 0 failed |
| Against a live provider, with minted tokens | 39 passed, 0 skipped, 0 failed |
The skips are not failures — they are the authenticated tests, which cannot run
without tokens. A provider claiming full conformance must supply them: the
suite needs an access token plus purpose-built tokens for the expired-grant,
revocation, cross-domain-denial and forbidden-writeback cases. The PHP provider
mints all of them with php bin/mint.php env.
Reproduce the 39/39 (measured 2026-08-05 against https://ppx.dev/ppx):
php bin/mint.php env > /tmp/ppx.env # on the provider host
set -a; . /tmp/ppx.env; set +a
pytest -q # 39 passed
Each run consumes its revocable grant, so re-run against freshly minted tokens.
What the second implementation established¶
The PHP provider was written to answer a narrow question — can a conforming provider run on ordinary shared hosting? — and it settled three broader ones.
The spec does not require a heavyweight stack. The reference provider needs four services and a machine to run them on. That is a property of the reference provider, not of PPX. The normative auth surface is one hard requirement — an expired grant MUST NOT authorize new access — plus "OAuth 2.1 or equivalent" and a bearer token. Keycloak is one way to satisfy that, not the way.
The spec is implementable from the document alone. Every endpoint, status
code, and payload shape in the PHP provider was derived from SPEC.md, the
HTTP binding, and the eleven schemas. Where the specification was precise, the
implementation followed it directly; the conformance suite then confirmed the
result interoperates.
The floor is lower than it looked. The whole provider is a few hundred lines of dependency-free PHP over a file-backed database. If that is the cost of entry, a provider is something an application can add, not a system it has to adopt.
Conformance results¶
The suite is the same one in this repository, run over public HTTPS against the deployed PHP provider:
with no skipped tests. That covers discovery-card validity, deny-by-default for
unauthenticated and invalid tokens, expired-grant rejection, scope redaction,
revocation taking effect, cross-domain denial, write-back proposals under
review_required, refusal under forbidden, and the schema round-trips.
What conformance does and does not mean
Passing L1 means a provider answers correctly on the behaviours the suite
exercises. It is not a security audit, and it is not a claim that either
implementation is production-ready. PPX is v0.1.0-draft; both providers
serve demonstration data only.
Writing a third¶
That is the useful next step, and the spec is more likely to improve from it than from more work on either existing provider.
Start with the HTTP binding, serve a discovery card, then run:
git clone https://github.com/Blazing-Customs/ppx-spec
pip install -e ppx-spec/conformance
PPX_PROVIDER_URL=https://your-provider.example pytest ppx-spec/conformance
The provider-backed tests need grant-scoped tokens supplied through the
environment; conformance/README.md lists them. If something in the
specification is ambiguous enough that you had to guess, that is a spec bug —
please open an issue.