@eventuras/fides-auth 0.8.0 → 0.11.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 losol
+Copyright (c) 2024 Losol AS
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -9,6 +9,7 @@ Framework-agnostic OAuth 2.0 / OpenID Connect library with PKCE, encrypted sessi
 - **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
+- **RP-initiated logout** — End the provider's session too, with `id_token_hint` (OIDC RP-Initiated Logout 1.0)
 - **Silent login** — Detect `prompt=none` results without user interaction
 - **Pluggable logging** — Bring your own logger (pino, winston, etc.) or use the built-in console logger
 - **Tree-shakeable** — Each module is a separate entry point; import only what you need
@@ -114,6 +115,7 @@ Each module is available as a separate entry point for tree-shaking:
 | `@eventuras/fides-auth/rate-limit`         | Universal   | Token-bucket rate limiter                             |
 | `@eventuras/fides-auth/logger`             | Universal   | Pluggable logger interface and configuration          |
 | `@eventuras/fides-auth/types`              | Universal   | TypeScript types (Session, Tokens, etc.)              |
+| `@eventuras/fides-auth/server`             | Node.js     | Request handlers (login, callback, logout, heartbeat) |
 | `@eventuras/fides-auth/providers/vipps`    | Node.js     | Vipps Login identity provider                         |
 
 ### OAuth — Node.js (`/oauth`)
@@ -173,6 +175,36 @@ low-level wrapper directly:
 const authUrl = await buildAuthorizationUrlWithPAR(config, pkce);
 ```
 
+#### RP-Initiated Logout
+
+Clearing your own session cookie is not a logout — the provider's session survives,
+so the next `/authorize` re-authenticates silently. `buildOidcLogoutUrl` builds the
+request that ends the provider session too, and returns `null` when the provider
+advertises no `end_session_endpoint`:
+
+```typescript
+const logoutUrl = await buildOidcLogoutUrl(oauthConfig, {
+  postLogoutRedirectUri: "https://app.example.com/",
+  idTokenHint: session?.tokens?.idToken,
+});
+```
+
+The `/server` entry point wraps the whole dance — read the hint, clear the cookies,
+redirect:
+
+```typescript
+import { handleOidcLogout } from "@eventuras/fides-auth/server";
+
+return handleOidcLogout(request, {
+  oauthConfig,
+  cookies,
+  postLogoutRedirectUri: "https://app.example.com/",
+});
+```
+
+See [docs/rp-initiated-logout.md](./docs/rp-initiated-logout.md) for the full
+parameter set, where the ID token is stored, and why `client_id` is still sent.
+
 ### OAuth — Browser (`/oauth-browser`)
 
 Lightweight browser-only flows using Web Crypto:

package/dist/cookies.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Browser per-cookie size limit (RFC 6265: browsers must support at least
+ * 4096 bytes for the sum of the cookie's name and value). Cookies at or above
+ * this size are silently dropped by the browser, which manifests as a broken
+ * login (the cookie is never stored, so the user appears unauthenticated).
+ */
+export declare const COOKIE_MAX_BYTES = 4096;
+/**
+ * Threshold at which an adapter should emit an informational log that a cookie is
+ * getting large. This is not an error — a session with many scopes/roles can
+ * legitimately approach this size — it just gives visibility before the hard limit.
+ */
+export declare const COOKIE_INFO_BYTES = 3500;
+/**
+ * Thrown when a cookie's name + value would meet or exceed the browser's
+ * per-cookie size limit. Setting such a cookie would be silently dropped by the
+ * browser, so adapters should fail loudly instead. Callers (e.g. an OIDC callback)
+ * can catch this to surface a clear error rather than producing a broken login.
+ */
+export declare class CookieTooLargeError extends Error {
+    readonly cookieName: string;
+    readonly size: number;
+    readonly limit: number;
+    constructor(cookieName: string, size: number, limit?: number);
+}
+export interface CookieOptions {
+    /** Cookie path (default: '/') */
+    path?: string;
+    /** Max age in seconds */
+    maxAge?: number;
+    /** SameSite policy (default: 'lax') */
+    sameSite?: 'strict' | 'lax' | 'none';
+    /** HTTP only flag (default: true) */
+    httpOnly?: boolean;
+    /**
+     * Secure flag. `true` in {@link defaultSessionCookieOptions} and
+     * {@link defaultOAuthCookieOptions}; when omitted from a hand-built options
+     * object, the adapter's own default applies.
+     */
+    secure?: boolean;
+}
+/**
+ * Default cookie options for session cookies.
+ * - Secure
+ * - HTTP only
+ * - Lax same-site policy
+ * - 30 days max age
+ *
+ * `secure` is unconditional rather than derived from NODE_ENV: a deployment that
+ * doesn't set it — staging, a container, any non-Next server — would otherwise put
+ * the session cookie on the wire in the clear, silently.
+ *
+ * The cookie spec exempts localhost from the https requirement, so a `Secure`
+ * cookie is still set and sent over `http://localhost` and local development is
+ * unaffected. Plain http on any other host — a LAN address, a custom dev hostname —
+ * needs an explicit `secure: false`.
+ */
+export declare const defaultSessionCookieOptions: CookieOptions;
+/**
+ * Default cookie options for OAuth state/PKCE cookies.
+ * - Secure — see {@link defaultSessionCookieOptions}
+ * - HTTP only
+ * - Lax same-site policy
+ * - 10 minutes max age (short-lived for security)
+ */
+export declare const defaultOAuthCookieOptions: CookieOptions;
+/**
+ * Name of the cookie holding the (split-out) access token.
+ *
+ * The access token — typically a large JWT carrying scopes/roles — is stored in
+ * its own cookie so it gets a full per-cookie byte budget, instead of competing
+ * for space with the rest of the session inside a single "session" cookie. See
+ * {@link CookieTooLargeError} for the limit this works around.
+ */
+export declare const ACCESS_TOKEN_COOKIE_NAME = "session_at";
+/**
+ * Name of the cookie holding the (split-out) ID token, kept for `id_token_hint`
+ * on RP-initiated logout.
+ *
+ * It gets its own cookie for two reasons: it is a second large JWT, which would
+ * eat into the access token's byte budget, and it must outlive access-token
+ * expiry — a logout after the session has gone stale is exactly when the hint is
+ * needed.
+ */
+export declare const ID_TOKEN_COOKIE_NAME = "session_it";
+/**
+ * Name of the main session cookie (everything except the split-out access and ID
+ * tokens). See {@link ACCESS_TOKEN_COOKIE_NAME} for why the raw tokens are stored
+ * apart.
+ */
+export declare const SESSION_COOKIE_NAME = "session";
+/**
+ * Serialized byte size of a `name=value` cookie pair. The browser per-cookie
+ * limit applies to the serialized pair, so the `=` separator is counted too —
+ * otherwise a borderline pair (name+value === 4095) would slip through only to be
+ * dropped at 4096 once serialized.
+ */
+export declare function cookieByteSize(name: string, value: string): number;
+/**
+ * Asserts that a `name=value` cookie pair is within the browser's per-cookie
+ * limit, throwing {@link CookieTooLargeError} if not. Returns the measured byte
+ * size so callers can additionally log when it crosses {@link COOKIE_INFO_BYTES}.
+ */
+export declare function assertCookieWithinLimit(name: string, value: string): number;
+//# sourceMappingURL=cookies.d.ts.map

