Express

npm install express express-session openid-client

PULSEID_ISSUER=https://id.warpulse.com
PULSEID_CLIENT_ID=YOUR_CLIENT_ID
PULSEID_CLIENT_SECRET=YOUR_CLIENT_SECRET
PULSEID_REDIRECT_URI=https://bytesizedbites.example/auth/callback
# true only for a verified web app: it asks for offline_access and prompt=consent
PULSEID_OFFLINE_ACCESS=false
SESSION_SECRET=A_RANDOM_VALUE_FROM_THE_COMMAND_ABOVE

openssl rand -base64 32 | tr '+/' '-_' | tr -d '='

import express from 'express'
import session from 'express-session'
import * as client from 'openid-client'

const { PULSEID_ISSUER, PULSEID_CLIENT_ID, PULSEID_CLIENT_SECRET, PULSEID_REDIRECT_URI, SESSION_SECRET } = process.env
// Refresh tokens come with offline_access, and only a verified web app gets one.
const OFFLINE = process.env.PULSEID_OFFLINE_ACCESS === 'true'
const SCOPE = OFFLINE ? 'openid profile email offline_access' : 'openid profile email'
const REDIRECT = new URL(PULSEID_REDIRECT_URI)
const REFRESH_MARGIN_SECONDS = 60
const REFRESH_SHARE_MS = 30 * 1000

// Discovery: the endpoints and the signing keys. The client secret goes to the token endpoint with HTTP Basic
// (client_secret_basic), which is how a web app is registered.
const config = await client.discovery(new URL(PULSEID_ISSUER), PULSEID_CLIENT_ID, undefined, client.ClientSecretBasic(PULSEID_CLIENT_SECRET))

const app = express()
app.set('trust proxy', 1) // behind the proxy that ends TLS, so the secure cookie is sent

// The browser holds only an opaque session id. The tokens stay on the server. The default store keeps sessions in
// memory and forgets them on a restart: use a real store (Redis, a database) in production.
app.use(
  session({
    name: '__Host-sid',
    secret: SESSION_SECRET,
    resave: false,
    saveUninitialized: false,
    cookie: { httpOnly: true, secure: true, sameSite: 'lax', maxAge: 30 * 24 * 3600 * 1000 },
  }),
)

