backend-validation

name

backend-validation

description

Use this skill when validating a backend API or WebSocket endpoint end-to-end, including acquiring an OIDC bearer token for authenticated calls. Trigger whenever the user asks to test/validate/smoke-check a backend, write a Hurl test, hit a WebSocket, acquire an access token, exercise an OIDC flow, debug a 401, or verify an endpoint works with real auth. Applies to projects that use Hurl for HTTP tests, websocat for WebSocket probes, and oauth2c or curl-based flows for token acquisition (Authentik, Keycloak, Okta, Auth0, any RFC 6749 / OIDC Core provider). Prefer this skill over ad-hoc curl + bash when the user has more than one endpoint to check, chained auth flows, or anything resembling a regression test — because the Hurl + cached-refresh-token pattern is 10× less code and survives the next session.

Backend Validation

For CLI-driven validation of backends behind OIDC auth. Deliberately tool-specific — Hurl, websocat, oauth2c. If the project has already picked Bruno/Postman/Insomnia, stop and use those instead; don't fork the tooling.

Framing before you test

Before picking flags and writing assertions, work the change as a thinking exercise — the tools come after.

1. What feature does this change represent? State it as a user-visible effect, not a function signature. If you can't state it that way, you don't yet know what to validate.
2. What does success look like? Be concrete — "a new session appears with status 'active' within 2s" beats "it works." Vague success criteria produce vague tests.
3. Validate in two passes. User-lens: drive the feature as a user would (for backend, that often means exercising the endpoints the UI calls, in the order and shape the UI sends them). System-lens: verify the system did the right thing underneath — status codes, DB rows, WS events, logs clean. Bugs hide in exactly one of these; running both catches them.
4. Check 2–3 adjacent paths. A /sessions POST probably affects the /sessions/mine listing, any subscribed realtime channel, caches. Don't attempt full regression — pick nearby behaviors that would obviously break.
5. Cover realistic failure modes (missing auth, invalid body, not-found, race on a shared resource), not exhaustive ones. One test per failure class beats ten happy-path tests.
6. Skip what can't plausibly break from this change. Judgment, not ritual.

When in doubt, run --help

Flags drift between tool versions and training data. For anything beyond the common invocations below — reconnect behavior, mTLS, a subprotocol you haven't used, a new oauth2c flag — run hurl --help, websocat --help, or oauth2c --help first rather than guessing. One --help call is cheaper than a debug session chasing a flag that changed meaning.

The stack

The tools are committed: Hurl for HTTP tests, websocat for WebSocket probes, oauth2c for OIDC token flows. All three are cross-platform (Rust/Go binaries). The only OS-specific surface is how the refresh token is cached:

• macOS: security add-generic-password / security find-generic-password (macOS Keychain)
• Linux: secret-tool (libsecret / GNOME Keyring) — install with apt install libsecret-tools or equivalent
• Windows: cmdkey + PowerShell's CredentialManager module, or WSL users reuse the Linux path

The reference script (references/token-script.sh) uses the macOS security command directly. On Linux/Windows, swap those two calls for the platform equivalent; the auth flow itself is identical.

The three orthogonal concerns

Keep these separate in your head and in the code:

1. Token acquisition — auth-code + PKCE with the refresh token cached in OS-native secret storage (see above). No passwords in env files, no ROPC against public clients (it fails — see below).
2. HTTP validation — .hurl files with [Captures] for chaining auth into calls and [Asserts] for pass/fail.
3. WebSocket probes — websocat one-shots with Authorization: Bearer header; scripted with -n1, interactive without.

Decision tree

Situation	Reach for
"Does this endpoint work with auth?"	oauth2c for token, then hurl or xh
"Is the WebSocket responding?"	websocat with bearer header
"Write tests for this API"	.hurl files with [Captures] + [Asserts]
Debugging a 401	Decode JWT claims; check iss, aud, exp, email_verified

The auth-code + PKCE pattern (why and how)

Public PKCE clients — which most SPAs and mobile apps use at runtime — refuse ROPC (password grant). Don't waste cycles trying grant_type=password: Authentik and most IdPs return invalid_grant regardless of whether credentials are right, identical error for every failure mode.

The pattern that works: authorization-code + PKCE for the initial browser login, then a cached refresh_token for silent renewals. Oauth2c handles the browser dance; the resulting refresh_token lives in OS secret storage (service name <project>-refresh-token) and gets rotated on each use.

Non-obvious flags:

• --prompt login on oauth2c forces a fresh sign-in prompt. Without it, an already-logged-in admin session in the browser gets used — the cached token ends up being for the wrong identity. This bit me once and will bite again without the flag.
• --login-hint <username> pre-fills the username field, useful when multiple accounts exist.
• offline_access scope is required to receive a refresh_token at all.
• Redirect URI — the OIDC provider must whitelist http://localhost:9876/callback (oauth2c's default) in Strict mode.
• email_verified: true must be set on the test user's attributes in the IdP. Many backends reject JWTs where this claim is false. In Authentik: Directory → Users → Attributes → email_verified: true (plain YAML, not wrapped in brackets — that's a list).

A full reference script lives in references/token-script.sh.

Hurl patterns

One file per scenario (smoke.hurl, sessions-crud.hurl). Parameterize base_url and token as --variable so the same file runs anywhere. [Captures] chains response values into later requests; [Asserts] defines pass/fail.

GET {{base_url}}/api/me
Authorization: Bearer {{token}}
HTTP 200
[Asserts]
jsonpath "$.id" isString

Run: hurl --test --variable token=$TOKEN --variable base_url=$BASE_URL *.hurl.

See references/hurl-patterns.md for captures chaining, retries, GraphQL, parallel runs, CI output.

WebSocket patterns

The one thing that's non-obvious: headers go via -H, which is how you pass the bearer. Everything else is either in websocat --help or references/websocat-patterns.md.

echo '{"op":"ping"}' | websocat -n1 -H "Authorization: Bearer $TOKEN" ws://.../endpoint

For subprotocols (graphql-transport-ws), mTLS (use wscat instead), auto-reconnect, ping/pong: see the reference.

When NOT to use this skill

• Project uses Bruno/Postman/newman/Insomnia — use those.
• Backend has no auth — plain curl or xh is enough.
• UI validation — use Playwright MCP or an in-house browser tool.
• CI secret storage — keychain is developer-machine-only; CI needs a secret manager.

References

• references/token-script.sh — complete bash script for token acquisition + refresh caching
• references/hurl-patterns.md — captures, assertions, retries, GraphQL, parallel, CI
• references/websocat-patterns.md — subprotocols, mTLS, reconnect, debugging
• references/oidc-token-flows.md — grant-type comparison, 401 debugging, discovery endpoint