package/dist/cookies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookies.d.ts","sourceRoot":"","sources":["../src/cookies.ts"],"names":[],"mappings":"AAUA;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAErC;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAEtC;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;aAE1B,UAAU,EAAE,MAAM;aAClB,IAAI,EAAE,MAAM;aACZ,KAAK,EAAE,MAAM;gBAFb,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,KAAK,GAAE,MAAyB;CAOnD;AAED,MAAM,WAAW,aAAa;IAC5B,iCAAiC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yBAAyB;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,QAAQ,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;IACrC,qCAAqC;IACrC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,2BAA2B,EAAE,aAMzC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,EAAE,aAMvC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,eAAe,CAAC;AAErD;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,eAAe,CAAC;AAEjD;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,YAAY,CAAC;AAE7C;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAGlE;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAM3E"}

package/dist/cookies.js

@@ -0,0 +1,118 @@
+//#region src/cookies.ts
+/**
+* Browser per-cookie size limit (RFC 6265: browsers must support at least
+* 4096 bytes for the sum of the cookie's name and value). Cookies at or above
+* this size are silently dropped by the browser, which manifests as a broken
+* login (the cookie is never stored, so the user appears unauthenticated).
+*/
+var COOKIE_MAX_BYTES = 4096;
+/**
+* Threshold at which an adapter should emit an informational log that a cookie is
+* getting large. This is not an error — a session with many scopes/roles can
+* legitimately approach this size — it just gives visibility before the hard limit.
+*/
+var COOKIE_INFO_BYTES = 3500;
+/**
+* Thrown when a cookie's name + value would meet or exceed the browser's
+* per-cookie size limit. Setting such a cookie would be silently dropped by the
+* browser, so adapters should fail loudly instead. Callers (e.g. an OIDC callback)
+* can catch this to surface a clear error rather than producing a broken login.
+*/
+var CookieTooLargeError = class extends Error {
+	cookieName;
+	size;
+	limit;
+	constructor(cookieName, size, limit = COOKIE_MAX_BYTES) {
+		super(`Cookie "${cookieName}" is ${size} bytes, which meets or exceeds the browser limit of ${limit} bytes and would be silently dropped`);
+		this.cookieName = cookieName;
+		this.size = size;
+		this.limit = limit;
+		this.name = "CookieTooLargeError";
+	}
+};
+/**
+* Default cookie options for session cookies.
+* - Secure
+* - HTTP only
+* - Lax same-site policy
+* - 30 days max age
+*
+* `secure` is unconditional rather than derived from NODE_ENV: a deployment that
+* doesn't set it — staging, a container, any non-Next server — would otherwise put
+* the session cookie on the wire in the clear, silently.
+*
+* The cookie spec exempts localhost from the https requirement, so a `Secure`
+* cookie is still set and sent over `http://localhost` and local development is
+* unaffected. Plain http on any other host — a LAN address, a custom dev hostname —
+* needs an explicit `secure: false`.
+*/
+var defaultSessionCookieOptions = {
+	path: "/",
+	maxAge: 2592e3,
+	sameSite: "lax",
+	httpOnly: true,
+	secure: true
+};
+/**
+* Default cookie options for OAuth state/PKCE cookies.
+* - Secure — see {@link defaultSessionCookieOptions}
+* - HTTP only
+* - Lax same-site policy
+* - 10 minutes max age (short-lived for security)
+*/
+var defaultOAuthCookieOptions = {
+	path: "/",
+	maxAge: 600,
+	sameSite: "lax",
+	httpOnly: true,
+	secure: true
+};
+/**
+* Name of the cookie holding the (split-out) access token.
+*
+* The access token — typically a large JWT carrying scopes/roles — is stored in
+* its own cookie so it gets a full per-cookie byte budget, instead of competing
+* for space with the rest of the session inside a single "session" cookie. See
+* {@link CookieTooLargeError} for the limit this works around.
+*/
+var ACCESS_TOKEN_COOKIE_NAME = "session_at";
+/**
+* Name of the cookie holding the (split-out) ID token, kept for `id_token_hint`
+* on RP-initiated logout.
+*
+* It gets its own cookie for two reasons: it is a second large JWT, which would
+* eat into the access token's byte budget, and it must outlive access-token
+* expiry — a logout after the session has gone stale is exactly when the hint is
+* needed.
+*/
+var ID_TOKEN_COOKIE_NAME = "session_it";
+/**
+* Name of the main session cookie (everything except the split-out access and ID
+* tokens). See {@link ACCESS_TOKEN_COOKIE_NAME} for why the raw tokens are stored
+* apart.
+*/
+var SESSION_COOKIE_NAME = "session";
+/**
+* Serialized byte size of a `name=value` cookie pair. The browser per-cookie
+* limit applies to the serialized pair, so the `=` separator is counted too —
+* otherwise a borderline pair (name+value === 4095) would slip through only to be
+* dropped at 4096 once serialized.
+*/
+function cookieByteSize(name, value) {
+	const encoder = new TextEncoder();
+	return encoder.encode(name).length + 1 + encoder.encode(value).length;
+}
+/**
+* Asserts that a `name=value` cookie pair is within the browser's per-cookie
+* limit, throwing {@link CookieTooLargeError} if not. Returns the measured byte
+* size so callers can additionally log when it crosses {@link COOKIE_INFO_BYTES}.
+*/
+function assertCookieWithinLimit(name, value) {
+	const size = cookieByteSize(name, value);
+	if (size >= 4096) throw new CookieTooLargeError(name, size);
+	return size;
+}
+//#endregion
+export { ACCESS_TOKEN_COOKIE_NAME, COOKIE_INFO_BYTES, COOKIE_MAX_BYTES, CookieTooLargeError, ID_TOKEN_COOKIE_NAME, SESSION_COOKIE_NAME, assertCookieWithinLimit, cookieByteSize, defaultOAuthCookieOptions, defaultSessionCookieOptions };
+
+//# sourceMappingURL=cookies.js.map