const regenerate = (req) => new Promise((resolve, reject) => req.session.regenerate((error) => (error ? reject(error) : resolve())))
const save = (req) => new Promise((resolve, reject) => req.session.save((error) => (error ? reject(error) : resolve())))
const escapeHtml = (text) => String(text).replace(/[&<>"']/g, (c) => '&#' + c.charCodeAt(0) + ';')
// Only ever send the person back to a path on this site: one slash, then no second slash, backslash, space or control character
// (a browser drops a tab, so "/<tab>/evil.com" would mean "//evil.com"), and one that still resolves to this origin.
const SITE = 'https://site.example'
const safePath = (value) => {
  if (typeof value !== 'string' || !/^\/(?![/\\])[^\u0000-\u0020\u007f\\]*$/.test(value)) return '/'
  return new URL(value, SITE).origin === SITE ? value : '/'
}
const expiresAt = (tokens) => Math.floor(Date.now() / 1000) + (tokens.expiresIn() ?? 600)

app.get('/auth/login', async (req, res, next) => {
  try {
    const verifier = client.randomPKCECodeVerifier()
    const state = client.randomState()
    const nonce = client.randomNonce()
    const url = client.buildAuthorizationUrl(config, {
      redirect_uri: REDIRECT.href,
      scope: SCOPE,
      // offline_access is only honoured together with prompt=consent.
      ...(OFFLINE ? { prompt: 'consent' } : {}),
      code_challenge: await client.calculatePKCECodeChallenge(verifier),
      code_challenge_method: 'S256',
      state,
      nonce,
    })
    req.session.login = { verifier, state, nonce, returnTo: safePath(req.query.returnTo) }
    await save(req) // stored before the browser leaves
    res.redirect(303, url.href)
  } catch (error) {
    next(error)
  }
})

app.get('/auth/callback', async (req, res) => {
  const login = req.session.login
  if (!login) return res.status(400).send('The sign-in expired. Start again.')
  try {
    // The registered redirect URI plus the query PulseID sent back (code, state, iss), not the Host header.
    const currentUrl = new URL(REDIRECT.href)
    currentUrl.search = new URL(req.originalUrl, REDIRECT).search

    // One call checks state, exchanges the code with the PKCE verifier and the client secret, and validates the ID token:
    // signature through the JWKS, issuer, audience, expiry and nonce. It throws on anything wrong, an error response included.
    const tokens = await client.authorizationCodeGrant(config, currentUrl, {
      pkceCodeVerifier: login.verifier,
      expectedState: login.state,
      expectedNonce: login.nonce,
      idTokenExpected: true,
    })
    const claims = tokens.claims()

    await regenerate(req) // a new session id at sign-in
    req.session.user = {
      sub: claims.sub,
      email: typeof claims.email === 'string' ? claims.email : null,
      name: typeof claims.name === 'string' ? claims.name : null,
      accessToken: tokens.access_token,
      refreshToken: tokens.refresh_token ?? null,
      accessExpires: expiresAt(tokens),
    }
    await save(req)
    res.redirect(303, login.returnTo)
  } catch (error) {
    console.error('PulseID sign-in failed:', error.code, error.message) // never the whole error: it can hold the response body
    delete req.session.login // the login secrets are good for one return
    res.status(400).send('Sign-in failed. Start again.')
  }
})

// A refresh token works once: the answer holds a new one. Use a token a second time and PulseID ends the whole sign-in.
// Requests that arrive together carry the same token, so they share one refresh. (This is one server process. With
// several, refresh behind a lock they all share.)
const refreshes = new Map()
function refreshOnce(refreshToken) {
  let pending = refreshes.get(refreshToken)
  if (!pending) {
    pending = client.refreshTokenGrant(config, refreshToken)
    refreshes.set(refreshToken, pending)
    pending.catch(() => refreshes.delete(refreshToken))
    setTimeout(() => refreshes.delete(refreshToken), REFRESH_SHARE_MS).unref()
  }
  return pending
}

// Middleware for the routes that need a signed-in person.
async function requireUser(req, res, next) {
  const user = req.session.user
  const login = '/auth/login?returnTo=' + encodeURIComponent(req.originalUrl)
  if (!user) return res.redirect(303, login)
  if (user.refreshToken && user.accessExpires - Date.now() / 1000 <= REFRESH_MARGIN_SECONDS) {
    try {
      const tokens = await refreshOnce(user.refreshToken)
      user.accessToken = tokens.access_token
      user.refreshToken = tokens.refresh_token ?? user.refreshToken
      user.accessExpires = expiresAt(tokens)
    } catch {
      // invalid_grant: the person signed out of PulseID, revoked the app, or the 30 days ended. Start again.
      return req.session.destroy(() => res.redirect(303, login))
    }
  }
  req.user = user
  next()
}

app.get('/account', requireUser, (req, res) => {
  const who = req.user.name ?? req.user.email ?? req.user.sub
  res.send('<p>Signed in as ' + escapeHtml(who) + '.</p><form action="/auth/logout" method="post"><button type="submit">Sign out</button></form>')
})

// POST only, from a form on your own site, so another site cannot sign people out.
app.post('/auth/logout', async (req, res, next) => {
  if (req.get('origin') !== REDIRECT.origin) return res.status(403).send('Forbidden')
  try {
    const refreshToken = req.session.user?.refreshToken
    // Ends the grant at PulseID. If it fails, the token still expires on its own.
    if (refreshToken) await client.tokenRevocation(config, refreshToken, { token_type_hint: 'refresh_token' }).catch(() => undefined)
    // PulseID asks the person to confirm, ends their PulseID session in this browser, and sends them back to a
    // post-logout redirect URI you registered for the app.
    const url = client.buildEndSessionUrl(config, { client_id: PULSEID_CLIENT_ID, post_logout_redirect_uri: new URL('/', REDIRECT).href })
    req.session.destroy(() => res.clearCookie('__Host-sid', { secure: true, httpOnly: true, sameSite: 'lax' }).redirect(303, url.href))
  } catch (error) {
    next(error)
  }
})

app.listen(3000)