@payez/next-mvp 4.8.0 → 4.8.2

package/src/lib/app-slug.ts

@@ -1,228 +1,228 @@
-/**
- * App Slug Utility for `@payez/next-mvp`
- *
- * Provides app-specific namespacing for Redis keys and cookies to prevent
- * collisions when multiple MVP-based apps run on the same host (e.g., localhost).
- *
- * The slug is derived from:
- * 1. APP_SLUG environment variable (preferred)
- * 2. CLIENT_ID environment variable (fallback)
- * 3. 'payez' (default fallback)
- */
-
-let cachedSlug: string | null = null;
-
-
-/**
- * Gets the app slug for namespacing.
- * Caches the result for performance.
- */
-export function getAppSlug(): string {
-  if (cachedSlug !== null) {
-    return cachedSlug;
-  }
-
-  // Priority: APP_SLUG > CLIENT_ID > default
-  cachedSlug = process.env.APP_SLUG || process.env.CLIENT_ID || 'payez';
-  return cachedSlug;
-}
-
-/**
- * The session cookie name has TWO producers: better-auth mints `${idpConfig.clientSlug || getAppSlug()}.session-token`, while
- * the gate and every reader use getSessionCookieName() = getAppSlug() = APP_SLUG || CLIENT_ID. When the IdP's slug is known and
- * differs, the gate looks for a cookie that was never set and every better-auth (Google) session bounces to
- * /sign-in?error=SessionInvalid straight after a successful 2FA (rigpert 60743, live on :4797 with CLIENT_ID=idp-admin-ui-graft
- * against clientSlug idp_admin_ui_graft). FAIL CLOSED: refuse rather than run with two names. No IdP slug -> nothing to compare.
- */
-export function slugMismatchReason(idpClientSlug: string | null | undefined): string | null {
-  if (!idpClientSlug) return null;
-  const gateSlug = getAppSlug();
-  return idpClientSlug !== gateSlug ? `SLUG_MISMATCH: cookie=${idpClientSlug} gate=${gateSlug}` : null;
-}
-
-/**
- * rigpert 60813: when the IdP returns NO client slug for this app (an unknown client: the config fetch failed or came back
- * without one), startup must fail LOUD. Silently defaulting would run with a cookie name nobody verified against the IdP. The
- * startup path swallows a failed config fetch when BETTER_AUTH_SECRET is supplied by env, so without this an unregistered
- * CLIENT_ID (e.g. payez_idp_customer_web, absent on dev-93) would boot 'fine'.
- */
-export function assertIdpSlugKnown(idpClientSlug: string | null | undefined): void {
-  if (idpClientSlug) return;
-  throw new Error(
-    `[FATAL] The IdP returned no client slug for this app (gate slug "${getAppSlug()}"). Either CLIENT_ID/APP_SLUG names a client ` +
-      `the IdP does not know, or its config could not be fetched. Refusing to start with an unverified session cookie name.`,
-  );
-}
-
-/**
- * The health-endpoint view: a mismatch is always reportable; an UNKNOWN slug is reported only once startup has actually been
- * attempted (before that nothing is known yet and health must not go red on a pod that has not started initialising).
- */
-export function slugStateReason(idpClientSlug: string | null | undefined, startupAttempted: boolean): string | null {
-  const mismatch = slugMismatchReason(idpClientSlug);
-  if (mismatch) return mismatch;
-  if (startupAttempted && !idpClientSlug) return `SLUG_UNKNOWN: the IdP returned no client slug for this app gate=${getAppSlug()}`;
-  return null;
-}
-
-export function assertAppSlugMatchesIdp(idpClientSlug: string | null | undefined): void {
-  if (!idpClientSlug) return;
-  const gateSlug = getAppSlug();
-  if (slugMismatchReason(idpClientSlug) !== null) {
-    throw new Error(
-      `[FATAL] Session cookie name would have two sources: the IdP client slug is "${idpClientSlug}" but this app's slug ` +
-        `(APP_SLUG, else CLIENT_ID) is "${gateSlug}". better-auth would set "${idpClientSlug}.session-token" while the gate reads ` +
-        `"${gateSlug}.session-token", so every better-auth session would be rejected. Set APP_SLUG (or CLIENT_ID) to "${idpClientSlug}".`,
-    );
-  }
-}
-
-/**
- * Clears the cached slug (useful for testing).
- */
-export function clearSlugCache(): void {
-  cachedSlug = null;
-}
-
-// ============================================================================
-// Redis Key Prefixes
-// ============================================================================
-
-/**
- * Gets the prefix for session keys.
- * Format: {slug}:sess:
- */
-export function getSessionPrefix(): string {
-  return `${getAppSlug()}:sess:`;
-}
-
-/**
- * Gets the prefix for anonymous session keys.
- * Format: {slug}:anon:
- */
-export function getAnonPrefix(): string {
-  return `${getAppSlug()}:anon:`;
-}
-
-/**
- * Gets the prefix for refresh lock keys.
- * Format: {slug}:refresh_lock:
- */
-export function getRefreshLockPrefix(): string {
-  return `${getAppSlug()}:refresh_lock:`;
-}
-
-// ============================================================================
-// Cookie Names - SINGLE SOURCE OF TRUTH
-// ============================================================================
-//
-// CRITICAL: The session cookie name MUST be consistent between:
-//   1. better-auth.ts (where auth SETS the cookie)
-//   2. getToken() calls (where we READ the cookie)
-//
-// If these don't match, sessions will appear empty in one environment but
-// work in another (e.g., works on localhost but fails in production).
-//
-// The ONLY cookie name for sessions is getSessionCookieName().
-// DO NOT use environment-specific variants for reading cookies.
-// ============================================================================
-
-/**
- * THE session cookie name - SINGLE SOURCE OF TRUTH.
- *
- * This is used by:
- * - better-auth.ts (cookies.sessionToken.name)
- * - getToken() calls (cookieName parameter)
- * - getJwtCookieName() (alias for consistency)
- *
- * Format: {slug}.session-token
- */
-export function getSessionCookieName(): string {
-  return `${getAppSlug()}.session-token`;
-}
-
-/**
- * Gets the JWT cookie name for getToken() calls.
- *
- * CRITICAL: This MUST match what the auth config sets:
- * - Production: __Secure-{slug}.session-token
- * - Development: {slug}.session-token
- *
- * This is the cookie name that getToken() should use to READ the JWT.
- */
-export function getJwtCookieName(): string {
-  // Must match auth config cookies.sessionToken.name logic
-  if (process.env.NODE_ENV === 'production') {
-    return getSecureSessionCookieName();
-  }
-  return getSessionCookieName();
-}
-
-/**
- * Validates that cookie names are consistent with the auth config.
- * Call this at startup to catch mismatches early.
- */
-export function validateCookieNameConsistency(): void {
-  const jwtName = getJwtCookieName();
-  const expectedName = process.env.NODE_ENV === 'production'
-    ? getSecureSessionCookieName()
-    : getSessionCookieName();
-
-  if (jwtName !== expectedName) {
-    throw new Error(
-      `[FATAL] Cookie name mismatch detected!\n` +
-      `  getJwtCookieName() = "${jwtName}"\n` +
-      `  Expected for ${process.env.NODE_ENV} = "${expectedName}"\n` +
-      `These MUST match or sessions will fail.`
-    );
-  }
-}
-
-/**
- * Gets the __Secure- prefixed cookie name.
- *
- * WARNING: This is ONLY for clearing cookies during logout.
- * DO NOT use this for reading cookies - use getSessionCookieName().
- * Auth does NOT automatically use this prefix.
- *
- * Format: __Secure-{slug}.session-token
- */
-export function getSecureSessionCookieName(): string {
-  return `__Secure-${getAppSlug()}.session-token`;
-}
-
-/**
- * Gets the anonymous session cookie name.
- * Format: {slug}_anon_id
- */
-export function getAnonCookieName(): string {
-  return `${getAppSlug()}_anon_id`;
-}
-
-/**
- * Gets the CSRF token cookie name.
- * Format: {slug}.csrf-token
- */
-export function getCsrfCookieName(): string {
-  return `${getAppSlug()}.csrf-token`;
-}
-
-/**
- * Gets the __Host- prefixed CSRF cookie name.
- *
- * WARNING: This is ONLY for clearing cookies during logout.
- * DO NOT use this for reading cookies - use getCsrfCookieName().
- *
- * Format: __Host-{slug}.csrf-token
- */
-export function getSecureCsrfCookieName(): string {
-  return `__Host-${getAppSlug()}.csrf-token`;
-}
-
-/**
- * Gets the callback URL cookie name.
- * Format: {slug}.callback-url
- */
-export function getCallbackUrlCookieName(): string {
-  return `${getAppSlug()}.callback-url`;
-}
+/**
+ * App Slug Utility for `@payez/next-mvp`
+ *
+ * Provides app-specific namespacing for Redis keys and cookies to prevent
+ * collisions when multiple MVP-based apps run on the same host (e.g., localhost).
+ *
+ * The slug is derived from:
+ * 1. APP_SLUG environment variable (preferred)
+ * 2. CLIENT_ID environment variable (fallback)
+ * 3. 'payez' (default fallback)
+ */
+
+let cachedSlug: string | null = null;
+
+
+/**
+ * Gets the app slug for namespacing.
+ * Caches the result for performance.
+ */
+export function getAppSlug(): string {
+  if (cachedSlug !== null) {
+    return cachedSlug;
+  }
+
+  // Priority: APP_SLUG > CLIENT_ID > default
+  cachedSlug = process.env.APP_SLUG || process.env.CLIENT_ID || 'payez';
+  return cachedSlug;
+}
+
+/**
+ * The session cookie name has TWO producers: better-auth mints `${idpConfig.clientSlug || getAppSlug()}.session-token`, while
+ * the gate and every reader use getSessionCookieName() = getAppSlug() = APP_SLUG || CLIENT_ID. When the IdP's slug is known and
+ * differs, the gate looks for a cookie that was never set and every better-auth (Google) session bounces to
+ * /sign-in?error=SessionInvalid straight after a successful 2FA (rigpert 60743, live on :4797 with CLIENT_ID=idp-admin-ui-graft
+ * against clientSlug idp_admin_ui_graft). FAIL CLOSED: refuse rather than run with two names. No IdP slug -> nothing to compare.
+ */
+export function slugMismatchReason(idpClientSlug: string | null | undefined): string | null {
+  if (!idpClientSlug) return null;
+  const gateSlug = getAppSlug();
+  return idpClientSlug !== gateSlug ? `SLUG_MISMATCH: cookie=${idpClientSlug} gate=${gateSlug}` : null;
+}
+
+/**
+ * rigpert 60813: when the IdP returns NO client slug for this app (an unknown client: the config fetch failed or came back
+ * without one), startup must fail LOUD. Silently defaulting would run with a cookie name nobody verified against the IdP. The
+ * startup path swallows a failed config fetch when BETTER_AUTH_SECRET is supplied by env, so without this an unregistered
+ * CLIENT_ID (e.g. payez_idp_customer_web, absent on dev-93) would boot 'fine'.
+ */
+export function assertIdpSlugKnown(idpClientSlug: string | null | undefined): void {
+  if (idpClientSlug) return;
+  throw new Error(
+    `[FATAL] The IdP returned no client slug for this app (gate slug "${getAppSlug()}"). Either CLIENT_ID/APP_SLUG names a client ` +
+      `the IdP does not know, or its config could not be fetched. Refusing to start with an unverified session cookie name.`,
+  );
+}
+
+/**
+ * The health-endpoint view: a mismatch is always reportable; an UNKNOWN slug is reported only once startup has actually been
+ * attempted (before that nothing is known yet and health must not go red on a pod that has not started initialising).
+ */
+export function slugStateReason(idpClientSlug: string | null | undefined, startupAttempted: boolean): string | null {
+  const mismatch = slugMismatchReason(idpClientSlug);
+  if (mismatch) return mismatch;
+  if (startupAttempted && !idpClientSlug) return `SLUG_UNKNOWN: the IdP returned no client slug for this app gate=${getAppSlug()}`;
+  return null;
+}
+
+export function assertAppSlugMatchesIdp(idpClientSlug: string | null | undefined): void {
+  if (!idpClientSlug) return;
+  const gateSlug = getAppSlug();
+  if (slugMismatchReason(idpClientSlug) !== null) {
+    throw new Error(
+      `[FATAL] Session cookie name would have two sources: the IdP client slug is "${idpClientSlug}" but this app's slug ` +
+        `(APP_SLUG, else CLIENT_ID) is "${gateSlug}". better-auth would set "${idpClientSlug}.session-token" while the gate reads ` +
+        `"${gateSlug}.session-token", so every better-auth session would be rejected. Set APP_SLUG (or CLIENT_ID) to "${idpClientSlug}".`,
+    );
+  }
+}
+
+/**
+ * Clears the cached slug (useful for testing).
+ */
+export function clearSlugCache(): void {
+  cachedSlug = null;
+}
+
+// ============================================================================
+// Redis Key Prefixes
+// ============================================================================
+
+/**
+ * Gets the prefix for session keys.
+ * Format: {slug}:sess:
+ */
+export function getSessionPrefix(): string {
+  return `${getAppSlug()}:sess:`;
+}
+
+/**
+ * Gets the prefix for anonymous session keys.
+ * Format: {slug}:anon:
+ */
+export function getAnonPrefix(): string {
+  return `${getAppSlug()}:anon:`;
+}
+
+/**
+ * Gets the prefix for refresh lock keys.
+ * Format: {slug}:refresh_lock:
+ */
+export function getRefreshLockPrefix(): string {
+  return `${getAppSlug()}:refresh_lock:`;
+}
+
+// ============================================================================
+// Cookie Names - SINGLE SOURCE OF TRUTH
+// ============================================================================
+//
+// CRITICAL: The session cookie name MUST be consistent between:
+//   1. better-auth.ts (where auth SETS the cookie)
+//   2. getToken() calls (where we READ the cookie)
+//
+// If these don't match, sessions will appear empty in one environment but
+// work in another (e.g., works on localhost but fails in production).
+//
+// The ONLY cookie name for sessions is getSessionCookieName().
+// DO NOT use environment-specific variants for reading cookies.
+// ============================================================================
+
+/**
+ * THE session cookie name - SINGLE SOURCE OF TRUTH.
+ *
+ * This is used by:
+ * - better-auth.ts (cookies.sessionToken.name)
+ * - getToken() calls (cookieName parameter)
+ * - getJwtCookieName() (alias for consistency)
+ *
+ * Format: {slug}.session-token
+ */
+export function getSessionCookieName(): string {
+  return `${getAppSlug()}.session-token`;
+}
+
+/**
+ * Gets the JWT cookie name for getToken() calls.
+ *
+ * CRITICAL: This MUST match what the auth config sets:
+ * - Production: __Secure-{slug}.session-token
+ * - Development: {slug}.session-token
+ *
+ * This is the cookie name that getToken() should use to READ the JWT.
+ */
+export function getJwtCookieName(): string {
+  // Must match auth config cookies.sessionToken.name logic
+  if (process.env.NODE_ENV === 'production') {
+    return getSecureSessionCookieName();
+  }
+  return getSessionCookieName();
+}
+
+/**
+ * Validates that cookie names are consistent with the auth config.
+ * Call this at startup to catch mismatches early.
+ */
+export function validateCookieNameConsistency(): void {
+  const jwtName = getJwtCookieName();
+  const expectedName = process.env.NODE_ENV === 'production'
+    ? getSecureSessionCookieName()
+    : getSessionCookieName();
+
+  if (jwtName !== expectedName) {
+    throw new Error(
+      `[FATAL] Cookie name mismatch detected!\n` +
+      `  getJwtCookieName() = "${jwtName}"\n` +
+      `  Expected for ${process.env.NODE_ENV} = "${expectedName}"\n` +
+      `These MUST match or sessions will fail.`
+    );
+  }
+}
+
+/**
+ * Gets the __Secure- prefixed cookie name.
+ *
+ * WARNING: This is ONLY for clearing cookies during logout.
+ * DO NOT use this for reading cookies - use getSessionCookieName().
+ * Auth does NOT automatically use this prefix.
+ *
+ * Format: __Secure-{slug}.session-token
+ */
+export function getSecureSessionCookieName(): string {
+  return `__Secure-${getAppSlug()}.session-token`;
+}
+
+/**
+ * Gets the anonymous session cookie name.
+ * Format: {slug}_anon_id
+ */
+export function getAnonCookieName(): string {
+  return `${getAppSlug()}_anon_id`;
+}
+
+/**
+ * Gets the CSRF token cookie name.
+ * Format: {slug}.csrf-token
+ */
+export function getCsrfCookieName(): string {
+  return `${getAppSlug()}.csrf-token`;
+}
+
+/**
+ * Gets the __Host- prefixed CSRF cookie name.
+ *
+ * WARNING: This is ONLY for clearing cookies during logout.
+ * DO NOT use this for reading cookies - use getCsrfCookieName().
+ *
+ * Format: __Host-{slug}.csrf-token
+ */
+export function getSecureCsrfCookieName(): string {
+  return `__Host-${getAppSlug()}.csrf-token`;
+}
+
+/**
+ * Gets the callback URL cookie name.
+ * Format: {slug}.callback-url
+ */
+export function getCallbackUrlCookieName(): string {
+  return `${getAppSlug()}.callback-url`;
+}