package/dist/cookies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookies.js","names":[],"sources":["../src/cookies.ts"],"sourcesContent":["// cookies.ts\n//\n// Framework-agnostic cookie attributes, size limits, and the access-token cookie\n// name. This module performs no I/O — it never reads or writes cookies. Framework\n// adapters (Next.js, React Router, …) own the actual cookie store and use these\n// values and helpers to configure and size-check the cookies they set.\n//\n// The companion module `session-cookies.ts` encodes/decodes a session into cookie\n// *values*; this module is about the cookie *attributes* and *limits*.\n\n/**\n * Browser per-cookie size limit (RFC 6265: browsers must support at least\n * 4096 bytes for the sum of the cookie's name and value). Cookies at or above\n * this size are silently dropped by the browser, which manifests as a broken\n * login (the cookie is never stored, so the user appears unauthenticated).\n */\nexport const COOKIE_MAX_BYTES = 4096;\n\n/**\n * Threshold at which an adapter should emit an informational log that a cookie is\n * getting large. This is not an error — a session with many scopes/roles can\n * legitimately approach this size — it just gives visibility before the hard limit.\n */\nexport const COOKIE_INFO_BYTES = 3500;\n\n/**\n * Thrown when a cookie's name + value would meet or exceed the browser's\n * per-cookie size limit. Setting such a cookie would be silently dropped by the\n * browser, so adapters should fail loudly instead. Callers (e.g. an OIDC callback)\n * can catch this to surface a clear error rather than producing a broken login.\n */\nexport class CookieTooLargeError extends Error {\n  constructor(\n    public readonly cookieName: string,\n    public readonly size: number,\n    public readonly limit: number = COOKIE_MAX_BYTES,\n  ) {\n    super(\n      `Cookie \"${cookieName}\" is ${size} bytes, which meets or exceeds the browser limit of ${limit} bytes and would be silently dropped`,\n    );\n    this.name = 'CookieTooLargeError';\n  }\n}\n\nexport interface CookieOptions {\n  /** Cookie path (default: '/') */\n  path?: string;\n  /** Max age in seconds */\n  maxAge?: number;\n  /** SameSite policy (default: 'lax') */\n  sameSite?: 'strict' | 'lax' | 'none';\n  /** HTTP only flag (default: true) */\n  httpOnly?: boolean;\n  /**\n   * Secure flag. `true` in {@link defaultSessionCookieOptions} and\n   * {@link defaultOAuthCookieOptions}; when omitted from a hand-built options\n   * object, the adapter's own default applies.\n   */\n  secure?: boolean;\n}\n\n/**\n * Default cookie options for session cookies.\n * - Secure\n * - HTTP only\n * - Lax same-site policy\n * - 30 days max age\n *\n * `secure` is unconditional rather than derived from NODE_ENV: a deployment that\n * doesn't set it — staging, a container, any non-Next server — would otherwise put\n * the session cookie on the wire in the clear, silently.\n *\n * The cookie spec exempts localhost from the https requirement, so a `Secure`\n * cookie is still set and sent over `http://localhost` and local development is\n * unaffected. Plain http on any other host — a LAN address, a custom dev hostname —\n * needs an explicit `secure: false`.\n */\nexport const defaultSessionCookieOptions: CookieOptions = {\n  path: '/',\n  maxAge: 60 * 60 * 24 * 30, // 30 days\n  sameSite: 'lax',\n  httpOnly: true,\n  secure: true,\n};\n\n/**\n * Default cookie options for OAuth state/PKCE cookies.\n * - Secure — see {@link defaultSessionCookieOptions}\n * - HTTP only\n * - Lax same-site policy\n * - 10 minutes max age (short-lived for security)\n */\nexport const defaultOAuthCookieOptions: CookieOptions = {\n  path: '/',\n  maxAge: 60 * 10, // 10 minutes\n  sameSite: 'lax',\n  httpOnly: true,\n  secure: true,\n};\n\n/**\n * Name of the cookie holding the (split-out) access token.\n *\n * The access token — typically a large JWT carrying scopes/roles — is stored in\n * its own cookie so it gets a full per-cookie byte budget, instead of competing\n * for space with the rest of the session inside a single \"session\" cookie. See\n * {@link CookieTooLargeError} for the limit this works around.\n */\nexport const ACCESS_TOKEN_COOKIE_NAME = 'session_at';\n\n/**\n * Name of the cookie holding the (split-out) ID token, kept for `id_token_hint`\n * on RP-initiated logout.\n *\n * It gets its own cookie for two reasons: it is a second large JWT, which would\n * eat into the access token's byte budget, and it must outlive access-token\n * expiry — a logout after the session has gone stale is exactly when the hint is\n * needed.\n */\nexport const ID_TOKEN_COOKIE_NAME = 'session_it';\n\n/**\n * Name of the main session cookie (everything except the split-out access and ID\n * tokens). See {@link ACCESS_TOKEN_COOKIE_NAME} for why the raw tokens are stored\n * apart.\n */\nexport const SESSION_COOKIE_NAME = 'session';\n\n/**\n * Serialized byte size of a `name=value` cookie pair. The browser per-cookie\n * limit applies to the serialized pair, so the `=` separator is counted too —\n * otherwise a borderline pair (name+value === 4095) would slip through only to be\n * dropped at 4096 once serialized.\n */\nexport function cookieByteSize(name: string, value: string): number {\n  const encoder = new TextEncoder();\n  return encoder.encode(name).length + 1 + encoder.encode(value).length;\n}\n\n/**\n * Asserts that a `name=value` cookie pair is within the browser's per-cookie\n * limit, throwing {@link CookieTooLargeError} if not. Returns the measured byte\n * size so callers can additionally log when it crosses {@link COOKIE_INFO_BYTES}.\n */\nexport function assertCookieWithinLimit(name: string, value: string): number {\n  const size = cookieByteSize(name, value);\n  if (size >= COOKIE_MAX_BYTES) {\n    throw new CookieTooLargeError(name, size);\n  }\n  return size;\n}\n"],"mappings":";;;;;;;AAgBA,IAAa,mBAAmB;;;;;;AAOhC,IAAa,oBAAoB;;;;;;;AAQjC,IAAa,sBAAb,cAAyC,MAAM;CAE3B;CACA;CACA;CAHlB,YACE,YACA,MACA,QAAgC,kBAChC;EACA,MACE,WAAW,WAAW,OAAO,KAAK,sDAAsD,MAAM,qCAChG;EANgB,KAAA,aAAA;EACA,KAAA,OAAA;EACA,KAAA,QAAA;EAKhB,KAAK,OAAO;CACd;AACF;;;;;;;;;;;;;;;;;AAmCA,IAAa,8BAA6C;CACxD,MAAM;CACN,QAAQ;CACR,UAAU;CACV,UAAU;CACV,QAAQ;AACV;;;;;;;;AASA,IAAa,4BAA2C;CACtD,MAAM;CACN,QAAQ;CACR,UAAU;CACV,UAAU;CACV,QAAQ;AACV;;;;;;;;;AAUA,IAAa,2BAA2B;;;;;;;;;;AAWxC,IAAa,uBAAuB;;;;;;AAOpC,IAAa,sBAAsB;;;;;;;AAQnC,SAAgB,eAAe,MAAc,OAAuB;CAClE,MAAM,UAAU,IAAI,YAAY;CAChC,OAAO,QAAQ,OAAO,IAAI,CAAC,CAAC,SAAS,IAAI,QAAQ,OAAO,KAAK,CAAC,CAAC;AACjE;;;;;;AAOA,SAAgB,wBAAwB,MAAc,OAAuB;CAC3E,MAAM,OAAO,eAAe,MAAM,KAAK;CACvC,IAAI,QAAA,MACF,MAAM,IAAI,oBAAoB,MAAM,IAAI;CAE1C,OAAO;AACT"}

