@douvery/auth 0.3.2 → 0.4.0

package/dist/index.d.ts

@@ -454,5 +454,180 @@ declare class TokenManager {
     clearReturnTo(): Promise<void>;
     clearAll(): Promise<void>;
 }
+/**
+ * Options for createServerBridgedStorage.
+ *
+ * Use this when tokens are managed server-side (httpOnly cookies)
+ * but the OAuth/PKCE flow needs client-side ephemeral storage.
+ */
+interface ServerBridgedStorageOptions {
+    /**
+     * Name of a **non-httpOnly** cookie that holds the access token
+     * expiration timestamp (in milliseconds). Used to infer whether
+     * a valid session exists without exposing the actual tokens.
+     */
+    tokenExpirationCookie: string;
+    /**
+     * Placeholder value returned by `get()` for server-managed keys
+     * (accessToken, refreshToken). Signals to the caller that the
+     * real token exists but is not readable from JS.
+     * @default "__server_managed__"
+     */
+    serverManagedPlaceholder?: string;
+    /**
+     * Enable debug logging.
+     * @default false
+     */
+    debug?: boolean;
+}
+/**
+ * Creates a `TokenStorage` adapter for apps where **tokens are
+ * managed server-side** (e.g. httpOnly cookies set by routeLoader$/
+ * routeAction$) but the OAuth PKCE flow still needs ephemeral
+ * client-side storage for state, nonce, codeVerifier and returnTo.
+ *
+ * Behaviour per key category:
+ *
+ * | Category          | get()                                    | set() / remove() |
+ * |-------------------|------------------------------------------|-------------------|
+ * | accessToken       | returns placeholder if session is active | no-op (server)    |
+ * | refreshToken      | returns placeholder if session exists    | no-op (server)    |
+ * | idToken           | always null                              | no-op             |
+ * | expiresAt         | reads from expiration cookie             | no-op (server)    |
+ * | state/nonce/etc.  | sessionStorage                           | sessionStorage    |
+ *
+ * @example
+ * ```ts
+ * import { createServerBridgedStorage } from '@douvery/auth';
+ *
+ * const bridgedStorage = createServerBridgedStorage({
+ *   tokenExpirationCookie: 'dou_token_exp',
+ *   debug: import.meta.env.DEV,
+ * });
+ *
+ * const config: DouveryAuthConfig = {
+ *   clientId: 'my-app',
+ *   redirectUri: '/callback',
+ *   customStorage: bridgedStorage,
+ *   autoRefresh: false, // server handles refresh
+ * };
+ * ```
+ */
+declare function createServerBridgedStorage(options: ServerBridgedStorageOptions): TokenStorage;
+
+/**
+ * @douvery/auth - Session Types
+ * Framework-agnostic opaque session resolution types
+ */
+/** Configuration for the session resolver factory */
+interface SessionResolverConfig {
+    /** Auth server session API base URL (e.g. "http://localhost:9924/api/session") */
+    sessionApiUrl: string;
+    /**
+     * Internal service name for IdP UI auth via X-Douvery-Internal-Service header.
+     * Used by the IdP's own UI (like accounts.google.com) — NOT an OAuth client.
+     * Requires internalServiceSecret.
+     */
+    internalServiceName?: string;
+    /**
+     * HMAC secret for internal service auth.
+     * Signs X-Douvery-Internal-Signature: HMAC-SHA256(timestamp:serviceName, secret).
+     * Used together with internalServiceName.
+     */
+    internalServiceSecret?: string;
+    /**
+     * OAuth Client ID for consumer app auth via X-Client-Id header.
+     * For apps that ARE OAuth clients (douvery-web, center, mobile).
+     */
+    clientId?: string;
+    /**
+     * OAuth Client Secret for consumer app auth via X-Client-Secret header.
+     * Used together with clientId. Validated against oauth_clients table (Argon2).
+     */
+    clientSecret?: string;
+    /** Cookie name for the session ID (e.g. "douvery-session") */
+    cookieName: string;
+    /** Session cookie max age in seconds @default 2592000 (30 days) */
+    cookieMaxAge?: number;
+    /** Whether cookies should use the 'secure' flag @default true */
+    secureCookies?: boolean;
+    /** Timeout for lightweight session API calls like /token (ms) @default 3000 */
+    fetchTimeoutMs?: number;
+    /** Timeout for heavy session API calls like /refresh (ms) @default 8000 */
+    refreshTimeoutMs?: number;
+    /** Fallback cache TTL when JWT exp cannot be parsed (ms) @default 30000 */
+    fallbackCacheTtlMs?: number;
+    /** Enable debug logging @default false */
+    debug?: boolean;
+    /** Custom logger implementation. Defaults to console when debug is true. */
+    logger?: SessionLogger;
+}
+/**
+ * Minimal cookie adapter interface.
+ * Each framework implements this for its own cookie API (Qwik, Next.js, Express, etc).
+ *
+ * The resolver uses the adapter object reference as a WeakMap key for per-request
+ * caching. Ensure the SAME adapter instance is used for all calls within a single
+ * request to benefit from deduplication and caching.
+ */
+interface CookieAdapter {
+    /** Read a cookie value by name. Returns undefined if not found. */
+    get(name: string): string | undefined;
+    /** Set a cookie with the given name, value, and options. */
+    set(name: string, value: string, options: CookieSetOptions): void;
+}
+/** Options for setting a cookie (standard HTTP cookie attributes) */
+interface CookieSetOptions {
+    path?: string;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: "strict" | "lax" | "none";
+    maxAge?: number;
+}
+/**
+ * Result of a refresh attempt. Callers MUST distinguish between:
+ * - 'success': tokens refreshed, cache invalidated — proceed normally
+ * - 'definitive_failure': server confirmed session is dead (401/404) — safe to clear cookie
+ * - 'transient_failure': timeout/network/500 — session may still be valid, DON'T clear cookie
+ */
+type RefreshResult = "success" | "definitive_failure" | "transient_failure";
+interface SessionLogger {
+    debug(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}
+/** The public API returned by createSessionResolver() */
+interface SessionResolver {
+    /**
+     * Resolve opaque session to JWT access_token (async).
+     * Uses per-request caching and deduplication.
+     * Returns the JWT even if expired — the caller handles refresh.
+     */
+    getAccessToken(cookies: CookieAdapter): Promise<string | undefined>;
+    /**
+     * Synchronous access to cached token (for sync header builders).
+     * Returns cached value only — NO network call.
+     */
+    getAccessTokenSync(cookies: CookieAdapter): string | undefined;
+    /**
+     * Refresh session tokens via auth server.
+     * Triggers full token rotation. Deduplicates concurrent refresh calls
+     * across all requests for the same session_id.
+     */
+    refreshSession(cookies: CookieAdapter): Promise<RefreshResult>;
+    /** Destroy session on auth server and clear local cookie. */
+    destroySession(cookies: CookieAdapter): Promise<void>;
+    /** Save session ID in an HttpOnly cookie after OAuth callback. */
+    setSessionCookie(sessionId: string, cookies: CookieAdapter): void;
+    /** Read session ID from cookie. */
+    getSessionId(cookies: CookieAdapter): string | undefined;
+    /** Check if user has an active session cookie. */
+    hasSession(cookies: CookieAdapter): boolean;
+    /**
+     * Clear session cookie and invalidate cached token.
+     * Sets an expired cookie to ensure the browser removes it.
+     */
+    clearSessionCookie(cookies: CookieAdapter): void;
+}
 
-export { type AddAccountOptions, AuthError, type AuthErrorCode, type AuthEvent, type AuthEventHandler, type AuthNavigationOptions, type AuthState, type AuthStatus, type AuthUrl, type CallbackResult, CookieStorage, type DecodedIdToken, DouveryAuthClient, type DouveryAuthConfig, LocalStorage, type LoginOptions, type LogoutOptions, MemoryStorage, type OIDCDiscovery, type PKCEPair, type RecoverAccountOptions, type RegisterOptions, type RevokeTokenOptions, STORAGE_KEYS, type SelectAccountOptions, SessionStorage, type SetupAddressOptions, type SetupPasskeyOptions, type StorageKeys, type TokenInfo, TokenManager, type TokenSet, type TokenStorage, type UpgradeAccountOptions, type User, type VerifyAccountOptions, base64UrlDecode, base64UrlEncode, createDouveryAuth, createStorage, decodeJWT, generateCodeChallenge, generateCodeVerifier, generateNonce, generatePKCEPair, generateState, getTokenExpiration, isTokenExpired, verifyCodeChallenge };
+export { type AddAccountOptions, AuthError, type AuthErrorCode, type AuthEvent, type AuthEventHandler, type AuthNavigationOptions, type AuthState, type AuthStatus, type AuthUrl, type CallbackResult, type CookieAdapter, type CookieSetOptions, CookieStorage, type DecodedIdToken, DouveryAuthClient, type DouveryAuthConfig, LocalStorage, type LoginOptions, type LogoutOptions, MemoryStorage, type OIDCDiscovery, type PKCEPair, type RecoverAccountOptions, type RefreshResult, type RegisterOptions, type RevokeTokenOptions, STORAGE_KEYS, type SelectAccountOptions, type ServerBridgedStorageOptions, type SessionLogger, type SessionResolver, type SessionResolverConfig, SessionStorage, type SetupAddressOptions, type SetupPasskeyOptions, type StorageKeys, type TokenInfo, TokenManager, type TokenSet, type TokenStorage, type UpgradeAccountOptions, type User, type VerifyAccountOptions, base64UrlDecode, base64UrlEncode, createDouveryAuth, createServerBridgedStorage, createStorage, decodeJWT, generateCodeChallenge, generateCodeVerifier, generateNonce, generatePKCEPair, generateState, getTokenExpiration, isTokenExpired, verifyCodeChallenge };

package/dist/index.js

@@ -286,6 +286,113 @@ var TokenManager = class {
     await this.storage.clear();
   }
 };
