IO dev API server

Mock server of io-backend for io-app development.

Table of contents

• Features
• Local setup
• Docker setup
• Usage with the app

Features

The test server has been created to make the app development process easier and more productive. Therefore you can:

• Run it on local machines without an internet connection;
• Change response payloads to test and stress the app;
• Add new paths and handlers to integrate and test features not yet released;
• Understand flows and data exchanged between app and backend.

Login

The current login implementation by-passes SPID authentication: when the user asks for a login with a certain SPID Identity Provider, the server responses with a redirect containing the session token. The user will be immediately logged in.

Session

When the client asks for a session, a valid session is always returned. Of course the developer could implement a logic to return an expired session response to test different scenarios.

Local setup

We recommend the use of a virtual environment, nodenv is the chosen virtual environment for this guide, along with yarn for managing depencendices. From your command line, run:

# Clone this repository
$ git clone https://github.com/pagopa/io-dev-api-server

# CD into the repository
$ cd io-dev-api-server

# Install node with nodenv, the returned version should match the one in the .node-version file
$ nodenv install && nodenv version

# Install yarn and rehash to install shims
$ npm install -g yarn && nodenv rehash

# Install dependencies 
# Run this only while setting up and when dependencies change
$ yarn install

# Generate API definitions
# Run this only while setting up and when io-backend specs change
$ yarn generate

# Start the server
$ yarn start

Note: The default port (3000) can be changed in the server.ts file.

Docker setup

A Docker image is also available for local dev purposes. From your command line, run:

# Login into the github packages registry
# Reference: https://help.github.com/en/packages/using-github-packages-with-your-projects-ecosystem/configuring-npm-for-use-with-github-packages
$ docker login -u <YOUR_GITHUB_USERNAME> -p <GITHUB_TOKEN> docker.pkg.github.com

# Pull the latest Docker image 
# Other versions can be found here: https://github.com/pagopa/io-dev-api-server/pkgs/container/io-dev-api-server%2Fio-dev-api-server
$ docker pull ghcr.io/pagopa/io-dev-api-server/io-dev-api-server:latest

# Run the Docker container at http://127.0.0.1:<YOUR_HOST_PORT>/
$ docker run -d -p <YOUR_HOST_PORT>:3000 docker.pkg.github.com/pagopa/io-dev-api-server/io-dev-api-server:latest`

Usage with the app

Run the server, either locally on via Docker. Then, from your command line:

# CD into the app folder
$ cd io-app

# Use the local env 
# You can edit the server endpoint on your needs
$ cp .env.local .env 

# Run the app on iOS or Android
$ yarn run-ios (or yarn-run-android)

Lollipop

Server is able to verify lollipop header's signatures on incoming requests, provided a previously valid login that set both public key and public assertion (GET /login endpoint).

In order to enable lollipop on an endpoint, just wrap the middleware function that handles such endpoint with the lollipopMiddleware function (src/middleware/lollipopMiddleware.ts).

// Handler without lollipop
addHandler(
  messageRouter,
  "get",
  addApiV1Prefix("/third-party-messages/:id/precondition"),
  (req, res) => {...}
)

// Handler with lollipop
addHandler(
  messageRouter,
  "get",
  addApiV1Prefix("/third-party-messages/:id/precondition"),
  lollipopMiddleware((req, res) => {...})
)

The lollipop middleware runs before the wrapped function and automatically rejects-and-block any request that is not lollipop compliant (so the wrapped function is not executed in such case). Public key and Assertion Ref can be retrieved using getPublicKey and getAssertionRef (src/persistence/lollipop.ts - provided a previously valid login on the GET /login endpoint).

Regardless of how many endpoints have been wrapped, the lollipop middleware can be globally disabled using the config.feature.lollipop.enabled flag (default true).

FastLogin

Server is able to perform a FastLogin. A FastLogin is a type of login that provides a very short session which is automatically renewed by calling the fastlogin endpoint.

To enable this feature, you must set the FeatureFlag to a minimum version higher than 0.0.0 in src/payloads/backend.ts

fastLogin: {
      min_app_version: {
        ios: "1.0.0",
        android: "1.0.0"
      }
    }

If you want, you can specify a different minimum supported version for ios and android.

To enable Fast Login Opt-In screen, you must set its feature flag to a minimum version higher than 0.0.0 as shown below:

fastLogin: {
  min_app_version: {        
    ios: "1.0.0",
    android: "1.0.0"
  },
  opt_in: {
    min_app_version: {          
      ios: "1.0.0",
      android: "1.0.0"
    }
  }

It will be possible to renew the session via the fastlogin endpoint until the expiration date of the assertionRef.

You can configure the duration of the session by associating a value in MS to sessionTTLinMS in the config.ts file > features/fastlogin.

In the same file it is possible to configure the duration of the assertionRef, giving a value in MS to the key lollipop/assertionRefValidityMS. If no value is specified for this key, assertionRef gets infinite validity.

Email Validation

Server is able to validate/invalidate an email address with the below endpoints:

POST /validate-profile-email with body { value: boolean }

Email Already Taken

Server is able to set/reset if an email address is already taken with the below endpoints:

POST /set-email-already-taken with body { value: boolean }

Uniqueness of email validation flow test

In order to test the uniqueness of email validation flow, the config/config.json file must use configurations (of course you can edit them as you need):

{
  "profile": {
    "attrs": {
      "name": "Gian Maria",
      "is_email_validated": false,
      "is_email_already_taken": false, 
      "fiscal_code": "AAAAAA00A00A000M"
    }
  }
}

and to validate/invalidate the email or make the email already taken you have to navigate from the browser to http://localhost:3000/

Cie ID

To enable this feature, you must set the FeatureFlag to a minimum version higher than 0.0.0 in src/payloads/backend.ts

cie_id: {
  min_app_version: {
    ios: "1.0.0",
    android: "1.0.0"
  }
}