package/dist/heartbeat.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Configuration for {@link createHeartbeat}.
+ */
+export interface HeartbeatConfig {
+    /**
+     * Endpoint to POST to in order to refresh the session.
+     * The endpoint must run a server-side refresh and return 2xx with
+     * `{ accessTokenExpiresAt }` (ISO 8601) on success, or 401 when the refresh
+     * token is no longer valid.
+     * @default '/api/auth/heartbeat'
+     */
+    endpoint?: string;
+    /**
+     * How much of the access-token lifetime to keep as headroom: the refresh is
+     * scheduled when `fraction` of the TTL remains. Governs long tokens (a 1 h
+     * token at 0.3 refreshes ~42 min in); short tokens are dominated by
+     * {@link minSkewMs} instead.
+     * @default 0.3
+     */
+    fraction?: number;
+    /**
+     * Absolute floor for the refresh lead time (network round-trip + clock skew).
+     * Dominates for short-lived tokens: a 10 s token still refreshes ~5 s in.
+     * @default 5_000 (5 seconds)
+     */
+    minSkewMs?: number;
+    /**
+     * Floor on how often a refresh may fire, so ultra-short tokens don't hammer
+     * the endpoint.
+     * @default 5_000 (5 seconds)
+     */
+    minRefreshIntervalMs?: number;
+    /**
+     * How recently the user must have interacted for a due refresh to fire.
+     * Decoupled from the access-token TTL on purpose — this only suppresses
+     * refreshes in genuinely abandoned tabs, so keep it generous (tie it to the
+     * IdP's SSO/session idle, not the access token). When a refresh is suppressed
+     * the engine waits for the next interaction (or tab focus) and refreshes then.
+     * @default 1_800_000 (30 minutes)
+     */
+    idleThresholdMs?: number;
+    /**
+     * Known access-token expiry at start (ISO 8601 string or epoch ms). When
+     * provided, the first refresh is scheduled from it instead of priming with an
+     * immediate refresh to discover the expiry.
+     */
+    initialExpiresAt?: string | number | null;
+    /**
+     * Called when the heartbeat endpoint returns 401 — refresh token is gone.
+     */
+    onSessionExpired?: () => void;
+    /**
+     * Called after a successful refresh.
+     */
+    onRefreshed?: () => void;
+    /**
+     * Called on transient errors (network failure, 5xx). The engine retries — this
+     * is just an observability hook.
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Namespace for the logger.
+     * @default 'fides:heartbeat'
+     */
+    loggerNamespace?: string;
+}
+/** Handle returned by {@link createHeartbeat}. */
+export interface HeartbeatHandle {
+    /** Stops the heartbeat: clears timers, removes listeners, aborts in-flight fetches. */
+    stop: () => void;
+}
+/**
+ * Starts an expiry-driven session keepalive and returns a handle to stop it.
+ *
+ * Schedules each refresh from the access token's actual expiry rather than a
+ * fixed interval, so the cadence self-adjusts to whatever TTL the IdP issues: a
+ * 5-minute token refreshes ~3.5 min in; a 10-second token refreshes ~5 s in
+ * (skew floor). It primes with one refresh on start to learn the current expiry
+ * (pass {@link HeartbeatConfig.initialExpiresAt} to skip that), retries on
+ * transient failure, and — for hidden or idle tabs — defers the refresh until
+ * the tab is focused or the user interacts again.
+ *
+ * A 401 from the endpoint (refresh token / SSO session gone) is the logout
+ * trigger via {@link HeartbeatConfig.onSessionExpired}; the idle gate is only an
+ * optimization for abandoned tabs, never a gate on access-token freshness.
+ *
+ * No-ops (returns a handle whose `stop` does nothing) when there is no `window`,
+ * e.g. during server-side rendering.
+ */
+export declare function createHeartbeat(config?: HeartbeatConfig): HeartbeatHandle;
+//# sourceMappingURL=heartbeat.d.ts.map

