ads specs for routes and services and README

Author: amirbey

README.md

@@ -0,0 +1,87 @@
+# Identity Doc Auth Mock
+
+This project is a mock server for identity document authentication and verification workflows. It simulates endpoints for document verification, MRZ checks, and related flows, and is designed for integration testing and development without requiring real third-party services.
+
+## Features
+
+- **Express.js API** with endpoints for document verification, MRZ, and health checks
+- **Redis integration** for storing and retrieving transaction tokens
+- **Mocked webhook callbacks** for simulating document upload events
+- **Header and payload validation** for all endpoints
+- **Configurable via environment variables**
+
+## Endpoints
+
+### `/api/3.0/EmailAuthScore`  
+- **POST**: Document verification (requires `authorization` and `content-type: application/json` headers)
+
+### `/docv/doc_request`  
+- **POST**: Initiate a document verification request
+
+### `/dos/mrz`  
+- **POST**: MRZ check (requires `client-id`, `x-correlation-id`, `client-secret`, and `content-type: application/json` headers)
+
+### `/dos/healthcheck`  
+- **GET**: Health check endpoint
+
+## Setup
+
+1. **Install dependencies**
+   ```sh
+   yarn install
+   # or
+   npm install
+   ```
+
+2. **Configure environment variables**  
+   Create a `.env` file in the project root:
+   ```
+   PORT=3002
+   API_KEY=your-api-key
+   DEFAULT_IDP_DOCV_CALLBACK_URL=https://example.com/callback
+   IDP_WEBHOOK_PATH=/webhook
+   WEBHOOK_SECRET=your-webhook-secret
+   REDIS_URL=redis://localhost:6379
+   ```
+
+3. **Start the server**
+   ```sh
+   yarn start
+   # or
+   npm start
+   ```
+
+## Testing
+
+- **Run all tests**
+  ```sh
+  yarn test
+  # or
+  npm test
+  ```
+
+- **Lint the code**
+  ```sh
+  yarn lint
+  # or
+  npm run lint
+  ```
+
+## Development
+
+- Endpoints and logic are organized under the `routes/` and `services/` directories.
+- Mock data for document verification is in `data/docv/results.js`.
+- Tests are in the `test/` directory and use Mocha, Chai, and Sinon.
+
+## Public domain
+
+This project is in the public domain within the United States, and
+copyright and related rights in the work worldwide are waived through
+the [CC0 1.0 Universal public domain dedication](https://creativecommons.org/publicdomain/zero/1.0/).
+
+All contributions to this project will be released under the CC0
+dedication. By submitting a pull request, you are agreeing to comply
+with this waiver of copyright interest.
+
+---
+**Note:** This project is for development and testing purposes only. Do not use in production environments.

eslint.config.mjs

@@ -0,0 +1,8 @@
+import js from "@eslint/js";
+import globals from "globals";
+import { defineConfig } from "eslint/config";
+
+export default defineConfig([
+  { files: ["**/*.{js,mjs,cjs}"], plugins: { js }, extends: ["js/recommended"], languageOptions: { globals: globals.browser } },
+  { files: ["**/*.js"], languageOptions: { sourceType: "commonjs" } },
+]);

package.json

@@ -6,7 +6,7 @@
   "scripts": {
     "start": "node server.js",
     "dev": "nodemon server.js",
-    "test": "NODE_ENV=test mocha"
+    "test": "NODE_ENV=test mocha **/*.test.js --exit"
   },
   "dependencies": {
     "axios": "^1.9.0",
@@ -16,10 +16,14 @@
     "redis": "^5.5.6"
   },
   "devDependencies": {
+    "@eslint/js": "^9.32.0",
     "chai": "^5.2.1",
+    "eslint": "^9.32.0",
+    "globals": "^16.3.0",
     "mocha": "^11.7.1",
     "nodemon": "^3.0.0",
     "proxyquire": "^2.1.3",
+    "sinon": "^21.0.0",
     "supertest": "^7.1.4"
   },
   "private": true,

routes/id_plus.js

@@ -14,9 +14,9 @@ router.post('/', (req, res) => {
 
   const { modules } = req.body;
 
-  if (!Array.isArray(modules) &&
-    modules.length !== 1 &&
-    modules[0] !== "documentverification"
+  if (!Array.isArray(modules) ||
+    modules.length !== 1 ||
+    modules[0] !== "documentVerification"
   ) {
     return res.status(400).json({ error: 'Invalid modules' });
   }

test/routes/docv.test.js

@@ -0,0 +1,107 @@
+const express = require('express');
+const request = require('supertest');
+const sinon = require('sinon');
+const proxyquire = require('proxyquire').noCallThru();
+const { expect } = require('chai');
+
+describe('POST /docv/doc_request', function () {
+  let app, redisStub, axiosStub, authorizedStub;
+
+  beforeEach(async function () {
+    // Stub Redis client
+    redisStub = {
+      connect: sinon.stub().resolves(),
+      setEx: sinon.stub().resolves()
+    };
+
+    // Stub axios
+    axiosStub = { post: sinon.stub().resolves() };
+
+    // Stub authorized
+    authorizedStub = sinon.stub();
+
+    // Proxyquire the route with stubs
+    const docvRoute = proxyquire('../../routes/docv', {
+      axios: axiosStub,
+      crypto: require('crypto'),
+      redis: { createClient: () => redisStub },
+      '../services/id_plus': { authorized: authorizedStub }
+    });
+
+    // Set up express app
+    app = express();
+    app.use(express.json());
+    app.use('/docv', docvRoute);
+
+    // Set required env vars
+    process.env.DEFAULT_IDP_DOCV_CALLBACK_URL = 'https://example.com/callback';
+    process.env.IDP_WEBHOOK_PATH = '/webhook';
+    process.env.WEBHOOK_SECRET = 'secret';
+  });
+
+  it('should reject missing or invalid headers', async function () {
+    const res = await request(app)
+      .post('/docv/doc_request')
+      .send({});
+    expect(res.status).to.equal(400);
+    expect(res.body).to.have.property('error', 'Missing or invalid headers');
+  });
+
+  it('should reject unauthorized requests', async function () {
+    authorizedStub.returns(false);
+    const res = await request(app)
+      .post('/docv/doc_request')
+      .set('authorization', 'Bearer token')
+      .set('content-type', 'application/json')
+      .send({});
+    expect(res.status).to.equal(401);
+    expect(res.body).to.have.property('error', 'Unauthorized');
+  });
+
+  it('should reject invalid documentType', async function () {
+    authorizedStub.returns(true);
+    const res = await request(app)
+      .post('/docv/doc_request')
+      .set('authorization', 'Bearer token')
+      .set('content-type', 'application/json')
+      .send({ config: { documentType: 'foo', redirect: {} } });
+    expect(res.status).to.equal(400);
+    expect(res.body).to.have.property('error', 'Invalid or missing documentType');
+  });
+
+  it('should reject invalid redirect method', async function () {
+    authorizedStub.returns(true);
+    const res = await request(app)
+      .post('/docv/doc_request')
+      .set('authorization', 'Bearer token')
+      .set('content-type', 'application/json')
+      .send({ config: { documentType: 'license', redirect: { method: 'PUT', url: 'https://example.com/callback' } } });
+    expect(res.status).to.equal(400);
+    expect(res.body).to.have.property('error', 'Invalid or missing redirect method');
+  });
+
+  it('should reject invalid redirect url', async function () {
+    authorizedStub.returns(true);
+    const res = await request(app)
+      .post('/docv/doc_request')
+      .set('authorization', 'Bearer token')
+      .set('content-type', 'application/json')
+      .send({ config: { documentType: 'license', redirect: { method: 'GET', url: 'not-a-url' } } });
+    expect(res.status).to.equal(400);
+    expect(res.body).to.have.property('error', 'Invalid redirect url');
+  });
+
+  it('should accept valid request and store in redis', async function () {
+    authorizedStub.returns(true);
+    const res = await request(app)
+      .post('/docv/doc_request')
+      .set('authorization', 'Bearer token')
+      .set('content-type', 'application/json')
+      .send({ config: { documentType: 'passport', redirect: { method: 'POST', url: 'https://example.com/callback' } } });
+    expect(res.status).to.equal(200);
+    expect(res.body.data).to.have.property('url', 'https://example.com/callback');
+    expect(res.body.data).to.have.property('docvTransactionToken');
+    expect(redisStub.setEx.calledOnce).to.be.true;
+    expect(axiosStub.post.calledOnce).to.be.true;
+  });
+});

test/routes/dos.test.js

@@ -0,0 +1,70 @@
+const express = require('express');
+const request = require('supertest');
+const { expect } = require('chai');
+
+const dosRoute = require('../../routes/dos');
+
+describe('DOS Route', function () {
+  let app;
+
+  before(function () {
+    app = express();
+    app.use(express.json());
+    app.use('/dos', dosRoute);
+  });
+
+  describe('GET /dos/healthcheck', function () {
+    it('should return status UP', async function () {
+      const res = await request(app).get('/dos/healthcheck');
+      expect(res.status).to.equal(200);
+      expect(res.body).to.deep.equal({ status: 'UP' });
+    });
+  });
+
+  describe('POST /dos/mrz', function () {
+    const validHeaders = {
+      'client-id': 'test-client',
+      'x-correlation-id': 'corr-id',
+      'client-secret': 'secret',
+      'content-type': 'application/json'
+    };
+
+    it('should return 400 for missing headers', async function () {
+      const res = await request(app)
+        .post('/dos/mrz')
+        .send({});
+      expect(res.status).to.equal(400);
+      expect(res.body).to.have.property('error', 'Missing or invalid headers');
+    });
+
+    it('should return 200 and response YES for valid headers', async function () {
+      const res = await request(app)
+        .post('/dos/mrz')
+        .set(validHeaders)
+        .send({});
+      expect(res.status).to.equal(200);
+      expect(res.body).to.deep.equal({ response: 'YES' });
+    });
+
+    it('should return 400 if content-type is not application/json', async function () {
+      const headers = { ...validHeaders, 'content-type': 'text/plain' };
+      const res = await request(app)
+        .post('/dos/mrz')
+        .set(headers)
+        .send('');
+      expect(res.status).to.equal(400);
+      expect(res.body).to.have.property('error', 'Missing or invalid headers');
+    });
+
+    it('should return 400 if any required header is missing', async function () {
+      const headers = { ...validHeaders };
+      delete headers['client-secret'];
+      const res = await request(app)
+        .post('/dos/mrz')
+        .set(headers)
+        .send({});
+      expect(res.status).to.equal(400);
+      expect(res.body).to.have.property('error', 'Missing or invalid headers');
+    });
+  });
+});

test/routes/id_plus.test.js

@@ -0,0 +1,65 @@
+const express = require('express');
+const request = require('supertest');
+const sinon = require('sinon');
+const { expect } = require('chai');
+const proxyquire = require('proxyquire').noCallThru();
+
+describe('id_plus Route', function () {
+  let app, documentVerificationStub;
+
+  beforeEach(function () {
+    documentVerificationStub = sinon.stub().callsFake((req, res) => {
+      res.status(200).json({ ok: true });
+    });
+
+    const idPlusRoute = proxyquire('../../routes/id_plus', {
+      '../services/id_plus': {
+        authorized: () => true,
+        documentVerification: documentVerificationStub
+      }
+    });
+
+    app = express();
+    app.use(express.json());
+    app.use('/api/3.0/EmailAuthScore', idPlusRoute);
+  });
+
+  it('should return 400 for missing headers', async function () {
+    const res = await request(app)
+      .post('/api/3.0/EmailAuthScore')
+      .send({});
+    expect(res.status).to.equal(400);
+    expect(res.body).to.have.property('error', 'Missing or invalid headers');
+  });
+
+  it('should return 400 for invalid content-type', async function () {
+    const res = await request(app)
+      .post('/api/3.0/EmailAuthScore')
+      .set('authorization', 'Bearer token')
+      .set('content-type', 'text/plain')
+      .send('');
+    expect(res.status).to.equal(400);
+    expect(res.body).to.have.property('error', 'Missing or invalid headers');
+  });
+
+  it('should return 400 for invalid modules', async function () {
+    const res = await request(app)
+      .post('/api/3.0/EmailAuthScore')
+      .set('authorization', 'Bearer token')
+      .set('content-type', 'application/json')
+      .send({ modules: [] });
+    expect(res.status).to.equal(400);
+    expect(res.body).to.have.property('error', 'Invalid modules');
+  });
+
+  it('should call documentVerification for valid request', async function () {
+    const res = await request(app)
+      .post('/api/3.0/EmailAuthScore')
+      .set('authorization', 'Bearer token')
+      .set('content-type', 'application/json')
+      .send({ modules: ['documentVerification'] });
+    expect(res.status).to.equal(200);
+    expect(res.body).to.deep.equal({ ok: true });
+    expect(documentVerificationStub.calledOnce).to.be.true;
+  });
+});