# @codenhub/oidc

> OidcKit: OpenID Connect for both sides on the Fetch API and Web Crypto, built on @codenhub/jwt. A relying-party client (discover, createClient, authorize, callback, refresh, userinfo, revoke, clientCredentials, endSessionUrl) and an OpenID Provider (createProvider, handle, beginAuthorization, completeAuthorization, endSession), for untrusted input that returns results instead of throwing. Runs on Node.js 24 or newer, browsers and edge runtimes. The package is experimental.

Entrypoints: `@codenhub/oidc/client` exports `discover` and `createClient`; `@codenhub/oidc/provider` exports `createProvider`, `generateClientSecret` and `hashClientSecret`; `@codenhub/oidc/testing` exports `createMemoryStore`, which is for tests only, and `storeConformanceCases`, which checks a store adapter against the contract, seeding the clients a case needs through the factory; the root exports types only. Every result-returning operation on untrusted input (`discover`, `callback`, `refresh`, `userinfo`, `revoke`, `clientCredentials`, `beginAuthorization`, `completeAuthorization`, `endSession` and the other calls that return a result) returns `{ ok: true, value } | { ok: false, error: { issues } }`, where each issue has a stable `code`, an optional `path` and optional `params`, and never holds an input value. `handle` is not one of these: it answers with a `Response`, including OAuth error responses, or `null`. Invalid options and programmer errors throw `TypeError`, or reject for methods that are async. Users sign in through the authorization code flow with PKCE `S256` only, with exact redirect URI matching; clients registered for it get tokens of their own through `client_credentials`; access tokens are opaque, or RFC 9068 JWTs when the provider's `accessToken` option asks for them; the provider's ID tokens are signed by the first of `signingKeys`, and the client accepts only the asymmetric algorithms the provider advertises. `handle(request)` answers discovery, JWKS, token, userinfo and revocation and returns `null` for anything else, including the authorization endpoint, which the app serves and passes to `beginAuthorization`, then `completeAuthorization` with the user's outcome, and the end-session endpoint, which the app serves and passes to `endSession` before ending its own session. The app implements `OidcStore`, whose consume methods must be atomic. Install with `@codenhub/jwt` as a peer dependency, and use one copy of it.

## Documentation

- [Documentation overview](docs/index.md): what the code flow is, which entrypoint to import, the result shape, and a full sign-in walkthrough.
- [Client](docs/client.md): discovery, every `createClient` option, starting and finishing a sign-in, refresh, userinfo, revoking tokens, client credentials, ending the session at the provider, and client authentication methods.
- [Provider](docs/provider.md): every `createProvider` option, routing, the authorization step, the token endpoint and client credentials, JWT access tokens, userinfo, the revocation endpoint, ending sessions, and published metadata.
- [Store](docs/store.md): the `OidcStore` contract method by method, its atomicity requirement, the in-memory reference, and the conformance suite for adapters.
- [Hostile input](docs/security.md): what each kind of hostile input gets from each side, every limit, and what the package does not defend.
- [Issues](docs/errors.md): every issue code with its path and params, what the app does with each client issue, and which mistakes throw instead.