package/dist/heartbeat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat.d.ts","sourceRoot":"","sources":["../src/heartbeat.ts"],"names":[],"mappings":"AAeA;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAE9B;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAE1C;;OAEG;IACH,gBAAgB,CAAC,EAAE,MAAM,IAAI,CAAC;IAE9B;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;IAEzB;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAEjC;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,kDAAkD;AAClD,MAAM,WAAW,eAAe;IAC9B,uFAAuF;IACvF,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB;AA2BD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,MAAM,GAAE,eAAoB,GAAG,eAAe,CAsK7E"}

package/dist/heartbeat.js

@@ -0,0 +1,169 @@
+import { DEFAULT_ACTIVITY_EVENTS, createActivityTracker } from "./activity-tracker.js";
+import { createLogger } from "./logger.js";
+//#region src/heartbeat.ts
+var DEFAULTS = {
+	endpoint: "/api/auth/heartbeat",
+	fraction: .3,
+	minSkewMs: 5e3,
+	minRefreshIntervalMs: 5e3,
+	idleThresholdMs: 18e5,
+	loggerNamespace: "fides:heartbeat"
+};
+var FALLBACK_INTERVAL_MS = 6e4;
+var MAX_RETRY_DELAY_MS = 6e4;
+/** Parses an ISO 8601 string or epoch-ms number into epoch ms, or null. */
+function toEpochMs(value) {
+	if (typeof value === "number") return Number.isFinite(value) ? value : null;
+	if (typeof value === "string") {
+		const t = Date.parse(value);
+		return Number.isFinite(t) ? t : null;
+	}
+	return null;
+}
+/**
+* Starts an expiry-driven session keepalive and returns a handle to stop it.
+*
+* Schedules each refresh from the access token's actual expiry rather than a
+* fixed interval, so the cadence self-adjusts to whatever TTL the IdP issues: a
+* 5-minute token refreshes ~3.5 min in; a 10-second token refreshes ~5 s in
+* (skew floor). It primes with one refresh on start to learn the current expiry
+* (pass {@link HeartbeatConfig.initialExpiresAt} to skip that), retries on
+* transient failure, and — for hidden or idle tabs — defers the refresh until
+* the tab is focused or the user interacts again.
+*
+* A 401 from the endpoint (refresh token / SSO session gone) is the logout
+* trigger via {@link HeartbeatConfig.onSessionExpired}; the idle gate is only an
+* optimization for abandoned tabs, never a gate on access-token freshness.
+*
+* No-ops (returns a handle whose `stop` does nothing) when there is no `window`,
+* e.g. during server-side rendering.
+*/
+function createHeartbeat(config = {}) {
+	if (typeof window === "undefined") return { stop: () => void 0 };
+	const endpoint = config.endpoint ?? DEFAULTS.endpoint;
+	const fraction = config.fraction ?? DEFAULTS.fraction;
+	const minSkewMs = config.minSkewMs ?? DEFAULTS.minSkewMs;
+	const minRefreshIntervalMs = config.minRefreshIntervalMs ?? DEFAULTS.minRefreshIntervalMs;
+	const idleThresholdMs = config.idleThresholdMs ?? DEFAULTS.idleThresholdMs;
+	const initialExpiresAt = toEpochMs(config.initialExpiresAt);
+	const loggerNamespace = config.loggerNamespace ?? DEFAULTS.loggerNamespace;
+	const logger = createLogger({
+		namespace: loggerNamespace,
+		context: { component: "Heartbeat" }
+	});
+	const tracker = createActivityTracker();
+	const abortController = new AbortController();
+	let timeoutId = null;
+	let stopped = false;
+	let primed = initialExpiresAt !== null;
+	let expiresAt = initialExpiresAt;
+	let failureCount = 0;
+	let wakerArmed = false;
+	const clearTimer = () => {
+		if (timeoutId) {
+			clearTimeout(timeoutId);
+			timeoutId = null;
+		}
+	};
+	const disarmWaker = () => {
+		if (!wakerArmed) return;
+		wakerArmed = false;
+		for (const event of DEFAULT_ACTIVITY_EVENTS) globalThis.removeEventListener(event, onWake);
+		document.removeEventListener("visibilitychange", onVisibleWake);
+	};
+	const teardown = () => {
+		if (stopped) return;
+		stopped = true;
+		clearTimer();
+		disarmWaker();
+		abortController.abort();
+		tracker.dispose();
+	};
+	const nextDelay = () => {
+		if (!primed) return 0;
+		if (expiresAt === null) return FALLBACK_INTERVAL_MS;
+		const now = Date.now();
+		const ttl = Math.max(0, expiresAt - now);
+		const lead = Math.max(minSkewMs, fraction * ttl);
+		return Math.max(minRefreshIntervalMs, expiresAt - lead - now);
+	};
+	const scheduleRefresh = (delay = nextDelay()) => {
+		if (stopped) return;
+		clearTimer();
+		timeoutId = setTimeout(onDue, delay);
+	};
+	function onWake() {
+		if (stopped || !wakerArmed) return;
+		disarmWaker();
+		onDue();
+	}
+	function onVisibleWake() {
+		if (document.visibilityState !== "visible") return;
+		tracker.recordActivity();
+		onWake();
+	}
+	const deferUntilActive = () => {
+		if (stopped || wakerArmed) return;
+		wakerArmed = true;
+		clearTimer();
+		for (const event of DEFAULT_ACTIVITY_EVENTS) globalThis.addEventListener(event, onWake, { passive: true });
+		document.addEventListener("visibilitychange", onVisibleWake);
+	};
+	async function onDue() {
+		if (stopped) return;
+		timeoutId = null;
+		if (document.visibilityState === "hidden" || !tracker.isActiveWithin(idleThresholdMs)) {
+			logger.debug("Refresh due but tab hidden/idle — deferring until active");
+			deferUntilActive();
+			return;
+		}
+		await beat();
+	}
+	async function beat() {
+		if (stopped) return;
+		try {
+			const response = await fetch(endpoint, {
+				method: "POST",
+				credentials: "same-origin",
+				headers: { "content-type": "application/json" },
+				signal: abortController.signal
+			});
+			if (stopped) return;
+			if (response.status === 401) {
+				logger.info("Heartbeat returned 401 — session expired");
+				config.onSessionExpired?.();
+				teardown();
+				return;
+			}
+			if (!response.ok) throw new Error(`Heartbeat failed with status ${response.status}`);
+			failureCount = 0;
+			primed = true;
+			expiresAt = toEpochMs((await response.json().catch(() => null))?.accessTokenExpiresAt);
+			logger.debug({ expiresAt }, "Heartbeat refresh succeeded");
+			config.onRefreshed?.();
+			scheduleRefresh();
+		} catch (error) {
+			if (stopped) return;
+			const err = error instanceof Error ? error : new Error(String(error));
+			logger.warn({ error: err.message }, "Heartbeat tick failed, will retry");
+			config.onError?.(err);
+			failureCount += 1;
+			const backoff = Math.min(MAX_RETRY_DELAY_MS, minRefreshIntervalMs * 2 ** (failureCount - 1));
+			scheduleRefresh(backoff);
+		}
+	}
+	scheduleRefresh();
+	logger.debug({
+		fraction,
+		minSkewMs,
+		minRefreshIntervalMs,
+		idleThresholdMs,
+		endpoint,
+		primed
+	}, "Heartbeat started");
+	return { stop: teardown };
+}
+//#endregion
+export { createHeartbeat };
+
+//# sourceMappingURL=heartbeat.js.map