+var SERVER_TOKEN_KEYS = /* @__PURE__ */ new Set([
+  STORAGE_KEYS.accessToken,
+  STORAGE_KEYS.refreshToken,
+  STORAGE_KEYS.idToken
+]);
+var PKCE_KEYS = /* @__PURE__ */ new Set([
+  STORAGE_KEYS.state,
+  STORAGE_KEYS.nonce,
+  STORAGE_KEYS.codeVerifier,
+  STORAGE_KEYS.returnTo
+]);
+function readClientCookie(name) {
+  if (typeof document === "undefined") return null;
+  const cookies = document.cookie.split(";");
+  for (const c of cookies) {
+    const [key, ...parts] = c.trim().split("=");
+    if (key === name) return decodeURIComponent(parts.join("="));
+  }
+  return null;
+}
+function safeSessionStorage() {
+  if (typeof window === "undefined" || typeof sessionStorage === "undefined") {
+    return null;
+  }
+  return sessionStorage;
+}
+function createServerBridgedStorage(options) {
+  const {
+    tokenExpirationCookie,
+    serverManagedPlaceholder = "__server_managed__",
+    debug = false
+  } = options;
+  function log(msg) {
+    if (debug) console.debug(`[ServerBridgedStorage] ${msg}`);
+  }
+  return {
+    get(key) {
+      if (key === STORAGE_KEYS.accessToken) {
+        const exp = readClientCookie(tokenExpirationCookie);
+        if (exp) {
+          const ms = parseInt(exp, 10);
+          if (!isNaN(ms) && ms > Date.now()) return serverManagedPlaceholder;
+        }
+        return null;
+      }
+      if (key === STORAGE_KEYS.refreshToken) {
+        const exp = readClientCookie(tokenExpirationCookie);
+        return exp ? serverManagedPlaceholder : null;
+      }
+      if (key === STORAGE_KEYS.idToken) return null;
+      if (key === STORAGE_KEYS.expiresAt) {
+        return readClientCookie(tokenExpirationCookie);
+      }
+      if (PKCE_KEYS.has(key)) {
+        return safeSessionStorage()?.getItem(key) ?? null;
+      }
+      return safeSessionStorage()?.getItem(key) ?? null;
+    },
+    set(key, value) {
+      if (SERVER_TOKEN_KEYS.has(key) || key === STORAGE_KEYS.expiresAt) {
+        log(`Ignoring set("${key}") \u2013 managed by server`);
+        return;
+      }
+      const ss = safeSessionStorage();
+      if (ss) {
+        try {
+          ss.setItem(key, value);
+        } catch (e) {
+          if (debug)
+            console.warn(
+              "[ServerBridgedStorage] sessionStorage.setItem failed:",
+              e
+            );
+        }
+      }
+    },
+    remove(key) {
+      if (SERVER_TOKEN_KEYS.has(key) || key === STORAGE_KEYS.expiresAt) {
+        log(`Ignoring remove("${key}") \u2013 managed by server`);
+        return;
+      }
+      const ss = safeSessionStorage();
+      if (ss) {
+        try {
+          ss.removeItem(key);
+        } catch (e) {
+          if (debug)
+            console.warn(
+              "[ServerBridgedStorage] sessionStorage.removeItem failed:",
+              e
+            );
+        }
+      }
+    },
+    clear() {
+      const ss = safeSessionStorage();
+      if (!ss) return;
+      for (const key of PKCE_KEYS) {
+        try {
+          ss.removeItem(key);
+        } catch {
+        }
+      }
+      log("PKCE ephemeral data cleared from sessionStorage");
+    }
+  };
+}
 
 // src/client.ts
 var DEFAULT_ISSUER = "https://auth.douvery.com";
