# OAuth and OpenID Connect Clients and APIs in Node.js

`oauth/oidc-client` · Skill · v1.0.0

Secure OIDC sign-in, JWT access token validation and rotating refresh tokens in Node.js with openid-client 6, jose 6 and oauth4webapi 3.

Teaches an agent current OAuth 2.x and OpenID Connect practice for Node.js and TypeScript, checked against openid-client 6.8.8, jose 6.2.14 and oauth4webapi 3.8.8 and the OAuth Security BCP (RFC 9700). It covers what agents trained on openid-client v5 and hand-rolled JWT code get wrong: the v6 functional API (no Issuer, Client or generators), the async PKCE challenge, exact expectedState/expectedNonce semantics, the redirect_uri openid-client derives from the callback URL (and why it breaks behind a TLS proxy), RFC 9207 iss checks, the ID token checks openid-client performs and the signature check it skips by default, single-use login state and session regeneration, JWT access token validation with jose (RFC 9068 typ, issuer, audience, pinned algorithms, exp only checked when required, JWKS from discovery with rotation, RFC 6750 errors), and refresh token rotation with reuse detection: storing the rotated token, one refresh in flight per session, and telling invalid_grant apart from outages.

## Verdict

- level: **submitted** — In the catalog, not yet checked for this digest.
- uplift: **untested** — No runs exist for this digest.
- digest: `sha256:6ae4521aac569ac284203e2ba3f54ef549a41b2666ea9e7b018160ab45078df9`

## Uplift runs

None for this digest. Untested is not the same as useless: nobody has measured it yet.

## Security

No checks recorded for this digest.

## Compatibility

| agent | targeted | compiled | evaluated |
| --- | --- | --- | --- |
| Claude Code | yes | no record | no record |
| Codex | yes | no record | no record |
| Cursor | yes | no record | no record |
| GitHub Copilot | yes | no record | no record |
| Gemini CLI | yes | no record | no record |
| OpenCode | yes | no record | no record |

## Permissions

- network: none
- shell: node, npm ls, npm test, npx tsc
- filesystem: write
- env: none

## Files

- `SKILL.md` 17966 B sha256:7662b0ba47ee400cd08dd72bd1b586914467179dafc90843c6cf2c9857bf3a77
- `references/openid-client-v6.md` 9468 B sha256:f39807190268ee9a72cff07e91989a94dc550411354847b54171c3c919865932
- `references/resource-server.md` 8493 B sha256:9fd3930ac9e653e70906808ff3ce2ee3549ba291036064d606bbc8c78aa5f016
- `references/sources.md` 6284 B sha256:79b23d06624a2ad1eeb4a2f9a8d241277a49d11498edae191cf89f9ddbdb65bb
- `references/token-lifecycle.md` 6759 B sha256:2af2ec1f6e9b7e4c926a808dd281f2c6c3cab1b3e9de84e984fa91b486b7aa0a

## Limitations

- Written and verified against openid-client 6.8.8, jose 6.2.14 and oauth4webapi 3.8.8 on Node 24. openid-client v5 is covered only as a migration map.
- Provider-specific behaviour (Auth0, Okta, Entra ID, Keycloak, Cognito) is not covered, such as whether access tokens carry typ at+jwt, scope versus scp, or refresh token grace periods.
- The single-flight refresh pattern shown is per process; multi-instance deployments are described (sticky sessions, distributed locks) but not tested by the proof suite.
- Browser-only clients (SPAs without a backend), native apps, DPoP, PAR, JAR and FAPI profiles are mentioned, not taught in depth.
- The proof suite uses a local test IdP over plain HTTP with allowInsecureRequests enabled by configuration; TLS and certificate handling are out of scope.

## Install

```sh
npx sigil add oauth/oidc-client --agent claude-code,codex,cursor
```

Source: https://github.com/dgesteves/sigil/tree/5cb851d5b2f2f14446ddf631ef5e91bf9d3263dd/catalog/skills/oauth/oidc-client