package/dist/heartbeat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat.js","names":[],"sources":["../src/heartbeat.ts"],"sourcesContent":["// heartbeat.ts\n//\n// Framework-agnostic, browser-side session keepalive engine. This is the logic\n// behind the React `useHeartbeat` hook, extracted so it has no React dependency:\n// any adapter (React, React Router, plain JS) can start it and get a `stop()`\n// back. It uses browser globals (`fetch`, `document`, `window`) at runtime, but\n// importing this module performs no I/O and touches no globals.\n\nimport {\n  createActivityTracker,\n  DEFAULT_ACTIVITY_EVENTS,\n  type ActivityTracker,\n} from './activity-tracker';\nimport { createLogger } from './logger';\n\n/**\n * Configuration for {@link createHeartbeat}.\n */\nexport interface HeartbeatConfig {\n  /**\n   * Endpoint to POST to in order to refresh the session.\n   * The endpoint must run a server-side refresh and return 2xx with\n   * `{ accessTokenExpiresAt }` (ISO 8601) on success, or 401 when the refresh\n   * token is no longer valid.\n   * @default '/api/auth/heartbeat'\n   */\n  endpoint?: string;\n\n  /**\n   * How much of the access-token lifetime to keep as headroom: the refresh is\n   * scheduled when `fraction` of the TTL remains. Governs long tokens (a 1 h\n   * token at 0.3 refreshes ~42 min in); short tokens are dominated by\n   * {@link minSkewMs} instead.\n   * @default 0.3\n   */\n  fraction?: number;\n\n  /**\n   * Absolute floor for the refresh lead time (network round-trip + clock skew).\n   * Dominates for short-lived tokens: a 10 s token still refreshes ~5 s in.\n   * @default 5_000 (5 seconds)\n   */\n  minSkewMs?: number;\n\n  /**\n   * Floor on how often a refresh may fire, so ultra-short tokens don't hammer\n   * the endpoint.\n   * @default 5_000 (5 seconds)\n   */\n  minRefreshIntervalMs?: number;\n\n  /**\n   * How recently the user must have interacted for a due refresh to fire.\n   * Decoupled from the access-token TTL on purpose — this only suppresses\n   * refreshes in genuinely abandoned tabs, so keep it generous (tie it to the\n   * IdP's SSO/session idle, not the access token). When a refresh is suppressed\n   * the engine waits for the next interaction (or tab focus) and refreshes then.\n   * @default 1_800_000 (30 minutes)\n   */\n  idleThresholdMs?: number;\n\n  /**\n   * Known access-token expiry at start (ISO 8601 string or epoch ms). When\n   * provided, the first refresh is scheduled from it instead of priming with an\n   * immediate refresh to discover the expiry.\n   */\n  initialExpiresAt?: string | number | null;\n\n  /**\n   * Called when the heartbeat endpoint returns 401 — refresh token is gone.\n   */\n  onSessionExpired?: () => void;\n\n  /**\n   * Called after a successful refresh.\n   */\n  onRefreshed?: () => void;\n\n  /**\n   * Called on transient errors (network failure, 5xx). The engine retries — this\n   * is just an observability hook.\n   */\n  onError?: (error: Error) => void;\n\n  /**\n   * Namespace for the logger.\n   * @default 'fides:heartbeat'\n   */\n  loggerNamespace?: string;\n}\n\n/** Handle returned by {@link createHeartbeat}. */\nexport interface HeartbeatHandle {\n  /** Stops the heartbeat: clears timers, removes listeners, aborts in-flight fetches. */\n  stop: () => void;\n}\n\nconst DEFAULTS = {\n  endpoint: '/api/auth/heartbeat',\n  fraction: 0.3,\n  minSkewMs: 5_000,\n  minRefreshIntervalMs: 5_000,\n  idleThresholdMs: 30 * 60_000,\n  loggerNamespace: 'fides:heartbeat',\n} as const;\n\n// Fallback cadence when a refresh succeeds but the response carries no usable\n// expiry — keeps the session alive without busy-looping on an unknown TTL.\nconst FALLBACK_INTERVAL_MS = 60_000;\n// Upper bound for exponential backoff between transient-failure retries.\nconst MAX_RETRY_DELAY_MS = 60_000;\n\n/** Parses an ISO 8601 string or epoch-ms number into epoch ms, or null. */\nfunction toEpochMs(value: string | number | null | undefined): number | null {\n  if (typeof value === 'number') return Number.isFinite(value) ? value : null;\n  if (typeof value === 'string') {\n    const t = Date.parse(value);\n    return Number.isFinite(t) ? t : null;\n  }\n  return null;\n}\n\n/**\n * Starts an expiry-driven session keepalive and returns a handle to stop it.\n *\n * Schedules each refresh from the access token's actual expiry rather than a\n * fixed interval, so the cadence self-adjusts to whatever TTL the IdP issues: a\n * 5-minute token refreshes ~3.5 min in; a 10-second token refreshes ~5 s in\n * (skew floor). It primes with one refresh on start to learn the current expiry\n * (pass {@link HeartbeatConfig.initialExpiresAt} to skip that), retries on\n * transient failure, and — for hidden or idle tabs — defers the refresh until\n * the tab is focused or the user interacts again.\n *\n * A 401 from the endpoint (refresh token / SSO session gone) is the logout\n * trigger via {@link HeartbeatConfig.onSessionExpired}; the idle gate is only an\n * optimization for abandoned tabs, never a gate on access-token freshness.\n *\n * No-ops (returns a handle whose `stop` does nothing) when there is no `window`,\n * e.g. during server-side rendering.\n */\nexport function createHeartbeat(config: HeartbeatConfig = {}): HeartbeatHandle {\n  if (typeof window === 'undefined') return { stop: () => undefined };\n\n  const endpoint = config.endpoint ?? DEFAULTS.endpoint;\n  const fraction = config.fraction ?? DEFAULTS.fraction;\n  const minSkewMs = config.minSkewMs ?? DEFAULTS.minSkewMs;\n  const minRefreshIntervalMs = config.minRefreshIntervalMs ?? DEFAULTS.minRefreshIntervalMs;\n  const idleThresholdMs = config.idleThresholdMs ?? DEFAULTS.idleThresholdMs;\n  const initialExpiresAt = toEpochMs(config.initialExpiresAt);\n  const loggerNamespace = config.loggerNamespace ?? DEFAULTS.loggerNamespace;\n\n  const logger = createLogger({\n    namespace: loggerNamespace,\n    context: { component: 'Heartbeat' },\n  });\n\n  const tracker: ActivityTracker = createActivityTracker();\n  const abortController = new AbortController();\n\n  let timeoutId: ReturnType<typeof setTimeout> | null = null;\n  let stopped = false;\n  let primed = initialExpiresAt !== null;\n  let expiresAt: number | null = initialExpiresAt;\n  let failureCount = 0;\n  let wakerArmed = false;\n\n  const clearTimer = (): void => {\n    if (timeoutId) {\n      clearTimeout(timeoutId);\n      timeoutId = null;\n    }\n  };\n\n  const disarmWaker = (): void => {\n    if (!wakerArmed) return;\n    wakerArmed = false;\n    for (const event of DEFAULT_ACTIVITY_EVENTS) {\n      globalThis.removeEventListener(event, onWake);\n    }\n    document.removeEventListener('visibilitychange', onVisibleWake);\n  };\n\n  const teardown = (): void => {\n    if (stopped) return;\n    stopped = true;\n    clearTimer();\n    disarmWaker();\n    abortController.abort();\n    tracker.dispose();\n  };\n\n  // Time until the next refresh should fire, from the current known expiry.\n  const nextDelay = (): number => {\n    if (!primed) return 0; // prime now to discover the expiry\n    if (expiresAt === null) return FALLBACK_INTERVAL_MS;\n    const now = Date.now();\n    const ttl = Math.max(0, expiresAt - now);\n    const lead = Math.max(minSkewMs, fraction * ttl);\n    return Math.max(minRefreshIntervalMs, expiresAt - lead - now);\n  };\n\n  const scheduleRefresh = (delay = nextDelay()): void => {\n    if (stopped) return;\n    clearTimer();\n    timeoutId = setTimeout(onDue, delay);\n  };\n\n  function onWake(): void {\n    if (stopped || !wakerArmed) return;\n    disarmWaker();\n    void onDue();\n  }\n\n  function onVisibleWake(): void {\n    if (document.visibilityState !== 'visible') return;\n    // Returning to the tab counts as activity, so a refresh deferred past\n    // idleThresholdMs while hidden runs now instead of deferring again\n    // (a visibility change does not touch the activity tracker on its own).\n    tracker.recordActivity();\n    onWake();\n  }\n\n  // Suspend refreshing until the tab is focused or the user interacts again.\n  const deferUntilActive = (): void => {\n    if (stopped || wakerArmed) return;\n    wakerArmed = true;\n    clearTimer();\n    for (const event of DEFAULT_ACTIVITY_EVENTS) {\n      globalThis.addEventListener(event, onWake, { passive: true });\n    }\n    document.addEventListener('visibilitychange', onVisibleWake);\n  };\n\n  async function onDue(): Promise<void> {\n    if (stopped) return;\n    timeoutId = null;\n\n    // Hidden or abandoned: don't refresh now; wake on focus/interaction.\n    if (document.visibilityState === 'hidden' || !tracker.isActiveWithin(idleThresholdMs)) {\n      logger.debug('Refresh due but tab hidden/idle — deferring until active');\n      deferUntilActive();\n      return;\n    }\n\n    await beat();\n  }\n\n  async function beat(): Promise<void> {\n    if (stopped) return;\n    try {\n      const response = await fetch(endpoint, {\n        method: 'POST',\n        credentials: 'same-origin',\n        headers: { 'content-type': 'application/json' },\n        signal: abortController.signal,\n      });\n\n      // Stopped (or 401-driven teardown) during the fetch — bail before touching\n      // callbacks so we don't fire on a dead consumer.\n      if (stopped) return;\n\n      if (response.status === 401) {\n        logger.info('Heartbeat returned 401 — session expired');\n        config.onSessionExpired?.();\n        teardown();\n        return;\n      }\n\n      if (!response.ok) {\n        throw new Error(`Heartbeat failed with status ${response.status}`);\n      }\n\n      failureCount = 0;\n      primed = true;\n      const body = (await response.json().catch(() => null)) as\n        | { accessTokenExpiresAt?: string | number | null }\n        | null;\n      expiresAt = toEpochMs(body?.accessTokenExpiresAt);\n\n      logger.debug({ expiresAt }, 'Heartbeat refresh succeeded');\n      config.onRefreshed?.();\n      scheduleRefresh();\n    } catch (error) {\n      if (stopped) return;\n      const err = error instanceof Error ? error : new Error(String(error));\n      logger.warn({ error: err.message }, 'Heartbeat tick failed, will retry');\n      config.onError?.(err);\n\n      // Retry with capped exponential backoff; a real expiry resumes the normal\n      // cadence once a tick succeeds.\n      failureCount += 1;\n      const backoff = Math.min(\n        MAX_RETRY_DELAY_MS,\n        minRefreshIntervalMs * 2 ** (failureCount - 1),\n      );\n      scheduleRefresh(backoff);\n    }\n  }\n\n  scheduleRefresh();\n  logger.debug(\n    { fraction, minSkewMs, minRefreshIntervalMs, idleThresholdMs, endpoint, primed },\n    'Heartbeat started',\n  );\n\n  return { stop: teardown };\n}\n"],"mappings":"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"}

