$ show keycloakify/oidc-spa
oidc-spa is a production-grade OpenID Connect (OIDC) client library designed for browser-first single-page applications. It implements the Authorization Code + PKCE flow with security-first defaults including in-memory token storage, DPoP (Demonstration of Proof-of-Possession) support, token substitution to prevent token leakage, and browser runtime freezing to resist monkey-patching attacks. The library provides framework-specific adapters for React, Angular, Next.js, Nuxt, TanStack Start, and React Router, each offering hooks, guards, and middleware for seamless authentication integration. It also includes a Vite plugin for build-time injection, a mock OIDC adapter for testing, and server-side utilities for access token validation (RFC 9068). The core is framework-agnostic, with a custom reactive event system (Evt) for state management and cross-tab synchronization via BroadcastChannel. The repository contains extensive example applications demonstrating login/logout, protected routes, role-based access, and auto-logout overlays across multiple frameworks.
The LLM identified 3 files worth highlighting for reuse:
A custom, lightweight reactive event system that provides observable state with methods like `attach`, `detach`, `pipe`, and `state`. It is self-contained (no external dependencies) and can be extracted for use in any TypeScript project requiring fine-grained event-driven state management. Demonstrates non-obvious skill in implementing a type-safe, memory-efficient event emitter with support for derived state and cleanup.
Generates a DPoP proof JWT using the ES256 algorithm via the Web Crypto API. It creates a new ECDSA key pair, signs a token with required claims (jti, htm, htu, iat), and returns the proof as a compact JWT. This module is fully self-contained, uses only standard browser APIs, and can be reused in any OAuth2 client that needs DPoP support. Demonstrates deep understanding of the DPoP specification and cryptographic best practices.
Provides a mock OIDC client factory that simulates authentication without a real provider. It returns an object conforming to the Oidc interface, allowing developers to test protected routes, token refresh, and logout flows in isolation. The mock is configurable (e.g., custom tokens, user info) and can be injected via the framework adapters. This is a highly reusable pattern for any authentication library that needs a test double, and it is decoupled from the rest of the codebase.