@opengovsg/mockpass 4.0.11 → 4.1.0

package/.husky/pre-push

@@ -1,4 +1,4 @@
 #!/bin/sh
 . "$(dirname "$0")/_/husky.sh"
 
-npx commitlint --from origin/master --to HEAD --verbose
+npx commitlint --from origin/main --to HEAD --verbose

package/README.md

@@ -1,107 +1,186 @@
 # MockPass
 
-[![Gitpod Ready-to-Code](https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod)](https://gitpod.io/#https://github.com/opengovsg/mockpass)
+A mock Singpass/Corppass/Myinfo v3/sgID v2 server for dev purposes
 
-A mock SingPass/CorpPass/MyInfo server for dev purposes
+## Quick Start (hosted remotely on Gitpod)
 
-## Quick Start (hosted by Gitpod)
+[![Gitpod Ready-to-Code](https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod)](https://gitpod.io/#https://github.com/opengovsg/mockpass)
 
 - Click the ready-to-code badge above
 - Wait for MockPass to start
 - Make port 5156 public
-- Open Browser to note the URL hosting MockPass
+- Open browser to note the URL hosting MockPass
 - Configure your application per local machine quick start, changing
-  the localhost:5156 to the Gitpod hostname
+  the `localhost:5156` to the Gitpod hostname
+
+## Quick Start (hosted locally)
+
+### Singpass v2 (NDI OIDC)
+
+Configure your application to point to the following endpoints:
+
+- http://localhost:5156/singpass/v2/.well-known/openid-configuration
+- http://localhost:5156/singpass/v2/.well-known/keys
+- http://localhost:5156/singpass/v2/authorize
+- http://localhost:5156/singpass/v2/token
+
+Configure your application (or MockPass) with keys:
+
+- EITHER configure MockPass with your application's JWKS endpoint URL using the env
+ var `SP_RP_JWKS_ENDPOINT`.
+- OR configure your application to use the private keys from
+  `static/certs/oidc-v2-rp-secret.json`.
+
+MockPass accepts any value for `client_id` and `redirect_uri`.
+
+| Configuration item | Explanation |
+|---|---|
+| Client signing and encryption keys | **Overview:** When client makes any request, what signing key is used to verify the client's signature on the client assertion, and what encryption key is used to encrypt the data payload. <br> **Default:** static keyset `static/certs/oidc-v2-rp-public.json` is used. <br> **How to configure:** Set the env var `SP_RP_JWKS_ENDPOINT` to a JWKS URL that MockPass can connect to. This can be a HTTP or HTTPS URL. |
+| Login page | **Overview:** When client makes an authorize request, whether MockPass sends the client to a login page, instead of completing the login silently. <br> **Default:** Disabled for all requests. <br> **How to configure:** Enable for all requests by default by setting the env var `SHOW_LOGIN_PAGE` to `true`. Regardless of the default, you can override on a per-request basis by sending the HTTP request header `X-Show-Login-Page` with the value `true`. <br> **Detailed effect:** When login page is disabled, MockPass will immediately complete login and redirect to the `redirect_uri`. The profile used will be (in order of decreasing precedence) the profile specified in HTTP request headers (`X-Custom-NRIC` and `X-Custom-UUID` must both be specified), the profile with the NRIC specified in the env var `MOCKPASS_NRIC`, or the first profile in MockPass' static data. <br> When login page is enabled, MockPass returns a HTML page with a form that is used to complete the login. The client may select an existing profile, or provide a custom NRIC and UUID on the form. |
+
+### Corppass v2 (Corppass OIDC)
+
+Configure your application to point to the following endpoints:
+
+- http://localhost:5156/corppass/v2/.well-known/openid-configuration
+- http://localhost:5156/corppass/v2/.well-known/keys
+- http://localhost:5156/corppass/v2/authorize
+- http://localhost:5156/corppass/v2/token
+
+Configure your application (or MockPass) with keys:
+
+- EITHER configure MockPass with your application's JWKS endpoint URL using the env
+ var `CP_RP_JWKS_ENDPOINT`. HTTP/HTTPS endpoints are supported.
+- OR configure your application to use the private keys from
+  `static/certs/oidc-v2-rp-secret.json`.
+
+MockPass accepts any value for `client_id` and `redirect_uri`.
+
+| Configuration item | Explanation |
+|---|---|
+| Client signing and encryption keys | **Overview:** When client makes any request, what signing key is used to verify the client's signature on the client assertion, and what encryption key is used to encrypt the data payload. <br> **Default:** static keyset `static/certs/oidc-v2-rp-public.json` is used. <br> **How to configure:** Set the env var `CP_RP_JWKS_ENDPOINT` to a JWKS URL that MockPass can connect to. This can be a HTTP or HTTPS URL. |
+| Login page | **Overview:** When client makes an authorize request, whether MockPass sends the client to a login page, instead of completing the login silently. <br> **Default:** Disabled for all requests. <br> **How to configure:** Enable for all requests by default by setting the env var `SHOW_LOGIN_PAGE` to `true`. Regardless of the default, you can override on a per-request basis by sending the HTTP request header `X-Show-Login-Page` with the value `true`. <br> **Detailed effect:** When login page is disabled, MockPass will immediately complete login and redirect to the `redirect_uri`. The profile used will be (in order of decreasing precedence) the profile specified in HTTP request headers (`X-Custom-NRIC`, `X-Custom-UUID`, `X-Custom-UEN` must all be specified), the profile with the NRIC specified in the env var `MOCKPASS_NRIC`, or the first profile in MockPass' static data. <br> When login page is enabled, MockPass returns a HTML page with a form that is used to complete the login. The client may select an existing profile, or provide a custom NRIC, UUID and UEN on the form. |
+
+### Myinfo v3
+
+Configure your application to point to the following endpoints:
+
+- http://localhost:5156/myinfo/v3/authorise
+- http://localhost:5156/myinfo/v3/token
+- http://localhost:5156/myinfo/v3/person-basic (exclusive to government systems)
+- http://localhost:5156/myinfo/v3/person
+
+Configure your application (or MockPass) with certificates/keys:
+
+- Provide your application with
+  the certificate `static/certs/spcp.crt` as the Myinfo public certificate.
+- EITHER configure MockPass with your application's X.509 certificate by setting
+  the env vars `SERVICE_PROVIDER_PUB_KEY` and `SERVICE_PROVIDER_CERT_PATH` to 
+  the path to the certificate in PEM format. Self-signed or untrusted
+  certificates are supported.
+- OR configure your application to use the certificate and private key
+  from `static/certs/(server.crt|key.pem)`.
 
-## Quick Start (on local machine)
+MockPass accepts any value for `client_id`, `redirect_uri` and `sp_esvcId`.
+The `client_secret` value will be checked if configured, see below.
+
+Only the profiles (NRICs) that have entries in Mockpass' static dataset will
+succeed, using other NRICs will result in an error. See the list of personas in
+[static/myinfo/v3.json](static/myinfo/v3.json).
+
+| Configuration item | Explanation |
+|---|---|
+| Client certificate | **Overview:** When client makes any request, what certificate is used to verify the request signature, and what certificate is used to encrypt the data payload. <br> **Default:** static certificate/key `static/certs/(server.crt|key.pub)` are used. <br> **How to configure:** Set the env var `SERVICE_PROVIDER_PUB_KEY` to the path to a public key PEM file, and `SERVICE_PROVIDER_CERT_PATH` to the path to a certificate PEM file. (A certificate PEM file can also be provided to `SERVICE_PROVIDER_PUB_KEY`, despite the env var name.) |
+| Client secret | **Overview:** When client makes a Token request, whether MockPass verifies the request signature. <br> **Default:** Disabled. <br> **How to configure:** Enable for all requests by setting the env var `SERVICE_PROVIDER_MYINFO_SECRET` to some non-blank string. Provide this value to your application as well. |
+| Payload encryption | **Overview:** When client makes a Person or Person-Basic request, whether MockPass encrypts the data payload. When client makes a Person request, whether MockPass verifies the request signature. <br> **Default:** Disabled. <br> **How to configure:** Enable for all requests by setting the env var `ENCRYPT_MYINFO` to `true`. |
+
+To emulate the equivalent of the Test environment on Myinfo v3, you must both
+set a client secret and enable payload encryption on MockPass.
+
+### sgID v2
 
 Configure your application to point to the following endpoints:
 
-SingPass (v1 - Singpass OIDC):
+- http://localhost:5156/v2/.well-known/openid-configuration
+- http://localhost:5156/v2/.well-known/jwks.json
+- http://localhost:5156/v2/oauth/authorize
+- http://localhost:5156/v2/oauth/token
+- http://localhost:5156/v2/oauth/userinfo
+
+Configure your application (or MockPass) with certificates/keys:
+
+- Provide your application with the certificate `static/certs/spcp.crt` as the
+  sgID public key, or use the signing key published at the JWKS endpoint.
+- EITHER configure MockPass with your application's X.509 certificate using the
+  env var `SERVICE_PROVIDER_PUB_KEY`, as the path to the certificate in PEM
+  format. Self-signed or untrusted certificates are supported.
+- OR configure your application to use the certificate and private key
+  from `static/certs/(server.crt|key.pem)`.
+
+MockPass accepts any value for `client_id`, `client_secret` and `redirect_uri`.
+
+Only the profiles (NRICs) that have entries in Mockpass' static dataset will
+succeed, using other NRICs will result in an error. See the list of personas in 
+[static/myinfo/v3.json](static/myinfo/v3.json).
+
+| Configuration item | Explanation |
+|---|---|
+| Client certificate | **Overview:** When client makes any request, what certificate is used to verify the request signature, and what certificate is used to encrypt the data payload. <br> **Default:** static key `static/certs/key.pub` is used. <br> **How to configure:** Set the env var `SERVICE_PROVIDER_PUB_KEY` to the path to a public key PEM file. (A certificate PEM file can also be provided, despite the env var name.) |
+| Login page | **Overview:** When client makes an authorize request, whether MockPass sends the client to a login page, instead of completing the login silently. <br> **Default:** Disabled for all requests. <br> **How to configure:** Enable for all requests by default by setting the env var `SHOW_LOGIN_PAGE` to `true`. Regardless of the default, you can override on a per-request basis by sending the HTTP request header `X-Show-Login-Page` with the value `true`. <br> **Detailed effect:** When login page is disabled, MockPass will immediately complete login and redirect to the `redirect_uri`. The profile used will be (in order of decreasing precedence) the profile with the NRIC specified in the env var `MOCKPASS_NRIC`, or the first profile in MockPass' static data. <br> When login page is enabled, MockPass returns a HTML page with a form that is used to complete the login. The client may select an existing profile, or provide a custom NRIC and UUID on the form. |
+
+### Singpass/Corppass v1 (legacy)
+
+**The v1 APIs should no longer be in use, see the v2 APIs above!**
+
+Configure your application to point to the following endpoints:
+
+Singpass (v1 - Singpass OIDC):
  - http://localhost:5156/singpass/authorize - OIDC login redirect with optional page
  - http://localhost:5156/singpass/token - receives OIDC authorization code and returns id_token
 
-SingPass (v2 - NDI OIDC):
- - http://localhost:5156/singpass/v2/authorize - OIDC login redirect with optional page
- - http://localhost:5156/singpass/v2/token - receives OIDC authorization code and returns id_token
- - http://localhost:5156/singpass/v2/.well-known/openid-configuration - OpenID discovery endpoint
- - http://localhost:5156/singpass/v2/.well-known/keys - JWKS endpoint which exposes the auth provider's signing keys
-
-CorpPass (v1 - Corppass OIDC):
+Corppass (v1 - Corppass OIDC):
  - http://localhost:5156/corppass/authorize - OIDC login redirect with optional page
  - http://localhost:5156/corppass/token - receives OIDC authorization code and returns id_token
 
-CorpPass (v2 - Corppass OIDC):
- - http://localhost:5156/corppass/v2/authorize - OIDC login redirect with optional page
- - http://localhost:5156/corppass/v2/token - receives OIDC authorization code and returns id_token
- - http://localhost:5156/corppass/v2/.well-known/openid-configuration - OpenID discovery endpoint
- - http://localhost:5156/corppass/v2/.well-known/keys - JWKS endpoint which exposes the auth provider's signing keys
+Configure your application with keys and/or certificates:
 
-MyInfo:
- - http://localhost:5156/myinfo/v3/person-basic (exclusive to government systems)
- - http://localhost:5156/myinfo/v3/authorise
- - http://localhost:5156/myinfo/v3/token
- - http://localhost:5156/myinfo/v3/person
+Provide your application with the certificate `static/certs/spcp.crt` as the
+Singpass/Corppass public certificate.
+Provide the path to your application's X.509 certificate in PEM
+format as env var `SERVICE_PROVIDER_CERT_PATH` when running MockPass.
+Self-signed or untrusted certificates are supported.
+Alternatively, provide your application with the certificate and private key
+from `static/certs/(server.crt|key.pem)`.
 
-sgID:
- - http://localhost:5156/v2/oauth/authorize
- - http://localhost:5156/v2/oauth/token
- - http://localhost:5156/v2/oauth/userinfo
- - http://localhost:5156/v2/.well-known/openid-configuration - OpenID discovery endpoint
- - http://localhost:5156/v2/.well-known/jwks.json - JWKS endpoint which exposes the auth provider's signing keys
+### Run MockPass
 
-Provide your application with the `spcp*` certs found in `static/certs`
-and with application certs at `static/certs/{key.pem|server.crt}`
+Common configuration:
 
-Alternatively, provide the paths to your app cert as env vars
-`SERVICE_PROVIDER_CERT_PATH` and `SERVICE_PROVIDER_PUB_KEY`
+| Configuration item | Explanation |
+|---|---|
+| Port number | **Overview:** What port number MockPass will listen for HTTP requests on. <br> **Default:** 5156. <br> **How to configure:** Set the env var `MOCKPASS_PORT` or `PORT` to some port number. |
+| Stateless Mode | **Overview:** Enable for environments where the state of the process is not guaranteed, such as in serverless contexts. <br> **Default:** not set. <br> **How to configure:** Set the env var `MOCKPASS_STATELESS` to `true` or `false`. |
 
-If you are integrating with Singpass NDI OIDC and/or Corppass v2 OIDC, you should 
-provide your well-known key endpoints as env vars `SP_RP_JWKS_ENDPOINT` and/or
-`CP_RP_JWKS_ENDPOINT` respectively. Alternatively, provide your application with
-the `oidc-v2-rp-*.json` JWKS.
+Run MockPass:
 
 ```
 $ npm install @opengovsg/mockpass
 
-# All values shown here are defaults
+# Configure the listening port if desired, defaults to 5156
 $ export MOCKPASS_PORT=5156
 
-$ export SHOW_LOGIN_PAGE=true # Optional, defaults to `false`; can be overridden per request using `X-Show-Login-Page` HTTP header
-
-# Configure which profile to return when login page is disabled
-# Can be overridden per request using `X-Custom-NRIC`/`X-Custom-UUID`/`X-Custom-UEN` HTTP headers
-$ export MOCKPASS_NRIC=S8979373D # Optional, defaults to first profile
-
-# Disable signing/encryption (Optional, by default `true`)
-$ export SIGN_ASSERTION=false
-$ export ENCRYPT_ASSERTION=false
-$ export SIGN_RESPONSE=false
-$ export RESOLVE_ARTIFACT_REQUEST_SIGNED=false
-
-# Encrypt payloads returned by /myinfo/v3/{person, person-basic},
-# equivalent to MyInfo Auth Level L2 (testing and production)
-$ export ENCRYPT_MYINFO=false
-
-# If specified, will verify token provided in Authorization header
-# for requests to /myinfo/*/token
+# Configure any other options if required
+$ export SHOW_LOGIN_PAGE=false
+$ export MOCKPASS_NRIC=S8979373D
 $ export SERVICE_PROVIDER_MYINFO_SECRET=<your secret here>
+$ export ENCRYPT_MYINFO=false
 
 $ npx mockpass
 MockPass listening on 5156
-```
 
-## Background
-
-There currently is nothing widely available to test an application's integration
-with SingPass/CorpPass using a dev machine alone. This is awkward for developers
-who then need to connect to the staging servers hosted by SingPass/CorpPass,
-which may not always be available (eg, down for maintenance, or no Internet).
-
-MockPass tries to solves this by providing an extremely lightweight implementation
-of an OIDC Provider that returns mock SingPass and CorpPass assertions.
-It optionally provides a mock login page that (badly) mimics the SingPass/CorpPass
-login experience.
+# Alternatively, just run directly with npx
+MOCKPASS_PORT=5156 SHOW_LOGIN_PAGE=false MOCKPASS_NRIC=S8979373D npx @opengovsg/mockpass@latest
+```
 
 ## Contributing
 

package/app.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+const fs = require('fs')
+const express = require('express')
+const morgan = require('morgan')
+const path = require('path')
+require('dotenv').config()
+
+const {
+  configOIDC,
+  configOIDCv2,
+  configMyInfo,
+  configSGID,
+} = require('./lib/express')
+
+const serviceProvider = {
+  cert: fs.readFileSync(
+    path.resolve(
+      __dirname,
+      process.env.SERVICE_PROVIDER_CERT_PATH || './static/certs/server.crt',
+    ),
+  ),
+  pubKey: fs.readFileSync(
+    path.resolve(
+      __dirname,
+      process.env.SERVICE_PROVIDER_PUB_KEY || './static/certs/key.pub',
+    ),
+  ),
+}
+
+const cryptoConfig = {
+  signAssertion: process.env.SIGN_ASSERTION !== 'false', // default to true to be backward compatable
+  signResponse: process.env.SIGN_RESPONSE !== 'false',
+  encryptAssertion: process.env.ENCRYPT_ASSERTION !== 'false',
+  resolveArtifactRequestSigned:
+    process.env.RESOLVE_ARTIFACT_REQUEST_SIGNED !== 'false',
+}
+
+const isStateless = process.env.MOCKPASS_STATELESS === 'true'
+
+const options = {
+  serviceProvider,
+  showLoginPage: (req) =>
+    (req.header('X-Show-Login-Page') || process.env.SHOW_LOGIN_PAGE) === 'true',
+  encryptMyInfo: process.env.ENCRYPT_MYINFO === 'true',
+  cryptoConfig,
+  isStateless,
+}
+
+const app = express()
+app.use(morgan('combined'))
+
+configOIDC(app, options)
+configOIDCv2(app, options)
+configSGID(app, options)
+
+configMyInfo.consent(app, options)
+configMyInfo.v3(app, options)
+
+app.enable('trust proxy')
+app.use(express.static(path.join(__dirname, 'public')))
+
+exports.app = app

package/index.js

@@ -1,63 +1,8 @@
 #!/usr/bin/env node
-const fs = require('fs')
-const express = require('express')
-const morgan = require('morgan')
-const path = require('path')
-require('dotenv').config()
-
-const {
-  configOIDC,
-  configOIDCv2,
-  configMyInfo,
-  configSGID,
-} = require('./lib/express')
+const { app } = require('./app')
 
 const PORT = process.env.MOCKPASS_PORT || process.env.PORT || 5156
 
-const serviceProvider = {
-  cert: fs.readFileSync(
-    path.resolve(
-      __dirname,
-      process.env.SERVICE_PROVIDER_CERT_PATH || './static/certs/server.crt',
-    ),
-  ),
-  pubKey: fs.readFileSync(
-    path.resolve(
-      __dirname,
-      process.env.SERVICE_PROVIDER_PUB_KEY || './static/certs/key.pub',
-    ),
-  ),
-}
-
-const cryptoConfig = {
-  signAssertion: process.env.SIGN_ASSERTION !== 'false', // default to true to be backward compatable
-  signResponse: process.env.SIGN_RESPONSE !== 'false',
-  encryptAssertion: process.env.ENCRYPT_ASSERTION !== 'false',
-  resolveArtifactRequestSigned:
-    process.env.RESOLVE_ARTIFACT_REQUEST_SIGNED !== 'false',
-}
-
-const options = {
-  serviceProvider,
-  showLoginPage: (req) =>
-    (req.header('X-Show-Login-Page') || process.env.SHOW_LOGIN_PAGE) === 'true',
-  encryptMyInfo: process.env.ENCRYPT_MYINFO === 'true',
-  cryptoConfig,
-}
-
-const app = express()
-app.use(morgan('combined'))
-
-configOIDC(app, options)
-configOIDCv2(app, options)
-configSGID(app, options)
-
-configMyInfo.consent(app)
-configMyInfo.v3(app, options)
-
-app.enable('trust proxy')
-app.use(express.static(path.join(__dirname, 'public')))
-
 app.listen(PORT, (err) =>
   err
     ? console.error('Unable to start MockPass', err)

package/lib/auth-code.js

@@ -4,14 +4,24 @@ const crypto = require('crypto')
 const AUTH_CODE_TIMEOUT = 5 * 60 * 1000
 const profileAndNonceStore = new ExpiryMap(AUTH_CODE_TIMEOUT)
 
-const generateAuthCode = ({ profile, scopes, nonce }) => {
-  const authCode = crypto.randomBytes(45).toString('base64')
+const generateAuthCode = (
+  { profile, scopes, nonce },
+  { isStateless = false },
+) => {
+  const authCode = isStateless
+    ? Buffer.from(JSON.stringify({ profile, scopes, nonce })).toString(
+        'base64url',
+      )
+    : crypto.randomBytes(45).toString('base64')
+
   profileAndNonceStore.set(authCode, { profile, scopes, nonce })
   return authCode
 }
 
-const lookUpByAuthCode = (authCode) => {
-  return profileAndNonceStore.get(authCode)
+const lookUpByAuthCode = (authCode, { isStateless = false }) => {
+  return isStateless
+    ? JSON.parse(Buffer.from(authCode, 'base64url').toString('utf-8'))
+    : profileAndNonceStore.get(authCode)
 }
 
 module.exports = { generateAuthCode, lookUpByAuthCode }

package/lib/express/myinfo/consent.js

@@ -47,13 +47,13 @@ const authorizeViaOIDC = authorize(
     `/singpass/authorize?client_id=MYINFO-CONSENTPLATFORM&redirect_uri=${MYINFO_ASSERT_ENDPOINT}&state=${state}`,
 )
 
-function config(app) {
+function config(app, { isStateless }) {
   app.get(MYINFO_ASSERT_ENDPOINT, (req, res) => {
     const rawArtifact = req.query.SAMLart || req.query.code
     const artifact = rawArtifact.replace(/ /g, '+')
     const state = req.query.RelayState || req.query.state
 
-    const profile = lookUpByAuthCode(artifact).profile
+    const profile = lookUpByAuthCode(artifact, { isStateless }).profile
     const myinfoVersion = 'v3'
 
     const { nric: id } = profile

package/lib/express/oidc/spcp.js

@@ -24,7 +24,7 @@ const signingPem = fs.readFileSync(
   path.resolve(__dirname, '../../../static/certs/spcp-key.pem'),
 )
 
-function config(app, { showLoginPage, serviceProvider }) {
+function config(app, { showLoginPage, serviceProvider, isStateless }) {
   for (const idp of ['singPass', 'corpPass']) {
     const profiles = assertions.oidc[idp]
     const defaultProfile =
@@ -34,7 +34,7 @@ function config(app, { showLoginPage, serviceProvider }) {
       const { redirect_uri: redirectURI, state, nonce } = req.query
       if (showLoginPage(req)) {
         const values = profiles.map((profile) => {
-          const authCode = generateAuthCode({ profile, nonce })
+          const authCode = generateAuthCode({ profile, nonce }, { isStateless })
           const assertURL = buildAssertURL(redirectURI, authCode, state)
           const id = idGenerator[idp](profile)
           return { id, assertURL }
@@ -53,7 +53,7 @@ function config(app, { showLoginPage, serviceProvider }) {
         res.send(response)
       } else {
         const profile = customProfileFromHeaders[idp](req) || defaultProfile
-        const authCode = generateAuthCode({ profile, nonce })
+        const authCode = generateAuthCode({ profile, nonce }, { isStateless })
         const assertURL = buildAssertURL(redirectURI, authCode, state)
         console.warn(
           `Redirecting login from ${req.query.client_id} to ${redirectURI}`,
@@ -72,7 +72,7 @@ function config(app, { showLoginPage, serviceProvider }) {
         profile.uen = uen
       }
 
-      const authCode = generateAuthCode({ profile, nonce })
+      const authCode = generateAuthCode({ profile, nonce }, { isStateless })
       const assertURL = buildAssertURL(redirectURI, authCode, state)
       res.redirect(assertURL)
     })
@@ -88,20 +88,32 @@ function config(app, { showLoginPage, serviceProvider }) {
           const { refresh_token: suppliedRefreshToken } = req.body
           console.warn(`Refreshing tokens with ${suppliedRefreshToken}`)
 
-          profile = profileStore.get(suppliedRefreshToken)
+          profile = isStateless
+            ? JSON.parse(
+                Buffer.from(suppliedRefreshToken, 'base64url').toString(
+                  'utf-8',
+                ),
+              )
+            : profileStore.get(suppliedRefreshToken)
         } else {
           const { code: authCode } = req.body
           console.warn(
             `Received auth code ${authCode} from ${aud} and ${req.body.redirect_uri}`,
           )
-          ;({ profile, nonce } = lookUpByAuthCode(authCode))
+          ;({ profile, nonce } = lookUpByAuthCode(authCode, { isStateless }))
         }
 
         const iss = `${req.protocol}://${req.get('host')}`
 
-        const { idTokenClaims, accessToken, refreshToken } =
-          await assertions.oidc.create[idp](profile, iss, aud, nonce)
+        const {
+          idTokenClaims,
+          accessToken,
+          refreshToken: generatedRefreshToken,
+        } = await assertions.oidc.create[idp](profile, iss, aud, nonce)
 
+        const refreshToken = isStateless
+          ? Buffer.from(JSON.stringify(profile)).toString('base64url')
+          : generatedRefreshToken
         profileStore.set(refreshToken, profile)
 
         const signingKey = await jose.JWK.asKey(signingPem, 'pem')

package/lib/express/oidc/v2-ndi.js

@@ -140,7 +140,7 @@ function findEncryptionKey(jwks, algs) {
   }
 }
 
-function config(app, { showLoginPage }) {
+function config(app, { showLoginPage, isStateless }) {
   for (const idp of ['singPass', 'corpPass']) {
     const profiles = assertions.oidc[idp]
     const defaultProfile =
@@ -196,7 +196,7 @@ function config(app, { showLoginPage }) {
       // Identical to OIDC v1
       if (showLoginPage(req)) {
         const values = profiles.map((profile) => {
-          const authCode = generateAuthCode({ profile, nonce })
+          const authCode = generateAuthCode({ profile, nonce }, { isStateless })
           const assertURL = buildAssertURL(redirectURI, authCode, state)
           const id = idGenerator[idp](profile)
           return { id, assertURL }
@@ -215,7 +215,7 @@ function config(app, { showLoginPage }) {
         res.send(response)
       } else {
         const profile = customProfileFromHeaders[idp](req) || defaultProfile
-        const authCode = generateAuthCode({ profile, nonce })
+        const authCode = generateAuthCode({ profile, nonce }, { isStateless })
         const assertURL = buildAssertURL(redirectURI, authCode, state)
         console.warn(
           `Redirecting login from ${req.query.client_id} to ${redirectURI}`,
@@ -234,7 +234,7 @@ function config(app, { showLoginPage }) {
         profile.uen = uen
       }
 
-      const authCode = generateAuthCode({ profile, nonce })
+      const authCode = generateAuthCode({ profile, nonce }, { isStateless })
       const assertURL = buildAssertURL(redirectURI, authCode, state)
       res.redirect(assertURL)
     })
@@ -434,7 +434,7 @@ function config(app, { showLoginPage }) {
         }
 
         // Step 1: Obtain profile for which the auth code requested data for
-        const { profile, nonce } = lookUpByAuthCode(authCode)
+        const { profile, nonce } = lookUpByAuthCode(authCode, { isStateless })
 
         // Step 2: Get ID token
         const aud = clientAssertionClaims['sub']

package/lib/express/sgid.js

@@ -30,7 +30,7 @@ const buildAssertURL = (redirectURI, authCode, state) =>
     authCode,
   )}&state=${encodeURIComponent(state)}`
 
-function config(app, { showLoginPage, serviceProvider }) {
+function config(app, { showLoginPage, serviceProvider, isStateless }) {
   const profiles = assertions.oidc.singPass
   const defaultProfile =
     profiles.find((p) => p.nric === process.env.MOCKPASS_NRIC) || profiles[0]
@@ -43,7 +43,10 @@ function config(app, { showLoginPage, serviceProvider }) {
       const values = profiles
         .filter((profile) => assertions.myinfo.v3.personas[profile.nric])
         .map((profile) => {
-          const authCode = generateAuthCode({ profile, scopes, nonce })
+          const authCode = generateAuthCode(
+            { profile, scopes, nonce },
+            { isStateless },
+          )
           const assertURL = buildAssertURL(redirectURI, authCode, state)
           const id = idGenerator.singPass(profile)
           return { id, assertURL }
@@ -52,7 +55,10 @@ function config(app, { showLoginPage, serviceProvider }) {
       res.send(response)
     } else {
       const profile = defaultProfile
-      const authCode = generateAuthCode({ profile, scopes, nonce })
+      const authCode = generateAuthCode(
+        { profile, scopes, nonce },
+        { isStateless },
+      )
       const assertURL = buildAssertURL(redirectURI, authCode, state)
       console.info(
         `Redirecting login from ${req.query.client_id} to ${assertURL}`,
@@ -74,7 +80,9 @@ function config(app, { showLoginPage, serviceProvider }) {
       )
 
       try {
-        const { profile, scopes, nonce } = lookUpByAuthCode(authCode)
+        const { profile, scopes, nonce } = lookUpByAuthCode(authCode, {
+          isStateless,
+        })
         console.info(
           `Profile ${JSON.stringify(profile)} with token scope ${scopes}`,
         )
@@ -120,7 +128,9 @@ function config(app, { showLoginPage, serviceProvider }) {
       req.headers.authorization || req.headers.Authorization
     ).replace('Bearer ', '')
     // eslint-disable-next-line no-unused-vars
-    const { profile, scopes, unused } = lookUpByAuthCode(authCode)
+    const { profile, scopes, unused } = lookUpByAuthCode(authCode, {
+      isStateless,
+    })
     const uuid = profile.uuid
     const nric = assertions.oidc.singPass.find((p) => p.uuid === uuid).nric
     const persona = assertions.myinfo.v3.personas[nric]

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@opengovsg/mockpass",
-  "version": "4.0.11",
+  "version": "4.1.0",
   "description": "A mock SingPass/CorpPass server for dev purposes",
-  "main": "index.js",
+  "main": "app.js",
   "bin": {
     "mockpass": "index.js"
   },
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",
-    "start": "nodemon",
+    "start": "nodemon index",
     "cz": "git-cz",
     "lint": "eslint lib",
     "lint-fix": "eslint --fix lib",