@@ -303,6 +410,11 @@ var DouveryAuthClient = class {
     error: null
   };
   constructor(config) {
+    if (!config) {
+      throw new Error(
+        "[DouveryAuthClient] config is required. Make sure getDouveryAuthConfig() returns a valid DouveryAuthConfig object."
+      );
+    }
     this.config = {
       issuer: DEFAULT_ISSUER,
       scopes: DEFAULT_SCOPES,
@@ -866,6 +978,7 @@ var DouveryAuthClient = class {
   async getDiscovery() {
     if (this.discovery) return this.discovery;
     const discoveryUrl = `${this.config.issuer}/.well-known/openid-configuration`;
+    this.log("Fetching discovery from:", discoveryUrl);
     const response = await fetch(discoveryUrl);
     if (!response.ok) {
       throw new AuthError(
@@ -873,7 +986,29 @@ var DouveryAuthClient = class {
         "Failed to fetch discovery document"
       );
     }
-    this.discovery = await response.json();
+    const doc = await response.json();
+    const docIssuer = doc.issuer;
+    const configIssuer = this.config.issuer;
+    if (docIssuer && docIssuer !== configIssuer) {
+      this.log(
+        `Rewriting discovery endpoints: "${docIssuer}" -> "${configIssuer}"`
+      );
+      const rewrite = (url) => url.replace(docIssuer, configIssuer);
+      doc.issuer = configIssuer;
+      doc.authorization_endpoint = rewrite(doc.authorization_endpoint);
+      doc.token_endpoint = rewrite(doc.token_endpoint);
+      if (doc.userinfo_endpoint)
+        doc.userinfo_endpoint = rewrite(doc.userinfo_endpoint);
+      if (doc.end_session_endpoint)
+        doc.end_session_endpoint = rewrite(doc.end_session_endpoint);
+      if (doc.jwks_uri) doc.jwks_uri = rewrite(doc.jwks_uri);
+      if (doc.revocation_endpoint)
+        doc.revocation_endpoint = rewrite(doc.revocation_endpoint);
+      if (doc.introspection_endpoint)
+        doc.introspection_endpoint = rewrite(doc.introspection_endpoint);
+    }
+    this.log("authorization_endpoint:", doc.authorization_endpoint);
+    this.discovery = doc;
     return this.discovery;
   }
   setupAutoRefresh() {
@@ -931,6 +1066,6 @@ function createDouveryAuth(config) {
   return new DouveryAuthClient(config);
 }
 
-export { AuthError, CookieStorage, DouveryAuthClient, LocalStorage, MemoryStorage, STORAGE_KEYS, SessionStorage, TokenManager, base64UrlDecode, base64UrlEncode, createDouveryAuth, createStorage, decodeJWT, generateCodeChallenge, generateCodeVerifier, generateNonce, generatePKCEPair, generateState, getTokenExpiration, isTokenExpired, verifyCodeChallenge };
+export { AuthError, CookieStorage, DouveryAuthClient, LocalStorage, MemoryStorage, STORAGE_KEYS, SessionStorage, TokenManager, base64UrlDecode, base64UrlEncode, createDouveryAuth, createServerBridgedStorage, createStorage, decodeJWT, generateCodeChallenge, generateCodeVerifier, generateNonce, generatePKCEPair, generateState, getTokenExpiration, isTokenExpired, verifyCodeChallenge };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map