@opengovsg/mockpass 4.5.8 → 4.6.0

package/README.md

@@ -15,6 +15,46 @@ A mock Singpass/Corppass/Myinfo v3/sgID v2/Sign v3 server for dev purposes
 
 ## Quick Start (hosted locally)
 
+### Singpass v3 (FAPI flow)
+
+For more information regarding the FAPI flow, refer to: https://docs.developer.singpass.gov.sg/docs/technical-specifications/integration-guide/1.-authorization-request
+
+Configure your endpoint to point to the following endpoints:
+- http://localhost:5156/singpass/v3/fapi/.well-known/openid-configuration
+- http://localhost:5156/singpass/v3/fapi/.well-known/jwks.json
+- http://localhost:5156/singpass/v3/fapi/par
+- http://localhost:5156/singpass/v3/fapi/auth
+- http://localhost:5156/singpass/v3/fapi/token
+
+
+In the `/fapi/utils.js file`, you can configure your client JWKS endpoint in the `fapiClientConfiguration`. By default, it is set to `null` and Mockpass will read the default keys that are stored in the `fapi-private.json` and `fapi-public.json` If configured, Mockpass will attempt to fetch the JWKS from the specified endpoint. 
+Your JWKS endpoint will need to be publicly accessible, and it needs to contain a valid JWKS with a sig key and an enc key.
+
+Limitations:
+- `client_id` and `redirect_uri` can be set to anything.
+- Mockpass will not check if ephemeral keys, state, and nonce are reused.
+- Only Login is supported for now. Userinfo endpoint is not supported. 
+- Only `openid` is supported for the `scope` parameter.
+- Only `urn:singpass:authentication:loa:1` is supported for the `acr_values` parameter.
+
+### Helper functions
+
+There is a helper endpoint that can generate the ephemeral keys and tokens for you. This is useful if you want to experience the FAPI flow without a server setup. 
+- POST: http://localhost:5156/singpass/v3/fapi/tests/generate-tokens
+  #### Request Body
+
+| Body                | Description                                                                                                                                                                                                                                                                                                                                                                                   | Example                                                                                                           |
+|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------|
+| ephemeralPrivateKey | Optional. This is the generated ephemeral private key that will be used for the auth session. If provided, it will be used to sign the DPoP tokens. Otherwise, a new key will be generated for you in the response body. <br/><br/> Note: If you are calling the /token endpoint, you will need to pass in the generated private key so that the same key is used for signing the DPoP token. | ``` -----BEGIN PRIVATE KEY-----\nMIGHAgE...3HMe8M82x\n-----END PRIVATE KEY----- ```                               |
+| endpoint            | Mandatory. This is to populate the htu parameter in the DPoP token. Depending on which endpoint you are calling in the FAPI flow, you should select the correct endpoint.                                                                                                                                                                                                                     | Possible values are: `http://localhost:5156/singpass/v3/fapi/par`, `http://localhost:5156/singpass/v3/fapi/token` |
+
+#### Response Body
+| Body                 | Description                                                                                                         | Type       |
+|----------------------|---------------------------------------------------------------------------------------------------------------------|------------|
+| dpopToken            | The dpop token that is used for the API call.                                                                       | jwt        |
+| clientAssertionToken | The client assertion token that is used for the API call.                                                           | jwt        |
+| ephemeralPrivateKey  | The ephemeral private key that is used to sign the dpop token. This key should be used for the entire auth session. | PEM format |
+
 ### Singpass v2 (NDI OIDC)
 
 Configure your application to point to the following endpoints:
@@ -34,7 +74,7 @@ Configure your application (or MockPass) with keys:
 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. |
 | ID token exchange                  | **Overview:** Singpass uses the client's [profile](https://docs.developer.singpass.gov.sg/docs/technical-specifications/singpass-authentication-api/2.-token-endpoint/authorization-code-grant#id-token-structure) to decide the format of the id token to send across. <br> **Default:** `direct` <br> **How to configure:** To set this, set the env var (`SINGPASS_CLIENT_PROFILE`) to the desired value                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
@@ -58,7 +98,7 @@ Configure your application (or MockPass) with keys:
 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. |
 
@@ -90,7 +130,7 @@ 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`.                                                                                                                                                                                                                |
@@ -134,7 +174,7 @@ identify them.
 The `pocdex.number_of_employments` scope is not supported.
 
 | 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. |
 
@@ -186,7 +226,7 @@ Configure MockPass with your application client details:
 Common configuration:
 
 | 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`. |
 

