NDI App Check

API Specs

1) NPM install @govtechsg/ndi-app-check

Import the ndi-app-check npm library

npm install ndi-app-check

2) Initialize the NdiAppCheck class

Import the ndi-app-check library into your codebase. ndi-app-check is am ESModule so it can only be used via import. However, CommonJS can still import the library via dynamic import syntax showned below.

Typescript (ESM)

import { 
    NdiAppCheck, // NdiAppCheck class houses the functions to do app check
    NdiAppCheckParams,  // NdiAppCheck.validateNdiAppCheckHeader function param interface
    Options // NdiAppCheck class constructor init param interface
} from "ndi-app-check"

import path from "path"
import { fileURLToPath } from 'url';

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

// The file path to the Google service account json file
let serviceConfigFilePath = path.join(__dirname, "your-service-config.json")

let options: Options = {
    gcpServiceConfig: serviceConfigFilePath, // the file path string to your Google service account json file
    inProd: true,  // dictates the validation criteria between production and staging environment, allows package name sg.ndi.dev, and also disallow development environment for apple iOS attestation and deviceChecks
    debugMode: false  // // if true, more console logs will be printed to aid debugging
}

// Initialize NdiAppCheck class
let ndiAppCheck = new NdiAppCheck(options)

Javascript (CommonJS)

(async function() { // CommonJs does not allow top level await

    // The file path to the Google service account json file
    let serviceConfigFilePath = path.join(__dirname, "your-service-config.json")
    
    let options = {
        gcpServiceConfig: serviceConfigFilePath, // the file path string to your Google service account json file
        inProd: true,  // dictates the validation criteria between production and staging environment, allows package name sg.ndi.dev, and also disallow development environment for apple iOS attestation and deviceChecks
        debugMode: false  // if true, more console logs will be printed to aid debugging
    }

    let ndiAppCheck;
    await import("@govtechsg/ndi-app-check").then( ({ default: defaultImport }) => {
        // Initialize NdiAppCheck class
        ndiAppCheck = new defaultImport(options)
    } );
}) ();

2) Call the validateNdiAppCheckHeader function in NdiAppCheck class

NdiAppCheck class exposes 2 functions.

Typescript (ESM) validateNdiAppCheckHeader api call

// Determine if this header value requires a public key to validate
let headerNeedsPublicKey = ndiAppCheck.headerNeedsPublicKey(header)

// Fetch the public key from a database or other persistent storage
let pubkey = undefined
if (headerNeedPublicKey) {
    /**
     * fetch public keys from database
     */
    pubkey = <databased fetched publicKey>
}

let appcheck_params: NdiAppCheckParams = {
    header: header, //string - header value
    nonce: nonce, // string - nonce, hash, challenge (session-token, reg_ref, swk_qr_ref etc)
    publicKey: pubKey, // any - publickey only used for Apple key attestation, this value should be obtained from the result of validateNdiAppCheckHeader when a publickey is returned
}

let ndiAppCheckResult = await ndiAppCheck.validateNdiAppCheckHeader(appcheck_params)

Javascript (CommonJS) validateNdiAppCheckHeader api call

// Determine if this header value requires a public key to validate
let headerNeedsPublicKey = ndiAppCheck.headerNeedsPublicKey(header)

// Fetch the public key from a database or other persistent storage
let pubkey = undefined
if (headerNeedPublicKey) {
    /**
     * fetch public keys from database
     */
    pubkey = <databased fetched publicKey>
}

let appcheck_params = {
    header: header, //string - header value
    nonce: nonce, // string - nonce, hash, challenge (session-token, reg_ref, swk_qr_ref etc)
    publicKey: pubKey, // any - publickey only used for Apple key attestation, this value should be obtained from the result of validateNdiAppCheckHeader when a publickey is returned
}

let ndiAppCheckResult = await ndiAppCheck.validateNdiAppCheckHeader(appcheck_params)

Typescript (ESM) validateNdiAppCheckHeader response format

// result returned from ndiAppCheck.validateNdiAppCheckHeader conforms to the below interface
declare interface NdiAppCheckResponse {
    state: Boolean; // state will be true when validation was successful
    reason?: string; // reason will NOT be undefined/null when state == false and validation failed due to security criteria
    error?: string; // error will NOT be undefined/null when state == false and validation failed with an exception/error
    pubicKey?: any; // pubkey will NOT be undefined/null when state === true and validation succeeded with apple iOS attestation header
}

The NdiAppCheck.validateNdiAppCheckHeader function will return a result adhering to the interface NdiAppCheckResponse.

if ndiAppCheckResult contains a publicKey property, it means the validateNdiAppCheckHeader call was made using a Apple iOS key attestation header. This publicKey is to be saved into a database so that when a validateNdiAppCheckHeader call made with Apple iOS app assertion header, the assertion header can be validated successfully using the aforementioned publicKey

Accepted Header formats

Android (Google Play)

Header for Google Play Integrity

X-ndi-appcheck: gpi <token>

Android (Huawei)

Header for Huawei SysIntegrity

X-ndi-appcheck: hwsi <token>

Apple iOS

Header for Apple iOS DeviceCheck

X-ndi-appcheck: adc <token>

Header for Apple iOS App Key Attestation

X-ndi-appcheck: aka <token>

Header for Apple iOS App Assertion

X-ndi-appcheck: aaa <token>