@eventuras/fides-auth 0.3.1 → 0.5.0

package/README.md

@@ -5,6 +5,7 @@ Framework-agnostic OAuth 2.0 / OpenID Connect library with PKCE, encrypted sessi
 ## Features
 
 - **OAuth 2.0 + OIDC** — Authorization Code with PKCE, token refresh, client credentials
+- **Pushed Authorization Requests** — Opt-in RFC 9126 support (`usePar`) when the provider advertises it
 - **Dual environment** — Node.js (`openid-client`) and browser (Web Crypto) entry points
 - **Encrypted sessions** — AES-256-GCM encrypted JWTs for secure session storage
 - **Rate limiting** — Generic token-bucket algorithm, ready for login protection
@@ -123,6 +124,8 @@ Full OIDC flows using `openid-client`:
 import {
   buildPKCEOptions,
   buildAuthorizationUrl,
+  buildAuthorizationUrlWithPAR,
+  discoverAndBuildAuthorizationUrl,
   exchangeAuthorizationCode,
   refreshAccessToken,
   extractUserFromTokens,
@@ -133,6 +136,43 @@ import {
 } from "@eventuras/fides-auth/oauth";
 ```
 
+#### Pushed Authorization Requests (PAR, RFC 9126)
+
+Opt in by setting `usePar: true` on your `OAuthConfig`. The convenience
+helper `discoverAndBuildAuthorizationUrl` then posts the authorization
+parameters to the provider's PAR endpoint and returns a URL containing
+only `client_id` and `request_uri`:
+
+```typescript
+const oauthConfig = {
+  issuer: "https://auth.example.com",
+  clientId: "your-client-id",
+  clientSecret: "your-client-secret",
+  redirect_uri: "https://app.example.com/callback",
+  scope: "openid profile email offline_access",
+  usePar: true,
+};
+
+const pkce = await buildPKCEOptions(oauthConfig);
+const authUrl = await discoverAndBuildAuthorizationUrl(oauthConfig, pkce);
+// redirect user to authUrl
+```
+
+Behaviour:
+
+- `usePar: true` + provider advertises `pushed_authorization_request_endpoint` → uses PAR.
+- `usePar: true` + provider does **not** advertise PAR → throws.
+- `usePar` unset/false + provider advertises PAR → standard flow, with a
+  one-line `info` log noting that PAR is available but not enabled.
+- `usePar` unset/false + no PAR endpoint → standard flow, no advisory.
+
+If you already have a discovered `Configuration` you can call the
+low-level wrapper directly:
+
+```typescript
+const authUrl = await buildAuthorizationUrlWithPAR(config, pkce);
+```
+
 ### OAuth — Browser (`/oauth-browser`)
 
 Lightweight browser-only flows using Web Crypto:
@@ -231,15 +271,22 @@ import {
 
 ### Pluggable Logging (`/logger`)
 
-The library uses console logging by default. Plug in your preferred logger at startup:
+The library writes newline-delimited JSON to `console.<level>` by default — interoperable with Loki, Grafana, Datadog, and other log shippers without any setup. Plug in a richer logger at startup if you want OpenTelemetry, redaction, or shared formatting with the rest of your app:
 
 ```typescript
 import { configureLogger } from "@eventuras/fides-auth/logger";
 
-// Example: plug in pino
+// Example: plug in @eventuras/logger
+import { Logger } from "@eventuras/logger";
+configureLogger({
+  create(options) {
+    return Logger.create(options);
+  },
+});
+
+// Or plug in pino directly
 import pino from "pino";
 const pinoInstance = pino();
-
 configureLogger({
   create({ namespace, context }) {
     return pinoInstance.child({ namespace, ...context });
@@ -249,6 +296,12 @@ configureLogger({
 
 Any object implementing `{ debug, info, warn, error }` works — pino, winston, bunyan, or your own.
 
+The default JSONL output looks like:
+
+```json
+{"level":"info","time":"2026-04-15T19:40:57.300Z","namespace":"fides-auth:oauth","msg":"PKCE parameters generated"}
+```
+
 ### Vipps Login Provider (`/providers/vipps`)
 
 ```typescript