package/dist/index.d.ts

@@ -4,6 +4,7 @@
  * Generic authentication utilities with support for multiple providers.
  */
 export * from './activity-tracker';
+export * from './cookies';
 export * from './logger';
 export * from './oauth-logging';
 export * from './session-refresh';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,oBAAoB,CAAC;AACnC,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,oBAAoB,CAAC;AACnC,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC"}

package/dist/index.js

@@ -1,8 +1,9 @@
 import { DEFAULT_ACTIVITY_EVENTS, createActivityTracker } from "./activity-tracker.js";
+import { ACCESS_TOKEN_COOKIE_NAME, COOKIE_INFO_BYTES, COOKIE_MAX_BYTES, CookieTooLargeError, ID_TOKEN_COOKIE_NAME, SESSION_COOKIE_NAME, assertCookieWithinLimit, cookieByteSize, defaultOAuthCookieOptions, defaultSessionCookieOptions } from "./cookies.js";
 import { configureLogger, createLogger } from "./logger.js";
 import { getOAuthConfigLogContext, getOAuthErrorLogContext } from "./oauth-logging.js";
 import { refreshSession } from "./session-refresh.js";
-import { accessTokenExpires, createEncryptedJWT, decrypt, encrypt, generateToken, getSessionSecret, getSessionSecretUint8Array, hasScope, hexToUint8Array, sha256, sha512, toHex } from "./utils.js";
+import { accessTokenExpires, createEncryptedJWT, decrypt, decryptJWT, encrypt, generateToken, getSessionSecret, getSessionSecretUint8Array, hasScope, hexToUint8Array, sha256, sha512, toHex } from "./utils.js";
 import { isSession, validateSessionJwt } from "./session-validation.js";
 import "./types.js";
