@eventuras/fides-auth 0.11.0 → 0.13.0

package/dist/server/session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/server/session.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAQ5C,OAAO,KAAK,EAAE,oBAAoB,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAIlD,KAAK,MAAM,GAAG,MAAM,GAAG,UAAU,CAAC;AAYlC;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,CAAC,CAyBjB;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAmB7F;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAoCzB;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAQjG;AAED,mCAAmC;AACnC,wBAAsB,YAAY,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAIpE"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/server/session.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAG5C,OAAO,EACL,aAAa,EAEb,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC3B,MAAM,mBAAmB,CAAC;AAM3B,OAAO,KAAK,EAAE,oBAAoB,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAIlD,KAAK,MAAM,GAAG,MAAM,GAAG,UAAU,CAAC;AAqBlC,mEAAmE;AACnE,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,aAAa,CAAC,OAAO,GAAG,OAAO,aAAa,CAAC,SAAS,CAAC;IACtE,uGAAuG;IACvG,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,CAAC,CA6CjB;AAED,4DAA4D;AAC5D,MAAM,MAAM,iBAAiB,GACzB;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;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAmBnG;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAE7F;AAED,oCAAoC;AACpC,MAAM,MAAM,oBAAoB,GAC5B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,mBAAmB,EAAE,OAAO,CAAA;CAAE,GAC5D;IACA,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,qBAAqB,CAAC;IAC9B;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,KAAK,CAAC,EAAE,mBAAmB,CAAC;CAC7B,CAAC;AAEJ;;;;;;;;GAQG;AACH,wBAAsB,wBAAwB,CAC5C,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,oBAAoB,CAAC,CA8C/B;AAED;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAGzB;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAQjG;AAED,0FAA0F;AAC1F,MAAM,WAAW,mBAAmB;IAClC,8EAA8E;IAC9E,OAAO,CAAC,EAAE,qBAAqB,CAAC;IAChC,2EAA2E;IAC3E,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,mCAAmC;AACnC,wBAAsB,YAAY,CAChC,KAAK,EAAE,WAAW,EAClB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,IAAI,CAAC,CAYf"}

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,13 +29,38 @@ 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.
  *
- * Returns null when there is no session, the main value fails validation, or the
- * access token has expired — preserving the contract that an expired access token
- * means "no session". A corrupt access-token value is tolerated: the session is
- * returned without an access token rather than discarded.
+ * 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).

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

@@ -1 +1 @@
-{"version":3,"file":"session-cookies.d.ts","sourceRoot":"","sources":["../src/session-cookies.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAsBlC,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;;;;;;;;;;GAUG;AACH,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,iBAAiB,EACtB,MAAM,EAAE,MAAM,GAAG,UAAU,GAC1B,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CA0CzB;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

@@ -1,25 +1,9 @@
 import { createLogger } from "./logger.js";
 import { createEncryptedJWT, decryptJWT } from "./utils.js";
 import { validateSessionJwt } from "./session-validation.js";
-import { decodeJwt } from "jose";
 //#region src/session-cookies.ts
 var logger = createLogger({ namespace: "fides-auth:session-cookies" });
 /**
-* True only when the access token is a JWT carrying an `exp` claim that is in the
-* past. Mirrors {@link validateSessionJwt}: an access token we can't decode (an
-* opaque token, or one without `exp`) has unknown expiry and must NOT be treated
-* as expired — otherwise opaque tokens would silently discard the whole session.
-*/
-function accessTokenIsExpired(accessToken) {
-	try {
-		const { exp } = decodeJwt(accessToken);
-		if (typeof exp !== "number") return false;
-		return exp - Date.now() / 1e3 <= 0;
-	} catch {
-		return false;
-	}
-}
-/**
 * Encrypts a session into the three cookie values, splitting the raw access and ID
 * tokens out.
 *
@@ -45,36 +29,34 @@ 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 null when there is no session, the main value fails validation, or the
-* access token has expired — preserving the contract that an expired access token
-* means "no session". A corrupt access-token value is tolerated: the session is
-* returned without an access token rather than discarded.
+* 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;
-		if (accessToken) {
-			if (accessTokenIsExpired(accessToken)) {
-				logger.info("Access token has expired");
-				return null;
-			}
-			session.tokens = {
-				...session.tokens,
-				accessToken
-			};
-		}
+		if (accessToken) session.tokens = {
+			...session.tokens,
+			accessToken
+		};
 	} catch (error) {
 		logger.warn({ error }, "Failed to decode access-token cookie");
 	}
@@ -85,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.
@@ -105,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 { decodeJwt } from 'jose';\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/**\n * True only when the access token is a JWT carrying an `exp` claim that is in the\n * past. Mirrors {@link validateSessionJwt}: an access token we can't decode (an\n * opaque token, or one without `exp`) has unknown expiry and must NOT be treated\n * as expired — otherwise opaque tokens would silently discard the whole session.\n */\nfunction accessTokenIsExpired(accessToken: string): boolean {\n  try {\n    const { exp } = decodeJwt(accessToken);\n    if (typeof exp !== 'number') {\n      return false;\n    }\n    return exp - Date.now() / 1000 <= 0;\n  } catch {\n    return false;\n  }\n}\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 null when there is no session, the main value fails validation, or the\n * access token has expired — preserving the contract that an expired access token\n * means \"no session\". A corrupt access-token value is tolerated: the session is\n * returned without an access token rather than discarded.\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  // status === 'EXPIRED' only fires for legacy single-cookie sessions, where the\n  // access token still lives in the main value. Split sessions are checked below.\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        // Preserve the contract: a verifiably-expired access token means no\n        // session. Opaque/undecodable tokens are kept (unknown expiry).\n        if (accessTokenIsExpired(accessToken)) {\n          logger.info('Access token has expired');\n          return null;\n        }\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":";;;;;AAkBA,IAAM,SAAS,aAAa,EAAE,WAAW,6BAA6B,CAAC;;;;;;;AAQvE,SAAS,qBAAqB,aAA8B;CAC1D,IAAI;EACF,MAAM,EAAE,QAAQ,UAAU,WAAW;EACrC,IAAI,OAAO,QAAQ,UACjB,OAAO;EAET,OAAO,MAAM,KAAK,IAAI,IAAI,OAAQ;CACpC,QAAQ;EACN,OAAO;CACT;AACF;;;;;;;;AAgCA,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;;;;;;;;;;;;AAaA,eAAsB,qBACpB,KACA,QACyB;CACzB,IAAI,CAAC,IAAI,SACP,OAAO;CAGT,MAAM,EAAE,QAAQ,YAAY,MAAM,mBAAmB,IAAI,SAAS,MAAM;CAIxE,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,aAAa;GAGf,IAAI,qBAAqB,WAAW,GAAG;IACrC,OAAO,KAAK,0BAA0B;IACtC,OAAO;GACT;GACA,QAAQ,SAAS;IAAE,GAAG,QAAQ;IAAQ;GAAY;EACpD;CACF,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":"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"}

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/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"}