package/app.js

@@ -11,6 +11,7 @@ const {
   configMyInfo,
   configSGID,
   configSignV3,
+  configFapi,
 } = require('./lib/express')
 
 const serviceProvider = {
@@ -54,6 +55,7 @@ configOIDC(app, options)
 configOIDCv2(app, options)
 configSGID(app, options)
 configSignV3(app, options)
+configFapi(app, options)
 
 configMyInfo.consent(app, options)
 configMyInfo.v3(app, options)

package/lib/auth-code.js

@@ -18,10 +18,17 @@ const generateAuthCode = (
   return authCode
 }
 
+const generateAuthCodeForFapi = ({ profile, clientId = '' }) => {
+  const authCode = crypto.randomBytes(45).toString('base64url')
+
+  profileAndNonceStore.set(authCode, { profile, clientId })
+  return authCode
+}
+
 const lookUpByAuthCode = (authCode, { isStateless = false }) => {
   return isStateless
     ? JSON.parse(Buffer.from(authCode, 'base64url').toString('utf-8'))
     : profileAndNonceStore.get(authCode)
 }
 
-module.exports = { generateAuthCode, lookUpByAuthCode }
+module.exports = { generateAuthCode, generateAuthCodeForFapi, lookUpByAuthCode }

package/lib/express/fapi/fapi.controller.js

@@ -0,0 +1,75 @@
+const FapiService = require('./fapi.service.js')
+const FapiUtils = require('./utils.js')
+const express = require('express')
+const assertions = require('../../assertions')
+const fs = require('fs')
+const path = require('path')
+
+function config(app) {
+  app.use(express.json())
+  app.use(express.urlencoded({ extended: true }))
+  const profiles = assertions.oidc['singPass']
+  const service = new FapiService()
+
+  app.get(`${FapiUtils.FAPI_PATH}/.well-known/keys`, (req, res) => {
+    const keys = JSON.parse(
+      fs.readFileSync(
+        path.resolve(__dirname, '../../../static/certs/fapi-public.json'),
+        'utf8',
+      ),
+    )
+    return res.send(keys)
+  })
+
+  app.get(
+    `${FapiUtils.FAPI_PATH}/.well-known/openid-configuration`,
+    (req, res) => {
+      return res.send(FapiUtils.getFapiOpenIdConfiguration(req))
+    },
+  )
+
+  app.post(`${FapiUtils.FAPI_PATH}/par`, async (req, res) => {
+    try {
+      const request_uri = await service.handleParRequest(req)
+      return res.status(201).send({ request_uri, expires_in: 60 })
+    } catch (e) {
+      return res.status(400).send({ error: e.message })
+    }
+  })
+
+  app.get(`${FapiUtils.FAPI_PATH}/auth`, async (req, res) => {
+    try {
+      const authRequest = await service.handleAuthorizationRequest(req)
+      return res.send(
+        service.generateLoginPage(profiles, 'singPass', authRequest),
+      )
+    } catch (e) {
+      return res.status(400).send({ error: e.message })
+    }
+  })
+
+  app.post(`${FapiUtils.FAPI_PATH}/token`, async (req, res) => {
+    try {
+      return res.status(200).send(await service.handleTokenRequest(req))
+    } catch (e) {
+      return res.status(400).send({ error: e.message })
+    }
+  })
+
+  //Helper function to generate DPoP proof JWT and client assertion token for testing. In real implementation, these tokens should be generated by the client.
+  app.post(`${FapiUtils.FAPI_PATH}/tests/generate-tokens`, async (req, res) => {
+    try {
+      const { ephemeralPrivateKey, dpopToken, clientAssertionToken } =
+        await FapiUtils.generateDpopAndClientAssertionToken(req)
+      return res.send({
+        dpopToken,
+        clientAssertionToken,
+        ephemeralPrivateKey,
+      })
+    } catch (e) {
+      return res.status(400).send({ error: e.message })
+    }
+  })
+}
+
+module.exports = config

package/lib/express/fapi/fapi.service.js

@@ -0,0 +1,418 @@
+const assert = require('assert')
+const crypto = require('crypto')
+const FapiUtils = require('./utils.js')
+const { readFileSync } = require('fs')
+const path = require('path')
+const jose = require('jose')
+const { lookUpByAuthCode, generateAuthCodeForFapi } = require('../../auth-code')
+const fs = require('fs')
+const { buildAssertURL, idGenerator } = require('../oidc/utils')
+const { render } = require('mustache')
+const ExpiryMap = require('expiry-map')
+
+class FapiService {
+  constructor() {
+    this.map = new ExpiryMap(5 * 60 * 1000) // PAR request expires in 5 minutes
+  }
+
+  async handleParRequest(req) {
+    verifyParRequestBody(req)
+    const parEndpoint =
+      FapiUtils.getFapiOpenIdConfiguration(
+        req,
+      ).pushed_authorization_request_endpoint
+    const [, dpopJkt] = await Promise.all([
+      verifyClientAssertion(req),
+      verifyDpop(req.headers['dpop'], null, parEndpoint),
+    ])
+
+    const request_uri = `urn:ietf:params:oauth:request_uri:${crypto
+      .randomBytes(64)
+      .toString('base64url')}`
+
+    const object = {
+      request_uri,
+      redirect_uri: req.body.redirect_uri,
+      client_id: req.body.client_id,
+      code_challenge: req.body.code_challenge,
+      code_challenge_method: req.body.code_challenge_method,
+      scope: req.body.scope,
+      nonce: req.body.nonce,
+      state: req.body.state,
+      dpopJkt,
+    }
+
+    this.map.set(req.body.client_id, object)
+
+    return request_uri
+  }
+
+  async handleAuthorizationRequest(req) {
+    const authRequest = this.map.get(req.query.client_id)
+    if (!authRequest) throw new Error('No PAR request found in session')
+    verifyAuthRequestBody(req, authRequest)
+    return authRequest
+  }
+
+  async handleTokenRequest(req) {
+    //Due to Mockpass limitations, we are using clientid for session management.
+    const client_id = await verifyClientAssertion(req)
+    const authRequest = this.map.get(client_id)
+    if (!authRequest) throw new Error('No auth request found in session')
+
+    verifyTokenRequestBody(req, authRequest)
+    const tokenEndpoint =
+      FapiUtils.getFapiOpenIdConfiguration(req).token_endpoint
+    await verifyDpop(req.headers['dpop'], authRequest.dpopJkt, tokenEndpoint)
+    return await this.generateIdToken(req, authRequest)
+  }
+
+  generateLoginPage(profiles, idp, authRequest) {
+    const state = authRequest.state
+    const values = profiles.map((profile) => {
+      const authCode = generateAuthCodeForFapi({ profile, authRequest })
+      const assertURL = buildAssertURL(
+        authRequest.redirect_uri,
+        authCode,
+        state,
+      )
+      const id = idGenerator[idp](profile)
+      return { id, assertURL }
+    })
+    const LOGIN_TEMPLATE = fs.readFileSync(
+      path.resolve(__dirname, '../../../static/html/login-page.html'),
+      'utf8',
+    )
+    // console.debug('values: ', values) //useful when you want to test without a RP system
+    return render(LOGIN_TEMPLATE, {
+      values,
+      customProfileConfig: {
+        endpoint: `/${idp.toLowerCase()}/v2/auth/custom-profile`,
+        showUuid: true,
+        showUen: idp === 'corpPass',
+        redirectURI: authRequest.redirect_uri,
+        state: authRequest.state,
+        nonce: authRequest.nonce,
+      },
+    })
+  }
+
+  async generateIdToken(req, authRequest) {
+    //Generate tokens
+    const expires_in = FapiUtils.idTokenConfiguration.TOKEN_EXPIRY //30 minutes
+    const { profile } = lookUpByAuthCode(req.body.code, { isStateless: false })
+    if (!profile) throw new Error('No profile found in session')
+    const id_token = {
+      sub: profile.uuid,
+      sub_attributes: {
+        identity_number: profile.nric,
+      },
+      aud: authRequest.client_id,
+      acr: 'urn:singpass:authentication:loa:1', //Mockpass only
+      sub_type: 'user',
+      amr: ['pwd'],
+      iss: FapiUtils.getFapiOpenIdConfiguration(req).issuer,
+      exp: Math.floor(Date.now() / 1000) + expires_in,
+      iat: Date.now() / 1000,
+      nonce: authRequest.nonce,
+    }
+
+    //Sign Id Token
+
+    const aspSecret = fs.readFileSync(
+      path.resolve(__dirname, '../../../static/certs/oidc-v2-asp-secret.json'),
+    )
+
+    const getSigKey = async ({ keySet, kty = 'EC', crv = 'P-256' }) => {
+      return keySet.keys.find(
+        (item) => item.use === 'sig' && item.kty === kty && item.crv === crv,
+      )
+    }
+
+    const aspKeyset = JSON.parse(aspSecret)
+    const aspSigningKey = await getSigKey({ keySet: aspKeyset })
+    if (!aspSigningKey) {
+      throw new Error('No suitable signing key found')
+    }
+
+    const signingKey = await jose.importJWK(aspSigningKey, 'ES256')
+    const signedProtectedHeader = {
+      alg: 'ES256',
+      typ: 'JWT',
+      kid: aspSigningKey.kid,
+    }
+    const signedIdToken = await new jose.CompactSign(
+      new TextEncoder().encode(JSON.stringify(id_token)),
+    )
+      .setProtectedHeader(signedProtectedHeader)
+      .sign(signingKey)
+
+    //Encrypt signed id token
+    let rpEncPublicKey
+    if (FapiUtils.fapiClientConfiguration.client_jwks) {
+      const jwks = await fetch(
+        FapiUtils.fapiClientConfiguration.client_jwks,
+      ).then((res) => res.json())
+      if (!jwks.keys) throw new Error('Unable to fetch client jwks')
+      rpEncPublicKey = jwks.keys.find((key) => key.use === 'enc')
+    } else {
+      rpEncPublicKey = JSON.parse(
+        readFileSync(
+          path.resolve(__dirname, '../../../static/certs/fapi-public.json'),
+        ),
+      )['keys'].find((key) => key.use === 'enc')
+    }
+    if (!rpEncPublicKey) throw new Error('No suitable encryption key found')
+    const encKey = await jose.importJWK(rpEncPublicKey)
+    const encrpytionProtectedHeader = {
+      alg: rpEncPublicKey.alg,
+      typ: 'JWT',
+      kid: rpEncPublicKey.kid,
+      enc: 'A256GCM',
+      cty: 'JWT',
+    }
+    const encryptedIdToken = await new jose.CompactEncrypt(
+      new TextEncoder().encode(signedIdToken),
+    )
+      .setProtectedHeader(encrpytionProtectedHeader)
+      .encrypt(encKey)
+
+    return {
+      access_token: crypto.randomBytes(64).toString('base64url'),
+      id_token: encryptedIdToken,
+      token_type: 'DPoP',
+    }
+  }
+}
+
+//Verification functions
+async function verifyDpop(dpop, dpop_jkt, expectedEndpoint) {
+  if (!dpop && !dpop_jkt) throw new Error('Dpop or Dpop jkt is required')
+  if (dpop) {
+    const dpopToken = dpop.split(' ')[0]
+    const [headerB64] = dpopToken.split('.')
+    const header = JSON.parse(Buffer.from(headerB64, 'base64').toString())
+    const jwk = header.jwk
+    if (!jwk) throw new Error('DPoP header missing jwk')
+    try {
+      const key = await jose.importJWK(jwk, 'ES256')
+      await jose.jwtVerify(dpopToken, key, {
+        clockTolerance: FapiUtils.dpopConfiguration.DPOP_CLOCK_SKEW,
+        requiredClaims: ['jti', 'iat', 'exp', 'htu', 'htm'],
+      })
+    } catch (error) {
+      throw new Error(`Invalid DPoP token signature, ${error.message}`)
+    }
+    // Extract payload from DPoP token
+    const payloadB64 = dpopToken.split('.')[1]
+    const payload = JSON.parse(Buffer.from(payloadB64, 'base64').toString())
+    const { htu, htm } = payload
+    if (htu.toLowerCase() !== expectedEndpoint.toLowerCase()) {
+      throw new Error('Invalid DPoP htu')
+    }
+    if (typeof htm !== 'string' || !htm) {
+      throw new Error('DPoP htm must be a non-empty string')
+    }
+    if (htm.toUpperCase() !== 'POST') {
+      throw new Error('Only POST requests are supported with DPoP')
+    }
+    const jwkThumbprint = crypto
+      .createHash('sha256')
+      .update(
+        JSON.stringify({
+          crv: jwk.crv,
+          kty: jwk.kty,
+          x: jwk.x,
+          y: jwk.y,
+        }),
+      )
+      .digest('base64url')
+    if (dpop_jkt && dpop_jkt !== jwkThumbprint)
+      throw new Error('Invalid DPoP jkt')
+    return jwkThumbprint
+  }
+}
+async function verifyClientAssertion(req) {
+  const { client_assertion, client_assertion_type } = req.body
+  assert(client_assertion, 'Client assertion is required')
+  assert(client_assertion_type, 'Client assertion type is required')
+  if (
+    client_assertion_type !==
+    'urn:ietf:params:oauth:client-assertion-type:jwt-bearer'
+  )
+    throw new Error('Invalid client assertion type')
+  let jwks
+  if (FapiUtils.fapiClientConfiguration.client_jwks)
+    jwks = await fetch(FapiUtils.fapiClientConfiguration.client_jwks).then(
+      (res) => res.json(),
+    )
+  else
+    jwks = JSON.parse(
+      readFileSync(
+        path.resolve(__dirname, '../../../static/certs/fapi-public.json'),
+      ),
+    )
+  if (!jwks.keys) throw new Error('Unable to fetch client jwks')
+
+  const [headerB64] = client_assertion.split('.')
+  const header = JSON.parse(Buffer.from(headerB64, 'base64').toString())
+  if (!header.kid) throw new Error('No kid found in client assertion header')
+
+  const keyMap = Object.fromEntries(jwks.keys.map((k) => [k.kid, k]))
+  const keyToTry = await jose.importJWK(keyMap[header.kid], 'ES256')
+  if (!keyToTry) throw new Error('No matching key found for kid')
+
+  const { payload } = await jose
+    .jwtVerify(client_assertion, keyToTry, {
+      algorithms: ['ES256'],
+      clockTolerance: FapiUtils.dpopConfiguration.DPOP_CLOCK_SKEW,
+      requiredClaims: ['iss', 'sub', 'aud', 'exp', 'iat', 'jti'],
+    })
+    .catch(() => {
+      throw new Error('Invalid client assertion signature')
+    })
+
+  if (payload.aud !== FapiUtils.getFapiOpenIdConfiguration(req).issuer)
+    throw new Error('Invalid client assertion aud')
+  return payload.iss
+}
+function verifyParRequestBody(req) {
+  const {
+    response_type,
+    scope,
+    state,
+    nonce,
+    client_id,
+    redirect_uri,
+    acr_values,
+    code_challenge,
+    code_challenge_method,
+    authentication_context_type,
+    authentication_context_message,
+    redirect_uri_https_type,
+  } = req.body
+
+  verifyClientInfo(client_id, redirect_uri, redirect_uri_https_type)
+  verifyStateAndNonce(state, nonce)
+  verifyAllowedScopes(scope)
+  verifyAcrValues(acr_values)
+  verifyResponseType(response_type)
+  verifyCodeChallenge(code_challenge, code_challenge_method)
+  verifyAuthenticationContext(
+    authentication_context_type,
+    authentication_context_message,
+  )
+}
+function verifyAuthRequestBody(req, parRequest) {
+  const { client_id, request_uri } = req.query
+  if (!client_id) throw new Error('No Client ID in query')
+  if (!request_uri) throw new Error('No Request URI in query')
+  if (request_uri !== parRequest.request_uri)
+    throw new Error('Request URI not found')
+  if (client_id !== parRequest.client_id)
+    throw new Error('Client ID does not match')
+  if (!parRequest.scope.includes('openid'))
+    throw new Error('Scope must include openid')
+}
+function verifyTokenRequestBody(req, authRequest) {
+  const { grant_type, code, redirect_uri, code_verifier } = req.body
+  assert(
+    FapiUtils.SupportedGrantTypes.AUTHORIZATION_CODE.includes(grant_type),
+    'Only authorization code grant type is supported',
+  )
+  assert(code, 'Authorization code is required')
+  assert(redirect_uri, 'Redirect URI is required')
+  if (redirect_uri !== authRequest.redirect_uri)
+    throw new Error('Redirect URI does not match')
+  verifyCodeVerifier(code_verifier, authRequest.code_challenge)
+}
+function verifyClientInfo(clientId, redirect_uri, redirect_uri_https_type) {
+  /**
+   * Since this is a demo, will not enforce client id and redirect uri must match, but must be provided.
+   */
+  assert(clientId, 'Client ID is required')
+  assert(redirect_uri, 'Redirect URI is required')
+  let parsedUri
+  try {
+    parsedUri = new URL(redirect_uri)
+  } catch {
+    throw new Error('Invalid redirect uri')
+  }
+  const { protocol } = parsedUri
+  if (protocol !== 'https:' && protocol !== 'http:')
+    throw new Error('Invalid redirect uri protocol')
+  if (
+    redirect_uri_https_type &&
+    !FapiUtils.AllowedHttpsRedirectTypes.includes(redirect_uri_https_type)
+  )
+    throw new Error('Invalid redirect uri https type')
+}
+function verifyAllowedScopes(scope) {
+  assert(scope, 'Scope is required')
+  const scopes = scope.split(' ')
+  for (const s of scopes) {
+    if (!Object.values(FapiUtils.SupportedScope).includes(s))
+      throw new Error(`Scope ${s} is not supported`)
+  }
+}
+function verifyStateAndNonce(state, nonce) {
+  assert(state, 'State is required')
+  if (/^[A-Za-z0-9/+_\-=.]{30,255}$/.test(state) === false)
+    throw new Error('Invalid state')
+  assert(nonce, 'Nonce is required')
+  if (/^[A-Za-z0-9/+_\-=.]{30,255}$/.test(nonce) === false)
+    throw new Error('Invalid nonce')
+}
+function verifyResponseType(responseType) {
+  assert(responseType, 'Response type is required')
+  if (!Object.values(FapiUtils.SupportedResponseTypes).includes(responseType))
+    throw new Error('Invalid response type')
+}
+function verifyAcrValues(acrValue) {
+  //Optional parameter
+  if (!acrValue) return
+  if (!FapiUtils.AllowedAcrValues.includes(acrValue)) {
+    throw new Error('Invalid acr values')
+  }
+}
+function verifyCodeChallenge(codeChallenge, codeChallengeMethod) {
+  assert(codeChallenge, 'Code challenge is required')
+  if (codeChallengeMethod !== 'S256')
+    throw new Error('Invalid code challenge method')
+  assert(codeChallenge, 'Code challenge is required')
+  if (!/^[A-Za-z0-9\-_]{43,128}$/.test(codeChallenge))
+    throw new Error(
+      'Code challenge must be base64 encoded and at least 43 to 128 characters long',
+    )
+}
+function verifyAuthenticationContext(
+  authenticationContextType,
+  authenticationContextMessage,
+) {
+  //Not enforced if not provided. This parameter seems to fail when provided for some login apps
+  if (!authenticationContextType) return
+  if (
+    !FapiUtils.AllowedAuthenticationContextTypes.includes(
+      authenticationContextType,
+    )
+  )
+    throw new Error('Invalid authentication context type')
+  assert(
+    authenticationContextMessage,
+    'Authentication context message is required',
+  )
+  if (authenticationContextMessage.length > 100)
+    throw new Error(
+      'Authentication context message must be less than 100 characters',
+    )
+}
+function verifyCodeVerifier(codeVerifier, codeChallenge) {
+  const verifierSha256 = crypto
+    .createHash('sha256')
+    .update(codeVerifier)
+    .digest('base64url')
+  if (verifierSha256 !== codeChallenge)
+    throw new Error('Code verifier and code challenge do not match')
+}
+
+module.exports = FapiService

package/lib/express/fapi/utils.js

@@ -0,0 +1,208 @@
+const {
+  generateKeyPairSync,
+  createPrivateKey,
+  createPublicKey,
+  randomUUID,
+} = require('crypto')
+const jose = require('jose')
+const { readFileSync } = require('fs')
+const path = require('path')
+
+const SupportedScope = {
+  OPENID: 'openid',
+  UINFIN: 'uinfin',
+  USER_IDENTITY: 'user.identity',
+}
+const SupportedClaims = {
+  NONCE: 'nonce',
+  AUDIENCE: 'aud',
+  ISS: 'iss',
+  SUB: 'sub',
+  EXP: 'exp',
+  IAT: 'iat',
+}
+const SupportedGrantTypes = {
+  AUTHORIZATION_CODE: 'authorization_code',
+}
+
+const SupportedResponseTypes = {
+  CODE: 'code',
+}
+
+const AllowedAcrValues = [
+  'urn:singpass:authentication:loa:1',
+  'urn:singpass:authentication:loa:2',
+  'urn:singpass:authentication:loa:3',
+]
+const AllowedAuthenticationContextTypes = ['APP_AUTHENTICATION_DEFAULT']
+const AllowedHttpsRedirectTypes = ['app_claimed_https', 'standard_https']
+const clientAssertionConfig = {
+  CLOCK_SKEW: 60, // 1 minute
+  MAX_AGE: 120, //2 minutes
+}
+const dpopConfiguration = {
+  MAX_AGE: 120,
+  ALLOWED_DPOP_HEADER_TYP: ['dpop+jwt'],
+  ALLOWED_DPOP_HEADER_ALG: ['ES256'],
+  DPOP_CLOCK_SKEW: 60,
+}
+
+const idTokenConfiguration = {
+  TOKEN_EXPIRY: 1800,
+}
+
+const FAPI_PATH = '/v3/fapi'
+const fapiClientConfiguration = {
+  //This is only used for the /generate-tokens call. If used, your POST request must also use the same client_id
+  client_id: 'mock-fapi-client-id',
+
+  //If populated, mockpass will fetch from this endpoint. Ensure that enc key and sig key are included
+  client_jwks: process.env.FAPI_CLIENT_JWKS_ENDPOINT || null,
+}
+
+function getIssuerFromRequest(req) {
+  return `${req.protocol}://${req.get('host')}${FAPI_PATH}`
+}
+
+function getFapiOpenIdConfiguration(req) {
+  const issuer = getIssuerFromRequest(req)
+  return {
+    issuer,
+    pushed_authorization_request_endpoint: `${issuer}/par`,
+    authorization_endpoint: `${issuer}/auth`,
+    jwks_uri: `${issuer}/.well-known/keys`,
+    token_endpoint: `${issuer}/token`,
+    response_types_supported: Object.values(SupportedResponseTypes),
+    scopes_supported: Object.values(SupportedScope),
+    subject_types_supported: ['public'],
+    claims_supported: Object.values(SupportedClaims),
+    grant_types_supported: Object.values(SupportedGrantTypes),
+    token_endpoint_auth_methods_supported: ['private_key_jwt'],
+    token_endpoint_auth_signing_alg_values_supported: ['ES256'],
+    id_token_signing_alg_values_supported: ['ES256'],
+    id_token_encryption_alg_values_supported: [
+      'ECDH-ES+A256KW',
+      'ECDH-ES+A192KW',
+      'ECDH-ES+A128KW',
+    ],
+    id_token_encryption_enc_values_supported: ['A256CBC-HS512'],
+  }
+}
+
+/**
+ * Helper function to generate a DPoP, client assertion token, and return the ephemeral private key.
+ */
+async function generateDpopAndClientAssertionToken(req) {
+  const { publicKey, privateKey } = generateKeys(req.body.ephemeralPrivateKey)
+  const dpopToken = await generateDpopToken(req, publicKey, privateKey)
+  const clientAssertionToken = await generateClientAssertionToken(req)
+  return {
+    ephemeralPrivateKey: privateKey,
+    dpopToken,
+    clientAssertionToken,
+  }
+}
+function generateKeys(ephemeralPrivateKey) {
+  let publicKey, privateKey
+  if (ephemeralPrivateKey) {
+    //For later part of the FAPI flow, as the ephemeral private key needs to be reused.
+    privateKey = ephemeralPrivateKey
+    if (typeof privateKey === 'string') {
+      privateKey = privateKey.replace(/\\n/g, '\n')
+    }
+    const keyObject = createPrivateKey({
+      key: privateKey,
+      format: 'pem',
+    })
+    publicKey = createPublicKey(keyObject).export({ format: 'jwk' })
+  } else {
+    //Generate a new key if no private key is provided.
+    const keyPair = generateKeyPairSync('ec', {
+      namedCurve: 'P-256',
+      publicKeyEncoding: { format: 'jwk' },
+      privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+    })
+    publicKey = keyPair.publicKey
+    privateKey = keyPair.privateKey
+  }
+  return { publicKey, privateKey }
+}
+async function generateDpopToken(req, publicKey, privateKey) {
+  const dpop = {
+    max_age: dpopConfiguration.MAX_AGE,
+    header: {
+      alg: 'ES256',
+      typ: 'dpop+jwt',
+      jwk: {
+        kty: publicKey.kty,
+        crv: publicKey.crv,
+        x: publicKey.x,
+        y: publicKey.y,
+      },
+    },
+    body: {
+      htu: req.body.endpoint,
+      htm: 'POST',
+      jti: randomUUID(),
+      iat: Math.floor(Date.now() / 1000),
+      exp: Math.floor(Date.now() / 1000) + dpopConfiguration.MAX_AGE,
+      nonce: randomUUID(),
+    },
+  }
+  const dpopKey = createPrivateKey({
+    key: privateKey,
+    format: 'pem',
+    type: 'pkcs8',
+  })
+  return await new jose.SignJWT(dpop.body)
+    .setProtectedHeader(dpop.header)
+    .sign(dpopKey)
+}
+async function generateClientAssertionToken(req) {
+  const clientAssertionPrivateKey = JSON.parse(
+    readFileSync(
+      path.resolve(__dirname, '../../../static/certs/fapi-private.json'),
+    ),
+  )['keys'].find((key) => key.use === 'sig')
+  const clientAssertionPublicKey = JSON.parse(
+    readFileSync(
+      path.resolve(__dirname, '../../../static/certs/fapi-public.json'),
+    ),
+  )['keys'].find((key) => key.use === 'sig')
+  const clientAssertion = {
+    headers: {
+      alg: 'ES256',
+      kid: clientAssertionPublicKey.kid,
+      typ: 'JWT',
+    },
+    payload: {
+      iss: fapiClientConfiguration.client_id,
+      sub: fapiClientConfiguration.client_id,
+      aud: getFapiOpenIdConfiguration(req).issuer,
+      jti: randomUUID(),
+      iat: Math.floor(Date.now() / 1000),
+      exp: Math.floor(Date.now() / 1000) + 120,
+    },
+  }
+
+  const clientKey = await jose.importJWK(clientAssertionPrivateKey, 'ES256')
+  return await new jose.SignJWT(clientAssertion.payload)
+    .setProtectedHeader(clientAssertion.headers)
+    .sign(clientKey)
+}
+
+module.exports = {
+  AllowedAcrValues,
+  AllowedAuthenticationContextTypes,
+  AllowedHttpsRedirectTypes,
+  clientAssertionConfig,
+  dpopConfiguration,
+  FAPI_PATH,
+  fapiClientConfiguration,
+  generateDpopAndClientAssertionToken,
+  getFapiOpenIdConfiguration,
+  idTokenConfiguration,
+  SupportedGrantTypes,
+  SupportedResponseTypes,
+  SupportedScope,
+}

package/lib/express/index.js

@@ -3,4 +3,5 @@ module.exports = {
   configMyInfo: require('./myinfo'),
   configSGID: require('./sgid'),
   configSignV3: require('./signv3'),
+  configFapi: require('./fapi/fapi.controller'),
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengovsg/mockpass",
-  "version": "4.5.8",
+  "version": "4.6.0",
   "description": "A mock SingPass/CorpPass server for dev purposes",
   "main": "app.js",
   "bin": {
@@ -41,6 +41,7 @@
     "dotenv": "^17.2.0",
     "expiry-map": "^2.0.0",
     "express": "^5.1.0",
+    "express-session": "^1.19.0",
     "jose": "^5.2.3",
     "jsonwebtoken": "^9.0.0",
     "lodash": "^4.17.11",

package/static/certs/fapi-private.json

@@ -0,0 +1,23 @@
+{
+  "keys": [
+    {
+      "kty": "EC",
+      "x": "tkRXMLpC7djlH7cqntg8-fuekxG9YTvJx8IsRKApcAg",
+      "y": "elyS0xZn3ymk65tVPYO3pZplEaOEZtj_RegJ3_cwq7A",
+      "crv": "P-256",
+      "d": "uRwK14a2icjic0DSFsOG2PgKgqfZobaqhjgGS0wbkho",
+      "use": "sig",
+      "alg": "ES256"
+    },
+    {
+      "kty": "EC",
+      "x": "fvSpp2PLnde3dtY8VpY881WUxijtSqmhu4daeavEuKQ",
+      "y": "LzH6bK3nxZFPh8tPLjUN0EMYnIgQjkyUiafh4Eafmw8",
+      "crv": "P-256",
+      "d": "wqtEFMSkoWeYqfZ-aqbSn5CE2KmgqWZgxrowWQaHCXA",
+      "use": "enc",
+      "alg": "ECDH-ES+A256KW",
+      "kid": "fapi-enc-key"
+    }
+  ]
+}

package/static/certs/fapi-public.json

@@ -0,0 +1,22 @@
+{
+  "keys": [
+    {
+      "kty": "EC",
+      "crv": "P-256",
+      "x": "tkRXMLpC7djlH7cqntg8-fuekxG9YTvJx8IsRKApcAg",
+      "y": "elyS0xZn3ymk65tVPYO3pZplEaOEZtj_RegJ3_cwq7A",
+      "kid": "fapi-key-01",
+      "use": "sig",
+      "alg": "ES256"
+    },
+    {
+      "kty": "EC",
+      "x": "fvSpp2PLnde3dtY8VpY881WUxijtSqmhu4daeavEuKQ",
+      "y": "LzH6bK3nxZFPh8tPLjUN0EMYnIgQjkyUiafh4Eafmw8",
+      "crv": "P-256",
+      "use": "enc",
+      "alg": "ECDH-ES+A256KW",
+      "kid": "fapi-enc-key"
+    }
+  ]
+}