-export { DEFAULT_ACTIVITY_EVENTS, accessTokenExpires, configureLogger, createActivityTracker, createEncryptedJWT, createLogger, decrypt, encrypt, generateToken, getOAuthConfigLogContext, getOAuthErrorLogContext, getSessionSecret, getSessionSecretUint8Array, hasScope, hexToUint8Array, isSession, refreshSession, sha256, sha512, toHex, validateSessionJwt };
+export { ACCESS_TOKEN_COOKIE_NAME, COOKIE_INFO_BYTES, COOKIE_MAX_BYTES, CookieTooLargeError, DEFAULT_ACTIVITY_EVENTS, ID_TOKEN_COOKIE_NAME, SESSION_COOKIE_NAME, accessTokenExpires, assertCookieWithinLimit, configureLogger, cookieByteSize, createActivityTracker, createEncryptedJWT, createLogger, decrypt, decryptJWT, defaultOAuthCookieOptions, defaultSessionCookieOptions, encrypt, generateToken, getOAuthConfigLogContext, getOAuthErrorLogContext, getSessionSecret, getSessionSecretUint8Array, hasScope, hexToUint8Array, isSession, refreshSession, sha256, sha512, toHex, validateSessionJwt };

package/dist/logger.js

@@ -8,7 +8,7 @@ function serializeError(value) {
 	return value;
 }
 /** Field names the logger reserves so callers can't accidentally clobber them. */
-var RESERVED_KEYS = new Set([
+var RESERVED_KEYS = /* @__PURE__ */ new Set([
 	"level",
 	"time",
 	"namespace"