@eventuras/fides-auth 0.12.0 → 0.14.0

package/dist/session-cookies.d.ts

@@ -1,3 +1,4 @@
+import { SessionRejectedReason } from './session-events';
 import { Session } from './types';
 /** Encrypted cookie values produced from a session. */
 export interface EncodedSessionCookies {
@@ -28,6 +29,27 @@ export interface RawSessionCookies {
  * @param secret - The encryption key as a hex string or Uint8Array (32 bytes for A256GCM).
  */
 export declare function encodeSessionCookies(session: Session, secret: string | Uint8Array): Promise<EncodedSessionCookies>;
+/** Outcome of decoding the cookie values: a session, or why there isn't one. */
+export type DecodedSessionCookies = {
+    session: Session;
+    reason?: undefined;
+} | {
+    session: null;
+    reason: SessionRejectedReason;
+};
+/**
+ * Decodes the cookie values back into a session, reporting why when it can't.
+ *
+ * Same rules as {@link decodeSessionCookies}, but the failure carries a
+ * {@link SessionRejectedReason} from the package-wide vocabulary so a proxy or a
+ * status route logs the same word for the same situation as the heartbeat
+ * endpoint does. Deliberately does not log: the caller knows the request
+ * context, and logging here too would double every rejection.
+ *
+ * @param raw - The raw cookie values read from the store.
+ * @param secret - The decryption key as a hex string or Uint8Array (32 bytes for A256GCM).
+ */
+export declare function tryDecodeSessionCookies(raw: RawSessionCookies, secret: string | Uint8Array): Promise<DecodedSessionCookies>;
 /**
  * Decodes the cookie values back into a session, reattaching the access and ID tokens.
  *
@@ -37,6 +59,9 @@ export declare function encodeSessionCookies(session: Session, secret: string |
  * single-cookie session (one re-login). A corrupt access-token value is
  * tolerated: the session is returned without it.
  *
+ * Prefer {@link tryDecodeSessionCookies} when you want to log *why* there is no
+ * session.
+ *
  * @param raw - The raw cookie values read from the store.
  * @param secret - The decryption key as a hex string or Uint8Array (32 bytes for A256GCM).
  */

package/dist/session-cookies.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-cookies.d.ts","sourceRoot":"","sources":["../src/session-cookies.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAIlC,uDAAuD;AACvD,MAAM,WAAW,qBAAqB;IACpC,sFAAsF;IACtF,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mFAAmF;IACnF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,8DAA8D;AAC9D,MAAM,WAAW,iBAAiB;IAChC,wDAAwD;IACxD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,wDAAwD;IACxD,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,MAAM,GAAG,UAAU,GAC1B,OAAO,CAAC,qBAAqB,CAAC,CAmBhC;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,iBAAiB,EACtB,MAAM,EAAE,MAAM,GAAG,UAAU,GAC1B,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAoCzB;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,GAAG,UAAU,GAC1B,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAQ7B"}
+{"version":3,"file":"session-cookies.d.ts","sourceRoot":"","sources":["../src/session-cookies.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAIlC,uDAAuD;AACvD,MAAM,WAAW,qBAAqB;IACpC,sFAAsF;IACtF,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mFAAmF;IACnF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,8DAA8D;AAC9D,MAAM,WAAW,iBAAiB;IAChC,wDAAwD;IACxD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,wDAAwD;IACxD,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,MAAM,GAAG,UAAU,GAC1B,OAAO,CAAC,qBAAqB,CAAC,CAmBhC;AAED,gFAAgF;AAChF,MAAM,MAAM,qBAAqB,GAC7B;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,SAAS,CAAA;CAAE,GACxC;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,qBAAqB,CAAA;CAAE,CAAC;AAErD;;;;;;;;;;;GAWG;AACH,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,iBAAiB,EACtB,MAAM,EAAE,MAAM,GAAG,UAAU,GAC1B,OAAO,CAAC,qBAAqB,CAAC,CAyChC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,iBAAiB,EACtB,MAAM,EAAE,MAAM,GAAG,UAAU,GAC1B,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAEzB;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,GAAG,UAAU,GAC1B,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAQ7B"}

package/dist/session-cookies.js

@@ -29,24 +29,27 @@ async function encodeSessionCookies(session, secret) {
 	};
 }
 /**
-* Decodes the cookie values back into a session, reattaching the access and ID tokens.
+* Decodes the cookie values back into a session, reporting why when it can't.
 *
-* Returns the session whenever the main value decrypts and validates — an
-* expired access token does not hide it; token freshness is the caller's
-* concern. Returns null for a missing/invalid main value, or a stale legacy
-* single-cookie session (one re-login). A corrupt access-token value is
-* tolerated: the session is returned without it.
+* Same rules as {@link decodeSessionCookies}, but the failure carries a
+* {@link SessionRejectedReason} from the package-wide vocabulary so a proxy or a
+* status route logs the same word for the same situation as the heartbeat
+* endpoint does. Deliberately does not log: the caller knows the request
+* context, and logging here too would double every rejection.
 *
 * @param raw - The raw cookie values read from the store.
 * @param secret - The decryption key as a hex string or Uint8Array (32 bytes for A256GCM).
 */
-async function decodeSessionCookies(raw, secret) {
-	if (!raw.session) return null;
+async function tryDecodeSessionCookies(raw, secret) {
+	if (!raw.session) return {
+		session: null,
+		reason: "no_session_cookie"
+	};
 	const { status, session } = await validateSessionJwt(raw.session, secret);
-	if (status !== "VALID" || !session) {
-		logger.debug({ status }, "Session cookie did not validate");
-		return null;
-	}
+	if (status !== "VALID" || !session) return {
+		session: null,
+		reason: status === "EXPIRED" ? "stale_legacy_session" : "unreadable_session"
+	};
 	if (raw.accessToken) try {
 		const payload = await decryptJWT(raw.accessToken, secret);
 		const accessToken = typeof payload.accessToken === "string" ? payload.accessToken : void 0;
@@ -64,7 +67,25 @@ async function decodeSessionCookies(raw, secret) {
 			idToken
 		};
 	}
-	return session;
+	return { session };
+}
+/**
+* Decodes the cookie values back into a session, reattaching the access and ID tokens.
+*
+* Returns the session whenever the main value decrypts and validates — an
+* expired access token does not hide it; token freshness is the caller's
+* concern. Returns null for a missing/invalid main value, or a stale legacy
+* single-cookie session (one re-login). A corrupt access-token value is
+* tolerated: the session is returned without it.
+*
+* Prefer {@link tryDecodeSessionCookies} when you want to log *why* there is no
+* session.
+*
+* @param raw - The raw cookie values read from the store.
+* @param secret - The decryption key as a hex string or Uint8Array (32 bytes for A256GCM).
+*/
+async function decodeSessionCookies(raw, secret) {
+	return (await tryDecodeSessionCookies(raw, secret)).session;
 }
 /**
 * Decrypts the ID-token cookie value on its own, independent of session validity.
@@ -84,6 +105,6 @@ async function decodeIdTokenCookie(raw, secret) {
 	}
 }
 //#endregion
-export { decodeIdTokenCookie, decodeSessionCookies, encodeSessionCookies };
+export { decodeIdTokenCookie, decodeSessionCookies, encodeSessionCookies, tryDecodeSessionCookies };
 
 //# sourceMappingURL=session-cookies.js.map

package/dist/session-cookies.js.map

@@ -1 +1 @@
-{"version":3,"file":"session-cookies.js","names":[],"sources":["../src/session-cookies.ts"],"sourcesContent":["// session-cookies.ts\n//\n// Framework-agnostic encoding/decoding of a session into cookie *values*. This\n// module performs no I/O — it never reads or writes cookies. Framework adapters\n// (Next.js, React Router, …) own the actual cookie store and call these helpers\n// to split a session across two cookie values and to reassemble it again.\n//\n// The split: the large raw JWTs — the access token and the ID token (kept for\n// `id_token_hint` on logout) — each get their own encrypted value, everything else\n// goes in the main one, so no cookie has to carry two JWTs against the ~4KB limit.\n\nimport { createEncryptedJWT, decryptJWT } from './utils';\nimport { validateSessionJwt } from './session-validation';\nimport { createLogger } from './logger';\nimport { Session } from './types';\n\nconst logger = createLogger({ namespace: 'fides-auth:session-cookies' });\n\n/** Encrypted cookie values produced from a session. */\nexport interface EncodedSessionCookies {\n  /** Value for the main session cookie (everything except the raw access/ID tokens). */\n  session: string;\n  /**\n   * Value for the access-token cookie, or `undefined` when the session carries\n   * no access token. Adapters should delete the access-token cookie in that case.\n   */\n  accessToken?: string;\n  /** Value for the ID-token cookie, or `undefined` when the session carries none. */\n  idToken?: string;\n}\n\n/** Raw cookie values read from the store, before decoding. */\nexport interface RawSessionCookies {\n  /** The main session cookie value, or null if absent. */\n  session: string | null;\n  /** The access-token cookie value, or null if absent. */\n  accessToken: string | null;\n  /** The ID-token cookie value, or null if absent. */\n  idToken?: string | null;\n}\n\n/**\n * Encrypts a session into the three cookie values, splitting the raw access and ID\n * tokens out.\n *\n * @param session - The session to encode.\n * @param secret - The encryption key as a hex string or Uint8Array (32 bytes for A256GCM).\n */\nexport async function encodeSessionCookies(\n  session: Session,\n  secret: string | Uint8Array,\n): Promise<EncodedSessionCookies> {\n  const { tokens, ...rest } = session;\n  const accessToken = tokens?.accessToken;\n  const idToken = tokens?.idToken;\n\n  // Main value: the whole session minus the raw access and ID tokens (undefined\n  // keys are dropped during JWT serialization).\n  const coreSession: Session = {\n    ...rest,\n    tokens: tokens ? { ...tokens, accessToken: undefined, idToken: undefined } : undefined,\n  };\n\n  const main = await createEncryptedJWT(coreSession, secret);\n\n  return {\n    session: main,\n    accessToken: accessToken ? await createEncryptedJWT({ accessToken }, secret) : undefined,\n    idToken: idToken ? await createEncryptedJWT({ idToken }, secret) : undefined,\n  };\n}\n\n/**\n * Decodes the cookie values back into a session, reattaching the access and ID tokens.\n *\n * Returns the session whenever the main value decrypts and validates — an\n * expired access token does not hide it; token freshness is the caller's\n * concern. Returns null for a missing/invalid main value, or a stale legacy\n * single-cookie session (one re-login). A corrupt access-token value is\n * tolerated: the session is returned without it.\n *\n * @param raw - The raw cookie values read from the store.\n * @param secret - The decryption key as a hex string or Uint8Array (32 bytes for A256GCM).\n */\nexport async function decodeSessionCookies(\n  raw: RawSessionCookies,\n  secret: string | Uint8Array,\n): Promise<Session | null> {\n  if (!raw.session) {\n    return null;\n  }\n\n  const { status, session } = await validateSessionJwt(raw.session, secret);\n\n  // EXPIRED only fires for legacy single-cookie sessions — dropped, not migrated.\n  if (status !== 'VALID' || !session) {\n    logger.debug({ status }, 'Session cookie did not validate');\n    return null;\n  }\n\n  if (raw.accessToken) {\n    try {\n      const payload = await decryptJWT(raw.accessToken, secret);\n      const accessToken = typeof payload.accessToken === 'string' ? payload.accessToken : undefined;\n\n      if (accessToken) {\n        // Attached as stored, expired or not — freshness is the caller's concern.\n        session.tokens = { ...session.tokens, accessToken };\n      }\n    } catch (error) {\n      // A corrupt/forged access-token value shouldn't take down the session.\n      logger.warn({ error }, 'Failed to decode access-token cookie');\n    }\n  }\n\n  if (raw.idToken) {\n    const idToken = await decodeIdTokenCookie(raw.idToken, secret);\n    if (idToken) {\n      session.tokens = { ...session.tokens, idToken };\n    }\n  }\n\n  return session;\n}\n\n/**\n * Decrypts the ID-token cookie value on its own, independent of session validity.\n * Logout needs the hint precisely when the session has gone stale, so this must not\n * go through {@link decodeSessionCookies}.\n *\n * @param raw - The ID-token cookie value.\n * @param secret - The decryption key as a hex string or Uint8Array (32 bytes for A256GCM).\n */\nexport async function decodeIdTokenCookie(\n  raw: string,\n  secret: string | Uint8Array,\n): Promise<string | undefined> {\n  try {\n    const payload = await decryptJWT(raw, secret);\n    return typeof payload.idToken === 'string' ? payload.idToken : undefined;\n  } catch (error) {\n    logger.warn({ error }, 'Failed to decode ID-token cookie');\n    return undefined;\n  }\n}\n"],"mappings":";;;;AAgBA,IAAM,SAAS,aAAa,EAAE,WAAW,6BAA6B,CAAC;;;;;;;;AAgCvE,eAAsB,qBACpB,SACA,QACgC;CAChC,MAAM,EAAE,QAAQ,GAAG,SAAS;CAC5B,MAAM,cAAc,QAAQ;CAC5B,MAAM,UAAU,QAAQ;CAIxB,MAAM,cAAuB;EAC3B,GAAG;EACH,QAAQ,SAAS;GAAE,GAAG;GAAQ,aAAa,KAAA;GAAW,SAAS,KAAA;EAAU,IAAI,KAAA;CAC/E;CAIA,OAAO;EACL,SAAS,MAHQ,mBAAmB,aAAa,MAAM;EAIvD,aAAa,cAAc,MAAM,mBAAmB,EAAE,YAAY,GAAG,MAAM,IAAI,KAAA;EAC/E,SAAS,UAAU,MAAM,mBAAmB,EAAE,QAAQ,GAAG,MAAM,IAAI,KAAA;CACrE;AACF;;;;;;;;;;;;;AAcA,eAAsB,qBACpB,KACA,QACyB;CACzB,IAAI,CAAC,IAAI,SACP,OAAO;CAGT,MAAM,EAAE,QAAQ,YAAY,MAAM,mBAAmB,IAAI,SAAS,MAAM;CAGxE,IAAI,WAAW,WAAW,CAAC,SAAS;EAClC,OAAO,MAAM,EAAE,OAAO,GAAG,iCAAiC;EAC1D,OAAO;CACT;CAEA,IAAI,IAAI,aACN,IAAI;EACF,MAAM,UAAU,MAAM,WAAW,IAAI,aAAa,MAAM;EACxD,MAAM,cAAc,OAAO,QAAQ,gBAAgB,WAAW,QAAQ,cAAc,KAAA;EAEpF,IAAI,aAEF,QAAQ,SAAS;GAAE,GAAG,QAAQ;GAAQ;EAAY;CAEtD,SAAS,OAAO;EAEd,OAAO,KAAK,EAAE,MAAM,GAAG,sCAAsC;CAC/D;CAGF,IAAI,IAAI,SAAS;EACf,MAAM,UAAU,MAAM,oBAAoB,IAAI,SAAS,MAAM;EAC7D,IAAI,SACF,QAAQ,SAAS;GAAE,GAAG,QAAQ;GAAQ;EAAQ;CAElD;CAEA,OAAO;AACT;;;;;;;;;AAUA,eAAsB,oBACpB,KACA,QAC6B;CAC7B,IAAI;EACF,MAAM,UAAU,MAAM,WAAW,KAAK,MAAM;EAC5C,OAAO,OAAO,QAAQ,YAAY,WAAW,QAAQ,UAAU,KAAA;CACjE,SAAS,OAAO;EACd,OAAO,KAAK,EAAE,MAAM,GAAG,kCAAkC;EACzD;CACF;AACF"}
+{"version":3,"file":"session-cookies.js","names":[],"sources":["../src/session-cookies.ts"],"sourcesContent":["// session-cookies.ts\n//\n// Framework-agnostic encoding/decoding of a session into cookie *values*. This\n// module performs no I/O — it never reads or writes cookies. Framework adapters\n// (Next.js, React Router, …) own the actual cookie store and call these helpers\n// to split a session across two cookie values and to reassemble it again.\n//\n// The split: the large raw JWTs — the access token and the ID token (kept for\n// `id_token_hint` on logout) — each get their own encrypted value, everything else\n// goes in the main one, so no cookie has to carry two JWTs against the ~4KB limit.\n\nimport { createEncryptedJWT, decryptJWT } from './utils';\nimport { validateSessionJwt } from './session-validation';\nimport { createLogger } from './logger';\nimport type { SessionRejectedReason } from './session-events';\nimport { Session } from './types';\n\nconst logger = createLogger({ namespace: 'fides-auth:session-cookies' });\n\n/** Encrypted cookie values produced from a session. */\nexport interface EncodedSessionCookies {\n  /** Value for the main session cookie (everything except the raw access/ID tokens). */\n  session: string;\n  /**\n   * Value for the access-token cookie, or `undefined` when the session carries\n   * no access token. Adapters should delete the access-token cookie in that case.\n   */\n  accessToken?: string;\n  /** Value for the ID-token cookie, or `undefined` when the session carries none. */\n  idToken?: string;\n}\n\n/** Raw cookie values read from the store, before decoding. */\nexport interface RawSessionCookies {\n  /** The main session cookie value, or null if absent. */\n  session: string | null;\n  /** The access-token cookie value, or null if absent. */\n  accessToken: string | null;\n  /** The ID-token cookie value, or null if absent. */\n  idToken?: string | null;\n}\n\n/**\n * Encrypts a session into the three cookie values, splitting the raw access and ID\n * tokens out.\n *\n * @param session - The session to encode.\n * @param secret - The encryption key as a hex string or Uint8Array (32 bytes for A256GCM).\n */\nexport async function encodeSessionCookies(\n  session: Session,\n  secret: string | Uint8Array,\n): Promise<EncodedSessionCookies> {\n  const { tokens, ...rest } = session;\n  const accessToken = tokens?.accessToken;\n  const idToken = tokens?.idToken;\n\n  // Main value: the whole session minus the raw access and ID tokens (undefined\n  // keys are dropped during JWT serialization).\n  const coreSession: Session = {\n    ...rest,\n    tokens: tokens ? { ...tokens, accessToken: undefined, idToken: undefined } : undefined,\n  };\n\n  const main = await createEncryptedJWT(coreSession, secret);\n\n  return {\n    session: main,\n    accessToken: accessToken ? await createEncryptedJWT({ accessToken }, secret) : undefined,\n    idToken: idToken ? await createEncryptedJWT({ idToken }, secret) : undefined,\n  };\n}\n\n/** Outcome of decoding the cookie values: a session, or why there isn't one. */\nexport type DecodedSessionCookies =\n  | { session: Session; reason?: undefined }\n  | { session: null; reason: SessionRejectedReason };\n\n/**\n * Decodes the cookie values back into a session, reporting why when it can't.\n *\n * Same rules as {@link decodeSessionCookies}, but the failure carries a\n * {@link SessionRejectedReason} from the package-wide vocabulary so a proxy or a\n * status route logs the same word for the same situation as the heartbeat\n * endpoint does. Deliberately does not log: the caller knows the request\n * context, and logging here too would double every rejection.\n *\n * @param raw - The raw cookie values read from the store.\n * @param secret - The decryption key as a hex string or Uint8Array (32 bytes for A256GCM).\n */\nexport async function tryDecodeSessionCookies(\n  raw: RawSessionCookies,\n  secret: string | Uint8Array,\n): Promise<DecodedSessionCookies> {\n  if (!raw.session) {\n    return { session: null, reason: 'no_session_cookie' };\n  }\n\n  const { status, session } = await validateSessionJwt(raw.session, secret);\n\n  // EXPIRED only fires for legacy single-cookie sessions — dropped, not migrated,\n  // and worth separating from corruption because it costs exactly one re-login.\n  // validateSessionJwt already logs why it rejected the value; this layer only\n  // translates that into the shared vocabulary.\n  if (status !== 'VALID' || !session) {\n    return {\n      session: null,\n      reason: status === 'EXPIRED' ? 'stale_legacy_session' : 'unreadable_session',\n    };\n  }\n\n  if (raw.accessToken) {\n    try {\n      const payload = await decryptJWT(raw.accessToken, secret);\n      const accessToken = typeof payload.accessToken === 'string' ? payload.accessToken : undefined;\n\n      if (accessToken) {\n        // Attached as stored, expired or not — freshness is the caller's concern.\n        session.tokens = { ...session.tokens, accessToken };\n      }\n    } catch (error) {\n      // A corrupt/forged access-token value shouldn't take down the session.\n      logger.warn({ error }, 'Failed to decode access-token cookie');\n    }\n  }\n\n  if (raw.idToken) {\n    const idToken = await decodeIdTokenCookie(raw.idToken, secret);\n    if (idToken) {\n      session.tokens = { ...session.tokens, idToken };\n    }\n  }\n\n  return { session };\n}\n\n/**\n * Decodes the cookie values back into a session, reattaching the access and ID tokens.\n *\n * Returns the session whenever the main value decrypts and validates — an\n * expired access token does not hide it; token freshness is the caller's\n * concern. Returns null for a missing/invalid main value, or a stale legacy\n * single-cookie session (one re-login). A corrupt access-token value is\n * tolerated: the session is returned without it.\n *\n * Prefer {@link tryDecodeSessionCookies} when you want to log *why* there is no\n * session.\n *\n * @param raw - The raw cookie values read from the store.\n * @param secret - The decryption key as a hex string or Uint8Array (32 bytes for A256GCM).\n */\nexport async function decodeSessionCookies(\n  raw: RawSessionCookies,\n  secret: string | Uint8Array,\n): Promise<Session | null> {\n  return (await tryDecodeSessionCookies(raw, secret)).session;\n}\n\n/**\n * Decrypts the ID-token cookie value on its own, independent of session validity.\n * Logout needs the hint precisely when the session has gone stale, so this must not\n * go through {@link decodeSessionCookies}.\n *\n * @param raw - The ID-token cookie value.\n * @param secret - The decryption key as a hex string or Uint8Array (32 bytes for A256GCM).\n */\nexport async function decodeIdTokenCookie(\n  raw: string,\n  secret: string | Uint8Array,\n): Promise<string | undefined> {\n  try {\n    const payload = await decryptJWT(raw, secret);\n    return typeof payload.idToken === 'string' ? payload.idToken : undefined;\n  } catch (error) {\n    logger.warn({ error }, 'Failed to decode ID-token cookie');\n    return undefined;\n  }\n}\n"],"mappings":";;;;AAiBA,IAAM,SAAS,aAAa,EAAE,WAAW,6BAA6B,CAAC;;;;;;;;AAgCvE,eAAsB,qBACpB,SACA,QACgC;CAChC,MAAM,EAAE,QAAQ,GAAG,SAAS;CAC5B,MAAM,cAAc,QAAQ;CAC5B,MAAM,UAAU,QAAQ;CAIxB,MAAM,cAAuB;EAC3B,GAAG;EACH,QAAQ,SAAS;GAAE,GAAG;GAAQ,aAAa,KAAA;GAAW,SAAS,KAAA;EAAU,IAAI,KAAA;CAC/E;CAIA,OAAO;EACL,SAAS,MAHQ,mBAAmB,aAAa,MAAM;EAIvD,aAAa,cAAc,MAAM,mBAAmB,EAAE,YAAY,GAAG,MAAM,IAAI,KAAA;EAC/E,SAAS,UAAU,MAAM,mBAAmB,EAAE,QAAQ,GAAG,MAAM,IAAI,KAAA;CACrE;AACF;;;;;;;;;;;;;AAmBA,eAAsB,wBACpB,KACA,QACgC;CAChC,IAAI,CAAC,IAAI,SACP,OAAO;EAAE,SAAS;EAAM,QAAQ;CAAoB;CAGtD,MAAM,EAAE,QAAQ,YAAY,MAAM,mBAAmB,IAAI,SAAS,MAAM;CAMxE,IAAI,WAAW,WAAW,CAAC,SACzB,OAAO;EACL,SAAS;EACT,QAAQ,WAAW,YAAY,yBAAyB;CAC1D;CAGF,IAAI,IAAI,aACN,IAAI;EACF,MAAM,UAAU,MAAM,WAAW,IAAI,aAAa,MAAM;EACxD,MAAM,cAAc,OAAO,QAAQ,gBAAgB,WAAW,QAAQ,cAAc,KAAA;EAEpF,IAAI,aAEF,QAAQ,SAAS;GAAE,GAAG,QAAQ;GAAQ;EAAY;CAEtD,SAAS,OAAO;EAEd,OAAO,KAAK,EAAE,MAAM,GAAG,sCAAsC;CAC/D;CAGF,IAAI,IAAI,SAAS;EACf,MAAM,UAAU,MAAM,oBAAoB,IAAI,SAAS,MAAM;EAC7D,IAAI,SACF,QAAQ,SAAS;GAAE,GAAG,QAAQ;GAAQ;EAAQ;CAElD;CAEA,OAAO,EAAE,QAAQ;AACnB;;;;;;;;;;;;;;;;AAiBA,eAAsB,qBACpB,KACA,QACyB;CACzB,QAAQ,MAAM,wBAAwB,KAAK,MAAM,EAAA,CAAG;AACtD;;;;;;;;;AAUA,eAAsB,oBACpB,KACA,QAC6B;CAC7B,IAAI;EACF,MAAM,UAAU,MAAM,WAAW,KAAK,MAAM;EAC5C,OAAO,OAAO,QAAQ,YAAY,WAAW,QAAQ,UAAU,KAAA;CACjE,SAAS,OAAO;EACd,OAAO,KAAK,EAAE,MAAM,GAAG,kCAAkC;EACzD;CACF;AACF"}

package/dist/session-events.d.ts

@@ -0,0 +1,149 @@
+import { FidesLogger } from './logger';
+/**
+ * Event names. Use these constants rather than string literals so a rename is a
+ * compile error at every call site instead of a silently broken dashboard.
+ */
+export declare const SESSION_EVENT: {
+    /** A session was created from a token response (login, or client-credentials grant). */
+    readonly CREATED: "session.created";
+    /** An existing session was renewed with a fresh access token. */
+    readonly REFRESHED: "session.refreshed";
+    /** A request could not proceed with the session it had. Carries a {@link SessionRejectedReason}. */
+    readonly REJECTED: "session.rejected";
+    /** A refresh attempt failed. Carries a {@link RefreshFailureCause}. */
+    readonly REFRESH_FAILED: "session.refresh_failed";
+    /** Session cookies were deleted. Carries a {@link SessionClearedTrigger}. */
+    readonly CLEARED: "session.cleared";
+};
+export type SessionEventName = (typeof SESSION_EVENT)[keyof typeof SESSION_EVENT];
+/**
+ * Why a session could not be used for a request.
+ *
+ * One vocabulary for the whole package, so a proxy, a status route and the
+ * heartbeat endpoint all report the same word for the same situation.
+ */
+export type SessionRejectedReason = 
+/** No session cookie was sent. The ordinary anonymous case. */
+'no_session_cookie'
+/** A session cookie was sent but did not decrypt or validate — corruption, or a rotated secret. */
+ | 'unreadable_session'
+/** A pre-split single-cookie session. Dropped rather than migrated; costs one re-login. */
+ | 'stale_legacy_session'
+/** The session decoded but carries no refresh token — usually `offline_access` was never granted. */
+ | 'no_refresh_token'
+/** The refresh token was rejected by the provider. See {@link RefreshFailureCause}. */
+ | 'refresh_failed';
+/**
+ * Why a refresh attempt failed.
+ *
+ * The distinction that matters operationally: only `invalid_grant` means the
+ * user must log in again. The other two are infrastructure faults where the
+ * session is probably still fine, and logging the user out would be wrong.
+ */
+export type RefreshFailureCause = 
+/** The provider rejected the refresh token: expired, revoked, or already used. Terminal. */
+'invalid_grant'
+/** The provider was never reached — DNS, TCP, TLS, timeout, abort. Retryable. */
+ | 'transport'
+/** The provider was reached but answered with an error or something unparseable. Retryable. */
+ | 'idp_error';
+/** What caused the session cookies to be deleted. */
+export type SessionClearedTrigger = 
+/** The user (or the app) logged out deliberately. */
+'logout'
+/** The session was unusable and cleaned up. */
+ | 'rejected';
+/** Structured payload for one lifecycle event. */
+export type SessionEvent = {
+    event: typeof SESSION_EVENT.CREATED;
+    sid?: string;
+    /** False here guarantees logouts at access-token TTL — the single most useful login-time signal. */
+    hasRefreshToken: boolean;
+    /** Scopes the provider actually granted, which is not necessarily what was requested. */
+    scopes?: string[];
+    /** Seconds until the access token expires. */
+    expiresIn?: number;
+    /** Total bytes written across the session cookies. Near ~4096 means a session about to break. */
+    cookieBytes?: number;
+} | {
+    event: typeof SESSION_EVENT.REFRESHED;
+    sid?: string;
+    expiresIn?: number;
+    /** True when the provider issued a new refresh token. Rotation turns a lost cookie write into a dead session. */
+    rotatedRefreshToken: boolean;
+    cookieBytes?: number;
+} | {
+    event: typeof SESSION_EVENT.REJECTED;
+    sid?: string;
+    reason: SessionRejectedReason;
+    /** Which component made the call, e.g. 'heartbeat'. */
+    source?: string;
+} | {
+    event: typeof SESSION_EVENT.REFRESH_FAILED;
+    sid?: string;
+    cause: RefreshFailureCause;
+    /** HTTP status from the provider, when it answered at all. */
+    status?: number;
+    /** Expiry of the access token we were trying to replace — how long the session had left. */
+    accessTokenExpiresAt?: string;
+    error?: unknown;
+} | {
+    event: typeof SESSION_EVENT.CLEARED;
+    sid?: string;
+    trigger: SessionClearedTrigger;
+};
+type Level = 'debug' | 'info' | 'warn' | 'error';
+/** Resolves the level for an event, applying the per-reason and per-cause policy. */
+export declare function sessionEventLevel(payload: SessionEvent): Level;
+/**
+ * Emits one lifecycle event at the level the policy dictates.
+ *
+ * Call sites pass data, never a level or a message — that is what keeps the
+ * vocabulary consistent across modules and makes a dashboard built on `event`
+ * and `reason` keep working.
+ */
+export declare function logSessionEvent(logger: FidesLogger, payload: SessionEvent): void;
+/** The reasons, as a runtime list — for validating values that arrive over the wire. */
+export declare const SESSION_REJECTED_REASONS: readonly ["no_session_cookie", "unreadable_session", "stale_legacy_session", "no_refresh_token", "refresh_failed"];
+/** Narrows an untrusted value (a response body, a query param) to a known reason. */
+export declare function isSessionRejectedReason(value: unknown): value is SessionRejectedReason;
+/**
+ * Browser-side counterpart of {@link SessionEvent}.
+ *
+ * Same names and same `reason` vocabulary as the server events, so a consumer
+ * that beacons these to its own endpoint gets one queryable stream across both
+ * halves of a session. The shapes differ where the browser genuinely knows
+ * less: it never learns *why* a refresh failed server-side, only the status it
+ * got back, so there is no `cause` here to invent.
+ */
+export type SessionClientEvent = {
+    event: typeof SESSION_EVENT.REFRESHED;
+    source: 'heartbeat';
+    /** Epoch ms of the new access-token expiry, or null when the server didn't say. */
+    expiresAt: number | null;
+} | {
+    event: typeof SESSION_EVENT.REJECTED;
+    source: 'heartbeat' | 'session-monitor';
+    /** The server's own reason when it sent one; absent when it didn't. */
+    reason?: SessionRejectedReason;
+} | {
+    event: typeof SESSION_EVENT.REFRESH_FAILED;
+    source: 'heartbeat';
+    /** HTTP status, when there was a response at all. Absent means the request never landed. */
+    status?: number;
+    /** 1 for the first consecutive failure, 2 for the next, and so on. */
+    attempt: number;
+    error?: string;
+};
+/**
+ * Mints a session correlation id: 16 hex characters (64 bits).
+ *
+ * Deliberately random rather than derived from the refresh token. A hash of the
+ * refresh token would change every time the provider rotates it — which is on
+ * every refresh for a default Keycloak — and correlating a session's whole life
+ * is the entire point. Rotation stays visible through
+ * `rotatedRefreshToken` on {@link SESSION_EVENT.REFRESHED} instead.
+ */
+export declare function newSessionId(): string;
+export {};
+//# sourceMappingURL=session-events.d.ts.map

package/dist/session-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-events.d.ts","sourceRoot":"","sources":["../src/session-events.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C;;;GAGG;AACH,eAAO,MAAM,aAAa;IACxB,wFAAwF;;IAExF,iEAAiE;;IAEjE,oGAAoG;;IAEpG,uEAAuE;;IAEvE,6EAA6E;;CAErE,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,OAAO,aAAa,CAAC,CAAC;AAElF;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB;AAC/B,+DAA+D;AAC7D,mBAAmB;AACrB,mGAAmG;GACjG,oBAAoB;AACtB,2FAA2F;GACzF,sBAAsB;AACxB,qGAAqG;GACnG,kBAAkB;AACpB,uFAAuF;GACrF,gBAAgB,CAAC;AAErB;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB;AAC7B,4FAA4F;AAC1F,eAAe;AACjB,iFAAiF;GAC/E,WAAW;AACb,+FAA+F;GAC7F,WAAW,CAAC;AAEhB,qDAAqD;AACrD,MAAM,MAAM,qBAAqB;AAC/B,qDAAqD;AACnD,QAAQ;AACV,+CAA+C;GAC7C,UAAU,CAAC;AAEf,kDAAkD;AAClD,MAAM,MAAM,YAAY,GACpB;IACA,KAAK,EAAE,OAAO,aAAa,CAAC,OAAO,CAAC;IACpC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,oGAAoG;IACpG,eAAe,EAAE,OAAO,CAAC;IACzB,yFAAyF;IACzF,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iGAAiG;IACjG,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GACC;IACA,KAAK,EAAE,OAAO,aAAa,CAAC,SAAS,CAAC;IACtC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iHAAiH;IACjH,mBAAmB,EAAE,OAAO,CAAC;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GACC;IACA,KAAK,EAAE,OAAO,aAAa,CAAC,QAAQ,CAAC;IACrC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,qBAAqB,CAAC;IAC9B,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GACC;IACA,KAAK,EAAE,OAAO,aAAa,CAAC,cAAc,CAAC;IAC3C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,mBAAmB,CAAC;IAC3B,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4FAA4F;IAC5F,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GACC;IACA,KAAK,EAAE,OAAO,aAAa,CAAC,OAAO,CAAC;IACpC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,qBAAqB,CAAC;CAChC,CAAC;AAEJ,KAAK,KAAK,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAkCjD,qFAAqF;AACrF,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,YAAY,GAAG,KAAK,CAS9D;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,YAAY,GAAG,IAAI,CAQhF;AAGD,wFAAwF;AACxF,eAAO,MAAM,wBAAwB,oHAMgB,CAAC;AAEtD,qFAAqF;AACrF,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,qBAAqB,CAKtF;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IACA,KAAK,EAAE,OAAO,aAAa,CAAC,SAAS,CAAC;IACtC,MAAM,EAAE,WAAW,CAAC;IACpB,mFAAmF;IACnF,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B,GACC;IACA,KAAK,EAAE,OAAO,aAAa,CAAC,QAAQ,CAAC;IACrC,MAAM,EAAE,WAAW,GAAG,iBAAiB,CAAC;IACxC,uEAAuE;IACvE,MAAM,CAAC,EAAE,qBAAqB,CAAC;CAChC,GACC;IACA,KAAK,EAAE,OAAO,aAAa,CAAC,cAAc,CAAC;IAC3C,MAAM,EAAE,WAAW,CAAC;IACpB,4FAA4F;IAC5F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEJ;;;;;;;;GAQG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAIrC"}

package/dist/session-events.js

@@ -0,0 +1,96 @@
+//#region src/session-events.ts
+/**
+* Event names. Use these constants rather than string literals so a rename is a
+* compile error at every call site instead of a silently broken dashboard.
+*/
+var SESSION_EVENT = {
+	/** A session was created from a token response (login, or client-credentials grant). */
+	CREATED: "session.created",
+	/** An existing session was renewed with a fresh access token. */
+	REFRESHED: "session.refreshed",
+	/** A request could not proceed with the session it had. Carries a {@link SessionRejectedReason}. */
+	REJECTED: "session.rejected",
+	/** A refresh attempt failed. Carries a {@link RefreshFailureCause}. */
+	REFRESH_FAILED: "session.refresh_failed",
+	/** Session cookies were deleted. Carries a {@link SessionClearedTrigger}. */
+	CLEARED: "session.cleared"
+};
+/**
+* Level per reason rather than per event.
+*
+* A single level for the whole event would be wrong in both directions: an
+* anonymous request hitting a protected route is not a warning, and a session
+* cookie that won't decrypt is not routine. Getting this wrong is how a warn
+* stream becomes unreadable and operators conclude there is "nothing in the logs".
+*/
+var REJECTED_LEVEL = {
+	no_session_cookie: "debug",
+	stale_legacy_session: "info",
+	refresh_failed: "info",
+	unreadable_session: "warn",
+	no_refresh_token: "warn"
+};
+/** Only `invalid_grant` is business as usual; the rest are someone's infrastructure failing. */
+var REFRESH_FAILED_LEVEL = {
+	invalid_grant: "info",
+	transport: "warn",
+	idp_error: "error"
+};
+/** Human-readable message per event; the machine-readable truth is in the fields. */
+var MESSAGE = {
+	[SESSION_EVENT.CREATED]: "Session created",
+	[SESSION_EVENT.REFRESHED]: "Session refreshed",
+	[SESSION_EVENT.REJECTED]: "Session rejected",
+	[SESSION_EVENT.REFRESH_FAILED]: "Session refresh failed",
+	[SESSION_EVENT.CLEARED]: "Session cleared"
+};
+/** Resolves the level for an event, applying the per-reason and per-cause policy. */
+function sessionEventLevel(payload) {
+	switch (payload.event) {
+		case SESSION_EVENT.REJECTED: return REJECTED_LEVEL[payload.reason] ?? "warn";
+		case SESSION_EVENT.REFRESH_FAILED: return REFRESH_FAILED_LEVEL[payload.cause] ?? "error";
+		default: return "info";
+	}
+}
+/**
+* Emits one lifecycle event at the level the policy dictates.
+*
+* Call sites pass data, never a level or a message — that is what keeps the
+* vocabulary consistent across modules and makes a dashboard built on `event`
+* and `reason` keep working.
+*/
+function logSessionEvent(logger, payload) {
+	const level = sessionEventLevel(payload);
+	const fields = Object.fromEntries(Object.entries(payload).filter(([, value]) => value !== void 0));
+	logger[level](fields, MESSAGE[payload.event]);
+}
+/** The reasons, as a runtime list — for validating values that arrive over the wire. */
+var SESSION_REJECTED_REASONS = [
+	"no_session_cookie",
+	"unreadable_session",
+	"stale_legacy_session",
+	"no_refresh_token",
+	"refresh_failed"
+];
+/** Narrows an untrusted value (a response body, a query param) to a known reason. */
+function isSessionRejectedReason(value) {
+	return typeof value === "string" && SESSION_REJECTED_REASONS.includes(value);
+}
+/**
+* Mints a session correlation id: 16 hex characters (64 bits).
+*
+* Deliberately random rather than derived from the refresh token. A hash of the
+* refresh token would change every time the provider rotates it — which is on
+* every refresh for a default Keycloak — and correlating a session's whole life
+* is the entire point. Rotation stays visible through
+* `rotatedRefreshToken` on {@link SESSION_EVENT.REFRESHED} instead.
+*/
+function newSessionId() {
+	const bytes = /* @__PURE__ */ new Uint8Array(8);
+	crypto.getRandomValues(bytes);
+	return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+//#endregion
+export { SESSION_EVENT, SESSION_REJECTED_REASONS, isSessionRejectedReason, logSessionEvent, newSessionId, sessionEventLevel };
+
+//# sourceMappingURL=session-events.js.map

package/dist/session-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-events.js","names":[],"sources":["../src/session-events.ts"],"sourcesContent":["// session-events.ts\n//\n// The log vocabulary fides-auth emits for the session lifecycle. Every point\n// where the library creates a session, renews one, or decides one cannot\n// proceed emits exactly one event from this module — so a production operator\n// can answer \"which path ended this session?\" from logs alone, without reading\n// library source.\n//\n// Naming: `<area>.<outcome>`, dotted and past tense. Dotted so a dashboard can\n// match a whole area with a prefix (`event=~\"session\\..*\"`), past tense because\n// every event records something that already happened.\n//\n// The fields are deliberately low-cardinality except `sid` — see docs/session-events.md\n// for the dashboard/alerting contract.\n\nimport type { FidesLogger } from './logger';\n\n/**\n * Event names. Use these constants rather than string literals so a rename is a\n * compile error at every call site instead of a silently broken dashboard.\n */\nexport const SESSION_EVENT = {\n  /** A session was created from a token response (login, or client-credentials grant). */\n  CREATED: 'session.created',\n  /** An existing session was renewed with a fresh access token. */\n  REFRESHED: 'session.refreshed',\n  /** A request could not proceed with the session it had. Carries a {@link SessionRejectedReason}. */\n  REJECTED: 'session.rejected',\n  /** A refresh attempt failed. Carries a {@link RefreshFailureCause}. */\n  REFRESH_FAILED: 'session.refresh_failed',\n  /** Session cookies were deleted. Carries a {@link SessionClearedTrigger}. */\n  CLEARED: 'session.cleared',\n} as const;\n\nexport type SessionEventName = (typeof SESSION_EVENT)[keyof typeof SESSION_EVENT];\n\n/**\n * Why a session could not be used for a request.\n *\n * One vocabulary for the whole package, so a proxy, a status route and the\n * heartbeat endpoint all report the same word for the same situation.\n */\nexport type SessionRejectedReason =\n  /** No session cookie was sent. The ordinary anonymous case. */\n  | 'no_session_cookie'\n  /** A session cookie was sent but did not decrypt or validate — corruption, or a rotated secret. */\n  | 'unreadable_session'\n  /** A pre-split single-cookie session. Dropped rather than migrated; costs one re-login. */\n  | 'stale_legacy_session'\n  /** The session decoded but carries no refresh token — usually `offline_access` was never granted. */\n  | 'no_refresh_token'\n  /** The refresh token was rejected by the provider. See {@link RefreshFailureCause}. */\n  | 'refresh_failed';\n\n/**\n * Why a refresh attempt failed.\n *\n * The distinction that matters operationally: only `invalid_grant` means the\n * user must log in again. The other two are infrastructure faults where the\n * session is probably still fine, and logging the user out would be wrong.\n */\nexport type RefreshFailureCause =\n  /** The provider rejected the refresh token: expired, revoked, or already used. Terminal. */\n  | 'invalid_grant'\n  /** The provider was never reached — DNS, TCP, TLS, timeout, abort. Retryable. */\n  | 'transport'\n  /** The provider was reached but answered with an error or something unparseable. Retryable. */\n  | 'idp_error';\n\n/** What caused the session cookies to be deleted. */\nexport type SessionClearedTrigger =\n  /** The user (or the app) logged out deliberately. */\n  | 'logout'\n  /** The session was unusable and cleaned up. */\n  | 'rejected';\n\n/** Structured payload for one lifecycle event. */\nexport type SessionEvent =\n  | {\n    event: typeof SESSION_EVENT.CREATED;\n    sid?: string;\n    /** False here guarantees logouts at access-token TTL — the single most useful login-time signal. */\n    hasRefreshToken: boolean;\n    /** Scopes the provider actually granted, which is not necessarily what was requested. */\n    scopes?: string[];\n    /** Seconds until the access token expires. */\n    expiresIn?: number;\n    /** Total bytes written across the session cookies. Near ~4096 means a session about to break. */\n    cookieBytes?: number;\n  }\n  | {\n    event: typeof SESSION_EVENT.REFRESHED;\n    sid?: string;\n    expiresIn?: number;\n    /** True when the provider issued a new refresh token. Rotation turns a lost cookie write into a dead session. */\n    rotatedRefreshToken: boolean;\n    cookieBytes?: number;\n  }\n  | {\n    event: typeof SESSION_EVENT.REJECTED;\n    sid?: string;\n    reason: SessionRejectedReason;\n    /** Which component made the call, e.g. 'heartbeat'. */\n    source?: string;\n  }\n  | {\n    event: typeof SESSION_EVENT.REFRESH_FAILED;\n    sid?: string;\n    cause: RefreshFailureCause;\n    /** HTTP status from the provider, when it answered at all. */\n    status?: number;\n    /** Expiry of the access token we were trying to replace — how long the session had left. */\n    accessTokenExpiresAt?: string;\n    error?: unknown;\n  }\n  | {\n    event: typeof SESSION_EVENT.CLEARED;\n    sid?: string;\n    trigger: SessionClearedTrigger;\n  };\n\ntype Level = 'debug' | 'info' | 'warn' | 'error';\n\n/**\n * Level per reason rather than per event.\n *\n * A single level for the whole event would be wrong in both directions: an\n * anonymous request hitting a protected route is not a warning, and a session\n * cookie that won't decrypt is not routine. Getting this wrong is how a warn\n * stream becomes unreadable and operators conclude there is \"nothing in the logs\".\n */\nconst REJECTED_LEVEL: Record<SessionRejectedReason, Level> = {\n  no_session_cookie: 'debug',\n  stale_legacy_session: 'info',\n  refresh_failed: 'info',\n  unreadable_session: 'warn',\n  no_refresh_token: 'warn',\n};\n\n/** Only `invalid_grant` is business as usual; the rest are someone's infrastructure failing. */\nconst REFRESH_FAILED_LEVEL: Record<RefreshFailureCause, Level> = {\n  invalid_grant: 'info',\n  transport: 'warn',\n  idp_error: 'error',\n};\n\n/** Human-readable message per event; the machine-readable truth is in the fields. */\nconst MESSAGE: Record<SessionEventName, string> = {\n  [SESSION_EVENT.CREATED]: 'Session created',\n  [SESSION_EVENT.REFRESHED]: 'Session refreshed',\n  [SESSION_EVENT.REJECTED]: 'Session rejected',\n  [SESSION_EVENT.REFRESH_FAILED]: 'Session refresh failed',\n  [SESSION_EVENT.CLEARED]: 'Session cleared',\n};\n\n/** Resolves the level for an event, applying the per-reason and per-cause policy. */\nexport function sessionEventLevel(payload: SessionEvent): Level {\n  switch (payload.event) {\n    case SESSION_EVENT.REJECTED:\n      return REJECTED_LEVEL[payload.reason] ?? 'warn';\n    case SESSION_EVENT.REFRESH_FAILED:\n      return REFRESH_FAILED_LEVEL[payload.cause] ?? 'error';\n    default:\n      return 'info';\n  }\n}\n\n/**\n * Emits one lifecycle event at the level the policy dictates.\n *\n * Call sites pass data, never a level or a message — that is what keeps the\n * vocabulary consistent across modules and makes a dashboard built on `event`\n * and `reason` keep working.\n */\nexport function logSessionEvent(logger: FidesLogger, payload: SessionEvent): void {\n  const level = sessionEventLevel(payload);\n  // Undefined fields are dropped so absent data doesn't render as `\"sid\":null`\n  // and pollute label sets in the log backend.\n  const fields = Object.fromEntries(\n    Object.entries(payload).filter(([, value]) => value !== undefined),\n  );\n  logger[level](fields, MESSAGE[payload.event]);\n}\n\n\n/** The reasons, as a runtime list — for validating values that arrive over the wire. */\nexport const SESSION_REJECTED_REASONS = [\n  'no_session_cookie',\n  'unreadable_session',\n  'stale_legacy_session',\n  'no_refresh_token',\n  'refresh_failed',\n] as const satisfies readonly SessionRejectedReason[];\n\n/** Narrows an untrusted value (a response body, a query param) to a known reason. */\nexport function isSessionRejectedReason(value: unknown): value is SessionRejectedReason {\n  return (\n    typeof value === 'string' &&\n    (SESSION_REJECTED_REASONS as readonly string[]).includes(value)\n  );\n}\n\n/**\n * Browser-side counterpart of {@link SessionEvent}.\n *\n * Same names and same `reason` vocabulary as the server events, so a consumer\n * that beacons these to its own endpoint gets one queryable stream across both\n * halves of a session. The shapes differ where the browser genuinely knows\n * less: it never learns *why* a refresh failed server-side, only the status it\n * got back, so there is no `cause` here to invent.\n */\nexport type SessionClientEvent =\n  | {\n    event: typeof SESSION_EVENT.REFRESHED;\n    source: 'heartbeat';\n    /** Epoch ms of the new access-token expiry, or null when the server didn't say. */\n    expiresAt: number | null;\n  }\n  | {\n    event: typeof SESSION_EVENT.REJECTED;\n    source: 'heartbeat' | 'session-monitor';\n    /** The server's own reason when it sent one; absent when it didn't. */\n    reason?: SessionRejectedReason;\n  }\n  | {\n    event: typeof SESSION_EVENT.REFRESH_FAILED;\n    source: 'heartbeat';\n    /** HTTP status, when there was a response at all. Absent means the request never landed. */\n    status?: number;\n    /** 1 for the first consecutive failure, 2 for the next, and so on. */\n    attempt: number;\n    error?: string;\n  };\n\n/**\n * Mints a session correlation id: 16 hex characters (64 bits).\n *\n * Deliberately random rather than derived from the refresh token. A hash of the\n * refresh token would change every time the provider rotates it — which is on\n * every refresh for a default Keycloak — and correlating a session's whole life\n * is the entire point. Rotation stays visible through\n * `rotatedRefreshToken` on {@link SESSION_EVENT.REFRESHED} instead.\n */\nexport function newSessionId(): string {\n  const bytes = new Uint8Array(8);\n  crypto.getRandomValues(bytes);\n  return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');\n}\n"],"mappings":";;;;;AAqBA,IAAa,gBAAgB;;CAE3B,SAAS;;CAET,WAAW;;CAEX,UAAU;;CAEV,gBAAgB;;CAEhB,SAAS;AACX;;;;;;;;;AAmGA,IAAM,iBAAuD;CAC3D,mBAAmB;CACnB,sBAAsB;CACtB,gBAAgB;CAChB,oBAAoB;CACpB,kBAAkB;AACpB;;AAGA,IAAM,uBAA2D;CAC/D,eAAe;CACf,WAAW;CACX,WAAW;AACb;;AAGA,IAAM,UAA4C;EAC/C,cAAc,UAAU;EACxB,cAAc,YAAY;EAC1B,cAAc,WAAW;EACzB,cAAc,iBAAiB;EAC/B,cAAc,UAAU;AAC3B;;AAGA,SAAgB,kBAAkB,SAA8B;CAC9D,QAAQ,QAAQ,OAAhB;EACE,KAAK,cAAc,UACjB,OAAO,eAAe,QAAQ,WAAW;EAC3C,KAAK,cAAc,gBACjB,OAAO,qBAAqB,QAAQ,UAAU;EAChD,SACE,OAAO;CACX;AACF;;;;;;;;AASA,SAAgB,gBAAgB,QAAqB,SAA6B;CAChF,MAAM,QAAQ,kBAAkB,OAAO;CAGvC,MAAM,SAAS,OAAO,YACpB,OAAO,QAAQ,OAAO,CAAC,CAAC,QAAQ,GAAG,WAAW,UAAU,KAAA,CAAS,CACnE;CACA,OAAO,MAAM,CAAC,QAAQ,QAAQ,QAAQ,MAAM;AAC9C;;AAIA,IAAa,2BAA2B;CACtC;CACA;CACA;CACA;CACA;AACF;;AAGA,SAAgB,wBAAwB,OAAgD;CACtF,OACE,OAAO,UAAU,YAChB,yBAA+C,SAAS,KAAK;AAElE;;;;;;;;;;AA2CA,SAAgB,eAAuB;CACrC,MAAM,wBAAQ,IAAI,WAAW,CAAC;CAC9B,OAAO,gBAAgB,KAAK;CAC5B,OAAO,MAAM,KAAK,QAAQ,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,GAAG,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE;AAC1E"}

package/dist/silent-login.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"silent-login.d.ts","sourceRoot":"","sources":["../src/silent-login.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAItC,MAAM,WAAW,kBAAkB;IACjC,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,iBAAiB;IAChC,0CAA0C;IAC1C,OAAO,EAAE,OAAO,CAAC;IACjB,6DAA6D;IAC7D,gBAAgB,CAAC,EAAE,GAAG,CAAC;IACvB,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,WAAW,EACnB,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,GAAG,CAAC,CAoCd;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,GAAG,GAAG,iBAAiB,CA4B1E;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB;;;;;CAKpB,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,OAAO,iBAAiB,CAAC,MAAM,OAAO,iBAAiB,CAAC,CAAC;AAExF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAI3E"}
+{"version":3,"file":"silent-login.d.ts","sourceRoot":"","sources":["../src/silent-login.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAKtC,MAAM,WAAW,kBAAkB;IACjC,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,iBAAiB;IAChC,0CAA0C;IAC1C,OAAO,EAAE,OAAO,CAAC;IACjB,6DAA6D;IAC7D,gBAAgB,CAAC,EAAE,GAAG,CAAC;IACvB,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,WAAW,EACnB,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,GAAG,CAAC,CA+Bd;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,GAAG,GAAG,iBAAiB,CA4B1E;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB;;;;;CAKpB,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,OAAO,iBAAiB,CAAC,MAAM,OAAO,iBAAiB,CAAC,CAAC;AAExF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAI3E"}

package/dist/silent-login.js

@@ -1,4 +1,5 @@
 import { createLogger } from "./logger.js";
+import { discoverConfiguration } from "./oidc-discovery.js";
 import * as openid from "openid-client";
 //#region src/silent-login.ts
 /**
@@ -35,7 +36,7 @@ var logger = createLogger({ namespace: "fides-auth:silent-login" });
 async function buildSilentLoginUrl(config, options = {}) {
 	logger.debug({ issuer: config.issuer }, "Building silent login URL");
 	try {
-		const server = await openid.discovery(new URL(config.issuer), config.clientId, config.clientSecret, openid.ClientSecretPost(config.clientSecret));
+		const server = await discoverConfiguration(config);
 		const parameters = {
 			redirect_uri: config.redirect_uri,
 			scope: config.scope,

package/dist/silent-login.js.map

@@ -1 +1 @@
-{"version":3,"file":"silent-login.js","names":[],"sources":["../src/silent-login.ts"],"sourcesContent":["/**\n * Silent login functionality for OAuth flows.\n *\n * Silent login (also called \"prompt=none\") attempts to authenticate the user\n * without any user interaction. This is useful for:\n * - Checking if a user has an active SSO session\n * - Refreshing authentication silently in the background\n * - Implementing \"keep me logged in\" features\n */\n\nimport * as openid from 'openid-client';\n\nimport { createLogger } from './logger';\nimport { OAuthConfig } from './oauth';\n\nconst logger = createLogger({ namespace: 'fides-auth:silent-login' });\n\nexport interface SilentLoginOptions {\n  /** Optional hint about the user's identity (e.g., email or user ID) */\n  loginHint?: string;\n  /** Maximum age of authentication in seconds */\n  maxAge?: number;\n  /** Additional parameters to pass to the authorization endpoint */\n  additionalParams?: Record<string, string>;\n}\n\nexport interface SilentLoginResult {\n  /** Whether silent login was successful */\n  success: boolean;\n  /** The authorization URL to use (only if success is true) */\n  authorizationUrl?: URL;\n  /** Error message if silent login failed */\n  error?: string;\n  /** Detailed error description from OAuth provider */\n  errorDescription?: string;\n}\n\n/**\n * Builds an authorization URL for silent authentication.\n *\n * This function creates an authorization URL with prompt=none,\n * which tells the OAuth provider to authenticate without user interaction.\n * If the user doesn't have an active session, the provider will return an error.\n *\n * @param config - OAuth configuration\n * @param options - Silent login options\n * @returns Authorization URL for silent authentication\n *\n * @example\n * ```ts\n * const silentAuthUrl = await buildSilentLoginUrl(oauthConfig, {\n *   loginHint: 'user@example.com',\n *   maxAge: 3600, // Require authentication within last hour\n * });\n *\n * // Use this URL in an iframe or hidden window\n * ```\n */\nexport async function buildSilentLoginUrl(\n  config: OAuthConfig,\n  options: SilentLoginOptions = {}\n): Promise<URL> {\n  logger.debug({ issuer: config.issuer }, 'Building silent login URL');\n\n  try {\n    const server = await openid.discovery(\n      new URL(config.issuer),\n      config.clientId,\n      config.clientSecret,\n      openid.ClientSecretPost(config.clientSecret)\n    );\n\n    const parameters: Record<string, string> = {\n      redirect_uri: config.redirect_uri,\n      scope: config.scope,\n      prompt: 'none', // Critical: tells provider to not show any UI\n      response_type: 'code',\n      ...options.additionalParams,\n    };\n\n    // Add optional parameters\n    if (options.loginHint) {\n      parameters.login_hint = options.loginHint;\n    }\n\n    if (options.maxAge !== undefined) {\n      parameters.max_age = options.maxAge.toString();\n    }\n\n    const authUrl = openid.buildAuthorizationUrl(server, parameters);\n\n    logger.info('Silent login URL built successfully');\n    return authUrl;\n  } catch (error) {\n    logger.error({ error, issuer: config.issuer }, 'Failed to build silent login URL');\n    throw error;\n  }\n}\n\n/**\n * Checks if silent login is possible by examining the callback URL.\n *\n * After redirecting to the silent login URL, the OAuth provider will redirect back\n * with either a code (success) or an error (failure). This function parses the\n * callback URL to determine the result.\n *\n * @param callbackUrl - The URL the OAuth provider redirected to\n * @returns Result indicating success or failure with details\n *\n * @example\n * ```ts\n * // In your OAuth callback handler\n * const result = checkSilentLoginResult(new URL(request.url));\n *\n * if (result.success) {\n *   // User has active SSO session, proceed with token exchange\n *   const code = new URL(request.url).searchParams.get('code');\n *   // ... exchange code for tokens\n * } else if (result.error === 'login_required') {\n *   // User needs to log in interactively\n *   redirect('/login');\n * } else {\n *   // Other error\n *   console.error(result.errorDescription);\n * }\n * ```\n */\nexport function checkSilentLoginResult(callbackUrl: URL): SilentLoginResult {\n  const error = callbackUrl.searchParams.get('error');\n  const errorDescription = callbackUrl.searchParams.get('error_description');\n  const code = callbackUrl.searchParams.get('code');\n\n  if (error) {\n    logger.info({ error, errorDescription }, 'Silent login failed with error');\n\n    return {\n      success: false,\n      error,\n      errorDescription: errorDescription ?? undefined,\n    };\n  }\n\n  if (code) {\n    logger.info('Silent login successful');\n    return {\n      success: true,\n    };\n  }\n\n  logger.warn('Silent login callback missing both code and error');\n  return {\n    success: false,\n    error: 'invalid_callback',\n    errorDescription: 'Callback URL missing both code and error parameters',\n  };\n}\n\n/**\n * Common OAuth errors returned from silent login attempts.\n *\n * These can be used to handle specific error cases:\n * - login_required: User must log in interactively\n * - interaction_required: User interaction is needed (e.g., consent)\n * - consent_required: User must grant consent\n * - account_selection_required: User must select an account\n */\nexport const SilentLoginErrors = {\n  LOGIN_REQUIRED: 'login_required',\n  INTERACTION_REQUIRED: 'interaction_required',\n  CONSENT_REQUIRED: 'consent_required',\n  ACCOUNT_SELECTION_REQUIRED: 'account_selection_required',\n} as const;\n\nexport type SilentLoginError = typeof SilentLoginErrors[keyof typeof SilentLoginErrors];\n\n/**\n * Helper to check if an error requires interactive login.\n *\n * @param error - The error code from the OAuth provider\n * @returns True if the user must log in interactively\n *\n * @example\n * ```ts\n * const result = checkSilentLoginResult(callbackUrl);\n * if (!result.success && requiresInteractiveLogin(result.error)) {\n *   // Redirect to full login page\n *   redirect('/login');\n * }\n * ```\n */\nexport function requiresInteractiveLogin(error: string | undefined): boolean {\n  if (!error) return false;\n\n  return Object.values(SilentLoginErrors).includes(error as SilentLoginError);\n}\n"],"mappings":";;;;;;;;;;;;AAeA,IAAM,SAAS,aAAa,EAAE,WAAW,0BAA0B,CAAC;;;;;;;;;;;;;;;;;;;;;;AA2CpE,eAAsB,oBACpB,QACA,UAA8B,CAAC,GACjB;CACd,OAAO,MAAM,EAAE,QAAQ,OAAO,OAAO,GAAG,2BAA2B;CAEnE,IAAI;EACF,MAAM,SAAS,MAAM,OAAO,UAC1B,IAAI,IAAI,OAAO,MAAM,GACrB,OAAO,UACP,OAAO,cACP,OAAO,iBAAiB,OAAO,YAAY,CAC7C;EAEA,MAAM,aAAqC;GACzC,cAAc,OAAO;GACrB,OAAO,OAAO;GACd,QAAQ;GACR,eAAe;GACf,GAAG,QAAQ;EACb;EAGA,IAAI,QAAQ,WACV,WAAW,aAAa,QAAQ;EAGlC,IAAI,QAAQ,WAAW,KAAA,GACrB,WAAW,UAAU,QAAQ,OAAO,SAAS;EAG/C,MAAM,UAAU,OAAO,sBAAsB,QAAQ,UAAU;EAE/D,OAAO,KAAK,qCAAqC;EACjD,OAAO;CACT,SAAS,OAAO;EACd,OAAO,MAAM;GAAE;GAAO,QAAQ,OAAO;EAAO,GAAG,kCAAkC;EACjF,MAAM;CACR;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA,SAAgB,uBAAuB,aAAqC;CAC1E,MAAM,QAAQ,YAAY,aAAa,IAAI,OAAO;CAClD,MAAM,mBAAmB,YAAY,aAAa,IAAI,mBAAmB;CACzE,MAAM,OAAO,YAAY,aAAa,IAAI,MAAM;CAEhD,IAAI,OAAO;EACT,OAAO,KAAK;GAAE;GAAO;EAAiB,GAAG,gCAAgC;EAEzE,OAAO;GACL,SAAS;GACT;GACA,kBAAkB,oBAAoB,KAAA;EACxC;CACF;CAEA,IAAI,MAAM;EACR,OAAO,KAAK,yBAAyB;EACrC,OAAO,EACL,SAAS,KACX;CACF;CAEA,OAAO,KAAK,mDAAmD;CAC/D,OAAO;EACL,SAAS;EACT,OAAO;EACP,kBAAkB;CACpB;AACF;;;;;;;;;;AAWA,IAAa,oBAAoB;CAC/B,gBAAgB;CAChB,sBAAsB;CACtB,kBAAkB;CAClB,4BAA4B;AAC9B;;;;;;;;;;;;;;;;AAmBA,SAAgB,yBAAyB,OAAoC;CAC3E,IAAI,CAAC,OAAO,OAAO;CAEnB,OAAO,OAAO,OAAO,iBAAiB,CAAC,CAAC,SAAS,KAAyB;AAC5E"}
+{"version":3,"file":"silent-login.js","names":[],"sources":["../src/silent-login.ts"],"sourcesContent":["/**\n * Silent login functionality for OAuth flows.\n *\n * Silent login (also called \"prompt=none\") attempts to authenticate the user\n * without any user interaction. This is useful for:\n * - Checking if a user has an active SSO session\n * - Refreshing authentication silently in the background\n * - Implementing \"keep me logged in\" features\n */\n\nimport * as openid from 'openid-client';\n\nimport { createLogger } from './logger';\nimport { OAuthConfig } from './oauth';\nimport { discoverConfiguration } from './oidc-discovery';\n\nconst logger = createLogger({ namespace: 'fides-auth:silent-login' });\n\nexport interface SilentLoginOptions {\n  /** Optional hint about the user's identity (e.g., email or user ID) */\n  loginHint?: string;\n  /** Maximum age of authentication in seconds */\n  maxAge?: number;\n  /** Additional parameters to pass to the authorization endpoint */\n  additionalParams?: Record<string, string>;\n}\n\nexport interface SilentLoginResult {\n  /** Whether silent login was successful */\n  success: boolean;\n  /** The authorization URL to use (only if success is true) */\n  authorizationUrl?: URL;\n  /** Error message if silent login failed */\n  error?: string;\n  /** Detailed error description from OAuth provider */\n  errorDescription?: string;\n}\n\n/**\n * Builds an authorization URL for silent authentication.\n *\n * This function creates an authorization URL with prompt=none,\n * which tells the OAuth provider to authenticate without user interaction.\n * If the user doesn't have an active session, the provider will return an error.\n *\n * @param config - OAuth configuration\n * @param options - Silent login options\n * @returns Authorization URL for silent authentication\n *\n * @example\n * ```ts\n * const silentAuthUrl = await buildSilentLoginUrl(oauthConfig, {\n *   loginHint: 'user@example.com',\n *   maxAge: 3600, // Require authentication within last hour\n * });\n *\n * // Use this URL in an iframe or hidden window\n * ```\n */\nexport async function buildSilentLoginUrl(\n  config: OAuthConfig,\n  options: SilentLoginOptions = {}\n): Promise<URL> {\n  logger.debug({ issuer: config.issuer }, 'Building silent login URL');\n\n  try {\n    const server = await discoverConfiguration(config);\n\n    const parameters: Record<string, string> = {\n      redirect_uri: config.redirect_uri,\n      scope: config.scope,\n      prompt: 'none', // Critical: tells provider to not show any UI\n      response_type: 'code',\n      ...options.additionalParams,\n    };\n\n    // Add optional parameters\n    if (options.loginHint) {\n      parameters.login_hint = options.loginHint;\n    }\n\n    if (options.maxAge !== undefined) {\n      parameters.max_age = options.maxAge.toString();\n    }\n\n    const authUrl = openid.buildAuthorizationUrl(server, parameters);\n\n    logger.info('Silent login URL built successfully');\n    return authUrl;\n  } catch (error) {\n    logger.error({ error, issuer: config.issuer }, 'Failed to build silent login URL');\n    throw error;\n  }\n}\n\n/**\n * Checks if silent login is possible by examining the callback URL.\n *\n * After redirecting to the silent login URL, the OAuth provider will redirect back\n * with either a code (success) or an error (failure). This function parses the\n * callback URL to determine the result.\n *\n * @param callbackUrl - The URL the OAuth provider redirected to\n * @returns Result indicating success or failure with details\n *\n * @example\n * ```ts\n * // In your OAuth callback handler\n * const result = checkSilentLoginResult(new URL(request.url));\n *\n * if (result.success) {\n *   // User has active SSO session, proceed with token exchange\n *   const code = new URL(request.url).searchParams.get('code');\n *   // ... exchange code for tokens\n * } else if (result.error === 'login_required') {\n *   // User needs to log in interactively\n *   redirect('/login');\n * } else {\n *   // Other error\n *   console.error(result.errorDescription);\n * }\n * ```\n */\nexport function checkSilentLoginResult(callbackUrl: URL): SilentLoginResult {\n  const error = callbackUrl.searchParams.get('error');\n  const errorDescription = callbackUrl.searchParams.get('error_description');\n  const code = callbackUrl.searchParams.get('code');\n\n  if (error) {\n    logger.info({ error, errorDescription }, 'Silent login failed with error');\n\n    return {\n      success: false,\n      error,\n      errorDescription: errorDescription ?? undefined,\n    };\n  }\n\n  if (code) {\n    logger.info('Silent login successful');\n    return {\n      success: true,\n    };\n  }\n\n  logger.warn('Silent login callback missing both code and error');\n  return {\n    success: false,\n    error: 'invalid_callback',\n    errorDescription: 'Callback URL missing both code and error parameters',\n  };\n}\n\n/**\n * Common OAuth errors returned from silent login attempts.\n *\n * These can be used to handle specific error cases:\n * - login_required: User must log in interactively\n * - interaction_required: User interaction is needed (e.g., consent)\n * - consent_required: User must grant consent\n * - account_selection_required: User must select an account\n */\nexport const SilentLoginErrors = {\n  LOGIN_REQUIRED: 'login_required',\n  INTERACTION_REQUIRED: 'interaction_required',\n  CONSENT_REQUIRED: 'consent_required',\n  ACCOUNT_SELECTION_REQUIRED: 'account_selection_required',\n} as const;\n\nexport type SilentLoginError = typeof SilentLoginErrors[keyof typeof SilentLoginErrors];\n\n/**\n * Helper to check if an error requires interactive login.\n *\n * @param error - The error code from the OAuth provider\n * @returns True if the user must log in interactively\n *\n * @example\n * ```ts\n * const result = checkSilentLoginResult(callbackUrl);\n * if (!result.success && requiresInteractiveLogin(result.error)) {\n *   // Redirect to full login page\n *   redirect('/login');\n * }\n * ```\n */\nexport function requiresInteractiveLogin(error: string | undefined): boolean {\n  if (!error) return false;\n\n  return Object.values(SilentLoginErrors).includes(error as SilentLoginError);\n}\n"],"mappings":";;;;;;;;;;;;;AAgBA,IAAM,SAAS,aAAa,EAAE,WAAW,0BAA0B,CAAC;;;;;;;;;;;;;;;;;;;;;;AA2CpE,eAAsB,oBACpB,QACA,UAA8B,CAAC,GACjB;CACd,OAAO,MAAM,EAAE,QAAQ,OAAO,OAAO,GAAG,2BAA2B;CAEnE,IAAI;EACF,MAAM,SAAS,MAAM,sBAAsB,MAAM;EAEjD,MAAM,aAAqC;GACzC,cAAc,OAAO;GACrB,OAAO,OAAO;GACd,QAAQ;GACR,eAAe;GACf,GAAG,QAAQ;EACb;EAGA,IAAI,QAAQ,WACV,WAAW,aAAa,QAAQ;EAGlC,IAAI,QAAQ,WAAW,KAAA,GACrB,WAAW,UAAU,QAAQ,OAAO,SAAS;EAG/C,MAAM,UAAU,OAAO,sBAAsB,QAAQ,UAAU;EAE/D,OAAO,KAAK,qCAAqC;EACjD,OAAO;CACT,SAAS,OAAO;EACd,OAAO,MAAM;GAAE;GAAO,QAAQ,OAAO;EAAO,GAAG,kCAAkC;EACjF,MAAM;CACR;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA,SAAgB,uBAAuB,aAAqC;CAC1E,MAAM,QAAQ,YAAY,aAAa,IAAI,OAAO;CAClD,MAAM,mBAAmB,YAAY,aAAa,IAAI,mBAAmB;CACzE,MAAM,OAAO,YAAY,aAAa,IAAI,MAAM;CAEhD,IAAI,OAAO;EACT,OAAO,KAAK;GAAE;GAAO;EAAiB,GAAG,gCAAgC;EAEzE,OAAO;GACL,SAAS;GACT;GACA,kBAAkB,oBAAoB,KAAA;EACxC;CACF;CAEA,IAAI,MAAM;EACR,OAAO,KAAK,yBAAyB;EACrC,OAAO,EACL,SAAS,KACX;CACF;CAEA,OAAO,KAAK,mDAAmD;CAC/D,OAAO;EACL,SAAS;EACT,OAAO;EACP,kBAAkB;CACpB;AACF;;;;;;;;;;AAWA,IAAa,oBAAoB;CAC/B,gBAAgB;CAChB,sBAAsB;CACtB,kBAAkB;CAClB,4BAA4B;AAC9B;;;;;;;;;;;;;;;;AAmBA,SAAgB,yBAAyB,OAAoC;CAC3E,IAAI,CAAC,OAAO,OAAO;CAEnB,OAAO,OAAO,OAAO,iBAAiB,CAAC,CAAC,SAAS,KAAyB;AAC5E"}

package/dist/types.d.ts

@@ -14,6 +14,13 @@ export interface Tokens {
 }
 /** Authenticated user session with tokens, user info, and optional custom data. */
 export interface Session<TData = Record<string, unknown>> {
+    /**
+     * Correlation id for this session, minted at creation and carried across
+     * refreshes. Logged as `sid` on every session lifecycle event so one user's
+     * login, heartbeats and eventual logout can be tied together. Absent on
+     * sessions created before this field existed.
+     */
+    sid?: string;
     tokens?: Tokens;
     user?: {
         name: string;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,MAAM,WAAW,MAAM;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kGAAkG;IAClG,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,mFAAmF;AACnF,MAAM,WAAW,OAAO,CAAC,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACtD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE;QACL,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;KAClB,CAAC;IACF,kFAAkF;IAClF,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,8DAA8D;IAC9D,IAAI,CAAC,EAAE,KAAK,CAAC;CACd;AAED,oDAAoD;AACpD,MAAM,WAAW,oBAAoB;IACnC,oEAAoE;IACpE,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,MAAM,WAAW,MAAM;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kGAAkG;IAClG,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,mFAAmF;AACnF,MAAM,WAAW,OAAO,CAAC,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACtD;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE;QACL,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;KAClB,CAAC;IACF,kFAAkF;IAClF,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,8DAA8D;IAC9D,IAAI,CAAC,EAAE,KAAK,CAAC;CACd;AAED,oDAAoD;AACpD,MAAM,WAAW,oBAAoB;IACnC,oEAAoE;IACpE,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B"}

package/docs/discovery-cache.md

@@ -0,0 +1,53 @@
+# Discovery cache
+
+Every OIDC flow needs the provider's metadata — token endpoint, authorization
+endpoint, end-session endpoint. fides-auth fetches it once per provider and
+reuses it for five minutes.
+
+## Why it matters
+
+Without a cache, a refresh is two round-trips: a GET to
+`/.well-known/openid-configuration`, then the token request. On the heartbeat
+path that happens per user every few minutes. It doubles refresh latency,
+doubles the load your provider sees, and doubles the surface on which a refresh
+can fail — a discovery blip and a token-endpoint blip are indistinguishable to
+the caller, and both end up as a `session.refresh_failed` your operators have to
+explain.
+
+Concurrent callers share one round-trip. A burst of heartbeats arriving together
+does not become a burst of discovery requests, because the cache holds the
+in-flight promise rather than waiting for a result to store.
+
+## What is cached, and for how long
+
+Keyed by issuer and client id, for five minutes. The client secret is checked on
+every lookup: rotate it and the next call rediscovers rather than authenticating
+with a credential the provider has already retired.
+
+Failures are never cached. A provider that was briefly unreachable is retried on
+the next call — caching the rejection would turn one blip into five minutes of
+downtime.
+
+The TTL bounds only how long a *metadata* change takes to be noticed. Signing
+keys are not covered by it: openid-client fetches JWKS on its own schedule, so a
+key rollover does not wait for this cache.
+
+## Changing it
+
+```ts
+import { configureDiscoveryCache, clearDiscoveryCache } from "@eventuras/fides-auth/oidc-discovery";
+
+// Shorten the window, or pass 0 to discover on every call.
+configureDiscoveryCache({ ttlMs: 60_000 });
+
+// Drop everything now — after changing provider configuration you need picked
+// up immediately.
+clearDiscoveryCache();
+```
+
+Both are process-local: the cache lives in memory, so each instance of your app
+holds its own, and a deploy starts empty.
+
+If you write tests that mock discovery, call `clearDiscoveryCache()` between
+cases. The cache is module state and will otherwise serve one test's provider
+metadata to the next.