@blamejs/core 0.8.59 → 0.8.64

package/lib/auth/oauth.js

@@ -371,9 +371,13 @@ function create(opts) {
     revocationEndpoint:    opts.revocationEndpoint    || (preset && preset.revocationEndpoint)    || null,
     jwksUri:               opts.jwksUri               || (preset && preset.jwksUri)               || null,
     endSessionEndpoint:    opts.endSessionEndpoint    || (preset && preset.endSessionEndpoint)    || null,
+    checkSessionIframe:    opts.checkSessionIframe    || (preset && preset.checkSessionIframe)    || null,
     pushedAuthorizationRequestEndpoint:
                            opts.pushedAuthorizationRequestEndpoint ||
                            (preset && preset.pushedAuthorizationRequestEndpoint) || null,
+    backchannelAuthenticationEndpoint:
+                           opts.backchannelAuthenticationEndpoint ||
+                           (preset && preset.backchannelAuthenticationEndpoint) || null,
   };
 
   // Discovery + JWKS caches use b.cache.create + .wrap so concurrent
@@ -448,7 +452,9 @@ function create(opts) {
       revocationEndpoint:    "revocation_endpoint",
       jwksUri:               "jwks_uri",
       endSessionEndpoint:    "end_session_endpoint",
+      checkSessionIframe:    "check_session_iframe",
       pushedAuthorizationRequestEndpoint: "pushed_authorization_request_endpoint",
+      backchannelAuthenticationEndpoint:  "backchannel_authentication_endpoint",
     })[name];
     var endpoint = config[snake];
     if (!endpoint) {
@@ -744,8 +750,14 @@ function create(opts) {
     // Claim validation.
     var now = Math.floor(Date.now() / C.TIME.seconds(1));
     var skewSec = Math.floor(clockSkewMs / C.TIME.seconds(1));
-    if (typeof payload.exp !== "number" || payload.exp + skewSec < now) {
-      throw new OAuthError("auth-oauth/expired", "ID token expired (exp=" + payload.exp + ", now=" + now + ")");
+    // OIDC Back-Channel Logout 1.0 §2.4 — logout tokens have no `exp`
+    // claim; freshness comes from `iat` + jti-replay window. Operators
+    // verifying logout tokens pass `skipExpCheck: true`. ID tokens
+    // never set this and continue to require `exp`.
+    if (!vopts.skipExpCheck) {
+      if (typeof payload.exp !== "number" || payload.exp + skewSec < now) {
+        throw new OAuthError("auth-oauth/expired", "ID token expired (exp=" + payload.exp + ", now=" + now + ")");
+      }
     }
     if (typeof payload.iat === "number" && payload.iat - skewSec > now) {
       throw new OAuthError("auth-oauth/iat-future", "ID token iat is in the future");
@@ -870,16 +882,192 @@ function create(opts) {
     };
   }
 
+  // ---- OIDC Front-Channel Logout 1.0 ----
+  //
+  // The IdP renders an iframe pointing at the RP's
+  // frontchannel_logout_uri with `iss` + `sid` query params; the RP's
+  // iframe-served endpoint clears the local session for that sid and
+  // returns a no-content / blank page. Operators stand up a single
+  // /oidc/frontchannel-logout route, parse the request, and call
+  // `parseFrontchannelLogoutRequest(req)` to extract the validated
+  // (iss, sid) tuple to feed their session-store deletion.
+  //
+  // The IdP advertises support via `frontchannel_logout_supported`
+  // and `frontchannel_logout_session_required` in discovery; the RP
+  // registers `frontchannel_logout_uri` + `frontchannel_logout_session_required`
+  // at client-registration time. We don't auto-register here — the
+  // RP's registration step is operator-side; this surface only
+  // handles the runtime parse.
+  function parseFrontchannelLogoutRequest(req) {
+    if (!req || !req.url) {
+      throw new OAuthError("auth-oauth/bad-frontchannel-logout-req",
+        "parseFrontchannelLogoutRequest: req with url required");
+    }
+    var u;
+    try { u = new URL(req.url, "http://placeholder.invalid"); }                                  // allow:raw-new-url — req.url is the framework-normalized path; placeholder base provides a synthetic origin for relative-path parse
+    catch (_e) {
+      throw new OAuthError("auth-oauth/bad-frontchannel-logout-url",
+        "parseFrontchannelLogoutRequest: malformed request URL");
+    }
+    var iss = u.searchParams.get("iss");
+    var sid = u.searchParams.get("sid");
+    // RFC 0 invariant: `iss` MUST match the configured issuer when
+    // present (defends against an attacker-controlled IdP forging a
+    // logout for a session at a different IdP). `sid` is required
+    // when the RP registered with frontchannel_logout_session_required=true;
+    // we surface it either way and let the operator decide.
+    if (iss && iss !== issuer) {
+      throw new OAuthError("auth-oauth/frontchannel-logout-iss-mismatch",
+        "parseFrontchannelLogoutRequest: iss \"" + iss +
+        "\" does not match configured issuer \"" + issuer + "\"");
+    }
+    return { iss: iss || issuer, sid: sid || null };
+  }
+
+  // ---- OIDC Back-Channel Logout 1.0 ----
+  //
+  // The IdP POSTs an `application/x-www-form-urlencoded` body with
+  // `logout_token=<jwt>` to the RP's backchannel_logout_uri. The
+  // logout token is a JWT with:
+  //   header.typ = "logout+jwt"
+  //   payload.iss = the IdP issuer
+  //   payload.aud = the RP's client_id
+  //   payload.iat = recent timestamp
+  //   payload.jti = unique id (replay-cache key)
+  //   payload.events = { "http://schemas.openid.net/event/backchannel-logout": {} }
+  //   payload.sub OR payload.sid (one of)
+  //   MUST NOT contain `nonce`
+  //
+  // The RP verifies the JWS using the IdP's JWKS, validates each
+  // claim, and destroys every session for the matching sub or sid.
+  //
+  // Replay defense: operators provide a `seen({jti, iat}) -> Promise<bool>`
+  // callback that returns true the FIRST time it sees a (jti, iss)
+  // pair within the operator's chosen window (typical: 5 minutes).
+  // Subsequent calls with the same (jti, iss) return false and the
+  // RP rejects the duplicate. The framework does not maintain the
+  // store — operators wire b.cache or b.db.
+  async function verifyBackchannelLogoutToken(logoutToken, vopts) {
+    vopts = vopts || {};
+    if (typeof logoutToken !== "string" || logoutToken.length === 0) {
+      throw new OAuthError("auth-oauth/bad-logout-token",
+        "verifyBackchannelLogoutToken: logoutToken must be a non-empty string");
+    }
+    var parts = logoutToken.split(".");
+    if (parts.length !== 3) {
+      throw new OAuthError("auth-oauth/malformed-logout-token",
+        "verifyBackchannelLogoutToken: logout_token must be a 3-segment JWS");
+    }
+    var headerObj;
+    try { headerObj = JSON.parse(Buffer.from(parts[0], "base64url").toString("utf8")); }         // allow:bare-json-parse — pre-verify header parse to look up the typ; the JWS signature is verified by verifyIdToken below
+    catch (_e) {
+      throw new OAuthError("auth-oauth/bad-logout-header",
+        "verifyBackchannelLogoutToken: malformed header");
+    }
+    if (headerObj.typ !== "logout+jwt") {
+      throw new OAuthError("auth-oauth/wrong-typ",
+        "verifyBackchannelLogoutToken: header.typ must be \"logout+jwt\" (got \"" +
+        headerObj.typ + "\")");
+    }
+    // Reuse verifyIdToken's signature-verification path. It looks up
+    // the IdP JWKS and checks the JWS — same trust anchor.
+    var verified = await verifyIdToken(logoutToken, {
+      issuer:         issuer,
+      clientId:       clientId,
+      acceptedAlgs:   vopts.acceptedAlgs,
+      jwksUri:        vopts.jwksUri,
+      maxClockSkewMs: vopts.maxClockSkewMs,
+      // Logout tokens have no nonce — disable the nonce check that
+      // verifyIdToken would otherwise enforce on id_tokens.
+      skipNonceCheck: true,
+      // Logout tokens have no exp claim per OIDC Back-Channel Logout
+      // §2.4 — the freshness gate is iat + jti-replay window.
+      skipExpCheck:   true,
+    });
+    var claims = verified.claims;
+
+    // §2.6 — events claim presence + correct shape
+    if (!claims.events || typeof claims.events !== "object" ||
+        !claims.events["http://schemas.openid.net/event/backchannel-logout"]) {
+      throw new OAuthError("auth-oauth/missing-logout-event",
+        "verifyBackchannelLogoutToken: payload.events missing http://schemas.openid.net/event/backchannel-logout");
+    }
+    // §2.6 — nonce MUST NOT be present (nonce is for ID tokens only)
+    if (Object.prototype.hasOwnProperty.call(claims, "nonce")) {
+      throw new OAuthError("auth-oauth/forbidden-nonce",
+        "verifyBackchannelLogoutToken: payload.nonce is forbidden in logout tokens (§2.6)");
+    }
+    // §2.4 — sub OR sid REQUIRED (at least one)
+    if (!claims.sub && !claims.sid) {
+      throw new OAuthError("auth-oauth/no-sub-or-sid",
+        "verifyBackchannelLogoutToken: payload must include sub or sid");
+    }
+    // Replay defense — operator-supplied jti store
+    if (typeof vopts.seen === "function") {
+      if (typeof claims.jti !== "string" || claims.jti.length === 0) {
+        throw new OAuthError("auth-oauth/no-jti",
+          "verifyBackchannelLogoutToken: jti required when a seen() callback is configured");
+      }
+      var first;
+      try { first = await vopts.seen({ jti: claims.jti, iss: claims.iss, iat: claims.iat }); }
+      catch (e) {
+        throw new OAuthError("auth-oauth/seen-callback-failed",
+          "verifyBackchannelLogoutToken: seen() callback threw: " + ((e && e.message) || String(e)));
+      }
+      if (first === false) {
+        throw new OAuthError("auth-oauth/logout-token-replay",
+          "verifyBackchannelLogoutToken: jti already seen — replay refused");
+      }
+    }
+    return {
+      iss:    claims.iss,
+      aud:    claims.aud,
+      sub:    claims.sub || null,
+      sid:    claims.sid || null,
+      jti:    claims.jti || null,
+      iat:    claims.iat || null,
+      events: claims.events,
+      claims: claims,
+    };
+  }
+
+  // ---- OIDC Session Management 1.0 — check_session_iframe ----
+  //
+  // The IdP advertises a `check_session_iframe` URL in discovery.
+  // The RP loads it inside an iframe and posts `<client_id>
+  // <session_state>` messages to it; the iframe responds with
+  // "changed" / "unchanged" / "error" so the RP can periodically
+  // poll without a full network round-trip.
+  //
+  // This builder returns the iframe URL plus a small client-side
+  // helper string operators embed in their HTML to drive the
+  // postMessage handshake. The framework does not host the iframe —
+  // the IdP does. Operators that want CSP-compliant inline scripts
+  // emit the helper through the framework's nonce middleware.
+  async function checkSessionIframeUrl() {
+    var url;
+    try { url = await _resolveEndpoint("checkSessionIframe"); }
+    catch (_e) {
+      throw new OAuthError("auth-oauth/no-check-session-iframe",
+        "checkSessionIframeUrl: IdP discovery doc has no check_session_iframe " +
+        "(set opts.checkSessionIframe on create() if the IdP doesn't publish it)");
+    }
+    return url;
+  }
+
   return {
-    authorizationUrl:    authorizationUrl,
-    exchangeCode:        exchangeCode,
-    refreshAccessToken:  refreshAccessToken,
-    fetchUserInfo:       fetchUserInfo,
-    revokeToken:         revokeToken,
-    verifyIdToken:       verifyIdToken,
-    discover:            _discover,
-    endSessionUrl:           endSessionUrl,
-    pushAuthorizationRequest: pushAuthorizationRequest,
+    authorizationUrl:                authorizationUrl,
+    exchangeCode:                    exchangeCode,
+    refreshAccessToken:              refreshAccessToken,
+    fetchUserInfo:                   fetchUserInfo,
+    revokeToken:                     revokeToken,
+    verifyIdToken:                   verifyIdToken,
+    discover:                        _discover,
+    endSessionUrl:                   endSessionUrl,
+    pushAuthorizationRequest:        pushAuthorizationRequest,
+    parseFrontchannelLogoutRequest:  parseFrontchannelLogoutRequest,
+    verifyBackchannelLogoutToken:    verifyBackchannelLogoutToken,
+    checkSessionIframeUrl:           checkSessionIframeUrl,
     // Diagnostic / power-user surface
     issuer:              issuer,
     clientId:            clientId,